Skip to content
VB-OSVB-OSVB-OS Docs

Evaluations in VB-OS

An evaluation is the result of submitting evidence to a boundary. It records the verdict (ASSERT or DEFER), the evidence, the boundary version, and the binary version: everything needed to reproduce the decision.

The Evaluation Record

Section titled “The Evaluation Record”

Every evaluation produces an immutable record containing:

Field Description
id Unique identifier for this evaluation
replay_id Content-identity hash for replay determinism
decision ASSERT or DEFER
boundary_ref The boundary that was evaluated
boundary_version_id UUID of the compiled version used
boundary_version_number Integer version number
boundary_snapshot_hash Hash of the compiled snapshot
admissibility_satisfied Stage 1 result (boolean)
admissibility_summary Stage 1 detail: required vs. present fields
missing_fields Fields required but absent (null when satisfied)
predicate_summary Stage 3 result: each predicate and its outcome
failure_reason_types List of failure type strings (empty for ASSERT)
created_at When the evaluation occurred
latency_ms Evaluation duration in milliseconds
binary_version Evaluation engine version used
binary_sha256 Integrity hash of the engine binary

Immutability

Section titled “Immutability”

Evaluation records are append-only. Once created, they cannot be modified or deleted. This is enforced at the platform level: no API endpoint or code path can modify or delete evaluation records.

This immutability serves two purposes:

  1. Replay: the original inputs are preserved for reproduction
  2. Audit: the evaluation record is a tamper-evident artifact

Listing Evaluations

Section titled “Listing Evaluations”

Retrieve evaluation history for a project:

evaluations = client.evaluations.list(
    project_id="PROJECT_ID",
    limit=20,
)


for eval in evaluations.items:
    print(f"{eval.id}: {eval.decision}")

All list endpoints are paginated. Use the cursor from the response to fetch the next page.

Retrieving a Single Evaluation

Section titled “Retrieving a Single Evaluation”
evaluation = client.evaluations.get(
    project_id="PROJECT_ID",
    evaluation_id="EVALUATION_ID",
)

The detail response includes the full evaluation breakdown: admissibility summary, predicate summary, and failure reason types.

Replay

Section titled “Replay”

Any evaluation can be replayed to reproduce the original verdict:

replay = client.evaluations.replay(
    project_id="PROJECT_ID",
    evaluation_id="EVALUATION_ID",
)

Replay loads the boundary snapshot and evidence from immutable storage, verifies integrity hashes, and re-executes with the original binary version. See Replay Your Decision for details.

Evaluation vs. Verify

Section titled “Evaluation vs. Verify”
  • verify is the action: submitting evidence for evaluation
  • evaluation is the record: the immutable result of that action

The API reflects this distinction:

  • POST /v1/verify: submit evidence (action)
  • GET /v1/projects/{id}/evaluations: list evaluation records
  • GET /v1/projects/{id}/evaluations/{id}: retrieve a record
  • POST /v1/projects/{id}/evaluations/{id}/replay: replay a record

Next Steps

Section titled “Next Steps”