Merge pull request 'Adopt genesis's bus through the bus's planned step, its streams snapshotted first (issue 590, hq ADR 0333 §3)' (#108 ) from fix/590-adopt-the-bus-as-its-planned-step into main

Adopt genesis's bus through the bus's planned step, its streams snapshotted first (hq issue 590, ADR 0333 §3)
The broker step sent the nats module with a plain push, and the controller refuses a push that would replace the bus: that is a planned step, bus upgrade, which snapshots the streams first and checks them after (ADR 0236). Genesis stopped at step 18. The step now snapshots every stream with the module's own snapshot program (no backup holder exists yet to be asked), asks bus upgrade with that snapshot and why, says the one restart, and waits until the bus runs the module's image, answers, and the controller ends the step done. The bundle's bus runs the release the module's image is built on (2.11.17, by the same digest, where it ran 2.10.29), so the step changes no server release and is said reversible.
2026-10-13 11:11:41 +00:00 · 2026-10-13 11:47:10 +02:00 · 2026-10-13 09:23:04 +00:00 · 2026-10-13 11:13:44 +02:00 · 2026-10-13 09:08:59 +00:00 · 2026-10-13 10:59:45 +02:00
22 changed files with 1039 additions and 122 deletions
@@ -116,6 +116,8 @@ const usage = `mesh-bootstrap — make a bare machine into a mesh

  --tools-source     the repository the shared base is built from
  --tools-ref        what of it to build (default main)
+  --tools-go-source  the repository the Go toolchain is built from (default: mesh-tools-go beside --tools-source)
+  --tools-go-ref     what of it to build (default main)
  --catalog-source   the catalogue REPOSITORY, for building its modules;
                     --catalog is the checkout that says what they are
  --catalog-ref      what of it to build (default main)
@@ -308,6 +310,10 @@ func newFlagSet(opts *bootstrap.Options, jsonOut *bool) *flag.FlagSet {
 		"the repository the shared base is built from")
 	set.StringVar(&opts.ToolsSource.Ref, "tools-ref", opts.ToolsSource.Ref,
 		"what of it to build (default main)")
+	set.StringVar(&opts.ToolsGoSource.Repository, "tools-go-source", opts.ToolsGoSource.Repository,
+		"the repository the Go toolchain is built from (default: mesh-tools-go beside --tools-source)")
+	set.StringVar(&opts.ToolsGoSource.Ref, "tools-go-ref", opts.ToolsGoSource.Ref,
+		"what of it to build (default main)")
 	set.StringVar(&opts.CatalogSource.Repository, "catalog-source", opts.CatalogSource.Repository,
 		"the catalogue REPOSITORY, for building its modules — --catalog is the checkout that says what they are")
 	set.StringVar(&opts.CatalogSource.Ref, "catalog-ref", opts.CatalogSource.Ref,
@@ -49,7 +49,7 @@ func TestTheBundleCarriesTheFoundationAndTheControlPlaneAndNothingElse(t *testin
 	}
 	sort.Strings(images)

-	want := []string{"mesh-controller", "nats", "postgres"}
+	want := []string{"mesh-controller", "nats", "pgvector"}
 	if strings.Join(images, ",") != strings.Join(want, ",") {
 		t.Fatalf("the bundle carries %v; expected exactly %v.\n\n"+
 			"Adding one is a change to what every first node becomes, and to ADR 0006's "+
@@ -28,11 +28,12 @@
 // image, and this file is applied on a machine with no mesh to ask about anything (ADR 0006). The
 // registry prefix is the lab's; the digests are upstream's.
 //
-// The store's data is a NAMED VOLUME, not a directory on the machine. A directory the host
-// creates is owned by root, and the database runs as somebody else inside the container — so it
-// could not write, and the container crash-looped. A named volume lets the image set up its own
-// ownership, and outlives the container, which is what you want for the thing holding the mesh's
-// state.
+// **The store is raised where the `postgres` module keeps it** (novox/hq ADR 0338): the container
+// `postgres`, on the module's pgvector image, its data in the directory /var/lib/mesh-store owned by
+// the image's postgres user, its superuser password read from the module's own-secret file — so the
+// store step adopts it as it runs. Pinned upstream by the module's own digest, not through the lab's
+// registry prefix, because the two must be the same reference (mesh-host internal/bootstrap holds
+// them to each other against the module's manifest).

 {
  "declaration": 1,
@@ -83,17 +84,28 @@
      "boot": "enabled",
      "restart-on": ["base-filter"]
    },
+    // The store's data is a directory owned by the image's postgres user (999), made before the
+    // container starts: a directory the runtime made would be root's, and the database could not
+    // write it. Measured on the module's image 2026-10-13: it initialises a new store on a directory
+    // made so (novox/hq ADR 0338 §5).
+    {
+      "id": "store-data",
+      "type": "directory",
+      "path": "/var/lib/mesh-store",
+      "mode": "0700",
+      "owner": "999:70"
+    },
    {
      "id": "store",
      "type": "container",
-      "name": "mesh-store",
-      "image": "192.0.2.250:5000/postgres@sha256:7abf537131b66ed5af448d90653abf1679b0c7e9a1f07efdd4c3108a401b259a",
+      "name": "postgres",
+      "image": "pgvector/pgvector@sha256:cf134a767f474095eeba57e0117be8e568e011a63f33fbf252f14c9b760f8e6f",
      "env": {
        "POSTGRES_PASSWORD": "bootstrap",
        "PGDATA": "/var/lib/postgresql/data/pgdata"
      },
      "ports": ["5432:5432"],
-      "volumes": ["mesh-store-data:/var/lib/postgresql/data"]
+      "volumes": ["/var/lib/mesh-store:/var/lib/postgresql/data"]
    },
    // Over TCP, not the socket. While the store initialises it runs a temporary server on the
    // socket ONLY, then stops it and starts the real one — so a socket check passes, the action
@@ -102,21 +114,21 @@
    {
      "id": "store-ready",
      "type": "action",
-      "in": "mesh-store",
+      "in": "postgres",
      "command": ["sh", "-c", "for i in $(seq 1 180); do pg_isready -h 127.0.0.1 -U postgres >/dev/null 2>&1 && exit 0; sleep 1; done; echo 'the store did not answer within 180s; its own last words follow'; pg_isready -h 127.0.0.1 -U postgres; tail -n 20 /var/lib/postgresql/data/log/*.log 2>/dev/null; exit 1"],
 "verify": ["pg_isready", "-h", "127.0.0.1", "-U", "postgres"]
    },
    {
      "id": "inventory-database",
      "type": "action",
-      "in": "mesh-store",
+      "in": "postgres",
      "command": ["sh", "-c", "psql -U postgres -c 'CREATE DATABASE inventory'"],
      "verify": ["sh", "-c", "psql -U postgres -lqt | cut -d'|' -f1 | grep -qw inventory"]
    },
    {
      "id": "identity-database",
      "type": "action",
-      "in": "mesh-store",
+      "in": "postgres",
      "command": ["sh", "-c", "psql -U postgres -c 'CREATE DATABASE identity'"],
      "verify": ["sh", "-c", "psql -U postgres -lqt | cut -d'|' -f1 | grep -qw identity"]
    },
@@ -126,20 +138,20 @@
    {
      "id": "licences-database",
      "type": "action",
-      "in": "mesh-store",
+      "in": "postgres",
      "command": ["sh", "-c", "psql -U postgres -c 'CREATE DATABASE licences'"],
      "verify": ["sh", "-c", "psql -U postgres -lqt | cut -d'|' -f1 | grep -qw licences"]
    },
    {
      "id": "context-schemas",
      "type": "action",
-      "command": ["docker", "run", "--rm", "--network", "container:mesh-store",
+      "command": ["docker", "run", "--rm", "--network", "container:postgres",
                  "-e", "MESH_STORE_INVENTORY=postgres://postgres:bootstrap@127.0.0.1:5432/inventory?sslmode=disable",
                  "-e", "MESH_STORE_IDENTITY=postgres://postgres:bootstrap@127.0.0.1:5432/identity?sslmode=disable",
        "-e", "MESH_STORE_LICENCES=postgres://postgres:bootstrap@127.0.0.1:5432/licences?sslmode=disable",
                  "192.0.2.250:5000/mesh-controller@sha256:c67db38439ff0aee242b467486765467bb95801f52175fc5727cc4e437338ace",
                  "migrate"],
-      "verify": ["sh", "-c", "docker exec mesh-store psql -U postgres -d inventory -tAc \"select to_regclass('public.node')\" | grep -qx node && docker exec mesh-store psql -U postgres -d identity -tAc \"select to_regclass('public.signing_key')\" | grep -qx signing_key && docker exec mesh-store psql -U postgres -d licences -tAc \"select to_regclass('public.licence')\" | grep -qx licence"]
+      "verify": ["sh", "-c", "docker exec postgres psql -U postgres -d inventory -tAc \"select to_regclass('public.node')\" | grep -qx node && docker exec postgres psql -U postgres -d identity -tAc \"select to_regclass('public.signing_key')\" | grep -qx signing_key && docker exec postgres psql -U postgres -d licences -tAc \"select to_regclass('public.licence')\" | grep -qx licence"]
    },
    // **The bus is raised where the `nats` module keeps it** (novox/hq ADR 0333 §1): the container
    // `mesh-broker-nats`, its configuration and user list in /var/lib/nats-module/conf, its streams in
@@ -212,14 +224,17 @@
      "content": "// The first user list, carried by the installer because at genesis there is no mesh to\n// compose one. A bootstrap credential, rotated with the store's and replaced by the\n// controller's own composition from its first start onward.\naccounts {\n  MESH {\n    jetstream: enabled\n    users = [\n      { user: \"controller\", password: \"$2a$10$AHqJgOifIVbU41KmATiMhuXFs8xa7Wl2HuN4UVBCXdN2jIQzjqApy\", permissions: {\n        publish: { allow: [\"$JS.ACK.CONTROL.controller.>\", \"$JS.ACK.EVENTS.controller.>\", \"$JS.ACK.DEAD_LETTER_NOTICES.controller.>\", \"$JS.API.>\", \"$KV.mesh-controller_asked.>\", \"$KV.mesh-controller_calls.>\", \"$KV.mesh-controller_hand-acts.>\", \"$KV.mesh-controller_conditions.>\", \"$KV.mesh-controller_condition-history.>\", \"$KV.mesh-controller_lease.>\", \"$KV.SEAT_MESH_BUILD_MACHINE_cancelled.>\", \"$KV.SEAT_NODE_BUILD_AGENT_cancelled.>\", \"_INBOX.enrol.>\", \"mesh.assignment.>\", \"mesh.mod.*.tool.>\", \"mesh.node.>\", \"mesh.seat.mesh-build-machine.accept.>\", \"mesh.seat.node-build-agent.accept.>\", \"mesh.seat.mesh-build-machine.tool.>\", \"mesh.seat.node-build-agent.tool.>\", \"mesh.seat.mesh-controller.event.applied\", \"mesh.seat.mesh-controller.event.built-before\", \"mesh.seat.mesh-controller.event.refused\", \"mesh.seat.mesh-controller.event.rolled-back\", \"mesh.seat.mesh-controller.event.checked\", \"mesh.seat.mesh-controller.event.plan-moved\", \"mesh.seat.mesh-controller.event.condition-raised\", \"mesh.seat.mesh-controller.event.condition-changed\", \"mesh.seat.mesh-controller.event.condition-cleared\", \"mesh.seat.mesh-controller.event.doctor-heartbeat\", \"mesh.seat.mesh-controller.event.secret-replaced\", \"mesh.seat.mesh-controller.event.healer-acted\", \"$SRV.INFO\", \"mesh.seat.node-intrusion-prevention.tool.banned.*\", \"mesh.seat.node-backup.tool.backed-up.*\", \"mesh.seat.node-backup.tool.now.*\", \"mesh.seat.mesh-delivery.tool.stalled\", \"mesh.seat.mesh-delivery.tool.close\", \"mesh.seat.node-launcher.tool.secret.*\", \"mesh.seat.mesh-delivery.tool.release\", \"mesh.seat.mesh-delivery.tool.stop\", \"mesh.seat.mesh-delivery.tool.times\", \"mesh.seat.mesh-delivery.tool.groups\", \"mesh.seat.node-service-manager.tool.restart.*\", \"mesh.seat.mesh-controller.tool.plans\", \"mesh.events.dead.>\", \"mesh.again.>\"] }\n        subscribe: { allow: [\"$JS.API.>\", \"$JS.EVENT.ADVISORY.CONSUMER.MAX_DELIVERIES.>\", \"$JS.EVENT.ADVISORY.CONSUMER.DELETED.>\", \"_DELIVER.controller\", \"_DELIVER.controller.>\", \"_INBOX.controller.>\", \"mesh.control.>\", \"mesh.mod.*.event.provisioner.failing\", \"mesh.mod.*.event.provisioner.recovered\", \"mesh.mod.*.event.provisioner.retirement\", \"mesh.mod.gitea.event.pull.merged\", \"mesh.mod.gitea.event.pull.updated\", \"mesh.mod.mesh-catalog.event.catching-up\", \"mesh.mod.mesh-catalog.event.upgraded\", \"mesh.seat.mesh-build-machine.event.built\", \"mesh.seat.node-build-agent.event.built\", \"mesh.seat.operator-channel.event.decided.mesh-controller\", \"mesh.seat.mesh-controller.tool.>\", \"$SRV.PING\", \"$SRV.INFO\", \"$SRV.PING.mesh-controller\", \"$SRV.PING.mesh-controller.>\", \"$SRV.INFO.mesh-controller\", \"$SRV.INFO.mesh-controller.>\", \"$SRV.STATS\", \"$SRV.STATS.mesh-controller\", \"$SRV.STATS.mesh-controller.>\"] }\n        allow_responses: { max: 1, ttl: \"1m\" }\n      } }\n    ]\n  }\n}\n"
    },
    // The upstream server, until the broker step adopts it: the `nats` module's own image, built by the
-    // mesh, takes its place there once, on these same directories (ADR 0333 §3). The published port is the
+    // mesh, takes its place there once, on these same directories (ADR 0333 §3), as the bus's planned
+    // step (ADR 0236). The release is the one the module's image is built on (its NATS_BASE, 2.11.17),
+    // pinned upstream by that same digest: the adoption changes no server release, so it can be undone
+    // by putting the old image back and is said reversible. The published port is the
    // node's bus port, 5671 unless given, which every enrolment token names; the installer gives the
    // module the setting that maps its declared 4222 to it (ADR 0333 §2).
    {
      "id": "broker",
      "type": "container",
      "name": "mesh-broker-nats",
-      "image": "192.0.2.250:5000/nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927",
+      "image": "nats@sha256:e4bf19f15fd3218814a4e3c9e0064e1334bd8aa20d5984b9f1a0afd084f8cc00",
      "ports": ["5671:4222", "127.0.0.1:8222:8222"],
      "volumes": ["/var/lib/mesh-broker-nats:/data", "/var/lib/nats-module/conf:/etc/nats:ro", "/var/lib/mesh-broker-tls:/tls:ro"],
      "args": ["-c", "/etc/nats/nats.conf", "-js"]
@@ -227,8 +242,8 @@
    {
      "id": "broker-ready",
      "type": "action",
-      "command": ["sh", "-c", "for i in $(seq 1 60); do docker run --rm --network host --entrypoint sh 192.0.2.250:5000/nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927 -c 'nc -z 127.0.0.1 5671' >/dev/null 2>&1 && exit 0; sleep 1; done; exit 1"],
-      "verify": ["sh", "-c", "docker run --rm --network host --entrypoint sh 192.0.2.250:5000/nats@sha256:b83efabe3e7def1e0a4a31ec6e078999bb17c80363f881df35edc70fcb6bb927 -c 'nc -z 127.0.0.1 5671'"]
+      "command": ["sh", "-c", "for i in $(seq 1 60); do docker run --rm --network host --entrypoint sh nats@sha256:e4bf19f15fd3218814a4e3c9e0064e1334bd8aa20d5984b9f1a0afd084f8cc00 -c 'nc -z 127.0.0.1 5671' >/dev/null 2>&1 && exit 0; sleep 1; done; exit 1"],
+      "verify": ["sh", "-c", "docker run --rm --network host --entrypoint sh nats@sha256:e4bf19f15fd3218814a4e3c9e0064e1334bd8aa20d5984b9f1a0afd084f8cc00 -c 'nc -z 127.0.0.1 5671'"]
    },
    {
      "id": "control-plane",
@@ -174,6 +174,10 @@ type Options struct {
 	// ToolsSource is where the shared base is built from. Everything with code of its own
 	// compiles against it, so it is the first thing the mesh builds for itself.
 	ToolsSource Source
+	// ToolsGoSource is where the Go toolchain is built from (`mesh-tools-go`, ADR 0142): every Go
+	// bundle compiles in it, and genesis's own modules have Go code (issue 616). Empty means the
+	// repository beside ToolsSource named mesh-tools-go, as the mesh keeps it.
+	ToolsGoSource Source
 	// CatalogSource is where the catalogue REPOSITORY is, for building its modules. The catalogue
 	// CHECKOUT (Catalogue, above) says what a module is; this is where a builder clones it.
 	CatalogSource Source
@@ -38,27 +38,6 @@ func recording(t *testing.T) (*controlRecorder, controlPlane) {
 	return c, controlPlane{container: "temp-mesh-controller", run: c.run, timeout: time.Second}
 }

-func TestTheBuildersPackageRegistryPortIsASettingAndNotTheManifest(t *testing.T) {
-	c, control := recording(t)
-	o := Options{Node: "anchor", Ports: FoundationPorts{Packages: 3100}, Wait: time.Second}
-	if _, err := installModule(context.Background(), o, control, BuilderModule,
-		[]byte(theBuildersBinding), quietly); err != nil {
-		t.Fatal(err)
-	}
-	if got := c.settings[BuilderModule+"-settings.json"]; got != `{"serves":{"port":3100}}` {
-		t.Errorf("the builder was told %q about the package registry's port", got)
-	}
-	// The manifest reaches the mesh as the catalogue wrote it. A port rewritten into it here is a
-	// port the next registration from the catalogue silently takes back.
-	if got := c.settings[BuilderModule+"-module.json"]; got != theBuildersBinding {
-		t.Errorf("the installer changed the builder's manifest:\n%s", got)
-	}
-	set, push := c.index("settings set "+BuilderModule), c.index("push anchor")
-	if set < 0 || push < 0 || set > push {
-		t.Fatalf("the port was not set before the push that raises the builder: %v", c.told)
-	}
-}
-
 func TestTheBuilderOnTheDefaultPackagesPortIsToldNothing(t *testing.T) {
 	c, control := recording(t)
 	o := Options{Node: "anchor", Wait: time.Second}
@@ -0,0 +1,179 @@
+package bootstrap
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"encoding/pem"
+	"errors"
+	"fmt"
+	"os"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/novox/mesh-host/internal/declaration"
+)
+
+// Adopting the bus is the mesh's planned step for replacing it (novox/hq ADR 0333 §3, ADR 0236).
+//
+// The adoption replaces the bus's image once: the module's built image takes the place of the upstream
+// one the bundle raised, on the same streams, users and certificate. The controller refuses a push that
+// would replace the bus — "a planned step: `bus upgrade --why …` snapshots its streams first and checks
+// them after" — so genesis stopped at step 18 (issue 590). The installer takes that step: it snapshots the
+// streams itself, because at genesis no backup holder exists to be asked, and hands the snapshot to
+// `bus upgrade`, which sends the machine, opens `bus-maintenance`, and ends the step done only once the
+// bus answers healthy again — every stream, every durable consumer, a round trip (H-bus). The installer
+// waits for that end.
+
+// adoptionWhy is what the step is recorded as, for the record of hand acts and the bus's step.
+const adoptionWhy = "genesis adopts its bus as the nats module (ADR 0333)"
+
+// Where the installer keeps the streams' snapshot before the adoption, and the credential the snapshot
+// program reads while it runs. Beside genesis's own credentials; variables so a test writes elsewhere.
+var (
+	busSnapshotFile       = "/var/lib/mesh-genesis/bus-before-adoption.tar"
+	busSnapshotCredential = "/var/lib/mesh-genesis/bus-snapshot.credential"
+	busCertificateFile    = "/var/lib/mesh-broker-tls/tls.crt"
+	busControllerSecret   = BusControllerFile
+	// busStepWithin bounds the wait for the controller to say the step ended: its own bound (15 min,
+	// mesh-controller busStepBound), and its doctor's next look after that.
+	busStepWithin = 17 * time.Minute
+)
+
+// adoptTheBus sends the nats module to this machine through the bus's planned step. A bus already on the
+// module's image is the module's: it is sent like any module, and nothing is replaced.
+func adoptTheBus(ctx context.Context, o Options, control controlPlane, bus *declaration.Container,
+	say func(string)) error {
+
+	if running := runningImage(ctx, control, bus.Name); running != "" && running != bus.Image {
+		say("  already adopted   " + bus.Name + " — it runs the module's image")
+		_, err := pushNode(ctx, o, control, say)
+		return err
+	}
+	image, err := theModulesBusImage(ctx, o, control)
+	if err != nil {
+		return err
+	}
+	if err := snapshotTheBus(ctx, o, control, image, say); err != nil {
+		return err
+	}
+	say("  restarting        " + bus.Name + " — once, onto the " + BusModule + " module's image, as the bus's " +
+		"planned step; its streams, users and certificate stay where they are (novox/hq ADR 0333 §3, ADR 0236)")
+	if _, err := control.within(2*o.Wait).tell(ctx, "bus", "upgrade", "--why", adoptionWhy,
+		"--reversible", "--snapshot-taken", busSnapshotFile); err != nil {
+		return fmt.Errorf("the bus's planned step was refused, so the bus is not replaced: %w", err)
+	}
+	return nil
+}
+
+// meshBuiltImage is an image the mesh built, as it records it: `artifact-store://<module>/<artifact>@sha256:…`.
+var meshBuiltImage = regexp.MustCompile(`artifact-store://([a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*@sha256:[0-9a-f]{64})`)
+
+// theModulesBusImage is the nats module's server image, as the build just made it, pulled from this
+// mesh's registry: the image that carries the snapshot program.
+func theModulesBusImage(ctx context.Context, o Options, control controlPlane) (string, error) {
+	said, err := control.tell(ctx, "builds", BusModule, "-n", "1")
+	if err != nil {
+		return "", err
+	}
+	for _, m := range meshBuiltImage.FindAllStringSubmatch(said, -1) {
+		if strings.HasPrefix(m[1], BusModule+"/") {
+			return strings.TrimSuffix(o.Registry, "/") + "/" + m[1], nil
+		}
+	}
+	return "", fmt.Errorf("the mesh says no image it built for the %s module, so its snapshot program cannot "+
+		"be run before the bus is replaced:\n%s", BusModule, indent(strings.TrimSpace(said)))
+}
+
+// snapshotTheBus writes every stream of the running bus to busSnapshotFile with the module's own snapshot
+// program (mesh-catalog modules/nats, ADR 0235), as the controller's account, pinned to the bus's
+// certificate. The credential is written for the program's one run and removed after it.
+func snapshotTheBus(ctx context.Context, o Options, control controlPlane, image string, say func(string)) error {
+	password, err := readCredentialFile(busControllerSecret)
+	if err != nil {
+		return fmt.Errorf("the controller's bus credential is not at %s, so the streams cannot be snapshotted "+
+			"before the bus is replaced: %w", busControllerSecret, err)
+	}
+	fingerprint, err := certificateFingerprint(busCertificateFile)
+	if err != nil {
+		return err
+	}
+	port := o.Ports.orDefaults().Bus
+	server := "tls://127.0.0.1:" + strconv.Itoa(port)
+	credential, err := json.Marshal(map[string]string{"url": server, "fingerprint": fingerprint,
+		"user": busControllerUser, "password": password})
+	if err != nil {
+		return err
+	}
+	if err := os.WriteFile(busSnapshotCredential, credential, 0o600); err != nil {
+		return fmt.Errorf("the snapshot's credential could not be written: %w", err)
+	}
+	defer os.Remove(busSnapshotCredential)
+
+	script := "docker run --rm -i --network host --entrypoint /usr/local/bin/mesh-nats-snapshot " + image +
+		" snapshot --server " + server + " --credential - < " + busSnapshotCredential + " > " + busSnapshotFile +
+		".partial && mv " + busSnapshotFile + ".partial " + busSnapshotFile
+	running, cancel := context.WithTimeout(ctx, busStepWithin)
+	defer cancel()
+	if out, err := control.run(running, "sh", "-c", script); err != nil {
+		_, _ = control.run(ctx, "rm", "-f", busSnapshotFile+".partial")
+		return fmt.Errorf("the bus's streams could not be snapshotted, so the bus is not replaced: %w\n%s",
+			err, indent(strings.TrimSpace(out)))
+	}
+	say("  snapshotted       every stream of the bus, at " + busSnapshotFile + " (its module's snapshot program)")
+	return nil
+}
+
+// certificateFingerprint is the pin of the bus's certificate: sha256 of its DER, as every machine pins it.
+func certificateFingerprint(path string) (string, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("the bus's certificate is not at %s, so it cannot be pinned for the snapshot: %w", path, err)
+	}
+	block, _ := pem.Decode(raw)
+	if block == nil {
+		return "", fmt.Errorf("%s holds no PEM certificate", path)
+	}
+	sum := sha256.Sum256(block.Bytes)
+	return "sha256:" + hex.EncodeToString(sum[:]), nil
+}
+
+// waitForTheBusStep waits until the controller says the bus's planned step ended: done once the bus
+// answered healthy — every stream, every durable consumer, a round trip — or failed, with its snapshot as
+// the way back. The step's own bound is the controller's; this waits a little past it.
+func waitForTheBusStep(ctx context.Context, o Options, control controlPlane, say func(string)) error {
+	deadline := time.Now().Add(busStepWithin)
+	var last string
+	for {
+		said, err := control.tell(ctx, "bus")
+		if err == nil {
+			for _, line := range strings.Split(said, "\n") {
+				if strings.HasPrefix(strings.TrimSpace(line), "last step ") {
+					last = strings.TrimSpace(line)
+				}
+			}
+			switch {
+			case strings.Contains(last, ": done at "):
+				say("  bus step done     " + last)
+				return nil
+			case strings.Contains(last, ": failed at "):
+				return fmt.Errorf("the bus's planned step ended failed: %s\n%s", last, indent(strings.TrimSpace(said)))
+			}
+		}
+		if !time.Now().Before(deadline) {
+			break
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(answerEvery):
+		}
+	}
+	if last == "" {
+		return errors.New("the controller says no bus step after the adoption was sent; `mesh-controller bus` says how it stands")
+	}
+	return fmt.Errorf("the bus's planned step did not end within %s: %s", busStepWithin, last)
+}
@@ -0,0 +1,135 @@
+package bootstrap
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Defends novox/hq issue 590 at its broker step (ADR 0333 §3, ADR 0236): the adoption replaces the bus's
+// image, and the mesh replaces its bus only as a planned step. A plain push was refused — "sending anchor
+// would replace the bus … a planned step: `bus upgrade --why …`" — and genesis stopped at step 18.
+
+func TestTheBrokerStepAdoptsTheBusThroughItsPlannedStep(t *testing.T) {
+	catalogue := aCatalogue(t, map[string]string{BusModule: aBusModule(theModulesLayout)})
+	rewritten, err := Rewrite(theRealBundle(t), held)
+	if err != nil {
+		t.Fatal(err)
+	}
+	bundleImage := containerNamed(rewritten.Declaration, "mesh-broker-nats").Image
+	upgraded := false
+	var credential []byte
+	runtime := &asked{}
+	agrees := aMeshThatAgrees(nil)
+	runtime.answer = func(name string, args []string) (string, error) {
+		joined := strings.Join(args, " ")
+		switch {
+		case name == "sh" && strings.Contains(joined, "mesh-nats-snapshot"):
+			credential, _ = os.ReadFile(busSnapshotCredential) // as the program reads it
+		case strings.Contains(joined, "bus upgrade --why"):
+			upgraded = true
+		case strings.Contains(joined, "inspect --format {{.Config.Image}} mesh-broker-nats"):
+			if upgraded {
+				return theModulesImage + "\n", nil
+			}
+			return bundleImage + "\n", nil
+		}
+		return agrees(name, args)
+	}
+	_, fetch := aBusThatAdopts()
+	o := installing(t, catalogue)
+	o.CatalogSource = Source{Repository: "git://forge/mesh-catalog.git"}
+	o.Wait = 5 * time.Second
+	said, err := busStepWith(t, o, runtime, fetch)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	snapshot, upgrade := -1, -1
+	for i, c := range runtime.commands {
+		switch {
+		case strings.HasPrefix(c, "sh -c") && strings.Contains(c, "mesh-nats-snapshot"):
+			snapshot = i
+			for _, want := range []string{"127.0.0.1:5000/nats/server@sha256:" + strings.Repeat("4", 64),
+				"snapshot --server tls://127.0.0.1:5671 --credential - < " + busSnapshotCredential,
+				"> " + busSnapshotFile + ".partial && mv " + busSnapshotFile + ".partial " + busSnapshotFile} {
+				if !strings.Contains(c, want) {
+					t.Errorf("the snapshot is not taken with %q: %s", want, c)
+				}
+			}
+		case strings.Contains(c, "/mesh-controller bus upgrade"):
+			upgrade = i
+			if want := "bus upgrade --why " + adoptionWhy + " --reversible --snapshot-taken " + busSnapshotFile; !strings.HasSuffix(c, want) {
+				t.Errorf("the planned step is asked as %q; want it to end %q", c, want)
+			}
+		case strings.HasSuffix(c, "/mesh-controller push anchor"):
+			t.Errorf("the bus's module was sent by a plain push, which the mesh refuses for the bus: %v", runtime.commands)
+		}
+	}
+	if snapshot < 0 || upgrade < 0 || snapshot > upgrade {
+		t.Fatalf("the streams were not snapshotted before the bus's planned step (snapshot %d, upgrade %d): %v",
+			snapshot, upgrade, runtime.commands)
+	}
+	var cred map[string]string
+	if err := json.Unmarshal(credential, &cred); err != nil {
+		t.Fatalf("the snapshot program was given no credential: %v", err)
+	}
+	fingerprint, _ := certificateFingerprint(busCertificateFile)
+	if cred["user"] != "controller" || cred["password"] != "BUS-PW" || cred["fingerprint"] != fingerprint ||
+		cred["url"] != "tls://127.0.0.1:5671" {
+		t.Errorf("the snapshot's credential is %v", cred)
+	}
+	if _, err := os.Stat(busSnapshotCredential); !os.IsNotExist(err) {
+		t.Error("the snapshot's credential was left on the machine")
+	}
+	text := strings.Join(said, "\n")
+	for _, want := range []string{"snapshotted       every stream", "restarting        mesh-broker-nats — once",
+		"bus answers       mesh-broker-nats", "bus step done     last step 1", "adopted           mesh-broker-nats"} {
+		if !strings.Contains(text, want) {
+			t.Errorf("the step did not say %q:\n%s", want, text)
+		}
+	}
+}
+
+// A planned step the controller ends failed is the broker step failing, with the controller's words.
+func TestABusStepThatEndsFailedIsRefused(t *testing.T) {
+	aGenesisBusOnDisk(t)
+	runtime := &asked{answer: func(name string, args []string) (string, error) {
+		return "last step 1: not known → 53e51864 on anchor by installer (x): failed at 2026-10-13 11:59; snapshot s\n" +
+			"  stream KV_x has no messages\n", nil
+	}}
+	control := controlPlane{container: "mesh-controller", run: runtime.run, timeout: time.Second}
+	err := waitForTheBusStep(context.Background(), Options{}, control, quietly)
+	if err == nil || !strings.Contains(err.Error(), "failed at") || !strings.Contains(err.Error(), "KV_x") {
+		t.Fatalf("a failed bus step was not refused with its words: %v", err)
+	}
+}
+
+// The bundle's bus runs the release the module's image is built on, pinned by the same digest, so the
+// adoption changes no server release and is reversible as the step says (ADR 0333 §3).
+func TestTheBundlesBusRunsTheReleaseTheModulesImageIsBuiltOn(t *testing.T) {
+	var m struct {
+		Build struct {
+			On []struct{ Arg, Image string } `json:"on"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(theCataloguesModule(t, BusModule), &m); err != nil {
+		t.Fatal(err)
+	}
+	base := ""
+	for _, on := range m.Build.On {
+		if on.Arg == "NATS_BASE" {
+			base = on.Image
+		}
+	}
+	rewritten, err := Rewrite(theRealBundle(t), held)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := containerNamed(rewritten.Declaration, "mesh-broker-nats").Image; got != base {
+		t.Errorf("the bundle raises the bus on %s; the nats module's image is built on %s", got, base)
+	}
+}
@@ -0,0 +1,65 @@
+package bootstrap
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Genesis seals the build agent the forge it raised (novox/hq ADR 0336 §3, issue 121): the agent's
+// npm-package-registry requirement is optional and binds only once the gitea module is assigned, after
+// the base, so until then the packages step's genesis document is how the sdk and base steps reach the
+// forge.
+
+func TestThePackagesStepSealsTheGenesisDocumentToTheBuildAgent(t *testing.T) {
+	if BuilderModule != "build-agent" {
+		t.Fatalf("genesis installs %q; the document is the build agent's", BuilderModule)
+	}
+	c, control := recording(t)
+	o := Options{Node: "anchor", Ports: FoundationPorts{Packages: 3100}, Wait: time.Second}
+	doc := genesisRegistry(o.Ports.orDefaults(), "builder-password")
+	if err := deliverGenesisRegistry(context.Background(), o, control, doc, quietly); err != nil {
+		t.Fatal(err)
+	}
+	carried := c.settings["accepting-"+GenesisRegistrySecret]
+	var got GenesisRegistry
+	if err := json.Unmarshal([]byte(carried), &got); err != nil {
+		t.Fatalf("the genesis document carried is not JSON: %q", carried)
+	}
+	want := GenesisRegistry{Scheme: "http", At: "127.0.0.1", Port: 3100, NpmPath: "/api/packages/novox/npm/",
+		As: "mesh-builder", Password: "builder-password"}
+	if got != want {
+		t.Fatalf("the genesis document says %+v, want %+v", got, want)
+	}
+	accept := c.index("secret accept anchor build-agent genesis-package-registry --from /accepting-genesis-package-registry")
+	push := c.index("push anchor")
+	if accept < 0 || push < 0 || accept > push {
+		t.Fatalf("the genesis document was not sealed to the build agent before the push: %v", c.told)
+	}
+}
+
+// What the retired builder was given and the build agent declares neither of: an `npm-password`
+// own-secret and a `serves` setting for its carried binding (ADR 0336 §3).
+func TestNoStepGivesTheBuildAgentAServesSettingOrAnNpmPassword(t *testing.T) {
+	for _, module := range []string{BuilderModule} {
+		c, control := recording(t)
+		o := Options{Node: "anchor", Ports: FoundationPorts{Packages: 3100}, Wait: time.Second}
+		if _, err := installModule(context.Background(), o, control, module, []byte(`{"module":"`+module+`"}`), quietly); err != nil {
+			t.Fatal(err)
+		}
+		if got, set := c.settings[module+"-settings.json"]; set {
+			t.Errorf("%s was given a setting on a node with a non-default packages port: %s", module, got)
+		}
+		if err := deliverGenesisRegistry(context.Background(), o, control,
+			genesisRegistry(o.Ports.orDefaults(), "p"), quietly); err != nil {
+			t.Fatal(err)
+		}
+		for _, told := range c.told {
+			if strings.Contains(told, "npm-password") || strings.Contains(told, "serves") {
+				t.Errorf("genesis told the controller %q", told)
+			}
+		}
+	}
+}
@@ -0,0 +1,89 @@
+package bootstrap
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Defends novox/hq issue 616: genesis's base step builds the toolchain of every language a module
+// genesis installs is compiled in. It built only mesh-tools, and the store's module, with Go code,
+// stopped genesis at step 17: "this mesh holds no copy of it. Build mesh-tools-go first".
+
+// genesisModules is every catalogue module genesis installs on its own, read from the steps that
+// install them: the registry, the build agent, the store, the bus, the vault, the catalogue and the
+// filter (extras are the operator's choice and come after the base too, but are not genesis's own).
+var genesisModules = []string{RegistryModule, BuilderModule, "postgres", BusModule, "mesh-vault", "mesh-catalog", "nftables"}
+
+// Every genesis module's bundles are compiled in a toolchain the base step builds, read from the real
+// catalogue's manifests: a module that gains a language genesis does not build fails here, not at a
+// genesis.
+func TestTheBaseStepBuildsEveryToolchainAGenesisModuleIsCompiledIn(t *testing.T) {
+	built := map[string]bool{}
+	for _, tc := range genesisToolchains {
+		built[tc.Language] = true
+	}
+	for _, module := range genesisModules {
+		var m struct {
+			Build struct {
+				Artifacts []struct {
+					Name, Kind, Language string
+				} `json:"artifacts"`
+			} `json:"build"`
+		}
+		if err := json.Unmarshal(theCataloguesModule(t, module), &m); err != nil {
+			t.Fatalf("%s: %v", module, err)
+		}
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != "bundle" {
+				continue // an image builds on the bases its Dockerfile names, pinned upstream
+			}
+			if !built[a.Language] {
+				t.Errorf("%s's %q is a %s bundle, and genesis's base step builds no %s toolchain",
+					module, a.Name, a.Language, a.Language)
+			}
+		}
+	}
+}
+
+// And the base step asks for each toolchain's build: the base, then the Go toolchain beside it.
+func TestTheBaseStepBuildsTheGoToolchainBesideTheBase(t *testing.T) {
+	runtime := &asked{answer: aMeshThatAgrees(nil)}
+	control := controlPlane{container: "mesh-controller", run: runtime.run, timeout: time.Second}
+	o := Options{ToolsSource: Source{Repository: "git://192.0.2.30/mesh-tools.git"}}
+	if err := BuildBase(context.Background(), o, control, quietly); err != nil {
+		t.Fatal(err)
+	}
+	var builds []string
+	for _, c := range runtime.commands {
+		if strings.Contains(c, "/mesh-controller build ") {
+			builds = append(builds, c[strings.Index(c, "build "):])
+		}
+	}
+	want := []string{
+		"build git://192.0.2.30/mesh-tools.git --ref main --wait 1200s",
+		"build git://192.0.2.30/mesh-tools-go.git --ref main --wait 1200s",
+	}
+	if strings.Join(builds, "\n") != strings.Join(want, "\n") {
+		t.Fatalf("the base step built\n%s\nand not\n%s", strings.Join(builds, "\n"), strings.Join(want, "\n"))
+	}
+}
+
+func TestTheGoToolchainIsAsGivenOrBesideTheBase(t *testing.T) {
+	for _, c := range []struct{ tools, given, want string }{
+		{"http://forge/novox/mesh-tools.git", "", "http://forge/novox/mesh-tools-go.git"},
+		{"http://forge/novox/mesh-tools", "", "http://forge/novox/mesh-tools-go"},
+		{"http://forge/other/base.git", "http://forge/other/go.git", "http://forge/other/go.git"},
+	} {
+		got, err := toolsGoSource(Options{ToolsSource: Source{Repository: c.tools}, ToolsGoSource: Source{Repository: c.given}})
+		if err != nil || got.Repository != c.want {
+			t.Errorf("tools %s, given %q: %q %v; want %s", c.tools, c.given, got.Repository, err, c.want)
+		}
+	}
+	if _, err := toolsGoSource(Options{ToolsSource: Source{Repository: "http://forge/other/base.git"}}); err == nil ||
+		!strings.Contains(err.Error(), "--tools-go-source") {
+		t.Errorf("a base not named mesh-tools, and no Go toolchain given, was not refused naming the flag: %v", err)
+	}
+}
@@ -137,7 +137,26 @@ func registerAndAssign(ctx context.Context, o Options, control controlPlane, mod
 // should hold, seals every secret in them and publishes them, and on a first node that is the
 // slowest thing the mesh does.
 func pushNode(ctx context.Context, o Options, control controlPlane, say func(string)) (string, error) {
-	said, err := control.within(o.Wait).tell(ctx, "push", o.Node)
+	return pushing(ctx, o, control, false, say)
+}
+
+// pushNodeApplied is pushNode that returns only once the node reports it applied exactly what it was
+// sent (`push <node> --wait`, novox/hq ADR 0010): for a push whose content the very next step reads
+// on the machine. A plain push returns as soon as the declaration is sent, and the node applies it a
+// moment later (issue 615).
+func pushNodeApplied(ctx context.Context, o Options, control controlPlane, say func(string)) (string, error) {
+	return pushing(ctx, o, control, true, say)
+}
+
+func pushing(ctx context.Context, o Options, control controlPlane, applied bool, say func(string)) (string, error) {
+	args := []string{"push", o.Node}
+	patience := o.Wait
+	if applied {
+		args = append(args, "--wait", o.Wait.String())
+		// The controller's own wait, and time to compose and send before it starts.
+		patience = 2 * o.Wait
+	}
+	said, err := control.within(patience).tell(ctx, args...)
 	if err != nil {
 		return "", fmt.Errorf(
 			"%w\n\nWhat was registered and assigned is registered and assigned, and this node has "+
@@ -145,7 +164,20 @@ func pushNode(ctx context.Context, o Options, control controlPlane, say func(str
 				"at all. Fix what it named and run this installer again: it will find the module "+
 				"already registered and try the push again", err)
 	}
-	say("  pushed            " + o.Node)
+	if applied {
+		say("  pushed            " + o.Node + ", and it applied it")
+	} else {
+		say("  pushed            " + o.Node)
+	}
+	// **Every push may carry a new bus user, and until the adoption the bus hears of it only from here**
+	// (novox/hq issue 608, ADR 0331 §5, ADR 0333 §4). A module's account is minted into the mesh's
+	// records and sealed to this node with the push; the bus reads its user list from a file, and until
+	// the broker step adopts the bus as the nats module nothing but this installer writes that file. The
+	// list was placed only when the node enrolled, so the build agent's account (step 13) never reached
+	// the bus and the agent was refused ("Authorization Violation") until the sdk step gave up.
+	if err := placeUntilAdopted(ctx, control, say); err != nil {
+		return "", err
+	}
 	return strings.TrimSpace(said), nil
 }

@@ -25,20 +25,62 @@ import (
 // buildWait bounds one module build. Generous, because the first build compiles a toolchain.
 const buildWait = 20 * time.Minute

-// BuildBase asks the mesh to build the shared base every module with code of its own stands on.
+// BuildBase asks the mesh to build the shared base every module with code of its own stands on, and
+// the toolchain of every language genesis's own modules are written in.
 //
 // **First, because until it exists nothing else with code can be built.** Not registered as a
 // module here: it is never assigned — it runs nowhere — and the build itself records what was
 // made, which is all anything downstream reads.
+//
+// **Every toolchain a genesis module compiles in** (novox/hq issue 616). A bundle is compiled in its
+// language's base (mesh-controller internal/builder toolchain.go): TypeScript in mesh-tools, Go in
+// mesh-tools-go. The store's and the bus's modules carry Go code, so a genesis that built only
+// mesh-tools stopped at the store step: "this mesh holds no copy of it. Build mesh-tools-go first".
+// The bases are the ones genesisToolchains names, and a test holds them to the languages of every
+// module genesis installs, read from the catalogue.
 func BuildBase(ctx context.Context, o Options, control controlPlane, say func(string)) error {
 	if o.ToolsSource.Repository == "" {
 		return fmt.Errorf("phase two needs --tools-source: the shared base is built from its " +
 			"own repository, and an installer told nothing cannot know where that is")
 	}
-	say("  building          " + o.ToolsSource.Repository + " at " + refOr(o.ToolsSource.Ref))
-	_, err := control.within(buildWait).tell(ctx,
-		"build", o.ToolsSource.Repository, "--ref", refOr(o.ToolsSource.Ref), "--wait", "1200s")
-	return err
+	goSource, err := toolsGoSource(o)
+	if err != nil {
+		return err
+	}
+	for _, src := range []Source{o.ToolsSource, goSource} {
+		say("  building          " + src.Repository + " at " + refOr(src.Ref))
+		if _, err := control.within(buildWait).tell(ctx,
+			"build", src.Repository, "--ref", refOr(src.Ref), "--wait", "1200s"); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// genesisToolchains is the base each language's bundles compile in, for the languages genesis's own
+// modules are written in — the same pairs as mesh-controller internal/builder toolchain.go — in the
+// order BuildBase builds them.
+var genesisToolchains = []struct{ Language, Base string }{
+	{"typescript", "mesh-tools"},
+	{"go", "mesh-tools-go"},
+}
+
+// toolsGoSource is where the Go toolchain is built from: as given, or the repository beside the base's
+// named mesh-tools-go, which is how the mesh keeps its repositories side by side.
+func toolsGoSource(o Options) (Source, error) {
+	if o.ToolsGoSource.Repository != "" {
+		return o.ToolsGoSource, nil
+	}
+	repo := strings.TrimSuffix(o.ToolsSource.Repository, "/")
+	suffix := ""
+	if strings.HasSuffix(repo, ".git") {
+		repo, suffix = strings.TrimSuffix(repo, ".git"), ".git"
+	}
+	if !strings.HasSuffix(repo, "mesh-tools") {
+		return Source{}, fmt.Errorf("the Go toolchain is built from mesh-tools-go, and --tools-source (%s) is not a "+
+			"repository named mesh-tools to find it beside; give --tools-go-source", o.ToolsSource.Repository)
+	}
+	return Source{Repository: repo + "-go" + suffix, Ref: o.ToolsGoSource.Ref}, nil
 }

 // InstallFromCatalogue builds a catalogue module and installs it on this machine.
@@ -84,7 +84,7 @@ func InstallStore(ctx context.Context, o Options, control controlPlane,
 		say); err != nil {
 		return err
 	}
-	say("  adopted           mesh-store — the foundation's store is now the " + module + " module")
+	say("  adopted           " + store.Name + " — the foundation's store is now the " + module + " module")
 	return nil
 }

@@ -93,7 +93,8 @@ func InstallStore(ctx context.Context, o Options, control controlPlane,
 // be in it. InstallFromCatalogue is the same sequence without that moment; the store, the broker
 // and the vault each need it or need the shape, and three copies of it drifted.
 func installProvider(ctx context.Context, o Options, control controlPlane, module string,
-	manifest []byte, buildNote string, beforePush func() error, say func(string)) error {
+	manifest []byte, buildNote string, beforePush func() error, say func(string),
+	send ...func() error) error {

 	remote := "/" + module + "-module.json"
 	if err := control.carrying(ctx, module+"-module.json", manifest, remote); err != nil {
@@ -132,6 +133,11 @@ func installProvider(ctx context.Context, o Options, control controlPlane, modul
 			return err
 		}
 	}
+	// A module whose first send is not a plain push says how it is sent: the bus, whose replacement is a
+	// planned step (ADR 0236), is sent by that step (adoptTheBus).
+	if len(send) > 0 && send[0] != nil {
+		return send[0]()
+	}
 	_, err := pushNode(ctx, o, control, say)
 	return err
 }
@@ -176,9 +182,10 @@ const BusModule = "nats"
 // **The image is the one thing that changes, once** (ADR 0333 §3). The store's module pins the upstream
 // postgres the foundation runs; the bus's module builds its server image (it carries the mesh's snapshot
 // tool), so no pinned reference can be equal to the foundation's. The applier recreates the container on
-// the module's image, on the same streams, users and certificate. This says so before the push and waits
-// after it until the container runs the module's image and the bus answers, so nothing after this step
-// dials a bus that is restarting.
+// the module's image, on the same streams, users and certificate. The mesh replaces its bus only as a
+// planned step (ADR 0236), so the module is sent by that step: its streams snapshotted first, the restart
+// said, and the installer waits until the container runs the module's image, the bus answers, and the
+// controller ends the step done (bus_adoption.go), so nothing after this step dials a bus that is restarting.
 func InstallBroker(ctx context.Context, o Options, control controlPlane,
 	foundation *declaration.Declaration, fetch func(context.Context, string) (int, string, error),
 	say func(string)) error {
@@ -197,20 +204,15 @@ func InstallBroker(ctx context.Context, o Options, control controlPlane,
 	}
 	say("  adopting          " + bus.Name + " — the bus the foundation raised, its streams kept")
 	if err := installProvider(ctx, o, control, module, manifest, "(the server, adopting the foundation's bus)",
-		func() error {
-			if running := runningImage(ctx, control, bus.Name); running != "" && running != bus.Image {
-				say("  already restarted " + bus.Name + " — it runs the module's image")
-				return nil
-			}
-			say("  restarting        " + bus.Name + " — once, onto the " + module + " module's image; its " +
-				"streams, users and certificate stay where they are (novox/hq ADR 0333 §3)")
-			return nil
-		}, say); err != nil {
+		nil, say, func() error { return adoptTheBus(ctx, o, control, bus, say) }); err != nil {
 		return err
 	}
 	if err := waitForTheAdoptedBus(ctx, o, control, bus, fetch, say); err != nil {
 		return err
 	}
+	if err := waitForTheBusStep(ctx, o, control, say); err != nil {
+		return err
+	}
 	say("  adopted           " + bus.Name + " — the foundation's bus is now the " + module +
 		" module, and its user list is the module's from here on")
 	return nil
@@ -69,6 +69,7 @@ func aBusThatAdopts() (*asked, func(context.Context, string) (int, string, error
 func busStepWith(t *testing.T, o Options, runtime *asked,
 	fetch func(context.Context, string) (int, string, error)) ([]string, error) {
 	t.Helper()
+	aGenesisBusOnDisk(t)
 	rewritten, err := Rewrite(theRealBundle(t), held)
 	if err != nil {
 		t.Fatal(err)
@@ -222,7 +223,7 @@ func TestTheBrokerStepSaysTheRestartAndWaitsForTheBusToAnswer(t *testing.T) {
 	runtime.answer = func(name string, args []string) (string, error) {
 		joined := strings.Join(args, " ")
 		switch {
-		case strings.Contains(joined, "push anchor"):
+		case strings.Contains(joined, "bus upgrade --why"):
 			pushed = true
 		case strings.Contains(joined, "inspect --format {{.Config.Image}} mesh-broker-nats"):
 			if !pushed {
@@ -304,7 +305,7 @@ func TestARerunAfterTheAdoptionSaysTheBusIsTheModulesAlready(t *testing.T) {
 		t.Fatal(err)
 	}
 	text := strings.Join(said, "\n")
-	if strings.Contains(text, "restarting") || !strings.Contains(text, "already restarted mesh-broker-nats") {
+	if strings.Contains(text, "restarting") || !strings.Contains(text, "already adopted   mesh-broker-nats") {
 		t.Errorf("a re-run announced a restart, or did not say the bus is the module's already:\n%s", text)
 	}
 }
@@ -417,3 +418,30 @@ func TestTheBundlesBusFilesAreSeeds(t *testing.T) {
 		}
 	}
 }
+
+// aGenesisBusOnDisk puts what the adoption reads on the machine in a test's own directory: the bus's
+// certificate, the controller's bus credential, and where the snapshot goes. The step's wait is short.
+func aGenesisBusOnDisk(t *testing.T) {
+	t.Helper()
+	dir := t.TempDir()
+	cert := filepath.Join(dir, "tls.crt")
+	if err := os.WriteFile(cert, []byte(aCertificatePEM), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	secret := filepath.Join(dir, "bus-controller.secret")
+	if err := os.WriteFile(secret, []byte("BUS-PW"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	was := []string{busSnapshotFile, busSnapshotCredential, busCertificateFile, busControllerSecret}
+	wasWithin := busStepWithin
+	busSnapshotFile, busSnapshotCredential = filepath.Join(dir, "bus.tar"), filepath.Join(dir, "bus.credential")
+	busCertificateFile, busControllerSecret = cert, secret
+	busStepWithin = 50 * time.Millisecond
+	t.Cleanup(func() {
+		busSnapshotFile, busSnapshotCredential, busCertificateFile, busControllerSecret = was[0], was[1], was[2], was[3]
+		busStepWithin = wasWithin
+	})
+}
+
+// aCertificatePEM is a PEM block standing for the bus's certificate; its pin is the sha256 of these bytes.
+const aCertificatePEM = "-----BEGIN CERTIFICATE-----\nAAECAwQFBgcICQ==\n-----END CERTIFICATE-----\n"
@@ -2,6 +2,7 @@ package bootstrap

 import (
 	"context"
+	"encoding/json"
 	"fmt"
 	"net/http"
 	"os"
@@ -24,7 +25,7 @@ import (
 const (
 	// foundationStore is the foundation's postgres container — the mesh's own memory, raised from the
 	// bundle. gitea's bootstrap database lives here too, so a mesh runs one postgres (issue 051).
-	foundationStore = "mesh-store"
+	foundationStore = "postgres"
 	// giteaBootstrap is the gitea server raised directly at genesis, before gitea is a module —
 	// under the name the gitea MODULE declares for its container, so the module finds it and holds
 	// it rather than raising a second forge beside it (novox/hq ADR 0163, rule 7; issue 090).
@@ -49,8 +50,8 @@ const (
 	packagesTeam = "packages"
 	// giteaAdminUser is the admin the bootstrap creates and the provisioner later authenticates as.
 	giteaAdminUser = "mesh-admin"
-	// builderGiteaUser is the gitea account the builder publishes and pulls with at genesis. It is
-	// the `as` the builder's static package binding names.
+	// builderGiteaUser is the gitea account the build agent publishes and pulls with at genesis: the
+	// `as` of the genesis document (novox/hq ADR 0336 §3). Retiring it is issue 602.
 	builderGiteaUser = "mesh-builder"
 	// giteaDBRole/giteaDBName is gitea's own database in the foundation store.
 	giteaDBRole = "mesh_gitea"
@@ -133,8 +134,8 @@ func RaisePackageRegistry(ctx context.Context, o Options, d Deps, control contro
 		return err
 	}

-	say("  delivering the builder its registry credential")
-	if err := deliverBuilderNpm(ctx, o, control, builderPassword, say); err != nil {
+	say("  sealing the build agent the genesis document for the forge it raised")
+	if err := deliverGenesisRegistry(ctx, o, control, genesisRegistry(ports, builderPassword), say); err != nil {
 		return err
 	}

@@ -362,27 +363,69 @@ func packagePasswords() (db, admin, builder string, err error) {
 	return db, admin, builder, nil
 }

-// deliverBuilderNpm seals the builder's registry password to this node as its `npm-password`
-// own-secret, the same way the control plane's store connections are delivered — carry the value in,
-// `secret accept`, and the next push writes it sealed where the builder reads it.
-func deliverBuilderNpm(ctx context.Context, o Options, control controlPlane, password string,
-	say func(string)) error {
-	at := "/accepting-npm-password"
-	if err := control.carryingSecret(ctx, "mesh-accepting-npm-password", []byte(password), at); err != nil {
-		return err
-	}
-	if _, err := control.tell(ctx, "secret", "accept", o.Node, BuilderModule, "npm-password", "--from", at); err != nil {
-		return err
-	}
-	// Push so the sealed secret reaches the builder, which restarts on it and comes back credentialed.
-	if _, err := control.tell(ctx, "push", o.Node); err != nil {
-		return err
-	}
-	return nil
+// GenesisRegistrySecret is the build agent's own-secret the genesis document is sealed as (novox/hq
+// ADR 0336 §3). The build-agent manifest declares it, issued outside the mesh: only this installer
+// gives one, on genesis's node.
+const GenesisRegistrySecret = "genesis-package-registry"
+
+// GenesisRegistry is the genesis document (novox/hq ADR 0336 §3): the forge this step raised, the port
+// this node gave the package registry, its npm path, and the account this step made with its password.
+// mesh-controller's cmd/mesh-builder reads it under the same field names while the build agent's
+// npm-package-registry requirement is unbound, and prefers the binding once the gitea module is
+// assigned and it binds.
+type GenesisRegistry struct {
+	Scheme   string `json:"scheme"`
+	At       string `json:"at"`
+	Port     int    `json:"port"`
+	NpmPath  string `json:"npm-path"`
+	As       string `json:"as"`
+	Password string `json:"password"`
 }

-// PublishTheSDK dispatches a build of the SDK to the builder. The builder has its registry
-// credential by now, so the build's `npm publish` authenticates; the artifact is a `package`, built
+// genesisRegistry is the document for the forge raised here: on the machine's own loopback, where it
+// answers on the host network and where its ROOT_URL says it is (raiseGiteaServer), on the port this
+// node gave the package registry.
+func genesisRegistry(ports FoundationPorts, password string) GenesisRegistry {
+	return GenesisRegistry{Scheme: "http", At: "127.0.0.1", Port: ports.Packages,
+		NpmPath: "/api/packages/" + packagesOrg + "/npm/", As: builderGiteaUser, Password: password}
+}
+
+// deliverGenesisRegistry seals the genesis document to the build agent on this node as its
+// `genesis-package-registry` own-secret (novox/hq ADR 0336 §3), the same way the control plane's store
+// connections are delivered — carry the value in, `secret accept`, and the next push writes it sealed
+// where the build agent reads it.
+//
+// **The build agent's one way to the forge until the registry binds.** Its npm-package-registry
+// requirement is optional (ADR 0336 §1), and nothing provides it until the gitea module is assigned
+// after the base, so the sdk step (15) publishes and the base step (16) resolves with the account in
+// this document. It replaces the retired builder's `npm-password` own-secret and the `serves.port`
+// setting its carried binding took, neither of which the build agent declares.
+func deliverGenesisRegistry(ctx context.Context, o Options, control controlPlane, doc GenesisRegistry,
+	say func(string)) error {
+	raw, err := json.Marshal(doc)
+	if err != nil {
+		return err
+	}
+	at := "/accepting-" + GenesisRegistrySecret
+	if err := control.carryingSecret(ctx, "mesh-accepting-"+GenesisRegistrySecret, raw, at); err != nil {
+		return err
+	}
+	if _, err := control.tell(ctx, "secret", "accept", o.Node, BuilderModule, GenesisRegistrySecret, "--from", at); err != nil {
+		return err
+	}
+	// Push so the sealed document reaches the build agent, which reads it at its next build — and,
+	// like every push before the adoption, the bus hears the users it carries (issue 608).
+	//
+	// **Waited for until the node applied it** (issue 615). The next step asks the build agent to
+	// publish the SDK, and the agent reads the document from the file the node writes when it applies
+	// this push. A push that returned on sending let the ask race the apply: one genesis found the
+	// document in time, the next was refused, "neither its binding nor the genesis document".
+	_, err = pushNodeApplied(ctx, o, control, say)
+	return err
+}
+
+// PublishTheSDK dispatches a build of the SDK to the build agent. The agent has the genesis document by
+// now (novox/hq ADR 0336 §7), so the build's `npm publish` authenticates; the artifact is a `package`, built
 // on a public base, so this needs no toolchain — which is the whole point of doing it before the base.
 func PublishTheSDK(ctx context.Context, o Options, control controlPlane, say func(string)) error {
 	if o.SDKSource.Repository == "" {
@@ -117,24 +117,6 @@ const busModulePort = 4222
 // PortsSetting is the controller's settings key for a module's given ports.
 const PortsSetting = "ports"

-// ServesSetting is the settings key that carries what a provider serves, inside the one binding a
-// module carries rather than resolves — the builder's package binding (novox/hq 04-ISSUES/085).
-//
-// **A port given at genesis has to be a setting wherever it is read, or something puts it back.**
-// The builder reaches the package registry through a binding written in its own manifest, because
-// at genesis no module yet provides `package-registry` and so there is nothing for the controller
-// to resolve it from. That binding used to be rewritten, as text, when the installer registered the
-// builder — which a later registration from the catalogue undid silently. Set as a node's setting
-// instead, it is held by the controller rather than by the manifest, so re-registering the builder
-// leaves it where it was.
-//
-// **A settings layer is the module's, not one resource's.** The controller lays it over every file
-// of that module which merges as JSON, so `serves` lands in the package binding only because that
-// binding is the builder's one mergeable file. A second mergeable file added to the builder would
-// be given a `serves` key too, meaning nothing to whatever reads it. Worth knowing before adding
-// one.
-const ServesSetting = "serves"
-
 // setFoundationSettings tells the controller the ports this node gave a foundation module — and,
 // on an adopted node, that the registry is reached from anywhere, as a node pulls from it before it
 // has a private-network address (novox/hq ADR 0100). Done after the module is registered and before
@@ -148,13 +130,8 @@ func setFoundationSettings(ctx context.Context, o Options, control controlPlane,
 	if o.Adopted && module == RegistryModule {
 		values["expose"] = map[string]string{strconv.Itoa(DefaultPorts().Registry): "anywhere"}
 	}
-	if packages := o.Ports.orDefaults().Packages; module == BuilderModule &&
-		packages != DefaultPorts().Packages {
-		// The one binding nothing resolves: the builder dials the forge by a number it carries.
-		// The rest of the binding — the provision, the forge it is from, the account it presents —
-		// is the manifest's and stays there.
-		values[ServesSetting] = map[string]int{"port": packages}
-	}
+	// No `serves` setting for the build agent: the port given for the package registry reaches it in
+	// the genesis document (novox/hq ADR 0336 §3), and from the binding once the registry binds.
 	if len(values) == 0 {
 		return nil
 	}
@@ -68,7 +68,7 @@ func TestGivenPortsMoveOnlyTheMachinesSide(t *testing.T) {
 	if got.Places == 0 {
 		t.Fatal("nothing was rewritten")
 	}
-	storeC := containerNamed(r.Declaration, "mesh-store")
+	storeC := containerNamed(r.Declaration, "postgres")
 	if len(storeC.Ports) != 1 || storeC.Ports[0] != "5433:5432" {
 		t.Errorf("the store publishes %v", storeC.Ports)
 	}
@@ -239,6 +239,12 @@ func (c *controlRecorder) run(_ context.Context, name string, args ...string) (s
 	}
 	if name == "docker" && args[0] == "exec" {
 		c.told = append(c.told, strings.Join(args[3:], " "))
+		if strings.Join(args[3:], " ") == "broker accounts" {
+			return "accounts {}\n", nil // the composed user list, placed after every push (issue 608)
+		}
+	}
+	if name == "sh" {
+		c.told = append(c.told, "placed the bus's users")
 	}
 	return "", nil
 }
@@ -0,0 +1,134 @@
+package bootstrap
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+)
+
+// Defends novox/hq issue 608 (ADR 0331 §5, ADR 0333 §4): until the bus is adopted as the nats module,
+// every push genesis makes is followed by the installer placing the composed user list where the bus
+// reads it, and making the bus re-read it. The build agent's account was minted at step 13 and sealed
+// with that push, and the list was placed only at enrolment, so the bus refused the agent
+// ("Authorization Violation") and genesis stopped at step 15.
+
+// placing answers the controller as a mesh whose bus is or is not the nats module yet, and records
+// what was run, in order.
+func placing(adopted bool) (*asked, controlPlane) {
+	listed := "build-agent          1\n"
+	if adopted {
+		listed += "nats                 1\n"
+	}
+	runtime := &asked{}
+	runtime.answer = func(name string, args []string) (string, error) {
+		joined := strings.Join(args, " ")
+		switch {
+		case name == "sh":
+			return "", nil
+		case strings.HasSuffix(joined, "module list"):
+			return listed, nil
+		case strings.HasSuffix(joined, "broker accounts"):
+			return "accounts {\n  MESH { users = [ { user: \"anchor.build-agent\" } ] }\n}\n", nil
+		}
+		return "", nil
+	}
+	return runtime, controlPlane{container: "mesh-controller", run: runtime.run, timeout: time.Second}
+}
+
+// placedAfterThePush is whether the bus's users were placed — written at the module's bus-users path,
+// the bus told to re-read them — after the push, and how often.
+func placedAfterThePush(t *testing.T, commands []string) int {
+	t.Helper()
+	pushed, placed := -1, 0
+	for i, c := range commands {
+		if strings.Contains(c, "/mesh-controller push anchor") && pushed < 0 {
+			pushed = i
+		}
+		if strings.HasPrefix(c, "sh -c") && strings.Contains(c, busAccounts) &&
+			strings.Contains(c, "kill -s HUP "+busContainer) {
+			if pushed < 0 || i < pushed {
+				t.Fatalf("the bus's users were placed before the push that carries the account: %v", commands)
+			}
+			placed++
+		}
+	}
+	if pushed < 0 {
+		t.Fatalf("nothing was pushed: %v", commands)
+	}
+	return placed
+}
+
+func TestTheBusHearsTheBuildAgentsAccountAfterItsPush(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	runtime, control := placing(false)
+	o := Options{Node: "anchor", Wait: time.Second}
+	if _, err := installModule(context.Background(), o, control, BuilderModule, []byte(`{}`), quietly); err != nil {
+		t.Fatal(err)
+	}
+	if n := placedAfterThePush(t, runtime.commands); n != 1 {
+		t.Fatalf("the bus's users were placed %d time(s) after the build agent's push; once: %v", n, runtime.commands)
+	}
+}
+
+func TestTheGenesisDocumentsPushIsHeardByTheBusToo(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	runtime, control := placing(false)
+	o := Options{Node: "anchor", Wait: time.Second}
+	if err := deliverGenesisRegistry(context.Background(), o, control, genesisRegistry(DefaultPorts(), "pw"), quietly); err != nil {
+		t.Fatal(err)
+	}
+	if n := placedAfterThePush(t, runtime.commands); n != 1 {
+		t.Fatalf("the bus's users were placed %d time(s) after the genesis document's push; once: %v", n, runtime.commands)
+	}
+}
+
+// From the adoption on the nats module writes the list, and the installer does not (ADR 0333 §4).
+func TestOnceTheBusIsTheNatsModulesThePushPlacesNothing(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	runtime, control := placing(true)
+	o := Options{Node: "anchor", Wait: time.Second}
+	if _, err := installModule(context.Background(), o, control, BuilderModule, []byte(`{}`), quietly); err != nil {
+		t.Fatal(err)
+	}
+	if n := placedAfterThePush(t, runtime.commands); n != 0 {
+		t.Fatalf("the installer placed the bus's users over the nats module's: %v", runtime.commands)
+	}
+}
+
+// Defends novox/hq issue 615: the packages step's push is waited for until the node applied it, because
+// the sdk step right after asks the build agent for a build that reads the genesis document from the
+// file that apply writes. A push that returned on sending let the ask race the apply.
+func TestThePackagesStepWaitsUntilTheNodeAppliedTheGenesisDocument(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	runtime, control := placing(false)
+	o := Options{Node: "anchor", Wait: 3 * time.Minute}
+	if err := deliverGenesisRegistry(context.Background(), o, control, genesisRegistry(DefaultPorts(), "pw"), quietly); err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range runtime.commands {
+		if strings.Contains(c, "/mesh-controller push anchor") {
+			if !strings.HasSuffix(c, "push anchor --wait 3m0s") {
+				t.Fatalf("the genesis document's push does not wait for the node to apply it: %s", c)
+			}
+			return
+		}
+	}
+	t.Fatalf("the genesis document was never pushed: %v", runtime.commands)
+}
+
+// Every other push of genesis still returns on sending: only a push whose content the next step reads on
+// the machine waits.
+func TestAnOrdinaryPushDoesNotWait(t *testing.T) {
+	t.Setenv("TMPDIR", t.TempDir())
+	runtime, control := placing(false)
+	o := Options{Node: "anchor", Wait: time.Second}
+	if _, err := installModule(context.Background(), o, control, BuilderModule, []byte(`{}`), quietly); err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range runtime.commands {
+		if strings.Contains(c, "push anchor --wait") {
+			t.Fatalf("an ordinary push waits: %s", c)
+		}
+	}
+}
@@ -58,8 +58,20 @@ func aMeshThatAgrees(answers map[string]string) func(string, []string) (string,
 			}
 		}
 		switch {
+		case name == "sh" && len(args) == 2 && strings.Contains(args[1], "accounts.conf"):
+			return "", nil // the bus's users placed after a push (issue 608)
+		case name == "sh" && len(args) == 2 && strings.Contains(args[1], "mesh-nats-snapshot"):
+			return "", nil // the streams snapshotted before the bus's planned step (issue 590)
+		case name == "docker" && strings.HasSuffix(joined, "/mesh-controller bus"):
+			return "the bus is nats, built 53e51864, on anchor\nlast step 1: not known → 53e51864 on anchor by installer (" +
+				adoptionWhy + "): done at 2026-10-13 11:40; snapshot " + busSnapshotFile + "\n", nil
+		case name == "docker" && strings.Contains(joined, "/mesh-controller builds nats -n 1"):
+			return "nats  built 53e51864 anchor\n    image      artifact-store://nats/server@sha256:" +
+				strings.Repeat("4", 64) + "\n    bundle     artifact-store://nats/tools/blobs/sha256:" + strings.Repeat("5", 64) + "\n", nil
 		case name != "docker":
 			return "", fmt.Errorf("unexpected program %q", name)
+		case strings.HasSuffix(joined, "broker accounts"):
+			return "accounts {}\n", nil
 		case args[0] == "cp":
 			return "", nil
 		case args[0] == "container":
@@ -47,6 +47,9 @@ const (
 	// StoreSuperuserFile is where the store's superuser password lives on the machine — the
 	// postgres module's own-secret path, so genesis and adoption write the same file.
 	StoreSuperuserFile = "/var/lib/postgres/superuser.secret"
+	// StoreDataDir is where the store keeps its data — the postgres module's data directory, so
+	// genesis raises the store where the module adopts it (novox/hq ADR 0338 §1).
+	StoreDataDir = "/var/lib/mesh-store"
 	// BusControllerFile is where the controller's password on the bus lives on the machine. Not a
 	// module's path: no module reads it — the permanent controller is handed the address the
 	// temporary one was given — and genesis keeps it only so a second run puts the same account
@@ -62,7 +65,7 @@ const (
 	// What the template says, matched exactly. A template that says something else is a template
 	// this installer does not know how to make safe, and it says so rather than guessing.
 	templateStorePassword = `"POSTGRES_PASSWORD": "bootstrap"`
-	templateStoreVolumes  = `"volumes": ["mesh-store-data:/var/lib/postgresql/data"]`
+	templateStoreVolumes  = `"volumes": ["` + StoreDataDir + `:/var/lib/postgresql/data"]`
 	templateStoreURL      = "postgres:bootstrap@"

 	// BusURLPlaceholder is the controller's account in its bus address, as the template names it.
@@ -265,8 +268,8 @@ func Masking(say func(string), c RootCredentials) func(string) {
 // RefuseExistingServers stops a run that would put a made credential in front of a store raised
 // by an earlier installer with the template's.
 //
-// The store's password is set by initdb, once, on an empty volume. A machine that already holds
-// `mesh-store-data` and has no credential file was raised with `bootstrap`, and minting a new
+// The store's password is set by initdb, once, on an empty data directory. A machine that already holds
+// a cluster in the store's data directory and has no credential file was raised with `bootstrap`, and minting a new
 // value here would make a bundle that dials with a password the server does not have — failing
 // three steps later, in the schemas, with nothing pointing back here. Refused by name instead,
 // with the way forward.
@@ -278,11 +281,14 @@ func RefuseExistingServers(ctx context.Context, run Runner, c RootCredentials) e
 	if !c.StoreMade {
 		return nil
 	}
-	if _, err := run(ctx, "docker", "volume", "inspect", "mesh-store-data"); err != nil {
-		return nil // no such volume: a fresh machine, which is the case this installer makes
+	// Where the store keeps its data, as the postgres module does (novox/hq ADR 0338 §2): a cluster
+	// there is one initdb already set a password for. The docker volume genesis used before is not
+	// the store's data any more, and a machine holding only that is not refused.
+	if _, err := run(ctx, "test", "-e", StoreDataDir+"/pgdata/PG_VERSION"); err != nil {
+		return nil // no cluster there: a fresh machine, which is the case this installer makes
 	}
 	return fmt.Errorf(
-		"this machine already holds the store's data (volume mesh-store-data) and no credential at %s, so it was raised "+
+		"this machine already holds the store's data (in "+StoreDataDir+") and no credential at %s, so it was raised "+
 			"by an earlier installer with the template's password. A new one made here would not open it. "+
 			"Put the password the store has into %s (0600, the value alone) and run again; then change it "+
 			"on the server and accept the new value — this installer does not rotate a running store",
@@ -311,7 +317,7 @@ func RewriteRoot(r *Rewritten, c RootCredentials) (RootRewrite, error) {
 		return out, err
 	}
 	if bundle, err = replaceOnce(bundle, templateStoreVolumes,
-		`"volumes": ["mesh-store-data:/var/lib/postgresql/data", "`+StoreSuperuserFile+":"+storeSuperuserMount+`:ro"]`,
+		`"volumes": ["`+StoreDataDir+`:/var/lib/postgresql/data", "`+StoreSuperuserFile+":"+storeSuperuserMount+`:ro"]`,
 		"the store's volumes"); err != nil {
 		return out, err
 	}
@@ -59,7 +59,7 @@ func TestTheProducedBundleCarriesNoWellKnownCredential(t *testing.T) {
 		switch x := res.(type) {
 		case *declaration.Container:
 			switch x.Name {
-			case "mesh-store":
+			case "postgres":
 				store = true
 				if _, has := x.Env["POSTGRES_PASSWORD"]; has {
 					t.Error("the store still takes its password from its environment")
@@ -0,0 +1,163 @@
+package bootstrap
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-host/internal/declaration"
+)
+
+// Defends novox/hq ADR 0338 (issue 609): genesis raises its store as the postgres module's server, so
+// the store step adopts it as it runs. Until then the bundle raised `mesh-store`, on another image, in a
+// docker volume, and genesis stopped at step 17 of 24.
+
+// theStoreGenesisRaises is the store container of the bundle as the installer applies it: rewritten for
+// this machine's credentials, so its password is the file the module reads too.
+func theStoreGenesisRaises(t *testing.T) *declaration.Container {
+	t.Helper()
+	r := producedBundle(t)
+	store, err := storeIn(r.Declaration)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return store
+}
+
+// The bundle's store is exactly the catalogue's postgres module's server, read from the module's own
+// manifest (ADR 0338 §1): its name, its image (so a drift of either pin fails here), where its data is,
+// and the file its superuser password is read from, with the environment that says so.
+func TestTheBundleRaisesTheStoreAsTheCataloguesPostgresModuleDeclaresIt(t *testing.T) {
+	manifest := theCataloguesModule(t, "postgres")
+	var m struct {
+		Resources []struct {
+			ID      string            `json:"id"`
+			Type    string            `json:"type"`
+			Name    string            `json:"name"`
+			Image   string            `json:"image"`
+			Env     map[string]string `json:"env"`
+			Ports   []string          `json:"ports"`
+			Volumes []string          `json:"volumes"`
+		} `json:"resources"`
+	}
+	if err := json.Unmarshal(manifest, &m); err != nil {
+		t.Fatal(err)
+	}
+	ours := theStoreGenesisRaises(t)
+	found := false
+	for _, r := range m.Resources {
+		if r.Type != "container" || r.ID != "server" {
+			continue
+		}
+		found = true
+		if ours.Name != r.Name {
+			t.Errorf("the bundle raises the store as %q; the module's server is %q", ours.Name, r.Name)
+		}
+		if ours.Image != r.Image {
+			t.Errorf("the bundle raises the store on %s; the module pins %s — the two pins move together", ours.Image, r.Image)
+		}
+		for _, key := range []string{"POSTGRES_PASSWORD_FILE", "PGDATA"} {
+			if ours.Env[key] != r.Env[key] {
+				t.Errorf("the bundle's store has %s=%q; the module's %q", key, ours.Env[key], r.Env[key])
+			}
+		}
+		if _, has := ours.Env["POSTGRES_PASSWORD"]; has {
+			t.Error("the bundle's store takes its password from its environment; the module reads a file")
+		}
+		// The module's own directory for its state is <data root>/<module>, where genesis keeps the
+		// superuser's file (StoreSuperuserFile).
+		var theirs []string
+		for _, v := range r.Volumes {
+			theirs = append(theirs, strings.ReplaceAll(v, "${dir:state}", "/var/lib/postgres"))
+		}
+		if strings.Join(ours.Volumes, " ") != strings.Join(theirs, " ") {
+			t.Errorf("the bundle's store mounts %v; the module's %v", ours.Volumes, theirs)
+		}
+		if strings.Join(ours.Ports, " ") != strings.Join(r.Ports, " ") {
+			t.Errorf("the bundle publishes the store on %v; the module on %v", ours.Ports, r.Ports)
+		}
+		// And the store step's own check agrees: by name and image, before anything is registered.
+		if err := serverMatchesFoundation(manifest, ours, "postgres"); err != nil {
+			t.Errorf("the store step would refuse the store the bundle raises: %v", err)
+		}
+	}
+	if !found {
+		t.Fatal("the postgres module declares no server container")
+	}
+}
+
+// The store's data directory is made by the bundle before the store starts, owned by the image's
+// postgres user, as the module declares it (ADR 0338 §1, and the measurement under its §5).
+func TestTheBundleMakesTheStoresDataDirectoryAsTheModuleDoes(t *testing.T) {
+	r := producedBundle(t)
+	at, store := -1, -1
+	for i, res := range r.Declaration.Resources {
+		if d, ok := res.(*declaration.Directory); ok && d.Path == StoreDataDir {
+			at = i
+			if d.Mode != "0700" || d.Owner != "999:70" {
+				t.Errorf("the store's data directory is made %s %s; the module makes it 0700 999:70", d.Mode, d.Owner)
+			}
+		}
+		if res.Identity() == StoreID {
+			store = i
+		}
+	}
+	if at < 0 || store < 0 || at > store {
+		t.Fatalf("the store's data directory %s is not made before the store (directory at %d, store at %d)", StoreDataDir, at, store)
+	}
+}
+
+// No step of the bundle and no step of the installer names `mesh-store`, which is the seat's name only
+// (ADR 0338 §2): every step that reaches the store reaches the container the bundle raised.
+func TestNoStepReachesTheStoreByTheSeatsName(t *testing.T) {
+	text := string(theRealBundle(t))
+	for _, by := range []string{`"in": "mesh-store"`, `container:mesh-store`, `exec mesh-store`, `"name": "mesh-store"`, `mesh-store-data`} {
+		if strings.Contains(text, by) {
+			t.Errorf("the bundle still reaches the store as %s", by)
+		}
+	}
+	store := theStoreGenesisRaises(t)
+	if foundationStore != store.Name {
+		t.Errorf("the packages step reaches the store as %q; the bundle raises it as %q", foundationStore, store.Name)
+	}
+	r := producedBundle(t)
+	for _, res := range r.Declaration.Resources {
+		if a, ok := res.(*declaration.Action); ok && a.In != "" && a.In != store.Name && strings.Contains(a.ID, "database") {
+			t.Errorf("the step %s reaches the store in %q", a.ID, a.In)
+		}
+	}
+}
+
+// The installer's refusal to raise a store over data it cannot open looks where the store keeps its data
+// (ADR 0338 §2): a cluster there and no credential is refused; the old docker volume alone is not.
+func TestTheRefusalOverExistingDataLooksInTheStoresDirectory(t *testing.T) {
+	made := RootCredentials{Store: "s", Bus: "b", StoreMade: true}
+	machine := func(cluster, volume bool) Runner {
+		return func(_ context.Context, name string, args ...string) (string, error) {
+			joined := name + " " + strings.Join(args, " ")
+			switch {
+			case joined == "test -e "+StoreDataDir+"/pgdata/PG_VERSION":
+				if cluster {
+					return "", nil
+				}
+			case strings.HasPrefix(joined, "docker volume inspect"):
+				if volume {
+					return "[]", nil
+				}
+			}
+			return "", errors.New("exit status 1")
+		}
+	}
+	err := RefuseExistingServers(context.Background(), machine(true, false), made)
+	if err == nil || !strings.Contains(err.Error(), StoreDataDir) {
+		t.Fatalf("a cluster in %s and no credential was not refused naming it: %v", StoreDataDir, err)
+	}
+	if err := RefuseExistingServers(context.Background(), machine(false, true), made); err != nil {
+		t.Fatalf("a machine holding only the old volume was refused: %v", err)
+	}
+	if err := RefuseExistingServers(context.Background(), machine(true, false), RootCredentials{Store: "s"}); err != nil {
+		t.Fatalf("a kept credential was refused: %v", err)
+	}
+}
@@ -89,7 +89,7 @@ func TestAFoundationThatIsUpAndAnsweringIsAccepted(t *testing.T) {
 	// run-once and scheduled shapes are excluded on purpose — a step that has exited is not a
 	// fault. The name is `temp-mesh-controller` because the permanent one is a module and takes the
 	// plain name (novox/hq ADR 0067), which is what makes the two of them coexist at all.
-	want := []string{"mesh-store", "mesh-broker-nats", "temp-mesh-controller"}
+	want := []string{"postgres", "mesh-broker-nats", "temp-mesh-controller"}
 	if len(verified.Running) != len(want) {
 		t.Fatalf("confirmed %v running, want %v", verified.Running, want)
 	}
Author	SHA1	Message	Date
mesh-admin	12bc6a56a3	Merge pull request 'Adopt genesis's bus through the bus's planned step, its streams snapshotted first (issue 590, hq ADR 0333 §3)' (#108 ) from fix/590-adopt-the-bus-as-its-planned-step into main	2026-10-13 11:11:41 +00:00
jochen	cdcfcd9380	Adopt genesis's bus through the bus's planned step, its streams snapshotted first (hq issue 590, ADR 0333 §3) mesh/merge-gate head cdcfcd938016 merged into trunk 130c5d98a601 — pass: the change touches no module of the mesh's graph Details mesh/repo-check head cdcfcd938016 merged into trunk 130c5d98a601 — pass: its merge-check.sh passed Details mesh/delivery delivered Details The broker step sent the nats module with a plain push, and the controller refuses a push that would replace the bus: that is a planned step, bus upgrade, which snapshots the streams first and checks them after (ADR 0236). Genesis stopped at step 18. The step now snapshots every stream with the module's own snapshot program (no backup holder exists yet to be asked), asks bus upgrade with that snapshot and why, says the one restart, and waits until the bus runs the module's image, answers, and the controller ends the step done. The bundle's bus runs the release the module's image is built on (2.11.17, by the same digest, where it ran 2.10.29), so the step changes no server release and is said reversible.	2026-10-13 11:47:10 +02:00
mesh-admin	130c5d98a6	Merge pull request 'Build the Go toolchain at genesis's base step, beside the base (issue 616)' (#106 ) from fix/616-the-base-builds-every-genesis-toolchain into main	2026-10-13 09:23:04 +00:00
jochen	8108dd5c23	Build the Go toolchain at genesis's base step, beside the base (hq issue 616) mesh/merge-gate head 8108dd5c23c6 merged into trunk f0d39b4a4ab0 — pass: the change touches no module of the mesh's graph Details mesh/repo-check head 8108dd5c23c6 merged into trunk f0d39b4a4ab0 — pass: its merge-check.sh passed Details mesh/delivery delivered Details Genesis's base step built only mesh-tools, the TypeScript toolchain. The store's and the bus's modules carry Go bundles, compiled in mesh-tools-go, so genesis stopped at the store step: "this mesh holds no copy of it. Build mesh-tools-go first". The base step now builds mesh-tools-go too, from --tools-go-source or the repository beside --tools-source, and a test holds every toolchain a genesis module's bundles compile in, read from the catalogue, to the ones the step builds.	2026-10-13 11:13:44 +02:00
mesh-admin	f0d39b4a4a	Merge pull request 'Wait until the node applied the genesis document before the sdk step asks for a build (issue 615)' (#105 ) from fix/615-wait-for-the-genesis-document into main	2026-10-13 09:08:59 +00:00
jochen	89fd0c06e1	Wait until the node applied the genesis document before the sdk step asks for a build (hq issue 615) mesh/merge-gate head 89fd0c06e102 merged into trunk 17038b2a074b — pass: the change touches no module of the mesh's graph Details mesh/repo-check head 89fd0c06e102 merged into trunk 17038b2a074b — pass: its merge-check.sh passed Details mesh/delivery delivered Details The packages step sealed the build agent its genesis document and pushed, and the push returned as soon as it was sent. The sdk step then asked for the SDK's build at once, and the agent reads the document from the file the node writes when it applies that push: one genesis found it in time, the next was refused for having neither a binding nor the document. That one push now waits until the node reports it applied it (push --wait); every other push still returns on sending.	2026-10-13 10:59:45 +02:00
mesh-admin	17038b2a07	Merge pull request 'Raise genesis's store as the postgres module's server, so the store step adopts it as it runs (issue 609, hq ADR 0338)' (#104 ) from fix/609-genesis-raises-the-store-as-postgres into main	2026-10-13 08:55:41 +00:00
jochen	4dde21f0ab	Raise genesis's store as the postgres module's server, so the store step adopts it as it runs (hq issue 609, ADR 0338) mesh/merge-gate head 4dde21f0ab20 merged into trunk 7d1d6bffe30c — pass: the change touches no module of the mesh's graph Details mesh/repo-check head 4dde21f0ab20 merged into trunk 7d1d6bffe30c — pass: its merge-check.sh passed Details mesh/delivery delivered Details The bundle raised the store as mesh-store, on upstream postgres, in a docker volume; the postgres module keeps it as postgres, on its pgvector image, in /var/lib/mesh-store owned 999:70, reading its superuser password from a file. The store step refused, and genesis stopped at step 17 of 24. The bundle now raises the store with the module's name, image, data directory and password file, and every step of the bundle and the installer reaches it by that name. The refusal to raise a store over data it cannot open looks for a cluster in the store's directory, no longer for the old volume.	2026-10-13 10:47:53 +02:00
mesh-admin	7d1d6bffe3	Merge pull request 'Place the bus's users after every push until the bus is adopted (issue 608)' (#103 ) from fix/608-place-the-bus-users-after-every-push into main	2026-10-13 05:00:42 +00:00
jochen	7283209d1a	Place the bus's users after every push until the bus is adopted (hq issue 608) mesh/merge-gate head 7283209d1abc merged into trunk 64f0ab405101 — pass: the change touches no module of the mesh's graph Details mesh/repo-check head 7283209d1abc merged into trunk 64f0ab405101 — pass: its merge-check.sh passed Details mesh/delivery delivered Details The bus reads its user list from a file that, until the broker step adopts it as the nats module, only the installer writes, and the installer wrote it only at enrolment. The build agent's account, minted with step 13's push, never reached the bus; the agent was refused (Authorization Violation) and the sdk step's build waited until it was killed. Every push genesis makes now places the composed list and has the bus re-read it, until the nats module is registered (ADR 0331 §5, ADR 0333 §4).	2026-10-13 06:58:39 +02:00
mesh-admin	64f0ab4051	Merge pull request 'genesis: seal the build agent the forge it raised, in place of the builder's npm-password (hq issue 121, ADR 0336)' (#102 ) from fix/121-genesis-package-registry into main	2026-10-13 03:37:15 +00:00
jochen	5f147fe6b9	Seal the build agent the forge genesis raised, in place of the builder's npm-password (hq issue 121, ADR 0336) mesh/merge-gate head 5f147fe6b9c7 merged into trunk 0d11b4fc930d — pass: the change touches no module of the mesh's graph Details mesh/repo-check head 5f147fe6b9c7 merged into trunk 0d11b4fc930d — pass: its merge-check.sh passed Details mesh/delivery delivered Details mesh/delivery-group group fix/121-genesis-package-registry delivered: every member is delivered Details The build agent declares neither the retired builder's npm-password own-secret nor a serves setting, so the packages step handed its credential to nothing and genesis's sdk step had no way to publish. The packages step now seals the genesis-package-registry own-secret to build-agent: the forge on this node's loopback, the port given for the package registry, its npm path, and the mesh-builder account with its password. setFoundationSettings no longer gives the builder a serves.port.	2026-10-13 03:01:35 +02:00