Composition

A program is a directory of chapters. Each chapter's boundary is a contract seam; other chapters see the boundary, not the implementation.

> Uses: `fetch_price`

declares a dependency. The runner compiles dependencies first, in topological order, and verifies each chapter against its own contract, black box.

Why this is sound

Composition is sound if and only if every boundary is contract-verified. Chapter B can call chapter A on the strength of A's contract, without knowing how A is built or what language A compiled to. This is the microservices/IDL model applied at function granularity.

Mechanically today, artifacts land in build/ together, so B's artifact imports A's by module name. Cross-language calls go through the same generated adapters the judge uses.

Trickle-down in practice

Verified lower chapters become stable context for higher chapters: the compiler is handed the dependency's boundary when it generates the dependent. Dependencies compile first, dependents after, so verified behavior flows upward and downstream code cannot silently diverge.

The healing proof

The strongest composition result in the repo, proven live rather than staged:

• provision_service uses validate_config
• a real pydantic v1 to v2 pin bump made validate_config's old artifact fail with a hard ImportError, which made provision_service fail too
• regenerating only validate_config from its unchanged .angl chapter made both chapters pass again
• provision_service.py stayed byte-for-byte identical

dependency changed
one generated file was replaced
downstream generated code stayed byte-identical

The seam held because the seam is a contract, not a shared implementation detail.

Polyglot programs

Because every seam is a contract, chapters in one program can compile to different languages:

picnic_normalize.angl -> Python
picnic_menu.angl      -> Node
picnic_pack.angl      -> Ruby
picnic_plan.angl      -> Python

picnic_plan calls the other chapters through Uses; it does not contain all those languages itself. The incident-escalation demo goes further, crossing Python, Node, Ruby, Go, Rust, and TypeScript generated artifacts in one pipeline.