prep docs and service updates

docs/modules/evidence-locker/replay-payload-contract.md

@@ -1,42 +1,21 @@
-# Replay Payload Contract (Draft) — PREP-EVID-REPLAY-187-001
+# Replay Payload Contract (Prep for PREP-EVID-REPLAY-187-001)
 
-Status: Draft (2025-11-20)
-Owners: Evidence Locker Guild · Scanner Guild · CLI Guild
-Scope: Capture expected scanner record payloads needed by Evidence Locker replay APIs.
+Status: **Ready for implementation** (2025-11-20)
+Owners: Evidence Locker Guild · Scanner Guild
+Scope: Define deterministic scanner record payload shape required to ingest replay bundles (Sprint 0187).
 
-## 1) Payload envelope
-- Content type: `application/vnd.stella.replay.record+json;version=1`.
+## Payload shape
+- NDJSON per record; sorted by `recordedAtUtc` then `scanId`.
 - Fields:
-  - `record_id` (ULID, assigned by Scanner).
-  - `tenant_id` (string).
-  - `source` (enum): `scanner`, `attestor`, `cli`.
-  - `digest` (hex): SHA-256 of canonical payload bytes.
-  - `created_at` (RFC3339 UTC).
-  - `schema_version`: `replay.record.v1`.
+  - `scanId` (GUID), `tenantId`, `subjectDigest` (sha256:...), `scanKind` (sbom|vuln|policy),
+  - `startedAtUtc`, `completedAtUtc` (ISO-8601),
+  - `artifacts`: array of `{ type: sbom|vex|log, digest, uri }`,
+  - `provenance`: `{ dsseEnvelope, transparencyLog? }` (base64 DSSE; optional Rekor entry),
+  - `summary`: `{ findings: int, advisories: int, policies: int }`.
+- Determinism: no wall-clock except the recorded timestamps above; DSSE envelope copied verbatim from scanner output.
 
-## 2) Scanner record body (expected from Sprint 0186)
-- `image_digest` (string, required).
-- `sbom_digest` (string, optional) with SBOM pointer.
-- `observations` (array) of `{type, component_purl?, location, evidence, confidence}`.
-- `signals` (array) for runtime/static signals with `{name, value, units?, confidence}`.
-- `attestations` (array) of DSSE statement references `{type, uri, sha256}`.
-- `provenance` (object): `{scanner_version, policy_profile, worker_id}`.
+## Acceptance criteria
+- Scanner Guild provides sample NDJSON (10 records) with DSSE envelope redacted allowed.
+- Evidence Locker can ingest and store bundle with deterministic ordering and hash (SHA256) across runs.
+- Contract published here and referenced in Sprint 0187 P1/P2/P3.
 
-## 3) Evidence Locker ingestion contract
-- API: `POST /replay/records` (internal) accepting NDJSON stream (`record_envelope + body`).
-- Validation:
-  - hash must match `digest` supplied; timestamps UTC.
-  - tenant_id must match auth principal or delegated token.
-  - schema_version must equal `replay.record.v1` until upgraded.
-- Storage layout proposal: bucket prefix `replay/records/{tenant_id}/{record_id}.ndjson`, immutable; metadata indexed in Mongo with `{record_id, image_digest, created_at}`.
-
-## 4) Open dependencies
-- Scanner team to freeze exact `observations` and `signals` schema in Sprint 0186.
-- Need DSSE profile for `attestations` (Authority/Attestor alignment).
-- CLI replay commands depend on finalized pointer format to retrieve records.
-
-## 5) Next actions
-- Once Sprint 0186 publishes sample payloads, update this doc with enumerated observation/signal types and add JSON schema file under `docs/modules/evidence-locker/schemas/replay-record-v1.json`.
-
-## 6) Handoff
-Reference this document from sprint trackers for PREP-EVID-REPLAY-187-001 and related CLI/Attestor PREP tasks. Update when upstream payloads are available.