Compiler#
After resolving and verifying a ComponentGraph, the Compiler returns an ExecutablePlan separate from execution.
The Compiler does not run the Runtime; it records the capabilities and diagnostics the Runtime needs in the plan.
Compiler’s role#
The Compiler owns the boundary that resolves and verifies a ComponentGraph and returns an ExecutablePlan separate from execution. It does not run the Runtime and records the capabilities and diagnostics the Runtime needs in the plan.
Compilation, verification, and resolution#
Compilation proceeds through contract snapshotting, Resolution, and Verification in that order.
ResolutionRule returns candidates for resolving services, adapters, and schema bindings as proposals for claimed Graph locations.
VerificationRule observes the resolved Graph and returns Diagnostics without changing it.
The shared CompilationRule boundary contains a namespace, name, phase, and apply(RuleContext).
Resolution repeats until proposals converge; conflicts at the same Graph location and undeclared changes become error Diagnostics. Verification checks Graph well-formedness, port compatibility, services, data flow, state effects, lifecycle, and Runtime capabilities.
Executable plan#
ExecutablePlan is an immutable value holding the resolved Graph, Diagnostics, required Runtime capabilities, enabled rules, inserted adapters, and contract snapshots.
Because the plan owns neither an execution position nor current state, the same plan can be passed to RuntimeSession to separate execution from resumption.
When Diagnostics contain errors, whether the plan is accepted as executable input follows the caller’s checks and the Runtime contract.
From verification to execution#
flowchart LR
C[Component] --> N[ComponentNode]
N --> G[ComponentGraph]
G --> K[Compiler]
K --> P[ExecutablePlan]
P --> R[ExecutionRuntime]
Component through Graph is configuration, the Compiler performs resolution and verification, and everything after ExecutablePlan belongs to the Runtime. The Runtime applies StatePatches, events, and commands from plan node results and passes the verified state boundary to the next step.
Construction time and use time#
After the Graph is built, the Compiler reads contract snapshots and generates an ExecutablePlan through Resolution and Verification. The Runtime uses the generated ExecutablePlan and does not repeat Compiler resolution or verification during execution.
Invariants and diagnostics#
Diagnostic is a verification result with severity, code, message, contract path, and resolution hint.
The Compiler does not represent failures only as arbitrary exceptions; it collects multiple issues in a DiagnosticBag for plan decisions.
Typical failures include unknown node endpoints, unconnected required ports, mismatched DataSpecs, missing required services, undeclared state access, and missing Runtime capabilities.
The implementation reports them with codes such as invalid_graph_edge, incompatible_port, unresolved_service, and unknown_runtime_capability.
Compiler rules do not change undeclared Graph locations or arbitrarily change a StructuredRegion execution tree during resolution.
Violations become Diagnostics such as unclaimed_rewrite, conflicting_rewrite, and structured_execution_mutation.
Adapters must state the meaning and losslessness of their conversion and must not bypass port-compatibility checks.
Unresolvable or ambiguous adapters become Diagnostics such as ambiguous_adapter.
Extension points#
See the release-specific API reference for Compiler rule types and import paths. See Framework extensions for extension guidance.