Evidence in VB-OS

Evidence is the input to every evaluation. It is a structured collection of fields that describe the context of an action: the amounts, scores, identifiers, and conditions that a boundary evaluates.

Structure

Evidence is submitted as the workload field in a verification request. It is a dictionary of key-value pairs:

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

Field Names

Field names follow these rules:

• Start with an ASCII letter
• Contain only alphanumeric characters and underscores
• Are case-sensitive

Value Types

The evaluation engine operates on these types:

• Integer: 64-bit signed integers. All arithmetic and comparisons use integer math.
• String: UTF-8 strings. Used in equality comparisons and set membership checks.
• Boolean: true or false.

The engine does not use floating-point arithmetic anywhere in the evaluation path. If your source data contains floats, convert to integers before submission (e.g., represent $150.00 as 15000 cents).

Evidence and the Evaluation Pipeline

Evidence interacts with each pipeline stage differently:

Stage 1: Admissibility

The engine checks that every field declared with require_evidence in the boundary is present in the workload with a non-null value.

require_evidence: transaction_amount
require_evidence: account_balance

If transaction_amount is missing from the workload, the evaluation produces DEFER at Stage 1.

Conditional evidence requirements check presence only when a condition is true:

require_evidence IF risk_score > 50: enhanced_verification

If risk_score is greater than 50, then enhanced_verification must also be present.

Type declarations validate both presence and type:

require_type: transaction_amount: integer

Stage 2: Prohibition

Fields declared with prohibit_evidence must not be present:

prohibit_evidence: social_security_number

If social_security_number exists in the workload, the evaluation produces DEFER at Stage 2.

Stage 3: Predicate Evaluation

Named predicates and the BOUNDARY expression evaluate conditions against evidence values:

predicate: sufficient_funds: account_balance >= transaction_amount

The engine reads account_balance and transaction_amount from the workload and evaluates the comparison.

Evidence Sources

Evidence enters the system through two paths:

Direct Submission

Include evidence fields directly in the API request body as the workload dictionary. This is the simplest path: your application constructs the evidence and submits it.

Connectors

Connectors acquire evidence from external systems (databases, APIs, identity providers) and map the results to boundary fields. The connector attaches evaluation-level provenance metadata (a single acquisition_provenance dictionary) recording which system provided the evidence.

See Connectors for details on evidence acquisition.

Provenance

Evidence provenance tracks which system provided each evidence field. Boundaries can require specific provenance using require_provenance:

require_provenance: risk_score: internal_risk_engine

This declares that the risk_score field must come from the internal_risk_engine source. VB-OS verifies provenance: it does not verify truth. The boundary confirms that the data came from the declared source, not that the data is correct.

Immutability

The evidence submitted with an evaluation is preserved as part of the immutable evaluation record. It is stored in immutable storage and used for replay. The evidence is never modified after submission: it is a snapshot of the facts at evaluation time.

Next Steps

• Boundaries: what evaluates the evidence
• Evaluations: the record produced by evaluation
• Connectors: acquiring evidence from external systems