VBL Complete Language Reference

This is the complete reference for VBL. It covers every construct, its syntax, and its evaluation semantics.

Grammar

Boundary Specification

boundary_spec      ::= governance_spec? | boundary_block
governance_spec    ::= governance_header? governance_declaration+ boundary_block?
                     | governance_header boundary_block

A boundary specification consists of either a governance specification (with declarations and optional metadata) or a standalone BOUNDARY block. Governance metadata, if present, must appear first.

Governance Header (Metadata)

governance_header  ::= boundary_id_decl? version_decl? scope_decl? eta_cap_decl?
boundary_id_decl   ::= "boundary_id" ":" metadata_value
version_decl       ::= "version" ":" metadata_value
scope_decl         ::= "scope" ":" metadata_value
eta_cap_decl       ::= "eta_cap" ":" metadata_value

All metadata fields are optional. At least one must be present if you want a governance header. Metadata does not affect evaluation outcome: it is audit and traceability data.

Governance Declarations

governance_declaration ::= set_definition
                         | conditional_evidence_requirement
                         | evidence_requirement
                         | evidence_prohibition
                         | provenance_requirement
                         | type_declaration
                         | predicate_binding

Evidence Requirements

evidence_requirement              ::= "require_evidence" ":" evidence_class_name
conditional_evidence_requirement  ::= "require_evidence" "IF" comparison ":" evidence_class_name

Evidence Prohibitions

evidence_prohibition ::= "prohibit_evidence" ":" evidence_class_name ("WHERE" comparison)?

The WHERE comparison LHS must match the prohibited field name. Without WHERE, the field must not be present at all.

Provenance

provenance_requirement ::= "require_provenance" ":" evidence_class_name ":" provenance_source

Type Declarations

type_declaration ::= "require_type" ":" field_name ":" type_name
type_name        ::= "integer" | "string" | "boolean"

Named Sets

set_definition ::= "define_set" set_name ":" "(" literal ("," literal)* ")"
set_name       ::= lowercase_identifier

Named sets are referenced in expressions using @set_name. Sets must be homogeneous (all elements the same type) and non-empty.

Predicates

predicate_binding ::= "predicate" ":" predicate_name ":" expr ("|" string_literal)?
predicate_name    ::= lowercase_identifier

The optional | "message" suffix attaches a human-readable failure message to the predicate. Messages are metadata-only: they do not affect evaluation outcome.

Eta Cap

eta_cap_declaration ::= "eta_cap" ":" metadata_value

BOUNDARY Block

boundary_block ::= "BOUNDARY" "{" expr? "}"

Expressions

expr         ::= and_expr ("OR" and_expr)*
and_expr     ::= not_expr ("AND" not_expr)*
not_expr     ::= "NOT" not_expr | primary
primary      ::= "(" expr ")"
               | set_membership
               | list_contains
               | comparison

Comparisons

comparison     ::= field_name comparison_op comparison_rhs
comparison_rhs ::= literal | field_name
comparison_op  ::= "<=" | ">=" | "!=" | "<" | ">" | "=="

The right-hand side accepts either a literal value or a field reference, enabling field-to-field comparisons like refund_amount <= order_total.

Set Membership

set_membership ::= field_name set_op (set_reference | "(" literal ("," literal)* ")")
set_op         ::= "NOT" "IN" | "IN"
set_reference  ::= "@" set_name

Set membership checks whether a field value is in (or not in) a named set or an inline literal list.

Containment

list_contains ::= field_name "CONTAINS" literal

Checks whether a list-valued field contains a given scalar element.

Lexical Rules

evidence_class_name ::= [a-z] [a-z0-9_]*
predicate_name      ::= [a-z] [a-z0-9_]*
field_name          ::= field_segment ("." field_segment)*
field_segment       ::= [a-zA-Z] [a-zA-Z0-9_]*
literal             ::= string_literal | boolean_literal | integer_literal
integer_literal     ::= "-"? ("0" | [1-9] [0-9]*)
string_literal      ::= '"' (escaped_char | normal_char)* '"'
boolean_literal     ::= "true" | "false"
metadata_value      ::= '"' [^"]* '"' | [a-zA-Z0-9_.%-]+

Evidence class names and predicate names must be lowercase. Field names in expressions may use mixed case.

Evaluation Semantics

Pipeline Order

Stage 1: Admissibility (require_evidence, require_type, conditional evidence, require_provenance)
Stage 2: Prohibition (prohibit_evidence, conditional prohibition)
Stage 3: Predicates + BOUNDARY expression

Stages execute in order. On failure, subsequent stages do not run (short-circuit between stages).

Stage 1 Details

• require_evidence: field must be present with a non-null value. Failure: F2-004.
• require_type: field must be present with the declared type. Failure: F2-004.
• require_evidence IF comparison: if the condition is true, the field is required. If the condition field is missing, the requirement fails closed (is applied). Failure: F2-004.

Stage 2 Details

• prohibit_evidence: field must not be present. Failure: F2-005.
• prohibit_evidence WHERE comparison: field absent → satisfied. Field present + condition true → F2-005. Field present + condition false → satisfied. Condition indeterminate → F2-005 (fail closed).

Stage 3 Evaluation

• Named predicates are evaluated conjunctively: all must pass
• The BOUNDARY expression is evaluated after predicates
• Both branches of AND/OR are always evaluated (no short-circuit within expressions)
• An empty BOUNDARY block passes trivially
• BOUNDARY blocks contain inline field comparisons, not predicate name references

Reserved Keywords

Expression keywords: AND, OR, NOT, BOUNDARY, IN, CONTAINS, WHERE, true, false

Governance keywords: require_evidence, prohibit_evidence, require_provenance, require_type, predicate, define_set, boundary_id, version, scope, eta_cap

Governance keywords are recognized as keywords only when immediately followed by :. Without the colon, they are valid field names.

Governance keywords are unconditionally excluded from evidence_class_name and predicate_name positions regardless of context. For example, require_evidence: version is a parse error. However, governance keywords are valid as field names in expressions: predicate: check: version >= 2 is valid.

Comments

comment ::= ("#" | "//") .* newline

Implementation

The VBL parser is purpose-built for deterministic evaluation. The platform compiles VBL source into a compiled boundary using a single pipeline: VBL source → compiled boundary.