up

docs/replay/DETERMINISTIC_REPLAY.md

@@ -147,6 +147,8 @@ The optional `reachability` block captures the inputs needed to replay explainab
 
 Replay engines MUST verify every referenced artifact hash before re-evaluating reachability. Missing graphs downgrade affected signals to `reachability:unknown` and should raise policy warnings.
 
+Producer note: default clock values in `StellaOps.Replay.Core` are `UnixEpoch` to avoid hidden time drift; producers MUST set `scan.time` and `reachability.runtimeTraces[].recordedAt` explicitly.
+
 ---
 
 ## 4. Deterministic Execution Rules
@@ -169,10 +171,19 @@ Replay engines MUST verify every referenced artifact hash before re-evaluating r
 * Parallel jobs: ordered reduction by subject path.
 * Temporary directories: ephemeral but deterministic hash seeds.
 
-### 4.3 Feeds & Policies
-
-* All network I/O disabled; feeds must be read from snapshot bundles.
-* Policies and suppressions must resolve by hash, not name.
+### 4.3 Feeds & Policies
+
+* All network I/O disabled; feeds must be read from snapshot bundles.
+* Policies and suppressions must resolve by hash, not name.
+
+### 4.4 Library hooks (StellaOps.Replay.Core)
+
+Use the shared helpers in `src/__Libraries/StellaOps.Replay.Core` to keep outputs deterministic:
+
+- `CanonicalJson.Serialize(...)` → lexicographic key ordering with relaxed escaping, arrays preserved as-is.
+- `DeterministicHash.Sha256Hex(...)` and `DeterministicHash.MerkleRootHex(...)` → lowercase digests and stable Merkle roots for bundle manifests.
+- `DssePayloadBuilder.BuildUnsigned(...)` → DSSE payloads for replay manifests using payload type `application/vnd.stellaops.replay+json`.
+- `ReplayManifestExtensions.ComputeCanonicalSha256()` → convenience for CAS naming of manifest blobs.
 
 ---
 
@@ -182,7 +193,7 @@ Replay engines MUST verify every referenced artifact hash before re-evaluating r
 
 ```jsonc
 {
-  "payloadType": "application/vnd.stella.replay.manifest+json",
+  "payloadType": "application/vnd.stellaops.replay+json",
   "payload": "<base64-encoded canonical JSON>",
   "signatures": [
     { "keyid": "authority-root-fips", "sig": "..." },
@@ -193,12 +204,16 @@ Replay engines MUST verify every referenced artifact hash before re-evaluating r
 
 ### 5.2 Verification Steps
 
-1. Decode payload → verify canonical form.
-2. Verify each signature chain against RootPack (offline trust anchors).
-3. Recompute hash and compare to `dsseEnvelopeHash` in manifest.
-4. Optionally verify Rekor inclusion proof.
-
----
+1. Decode payload → verify canonical form.
+2. Verify each signature chain against RootPack (offline trust anchors).
+3. Recompute hash and compare to `dsseEnvelopeHash` in manifest.
+4. Optionally verify Rekor inclusion proof.
+
+### 5.3 Default payload type
+
+Replay DSSE envelopes emitted by `DssePayloadBuilder` use payload type `application/vnd.stellaops.replay+json`. Consumers should treat this as canonical unless a future manifest revision increments the schema and payload type together.
+
+---
 
 ## 6. CLI Interface
 

docs/replay/DEVS_GUIDE_REPLAY.md

@@ -86,13 +86,13 @@ stella replay manifest.json --what-if --vary=feeds
 
 ## Storage
 
-- **Mongo collections**
-  - `replay_runs`: manifest + DSSE envelopes + status
-  - `bundles`: content-addressed (input/output/rootpack)
-  - `subjects`: OCI digests, Merkle roots per layer
-  - `reachability_facts`: graph & runtime trace references tied to scan subjects
+- **Mongo collections** (see `../data/replay_schema.md`)
+  - `replay_runs`: manifest hash, status, signatures, outputs
+  - `replay_bundles`: digest, type, CAS location, size
+  - `replay_subjects`: OCI digests + per-layer Merkle roots
+- **Indexes** (canonical names): `runs_manifestHash_unique`, `runs_status_createdAt`, `bundles_type`, `bundles_location`, `subjects_layerDigest`
 - **File store**
-  - Bundles stored as `<sha256>.tar.zst`
+  - Bundles stored as `<sha256>.tar.zst` in CAS (`cas://replay/<shard>/<digest>.tar.zst`); shard = first two hex chars
 
 ---