refactor(runtime): share HMGET projection zipping via HashProjections

Extract the private mapHashFields helper from RedisReservationRepository
into a shared data.util.HashProjections, and switch the expiry event
hydration from positional HMGET reads (fields.get(0)..get(6)) to
name-keyed reads over a declared EXPIRED_EVENT_FIELDS projection.

Reordering or inserting a projected field can no longer silently shift
every later column in the expired-event payload. No wire or behavior
change: the HMGET commands issued are byte-identical.

Review follow-up (PR #237 round 2, minor carryover). Unit tests added
for the shared helper; full mvn verify green with the 95% JaCoCo gate.

Author: amavashev

AUDIT.md

@@ -52,7 +52,10 @@ every `HGETALL`. Mutation scripts also omit snapshot JSON when invoked without
 an idempotency key. The response-state marker remains available for the
 evidence finalization state machine, so this optimization does not weaken its
 race guarantees. Detail uses a static projection and both list paths construct
-their projection array once per request rather than once per Redis key.
+their projection array once per request rather than once per Redis key. All
+`HMGET` replies are zipped to field names by one shared `HashProjections`
+helper; the expiry event path now reads fields by name rather than positional
+index, so reordering a projection cannot silently shift columns.
 
 **Clear replay compatibility and metrics.** The Lua commit/release replay
 branches now do only payload-hash validation and return the immutable snapshot

CHANGELOG.md

@@ -55,8 +55,9 @@ called out but are not breaking to API clients.
   now use explicit `HMGET` projections. Immutable response snapshots and other
   unrelated hash fields are no longer transferred and parsed on every read.
   Projection arrays are built once per operation rather than once per hydrated
-  reservation. Lua also omits snapshot JSON when invoked without an
-  idempotency key.
+  reservation, and all projection replies are zipped to field names by a shared
+  `HashProjections` helper (name-keyed reads, no positional indexing). Lua also
+  omits snapshot JSON when invoked without an idempotency key.
 
 ### Compatibility
 

cycles-protocol-service/cycles-protocol-service-data/src/main/java/io/runcycles/protocol/data/repository/RedisReservationRepository.java

@@ -9,6 +9,7 @@
 import io.runcycles.protocol.data.service.EvidenceEmitter;
 import io.runcycles.protocol.data.service.LuaScriptRegistry;
 import io.runcycles.protocol.data.service.ScopeDerivationService;
+import io.runcycles.protocol.data.util.HashProjections;
 import io.runcycles.protocol.data.util.LogSanitizer;
 import io.runcycles.protocol.model.*;
 import io.runcycles.protocol.model.audit.AuditLogEntry;
@@ -1507,7 +1508,7 @@ public ReservationExtendResponse extendReservation(String reservationId, Reserva
     public ReservationDetail getReservationById(String reservationId) {
         try (Jedis jedis = jedisPool.getResource()) {
             String key = "reservation:res_" + reservationId;
-            Map<String, String> fields = mapHashFields(
+            Map<String, String> fields = HashProjections.mapHashFields(
                 RESERVATION_DETAIL_FIELDS, jedis.hmget(key, RESERVATION_DETAIL_FIELD_ARRAY));
             if (fields == null || fields.isEmpty()) {
                 throw CyclesProtocolException.notFound(reservationId);
@@ -1624,7 +1625,7 @@ public ReservationListResponse listReservations(String tenant, String idempotenc
                     for (int i = startIndex; i < keys.size(); i++) {
                         String key = keys.get(i);
                         try {
-                            Map<String, String> fields = mapHashFields(projection, responses.get(key).get());
+                            Map<String, String> fields = HashProjections.mapHashFields(projection, responses.get(key).get());
                             if (fields.isEmpty()) continue;
                             if (!tenant.equals(fields.get("tenant"))) continue;
                             if (status != null && !status.equals(fields.get("state"))) continue;
@@ -1735,7 +1736,7 @@ private ReservationListResponse listReservationsSorted(
 
                     for (String key : keys) {
                         try {
-                            Map<String, String> fields = mapHashFields(projection, responses.get(key).get());
+                            Map<String, String> fields = HashProjections.mapHashFields(projection, responses.get(key).get());
                             if (fields.isEmpty()) continue;
                             ReservationSummary summary = matchingReservation(fields, tenant,
                                     idempotencyKey, status, workspaceSegment, appSegment,
@@ -2468,21 +2469,6 @@ private static List<String> reservationProjection(Set<ReservationInclude> includ
         return fields;
     }
 
-    private static Map<String, String> mapHashFields(List<String> names,
-                                                     List<String> values) {
-        if (values == null) {
-            return Collections.emptyMap();
-        }
-        Map<String, String> fields = new HashMap<>();
-        for (int i = 0; i < names.size() && i < values.size(); i++) {
-            String value = values.get(i);
-            if (value != null) {
-                fields.put(names.get(i), value);
-            }
-        }
-        return fields;
-    }
-
     private ReservationDetail buildReservationSummary(Map<String, String> fields) throws Exception {
         String estimateUnitStr = fields.get("estimate_unit");
         String estimateAmountStr = fields.get("estimate_amount");

cycles-protocol-service/cycles-protocol-service-data/src/main/java/io/runcycles/protocol/data/service/ReservationExpiryService.java

@@ -3,6 +3,7 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.runcycles.protocol.data.metrics.CyclesMetrics;
+import io.runcycles.protocol.data.util.HashProjections;
 import io.runcycles.protocol.data.util.LogSanitizer;
 import io.runcycles.protocol.data.util.TraceContext;
 import io.runcycles.protocol.data.util.TraceIdGenerator;
@@ -18,6 +19,7 @@
 
 import java.time.Instant;
 import java.util.List;
+import java.util.Map;
 
 /**
  * Cycles Protocol v0.1.25 - Background job that marks expired reservations.
@@ -42,6 +44,11 @@ public class ReservationExpiryService {
     /** Max candidates per sweep to avoid OOM after prolonged outages. */
     private static final int SWEEP_BATCH_SIZE = 1000;
 
+    /** HMGET projection for the reservation.expired event payload. */
+    private static final List<String> EXPIRED_EVENT_FIELDS = List.of(
+        "tenant", "scope_path", "estimate_unit", "estimate_amount",
+        "created_at", "expires_at", "extension_count");
+
     @Scheduled(fixedDelayString = "${cycles.expiry.interval-ms:5000}",
                initialDelayString = "${cycles.expiry.initial-delay-ms:5000}")
     public void expireReservations() {
@@ -110,24 +117,24 @@ private void emitExpiredEvent(Jedis jedis, String reservationId, JsonNode luaRes
             // previously wrong (missing prefix) — dormant because HMGET on a non-existent key
             // returns null fields rather than throwing, so the method just silently no-op'd.
             // Surfaced by the new cycles.reservations.expired counter test in v0.1.25.10.
-            List<String> fields = jedis.hmget("reservation:res_" + reservationId,
-                "tenant", "scope_path", "estimate_unit", "estimate_amount",
-                "created_at", "expires_at", "extension_count");
-            if (fields == null || fields.isEmpty()) return;
+            Map<String, String> fields = HashProjections.mapHashFields(EXPIRED_EVENT_FIELDS,
+                jedis.hmget("reservation:res_" + reservationId,
+                    EXPIRED_EVENT_FIELDS.toArray(String[]::new)));
+            if (fields.isEmpty()) return;
 
-            tenantId = fields.get(0);
+            tenantId = fields.get("tenant");
             if (tenantId == null) return;
 
             // Counter is bumped once per actual EXPIRED transition (SKIP results from
             // still-in-grace or already-finalised reservations are filtered out above).
             metrics.recordExpired(tenantId);
 
-            scopePath = fields.get(1);
-            String unit = fields.get(2);
-            Long estimateAmount = parseLong(fields.get(3));
-            Long createdAtMs = parseLong(fields.get(4));
-            Long expiresAtMs = parseLong(fields.get(5));
-            Integer extensionCount = parseInt(fields.get(6));
+            scopePath = fields.get("scope_path");
+            String unit = fields.get("estimate_unit");
+            Long estimateAmount = parseLong(fields.get("estimate_amount"));
+            Long createdAtMs = parseLong(fields.get("created_at"));
+            Long expiresAtMs = parseLong(fields.get("expires_at"));
+            Integer extensionCount = parseInt(fields.get("extension_count"));
             Integer ttlMs = (createdAtMs != null && expiresAtMs != null)
                     ? (int) (expiresAtMs - createdAtMs) : null;
 

cycles-protocol-service/cycles-protocol-service-data/src/main/java/io/runcycles/protocol/data/util/HashProjections.java

@@ -0,0 +1,44 @@
+package io.runcycles.protocol.data.util;
+
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Zips an {@code HMGET} projection (the requested field names) with its
+ * positional Redis reply into a name-keyed map, so consumers read
+ * {@code fields.get("tenant")} instead of {@code values.get(0)} — inserting or
+ * reordering a projected field can no longer silently shift every later
+ * column. Shared by the reservation repository's detail/list projections and
+ * the expiry event hydration.
+ *
+ * <p>{@code HMGET} returns one entry per requested name with {@code null} for
+ * absent fields; nulls are dropped, so a missing key (all-null reply) yields
+ * an empty map, which callers already treat as "hash not found".
+ */
+public final class HashProjections {
+
+    private HashProjections() {
+    }
+
+    /**
+     * @param names  the field names passed to {@code HMGET}, in call order
+     * @param values the positional {@code HMGET} reply ({@code null} tolerated)
+     * @return name→value for every non-null reply entry; empty when
+     *         {@code values} is null or every value is null
+     */
+    public static Map<String, String> mapHashFields(List<String> names, List<String> values) {
+        if (values == null) {
+            return Collections.emptyMap();
+        }
+        Map<String, String> fields = new HashMap<>();
+        for (int i = 0; i < names.size() && i < values.size(); i++) {
+            String value = values.get(i);
+            if (value != null) {
+                fields.put(names.get(i), value);
+            }
+        }
+        return fields;
+    }
+}

cycles-protocol-service/cycles-protocol-service-data/src/test/java/io/runcycles/protocol/data/util/HashProjectionsTest.java

@@ -0,0 +1,51 @@
+package io.runcycles.protocol.data.util;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.util.Arrays;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DisplayName("HashProjections")
+class HashProjectionsTest {
+
+    private static final List<String> NAMES = List.of("tenant", "state", "estimate_amount");
+
+    @Test
+    void zipsNamesToValuesInCallOrder() {
+        assertThat(HashProjections.mapHashFields(NAMES, List.of("acme", "ACTIVE", "5000")))
+            .containsOnly(
+                java.util.Map.entry("tenant", "acme"),
+                java.util.Map.entry("state", "ACTIVE"),
+                java.util.Map.entry("estimate_amount", "5000"));
+    }
+
+    @Test
+    @DisplayName("null HMGET values (absent hash fields) are dropped, not stored as nulls")
+    void dropsNullValues() {
+        assertThat(HashProjections.mapHashFields(NAMES, Arrays.asList("acme", null, null)))
+            .containsOnly(java.util.Map.entry("tenant", "acme"));
+    }
+
+    @Test
+    @DisplayName("missing key (all-null reply) yields an empty map — callers treat as not-found")
+    void allNullReplyYieldsEmptyMap() {
+        assertThat(HashProjections.mapHashFields(NAMES, Arrays.asList(null, null, null))).isEmpty();
+    }
+
+    @Test
+    void nullReplyYieldsEmptyMap() {
+        assertThat(HashProjections.mapHashFields(NAMES, null)).isEmpty();
+    }
+
+    @Test
+    @DisplayName("length mismatch is bounded by the shorter list (defensive against driver quirks)")
+    void lengthMismatchIsBounded() {
+        assertThat(HashProjections.mapHashFields(NAMES, List.of("acme")))
+            .containsOnly(java.util.Map.entry("tenant", "acme"));
+        assertThat(HashProjections.mapHashFields(List.of("tenant"), List.of("acme", "extra")))
+            .containsOnly(java.util.Map.entry("tenant", "acme"));
+    }
+}