jschoubben
41637befff
One name per thing, per the HQ glossary: the module/container/image/binary/repo becomes mesh-controller, the seat the-controller, and the store+broker pair the foundation (embedded base bundles, default template and example lock renamed with their go:embed directives). No behaviour change — a pure vocabulary rename. Claude-Session: https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
60 lines
3.3 KiB
Markdown
60 lines
3.3 KiB
Markdown
# 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-controller`, `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 foundation, the control-plane
|
|
contexts and the surfaces are the mesh itself; they ship as their own repositories
|
|
(`mesh-host`, `mesh-foundation`, `mesh-controller`, `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-controller`; 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
|