0002. Organise the repository into bounded contexts
- Status: Accepted (provisional)
- Date: 2026-11-14
- Decided by: Mik, on recommendation
- Planning item: D36
Context
The framework spans a compiler, a runtime, a kit, platform code in three languages, editor tooling and an agent layer. It will be built by several agents at once, each with a narrow context. Without explicit boundaries, agents collide on files and words drift between areas.
Decision
The repository is split into 15 bounded contexts (Language, Syntax, Analysis, Styling, Emission, Runtime, Navigation, Kit, Platform, Modules, Tooling, Editor intelligence, Editor shells, Agent surface, Delivery), plus Foundations for root files, docs and tools. Each has owner paths in OWNERS.yaml, a public surface, and its own nested AGENTS.md. Contexts communicate only through the contracts in docs/plan/contracts.md. The context map is in docs/explanation/domain.md.
Navigation lives inside Runtime's and Analysis's paths for now; it gets its own folders when there is enough code to justify them.
Alternatives considered
| Option | Why not |
|---|---|
| Organise by language (all Rust, all TypeScript) | Splits one concept, such as styling, across unrelated folders |
| No formal contexts | Parallel agents collide, and there is no basis for ownership checks |
Consequences
Every brief names one context and its owner paths. A change spanning contexts is split into one pull request per context, producer first.