Compiler Architecture#

This directory contains current contracts that span compiler crates, generated runtime services, target adapters, or standard-library implementation modules. It does not define public language, platform, tooling, or standard-library behavior.

Public language, platform, CLI, diagnostic, and editor behavior belongs to spec/. Exact standard-library declarations and their observable behavior belong under std/. A workspace crate's private mechanism belongs in that crate's colocated README.md. Work order, rejected migrations, qualification evidence, and release history belong under development/history/.

Reading Order#

1. 1. Architecture Overview for the program pipeline, side authorities, and dependency rules.
2. The relevant workspace crate README for one crate's exported contract and private responsibilities.
3. One cross-responsibility contract below when a decision crosses those local boundaries.
4. Historical milestones or reviews only when the reason or qualification evidence is needed.

Pipeline#

These documents own handoffs between semantic products and tooling projections:

• Checked Program
• Declaration Diagnostics
• Target, Executable, and MIR Programs
• Machine Program and Native Target
• Incremental Computation
• Semantic Presentation

Semantic Contracts#

These documents own compiler-wide relations that more than one pipeline stage consumes:

• Execution Contracts
• Value Provenance
• Compile-Time Callables
• Erased Callables

Representations#

These documents own one representation as it travels from syntax or checked semantics to stored layout and native execution:

• Tuples
• Floating-Point Values
• Unicode Scalars
• Static Unicode Data

Runtime Integration#

These documents own boundaries that cross standard source, compiler products, runtime services, target adapters, and resource lifecycles:

• Asynchronous Computation
• Blocking Jobs
• Asynchronous Byte Streams
• Filesystem and File I/O
• Processes
• Networking
• HTTP Client
• Secure Transport
• HTTP Service

Standard-Library Implementation#

These are internal implementation boundaries, not public API guides:

• Source Layout
• Associative Collections
• JSON

Grammar-derived test coverage belongs to development/compiler/tests/grammar.md. Performance methodology belongs to development/benchmarks/. Repository maintenance workflow belongs to development/README.md.

Information Ownership#

Information	Sole owner
Public language, platform, CLI, diagnostic, and editor behavior	spec/
Exact standard-library declarations and declaration documentation	each std/**/index.nct
Longer observable standard-library behavior	the guide assigned by std/README.md
Compiler-wide dependency direction and cross-responsibility contracts	this directory
One crate's inputs, outputs, private split, and local invariants	that crate's README.md
Exact Rust APIs and dependencies	source, rustdoc, and Cargo manifests
Current work and blockers	development/TODO.md
Work order, design findings, and qualification evidence	development/history/

Architecture documents state current authorities, information flow, lifecycle, and invariants. They do not retain delivery phases, completed gates, or superseded alternatives as current design.