Genesis is a pivot, public routing is name-agnostic, and five issues the fake registry was hiding #32

2026-09-11T19:46:44Z

jschoubben commented

2026-09-11 19:46:44 +00:00

This carries 242 commits, because main was far behind. Most of it is prior design work that had never landed — ADRs 0044–0065 and the research chain behind them. main is a strict ancestor, so nothing here is divergent, but it is worth knowing before merging that this is not only today's work.

Decisions (both accepted)

ADR 0066 — public routing is name-agnostic. A module contributes a label; a node contributes its public domain; the mesh composes <label>.<public-domain> and interprets neither half. Granted names are published into internal resolution, and an internal authority certifies them by the same path a public one would. Validated live on a four-node bed: one node setting moved an entire domain while another node's routes stayed put, a routed name resolved inside the mesh and was issued a real certificate by step-ca, and TLS verified against that authority with no override.

ADR 0067 — genesis is a pivot. Pinning every image by digest quietly required a registry to exist before the thing that lets a mesh have a registry could start — a dependency the rule created by accident, not a pin. A bare sha256:… now names an image the machine already holds, and genesis runs as a pivot: a temporary control plane installs the registry that makes it permanent, after which the control plane is an ordinary module and the mesh can roll out its own upgrades. Proven end to end: the control plane now runs from a digest the mesh's own registry assigned.

Issues

038 — a provider co-located with its consumer was announced at a port nothing listened on (resolved)
039 — the lab's registry was silently pinning what the catalogue left unpinned (resolved)
040 — the only description of how a mesh is stood up was a test
041 — a credential the mesh took care to seal ends up in the process environment
042 — nothing gives a node an account for a registry

Design

08-connectivity amended for 0066. 04-lab-installation gains a prerequisite found the hard way: a container runtime on the same workstation sets the kernel's forwarding policy to drop, so lab machines get addresses, resolve names, and reach nothing — asserted now by fetching something, never by reading a policy.

Structural checks pass; the reading order is current.

**This carries 242 commits, because `main` was far behind.** Most of it is prior design work that had never landed — ADRs 0044–0065 and the research chain behind them. `main` is a strict ancestor, so nothing here is divergent, but it is worth knowing before merging that this is not only today's work. ## Decisions (both accepted) **ADR 0066 — public routing is name-agnostic.** A module contributes a *label*; a node contributes its *public domain*; the mesh composes `<label>.<public-domain>` and interprets neither half. Granted names are published into internal resolution, and an internal authority certifies them by the same path a public one would. Validated live on a four-node bed: one node setting moved an entire domain while another node's routes stayed put, a routed name resolved inside the mesh and was issued a real certificate by step-ca, and TLS verified against that authority with no override. **ADR 0067 — genesis is a pivot.** Pinning every image by digest quietly required a registry to exist *before* the thing that lets a mesh have a registry could start — a dependency the rule created by accident, not a pin. A bare `sha256:…` now names an image the machine already holds, and genesis runs as a pivot: a temporary control plane installs the registry that makes it permanent, after which the control plane is an ordinary module and the mesh can roll out its own upgrades. Proven end to end: the control plane now runs from a digest *the mesh's own registry assigned*. ## Issues - **038** — a provider co-located with its consumer was announced at a port nothing listened on (resolved) - **039** — the lab's registry was silently pinning what the catalogue left unpinned (resolved) - **040** — the only description of how a mesh is stood up was a test - **041** — a credential the mesh took care to seal ends up in the process environment - **042** — nothing gives a node an account for a registry ## Design `08-connectivity` amended for 0066. `04-lab-installation` gains a prerequisite found the hard way: a container runtime on the same workstation sets the kernel's forwarding policy to drop, so lab machines get addresses, resolve names, and reach nothing — asserted now by *fetching something*, never by reading a policy. Structural checks pass; the reading order is current.

jschoubben added 19 commits 2026-09-11 19:46:45 +00:00

ADR 0056 + connectivity: public routing is name-agnostic, resolved in-mesh, internally certifiable e2afb3e144

A route contribution carries a label; the node carries its public domain; the
mesh composes <label>.<public-domain> and holds no name map. A granted route is
published into internal resolution so anything in-mesh (notably an internal ACME
authority) can resolve and reach it. That authority certifies routed names by the
same path a public one would, differing only in issuer and trusted root.

Records the decision as proposed and amends connectivity SS2/SS3/SS5 plus its Open
list with the lab findings behind it.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 021 — a provider is announced at a name its port is not bound to 315bd7118a

A from:mesh provider is announced (per 018's fix) at the node's private-network
name, but its port is published bound to loopback, so consumers dialing the
announced <node>.internal:port reach nothing. Diagnosed from the lab: DB
consumers that require the database at startup crash-loop; the provider is
healthy on loopback only.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 021: narrow to mesh-assigned ports (bare decl binds loopback, explicit host mapping binds 0.0.0.0) d16b5294f6

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Renumber to issue 038 — 021 is already taken (same-node credentials, closed) and issues run to 037 across branches 9ffe9e97c9

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 038 resolved — corrected root cause (same-node served-port mismatch, not loopback) + fix reference a4440c9acf

The real defect is same-node consumers announced the declared port instead of
the assigned/published one; the loopback observation was a stale pre-0038 build.
Fixed in mesh-control fix/same-node-provider-announced-port (c147a26) with a
regression test.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Renumber the routing record to 0066 — 0056 was already taken 5852b35ab9

0056 is 'the authority is the control plane, not a database', drafted on the
in-progress record chain this branch was cut from before those three records
landed. Two files would have collided at merge, which is the kind of thing that
is cheap now and confusing later. The code written against it still says 0056
and is corrected separately.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

ADR 0067 — genesis is a pivot through a temporary control plane cd1653bfe9

The control plane's image is built from source and pushed nowhere, so it has no
manifest digest; a registry assigns those. Pinning therefore required a registry
before the thing that lets a mesh have a registry could start — a dependency the
rule created by accident. The lab hid it by raising a disposable registry no
production has.

Proposed, not accepted.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 039 — the lab's registry was pinning what the catalogue left unpinned e228355a52

Nine images across seven modules name a tag, not a digest. ADR 0006 forbids it
and the host refuses it by name — and the refusal has never fired in a bed,
because the lab pushed every image into its own registry and rewrote every
reference to the digest it had just assigned. The harness was supplying the
property under test. Found by deleting the harness.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 040 — the only description of how a mesh is stood up is a test f9e129f734

There is no installer. The complete account of standing up a mesh is an
integration test in the lab, and a fixture may invent what it needs — this one
raised a registry no production has and rewrote every image reference through
it, concealing both 039 and the fact that a first node outside the lab had no
bootstrap path at all. The bed being green said nothing about whether a mesh
could be installed.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

0067: the artifact store may require nothing, not merely build nothing 8f23d4b114

029 says a module providing the artifact store may not build artifacts. The
pivot shows that is the narrow case: it may not require anything the store is
needed to deliver. A route-label migration gave the registry a public name and
a route requirement, and at genesis nothing provides a route — nor can anything,
since the routing stack needs images and images need the store.

The same cycle through a door the existing wording did not cover, so the rule is
widened where the bootstrap decision states it, with a check that would catch the
next one where it is written.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Lab installation: a path out, and why the daemon having one is not enough 1ce1c3d4e0

A container runtime on the same workstation sets the kernel's forwarding policy
to drop, and the virtualisation daemon's own accept rules do not override it —
both are consulted and a drop anywhere is the answer. The machines then get
addresses and resolve names, because the daemon's resolver is on the bridge, and
discard every packet to anything real.

The sharpest 'available is not adequate' yet: nothing is misconfigured, nothing
logs, and it presents as every image pull hanging. A workstation that runs
containers is the ordinary case, so it is a prerequisite — verified by reaching
something, never by reading a setting.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Lab installation: the reachability check joins the assertions it belongs with e4a5d9b1d0

The doc's own rule is that the lab verifies capability by outcome, never by
reading a setting. A path out is exactly that kind of claim — a route and a
policy can both read correctly while nothing gets through — so it is asserted by
fetching something, in the table with the rest.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Merge branch 'issue/021-provider-port-published-on-loopback' into design/bootstrap-is-a-pivot 84c95c53af

# Conflicts:
#	03-DESIGN/01-to-be/04-lab-installation.md

Merge branch 'feat/routing-is-name-agnostic' into design/bootstrap-is-a-pivot 56d0dcc4ff

Place the two new records in the reading order, and fix a link the merge moved 423fde8534

Both carried a topic outside the six the index knows, so neither had a place to
be read in — 0067 had none at all. Both are 'the tiers', beside 0036 (bootstrap
ends at a usable mesh) and 0007 (connectivity), which is what they extend.

0067 cited 0041 for tier 0's property; on this trunk 0041 is events, and the
record it meant is 0005. A citation that resolves to the wrong record reads as
corroboration, which is worse than a dead link.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Accept ADR 0066 and ADR 0067 47dc3bc8e5

0066 was proven on a four-node bed before it was ratified: one node setting
moved an entire domain, a routed name resolved inside the mesh and was issued a
certificate by the internal authority, and TLS verified against that authority
with no override. 08-connectivity rests on it and could not while it was
proposed.

0067 records what deleting the lab's registry exposed — that pinning quietly
required a registry before the thing that lets a mesh have a registry could
start — and the pivot that resolves it.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 039 resolved — the operator's images are pinned, and why that is a stopgap c29accd1be

Nine references now name the digest their tag resolved to. What closed is the
immediate fault; the open questions stand, because a digest in a repository is
wrong the moment anybody rebuilds — which is the reason the design wants the
repository to name artifacts and the mesh to hold digests.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

0054 and 0055 join the topic their subject already had cde00e1d5f

Both carried 'model access', which is not one of the six the reading order
knows, so neither had a place in it. 0050 — the record they extend, on the same
subject — is 'what runs on it'.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

Issue 042 — nothing gives a node an account for a registry 26bec28c60

Found by deleting the lab's registry and giving the machines a real path out:
public images fetched, the operator's own could not be fetched at all. There is
no provision for a registry credential, no manifest field, and no step in
enrolment that establishes one.

It applies to the mesh's own store too, which today asks for nothing — a
decision that has never been written down as one, and so reads as an absence.

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

jschoubben merged commit c567410687 into main

2026-09-11 19:56:50 +00:00

jschoubben deleted branch design/bootstrap-is-a-pivot

2026-09-11 19:56:51 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/hq#32