Skip to content
VB-OSVB-OSVB-OS Docs

Deterministic Authorization Patterns with VB-OS

VB-OS implements deterministic authorization: the same evidence always produces the same verdict. This page covers the design patterns that make this possible.

Separate Inference from Authority

Section titled “Separate Inference from Authority”

The system that recommends an action is not the system that authorizes it. These are structurally different responsibilities:

Concern System Properties
Inference Your model, rules engine, or agent Probabilistic, evolving, complex
Authority VB-OS boundary Deterministic, versioned, replayable

Keep them separate. The inference system produces evidence (scores, classifications, recommendations). VB-OS evaluates that evidence against a boundary and produces a verdict.

Integer Encoding

Section titled “Integer Encoding”

All boundary evaluation uses 64-bit integer arithmetic. Encode decimal values as integers:

Domain Real Value Integer Encoding
Currency $150.00 15000 (cents)
Percentage 99.5% 9950 (basis points)
Score 0.85 8500 (×10000)
Temperature 36.6°C 366 (×10)

Choose a consistent scale factor for each field. Document the encoding in the boundary and evidence schema.

Fail-Closed Design

Section titled “Fail-Closed Design”

Design boundaries to fail closed: when uncertain, DEFER:

# Require all evidence -- missing fields produce DEFER
require_evidence: score
require_evidence: threshold
require_evidence: authorization_level
require_evidence: risk_level


# Conditional requirements fail closed too
# If the condition field is missing, the requirement applies
require_evidence IF risk_level > 50: enhanced_check

Never design a boundary where missing evidence produces ASSERT.

Idempotent Verification

Section titled “Idempotent Verification”

Use the X-Idempotency-Key header to make verification calls safe to retry:

result = client.verify(
    workload=evidence,
    project="my-project",
    boundary_ref="my-boundary",
)

The same idempotency key returns the same evaluation result without creating a duplicate record. Pass the key as an HTTP header, not in metadata – metadata is non-authoritative and never affects evaluation outcome or request identity.

Version Pinning

Section titled “Version Pinning”

Always reference explicit boundary versions when promoting or deploying. Never rely on “latest”:

# Correct: explicit version
client.deployments.create(
    project_id="PROJECT_ID",
    environment_id="PROD_ENV_ID",
    boundary_version_id="SPECIFIC_VERSION_ID",
)

This prevents TOCTOU races where a newer version is compiled between your decision to deploy and the actual deployment.

Next Steps

Section titled “Next Steps”