# 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