ADR-0002: Run Snapshots & Determinism

Status: Accepted
Date: 2025-12-29

Context

• Assessment runs must be reproducible for audit purposes
• External dependencies (LLM responses, embeddings) change over time
• Need to reconstruct exact assessment state for regulatory review

Decision

1. Snapshot pinning at run creation - 6 version IDs frozen (shared/schema.ts:353-359):

   • snapshotCriteriaVersionId
   • snapshotCorpusActivationId
   • snapshotRetrievalVersionId
   • snapshotPromptVersionId
   • snapshotChunkingVersionId
   • snapshotAgentVersionId

2. SnapshotStatus enum at shared/schema.ts:306-313:

   • PENDING: Run in progress
   • CAPTURED: Snapshot successfully stored
   • FAILED: Snapshot capture failed
   • LEGACY: Pre-Step 9 run, no snapshot exists

3. Immutable replay snapshots stored in run_replay_snapshots table (shared/schema.ts:382-396)

4. Pack immutability enforced by server/lib/packSafetyService.ts:

   • Once ACTIVE, pack bindings cannot be modified in-place
   • HTTP 409 PACK_ACTIVE_IMMUTABLE returned on mutation attempts

5. Replay guard at server/lib/replayGuard.ts prevents non-deterministic operations during replay

Alternatives Considered

1. Store full LLM responses - Rejected: storage cost, privacy concerns
2. No versioning, accept non-reproducibility - Rejected: regulatory requirement

Consequences

• All binding changes require new pack or version
• FAILED runs cannot be replayed from live tables
• Operators must handle LEGACY runs with warning