jschoubben
e1febe8e0f
The consolidation left a sparse sequence -- 1, 4, 6, 7, 9, 10, 12, 15, 16, 18, 19, 25, 34, 35, 36, 37, 40, 42, 44, 45, 48, 49, 58 -- where the gaps were only the archaeology of what used to be there. Renumbered contiguously. Renames run in ascending order, so every target number is already free and no two files ever collide. The reference rewrite is one simultaneous pass rather than a sequence of replacements. Numbers moved into slots other numbers were vacating -- the node host went 37 to 16 while the lab went 16 to 9 -- so replacing one at a time would have cascaded and silently pointed things at the wrong record. Seven plain-text references survived the merges as prose rather than links, naming records that no longer existed: the enrolment token, the link boundary, what a declaration is, reachability, the repository structure. Each mapped to the consolidated record that now holds it. Verified rather than assumed: every [ADR NNNN](path) link now has matching text and target, checked across the whole repository, and the checker passes. Frontmatter `consolidates:` lists dropped -- they named records that are gone, and each consolidated record already says in prose what it absorbed.
71 lines
3.9 KiB
Markdown
71 lines
3.9 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 0011](../02-DECISIONS/0011-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 0011](../02-DECISIONS/0011-how-this-repository-works.md) records the repositories the
|
|
monorepo decomposes into. **`mesh-lab` and `mesh-host` exist so far** — the lab is built first
|
|
([ADR 0009](../02-DECISIONS/0009-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 0016](../02-DECISIONS/0016-the-node-host.md)) |
|
|
| `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 0011 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/0006-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/0004-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.
|