jschoubben
33a00d5656
"control plane" -> controller and "substrate" -> foundation throughout 03-DESIGN, 00-META and the README, with 06-the-control-plane.md and 07-the-substrate.md renamed to 06-the-controller.md and 07-the-foundation.md. The immutable 02-DECISIONS records keep their original wording (and links to them are unchanged) — a term retired here may still appear there, which the glossary explains how to read. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
71 lines
4.3 KiB
Markdown
71 lines
4.3 KiB
Markdown
---
|
|
status: canonical
|
|
updated: 2026-08-23
|
|
---
|
|
|
|
# The Novox repositories
|
|
|
|
The map of where implementation lives. Humans use it for orientation; agents use it for issue
|
|
triage (playbook [`process/03-issues.md`](process/03-issues.md)). The `code:` frontmatter
|
|
field in design documents points at entries here.
|
|
|
|
Repository *names* are recorded; hosts, URLs and owners are not — this repository is public,
|
|
and a forge address is an operational detail (see [`README`](../README.md)).
|
|
|
|
| Repository | Owns |
|
|
|---|---|
|
|
| `hal` | The monorepo — the node runtime, the module catalogue, the delivery machinery, and the bootstrap scripts. Every core module lives here. |
|
|
| `hq` | This repository, under the company organisation — mission, research, design, decisions, issue diagnosis. Company-scoped ([ADR 0019](../02-DECISIONS/0019-how-this-repository-works.md)); the mesh is its first product. The source of truth for *why*. Carries no implementation. |
|
|
| *(one per application)* | Every standalone application, site or side-project gets its own repository, with `module.yml` at the root. Registered with the mesh as a build source; built and deployed by the same pipeline as anything in the monorepo. |
|
|
|
|
## What the mesh becomes
|
|
|
|
[ADR 0019](../02-DECISIONS/0019-how-this-repository-works.md) records the repositories the
|
|
monorepo decomposes into. **`mesh-lab`, `mesh-host` and `mesh-control` exist so far** — the lab is built first
|
|
([ADR 0016](../02-DECISIONS/0016-the-lab.md)); the rest are the
|
|
target, not the present.
|
|
|
|
| Repository | Tier | Holds |
|
|
|---|---|---|
|
|
| `mesh-host` | 0 | **exists.** The node host — one statically linked binary, requiring nothing present ([ADR 0005](../02-DECISIONS/0005-the-node-host.md)) |
|
|
| `mesh-foundation` | 1 | the four pinned services, as declarations |
|
|
| `mesh-control` | 2 | **exists.** The controller and its contexts — one of seven built ([ADR 0006](../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)) |
|
|
| `mesh-surfaces` | 3 | tools, web, cli |
|
|
| `mesh-sdk` | — | the stable spine modules build against — the tool-serving harness, the messaging/event framework, the contracts and core primitives. Holds nothing per-module and nothing volatile ([ADR 0039](../02-DECISIONS/0039-what-the-sdk-holds-and-refuses.md)). |
|
|
| `mesh-lab` | — | **exists.** The lab — scenario lifecycle, networking, placement. Ships to nobody; runs on a workstation. |
|
|
|
|
Tier 4's shape is open, and deliberately so: see ADR 0019 and
|
|
[research 005](../01-RESEARCH/005-domain-grouping/00-overview.md).
|
|
|
|
## What lives where inside the monorepo
|
|
|
|
Named by role, because the layout is itself part of the as-is design — see
|
|
[`03-DESIGN/00-as-is/`](../03-DESIGN/00-as-is/).
|
|
|
|
| Area | Holds |
|
|
|---|---|
|
|
| Module catalogue | One directory per module, each with a manifest. Core modules sit under the mesh's own namespace; everything else at the top level. |
|
|
| Node runtime | The daemon and interactive runtime that every node runs. |
|
|
| Bootstrap scripts | First-node initialisation, joining an existing mesh, and node rescue. |
|
|
| Shared library | The SDK every module builds against. |
|
|
| Pipeline test harness | End-to-end coverage of the delivery pipeline. Currently unbuildable — see [`04-ISSUES/005`](../04-ISSUES/005-pipeline-test-harness-unbuildable/00-report.md). |
|
|
|
|
## Why applications do not live in the monorepo
|
|
|
|
A standalone application in the monorepo is a convention violation, and reviewers reject it.
|
|
The reasoning is recorded in [`02-DECISIONS/0010`](../02-DECISIONS/0015-applications-live-in-their-own-repository.md):
|
|
the mesh installs, provisions for, and ships an application through exactly the same machinery
|
|
whether or not its source sits beside the mesh's own — so co-location buys nothing and costs
|
|
the monorepo's review cadence.
|
|
|
|
## There is no npm workspace
|
|
|
|
Each module is a standalone package that consumes its dependencies from the private registry,
|
|
not from a sibling directory. The workspace was removed after it caused build-versus-development
|
|
divergence — a workspace member importing another resolved to local unbuilt source in the
|
|
pipeline and to a published version in development. Recorded in
|
|
[`02-DECISIONS/0007`](../02-DECISIONS/0014-no-npm-workspace.md).
|
|
|
|
Consequence, and it is a real one: a cross-package change is two steps — publish, then consume
|
|
— and a repository-wide `npm install` does not exist.
|