Skip to content
VB-OSVB-OSVB-OS Docs

Deterministic Replay in VB-OS

Replay is the ability to reproduce any past evaluation and get an identical result. It is an architectural guarantee backed by immutability, immutable storage, and integrity verification.

How Replay Works

Section titled “How Replay Works”

When you replay an evaluation, the system:

  1. Retrieves the original evaluation record
  2. Loads the boundary snapshot from the BoundaryVersion record (immutable by convention)
  3. Verifies the boundary snapshot hash matches the recorded hash
  4. Loads the original evidence from immutable storage
  5. Identifies the binary version used in the original evaluation
  6. Verifies the engine version hash matches the recorded hash
  7. Re-executes the evaluation with the original inputs
  8. Returns the result: identical to the original

Immutable Storage, Not Live State

Section titled “Immutable Storage, Not Live State”

This is a critical distinction. Replay never uses live database state. The boundary may have been updated to version 5 since the evaluation, but replay uses the exact version 2 snapshot from the original evaluation. The evidence table may contain newer records, but replay uses the exact evidence snapshot from the original submission.

Boundary versions are stored in PostgreSQL (the BoundaryVersion table is immutable by convention). Evaluation artifacts are preserved in immutable storage.

Integrity Verification

Section titled “Integrity Verification”

Before replay executes, integrity hashes are verified:

  • workload_hash: the workload content has not been altered
  • evidence_chain_hash: the evidence chain is intact
  • boundary_snapshot_hash: the compiled boundary has not been tampered with
  • replay_id recomputation: the replay identifier matches
  • boundary version hash: the boundary version hash matches the original
  • binary_sha256: the evaluation engine binary is the same version

If any hash does not match, replay fails with an integrity error. The system will not produce an unverifiable result.

Why Replay Is Deterministic

Section titled “Why Replay Is Deterministic”

The evaluation engine guarantees deterministic execution:

  • Integer-only arithmetic: no floating-point rounding differences across platforms
  • No side effects: evaluation reads inputs and returns a verdict, nothing else
  • No randomness: no random number generation
  • Both branches evaluated: AND/OR expressions always evaluate both sides
  • Fixed pipeline order: admissibility → prohibition → predicate evaluation, every time

Same inputs + same boundary + same binary = same result. Always.

Replay Executions

Section titled “Replay Executions”

Each replay creates an append-only ReplayExecution record that captures:

  • The original evaluation ID
  • The replayed verdict
  • The binary version used for replay
  • binary_version_match: whether the binary version matches the original
  • result_match: whether the replayed verdict matches the original
  • replay_id_match: whether the recomputed replay ID matches the original
  • Who initiated the replay and when

Replay executions are themselves immutable records.

Use Cases

Section titled “Use Cases”
Use Case How Replay Helps
Audit Auditors independently verify past authorization decisions
Incident investigation Reproduce the exact evaluation that authorized or deferred an action
Regression testing Replay historical evaluations against updated boundaries to preview impact
Compliance Demonstrate reproducibility to regulators

Running a Replay

Section titled “Running a Replay”
replay = client.evaluations.replay(
    project_id="PROJECT_ID",
    evaluation_id="EVALUATION_ID",
)


print(replay.decision)  # Identical to the original
Terminal window
curl -X POST https://api.vb-os.org/v1/projects/{project_id}/evaluations/{evaluation_id}/replay \
  -H "Authorization: Bearer YOUR_API_KEY_HERE"

Next Steps

Section titled “Next Steps”