Put the module trees of a merge into go/buildstep for both fetch steps, and let a preview name the conflicts of a head that does not merge (issues 1675, 1676, 1445)

Both still prove what they did: the counter test still collides every run and fails when an increment
writes without its revision; the deadline test fails when the read after a failed write takes a later
deadline than the ask's.

go/README.md

@@ -17,3 +17,5 @@ at the same version as the TypeScript package.
 What it holds, under ADR 0039's test: the stdio loop and the tool type, and `cli`, the local protocol
 `mesh-cli` speaks to the node-engine on its machine (novox/hq ADR 0272): the socket's path and one request and one
 answer; and `seal`, the mesh's sealed box (novox/hq ADR 0206: X25519, HKDF-SHA256, AES-256-GCM, `{v, eph, iv, tag, ct}`), byte for byte the box the licence manager made before it lived here and the TypeScript `@novox/mesh-sdk/seal` makes. Nothing else — no bus, no client, nothing of any module's. `go build ./example` and pipe a `tools/list` request into it.
+
+From release 4a of design 47 (novox/hq ADR 0453 clause 3, ADR 0446 clause 4) it also holds the composition of a machine's declaration, over a plain input and with nothing behind it: `declaration` and `validate`, the node-engine's parser and its validator, copied from mesh-host; `catalogue`, the manifests, their resolution and rendering, and `overlay`, the private network's generator, copied from mesh-controller; `compose`, the controller's planFor, renderingFor and declarationWith as functions of an `Input` (the composition never allocates, makes, keeps or writes: what a send would do it names as foreseen or returns); `sdkversion`, which mesh-sdk version a program was built with; and, in `delivery`, the layouts of the keys the builder, the checker and the indexer write (the source fingerprint's new form, the builds, the verdicts and kept verdicts, the manifests by digest). None of them holds a bus, a store or a vault client, which `go list -deps` of `compose` shows.

go/asks/condition.go

@@ -0,0 +1,149 @@
+package asks
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"reflect"
+	"strings"
+)
+
+// ConditionSubject is where a module says a condition to the operator: a by-caller accept of the operator-channel
+// seat, `mesh.seat.operator-channel.accept.condition.<publisher>` (novox/hq ADR 0437 §9). The router reads the
+// verb at the fifth part and the caller at the sixth, so the publisher is one token, the module's own name; it is
+// refused when empty or when it holds a dot, a wildcard or whitespace.
+func ConditionSubject(publisher string) (string, error) {
+	if publisher == "" {
+		return "", errors.New("asks: the condition's publisher is empty")
+	}
+	if strings.ContainsAny(publisher, ".*> \t\r\n") || strings.ContainsFunc(publisher, func(r rune) bool { return r <= ' ' }) {
+		return "", fmt.Errorf("asks: the condition's publisher %q is not one token: it holds a dot, a wildcard or whitespace", publisher)
+	}
+	return "mesh.seat." + Seat + ".accept.condition." + publisher, nil
+}
+
+// ConditionVersion is the version of the condition value this package writes and the only one it reads.
+const ConditionVersion = 1
+
+// ErrUnknownConditionVersion is what DecodeCondition returns for a value whose version is missing or not
+// ConditionVersion. Test it with errors.Is.
+var ErrUnknownConditionVersion = errors.New("asks: unknown condition version")
+
+// The words a condition's explanation opens with (novox/hq ADR 0253 §1).
+const (
+	NothingToDo = "Nothing for you to do."
+	NeedsYou    = "Needs you: "
+)
+
+// The severities and states of a condition.
+const (
+	SeverityUrgent  = "urgent"
+	SeverityWarning = "warning"
+	StateRaised     = "raised"
+	StateCleared    = "cleared"
+)
+
+// Scope is what a condition is about, under the controller's names.
+type Scope struct {
+	Scope   string `json:"scope"`
+	ID      string `json:"id"`
+	Machine string `json:"machine,omitempty"`
+}
+
+// Action is one answer a notification offers, under the controller's names.
+type Action struct {
+	Label     string            `json:"label"`
+	Verb      string            `json:"verb"`
+	Machine   string            `json:"machine,omitempty"`
+	Arguments map[string]string `json:"arguments,omitempty"`
+	Level     Level             `json:"level,omitempty"`
+}
+
+// Condition is a condition a module says to the operator, under the names of the controller's conditions: its key,
+// severity, subject, state (raised or cleared), summary and the plain words of ADR 0253. A cleared condition needs
+// only its key, subject and state. The router alone chooses the channels.
+type Condition struct {
+	V           int      `json:"v"`
+	Key         string   `json:"key"`
+	Severity    string   `json:"severity,omitempty"`
+	Subject     Scope    `json:"subject"`
+	State       string   `json:"state"`
+	Summary     string   `json:"summary,omitempty"`
+	Headline    string   `json:"headline,omitempty"`
+	Needs       string   `json:"needs,omitempty"`
+	Explanation string   `json:"explanation,omitempty"`
+	Resolved    string   `json:"resolved,omitempty"`
+	Actions     []Action `json:"actions,omitempty"`
+}
+
+func (c Condition) check() error {
+	if c.Key == "" {
+		return errors.New("asks: a condition has no key")
+	}
+	if c.Subject.Scope == "" || c.Subject.ID == "" {
+		return errors.New("asks: a condition's subject needs its scope and id")
+	}
+	switch c.State {
+	case StateCleared:
+		return nil
+	case StateRaised:
+	default:
+		return fmt.Errorf("asks: the condition's state %q is not raised or cleared", c.State)
+	}
+	switch c.Severity {
+	case SeverityUrgent, SeverityWarning:
+	default:
+		return fmt.Errorf("asks: the condition's severity %q is not urgent or warning", c.Severity)
+	}
+	if c.Headline == "" {
+		return errors.New("asks: a raised condition has no headline")
+	}
+	if n := len([]rune(c.Headline)); n > HeadlineLength {
+		return fmt.Errorf("asks: the condition's headline is %d characters, more than %d", n, HeadlineLength)
+	}
+	verdict := NothingToDo
+	if c.Needs != "" {
+		verdict = NeedsYou + c.Needs
+	}
+	if !strings.HasPrefix(c.Explanation, verdict) {
+		return fmt.Errorf("asks: the condition's explanation must open with %q", verdict)
+	}
+	return nil
+}
+
+// EncodeCondition is c as JSON at ConditionVersion; it refuses what ADR 0253 and ADR 0437 §9 refuse.
+func EncodeCondition(c Condition) ([]byte, error) {
+	if err := c.check(); err != nil {
+		return nil, err
+	}
+	c.V = ConditionVersion
+	return json.Marshal(c)
+}
+
+// DecodeCondition reads a condition; it refuses an unknown version (ErrUnknownConditionVersion) and what
+// EncodeCondition refuses.
+func DecodeCondition(data []byte) (Condition, error) {
+	var probe struct {
+		V *int `json:"v"`
+	}
+	if err := json.Unmarshal(data, &probe); err != nil {
+		return Condition{}, fmt.Errorf("asks: the condition is not JSON: %w", err)
+	}
+	if probe.V == nil {
+		return Condition{}, fmt.Errorf("%w: no version in the value, this reader reads %d", ErrUnknownConditionVersion, ConditionVersion)
+	}
+	if *probe.V != ConditionVersion {
+		return Condition{}, fmt.Errorf("%w: the value is version %d, this reader reads %d", ErrUnknownConditionVersion, *probe.V, ConditionVersion)
+	}
+	var c Condition
+	if err := json.Unmarshal(data, &c); err != nil {
+		return Condition{}, fmt.Errorf("asks: the condition does not fit its shape: %w", err)
+	}
+	if err := c.check(); err != nil {
+		return Condition{}, err
+	}
+	return c, nil
+}
+
+// SameCondition says whether two conditions are the same value.
+func SameCondition(a, b Condition) bool { return reflect.DeepEqual(a, b) }

go/asks/condition_test.go

@@ -0,0 +1,143 @@
+package asks
+
+import (
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestConditionSubject(t *testing.T) { // 1202/AC1
+	s, err := ConditionSubject("mesh-delivery-teller")
+	if err != nil || s != "mesh.seat.operator-channel.accept.condition.mesh-delivery-teller" {
+		t.Fatalf("subject = %q, %v", s, err)
+	}
+	// The router splits an accept subject in six parts and reads the verb at 4 and the caller at 5.
+	parts := strings.Split(s, ".")
+	if len(parts) != 6 || parts[4] != "condition" || parts[5] != "mesh-delivery-teller" {
+		t.Errorf("subject %q does not keep the router's shape: %v", s, parts)
+	}
+	for _, bad := range []string{"", "a.b", "a*", "a>", "a b", "a\tb", "a\nb"} {
+		if _, err := ConditionSubject(bad); err == nil {
+			t.Errorf("publisher %q accepted", bad)
+		}
+	}
+}
+
+func raisedCondition() Condition {
+	return Condition{
+		Key: "delivery.stuck.mesh-mail", Severity: "warning",
+		Subject: Scope{Scope: "module", ID: "mesh-mail", Machine: "ace"}, State: "raised",
+		Summary: "plan 12 stopped", Headline: "Delivery of mesh-mail is stuck",
+		Needs: "approve the merge.", Explanation: "Needs you: approve the merge. The plan waits.",
+		Resolved: "The delivery of mesh-mail moved on.",
+		Actions: []Action{{Label: "Approve", Verb: "mesh-controller.assign", Machine: "ace",
+			Arguments: map[string]string{"why": ""}, Level: Approve}},
+	}
+}
+
+func clearedCondition() Condition {
+	return Condition{Key: "delivery.stuck.mesh-mail", Subject: Scope{Scope: "module", ID: "mesh-mail"}, State: "cleared"}
+}
+
+func TestConditionRoundTrip(t *testing.T) { // 1202/AC2
+	for _, c := range []Condition{raisedCondition(), clearedCondition()} {
+		data, err := EncodeCondition(c)
+		if err != nil {
+			t.Fatalf("%s: %v", c.State, err)
+		}
+		var probe map[string]any
+		if err := json.Unmarshal(data, &probe); err != nil || probe["v"] != float64(1) {
+			t.Fatalf("%s: %s does not carry v:1", c.State, data)
+		}
+		c.V = ConditionVersion
+		got, err := DecodeCondition(data)
+		if err != nil || !SameCondition(got, c) {
+			t.Errorf("%s round trip: %+v %v", c.State, got, err)
+		}
+	}
+	data, _ := EncodeCondition(raisedCondition())
+	var probe map[string]any
+	_ = json.Unmarshal(data, &probe)
+	for _, name := range []string{"key", "severity", "subject", "summary", "headline", "needs", "explanation", "resolved", "actions", "state"} {
+		if _, ok := probe[name]; !ok {
+			t.Errorf("the JSON has no %q: %s", name, data)
+		}
+	}
+	subject := probe["subject"].(map[string]any)
+	for _, name := range []string{"scope", "id", "machine"} {
+		if _, ok := subject[name]; !ok {
+			t.Errorf("the subject has no %q: %s", name, data)
+		}
+	}
+	action := probe["actions"].([]any)[0].(map[string]any)
+	for _, name := range []string{"label", "verb", "machine", "arguments", "level"} {
+		if _, ok := action[name]; !ok {
+			t.Errorf("the action has no %q: %s", name, data)
+		}
+	}
+	for _, in := range []string{`{"key":"k"}`, `{"v":2,"key":"k"}`} {
+		if _, err := DecodeCondition([]byte(in)); !errors.Is(err, ErrUnknownConditionVersion) {
+			t.Errorf("decode of %s = %v, want ErrUnknownConditionVersion", in, err)
+		}
+	}
+}
+
+func TestConditionVerdict(t *testing.T) { // 1202/AC3
+	c := raisedCondition()
+	c.Needs, c.Explanation = "", "The plan waits."
+	_, err := EncodeCondition(c)
+	if err == nil || !strings.Contains(err.Error(), "Nothing for you to do.") {
+		t.Errorf("empty needs without its verdict: %v", err)
+	}
+	c.Explanation = "Nothing for you to do. The plan waits."
+	if _, err := EncodeCondition(c); err != nil {
+		t.Errorf("empty needs with its verdict refused: %v", err)
+	}
+	c = raisedCondition()
+	c.Explanation = "Nothing for you to do. The plan waits."
+	_, err = EncodeCondition(c)
+	if err == nil || !strings.Contains(err.Error(), "Needs you: approve the merge.") {
+		t.Errorf("needs set with the wrong verdict: %v", err)
+	}
+	c.Explanation = "Needs you: something else. The plan waits."
+	if _, err = EncodeCondition(c); err == nil {
+		t.Error("needs set with other needs in the verdict accepted")
+	}
+}
+
+func TestConditionRefused(t *testing.T) { // 1202/AC4
+	mutate := func(f func(*Condition)) error {
+		c := raisedCondition()
+		f(&c)
+		_, err := EncodeCondition(c)
+		return err
+	}
+	for name, f := range map[string]func(*Condition){
+		"severity":      func(c *Condition) { c.Severity = "critical" },
+		"state":         func(c *Condition) { c.State = "open" },
+		"key":           func(c *Condition) { c.Key = "" },
+		"headline":      func(c *Condition) { c.Headline = "" },
+		"long headline": func(c *Condition) { c.Headline = strings.Repeat("h", HeadlineLength+1) },
+	} {
+		if err := mutate(f); err == nil {
+			t.Errorf("a condition with a bad %s accepted", name)
+		}
+	}
+	if err := mutate(func(c *Condition) { c.Headline = strings.Repeat("h", HeadlineLength) }); err != nil {
+		t.Errorf("a headline of the greatest length refused: %v", err)
+	}
+	if _, err := EncodeCondition(clearedCondition()); err != nil {
+		t.Errorf("a cleared condition with only key, subject and state refused: %v", err)
+	}
+	c := clearedCondition()
+	c.Key = ""
+	if _, err := EncodeCondition(c); err == nil {
+		t.Error("a cleared condition without its key accepted")
+	}
+	c = clearedCondition()
+	c.State = "gone"
+	if _, err := EncodeCondition(c); err == nil {
+		t.Error("a condition with an unknown state accepted")
+	}
+}

go/buildstep/fetch.go

@@ -0,0 +1,114 @@
+package buildstep
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+	"regexp"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+// Option changes FetchCommit.
+type Option func(*fetchOptions)
+
+type fetchOptions struct{ allowFile bool }
+
+// AllowFileRemote lets FetchCommit take a file:// remote. It is for a test's local repository; production
+// code does not pass it, and FetchCommit then refuses anything but ssh://.
+func AllowFileRemote() Option { return func(o *fetchOptions) { o.allowFile = true } }
+
+var (
+	commitOK = regexp.MustCompile(`^[0-9a-f]{40}$`)
+	refOK    = regexp.MustCompile(`^refs/[A-Za-z0-9._/-]+$`)
+)
+
+// FetchCommit fetches one commit of a forge repository into dir, an empty directory, and checks it out detached
+// (novox/hq ADR 0466 §4, §5; issue 1474). remote is ssh://<ssh name>/<owner>/<repo>.git, the ssh name being the
+// one the build module's templates set up (ADR 0409 §1); commit is a full 40-hex sha; ref is optional, and names
+// the pull request's head (refs/pull/<n>/head) when the commit is only there. Every git command runs through run
+// as `git -C dir ...` with GIT_TERMINAL_PROMPT=0 and no credential helper, so nothing is asked for and no
+// credential is used. A remote that is not ssh://, or one with user information, and a commit that is not 40
+// hex digits are refused before anything runs.
+func FetchCommit(ctx context.Context, run forgekey.Runner, dir, remote, commit, ref string, opts ...Option) error {
+	var o fetchOptions
+	for _, opt := range opts {
+		opt(&o)
+	}
+	if err := checkFetch(o, dir, remote, commit, ref); err != nil {
+		return err
+	}
+	env := []string{"GIT_TERMINAL_PROMPT=0"}
+	git := func(args ...string) (string, error) {
+		full := append([]string{"-c", "credential.helper=", "-C", dir}, args...)
+		r := run(ctx, env, "git", full...)
+		if r.Status != 0 || r.Err != "" {
+			return "", fmt.Errorf("git %s: %s", args[0], firstLine(r.Err+" "+r.Stderr))
+		}
+		return r.Stdout, nil
+	}
+	if _, err := git("init", "-q"); err != nil {
+		return err
+	}
+	if _, err := git("remote", "add", "origin", remote); err != nil {
+		return err
+	}
+	if _, err := git("fetch", "--no-tags", "--depth", "1", "origin", commit); err != nil {
+		if ref == "" {
+			return err
+		}
+		if _, rerr := git("fetch", "--no-tags", "origin", ref); rerr != nil {
+			return fmt.Errorf("%v; then the ref %s: %w", err, ref, rerr)
+		}
+		if _, verr := git("cat-file", "-e", commit+"^{commit}"); verr != nil {
+			return fmt.Errorf("the commit %s is not in %s: %w", commit, ref, verr)
+		}
+	}
+	if _, err := git("checkout", "-q", "--detach", commit); err != nil {
+		return err
+	}
+	out, err := git("rev-parse", "HEAD")
+	if err != nil {
+		return err
+	}
+	if head := strings.TrimSpace(out); head != commit {
+		return fmt.Errorf("the checkout is at %s, not at the commit %s", head, commit)
+	}
+	return nil
+}
+
+func checkFetch(o fetchOptions, dir, remote, commit, ref string) error {
+	if dir == "" {
+		return fmt.Errorf("buildstep: no workspace directory")
+	}
+	if !commitOK.MatchString(commit) {
+		return fmt.Errorf("buildstep: %q is not a full commit (40 hex digits)", commit)
+	}
+	if ref != "" && !refOK.MatchString(ref) {
+		return fmt.Errorf("buildstep: %q is not a ref (refs/...)", ref)
+	}
+	u, err := url.Parse(remote)
+	if err != nil {
+		return fmt.Errorf("buildstep: the remote is not a URL: %w", err)
+	}
+	if u.User != nil {
+		return fmt.Errorf("buildstep: the remote carries user information; the key is the credential")
+	}
+	switch {
+	case u.Scheme == "ssh" && u.Host != "":
+	case u.Scheme == "file" && o.allowFile:
+	default:
+		return fmt.Errorf("buildstep: the remote %q is not ssh://", remote)
+	}
+	return nil
+}
+
+func firstLine(s string) string {
+	for _, l := range strings.Split(s, "\n") {
+		if l = strings.TrimSpace(l); l != "" {
+			return l
+		}
+	}
+	return ""
+}

go/buildstep/fetch_integration_test.go

@@ -0,0 +1,59 @@
+//go:build integration
+
+package buildstep
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+func gitIn(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir, "-c", "user.name=t", "-c", "user.email=t@example.invalid"}, args...)...)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %v: %v\n%s", args, err, out)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+// 1474/AC5: a local bare repository with a commit only under refs/pull/1/head (a file:// remote, allowed by the
+// test-only option): the workspace's HEAD is the commit. The forge itself is proven live after the build
+// modules' delivery (ADR 0466 §5).
+func TestFetchCommitFromAPullRefOnly(t *testing.T) {
+	root := t.TempDir()
+	bare := filepath.Join(root, "r.git")
+	work := filepath.Join(root, "work")
+	for _, d := range []string{bare, work} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	gitIn(t, bare, "init", "-q", "--bare")
+	gitIn(t, work, "init", "-q")
+	if err := os.WriteFile(filepath.Join(work, "f"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	gitIn(t, work, "add", "f")
+	gitIn(t, work, "commit", "-q", "-m", "pull request head")
+	commit := gitIn(t, work, "rev-parse", "HEAD")
+	gitIn(t, work, "push", "-q", bare, "HEAD:refs/pull/1/head")
+
+	ws := filepath.Join(root, "ws")
+	if err := os.MkdirAll(ws, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	err := FetchCommit(context.Background(), forgekey.ExecRunner, ws, "file://"+bare, commit, "refs/pull/1/head", AllowFileRemote())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if head := gitIn(t, ws, "rev-parse", "HEAD"); head != commit {
+		t.Errorf("HEAD = %s, want %s", head, commit)
+	}
+}

go/buildstep/fetch_test.go

@@ -0,0 +1,137 @@
+package buildstep
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+const sha = "0123456789abcdef0123456789abcdef01234567"
+
+// fakeGit records every command and answers by a rule.
+type fakeGit struct {
+	calls []string
+	envs  [][]string
+	rule  func(args string) forgekey.Ran
+}
+
+func (f *fakeGit) run(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
+	line := name + " " + strings.Join(args, " ")
+	f.calls = append(f.calls, line)
+	f.envs = append(f.envs, env)
+	if f.rule != nil {
+		if r := f.rule(line); r.Status != 0 || r.Stdout != "" || r.Err != "" {
+			return r
+		}
+	}
+	if len(args) > 4 && args[4] == "rev-parse" {
+		return forgekey.Ran{Stdout: sha + "\n"}
+	}
+	return forgekey.Ran{}
+}
+
+const pre = "git -c credential.helper= -C /w "
+
+// 1474/AC1: the git commands are exactly the sequence, none with a credential or an https remote.
+func TestFetchCommitRunsTheSequence(t *testing.T) {
+	f := &fakeGit{}
+	if err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/novox/mesh-sdk.git", sha, ""); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{
+		pre + "init -q",
+		pre + "remote add origin ssh://mesh-forge/novox/mesh-sdk.git",
+		pre + "fetch --no-tags --depth 1 origin " + sha,
+		pre + "checkout -q --detach " + sha,
+		pre + "rev-parse HEAD",
+	}
+	if strings.Join(f.calls, "\n") != strings.Join(want, "\n") {
+		t.Errorf("commands:\n%s\nwant:\n%s", strings.Join(f.calls, "\n"), strings.Join(want, "\n"))
+	}
+	for i, c := range f.calls {
+		if strings.Contains(c, "https://") || strings.Contains(c, "@") || !strings.Contains(c, "credential.helper= ") {
+			t.Errorf("command %q carries a credential or https", c)
+		}
+		if len(f.envs[i]) != 1 || f.envs[i][0] != "GIT_TERMINAL_PROMPT=0" {
+			t.Errorf("env %v", f.envs[i])
+		}
+	}
+}
+
+// 1474/AC2: the depth-1 fetch fails and a pull ref is given: the ref is fetched and the commit verified; with no
+// ref, the fetch's failure is the answer.
+func TestFetchCommitFallsBackToThePullRef(t *testing.T) {
+	f := &fakeGit{rule: func(l string) forgekey.Ran {
+		if strings.Contains(l, "--depth 1") {
+			return forgekey.Ran{Status: 128, Stderr: "fatal: couldn't find remote ref " + sha + "\n"}
+		}
+		return forgekey.Ran{}
+	}}
+	if err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", sha, "refs/pull/1/head"); err != nil {
+		t.Fatal(err)
+	}
+	want := []string{pre + "fetch --no-tags origin refs/pull/1/head", pre + "cat-file -e " + sha + "^{commit}", pre + "checkout -q --detach " + sha}
+	got := strings.Join(f.calls[3:6], "\n")
+	if got != strings.Join(want, "\n") {
+		t.Errorf("after the failed fetch:\n%s\nwant:\n%s", got, strings.Join(want, "\n"))
+	}
+
+	g := &fakeGit{rule: f.rule}
+	err := FetchCommit(context.Background(), g.run, "/w", "ssh://mesh-forge/o/r.git", sha, "")
+	if err == nil || !strings.Contains(err.Error(), "couldn't find remote ref") || len(g.calls) != 3 {
+		t.Errorf("without a ref: %v after %d commands", err, len(g.calls))
+	}
+
+	h := &fakeGit{rule: func(l string) forgekey.Ran {
+		if strings.Contains(l, "--depth 1") || strings.Contains(l, "cat-file") {
+			return forgekey.Ran{Status: 1, Stderr: "no"}
+		}
+		return forgekey.Ran{}
+	}}
+	if err := FetchCommit(context.Background(), h.run, "/w", "ssh://mesh-forge/o/r.git", sha, "refs/pull/1/head"); err == nil {
+		t.Error("a commit that is not in the ref was accepted")
+	}
+}
+
+// 1474/AC3: HEAD differs from the commit after the checkout: an error naming both.
+func TestFetchCommitAnswersAHeadThatIsNotTheCommit(t *testing.T) {
+	other := strings.Repeat("a", 40)
+	f := &fakeGit{rule: func(l string) forgekey.Ran {
+		if strings.HasSuffix(l, "rev-parse HEAD") {
+			return forgekey.Ran{Stdout: other + "\n"}
+		}
+		return forgekey.Ran{}
+	}}
+	err := FetchCommit(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", sha, "")
+	if err == nil || !strings.Contains(err.Error(), other) || !strings.Contains(err.Error(), sha) {
+		t.Errorf("error = %v, want both shas", err)
+	}
+}
+
+// 1474/AC4: an https remote, user information, a file remote without the option, or a commit that is not 40
+// hex digits is refused before anything runs.
+func TestFetchCommitRefusesBeforeRunningAnything(t *testing.T) {
+	for _, c := range []struct{ remote, commit, ref string }{
+		{"https://forge.example/o/r.git", sha, ""},
+		{"http://forge.example/o/r.git", sha, ""},
+		{"ssh://git@mesh-forge/o/r.git", sha, ""},
+		{"ssh://user:pw@mesh-forge/o/r.git", sha, ""},
+		{"file:///tmp/r.git", sha, ""},
+		{"/tmp/r.git", sha, ""},
+		{"ssh://mesh-forge/o/r.git", "abc123", ""},
+		{"ssh://mesh-forge/o/r.git", strings.ToUpper(sha), ""},
+		{"ssh://mesh-forge/o/r.git", "main", ""},
+		{"ssh://mesh-forge/o/r.git", sha, "--upload-pack=x"},
+	} {
+		f := &fakeGit{}
+		if err := FetchCommit(context.Background(), f.run, "/w", c.remote, c.commit, c.ref); err == nil || len(f.calls) != 0 {
+			t.Errorf("%+v: err %v, %d commands", c, err, len(f.calls))
+		}
+	}
+	f := &fakeGit{}
+	if err := FetchCommit(context.Background(), f.run, "/w", "file:///tmp/r.git", sha, "", AllowFileRemote()); err != nil {
+		t.Errorf("a file remote with the option: %v", err)
+	}
+}

go/buildstep/guard.go

@@ -0,0 +1,52 @@
+package buildstep
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+
+	"git.novox.be/novox/mesh-sdk/go/delivery"
+)
+
+// Guard is a build module's check that the toolchain installed on its node is the one its recipe builds with
+// (novox/hq ADR 0469 §1; issue 1473). The same guard serves ADR 0470 §4's postgres major for the integration
+// level, with its own Probe and Want.
+type Guard struct {
+	// Language is the toolchain's key part: go or typescript (delivery.ToolchainKey).
+	Language string
+	// Want is the toolchain version the recipe builds with, and Recipe the recipe's own version. The indexer
+	// compares both texts as they are written here.
+	Want, Recipe string
+	// Probe reads the installed version (go version, node --version).
+	Probe func(ctx context.Context) (installed string, err error)
+	Node  string
+	// Put is the toolchains state's Put (stdio.State(delivery.ToolchainsState).Put).
+	Put Put
+}
+
+// Check probes the installed version, writes it to <node>.<language> of the toolchains state every time it runs,
+// and answers nil when it is the recipe's. Otherwise it answers a *Refusal naming both versions; the installed
+// version is written even then, so the indexer sees that builders disagree. A probe that fails is a *Refusal
+// naming its failure, and nothing is written. A write that fails is an error that is not a Refusal.
+func (g Guard) Check(ctx context.Context) error {
+	installed, err := g.Probe(ctx)
+	if err != nil {
+		return &Refusal{Text: fmt.Sprintf("the installed %s version could not be read: %v", g.Language, err), Want: g.Want}
+	}
+	key, err := delivery.ToolchainKey(g.Node, g.Language)
+	if err != nil {
+		return err
+	}
+	raw, err := delivery.EncodeToolchain(delivery.Toolchain{Language: g.Language, Version: installed, Recipe: g.Recipe, At: now().UTC()})
+	if err != nil {
+		return err
+	}
+	if _, err := g.Put(key, json.RawMessage(raw)); err != nil {
+		return fmt.Errorf("buildstep: writing the toolchain %s: %w", key, err)
+	}
+	if installed != g.Want {
+		return &Refusal{Text: fmt.Sprintf("%s %s installed, the recipe builds with %s %s", g.Language, installed, g.Language, g.Want),
+			Want: g.Want, Have: installed}
+	}
+	return nil
+}

go/buildstep/guard_test.go

@@ -0,0 +1,79 @@
+package buildstep
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/delivery"
+)
+
+type toolchainKeys map[string]delivery.Toolchain
+
+func (k toolchainKeys) put(key string, value any) (uint64, error) {
+	tc, err := delivery.DecodeToolchain(value.(json.RawMessage))
+	if err != nil {
+		return 0, err
+	}
+	k[key] = tc
+	return uint64(len(k)), nil
+}
+
+func guardFor(k toolchainKeys, installed string, probeErr error) Guard {
+	return Guard{Language: "go", Want: "1.27.0", Recipe: "r7", Node: "ace", Put: k.put,
+		Probe: func(context.Context) (string, error) { return installed, probeErr }}
+}
+
+// 1473/AC1: the probe answers the recipe's version: nil, and <node>.go holds that version and the recipe's.
+func TestCheckPassesAndWritesTheToolchain(t *testing.T) {
+	k := toolchainKeys{}
+	if err := guardFor(k, "1.27.0", nil).Check(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+	tc, ok := k["ace.go"]
+	if !ok || tc.Version != "1.27.0" || tc.Recipe != "r7" || tc.Language != "go" || tc.At.IsZero() {
+		t.Errorf("keys = %+v", k)
+	}
+}
+
+// 1473/AC2: another version: a Refusal naming both, and the key holds the installed version.
+func TestCheckRefusesAnotherVersionAndWritesTheInstalledOne(t *testing.T) {
+	k := toolchainKeys{}
+	err := guardFor(k, "1.27.1", nil).Check(context.Background())
+	var ref *Refusal
+	if !errors.As(err, &ref) {
+		t.Fatalf("Check = %v, want a Refusal", err)
+	}
+	if ref.Text != "go 1.27.1 installed, the recipe builds with go 1.27.0" || ref.Want != "1.27.0" || ref.Have != "1.27.1" {
+		t.Errorf("refusal = %+v", ref)
+	}
+	if k["ace.go"].Version != "1.27.1" {
+		t.Errorf("the key holds %q, want the installed 1.27.1", k["ace.go"].Version)
+	}
+}
+
+// 1473/AC3: a probe that fails: a Refusal naming the failure, and nothing put.
+func TestCheckRefusesAFailedProbeAndPutsNothing(t *testing.T) {
+	k := toolchainKeys{}
+	err := guardFor(k, "", errors.New("go: not found")).Check(context.Background())
+	var ref *Refusal
+	if !errors.As(err, &ref) || !strings.Contains(ref.Text, "go: not found") {
+		t.Fatalf("Check = %v, want a Refusal naming the probe's failure", err)
+	}
+	if len(k) != 0 {
+		t.Errorf("put %v", k)
+	}
+}
+
+// A failed write is an error, not a refusal: the step fails instead of refusing.
+func TestCheckAnswersAFailedWriteAsAnError(t *testing.T) {
+	g := guardFor(toolchainKeys{}, "1.27.0", nil)
+	g.Put = func(string, any) (uint64, error) { return 0, errors.New("no grant") }
+	err := g.Check(context.Background())
+	var ref *Refusal
+	if err == nil || errors.As(err, &ref) {
+		t.Errorf("Check = %v", err)
+	}
+}

go/buildstep/merge.go

@@ -0,0 +1,112 @@
+package buildstep
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+// MergeResult is what MergeInto made of a head and a trunk commit: the trunk commit (Base) and the head, whole, and the
+// merge commit and the paths the merge changes against the trunk commit; or, when the head does not merge cleanly, the
+// files in conflict, with Merge and Changed empty.
+type MergeResult struct {
+	Base, Head, Merge string
+	Conflicts         []string
+	Changed           []string
+}
+
+// MergeInto makes, in the workspace dir that FetchCommit left at commit, the merge of commit into the trunk commit
+// base, as the forge's default merge would (a merge commit, never a fast-forward), and leaves the workspace at the merge
+// (novox/hq ADR 0484 clause 3, ADR 0323). It is the one merge the build modules' fetch steps make, with the identity
+// and flags of the controller's check merge (mesh-controller internal/builder/check_merge.go): a name nobody owns, no
+// signature, no hook, nothing of the machine's git configuration that changes a merge. Nothing is pushed.
+//
+// A merge needs both histories, so it makes the fetch whole (the shallow clone FetchCommit made is deepened) and
+// fetches base by its sha. A head that does not merge cleanly is an answer, not an error: the files in conflict, the
+// merge undone and the workspace left at base. A head already in base answers a Merge equal to Base and no changed
+// paths. An error is that the merge could not be tried: a base or commit that is not a full sha, no base, a workspace
+// not at commit, or a fetch or git command that failed. remote and the options are those of FetchCommit; the runner's
+// bound must allow a whole fetch.
+func MergeInto(ctx context.Context, run forgekey.Runner, dir, remote, base, commit string, opts ...Option) (MergeResult, error) {
+	var o fetchOptions
+	for _, opt := range opts {
+		opt(&o)
+	}
+	res := MergeResult{Base: base, Head: commit}
+	if base == "" {
+		return res, fmt.Errorf("buildstep: no base: a merge needs the trunk commit it is made onto")
+	}
+	if err := checkFetch(o, dir, remote, base, ""); err != nil {
+		return res, err
+	}
+	if err := checkFetch(o, dir, remote, commit, ""); err != nil {
+		return res, err
+	}
+	env := []string{"GIT_TERMINAL_PROMPT=0"}
+	git := func(args ...string) (string, error) {
+		full := append([]string{"-c", "credential.helper=", "-C", dir}, args...)
+		r := run(ctx, env, "git", full...)
+		if r.Status != 0 || r.Err != "" {
+			return "", fmt.Errorf("git %s: %s", args[0], firstLine(r.Err+" "+r.Stderr))
+		}
+		return r.Stdout, nil
+	}
+	at, err := git("rev-parse", "HEAD")
+	if err != nil {
+		return res, err
+	}
+	if head := strings.TrimSpace(at); head != commit {
+		return res, fmt.Errorf("buildstep: the workspace is at %s, not at the commit %s", head, commit)
+	}
+	shallow, err := git("rev-parse", "--is-shallow-repository")
+	if err != nil {
+		return res, err
+	}
+	fetch := []string{"fetch", "--no-tags", "origin", base}
+	if strings.TrimSpace(shallow) == "true" {
+		fetch = []string{"fetch", "--no-tags", "--unshallow", "origin", base}
+	}
+	if _, err := git(fetch...); err != nil {
+		return res, fmt.Errorf("the trunk commit %s: %w", base, err)
+	}
+	if _, err := git("checkout", "-q", "--detach", base); err != nil {
+		return res, fmt.Errorf("the trunk commit %s cannot be checked out: %w", base, err)
+	}
+	message := fmt.Sprintf("Check the merge of %s into %s (made for a check, never pushed)", short(commit), short(base))
+	args := append(append([]string{}, mergeIdentity...), "merge", "--no-ff", "--no-edit", "--no-verify", "--quiet", "-m", message, commit)
+	if _, err := git(args...); err != nil {
+		out, _ := git("diff", "--name-only", "--diff-filter=U")
+		res.Conflicts = strings.Fields(out)
+		_, _ = git("merge", "--abort")
+		if len(res.Conflicts) == 0 {
+			return res, fmt.Errorf("the head %s could not be merged into the trunk commit %s: %w", short(commit), short(base), err)
+		}
+		return res, nil
+	}
+	merge, err := git("rev-parse", "HEAD")
+	if err != nil {
+		return res, fmt.Errorf("the merge cannot be read: %w", err)
+	}
+	res.Merge = strings.TrimSpace(merge)
+	changed, err := git("diff", "--name-only", "--no-renames", base, res.Merge)
+	if err != nil {
+		return res, fmt.Errorf("the paths the merge changes cannot be read: %w", err)
+	}
+	res.Changed = strings.Fields(changed)
+	return res, nil
+}
+
+// mergeIdentity is who a check's merge is made as: it is never pushed, so it names nobody's account. No hook of the
+// clone's or the build machine's git configuration runs, and no setting there changes the merge (the controller's
+// check merge, internal/builder/check_merge.go).
+var mergeIdentity = []string{"-c", "user.name=mesh merge check", "-c", "user.email=merge-check@mesh.invalid",
+	"-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", "-c", "merge.verifySignatures=false"}
+
+func short(commit string) string {
+	if len(commit) > 12 {
+		return commit[:12]
+	}
+	return commit
+}

go/buildstep/merge_integration_test.go

@@ -0,0 +1,172 @@
+//go:build integration
+
+package buildstep
+
+import (
+	"context"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+// The merge on real git repositories starts git processes, so it is an integration test (the unit level keeps its bound,
+// issue 895); the unit tests of merge_test.go prove the commands and the refusals with a fake runner.
+
+func realGit(t *testing.T, dir string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", append([]string{"-C", dir, "-c", "user.name=t", "-c", "user.email=t@example.invalid", "-c", "commit.gpgsign=false"}, args...)...)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %v: %v\n%s", args, err, out)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func writeFile(t *testing.T, dir, name, content string) {
+	t.Helper()
+	p := filepath.Join(dir, name)
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// mergeRig is a local bare repository standing in for the forge, a work repository that pushes to it, and an empty
+// workspace: the fetch step's shape (FetchCommit of the head into the workspace, then MergeInto).
+type mergeRig struct {
+	t              *testing.T
+	bare, work, ws string
+	fork, trunk    string // the commit both histories share, and the trunk's head
+	remote         string
+}
+
+func newMergeRig(t *testing.T) *mergeRig {
+	root := t.TempDir()
+	r := &mergeRig{t: t, bare: filepath.Join(root, "r.git"), work: filepath.Join(root, "work"), ws: filepath.Join(root, "ws")}
+	for _, d := range []string{r.bare, r.work, r.ws} {
+		if err := os.MkdirAll(d, 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	r.remote = "file://" + r.bare
+	realGit(t, r.bare, "init", "-q", "--bare")
+	realGit(t, r.work, "init", "-q", "-b", "main")
+	writeFile(t, r.work, "a.txt", "one\ntwo\nthree\n")
+	writeFile(t, r.work, "modules/m/module.json", "{}\n")
+	realGit(t, r.work, "add", ".")
+	realGit(t, r.work, "commit", "-q", "-m", "fork point")
+	r.fork = realGit(t, r.work, "rev-parse", "HEAD")
+	return r
+}
+
+// head makes a commit on a branch off the fork point, pushes it as the pull request's head ref and answers its sha.
+func (r *mergeRig) head(files map[string]string) string {
+	realGit(r.t, r.work, "checkout", "-q", "-B", "pr", r.fork)
+	for n, c := range files {
+		writeFile(r.t, r.work, n, c)
+	}
+	realGit(r.t, r.work, "add", ".")
+	realGit(r.t, r.work, "commit", "-q", "-m", "head")
+	h := realGit(r.t, r.work, "rev-parse", "HEAD")
+	realGit(r.t, r.work, "push", "-q", r.bare, "HEAD:refs/pull/1/head")
+	return h
+}
+
+// advance moves the trunk past the fork point with a commit changing files, pushes it and answers its sha.
+func (r *mergeRig) advance(files map[string]string) string {
+	realGit(r.t, r.work, "checkout", "-q", "-B", "main", r.fork)
+	for n, c := range files {
+		writeFile(r.t, r.work, n, c)
+	}
+	realGit(r.t, r.work, "add", ".")
+	realGit(r.t, r.work, "commit", "-q", "-m", "trunk moves")
+	r.trunk = realGit(r.t, r.work, "rev-parse", "HEAD")
+	realGit(r.t, r.work, "push", "-q", "-f", r.bare, "HEAD:refs/heads/main")
+	return r.trunk
+}
+
+func (r *mergeRig) fetch(head string) {
+	if err := FetchCommit(context.Background(), forgekey.ExecRunner, r.ws, r.remote, head, "refs/pull/1/head", AllowFileRemote()); err != nil {
+		r.t.Fatal(err)
+	}
+}
+
+// 1674/AC1: a clean merge answers the merge commit and the changed files, and leaves the workspace at the merge, which
+// holds both sides' changes.
+func TestMergeIntoACleanMergeAnswersTheMergeCommitAndTheChangedFiles(t *testing.T) {
+	r := newMergeRig(t)
+	head := r.head(map[string]string{"b.txt": "head\n"})
+	base := r.advance(map[string]string{"a.txt": "one\ntwo\nthree\nfour\n"})
+	r.fetch(head)
+	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Base != base || res.Head != head || len(res.Merge) != 40 || res.Merge == base || res.Merge == head || len(res.Conflicts) != 0 {
+		t.Fatalf("result = %+v", res)
+	}
+	if !reflect.DeepEqual(res.Changed, []string{"b.txt"}) {
+		t.Errorf("changed = %v, want only what the head adds to the trunk: b.txt", res.Changed)
+	}
+	if at := realGit(t, r.ws, "rev-parse", "HEAD"); at != res.Merge {
+		t.Errorf("the workspace is at %s, not at the merge %s", at, res.Merge)
+	}
+	for f, want := range map[string]string{"b.txt": "head\n", "a.txt": "one\ntwo\nthree\nfour\n"} {
+		if got, _ := os.ReadFile(filepath.Join(r.ws, f)); string(got) != want {
+			t.Errorf("%s = %q, want %q", f, got, want)
+		}
+	}
+	if parents := strings.Fields(realGit(t, r.ws, "rev-list", "--parents", "-n", "1", res.Merge)); len(parents) != 3 || parents[1] != base || parents[2] != head {
+		t.Errorf("the merge commit's parents = %v, want the trunk commit and the head", parents)
+	}
+	if author := realGit(t, r.ws, "log", "-1", "--format=%an <%ae>", res.Merge); author != "mesh merge check <merge-check@mesh.invalid>" {
+		t.Errorf("the merge is made as %q", author)
+	}
+}
+
+// 1674/AC2: a conflict is an answer: the files in conflict, no merge commit, and the workspace left at the trunk commit.
+func TestMergeIntoAConflictAnswersTheFilesAndLeavesTheTreeAtTheTrunk(t *testing.T) {
+	r := newMergeRig(t)
+	head := r.head(map[string]string{"a.txt": "one\nHEAD\nthree\n", "c.txt": "c\n"})
+	base := r.advance(map[string]string{"a.txt": "one\nTRUNK\nthree\n"})
+	r.fetch(head)
+	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
+	if err != nil {
+		t.Fatalf("a conflict is an answer, not an error: %v", err)
+	}
+	if !reflect.DeepEqual(res.Conflicts, []string{"a.txt"}) || res.Merge != "" || len(res.Changed) != 0 || res.Base != base || res.Head != head {
+		t.Fatalf("result = %+v", res)
+	}
+	if at := realGit(t, r.ws, "rev-parse", "HEAD"); at != base {
+		t.Errorf("the workspace is at %s, not at the trunk commit %s", at, base)
+	}
+	if got, _ := os.ReadFile(filepath.Join(r.ws, "a.txt")); string(got) != "one\nTRUNK\nthree\n" {
+		t.Errorf("a.txt = %q, want the trunk's", got)
+	}
+	if st := realGit(t, r.ws, "status", "--porcelain"); st != "" {
+		t.Errorf("the tree is not clean after the aborted merge: %q", st)
+	}
+	if _, err := os.Stat(filepath.Join(r.ws, "c.txt")); err == nil {
+		t.Error("a file of the head is in a tree left at the trunk")
+	}
+}
+
+// A head already in the trunk merges into nothing: the merge is the trunk commit and no path changes.
+func TestMergeIntoAHeadAlreadyInTheTrunkChangesNothing(t *testing.T) {
+	r := newMergeRig(t)
+	head := r.head(map[string]string{"b.txt": "head\n"})
+	r.fork = head // the trunk continues from the head
+	base := r.advance(map[string]string{"a.txt": "one\ntwo\nthree\nfour\n"})
+	r.fetch(head)
+	res, err := MergeInto(context.Background(), forgekey.ExecRunner, r.ws, r.remote, base, head, AllowFileRemote())
+	if err != nil || res.Merge != base || len(res.Changed) != 0 || len(res.Conflicts) != 0 {
+		t.Errorf("result = %+v, %v", res, err)
+	}
+}

go/buildstep/merge_test.go

@@ -0,0 +1,74 @@
+package buildstep
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+// 1674/AC3: no base is refused before anything runs; so is a base or a commit that is not a full sha, a workspace that
+// is not at the commit, and a remote that is not ssh://.
+func TestMergeIntoRefusesWhatIsNotAMerge(t *testing.T) {
+	f := &fakeGit{}
+	for name, c := range map[string]struct{ remote, base, commit string }{
+		"no base":          {"ssh://mesh-forge/o/r.git", "", sha},
+		"a short base":     {"ssh://mesh-forge/o/r.git", "abc123", sha},
+		"a branch as base": {"ssh://mesh-forge/o/r.git", "main", sha},
+		"a short commit":   {"ssh://mesh-forge/o/r.git", sha, "abc"},
+		"an https remote":  {"https://forge.example/o/r.git", sha, sha},
+	} {
+		_, err := MergeInto(context.Background(), f.run, "/w", c.remote, c.base, c.commit)
+		if err == nil {
+			t.Errorf("%s accepted", name)
+		}
+	}
+	if len(f.calls) != 0 {
+		t.Errorf("git ran for a refused merge: %v", f.calls)
+	}
+	g := &fakeGit{rule: func(l string) forgekey.Ran {
+		if strings.Contains(l, "rev-parse HEAD") {
+			return forgekey.Ran{Stdout: strings.Repeat("f", 40) + "\n"}
+		}
+		return forgekey.Ran{}
+	}}
+	_, err := MergeInto(context.Background(), g.run, "/w", "ssh://mesh-forge/o/r.git", strings.Repeat("a", 40), sha)
+	if err == nil || !strings.Contains(err.Error(), "not at the commit") || len(g.calls) != 1 {
+		t.Errorf("a workspace at another commit: %v after %d commands", err, len(g.calls))
+	}
+}
+
+// 1674/AC4: the merge is made with the check merge's identity and flags, hooks off, and fetches with no credential.
+func TestMergeIntoRunsTheCheckMergesCommands(t *testing.T) {
+	base := strings.Repeat("b", 40)
+	f := &fakeGit{rule: func(l string) forgekey.Ran {
+		switch {
+		case strings.HasSuffix(l, "rev-parse HEAD"):
+			return forgekey.Ran{Stdout: sha + "\n"}
+		case strings.Contains(l, "--is-shallow-repository"):
+			return forgekey.Ran{Stdout: "true\n"}
+		}
+		return forgekey.Ran{}
+	}}
+	if _, err := MergeInto(context.Background(), f.run, "/w", "ssh://mesh-forge/o/r.git", base, sha); err != nil {
+		t.Fatal(err)
+	}
+	all := strings.Join(f.calls, "\n")
+	for _, want := range []string{
+		pre + "fetch --no-tags --unshallow origin " + base,
+		pre + "checkout -q --detach " + base,
+		"user.name=mesh merge check", "user.email=merge-check@mesh.invalid", "commit.gpgsign=false", "core.hooksPath=/dev/null",
+		"merge --no-ff --no-edit --no-verify --quiet -m",
+		pre + "diff --name-only --no-renames " + base,
+	} {
+		if !strings.Contains(all, want) {
+			t.Errorf("the commands lack %q:\n%s", want, all)
+		}
+	}
+	for _, c := range f.calls {
+		if strings.Contains(c, "https://") || !strings.Contains(c, "credential.helper= ") {
+			t.Errorf("command %q carries a credential or https", c)
+		}
+	}
+}

go/buildstep/pack.go

@@ -0,0 +1,100 @@
+package buildstep
+
+import (
+	"archive/tar"
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// Pack tars and gzips a directory the way the build agent does, byte for byte, and answers the archive and its
+// digest, "sha256:" and the hex of the archive's bytes (issue 1479; novox/hq ADR 0405 §7, ADR 0453 §7). It is a
+// copy of mesh-controller's internal/builder/builder.go pack (origin/main 073ccc29, :1351-1425), which stays
+// where it is until the build agent goes: a build module's digest is compared with the build agent's for one
+// fingerprint, so the bytes must be equal.
+//
+// Deterministically: regular files only (a symlink or a device is refused), sorted relative paths with
+// slashes, each header carrying its name, permission bits and size and nothing else, the gzip default writer.
+func Pack(root string) (archive []byte, digest string, err error) {
+	raw, err := pack(root)
+	if err != nil {
+		return nil, "", err
+	}
+	sum := sha256.Sum256(raw)
+	return raw, "sha256:" + hex.EncodeToString(sum[:]), nil
+}
+
+func pack(root string) ([]byte, error) {
+	info, err := os.Stat(root)
+	if err != nil {
+		return nil, err
+	}
+	if !info.IsDir() {
+		return nil, fmt.Errorf("%s is not a directory", root)
+	}
+
+	var paths []string
+	err = filepath.Walk(root, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if info.IsDir() || !info.Mode().IsRegular() {
+			// Only files. A symlink or a device in an archive is refused by the host that unpacks
+			// it, so putting one in would build something that cannot be applied.
+			if !info.IsDir() && !info.Mode().IsRegular() {
+				return fmt.Errorf("%s is neither a file nor a directory, and an archive carries "+
+					"only those", path)
+			}
+			return nil
+		}
+		paths = append(paths, path)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	// filepath.Walk walks in lexical order; the sort is kept as the build agent keeps it, since an archive
+	// whose digest changes because the traversal did is a silent failure.
+	sort.Strings(paths)
+
+	var out bytes.Buffer
+	zipped := gzip.NewWriter(&out)
+	writer := tar.NewWriter(zipped)
+	for _, path := range paths {
+		body, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		relative, err := filepath.Rel(root, path)
+		if err != nil {
+			return nil, err
+		}
+		info, err := os.Stat(path)
+		if err != nil {
+			return nil, err
+		}
+		mode := int64(info.Mode().Perm())
+		if err := writer.WriteHeader(&tar.Header{
+			Name: filepath.ToSlash(relative), Mode: mode, Size: int64(len(body)),
+			Typeflag: tar.TypeReg,
+			// Everything else left at its zero value on purpose: no times, owners or names.
+		}); err != nil {
+			return nil, err
+		}
+		if _, err := writer.Write(body); err != nil {
+			return nil, err
+		}
+	}
+	if err := writer.Close(); err != nil {
+		return nil, err
+	}
+	if err := zipped.Close(); err != nil {
+		return nil, err
+	}
+	return out.Bytes(), nil
+}

go/buildstep/pack_test.go

@@ -0,0 +1,84 @@
+package buildstep
+
+import (
+	"bytes"
+	"compress/gzip"
+	"crypto/sha256"
+	"encoding/hex"
+	"io"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// fixture writes three files in two directories (modes 0644 and 0755).
+func fixture(t *testing.T) string {
+	t.Helper()
+	root := t.TempDir()
+	for _, f := range []struct {
+		p    string
+		mode os.FileMode
+		body string
+	}{{"a/x.txt", 0o644, "x\n"}, {"a/run.sh", 0o755, "#!/bin/sh\necho hi\n"}, {"b/c/y.txt", 0o644, "why\n"}} {
+		path := filepath.Join(root, f.p)
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(f.body), f.mode); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.Chmod(path, f.mode); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+// 1479/AC1: the tar stream inside the archive equals the bytes mesh-controller's pack makes for this tree.
+// testdata/pack-golden.tar is the uncompressed stream, made once by running mesh-controller
+// internal/builder/builder.go pack (origin/main 073ccc29, :1351-1425) on this fixture (above, modes set by chmod)
+// and gunzipping its archive. The gzip layer is not compared byte for byte, since compress/gzip's output differs
+// between Go versions; its header is checked to carry no name, no comment and no time.
+func TestPackEqualsTheBuildAgentsArchive(t *testing.T) {
+	golden, err := os.ReadFile("testdata/pack-golden.tar")
+	if err != nil {
+		t.Fatal(err)
+	}
+	archive, digest, err := Pack(fixture(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	zr, err := gzip.NewReader(bytes.NewReader(archive))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if zr.Name != "" || zr.Comment != "" || !zr.ModTime.IsZero() {
+		t.Errorf("gzip header = name %q, comment %q, time %v; want none", zr.Name, zr.Comment, zr.ModTime)
+	}
+	tarBytes, err := io.ReadAll(zr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !bytes.Equal(tarBytes, golden) {
+		t.Errorf("the tar stream is %d bytes, the build agent's %d, and they differ", len(tarBytes), len(golden))
+	}
+	sum := sha256.Sum256(archive)
+	if digest != "sha256:"+hex.EncodeToString(sum[:]) {
+		t.Errorf("digest = %s, not the sha256 of the archive", digest)
+	}
+}
+
+// 1479/AC2: touching every file's time changes nothing.
+func TestPackDigestIgnoresFileTimes(t *testing.T) {
+	root := fixture(t)
+	_, first, err := Pack(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	later := time.Now().Add(48 * time.Hour)
+	filepath.Walk(root, func(p string, _ os.FileInfo, _ error) error { return os.Chtimes(p, later, later) })
+	if _, second, err := Pack(root); err != nil || second != first {
+		t.Errorf("digests %s and %s (%v)", first, second, err)
+	}
+}

go/buildstep/pack_unix_test.go

@@ -0,0 +1,25 @@
+//go:build unix
+
+package buildstep
+
+import (
+	"path/filepath"
+	"strings"
+	"syscall"
+	"testing"
+)
+
+// 1479/AC3: anything but a file or a directory is refused, naming it. The rule of this repository is that no
+// test makes a symlink, so the non-regular entry is a named pipe: Pack refuses a symlink on the same branch
+// (filepath.Walk reports it by lstat as not regular).
+func TestPackRefusesAnEntryThatIsNotAFile(t *testing.T) {
+	root := fixture(t)
+	pipe := filepath.Join(root, "a", "pipe")
+	if err := syscall.Mkfifo(pipe, 0o644); err != nil {
+		t.Fatal(err)
+	}
+	_, _, err := Pack(root)
+	if err == nil || !strings.Contains(err.Error(), pipe) {
+		t.Errorf("Pack = %v, want a refusal naming %s", err, pipe)
+	}
+}

go/buildstep/refusal.go

@@ -0,0 +1,13 @@
+package buildstep
+
+// Refusal is a step that is not run on purpose, as against one that failed: the toolchain installed is not the
+// recipe's, the integration level's postgres major is not the one it is built for (novox/hq ADR 0469 §1, ADR 0470
+// §4; issue 1473). A step's run returns one and the runner ends the step refused with its text.
+type Refusal struct {
+	// Text is the reason, in words the operator reads.
+	Text string
+	// Want is the version the recipe asks for and Have the one found; either may be empty.
+	Want, Have string
+}
+
+func (r *Refusal) Error() string { return r.Text }

go/buildstep/step.go

@@ -0,0 +1,99 @@
+// Package buildstep is what both build modules share: the runner of a long step that answers a tool call at once
+// and ends on its key in the module's `steps` state (novox/hq ADR 0469 §2; issue 1471), the toolchain guard
+// (issue 1473) and the fetch of one commit over SSH (issue 1474).
+package buildstep
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strconv"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/delivery"
+)
+
+// Put writes one key of a state: stdio.State(delivery.StepsState).Put's shape (go/state.go).
+type Put func(key string, value any) (uint64, error)
+
+// EndAttempts and EndRetry bound how a step's end is written: a write that fails is tried again, since the end
+// is the only way the step's reader learns it is over.
+var (
+	EndAttempts = 5
+	EndRetry    = 2 * time.Second
+)
+
+var now = time.Now
+
+// NewID is a step id: the time in milliseconds in base 36 and six random hex digits, lower-case letters and
+// digits only, so it is one key token and differs between two steps of one node even in one millisecond.
+func NewID() string {
+	var b [3]byte
+	_, _ = rand.Read(b[:])
+	return strconv.FormatInt(now().UnixMilli(), 36) + hex.EncodeToString(b[:])
+}
+
+// Start begins a step of tool on node and answers its id at once: the key <node>.<id> holds state running when
+// Start returns. run is then called in a goroutine of its own, under ctx (the process's, not the tool call's: the
+// call is cut at 30 s, the step is not). When it returns, the key is written passed with run's result, failed with
+// the error's text, or refused when the error is a *Refusal; a panic in run ends the step failed, naming it, and
+// the process goes on. If the running write fails, nothing was started and Start answers the error.
+func Start(ctx context.Context, put Put, node, tool string, run func(ctx context.Context) (result any, err error)) (string, error) {
+	step := delivery.Step{ID: NewID(), Tool: tool, Node: node, State: delivery.StepRunning, Started: now().UTC()}
+	key, err := delivery.StepKey(node, step.ID)
+	if err != nil {
+		return "", err
+	}
+	if err := write(put, key, step); err != nil {
+		return "", fmt.Errorf("buildstep: writing the running step %s: %w", key, err)
+	}
+	go func() {
+		result, err := protect(ctx, run)
+		step.Ended = now().UTC()
+		switch ref := (*Refusal)(nil); {
+		case err == nil:
+			step.State = delivery.StepPassed
+			if result != nil {
+				raw, merr := json.Marshal(result)
+				if merr != nil {
+					step.State, step.Reason = delivery.StepFailed, "the result is not JSON: "+merr.Error()
+				} else {
+					step.Result = raw
+				}
+			}
+		case errors.As(err, &ref):
+			step.State, step.Reason = delivery.StepRefused, err.Error()
+		default:
+			step.State, step.Reason = delivery.StepFailed, err.Error()
+		}
+		for attempt := 1; ; attempt++ {
+			if werr := write(put, key, step); werr == nil || attempt >= EndAttempts {
+				return
+			}
+			time.Sleep(EndRetry)
+		}
+	}()
+	return step.ID, nil
+}
+
+// protect is run with a panic turned into the error that ends the step.
+func protect(ctx context.Context, run func(ctx context.Context) (any, error)) (result any, err error) {
+	defer func() {
+		if p := recover(); p != nil {
+			result, err = nil, fmt.Errorf("the step panicked: %v", p)
+		}
+	}()
+	return run(ctx)
+}
+
+func write(put Put, key string, step delivery.Step) error {
+	raw, err := delivery.EncodeStep(step)
+	if err != nil {
+		return err
+	}
+	_, err = put(key, json.RawMessage(raw))
+	return err
+}

go/buildstep/step_test.go

@@ -0,0 +1,154 @@
+package buildstep
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"sync"
+	"testing"
+	"time"
+
+	"git.novox.be/novox/mesh-sdk/go/delivery"
+)
+
+// keys is a steps state in memory: every value put, in order, per key, and a signal for each end.
+type keys struct {
+	mu    sync.Mutex
+	puts  map[string][]delivery.Step
+	ended chan string
+}
+
+func newKeys() *keys { return &keys{puts: map[string][]delivery.Step{}, ended: make(chan string, 16)} }
+
+func (k *keys) put(key string, value any) (uint64, error) {
+	step, err := delivery.DecodeStep(value.(json.RawMessage))
+	if err != nil {
+		return 0, err
+	}
+	k.mu.Lock()
+	k.puts[key] = append(k.puts[key], step)
+	n := uint64(len(k.puts[key]))
+	k.mu.Unlock()
+	if step.State != delivery.StepRunning {
+		k.ended <- key
+	}
+	return n, nil
+}
+
+func (k *keys) last(key string) delivery.Step {
+	k.mu.Lock()
+	defer k.mu.Unlock()
+	s := k.puts[key]
+	return s[len(s)-1]
+}
+
+func (k *keys) waitEnd(t *testing.T) string {
+	t.Helper()
+	select {
+	case key := <-k.ended:
+		return key
+	case <-time.After(3 * time.Second):
+		t.Fatal("the step never ended on its key")
+		return ""
+	}
+}
+
+// 1471/AC1: a run that blocks: Start answers an id within 100 ms and the key holds running.
+func TestStartAnswersAtOnceWithTheStepRunning(t *testing.T) {
+	k := newKeys()
+	release := make(chan struct{})
+	defer close(release)
+	began := time.Now()
+	id, err := Start(context.Background(), k.put, "ace", "fetch", func(ctx context.Context) (any, error) {
+		<-release
+		return nil, nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d := time.Since(began); d > 100*time.Millisecond {
+		t.Errorf("Start took %v", d)
+	}
+	s := k.last("ace." + id)
+	if s.State != delivery.StepRunning || s.Tool != "fetch" || s.Node != "ace" || s.ID != id || s.Started.IsZero() {
+		t.Errorf("step = %+v", s)
+	}
+}
+
+// 1471/AC2 and 1473/AC4: a result, an error and a Refusal end the step passed, failed and refused.
+func TestStepEndsPassedFailedOrRefusedOnItsKey(t *testing.T) {
+	for _, c := range []struct {
+		name   string
+		run    func(context.Context) (any, error)
+		state  string
+		reason string
+		result string
+	}{
+		{"result", func(context.Context) (any, error) { return map[string]string{"sha": "abc"}, nil }, delivery.StepPassed, "", `{"sha":"abc"}`},
+		{"error", func(context.Context) (any, error) { return nil, errors.New("exit 2") }, delivery.StepFailed, "exit 2", ""},
+		{"refusal", func(context.Context) (any, error) {
+			return nil, &Refusal{Text: "go 1.27.1 installed, the recipe builds with go 1.27.0", Want: "1.27.0", Have: "1.27.1"}
+		}, delivery.StepRefused, "go 1.27.1 installed, the recipe builds with go 1.27.0", ""},
+	} {
+		t.Run(c.name, func(t *testing.T) {
+			k := newKeys()
+			id, err := Start(context.Background(), k.put, "ace", "test", c.run)
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got := k.waitEnd(t); got != "ace."+id {
+				t.Fatalf("ended key %q", got)
+			}
+			s := k.last("ace." + id)
+			if s.State != c.state || s.Reason != c.reason || string(s.Result) != c.result || s.Ended.IsZero() {
+				t.Errorf("step = %+v", s)
+			}
+		})
+	}
+}
+
+// 1471/AC3: a panic in run ends the step failed, naming it, and the test process goes on.
+func TestAPanicEndsTheStepFailed(t *testing.T) {
+	k := newKeys()
+	id, _ := Start(context.Background(), k.put, "ace", "build", func(context.Context) (any, error) { panic("boom") })
+	k.waitEnd(t)
+	s := k.last("ace." + id)
+	if s.State != delivery.StepFailed || s.Reason != "the step panicked: boom" {
+		t.Errorf("step = %+v", s)
+	}
+}
+
+// 1471/AC5: ids made in one and the same millisecond differ, and each is one key token. The clock is fixed
+// while no step runs, so no goroutine reads it meanwhile.
+func TestTwoIDsInOneMillisecondDiffer(t *testing.T) {
+	was := now
+	defer func() { now = was }()
+	at := time.Date(2026, 10, 20, 12, 0, 0, 0, time.UTC)
+	now = func() time.Time { return at }
+	seen := map[string]bool{}
+	for i := 0; i < 50; i++ {
+		id := NewID()
+		if seen[id] {
+			t.Fatalf("id %q handed out twice", id)
+		}
+		seen[id] = true
+		if _, err := delivery.StepKey("ace", id); err != nil {
+			t.Errorf("id %q: %v", id, err)
+		}
+	}
+}
+
+// A first write that fails starts nothing.
+func TestStartAnswersTheErrorWhenTheRunningWriteFails(t *testing.T) {
+	ran := make(chan struct{}, 1)
+	_, err := Start(context.Background(), func(string, any) (uint64, error) { return 0, errors.New("no grant") }, "ace", "fetch",
+		func(context.Context) (any, error) { ran <- struct{}{}; return nil, nil })
+	if err == nil {
+		t.Fatal("Start answered no error")
+	}
+	select {
+	case <-ran:
+		t.Error("run was called")
+	case <-time.After(50 * time.Millisecond):
+	}
+}

go/buildstep/trees.go

@@ -0,0 +1,67 @@
+package buildstep
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+// ModuleTree is what a merge holds of one module directory: its tree id, the sha256 of its module.json and the sha256
+// of each lock file it has (go.sum, package-lock.json), from which the checker and the indexer take the module's inputs
+// (novox/hq ADR 0484 clause 3).
+type ModuleTree struct {
+	Tree     string            `json:"tree"`
+	Manifest string            `json:"manifest"`
+	Locks    map[string]string `json:"locks,omitempty"`
+}
+
+var lockFiles = []string{"go.sum", "package-lock.json"}
+
+// ModuleTrees are the trees, in commit, of every directory of the workspace dir that holds a module.json, by directory
+// (the repository's root is "."). The workspace is at commit, so the manifests and the lock files are read from it. env is
+// the environment git runs with (nil for none). Both build modules' fetch steps answer it for a merge.
+func ModuleTrees(ctx context.Context, run forgekey.Runner, env []string, dir, commit string) (map[string]ModuleTree, error) {
+	r := run(ctx, env, "git", "-C", dir, "ls-files", "--", "module.json", "*/module.json")
+	if r.Status != 0 || r.Err != "" {
+		return nil, fmt.Errorf("git ls-files: %s", firstLine(r.Err+" "+r.Stderr))
+	}
+	trees := map[string]ModuleTree{}
+	for _, l := range strings.Split(r.Stdout, "\n") {
+		if l = strings.TrimSpace(l); l == "" {
+			continue
+		}
+		mdir := filepath.ToSlash(filepath.Dir(l))
+		spec := commit + ":" + mdir
+		if mdir == "." {
+			spec = commit + "^{tree}"
+		}
+		t := run(ctx, env, "git", "-C", dir, "rev-parse", spec)
+		if t.Status != 0 || t.Err != "" {
+			return nil, fmt.Errorf("git rev-parse %s: %s", spec, firstLine(t.Err+" "+t.Stderr))
+		}
+		mt := ModuleTree{Tree: strings.TrimSpace(t.Stdout)}
+		raw, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(l)))
+		if err != nil {
+			return nil, err
+		}
+		mt.Manifest = sha256Hex(raw)
+		for _, lock := range lockFiles {
+			if raw, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(mdir), lock)); err == nil {
+				if mt.Locks == nil {
+					mt.Locks = map[string]string{}
+				}
+				mt.Locks[lock] = sha256Hex(raw)
+			}
+		}
+		trees[mdir] = mt
+	}
+	return trees, nil
+}
+
+func sha256Hex(b []byte) string { h := sha256.Sum256(b); return hex.EncodeToString(h[:]) }

go/buildstep/trees_test.go

@@ -0,0 +1,93 @@
+package buildstep
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/forgekey"
+)
+
+func hexOf(s string) string { h := sha256.Sum256([]byte(s)); return hex.EncodeToString(h[:]) }
+
+func writeTreeFile(t *testing.T, root, name, content string) {
+	t.Helper()
+	p := filepath.Join(root, filepath.FromSlash(name))
+	if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// ModuleTrees answers, for each directory holding a module.json (the root as "."), the tree id git gives, the sha256 of
+// module.json and of each lock file present, and reads them from the workspace.
+func TestModuleTreesAnswersTreeManifestAndLocksPerModuleDirectory(t *testing.T) {
+	root := t.TempDir()
+	writeTreeFile(t, root, "module.json", `{"root":1}`)
+	writeTreeFile(t, root, "go.sum", "rootsum")
+	writeTreeFile(t, root, "modules/a/module.json", `{"a":1}`)
+	writeTreeFile(t, root, "modules/a/go.sum", "asum")
+	writeTreeFile(t, root, "modules/a/package-lock.json", "alock")
+	writeTreeFile(t, root, "modules/b/module.json", `{"b":1}`)
+	merge := strings.Repeat("c", 40)
+	var calls []string
+	var envs [][]string
+	run := func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
+		calls = append(calls, name+" "+strings.Join(args[2:], " "))
+		envs = append(envs, env)
+		switch args[2] {
+		case "ls-files":
+			return forgekey.Ran{Stdout: "module.json\nmodules/a/module.json\nmodules/b/module.json\n"}
+		case "rev-parse":
+			return forgekey.Ran{Stdout: "tree-of-" + args[3] + "\n"}
+		}
+		return forgekey.Ran{Status: 1, Stderr: "unexpected"}
+	}
+	got, err := ModuleTrees(context.Background(), run, []string{"X=1"}, root, merge)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string]ModuleTree{
+		".":         {Tree: "tree-of-" + merge + "^{tree}", Manifest: hexOf(`{"root":1}`), Locks: map[string]string{"go.sum": hexOf("rootsum")}},
+		"modules/a": {Tree: "tree-of-" + merge + ":modules/a", Manifest: hexOf(`{"a":1}`), Locks: map[string]string{"go.sum": hexOf("asum"), "package-lock.json": hexOf("alock")}},
+		"modules/b": {Tree: "tree-of-" + merge + ":modules/b", Manifest: hexOf(`{"b":1}`)},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("trees = %+v\nwant %+v", got, want)
+	}
+	if got["modules/b"].Locks != nil {
+		t.Error("a module with no lock file carries a lock map")
+	}
+	for _, e := range envs {
+		if len(e) != 1 || e[0] != "X=1" {
+			t.Errorf("git ran with env %v, want the one given", e)
+		}
+	}
+}
+
+func TestModuleTreesFailsNamingTheGitCommandOrTheUnreadableManifest(t *testing.T) {
+	root := t.TempDir()
+	fail := func(on string) forgekey.Runner {
+		return func(ctx context.Context, env []string, name string, args ...string) forgekey.Ran {
+			if args[2] == on {
+				return forgekey.Ran{Status: 128, Stderr: "fatal: no\n"}
+			}
+			return forgekey.Ran{Stdout: "modules/a/module.json\n"}
+		}
+	}
+	for _, on := range []string{"ls-files", "rev-parse"} {
+		if _, err := ModuleTrees(context.Background(), fail(on), nil, root, sha); err == nil || !strings.Contains(err.Error(), on) || !strings.Contains(err.Error(), "fatal: no") {
+			t.Errorf("%s failing: %v", on, err)
+		}
+	}
+	if _, err := ModuleTrees(context.Background(), fail("none"), nil, root, sha); err == nil {
+		t.Error("a module.json that is not in the workspace was read")
+	}
+}

go/catalogue/a_service_process_test.go

@@ -0,0 +1,166 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// novox/hq issue 213 (ADR 0188 §1, §3): a module's own Go service is a bundle the host runs as a
+// process, not an image. Each test holds one thing that had to change in the composer for the
+// controller to be declared that way.
+
+const aServiceDigest = "sha256:dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
+
+// aServiceModule is the controller's shape in miniature: it answers tools of its own, its code is a
+// Go bundle a process runs as an account it declares, its secrets belong to that account, it
+// prepares its state, and its process replaces the container it used to run as.
+func aServiceModule(t *testing.T) Manifest {
+	t.Helper()
+	raw := `{
+	  "module": "svc", "version": "1", "tools": ["status"], "prepares": true,
+	  "own-secrets": {"store": "${dir:state}/store"},
+	  "secrets-owner": "svc",
+	  "resources": [
+	    {"id": "state", "type": "directory", "mode": "0700", "place": "mesh", "owner": "svc"},
+	    {"id": "service", "type": "process", "name": "svc", "artifact": "code",
+	     "run": ["./svc", "serve"], "user": "svc", "replaces": ["server"],
+	     "env": {"SVC_STORE_FILE": "${dir:state}/store", "SVC_STORE_PORT": "${seat:mesh-store:5432}"}},
+	    {"id": "account", "type": "user", "name": "svc", "shell": "/usr/bin/nologin", "home": "/var/lib/svc"}
+	  ],
+	  "build": {"artifacts": [{"name": "code", "kind": "bundle", "language": "go", "system": "arch",
+	    "from": "cmd/svc", "binary": "svc"}]}
+	}`
+	m, err := ParseManifest([]byte(raw))
+	if err != nil {
+		t.Fatalf("the service's manifest is refused: %v", err)
+	}
+	resolved, err := m.Resolve([]Built{{Name: "code", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "svc/code@" + aServiceDigest, Digest: aServiceDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return resolved
+}
+
+func composeTheService(t *testing.T, with Rendering) []map[string]any {
+	t.Helper()
+	with.Needed = map[string]map[string]string{"svc": {"store": "sealed-store"}}
+	with.ArtifactStore = "anchor.internal:5100"
+	out, err := Resolution{Node: "anchor", Modules: []Manifest{aServiceModule(t)}}.Declaration(with)
+	if err != nil {
+		t.Fatalf("the service does not compose: %v", err)
+	}
+	return out
+}
+
+func indexOf(out []map[string]any, id string) int {
+	for i, r := range out {
+		if r["id"] == id {
+			return i
+		}
+	}
+	return -1
+}
+
+// A module that declares tools has every bundle served by the node's runtime unless it says
+// otherwise — and the controller declares the verbs it answers as tools. Its service bundle is run
+// by its own process; launched a second time by the runtime it would be a second controller
+// pretending to be an MCP server.
+func TestABundleItsOwnProcessRunsIsNotServedByTheRuntime(t *testing.T) {
+	m := aServiceModule(t)
+	if len(m.Bundles) != 1 {
+		t.Fatalf("the service's bundle was not kept: %+v", m.Bundles)
+	}
+	if loads := m.Bundles[0].Loads; len(loads) != 0 {
+		t.Fatalf("the runtime would launch the service's own bundle as tools: %v", loads)
+	}
+	// And a bundle no resource runs still is served, as a module declaring tools always had it.
+	tools := Manifest{Module: "t", Version: "1", Tools: []string{"x"},
+		Build: &Build{Artifacts: []Artifact{{Name: "tools", Kind: ArtifactBundle, Language: "go",
+			System: "arch", From: "cmd/t"}}}}
+	resolved, err := tools.Resolve([]Built{{Name: "tools", Kind: ArtifactBundle,
+		Reference: ArtifactStoreScheme + "t/tools@" + aServiceDigest, Digest: aServiceDigest}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loads := resolved.Bundles[0].Loads; len(loads) != 1 || loads[0] != "t" {
+		t.Fatalf("a tools bundle nothing runs is no longer served: %v", loads)
+	}
+}
+
+// The account is created before anything is given to it. Its secrets are mesh-computed and so
+// placed before the module's own resources; given to a user the machine did not have yet, they were
+// refused on the first apply and the process started without them.
+func TestAModulesAccountComesBeforeWhatBelongsToIt(t *testing.T) {
+	out := composeTheService(t, Rendering{})
+	account, secret := indexOf(out, "svc.account"), indexOf(out, "svc."+NeedID("store"))
+	if account < 0 || secret < 0 {
+		t.Fatalf("the account or the secret is missing: %v", out)
+	}
+	if account > secret {
+		t.Fatalf("the secret owned by svc is written before svc exists: account at %d, secret at %d",
+			account, secret)
+	}
+	if owner := out[secret]["owner"]; owner != "svc" {
+		t.Errorf("the secret belongs to %v, not the account its process runs as", owner)
+	}
+}
+
+// The process is the module's program; its preparation is the same program asked to prepare, as a
+// step before it — with the same account and environment, and handing nothing over.
+func TestAProcessIsPreparedByItsOwnProgram(t *testing.T) {
+	out := composeTheService(t, Rendering{})
+	step, process := indexOf(out, "svc.service-prepare"), indexOf(out, "svc.service")
+	if step < 0 || process < 0 || step > process {
+		t.Fatalf("the preparation is not a step before the process (%d, %d): %v", step, process, out)
+	}
+	s := out[step]
+	if s["type"] != "process" || s["run-once"] != true || s["name"] != "svc-prepare" {
+		t.Errorf("the preparation is not a run-once process: %v", s)
+	}
+	if run, _ := json.Marshal(s["run"]); string(run) != `["./svc","prepare"]` {
+		t.Errorf("the preparation runs %s", run)
+	}
+	if s["user"] != "svc" || s["source"] != out[process]["source"] {
+		t.Errorf("the preparation does not run the same bundle as the same account: %v", s)
+	}
+	if env, _ := s["env"].(map[string]any); env["SVC_STORE_FILE"] == nil {
+		t.Errorf("the preparation is not given the process's environment: %v", s["env"])
+	}
+	if _, has := s["replaces"]; has {
+		t.Errorf("the preparation would hand over what the process replaces: %v", s)
+	}
+	if _, has := s["args"]; has {
+		t.Errorf("the preparation carries a container's args: %v", s)
+	}
+}
+
+// What the process replaces is named as the host recorded it, `<module>.<id>`; unprefixed, the host
+// matches nothing and removes the container first, as before.
+func TestWhatAProcessReplacesIsNamedAsTheHostRecordedIt(t *testing.T) {
+	out := composeTheService(t, Rendering{})
+	p := out[indexOf(out, "svc.service")]
+	if got, _ := json.Marshal(p["replaces"]); string(got) != `["svc.server"]` {
+		t.Fatalf("the process replaces %s", got)
+	}
+}
+
+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"]}`,
+		"a step":             `{"id":"p","type":"process","name":"p","run":["./p"],"run-once":true,"replaces":["old"]}`,
+		"something declared": `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["p"]}`,
+		"another module's":   `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["other.old"]}`,
+		"not a list":         `{"id":"p","type":"process","name":"p","run":["./p"],"replaces":"old"}`,
+	} {
+		raw := `{"module":"m","version":"1","resources":[` + resource + `]}`
+		if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), "replace") {
+			t.Errorf("replaces on %s was accepted: %v", what, err)
+		}
+	}
+	ok := `{"module":"m","version":"1","resources":[{"id":"p","type":"process","name":"p","run":["./p"],"replaces":["old"]}]}`
+	if _, err := ParseManifest([]byte(ok)); err != nil {
+		t.Errorf("a process replacing what its module no longer declares was refused: %v", err)
+	}
+}

go/catalogue/accesses_test.go

@@ -0,0 +1,108 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The fault 04-ISSUES/036 records: a media stack is several modules — a library server, the
+// acquisition managers, a download client — that must share directories on one machine. Written
+// as owned `directory` resources, two of them on one node are refused as rivalrous owners, which
+// is right in general and wrong here: sharing those directories is the whole point of the stack.
+//
+// Declared as accesses to an operator-owned path (novox/hq ADR 0051), they co-resolve. An access
+// is not a resource and never enters the duplicate-owner map, so this is the exact case the
+// resolver refuses above when the same path is owned — and does not, when it is merely accessed.
+func TestTwoModulesAccessingOnePathCoResolve(t *testing.T) {
+	a := mod("a", nil, nil, nil)
+	a.Accesses = []Access{{Path: "/services/media/downloads", Mode: AccessReadWrite}}
+	b := mod("b", nil, nil, nil)
+	b.Accesses = []Access{{Path: "/services/media/downloads", Mode: AccessRead}}
+
+	got, err := Resolve(shelf(a, b), []string{"a", "b"}, workstation(), World{})
+	if err != nil {
+		t.Fatalf("two modules accessing one operator-owned path were refused: %v", err)
+	}
+
+	// And each accessing module's grant reaches the machine as its own `access` resource, so the
+	// host can find the path present or refuse — both naming the one operator-owned path.
+	var accesses int
+	for _, r := range mustDeclare(t, got) {
+		if r["type"] == "access" && r["path"] == "/services/media/downloads" {
+			accesses++
+		}
+	}
+	if accesses != 2 {
+		t.Errorf("expected both modules' accesses in the declaration, got %d", accesses)
+	}
+}
+
+// The mirror of the case above, so the sharing vocabulary does not weaken the rule it sits beside:
+// two modules OWNING one path is still refused, exactly as before accesses existed.
+func TestTwoModulesOwningOnePathAreStillRefused(t *testing.T) {
+	a := mod("a", nil, nil, nil)
+	a.Resources = []map[string]any{
+		{"id": "lib", "type": "directory", "path": "/services/media/movies", "mode": "0755"}}
+	b := mod("b", nil, nil, nil)
+	b.Resources = []map[string]any{
+		{"id": "lib", "type": "directory", "path": "/services/media/movies", "mode": "0755"}}
+
+	_, err := Resolve(shelf(a, b), []string{"a", "b"}, workstation(), World{})
+	if err == nil {
+		t.Fatal("two modules owning the same directory were both assigned")
+	}
+	if !strings.Contains(err.Error(), "/services/media/movies") {
+		t.Errorf("the refusal does not name the path: %v", err)
+	}
+}
+
+// Shared data is the operator's, owned by no module (novox/hq ADR 0051). A module owning the path
+// another module was told to expect the operator to provide would create and chown it — and the
+// two intentions cannot both hold, so it is refused by name. This is what keeps the distinction
+// machine-checkable rather than a convention nobody enforces.
+func TestAModuleMayNotOwnWhatAnotherAccesses(t *testing.T) {
+	owns := mod("owns", nil, nil, nil)
+	owns.Resources = []map[string]any{
+		{"id": "lib", "type": "directory", "path": "/services/media/movies", "mode": "0755"}}
+	uses := mod("uses", nil, nil, nil)
+	uses.Accesses = []Access{{Path: "/services/media/movies", Mode: AccessRead}}
+
+	_, err := Resolve(shelf(owns, uses), []string{"owns", "uses"}, workstation(), World{})
+	if err == nil {
+		t.Fatal("a module owning a path another accesses was allowed")
+	}
+	if !strings.Contains(err.Error(), "/services/media/movies") ||
+		!strings.Contains(err.Error(), "the operator's") {
+		t.Errorf("the refusal does not explain the ownership conflict: %v", err)
+	}
+}
+
+// A manifest states an access's extent, the way a listening port states its source. An absolute
+// path and a mode of read or read-write; anything else is refused rather than acted on wrongly.
+func TestAnAccessIsValidated(t *testing.T) {
+	good := []byte(`{"module":"m","accesses":[{"path":"/services/media","mode":"read-write"}]}`)
+	if _, err := ParseManifest(good); err != nil {
+		t.Fatalf("a valid access was refused: %v", err)
+	}
+
+	// Mode is optional and narrows to read — the safe default, because the danger with an access
+	// is being given more than was meant, not less.
+	bare := []byte(`{"module":"m","accesses":[{"path":"/services/media"}]}`)
+	m, err := ParseManifest(bare)
+	if err != nil {
+		t.Fatalf("an access with no mode was refused: %v", err)
+	}
+	if m.Accesses[0].At() != AccessRead {
+		t.Errorf("an access with no mode is %q, want %q", m.Accesses[0].At(), AccessRead)
+	}
+
+	relative := []byte(`{"module":"m","accesses":[{"path":"services/media","mode":"read"}]}`)
+	if _, err := ParseManifest(relative); err == nil {
+		t.Error("a relative access path was accepted")
+	}
+
+	wrong := []byte(`{"module":"m","accesses":[{"path":"/services/media","mode":"append"}]}`)
+	if _, err := ParseManifest(wrong); err == nil {
+		t.Error("an access with an unknown mode was accepted")
+	}
+}

go/catalogue/adoption.go

@@ -0,0 +1,242 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// What an adopted node is declared in place of a filter (novox/hq ADR 0100).
+//
+// On an adopted node the firewall found on the machine stays in force: the mesh loads no table
+// that drops by default or holds an accept. What the mesh needs reachable is declared as
+// openings, which the host converges through the found firewall in its own terms; and the mesh
+// guards its own foundation ports itself, in a table that only refuses.
+
+// AdoptionPrefix is the id prefix of what the mesh declares of its own on an adopted node. It is
+// never a module's, so none of it is ever held as found.
+const AdoptionPrefix = "adoption."
+
+// Where an opening admits from, on the wire.
+const (
+	OpeningFromEverywhere = "everywhere"
+	OpeningFromMesh       = "mesh"
+)
+
+// The two paths a packet reaches a port by: received by the machine, or forwarded to a
+// container that publishes it.
+const (
+	PathIncoming  = "incoming"
+	PathForwarded = "forwarded"
+)
+
+// Guard resources: the refusal-only table, the unit that loads it, and that unit running.
+const (
+	GuardPath = "/etc/mesh/guard.nft"
+	GuardUnit = "mesh-guard.service"
+	// GuardUnitPath is where the unit is written.
+	GuardUnitPath = "/etc/systemd/system/" + GuardUnit
+)
+
+// GuardID, GuardUnitID and GuardRunningID are the guard's resource identities. The installer
+// raises the same three on an adopted genesis, so the first push finds them already there.
+func GuardID() string        { return AdoptionPrefix + "guard" }
+func GuardUnitID() string    { return AdoptionPrefix + "guard-unit" }
+func GuardRunningID() string { return AdoptionPrefix + "guard-running" }
+
+// GuardPackageID is the tool that loads the guard, declared first: a node joining adopted has
+// no filter module and may have no nft at all, and a table nothing can load guards nothing.
+func GuardPackageID() string { return AdoptionPrefix + "guard-package" }
+
+// GuardPackage is the package that carries nft.
+const GuardPackage = "nftables"
+
+// OpeningID is an opening's resource identity: its protocol, port and path say what it is.
+func OpeningID(protocol string, port int, path string) string {
+	return fmt.Sprintf("%sopening-%s-%d-%s", AdoptionPrefix, protocol, port, path)
+}
+
+// Openings are what the mesh needs reachable on an adopted node, from the same inputs as the
+// filter it would load were the node converged, each from where that filter would admit it.
+//
+// `rules` is Filtering's answer — every module's listens, the hub's port, the per-node exposure —
+// and `foundation` is the ports the mesh itself needs, from everywhere. A rule for this machine
+// only opens nothing. `published` maps a machine port a container publishes to the container's
+// port: a published port is forwarded, not received, so its opening names the forwarded path and
+// the port the packet is forwarded to.
+func Openings(rules []Rule, foundation []int, published map[string]map[int]int) []map[string]any {
+	type key struct {
+		protocol string
+		port     int
+	}
+	from := map[key]string{}
+	var order []key
+	widen := func(k key, f string) {
+		was, seen := from[k]
+		if !seen {
+			order = append(order, k)
+		}
+		if !seen || was != OpeningFromEverywhere {
+			from[k] = f
+		}
+	}
+	for _, rule := range rules {
+		switch rule.From {
+		case FromEverywhere:
+			widen(key{rule.Protocol, rule.Port}, OpeningFromEverywhere)
+		case FromMesh:
+			widen(key{rule.Protocol, rule.Port}, OpeningFromMesh)
+		case FromLocalNetwork:
+			// The private network's part only (novox/hq ADR 0340). An adopted node's found firewall
+			// stays, and it is what admits the machine's local network; an opening has no word for a
+			// local network, and widening it to everywhere would open the port to the internet.
+			widen(key{rule.Protocol, rule.Port}, OpeningFromMesh)
+		}
+	}
+	for _, port := range foundation {
+		widen(key{"tcp", port}, OpeningFromEverywhere)
+	}
+	sort.Slice(order, func(a, b int) bool {
+		if order[a].port != order[b].port {
+			return order[a].port < order[b].port
+		}
+		return order[a].protocol < order[b].protocol
+	})
+	out := make([]map[string]any, 0, len(order))
+	for _, k := range order {
+		opening := map[string]any{"type": "opening", "port": k.port, "protocol": k.protocol,
+			"from": from[k]}
+		if to, forwarded := published[k.protocol][k.port]; forwarded {
+			opening["id"] = OpeningID(k.protocol, k.port, PathForwarded)
+			opening["path"] = PathForwarded
+			opening["to"] = to
+		} else {
+			opening["id"] = OpeningID(k.protocol, k.port, PathIncoming)
+			opening["path"] = PathIncoming
+		}
+		out = append(out, opening)
+	}
+	return out
+}
+
+// Published is every port the given containers publish on the machine, by protocol and machine
+// port, mapped to the container's own port. A mapping bound to loopback is left out: nothing off
+// the machine reaches it, forwarded or not.
+func Published(resources []map[string]any) map[string]map[int]int {
+	out := map[string]map[int]int{}
+	for _, r := range resources {
+		if fmt.Sprint(r["type"]) != "container" {
+			continue
+		}
+		listed, _ := r["ports"].([]any)
+		for _, entry := range listed {
+			written := strings.TrimSpace(fmt.Sprint(entry))
+			protocol := "tcp"
+			if cut := strings.LastIndex(written, "/"); cut >= 0 {
+				protocol = written[cut+1:]
+			}
+			// Indexed from the end, so an IPv6 address's own colons never shift the ports.
+			outer, inner, address, ok := mapping(written)
+			if !ok {
+				continue
+			}
+			switch strings.Trim(address, "[]") {
+			case "127.0.0.1", "localhost", "::1":
+				continue
+			}
+			if out[protocol] == nil {
+				out[protocol] = map[int]int{}
+			}
+			out[protocol][outer] = inner
+		}
+	}
+	return out
+}
+
+// AsGuard renders the mesh's refusal-only table for the given machine ports.
+//
+// It passes everything by default and holds nothing but a refusal, so it cannot close anything
+// the machine serves; and it is the mesh's own table, so the found firewall reloading does not
+// touch it. It refuses only packets addressed to this machine, and the ports except from the
+// machine itself — its loopback and the container runtime's own networks — and from the private
+// network, known by the interface a packet arrives on and never by its source address. At
+// prerouting, ahead of the runtime's destination translation, so it matches the port the packet
+// was sent to; in the inet family, so both address families.
+//
+// **The machine's own interfaces are named, where the derived filter names address ranges.** The
+// filter accepts the container runtime's networks by CIDR; this excludes its bridges by name — lo,
+// docker0, the br-* a compose network gets, and the mesh's own mesh0. A runtime whose bridge is
+// named anything else (a podman or libvirt bridge, or a docker network created with a fixed name)
+// would have its containers' traffic to a guarded port refused, which reads as the port being
+// down. Names rather than addresses is deliberate: a source address can be claimed by whoever
+// sends the packet, and this table exists to refuse what the found firewall never sees. Widening
+// it means adding names here and in the installer's copy together, which the golden test holds to
+// one text.
+//
+// The same text the installer raises on an adopted genesis; a test holds both to it.
+func AsGuard(ports []int) string {
+	sorted := append([]int{}, ports...)
+	sort.Ints(sorted)
+	listed := make([]string, len(sorted))
+	for i, p := range sorted {
+		listed[i] = strconv.Itoa(p)
+	}
+	var b strings.Builder
+	b.WriteString("table inet mesh_guard {}\n")
+	b.WriteString("delete table inet mesh_guard\n")
+	b.WriteString("table inet mesh_guard {\n")
+	b.WriteString("\tchain prerouting {\n")
+	b.WriteString("\t\ttype filter hook prerouting priority raw; policy accept;\n")
+	// Only packets addressed to this machine: traffic it routes for others — a predecessor's hub,
+	// say — is never the guard's business (novox/hq ADR 0103).
+	fmt.Fprintf(&b, "\t\tfib daddr type local iifname != \"lo\" iifname != \"docker0\" "+
+		"iifname != \"br-*\" iifname != \"mesh0\" tcp dport { %s } drop\n",
+		strings.Join(listed, ", "))
+	b.WriteString("\t}\n")
+	b.WriteString("}\n")
+	return b.String()
+}
+
+// GuardUnitText is the unit that loads the guard. Stopping it deletes only its own table: never
+// a flush, which would take the container runtime's rules and the found firewall with it.
+func GuardUnitText() string {
+	return "[Unit]\n" +
+		"Description=The mesh's guard: refuses its own ports from outside (novox/hq ADR 0100)\n" +
+		// Early, before the network is up, and without the default dependencies that would
+		// order it after the network; stopped at shutdown like any unit.
+		"DefaultDependencies=no\n" +
+		"Wants=network-pre.target\n" +
+		"Before=network-pre.target shutdown.target\n" +
+		"Conflicts=shutdown.target\n" +
+		"\n" +
+		"[Service]\n" +
+		"Type=oneshot\n" +
+		"RemainAfterExit=yes\n" +
+		"ExecStart=nft -f " + GuardPath + "\n" +
+		"ExecReload=nft -f " + GuardPath + "\n" +
+		"ExecStop=nft delete table inet mesh_guard\n" +
+		"\n" +
+		"[Install]\n" +
+		"WantedBy=multi-user.target\n"
+}
+
+// GuardResources are the guard as four resources of the existing kinds: the tool that loads it,
+// the table, the unit, and the unit running — reloaded when the table changes, so the new table
+// replaces the old in one `nft -f` through the unit's ExecReload with no moment unguarded, and
+// restarted only when the unit itself changes. Nothing when there is nothing to guard: an empty
+// set is not a table nft loads.
+func GuardResources(ports []int) []map[string]any {
+	if len(ports) == 0 {
+		return nil
+	}
+	return []map[string]any{
+		{"id": GuardPackageID(), "type": "package", "package": GuardPackage},
+		{"id": GuardID(), "type": "file", "path": GuardPath, "content": AsGuard(ports),
+			"mode": "0644"},
+		{"id": GuardUnitID(), "type": "file", "path": GuardUnitPath, "content": GuardUnitText(),
+			"mode": "0644"},
+		{"id": GuardRunningID(), "type": "service", "unit": GuardUnit, "state": "running",
+			"boot": "enabled", "restart-on": []any{GuardUnitID()}, "reload-on": []any{GuardID()}},
+	}
+}

go/catalogue/adoption_test.go

@@ -0,0 +1,683 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"reflect"
+	"slices"
+	"strings"
+	"testing"
+)
+
+// novox/hq ADR 0100: on an adopted node the found firewall stays in force. The mesh declares
+// openings where it would have loaded a filter, and guards its own ports in a table that only
+// refuses.
+
+// hub is the private network's generator on the hub: it opens the hub's port from anywhere.
+type hub struct{}
+
+func (hub) Resources(string) ([]map[string]any, bool, error) {
+	return []map[string]any{{"id": "config", "type": "file", "path": "/etc/wireguard/mesh0.conf",
+		"content": "[Interface]\n"}}, true, nil
+}
+func (hub) Listens(string) ([]Listening, error) {
+	return []Listening{{Port: 51820, Protocol: "udp", From: FromEverywhere}}, nil
+}
+
+// anAdoptedAnchor is the control-node's set: the store, the bus, the registry, the private network,
+// a served module and the filter module.
+func anAdoptedAnchor() Resolution {
+	return Resolution{Node: "anchor", Modules: []Manifest{
+		{Module: "network", Computed: "overlay"},
+		{Module: "postgres", Guards: []int{5432},
+			Listens: []Listening{{Port: 5432, From: FromMesh}},
+			Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-store",
+				"ports": []any{"5432:5432"}}}},
+		{Module: "lavinmq", Guards: []int{15672},
+			Listens: []Listening{{Port: 5671, From: FromMesh}, {Port: 5672, From: FromMesh}},
+			Resources: []map[string]any{{"id": "server", "type": "container", "name": "mesh-broker",
+				"ports": []any{"5671:5671", "5672:5672", "127.0.0.1:15672:15672"}}}},
+		{Module: "distribution",
+			Listens: []Listening{{Port: 5000, From: FromMesh}},
+			Resources: []map[string]any{{"id": "store", "type": "container", "name": "registry",
+				"ports": []any{"5000"}}}},
+		{Module: "hello-web",
+			Listens: []Listening{{Port: 8080, From: FromEverywhere}},
+			Resources: []map[string]any{{"id": "server", "type": "container", "name": "hello-web",
+				"ports": []any{"8080"}}}},
+		{Module: "helper", Listens: []Listening{{Port: 9000, From: FromMachine}}},
+		{Module: "nftables", Filtering: &Filtering{Into: "/etc/nftables.conf"},
+			Resources: []map[string]any{{"id": "load", "type": "service", "unit": "mesh-filter.service",
+				"state": "running", "restart-on": []any{"filtering"}}}},
+	}}
+}
+
+func anchorRendering(adopted bool) Rendering {
+	return Rendering{
+		Generators: map[string]Generator{"overlay": hub{}},
+		Ports:      map[string]map[int]int{"distribution": {5000: 5000}, "hello-web": {8080: 20001}},
+		Settings: SettingsBy{"distribution": {{From: "node anchor",
+			Placement: map[string]any{ExposeSetting: map[string]any{"5000": FromEverywhere}}}}},
+		Mesh:       []string{"10.42.0.1"},
+		Foundation: []int{5671},
+		// What the machine reported faces outside, which every rule in the filter is written
+		// around (novox/hq ADR 0140).
+		OutwardLinks:    []string{"eth0"},
+		TunnelInterface: "mesh0",
+		Adopted:         adopted,
+		// Genesis takes the foundation's modules.
+		Taken: map[string]bool{"postgres": true, "lavinmq": true},
+	}
+}
+
+func byID(resources []map[string]any) map[string]map[string]any {
+	out := map[string]map[string]any{}
+	for _, r := range resources {
+		out[r["id"].(string)] = r
+	}
+	return out
+}
+
+func TestAnAdoptedNodeIsDeclaredOpeningsFromTheSameInputsAsTheFilter(t *testing.T) {
+	composed, err := anAdoptedAnchor().Compose(anchorRendering(true))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := byID(composed.Resources)
+	want := map[string]map[string]any{
+		// The hub's port, from anywhere, received.
+		"adoption.opening-udp-51820-incoming": {"port": 51820, "protocol": "udp",
+			"from": "everywhere", "path": "incoming"},
+		// The store's port from the private network only, and forwarded: a container publishes it.
+		"adoption.opening-tcp-5432-forwarded": {"port": 5432, "protocol": "tcp", "from": "mesh",
+			"path": "forwarded", "to": 5432},
+		// The bus from anywhere: a node enrols over it before it has a private address.
+		"adoption.opening-tcp-5671-forwarded": {"port": 5671, "protocol": "tcp",
+			"from": "everywhere", "path": "forwarded", "to": 5671},
+		"adoption.opening-tcp-5672-forwarded": {"port": 5672, "protocol": "tcp", "from": "mesh",
+			"path": "forwarded", "to": 5672},
+		// The registry from anywhere, by its node's exposure setting.
+		"adoption.opening-tcp-5000-forwarded": {"port": 5000, "protocol": "tcp",
+			"from": "everywhere", "path": "forwarded", "to": 5000},
+		// A published port names the machine port and the container port it is forwarded to.
+		"adoption.opening-tcp-20001-forwarded": {"port": 20001, "protocol": "tcp",
+			"from": "everywhere", "path": "forwarded", "to": 8080},
+	}
+	for id, fields := range want {
+		opening, ok := got[id]
+		if !ok {
+			t.Errorf("no %s among %v", id, keys(got))
+			continue
+		}
+		if opening["type"] != "opening" {
+			t.Errorf("%s is a %v", id, opening["type"])
+		}
+		for k, v := range fields {
+			if opening[k] != v {
+				t.Errorf("%s: %s is %v, want %v", id, k, opening[k], v)
+			}
+		}
+	}
+	for id := range got {
+		if strings.HasPrefix(id, "adoption.opening-") && want[id] == nil {
+			t.Errorf("an opening nothing asked for: %s", id)
+		}
+	}
+	// A port for this machine only opens nothing, and the management port is not opened at all.
+	for id := range got {
+		if strings.Contains(id, "-9000-") || strings.Contains(id, "-15672-") {
+			t.Errorf("%s is opened", id)
+		}
+	}
+
+	// And openings come first, in the order the machine applies them.
+	if !strings.HasPrefix(composed.Resources[0]["id"].(string), "adoption.opening-") {
+		t.Errorf("openings are not first: %v", composed.Resources[0]["id"])
+	}
+}
+
+func TestAnAdoptedNodeLoadsNoFilterOfTheMeshs(t *testing.T) {
+	composed, err := anAdoptedAnchor().Compose(anchorRendering(true))
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range composed.Resources {
+		if r["path"] == "/etc/nftables.conf" || strings.HasPrefix(r["id"].(string), "nftables.") {
+			t.Fatalf("an adopted node is declared the filter module's %v", r["id"])
+		}
+		if content, _ := r["content"].(string); strings.Contains(content, "policy drop") {
+			t.Fatalf("an adopted node is declared a table that drops by default: %v", r["id"])
+		}
+		// Nothing but refusals: the only accept in the guard is its policy.
+		if content, _ := r["content"].(string); r["id"] == GuardID() &&
+			strings.Count(content, "accept") != 1 {
+			t.Fatalf("the guard holds an accept:\n%s", content)
+		}
+	}
+	got := byID(composed.Resources)
+	guard := got[GuardID()]
+	if guard == nil || got[GuardUnitID()] == nil || got[GuardRunningID()] == nil {
+		t.Fatalf("no guard: %v", keys(got))
+	}
+	if guard["content"] != AsGuard([]int{5432, 5672, 15672}) {
+		t.Fatalf("the guard does not guard the store, the broker and its management port:\n%s",
+			guard["content"])
+	}
+	// The tool that loads it comes first, and the table after it: a node joining adopted has no
+	// filter module and may have no nft.
+	pkg, table := -1, -1
+	for i, r := range composed.Resources {
+		switch r["id"] {
+		case GuardPackageID():
+			pkg = i
+			if r["type"] != "package" || r["package"] != "nftables" {
+				t.Fatalf("the guard's package is %v", r)
+			}
+		case GuardID():
+			table = i
+		}
+	}
+	if pkg < 0 || pkg > table {
+		t.Fatalf("nftables is not declared before the guard's table (%d, %d)", pkg, table)
+	}
+	// A changed table is reloaded — one `nft -f`, atomic — never restarted, which would delete the
+	// table and leave the ports unguarded until it is loaded again. Only a changed unit restarts.
+	if !reflect.DeepEqual(got[GuardRunningID()]["reload-on"], []any{GuardID()}) ||
+		!reflect.DeepEqual(got[GuardRunningID()]["restart-on"], []any{GuardUnitID()}) {
+		t.Fatalf("the guard is not reloaded on its table and restarted on its unit: %v",
+			got[GuardRunningID()])
+	}
+	// Nothing of the mesh's own is anybody's to hold.
+	for id, module := range composed.Owner {
+		if strings.HasPrefix(id, AdoptionPrefix) {
+			t.Fatalf("%s is owned by %s", id, module)
+		}
+	}
+}
+
+func TestAConvergedNodeIsDeclaredItsFilterAndNoOpenings(t *testing.T) {
+	composed, err := anAdoptedAnchor().Compose(anchorRendering(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := byID(composed.Resources)
+	if got["nftables.filtering"] == nil || got["nftables.load"] == nil {
+		t.Fatalf("a converged node lost its filter: %v", keys(got))
+	}
+	for id := range got {
+		if strings.HasPrefix(id, AdoptionPrefix) {
+			t.Fatalf("a converged node is declared %s", id)
+		}
+	}
+	plain, err := anAdoptedAnchor().Declaration(anchorRendering(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	a, _ := json.Marshal(plain)
+	b, _ := json.Marshal(composed.Resources)
+	if string(a) != string(b) {
+		t.Fatal("Compose and Declaration disagree on a converged node")
+	}
+}
+
+// The table the installer raises and the controller declares, character for character.
+func TestTheGuardIsExactlyThisTable(t *testing.T) {
+	const golden = `table inet mesh_guard {}
+delete table inet mesh_guard
+table inet mesh_guard {
+	chain prerouting {
+		type filter hook prerouting priority raw; policy accept;
+		fib daddr type local iifname != "lo" iifname != "docker0" iifname != "br-*" iifname != "mesh0" tcp dport { 5432, 15672 } drop
+	}
+}
+`
+	if got := AsGuard([]int{15672, 5432}); got != golden {
+		t.Fatalf("the guard changed:\n%s", got)
+	}
+	const unit = `[Unit]
+Description=The mesh's guard: refuses its own ports from outside (novox/hq ADR 0100)
+DefaultDependencies=no
+Wants=network-pre.target
+Before=network-pre.target shutdown.target
+Conflicts=shutdown.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=nft -f /etc/mesh/guard.nft
+ExecReload=nft -f /etc/mesh/guard.nft
+ExecStop=nft delete table inet mesh_guard
+
+[Install]
+WantedBy=multi-user.target
+`
+	if got := GuardUnitText(); got != unit {
+		t.Fatalf("the guard's unit changed:\n%s", got)
+	}
+	if GuardResources(nil) != nil {
+		t.Fatal("a guard with nothing to guard is an empty set nft refuses to load")
+	}
+}
+
+func TestAGuardedPortMustBeAPort(t *testing.T) {
+	if _, err := ParseManifest([]byte(`{"module":"postgres","guards":[5432]}`)); err != nil {
+		t.Fatalf("guards is refused: %v", err)
+	}
+	if _, err := ParseManifest([]byte(`{"module":"postgres","guards":[0]}`)); err == nil {
+		t.Fatal("guarding port 0 was accepted")
+	}
+}
+
+func keys[V any](m map[string]V) []string {
+	return sortedKeys(m)
+}
+
+// novox/hq ADR 0100: the foundation's ports are the node's. Given 5433 for the store, every place
+// that uses the port reads it from there: the container, the filter, the openings, the guard.
+func TestAGivenPortIsUsedEverywhereThePortIs(t *testing.T) {
+	given := map[string]map[int]int{"postgres": {5432: 5433}, "lavinmq": {15672: 15673}}
+	for _, adopted := range []bool{true, false} {
+		with := anchorRendering(adopted)
+		with.Given = given
+		with.Ports["postgres"] = map[int]int{5432: 5433}
+		composed, err := anAdoptedAnchor().Compose(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		got := byID(composed.Resources)
+		if ports := got["postgres.server"]["ports"]; !reflect.DeepEqual(ports, []any{"5433:5432"}) {
+			t.Fatalf("the store's container publishes %v", ports)
+		}
+		if ports := got["lavinmq.server"]["ports"]; !reflect.DeepEqual(ports,
+			[]any{"5671:5671", "5672:5672", "127.0.0.1:15673:15672"}) {
+			t.Fatalf("the broker's container publishes %v", ports)
+		}
+		if !adopted {
+			filter, _ := got["nftables.filtering"]["content"].(string)
+			if !strings.Contains(filter, "tcp dport 5433 accept") || strings.Contains(filter, "5432") {
+				t.Fatalf("the filter does not use the given port:\n%s", filter)
+			}
+			continue
+		}
+		if o := got["adoption.opening-tcp-5433-forwarded"]; o == nil || o["to"] != 5432 {
+			t.Fatalf("no opening for the given port: %v", keys(got))
+		}
+		if guard := got[GuardID()]["content"]; guard != AsGuard([]int{5433, 5672, 15673}) {
+			t.Fatalf("the guard does not guard the given ports:\n%s", guard)
+		}
+	}
+}
+
+func TestAGivenPortIsTheNodesAndReachesSomething(t *testing.T) {
+	store := anAdoptedAnchor().Modules[1]
+	node := func(v any) []Layer {
+		return []Layer{{From: "anchor", Placement: map[string]any{PortsSetting: v}}}
+	}
+	if got, err := GivenPorts(store, node(map[string]any{"5432": float64(5433)})); err != nil ||
+		got[5432] != 5433 {
+		t.Fatalf("a node's given port was not read: %v %v", got, err)
+	}
+	if _, err := GivenPorts(store, []Layer{{From: MeshWideLayer,
+		Placement: map[string]any{PortsSetting: map[string]any{"5432": float64(5433)}}}}); err == nil {
+		t.Fatal("a port given for the whole mesh was accepted")
+	}
+	if _, err := GivenPorts(store, node(map[string]any{"6000": float64(6001)})); err == nil {
+		t.Fatal("a port the module neither listens on, publishes nor guards was given")
+	}
+	if _, err := GivenPorts(store, node(map[string]any{"5432": float64(70000)})); err == nil {
+		t.Fatal("a machine port that is not a port was given")
+	}
+	if _, err := GivenPorts(store, node(map[string]any{"5432": float64(22)})); err == nil {
+		t.Fatal("ssh's port was given")
+	}
+	broker := anAdoptedAnchor().Modules[2]
+	if _, err := GivenPorts(broker, node(map[string]any{"5671": float64(5700),
+		"5672": float64(5700)})); err == nil {
+		t.Fatal("one machine port was given for two of the module's ports")
+	}
+	if stray := UnusedSettings(store, node(map[string]any{"5432": float64(5433)})); len(stray) != 0 {
+		t.Fatalf("a given port is called stray: %v", stray)
+	}
+}
+
+// novox/hq ADR 0103: the guard is derived, and from taken modules only — every machine port a taken
+// module publishes that the filter admits from the private network only, and the ports its
+// manifest guards. A module assigned but not taken is not guarded: its port may still be the
+// predecessor's.
+func TestTheGuardIsDerivedFromTakenModulesOnly(t *testing.T) {
+	guardOf := func(with Rendering) string {
+		t.Helper()
+		composed, err := anAdoptedAnchor().Compose(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		content, _ := byID(composed.Resources)[GuardID()]["content"].(string)
+		return content
+	}
+
+	// The broker taken, the store not: the broker's plain port follows from its listens (from
+	// the mesh, published), its management port from its manifest; the store is not guarded, and
+	// neither is the bus, which the mesh needs from everywhere.
+	with := anchorRendering(true)
+	with.Taken = map[string]bool{"lavinmq": true}
+	if got := guardOf(with); got != AsGuard([]int{5672, 15672}) {
+		t.Fatalf("the guard is not the taken broker's ports:\n%s", got)
+	}
+
+	// A taken module publishing a port admitted from everywhere is not guarded; one admitted from
+	// the mesh is. The registry is exposed everywhere on this node, and hello-web listens from
+	// everywhere.
+	with.Taken = map[string]bool{"distribution": true, "hello-web": true}
+	if got := guardOf(with); got != "" {
+		t.Fatalf("a port admitted from everywhere is guarded:\n%s", got)
+	}
+	with.Settings = nil
+	if got := guardOf(with); got != AsGuard([]int{5000}) {
+		t.Fatalf("the registry, from the mesh only, is not guarded:\n%s", got)
+	}
+
+	// Nothing taken, nothing guarded — and no guard at all rather than an empty set.
+	with = anchorRendering(true)
+	with.Taken = nil
+	if got := guardOf(with); got != "" {
+		t.Fatalf("an untaken store is guarded:\n%s", got)
+	}
+
+	// A given port is followed: where the machine put it is what is refused.
+	with = anchorRendering(true)
+	with.Given = map[string]map[int]int{"lavinmq": {5672: 5682, 15672: 15673}}
+	with.Ports["lavinmq"] = map[int]int{5671: 5671, 5672: 5682}
+	if got := guardOf(with); got != AsGuard([]int{5432, 5682, 15673}) {
+		t.Fatalf("the guard does not follow the given ports:\n%s", got)
+	}
+}
+
+// A mapping bound to loopback is not published to anything off the machine — in either address
+// family — and an address's own colons never shift the ports.
+func TestPublishedLeavesOutLoopbackInBothFamilies(t *testing.T) {
+	got := Published([]map[string]any{{"type": "container", "ports": []any{
+		"127.0.0.1:15672:15672", "[::1]:8080:80", "localhost:9090:90",
+		"[::]:8443:443", "0.0.0.0:5000:5000", "5353:53/udp"}}})
+	want := map[string]map[int]int{"tcp": {8443: 443, 5000: 5000}, "udp": {5353: 53}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("published is %v, want %v", got, want)
+	}
+}
+
+// novox/hq ADR 0038: only a published port is the mesh's to move. A module that binds the machine
+// itself listens where its software was told to, so giving it a machine port is refused.
+func TestAGivenPortIsRefusedForAPortNoContainerPublishes(t *testing.T) {
+	onTheMachine := Manifest{Module: "daemon",
+		Listens: []Listening{{Port: 9000, From: FromMesh}}, Guards: []int{9000}}
+	layers := []Layer{{From: "node anchor",
+		Placement: map[string]any{PortsSetting: map[string]any{"9000": float64(9100)}}}}
+	_, err := GivenPorts(onTheMachine, layers)
+	if err == nil || !strings.Contains(err.Error(), "does not publish") {
+		t.Fatalf("a port no container publishes was given: %v", err)
+	}
+}
+
+// novox/hq ADR 0103: a guarded port this node is told to open to everyone is opened, not guarded.
+// An opening from everywhere beside a guard dropping it is one statement refusing the other.
+func TestAGuardedPortOpenedToEveryoneIsNotGuarded(t *testing.T) {
+	with := anchorRendering(true)
+	with.Settings["postgres"] = []Layer{{From: "node anchor",
+		Placement: map[string]any{ExposeSetting: map[string]any{"5432": FromEverywhere}}}}
+	composed, err := anAdoptedAnchor().Compose(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := byID(composed.Resources)
+	if o := got["adoption.opening-tcp-5432-forwarded"]; o == nil || o["from"] != OpeningFromEverywhere {
+		t.Fatalf("the store's port is not opened to everyone: %v", o)
+	}
+	if guard, _ := got[GuardID()]["content"].(string); guard != AsGuard([]int{5672, 15672}) {
+		t.Fatalf("a port opened to everyone is still guarded:\n%s", guard)
+	}
+}
+
+// A module that publishes its ssh port the long way — `2222:22`, because the machine's own daemon
+// holds 22 — and says it listens on the machine side of that mapping, which is what anything
+// reaching it dials.
+func aForge() Manifest {
+	return Manifest{Module: "forge",
+		Provides: []Offer{{Name: "git-over-ssh", Scope: ScopeMesh}},
+		Serves:   map[string]map[string]any{"git-over-ssh": {"port": 2222}},
+		Listens:  []Listening{{Port: 3000, From: FromMesh}, {Port: 2222, From: FromMesh}},
+		Resources: []map[string]any{{"id": "server", "type": "container", "name": "forge",
+			"ports": []any{"3000", "2222:22"}}}}
+}
+
+// portsAsThePlanWould is where this machine puts each of a module's ports, derived the way
+// cmd/mesh-controller/plan.go derives it: a given port first, looked up by the port the module
+// says it listens on, and otherwise wherever the manifest's own mapping already put it. Written
+// here because everything below — the filter, the openings, the guard, what a consumer is told —
+// reads that map, and a given port that the lookup does not find moves the container's mapping
+// and nothing else.
+//
+// It stands in for the plan only where the plan does not allocate: a port the manifest already
+// placed, or one a node was given. For a short form with no given port the real plan asks the
+// inventory for a machine port and may come back with one from the pool, which needs a store and
+// is what cmd/mesh-controller's own tests exercise. So an assertion here about such a port asserts
+// this helper, not the mesh; keep the assertions to the ports under test.
+func portsAsThePlanWould(m Manifest, given map[int]int) map[int]int {
+	out := map[int]int{}
+	for _, l := range m.Listens {
+		if at, is := given[l.Port]; is {
+			out[l.Port] = at
+			continue
+		}
+		at, _ := m.MachineSide(l.Port)
+		out[l.Port] = at
+	}
+	return out
+}
+
+// novox/hq ADR 0100 and 0038: the machine side of a long-form mapping is a port the module
+// publishes, so a node may move it — and a module may name a mapping by either end.
+func TestAGivenPortNamesEitherEndOfWhatTheModulePublishes(t *testing.T) {
+	forge := aForge()
+	node := func(v any) []Layer {
+		return []Layer{{From: "node anchor", Placement: map[string]any{PortsSetting: v}}}
+	}
+
+	// The machine side — the number this module says it listens on, and the one the predecessor
+	// had somewhere else. Answered under 2222, the end the module itself names, which is what
+	// every reader of this map asks for. One entry, not two: a second key for the same answer is
+	// an entry another mapping's reader could find instead.
+	given, err := GivenPorts(forge, node(map[string]any{"2222": float64(222)}))
+	if err != nil {
+		t.Fatalf("the machine side of a mapping cannot be given a port: %v", err)
+	}
+	if want := map[int]int{2222: 222}; !reflect.DeepEqual(given, want) {
+		t.Fatalf("the forge was given %v; the mapping it names is filed under %v", given, want)
+	}
+
+	// The container's own port names the same mapping and means the same thing — and is filed
+	// under the same name, because the module's name for it has not changed.
+	if inside, err := GivenPorts(forge, node(map[string]any{"22": float64(222)})); err != nil ||
+		!reflect.DeepEqual(inside, map[int]int{2222: 222}) {
+		t.Fatalf("the container's end of the mapping was given %v: %v", inside, err)
+	}
+
+	// A short form is published on the number it names, and is unchanged by any of this.
+	if short, err := GivenPorts(forge, node(map[string]any{"3000": float64(2999)})); err != nil ||
+		short[3000] != 2999 {
+		t.Fatalf("the short form was given %v: %v", short, err)
+	}
+
+	// A port no container publishes is still refused, in the same words.
+	if _, err := GivenPorts(forge, node(map[string]any{"9000": float64(9100)})); err == nil ||
+		!strings.Contains(err.Error(), "does not publish") {
+		t.Fatalf("a port the forge does not publish was given: %v", err)
+	}
+
+	// And the two ends of one mapping given two different numbers is one setting contradicting
+	// the other: the machine publishes it once.
+	if _, err := GivenPorts(forge, node(map[string]any{
+		"2222": float64(222), "22": float64(300)})); err == nil ||
+		!strings.Contains(err.Error(), "one mapping") {
+		t.Fatalf("the two ends of one mapping were given different ports: %v", err)
+	}
+	// Said at both ends with the same number, it is still said twice, and refused where every
+	// other repeated machine port is — as the inventory refuses it when the setting is stored,
+	// which is the layer that sees it first.
+	if _, err := GivenPorts(forge, node(map[string]any{
+		"2222": float64(222), "22": float64(222)})); err == nil ||
+		!strings.Contains(err.Error(), "to both its 22 and its 2222") {
+		t.Fatalf("one mapping given one machine port at both ends: %v", err)
+	}
+	// A number that names two different mappings names neither: which one to move is not said.
+	twice := aForge()
+	twice.Resources[0]["ports"] = []any{"22", "2222:22"}
+	if _, err := GivenPorts(twice, node(map[string]any{"22": float64(222)})); err == nil ||
+		!strings.Contains(err.Error(), "twice") {
+		t.Fatalf("a number naming two of the module's mappings was accepted: %v", err)
+	}
+
+	// And the same refusal when the number naming two mappings is not the one the setting used
+	// but the one the answer would be filed under. Here `80` is the module's own name for a
+	// mapping, and two mappings wear it; filing an answer there is one container's port standing
+	// where the other's is read, and both containers then publish it.
+	shared := Manifest{Module: "gallery",
+		Listens: []Listening{{Port: 80, From: FromMesh}},
+		Resources: []map[string]any{
+			{"id": "a", "type": "container", "name": "a", "ports": []any{"4001:80"}},
+			{"id": "b", "type": "container", "name": "b", "ports": []any{"4002:80"}}}}
+	if _, err := GivenPorts(shared, node(map[string]any{"4001": float64(1234)})); err == nil ||
+		!strings.Contains(err.Error(), "twice") {
+		t.Fatalf("two containers were put on one machine port: %v", err)
+	}
+
+	// A module whose mappings chain — one's machine side is another's container port — keeps them
+	// apart, because each is filed under the port the module names it by and neither name is
+	// shared. Given both, each moves on its own and neither overwrites the other.
+	chained := Manifest{Module: "chain",
+		Listens: []Listening{{Port: 80, From: FromMesh}, {Port: 9090, From: FromMesh}},
+		Resources: []map[string]any{{"id": "server", "type": "container", "name": "chain",
+			"ports": []any{"8080:80", "9090:8080"}}}}
+	both, err := GivenPorts(chained, node(map[string]any{"80": float64(1234), "9090": float64(5678)}))
+	if err != nil || !reflect.DeepEqual(both, map[int]int{80: 1234, 9090: 5678}) {
+		t.Fatalf("chained mappings were given %v: %v", both, err)
+	}
+	if moved := givenOuter("8080:80", both); moved != "1234:80" {
+		t.Fatalf("the first mapping moved to %q, and it was given 1234", moved)
+	}
+	if moved := givenOuter("9090:8080", both); moved != "5678:8080" {
+		t.Fatalf("the second mapping moved to %q, and it was given 5678", moved)
+	}
+}
+
+// And the number reaches everything derived from it. The fault this is written against moved the
+// container's mapping alone: the filter opened the port the software had left, the adopted node's
+// opening named it too, the guard refused it, and a consumer was sent to it.
+func TestAGivenMachineSideReachesTheFilterTheOpeningAndTheConsumer(t *testing.T) {
+	forge := aForge()
+	given, err := GivenPorts(forge, []Layer{{From: "node anchor",
+		Placement: map[string]any{PortsSetting: map[string]any{"2222": float64(222)}}}})
+	if err != nil {
+		t.Fatalf("the machine side of a mapping cannot be given a port: %v", err)
+	}
+	r := Resolution{Node: "anchor", Modules: []Manifest{forge}}
+	with := Rendering{
+		Ports:           map[string]map[int]int{"forge": portsAsThePlanWould(forge, given)},
+		Given:           map[string]map[int]int{"forge": given},
+		Mesh:            []string{"10.77.0.1"},
+		Adopted:         true,
+		OutwardLinks:    []string{"eth0"},
+		TunnelInterface: "mesh0",
+		Taken:           map[string]bool{"forge": true},
+	}
+
+	// What the runtime is handed: the machine's own port on the outside, the container's within.
+	composed, err := r.Compose(with)
+	if err != nil {
+		t.Fatalf("the forge does not compose: %v", err)
+	}
+	got := byID(composed.Resources)
+	if ports := got["forge.server"]["ports"]; !reflect.DeepEqual(ports, []any{"3000:3000", "222:22"}) {
+		t.Fatalf("the forge's container publishes %v", ports)
+	}
+
+	// What the filter would open, were the node converged.
+	rules, err := r.Rules(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var opened []int
+	for _, rule := range rules {
+		opened = append(opened, rule.Port)
+	}
+	// Only the moved port is asserted: the forge's other port is a short form the real plan would
+	// allocate rather than read off the manifest, so its number here is portsAsThePlanWould's and
+	// not the mesh's.
+	if !slices.Contains(opened, 222) || slices.Contains(opened, 2222) {
+		t.Fatalf("the filter opens %v, not where the machine puts the forge", opened)
+	}
+
+	// And what it is declared instead, adopted: an opening on the machine's port, naming the
+	// container's port on the forwarded path — a published port is forwarded, never received.
+	opening := got[OpeningID("tcp", 222, PathForwarded)]
+	if opening == nil || opening["to"] != 22 || opening["from"] != OpeningFromMesh {
+		t.Fatalf("no opening for the port this node gave the forge: %v", keys(got))
+	}
+	for id := range got {
+		if strings.HasPrefix(id, "adoption.opening-tcp-2222-") {
+			t.Errorf("an opening for the port the forge was moved off: %s", id)
+		}
+	}
+
+	// The guard refuses it where the machine put it, and nothing where it used to be.
+	guard, _ := got[GuardID()]["content"].(string)
+	if !strings.Contains(guard, "222") || strings.Contains(guard, "2222") {
+		t.Fatalf("the guard does not follow the given port:\n%s", guard)
+	}
+
+	// And a consumer is sent to the same number, which is read from what the module serves.
+	if told := ServedOn(forge, "git-over-ssh", with.Ports["forge"])["port"]; told != 222 {
+		t.Fatalf("a consumer is told the forge answers on %v", told)
+	}
+}
+
+// And the mapping itself moves under either name, because Rendering.Given is a map anybody
+// composing a declaration hands in: keyed by the machine side, which is what a module declaring
+// 2222 calls its port, only the outside moves and the container's own port stays as written.
+func TestAMappingIsMovedUnderEitherOfItsNames(t *testing.T) {
+	for _, c := range []struct {
+		written string
+		given   map[int]int
+		want    string
+	}{
+		{"2222:22", map[int]int{2222: 222}, "222:22"},
+		{"2222:22", map[int]int{22: 222}, "222:22"},
+		{"127.0.0.1:15672:15672/tcp", map[int]int{15672: 15673}, "127.0.0.1:15673:15672/tcp"},
+		{"2222:22", map[int]int{3000: 2999}, "2222:22"},
+		{"2222:22", nil, "2222:22"},
+	} {
+		if got := givenOuter(c.written, c.given); got != c.want {
+			t.Errorf("%s given %v is published as %s, want %s", c.written, c.given, got, c.want)
+		}
+	}
+}
+
+// The same on a node that was given nothing, which is where the derivation was never at fault:
+// a long-form mapping is published where the manifest put it, and an adopted node opens that port
+// on the forwarded path like any other. What broke it was the number reaching only the mapping.
+func TestALongFormPortIsOpenedWhereTheManifestPublishesIt(t *testing.T) {
+	forge := aForge()
+	r := Resolution{Node: "anchor", Modules: []Manifest{forge}}
+	composed, err := r.Compose(Rendering{
+		Ports:           map[string]map[int]int{"forge": portsAsThePlanWould(forge, nil)},
+		Mesh:            []string{"10.77.0.1"},
+		Adopted:         true,
+		OutwardLinks:    []string{"eth0"},
+		TunnelInterface: "mesh0",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := byID(composed.Resources)
+	opening := got[OpeningID("tcp", 2222, PathForwarded)]
+	if opening == nil || opening["to"] != 22 {
+		t.Fatalf("no opening for the forge's published ssh port: %v", keys(got))
+	}
+}

go/catalogue/agent_account_test.go

@@ -0,0 +1,119 @@
+package catalogue
+
+import (
+	"testing"
+)
+
+// The account agents run as (novox/hq ADR 0266): a module names it as a machine fact — the agent account
+// where the node names one, the operator's otherwise — and asks the node-engine to judge it never to become
+// root only where it is the agents' own.
+
+func TestTheAgentAccountFactFallsBackToTheOperatorAndIsNeverRootOnlyWhenItsOwn(t *testing.T) {
+	facts := machineFacts(Resolution{Node: "anchor", Account: "ops"}, nil, "")
+	if facts["agent-account"] != "ops" || facts["agent-home"] != "/home/ops" || facts["agent-root"] != "" {
+		t.Errorf("with no agent account named, agents run as the operator: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AccountHome: "/srv/ops"}, nil, "")
+	if facts["agent-home"] != "/srv/ops" {
+		t.Errorf("the operator's stated home is the agent's home when they are one account: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", Account: "ops", AgentAccount: "agent"}, nil, "")
+	if facts["agent-account"] != "agent" || facts["agent-home"] != "/home/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("a named agent account is the agents', never root: %v", facts)
+	}
+	if facts["account"] != "ops" {
+		t.Errorf("the operator account is still the operator's: %v", facts)
+	}
+	facts = machineFacts(Resolution{Node: "anchor", AgentAccount: "agent", AgentAccountHome: "/var/lib/agent"}, nil, "")
+	if facts["agent-home"] != "/var/lib/agent" || facts["agent-root"] != RootNever {
+		t.Errorf("an agent account with a stated home on a machine with no operator: %v", facts)
+	}
+	if _, has := machineFacts(Resolution{Node: "anchor"}, nil, "")["agent-account"]; has {
+		t.Error("a machine with no account at all names an agent account")
+	}
+}
+
+// The agent's module, in the shape the catalogue's declares it: the account, never root where it is its
+// own; its directory under that home, owned by it.
+const agentModule = `{"module": "agent", "version": "1", "resources": [
+  {"id": "account", "type": "user", "name": "${machine:agent-account}", "home": "${machine:agent-home}",
+   "root": "${machine:agent-root}"},
+  {"id": "home", "type": "directory", "path": "${machine:agent-home}/.agent", "mode": "0700",
+   "owner": "${machine:agent-account}"}
+]}`
+
+func TestTheAgentAccountIsDeclaredNeverRootOnlyToAnEngineThatJudgesIt(t *testing.T) {
+	m, err := ParseManifest([]byte(agentModule))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compose := func(r Resolution, with Rendering) (user, home map[string]any) {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{m}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return fileNamed(out, "agent.account"), fileNamed(out, "agent.home")
+	}
+
+	user, home := compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{JudgesRoot: true})
+	if user["name"] != "agent" || user[RootField] != RootNever || user["home"] != "/home/agent" {
+		t.Errorf("an engine that judges root is sent the agent account never to become root: %v", user)
+	}
+	if home["path"] != "/home/agent/.agent" || home["owner"] != "agent" {
+		t.Errorf("the agent's directory is under its own home, its own: %v", home)
+	}
+
+	user, _ = compose(Resolution{Account: "ops", AgentAccount: "agent", AgentAccountHome: "/srv/agent"}, Rendering{JudgesRoot: true})
+	if user["home"] != "/srv/agent" {
+		t.Errorf("an agent account named with a home of its own is made there: %v", user)
+	}
+
+	user, _ = compose(Resolution{Account: "ops", AgentAccount: "agent"}, Rendering{})
+	if _, sent := user[RootField]; sent || user["name"] != "agent" {
+		t.Errorf("an older engine, which parses strictly, is sent root: %v", user)
+	}
+
+	user, home = compose(Resolution{Account: "ops"}, Rendering{JudgesRoot: true})
+	if _, sent := user[RootField]; sent || user["name"] != "ops" {
+		t.Errorf("where agents run as the operator, root asserts nothing and is not sent: %v", user)
+	}
+	if home["path"] != "/home/ops/.agent" || home["owner"] != "ops" {
+		t.Errorf("with no agent account, the agent's directory is the operator's: %v", home)
+	}
+}
+
+func TestTheRuntimeIsToldTheAgentAccount(t *testing.T) {
+	with := Rendering{ArtifactStore: "anchor.internal:5101",
+		Needed: map[string]map[string]string{RuntimeModule: {"broker": "sealed-credential"}}}
+	envOf := func(r Resolution) map[string]string {
+		t.Helper()
+		r.Node, r.Modules = "anchor", []Manifest{aToolsModule(t, "nftables", "tools/index.js"), theRuntime(t)}
+		out, err := r.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		process := fileNamed(out, RuntimeModule+"."+RuntimeProcessID())
+		if process == nil {
+			t.Fatal("no runtime process was composed")
+		}
+		return process["env"].(map[string]string)
+	}
+	env := envOf(Resolution{Account: "ops", AgentAccount: "agent"})
+	if env[RuntimeAgentAccount] != "agent" || env[RuntimeAgentHome] != "/home/agent" || env[RuntimeOperatorAccount] != "ops" {
+		t.Errorf("the runtime is not told whom agents run as: %v", env)
+	}
+	env = envOf(Resolution{Account: "ops"})
+	if env[RuntimeAgentAccount] != "ops" || env[RuntimeAgentHome] != "/home/ops" {
+		t.Errorf("with no agent account, agents run as the operator: %v", env)
+	}
+	env = envOf(Resolution{})
+	if _, set := env[RuntimeAgentAccount]; set {
+		t.Errorf("a machine with no account names an agent account: %v", env)
+	}
+	if problems := bundleEnvProblems("x", Artifact{Name: "b", Kind: ArtifactBundle, Loads: []string{"x"},
+		Env: map[string]string{RuntimeAgentAccount: "me"}}); len(problems) == 0 {
+		t.Error("a bundle may tell the runtime whom agents run as")
+	}
+}

go/catalogue/amqp_is_not_a_provision_test.go

@@ -0,0 +1,50 @@
+package catalogue
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// **The word does not come back through a manifest** (novox/hq ADR 0131). A module that wants
+// messaging wants the mesh's bus, reached through the sdk and named by the `mesh-broker` seat. Naming
+// the old wire protocol asks for the one server being retired, so both directions are refused at the
+// parser — this is judged from the manifest alone, no store needed.
+
+func TestAManifestProvidingAmqpIsRefused(t *testing.T) {
+	raw := []byte(`{"module":"old-broker","version":"1","provides":[{"name":"amqp","scope":"mesh"}]}`)
+	_, err := ParseManifest(raw)
+	if err == nil || !strings.Contains(err.Error(), `provides "amqp", which is not a provision`) {
+		t.Fatalf("a module providing amqp was not refused, or not for the reason: %v", err)
+	}
+}
+
+func TestAManifestRequiringAmqpIsRefused(t *testing.T) {
+	raw := []byte(`{"module":"forwarder","version":"1","requires":["amqp"]}`)
+	_, err := ParseManifest(raw)
+	if err == nil || !strings.Contains(err.Error(), `requires "amqp", which is not a provision`) {
+		t.Fatalf("a module requiring amqp was not refused, or not for the reason: %v", err)
+	}
+}
+
+// And the catalogue (internal/beside) names it nowhere — the three modules that did are removed under
+// design 28 task 5.4, not converted.
+func TestNoCatalogueManifestNamesAmqp(t *testing.T) {
+	modules, err := filepath.Glob(filepath.Join(beside.Catalogue(t), "*", "module.json"))
+	if err != nil || len(modules) == 0 {
+		t.Fatalf("no manifests in the catalogue, so this proved nothing: %v", err)
+	}
+	for _, path := range modules {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if strings.Contains(string(raw), `"amqp"`) {
+			t.Errorf("%s names amqp, which is not a provision (novox/hq ADR 0131)",
+				filepath.Base(filepath.Dir(path)))
+		}
+	}
+}

go/catalogue/artifact_store_alias_test.go

@@ -0,0 +1,18 @@
+package catalogue
+
+import "testing"
+
+// A claim written before the rename still holds (novox/hq ADR 0122, ADR 0156): with the store's
+// aliases loaded, the former name resolves to the seat.
+func TestTheArtifactStoresFormerNameResolvesToIt(t *testing.T) {
+	was := aliases
+	t.Cleanup(func() { aliases = was })
+	UseAliases(map[string]string{"the-artifact-store": "mesh-artifact-store"})
+	seat, known := SeatNamed("the-artifact-store")
+	if !known || seat.Name != "mesh-artifact-store" || seat.Delivers != "artifact-store" {
+		t.Fatalf("the former name did not resolve: %+v %v", seat, known)
+	}
+	if _, known := SeatNamed("mesh-artifact-store"); !known {
+		t.Fatal("the seat is not in the set under its name")
+	}
+}

go/catalogue/artifact_store_seat_test.go

@@ -0,0 +1,38 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The artifact store's seat is one per mesh, read from the catalogue beside this checkout.
+//
+// **A second store anywhere is refused by name, not discovered as a consumer failure.** The seat
+// was node-scoped, so a second `distribution` on another machine resolved cleanly there — and a
+// node-scoped requirement with one candidate installs that candidate on the node, so anything that
+// required the store's presence beside it would have raised a fresh, empty store on the wrong
+// machine. Only afterwards did the mesh notice: `artifact-store` offered by two nodes, and every
+// consumer elsewhere refusing to choose. The claim says it first, where the second store is
+// assigned.
+func TestASecondArtifactStoreAnywhereIsRefusedByName(t *testing.T) {
+	store := catalogueManifest(t, "distribution")
+
+	// The first store resolves as it always has.
+	if _, err := Resolve(shelf(store), []string{"distribution"}, workstation(), World{}); err != nil {
+		t.Fatalf("the store alone does not resolve: %v", err)
+	}
+
+	// A second one, on any other machine, is refused — and the refusal names the seat.
+	elsewhere := World{Held: []Held{{Claim: "mesh-artifact-store", Scope: ScopeMesh,
+		Node: "anchor", Module: "distribution"}}}
+	other := workstation()
+	other.Name = "laptop"
+	_, err := Resolve(shelf(store), []string{"distribution"}, other, elsewhere)
+	if err == nil {
+		t.Fatal("a second store was accepted on another machine; it would offer artifact-store a " +
+			"second time and every consumer elsewhere would refuse to choose")
+	}
+	if !strings.Contains(err.Error(), "mesh-artifact-store") || !strings.Contains(err.Error(), "one per mesh") {
+		t.Fatalf("refused without naming the seat: %v", err)
+	}
+}

go/catalogue/artifacts.go

@@ -0,0 +1,145 @@
+package catalogue
+
+import (
+	"fmt"
+	"strings"
+)
+
+// What the mesh built, named by what it is rather than by where it was pushed.
+//
+// **An image is recorded by its digest and its path; the registry's address is a route to it**
+// (novox/hq 04-ISSUES/102). A build used to be recorded as `<registry>:<port>/<module>/<artifact>@sha256:…`
+// — the reference the builder pushed to, kept whole — and every declaration carried that literal.
+// Move the registry's port, or the registry, and every fresh pull of a mesh image fails: a new
+// node, a recreate after eviction. The digest is the identity; the address is the node's setting
+// for the module that serves the artifact store, and it is read from there when a reference is
+// composed, never written into a record.
+//
+// So a kept reference has a scheme of the mesh's own, named after the provision that answers it:
+//
+//	artifact-store://<module>/<artifact>@sha256:<hex>            an image
+//	artifact-store://<module>/<artifact>/blobs/sha256:<hex>      an archive
+//
+// No runtime knows the scheme. That is the point of it being one: a reference that leaks to a
+// machine uncomposed is refused by the runtime as malformed, in front of whoever sent it, rather
+// than pulled from a public registry that happens to have a repository by that name — which is
+// what an address-less `<module>/<artifact>@sha256:…` would be.
+
+// ArtifactStoreScheme marks a reference to something in the mesh's artifact store, kept without
+// the store's address.
+const ArtifactStoreScheme = ArtifactStoreProvision + "://"
+
+// Recorded is a reference as the mesh records it: the artifact store's address, if the builder wrote
+// one, taken off.
+//
+// For a reference the builder announced — one it pushed to the store — which is the only kind
+// this is called on. An image the builder named `<host>/<path>@sha256:…` is kept as its path; an
+// archive it named `http://<host>/v2/<path>/blobs/<digest>` likewise. A reference with no address
+// in it — an image id from a genesis build that had nowhere to publish, a package version — is
+// what it was.
+func Recorded(reference string) string {
+	if strings.HasPrefix(reference, ArtifactStoreScheme) {
+		return reference
+	}
+	if rest, isURL := strings.CutPrefix(reference, "http://"); isURL {
+		if _, path, ok := strings.Cut(rest, "/v2/"); ok && strings.Contains(path, "/blobs/") {
+			return ArtifactStoreScheme + path
+		}
+		return reference
+	}
+	host, path, ok := strings.Cut(reference, "/")
+	if !ok || !isRegistryHost(host) || !strings.Contains(path, "@sha256:") {
+		return reference
+	}
+	return ArtifactStoreScheme + path
+}
+
+// isRegistryHost is the runtime's own rule for reading the first component of a reference as a
+// registry rather than as a namespace: it has a dot or a port in it, or it is localhost.
+func isRegistryHost(component string) bool {
+	return component == "localhost" || strings.ContainsAny(component, ".:")
+}
+
+// InArtifactStore reports whether a reference is a kept one, and what it names there.
+func InArtifactStore(reference string) (path string, kept bool) {
+	return strings.CutPrefix(reference, ArtifactStoreScheme)
+}
+
+// Routed is a kept reference as a machine fetches it, through the artifact store at `address`
+// (host:port). A reference that is not a kept one is what it was.
+func Routed(reference, address string) string {
+	path, kept := InArtifactStore(reference)
+	if !kept {
+		return reference
+	}
+	if strings.Contains(path, "/blobs/") {
+		return "http://" + address + "/v2/" + path
+	}
+	return address + "/" + path
+}
+
+// Rerouted is a reference the mesh recorded, whichever way it was recorded, as a machine fetches
+// it now: a kept one composed with the store's address, and one recorded before references were
+// kept without their address — the builder's own `<host>/<path>@sha256:…` — re-routed to where
+// the store is now. Only for references that are the mesh's own: everything a build record
+// holds is, by construction.
+func Rerouted(reference, address string) string {
+	return Routed(Recorded(reference), address)
+}
+
+// artifactsInto composes the artifact store's address into a resource's `image` and `source`.
+//
+// **Composed here, at the last moment before a machine, and stored nowhere.** A kept reference is
+// routed through the store as this network reaches it now. A reference recorded with an address
+// before references were kept without one is re-routed the same way — but only when the mesh
+// built it (`with.Built` names every `<module>/<artifact>` it has), because a module may run an
+// image from a public registry under its own name and that one is exactly where it says.
+//
+// A kept reference with no store to route it through is refused: sent as it is, the runtime would
+// refuse the scheme on the machine, one push away from the reason.
+//
+// **What this does not reach: the images genesis pinned.** The installer builds the control plane
+// and the builder before the mesh exists, pushes them itself and pins their manifests to
+// `<registry>:<port>/mesh-controller@…` and `<registry>:<port>/mesh-builder@…` — single-segment
+// repositories with no build record, so `with.Built` does not name them and they are left as
+// written until each is rebuilt through the mesh, which records it by digest and path. Until then
+// a registry that moves strands exactly those two on a recreate, and the control plane's is the
+// one that cannot be repaired through the mesh. Rebuild both through `build` before moving the
+// store (novox/hq 04-ISSUES/102, finding F4).
+func artifactsInto(resource map[string]any, module string, with Rendering) error {
+	for _, key := range []string{"image", "source"} {
+		written, ok := resource[key].(string)
+		if !ok {
+			continue
+		}
+		if _, kept := InArtifactStore(written); kept {
+			if with.ArtifactStore == "" {
+				return fmt.Errorf(
+					"%s's %v names %s, which is in the mesh's artifact store, and this mesh has no "+
+						"artifact store on its network to fetch it from — nothing assigned offers "+
+						"%s, or the machine offering it is not on the private network",
+					module, resource["id"], written, ArtifactStoreProvision)
+			}
+			resource[key] = Routed(written, with.ArtifactStore)
+			continue
+		}
+		if with.ArtifactStore == "" {
+			continue
+		}
+		recorded := Recorded(written)
+		if recorded == written {
+			continue
+		}
+		path, _ := InArtifactStore(recorded)
+		repository := path
+		if at := strings.IndexAny(path, "@"); at >= 0 {
+			repository = path[:at]
+		} else if blobs := strings.Index(path, "/blobs/"); blobs >= 0 {
+			repository = path[:blobs]
+		}
+		if with.Built[repository] {
+			resource[key] = Routed(recorded, with.ArtifactStore)
+		}
+	}
+	return nil
+}

go/catalogue/artifacts_test.go

@@ -0,0 +1,137 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A build is recorded by what it is; where it is pushed is composed where it is used (novox/hq
+// 04-ISSUES/102).
+
+var digest = "sha256:" + strings.Repeat("d", 64)
+
+func TestAReferenceIsRecordedWithoutTheStoresAddress(t *testing.T) {
+	cases := map[string]string{
+		"anchor.internal:5100/gitea/server@" + digest:                 ArtifactStoreScheme + "gitea/server@" + digest,
+		"localhost:5000/gitea/server@" + digest:                       ArtifactStoreScheme + "gitea/server@" + digest,
+		"http://anchor.internal:5100/v2/gitea/config/blobs/" + digest: ArtifactStoreScheme + "gitea/config/blobs/" + digest,
+		ArtifactStoreScheme + "gitea/server@" + digest:                ArtifactStoreScheme + "gitea/server@" + digest,
+		digest:                  digest,
+		"@novox/sdk@1.2.3":      "@novox/sdk@1.2.3",
+		"gitea/gitea@" + digest: "gitea/gitea@" + digest,
+		"https://registry.example/v2/gitea/config/blobs/" + digest: "https://registry.example/v2/gitea/config/blobs/" + digest,
+	}
+	for announced, want := range cases {
+		if got := Recorded(announced); got != want {
+			t.Errorf("Recorded(%q) = %q, want %q", announced, got, want)
+		}
+	}
+}
+
+func TestARecordedReferenceIsRoutedThroughTheStoreAsItIsNow(t *testing.T) {
+	if got := Routed(ArtifactStoreScheme+"gitea/server@"+digest, "anchor.internal:5101"); got != "anchor.internal:5101/gitea/server@"+digest {
+		t.Errorf("an image is fetched as %q", got)
+	}
+	if got := Routed(ArtifactStoreScheme+"gitea/config/blobs/"+digest, "anchor.internal:5101"); got != "http://anchor.internal:5101/v2/gitea/config/blobs/"+digest {
+		t.Errorf("an archive is fetched as %q", got)
+	}
+	if got := Routed("gitea/gitea@"+digest, "anchor.internal:5101"); got != "gitea/gitea@"+digest {
+		t.Errorf("a reference that is not the store's was routed: %q", got)
+	}
+	// One recorded before references were kept without their address follows the store too.
+	if got := Rerouted("anchor.internal:5100/gitea/server@"+digest, "anchor.internal:5101"); got != "anchor.internal:5101/gitea/server@"+digest {
+		t.Errorf("a reference recorded with the old address stays there: %q", got)
+	}
+}
+
+// **The address is composed into a declaration, and the record never carries it.**
+func TestAnImageTheMeshBuiltIsRoutedThroughTheStoreWhenDeclared(t *testing.T) {
+	m := Manifest{Module: "gitea", Version: "1", Resources: []map[string]any{
+		{"id": "server", "type": "container", "name": "mesh-gitea", "artifact": "server"},
+		{"id": "config", "type": "archive", "path": "/etc/gitea", "artifact": "config"},
+		{"id": "cache", "type": "container", "name": "mesh-gitea-cache", "image": "valkey/valkey@" + digest},
+	}, Build: &Build{Artifacts: []Artifact{
+		{Name: "server", Kind: ArtifactImage, From: "Dockerfile"},
+		{Name: "config", Kind: ArtifactArchive, From: "config"},
+	}}}
+	resolved, err := m.Resolve([]Built{
+		{Name: "server", Kind: ArtifactImage, Reference: ArtifactStoreScheme + "gitea/server@" + digest},
+		{Name: "config", Kind: ArtifactArchive, Reference: ArtifactStoreScheme + "gitea/config/blobs/" + digest, Digest: digest},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := Resolution{Node: "anchor", Modules: []Manifest{resolved}}
+
+	out, err := r.Declaration(Rendering{ArtifactStore: "anchor.internal:5101"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fileNamed(out, "gitea.server")["image"]; got != "anchor.internal:5101/gitea/server@"+digest {
+		t.Errorf("the image the mesh built is fetched as %v", got)
+	}
+	if got := fileNamed(out, "gitea.config")["source"]; got != "http://anchor.internal:5101/v2/gitea/config/blobs/"+digest {
+		t.Errorf("the archive the mesh built is fetched from %v", got)
+	}
+	if got := fileNamed(out, "gitea.cache")["image"]; got != "valkey/valkey@"+digest {
+		t.Errorf("an image from a public registry was routed through the store: %v", got)
+	}
+	// The manifest the mesh holds still says what it is, not where it was fetched from.
+	if got := resolved.Resources[0]["image"]; got != ArtifactStoreScheme+"gitea/server@"+digest {
+		t.Errorf("composing wrote the address into the catalogue's copy: %v", got)
+	}
+
+	// And the store moves: the same record, another address, without a rebuild.
+	out, err = r.Declaration(Rendering{ArtifactStore: "laptop.internal:5000"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fileNamed(out, "gitea.server")["image"]; got != "laptop.internal:5000/gitea/server@"+digest {
+		t.Errorf("after the store moved, the image is still fetched as %v", got)
+	}
+}
+
+func TestAnImageInTheStoreWithNoStoreToFetchItFromIsRefused(t *testing.T) {
+	m := Manifest{Module: "gitea", Version: "1", Resources: []map[string]any{
+		{"id": "server", "type": "container", "name": "mesh-gitea",
+			"image": ArtifactStoreScheme + "gitea/server@" + digest},
+	}}
+	_, err := Resolution{Node: "anchor", Modules: []Manifest{m}}.Declaration(Rendering{})
+	if err == nil || !strings.Contains(err.Error(), "no artifact store") {
+		t.Fatalf("a reference nothing can fetch was sent to a machine: %v", err)
+	}
+}
+
+// **A reference recorded with an address before this follows the store too** — when the mesh
+// built it. A module running an image straight from a public registry under its own name is left
+// exactly where it says: `quay.io/keycloak/keycloak` is not the mesh's, whatever it is called.
+func TestAReferenceRecordedWithAnAddressFollowsTheStoreWhenTheMeshBuiltIt(t *testing.T) {
+	m := Manifest{Module: "keycloak", Version: "1", Resources: []map[string]any{
+		{"id": "server", "type": "container", "name": "mesh-keycloak",
+			"image": "anchor.internal:5100/keycloak/server@" + digest},
+		{"id": "upstream", "type": "container", "name": "mesh-keycloak-upstream",
+			"image": "quay.io/keycloak/keycloak@" + digest},
+	}}
+	r := Resolution{Node: "anchor", Modules: []Manifest{m}}
+	out, err := r.Declaration(Rendering{
+		ArtifactStore: "anchor.internal:5101",
+		Built:         map[string]bool{"keycloak/server": true},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fileNamed(out, "keycloak.server")["image"]; got != "anchor.internal:5101/keycloak/server@"+digest {
+		t.Errorf("an image the mesh built, recorded with the old address, is fetched as %v", got)
+	}
+	if got := fileNamed(out, "keycloak.upstream")["image"]; got != "quay.io/keycloak/keycloak@"+digest {
+		t.Errorf("a public image was re-routed through the store: %v", got)
+	}
+	// Nothing known to be built: nothing re-routed, nothing refused.
+	out, err = r.Declaration(Rendering{ArtifactStore: "anchor.internal:5101"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fileNamed(out, "keycloak.server")["image"]; got != "anchor.internal:5100/keycloak/server@"+digest {
+		t.Errorf("with no build record, a reference was rewritten: %v", got)
+	}
+}

go/catalogue/backup_placement.go

@@ -0,0 +1,53 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+)
+
+// What the machine's modules back up is placement (design 57 L3, issue 794). The holder of node-backup names it as
+// `${backup:lines}` (what to run and which paths to keep) and `${backup:data}` (every item with its class and
+// protection): the text `${contribution:node-backup:backup}` and `${contribution:node-backup:data}` render, from the
+// same function, derived from each placed module's declared data (novox/hq ADR 0233). A handed holder has the text in
+// its plan's placement for its client to fill; one not handed has the controller fill it where it stands.
+
+// BackupNamespace is the placeholder kind of the machine's backup lines and data.
+const BackupNamespace = "backup"
+
+// ofBackup is where a holder places them: ${backup:<key>}. Loose inside the braces, so a misspelt key is found and
+// refused rather than written out as text.
+var ofBackup = regexp.MustCompile(`\$\{backup:([^}]*)\}`)
+
+// backupKinds is the contribution kind each key of the backup placement renders.
+var backupKinds = map[string]string{"lines": BackupKindBackup, "data": BackupKindData}
+
+// backupPlacer is the machine's modules the backup placement is composed over, as the old contributions are.
+type backupPlacer struct {
+	modules  []Manifest
+	with     Rendering
+	facts    map[string]string
+	caps     map[string]bool
+	unplaced *[]string
+}
+
+// placed is the text of one key for a holder, or what is wrong with naming it.
+func (b backupPlacer) placed(holder Manifest, key string, item bool) (string, string) {
+	kind, known := backupKinds[key]
+	switch {
+	case item:
+		return "", "an item is kept per item; the machine's backup lines are placed only in a file"
+	case !known:
+		return "", fmt.Sprintf("the backup placement has `lines` and `data`, not %q", key)
+	case !holder.ClaimsSeat(BackupSeat):
+		return "", fmt.Sprintf("%s does not claim %s; the machine's backup lines are placed by its holder alone "+
+			"(novox/hq ADR 0212)", holder.Module, BackupSeat)
+	}
+	text, left, err := seatContributions(b.modules, holder, BackupSeat+":"+kind, b.with, b.facts, b.caps)
+	if b.unplaced != nil {
+		*b.unplaced = append(*b.unplaced, left...)
+	}
+	if err != nil {
+		return "", err.Error()
+	}
+	return text, ""
+}

go/catalogue/backup_placement_test.go

@@ -0,0 +1,126 @@
+package catalogue
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// A machine's backup lines are placement (design 57 L3, issue 794): the holder of node-backup names them as
+// `${backup:lines}` and `${backup:data}`, which a handed holder has its client fill from the plan and an unhanded
+// one has the controller fill as it fills `${contribution:node-backup:backup}` and `${...:data}`: the same text.
+
+const (
+	oldBackupText   = "# lines\n${contribution:node-backup:backup}"
+	oldDataText     = "# data\n${contribution:node-backup:data}"
+	placedBackupTxt = "# lines\n${backup:lines}"
+	placedDataTxt   = "# data\n${backup:data}"
+	backupHolder    = `{"module":"restic","version":"1","moved":true,"claims":[{"name":"node-backup","scope":"node"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"declared","type":"file","path":"/etc/backups.conf","template":"files/backups"},
+               {"id":"data-declared","type":"file","path":"/etc/data.conf","template":"files/data"}]}`
+)
+
+func dataModule(name string) string {
+	return `{"module":"` + name + `","version":"1","resources":[{"id":"d","type":"directory","mode":"0700"}],
+  "data":{"own":[{"id":"d","path":"${dir:d}","class":"irreplaceable","why":"the ` + name + ` data"}]}}`
+}
+
+// backupsOn is a machine of a holder whose files say these texts and the modules that declare data.
+func backupsOn(t *testing.T, lines, data string, modules ...string) Resolution {
+	t.Helper()
+	all := []Manifest{held(t, backupHolder, builtWith("restic", map[string]string{"backups": lines, "data": data}))}
+	names := []string{"restic"}
+	for _, name := range modules {
+		all = append(all, mustParse(t, dataModule(name)))
+		names = append(names, name)
+	}
+	r, err := Resolve(shelf(all...), names, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account = "op"
+	return r
+}
+
+var backupModules = []string{"alpha", "beta", "gamma"}
+
+// gammaLeftOut is a machine whose gamma does not place: its lines are kept, best effort.
+func gammaLeftOut(with Rendering) Rendering {
+	with.NotPlaced = map[string]string{"gamma": "its placement setting does not read"}
+	return with
+}
+
+func TestTheBackupPlacementIsTheTextTheOldPlaceholdersRender(t *testing.T) {
+	// The old form is an unmoved holder: its placeholders are the controller's alone.
+	oldHolder := strings.Replace(backupHolder, `"moved":true,`, "", 1)
+	all := []Manifest{held(t, oldHolder, builtWith("restic", map[string]string{"backups": oldBackupText, "data": oldDataText}))}
+	for _, name := range backupModules {
+		all = append(all, mustParse(t, dataModule(name)))
+	}
+	old, err := Resolve(shelf(all...), append([]string{"restic"}, backupModules...), workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	old.Account = "op"
+	wantLines, wantData := fileOf(t, old, gammaLeftOut(Rendering{}), "restic.declared"), fileOf(t, old, gammaLeftOut(Rendering{}), "restic.data-declared")
+	if !strings.Contains(wantLines, "# alpha\npath ") || !strings.Contains(wantLines, "# gamma\n") || !strings.Contains(wantData, "item d") {
+		t.Fatalf("the old form renders\n%s\n%s", wantLines, wantData)
+	}
+	moved := backupsOn(t, placedBackupTxt, placedDataTxt, backupModules...)
+	// Not handed: the controller fills the new placeholders with the old text.
+	if got := fileOf(t, moved, gammaLeftOut(Rendering{}), "restic.declared"); got != wantLines {
+		t.Errorf("not handed, the lines are\n%s\nwant\n%s", got, wantLines)
+	}
+	if got := fileOf(t, moved, gammaLeftOut(Rendering{}), "restic.data-declared"); got != wantData {
+		t.Errorf("not handed, the data is\n%s\nwant\n%s", got, wantData)
+	}
+	// Handed: the plan carries the same text as placement, and the files are the client's.
+	c, _ := composeWith(t, moved, gammaLeftOut(handingTo("store:5000")))
+	p := c.Plans["restic"].Placement
+	if got := "# lines\n" + p["backup:lines"]; got != wantLines {
+		t.Errorf("handed, the plan's lines are\n%s\nwant\n%s", got, wantLines)
+	}
+	if got := "# data\n" + p["backup:data"]; got != wantData {
+		t.Errorf("handed, the plan's data is\n%s\nwant\n%s", got, wantData)
+	}
+	if len(p) != 2 {
+		t.Errorf("the plan's placement is %v", p)
+	}
+}
+
+func TestAModuleAddedOrTakenAwayChangesTheBackupPlan(t *testing.T) {
+	plan := func(modules ...string) map[string]string {
+		c, _ := composeWith(t, backupsOn(t, placedBackupTxt, placedDataTxt, modules...), handingTo("store:5000"))
+		return c.Plans["restic"].Placement
+	}
+	two, three := plan("alpha", "beta"), plan("alpha", "beta", "gamma")
+	if reflect.DeepEqual(two, three) || strings.Contains(two["backup:lines"], "gamma") || !strings.Contains(three["backup:lines"], "# gamma\n") {
+		t.Errorf("two modules give %v, three give %v", two, three)
+	}
+}
+
+func TestAnUnknownBackupKeyIsRefused(t *testing.T) {
+	r := backupsOn(t, "${backup:rows}", placedDataTxt, backupModules...)
+	if _, err := r.Compose(handingTo("store:5000")); err == nil || !strings.Contains(err.Error(), "backup:rows") {
+		t.Errorf("handed, an unknown key is %v", err)
+	}
+	if _, err := r.Declaration(Rendering{}); err == nil || !strings.Contains(err.Error(), "backup:rows") {
+		t.Errorf("not handed, an unknown key is %v", err)
+	}
+}
+
+func fileOf(t *testing.T, r Resolution, with Rendering, id string) string {
+	t.Helper()
+	out, err := r.Declaration(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, res := range out {
+		if res["id"] == id {
+			return res["content"].(string)
+		}
+	}
+	t.Fatalf("%s was not composed", id)
+	return ""
+}

go/catalogue/backup_test.go

@@ -0,0 +1,47 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A backup contribution written by hand still names its module's own directories; one it does not
+// declare is refused where it is written rather than reaching the holder as the literal text. (The
+// catalogue check refuses a hand-written backup line at all since ADR 0233; parsing still reads one,
+// because a module on the shelf was written before.)
+func TestABackupNamingAnUndeclaredDirectoryIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"pg","version":"1",
+		"contributions":[{"seat":"node-backup","kind":"backup","content":"path ${dir:nowhere}"}]}`))
+	if err == nil || !strings.Contains(err.Error(), "nowhere") {
+		t.Fatalf("a backup of an undeclared directory was accepted: %v", err)
+	}
+}
+
+// A module on the shelf from before ADR 0233, which writes its backup lines by hand and declares no
+// data, is still backed up: its lines are placed as written, each module's under a comment naming it.
+func TestHandWrittenBackupLinesOfAnOlderModuleArePlaced(t *testing.T) {
+	pg, err := ParseManifest([]byte(`{"module":"pg","version":"1",
+		"resources":[{"id":"dumps","type":"directory","path":"/srv/pg/dumps","mode":"0700"}],
+		"contributions":[{"seat":"node-backup","kind":"backup","content":"run pg-dump-all\npath ${dir:dumps}"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	mail, err := ParseManifest([]byte(`{"module":"mail","version":"1",
+		"resources":[{"id":"spool","type":"directory","mode":"0700"}],
+		"contributions":[{"seat":"node-backup","kind":"backup","content":"path ${dir:spool}"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	placed, _, err := seatContributions([]Manifest{pg, mail}, Manifest{}, BackupSeat+":"+"backup", Rendering{}, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, want := range []string{"# pg\nrun pg-dump-all\npath /srv/pg/dumps\n", "# mail\npath /var/lib/mail/spool\n"} {
+		if !strings.Contains(placed, want) {
+			t.Errorf("placed contributions lack %q:\n%s", want, placed)
+		}
+	}
+	if strings.Contains(placed, "${dir:") {
+		t.Errorf("a directory reached the holder unfilled:\n%s", placed)
+	}
+}

go/catalogue/bootstrap_cycle_test.go

@@ -0,0 +1,71 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The module that provides the artifact store may not be delivered through it.
+//
+// Building publishes to the store and the builder will not start without one, so a module that
+// provides the store and also builds something asks the mesh to put an artifact into the thing
+// that artifact is needed to create. On a mesh new enough to have no registry, that is a build
+// that never returns (novox/hq 04-ISSUES/029).
+func TestTheArtifactStoreCannotBeDeliveredThroughItself(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"registry","version":"1",` +
+		`"provides":[{"name":"artifact-store","scope":"mesh"}],` +
+		`"build":{"artifacts":[{"name":"registry","kind":"upstream","from":"registry:2"}]},` +
+		`"resources":[{"id":"store","type":"container","name":"mesh-registry",` +
+		`"artifact":"registry","ports":["5000:5000"]}]}`))
+	if err == nil {
+		t.Fatal("a registry module that builds its own image was accepted; the build has " +
+			"nowhere to publish until the module it belongs to is already running")
+	}
+	if !strings.Contains(err.Error(), "artifact-store") {
+		t.Fatalf("refused without naming the provision the cycle turns on: %v", err)
+	}
+}
+
+// Naming the image directly is the way out, and must stay accepted.
+func TestAnArtifactStoreThatNamesItsImageIsAccepted(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"registry","version":"1",` +
+		`"provides":[{"name":"artifact-store","scope":"mesh"}],` +
+		`"resources":[{"id":"store","type":"container","name":"mesh-registry",` +
+		`"image":"registry@sha256:` +
+		`266f282fabd7cd3df053ee7c658c77b42380d1a2f0d8e5a1c0d7a6d5b5c4a3b2",` +
+		`"ports":["5000:5000"]}]}`))
+	if err != nil {
+		t.Fatalf("the one way an artifact store can be delivered was refused: %v", err)
+	}
+}
+
+// And an ordinary module still builds whatever it likes.
+func TestAModuleThatDoesNotProvideTheStoreStillBuilds(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"forge","version":"1",` +
+		`"build":{"artifacts":[{"name":"forge","kind":"upstream","from":"gitea/gitea:1.22"}]},` +
+		`"resources":[{"id":"run","type":"container","name":"forge","artifact":"forge"}]}`))
+	if err != nil {
+		t.Fatalf("an ordinary module was caught by a rule about the artifact store: %v", err)
+	}
+}
+
+// A mapping that names an address still names the port, and the machine side is still the middle.
+//
+// The foundation bundle writes "127.0.0.1:5432:5432" today, so the shape is not hypothetical.
+// Found in review: the first cut split on the first colon, read "127.0.0.1" as the machine port,
+// failed to parse it, and silently skipped the mapping — which put the filter back on the
+// declared port, the exact fault MachineSide was written to end.
+func TestAnAddressedMappingStillNamesThePort(t *testing.T) {
+	m := Manifest{Module: "store", Resources: []map[string]any{
+		{"type": "container", "id": "server", "ports": []any{"127.0.0.1:8080:80"}},
+	}}
+	for _, named := range []int{8080, 80} {
+		at, mayAssign := m.MachineSide(named)
+		if mayAssign {
+			t.Fatalf("%d was reassigned though the manifest published it explicitly", named)
+		}
+		if at != 8080 {
+			t.Fatalf("naming %d gave %d; the machine side of 127.0.0.1:8080:80 is 8080", named, at)
+		}
+	}
+}

go/catalogue/bound.go

@@ -0,0 +1,186 @@
+package catalogue
+
+import (
+	"fmt"
+	"slices"
+	"strings"
+)
+
+// A consumer of a provision that keeps its data stays bound where its data is (novox/hq ADR 0232).
+//
+// **What a resolution chooses is not where a consumer's data is.** Resolving answers "which provider
+// would I pick now", from the seats' holders, the pins and what is assigned where, and every one of
+// those can change under a consumer without anybody meaning to move it. For a resolver that is the
+// point: any provider answers alike. For a database it is the consumer's whole state: on 2026-10-05
+// one change to how a seat's holder answers (issue 258) re-bound five database consumers on one
+// machine to the store on another, each was given a fresh, empty database there, and nothing warned
+// for twenty hours (issue 273). Nothing was lost only because the old provider kept everything.
+//
+// So the mesh records where each such consumer was last sent (the store's `binding` table), and a
+// resolution that would answer it from anywhere else keeps the recorded provider instead and says so.
+// **Only a pin moves it**, because a pin is a person: the one act that says "answer this machine's
+// consumers from there", taken knowing the data must go first.
+
+// KeptBinding is one consumer this resolution would have moved, and did not.
+type KeptBinding struct {
+	// Machine is where the consumer runs, and Consumer the module there that is bound.
+	Machine  string
+	Consumer string
+	// Provision is what it is bound for.
+	Provision string
+	// Bound is the provider it was recorded at, and still is; Would is the one the resolution chose.
+	Bound Chosen
+	Would Chosen
+}
+
+// String is the condition's sentence: the move, where the data is, and the act that confirms it.
+func (k KeptBinding) String() string {
+	return fmt.Sprintf("would move %s's %s from %s to %s — its data is on %s; kept there. "+
+		"`pin %s %s %s %s` to confirm a move (and move the data first)",
+		k.Consumer, k.Provision, k.Bound, k.Would, k.Bound, k.Machine, k.Provision, k.Would.Node, k.Would.Module)
+}
+
+// keepBound holds every need for a provision that keeps its consumers' data at the provider its
+// consumer was bound to, where the resolution chose another.
+//
+// A need with no record is a binding being made, and is left as resolved: it is recorded when it is
+// first sent. A pin naming the provider the resolution chose is a person moving it, and is left too.
+// Otherwise the recorded provider answers, if it still provides the provision — beside the consumer,
+// or offered from elsewhere — and the move is returned as kept. **One that no longer does is refused,
+// never answered by the provider chosen**: answering it there is exactly the silent move this exists
+// to stop, and the consumer's data is still wherever it was.
+func keepBound(needs []Needed, catalogue map[string]Manifest, node Node, world World,
+	keeps map[string]bool, here func(string) bool) ([]Needed, []KeptBinding, []string) {
+	var kept []KeptBinding
+	var problems []string
+	refused := map[[2]string]bool{}
+	out := make([]Needed, 0, len(needs))
+	for _, n := range needs {
+		if n.ByRecord || !keeps[n.Name] {
+			out = append(out, n)
+			continue
+		}
+		n.KeepsData = true
+		bound, recorded := world.Bound[n.For][n.Name]
+		chose := Chosen{Node: n.From, Module: n.Module}
+		if !recorded || sameProvider(bound, chose) {
+			out = append(out, n)
+			continue
+		}
+		if pin, pinned := world.Pinned[n.Name]; pinned && pin.matches(Provider{Node: chose.Node, Module: chose.Module}) {
+			out = append(out, n)
+			continue
+		}
+		held, ok, why := boundNeed(n, bound, catalogue, node, world, here)
+		if !ok {
+			if key := [2]string{n.For, n.Name}; !refused[key] {
+				refused[key] = true
+				problems = append(problems, fmt.Sprintf(
+					"%s on %s is bound to %s for %q, which keeps its data, and %s — it would move to %s, "+
+						"which holds none of it. Move its data and say so with `pin %s %s %s %s`, or give "+
+						"%s back what it provided",
+					n.For, node.Name, bound, n.Name, why, chose, node.Name, n.Name, chose.Node, chose.Module,
+					bound.Node))
+			}
+			continue
+		}
+		out = append(out, held)
+		kept = append(kept, KeptBinding{Machine: node.Name, Consumer: n.For, Provision: n.Name, Bound: bound, Would: chose})
+	}
+	return out, kept, problems
+}
+
+// sameProvider is whether a recorded provider is the one chosen. A record naming no module (none
+// is written without one, but a person's hand might) matches any module on its node.
+func sameProvider(bound, chose Chosen) bool {
+	return bound.Node == chose.Node && (bound.Module == "" || bound.Module == chose.Module)
+}
+
+// boundNeed is the need answered by the recorded provider, or why it cannot be.
+func boundNeed(n Needed, bound Chosen, catalogue map[string]Manifest, node Node, world World,
+	here func(string) bool) (Needed, bool, string) {
+	held := Needed{Name: n.Name, For: n.For, Local: n.Local, KeepsData: true}
+	if bound.Node == node.Name {
+		m, known := catalogue[bound.Module]
+		if !known || !here(bound.Module) || !providesAt(m, n.Name, ScopeMesh) {
+			return Needed{}, false, fmt.Sprintf("%s no longer runs on %s", bound.Module, node.Name)
+		}
+		at := node.At
+		if at == "" {
+			at = "127.0.0.1"
+		}
+		held.From, held.At, held.Module = node.Name, at, m.Module
+		held.Serves, held.SharedOwn, held.Identity = servedByOne(m, n.Name), sharedByOne(m, n.Name), m.IdentityBoundOf(n.Name)
+		held.CredentialForm, held.CredentialTool = m.CredentialFormOf(n.Name), m.CredentialToolOf(n.Name)
+		return held, true, ""
+	}
+	matching := bound.among(world.Offered[n.Name])
+	if len(matching) != 1 {
+		return Needed{}, false, fmt.Sprintf("%s no longer provides it", bound)
+	}
+	p := matching[0]
+	if node.At == "" || p.At == "" {
+		return Needed{}, false, fmt.Sprintf("%s and %s are not both on the private network", node.Name, p.Node)
+	}
+	identity := DefaultIdentityBound
+	if pm, known := catalogue[p.Module]; known {
+		held.SharedOwn, _ = pm.SharedCredentialOf(n.Name)
+		held.CredentialForm, held.CredentialTool = pm.CredentialFormOf(n.Name), pm.CredentialToolOf(n.Name)
+		identity = pm.IdentityBoundOf(n.Name)
+	}
+	held.From, held.At, held.Module, held.Serves, held.Identity = p.Node, p.At, p.Module, p.Serves, identity
+	held.LeftOut = p.LeftOut
+	return held, true, ""
+}
+
+// Unbound is one consumer that still asks for a provision and whose own resolution binds it to
+// another provider than the one a pair credential on record was made with (novox/hq issue 274).
+//
+// **A provider is granted exactly the consumers bound to it.** The credential from the old provider
+// stays on record — it is the key to a login that provider keeps, disabled, with the consumer's data,
+// until a person deletes it with `cleanup delete` (ADR 0230), and a pin back must find it — but it is
+// no longer granted, so the provider stops being asked for it and retires it. Said on every plan and
+// push of the provider, so a credential the mesh keeps and does not use is never kept silently.
+type Unbound struct {
+	// Provision is what was required, Provider the machine the credential on record is from.
+	Provision string `json:"provision"`
+	Provider  string `json:"provider"`
+	// Consumer is the machine, Module the module on it that requires it, Local the credential's
+	// name inside it where it keeps several (ADR 0094).
+	Consumer string `json:"consumer"`
+	Module   string `json:"module"`
+	Local    string `json:"local,omitempty"`
+	// BoundTo is every provider the consumer's resolution binds this credential to now; empty when
+	// it binds it nowhere — the module asks for the provision under other local names.
+	BoundTo []string `json:"bound_to,omitempty"`
+}
+
+func (u Unbound) String() string {
+	who := u.Module
+	if u.Local != "" {
+		who += " (as " + u.Local + ")"
+	}
+	now := "is bound to no provider under that name"
+	if len(u.BoundTo) > 0 {
+		now = "is bound to " + strings.Join(u.BoundTo, ", ")
+	}
+	return fmt.Sprintf("%s on %s %s for %s, not to %s — %s no longer grants it, so it retires that "+
+		"login and keeps its data until `cleanup delete` (ADR 0230); the credential from %s stays on "+
+		"record while that login does", who, u.Consumer, now, u.Provision, u.Provider, u.Provider, u.Provider)
+}
+
+// BindsFrom is the providers this resolution binds a pair credential's need to — the provision, the
+// module that requires it and the credential's local name — answered by a machine rather than by a
+// record. None means this machine states no such binding.
+func (r Resolution) BindsFrom(provision, module, local string) []string {
+	var from []string
+	for _, n := range r.Needs {
+		if n.ByRecord || n.Name != provision || n.For != module || n.Local != local {
+			continue
+		}
+		if !slices.Contains(from, n.From) {
+			from = append(from, n.From)
+		}
+	}
+	return from
+}

go/catalogue/bound_into_files.go

@@ -0,0 +1,192 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// The half of a connection that is not secret, put where the program reading it can find it.
+//
+// **The asymmetry this removes was backwards** (novox/hq 04-ISSUES/023). A sealed credential can
+// be placed inside any configuration file a module writes: the module leaves a hole, the mesh
+// delivers the value sealed beside it, and the host — the only thing that sees both — fills it in.
+// The host and the port and the name to present are ordinary facts the mesh holds in the clear,
+// and they were the ones stuck: readable only inside a JSON binding, which a program reading
+// `KEY=value` cannot use.
+//
+// So the same shape, and simpler. These values are not secret, so **the control plane substitutes
+// them itself** before the declaration is sent. Nothing new reaches the host, which learns no
+// formats and gains no fields.
+//
+// **It stays name-agnostic** ([ADR 0027]). The mesh does not learn what a `postgres-database` is:
+// `at`, `as`, `from` and `address` (the providing machine's private address, novox/hq ADR 0194) are
+// facts about any provision at all, and everything else comes from what the provider said it
+// serves — whose keys are agreed by the requirement's name, not by this file.
+
+// bound is where a module says a value from one of its bindings belongs:
+// ${bound:<provision>:<key>}, and for an optional requirement the value it takes while absent,
+// ${bound:<provision>:<key>|default:<value>} (novox/hq ADR 0330 §4). A default is never empty: an
+// absent requirement is never rendered as an empty string.
+var bound = regexp.MustCompile(`\$\{bound:([a-z0-9][a-z0-9.-]*[a-z0-9]):([a-z0-9][a-z0-9_-]*)(?:\|default:([^}\n]+))?\}`)
+
+// knownFor is everything a module may name from one of its bindings.
+//
+// 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, error) {
+	out := map[string]map[string]string{}
+	for _, want := range m.Wants() {
+		for i := range needs {
+			n := needs[i]
+			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":   as,
+			}
+			// What the provider derives for this consumer rather than for all of them
+			// (novox/hq ADR 0202). 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)
+			}
+			out[want] = values
+		}
+	}
+	return out, nil
+}
+
+// withOwnNames adds a module's own composed names to what it may name from one binding:
+// `${bound:<provision>:name}` and `:internal-name`, and for several contributions to one requirement
+// `:name-<local>` / `:internal-name-<local>`. Set over anything the provider serves under those keys:
+// what the module is called is the mesh's statement, not the provider's.
+func withOwnNames(values map[string]string, own map[string]any) {
+	for _, key := range []string{"name", "internal-name"} {
+		if v, ok := own[key].(string); ok {
+			values[key] = v
+		}
+	}
+	many, _ := own["names"].(map[string]any)
+	for local, raw := range many {
+		names, _ := raw.(map[string]any)
+		for _, key := range []string{"name", "internal-name"} {
+			if v, ok := names[key].(string); ok {
+				values[key+"-"+local] = v
+			}
+		}
+	}
+}
+
+// plainly renders a served value as a program would expect to read it.
+func plainly(value any) string {
+	switch v := value.(type) {
+	case string:
+		return v
+	case float64:
+		if v == float64(int64(v)) {
+			return fmt.Sprintf("%d", int64(v))
+		}
+		return strings.TrimRight(strings.TrimRight(fmt.Sprintf("%f", v), "0"), ".")
+	case bool:
+		return fmt.Sprintf("%t", v)
+	case nil:
+		return ""
+	default:
+		return fmt.Sprint(v)
+	}
+}
+
+// boundInto replaces a file's ${bound:…} placeholders with what the mesh knows.
+//
+// A placeholder naming something the module does not require, or a key the provider does not
+// serve, is refused. Left as it was, the literal `${bound:x:y}` would be written into a
+// configuration file and read as a value — a connection to a host called `${bound:x:y}`, failing
+// somewhere that names neither the module nor the mesh.
+//
+// **An optional requirement left absent takes the default its placeholder names** (novox/hq ADR
+// 0330 §4), and one that names none is refused rather than rendered empty. The module check refuses
+// that already; this is the same rule where the file is made, for a manifest registered before it.
+func boundInto(resource map[string]any, known map[string]map[string]string, module string, absent map[string]bool) error {
+	if fmt.Sprint(resource["type"]) != "file" {
+		return nil
+	}
+	content, ok := resource["content"].(string)
+	if !ok {
+		return nil
+	}
+	var refused error
+	filled := bound.ReplaceAllStringFunc(content, func(token string) string {
+		if refused != nil {
+			return token
+		}
+		m := bound.FindStringSubmatch(token)
+		provision, key, fallback := m[1], m[2], m[3]
+		values, has := known[provision]
+		if !has {
+			if absent[provision] {
+				if fallback != "" {
+					return fallback
+				}
+				refused = fmt.Errorf(
+					"%s has a file that says ${bound:%s:%s}, and %q is optional and absent here: it names no "+
+						"value for then (${bound:%s:%s|default:<value>}), so it would be written empty "+
+						"(novox/hq ADR 0330 §4)", module, provision, key, provision, provision, key)
+				return token
+			}
+			refused = fmt.Errorf(
+				"%s has a file that says ${bound:%s:%s}, and %s does not require %q. It may name %s",
+				module, provision, key, module, provision, orNothing(namesOfBindings(known)))
+			return token
+		}
+		value, said := values[key]
+		if !said {
+			refused = fmt.Errorf(
+				"%s asks its %s binding for %q, and what answers it says %s",
+				module, provision, key, orNothing(namesOfKeys(values)))
+			return token
+		}
+		return value
+	})
+	if refused != nil {
+		return refused
+	}
+	resource["content"] = filled
+	return nil
+}
+
+func namesOfBindings(known map[string]map[string]string) []string {
+	var names []string
+	for name := range known {
+		names = append(names, fmt.Sprintf("%q", name))
+	}
+	sort.Strings(names)
+	return names
+}
+
+func namesOfKeys(values map[string]string) []string {
+	var names []string
+	for key := range values {
+		names = append(names, fmt.Sprintf("%q", key))
+	}
+	sort.Strings(names)
+	return names
+}
+
+func orNothing(names []string) string {
+	if len(names) == 0 {
+		return "nothing"
+	}
+	return join(names)
+}

go/catalogue/bound_into_files_test.go

@@ -0,0 +1,265 @@
+package catalogue
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// A consumer writes its own connection string (novox/hq 04-ISSUES/023).
+//
+// Everything needed for one now reaches the file that needs it: the address and port from what the
+// provider serves, the name to present from what the mesh decided, the database name from what the
+// module itself contributed, and the password through the sealed hole the host fills.
+func TestAConsumerCanWriteAConnectionString(t *testing.T) {
+	r := Resolution{
+		Node: "workstation",
+		Modules: []Manifest{{
+			Module:   "keycloak",
+			Requires: []string{"postgres-database"},
+			Secrets:  map[string]string{"postgres-database": "/var/lib/keycloak/db.secret"},
+			Resources: []map[string]any{{
+				"id": "dbenv", "type": "file", "path": "/var/lib/keycloak/database.env",
+				"mode": "0600",
+				"content": "KC_DB_URL=jdbc:postgresql://${bound:postgres-database:at}:" +
+					"${bound:postgres-database:port}/keycloak\n" +
+					"KC_DB_USERNAME=${bound:postgres-database:as}\n" +
+					"KC_DB_PASSWORD=${secret:postgres-database}\n",
+			}},
+		}},
+		Needs: []Needed{{
+			Name: "postgres-database", From: "anchor", At: "anchor.internal", For: "keycloak",
+			Sealed: "sealed-db", Serves: map[string]any{"port": float64(5432)},
+		}},
+	}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	file := fileNamed(out, "keycloak.dbenv")
+	if file == nil {
+		t.Fatalf("no file in %v", out)
+	}
+	got := file["content"].(string)
+
+	want := "KC_DB_URL=jdbc:postgresql://anchor.internal:5432/keycloak\n" +
+		"KC_DB_USERNAME=mesh_workstation_keycloak\n" +
+		"KC_DB_PASSWORD=${secret:postgres-database}\n"
+	if got != want {
+		t.Errorf("the consumer cannot connect with what it was given:\n got %q\nwant %q", got, want)
+	}
+	// The password is still a hole. Only the host may fill that one, and only on the machine.
+	if sealed, _ := file["secrets"].(map[string]any); sealed["postgres-database"] != "sealed-db" {
+		t.Errorf("the credential did not travel with the file: %v", file)
+	}
+}
+
+// A provider answered on its consumer's own machine is announced at the port the machine PUBLISHES
+// it on, not the port the module declared (novox/hq 04-ISSUES/038).
+//
+// Issue 018 made the same-node provider announced at all; this is the promise after it — that the
+// port a co-located consumer is told is the one actually listening at the address it is handed. The
+// mesh assigns a bare `ports` mapping a host port (here the container's 5432 becomes 15432 on this
+// machine), and it must announce 15432, or the consumer dials workstation.internal:5432 where the
+// provider is not published. Cross-node consumers already got this (the plan re-derives the served
+// facts with the provider's assignment); the same-node need was settled before the assignment and
+// carried the declared port until now.
+func TestASameNodeProviderIsAnnouncedAtThePortItIsPublishedOn(t *testing.T) {
+	provider := Manifest{
+		Module: "postgres", Version: "1",
+		Provides: FromAnywhere("postgres-database"),
+		Listens:  []Listening{{Port: 5432, Protocol: "tcp", From: "mesh"}},
+		Serves:   map[string]map[string]any{"postgres-database": {"port": 5432}},
+		Resources: []map[string]any{{
+			"id": "server", "type": "container", "name": "postgres",
+			"ports": []any{"5432"},
+		}},
+	}
+	consumer := Manifest{
+		Module: "keycloak", Version: "1", Requires: []string{"postgres-database"},
+		Resources: []map[string]any{{
+			"id": "dbenv", "type": "file", "path": "/var/lib/keycloak/database.env", "mode": "0600",
+			"content": "KC_DB_URL=jdbc:postgresql://${bound:postgres-database:at}:" +
+				"${bound:postgres-database:port}/keycloak\n",
+		}},
+	}
+	r, err := Resolve(shelf(provider, consumer),
+		[]string{"postgres", "keycloak"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	// The mesh assigned the container's 5432 to 15432 on this machine.
+	out, err := r.Declaration(Rendering{Ports: map[string]map[int]int{"postgres": {5432: 15432}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Where the provider is actually published: the assigned host port, on the machine at large.
+	server := fileNamed(out, "postgres.server")
+	if server == nil {
+		t.Fatalf("the provider container is not in the declaration: %v", out)
+	}
+	if published := fmt.Sprint(server["ports"]); !strings.Contains(published, "15432:5432") {
+		t.Fatalf("the provider was not published on the assigned port: %v", server["ports"])
+	}
+
+	// What the consumer was told to dial: the SAME port, at the announced address — not the 5432 the
+	// module declared, which is closed on that address.
+	dbenv := fileNamed(out, "keycloak.dbenv")
+	if dbenv == nil {
+		t.Fatalf("the consumer's binding file is not in the declaration: %v", out)
+	}
+	got := dbenv["content"].(string)
+	want := "KC_DB_URL=jdbc:postgresql://workstation.internal:15432/keycloak\n"
+	if got != want {
+		t.Errorf("the consumer dials a port the provider does not listen on:\n got %q\nwant %q",
+			got, want)
+	}
+}
+
+// A port is 5432, not 5432.000000 — which is what a number decoded from JSON would write, and what
+// every connection string in the world would refuse.
+func TestAPortIsWrittenAsAPort(t *testing.T) {
+	if got := plainly(float64(5432)); got != "5432" {
+		t.Errorf("a port was rendered as %q", got)
+	}
+	if got := plainly("postgres"); got != "postgres" {
+		t.Errorf("a string was rendered as %q", got)
+	}
+}
+
+// The name the provider will create is the name the consumer is told to present. One derivation,
+// so the two agree by construction rather than by two conventions written on the same day.
+func TestTheProviderAndTheConsumerAgreeOnTheName(t *testing.T) {
+	provider, err := Resolve(shelf(Manifest{
+		Module: "postgres", Version: "1", Provides: FromAnywhere("postgres-database"),
+		Grants:   map[string]string{"postgres-database": "/var/lib/postgres/grants"},
+		Receives: map[string]string{"postgres-database": "/var/lib/postgres/grants/mesh.json"},
+	}), []string{"postgres"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := provider.Declaration(Rendering{Grants: []Grant{{
+		Provision: "postgres-database", Consumer: "workstation", From: "keycloak",
+		Values: map[string]any{"name": "keycloak"}, Sealed: "sealed",
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var told string
+	for _, res := range out {
+		if res["path"] == "/var/lib/postgres/grants/mesh.json" {
+			told = res["content"].(string)
+		}
+	}
+	if !strings.Contains(told, `"as": "mesh_workstation_keycloak"`) {
+		t.Errorf("the provider was not told what to call the login: %s", told)
+	}
+	if told == "" {
+		t.Fatal("the provider was told nothing at all")
+	}
+	// Which is exactly what the consumer, on its own machine, is told to present.
+	if ConsumerIdentity("workstation", "keycloak") != "mesh_workstation_keycloak" {
+		t.Errorf("got %q", ConsumerIdentity("workstation", "keycloak"))
+	}
+}
+
+// A binding the module does not have is a typo, refused where it was written.
+func TestAFileCannotNameABindingTheModuleDoesNotHave(t *testing.T) {
+	r := Resolution{
+		Node: "workstation",
+		Modules: []Manifest{{
+			Module: "keycloak", Requires: []string{"postgres-database"},
+			Resources: []map[string]any{{
+				"id": "conf", "type": "file", "path": "/etc/keycloak.conf",
+				"content": "host=${bound:s3-bucket:at}\n",
+			}},
+		}},
+		Needs: []Needed{{Name: "postgres-database", From: "anchor", At: "a", For: "keycloak"}},
+	}
+	_, err := r.Declaration(Rendering{})
+	if err == nil {
+		t.Fatal("a module read a binding it does not have")
+	}
+	if !strings.Contains(err.Error(), "postgres-database") {
+		t.Errorf("the refusal does not say what it could have named: %v", err)
+	}
+}
+
+// A key the provider does not serve is refused too. Written through, the literal placeholder
+// becomes a hostname, and the failure names neither the module nor the mesh.
+func TestAKeyTheProviderDoesNotServeIsRefused(t *testing.T) {
+	r := Resolution{
+		Node: "workstation",
+		Modules: []Manifest{{
+			Module: "keycloak", Requires: []string{"postgres-database"},
+			Resources: []map[string]any{{
+				"id": "conf", "type": "file", "path": "/etc/keycloak.conf",
+				"content": "sock=${bound:postgres-database:socket}\n",
+			}},
+		}},
+		Needs: []Needed{{
+			Name: "postgres-database", From: "anchor", At: "a", For: "keycloak",
+			Serves: map[string]any{"port": float64(5432)},
+		}},
+	}
+	_, err := r.Declaration(Rendering{})
+	if err == nil {
+		t.Fatal("a module read a key nothing serves, and the placeholder became a value")
+	}
+	if !strings.Contains(err.Error(), `"port"`) {
+		t.Errorf("the refusal does not say what is served: %v", err)
+	}
+}
+
+// A name too long to stay distinct is refused before anything is created.
+func TestAnIdentityTooLongToBeDistinctIsRefused(t *testing.T) {
+	if err := CheckIdentity("anchor", "keycloak"); err != nil {
+		t.Fatalf("an ordinary consumer was refused: %v", err)
+	}
+	if err := CheckIdentity(strings.Repeat("n", 40), strings.Repeat("m", 40)); err == nil {
+		t.Fatal("an identity that providers would shorten was accepted")
+	}
+}
+
+// Two modules on one node get two identities, which is the whole point of both issues.
+func TestTwoModulesOnOneNodeAreTwoIdentities(t *testing.T) {
+	if ConsumerIdentity("anchor", "gitea") == ConsumerIdentity("anchor", "keycloak") {
+		t.Fatal("two consumers on one machine share an identity")
+	}
+	// And one module on two nodes, likewise.
+	if ConsumerIdentity("anchor", "gitea") == ConsumerIdentity("laptop", "gitea") {
+		t.Fatal("one module on two machines shares an identity")
+	}
+}
+
+// A machine's resolver configuration must name its resolver by address — it cannot resolve the name
+// of the thing it resolves names with (novox/hq ADR 0194). So a binding offers the providing
+// machine's private address beside its name, and only when the machine has one.
+func TestABindingOffersTheProvidersAddress(t *testing.T) {
+	consumer := func() Resolution {
+		return Resolution{
+			Node: "workstation",
+			Modules: []Manifest{{
+				Module:   "resolv-conf",
+				Requires: []string{"wildcard-resolution"},
+				Resources: []map[string]any{{
+					"id": "resolv", "type": "file", "path": "/etc/resolv.conf", "mode": "0644",
+					"content": "nameserver ${bound:wildcard-resolution:address}\n",
+				}},
+			}},
+			Needs: []Needed{{Name: "wildcard-resolution", From: "anchor", At: "anchor.internal", For: "resolv-conf"}},
+		}
+	}
+	out, err := consumer().Declaration(Rendering{Machines: map[string]string{"anchor.internal": "10.77.0.1"}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := fileNamed(out, "resolv-conf.resolv")["content"]; got != "nameserver 10.77.0.1\n" {
+		t.Fatalf("the resolver is not named by its address: %q", got)
+	}
+	// A machine with no address yet: refused, never written with a blank where the address belongs.
+	if _, err := consumer().Declaration(Rendering{}); err == nil {
+		t.Fatal("a file naming an address the mesh does not have was composed")
+	}
+}

go/catalogue/bound_test.go

@@ -0,0 +1,257 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A consumer of a provision that keeps its data stays bound where its data is (novox/hq ADR 0232,
+// issue 273).
+//
+// The incident, exactly: a machine runs its own store and five consumers of it; the mesh's store seat
+// is held by the store on another machine. Issue 258's rule — the seat's holder elsewhere answers
+// before this machine's own provider — re-bound all five to the holder, each was made a fresh, empty
+// database there, and nothing said so.
+
+var incidentConsumers = []string{"board", "listings", "workflows", "agents", "game"}
+
+func storeMesh() map[string]Manifest {
+	shelf := map[string]Manifest{
+		"store": {Module: "store", Version: "1",
+			Provides: []Offer{{Name: "postgres-database", Scope: ScopeMesh}},
+			Claims:   []Claim{{Name: "mesh-store", Scope: ScopeMesh}},
+			Serves:   map[string]map[string]any{"postgres-database": {"port": 5432}},
+			Grants:   map[string]string{"postgres-database": "/grants"}},
+		"resolver": {Module: "resolver", Version: "1",
+			Provides: []Offer{{Name: "wildcard-resolution", Scope: ScopeMesh}},
+			Claims:   []Claim{{Name: "mesh-dns-resolver", Scope: ScopeMesh}}},
+		"network": {Module: "network", Version: "1", Requires: []string{"wildcard-resolution"}},
+	}
+	for _, c := range incidentConsumers {
+		shelf[c] = Manifest{Module: c, Version: "1", Requires: []string{"postgres-database"}}
+	}
+	return shelf
+}
+
+// storeWorld is the rest of the mesh as the home server's plan sees it: the anchor runs a store and a
+// resolver and holds both seats; the home server runs its own of each.
+func storeWorld() World {
+	w := World{Offered: map[string][]Provider{
+		"postgres-database": {
+			{Node: "anchor", At: "anchor.internal", Module: "store", Serves: map[string]any{"port": 5432}},
+			{Node: "home", At: "home.internal", Module: "store", Serves: map[string]any{"port": 5434}},
+		},
+		"wildcard-resolution": {
+			{Node: "anchor", At: "anchor.internal", Module: "resolver"},
+			{Node: "home", At: "home.internal", Module: "resolver"},
+		},
+	}}
+	w.Held = []Held{
+		{Claim: "mesh-store", Scope: ScopeMesh, Node: "anchor", Module: "store"},
+		{Claim: "mesh-dns-resolver", Scope: ScopeMesh, Node: "anchor", Module: "resolver"},
+	}
+	w.Holdings = w.Held
+	return w
+}
+
+var home = Node{Name: "home", At: "home.internal"}
+
+func homeAssigned() []string {
+	return append([]string{"store", "resolver", "network"}, incidentConsumers...)
+}
+
+func boundFrom(t *testing.T, r Resolution, consumer, provision string) Needed {
+	t.Helper()
+	for _, n := range r.Needs {
+		if n.For == consumer && n.Name == provision {
+			return n
+		}
+	}
+	t.Fatalf("no binding of %s for %s: %+v", consumer, provision, r.Needs)
+	return Needed{}
+}
+
+func TestTheIncidentAMachinesOwnStoreKeepsItsConsumersWhenTheSeatIsHeldElsewhere(t *testing.T) {
+	got, err := Resolve(storeMesh(), homeAssigned(), home, storeWorld())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range incidentConsumers {
+		if n := boundFrom(t, got, c, "postgres-database"); n.From != "home" || n.Module != "store" {
+			t.Errorf("%s bound to %s/%s; its data is on the store beside it (issue 273)", c, n.From, n.Module)
+		}
+	}
+	// And the resolver, which keeps nothing of anybody's, still answers from the seat's holder (258).
+	if n := boundFrom(t, got, "network", "wildcard-resolution"); n.From != "anchor" {
+		t.Errorf("the resolver bound to %s; the seat is held on anchor (issue 258)", n.From)
+	}
+	if len(got.Kept) != 0 {
+		t.Errorf("nothing was moved, and %d kept: %+v", len(got.Kept), got.Kept)
+	}
+}
+
+func TestTheIncidentWithEveryConsumerOnRecordStillMovesNothing(t *testing.T) {
+	w := storeWorld()
+	w.Bound = map[string]map[string]Chosen{}
+	for _, c := range incidentConsumers {
+		w.Bound[c] = map[string]Chosen{"postgres-database": {Node: "home", Module: "store"}}
+	}
+	got, err := Resolve(storeMesh(), homeAssigned(), home, w)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range incidentConsumers {
+		if n := boundFrom(t, got, c, "postgres-database"); n.From != "home" {
+			t.Errorf("%s bound to %s", c, n.From)
+		}
+	}
+	if len(got.Kept) != 0 {
+		t.Errorf("kept %+v", got.Kept)
+	}
+}
+
+func TestAPinElsewhereStillMovesAStoresConsumers(t *testing.T) {
+	w := storeWorld()
+	w.Pinned = map[string]Chosen{"postgres-database": {Node: "anchor", Module: "store"}}
+	w.Bound = map[string]map[string]Chosen{"board": {"postgres-database": {Node: "home", Module: "store"}}}
+	got, err := Resolve(storeMesh(), homeAssigned(), home, w)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := boundFrom(t, got, "board", "postgres-database"); n.From != "anchor" || n.Module != "store" {
+		t.Errorf("bound to %s/%s; a person pinned it to anchor", n.From, n.Module)
+	}
+	if len(got.Kept) != 0 {
+		t.Errorf("a pin is a person's move, not one to keep: %+v", got.Kept)
+	}
+}
+
+// A consumer on a machine with no store of its own, bound to one store, when the seat moves to
+// another: the holder would answer, and the binding stays.
+func laptopWorld(holder string) World {
+	w := storeWorld()
+	w.Held = []Held{{Claim: "mesh-store", Scope: ScopeMesh, Node: holder, Module: "store"}}
+	w.Holdings = w.Held
+	return w
+}
+
+var laptop = Node{Name: "laptop", At: "laptop.internal"}
+
+func TestABoundConsumerStaysWhenTheSeatsHolderChanges(t *testing.T) {
+	w := laptopWorld("home")
+	w.Bound = map[string]map[string]Chosen{"board": {"postgres-database": {Node: "anchor", Module: "store"}}}
+	got, err := Resolve(storeMesh(), []string{"board"}, laptop, w)
+	if err != nil {
+		t.Fatal(err)
+	}
+	n := boundFrom(t, got, "board", "postgres-database")
+	if n.From != "anchor" || n.At != "anchor.internal" || n.Serves["port"] != 5432 {
+		t.Fatalf("bound to %s at %s %v; its data is on anchor", n.From, n.At, n.Serves)
+	}
+	if len(got.Kept) != 1 {
+		t.Fatalf("the move was not said: %+v", got.Kept)
+	}
+	k := got.Kept[0]
+	if k.Bound != (Chosen{"anchor", "store"}) || k.Would != (Chosen{"home", "store"}) || k.Consumer != "board" {
+		t.Fatalf("kept %+v", k)
+	}
+	for _, want := range []string{"would move board's postgres-database from anchor/store to home/store",
+		"its data is on anchor/store", "pin laptop postgres-database home store", "move the data first"} {
+		if !strings.Contains(k.String(), want) {
+			t.Errorf("%q does not say %q", k.String(), want)
+		}
+	}
+	// Without a record it is a binding being made, and the holder answers it as before.
+	w.Bound = nil
+	got, err = Resolve(storeMesh(), []string{"board"}, laptop, w)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := boundFrom(t, got, "board", "postgres-database"); n.From != "home" {
+		t.Errorf("a new consumer bound to %s; the seat is held on home", n.From)
+	}
+}
+
+func TestABoundConsumerWhoseProviderIsGoneIsRefusedNotMoved(t *testing.T) {
+	w := laptopWorld("anchor")
+	w.Offered["postgres-database"] = w.Offered["postgres-database"][:1] // only anchor's store is left
+	w.Bound = map[string]map[string]Chosen{"board": {"postgres-database": {Node: "home", Module: "store"}}}
+	_, err := Resolve(storeMesh(), []string{"board"}, laptop, w)
+	if err == nil {
+		t.Fatal("bound to home's store, which is gone, and answered by anchor's — the silent move")
+	}
+	for _, want := range []string{"board on laptop is bound to home/store", "home/store no longer provides it",
+		"pin laptop postgres-database anchor store"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("%q does not say %q", err, want)
+		}
+	}
+}
+
+func TestAMachinesOwnStoreUnassignedRefusesItsBoundConsumers(t *testing.T) {
+	w := storeWorld()
+	w.Bound = map[string]map[string]Chosen{"board": {"postgres-database": {Node: "home", Module: "store"}}}
+	_, err := Resolve(storeMesh(), []string{"board"}, home, w)
+	if err == nil || !strings.Contains(err.Error(), "store no longer runs on home") {
+		t.Fatalf("got %v", err)
+	}
+}
+
+// The first pass asks only what a machine offers, and is never refused by a binding.
+func TestTheFirstPassKeepsNoBinding(t *testing.T) {
+	w := storeWorld()
+	w.Unchecked = true
+	w.Bound = map[string]map[string]Chosen{"board": {"postgres-database": {Node: "gone", Module: "store"}}}
+	if _, err := Resolve(storeMesh(), []string{"board"}, laptop, w); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnOfferSaysWhetherItKeepsConsumerData(t *testing.T) {
+	var o Offer
+	if err := json.Unmarshal([]byte(`{"name":"wildcard-resolution","scope":"mesh","keeps-consumer-data":false}`), &o); err != nil {
+		t.Fatal(err)
+	}
+	if o.KeepsConsumerData == nil || *o.KeepsConsumerData {
+		t.Fatalf("read %+v", o)
+	}
+	out, err := json.Marshal(o)
+	if err != nil || !strings.Contains(string(out), `"keeps-consumer-data":false`) {
+		t.Fatalf("wrote %s, %v", out, err)
+	}
+	yes, no := true, false
+	granting := Manifest{Module: "g", Provides: []Offer{{Name: "p", Scope: ScopeMesh}}, Grants: map[string]string{"p": "/g"}}
+	if !granting.KeepsConsumerData("p") {
+		t.Error("a provider granting each consumer a credential keeps what it writes, unsaid")
+	}
+	if (Manifest{Module: "r", Provides: []Offer{{Name: "p", Scope: ScopeMesh}}}).KeepsConsumerData("p") {
+		t.Error("a provider granting nothing keeps nothing, unsaid")
+	}
+	granting.Provides[0].KeepsConsumerData = &no
+	if granting.KeepsConsumerData("p") {
+		t.Error("what an offer says, it gets")
+	}
+	said := Manifest{Module: "s", Provides: []Offer{{Name: "p", Scope: ScopeMesh, KeepsConsumerData: &yes}}}
+	if !said.KeepsConsumerData("p") || !KeepsConsumerData(map[string]Manifest{"s": said, "r": {Module: "r",
+		Provides: []Offer{{Name: "p", Scope: ScopeMesh, KeepsConsumerData: &no}}}}, "p") {
+		t.Error("a name any provider says keeps data keeps data")
+	}
+}
+
+// An offer saying it keeps nothing is answered by the seat's holder as the resolver is, even where it
+// grants a credential.
+func TestAStoreSayingItKeepsNothingFollowsTheSeat(t *testing.T) {
+	shelf := storeMesh()
+	no := false
+	s := shelf["store"]
+	s.Provides = []Offer{{Name: "postgres-database", Scope: ScopeMesh, KeepsConsumerData: &no}}
+	shelf["store"] = s
+	got, err := Resolve(shelf, homeAssigned(), home, storeWorld())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := boundFrom(t, got, "board", "postgres-database"); n.From != "anchor" {
+		t.Errorf("bound to %s; it keeps nothing, and the seat is held on anchor", n.From)
+	}
+}

go/catalogue/broker_seat_test.go

@@ -0,0 +1,87 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The mesh's bus is one per mesh, read from the catalogue beside this checkout.
+//
+// **This is step 2's claim, and it is checked here rather than in a bed** (novox/hq ADR 0116):
+// adoption puts the NATS server into the `mesh-broker` seat on a mesh that is already running,
+// and the property that matters is that a second one anywhere is refused *when it is assigned*,
+// not discovered later as two servers holding different halves of the mesh's traffic. A second
+// bus is not a degraded mesh; it is two meshes that both believe they are the one.
+func TestASecondMeshBusAnywhereIsRefusedByName(t *testing.T) {
+	nats := catalogueManifest(t, "nats")
+
+	if _, err := Resolve(shelf(nats), []string{"nats"}, workstation(), World{}); err != nil {
+		t.Fatalf("the bus alone does not resolve: %v", err)
+	}
+
+	elsewhere := World{Held: []Held{{Claim: "mesh-broker", Scope: ScopeMesh,
+		Node: "anchor", Module: "nats"}}}
+	other := workstation()
+	other.Name = "laptop"
+	_, err := Resolve(shelf(nats), []string{"nats"}, other, elsewhere)
+	if err == nil {
+		t.Fatal("a second bus was accepted on another machine")
+	}
+	if !strings.Contains(err.Error(), "mesh-broker") || !strings.Contains(err.Error(), "one per mesh") {
+		t.Fatalf("refused without naming the seat: %v", err)
+	}
+}
+
+// The seat is the server's role, not the product's name (novox/hq ADR 0079). A different
+// implementation of the bus claims the same seat, and the mesh refuses it for the same reason —
+// which is the property that lets the bus be replaced at all.
+func TestTheSeatRefusesADifferentBusToo(t *testing.T) {
+	nats := catalogueManifest(t, "nats")
+	held := World{Held: []Held{{Claim: "mesh-broker", Scope: ScopeMesh,
+		Node: "anchor", Module: "some-other-broker"}}}
+	other := workstation()
+	other.Name = "laptop"
+	if _, err := Resolve(shelf(nats), []string{"nats"}, other, held); err == nil {
+		t.Fatal("the seat admitted a second holder because the module's name differed")
+	}
+}
+
+// The old broker is gone from the catalogue (novox/hq ADR 0131, design 28 task 5.4), so it is no
+// longer a fixture here. That two eligible holders stand beside each other with one on record is
+// pinned in holdings_test.go against manifests this package owns.
+
+// **A seat and the interface it delivers are different names, and renaming one must not rename
+// the other** (novox/hq ADR 0118). This nearly went wrong: the seats were renamed to the `mesh-*`
+// prefix, and a blanket search-and-replace also renamed `npm-package-registry` and `git` where
+// they are *provisions* — which a consumer requires and a provider offers. The tests failed with
+// "the package registry is served on <nil>", which does not say "you renamed an interface".
+func TestRenamingASeatDidNotRenameTheInterfaceItDelivers(t *testing.T) {
+	for _, pair := range []struct{ seat, delivers string }{
+		{"git", "git"},
+		{"npm-package-registry", "npm-package-registry"},
+		{"mesh-artifact-store", "artifact-store"},
+		{"mesh-store", "postgres-database"},
+		{"mesh-broker", "mesh-bus"},
+	} {
+		s, known := SeatNamed(pair.seat)
+		if !known {
+			t.Fatalf("%q is not a seat", pair.seat)
+		}
+		if s.Delivers != pair.delivers {
+			t.Errorf("the %s seat delivers %q, expected %q — renaming the seat moved the "+
+				"interface with it, and every consumer requiring it would stop resolving",
+				pair.seat, s.Delivers, pair.delivers)
+		}
+		// **Three of these deliberately share a name with what they deliver**, and that is not an
+		// incomplete rename. Renaming a seat that delivers a provision cascades to every consumer
+		// requiring it, with a mesh-wide window where a holder stops resolving mid-flight — so the
+		// trunk deferred exactly those three (novox/hq ADR 0121) while renaming the node-scoped ones.
+		// What this test is for is the other direction: that renaming a seat never moves the
+		// interface, which once produced "the package registry is served on <nil>".
+	}
+}
+
+// A manifest written against an old seat name is told what it became rather than refused as
+// unknown. **That map is the controller's store now, not this package** (novox/hq ADR 0122): a
+// rename is a row, so the courtesy survives a rename nobody recompiled for. Checked where the
+// table is read, not here, where there is no longer a hardcoded list to check against.

go/catalogue/brokered_test.go

@@ -0,0 +1,332 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// Where the answer to a requirement is allowed to live.
+//
+// A shell, a display server and a private network have to be on the machine that needs them. A
+// database does not — it runs somewhere and is reached over the network. Both were written
+// `requires`, so both were answered the same way, and the second answer was to install PostgreSQL
+// on every machine that runs a web application.
+
+// onNetwork is a set of providers, all of them reachable. Written as a helper because a machine
+// that cannot reach the one answering its requirement is its own case, tested separately.
+// reachable is this machine, on the private network.
+func reachable() Node {
+	n := workstation()
+	n.At = "workstation.internal"
+	return n
+}
+
+func onNetwork(nodes ...string) map[string][]Provider {
+	out := make([]Provider, 0, len(nodes))
+	for _, n := range nodes {
+		out = append(out, Provider{Node: n, At: n + ".internal", Module: "postgres"})
+	}
+	return map[string][]Provider{"postgres-database": out}
+}
+
+func brokeredShelf() map[string]Manifest {
+	return shelf(
+		Manifest{Module: "postgres", Version: "1", Provides: FromAnywhere("postgres-database")},
+		Manifest{Module: "meshboard", Version: "1", Requires: []string{"postgres-database"}},
+	)
+}
+
+func TestADatabaseIsNotInstalledOnEveryMachineThatUsesOne(t *testing.T) {
+	// The fault this whole distinction exists for.
+	got, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: onNetwork("anchor")})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if have := strings.Join(names(got), " "); strings.Contains(have, "postgres") {
+		t.Fatalf("using a database installed one here: %s", have)
+	}
+}
+
+func TestWhatAMachineTakesFromElsewhereIsRecorded(t *testing.T) {
+	// It is the only part of a node's set that stops working when a *different* machine goes
+	// away, and it is where a credential will have to be handed back.
+	got, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: onNetwork("anchor")})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Needs) != 1 {
+		t.Fatalf("got %v", got.Needs)
+	}
+	if got.Needs[0].Name != "postgres-database" || got.Needs[0].From != "anchor" {
+		t.Fatalf("got %v", got.Needs[0])
+	}
+	if got.Needs[0].For != "meshboard" {
+		t.Fatalf("it does not say what wanted it: %v", got.Needs[0])
+	}
+}
+
+func TestNothingInTheMeshProvidingItIsRefusedWithSomewhereToPutIt(t *testing.T) {
+	// Refused rather than installed here. Choosing a machine to put a database on is a decision
+	// with consequences, and nothing resolving a web application should make it silently.
+	_, err := Resolve(brokeredShelf(), []string{"meshboard"}, workstation(), World{})
+	if err == nil {
+		t.Fatal("a database was found in a mesh that has none")
+	}
+	if !strings.Contains(err.Error(), "assign") || !strings.Contains(err.Error(), "postgres") {
+		t.Fatalf("the refusal does not say what to do: %v", err)
+	}
+}
+
+func TestTwoNodesProvidingItIsRefusedRatherThanPicked(t *testing.T) {
+	// Same rule as everywhere else. Picking one would be a guess about which database a person
+	// meant, and the wrong guess is somebody's data in the wrong place.
+	_, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: onNetwork("anchor", "archive")})
+	if err == nil {
+		t.Fatal("one of two databases was picked silently")
+	}
+	for _, want := range []string{"anchor", "archive", "pin"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("the refusal does not name %s: %v", want, err)
+		}
+	}
+}
+
+func TestSayingWhichOneSettlesIt(t *testing.T) {
+	got, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{
+			Offered: onNetwork("anchor", "archive"),
+			Pinned:  map[string]Chosen{"postgres-database": {Node: "archive", Module: "postgres"}},
+		})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Needs) != 1 || got.Needs[0].From != "archive" {
+		t.Fatalf("the choice was not taken: %v", got.Needs)
+	}
+}
+
+func TestBeingPointedAtAMachineThatDoesNotProvideItIsRefused(t *testing.T) {
+	// Rather than falling back to one that does. A fallback would quietly move somebody's data to
+	// a machine they did not choose, which is the whole reason the question is asked.
+	_, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{
+			Offered: onNetwork("anchor", "archive"),
+			Pinned:  map[string]Chosen{"postgres-database": {Node: "somewhere-else", Module: "postgres"}},
+		})
+	if err == nil {
+		t.Fatal("a machine was silently given a different database from the one chosen")
+	}
+	if !strings.Contains(err.Error(), "somewhere-else") {
+		t.Fatalf("the refusal does not say what was chosen: %v", err)
+	}
+}
+
+func TestOneProviderDoesNotOverruleAChoice(t *testing.T) {
+	// A single answer is normally taken silently. Not when somebody said they wanted a different
+	// one -- that is the mesh overruling a person, which it does nowhere else.
+	_, err := Resolve(brokeredShelf(), []string{"meshboard"}, reachable(),
+		World{
+			Offered: onNetwork("anchor"),
+			Pinned:  map[string]Chosen{"postgres-database": {Node: "archive", Module: "postgres"}},
+		})
+	if err == nil {
+		t.Fatal("the only database was used although another was chosen")
+	}
+	if !strings.Contains(err.Error(), "only anchor/postgres provides it") {
+		t.Fatalf("the refusal does not say what is available: %v", err)
+	}
+}
+
+func TestACatalogueThatDisagreesAboutScopeIsRefused(t *testing.T) {
+	// If one module says a database is local and another says it is anywhere, the same
+	// requirement means two things depending on which one happens to answer it.
+	_, err := Resolve(shelf(
+		Manifest{Module: "postgres", Version: "1", Provides: FromAnywhere("postgres-database")},
+		Manifest{Module: "sqlite", Version: "1", Provides: Offers("postgres-database")},
+		Manifest{Module: "meshboard", Version: "1", Requires: []string{"postgres-database"}},
+	), []string{"meshboard"}, workstation(), World{})
+	if err == nil {
+		t.Fatal("a catalogue that disagrees about where a database lives was accepted")
+	}
+	if !strings.Contains(err.Error(), "two things") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+func TestALocalRequirementIsStillAnsweredLocally(t *testing.T) {
+	// The change must not have made everything brokered. A shell is still installed here.
+	got, err := Resolve(shelf(
+		Manifest{Module: "zsh", Version: "1", Provides: Offers("shell")},
+		Manifest{Module: "tools", Version: "1", Requires: []string{"shell"}},
+	), []string{"tools"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if have := strings.Join(names(got), " "); !strings.Contains(have, "zsh") {
+		t.Fatalf("a shell was not installed on the machine that needs one: %s", have)
+	}
+}
+
+func TestTheShortFormStillMeansHere(t *testing.T) {
+	// `"provides": ["shell"]` must keep meaning what it meant, or every existing manifest
+	// silently changes meaning.
+	m, err := ParseManifest([]byte(`{"module":"zsh","version":"1","provides":["shell"]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(m.Provides) != 1 || m.Provides[0].At() != ScopeNode {
+		t.Fatalf("a plain name is no longer node-scoped: %v", m.Provides)
+	}
+}
+
+func TestASiteScopedProvisionIsRefused(t *testing.T) {
+	// Meaningful for a claim — one DHCP server per segment — and not yet meaningful for a
+	// provision, because nothing knows how to reach "the one at my site".
+	_, err := ParseManifest([]byte(
+		`{"module":"dns","version":"1","provides":[{"name":"resolver","scope":"site"}]}`))
+	if err == nil {
+		t.Fatal("a site-scoped provision was accepted")
+	}
+	if !strings.Contains(err.Error(), "site") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+// Being told, which is the difference between knowing and being able to.
+
+func boundShelf() map[string]Manifest {
+	return shelf(
+		Manifest{Module: "postgres", Version: "1", Provides: FromAnywhere("postgres-database"),
+			Serves: map[string]map[string]any{"postgres-database": {"port": 5432, "driver": "postgres"}}},
+		Manifest{Module: "meshboard", Version: "1", Requires: []string{"postgres-database"},
+			Binds: map[string]string{"postgres-database": "/etc/meshboard/database.json"}},
+	)
+}
+
+func binding(t *testing.T, out []map[string]any) map[string]any {
+	t.Helper()
+	for _, r := range out {
+		if r["path"] != "/etc/meshboard/database.json" {
+			continue
+		}
+		var parsed map[string]any
+		if err := json.Unmarshal([]byte(r["content"].(string)), &parsed); err != nil {
+			t.Fatalf("what the app is told is not readable: %v", err)
+		}
+		return parsed
+	}
+	t.Fatalf("the app was told nothing: %v", out)
+	return nil
+}
+
+func TestAnAppIsToldWhereItsDatabaseIs(t *testing.T) {
+	// Knowing it needs the anchor's database is useless to the program that needs it unless the
+	// program is told. This is the whole point of the field.
+	got, err := Resolve(boundShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: map[string][]Provider{"postgres-database": {{Node: "anchor", At: "anchor.internal",
+			Serves: map[string]any{"port": 5432, "driver": "postgres"}}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	told := binding(t, mustDeclare(t, got))
+	if told["from"] != "anchor" || told["at"] != "anchor.internal" {
+		t.Fatalf("it was not told where: %v", told)
+	}
+	serves, _ := told["serves"].(map[string]any)
+	if serves["port"] != float64(5432) || serves["driver"] != "postgres" {
+		t.Fatalf("it was not told how: %v", serves)
+	}
+}
+
+func TestItSaysWhereTheCredentialIsInstead(t *testing.T) {
+	// A missing field looks like a bug; a stated absence looks like a boundary. Somebody wiring
+	// this up must not spend an afternoon looking for the password field.
+	//
+	// It used to say only that the mesh had no way to issue one, which stopped being true when
+	// 021 was fixed. A stated absence is only useful while it is accurate — once it is not, it
+	// sends the reader somewhere there is nothing to find.
+	got, _ := Resolve(boundShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: map[string][]Provider{"postgres-database": {{Node: "anchor", At: "anchor.internal"}}}})
+	told := binding(t, mustDeclare(t, got))
+	note, _ := told["generated"].(string)
+	if !strings.Contains(note, "not here") || !strings.Contains(note, "secrets") {
+		t.Fatalf("the file does not say where the credential is instead: %v", note)
+	}
+	for key := range told {
+		if strings.Contains(key, "password") || strings.Contains(key, "secret") {
+			t.Fatalf("something that looks like a credential appeared: %q", key)
+		}
+	}
+}
+
+func TestTwoMachinesThatCannotReachEachOtherAreRefused(t *testing.T) {
+	// An app on one machine and a database on another that share no private network is a mesh
+	// that reports itself configured and does not work. Said here rather than discovered as a
+	// connection timing out.
+	_, err := Resolve(boundShelf(), []string{"meshboard"}, workstation(), // not on the network
+		World{Offered: map[string][]Provider{"postgres-database": {{Node: "anchor", At: "anchor.internal"}}}})
+	if err == nil {
+		t.Fatal("an app was pointed at a database it has no path to")
+	}
+	if !strings.Contains(err.Error(), "private network") {
+		t.Fatalf("the refusal does not say what is wrong: %v", err)
+	}
+	if !strings.Contains(err.Error(), meshNetwork) {
+		t.Fatalf("the refusal does not say what to assign: %v", err)
+	}
+}
+
+func TestTheProviderBeingOffTheNetworkIsAlsoRefused(t *testing.T) {
+	// Both directions, because the failure is identical from either end and the remedy differs.
+	_, err := Resolve(boundShelf(), []string{"meshboard"}, reachable(),
+		World{Offered: map[string][]Provider{"postgres-database": {{Node: "anchor"}}}})
+	if err == nil {
+		t.Fatal("an app was pointed at a database that is not on the private network")
+	}
+	if !strings.Contains(err.Error(), "anchor") {
+		t.Fatalf("the refusal does not name the unreachable end: %v", err)
+	}
+}
+
+func TestBindingSomethingAnsweredHereWritesNothing(t *testing.T) {
+	// A file saying "it is on this node" is a fact nobody needs and one more thing to keep true.
+	got, err := Resolve(shelf(
+		Manifest{Module: "zsh", Version: "1", Provides: Offers("shell")},
+		Manifest{Module: "tools", Version: "1", Requires: []string{"shell"},
+			Binds: map[string]string{"shell": "/etc/tools/shell.json"}},
+	), []string{"tools"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range mustDeclare(t, got) {
+		if r["path"] == "/etc/tools/shell.json" {
+			t.Fatalf("a binding was written for something on this machine: %v", r)
+		}
+	}
+}
+
+func TestBindingWhatYouDoNotRequireIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"app","version":"1",
+		"binds":{"postgres-database":"/etc/app/db.json"}}`))
+	if err == nil {
+		t.Fatal("a module was told about something it never asked for")
+	}
+	if !strings.Contains(err.Error(), "does not require") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+func TestServingWhatYouDoNotProvideIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"app","version":"1",
+		"serves":{"postgres-database":{"port":5432}}}`))
+	if err == nil {
+		t.Fatal("a module served something it does not provide")
+	}
+	if !strings.Contains(err.Error(), "does not provide") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}

go/catalogue/bucket_shares.go

@@ -0,0 +1,124 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"sort"
+)
+
+// BucketShare is one entry of `shares` on a module's requirement of `s3-bucket` (novox/hq ADR 0468 §8): who else may
+// put or get in the consumer's bucket, and with which methods. Not the NFS shares of shares.go (ADR 0263).
+//
+//	"requires": [{"name": "s3-bucket", "shares": [{"to": "seat:node-files", "methods": ["put"]},
+//	                                             {"to": "print-and-scan", "methods": ["get"]}]}]
+//
+// `to` is a module name, or `seat:<seat name>`. `methods` is a non-empty subset of get and put, without a repeat.
+// Shares are allowed on `s3-bucket` only, and no two entries name the same `to`.
+type BucketShare struct {
+	To      string   `json:"to"`
+	Methods []string `json:"methods"`
+}
+
+// BucketRequirement is the requirement `shares` may be written on.
+const BucketRequirement = "s3-bucket"
+
+// RequireSharesKey is where a stored manifest keeps the shares of its requirements: beside `requires`, which stays a
+// plain list of names, for the reason OptionalRequiresKey is beside it. An older controller sets the unknown key
+// aside instead of failing the catalogue.
+const RequireSharesKey = "requires-shares"
+
+// SharesValue is the key of the value a consumer gives the provider of s3-bucket in its grant: the list of
+// {to, methods} sorted by `to`. A consumer's own `contributes` may not name it.
+const SharesValue = "shares"
+
+var shareTarget = regexp.MustCompile(`^(seat:)?[a-z0-9][a-z0-9-]*$`)
+
+// checkBucketShares refuses a malformed `shares` of one requirement, naming the entry and ADR 0468 §8.
+func checkBucketShares(requirement string, shares []BucketShare) error {
+	if len(shares) == 0 {
+		return nil
+	}
+	if requirement != BucketRequirement {
+		return fmt.Errorf("requires %s: `shares` is allowed on %s only (novox/hq ADR 0468 §8)", requirement, BucketRequirement)
+	}
+	seen := map[string]bool{}
+	for i, s := range shares {
+		at := fmt.Sprintf("requires %s: shares[%d] (to %q)", requirement, i, s.To)
+		if !shareTarget.MatchString(s.To) {
+			return fmt.Errorf("%s: `to` is a module name or seat:<seat name> (novox/hq ADR 0468 §8)", at)
+		}
+		if seen[s.To] {
+			return fmt.Errorf("%s: a second entry for the same `to` (novox/hq ADR 0468 §8)", at)
+		}
+		seen[s.To] = true
+		if len(s.Methods) == 0 {
+			return fmt.Errorf("%s: `methods` is empty; name get, put or both (novox/hq ADR 0468 §8)", at)
+		}
+		used := map[string]bool{}
+		for _, method := range s.Methods {
+			if method != "get" && method != "put" {
+				return fmt.Errorf("%s: method %q is not get or put (novox/hq ADR 0468 §8)", at, method)
+			}
+			if used[method] {
+				return fmt.Errorf("%s: method %q twice (novox/hq ADR 0468 §8)", at, method)
+			}
+			used[method] = true
+		}
+	}
+	return nil
+}
+
+// readRequireShares reads the stored form's side key.
+func readRequireShares(raw json.RawMessage) (map[string][]BucketShare, error) {
+	var out map[string][]BucketShare
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, fmt.Errorf("%s: an object of requirement to a list of {to, methods}: %w", RequireSharesKey, err)
+	}
+	for requirement, shares := range out {
+		if err := checkBucketShares(requirement, shares); err != nil {
+			return nil, err
+		}
+	}
+	return out, nil
+}
+
+// sortedShares is a requirement's shares as they are handed to the provider: sorted by `to` (a file whose lines move
+// looks changed), each entry's methods sorted, and a copy so the manifest is not reordered.
+func sortedShares(shares []BucketShare) []BucketShare {
+	out := make([]BucketShare, 0, len(shares))
+	for _, s := range shares {
+		methods := append([]string(nil), s.Methods...)
+		sort.Strings(methods)
+		out = append(out, BucketShare{To: s.To, Methods: methods})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].To < out[j].To })
+	return out
+}
+
+// withShares adds this module's shares of the requirement to the values it gives the provider. A module whose own
+// `contributes` already names `shares` is refused: the field is the only way to say it (ADR 0468 §8).
+func withShares(m Manifest, requirement string, values map[string]any) (map[string]any, error) {
+	shares := m.RequireShares[requirement]
+	if _, named := values[SharesValue]; named && requirement == BucketRequirement {
+		return nil, fmt.Errorf("%s contributing to %s names `shares`; write it on its requirement instead (novox/hq ADR 0468 §8)",
+			m.Module, requirement)
+	}
+	if len(shares) == 0 {
+		return values, nil
+	}
+	out := make(map[string]any, len(values)+1)
+	for k, v := range values {
+		out[k] = v
+	}
+	listed := []any{}
+	for _, s := range sortedShares(shares) {
+		methods := []any{}
+		for _, method := range s.Methods {
+			methods = append(methods, method)
+		}
+		listed = append(listed, map[string]any{"to": s.To, "methods": methods})
+	}
+	out[SharesValue] = listed
+	return out, nil
+}

go/catalogue/bucket_shares_test.go

@@ -0,0 +1,185 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// Issue 1591: `shares` on a requirement of s3-bucket (novox/hq ADR 0468 §8).
+
+const filesWithShares = `{"module":"files","version":"1","requires":["shell",
+	{"name":"s3-bucket","shares":[{"to":"seat:node-files","methods":["put"]},{"to":"print-and-scan","methods":["get","put"]}]}]}`
+
+func minioLike() Manifest {
+	return Manifest{Module: "minio", Version: "1", Provides: Offers("s3-bucket"),
+		Receives: map[string]string{"s3-bucket": "/grants/mesh.json"}}
+}
+
+func givenToMinio(t *testing.T, out []map[string]any) []Contribution {
+	t.Helper()
+	for _, r := range out {
+		if r["path"] != "/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("minio was given no file: %v", out)
+	return nil
+}
+
+func sharesOf(t *testing.T, values map[string]any) string {
+	t.Helper()
+	raw, err := json.Marshal(values["shares"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(raw)
+}
+
+const sortedSharesJSON = `[{"methods":["get","put"],"to":"print-and-scan"},{"methods":["put"],"to":"seat:node-files"}]`
+
+// 1591/AC1: parsed, the shares are on the manifest; stored, `requires` is plain names and the side key holds them.
+func TestSharesParseAndAreStoredBesideRequires(t *testing.T) {
+	m := mustParse(t, filesWithShares)
+	want := []BucketShare{{To: "seat:node-files", Methods: []string{"put"}}, {To: "print-and-scan", Methods: []string{"get", "put"}}}
+	if !reflect.DeepEqual(m.RequireShares["s3-bucket"], want) {
+		t.Fatalf("the shares read as %+v", m.RequireShares)
+	}
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var keys map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keys); err != nil {
+		t.Fatal(err)
+	}
+	if string(keys["requires"]) != `["shell","s3-bucket"]` {
+		t.Errorf("the stored requires is not plain names: %s", keys["requires"])
+	}
+	if !strings.Contains(string(keys[RequireSharesKey]), `"seat:node-files"`) {
+		t.Errorf("the side key does not hold the shares: %s", raw)
+	}
+	var again Manifest
+	if err := json.Unmarshal(raw, &again); err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(again, m) {
+		t.Fatalf("not lossless:\n%+v\n%+v", again, m)
+	}
+}
+
+// 1591/AC2: a malformed share is refused, naming the entry and ADR 0468 §8.
+func TestAMalformedShareIsRefused(t *testing.T) {
+	cases := map[string]string{
+		"unknown method": `{"name":"s3-bucket","shares":[{"to":"a","methods":["delete"]}]}`,
+		"empty to":       `{"name":"s3-bucket","shares":[{"to":"","methods":["get"]}]}`,
+		"malformed to":   `{"name":"s3-bucket","shares":[{"to":"Seat:X y","methods":["get"]}]}`,
+		"empty methods":  `{"name":"s3-bucket","shares":[{"to":"a","methods":[]}]}`,
+		"duplicate to":   `{"name":"s3-bucket","shares":[{"to":"a","methods":["get"]},{"to":"a","methods":["put"]}]}`,
+		"duplicate verb": `{"name":"s3-bucket","shares":[{"to":"a","methods":["get","get"]}]}`,
+		"other require":  `{"name":"route","shares":[{"to":"a","methods":["get"]}]}`,
+	}
+	for name, entry := range cases {
+		_, err := ParseManifest([]byte(`{"module":"files","version":"1","requires":[` + entry + `]}`))
+		if err == nil {
+			t.Errorf("%s: accepted", name)
+			continue
+		}
+		if !strings.Contains(err.Error(), "ADR 0468 §8") || !strings.Contains(err.Error(), "requires") {
+			t.Errorf("%s: the error does not name the entry and the ADR: %v", name, err)
+		}
+	}
+	// The stored form is held to the same rules.
+	_, err := ParseManifest([]byte(`{"module":"files","version":"1","requires":["s3-bucket"],
+		"requires-shares":{"s3-bucket":[{"to":"a","methods":[]}]}}`))
+	if err == nil || !strings.Contains(err.Error(), "ADR 0468 §8") {
+		t.Errorf("the stored form was accepted: %v", err)
+	}
+}
+
+// 1591/AC3: the values a consumer gives carry the shares sorted by `to`, remote (grant) and co-located alike.
+func TestTheGrantCarriesTheSharesSorted(t *testing.T) {
+	m := mustParse(t, filesWithShares)
+	remote := Resolution{Node: "laptop", Modules: []Manifest{m}}
+	values, asks, err := remote.ContributionsFrom("s3-bucket", "files", SettingsBy{})
+	if err != nil || !asks {
+		t.Fatalf("asks %v, err %v", asks, err)
+	}
+	if got := sharesOf(t, values); got != sortedSharesJSON {
+		t.Fatalf("the grant values carry %s", got)
+	}
+	// As the provider's file shows it, through a grant.
+	provider, err := Resolve(shelf(minioLike()), []string{"minio"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := provider.Declaration(Rendering{Grants: []Grant{{Provision: "s3-bucket", Consumer: "laptop", From: "files", Values: values}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := givenToMinio(t, out)
+	if len(given) != 1 || sharesOf(t, given[0].Values) != sortedSharesJSON {
+		t.Fatalf("the remote consumer's shares did not reach the file: %+v", given)
+	}
+
+	// Co-located: the consumer contributes to s3-bucket too, and no grant is passed.
+	co := mustParse(t, `{"module":"files","version":"1","contributes":{"s3-bucket":{"name":"files"}},
+		"requires":[{"name":"s3-bucket","shares":[{"to":"seat:node-files","methods":["put"]},{"to":"print-and-scan","methods":["put","get"]}]}]}`)
+	both, err := Resolve(shelf(minioLike(), co), []string{"files"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err = both.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given = givenToMinio(t, out)
+	if len(given) != 1 || sharesOf(t, given[0].Values) != sortedSharesJSON || given[0].Values["name"] != "files" {
+		t.Fatalf("the co-located consumer's shares did not reach the file: %+v", given)
+	}
+}
+
+// 1591/AC4: only the shares change, so the module is not recreated and held for no one; the provider's file changes.
+func TestChangingOnlyTheSharesDoesNotRecreateTheConsumer(t *testing.T) {
+	was := mustParse(t, filesWithShares)
+	now := mustParse(t, `{"module":"files","version":"1","requires":["shell",
+		{"name":"s3-bucket","shares":[{"to":"print-and-scan","methods":["get"]}]}]}`)
+	if said := Recreates(was, now).Say("files"); said != "" {
+		t.Errorf("a change of shares recreates the module: %s", said)
+	}
+	if said := Holds(was, now); said != "" {
+		t.Errorf("a change of shares holds the module: %s", said)
+	}
+	before := Resolution{Node: "laptop", Modules: []Manifest{was}}
+	after := Resolution{Node: "laptop", Modules: []Manifest{now}}
+	a, _, _ := before.ContributionsFrom("s3-bucket", "files", SettingsBy{})
+	b, _, _ := after.ContributionsFrom("s3-bucket", "files", SettingsBy{})
+	if sharesOf(t, a) == sharesOf(t, b) {
+		t.Fatalf("the provider's values did not change: %s", sharesOf(t, a))
+	}
+}
+
+// 1591/AC5: a consumer whose contributes to s3-bucket names `shares` itself is refused.
+func TestAConsumerCannotContributeSharesItself(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"files","version":"1",
+		"contributes":{"s3-bucket":{"shares":"x"}},
+		"requires":[{"name":"s3-bucket","shares":[{"to":"a","methods":["get"]}]}]}`))
+	if err == nil || !strings.Contains(err.Error(), "ADR 0468 §8") {
+		t.Errorf("both written, accepted: %v", err)
+	}
+	// Without the field the grant is still refused, so the provider is never told something the manifest did not say.
+	m := Manifest{Module: "files", Requires: []string{"s3-bucket"},
+		Contributes: map[string]map[string]any{"s3-bucket": {"shares": "x"}}}
+	r := Resolution{Node: "laptop", Modules: []Manifest{m}}
+	if _, _, err := r.ContributionsFrom("s3-bucket", "files", SettingsBy{}); err == nil {
+		t.Error("a contributed `shares` reached the grant")
+	}
+}

go/catalogue/build.go

@@ -0,0 +1,651 @@
+package catalogue
+
+import (
+	"fmt"
+	"net"
+	"net/url"
+	"path"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Turning a manifest that names artifacts into one that names digests.
+//
+// **Two documents, deliberately.** The manifest in a repository says *this resource uses the
+// archive called `config`*; the manifest the mesh holds says *this resource is sha256:…*. A digest
+// is not knowable until something is built, so a repository carrying one would be a repository
+// whose file is wrong the moment anybody edits anything — and the mesh would be pinning a value
+// nobody could have checked.
+//
+// So the built manifest is **derived**, and the record of which commit it was derived from is what
+// makes "is this current?" answerable without building (novox/hq ADR 0009).
+
+// Built is one artifact after it exists: where it is and what it hashes to.
+type Built struct {
+	// Name is what the manifest called it.
+	Name string
+	// Kind is "image" or "archive".
+	Kind string
+	// Reference is what a machine uses to get it — an image reference for an image, a URL for an
+	// archive. Both already carry the digest for an image; an archive carries it separately.
+	Reference string
+	// Digest is "sha256:<hex>", for an archive. An image reference already ends in one.
+	Digest string
+	// Launchers are, for a bundle in an interpreted language, the executable the build wrote beside
+	// each entrypoint, by entrypoint (novox/hq ADR 0193): what the node's runtime starts to serve it.
+	Launchers map[string]string
+	// Texts are, for the archive a module packs its templates into (TemplatesArtifact), each file's text as the
+	// build read it back from the packed archive, by its path inside it (novox/hq ADR 0349 §2). Never carried on
+	// the wire or kept: Resolve reads them into the files' content, which is what the mesh holds.
+	Texts map[string]string `json:"-"`
+}
+
+// Resolve fills a manifest's resources in from what was built.
+//
+// Every resource naming an artifact is rewritten to name the thing itself, and the `artifact` key
+// is removed — because it is a build-time word and the host has never heard of it. A resource
+// naming an artifact nothing produced is refused: it would otherwise reach a machine with an
+// empty image or an unpinned archive, which is the shape of failure that looks like success.
+func (m Manifest) Resolve(built []Built) (Manifest, error) {
+	if m.Build == nil && len(built) == 0 {
+		return m, nil
+	}
+
+	by := map[string]Built{}
+	for _, b := range built {
+		by[b.Name] = b
+	}
+	// Declared and not produced is a build that did not do what the manifest asked, and saying so
+	// here beats a machine reporting it later.
+	var missing []string
+	if m.Build != nil {
+		for _, a := range m.Build.Artifacts {
+			if _, ok := by[a.Name]; !ok {
+				missing = append(missing, a.Name)
+			}
+		}
+	}
+	if len(missing) > 0 {
+		sort.Strings(missing)
+		return Manifest{}, fmt.Errorf(
+			"%s says it builds %s and the build did not produce %s — the build did not do what "+
+				"the manifest asked, which is a different fault from a resource asking for the "+
+				"wrong thing",
+			m.Module, strings.Join(missing, " and "), oneOrOther(len(missing)))
+	}
+
+	// **Each template's text, as the build read it back from its templates archive** (novox/hq ADR 0349 §2): into
+	// the file's content, so what the mesh holds and composes is what the same text inline would be.
+	var handed *Handed
+	if m.Templated() {
+		name := TemplatesArtifact(m)
+		texts := by[name].Texts
+		if name == "" || texts == nil {
+			return Manifest{}, fmt.Errorf("%s names templates, and the build carried no text read back from the "+
+				"archive it packs %s/ into (%q): the builder that built it does not read templates",
+				m.Module, m.TemplatesDir(), name)
+		}
+		dir := m.TemplatesDir()
+		filled, err := fillTemplates(m.Module, dir, m.Resources, func(template string) (string, bool) {
+			t, ok := texts[strings.TrimPrefix(template, dir+"/")]
+			return t, ok
+		}, fmt.Sprintf("the archive %q", name))
+		if err != nil {
+			return Manifest{}, err
+		}
+		items, err := fillItemTemplates(m, m.Items, func(template string) (string, bool) {
+			t, ok := texts[strings.TrimPrefix(template, dir+"/")]
+			return t, ok
+		}, fmt.Sprintf("the archive %q", name))
+		if err != nil {
+			return Manifest{}, err
+		}
+		// And, for a moved module, where its templates are and which one each file and item is filled from
+		// (handed.go): read while its resources and items still name their templates.
+		handed = handedBy(m, by[name])
+		m.Resources = filled
+		m.Items = items
+	}
+
+	out := m
+	out.Handed = handed
+	out.Build = nil
+	// Read with the build, like Build: the manifest the mesh holds carries each file's text (issue 731).
+	out.Templates = ""
+	out.Resources = nil
+	// What the build compiled, kept on the resolved manifest (novox/hq ADR 0175): a tools bundle is
+	// named by no resource of the module's own — the node's runtime loads it — so this is the only
+	// place the mesh would otherwise not have it. In artifact order, so two resolutions of one
+	// build compare equal.
+	out.Bundles = nil
+	if m.Build != nil {
+		run := runByAResource(m)
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != ArtifactBundle {
+				continue
+			}
+			made := by[a.Name]
+			// What the runtime loads: what the artifact said, else every entrypoint of a module
+			// that declares tools, else nothing (the field's own rule; see Artifact.Loads).
+			//
+			// **Never, unasked, a bundle one of the module's own resources runs** (novox/hq issue 213).
+			// A process the host runs is the module's service, not its tools: the controller declares
+			// the verbs it answers as `tools` and serves them itself, and its bundle would otherwise
+			// have been launched a second time by the node's runtime, as an MCP child it is not.
+			loads := append([]string(nil), a.Loads...)
+			if a.Loads == nil && len(m.Tools) > 0 && !run[a.Name] {
+				loads = append([]string(nil), a.Entrypoints...)
+				// A bundle compiled to a binary has no entrypoints: the binary is what it is, and what
+				// the runtime starts to serve it (novox/hq ADR 0193). So a Go tools bundle is served
+				// as Go — the runtime execs it — exactly as a TypeScript one is through its launcher.
+				if bin := BinaryOf(a); bin != "" {
+					loads = []string{bin}
+				}
+			}
+			// **Kept, never routed** (ADR 0155): the builder publishes to the store at the address
+			// it reached it by, and a manifest carrying that address names an installation —
+			// registration refused node-tools for exactly this on 2026-10-02. The build record
+			// already keeps the store-relative form; the resolved manifest keeps the same, and
+			// composition routes it through the store a machine reaches (Routed).
+			out.Bundles = append(out.Bundles, Bundle{
+				Name: a.Name, Source: Recorded(made.Reference), Digest: made.Digest,
+				Language: a.Language, Entrypoints: append([]string(nil), a.Entrypoints...),
+				Loads: loads, Env: copyWords(a.Env), Launchers: copyWords(made.Launchers),
+				Binary: BinaryOf(a),
+			})
+		}
+		sort.Slice(out.Bundles, func(i, j int) bool { return out.Bundles[i].Name < out.Bundles[j].Name })
+	}
+	for _, r := range m.Resources {
+		named, _ := r["artifact"].(string)
+		if named == "" {
+			out.Resources = append(out.Resources, r)
+			continue
+		}
+		artifact, ok := by[named]
+		if !ok {
+			return Manifest{}, fmt.Errorf(
+				"%s: %v uses the artifact %q, and this module builds no such thing",
+				m.Module, r["id"], named)
+		}
+
+		filled := map[string]any{}
+		for k, v := range r {
+			filled[k] = v
+		}
+		delete(filled, "artifact")
+		switch artifact.Kind {
+		case ArtifactPackage:
+			// A package is not a resource on any machine; it is consumed by other builds. A
+			// resource that names one is a manifest error, named here rather than shipped.
+			return Manifest{}, fmt.Errorf(
+				"%s: %v uses %q, which is a package — a build input, not a resource a machine runs",
+				m.Module, r["id"], named)
+		case ArtifactImage, ArtifactUpstream:
+			filled["image"] = artifact.Reference
+			// An image is not unpacked anywhere, so it has no directory to be named for its
+			// version and `${version}` has nothing to mean. Refused rather than left as literal
+			// text in a path, which is how it would reach a machine and be created as a directory
+			// called `${version}`.
+			for key, value := range filled {
+				if text, isText := value.(string); isText && strings.Contains(text, versionRef) {
+					return Manifest{}, fmt.Errorf(
+						"%s: %v says %s in %q, and %q is an image — an image is not unpacked, so "+
+							"it has no versioned place. %s is for an archive or a bundle",
+						m.Module, r["id"], versionRef, key, named, versionRef)
+				}
+			}
+		case ArtifactArchive, ArtifactBundle:
+			// The same on the wire: both are bytes fetched by digest and unpacked. They differ in
+			// how they were made — one packed as it stood, the other compiled first — and a
+			// machine has no reason to care which.
+			// Kept, not routed, for the reason the bundles above are (ADR 0155).
+			filled["source"] = Recorded(artifact.Reference)
+			filled["digest"] = artifact.Digest
+			// **And `${version}`, so a resource can name a place that is this build's alone**
+			// (novox/hq ADR 0141, 04-ISSUES/142). A component is unpacked into a directory named
+			// for its version so it can read its own version from its path — and until this,
+			// nothing could compose that path: an archive named a fixed one in the manifest and
+			// nothing interpolated the build into it, so nothing could ask for
+			// `…/versions/<version>/` and every machine took a hand-placed fallback.
+			//
+			// The version is the artifact's own digest, short. Not the commit: two builds of one
+			// commit are meant to be the same bytes (the toolchains are `-trimpath` for this), and
+			// a content-addressed version means an unchanged build resolves to the path it already
+			// had — so re-composing a declaration moves nothing, where a commit would move the
+			// path of an identical binary and recreate everything that reads it.
+			for key, value := range filled {
+				filled[key] = withVersion(value, versionOf(artifact.Digest))
+			}
+		default:
+			return Manifest{}, fmt.Errorf("%s: %q is a %q, and an artifact is %q, %q, %q or %q",
+				m.Module, named, artifact.Kind, ArtifactImage, ArtifactArchive, ArtifactUpstream,
+				ArtifactBundle)
+		}
+		out.Resources = append(out.Resources, filled)
+	}
+	return out, nil
+}
+
+// withVersion is a resource's value with `${version}` filled: in a string, and in each string of a map —
+// a process's env, where the controller is told which build it is (novox/hq issue 352). Anything else is
+// left as it is.
+func withVersion(value any, version string) any {
+	switch v := value.(type) {
+	case string:
+		if strings.Contains(v, versionRef) {
+			return strings.ReplaceAll(v, versionRef, version)
+		}
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for k, x := range v {
+			out[k] = withVersion(x, version)
+		}
+		return out
+	case map[string]string:
+		out := make(map[string]string, len(v))
+		for k, x := range v {
+			out[k] = strings.ReplaceAll(x, versionRef, version)
+		}
+		return out
+	}
+	return value
+}
+
+// checkBuild is the manifest's own account of what it builds.
+func (b *Build) problems(module string) []string {
+	if b == nil {
+		return nil
+	}
+	var problems []string
+	seen := map[string]bool{}
+	for _, a := range b.Artifacts {
+		if a.Name == "" {
+			problems = append(problems, module+" builds an artifact with no name")
+			continue
+		}
+		if seen[a.Name] {
+			problems = append(problems, fmt.Sprintf(
+				"%s builds two artifacts called %q, and a resource naming it could mean either",
+				module, a.Name))
+		}
+		seen[a.Name] = true
+		switch a.Kind {
+		case ArtifactImage, ArtifactArchive, ArtifactUpstream, ArtifactBundle, ArtifactPackage:
+		default:
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q is a %q, and an artifact is %q, %q, %q or %q",
+				module, a.Name, a.Kind, ArtifactImage, ArtifactArchive, ArtifactUpstream,
+				ArtifactBundle+", "+ArtifactPackage))
+		}
+		// **A bundle is built from the module itself, so it says a language instead.** Everything
+		// else names what it is built from: a Dockerfile, a directory, somebody else's reference.
+		// A bundle's source is the module's own directory by definition, and what it needs to say
+		// is which compiler — because the mesh chooses that, and cannot choose for a module that
+		// has not said.
+		if len(a.External) > 0 && (a.Kind != ArtifactBundle || a.Language != "typescript") {
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q names packages it keeps external, and only a TypeScript bundle is bundled into "+
+					"one file with some kept out (novox/hq ADR 0193)", module, a.Name))
+		}
+		if len(a.Env) > 0 && a.Kind != ArtifactBundle {
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q is a %q and says what it is given (env). Only a bundle the node's runtime "+
+					"serves is given words (novox/hq ADR 0192); a container says its own environment",
+				module, a.Name, a.Kind))
+		}
+		if a.Kind == ArtifactBundle || a.Kind == ArtifactPackage {
+			// **Except for a language that compiles to a binary, where it names which one**
+			// (novox/hq 04-ISSUES/142). A bundle in an interpreted language is the module's own
+			// directory compiled whole, and naming a source would be describing its own build. A
+			// repository written in a compiled language holds several commands — the host and its
+			// bootstrap live in one, and the mesh needs the host — and "the module's own directory"
+			// is then not a package at all. So the compiled case may say which package, and says
+			// the module root by saying nothing.
+			if a.From != "" && !compilesToABinary(a.Language) {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is a bundle and names what it is built from (%q). A bundle is built "+
+						"from the module's own directory; what it says is the language",
+					module, a.Name, a.From))
+			}
+			if strings.TrimSpace(a.Language) == "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is a bundle and says no language, so nothing can choose a compiler "+
+						"for it", module, a.Name))
+			}
+			problems = append(problems, bundleEnvProblems(module, a)...)
+			// What the runtime loads is among what was compiled (ADR 0175): a name here that is
+			// not an entrypoint is a file the bundle does not contain, and the runtime would
+			// fail to import it on every machine rather than here.
+			for _, load := range a.Loads {
+				found := false
+				for _, e := range a.Entrypoints {
+					found = found || e == load
+				}
+				// A bundle compiled to a binary is one executable: the runtime loads that or nothing
+				// (novox/hq ADR 0193).
+				if bin := BinaryOf(a); bin != "" {
+					found = load == bin
+				}
+				if !found {
+					problems = append(problems, fmt.Sprintf(
+						"%s: %q says the runtime loads %q, which is not among its entrypoints — "+
+							"what is loaded is compiled, so it is named there too", module, a.Name, load))
+				}
+			}
+			// **A system, for a language that compiles to a binary** (novox/hq ADR 0142). A binary
+			// is pinned to one operating system at link time so a host refuses to touch a machine
+			// it was not built for (novox/hq ADR 0005); an artifact that says nothing would be
+			// compiled for whatever the build machine happened to be, which reads as portable and
+			// is not.
+			if compiled := compilesToABinary(a.Language); compiled && strings.TrimSpace(a.System) == "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is compiled to a binary and says no system, so it would be built for "+
+						"whatever the build machine happens to be. Declare one artifact per "+
+						"system: %s", module, a.Name, spokenSystems()))
+			} else if !compiled && strings.TrimSpace(a.System) != "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q names the system %q and is written in %q, which compiles to code that "+
+						"runs anywhere — a system that decides nothing reads as though it did",
+					module, a.Name, a.System, a.Language))
+			} else if compiled && !knownSystem(a.System) {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is built for %q, and a system is %s",
+					module, a.Name, a.System, spokenSystems()))
+			}
+		} else {
+			if a.From == "" && a.URL == "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q says nothing about what it is built from", module, a.Name))
+			}
+			if a.Language != "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is a %q and names a language. Only a bundle is compiled by the mesh; "+
+						"everything else brings its own recipe", module, a.Name, a.Kind))
+			}
+		}
+		if a.Compiles != "" {
+			if a.Kind != ArtifactImage {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is a %q and names a Go package it compiles. Only an image's recipe is "+
+						"told which; a bundle names its package in from (novox/hq ADR 0267)", module, a.Name, a.Kind))
+			} else if c := strings.TrimSpace(a.Compiles); strings.HasPrefix(c, "/") || c == ".." ||
+				strings.HasPrefix(c, "../") || strings.Contains(c, "/../") || strings.HasSuffix(c, "/..") {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q compiles %q, which leaves the tree it is built in", module, a.Name, a.Compiles))
+			}
+		}
+		// An upstream image is named, not read from the repository, so the path rule does not
+		// apply to it — and applying it anyway would refuse every reference with a registry host
+		// in it.
+		if a.Kind != ArtifactUpstream &&
+			(strings.HasPrefix(a.From, "/") || strings.Contains(a.From, "..")) {
+			// A build reads its own repository and nothing else. A path leaving it would make
+			// what gets built depend on whatever happens to be on the machine building it.
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q is built from %q, which is outside its own repository",
+				module, a.Name, a.From))
+		}
+		if a.Kind == ArtifactUpstream && !strings.Contains(a.From, ":") {
+			// Without a tag or digest, what gets mirrored is whatever `latest` means today, and
+			// a module pinned to that is not pinned.
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q mirrors %q, which names no tag or digest", module, a.Name, a.From))
+		}
+		problems = append(problems, upstreamFileProblems(module, a)...)
+	}
+	return problems
+}
+
+// reservedSuffixes are names no public vendor publishes under: an installation's own and documentation's.
+var reservedSuffixes = []string{".internal", ".local", ".lan", ".home", ".corp", ".localhost", ".home.arpa",
+	".test", ".invalid", ".example", ".intranet", ".private"}
+
+// notAPublicHost says why a host is not a public vendor's name, or "".
+func notAPublicHost(host string) string {
+	h := strings.ToLower(strings.TrimSuffix(host, "."))
+	if net.ParseIP(h) != nil {
+		return "an address rather than a name"
+	}
+	if !strings.Contains(h, ".") {
+		return "a name with no domain"
+	}
+	for _, s := range reservedSuffixes {
+		if strings.HasSuffix(h, s) {
+			return "a name under " + s + ", which is nobody's public domain"
+		}
+	}
+	return ""
+}
+
+// sha256Hex is a pinned sha256 as a manifest writes it: 64 lower-case hexadecimal characters.
+var sha256Hex = regexp.MustCompile(`^[0-9a-f]{64}$`)
+
+// upstreamFileProblems is what is wrong with an archive pinned by URL (novox/hq ADR 0316 §2, §6): it is an
+// archive, fetched over https, pinned by a sha256 and a version, and it names no directory of the repository
+// besides; a file name or a directory within is a plain path that stays where it is put.
+func upstreamFileProblems(module string, a Artifact) []string {
+	pinned := a.URL != "" || a.SHA256 != "" || a.Version != "" || a.File != "" || a.Within != ""
+	if !pinned {
+		return nil
+	}
+	var problems []string
+	say := func(format string, args ...any) {
+		problems = append(problems, fmt.Sprintf("%s: %q ", module, a.Name)+fmt.Sprintf(format, args...))
+	}
+	if a.Kind != ArtifactArchive {
+		say("is a %q and names an upstream file (url, sha256, version, file, within): only an archive is "+
+			"mirrored from one (novox/hq ADR 0316)", a.Kind)
+		return problems
+	}
+	if a.URL == "" {
+		say("names a sha256, a version, a file or a directory within, and no url to fetch it from")
+		return problems
+	}
+	if a.From != "" {
+		say("is built from %q and fetched from %s: an archive is one or the other", a.From, a.URL)
+	}
+	if u, err := url.Parse(a.URL); err != nil || u.Scheme != "https" || u.Host == "" {
+		say("is fetched from %q, and an upstream file is fetched over https from a named host", a.URL)
+	} else if why := notAPublicHost(u.Hostname()); why != "" {
+		say("is fetched from %s, %s: an upstream file is somebody else's release, published under a public name", a.URL, why)
+	}
+	if !sha256Hex.MatchString(a.SHA256) {
+		say("is fetched from %s without a pinned sha256 (64 lower-case hexadecimal characters): what that "+
+			"address serves changes under the mesh, and only the digest says it is what was reviewed", a.URL)
+	}
+	if strings.TrimSpace(a.Version) == "" {
+		say("pins %s and says no version, so a person reading the pin cannot tell which release it is", a.URL)
+	}
+	if a.File != "" && a.Within != "" {
+		say("names a file (%q) and a directory within (%q): a file is kept whole, a directory is taken out "+
+			"of an archive", a.File, a.Within)
+	}
+	for field, p := range map[string]string{"file": a.File, "within": a.Within} {
+		if p == "" {
+			continue
+		}
+		clean := path.Clean(p)
+		if clean != p || strings.HasPrefix(p, "/") || clean == "." || clean == ".." || strings.HasPrefix(clean, "../") ||
+			(field == "file" && strings.Contains(p, "/")) {
+			say("names %s %q, which is not a plain relative %s", field, p, map[string]string{
+				"file": "file name", "within": "directory"}[field])
+		}
+	}
+	return problems
+}
+
+// oneOrOther keeps the message readable for one artifact and for several, because a message that
+// says "neither" about one thing reads as a bug in the message.
+func oneOrOther(n int) string {
+	if n == 1 {
+		return "it"
+	}
+	return "them"
+}
+
+// Systems the mesh builds binaries for, which is the set a host may be pinned to (novox/hq ADR 0005).
+//
+// **A closed list, and the host's own, not the compiler's.** These are not the values a Go toolchain
+// would call an operating system — the difference between two of them is a C library, not a kernel.
+// They are what a machine reports itself to be and what a host is linked to refuse, so the list that
+// matters is the one the host understands.
+var systems = []string{"alpine", "android", "arch"}
+
+// knownSystem is whether the mesh builds for it.
+func knownSystem(system string) bool {
+	want := strings.ToLower(strings.TrimSpace(system))
+	for _, s := range systems {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}
+
+// spokenSystems is the list as a refusal says it, so a reader is one edit from right.
+func spokenSystems() string {
+	return strings.Join(systems, ", ")
+}
+
+// compilesToABinary is whether this language's bundle is a binary for one operating system rather
+// than code that runs wherever its interpreter does.
+//
+// **Asked of the language, not of the artifact.** A module says what it is written in; what that
+// implies is the mesh's to know, exactly as the compiler is (novox/hq ADR 0142). Asking the artifact
+// would let two artifacts in one language disagree about whether they are portable.
+func compilesToABinary(language string) bool {
+	switch strings.ToLower(strings.TrimSpace(language)) {
+	case "go":
+		return true
+	default:
+		return false
+	}
+}
+
+// versionRef is how a resource names the version of the artifact it uses: ${version}.
+//
+// No artifact name in it, because the resource already says which artifact it is for — a second
+// name would be a second thing to keep in step with the first.
+const versionRef = "${version}"
+
+// versionOf is an artifact's version as a path names it: its digest, short.
+//
+// **Content-addressed on purpose.** The alternative is the commit a build came from, and two builds
+// of one commit are meant to produce the same bytes — every toolchain here is `-trimpath` for that
+// reason. A commit-named path would move for an identical binary, and everything reading that path
+// would be recreated for a change that is not one. A digest-named path moves exactly when the bytes
+// do.
+//
+// Twelve hex characters: enough that two of this mesh's builds will not collide, short enough to
+// read in a path and in a journal line. The `sha256:` prefix goes, because a directory name carrying
+// a colon is a directory name people quote wrong.
+func versionOf(digest string) string {
+	hex := strings.TrimPrefix(strings.TrimSpace(digest), "sha256:")
+	if len(hex) > 12 {
+		return hex[:12]
+	}
+	return hex
+}
+
+// bundleEnvWords are the words the runtime sets for itself; a bundle that named one would be
+// telling the runtime what it is, which is the mesh's to say (novox/hq ADR 0192).
+var bundleEnvWords = map[string]bool{
+	RuntimeToolModules: true, RuntimeBrokerFile: true, RuntimeOperatorAccount: true,
+	RuntimeOperatorHome: true, RuntimeToolEnv: true, RuntimeAgentAccount: true, RuntimeAgentHome: true,
+}
+
+// bundleEnvProblems says what is wrong with what a bundle says it is given (novox/hq ADR 0192):
+// a value is a path or a constant written with the references a container's environment may use
+// for a place or a port, and never a secret's content or another module's binding — a secret
+// reaches a tool as a file whose path is named.
+func bundleEnvProblems(module string, a Artifact) []string {
+	if len(a.Env) == 0 {
+		return nil
+	}
+	var problems []string
+	for _, word := range sortedKeys(a.Env) {
+		value := a.Env[word]
+		if bundleEnvWords[word] {
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q gives itself %s, which the node's runtime sets for itself; a bundle is "+
+					"given its own words beside the runtime's, never in place of them (novox/hq ADR 0192)",
+				module, a.Name, word))
+		}
+		rest := ofPort.ReplaceAllString(dirRef.ReplaceAllString(value, ""), "")
+		if strings.Contains(rest, "${") {
+			problems = append(problems, fmt.Sprintf(
+				"%s: %q gives %s the value %q. A bundle's word is a path or a constant, written with "+
+					"${dir:…} and ${port:…} only; a secret reaches a tool as a file the mesh places, "+
+					"named by its path, never as its content (novox/hq ADR 0192)",
+				module, a.Name, word, value))
+		}
+	}
+	return problems
+}
+
+func copyWords(in map[string]string) map[string]string {
+	if len(in) == 0 {
+		return nil
+	}
+	out := make(map[string]string, len(in))
+	for k, v := range in {
+		out[k] = v
+	}
+	return out
+}
+
+// BinaryOf is what a bundle compiled to a binary is called once built: what the artifact names, else
+// the package it is built from, else the artifact's own name (novox/hq 04-ISSUES/142). Empty for a
+// language that does not compile to one. The builder writes the binary under this name, and the
+// composer runs it by it, so both ask here.
+func BinaryOf(a Artifact) string {
+	if !compilesToABinary(a.Language) {
+		return ""
+	}
+	if name := strings.TrimSpace(a.Binary); name != "" {
+		return name
+	}
+	if from := strings.Trim(a.From, "./"); from != "" {
+		return path.Base(from)
+	}
+	return a.Name
+}
+
+// runByAResource is the artifacts one of a module's own resources names — a process that runs it,
+// a step, an archive that unpacks it — by name.
+func runByAResource(m Manifest) map[string]bool {
+	named := map[string]bool{}
+	for _, r := range m.Resources {
+		if a, ok := r["artifact"].(string); ok && a != "" {
+			named[a] = true
+		}
+	}
+	return named
+}
+
+// undeliveredBundles says which of a module's bundles nothing would ever put on a machine (novox/hq
+// 04-ISSUES/216). A bundle reaches a machine three ways: the node's runtime serves it (it says
+// `loads`, or its module declares `tools`), a resource names it (a process, a step, an archive), or
+// it is the runtime itself. One reached by none of them was built, recorded and pushed as success,
+// and was simply absent — seven modules' tools went missing that way on 2026-10-03. Refused here,
+// naming the field that would deliver it.
+func undeliveredBundles(m Manifest) []string {
+	if m.Build == nil || m.Module == RuntimeModule {
+		return nil
+	}
+	named := runByAResource(m)
+	var problems []string
+	for _, a := range m.Build.Artifacts {
+		if a.Kind != ArtifactBundle || named[a.Name] || len(a.Loads) > 0 || len(m.Tools) > 0 {
+			continue
+		}
+		problems = append(problems, fmt.Sprintf(
+			"%s: the bundle %q would be built and never reach a machine: nothing loads it, runs it or "+
+				"unpacks it. A tools bundle says `loads` (the entrypoints the node's runtime serves) or its "+
+				"module lists its `tools`; a daemon or a step is a resource naming it (novox/hq 04-ISSUES/216)",
+			m.Module, a.Name))
+	}
+	return problems
+}

go/catalogue/build_system_test.go

@@ -0,0 +1,82 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// bundleFor is a manifest whose one artifact is a bundle in the given language and system.
+func bundleFor(language, system string) Manifest {
+	return Manifest{Module: "a-component", Build: &Build{Artifacts: []Artifact{
+		{Name: "binary", Kind: ArtifactBundle, Language: language, System: system},
+	}}}
+}
+
+func problemsOf(t *testing.T, m Manifest) string {
+	t.Helper()
+	return strings.Join(m.Build.problems(m.Module), "\n")
+}
+
+// **A language that compiles to a binary must say which system.**
+//
+// A binary is pinned to one operating system at link time, so a host refuses to touch a machine it
+// was not built for. An artifact that says nothing would be compiled for whatever the build machine
+// happened to be — which reads as portable and is not, and is the fault this check exists for.
+func TestABinaryMustSayWhichSystemItIsFor(t *testing.T) {
+	got := problemsOf(t, bundleFor("go", ""))
+	if !strings.Contains(got, "says no system") {
+		t.Fatalf("a compiled bundle with no system was accepted:\n%s", got)
+	}
+	// And the refusal names what it could have said, so a reader is one edit from right.
+	for _, system := range []string{"alpine", "android", "arch"} {
+		if !strings.Contains(got, system) {
+			t.Fatalf("the refusal does not name %q as a choice:\n%s", system, got)
+		}
+	}
+}
+
+func TestABinaryThatNamesASystemIsAccepted(t *testing.T) {
+	if got := problemsOf(t, bundleFor("go", "arch")); got != "" {
+		t.Fatalf("a compiled bundle naming a system was refused:\n%s", got)
+	}
+}
+
+// A system the mesh does not build for is refused where it is written. These are the host's own
+// names, not a compiler's: the difference between two of them is a C library rather than a kernel,
+// so a value that looks like an operating system to a toolchain is still wrong here.
+func TestASystemTheMeshDoesNotBuildForIsRefused(t *testing.T) {
+	for _, wrong := range []string{"linux", "debian", "darwin"} {
+		got := problemsOf(t, bundleFor("go", wrong))
+		if !strings.Contains(got, "and a system is") {
+			t.Fatalf("%q was accepted as a system:\n%s", wrong, got)
+		}
+	}
+}
+
+// **And a language that runs anywhere must not name one.** A system that decides nothing reads as
+// though it did, which is the same fault as a restriction that restricts nothing (novox/hq ADR 0045).
+func TestAPortableBundleMayNotNameASystem(t *testing.T) {
+	got := problemsOf(t, bundleFor("typescript", "arch"))
+	if !strings.Contains(got, "runs anywhere") {
+		t.Fatalf("a portable bundle was allowed to name a system:\n%s", got)
+	}
+}
+
+func TestAPortableBundleNamingNoSystemIsAccepted(t *testing.T) {
+	if got := problemsOf(t, bundleFor("typescript", "")); got != "" {
+		t.Fatalf("an ordinary bundle was refused:\n%s", got)
+	}
+}
+
+// One component, one artifact per system: the shape the mesh's own binaries are declared in, and the
+// reason the target is the artifact's rather than the recipe's.
+func TestOneArtifactPerSystemIsAccepted(t *testing.T) {
+	m := Manifest{Module: "the-host", Build: &Build{Artifacts: []Artifact{
+		{Name: "arch", Kind: ArtifactBundle, Language: "go", System: "arch"},
+		{Name: "alpine", Kind: ArtifactBundle, Language: "go", System: "alpine"},
+		{Name: "android", Kind: ArtifactBundle, Language: "go", System: "android"},
+	}}}
+	if got := problemsOf(t, m); got != "" {
+		t.Fatalf("one artifact per system was refused:\n%s", got)
+	}
+}

go/catalogue/build_test.go

@@ -0,0 +1,203 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The manifest in a repository and the manifest the mesh holds are two documents.
+//
+// A digest is not knowable until something is built, so a repository carrying one would be a
+// repository whose file is wrong the moment anybody edits anything — and the mesh would be pinning
+// a value nobody could have checked.
+
+func buildable() Manifest {
+	return Manifest{
+		Module: "meshboard", Version: "1",
+		Build: &Build{Artifacts: []Artifact{
+			{Name: "server", Kind: ArtifactImage, From: "Dockerfile"},
+			{Name: "theme", Kind: ArtifactArchive, From: "files"},
+		}},
+		Resources: []map[string]any{
+			{"id": "svc", "type": "container", "name": "meshboard", "artifact": "server"},
+			{"id": "look", "type": "archive", "path": "/opt/meshboard", "artifact": "theme"},
+			{"id": "dir", "type": "directory", "path": "/opt/meshboard"},
+		},
+	}
+}
+
+func wasBuilt() []Built {
+	return []Built{
+		{Name: "server", Kind: ArtifactImage,
+			Reference: "registry.invalid/meshboard@sha256:" + strings.Repeat("a", 64)},
+		{Name: "theme", Kind: ArtifactArchive,
+			Reference: "https://store.invalid/theme.tar.gz",
+			Digest:    "sha256:" + strings.Repeat("b", 64)},
+	}
+}
+
+func TestAResourceNamingAnArtifactBecomesOneNamingTheThing(t *testing.T) {
+	got, err := buildable().Resolve(wasBuilt())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range got.Resources {
+		if r["artifact"] != nil {
+			// A build-time word the host has never heard of. Leaving it would be a field the
+			// strict decoder refuses on the machine, at the worst moment.
+			t.Fatalf("%v still names an artifact: %v", r["id"], r)
+		}
+	}
+	if got.Resources[0]["image"] != "registry.invalid/meshboard@sha256:"+strings.Repeat("a", 64) {
+		t.Fatalf("the image was not filled in: %v", got.Resources[0])
+	}
+	if got.Resources[1]["source"] != "https://store.invalid/theme.tar.gz" ||
+		got.Resources[1]["digest"] != "sha256:"+strings.Repeat("b", 64) {
+		t.Fatalf("the archive was not filled in: %v", got.Resources[1])
+	}
+	// And a resource that names nothing is untouched.
+	if got.Resources[2]["path"] != "/opt/meshboard" || len(got.Resources[2]) != 3 {
+		t.Fatalf("an ordinary resource was changed: %v", got.Resources[2])
+	}
+	// The built manifest carries no build section: it is the derived document, and something
+	// holding both would invite somebody to build from it again.
+	if got.Build != nil {
+		t.Fatal("the built manifest still says how to build itself")
+	}
+}
+
+func TestAnArtifactDeclaredAndNotBuiltIsRefused(t *testing.T) {
+	// A build that did not do what the manifest asked. Said here rather than by a machine later
+	// reporting an empty image.
+	_, err := buildable().Resolve(wasBuilt()[:1])
+	if err == nil {
+		t.Fatal("a manifest resolved with an artifact missing")
+	}
+	if !strings.Contains(err.Error(), "theme") {
+		t.Fatalf("the refusal does not name what is missing: %v", err)
+	}
+	// And it must blame the build rather than the resource. A resource asking for something that
+	// does not exist is a manifest fault; a build not producing what the manifest declared is a
+	// build fault, and telling somebody to fix the wrong one costs an afternoon.
+	if !strings.Contains(err.Error(), "the build did not produce") {
+		t.Fatalf("the refusal blames the wrong thing: %v", err)
+	}
+}
+
+func TestAResourceNamingSomethingTheModuleDoesNotBuildIsRefused(t *testing.T) {
+	m := buildable()
+	m.Resources = append(m.Resources,
+		map[string]any{"id": "other", "type": "archive", "path": "/x", "artifact": "nothing"})
+	if _, err := m.Resolve(wasBuilt()); err == nil {
+		t.Fatal("a resource naming an artifact nobody builds was accepted")
+	}
+}
+
+func TestAModuleThatBuildsNothingIsOrdinary(t *testing.T) {
+	// Most of what a person installs is configuration. Requiring an empty build section would be
+	// a field that exists to be left blank.
+	m := Manifest{Module: "shell", Version: "1", Resources: []map[string]any{
+		{"id": "rc", "type": "file", "path": "/etc/zsh/zshrc", "content": "setopt"},
+	}}
+	got, err := m.Resolve(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Resources) != 1 {
+		t.Fatalf("got %v", got.Resources)
+	}
+}
+
+func TestTwoArtifactsWithOneNameAreRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+		{"name":"x","kind":"image","from":"Dockerfile"},
+		{"name":"x","kind":"archive","from":"files"}]}}`))
+	if err == nil {
+		t.Fatal("two artifacts with one name were accepted")
+	}
+	if !strings.Contains(err.Error(), "could mean either") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+func TestAnArtifactBuiltFromOutsideItsRepositoryIsRefused(t *testing.T) {
+	// A build reads its own repository and nothing else. A path leaving it would make what gets
+	// built depend on whatever happens to be on the machine doing the building.
+	for _, from := range []string{"/etc/passwd", "../elsewhere"} {
+		_, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+			{"name":"x","kind":"archive","from":"` + from + `"}]}}`))
+		if err == nil {
+			t.Fatalf("%q was accepted as a build input", from)
+		}
+		if !strings.Contains(err.Error(), "outside its own repository") {
+			t.Fatalf("refused for the wrong reason: %v", err)
+		}
+	}
+}
+
+func TestAnArtifactOfAnUnknownKindIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+		{"name":"x","kind":"binary","from":"main.go"}]}}`))
+	if err == nil {
+		t.Fatal("an artifact of an unknown kind was accepted")
+	}
+}
+
+func TestAPackageParsesLikeABundleAndNeedsALanguage(t *testing.T) {
+	// The SDK's shape: a package built from the module's own directory, naming a language.
+	m, err := ParseManifest([]byte(`{"module":"mesh-sdk","version":"1","slug":"sdk",
+		"build":{"artifacts":[{"name":"lib","kind":"package","language":"typescript"}]},
+		"resources":[]}`))
+	if err != nil {
+		t.Fatalf("the SDK's package manifest did not parse: %v", err)
+	}
+	if m.Build.Artifacts[0].Kind != ArtifactPackage {
+		t.Fatalf("expected a package artifact, got %q", m.Build.Artifacts[0].Kind)
+	}
+
+	// A package that names what it is built from is refused, exactly as a bundle is: it is built
+	// from the module's own directory.
+	if _, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+		{"name":"lib","kind":"package","language":"typescript","from":"Dockerfile"}]}}`)); err == nil {
+		t.Fatal("a package naming a source was accepted")
+	}
+	// A package with no language cannot choose a toolchain.
+	if _, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+		{"name":"lib","kind":"package"}]}}`)); err == nil {
+		t.Fatal("a package with no language was accepted")
+	}
+}
+
+func TestAResourceNamingAPackageIsRefused(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"a","version":"1","slug":"a",
+		"build":{"artifacts":[{"name":"lib","kind":"package","language":"typescript"}]},
+		"resources":[{"id":"svc","type":"container","name":"a","artifact":"lib"}]}`))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	_, err = m.Resolve([]Built{{Name: "lib", Kind: ArtifactPackage, Reference: "@novox/a@1.0.0"}})
+	if err == nil {
+		t.Fatal("a resource backed by a package was accepted; a package is not a resource")
+	}
+}
+
+// An image names the Go package its recipe compiles (novox/hq ADR 0267): within the tree it is built in,
+// and only an image says one.
+func TestOnlyAnImageNamesThePackageItCompilesWithinItsTree(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[
+		{"name":"x","kind":"image","from":"Dockerfile","compiles":"cmd/x"}]}}`))
+	if err != nil || m.Build.Artifacts[0].Compiles != "cmd/x" {
+		t.Fatalf("an image naming its package was refused or lost it: %v", err)
+	}
+	for _, c := range []struct{ artifact, says string }{
+		{`{"name":"x","kind":"archive","from":"files","compiles":"cmd/x"}`, "Only an image"},
+		{`{"name":"x","kind":"image","from":"Dockerfile","compiles":"../x"}`, "leaves the tree"},
+		{`{"name":"x","kind":"image","from":"Dockerfile","compiles":"/x"}`, "leaves the tree"},
+		{`{"name":"x","kind":"image","from":"Dockerfile","compiles":"a/../../x"}`, "leaves the tree"},
+	} {
+		_, err := ParseManifest([]byte(`{"module":"a","version":"1","build":{"artifacts":[` + c.artifact + `]}}`))
+		if err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: %v, wanted a refusal saying %q", c.artifact, err, c.says)
+		}
+	}
+}

go/catalogue/bus_snapshot_test.go

@@ -0,0 +1,80 @@
+package catalogue
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// The module holding mesh-broker is the bus, and its account is granted the bus's snapshot API and
+// nothing else (novox/hq ADR 0235). Anything it declared to say or hear on the bus would be granted
+// nothing, so it is refused at the parser rather than silently dropped.
+func TestTheBussAccountSaysNothingOnTheBus(t *testing.T) {
+	raw := []byte(`{"module":"bus","version":"1","provides":[{"name":"mesh-bus","scope":"mesh"}],
+		"claims":[{"name":"mesh-broker","scope":"mesh"}],"own-secrets":{"broker":"/run/broker"},
+		"emits":["something.happened"]}`)
+	_, err := ParseManifest(raw)
+	if err == nil || !strings.Contains(err.Error(), "granted the bus's snapshot API and nothing else") {
+		t.Fatalf("a bus module declaring what it emits was not refused, or not for the reason: %v", err)
+	}
+
+	// Its tools bundle says what it emits (novox/hq ADR 0357): the node's runtime carries the bundle and is
+	// granted the module's events, so a bus module that ships one may declare them.
+	bundled := []byte(`{"module":"bus","version":"1","provides":[{"name":"mesh-bus","scope":"mesh"}],
+		"claims":[{"name":"mesh-broker","scope":"mesh"}],"own-secrets":{"broker":"/run/broker"},
+		"emits":["bus.slow-consumer"],"tools":["bus_streams"],
+		"build":{"artifacts":[{"name":"tools","kind":"bundle","language":"go","system":"arch","from":"cmd/t","binary":"t"}]}}`)
+	if _, err := ParseManifest(bundled); err != nil {
+		t.Fatalf("a bus module whose tools bundle declares what it emits was refused: %v", err)
+	}
+
+	quiet := []byte(`{"module":"bus","version":"1","provides":[{"name":"mesh-bus","scope":"mesh"}],
+		"claims":[{"name":"mesh-broker","scope":"mesh"}],"own-secrets":{"broker":"/run/broker"},
+		"tools":["bus_streams"]}`)
+	m, err := ParseManifest(quiet)
+	if err != nil {
+		t.Fatalf("a bus module with an account and tools was refused: %v", err)
+	}
+	if !m.ClaimsSeat(BrokerSeat) {
+		t.Fatal("it does not read as holding the broker seat")
+	}
+}
+
+// The catalogue's bus protects its streams by the snapshot, not as live files: its streams' item is a
+// dump into its snapshots, it has the account the dump runs as, and the dump runs the snapshot
+// program in the bus's own container.
+func TestTheCataloguesBusIsBackedUpBySnapshot(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join(beside.Catalogue(t), "nats", "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, account := m.OwnSecrets["broker"]; !account {
+		t.Fatal("the bus declares no account, so its snapshot could not reach it")
+	}
+	var found bool
+	if m.Data == nil {
+		t.Fatal("the bus declares no data")
+	}
+	for _, it := range m.Data.Own {
+		if it.ID != "jetstream" {
+			continue
+		}
+		found = true
+		if !it.Backup.IsDump() || it.Backup.Into != "snapshots" {
+			t.Fatalf("the bus's streams are protected by %+v, not a snapshot into its snapshots", it.Backup)
+		}
+		if !strings.Contains(it.Backup.Dump, "mesh-nats-snapshot snapshot") {
+			t.Fatalf("the dump does not run the snapshot program: %s", it.Backup.Dump)
+		}
+	}
+	if !found {
+		t.Fatal("the bus declares no item for its streams")
+	}
+}

go/catalogue/busy.go

@@ -0,0 +1,124 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+)
+
+// A long-running container may say it is busy (novox/hq ADR 0335 §1).
+//
+// **Beside its health, on the container**: a command run inside it, by its shell, as an exec health check
+// is, that exits 0 while the container holds work a replacement would lose and non-zero when it is idle;
+// and how long one ask may take. Being asked is also its notice that it is about to be replaced: from the
+// first ask it takes no new work. The node-engine asks before it replaces the container, leaves it running
+// while it says busy, and replaces it on the first pass it says idle, or at 15 minutes — the engine's bound,
+// never the module's.
+//
+// Sent only to a node-engine that reads it (link.BusyContract): an older, strict engine refuses a field it
+// does not know, whole, and to it the container is replaced at once, as before.
+
+// BusyField is the resource field.
+const BusyField = "busy"
+
+// The bounds of one ask (ADR 0335), the node-engine's own, held here near the author.
+const (
+	BusyTimeoutDefault = 10 * time.Second
+	BusyTimeoutCeiling = time.Minute
+)
+
+// Busy is one container's busy, read.
+type Busy struct {
+	Command string
+	Timeout time.Duration
+}
+
+// ReadBusy reads a resource's `busy` field, its default applied. False when it carries none.
+func ReadBusy(r map[string]any) (Busy, bool, []string) {
+	raw, present := r[BusyField]
+	if !present {
+		return Busy{}, false, nil
+	}
+	id := fmt.Sprint(r["id"])
+	fields, ok := raw.(map[string]any)
+	if !ok {
+		return Busy{}, true, []string{fmt.Sprintf("%s: busy is %T; it is an object with a command", id, raw)}
+	}
+	var problems []string
+	keys := make([]string, 0, len(fields))
+	for k := range fields {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		if k != "command" && k != "timeout" {
+			problems = append(problems, fmt.Sprintf("%s: its busy says %q; busy has a command and a timeout", id, k))
+		}
+	}
+	b := Busy{Timeout: BusyTimeoutDefault}
+	if v, has := fields["command"]; has {
+		s, ok := v.(string)
+		if !ok {
+			problems = append(problems, fmt.Sprintf("%s: its busy's command is %T; it is text", id, v))
+		}
+		b.Command = strings.TrimSpace(s)
+	}
+	if v, has := fields["timeout"]; has {
+		s, _ := v.(string)
+		d, err := time.ParseDuration(strings.TrimSpace(s))
+		switch {
+		case err != nil:
+			problems = append(problems, fmt.Sprintf("%s: its busy's timeout is %v; it is a duration such as \"10s\"", id, v))
+		case d <= 0 || d > BusyTimeoutCeiling:
+			problems = append(problems, fmt.Sprintf("%s: an ask of its busy takes more than nothing and at most %s, not %s",
+				id, BusyTimeoutCeiling, d))
+		default:
+			b.Timeout = d
+		}
+	}
+	return b, true, problems
+}
+
+// busyProblems is everything wrong with a manifest's `busy` fields, in the manifest's words: a command on
+// one line, a timeout within its bounds, and only on a container that stays up.
+func busyProblems(m Manifest) []string {
+	var problems []string
+	for _, r := range m.Resources {
+		b, has, read := ReadBusy(r)
+		if !has {
+			continue
+		}
+		where := m.Module + ": " + fmt.Sprint(r["id"])
+		for _, p := range read {
+			problems = append(problems, m.Module+": "+p)
+		}
+		if fmt.Sprint(r["type"]) != "container" || !LongRunning(r) {
+			problems = append(problems, fmt.Sprintf("%s declares busy and is not a container that stays up: busy is "+
+				"asked of a running container before it is replaced (ADR 0335)", where))
+		}
+		if b.Command == "" {
+			problems = append(problems, where+"'s busy names no command: one run inside the container, exiting 0 "+
+				"while it is busy")
+		}
+		if strings.ContainsAny(b.Command, "\n\r") {
+			problems = append(problems, where+"'s busy command is one line")
+		}
+	}
+	return problems
+}
+
+// busyInto composes a container's `busy` into the node-engine's words, or takes it away: for an engine that
+// reads it, the command and its timeout written out; for one that does not, the field is not sent, and the
+// container is replaced at once, as before.
+func busyInto(resource map[string]any, with Rendering) {
+	if _, has := resource[BusyField]; !has {
+		return
+	}
+	if !with.ReadsBusy {
+		delete(resource, BusyField)
+		return
+	}
+	b, _, _ := ReadBusy(resource)
+	resource[BusyField] = map[string]any{"command": b.Command, "timeout": b.Timeout.String()}
+}

go/catalogue/busy_test.go

@@ -0,0 +1,94 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/validate"
+)
+
+// A long-running container may say it is busy (novox/hq ADR 0335 §1): `module check` holds the field to its
+// shape near its author, and it is sent only to a node-engine that reads it, in words the engine's own
+// validator accepts.
+
+func busyManifest(t *testing.T, on string, busy any) []byte {
+	t.Helper()
+	extra := map[string]any{"id": "agent", "type": "container", "name": "app-agent",
+		"image": "registry.example/app" + healthDigest}
+	var m map[string]any
+	if err := json.Unmarshal(healthManifest(t, "", nil, extra), &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m["resources"].([]any) {
+		if r := r.(map[string]any); r["id"] == on {
+			r[BusyField] = busy
+		}
+	}
+	out, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func TestABusyIsHeldToItsShape(t *testing.T) {
+	if _, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "mesh-builder busy"})); err != nil {
+		t.Fatalf("a well-formed busy was refused: %v", err)
+	}
+	if _, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "x", "timeout": "30s"})); err != nil {
+		t.Fatalf("a busy with its timeout was refused: %v", err)
+	}
+	for name, c := range map[string]struct {
+		on   string
+		busy any
+		says string
+	}{
+		"text":           {"agent", "mesh-builder busy", "it is an object"},
+		"no command":     {"agent", map[string]any{"timeout": "5s"}, "names no command"},
+		"two lines":      {"agent", map[string]any{"command": "a\nb"}, "one line"},
+		"a long timeout": {"agent", map[string]any{"command": "x", "timeout": "5m"}, "at most 1m0s"},
+		"an unknown key": {"agent", map[string]any{"command": "x", "every": "1m"}, `says "every"`},
+		"on a step":      {"seed", map[string]any{"command": "x"}, "not a container that stays up"},
+		"on a service":   {"daemon", map[string]any{"command": "x"}, "not a container that stays up"},
+	} {
+		_, err := ParseManifest(busyManifest(t, c.on, c.busy))
+		if err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: want a refusal saying %q, got %v", name, c.says, err)
+		}
+	}
+}
+
+func TestABusyIsSentOnlyToAnEngineThatReadsIt(t *testing.T) {
+	m, err := ParseManifest(busyManifest(t, "agent", map[string]any{"command": "mesh-builder busy"}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	compose := func(with Rendering) []map[string]any {
+		out, err := Resolution{Node: "laptop", Modules: []Manifest{m}}.Declaration(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return out
+	}
+	older := compose(Rendering{})
+	if b, sent := older[indexOfID(older, "app.agent")][BusyField]; sent {
+		t.Fatalf("busy was sent to an engine that does not read it: %v", b)
+	}
+	newer := compose(Rendering{ReadsBusy: true})
+	got, _ := newer[indexOfID(newer, "app.agent")][BusyField].(map[string]any)
+	if got["command"] != "mesh-builder busy" || got["timeout"] != "10s" {
+		t.Fatalf("busy composed as %v", got)
+	}
+	// And the engine's own validator takes the container with it.
+	body, err := json.Marshal(map[string]any{"declaration": validate.Version, "resources": newer})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if problems := validate.Declaration(body); len(problems) > 0 {
+		t.Fatalf("the node-engine's validator refuses the composed busy: %v", problems)
+	}
+	if _, has := m.Resources[len(m.Resources)-1][BusyField].(map[string]any)["timeout"]; has {
+		t.Error("composing wrote the timeout into the catalogue's own manifest")
+	}
+}

go/catalogue/catalogue_check_test.go

@@ -0,0 +1,122 @@
+package catalogue
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// TestEveryCatalogueManifestParses runs the real catalogue through the real gate.
+//
+// Not a fixture: the point is whether the manifests as written are accepted by the control plane that
+// will read them, and a copy of one manifest proves nothing about the other seventy-one.
+// catalogueRoot is the catalogue these checks run over: in a merge check the clone the build seat put
+// beside this one, elsewhere the copy captured in testdata/beside (internal/beside). A check that only
+// ran when somebody remembered a variable was a check nobody ran (novox/hq issue 134), and one that read
+// whatever checkout sat beside judged the machine, not the change (novox/hq issue 432): it never skips.
+func catalogueRoot(t *testing.T) string {
+	t.Helper()
+	return beside.Dir(t, "mesh-catalog")
+}
+
+func TestEveryCatalogueManifestParses(t *testing.T) {
+	_, found := catalogueManifests(t)
+	named, routed := 0, 0
+	for _, r := range found {
+		m, err := r.manifest, r.err
+		if err != nil {
+			t.Errorf("%s: %v", filepath.Base(filepath.Dir(r.path)), err)
+			continue
+		}
+		for _, l := range m.Listens {
+			if l.Name != "" {
+				named++
+			}
+		}
+		for port := range RoutedPorts(m) {
+			_ = port
+			routed++
+		}
+	}
+	t.Logf("%d manifests, %d named endpoints, %d routed endpoints resolved", len(found), named, routed)
+	if named == 0 {
+		t.Fatal("no endpoint in the catalogue is named, so this proved nothing")
+	}
+}
+
+// TestNoCatalogueManifestNamesAnInstallation is ADR 0112's check, run over the real catalogue: no
+// definition names a domain or a public address the mesh acts on, and every value that must for now
+// carries its reason (novox/hq ADR 0155, issue 134). The list it prints is the one that shrinks.
+func TestNoCatalogueManifestNamesAnInstallation(t *testing.T) {
+	_, found := catalogueManifests(t)
+	var named []string
+	for _, r := range found {
+		m, err := r.manifest, r.err
+		if err != nil {
+			t.Errorf("%s: %v", r.path, err)
+			continue
+		}
+		named = append(named, InstallationProblems(m)...)
+	}
+	if len(named) > 0 {
+		t.Fatalf("%d value(s) name an installation:\n  %s", len(named), strings.Join(named, "\n  "))
+	}
+}
+
+// TestEveryCatalogueModuleDeclaresItsData is ADR 0233's check over the real catalogue (it replaced ADR
+// 0214's store list): every provider that grants says what it keeps for its consumers, nothing writes a
+// backup line by hand, every directory a container writes is declared, and every irreplaceable item is
+// backed up — so a store added is a store backed up, without a list of stores to keep in step.
+func TestEveryCatalogueModuleDeclaresItsData(t *testing.T) {
+	_, found := catalogueManifests(t)
+	shelf := Shelf{}
+	granting := 0
+	for _, r := range found {
+		m, err := r.manifest, r.err
+		if err != nil {
+			continue // TestEveryCatalogueManifestParses says why
+		}
+		if len(m.Grants) > 0 {
+			granting++
+		}
+		shelf[m.Module] = m
+	}
+	for _, problem := range DataProblems(shelf) {
+		t.Error(problem)
+	}
+	if granting == 0 {
+		t.Fatal("no module in the catalogue grants a provision, so this proved nothing")
+	}
+}
+
+// TestEveryCatalogueIdentityFitsWhatItRequires is ADR 0225's check over the real catalogue: every
+// module's identity, on the longest machine name, fits the bound of every provision it wants. An
+// overflow fails here, in the pull request that introduces it, rather than on the provider's machine
+// the first time a real machine's name meets the module's (issue 263).
+func TestEveryCatalogueIdentityFitsWhatItRequires(t *testing.T) {
+	_, found := catalogueManifests(t)
+	shelf := Shelf{}
+	for _, r := range found {
+		m, err := r.manifest, r.err
+		if err != nil {
+			t.Fatalf("%s: %v", r.path, err)
+		}
+		shelf[m.Module] = m
+	}
+	for _, p := range IdentityProblems(shelf, DefaultLongestMachine) {
+		t.Error(p)
+	}
+	// The night it was found: the resolver provision bounds nothing, and the object store still 20.
+	if dns, ok := shelf["dnsmasq"]; ok {
+		if b := dns.IdentityBoundOf("wildcard-resolution"); b.Bounded() {
+			t.Errorf("the resolver provision bounds its consumers' identities: %+v", b)
+		}
+	}
+	if store, ok := shelf["minio"]; ok {
+		if b := store.IdentityBoundOf("s3-bucket"); b.Max != 20 {
+			t.Errorf("the object store's access key is not bounded at 20: %+v", b)
+		}
+	}
+}

go/catalogue/catalogue_read_test.go

@@ -0,0 +1,44 @@
+package catalogue
+
+import (
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+// readManifest is one manifest of the catalogue as ReadTreeManifest read it.
+type readManifest struct {
+	path     string // the module.json
+	manifest Manifest
+	err      error
+}
+
+var (
+	readOnce sync.Once
+	readAll  []readManifest
+	readRoot string
+)
+
+// catalogueManifests is every manifest of the catalogue (catalogueRoot), read through ReadTreeManifest once
+// per test binary and not once per test: the checks over the real catalogue each read and parsed every
+// manifest again, and together took 1.5 s of mesh-sdk's unit bound of 2 s (issue 1756). What it returns is
+// shared and read-only: a test that changes a manifest copies it first.
+func catalogueManifests(t *testing.T) (string, []readManifest) {
+	t.Helper()
+	root := catalogueRoot(t)
+	readOnce.Do(func() {
+		readRoot = root
+		found, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+		if err != nil {
+			return
+		}
+		for _, p := range found {
+			m, err := ReadTreeManifest(root, filepath.Dir(p))
+			readAll = append(readAll, readManifest{path: p, manifest: m, err: err})
+		}
+	})
+	if len(readAll) == 0 {
+		t.Fatalf("no manifests under %s", root)
+	}
+	return readRoot, readAll
+}

go/catalogue/catrust_manifest_test.go

@@ -0,0 +1,69 @@
+package catalogue
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// **A machine trusts the mesh's authority because a module put its root there** (novox/hq ADR
+// 0147, issue 129). The module carries a shell script and a unit, and both are worthless unless
+// the mesh fills in where the authority is — which is the one thing about it the manifest cannot
+// state, because the authority's address is a fact about the mesh and not about the module.
+//
+// So what is checked here is the rendering, not the parsing: the script the machine will run
+// names the authority it was bound to, and the unit runs that script both ways. The verification
+// itself — a plain client trusting an internal name on a machine holding this, and failing on one
+// that does not — is the lab's, and cannot be had here.
+func TestCaTrustRendersTheAuthorityItWasBoundTo(t *testing.T) {
+	m, err := ReadTreeManifest(beside.Dir(t, "mesh-catalog"), filepath.Join(beside.Catalogue(t), "ca-trust"))
+	if err != nil {
+		t.Fatalf("the trust module does not parse:\n%v", err)
+	}
+
+	r := Resolution{
+		Node:    "workstation",
+		Modules: []Manifest{m},
+		Needs: []Needed{{
+			Name: "internal-acme-ca", From: "anchor", At: "anchor.internal", For: "ca-trust",
+			Serves: map[string]any{
+				"port": float64(9000), "path": "/acme/acme/directory", "roots": "/roots.pem",
+			},
+		}},
+	}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatalf("the trust module could not be composed for a machine: %v", err)
+	}
+
+	script := fileNamed(out, "ca-trust.anchor")
+	if script == nil {
+		t.Fatalf("nothing writes the script the unit runs: %v", out)
+	}
+	body, _ := script["content"].(string)
+	if !strings.Contains(body, "https://anchor.internal:9000/roots.pem") {
+		t.Errorf("the script does not fetch from the authority it was bound to:\n%s", body)
+	}
+	if script["mode"] != "0755" {
+		t.Errorf("the script is written %v, which systemd cannot execute", script["mode"])
+	}
+
+	unit := fileNamed(out, "ca-trust.unit")
+	if unit == nil {
+		t.Fatalf("no unit: %v", out)
+	}
+	text, _ := unit["content"].(string)
+	// Both halves. A unit that only installs the anchor leaves a machine trusting an authority
+	// nobody assigned it to any more, which is the half issue 129 asked for by name.
+	for _, want := range []string{
+		"ExecStart=" + script["path"].(string) + " install",
+		"ExecStop=" + script["path"].(string) + " remove",
+		"RemainAfterExit=yes",
+	} {
+		if !strings.Contains(text, want) {
+			t.Errorf("the unit does not say %q:\n%s", want, text)
+		}
+	}
+}

go/catalogue/chosen.go

@@ -0,0 +1,100 @@
+package catalogue
+
+import (
+	"sort"
+)
+
+// Chosen is the provider somebody named for a provision: the module, and the node it runs on. Both,
+// always (novox/hq #258) — a provision comes from a module, and the same module on two machines is
+// two answers, so neither half alone says which. Module is empty only on a record made before this
+// was asked, and such a record is honoured exactly as long as it is unambiguous.
+type Chosen struct {
+	Node   string
+	Module string
+}
+
+func (c Chosen) String() string {
+	if c.Module == "" {
+		return c.Node
+	}
+	return c.Node + "/" + c.Module
+}
+
+// matches is whether this provider is the one chosen.
+func (c Chosen) matches(p Provider) bool {
+	return p.Node == c.Node && (c.Module == "" || p.Module == c.Module)
+}
+
+// among is every offered provider the choice names — one, when the choice is whole.
+func (c Chosen) among(where []Provider) []Provider {
+	var out []Provider
+	for _, p := range where {
+		if c.matches(p) {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// nameOf is how a refusal names a provider: the node and the module on it.
+func nameOf(p Provider) string {
+	return Chosen{Node: p.Node, Module: p.Module}.String()
+}
+
+// providerNames is every provider named, sorted, for a refusal to list.
+func providerNames(where []Provider) []string {
+	out := make([]string, 0, len(where))
+	for _, p := range where {
+		out = append(out, nameOf(p))
+	}
+	sort.Strings(out)
+	return out
+}
+
+// providersHere is which modules in this node's own set offer a provision, sorted.
+func providersHere(catalogue map[string]Manifest, here func(string) bool, want string) []string {
+	var out []string
+	for name, m := range catalogue {
+		if !here(name) {
+			continue
+		}
+		for _, o := range m.Offers() {
+			if o == want {
+				out = append(out, name)
+				break
+			}
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// servedByOne is what one provider beside the consumer says a consumer needs to know, or nothing.
+//
+// Serving is *whether* a need is created at all when the provider is on this same machine (novox/hq
+// 04-ISSUES/038's sibling): a need never created is a binding the consumer never gets. The manifest
+// alone answers that; the values are settled later, with the node's settings.
+func servedByOne(m Manifest, want string) map[string]any {
+	if _, ok := m.Serves[want]; ok {
+		return ServedOn(m, want, nil)
+	}
+	return nil
+}
+
+// sharedByOne is the own secret that provider names as its credential (ADR 0158), or "" when it
+// gives each consumer its own.
+func sharedByOne(m Manifest, want string) string {
+	if own, shared := m.SharedCredentialOf(want); shared {
+		return own
+	}
+	return ""
+}
+
+func oneOf(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}

go/catalogue/co_located_test.go

@@ -0,0 +1,315 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A provider and its consumer on ONE machine, which is what ADR 0066's anchor is.
+//
+// **Every fault in this file is the same shape: the same-node path diverging from the cross-node
+// one.** A provider on another machine is walked by the control plane — its served facts are
+// re-derived from its manifest with that machine's port assignments and settled with that node's
+// settings layers — and only then handed to the consumer. A provider on the consumer's OWN machine
+// never passes through that walk, so every step of it had to be repeated here, and each step that
+// was not is a promise the co-located arrangement quietly breaks.
+//
+// 04-ISSUES/038 was the first of them (the port). These are the rest.
+
+// A root certificate, as a certificate authority serves one: a real, self-signed one made for these tests (its key
+// thrown away), because the one setting that may hold lines must parse as a certificate (novox/hq issue 339).
+const servedRoot = `-----BEGIN CERTIFICATE-----
+MIIBPjCB8aADAgECAhRZG3p93hUUB5bz00uxhYo/nJnTQjAFBgMrZXAwFDESMBAG
+A1UEAwwJdGVzdCByb290MCAXDTI2MTAwODIyMjE0NloYDzIxMjYwOTE0MjIyMTQ2
+WjAUMRIwEAYDVQQDDAl0ZXN0IHJvb3QwKjAFBgMrZXADIQA0pt/ld+W0MXwBhPfO
+cuAt56kIW6Qcn+4vqWpuvHTiqaNTMFEwHQYDVR0OBBYEFIjgaLk4OVGIOeZQiqnN
+p9vhciFjMB8GA1UdIwQYMBaAFIjgaLk4OVGIOeZQiqnNp9vhciFjMA8GA1UdEwEB
+/wQFMAMBAf8wBQYDK2VwA0EAl9uWeSM2XAV8u0reyV3BLRxNVik+4FCRO1QKPs2k
+IlB1rK9oAOYManH+VFuBMI/JJ31ajSti81q4E0CSw8r5DQ==
+-----END CERTIFICATE-----
+`
+
+// stepCA is an internal ACME authority: it answers `acme-ca` from anywhere in the mesh, and what a
+// consumer must know is the directory URL and the root to trust. **The root is not knowable when
+// the module is written** — it exists only once the CA has been initialised — so the manifest
+// declares the key and the operator supplies the value as a setting, which is exactly the shape the
+// cross-node path settles and the same-node path did not.
+func stepCA() Manifest {
+	return Manifest{
+		Module: "step-ca", Version: "1",
+		Provides: FromAnywhere("acme-ca"),
+		Listens:  []Listening{{Port: 9000, Protocol: "tcp", From: FromMesh}},
+		Serves: map[string]map[string]any{"acme-ca": {
+			"directory": "https://anchor.internal/acme/acme/directory",
+			// Declared empty: a manifest is the same on every mesh, and this mesh's root is not.
+			"root": "",
+		}},
+		Resources: []map[string]any{{
+			"id": "server", "type": "container", "name": "step-ca", "ports": []any{"9000"},
+		}},
+	}
+}
+
+// stepCAWithItsRoot is the authority whose root the operator supplies: the served key asks for it as
+// `${setting:root}` (ADR 0155), the only way a setting reaches what a provider serves since a layer
+// stopped replacing a served key (novox/hq issue 696; before it, the empty `root` was replaced whole).
+func stepCAWithItsRoot() Manifest {
+	m := stepCA()
+	m.Serves["acme-ca"]["root"] = "${setting:root}"
+	return m
+}
+
+// routeProxy issues from that authority, so it must be told the root to verify it with.
+func routeProxy() Manifest {
+	return Manifest{
+		Module: "route-proxy", Version: "1",
+		Requires: []string{"acme-ca"},
+		Provides: FromAnywhere("route"),
+		Binds:    map[string]string{"acme-ca": "/var/lib/route-proxy/acme-ca.json"},
+		Receives: map[string]string{"route": "/var/lib/route-proxy/routes.json"},
+		Resources: []map[string]any{{
+			"id": "bundle", "type": "file", "path": "/var/lib/route-proxy/ca.pem", "mode": "0644",
+			"content": "${bound:acme-ca:root}",
+		}},
+	}
+}
+
+// A co-located provider's served VALUES reach its consumer, not just its served keys.
+//
+// The mesh walks a provider on ANOTHER machine and settles what it serves with that node's settings
+// layers before offering it (cmd/mesh-controller plan.go, theRestOfTheMesh). A provider on the
+// consumer's own machine was never settled at all: resolve.go's servedHere and declaration.go's
+// here() both read the manifest and stop there. So a served value the operator supplied — the one
+// kind of value a manifest cannot carry, because it is different on every mesh — arrived as the
+// manifest's empty default.
+//
+// The consequence is silent and total: route-proxy wrote an empty CA bundle, fell back to the
+// system trust store, could not verify the internal authority, and no certificate was ever issued.
+func TestACoLocatedProvidersServedValuesReachItsConsumer(t *testing.T) {
+	r, err := Resolve(shelf(stepCAWithItsRoot(), routeProxy()),
+		[]string{"step-ca", "route-proxy"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// What the operator set on the provider, on this node — the CA's root, which only exists once
+	// the CA has been initialised.
+	out, err := r.Declaration(Rendering{Settings: SettingsBy{
+		"step-ca": {{From: "the operator", Values: map[string]any{"root": servedRoot}}},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	bundle := fileNamed(out, "route-proxy.bundle")
+	if bundle == nil {
+		t.Fatalf("the consumer was given no bundle at all: %v", out)
+	}
+	if got := bundle["content"]; got != servedRoot {
+		t.Errorf("the co-located consumer was not told the root it must trust:\n got %q\nwant %q",
+			got, servedRoot)
+	}
+}
+
+// And the binding file says the same thing, for a consumer that reads the binding rather than a
+// substituted placeholder. The two are one fact and must not be able to disagree.
+func TestACoLocatedConsumersBindingCarriesTheSettledValues(t *testing.T) {
+	r, err := Resolve(shelf(stepCAWithItsRoot(), routeProxy()),
+		[]string{"step-ca", "route-proxy"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{
+		Settings: SettingsBy{
+			"step-ca": {{From: "the operator", Values: map[string]any{"root": servedRoot}}},
+		},
+		// And the machine moved the provider's port while it was at it, so both halves of the
+		// cross-node derivation are exercised at once.
+		Ports: map[string]map[int]int{"step-ca": {9000: 19000}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	binding := fileNamed(out, "route-proxy.bound-acme-ca")
+	if binding == nil {
+		t.Fatalf("the consumer was given no binding at all: %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["root"] != servedRoot {
+		t.Errorf("the binding does not carry the settled root: %q", said.Serves["root"])
+	}
+	if port, _ := asPort(said.Serves["port"]); port != 19000 {
+		t.Errorf("the binding does not carry the port the machine publishes: %v", said.Serves["port"])
+	}
+}
+
+// A provider PULLED IN rather than assigned is settled the same way.
+//
+// The resolver's same-node need is built during the walk, from whichever modules had been chosen by
+// the time the requirement came up — so which path a co-located binding took depended on the order
+// a person happened to assign things in. Settling after the closure is known removes that: both
+// orders now produce the same file.
+func TestACoLocatedProviderIsSettledWhicheverWayItWasPulledIn(t *testing.T) {
+	for _, assigned := range [][]string{
+		{"step-ca", "route-proxy"},
+		{"route-proxy", "step-ca"},
+	} {
+		r, err := Resolve(shelf(stepCAWithItsRoot(), routeProxy()), assigned, reachable(), World{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		out, err := r.Declaration(Rendering{Settings: SettingsBy{
+			"step-ca": {{From: "the operator", Values: map[string]any{"root": servedRoot}}},
+		}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		bundle := fileNamed(out, "route-proxy.bundle")
+		if bundle == nil || bundle["content"] != servedRoot {
+			t.Errorf("assigned %v: the consumer was not told the root", assigned)
+		}
+	}
+}
+
+// A same-node contribution names the port the MACHINE publishes, not the one the module declared.
+//
+// 04-ISSUES/038 fixed this for what a consumer is TOLD about a provider. This is the other
+// direction: what a workload TELLS the provider about itself. gitea declares a bare container port
+// 3000, the mesh publishes it as 20000:3000 — and gitea's route contribution still said 3000, so
+// the proxy beside it dialled a port nothing listens on and answered 502 for every request.
+//
+// The redirect uses the CONTRIBUTING module's assignment: the port belongs to the workload, and
+// using the provider's map would move it to wherever the proxy happens to be published.
+func TestASameNodeContributionNamesThePortTheMachinePublishes(t *testing.T) {
+	gitea := Manifest{
+		Module: "gitea", Version: "1",
+		Listens:     []Listening{{Port: 3000, Protocol: "tcp", From: FromMesh}},
+		Contributes: map[string]map[string]any{"route": {"label": "git", "port": 3000}},
+		Resources: []map[string]any{{
+			"id": "server", "type": "container", "name": "gitea", "ports": []any{"3000"},
+		}},
+	}
+	r, err := Resolve(shelf(gitea, routeProxy(), stepCA()),
+		[]string{"gitea", "route-proxy", "step-ca"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{
+		// The machine put gitea's 3000 on 20000, and published it that way.
+		Ports: map[string]map[int]int{"gitea": {3000: 20000}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Where the workload is actually published.
+	server := fileNamed(out, "gitea.server")
+	if published := strings.Join(asStrings(server["ports"]), ","); published != "20000:3000" {
+		t.Fatalf("the workload was not published on the assigned port: %v", server["ports"])
+	}
+
+	// What the proxy beside it was told to dial: the SAME port.
+	routes := fileNamed(out, "route-proxy.received-route")
+	if routes == nil {
+		t.Fatalf("the proxy was given no routes file at all: %v", out)
+	}
+	var given struct {
+		Given []Contribution `json:"given"`
+	}
+	if err := json.Unmarshal([]byte(routes["content"].(string)), &given); err != nil {
+		t.Fatal(err)
+	}
+	if len(given.Given) != 1 {
+		t.Fatalf("expected one route, got %v", given.Given)
+	}
+	port, ok := asPort(given.Given[0].Values["port"])
+	if !ok || port != 20000 {
+		t.Errorf("the proxy was told to dial a port nothing listens on: %v",
+			given.Given[0].Values["port"])
+	}
+}
+
+// A contribution from ANOTHER machine is left exactly as it was.
+//
+// Its port belongs to that machine's assignment, which this node's map knows nothing about —
+// applying this node's map to it would move a remote workload's port to wherever a local module of
+// the same name happens to be published, which is worse than the fault being fixed.
+func TestAContributionFromAnotherMachineKeepsItsOwnPort(t *testing.T) {
+	r, err := Resolve(shelf(routeProxy(), stepCA()),
+		[]string{"route-proxy", "step-ca"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := r.Declaration(Rendering{
+		// A same-named module on this machine, moved. The grant below is a laptop's, and must not
+		// be dragged along with it.
+		Ports: map[string]map[int]int{"gitea": {3000: 20000}},
+		Grants: []Grant{{
+			Provision: "route", Consumer: "laptop", From: "gitea", At: "laptop.internal",
+			Values: map[string]any{"name": "git.example", "port": 3000},
+		}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	routes := fileNamed(out, "route-proxy.received-route")
+	var given struct {
+		Given []Contribution `json:"given"`
+	}
+	if err := json.Unmarshal([]byte(routes["content"].(string)), &given); err != nil {
+		t.Fatal(err)
+	}
+	if len(given.Given) != 1 {
+		t.Fatalf("expected one route, got %v", given.Given)
+	}
+	if port, _ := asPort(given.Given[0].Values["port"]); port != 3000 {
+		t.Errorf("another machine's contribution was rewritten with this machine's ports: %v",
+			given.Given[0].Values["port"])
+	}
+}
+
+// The cross-node half of the same fault: a grant assembled on the providing machine carries the
+// consumer's declared port until the CONSUMER's machine's assignments are applied to it. The
+// declaration layer cannot do it — those assignments are not this machine's, which is the line the
+// test above holds — so the grant layer is handed them and does it there.
+func TestAContributionIsRedirectedToWhereItsOwnMachinePublishedIt(t *testing.T) {
+	published := map[int]int{3000: 20000}
+
+	got := AtPublishedPort(map[string]any{"name": "git.example.tld", "port": 3000}, "forge", published)
+	if port, _ := asPort(got["port"]); port != 20000 {
+		t.Errorf("the proxy would dial a port that machine never published: %v", got["port"])
+	}
+	if got["name"] != "git.example.tld" {
+		t.Errorf("redirecting the port disturbed the rest of the contribution: %v", got)
+	}
+
+	// Idempotent, and silent about a port nobody moved: a module that pinned its own mapping has no
+	// assignment, and must come back exactly as it was written.
+	again := AtPublishedPort(got, "forge", published)
+	if port, _ := asPort(again["port"]); port != 20000 {
+		t.Errorf("applying it twice moved the port again: %v", again["port"])
+	}
+	pinned := AtPublishedPort(map[string]any{"port": 9070}, "office", published)
+	if port, _ := asPort(pinned["port"]); port != 9070 {
+		t.Errorf("a port the mesh never assigned was rewritten: %v", pinned["port"])
+	}
+}
+
+func asStrings(v any) []string {
+	listed, ok := v.([]any)
+	if !ok {
+		return nil
+	}
+	out := make([]string, 0, len(listed))
+	for _, one := range listed {
+		out = append(out, strings.TrimSpace(plainly(one)))
+	}
+	return out
+}

go/catalogue/collections.go

@@ -0,0 +1,635 @@
+package catalogue
+
+import (
+	"fmt"
+	"path"
+	"regexp"
+	"slices"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Collections (novox/hq ADR 0349 clause 13, design 57 L1, issue 684): a provision with many providers.
+//
+// **A collector requires a collection; a contributor provides an item from a template.** A module taking additions
+// from others names a collection in a file of its own, `${collected:<collection>}`, and declares it under
+// `collections`, with the comment its tool writes a line in. Each contributor ships its item as a template of its
+// own repository and declares it under `items`: `{"collection": …, "template": "files/<name>"}`. Its build packs the
+// template with the module's others, and the mesh holds its text as it holds a file's (template.go).
+//
+// **The node's provisioner client fills both.** An item is filled on the node by the client of the node its
+// contributor is placed on, from the same owners as a file, and recorded in mesh-provisioner_collect; a collector's
+// file is filled by the same client from every item of its collection recorded for that node, so an item goes when
+// its contributor leaves. So a module contributing an item is a moved module (handed.go), and the controller renders
+// no item: the plan of a contributor names its items and their templates, and the plan of a collector names each
+// collection it reads and its comment. Neither carries a contributor's text.
+//
+// **The three old namespaces read as collections.** `${shell:<shell>:<slot>}`, `${environment:<format>}` and
+// `${contribution:<seat>:<kind>}` name, in a handed collector's file, the collection of the same name —
+// `shell:zsh:normal` — with the comment the controller wrote before each module's piece. An item is contributed to
+// one by that name, by a module the old form would have let contribute it. Each file is filled one way, never
+// both (ADR 0349 clause 17): a handed collector is filled from items alone and an unhanded one from the old forms
+// alone, and a piece of the other form on the same machine is said as not placed, never dropped quietly.
+
+// Item is one item a module contributes to a collection: its template in the module's repository, or, in the
+// manifest the mesh holds, the template's text, read back from the build's templates archive like a file's.
+//
+// **Attributes, a capability and a name** (design 57 L3, issue 777): an item may carry `attributes` (string keys and
+// values; `order`, a whole number 0–99 defaulting to 50, orders the items of one placeholder) and `if-capability`,
+// the capability a machine must report for the item to be placed on it. A module may give several items to one
+// collection, each then with a `name` unique within the module and the collection. A collector takes only the items
+// whose attributes match, `${collected:<collection>:<k>=<v>,…}`, and all of them without the selector.
+type Item struct {
+	Collection   string            `json:"collection"`
+	Name         string            `json:"name,omitempty"`
+	Template     string            `json:"template,omitempty"`
+	Content      string            `json:"content,omitempty"`
+	Attributes   map[string]string `json:"attributes,omitempty"`
+	IfCapability string            `json:"if-capability,omitempty"`
+}
+
+// ItemKey is an item's key among its module's: the collection, and `/<name>` for a named item.
+func ItemKey(collection, name string) string {
+	if name == "" {
+		return collection
+	}
+	return collection + "/" + name
+}
+
+func (it Item) key() string { return ItemKey(it.Collection, it.Name) }
+
+// order is the item's place among the items of one placeholder: its `order` attribute, or OrderDefault.
+func (it Item) order() int {
+	if n, err := strconv.Atoi(it.Attributes[OrderAttribute]); err == nil && n >= 0 && n <= 99 {
+		return n
+	}
+	return OrderDefault
+}
+
+// OrderAttribute is the attribute that orders items.
+const OrderAttribute = "order"
+
+// matches is whether the item's attributes carry every pair of the selector.
+func (it Item) matches(where map[string]string) bool {
+	for k, v := range where {
+		if got, has := it.Attributes[k]; !has || got != v {
+			return false
+		}
+	}
+	return true
+}
+
+// itemsInOrder is the module's items by order, then name; the order the old form placed a module's pieces in.
+func itemsInOrder(items []Item) []Item {
+	out := append([]Item(nil), items...)
+	sort.SliceStable(out, func(a, b int) bool {
+		if oa, ob := out[a].order(), out[b].order(); oa != ob {
+			return oa < ob
+		}
+		return out[a].Name < out[b].Name
+	})
+	return out
+}
+
+// Collection is one collection a module collects, and the comment its tool writes a line in: each contributor's item
+// is introduced by `<comment> <contributor>`, and by nothing without one.
+type Collection struct {
+	Name    string `json:"name"`
+	Comment string `json:"comment,omitempty"`
+}
+
+// CollectedNamespace is a collection's placeholder namespace, `${collected:<collection>}`.
+const CollectedNamespace = "collected"
+
+// EnvironmentCollection is the one collection of the session environment (design 57 L3, issue 795): its items are
+// typed by attributes, a variable (`kind=variable`, `name`) or a PATH entry (`kind=path`, `at=start|end`), and the
+// template's text is the value or the entry. A collector names the rendering, `${collected:environment:posix}` or
+// `${collected:environment:systemd}`, which is not a selector.
+const EnvironmentCollection = "environment"
+
+// oldCollectionNamespaces are the namespaces read as collections of their own name.
+var oldCollectionNamespaces = []string{"shell", "environment", "contribution"}
+
+var (
+	// ofCollected is where a collector places a collection. Loose inside the braces, so a misspelt name is refused.
+	ofCollected = regexp.MustCompile(`\$\{collected:([^}]*)\}`)
+	// collectionName is words joined by colons, so an old namespace's placeholder names its collection as it reads.
+	collectionName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*(:[a-z0-9][a-z0-9-]*)*$`)
+	// itemName, attributeKey and attributeValue are the words an item's name and attributes are made of; none holds
+	// a colon, a comma or an equals sign, which tell a selector from a collection's name.
+	itemName       = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+	attributeKey   = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
+	attributeValue = regexp.MustCompile(`^[a-z0-9][a-z0-9_.-]*$`)
+)
+
+// splitSelector is a placeholder's name without its selector, and the selector: `widgets:bar=top,place=left` is
+// `widgets` and `bar=top,place=left`. A collection's name holds no `=`, so the selector begins at the last colon
+// before the first one.
+func splitSelector(name string) (collection, selector string) {
+	eq := strings.Index(name, "=")
+	if eq < 0 {
+		return name, ""
+	}
+	colon := strings.LastIndex(name[:eq], ":")
+	if colon < 0 {
+		return name, ""
+	}
+	return name[:colon], name[colon+1:]
+}
+
+// selectorOf is a selector's pairs, or why it is none.
+func selectorOf(selector string) (map[string]string, error) {
+	out := map[string]string{}
+	if selector == "" {
+		return out, nil
+	}
+	for _, pair := range strings.Split(selector, ",") {
+		k, v, ok := strings.Cut(pair, "=")
+		switch {
+		case !ok || !attributeKey.MatchString(k) || !attributeValue.MatchString(v):
+			return nil, fmt.Errorf("%q in %q is not <attribute>=<value>", pair, selector)
+		case out[k] != "":
+			return nil, fmt.Errorf("%q names %s twice", selector, k)
+		}
+		out[k] = v
+	}
+	return out, nil
+}
+
+// collectionOfPlaceholder is the collection a placeholder's namespace and key name, and whether they name one.
+func collectionOfPlaceholder(namespace, key string) (string, bool) {
+	key, _ = splitSelector(key)
+	switch {
+	case namespace == CollectedNamespace && strings.HasPrefix(key, EnvironmentCollection+":"):
+		// The environment is one collection, and the rest of the name picks the rendering (issue 795).
+		return EnvironmentCollection, true
+	case namespace == CollectedNamespace:
+		return key, true
+	case namespace == "environment":
+		return EnvironmentCollection, true
+	case slices.Contains(oldCollectionNamespaces, namespace):
+		return namespace + ":" + key, true
+	}
+	return "", false
+}
+
+// oldCollection is an old namespace's collection by its name: its comment, or why no item may be contributed to it.
+// ok is false for a name that is not an old namespace's.
+//
+// forItem is whether an item is to be contributed to it: an item may be contributed to a kind received as data,
+// which a collector may place as a collection only where its shape says its pieces are text (design 57 L3).
+func oldCollection(name string, forItem bool) (comment string, old bool, wrong error) {
+	namespace, key, _ := strings.Cut(name, ":")
+	if !slices.Contains(oldCollectionNamespaces, namespace) {
+		return "", false, nil
+	}
+	switch namespace {
+	case "shell":
+		target, slot, two := strings.Cut(key, ":")
+		if !two || !oneOf(contributionTargets(), target) || !oneOf(knownSlots, slot) {
+			return "", true, fmt.Errorf("%s is no slot: shell code is shell:<shell>:<slot>, the shell one of %s, "+
+				"the session's file one of %s or the power moment one of %s, and the slot one of %s", name,
+				strings.Join(knownShells, ", "), strings.Join(sessionFiles, ", "), strings.Join(powerMoments, ", "),
+				strings.Join(knownSlots, ", "))
+		}
+		// shellCode's line before each module's code.
+		return "#", true, nil
+	case "environment":
+		if key == "" {
+			// The collection itself, which an item is contributed to; a placeholder names a rendering.
+			return "#", true, nil
+		}
+		if key != EnvironmentPOSIX && key != EnvironmentSystemd {
+			return "", true, fmt.Errorf("%s is no format: the environment is environment:%s or environment:%s",
+				name, EnvironmentPOSIX, EnvironmentSystemd)
+		}
+		return "#", true, nil
+	}
+	seat, kind, _ := strings.Cut(key, ":")
+	s, r, ok := receivable(seat, kind)
+	switch {
+	case !ok && s.Name == "":
+		return "", true, fmt.Errorf("%s names the seat %q, which the mesh does not define", name, seat)
+	case !ok:
+		return "", true, fmt.Errorf("%s: %s; %s", name, s.Name, kindsOf(s))
+	case r.Shape != nil && (forItem || collectableAsText(r)):
+		return r.Comment, true, nil
+	case r.Shape != nil:
+		return "", true, fmt.Errorf("%s is received by %s as data in its own shape, which no item of text is "+
+			"(novox/hq ADR 0255)", name, s.Name)
+	case r.Dirs:
+		return "", true, fmt.Errorf("%s names its contributors' directories, which the holder reads as paths "+
+			"the controller fills; it is not yet a collection (design 57 L1)", name)
+	case s.Name != canonicalSeat(seat):
+		return "", true, fmt.Errorf("%s names the seat by another name; a collection names it %s", name, s.Name)
+	}
+	return r.Comment, true, nil
+}
+
+// placerOfOld is the seat whose holder alone may collect an old namespace's collection (ADR 0203, 0204, 0208,
+// 0211, 0212): the same seat that places it the old way.
+func placerOfOld(name string) string {
+	namespace, key, _ := strings.Cut(name, ":")
+	switch namespace {
+	case "shell":
+		target, _, _ := strings.Cut(key, ":")
+		return placerOf(target)
+	case "environment":
+		return EnvironmentSeat
+	}
+	seat, _, _ := strings.Cut(key, ":")
+	return canonicalSeat(seat)
+}
+
+// collectionProblems is what is wrong with a module's collections and items, from the manifest alone.
+func collectionProblems(m Manifest) []string {
+	var problems []string
+	declared := map[string]bool{}
+	for i, c := range m.Collections {
+		switch {
+		case !collectionName.MatchString(c.Name):
+			problems = append(problems, fmt.Sprintf("%s's collection %d is %q, which is not a collection's name: "+
+				"words of lower-case letters, digits and hyphens, joined by colons", m.Module, i+1, c.Name))
+		case declared[c.Name]:
+			problems = append(problems, fmt.Sprintf("%s collects %s twice", m.Module, c.Name))
+		}
+		if _, old, _ := oldCollection(c.Name, false); old {
+			problems = append(problems, fmt.Sprintf("%s collects %s, which is read from its placeholder: a module "+
+				"places it as ${%s} where it holds the seat that places it, and declares nothing", m.Module, c.Name,
+				c.Name))
+		}
+		if strings.ContainsAny(c.Comment, "\n\r") {
+			problems = append(problems, fmt.Sprintf("%s's collection %s has a comment holding a line break",
+				m.Module, c.Name))
+		}
+		declared[c.Name] = true
+	}
+	// A collection declared and placed nowhere is a word read by nothing; judged where every file's text is here.
+	if !m.Templated() {
+		named := map[string]bool{}
+		for _, r := range m.Resources {
+			if text, ok := r["content"].(string); ok {
+				for _, f := range ofCollected.FindAllStringSubmatch(text, -1) {
+					base, _ := splitSelector(f[1])
+					named[base] = true
+				}
+			}
+		}
+		for _, c := range m.Collections {
+			if !named[c.Name] && collectionName.MatchString(c.Name) {
+				problems = append(problems, fmt.Sprintf("%s collects %s and no file of its places it as "+
+					"${collected:%s}", m.Module, c.Name, c.Name))
+			}
+		}
+	}
+	contributed := map[string]bool{}
+	for i, it := range m.Items {
+		where := fmt.Sprintf("%s's item %d", m.Module, i+1)
+		if !collectionName.MatchString(it.Collection) {
+			problems = append(problems, fmt.Sprintf("%s is to %q, which is not a collection's name", where,
+				it.Collection))
+		} else if _, old, wrong := oldCollection(it.Collection, true); old && wrong != nil {
+			problems = append(problems, fmt.Sprintf("%s: %v", where, wrong))
+		}
+		switch {
+		case it.Name != "" && !itemName.MatchString(it.Name):
+			problems = append(problems, fmt.Sprintf("%s: the name %q is not a name: lower-case letters, digits and "+
+				"hyphens", where, it.Name))
+		case contributed[it.key()]:
+			problems = append(problems, fmt.Sprintf("%s contributes to %s twice; a module contributes one item to "+
+				"a collection, or several each with a name of its own", m.Module, it.key()))
+		case it.Name == "" && slices.ContainsFunc(m.Items, func(o Item) bool {
+			return o.Collection == it.Collection && o.Name != ""
+		}):
+			problems = append(problems, fmt.Sprintf("%s contributes several items to %s and %s has no name; each "+
+				"of several items has a name of its own", m.Module, it.Collection, where))
+		}
+		contributed[it.key()] = true
+		problems = append(problems, itemAttributeProblems(m.Module, where, it)...)
+		if it.Collection == EnvironmentCollection {
+			problems = append(problems, environmentItemProblems(where, it)...)
+		}
+		switch {
+		case it.Template == "" && it.Content == "":
+			problems = append(problems, fmt.Sprintf("%s names no template: an item is a template of the module's "+
+				"own, \"template\": \"%s/<name>\" (novox/hq ADR 0349 §13)", where, m.TemplatesDir()))
+		case it.Template != "" && it.Content != "":
+			problems = append(problems, fmt.Sprintf("%s names its template and says its content too", where))
+		case it.Template != "":
+			if wrong := itemTemplateProblem(m, it.Template); wrong != "" {
+				problems = append(problems, fmt.Sprintf("%s: %s", where, wrong))
+			}
+			// **Filled by the provisioner's client alone**: the controller renders no item.
+			if !m.Moved {
+				problems = append(problems, fmt.Sprintf("%s: an item is filled by the provisioner's client of the "+
+					"node its contributor is placed on, so a module contributing one is marked moved "+
+					"(\"moved\": true; novox/hq ADR 0349 §13, §17)", where))
+			}
+		}
+		if it.Content != "" {
+			problems = append(problems, itemTextProblems(m.Module, it)...)
+		}
+	}
+	return problems
+}
+
+// itemAttributeProblems is what is wrong with an item's attributes and capability. The attributes of an item of a kind
+// received as data are the fields its shape places by (and `order`), each with a value the shape takes.
+func itemAttributeProblems(module, where string, it Item) []string {
+	var problems []string
+	for _, k := range sortedKeys(it.Attributes) {
+		v := it.Attributes[k]
+		switch {
+		case !attributeKey.MatchString(k):
+			problems = append(problems, fmt.Sprintf("%s: the attribute %q is not a name: lower-case letters, digits "+
+				"and hyphens", where, k))
+			continue
+		case !attributeFits(it.Collection, k, v):
+			problems = append(problems, fmt.Sprintf("%s: %s=%q is not a value: lower-case letters, digits, hyphens, "+
+				"dots and underscores (an environment variable's name, letters, digits and underscores)", where, k, v))
+			continue
+		}
+		if n, err := strconv.Atoi(v); k == OrderAttribute && (err != nil || n < 0 || n > 99) {
+			problems = append(problems, fmt.Sprintf("%s: order=%q is not a whole number from 0 to 99", where, v))
+		}
+	}
+	if namespace, key, _ := strings.Cut(it.Collection, ":"); namespace == "contribution" {
+		seat, kind, _ := strings.Cut(key, ":")
+		if _, r, ok := receivable(seat, kind); ok && r.Shape != nil {
+			for _, k := range sortedKeys(it.Attributes) {
+				var place *PlaceField
+				for i := range r.Shape.Places {
+					if r.Shape.Places[i].Field == k {
+						place = &r.Shape.Places[i]
+					}
+				}
+				switch {
+				case k == OrderAttribute:
+				case place == nil:
+					problems = append(problems, fmt.Sprintf("%s: %s is placed by %s, and %q is none of them", where,
+						it.Collection, placeFields(r), k))
+				case !oneOf(place.Values, it.Attributes[k]):
+					problems = append(problems, fmt.Sprintf("%s: %s=%s; %s is one of %s", where, k, it.Attributes[k], k,
+						strings.Join(place.Values, ", ")))
+				}
+			}
+		}
+	}
+	switch {
+	case it.IfCapability == "":
+	case !capabilityName.MatchString(it.IfCapability):
+		problems = append(problems, fmt.Sprintf("%s: if-capability %q is not a capability's name", where, it.IfCapability))
+	case !oneOf(KnownCapabilities, it.IfCapability):
+		problems = append(problems, fmt.Sprintf("%s: if-capability %q is one no machine reports; the node-engine "+
+			"detects %s", where, it.IfCapability, strings.Join(KnownCapabilities, ", ")))
+	}
+	return problems
+}
+
+// AttributeFits is whether an item's attribute is of the shape its collection allows: words of lower case, except
+// the environment's `name`, which is a variable's name (design 57 L3, issue 795). The same rule is mesh-catalog's
+// provisioner client's, and the inventory's.
+func attributeFits(collection, k, v string) bool {
+	if collection == EnvironmentCollection && k == "name" {
+		return variableName.MatchString(v)
+	}
+	return attributeKey.MatchString(k) && attributeValue.MatchString(v)
+}
+
+// environmentItemProblems is what is wrong with an item of the environment collection: typed by `kind`, a variable
+// with its `name`, a PATH entry `at` the start or the end, and no attribute besides `order`.
+func environmentItemProblems(where string, it Item) []string {
+	var problems []string
+	for _, k := range sortedKeys(it.Attributes) {
+		if !slices.Contains([]string{"kind", "name", "at", OrderAttribute}, k) {
+			problems = append(problems, fmt.Sprintf("%s: %s is typed by kind, name and at, and %q is none of them",
+				where, it.Collection, k))
+		}
+	}
+	switch kind := it.Attributes["kind"]; kind {
+	case "variable":
+		if it.Attributes["name"] == "" || it.Attributes["at"] != "" {
+			problems = append(problems, fmt.Sprintf("%s: a variable names itself with name=<NAME> and has no at", where))
+		} else if it.Attributes["name"] == "PATH" {
+			problems = append(problems, fmt.Sprintf("%s: PATH is not a variable; a PATH entry is kind=path", where))
+		}
+	case "path":
+		if it.Attributes["name"] != "" || (it.Attributes["at"] != PathAtStart && it.Attributes["at"] != PathAtEnd) {
+			problems = append(problems, fmt.Sprintf("%s: a PATH entry is at=%s or at=%s and has no name", where,
+				PathAtStart, PathAtEnd))
+		}
+	default:
+		problems = append(problems, fmt.Sprintf("%s: an item of %s is kind=variable or kind=path, not %q", where,
+			it.Collection, kind))
+	}
+	return problems
+}
+
+// itemTemplateProblem is what is wrong with an item's template path, or "".
+func itemTemplateProblem(m Manifest, name string) string {
+	dir := m.TemplatesDir()
+	if strings.HasPrefix(name, "/") || path.Clean(name) != name || !strings.HasPrefix(name, dir+"/") ||
+		strings.Contains(name, "\\") {
+		return fmt.Sprintf("the template %q is not a file under %s/ of its own repository: a template is %q, a "+
+			"plain relative path, and the build packs only %s/", name, dir, dir+"/<name>", dir)
+	}
+	return ""
+}
+
+// itemTextProblems is what an item's text may not name: a secret or a bound value, since an item is kept in a
+// bucket and no secret is (ADR 0349 clause 7), and a collection, since an item is not a collector. And every
+// placeholder no pass fills, as in a file's content.
+func itemTextProblems(module string, it Item) []string {
+	var problems []string
+	for _, f := range templatePlaceholder.FindAllStringSubmatch(it.Content, -1) {
+		namespace, key := f[1], f[2]
+		switch _, collection := collectionOfPlaceholder(namespace, key); {
+		case namespace == "secret" || namespace == "bound":
+			problems = append(problems, fmt.Sprintf("%s's item of %s names %s: an item is kept in a bucket, where "+
+				"no secret is (novox/hq ADR 0349 §7)", module, it.Collection, f[0]))
+		case collection:
+			problems = append(problems, fmt.Sprintf("%s's item of %s names %s: an item is not a collector",
+				module, it.Collection, f[0]))
+		}
+	}
+	return append(problems, unconsumedPlaceholders(module, map[string]any{"id": "item:" + it.key(),
+		"type": "file", "content": it.Content})...)
+}
+
+// isOld is whether a collection's name is an old namespace's.
+func isOld(name string) bool {
+	_, old, _ := oldCollection(name, true)
+	return old
+}
+
+// collectedPlaceholderProblems is what is wrong with one resource's ${collected:…}: placed only in a file's content,
+// and naming a collection the module declares it collects.
+func collectedPlaceholderProblems(m Manifest, r map[string]any) []string {
+	var problems []string
+	for _, field := range sortedKeys(r) {
+		v, ok := r[field].(string)
+		if !ok {
+			continue
+		}
+		for _, f := range ofCollected.FindAllStringSubmatch(v, -1) {
+			base, selector := splitSelector(f[1])
+			if _, err := selectorOf(selector); err != nil {
+				problems = append(problems, fmt.Sprintf("%s's resource %v names %s: %v", m.Module, r["id"], f[0], err))
+				continue
+			}
+			switch {
+			case field != "content":
+				problems = append(problems, fmt.Sprintf("%s's resource %v names %s in its %s; a collection is placed "+
+					"only in a file's content", m.Module, r["id"], f[0], field))
+			case isOld(base):
+				if _, _, wrong := oldCollection(base, false); wrong != nil {
+					problems = append(problems, fmt.Sprintf("%s's resource %v names %s: %v", m.Module, r["id"], f[0], wrong))
+				}
+			case !slices.ContainsFunc(m.Collections, func(c Collection) bool { return c.Name == base }):
+				problems = append(problems, fmt.Sprintf("%s's resource %v names %s, and %s does not collect %q: "+
+					"declare it under collections (novox/hq ADR 0349 §13)", m.Module, r["id"], f[0], m.Module, base))
+			}
+		}
+	}
+	return problems
+}
+
+// collectionComment is the comment of a collection a module's file names: declared, or the old namespace's.
+func collectionComment(m Manifest, name string) (string, error) {
+	if comment, old, wrong := oldCollection(name, false); old {
+		return comment, wrong
+	}
+	for _, c := range m.Collections {
+		if c.Name == name {
+			return c.Comment, nil
+		}
+	}
+	return "", fmt.Errorf("%s names ${collected:%s} and does not collect it", m.Module, name)
+}
+
+// itemsLeftOut says each item of a collection a file is filled with the old way that the controller could not render
+// there (heldItemText): the collector is not handed to the provisioner on this machine (ADR 0349 clause 17). Said,
+// never dropped quietly.
+func itemsLeftOut(modules []Manifest, holder Manifest, collection string, facts map[string]string) []string {
+	return itemsLeftOutFor(modules, holder, collection, nil, facts, nil)
+}
+
+// itemsLeftOutFor is itemsLeftOut for a placeholder that selects by attributes (where), on a machine with these
+// capabilities: an item the selector does not take, or whose capability the machine lacks, is not left out but not
+// wanted here.
+func itemsLeftOutFor(modules []Manifest, holder Manifest, collection string, where map[string]string,
+	facts map[string]string, caps map[string]bool) []string {
+	var out []string
+	for _, m := range inModuleOrder(modules) {
+		for _, it := range itemsInOrder(m.Items) {
+			if it.Collection != collection || !it.matches(where) || (it.IfCapability != "" && !caps[it.IfCapability]) {
+				continue
+			}
+			if _, rendered := heldText(it, facts); rendered && renderedOldWay(collection) {
+				continue
+			}
+			out = append(out, fmt.Sprintf("%s's item of %s is not placed: %s is filled the old way on this "+
+				"machine, from contributions, and an item only by the provisioner's client (design 57 L1)",
+				m.Module, it.key(), holder.Module))
+		}
+	}
+	return out
+}
+
+// oldFormsLeftOut says each piece of an old form a handed collector's collections would have held: the collector is
+// filled from items alone, and the piece's module contributes none (ADR 0349 clause 17).
+func oldFormsLeftOut(modules []Manifest, holder Manifest, collections []PlanCollection) []string {
+	var out []string
+	for _, c := range collections {
+		namespace, key, _ := strings.Cut(c.Name, ":")
+		for _, m := range inModuleOrder(modules) {
+			old := false
+			switch namespace {
+			case "shell":
+				target, slot, _ := strings.Cut(key, ":")
+				old = slices.ContainsFunc(m.Shell, func(s ShellCode) bool { return s.For == target && s.Slot == slot })
+			case "environment":
+				old = m.Environment != nil && (len(m.Environment.Variables) > 0 || len(m.Environment.Path) > 0)
+			case "contribution":
+				seat, kind, _ := strings.Cut(key, ":")
+				old = slices.ContainsFunc(m.allContributions(), func(s SeatContribution) bool {
+					return canonicalSeat(s.Seat) == canonicalSeat(seat) && s.Kind == kind
+				})
+			}
+			if old {
+				out = append(out, fmt.Sprintf("%s's %s is not placed: %s is filled by the provisioner's client on "+
+					"this machine, from items, and %s contributes it the old way (design 57 L1)", m.Module, c.Name,
+					holder.Module, m.Module))
+			}
+		}
+	}
+	return out
+}
+
+// heldItemText is a moved contributor's items of an old namespace's collection as the controller renders them into a
+// collector not handed on this machine (design 57 L2, issue 681): the text the mesh holds, read back from the
+// contributor's templates archive, with the machine's facts filled, each ending its line. As a moved module's file
+// keeps its text for a machine that cannot take it handed (handed.go), an item keeps its place in a collector filled
+// the old way, so the file stays what its old form made it. Only `shell:` and `contribution:` collections, which the
+// controller renders as text; false for a module with no such item, or an item whose text the mesh does not hold or
+// which names anything but a machine fact this machine has, which is then said as not placed.
+func heldItemText(m Manifest, collection string, facts map[string]string) (string, bool) {
+	items := heldItems(m, collection, nil, facts, nil)
+	var b strings.Builder
+	for _, h := range items {
+		b.WriteString(h.text)
+	}
+	return b.String(), len(items) > 0
+}
+
+// renderedOldWay is whether the controller renders a collection's items into a collector not handed.
+func renderedOldWay(collection string) bool {
+	namespace, _, _ := strings.Cut(collection, ":")
+	return namespace == "shell" || namespace == "contribution" || namespace == EnvironmentCollection
+}
+
+// heldItem is one item of a module rendered the old way.
+type heldItem struct {
+	item Item
+	text string
+}
+
+// heldItems is a module's items of the collection that the selector takes and the machine's capabilities allow, by
+// order then name, each rendered as heldText does; the ones it cannot render are left out (itemsLeftOutFor says so).
+func heldItems(m Manifest, collection string, where map[string]string, facts map[string]string,
+	caps map[string]bool) []heldItem {
+	if !renderedOldWay(collection) {
+		return nil
+	}
+	var out []heldItem
+	for _, it := range itemsInOrder(m.Items) {
+		if it.Collection != collection || !it.matches(where) || (it.IfCapability != "" && !caps[it.IfCapability]) {
+			continue
+		}
+		if text, ok := heldText(it, facts); ok {
+			out = append(out, heldItem{item: it, text: text})
+		}
+	}
+	return out
+}
+
+// heldText is an item's text with the machine's facts filled, ending its line; false for an item whose text the mesh
+// does not hold or which names anything but a machine fact this machine has.
+func heldText(it Item, facts map[string]string) (string, bool) {
+	if it.Content == "" {
+		return "", false
+	}
+	text := it.Content
+	for _, f := range templatePlaceholder.FindAllStringSubmatch(text, -1) {
+		value, has := facts[f[2]]
+		if f[1] != "machine" || !has {
+			return "", false
+		}
+		text = strings.ReplaceAll(text, f[0], value)
+	}
+	if !strings.HasSuffix(text, "\n") {
+		text += "\n"
+	}
+	return text, true
+}

go/catalogue/collections_bar_test.go

@@ -0,0 +1,135 @@
+package catalogue
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+// A bar's blocks are a collection of text (design 57 L3, issue 781): the holder of node-bar names the kind as
+// `${collected:contribution:node-bar:block:bar=<b>,place=<p>}`, which a handed collector has its client fill from the
+// items and an unhanded one has the controller fill as it fills the old placeholder.
+
+const (
+	collectedBarsText = "top\n${collected:contribution:node-bar:block:bar=top,place=status}" +
+		"bottom\n${collected:contribution:node-bar:block:bar=bottom,place=status}"
+	collectedBars = `{"module":"bars","version":"1","moved":true,
+  "claims":[{"name":"node-bar","scope":"node","renders":{"block":"{{.shows}}"}}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"conf","type":"file","path":"/etc/bars.conf","template":"files/bars"}]}`
+	itemsOfPower = `{"module":"power","version":"1","moved":true,
+  "items":[{"collection":"contribution:node-bar:block","name":"battery","if-capability":"battery","attributes":{"bar":"bottom","place":"status","order":"40"},"template":"files/battery"},
+           {"collection":"contribution:node-bar:block","name":"draw","attributes":{"bar":"bottom","place":"status","order":"45"},"template":"files/draw"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`
+)
+
+func collectedBarsOn(t *testing.T, caps map[string]bool) Resolution {
+	t.Helper()
+	bars := held(t, collectedBars, builtWith("bars", map[string]string{"bars": collectedBarsText}))
+	power := held(t, itemsOfPower, builtWith("power", map[string]string{"battery": "B\n", "draw": "D ${machine:name}\n"}))
+	r, err := Resolve(shelf(bars, power), []string{"bars", "power"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account, r.Capabilities = "op", caps
+	return r
+}
+
+func TestACollectorMayNameTheBarsBlocksAsACollectionAndNoOtherDataKind(t *testing.T) {
+	bars := held(t, collectedBars, builtWith("bars", map[string]string{"bars": collectedBarsText}))
+	if _, err := collectedBarsOn(t, nil).Compose(handingTo("store:5000")); err != nil {
+		t.Fatalf("the handed collector is refused: %v", err)
+	}
+	if got := collectedPlaceholderProblems(bars, map[string]any{"id": "x",
+		"content": "${collected:contribution:node-bar:block:bar=top,place=status}"}); len(got) != 0 {
+		t.Fatalf("the check refuses it: %v", got)
+	}
+	// A data kind whose shape does not say its items are text stays refused.
+	_, plain, _ := receivable(BarSeat, BarKindBlock)
+	plain.Shape = &Shape{}
+	if collectableAsText(plain) {
+		t.Fatal("a shape not marked as text is collectable")
+	}
+	if _, _, err := oldCollection("contribution:node-bar:block", false); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestTheBarsCollectionIsFilledTheOldWayWhereTheCollectorIsNotHanded(t *testing.T) {
+	for _, caps := range []map[string]bool{nil, {"battery": true}} {
+		got := composedFile(t, collectedBarsOn(t, caps), "bars.conf")
+		want := "top\nbottom\n# power\nD workstation\n"
+		if caps["battery"] {
+			want = "top\nbottom\n# power\nB\n# power\nD workstation\n"
+		}
+		if got != want {
+			t.Errorf("caps %v: the file is %q, want %q", caps, got, want)
+		}
+	}
+}
+
+func TestTheBarsCollectionIsNamedInTheHandedPlan(t *testing.T) {
+	c, _ := composeWith(t, collectedBarsOn(t, map[string]bool{"battery": true}), handingTo("store:5000"))
+	if !reflect.DeepEqual(c.Plans["bars"].Collections, []PlanCollection{{Name: "contribution:node-bar:block", Comment: "#"}}) {
+		t.Fatalf("the plan collects %+v", c.Plans["bars"].Collections)
+	}
+	if n := len(c.Plans["power"].Items); n != 2 {
+		t.Fatalf("the contributor's plan names %d items", n)
+	}
+}
+
+// The bars of the catalogue's i3status-rust, with the blocks of power's items, compose to the files the old shaped
+// contribution made (issue 781). testdata/bars holds the catalogue's bars and block texts as of the move and the bars as
+// composed before it, for a machine with neither capability, the battery, the power meter and both. Where the
+// collector is not handed the controller fills the files; where it is, it names the items for the client, which
+// fills the same files (mesh-catalog's provisioner client holds that half against the same golden files).
+func TestTheBarsOfTheCatalogueAreTheSameHandedOrNot(t *testing.T) {
+	read := func(name string) string {
+		b, err := os.ReadFile(filepath.Join("testdata", "bars", name))
+		if err != nil {
+			t.Fatal(err)
+		}
+		return string(b)
+	}
+	collector := `{"module":"bars","version":"1","moved":true,"claims":[{"name":"node-bar","scope":"node"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"top","type":"file","path":"/t","template":"files/top"},
+               {"id":"bottom","type":"file","path":"/b","template":"files/bottom"}]}`
+	power := `{"module":"power","version":"1","moved":true,
+  "items":[{"collection":"contribution:node-bar:block","name":"battery","if-capability":"battery","attributes":{"bar":"bottom","place":"status","order":"40"},"template":"files/battery"},
+           {"collection":"contribution:node-bar:block","name":"power-draw","if-capability":"power-meter","attributes":{"bar":"bottom","place":"status","order":"45"},"template":"files/draw"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`
+	for name, caps := range map[string]map[string]bool{"none": nil, "battery": {"battery": true},
+		"power-meter": {"power-meter": true}, "both": {"battery": true, "power-meter": true}} {
+		bars := held(t, collector, builtWith("bars", map[string]string{"top": read("top-bar.toml"), "bottom": read("bottom-bar.toml")}))
+		blocks := held(t, power, builtWith("power", map[string]string{"battery": read("bar-battery"), "draw": read("bar-power-draw")}))
+		r, err := Resolve(shelf(bars, blocks), []string{"bars", "power"}, workstation(), World{})
+		if err != nil {
+			t.Fatal(err)
+		}
+		r.Account, r.Capabilities = "op", caps
+		// Not handed: the controller fills them.
+		for id, which := range map[string]string{"bars.top": "top", "bars.bottom": "bottom"} {
+			if got := composedFile(t, r, id); got != read(name+"."+which+"-bar.toml") {
+				t.Errorf("%s, %s bar, not handed:\n%s\nwant\n%s", name, which, got, read(name+"."+which+"-bar.toml"))
+			}
+		}
+		// Handed: the plan names the items the machine's capabilities allow, for the client to fill.
+		c, _ := composeWith(t, r, handingTo("store:5000"))
+		var names []string
+		for _, it := range c.Plans["power"].Items {
+			names = append(names, it.Name)
+		}
+		want := []string{}
+		if caps["battery"] {
+			want = append(want, "battery")
+		}
+		if caps["power-meter"] {
+			want = append(want, "power-draw")
+		}
+		if !reflect.DeepEqual(append([]string{}, names...), want) {
+			t.Errorf("%s: the plan names %v, want %v", name, names, want)
+		}
+	}
+}

go/catalogue/collections_l2_test.go

@@ -0,0 +1,60 @@
+package catalogue
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// The collectors design 57 L2 moved (issue 681), composed with nothing handed: zsh's rc, triggerhappy's triggers and
+// power's after-wake moment, from the catalogue's real templates and its moved contributors' real items, are byte
+// for byte what the controller composed from the old forms before the move (testdata/l2-moved: templates/ and items/
+// copied from mesh-catalog at the move, want/ composed at the feature branch before it).
+
+func l2Moved(t *testing.T, parts ...string) string {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join(append([]string{"testdata", "l2-moved"}, parts...)...))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(raw)
+}
+
+func TestTheCollectorsL2MovedComposeAsBeforeWhereNothingIsHanded(t *testing.T) {
+	// Each moved contributor, its items read back from its templates archive as the mesh holds them.
+	items := map[string][]string{
+		"asus-zephyrus-g14":       {"shell:after-wake:normal", "contribution:node-hotkeys:trigger"},
+		"claude-code":             {"shell:zsh:normal"},
+		"mesh-cli":                {"shell:zsh:normal"},
+		"powerlevel10k":           {"shell:zsh:normal"},
+		"zsh-autosuggestions":     {"shell:zsh:normal"},
+		"zsh-syntax-highlighting": {"shell:zsh:last"},
+	}
+	var modules []Manifest
+	for _, module := range sortedKeys(items) {
+		m := Manifest{Module: module, Moved: true}
+		for _, collection := range items[module] {
+			m.Items = append(m.Items, Item{Collection: collection,
+				Content: l2Moved(t, "items", module+"."+strings.ReplaceAll(collection, ":", "-"))})
+		}
+		modules = append(modules, m)
+	}
+	for _, c := range []struct{ module, seat string }{{"zsh", LoginShellSeat}, {"triggerhappy", HotkeysSeat},
+		{"power", PowerSeat}} {
+		holder := Manifest{Module: c.module, Moved: true, Claims: []Claim{{Name: c.seat}}}
+		resource := map[string]any{"id": "file", "type": "file", "path": "/etc/" + c.module,
+			"content": l2Moved(t, "templates", c.module)}
+		var unplaced []string
+		if err := contributionsInto(resource, holder, append([]Manifest{holder}, modules...),
+			map[string]string{"name": "g14"}, Rendering{}, map[string]bool{}, &unplaced); err != nil {
+			t.Fatalf("%s: %v", c.module, err)
+		}
+		if got, want := resource["content"], l2Moved(t, "want", c.module); got != want {
+			t.Errorf("%s's file is not what the old forms made:\n%s\nwant:\n%s", c.module, got, want)
+		}
+		if len(unplaced) != 0 {
+			t.Errorf("%s: unplaced %v", c.module, unplaced)
+		}
+	}
+}

go/catalogue/collections_l3_test.go

@@ -0,0 +1,158 @@
+package catalogue
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// An item may carry attributes and a capability, a module may give several items to one collection, and a
+// placeholder may select by attributes (design 57 L3, issue 777). The controller leaves out of a plan an item whose
+// capability the machine lacks, accepts a selecting placeholder where it accepts the collection, and renders a
+// selected moved item into an old placeholder exactly as the contribution it replaces.
+
+const (
+	barCollector = `{"module":"bars","version":"1","moved":true,
+  "collections":[{"name":"blocks","comment":"#"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"conf","type":"file","path":"/etc/bars.conf","template":"files/bars"}]}`
+	barsText      = "top\n${collected:blocks:bar=top,place=status}bottom\n${collected:blocks:bar=bottom,place=status}${collected:blocks}"
+	barContribute = `{"module":"power","version":"1","moved":true,
+  "items":[{"collection":"blocks","name":"battery","if-capability":"battery","attributes":{"bar":"bottom","place":"status","order":"20"},"template":"files/battery"},
+           {"collection":"blocks","name":"clock","attributes":{"bar":"top","place":"status"},"template":"files/clock"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`
+)
+
+func blocksOn(t *testing.T, caps map[string]bool) Composed {
+	t.Helper()
+	bars := held(t, barCollector, builtWith("bars", map[string]string{"bars": barsText}))
+	power := held(t, barContribute, builtWith("power", map[string]string{"battery": "B\n", "clock": "C\n"}))
+	r, err := Resolve(shelf(bars, power), []string{"bars", "power"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account, r.Capabilities = "op", caps
+	c, _ := composeWith(t, r, handingTo("store:5000"))
+	return c
+}
+
+func TestAnItemWhoseCapabilityTheMachineLacksIsLeftOutOfItsPlan(t *testing.T) {
+	with := blocksOn(t, map[string]bool{"battery": true}).Plans["power"]
+	want := []PlanItem{
+		{Collection: "blocks", Name: "battery", Template: "battery",
+			Attributes: map[string]string{"bar": "bottom", "place": "status", "order": "20"}},
+		{Collection: "blocks", Name: "clock", Template: "clock", Attributes: map[string]string{"bar": "top", "place": "status"}},
+	}
+	if !reflect.DeepEqual(with.Items, want) {
+		t.Fatalf("with the capability the plan carries %+v", with.Items)
+	}
+	without := blocksOn(t, map[string]bool{"seat": true}).Plans["power"]
+	if !reflect.DeepEqual(without.Items, want[1:]) {
+		t.Fatalf("without it the plan carries %+v", without.Items)
+	}
+}
+
+func TestACollectorSelectingByAttributesCollectsTheCollectionOnce(t *testing.T) {
+	bars := blocksOn(t, nil).Plans["bars"]
+	if !reflect.DeepEqual(bars.Collections, []PlanCollection{{Name: "blocks", Comment: "#"}}) {
+		t.Fatalf("the plan collects %+v", bars.Collections)
+	}
+}
+
+func TestASelectorIsRefusedWhenMalformedOrNamingACollectionNotCollected(t *testing.T) {
+	for placeholder, want := range map[string]string{
+		"${collected:blocks:bar}":                "", // no equals sign: a collection named blocks:bar
+		"${collected:blocks:bar=top,bar=bottom}": "names bar twice",
+		"${collected:blocks:bar=}":               "is not <attribute>=<value>",
+		"${collected:other:bar=top}":             `does not collect "other"`,
+	} {
+		raw := strings.Replace(barCollector, `"template":"files/bars"`, `"content":"`+placeholder+`"`, 1)
+		raw = strings.Replace(raw, `"build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},`, "", 1)
+		raw = strings.Replace(raw, `"moved":true,`, "", 1)
+		m, err := ParseManifest([]byte(raw))
+		if err == nil {
+			_, err = (Resolution{Node: "n", Modules: []Manifest{m}}).Declaration(Rendering{})
+		}
+		if want == "" {
+			continue
+		}
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("%s: %v, want %q", placeholder, err, want)
+		}
+	}
+}
+
+func TestItemNamesAttributesAndCapabilitiesAreJudged(t *testing.T) {
+	item := func(extra string) string {
+		return `{"module":"p","moved":true,"build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},` +
+			`"items":[` + extra + `]}`
+	}
+	for items, want := range map[string]string{
+		`{"collection":"c","name":"a","template":"files/a"},{"collection":"c","template":"files/b"}`:            "has no name",
+		`{"collection":"c","name":"a","template":"files/a"},{"collection":"c","name":"a","template":"files/b"}`: "twice",
+		`{"collection":"c","name":"Big","template":"files/a"}`:                                                  "is not a name",
+		`{"collection":"c","attributes":{"order":"100"},"template":"files/a"}`:                                  "0 to 99",
+		`{"collection":"c","attributes":{"bar":"a b"},"template":"files/a"}`:                                    "is not a value",
+		`{"collection":"c","if-capability":"batery","template":"files/a"}`:                                      "no machine reports",
+		`{"collection":"contribution:node-bar:block","attributes":{"bar":"left"},"template":"files/a"}`:         "bar=left",
+		`{"collection":"contribution:node-bar:block","attributes":{"colour":"red"},"template":"files/a"}`:       `"colour" is none of them`,
+		`{"collection":"c","name":"a","template":"files/a","colour":"red"}`:                                     "colour",
+	} {
+		_, err := ParseManifest([]byte(item(items)))
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("%s: %v, want %q", items, err, want)
+		}
+	}
+	ok := item(`{"collection":"contribution:node-bar:block","name":"a","attributes":{"bar":"top","place":"status","order":"5"},"if-capability":"battery","template":"files/a"}`)
+	if _, err := ParseManifest([]byte(ok)); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A moved contributor's items, selected by the old placeholder's pair, render in the old order (order, module, item
+// name) and with the same lines as the contributions they replace.
+func TestASelectedMovedItemRendersIntoTheOldBarPlaceholderAsTheContributionDid(t *testing.T) {
+	piece := func(order, command string) string {
+		return "[[block]]\nblock = \"custom\"\ncommand = \"" + command + "\"\ninterval = 5\n"
+	}
+	asOld := Manifest{Module: "power", Contributions: []SeatContribution{
+		block(`{"bar":"bottom","place":"status","order":20,"shows":"command","options":{"command":"two","interval":5}}`),
+		block(`{"bar":"bottom","place":"status","shows":"command","options":{"command":"one","interval":5}}`),
+		block(`{"bar":"top","place":"resources","shows":"command","options":{"command":"up","interval":5}}`),
+	}}
+	asItems := Manifest{Module: "power", Moved: true, Items: []Item{
+		{Collection: "contribution:node-bar:block", Name: "b", Content: piece("", "one"),
+			Attributes: map[string]string{"bar": "bottom", "place": "status"}},
+		{Collection: "contribution:node-bar:block", Name: "a", Content: piece("", "two"),
+			Attributes: map[string]string{"bar": "bottom", "place": "status", "order": "20"}},
+		{Collection: "contribution:node-bar:block", Name: "c", Content: piece("", "up"),
+			Attributes: map[string]string{"bar": "top", "place": "resources"}},
+		{Collection: "contribution:node-bar:block", Name: "d", Content: "x\n", IfCapability: "battery",
+			Attributes: map[string]string{"bar": "bottom", "place": "status"}},
+	}}
+	other := Manifest{Module: "another", Contributions: []SeatContribution{
+		block(`{"bar":"bottom","place":"status","order":20,"shows":"command","options":{"command":"mid","interval":5}}`)}}
+	for _, caps := range []map[string]bool{nil, {"battery": true}} {
+		was := composedFile(t, Resolution{Node: "n", Account: "op", Capabilities: caps,
+			Modules: []Manifest{barHolder(), asOld, other}}, "a-bar.bottom")
+		is := composedFile(t, Resolution{Node: "n", Account: "op", Capabilities: caps,
+			Modules: []Manifest{barHolder(), asItems, other}}, "a-bar.bottom")
+		// The old form puts the contributions of a module under one line naming it and the item form puts one under
+		// each item: the same pieces in the same order, otherwise the same bytes.
+		want := "own-first\nown-middle\n# another\n" + piece("", "mid") + "# power\n" + piece("", "two") +
+			"# power\n" + piece("", "one")
+		if caps["battery"] {
+			want += "# power\nx\n"
+		}
+		want += "own-last\n"
+		if is != want {
+			t.Errorf("caps %v: the items render\n%s\nnot\n%s", caps, is, want)
+		}
+		if !strings.Contains(was, piece("", "two")) {
+			t.Errorf("the contributions made\n%s", was)
+		}
+	}
+	if got := composedFile(t, Resolution{Node: "n", Account: "op", Modules: []Manifest{barHolder(), asItems}}, "a-bar.top"); !strings.Contains(got, "\"up\"") || strings.Contains(got, `"one"`) {
+		t.Errorf("the top bar renders\n%s", got)
+	}
+}

go/catalogue/collections_test.go

@@ -0,0 +1,179 @@
+package catalogue
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// A collection is declared and filled by the client (novox/hq ADR 0349 §13, design 57 L1, issue 684): a collector
+// names a collection it collects, a contributor an item from a template of its own, and a handed composition plans
+// both for the node's provisioner client and renders neither. The three old namespaces read as collections of their
+// own name. Each file is filled one way: a piece of the other form on the machine is said as not placed.
+
+const (
+	collectorZsh = `{"module":"zsh","version":"1","moved":true,
+  "claims":[{"name":"node-login-shell","scope":"node"}],
+  "collections":[{"name":"widgets","comment":"#"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"rc","type":"file","path":"${machine:account-home}/.zshrc","owner":"${machine:account}",
+    "mode":"0644","template":"files/zshrc"}]}`
+	zshrcText       = "# zsh\n${shell:zsh:normal}${collected:widgets}"
+	contributorText = "source ${machine:account-home}/.p10k.zsh\n"
+	contributorP10k = `{"module":"prompt","version":"1","moved":true,
+  "items":[{"collection":"shell:zsh:normal","template":"files/zsh"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`
+	oldFormAliases = `{"module":"aliases","version":"1",
+  "shell":[{"for":"zsh","slot":"normal","code":"alias ll='ls -l'\n"}]}`
+)
+
+func builtWith(module string, texts map[string]string) []Built {
+	return []Built{{Name: "files", Kind: ArtifactArchive,
+		Reference: ArtifactStoreScheme + module + "/files/blobs/sha256:" + strings.Repeat("e", 64),
+		Digest:    "sha256:" + strings.Repeat("e", 64), Texts: texts}}
+}
+
+func collectionsOn(t *testing.T) Resolution {
+	t.Helper()
+	zsh := held(t, collectorZsh, builtWith("zsh", map[string]string{"zshrc": zshrcText}))
+	prompt := held(t, contributorP10k, builtWith("prompt", map[string]string{"zsh": contributorText}))
+	aliases, err := ParseManifest([]byte(oldFormAliases))
+	if err != nil {
+		t.Fatal(err)
+	}
+	r, err := Resolve(shelf(zsh, prompt, aliases), []string{"zsh", "prompt", "aliases"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account = "op"
+	return r
+}
+
+func TestAContributorsBuildKeepsItsItemsTemplateAndText(t *testing.T) {
+	m := held(t, contributorP10k, builtWith("prompt", map[string]string{"zsh": contributorText}))
+	if m.Handed == nil || !reflect.DeepEqual(m.Handed.Items, map[string]string{"shell:zsh:normal": "zsh"}) {
+		t.Fatalf("the build kept %+v", m.Handed)
+	}
+	if !reflect.DeepEqual(m.Items, []Item{{Collection: "shell:zsh:normal", Content: contributorText}}) {
+		t.Fatalf("the held items are %+v: the template's text, read back", m.Items)
+	}
+}
+
+func TestAHandedCollectorAndContributorArePlannedAndNeitherIsRendered(t *testing.T) {
+	c, got := composeWith(t, collectionsOn(t), handingTo("store:5000"))
+	if strings.Contains(got, ".p10k.zsh") || strings.Contains(got, "alias ll") {
+		t.Fatalf("the controller rendered a contribution into a handed collector: %s", got)
+	}
+	zsh, prompt := c.Plans["zsh"], c.Plans["prompt"]
+	wantCollections := []PlanCollection{{Name: "shell:zsh:normal", Comment: "#"}, {Name: "widgets", Comment: "#"}}
+	if !reflect.DeepEqual(zsh.Collections, wantCollections) || len(zsh.Items) != 0 {
+		t.Fatalf("zsh's plan collects %+v and contributes %+v", zsh.Collections, zsh.Items)
+	}
+	if !reflect.DeepEqual(prompt.Items, []PlanItem{{Collection: "shell:zsh:normal", Template: "zsh"}}) ||
+		len(prompt.Files) != 0 || prompt.Placement["machine:account-home"] != "/home/op" {
+		t.Fatalf("prompt's plan is %+v: its item, by template, and the placement its template names", prompt)
+	}
+	// The old form on the same machine is not placed, and said so.
+	if len(c.Unplaced) != 1 || !strings.Contains(c.Unplaced[0], "aliases's shell:zsh:normal is not placed") {
+		t.Fatalf("unplaced: %v", c.Unplaced)
+	}
+}
+
+// A collector filled the old way holds the old forms and each moved contributor's item, rendered from the text the
+// mesh holds as its old form was (design 57 L2, issue 681), so the file loses no line where nothing is handed; a
+// collection of the new form stays empty.
+func TestACollectorFilledTheOldWayHoldsTheOldFormsAndEachHeldItem(t *testing.T) {
+	c, got := composeWith(t, collectionsOn(t), Rendering{ArtifactStore: "store:5000"})
+	if c.Plans != nil {
+		t.Fatalf("handed on a machine that cannot take it: %v", c.Plans)
+	}
+	if !strings.Contains(got, `"content":"# zsh\n# aliases\nalias ll='ls -l'\n# prompt\nsource /home/op/.p10k.zsh\n"`) {
+		t.Fatalf("the old way does not hold the old forms and the held item in module order: %s", got)
+	}
+	if len(c.Unplaced) != 0 {
+		t.Fatalf("unplaced: %v", c.Unplaced)
+	}
+}
+
+// An item the controller cannot render the old way (it names a value but a machine fact) is said as not placed.
+func TestAHeldItemNamingMoreThanAFactIsSaidNotPlacedTheOldWay(t *testing.T) {
+	zsh := held(t, collectorZsh, builtWith("zsh", map[string]string{"zshrc": zshrcText}))
+	if _, ok := heldItemText(Manifest{Module: "p", Items: []Item{{Collection: "shell:zsh:normal",
+		Content: "export THEME=${config:theme}\n"}}}, "shell:zsh:normal", map[string]string{}); ok {
+		t.Fatal("an item naming a config value was rendered by the controller")
+	}
+	if _, ok := heldItemText(Manifest{Module: "p", Items: []Item{{Collection: "shell:zsh:normal",
+		Content: "cd ${machine:account-home}\n"}}}, "shell:zsh:normal", map[string]string{}); ok {
+		t.Fatal("an item naming a fact this machine lacks was rendered")
+	}
+	if _, ok := heldItemText(Manifest{Module: "p", Items: []Item{{Collection: "widgets", Content: "x\n"}}},
+		"widgets", nil); ok {
+		t.Fatal("an item of a collection of the new form was rendered the old way")
+	}
+	left := itemsLeftOut([]Manifest{zsh, {Module: "p", Items: []Item{{Collection: "shell:zsh:normal",
+		Content: "export THEME=${config:theme}\n"}}}}, zsh, "shell:zsh:normal", map[string]string{})
+	if len(left) != 1 || !strings.Contains(left[0], "p's item of shell:zsh:normal is not placed") {
+		t.Fatalf("left out: %v", left)
+	}
+}
+
+// Each old namespace L2 moves renders a moved contributor's item exactly as its old form did, where the collector is
+// not handed: the same contributor written both ways composes the same bytes (design 57 L2, issue 681).
+func TestAMovedContributorsItemRendersAsItsOldFormDid(t *testing.T) {
+	code := "# two lines\nalias a=b"
+	asOld := Manifest{Module: "laptop", Shell: []ShellCode{{For: "zsh", Slot: "normal", Code: code}},
+		Contributions: []SeatContribution{{Seat: HotkeysSeat, Kind: "trigger", Content: "KEY_F21 1 touchpad\n"}}}
+	asItem := Manifest{Module: "laptop", Moved: true, Items: []Item{{Collection: "shell:zsh:normal", Content: code},
+		{Collection: "contribution:node-hotkeys:trigger", Content: "KEY_F21 1 touchpad\n"}}}
+	other := Manifest{Module: "zz-other", Shell: []ShellCode{{For: "zsh", Slot: "normal", Code: "x=1\n"}},
+		Contributions: []SeatContribution{{Seat: HotkeysSeat, Kind: "trigger", Content: "KEY_MUTE 1 mute\n"}}}
+	first := Manifest{Module: "aa-first", Shell: []ShellCode{{For: "zsh", Slot: "normal", Code: "y=2\n"}}}
+	for _, mods := range [][]Manifest{{other, first}, {}} {
+		was := append(append([]Manifest(nil), mods...), asOld)
+		is := append(append([]Manifest(nil), mods...), asItem)
+		if a, b := shellCodeOn(was, "zsh", "normal", nil), shellCodeOn(is, "zsh", "normal", nil); a != b || a == "" {
+			t.Errorf("shell: the old form made %q, the item %q", a, b)
+		}
+		a, _, errA := seatContributions(was, hotkeysHolder(), "node-hotkeys:trigger", Rendering{}, nil, nil)
+		b, left, errB := seatContributions(is, hotkeysHolder(), "node-hotkeys:trigger", Rendering{}, nil, nil)
+		if errA != nil || errB != nil || a != b || a == "" || len(left) != 0 {
+			t.Errorf("hotkeys: the old form made %q, the item %q (%v %v %v)", a, b, errA, errB, left)
+		}
+	}
+}
+
+func TestCollectionsAndItemsAreJudged(t *testing.T) {
+	for name, c := range map[string]struct{ raw, says string }{
+		"an item of a module not moved": {`{"module":"m","version":"1",
+  "items":[{"collection":"shell:zsh:normal","template":"files/x"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`, "is marked moved"},
+		"two items to one collection": {`{"module":"m","version":"1","moved":true,
+  "items":[{"collection":"a","template":"files/x"},{"collection":"a","template":"files/y"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`, "contributes to a twice"},
+		"an item to no slot": {`{"module":"m","version":"1","moved":true,
+  "items":[{"collection":"shell:zsh:middle","template":"files/x"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`, "is no slot"},
+		"an item outside the templates": {`{"module":"m","version":"1","moved":true,
+  "items":[{"collection":"a","template":"x"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`, "is not a file under files/"},
+		"an item naming a secret": {`{"module":"m","version":"1",
+  "items":[{"collection":"a","content":"t=${secret:token}"}]}`, "where no secret is"},
+		"a collection not declared": {`{"module":"m","version":"1",
+  "resources":[{"id":"f","type":"file","path":"/f","content":"${collected:a}"}]}`, "does not collect"},
+		"an old namespace declared": {`{"module":"m","version":"1","collections":[{"name":"shell:zsh:normal"}],
+  "resources":[{"id":"f","type":"file","path":"/f","content":"x"}]}`, "read from its placeholder"},
+		"a collection placed nowhere": {`{"module":"m","version":"1","collections":[{"name":"a"}],
+  "resources":[{"id":"f","type":"file","path":"/f","content":"x"}]}`, "no file of its places it"},
+		"a collection in a path": {`{"module":"m","version":"1","collections":[{"name":"a"}],
+  "resources":[{"id":"f","type":"file","path":"/${collected:a}","content":"${collected:a}"}]}`,
+			"only in a file's content"},
+	} {
+		_, err := ParseManifest([]byte(c.raw))
+		if err == nil || !strings.Contains(err.Error(), c.says) {
+			t.Errorf("%s: %v, want it to say %q", name, err, c.says)
+		}
+	}
+	if _, err := ParseManifest([]byte(collectorZsh)); err != nil {
+		t.Errorf("a collector: %v", err)
+	}
+}

go/catalogue/computed_test.go

@@ -0,0 +1,205 @@
+package catalogue
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// A module whose files cannot be written in advance.
+//
+// The mesh's private network is the case: a machine's peer list is derived from every other
+// machine, so it differs on each one and changes when any of them changes. What matters in these
+// tests is not that it works, but that being computed changes *nothing else* about being a
+// module — it is assigned, resolved, settled and absent when nobody asked for it.
+
+type fake struct {
+	on    map[string]bool
+	asked []string
+	err   error
+}
+
+func (f *fake) Resources(node string) ([]map[string]any, bool, error) {
+	f.asked = append(f.asked, node)
+	if f.err != nil {
+		return nil, false, f.err
+	}
+	if !f.on[node] {
+		return nil, false, nil
+	}
+	return []map[string]any{{"id": "peers", "type": "file", "path": "/etc/x.conf",
+		"merge": MergeJSON, "content": `{"peer":"` + node + `"}`}}, true, nil
+}
+
+func computedShelf() map[string]Manifest {
+	return shelf(Manifest{Module: "mesh-network", Computed: "mesh-network",
+		Provides: Offers("private-network")})
+}
+
+func TestAComputedModuleIsAskedAboutTheNodeItIsFor(t *testing.T) {
+	// The generator gets a node name, not a plan. Everything it needs is the whole mesh, which
+	// it was built with — this is the one thing a node could never work out for itself.
+	got, err := Resolve(computedShelf(), []string{"mesh-network"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	gen := &fake{on: map[string]bool{"workstation": true}}
+	out, err := got.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": gen}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(gen.asked) != 1 || gen.asked[0] != "workstation" {
+		t.Fatalf("asked about %v, wanted workstation once", gen.asked)
+	}
+	if len(out) != 1 || !strings.Contains(out[0]["content"].(string), `"peer": "workstation"`) {
+		t.Fatalf("got %v", out)
+	}
+}
+
+func TestAMachineNobodyGaveItGetsNothing(t *testing.T) {
+	// The whole point of making the network a module. Before this, every machine with an address
+	// was on the private network and there was no way to say one should stay off.
+	got, err := Resolve(computedShelf(), nil, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	gen := &fake{on: map[string]bool{"workstation": true}}
+	out, err := got.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": gen}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(out) != 0 {
+		t.Fatalf("a machine that was assigned nothing got %d resource(s)", len(out))
+	}
+	if len(gen.asked) != 0 {
+		t.Fatalf("the generator was asked about %v, and nobody had asked for it", gen.asked)
+	}
+}
+
+func TestAssignedAndNotYetPartOfItIsNotAFailure(t *testing.T) {
+	// A machine given the network module before it has a place on it. Brief and ordinary — the
+	// answer is "nothing yet", and treating it as an error would make an ordering a fault.
+	got, _ := Resolve(computedShelf(), []string{"mesh-network"}, workstation(), World{})
+	gen := &fake{on: map[string]bool{}}
+	out, err := got.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": gen}})
+	if err != nil {
+		t.Fatalf("refused a node that is not on the network yet: %v", err)
+	}
+	if len(out) != 0 {
+		t.Fatalf("got %v", out)
+	}
+}
+
+func TestAGeneratorThisControlPlaneDoesNotHaveIsRefused(t *testing.T) {
+	// Sending a machine a module with no files would look like it worked. Named in the message,
+	// because the only fix is a control plane that has it.
+	got, _ := Resolve(shelf(Manifest{Module: "weather", Computed: "the-weather"}), []string{"weather"}, workstation(), World{})
+
+	_, err := got.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": &fake{}}})
+	if err == nil {
+		t.Fatal("a module computed by nothing was accepted")
+	}
+	if !strings.Contains(err.Error(), "the-weather") {
+		t.Fatalf("the refusal does not name what is missing: %v", err)
+	}
+}
+
+func TestAModuleIsEitherWrittenOrComputedNotBoth(t *testing.T) {
+	// Otherwise nobody could say where a given file on a machine came from.
+	_, err := ParseManifest([]byte(`{"module":"mesh-network","version":"1",
+		"computed":"mesh-network",
+		"resources":[{"id":"a","type":"package","package":"wireguard-tools"}]}`))
+	if err == nil {
+		t.Fatal("a module that both ships files and has them computed was accepted")
+	}
+	if !strings.Contains(err.Error(), "one or the other") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+func TestSettingsApplyToAComputedModuleToo(t *testing.T) {
+	// Being computed is about where the files come from, not about whether they are configurable.
+	// A line drawn there would be arbitrary and nobody could predict it.
+	got, _ := Resolve(computedShelf(), []string{"mesh-network"}, workstation(), World{})
+	gen := &fake{on: map[string]bool{"workstation": true}}
+	out, err := got.Declaration(Rendering{
+		Generators: map[string]Generator{"mesh-network": gen},
+		Settings: SettingsBy{"mesh-network": {{From: "the mesh",
+			Values: map[string]any{"keepalive": 25}}}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	content := out[0]["content"].(string)
+	if !strings.Contains(content, `"keepalive": 25`) {
+		t.Fatalf("the setting did not reach a computed file: %s", content)
+	}
+	if !strings.Contains(content, `"peer": "workstation"`) {
+		t.Fatalf("the setting replaced what the generator computed: %s", content)
+	}
+}
+
+func TestTwoWaysToBeOnAPrivateNetworkRefuseAndNameBoth(t *testing.T) {
+	// WireGuard is one way. The refusing rule is what makes a second one safe to add: assigning
+	// both is caught rather than producing a machine on two networks that each half-work.
+	_, err := Resolve(shelf(
+		Manifest{Module: "mesh-network", Computed: "mesh-network",
+			Provides: Offers("private-network")},
+		Manifest{Module: "tailscale", Provides: Offers("private-network")},
+		Manifest{Module: "backups", Requires: []string{"private-network"}},
+	), []string{"backups"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("two answers to one requirement were taken silently")
+	}
+	for _, want := range []string{"mesh-network", "tailscale", "private-network"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("the refusal does not name %s: %v", want, err)
+		}
+	}
+}
+
+// reloading answers the runtime's trust as the networking module once did (novox/hq ADR 0102; it no
+// longer does, ADR 0222 — and beside the runtime's module it is refused, generated_collision_test): a file
+// written into, and the runtime reloaded on it.
+type reloading struct{}
+
+func (reloading) Resources(node string) ([]map[string]any, bool, error) {
+	return []map[string]any{
+		{"id": "registry-trust", "type": "file", "path": "/etc/docker/daemon.json",
+			"merge": MergeJSON, "into": "json", "content": `{"insecure-registries":["r:5000"]}`},
+		{"id": "registry-trust-reload", "type": "service", "unit": "docker.service",
+			"state": "running", "reload-on": []string{"registry-trust"}},
+	}, true, nil
+}
+
+func TestWhatAServiceIsReloadedOnIsNamedAsTheHostWillSeeIt(t *testing.T) {
+	// Ids are prefixed with their module on the way out. An unprefixed reload-on would name a
+	// resource the host never sees, and the runtime would never be reloaded for its trust.
+	got, err := Resolve(computedShelf(), []string{"mesh-network"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := got.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": reloading{}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var file, service map[string]any
+	for _, r := range out {
+		switch r["type"] {
+		case "file":
+			file = r
+		case "service":
+			service = r
+		}
+	}
+	if file == nil || service == nil {
+		t.Fatalf("got %v", out)
+	}
+	if file["into"] != "json" {
+		t.Errorf("into did not reach the host: %v", file)
+	}
+	if want := "[" + file["id"].(string) + "]"; fmt.Sprint(service["reload-on"]) != want {
+		t.Errorf("reload-on names %v, the file is %v", service["reload-on"], file["id"])
+	}
+}

go/catalogue/config.go

@@ -0,0 +1,504 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"slices"
+	"strings"
+)
+
+// A module declares its config (novox/hq ADR 0348 §1, §4, §5, §6, §8, §11; design 57 package K1, issue 660).
+//
+// **One concept, two spellings for a while.** "Config" replaces "settings": the manifest says `config` for
+// `settings`, `takes-config` for `takes-settings` and `${config:<key>}` for `${setting:<key>}`. The old names stay
+// accepted as aliases until every module has moved (ADR 0348 §1), and a module uses one form or the other, never
+// both. The config form is read into the very fields the settings form fills — Settings, a mergeable file's
+// takes-settings and `${setting:<key>}` — so composition has one path and `${config:<key>}` fills exactly as
+// `${setting:<key>}` does: a module rewritten from settings to config composes byte-identically. It is written
+// back in the form it was read in, so what the mesh holds is what its author wrote.
+//
+// **A moved module is held to the whole declaration.** Under `config` every value has a type (number, string or
+// boolean; an object or a list only when trusted), a description including its unit, its validation (enum,
+// minimum and maximum, pattern), whether it is trusted, optionally the predefined key it falls back to, and either
+// a default or `required`; it lands in a file or is read at runtime (`runtime: true`); every mergeable file names
+// the keys it takes; a `reload-on` or `restart-on` names a file the module declares. A module not yet moved keeps
+// today's form and today's rules (SettingProblems, TakenSettingsProblems) until the catalogue's list of such
+// modules is empty (ADR 0348 §11).
+//
+// **A required value nothing sets** is the operator's own: it composes as an operator's setting nobody gave does
+// today, refused by name at composition (UnsetSettingError). Who reports it once mesh-config answers values is the
+// provisioner's (ADR 0349), not this file's.
+
+// ConfigField is the manifest key a module declares its config values under.
+const ConfigField = "config"
+
+// TakesConfigField is the key a mergeable file names the config values it takes by.
+const TakesConfigField = "takes-config"
+
+// SettingsField is the old name of ConfigField, read as its alias.
+const SettingsField = "settings"
+
+// configRef is how a file asks for a config value: ${config:<key>}, the same keys as settingRef.
+var configRef = regexp.MustCompile(`\$\{config:([a-z0-9][a-z0-9_.-]*)\}`)
+
+// takesConfigKey and takesSettingsKey are the two spellings as a key of a JSON object. A string value is never
+// followed by a colon, and a quote inside a string is escaped, so these match only keys.
+var (
+	takesConfigKey   = regexp.MustCompile(`"` + TakesConfigField + `"(\s*):`)
+	takesSettingsKey = regexp.MustCompile(`"` + TakesSettingsField + `"(\s*):`)
+)
+
+// The types a config value may have (ADR 0348 §4).
+const (
+	ConfigNumber  = "number"
+	ConfigString  = "string"
+	ConfigBoolean = "boolean"
+	ConfigObject  = "object"
+	ConfigList    = "list"
+)
+
+// accountFacts are what the mesh places for a module's account, never config values (ADR 0348 §11).
+var accountFacts = map[string]bool{"puid": true, "pgid": true}
+
+// configForms is which of the two forms a manifest was written in, by the words of each it uses.
+type configForms struct {
+	config, settings []string
+}
+
+// DeclaresConfig is whether the manifest is written in the config form: `config`, `takes-config` or
+// `${config:<key>}` (ADR 0348 §1, §11).
+func (m Manifest) DeclaresConfig() bool { return len(m.forms.config) > 0 }
+
+// toSettingsForm is raw with the config form's placeholders and takes-config read as the settings form's, and
+// which words of each form it used. `config` itself is a top-level key, renamed where the keys are read
+// (UnmarshalJSON).
+func toSettingsForm(raw []byte) ([]byte, configForms) {
+	var f configForms
+	if configRef.Match(raw) {
+		f.config = append(f.config, "${config:…}")
+	}
+	if takesConfigKey.Match(raw) {
+		f.config = append(f.config, TakesConfigField)
+	}
+	if settingRef.Match(raw) {
+		f.settings = append(f.settings, "${setting:…}")
+	}
+	if takesSettingsKey.Match(raw) {
+		f.settings = append(f.settings, TakesSettingsField)
+	}
+	if len(f.config) == 0 {
+		return raw, f
+	}
+	raw = configRef.ReplaceAllFunc(raw, func(ref []byte) []byte {
+		return []byte("${setting:" + string(configRef.FindSubmatch(ref)[1]) + "}")
+	})
+	raw = takesConfigKey.ReplaceAllFunc(raw, func(key []byte) []byte {
+		return []byte(`"` + TakesSettingsField + `"` + string(takesConfigKey.FindSubmatch(key)[1]) + ":")
+	})
+	return raw, f
+}
+
+// toConfigForm is a manifest written in the settings form's words, as JSON, in the config form's: what
+// toSettingsForm and UnmarshalJSON read, written back.
+func toConfigForm(raw []byte) ([]byte, error) {
+	var keys map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keys); err != nil {
+		return nil, err
+	}
+	if settings, has := keys[SettingsField]; has {
+		keys[ConfigField] = settings
+		delete(keys, SettingsField)
+		var err error
+		if raw, err = json.Marshal(keys); err != nil {
+			return nil, err
+		}
+	}
+	raw = settingRef.ReplaceAllFunc(raw, func(ref []byte) []byte {
+		return []byte("${config:" + string(settingRef.FindSubmatch(ref)[1]) + "}")
+	})
+	raw = takesSettingsKey.ReplaceAllFunc(raw, func(key []byte) []byte {
+		return []byte(`"` + TakesConfigField + `"` + string(takesSettingsKey.FindSubmatch(key)[1]) + ":")
+	})
+	return raw, nil
+}
+
+// inConfigWords is a refusal said of a module in the config form in its words: `${config:<key>}` and
+// takes-config, where the rules shared with the settings form say `${setting:<key>}` and takes-settings.
+func inConfigWords(problem string) string {
+	problem = settingRef.ReplaceAllStringFunc(problem, func(ref string) string {
+		return "${config:" + settingRef.FindStringSubmatch(ref)[1] + "}"
+	})
+	return strings.ReplaceAll(problem, TakesSettingsField, TakesConfigField)
+}
+
+// MixedFormProblems is a manifest using both forms, said with the words of each (ADR 0348 §1).
+func MixedFormProblems(m Manifest) []string {
+	if len(m.forms.config) == 0 || len(m.forms.settings) == 0 {
+		return nil
+	}
+	return []string{fmt.Sprintf("%s mixes the config form (%s) with the settings form (%s): a module uses one form "+
+		"or the other, never both; write %s, %s and ${config:<key>} throughout (novox/hq ADR 0348 §1)",
+		m.Module, strings.Join(m.forms.config, ", "), strings.Join(m.forms.settings, ", "),
+		ConfigField, TakesConfigField)}
+}
+
+// configDeclaration is the config form's declaration as written: nothing of the settings form's, and nothing
+// unsaid.
+type configDeclaration struct {
+	Type        string   `json:"type,omitempty"`
+	Description string   `json:"description,omitempty"`
+	Enum        []any    `json:"enum,omitempty"`
+	Minimum     *float64 `json:"minimum,omitempty"`
+	Maximum     *float64 `json:"maximum,omitempty"`
+	Pattern     string   `json:"pattern,omitempty"`
+	Trusted     bool     `json:"trusted,omitempty"`
+	Predefined  string   `json:"predefined,omitempty"`
+	Default     any      `json:"default,omitempty"`
+	Required    bool     `json:"required,omitempty"`
+	Runtime     bool     `json:"runtime,omitempty"`
+}
+
+// MarshalJSON writes a settings declaration exactly as before, and a config declaration without the settings
+// form's kind and why, and without a default it does not have.
+func (d SettingDeclaration) MarshalJSON() ([]byte, error) {
+	type plain SettingDeclaration
+	if d.Kind != "" || d.Why != "" {
+		return json.Marshal(plain(d))
+	}
+	return json.Marshal(configDeclaration{Type: d.Type, Description: d.Description, Enum: d.Enum,
+		Minimum: d.Minimum, Maximum: d.Maximum, Pattern: d.Pattern, Trusted: d.Trusted, Predefined: d.Predefined,
+		Default: d.Default, Required: d.Required, Runtime: d.Runtime})
+}
+
+// configShaped is whether a declaration says anything of the config form's.
+func configShaped(d SettingDeclaration) bool {
+	return d.Type != "" || d.Description != "" || len(d.Enum) > 0 || d.Minimum != nil || d.Maximum != nil ||
+		d.Pattern != "" || d.Trusted || d.Predefined != "" || d.Required || d.Runtime
+}
+
+// TypedSettingProblems is a declaration under `settings` that says what only `config` says: a value with a type,
+// a description and its validation is declared in the config form (ADR 0348 §1, §4).
+func TypedSettingProblems(m Manifest) []string {
+	var problems []string
+	for _, key := range sortedSettingKeys(m.Settings) {
+		if configShaped(m.Settings[key]) {
+			problems = append(problems, fmt.Sprintf("%s's setting %q says its type, description or validation "+
+				"under %s: a value declared with those is declared under config, with ${config:<key>} and "+
+				"takes-config, never under %s (novox/hq ADR 0348 §1, §4)", m.Module, key, SettingsField, SettingsField))
+		}
+	}
+	return problems
+}
+
+// ConfigProblems is every way a module in the config form declares its config wrongly, each said by name with
+// what to do (ADR 0348 How it is checked, design 57 package K1).
+func ConfigProblems(m Manifest) []string {
+	if !m.DeclaresConfig() {
+		return nil
+	}
+	var problems []string
+	placed := configPlaced(m)
+	fallsBack := fileFallsBack(m)
+	renamed := renamedTaken(m)
+	for _, key := range sortedSettingKeys(m.Settings) {
+		d := m.Settings[key]
+		say := func(format string, args ...any) {
+			problems = append(problems, fmt.Sprintf("%s's config value %q: ", m.Module, key)+fmt.Sprintf(format, args...))
+		}
+		if !settingRef.MatchString("${setting:" + key + "}") {
+			say("not a usable key: lower-case letters, digits, dots, dashes and underscores")
+			continue
+		}
+		if meshWords[key] || accountFacts[key] {
+			say("%q is placement, which the mesh decides, never a config value (novox/hq ADR 0348 §11)", key)
+			continue
+		}
+		if d.Kind != "" || d.Why != "" {
+			say("kind and why are the settings form's; under config a value says its type and its description " +
+				"(novox/hq ADR 0348 §1, §4)")
+		}
+		switch d.Type {
+		case ConfigNumber, ConfigString, ConfigBoolean:
+		case ConfigObject, ConfigList:
+			if !d.Trusted {
+				say("is %s and not trusted: an object or a list decides more than one value can say, so it is "+
+					"trusted, \"trusted\": true, or split into numbers, strings and booleans (novox/hq ADR 0348 §4)", d.Type)
+			}
+		case "":
+			say("no type: say \"type\": number, string or boolean, or object or list when trusted (novox/hq ADR 0348 §4)")
+		default:
+			say("type %q is none of number, string, boolean, object and list (novox/hq ADR 0348 §4)", d.Type)
+		}
+		if strings.TrimSpace(d.Description) == "" {
+			say("no description: say in a sentence what the value is, including its unit (novox/hq ADR 0348 §4)")
+		}
+		switch {
+		case d.Required && d.Default != nil:
+			say("both a default and required: a required value is the operator's own and has no default; give " +
+				"one or the other (novox/hq ADR 0348 §4)")
+		case !d.Required && d.Default == nil:
+			say("neither a default nor required: give a default, or say \"required\": true for a value that is " +
+				"the operator's own (novox/hq ADR 0348 §4)")
+		}
+		if as := renamed[key]; as != "" && d.Required {
+			say("is laid into its file as %q, and only when it is set, so the file and its code fall back when "+
+				"it is not: it is never required; give it the file's default, the empty value of its type "+
+				"(novox/hq issue 751)", as)
+		}
+		for _, wrong := range validationProblems(d) {
+			say("%s", wrong)
+		}
+		if word := operatorsWord(key); word != "" && d.Default != nil && !fallsBack[key] {
+			say("a key naming %q is the operator's value: declare it \"required\": true, with no default, "+
+				"unless a mergeable file takes it and no placeholder asks for it, where the file falls back "+
+				"(novox/hq ADR 0348 §4, ADR 0112, issue 735)", word)
+		}
+		if d.Predefined != "" {
+			p, listed := m.predefined[d.Predefined]
+			switch {
+			case m.predefined == nil:
+				say("falls back to the predefined key %q, and the list of predefined keys (%s at the root of "+
+					"the catalogue's repository) is not present where it is judged: a value falls back only to a "+
+					"key on that list; judge it in the catalogue, or leave \"predefined\" out (novox/hq ADR 0348 §7)",
+					d.Predefined, PredefinedFile)
+			case !listed:
+				say("falls back to %q, which is not on the list of predefined keys: name a key on it, or leave "+
+					"\"predefined\" out (novox/hq ADR 0348 §7)", d.Predefined)
+			default:
+				if p.Type != d.Type {
+					say("falls back to the predefined key %q, which is a %s, and this value is a %s: a value falls "+
+						"back only to a key of its own type (novox/hq ADR 0348 §4)", d.Predefined, p.Type, d.Type)
+				}
+				if p.Trusted && !d.Trusted {
+					say("falls back to the trusted predefined key %q and is not trusted itself: a value that falls "+
+						"back to a trusted key is trusted, \"trusted\": true (novox/hq ADR 0348 §8)", d.Predefined)
+				}
+			}
+		}
+		// A template's text is not here yet. Resolve fills it from the build, WithTemplatesFrom from the tree; neither
+		// judges again itself, but WithTemplatesFrom parses its result again, and a resolved build is parsed again
+		// where it is registered, and this is judged then.
+		if !placed[key] && !d.Runtime && !m.Templated() {
+			say("placed nowhere: no file says ${config:%s} or takes it under %s, and it is not marked "+
+				"\"runtime\": true for a value the module's code reads itself (novox/hq ADR 0348 §5)", key, TakesConfigField)
+		}
+	}
+	used := settingKeysUsedBy(m)
+	for _, key := range sortedKeys(used) {
+		if _, declared := m.Settings[key]; !declared {
+			problems = append(problems, fmt.Sprintf("%s says ${config:%s} and declares no such value under %s: "+
+				"declare %q with its type, description and a default or required (novox/hq ADR 0348 §4, §5)",
+				m.Module, key, ConfigField, key))
+		}
+	}
+	problems = append(problems, configTakesProblems(m)...)
+	problems = append(problems, reflectsProblems(m)...)
+	return problems
+}
+
+// configPlaced is every value a file, a unit, a directory's owner, a contribution or a served fact asks for, and
+// every value a mergeable file takes.
+func configPlaced(m Manifest) map[string]bool {
+	placed := settingKeysUsedBy(m)
+	for _, r := range m.Resources {
+		for _, k := range takenKeyList(r) {
+			placed[k] = true
+		}
+	}
+	return placed
+}
+
+// fileFallsBack is every value a mergeable file takes and no placeholder asks for. Unset, such a value is simply
+// not laid over the file: the file's own content, or the module's code reading the file, falls back. So one named
+// after the operator's value (a url, a user, an address) is not `required`, and its default is the file's: its
+// value in the content, else the empty value of its type, never laid over the file (the operator's decision on
+// issue 664, issue 735). A placeholder has no such fallback: its default would be filled in where the operator's
+// value belongs (ADR 0112).
+func fileFallsBack(m Manifest) map[string]bool {
+	asked := settingKeysUsedBy(m)
+	out := map[string]bool{}
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how == "" {
+			continue
+		}
+		for _, k := range takenKeyList(r) {
+			if !asked[k] {
+				out[k] = true
+			}
+		}
+	}
+	return out
+}
+
+// renamedTaken is every value a mergeable file takes under a name of its own, with that name (issue 751).
+func renamedTaken(m Manifest) map[string]string {
+	out := map[string]string{}
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how == "" {
+			continue
+		}
+		for _, e := range takenEntries(r[TakesSettingsField]) {
+			if e.renamed {
+				out[e.key] = e.as
+			}
+		}
+	}
+	return out
+}
+
+// validationProblems is what is wrong with a declaration's validation, and its default against it.
+func validationProblems(d SettingDeclaration) []string {
+	var problems []string
+	isNumber := d.Type == ConfigNumber
+	if len(d.Enum) > 0 && d.Type != ConfigNumber && d.Type != ConfigString {
+		problems = append(problems, fmt.Sprintf("an enum is for a number or a string, and this is a %s", d.Type))
+	}
+	if (d.Minimum != nil || d.Maximum != nil) && !isNumber {
+		problems = append(problems, fmt.Sprintf("a minimum or maximum is for a number, and this is a %s", d.Type))
+	}
+	if d.Minimum != nil && d.Maximum != nil && *d.Minimum > *d.Maximum {
+		problems = append(problems, fmt.Sprintf("its minimum %v is above its maximum %v", *d.Minimum, *d.Maximum))
+	}
+	var pattern *regexp.Regexp
+	if d.Pattern != "" {
+		if d.Type != ConfigString {
+			problems = append(problems, fmt.Sprintf("a pattern is for a string, and this is a %s", d.Type))
+		}
+		var err error
+		if pattern, err = regexp.Compile(`^(?:` + d.Pattern + `)$`); err != nil {
+			problems = append(problems, fmt.Sprintf("its pattern %q is not a regular expression: %v", d.Pattern, err))
+		}
+	}
+	for _, v := range d.Enum {
+		if !ofType(v, d.Type) {
+			problems = append(problems, fmt.Sprintf("its enum holds %v, which is not a %s", v, d.Type))
+		}
+	}
+	if d.Default == nil {
+		return problems
+	}
+	if !ofType(d.Default, d.Type) {
+		if d.Type != "" {
+			problems = append(problems, fmt.Sprintf("its default %v is not a %s", d.Default, d.Type))
+		}
+		return problems
+	}
+	if len(d.Enum) > 0 && !slices.ContainsFunc(d.Enum, func(v any) bool { return v == d.Default }) {
+		problems = append(problems, fmt.Sprintf("its default %v is not one of %v", d.Default, d.Enum))
+	}
+	if n, ok := d.Default.(float64); ok {
+		if d.Minimum != nil && n < *d.Minimum {
+			problems = append(problems, fmt.Sprintf("its default %v is below its minimum %v", n, *d.Minimum))
+		}
+		if d.Maximum != nil && n > *d.Maximum {
+			problems = append(problems, fmt.Sprintf("its default %v is above its maximum %v", n, *d.Maximum))
+		}
+	}
+	if s, ok := d.Default.(string); ok && pattern != nil && !pattern.MatchString(s) {
+		problems = append(problems, fmt.Sprintf("its default %q does not match its pattern %q", s, d.Pattern))
+	}
+	return problems
+}
+
+// ofType is whether a value read from JSON is of a config type.
+func ofType(v any, kind string) bool {
+	switch v.(type) {
+	case float64:
+		return kind == ConfigNumber
+	case string:
+		return kind == ConfigString
+	case bool:
+		return kind == ConfigBoolean
+	case map[string]any:
+		return kind == ConfigObject
+	case []any:
+		return kind == ConfigList
+	}
+	return false
+}
+
+// configTakesProblems is what ADR 0348 §11 adds for a module in the config form: an account fact in
+// takes-config (the mesh's own words are refused for both forms by TakenSettingsProblems), and a mergeable file
+// naming no keys where none of the module's does (where one does, TakenSettingsProblems names every one that
+// does not).
+func configTakesProblems(m Manifest) []string {
+	var problems, silent []string
+	naming := false
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how == "" {
+			continue
+		}
+		if _, said := r[TakesSettingsField]; !said {
+			silent = append(silent, fmt.Sprint(r["id"]))
+			continue
+		}
+		naming = true
+		for _, k := range takenKeyList(r) {
+			_, declared := m.Settings[k]
+			switch {
+			case accountFacts[k]:
+				problems = append(problems, fmt.Sprintf("%s's %v names %q in %s, and %q is an account fact the "+
+					"mesh places, never a config value (novox/hq ADR 0348 §11)", m.Module, r["id"], k,
+					TakesConfigField, k))
+			case meshWords[k]:
+				// Refused for both forms by TakenSettingsProblems, in its words.
+			case !declared:
+				problems = append(problems, fmt.Sprintf("%s's %v names %q in %s and declares no such value under "+
+					"%s: a value a file takes is declared like every other, with its type, description and a "+
+					"default or required, or the config verb could never set it (novox/hq ADR 0348 §4, §11)",
+					m.Module, r["id"], k, TakesConfigField, ConfigField))
+			}
+		}
+	}
+	if !naming {
+		for _, id := range silent {
+			problems = append(problems, fmt.Sprintf("%s's mergeable %s names no %s: a module that declares config "+
+				"names the keys each mergeable file takes, an empty list for none (novox/hq ADR 0348 §11)",
+				m.Module, id, TakesConfigField))
+		}
+	}
+	return problems
+}
+
+// meshMadeIDs are the resources the mesh composes into a module's own set, which its `restart-on` may name
+// without declaring them; meshMadePrefixes are those named after what they are for.
+var (
+	meshMadeIDs      = []string{ComposedJailsID(), FilteringID(), CertificateID(), AuthorityID(), BusUsersID()}
+	meshMadePrefixes = []string{NeedID(""), SecretID(""), strings.TrimSuffix(GrantID("", ""), "-"), BoundID(""), ReceivedID(""), AccessID("/")}
+)
+
+// reflectsProblems is a `reload-on` or `restart-on` naming a file the module does not declare (ADR 0348 §6): not
+// one of its own resources, not one the mesh composes for it, and not another module's, which is named
+// `<module>.<id>`.
+func reflectsProblems(m Manifest) []string {
+	own := map[string]bool{}
+	for _, r := range m.Resources {
+		own[fmt.Sprint(r["id"])] = true
+	}
+	meshMade := func(id string) bool {
+		if slices.Contains(meshMadeIDs, id) {
+			return true
+		}
+		for _, p := range meshMadePrefixes {
+			if strings.HasPrefix(id, p) && len(id) > len(p) {
+				return true
+			}
+		}
+		return false
+	}
+	var problems []string
+	for _, r := range m.Resources {
+		for _, field := range []string{"reload-on", "restart-on"} {
+			for _, id := range stringsOf(r[field]) {
+				if strings.Contains(id, ".") || own[id] || meshMade(id) {
+					continue
+				}
+				problems = append(problems, fmt.Sprintf("%s's %v names %q in its %s, and %s declares no such "+
+					"file: name a file of its own, or another module's as <module>.<id> (novox/hq ADR 0348 §6)",
+					m.Module, r["id"], id, field, m.Module))
+			}
+		}
+	}
+	return problems
+}

go/catalogue/config_move.go

@@ -0,0 +1,40 @@
+package catalogue
+
+import "strings"
+
+// What the move of config reads of a module's declaration (novox/hq ADR 0348 §9, design 57 K5, issue 664): where a
+// layer's key goes, how two layers' values become one, and whether a value is one its declaration takes.
+
+// TakenAs is each name a mergeable file takes a config value under that is not the value's config key, with that
+// key (issue 751): a layer set before the module moved may still say the file's name, and the move sets it under
+// the config key.
+func TakenAs(m Manifest) map[string]string {
+	out := map[string]string{}
+	for key, as := range renamedTaken(m) {
+		out[as] = key
+	}
+	return out
+}
+
+// AskedKeys is every value a placeholder of the module asks for: a file, a unit, a directory's owner, a
+// contribution or a served fact. Such a value is taken whole from the last layer that sets it, where a mergeable
+// file lays one object over another key by key.
+func AskedKeys(m Manifest) map[string]bool { return settingKeysUsedBy(m) }
+
+// LaidOver is a value laid over another as a later layer is laid over an earlier: two objects key by key, anything
+// else replaced whole.
+func LaidOver(under, over any) any { return mergeValue(under, over) }
+
+// ValueProblems is what is wrong with a value for a declaration: its type, and its enum, bounds or pattern.
+func ValueProblems(d SettingDeclaration, v any) []string {
+	if v == nil {
+		return []string{"no value"}
+	}
+	d.Default = v
+	d.Required = false
+	var problems []string
+	for _, p := range validationProblems(d) {
+		problems = append(problems, strings.ReplaceAll(p, "its default", "the value"))
+	}
+	return problems
+}

go/catalogue/config_rename_test.go

@@ -0,0 +1,185 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A takes-config entry may lay a value under the name the file's software reads (issue 751): the key stays a
+// config key, lower-case, and the file names its own variable, such as ATLASSIAN_URL.
+
+// renaming is inConfigForm with its rules file taking `url` as NOTIFIER_URL, a value the code reading the file
+// falls back on when the file lacks it.
+func renaming() map[string]any {
+	m := inConfigForm()
+	m["config"].(map[string]any)["url"] = map[string]any{"type": "string",
+		"description": "the address the notifier posts to, a URL; unset, the notifier's own environment says it",
+		"default":     ""}
+	resourceOf(m, "rules")["takes-config"] = []any{"position", "theme",
+		map[string]any{"key": "url", "as": "NOTIFIER_URL"}}
+	return m
+}
+
+// rulesComposed is the rules file's content as the module's defaults and these layers make it.
+func rulesComposed(t *testing.T, m Manifest, layers ...Layer) string {
+	t.Helper()
+	all := layers
+	if d, ok := Defaults(m); ok {
+		all = append([]Layer{d}, layers...)
+	}
+	for _, r := range m.Resources {
+		if r["id"] != "rules" {
+			continue
+		}
+		out, err := ApplySettings(r, all)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if _, left := out[TakesSettingsField]; left {
+			t.Fatalf("the composed file still says %s: %v", TakesSettingsField, out)
+		}
+		return out["content"].(string)
+	}
+	t.Fatal("no rules file")
+	return ""
+}
+
+func TestATakenValueIsLaidUnderTheFilesOwnName(t *testing.T) {
+	m, err := parseRaw(t, renaming())
+	if err != nil {
+		t.Fatalf("a renamed takes-config entry was refused: %v", err)
+	}
+	got := rulesComposed(t, m, Layer{From: "ace", Values: map[string]any{"url": "https://hooks.example.test/n"}})
+	var doc map[string]any
+	if err := json.Unmarshal([]byte(got), &doc); err != nil {
+		t.Fatal(err)
+	}
+	if doc["NOTIFIER_URL"] != "https://hooks.example.test/n" {
+		t.Fatalf("url was not laid as NOTIFIER_URL: %s", got)
+	}
+	if _, said := doc["url"]; said {
+		t.Fatalf("url was laid under the config key too: %s", got)
+	}
+}
+
+func TestAnUnsetRenamedValueLeavesTheFileAsItWas(t *testing.T) {
+	plain := inConfigForm()
+	base, err := parseRaw(t, plain)
+	if err != nil {
+		t.Fatal(err)
+	}
+	m, err := parseRaw(t, renaming())
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := rulesComposed(t, base)
+	if got := rulesComposed(t, m); got != want {
+		t.Fatalf("with no layer the file is\n%s\nwanted, as without the entry,\n%s", got, want)
+	}
+	other := Layer{From: "ace", Values: map[string]any{"theme": "light"}}
+	if got, want := rulesComposed(t, m, other), rulesComposed(t, base, other); got != want {
+		t.Fatalf("with url unset the file is\n%s\nwanted\n%s", got, want)
+	}
+}
+
+// A layer said before its module moved names the file's own spelling, such as nodered's timeZone on one machine.
+// Until K5 moves the layer and renames the key, that spelling still reaches the file, so the move changes no
+// machine's file; the config key wins where one layer says both.
+func TestALayerStillSayingTheFilesNameReachesItUntilItsMove(t *testing.T) {
+	m, err := parseRaw(t, renaming())
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, said := range []string{"url", "NOTIFIER_URL"} {
+		if stray := UnusedSettings(m, []Layer{{From: "ace", Values: map[string]any{said: "https://x.test"}}}); len(stray) > 0 {
+			t.Fatalf("%s, which the rules file takes, is said stray: %v", said, stray)
+		}
+		got := rulesComposed(t, m, Layer{From: "ace", Values: map[string]any{said: "https://x.test"}})
+		var doc map[string]any
+		if err := json.Unmarshal([]byte(got), &doc); err != nil {
+			t.Fatal(err)
+		}
+		if doc["NOTIFIER_URL"] != "https://x.test" || doc["url"] != nil {
+			t.Fatalf("a layer saying %s made the file %s", said, got)
+		}
+	}
+	both := rulesComposed(t, m, Layer{From: "ace", Values: map[string]any{"url": "https://key.test", "NOTIFIER_URL": "https://old.test"}})
+	if !strings.Contains(both, "https://key.test") || strings.Contains(both, "old.test") {
+		t.Fatalf("where one layer says both, the config key did not win: %s", both)
+	}
+	later := rulesComposed(t, m, Layer{From: "mesh", Values: map[string]any{"url": "https://mesh.test"}},
+		Layer{From: "ace", Values: map[string]any{"NOTIFIER_URL": "https://ace.test"}})
+	if !strings.Contains(later, "https://ace.test") {
+		t.Fatalf("a later layer's old spelling did not beat an earlier layer's key: %s", later)
+	}
+	// Who may set it is the same under either spelling: the rules file is trusted, so both are the terminal's.
+	terminal := TerminalKeys(m)
+	for _, k := range []string{"url", "NOTIFIER_URL"} {
+		if !listHolds(terminal, k) {
+			t.Fatalf("%s is not the terminal's in a trusted file: %v", k, terminal)
+		}
+	}
+}
+
+func listHolds(list []string, s string) bool {
+	for _, x := range list {
+		if x == s {
+			return true
+		}
+	}
+	return false
+}
+
+func TestARenamedEntryIsWrittenBackAsItWasSaid(t *testing.T) {
+	m, err := parseRaw(t, renaming())
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(string(raw), `"takes-config":["position","theme",{"as":"NOTIFIER_URL","key":"url"}]`) {
+		t.Fatalf("written back as %s", raw)
+	}
+	if _, err := ParseManifest(raw); err != nil {
+		t.Fatalf("read again: %v", err)
+	}
+}
+
+func TestARenamedEntryIsRefusedWhereItCouldNotHold(t *testing.T) {
+	entry := func(m map[string]any, e any) map[string]any {
+		resourceOf(m, "rules")["takes-config"] = []any{"position", "theme", e}
+		return m
+	}
+	refused(t, entry(renaming(), map[string]any{"key": "url"}), "notifier's rules", `"key" and "as"`)
+	refused(t, entry(renaming(), map[string]any{"key": "url", "as": "NOTIFIER_URL", "when": "set"}), `"key" and "as"`)
+	refused(t, entry(renaming(), map[string]any{"key": "URL", "as": "NOTIFIER_URL"}), "not a usable key")
+	refused(t, entry(renaming(), map[string]any{"key": "url", "as": "NOTIFIER URL"}), "not a usable name")
+	refused(t, entry(renaming(), map[string]any{"key": "url", "as": "endpoints"}), `"endpoints"`, "the mesh reads")
+	refused(t, entry(renaming(), map[string]any{"key": "url", "as": "theme"}), `"theme"`, "twice")
+	refused(t, entry(renaming(), map[string]any{"key": "theme", "as": "THEME"}), `"theme"`, "twice")
+	refused(t, entry(renaming(), map[string]any{"key": "nothing", "as": "NOTHING"}), `"nothing"`, "declares no such value")
+
+	kept := entry(renaming(), map[string]any{"key": "url", "as": "NOTIFIER_URL"})
+	resourceOf(kept, "rules")["protected"] = []any{"NOTIFIER_URL"}
+	refused(t, kept, `"NOTIFIER_URL"`, "protected")
+
+	// Laid only when set, so the code's own fallback holds: never required.
+	required := renaming()
+	declaration(required, "url")["required"] = true
+	delete(declaration(required, "url"), "default")
+	refused(t, required, `"url"`, "only when it is set", "never required")
+}
+
+func TestARenamedEntryIsTheConfigFormsOnly(t *testing.T) {
+	m := map[string]any{
+		"module": "notifier", "version": "1",
+		"resources": []any{
+			map[string]any{"id": "rules", "type": "file", "path": "/x/rules.json", "merge": "json", "content": "{}",
+				"takes-settings": []any{map[string]any{"key": "url", "as": "NOTIFIER_URL"}}},
+		},
+	}
+	refused(t, m, "notifier's rules", "config form")
+}

go/catalogue/config_test.go

@@ -0,0 +1,510 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+)
+
+// A module declares its config (novox/hq ADR 0348 §1, §4, §5, §6, §8, §11; design 57 package K1, issue 660):
+// one registration refusal per rule of design 57's K1, the old names read as aliases, and a module rewritten
+// from settings to config composing byte-identically.
+
+// inConfigForm is a module in the config form that registers: every value typed, described, defaulted or
+// required, placed in a file or read at runtime, and its mergeable file naming its keys.
+func inConfigForm() map[string]any {
+	return map[string]any{
+		"module":  "notifier",
+		"version": "1",
+		"config": map[string]any{
+			"font-size": map[string]any{"type": "number", "description": "the notification's font size, in points",
+				"minimum": 6, "maximum": 40, "default": 10},
+			"width": map[string]any{"type": "number", "description": "the notification's width, in pixels",
+				"default": 250},
+			"position": map[string]any{"type": "string", "description": "the corner it shows in, a word",
+				"enum": []any{"top-right", "top-left"}, "default": "top-right"},
+			"theme": map[string]any{"type": "string", "description": "the colour theme, a lower-case name",
+				"pattern": "[a-z]+", "default": "dark"},
+			"history": map[string]any{"type": "number", "description": "how many notifications it keeps, a count",
+				"default": 20, "runtime": true},
+			"sender": map[string]any{"type": "string", "description": "the address it mails a digest from",
+				"required": true},
+		},
+		"resources": []any{
+			map[string]any{"id": "configuration", "type": "file", "path": "/x/notifierrc",
+				"content": "font = Inter ${config:font-size}\nwidth = ${config:width}\nfrom = ${config:sender}\n"},
+			map[string]any{"id": "rules", "type": "file", "path": "/x/rules.json", "merge": "json",
+				"takes-config": []any{"position", "theme"}, "content": "{\"position\": \"top-right\"}\n"},
+			map[string]any{"id": "notifier", "type": "service", "unit": "notifier.service",
+				"reload-on": []any{"configuration"}, "restart-on": []any{"rules"}},
+		},
+	}
+}
+
+// declaration is one value of inConfigForm's config, to change in place.
+func declaration(m map[string]any, key string) map[string]any {
+	return m["config"].(map[string]any)[key].(map[string]any)
+}
+
+func resourceOf(m map[string]any, id string) map[string]any {
+	for _, r := range m["resources"].([]any) {
+		if r.(map[string]any)["id"] == id {
+			return r.(map[string]any)
+		}
+	}
+	return nil
+}
+
+func parseRaw(t *testing.T, m map[string]any) (Manifest, error) {
+	t.Helper()
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return ParseManifest(raw)
+}
+
+// refused is that the manifest is refused with every one of these words.
+func refused(t *testing.T, m map[string]any, words ...string) {
+	t.Helper()
+	_, err := parseRaw(t, m)
+	if err == nil {
+		t.Fatalf("registered; wanted a refusal saying %q", words)
+	}
+	for _, w := range words {
+		if !strings.Contains(err.Error(), w) {
+			t.Fatalf("refused without %q:\n%v", w, err)
+		}
+	}
+}
+
+func TestAModuleInTheConfigFormRegisters(t *testing.T) {
+	m, err := parseRaw(t, inConfigForm())
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !m.DeclaresConfig() {
+		t.Fatal("a module declaring config is not read as in the config form")
+	}
+	d := m.Settings["font-size"]
+	if d.Type != "number" || d.Description == "" || d.Minimum == nil || *d.Minimum != 6 || d.Default != float64(10) {
+		t.Fatalf("font-size read as %+v", d)
+	}
+	if s := m.Settings["sender"]; !s.Required || s.Default != nil {
+		t.Fatalf("sender read as %+v", s)
+	}
+}
+
+// Rule 1: a value without type or description.
+func TestConfigRefusesAValueWithoutTypeOrDescription(t *testing.T) {
+	m := inConfigForm()
+	delete(declaration(m, "width"), "type")
+	refused(t, m, `notifier's config value "width"`, "no type")
+	m = inConfigForm()
+	declaration(m, "width")["type"] = "colour"
+	refused(t, m, `"width"`, `type "colour"`)
+	m = inConfigForm()
+	delete(declaration(m, "width"), "description")
+	refused(t, m, `"width"`, "no description")
+}
+
+// Rule 2: a value with neither a default nor required.
+func TestConfigRefusesAValueWithNeitherDefaultNorRequired(t *testing.T) {
+	m := inConfigForm()
+	delete(declaration(m, "width"), "default")
+	refused(t, m, `"width"`, "neither a default nor required")
+	m = inConfigForm()
+	declaration(m, "sender")["default"] = "noreply@example.org"
+	refused(t, m, `"sender"`, "both a default and required")
+}
+
+// Rule 3: a default failing its validation.
+func TestConfigRefusesADefaultFailingItsValidation(t *testing.T) {
+	for _, c := range []struct {
+		key   string
+		value any
+		said  string
+	}{
+		{"font-size", 4, "below its minimum"},
+		{"font-size", 41, "above its maximum"},
+		{"font-size", "10", "not a number"},
+		{"position", "bottom", "not one of"},
+		{"theme", "Dark", "does not match"},
+	} {
+		m := inConfigForm()
+		declaration(m, c.key)["default"] = c.value
+		refused(t, m, `"`+c.key+`"`, c.said)
+	}
+}
+
+// Rule 4: an object or a list not trusted.
+func TestConfigRefusesAnObjectOrListNotTrusted(t *testing.T) {
+	for _, kind := range []string{"object", "list"} {
+		m := inConfigForm()
+		def := any(map[string]any{"a": 1})
+		if kind == "list" {
+			def = []any{"a"}
+		}
+		m["config"].(map[string]any)["rules"] = map[string]any{"type": kind, "description": "the rules, as " + kind,
+			"default": def, "runtime": true}
+		refused(t, m, `"rules"`, "is "+kind+" and not trusted")
+		m["config"].(map[string]any)["rules"].(map[string]any)["trusted"] = true
+		if _, err := parseRaw(t, m); err != nil {
+			t.Fatalf("a trusted %s is refused: %v", kind, err)
+		}
+	}
+}
+
+// withPredefined is the list of predefined keys the mesh published, for the length of a test.
+func withPredefined(t *testing.T, keys PredefinedList) {
+	t.Helper()
+	was := ReplacePublished(keys)
+	t.Cleanup(func() { ReplacePublished(was) })
+}
+
+// Rule 5: a predefined key not on the list, or of another type. Where no list is present, a value naming one is
+// refused saying so.
+func TestConfigRefusesAPredefinedKeyNotOnTheListOrOfAnotherType(t *testing.T) {
+	withPredefined(t, nil)
+	m := inConfigForm()
+	declaration(m, "font-size")["predefined"] = "font-size"
+	refused(t, m, `"font-size"`, "the list of predefined keys", "is not present")
+
+	withPredefined(t, map[string]PredefinedKey{"font-size": {Type: "number"}, "accent": {Type: "string"}})
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatalf("a value falling back to a listed key of its type is refused: %v", err)
+	}
+	m = inConfigForm()
+	declaration(m, "font-size")["predefined"] = "font-scale"
+	refused(t, m, `"font-size"`, `"font-scale"`, "not on the list")
+	m = inConfigForm()
+	declaration(m, "font-size")["predefined"] = "accent"
+	refused(t, m, `"font-size"`, `"accent"`, "is a string")
+}
+
+// Rule 6: an untrusted value falling back to a trusted predefined key.
+func TestConfigRefusesAnUntrustedValueFallingBackToATrustedKey(t *testing.T) {
+	withPredefined(t, nil)
+	m := inConfigForm()
+	declaration(m, "theme")["predefined"] = "theme"
+	refused(t, m, `"theme"`, "is not present")
+
+	withPredefined(t, map[string]PredefinedKey{"theme": {Type: "string", Trusted: true}})
+	refused(t, m, `"theme"`, "trusted", "is not")
+	declaration(m, "theme")["trusted"] = true
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatalf("a trusted value falling back to a trusted key is refused: %v", err)
+	}
+}
+
+// Rule 7: a value neither placed in a template nor read at runtime.
+func TestConfigRefusesAValueNeitherPlacedNorReadAtRuntime(t *testing.T) {
+	m := inConfigForm()
+	delete(declaration(m, "history"), "runtime")
+	refused(t, m, `"history"`, "${config:history}", `"runtime": true`)
+	// Taken by a mergeable file is placed.
+	m = inConfigForm()
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// Rule 8: a placeholder naming an undeclared value.
+func TestConfigRefusesAPlaceholderNamingAnUndeclaredValue(t *testing.T) {
+	m := inConfigForm()
+	resourceOf(m, "configuration")["content"] = "font = ${config:font-size}\nwidth = ${config:width}\n" +
+		"from = ${config:sender}\ncolour = ${config:colour}\n"
+	refused(t, m, "${config:colour}", "declares no such value")
+}
+
+// Rule 9: a reload-on or restart-on naming a file the module does not declare.
+func TestConfigRefusesAReloadOrRestartOnNamingAnUndeclaredFile(t *testing.T) {
+	m := inConfigForm()
+	resourceOf(m, "notifier")["reload-on"] = []any{"configuration", "dunstrc"}
+	refused(t, m, "reload-on", `"dunstrc"`, "declares no such")
+	m = inConfigForm()
+	resourceOf(m, "notifier")["restart-on"] = []any{"rule"}
+	refused(t, m, "restart-on", `"rule"`)
+	// Another module's file, and one the mesh makes for the module, are not the module's to declare.
+	m = inConfigForm()
+	resourceOf(m, "notifier")["restart-on"] = []any{"rules", "resolver.fact-zones", "secret-mail", "composed-jails"}
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatalf("refused: %v", err)
+	}
+}
+
+// Rule 10: a moved module's mergeable file not naming its keys under takes-config.
+func TestConfigRefusesAMergeableFileNotNamingItsKeys(t *testing.T) {
+	m := inConfigForm()
+	delete(resourceOf(m, "rules"), "takes-config")
+	// position and theme are then placed nowhere; say they are read at runtime so only the file's rule speaks.
+	declaration(m, "position")["runtime"] = true
+	declaration(m, "theme")["runtime"] = true
+	refused(t, m, "rules", "names no takes-config")
+}
+
+// Rule 11: a mesh word, puid or pgid in takes-config.
+func TestConfigRefusesAMeshWordOrAnAccountFactInTakesConfig(t *testing.T) {
+	for _, word := range []string{"ports", "expose", "reach", "endpoints", "places", "accesses", "networks", "puid", "pgid"} {
+		m := inConfigForm()
+		resourceOf(m, "rules")["takes-config"] = []any{"position", "theme", word}
+		refused(t, m, `"`+word+`"`, "takes-config")
+	}
+}
+
+// A module uses one form or the other, never both.
+func TestAManifestMixingTheConfigAndSettingsFormsIsRefused(t *testing.T) {
+	m := inConfigForm()
+	resourceOf(m, "configuration")["content"] = "font = ${config:font-size}\nwidth = ${setting:width}\nfrom = ${config:sender}\n"
+	refused(t, m, "mixes", "${setting:", "config")
+
+	m = inConfigForm()
+	delete(resourceOf(m, "rules"), "takes-config")
+	resourceOf(m, "rules")["takes-settings"] = []any{"position", "theme"}
+	refused(t, m, "mixes", "takes-settings")
+
+	m = inConfigForm()
+	m["settings"] = map[string]any{"colour": map[string]any{"kind": "preference", "default": "red", "why": "red"}}
+	refused(t, m, "mixes", "settings")
+}
+
+// The settings form keeps its own declaration; the config form's has no kind or why.
+func TestEachFormKeepsItsOwnDeclaration(t *testing.T) {
+	m := inConfigForm()
+	declaration(m, "width")["why"] = "fits a title"
+	refused(t, m, `"width"`, "why")
+
+	err := parsed(t, Manifest{Module: "notifier",
+		Settings: map[string]SettingDeclaration{"width": {Kind: KindPreference, Default: float64(250),
+			Why: "fits a title", Type: "number"}},
+		Resources: []map[string]any{{"id": "c", "type": "file", "path": "/x", "content": "${setting:width}"}}})
+	if err == nil || !strings.Contains(err.Error(), "under config") {
+		t.Fatalf("a typed value under settings: %v", err)
+	}
+}
+
+// What the mesh holds is what was written: a module in the config form is written back in it, and read again
+// the same.
+func TestAConfigManifestIsWrittenBackInItsOwnForm(t *testing.T) {
+	m, err := parseRaw(t, inConfigForm())
+	if err != nil {
+		t.Fatal(err)
+	}
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, said := range []string{`"config":`, `${config:font-size}`, `"takes-config":`, `"required":true`} {
+		if !strings.Contains(string(raw), said) {
+			t.Fatalf("written back without %s: %s", said, raw)
+		}
+	}
+	for _, unsaid := range []string{`"settings":`, `${setting:`, `"takes-settings"`, `"kind"`, `"why"`, `"default":null`} {
+		if strings.Contains(string(raw), unsaid) {
+			t.Fatalf("written back with %s: %s", unsaid, raw)
+		}
+	}
+	again, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	twice, _ := json.Marshal(again)
+	if !bytes.Equal(raw, twice) {
+		t.Fatalf("read again it is written\n%s\nwhere it was\n%s", twice, raw)
+	}
+}
+
+// A module in the settings form is written back byte for byte as before.
+func TestASettingsManifestIsWrittenBackAsBefore(t *testing.T) {
+	d := SettingDeclaration{Kind: KindPreference, Default: float64(10), Why: "readable"}
+	raw, err := json.Marshal(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(raw) != `{"kind":"preference","default":10,"why":"readable"}` {
+		t.Fatalf("written as %s", raw)
+	}
+}
+
+// settingsDunst is the dunst module as it is written today; configDunst the same module rewritten from settings to
+// config.
+const settingsDunst = `{"module": "dunst", "version": "1",
+  "settings": {
+    "font-size": {"kind": "preference", "default": 10, "why": "10 points of Inter reads well on a screen of about 100 DPI"},
+    "width": {"kind": "preference", "default": 250, "why": "250 pixels fits a title of about forty characters at 10 points"}
+  },
+  "resources": [
+    {"id": "package", "type": "package", "package": "dunst"},
+    {"id": "configuration", "type": "file", "path": "/home/me/.config/dunst/dunstrc", "mode": "0644",
+     "content": "[global]\n    font = Inter ${setting:font-size}\n    width = ${setting:width}\n"},
+    {"id": "rules", "type": "file", "path": "/home/me/.config/dunst/rules.json", "merge": "json",
+     "takes-settings": [], "content": "{\"urgency\": \"low\"}\n"},
+    {"id": "notifier", "type": "service", "unit": "dunst.service", "reload-on": ["configuration"]}
+  ]}`
+
+const configDunst = `{"module": "dunst", "version": "1",
+  "config": {
+    "font-size": {"type": "number", "description": "the font size of a notification, in points", "minimum": 6,
+                  "maximum": 40, "default": 10},
+    "width": {"type": "number", "description": "the width of a notification, in pixels", "minimum": 100,
+              "default": 250}
+  },
+  "resources": [
+    {"id": "package", "type": "package", "package": "dunst"},
+    {"id": "configuration", "type": "file", "path": "/home/me/.config/dunst/dunstrc", "mode": "0644",
+     "content": "[global]\n    font = Inter ${config:font-size}\n    width = ${config:width}\n"},
+    {"id": "rules", "type": "file", "path": "/home/me/.config/dunst/rules.json", "merge": "json",
+     "takes-config": [], "content": "{\"urgency\": \"low\"}\n"},
+    {"id": "notifier", "type": "service", "unit": "dunst.service", "reload-on": ["configuration"]}
+  ]}`
+
+// ${config:<key>} fills exactly as ${setting:<key>} does: the module rewritten from settings to config composes
+// to the same bytes, with no layer, with the node's, and with the mesh's under the node's.
+func TestAModuleRewrittenFromSettingsToConfigComposesByteIdentically(t *testing.T) {
+	composed := func(manifest string, layers []Layer) []byte {
+		t.Helper()
+		m, err := ParseManifest([]byte(manifest))
+		if err != nil {
+			t.Fatal(err)
+		}
+		r := anAdoptedAnchor()
+		r.Modules = append(r.Modules, m)
+		with := anchorRendering(false)
+		if layers != nil {
+			with.Settings["dunst"] = layers
+		}
+		c, err := r.Compose(with)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if why, left := c.LeftOut["dunst"]; left {
+			t.Fatalf("dunst was left out: %s", why)
+		}
+		raw, err := json.Marshal(c)
+		if err != nil {
+			t.Fatal(err)
+		}
+		return raw
+	}
+	for _, layers := range [][]Layer{
+		nil,
+		{{From: "anchor", Values: map[string]any{"font-size": float64(13)}}},
+		{{From: MeshWideLayer, Values: map[string]any{"width": float64(300)}},
+			{From: "anchor", Values: map[string]any{"font-size": float64(12), "width": float64(320)}}},
+	} {
+		was, is := composed(settingsDunst, layers), composed(configDunst, layers)
+		if !bytes.Equal(was, is) {
+			t.Fatalf("composed differently with %v:\nsettings: %s\nconfig:   %s", layers, was, is)
+		}
+		if !strings.Contains(string(is), "font = Inter 1") || strings.Contains(string(is), "${config:") {
+			t.Fatalf("not filled: %s", is)
+		}
+	}
+}
+
+// A key a mergeable file takes is a config value like every other: one not declared under config is refused by
+// name (ADR 0348 §4, review of mesh-controller#320).
+func TestConfigRefusesATakesConfigKeyNotDeclared(t *testing.T) {
+	m := inConfigForm()
+	resourceOf(m, "rules")["takes-config"] = []any{"position", "theme", "urgency"}
+	refused(t, m, `"urgency"`, "takes-config", "declares no such value under config")
+}
+
+// A required value nothing sets is refused at composition in the config form's words: ${config:<key>} and the
+// config verb, never `settings set` (review of mesh-controller#320). The settings form's words are unchanged.
+func TestAnUnsetRequiredValueIsRefusedInTheConfigFormsWords(t *testing.T) {
+	m, err := parseRaw(t, inConfigForm())
+	if err != nil {
+		t.Fatal(err)
+	}
+	r := anAdoptedAnchor()
+	r.Modules = append(r.Modules, m)
+	composed, err := r.Compose(anchorRendering(false))
+	if err != nil {
+		t.Fatal(err)
+	}
+	why, left := composed.LeftOut["notifier"]
+	if !left {
+		t.Fatal("a module whose required value nothing sets was not left out")
+	}
+	for _, said := range []string{"${config:sender}", `required config value "sender"`, "config verb"} {
+		if !strings.Contains(why, said) {
+			t.Fatalf("left out without %q: %s", said, why)
+		}
+	}
+	for _, unsaid := range []string{"${setting:", "settings set"} {
+		if strings.Contains(why, unsaid) {
+			t.Fatalf("left out in the settings form's words (%q): %s", unsaid, why)
+		}
+	}
+	var unset *UnsetSettingError
+	if err := unsetInConfigWords(settingInto(map[string]any{"type": "file", "content": "${setting:sender}"}, nil,
+		"notifier"), m); !errors.As(err, &unset) || unset.Setting != "sender" {
+		t.Fatalf("not typed as a value nobody gave: %v", err)
+	}
+
+	settingsForm := notifier()
+	settingsForm.Resources[0]["content"] = "from = ${setting:domain}\n"
+	err = unsetInConfigWords(settingInto(settingsForm.Resources[0], nil, "notifier"), settingsForm)
+	if err == nil || !strings.Contains(err.Error(), "`settings set notifier <file>`") {
+		t.Fatalf("the settings form's refusal changed: %v", err)
+	}
+}
+
+// A value named after the operator's own (a url, a user, an address) is `required` where nothing falls back when
+// it is unset; where a mergeable file takes it and no placeholder asks for it, the file's own content (or the
+// module's code reading the file) falls back, so it keeps a default and stays optional, as it is today: the
+// operator's decision on issue 664's second question (issue 735).
+func TestAnOperatorNamedValueAFileFallsBackOnMayHaveADefault(t *testing.T) {
+	m := inConfigForm()
+	m["config"].(map[string]any)["url"] = map[string]any{"type": "string",
+		"description": "the address the notifier posts to, a URL; empty for the one the file's software picks",
+		"default":     ""}
+	resourceOf(m, "rules")["takes-config"] = []any{"position", "theme", "url"}
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatalf("a taken value named after the operator's, with a default, was refused: %v", err)
+	}
+
+	// A placeholder asking for it has no fallback but the default, which would put a value in the definition
+	// where the operator's belongs (ADR 0112).
+	asked := inConfigForm()
+	asked["config"].(map[string]any)["url"] = map[string]any{"type": "string", "description": "a URL", "default": ""}
+	resourceOf(asked, "rules")["takes-config"] = []any{"position", "theme", "url"}
+	resourceOf(asked, "configuration")["content"] = "font = Inter ${config:font-size}\nwidth = ${config:width}\n" +
+		"from = ${config:sender}\npost = ${config:url}\n"
+	refused(t, asked, `"url"`, `a key naming "url" is the operator's value`)
+
+	// Read by the module's code alone, nothing in the definition says it falls back.
+	runtime := inConfigForm()
+	runtime["config"].(map[string]any)["url"] = map[string]any{"type": "string", "description": "a URL",
+		"default": "", "runtime": true}
+	refused(t, runtime, `"url"`, `a key naming "url" is the operator's value`)
+}
+
+// 1658/AC1: a value whose only placement is ${config:key} in an item's text is placed.
+func TestConfigCountsAnItemsTextAsAPlacement(t *testing.T) {
+	m := map[string]any{
+		"module": "m", "version": "1",
+		"config": map[string]any{
+			"k": map[string]any{"type": "string", "description": "a word the item says", "default": "x"},
+		},
+		"items": []any{map[string]any{"collection": "a", "content": "k = ${config:k}\n"}},
+	}
+	if _, err := parseRaw(t, m); err != nil {
+		t.Fatalf("a value placed only in an item's text is refused: %v", err)
+	}
+}
+
+// 1658/AC2: a declared value placed nowhere, with an item that does not say it, is still refused.
+func TestConfigStillRefusesAValueNoItemPlaces(t *testing.T) {
+	m := map[string]any{
+		"module": "m", "version": "1",
+		"config": map[string]any{
+			"k": map[string]any{"type": "string", "description": "a word nothing says", "default": "x"},
+		},
+		"items": []any{map[string]any{"collection": "a", "content": "k = fixed\n"}},
+	}
+	refused(t, m, `"k"`, "placed nowhere")
+}

go/catalogue/consumer_into_serves.go

@@ -0,0 +1,338 @@
+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 0202, 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 inside the bound of the provision serving them: a provider that serves one as a DNS label
+// bounds it at 63 or less (CheckServes, novox/hq ADR 0225), and one that serves it at all without
+// saying is held to twenty (IdentityBoundOf). 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 {
+				// A provider's own name is filled only in a value of its own (novox/hq ADR 0346): one
+				// nested in a list or an object would be served as the placeholder, unsaid.
+				problems = append(problems, nestedOwnNames(m, provision, key, m.Serves[provision][key])...)
+				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))
+			}
+			// And the provider's own names it may serve (novox/hq ADR 0346).
+			problems = append(problems, checkServedOwnNames(m, provision, key, text)...)
+			// A label longer than DNS keeps is not truncated here (asDNSLabel), so the offer's own
+			// bound has to keep the identity inside one (ADR 0225).
+			if strings.Contains(text, "${consumer:as:dns}") {
+				if b := m.IdentityBoundOf(provision); !b.Bounded() || b.Max > dnsLabelLimit {
+					problems = append(problems, fmt.Sprintf(
+						"%s serves %s's consumers their identity as a DNS label in %q, and bounds "+
+							"that identity at %s: a label keeps %d — state an `identity` of at most %d",
+						m.Module, provision, key, boundWords(b), dnsLabelLimit, dnsLabelLimit))
+				}
+			}
+		}
+	}
+	return problems
+}
+
+// dnsLabelLimit is the longest DNS label (RFC 1035 §2.3.4).
+const dnsLabelLimit = 63
+
+func boundWords(b IdentityBound) string {
+	if !b.Bounded() {
+		return "nothing"
+	}
+	return fmt.Sprintf("%d", b.Max)
+}
+
+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 0202).
+//
+// 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 0202)",
+				consumer, local, provision, m.Module, orNothing(sortedAnyKeys(names)))
+		}
+		settled, err := Settle(names, WithDefaults(m, 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 0202, 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
+}

go/catalogue/consumers.go

@@ -0,0 +1,110 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"slices"
+)
+
+// A provider's consumers' credentials, in a file of the provider's own (novox/hq ADR 0373, issue 679).
+//
+// A provider in the tool runner may not ask the vault (ADR 0349 clause 11, ADR 0370 clause 2), so its template names
+// `${consumers:<provision>}` and its machine's provisioner client fills it: one entry per consumer bound to the
+// provider for that provision, each carrying the credential the vault keeps for the pair. Only the client fills it,
+// so the placeholder is a provider's alone, for a provision it provides, in a file only the provider reads (mode 0600
+// or 0400, owned at runtime, so a change on disk is written back); and a module not handed to the client on a machine
+// is refused there, never written the placeholder's text, nor an empty list the provider would read as no consumers.
+
+// ConsumersNamespace is a provider's consumers' credentials' placeholder namespace, `${consumers:<provision>}`.
+const ConsumersNamespace = "consumers"
+
+// ofConsumers is where a provider places its consumers' credentials. Loose inside the braces, so a misspelt name is
+// refused rather than passed over.
+var ofConsumers = regexp.MustCompile(`\$\{consumers:([^}]*)\}`)
+
+// consumersPlaceholderProblems is what is wrong with one resource's ${consumers:…}: placed only in a file's content,
+// for a provision the module provides, in a file only the provider reads and the client writes back.
+func consumersPlaceholderProblems(m Manifest, r map[string]any) []string {
+	var problems []string
+	for _, field := range sortedKeys(r) {
+		v, ok := r[field].(string)
+		if !ok {
+			continue
+		}
+		for _, f := range ofConsumers.FindAllStringSubmatch(v, -1) {
+			switch {
+			case field != "content" || fmt.Sprint(r["type"]) != "file":
+				problems = append(problems, fmt.Sprintf("%s's resource %v names %s in its %s; a provider's consumers "+
+					"are placed only in a file's content (novox/hq ADR 0373)", m.Module, r["id"], f[0], field))
+				continue
+			case !slices.ContainsFunc(m.Provides, func(o Offer) bool { return o.Name == f[1] }):
+				problems = append(problems, fmt.Sprintf("%s's resource %v names %s, and %s does not provide %q: only a "+
+					"provider's template holds its consumers' credentials (novox/hq ADR 0373)", m.Module, r["id"], f[0],
+					m.Module, f[1]))
+			}
+			if mode := fmt.Sprint(r["mode"]); mode != "0600" && mode != "0400" {
+				problems = append(problems, fmt.Sprintf("%s's resource %v holds its consumers' credentials (%s) with "+
+					"mode %q: the provider alone reads it, 0600 or 0400 (novox/hq ADR 0373)", m.Module, r["id"], f[0],
+					r["mode"]))
+			}
+			if owner := ownershipOf(r); owner != RuntimeOwned {
+				problems = append(problems, fmt.Sprintf("%s's resource %v holds its consumers' credentials (%s) and is "+
+					"%s at runtime: it is owned, written back whenever it differs (novox/hq ADR 0373)", m.Module,
+					r["id"], f[0], owner))
+			}
+		}
+	}
+	return problems
+}
+
+// consumersHandedOnly says what a file naming ${consumers:…} is where it would be written the old way: the provisioner's
+// client alone fills it, so on a machine that does not hand the module it is **left out** of the declaration, never
+// written as that text or as an empty list the provider would read as no consumers, and never the reason the module is
+// refused: a provider not handed there keeps working as it did, from its grant files (novox/hq ADR 0373, issue 780).
+// A moved module judged from its repository's tree (WithTemplatesFrom: `module check`), on a machine
+// that would hand it, has no templates archive to hand and is judged as it composes; there the placeholder is judged
+// and taken out of the text, since what is composed so is never sent (judged answers whether the file is so judged).
+func consumersHandedOnly(m Manifest, r map[string]any, with Rendering) (judged, leftOut bool) {
+	content, _ := r["content"].(string)
+	switch {
+	case ofConsumers.FindString(content) == "":
+		return false, false
+	case m.Moved && m.Handed == nil && with.Hands && with.Provisioner != "":
+		return true, false
+	}
+	return false, true
+}
+
+// consumersLeftOutLine is the plan's one line for a file left out because the module is not handed.
+func consumersLeftOutLine(m Manifest, r map[string]any) string {
+	return fmt.Sprintf("%s's %v names ${consumers:…}, which the provisioner's client alone fills: left out, handed only "+
+		"(novox/hq ADR 0373)", m.Module, r["id"])
+}
+
+// consumersNotHanded is consumersHandedOnly as a refusal, for a caller that has no way to leave the file out.
+func consumersNotHanded(m Manifest, r map[string]any, with Rendering) (judged bool, err error) {
+	judged, left := consumersHandedOnly(m, r, with)
+	if left {
+		return false, fmt.Errorf("%s's resource %v names %s, which the provisioner's client alone fills, and %s is not "+
+			"handed to it on this machine: it would be written as that text, or empty, and the provider would read no "+
+			"consumers (novox/hq ADR 0373)", m.Module, r["id"], ofConsumers.FindString(fmt.Sprint(r["content"])), m.Module)
+	}
+	return judged, nil
+}
+
+// consumersOfTemplate is what is wrong with a handed file's template naming ${consumers:…}, judged on the file's
+// resource as if its text were inline.
+func consumersOfTemplate(m Manifest, id, text string) []string {
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["id"]) != id {
+			continue
+		}
+		withText := map[string]any{}
+		for k, v := range r {
+			withText[k] = v
+		}
+		withText["content"] = text
+		return consumersPlaceholderProblems(m, withText)
+	}
+	return nil
+}

go/catalogue/consumes_start_test.go

@@ -0,0 +1,24 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// 1279/AC4 (ADR 0443 §4): no module is given a way to ask where its consumer starts. A consumes entry is an event's
+// name; one that carries a key asking for the stream's history is refused by name, so the safe start is the only one.
+func TestAConsumesEntryAskingWhereItStartsIsRefused(t *testing.T) { // 1279/AC4
+	for _, key := range []string{"from", "start", "deliver"} {
+		raw := `{"module":"audit","version":"1","consumes":[{"event":"shop.order.placed","` + key + `":"beginning"}]}`
+		_, err := ParseManifest([]byte(raw))
+		if err == nil {
+			t.Fatalf("a consumes entry with %q was accepted", key)
+		}
+		if !strings.Contains(err.Error(), `"`+key+`"`) || !strings.Contains(err.Error(), "consumes") {
+			t.Errorf("the refusal for %q does not name the key and the field: %v", key, err)
+		}
+	}
+	if _, err := ParseManifest([]byte(`{"module":"audit","version":"1","consumes":["shop.order.placed"]}`)); err != nil {
+		t.Errorf("a plain consumes entry was refused: %v", err)
+	}
+}

go/catalogue/contributes_test.go

@@ -0,0 +1,412 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// The other half of an edge.
+//
+// `requires` says a thing must be there. It never said what to do with it — a web application
+// requiring a reverse proxy has to say *which name, which port*, and there was nowhere to put
+// that. The two modules that needed it most, the proxy and the VPN, went round the outside and
+// opened a connection to the control plane's database, which is why every node held a credential
+// to it permanently.
+
+func published(module, host string, port int) Manifest {
+	return Manifest{Module: module, Version: "1",
+		Contributes: map[string]map[string]any{
+			"reverse-proxy": {"host": host, "port": port},
+		}}
+}
+
+func proxy() Manifest {
+	return Manifest{Module: "traefik", Version: "1",
+		Provides: Offers("reverse-proxy"),
+		Receives: map[string]string{"reverse-proxy": "/etc/traefik/mesh.json"},
+		Resources: []map[string]any{
+			{"id": "up", "type": "service", "unit": "traefik", "state": "running",
+				"restart-on": []any{ReceivedID("reverse-proxy")}},
+		}}
+}
+
+// received digs the delivered contributions back out of a declaration.
+func received(t *testing.T, out []map[string]any) []Contribution {
+	t.Helper()
+	for _, r := range out {
+		if r["path"] != "/etc/traefik/mesh.json" {
+			continue
+		}
+		body := r["content"].(string)
+		var parsed struct {
+			Requirement string         `json:"requirement"`
+			Given       []Contribution `json:"given"`
+		}
+		if err := json.Unmarshal([]byte(body), &parsed); err != nil {
+			t.Fatalf("the file the proxy is given is not readable: %v\n%s", err, body)
+		}
+		if parsed.Requirement != "reverse-proxy" {
+			t.Fatalf("the file does not say what it is about: %q", parsed.Requirement)
+		}
+		return parsed.Given
+	}
+	t.Fatalf("the provider was given no file at all: %v", out)
+	return nil
+}
+
+func TestTheFileTheProviderGetsIsMachineReadable(t *testing.T) {
+	// It is written for a program, and the first version put a `//` header above the JSON — a
+	// file that says "do not edit" to a person and fails to parse for the thing meant to read it.
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	for _, r := range mustDeclare(t, got) {
+		if r["path"] != "/etc/traefik/mesh.json" {
+			continue
+		}
+		var any map[string]any
+		if err := json.Unmarshal([]byte(r["content"].(string)), &any); err != nil {
+			t.Fatalf("the file is not parseable: %v\n%s", err, r["content"])
+		}
+		if note, _ := any["generated"].(string); !strings.Contains(note, "do not edit") {
+			// Inside the document rather than above it, so it reaches a person without
+			// breaking the parse.
+			t.Fatalf("the file does not say it is generated: %v", any["generated"])
+		}
+		return
+	}
+	t.Fatal("no received file")
+}
+
+func TestAModuleTellsItsProviderWhatItNeeds(t *testing.T) {
+	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := got.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, out)
+	if len(given) != 1 || given[0].From != "board" {
+		t.Fatalf("the proxy was not told about board: %v", given)
+	}
+	if given[0].Values["host"] != "board" || given[0].Values["port"] != float64(8080) {
+		t.Fatalf("the contribution did not survive: %v", given[0].Values)
+	}
+}
+
+func TestContributingToSomethingIsRequiringIt(t *testing.T) {
+	// Asking to be published means a publisher must exist. A module that had to say both would
+	// eventually say one, and the failure would be a machine where nothing serves the route.
+	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(strings.Join(names(got), " "), "traefik") {
+		t.Fatalf("contributing to reverse-proxy did not bring one in: %v", names(got))
+	}
+}
+
+func TestNothingToContributeToIsRefused(t *testing.T) {
+	_, err := Resolve(shelf(published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("a module was published through a proxy that does not exist")
+	}
+	if !strings.Contains(err.Error(), "reverse-proxy") {
+		t.Fatalf("the refusal does not name what is missing: %v", err)
+	}
+}
+
+func TestEveryPublisherOnTheMachineIsInOneFile(t *testing.T) {
+	got, err := Resolve(shelf(proxy(),
+		published("board", "board", 8080),
+		published("archive", "archive", 9000),
+	), []string{"board", "archive"}, workstation(), World{})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, mustDeclare(t, got))
+	if len(given) != 2 {
+		t.Fatalf("the proxy was told about %d of 2: %v", len(given), given)
+	}
+	// Ordered by module, because this becomes a file and a file whose lines move about looks
+	// changed when nothing changed — which would restart the proxy for ever.
+	if given[0].From != "archive" || given[1].From != "board" {
+		t.Fatalf("the order is not stable: %v", given)
+	}
+}
+
+func TestAProviderWithNoConsumersStillGetsTheFile(t *testing.T) {
+	// Empty rather than absent. A provider that finds no file cannot tell "nothing asked for me"
+	// from "the mesh never wrote it", and those want completely different responses — the same
+	// rule the host follows about a service that does not exist.
+	got, err := Resolve(shelf(proxy()), []string{"traefik"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if given := received(t, mustDeclare(t, got)); len(given) != 0 {
+		t.Fatalf("got %v", given)
+	}
+}
+
+func TestTheProviderCanReloadWhenTheRoutesChange(t *testing.T) {
+	// A proxy that got a new route and did not reload is a route that silently does not work.
+	// The same fault the private network had when a peer list changed under a running interface,
+	// which is why the received file has a name a module can point at.
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	out := mustDeclare(t, got)
+	for _, r := range out {
+		if r["type"] != "service" {
+			continue
+		}
+		reflects, ok := r["restart-on"].([]any)
+		if !ok || len(reflects) != 1 {
+			t.Fatalf("the proxy does not reflect anything: %v", r)
+		}
+		if reflects[0] != "traefik."+ReceivedID("reverse-proxy") {
+			t.Fatalf("it reflects %v, which is not the file it was given", reflects[0])
+		}
+		return
+	}
+	t.Fatal("no service in the declaration")
+}
+
+func TestARouteCanBeSetPerMesh(t *testing.T) {
+	// The hostname is exactly the kind of thing that differs between one mesh and the next. A
+	// module whose route could not be set would have to be edited to be reused anywhere.
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	out, err := got.Declaration(Rendering{Settings: SettingsBy{
+		"board": {{From: "the mesh", Values: map[string]any{"host": "dashboard"}}},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, out)
+	if given[0].Values["host"] != "dashboard" {
+		t.Fatalf("the setting did not reach the route: %v", given[0].Values)
+	}
+	if given[0].Values["port"] != float64(8080) {
+		t.Fatalf("setting the host dropped the port: %v", given[0].Values)
+	}
+}
+
+func TestASettingReachesAContributionOnlyWhereItDeclaresTheKey(t *testing.T) {
+	// novox/hq 04-ISSUES/173: the mail module's site name, set so its environment file could read
+	// it, arrived in every route it contributed. A setting overrides a key the contribution
+	// declares and adds none — the provider reads the contribution as a contract.
+	got, _ := Resolve(shelf(proxy(), published("board", "board", 8080)), []string{"board"}, workstation(), World{})
+
+	out, err := got.Declaration(Rendering{Settings: SettingsBy{
+		"board": {{From: "the mesh", Values: map[string]any{"host": "dashboard", "sitename": "Board"}}},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, out)
+	if given[0].Values["host"] != "dashboard" {
+		t.Fatalf("the setting did not override the route's host: %v", given[0].Values)
+	}
+	if _, leaked := given[0].Values["sitename"]; leaked {
+		t.Fatalf("a setting the route never declared reached the proxy: %v", given[0].Values)
+	}
+}
+
+func TestReceivingWhatYouDoNotProvideIsRefused(t *testing.T) {
+	// It would create a file nobody ever writes to, on a machine where nothing asked for it.
+	_, err := ParseManifest([]byte(`{"module":"traefik","version":"1",
+		"receives":{"reverse-proxy":"/etc/traefik/mesh.json"}}`))
+	if err == nil {
+		t.Fatal("a module received contributions to something it does not provide")
+	}
+	if !strings.Contains(err.Error(), "does not provide") {
+		t.Fatalf("unhelpful refusal: %v", err)
+	}
+}
+
+func TestAnEmptyContributionIsRefused(t *testing.T) {
+	// Either a mistake or a requirement written the long way round, and both are better said.
+	_, err := ParseManifest([]byte(`{"module":"board","version":"1",
+		"contributes":{"reverse-proxy":{}}}`))
+	if err == nil {
+		t.Fatal("a module contributed nothing and was accepted")
+	}
+	if !strings.Contains(err.Error(), "require it") {
+		t.Fatalf("the refusal does not say what to do instead: %v", err)
+	}
+}
+
+// A provision answered from anywhere in the mesh has consumers on other machines, and the
+// provider has to know who they are. Contributions were node-local until this, which meant the
+// one case that most needed them was the one they did not reach.
+
+func provider() Manifest {
+	return Manifest{Module: "postgres", Version: "1",
+		Provides: FromAnywhere("postgres-database"),
+		Receives: map[string]string{"postgres-database": "/var/lib/postgres/grants/mesh.json"},
+		Grants:   map[string]string{"postgres-database": "/var/lib/postgres/grants"},
+	}
+}
+
+// oneGrant is a declaration with a single consumer on another machine.
+func oneGrant(t *testing.T) []map[string]any {
+	t.Helper()
+	got, err := Resolve(shelf(provider()), []string{"postgres"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := got.Declaration(Rendering{Grants: []Grant{{
+		Provision: "postgres-database", Consumer: "workstation", From: "meshboard",
+		Values: map[string]any{"name": "meshboard"}, Sealed: "c2VhbGVk",
+	}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return out
+}
+
+func grantedTo(t *testing.T, out []map[string]any) []Contribution {
+	t.Helper()
+	for _, r := range out {
+		if r["path"] != "/var/lib/postgres/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 manifest: %v", out)
+	return nil
+}
+
+func TestAProviderIsToldAboutConsumersOnOtherMachines(t *testing.T) {
+	// A database told to create a password and not who for can do nothing with it.
+	given := grantedTo(t, oneGrant(t))
+	if len(given) != 1 {
+		t.Fatalf("got %v", given)
+	}
+	if given[0].Node != "workstation" || given[0].From != "meshboard" {
+		t.Fatalf("it does not say who asked: %v", given[0])
+	}
+	if given[0].Values["name"] != "meshboard" {
+		t.Fatalf("it does not say what was asked for: %v", given[0].Values)
+	}
+}
+
+func TestTheManifestNamesTheFileRatherThanCarryingTheCredential(t *testing.T) {
+	// The mesh discarded the value and could not put it here if it wanted to. What is here is
+	// where to find it — and the readable half therefore stays readable.
+	out := oneGrant(t)
+	given := grantedTo(t, out)
+	// Named after the machine and the module, because a consumer is both (novox/hq
+	// 04-ISSUES/022). The machine alone, two modules on one node wrote to one path.
+	if given[0].Secret != "/var/lib/postgres/grants/workstation.meshboard.secret" {
+		t.Fatalf("the manifest does not name the credential's file: %q", given[0].Secret)
+	}
+	for _, r := range out {
+		if r["path"] != "/var/lib/postgres/grants/mesh.json" {
+			continue
+		}
+		if strings.Contains(r["content"].(string), "c2VhbGVk") {
+			t.Fatal("the readable manifest carries the sealed credential")
+		}
+	}
+}
+
+func TestTheCredentialItselfLandsSealedBesideIt(t *testing.T) {
+	for _, r := range oneGrant(t) {
+		if r["path"] != "/var/lib/postgres/grants/workstation.meshboard.secret" {
+			continue
+		}
+		if r["sealed"] != "c2VhbGVk" {
+			t.Fatalf("got %v", r)
+		}
+		if r["content"] != nil {
+			t.Fatal("a credential was written in the clear")
+		}
+		return
+	}
+	t.Fatal("no credential file")
+}
+
+func TestAConsumersOwnContributionsAreStillThere(t *testing.T) {
+	// Cross-node grants are merged in with this machine's own, because from the provider's side
+	// they are the same thing — somebody wanting something — and a provider that had to read two
+	// lists would read one of them.
+	got, err := Resolve(shelf(proxy(), published("board", "board", 8080)),
+		[]string{"board"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, mustDeclare(t, got))
+	if len(given) != 1 || given[0].Node != "" {
+		t.Fatalf("a local contribution grew a node: %v", given)
+	}
+}
+
+func TestARequireOnlyConsumerOfAParameterlessProvisionStillAsks(t *testing.T) {
+	// A consumer that requires a parameterless provision (one whose serves names no consumer key —
+	// redis-cache, amqp) contributes no payload, but it still ASKS for the provision and must be
+	// granted a credential. Keying "asks" on contributions alone gave its grant From="" — read as
+	// withdrawn — so the provider never created the account and the consumer authenticated nowhere.
+	r := Resolution{
+		Node: "laptop",
+		Modules: []Manifest{{
+			Module:   "amqp-ping",
+			Requires: []string{"amqp"},
+		}},
+	}
+	values, asks, err := r.ContributionsFrom("amqp", "amqp-ping", SettingsBy{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !asks {
+		t.Fatal("a require-only consumer was treated as not asking; its grant would be withdrawn and it would never be provisioned")
+	}
+	if values == nil {
+		t.Fatalf("asks is true but values is nil; expected an empty contribution, got %v", values)
+	}
+}
+
+func TestAConsumerThatStoppedAskingIsWithdrawn(t *testing.T) {
+	// Withdrawal is how a credential is taken away. The provisioner removes what nobody asks for,
+	// and it can only do that if the mesh stops asking — a consumer that was unassigned would
+	// otherwise keep a working login for ever, and nothing would say so.
+	//
+	// A grant with no asking module is exactly that state: the mesh still holds the secret,
+	// because it is sealed and unusable to the mesh anyway, and the machine no longer wants it.
+	got, err := Resolve(shelf(provider()), []string{"postgres"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	out, err := got.Declaration(Rendering{Grants: []Grant{
+		{Provision: "postgres-database", Consumer: "still-here", From: "meshboard",
+			Values: map[string]any{"name": "meshboard"}, Sealed: "c2VhbGVk"},
+		{Provision: "postgres-database", Consumer: "gone-away", Sealed: "c3RhbGU="},
+	}})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	given := grantedTo(t, out)
+	if len(given) != 1 || given[0].Node != "still-here" {
+		t.Fatalf("the provider is still told about a machine that stopped asking: %v", given)
+	}
+	// And no credential is written for it either, or the provisioner would find a file for a
+	// consumer its manifest does not mention and have to guess what that means.
+	for _, r := range out {
+		if path, _ := r["path"].(string); strings.Contains(path, "gone-away") {
+			t.Fatalf("a withdrawn consumer's credential is still delivered: %v", r)
+		}
+	}
+}

go/catalogue/contribution_dependencies_test.go

@@ -0,0 +1,136 @@
+package catalogue
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// Defends novox/hq ADR 0210 §3: a contribution is a dependency on the seat that receives it.
+
+func TestAContributionDependsOnTheSeatThatPlacesIt(t *testing.T) {
+	env := mod("theme", nil, nil, nil)
+	env.Environment = &Environment{Variables: map[string]string{"GTK_THEME": "Adwaita:dark"}}
+	path := mod("toolchain", nil, nil, nil)
+	path.Environment = &Environment{Path: []PathEntry{{Entry: "/opt/x/bin"}}}
+	shell := mod("prompt", nil, nil, nil)
+	shell.Shell = []ShellCode{{For: "zsh", Slot: "first", Code: "true"}}
+	session := mod("wallpaper", nil, nil, nil)
+	session.Shell = []ShellCode{{For: "xinitrc", Slot: "normal", Code: "true"}}
+	resources := mod("bar", nil, nil, nil)
+	resources.Shell = []ShellCode{{For: "xresources", Slot: "normal", Code: "x: y"}}
+	empty := mod("nothing", nil, nil, nil)
+	empty.Environment = &Environment{}
+
+	cases := map[string]struct {
+		m    Manifest
+		want []string
+	}{
+		"a variable":                {env, []string{EnvironmentSeat}},
+		"a path entry":              {path, []string{EnvironmentSeat}},
+		"shell code":                {shell, []string{LoginShellSeat}},
+		"the session's start":       {session, []string{DisplayServerSeat}},
+		"the session's X resources": {resources, []string{DisplayServerSeat}},
+		"an empty environment":      {empty, nil},
+	}
+	for name, c := range cases {
+		got := DependsOn(nil, c.m)
+		if len(got) == 0 {
+			got = nil
+		}
+		if !reflect.DeepEqual(got, c.want) {
+			t.Errorf("%s depends on %v, want %v", name, got, c.want)
+		}
+	}
+}
+
+func TestAContributionIsMetByAHolderOnTheNodeAndRefusedWithout(t *testing.T) {
+	holder := mod("node-env", nil, nil, nil, Claim{Name: EnvironmentSeat})
+	contributor := mod("theme", nil, nil, nil)
+	contributor.Environment = &Environment{Variables: map[string]string{"GTK_THEME": "Adwaita:dark"}}
+	catalogue := map[string]Manifest{"node-env": holder, "theme": contributor}
+
+	if _, err := AssignRefusal(catalogue, "laptop", []string{"node-env"}, []string{"theme"}); err != nil {
+		t.Fatalf("a contributor beside the holder is refused: %v", err)
+	}
+	_, err := AssignRefusal(catalogue, "laptop", nil, []string{"theme"})
+	if err == nil {
+		t.Fatal("a contributor on a node without the holder was accepted, and its contribution would be written nowhere")
+	}
+	if !strings.Contains(err.Error(), EnvironmentSeat) || !strings.Contains(err.Error(), "node-env") {
+		t.Errorf("the refusal names neither the seat nor its holder: %v", err)
+	}
+	if _, err := AssignRefusal(catalogue, "laptop", nil, []string{"theme", "node-env"}); err != nil {
+		t.Errorf("the contributor and the holder assigned together are refused: %v", err)
+	}
+}
+
+func TestAHolderMeetsItsOwnContribution(t *testing.T) {
+	// The display server's module contributes nothing to its own seat today, but the zsh module's
+	// environment contributions do go to another seat: a claim meets only the seat it names.
+	zsh := mod("zsh", nil, nil, nil, Claim{Name: LoginShellSeat})
+	zsh.Shell = []ShellCode{{For: "zsh", Slot: "normal", Code: "true"}}
+	zsh.Environment = &Environment{Variables: map[string]string{"EDITOR": "vim"}}
+	catalogue := map[string]Manifest{"zsh": zsh,
+		"node-env": mod("node-env", nil, nil, nil, Claim{Name: EnvironmentSeat})}
+	unheld := UnheldDependencies(catalogue, "laptop", []Manifest{zsh}, nil)
+	if len(unheld) != 1 || unheld[0].Seat != EnvironmentSeat {
+		t.Errorf("zsh alone: unheld %v, want only %s (its shell code is its own seat's)", unheld, EnvironmentSeat)
+	}
+}
+
+func TestTwoModulesMayDeclareOnePackage(t *testing.T) {
+	pacman := withResources(mod("pacman", nil, nil, nil, Claim{Name: PackageManagerSeat}),
+		res("package", "pacman-contrib"))
+	bar := withResources(mod("bar", nil, nil, nil), res("package", "bar"), res("package", "pacman-contrib"))
+	catalogue := map[string]Manifest{"pacman": pacman, "bar": bar}
+	if err := CollisionRefusal(catalogue, "laptop", []string{"pacman"}, []string{"bar"}); err != nil {
+		t.Fatalf("a second declaration of a package was refused (novox/hq ADR 0303): %v", err)
+	}
+}
+
+func TestAPackageDeclaredPresentAndAbsentIsRefusedNamingBoth(t *testing.T) {
+	gone := res("package", "ufw")
+	gone["absent"] = true
+	filter := withResources(mod("nftables", nil, nil, nil), gone)
+	wants := withResources(mod("legacy", nil, nil, nil), res("package", "ufw"))
+	other := withResources(mod("other", nil, nil, nil), res("package", "other"))
+	catalogue := map[string]Manifest{"nftables": filter, "legacy": wants, "other": other}
+
+	err := CollisionRefusal(catalogue, "laptop", []string{"nftables"}, []string{"legacy"})
+	if err == nil || !strings.Contains(err.Error(), "ufw") || !strings.Contains(err.Error(), "nftables") ||
+		!strings.Contains(err.Error(), "legacy") || !strings.Contains(err.Error(), "ADR 0303") {
+		t.Fatalf("a package declared present and absent was not refused naming both: %v", err)
+	}
+	if strings.Contains(err.Error(), "one owner per node") {
+		t.Errorf("the refusal gives the one-owner rule, which no longer holds for packages: %v", err)
+	}
+	if err := CollisionRefusal(catalogue, "laptop", []string{"nftables"}, []string{"other"}); err != nil {
+		t.Errorf("a module declaring nothing contradictory is refused: %v", err)
+	}
+	// A contradiction already on the node is status's, not a reason to refuse an unrelated assignment.
+	if err := CollisionRefusal(catalogue, "laptop", []string{"nftables", "legacy"}, []string{"other"}); err != nil {
+		t.Errorf("an unrelated assignment is refused for a contradiction already there: %v", err)
+	}
+}
+
+func TestCodeForAPowerMomentDependsOnThePowerSeat(t *testing.T) {
+	for _, moment := range powerMoments {
+		m := mod("laptop", nil, nil, nil)
+		m.Shell = []ShellCode{{For: moment, Slot: "normal", Code: "true"}}
+		if got := DependsOn(nil, m); !reflect.DeepEqual(got, []string{PowerSeat}) {
+			t.Errorf("code for %s depends on %v, want %s", moment, got, PowerSeat)
+		}
+		if p := m.shellProblems(); len(p) != 0 {
+			t.Errorf("code for %s is refused: %v", moment, p)
+		}
+	}
+	m := mod("laptop", nil, nil, nil)
+	m.Shell = []ShellCode{{For: "after-lunch", Slot: "normal", Code: "true"}}
+	if p := m.shellProblems(); len(p) == 0 {
+		t.Error("code for a moment that does not exist was accepted")
+	}
+	if s, ok := SeatNamed(PowerSeat); !ok || s.Scope != ScopeNode {
+		t.Errorf("%s is not a node seat of the mesh's own: %+v %v", PowerSeat, s, ok)
+	}
+}

go/catalogue/core_credentials.go

@@ -0,0 +1,33 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"slices"
+)
+
+// The core's own credentials (novox/hq ADR 0349 §16, issue 755). The bus, the node-engine, the controller and
+// mesh-provisioner need their files before any provisioner client runs, so their files stay placement and their
+// credentials travel in the declaration as values the vault sealed to the machine they run on, which the controller
+// carries and cannot open; the node-engine opens them there (mesh-host's VaultBoxContract).
+
+// CoreCredentialModules are the modules whose own secrets are the core's credentials: the bus, mesh-provisioner and
+// its client. The node-engine and the controller hold no own secret of a module's. **Fixed here, in the controller's
+// code, as the clause says** — and the vault keeps the same list (mesh-vault's CoreModules), answering the controller
+// for these alone.
+var CoreCredentialModules = []string{"mesh-provisioner", "mesh-provisioner-client", "nats"}
+
+// CarriesVaultSealed says whether module's own secrets are the core's credentials.
+func CarriesVaultSealed(module string) bool { return slices.Contains(CoreCredentialModules, module) }
+
+// VaultSealedField is the field of a file the vault sealed to its machine (mesh-host's File.VaultSealed).
+const VaultSealedField = "vault-sealed"
+
+// ForeseenVaultBox stands for a core credential's box in a composition asked ahead of the send, when none is kept
+// yet: the send asks the vault for it. Never sent.
+var ForeseenVaultBox = json.RawMessage(`{"v":1,"eph":"","iv":"","tag":"","ct":"","foreseen":"asked of the vault by the next send"}`)
+
+// vaultSealedOf is the vault's box for one of module's own secrets, if the rendering was given one.
+func (with Rendering) vaultSealedOf(module, name string) (json.RawMessage, bool) {
+	box, ok := with.VaultSealed[module][name]
+	return box, ok && len(box) > 0
+}

go/catalogue/core_credentials_test.go

@@ -0,0 +1,107 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// The core's own credentials travel sealed by the vault to their machine (novox/hq ADR 0349 §16, issue 755): the
+// controller carries the vault's box and cannot open it. The list is fixed here, and the composition carries the box
+// in place of the controller's own sealed value only where the rendering was given one.
+
+func TestTheCoresOwnCredentialsAreTheBusTheProvisionerAndItsClient(t *testing.T) {
+	if want := []string{"mesh-provisioner", "mesh-provisioner-client", "nats"}; !reflect.DeepEqual(CoreCredentialModules, want) {
+		t.Fatalf("the core's modules are %v, want %v (mesh-vault's CoreModules is the same list)", CoreCredentialModules, want)
+	}
+	for _, m := range []string{"nats", "mesh-provisioner", "mesh-provisioner-client"} {
+		if !CarriesVaultSealed(m) {
+			t.Errorf("%s is not on the list", m)
+		}
+	}
+	for _, m := range []string{"postgres", "mesh-vault", "mesh-controller", ""} {
+		if CarriesVaultSealed(m) {
+			t.Errorf("%s is on the list", m)
+		}
+	}
+}
+
+const provisionerClient = `{"module":"mesh-provisioner-client","version":"1",
+  "own-secrets":{"provisioner-broker":"${dir:state}/broker"},
+  "resources":[{"id":"state","type":"directory","mode":"0700","place":"."}]}`
+
+func clientOn(t *testing.T) Resolution {
+	t.Helper()
+	m, err := ParseManifest([]byte(provisionerClient))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return notifierOn(t, m)
+}
+
+func brokerFile(t *testing.T, c Composed) map[string]any {
+	t.Helper()
+	for _, r := range c.Resources {
+		if r["id"] == "mesh-provisioner-client.needs-provisioner-broker" {
+			return r
+		}
+	}
+	return nil
+}
+
+var aVaultBox = json.RawMessage(`{"v":1,"eph":"ZQ==","iv":"aQ==","tag":"dA==","ct":"Yw=="}`)
+
+func TestACoreCredentialCarriesTheVaultsBoxAndNoSealOfTheControllers(t *testing.T) {
+	r := clientOn(t)
+	with := Rendering{Needed: map[string]map[string]string{"mesh-provisioner-client": {"provisioner-broker": "nacl"}},
+		VaultSealed: map[string]map[string]json.RawMessage{"mesh-provisioner-client": {"provisioner-broker": aVaultBox}}}
+	c, got := composeWith(t, r, with)
+	f := brokerFile(t, c)
+	if f == nil {
+		t.Fatalf("the credential's file is not declared: %s", got)
+	}
+	if f["sealed"] != nil || !reflect.DeepEqual(f["vault-sealed"], aVaultBox) || strings.Contains(got, `"nacl"`) {
+		t.Fatalf("the file is %v: the vault's box alone, never the controller's seal", f)
+	}
+	// Without the controller's own value at all: the vault's box is enough.
+	with.Needed = nil
+	if c, _ := composeWith(t, r, with); brokerFile(t, c) == nil {
+		t.Fatal("a core credential with the vault's box and no seal of the controller's was refused or dropped")
+	}
+}
+
+func TestACoreModuleTheVaultGaveNothingForIsLeftOutWithWhy(t *testing.T) {
+	r := clientOn(t)
+	c, got := composeWith(t, r, Rendering{NotPlaced: map[string]string{
+		"mesh-provisioner-client": "the vault did not answer for its credential"}})
+	if brokerFile(t, c) != nil || strings.Contains(got, "mesh-provisioner-client.") {
+		t.Fatalf("a core module the vault gave nothing for was placed: %s", got)
+	}
+	if !strings.Contains(c.LeftOut["mesh-provisioner-client"], "the vault did not answer") {
+		t.Fatalf("left out %v", c.LeftOut)
+	}
+}
+
+// An engine below VaultBoxContract is rendered with neither field: its composition is the controller's sealed value,
+// byte for byte what it was.
+func TestWithoutTheVaultsBoxTheCompositionIsAsBefore(t *testing.T) {
+	r := clientOn(t)
+	with := Rendering{Needed: map[string]map[string]string{"mesh-provisioner-client": {"provisioner-broker": "nacl"}}}
+	before, _ := composeWith(t, r, with)
+	with.VaultSealed, with.NotPlaced = map[string]map[string]json.RawMessage{}, map[string]string{}
+	after, _ := composeWith(t, r, with)
+	if !reflect.DeepEqual(before, after) || brokerFile(t, before)["sealed"] != "nacl" {
+		t.Fatalf("the composition changed: %v", brokerFile(t, after))
+	}
+}
+
+// Asked ahead of a send that has no box kept yet: a stand-in, named as foreseen, never sent.
+func TestAForeseenVaultBoxIsNamed(t *testing.T) {
+	r := clientOn(t)
+	c, _ := composeWith(t, r, Rendering{VaultSealed: map[string]map[string]json.RawMessage{
+		"mesh-provisioner-client": {"provisioner-broker": ForeseenVaultBox}}})
+	if !reflect.DeepEqual(c.Foreseen, []string{"mesh-provisioner-client/provisioner-broker"}) {
+		t.Fatalf("foreseen %v", c.Foreseen)
+	}
+}

go/catalogue/cron.go

@@ -0,0 +1,92 @@
+package catalogue
+
+// A five-field cron validator, enough to refuse a malformed schedule near its author
+// (novox/hq ADR 0053).
+//
+// **Validation only, and written rather than pulled in.** The control plane's part in a scheduled
+// step is small and exact: carry the field to the host unchanged, and refuse a `schedule` that is
+// not a well-formed cron here rather than on the machine — the same near-versus-far discipline the
+// manifest keeps for an action a module may not declare and a run-once that is not a boolean. What
+// *when to run it again* means is the host's to evaluate; the control plane only checks the string
+// is one it could. A cron library would be a dependency carried for evaluation nobody does here.
+//
+// The ordinary five fields — minute, hour, day-of-month, month, day-of-week — with `*`, lists
+// (`,`), ranges (`-`) and steps (`/`). No names (jan, mon): a numeric cron is what the host
+// evaluates, and refusing a name here is refusing it near whoever wrote it.
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+)
+
+// validateCron reports why a string is not a five-field cron expression, or nil if it is one.
+func validateCron(expr string) error {
+	fields := strings.Fields(expr)
+	if len(fields) != 5 {
+		return fmt.Errorf(
+			"a schedule is a five-field cron expression (minute hour day-of-month month "+
+				"day-of-week), and this has %d field(s)", len(fields))
+	}
+	bounds := []struct {
+		name     string
+		min, max int
+	}{
+		{"minute", 0, 59},
+		{"hour", 0, 23},
+		{"day-of-month", 1, 31},
+		{"month", 1, 12},
+		{"day-of-week", 0, 7}, // 0 and 7 are both Sunday, the convention every cron keeps
+	}
+	for i, b := range bounds {
+		if err := validateCronField(fields[i], b.min, b.max); err != nil {
+			return fmt.Errorf("%s field: %w", b.name, err)
+		}
+	}
+	return nil
+}
+
+// validateCronField checks one field's elements are within range and well-formed.
+func validateCronField(spec string, min, max int) error {
+	if spec == "" {
+		return fmt.Errorf("is empty")
+	}
+	for _, part := range strings.Split(spec, ",") {
+		if part == "" {
+			return fmt.Errorf("%q has an empty element between commas", spec)
+		}
+
+		rangePart := part
+		if slash := strings.IndexByte(part, '/'); slash >= 0 {
+			rangePart = part[:slash]
+			n, err := strconv.Atoi(part[slash+1:])
+			if err != nil || n < 1 {
+				return fmt.Errorf("step in %q is not a positive number", part)
+			}
+		}
+
+		switch {
+		case rangePart == "*":
+			// Any value; nothing to bound.
+		case strings.IndexByte(rangePart, '-') >= 0:
+			dash := strings.IndexByte(rangePart, '-')
+			lo, errLo := strconv.Atoi(rangePart[:dash])
+			hi, errHi := strconv.Atoi(rangePart[dash+1:])
+			if errLo != nil || errHi != nil {
+				return fmt.Errorf("range %q is not two numbers", rangePart)
+			}
+			if lo < min || hi > max || lo > hi {
+				return fmt.Errorf("range %q is outside the allowed %d-%d", part, min, max)
+			}
+		default:
+			v, err := strconv.Atoi(rangePart)
+			if err != nil {
+				return fmt.Errorf("%q is not a number", rangePart)
+			}
+			if v < min || v > max {
+				return fmt.Errorf("%q is outside the allowed range %d-%d", part, min, max)
+			}
+		}
+	}
+	return nil
+}

go/catalogue/data.go

@@ -0,0 +1,791 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// A module declares the data it holds, and the mesh protects and watches it from that declaration
+// (novox/hq ADR 0233).
+//
+// **One section, `data`, for every kind of data a module keeps:** its own, by directory — a store's
+// files, a mail spool, an application's uploads — or by an operator's path it was given; what it keeps
+// for its consumers, by the provision they reach it through; and what of its own lives with a
+// provider, by the provision it requires. Each entry has a class — how precious it is — and, for its
+// own data, how it is protected; everything the mesh does is derived from those, never written per
+// module:
+//
+//   - a binding to a consumer's data does not move (ADR 0232) where the provision's class keeps data;
+//   - the backup holder's lines are composed from it — a module no longer writes them by hand;
+//   - what an unassignment leaves behind of an irreplaceable or valuable item is retired, listed by
+//     `cleanup list` and deleted only by `cleanup delete` (ADR 0230);
+//   - the self-check measures every item and says when one shrinks, disappears, stops being written,
+//     goes without its backup, sits on a degraded array, or is replaced by an empty copy of itself —
+//     urgent for what is irreplaceable, a warning for what is valuable.
+
+// The classes: how precious the data is. A fixed vocabulary, ranked by the operator (2026-10-06): a
+// class is what the protections are derived from, so a new one is a decision, not a manifest's choice.
+const (
+	// ClassIrreplaceable is what must never be lost: the operator names it (the media library, the
+	// photo sites' storage). Protected by a backup or by a declared redundancy — one is required —
+	// retired rather than removed, and every alert about it is urgent.
+	ClassIrreplaceable = "irreplaceable"
+	// ClassValuable is anybody's work that would be painful to lose: in the nightly backup by default,
+	// retired rather than removed, and every alert about it a warning.
+	ClassValuable = "valuable"
+	// ClassRebuildable can be made again from something kept elsewhere — a clone, an index, a
+	// download, a night's dump — at a cost in time, not in data. In the nightly backup by default;
+	// forgotten when its module goes, and never alerted on.
+	ClassRebuildable = "rebuildable"
+	// ClassCache may be emptied at any moment with nothing lost but speed: never backed up, never
+	// measured, never alerted on.
+	ClassCache = "cache"
+	// ClassNone is a provision that keeps nothing of its consumers' (consumers only): a resolver, a
+	// certificate authority, an artifact store.
+	ClassNone = "none"
+)
+
+// classRank orders the classes by how precious they are, so the stricter of two is chosen.
+var classRank = map[string]int{ClassNone: 0, ClassCache: 1, ClassRebuildable: 2, ClassValuable: 3, ClassIrreplaceable: 4}
+
+// StricterClass is the more precious of two classes.
+func StricterClass(a, b string) string {
+	if classRank[b] > classRank[a] {
+		return b
+	}
+	return a
+}
+
+// Retires is whether a class's data is retired, not forgotten, when its machine no longer declares it.
+func Retires(class string) bool { return class == ClassIrreplaceable || class == ClassValuable }
+
+// Watched is whether a class's data raises conditions: irreplaceable and valuable.
+func Watched(class string) bool { return Retires(class) }
+
+// DefaultBackupWithin is how old the last good backup of an item may be before the self-check says so
+// (novox/hq ADR 0214: a machine with data and no good backup in 48 hours).
+const DefaultBackupWithin = 48 * time.Hour
+
+// Data is a manifest's `data` section.
+type Data struct {
+	// Own is the data this module keeps itself.
+	Own []DataItem `json:"own,omitempty"`
+	// Consumers is what it keeps for its consumers, per provision it grants.
+	Consumers map[string]ConsumerData `json:"consumers,omitempty"`
+	// KeptBy is what of its own lives with the provider of a provision it requires — its rows, its
+	// objects — and how precious that is. The provider's protections follow the stricter of its own
+	// class for its consumers and this.
+	KeptBy map[string]KeptData `json:"kept-by,omitempty"`
+}
+
+// DataItem is one piece of a module's own data.
+type DataItem struct {
+	// ID names it within the module: what `data`, `cleanup` and a condition call it.
+	ID string `json:"id"`
+	// Path is one of the module's directories, `${dir:<id>}`, or an operator's path it was given,
+	// `${access:<id>}`, or a path beneath either. Never a machine path (novox/hq ADR 0112).
+	Path  string `json:"path"`
+	Class string `json:"class"`
+	// Backup is how it is copied: "copy" (the holder reads it as it stands), "none", or a dump — a
+	// command that writes a consistent copy into another item, which is copied. Unsaid, anything but a
+	// cache is copied, unless it says it is protected by redundancy instead.
+	Backup *DataBackup `json:"backup,omitempty"`
+	// Redundancy says it is protected by the redundancy of the storage it lives on rather than by a
+	// copy, and why that is enough: the media library on an array there is no room to copy. The
+	// backup holder then watches that array, and a degraded one is said.
+	Redundancy string `json:"redundancy,omitempty"`
+	// Within is how old its last good backup may be; unsaid, DefaultBackupWithin.
+	Within string `json:"within,omitempty"`
+	// Measure is how the backup holder measures it: `walk` (the default — every file, at most daily and
+	// bounded, for small items), `dataset` (a ZFS dataset's own counters, hourly, nothing walked) or
+	// `shallow` (its top-level entries only, no size). A large item never says walk.
+	Measure string `json:"measure,omitempty"`
+	// Active is how long it may go unwritten before that is a fault — for data something is
+	// expected to write all the time. Unsaid, a quiet item is not a fault.
+	Active string `json:"active,omitempty"`
+	// Why is a line for the reviewer: why this class.
+	Why string `json:"why,omitempty"`
+}
+
+// ConsumerData is what a provider keeps for the consumers of one provision.
+type ConsumerData struct {
+	Class string `json:"class"`
+	// In is where it lives: one of the module's own items (whose protection covers it), or a
+	// provision this module requires (whose provider keeps it, as its consumer). Unsaid only for none
+	// and cache.
+	In  string `json:"in,omitempty"`
+	Why string `json:"why,omitempty"`
+}
+
+// KeptData is how precious what a module keeps with a provider is.
+type KeptData struct {
+	Class string `json:"class"`
+	Why   string `json:"why,omitempty"`
+}
+
+// DataBackup is how an item is copied.
+type DataBackup struct {
+	Copy bool
+	None bool
+	// Dump is the command writing a consistent copy into the item Into.
+	Dump string
+	Into string
+}
+
+// UnmarshalJSON reads "copy", "none" or {"dump": "...", "into": "<item>"}.
+func (b *DataBackup) UnmarshalJSON(raw []byte) error {
+	var word string
+	if err := json.Unmarshal(raw, &word); err == nil {
+		switch word {
+		case "copy":
+			*b = DataBackup{Copy: true}
+		case "none":
+			*b = DataBackup{None: true}
+		default:
+			return fmt.Errorf("a data item's backup is \"copy\", \"none\" or {dump, into}, not %q", word)
+		}
+		return nil
+	}
+	var full struct {
+		Dump string `json:"dump"`
+		Into string `json:"into"`
+	}
+	dec := json.NewDecoder(bytes.NewReader(raw))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&full); err != nil {
+		return fmt.Errorf("a data item's backup is \"copy\", \"none\" or {dump, into}: %w", typedUnknown(err))
+	}
+	*b = DataBackup{Dump: full.Dump, Into: full.Into}
+	return nil
+}
+
+// MarshalJSON writes it back in the form it was written.
+func (b DataBackup) MarshalJSON() ([]byte, error) {
+	switch {
+	case b.Copy:
+		return json.Marshal("copy")
+	case b.None:
+		return json.Marshal("none")
+	}
+	return json.Marshal(struct {
+		Dump string `json:"dump"`
+		Into string `json:"into"`
+	}{b.Dump, b.Into})
+}
+
+// IsDump is whether the item is copied by a dump.
+func (b *DataBackup) IsDump() bool { return b != nil && b.Dump != "" }
+
+// BackedUp is whether the holder keeps restore points of this item: anything but a cache by default —
+// the nightly backup is the standard plan — unless it says "none", or says it is protected by
+// redundancy and says nothing of a backup.
+func (it DataItem) BackedUp() bool {
+	switch {
+	case it.Backup == nil:
+		return it.Class != ClassCache && it.Redundancy == ""
+	case it.Backup.None:
+		return false
+	}
+	return true
+}
+
+// Protection is how the item is protected, in one word: "backup", "redundancy", both joined by "+",
+// or "none".
+func (it DataItem) Protection() string {
+	var by []string
+	if it.BackedUp() {
+		by = append(by, "backup")
+	}
+	if it.Redundancy != "" {
+		by = append(by, "redundancy")
+	}
+	if len(by) == 0 {
+		return "none"
+	}
+	return strings.Join(by, "+")
+}
+
+// The ways an item is measured.
+const (
+	MeasureWalk    = "walk"
+	MeasureDataset = "dataset"
+	MeasureShallow = "shallow"
+)
+
+// MeasuredBy is how the item is measured, with the default applied.
+func (it DataItem) MeasuredBy() string {
+	if it.Measure == "" {
+		return MeasureWalk
+	}
+	return it.Measure
+}
+
+// OwnedByModule is whether the item is in one of the module's own directories — the mesh's to retire —
+// rather than an operator's path it was given, which the mesh never retires and never deletes.
+func (it DataItem) OwnedByModule() bool { return strings.HasPrefix(it.Path, "${dir:") }
+
+// BackupWithin is the item's bound on its last good backup.
+func (it DataItem) BackupWithin() time.Duration {
+	if d, err := ParseDataDuration(it.Within); err == nil && d > 0 {
+		return d
+	}
+	return DefaultBackupWithin
+}
+
+// ActiveWithin is how long the item may go unwritten; zero when quiet is not a fault.
+func (it DataItem) ActiveWithin() time.Duration {
+	d, _ := ParseDataDuration(it.Active)
+	return d
+}
+
+// ParseDataDuration reads "48h", "90m" or "7d"; empty is zero.
+func ParseDataDuration(s string) (time.Duration, error) {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return 0, nil
+	}
+	if days, ok := strings.CutSuffix(s, "d"); ok {
+		n, err := strconv.Atoi(days)
+		if err != nil || n <= 0 {
+			return 0, fmt.Errorf("%q is not a number of days", s)
+		}
+		return time.Duration(n) * 24 * time.Hour, nil
+	}
+	d, err := time.ParseDuration(s)
+	if err != nil || d <= 0 {
+		return 0, fmt.Errorf("%q is not a duration (48h, 90m, 7d)", s)
+	}
+	return d, nil
+}
+
+// DataItems is the module's own data, in the order declared.
+func (m Manifest) DataItems() []DataItem {
+	if m.Data == nil {
+		return nil
+	}
+	return m.Data.Own
+}
+
+// DataItem is one own item by id.
+func (m Manifest) DataItem(id string) (DataItem, bool) {
+	for _, it := range m.DataItems() {
+		if it.ID == id {
+			return it, true
+		}
+	}
+	return DataItem{}, false
+}
+
+// ConsumerDataOf is what this module says it keeps for a provision's consumers, and whether it says.
+func (m Manifest) ConsumerDataOf(provision string) (ConsumerData, bool) {
+	if m.Data == nil {
+		return ConsumerData{}, false
+	}
+	c, ok := m.Data.Consumers[provision]
+	return c, ok
+}
+
+// KeptByOf is how precious what this module keeps with a provision's provider is, and whether it says.
+func (m Manifest) KeptByOf(provision string) (KeptData, bool) {
+	if m.Data == nil {
+		return KeptData{}, false
+	}
+	k, ok := m.Data.KeptBy[provision]
+	return k, ok
+}
+
+// keepsByClass is whether a class keeps something a binding must not move away from.
+func keepsByClass(class string) bool {
+	return class == ClassIrreplaceable || class == ClassValuable || class == ClassRebuildable
+}
+
+// dataID is what an item's id may be: it is a token in a condition's key and a word on a line.
+var dataID = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+
+// dataPathRef is an item's path: one of the module's directories or accesses, and optionally a path
+// beneath it.
+var dataPathRef = regexp.MustCompile(`^\$\{(dir|access):([a-z0-9][a-z0-9-]*)\}(/[^\s$]*)?$`)
+
+// dataProblems is what is wrong with the `data` section itself, from the manifest alone: judged at
+// registration as every other per-manifest problem is. Whether a module declares what it should is
+// the catalogue check's (DataProblems), because a module already running was written before it.
+func (m Manifest) dataProblems() []string {
+	if m.Data == nil {
+		return nil
+	}
+	var problems []string
+	say := func(format string, args ...any) {
+		problems = append(problems, fmt.Sprintf("%s's data: ", m.Module)+fmt.Sprintf(format, args...))
+	}
+	dirs := map[string]bool{}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "directory" {
+			dirs[fmt.Sprint(r["id"])] = true
+		}
+	}
+	accesses := map[string]bool{}
+	for _, a := range m.Accesses {
+		if a.ID != "" {
+			accesses[a.ID] = true
+		}
+	}
+	ids := map[string]DataItem{}
+	paths := map[string]string{}
+	for i, it := range m.Data.Own {
+		label := it.ID
+		if label == "" {
+			label = fmt.Sprintf("item %d", i+1)
+		}
+		if !dataID.MatchString(it.ID) {
+			say("%s has no usable id: lower-case letters, digits and dashes", label)
+		} else if _, twice := ids[it.ID]; twice {
+			say("%s is declared twice", it.ID)
+		}
+		ids[it.ID] = it
+		ref := dataPathRef.FindStringSubmatch(it.Path)
+		switch {
+		case ref == nil:
+			say("%s's path %q is not one of the module's directories or accesses: ${dir:<id>} or ${access:<id>}, "+
+				"or a path beneath one (a definition names no machine path, novox/hq ADR 0112)", label, it.Path)
+		case ref[1] == "dir" && !dirs[ref[2]]:
+			say("%s's path names ${dir:%s}, and %s declares no directory %q", label, ref[2], m.Module, ref[2])
+		case ref[1] == "access" && !accesses[ref[2]]:
+			say("%s's path names ${access:%s}, and %s declares no access %q", label, ref[2], m.Module, ref[2])
+		case strings.Contains(it.Path, ".."):
+			say("%s's path %q climbs out of its directory", label, it.Path)
+		}
+		if other, twice := paths[it.Path]; twice && it.Path != "" {
+			say("%s and %s name the same path %s", other, label, it.Path)
+		}
+		paths[it.Path] = label
+		switch it.Class {
+		case ClassIrreplaceable, ClassValuable, ClassRebuildable, ClassCache:
+		case ClassNone:
+			say("%s is class none, which only a provision keeping nothing of its consumers' is; own data "+
+				"that is disposable is cache", label)
+		default:
+			say("%s's class %q is not one the mesh protects by: irreplaceable, valuable, rebuildable or cache",
+				label, it.Class)
+		}
+		if it.Class == ClassIrreplaceable && !it.BackedUp() && strings.TrimSpace(it.Redundancy) == "" {
+			say("%s is irreplaceable and is neither backed up nor said to be protected by redundancy; the only "+
+				"copy of something is protected one way or the other (novox/hq ADR 0233) — copy it, dump it into "+
+				"another item, or say `redundancy` with why that is enough", label)
+		}
+		if it.Class == ClassCache && it.Backup != nil && !it.Backup.None {
+			say("%s is a cache and asks to be backed up; a cache is disposable, or it is not a cache", label)
+		}
+		if it.Class == ClassCache && it.Redundancy != "" {
+			say("%s is a cache and says it is protected by redundancy; a cache is not protected", label)
+		}
+		switch it.Measure {
+		case "", MeasureWalk, MeasureDataset, MeasureShallow:
+		default:
+			say("%s's measure %q is walk, dataset or shallow", label, it.Measure)
+		}
+		if _, err := ParseDataDuration(it.Within); err != nil {
+			say("%s's within: %v", label, err)
+		}
+		if _, err := ParseDataDuration(it.Active); err != nil {
+			say("%s's active: %v", label, err)
+		}
+		if it.Within != "" && !it.BackedUp() {
+			say("%s states within, and is not backed up", label)
+		}
+		if it.Active != "" && !Watched(it.Class) {
+			say("%s is %s and expects writes; only irreplaceable and valuable data is watched", label, it.Class)
+		}
+	}
+	// Dumps go into an item of the same module, declared, and not into themselves.
+	for _, it := range m.Data.Own {
+		if it.Backup == nil || it.Backup.Copy || it.Backup.None {
+			continue
+		}
+		switch into, ok := ids[it.Backup.Into]; {
+		case strings.TrimSpace(it.Backup.Dump) == "":
+			say("%s's backup names no dump command", it.ID)
+		case it.Backup.Into == "":
+			say("%s's dump says no item it writes into", it.ID)
+		case !ok:
+			say("%s's dump writes into %q, which is not one of the module's data items", it.ID, it.Backup.Into)
+		case into.ID == it.ID:
+			say("%s's dump writes into itself; a dump is copied from where it lands", it.ID)
+		case into.Class == ClassCache:
+			say("%s's dump writes into %s, a cache; what is copied must not be disposable", it.ID, into.ID)
+		}
+		if it.Backup.Dump != "" {
+			declared := map[string]string{}
+			for d := range dirs {
+				declared[d] = ""
+			}
+			if _, err := dirFill(it.Backup.Dump, declared, m.Module); err != nil {
+				say("%s's dump: %v", it.ID, err)
+			}
+		}
+	}
+	provided := map[string]bool{}
+	for _, o := range m.Provides {
+		provided[o.Name] = true
+	}
+	wants := map[string]bool{}
+	for _, w := range m.Wants() {
+		wants[w] = true
+	}
+	for _, provision := range sortedKeys(m.Data.Consumers) {
+		c := m.Data.Consumers[provision]
+		if !provided[provision] {
+			say("says what it keeps for the consumers of %q, which it does not provide", provision)
+		}
+		switch c.Class {
+		case ClassIrreplaceable, ClassValuable, ClassRebuildable, ClassCache, ClassNone:
+		default:
+			say("its consumers' %s is class %q; one of irreplaceable, valuable, rebuildable, cache or none", provision, c.Class)
+		}
+		switch {
+		case c.Class == ClassNone && c.In != "":
+			say("its consumers' %s keeps nothing and says where it is kept (%s)", provision, c.In)
+		case keepsByClass(c.Class) && c.In == "":
+			say("its consumers' %s is %s and says nowhere it lives: `in` names one of the module's items, or a "+
+				"provision it requires", provision, c.Class)
+		case c.In != "":
+			if own, ok := ids[c.In]; ok {
+				if c.Class == ClassIrreplaceable && !own.BackedUp() && own.Redundancy == "" {
+					say("its consumers' %s is irreplaceable and lives in %s, which is not protected", provision, c.In)
+				}
+				if classRank[own.Class] < classRank[c.Class] {
+					say("its consumers' %s is %s and lives in %s, which is only %s", provision, c.Class, c.In, own.Class)
+				}
+			} else if !wants[c.In] {
+				say("its consumers' %s lives in %q, which is neither one of its data items nor a provision it "+
+					"requires", provision, c.In)
+			}
+		}
+	}
+	for _, provision := range sortedKeys(m.Data.KeptBy) {
+		k := m.Data.KeptBy[provision]
+		if !wants[provision] {
+			say("says it keeps data with the provider of %q, which it does not require", provision)
+		}
+		switch k.Class {
+		case ClassIrreplaceable, ClassValuable, ClassRebuildable, ClassCache:
+		default:
+			say("what it keeps with %s is class %q; one of irreplaceable, valuable, rebuildable or cache", provision, k.Class)
+		}
+	}
+	return problems
+}
+
+// KeepsConsumerData is whether this module, providing a provision, keeps what each consumer writes
+// there (novox/hq ADR 0232, ADR 0233): whether a consumer bound to it is bound to its data.
+//
+// **What the data section says, it gets**: irreplaceable, valuable or rebuildable keeps; cache and none
+// do not — a cache lost in a move costs speed, not data. Before the section, an offer said it with
+// `keeps-consumer-data`, which is still read; unsaid in both, a provider that grants each consumer a
+// credential of its own keeps that consumer's data (ADR 0232 §1). The catalogue check refuses the
+// unsaid case for a provider that grants (DataProblems), so the inference is what an older definition
+// on the shelf gets, never a new one.
+func (m Manifest) KeepsConsumerData(provision string) bool {
+	if c, ok := m.ConsumerDataOf(provision); ok {
+		return keepsByClass(c.Class)
+	}
+	for _, o := range m.Provides {
+		if o.Name == provision && o.KeepsConsumerData != nil {
+			return *o.KeepsConsumerData
+		}
+	}
+	_, grants := m.Grants[provision]
+	return grants
+}
+
+// NeedsBackupHolder is whether a module's data needs the machine's backup holder to be there: it keeps
+// something irreplaceable — backed up by the holder, or protected by an array the holder watches. A
+// module keeping only valuable or rebuildable data is backed up where a holder is, and refused nowhere
+// for want of one: the standard plan, not a requirement.
+func (m Manifest) NeedsBackupHolder() bool {
+	for _, it := range m.DataItems() {
+		if it.Class == ClassIrreplaceable {
+			return true
+		}
+	}
+	return false
+}
+
+// --- derived: the backup holder's lines ---------------------------------------------------------
+
+// The node-backup seat's kinds (novox/hq to-be 43, ADR 0233): `backup` is what to run and which paths
+// to keep, `data` every item with its class and protection, for the holder to measure and watch.
+const (
+	BackupKindBackup = "backup"
+	BackupKindData   = "data"
+)
+
+// derivedContributions is what a module's data section gives the backup holder: its backup lines and
+// its items. Every item is listed, so a valuable one on a machine is measured whether or not it is
+// copied; a cache is listed and not measured.
+func (m Manifest) derivedContributions() []SeatContribution {
+	items := m.DataItems()
+	if len(items) == 0 {
+		return nil
+	}
+	var lines []string
+	kept := map[string]bool{}
+	keep := func(path string) {
+		if !kept[path] {
+			kept[path] = true
+			lines = append(lines, "path "+path)
+		}
+	}
+	for _, it := range items {
+		if !it.BackedUp() {
+			continue
+		}
+		if it.Backup.IsDump() {
+			lines = append(lines, "run "+strings.TrimSpace(it.Backup.Dump))
+			if into, ok := m.DataItem(it.Backup.Into); ok {
+				keep(into.Path)
+			}
+			continue
+		}
+		keep(it.Path)
+	}
+	var described []string
+	for _, it := range items {
+		covered := "-"
+		switch {
+		case it.Backup.IsDump():
+			if into, ok := m.DataItem(it.Backup.Into); ok {
+				covered = into.Path
+			}
+		case it.BackedUp():
+			covered = it.Path
+		}
+		described = append(described, fmt.Sprintf("item %s %s %s %s %s %s", it.ID, it.Class, it.Path, covered,
+			it.Protection(), it.MeasuredBy()))
+	}
+	var out []SeatContribution
+	if len(lines) > 0 {
+		out = append(out, SeatContribution{Seat: BackupSeat, Kind: BackupKindBackup, Content: strings.Join(lines, "\n") + "\n"})
+	}
+	return append(out, SeatContribution{Seat: BackupSeat, Kind: BackupKindData, Content: strings.Join(described, "\n") + "\n"})
+}
+
+// allContributions is every contribution a module makes to a seat's holder: what it wrote, and what
+// its data section derives. **One list**: a module that declares its data has its backup lines
+// composed from it, and a backup line it still writes by hand is not placed — the catalogue check
+// refuses it — so the holder never copies two lists that disagree.
+func (m Manifest) allContributions() []SeatContribution {
+	if m.Data == nil {
+		return m.Contributions
+	}
+	derived := m.derivedContributions()
+	out := make([]SeatContribution, 0, len(m.Contributions)+len(derived))
+	for _, c := range m.Contributions {
+		if s, known := SeatNamed(c.Seat); known && s.Name == BackupSeat {
+			continue
+		}
+		out = append(out, c)
+	}
+	return append(out, derived...)
+}
+
+// --- the catalogue check ------------------------------------------------------------------------
+
+// DataProblems is what the catalogue check refuses about the data a module declares (novox/hq ADR
+// 0233), judged over the manifests given together:
+//
+//   - a provider that grants a provision says what it keeps for that provision's consumers;
+//   - nobody says it on the offer any more (`keeps-consumer-data`): the data section is the one place;
+//   - nobody writes a backup line by hand: it is derived from the data section;
+//   - a directory a container writes, mounted whole, is a data item of some class;
+//   - consumer data said to live in a required provision lives where that provision's provider keeps
+//     its consumers' data, as preciously, when the provider is given;
+//   - data a consumer keeps with a provider as irreplaceable is protected there, when the provider is
+//     given.
+//
+// **The check's, not registration's**, as ADR 0214's backup rule was: a module already on the shelf
+// was written before the rule, and refusing it there would refuse the very providers whose data the
+// rule protects. Each module meets it where it is written.
+func DataProblems(shelf Shelf) []string {
+	var problems []string
+	for _, name := range shelfOrder(shelf) {
+		m := shelf[name]
+		for _, provision := range sortedKeys(m.Grants) {
+			if _, said := m.ConsumerDataOf(provision); !said {
+				problems = append(problems, fmt.Sprintf(
+					"%s grants %s and does not say what it keeps for its consumers: data.consumers.%s with a "+
+						"class — irreplaceable, valuable, rebuildable, cache, or none (novox/hq ADR 0233)", name, provision, provision))
+			}
+		}
+		for _, o := range m.Provides {
+			if o.KeepsConsumerData != nil {
+				problems = append(problems, fmt.Sprintf(
+					"%s says keeps-consumer-data on its offer of %s; it is said once, in data.consumers.%s, with a "+
+						"class (novox/hq ADR 0233)", name, o.Name, o.Name))
+			}
+		}
+		for i, c := range m.Contributions {
+			if s, known := SeatNamed(c.Seat); known && s.Name == BackupSeat {
+				problems = append(problems, fmt.Sprintf(
+					"%s's contribution %d is a backup line written by hand; backups are derived from the data "+
+						"section — declare the data, with its class and how it is protected (novox/hq ADR 0233)", name, i+1))
+			}
+		}
+		for _, dir := range writtenDirectories(m) {
+			if !coversDirectory(m, dir) {
+				problems = append(problems, fmt.Sprintf(
+					"%s mounts its directory %q into a container to be written, and declares no data in it: "+
+						"data.own with a class — cache if it is disposable (novox/hq ADR 0233)", name, dir))
+			}
+		}
+		if m.Data == nil {
+			continue
+		}
+		for _, provision := range sortedKeys(m.Data.Consumers) {
+			c := m.Data.Consumers[provision]
+			if c.In == "" {
+				continue
+			}
+			if _, own := m.DataItem(c.In); own {
+				continue
+			}
+			for _, pname := range shelfOrder(shelf) {
+				p := shelf[pname]
+				pc, said := p.ConsumerDataOf(c.In)
+				if !said || !providesName(p, c.In) {
+					continue
+				}
+				if classRank[pc.Class] < classRank[c.Class] {
+					problems = append(problems, fmt.Sprintf(
+						"%s keeps its consumers' %s, %s, in %s — and %s keeps its consumers' %s as %s, "+
+							"so it is not protected as %s", name, provision, c.Class, c.In, pname, c.In, pc.Class, c.Class))
+				}
+			}
+		}
+		for _, provision := range sortedKeys(m.Data.KeptBy) {
+			k := m.Data.KeptBy[provision]
+			if k.Class != ClassIrreplaceable {
+				continue
+			}
+			for _, pname := range shelfOrder(shelf) {
+				p := shelf[pname]
+				pc, said := p.ConsumerDataOf(provision)
+				if !said || !providesName(p, provision) {
+					continue
+				}
+				if !keepsByClass(pc.Class) {
+					problems = append(problems, fmt.Sprintf(
+						"%s keeps irreplaceable data with %s, and %s keeps its consumers' %s as %s — nothing of it is "+
+							"protected there", name, provision, pname, provision, pc.Class))
+					continue
+				}
+				if in, own := p.DataItem(pc.In); own && !in.BackedUp() && in.Redundancy == "" {
+					problems = append(problems, fmt.Sprintf(
+						"%s keeps irreplaceable data with %s, and %s keeps it in %s, which is neither backed up nor "+
+							"on declared redundancy", name, provision, pname, pc.In))
+				}
+			}
+		}
+	}
+	return problems
+}
+
+func providesName(m Manifest, provision string) bool {
+	for _, o := range m.Provides {
+		if o.Name == provision {
+			return true
+		}
+	}
+	return false
+}
+
+// writtenDirectories are the module's directories a container mounts whole and may write: a volume
+// `${dir:<id>}:<target>` without `:ro`, or a directory stated by an absolute path mounted the same
+// way. A file beneath a directory, or a read-only mount, is configuration the mesh wrote.
+func writtenDirectories(m Manifest) []string {
+	absolute := map[string]string{}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "directory" {
+			continue
+		}
+		if p, ok := r["path"].(string); ok && strings.HasPrefix(p, "/") {
+			absolute[strings.TrimRight(p, "/")] = fmt.Sprint(r["id"])
+		}
+	}
+	seen := map[string]bool{}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "container" {
+			continue
+		}
+		vols, _ := r["volumes"].([]any)
+		for _, v := range vols {
+			s, _ := v.(string)
+			mount := volumeMount.FindStringSubmatch(s)
+			if mount == nil || volumeReadOnly(mount[3]) {
+				continue
+			}
+			src := strings.TrimRight(mount[1], "/")
+			if ref := dirPlain.FindStringSubmatch(src); ref != nil {
+				seen[ref[1]] = true
+			} else if id, ok := absolute[src]; ok {
+				seen[id] = true
+			}
+		}
+	}
+	out := make([]string, 0, len(seen))
+	for id := range seen {
+		out = append(out, id)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// volumeMount is a container's volume, `<source>:<target>[:<options>]`, its source possibly a
+// `${dir:<id>}` — whose own colon is not the separator.
+var volumeMount = regexp.MustCompile(`^(\$\{(?:dir|access):[a-z0-9][a-z0-9-]*\}[^:]*|[^:]+):([^:]+)(?::(.*))?$`)
+
+// volumeReadOnly is whether a volume's options mount it read-only.
+func volumeReadOnly(options string) bool {
+	for _, o := range strings.Split(options, ",") {
+		if strings.TrimSpace(o) == "ro" {
+			return true
+		}
+	}
+	return false
+}
+
+// dirPlain is a whole directory, `${dir:<id>}` and nothing after it.
+var dirPlain = regexp.MustCompile(`^\$\{dir:([a-z0-9][a-z0-9-]*)\}$`)
+
+// coversDirectory is whether a data item names the directory, a path within it, or a directory it
+// is placed beneath.
+func coversDirectory(m Manifest, dir string) bool {
+	parents := map[string]string{}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "directory" {
+			continue
+		}
+		if p, ok := r["path"].(string); ok {
+			if ref := dirRef.FindStringSubmatch(p); ref != nil && strings.HasPrefix(p, "${dir:") {
+				parents[fmt.Sprint(r["id"])] = ref[1]
+			}
+		}
+	}
+	for _, it := range m.DataItems() {
+		ref := dataPathRef.FindStringSubmatch(it.Path)
+		if ref == nil || ref[1] != "dir" {
+			continue
+		}
+		for d, hops := dir, 0; d != "" && hops < 4; d, hops = parents[d], hops+1 {
+			if ref[2] == d {
+				return true
+			}
+		}
+	}
+	return false
+}

go/catalogue/data_test.go

@@ -0,0 +1,227 @@
+package catalogue
+
+import (
+	"slices"
+	"strings"
+	"testing"
+)
+
+// A store as a module now declares it (novox/hq ADR 0233): its own data by directory with a class and a
+// dump, and what it keeps for its consumers.
+const declaredStore = `{"module":"pg","version":"1",
+	"provides":[{"name":"postgres-database","scope":"mesh"}],
+	"grants":{"postgres-database":"${dir:grants}"},
+	"data":{
+		"own":[
+			{"id":"store","path":"${dir:store}","class":"irreplaceable","backup":{"dump":"dump-all > ${dir:dumps}/all","into":"dumps"},"active":"1d"},
+			{"id":"dumps","path":"${dir:dumps}","class":"rebuildable","backup":"none"}],
+		"consumers":{"postgres-database":{"class":"irreplaceable","in":"store"}}},
+	"resources":[
+		{"id":"grants","type":"directory","mode":"0700"},
+		{"id":"store","type":"directory","path":"/srv/store","mode":"0700"},
+		{"id":"dumps","type":"directory","path":"${dir:store}/dumps","mode":"0700"},
+		{"id":"server","type":"container","image":"x@sha256:aa","volumes":["${dir:store}:/var/lib/postgresql/data"]}]}`
+
+func mustParse(t *testing.T, raw string) Manifest {
+	t.Helper()
+	m, err := ParseManifest([]byte(raw))
+	if err != nil {
+		t.Fatalf("refused: %v", err)
+	}
+	return m
+}
+
+func TestADeclaredStoreParsesAndPassesTheCheck(t *testing.T) {
+	m := mustParse(t, declaredStore)
+	if problems := DataProblems(Shelf{"pg": m}); len(problems) > 0 {
+		t.Fatalf("a store declaring its data was refused: %v", problems)
+	}
+	if !m.KeepsConsumerData("postgres-database") {
+		t.Fatal("an irreplaceable consumer class does not keep the consumer's data")
+	}
+	if it, _ := m.DataItem("store"); !it.BackedUp() || it.BackupWithin() != DefaultBackupWithin || it.ActiveWithin().Hours() != 24 {
+		t.Fatalf("the store item reads %+v", it)
+	}
+	if it, _ := m.DataItem("dumps"); it.BackedUp() {
+		t.Fatal("a rebuildable item that says none is backed up")
+	}
+}
+
+// Every rule of the section itself, refused at parse in the words of the module.
+func TestTheDataSectionIsRefusedWhereItIsWrong(t *testing.T) {
+	for _, c := range []struct{ name, data, want string }{
+		{"a class it does not know", `{"own":[{"id":"a","path":"${dir:d}","class":"precious"}]}`, "not one the mesh protects by"},
+		{"an access it does not have", `{"own":[{"id":"a","path":"${access:media}","class":"irreplaceable","redundancy":"an array"}]}`, "declares no access"},
+		{"irreplaceable and protected by nothing", `{"own":[{"id":"a","path":"${dir:d}","class":"irreplaceable","backup":"none"}]}`, "protected one way or the other"},
+		{"a cache on redundancy", `{"own":[{"id":"a","path":"${dir:d}","class":"cache","redundancy":"an array"}]}`, "a cache is not protected"},
+		{"kept with something not required", `{"kept-by":{"s3-bucket":{"class":"irreplaceable"}}}`, "does not require"},
+		{"a measure it does not know", `{"own":[{"id":"a","path":"${dir:d}","class":"cache","measure":"du"}]}`, "walk, dataset or shallow"},
+		{"a cache expecting writes", `{"own":[{"id":"a","path":"${dir:d}","class":"cache","active":"1d"}]}`, "only irreplaceable and valuable"},
+		{"a machine path", `{"own":[{"id":"a","path":"/srv/a","class":"cache"}]}`, "names no machine path"},
+		{"a directory it does not declare", `{"own":[{"id":"a","path":"${dir:nowhere}","class":"cache"}]}`, "declares no directory"},
+		{"a cache backed up", `{"own":[{"id":"a","path":"${dir:d}","class":"cache","backup":"copy"}]}`, "disposable"},
+		{"a dump into nothing", `{"own":[{"id":"a","path":"${dir:d}","class":"irreplaceable","backup":{"dump":"x","into":"b"}}]}`, "not one of the module's data items"},
+		{"a dump into itself", `{"own":[{"id":"a","path":"${dir:d}","class":"irreplaceable","backup":{"dump":"x","into":"a"}}]}`, "into itself"},
+		{"a bad duration", `{"own":[{"id":"a","path":"${dir:d}","class":"irreplaceable","within":"soon"}]}`, "not a duration"},
+		{"the same id twice", `{"own":[{"id":"a","path":"${dir:d}","class":"cache"},{"id":"a","path":"${dir:d}/x","class":"cache"}]}`, "declared twice"},
+		{"own data of class none", `{"own":[{"id":"a","path":"${dir:d}","class":"none"}]}`, "only a provision"},
+		{"consumers of something not provided", `{"consumers":{"s3-bucket":{"class":"cache"}}}`, "does not provide"},
+		{"consumer data that lives nowhere", `{"consumers":{"q":{"class":"irreplaceable"}}}`, "says nowhere it lives"},
+		{"consumer data in an item less precious", `{"own":[{"id":"a","path":"${dir:d}","class":"rebuildable"}],"consumers":{"q":{"class":"irreplaceable","in":"a"}}}`, "which is only rebuildable"},
+		{"consumer data in something unknown", `{"consumers":{"q":{"class":"rebuildable","in":"elsewhere"}}}`, "neither one of its data items"},
+	} {
+		raw := `{"module":"m","version":"1","provides":["q"],"resources":[{"id":"d","type":"directory","mode":"0700"}],"data":` + c.data + `}`
+		_, err := ParseManifest([]byte(raw))
+		if err == nil || !strings.Contains(err.Error(), c.want) {
+			t.Errorf("%s: %v, want %q", c.name, err, c.want)
+		}
+	}
+}
+
+// The catalogue check: a granting provider says what it keeps, says it in one place, writes no backup
+// line by hand, and every directory a container writes is declared (novox/hq ADR 0233).
+func TestTheCatalogueCheckAsksEveryModuleForItsData(t *testing.T) {
+	unsaid := mustParse(t, `{"module":"q","version":"1","provides":[{"name":"queue","scope":"mesh"}],
+		"grants":{"queue":"${dir:g}"},"resources":[{"id":"g","type":"directory","mode":"0700"}]}`)
+	onTheOffer := mustParse(t, `{"module":"r","version":"1","provides":[{"name":"resolver","scope":"mesh","keeps-consumer-data":false}]}`)
+	byHand := mustParse(t, `{"module":"h","version":"1","resources":[{"id":"d","type":"directory","mode":"0700"}],
+		"contributions":[{"seat":"node-backup","kind":"backup","content":"path ${dir:d}"}]}`)
+	writes := mustParse(t, `{"module":"w","version":"1","resources":[{"id":"d","type":"directory","mode":"0700"},
+		{"id":"c","type":"directory","mode":"0700"},
+		{"id":"app","type":"container","image":"x@sha256:aa","volumes":["${dir:d}:/data","${dir:c}:/etc/app:ro","${dir:d}/f:/f"]}]}`)
+	problems := strings.Join(DataProblems(Shelf{"q": unsaid, "r": onTheOffer, "h": byHand, "w": writes}), "\n")
+	for _, want := range []string{
+		"q grants queue and does not say what it keeps",
+		"r says keeps-consumer-data on its offer",
+		"h's contribution 1 is a backup line written by hand",
+		`w mounts its directory "d" into a container to be written`,
+	} {
+		if !strings.Contains(problems, want) {
+			t.Errorf("the check does not say %q:\n%s", want, problems)
+		}
+	}
+	if strings.Contains(problems, `"c"`) {
+		t.Errorf("a read-only mount was taken for written data:\n%s", problems)
+	}
+	// The same module declaring the directory, as a cache, passes.
+	declared := mustParse(t, `{"module":"w","version":"1","data":{"own":[{"id":"d","path":"${dir:d}","class":"cache"}]},
+		"resources":[{"id":"d","type":"directory","mode":"0700"},
+		{"id":"app","type":"container","image":"x@sha256:aa","volumes":["${dir:d}:/data"]}]}`)
+	if p := DataProblems(Shelf{"w": declared}); len(p) > 0 {
+		t.Fatalf("a declared directory is still refused: %v", p)
+	}
+}
+
+// Consumer data said to live in a provision the module requires is protected only as well as that
+// provision's provider protects its consumers' data.
+func TestConsumerDataInARequiredProvisionIsJudgedAgainstItsProvider(t *testing.T) {
+	idp := mustParse(t, `{"module":"idp","version":"1","requires":["postgres-database"],
+		"provides":[{"name":"oidc-client","scope":"mesh"}],"grants":{"oidc-client":"${dir:g}"},
+		"resources":[{"id":"g","type":"directory","mode":"0700"}],
+		"data":{"consumers":{"oidc-client":{"class":"irreplaceable","in":"postgres-database"}}}}`)
+	cachy := mustParse(t, strings.Replace(declaredStore, `"consumers":{"postgres-database":{"class":"irreplaceable","in":"store"}}`,
+		`"consumers":{"postgres-database":{"class":"cache"}}`, 1))
+	if p := strings.Join(DataProblems(Shelf{"idp": idp, "pg": cachy}), "\n"); !strings.Contains(p, "not protected as irreplaceable") {
+		t.Fatalf("irreplaceable data kept in a cache passed: %s", p)
+	}
+	if p := DataProblems(Shelf{"idp": idp, "pg": mustParse(t, declaredStore)}); len(p) > 0 {
+		t.Fatalf("refused against a provider that keeps its consumers' data: %v", p)
+	}
+}
+
+// What a binding is sticky by follows the class (ADR 0232, generalised by 0233): a cache's consumers
+// move freely, a store's do not; an older definition saying nothing still follows its grant.
+func TestKeepingConsumerDataFollowsTheClass(t *testing.T) {
+	for class, keeps := range map[string]bool{"irreplaceable": true, "valuable": true, "rebuildable": true, "cache": false, "none": false} {
+		in := `,"in":"d"`
+		own := `"own":[{"id":"d","path":"${dir:d}","class":"irreplaceable"}],`
+		if !keeps {
+			in, own = "", ""
+		}
+		m := mustParse(t, `{"module":"p","version":"1","provides":[{"name":"q","scope":"mesh"}],"grants":{"q":"${dir:d}"},
+			"resources":[{"id":"d","type":"directory","mode":"0700"}],
+			"data":{`+own+`"consumers":{"q":{"class":"`+class+`"`+in+`}}}}`)
+		if m.KeepsConsumerData("q") != keeps {
+			t.Errorf("class %s keeps consumer data: %v, want %v", class, !keeps, keeps)
+		}
+		shelf := map[string]Manifest{"p": m}
+		if KeepsConsumerData(shelf, "q") != keeps {
+			t.Errorf("class %s: the provision by name keeps: %v", class, !keeps)
+		}
+	}
+	older := mustParse(t, `{"module":"p","version":"1","provides":[{"name":"q","scope":"mesh"}],"grants":{"q":"${dir:d}"},
+		"resources":[{"id":"d","type":"directory","mode":"0700"}]}`)
+	if !older.KeepsConsumerData("q") {
+		t.Fatal("an older definition that grants no longer keeps its consumers' data")
+	}
+}
+
+// The backup holder's lines are derived: the dump runs and the directory it writes into is kept,
+// anything but a cache is copied by default — the standard nightly plan — an item on redundancy is not
+// copied, and every item is listed with its class and protection for the holder to measure and watch:
+// directories filled, a home directory filled from the machine, an operator's path from where the
+// assignment placed it. A backup line still written by hand beside a data section is not placed.
+func TestTheBackupHoldersLinesAreDerivedFromTheData(t *testing.T) {
+	pg := mustParse(t, declaredStore)
+	pg.Contributions = append(pg.Contributions, SeatContribution{Seat: BackupSeat, Kind: "backup", Content: "path /stale"})
+	agent := mustParse(t, `{"module":"agent","version":"1",
+		"data":{"own":[{"id":"home","path":"${dir:home}","class":"valuable"},{"id":"tmp","path":"${dir:home}/tmp","class":"cache"}]},
+		"resources":[{"id":"home","type":"directory","path":"${machine:account-home}/.agent","mode":"0700"}]}`)
+	media := mustParse(t, `{"module":"media","version":"1",
+		"accesses":[{"id":"films","mode":"read"}],
+		"data":{"own":[{"id":"films","path":"${access:films}","class":"irreplaceable","redundancy":"on a redundant array; no room for a copy","measure":"dataset"},
+			{"id":"meta","path":"${dir:meta}","class":"rebuildable"}]},
+		"resources":[{"id":"meta","type":"directory","mode":"0700"}]}`)
+	facts := map[string]string{"account-home": "/home/op"}
+	with := Rendering{Settings: SettingsBy{"media": {LayerOf("node", map[string]any{AccessesSetting: map[string]any{"films": "/tank/films"}})}}}
+	backup, _, err := seatContributions([]Manifest{pg, agent, media}, Manifest{}, BackupSeat+":"+BackupKindBackup, with, facts, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "# agent\npath /home/op/.agent\n# media\npath /var/lib/media/meta\n# pg\nrun dump-all > /srv/store/dumps/all\npath /srv/store/dumps\n"
+	if backup != want {
+		t.Fatalf("backup lines:\n%s\nwant:\n%s", backup, want)
+	}
+	data, _, err := seatContributions([]Manifest{pg, agent, media}, Manifest{}, BackupSeat+":"+BackupKindData, with, facts, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want = "# agent\nitem home valuable /home/op/.agent /home/op/.agent backup walk\nitem tmp cache /home/op/.agent/tmp - none walk\n" +
+		"# media\nitem films irreplaceable /tank/films - redundancy dataset\nitem meta rebuildable /var/lib/media/meta /var/lib/media/meta backup walk\n" +
+		"# pg\nitem store irreplaceable /srv/store /srv/store/dumps backup walk\nitem dumps rebuildable /srv/store/dumps - none walk\n"
+	if data != want {
+		t.Fatalf("data lines:\n%s\nwant:\n%s", data, want)
+	}
+	if _, _, err := seatContributions([]Manifest{agent}, Manifest{}, BackupSeat+":"+BackupKindData, Rendering{}, nil, nil); err == nil {
+		t.Fatal("a home directory with no account on the machine reached the holder as a placeholder")
+	}
+	// What keeps something irreplaceable depends on the machine's backup holder — it backs it up or
+	// watches its array; valuable data alone is backed up where a holder is, and refused nowhere.
+	if !slices.Contains(DependsOn(nil, media), BackupSeat) || !slices.Contains(DependsOn(nil, pg), BackupSeat) ||
+		slices.Contains(DependsOn(nil, agent), BackupSeat) {
+		t.Fatalf("depends: media %v, pg %v, agent %v", DependsOn(nil, media), DependsOn(nil, pg), DependsOn(nil, agent))
+	}
+	if it, _ := media.DataItem("films"); it.OwnedByModule() || it.Protection() != "redundancy" {
+		t.Fatalf("an operator's path reads %+v", it)
+	}
+}
+
+// Data a consumer keeps with a provider as irreplaceable must be protected there: the check refuses a
+// provider that keeps its consumers' data as a cache, or in an item with no protection.
+func TestIrreplaceableDataKeptWithAProviderMustBeProtectedThere(t *testing.T) {
+	photos := mustParse(t, `{"module":"photos","version":"1","requires":["s3-bucket"],
+		"data":{"kept-by":{"s3-bucket":{"class":"irreplaceable"}}}}`)
+	store := func(backup string) Manifest {
+		return mustParse(t, `{"module":"objects","version":"1","provides":[{"name":"s3-bucket","scope":"mesh"}],
+			"grants":{"s3-bucket":"${dir:g}"},
+			"data":{"own":[{"id":"data","path":"${dir:data}","class":"valuable","backup":"`+backup+`"}],
+				"consumers":{"s3-bucket":{"class":"valuable","in":"data"}}},
+			"resources":[{"id":"g","type":"directory","mode":"0700"},{"id":"data","type":"directory","mode":"0700"}]}`)
+	}
+	if p := DataProblems(Shelf{"photos": photos, "objects": store("copy")}); len(p) > 0 {
+		t.Fatalf("a provider backing its consumers' data up was refused: %v", p)
+	}
+	if p := strings.Join(DataProblems(Shelf{"photos": photos, "objects": store("none")}), "\n"); !strings.Contains(p, "neither backed up") {
+		t.Fatalf("irreplaceable photos in an unprotected store passed: %s", p)
+	}
+}

go/catalogue/declaration_test.go

@@ -0,0 +1,80 @@
+package catalogue
+
+import "testing"
+
+// The mesh's user list reaches the module holding the bus, and nothing else.
+//
+// Three refusals and one delivery, because each of the refusals would be silent in a different way:
+// a module that asked and was given it could read every credential on the bus; a bus given an empty
+// file refuses every connection in the mesh and looks like a machine problem; and a bus that never
+// asked gets nothing rather than a file it does not read.
+func TestTheMeshsUserListGoesOnlyToTheModuleHoldingTheBus(t *testing.T) {
+	theBus := func() Manifest {
+		return Manifest{
+			Module: "nats", Version: "1",
+			Claims:    []Claim{{Name: "mesh-broker", Scope: ScopeMesh}},
+			BusUsers:  "/var/lib/nats-module/conf/accounts.conf",
+			Resources: []map[string]any{},
+		}
+	}
+
+	on := func(t *testing.T, m Manifest, with Rendering) ([]map[string]any, error) {
+		t.Helper()
+		return Resolution{Node: "anchor", Modules: []Manifest{m}}.Declaration(with)
+	}
+
+	t.Run("the holder is given it", func(t *testing.T) {
+		resources, err := on(t, theBus(), Rendering{BusUsers: "accounts { MESH { users = [] } }"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		// Prefixed with the module it came from, like every resource: two modules may reasonably
+		// both call something "config", and without the prefix the second would silently replace
+		// the first.
+		var found map[string]any
+		for _, r := range resources {
+			if r["id"] == "nats."+BusUsersID() {
+				found = r
+			}
+		}
+		if found == nil {
+			t.Fatalf("the bus was given no user list: %+v", resources)
+		}
+		if found["path"] != "/var/lib/nats-module/conf/accounts.conf" {
+			t.Errorf("written to %v rather than where the module asked", found["path"])
+		}
+		if found["mode"] != "0600" {
+			t.Errorf("mode %v: a list of every user in the mesh belongs to the one process that "+
+				"needs it", found["mode"])
+		}
+	})
+
+	t.Run("a module that does not claim the seat is refused", func(t *testing.T) {
+		m := theBus()
+		m.Claims = nil
+		if _, err := on(t, m, Rendering{BusUsers: "accounts {}"}); err == nil {
+			t.Fatal("a module that claims nothing was handed every user's password hash")
+		}
+	})
+
+	t.Run("the holder with nothing composed is refused", func(t *testing.T) {
+		if _, err := on(t, theBus(), Rendering{}); err == nil {
+			t.Fatal("the bus was given an empty user list, so it would refuse every connection in " +
+				"the mesh and look like a machine problem")
+		}
+	})
+
+	t.Run("a module that did not ask gets nothing", func(t *testing.T) {
+		m := theBus()
+		m.BusUsers = ""
+		resources, err := on(t, m, Rendering{BusUsers: "accounts {}"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		for _, r := range resources {
+			if r["id"] == "nats."+BusUsersID() {
+				t.Fatal("a module that asked for no user list was given one")
+			}
+		}
+	})
+}

go/catalogue/delivery_seat.go

@@ -0,0 +1,140 @@
+package catalogue
+
+// The delivery's owner (novox/hq ADR 0239, to-be 47): one holder for the mesh, the module mesh-delivery,
+// which owns a delivery — one commit in one repository, from its pull request's head to every machine —
+// and a delivery group, and asks the controller for every act. A seat of the mesh's own, so the role has
+// one name whoever holds it, and the controller can tell whether anything holds it: while nothing does,
+// the controller starts every walk itself, as it did before there was a delivery to own.
+
+// DeliverySeat is the seat mesh-delivery holds.
+const DeliverySeat = "mesh-delivery"
+
+// deliveryVerbs are the delivery seat's tools: six that read, and the acts of a person, a reviewer and healer H2.
+func deliveryVerbs() []Verb {
+	return []Verb{
+		{Name: "deliveries", Description: "Every delivery not final, and those that ended in the last day, one line " +
+			"each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed " +
+			"by state, repository or group.",
+			Input: schema(map[string]string{"state": "one state, e.g. delivering or held",
+				"repository": "owner/repository", "group": "a group's id (its branch name)",
+				"all": "\"true\": the final ones of the last thirty days too"}, nil, "all")},
+		// Delivery time against the delivery budgets (novox/hq ADR 0282): what probe D16 reads, optional until its
+		// holder serves it.
+		{Name: "times", Description: "Delivery time: from a merge to every machine of its walk running the build. " +
+			"Each class's delivery budget (a leaf module three minutes, a core module ten), the last days' median and " +
+			"worst, how many within and over, the newest delivery of each class, every delivery over its budget with its " +
+			"longest phase, and the delivered ones whose time is not known. Given a delivery's id, its time phase by phase.",
+			Input: schema(map[string]string{"days": "how many days back (default 7)", "id": "one delivery's id: its phases"}, nil),
+			// Optional until mesh-delivery serves it: its holder lives in the catalogue (design 33 §7).
+			Optional: true},
+		{Name: "show", Description: "One delivery or group whole: its delivery plan (what it builds, what each " +
+			"machine receives, what is not an ordinary send), every transition with when and why, the machine " +
+			"steps of its walk, its group and its order.",
+			Input: schema(map[string]string{"id": "a delivery's id, or a group's"}, []string{"id"})},
+		{Name: "groups", Description: "Every delivery group: its members in order, why each pair is ordered " +
+			"(declared, built by, version skew, engine before controller, by name), its composed check and its " +
+			"state, derived from its members.",
+			Input: schema(map[string]string{"all": "\"true\": the groups that ended too"}, nil, "all")},
+		{Name: "what-if", Description: "The delivery plan a change would have, asked of the controller's planner " +
+			"and kept nowhere: the modules it moves and their dependents in tiers, what each machine would receive, " +
+			"the steps that are not an ordinary send.",
+			Input: schema(map[string]string{"repository": "owner/repository",
+				"paths": "the files it changes, comma-separated, from the repository's root",
+				"base":  "the branch it merges into (default main)"}, []string{"repository", "paths"})},
+		{Name: "checks", Description: "What the mesh's checks said of a pull request's head or of one commit: each " +
+			"of the commit's mesh statuses (mesh/merge-gate, mesh/repo-check, mesh/delivery, …) with its state, " +
+			"description and when it was set; the merge check's full verdict as the controller said it — each " +
+			"layer's summary, the machine that ran it, when, its build id and its report; and whether the branch's " +
+			"protection would let it merge, every required status being success.",
+			Input: schema(map[string]string{"repository": "owner/repository",
+				"number": "a pull request's number: its head is read",
+				"commit": "a commit's sha, or the start of one, instead of a pull request"}, []string{"repository"}),
+			// Added after the seat's first holder shipped: optional until mesh-delivery serves it everywhere.
+			Optional: true},
+		{Name: "table", Description: "The state table every delivery runs by: each transition with its guard, " +
+			"each state's bound and what healer H2 may do once it has passed; and the machine steps' table.",
+			Input: schema(map[string]string{}, nil)},
+		{Name: "stalled", Description: "Every delivery held past its state's bound, with the transition the table " +
+			"lets healer H2 take for it, or none.",
+			Input: schema(map[string]string{}, nil)},
+		{Name: "recheck", Description: "Check a rejected or ready delivery again: it goes back to proposed and the " +
+			"controller is asked for its check. With why.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "release", Description: "A person's word that a held delivery goes on: it starts delivering. With why.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "stop", Description: "Stop a delivery that is not final, with why; its walk is ended through the " +
+			"controller, and in a group every member after it is stopped too, naming it.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "close", Description: "Healer H2's verb: take the one transition the table names for a delivery held " +
+			"past its bound. Refused for any other.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "the condition it answers"},
+				[]string{"id", "why"})},
+		{Name: "retire-history", Description: "Retire held deliveries that are history, on a person's word, with " +
+			"why: each made from the forge's word for a merge on the trunk heard long after it happened — replayed " +
+			"when the holder first held the seat — with no walk of it open. Never released, delivered or put back: " +
+			"retired, final. One by id, refused when the rule does not take it; or every held one, of one " +
+			"repository when named, answering how many it retired and naming those it left held. dry \"true\" " +
+			"answers what it would do and changes nothing.",
+			Input: schema(map[string]string{"why": "why, kept with every transition",
+				"id":         "one delivery's id; every held one when empty",
+				"repository": "owner/repository: only its held deliveries",
+				"dry":        "\"true\": what it would retire, changing nothing"}, []string{"why"}, "dry"),
+			// Added after the seat's holder shipped (novox/hq issue 313): optional until mesh-delivery serves it.
+			Optional: true},
+		{Name: "mark-ready", Description: "A reviewer's word that a delivery's head is approved: the holder puts the " +
+			"label mesh/ready on its pull request and then writes \"ready at <head>\", the order the forge counts, " +
+			"as the mesh's own forge account, naming who reviewed it and why. Refused when the delivery's commit is " +
+			"no longer its pull request's head. mesh-delivery then merges it once its checks pass (novox/hq ADR 0364).",
+			Input: schema(map[string]string{"id": "the delivery's id (owner/repository@commit): the head reviewed",
+				"reviewed-by": "who reviewed it, as who@node", "why": "the review's verdict in a line"},
+				[]string{"id", "reviewed-by", "why"}),
+			// Kept one more release, optional (novox/hq issue 1022): mesh-delivery no longer serves it, but the manifest
+			// it still has on the mesh does until its catalogue member merges, and a seat refuses a holder that serves
+			// a verb it does not promise. The next release removes this entry.
+			Optional: true},
+	}
+}
+
+// SeatSays is whether a consumed `<seat>.<event>` names one of the seat's own events: the seat emits it,
+// exactly or by one of its patterns (`log.*`). A consumed name whose emitter is a seat and whose event the
+// seat does not emit is the event of the module of that name (novox/hq ADR 0239): mesh-delivery is a seat
+// and the module holding it, and what the module says it says as itself, through the runtime that launches
+// it — read as the seat's, a consumer would subscribe a subject nothing may publish.
+func SeatSays(emits []string, event string) bool {
+	for _, e := range emits {
+		if e == event || topicMatches(e, event) {
+			return true
+		}
+	}
+	return false
+}
+
+// topicMatches is whether an event's name matches a declared pattern, `*` one dot-separated segment and
+// `>` or `**` the rest.
+func topicMatches(pattern, event string) bool {
+	p, e := splitDots(pattern), splitDots(event)
+	for i, part := range p {
+		if part == ">" || part == "**" {
+			return len(e) > i
+		}
+		if i >= len(e) || (part != "*" && part != e[i]) {
+			return false
+		}
+	}
+	return len(p) == len(e)
+}
+
+func splitDots(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); i++ {
+		if s[i] == '.' {
+			out = append(out, s[start:i])
+			start = i + 1
+		}
+	}
+	return append(out, s[start:])
+}

go/catalogue/delivery_seat_test.go

@@ -0,0 +1,164 @@
+package catalogue
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// The delivery seat answers "what did the mesh's checks say of this pull request?" as a verb of its own,
+// `checks` (novox/hq ADR 0239): read by repository and a pull request's number or a commit.
+func TestTheDeliverySeatPromisesChecks(t *testing.T) {
+	seat, ok := SeatNamed(DeliverySeat)
+	if !ok {
+		t.Fatal("the delivery seat is not in the set")
+	}
+	var checks *Verb
+	for i := range seat.Serves {
+		if seat.Serves[i].Name == "checks" {
+			checks = &seat.Serves[i]
+		}
+	}
+	if checks == nil {
+		t.Fatalf("the delivery seat promises %v and not checks", VerbNames(seat.Serves))
+	}
+	props, _ := checks.Input["properties"].(map[string]any)
+	for _, arg := range []string{"repository", "number", "commit"} {
+		if _, has := props[arg]; !has {
+			t.Errorf("checks takes no %q", arg)
+		}
+	}
+	if req, _ := checks.Input["required"].([]string); !reflect.DeepEqual(req, []string{"repository"}) {
+		t.Errorf("checks requires %v, wanted only the repository", req)
+	}
+
+	// Added after the seat's holder shipped, it is optional: the holder serving the ten verbs before it still
+	// holds the seat, and one serving all eleven does too — so the controller and the catalogue can move in
+	// either order, and no check of the catalogue fails on a module nobody touched between the two.
+	if !checks.Optional {
+		t.Fatal("checks is a condition of holding before its holder serves it")
+	}
+	var before []string
+	for _, v := range VerbNames(seat.Serves) {
+		if v != "checks" {
+			before = append(before, v)
+		}
+	}
+	m := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: before}}}
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder without checks yet: %v", err)
+	}
+	m.Claims[0].Serves = VerbNames(seat.Serves)
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder serving every verb: %v", err)
+	}
+	// Every other verb is still a condition of holding.
+	m.Claims[0].Serves = append([]string{"checks"}, before[1:]...)
+	if err := CanHold(m, seat); err == nil || !strings.Contains(err.Error(), before[0]) {
+		t.Fatalf("a holder without %s: %v", before[0], err)
+	}
+}
+
+// The seat retires history on a person's word (novox/hq issue 313): `retire-history`, with why, one delivery by
+// id or every held one, dry to see first. Added after the holder shipped, it is optional, so the holder that
+// does not serve it yet still holds the seat, and one that does is not refused for a verb the seat lacks.
+func TestTheDeliverySeatPromisesRetireHistoryOptionally(t *testing.T) {
+	seat, _ := SeatNamed(DeliverySeat)
+	var retire *Verb
+	for i := range seat.Serves {
+		if seat.Serves[i].Name == "retire-history" {
+			retire = &seat.Serves[i]
+		}
+	}
+	if retire == nil || !retire.Optional {
+		t.Fatalf("the delivery seat promises %v, retire-history optionally", VerbNames(seat.Serves))
+	}
+	props, _ := retire.Input["properties"].(map[string]any)
+	for _, arg := range []string{"why", "id", "repository", "dry"} {
+		if _, has := props[arg]; !has {
+			t.Errorf("retire-history takes no %q", arg)
+		}
+	}
+	if req, _ := retire.Input["required"].([]string); !reflect.DeepEqual(req, []string{"why"}) {
+		t.Errorf("retire-history requires %v, wanted only why", req)
+	}
+	var without []string
+	for _, v := range VerbNames(seat.Serves) {
+		if v != "retire-history" {
+			without = append(without, v)
+		}
+	}
+	m := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: without}}}
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder without retire-history yet: %v", err)
+	}
+	m.Claims[0].Serves = VerbNames(seat.Serves)
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder serving retire-history: %v", err)
+	}
+}
+
+// The seat says delivery times (novox/hq ADR 0282, issue 382): `times`, over some days or for one delivery. Added
+// after the holder shipped, it is optional, so the holder that does not serve it yet still holds the seat, and one
+// that does is not refused for a verb the seat lacks.
+func TestTheDeliverySeatPromisesTimesOptionally(t *testing.T) {
+	seat, _ := SeatNamed(DeliverySeat)
+	var times *Verb
+	for i := range seat.Serves {
+		if seat.Serves[i].Name == "times" {
+			times = &seat.Serves[i]
+		}
+	}
+	if times == nil || !times.Optional {
+		t.Fatalf("the delivery seat promises %v, times optionally", VerbNames(seat.Serves))
+	}
+	props, _ := times.Input["properties"].(map[string]any)
+	for _, arg := range []string{"days", "id"} {
+		if _, has := props[arg]; !has {
+			t.Errorf("times takes no %q", arg)
+		}
+	}
+	var without []string
+	for _, v := range VerbNames(seat.Serves) {
+		if v != "times" {
+			without = append(without, v)
+		}
+	}
+	m := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: without}}}
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder without times yet: %v", err)
+	}
+	m.Claims[0].Serves = VerbNames(seat.Serves)
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder serving times: %v", err)
+	}
+}
+
+// The seat still promises `mark-ready`, optionally, for one more release (issue 1022); it was added by novox/hq issue 913: `mark-ready`, with the delivery's id, who reviewed it
+// and why, so a reviewer marks a pull request through one audited verb, label and comment in the order the forge
+// counts, instead of two raw forge calls. Added after the holder shipped, it is optional.
+func TestTheDeliverySeatPromisesMarkReadyOptionally(t *testing.T) {
+	seat, _ := SeatNamed(DeliverySeat)
+	var mark *Verb
+	for i := range seat.Serves {
+		if seat.Serves[i].Name == "mark-ready" {
+			mark = &seat.Serves[i]
+		}
+	}
+	if mark == nil || !mark.Optional {
+		t.Fatalf("the delivery seat promises %v, mark-ready optionally", VerbNames(seat.Serves))
+	}
+	if req, _ := mark.Input["required"].([]string); !reflect.DeepEqual(req, []string{"id", "reviewed-by", "why"}) {
+		t.Errorf("mark-ready requires %v, wanted id, reviewed-by and why", req)
+	}
+	var without []string
+	for _, v := range VerbNames(seat.Serves) {
+		if v != "mark-ready" {
+			without = append(without, v)
+		}
+	}
+	m := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: without}}}
+	if err := CanHold(m, seat); err != nil {
+		t.Fatalf("a holder without mark-ready yet: %v", err)
+	}
+}

go/catalogue/derived_for_consumer_test.go

@@ -0,0 +1,346 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// What a provider derives for each consumer, said once and delivered to both ends
+// (novox/hq ADR 0202, 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 where its definition asks (${setting:…}), and
+// the mesh still derives the rest: the setting is filled first, then the consumer's half. (Until
+// novox/hq issue 696 the layer replaced the served bucket whole; a layer replaces no served key now.)
+func TestASettingComposesWithADerivedValue(t *testing.T) {
+	prefixed := store()
+	prefixed.Serves["s3-bucket"]["bucket"] = "${setting:bucket-prefix}${consumer:as:dns}"
+	r, err := Resolve(shelf(prefixed, 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-prefix": "team-"}}}},
+		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)
+		}
+	}
+}

go/catalogue/dir_into.go

@@ -0,0 +1,373 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// A directory the mesh places (novox/hq ADR 0112, to-be 27, issue 119).
+//
+// **A module definition names no host path.** A directory resource may omit `path`; the mesh
+// resolves where it lands when the declaration is composed — `<root>/<module>/<id>`, the root a
+// node's own setting with /var/lib as the default. From then on the module's own files, mounts
+// and environment name the place as `${dir:<id>}`, the same shape as `${bound:…}` and
+// `${secret:…}`: a fact the module asks for by name and never states.
+//
+// **A directory that states a path keeps it, and still answers `${dir:<id>}`.** That is the
+// placement for an adopted machine: data that must sit where the predecessor already put it is
+// declared with the path as the exception it is, and everything else in the module names it by
+// id — so moving it later is one line, not a search.
+//
+// **The mesh's own files for a module are placed too** (novox/hq issue 174). What the mesh writes
+// *for* a module — its sealed bus credential, its merged configuration, its bindings — is the
+// mesh's plumbing, not the module's data, and sits under `<root>/mesh/<module>`. A directory
+// saying `"place": "mesh"` is that place; the definition names the files beneath it by
+// `${dir:<id>}` and states no path.
+//
+// **Resolved here, not on the machine.** The host receives concrete paths exactly as it always
+// has; nothing new reaches it and it learns no field. Which also means a resolved path changing
+// is a spec change like any other — and the spec comparison must see it (novox/hq issue 126).
+
+// defaultDataRoot is where module data lands when a node states no root of its own.
+const defaultDataRoot = "/var/lib"
+
+// The two places a pathless directory may name, beside its own id.
+const (
+	// placeOwn is the assignment's own root, <root>/<module> — to-be 27's one directory per
+	// assignment, which every other placed thing of the module sits beneath.
+	placeOwn = "."
+	// placeMesh is where the mesh keeps what it writes for the module, <root>/mesh/<module>.
+	placeMesh = "mesh"
+)
+
+// dirRef is how a module names one of its placed directories: ${dir:<id>}.
+var dirRef = regexp.MustCompile(`\$\{dir:([a-z0-9][a-z0-9-]*)\}`)
+
+// dataRoot is the root this node keeps placed directories under.
+func dataRoot(with Rendering) string {
+	if root := strings.TrimRight(strings.TrimSpace(with.DataRoot), "/"); root != "" {
+		return root
+	}
+	return defaultDataRoot
+}
+
+// dirsFor is every placed directory of a module, id → the path it resolves to on this node.
+//
+// A pathless directory saying `"place": "."` is the assignment's own root, <root>/<module>; one
+// saying `"place": "mesh"` is the mesh's directory for the module, <root>/mesh/<module>; one
+// saying neither is <root>/<module>/<id>. At most one of each place makes sense; nothing enforces
+// one, because two ids resolving to one path is a mistake the module's own files make visible
+// immediately.
+//
+// A stated path may itself begin with a placed reference — `${dir:mesh-state}/state` — and is
+// filled after the directories it can name are resolved; one level, because a directory beneath
+// a placed one is the whole of what an adopted layout needs (issue 174's `state` and `out`).
+func dirsFor(m Manifest, with Rendering) map[string]string {
+	dirs := map[string]string{}
+	var beneath []map[string]any
+	// The assignment's placement wins over both (novox/hq issue 153). Refused elsewhere when
+	// malformed; here an invalid setting simply places nothing.
+	placed, _ := Places(m, with.Settings[m.Module])
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) != "directory" {
+			continue
+		}
+		id := fmt.Sprint(r["id"])
+		if p, said := placed[id]; said {
+			dirs[id] = p.Path
+			continue
+		}
+		if path, stated := r["path"].(string); stated && path != "" {
+			if strings.HasPrefix(path, "${dir:") {
+				beneath = append(beneath, r)
+				continue
+			}
+			dirs[id] = strings.TrimRight(path, "/")
+			continue
+		}
+		switch place, _ := r["place"].(string); place {
+		case placeOwn:
+			dirs[id] = dataRoot(with) + "/" + m.Module
+		case placeMesh:
+			dirs[id] = dataRoot(with) + "/mesh/" + m.Module
+		default:
+			dirs[id] = dataRoot(with) + "/" + m.Module + "/" + id
+		}
+	}
+	for _, r := range beneath {
+		path := strings.TrimRight(r["path"].(string), "/")
+		// A reference to no directory is left as written and refused where the resource is
+		// placed (dirInto), with the message that names what exists.
+		filled, _ := dirFill(path, dirs, m.Module)
+		dirs[fmt.Sprint(r["id"])] = filled
+	}
+	return dirs
+}
+
+// placedOrAbsolute says a path is usable where the mesh needs one: absolute already, or
+// beginning with a placed reference — resolution makes it absolute before anything reads it.
+// (unknownDirRefs is what checks the reference names a real directory.)
+func placedOrAbsolute(path string) bool {
+	return strings.HasPrefix(path, "/") ||
+		(strings.HasPrefix(path, "${dir:") && dirRef.MatchString(path))
+}
+
+// dirFill resolves every ${dir:…} in one string, or refuses a reference naming no directory.
+func dirFill(s string, dirs map[string]string, module string) (string, error) {
+	var missing error
+	out := dirRef.ReplaceAllStringFunc(s, func(ref string) string {
+		id := dirRef.FindStringSubmatch(ref)[1]
+		path, has := dirs[id]
+		if !has {
+			missing = fmt.Errorf(
+				"%s says ${dir:%s}, and %s declares no directory %q. It declares %s",
+				module, id, module, id, orNothing(namesOfDirs(dirs)))
+			return ref
+		}
+		return path
+	})
+	return out, missing
+}
+
+// placedManifest is the manifest with every path the mesh resolves already resolved: the maps
+// naming where bindings, credentials and contributions land are filled against this node's
+// placed directories, so everything downstream — the generated binding files, the sealed
+// secrets, the grant directories — reads a concrete place and learns nothing new.
+func placedManifest(m Manifest, with Rendering) (Manifest, error) {
+	dirs := dirsFor(m, with)
+	fillMap := func(in map[string]string) (map[string]string, error) {
+		if len(in) == 0 {
+			return in, nil
+		}
+		out := make(map[string]string, len(in))
+		for key, value := range in {
+			filled, err := dirFill(value, dirs, m.Module)
+			if err != nil {
+				return nil, err
+			}
+			out[key] = filled
+		}
+		return out, nil
+	}
+	var err error
+	if m.Receives, err = fillMap(m.Receives); err != nil {
+		return m, err
+	}
+	if m.Binds, err = fillMap(m.Binds); err != nil {
+		return m, err
+	}
+	if m.Secrets, err = fillMap(m.Secrets); err != nil {
+		return m, err
+	}
+	if len(m.OwnSecrets) > 0 {
+		own := make(OwnSecrets, len(m.OwnSecrets))
+		for name, s := range m.OwnSecrets {
+			filled, err := dirFill(s.Path, dirs, m.Module)
+			if err != nil {
+				return m, err
+			}
+			own[name] = OwnSecret{Path: filled, Taken: s.Taken, IssuedBy: s.IssuedBy, Prompt: s.Prompt, Owner: s.Owner}
+		}
+		m.OwnSecrets = own
+	}
+	if m.Grants, err = fillMap(m.Grants); err != nil {
+		return m, err
+	}
+	if len(m.SecretsMany) > 0 {
+		many := make(map[string]map[string]string, len(m.SecretsMany))
+		for to, locals := range m.SecretsMany {
+			if many[to], err = fillMap(locals); err != nil {
+				return m, err
+			}
+		}
+		m.SecretsMany = many
+	}
+	return m, nil
+}
+
+// dirInto places a resource: a pathless directory is given the path the mesh resolved for it,
+// and every ${dir:…} the resource carries — in its path, its content, its mounts, its
+// environment and its env-files — becomes that path.
+//
+// A reference naming no directory of this module is refused. Left as written, the literal
+// `${dir:x}` would reach the machine as a path, and the runtime would create and mount a
+// directory called `${dir:x}` — real, wrong, and named after the mistake.
+func dirInto(resource map[string]any, dirs map[string]string, module string) error {
+	fill := func(s string) (string, error) { return dirFill(s, dirs, module) }
+
+	if fmt.Sprint(resource["type"]) == "directory" {
+		id := fmt.Sprint(resource["id"])
+		if path, stated := resource["path"].(string); !stated || path == "" {
+			resource["path"] = dirs[id]
+		}
+		// Said in the catalogue, not on the machine: the host parses strictly and knows no
+		// such field — resolved, the place IS the path.
+		delete(resource, "place")
+	}
+
+	var err error
+	if path, ok := resource["path"].(string); ok {
+		if resource["path"], err = fill(path); err != nil {
+			return err
+		}
+	}
+	if content, ok := resource["content"].(string); ok {
+		if resource["content"], err = fill(content); err != nil {
+			return err
+		}
+	}
+	// Nested values are rebuilt, never written into: the resource is a shallow copy of the
+	// manifest's own map, and the manifest is composed once per node — a fill written in place
+	// would leave the first node's paths inside every later composition.
+	if volumes, ok := resource["volumes"].([]any); ok {
+		filled := make([]any, len(volumes))
+		for i, v := range volumes {
+			filled[i] = v
+			if mount, ok := v.(string); ok {
+				if filled[i], err = fill(mount); err != nil {
+					return err
+				}
+			}
+		}
+		resource["volumes"] = filled
+	}
+	if env, ok := resource["env"].(map[string]any); ok {
+		filled := make(map[string]any, len(env))
+		for key, v := range env {
+			filled[key] = v
+			if value, ok := v.(string); ok {
+				if filled[key], err = fill(value); err != nil {
+					return err
+				}
+			}
+		}
+		resource["env"] = filled
+	}
+	if files, ok := resource["env-file"].([]any); ok {
+		filled := make([]any, len(files))
+		for i, v := range files {
+			filled[i] = v
+			if path, ok := v.(string); ok {
+				if filled[i], err = fill(path); err != nil {
+					return err
+				}
+			}
+		}
+		resource["env-file"] = filled
+	}
+	return nil
+}
+
+// unknownDirRefs is every ${dir:…} in the definition that names no directory the definition
+// declares — refused where the author is, not at composition on some later day (the same
+// near-versus-far reasoning as the host's strict parse).
+func (m Manifest) unknownDirRefs() []string {
+	declared := map[string]bool{}
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "directory" {
+			declared[fmt.Sprint(r["id"])] = true
+		}
+	}
+	referenced := func(s string) []string {
+		var ids []string
+		for _, match := range dirRef.FindAllStringSubmatch(s, -1) {
+			ids = append(ids, match[1])
+		}
+		return ids
+	}
+	var problems []string
+	for _, r := range m.Resources {
+		place, said := r["place"].(string)
+		if !said {
+			continue
+		}
+		if fmt.Sprint(r["type"]) != "directory" {
+			problems = append(problems, fmt.Sprintf(
+				"%s says place on %v, which is not a directory — only a directory is placed",
+				m.Module, r["id"]))
+			continue
+		}
+		if path, stated := r["path"].(string); stated && path != "" {
+			problems = append(problems, fmt.Sprintf(
+				"%s states both path and place on %v — a stated path IS the placement",
+				m.Module, r["id"]))
+		}
+		if place != placeOwn && place != placeMesh {
+			problems = append(problems, fmt.Sprintf(
+				"%s says place %q on %v, and the places are %q — the assignment's own root — and "+
+					"%q — where the mesh keeps what it writes for the module",
+				m.Module, place, r["id"], placeOwn, placeMesh))
+		}
+	}
+	seen := map[string]bool{}
+	refuse := func(id string, where any) {
+		if declared[id] || seen[id] {
+			return
+		}
+		seen[id] = true
+		problems = append(problems, fmt.Sprintf(
+			"%s says ${dir:%s} in %v, and declares no directory %q — a reference the mesh "+
+				"cannot place would reach the machine as a literal path",
+			m.Module, id, where, id))
+	}
+	for _, r := range m.Resources {
+		for _, field := range []string{"path", "content"} {
+			if s, ok := r[field].(string); ok {
+				for _, id := range referenced(s) {
+					refuse(id, r["id"])
+				}
+			}
+		}
+		for _, field := range []string{"volumes", "env-file"} {
+			if list, ok := r[field].([]any); ok {
+				for _, v := range list {
+					if s, ok := v.(string); ok {
+						for _, id := range referenced(s) {
+							refuse(id, r["id"])
+						}
+					}
+				}
+			}
+		}
+		if env, ok := r["env"].(map[string]any); ok {
+			for _, v := range env {
+				if s, ok := v.(string); ok {
+					for _, id := range referenced(s) {
+						refuse(id, r["id"])
+					}
+				}
+			}
+		}
+	}
+	maps := map[string]map[string]string{
+		"receives": m.Receives, "binds": m.Binds, "secrets": m.Secrets,
+		"own-secrets": m.OwnSecrets.Paths(), "grants": m.Grants,
+	}
+	for field, entries := range maps {
+		for _, value := range entries {
+			for _, id := range referenced(value) {
+				refuse(id, field)
+			}
+		}
+	}
+	for to, locals := range m.SecretsMany {
+		for _, value := range locals {
+			for _, id := range referenced(value) {
+				refuse(id, "secrets."+to)
+			}
+		}
+	}
+	sort.Strings(problems)
+	return problems
+}
+
+func namesOfDirs(dirs map[string]string) []string {
+	var names []string
+	for id := range dirs {
+		names = append(names, fmt.Sprintf("%q", id))
+	}
+	sort.Strings(names)
+	return names
+}

go/catalogue/dir_into_test.go

@@ -0,0 +1,325 @@
+package catalogue
+
+// A directory the mesh places (novox/hq ADR 0112). These tests pin the contract: a pathless
+// directory resolves under the node's root, ${dir:…} names it from every field a host path can
+// live in, a stated path is the adopted-data placement and wins, an unknown reference refuses at
+// the manifest, and filling for one node never leaks into the next composition.
+
+import (
+	"strings"
+	"testing"
+)
+
+func placedModule() Manifest {
+	return Manifest{
+		Module: "photos",
+		Resources: []map[string]any{
+			{"id": "data", "type": "directory", "mode": "0700"},
+			{"id": "server-env", "type": "file", "path": "${dir:data}/server.env",
+				"content": "STORE=${dir:data}/objects\n"},
+			{"id": "server", "type": "container", "name": "photos-server",
+				"volumes":  []any{"${dir:data}:/data"},
+				"env":      map[string]any{"DATA": "${dir:data}/objects"},
+				"env-file": []any{"${dir:data}/server.env"}},
+		},
+	}
+}
+
+func TestAPathlessDirectoryResolvesUnderTheNodesRoot(t *testing.T) {
+	m := placedModule()
+	dirs := dirsFor(m, Rendering{})
+	if dirs["data"] != "/var/lib/photos/data" {
+		t.Fatalf("the default root is /var/lib and the shape is <root>/<module>/<id>; got %q", dirs["data"])
+	}
+	dirs = dirsFor(m, Rendering{DataRoot: "/tank/nox/"})
+	if dirs["data"] != "/tank/nox/photos/data" {
+		t.Fatalf("a node's own root is honoured, trailing slash and all; got %q", dirs["data"])
+	}
+}
+
+func TestDirReferencesBecomeThePlaceInEveryField(t *testing.T) {
+	m := placedModule()
+	dirs := dirsFor(m, Rendering{})
+
+	directory := shallowCopy(m.Resources[0])
+	if err := dirInto(directory, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if directory["path"] != "/var/lib/photos/data" {
+		t.Fatalf("a pathless directory receives its resolved path; got %v", directory["path"])
+	}
+
+	file := shallowCopy(m.Resources[1])
+	if err := dirInto(file, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if file["path"] != "/var/lib/photos/data/server.env" {
+		t.Fatalf("a file's path names the place; got %v", file["path"])
+	}
+	if file["content"] != "STORE=/var/lib/photos/data/objects\n" {
+		t.Fatalf("a file's content names the place; got %v", file["content"])
+	}
+
+	container := shallowCopy(m.Resources[2])
+	if err := dirInto(container, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if container["volumes"].([]any)[0] != "/var/lib/photos/data:/data" {
+		t.Fatalf("a mount names the place; got %v", container["volumes"])
+	}
+	if container["env"].(map[string]any)["DATA"] != "/var/lib/photos/data/objects" {
+		t.Fatalf("an environment value names the place; got %v", container["env"])
+	}
+	if container["env-file"].([]any)[0] != "/var/lib/photos/data/server.env" {
+		t.Fatalf("an env-file names the place; got %v", container["env-file"])
+	}
+}
+
+func TestAStatedPathIsThePlacementAndStillAnswersByName(t *testing.T) {
+	m := placedModule()
+	// The adopted-machine case: data that must sit where the predecessor already put it.
+	m.Resources[0]["path"] = "/services/mssql/data/"
+	dirs := dirsFor(m, Rendering{})
+	if dirs["data"] != "/services/mssql/data" {
+		t.Fatalf("a stated path wins over the root, trimmed; got %q", dirs["data"])
+	}
+	container := shallowCopy(m.Resources[2])
+	if err := dirInto(container, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if container["volumes"].([]any)[0] != "/services/mssql/data:/data" {
+		t.Fatalf("references follow the placement; got %v", container["volumes"])
+	}
+}
+
+func TestFillingForOneNodeLeaksIntoNoOther(t *testing.T) {
+	m := placedModule()
+	first := shallowCopy(m.Resources[2])
+	if err := dirInto(first, dirsFor(m, Rendering{DataRoot: "/first"}), m.Module); err != nil {
+		t.Fatal(err)
+	}
+	second := shallowCopy(m.Resources[2])
+	if err := dirInto(second, dirsFor(m, Rendering{DataRoot: "/second"}), m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if got := second["volumes"].([]any)[0]; got != "/second/photos/data:/data" {
+		t.Fatalf("the second composition must see the manifest, not the first fill; got %v", got)
+	}
+	if m.Resources[2]["volumes"].([]any)[0] != "${dir:data}:/data" {
+		t.Fatalf("the manifest itself stays a template; got %v", m.Resources[2]["volumes"])
+	}
+}
+
+func TestAReferenceToNoDirectoryRefusesAtTheManifest(t *testing.T) {
+	m := placedModule()
+	m.Resources[2]["volumes"] = []any{"${dir:date}:/data"} // a typo, the likely shape
+	problems := m.unknownDirRefs()
+	if len(problems) != 1 || !strings.Contains(problems[0], `${dir:date}`) {
+		t.Fatalf("a reference naming no directory is a manifest problem; got %v", problems)
+	}
+	if got := placedModule().unknownDirRefs(); len(got) != 0 {
+		t.Fatalf("a correct definition has none; got %v", got)
+	}
+}
+
+func TestAReferenceToNoDirectoryRefusesAtCompositionToo(t *testing.T) {
+	m := placedModule()
+	container := shallowCopy(m.Resources[2])
+	container["env"] = map[string]any{"DATA": "${dir:date}"}
+	err := dirInto(container, dirsFor(m, Rendering{}), m.Module)
+	if err == nil || !strings.Contains(err.Error(), `"date"`) || !strings.Contains(err.Error(), `"data"`) {
+		t.Fatalf("the refusal names the mistake and what exists; got %v", err)
+	}
+}
+
+func TestTheAssignmentsOwnRootIsAPlace(t *testing.T) {
+	m := Manifest{Module: "mailu", Resources: []map[string]any{
+		{"id": "state", "type": "directory", "place": ".", "mode": "0700"},
+		{"id": "data-mail", "type": "directory"},
+	}}
+	dirs := dirsFor(m, Rendering{})
+	if dirs["state"] != "/var/lib/mailu" {
+		t.Fatalf("place %q is the assignment's root; got %q", ".", dirs["state"])
+	}
+	if dirs["data-mail"] != "/var/lib/mailu/data-mail" {
+		t.Fatalf("everything else sits beneath it; got %q", dirs["data-mail"])
+	}
+	root := shallowCopy(m.Resources[0])
+	if err := dirInto(root, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if root["path"] != "/var/lib/mailu" {
+		t.Fatalf("the root receives its path; got %v", root["path"])
+	}
+	if _, still := root["place"]; still {
+		t.Fatal("place must never reach the host, which parses strictly")
+	}
+}
+
+func TestTheManifestsMapsArePlaced(t *testing.T) {
+	m := Manifest{
+		Module: "photos",
+		Resources: []map[string]any{
+			{"id": "state", "type": "directory", "place": "."},
+		},
+		Binds:      map[string]string{"route": "${dir:state}/route.json"},
+		Secrets:    map[string]string{"mongodb-database": "${dir:state}/database.secret"},
+		OwnSecrets: OwnSecrets{"admin-key": {Path: "${dir:state}/admin-key.secret"}},
+		Receives:   map[string]string{"route": "${dir:state}/grants/mesh.json"},
+	}
+	placed, err := placedManifest(m, Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if placed.Binds["route"] != "/var/lib/photos/route.json" {
+		t.Fatalf("binds are placed; got %v", placed.Binds)
+	}
+	if placed.Secrets["mongodb-database"] != "/var/lib/photos/database.secret" {
+		t.Fatalf("secrets are placed; got %v", placed.Secrets)
+	}
+	if placed.OwnSecrets["admin-key"].Path != "/var/lib/photos/admin-key.secret" {
+		t.Fatalf("own-secrets are placed; got %v", placed.OwnSecrets)
+	}
+	if placed.Receives["route"] != "/var/lib/photos/grants/mesh.json" {
+		t.Fatalf("receives are placed; got %v", placed.Receives)
+	}
+	if m.Binds["route"] != "${dir:state}/route.json" {
+		t.Fatalf("the manifest itself stays a template; got %v", m.Binds)
+	}
+}
+
+func TestAMapReferenceToNoDirectoryRefusesAtTheManifest(t *testing.T) {
+	m := Manifest{
+		Module:    "photos",
+		Resources: []map[string]any{{"id": "state", "type": "directory", "place": "."}},
+		Binds:     map[string]string{"route": "${dir:stat}/route.json"},
+	}
+	problems := m.unknownDirRefs()
+	if len(problems) != 1 || !strings.Contains(problems[0], `${dir:stat}`) {
+		t.Fatalf("a map naming no directory is a manifest problem; got %v", problems)
+	}
+}
+
+func TestPlaceIsValidatedAtTheManifest(t *testing.T) {
+	both := Manifest{Module: "x", Resources: []map[string]any{
+		{"id": "d", "type": "directory", "place": ".", "path": "/somewhere"},
+	}}
+	if got := both.unknownDirRefs(); len(got) != 1 || !strings.Contains(got[0], "both path and place") {
+		t.Fatalf("path beside place refuses; got %v", got)
+	}
+	elsewhere := Manifest{Module: "x", Resources: []map[string]any{
+		{"id": "f", "type": "file", "place": ".", "path": "/somewhere", "content": ""},
+	}}
+	if got := elsewhere.unknownDirRefs(); len(got) != 1 || !strings.Contains(got[0], "not a directory") {
+		t.Fatalf("place on a file refuses; got %v", got)
+	}
+	wrong := Manifest{Module: "x", Resources: []map[string]any{
+		{"id": "d", "type": "directory", "place": "sub/dir"},
+	}}
+	if got := wrong.unknownDirRefs(); len(got) != 1 || !strings.Contains(got[0], `the places are "."`) {
+		t.Fatalf("a place that is neither root refuses; got %v", got)
+	}
+}
+
+func TestTheMeshsDirectoryForAModuleIsAPlace(t *testing.T) {
+	// novox/hq issue 174. What the mesh writes for a module — its bus credential, its bindings —
+	// is the mesh's plumbing under <root>/mesh/<module>, and the definition names it by id.
+	m := Manifest{Module: "umami",
+		Resources: []map[string]any{
+			{"id": "mesh-state", "type": "directory", "place": "mesh"},
+			{"id": "state", "type": "directory", "place": "."},
+			{"id": "server", "type": "container", "image": "x@sha256:aa",
+				"volumes": []any{"${dir:mesh-state}/broker:/run/secrets/broker:ro"}},
+		},
+		OwnSecrets: OwnSecrets{"broker": {Path: "${dir:mesh-state}/broker"}},
+		Binds:      map[string]string{"route": "${dir:state}/route.json"},
+	}
+	if got := m.unknownDirRefs(); len(got) != 0 {
+		t.Fatalf("place %q is a place; got %v", "mesh", got)
+	}
+	dirs := dirsFor(m, Rendering{})
+	if dirs["mesh-state"] != "/var/lib/mesh/umami" || dirs["state"] != "/var/lib/umami" {
+		t.Fatalf("the mesh's directory sits beside the module's, not in it; got %v", dirs)
+	}
+	dirs = dirsFor(m, Rendering{DataRoot: "/srv"})
+	if dirs["mesh-state"] != "/srv/mesh/umami" {
+		t.Fatalf("a node's root moves the mesh's files with the module's; got %v", dirs)
+	}
+	placed, err := placedManifest(m, Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if placed.OwnSecrets["broker"].Path != "/var/lib/mesh/umami/broker" {
+		t.Fatalf("own-secrets are placed under the mesh's directory; got %v", placed.OwnSecrets)
+	}
+	container := shallowCopy(m.Resources[2])
+	if err := dirInto(container, dirsFor(m, Rendering{}), m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if container["volumes"].([]any)[0] != "/var/lib/mesh/umami/broker:/run/secrets/broker:ro" {
+		t.Fatalf("the mount's host side is placed; got %v", container["volumes"])
+	}
+}
+
+func TestTwoModulesPlacedRootsAreNoCollision(t *testing.T) {
+	a := Manifest{Module: "gitea", Resources: []map[string]any{
+		{"id": "state", "type": "directory", "place": "."},
+		{"id": "env", "type": "file", "path": "${dir:state}/server.env", "content": ""},
+	}}
+	b := Manifest{Module: "nextcloud", Resources: []map[string]any{
+		{"id": "state", "type": "directory", "place": "."},
+		{"id": "env", "type": "file", "path": "${dir:state}/server.env", "content": ""},
+	}}
+	if got := checkResources([]Manifest{a, b}); len(got) != 0 {
+		t.Fatalf("alike templates are different places; got %v", got)
+	}
+	// And the real collision is still caught: a module stating another's placed root.
+	c := Manifest{Module: "squatter", Resources: []map[string]any{
+		{"id": "nest", "type": "directory", "path": "/var/lib/gitea"},
+	}}
+	got := checkResources([]Manifest{a, c})
+	if len(got) != 1 || !strings.Contains(got[0], `"/var/lib/gitea"`) {
+		t.Fatalf("a stated path on a placed root collides; got %v", got)
+	}
+}
+
+func shallowCopy(resource map[string]any) map[string]any {
+	copied := map[string]any{}
+	for k, v := range resource {
+		copied[k] = v
+	}
+	return copied
+}
+
+func TestADirectoryBeneathAPlacedOneIsPlacedWithIt(t *testing.T) {
+	// An adopted layout keeps a subdirectory the predecessor made under the mesh's directory
+	// (issue 174: a forge's runtime state, a manager's output). Stated as beneath the placed one,
+	// it moves with it — a node's root moves both, and the definition names no host path.
+	m := Manifest{Module: "gitea", Resources: []map[string]any{
+		{"id": "mesh-state", "type": "directory", "place": "mesh"},
+		{"id": "runtime-state", "type": "directory", "path": "${dir:mesh-state}/state"},
+		{"id": "server", "type": "container", "image": "x@sha256:aa",
+			"volumes": []any{"${dir:runtime-state}:/data"}},
+	}}
+	if got := m.unknownDirRefs(); len(got) != 0 {
+		t.Fatalf("a path beneath a placed directory is well formed; got %v", got)
+	}
+	dirs := dirsFor(m, Rendering{DataRoot: "/srv"})
+	if dirs["runtime-state"] != "/srv/mesh/gitea/state" {
+		t.Fatalf("the subdirectory follows the placed one; got %v", dirs)
+	}
+	sub := shallowCopy(m.Resources[1])
+	if err := dirInto(sub, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if sub["path"] != "/srv/mesh/gitea/state" {
+		t.Fatalf("the directory resource itself is resolved; got %v", sub["path"])
+	}
+	container := shallowCopy(m.Resources[2])
+	if err := dirInto(container, dirs, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if container["volumes"].([]any)[0] != "/srv/mesh/gitea/state:/data" {
+		t.Fatalf("a reference to the subdirectory resolves whole; got %v", container["volumes"])
+	}
+}

go/catalogue/doc.go

@@ -0,0 +1,7 @@
+// Copied from mesh-controller internal/catalogue at commit 6c2a8d62100cb7d491f8eb9a623e1eeea5ec0de1 (novox/hq ADR 0453
+// clause 3, ADR 0446 clause 4), so the builder, the checker and the assigner can read and resolve a manifest. The files
+// are unchanged but for import paths, this note and KnownCapabilities, which gains user-namespaces (issue 1308's name).
+// The test files that read mesh-controller's other packages or its own module.json stay in mesh-controller, as do two
+// tests of single files here that read its module.json (TestTheControllersOwnManifestClaimsItsSeat and
+// TestTheControlPlanesOwnAddressesFollowTheNodesPorts). mesh-controller keeps its own copy until release 4b.
+package catalogue

go/catalogue/domain_test.go

@@ -0,0 +1,134 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A domain module is a module with requirements and no files of its own.
+//
+// Most people want the network working and do not want to choose a VPN. Some want a particular
+// one. Both are the same mechanism: assigning `networking` takes the only answer to each of its
+// requirements silently, and the day there are two answers the resolver refuses and names them,
+// so choosing is assigning the one you want. There is no flavor field and nothing to configure.
+
+func networkingShelf(extra ...Manifest) map[string]Manifest {
+	base := []Manifest{
+		{Module: "networking", Requires: []string{"private-network", "name-resolution"}},
+		{Module: "mesh-wireguard", Computed: "mesh-wireguard",
+			Provides: Offers("private-network", "mesh-addressing"),
+			Claims:   []Claim{{Name: "the-private-network", Scope: ScopeNode}}},
+		{Module: "mesh-names", Computed: "mesh-names",
+			Provides: Offers("name-resolution"), Requires: []string{"mesh-addressing"}},
+	}
+	return shelf(append(base, extra...)...)
+}
+
+func TestOneWordBringsUpTheNetwork(t *testing.T) {
+	// The case that has to stay easy. Nothing is asked, because with one answer to each
+	// requirement there was never a question.
+	got, err := Resolve(networkingShelf(), []string{"networking"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	have := strings.Join(names(got), " ")
+	for _, want := range []string{"networking", "mesh-wireguard", "mesh-names"} {
+		if !strings.Contains(have, want) {
+			t.Fatalf("assigning networking did not bring in %s: %s", want, have)
+		}
+	}
+}
+
+func TestASecondVPNTurnsItIntoAChoice(t *testing.T) {
+	// And the choice is offered rather than made. A default here would be the flavor field coming
+	// back under another name.
+	_, err := Resolve(networkingShelf(
+		Manifest{Module: "tailscale", Provides: Offers("private-network"),
+			Claims: []Claim{{Name: "the-private-network", Scope: ScopeNode}}},
+	), []string{"networking"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("two VPNs and one was picked silently")
+	}
+	for _, want := range []string{"mesh-wireguard", "tailscale"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("the refusal does not name %s: %v", want, err)
+		}
+	}
+}
+
+func TestChoosingIsAssigning(t *testing.T) {
+	// No second verb. Assigning the one you want answers the requirement, and the bundle takes it.
+	got, err := Resolve(networkingShelf(
+		Manifest{Module: "tailscale",
+			Provides: Offers("private-network", "name-resolution"),
+			Claims:   []Claim{{Name: "the-private-network", Scope: ScopeNode}}},
+	), []string{"networking", "tailscale"}, workstation(), World{})
+
+	if err != nil {
+		t.Fatal(err)
+	}
+	have := strings.Join(names(got), " ")
+	if !strings.Contains(have, "tailscale") {
+		t.Fatalf("the chosen VPN is not in the set: %s", have)
+	}
+	if strings.Contains(have, "mesh-wireguard") {
+		t.Fatalf("choosing tailscale still installed WireGuard: %s", have)
+	}
+}
+
+func TestChoosingOneVPNCannotDragTheOtherBackIn(t *testing.T) {
+	// This happened. The person chose tailscale; the names module required the mesh's own
+	// addressing; only WireGuard provides that; so both were installed and nobody was told.
+	//
+	// The claim is what catches it. Providing a private network is not the singular part — a
+	// machine could run two VPNs for two purposes — but being *the* one the mesh runs over is.
+	_, err := Resolve(networkingShelf(
+		Manifest{Module: "tailscale", Provides: Offers("private-network"),
+			Claims: []Claim{{Name: "the-private-network", Scope: ScopeNode}}},
+	), []string{"networking", "tailscale"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("a machine was given two private networks without being told")
+	}
+	if !strings.Contains(err.Error(), "the-private-network") {
+		t.Fatalf("the refusal does not say what collided: %v", err)
+	}
+}
+
+func TestNamesNeedTheMeshsOwnAddresses(t *testing.T) {
+	// Names are computed from addresses the mesh handed out. Over a VPN that hands out its own,
+	// the mesh has nothing to write, so the names module requires the addressing rather than a
+	// private network in general — otherwise a machine gets a hosts file full of addresses that
+	// mean nothing on it.
+	_, err := Resolve(shelf(
+		Manifest{Module: "mesh-names", Computed: "mesh-names",
+			Provides: Offers("name-resolution"), Requires: []string{"mesh-addressing"}},
+		Manifest{Module: "tailscale", Provides: Offers("private-network")},
+	), []string{"mesh-names", "tailscale"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("the mesh's names were installed over a VPN whose addresses it does not hand out")
+	}
+	if !strings.Contains(err.Error(), "mesh-addressing") {
+		t.Fatalf("the refusal does not say what is missing: %v", err)
+	}
+}
+
+func TestARequirementWantedTwiceIsReportedOnce(t *testing.T) {
+	// Two identical lines make a person hunt for the difference between them before realising
+	// there is none.
+	_, err := Resolve(shelf(
+		Manifest{Module: "one", Requires: []string{"shell"}},
+		Manifest{Module: "two", Requires: []string{"shell"}},
+		Manifest{Module: "bash", Provides: Offers("shell")},
+		Manifest{Module: "zsh", Provides: Offers("shell")},
+	), []string{"one", "two"}, workstation(), World{})
+
+	if err == nil {
+		t.Fatal("two shells and one was picked silently")
+	}
+	if n := strings.Count(err.Error(), `"shell" is wanted by`); n != 1 {
+		t.Fatalf("the same requirement was reported %d times:\n%v", n, err)
+	}
+}

go/catalogue/endpoint_test.go

@@ -0,0 +1,205 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// aMediaServer is the shape one port number per key cannot express: two endpoints of different kinds.
+// A web surface a proxy serves under a subdomain, and a protocol port clients dial directly because
+// the client expects that number.
+func aMediaServer() Manifest {
+	return Manifest{
+		Module: "media",
+		Listens: []Listening{
+			{Name: "web", Port: 80, From: FromMesh, Why: "the app, behind the proxy"},
+			{Name: "stream", Port: 32400, From: FromEverywhere, Fixed: true,
+				Why: "the client dials this number; the protocol chose it"},
+		},
+		Contributes: map[string]map[string]any{
+			"route": {"label": "media", RouteEndpoint: "web"},
+		},
+		// Both endpoints are published by its container, which is what lets a machine port be given
+		// for either: the mesh moves a port the module publishes, never one it merely listens on.
+		Resources: []map[string]any{
+			{"id": "server", "type": "container", "name": "media",
+				"ports": []any{"80", "32400"}},
+		},
+	}
+}
+
+// **A route names the endpoint it serves.** A route and a listen both carried a port and nothing said
+// they were the same thing; now one of them says so.
+func TestARouteNamesTheEndpointItServes(t *testing.T) {
+	m := aMediaServer()
+	if port, ok := EndpointPort(m, "web"); !ok || port != 80 {
+		t.Fatalf("the web endpoint resolves to %d (%v), want 80", port, ok)
+	}
+	if port, ok := EndpointPort(m, "stream"); !ok || port != 32400 {
+		t.Fatalf("the stream endpoint resolves to %d (%v), want 32400", port, ok)
+	}
+	if _, ok := EndpointPort(m, "absent"); ok {
+		t.Fatal("an endpoint the module does not declare resolved to a port")
+	}
+}
+
+// And the routed set is read through the name, so the endpoint the proxy serves is known without a
+// reader joining two numbers.
+func TestTheRoutedEndpointIsFoundByName(t *testing.T) {
+	routed := RoutedPorts(aMediaServer())
+	if !routed[80] {
+		t.Fatalf("the routed endpoint was not found by name: %v", routed)
+	}
+	// And the directly-dialled one is not routed, which is what lets its reach govern its port.
+	if routed[32400] {
+		t.Fatalf("the endpoint clients dial directly reads as routed: %v", routed)
+	}
+}
+
+// **Two endpoints of different shapes, configured as themselves.** The web endpoint's reach asks for
+// names and leaves its port to the proxy; the stream endpoint's reach governs its port, because
+// clients dial it and there is no name.
+func TestTwoEndpointsOfDifferentShapesAreConfiguredSeparately(t *testing.T) {
+	m := aMediaServer()
+	settings := SettingsBy{"media": {{From: "node anchor", Values: map[string]any{
+		ReachSetting: map[string]any{"80": ReachBoth, "32400": ReachPublic},
+	}}}}
+
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	rules, err := r.Rules(Rendering{Settings: settings})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, rule := range rules {
+		switch rule.Port {
+		case 80:
+			if rule.From != FromMesh {
+				t.Fatalf("the routed endpoint's port opened to %q; the proxy is how it is reached",
+					rule.From)
+			}
+		case 32400:
+			if rule.From != FromEverywhere {
+				t.Fatalf("the directly-dialled endpoint's port is %q, want anywhere", rule.From)
+			}
+		}
+	}
+
+	// And the routed one carries both names, asked for by the same statement.
+	given, err := r.contributions(settings, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var public, internal string
+	for _, c := range given["route"] {
+		public, _ = c.Values["name"].(string)
+		internal, _ = c.Values["internal-name"].(string)
+	}
+	if public != "media.example.test" || internal != "media.anchor.internal" {
+		t.Fatalf("names are %q and %q, want both", public, internal)
+	}
+}
+
+// A route naming an endpoint the module does not declare reaches nothing, and is refused where it is
+// written rather than resolving to no port and serving nothing.
+func TestARouteNamingAnEndpointTheModuleLacksIsRefused(t *testing.T) {
+	m := aMediaServer()
+	m.Contributes["route"][RouteEndpoint] = "absent"
+	got := strings.Join(RouteProblems(m), "\n")
+	if !strings.Contains(got, "does not declare") {
+		t.Fatalf("a route naming an absent endpoint was accepted:\n%s", got)
+	}
+}
+
+// **Two endpoints called the same would make an assignment configure whichever was read last.** The
+// point of a name is that it identifies one thing.
+func TestTwoEndpointsWithOneNameAreRefused(t *testing.T) {
+	m := Manifest{Module: "twice", Listens: []Listening{
+		{Name: "web", Port: 80, From: FromMesh},
+		{Name: "web", Port: 8080, From: FromMesh},
+	}}
+	got := strings.Join(endpointNameProblems(m), "\n")
+	if !strings.Contains(got, "could mean either") {
+		t.Fatalf("two endpoints with one name were accepted:\n%s", got)
+	}
+}
+
+// A name that is not a name is refused where it is written: it ends up in something a person types.
+func TestAnEndpointNameIsHeldToItsShape(t *testing.T) {
+	for _, wrong := range []string{"Web", "web port", "3000", "-web", "web_surface"} {
+		m := Manifest{Module: "odd", Listens: []Listening{{Name: wrong, Port: 80, From: FromMesh}}}
+		if got := strings.Join(endpointNameProblems(m), "\n"); !strings.Contains(got, "a name is lowercase") {
+			t.Fatalf("%q was accepted as an endpoint name:\n%s", wrong, got)
+		}
+	}
+}
+
+// **Every endpoint in the catalogue is unnamed today, and must stay valid.** The word ships one
+// release before anything uses it.
+func TestAnUnnamedEndpointIsStillValid(t *testing.T) {
+	m := Manifest{Module: "ordinary", Listens: []Listening{{Port: 443, From: FromEverywhere}}}
+	if got := endpointNameProblems(m); len(got) != 0 {
+		t.Fatalf("an unnamed endpoint was refused: %v", got)
+	}
+	if got := RouteProblems(m); len(got) != 0 {
+		t.Fatalf("a module with no route was refused: %v", got)
+	}
+}
+
+// **A route that names an endpoint still carries that endpoint's port.**
+//
+// Everything downstream reads the port: the provider is told where to reach the consumer, and the
+// redirection that turns a declared port into the number the machine published is keyed on it. A route
+// naming only its endpoint left the proxy with no port, and a proxy with no port has nothing to dial.
+//
+// Caught after the catalogue had already been changed to name endpoints, and before the mesh picked
+// those manifests up — which is the only reason nothing broke.
+func TestARouteNamingAnEndpointStillCarriesItsPort(t *testing.T) {
+	m := aMediaServer()
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	given, err := r.contributions(nil, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var saw bool
+	for _, c := range given["route"] {
+		saw = true
+		port, ok := asPort(c.Values["port"])
+		if !ok {
+			t.Fatalf("the route carries no port, so the proxy has nothing to dial: %v", c.Values)
+		}
+		if port != 80 {
+			t.Fatalf("the route carries port %d, want the web endpoint's 80", port)
+		}
+	}
+	if !saw {
+		t.Fatal("the module contributed no route")
+	}
+}
+
+// And the declared port, not the machine one: the redirection to where the machine published it
+// happens later and is keyed on the declared number, so filling the machine port in here would be
+// redirected twice or not at all.
+func TestTheEndpointsDeclaredPortIsFilledInNotTheMachineOne(t *testing.T) {
+	m := aMediaServer()
+	values := map[string]any{RouteEndpoint: "web", "label": "media"}
+	portOfEndpoint(values, endpointPorts(m))
+	if got, _ := asPort(values["port"]); got != 80 {
+		t.Fatalf("filled in port %d, want the declared 80", got)
+	}
+	// Then the ordinary redirection puts it where the machine published it.
+	moved := atMachinePort(values, m.Module, map[string]map[int]int{"media": {80: 20009}})
+	if got, _ := asPort(moved["port"]); got != 20009 {
+		t.Fatalf("after redirection the port is %d, want the machine's 20009", got)
+	}
+}
+
+// A route that repeats a port keeps it, because that is the older shape and still read.
+func TestARouteThatRepeatsItsPortKeepsIt(t *testing.T) {
+	values := map[string]any{RouteEndpoint: "web", "port": 8080}
+	portOfEndpoint(values, map[string]int{"web": 80})
+	if got, _ := asPort(values["port"]); got != 8080 {
+		t.Fatalf("the port it stated was overwritten with %d", got)
+	}
+}

go/catalogue/endpoints_setting_test.go

@@ -0,0 +1,140 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+func configured(block map[string]any) SettingsBy {
+	return SettingsBy{"media": {{From: "node anchor",
+		Placement: map[string]any{EndpointsSetting: block}}}}
+}
+
+// **One block per endpoint, saying all three things.** The machine port, the subdomain and the reach
+// were `ports`, the route's label and `reach`, each keyed by a port number, so configuring a module
+// with two endpoints of different shapes meant knowing which number was which.
+func TestAnEndpointsBlockSaysPortLabelAndReach(t *testing.T) {
+	m := aMediaServer()
+	// stream's reach NARROWS what the manifest says — the manifest has it from anywhere, the
+	// assignment says internal. Chosen deliberately: a reach that agrees with the manifest proves
+	// nothing about whether the block was read at all.
+	settings := configured(map[string]any{
+		"web":    map[string]any{"port": 20009, "label": "cinema", "reach": ReachBoth},
+		"stream": map[string]any{"reach": ReachInternal},
+	})
+
+	// The machine port, where the mapping is read.
+	given, err := GivenPorts(m, settings["media"])
+	if err != nil {
+		t.Fatal(err)
+	}
+	if given[80] != 20009 {
+		t.Fatalf("the web endpoint is on machine port %d, want 20009: %v", given[80], given)
+	}
+
+	// The reach, where the filter reads it.
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	rules, err := r.Rules(Rendering{Settings: settings})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, rule := range rules {
+		if rule.Port == 32400 && rule.From != FromMesh {
+			t.Fatalf("the directly-dialled endpoint is %q; the assignment narrowed it to the private "+
+				"network and the manifest's 'anywhere' should not win", rule.From)
+		}
+		if rule.Port == 80 && rule.From != FromMesh {
+			t.Fatalf("the routed endpoint's port opened to %q; the proxy is how it is reached", rule.From)
+		}
+	}
+
+	// And the subdomain, where the name is composed — the assignment's, not the module's.
+	nodes, err := r.contributions(settings, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range nodes["route"] {
+		if got, _ := c.Values["name"].(string); got != "cinema.example.test" {
+			t.Fatalf("the public name is %q, want the label the assignment gave", got)
+		}
+		if got, _ := c.Values["internal-name"].(string); got != "cinema.anchor.internal" {
+			t.Fatalf("the internal name is %q, want the label the assignment gave", got)
+		}
+	}
+}
+
+// A block that says only a reach leaves the port to the mesh and the label to the module, which is the
+// ordinary case and must not require writing the other two.
+func TestABlockMaySayOnlyAReach(t *testing.T) {
+	m := aMediaServer()
+	settings := configured(map[string]any{"web": map[string]any{"reach": ReachInternal}})
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	nodes, err := r.contributions(settings, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, c := range nodes["route"] {
+		if got, _ := c.Values["name"].(string); got != "" {
+			t.Fatalf("an internal endpoint composed the public name %q", got)
+		}
+		// The module's own label, untouched.
+		if got, _ := c.Values["internal-name"].(string); got != "media.anchor.internal" {
+			t.Fatalf("the internal name is %q, want the module's own label", got)
+		}
+	}
+}
+
+// An endpoint the module does not declare reaches nothing, and the refusal says what it does declare.
+func TestConfiguringAnEndpointTheModuleLacksIsRefused(t *testing.T) {
+	_, err := Endpoints(aMediaServer(), configured(map[string]any{
+		"admin": map[string]any{"reach": ReachInternal}})["media"])
+	if err == nil || !strings.Contains(err.Error(), "does not declare") {
+		t.Fatalf("configuring an absent endpoint was accepted: %v", err)
+	}
+	if err != nil && !strings.Contains(err.Error(), "stream") {
+		t.Fatalf("the refusal does not name what the module declares: %v", err)
+	}
+}
+
+func TestAReachInABlockIsHeldToTheFourValues(t *testing.T) {
+	_, err := Endpoints(aMediaServer(), configured(map[string]any{
+		"web": map[string]any{"reach": "mesh"}})["media"])
+	if err == nil || !strings.Contains(err.Error(), "a reach is") {
+		t.Fatalf("a filter word was accepted as a reach: %v", err)
+	}
+}
+
+// **Two places giving one endpoint a machine port is the confusion this key exists to end.**
+func TestAnEndpointGivenAPortTwiceIsRefused(t *testing.T) {
+	m := aMediaServer()
+	_, err := GivenPorts(m, []Layer{{From: "node anchor", Placement: map[string]any{
+		EndpointsSetting: map[string]any{"web": map[string]any{"port": 20009}},
+		PortsSetting:     map[string]any{"80": 30000},
+	}}})
+	if err == nil || !strings.Contains(err.Error(), "published once") {
+		t.Fatalf("an endpoint given two machine ports was accepted: %v", err)
+	}
+}
+
+// And the same for its reach, said once here and once through the older key.
+func TestAnEndpointWhoseReachIsAlsoExposedIsRefused(t *testing.T) {
+	_, err := Endpoints(aMediaServer(), []Layer{{From: "node anchor", Placement: map[string]any{
+		EndpointsSetting: map[string]any{"web": map[string]any{"reach": ReachInternal}},
+		ExposeSetting:    map[string]any{"80": FromEverywhere},
+	}}})
+	if err == nil || !strings.Contains(err.Error(), "same thing in different words") {
+		t.Fatalf("a reach said two ways was accepted: %v", err)
+	}
+}
+
+// A module whose endpoints are unnamed cannot be configured this way, and is told so rather than
+// having a block silently reach nothing — which is every module in the catalogue today.
+func TestAModuleWithNoNamedEndpointsIsToldSo(t *testing.T) {
+	m := Manifest{Module: "media", Listens: []Listening{{Port: 80, From: FromMesh}}}
+	_, err := Endpoints(m, configured(map[string]any{"web": map[string]any{"reach": ReachBoth}})["media"])
+	if err == nil || !strings.Contains(err.Error(), "no endpoints by name") {
+		t.Fatalf("a module with no named endpoints accepted a block: %v", err)
+	}
+}

go/catalogue/engine_guard_test.go

@@ -0,0 +1,71 @@
+package catalogue
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"path/filepath"
+	"slices"
+	"strconv"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// The controller refuses a definition's resolved path by the node-engine's own rules, no more (novox/hq issue
+// 496): the same lists, read here from mesh-host's internal/apply/placement_guard.go — in a merge check the clone
+// beside it at the commit the mesh runs, elsewhere the copy captured in testdata/beside. When the engine's lists
+// move, this fails until the controller's move with them, so the gate never refuses what the engine applies nor
+// passes what it refuses by path alone.
+func TestTheResolvedPathRulesAreTheNodeEnginesOwn(t *testing.T) {
+	file := filepath.Join(beside.Dir(t, "mesh-host"), "internal", "apply", "placement_guard.go")
+	parsed, err := parser.ParseFile(token.NewFileSet(), file, nil, 0)
+	if err != nil {
+		t.Fatalf("the node-engine's guard does not parse: %v", err)
+	}
+	lists := map[string][]string{}
+	consts := map[string]string{}
+	ast.Inspect(parsed, func(n ast.Node) bool {
+		spec, ok := n.(*ast.ValueSpec)
+		if !ok {
+			return true
+		}
+		for i, name := range spec.Names {
+			if i >= len(spec.Values) {
+				continue
+			}
+			switch v := spec.Values[i].(type) {
+			case *ast.CompositeLit:
+				for _, elt := range v.Elts {
+					if lit, ok := elt.(*ast.BasicLit); ok && lit.Kind == token.STRING {
+						s, _ := strconv.Unquote(lit.Value)
+						lists[name.Name] = append(lists[name.Name], s)
+					}
+				}
+			case *ast.BasicLit:
+				if v.Kind == token.STRING {
+					consts[name.Name], _ = strconv.Unquote(v.Value)
+				}
+			}
+		}
+		return true
+	})
+	for name, ours := range map[string][]string{
+		"protectedRoots": protectedRoots, "forbiddenBelow": forbiddenBelow, "engineTrees": engineTrees,
+	} {
+		theirs := lists[name]
+		if len(theirs) == 0 {
+			t.Errorf("the node-engine's guard names no %s any more; read it and say where its rule went", name)
+			continue
+		}
+		a, b := slices.Clone(ours), slices.Clone(theirs)
+		slices.Sort(a)
+		slices.Sort(b)
+		if !slices.Equal(a, b) {
+			t.Errorf("%s differs from the node-engine's:\n controller %v\n node-engine %v", name, a, b)
+		}
+	}
+	if consts["engineModule"] != engineModule {
+		t.Errorf("the node-engine's own module is %q there and %q here", consts["engineModule"], engineModule)
+	}
+}

go/catalogue/environment_into.go

@@ -0,0 +1,731 @@
+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"
+	// PowerSeat is the seat whose holder places code for the power moments (novox/hq ADR 0211).
+	PowerSeat = "node-power"
+)
+
+// 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"}
+	// sessionFiles are the two files of the graphical session's start that read no directory, so a
+	// contribution to them is a slot rather than a drop-in (novox/hq ADR 0208 §4): `xinitrc` is POSIX
+	// code the session's start runs, `xresources` X resources merged at its start. Placed by the
+	// display server's holder, as a shell's slots are placed by the login shell's.
+	sessionFiles = []string{"xinitrc", "xresources"}
+	// powerMoments are the moments of a machine's power a module may run code at (novox/hq ADR
+	// 0211 §3): POSIX code run as root by node-power's holder, in module order, each piece bounded.
+	powerMoments = []string{"after-boot", "before-sleep", "after-wake", "before-shutdown", "on-mains", "on-battery"}
+)
+
+// contributionTargets is every name a contribution's `for` may take.
+func contributionTargets() []string {
+	out := append(append([]string(nil), knownShells...), sessionFiles...)
+	return append(out, powerMoments...)
+}
+
+// placerOf is the seat whose holder places a contribution for this target (novox/hq ADR 0204,
+// ADR 0208 §4).
+func placerOf(target string) string {
+	if oneOf(sessionFiles, target) {
+		return DisplayServerSeat
+	}
+	if oneOf(powerMoments, target) {
+		return PowerSeat
+	}
+	return LoginShellSeat
+}
+
+// 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:([^}]*)\}`)
+	// ofContributed is either kind of contributed text, matched together so both fill in one pass.
+	ofContributed = regexp.MustCompile(`\$\{(shell|contribution|backup):([^}]*)\}`)
+)
+
+// 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(contributionTargets(), c.For) {
+			problems = append(problems, fmt.Sprintf(
+				"%s's shell code %d is for %q; the shells are %s, the session's files %s, and the power "+
+					"moments %s", m.Module, i+1, c.For, strings.Join(knownShells, ", "),
+				strings.Join(sessionFiles, ", "), strings.Join(powerMoments, ", ")))
+		}
+		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)...)
+		problems = append(problems, seatPlaceholderProblems(m, r)...)
+		problems = append(problems, collectedPlaceholderProblems(m, r)...)
+		problems = append(problems, consumersPlaceholderProblems(m, r)...)
+		// And every placeholder no pass fills where it stands: a misspelt namespace, a key its
+		// namespace cannot take, or a field its pass does not read (novox/hq issue 231).
+		problems = append(problems, unconsumedPlaceholders(m.Module, 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))
+		}
+		// Each placeholder judged by its own target: a shell's code is the login shell's holder's to
+		// place (ADR 0204), the session's files the display server's (ADR 0208 §4) — and a holder of
+		// one placing the other's would be a second writer of a file there is one of.
+		refusedFor := map[string]bool{}
+		for _, c := range code {
+			target, slot, two := strings.Cut(c[1], ":")
+			if !two || !oneOf(contributionTargets(), target) || !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, the session's file one of %s or the power moment one of %s, and the slot one of %s",
+					m.Module, r["id"], c[0], strings.Join(knownShells, ", "), strings.Join(sessionFiles, ", "),
+					strings.Join(powerMoments, ", "), strings.Join(knownSlots, ", ")))
+				continue
+			}
+			seat := placerOf(target)
+			if m.ClaimsSeat(seat) || refusedFor[seat] {
+				continue
+			}
+			refusedFor[seat] = true
+			if seat == PowerSeat {
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %v names %s and %s does not claim %s; every module's code for a power "+
+						"moment is placed by the power seat's holder alone (novox/hq ADR 0211)",
+					m.Module, r["id"], c[0], m.Module, seat))
+				continue
+			}
+			if seat == DisplayServerSeat {
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %v names %s and %s does not claim %s; every module's %s is placed by "+
+						"the display server's holder alone (novox/hq ADR 0208)",
+					m.Module, r["id"], c[0], m.Module, seat, target))
+				continue
+			}
+			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"], c[0], m.Module, seat))
+		}
+	}
+	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) {
+		e := environmentOf(m)
+		if e == nil {
+			continue
+		}
+		for _, n := range sortedKeys(e.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) {
+		e := environmentOf(m)
+		if e == nil {
+			continue
+		}
+		if len(e.Variables) > 0 {
+			set := setBy{module: m.Module, values: map[string]string{}}
+			for _, n := range sortedKeys(e.Variables) {
+				v, err := factsIn(e.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 e.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
+}
+
+// environmentOf is a module's environment as the old form and the items of the environment collection say it: an
+// item's template is the variable's value or the PATH entry, and its attributes the kind, the name and where on PATH
+// (design 57 L3, issue 795). A moved contributor's items are rendered here into a collector not handed, as the
+// provisioner's client renders them into one that is. An item whose text the mesh does not hold is not here; it is
+// said as not placed (itemsLeftOutFor).
+func environmentOf(m Manifest) *Environment {
+	var out *Environment
+	if m.Environment != nil {
+		out = &Environment{Variables: map[string]string{}, Path: append([]PathEntry(nil), m.Environment.Path...)}
+		for k, v := range m.Environment.Variables {
+			out.Variables[k] = v
+		}
+	}
+	for _, it := range itemsInOrder(m.Items) {
+		if it.Collection != EnvironmentCollection || it.Content == "" {
+			continue
+		}
+		if out == nil {
+			out = &Environment{Variables: map[string]string{}}
+		}
+		value := strings.TrimSuffix(it.Content, "\n")
+		switch it.Attributes["kind"] {
+		case "variable":
+			out.Variables[it.Attributes["name"]] = value
+		case "path":
+			out.Path = append(out.Path, PathEntry{Entry: value, At: it.Attributes["at"]})
+		}
+	}
+	return out
+}
+
+// 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 {
+	return shellCodeOn(modules, shell, slot, nil)
+}
+
+// shellCodeOn is shellCode on a machine with these facts: a moved contributor's item of the slot's collection is
+// rendered in its module's place as its old form was (heldItemText), so a collector not handed keeps every line.
+func shellCodeOn(modules []Manifest, shell, slot string, facts map[string]string) string {
+	return shellCodeFor(modules, shell, slot, facts, nil)
+}
+
+// oldFormOfCollected is a file's text with each `${collected:contribution:<seat>:<kind>:…}` of a kind received as data
+// read as the old `${contribution:<seat>:<kind>:…}`: where the collector is not handed, the controller renders the
+// kind's items as it rendered its contributions, so the two forms place the same text (design 57 L3, issue 781).
+func oldFormOfCollected(content string) string {
+	return ofCollected.ReplaceAllStringFunc(content, func(placeholder string) string {
+		name := ofCollected.FindStringSubmatch(placeholder)[1]
+		base, _ := splitSelector(name)
+		if format, is := strings.CutPrefix(base, EnvironmentCollection+":"); is {
+			return "${environment:" + format + "}"
+		}
+		if !strings.HasPrefix(base, "contribution:") {
+			return placeholder
+		}
+		seat, kind, _ := strings.Cut(strings.TrimPrefix(base, "contribution:"), ":")
+		if _, r, ok := receivable(seat, kind); !ok || !collectableAsText(r) {
+			return placeholder
+		}
+		return "${" + name + "}"
+	})
+}
+
+// shellCodeFor is shellCodeOn on a machine with these capabilities, which an item's `if-capability` is judged by. The
+// pieces are placed by order (an item's `order` attribute, the default for the old form), then module, as the
+// provisioner's client places them.
+func shellCodeFor(modules []Manifest, shell, slot string, facts map[string]string, caps map[string]bool) string {
+	var blocks []textBlock
+	for _, m := range inModuleOrder(modules) {
+		var old strings.Builder
+		for _, c := range m.Shell {
+			if c.For != shell || c.Slot != slot {
+				continue
+			}
+			if old.Len() == 0 {
+				fmt.Fprintf(&old, "# %s\n", m.Module)
+			}
+			old.WriteString(c.Code)
+			if !strings.HasSuffix(c.Code, "\n") {
+				old.WriteString("\n")
+			}
+		}
+		blocks = append(blocks, moduleBlocks(m, "#", old.String(), heldItems(m, "shell:"+shell+":"+slot, nil, facts, caps))...)
+	}
+	return joinBlocks(blocks)
+}
+
+// textBlock is a stretch of a collector's text and the order it is placed by.
+type textBlock struct {
+	order int
+	text  string
+}
+
+// moduleBlocks is one module's pieces of a placeholder: what its old form made (placed by the default order), and
+// each of its held items under a line naming the module, as the provisioner's client writes one per item. An item
+// of the default order that follows the old form's text shares its line, as a module's item always did.
+func moduleBlocks(m Manifest, comment, old string, items []heldItem) []textBlock {
+	var blocks []textBlock
+	if old != "" {
+		blocks = append(blocks, textBlock{OrderDefault, old})
+	}
+	for i, h := range items {
+		text := h.text
+		if i == 0 && old != "" && h.item.order() == OrderDefault {
+			blocks[0].text += text
+			continue
+		}
+		blocks = append(blocks, textBlock{h.item.order(), fmt.Sprintf("%s %s\n", comment, m.Module) + text})
+	}
+	return blocks
+}
+
+// joinBlocks is the blocks by order, those of one order in the order given (module order).
+func joinBlocks(blocks []textBlock) string {
+	sort.SliceStable(blocks, func(a, b int) bool { return blocks[a].order < blocks[b].order })
+	var b strings.Builder
+	for _, blk := range blocks {
+		b.WriteString(blk.text)
+	}
+	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, with Rendering, caps map[string]bool, unplaced *[]string) error {
+	problems := append(placeholderProblems(m, resource), seatPlaceholderProblems(m, resource)...)
+	if problems = append(problems, collectedPlaceholderProblems(m, resource)...); len(problems) > 0 {
+		return fmt.Errorf("%s", problems[0])
+	}
+	judged, err := consumersNotHanded(m, resource, with)
+	if err != nil {
+		return err
+	}
+	if judged {
+		resource["content"] = ofConsumers.ReplaceAllString(fmt.Sprint(resource["content"]), "")
+	}
+	content, ok := resource["content"].(string)
+	if !ok {
+		return nil
+	}
+	content = oldFormOfCollected(content)
+	// **An item is the provisioner client's** (design 57 L1): a collector filled here, the old way, holds the old
+	// forms alone, and each item of its collections is said as not placed. A collection of the new form is empty.
+	if unplaced != nil {
+		for _, f := range templatePlaceholder.FindAllStringSubmatch(content, -1) {
+			if collection, is := collectionOfPlaceholder(f[1], f[2]); is {
+				_, selector := splitSelector(f[2])
+				where, _ := selectorOf(selector)
+				*unplaced = append(*unplaced, itemsLeftOutFor(modules, m, collection, where, facts, caps)...)
+			}
+		}
+	}
+	content = ofCollected.ReplaceAllString(content, "")
+	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()
+		})
+	}
+	// Shell code and seat contributions in one pass (novox/hq ADR 0212): both are contributed text
+	// the controller does not read, so neither may be scanned after the other is in place — a
+	// contributed line that happened to spell the other's placeholder would be filled.
+	if ofContributed.MatchString(content) {
+		var failed error
+		content = ofContributed.ReplaceAllStringFunc(content, func(placeholder string) string {
+			found := ofContributed.FindStringSubmatch(placeholder)
+			first, second, _ := strings.Cut(found[2], ":")
+			if found[1] == BackupNamespace {
+				placed, problem := backupPlacer{modules, with, facts, caps, unplaced}.placed(m, found[2], false)
+				if problem != "" && failed == nil {
+					failed = fmt.Errorf("%s names %s: %s", m.Module, placeholder, problem)
+				}
+				return placed
+			}
+			if found[1] == "contribution" {
+				placed, left, err := seatContributions(modules, m, found[2], with, facts, caps)
+				if err != nil && failed == nil {
+					failed = err
+				}
+				if unplaced != nil {
+					*unplaced = append(*unplaced, left...)
+				}
+				return placed
+			}
+			return shellCodeFor(modules, first, second, facts, caps)
+		})
+		if failed != nil {
+			return failed
+		}
+	}
+	resource["content"] = content
+	return nil
+}

go/catalogue/environment_into_integration_test.go

@@ -0,0 +1,91 @@
+//go:build integration
+
+package catalogue
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+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)
+	}
+}
+
+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("NOT JUDGED: no environment.d generator on this machine, so the service manager's reading " +
+			"of the rendering is judged only where systemd runs; the rendering itself is held byte for byte " +
+			"by TestTheEnvironmentRendersForTheServiceManagerByteForByte")
+	}
+	const base = "/usr/bin:/bin"
+	read := func(conf string) map[string]string {
+		t.Helper()
+		config := t.TempDir()
+		if err := os.MkdirAll(filepath.Join(config, "environment.d"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if conf != "" {
+			if err := os.WriteFile(filepath.Join(config, "environment.d", "50-mesh.conf"), []byte(conf), 0o644); err != nil {
+				t.Fatal(err)
+			}
+		}
+		cmd := exec.Command(generator)
+		cmd.Env = []string{"PATH=" + base, "HOME=" + config, "XDG_CONFIG_HOME=" + config}
+		out, err := cmd.CombinedOutput()
+		if err != nil {
+			t.Fatalf("%v\n%s", err, out)
+		}
+		vars := map[string]string{}
+		for _, line := range strings.Split(strings.TrimSpace(string(out)), "\n") {
+			if k, v, ok := strings.Cut(line, "="); ok {
+				vars[k] = v
+			}
+		}
+		return vars
+	}
+	machine, read50 := read(""), read(composedSystemd)
+
+	// What the machine's own files do to PATH: nothing, or append to it. One that replaces or prepends
+	// leaves nothing this test can say about the mesh's file, and says so rather than guess.
+	added, ok := strings.CutPrefix(machine["PATH"], base)
+	if machine["PATH"] != "" && !ok {
+		t.Skipf("NOT JUDGED: this machine's own environment.d sets PATH to %s, not %s with something after it, so "+
+			"what the mesh's file adds cannot be told apart from it", machine["PATH"], base)
+	}
+	want := "/home/op/go/bin:/usr/local/go/bin:/home/op/.local/bin:/home/op/bin:/usr/bin:/bin:/opt/agent/bin:/opt/scripts" + added
+	if read50["PATH"] != want || read50["GOPATH"] != "/home/op/go" {
+		t.Fatalf("the service manager read PATH=%s GOPATH=%s, not PATH=%s GOPATH=/home/op/go (the machine's own "+
+			"files add %q to PATH)", read50["PATH"], read50["GOPATH"], want, added)
+	}
+}

go/catalogue/environment_into_test.go

@@ -0,0 +1,424 @@
+package catalogue
+
+import (
+	"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.
+
+// 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.
+//
+// The generator also reads the machine's own environment.d (/etc, /run, /usr/lib, /usr/local/lib), and
+// no option points it elsewhere: a desktop whose snapd appends its bin directory failed this, on main,
+// for a file the mesh never wrote (novox/hq issue 432). So the generator is run twice, once without the
+// mesh's file, and what the machine's own files make of PATH and set is held out of the verdict.
+//
+// A machine without the generator — the build seat's toolchain image holds no systemd — cannot judge
+// this and says so: there the rendering is held byte for byte by
+// TestTheEnvironmentRendersForTheServiceManagerByteForByte, and this reading only where systemd runs.
+
+// 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)
+	}
+}

go/catalogue/environment_items_test.go

@@ -0,0 +1,165 @@
+package catalogue
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+// The session environment is a collection of typed items (design 57 L3, issue 795): a variable is an item with
+// kind=variable and name=<NAME>, a PATH entry one with kind=path and at=start|end, each a template whose text is the
+// value or the entry. Where node-env is not handed the controller renders the items as the old form was rendered;
+// where it is, it names the collection for the client, which fills the same files (mesh-catalog's provisioner client
+// holds that half against the same golden files). testdata/environment holds the environment of the catalogue's five
+// contributors as the old form composed it, with all five and with zsh alone.
+
+type envDecl struct{ module, item, name, value string }
+
+func environmentOfTheCatalogue() []envDecl {
+	return []envDecl{
+		{"adwaita", "gtk-theme", "GTK_THEME", "Adwaita:dark"},
+		{"adwaita", "gtk2-rc-files", "GTK2_RC_FILES", "/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc"},
+		{"adwaita", "qt-qpa-platformtheme", "QT_QPA_PLATFORMTHEME", "qt6ct"},
+		{"adwaita", "qt-style-override", "QT_STYLE_OVERRIDE", "Fusion"},
+		{"adwaita", "qt-select", "QT_SELECT", "6"},
+		{"adwaita", "xcursor-theme", "XCURSOR_THEME", "Adwaita"},
+		{"adwaita", "xcursor-size", "XCURSOR_SIZE", "24"},
+		{"clipmenu", "cm-selections", "CM_SELECTIONS", "clipboard"},
+		{"clipmenu", "cm-max-clips", "CM_MAX_CLIPS", "500"},
+		{"clipmenu", "cm-histlength", "CM_HISTLENGTH", "15"},
+		{"i3", "xdg-current-desktop", "XDG_CURRENT_DESKTOP", "i3"},
+		{"i3", "xdg-session-desktop", "XDG_SESSION_DESKTOP", "i3"},
+		{"xterm", "terminal", "TERMINAL", "xterm"},
+		{"zsh", "editor", "EDITOR", "vim"},
+		{"zsh", "visual", "VISUAL", "vim"},
+		{"zsh", "xdg-config-home", "XDG_CONFIG_HOME", "${machine:account-home}/.config"},
+		{"zsh", "path-local-bin", "path:10", "${machine:account-home}/.local/bin"},
+		{"zsh", "path-scripts", "path:20", "${machine:account-home}/scripts"},
+		{"zsh", "path-scripts-bin", "path:30", "${machine:account-home}/scripts/bin"},
+	}
+}
+
+const environmentCollector = `{"module":"node-env","version":"1","moved":true,
+  "claims":[{"name":"node-environment","scope":"node"}],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]},
+  "resources":[{"id":"posix","type":"file","path":"/home/op/.config/mesh/environment.sh","template":"files/posix"},
+               {"id":"systemd","type":"file","path":"/home/op/.config/environment.d/50-mesh.conf","template":"files/systemd"}]}`
+
+// nodeEnvWith is node-env, its file placing the environment as plan says, with the declared contributors' items.
+func nodeEnvWith(t *testing.T, decls []envDecl, plan string) Resolution {
+	t.Helper()
+	collector := held(t, environmentCollector, builtWith("node-env", map[string]string{
+		"posix": "# header\n" + plan, "systemd": "${environment:systemd}"}))
+	mods := []Manifest{collector}
+	order := []string{"node-env"}
+	byModule := map[string][]envDecl{}
+	var modules []string
+	for _, d := range decls {
+		if byModule[d.module] == nil {
+			modules = append(modules, d.module)
+		}
+		byModule[d.module] = append(byModule[d.module], d)
+	}
+	for _, name := range modules {
+		var items []string
+		texts := map[string]string{}
+		for _, d := range byModule[name] {
+			attrs := fmt.Sprintf(`{"kind":"variable","name":%q}`, d.name)
+			if order, isPath := strings.CutPrefix(d.name, "path:"); isPath {
+				attrs = fmt.Sprintf(`{"kind":"path","at":"start","order":%q}`, order)
+			}
+			items = append(items, fmt.Sprintf(`{"collection":"environment","name":%q,"attributes":%s,"template":"files/env-%s"}`,
+				d.item, attrs, d.item))
+			texts["env-"+d.item] = d.value + "\n"
+		}
+		raw := fmt.Sprintf(`{"module":%q,"version":"1","moved":true,"items":[%s],
+  "build":{"artifacts":[{"name":"files","kind":"archive","from":"files"}]}}`, name, strings.Join(items, ","))
+		mods = append(mods, held(t, raw, builtWith(name, texts)))
+		order = append(order, name)
+	}
+	r, err := Resolve(shelf(mods...), order, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	r.Account = "op"
+	return r
+}
+
+func TestTheEnvironmentOfTheCatalogueIsTheSameHandedOrNot(t *testing.T) {
+	read := func(name string) string {
+		b, err := os.ReadFile(filepath.Join("testdata", "environment", name))
+		if err != nil {
+			t.Fatal(err)
+		}
+		return string(b)
+	}
+	for name, only := range map[string]string{"all": "", "zsh": "zsh"} {
+		var decls []envDecl
+		for _, d := range environmentOfTheCatalogue() {
+			if only == "" || d.module == only {
+				decls = append(decls, d)
+			}
+		}
+		// Named as the collector names it, and as the old placeholder does.
+		for _, plan := range []string{"${collected:environment:posix}", "${environment:posix}"} {
+			r := nodeEnvWith(t, decls, plan)
+			// Not handed: the controller renders each moved contributor's items as the old form was rendered.
+			if got, want := composedFile(t, r, "node-env.posix"), "# header\n"+read(name+".posix"); got != want {
+				t.Errorf("%s, %s, not handed, the POSIX file is\n%s\nwant\n%s", name, plan, got, want)
+			}
+			if got, want := composedFile(t, r, "node-env.systemd"), read(name+".systemd"); got != want {
+				t.Errorf("%s, %s, not handed, the environment.d file is\n%s\nwant\n%s", name, plan, got, want)
+			}
+			// Handed: one collection, named for the client; each contributor's plan names its items.
+			c, _ := composeWith(t, r, handingTo("store:5000"))
+			if got := c.Plans["node-env"].Collections; !reflect.DeepEqual(got, []PlanCollection{{Name: "environment", Comment: "#"}}) {
+				t.Errorf("%s: the plan collects %+v", name, got)
+			}
+			items, got := len(decls), 0
+			for m := range c.Plans {
+				got += len(c.Plans[m].Items)
+			}
+			if got != items {
+				t.Errorf("%s: the plans name %d items, want %d", name, got, items)
+			}
+		}
+	}
+}
+
+func TestAnEnvironmentItemIsTypedAndNamesWhatItNeeds(t *testing.T) {
+	item := func(attrs map[string]string) []string {
+		return environmentItemProblems("x", Item{Collection: "environment", Attributes: attrs})
+	}
+	for _, ok := range []map[string]string{
+		{"kind": "variable", "name": "GTK_THEME"},
+		{"kind": "path", "at": "end", "order": "10"},
+	} {
+		if p := item(ok); len(p) != 0 {
+			t.Errorf("%v is refused: %v", ok, p)
+		}
+	}
+	for _, bad := range []map[string]string{
+		nil, {"kind": "other"}, {"kind": "variable"}, {"kind": "variable", "name": "PATH"},
+		{"kind": "path"}, {"kind": "path", "at": "middle"}, {"kind": "path", "at": "start", "name": "X"},
+		{"kind": "variable", "name": "A", "color": "red"},
+	} {
+		if p := item(bad); len(p) == 0 {
+			t.Errorf("%v is taken", bad)
+		}
+	}
+	if !attributeFits("environment", "name", "GTK_THEME") || attributeFits("shell:zsh:normal", "name", "GTK_THEME") ||
+		attributeFits("environment", "kind", "Variable") {
+		t.Error("an upper-case name is the environment's name alone")
+	}
+	// A module that sets a variable twice, in two modules, is refused as the old form refused it.
+	a := Manifest{Module: "a", Items: []Item{{Collection: "environment", Content: "1\n",
+		Attributes: map[string]string{"kind": "variable", "name": "X"}}}}
+	b := Manifest{Module: "b", Items: []Item{{Collection: "environment", Content: "2\n",
+		Attributes: map[string]string{"kind": "variable", "name": "X"}}}}
+	if err := variablesSetOnce([]Manifest{a, b}); err == nil || !strings.Contains(err.Error(), "both set X") {
+		t.Errorf("two modules setting X: %v", err)
+	}
+}

go/catalogue/events.go

@@ -0,0 +1,199 @@
+package catalogue
+
+import (
+	"fmt"
+	"regexp"
+	"slices"
+	"strings"
+)
+
+// What a module may call an event, and what a consumer may ask for.
+//
+// A module names an event **locally**: `order.placed`, not a subject and not a routing key
+// (design 29 §1). A consumer names the emitter and the event: `billing.order.placed`. The mesh
+// derives the subject from those, so reorganising the subject space leaves every manifest correct.
+//
+// **Nothing checked this until every manifest in the catalogue was wrong the same way**
+// (novox/hq 04-ISSUES/127). All thirty-seven kept the old bus's routing key —
+// `module.<module>.<verb>` — which the derivation read as "a module called `module`", so every
+// cross-module subscription in the mesh pointed at a namespace nobody publishes to. Nothing failed:
+// the services started and none of them reacted. The documentation on these fields taught the old
+// form too, which is why the drift was uniform rather than scattered.
+
+// eventName is one name in a local event: lower-case, and no wildcard.
+var eventName = regexp.MustCompile(`^[a-z0-9][a-z0-9-]*$`)
+
+// The wildcards a consumer may use, spelled the mesh's way and derived to whatever the transport
+// spells them as.
+//
+// **A manifest holds no transport token**, which is the whole point of naming locally: the bus the
+// mesh runs on today spells these `*` and `#`, and the one being built spells them `*` and `>`. A
+// manifest that said either would be a manifest that stopped being true when the wire changed.
+const (
+	// OneName stands for exactly one name.
+	OneName = "*"
+	// TheRest stands for one or more names, and may only come last.
+	TheRest = "**"
+)
+
+// EventProblems is what is wrong with a manifest's events.
+//
+// Refused at registration, because the alternative is a module that installs, starts, connects and
+// reacts to nothing — and every log line says it is fine.
+func EventProblems(m Manifest) []string {
+	var problems []string
+
+	for _, e := range m.Emits {
+		if was, stale := staleEventForm(e, m.Module); stale {
+			problems = append(problems, fmt.Sprintf(
+				"%s emits %q, which is the old bus's routing key. An event is named locally now, so "+
+					"write %q — the mesh derives the subject (novox/hq design 29 §1)",
+				m.Module, was, strings.TrimPrefix(was, "module."+m.Module+".")))
+			continue
+		}
+		if strings.HasPrefix(e, "module.") {
+			problems = append(problems, fmt.Sprintf(
+				"%s emits %q: `module.` is reserved, because it is how the old bus spelled a "+
+					"routing key and an event named that way derives into a namespace nobody owns",
+				m.Module, e))
+			continue
+		}
+		if err := localName(e); err != nil {
+			problems = append(problems, fmt.Sprintf("%s emits %q: %v", m.Module, e, err))
+			continue
+		}
+		// **Its own name, never another's.** The bus enforces that a namespace belongs to the module
+		// it is named for, so an event named for somebody else cannot be published at all. If the
+		// event is about a role rather than about this module, it belongs on the seat: a name that
+		// is stable across whoever fills it (04-ISSUES/127).
+		if first, _, split := strings.Cut(e, "."); split && isAModuleNameOtherThan(first, m.Module) {
+			problems = append(problems, fmt.Sprintf(
+				"%s emits %q, which reads as another module's event. A module publishes under its "+
+					"own name only. If this is about a role rather than about %s, declare it on that "+
+					"seat, where the name survives the holder changing",
+				m.Module, e, m.Module))
+		}
+	}
+
+	for _, c := range m.Consumes {
+		if strings.HasPrefix(c, "module.") {
+			problems = append(problems, fmt.Sprintf(
+				"%s consumes %q, which is the old bus's pattern. A consumed event names its emitter "+
+					"and the event: write %q", m.Module, c, strings.TrimPrefix(c, "module.")))
+			continue
+		}
+		if c == "#" {
+			problems = append(problems, fmt.Sprintf(
+				"%s consumes %q, which is the old bus's wildcard for everything. Write %q",
+				m.Module, c, TheRest))
+			continue
+		}
+		if err := consumePattern(c); err != nil {
+			problems = append(problems, fmt.Sprintf("%s consumes %q: %v", m.Module, c, err))
+		}
+	}
+	return problems
+}
+
+// staleEventForm says an emitted name is this module's own old routing key, and what it was.
+func staleEventForm(event, module string) (string, bool) {
+	return event, module != "" && strings.HasPrefix(event, "module."+module+".")
+}
+
+// isAModuleNameOtherThan says a first token names some module of this mesh that is not this one.
+//
+// Only the mesh's own seats and the catalogue could answer this properly, and neither is reachable
+// from a parser given one manifest. So this catches the case that actually happened — a name that
+// is a *provision* the mesh defines, which is where "another module's event" comes from in practice
+// — and the whole-catalogue check catches the rest.
+func isAModuleNameOtherThan(first, module string) bool {
+	if first == module || first == "" {
+		return false
+	}
+	if _, isASeat := SeatNamed(first); isASeat {
+		return true
+	}
+	if _, isASeat := SeatDelivering(first); isASeat {
+		return true
+	}
+	return false
+}
+
+// localName checks one event name: dot-separated names, no wildcards, nothing else.
+func localName(event string) error {
+	if event == "" {
+		return fmt.Errorf("an event needs a name")
+	}
+	for _, part := range strings.Split(event, ".") {
+		if part == OneName || part == TheRest {
+			return fmt.Errorf("an emitted event names one event, so it carries no wildcard")
+		}
+		if !eventName.MatchString(part) {
+			return fmt.Errorf("%q is not a usable name: lower-case letters, digits and dashes", part)
+		}
+	}
+	return nil
+}
+
+// consumePattern checks a consumed pattern: the emitter, then the event, with wildcards.
+func consumePattern(pattern string) error {
+	if pattern == "" {
+		return fmt.Errorf("a consumed event needs an emitter and an event")
+	}
+	parts := strings.Split(pattern, ".")
+	for i, part := range parts {
+		switch {
+		case part == TheRest:
+			if i != len(parts)-1 {
+				return fmt.Errorf("%q stands for the rest of a name, so nothing may follow it", TheRest)
+			}
+		case part == OneName:
+		case !eventName.MatchString(part):
+			return fmt.Errorf("%q is not a usable name: lower-case letters, digits and dashes", part)
+		}
+	}
+	// `**` alone is every event from every module, which the audit logger wants and says plainly.
+	if len(parts) == 1 && parts[0] != TheRest {
+		return fmt.Errorf(
+			"%q names an emitter and no event. Write <emitter>.<event>, or %q for every event",
+			pattern, TheRest)
+	}
+	return nil
+}
+
+// The events a provider says about its consumers (novox/hq ADR 0224): a consumer it has failed
+// without one success for minutes, and that consumer succeeding again or being withdrawn. The
+// controller follows them from every module and `status` names a consumer failing until it recovers.
+//
+// **And what becomes of a consumer the mesh stopped asking for** (novox/hq ADR 0230): retired — its
+// access disabled and its data kept — after the same answer in five passes, waiting for a person when
+// more would go than the bound allows, re-enabled when asked for again, and deleted only by a person's
+// `cleanup delete`. One event, its `change` saying which.
+const (
+	ProvisionerFailing    = "provisioner.failing"
+	ProvisionerRecovered  = "provisioner.recovered"
+	ProvisionerRetirement = "provisioner.retirement"
+)
+
+// ProvisionerEvents are all three, in the order they are said.
+var ProvisionerEvents = []string{ProvisionerFailing, ProvisionerRecovered, ProvisionerRetirement}
+
+// EmitsAll is every event a module may publish: what it declares and, for a module that receives
+// contributions — a provider, running a provisioner over them — the provider's standing events.
+//
+// **Derived, not declared**, because they are the mesh's rule about every provider rather than
+// anything one module chose to say: a provider whose manifest forgot them would fail its consumers
+// as silently as on 2026-10-05, with its announcement refused by the bus (novox/hq issue 179). Every
+// grant of a module's publishing reads this, never the declared list alone.
+func (m Manifest) EmitsAll() []string {
+	out := append([]string(nil), m.Emits...)
+	if len(m.Receives) == 0 {
+		return out
+	}
+	for _, e := range ProvisionerEvents {
+		if !slices.Contains(out, e) {
+			out = append(out, e)
+		}
+	}
+	return out
+}

go/catalogue/file_references_test.go

@@ -0,0 +1,10 @@
+package catalogue
+
+import "testing"
+
+// 1694/AC5: the capability a node-engine reports for files by digest (novox/hq ADR 0486 §5) is a known one.
+func TestFileReferencesIsAKnownCapability(t *testing.T) {
+	if !oneOf(KnownCapabilities, "file-references") {
+		t.Fatal("file-references is not a known capability")
+	}
+}

go/catalogue/files.go

@@ -0,0 +1,163 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"path"
+	"strings"
+)
+
+// A node's files, read and managed (novox/hq ADR 0394, issue 900; superseding ADR 0310; hq to-be 41 WP9).
+//
+// **One seat for every file on a node.** The holder runs as the tool runner's account, the node's operator
+// account (ADR 0394 §2), and reaches further through `sudo -n` where that account's rights do not. It refuses by
+// name the places a secret is kept (reads only, ADR 0394 §7) and the paths a module owns, unless a write names a reason (`override`).
+// node-reads stays beside it until mesh-files is assigned on every node (ADR 0394 §9); it goes in the next
+// delivery.
+
+// FilesSeat is the role that reads and manages a node's files and accounts (novox/hq ADR 0394).
+const FilesSeat = "node-files"
+
+// FilesOwnedPaths is the word the holder of node-files is given beside the secret places: a JSON object from
+// each absolute path a module owns on its node to "module (tool to use)" (novox/hq ADR 0394 §5).
+const FilesOwnedPaths = "MESH_OWNED_PATHS"
+
+const (
+	filesAsAccount = "as the node's operator account, through sudo -n where its rights do not reach; a place a " +
+		"secret is kept, or a known credential file, is refused by name"
+	overrideWord = "a reason, to change a path a module owns anyway (optional)"
+)
+
+// filesVerbs is the contract every holder of node-files serves (novox/hq ADR 0394 §1): the reads of node-reads,
+// with their descriptions restated for the operator's account, and the writes.
+func filesVerbs() []Verb {
+	var verbs []Verb
+	for _, v := range readsVerbs() {
+		v.Description = strings.Replace(v.Description,
+			"Read as the holder's own account, which holds no secret: a component it may not reach says so.",
+			"", 1)
+		v.Description = strings.TrimSpace(v.Description) + " Read " + filesAsAccount + "."
+		verbs = append(verbs, v)
+	}
+	write := func(name, description string, in map[string]string, required []string, optional []string, replaces ...string) Verb {
+		in["reason"] = "why the file is changed, for the audit trail"
+		in["override"] = overrideWord
+		return Verb{Name: name, Description: description + " Refuses a path a module owns " +
+			"unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
+			Input: schema(in, append(required, "reason"), append(optional, "override")...), Replaces: replaces}
+	}
+	return append(verbs,
+		write("write", "Write one text file whole, replacing what it holds; the old content goes to the node's trash.",
+			map[string]string{"path": "an absolute path", "content": "the text to write",
+				"mode": "the file's mode, such as 0644 (optional)"},
+			[]string{"path", "content"}, []string{"mode"}, "tee", ">"),
+		write("copy", "Copy a file or directory to a path on this node. A target on another node (<node>:/path) is "+
+			"refused: copying between nodes comes in step 2 (issue 903). An existing target is overwritten, the old one "+
+			"kept in the node's trash for 7 days.",
+			map[string]string{"from": "an absolute path", "to": "an absolute path on this node"},
+			[]string{"from", "to"}, nil, "cp", "cp -a", "ssh <node> cp"),
+		write("move", "Move or rename a file or directory. A target on another node is refused: copying between nodes "+
+			"comes in step 2 (issue 903). An existing target is overwritten, the old one kept in the node's trash for 7 days.",
+			map[string]string{"from": "an absolute path", "to": "an absolute path"},
+			[]string{"from", "to"}, nil, "mv"),
+		write("delete", "Delete a file or directory into the node's trash, where restore can bring it back.",
+			map[string]string{"path": "an absolute path", "recursive": "\"true\": delete a directory with what it holds"},
+			[]string{"path"}, []string{"recursive"}, "rm", "rm -r"),
+		write("mkdir", "Make a directory.",
+			map[string]string{"path": "an absolute path", "parents": "\"true\": make the missing parents too"},
+			[]string{"path"}, []string{"parents"}, "mkdir", "mkdir -p"),
+		write("chmod", "Change the mode of a file or directory.",
+			map[string]string{"path": "an absolute path", "mode": "the mode, such as 0644 or u+x",
+				"recursive": "\"true\": also everything under a directory"},
+			[]string{"path", "mode"}, []string{"recursive"}, "chmod"),
+		write("chown", "Change the owner and group of a file or directory.",
+			map[string]string{"path": "an absolute path", "owner": "an account's name or number",
+				"group": "a group's name or number (optional)", "recursive": "\"true\": also everything under a directory"},
+			[]string{"path", "owner"}, []string{"group", "recursive"}, "chown", "chgrp"),
+		Verb{Name: "upload", Description: "Send one file of this node into a bucket of the object store, over a short signed link " +
+			"and never over the bus; answers the key (the file's SHA-256 when none is given), the size and the SHA-256. " +
+			"At most 100 MiB. A place a secret is kept, a known credential file, or a link to one is refused by name, " +
+			"before anything is sent. Read " + filesAsAccount + ".",
+			Input: schema(map[string]string{"path": "an absolute path to a file", "bucket": "the bucket the file goes into",
+				"key": "the object's key (optional; the file's SHA-256 when not given)"}, []string{"path", "bucket"})},
+		// download is a plain Verb, not through write(): write() types its optional arguments as true/false
+		// switches, which a hash and a reason are not (issue 1719).
+		Verb{Name: "download", Description: "Write one object of a bucket to a file of this node, over a short signed link and " +
+			"never over the bus; the old file goes to the node's trash. At most 100 MiB. The bytes must hash to sha256, or to " +
+			"the key when the key is a SHA-256; otherwise no file is written. Refuses a path a module owns " +
+			"unless override names a reason; done as the node's operator account, through sudo -n where its rights do not reach.",
+			Input: schema(map[string]string{"bucket": "the bucket", "key": "the object's key", "path": "an absolute path",
+				"sha256":   "the SHA-256 the bytes must have (optional; the key when that is a SHA-256)",
+				"reason":   "why the file is changed, for the audit trail",
+				"override": overrideWord}, []string{"bucket", "key", "path", "reason"})},
+		Verb{Name: "trash", Description: "What the node's trash holds: each deleted or replaced item with its id, " +
+			"original path and when it went.",
+			Input: schema(map[string]string{}, nil), Replaces: []string{"ls ~/.local/share/Trash"}},
+		write("restore", "Put an item of the node's trash back where it was; refuses when something is there now.",
+			map[string]string{"id": "an id from trash"}, []string{"id"}, nil, "trash-restore"),
+	)
+}
+
+// FilesHolderProblems is what a holder of node-files is held to (novox/hq ADR 0394 §2): it runs as the tool
+// runner's account, the node's operator account, so it declares no runs-as.
+func FilesHolderProblems(m Manifest) []string {
+	if !m.ClaimsSeat(FilesSeat) || m.RunsAs == "" {
+		return nil
+	}
+	return []string{fmt.Sprintf("%s claims %s and declares runs-as %q: its holder runs as the tool runner's account, "+
+		"the node's operator account (novox/hq ADR 0394 §2)", m.Module, FilesSeat, m.RunsAs)}
+}
+
+// ownedPaths is every path a module owns on this node, as the holder is told (novox/hq ADR 0394 §5): the
+// paths every seat declares (ADR 0287) with the module holding the seat here, and the paths and files each
+// module's manifest places (declaredPaths). A seat's path wins where both name one.
+func (r Resolution) ownedPaths() map[string]string {
+	owned := map[string]string{}
+	for _, m := range r.Modules {
+		for _, p := range sortedKeys(declaredPaths(m)) {
+			owned[p] = m.Module + " (its own tools)"
+		}
+	}
+	for _, s := range Seats() {
+		for _, sp := range s.Paths {
+			for _, m := range r.Modules {
+				if m.ClaimsSeat(s.Name) && declaresPath(m, path.Clean(sp.Path)) {
+					owned[sp.Path] = m.Module + " (" + s.Name + ")"
+				}
+			}
+		}
+	}
+	return owned
+}
+
+// filesWords is what the holder of node-files is given beside its own words: the node's secret places and the
+// paths modules own here.
+func (r Resolution) filesWords(m Manifest, words map[string]string, with Rendering) (map[string]string, error) {
+	if !m.ClaimsSeat(FilesSeat) {
+		return words, nil
+	}
+	places, err := r.secretPlaces(with)
+	if err != nil {
+		return nil, err
+	}
+	places2, err := json.Marshal(places)
+	if err != nil {
+		return nil, err
+	}
+	owned, err := json.Marshal(r.ownedPaths())
+	if err != nil {
+		return nil, err
+	}
+	if words == nil {
+		words = map[string]string{}
+	}
+	for _, w := range []string{ReadsSecretPlaces, FilesOwnedPaths} {
+		if _, has := words[w]; has {
+			return nil, fmt.Errorf("%s gives its own %s; the node's secret places and owned paths are the mesh's to "+
+				"say (novox/hq ADR 0394 §5)", m.Module, w)
+		}
+	}
+	words[ReadsSecretPlaces] = string(places2)
+	words[FilesOwnedPaths] = string(owned)
+	return words, nil
+}

go/catalogue/files_test.go

@@ -0,0 +1,203 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"sort"
+	"strings"
+	"testing"
+)
+
+// issue 900, novox/hq ADR 0394 §1: node-files is a node seat whose verbs say the commands they replace.
+func TestNodeFilesIsANodeSeatWithEveryVerbOfADR0394(t *testing.T) {
+	s, ok := SeatNamed(FilesSeat)
+	if !ok {
+		t.Fatalf("the mesh defines no seat %s", FilesSeat)
+	}
+	if s.Scope != ScopeNode || s.Delivers != "" || !strings.Contains(s.Decision, "ADR 0394") {
+		t.Errorf("%s: scope %q, delivers %q, decision %q", FilesSeat, s.Scope, s.Delivers, s.Decision)
+	}
+	have := map[string]bool{}
+	replaced := map[string]string{}
+	for _, v := range s.Serves {
+		have[v.Name] = true
+		if v.Optional {
+			t.Errorf("%s.%s is optional", FilesSeat, v.Name)
+		}
+		// upload and download (ADR 0468 §9, issue 1718) move bytes through the object store: no command is theirs.
+		if len(v.Replaces) == 0 && v.Name != "upload" && v.Name != "download" {
+			t.Errorf("%s.%s says nothing it replaces", FilesSeat, v.Name)
+		}
+		for _, c := range v.Replaces {
+			replaced[c] = v.Name
+		}
+	}
+	for _, name := range []string{"stat", "readlink", "list", "read", "search", "account", "write", "copy", "move",
+		"delete", "mkdir", "chmod", "chown", "upload", "download", "trash", "restore"} {
+		if !have[name] {
+			t.Errorf("%s serves no verb %s", FilesSeat, name)
+		}
+	}
+	for command, verb := range map[string]string{"cat": "read", "tee": "write", "cp": "copy", "mv": "move",
+		"rm": "delete", "mkdir -p": "mkdir", "chmod": "chmod", "chgrp": "chown"} {
+		if replaced[command] != verb {
+			t.Errorf("%q is replaced by %q, want %s.%s", command, replaced[command], FilesSeat, verb)
+		}
+	}
+}
+
+// issue 900, ADR 0394 §2: a holder of node-files runs as the tool runner's account, so it declares no runs-as.
+func TestAHolderOfNodeFilesDeclaringRunsAsIsRefused(t *testing.T) {
+	p := FilesHolderProblems(Manifest{Module: "files", RunsAs: "mesh-files", Claims: []Claim{{Name: FilesSeat}}})
+	if len(p) != 1 || !strings.Contains(p[0], "0394") || !strings.Contains(p[0], "runs-as") {
+		t.Errorf("a holder declaring runs-as was not refused: %v", p)
+	}
+	if p := FilesHolderProblems(Manifest{Module: "files", Claims: []Claim{{Name: FilesSeat}}}); len(p) != 0 {
+		t.Errorf("a holder declaring none was refused: %v", p)
+	}
+	if p := FilesHolderProblems(Manifest{Module: "other", RunsAs: "x"}); len(p) != 0 {
+		t.Errorf("a non-holder was judged: %v", p)
+	}
+}
+
+// issue 900, ADR 0394 §4: the holder is told the secret places and the paths modules own on its node.
+func TestTheHolderOfNodeFilesIsToldSecretPlacesAndOwnedPaths(t *testing.T) {
+	files := Manifest{Module: "files", Version: "1", Claims: []Claim{{Name: FilesSeat}},
+		OwnSecrets: OwnSecrets{"broker": {Path: "/var/lib/files/broker"}}}
+	host := Manifest{Module: "hostnames", Version: "1", Claims: []Claim{{Name: "node-hostname"}},
+		Resources: []map[string]any{{"id": "hosts", "type": "file", "path": "/etc/hosts"}}}
+	app := Manifest{Module: "app", Version: "1",
+		Resources: []map[string]any{{"id": "conf", "type": "file", "path": "/etc/app/app.conf"}}}
+	r := Resolution{Node: "anchor", Modules: []Manifest{files, host, app}}
+	words, err := r.filesWords(files, nil, Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var places []string
+	if err := json.Unmarshal([]byte(words[ReadsSecretPlaces]), &places); err != nil || len(places) == 0 {
+		t.Errorf("no secret places: %v %v", err, words)
+	}
+	var owned map[string]string
+	if err := json.Unmarshal([]byte(words[FilesOwnedPaths]), &owned); err != nil {
+		t.Fatalf("no owned paths: %v (%v)", err, words)
+	}
+	if !strings.HasPrefix(owned["/etc/hosts"], "hostnames") {
+		t.Errorf("/etc/hosts is owned by %q, want hostnames", owned["/etc/hosts"])
+	}
+	if !strings.HasPrefix(owned["/etc/app/app.conf"], "app") {
+		t.Errorf("a placed file is owned by %q, want app", owned["/etc/app/app.conf"])
+	}
+	if w, _ := r.filesWords(app, nil, Rendering{}); w[FilesOwnedPaths] != "" {
+		t.Error("a module not holding node-files is told the owned paths")
+	}
+}
+
+// issue 900: restore, like every write verb, takes a reason and an override.
+func TestNodeFilesRestoreTakesIdAndReason(t *testing.T) {
+	s, _ := SeatNamed(FilesSeat)
+	for _, v := range s.Serves {
+		if v.Name != "restore" {
+			continue
+		}
+		props, _ := v.Input["properties"].(map[string]any)
+		for _, p := range []string{"id", "reason", "override"} {
+			if _, has := props[p]; !has {
+				t.Errorf("restore has no input %s", p)
+			}
+		}
+		if req, _ := v.Input["required"].([]string); strings.Join(req, ",") != "id,reason" {
+			t.Errorf("restore requires %v, want id and reason", req)
+		}
+		return
+	}
+	t.Error("no restore verb")
+}
+
+// 1718/AC1: node-files names upload and download, in mesh-files' order, before trash.
+func TestNodeFilesNamesUploadAndDownloadBeforeTrash(t *testing.T) {
+	s, _ := SeatNamed(FilesSeat)
+	var names []string
+	for _, v := range s.Serves {
+		names = append(names, v.Name)
+	}
+	joined := strings.Join(names, ",")
+	if !strings.Contains(joined, "chown,upload,download,trash") {
+		t.Errorf("1718/AC1: node-files' verbs are %s, want upload and download between chown and trash", joined)
+	}
+}
+
+// 1718/AC2: a holder serving every verb including upload and download is accepted; one naming a verb outside the
+// contract is still refused, and one leaving upload out is refused.
+func TestAHolderOfNodeFilesServesUploadAndDownloadAndNothingElse(t *testing.T) {
+	s, _ := SeatNamed(FilesSeat)
+	var verbs []string
+	for _, v := range s.Serves {
+		verbs = append(verbs, v.Name)
+	}
+	hold := func(serves []string) error {
+		return CanHold(Manifest{Module: "mesh-files", Version: "1",
+			Claims: []Claim{{Name: FilesSeat, Scope: ScopeNode, Serves: serves}}}, s)
+	}
+	if err := hold(verbs); err != nil {
+		t.Errorf("1718/AC2: a holder serving every verb was refused: %v", err)
+	}
+	if err := hold(append(append([]string{}, verbs...), "sync")); err == nil || !strings.Contains(err.Error(), "does not promise") {
+		t.Errorf("1718/AC2: a verb outside the contract was accepted: %v", err)
+	}
+	var without []string
+	for _, v := range verbs {
+		if v != "upload" {
+			without = append(without, v)
+		}
+	}
+	if err := hold(without); err == nil || !strings.Contains(err.Error(), "upload") {
+		t.Errorf("1718/AC2: a holder leaving upload out was accepted: %v", err)
+	}
+}
+
+// 1718/AC3: upload requires path and bucket; download requires bucket, key, path and reason; sha256, key (upload)
+// and override are plain strings, not true/false switches.
+func TestNodeFilesUploadAndDownloadInputs(t *testing.T) {
+	s, _ := SeatNamed(FilesSeat)
+	want := map[string]struct {
+		required string
+		strs     []string
+	}{
+		"upload":   {"path,bucket", []string{"path", "bucket", "key"}},
+		"download": {"bucket,key,path,reason", []string{"bucket", "key", "path", "sha256", "reason", "override"}},
+	}
+	seen := 0
+	for _, v := range s.Serves {
+		w, ok := want[v.Name]
+		if !ok {
+			continue
+		}
+		seen++
+		req, _ := v.Input["required"].([]string)
+		got := append([]string{}, req...)
+		sortStrings(got)
+		exp := strings.Split(w.required, ",")
+		sortStrings(exp)
+		if strings.Join(got, ",") != strings.Join(exp, ",") {
+			t.Errorf("1718/AC3: %s requires %v, want %s", v.Name, req, w.required)
+		}
+		props, _ := v.Input["properties"].(map[string]any)
+		if len(props) != len(w.strs) {
+			t.Errorf("1718/AC3: %s has %d inputs, want %v", v.Name, len(props), w.strs)
+		}
+		for _, name := range w.strs {
+			p, has := props[name].(map[string]any)
+			if !has {
+				t.Errorf("1718/AC3: %s has no input %s", v.Name, name)
+				continue
+			}
+			if _, enum := p["enum"]; enum || p["type"] != "string" {
+				t.Errorf("1718/AC3: %s input %s is %v, want a plain string", v.Name, name, p)
+			}
+		}
+	}
+	if seen != 2 {
+		t.Errorf("1718/AC3: found %d of upload and download", seen)
+	}
+}
+
+func sortStrings(s []string) { sort.Strings(s) }

go/catalogue/filtering_foundation_test.go

@@ -0,0 +1,58 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The mesh's own ports survive a ruleset derived from modules that do not mention them.
+//
+// **The firewall is computed from what modules declare they listen on, and the foundation is not a
+// module** (novox/hq 04-ISSUES/052). So the broker's port — the one every machine dials to enrol
+// and to receive every declaration it is ever sent — was absent from every ruleset the mesh ever
+// generated, and nothing caught it: a mesh of one never dials its own broker across the network,
+// so the ruleset looks complete right up until a second machine tries to join and is refused by
+// the packet filter, during enrolment, before the mesh can report anything about it.
+func TestTheBrokersPortIsOpenedThoughNoModuleDeclaresIt(t *testing.T) {
+	const brokerPort = 5671
+
+	// A machine on the private network, with one ordinary module rule, and nothing that mentions
+	// the broker — which is every machine.
+	rules := []Rule{{Port: 8080, From: FromMesh, Because: []string{"some-module"}}}
+	out := AsNftables(rules, []string{"10.42.0.1"}, false, []int{brokerPort}, nil, "mesh0")
+
+	if !strings.Contains(out, "tcp dport 5671 accept") {
+		t.Fatalf("the broker's port is not opened, so no machine could enrol:\n%s", out)
+	}
+
+	// From anywhere, deliberately: a node enrols BEFORE it has an address on the private network,
+	// so a rule narrowed to that network would close the door being knocked on.
+	for _, line := range strings.Split(out, "\n") {
+		if strings.Contains(line, "5671") && strings.Contains(line, "saddr") {
+			t.Fatalf("the broker's port is narrowed to the private network, which a machine that "+
+				"has not yet enrolled is not on:\n%s", line)
+		}
+	}
+
+	// And forwarded, not only accepted on input: the broker is a published container port, so a
+	// cross-node dial is redirected and forwarded and never reaches the input chain. Without this
+	// a joined node reaches the broker only until its first connection's conntrack entry drops —
+	// which a broker restart (adopting the foundation's broker) causes — and then never receives
+	// another declaration (novox/hq issue 063).
+	if !strings.Contains(out, "ct original proto-dst 5671 accept") {
+		t.Fatalf("the broker's port is not forwarded, so a DNAT'd broker is unreachable "+
+			"cross-node after it restarts:\n%s", out)
+	}
+}
+
+// And a mesh that was never told about a broker still gets a ruleset, rather than an empty one or
+// a panic. A control plane in that state cannot issue tokens either, which is where it surfaces.
+func TestNoBrokerMeansNoFoundationRuleRatherThanNoRuleset(t *testing.T) {
+	out := AsNftables(nil, []string{"10.42.0.1"}, false, nil, nil, "mesh0")
+	if !strings.Contains(out, "table inet mesh") {
+		t.Fatalf("no ruleset at all:\n%s", out)
+	}
+	if strings.Contains(out, "never derived, never closed\n\t\ttcp dport") {
+		t.Fatalf("a foundation rule was written for a mesh with no broker:\n%s", out)
+	}
+}

go/catalogue/filtering_test.go

@@ -0,0 +1,920 @@
+package catalogue
+
+import (
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+)
+
+// A manifest key nothing reads is worse than a key that is refused: five HAL manifests carried
+// `scope:`, which read as a restriction and restricted nothing (novox/hq 04-ISSUES/003). The host's
+// declaration parser has always refused unknown keys; manifests never did.
+func TestAManifestKeyNothingReadsIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"web","scope":"mesh"}`))
+	if err == nil {
+		t.Fatal("a manifest with a key nothing reads was accepted, which is how scope: survived")
+	}
+	if !strings.Contains(err.Error(), "scope") {
+		t.Fatalf("refused without naming the key, which leaves the author guessing: %v", err)
+	}
+}
+
+// The same discipline must not refuse a manifest that is merely ordinary.
+func TestAnOrdinaryManifestIsStillAccepted(t *testing.T) {
+	m, err := ParseManifest([]byte(
+		`{"module":"web","listens":[{"port":443,"from":"anywhere","why":"the site"}]}`))
+	if err != nil {
+		t.Fatalf("an ordinary manifest was refused: %v", err)
+	}
+	if len(m.Listens) != 1 || m.Listens[0].At() != "tcp" {
+		t.Fatalf("listens did not survive parsing: %+v", m.Listens)
+	}
+}
+
+// A rule with no source is open, and must say so rather than appear to restrict something.
+func TestAPortWithNoSourceIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"web","listens":[{"port":443}]}`))
+	if err == nil {
+		t.Fatal("a port that never said who may reach it was accepted; it reads as a restriction")
+	}
+	if !strings.Contains(err.Error(), "from where") {
+		t.Fatalf("refused without saying what is missing: %v", err)
+	}
+}
+
+func TestASourceNobodyDefinedIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"web","listens":[{"port":443,"from":"lan"}]}`))
+	if err == nil {
+		t.Fatal("a source the mesh cannot render was accepted, and would be silently dropped")
+	}
+}
+
+// The derivation is over the whole node, not one module.
+func TestTheRuleSetIsEveryAssignedModulesPorts(t *testing.T) {
+	r := Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+	}}
+	rules := mustFilter(t, r, nil)
+	if len(rules) != 2 {
+		t.Fatalf("a node's rule set lost a module's ports: %+v", rules)
+	}
+	if rules[0].Port != 443 || rules[1].Port != 5432 {
+		t.Fatalf("rules are not in a stable order, so every diff is unreadable: %+v", rules)
+	}
+}
+
+// Every rule names what caused it, and both causes survive.
+func TestTwoModulesWantingOnePortAreBothNamed(t *testing.T) {
+	r := Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere, Why: "the site"}}},
+		{Module: "board", Listens: []Listening{{Port: 443, From: FromEverywhere, Why: "the board"}}},
+	}}
+	rules := mustFilter(t, r, nil)
+	if len(rules) != 1 {
+		t.Fatalf("one port became %d rules", len(rules))
+	}
+	if len(rules[0].Because) != 2 {
+		t.Fatalf("a module that wanted this port open is not named: %+v", rules[0])
+	}
+	// The consequence, which is the reason this matters: removing web must not read as closing 443.
+	nft := AsNftables(rules, nil, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "web") || !strings.Contains(nft, "board") {
+		t.Fatalf("the rendered rule set does not name both sources:\n%s", nft)
+	}
+}
+
+// Widening, and only widening.
+func TestAPortOpenToEveryoneIsNotAlsoRestrictedToTheMesh(t *testing.T) {
+	r := Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+		{Module: "board", Listens: []Listening{{Port: 443, From: FromMesh}}},
+	}}
+	rules := mustFilter(t, r, nil)
+	if len(rules) != 1 {
+		t.Fatalf("the same port was rendered twice, once restricting nothing: %+v", rules)
+	}
+	if rules[0].From != FromEverywhere {
+		t.Fatalf("the narrower rule won, which closes a port a module asked to open: %+v", rules[0])
+	}
+	if len(rules[0].Because) != 2 {
+		t.Fatalf("the covered module was dropped along with its rule: %+v", rules[0])
+	}
+}
+
+// What is not declared is closed.
+func TestWhatNoModuleDeclaredIsClosed(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}, nil), []string{"198.51.100.2"}, false, nil, nil, "mesh0")
+	// Naming the chain, not just the policy: the forward chain drops too, and an assertion on
+	// "policy drop" alone passes while the input chain accepts everything. It did, once, here.
+	if !strings.Contains(nft, "type filter hook input priority filter; policy drop;") {
+		t.Fatalf("the input chain does not drop by default, so nothing is filtered:\n%s", nft)
+	}
+	// Some port nothing asked for. **Not 22**, which this used to use: ssh is now the one line in
+	// the chain that nothing derives, because a mesh that has been assigned almost nothing computes
+	// a firewall that shuts the port used to fix it (novox/hq issue 047).
+	if strings.Contains(nft, "dport 9999") {
+		t.Fatalf("a port no module declared was opened:\n%s", nft)
+	}
+	// Dropping by default must not mean unreachable: the node's own outbound link to the broker
+	// is the one connection the whole mesh runs on, and it is a reply to something it started.
+	if !strings.Contains(nft, "ct state established,related accept") {
+		t.Fatalf("a node applying this would lose its own link to the mesh:\n%s", nft)
+	}
+	if !strings.Contains(nft, "iif lo accept") {
+		t.Fatalf("loopback is filtered, which breaks everything on the machine:\n%s", nft)
+	}
+}
+
+// Loading it twice must be the same as loading it once, and must not disturb anything else.
+//
+// `flush ruleset` would do the first and not the second: it empties every table on the machine,
+// including the ones the container runtime writes for its bridges.
+func TestReloadingReplacesOnlyTheMeshsOwnRules(t *testing.T) {
+	nft := AsNftables(nil, nil, false, nil, nil, "mesh0")
+	if strings.Contains(nft, "flush ruleset") {
+		t.Fatalf("loading the rule set empties every table on the machine:\n%s", nft)
+	}
+	if !strings.Contains(nft, "delete table inet mesh") {
+		t.Fatalf("loading it a second time would add to what is there rather than replace it:\n%s", nft)
+	}
+	// The delete must not fail on a machine that has never loaded one, or the service does not
+	// start and the machine filters nothing while reporting a configuration error.
+	if !strings.Contains(nft, "table inet mesh {}\ndelete table inet mesh") {
+		t.Fatalf("the delete has nothing to delete on a machine loading this for the first time:\n%s", nft)
+	}
+}
+
+// The rule set governs what is forwarded too, or it does not govern container ports at all.
+//
+// **This reverses an earlier decision, and keeps the thing that decision was protecting.** There was
+// no forward chain, on the reasoning that dropping there stops container traffic the runtime
+// allowed — every container on the node, control plane included. That much is true. What it missed
+// is that a published port is redirected and then forwarded, so it never reaches the input chain,
+// and a firewall without a forward chain is silent about exactly the ports worth protecting
+// (novox/hq issue 047).
+//
+// So the chain exists and denies by default, and the runtime's own networks are allowed explicitly
+// — which is how the system being replaced has been doing it on these machines for months.
+func TestWhatIsForwardedIsGovernedToo(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "hook forward priority filter; policy drop") {
+		t.Fatalf("forwarded traffic is not governed, so container ports are open:\n%s", nft)
+	}
+}
+
+// And this machine's own guests keep working, which is the whole reason the chain was left out
+// before — by not being mentioned (novox/hq ADR 0140).
+//
+// It used to be done by naming the address ranges they sit on: two fixed here and the rest recorded
+// per machine. That list broke a workstation's containers at a flip and could not be made correct,
+// because a range describes one machine and cannot tell a network the mesh made from one a
+// predecessor left behind. What replaced it is a single line about the links traffic arrives on.
+func TestThisMachinesOwnGuestsKeepWorkingWithoutBeingNamed(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, []string{"eth0"}, "mesh0")
+	if !strings.Contains(nft, `iifname != { "eth0", "mesh0" } accept`) {
+		t.Fatalf("what did not arrive from outside is not accepted, so this machine's own guests "+
+			"reach nothing:\n%s", nft)
+	}
+}
+
+// No address of a machine's own networks appears anywhere in a rendered filter.
+//
+// This is the assertion that fails against the previous behaviour, and it is why it is written on
+// the text rather than on an outcome: the two ranges were a constant in this file, so nothing but
+// reading the output catches one creeping back in.
+func TestNoNetworkOfTheMachinesOwnIsNamed(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, []string{"eth0"}, "mesh0")
+	for _, gone := range []string{"172.16.0.0/12", "192.168.128.0/17", "saddr 192.168", "saddr 172."} {
+		if strings.Contains(nft, gone) {
+			t.Fatalf("%q is named, and a range describes one machine and goes stale in silence:\n%s",
+				gone, nft)
+		}
+	}
+}
+
+// **The tunnel is constrained, not treated as inside.**
+//
+// Accepting everything arriving over the private network would make a port nothing declares
+// reachable from every machine in the mesh — the derivation abandoned, and a rule that reads as a
+// restriction while restricting nothing. So the tunnel is named beside the outward links, and
+// traffic arriving on it meets the declared rules like anything else.
+func TestTheTunnelIsConstrainedLikeAnOutwardLink(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, []string{"eth0"}, "mesh0")
+	line := `iifname != { "eth0", "mesh0" } accept`
+	if !strings.Contains(nft, line) {
+		t.Fatalf("the tunnel is not constrained, so an undeclared port is reachable from any "+
+			"machine in the mesh:\n%s", nft)
+	}
+}
+
+// A machine with two links facing outside has both constrained. Asserted on the one line, because a
+// rule covering one and not the other would leave a machine filtering half of what reaches it.
+func TestEveryOutwardLinkIsConstrained(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, []string{"eth0", "wlan0"}, "mesh0")
+	if !strings.Contains(nft, `iifname != { "eth0", "wlan0", "mesh0" } accept`) {
+		t.Fatalf("not every outward link is constrained:\n%s", nft)
+	}
+}
+
+// A guest asks its host for an address and for names, and those two arrive at the input chain. Asked
+// for by the link they arrive on, so a resolver bound anywhere but an outward link keeps answering.
+func TestGuestsMayAskTheirHostForAnAddressAndNames(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, []string{"eth0"}, "mesh0")
+	for _, want := range []string{
+		`iifname != { "eth0", "mesh0" } udp dport { 53, 67 } accept`,
+		`iifname != { "eth0", "mesh0" } tcp dport 53 accept`,
+	} {
+		if !strings.Contains(nft, want) {
+			t.Fatalf("a guest cannot ask its host for an address or a name, which is not a closed "+
+				"port but a network that does not work:\n%s", nft)
+		}
+	}
+}
+
+// With no link named at all the chain denies rather than rendering an empty set, which nftables
+// refuses — and a rule set that does not load is a machine filtering nothing while its unit reports
+// success. Composing a declaration for such a machine is refused upstream; this is the floor.
+func TestNoLinkNamedRendersNoCatchAllRatherThanAnEmptySet(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, false, nil, nil, "")
+	if strings.Contains(nft, "{  }") || strings.Contains(nft, "iifname != {}") {
+		t.Fatalf("an empty set is rendered, which nftables refuses:\n%s", nft)
+	}
+	if !strings.Contains(nft, "hook forward priority filter; policy drop") {
+		t.Fatalf("the forward chain does not deny:\n%s", nft)
+	}
+}
+
+// A machine that has not said which links face outside is sent no filter, and the refusal names the
+// module that would have loaded it so the reader knows what is being withheld.
+func TestAMachineThatNamedNoOutwardLinkIsSentNoFilter(t *testing.T) {
+	r := Resolution{Node: "anchor", Modules: []Manifest{
+		{Module: "nftables", Filtering: &Filtering{Into: "/etc/mesh/filter.nft"}},
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}
+	_, err := r.Declaration(Rendering{Mesh: []string{"198.51.100.2"}, TunnelInterface: "mesh0"})
+	if err == nil {
+		t.Fatal("a machine that named no outward link was sent a filter written around none")
+	}
+	for _, want := range []string{"anchor", "nftables", "face outside"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("the refusal does not say %q: %v", want, err)
+		}
+	}
+}
+
+// And a machine that names none but loads no filter is not refused: there is nothing to write.
+func TestAMachineWithNoFilterModuleIsNotRefused(t *testing.T) {
+	r := Resolution{Node: "anchor", Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}
+	if _, err := r.Declaration(Rendering{Mesh: []string{"198.51.100.2"}}); err != nil {
+		t.Fatalf("a machine that loads no filter was refused one: %v", err)
+	}
+}
+
+// A published port is matched by what the client asked for, not by where the packet ends up.
+//
+// The runtime rewrites the destination before this chain sees it, so a rule naming the published
+// port would match nothing and the port would stay shut while reporting itself open.
+func TestAPublishedPortIsMatchedByWhatWasAskedFor(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 8080, From: FromEverywhere}}},
+	}}, nil), []string{"198.51.100.2"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "ct original proto-dst 8080 accept") {
+		t.Fatalf("the forwarded rule does not match the port a client asked for:\n%s", nft)
+	}
+}
+
+// And a mesh-scoped port stays mesh-scoped when it is reached through the runtime.
+func TestAMeshScopedPortIsMeshScopedWhenForwarded(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+	}}, nil), []string{"198.51.100.2"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "ip saddr { 198.51.100.2 } ct original proto-dst 5432 accept") {
+		t.Fatalf("a mesh-only port is reachable from anywhere once forwarded:\n%s", nft)
+	}
+}
+
+// "From the mesh" is the addresses the mesh actually has.
+func TestFromTheMeshIsTheNodesTheMeshKnows(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+	}}, nil), []string{"198.51.100.2", "198.51.100.3"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "ip saddr { 198.51.100.2, 198.51.100.3 } tcp dport 5432 accept") {
+		t.Fatalf("a mesh-scoped port was not restricted to the mesh's addresses:\n%s", nft)
+	}
+}
+
+// The case that must not be widened silently.
+func TestAMeshPortOnANodeWithNoMeshIsClosedAndSaysSo(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+	}}, nil), nil, false, nil, nil, "mesh0")
+	if strings.Contains(nft, "dport 5432 accept") {
+		t.Fatalf("a port meant for the mesh was opened to everything:\n%s", nft)
+	}
+	if !strings.Contains(nft, "closed") {
+		t.Fatalf("it was closed silently, which is a fault nobody can find:\n%s", nft)
+	}
+}
+
+// A port bound for something else on the same machine must not reach the network.
+func TestAMachineScopedPortIsNotOpened(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "cache", Listens: []Listening{{Port: 6379, From: FromMachine}}},
+	}}, nil), []string{"198.51.100.2"}, false, nil, nil, "mesh0")
+	if strings.Contains(nft, "dport 6379 accept") {
+		t.Fatalf("a port for this machine only was opened to the network:\n%s", nft)
+	}
+}
+
+// The rule set is the machine's, not the asking module's.
+func TestTheModuleAskingForTheRuleSetGetsEveryModulesPorts(t *testing.T) {
+	r := Resolution{Modules: []Manifest{
+		{Module: "firewall", Filtering: &Filtering{Into: "/etc/mesh/filter.nft"}},
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}
+	out, err := r.Declaration(Rendering{Mesh: []string{"198.51.100.2"},
+		OutwardLinks: []string{"eth0"}, TunnelInterface: "mesh0"})
+	if err != nil {
+		t.Fatalf("declaration: %v", err)
+	}
+	var content string
+	for _, res := range out {
+		if res["path"] == "/etc/mesh/filter.nft" {
+			content, _ = res["content"].(string)
+		}
+	}
+	if content == "" {
+		t.Fatal("the module that asked for the rule set did not receive one")
+	}
+	if !strings.Contains(content, "dport 443 accept") {
+		t.Fatalf("the rule set holds only the asking module's ports:\n%s", content)
+	}
+}
+
+func TestAskingForTheRuleSetWithNowhereToPutItIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"firewall","filtering":{"into":""}}`))
+	if err == nil {
+		t.Fatal("a module asked for the rule set and named no path; it would receive nothing")
+	}
+}
+
+// nftables matches the two address families separately, and one set holding both is a syntax
+// error — so the file fails to load, the service reports a fault, and the machine filters nothing.
+func TestAMeshOnBothAddressFamiliesRendersBoth(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+	}}, nil), []string{"198.51.100.2", "2001:db8::2"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "ip saddr { 198.51.100.2 } tcp dport 5432 accept") {
+		t.Fatalf("the machines with v4 addresses were dropped:\n%s", nft)
+	}
+	if !strings.Contains(nft, "ip6 saddr { 2001:db8::2 } tcp dport 5432 accept") {
+		t.Fatalf("the machines with v6 addresses were dropped:\n%s", nft)
+	}
+	// And never in one set, which is the syntax error this exists to avoid.
+	if strings.Contains(nft, "198.51.100.2, 2001:db8::2") {
+		t.Fatalf("both families are in one set, so the file will not load:\n%s", nft)
+	}
+}
+
+// The host does not sort, so the order the mesh writes is the order a machine applies.
+//
+// A module's service or container routinely depends on a file the mesh computed — a certificate,
+// a credential, a rule set. Written after the service, the service is applied first, fails, and
+// the next reconcile fixes it. A fault that repairs itself on the second attempt is worse than one
+// that does not: what gets remembered is that it works.
+func TestWhatTheMeshComputesIsAppliedBeforeWhatTheModuleDeclared(t *testing.T) {
+	r := Resolution{Modules: []Manifest{{
+		Module:    "firewall",
+		Filtering: &Filtering{Into: "/etc/nftables.conf"},
+		Resources: []map[string]any{
+			{"id": "load", "type": "service", "unit": "nftables.service", "state": "running",
+				"restart-on": []any{"filtering"}},
+		},
+	}}}
+	out, err := r.Declaration(Rendering{Mesh: []string{"198.51.100.2"},
+		OutwardLinks: []string{"eth0"}, TunnelInterface: "mesh0"})
+	if err != nil {
+		t.Fatalf("declaration: %v", err)
+	}
+	var order []string
+	for _, res := range out {
+		order = append(order, fmt.Sprint(res["id"]))
+	}
+	if len(order) != 2 {
+		t.Fatalf("expected the rule set and the service, got %v", order)
+	}
+	if order[0] != "firewall.filtering" {
+		t.Fatalf("the service is applied before the file it reflects: %v", order)
+	}
+}
+
+// The same, for a module whose resources are computed elsewhere — that branch replaces the
+// module's resources wholesale, and merging in the wrong place would throw away its credentials.
+func TestAComputedModuleStillGetsWhatTheMeshMadeForIt(t *testing.T) {
+	r := Resolution{Modules: []Manifest{{
+		Module: "networking", Computed: "mesh-network",
+		OwnSecrets: OwnSecrets{"key": {Path: "/var/lib/mesh/key"}},
+	}}}
+	out, err := r.Declaration(Rendering{
+		Needed:     map[string]map[string]string{"networking": {"key": "sealed"}},
+		Generators: map[string]Generator{"mesh-network": computedOnce{}},
+	})
+	if err != nil {
+		t.Fatalf("declaration: %v", err)
+	}
+	var ids []string
+	for _, res := range out {
+		ids = append(ids, fmt.Sprint(res["id"]))
+	}
+	if len(ids) == 0 || ids[0] != "networking."+NeedID("key") {
+		t.Fatalf("a computed module lost the secret the mesh made for it, or applies it late: %v", ids)
+	}
+}
+
+type computedOnce struct{}
+
+func (computedOnce) Resources(string) ([]map[string]any, bool, error) {
+	return []map[string]any{{"id": "wg", "type": "file", "path": "/etc/wireguard/wg0.conf",
+		"content": "x", "mode": "0600"}}, true, nil
+}
+
+// A consumer bound to something answered on its own machine still has to be told where it is.
+//
+// The location is a fact nobody needs — "it is here" — and everything beside it is not: the
+// binding carries what the provider said a consumer must know, which is the port. A build machine
+// sharing a node with the registry it pushes to sat in a loop saying it could not read its own
+// binding, because none was written.
+func TestSomethingAnsweredOnThisMachineIsStillBound(t *testing.T) {
+	r := Resolution{
+		Node: "anchor", At: "anchor.internal",
+		Modules: []Manifest{
+			{Module: "registry", Provides: []Offer{{Name: "artifact-store", Scope: ScopeMesh}},
+				Serves: map[string]map[string]any{"artifact-store": {"port": 5000}}},
+			{Module: "builder", Requires: []string{"artifact-store"},
+				Binds: map[string]string{"artifact-store": "/var/lib/builder/store.json"}},
+		},
+	}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatalf("declaration: %v", err)
+	}
+	var content string
+	for _, res := range out {
+		if res["path"] == "/var/lib/builder/store.json" {
+			content, _ = res["content"].(string)
+		}
+	}
+	if content == "" {
+		t.Fatal("nothing was written, so the consumer cannot find a provider on its own machine")
+	}
+	if !strings.Contains(content, "5000") {
+		t.Fatalf("the binding does not carry the port, which is the part nobody can guess:\n%s", content)
+	}
+	if !strings.Contains(content, "anchor.internal") {
+		t.Fatalf("the binding does not say where to reach it:\n%s", content)
+	}
+}
+
+// And a machine not on the private network still reaches itself.
+func TestAMachineOffTheNetworkIsBoundToItselfByAnAddressThatWorks(t *testing.T) {
+	r := Resolution{
+		Node: "alone",
+		Modules: []Manifest{
+			{Module: "registry", Provides: []Offer{{Name: "artifact-store", Scope: ScopeMesh}},
+				Serves: map[string]map[string]any{"artifact-store": {"port": 5000}}},
+			{Module: "builder", Requires: []string{"artifact-store"},
+				Binds: map[string]string{"artifact-store": "/var/lib/builder/store.json"}},
+		},
+	}
+	out, err := r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatalf("declaration: %v", err)
+	}
+	for _, res := range out {
+		if res["path"] != "/var/lib/builder/store.json" {
+			continue
+		}
+		content, _ := res["content"].(string)
+		if !strings.Contains(content, "127.0.0.1") {
+			t.Fatalf("bound by a name nothing on this machine resolves:\n%s", content)
+		}
+		return
+	}
+	t.Fatal("nothing was written")
+}
+
+// mustFilter is the rule set, refusing to continue if it could not be computed.
+func mustFilter(t *testing.T, r Resolution, computed map[string]Generator) []Rule {
+	t.Helper()
+	rules, err := r.Filtering(computed, nil, nil)
+	if err != nil {
+		t.Fatalf("no rule set could be computed: %v", err)
+	}
+	return rules
+}
+
+// opensOnHub is a generator that says a machine opens a port because of where it sits.
+type opensOnHub struct{ hub string }
+
+func (opensOnHub) Resources(string) ([]map[string]any, bool, error) { return nil, true, nil }
+
+func (o opensOnHub) Listens(node string) ([]Listening, error) {
+	if node != o.hub {
+		return nil, nil
+	}
+	return []Listening{{Port: 51820, Protocol: "udp", From: FromEverywhere,
+		Why: "the private network"}}, nil
+}
+
+// cannotSay is a generator that does not know what a machine opens.
+type cannotSay struct{}
+
+func (cannotSay) Resources(string) ([]map[string]any, bool, error) { return nil, true, nil }
+func (cannotSay) Listens(string) ([]Listening, error) {
+	return nil, errors.New("this machine's endpoint has no port in it")
+}
+
+// A computed module contributes listens the way it contributes resources.
+//
+// A static field is one answer for every machine that runs the module, and a hub's own port is
+// not one of those: the machine that most needs filtering — the one facing the public internet —
+// is exactly the one a static answer gets wrong.
+func TestAComputedModuleOpensThePortItsMachineNeeds(t *testing.T) {
+	network := Manifest{Module: "networking", Computed: "mesh-network"}
+	gens := map[string]Generator{"mesh-network": opensOnHub{hub: "anchor"}}
+
+	onHub := mustFilter(t, Resolution{Node: "anchor", Modules: []Manifest{network}}, gens)
+	if len(onHub) != 1 || onHub[0].Port != 51820 {
+		t.Fatalf("the hub's own way onto the private network was not opened: %+v", onHub)
+	}
+	if onHub[0].Because[0] != "networking" {
+		t.Fatalf("the rule does not name what caused it: %+v", onHub[0])
+	}
+
+	// And the machine that dials out opens nothing, from the same module.
+	elsewhere := mustFilter(t, Resolution{Node: "laptop", Modules: []Manifest{network}}, gens)
+	if len(elsewhere) != 0 {
+		t.Fatalf("a machine nothing dials opened a port because another machine needed one: %+v",
+			elsewhere)
+	}
+}
+
+// What a module says and what was computed for it are both kept.
+func TestAComputedModulesOwnListensAreNotLost(t *testing.T) {
+	network := Manifest{Module: "networking", Computed: "mesh-network",
+		Listens: []Listening{{Port: 9, From: FromMesh, Why: "something the module always wants"}}}
+	rules := mustFilter(t, Resolution{Node: "anchor", Modules: []Manifest{network}},
+		map[string]Generator{"mesh-network": opensOnHub{hub: "anchor"}})
+	if len(rules) != 2 {
+		t.Fatalf("one of the two sources was dropped: %+v", rules)
+	}
+}
+
+// A generator that cannot say is refused, not read as silence.
+//
+// Closing a port on the evidence of a failure to look is how a machine is severed by a fault
+// somewhere else entirely — and the machine it would sever is the hub.
+func TestAGeneratorThatCannotSayRefusesTheRuleSet(t *testing.T) {
+	_, err := Resolution{Node: "anchor",
+		Modules: []Manifest{{Module: "networking", Computed: "mesh-network"}},
+	}.Filtering(map[string]Generator{"mesh-network": cannotSay{}}, nil, nil)
+	if err == nil {
+		t.Fatal("a machine whose open ports could not be computed was given a rule set anyway")
+	}
+	if !strings.Contains(err.Error(), "anchor") {
+		t.Fatalf("the refusal does not name the machine: %v", err)
+	}
+}
+
+// A generator with nothing to say about ports is ordinary and must not be required to say so.
+func TestAGeneratorThatOpensNothingNeedsNoMethod(t *testing.T) {
+	rules := mustFilter(t, Resolution{Node: "anchor",
+		Modules: []Manifest{{Module: "names", Computed: "mesh-names"}}},
+		map[string]Generator{"mesh-names": computedOnce{}})
+	if len(rules) != 0 {
+		t.Fatalf("a generator that says nothing about ports opened one: %+v", rules)
+	}
+}
+
+// A module may reflect a file another module put on the machine.
+//
+// The case this exists for: a resolver restarting when the mesh rewrites the names. Those are
+// computed by the mesh and belong to its module, not to the daemon's — so without this the
+// daemon would serve the names it started with for ever, while every check reported success.
+func TestAServiceCanReflectAnotherModulesFile(t *testing.T) {
+	out, err := Resolution{Node: "anchor", Modules: []Manifest{{
+		Module: "dnsmasq",
+		Resources: []map[string]any{
+			{"id": "config", "type": "file", "path": "/etc/dnsmasq.conf",
+				"content": "x", "mode": "0644"},
+			{"id": "run", "type": "service", "unit": "dnsmasq.service", "state": "running",
+				"restart-on": []any{"config", "mesh-resolver.nodes"}},
+		},
+	}}}.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range out {
+		if r["type"] != "service" {
+			continue
+		}
+		reflects := r["restart-on"].([]any)
+		var own, other bool
+		for _, id := range reflects {
+			switch id.(string) {
+			case "dnsmasq.config":
+				own = true
+			case "mesh-resolver.nodes":
+				other = true
+			}
+		}
+		if !own {
+			t.Fatalf("its own file was not prefixed with its module: %v", reflects)
+		}
+		if !other {
+			t.Fatalf("a file it named in full was prefixed again and now points at nothing: %v",
+				reflects)
+		}
+		return
+	}
+	t.Fatal("no service in the declaration")
+}
+
+// What answers a requirement is applied before what asked for it.
+//
+// The host does not sort, so the order written here is the order a machine applies. Selection
+// walks outward from what was assigned, which puts a consumer first — and a service that reads a
+// file another module writes then starts before the file exists, fails, and is fixed by the next
+// reconcile. That is the worst shape a fault can take: what gets remembered is that it works.
+func TestWhatAnsweredARequirementIsAppliedFirst(t *testing.T) {
+	got, err := Resolve(map[string]Manifest{
+		"dnsmasq": {Module: "dnsmasq", Requires: []string{"resolver-data"}},
+		"data":    {Module: "data", Provides: []Offer{{Name: "resolver-data"}}},
+	}, []string{"dnsmasq"}, Node{Name: "anchor"}, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.Modules[0].Module != "data" {
+		t.Fatalf("the consumer is applied before what it requires: %v", named(got))
+	}
+}
+
+// Through a chain, not only one step: a machine applies what the thing it needs needs, first.
+func TestAChainOfRequirementsIsAppliedFromTheBottom(t *testing.T) {
+	got, err := Resolve(map[string]Manifest{
+		"top":    {Module: "top", Requires: []string{"middle-thing"}},
+		"middle": {Module: "middle", Provides: []Offer{{Name: "middle-thing"}}, Requires: []string{"bottom-thing"}},
+		"bottom": {Module: "bottom", Provides: []Offer{{Name: "bottom-thing"}}},
+	}, []string{"top"}, Node{Name: "anchor"}, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	order := named(got)
+	if order[0] != "bottom" || order[1] != "middle" || order[2] != "top" {
+		t.Fatalf("a chain was not applied from the bottom: %v", order)
+	}
+}
+
+// Modules with no relation keep the order selection gave them — assigned first, then what they
+// pulled in. A sort that reshuffled unrelated modules would make every declaration's diff
+// unreadable for no gain.
+func TestUnrelatedModulesKeepTheirOrder(t *testing.T) {
+	got, err := Resolve(map[string]Manifest{
+		"one":   {Module: "one"},
+		"two":   {Module: "two"},
+		"three": {Module: "three"},
+	}, []string{"one", "two", "three"}, Node{Name: "anchor"}, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	order := named(got)
+	if order[0] != "one" || order[1] != "two" || order[2] != "three" {
+		t.Fatalf("unrelated modules were reshuffled: %v", order)
+	}
+}
+
+// Two modules requiring each other are both applied rather than refused: a cycle here is not a
+// machine that cannot work, and refusing would make a cooperating pair impossible to assign.
+func TestTwoModulesRequiringEachOtherAreStillApplied(t *testing.T) {
+	got, err := Resolve(map[string]Manifest{
+		"a": {Module: "a", Provides: []Offer{{Name: "from-a"}}, Requires: []string{"from-b"}},
+		"b": {Module: "b", Provides: []Offer{{Name: "from-b"}}, Requires: []string{"from-a"}},
+	}, []string{"a"}, Node{Name: "anchor"}, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Modules) != 2 {
+		t.Fatalf("a cooperating pair was not applied: %v", named(got))
+	}
+}
+
+func named(r Resolution) []string {
+	var out []string
+	for _, m := range r.Modules {
+		out = append(out, m.Module)
+	}
+	return out
+}
+
+// A port's source is a per-node setting, not a manifest constant: the same module is internal on
+// one machine and public on another (novox/hq ADR 0046). postgres listens from the mesh by default;
+// a setting on one node exposes it to anywhere, and the rule set follows.
+func TestExposureSettingOverridesAListensSource(t *testing.T) {
+	postgres := Manifest{Module: "postgres", Version: "1",
+		Listens: []Listening{{Port: 5432, From: FromMesh, Why: "the database"}}}
+
+	base, err := Resolution{Node: "ace", Modules: []Manifest{postgres}}.Filtering(nil, nil, nil)
+	if err != nil {
+		t.Fatalf("filtering: %v", err)
+	}
+	if len(base) != 1 || base[0].From != FromMesh {
+		t.Fatalf("without a setting, the default source is the mesh: %+v", base)
+	}
+
+	expose := map[string]map[int]string{"postgres": {5432: FromEverywhere}}
+	exposed, err := Resolution{Node: "novox", Modules: []Manifest{postgres}}.Filtering(nil, nil, expose)
+	if err != nil {
+		t.Fatalf("filtering: %v", err)
+	}
+	if len(exposed) != 1 || exposed[0].From != FromEverywhere {
+		t.Fatalf("the setting did not open the port to anywhere: %+v", exposed)
+	}
+}
+
+// Exposure refuses a setting that names a port the module does not listen on, or a source that is
+// not a real one — a setting reaching nothing is worse than none (novox/hq ADR 0043/0046).
+func TestExposureRefusesAPortNotListenedOnAndABadSource(t *testing.T) {
+	postgres := Manifest{Module: "postgres", Listens: []Listening{{Port: 5432, From: FromMesh}}}
+	layer := func(port, source string) []Layer {
+		return []Layer{{From: "node", Placement: map[string]any{ExposeSetting: map[string]any{port: source}}}}
+	}
+
+	if _, err := Exposure(postgres, layer("5432", FromEverywhere)); err != nil {
+		t.Fatalf("a valid exposure was refused: %v", err)
+	}
+	if _, err := Exposure(postgres, layer("6379", FromEverywhere)); err == nil {
+		t.Error("a port the module does not listen on was accepted")
+	}
+	if _, err := Exposure(postgres, layer("5432", "everyone")); err == nil {
+		t.Error("a source that is not mesh/anywhere/machine was accepted")
+	}
+}
+
+// ssh survives whatever the mesh does or does not know about this machine.
+//
+// **The one rule here that nothing derives.** Every other line comes from what is assigned, which
+// is the point of the mechanism — and a mesh part-way through adopting a machine has been assigned
+// almost nothing, so what it computes is a chain that drops the port used to fix it. The session
+// loading the rules lives on conntrack until it drops, and then the machine is reached from a
+// rescue console (novox/hq issue 047).
+func TestSSHIsOpenFromTheMeshEvenWhenNothingIsAssigned(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2", "198.51.100.3"}, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "ip saddr { 198.51.100.2, 198.51.100.3 } tcp dport 22 accept") {
+		t.Fatalf("ssh is not open to the mesh, so a machine can lock everyone out:\n%s", nft)
+	}
+	// And not to the world, on a machine that does not face it.
+	if strings.Contains(nft, "\t\ttcp dport 22 accept") {
+		t.Fatalf("ssh is open to everywhere on a machine that faces inward only:\n%s", nft)
+	}
+}
+
+// And from outside as well, on a machine that faces outward — because that is the way in when the
+// private network is the thing that broke.
+func TestSSHIsOpenFromOutsideOnAMachineThatFacesIt(t *testing.T) {
+	nft := AsNftables(nil, []string{"198.51.100.2"}, true, nil, nil, "mesh0")
+	if !strings.Contains(nft, "\t\ttcp dport 22 accept") {
+		t.Fatalf("a machine reachable from outside does not answer ssh there:\n%s", nft)
+	}
+}
+
+// A machine the mesh knows no addresses for still answers ssh.
+//
+// **This is the machine it matters most for.** Before the private network exists there is nothing
+// to narrow the rule to, so narrowing it shuts the port entirely — on the first machine anybody
+// adopts, reached over the network, closed by the act of adopting it.
+func TestSSHIsNeverLeftWithoutARule(t *testing.T) {
+	nft := AsNftables(nil, nil, false, nil, nil, "mesh0")
+	if !strings.Contains(nft, "tcp dport 22 accept") {
+		t.Fatalf("a machine with no mesh addresses has no ssh rule, so adopting it locks it:\n%s", nft)
+	}
+}
+
+// chainBody is one chain's own lines, so an assertion cannot be satisfied by an identical line in
+// another chain.
+//
+// **Written because that happened.** The rule letting this machine's own callers through appears in the
+// input chain and, in the same words, in the forward chain. A test asserting on the whole rendered file
+// passed with the input chain's copy deleted — it was reading the forward chain's. ADR 0137's own tests
+// say to assert per chain body for exactly this reason, and this file was not doing it.
+func chainBody(t *testing.T, nft, chain string) string {
+	t.Helper()
+	open := "\tchain " + chain + " {"
+	i := strings.Index(nft, open)
+	if i < 0 {
+		t.Fatalf("no chain %q in:\n%s", chain, nft)
+	}
+	rest := nft[i+len(open):]
+	j := strings.Index(rest, "\n\t}")
+	if j < 0 {
+		t.Fatalf("chain %q does not close in:\n%s", chain, nft)
+	}
+	return rest[:j]
+}
+
+// **Anything on this machine may call anything on this machine.**
+//
+// Local is not a boundary this mesh draws, and whether a caller sits in a container was never meant to
+// change the answer. It did, because the chain asked about addresses: a caller on the machine carries
+// the machine's address and a caller in one of its containers carries a bridge address, so a rule
+// naming the machines' own addresses silently refused every container on them.
+//
+// Measured: a module reaching its database on its own machine's name timed out for eleven hours while
+// the machine itself could reach it (novox/hq 04-ISSUES/145).
+func TestAnythingOnThisMachineMayCallAnythingOnIt(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "store", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+		{Module: "private", Listens: []Listening{{Port: 9999, From: FromMachine}}},
+	}}, nil), []string{"10.10.0.1", "10.10.0.2"}, false, nil, []string{"eth0"}, "mesh0")
+
+	// In the INPUT chain, which is where a call to a service on this machine arrives. The forward
+	// chain carries the same line in the same words, so asserting on the whole file proves nothing.
+	input := chainBody(t, nft, "input")
+	if !strings.Contains(input, `iifname != { "eth0", "mesh0" } accept`) {
+		t.Fatalf("a caller on this machine cannot reach a service on it:\n%s", input)
+	}
+	// One rule, for every service here — not a line per port that only covers the ports somebody
+	// remembered to think about.
+	if strings.Contains(input, `iifname != { "eth0", "mesh0" } tcp dport 5432`) {
+		t.Fatalf("the local allowance is still written per port:\n%s", input)
+	}
+	// And the private network still reaches what is exposed to it, which is a different question.
+	if !strings.Contains(input, "ip saddr { 10.10.0.1, 10.10.0.2 } tcp dport 5432 accept") {
+		t.Fatalf("the private network no longer reaches a service exposed to it:\n%s", input)
+	}
+}
+
+// The three reaches, as three lines. This is the whole of what the filter says about who may call what.
+func TestTheThreeReachesAreThreeLines(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "internal-only", Listens: []Listening{{Port: 5432, From: FromMesh}}},
+		{Module: "public", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}, nil), []string{"10.10.0.1"}, false, nil, []string{"eth0"}, "mesh0")
+
+	input := chainBody(t, nft, "input")
+	for what, want := range map[string]string{
+		"on this machine":          `iifname != { "eth0", "mesh0" } accept`,
+		"over the private network": "ip saddr { 10.10.0.1 } tcp dport 5432 accept",
+		"from anywhere":            "tcp dport 443 accept",
+	} {
+		if !strings.Contains(input, want) {
+			t.Fatalf("a caller %s cannot reach what is exposed to it (%q):\n%s", what, want, input)
+		}
+	}
+}
+
+// A port open to everything needs no such line — it is already open to a guest.
+func TestAPublicPortNeedsNoGuestLine(t *testing.T) {
+	nft := AsNftables(mustFilter(t, Resolution{Modules: []Manifest{
+		{Module: "web", Listens: []Listening{{Port: 443, From: FromEverywhere}}},
+	}}, nil), []string{"10.10.0.1"}, false, nil, []string{"eth0"}, "mesh0")
+	if strings.Count(nft, `iifname != { "eth0", "mesh0" } tcp dport 443`) != 0 {
+		t.Fatalf("a public port was given a guest line it does not need:\n%s", nft)
+	}
+}
+
+// **The hub relays the mesh** (novox/hq ADR 0007, issue 196). Two machines that are not co-located
+// reach each other through the hub, so the hub forwards a packet that arrives on the tunnel and
+// leaves on it. The forward chain judged that packet by the hub's own published ports, and two
+// machines behind the hub reached each other only on the ports the hub happened to publish.
+//
+// Measured: from one home machine to another through the hub, 17 of 55 ports answered, and they
+// were exactly the hub's own; the SYN for the rest never left the hub.
+func TestTheMeshPassingThroughIsRelayedNotJudgedAsThisMachines(t *testing.T) {
+	nft := AsNftables(nil, []string{"10.42.0.1", "10.42.0.2"}, false, nil, []string{"eth0"}, "mesh0")
+	relay := `iifname "mesh0" oifname "mesh0" accept`
+	if !strings.Contains(chainBody(t, nft, "forward"), relay) {
+		t.Errorf("the forward chain does not relay the mesh through this machine:\n%s", chainBody(t, nft, "forward"))
+	}
+	// Relaying is not receiving: nothing in the input chain opens because of it.
+	if strings.Contains(chainBody(t, nft, "input"), "oifname") {
+		t.Errorf("the input chain names an outgoing interface, which no packet for this machine has:\n%s",
+			chainBody(t, nft, "input"))
+	}
+	// And off the tunnel into this machine's own containers is still judged: the tunnel is not
+	// accepted wholesale, only in and out on it.
+	if strings.Contains(chainBody(t, nft, "forward"), `iifname "mesh0" accept`) {
+		t.Errorf("the forward chain accepts everything off the tunnel:\n%s", chainBody(t, nft, "forward"))
+	}
+
+	// A machine with no tunnel relays nothing, and names no interface it does not have.
+	alone := AsNftables(nil, nil, false, nil, []string{"eth0"}, "")
+	if strings.Contains(alone, "oifname") {
+		t.Errorf("a machine with no tunnel was given a relay rule:\n%s", alone)
+	}
+}

go/catalogue/foundation_manifests_test.go

@@ -0,0 +1,334 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"fmt"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+
+	"git.novox.be/novox/mesh-sdk/go/internal/beside"
+)
+
+// The catalogue's foundation modules as they are — in a merge check the catalogue cloned beside it,
+// elsewhere the copy captured in testdata/beside (internal/beside, novox/hq issue 432) — parsed by the
+// real parser (novox/hq ADR 0100):
+// the store and the broker say which of their ports the mesh guards on an adopted node, and the
+// filter module loads its table through a unit of its own whose stop deletes only that table.
+// moduleTree is where a module is read from: the catalogue beside, with the catalogue as the root. In
+// mesh-controller it first looked in the repository's own modules/<module>, where build-agent and
+// route-proxy live whole (novox/hq ADR 0420 §1, issue 1019); mesh-sdk has no such directory, and the
+// tests that read those two modules stay in mesh-controller (issue 1379).
+func moduleTree(t *testing.T, module string) (root, dir string) {
+	t.Helper()
+	return beside.Dir(t, "mesh-catalog"), filepath.Join(beside.Catalogue(t), module)
+}
+
+func catalogueManifest(t *testing.T, module string) Manifest {
+	t.Helper()
+	root, dir := moduleTree(t, module)
+	m, err := ReadTreeManifest(root, dir)
+	if err != nil {
+		t.Fatalf("%s does not parse:\n%v", module, err)
+	}
+	return m
+}
+
+func TestTheStoreAndTheBrokerSayWhatTheMeshGuards(t *testing.T) {
+	if got := catalogueManifest(t, "postgres").Guards; !reflect.DeepEqual(got, []int{5432}) {
+		t.Errorf("postgres guards %v; the store's port must be refused from outside", got)
+	}
+	// The bus's monitoring port, not its client port: a node reaches the bus, nobody outside
+	// reads its state (novox/hq ADR 0131 — the broker that guarded 15672 has left the catalogue).
+	if got := catalogueManifest(t, "nats").Guards; !reflect.DeepEqual(got, []int{8222}) {
+		t.Errorf("nats guards %v; the monitoring port must be refused from outside", got)
+	}
+}
+
+func TestTheFilterModuleNeverFlushesTheRuleset(t *testing.T) {
+	m := catalogueManifest(t, "nftables")
+	var unit, stock, load map[string]any
+	for _, r := range m.Resources {
+		switch r["id"] {
+		case "unit":
+			unit = r
+		case "stock-unit-stop":
+			stock = r
+		case "load":
+			load = r
+		}
+	}
+	if load == nil || load["unit"] != "mesh-filter.service" {
+		t.Fatalf("the filter is not loaded by its own unit: %v", load)
+	}
+	content, _ := unit["content"].(string)
+	if unit == nil || unit["path"] != "/etc/systemd/system/mesh-filter.service" {
+		t.Fatalf("the filter's unit is not written: %v", unit)
+	}
+	if strings.Contains(content, "flush") {
+		t.Fatalf("stopping the filter flushes the whole ruleset — the runtime's and the found "+
+			"firewall's with it:\n%s", content)
+	}
+	if !strings.Contains(content, "ExecStop=nft delete table inet mesh\n") ||
+		!strings.Contains(content, "ExecStart=nft -f "+m.Filtering.Into+"\n") {
+		t.Fatalf("the unit does not load the computed rule set and delete only its own table:\n%s",
+			content)
+	}
+	// A node converged before the filter had its own unit still has the stock nftables.service
+	// enabled, whose stop flushes the whole ruleset: a drop-in makes it delete only the mesh's
+	// table, and the load is restarted on it so the host reloads units and the drop-in is read.
+	if stock == nil || stock["path"] != "/etc/systemd/system/nftables.service.d/mesh.conf" ||
+		!strings.HasSuffix(fmt.Sprint(stock["content"]),
+			"[Service]\nExecStop=\nExecStop=nft delete table inet mesh\n") {
+		t.Fatalf("the stock unit's stop is not replaced with deleting the mesh's table: %v", stock)
+	}
+	// A changed rule set is RELOADED — ExecReload replaces the table in one `nft -f`, so the node
+	// is never unfiltered — and only the units themselves restart it, which is the one change a
+	// reload cannot carry.
+	if !reflect.DeepEqual(load["reload-on"], []any{"filtering"}) {
+		t.Fatalf("the filter is restarted rather than reloaded when its rules change, leaving the "+
+			"node unfiltered in between: %v", load)
+	}
+	if !reflect.DeepEqual(load["restart-on"], []any{"unit", "stock-unit-stop"}) {
+		t.Fatalf("the filter is not restarted when its unit or the stock unit's drop-in changes: %v",
+			load["restart-on"])
+	}
+}
+
+// The package registry's port is the node's, like every other foundation port (novox/hq
+// 04-ISSUES/085, ADR 0100). The forge is reached through what it says it serves, and consumers —
+// the builder among them — are told that, rather than carrying a number of their own.
+
+func TestTheForgesPortIsGivenLikeAnyOtherProvidersPort(t *testing.T) {
+	forge := catalogueManifest(t, "gitea")
+
+	// The catalogue's number is a default and the node's setting moves it.
+	given, err := GivenPorts(forge, []Layer{{From: "anchor",
+		Placement: map[string]any{PortsSetting: map[string]any{"3000": float64(3100)}}}})
+	if err != nil {
+		t.Fatalf("the forge's port cannot be given on a node: %v", err)
+	}
+	if given[3000] != 3100 {
+		t.Fatalf("the forge was given %v", given)
+	}
+
+	// And every consumer of the package registry is told where the machine actually put it,
+	// because that is read from what the forge serves rather than written in the consumer.
+	if got := ServedOn(forge, "npm-package-registry", given)["port"]; got != 3100 {
+		t.Errorf("the package registry is served on %v, not the port this node gave it", got)
+	}
+	if got := ServedOn(forge, "npm-package-registry", nil)["port"]; got != float64(3000) {
+		t.Errorf("without a setting the forge serves %v, not the catalogue's port", got)
+	}
+	// And so is where a repository on it is cloned from (novox/hq ADR 0111), for the same reason:
+	// a build composes the URL from what the forge serves, so a given port is a followed port.
+	if got := ServedOn(forge, "git", given)["port"]; got != 3100 {
+		t.Errorf("git is served on %v, not the port this node gave the forge", got)
+	}
+}
+
+// The forge holds the seats it answers for (novox/hq ADR 0110, 0111), parsed by the real parser —
+// which refuses a delivering seat claimed by a module that does not provide what it delivers.
+func TestTheForgeHoldsTheNpmAndGitSeats(t *testing.T) {
+	forge := catalogueManifest(t, "gitea")
+	holds := map[string]bool{}
+	for _, c := range forge.Claims {
+		holds[c.Name] = true
+	}
+	for _, seat := range []string{"npm-package-registry", "git"} {
+		if !holds[seat] {
+			t.Errorf("gitea does not claim the %s seat: %+v", seat, forge.Claims)
+		}
+	}
+	git := ServedOn(forge, "git", nil)
+	if git["scheme"] != "http" || git["port"] != float64(3000) {
+		t.Errorf("gitea serves nothing a clone URL can be composed from: %v", git)
+	}
+	npm := ServedOn(forge, "npm-package-registry", nil)
+	if npm["npm-path"] != "/api/packages/novox/npm/" {
+		t.Errorf("gitea no longer says where its npm registry is: %v", npm)
+	}
+}
+
+// **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 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
+// port (ADR 0100). Composed through the whole path, because what proves the placeholder resolves
+// in an `env` at all is a declaration, not a manifest.
+func TestTheForgesOwnAddressFollowsThePortTheNodeGaveIt(t *testing.T) {
+	forge, err := catalogueManifest(t, "gitea").Resolve(forgeBuilt(catalogueManifest(t, "gitea")))
+	if err != nil {
+		t.Fatalf("the forge's manifest does not resolve against its own build: %v", err)
+	}
+	r := Resolution{Node: "anchor", Account: "op", PublicDomain: "example.org",
+		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"},
+			{Name: "secret", For: "gitea", From: "anchor", Local: "internal-token", Sealed: "sealed-token"},
+			{Name: "secret", For: "gitea", From: "anchor", Local: "admin", Sealed: "sealed-admin"},
+		}}
+
+	// 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{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 {
+		t.Fatalf("the forge does not compose: %v", err)
+	}
+
+	// What the machine publishes, and what the forge's sidecar is told to dial: one number.
+	server := fileNamed(out, "gitea.server")
+	if server == nil {
+		t.Fatalf("the forge's own container is not in the declaration: %v", out)
+	}
+	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"])
+	}
+	// 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 node's runtime is not in the declaration: %v", ids(out))
+	}
+	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"])
+	}
+}
+
+// gitea's own sshd is unmodified — the module's own internal port is 22, the number in
+// `listens`, the same convention every other module in the catalogue uses (its internal port,
+// not an invented identity). Composed from the manifest in the catalogue beside this checkout,
+// because what the mesh publishes is a fact about what the module actually writes.
+func declaredGiteaSsh(t *testing.T, given map[int]int) map[string]any {
+	t.Helper()
+	forge := catalogueManifest(t, "gitea")
+	resolved, err := forge.Resolve(forgeBuilt(forge))
+	if err != nil {
+		t.Fatalf("the forge's manifest does not resolve against its own build: %v", err)
+	}
+	r := Resolution{Node: "anchor", Account: "op", PublicDomain: "example.org",
+		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"},
+			{Name: "secret", For: "gitea", From: "anchor", Local: "internal-token", Sealed: "sealed-token"},
+			{Name: "secret", For: "gitea", From: "anchor", Local: "admin", Sealed: "sealed-admin"},
+		}}
+	givenPorts := map[int]int{3000: 3000}
+	for k, v := range given {
+		givenPorts[k] = v
+	}
+	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},
+	})
+	if err != nil {
+		t.Fatalf("the forge does not compose: %v", err)
+	}
+	server := fileNamed(out, "gitea.server")
+	if server == nil {
+		t.Fatalf("the forge's own container is not in the declaration: %v", out)
+	}
+	return server
+}
+
+// **The forge publishes ssh at the mesh's own fixed convention by default** (novox/hq ADR 0100).
+//
+// `222` is the mesh's own public convention for the forge's ssh, written directly in the
+// manifest's `ports` — every node the forge has run on used the same number, so it needs no
+// per-node setting to reach it.
+func TestTheForgesSshPortIsTheMeshsFixedConventionByDefault(t *testing.T) {
+	forge := catalogueManifest(t, "gitea")
+	// Nothing was given — no node moved this port — which is the ordinary answer: the mesh only
+	// reports what a setting moved, and the manifest's own `222:22` needs no move to be reached.
+	given, err := GivenPorts(forge, nil)
+	if err != nil {
+		t.Fatalf("the forge's ssh port cannot be given on a node: %v", err)
+	}
+	if len(given) != 0 {
+		t.Fatalf("nothing moved the forge's ssh port, yet it was given %v", given)
+	}
+	server := declaredGiteaSsh(t, given)
+	if published := fmt.Sprint(server["ports"]); !strings.Contains(published, "222:22") {
+		t.Fatalf("the forge is published on %v, not its own fixed convention", server["ports"])
+	}
+}
+
+// **A node whose predecessor served git on a different number can still be told to leave it
+// there.** The setting names the port the module itself listens on — 22, gitea's own sshd, the
+// same number `listens` uses — not the mesh's own default machine-side number, so moving it does
+// not require guessing what the manifest happens to default to.
+func TestANodeMayGiveTheForgesSshPortADifferentNumber(t *testing.T) {
+	forge := catalogueManifest(t, "gitea")
+	given, err := GivenPorts(forge, []Layer{{From: "anchor",
+		Placement: map[string]any{PortsSetting: map[string]any{"22": float64(9022)}}}})
+	if err != nil {
+		t.Fatalf("the forge's ssh port cannot be moved on a node: %v", err)
+	}
+	if want := map[int]int{22: 9022}; !reflect.DeepEqual(given, want) {
+		t.Fatalf("the forge was given %v, and the setting named %v", given, want)
+	}
+	server := declaredGiteaSsh(t, given)
+	if published := fmt.Sprint(server["ports"]); !strings.Contains(published, "9022:22") ||
+		strings.Contains(published, "222:22") {
+		t.Fatalf("the forge is published on %v, not the port this node gave it", server["ports"])
+	}
+}
+
+// forgeBuilt is a build of every artifact the forge's manifest declares: its code bundle and, since the
+// catalogue added it (novox/hq ADR 0251 §4), its npm registry's. Named from the manifest, so a third
+// artifact does not break every forge test again.
+func forgeBuilt(forge Manifest) []Built {
+	var out []Built
+	for _, a := range forge.Build.Artifacts {
+		out = append(out, Built{Name: a.Name, Kind: ArtifactBundle,
+			Reference: ArtifactStoreScheme + "gitea/" + a.Name + "/blobs/" + bundleDigest, Digest: bundleDigest})
+	}
+	return out
+}
+
+// catalogueResolved is a catalogue module as the mesh holds it once built: the manifest as written, resolved against
+// what the build produced besides the archive its templates are packed into, which carries the text read back from the
+// module's files/ directory as the real build reads it (novox/hq ADR 0349 §2) — so a module whose file text moved into
+// templates composes with it, and one that did not is resolved as it was.
+func catalogueResolved(t *testing.T, module string, built ...Built) Manifest {
+	t.Helper()
+	root, dir := moduleTree(t, module)
+	m, err := ReadTreeManifestWritten(root, dir)
+	if err != nil {
+		t.Fatalf("%s does not parse:\n%v", module, err)
+	}
+	if name := TemplatesArtifact(m); name != "" {
+		read, err := ReadTemplates(m, dir)
+		if err != nil {
+			t.Fatalf("%s: %v", module, err)
+		}
+		// By the path inside the archive, as the build reads it back, not by the path in the module's directory.
+		texts := map[string]string{}
+		for path, text := range read {
+			texts[strings.TrimPrefix(path, m.TemplatesDir()+"/")] = text
+		}
+		built = append(built, Built{Name: name, Kind: ArtifactArchive,
+			Reference: ArtifactStoreScheme + module + "/" + name + "/blobs/" + bundleDigest, Digest: bundleDigest,
+			Texts: texts})
+	}
+	held, err := m.Resolve(built)
+	if err != nil {
+		t.Fatalf("%s does not resolve against its own build: %v", module, err)
+	}
+	return held
+}

go/catalogue/generated_collision_test.go

@@ -0,0 +1,85 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// novox/hq issue 190, step 5 (ADR 0222): what the mesh computes for a module is held to the rule
+// every module is — no two modules on a machine declare one path, unit or name (a package may be declared by
+// several, novox/hq ADR 0303). The
+// private network once declared the container runtime's file and service beside the runtime's own
+// module, and nothing refused it, because the collision check only ever saw catalogue manifests.
+
+func runtimesOwn() Manifest {
+	return Manifest{Module: "docker", Resources: []map[string]any{
+		{"id": "daemon", "type": "file", "path": "/etc/docker/daemon.json", "into": "json",
+			"content": `{"live-restore": true}`},
+		{"id": "runtime", "type": "service", "unit": "docker.service", "state": "running",
+			"reload-on": []any{"daemon"}},
+	}}
+}
+
+func TestAGeneratedResourceCollidingWithAModulesIsRefused(t *testing.T) {
+	r := Resolution{Node: "workstation", Modules: []Manifest{
+		{Module: "mesh-network", Computed: "mesh-network", Provides: Offers("private-network")},
+		runtimesOwn(),
+	}}
+	_, err := r.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": reloading{}}})
+	if err == nil {
+		t.Fatal("a generated resource declaring the runtime's file beside the runtime's module was accepted")
+	}
+	for _, want := range []string{"mesh-network", "docker", "/etc/docker/daemon.json", "docker.service"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal does not name %s: %v", want, err)
+		}
+	}
+}
+
+func TestAGeneratedResourceBesideAModulesOwnIsComposed(t *testing.T) {
+	r := Resolution{Node: "workstation", Modules: []Manifest{
+		{Module: "mesh-network", Computed: "mesh-network", Provides: Offers("private-network")},
+		runtimesOwn(),
+	}}
+	gen := &fake{on: map[string]bool{"workstation": true}}
+	out, err := r.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": gen}})
+	if err != nil {
+		t.Fatalf("disjoint resources were refused: %v", err)
+	}
+	if fileNamed(out, "docker.daemon") == nil {
+		t.Fatalf("the runtime's own file is missing: %v", out)
+	}
+	// And a machine not on the network yet generates nothing, which collides with nothing.
+	if _, err := r.Declaration(Rendering{Generators: map[string]Generator{"mesh-network": &fake{}}}); err != nil {
+		t.Fatalf("a machine off the network was refused: %v", err)
+	}
+}
+
+// The catalogue's container runtime module states the mesh's registry itself (ADR 0222).
+func TestTheRuntimesModuleTrustsTheMeshsRegistry(t *testing.T) {
+	docker := catalogueManifest(t, "docker")
+	r := Resolution{Node: "workstation", Modules: []Manifest{docker}}
+	out, err := r.Declaration(Rendering{
+		SeatReach: map[string]string{"mesh-artifact-store": "anchor.internal:5100"},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	daemon := fileNamed(out, "docker.daemon")
+	if daemon == nil || daemon["into"] != "json" {
+		t.Fatalf("the runtime's file is not written into: %v", daemon)
+	}
+	content, _ := daemon["content"].(string)
+	if !strings.Contains(content, `"insecure-registries": ["anchor.internal:5100"]`) ||
+		!strings.Contains(content, `"live-restore": true`) {
+		t.Fatalf("the runtime's file says %q", content)
+	}
+
+	out, err = r.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if content, _ := fileNamed(out, "docker.daemon")["content"].(string); strings.Contains(content, "insecure-registries") {
+		t.Fatalf("with no store on the network, the runtime is told %q", content)
+	}
+}

go/catalogue/go_bundle_test.go

@@ -0,0 +1,37 @@
+package catalogue
+
+import "testing"
+
+// A bundle is the module's own directory compiled whole, and naming a source would be describing its
+// own build. That holds for an interpreted language and cannot hold for a compiled one: a repository
+// written in Go carries several commands — the host and its bootstrap live in one — and "the module's
+// own directory" is then not a package at all (novox/hq 04-ISSUES/142).
+
+func TestAGoBundleMayNameItsCommand(t *testing.T) {
+	b := &Build{Artifacts: []Artifact{{
+		Name: "host-arch", Kind: ArtifactBundle, Language: "go", System: "arch",
+		From: "cmd/mesh-host",
+	}}}
+	if p := b.problems("mesh-host"); len(p) != 0 {
+		t.Fatalf("a go bundle naming its command was refused: %v", p)
+	}
+}
+
+func TestAnInterpretedBundleStillMayNotNameASource(t *testing.T) {
+	b := &Build{Artifacts: []Artifact{{
+		Name: "tools", Kind: ArtifactBundle, Language: "typescript", From: "src",
+	}}}
+	p := b.problems("something")
+	if len(p) == 0 {
+		t.Fatal("an interpreted bundle naming what it is built from was accepted")
+	}
+}
+
+func TestACompiledBundleStillMustSayItsSystem(t *testing.T) {
+	b := &Build{Artifacts: []Artifact{{
+		Name: "host", Kind: ArtifactBundle, Language: "go", From: "cmd/mesh-host",
+	}}}
+	if len(b.problems("mesh-host")) == 0 {
+		t.Fatal("a compiled bundle with no system was accepted")
+	}
+}

go/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
+}