jschoubben
545d038198
hq cannot hold the migration's operational record — it names machines, addresses and paths, and this repository is public — but it can say where that record is, which is what this map is for. Asked for by the operator, who had to be told.
5.2 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 host — 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 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. |
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.