The catalogue moves to its own repository

Thirty modules the mesh builds, provisions and runs, as manifests — one
per module, flat under modules/. They were in mesh-control/examples/,
which framed the mesh's real modules as illustrations of a control-plane
package; they are neither examples nor the control plane's. The engine
that reads them stays in mesh-control; the data lives here, consumed as
a build source.

Answers the tier-4 question novox/hq ADR 0030 left open — where the
catalogue lives — in favour of one flat repository, which the drop of
domain grouping (seats, claims and tags instead) makes the right shape.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF
This commit is contained in:
2026-09-02 23:51:53 +02:00
commit 86ea181c76
31 changed files with 2010 additions and 0 deletions
+59
View File
@@ -0,0 +1,59 @@
# mesh-catalog
The Novox Mesh catalogue. The modules the mesh builds, provisions and runs — as manifests, one
per module under [`modules/`](modules/).
This is **data, not a control-plane concern**. The manifests describe *what a module is*: what it
provides, what it requires, the seats it claims, the resources the host applies for it. The
engine that reads them — parsing, eligibility resolution, sealing, declaration emission — lives
in the control plane (`novox/mesh-control`, `internal/catalogue`), which consumes this repository
as a build source. The host (`novox/mesh-host`) applies the declarations the control plane emits.
Neither is here.
## What a module is, and is not
A module is one thing the mesh can run, named once, described completely by its manifest. A
manifest names its image (pinned by digest), the resources the host owns for it (directories,
files, the container, the private network it joins), what it `requires` from a provider and what
it `provides` to consumers, and the sealed secrets it needs filled on the machine.
- **Core mesh components are not modules.** The node host, the substrate, the control-plane
contexts and the surfaces are the mesh itself; they ship as their own repositories
(`mesh-host`, `mesh-substrate`, `mesh-control`, `mesh-surfaces`, `mesh-sdk`), not from here.
- **Standalone applications are not here either.** A larger application lives in its own
repository with its manifest at the root, registered with the mesh as a build source
(novox/hq [ADR 0010](https://git.novox.be/novox/hq)). This repository holds the modules the
mesh maintains as its shared catalogue; an application the mesh merely hosts keeps its manifest
beside its own code.
So there is one home for the catalogue the mesh owns, and every application that runs *on* the
mesh rather than being *of* it carries its own — both reach the pipeline the same way, as a
registered source.
## Layout
```
modules/<name>.json one manifest per module
```
Flat, because the catalogue's shape carries no meaning: a module is found by its name and
described by its manifest, and what relates two modules — a shared seat, a claim, a
provider/consumer edge — is data inside the manifests, not a directory the tree encodes
(novox/hq, the domain-grouping question closed in favour of seats, claims and tags).
## The manifest contract
The shape a manifest must satisfy is owned by the control plane's catalogue engine and is what
validates a manifest before a machine ever sees it — a stray key, a consumer contributing the
wrong provision field, an image that nothing builds. That validation belongs with this
repository and is being re-homed here from `mesh-control`; until it is, the pipeline is the
gate — it builds each module and refuses a manifest it cannot resolve.
## Where the reasoning lives
Design and decisions are in [`novox/hq`](https://git.novox.be/novox/hq):
- `02-DECISIONS/0002-everything-is-a-module.md` — one unit, no second mechanism
- `02-DECISIONS/0010-applications-live-in-their-own-repository.md` — why applications are not here
- `02-DECISIONS/0030-the-repository-structure.md` — the repositories, and the open tier-4 question this repository answers
- `03-DESIGN/00-as-is/10-module-catalogue.md` — the catalogue's shape, and what it records