jschoubben
333356cff3
Jochen asked whether the order made sense. It did not -- it followed when things happened to be decided, which after consolidation is fictional anyway since record 5 alone folds decisions taken across a week. Concretely wrong before: the domain statement sat at 8, after five engineering rules; the constitution was scattered across 5, 12 and 17; the tiers landed at 15, 16, 21 and 22 with process records in between. Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what runs on them and how it gets there (9-10), how it is built (11-16), how it is checked (17-18), how we work (19-23). Two things made this safe rather than free. It is a permutation, not a compaction, so the renames go through temporary names -- otherwise two files want one slot and one is lost. And the reference rewrite is a single simultaneous pass, because almost every number moved into a slot another number was vacating; replacing one at a time would have cascaded and pointed things at the wrong record while still resolving. Verified: 284 [ADR NNNN](path) links across the repository, all with matching text and target. The ordering principle is now stated in 19 rather than left implicit -- the repository already said "the numbering is the flow" about its folders, and there was no reason for the records to be the exception.
3.9 KiB
status, updated
| status | updated |
|---|---|
| canonical | 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). 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).
| 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); 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 records the repositories the
monorepo decomposes into. mesh-lab and mesh-host exist so far — the lab is built first
(ADR 0016); 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) |
mesh-substrate |
1 | the four pinned services, as declarations |
mesh-control |
2 | the control plane and its contexts |
mesh-surfaces |
3 | tools, web, cli |
mesh-sdk |
— | contracts shared across tiers |
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.
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/.
| 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. |
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:
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.
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.