Appendix D — Codegen Target Catalog

This appendix enumerates the code-generation targets defined by CADL v0.2 and the mapping to the reference implementation's directory layout. Appendix A §A.9 defines the EBNF for codegen: entries; this appendix pairs each target name with its category, intended artifact, and implementation location in the reference implementation (cadl 0.3).

D.1 Target catalog

Target name	Category	Emitted artifact	Reference-impl module	Command
python	Runtime code	Python package (actors, contract monitors, protocols, regime controller, metrics, runtime)	cadl.codegen	cadl codegen -t python
solidity	Institutional contract	Solidity [Solidity Documentation] smart contracts, one per contract	cadl.codegen.solidity	cadl codegen -t solidity
opa	Institutional policy	Rego / OPA [Open Policy Agent] policies, one per contract	cadl.codegen.opa	cadl codegen -t opa
unity-csharp	Runtime code	Unity C# classes for the lifecycles and monitors of Appendix E	cadl.codegen.unity_csharp	cadl codegen -t unity-csharp
unity	Simulator config	JSON for a Unity-based simulator	cadl.sim.gen_unity	cadl sim-gen -t unity
go	Simulator config	JSON for a Go-based simulator	cadl.sim.gen_go	cadl sim-gen -t go
python (simulator)	Simulator config	YAML for a Python-based simulator	cadl.sim.gen_python	cadl sim-gen -t python
ros2	Runtime node	ROS 2 [Macenski+, 2022] node scaffolds	not implemented in cadl 0.3	—
other name (user-defined)	Plugin	Whatever the user plugin emits	no plugin mechanism exists in cadl 0.3; other target names are rejected on the command line and get a warning in a codegen: entry	—

The name python denotes the runtime-code target in a codegen: entry; the simulator configuration of the same name is requested with cadl sim-gen. The Python simulator config therefore cannot be requested from a codegen: entry in v0.2; use cadl sim-gen -t python. In the reference implementation (cadl 0.3) the target is selected on the command line as shown in the last column; codegen: entries in the file are parsed but do not yet drive generation. From cadl 0.3.9, an entry that names a target the implementation cannot emit gets a warning (D.4).

D.2 Two-tier generator layout

The reference implementation splits codegen into two tiers, reflecting whether the output is code that enforces or executes the contracts or a configuration for a simulator:

src/cadl/
├── codegen/            ← code tier (cadl codegen)
│   ├── *_gen.py        ← Python runtime package
│   ├── solidity/       ← smart-contract enforcement of contracts
│   ├── opa/            ← policy enforcement (Rego) of contracts
│   └── unity_csharp/   ← Unity C# lifecycle / monitor runtime
└── sim/                ← simulator tier (cadl sim-gen)
    ├── ir.py           ← three-layer simulator IR
    ├── gen_unity.py
    ├── gen_go.py
    └── gen_python.py

A single CADL source file MAY declare targets from both tiers in one codegen: block. The processor SHOULD dispatch each target to its tier independently.

D.3 Selection guidance

• Pick unity when the experiment is a multi-agent simulation with graphical inspection, and unity-csharp when contract lifecycles and monitors (Appendix E) are to run inside that simulation.
• Pick python when you want an executable runtime skeleton of the actors, contract monitors, and protocols; ros2 is reserved for driving actual robots and is not implemented in cadl 0.3.
• Pick solidity when the Institution-layer contracts must be enforced on-chain (blockchain deployment).
• Pick opa when contracts should be enforced as policies at API / service boundaries (policy-as-code).

Multiple targets in one file are permitted but the resulting artifacts are independent — the CADL toolchain does not guarantee runtime interoperability between, e.g., a Unity simulator config and a Solidity contract generated from the same source.

D.4 Conformance

A processor is codegen-core-conforming if it supports at least one target from each tier (for example unity together with solidity or opa).

A processor that cannot emit a requested target MUST report a clear diagnostic (for example, "codegen target ros2 is not supported by this processor") rather than silently skipping it.

D.5 Cross-reference

• Appendix A §A.9 — EBNF.
• Glossary — Codegen target definition.