A container publishes only a port its module declares (hq issue 227)

The short form is a question the mesh answers: "80" means publish what the
software calls 80, and the mesh fills in the machine's half from the port it
assigned. It can only assign one for a port the module declared, so a number
appearing nowhere in listens gets no assignment and reaches the machine as
written — which is how the photo module asked for port 80 on the node whose
reverse proxy holds it.

Four modules publish 80 quite safely, because they declare 80. The difference
is the declaration, not the number. A catalogue-wide test now says so; it
names all three offenders against the catalogue as it was.

Dockerfile

@@ -1,5 +1,11 @@
-ARG GO_BASE=golang:1.25-alpine
-# The control plane's image.
+# The Go it builds with, pinned here because genesis builds this file with no arguments (novox/hq
+# issue 223) — the Makefile passes the same digest. A tag older than go.mod asks for is how
+# `make image` broke once before (issue 146).
+ARG GO_BASE=golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c
+# The control plane's image — for genesis and the lab only. The mesh runs the controller as a Go
+# bundle the host starts as a process (module.json; novox/hq issue 213), and builds no image of it.
+# Genesis builds this file and raises it as the container the process replaces on the first push
+# (mesh-host internal/bootstrap, novox/hq issue 223).
 #
 # novox/hq ADR 0006: this image is pinned by digest in the bundle the host carries, fetched on a
 # machine where no mesh exists yet, and run before there is anything to check it against. So it

Makefile

@@ -27,17 +27,21 @@ build:
 IMAGE ?= mesh-controller:$(VERSION)
 DEV_TAG ?= mesh-controller:development
 
-# The base the module declares, read from the manifest rather than written here twice.
+# The Go base the image is built on.
 #
 # **`make image` was broken and stayed broken**, because the Dockerfile's fallback base was a Go
 # older than go.mod asks for: every build died at `go mod download` with "go.mod requires go >=
 # 1.26.0", and the pipeline never saw it because the pipeline passes the declared base in. Anybody
 # building the image by hand hit it and had to find the digest themselves (novox/hq 04-ISSUES/146,
 # what it cost).
-GO_BASE ?= $(shell python3 -c "import json;print(next(o['image'] for o in json.load(open('module.json'))['build']['on'] if o['arg']=='GO_BASE'))" 2>/dev/null)
+#
+# **Pinned here since the manifest stopped building an image** (novox/hq issue 213): the mesh builds
+# the controller as a Go bundle with its own toolchain, and only `make image` — genesis and the lab —
+# still needs a Go base. The digest is the one the manifest declared until then.
+GO_BASE ?= golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c
 
 image:
-	@test -n "$(GO_BASE)" || { echo "module.json declares no GO_BASE; pass GO_BASE=<image> or fix the manifest"; exit 1; }
+	@test -n "$(GO_BASE)" || { echo "no GO_BASE; pass GO_BASE=<image>"; exit 1; }
 	docker build --build-arg GO_BASE=$(GO_BASE) --build-arg VERSION=$(VERSION) -t $(IMAGE) -t $(DEV_TAG) .
 	@echo
 	@docker image inspect $(IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'
@@ -48,7 +52,7 @@ BUILDER_IMAGE ?= mesh-builder:$(VERSION)
 BUILDER_DEV_TAG ?= mesh-builder:development
 
 builder-image:
-	@test -n "$(GO_BASE)" || { echo "module.json declares no GO_BASE; pass GO_BASE=<image> or fix the manifest"; exit 1; }
+	@test -n "$(GO_BASE)" || { echo "no GO_BASE; pass GO_BASE=<image>"; exit 1; }
 	docker build --build-arg GO_BASE=$(GO_BASE) -f cmd/mesh-builder/Dockerfile -t $(BUILDER_IMAGE) -t $(BUILDER_DEV_TAG) .
 	@echo
 	@docker image inspect $(BUILDER_IMAGE) --format 'built {{.RepoTags}}  {{.Size}} bytes'

README.md

@@ -193,6 +193,13 @@ passes every check that only looks at the message.
 
 ## The image
 
+**The mesh no longer runs the controller from it** (novox/hq issue 213). The module declares a Go
+bundle, `controller`, which the host on the controller's machine unpacks and runs as the process
+`mesh-controller` under the account of the same name (ADR 0188 §1, §3). The image stays for what
+still runs a container of the controller: genesis, which raises the first controller from it and
+installs the module from its manifest (mesh-host `internal/bootstrap`), and the lab. Neither is the
+mesh's own build any more — `make image` builds it.
+
 `FROM scratch`, holding one statically linked binary and nothing else — no shell, no package
 manager, no libc, no CA certificates.
 

cmd/mesh-controller/addresses_test.go

@@ -145,7 +145,7 @@ func TestTheRegistryTrustAndEveryImageFollowThePortTheNodeGaveTheStore(t *testin
 //
 // Composed from the control plane's own manifest against a real inventory: the store's module is
 // given 6852 on this node the way genesis or an operator gives it, and the control plane's
-// container is told so beside the sealed connection genesis wrote.
+// process is told so beside the sealed connection genesis wrote.
 func TestTheControlPlaneIsToldWhereTheNodePutTheStoreAndTheBroker(t *testing.T) {
 	open := aMesh(t)
 	ctx := t.Context()
@@ -157,8 +157,8 @@ func TestTheControlPlaneIsToldWhereTheNodePutTheStoreAndTheBroker(t *testing.T)
 	if err != nil {
 		t.Fatal(err)
 	}
-	control, err := withSeatPorts(m).Resolve([]catalogue.Built{{Name: "server", Kind: catalogue.ArtifactImage,
-		Reference: "registry.example/control@" + aDigest}})
+	control, err := withSeatPorts(m).Resolve([]catalogue.Built{{Name: "controller", Kind: catalogue.ArtifactBundle,
+		Reference: "https://registry.example/mesh-controller/controller.tar.gz", Digest: aDigest}})
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -200,12 +200,12 @@ func TestTheControlPlaneIsToldWhereTheNodePutTheStoreAndTheBroker(t *testing.T)
 
 	var env map[string]any
 	for _, r := range composed(t, open, "anchor").Resources {
-		if r["id"] == "mesh-controller.server" {
+		if r["id"] == "mesh-controller.controller" {
 			env, _ = r["env"].(map[string]any)
 		}
 	}
 	if env == nil {
-		t.Fatal("the control plane's container is not in its own node's declaration")
+		t.Fatal("the control plane's process is not in its own node's declaration")
 	}
 	for key, want := range map[string]string{
 		"MESH_STORE_INVENTORY_PORT": "6852",
@@ -238,7 +238,7 @@ func withSeatPorts(m catalogue.Manifest) catalogue.Manifest {
 	out := m
 	out.Resources = nil
 	for _, r := range m.Resources {
-		if r["type"] != "container" {
+		if r["type"] != "container" && r["type"] != "process" {
 			out.Resources = append(out.Resources, r)
 			continue
 		}

cmd/mesh-controller/build.go

@@ -558,6 +558,10 @@ func takeIn(ctx context.Context, inv *inventory.Inventory, result link.BuildResu
 		}
 		return manifest, kept, err
 	}
+	// The keep set just moved, and new bytes just landed (novox/hq ADR 0189). Asked here rather
+	// than on a timer of its own: this is the only moment either is true. Never fatal — the build
+	// worked and the module is registered.
+	collect(ctx, inv)
 	return manifest, kept, nil
 }
 

cmd/mesh-controller/check.go

@@ -7,6 +7,7 @@ import (
 	"os"
 	"path/filepath"
 	"sort"
+	"strings"
 
 	"github.com/novox/mesh-controller/internal/catalogue"
 )
@@ -90,6 +91,17 @@ func moduleCheck(paths []string, out io.Writer) error {
 		if len(m.Invokes) > 0 {
 			fmt.Fprintf(out, ", invokes %s", joinInvokes(m.Invokes))
 		}
+		// The state it keeps and reads (novox/hq ADR 0201), so a reviewer sees what lands on the bus.
+		if len(m.State) > 0 {
+			kept := make([]string, 0, len(m.State))
+			for _, s := range m.State {
+				kept = append(kept, s.Name)
+			}
+			fmt.Fprintf(out, ", keeps state %s", strings.Join(kept, ", "))
+		}
+		if len(m.Reads) > 0 {
+			fmt.Fprintf(out, ", reads %s", strings.Join(m.Reads, ", "))
+		}
 		fmt.Fprintln(out)
 	}
 	if failed > 0 {

cmd/mesh-controller/collect.go

@@ -0,0 +1,123 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/artifacts"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// Letting the artifact store go of what the mesh no longer keeps (novox/hq ADR 0189, issue 108).
+//
+// **Run where the records change.** A build is the moment new bytes landed in the store and the
+// moment the keep set moved, so it is the moment to say what may go — and it needs no timer of
+// its own. Reclaiming the bytes is the store's own nightly step; this only decides.
+//
+// Never fatal to a build. The build succeeded, the module is registered, and a store that could
+// not be reached is a thing to say rather than a reason to undo any of that. The next build asks
+// again, and the references it could not collect are still uncollected, so nothing is lost by
+// having failed.
+
+// collect asks the store to let go of everything the mesh made and no longer keeps, and records
+// what it let go of. Says what it did and what it could not; returns nothing, because nothing
+// upstream should branch on it.
+func collect(ctx context.Context, inv *inventory.Inventory) {
+	references, err := inv.ToCollect(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "could not work out what the artifact store may let go of: %v\n", err)
+		return
+	}
+	if len(references) == 0 {
+		return
+	}
+	shelf, err := inv.Catalogue(ctx)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "could not read the catalogue to find the artifact store: %v\n", err)
+		return
+	}
+	// As the mesh reaches it from the network. Empty means the store is not on the network — on a
+	// mesh being raised it is not yet, and there the store holds one build of anything and has
+	// nothing to collect.
+	address, err := artifactStoreAddress(ctx, inv, shelf, "")
+	if err != nil || address == "" {
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "could not find the artifact store to collect from: %v\n", err)
+		}
+		return
+	}
+
+	// **Bounded, because this runs inside somebody's build.** The first sweep of a mesh that has
+	// never collected has the whole history to get through, and a person waiting on `build` should
+	// not pay for it. Two bounds, and what is left over is simply offered again next time —
+	// builds are frequent, and the point is that the store stops growing, not that it empties
+	// tonight.
+	within, stop := context.WithTimeout(ctx, sweepBudget)
+	defer stop()
+	store := artifacts.Store{Address: address}
+
+	var done []string
+	var left, skipped int
+	for i, reference := range references {
+		if i >= mostPerSweep || within.Err() != nil {
+			left = len(references) - i
+			break
+		}
+		err := store.LetGo(within, reference)
+		if err == nil || errors.Is(err, artifacts.Gone) {
+			// Gone is the outcome wanted, already true. Recorded so the next sweep does not ask
+			// again for ever.
+			done = append(done, reference)
+			continue
+		}
+		if errors.Is(err, artifacts.ErrNotOurs) {
+			// **A fact about this record, so this record is skipped** (novox/hq issue 226). Not
+			// marked collected — the mesh did not remove it and should not claim to — and not a
+			// reason to stop, because the store was never asked. One of these at the front of
+			// the oldest-first order ended every sweep until this.
+			skipped++
+			if skipped == 1 {
+				fmt.Fprintf(os.Stderr,
+					"the sweep will not address %s and went on: %v\n", reference, err)
+			}
+			continue
+		}
+		// **Stopped at the first refusal by the STORE, not pushed through.** A store that refuses
+		// one refuses all of them — deletion disabled, the store down, the network gone — so
+		// going on would be a hundred identical failures and a hundred identical log lines in
+		// front of whoever was building something.
+		fmt.Fprintf(os.Stderr, "the artifact store kept %s, so nothing more was asked of it: %v\n",
+			reference, err)
+		left = len(references) - i
+		break
+	}
+
+	if len(done) > 0 {
+		// Recorded outside `within`: the deletions happened, and losing the record of them because
+		// the sweep ran out of budget would mean asking about them again for ever.
+		if err := inv.MarkCollected(ctx, done); err != nil {
+			fmt.Fprintf(os.Stderr, "the store let go of %d artifact(s) and the record of it did not keep: %v\n",
+				len(done), err)
+			return
+		}
+		fmt.Fprintf(os.Stderr, "the artifact store let go of %d artifact(s) the mesh no longer keeps\n",
+			len(done))
+	}
+	if left > 0 {
+		fmt.Fprintf(os.Stderr, "%d more to collect; the next build asks again\n", left)
+	}
+	if skipped > 0 {
+		fmt.Fprintf(os.Stderr, "%d artifact(s) the sweep will not address were skipped\n", skipped)
+	}
+}
+
+// mostPerSweep is how many artifacts one sweep will ask about. Enough that a mesh building
+// several times a day converges within days of this landing; small enough that no single build
+// waits on the whole backlog.
+const mostPerSweep = 200
+
+// sweepBudget is the longest a sweep will keep a build waiting.
+const sweepBudget = 60 * time.Second

cmd/mesh-controller/plans_one_at_a_time_test.go

@@ -0,0 +1,47 @@
+package main
+
+import (
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// novox/hq issue 213: for the moment a machine hands its controller over, the container and the
+// process both run the plan timer on one store. Only the one holding the plans moves them; the other
+// leaves them alone, and moves them once they are let go.
+func TestAControllerLeavesThePlansToTheOneHoldingThem(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	now := time.Now().UTC()
+	// Every tier done: the next step is the plan's last, and needs nothing but the store.
+	plan := inventory.Plan{ID: "plan-213", Repository: "r", Commit: "abc", Created: now, Updated: now,
+		State: inventory.PlanRolling, Tier: 1, Tiers: [][]string{{"app"}},
+		Modules: map[string]*inventory.PlanModule{"app": {State: "built"}}}
+	if err := open.inventory.SavePlan(ctx, plan); err != nil {
+		t.Fatal(err)
+	}
+
+	// The other controller: its own connections to the same store, holding the plans.
+	other, err := inventory.Open(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(other.Close)
+	release, err := other.HoldPlans(ctx, false)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(release) // before the close above: a pool waits for a connection still held
+
+	advancePlans(ctx, open)
+	if p, err := open.inventory.PlanByID(ctx, "plan-213"); err != nil || !p.Open() {
+		t.Fatalf("a controller moved a plan another held: %+v %v", p, err)
+	}
+
+	release()
+	advancePlans(ctx, open)
+	if p, err := open.inventory.PlanByID(ctx, "plan-213"); err != nil || p.State != inventory.PlanDone {
+		t.Fatalf("the plan did not move once it was let go: %+v %v", p, err)
+	}
+}

cmd/mesh-controller/push.go

@@ -747,6 +747,16 @@ func issueMemberships(ctx context.Context, open *stores, server *link.Server, se
 	if !ok {
 		return nil
 	}
+	// **Every declared state's bucket, before the memberships that name it** (novox/hq ADR 0201). The
+	// raise at start asserts them too, but a module registered and assigned since would otherwise have
+	// its bucket only after the control plane next restarts — found the first time a module declared
+	// state: its bundle asked for a bucket that did not exist. Idempotent and cheap; a failure is said
+	// and the push stands, as a membership's is.
+	if buckets, err := open.inventory.DeclaredBuckets(ctx); err != nil {
+		fmt.Printf("  the modules' state could not be read, so no bucket was asserted: %v\n", err)
+	} else if _, err := broker.RaiseBuckets(broker.OnConn(bus.Conn), buckets); err != nil {
+		fmt.Printf("  the modules' state could not be asserted on the bus: %v — the next push tries again\n", err)
+	}
 	// The declarations are sent and recorded by now; a membership that cannot be issued is said
 	// and does not unsay them. Every runtime without one serves the shape it derives (ADR 0160), so
 	// the push stands, the first failure is named once, and the next push tries again.
@@ -898,6 +908,21 @@ func raiseTheBus(ctx context.Context, inv *inventory.Inventory, address string)
 	if err := broker.RaiseSeats(js, inventory.MeshSeats(), holders); err != nil {
 		return err
 	}
+	// Every module's state (novox/hq ADR 0201), from the catalogue: a bucket exists from
+	// registration, so a module reading one may watch it before its owner runs anywhere. One that
+	// nothing declares any more is said and kept — what it holds is data.
+	buckets, err := inv.DeclaredBuckets(ctx)
+	if err != nil {
+		return err
+	}
+	undeclared, err := broker.RaiseBuckets(js, buckets)
+	if err != nil {
+		return err
+	}
+	if len(undeclared) > 0 {
+		fmt.Printf("the bus holds state nothing declares any more, kept because it is data: %s — "+
+			"removing it is a person's act\n", strings.Join(undeclared, ", "))
+	}
 	// And how every module hears what it consumes. Derived from the same records the user list is
 	// composed from, so a module the mesh grants a consumer's subjects has that consumer waiting.
 	// Done on every raise, not only when a credential is issued: every module moved onto this bus
@@ -921,8 +946,8 @@ func raiseTheBus(ctx context.Context, inv *inventory.Inventory, address string)
 		}
 		hearing++
 	}
-	fmt.Printf("the bus at %s has its streams, %d machine(s) can hear a declaration, and %d module(s) "+
-		"can hear what they consume\n", broker.BareAddress(address), len(names), hearing)
+	fmt.Printf("the bus at %s has its streams, %d machine(s) can hear a declaration, %d module(s) "+
+		"can hear what they consume, and %d bucket(s) of state\n", broker.BareAddress(address), len(names), hearing, len(buckets))
 	return nil
 }
 

cmd/mesh-controller/release_plan.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"errors"
 	"flag"
 	"fmt"
 	"sort"
@@ -296,6 +297,15 @@ func askTier(ctx context.Context, inv *inventory.Inventory, p *inventory.Plan) e
 // build's request time is not known, and such an outcome is taken as before.
 func planBuilt(ctx context.Context, open *stores, module, commit, failed string, asked time.Time) {
 	inv := open.inventory
+	// One controller works the plans at a time (novox/hq issue 213); an outcome waits its turn rather
+	// than write over what the holder is about to save. Not taken, it is still in the build records,
+	// which the holder settles the plan from (issue 214).
+	release, err := inv.HoldPlans(ctx, true)
+	if err != nil {
+		fmt.Printf("plans: %s's outcome is left to the build records: %v\n", module, err)
+		return
+	}
+	defer release()
 	plans, err := inv.OpenPlans(ctx)
 	if err != nil {
 		fmt.Printf("plans: cannot read them: %v\n", err)
@@ -342,13 +352,30 @@ func planBuilt(ctx context.Context, open *stores, module, commit, failed string,
 			fmt.Printf("%s: %s; the tiers after it are not asked\n", p.ID, p.Note)
 		}
 	}
-	advancePlans(ctx, open)
+	advanceHeld(ctx, open)
 }
 
 // advancePlans moves every open plan as far as the facts allow: a tier whose modules are all built
 // and whose gates are applied gives way to the next; the last tier done is the plan done. Called
 // after every outcome and on a timer, so a plan waiting on a machine's report moves when it comes.
+//
+// **One controller at a time** (novox/hq issue 213). A plan is read, changed and saved whole; two
+// controllers — the old and the new while a machine hands its controller over — would each ask a
+// tier the other had just asked. Taken without waiting: whoever holds the plans is moving them.
 func advancePlans(ctx context.Context, open *stores) {
+	release, err := open.inventory.HoldPlans(ctx, false)
+	if err != nil {
+		if !errors.Is(err, inventory.ErrPlansBusy) {
+			fmt.Printf("plans: cannot hold them: %v\n", err)
+		}
+		return
+	}
+	defer release()
+	advanceHeld(ctx, open)
+}
+
+// advanceHeld is advancePlans for a caller already holding the plans.
+func advanceHeld(ctx context.Context, open *stores) {
 	inv := open.inventory
 	plans, err := inv.OpenPlans(ctx)
 	if err != nil {
@@ -676,6 +703,19 @@ func plansCommand(ctx context.Context, args []string) error {
 		}
 		p.State = inventory.PlanFailed
 		p.Note = "stopped by hand at tier " + fmt.Sprint(p.Tier)
+		release, err := inv.HoldPlans(ctx, true)
+		if err != nil {
+			return err
+		}
+		defer release()
+		if p, err = inv.PlanByID(ctx, positionals[1]); err != nil {
+			return err
+		}
+		if !p.Open() {
+			return fmt.Errorf("%s is already %s", p.ID, p.State)
+		}
+		p.State = inventory.PlanFailed
+		p.Note = "stopped by hand at tier " + fmt.Sprint(p.Tier)
 		if err := inv.SavePlan(ctx, p); err != nil {
 			return err
 		}

cmd/mesh-controller/upgrades.go

@@ -315,6 +315,13 @@ func (f following) SourceMoved(ctx context.Context, m link.SourceMoved) error {
 	for _, e := range moved {
 		movedNames = append(movedNames, e.Manifest.Module)
 	}
+	// Written and its first tier asked as one act on the plans (novox/hq issue 213): a timer on
+	// another controller reading it between the two would ask the tier again.
+	release, err := inv.HoldPlans(ctx, true)
+	if err != nil {
+		return notNow(err)
+	}
+	defer release()
 	plan := planOfMerge(m, movedNames, edges)
 	if hasCycle(plan.Tiers, edges) {
 		fmt.Printf("  the last tier depends on itself: %s — built together, in no order\n",

internal/artifacts/store.go

@@ -0,0 +1,113 @@
+// Package artifacts speaks to the mesh's artifact store over its own door.
+//
+// Only what the mesh needs that nothing else does: letting go of something it put there
+// (novox/hq ADR 0189, issue 108). Pushing is the builder's, through the container runtime; reading
+// is every machine's, through its runtime. This is the one operation that belongs to the thing
+// holding the records, because it is the only one that is a decision rather than a transfer.
+package artifacts
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// Store is the artifact store at an address, as this machine reaches it.
+type Store struct {
+	// Address is `host:port` — the store as the caller reaches it now, composed and never
+	// recorded (novox/hq 04-ISSUES/102).
+	Address string
+	// HTTP is the client used; nil is a client with a modest timeout.
+	HTTP *http.Client
+}
+
+// Gone is the answer when the store does not hold it: the outcome wanted, already true.
+var Gone = errors.New("the store does not hold it")
+
+// ErrNotOurs is a reference this sweep will not address: not the mesh's own, or naming nothing
+// the store holds by digest.
+//
+// **A fact about the record, not about the store** (novox/hq issue 226). The two deserve opposite
+// responses — skip one and go on, abandon the sweep for the other — and collapsing them into "an
+// error" is how a cautious loop became one that did nothing while reporting the right number.
+var ErrNotOurs = errors.New("not a reference into the mesh's artifact store")
+
+// LetGo asks the store to drop one artifact the mesh recorded making.
+//
+// Takes a reference as the mesh records it — `artifact-store://<module>/<artifact>@sha256:…` for
+// an image, `…/blobs/sha256:…` for an archive — because that is the identity every record uses,
+// and composes the address here at the moment of use.
+//
+// Returns Gone when the store answers that it does not have it. That is not a failure: the sweep
+// wants the artifact absent, and it is. It is distinguished from success only so a caller can say
+// which of the two happened.
+func (s Store) LetGo(ctx context.Context, reference string) error {
+	// **Strict, and deliberately** (novox/hq issue 226). Only a reference the mesh keeps in its
+	// own vocabulary is addressed here. `Recorded` would read `docker.io/library/registry@sha256:…`
+	// as the mesh's too — it cannot tell one registry host from another — so normalising belongs
+	// where the provenance is known, which is the sweep reading its own build records, not here
+	// where the only job is to refuse anything that is not plainly ours.
+	path, kept := catalogue.InArtifactStore(reference)
+	if !kept {
+		// Nothing the mesh put in its own store. Refused rather than attempted: composing a
+		// delete for a reference of unknown shape is how a sweep reaches something that is not
+		// the mesh's. Distinguished from a store that refuses, so a sweep skips this and goes on.
+		return fmt.Errorf("%w: %s", ErrNotOurs, reference)
+	}
+	if s.Address == "" {
+		return fmt.Errorf("this mesh has no artifact store on its network to ask about %s", reference)
+	}
+	repository, kind, digest, err := split(path)
+	if err != nil {
+		return err
+	}
+	url := "http://" + s.Address + "/v2/" + repository + "/" + kind + "/" + digest
+
+	request, err := http.NewRequestWithContext(ctx, http.MethodDelete, url, nil)
+	if err != nil {
+		return err
+	}
+	client := s.HTTP
+	if client == nil {
+		client = &http.Client{Timeout: 30 * time.Second}
+	}
+	response, err := client.Do(request)
+	if err != nil {
+		return err
+	}
+	defer response.Body.Close()
+	switch response.StatusCode {
+	case http.StatusAccepted, http.StatusOK, http.StatusNoContent:
+		return nil
+	case http.StatusNotFound:
+		return Gone
+	case http.StatusMethodNotAllowed:
+		// The registry was started without deletion enabled. Said plainly, because the remedy is
+		// a setting on the store's module and not anything about this artifact.
+		return fmt.Errorf(
+			"the artifact store refuses deletion: its server was started without it enabled "+
+				"(REGISTRY_STORAGE_DELETE_ENABLED), so nothing can be collected until the store "+
+				"module is applied again (novox/hq ADR 0189). Asking about %s", reference)
+	default:
+		return fmt.Errorf("the artifact store answered %s for %s", response.Status, reference)
+	}
+}
+
+// split reads a recorded path into the repository, which endpoint names the thing, and the digest.
+//
+// Two shapes, which are the two the mesh records: `<repository>@sha256:<hex>` is a manifest, and
+// `<repository>/blobs/sha256:<hex>` is a blob.
+func split(path string) (repository, kind, digest string, err error) {
+	if before, after, ok := strings.Cut(path, "@sha256:"); ok {
+		return before, "manifests", "sha256:" + after, nil
+	}
+	if before, after, ok := strings.Cut(path, "/blobs/sha256:"); ok {
+		return before, "blobs", "sha256:" + after, nil
+	}
+	return "", "", "", fmt.Errorf("%w: %q names nothing the store holds by digest", ErrNotOurs, path)
+}

internal/artifacts/store_test.go

@@ -0,0 +1,117 @@
+package artifacts
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// Asking the store to let go of what the mesh no longer keeps (novox/hq ADR 0189, issue 108).
+//
+// A fake store records what it was asked to delete, so what is asserted is the mesh's decision
+// and the shape of the request — not the registry's behaviour, which is the registry's to test.
+
+func fakeStore(t *testing.T, answer int) (Store, *[]string) {
+	t.Helper()
+	var asked []string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodDelete {
+			t.Errorf("the store was asked %s %s; collecting is a delete", r.Method, r.URL.Path)
+		}
+		asked = append(asked, r.URL.Path)
+		w.WriteHeader(answer)
+	}))
+	t.Cleanup(server.Close)
+	return Store{Address: strings.TrimPrefix(server.URL, "http://")}, &asked
+}
+
+func TestAnImageAndAnArchiveAreAskedForAtTheirOwnEndpoints(t *testing.T) {
+	// The two shapes the mesh records: a manifest by digest, and a blob by digest. They are
+	// different endpoints, and asking at the wrong one answers 404 — which this would then
+	// record as collected, leaving the bytes on disk for ever while the record says otherwise.
+	store, asked := fakeStore(t, http.StatusAccepted)
+	ctx := context.Background()
+
+	image := catalogue.ArtifactStoreScheme + "web/app@sha256:abc123"
+	archive := catalogue.ArtifactStoreScheme + "web/config/blobs/sha256:def456"
+	if err := store.LetGo(ctx, image); err != nil {
+		t.Fatal(err)
+	}
+	if err := store.LetGo(ctx, archive); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{"/v2/web/app/manifests/sha256:abc123", "/v2/web/config/blobs/sha256:def456"}
+	if len(*asked) != 2 || (*asked)[0] != want[0] || (*asked)[1] != want[1] {
+		t.Fatalf("the store was asked %v; want %v", *asked, want)
+	}
+}
+
+func TestAStoreThatDoesNotHaveItAnswersGone(t *testing.T) {
+	// The outcome wanted, already true. Told apart from success only so the sweep can say which
+	// happened; both are recorded, because retrying for ever is the thing to avoid.
+	store, _ := fakeStore(t, http.StatusNotFound)
+	err := store.LetGo(context.Background(), catalogue.ArtifactStoreScheme+"web/app@sha256:abc123")
+	if !errors.Is(err, Gone) {
+		t.Fatalf("a store that does not hold it answered %v, want Gone", err)
+	}
+}
+
+func TestAStoreWithDeletionOffSaysSoAndNamesTheRemedy(t *testing.T) {
+	// The registry answers 405 when it was started without deletion enabled. The remedy is a
+	// setting on the store's module, and saying "405" would send somebody to the wrong place.
+	store, _ := fakeStore(t, http.StatusMethodNotAllowed)
+	err := store.LetGo(context.Background(), catalogue.ArtifactStoreScheme+"web/app@sha256:abc123")
+	if err == nil {
+		t.Fatal("a store that refuses deletion was read as success")
+	}
+	if !strings.Contains(err.Error(), "REGISTRY_STORAGE_DELETE_ENABLED") {
+		t.Fatalf("the refusal does not name the remedy: %v", err)
+	}
+}
+
+func TestAReferenceThatIsNotTheMeshsOwnIsNeverAsked(t *testing.T) {
+	// The whole safety of the sweep is that it names only what the mesh recorded putting there.
+	// A reference of another shape — a vendor's image, a package version — is refused rather
+	// than composed into a delete somewhere that is not the mesh's store.
+	store, asked := fakeStore(t, http.StatusAccepted)
+	for _, reference := range []string{
+		"docker.io/library/registry@sha256:abc123",
+		"registry@sha256:abc123",
+		"1.4.2",
+	} {
+		if err := store.LetGo(context.Background(), reference); err == nil {
+			t.Errorf("%s was asked about; it is not a reference into the mesh's store", reference)
+		}
+	}
+	if len(*asked) != 0 {
+		t.Fatalf("the store was asked about %v", *asked)
+	}
+}
+
+// A reference this sweep will not address says so as ErrNotOurs, which is a fact about the
+// record and not about the store (novox/hq issue 226).
+//
+// The sweep skips one and abandons itself for the other, so they cannot be the same error. The
+// first live run met a reference recorded with the store's old address, read the refusal as "the
+// store refuses everything", and collected none of the 1681 it had found.
+func TestAReferenceThisSweepWillNotAddressIsToldApartFromAStoreRefusing(t *testing.T) {
+	store, asked := fakeStore(t, http.StatusAccepted)
+	for _, reference := range []string{
+		"docker.io/library/registry@sha256:abc123",
+		"127.0.0.1:5100/mesh-tools/build@sha256:abc123",
+		"1.4.2",
+	} {
+		err := store.LetGo(context.Background(), reference)
+		if !errors.Is(err, ErrNotOurs) {
+			t.Errorf("%s answered %v; a sweep must be able to skip it and go on", reference, err)
+		}
+	}
+	if len(*asked) != 0 {
+		t.Fatalf("the store was asked about %v", *asked)
+	}
+}

internal/broker/jetstream.go

@@ -1,6 +1,7 @@
 package broker
 
 import (
+	"context"
 	"crypto/sha256"
 	"crypto/tls"
 	"crypto/x509"
@@ -12,6 +13,7 @@ import (
 	"time"
 
 	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/jetstream"
 )
 
 // The JetStream side of the controller: the one place the mesh's streams and consumers are
@@ -84,6 +86,13 @@ func pinnedTo(path string) (*tls.Config, error) {
 	return PinnedToFingerprint(want), nil
 }
 
+// OnConn is the JetStream handle over a connection the caller already holds — the control plane's
+// link — for asserting what the bus holds without dialling a second time.
+func OnConn(conn *nats.Conn) *JetStream {
+	js, _ := conn.JetStream()
+	return &JetStream{conn: conn, js: js}
+}
+
 // DialPinned is Dial with the server's certificate pinned by a fingerprint the caller already holds
 // — a module or a build machine that was handed one beside its credential, and has no file.
 func DialPinned(url, fingerprint string, opts ...nats.Option) (*JetStream, error) {
@@ -316,3 +325,50 @@ func retentionOf(r Retention) nats.RetentionPolicy {
 		return nats.LimitsPolicy
 	}
 }
+
+// EnsureBucket creates a module's bucket if it is absent and brings its options to match if it is
+// present (novox/hq ADR 0201).
+//
+// **An update, never a delete and recreate**, for the reason a stream is updated: recreating
+// discards what the bucket holds, and what a module's state holds is data. The mesh's caps are
+// asserted with the owner's options, so a bucket made by hand converges to them.
+func (j *JetStream) EnsureBucket(b Bucket) error {
+	history := b.History
+	if history == 0 {
+		history = 1
+	}
+	js, err := jetstream.New(j.conn)
+	if err != nil {
+		return err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	if _, err := js.CreateOrUpdateKeyValue(ctx, jetstream.KeyValueConfig{
+		Bucket:       b.Bucket(),
+		Description:  b.Why(),
+		History:      uint8(history),
+		TTL:          time.Duration(b.TTLSeconds) * time.Second,
+		MaxValueSize: StateMaxValueBytes,
+		MaxBytes:     StateMaxBytes,
+		Storage:      jetstream.FileStorage,
+	}); err != nil {
+		return fmt.Errorf("asserting bucket %s: %w", b.Bucket(), err)
+	}
+	return nil
+}
+
+// BucketNames is every key-value bucket on the server, the mesh's and anybody else's.
+func (j *JetStream) BucketNames() ([]string, error) {
+	js, err := jetstream.New(j.conn)
+	if err != nil {
+		return nil, err
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	lister := js.KeyValueStoreNames(ctx)
+	var out []string
+	for name := range lister.Name() {
+		out = append(out, name)
+	}
+	return out, lister.Error()
+}

internal/broker/membership.go

@@ -45,6 +45,11 @@ type Membership struct {
 	// module that must tell the mesh from the world, the route proxy serving an internal name, reads
 	// it here rather than keeping a definition of its own.
 	Mesh []string `json:"mesh,omitempty"`
+	// State is every bucket this module's code may reach, by the name it uses for each, and whether
+	// it may write it (novox/hq ADR 0201): the runtime answers a bundle's state verbs from this list
+	// and refuses, with the reason, what is not on it — the bus enforces only the union over every
+	// module on the machine.
+	State []StateIssued `json:"state,omitempty"`
 }
 
 // Served is one address a tool is answered on.
@@ -103,6 +108,7 @@ func MembershipFor(node string, d Declared, where Placements) Membership {
 			m.Seats = append(m.Seats, SeatServed{Seat: s.Name, Verb: verb, Subject: seatToolSubject(s, verb, node)})
 		}
 	}
+	m.State = stateIssuedFor(d)
 	if len(d.Invokes) > 0 {
 		m.Reaches = map[string][]string{}
 		for _, t := range d.Invokes {

internal/broker/nats.go

@@ -103,6 +103,12 @@ type Principal struct {
 	// permission and nothing beside it.
 	Invokes []string
 
+	// State is the local names of the state this principal's module keeps, and Reads the state of
+	// others it reads as `<module>.<name>` (novox/hq ADR 0201): a bucket each, kept by the owner's
+	// instances and read by whoever declares it.
+	State []string
+	Reads []string
+
 	// PasswordHash is the bcrypt hash the mesh minted. The plaintext is sealed to the principal
 	// and never appears here: this file is written to a node's disk and read by a server, and a
 	// secret that can be read from a configuration file is a secret with a wider blast radius
@@ -421,6 +427,10 @@ func PermissionsFor(p Principal) (Permissions, error) {
 			}
 		}
 
+		// 5. Its state, and the state of others it reads (novox/hq ADR 0201): every one read and
+		//    watched, its own written too.
+		pub = append(pub, stateGrants(p.Module, p.State, p.Reads)...)
+
 	case KindNodeTools:
 		// **One process serves what every module on the machine would have served for itself**
 		// (novox/hq ADR 0175). Each carried module's whole tool namespace — the same grant that
@@ -487,6 +497,13 @@ func PermissionsFor(p Principal) (Permissions, error) {
 				"$JS.API.CONSUMER.MSG.NEXT."+stream+"."+durable,
 				"$JS.ACK."+stream+"."+durable+".>")
 		}
+		// **And it keeps and reads state for the modules it carries** (novox/hq ADR 0201): the union
+		// of what each may do with a bucket — an owner's write, a reader's read. That one module's code
+		// does not write another's bucket through it is the runtime's to keep, from the membership
+		// each assignment is issued, as it keeps each module's events under that module's own name.
+		for _, d := range p.Carries {
+			pub = append(pub, stateGrants(d.Module, stateNames(d.State), d.Reads)...)
+		}
 		sub = unique(sub)
 		pub = unique(pub)
 	}

internal/broker/state.go

@@ -0,0 +1,169 @@
+package broker
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// A module's state on the bus (novox/hq ADR 0201, design 32 §4, design 25 §3).
+//
+// A module names the state it keeps (`state`) and the state of others it reads (`reads`), and each
+// is a key-value bucket: the server's own last-per-subject stream with direct reads, delete markers
+// and watches, which is the state relationship the mesh already uses for declarations, opened to
+// modules. The controller creates every bucket from the catalogue — from registration, like a
+// seat's stream, so a reader may watch before the owner runs anywhere — and no module can.
+//
+// Pure, like everything else in this package that decides what the bus holds; jetstream.go is the
+// part that asks a server.
+
+// The mesh's caps on a bucket, the same for every module: a value is a piece of state, not a file,
+// and a bucket that grew without bound would be one module filling the bus's disk for everyone.
+const (
+	StateMaxValueBytes = 256 * 1024
+	StateMaxBytes      = 64 * 1024 * 1024
+)
+
+// A Bucket is one module's declared state as the bus holds it.
+type Bucket struct {
+	Module string
+	Name   string
+	// History is how many values a key keeps; zero is one.
+	History int
+	// TTLSeconds is how long a value lives; zero is until replaced or deleted.
+	TTLSeconds int
+}
+
+// BucketName is the bucket a module's state lives in: the module and the local name joined by an
+// underscore, which neither may contain, so two modules can never derive one bucket.
+func BucketName(module, name string) string { return module + "_" + name }
+
+// Bucket is this bucket's name on the bus.
+func (b Bucket) Bucket() string { return BucketName(b.Module, b.Name) }
+
+// Why is carried into the server's description of the bucket, so somebody reading the server's
+// own state finds whose it is and why it is kept.
+func (b Bucket) Why() string {
+	return fmt.Sprintf("%s's state %q (novox/hq ADR 0201): its current value per key, written by %s, "+
+		"read by whatever declares it reads it; kept when %s is unassigned, because it is data",
+		b.Module, b.Name, b.Module, b.Module)
+}
+
+// bucketOfRead is the bucket a read names, `<module>.<name>`, or false when it names none.
+func bucketOfRead(read string) (string, bool) {
+	at := strings.LastIndex(read, ".")
+	if at <= 0 || at == len(read)-1 {
+		return "", false
+	}
+	module, name := read[:at], read[at+1:]
+	if !safeSubject.MatchString(module) || !safeSubject.MatchString(name) {
+		return "", false
+	}
+	return BucketName(module, name), true
+}
+
+// stateGrants is what a principal publishes to reach the state its modules keep and read: for every
+// bucket, binding to it, reading a key directly, and an ordered consumer for listing and watching,
+// created and deleted on the bucket's own stream, with its flow control answered; for a bucket an
+// owner keeps, writing under the bucket's own subjects too.
+//
+// **Measured against a running server, 2026-10-04** (novox/hq research 024), and each one is there
+// because leaving it out failed: without STREAM.INFO nothing binds; without DIRECT.GET nothing is
+// read; without CONSUMER.CREATE no key is listed and nothing is watched; without CONSUMER.DELETE a
+// watch cannot be stopped and lingers on the server. A write outside these is refused by the server
+// — and reaches the writer as a timeout, not a refusal, which is why the runtime refuses first.
+func stateGrants(module string, keeps []string, reads []string) []string {
+	var out []string
+	read := func(bucket string) {
+		stream := "KV_" + bucket
+		out = append(out,
+			"$JS.API.STREAM.INFO."+stream,
+			"$JS.API.DIRECT.GET."+stream+".>",
+			"$JS.API.CONSUMER.CREATE."+stream+".>",
+			"$JS.API.CONSUMER.DELETE."+stream+".>",
+			"$JS.FC."+stream+".>")
+	}
+	for _, name := range keeps {
+		if !safeSubject.MatchString(name) {
+			continue
+		}
+		bucket := BucketName(module, name)
+		read(bucket)
+		out = append(out, "$KV."+bucket+".>")
+	}
+	for _, r := range reads {
+		if bucket, ok := bucketOfRead(r); ok {
+			read(bucket)
+		}
+	}
+	return out
+}
+
+// StateIssued is one bucket an assignment may reach, by the name its module uses for it: its own
+// state by the local name, another's as `<module>.<name>` (novox/hq ADR 0201).
+type StateIssued struct {
+	Name   string `json:"name"`
+	Bucket string `json:"bucket"`
+	Writes bool   `json:"writes,omitempty"`
+}
+
+// stateIssuedFor is every bucket a module's code may reach, as its membership lists them.
+func stateIssuedFor(d Declared) []StateIssued {
+	var out []StateIssued
+	for _, b := range d.State {
+		out = append(out, StateIssued{Name: b.Name, Bucket: BucketName(d.Module, b.Name), Writes: true})
+	}
+	for _, r := range d.Reads {
+		if bucket, ok := bucketOfRead(r); ok {
+			out = append(out, StateIssued{Name: r, Bucket: bucket})
+		}
+	}
+	return out
+}
+
+// stateNames is the local names of a module's own buckets.
+func stateNames(buckets []Bucket) []string {
+	out := make([]string, 0, len(buckets))
+	for _, b := range buckets {
+		out = append(out, b.Name)
+	}
+	return out
+}
+
+// A BucketAsserter is the part of a JetStream connection bucket assertion needs.
+type BucketAsserter interface {
+	// EnsureBucket creates the bucket if absent and brings its options to match if present, never
+	// discarding what it holds.
+	EnsureBucket(b Bucket) error
+	// BucketNames is every key-value bucket on the server.
+	BucketNames() ([]string, error)
+}
+
+// RaiseBuckets asserts every declared bucket and answers the buckets on the server that nothing
+// declares any more.
+//
+// **Those are reported, never removed** (novox/hq ADR 0201, ADR 0030): what a module stored is
+// data, and a manifest edited, a module renamed or a catalogue entry dropped is an ordinary day's
+// work that must not take data with it. Removing one is a person's act.
+func RaiseBuckets(a BucketAsserter, buckets []Bucket) (undeclared []string, err error) {
+	sorted := append([]Bucket(nil), buckets...)
+	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Bucket() < sorted[j].Bucket() })
+	declared := map[string]bool{}
+	for _, b := range sorted {
+		if err := a.EnsureBucket(b); err != nil {
+			return nil, fmt.Errorf("asserting %s's state %q: %w", b.Module, b.Name, err)
+		}
+		declared[b.Bucket()] = true
+	}
+	names, err := a.BucketNames()
+	if err != nil {
+		return nil, fmt.Errorf("listing the bus's state: %w", err)
+	}
+	for _, n := range names {
+		if !declared[n] {
+			undeclared = append(undeclared, n)
+		}
+	}
+	sort.Strings(undeclared)
+	return undeclared, nil
+}

internal/broker/state_test.go

@@ -0,0 +1,180 @@
+package broker
+
+import (
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/nats-io/nats.go"
+)
+
+// The grants measured against a running server (novox/hq research 024): an owner reads and writes
+// its bucket, a reader only reads, and neither reaches any other bucket.
+func TestAnOwnerWritesItsStateAndAReaderOnlyReads(t *testing.T) {
+	owner, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "claude-code",
+		State: []string{"servers"}, PasswordHash: "x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, s := range []string{
+		"$KV.claude-code_servers.>",
+		"$JS.API.STREAM.INFO.KV_claude-code_servers",
+		"$JS.API.DIRECT.GET.KV_claude-code_servers.>",
+		"$JS.API.CONSUMER.CREATE.KV_claude-code_servers.>",
+		"$JS.API.CONSUMER.DELETE.KV_claude-code_servers.>",
+		"$JS.FC.KV_claude-code_servers.>",
+	} {
+		has(t, owner.Publish, s)
+	}
+	hasNot(t, owner.Publish, "$KV.>")
+	hasNot(t, owner.Publish, "$JS.API.>")
+
+	reader, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "console",
+		Reads: []string{"claude-code.servers"}, PasswordHash: "x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	has(t, reader.Publish, "$JS.API.DIRECT.GET.KV_claude-code_servers.>")
+	has(t, reader.Publish, "$JS.API.CONSUMER.CREATE.KV_claude-code_servers.>")
+	hasNot(t, reader.Publish, "$KV.claude-code_servers.>")
+	for _, s := range reader.Subscribe {
+		if s == "$KV.claude-code_servers.>" {
+			t.Fatalf("a reader subscribes the bucket's subjects directly: %v", reader.Subscribe)
+		}
+	}
+}
+
+// One runtime carries every module on its machine, so its grant is the union: the owner's write
+// where an owner is carried, a read where only a reader is.
+func TestTheRuntimeKeepsAndReadsStateForItsModules(t *testing.T) {
+	perms, err := PermissionsFor(Principal{Kind: KindNodeTools, Node: "one", Module: RuntimeModule,
+		Carries: []Declared{
+			{Module: "claude-code", State: []Bucket{{Module: "claude-code", Name: "servers"}},
+				Reads: []string{"licence-manager.bindings"}},
+			{Module: "audit"},
+		}, PasswordHash: "x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	has(t, perms.Publish, "$KV.claude-code_servers.>")
+	has(t, perms.Publish, "$JS.API.DIRECT.GET.KV_licence-manager_bindings.>")
+	hasNot(t, perms.Publish, "$KV.licence-manager_bindings.>")
+}
+
+// A module with no state is granted nothing of any bucket — the composition of every module that
+// existed before this is unchanged.
+func TestAModuleWithNoStateReachesNoBucket(t *testing.T) {
+	perms, err := PermissionsFor(Principal{Kind: KindModule, Node: "one", Module: "billing",
+		Emits: []string{"order.placed"}, PasswordHash: "x"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, s := range perms.Publish {
+		if strings.HasPrefix(s, "$KV.") || strings.HasPrefix(s, "$JS.FC.") || strings.Contains(s, ".KV_") {
+			t.Fatalf("granted %q without declaring state", s)
+		}
+	}
+}
+
+// A read that names no bucket grants nothing rather than something that happens to parse.
+func TestAReadThatNamesNoBucketGrantsNothing(t *testing.T) {
+	if got := stateGrants("a", nil, []string{"nodot", "x.", ".y", "a.b>"}); len(got) != 0 {
+		t.Fatalf("granted %v for reads that name no bucket", got)
+	}
+}
+
+// The membership lists every bucket the module's code may reach, by the name the module uses for
+// it, and whether it may write it — the list the runtime refuses from.
+func TestAMembershipListsTheStateItsModuleMayReach(t *testing.T) {
+	m := MembershipFor("one", Declared{Module: "claude-code",
+		State: []Bucket{{Module: "claude-code", Name: "servers"}},
+		Reads: []string{"licence-manager.bindings"}}, Placements{})
+	want := []StateIssued{
+		{Name: "servers", Bucket: "claude-code_servers", Writes: true},
+		{Name: "licence-manager.bindings", Bucket: "licence-manager_bindings"},
+	}
+	if !slices.Equal(m.State, want) {
+		t.Fatalf("issued %+v, want %+v", m.State, want)
+	}
+	if none := MembershipFor("one", Declared{Module: "audit"}, Placements{}); none.State != nil {
+		t.Fatalf("a module with no state was issued %+v", none.State)
+	}
+}
+
+type buckets struct {
+	ensured []string
+	on      []string
+}
+
+func (b *buckets) EnsureBucket(x Bucket) error {
+	b.ensured = append(b.ensured, x.Bucket())
+	return nil
+}
+func (b *buckets) BucketNames() ([]string, error) { return b.on, nil }
+
+// Every declared bucket is asserted; one on the server that nothing declares is said, not removed.
+func TestRaisingStateReportsWhatNothingDeclares(t *testing.T) {
+	b := &buckets{on: []string{"claude-code_servers", "gone_old", "ours_by_hand"}}
+	undeclared, err := RaiseBuckets(b, []Bucket{{Module: "claude-code", Name: "servers"}, {Module: "a", Name: "b"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !slices.Equal(b.ensured, []string{"a_b", "claude-code_servers"}) {
+		t.Fatalf("asserted %v", b.ensured)
+	}
+	if !slices.Equal(undeclared, []string{"gone_old", "ours_by_hand"}) {
+		t.Fatalf("reported %v", undeclared)
+	}
+}
+
+// Against a real server: a bucket is created with the owner's options and the mesh's caps,
+// asserting it again changes nothing and keeps what it holds, and a changed option is brought to
+// match in place.
+func TestABucketIsAssertedInPlace(t *testing.T) {
+	js := aLiveBus(t)
+	b := Bucket{Module: "statetest", Name: "servers"}
+	if _, err := RaiseBuckets(js, []Bucket{b}); err != nil {
+		t.Fatalf("a real server refused a module's bucket: %v", err)
+	}
+	kv, err := js.Context().KeyValue(b.Bucket())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := kv.Put("all.one", []byte(`{"kept":true}`)); err != nil {
+		t.Fatal(err)
+	}
+	b.History = 3
+	if _, err := RaiseBuckets(js, []Bucket{b}); err != nil {
+		t.Fatalf("asserting the bucket again failed, so a restart would: %v", err)
+	}
+	got, err := kv.Get("all.one")
+	if err != nil || string(got.Value()) != `{"kept":true}` {
+		t.Fatalf("asserting again lost what the bucket held: %v %v", got, err)
+	}
+	status, err := kv.Status()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if status.History() != 3 {
+		t.Fatalf("history is %d, the owner declared 3", status.History())
+	}
+	if s, ok := status.(*nats.KeyValueBucketStatus); ok {
+		if c := s.StreamInfo().Config; c.MaxMsgSize != StateMaxValueBytes || c.MaxBytes != StateMaxBytes {
+			t.Fatalf("the mesh's caps are not on the bucket: value %d, bucket %d", c.MaxMsgSize, c.MaxBytes)
+		}
+	}
+}
+
+// Against a real server: the handle over a connection the control plane already holds asserts a
+// bucket as Dial's does — what a push uses, so a module registered since the last start has its
+// bucket before its membership names it.
+func TestABucketIsAssertedOverAHeldConnection(t *testing.T) {
+	js := aLiveBus(t)
+	held := OnConn(js.Conn())
+	if _, err := RaiseBuckets(held, []Bucket{{Module: "statetest", Name: "held"}}); err != nil {
+		t.Fatalf("asserting over a held connection failed: %v", err)
+	}
+	if _, err := js.Context().KeyValue("statetest_held"); err != nil {
+		t.Fatalf("the bucket is not there: %v", err)
+	}
+}

internal/broker/users.go

@@ -33,6 +33,10 @@ type Declared struct {
 	Watches []Seat
 	// Invokes are the tools it calls, `<module>.<tool>` or `*` (novox/hq ADR 0152).
 	Invokes []string
+	// State is the state it keeps, each a bucket its instances write (novox/hq ADR 0201).
+	State []Bucket
+	// Reads are other modules' state it reads, each `<module>.<name>` (novox/hq ADR 0201).
+	Reads []string
 }
 
 // Records is what composing a user list needs to know about the mesh, and nothing more.
@@ -81,6 +85,7 @@ func Users(r Records) ([]Principal, error) {
 				Kind: KindModule, Node: node, Module: d.Module,
 				Emits: d.Emits, Consumes: d.Consumes, Serves: d.Serves,
 				Holds: d.Holds, Uses: d.Uses, Watches: d.Watches, Invokes: d.Invokes,
+				State: stateNames(d.State), Reads: d.Reads,
 			})
 		}
 		if runtimeHere {

internal/builder/builder.go

@@ -215,7 +215,7 @@ func Build(ctx context.Context, run Runner, publish Publisher,
 		sort.Slice(artifacts, func(i, j int) bool { return artifacts[i].Name < artifacts[j].Name })
 		for _, a := range artifacts {
 			say("artifact", "%s (%s%s) — starting", a.Name, a.Kind, langSuffix(a))
-			made, err := one(ctx, run, publish, manifest.Module, within, workspace, commit, credentials, a, args, held, npmrcPath, seatBases, say)
+			made, err := one(ctx, run, publish, manifest.Module, within, workspace, commit, credentials, a, args, held, npmrcPath, npmrc, seatBases, say)
 			if err != nil {
 				say("artifact", "%s FAILED: %v", a.Name, err)
 				return Result{}, err
@@ -443,7 +443,7 @@ func wantsPackages(manifest catalogue.Manifest, within string) bool {
 
 func one(ctx context.Context, run Runner, publish Publisher,
 	module, tree, workspace, commit, credentials string, a catalogue.Artifact, args []string,
-	held map[string]string, npmrc string, seats map[string]string,
+	held map[string]string, npmrc string, registry Npmrc, seats map[string]string,
 	say func(step, format string, args ...any)) (catalogue.Built, error) {
 
 	switch a.Kind {
@@ -582,6 +582,11 @@ func one(ctx context.Context, run Runner, publish Publisher,
 					"holds no copy of it. Build %s first",
 				module, a.Name, chain.Language, chain.Base, chain.Artifact, chain.Base)
 		}
+		// The module's own packages first, where the compiler and the bundler resolve them from
+		// (dependencies.go); nothing at all for a module whose package.json names only the SDK.
+		if err := installOwn(ctx, run, tree, chain, base, registry, say); err != nil {
+			return catalogue.Built{}, fmt.Errorf("%s: %s: %w", module, a.Name, err)
+		}
 		say("bundle", "compiling %s in %s's toolchain", a.Language, chain.Base)
 		compiled, err := compile(ctx, run, tree, chain, base, a)
 		if err != nil {

internal/builder/dependencies.go

@@ -0,0 +1,147 @@
+package builder
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// A module's own packages, installed before its bundle is compiled, so the bundler inlines them.
+//
+// **A bundle could only import what the toolchain happened to carry.** The compiler and the bundler
+// resolve an import by walking up from the module's source: the module's own directory first, then
+// the toolchain image's node_modules. Nothing ever put anything in the first, so a module needing a
+// database driver (`pg`, `mongodb`, `mssql`) could not be a bundle at all, and kept a container whose
+// recipe installed it by hand (novox/hq ADR 0198 §4: "the backend's own driver inside the bundle").
+// Now the module's `package.json` says what it depends on, as any Node package does, and the build
+// installs exactly that into the module's own directory before compiling.
+//
+// **The SDK the toolchain carries is the one a bundle is built with, whatever the module says**
+// (novox/hq issue 212: the toolchain is rebuilt on every SDK release and every bundle after it). A
+// module's `package.json` names `@novox/mesh-sdk` with a range — it has to, to type-check on a
+// workstation — and installing that range would shadow the toolchain's copy for this module alone:
+// one module compiled against an older SDK than its neighbours, chosen by a caret nobody re-reads.
+// So the SDK is taken out of what is installed (and never fetched), and any copy something else
+// pulls in is removed afterwards; every import of it resolves past the module's node_modules to the
+// toolchain's. A module therefore cannot pin a different SDK, by design: the toolchain is the pin.
+//
+// **Correctness before speed.** Every build installs afresh into a fresh clone, from the lockfile
+// when the module has one (`npm ci`, exact) and from its ranges otherwise; nothing installed is kept
+// between builds. What is shared is npm's own download cache, a named volume, which is
+// content-addressed and verified by integrity on every read — it saves the network, never the
+// install. Install scripts do not run: the build node runs nobody's postinstall, and what a script
+// would build natively could not be inlined into one file anyway.
+
+// sdkPackage is the package a TypeScript bundle's launcher serves through, and the one package a
+// module's own dependencies never supply (above).
+const sdkPackage = "@novox/mesh-sdk"
+
+// npmCache is the named volume npm's download cache lives in across builds on one build node.
+const npmCache = "mesh-builder-npm-cache"
+
+// ownDependencies is what a module's package.json depends on beyond the SDK, sorted; nothing when
+// the module has no package.json or depends on nothing else — which builds exactly as before.
+func ownDependencies(tree string) ([]string, error) {
+	raw, err := os.ReadFile(filepath.Join(tree, "package.json"))
+	if errors.Is(err, os.ErrNotExist) {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var p struct {
+		Dependencies map[string]string `json:"dependencies"`
+	}
+	if err := json.Unmarshal(raw, &p); err != nil {
+		return nil, fmt.Errorf("the module's package.json is not JSON: %w", err)
+	}
+	var names []string
+	for name := range p.Dependencies {
+		if name != sdkPackage {
+			names = append(names, name)
+		}
+	}
+	sort.Strings(names)
+	return names, nil
+}
+
+// installSteps is the script run inside the toolchain image, from the module's own directory ($0).
+// It works in a scratch copy so the module's package.json and lockfile are never rewritten, takes
+// the SDK out of what is installed, installs production dependencies only, removes any copy of the
+// SDK something pulled in, and puts the result at the module's node_modules.
+const installSteps = `set -e
+work="$(mktemp -d)"
+cp "$0/package.json" "$work/"
+if [ -f "$0/package-lock.json" ]; then cp "$0/package-lock.json" "$work/"; fi
+cd "$work"
+node -e '
+const fs = require("fs"), sdk = process.argv[1];
+const p = JSON.parse(fs.readFileSync("package.json", "utf8"));
+for (const k of ["dependencies", "peerDependencies", "optionalDependencies"]) if (p[k]) delete p[k][sdk];
+delete p.devDependencies; delete p.scripts;
+fs.writeFileSync("package.json", JSON.stringify(p));
+' "$1"
+shift
+if [ -f package-lock.json ]; then
+  npm ci --omit=dev --omit=peer --ignore-scripts --no-audit --no-fund "$@"
+else
+  npm install --omit=dev --omit=peer --ignore-scripts --no-audit --no-fund --no-package-lock "$@"
+fi
+find node_modules -depth -type d -path "*/node_modules/@novox/mesh-sdk" -exec rm -rf {} +
+rm -rf "$0/node_modules"
+cp -a node_modules "$0/node_modules"
+`
+
+// installOwn installs a TypeScript module's own production dependencies into its directory, in the
+// toolchain image, before the compile — or does nothing at all for a module that has none.
+func installOwn(ctx context.Context, run Runner, tree string, chain Toolchain, base string,
+	registry Npmrc, say func(step, format string, args ...any)) error {
+	if chain.Language != "typescript" {
+		return nil
+	}
+	deps, err := ownDependencies(tree)
+	if err != nil || len(deps) == 0 {
+		return err
+	}
+	scoped := strings.TrimSpace(registry.Scope)
+	if !registry.Enabled() {
+		// **No registry, no scoped package.** Without the mesh's registry a scoped name resolves on
+		// the public one, where anybody may have published it: a dependency that installs is not
+		// the dependency the module meant.
+		for _, d := range deps {
+			if strings.HasPrefix(d, "@novox/") {
+				return fmt.Errorf("the module depends on %s, and this build knows no package registry "+
+					"for its scope; it would resolve from the public registry, which is not where the "+
+					"mesh publishes it", d)
+			}
+		}
+	}
+	const within = "/app/modules/module"
+	invocation := []string{"run", "--rm",
+		"--volume", tree + ":" + within,
+		"--volume", npmCache + ":/root/.npm",
+		"--workdir", within}
+	var flags []string
+	if registry.Enabled() {
+		// The registry is reached where the binding says it is, which may be this machine's own
+		// loopback — the reason an image build that resolves packages runs on the host network too.
+		invocation = append(invocation, "--network", "host")
+		reg := strings.TrimSpace(registry.Registry)
+		if !strings.HasSuffix(reg, "/") {
+			reg += "/"
+		}
+		flags = append(flags, "--"+scoped+":registry="+reg)
+	}
+	invocation = append(invocation, base, "sh", "-c", installSteps, within, sdkPackage)
+	invocation = append(invocation, flags...)
+	say("bundle", "installing the module's own packages: %s", strings.Join(deps, ", "))
+	if _, err := run(ctx, tree, "docker", invocation...); err != nil {
+		return fmt.Errorf("installing the module's own packages (%s): %w", strings.Join(deps, ", "), err)
+	}
+	return nil
+}

internal/builder/dependencies_test.go

@@ -0,0 +1,131 @@
+package builder
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+// A module's own packages (dependencies.go): installed into its own directory, in the toolchain,
+// before the compile, so the bundler inlines them — the SDK always the toolchain's.
+
+func buildWithPackageJSON(t *testing.T, pkg string, extra map[string]string, registry Npmrc) (*recorded, error) {
+	t.Helper()
+	files := map[string]string{"index.ts": "console.log(1)"}
+	if pkg != "" {
+		files["package.json"] = pkg
+	}
+	for k, v := range extra {
+		files[k] = v
+	}
+	r, workspace := aRepository(t, aBundle, files)
+	held := map[string]string{"mesh-tools/build": "registry.invalid/mesh-tools/build@sha256:" + strings.Repeat("b", 64)}
+	_, err := Build(context.Background(), compiling{r}.run, r,
+		"https://forge.invalid/greeter.git", "", "", workspace, held, registry, GitCredential{}, nil)
+	return r, err
+}
+
+func installs(r *recorded) []string {
+	var out []string
+	for _, line := range r.ran {
+		if strings.HasPrefix(line, "docker run") && strings.Contains(line, "npm ci") {
+			out = append(out, line)
+		}
+	}
+	return out
+}
+
+func compileIndex(r *recorded) int {
+	for i, line := range r.ran {
+		if strings.Contains(line, "--outDir") {
+			return i
+		}
+	}
+	return -1
+}
+
+func TestAModulesOwnPackagesAreInstalledInTheToolchainBeforeTheCompile(t *testing.T) {
+	r, err := buildWithPackageJSON(t, `{"type":"module","dependencies":{"@novox/mesh-sdk":"^0.1.0","pg":"^8"},"devDependencies":{"typescript":"^5"}}`,
+		nil, Npmrc{Scope: "@novox", Registry: "https://forge.invalid/api/packages/novox/npm"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := installs(r)
+	if len(got) != 1 {
+		t.Fatalf("want one install of the module's own packages:\n%s", strings.Join(r.ran, "\n"))
+	}
+	line := got[0]
+	for _, want := range []string{
+		"mesh-tools/build@sha256:",       // in the toolchain image
+		":/app/modules/module",           // into the module's own directory
+		"--workdir /app/modules/module",  //
+		npmCache + ":/root/.npm",         // npm's verified download cache, and only that
+		"--omit=dev", "--ignore-scripts", // production packages, no build-node scripts
+		"npm ci", "npm install", "--no-package-lock", // the lockfile when there is one, else the ranges
+		"--@novox:registry=https://forge.invalid/api/packages/novox/npm/", // the scope from the mesh's registry
+		"--network host",
+		"@novox/mesh-sdk", // named, to be taken out of what is installed
+	} {
+		if !strings.Contains(line, want) {
+			t.Errorf("the install lacks %q:\n%s", want, line)
+		}
+	}
+	// The SDK is the toolchain's: never installed from the module's range, and any copy removed.
+	if !strings.Contains(line, `delete p[k][sdk]`) || !strings.Contains(line, `-path "*/node_modules/@novox/mesh-sdk" -exec rm -rf`) {
+		t.Errorf("the module's own SDK range could shadow the toolchain's SDK:\n%s", line)
+	}
+	if i, c := strings.Index(strings.Join(r.ran, "\n"), "npm ci"), compileIndex(r); c < 0 ||
+		i > strings.Index(strings.Join(r.ran, "\n"), "--outDir") {
+		t.Fatalf("the install did not run before the compile:\n%s", strings.Join(r.ran, "\n"))
+	}
+}
+
+// **A module with nothing beyond the SDK builds exactly as before**: the same commands, no install.
+func TestAModuleDependingOnlyOnTheSDKBuildsExactlyAsBefore(t *testing.T) {
+	without, err := buildWithPackageJSON(t, "", nil, Npmrc{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, pkg := range []string{
+		`{"type":"module","dependencies":{"@novox/mesh-sdk":"^0.1.0"},"devDependencies":{"typescript":"^5"}}`,
+		`{"type":"module"}`,
+	} {
+		with, err := buildWithPackageJSON(t, pkg, map[string]string{"package-lock.json": "{}"}, Npmrc{Scope: "@novox", Registry: "https://forge.invalid/npm/"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if strings.Contains(strings.Join(with.ran, "\n"), "npm ") {
+			t.Fatalf("a module depending on nothing but the SDK ran npm:\n%s", strings.Join(with.ran, "\n"))
+		}
+		if len(with.ran) != len(without.ran) {
+			t.Fatalf("a module depending only on the SDK built differently from one with no package.json:\n%s\n---\n%s",
+				strings.Join(with.ran, "\n"), strings.Join(without.ran, "\n"))
+		}
+	}
+}
+
+// Without the mesh's registry a scoped package would resolve on the public one: refused by name.
+func TestAScopedPackageWithNoRegistryIsRefused(t *testing.T) {
+	r, err := buildWithPackageJSON(t, `{"dependencies":{"@novox/mesh-sdk":"^0.1.0","@novox/other":"^1"}}`, nil, Npmrc{})
+	if err == nil || !strings.Contains(err.Error(), "@novox/other") {
+		t.Fatalf("a scoped package was installed with no registry for its scope: %v", err)
+	}
+	if strings.Contains(strings.Join(r.ran, "\n"), "--outDir") {
+		t.Fatal("the compile ran after the refusal")
+	}
+	// A public package installs without one, from the public registry and nothing else.
+	r, err = buildWithPackageJSON(t, `{"dependencies":{"mssql":"^11"}}`, nil, Npmrc{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := installs(r); len(got) != 1 || strings.Contains(got[0], ":registry=") || strings.Contains(got[0], "--network host") {
+		t.Fatalf("a public package's install: %v", got)
+	}
+}
+
+func TestAnUnreadablePackageJSONIsRefusedByName(t *testing.T) {
+	_, err := buildWithPackageJSON(t, `{"dependencies":`, nil, Npmrc{})
+	if err == nil || !strings.Contains(err.Error(), "package.json") {
+		t.Fatalf("a broken package.json was not refused by name: %v", err)
+	}
+}

internal/builder/toolchain.go

@@ -67,8 +67,9 @@ type Toolchain struct {
 	// `package.json` saying `"type": "module"` — Node reads a bare `.js` as CommonJS otherwise, so a
 	// bundle with its dependencies and without that line still fails to start — and the pruned,
 	// production-only node_modules the runtime itself ships with: the SDK's and the runtime's
-	// dependencies, and nothing module-specific yet (novox/hq ADR 0188 §5: a skeleton; a module's
-	// own npm dependencies are a later step). Empty for a language whose bundle carries its own —
+	// dependencies, and nothing module-specific (a module's own npm dependencies are installed into
+	// its own directory before the compile and inlined by the bundler: dependencies.go). Empty for a
+	// language whose bundle carries its own —
 	// a Go binary is static, a Python bundle is installed with its dependencies.
 	//
 	// A toolchain image without the directory fails the build by name rather than packing a bundle

internal/catalogue/a_service_process_test.go

@@ -146,18 +146,6 @@ func TestWhatAProcessReplacesIsNamedAsTheHostRecordedIt(t *testing.T) {
 	}
 }
 
-// Where the machine put the store is told to a process as to a container.
-func TestAProcessIsToldWhereTheSeatsAre(t *testing.T) {
-	out := composeTheService(t, Rendering{Seats: map[string]map[int]int{"mesh-store": {5432: 6852}}})
-	env, _ := out[indexOf(out, "svc.service")]["env"].(map[string]any)
-	if env["SVC_STORE_PORT"] != "6852" {
-		t.Fatalf("the process is told the store is on %v; the node put it on 6852", env["SVC_STORE_PORT"])
-	}
-	if !strings.HasPrefix(env["SVC_STORE_FILE"].(string), "/") {
-		t.Errorf("the secret's path was not placed: %v", env["SVC_STORE_FILE"])
-	}
-}
-
 func TestWhatReplacesMayNameIsRefusedNearItsAuthor(t *testing.T) {
 	for what, resource := range map[string]string{
 		"a container":        `{"id":"c","type":"container","name":"c","image":"x@` + aServiceDigest + `","replaces":["old"]}`,

internal/catalogue/bound_into_files.go

@@ -46,7 +46,7 @@ func boundUsed(content string) [][2]string {
 // Three facts the mesh states about any provision, plus whatever the provider said it serves. A
 // module may not reach a binding it does not have — the same boundary as a secret, for the same
 // reason.
-func knownFor(m Manifest, needs []Needed, node string) map[string]map[string]string {
+func knownFor(m Manifest, needs []Needed, node string) (map[string]map[string]string, error) {
 	out := map[string]map[string]string{}
 	for _, want := range m.Wants() {
 		for i := range needs {
@@ -54,12 +54,20 @@ func knownFor(m Manifest, needs []Needed, node string) map[string]map[string]str
 			if n.Name != want || n.For != m.Module {
 				continue
 			}
+			as := ConsumerIdentity(node, IdentitySource(m.Slug, m.Module))
 			values := map[string]string{
 				"at":   n.At,
 				"from": n.From,
-				"as":   ConsumerIdentity(node, IdentitySource(m.Slug, m.Module)),
+				"as":   as,
 			}
-			for key, value := range n.Serves {
+			// What the provider derives for this consumer rather than for all of them
+			// (novox/hq ADR 0201). Filled here, the one place a provision and the module
+			// requiring it are both in hand.
+			served, err := ServedTo(n.Serves, as)
+			if err != nil {
+				return nil, fmt.Errorf("%s requires %s: %w", m.Module, want, err)
+			}
+			for key, value := range served {
 				// The provider's own vocabulary. Rendered plainly: a port is 5432, not 5432.000000,
 				// which is what a float would write and what a connection string would refuse.
 				values[key] = plainly(value)
@@ -67,7 +75,7 @@ func knownFor(m Manifest, needs []Needed, node string) map[string]map[string]str
 			out[want] = values
 		}
 	}
-	return out
+	return out, nil
 }
 
 // withOwnNames adds a module's own composed names to what it may name from one binding:

internal/catalogue/consumer_into_serves.go

@@ -0,0 +1,311 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// What a provider derives for one consumer, said once in the provider's definition and delivered
+// to both ends (novox/hq ADR 0201, issue 124).
+//
+// A `serves` block is otherwise literal: the same values for every consumer. Where the provider
+// *names the resource* — a bucket, a database, a vhost — the name is derived from who is asking,
+// and before this the mesh had no channel for it. The provider recomputed it in its own code and
+// every consumer transcribed it into its own definition by hand, which is a copy of somebody
+// else's rule kept in agreement by nobody. One of three transcriptions was wrong for months.
+//
+// **The mesh learns no protocol here; it spells its own name in an alphabet it already knows.**
+// The only fact a served value may name is the identity the mesh itself minted for the consumer,
+// in one of two alphabets: as it was minted, and as a DNS label. Everything a provider wants
+// around it — a prefix, a suffix, a separator — it writes around the placeholder, because a
+// served value is a string.
+
+// consumerFact is `${consumer:<fact>}` or `${consumer:<fact>:<alphabet>}`.
+var consumerFact = regexp.MustCompile(`\$\{consumer:([a-z][a-z0-9-]*)(?::([a-z][a-z0-9-]*))?\}`)
+
+// consumerFacts are what a served value may name about the consumer it is being derived for.
+// One entry, deliberately: the identity is the one thing about a consumer the mesh itself chose,
+// so it is the one thing the mesh can hand to a provider without either end guessing.
+var consumerFacts = []string{"as"}
+
+// consumerAlphabets are the ways the mesh will write that identity. `dns` is the mesh's own
+// identifier with its separator written `-` instead of `_` — the whole of the difference between
+// the alphabet the mesh mints in and the one buckets, vhosts and hostnames accept.
+var consumerAlphabets = []string{"dns"}
+
+// ServedTo fills a provider's served values for one consumer.
+//
+// `as` is the identity the mesh minted for that consumer — the same string it is told to present
+// as a login. Values with no placeholder are returned exactly as they were, and a block with no
+// placeholder at all is returned unchanged, so this costs nothing for the providers that derive
+// nothing.
+//
+// Only strings carry placeholders. A number, a boolean or a nested object is a value the provider
+// stated outright, and is left alone.
+func ServedTo(serves map[string]any, as string) (map[string]any, error) {
+	if len(serves) == 0 {
+		return serves, nil
+	}
+	var out map[string]any
+	for _, key := range sortedAnyKeys(serves) {
+		text, ok := serves[key].(string)
+		if !ok || !strings.Contains(text, "${consumer:") {
+			continue
+		}
+		filled, err := consumerInto(text, as)
+		if err != nil {
+			return nil, fmt.Errorf("the value served as %q: %w", key, err)
+		}
+		if out == nil {
+			// Copied only once something actually changes: the caller's map is the manifest's,
+			// and a provider that derives nothing must not have it rewritten underneath it.
+			out = make(map[string]any, len(serves))
+			for k, v := range serves {
+				out[k] = v
+			}
+		}
+		out[key] = filled
+	}
+	if out == nil {
+		return serves, nil
+	}
+	return out, nil
+}
+
+// consumerInto replaces every `${consumer:…}` in one value.
+//
+// **A fact or an alphabet the mesh does not have is refused, not left standing.** Written through,
+// the literal `${consumer:as}` would reach a configuration file and be read as a bucket name,
+// failing somewhere that names neither the module nor the mesh — the same reasoning `${bound:…}`
+// is refused by (boundInto).
+func consumerInto(value, as string) (string, error) {
+	var failed error
+	out := consumerFact.ReplaceAllStringFunc(value, func(match string) string {
+		parts := consumerFact.FindStringSubmatch(match)
+		fact, alphabet := parts[1], parts[2]
+		if fact != "as" {
+			if failed == nil {
+				failed = fmt.Errorf(
+					"says %s, and the mesh states %s about a consumer", match, orNothing(consumerFacts))
+			}
+			return match
+		}
+		switch alphabet {
+		case "":
+			return as
+		case "dns":
+			return asDNSLabel(as)
+		default:
+			if failed == nil {
+				failed = fmt.Errorf(
+					"says %s, and the mesh writes an identity as %s", match, orNothing(consumerAlphabets))
+			}
+			return match
+		}
+	})
+	if failed != nil {
+		return "", failed
+	}
+	return out, nil
+}
+
+// asDNSLabel writes a minted identity as a DNS label.
+//
+// The mesh's identities are already lower-case letters, digits and `_` (ConsumerIdentity), and
+// already short enough for the tightest backend they reach (CheckIdentity, twenty characters). So
+// this is the separator and nothing else — no lower-casing of what is already lower case, no
+// truncation to a limit the identity is already inside, no padding of a name that is already long
+// enough. Each of those would be the mesh guessing at a rule it has not been given.
+func asDNSLabel(as string) string {
+	return strings.ReplaceAll(as, "_", "-")
+}
+
+// CheckServes refuses a `serves` block that names a consumer fact or an alphabet the mesh does not
+// have, when the definition is parsed rather than when a consumer is resolved.
+//
+// A provision nobody consumes yet still has its rule read: a definition that would be refused the
+// first time somebody required it is a definition that is wrong now.
+func CheckServes(m Manifest) []string {
+	var problems []string
+	for _, provision := range sortedServes(m.Serves) {
+		for _, key := range sortedAnyKeys(m.Serves[provision]) {
+			text, ok := m.Serves[provision][key].(string)
+			if !ok {
+				continue
+			}
+			// A probe identity, because what is checked is the shape of the statement and not
+			// what any consumer is called.
+			if _, err := consumerInto(text, "mesh_node_module"); err != nil {
+				problems = append(problems, fmt.Sprintf(
+					"%s serves %s, and the value it serves as %q %s", m.Module, provision, key, err))
+			}
+		}
+	}
+	return problems
+}
+
+func sortedServes(serves map[string]map[string]any) []string {
+	out := make([]string, 0, len(serves))
+	for k := range serves {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func sortedAnyKeys(values map[string]any) []string {
+	out := make([]string, 0, len(values))
+	for k := range values {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// derivedFor is what the provider on this machine derives for one consumer of one provision
+// (novox/hq ADR 0201).
+//
+// Settled first, then derived: an operator may set a prefix on what the provider serves and the
+// mesh still fills the consumer's half of it ([ADR 0174]). Only the keys that actually name the
+// consumer are returned — the rest of a `serves` block is the same for every consumer and is
+// already in the provider's own definition, so repeating it here would be a second copy to go
+// stale.
+//
+// The first module in the resolved order that says it serves the provision answers, which is the
+// choice servedOnThisMachine makes for the consumer's half. Nothing serving it on this machine is
+// not an error: a contribution can reach a machine whose provider is a record or an adapter, and
+// then there is nothing derived to tell.
+func (r Resolution) derivedFor(provision, as, consumer, local string, settings SettingsBy) (map[string]any, error) {
+	for _, m := range r.Modules {
+		serves, said := m.Serves[provision]
+		if !said {
+			continue
+		}
+		var names map[string]any
+		for key, value := range serves {
+			if text, ok := value.(string); ok && strings.Contains(text, "${consumer:") {
+				if names == nil {
+					names = map[string]any{}
+				}
+				names[key] = value
+			}
+		}
+		if names == nil {
+			return nil, nil
+		}
+		// **A consumer that keeps several holders of this provision is refused** — this is issue
+		// 124's own failure one case to the side, and it would be just as quiet.
+		//
+		// Each holder gets its own login, `…_<local>` (ADR 0094), and a provider derives from the
+		// login, so it would make one resource per holder. The consumer's side has no such
+		// dimension: one binding file per provision, one `${bound:<provision>:<key>}`, both
+		// derived from the un-suffixed identity. So the provider would create the holder's
+		// resource and the consumer would be configured against a name nothing made — it would
+		// authenticate successfully and be refused on every object, which reads like a credential
+		// fault and is not one.
+		//
+		// Lifting this means giving the consumer's side a local dimension. That is a decision,
+		// not an omission, and until it is taken the mesh says so rather than guessing.
+		if local != "" {
+			return nil, fmt.Errorf(
+				"%s keeps several holders of %s (this one is %q), and %s derives %s for each "+
+					"consumer from the login the mesh minted. Each holder has its own login, and a "+
+					"consumer is told one value per requirement — so the two ends would name "+
+					"different things and nothing would compare them (novox/hq ADR 0201)",
+				consumer, local, provision, m.Module, orNothing(sortedAnyKeys(names)))
+		}
+		settled, err := Settle(names, settings[m.Module])
+		if err != nil {
+			return nil, fmt.Errorf("%s serving %s: %w", m.Module, provision, err)
+		}
+		derived, err := ServedTo(settled, as)
+		if err != nil {
+			return nil, fmt.Errorf("%s serving %s to %s: %w", m.Module, provision, as, err)
+		}
+		return derived, nil
+	}
+	return nil, nil
+}
+
+// notTranscribed refuses a consumer's file that writes out the value its provider derives for it,
+// instead of asking for it (novox/hq ADR 0201, issue 124).
+//
+// **What would have caught the one wrong instance.** The object store's three consumers each wrote
+// their bucket into their own configuration by hand. One of them named a predecessor's bucket, and
+// nothing compared it to what the provider would actually create: the module would have
+// authenticated successfully and been refused on every object, which reads like a credential fault
+// and is not one. It looked authoritative for months.
+//
+// The test is exact and costs one string search: a definition whose file already contains the
+// value the mesh is about to derive for it has written down somebody else's rule. It cannot be a
+// coincidence — a derived value carries the identity the mesh minted for this very consumer on
+// this very machine, which nothing else would spell out — and it cannot be checked afterwards,
+// because after substitution every consumer's file contains it legitimately.
+//
+// Only values that actually name the consumer are judged. A provider that serves a constant under
+// the same key serves the same constant to everyone, and a consumer repeating it is redundant
+// rather than wrong.
+func notTranscribed(resource map[string]any, known map[string]map[string]string, module string) error {
+	if fmt.Sprint(resource["type"]) != "file" {
+		return nil
+	}
+	content, ok := resource["content"].(string)
+	if !ok || content == "" {
+		return nil
+	}
+	for _, provision := range sortedKnown(known) {
+		values := known[provision]
+		identity := values["as"]
+		if identity == "" {
+			continue
+		}
+		for _, key := range sortedStringKeys(values) {
+			if key == "as" {
+				// The login is not derived from itself, and a consumer that must present it in a
+				// connection string legitimately has it from `${bound:…}` — which is what it will
+				// be after substitution, so this would judge the substitution, not the module.
+				continue
+			}
+			value := values[key]
+			if value == "" || !namesTheConsumer(value, identity) {
+				continue
+			}
+			if !strings.Contains(content, value) {
+				continue
+			}
+			return fmt.Errorf(
+				"%s writes %q into %v, and that is exactly what %s derives for it — a definition "+
+					"keeping its own copy of somebody else's naming rule is one that can disagree "+
+					"with it, silently. Say ${bound:%s:%s} and be told",
+				module, value, resource["id"], provision, provision, key)
+		}
+	}
+	return nil
+}
+
+// namesTheConsumer is whether a derived value was built from this consumer's identity — in the
+// alphabet it was minted in, or as a DNS label. A value that does not contain it was not derived
+// from it, whatever else it may be.
+func namesTheConsumer(value, identity string) bool {
+	return strings.Contains(value, identity) || strings.Contains(value, asDNSLabel(identity))
+}
+
+func sortedKnown(known map[string]map[string]string) []string {
+	out := make([]string, 0, len(known))
+	for k := range known {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}
+
+func sortedStringKeys(values map[string]string) []string {
+	out := make([]string, 0, len(values))
+	for k := range values {
+		out = append(out, k)
+	}
+	sort.Strings(out)
+	return out
+}

internal/catalogue/controller_is_a_process_test.go

@@ -0,0 +1,131 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+)
+
+// novox/hq issue 213: the controller is a Go program and was the one piece of the mesh's own Go
+// code still shipped as an image (ADR 0188 §1). Its own manifest, composed for the machine that runs
+// it, is a Go bundle run by the host as a process — and no container.
+func TestTheControllerIsAProcessAndNoContainer(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatalf("the controller's own manifest does not parse:\n%v", err)
+	}
+	if m.Build == nil || len(m.Build.Artifacts) != 1 {
+		t.Fatalf("the controller builds %+v; it is one bundle", m.Build)
+	}
+	a := m.Build.Artifacts[0]
+	if a.Kind != ArtifactBundle || a.Language != "go" || a.System == "" || BinaryOf(a) != "mesh-controller" {
+		t.Fatalf("the controller's artifact is %+v, not a Go bundle naming its system and binary", a)
+	}
+	for _, c := range m.Capabilities {
+		if c == "container-runtime" {
+			t.Error("the controller still requires a container runtime on its machine")
+		}
+	}
+
+	digest := "sha256:" + strings.Repeat("c", 64)
+	control, err := m.Resolve([]Built{{Name: a.Name, Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "mesh-controller/" + a.Name + "@" + digest, Digest: digest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The node's runtime does not launch it: it serves its seat's verbs itself.
+	if loads := control.Bundles[0].Loads; len(loads) != 0 {
+		t.Errorf("the node's runtime would launch the controller as a tools bundle: %v", loads)
+	}
+
+	needed := map[string]map[string]string{"mesh-controller": {}}
+	for name := range m.OwnSecrets {
+		needed["mesh-controller"][name] = "sealed-" + name
+	}
+	out, err := Resolution{Node: "anchor", Modules: []Manifest{control}}.Declaration(Rendering{
+		Needed: needed, ArtifactStore: "anchor.internal:5100",
+		Seats: map[string]map[int]int{"mesh-store": {5432: 6852}},
+	})
+	if err != nil {
+		t.Fatalf("the controller does not compose: %v", err)
+	}
+
+	var process, step map[string]any
+	account, firstSecret := -1, -1
+	for i, r := range out {
+		switch {
+		case r["type"] == "container":
+			t.Errorf("the controller's declaration still runs a container: %v", r)
+		case r["id"] == "mesh-controller.controller":
+			process = r
+		case r["id"] == "mesh-controller.controller-prepare":
+			step = r
+			if process != nil {
+				t.Error("the controller's preparation is placed after the process it prepares for")
+			}
+		case r["type"] == "user" && r["name"] == "mesh-controller":
+			account = i
+		case strings.HasPrefix(fmt.Sprint(r["id"]), "mesh-controller.needs-") && firstSecret < 0:
+			firstSecret = i
+		}
+	}
+	if process == nil {
+		t.Fatalf("the controller's process is not in its declaration: %v", out)
+	}
+	if run, _ := json.Marshal(process["run"]); string(run) != `["./mesh-controller","serve"]` {
+		t.Errorf("the controller is run as %s, not its own bundle's binary", run)
+	}
+	if process["source"] != "anchor.internal:5100/mesh-controller/"+a.Name+"@"+digest || process["digest"] != digest {
+		t.Errorf("the controller's bundle is fetched from %v (%v)", process["source"], process["digest"])
+	}
+	// The user: an account the host declares, which owns what the process reads.
+	if process["user"] != "mesh-controller" || account < 0 {
+		t.Errorf("the controller runs as %v, and the account declared is at %d", process["user"], account)
+	}
+	if firstSecret >= 0 && account > firstSecret {
+		t.Error("the controller's secrets are written before the account they belong to exists")
+	}
+	for _, r := range out {
+		if strings.HasPrefix(fmt.Sprint(r["id"]), "mesh-controller.needs-") && r["owner"] != "mesh-controller" {
+			t.Errorf("%v belongs to %v, which the controller's process cannot read", r["id"], r["owner"])
+		}
+	}
+	if dir := fileNamed(out, "mesh-controller.mesh-state"); dir == nil || dir["owner"] != "mesh-controller" {
+		t.Errorf("the controller's state directory is not its account's to enter: %v", dir)
+	}
+	// Each mount became a path the process reads: nothing it is told is a path inside a container.
+	state := fmt.Sprint(fileNamed(out, "mesh-controller.mesh-state")["path"])
+	env, _ := process["env"].(map[string]any)
+	for key, value := range env {
+		v := fmt.Sprint(value)
+		if strings.HasPrefix(v, "/run/secrets") || strings.HasPrefix(v, "/broker-tls") {
+			t.Errorf("%s=%s is a path inside the container the controller no longer runs in", key, v)
+		}
+		if strings.HasSuffix(key, "_FILE") && !strings.HasPrefix(v, state+"/") {
+			t.Errorf("%s=%s is not one of the files the mesh places for it", key, v)
+		}
+	}
+	if env["MESH_BROKER_CERTIFICATE"] != "/var/lib/mesh-broker-tls/tls.crt" {
+		t.Errorf("the controller reads the broker's certificate from %v", env["MESH_BROKER_CERTIFICATE"])
+	}
+	if env["MESH_STORE_INVENTORY_PORT"] != "6852" {
+		t.Errorf("the controller is told the store is on %v; the node put it on 6852", env["MESH_STORE_INVENTORY_PORT"])
+	}
+	// The handover: the container it ran as goes only once this is running.
+	if got, _ := json.Marshal(process["replaces"]); string(got) != `["mesh-controller.server"]` {
+		t.Errorf("the controller's process replaces %s, not the container it ran as", got)
+	}
+	// And its state is prepared first, by the same program as the same account.
+	if step == nil || step["run-once"] != true || step["user"] != "mesh-controller" {
+		t.Fatalf("the controller's preparation is %v", step)
+	}
+	if run, _ := json.Marshal(step["run"]); string(run) != `["./mesh-controller","prepare"]` {
+		t.Errorf("the controller's preparation runs %s", run)
+	}
+}

internal/catalogue/declaration.go

@@ -415,6 +415,13 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 	filtering := AsNftables(rules, with.Mesh, r.PublicDomain != "", with.Foundation,
 		with.OutwardLinks, with.TunnelInterface)
 
+	// **A variable two modules set is refused whether or not anything places it** (novox/hq ADR
+	// 0203 §5): the account has one environment, and a machine whose holder arrives later should not
+	// be the moment two modules are found to disagree about it.
+	if err := variablesSetOnce(r.Modules); err != nil {
+		return nil, err
+	}
+
 	var out []map[string]any
 	for _, m := range r.Modules {
 		if with.Adopted && m.Filtering != nil {
@@ -603,14 +610,14 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 					// and nothing would say so.
 					continue
 				}
-				first = append(first, map[string]any{
+				first = append(first, ownedBy(r.provisionsAs(m), map[string]any{
 					// One file per holder — the consumer's module with its local name after it
 					// where it keeps several (ADR 0094); the lab found two files with one id.
 					"id":     GrantID(to, g.Consumer+"."+holderAs(g.From, g.Local)),
 					"type":   "file",
 					"path":   grantPath(m.Grants[to], g.Consumer, holderAs(g.From, g.Local)),
 					"sealed": g.Sealed,
-				})
+				}))
 			}
 		}
 		for _, to := range sortedKeys(m.Binds) {
@@ -645,7 +652,16 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			if err != nil {
 				return nil, err
 			}
-			file, err := boundFile(*found, m.Binds[to], ConsumerIdentity(r.Node, IdentitySource(m.Slug, m.Module)), own)
+			as := ConsumerIdentity(r.Node, IdentitySource(m.Slug, m.Module))
+			// What the provider derives for THIS consumer, filled here where the consumer is
+			// known (novox/hq ADR 0201). The same fill knownFor does below, so the binding file
+			// and the module's `${bound:…}` substitutions cannot say different things.
+			told := *found
+			told.Serves, err = ServedTo(told.Serves, as)
+			if err != nil {
+				return nil, fmt.Errorf("%s is told about %s: %w", m.Module, to, err)
+			}
+			file, err := boundFile(told, m.Binds[to], as, own)
 			if err != nil {
 				return nil, err
 			}
@@ -719,7 +735,10 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			return nil, err
 		}
 		// And what its bindings say, for the half of a connection that is not secret.
-		known := knownFor(m, r.Needs, r.Node)
+		known, err := knownFor(m, r.Needs, r.Node)
+		if err != nil {
+			return nil, err
+		}
 		// A requirement answered on this same machine is not in r.Needs — its binding file is
 		// written from `here` (above) — and so `${bound:…}` could not name it, though the file
 		// beside it said the same facts. Filled from the same answer, so the two cannot disagree.
@@ -736,7 +755,11 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			}
 			local := *answered
 			local.For = m.Module
-			for provision, values := range knownFor(m, []Needed{local}, r.Node) {
+			here, err := knownFor(m, []Needed{local}, r.Node)
+			if err != nil {
+				return nil, err
+			}
+			for provision, values := range here {
 				known[provision] = values
 			}
 		}
@@ -761,6 +784,17 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 		// And the machine underneath, which no binding of its own can tell it.
 		thisMachine := machineFacts(r, with.Names, with.MeshRange)
 
+		// **A definition that already holds the answer transcribed it** (novox/hq ADR 0201).
+		// Judged over what the module itself declares, and before anything is substituted: the
+		// mesh's own generated files — the binding, the contributions — legitimately carry the
+		// derived value, and after substitution so does every consumer's file, so this is the one
+		// moment the two can be told apart.
+		for _, own := range m.Resources {
+			if err := notTranscribed(own, known, m.Module); err != nil {
+				return nil, err
+			}
+		}
+
 		// Which of this module's files carry a secret, for the rule that a container may not read
 		// one of them as its environment without saying so (ADR 0086, issue 041).
 		secretFiles := secretFilesOf(resources)
@@ -862,6 +896,13 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 				return nil, err
 			}
 			publishedOn(copied, m.Module, with)
+			// The account's environment and every module's shell code, where this module holds the
+			// seat that places them (novox/hq ADR 0203, ADR 0204). Gathered from every module on
+			// the node, as the jails are, and **last of every placeholder pass**: shell code is a
+			// shell's own syntax, full of `${…}` no pass above should ever be shown.
+			if err := contributionsInto(copied, m, r.Modules, thisMachine); err != nil {
+				return nil, err
+			}
 			copied["id"] = m.Module + "." + fmt.Sprint(resource["id"])
 			// A service saying what it reflects names resources within its own module, so those
 			// are prefixed too or they would point at nothing.
@@ -880,6 +921,15 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			if renamed := reflectsRenamed(m.Module, resource["reload-on"]); renamed != nil {
 				copied["reload-on"] = renamed
 			}
+			// And which of its module's containers a scheduled step holds still (novox/hq ADR 0189).
+			// **The loudest of the three when it is missed.** An unprefixed `restart-on` matches
+			// nothing and a service quietly never restarts; an unprefixed `while-stopped` names a
+			// container the declaration does not contain, and the host refuses the whole
+			// declaration — so the machine takes nothing at all, for every push, until this is
+			// right. That is what it did on the control node (2026-10-04).
+			if renamed := reflectsRenamed(m.Module, resource[WhileStopped]); renamed != nil {
+				copied[WhileStopped] = renamed
+			}
 			// And what a process replaces (novox/hq issue 213): a resource of this module's that it
 			// no longer declares, named as the host recorded it, or the host hands nothing over and
 			// removes it first.
@@ -1175,6 +1225,41 @@ type Contribution struct {
 	// requirement's name — everything providing `reverse-proxy` understands the same shape, which
 	// is what makes swapping one for another cost nothing.
 	Values map[string]any `json:"values"`
+	// Derived is what this provider's own definition said it derives for this consumer, already
+	// derived (novox/hq ADR 0201).
+	//
+	// **The provider is told, rather than recomputing it.** A served value may name the consumer's
+	// identity — a bucket named for who is asking, a database prefixed with it — and before this
+	// the rule lived twice: once in the provisioner's code, once transcribed into every consumer's
+	// definition. The mesh fills the provider's own statement here and delivers the same filled
+	// value to the consumer, so the two cannot disagree: there is no second computation to
+	// disagree with.
+	//
+	// Only the keys that are per-consumer. The rest of what the provider serves is the same for
+	// everyone and is in its own definition, where it already is.
+	Derived map[string]any `json:"derived,omitempty"`
+}
+
+// provisionsAs is the account that reads what the mesh writes for this provider: the one secret
+// per consumer it must open to set that consumer's password (novox/hq issue 225).
+//
+// **A root-owned 0600 file is one that process cannot read**, which is the same sentence already
+// written above for a module's own secrets — and the grant secret is the other kind of secret
+// the mesh writes for a module, so it is the same rule.
+//
+// Which account depends on where the module's code runs. A module whose code is a bundle is run
+// by the node's tool runtime, as the node's account ([ADR 0198](0198)); one still in a container
+// is whatever it declares as its secrets owner. Nothing names these paths, so the rule that
+// claims a bundle's other files by the words that name them (givenTo) cannot reach them: the
+// harness composes a grant secret's path from the contributions file, not from a word.
+//
+// Empty is root, which is what it was and what a module with no bundle and no declared owner
+// still wants.
+func (r Resolution) provisionsAs(m Manifest) string {
+	if len(m.Bundles) > 0 && r.Account != "" {
+		return r.Account
+	}
+	return m.SecretsOwner
 }
 
 // grantPath is where one consumer's sealed credential lands on the providing machine.
@@ -1266,12 +1351,17 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
 			// told about it and withdraws the login on its next pass.
 			continue
 		}
+		as := holderAs(ConsumerIdentity(g.Consumer, IdentitySource(g.Slug, g.From)), g.Local)
+		derived, err := r.derivedFor(g.Provision, as, g.From, g.Local, settings)
+		if err != nil {
+			return nil, err
+		}
 		out[g.Provision] = append(out[g.Provision], Contribution{
-			From: g.From, Node: g.Consumer, At: g.At, Values: g.Values,
+			From: g.From, Node: g.Consumer, At: g.At, Values: g.Values, Derived: derived,
 			// One holder per local name: the identity the consumer is known by, and the local name
 			// after it where the module keeps several (ADR 0094). Not a login any backend checks —
 			// a secret is not a login — so the identity limit does not apply to the suffix.
-			As:     holderAs(ConsumerIdentity(g.Consumer, IdentitySource(g.Slug, g.From)), g.Local),
+			As:     as,
 			Secret: grantPath(directories[g.Provision], g.Consumer, holderAs(g.From, g.Local)),
 		})
 		if granted[g.Provision] == nil {

internal/catalogue/derived_for_consumer_test.go

@@ -0,0 +1,343 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// What a provider derives for each consumer, said once and delivered to both ends
+// (novox/hq ADR 0201, issue 124).
+//
+// The failure these are written against: the object store's provisioner derived each consumer's
+// bucket from the login the mesh minted, in its own code, and the mesh had no channel to tell the
+// consumer which bucket that was — so all three consumers wrote the answer into their own
+// definitions by hand. Two were right. One named a predecessor's bucket and would have
+// authenticated successfully and been refused on every object. Each of them also named the
+// machine the module happens to run on, which a definition may not do.
+
+// store is an object store in the shape minio has: it serves a region and a port to everyone, and
+// a bucket named for whoever is asking.
+func store() Manifest {
+	return Manifest{
+		Module: "store", Version: "1",
+		Provides: FromAnywhere("s3-bucket"),
+		Listens:  []Listening{{Port: 9000, Protocol: "tcp", From: FromMesh}},
+		Serves: map[string]map[string]any{"s3-bucket": {
+			"region": "eu-west",
+			"bucket": "${consumer:as:dns}",
+		}},
+		Receives: map[string]string{"s3-bucket": "/var/lib/store/grants/mesh.json"},
+		Grants:   map[string]string{"s3-bucket": "/var/lib/store/grants"},
+		Resources: []map[string]any{{
+			"id": "server", "type": "container", "name": "store", "ports": []any{"9000"},
+		}},
+	}
+}
+
+// files is a consumer that writes the bucket into its own configuration — which is the thing it
+// could not do before, and had to transcribe.
+func files() Manifest {
+	return Manifest{
+		Module: "files", Version: "1", Slug: "files",
+		Requires: []string{"s3-bucket"},
+		Binds:    map[string]string{"s3-bucket": "/var/lib/files/store.json"},
+		Secrets:  map[string]string{"s3-bucket": "/var/lib/files/store.secret"},
+		Resources: []map[string]any{{
+			"id": "env", "type": "file", "path": "/var/lib/files/env", "mode": "0600",
+			"content": "BUCKET=${bound:s3-bucket:bucket}\nREGION=${bound:s3-bucket:region}\n",
+		}},
+	}
+}
+
+// pics is a second consumer of the same provider on the same machine: two derivations, neither
+// the other's.
+func pics() Manifest {
+	return Manifest{
+		Module: "pics", Version: "1", Slug: "pics",
+		Requires: []string{"s3-bucket"},
+		Binds:    map[string]string{"s3-bucket": "/var/lib/pics/store.json"},
+		Secrets:  map[string]string{"s3-bucket": "/var/lib/pics/store.secret"},
+		Resources: []map[string]any{{
+			"id": "env", "type": "file", "path": "/var/lib/pics/env", "mode": "0600",
+			"content": "BUCKET=${bound:s3-bucket:bucket}\n",
+		}},
+	}
+}
+
+// The three places the derived value lands must agree, because agreeing is the whole point: the
+// consumer's own file, the binding it reads as JSON, and the provider's contributions entry.
+func TestADerivedValueReachesBothEndsAndAgrees(t *testing.T) {
+	r, err := Resolve(shelf(store(), files()), []string{"store", "files"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{Grants: []Grant{{
+		Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+		Values: map[string]any{}, Sealed: "c2VhbGVk",
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// The mesh minted this identity for the consumer; the bucket is that identity as a DNS label.
+	// Derived here with the mesh's own function, so the test cannot agree with a wrong rule.
+	as := ConsumerIdentity("workstation", IdentitySource("files", "files"))
+	want := strings.ReplaceAll(as, "_", "-")
+	if want == as || !strings.Contains(as, "_") {
+		t.Fatalf("the mesh's identity %q has no separator to rewrite; this test proves nothing", as)
+	}
+
+	env := fileNamed(out, "files.env")
+	if env == nil {
+		t.Fatalf("the consumer was given no file: %v", out)
+	}
+	if got := env["content"].(string); !strings.Contains(got, "BUCKET="+want+"\n") {
+		t.Errorf("the consumer's own file was not told the bucket:\n%s\nwant BUCKET=%s", got, want)
+	}
+
+	binding := fileNamed(out, "files.bound-s3-bucket")
+	if binding == nil {
+		t.Fatalf("the consumer was given no binding: %v", out)
+	}
+	var said struct {
+		Serves map[string]any `json:"serves"`
+	}
+	if err := json.Unmarshal([]byte(binding["content"].(string)), &said); err != nil {
+		t.Fatal(err)
+	}
+	if said.Serves["bucket"] != want {
+		t.Errorf("the binding says the bucket is %q, want %q", said.Serves["bucket"], want)
+	}
+	// And what is the same for everybody is still the same for everybody.
+	if said.Serves["region"] != "eu-west" {
+		t.Errorf("the binding lost what the provider serves to all: %v", said.Serves)
+	}
+
+	given := storeGrants(t, out)
+	if len(given) != 1 {
+		t.Fatalf("the provider was told about %d consumer(s): %v", len(given), given)
+	}
+	if given[0].Derived["bucket"] != want {
+		t.Errorf("the provider was told the bucket is %v, and the consumer was told %q — "+
+			"the two ends disagree, which is the whole failure", given[0].Derived["bucket"], want)
+	}
+	// Only the per-consumer half. The region is the same for everyone and is already in the
+	// provider's own definition; repeating it here would be a copy to go stale.
+	if _, carried := given[0].Derived["region"]; carried {
+		t.Errorf("the provider was handed back what it already says for everyone: %v", given[0].Derived)
+	}
+}
+
+// Two consumers of one provider on one machine get two buckets, and neither gets the other's.
+func TestTwoConsumersOfOneProviderGetTheirOwnDerivation(t *testing.T) {
+	r, err := Resolve(shelf(store(), files(), pics()),
+		[]string{"store", "files", "pics"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{Grants: []Grant{
+		{Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+			Values: map[string]any{}, Sealed: "c2VhbGVk"},
+		{Provision: "s3-bucket", Consumer: "workstation", From: "pics", Slug: "pics",
+			Values: map[string]any{}, Sealed: "c2VhbGVk"},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	forFiles := strings.ReplaceAll(ConsumerIdentity("workstation", IdentitySource("files", "files")), "_", "-")
+	forPics := strings.ReplaceAll(ConsumerIdentity("workstation", IdentitySource("pics", "pics")), "_", "-")
+	if forFiles == forPics {
+		t.Fatal("the two consumers were given the same identity; this test proves nothing")
+	}
+	if got := fileNamed(out, "files.env")["content"].(string); !strings.Contains(got, "BUCKET="+forFiles+"\n") {
+		t.Errorf("files was not given its own bucket:\n%s", got)
+	}
+	if got := fileNamed(out, "pics.env")["content"].(string); !strings.Contains(got, "BUCKET="+forPics+"\n") {
+		t.Errorf("pics was not given its own bucket:\n%s", got)
+	}
+	var buckets []any
+	for _, g := range storeGrants(t, out) {
+		buckets = append(buckets, g.Derived["bucket"])
+	}
+	if len(buckets) != 2 || buckets[0] == buckets[1] {
+		t.Errorf("the provider was told %v; it must be told one bucket per consumer", buckets)
+	}
+}
+
+// An operator may still set what the provider serves, and the mesh still derives the rest: the
+// setting is laid on first, then the consumer's half is filled.
+func TestASettingComposesWithADerivedValue(t *testing.T) {
+	r, err := Resolve(shelf(store(), files()), []string{"store", "files"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{
+		Settings: SettingsBy{"store": {{From: "the operator",
+			Values: map[string]any{"bucket": "team-${consumer:as:dns}"}}}},
+		Grants: []Grant{{Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+			Values: map[string]any{}, Sealed: "c2VhbGVk"}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "team-" + strings.ReplaceAll(ConsumerIdentity("workstation", IdentitySource("files", "files")), "_", "-")
+	if got := fileNamed(out, "files.env")["content"].(string); !strings.Contains(got, "BUCKET="+want+"\n") {
+		t.Errorf("the operator's prefix did not survive the derivation:\n%s\nwant BUCKET=%s", got, want)
+	}
+	if given := storeGrants(t, out); given[0].Derived["bucket"] != want {
+		t.Errorf("the provider was told %v, the consumer %q", given[0].Derived["bucket"], want)
+	}
+}
+
+// A fact or an alphabet the mesh does not have is refused where the definition is, not where a
+// consumer happens to be resolved — and the refusal says what may be said instead.
+func TestAServedValueNamingSomethingTheMeshDoesNotHaveIsRefused(t *testing.T) {
+	for _, c := range []struct{ value, says string }{
+		{"${consumer:node}", "as"},
+		{"${consumer:as:punycode}", "dns"},
+	} {
+		m := store()
+		m.Serves["s3-bucket"]["bucket"] = c.value
+		raw, err := json.Marshal(m)
+		if err != nil {
+			t.Fatal(err)
+		}
+		_, err = ParseManifest(raw)
+		if err == nil {
+			t.Fatalf("%s was accepted", c.value)
+		}
+		if !strings.Contains(err.Error(), c.value) {
+			t.Errorf("the refusal of %s does not quote it: %v", c.value, err)
+		}
+		if !strings.Contains(err.Error(), c.says) {
+			t.Errorf("the refusal of %s does not say what may be said (%q): %v", c.value, c.says, err)
+		}
+	}
+}
+
+// `dns` is checked against an identity the mesh actually mints, not an invented string.
+func TestTheDNSAlphabetIsTheMintedIdentityWithItsSeparatorRewritten(t *testing.T) {
+	as := ConsumerIdentity("anchor", IdentitySource("ncloud", "nextcloud"))
+	if err := CheckIdentity("anchor", IdentitySource("ncloud", "nextcloud")); err != nil {
+		t.Fatalf("the mesh would not mint this identity at all: %v", err)
+	}
+	label := asDNSLabel(as)
+	if strings.Contains(label, "_") {
+		t.Errorf("%q is not a DNS label", label)
+	}
+	if strings.ReplaceAll(label, "-", "_") != as {
+		t.Errorf("%q is not %q with its separator rewritten", label, as)
+	}
+}
+
+// The check that would have caught the one wrong instance: a consumer that writes the derived
+// value into its own definition instead of asking for it is refused, whether it transcribed the
+// right answer or a predecessor's.
+func TestAConsumerThatTranscribesWhatItsProviderDerivesIsRefused(t *testing.T) {
+	as := ConsumerIdentity("workstation", IdentitySource("files", "files"))
+	transcribed := strings.ReplaceAll(as, "_", "-")
+
+	m := files()
+	m.Resources = []map[string]any{{
+		"id": "env", "type": "file", "path": "/var/lib/files/env", "mode": "0600",
+		// Exactly what the provider will create — correct today, and a copy of a rule that is
+		// not this module's.
+		"content": "BUCKET=" + transcribed + "\n",
+	}}
+	r, err := Resolve(shelf(store(), m), []string{"store", "files"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = r.Declaration(Rendering{Grants: []Grant{{
+		Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+		Values: map[string]any{}, Sealed: "c2VhbGVk",
+	}}})
+	if err == nil {
+		t.Fatal("a definition holding its own copy of the provider's naming rule was accepted")
+	}
+	if !strings.Contains(err.Error(), "${bound:s3-bucket:bucket}") {
+		t.Errorf("the refusal does not say what to write instead: %v", err)
+	}
+
+	// And a constant the provider serves to everyone is not a transcription: repeating it is
+	// redundant, not wrong, and refusing it would be the mesh policing style.
+	m.Resources = []map[string]any{{
+		"id": "env", "type": "file", "path": "/var/lib/files/env", "mode": "0600",
+		"content": "REGION=eu-west\n",
+	}}
+	r, err = Resolve(shelf(store(), m), []string{"store", "files"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := r.Declaration(Rendering{Grants: []Grant{{
+		Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+		Values: map[string]any{}, Sealed: "c2VhbGVk",
+	}}}); err != nil {
+		t.Errorf("a value the provider serves to everyone was judged a transcription: %v", err)
+	}
+}
+
+func storeGrants(t *testing.T, out []map[string]any) []Contribution {
+	t.Helper()
+	for _, r := range out {
+		if r["path"] != "/var/lib/store/grants/mesh.json" {
+			continue
+		}
+		var parsed struct {
+			Given []Contribution `json:"given"`
+		}
+		if err := json.Unmarshal([]byte(r["content"].(string)), &parsed); err != nil {
+			t.Fatal(err)
+		}
+		return parsed.Given
+	}
+	t.Fatalf("the provider was given no contributions file: %v", out)
+	return nil
+}
+
+// A consumer that keeps SEVERAL holders of one provision is refused, rather than told one thing
+// while its provider is told another.
+//
+// **This is issue 124's own failure, one case to the side.** The mesh gives each holder its own
+// login — `mesh_node_mod_<local>` (ADR 0094) — and the provider derives from the login, so it
+// would make one resource per holder. The consumer's side has no such dimension: there is one
+// binding file per provision and one `${bound:<provision>:<key>}`, both derived from the
+// un-suffixed identity. So the provider would create `…-mod-cold` and the consumer would be
+// configured against `…-mod`: it would authenticate successfully and be refused on every object,
+// which is exactly the fault this whole record exists to end.
+//
+// Refused, loudly, at the one place that can see both halves. Lifting it means giving the
+// consumer's side a local dimension, which is a decision and not an omission.
+func TestAConsumerWithSeveralHoldersOfADerivingProviderIsRefused(t *testing.T) {
+	m := files()
+	// Two holders of the one provision, the shape ADR 0094 gives a module that keeps several.
+	m.Secrets = nil
+	m.SecretsMany = map[string]map[string]string{"s3-bucket": {
+		"hot":  "/var/lib/files/hot.secret",
+		"cold": "/var/lib/files/cold.secret",
+	}}
+	m.Resources = []map[string]any{{
+		"id": "env", "type": "file", "path": "/var/lib/files/env", "mode": "0600",
+		"content": "BUCKET=${bound:s3-bucket:bucket}\n",
+	}}
+	r, err := Resolve(shelf(store(), m), []string{"store", "files"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	_, err = r.Declaration(Rendering{Grants: []Grant{
+		{Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+			Local: "hot", Values: map[string]any{}, Sealed: "c2VhbGVk"},
+		{Provision: "s3-bucket", Consumer: "workstation", From: "files", Slug: "files",
+			Local: "cold", Values: map[string]any{}, Sealed: "c2VhbGVk"},
+	}})
+	if err == nil {
+		t.Fatal("a consumer with several holders of a deriving provider was accepted; " +
+			"its two ends would have disagreed in silence")
+	}
+	for _, want := range []string{"files", "s3-bucket", "bucket"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal does not name %q: %v", want, err)
+		}
+	}
+}

internal/catalogue/environment_into.go

@@ -0,0 +1,523 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// The account's environment and the login shell's code, composed from the modules a node runs
+// (novox/hq ADR 0203, ADR 0204).
+//
+// **The same shape as the jails.** Every module may contribute — a toolchain its directory on PATH,
+// a version manager a variable naming its home, a prompt the code that loads it — naming no node, no
+// path and no file of the shell's (ADR 0112). The one module holding the matching seat places the
+// result with a placeholder in its own file, and the controller fills it from every module on the
+// node. A node not running a module has none of its contribution, and unassigning one takes its
+// lines away at the next composition.
+//
+// **Two kinds of contribution, kept apart on purpose.** The environment is facts, which the
+// controller writes in two standard formats — POSIX assignment and the service manager's
+// environment.d — so a terminal, a script, the login shell's `execute` and a graphical session all
+// read the same values (ADR 0203). Shell code is not a fact: it is text in one shell's syntax, which
+// the controller sorts into a slot and pastes without reading, as it pastes a jail's stanza (ADR
+// 0204).
+
+// EnvironmentSeat and LoginShellSeat are the seats whose holders may place what the modules
+// contributed: the account's environment, and the login shell's code.
+const (
+	EnvironmentSeat = "node-environment"
+	LoginShellSeat  = "node-login-shell"
+)
+
+// Where an environment entry on PATH goes: before the account's existing PATH, or after it.
+const (
+	PathAtStart = "start"
+	PathAtEnd   = "end"
+)
+
+// Environment is what one module adds to the account's environment (novox/hq ADR 0203).
+type Environment struct {
+	// Variables are names and literal values. A value may name the machine's own facts with
+	// ${machine:…}, resolved before anything is written, and nothing else that expands.
+	Variables map[string]string `json:"variables,omitempty"`
+	// Path is entries on the account's PATH, each at its start or its end, in the order declared.
+	Path []PathEntry `json:"path,omitempty"`
+}
+
+// PathEntry is one directory a module puts on the account's PATH.
+type PathEntry struct {
+	Entry string `json:"entry"`
+	At    string `json:"at"`
+}
+
+// ShellCode is one piece of code a module adds to a shell's startup (novox/hq ADR 0204).
+type ShellCode struct {
+	// For is the shell the code is written in.
+	For string `json:"for"`
+	// Slot is where it runs among the other modules' code: first, normal or last. Named rather
+	// than numbered, because every contributor would guess a number and a collision says nothing.
+	Slot string `json:"slot"`
+	// Code is never interpreted — it is the shell's syntax, and only the shell reads it.
+	Code string `json:"code"`
+}
+
+// The shells and slots a contribution may name (novox/hq ADR 0204). Closed, so a typo is a refusal
+// at the check rather than code that silently lands in no placeholder.
+var (
+	knownShells = []string{"zsh", "bash", "fish"}
+	knownSlots  = []string{"first", "normal", "last"}
+)
+
+// The two renderings of the environment a holder may place (novox/hq ADR 0203, decision 3).
+const (
+	EnvironmentPOSIX   = "posix"
+	EnvironmentSystemd = "systemd"
+)
+
+// ofEnvironment and ofShell are where a holder places what was contributed: ${environment:posix},
+// ${environment:systemd} and ${shell:<shell>:<slot>}. Loose inside the braces on purpose, so a
+// misspelt key is found and refused rather than left in a file as a literal nobody reads.
+var (
+	ofEnvironment = regexp.MustCompile(`\$\{environment:([^}]*)\}`)
+	ofShell       = regexp.MustCompile(`\$\{shell:([^}]*)\}`)
+)
+
+// variableName is a POSIX shell variable name, which is also what environment.d accepts.
+var variableName = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)
+
+// environmentProblems is what is wrong with this module's environment contribution, from the
+// manifest alone.
+func (m Manifest) environmentProblems() []string {
+	if m.Environment == nil {
+		return nil
+	}
+	var problems []string
+	for _, n := range sortedKeys(m.Environment.Variables) {
+		switch {
+		case !variableName.MatchString(n):
+			problems = append(problems, fmt.Sprintf(
+				"%s sets the variable %q, which is not a name a shell accepts: a letter or an "+
+					"underscore, then letters, digits and underscores", m.Module, n))
+			continue
+		case n == "PATH":
+			// PATH is the one variable every module shares, so no module may set it whole: a second
+			// setter would replace the first's entries, and the account's own PATH with them.
+			problems = append(problems, fmt.Sprintf(
+				"%s sets PATH as a variable; a module adds an entry under environment.path, at the "+
+					"start or the end, and PATH is composed from every module's (novox/hq ADR 0203)", m.Module))
+			continue
+		}
+		if why := literalProblem(m.Environment.Variables[n]); why != "" {
+			problems = append(problems, fmt.Sprintf(
+				"%s sets %s to %q, which %s — %s", m.Module, n, m.Environment.Variables[n], why, literalRule))
+		}
+	}
+	seen := map[string]bool{}
+	for i, p := range m.Environment.Path {
+		switch {
+		case p.Entry == "":
+			problems = append(problems, fmt.Sprintf("%s's PATH entry %d names no directory", m.Module, i+1))
+		case strings.Contains(ofMachine.ReplaceAllString(p.Entry, ""), ":"):
+			// A colon is PATH's own separator, so an entry holding one is two entries, and the
+			// check that it is already present would look for the wrong thing.
+			problems = append(problems, fmt.Sprintf(
+				"%s puts %q on PATH, which holds a colon, PATH's own separator", m.Module, p.Entry))
+		case seen[p.Entry]:
+			problems = append(problems, fmt.Sprintf("%s puts %q on PATH twice", m.Module, p.Entry))
+		default:
+			if why := literalProblem(p.Entry); why != "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s puts %q on PATH, which %s — %s", m.Module, p.Entry, why, literalRule))
+			}
+		}
+		seen[p.Entry] = true
+		if p.At != PathAtStart && p.At != PathAtEnd {
+			problems = append(problems, fmt.Sprintf(
+				"%s puts %q on PATH at %q; an entry goes at %q or %q of the account's PATH",
+				m.Module, p.Entry, p.At, PathAtStart, PathAtEnd))
+		}
+	}
+	return problems
+}
+
+// literalRule is why a value must be literal, said with every refusal of one.
+const literalRule = "a value is literal, so a POSIX shell and the service manager read it alike, and " +
+	"names the machine only through the mesh's own ${machine:…} facts (novox/hq ADR 0203)"
+
+// literalProblem is why a value cannot be written, unquoted by either reader, as the same string in
+// both formats — or nothing. A `$` would expand differently in each; a quote or a backslash is
+// quoting in one and a character in the other; a line break ends the line in both.
+func literalProblem(v string) string {
+	switch {
+	case strings.ContainsAny(v, `'"`):
+		return "holds a quote"
+	case strings.Contains(v, `\`):
+		return "holds a backslash"
+	case strings.ContainsAny(v, "\n\r"):
+		return "holds a line break"
+	case strings.ContainsRune(v, 0):
+		return "holds a NUL"
+	case strings.Contains(ofMachine.ReplaceAllString(v, ""), "$"):
+		return "holds a $ that is not one of the machine's ${machine:…} facts"
+	}
+	return ""
+}
+
+// shellProblems is what is wrong with this module's shell code, from the manifest alone. The code
+// itself is not judged: it is the shell's syntax, which the controller does not read.
+func (m Manifest) shellProblems() []string {
+	var problems []string
+	for i, c := range m.Shell {
+		if !oneOf(knownShells, c.For) {
+			problems = append(problems, fmt.Sprintf(
+				"%s's shell code %d is for %q; the shells are %s", m.Module, i+1, c.For,
+				strings.Join(knownShells, ", ")))
+		}
+		if !oneOf(knownSlots, c.Slot) {
+			problems = append(problems, fmt.Sprintf(
+				"%s's shell code %d goes in the slot %q; the slots are %s", m.Module, i+1, c.Slot,
+				strings.Join(knownSlots, ", ")))
+		}
+		if strings.TrimSpace(c.Code) == "" {
+			problems = append(problems, fmt.Sprintf("%s's shell code %d has no code", m.Module, i+1))
+		}
+	}
+	return problems
+}
+
+// contributionPlaceholderProblems is every place this module's resources name the environment or
+// the shell's code and may not — judged from the manifest, so the catalogue check refuses it before
+// a mesh does, and again at composition in the same words.
+func (m Manifest) contributionPlaceholderProblems() []string {
+	var problems []string
+	for _, r := range m.Resources {
+		problems = append(problems, placeholderProblems(m, r)...)
+	}
+	return problems
+}
+
+// placeholderProblems is what is wrong with one resource's ${environment:…} and ${shell:…}.
+//
+// **The seat authorises it, not the placeholder** (novox/hq ADR 0203 §5, ADR 0204 §3), as the seat
+// authorises the bus's user list: a module that does not hold the account's environment writing it
+// would be a second writer of a file there is one of, and a module that does not hold the login
+// shell writing every module's shell code would be a second shell.
+func placeholderProblems(m Manifest, r map[string]any) []string {
+	var problems []string
+	for _, field := range sortedKeys(r) {
+		s, ok := r[field].(string)
+		if !ok {
+			continue
+		}
+		env := ofEnvironment.FindAllStringSubmatch(s, -1)
+		code := ofShell.FindAllStringSubmatch(s, -1)
+		if len(env)+len(code) == 0 {
+			continue
+		}
+		if field != "content" {
+			// Placed only where a file's bytes are, which is where every one of them is meant to go:
+			// a path or an owner holding several lines of shell is nothing the host could act on.
+			problems = append(problems, fmt.Sprintf(
+				"%s's resource %v names %s in its %s; the environment and the shell's code are placed "+
+					"only in a file's content", m.Module, r["id"], placeholderOf(env, code), field))
+			continue
+		}
+		for _, e := range env {
+			if e[1] != EnvironmentPOSIX && e[1] != EnvironmentSystemd {
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %v names %s; the environment is ${environment:%s} or ${environment:%s}",
+					m.Module, r["id"], e[0], EnvironmentPOSIX, EnvironmentSystemd))
+			}
+		}
+		if len(env) > 0 && !m.ClaimsSeat(EnvironmentSeat) {
+			problems = append(problems, fmt.Sprintf(
+				"%s's resource %v names %s and %s does not claim %s; the account's environment is "+
+					"written by that seat's holder alone (novox/hq ADR 0203)",
+				m.Module, r["id"], env[0][0], m.Module, EnvironmentSeat))
+		}
+		for _, c := range code {
+			shell, slot, two := strings.Cut(c[1], ":")
+			if !two || !oneOf(knownShells, shell) || !oneOf(knownSlots, slot) {
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %v names %s; shell code is ${shell:<shell>:<slot>}, the shell one of "+
+						"%s and the slot one of %s", m.Module, r["id"], c[0],
+					strings.Join(knownShells, ", "), strings.Join(knownSlots, ", ")))
+			}
+		}
+		if len(code) > 0 && !m.ClaimsSeat(LoginShellSeat) {
+			problems = append(problems, fmt.Sprintf(
+				"%s's resource %v names %s and %s does not claim %s; every module's shell code is "+
+					"placed by the login shell's holder alone (novox/hq ADR 0204)",
+				m.Module, r["id"], code[0][0], m.Module, LoginShellSeat))
+		}
+	}
+	return problems
+}
+
+func placeholderOf(env, code [][]string) string {
+	if len(env) > 0 {
+		return env[0][0]
+	}
+	return code[0][0]
+}
+
+// contributedEnvironment is one node's environment, gathered and in the order it is written.
+type contributedEnvironment struct {
+	// variables is by module in name order, each module's sorted by name.
+	variables []setBy
+	// start and end are PATH's entries in their final order, each once.
+	start, end []placedOn
+}
+
+type setBy struct {
+	module string
+	names  []string
+	values map[string]string
+}
+
+type placedOn struct {
+	module, entry string
+}
+
+// inModuleOrder is the modules sorted by name — the order contributions are written in (novox/hq
+// ADR 0203, ADR 0204), so the same set composes byte for byte whatever order they were assigned in.
+func inModuleOrder(modules []Manifest) []Manifest {
+	out := append([]Manifest(nil), modules...)
+	sort.SliceStable(out, func(a, b int) bool { return out[a].Module < out[b].Module })
+	return out
+}
+
+// variablesSetOnce refuses a variable two modules on one node both set (novox/hq ADR 0203 §5),
+// naming both. Neither is chosen: whichever was written last would win in one reader and not
+// necessarily in the other, and the module that lost would not be told.
+func variablesSetOnce(modules []Manifest) error {
+	setter := map[string]string{}
+	for _, m := range inModuleOrder(modules) {
+		if m.Environment == nil {
+			continue
+		}
+		for _, n := range sortedKeys(m.Environment.Variables) {
+			if first, taken := setter[n]; taken {
+				return fmt.Errorf(
+					"%s and %s both set %s on this machine; the account has one environment, so one "+
+						"of them must stop setting it (novox/hq ADR 0203)", first, m.Module, n)
+			}
+			setter[n] = m.Module
+		}
+	}
+	return nil
+}
+
+// environmentOn gathers every module's environment on a node, with the machine's facts in place.
+//
+// A PATH entry two modules both add is written once, where the first puts it: two toolchains
+// sharing ~/.local/bin is ordinary, and nothing about it is in conflict.
+func environmentOn(modules []Manifest, facts map[string]string) (contributedEnvironment, error) {
+	var env contributedEnvironment
+	if err := variablesSetOnce(modules); err != nil {
+		return env, err
+	}
+	placed := map[string]bool{}
+	for _, m := range inModuleOrder(modules) {
+		if m.Environment == nil {
+			continue
+		}
+		if len(m.Environment.Variables) > 0 {
+			set := setBy{module: m.Module, values: map[string]string{}}
+			for _, n := range sortedKeys(m.Environment.Variables) {
+				v, err := factsIn(m.Environment.Variables[n], facts, m.Module, n)
+				if err != nil {
+					return env, err
+				}
+				set.names = append(set.names, n)
+				set.values[n] = v
+			}
+			env.variables = append(env.variables, set)
+		}
+		for _, p := range m.Environment.Path {
+			entry, err := factsIn(p.Entry, facts, m.Module, "a PATH entry")
+			if err != nil {
+				return env, err
+			}
+			if strings.Contains(entry, ":") {
+				return env, fmt.Errorf("%s puts %q on PATH on this machine, which holds a colon, PATH's own separator",
+					m.Module, entry)
+			}
+			if placed[entry] {
+				continue
+			}
+			placed[entry] = true
+			if p.At == PathAtEnd {
+				env.end = append(env.end, placedOn{m.Module, entry})
+			} else {
+				env.start = append(env.start, placedOn{m.Module, entry})
+			}
+		}
+	}
+	return env, nil
+}
+
+// factsIn resolves a contributed value's ${machine:…} facts with this machine's — first, before
+// either format is written, so both say the same thing (novox/hq ADR 0203).
+func factsIn(v string, facts map[string]string, module, what string) (string, error) {
+	for _, key := range machineUsed(v) {
+		value, has := facts[key]
+		if !has {
+			return "", fmt.Errorf("%s sets %s to a value that says ${machine:%s}, and this machine says %s",
+				module, what, key, orNothing(namesOfFacts(facts)))
+		}
+		v = strings.ReplaceAll(v, fmt.Sprintf("${machine:%s}", key), value)
+	}
+	// Judged again once filled: a fact is the mesh's, and still has to be a literal both readers
+	// take alike.
+	if why := literalProblem(v); why != "" {
+		return "", fmt.Errorf("%s sets %s to %q on this machine, which %s — %s", module, what, v, why, literalRule)
+	}
+	return v, nil
+}
+
+// posix is the environment as lines a POSIX shell sources (novox/hq ADR 0203 §3): every variable
+// exported, every PATH entry added only when it is missing, so sourcing the file twice — a login
+// shell that starts another — changes nothing. POSIX sh only, because sh, bash and zsh all read it.
+//
+// The start entries are written last-first: each is put in front of PATH, so the last written ends
+// up first, and the result reads in module order, then the order each module declared.
+func (e contributedEnvironment) posix() string {
+	var b strings.Builder
+	for _, set := range e.variables {
+		fmt.Fprintf(&b, "# %s\n", set.module)
+		for _, n := range set.names {
+			fmt.Fprintf(&b, "export %s='%s'\n", n, set.values[n])
+		}
+	}
+	named := ""
+	for i := len(e.start) - 1; i >= 0; i-- {
+		p := e.start[i]
+		if p.module != named {
+			fmt.Fprintf(&b, "# %s\n", p.module)
+			named = p.module
+		}
+		fmt.Fprintf(&b, "case \":${PATH}:\" in *':%s:'*) ;; *) PATH='%s'\"${PATH:+:${PATH}}\" ;; esac\n",
+			p.entry, p.entry)
+	}
+	named = ""
+	for _, p := range e.end {
+		if p.module != named {
+			fmt.Fprintf(&b, "# %s\n", p.module)
+			named = p.module
+		}
+		fmt.Fprintf(&b, "case \":${PATH}:\" in *':%s:'*) ;; *) PATH=\"${PATH:+${PATH}:}\"'%s' ;; esac\n",
+			p.entry, p.entry)
+	}
+	if len(e.start)+len(e.end) > 0 {
+		b.WriteString("export PATH\n")
+	}
+	return b.String()
+}
+
+// systemd is the same environment as the service manager's environment.d reads it (novox/hq ADR
+// 0203 §3), for the account's user manager and so for everything a graphical session starts. Read
+// once per manager start, so it needs no guard against running twice; the account's existing PATH
+// sits between the start and the end entries.
+func (e contributedEnvironment) systemd() string {
+	var b strings.Builder
+	for _, set := range e.variables {
+		fmt.Fprintf(&b, "# %s\n", set.module)
+		for _, n := range set.names {
+			fmt.Fprintf(&b, "%s=%s\n", n, set.values[n])
+		}
+	}
+	if len(e.start) > 0 {
+		fmt.Fprintf(&b, "# %s\nPATH=%s${PATH:+:$PATH}\n", modulesOf(e.start), entriesOf(e.start))
+	}
+	if len(e.end) > 0 {
+		fmt.Fprintf(&b, "# %s\nPATH=${PATH:+$PATH:}%s\n", modulesOf(e.end), entriesOf(e.end))
+	}
+	return b.String()
+}
+
+// modulesOf names who contributed a line holding several modules' entries, in the order they appear.
+func modulesOf(entries []placedOn) string {
+	var names []string
+	seen := map[string]bool{}
+	for _, p := range entries {
+		if !seen[p.module] {
+			seen[p.module] = true
+			names = append(names, p.module)
+		}
+	}
+	return strings.Join(names, ", ")
+}
+
+func entriesOf(entries []placedOn) string {
+	out := make([]string, len(entries))
+	for i, p := range entries {
+		out[i] = p.entry
+	}
+	return strings.Join(out, ":")
+}
+
+// shellCode is every module's code for one shell and one slot (novox/hq ADR 0204 §3): in module
+// order, each module's pieces in the order it declared them, each preceded by a line naming the
+// module, and empty when nothing is contributed.
+func shellCode(modules []Manifest, shell, slot string) string {
+	var b strings.Builder
+	for _, m := range inModuleOrder(modules) {
+		named := false
+		for _, c := range m.Shell {
+			if c.For != shell || c.Slot != slot {
+				continue
+			}
+			if !named {
+				fmt.Fprintf(&b, "# %s\n", m.Module)
+				named = true
+			}
+			b.WriteString(c.Code)
+			if !strings.HasSuffix(c.Code, "\n") {
+				b.WriteString("\n")
+			}
+		}
+	}
+	return b.String()
+}
+
+// contributionsInto fills a holder's file with the node's environment and its shell code.
+//
+// **Last, after every other placeholder pass, and in one pass each.** Shell code is contributed text
+// in a shell's own syntax — `${XDG_CACHE_HOME:-$HOME/.cache}`, `${(%):-%n}` — and the rendered
+// environment holds `${PATH:+…}`: a scanner for the mesh's own placeholders that ran after these
+// were in place would read the shell's expansions as the mesh's and refuse them, or fill a
+// `${machine:…}` some module wrote for its shell to see. So nothing runs after them, the environment
+// is filled before the shell's code is, and each is replaced in a single pass over what the holder
+// wrote, so a contributed piece is never scanned again.
+func contributionsInto(resource map[string]any, m Manifest, modules []Manifest, facts map[string]string) error {
+	if problems := placeholderProblems(m, resource); len(problems) > 0 {
+		return fmt.Errorf("%s", problems[0])
+	}
+	content, ok := resource["content"].(string)
+	if !ok {
+		return nil
+	}
+	if ofEnvironment.MatchString(content) {
+		env, err := environmentOn(modules, facts)
+		if err != nil {
+			return err
+		}
+		content = ofEnvironment.ReplaceAllStringFunc(content, func(placeholder string) string {
+			if ofEnvironment.FindStringSubmatch(placeholder)[1] == EnvironmentSystemd {
+				return env.systemd()
+			}
+			return env.posix()
+		})
+	}
+	if ofShell.MatchString(content) {
+		content = ofShell.ReplaceAllStringFunc(content, func(placeholder string) string {
+			shell, slot, _ := strings.Cut(ofShell.FindStringSubmatch(placeholder)[1], ":")
+			return shellCode(modules, shell, slot)
+		})
+	}
+	resource["content"] = content
+	return nil
+}

internal/catalogue/environment_into_test.go

@@ -0,0 +1,471 @@
+package catalogue
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Defends novox/hq ADR 0203 (the account's environment is one module's, and every module
+// contributes to it) and ADR 0204 (shell code in named slots, placed by the login shell's holder).
+
+// contributors is a fixed set of contributions, in no particular order: what the renderings are
+// asserted against byte for byte. go-toolchain and zsh both put ~/.local/bin on PATH, which is the
+// ordinary case of two modules sharing a directory, and is written once.
+func contributors() []Manifest {
+	return []Manifest{
+		{Module: "zsh", Environment: &Environment{
+			Variables: map[string]string{"XDG_CONFIG_HOME": "${machine:account-home}/.config", "EDITOR": "vim"},
+			Path: []PathEntry{
+				{Entry: "${machine:account-home}/.local/bin", At: PathAtStart},
+				{Entry: "${machine:account-home}/bin", At: PathAtStart},
+				{Entry: "/opt/scripts", At: PathAtEnd},
+			},
+		}},
+		{Module: "go-toolchain", Environment: &Environment{
+			Variables: map[string]string{"GOPATH": "${machine:account-home}/go"},
+			Path: []PathEntry{
+				{Entry: "${machine:account-home}/go/bin", At: PathAtStart},
+				{Entry: "/usr/local/go/bin", At: PathAtStart},
+				{Entry: "${machine:account-home}/.local/bin", At: PathAtStart},
+			},
+		}},
+		{Module: "agent", Environment: &Environment{
+			Variables: map[string]string{"DISABLE_AUTOUPDATER": "1"},
+			Path:      []PathEntry{{Entry: "/opt/agent/bin", At: PathAtEnd}},
+		}},
+		// A module contributing nothing is in the set and writes nothing.
+		{Module: "postgres"},
+	}
+}
+
+var operatorFacts = map[string]string{"name": "workstation", "account": "op", "account-home": "/home/op"}
+
+// The final PATH this set composes, around whatever the account had: the start entries in module
+// order and then declared order, the account's own, then the end entries.
+const composedPOSIX = `# agent
+export DISABLE_AUTOUPDATER='1'
+# go-toolchain
+export GOPATH='/home/op/go'
+# zsh
+export EDITOR='vim'
+export XDG_CONFIG_HOME='/home/op/.config'
+# zsh
+case ":${PATH}:" in *':/home/op/bin:'*) ;; *) PATH='/home/op/bin'"${PATH:+:${PATH}}" ;; esac
+# go-toolchain
+case ":${PATH}:" in *':/home/op/.local/bin:'*) ;; *) PATH='/home/op/.local/bin'"${PATH:+:${PATH}}" ;; esac
+case ":${PATH}:" in *':/usr/local/go/bin:'*) ;; *) PATH='/usr/local/go/bin'"${PATH:+:${PATH}}" ;; esac
+case ":${PATH}:" in *':/home/op/go/bin:'*) ;; *) PATH='/home/op/go/bin'"${PATH:+:${PATH}}" ;; esac
+# agent
+case ":${PATH}:" in *':/opt/agent/bin:'*) ;; *) PATH="${PATH:+${PATH}:}"'/opt/agent/bin' ;; esac
+# zsh
+case ":${PATH}:" in *':/opt/scripts:'*) ;; *) PATH="${PATH:+${PATH}:}"'/opt/scripts' ;; esac
+export PATH
+`
+
+const composedSystemd = `# agent
+DISABLE_AUTOUPDATER=1
+# go-toolchain
+GOPATH=/home/op/go
+# zsh
+EDITOR=vim
+XDG_CONFIG_HOME=/home/op/.config
+# go-toolchain, zsh
+PATH=/home/op/go/bin:/usr/local/go/bin:/home/op/.local/bin:/home/op/bin${PATH:+:$PATH}
+# agent, zsh
+PATH=${PATH:+$PATH:}/opt/agent/bin:/opt/scripts
+`
+
+func TestTheEnvironmentRendersForAPOSIXShellByteForByte(t *testing.T) {
+	env, err := environmentOn(contributors(), operatorFacts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := env.posix(); got != composedPOSIX {
+		t.Fatalf("the POSIX rendering is\n%s\nnot\n%s", got, composedPOSIX)
+	}
+}
+
+func TestTheEnvironmentRendersForTheServiceManagerByteForByte(t *testing.T) {
+	env, err := environmentOn(contributors(), operatorFacts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := env.systemd(); got != composedSystemd {
+		t.Fatalf("the environment.d rendering is\n%s\nnot\n%s", got, composedSystemd)
+	}
+}
+
+// Sourcing twice changes nothing (ADR 0203 §3): a login shell that starts another reads the file
+// again, and a PATH that grew each time would be the symptom. Run by a real `sh`, because the claim
+// is about what a shell does with the file, not about what the file looks like.
+func TestThePOSIXEnvironmentSourcedTwiceLeavesPATHAsOnce(t *testing.T) {
+	sh, err := exec.LookPath("sh")
+	if err != nil {
+		t.Skip("no sh on this machine")
+	}
+	script := "PATH=/usr/bin:/bin\n" + composedPOSIX + "once=$PATH\n" + composedPOSIX +
+		`[ "$PATH" = "$once" ] || { echo "changed: $once -> $PATH"; exit 1; }` + "\n" +
+		`echo "$PATH"; echo "$GOPATH"`
+	out, err := exec.Command(sh, "-c", script).CombinedOutput()
+	if err != nil {
+		t.Fatalf("sourcing twice: %v\n%s", err, out)
+	}
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	want := "/home/op/go/bin:/usr/local/go/bin:/home/op/.local/bin:/home/op/bin:/usr/bin:/bin:/opt/agent/bin:/opt/scripts"
+	if lines[0] != want {
+		t.Fatalf("PATH is %s, not %s", lines[0], want)
+	}
+	if lines[1] != "/home/op/go" {
+		t.Fatalf("GOPATH was not exported: %q", lines[1])
+	}
+	// And an entry the account already has stays where it is, and once.
+	out, err = exec.Command(sh, "-c", "PATH=/opt/scripts:/usr/bin\n"+composedPOSIX+`echo "$PATH"`).CombinedOutput()
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	if got := strings.TrimSpace(string(out)); got !=
+		"/home/op/go/bin:/usr/local/go/bin:/home/op/.local/bin:/home/op/bin:/opt/scripts:/usr/bin:/opt/agent/bin" {
+		t.Fatalf("an entry already on PATH was added again or moved: %s", got)
+	}
+}
+
+// The environment.d rendering, read by the service manager's own generator where this machine has
+// one — the same reader an account's user manager runs, so the PATH it composes is the one asserted.
+func TestTheServiceManagerReadsTheSystemdRenderingAsMeant(t *testing.T) {
+	generator := "/usr/lib/systemd/user-environment-generators/30-systemd-environment-d-generator"
+	if _, err := os.Stat(generator); err != nil {
+		t.Skip("no environment.d generator on this machine")
+	}
+	config := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(config, "environment.d"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(config, "environment.d", "50-mesh.conf"), []byte(composedSystemd), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	cmd := exec.Command(generator)
+	cmd.Env = []string{"PATH=/usr/bin:/bin", "HOME=" + config, "XDG_CONFIG_HOME=" + config}
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("%v\n%s", err, out)
+	}
+	want := "PATH=/home/op/go/bin:/usr/local/go/bin:/home/op/.local/bin:/home/op/bin:/usr/bin:/bin:/opt/agent/bin:/opt/scripts"
+	if !strings.Contains(string(out), want+"\n") || !strings.Contains(string(out), "GOPATH=/home/op/go\n") {
+		t.Fatalf("the service manager read\n%s", out)
+	}
+}
+
+// Nothing contributed renders nothing, in both formats — not an empty `export PATH`.
+func TestNoContributionsRenderNothing(t *testing.T) {
+	env, err := environmentOn([]Manifest{{Module: "postgres"}}, operatorFacts)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if env.posix() != "" || env.systemd() != "" {
+		t.Fatalf("an empty environment rendered %q and %q", env.posix(), env.systemd())
+	}
+}
+
+// A ${machine:…} fact the machine does not have is refused naming the module, as a file's is.
+func TestAContributedFactTheMachineLacksIsRefused(t *testing.T) {
+	_, err := environmentOn(contributors(), map[string]string{"name": "server"})
+	if err == nil || !strings.Contains(err.Error(), "go-toolchain sets GOPATH") ||
+		!strings.Contains(err.Error(), "${machine:account-home}") {
+		t.Fatalf("a missing account home was not refused by name: %v", err)
+	}
+}
+
+// ADR 0203 §5: two modules setting one variable are refused, both named — neither silently wins.
+func TestAVariableTwoModulesSetIsRefusedNamingBoth(t *testing.T) {
+	modules := append(contributors(), Manifest{Module: "neovim", Environment: &Environment{
+		Variables: map[string]string{"EDITOR": "nvim"}}})
+	_, err := environmentOn(modules, operatorFacts)
+	if err == nil || err.Error() != "neovim and zsh both set EDITOR on this machine; the account has one "+
+		"environment, so one of them must stop setting it (novox/hq ADR 0203)" {
+		t.Fatalf("a variable set twice was not refused naming both: %v", err)
+	}
+	// And at composition, whether or not the node holds the environment.
+	r := Resolution{Node: "workstation", Account: "op", Modules: modules}
+	if _, err := r.Declaration(Rendering{}); err == nil || !strings.Contains(err.Error(), "neovim and zsh both set EDITOR") {
+		t.Fatalf("composition accepted a variable set twice: %v", err)
+	}
+}
+
+// shells contributes code for several shells and slots, in no order.
+func shells() []Manifest {
+	return []Manifest{
+		{Module: "zsh-syntax-highlighting", Shell: []ShellCode{
+			{For: "zsh", Slot: "last", Code: "source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh"},
+		}},
+		{Module: "powerlevel10k", Shell: []ShellCode{
+			{For: "zsh", Slot: "first", Code: "if [[ -r \"${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh\" ]]; then\n" +
+				"  source \"${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh\"\nfi\n"},
+			{For: "zsh", Slot: "normal", Code: "source ~/.local/share/powerlevel10k/powerlevel10k.zsh-theme"},
+			{For: "zsh", Slot: "normal", Code: "[[ -f ~/.local/share/powerlevel10k/p10k.zsh ]] && source ~/.local/share/powerlevel10k/p10k.zsh"},
+		}},
+		{Module: "zsh-autosuggestions", Shell: []ShellCode{
+			{For: "zsh", Slot: "normal", Code: "source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh"},
+			{For: "bash", Slot: "normal", Code: "echo not for zsh"},
+		}},
+		{Module: "direnv", Shell: []ShellCode{
+			{For: "fish", Slot: "last", Code: "direnv hook fish | source"},
+			{For: "bash", Slot: "last", Code: "eval \"$(direnv hook bash)\""},
+		}},
+	}
+}
+
+// ADR 0204 §3: a slot holds that shell's code only, in module order, each module's pieces in the
+// order it declared them under a line naming it; empty when nothing is contributed.
+func TestShellCodeLandsInItsSlotInModuleOrderForItsShellOnly(t *testing.T) {
+	if got, want := shellCode(shells(), "zsh", "normal"), "# powerlevel10k\n"+
+		"source ~/.local/share/powerlevel10k/powerlevel10k.zsh-theme\n"+
+		"[[ -f ~/.local/share/powerlevel10k/p10k.zsh ]] && source ~/.local/share/powerlevel10k/p10k.zsh\n"+
+		"# zsh-autosuggestions\n"+
+		"source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh\n"; got != want {
+		t.Fatalf("zsh's normal slot is\n%s\nnot\n%s", got, want)
+	}
+	if got, want := shellCode(shells(), "zsh", "last"), "# zsh-syntax-highlighting\n"+
+		"source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh\n"; got != want {
+		t.Fatalf("zsh's last slot is\n%s\nnot\n%s", got, want)
+	}
+	if got, want := shellCode(shells(), "bash", "last"), "# direnv\neval \"$(direnv hook bash)\"\n"; got != want {
+		t.Fatalf("bash's last slot is %q, not %q", got, want)
+	}
+	if got := shellCode(shells(), "fish", "first"); got != "" {
+		t.Fatalf("a slot nobody contributed to holds %q", got)
+	}
+}
+
+// The holder of node-login-shell, as WP3's zsh module writes its block, with its own zsh around the
+// slots — which holds `${…}` of the shell's own that no mesh pass may touch either.
+func zshHolder() Manifest {
+	return Manifest{Module: "zsh", Claims: []Claim{{Name: LoginShellSeat, Scope: ScopeNode}},
+		Resources: []map[string]any{
+			{"id": "zshrc", "type": "file", "path": "${machine:account-home}/.zshrc", "content": "" +
+				"${shell:zsh:first}" +
+				"PROMPT='%n@%m ${PWD/#$HOME/~} '\n" +
+				"${shell:zsh:normal}" +
+				"alias ll='ls -l'\n" +
+				"${shell:zsh:last}"},
+		}}
+}
+
+// The case the ordering exists for: contributed zsh code full of `${…}` reaches the file byte for
+// byte, because the shell's code is placed after every other placeholder pass and in one pass — a
+// scanner for the mesh's placeholders that ran after it would read `${XDG_CACHE_HOME:-…}` and
+// `${(%):-%n}` as the mesh's, or fill a `${machine:…}` some module wrote for its shell to see.
+func TestShellCodeReachesTheHoldersFileByteForByte(t *testing.T) {
+	modules := append(shells(), zshHolder(), Manifest{Module: "sly", Shell: []ShellCode{
+		{For: "zsh", Slot: "last", Code: "echo ${machine:account-home} ${secret:x} ${shell:zsh:first} ${environment:posix}"},
+	}})
+	r := Resolution{Node: "workstation", Account: "op", Modules: modules}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var zshrc map[string]any
+	for _, res := range out {
+		if res["id"] == "zsh.zshrc" {
+			zshrc = res
+		}
+	}
+	if zshrc == nil {
+		t.Fatalf("the holder's file was not composed: %v", out)
+	}
+	if zshrc["path"] != "/home/op/.zshrc" {
+		t.Fatalf("the holder's own placeholders were not filled first: %v", zshrc["path"])
+	}
+	want := "# powerlevel10k\n" +
+		"if [[ -r \"${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh\" ]]; then\n" +
+		"  source \"${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh\"\nfi\n" +
+		"PROMPT='%n@%m ${PWD/#$HOME/~} '\n" +
+		"# powerlevel10k\n" +
+		"source ~/.local/share/powerlevel10k/powerlevel10k.zsh-theme\n" +
+		"[[ -f ~/.local/share/powerlevel10k/p10k.zsh ]] && source ~/.local/share/powerlevel10k/p10k.zsh\n" +
+		"# zsh-autosuggestions\n" +
+		"source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh\n" +
+		"alias ll='ls -l'\n" +
+		"# sly\n" +
+		"echo ${machine:account-home} ${secret:x} ${shell:zsh:first} ${environment:posix}\n" +
+		"# zsh-syntax-highlighting\n" +
+		"source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh\n"
+	if got := zshrc["content"]; got != want {
+		t.Fatalf("the holder's .zshrc is\n%s\nnot\n%s", got, want)
+	}
+}
+
+// The holder of node-environment places both renderings, and they are the same as rendered alone.
+func TestTheEnvironmentHolderPlacesBothRenderings(t *testing.T) {
+	holder := Manifest{Module: "node-env", Claims: []Claim{{Name: EnvironmentSeat, Scope: ScopeNode}},
+		Resources: []map[string]any{
+			{"id": "posix", "type": "file", "path": "${machine:account-home}/.config/mesh/environment.sh",
+				"content": "# The mesh's environment.\n${environment:posix}"},
+			{"id": "systemd", "type": "file", "path": "${machine:account-home}/.config/environment.d/50-mesh.conf",
+				"content": "${environment:systemd}"},
+		}}
+	r := Resolution{Node: "workstation", Account: "op", Modules: append(contributors(), holder)}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	by := map[string]any{}
+	for _, res := range out {
+		by[res["id"].(string)] = res["content"]
+	}
+	if by["node-env.posix"] != "# The mesh's environment.\n"+composedPOSIX {
+		t.Fatalf("the POSIX file is\n%v", by["node-env.posix"])
+	}
+	if by["node-env.systemd"] != composedSystemd {
+		t.Fatalf("the environment.d file is\n%v", by["node-env.systemd"])
+	}
+}
+
+// ADR 0203 §5 and ADR 0204 §3: a placeholder outside the seat's holder is refused — by the parser,
+// which is what the catalogue check and registration run, and again at composition, in the same words.
+func TestAPlaceholderOutsideTheHolderIsRefused(t *testing.T) {
+	for _, c := range []struct{ content, want string }{
+		{"${environment:posix}", "toolchain's resource rc names ${environment:posix} and toolchain does not claim node-environment"},
+		{"${shell:zsh:normal}", "toolchain's resource rc names ${shell:zsh:normal} and toolchain does not claim node-login-shell"},
+	} {
+		raw := `{"module":"toolchain","resources":[{"id":"rc","type":"file","path":"/etc/rc","content":"` + c.content + `"}]}`
+		if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("the catalogue check accepted %s outside its holder: %v", c.content, err)
+		}
+		m := Manifest{Module: "toolchain", Resources: []map[string]any{
+			{"id": "rc", "type": "file", "path": "/etc/rc", "content": c.content}}}
+		r := Resolution{Node: "workstation", Account: "op", Modules: []Manifest{m}}
+		if _, err := r.Declaration(Rendering{}); err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("composition accepted %s outside its holder: %v", c.content, err)
+		}
+	}
+}
+
+// A key nobody renders is refused, not left in the file as a literal.
+func TestAnUnknownPlaceholderKeyIsRefused(t *testing.T) {
+	for _, c := range []struct{ content, want string }{
+		{"${environment:foo}", "names ${environment:foo}; the environment is ${environment:posix} or ${environment:systemd}"},
+		{"${shell:zsh:middle}", "names ${shell:zsh:middle}; shell code is ${shell:<shell>:<slot>}"},
+		{"${shell:tcsh:first}", "names ${shell:tcsh:first}; shell code is ${shell:<shell>:<slot>}"},
+		{"${shell:zsh}", "names ${shell:zsh}; shell code is ${shell:<shell>:<slot>}"},
+	} {
+		raw := `{"module":"holder","claims":[{"name":"node-environment","scope":"node"},{"name":"node-login-shell","scope":"node"}],` +
+			`"resources":[{"id":"rc","type":"file","path":"/etc/rc","content":"` + c.content + `"}]}`
+		if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s was accepted: %v", c.content, err)
+		}
+	}
+	// And outside a file's content, where nothing could be placed.
+	raw := `{"module":"holder","claims":[{"name":"node-environment","scope":"node"}],` +
+		`"resources":[{"id":"rc","type":"file","path":"/etc/${environment:posix}","content":"x"}]}`
+	if _, err := ParseManifest([]byte(raw)); err == nil ||
+		!strings.Contains(err.Error(), "names ${environment:posix} in its path; the environment and the shell's code are placed only in a file's content") {
+		t.Errorf("a placeholder in a path was accepted: %v", err)
+	}
+}
+
+// What ADR 0203 §2 allows a contribution to say, refused at parse when it says anything else.
+func TestAMalformedEnvironmentIsRefusedAtParse(t *testing.T) {
+	for _, c := range []struct{ environment, want string }{
+		{`{"variables":{"1X":"a"}}`, `tool sets the variable "1X", which is not a name a shell accepts`},
+		{`{"variables":{"MY-VAR":"a"}}`, `tool sets the variable "MY-VAR", which is not a name a shell accepts`},
+		{`{"variables":{"PATH":"/bin"}}`, `tool sets PATH as a variable; a module adds an entry under environment.path`},
+		{`{"variables":{"A":"$HOME/x"}}`, `tool sets A to "$HOME/x", which holds a $ that is not one of the machine's ${machine:…} facts`},
+		{`{"variables":{"A":"${HOME}/x"}}`, `tool sets A to "${HOME}/x", which holds a $`},
+		{`{"variables":{"A":"it's"}}`, `tool sets A to "it's", which holds a quote`},
+		{`{"variables":{"A":"say \"hi\""}}`, `which holds a quote`},
+		{`{"variables":{"A":"a\\b"}}`, `which holds a backslash`},
+		{`{"variables":{"A":"a\nb"}}`, `which holds a line break`},
+		{`{"variables":{"A":"a\u0000b"}}`, `which holds a NUL`},
+		{`{"path":[{"entry":"","at":"start"}]}`, `tool's PATH entry 1 names no directory`},
+		{`{"path":[{"entry":"/a:/b","at":"start"}]}`, `tool puts "/a:/b" on PATH, which holds a colon`},
+		{`{"path":[{"entry":"$HOME/bin","at":"start"}]}`, `tool puts "$HOME/bin" on PATH, which holds a $`},
+		{`{"path":[{"entry":"/a","at":"middle"}]}`, `tool puts "/a" on PATH at "middle"; an entry goes at "start" or "end"`},
+		{`{"path":[{"entry":"/a"}]}`, `tool puts "/a" on PATH at ""`},
+		{`{"path":[{"entry":"/a","at":"start"},{"entry":"/a","at":"end"}]}`, `tool puts "/a" on PATH twice`},
+		{`{"variables":{"A":"x"},"paths":[]}`, `unknown field "paths"`},
+	} {
+		_, err := ParseManifest([]byte(`{"module":"tool","environment":` + c.environment + `}`))
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: want %q, got %v", c.environment, c.want, err)
+		}
+	}
+	// What is allowed: a literal, and the machine's own facts.
+	if _, err := ParseManifest([]byte(`{"module":"tool","environment":{` +
+		`"variables":{"GOPATH":"${machine:account-home}/go","DISABLE_X":"1","ANSWER":"a b+c=d"},` +
+		`"path":[{"entry":"${machine:account-home}/go/bin","at":"start"},{"entry":"/opt/x","at":"end"}]}}`)); err != nil {
+		t.Fatalf("a well-formed environment was refused: %v", err)
+	}
+}
+
+func TestMalformedShellCodeIsRefusedAtParse(t *testing.T) {
+	for _, c := range []struct{ shell, want string }{
+		{`[{"for":"tcsh","slot":"normal","code":"x"}]`, `tool's shell code 1 is for "tcsh"; the shells are zsh, bash, fish`},
+		{`[{"for":"zsh","slot":"middle","code":"x"}]`, `tool's shell code 1 goes in the slot "middle"; the slots are first, normal, last`},
+		{`[{"for":"zsh","slot":"last","code":"x"},{"for":"zsh","slot":"last","code":" \n"}]`, `tool's shell code 2 has no code`},
+		{`[{"for":"zsh","slot":"last","code":"x","order":1}]`, `unknown field "order"`},
+	} {
+		_, err := ParseManifest([]byte(`{"module":"tool","shell":` + c.shell + `}`))
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: want %q, got %v", c.shell, c.want, err)
+		}
+	}
+	// The code itself is never judged: a shell's own `${…}` is not the mesh's.
+	if _, err := ParseManifest([]byte(`{"module":"tool","shell":[{"for":"zsh","slot":"first",` +
+		`"code":"source \"${XDG_CACHE_HOME:-$HOME/.cache}/p10k-instant-prompt-${(%):-%n}.zsh\""}]}`)); err != nil {
+		t.Fatalf("shell code was judged as if it were the mesh's: %v", err)
+	}
+}
+
+// ADR 0203 §1 and ADR 0204 §1: both seats are the mesh's own, held once per machine; the login
+// shell's contract is `execute`, described and with a schema an agent can call.
+func TestTheSeatTableCarriesTheEnvironmentAndTheLoginShell(t *testing.T) {
+	env, ok := SeatNamed("node-environment")
+	if !ok || env.Scope != ScopeNode || env.Decision != "novox/hq ADR 0203" ||
+		len(env.Serves)+len(env.Accepts)+len(env.Emits) != 0 || env.Delivers != "" {
+		t.Fatalf("node-environment is not a node seat with no protocol: %+v (defined %v)", env, ok)
+	}
+	shell, ok := SeatNamed("node-login-shell")
+	if !ok || shell.Scope != ScopeNode || shell.Decision != "novox/hq ADR 0204" {
+		t.Fatalf("node-login-shell is not a node seat: %+v (defined %v)", shell, ok)
+	}
+	if len(shell.Serves) != 1 || shell.Serves[0].Name != "execute" || shell.Serves[0].Description == "" {
+		t.Fatalf("the login shell serves %+v, not execute alone", shell.Serves)
+	}
+	props, _ := shell.Serves[0].Input["properties"].(map[string]any)
+	required, _ := shell.Serves[0].Input["required"].([]string)
+	if _, has := props["command"]; !has || len(required) != 1 || required[0] != "command" {
+		t.Fatalf("execute does not require a command: %v", shell.Serves[0].Input)
+	}
+	if _, has := props["timeout_seconds"]; !has {
+		t.Fatalf("execute takes no timeout: %v", props)
+	}
+}
+
+// ADR 0204 §1: the login shell is the mesh's, so no module declares it — neither under the mesh's
+// name nor under the name a module gave it before.
+func TestNoModuleMayDeclareTheLoginShell(t *testing.T) {
+	for _, n := range []string{"login-shell", "node-login-shell", "node-environment"} {
+		raw := `{"module":"zsh","seats":[{"name":"` + n + `","scope":"node","serves":["execute"]}],"tools":["execute"]}`
+		_, err := ParseManifest([]byte(raw))
+		if err == nil {
+			t.Errorf("a module declaring %q was accepted", n)
+		}
+	}
+	got := strings.Join(declaredSeatProblems(Manifest{Module: "zsh",
+		DefinesSeats: []SeatDeclaration{{Name: "login-shell", Scope: ScopeNode}}}), "; ")
+	if !strings.Contains(got, `zsh declares a seat named "login-shell"; the login shell is the mesh's own seat node-login-shell`) {
+		t.Fatalf("declaring login-shell was not refused by name: %q", got)
+	}
+	// And a shell module claiming the mesh's seat, serving execute, is what the seat is for.
+	m, err := ParseManifest([]byte(`{"module":"zsh","tools":["execute"],` +
+		`"claims":[{"name":"node-login-shell","scope":"node"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := CanHold(m, Seat{Name: LoginShellSeat, Scope: ScopeNode, Serves: loginShellVerbs()}); err != nil {
+		t.Fatalf("a shell module claiming the seat cannot hold it: %v", err)
+	}
+}

internal/catalogue/foundation_manifests_test.go

@@ -1,6 +1,7 @@
 package catalogue
 
 import (
+	"encoding/json"
 	"fmt"
 	"os"
 	"reflect"
@@ -170,7 +171,7 @@ func TestTheForgeHoldsTheNpmAndGitSeats(t *testing.T) {
 // **And the forge's own address follows it**, composed from the manifest in the catalogue beside
 // this checkout (novox/hq 04-ISSUES/088).
 //
-// The forge is reached a third way that neither test above covers: by its own sidecar, over the
+// The forge is reached a third way that neither test above covers: by its own code, over the
 // machine's loopback, told where to go in its environment. The `2999:3000` mapping that lets the
 // forge go on binding 3000 does nothing for a caller dialling the machine — so a literal there is
 // wrong on every node whose assignment differs, and wrong for a second reason on a node given the
@@ -178,13 +179,13 @@ func TestTheForgeHoldsTheNpmAndGitSeats(t *testing.T) {
 // in an `env` at all is a declaration, not a manifest.
 func TestTheForgesOwnAddressFollowsThePortTheNodeGaveIt(t *testing.T) {
 	forge, err := catalogueManifest(t, "gitea").Resolve([]Built{{
-		Name: "runtime", Kind: ArtifactImage,
-		Reference: "registry.example/gitea-runtime@sha256:" + strings.Repeat("a", 64),
+		Name: "code", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "gitea/code/blobs/" + bundleDigest, Digest: bundleDigest,
 	}})
 	if err != nil {
 		t.Fatalf("the forge's manifest does not resolve against its own build: %v", err)
 	}
-	r := Resolution{Node: "anchor", Modules: []Manifest{forge}, Needs: []Needed{
+	r := Resolution{Node: "anchor", Modules: []Manifest{forge, theRuntime(t)}, Needs: []Needed{
 		{Name: "postgres-database", For: "gitea", From: "anchor", At: "127.0.0.1",
 			Serves: map[string]any{"port": float64(5432)}, Sealed: "sealed-db"},
 		{Name: "route", For: "gitea", From: "anchor"},
@@ -194,8 +195,8 @@ func TestTheForgesOwnAddressFollowsThePortTheNodeGaveIt(t *testing.T) {
 
 	// The number this node was given for the forge — the one the machine it is about to run on
 	// already publishes.
-	out, err := r.Declaration(Rendering{
-		Needed: map[string]map[string]string{"gitea": {"broker": "sealed-broker"}},
+	out, err := r.Declaration(Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-broker"}},
 		Given:  map[string]map[int]int{"gitea": {3000: 2999}},
 	})
 	if err != nil {
@@ -210,14 +211,19 @@ func TestTheForgesOwnAddressFollowsThePortTheNodeGaveIt(t *testing.T) {
 	if published := fmt.Sprint(server["ports"]); !strings.Contains(published, "2999:3000") {
 		t.Fatalf("the forge is not published on the port this node gave it: %v", server["ports"])
 	}
-	runtime := fileNamed(out, "gitea.runtime")
+	// The forge's own code runs in the node's runtime (novox/hq ADR 0198), given its words there.
+	runtime := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
 	if runtime == nil {
-		t.Fatalf("the forge's sidecar is not in the declaration: %v", out)
+		t.Fatalf("the node's runtime is not in the declaration: %v", ids(out))
 	}
-	env, _ := runtime["env"].(map[string]any)
-	if env["MESH_GITEA_URL"] != "http://127.0.0.1:2999" {
-		t.Fatalf("the forge's sidecar dials %v while the machine publishes the forge on 2999 — "+
-			"whatever reads it dials a dead port", env["MESH_GITEA_URL"])
+	env, _ := runtime["env"].(map[string]string)
+	var given map[string]map[string]string
+	if err := json.Unmarshal([]byte(env[RuntimeToolEnv]), &given); err != nil {
+		t.Fatalf("the runtime's %s is not JSON: %q", RuntimeToolEnv, env[RuntimeToolEnv])
+	}
+	if given["gitea"]["MESH_GITEA_URL"] != "http://127.0.0.1:2999" {
+		t.Fatalf("the forge's code dials %v while the machine publishes the forge on 2999 — "+
+			"whatever reads it dials a dead port", given["gitea"]["MESH_GITEA_URL"])
 	}
 }
 
@@ -229,13 +235,13 @@ func declaredGiteaSsh(t *testing.T, given map[int]int) map[string]any {
 	t.Helper()
 	forge := catalogueManifest(t, "gitea")
 	resolved, err := forge.Resolve([]Built{{
-		Name: "runtime", Kind: ArtifactImage,
-		Reference: "registry.example/gitea-runtime@sha256:" + strings.Repeat("a", 64),
+		Name: "code", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "gitea/code/blobs/" + bundleDigest, Digest: bundleDigest,
 	}})
 	if err != nil {
 		t.Fatalf("the forge's manifest does not resolve against its own build: %v", err)
 	}
-	r := Resolution{Node: "anchor", Modules: []Manifest{resolved}, Needs: []Needed{
+	r := Resolution{Node: "anchor", Modules: []Manifest{resolved, theRuntime(t)}, Needs: []Needed{
 		{Name: "postgres-database", For: "gitea", From: "anchor", At: "127.0.0.1",
 			Serves: map[string]any{"port": float64(5432)}, Sealed: "sealed-db"},
 		{Name: "route", For: "gitea", From: "anchor"},
@@ -246,8 +252,8 @@ func declaredGiteaSsh(t *testing.T, given map[int]int) map[string]any {
 	for k, v := range given {
 		givenPorts[k] = v
 	}
-	out, err := r.Declaration(Rendering{
-		Needed: map[string]map[string]string{"gitea": {"broker": "sealed-broker"}},
+	out, err := r.Declaration(Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-broker"}},
 		Ports:  map[string]map[int]int{"gitea": givenPorts},
 		Given:  map[string]map[int]int{"gitea": given},
 	})

internal/catalogue/genesis_image_test.go

@@ -0,0 +1,29 @@
+package catalogue
+
+import (
+	"os"
+	"regexp"
+	"testing"
+)
+
+// novox/hq issue 223: genesis raises the controller as a container built from this repository's own
+// Dockerfile, with no build arguments — the manifest no longer builds an image, so nothing passes a
+// base in. The Dockerfile's own default must therefore be a Go that builds this module, pinned by
+// digest, and the replacement the manifest's process names must be the container genesis raises.
+func TestGenesisCanBuildTheControllersImageAsItStands(t *testing.T) {
+	raw, err := os.ReadFile("../../Dockerfile")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !regexp.MustCompile(`(?m)^ARG GO_BASE=golang@sha256:[0-9a-f]{64}$`).Match(raw) {
+		t.Fatal("the Dockerfile's default Go base is not pinned by digest; genesis builds it with no arguments")
+	}
+	makefile, err := os.ReadFile("../../Makefile")
+	if err != nil {
+		t.Fatal(err)
+	}
+	pin := regexp.MustCompile(`golang@sha256:[0-9a-f]{64}`)
+	if string(pin.Find(raw)) != string(pin.Find(makefile)) {
+		t.Errorf("the Dockerfile and the Makefile build on different Go: %s, %s", pin.Find(raw), pin.Find(makefile))
+	}
+}

internal/catalogue/grant_secret_owner_test.go

@@ -0,0 +1,103 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A grant secret is read by whatever provisions, and that stopped being root (novox/hq issue 225).
+//
+// The mesh seals one credential per consumer beside the provider's contributions file. The
+// provider's harness reads both: the file to learn who asked, the secret to set their password.
+// While a module's own code ran in a container as root, a root-owned 0600 file was readable by
+// the thing that needed it. ADR 0198 moved that code under the node's runtime, which runs as the
+// operator's account — and the secret stayed root's.
+//
+// **The cost was silence.** The harness says `secret not readable yet`, which is true and
+// ordinary on the first pass, so four thousand refusals in three hours read as patience. No user
+// was ever created, and two consumers crash-looped against a database that had never heard of
+// them.
+//
+// The same reasoning is already written for a module's *own* secrets, three hundred lines above:
+// "a root-owned 0600 file is one that process cannot read". This is that rule reaching the other
+// kind of secret the mesh writes for a module.
+
+// aProviderWithABundle is a provider whose code is a bundle the node's runtime runs — the shape
+// every TypeScript provisioner has since ADR 0198.
+func aProviderWithABundle() Manifest {
+	return Manifest{
+		Module: "mongodb", Version: "1",
+		Provides: FromAnywhere("mongodb-database"),
+		Receives: map[string]string{"mongodb-database": "/var/lib/mongodb/grants/mesh.json"},
+		Grants:   map[string]string{"mongodb-database": "/var/lib/mongodb/grants"},
+		Bundles:  []Bundle{{Name: "code", Language: "typescript"}},
+		Resources: []map[string]any{{
+			"id": "server", "type": "container", "name": "mongodb-server",
+			"image": "mongo@sha256:" + strings.Repeat("a", 64),
+		}},
+	}
+}
+
+func TestAGrantSecretIsOwnedByTheAccountThatProvisions(t *testing.T) {
+	r, err := Resolve(shelf(aProviderWithABundle()), []string{"mongodb"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account = "operator"
+	out, err := r.Declaration(Rendering{Grants: []Grant{{
+		Provision: "mongodb-database", Consumer: "workstation", From: "photos", Slug: "photos",
+		Values: map[string]any{}, Sealed: "c2VhbGVk",
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var secret map[string]any
+	for _, res := range out {
+		if res["type"] == "file" && strings.HasSuffix(fmtPath(res), ".secret") {
+			secret = res
+		}
+	}
+	if secret == nil {
+		t.Fatalf("no grant secret was composed at all: %v", out)
+	}
+	if got := secret["owner"]; got != "operator" {
+		t.Fatalf("the grant secret at %v belongs to %v; the provisioner runs as %q and a "+
+			"root-owned 0600 file is one it cannot read — which is silent, because the harness "+
+			"calls it \"not readable yet\"", fmtPath(secret), got, "operator")
+	}
+}
+
+// And a provider whose code still runs in a container keeps the owner it declares, so this
+// changes nothing for the modules the runtime has not taken.
+func TestAContainerProvidersGrantSecretKeepsItsDeclaredOwner(t *testing.T) {
+	m := aProviderWithABundle()
+	m.Bundles = nil
+	m.SecretsOwner = "65534:65534"
+	r, err := Resolve(shelf(m), []string{"mongodb"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account = "operator"
+	out, err := r.Declaration(Rendering{Grants: []Grant{{
+		Provision: "mongodb-database", Consumer: "workstation", From: "photos", Slug: "photos",
+		Values: map[string]any{}, Sealed: "c2VhbGVk",
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, res := range out {
+		if res["type"] == "file" && strings.HasSuffix(fmtPath(res), ".secret") {
+			if got := res["owner"]; got != "65534:65534" {
+				t.Fatalf("a container provider's grant secret belongs to %v, not what it declares", got)
+			}
+			return
+		}
+	}
+	t.Fatal("no grant secret was composed")
+}
+
+func fmtPath(r map[string]any) string {
+	p, _ := r["path"].(string)
+	return p
+}

internal/catalogue/manifest.go

@@ -325,6 +325,15 @@ type Manifest struct {
 	// person's account (design 25 §7) already had the same shape.
 	Invokes []string `json:"invokes,omitempty"`
 
+	// State is the current state this module keeps on the bus, by local name: each a key-value
+	// bucket the controller creates, which every instance of the module writes and reads
+	// (novox/hq ADR 0201). Not history — that is an event — and never a secret, sealed or not.
+	State []StateDeclaration `json:"state,omitempty"`
+
+	// Reads are other modules' state this module reads and watches, each `<module>.<name>`
+	// (novox/hq ADR 0201). Read-only: only the owner's instances write.
+	Reads []string `json:"reads,omitempty"`
+
 	// Capabilities the machine must have. A different field from Requires because the remedy
 	// differs: a missing module can be assigned, and a missing capability means the wrong
 	// machine.
@@ -508,6 +517,17 @@ type Manifest struct {
 	// holder. Like Filtering: one module per node gathers what every module declared and writes it.
 	Jailing *Jailing `json:"jailing,omitempty"`
 
+	// Environment is what this module adds to the operator account's environment: variables, and
+	// entries on PATH (novox/hq ADR 0203). Facts, not lines of one shell's syntax — the holder of
+	// node-environment places them, and the controller writes them in each reader's format. Like
+	// Jails: any module contributes, gathered from every module on the node, written by the holder.
+	Environment *Environment `json:"environment,omitempty"`
+
+	// Shell is code this module adds to the login shell's startup, for a named shell in a named
+	// slot (novox/hq ADR 0204). The controller never reads it: it is placed, in module order, where
+	// the holder of node-login-shell put the slot's placeholder.
+	Shell []ShellCode `json:"shell,omitempty"`
+
 	// Guards are ports of this module's the mesh refuses on an adopted node except from the
 	// private network and from the machine itself (novox/hq ADR 0100) — the store's port and the
 	// broker's management port. The ports the software uses; the mesh guards where the machine
@@ -1316,6 +1336,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	// module whose event names are wrong installs, starts, connects and reacts to nothing, with
 	// every log line saying it is fine (novox/hq 04-ISSUES/127).
 	problems = append(problems, EventProblems(m)...)
+	// And what it may call its state, and whose it may read (state.go, novox/hq ADR 0201).
+	problems = append(problems, StateProblems(m)...)
 	wellFormed := true
 	for _, c := range m.Claims {
 		if !name.MatchString(c.Name) {
@@ -1428,6 +1450,10 @@ func ParseManifest(raw []byte) (Manifest, error) {
 				"%s serves %q to whoever requires it, and does not provide it", m.Module, to))
 		}
 	}
+	// A served value may be derived for the consumer it is served to (novox/hq ADR 0201). Read
+	// here, where the definition is, rather than when somebody first requires it: a rule that
+	// would be refused at the first consumer is wrong from the moment it is written.
+	problems = append(problems, CheckServes(m)...)
 	for to, where := range m.Binds {
 		if !placedOrAbsolute(where) {
 			problems = append(problems, fmt.Sprintf(
@@ -1622,6 +1648,13 @@ func ParseManifest(raw []byte) (Manifest, error) {
 				}
 			}
 		}
+		// **A scheduled step may hold this module's own containers still while it runs**
+		// (novox/hq ADR 0189). What the host judges is the declaration it receives — whether each
+		// id is a container placed on that machine; what belongs here is what only the definition
+		// shows: that the ids are this module's, that they are containers, and that the step is
+		// scheduled. A module naming a neighbour's container would be a module that can stop the
+		// mesh, and the manifest is where that is visible.
+		problems = append(problems, whileStoppedProblems(m, r, hasSchedule(r))...)
 	}
 	for name, own := range m.OwnSecrets {
 		if !placedOrAbsolute(own.Path) {
@@ -1783,6 +1816,12 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	problems = append(problems, m.unknownDirRefs()...)
 	problems = append(problems, m.unknownAccessRefs()...)
 	problems = append(problems, m.jailProblems()...)
+	// What a module adds to the account's environment and to the login shell, and the holder's
+	// placeholders for them (novox/hq ADR 0203, ADR 0204) — here, so the catalogue check refuses
+	// them in the words registration does.
+	problems = append(problems, m.environmentProblems()...)
+	problems = append(problems, m.shellProblems()...)
+	problems = append(problems, m.contributionPlaceholderProblems()...)
 
 	for i, r := range m.Resources {
 		id, _ := r["id"].(string)
@@ -2153,3 +2192,71 @@ func (o OwnSecrets) Paths() map[string]string {
 // InstancesInterchangeable is the one value of a definition's `instances`: the module is the same
 // on every machine, so any instance may answer for the module.
 const InstancesInterchangeable = "interchangeable"
+
+// WhileStopped is the resource key naming the containers a scheduled step holds still while it
+// runs (novox/hq ADR 0189). Carried to the host unchanged, like `schedule`.
+const WhileStopped = "while-stopped"
+
+// hasSchedule is whether a resource declares a cadence, as a string.
+func hasSchedule(r map[string]any) bool {
+	s, _ := r["schedule"].(string)
+	return s != ""
+}
+
+// whileStoppedProblems judges one container's maintenance window against its own definition
+// (novox/hq ADR 0189).
+//
+// Three things the manifest is the only place to see: that the step is scheduled (a one-time
+// offline job says *before* rather than *instead of* — at apply the host already has a window,
+// because the declaration is applied in order and a run-once step gates what follows); that every
+// id it names is **this module's own** container; and that it does not name itself.
+//
+// The host checks the fourth — that the container is actually placed on that machine — because
+// that is a fact about the declaration and not about the definition.
+func whileStoppedProblems(m Manifest, r map[string]any, scheduled bool) []string {
+	raw, present := r[WhileStopped]
+	if !present {
+		return nil
+	}
+	ids, ok := raw.([]any)
+	if !ok {
+		return []string{fmt.Sprintf(
+			"%s declares %s on %v as a %T; it is a list of this module's container ids",
+			m.Module, WhileStopped, r["id"], raw)}
+	}
+	var problems []string
+	if len(ids) > 0 && !scheduled {
+		problems = append(problems, fmt.Sprintf(
+			"%s declares %s on %v, which has no schedule. A maintenance window is for a recurring "+
+				"step: at apply the mesh already has one, because a run-once step gates what is "+
+				"declared after it (novox/hq ADR 0189)", m.Module, WhileStopped, r["id"]))
+	}
+	containers := map[string]bool{}
+	for _, own := range m.Resources {
+		if fmt.Sprint(own["type"]) == "container" {
+			containers[fmt.Sprint(own["id"])] = true
+		}
+	}
+	for _, each := range ids {
+		id, ok := each.(string)
+		if !ok {
+			problems = append(problems, fmt.Sprintf(
+				"%s declares %s on %v naming a %T; each entry is a container's id",
+				m.Module, WhileStopped, r["id"], each))
+			continue
+		}
+		if id == fmt.Sprint(r["id"]) {
+			problems = append(problems, fmt.Sprintf(
+				"%s declares %s on %v naming itself", m.Module, WhileStopped, r["id"]))
+			continue
+		}
+		if !containers[id] {
+			problems = append(problems, fmt.Sprintf(
+				"%s declares %s on %v naming %q, which is not a container this module declares. "+
+					"A step may hold still its own module's containers and nobody else's — one "+
+					"that could quiesce a neighbour could stop the mesh",
+				m.Module, WhileStopped, r["id"], id))
+		}
+	}
+	return problems
+}

internal/catalogue/port_into.go

@@ -31,7 +31,7 @@ import (
 //
 // So a module asks. `${port:8080}` is "the machine-side port you gave me for the 8080 I said I
 // listen on", and the module writes that where it would otherwise have written a literal — in a
-// file's content, or in a value of a container's `env`.
+// file's content, or in a value of a container's or a process's `env`.
 //
 // **The environment is filled by the control plane, exactly as a bound value is.** A port is not
 // secret — the mesh holds it in the clear — so there is nothing for the host to be the only
@@ -64,7 +64,12 @@ func portsUsed(content string) []int {
 }
 
 // portInto replaces a resource's ${port:…} placeholders with what this machine assigned — in a
-// file's content, and in a value of a container's environment.
+// file's content, and in a value of a container's or a process's environment.
+//
+// **A process's environment is a container's** (novox/hq to-be 38 WP4c). A module's code moving out
+// of its container becomes a process on the machine and still has to be told what the container
+// was told; filled for one kind and not the other, the literal reached the process and was read as
+// a port, and the modules that moved first wrote their run-once steps a 0600 env file instead.
 //
 // A port the module did not say it listens on is refused, for the same reason a binding's unknown
 // key is: the module is asking about something it never declared, and the answer would be a guess.
@@ -84,7 +89,7 @@ func portInto(resource map[string]any, module string, listens []Listening, with
 		}
 		resource["content"] = filled
 
-	case "container":
+	case "container", "process":
 		env, ok := resource["env"].(map[string]any)
 		if !ok {
 			return nil
@@ -106,8 +111,8 @@ func portInto(resource map[string]any, module string, listens []Listening, with
 				continue
 			}
 			value, err := portsFilledInto(written,
-				fmt.Sprintf("%s's container %s sets %s to something that",
-					module, resource["name"], key), module, listens, with)
+				fmt.Sprintf("%s's %s %s sets %s to something that",
+					module, resource["type"], resource["name"], key), module, listens, with)
 			if err != nil {
 				return err
 			}

internal/catalogue/process_env_test.go

@@ -0,0 +1,80 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// **A process's environment is composed as a container's is** (novox/hq to-be 38 WP4c).
+//
+// A module's code moving out of its container becomes a process on the machine, and what its
+// container's environment asked for — the port this machine gave the module, the place it put the
+// module's directory — it still has to be told. Filled for a container and not for a process, the
+// literal `${port:8080}` reached the process as its environment and was read as a port; the modules
+// that moved first wrote their run-once steps an env file instead.
+func processModule(env map[string]any) Manifest {
+	return Manifest{
+		Module:  "showcase",
+		Listens: []Listening{{Port: 8080, From: FromMesh}},
+		Resources: []map[string]any{
+			{"id": "data", "type": "directory", "mode": "0700"},
+			{"id": "setup", "type": "process", "name": "showcase-setup", "run-once": true,
+				"run": []any{"/usr/bin/showcase", "setup"}, "env": env},
+		},
+	}
+}
+
+func TestAProcessIsToldItsPortAndItsPlaceInItsEnvironment(t *testing.T) {
+	env := map[string]any{
+		"SHOWCASE_URL":  "http://127.0.0.1:${port:8080}",
+		"SHOWCASE_DATA": "${dir:data}/objects",
+		"SHOWCASE_DB":   "127.0.0.1:${seat:mesh-store:5432}",
+		"GREETING":      "hello",
+	}
+	out, err := Resolution{Node: "anchor", Modules: []Manifest{processModule(env)}}.Declaration(Rendering{
+		Ports: map[string]map[int]int{"showcase": {8080: 21000}},
+		Seats: map[string]map[int]int{"mesh-store": {5432: 6852}},
+	})
+	if err != nil {
+		t.Fatalf("a process asking for its port and its place does not compose: %v", err)
+	}
+	setup := fileNamed(out, "showcase.setup")
+	if setup == nil {
+		t.Fatalf("the process is not in the declaration: %v", out)
+	}
+	got, _ := setup["env"].(map[string]any)
+	for key, want := range map[string]string{
+		"SHOWCASE_URL":  "http://127.0.0.1:21000",
+		"SHOWCASE_DATA": "/var/lib/showcase/data/objects",
+		"SHOWCASE_DB":   "127.0.0.1:6852",
+		"GREETING":      "hello",
+	} {
+		if got[key] != want {
+			t.Errorf("the process is told %s=%v, want %q", key, got[key], want)
+		}
+	}
+	if env["SHOWCASE_URL"] != "http://127.0.0.1:${port:8080}" {
+		t.Fatalf("composing for one machine edited the module's own manifest: %v", env)
+	}
+}
+
+// An unknown reference in a process's environment is refused as a container's is, naming the
+// process and the variable — left alone, it would reach the machine as a literal.
+func TestAProcessAskingAboutAnUndeclaredPortIsRefused(t *testing.T) {
+	env := map[string]any{"SHOWCASE_URL": "http://127.0.0.1:${port:9999}"}
+	_, err := Resolution{Node: "anchor", Modules: []Manifest{processModule(env)}}.Declaration(Rendering{})
+	if err == nil {
+		t.Fatal("a process was told a port its module never said it listens on")
+	}
+	for _, said := range []string{"showcase-setup", "SHOWCASE_URL", "${port:9999}", "8080"} {
+		if !strings.Contains(err.Error(), said) {
+			t.Errorf("the refusal does not say %q: %v", said, err)
+		}
+	}
+
+	env = map[string]any{"SHOWCASE_DATA": "${dir:date}/objects"}
+	if _, err := (Resolution{Node: "anchor", Modules: []Manifest{processModule(env)}}).Declaration(Rendering{}); err == nil ||
+		!strings.Contains(err.Error(), "${dir:date}") {
+		t.Fatalf("a process naming no directory of its module was not refused: %v", err)
+	}
+}

internal/catalogue/published_ports_test.go

@@ -0,0 +1,75 @@
+package catalogue
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+)
+
+// A container publishes only a port its module declares (novox/hq issue 227).
+//
+// **The short form is a question the mesh answers.** `"80"` means *publish what the software
+// calls 80*, and the mesh fills in the machine's half from the port it assigned
+// ([ADR 0038](0038)). It can only assign one for a port the module declared in `listens` — so a
+// container publishing a number that appears nowhere in `listens` gets no assignment, and
+// `publishedOn` falls back to the number as written. It escapes to the machine.
+//
+// That is how the photo module asked for port 80 on the control node, where the reverse proxy
+// holds it: it declared its web endpoint at 4001, published a bare 80, and the container never
+// started. Four other modules publish 80 quite safely — because they declare 80, so the mesh
+// gives them a machine port for it. The difference is the declaration, not the number.
+//
+// A mapping written the long way is a module pinning both halves on purpose and is left alone.
+func TestEveryPublishedPortIsOneItsModuleDeclares(t *testing.T) {
+	root := catalogueRoot(t)
+	entries, err := os.ReadDir(filepath.Join(root, "modules"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var escaped []string
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			continue
+		}
+		raw, err := os.ReadFile(filepath.Join(root, "modules", entry.Name(), "module.json"))
+		if err != nil {
+			continue
+		}
+		m, err := ParseManifest(raw)
+		if err != nil {
+			// Whether every manifest parses is TestEveryCatalogueManifestParses's question.
+			continue
+		}
+		declared := map[int]bool{}
+		for _, l := range m.Listens {
+			declared[l.Port] = true
+		}
+		for _, r := range m.Resources {
+			if fmt.Sprint(r["type"]) != "container" {
+				continue
+			}
+			listed, _ := r["ports"].([]any)
+			for _, p := range listed {
+				written := strings.Split(fmt.Sprint(p), "/")[0]
+				if strings.Contains(written, ":") {
+					continue // pinned by hand, both halves, on purpose
+				}
+				port, err := strconv.Atoi(strings.TrimSpace(written))
+				if err != nil || declared[port] {
+					continue
+				}
+				escaped = append(escaped, fmt.Sprintf(
+					"%s's %v publishes %d, and %s declares no such port — the mesh has nothing "+
+						"to assign, so %d reaches the machine as written",
+					m.Module, r["id"], port, m.Module, port))
+			}
+		}
+	}
+	if len(escaped) > 0 {
+		t.Fatalf("a container may publish only a port its module declares:\n  - %s",
+			strings.Join(escaped, "\n  - "))
+	}
+}

internal/catalogue/seat_into.go

@@ -43,8 +43,8 @@ import (
 var ofSeat = regexp.MustCompile(`\$\{seat:([a-z0-9][a-z0-9-]*):([0-9]+)\}`)
 
 // seatInto replaces a resource's ${seat:…} placeholders with where this machine put each seat's
-// holder — in a file's content, and in a value of a container's or a process's environment. The same two places
-// portInto fills, for the same reason: they are where a process reads a number from.
+// holder — in a file's content, and in a value of a container's or a process's environment. The
+// same places portInto fills, for the same reason: they are where a program reads a number from.
 func seatInto(resource map[string]any, module string, with Rendering) error {
 	switch fmt.Sprint(resource["type"]) {
 	case "file":
@@ -58,8 +58,6 @@ func seatInto(resource map[string]any, module string, with Rendering) error {
 		}
 		resource["content"] = filled
 
-	// A process's environment as a container's (novox/hq issue 213): the controller reads where its
-	// store and broker are from it, whichever way the host runs it.
 	case "container", "process":
 		env, ok := resource["env"].(map[string]any)
 		if !ok {

internal/catalogue/seat_into_test.go

@@ -101,7 +101,7 @@ func TestTheControlPlanesOwnAddressesFollowTheNodesPorts(t *testing.T) {
 	}
 	// The manifest itself names them now; withSeatPorts is a no-op on it, and this holds it so.
 	for _, r := range m.Resources {
-		if r["type"] != "container" {
+		if r["type"] != "process" {
 			continue
 		}
 		env, _ := r["env"].(map[string]any)
@@ -113,8 +113,9 @@ func TestTheControlPlanesOwnAddressesFollowTheNodesPorts(t *testing.T) {
 	}
 	m = withSeatPorts(m)
 	control, err := m.Resolve([]Built{{
-		Name: "server", Kind: ArtifactImage,
-		Reference: ArtifactStoreScheme + "mesh-controller/server@sha256:" + strings.Repeat("c", 64),
+		Name: "controller", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "mesh-controller/controller@sha256:" + strings.Repeat("c", 64),
+		Digest:    "sha256:" + strings.Repeat("c", 64),
 	}})
 	if err != nil {
 		t.Fatal(err)
@@ -135,9 +136,9 @@ func TestTheControlPlanesOwnAddressesFollowTheNodesPorts(t *testing.T) {
 	if err != nil {
 		t.Fatalf("the control plane does not compose: %v", err)
 	}
-	server := fileNamed(out, "mesh-controller.server")
+	server := fileNamed(out, "mesh-controller.controller")
 	if server == nil {
-		t.Fatalf("the control plane's container is not in the declaration: %v", out)
+		t.Fatalf("the control plane's process is not in the declaration: %v", out)
 	}
 	env, _ := server["env"].(map[string]any)
 	for key, want := range map[string]string{
@@ -151,8 +152,8 @@ func TestTheControlPlanesOwnAddressesFollowTheNodesPorts(t *testing.T) {
 			t.Errorf("the control plane is told %s=%v; the node put it on %s", key, env[key], want)
 		}
 	}
-	if got := server["image"]; got != "anchor.internal:5100/mesh-controller/server@sha256:"+strings.Repeat("c", 64) {
-		t.Errorf("the control plane's own image is %v, not routed through the store", got)
+	if got := server["source"]; got != "anchor.internal:5100/mesh-controller/controller@sha256:"+strings.Repeat("c", 64) {
+		t.Errorf("the control plane's own bundle is fetched from %v, not routed through the store", got)
 	}
 
 	// And on a mesh where the foundation is where genesis raised it, nothing is added.
@@ -160,7 +161,7 @@ func TestTheControlPlanesOwnAddressesFollowTheNodesPorts(t *testing.T) {
 	if err != nil {
 		t.Fatal(err)
 	}
-	env, _ = fileNamed(out, "mesh-controller.server")["env"].(map[string]any)
+	env, _ = fileNamed(out, "mesh-controller.controller")["env"].(map[string]any)
 	if env["MESH_STORE_INVENTORY_PORT"] != "" {
 		t.Errorf("with no settings, the control plane is told %v", env)
 	}
@@ -186,7 +187,7 @@ func withSeatPorts(m Manifest) Manifest {
 	out := m
 	out.Resources = nil
 	for _, r := range m.Resources {
-		if r["type"] != "container" {
+		if r["type"] != "container" && r["type"] != "process" {
 			out.Resources = append(out.Resources, r)
 			continue
 		}

internal/catalogue/seats.go

@@ -150,6 +150,17 @@ var defaultSeats = []Seat{
 	// served by the node tools runtime (ADR 0175).
 	{Name: "node-service-manager", Scope: ScopeNode, Decision: "novox/hq ADR 0177",
 		Serves: serviceManagerVerbs()},
+	// The operator account's environment (novox/hq ADR 0203): one module per machine writes it, and
+	// every module contributes to it. No verbs — the seat says who places the environment's files,
+	// and their path is its protocol: a shell sources ~/.config/mesh/environment.sh without knowing
+	// which module wrote it.
+	{Name: EnvironmentSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0203"},
+	// The login shell (novox/hq ADR 0204, replacing the module-declared `login-shell` of ADR 0176):
+	// the mesh's, so a second shell module claims the seat rather than declaring a second one, and
+	// the seat exists whether or not zsh's definition is registered. `execute` is the contract any
+	// node may call; the holder places every module's shell code in its slots.
+	{Name: LoginShellSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0204",
+		Serves: loginShellVerbs()},
 	// Deferred (novox/hq ADR 0121): renaming to mesh-private-network is a scope + server/client
 	// model change, not a rename, so it stays until that is built.
 	{Name: "the-private-network", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
@@ -456,3 +467,17 @@ func serviceManagerVerbs() []Verb {
 			Input: scoped(map[string]string{"unit": unit["unit"], "lines": "how many lines from the end (default 100)"}, []string{"unit"})},
 	}
 }
+
+// loginShellVerbs is the contract every holder of node-login-shell serves (novox/hq ADR 0176, ADR
+// 0204): one command, run the way the operator's own terminal would run it, bounded below the
+// runtime's thirty-second call limit so a hung command answers rather than times the caller out.
+func loginShellVerbs() []Verb {
+	return []Verb{
+		{Name: "execute", Description: "Run one command on this machine as the operator account, in a " +
+			"non-interactive login shell in its home; answers with what it printed and how it exited.",
+			Input: schema(map[string]string{
+				"command":         "the command line, as you would type it",
+				"timeout_seconds": "give up after this long, at most 25 (default 20)",
+			}, []string{"command"})},
+	}
+}

internal/catalogue/seats_declared.go

@@ -25,6 +25,10 @@ import (
 // and nothing to keep in step when a mesh seat is added.
 const meshSeatPrefix = "mesh-"
 
+// retiredLoginShell is the one name outside the prefix a module may not declare: the login shell's,
+// from when a module declared it (novox/hq ADR 0176), before it became the mesh's (ADR 0204).
+const retiredLoginShell = "login-shell"
+
 // A SeatDeclaration is a role a module offers on the bus: what may be sent to it, what it says,
 // and what it answers. A caller declares that it uses the *seat*, never the module, so the
 // implementation can be replaced under it.
@@ -88,6 +92,15 @@ func declaredSeatProblems(m Manifest) []string {
 					"seats (novox/hq ADR 0118)", m.Module, s.Name, meshSeatPrefix+"*"))
 			continue
 		}
+		if s.Name == retiredLoginShell {
+			// The name ADR 0176 gave the login shell when the zsh module declared it. The seat is
+			// the mesh's now, so a module declaring the old name would be a second login shell
+			// beside it, with a protocol of its own (novox/hq ADR 0204).
+			problems = append(problems, fmt.Sprintf(
+				"%s declares a seat named %q; the login shell is the mesh's own seat %s, which a shell "+
+					"module claims and none declares (novox/hq ADR 0204)", m.Module, s.Name, LoginShellSeat))
+			continue
+		}
 		if seen[s.Name] {
 			problems = append(problems, fmt.Sprintf(
 				"%s declares the seat %q twice", m.Module, s.Name))
@@ -215,6 +228,13 @@ func CatalogueProblems(shelf Shelf) []string {
 			}
 		}
 	}
+	// A read of a module's state that module does not keep (novox/hq ADR 0201) — said only where the
+	// owner is on the shelf, as a consumer may be installed before its emitter.
+	var manifests []Manifest
+	for _, module := range shelfOrder(shelf) {
+		manifests = append(manifests, shelf[module])
+	}
+	problems = append(problems, StateReadsNothingDeclares(manifests)...)
 	sort.Strings(problems)
 	return problems
 }

internal/catalogue/seats_test.go

@@ -44,10 +44,11 @@ func TestTheSeatsAreAClosedSetAndEachNamesItsDecision(t *testing.T) {
 			delivered[s.Delivers] = s.Name
 		}
 	}
-	// Seventeen since node-build-agent (novox/hq ADR 0190) — sixteen once the retired
-	// mesh-build-machine row goes, when no registered manifest claims it any more.
-	if len(Seats()) != 17 {
-		t.Errorf("the mesh defines %d seats rather than 17; the set is closed, so a change here is "+
+	// Nineteen since node-environment and node-login-shell (novox/hq ADR 0203, ADR 0204), after
+	// node-build-agent made seventeen (ADR 0190) — eighteen once the retired mesh-build-machine row
+	// goes, when no registered manifest claims it any more.
+	if len(Seats()) != 19 {
+		t.Errorf("the mesh defines %d seats rather than 19; the set is closed, so a change here is "+
 			"a decision (novox/hq ADR 0110): %s", len(Seats()), seatNames())
 	}
 }

internal/catalogue/state.go

@@ -0,0 +1,150 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// What a module may call its state, and whose state it may ask to read (novox/hq ADR 0201).
+//
+// A module names its state **locally** — `servers`, never a bucket or a subject — and another
+// module's as `<module>.<name>`, the way a consumed event names its emitter (design 32 §1). The
+// mesh derives the bucket from the two names, so the module and the local name must each be one
+// token: the bucket joins them with an underscore, which neither may contain, so two modules can
+// never derive one bucket.
+
+// stateName is one local name of a module's state: lower-case, no dot, no underscore.
+var stateName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+
+// The mesh's caps on what a module may ask of a bucket's history.
+const (
+	// StateMostHistory is the most past values a key may keep. The server's own limit.
+	StateMostHistory = 64
+)
+
+// StateDeclaration is one bucket a module owns: its local name, and the options that are the
+// owner's to choose, as a seat chooses how long its backlog survives (design 32 §3).
+type StateDeclaration struct {
+	Name string `json:"name"`
+	// History is how many values a key keeps, the current one included; zero is one.
+	History int `json:"history,omitempty"`
+	// TTLSeconds is how long a value lives once written; zero is until it is replaced or deleted.
+	TTLSeconds int `json:"ttl-seconds,omitempty"`
+}
+
+// UnmarshalJSON reads a bucket as its bare name, or as {name, history, ttl-seconds}.
+func (s *StateDeclaration) UnmarshalJSON(raw []byte) error {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) > 0 && trimmed[0] == '"' {
+		return json.Unmarshal(trimmed, &s.Name)
+	}
+	type plain StateDeclaration
+	var full plain
+	dec := json.NewDecoder(bytes.NewReader(trimmed))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&full); err != nil {
+		return fmt.Errorf("a state is either a name or {name, history, ttl-seconds}: %w", err)
+	}
+	*s = StateDeclaration(full)
+	return nil
+}
+
+// MarshalJSON writes back the short form when there is nothing else to say.
+func (s StateDeclaration) MarshalJSON() ([]byte, error) {
+	if s.History == 0 && s.TTLSeconds == 0 {
+		return json.Marshal(s.Name)
+	}
+	type plain StateDeclaration
+	return json.Marshal(plain(s))
+}
+
+// ReadState splits a read into the owning module and the local name, or says why it is not one.
+func ReadState(read string) (module, local string, err error) {
+	at := strings.LastIndex(read, ".")
+	if at <= 0 || at == len(read)-1 {
+		return "", "", fmt.Errorf("%q does not name a module and its state: a read is <module>.<name>", read)
+	}
+	module, local = read[:at], read[at+1:]
+	if !stateName.MatchString(module) {
+		return "", "", fmt.Errorf("%q cannot own state: a module whose state is read is one plain name", module)
+	}
+	if !stateName.MatchString(local) {
+		return "", "", fmt.Errorf("%q is not a state name: lower-case letters, digits and hyphens", local)
+	}
+	return module, local, nil
+}
+
+// StateProblems is what is wrong with a manifest's state and reads.
+//
+// Refused at registration, because a bucket name the bus cannot hold is a module that installs,
+// starts, and is refused on its first write with a reason about a bucket nobody named.
+func StateProblems(m Manifest) []string {
+	var problems []string
+	if len(m.State) > 0 && !stateName.MatchString(m.Module) {
+		problems = append(problems, fmt.Sprintf(
+			"%s keeps state, and a module's name is part of its buckets' names, which take one plain "+
+				"name — no dot (novox/hq ADR 0201)", m.Module))
+	}
+	seen := map[string]bool{}
+	for _, s := range m.State {
+		switch {
+		case !stateName.MatchString(s.Name):
+			problems = append(problems, fmt.Sprintf(
+				"%s keeps state %q: a state is named locally — lower-case letters, digits and hyphens, "+
+					"no dot and no underscore; the mesh derives the bucket (novox/hq ADR 0201)", m.Module, s.Name))
+		case seen[s.Name]:
+			problems = append(problems, fmt.Sprintf("%s keeps state %q twice", m.Module, s.Name))
+		}
+		seen[s.Name] = true
+		if s.History < 0 || s.History > StateMostHistory {
+			problems = append(problems, fmt.Sprintf(
+				"%s keeps %d values of %q; a key keeps between 1 and %d", m.Module, s.History, s.Name, StateMostHistory))
+		}
+		if s.TTLSeconds < 0 {
+			problems = append(problems, fmt.Sprintf("%s gives %q a negative lifetime", m.Module, s.Name))
+		}
+	}
+	for _, r := range m.Reads {
+		module, _, err := ReadState(r)
+		if err != nil {
+			problems = append(problems, fmt.Sprintf("%s reads %v", m.Module, err))
+			continue
+		}
+		if module == m.Module {
+			problems = append(problems, fmt.Sprintf(
+				"%s reads %q, which is its own state: a module reads and writes what it keeps already", m.Module, r))
+		}
+	}
+	return problems
+}
+
+// StateReadsNothingDeclares is every read across a catalogue whose owner is present and declares no
+// such state. An absent owner says nothing — a module may be installed long before the one whose
+// state it reads, as a consumer may before its emitter (design 32 §1).
+func StateReadsNothingDeclares(manifests []Manifest) []string {
+	declared := map[string]map[string]bool{}
+	for _, m := range manifests {
+		own := map[string]bool{}
+		for _, s := range m.State {
+			own[s.Name] = true
+		}
+		declared[m.Module] = own
+	}
+	var problems []string
+	for _, m := range manifests {
+		for _, r := range m.Reads {
+			module, local, err := ReadState(r)
+			if err != nil {
+				continue
+			}
+			if own, present := declared[module]; present && !own[local] {
+				problems = append(problems, fmt.Sprintf(
+					"%s reads %q, and %s keeps no state called %q", m.Module, r, module, local))
+			}
+		}
+	}
+	return problems
+}

internal/catalogue/state_test.go

@@ -0,0 +1,94 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A module declares the state it keeps and the state it reads (novox/hq ADR 0201), a bucket by its
+// bare name or with the owner's options.
+func TestAManifestMaySayWhatStateItKeepsAndReads(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"claude-code","version":"1",` +
+		`"state":["servers",{"name":"seen","history":5,"ttl-seconds":3600}],` +
+		`"reads":["licence-manager.bindings"]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(m.State) != 2 || m.State[0].Name != "servers" || m.State[1].History != 5 || m.State[1].TTLSeconds != 3600 {
+		t.Fatalf("state not read: %+v", m.State)
+	}
+	if len(m.Reads) != 1 || m.Reads[0] != "licence-manager.bindings" {
+		t.Fatalf("reads not read: %v", m.Reads)
+	}
+	// Written back as it came in: the short form where nothing else is said.
+	out, _ := json.Marshal(m.State)
+	if string(out) != `["servers",{"name":"seen","history":5,"ttl-seconds":3600}]` {
+		t.Fatalf("written back as %s", out)
+	}
+}
+
+// A name the bus could not hold, or that would let two modules derive one bucket, is refused at
+// registration in the manifest's words.
+func TestAStateNameIsLocalAndOneToken(t *testing.T) {
+	for _, c := range []struct{ manifest, says string }{
+		{`{"module":"a","version":"1","state":["mesh.servers"]}`, `keeps state "mesh.servers": a state is named locally`},
+		{`{"module":"a","version":"1","state":["my_servers"]}`, `keeps state "my_servers"`},
+		{`{"module":"a","version":"1","state":["s","s"]}`, `keeps state "s" twice`},
+		{`{"module":"a","version":"1","state":[{"name":"s","history":65}]}`, `a key keeps between 1 and 64`},
+		{`{"module":"a.b","version":"1","state":["s"]}`, `no dot`},
+		{`{"module":"a","version":"1","reads":["bindings"]}`, `a read is <module>.<name>`},
+		{`{"module":"a","version":"1","reads":["a.s"]}`, `which is its own state`},
+		{`{"module":"a","version":"1","state":[{"name":"s","shared":true}]}`, `{name, history, ttl-seconds}`},
+	} {
+		_, err := ParseManifest([]byte(c.manifest))
+		if err == nil {
+			t.Errorf("%s was accepted", c.manifest)
+			continue
+		}
+		if !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s refused for the wrong reason: %v", c.manifest, err)
+		}
+	}
+}
+
+// A read whose owner is present must name a state that owner keeps; an absent owner says nothing,
+// because a module may be installed before the one whose state it reads.
+func TestAReadNamesStateItsOwnerKeeps(t *testing.T) {
+	owner := Manifest{Module: "licence-manager", State: []StateDeclaration{{Name: "bindings"}}}
+	good := Manifest{Module: "claude-code", Reads: []string{"licence-manager.bindings", "absent.anything"}}
+	bad := Manifest{Module: "other", Reads: []string{"licence-manager.tokens"}}
+	if p := StateReadsNothingDeclares([]Manifest{owner, good}); len(p) != 0 {
+		t.Fatalf("a read of declared state was refused: %v", p)
+	}
+	p := StateReadsNothingDeclares([]Manifest{owner, bad})
+	if len(p) != 1 || !strings.Contains(p[0], `licence-manager keeps no state called "tokens"`) {
+		t.Fatalf("a read of state nobody keeps was not named: %v", p)
+	}
+}
+
+// **Across the whole catalogue**: every state name is local, and every read whose owner is present
+// names state that owner keeps.
+func TestEveryManifestsStateIsLocalAndEveryReadIsKept(t *testing.T) {
+	manifests := theCatalogue(t)
+	var problems []string
+	for _, m := range manifests {
+		problems = append(problems, StateProblems(m)...)
+	}
+	problems = append(problems, StateReadsNothingDeclares(manifests)...)
+	if len(problems) > 0 {
+		t.Fatalf("the catalogue's state is not what ADR 0201 says:\n  %s", strings.Join(problems, "\n  "))
+	}
+}
+
+// `module check` says it too: the cross-catalogue pass names a read nothing on the shelf keeps.
+func TestTheCataloguePassNamesAReadItsOwnerDoesNotKeep(t *testing.T) {
+	shelf := Shelf{
+		"licence-manager": {Module: "licence-manager", State: []StateDeclaration{{Name: "bindings"}}},
+		"claude-code":     {Module: "claude-code", Reads: []string{"licence-manager.tokens"}},
+	}
+	problems := CatalogueProblems(shelf)
+	if len(problems) != 1 || !strings.Contains(problems[0], `keeps no state called "tokens"`) {
+		t.Fatalf("the catalogue pass said %v", problems)
+	}
+}

internal/catalogue/while_stopped_test.go

@@ -0,0 +1,145 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// A scheduled step may hold its module's own containers still while it runs (novox/hq ADR 0189).
+//
+// The host judges what it receives — whether each id is a container on that machine. What the
+// definition is the only place to see is judged here, near whoever wrote it.
+
+func aStoreManifest(step map[string]any) []byte {
+	m := map[string]any{
+		"module": "distribution", "version": "1",
+		"resources": []any{
+			map[string]any{"id": "store", "type": "container", "name": "mesh-registry",
+				"image": "registry@sha256:" + strings.Repeat("a", 64)},
+			step,
+		},
+	}
+	raw, _ := json.Marshal(m)
+	return raw
+}
+
+func TestAMaintenanceWindowOnItsOwnModulesContainerIsAccepted(t *testing.T) {
+	raw := aStoreManifest(map[string]any{
+		"id": "collect", "type": "container", "name": "mesh-registry-collect",
+		"image":    "registry@sha256:" + strings.Repeat("a", 64),
+		"schedule": "30 3 * * *", "while-stopped": []any{"store"},
+	})
+	if _, err := ParseManifest(raw); err != nil {
+		t.Fatalf("a step holding its own module's container still was refused: %v", err)
+	}
+}
+
+func TestAMaintenanceWindowIsRefusedWhereTheDefinitionShowsItCannotMean(t *testing.T) {
+	for _, c := range []struct {
+		name string
+		step map[string]any
+		says string
+	}{
+		{
+			"on a step with no schedule",
+			map[string]any{"id": "collect", "type": "container", "name": "c",
+				"image":         "registry@sha256:" + strings.Repeat("a", 64),
+				"while-stopped": []any{"store"}},
+			"gates what is declared after it",
+		},
+		{
+			"on a run-once step, which already has order",
+			map[string]any{"id": "collect", "type": "container", "name": "c",
+				"image":    "registry@sha256:" + strings.Repeat("a", 64),
+				"run-once": true, "while-stopped": []any{"store"}},
+			"A maintenance window is for a recurring step",
+		},
+		{
+			"naming a container this module does not declare",
+			map[string]any{"id": "collect", "type": "container", "name": "c",
+				"image":    "registry@sha256:" + strings.Repeat("a", 64),
+				"schedule": "30 3 * * *", "while-stopped": []any{"the-broker"}},
+			"could quiesce a neighbour could stop the mesh",
+		},
+		{
+			"naming itself",
+			map[string]any{"id": "collect", "type": "container", "name": "c",
+				"image":    "registry@sha256:" + strings.Repeat("a", 64),
+				"schedule": "30 3 * * *", "while-stopped": []any{"collect"}},
+			"naming itself",
+		},
+		{
+			"written as something that is not a list",
+			map[string]any{"id": "collect", "type": "container", "name": "c",
+				"image":    "registry@sha256:" + strings.Repeat("a", 64),
+				"schedule": "30 3 * * *", "while-stopped": "store"},
+			"a list of this module's container ids",
+		},
+	} {
+		_, err := ParseManifest(aStoreManifest(c.step))
+		if err == nil {
+			t.Errorf("%s was accepted", c.name)
+			continue
+		}
+		if !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: the refusal does not say %q:\n%v", c.name, c.says, err)
+		}
+	}
+}
+
+// A composed declaration names the step's held containers the way the machine knows them.
+//
+// **The gap that let a bug through to the control node.** The manifest says `while-stopped:
+// ["store"]`, because a module names its own resources locally; the declaration a machine
+// receives calls that container `distribution.store`, because every resource is composed under
+// its module. `restart-on` and `reload-on` are rewritten for exactly this reason, and
+// `while-stopped` was not — so the host found no container by that id and refused the whole
+// declaration, every push, until it was fixed.
+//
+// It passed every test on both sides: the controller's tests read manifests, the host's read
+// hand-written declarations with bare ids. Only composing one and judging the result catches it.
+func TestAComposedWindowNamesTheContainerAsTheMachineKnowsIt(t *testing.T) {
+	store := Manifest{
+		Module: "distribution", Version: "1",
+		Provides: FromAnywhere("artifact-store"),
+		Listens:  []Listening{{Port: 5000, Protocol: "tcp", From: FromMesh}},
+		Serves:   map[string]map[string]any{"artifact-store": {"port": 5000}},
+		Resources: []map[string]any{
+			{"id": "store", "type": "container", "name": "mesh-registry",
+				"image": "registry@sha256:" + strings.Repeat("a", 64), "ports": []any{"5000"}},
+			{"id": "collect", "type": "container", "name": "mesh-registry-collect",
+				"image":    "registry@sha256:" + strings.Repeat("a", 64),
+				"schedule": "30 3 * * *", WhileStopped: []any{"store"}},
+		},
+	}
+	r, err := Resolve(shelf(store), []string{"distribution"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	collect := fileNamed(out, "distribution.collect")
+	if collect == nil {
+		for _, res := range out {
+			if res["id"] == "distribution.collect" {
+				collect = res
+			}
+		}
+	}
+	if collect == nil {
+		t.Fatalf("the step was not composed at all: %v", out)
+	}
+	held, _ := collect[WhileStopped].([]any)
+	if len(held) != 1 {
+		t.Fatalf("the composed step holds %v still; want one container", collect[WhileStopped])
+	}
+	if got := fmt.Sprint(held[0]); got != "distribution.store" {
+		t.Fatalf("the composed step says it holds %q still, and the machine's container is "+
+			"called %q — the host refuses a declaration naming a container it does not have, "+
+			"whole, so the machine would take nothing at all", got, "distribution.store")
+	}
+}

internal/inventory/busrecords.go

@@ -132,6 +132,9 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
 		Serves: m.Tools,
 		// And what it calls (novox/hq ADR 0152) — the console's `*`, nothing else's.
 		Invokes: m.Invokes,
+		// And the state it keeps and reads (novox/hq ADR 0201).
+		State: bucketsOf(m),
+		Reads: m.Reads,
 	}
 	for _, c := range m.Claims {
 		// Every seat with a protocol, the mesh's own included. One that says only who does a job is
@@ -148,6 +151,30 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
 	return d
 }
 
+// bucketsOf is the state a module keeps, as the bus holds it.
+func bucketsOf(m catalogue.Manifest) []broker.Bucket {
+	var out []broker.Bucket
+	for _, s := range m.State {
+		out = append(out, broker.Bucket{Module: m.Module, Name: s.Name, History: s.History, TTLSeconds: s.TTLSeconds})
+	}
+	return out
+}
+
+// DeclaredBuckets is every bucket the catalogue declares, registered modules assigned or not: a
+// bucket exists from registration, like a seat's stream, so a module reading it may watch before its
+// owner runs anywhere (novox/hq ADR 0201).
+func (i *Inventory) DeclaredBuckets(ctx context.Context) ([]broker.Bucket, error) {
+	declared, err := i.Catalogue(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("cannot read the catalogue: %w", err)
+	}
+	var out []broker.Bucket
+	for _, m := range declared {
+		out = append(out, bucketsOf(m)...)
+	}
+	return out, nil
+}
+
 func asSeat(s catalogue.SeatDeclaration) broker.Seat {
 	return broker.Seat{Name: s.Name, Scope: s.Scope, Accepts: s.Accepts, Emits: s.Emits,
 		Serves: catalogue.VerbNames(s.Serves)}

internal/inventory/catalogue.go

@@ -78,11 +78,12 @@ func (i *Inventory) RegisterModule(ctx context.Context, m catalogue.Manifest, fr
 	// (novox/hq ADR 0175, to-be 38 WP2.4): a module serving its tools from a container built on the
 	// runtime's image. Refused at registration, by name, for a module that is new to the catalogue
 	// or that was registered in another shape — the mechanism that keeps the old pattern from
-	// returning by habit. **Not refused for a module already registered in that shape**: the
-	// catalogue holds some thirty of them the day the runtime arrives, each moves to a bundle in
-	// its own change (to-be 38 WP4 onward), and a gate that refused every rebuild of every unmoved
-	// module in the meantime would stop the whole pipeline to make a point the record already makes.
-	// Before the runtime exists the pattern is accepted as it always was.
+	// returning by habit. Before the runtime exists the pattern is accepted as it always was.
+	//
+	// *Since 2026-10-04 (to-be 38 WP4b's last step):* refused for **every** module. While some
+	// thirty modules still stood in that shape, one already registered so was rebuilt without
+	// complaint, so the pipeline kept running while each moved; every module has moved since, and
+	// the exception would only let one move back.
 	if m.Module != catalogue.RuntimeModule {
 		if why := catalogue.ToolContainerOnTheRuntime(m, from.Against); why != "" {
 			runtime, err := i.hasModule(ctx, catalogue.RuntimeModule)
@@ -90,13 +91,7 @@ func (i *Inventory) RegisterModule(ctx context.Context, m catalogue.Manifest, fr
 				return err
 			}
 			if runtime {
-				already, err := i.registeredInThatShape(ctx, m.Module)
-				if err != nil {
-					return err
-				}
-				if !already {
-					return fmt.Errorf("%s is not registered: %s", m.Module, why)
-				}
+				return fmt.Errorf("%s is not registered: %s", m.Module, why)
 			}
 		}
 	}
@@ -152,26 +147,6 @@ func (i *Inventory) RegisterModule(ctx context.Context, m catalogue.Manifest, fr
 	return nil
 }
 
-// registeredInThatShape is whether the catalogue already holds this module as a tools container on
-// the runtime's image — judged from the manifest it holds and what that module's newest build stood
-// on, the same two things the gate judges a new registration by. False for a module the catalogue
-// does not hold.
-func (i *Inventory) registeredInThatShape(ctx context.Context, name string) (bool, error) {
-	held, err := i.Catalogue(ctx)
-	if err != nil {
-		return false, err
-	}
-	stored, has := held[name]
-	if !has {
-		return false, nil
-	}
-	against, err := i.BuiltAgainst(ctx)
-	if err != nil {
-		return false, err
-	}
-	return catalogue.ToolContainerOnTheRuntime(stored, against[name]) != "", nil
-}
-
 // hasModule is whether the catalogue holds a module of that name.
 func (i *Inventory) hasModule(ctx context.Context, name string) (bool, error) {
 	var one int

internal/inventory/catalogue_test.go

@@ -688,9 +688,9 @@ func TestRegisteringWithoutProvenanceKeepsTheSeat(t *testing.T) {
 
 // Once the node's tool runtime is in the catalogue, a module serving its tools from a container
 // built on the runtime's image is refused at registration, naming the record (novox/hq ADR 0175,
-// to-be 38 WP2.4) — for a module new to the catalogue or one that had moved away from it; a module
-// already standing in that shape is rebuilt as before, so the catalogue's pipeline keeps running
-// while each moves (WP3's amendment). Before the runtime, it is accepted as it always was — so a
+// to-be 38 WP2.4) — for every module, since every module has moved (WP4b's last step; WP3's
+// amendment let one already standing in that shape be rebuilt while each moved). Before the
+// runtime, it is accepted as it always was — so a
 // mesh converts in the order the design says and nothing is refused before there is anything to
 // move to.
 func TestAToolContainerIsRefusedOnceTheRuntimeIsRegistered(t *testing.T) {
@@ -715,11 +715,11 @@ func TestAToolContainerIsRefusedOnceTheRuntimeIsRegistered(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	// **A module already registered in that shape is rebuilt without complaint** (to-be 38 WP2.4 as
-	// amended by WP3): some thirty of them stand the day the runtime arrives, and each moves in its
-	// own change. The gate is against the pattern spreading, not against the pipeline running.
-	if err := inv.RegisterModule(ctx, filter, Source{Repository: "/r", Against: stoodOn}); err != nil {
-		t.Fatalf("a rebuild of a module that already had the pattern was refused: %v", err)
+	// **A module already registered in that shape is refused too** (WP4b's last step): every module
+	// has moved, and a rebuild in the old shape is one moving back.
+	if err := inv.RegisterModule(ctx, filter, Source{Repository: "/r", Against: stoodOn}); err == nil ||
+		!strings.Contains(err.Error(), "ADR 0175") {
+		t.Fatalf("a rebuild of a module in the old pattern was registered beside the runtime: %v", err)
 	}
 	// A module new to the catalogue in that shape is refused, naming the record.
 	newcomer := filter

internal/inventory/collection.go

@@ -0,0 +1,264 @@
+package inventory
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// What the artifact store keeps, and what it may let go (novox/hq ADR 0189, issue 108).
+//
+// The store has never collected anything: every build pushes another layer set and nothing has
+// ever removed one. The registry's own answer — collect what no tag names — is wrong here, because
+// the mesh pushes each artifact under one moving tag and pins machines by digest, so every build
+// but the newest is untagged and some machine may still be running it.
+//
+// **So the mesh decides, from its own records, and it never has to look in the store to do it.**
+// It has never put anything there it did not record, which means every digest it could remove is
+// already in a build row. A digest the mesh did not record making is therefore never named here —
+// not as a safety margin but as the rule restated, and it is what keeps the sweep away from the
+// images genesis pushed before any record existed (04-ISSUES/102, F4).
+
+// KeptBuilds is how many successful builds of each module keep their artifacts, counting the
+// newest. The newest is what the mesh hands a machine now; the four behind it are how far back a
+// release that turns out wrong can be taken.
+const KeptBuilds = 5
+
+// ToCollect is every artifact the mesh made, no longer keeps, and has not already collected.
+//
+// Three reasons an artifact stays, and nothing else is a reason:
+//
+//   - **a definition names it** — the reference appears in a module's recorded manifest, which is
+//     what the mesh would hand a machine now. No age limit: this is the floor;
+//   - **the mesh can still go back to it** — it is an artifact of one of the KeptBuilds most
+//     recent successful builds of its module;
+//   - it was already collected, in which case there is nothing left to do.
+//
+// Returned in a stated order so two runs over the same records ask for the same things in the
+// same sequence, which is what makes a failed sweep safe to simply run again.
+func (i *Inventory) ToCollect(ctx context.Context) ([]string, error) {
+	keep, err := i.keptReferences(ctx)
+	if err != nil {
+		return nil, err
+	}
+	rows, err := i.store.Pool().Query(ctx,
+		// Every artifact of every successful build, oldest first, minus what has already been
+		// collected. A failed build published nothing, so it names nothing to remove.
+		`select b.made
+		   from build b
+		  where b.failed = '' and b.module is not null and b.module <> ''
+		  order by b.at asc, b.id asc`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	collected, err := i.alreadyCollected(ctx)
+	if err != nil {
+		return nil, err
+	}
+	seen := map[string]bool{}
+	var out []string
+	for rows.Next() {
+		var raw []byte
+		if err := rows.Scan(&raw); err != nil {
+			return nil, err
+		}
+		var made []Artifact
+		if err := json.Unmarshal(raw, &made); err != nil {
+			// One unreadable record must not stop the rest being collected — and an artifact this
+			// row named is simply not offered, which errs toward keeping.
+			continue
+		}
+		for _, a := range made {
+			reference := asRecorded(a.Reference)
+			if reference == "" || keep[reference] || collected[reference] || seen[reference] {
+				continue
+			}
+			seen[reference] = true
+			out = append(out, reference)
+		}
+	}
+	return out, rows.Err()
+}
+
+// keptReferences is every artifact reference the mesh still keeps, for either of the two reasons.
+func (i *Inventory) keptReferences(ctx context.Context) (map[string]bool, error) {
+	keep := map[string]bool{}
+
+	// **Whatever a definition the mesh holds names.** Read as text rather than by walking the
+	// resource shapes: a reference may be a container's image, a bundle's source, or a field some
+	// later kind of resource grows, and what matters is only whether the mesh could hand this
+	// string to a machine. A manifest that mentions it is a manifest that might.
+	manifests, err := i.store.Pool().Query(ctx, `select manifest::text from module where manifest is not null`)
+	if err != nil {
+		return nil, err
+	}
+	defer manifests.Close()
+	var named []string
+	for manifests.Next() {
+		var text string
+		if err := manifests.Scan(&text); err != nil {
+			return nil, err
+		}
+		named = append(named, text)
+	}
+	if err := manifests.Err(); err != nil {
+		return nil, err
+	}
+
+	// The KeptBuilds most recent successful builds of each module, whole.
+	recent, err := i.store.Pool().Query(ctx,
+		`select made from (
+		    select made, row_number() over (partition by module order by at desc, id desc) as back
+		      from build
+		     where failed = '' and module is not null and module <> ''
+		 ) ranked where back <= $1`, KeptBuilds)
+	if err != nil {
+		return nil, err
+	}
+	defer recent.Close()
+	for recent.Next() {
+		var raw []byte
+		if err := recent.Scan(&raw); err != nil {
+			return nil, err
+		}
+		var made []Artifact
+		if err := json.Unmarshal(raw, &made); err != nil {
+			continue
+		}
+		for _, a := range made {
+			if reference := asRecorded(a.Reference); reference != "" {
+				keep[reference] = true
+			}
+		}
+	}
+	if err := recent.Err(); err != nil {
+		return nil, err
+	}
+
+	// And anything a manifest mentions. Done after the recent set so the scan runs over the
+	// candidates rather than over every reference ever recorded: a manifest holds a reference
+	// composed with the store's address or kept bare, so the search is for the digest within it.
+	if len(named) > 0 {
+		all, err := i.everyReferenceMade(ctx)
+		if err != nil {
+			return nil, err
+		}
+		for _, reference := range all {
+			if keep[reference] {
+				continue
+			}
+			digest := digestIn(reference)
+			if digest == "" {
+				// Not something the store holds by digest; nothing here can speak for it, so it
+				// is kept rather than guessed about.
+				keep[reference] = true
+				continue
+			}
+			for _, text := range named {
+				if strings.Contains(text, digest) {
+					keep[reference] = true
+					break
+				}
+			}
+		}
+	}
+	return keep, nil
+}
+
+// everyReferenceMade is every artifact reference any successful build recorded.
+func (i *Inventory) everyReferenceMade(ctx context.Context) ([]string, error) {
+	rows, err := i.store.Pool().Query(ctx,
+		`select made from build where failed = '' and module is not null and module <> ''`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	seen := map[string]bool{}
+	var out []string
+	for rows.Next() {
+		var raw []byte
+		if err := rows.Scan(&raw); err != nil {
+			return nil, err
+		}
+		var made []Artifact
+		if err := json.Unmarshal(raw, &made); err != nil {
+			continue
+		}
+		for _, a := range made {
+			reference := asRecorded(a.Reference)
+			if reference == "" || seen[reference] {
+				continue
+			}
+			seen[reference] = true
+			out = append(out, reference)
+		}
+	}
+	return out, rows.Err()
+}
+
+// asRecorded is an artifact reference in the one vocabulary the sweep speaks (novox/hq issue 226).
+//
+// **Every reference here came from a build record, so every one of them is the mesh's own.** That
+// is what makes it safe to normalise: references kept before the store's address stopped being
+// written are `<host>:<port>/<path>@sha256:…` (04-ISSUES/102), and `Recorded` reads those as the
+// `artifact-store://` references the rest of the mesh uses. Done here rather than when the store
+// is asked, because `Recorded` cannot tell one registry host from another — only the provenance
+// can, and the provenance is here.
+//
+// The oldest artifacts are exactly the ones recorded the old way, and exactly the ones a
+// sweep reaches first. Untranslated, the first of them ended every sweep.
+func asRecorded(reference string) string {
+	if reference == "" {
+		return ""
+	}
+	return catalogue.Recorded(reference)
+}
+
+// digestIn is the `sha256:<hex>` a reference names, empty when it names none.
+func digestIn(reference string) string {
+	for _, marker := range []string{"@sha256:", "/sha256:"} {
+		if _, after, ok := strings.Cut(reference, marker); ok {
+			return "sha256:" + after
+		}
+	}
+	return ""
+}
+
+// alreadyCollected is what the store has already been asked to let go.
+func (i *Inventory) alreadyCollected(ctx context.Context) (map[string]bool, error) {
+	rows, err := i.store.Pool().Query(ctx, `select reference from artifact_collected`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	out := map[string]bool{}
+	for rows.Next() {
+		var reference string
+		if err := rows.Scan(&reference); err != nil {
+			return nil, err
+		}
+		out[reference] = true
+	}
+	return out, rows.Err()
+}
+
+// MarkCollected records that the store no longer holds these.
+//
+// **A store that answered "not found" is recorded too.** The outcome wanted is that the artifact
+// is gone, and it is; retrying it every sweep for ever is the failure this table exists to
+// prevent. Only a store that could not be reached, or refused, leaves a reference unmarked — and
+// then the next sweep asks again, which is what should happen.
+func (i *Inventory) MarkCollected(ctx context.Context, references []string) error {
+	for _, reference := range references {
+		if _, err := i.store.Pool().Exec(ctx,
+			`insert into artifact_collected (reference) values ($1) on conflict (reference) do nothing`,
+			reference); err != nil {
+			return err
+		}
+	}
+	return nil
+}

internal/inventory/collection_test.go

@@ -0,0 +1,192 @@
+package inventory
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// What the store keeps, and what it may let go (novox/hq ADR 0189, issue 108).
+//
+// The store has collected nothing since it was raised, and the registry's own answer — collect
+// what no tag names — would delete images machines are running, because the mesh pushes under one
+// moving tag and pins by digest. So the rule is the mesh's, read from its own records, and these
+// are the three reasons an artifact stays and the one reason it goes.
+
+// ref is an artifact reference as the mesh records one.
+func ref(module, artifact string, n int) string {
+	return fmt.Sprintf("%s%s/%s@sha256:%064x", catalogue.ArtifactStoreScheme, module, artifact, n)
+}
+
+// built records one successful build of a module publishing one image.
+func built(t *testing.T, inv *Inventory, id, module string, n int) string {
+	t.Helper()
+	reference := ref(module, "app", n)
+	b := aBuild(id, module, "")
+	b.Made = []Artifact{{Name: "app", Kind: "image", Reference: reference}}
+	if err := inv.RecordBuild(context.Background(), b); err != nil {
+		t.Fatal(err)
+	}
+	return reference
+}
+
+func TestTheStoreKeepsTheRecentBuildsAndLetsGoOfTheRest(t *testing.T) {
+	inv := fresh(t)
+	ctx := context.Background()
+
+	// Eight builds of one module, oldest first. Five are kept — the newest, and the four a
+	// release that turns out wrong can be taken back to.
+	var made []string
+	for i := 1; i <= 8; i++ {
+		made = append(made, built(t, inv, fmt.Sprintf("b%02d", i), "web", i))
+	}
+
+	go_, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := made[:3] // the three oldest
+	if len(go_) != len(want) {
+		t.Fatalf("offered %v to collect; want the %d oldest of %d", go_, len(want), len(made))
+	}
+	for i := range want {
+		if go_[i] != want[i] {
+			t.Fatalf("offered %v; want %v — and in that order, so a failed sweep is safe to run again",
+				go_, want)
+		}
+	}
+}
+
+func TestADefinitionNamingAnArtifactKeepsItHoweverOldItIs(t *testing.T) {
+	// The floor: no age limit. A module recorded at an older commit still names what the mesh
+	// would hand a machine now, and that is what must not be collected out from under it.
+	inv := fresh(t)
+	ctx := context.Background()
+
+	var made []string
+	for i := 1; i <= 8; i++ {
+		made = append(made, built(t, inv, fmt.Sprintf("b%02d", i), "web", i))
+	}
+	oldest := made[0]
+
+	// A definition the mesh holds, whose container runs that oldest image.
+	m := catalogue.Manifest{Module: "web", Version: "1", Resources: []map[string]any{{
+		"id": "app", "type": "container", "name": "web", "image": oldest,
+	}}}
+	if err := inv.RegisterModule(ctx, m, Source{Repository: "https://forge.invalid/web.git"}); err != nil {
+		t.Fatal(err)
+	}
+
+	go_, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, reference := range go_ {
+		if reference == oldest {
+			t.Fatalf("the mesh offered to collect %s, which a definition it holds names", oldest)
+		}
+	}
+	if len(go_) != 2 {
+		t.Fatalf("offered %v; want the two oldest that nothing names", go_)
+	}
+}
+
+func TestWhatHasBeenCollectedIsNotOfferedAgain(t *testing.T) {
+	// Without this the sweep reissues a delete for every artifact it has ever collected, every
+	// time it runs, for ever — a number of requests that grows with the mesh's whole history.
+	inv := fresh(t)
+	ctx := context.Background()
+	for i := 1; i <= 7; i++ {
+		built(t, inv, fmt.Sprintf("b%02d", i), "web", i)
+	}
+	first, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(first) != 2 {
+		t.Fatalf("offered %v, want two", first)
+	}
+	if err := inv.MarkCollected(ctx, first); err != nil {
+		t.Fatal(err)
+	}
+	again, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(again) != 0 {
+		t.Fatalf("offered %v again after collecting it", again)
+	}
+}
+
+func TestAFailedBuildNamesNothingToCollectAndEachModuleIsCountedOnItsOwn(t *testing.T) {
+	inv := fresh(t)
+	ctx := context.Background()
+
+	// A failed build published nothing, so it is neither kept nor collected — and it must not
+	// count against the module's five.
+	for i := 1; i <= 6; i++ {
+		built(t, inv, fmt.Sprintf("w%02d", i), "web", i)
+	}
+	if err := inv.RecordBuild(ctx, aBuild("w99", "web", "the recipe would not build")); err != nil {
+		t.Fatal(err)
+	}
+	// And a second module with three builds keeps all three: five each, not five between them.
+	for i := 1; i <= 3; i++ {
+		built(t, inv, fmt.Sprintf("d%02d", i), "db", 100+i)
+	}
+
+	go_, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(go_) != 1 || go_[0] != ref("web", "app", 1) {
+		t.Fatalf("offered %v; want only web's oldest — db's three are all within its five", go_)
+	}
+}
+
+// An artifact recorded with the store's old address is offered for collection, in the vocabulary
+// the rest of the mesh speaks (novox/hq issue 226).
+//
+// Before references were kept without an address the mesh recorded
+// `<host>:<port>/<path>@sha256:…` (04-ISSUES/102). Those are the oldest artifacts, which makes
+// them exactly the ones an oldest-first sweep reaches first — and the first live run met one,
+// read "I will not address this" as "the store refuses everything", and collected none of 1681.
+func TestAnArtifactRecordedWithAnAddressIsOfferedAsTheMeshRecordsOne(t *testing.T) {
+	inv := fresh(t)
+	ctx := context.Background()
+
+	// The oldest build published the old way; five newer ones fill the module's five.
+	old := aBuild("a00", "tools", "")
+	old.Made = []Artifact{{Name: "build", Kind: "image",
+		Reference: "127.0.0.1:5100/tools/build@sha256:" + fmt.Sprintf("%064x", 1)}}
+	if err := inv.RecordBuild(ctx, old); err != nil {
+		t.Fatal(err)
+	}
+	for i := 2; i <= 6; i++ {
+		built(t, inv, fmt.Sprintf("a%02d", i), "tools", i)
+	}
+
+	go_, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := ref("tools", "build", 1)
+	if len(go_) != 1 || go_[0] != want {
+		t.Fatalf("offered %v; want %q — the address is a route to the artifact, not part of its "+
+			"name, and the sweep speaks the name", go_, want)
+	}
+	// And marking it collected uses that same name, so the next sweep does not offer it again
+	// under a spelling it has not seen.
+	if err := inv.MarkCollected(ctx, go_); err != nil {
+		t.Fatal(err)
+	}
+	again, err := inv.ToCollect(ctx)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(again) != 0 {
+		t.Fatalf("offered %v again after collecting it", again)
+	}
+}

internal/inventory/hold.go

@@ -87,3 +87,62 @@ func (i *Inventory) tryHold(ctx context.Context, sorted []string) (func(), strin
 	}
 	return release, "", nil
 }
+
+// ErrPlansBusy is the plans held by another act — on a machine replacing its controller, the other
+// controller — for longer than a caller waits, or at all for one that does not wait.
+var ErrPlansBusy = errors.New("another controller is working the plans")
+
+// HoldPlans makes working the plans one act at a time, across every controller on the store
+// (novox/hq issue 213). A plan is read, changed and written whole; two controllers doing that at
+// once — the old and the new for the moment a machine hands its controller over, or a controller
+// and a person's `plans stop` — each act on what the other has not saved yet: a tier asked twice,
+// an outcome written over. A session-level advisory lock on one connection, released by the
+// returned function and by the session ending, so a controller that dies holding it holds nothing.
+//
+// wait false gives ErrPlansBusy at once when another holds them — the timer's way: the holder is
+// moving the plans already. wait true looks again every HoldPoll for up to HoldWaitFor — an
+// outcome's or a merge's way, which must be written.
+func (i *Inventory) HoldPlans(ctx context.Context, wait bool) (func(), error) {
+	deadline := time.Now().Add(HoldWaitFor)
+	for {
+		release, took, err := i.tryLock(ctx, "mesh-plans")
+		if err != nil || took {
+			return release, err
+		}
+		if !wait || time.Now().After(deadline) {
+			return nil, ErrPlansBusy
+		}
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		case <-time.After(HoldPoll):
+		}
+	}
+}
+
+// tryLock takes one named advisory lock on a connection of its own, or gives the connection back.
+func (i *Inventory) tryLock(ctx context.Context, key string) (func(), bool, error) {
+	conn, err := i.store.Pool().Acquire(ctx)
+	if err != nil {
+		return nil, false, err
+	}
+	var once sync.Once
+	release := func() {
+		once.Do(func() {
+			if _, err := conn.Exec(context.WithoutCancel(ctx), `select pg_advisory_unlock_all()`); err != nil {
+				_ = conn.Conn().Close(context.WithoutCancel(ctx))
+			}
+			conn.Release()
+		})
+	}
+	var took bool
+	if err := conn.QueryRow(ctx, `select pg_try_advisory_lock(hashtext($1)::bigint)`, key).Scan(&took); err != nil {
+		release()
+		return nil, false, err
+	}
+	if !took {
+		release()
+		return nil, false, nil
+	}
+	return release, true, nil
+}

internal/inventory/hold_plans_test.go

@@ -0,0 +1,38 @@
+package inventory
+
+import (
+	"errors"
+	"testing"
+	"time"
+)
+
+// novox/hq issue 213: while a machine hands its controller over from the container to the process,
+// two controllers run on one store for a moment. Working the plans is one act at a time across them.
+func TestThePlansAreWorkedByOneControllerAtATime(t *testing.T) {
+	first := ForTest(t)
+	// A second controller: its own connections to the same store.
+	second, err := Open(t.Context())
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(second.Close)
+
+	release, err := first.HoldPlans(t.Context(), false)
+	if err != nil {
+		t.Fatalf("the plans could not be held when nobody held them: %v", err)
+	}
+	t.Cleanup(release) // a pool closing waits for a connection still held; release is idempotent
+	if _, err := second.HoldPlans(t.Context(), false); !errors.Is(err, ErrPlansBusy) {
+		t.Fatalf("a second controller held the plans while the first did: %v", err)
+	}
+	// A waiter gets them once they are let go.
+	was := HoldPoll
+	HoldPoll = 10 * time.Millisecond
+	defer func() { HoldPoll = was }()
+	go func() { time.Sleep(50 * time.Millisecond); release() }()
+	again, err := second.HoldPlans(t.Context(), true)
+	if err != nil {
+		t.Fatalf("a waiting controller never got the plans once they were let go: %v", err)
+	}
+	again()
+}

internal/inventory/migrations/0056-what-the-store-no-longer-keeps.sql

@@ -0,0 +1,23 @@
+-- What the artifact store no longer keeps (novox/hq ADR 0189, issue 108).
+--
+-- The mesh removes from its store only what it put there and can account for: every digest it
+-- could remove is already in a build record, so the sweep reads its own records rather than
+-- enumerating the store. What it does not get from those records is whether it has already
+-- removed something -- `build.made` says what that build published, for ever, which is history
+-- and not an index of what is on disk.
+--
+-- Without this the sweep would reissue a delete for every artifact it has ever collected, every
+-- time it runs, and each one would answer 404 -- a number of requests that grows with the mesh's
+-- whole history and never shrinks.
+--
+-- Keyed by the reference as the mesh records it (`artifact-store://<module>/<artifact>@sha256:…`),
+-- because that is the identity the record uses everywhere else. Not a foreign key to build: two
+-- builds can publish the same digest (the same source built twice produces the same bytes), and
+-- what is collected is the artifact, not the attempt that made it.
+create table artifact_collected (
+    reference text        primary key,
+
+    -- When the store answered. Kept so a reader of an old build record can tell "this artifact is
+    -- gone" from "this artifact was never there", which are different kinds of surprise.
+    at        timestamptz not null default now()
+);

internal/link/receive_nats.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"log"
 	"strings"
 	"time"
 
@@ -78,10 +79,15 @@ func (n *natsInbound) Receive(ctx context.Context, act func(context.Context, Con
 	// than creating one here: the consumer is an object with a configuration — ack policy, ack
 	// wait, redelivery — and a client that creates its own would be a second opinion about it.
 	control := make(chan *nats.Msg, Prefetch)
-	said, err := js.ChanSubscribe("", control, nats.Bind("CONTROL", broker.ControllerName))
+	said, err := standingBy(ctx, log.Default(), "CONTROL", func() (*nats.Subscription, error) {
+		return js.ChanSubscribe("", control, nats.Bind("CONTROL", broker.ControllerName))
+	})
 	if err != nil {
 		return fmt.Errorf("subscribing to what nodes say: %w", err)
 	}
+	if said == nil {
+		return nil // stopped while standing by
+	}
 	defer func() { _ = said.Unsubscribe() }()
 
 	// Heartbeats, on core NATS and off any stream (design 25 §3). Their own subscription because
@@ -97,10 +103,15 @@ func (n *natsInbound) Receive(ctx context.Context, act func(context.Context, Con
 	var events chan *nats.Msg
 	if len(n.follows) > 0 {
 		events = make(chan *nats.Msg, Prefetch)
-		followed, err := js.ChanSubscribe("", events, nats.Bind("EVENTS", broker.ControllerName))
+		followed, err := standingBy(ctx, log.Default(), "EVENTS", func() (*nats.Subscription, error) {
+			return js.ChanSubscribe("", events, nats.Bind("EVENTS", broker.ControllerName))
+		})
 		if err != nil {
 			return fmt.Errorf("subscribing to what the catalogue says: %w", err)
 		}
+		if followed == nil {
+			return nil
+		}
 		defer func() { _ = followed.Unsubscribe() }()
 	}
 
@@ -324,3 +335,44 @@ func (m *natsControl) forget() {
 type replyAddressed struct {
 	ReplyTo string `json:"reply_to,omitempty"`
 }
+
+// StandbyPoll is how often a controller standing by looks again for its consumers. A variable so a
+// test need not wait.
+var StandbyPoll = 2 * time.Second
+
+// standingBy binds one of the controller's consumers, waiting while another controller holds it.
+//
+// **Two controllers, one consumer** (novox/hq issue 213). The controller's consumers are push
+// consumers with no delivery group, so the server lets one subscription bind each — on purpose:
+// two would each act on every message (issue 146). When a machine hands its controller over from
+// the container to the process, the host starts the process first and removes the container only
+// once the process is up; the process then finds the consumers bound. Exiting on that would never
+// be up, so the container would never go. It stands by instead — the seat's verbs are already
+// served from a queue group, and the plans wait on their lock — and binds as soon as the other lets
+// go. Nil and no error is ctx ending while it waited.
+func standingBy(ctx context.Context, logger interface{ Printf(string, ...any) }, stream string,
+	bind func() (*nats.Subscription, error)) (*nats.Subscription, error) {
+	said := false
+	for {
+		sub, err := bind()
+		if err == nil {
+			if said {
+				logger.Printf("took the controller's consumer on %s: the controller that held it let go", stream)
+			}
+			return sub, nil
+		}
+		if !strings.Contains(err.Error(), "already bound") {
+			return nil, err
+		}
+		if !said {
+			logger.Printf("another controller holds the controller's consumer on %s; standing by "+
+				"until it lets go", stream)
+			said = true
+		}
+		select {
+		case <-ctx.Done():
+			return nil, nil
+		case <-time.After(StandbyPoll):
+		}
+	}
+}

internal/link/standby_nats_test.go

@@ -0,0 +1,69 @@
+package link
+
+import (
+	"context"
+	"encoding/json"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/broker"
+)
+
+// novox/hq issue 213: while a machine hands its controller over, the new controller (the process)
+// is started while the old one (the container) still holds the controller's consumers. It must not
+// exit — the host would read that as a replacement that did not come up and never remove the
+// container — and must not act on what the old one is handed. It stands by, and takes the consumers
+// when the old one lets go.
+func TestNatsASecondControllerStandsByAndTakesOverWhenTheFirstLetsGo(t *testing.T) {
+	js := aBus(t)
+	was := StandbyPoll
+	StandbyPoll = 50 * time.Millisecond
+	defer func() { StandbyPoll = was }()
+
+	old := &counted{}
+	_, stopOld := servingOn(t, js, old)
+	eventually(t, "the first controller binding its consumer", func() bool {
+		info, err := js.Context().ConsumerInfo("CONTROL", broker.ControllerName)
+		return err == nil && info.PushBound
+	})
+
+	// The new one, on a connection of its own as the process would have.
+	second, err := broker.Dial(os.Getenv("MESH_TEST_NATS"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(second.Close)
+	fresh := &counted{}
+	s := &Server{inbound: Nats(second), bus: OverNATS{Conn: second.Conn(), JS: second.Context()},
+		listener: fresh, log: quiet()}
+	ctx, stopNew := context.WithCancel(context.Background())
+	defer stopNew()
+	ended := make(chan error, 1)
+	go func() { ended <- s.Serve(ctx) }()
+
+	select {
+	case err := <-ended:
+		t.Fatalf("the second controller stopped instead of standing by: %v", err)
+	case <-time.After(500 * time.Millisecond):
+	}
+
+	report := func(declared string) {
+		body, _ := json.Marshal(Report{Node: "anchor", Declared: declared, Applied: []string{"store"}})
+		if _, err := js.Context().Publish(ReportSubject("anchor"), body); err != nil {
+			t.Fatal(err)
+		}
+	}
+	report("d1")
+	eventually(t, "the holding controller hearing the report", func() bool { return old.count() == 1 })
+	if fresh.count() != 0 {
+		t.Fatal("the controller standing by acted on a report the holder was handed")
+	}
+
+	stopOld()
+	report("d2")
+	eventually(t, "the second controller taking over once the first let go", func() bool { return fresh.count() == 1 })
+	if old.count() != 1 {
+		t.Errorf("the first controller heard %d reports", old.count())
+	}
+}

internal/store/manifest_test.go

@@ -30,7 +30,7 @@ func TestTheManifestsOwnPlaceholderUnfilledLeavesTheStoreWhereTheFileSays(t *tes
 	}
 	var written string
 	for _, r := range m.Resources {
-		if r.Type == "container" {
+		if r.Type == "process" {
 			written = r.Env["MESH_STORE_INVENTORY_PORT"]
 		}
 	}

module.json

@@ -2,9 +2,6 @@
   "module": "mesh-controller",
   "version": "1",
   "slug": "control",
-  "capabilities": [
-    "container-runtime"
-  ],
   "claims": [
     {
       "name": "mesh-controller",
@@ -26,7 +23,7 @@
     "broker-address": "${dir:mesh-state}/broker-address",
     "bus": "${dir:mesh-state}/bus"
   },
-  "secrets-owner": "65534:65534",
+  "secrets-owner": "mesh-controller",
   "prepares": true,
   "tools": [
     "tools",
@@ -43,62 +40,58 @@
     "build"
   ],
   "resources": [
+    {
+      "id": "account",
+      "type": "user",
+      "name": "mesh-controller",
+      "shell": "/usr/bin/nologin",
+      "home": "/var/lib/mesh-controller"
+    },
     {
       "id": "mesh-state",
       "type": "directory",
       "mode": "0700",
-      "place": "mesh"
+      "place": "mesh",
+      "owner": "mesh-controller"
     },
     {
-      "id": "server",
-      "type": "container",
+      "id": "controller",
+      "type": "process",
       "name": "mesh-controller",
-      "network": "host",
-      "args": [
+      "artifact": "controller",
+      "run": [
+        "./mesh-controller",
         "serve"
       ],
+      "user": "mesh-controller",
       "env": {
-        "MESH_BROKER_CERTIFICATE": "/broker-tls/tls.crt",
-        "MESH_STORE_INVENTORY_FILE": "/run/secrets/inventory",
-        "MESH_STORE_IDENTITY_FILE": "/run/secrets/identity",
-        "MESH_STORE_LICENCES_FILE": "/run/secrets/licences",
-        "MESH_BROKER_MANAGEMENT_FILE": "/run/secrets/broker-management",
-        "MESH_BROKER_ADDRESS_FILE": "/run/secrets/broker-address",
+        "MESH_BROKER_CERTIFICATE": "/var/lib/mesh-broker-tls/tls.crt",
+        "MESH_STORE_INVENTORY_FILE": "${dir:mesh-state}/inventory",
+        "MESH_STORE_IDENTITY_FILE": "${dir:mesh-state}/identity",
+        "MESH_STORE_LICENCES_FILE": "${dir:mesh-state}/licences",
+        "MESH_BROKER_MANAGEMENT_FILE": "${dir:mesh-state}/broker-management",
+        "MESH_BROKER_ADDRESS_FILE": "${dir:mesh-state}/broker-address",
         "MESH_STORE_INVENTORY_PORT": "${seat:mesh-store:5432}",
         "MESH_STORE_IDENTITY_PORT": "${seat:mesh-store:5432}",
         "MESH_STORE_LICENCES_PORT": "${seat:mesh-store:5432}",
         "MESH_BROKER_MANAGEMENT_PORT": "${seat:mesh-broker:15672}",
         "MESH_BROKER_ADDRESS_PORT": "${seat:mesh-broker:5671}",
-        "MESH_BUS_NATS_FILE": "/run/secrets/bus"
+        "MESH_BUS_NATS_FILE": "${dir:mesh-state}/bus"
       },
-      "volumes": [
-        "/var/lib/mesh-broker-tls:/broker-tls:ro",
-        "${dir:mesh-state}/inventory:/run/secrets/inventory:ro",
-        "${dir:mesh-state}/identity:/run/secrets/identity:ro",
-        "${dir:mesh-state}/licences:/run/secrets/licences:ro",
-        "${dir:mesh-state}/broker:/run/secrets/broker:ro",
-        "${dir:mesh-state}/bus:/run/secrets/bus:ro",
-        "${dir:mesh-state}/broker-management:/run/secrets/broker-management:ro",
-        "${dir:mesh-state}/broker-address:/run/secrets/broker-address:ro"
-      ],
-      "artifact": "server",
-      "restart-on": [
-        "control-env"
+      "replaces": [
+        "server"
       ]
     }
   ],
   "build": {
     "artifacts": [
       {
-        "name": "server",
-        "kind": "image",
-        "from": "Dockerfile"
-      }
-    ],
-    "on": [
-      {
-        "arg": "GO_BASE",
-        "image": "golang@sha256:8ac98ca534ac3f51e1f420a1dd2c15e74c75cfa0f23f3ad27eb5d7236c349a0c"
+        "name": "controller",
+        "kind": "bundle",
+        "language": "go",
+        "system": "arch",
+        "from": "cmd/mesh-controller",
+        "binary": "mesh-controller"
       }
     ]
   }