hq/01-RESEARCH/006-mesh-from-scratch/code-skeleton.md

effort, updated

effort	updated
006-mesh-from-scratch	2026-08-23

The code skeleton

skeleton.md laid out tiers and repositories. This is the level below: what a module looks like on disk, and — the question that forced a correction — where a given piece of today's catalogue actually lands.

The tier test

A decision procedure, so placement is answerable rather than argued. Ask in order; first match wins:

1. Does it apply state on a machine? → tier 0, inside the host.
2. Can the control plane start without it? If no → tier 1, substrate. Note the verb: start, not function fully. A capability the control plane loses without something is not the same as a thing it cannot come up without — see "becoming self-hosting" below.
3. Does it decide what should be true across nodes? → tier 2, a control-plane context.
4. Is it a way to talk to tier 2, holding no logic of its own? → tier 3, a surface.
5. Otherwise → tier 4, a workload.

Worked example — where postgres ends up

The obvious answer is "twice": once as the mesh's own database in the substrate, once as a hosted database in the catalogue. That answer is wrong, and seeing why fixes something.

Run the test. Can the control plane exist without a relational store? No. Postgres is tier 1. It lives once:

mesh-substrate/store/postgres/

There is no second copy in the catalogue, because the thing that differs between the mesh's own database and a project's database is not the module. It is how that instance is brought up:

	The mesh's own instance	A project's database
Brought up by	the host, from the pinned bundle, with no control plane present	the ordinary delivery and provisioning path
Declared in	mesh-substrate/bundle.yml	the consuming module's requires:
Exists because	the control plane cannot start without it	something asked for it

Same module, two roles. Tier is a property of the module — what must exist before what — and the bundle is a property of the mesh's own instance.

This is also legal under the dependency rule, which is worth checking rather than assuming: a tier-4 workload that requires a database depends on tier 1, which points downward. The inverse — substrate reaching into the catalogue for a module — would not be, and is the shape the naive "twice" answer would have created.

The same reasoning places the rest of the substrate: the bus, the object store, the image registry. Each fails step 2, each lives once, each is pinned. That is the whole substrate: four services, and the deliberate absence of a fifth.

The identity provider was raised as a boundary case and is settled: it is not substrate. The mesh does not require one — tier 2 authenticates its own callers natively, and an identity provider is a service the mesh hosts like any other. The substrate is four services, not five.

The test earned its keep here by turning a vague unease into one answerable question — does the control plane delegate authentication? — rather than a debate about how important identity feels.

Becoming self-hosting — the forge and the registries

Self-improvement means the mesh hosts the things it improves itself with: a forge, an image registry, a package registry. The obvious worry is that these duplicate — a mesh-gitea for the mesh and a gitea for everyone else. They do not, and the reason is worth stating carefully, because it is the same reason the bootstrap keeps failing today.

They are not substrate

Run the test with the sharpened verb. Can the control plane start without a forge? Yes. It comes up, holds inventory, answers questions and manages nodes with the modules it already has. What it cannot do is change itself. That is a capability, not a precondition.

So: forge, image registry and package registry are tier 4 workloads. One module each, in the catalogue, exactly like the media server. There is no mesh-specific copy.

This is not a technicality. It buys a property worth having: if the forge dies, the mesh keeps running. Nodes stay managed, services stay up, only self-modification stops. Putting the forge in the substrate would make losing it fatal, for no gain.

But delivery needs them — is that not an upward dependency?

It would be, stated naively, and that would break the one rule the whole skeleton rests on.

It is resolved the way the constitution already says to resolve it — depend on abstractions, not on concrete dependencies. Tier 2's delivery context does not require the forge module. It declares requirements:

Delivery requires	Satisfied by
a source of record for module code	whichever module provides it
somewhere to publish images	whichever module provides it
somewhere to publish packages	whichever module provides it
somewhere to put build artifacts	the substrate's object store

Tier 2 defines the requirement; tier 4 provides the implementation; the binding is data. The dependency points downward from the provider to the interface, which is legal, and the control plane never names a concrete module.

The mechanism for this already exists and is the mesh's most valuable one: provisioning. A module declares what it provides; a consumer declares what it requires; the mesh binds them. The only new idea is that the control plane is itself a consumer — it has requirements, and they are satisfied the same way a workload's are.

That generalisation is significant enough to need its own study, and is not settled here.

Self-hosting is a state the mesh reaches, not a precondition

This is the part today's mesh gets wrong, and it explains a recurring class of pain.

A first node comes up from pinned external artifacts — upstream images, by digest, carried in the bundle. It has to: the mesh's own registry does not exist yet, and cannot. The mesh at this point is running and manages nodes, and is not yet self-hosting.

Self-hosting is then reached: the forge is installed as an ordinary workload, the mesh's own source moves into it, the registries come up, and delivery's requirements are re-bound from external providers to internal ones. From that point the mesh builds and deploys itself.

Stated as a lifecycle:

pinned external artifacts  ─►  mesh runs, manages nodes
                                      │
                                      │  forge + registries installed as workloads
                                      │  delivery's requirements re-bound
                                      ▼
                               mesh builds and deploys itself

Today's mesh assumes the second state from the first moment. Its source, its packages and its images are all expected to be self-hosted before there is anything to host them — which is why raising a first node needs a script that exists solely to paper over the impossibility, and why that script is the least-exercised path in the system.

Making the transition explicit has a second benefit: it is reversible. A mesh whose forge is broken can re-bind delivery to external providers and keep improving itself while it repairs the forge. Today that escape hatch does not exist, because the dependency is not expressed anywhere it could be changed.

So, concretely

One gitea module. One image-registry module. One package-registry module. Each a tier-4 workload. The mesh's own instances are distinguished from any other instance by what they are bound to, not by being different modules — precisely the same answer as postgres, arrived at by the same test.

The five fates of a module

Research 005 asked whether a catalogue module should be grouped into a domain or leave the repository. Working the tier test across the catalogue surfaces a third answer that neither option covers, and it is the most common one.

Fate	Means	Examples from today
Absorbed into the host	It is not a module at all. It is part of what "managing a machine" means, and belongs in tier 0.	overlay membership, packet filtering, package management, service supervision, container runtime, filesystem management
Substrate	The control plane cannot exist without it. Pinned, host-applied.	relational store, bus, object store, image registry
Control-plane context	It decides something across nodes.	connectivity policy, inventory, delivery, provisioning, observability
Workload module	The mesh hosts it. Grouped per ADR 0009.	media library, desktop session, collaboration tooling
Leaves the repository	A standalone application, per ADR 0015.	the applications identified in research 005

The first fate is the finding. Research 005 measured the reachability cluster — proxy, resolver, firewall, overlay — as the only place in the catalogue where modules genuinely change together under one intent. The skeleton explains why: they are not four modules that ought to be one domain module. They are four facets of one thing the host should own, currently expressed as modules because a module was the only unit available.

Under this skeleton the overlay module and the firewall module stop existing. The host holds membership and applies filtering; tier 2 decides the policy; the swappable backends stay modules. That is a different and better answer than grouping them, and it was not visible from inside the current frame.

It also partly answers research 005's other open question — the fifty modules that co-change with nothing. Several are host concerns rather than domains: package management, container runtime, filesystem tooling. Silence was the right signal after all; the wrong conclusion was that grouping was the only available fix.

What a module looks like on disk

Per skeleton.md Move 4, a module declares parts — independently selectable pieces of desired state — and produces artifacts — things built once per version.

<module>/
    module.yml            identity, what it provides, what it requires,
                          which host profiles it can land on
    parts/
        service/          desired state: container, volumes, exposure
        provisioner/      how it grants its resource to consumers
        migrations/       its own persistent state
        tools/            capabilities it contributes
    artifacts/
        <name>/           source for something built and published

A module with no artifacts consumes an upstream image and builds nothing. A module with no parts is not a module.

Worked through for the substrate's relational store:

mesh-substrate/store/postgres/
    module.yml            provides: database · profiles: [managed]
    parts/
        service/          the container, its volume, its network exposure
        provisioner/      grants a database and role to a consumer
        migrations/       none — it holds no state of its own
    artifacts/            none — upstream image, pinned by digest in bundle.yml

The tree, at file level

mesh-host/                     TIER 0
    cmd/host/
    internal/
        apply/                     reconcile declared state
        inventory/                 what this machine is and can do
        link/                      outbound connection to the control plane
        overlay/                   membership: address, keys, tunnel
        filter/                    packet filtering from tier-2 policy
        packages/                  package management
        services/                  supervision
        containers/                container runtime
        store/                     embedded local state
        profile/                   managed · user · edge
    substrate.lock                 pinned tier-1 descriptor

mesh-substrate/                TIER 1
    bundle.yml                     the pinned set, by digest
    store/postgres/
    bus/<broker>/
    objects/<object-store>/
    images/<registry>/

mesh-control/                  TIER 2
    record/                        the event log contexts integrate through
    inventory/                     nodes · modules · assignments · versions
    config/                        settings · secrets · derivation
    connectivity/                  addresses · resolution · exposure · filtering · certificates
    provisioning/                  grants between modules
    delivery/                      source → artifact → node
    observability/                 health · logs · metrics
    identity/                      agents · humans · services · authorisation
    work/                          tasks · workflows · runs
    knowledge/                     memory · documents · retrieval
    api/                           the one interface surfaces speak to

mesh-surfaces/                 TIER 3
    tools/   web/   cli/

mesh-catalog/                  TIER 4
    <domain>/<module>/             layout as above

mesh-lab/     mesh-sdk/          hq/  (company-scoped — ADR 0019)

What this does not settle

• The identity boundary case. Four substrate services or five.
• Where the record lives. Still the open question from 00-overview.md, and the tier test does not resolve it: the record is needed by tier 2 and is of tier 2, which is exactly the shape that produces a circularity.
• Whether absorbing into the host makes the host too large. Six internal concerns is already a lot for a binary whose whole argument is that it has no dependencies. The counter-argument is that each is small and none can be optional — but this is the skeleton's biggest unproven claim, and it should be tested by writing the host's interface before anything else.
• The migration. Nothing here says how today becomes this.