Skip to content
VB-OSVB-OSVB-OS Docs

How VB-OS Works: The Three-Stage Evaluation Pipeline

VB-OS separates execution authority from inference capability. It provides a deterministic evaluation pipeline that processes evidence against boundaries to produce binary verdicts.

The Evaluation Pipeline

Section titled “The Evaluation Pipeline”

Every evaluation runs through a fixed three-stage pipeline. The stages execute in order and short-circuit on failure: if Stage 1 fails, Stages 2 and 3 never run.

Stage 1: Admissibility

Section titled “Stage 1: Admissibility”

The engine checks whether all required evidence is present in the workload.

Every field declared with require_evidence must exist with a non-null value. If any required field is missing, the evaluation produces DEFER with failure code F2-004. The API returns this as failure type admissibility_not_satisfied.

Conditional evidence requirements (require_evidence IF condition: field) are also checked here: the target field is required only when the condition evaluates to true. If the condition is indeterminate (references missing fields), the requirement fails closed.

Type declarations (require_type: field: integer) validate both presence and type in this stage.

Stage 2: Prohibition

Section titled “Stage 2: Prohibition”

The engine checks whether any prohibited evidence is present.

Fields declared with prohibit_evidence must not exist in the workload (simple form), or must not satisfy a WHERE condition when present (conditional form). If any prohibition is violated, the evaluation produces DEFER with failure code F2-005. The API returns this as failure type prohibited_evidence_present.

Stage 3: Predicate Evaluation

Section titled “Stage 3: Predicate Evaluation”

The engine evaluates all named predicates and the BOUNDARY expression.

Named predicates (predicate: name: expression) are evaluated conjunctively: all must pass. The BOUNDARY expression, if present, is evaluated against the workload fields. All comparisons use integer, string, or boolean arithmetic with no floating-point operations.

If all predicates and the BOUNDARY expression pass, the evaluation produces ASSERT. If any predicate fails, the result is DEFER with failure code F2-001. The API returns this as failure type predicate_failed.

The Boundary

Section titled “The Boundary”

A boundary is the complete specification of what must be true for an action to proceed. Boundaries are written in VBL (Verification Boundary Language) and contain:

  • Evidence requirements: which fields must be present
  • Evidence prohibitions: which fields must not be present
  • Provenance declarations: which fields must come from specific sources
  • Named predicates: conditions that evidence must satisfy
  • A BOUNDARY expression: the logical formula combining comparisons
  • Governance metadata: identity, version, scope, and eta cap
boundary_id: payment-authorization
version: 1
scope: production


require_evidence: transaction_amount
require_evidence: account_balance
require_evidence: risk_score
require_provenance: risk_score: internal_risk_engine


predicate: sufficient_funds: account_balance >= transaction_amount
predicate: risk_acceptable: risk_score <= 75
predicate: amount_within_limit: transaction_amount <= 50000

Evidence

Section titled “Evidence”

Evidence is the structured data submitted with a verification request. It is a flat or nested JSON object containing the fields that the boundary evaluates.

{
  "transaction_amount": 15000,
  "account_balance": 42000,
  "risk_score": 35
}

Evidence enters the system through two paths:

  1. Direct submission: included in the POST /v1/verify request body
  2. Connectors: acquired from external systems (databases, APIs, identity providers) and mapped to boundary fields

Immutability and Replay

Section titled “Immutability and Replay”

Every evaluation produces an immutable record containing:

  • The boundary version (compiled version, hash-verified)
  • The submitted evidence
  • The verdict (ASSERT or DEFER)
  • The failure reason (if DEFER)
  • The evaluation engine version (integrity-verified)

Because all inputs are preserved and the evaluation engine is deterministic (integer-only, no side effects, no randomness), any evaluation can be replayed from stored artifacts. The replay uses the original boundary snapshot and evidence from immutable storage, not live database state, and verifies integrity hashes before execution.

This is not best-effort reproducibility. It is an architectural guarantee: if the artifact exists and the binary exists, replay produces an identical result.

Architecture

Section titled “Architecture”
┌──────────────┐     ┌──────────────────┐     ┌────────────────┐
│  Your App    │────▶│  VB-OS Cloud API │────▶│  VB-OS Engine  │
│  (SDK/CLI)   │◀────│  (Orchestration) │◀────│  (Evaluation Engine) │
└──────────────┘     └──────────────────┘     └────────────────┘
                              │
                     ┌────────┴────────┐
                     │   Connectors    │
                     │  (Evidence      │
                     │   Acquisition)  │
                     └─────────────────┘

The cloud platform orchestrates. It manages boundaries, connectors, environments, and deployments. The evaluation engine evaluates. It receives a workload and boundary, runs the three-stage pipeline, and returns a verdict. The binary is stateless, deterministic, and bit-identical across deployments.

Next Steps

Section titled “Next Steps”