feat(reservation): persist + project evidence refs (include=evidence, v0.1.25.37)

Implements cycles-protocol v0.1.25.9 (#117). Lets a consumer link a reservation
to its signed CyclesEvidence envelope(s) without having captured the evidence_id
off the original reserve/commit/release response.

- persistEvidenceRef: fail-open follow-up HSET of <artifact>_evidence_id +
  _evidence_url onto the reservation hash right after the ref is stamped on the
  reserve/commit/release response (HSET preserves the Lua 30-day terminal TTL).
- buildReservationSummary hydrates a new ReservationEvidence map (reserve /
  commit / release -> CyclesEvidenceRef); toSummary gates it on a new
  ReservationInclude.EVIDENCE token (?include=evidence), projection-only (not
  folded into FilterHasher). getReservation always carries it.
- Degrades gracefully: null when evidence emission is disabled or for
  pre-feature reservations; half-written ref (id without url) ignored.

Tests: ReservationEvidenceTest, ReservationIncludeTest +2,
RedisReservationEvidenceLinkTest +6. Full mvn verify green across model/data/api,
JaCoCo 95% gate met; contract + spec-coverage pass against #117 on main.
Additive/non-breaking. AUDIT.md updated.

Author: amavashev

AUDIT.md

@@ -5,6 +5,14 @@
 
 ---
 
+### 2026-06-22 — v0.1.25.37: link reservations to their evidence via `include=evidence`
+
+Implements cycles-protocol v0.1.25.9 (runcycles/cycles-protocol#117). The `cycles_evidence` ref previously rode only on the live reserve/commit/release response, so a reservation fetched later (e.g. by the admin dashboard) had no path back to its signed envelope — you had to have captured the `evidence_id` at the moment of the call. Now the server persists each computed ref onto the reservation and surfaces it via a new `evidence` projection.
+
+`EvidenceEmitter.emit` already computes the `evidence_id` synchronously (when the server identity is configured), but only after the reserve/commit/release Lua runs — so the id can't be passed into the script. Instead `persistEvidenceRef` does a fail-open follow-up `HSET` of `<artifact>_evidence_id` + `<artifact>_evidence_url` onto the `reservation:res_*` hash right after the ref is stamped on the response (HSET preserves the terminal 30-day TTL set by Lua; a write failure logs and never fails the op). Both id and url are stored so hydration needs no server-id reconstruction. `buildReservationSummary` hydrates them into a new `ReservationEvidence` map (keyed `reserve`/`commit`/`release`, each a `CyclesEvidenceRef`); `toSummary` gates it on a new `ReservationInclude.EVIDENCE` token (`?include=evidence`) for symmetry with the metadata projections — projection-only, NOT folded into `FilterHasher`, so it never invalidates a cursor. The single-row `getReservation` always carries it. A reservation has at most a `reserve` entry plus one terminal (`commit` XOR `release`); a half-written ref (id without url) is ignored. Degrades gracefully: `null` when evidence emission is disabled or for pre-feature reservations (`NON_NULL` strips it).
+
+New `ReservationEvidence` model + `ReservationInclude.EVIDENCE`. `ReservationEvidenceTest` (isEmpty + per-artifact refs), `ReservationIncludeTest` +2 (evidence token, all-three parse), `RedisReservationEvidenceLinkTest` +6 (hydrate reserve+commit, absent → null, half-written ignored, persist HSETs id+url, null-ref/null-id no-op, projection gated on include). Full `mvn verify` green across model/data/api, JaCoCo 95% gate met; contract + spec-coverage tests pass against cycles-protocol#117 (merged to main). Additive/non-breaking — clients that don't request `include=evidence` see byte-identical responses.
+
 ### 2026-06-19 — v0.1.25.36: surface `committed` + opt-in metadata on `listReservations`
 
 Follow-up to v0.1.25.34/#197: the same fields surfaced on the single-row `getReservation` were dropped from the `GET /v1/reservations` list rows (runcycles/cycles-server#201). The list path already hydrated a full `ReservationDetail` per row (`buildReservationSummary`), but `toSummary` down-converted to `ReservationSummary` and discarded `committed`, `metadata`, and `committed_metadata` — so the data was read then thrown away.

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

@@ -355,6 +355,9 @@ private void stampAndEmitEvidence(ReservationCreateResponse response,
                     .evidenceId(ref.evidenceId())
                     .cyclesEvidenceUrl(ref.cyclesEvidenceUrl())
                     .build());
+            // Record the ref on the reservation so it is linkable later via
+            // include=evidence. Null reservation_id (dry_run) is a no-op.
+            persistEvidenceRef(response.getReservationId(), "reserve", ref);
         }
     }
 
@@ -413,6 +416,60 @@ private EvidenceEmitter.EvidenceRef emitLifecycleEvidence(String artifactType, S
         return evidenceEmitter.emit(artifactType, System.currentTimeMillis(), traceId, payloadBody);
     }
 
+    /**
+     * Persist the just-computed evidence ref for an artifact onto the reservation
+     * hash ({@code <artifact>_evidence_id} / {@code <artifact>_evidence_url}), so
+     * {@code listReservations} / {@code getReservation} can surface it via
+     * {@code include=evidence} — letting a consumer link a reservation to its
+     * signed envelope(s) without having captured the id off the original
+     * response. Both id and url are stored so hydration needs no server-id
+     * reconstruction. No-op when the ref is null (evidence emission disabled) or
+     * for dry-run (no reservation_id). Fail-open: a write failure is logged,
+     * never thrown — it only degrades the evidence projection, never the op.
+     */
+    private void persistEvidenceRef(String reservationId, String artifactType,
+                                    EvidenceEmitter.EvidenceRef ref) {
+        if (ref == null || reservationId == null || reservationId.isEmpty()) {
+            return;
+        }
+        try (Jedis jedis = jedisPool.getResource()) {
+            Map<String, String> f = new LinkedHashMap<>();
+            f.put(artifactType + "_evidence_id", ref.evidenceId());
+            f.put(artifactType + "_evidence_url", ref.cyclesEvidenceUrl());
+            jedis.hset("reservation:res_" + reservationId, f);
+        } catch (Exception e) {
+            LOG.warn("Failed to persist {} evidence for reservation {}: {}",
+                    artifactType, reservationId, e.getMessage());
+        }
+    }
+
+    /**
+     * Hydrate the {@code evidence} projection from the persisted
+     * {@code <artifact>_evidence_id} / {@code _url} hash fields. Returns null
+     * when no artifact has recorded evidence (NON_NULL then strips the field).
+     */
+    private ReservationEvidence buildEvidence(Map<String, String> fields) {
+        ReservationEvidence.ReservationEvidenceBuilder b = ReservationEvidence.builder();
+        boolean any = false;
+        for (String artifact : new String[] {"reserve", "commit", "release"}) {
+            String id = fields.get(artifact + "_evidence_id");
+            String url = fields.get(artifact + "_evidence_url");
+            if (id == null || id.isEmpty() || url == null || url.isEmpty()) {
+                continue;
+            }
+            CyclesEvidenceRef ref = CyclesEvidenceRef.builder()
+                    .evidenceId(id).cyclesEvidenceUrl(url).build();
+            switch (artifact) {
+                case "reserve" -> b.reserve(ref);
+                case "commit" -> b.commit(ref);
+                case "release" -> b.release(ref);
+                default -> { /* unreachable */ }
+            }
+            any = true;
+        }
+        return any ? b.build() : null;
+    }
+
     /** Cache a finalized lifecycle response body (with evidence stamped) for verbatim replay,
      *  keyed by {@code <artifact>:body:<reservation_id>}, 30-day TTL matching the terminal
      *  reservation hash. Fail-open. */
@@ -872,6 +929,7 @@ public CommitResponse commitReservation(String reservationId, CommitRequest requ
                         .evidenceId(ref.evidenceId())
                         .cyclesEvidenceUrl(ref.cyclesEvidenceUrl())
                         .build());
+                persistEvidenceRef(reservationId, "commit", ref);
             }
             cacheLifecycleBody("commit", reservationId, committed);
             return committed;
@@ -970,6 +1028,7 @@ public ReleaseResponse releaseReservation(String reservationId, ReleaseRequest r
                         .evidenceId(ref.evidenceId())
                         .cyclesEvidenceUrl(ref.cyclesEvidenceUrl())
                         .build());
+                persistEvidenceRef(reservationId, "release", ref);
             }
             cacheLifecycleBody("release", reservationId, releasedResponse);
             return releasedResponse;
@@ -1919,6 +1978,13 @@ private ReservationSummary toSummary(ReservationDetail detail, Set<ReservationIn
         if (include.contains(ReservationInclude.COMMITTED_METADATA)) {
             builder.committedMetadata(detail.getCommittedMetadata());
         }
+        // evidence is the linkage from a reservation to its signed envelope(s);
+        // a small map of refs, but opt-in on list rows for symmetry with the
+        // other heavy projections. Always present on the single-row detail.
+        // Spec: cycles-protocol-v0.yaml revision 2026-06-22 (v0.1.25.9).
+        if (include.contains(ReservationInclude.EVIDENCE)) {
+            builder.evidence(detail.getEvidence());
+        }
         return builder.build();
     }
 
@@ -1994,6 +2060,11 @@ private ReservationDetail buildReservationSummary(Map<String, String> fields) th
         detail.setExpiresAtMs(Long.parseLong(expiresAtStr));
         detail.setScopePath(fields.get("scope_path"));
         detail.setAffectedScopes(affectedScopes);
+        // Evidence refs recorded at reserve/commit/release time (spec v0.1.25.9).
+        // Always hydrated onto the detail; listReservations strips it in toSummary
+        // unless include=evidence. Null when the reservation has no recorded
+        // evidence (emission disabled, or pre-evidence reservation).
+        detail.setEvidence(buildEvidence(fields));
         return detail;
     }
 

cycles-protocol-service/cycles-protocol-service-data/src/test/java/io/runcycles/protocol/data/repository/RedisReservationEvidenceLinkTest.java

@@ -0,0 +1,138 @@
+package io.runcycles.protocol.data.repository;
+
+import io.runcycles.protocol.data.service.EvidenceEmitter;
+import io.runcycles.protocol.model.*;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.util.EnumSet;
+import java.util.Map;
+import java.util.Set;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Covers the reservation -> evidence linkage (spec v0.1.25.9): persisting the
+ * computed evidence ref onto the reservation hash, hydrating it back into the
+ * {@code evidence} field, and the {@code include=evidence} list projection.
+ */
+@DisplayName("RedisReservationRepository — evidence linkage")
+class RedisReservationEvidenceLinkTest extends BaseRedisReservationRepositoryTest {
+
+    private static final String HEX_A = "a".repeat(64);
+    private static final String HEX_B = "b".repeat(64);
+    private static final String HEX_C = "c".repeat(64);
+
+    // ---- hydration (getReservationById builds detail.evidence) ----
+
+    @Test
+    @DisplayName("getReservationById hydrates reserve + commit evidence refs from the hash")
+    void hydratesEvidence() {
+        when(jedisPool.getResource()).thenReturn(jedis);
+        doNothing().when(jedis).close();
+        Map<String, String> fields = reservationFields("res-ev", "COMMITTED");
+        fields.put("charged_amount", "3000");
+        fields.put("reserve_evidence_id", HEX_A);
+        fields.put("reserve_evidence_url", "http://h/v1/evidence/" + HEX_A);
+        fields.put("commit_evidence_id", HEX_B);
+        fields.put("commit_evidence_url", "http://h/v1/evidence/" + HEX_B);
+        when(jedis.hgetAll("reservation:res_res-ev")).thenReturn(fields);
+
+        ReservationDetail detail = repository.getReservationById("res-ev");
+
+        assertThat(detail.getEvidence()).isNotNull();
+        assertThat(detail.getEvidence().getReserve().getEvidenceId()).isEqualTo(HEX_A);
+        assertThat(detail.getEvidence().getReserve().getCyclesEvidenceUrl())
+                .isEqualTo("http://h/v1/evidence/" + HEX_A);
+        assertThat(detail.getEvidence().getCommit().getEvidenceId()).isEqualTo(HEX_B);
+        assertThat(detail.getEvidence().getRelease()).isNull();
+    }
+
+    @Test
+    @DisplayName("getReservationById leaves evidence null when no refs were recorded")
+    void noEvidenceWhenAbsent() {
+        when(jedisPool.getResource()).thenReturn(jedis);
+        doNothing().when(jedis).close();
+        when(jedis.hgetAll("reservation:res_bare")).thenReturn(reservationFields("bare", "ACTIVE"));
+
+        assertThat(repository.getReservationById("bare").getEvidence()).isNull();
+    }
+
+    @Test
+    @DisplayName("a half-written ref (id without url) is ignored")
+    void partialRefIgnored() {
+        when(jedisPool.getResource()).thenReturn(jedis);
+        doNothing().when(jedis).close();
+        Map<String, String> fields = reservationFields("res-half", "ACTIVE");
+        fields.put("reserve_evidence_id", HEX_A); // url missing
+        when(jedis.hgetAll("reservation:res_res-half")).thenReturn(fields);
+
+        assertThat(repository.getReservationById("res-half").getEvidence()).isNull();
+    }
+
+    // ---- persistence (persistEvidenceRef writes id + url) ----
+
+    @Test
+    @DisplayName("persistEvidenceRef HSETs both id and url onto the reservation hash")
+    void persistsRef() throws Exception {
+        when(jedisPool.getResource()).thenReturn(jedis);
+        doNothing().when(jedis).close();
+        EvidenceEmitter.EvidenceRef ref =
+                new EvidenceEmitter.EvidenceRef(HEX_C, "http://h/v1/evidence/" + HEX_C);
+
+        invokePersist("res-p", "commit", ref);
+
+        verify(jedis).hset(eq("reservation:res_res-p"), argThat((Map<String, String> m) ->
+                HEX_C.equals(m.get("commit_evidence_id"))
+                        && ("http://h/v1/evidence/" + HEX_C).equals(m.get("commit_evidence_url"))));
+    }
+
+    @Test
+    @DisplayName("persistEvidenceRef is a no-op for a null ref or null reservation id")
+    void persistNoOp() throws Exception {
+        invokePersist("res-p", "reserve", null);
+        invokePersist(null, "reserve",
+                new EvidenceEmitter.EvidenceRef(HEX_C, "http://h/v1/evidence/" + HEX_C));
+        // Never touched the pool / wrote anything.
+        verify(jedisPool, never()).getResource();
+        verify(jedis, never()).hset(anyString(), anyMap());
+    }
+
+    // ---- projection (toSummary gates evidence on include=evidence) ----
+
+    @Test
+    @DisplayName("toSummary projects evidence only when include=evidence")
+    void projectionGated() throws Exception {
+        ReservationDetail detail = new ReservationDetail();
+        detail.setReservationId("res-x");
+        detail.setEvidence(ReservationEvidence.builder()
+                .reserve(CyclesEvidenceRef.builder().evidenceId(HEX_A)
+                        .cyclesEvidenceUrl("http://h/v1/evidence/" + HEX_A).build())
+                .build());
+
+        assertThat(invokeToSummary(detail, EnumSet.of(ReservationInclude.EVIDENCE)).getEvidence())
+                .isNotNull();
+        assertThat(invokeToSummary(detail, EnumSet.noneOf(ReservationInclude.class)).getEvidence())
+                .isNull();
+    }
+
+    // ---- reflection helpers ----
+
+    private void invokePersist(String id, String artifact, EvidenceEmitter.EvidenceRef ref) throws Exception {
+        Method m = RedisReservationRepository.class.getDeclaredMethod(
+                "persistEvidenceRef", String.class, String.class, EvidenceEmitter.EvidenceRef.class);
+        m.setAccessible(true);
+        m.invoke(repository, id, artifact, ref);
+    }
+
+    private ReservationSummary invokeToSummary(ReservationDetail detail, Set<ReservationInclude> include)
+            throws Exception {
+        Method m = RedisReservationRepository.class.getDeclaredMethod(
+                "toSummary", ReservationDetail.class, Set.class);
+        m.setAccessible(true);
+        return (ReservationSummary) m.invoke(repository, detail, include);
+    }
+}

cycles-protocol-service/cycles-protocol-service-model/src/main/java/io/runcycles/protocol/model/ReservationEvidence.java

@@ -0,0 +1,33 @@
+package io.runcycles.protocol.model;
+
+import com.fasterxml.jackson.annotation.*;
+import jakarta.validation.Valid;
+import lombok.*;
+
+/**
+ * Map of artifact type to the CyclesEvidence reference emitted for that
+ * operation on a reservation (cycles-protocol-v0.yaml revision 2026-06-22,
+ * v0.1.25.9). Lets a consumer jump from a reservation straight to its signed
+ * envelope(s) via {@code getEvidence} without having captured the
+ * {@code evidence_id} off the original reserve / commit / release response.
+ *
+ * <p>A reservation has at most a {@code reserve} entry plus one terminal entry
+ * ({@code commit} XOR {@code release}). TRANSPORT METADATA, NOT ATTESTED (see
+ * {@link CyclesEvidenceRef}) — each entry is recorded after its artifact's
+ * {@code evidence_id} was computed. {@code NON_NULL} strips absent artifacts;
+ * the whole object is absent when the reservation has no recorded evidence
+ * (emission disabled, or the reservation predates evidence support).
+ */
+@Data @Builder @NoArgsConstructor @AllArgsConstructor
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public class ReservationEvidence {
+    @Valid @JsonProperty("reserve") private CyclesEvidenceRef reserve;
+    @Valid @JsonProperty("commit") private CyclesEvidenceRef commit;
+    @Valid @JsonProperty("release") private CyclesEvidenceRef release;
+
+    /** True when no artifact ref is set — used to avoid attaching an empty map. */
+    @JsonIgnore
+    public boolean isEmpty() {
+        return reserve == null && commit == null && release == null;
+    }
+}

cycles-protocol-service/cycles-protocol-service-model/src/main/java/io/runcycles/protocol/model/ReservationInclude.java

@@ -17,7 +17,11 @@
  */
 public enum ReservationInclude {
     METADATA("metadata"),
-    COMMITTED_METADATA("committed_metadata");
+    COMMITTED_METADATA("committed_metadata"),
+    /** Project ReservationSummary.evidence (CyclesEvidence refs for the
+     * reservation's reserve/commit/release operations). Spec revision
+     * 2026-06-22 (v0.1.25.9). */
+    EVIDENCE("evidence");
 
     private final String wire;
 

cycles-protocol-service/cycles-protocol-service-model/src/main/java/io/runcycles/protocol/model/ReservationSummary.java

@@ -43,4 +43,12 @@ public class ReservationSummary {
      * (include=committed_metadata). Spec: cycles-protocol-v0.yaml revision
      * 2026-06-19 (cycles-server#197 read-path, #201 list projection). */
     @JsonProperty("committed_metadata") private Map<String, Object> committedMetadata;
+    /** CyclesEvidence references for this reservation's reserve / commit /
+     * release operations, keyed by artifact type — lets a consumer resolve the
+     * signed envelope(s) via getEvidence without having captured the
+     * evidence_id off the original response. Always present (when recorded) on
+     * the single-row ReservationDetail; on listReservations it is OMITTED BY
+     * DEFAULT and projected only when the caller opts in via include=evidence.
+     * Spec: cycles-protocol-v0.yaml revision 2026-06-22 (v0.1.25.9). */
+    @Valid @JsonProperty("evidence") private ReservationEvidence evidence;
 }

cycles-protocol-service/cycles-protocol-service-model/src/test/java/io/runcycles/protocol/model/ReservationEvidenceTest.java

@@ -0,0 +1,39 @@
+package io.runcycles.protocol.model;
+
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DisplayName("ReservationEvidence")
+class ReservationEvidenceTest {
+
+    private static CyclesEvidenceRef ref(String hex) {
+        return CyclesEvidenceRef.builder()
+                .evidenceId(hex).cyclesEvidenceUrl("http://h/v1/evidence/" + hex).build();
+    }
+
+    @Test
+    @DisplayName("isEmpty is true only when no artifact ref is set")
+    void isEmpty() {
+        assertThat(ReservationEvidence.builder().build().isEmpty()).isTrue();
+        assertThat(ReservationEvidence.builder().reserve(ref("a".repeat(64))).build().isEmpty())
+                .isFalse();
+        assertThat(ReservationEvidence.builder().commit(ref("b".repeat(64))).build().isEmpty())
+                .isFalse();
+        assertThat(ReservationEvidence.builder().release(ref("c".repeat(64))).build().isEmpty())
+                .isFalse();
+    }
+
+    @Test
+    @DisplayName("holds a ref per artifact type")
+    void holdsRefs() {
+        ReservationEvidence e = ReservationEvidence.builder()
+                .reserve(ref("a".repeat(64)))
+                .commit(ref("b".repeat(64)))
+                .build();
+        assertThat(e.getReserve().getEvidenceId()).isEqualTo("a".repeat(64));
+        assertThat(e.getCommit().getEvidenceId()).isEqualTo("b".repeat(64));
+        assertThat(e.getRelease()).isNull();
+    }
+}