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.
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 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` and `mesh-host` 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-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](../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.
|