docs/vrl-proof-bundle

core concepts

VRL Proof Bundle

A VRL Proof Bundle is a structured evidence record produced for a verified API call. It contains the verdict, confidence score, per-verifier results, extracted claims, timestamps, and configured integrity metadata. Long-term tamper evidence depends on the storage controls configured for the deployment.

example bundle (abbreviated)

{
  "bundle_id": "bndl_01j9xk2m3n4p5q6r7s8t9u0v",
  "schema_version": "1.2.0",
  "created_at": "2025-01-15T14:23:07.412Z",
  "verdict": "PASS",
  "confidence_score": 0.94,
  "model": {
    "declared": "openai/gpt-4o",
    "fingerprinted": "openai/gpt-4o",
    "match": true
  },
  "verifiers": [
    {
      "id": "model_fingerprinter",
      "type": "deterministic",
      "verdict": "PASS",
      "score": 1.0,
      "weight": 0.10,
      "latency_ms": 12
    },
    {
      "id": "symbolic_solver",
      "type": "deterministic",
      "verdict": "PASS",
      "score": 1.0,
      "weight": 0.50,
      "claims_checked": 2,
      "latency_ms": 38
    }
    // ... 5 more verifiers
  ],
  "findings": [],
  "integrity": {
    "hash": "sha256:9f2b...",
    "signature_status": "configured_when_enabled",
    "proof_status": "configured_when_enabled"
  }
}

Top-level fields

bundle_idstringrequired

Unique identifier for this bundle. Format: bndl_ followed by a 26-character ULID. Use this ID to retrieve the full bundle via GET /v1/bundles/{bundle_id}.

example: "bndl_01j9xk2m3n4p5q6r7s8t9u0v"

schema_versionstringrequired

VRL Protocol schema version used to produce this bundle. Follows semantic versioning. Consumers should check this field before parsing.

example: "1.2.0"

created_atstring (ISO 8601)required

Timestamp of bundle creation in UTC. Millisecond precision.

example: "2025-01-15T14:23:07.412Z"

verdictenum: PASS | FLAG | BLOCKrequired

Aggregated verdict. PASS: confidence ≥ flag_threshold. FLAG: confidence between block_threshold and flag_threshold. BLOCK: confidence < block_threshold, or any deterministic verifier returned BLOCK.

example: "PASS"

confidence_scorenumber (0.0–1.0)required

Weighted confidence score aggregated from all verifier scores. Deterministic verifiers contribute binary scores (0.0 or 1.0). LLM and hybrid verifiers contribute continuous scores.

example: 0.94

model

Produced by Verifier 01 (Model Fingerprinter). Records the declared model identity and the behaviorally fingerprinted identity, and whether they match.

model.declaredstring

Model identity as declared in the request (provider/model-name).

example: "openai/gpt-4o"

model.fingerprintedstring

Model identity as determined by behavioral fingerprinting. null if fingerprinting was inconclusive.

example: "openai/gpt-4o"

model.matchboolean

True if declared and fingerprinted identities match. False triggers a FLAG or BLOCK depending on threshold configuration.

example: true

verifiers[]

Array of 7 verifier result objects. Each verifier runs independently; results are never seen by other verifiers before aggregation.

verifiers[].idstring

Verifier identifier. One of: model_fingerprinter, cross_examiner, hallucination_detector, symbolic_solver, knowledge_graph, temporal_consistency, schema_validator.

example: "symbolic_solver"

verifiers[].typeenum: deterministic | llm | hybrid

Verifier type. Deterministic verifiers produce binary results; LLM verifiers produce continuous confidence scores; hybrid verifiers use both methods.

verifiers[].verdictenum: PASS | FLAG | BLOCK | SKIP

Verifier-level verdict. SKIP indicates the verifier had no applicable claims to evaluate (e.g., no mathematical expressions for symbolic_solver).

verifiers[].scorenumber (0.0–1.0)

Raw verifier score before weight is applied. Deterministic verifiers return 1.0 (PASS) or 0.0 (BLOCK). LLM verifiers return a continuous confidence value.

verifiers[].weightnumber (0.0–1.0)

Weight applied to this verifier's score in the aggregated confidence calculation. Weights sum to 1.0 across all non-SKIP verifiers. Configurable per deployment.

verifiers[].claims_checkedinteger

Number of claims evaluated by this verifier. Present on verifiers that operate on extracted claims.

example: 4

verifiers[].latency_msinteger

Time in milliseconds for this verifier to complete. All verifiers run in parallel; total added latency ≈ max(verifier latencies).

example: 1240

findings[]

Array of specific issues identified by verifiers. Empty for PASS verdicts with no notable signals. Each finding references the claim and the verifier that raised it.

findings[].verifier_idstring

ID of the verifier that raised this finding.

findings[].claim_idstring

ID of the specific extracted claim this finding applies to.

findings[].severityenum: info | warning | error

Severity of the finding. error findings contribute to BLOCK verdicts; warning findings contribute to FLAG.

findings[].descriptionstring

Human-readable description of the finding. Not suitable for display to end users without sanitisation.

integrity

Deployment-specific integrity metadata. These fields are used to record hashes and configured verification metadata for the customer environment in scope. They should be confirmed during onboarding before they are referenced in a security questionnaire.

integrity.hashstring

Hash of the bundle payload for comparison during review.

integrity.signature_statusstring

Whether a deployment-specific signing control is configured.

integrity.proof_statusstring

Whether additional proof metadata is configured for the deployment.

proofs[]

Optional array of typed cryptographic proof entries. Each entry advertises its proof_type so a generic VRL Proof Bundle consumer can dispatch to the matching verifier without modifying the core schema. Each entry is self-contained: it can be verified independently of the rest of the bundle, and an outer integrity layer chains it via its hash.

proofs[].proof_typestring

Identifier of the typed proof. The verifier uses this to dispatch.

example: "vrl.shipping.linear-sum.v1"

proofs[].proof_versionstring

Semver of the typed proof. Backward-incompatible changes increment the major version and a new identifier (…v2) is registered.

example: "1.0.0"

proofs[].domainstring

High-level domain of the proof (e.g. shipping, tariffs, claims).

proofs[].schemestring

Underlying cryptographic scheme(s) used. Combined with proof_type, fully specifies how to verify.

example: "pedersen-linear-nizk-v1+vrl-zk-range-bit-or-v1"

proofs[].statementobject

Public claim being proved. Shape is fixed by the proof_type.

proofs[].payloadobject

Cryptographic material (commitments, range proofs, transcripts, group parameters). Shape is fixed by the proof_type.

proofs[].hashstring

sha256 digest of the canonical encoding of the entry, excluding the hash field itself. Lets an outer integrity layer chain the entry without parsing the typed payload.

→ Reference: vrl.shipping.linear-sum.v1 → Reference: vrl.tariff.duty-membership.v1 → Reference: vrl.drug-pricing.340b-ceiling.v1

evidence review

Use the bundle together with workspace logs, retention settings, access records, and customer-specific deployment notes. Do not claim a stronger integrity guarantee unless it is enabled and evidenced for that customer environment.

evidence.workspace_idstring

Workspace that produced the bundle.

evidence.retention_policystring

Retention policy applied to the bundle and related logs.

evidence.access_scopestring

Roles or service accounts allowed to retrieve the bundle.