One-node bed: SDK-by-version, rename, and the store/broker upgrade proofs #27

2026-09-16T21:20:32Z

jschoubben commented

2026-09-16 21:20:32 +00:00

This session's work, proven 22/22: the one-node bed drives genesis→self-upgrade, the mesh-controller/foundation rename, and the Phase 3 store/broker upgrade-window steps (S1/S2).

https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx

This session's work, proven 22/22: the one-node bed drives genesis→self-upgrade, the mesh-controller/foundation rename, and the Phase 3 store/broker upgrade-window steps (S1/S2). https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx

jschoubben added 26 commits 2026-09-16 21:20:32 +00:00

Raise machines that are somebody, and a bed that hands over nothing babf08b9f8

Every machine in a bed is a clone of one base image, so all of them booted with
the same /etc/machine-id. systemd's DHCP client derives its client identifier
from that file and dnsmasq keys leases on the identifier rather than the MAC, so
four machines with four distinct MACs were handed one address and the host kept
one ARP entry for it. Whichever machine last answered an ARP request received
everybody's replies.

This is the fault behind every run lost to "flaky lab DNS": resolution that works
two times in three, pulls that succeed on a retry, and one machine out of four
being fine while the rest have no path at all. It survived an earlier diagnosis
that blamed resolver ordering, because reordering resolvers on a machine that has
just won the ARP race looks exactly like a fix.

Each machine is now given its own machine-id before the uplink lease is asked
for, and a check after addresses are applied refuses to go on if two machines
took the same one — the positive control this never had, since the fault is
invisible where it happens and unrecognisable where it surfaces.

The egress check also now demands five consecutive lookups rather than one. A
single answer is what let a machine resolving one query in three pass and then
die twenty minutes later inside a pull.

And fresh-mesh: whole-mesh-full's topology with genesis-single's honesty. The
four-machine bed loads thirty-four of the mesh's own images onto its machines
from the workstation because it does not build them, which is a shape no real
installation has and the same fiction the lab removed when it deleted its own
registry. This scenario names no images at all. The machines pull what is public,
the installer builds the control plane, and the mesh builds the rest — including,
last and deliberately, a module on a machine that did not build it.

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

A manifest the control plane can open, and stop swallowing the failure when it cannot 4ef0a19053

mesh-control runs in a container, so a manifest pushed to the machine is not a
file it can read; `module add` said so plainly and it was briefly taken for a
missing manifest. It is copied the last step of the way now.

The base's registration was doing this too, and its failure was swallowed by a
bare catch on the reasoning that the module might already be known. The step
passed regardless — a base with nothing to stand on builds whether or not the
mesh holds a record of it — and the fault surfaced one step later, where the
record was needed.

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

Give the module the broker it asks for, rather than a module that asks for nothing f04911a763

The mesh refused to place amqp-ping: nothing provides amqp. That refusal is
right. The substrate raises a broker, but as a bundle resource — plumbing, not a
module the mesh has a record of — so it offers nothing to anything, and a module
wanting a broker wants one in the graph.

lavinmq is that module and needs no building, its image being upstream, so this
is a register and an assign. The alternative was to pick a module with no
requires, which would have passed by testing less.

Also: the control plane's image has no /tmp to copy a manifest into. Root does.

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

Build each repository from its own ref, and build the provider c3d5ec1d55

lavinmq needs building now, so the step that assigns it builds it first.

And the ref is per repository rather than one value for all of them: a change
under test lives in one repository, and building the others from that branch
would prove it against itself.

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

Name the container, and issue the account 9146f30859

Waiting for "a container whose name contains lavinmq" was satisfied by the
broker — lavinmq, up and healthy — while the thing under test, the module's own
runtime mesh-lavinmq, crash-looped beside it. The step went green and the fault
was found by reading docker ps by hand. Containers are named exactly now, and a
failure prints that container's own last words.

And lavinmq gets a broker account, which it was never issued. Without one the
mesh still fills the secret the module declares it owns, with a generated value,
so the runtime starts, fails to parse a password as a credential document, and
loops on a JSON syntax error that mentions no missing account.

The two module-issue calls written .catch(() => {}) are not. That pattern has now
hidden three separate faults in this file.

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

A one-node mesh, and twelve things that have to be true of it 7641bb2059

The common case, and the one that was never tested as a whole. What existed
asked whether four machines converged; it never asked whether ONE machine ends
up holding a mesh.

The order was wrong too. Three machines were enrolled second, into a mesh that
could not yet produce a single module, and that was reported as though something
had been shown. 17-raising-a-mesh is explicit: genesis ends with a mesh that
RUNS, and what remains after the core modules are built is "adding machines".
So the core comes first and machines arrive last — here, not at all, because a
second node is only meaningful once the first is complete.

Three things were missing entirely and nothing complained, because nothing asked:
the mesh never built its own catalogue, never had a store of its own for that
catalogue to use, and never rebuilt its own control plane through the module
path.

And four checks that were absent rather than failing:

  - it can describe itself — status, module list, plan --json, and the
    catalogue's five tools ASKED rather than observed. A container being up was
    being read as the catalogue working, which is the same error as matching a
    container by substring and finding the wrong one.
  - its networking is what the modules asked for — default closed, ssh open,
    declared ports open, .internal names written, module networks present. Left
    out altogether, which is hard to defend given the firewall work this week.
  - a change to a module's source reaches the machine on its own. The capability
    the migration depends on.
  - it comes back after a reboot. Never once tested; the lab had no way to
    restart a machine, because nothing had ever needed one.

Machines are named by role now — anchor, home-server, workstation, laptop — not
after the operator's own nodes, which made test output and real state hard to
tell apart.

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

Genesis makes six claims; assert them separately 2f470f27b8

Genesis is twelve steps and was reported as one line, so a failure said nothing
about which claim broke and a pass was one tick standing in for six things being
true: the substrate up, the control plane built rather than handed over, the
pivot finished, the registry serving what was published into it, the machine
enrolled with an agent actually running, and the builder installed as a module.

Each is asked of the machine rather than read from the installer's own output.
The installer saying it published an image and the registry serving one are
different facts, and only the second matters.

And the catalogue is invoked by its real entrypoint. 'mesh-tools' is not on PATH
in the runtime image; the image runs 'node dist/main.js', and the invoke mode is
missing from the header comment that says there are three modes.

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

A plan with codes, stated up front and reported against 572aae2eb4

Steps were identified by their own sentences, so 'which one failed' meant reading
prose, and rewording a step silently made it a different step with no history.
Each now carries a stable code: R for raising the mesh, P for it being able to
produce, U for something being used on it, V for verifying what it says about
itself, E for enduring — a change following on its own, and coming back after the
machine stops.

The plan is data, printed before anything is attempted, so a reader knows what
the run intends to establish rather than inferring it from what happens to be
printed. The run ends with a table and a JSON report, and distinguishes SKIP from
FAIL: a step whose dependency failed was never asked, which is not the same as a
step that was asked and said no.

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

Ask the catalogue as the only thing that is allowed to 3690e17cf4

Invoking a tool from inside the module's own container is refused: its account is
scoped to what it emits and consumes, and a tool call needs a reply queue. Filed
as novox/hq issue 049 — the account is right, the request is reasonable, and
nothing can make it.

Until that is decided the caller is the substrate's bootstrap admin over the
broker's loopback, reached by joining its network namespace the way genesis
reaches a substrate container. Recorded in the step as the workaround it is,
rather than left looking like how a mesh is meant to be asked a question.

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

Split describing the mesh from the catalogue holding it d0d56782a0

Two claims were bundled in one step: that the control plane can describe the mesh
correctly, and that the catalogue holds a complete record of what was built. The
first passes; the second is novox/hq issue 050. Bundled, one open fault stopped
three later steps from ever being attempted, which is exactly the information the
run existed to produce.

The catalogue is now measured against what the control plane ordered rather than
against a list written in the test — a catalogue cannot know what it was never
told, so it has to be compared with something that does.

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

Assigning networking is not being on the network 6b482ee7dc

N1 assigned the module and stopped, and the mesh wrote a names file with no names
in it. That is correct behaviour, not a bug: a node with no address on the
network has no name, because a name resolving to nothing is worse than no name —
a connection to an address that does not answer hangs, where a name that does not
resolve fails at once and says so.

The missing act is placement. Assigning installs the module that answers how
machines reach each other; placing says where this machine is on the resulting
network. The four-machine test did both and this one did neither, which is how
the distinction stayed invisible.

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

The packet filter is a module too, and it was assigned to nothing f132a4bcbd

V3 asked whether the machine's networking is what the modules asked for and found
no mesh firewall table at all. The firewall is a module — it claims the
packet-filter seat, installs the filter and loads the rules — and like networking
before it, it had never been assigned to anything.

So every rule the mesh generates from module listen declarations had never been
applied to any machine in this test. Not open by accident: a mesh where that
whole generation has never run.

Assigned separately from networking because they answer different questions. One
is how machines reach each other; the other is what may reach this one.

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

Register the firewall before assigning it 475fd9a088

'no module of that name: firewall'. The networking family is computed by the
control plane, so the mesh knows those exist without anyone saying so; the
firewall is an ordinary catalogue module and has to be added like any other.

That is a second way for a module to be absent, and a less obvious one than
being present and placed nowhere — the mesh does not hold it at all, so nothing
can even report it unassigned.

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

E1 moves the module's source for real 9b8b21ac17

Reading the branch head and telling the mesh the source had moved there named the
commit it had just built, so the mesh correctly answered that everything was
current. Naming a different commit would not work either: staleness compares
artifacts, not commits, deliberately, so that editing a comment in a shared base
does not rebuild everything standing on it to arrive back where it started.

So the step makes a real change and pushes it, and asserts the module comes back
on a DIFFERENT artifact than it had. A test that writes to a branch is worth
knowing about; the alternative is proving the loop by telling the mesh something
untrue.

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

Containers coming back is not the mesh coming back 3ebf0bb38c

E2 asserted that every container was running after a reboot and stopped there.
The runtime restarts containers by itself; what makes a machine part of a mesh is
an agent listening for what it should be. A machine whose containers returned and
whose agent did not looks healthy and cannot be told anything.

The installer is explicit that a host started the way the lab starts it does not
survive a reboot, so this may now fail — and if it does, it is the packaging gap
the design already records under what is not yet true, not a fault in the mesh.
Better a named failure than a pass that means less than it appears to.

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

Verify every resource kind, not the one I kept looking at 1425f5e7d4

Every check in this file asked about containers. A container is one resource kind
out of ten — directory, file, user, network, access, archive, service, package,
container, action — and a module is far more often the others: the firewall is a
package and a service, the mesh's names are a file, a run-once step is an action
or a container that exits. Asking only about containers is how a module with no
container at all went unnoticed.

V4 takes the declaration the machine was actually sent and verifies each resource
in it, by kind, on the machine. Nothing is hand-picked — whatever the installed
modules declared is what gets checked.

And it reports which kinds were never exercised, rather than counting their
absence as success. A vocabulary this test never sees is a vocabulary this test
says nothing about, and saying so is the difference between a passing run and a
meaningful one.

The service check accepts a one-shot that has done its work and reports inactive,
which is the reading that made the firewall module look broken on every machine
for months.

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

A run-once step leaves nothing to ask, and V4 asked anyway fce554d150

V4's first run reported a working mesh as broken: it asserted that lavinmq's
run-once bootstrap container existed, and the host removes an exited run-once
container on purpose — so a later apply is not confused by a stopped one, keeping
the record that it ran in its own store instead.

So the check asserted the opposite of correct behaviour. The step had run; it is
why the broker came up configured.

Counted as unverified now rather than assumed good. What would verify a step is
the host's own record of having run it, and this walks the machine rather than
the host — so the honest answer is that this check says nothing about steps, and
it now says so.

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

The lab names the modules as the catalogue does e451a9191a

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

The lab answers the installer's questions the unattended way 09a22de78f

The installer asks where a human must choose, and this bed has no human — so
every choice arrives as a flag, and a required choice with no flag is the
installer refusing, which is the behaviour rather than a lab problem.

Both choices have one option today, so the flags are redundant on purpose: the
day a second filter exists this bed keeps working instead of refusing, and
choosing becomes a thing it visibly does.

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

The lab stocks the full catalogue, not the bootstrap three 61abeb7f6b

Phase two of the installer reads each module's manifest from --catalog, which is
documented as a checkout of the catalogue repository. Genesis stocked it with
only the three modules the pivot needs, so step 14 failed reading postgres's
manifest — a file nobody had put there.

The installer code is right: --catalog is meant to be a full checkout. The lab
was the shortcut. It now copies the whole modules tree once (tar, push, extract)
rather than three files, and still checks the bootstrap three are present so a
missing one fails at preparation rather than at step 8. Production's equivalent is
an operator with a full checkout, or the installer cloning the repo.

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

The bed publishes the SDK before the base build eff91742e8

genesis passes --sdk-source so the installer raises the registry and publishes
the SDK ahead of the base, which now resolves it by version.

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

The one-node bed places at the site it operates, and tolerates the CP recreating f57e05e75e

Genesis places the anchor at the same site the test re-places it at, so that step
is a no-op rather than a change that recreates the control plane. And mesh() —
which runs commands inside the control-plane container — retries a transient
"container not running", because the control plane is a live mesh-managed
container the mesh recreates when its declaration changes (e.g. its first
.internal add-host). Also passes --sdk-source/--tools-ref for the SDK build.

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

The one-node bed supervises the host as a service, so reboot is a real check 49b80d8516

Installs the shipped nox-mesh-host launcher and unit in the machine and lets the
installer's --host-service start and enable it, instead of --host-in-background
which cannot survive a reboot. E2 now proves the mesh comes back on its own.

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

Rename mesh-control -> mesh-controller, substrate -> foundation 5d6e8fbe7a

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

Phase 3.2: lavinmq declares no network — it adopts mesh-broker 70c1545161

The V3 networking check asserted a `lavinmq` docker network exists, from the
two-server world. The module now adopts the foundation's broker rather than
raising its own on a private network (issue 051, WBS 3.2), so only the
consumer's own network remains.

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

Phase 3.3/3.4: prove the store and broker upgrade in place, through the window 440e2653b2

S1 upgrades the store: a spec change recreates mesh-store (the server the control
plane reads from), and asserts the data on the named volume survives and the
pool reconnects — the stated window. It also asserts postgres/lavinmq are now
source-tracked modules the mesh can report behind (3.4), the question that could
not form before adoption. S2 does the same for the broker, the harder case: the
push that upgrades it travels over it, so it proves the mesh reconnects to the
bus it just replaced.

Issue 051 (WBS 3.3, 3.4).

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

jschoubben merged commit 03d036cbeb into main

2026-09-16 21:25:34 +00:00

jschoubben deleted branch feat/a-bed-that-hands-over-nothing

2026-09-16 21:25:34 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/mesh-lab#27