jschoubben
5c81f1170c
Research 063 graduated into ADR 0429 and this design (playbook 02 step 3). The design names the parts and the releases; its other sections hold until each release is delivered and are rewritten as each is prepared (issue 1130). The words the plans use are marked as going at release 6, not struck: they stay true until that release is delivered.
4.9 KiB
status, updated
| status | updated |
|---|---|
| canonical | 2026-09-24 |
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. |
migration |
Private. The record of one installation replacing the predecessor mesh with this one: the runbook, a dated log of every step and what it cost, the per-service data procedures, the readiness checks, and the scripts. Private because it is the opposite of this repository in every way that matters — it names machines, addresses, ports and paths, because a procedure that cannot be followed is not one. Where hq asks what did we decide and why, that repository answers what happened on the machines, in what order, and what to do next. Its HANDOFF.md is where somebody picking the work up starts. |
What the mesh becomes
ADR 0019 records the repositories the
monorepo decomposes into. mesh-host, mesh-controller, mesh-catalog, mesh-lab, mesh-sdk and mesh-tools exist
so far — the lab was built first (ADR 0016). The tiered
decomposition below is the planned shape; the repositories built to date do not map onto it
one-for-one — mesh-catalog, mesh-sdk and mesh-tools exist where the table names
mesh-foundation and mesh-surfaces, and reconciling the two is itself still ahead.
| Repository | Tier | Holds |
|---|---|---|
mesh-host |
0 | exists. The node-engine — one statically linked binary, requiring nothing present (ADR 0005) |
mesh-foundation |
1 | the four pinned services, as declarations |
mesh-controller |
2 | exists. The controller and its contexts — one of seven built (ADR 0006) |
mesh-surfaces |
3 | tools, web, cli |
mesh-sdk |
— | the stable spine modules build against — the tool-serving SDK harness, the messaging/event framework, the contracts and core primitives. Holds nothing per-module and nothing volatile (ADR 0039). |
mesh-lab |
— | exists. The lab — scenario lifecycle, networking, placement. Ships to nobody; runs on a workstation. |
mesh-delivery |
— | the delivery domain: the parts that build, check and deliver a change by watching and writing keys on the bus, nine modules each whole in it, prefixed mesh-delivery- (ADR 0429). Made by the forge module from its config (ADR 0428). |
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 ADR 0015: 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 ADR 0014.
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.