Duolith docs

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

OptionWhy not
Organise by language (all Rust, all TypeScript)Splits one concept, such as styling, across unrelated folders
No formal contextsParallel 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.