jschoubben
77f3a4cea7
Every remaining cluster merged. Each was one design that had been split across
several records because it was worked out over days rather than at once.
the node host 8 -> 1 applies not decides, depends on nothing,
per operating system, root service, the
launcher, episodic, what a declaration is,
actions from the bundle only
a node and how it joins 4 -> 1 what a node is, joining, the link as
security boundary, the enrolment token
modules and the graph 7 -> 1 everything is a module, no domain modules,
three edges, provisioning, the core library
substrate and control 6 -> 1 the test, seven contexts, one control plane,
plane the authority is not a database, the named
products, the pinned bundle
connectivity 3 -> 1 a route is a grant, reachability declared,
filter rules
delivery 5 -> 1 reconciliation not a pipeline, artifacts,
the three silos, a failed step, the verdict
the lab 5 -> 1 (earlier)
how this repository 10 -> 1 (earlier)
works
Nothing was dropped. Each consolidated record carries the reasoning of the ones
it absorbs -- the measurements, the incidents, the alternatives rejected --
because that reasoning is the only reason to keep a record at all. What is gone
is the fragmentation: eight files to read to understand tier 0, when tier 0 is
one component.
The four superseded records went too. They existed to point at their
successors, and the successors now contain what they said.
The checker made this safe. Each merge left dangling links -- 38 files after
the host merge alone -- and it named every one. Nothing was found by reading,
and a manual pass would certainly have missed some, including references inside
AGENTS.md which every session loads.
6.0 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | ||||
|---|---|---|---|---|---|---|---|---|
| as-is | implemented |
|
2026-08-23 |
|
Modules, manifests and features
Everything the mesh installs is a module: a directory with a manifest. There is no second mechanism.
What a manifest declares
| Declares | Meaning |
|---|---|
| Identity | Name and version. Version is owned by the builder — a hand-edited version is a defect, and reviewers revert it. |
| Environment | Every variable the module reads, with how each is produced: a static default, a generated secret, a value pulled from the node's own record, or a template composed from the others. A variable not declared here is invisible to the mesh and will not be generated, injected or audited. |
| What it provides | The resource type this module can provision for others, and the network on which it is reachable. |
| What it requires | Resources it needs from other modules, and the mapping from each resource's connection fields onto its own environment variables. |
| Service shape | The primary container, and the data directories that must exist with the right ownership before it starts. |
| Exposure | The public names this module's interfaces answer on, declared portably so the reverse proxy configuration can be generated rather than written. |
| Images | Container images this module builds, so the pipeline builds and publishes them before publishing the module. |
Features are the unit of work
A module is not the unit the pipeline addresses. A feature is.
A feature is a kind of content a module can carry: a service, a set of capabilities, a long-running process, managed configuration files, migrations, firewall rules, an installable application. One module can carry several.
Features are detected from directory contents, not declared. A module with a capabilities directory has that feature; a module with a daemon directory has that one. An explicit declaration was supported and is now discouraged, because a declared list and the directory it describes drift, and the directory is the one that is true.
Every pipeline command and event names a feature. There is no per-module build.
What detection costs
Detection makes the manifest shorter and the truth singular, and it makes the directory structure load-bearing in a way that is not obvious from reading a manifest. Renaming a directory changes what a module is, silently. The recurring failure is a hook named for a feature the module does not carry: it is skipped without complaint, and the change it was supposed to make simply never happens.
An unknown key in a manifest is likewise accepted in silence — which is how a firewall rule
can appear to restrict a port and restrict nothing (see
04-ISSUES/003).
Kinds of module
The kinds are not a type system — they are what the detected features add up to.
- A service module carries a container definition. It gets a runtime directory, generated environment, data directories, and is started under supervision.
- A capability module carries capabilities and no service. It contributes what a node can do, locally and to its peers.
- A flag module carries nothing but a manifest. Its presence in a node's assignment is the entire content: it gates behaviour elsewhere.
- Combinations are ordinary. A database module is a service and a capability provider and a provisioner.
Selections
A module can ship variants of the same feature and a node takes the one that fits it — a build for one accelerator or another, a configuration for a public node or a private one. The artifact stays selection-blind; the choice is a property of the assignment, held in the mesh database.
This is one of the areas where behaviour has repeatedly diverged from intent, in both directions: selection files that were never packaged into the artifact at all, and a stale staged override on a node that silently won over the newly selected one. Both classes are recorded in the knowledge base; both presented as "the change did not apply" with no error.
Dependencies between modules
Modules depend on each other, above all on the shared library they all build against. There is no workspace (ADR 0007): each module is a standalone package consuming published dependencies, including the mesh's own.
The pipeline resolves modules into dependency levels and completes a level before starting the next, so a module always builds against its dependencies as just published.
The cost is a publish-and-consume round trip for every cross-package change, and the absence of
any repository-wide build. One thing that assumed a repository-wide build has stayed broken
since (see
04-ISSUES/005).
Persistent state
A module that owns state owns its migrations: numbered, written in the module's own language, compiled with it, frozen once they have run anywhere, and idempotent so that re-running is safe (ADR 0006).
Two kinds exist and the distinction matters: migrations against the module's own local state, and migrations against a provisioned resource, which run on the node that consumes the resource rather than on the node that built the module.
A documented rule with no enforcement
Every module exposing capabilities is documented as required to declare the mesh's core runtime as a dependency. Zero of the catalogue's modules do.
This is recorded here rather than quietly corrected, because it is the clearest instance of the rule this repository states about itself: a rule whose enforcement does not exist is indistinguishable from a wrong one, and costs more, because people believe it. Whether the rule or the catalogue is wrong has not been decided.