6. Design
This chapter describes the design of the CADL toolchain. Each section
separates what the public reference implementation (cadl 0.3)
provides from what is design intent and still planned.
Chapter 10 tracks the status per phase.
6.1 Architecture
The CADL toolchain is designed around the following four main components:
Parser and Type Checker (Frontend): Analyzes CADL descriptions and
generates abstract syntax trees (AST). Static type checking verifies
actor reference resolution, contract party consistency, and parameter
ranges. Available in cadl 0.3.
Verification Engine (Verifier): Performs formal verification on AST.
cadl 0.3 provides consistency verification with an SMT solver (Z3 [de Moura & Bjørner, 2008]), protocol
deadlock detection, and graph analysis of regime transitions. For a file
that declares the stochastic model extension
(Appendix H), cadl model-check evaluates
the properties of the parametric Markov model with an internal reference
evaluator in exact arithmetic and computes certified regime maps, and
cadl model-export writes the model in the PRISM language for PRISM and
Storm. For a file that also declares the strategic model extension
(Appendix I), cadl game-check decides in exact
arithmetic whether a named strategy profile, such as compliance, is an
equilibrium, and with --certify computes equilibrium maps over the
parameters. For a file that declares the norms extension,
cadl norms-check translates the norms of one or more instances of a
contract, also when the contract is amended, into a model for PRISM and asks whether each norm can be activated, violated,
and fulfilled and which norms conflict; the norms engine confirms each
trace that PRISM returns (Appendix F, F.12).
Model checking of protocols and reachability analysis of
continuous dynamics are planned.
Code Generator: Generates code from CADL descriptions. cadl 0.3 targets
Python (runtime), Solidity [Solidity Documentation], OPA/Rego [Open Policy Agent], and Unity C# (for the SoS-DSL
extension, Appendix E), and the boundary
policies of the agent governance extension in Rego and Cedar
(Appendix G), and also emits
simulator configurations; the targets are listed in
Appendix D. For a file that declares the norms
extension, the Rego and Solidity targets also write a monitor of the
norms of each contract (Appendix D, D.5). TypeScript
generation and conversion to SysMLv2 [OMG, 2025] and AADL [Feiler & Gluch, 2012] are planned.
Runtime Monitor: Monitors execution of deployed institutions,
detects contract violations, executes institutional transitions, and
performs logging. cadl 0.3 provides these as classes in the generated
runtime code, not as a separate monitoring service. For a file that
declares the norms extension (Appendix F), the
generated Python, Rego, and Solidity code also monitors the norms while
the system runs. For the agent governance extension, cadl mcp-gateway
and cadl a2a-gateway run between an agent and the tools or agents it
calls, decide every message against the contract, and write an audit
log whose hash chain cadl audit-verify checks
(Appendix G).
The pipeline below shows the stages as provided by cadl 0.3.
The figure shows the intended order of use. cadl codegen itself runs
the type check but not the verification engine, so cadl verify has to
be run separately before generating code.
6.2 Toolchain Components
6.2.1 Parser
Parses YAML-based syntax and additionally parses CADL-specific
constraint expressions and protocol steps. In cadl 0.3 a YAML loader reads
the document structure and a Lark [Shinan+] grammar parses the expression
sub-language; parse results are output as typed AST. Parsing stops at
the first error, and keys the parser does not know are skipped without a
diagnostic. A PEG-based parser with error recovery is design intent and
not implemented.
6.2.2 Type Checker
Type checking verifies the following: (1) Actor reference existence
confirmation, (2) Detection of duplicate/missing contract parties, (3)
Protocol step senders/receivers match actor definitions, (4) Information
sharing declarations refer to defined actors, (5) Value constraints for
institutional parameters (0 ≤ α, β, λ ≤ 1), (6) from cadl 0.3.10, the
static semantics of the SoS-DSL extension
(Appendix E, Section E.4), (7) further checks of ids and values —
duplicate ids, identifiers, sharing: entries, autonomy:, severity:, and the
deadline: / sampling: values — listed in
Appendix A, §A.12. Checking information sharing
declarations against the actual message exchanges is planned.
6.2.3 Other Commands
Besides cadl verify and cadl codegen, the reference implementation
provides the following commands.
cadl parseruns the parser alone, andcadl checkthe parser and the type checker.cadl regime-mapgives the regime-graph analysis of Section 6.3 as a report (text, DOT, or JSON).cadl iec62853gives a dependability summary built from the parsed definition.cadl sim-validate,cadl sim-ir, andcadl sim-genlower the definition to the three-layer IR and generate simulator configs (Appendix D).cadl aidrafts a CADL file from a natural-language description through an LLM API, then parses and type-checks it.cadl norms-evalcomputes the verdicts of the norms of one contract instance on a recorded trace, andcadl norms-diffreports what an amendment from one version of a file to the next does to the norms (norms extension, Appendix F).cadl norms-checkis described under the Verification Engine in Section 6.1.cadl norms-indicesderives indices of information sharing and concentration of powers and the incentive coverage from the norms of each contract and compares them with the declared α and β (grounding extension, Appendix J).cadl agents-decidedecides one message at the boundary (allow, deny, or escalate), andcadl agents-runreplays a recorded sequence of messages through the reference runtime, with holds, delegations, and audit records (agent governance extension, Appendix G). Both work offline. The gatewayscadl mcp-gatewayandcadl a2a-gatewaymake the same decisions while the agents run (Section 6.1);cadl mcp-approveapproves or rejects a held call,cadl mcp-messagereports another governed message, such as a grant between agents, to a running MCP gateway, andcadl audit-verifychecks the hash chain of an audit log.cadl model-checkandcadl model-export(stochastic model extension, Appendix H) andcadl game-check(strategic model extension, Appendix I) are described under the Verification Engine in Section 6.1.
6.3 Verification Engine
The verification engine is designed to integrate four verification
techniques. The reference verifier implements only the smt method;
the last column shows what cadl 0.3 provides for each technique.
| Verification Technique | Verification Target | Tool Foundation (design) | Reference implementation (cadl 0.3) |
|---|---|---|---|
| SMT-Based Verification | Consistency between contracts. Logical consistency of guarantees. | Z3 [de Moura & Bjørner, 2008], CVC5 [Barbosa+, 2022] | Available with Z3: consistency within each contract and between contracts that share a party, satisfiability of the assumptions of each contract, exclusivity of transition conditions. Whether the guarantees follow from the assumptions is reported as information only. CVC5 is not integrated. |
| Model Checking | Deadlock and livelock detection in protocols. Exhaustive search of reachable states. | UPPAAL [Larsen+, 1997], NuSMV [Cimatti+, 2002] | Not integrated. Deadlock detection is done by structural analysis instead (mutual sends between the branches of a parallel block, barrier reachability, circular fallback chains). Steps written in sequence are ordered and are not treated as circular waits. Livelock detection is planned. The probabilistic models of the stochastic model extension can be exported to PRISM and Storm (Section 6.1). The norms of one contract instance are checked with PRISM 4.11 by cadl norms-check (Section 6.1). |
| Reachability Analysis | Preservation of safety invariants during institutional transitions. Hamilton-Jacobi reachability analysis [Bansal+, 2017]. | hj_reachability [Stanford ASL] | Not integrated. Available instead: reachability, dead-state, and cycle analysis on the regime transition graph, and a satisfiability check of each safety invariant with Z3. The initial regime is inferred from the transitions, and a regime with no outgoing transition is reported as a failure. |
| Compositional Verification | Differential verification when actors join/leave. Impact analysis on existing contracts. | Custom implementation | Planned. |
6.4 Runtime System
The runtime system monitors and controls runtime code generated from CADL descriptions on the execution platform. The main features are as follows; unless noted, they describe design intent:
Contract Monitoring: Monitors satisfaction of assume/guarantee at
runtime for each contract and executes defined violation actions when
violations are detected. cadl 0.3 generates one monitor class per contract
that checks assume/guarantee and records violations.
Institutional Transition Control: Safely executes institutional
transitions in response to environmental parameter changes based on
regime maps. Manages each step of transition protocols and provides
rollback functionality. cadl 0.3 generates a regime controller that
evaluates transition conditions and asserts the safety invariant when
switching; managed transition steps and rollback execution are planned.
Metrics Collection: Computes defined evaluation metrics
(performance, fairness, resilience, etc.) in real-time and displays them
on dashboards. cadl 0.3 generates a metrics collector that records values
and checks targets; a dashboard is not provided.
Logging and Audit: Records all protocol executions, contract
violations, and institutional transitions with timestamps, supporting
post-analysis and accountability. The cadl 0.3 runtime keeps a timestamped
in-memory log of protocol executions, violations, and regime
transitions. Integration with IEC 62853 [IEC 62853:2018]
agreement description databases is planned.