K3: pin gitea to mesh-sdk 104533e8, the group's final SDK head after S1 and S2 (ADR 0500 §2)

The catalogue's paths check (ADR 0260) reads every file of a module but its documentation and tests, and
the verbatim manifest names claude-code's own paths; as a constant in a _test.go file it stays a real
capture without being taken for one module reaching into another's state.

.gitignore

@@ -8,16 +8,23 @@ modules/messenger/cmd/messenger/messenger
 modules/mesh-watcher/cmd/mesh-watcher/mesh-watcher
 modules/claude-code/cmd/claude-code/claude-code
 modules/dnsmasq/cmd/dnsmasq-tools/dnsmasq-tools
-modules/mesh-delivery/cmd/mesh-delivery/mesh-delivery
 # ...and the same built from the module's root (go build ./cmd/<name>), which names it after the module.
 modules/messenger/messenger
 modules/claude-code/claude-code
 modules/mesh-watcher/mesh-watcher
 modules/dnsmasq/dnsmasq
-modules/mesh-delivery/mesh-delivery
 modules/mesh-issues/cmd/mesh-issues/mesh-issues
 modules/mounts/cmd/mounts/mounts
 modules/mesh-knowledge/cmd/mesh-knowledge/mesh-knowledge
 modules/mesh-knowledge/mesh-knowledge
 modules/mesh-reads/mesh-reads
 modules/mesh-reads/cmd/mesh-reads/mesh-reads
+modules/mesh-files/mesh-files
+modules/mesh-files/cmd/mesh-files/mesh-files
+
+# The provisioner client built in place (issue 671).
+modules/mesh-provisioner-client/cmd/mesh-provisioner-client/mesh-provisioner-client
+modules/brother/cmd/brother/brother
+modules/mesh-build-go/cmd/mesh-build-go/mesh-build-go
+modules/mesh-config/mesh-config
+modules/mesh-build-image/cmd/mesh-build-image/mesh-build-image

RELEASE-57.md

@@ -0,0 +1,6 @@
+# Release 57: config and provisioning
+
+This branch carries the work of hq design 57 (ADR 0348, ADR 0349) in this repository. Each package
+merges here through its own reviewed pull request; the branch reaches main as one pull request, in one
+delivery group with the branch of the same name in mesh-controller, mesh-host, mesh-sdk, mesh-catalog
+and hq, after a rehearsal in the lab. This file is deleted by the last commit before that pull request.

checks/config/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/config
+
+go 1.22

checks/config/main.go

@@ -0,0 +1,201 @@
+// Command config refuses the settings form's names in a module that has moved to config (novox/hq ADR 0348
+// clauses 1 and 11, design 57 package K6, issue 665).
+//
+// "Config" replaces "settings": a manifest declares its values under `config`, a mergeable file names the keys it
+// takes under `takes-config`, and a file asks for a value with `${config:<key>}`. A mergeable file naming no keys at
+// all is the settings form's last shape: it takes every key of its module's layer and declares none, so mesh-config
+// could set none of them (ADR 0348 §10, ADR 0326 §3); it is found here like an old name (issue 735). The old names — `settings`,
+// `takes-settings` and `${setting:<key>}` — stay accepted by the controller as aliases until every module has
+// moved, and are then refused (ADR 0348 §1). The modules not yet moved are listed in the file `unmoved` beside this
+// check, one per line: the catalogue's list ADR 0348 §11 names. Every other module says no old name, in its
+// manifest or in a template file its manifest names; a module on the list that says none is taken off it; and a
+// line the trunk's copy (the merge base's, given with -base) does not hold is refused, so the list only shrinks;
+// while the trunk holds no copy, the modules in seed are the trunk's.
+// When it is empty, the controller refuses the old names itself (design 57 package R1).
+//
+// Prose is not judged: a comment in a file's text that says "settings" composes into the machine's file, and
+// rewording it would change what a node is sent.
+//
+//	go run . [-base <the trunk's unmoved>] <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// The settings form's names (ADR 0348 §1). A key of a JSON object is a quoted string followed by a colon; a
+// string value is never followed by one.
+var (
+	settingRef        = regexp.MustCompile(`\$\{setting:[a-z0-9][a-z0-9_.-]*\}`)
+	takesSettingsKey  = regexp.MustCompile(`"takes-settings"\s*:`)
+	oldPlaceholder    = "${setting:…}"
+	oldTakes          = "takes-settings"
+	oldDeclaration    = "settings"
+	wholeLayer        = "taking its whole layer"
+	listFile          = "unmoved"
+	listPathInCatalog = "checks/config/" + listFile
+)
+
+// Check answers, per module that says any, the settings form's names its manifest and its template files say.
+func Check(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	out := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Settings  json.RawMessage  `json:"settings"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		var said []string
+		if len(m.Settings) > 0 && string(m.Settings) != "null" {
+			said = append(said, oldDeclaration)
+		}
+		if takesSettingsKey.Match(raw) {
+			said = append(said, oldTakes)
+		}
+		if settingRef.Match(raw) {
+			said = append(said, oldPlaceholder)
+		}
+		for _, r := range m.Resources {
+			// A mergeable file naming no keys takes every key of the layer (ADR 0326 §3), declaring none of them.
+			if how, _ := r["merge"].(string); how != "" {
+				_, oldList := r["takes-settings"]
+				_, newList := r["takes-config"]
+				if !oldList && !newList {
+					said = append(said, fmt.Sprintf("%v %s", r["id"], wholeLayer))
+				}
+			}
+			name, _ := r["template"].(string)
+			if name == "" {
+				continue
+			}
+			text, err := os.ReadFile(filepath.Join(filepath.Dir(path), filepath.FromSlash(name)))
+			if err != nil {
+				return nil, fmt.Errorf("%s names the template %s: %w", m.Module, name, err)
+			}
+			if settingRef.Match(text) {
+				said = append(said, oldPlaceholder+" in "+name)
+			}
+		}
+		if len(said) > 0 {
+			sort.Strings(said)
+			out[m.Module] = said
+		}
+	}
+	return out, nil
+}
+
+// seed is the list as it was first written, standing for the trunk's copy until the trunk holds one.
+// The modules taking a whole layer were found after the list was first written and before the trunk held a copy
+// (issue 735), so they stand in it too.
+var seed = map[string]bool{
+	"betterbird": true, "fail2ban": true, "influxdb": true, "keycloak": true, "mailu": true, "searxng": true,
+	"baserow": true, "confluence": true, "gitea": true, "gitlab": true, "grafana": true, "home-assistant": true,
+	"icecast": true, "jira": true, "letta": true, "matrix": true, "nodered": true, "supabase": true, "unifi": true,
+}
+
+// Unmoved is the modules a list names, one per line; a line starting with # and a blank line are not modules.
+func Unmoved(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	out := map[string]bool{}
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := strings.TrimSpace(s.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out[line] = true
+	}
+	return out, s.Err()
+}
+
+// Judge answers the modules that say an old name and are not on the list (refused), the modules on the list that
+// say none (stale), and the modules on the list that the trunk's list does not hold (added).
+func Judge(found map[string][]string, unmoved, base map[string]bool) (refused, stale, added []string) {
+	for m := range found {
+		if !unmoved[m] {
+			refused = append(refused, m)
+		}
+	}
+	for m := range unmoved {
+		if _, says := found[m]; !says {
+			stale = append(stale, m)
+		}
+		if !base[m] {
+			added = append(added, m)
+		}
+	}
+	sort.Strings(refused)
+	sort.Strings(stale)
+	sort.Strings(added)
+	return refused, stale, added
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's copy of unmoved (the merge base's); seed when absent")
+	flag.Parse()
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	unmoved, err := Unmoved(listFile)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	base := seed
+	if *basePath != "" {
+		if base, err = Unmoved(*basePath); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	}
+	refused, stale, added := Judge(found, unmoved, base)
+	for _, m := range refused {
+		fmt.Printf("%s says %s, the settings form's names, and is not on %s: write config, takes-config and "+
+			"${config:<key>} throughout, and name the keys each mergeable file takes (novox/hq ADR 0348 §1, §11)\n", m, strings.Join(found[m], ", "), listPathInCatalog)
+	}
+	for _, m := range stale {
+		fmt.Printf("%s names %s, which says no old name: take it off the list\n", listPathInCatalog, m)
+	}
+	for _, m := range added {
+		fmt.Printf("%s gains %s, which the trunk's copy does not hold: the list only shrinks — move the module to "+
+			"config instead (novox/hq ADR 0348 §11)\n", listPathInCatalog, m)
+	}
+	if len(refused) > 0 || len(stale) > 0 || len(added) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("config: no moved module says settings, takes-settings or ${setting:<key>}, or takes a whole layer "+
+		"(%d not yet moved)\n",
+		len(unmoved))
+}

checks/config/main_test.go

@@ -0,0 +1,131 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func module(t *testing.T, root, name, body string, files map[string]string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for path, text := range files {
+		full := filepath.Join(dir, filepath.FromSlash(path))
+		if err := os.MkdirAll(filepath.Dir(full), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(full, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+// Each of the settings form's names is found where it stands: the declaration, a mergeable file's keys, a
+// placeholder in the manifest, and a placeholder in a template file the manifest names (novox/hq ADR 0348 §1).
+func TestEveryOldNameIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "declares", `{"module":"declares","settings":{"size":{"kind":"preference","default":1,"why":"w"}},`+
+		`"resources":[{"id":"f","type":"file","content":"${setting:size}"}]}`, nil)
+	module(t, root, "takes", `{"module":"takes","resources":[{"id":"f","type":"file","merge":"json",`+
+		`"takes-settings":["a"],"content":"{}"}]}`, nil)
+	module(t, root, "asks", `{"module":"asks","serves":{"x":{"d":"${setting:domain}"}}}`, nil)
+	module(t, root, "templated", `{"module":"templated","config":{"size":{"type":"number","description":"d",`+
+		`"default":1}},"resources":[{"id":"f","type":"file","template":"files/conf"}]}`,
+		map[string]string{"files/conf": "size = ${setting:size}\n"})
+	module(t, root, "moved", `{"module":"moved","config":{"size":{"type":"number","description":"d","default":1}},`+
+		`"resources":[{"id":"f","type":"file","template":"files/conf"},{"id":"g","type":"file","merge":"json",`+
+		`"takes-config":[],"content":"{\"settings\": 1}"}]}`,
+		map[string]string{"files/conf": "size = ${config:size}\n# change the settings, never this file\n"})
+	module(t, root, "none", `{"module":"none","resources":[{"id":"f","type":"file","content":"no settings here"}]}`, nil)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{
+		"asks":      {"${setting:…}"},
+		"declares":  {"${setting:…}", "settings"},
+		"takes":     {"takes-settings"},
+		"templated": {"${setting:…} in files/conf"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}
+
+// A module not on the list says no old name; one on the list that says none is taken off it; a line the trunk's
+// list does not hold is refused, so the list only shrinks until it is empty (novox/hq ADR 0348 §11).
+func TestTheListOfModulesNotYetMovedOnlyShrinks(t *testing.T) {
+	found := map[string][]string{"old": {"settings"}, "forgotten": {"takes-settings"}}
+	unmoved := map[string]bool{"old": true, "done": true, "new": true}
+	base := map[string]bool{"old": true, "done": true, "forgotten": true}
+	refused, stale, added := Judge(found, unmoved, base)
+	if !reflect.DeepEqual(refused, []string{"forgotten"}) || !reflect.DeepEqual(stale, []string{"done", "new"}) ||
+		!reflect.DeepEqual(added, []string{"new"}) {
+		t.Fatalf("refused %v, stale %v, added %v", refused, stale, added)
+	}
+}
+
+func TestTheListIsReadWithoutItsComments(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "unmoved")
+	if err := os.WriteFile(path, []byte("# why\n\nmailu\n  searxng  \n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Unmoved(path)
+	if err != nil || !reflect.DeepEqual(got, map[string]bool{"mailu": true, "searxng": true}) {
+		t.Fatalf("%v %v", got, err)
+	}
+}
+
+// The catalogue itself: every moved module says config alone, and the list names exactly the modules that
+// still say settings.
+func TestTheCatalogueSaysConfigInEveryMovedModule(t *testing.T) {
+	found, err := Check(filepath.Join("..", ".."))
+	if err != nil {
+		t.Fatal(err)
+	}
+	unmoved, err := Unmoved("unmoved")
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale, added := Judge(found, unmoved, seed)
+	for _, m := range refused {
+		t.Errorf("%s is not on checks/config/unmoved and says %s", m, strings.Join(found[m], ", "))
+	}
+	for _, m := range stale {
+		t.Errorf("checks/config/unmoved names %s, which says no old name", m)
+	}
+	for _, m := range added {
+		t.Errorf("checks/config/unmoved gains %s, which its first copy did not hold", m)
+	}
+}
+
+// A mergeable file that names no keys takes every key of its module's layer (novox/hq ADR 0326 §3): the settings
+// form's last shape, which declares none of what it takes, so mesh-config could set none of it (ADR 0348 §10). It
+// is found like an old name, in a module that says no other (issue 735); one naming its keys, an empty list
+// included, is not.
+func TestAMergeableFileTakingTheWholeLayerIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "whole", `{"module":"whole","resources":[{"id":"runtime-config","type":"file","merge":"json",`+
+		`"template":"files/config.json"}]}`, map[string]string{"files/config.json": "{}\n"})
+	module(t, root, "names", `{"module":"names","config":{"url":{"type":"string","description":"d","default":""}},`+
+		`"resources":[{"id":"runtime-config","type":"file","merge":"json","takes-config":["url"],"content":"{}"}]}`, nil)
+	module(t, root, "none", `{"module":"none","resources":[{"id":"c","type":"file","merge":"json",`+
+		`"takes-config":[],"content":"{}"}]}`, nil)
+	module(t, root, "plain", `{"module":"plain","resources":[{"id":"c","type":"file","content":"{}"}]}`, nil)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{"whole": {"runtime-config taking its whole layer"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}

checks/config/unmoved

@@ -0,0 +1,5 @@
+# The modules still written in the settings form (`settings`, `takes-settings`, `${setting:<key>}`, or a mergeable
+# file naming no keys, which takes its whole layer), one per line: the catalogue's list of modules not yet moved to
+# config (novox/hq ADR 0348 §11). Every other module says config alone. This list only shrinks: a module that says no
+# old name is taken off, and a line the trunk's copy does not hold is refused. When it is empty, the controller
+# refuses the old names (design 57 package R1).

checks/imagebuild/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/imagebuild
+
+go 1.22

checks/imagebuild/main.go

@@ -0,0 +1,92 @@
+// Command imagebuild refuses any manifest but modules/buildah providing the rootless-image-build provision
+// (novox/hq ADR 0487 §3, issue 1704): the image builder's tool is buildah alone, and docker, whose daemon holds
+// the machine's root, never stands in for it. A second provider would let a node compose mesh-build-image over
+// something that is not the rootless builder it was designed against.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// Provision is the provision only Provider may provide.
+const Provision = "rootless-image-build"
+
+// Provider is the one module allowed to provide it.
+const Provider = "buildah"
+
+// Finding is one manifest refused: a module other than buildah providing the provision.
+type Finding struct {
+	Module string
+}
+
+// Check reads every manifest under root/modules and answers which ones it refuses, and whether buildah provides.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	provided := false
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module   string `json:"module"`
+			Provides []struct {
+				Name string `json:"name"`
+			} `json:"provides"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, p := range m.Provides {
+			if p.Name != Provision {
+				continue
+			}
+			if m.Module == Provider {
+				provided = true
+			} else {
+				out = append(out, Finding{Module: m.Module})
+			}
+			break
+		}
+	}
+	if !provided {
+		out = append(out, Finding{Module: Provider})
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		if f.Module == Provider {
+			fmt.Printf("%s does not provide %s (novox/hq ADR 0487 §3)\n", Provider, Provision)
+			continue
+		}
+		fmt.Printf("%s provides %s: only %s may, and docker never (novox/hq ADR 0487 §3)\n", f.Module, Provision, Provider)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("imagebuild: rootless-image-build is provided only by buildah")
+}

checks/imagebuild/main_test.go

@@ -0,0 +1,74 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+func catalogue(t *testing.T, manifests map[string]string) string {
+	t.Helper()
+	root := t.TempDir()
+	for name, body := range manifests {
+		dir := filepath.Join(root, "modules", name)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+const buildah = `{"module":"buildah","provides":[{"name":"rootless-image-build","reach":"machine"}]}`
+
+func TestOnlyBuildahProvidesTheRootlessImageBuild(t *testing.T) {
+	root := catalogue(t, map[string]string{"buildah": buildah, "go": `{"module":"go","provides":[{"name":"go-toolchain"}]}`})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Errorf("found %v, want none", got)
+	}
+}
+
+func TestDockerAndAnySecondProviderAreRefused(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"buildah": buildah,
+		"docker":  `{"module":"docker","provides":[{"name":"rootless-image-build"}]}`,
+		"other":   `{"module":"other","provides":[{"name":"x"},{"name":"rootless-image-build"}]}`,
+	})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []Finding{{Module: "docker"}, {Module: "other"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("found %v, want %v", got, want)
+	}
+}
+
+func TestBuildahMustProvideIt(t *testing.T) {
+	root := catalogue(t, map[string]string{"buildah": `{"module":"buildah"}`})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []Finding{{Module: "buildah"}}; !reflect.DeepEqual(got, want) {
+		t.Errorf("found %v, want %v", got, want)
+	}
+}
+
+// The catalogue as it stands: this is the check itself, run here too.
+func TestTheCatalogueGivesTheProvisionToBuildahAlone(t *testing.T) {
+	got, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Errorf("the catalogue's providers of rootless-image-build are wrong: %v", got)
+	}
+}

checks/imageplace/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/imageplace
+
+go 1.22

checks/imageplace/main.go

@@ -0,0 +1,91 @@
+// Command imageplace refuses an image artifact whose Dockerfile is not a file inside its own module's directory
+// (novox/hq ADR 0487 §1, issue 1707): the image builder builds a module from that module's directory alone, so
+// a `from` that leaves it (../other/Dockerfile) or names a file that is not there could never build.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// Finding is one image refused: Module's artifact Artifact names From, and Why says what is wrong with it.
+type Finding struct {
+	Module, Artifact, From, Why string
+}
+
+// Check reads every manifest under root/modules and answers which images it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module string `json:"module"`
+			Build  struct {
+				Artifacts []struct {
+					Name string `json:"name"`
+					Kind string `json:"kind"`
+					From string `json:"from"`
+				} `json:"artifacts"`
+			} `json:"build"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		dir := filepath.Dir(path)
+		for _, a := range m.Build.Artifacts {
+			if a.Kind != "image" {
+				continue
+			}
+			f := Finding{Module: m.Module, Artifact: a.Name, From: a.From}
+			clean := filepath.Clean(a.From)
+			switch {
+			case a.From == "" || filepath.IsAbs(clean) || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)):
+				f.Why = "is not a path inside the module's own directory"
+			default:
+				info, err := os.Stat(filepath.Join(dir, clean))
+				if err != nil || info.IsDir() {
+					f.Why = "is not a file in the module's directory"
+				}
+			}
+			if f.Why != "" {
+				out = append(out, f)
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s: image %s builds from %q, which %s (novox/hq ADR 0487 §1)\n", f.Module, f.Artifact, f.From, f.Why)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("imageplace: every image builds from a Dockerfile in its own module's directory")
+}

checks/imageplace/main_test.go

@@ -0,0 +1,84 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+// module writes modules/<name>/module.json with one image artifact from `from`, and the files named.
+func module(t *testing.T, root, name, from string, files ...string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `{"module":"` + name + `","build":{"artifacts":[{"name":"server","kind":"image","from":"` + from + `"},{"name":"files","kind":"archive","from":"../elsewhere"}]}}`
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	for _, f := range files {
+		p := filepath.Join(dir, f)
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte("FROM scratch\n"), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestADockerfileInTheModulesOwnDirectoryPasses(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "own", "Dockerfile", "Dockerfile")
+	module(t, root, "nested", "image/Dockerfile", "image/Dockerfile")
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Errorf("found %v, want none", got)
+	}
+}
+
+func TestADockerfileOutsideTheModulesDirectoryFails(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "other", "Dockerfile", "Dockerfile")
+	module(t, root, "leaves", "../other/Dockerfile")
+	module(t, root, "absolute", "/etc/Dockerfile")
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var mods []string
+	for _, f := range got {
+		mods = append(mods, f.Module)
+	}
+	if want := []string{"absolute", "leaves"}; !reflect.DeepEqual(mods, want) {
+		t.Errorf("refused %v (%v), want %v", mods, got, want)
+	}
+}
+
+func TestAMissingDockerfileFails(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "gone", "Dockerfile")
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].Module != "gone" {
+		t.Errorf("found %v, want gone refused", got)
+	}
+}
+
+// The catalogue as it stands: this is the check itself, run here too.
+func TestTheCataloguesImagesBuildFromTheirOwnDirectories(t *testing.T) {
+	got, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Errorf("an image builds from outside its module: %v", got)
+	}
+}

checks/locks/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/locks
+
+go 1.22

checks/locks/main.go

@@ -0,0 +1,105 @@
+// Command locks refuses a TypeScript module that names packages beyond the SDK in its package.json and commits no
+// package-lock.json (novox/hq ADR 0469 §5, issue 1868): the Node build module installs a module's own packages only
+// from its committed lock, so such a module is refused by the builder and could not be delivered.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding. The packages that count are those the build module counts (mesh-build-node fetch.go
+// ownDependencies): the `dependencies` beyond the SDK, typescript and the @types packages.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// Finding is one module refused: it names Packages beyond the SDK and has no lock file.
+type Finding struct {
+	Module   string
+	Packages []string
+}
+
+// Check reads every module under root/modules that builds a TypeScript artifact.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module string `json:"module"`
+			Build  struct {
+				Artifacts []struct {
+					Language string `json:"language"`
+				} `json:"artifacts"`
+			} `json:"build"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		typescript := false
+		for _, a := range m.Build.Artifacts {
+			typescript = typescript || a.Language == "typescript"
+		}
+		if !typescript {
+			continue
+		}
+		dir := filepath.Dir(path)
+		pkgRaw, err := os.ReadFile(filepath.Join(dir, "package.json"))
+		if os.IsNotExist(err) {
+			continue
+		}
+		if err != nil {
+			return nil, err
+		}
+		var pkg struct {
+			Dependencies map[string]json.RawMessage `json:"dependencies"`
+		}
+		if err := json.Unmarshal(pkgRaw, &pkg); err != nil {
+			return nil, fmt.Errorf("%s: package.json: %w", m.Module, err)
+		}
+		var names []string
+		for n := range pkg.Dependencies {
+			if n != "@novox/mesh-sdk" && n != "typescript" && !strings.HasPrefix(n, "@types/") {
+				names = append(names, n)
+			}
+		}
+		if len(names) == 0 {
+			continue
+		}
+		if _, err := os.Stat(filepath.Join(dir, "package-lock.json")); err != nil {
+			sort.Strings(names)
+			out = append(out, Finding{Module: m.Module, Packages: names})
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s names packages beyond the SDK (%s) and has no package-lock.json: commit one made by the build module's toolchain (novox/hq ADR 0469 §5)\n", f.Module, strings.Join(f.Packages, ", "))
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("locks: every TypeScript module that names packages beyond the SDK commits its lock")
+}

checks/locks/main_test.go

@@ -0,0 +1,63 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+// module writes modules/<name> with a TypeScript artifact, the package.json given ("" for none) and, when lock, a lock.
+func module(t *testing.T, root, name, language, pkg string, lock bool) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	write := func(file, body string) {
+		if err := os.WriteFile(filepath.Join(dir, file), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write("module.json", `{"module":"`+name+`","build":{"artifacts":[{"name":"tools","kind":"bundle","language":"`+language+`","from":"index.ts"}]}}`)
+	if pkg != "" {
+		write("package.json", pkg)
+	}
+	if lock {
+		write("package-lock.json", "{}")
+	}
+}
+
+const sdkOnly = `{"dependencies":{"@novox/mesh-sdk":"^0.1.1"},"devDependencies":{"typescript":"^5","@types/node":"^22"}}`
+const withPg = `{"dependencies":{"@novox/mesh-sdk":"^0.1.1","pg":"^8","@types/pg":"^8"}}`
+
+func TestAModuleNamingOnlyTheSDKNeedsNoLock(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "plain", "typescript", sdkOnly, false)
+	module(t, root, "none", "typescript", "", false)
+	got, err := Check(root)
+	if err != nil || len(got) != 0 {
+		t.Fatalf("%v %v", got, err)
+	}
+}
+
+func TestAModuleNamingMorePackagesWithoutALockIsRefusedNamingThem(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "db", "typescript", withPg, false)
+	module(t, root, "db-locked", "typescript", withPg, true)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []Finding{{Module: "db", Packages: []string{"pg"}}}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("got %v, want %v", got, want)
+	}
+}
+
+func TestAModuleThatIsNotTypeScriptIsNotJudged(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "go", "go", withPg, false)
+	if got, err := Check(root); err != nil || len(got) != 0 {
+		t.Fatalf("%v %v", got, err)
+	}
+}

checks/mailstore/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/mailstore
+
+go 1.22

checks/mailstore/main.go

@@ -0,0 +1,81 @@
+// Command mailstore refuses any manifest but modules/mesh-mail claiming the mail-store seat (novox/hq ADR 0378
+// §3, issue 800 part A): the operator's mail is read, searched and sent through this one seat, and a second
+// claimant would be a second path to the same mail that ADR 0378 never accounted for.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// MailStoreSeat is the seat only mesh-mail may claim.
+const MailStoreSeat = "mail-store"
+
+// MailStoreModule is the one module allowed to claim it.
+const MailStoreModule = "mesh-mail"
+
+// Finding is one manifest refused: a module other than mesh-mail claiming mail-store.
+type Finding struct {
+	Module string
+}
+
+// Check reads every manifest under root/modules and answers which ones it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module string `json:"module"`
+			Claims []struct {
+				Name string `json:"name"`
+			} `json:"claims"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		if m.Module == MailStoreModule {
+			continue
+		}
+		for _, c := range m.Claims {
+			if c.Name == MailStoreSeat {
+				out = append(out, Finding{Module: m.Module})
+				break
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s claims the mail-store seat: only %s may (novox/hq ADR 0378 §3)\n", f.Module, MailStoreModule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("mail-store: claimed only by mesh-mail")
+}

checks/mailstore/main_test.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, claims string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	body := `{"module":"` + module + `","claims":[` + claims + `]}`
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnotherModuleClaimingMailStoreIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "mesh-mail", `{"name":"mail-store","scope":"mesh"}`)
+	manifest(t, root, "betterbird", `{"name":"mail-store","scope":"mesh"}`)
+	manifest(t, root, "dunst", `{"name":"node-notifier","scope":"node"}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "betterbird" {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestTheCatalogueHasNone(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("%+v", found)
+	}
+}

checks/owned/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/owned
+
+go 1.22

checks/owned/main.go

@@ -0,0 +1,242 @@
+// Command owned judges how the catalogue's directories and archives treat files they did not write (novox/hq
+// ADR 0422 §8, issue 1024). It refuses, naming the module, the resource and the reason:
+//
+//  1. a directory or archive without `unknown`, or with a value but move-out, module or program;
+//
+//  2. `move-out` on a path not under ${machine:account-home} or ${machine:agent-home};
+//
+//  3. `knows` with an empty, absolute, `.`/`..`/empty-component or repeated path;
+//
+//  4. a path one module declares (a resource's path, or a fact with "home": true) lying inside a directory of
+//     another module, after ${dir:<id>} is resolved within each module and both homes are read as one root.
+//     Archives are not containers for this rule. This holds for ~/.ssh what checks/sshdir held (ADR 0415 §6).
+//
+//     go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Home is the one root both machine homes are read as.
+const Home = "${home}"
+
+var (
+	ofDir   = regexp.MustCompile(`\$\{dir:([a-z0-9][a-z0-9_-]*)\}`)
+	homeVar = strings.NewReplacer("${machine:account-home}", Home, "${machine:agent-home}", Home)
+	values  = map[string]bool{"move-out": true, "module": true, "program": true}
+)
+
+// Finding is one refusal.
+type Finding struct {
+	Rule            int
+	Module, ID, Why string
+}
+
+type resource struct {
+	ID, Type, Path, Unknown string
+	Knows                   []string
+	HasKnows                bool
+}
+
+type parsed struct {
+	Module    string
+	Resources []resource
+	Facts     []string // paths of facts with "home": true, under the home
+}
+
+func load(file string) (*parsed, error) {
+	raw, err := os.ReadFile(file)
+	if err != nil {
+		return nil, err
+	}
+	var m struct {
+		Module    string `json:"module"`
+		Resources []struct {
+			ID      string   `json:"id"`
+			Type    string   `json:"type"`
+			Path    string   `json:"path"`
+			Unknown *string  `json:"unknown"`
+			Knows   []string `json:"knows"`
+		} `json:"resources"`
+		Facts map[string]struct {
+			Path string `json:"path"`
+			Home bool   `json:"home"`
+		} `json:"facts"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, fmt.Errorf("%s: %w", file, err)
+	}
+	out := &parsed{Module: m.Module}
+	if out.Module == "" {
+		out.Module = filepath.Base(filepath.Dir(file))
+	}
+	for _, r := range m.Resources {
+		x := resource{ID: r.ID, Type: r.Type, Path: r.Path, Knows: r.Knows, HasKnows: r.Knows != nil}
+		if r.Unknown != nil {
+			x.Unknown = *r.Unknown
+			if x.Unknown == "" {
+				x.Unknown = "(empty)"
+			}
+		}
+		out.Resources = append(out.Resources, x)
+	}
+	keys := make([]string, 0, len(m.Facts))
+	for k := range m.Facts {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	for _, k := range keys {
+		if f := m.Facts[k]; f.Home && f.Path != "" {
+			out.Facts = append(out.Facts, f.Path)
+		}
+	}
+	return out, nil
+}
+
+// norm resolves ${dir:<id>} from the module's own resources, reads both homes as one root and cleans the path.
+func norm(p string, dirs map[string]string) string {
+	for i := 0; i < 8 && ofDir.MatchString(p); i++ {
+		p = ofDir.ReplaceAllStringFunc(p, func(w string) string {
+			if to, ok := dirs[ofDir.FindStringSubmatch(w)[1]]; ok {
+				return to
+			}
+			return w
+		})
+	}
+	p = homeVar.Replace(p)
+	if p == "" {
+		return ""
+	}
+	return path.Clean(p)
+}
+
+func underHome(p string) bool { return strings.HasPrefix(p, Home+"/") }
+
+// badKnows says why a knows entry is refused, or "".
+func badKnows(k string) string {
+	if k == "" {
+		return "is empty"
+	}
+	if strings.HasPrefix(k, "/") {
+		return "is absolute"
+	}
+	for _, c := range strings.Split(strings.TrimSuffix(k, "/"), "/") {
+		if c == "" || c == "." || c == ".." {
+			return "has an empty, . or .. component"
+		}
+	}
+	return ""
+}
+
+type declared struct {
+	module, id, path string
+}
+
+// Check reads every manifest under root/modules and answers what it refuses.
+func Check(root string) ([]Finding, error) {
+	files, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(files)
+	var out []Finding
+	var paths []declared
+	type container struct{ module, path string }
+	var containers []container
+	for _, file := range files {
+		m, err := load(file)
+		if err != nil {
+			return nil, err
+		}
+		dirs := map[string]string{}
+		for _, r := range m.Resources {
+			switch {
+			case r.ID != "" && r.Path != "":
+				dirs[r.ID] = r.Path
+			case r.ID != "" && r.Type == "directory":
+				// A directory the mesh places for the module (`place`): where it lies is the node-engine's, but it is
+				// the module's own, so a path under it belongs to this module and to no other's directory of the same
+				// id (issue 1484: two runs-as modules each keep a .ssh in their own state directory).
+				dirs[r.ID] = "/placed/" + m.Module + "/" + r.ID
+			}
+		}
+		for _, r := range m.Resources {
+			p := norm(r.Path, dirs)
+			if p != "" {
+				paths = append(paths, declared{m.Module, r.ID, p})
+			}
+			if r.Type != "directory" && r.Type != "archive" {
+				continue
+			}
+			if r.Type == "directory" && p != "" {
+				containers = append(containers, container{m.Module, p})
+			}
+			add := func(rule int, why string) { out = append(out, Finding{rule, m.Module, r.ID, why}) }
+			switch {
+			case r.Unknown == "":
+				add(1, "a "+r.Type+" without `unknown` (move-out, module or program)")
+			case !values[r.Unknown]:
+				add(1, fmt.Sprintf("`unknown` is %q, not move-out, module or program", r.Unknown))
+			case r.Unknown == "move-out" && !underHome(p):
+				add(2, fmt.Sprintf("`move-out` on %q, which is not under ${machine:account-home} or ${machine:agent-home}", r.Path))
+			}
+			seen := map[string]bool{}
+			for _, k := range r.Knows {
+				if why := badKnows(k); why != "" {
+					add(3, fmt.Sprintf("`knows` entry %q %s", k, why))
+					continue
+				}
+				c := strings.TrimSuffix(k, "/")
+				if seen[c] {
+					add(3, fmt.Sprintf("`knows` entry %q is repeated", k))
+				}
+				seen[c] = true
+			}
+			if r.HasKnows && len(r.Knows) == 0 {
+				add(3, "`knows` is empty")
+			}
+		}
+		for _, f := range m.Facts {
+			if p := norm(Home+"/"+f, nil); p != "" {
+				paths = append(paths, declared{m.Module, "fact " + f, p})
+			}
+		}
+	}
+	for _, d := range paths {
+		for _, c := range containers {
+			if c.module != d.module && (d.path == c.path || strings.HasPrefix(d.path, c.path+"/")) {
+				out = append(out, Finding{4, d.module, d.id, fmt.Sprintf("declares %q, inside a directory of %s (%q)", d.path, c.module, c.path)})
+			}
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s: %s: %s (rule %d, novox/hq ADR 0422 §8, issue 1024)\n", f.Module, f.ID, f.Why, f.Rule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("owned paths: every directory and archive says how it treats unknown files; no module declares inside another's directory")
+}

checks/owned/main_test.go

@@ -0,0 +1,147 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func check(t *testing.T, root string) []Finding {
+	t.Helper()
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return found
+}
+
+// only asserts exactly one finding, of the rule, naming the module and the resource (issue 1024).
+func only(t *testing.T, found []Finding, rule int, module, id string) {
+	t.Helper()
+	if len(found) != 1 || found[0].Rule != rule || found[0].Module != module || found[0].ID != id || found[0].Why == "" {
+		t.Fatalf("found %+v; want one finding of rule %d for %s/%s with a reason", found, rule, module, id)
+	}
+}
+
+func dir(id, path, rest string) string {
+	return `{"id":"` + id + `","type":"directory","path":"` + path + `"` + rest + `}`
+}
+
+func mod(name string, resources ...string) string {
+	return `{"module":"` + name + `","resources":[` + strings.Join(resources, ",") + `]}`
+}
+
+func TestMissingOrUnknownValueIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "/var/lib/a", "")))
+	only(t, check(t, root), 1, "a", "d")
+
+	root = t.TempDir()
+	manifest(t, root, "a", mod("a", `{"id":"z","type":"archive","path":"/opt/a","unknown":"delete"}`))
+	only(t, check(t, root), 1, "a", "z")
+}
+
+func TestMoveOutOutsideAHomeIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "/etc/a.d", `,"unknown":"move-out"`)))
+	only(t, check(t, root), 2, "a", "d")
+}
+
+func TestMoveOutUnderAHomeIsAllowed(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a",
+		dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out"`),
+		dir("e", "${dir:d}/sub", `,"unknown":"move-out"`),
+		dir("f", "${machine:agent-home}/x", `,"unknown":"move-out"`),
+		dir("g", "/var/lib/a", `,"unknown":"program"`),
+		dir("h", "${machine:account-home}/.ssh", `,"unknown":"module"`)))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestBadKnowsIsRefused(t *testing.T) {
+	for _, knows := range []string{`[""]`, `["/abs"]`, `["a/../b"]`, `["./a"]`, `["a//b"]`, `["a","a"]`, `["a","a/"]`} {
+		root := t.TempDir()
+		manifest(t, root, "a", mod("a", dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out","knows":`+knows)))
+		only(t, check(t, root), 3, "a", "d")
+	}
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a", dir("d", "${machine:account-home}/.config/a", `,"unknown":"move-out","knows":["forge.credentials","kept/"]`)))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+func TestAnotherModulesPathInsideADirectoryIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "owner", mod("owner", dir("ssh", "${machine:account-home}/.ssh", `,"unknown":"module"`)))
+	manifest(t, root, "intruder", mod("intruder", `{"id":"f","type":"file","path":"${machine:account-home}/.ssh/config.d/20"}`))
+	manifest(t, root, "viahome", mod("viahome", `{"id":"g","type":"file","path":"${machine:agent-home}/.ssh/x"}`))
+	manifest(t, root, "facty", `{"module":"facty","facts":{"hosts":{"path":".ssh/config.d/00","home":true}}}`)
+	manifest(t, root, "outside", mod("outside", `{"id":"o","type":"file","path":"${machine:account-home}/.sshrc"}`))
+	got := map[string]int{}
+	for _, f := range check(t, root) {
+		if f.Rule != 4 || f.Why == "" {
+			t.Fatalf("finding %+v", f)
+		}
+		got[f.Module]++
+	}
+	if len(got) != 3 || got["intruder"] != 1 || got["viahome"] != 1 || got["facty"] != 1 {
+		t.Fatalf("refused %v; want intruder, viahome, facty", got)
+	}
+}
+
+func TestDirReferencesAreResolvedPerModule(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "owner", mod("owner", dir("base", "${machine:account-home}/.config/o", `,"unknown":"move-out"`)))
+	manifest(t, root, "other", mod("other",
+		dir("base", "${machine:account-home}/.config/p", `,"unknown":"move-out"`),
+		`{"id":"f","type":"file","path":"${dir:base}/x"}`))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+	manifest(t, root, "third", mod("third",
+		dir("d", "${machine:account-home}/.config/t", `,"unknown":"move-out"`),
+		`{"id":"f","type":"file","path":"${dir:d}/../o/x"}`))
+	only(t, check(t, root), 4, "third", "f")
+}
+
+func TestAnArchiveIsNotAContainerAndSameModuleIsFine(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", mod("a",
+		`{"id":"arc","type":"archive","path":"/opt/a","unknown":"program"}`,
+		dir("d", "/opt/a2", `,"unknown":"program"`),
+		`{"id":"f","type":"file","path":"/opt/a2/x"}`))
+	manifest(t, root, "b", mod("b", `{"id":"f","type":"file","path":"/opt/a/x"}`))
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}
+
+// Issue 1484: a directory the mesh places for a module (no path, `place`) is that module's own: another module's
+// directory of the same id, and a path under it, are not inside it.
+func TestPlacedDirectoriesOfTwoModulesAreTheirOwn(t *testing.T) {
+	root := t.TempDir()
+	for _, name := range []string{"first", "second"} {
+		manifest(t, root, name, mod(name,
+			`{"id":"state","type":"directory","place":".","unknown":"program"}`,
+			dir("ssh", "${dir:state}/.ssh", `,"unknown":"program"`),
+			`{"id":"conf","type":"file","path":"${dir:ssh}/config"}`))
+	}
+	if found := check(t, root); len(found) != 0 {
+		t.Fatalf("refused %+v", found)
+	}
+}

checks/particulars/covered

@@ -0,0 +1,3 @@
+# The modules the check covers (novox/hq ADR 0507 §9, issue 1838), one a line; issue 1838 widens it.
+pacman
+kernel

checks/particulars/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/particulars
+
+go 1.22

checks/particulars/main.go

@@ -0,0 +1,159 @@
+// Command particulars keeps this mesh's node names out of the modules it covers (novox/hq ADR 0507 §9,
+// issue 1838): a module is for any mesh, so no manifest, file, code string, identifier, comment, test name or
+// fixture of a covered module names a node of this one.
+//
+// The names are in the file `particulars` at the catalogue's root, one a line, `#` comments — the one place
+// they may be written. The modules covered are in `covered` at checks/particulars/covered, one a line. A name is matched
+// whole and in any case; a hyphen, an underscore or a CamelCase boundary parts one, so a longer word holding a name is another word.
+// The forge is not a node name: its host (git.novox.be) and the organisation path (novox/<repo>) are blanked
+// before a line is read.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 naming file:line and the word, 2 when a list cannot be read.
+package main
+
+import (
+	"bufio"
+	"bytes"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// forge is the forge's host and organisation path, blanked before a line is read; a path segment novox/ elsewhere
+// (testdata/novox/x, /srv/novox/data) is not blanked.
+var forge = regexp.MustCompile(`(?i)git\.novox\.be(?:/novox/[\w.-]+)?|(?:^|[^/\w.-])novox/[\w.-]+`)
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	os.Exit(check(root))
+}
+
+// check runs the check over a catalogue and returns the exit code: 0 clean, 1 a finding, 2 a list unreadable.
+func check(root string) int {
+	names, err := readList(filepath.Join(root, "particulars"))
+	if err == nil && len(names) == 0 {
+		err = fmt.Errorf("particulars lists no name — the check would pass on anything")
+	}
+	var covered []string
+	if err == nil {
+		covered, err = readList(filepath.Join(root, "checks/particulars/covered"))
+		if err == nil && len(covered) == 0 {
+			err = fmt.Errorf("covered lists no module — the check would pass on anything")
+		}
+	}
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "particulars:", err)
+		return 2
+	}
+	findings, err := run(root, names, covered)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "particulars:", err)
+		return 2
+	}
+	for _, f := range findings {
+		fmt.Println(f)
+	}
+	if len(findings) > 0 {
+		fmt.Printf("particulars: %d node name(s) in a module for any mesh (novox/hq ADR 0507 §9) — say what it shows, not where it was seen\n", len(findings))
+		return 1
+	}
+	fmt.Printf("particulars: none of %d node names in the %d covered modules\n", len(names), len(covered))
+	return 0
+}
+
+// readList reads a list: one entry a line; blank lines and lines starting with # are not entries.
+func readList(path string) ([]string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	var out []string
+	sc := bufio.NewScanner(f)
+	for sc.Scan() {
+		line := strings.TrimSpace(sc.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out = append(out, line)
+	}
+	return out, sc.Err()
+}
+
+// run reads every text file of each covered module and returns the findings, sorted.
+func run(root string, names, covered []string) ([]string, error) {
+	var out []string
+	for _, m := range covered {
+		dir := filepath.Join(root, "modules", m)
+		err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+			if err != nil {
+				return err
+			}
+			if d.IsDir() {
+				switch d.Name() {
+				case "node_modules", "dist", "vendor", ".git":
+					return filepath.SkipDir
+				}
+				return nil
+			}
+			rel, _ := filepath.Rel(root, path)
+			// A path is read too: a testdata directory named after a node is a finding.
+			for _, n := range hits(filepath.ToSlash(rel), names) {
+				out = append(out, fmt.Sprintf("%s:0: node name %q in the path", filepath.ToSlash(rel), n))
+			}
+			if d.Name() == "go.sum" {
+				return nil
+			}
+			b, err := os.ReadFile(path)
+			if err != nil {
+				return err
+			}
+			if bytes.IndexByte(b, 0) >= 0 {
+				return nil
+			}
+			out = append(out, scan(filepath.ToSlash(rel), string(b), names)...)
+			return nil
+		})
+		if err != nil {
+			return nil, err
+		}
+	}
+	sort.Strings(out)
+	return out, nil
+}
+
+// scan returns a finding for each node name in src, whole-word and in any case.
+func scan(file, src string, names []string) []string {
+	var out []string
+	for i, line := range strings.Split(src, "\n") {
+		for _, n := range hits(line, names) {
+			out = append(out, fmt.Sprintf("%s:%d: node name %q — %s", file, i+1, n, strings.Join(strings.Fields(line), " ")))
+		}
+	}
+	return out
+}
+
+// hits returns the node names one line holds: as a word (a hyphen or underscore parts it), as a part of a
+// CamelCase identifier (TestAce, novoxTree), the forge's host and organisation path blanked first.
+func hits(line string, names []string) []string {
+	line = forge.ReplaceAllStringFunc(line, func(s string) string { return strings.Repeat(" ", len(s)) })
+	var out []string
+	for _, n := range names {
+		q := regexp.QuoteMeta(n)
+		camel := regexp.QuoteMeta(strings.ToUpper(n[:1]) + n[1:])
+		rx := regexp.MustCompile(`(?i:(?:^|[^A-Za-z0-9])` + q + `(?:$|[^A-Za-z0-9]))|[a-z0-9]` + camel + `(?:$|[^a-z])|(?:^|[^A-Za-z0-9])` + q + `[A-Z0-9]`)
+		if rx.MatchString(line) {
+			out = append(out, strings.ToLower(n))
+		}
+	}
+	return out
+}

checks/particulars/main_test.go

@@ -0,0 +1,116 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+var names = []string{"novox", "ace", "shanks", "g14"}
+
+func TestANodeNameIsRefusedWhereItIsWritten(t *testing.T) {
+	cases := map[string]struct{ file, src string }{
+		"manifest string": {"modules/kernel/module.json", "{\n \"description\": \"as on Shanks\"\n}\n"},
+		"file line":       {"modules/kernel/files/boot.sh", "#!/bin/sh\necho run on g14\n"},
+		"go identifier":   {"modules/kernel/cmd/x/a.go", "package main\n\nfunc novox() {}\n"},
+		"test name":       {"modules/kernel/cmd/x/a_test.go", "package main\n\nfunc TestAce(t *testing.T) {}\n\nfunc TestOnAce_x(t *testing.T) {}\n"},
+	}
+	for name, c := range cases {
+		if got := scan(c.file, c.src, names); len(got) == 0 {
+			t.Errorf("%s: %q not refused", name, c.src)
+		}
+	}
+}
+
+func TestTheFindingNamesTheLineAndTheWord(t *testing.T) {
+	got := scan("f.sh", "a\nb\nrun on ACE now\n", names)
+	if len(got) != 1 || !strings.HasPrefix(got[0], "f.sh:3:") || !strings.Contains(got[0], "ace") {
+		t.Errorf("got %v", got)
+	}
+}
+
+func TestTheForgeIsNotANodeName(t *testing.T) {
+	for _, s := range []string{
+		"see novox/hq issue 5",
+		"module git.novox.be/novox/mesh-sdk/go v1.2.3",
+		"https://git.novox.be/novox/mesh-catalog",
+		"git.novox.be",
+		"space trace surface grace g14x",
+	} {
+		if got := scan("f", s, names); len(got) != 0 {
+			t.Errorf("%q refused: %v", s, got)
+		}
+	}
+}
+
+func TestANodeNameInAPathOrJoinedIsRefused(t *testing.T) {
+	for _, s := range []string{
+		"modules/kernel/testdata/novox/meminfo",
+		"/srv/novox/data",
+		"testdata/shanks-meminfo.txt",
+		"on-shanks",
+		"shanks-desktop",
+		"mesh-novox",
+		"func novoxTree() {}",
+		"aceFiles := 1",
+		"g14Meminfo := 2",
+		"novox_tree := 3",
+	} {
+		if got := scan("f", s, names); len(got) == 0 {
+			t.Errorf("%q not refused", s)
+		}
+	}
+}
+
+func TestANodeNamedPathIsRefusedThroughRun(t *testing.T) {
+	root := t.TempDir()
+	p := filepath.Join(root, "modules/kernel/testdata/ace/x")
+	os.MkdirAll(filepath.Dir(p), 0o755)
+	os.WriteFile(p, []byte("clean\n"), 0o644)
+	got, err := run(root, names, []string{"kernel"})
+	if err != nil || len(got) != 1 || !strings.HasPrefix(got[0], "modules/kernel/testdata/ace/x:0: ") {
+		t.Errorf("got %v, %v", got, err)
+	}
+}
+
+func TestCheckReturnsOneOnAFindingAndTwoOnAnUnreadableList(t *testing.T) {
+	root := t.TempDir()
+	write := func(p, s string) {
+		p = filepath.Join(root, p)
+		os.MkdirAll(filepath.Dir(p), 0o755)
+		os.WriteFile(p, []byte(s), 0o644)
+	}
+	write("particulars", "ace\n")
+	write("checks/particulars/covered", "kernel\n")
+	write("modules/kernel/a", "clean\n")
+	if got := check(root); got != 0 {
+		t.Errorf("clean = %d, want 0", got)
+	}
+	write("modules/kernel/a", "on ace\n")
+	if got := check(root); got != 1 {
+		t.Errorf("finding = %d, want 1", got)
+	}
+	os.Remove(filepath.Join(root, "particulars"))
+	if got := check(root); got != 2 {
+		t.Errorf("no list = %d, want 2", got)
+	}
+}
+
+func TestOnlyCoveredModulesAreRead(t *testing.T) {
+	root := t.TempDir()
+	write := func(p, s string) {
+		p = filepath.Join(root, p)
+		os.MkdirAll(filepath.Dir(p), 0o755)
+		os.WriteFile(p, []byte(s), 0o644)
+	}
+	write("modules/kernel/files/a", "on novox\n")
+	write("modules/other/files/a", "on novox\n")
+	got, err := run(root, names, []string{"kernel"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || !strings.Contains(got[0], "modules/kernel/files/a:1") {
+		t.Errorf("got %v", got)
+	}
+}

checks/predefined/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/predefined
+
+go 1.22

checks/predefined/main.go

@@ -0,0 +1,153 @@
+// Command predefined refuses a change to predefined.json that removes a key a module still names (novox/hq ADR
+// 0348 clause 7, design 57 package K2, issue 661).
+//
+// Mesh config and node config hold values only for the keys on the catalogue's list of predefined keys, at the
+// root of the repository; a module's config value may fall back to one, `"predefined": "<key>"`. A key removed
+// while a manifest still names it would leave that module falling back to nothing: the controller refuses its
+// build then, at the next merge that touches it. So the removal is refused here, in the pull request that makes
+// it, naming each module that names the key.
+//
+// **What it cannot know.** Whether a key still holds a value at the mesh or a node is mesh-config's to say (design
+// 57 package K3): it holds the values, and the catalogue's check reads no store. Until mesh-config refuses that
+// itself, removing a key nobody names is let through here, and said.
+//
+// The list it compares with is the trunk's at the merge base, given with -base; without one, nothing was removed.
+// The controller the mesh runs reads the list itself (type, validation, every manifest against it) in the
+// module check; this check reads only its keys.
+//
+//	go run . [-base <the trunk's predefined.json>] <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+// File is the list's file at the root of the catalogue.
+const File = "predefined.json"
+
+// Keys is the keys of a list, read as a JSON object; an absent file has none.
+func Keys(path string) (map[string]bool, error) {
+	raw, err := os.ReadFile(path)
+	if errors.Is(err, fs.ErrNotExist) {
+		return map[string]bool{}, nil
+	}
+	if err != nil {
+		return nil, err
+	}
+	var keys map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keys); err != nil {
+		return nil, fmt.Errorf("%s is not a JSON object of keys: %w", path, err)
+	}
+	out := map[string]bool{}
+	for k := range keys {
+		out[k] = true
+	}
+	return out, nil
+}
+
+// Named is, per predefined key, the modules whose manifests name it: under `config`, or its alias `settings`.
+func Named(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	named := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module   string                     `json:"module"`
+			Config   map[string]json.RawMessage `json:"config"`
+			Settings map[string]json.RawMessage `json:"settings"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, declared := range []map[string]json.RawMessage{m.Config, m.Settings} {
+			for _, d := range declared {
+				var value struct {
+					Predefined string `json:"predefined"`
+				}
+				if json.Unmarshal(d, &value) == nil && value.Predefined != "" {
+					named[value.Predefined] = append(named[value.Predefined], m.Module)
+				}
+			}
+		}
+	}
+	return named, nil
+}
+
+// Removed is each key the base list holds and the tree's does not, with the modules still naming it; a removed
+// key nobody names is answered with none.
+func Removed(base, tree map[string]bool, named map[string][]string) map[string][]string {
+	out := map[string][]string{}
+	for k := range base {
+		if !tree[k] {
+			out[k] = named[k]
+		}
+	}
+	return out
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's predefined.json at the merge base")
+	flag.Parse()
+	if flag.NArg() != 1 {
+		fmt.Fprintln(os.Stderr, "usage: predefined [-base <the trunk's predefined.json>] <catalogue root>")
+		os.Exit(2)
+	}
+	root := flag.Arg(0)
+	tree, err := Keys(filepath.Join(root, File))
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	if *basePath == "" {
+		fmt.Printf("%s: %d key(s); no trunk list given, so none was removed\n", File, len(tree))
+		return
+	}
+	base, err := Keys(*basePath)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	named, err := Named(root)
+	if err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+	removed := Removed(base, tree, named)
+	keys := make([]string, 0, len(removed))
+	for k := range removed {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	failed := false
+	for _, k := range keys {
+		if modules := removed[k]; len(modules) > 0 {
+			failed = true
+			fmt.Printf("%s: the key %q is removed and still named by %s: move each off it first (novox/hq ADR 0348 "+
+				"clause 7)\n", File, k, strings.Join(modules, ", "))
+		} else {
+			fmt.Printf("%s: the key %q is removed and no module names it; whether the mesh or a node still holds a "+
+				"value for it is mesh-config's to refuse, not this check's\n", File, k)
+		}
+	}
+	if failed {
+		os.Exit(1)
+	}
+	fmt.Printf("%s: %d key(s), none removed that a module names\n", File, len(tree))
+}

checks/predefined/main_test.go

@@ -0,0 +1,100 @@
+package main
+
+import (
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// A catalogue whose dunst falls back to font-size, and the trunk's list holding font-size and
+// agent-managed-settings.
+func aCatalogue(t *testing.T, list string) (root, base string) {
+	t.Helper()
+	root = t.TempDir()
+	write := func(path, text string) {
+		t.Helper()
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(path, []byte(text), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	write(filepath.Join(root, "modules", "dunst", "module.json"), `{"module": "dunst", "config": {"font-size":
+	  {"type": "number", "description": "points", "default": 10, "predefined": "font-size"}}}`)
+	write(filepath.Join(root, "modules", "claude-code", "module.json"), `{"module": "claude-code", "settings": {
+	  "managed_settings": {"kind": "preference", "default": "{}", "why": "none"}}}`)
+	write(filepath.Join(root, "modules", "plain", "module.json"), `{"module": "plain"}`)
+	if list != "" {
+		write(filepath.Join(root, File), list)
+	}
+	base = filepath.Join(t.TempDir(), "base.json")
+	write(base, `{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}}`)
+	return root, base
+}
+
+func run(t *testing.T, args ...string) (string, error) {
+	t.Helper()
+	out, err := exec.Command("go", append([]string{"run", "."}, args...)...).CombinedOutput()
+	return string(out), err
+}
+
+func TestARemovalOfAKeyAModuleStillNamesIsRefused(t *testing.T) {
+	// The planted removal: font-size goes while dunst still falls back to it.
+	root, base := aCatalogue(t, `{"agent-managed-settings": {"type": "object"}}`)
+	out, err := run(t, "-base", base, root)
+	if err == nil || !strings.Contains(out, `the key "font-size" is removed and still named by dunst`) {
+		t.Fatalf("a removal of a named key passed:\n%s", out)
+	}
+}
+
+func TestARemovalNobodyNamesPassesAndSaysWhatItCannotKnow(t *testing.T) {
+	root, base := aCatalogue(t, `{"font-size": {"type": "number"}}`)
+	out, err := run(t, "-base", base, root)
+	if err != nil || !strings.Contains(out, `"agent-managed-settings" is removed and no module names it`) ||
+		!strings.Contains(out, "mesh-config's to refuse") {
+		t.Fatalf("a removal nobody names: %v\n%s", err, out)
+	}
+}
+
+func TestAListUnchangedOrGrownPasses(t *testing.T) {
+	for _, list := range []string{
+		`{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}}`,
+		`{"font-size": {"type": "number"}, "agent-managed-settings": {"type": "object"}, "accent": {"type": "string"}}`,
+	} {
+		root, base := aCatalogue(t, list)
+		if out, err := run(t, "-base", base, root); err != nil || !strings.Contains(out, "none removed") {
+			t.Fatalf("%s: %v\n%s", list, err, out)
+		}
+	}
+	// No trunk list given: nothing was removed.
+	root, _ := aCatalogue(t, `{}`)
+	if out, err := run(t, root); err != nil || !strings.Contains(out, "none was removed") {
+		t.Fatalf("without a base: %v\n%s", err, out)
+	}
+}
+
+func TestTheFileRemovedWholeIsARemovalOfEveryKey(t *testing.T) {
+	root, base := aCatalogue(t, "")
+	out, err := run(t, "-base", base, root)
+	if err == nil || !strings.Contains(out, `"font-size" is removed and still named by dunst`) {
+		t.Fatalf("the list removed whole passed:\n%s", out)
+	}
+}
+
+func TestNamedReadsBothForms(t *testing.T) {
+	root, _ := aCatalogue(t, "")
+	if err := os.WriteFile(filepath.Join(root, "modules", "plain", "module.json"), []byte(`{"module": "plain",
+	  "settings": {"size": {"predefined": "font-size"}}}`), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	named, err := Named(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := strings.Join(named["font-size"], ","); got != "dunst,plain" {
+		t.Fatalf("font-size named by %s", got)
+	}
+}

checks/secrets/main.go

@@ -7,7 +7,8 @@
 // until somebody removed it by hand. The controller refuses a setting of a key the file keeps as `protected`,
 // naming the layer and the key, never the value. This check holds every such file to that: each top-level key
 // whose value holds `${secret:…}`, anywhere below it, is either listed in the file's `protected`, or left out
-// of the file's `takes-settings` (novox/hq ADR 0326), so that no layer reaches it.
+// of the file's `takes-settings` (novox/hq ADR 0326), so that no layer reaches it. A file whose text is a template
+// in files/ is judged by the template's text.
 //
 // A secret nested below a key the file takes for its other values (`server.secret_key` below `server`) cannot
 // be protected alone today: the controller protects top-level keys. Such a file is named in the file `known`
@@ -64,6 +65,15 @@ func Check(root string) ([]Finding, error) {
 			}
 			id, _ := r["id"].(string)
 			content, _ := r["content"].(string)
+			// A file whose text is a template in its module's files/ (novox/hq ADR 0349 §2) is judged by that text,
+			// exactly as it would be inline.
+			if name, _ := r["template"].(string); name != "" {
+				text, err := os.ReadFile(filepath.Join(filepath.Dir(path), filepath.FromSlash(name)))
+				if err != nil {
+					return nil, fmt.Errorf("%s: %s names the template %s: %w", m.Module, id, name, err)
+				}
+				content = string(text)
+			}
 			var doc map[string]any
 			if strings.TrimSpace(content) == "" {
 				continue

checks/secrets/main_test.go

@@ -51,6 +51,35 @@ func TestASecretASettingCouldReplaceIsRefused(t *testing.T) {
 	}
 }
 
+// A mergeable file whose text is a template in files/ (novox/hq ADR 0349 §2) is judged by the template's text,
+// exactly as the same text inline; a template the module's directory lacks is an error, never a silent pass.
+func TestAMergeableFilesTemplateIsJudgedAsItsText(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "a", `{"id":"cfg","type":"file","merge":"json","template":"files/cfg.json"}`)
+	manifest(t, root, "c", `{"id":"cfg","type":"file","merge":"json","protected":["password"],"template":"files/cfg.json"}`)
+	for _, m := range []string{"a", "c"} {
+		dir := filepath.Join(root, "modules", m, "files")
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "cfg.json"), []byte(`{"password": "${secret:admin}"}`), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].String() != "a cfg password" {
+		t.Fatalf("found %v, want [a cfg password]", found)
+	}
+
+	manifest(t, root, "g", `{"id":"cfg","type":"file","merge":"json","template":"files/gone.json"}`)
+	if _, err := Check(root); err == nil {
+		t.Fatal("a template the module's directory lacks passed the check")
+	}
+}
+
 func TestTheKnownListOnlyShrinks(t *testing.T) {
 	found := []Finding{{"b", "cfg", "server.secret_key"}, {"a", "cfg", "password"}}
 	refused, stale := Judge(found, map[string]bool{"b cfg server.secret_key": true, "gone cfg token": true})

checks/sshdir/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/sshdir
+
+go 1.22

checks/sshdir/main.go

@@ -0,0 +1,161 @@
+// Command sshdir refuses any manifest but modules/ssh-client naming a path under ~/.ssh (novox/hq ADR 0415 §6,
+// issue 1020): ssh-client owns ~/.ssh and sweeps what it does not know, so a path another module placed there
+// would be moved out at the next sweep. A module that needs something there provides it to ssh-client instead.
+//
+//	go run . <catalogue root>
+//
+// Every string of a manifest is read, wherever it stands, except prose and a file's text (Prose): a path, a
+// place, a volume; a path inside a directory of the module's own (`${dir:<id>}`) is not ~/.ssh. Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// SSHModule is the one module allowed to name a path under ~/.ssh.
+const SSHModule = "ssh-client"
+
+// underSSH is a path under ~/.ssh, or ~/.ssh itself, however the home is spelled: ${machine:account-home}/.ssh,
+// ~/.ssh, .ssh/config, or a volume's host side (…/.ssh:/root/.ssh).
+var underSSH = regexp.MustCompile(`(^|[/~])\.ssh($|[/:])`)
+
+// Prose are the keys whose strings are words or a file's text, not a path: a template may say ~/.ssh in a comment.
+var Prose = map[string]bool{"description": true, "why": true, "does": true, "template": true, "content": true, "title": true}
+
+// Finding is one path under ~/.ssh in a manifest other than ssh-client's.
+type Finding struct {
+	Module string
+	Key    string
+	Value  string
+}
+
+// Check reads every manifest under root/modules and answers which paths it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m any
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		module := filepath.Base(filepath.Dir(path))
+		if obj, ok := m.(map[string]any); ok {
+			if name, ok := obj["module"].(string); ok && name != "" {
+				module = name
+			}
+		}
+		if module == SSHModule {
+			continue
+		}
+		walk(m, "", dirsOf(m), func(key, value string) {
+			out = append(out, Finding{Module: module, Key: key, Value: value})
+		})
+	}
+	return out, nil
+}
+
+// walk calls found for every string under v, outside Prose, that names a path under ~/.ssh.
+func walk(v any, key string, dirs map[string]string, found func(key, value string)) {
+	switch x := v.(type) {
+	case map[string]any:
+		keys := make([]string, 0, len(x))
+		for k := range x {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if !Prose[k] {
+				walk(x[k], k, dirs, found)
+			}
+		}
+	case []any:
+		for _, e := range x {
+			walk(e, key, dirs, found)
+		}
+	case string:
+		// A path under a directory the mesh places for the module (${dir:<id>} of a directory with a place and no path,
+		// as a runs-as module's home) is that account's own .ssh, not the operator's ~/.ssh that ssh-client sweeps
+		// (issue 1484, ADR 0466 §4). Any other ${dir:<id>} is resolved to the path its resource declares and judged.
+		if resolved, placed := resolveDir(x, dirs); !placed && underSSH.MatchString(resolved) {
+			found(key, x)
+		}
+	}
+}
+
+var ofDir = regexp.MustCompile(`^\$\{dir:([a-z0-9][a-z0-9_-]*)\}`)
+
+// placedDir marks a directory the mesh places for the module: it has no path of its own.
+const placedDir = "\x00placed"
+
+// dirsOf are the module's directories by id: the path each declares, or placedDir for one with a place and no path.
+func dirsOf(m any) map[string]string {
+	dirs := map[string]string{}
+	obj, _ := m.(map[string]any)
+	list, _ := obj["resources"].([]any)
+	for _, r := range list {
+		res, _ := r.(map[string]any)
+		id, _ := res["id"].(string)
+		path, _ := res["path"].(string)
+		switch {
+		case id == "":
+		case path != "":
+			dirs[id] = path
+		case res["type"] == "directory":
+			dirs[id] = placedDir
+		}
+	}
+	return dirs
+}
+
+// resolveDir follows a leading ${dir:<id>} through the module's directories. It answers the path with the references
+// resolved, and whether it ends under a placed directory.
+func resolveDir(x string, dirs map[string]string) (string, bool) {
+	for i := 0; i < 8; i++ {
+		m := ofDir.FindStringSubmatch(x)
+		if m == nil {
+			return x, false
+		}
+		to, ok := dirs[m[1]]
+		if !ok {
+			return x, false
+		}
+		if to == placedDir {
+			return x, true
+		}
+		x = to + strings.TrimPrefix(x, m[0])
+	}
+	return x, false
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		fmt.Printf("%s names %q (%s) under ~/.ssh: only %s may, and the sweep moves anything else out (novox/hq ADR 0415 §6)\n", f.Module, f.Value, f.Key, SSHModule)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("~/.ssh: named only by ssh-client")
+}

checks/sshdir/main_test.go

@@ -0,0 +1,78 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func manifest(t *testing.T, root, module, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", module)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestAnotherModuleNamingSSHIsRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "ssh-client", `{"module":"ssh-client","resources":[{"path":"${machine:account-home}/.ssh/config"}]}`)
+	manifest(t, root, "forge-account", `{"module":"forge-account","resources":[{"path":"${machine:account-home}/.ssh/config.d/20-forge"}]}`)
+	manifest(t, root, "roster", `{"module":"roster","facts":{"hosts":{"path":".ssh/known_hosts"}}}`)
+	manifest(t, root, "box", `{"module":"box","containers":[{"volumes":["~/.ssh:/root/.ssh:ro"]}]}`)
+	manifest(t, root, "quiet", `{"module":"quiet","description":"reads ~/.ssh/config","resources":[{"path":"${machine:account-home}/.sshrc-not","template":"# see ~/.ssh/config"},{"path":"/etc/ssh/sshd_config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := map[string]bool{}
+	for _, f := range found {
+		got[f.Module] = true
+	}
+	if len(found) != 3 || !got["forge-account"] || !got["roster"] || !got["box"] {
+		t.Fatalf("refused %+v; want forge-account, roster and box", found)
+	}
+}
+
+// Issue 1484: a runs-as module's own account has a .ssh of its own, inside its home (a directory of the module's);
+// that is not the operator's ~/.ssh, which only ssh-client names. A path outside any ${dir:} is still refused.
+func TestAModulesOwnDirectoryMayHoldADotSSH(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "builder", `{"module":"builder","resources":[{"id":"state","type":"directory","place":"."},{"id":"ssh-dir","type":"directory","path":"${dir:state}/.ssh"},{"path":"${dir:ssh-dir}/config"}]}`)
+	manifest(t, root, "other", `{"module":"other","resources":[{"path":"${machine:account-home}/.ssh/config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "other" {
+		t.Fatalf("refused %+v; want only other", found)
+	}
+}
+
+// Issue 1484 review: only a directory the mesh places is the module's own home. A ${dir:} that resolves to the
+// operator's home is judged by the path it resolves to.
+func TestADirResolvingToTheOperatorsHomeIsStillRefused(t *testing.T) {
+	root := t.TempDir()
+	manifest(t, root, "escape", `{"module":"escape","resources":[{"id":"h","type":"directory","path":"${machine:account-home}","unknown":"module"},{"path":"${dir:h}/.ssh/config"}]}`)
+	manifest(t, root, "placed", `{"module":"placed","resources":[{"id":"state","type":"directory","place":".","unknown":"program"},{"id":"s","type":"directory","path":"${dir:state}/.ssh"},{"path":"${dir:s}/config"}]}`)
+	found, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 1 || found[0].Module != "escape" {
+		t.Fatalf("refused %+v; want only escape", found)
+	}
+}
+
+func TestTheCatalogueHasNone(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(found) != 0 {
+		t.Fatalf("the catalogue names paths under ~/.ssh outside ssh-client: %+v", found)
+	}
+}

checks/templates/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/templates
+
+go 1.22

checks/templates/inline

@@ -0,0 +1,9 @@
+# The modules that still keep a file's text inline in module.json (`content`), one per line: the catalogue's list of
+# modules whose file text has not yet moved to a template in files/ (novox/hq ADR 0349 §2, design 57), or in the
+# templates directory its manifest names (`templates`, issue 731). Every other module's file resources name their
+# template. This list only shrinks: a module that keeps no file text inline is taken off, and a line the trunk's copy
+# does not hold is refused. When it is empty, no manifest in the catalogue carries file text (design 57 package T5,
+# issue 658).
+#
+# A window-manager addition (`contributions`, such as files/i3/*.conf) is not a file resource and takes no template;
+# it moves with the collections (design 57 package L2, issue 681) and is not judged here.

checks/templates/main.go

@@ -0,0 +1,178 @@
+// Command templates refuses a file's text kept inline in a manifest, outside the modules still to move (novox/hq
+// ADR 0349 §2, design 57 package T5, issue 658).
+//
+// A file resource names its text as a template in its module's templates directory (`"template": "<dir>/<name>"`;
+// the directory is the manifest's `"templates"`, files/ when it says none), which the module's build packs into an
+// archive; the controller reads each template back into the file's content, so the
+// mesh holds and composes what it would for the same text inline. A module whose file text has not yet moved is
+// listed in the file `inline` beside this check, one per line. Every other module's file resources say no
+// `content`; a module on the list that keeps none inline is taken off it; and a line the trunk's copy (the merge
+// base's, given with -base) does not hold is refused, so the list only shrinks; while the trunk holds no copy, the
+// modules in seed are the trunk's. When it is empty, no manifest in the catalogue carries file text.
+//
+// Only file resources are judged: a window-manager addition (`contributions`) takes no template and moves with the
+// collections (design 57 package L2, issue 681).
+//
+//	go run . [-base <the trunk's inline>] <catalogue root>
+//
+// Every refusal names the refused module's own templates directory. Exits 1 on a finding.
+package main
+
+import (
+	"bufio"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+)
+
+const (
+	listFile          = "inline"
+	listPathInCatalog = "checks/templates/" + listFile
+)
+
+// Check answers, per module that keeps any, the ids of its file resources that say their text inline.
+func Check(root string) (map[string][]string, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	out := map[string][]string{}
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string           `json:"module"`
+			Resources []map[string]any `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		for _, r := range m.Resources {
+			if _, inline := r["content"]; inline && r["type"] == "file" {
+				out[m.Module] = append(out[m.Module], fmt.Sprint(r["id"]))
+			}
+		}
+	}
+	return out, nil
+}
+
+// TemplatesDir answers the directory a module keeps its templates in, with a trailing slash: its manifest's
+// `templates`, files/ when the manifest says none or cannot be read here.
+func TemplatesDir(root, module string) string {
+	dir := "files/"
+	raw, err := os.ReadFile(filepath.Join(root, "modules", module, "module.json"))
+	if err != nil {
+		return dir
+	}
+	var m struct {
+		Templates string `json:"templates"`
+	}
+	if json.Unmarshal(raw, &m) == nil && m.Templates != "" {
+		dir = strings.TrimSuffix(m.Templates, "/") + "/"
+	}
+	return dir
+}
+
+// Refusal is the finding for a module that keeps file text inline and is not on the list.
+func Refusal(module string, ids []string, dir string) string {
+	return fmt.Sprintf("%s keeps the text of %s inline and is not on %s: keep each file's text in %s and name it as "+
+		"the file's template, packed by the build's archive from %s (novox/hq ADR 0349 §2)",
+		module, strings.Join(ids, ", "), listPathInCatalog, dir, dir)
+}
+
+// Gained is the finding for a module the list gains against the trunk's copy.
+func Gained(module, dir string) string {
+	return fmt.Sprintf("%s gains %s, which the trunk's copy does not hold: the list only shrinks — move its file text "+
+		"to %s instead (novox/hq ADR 0349 §2)", listPathInCatalog, module, dir)
+}
+
+// seed is the list as it was first written, standing for the trunk's copy until the trunk holds one.
+var seed = map[string]bool{"asus-zephyrus-g14": true, "power": true, "showcase": true}
+
+// Listed is the modules a list names, one per line; a line starting with # and a blank line are not modules.
+func Listed(path string) (map[string]bool, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	defer f.Close()
+	out := map[string]bool{}
+	s := bufio.NewScanner(f)
+	for s.Scan() {
+		line := strings.TrimSpace(s.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		out[line] = true
+	}
+	return out, s.Err()
+}
+
+// Judge answers the modules that keep file text inline and are not on the list (refused), the modules on the list
+// that keep none (stale), and the modules on the list that the trunk's list does not hold (added).
+func Judge(found map[string][]string, listed, base map[string]bool) (refused, stale, added []string) {
+	for m := range found {
+		if !listed[m] {
+			refused = append(refused, m)
+		}
+	}
+	for m := range listed {
+		if _, keeps := found[m]; !keeps {
+			stale = append(stale, m)
+		}
+		if !base[m] {
+			added = append(added, m)
+		}
+	}
+	sort.Strings(refused)
+	sort.Strings(stale)
+	sort.Strings(added)
+	return refused, stale, added
+}
+
+func main() {
+	basePath := flag.String("base", "", "the trunk's copy of inline (the merge base's); seed when absent")
+	flag.Parse()
+	root := "."
+	if flag.NArg() > 0 {
+		root = flag.Arg(0)
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	listed, err := Listed(listFile)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	base := seed
+	if *basePath != "" {
+		if base, err = Listed(*basePath); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			os.Exit(1)
+		}
+	}
+	refused, stale, added := Judge(found, listed, base)
+	for _, m := range refused {
+		fmt.Println(Refusal(m, found[m], TemplatesDir(root, m)))
+	}
+	for _, m := range stale {
+		fmt.Printf("%s names %s, which keeps no file text inline: take it off the list\n", listPathInCatalog, m)
+	}
+	for _, m := range added {
+		fmt.Println(Gained(m, TemplatesDir(root, m)))
+	}
+	if len(refused) > 0 || len(stale) > 0 || len(added) > 0 {
+		os.Exit(1)
+	}
+	fmt.Printf("templates: no module keeps a file's text inline but the %d listed\n", len(listed))
+}

checks/templates/main_test.go

@@ -0,0 +1,102 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func module(t *testing.T, root, name, body string) {
+	t.Helper()
+	dir := filepath.Join(root, "modules", name)
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// A file resource that says its text inline is found, by module and resource; one naming its template, a
+// resource that is not a file and a window-manager addition are not (novox/hq ADR 0349 §2).
+func TestEveryInlineFileTextIsFound(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "inline", `{"module":"inline","resources":[{"id":"a","type":"file","content":"x"},`+
+		`{"id":"b","type":"file","template":"files/b"},{"id":"c","type":"file","content":""}]}`)
+	module(t, root, "templated", `{"module":"templated","resources":[{"id":"a","type":"file","template":"files/a"},`+
+		`{"id":"d","type":"directory","path":"/x"}],"contributions":{"i3":[{"content":"bindsym x"}]}}`)
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := map[string][]string{"inline": {"a", "c"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("found %v, want %v", got, want)
+	}
+}
+
+// A module not on the list keeps no file text inline; one on the list that keeps none is taken off it; a line the
+// trunk's list does not hold is refused, so the list only shrinks until it is empty.
+func TestTheListOfModulesKeepingTextInlineOnlyShrinks(t *testing.T) {
+	found := map[string][]string{"old": {"a"}, "forgotten": {"b"}}
+	inline := map[string]bool{"old": true, "done": true, "new": true}
+	base := map[string]bool{"old": true, "done": true, "forgotten": true}
+	refused, stale, added := Judge(found, inline, base)
+	if !reflect.DeepEqual(refused, []string{"forgotten"}) || !reflect.DeepEqual(stale, []string{"done", "new"}) ||
+		!reflect.DeepEqual(added, []string{"new"}) {
+		t.Fatalf("refused %v, stale %v, added %v", refused, stale, added)
+	}
+}
+
+func TestTheListIsReadWithoutItsComments(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "inline")
+	if err := os.WriteFile(path, []byte("# why\n\npower\n  showcase  \n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	got, err := Listed(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(got, map[string]bool{"power": true, "showcase": true}) {
+		t.Fatalf("read %v", got)
+	}
+}
+
+// The catalogue itself: no module keeps a file's text inline but those the list names, and the list names none
+// that keeps it no longer (design 57 package T5, issue 658: the ten modules without a build moved).
+func TestTheCatalogueKeepsFileTextInlineOnlyWhereListed(t *testing.T) {
+	found, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	inline, err := Listed(listFile)
+	if err != nil {
+		t.Fatal(err)
+	}
+	refused, stale, _ := Judge(found, inline, inline)
+	if len(refused) > 0 || len(stale) > 0 {
+		t.Fatalf("keeping file text inline and not listed: %v; listed and keeping none: %v", refused, stale)
+	}
+}
+
+// A refusal names the refused module's own templates directory, not files/ when the module names another (issue 809).
+func TestARefusalNamesTheModulesOwnTemplatesDirectory(t *testing.T) {
+	root := t.TempDir()
+	module(t, root, "own", `{"module":"own","templates":"t/","resources":[{"id":"a","type":"file","content":"x"}]}`)
+	module(t, root, "plain", `{"module":"plain","resources":[{"id":"a","type":"file","content":"x"}]}`)
+	module(t, root, "bare", `{"module":"bare","templates":"templates","resources":[]}`)
+	for module, dir := range map[string]string{"own": "t/", "plain": "files/", "bare": "templates/"} {
+		if got := TemplatesDir(root, module); got != dir {
+			t.Fatalf("%s: directory %q, want %q", module, got, dir)
+		}
+	}
+	msg := Refusal("own", []string{"a"}, TemplatesDir(root, "own"))
+	if !strings.Contains(msg, "t/") || strings.Contains(msg, "files/") {
+		t.Fatalf("refusal %q", msg)
+	}
+	if msg := Gained("own", TemplatesDir(root, "own")); !strings.Contains(msg, "t/") || strings.Contains(msg, "files/") {
+		t.Fatalf("gained %q", msg)
+	}
+}

checks/toolchains/go.mod

@@ -0,0 +1,3 @@
+module git.novox.be/novox/mesh-catalog/checks/toolchains
+
+go 1.22

checks/toolchains/main.go

@@ -0,0 +1,105 @@
+// Command toolchains refuses any manifest but the owner's declaring a language's toolchain package (novox/hq
+// ADR 0477 clause 4, issue 1573): the package go only in modules/go, nodejs and npm only in modules/nodejs, and buildah (issue 1702) only in modules/buildah.
+// Everything that compiles or runs that language requires the owner's provision instead (go-toolchain,
+// node-toolchain), so the package is declared once, and a node without the owner refuses the module that
+// needs it at resolution rather than failing at its first build. The owners must declare their packages.
+//
+//	go run . <catalogue root>
+//
+// Exits 1 on a finding.
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// Owners names, for each toolchain package, the one module that declares it.
+var Owners = map[string]string{
+	"buildah": "buildah",
+	"go":      "go",
+	"nodejs":  "nodejs",
+	"npm":     "nodejs",
+}
+
+// Finding is one refusal: Module declares Package, which Owner alone may, or (Missing) Owner does not declare
+// the Package it owns.
+type Finding struct {
+	Module, Package, Owner string
+	Missing                bool
+}
+
+// Check reads every manifest under root/modules and answers what it refuses.
+func Check(root string) ([]Finding, error) {
+	manifests, err := filepath.Glob(filepath.Join(root, "modules", "*", "module.json"))
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(manifests)
+	var out []Finding
+	declared := map[string]map[string]bool{} // module -> packages
+	for _, path := range manifests {
+		raw, err := os.ReadFile(path)
+		if err != nil {
+			return nil, err
+		}
+		var m struct {
+			Module    string `json:"module"`
+			Resources []struct {
+				Type    string `json:"type"`
+				Package string `json:"package"`
+			} `json:"resources"`
+		}
+		if err := json.Unmarshal(raw, &m); err != nil {
+			return nil, fmt.Errorf("%s: %w", path, err)
+		}
+		declared[m.Module] = map[string]bool{}
+		for _, r := range m.Resources {
+			if r.Type != "package" {
+				continue
+			}
+			declared[m.Module][r.Package] = true
+			if owner, ok := Owners[r.Package]; ok && owner != m.Module {
+				out = append(out, Finding{Module: m.Module, Package: r.Package, Owner: owner})
+			}
+		}
+	}
+	var pkgs []string
+	for p := range Owners {
+		pkgs = append(pkgs, p)
+	}
+	sort.Strings(pkgs)
+	for _, p := range pkgs {
+		if !declared[Owners[p]][p] {
+			out = append(out, Finding{Module: Owners[p], Package: p, Owner: Owners[p], Missing: true})
+		}
+	}
+	return out, nil
+}
+
+func main() {
+	root := "."
+	if len(os.Args) > 1 {
+		root = os.Args[1]
+	}
+	found, err := Check(root)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, err)
+		os.Exit(1)
+	}
+	for _, f := range found {
+		if f.Missing {
+			fmt.Printf("%s does not declare the package %s it owns (novox/hq ADR 0477 clause 4)\n", f.Owner, f.Package)
+			continue
+		}
+		fmt.Printf("%s declares the package %s: only %s may; require its provision instead (novox/hq ADR 0477 clause 4)\n",
+			f.Module, f.Package, f.Owner)
+	}
+	if len(found) > 0 {
+		os.Exit(1)
+	}
+	fmt.Println("toolchains: go, nodejs, npm and buildah are declared only by their owners")
+}

checks/toolchains/main_test.go

@@ -0,0 +1,82 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"reflect"
+	"testing"
+)
+
+func catalogue(t *testing.T, manifests map[string]string) string {
+	t.Helper()
+	root := t.TempDir()
+	for name, body := range manifests {
+		dir := filepath.Join(root, "modules", name)
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(dir, "module.json"), []byte(body), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	return root
+}
+
+func TestOnlyTheOwnerDeclaresAToolchainPackage(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"go":      `{"module":"go","resources":[{"id":"go","type":"package","package":"go"}]}`,
+		"nodejs":  `{"module":"nodejs","resources":[{"id":"nodejs","type":"package","package":"nodejs"},{"id":"npm","type":"package","package":"npm"}]}`,
+		"buildah": `{"module":"buildah","resources":[{"id":"b","type":"package","package":"buildah"}]}`,
+		"lab":     `{"module":"lab","resources":[{"id":"git","type":"package","package":"git"},{"id":"go","type":"package","package":"go"}]}`,
+		"builder": `{"module":"builder","resources":[{"id":"n","type":"package","package":"nodejs"},{"id":"dir","type":"directory","path":"/go"}]}`,
+	})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []Finding{{Module: "builder", Package: "nodejs", Owner: "nodejs"}, {Module: "lab", Package: "go", Owner: "go"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("found %v, want %v", got, want)
+	}
+}
+
+func TestASecondDeclarerOfBuildahIsRefused(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"go":      `{"module":"go","resources":[{"id":"go","type":"package","package":"go"}]}`,
+		"nodejs":  `{"module":"nodejs","resources":[{"id":"nodejs","type":"package","package":"nodejs"},{"id":"npm","type":"package","package":"npm"}]}`,
+		"buildah": `{"module":"buildah","resources":[{"id":"b","type":"package","package":"buildah"}]}`,
+		"imagery": `{"module":"imagery","resources":[{"id":"b","type":"package","package":"buildah"}]}`,
+	})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []Finding{{Module: "imagery", Package: "buildah", Owner: "buildah"}}
+	if !reflect.DeepEqual(got, want) {
+		t.Errorf("found %v, want %v", got, want)
+	}
+}
+
+func TestTheOwnersMustExistAndDeclareTheirPackages(t *testing.T) {
+	root := catalogue(t, map[string]string{
+		"go": `{"module":"go","resources":[]}`,
+	})
+	got, err := Check(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 4 {
+		t.Errorf("an owner missing its packages gave %v, want four findings (buildah, go, nodejs, npm)", got)
+	}
+}
+
+// The catalogue as it stands: this is the check itself, run here too.
+func TestTheCatalogueGivesEachToolchainPackageToItsOwnerAlone(t *testing.T) {
+	got, err := Check("../..")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 0 {
+		t.Errorf("the catalogue declares a toolchain package outside its owner: %v", got)
+	}
+}

health-undeclared

@@ -1,4 +1,4 @@
-66
+58
 The long-running resources of this catalogue that do not say how they are ready (`health`, novox/hq ADR 0240
 rule 8), as `module check` counts them. It may only go down: merge-check.sh fails a change that raises it, and
 one that lowers it writes the new number on the first line. From 2026-11-18, or once it is 0, a long-running

merge-check-typescript.sh

@@ -23,9 +23,51 @@
 #
 # By hand: MESH_CHECK_MODULES=gitea sh merge-check-typescript.sh, in the toolchain image (it reads
 # /app/node_modules), or with TOOLCHAIN_MODULES pointing at a node_modules that holds the same.
+#
+# **In an agent's session, outside the toolchain image** (novox/hq issue 742), the same node_modules is
+# assembled first, in a throwaway directory under the check's own workspace, the way the image's `deps` stage
+# assembles it: the toolchain's own package.json and lock (mesh-tools' node-tools/, read from the forge this
+# clone came from, so the list is never copied here) installed with `npm ci`, then the SDK the mesh last
+# published (`@novox/mesh-sdk@latest`), the @novox scope from the forge's package registry, read without a
+# credential. Node and npm are the dev-tools module's; nothing is installed on the machine, no npm
+# configuration or cache of the account's is read or written. Only when neither TOOLCHAIN_MODULES nor
+# /app/node_modules is there: the forge's check, in the image, fetches nothing, as before. The forge is
+# MESH_FORGE (default: the origin remote's), the owner MESH_FORGE_OWNER (default: the origin's owner).
 set -eu
 
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
 deps="${TOOLCHAIN_MODULES:-/app/node_modules}"
+if [ -z "${TOOLCHAIN_MODULES:-}" ] && [ ! -f "$deps/typescript/bin/tsc" ]; then
+	origin=$(git remote get-url origin 2>/dev/null || true)
+	forge="${MESH_FORGE:-$(printf '%s\n' "$origin" | sed -n 's#^\(https\{0,1\}://[^/]*\)/.*#\1#p')}"
+	owner="${MESH_FORGE_OWNER:-$(printf '%s\n' "$origin" | sed -n 's#^https\{0,1\}://[^/]*/\([^/]*\)/.*#\1#p')}"
+	if [ -z "$forge" ] || [ -z "$owner" ]; then
+		echo "NOT CHECKED: no TypeScript toolchain at $deps, and no forge to assemble one from (origin is '$origin'; set MESH_FORGE and MESH_FORGE_OWNER, or TOOLCHAIN_MODULES)"
+		exit 1
+	fi
+	echo "no TypeScript toolchain at $deps: assembling one from $forge/$owner/mesh-tools node-tools/ and $owner's package registry (novox/hq issue 742)"
+	tc="$work/toolchain"
+	mkdir -p "$tc"
+	printf '@%s:registry=%s/api/packages/%s/npm/\n' "$owner" "$forge" "$owner" >"$work/npmrc"
+	# Read with Node's own fetch (dev-tools declares Node, not curl); a status that is not 2xx fails.
+	if ! { node -e '
+		const [base, dir] = process.argv.slice(1);
+		Promise.all(["package.json", "package-lock.json"].map(async (f) => {
+			const r = await fetch(base + f);
+			if (!r.ok) throw new Error(base + f + ": " + r.status);
+			require("fs").writeFileSync(dir + "/" + f, await r.text());
+		})).catch((e) => { console.error(e.message); process.exit(1); });' \
+		"$forge/$owner/mesh-tools/raw/branch/main/node-tools/" "$tc" &&
+		(cd "$tc" && export npm_config_userconfig="$work/npmrc" npm_config_cache="$work/npm-cache" &&
+			npm ci --ignore-scripts --no-audit --no-fund --loglevel=error &&
+			npm install --ignore-scripts --no-audit --no-fund --no-save --loglevel=error "@$owner/mesh-sdk@latest"); }; then
+		echo "NOT CHECKED: the TypeScript toolchain could not be assembled from $forge (novox/hq issue 742)"
+		exit 1
+	fi
+	deps="$tc/node_modules"
+fi
 tsc="$deps/typescript/bin/tsc"
 if [ ! -f "$tsc" ]; then
 	echo "NOT CHECKED: no TypeScript compiler at $tsc — this part runs in the TypeScript toolchain"
@@ -39,8 +81,6 @@ touched=$({
 	printf '%s\n' "${MESH_CHECK_CHANGED:-}" | tr ',' '\n' | sed -n 's#^modules/\([^/]*\)/.*#\1#p'
 } | sed '/^$/d' | sort -u)
 
-work=$(mktemp -d)
-trap 'rm -rf "$work"' EXIT
 failed=""
 for m in $touched; do
 	d="modules/$m"

merge-check.sh

@@ -17,7 +17,8 @@
 #      toolchain has a C compiler. A requirement of the mesh's own forge the module cache does not hold (a
 #      pinned SDK commit) is taken from its repository's clone beside the check (checks/deps); a module whose
 #      dependencies still cannot be had **fails the check**, by name and why — its tests could not run, and a
-#      test that could not run is a failure, never a note (novox/hq issue 385). A module written in
+#      test that could not run is a failure, never a note (novox/hq issue 385). The integration tests (`//go:build
+#      integration`) run here, with -tags integration, and only here. A module written in
 #      TypeScript is type-checked and tested by
 #      merge-check-typescript.sh, declared above, in the TypeScript toolchain (novox/hq issues 302, 311);
 #   3. the words (novox/hq ADR 0244): no word the glossary retired for the tools, as copied in
@@ -33,11 +34,47 @@
 #   6. the secrets (novox/hq issue 342): no mergeable file fills a key with a vault secret that a setting could
 #      replace — the key is `protected`, or left out of the file's `takes-settings`. checks/secrets/known names
 #      the nested ones the controller cannot protect alone yet, and only shrinks.
+#   7. the list of predefined keys (novox/hq ADR 0348 clause 7): a change to predefined.json removes no key a
+#      module still names, judged against the trunk's copy at the merge base. Whether a removed key still holds a
+#      value at the mesh or a node is mesh-config's to refuse; this check reads no store. The list itself and
+#      every manifest against it are judged by the controller's module check in step 1.
+#   8. the config form (novox/hq ADR 0348 clauses 1 and 11): no module says `settings`, `takes-settings` or
+#      `${setting:<key>}`, in its manifest or a template it names, or has a mergeable file naming no keys (which
+#      takes its whole layer), unless checks/config/unmoved lists it as not yet moved; that list only shrinks,
+#      judged against the trunk's copy at the merge base.
+#   9. the file text (novox/hq ADR 0349 §2): no module keeps a file's text inline in its manifest (`content`)
+#      unless checks/templates/inline lists it as not yet moved; each names its template in files/. That list
+#      only shrinks, judged against the trunk's copy at the merge base.
+#   10. the mail-store seat (novox/hq ADR 0378 §3, issue 800): no manifest but modules/mesh-mail claims it.
+#   11. owned paths (novox/hq ADR 0422 §8, issue 1024; it holds ~/.ssh for ssh-client as ADR 0415 §6 asked):
+#      every directory and archive says `unknown` (move-out, module or program) and a valid `knows`; `move-out`
+#      only under a home; and no module declares a path inside a directory of another module.
+#      checks/sshdir (ADR 0415 §6) stays while main runs it; it goes under issue 1035 once main runs checks/owned.
+#   12. the image builder (novox/hq ADR 0487 §3, issue 1704): only modules/buildah provides rootless-image-build.
+#   13. the image's place (novox/hq ADR 0487 §1, issue 1707): every image builds from a Dockerfile in its own module's directory.
 set -eu
 
 (cd checks/words && go test -count=1 . && go run . ../..)
+# Node names (novox/hq ADR 0507 §9, issue 1838): no node name of this mesh in a covered module; the names are in
+# `particulars`, the covered modules in checks/particulars/covered.
+(cd checks/particulars && go test -count=1 . && go run . ../..)
+# The toolchains (novox/hq ADR 0477 clause 4): the package go only in modules/go, nodejs and npm only in modules/nodejs.
+(cd checks/toolchains && go test -count=1 . && go run . ../..)
+# The image builder (novox/hq ADR 0487 §3): only modules/buildah provides rootless-image-build, docker never.
+(cd checks/imagebuild && go test -count=1 . && go run . ../..)
+# The image's place (novox/hq ADR 0487 §1): every image builds from a Dockerfile in its own module's directory.
+(cd checks/imageplace && go test -count=1 . && go run . ../..)
+# The Node lock files (novox/hq ADR 0469 §5, issue 1868): a TypeScript module that names packages beyond the SDK commits its lock.
+(cd checks/locks && go test -count=1 . && go run . ../..)
 # The agent's home (novox/hq ADR 0266): no archive, and no file written into, under it.
 (cd checks/agenthome && go test -count=1 . && go run . ../..)
+# The mail-store seat (novox/hq ADR 0378 §3): only mesh-mail may claim it.
+(cd checks/mailstore && go test -count=1 . && go run . ../..)
+# ~/.ssh (novox/hq ADR 0415 §6): only ssh-client may name a path under it. Main's merge check runs this line, so
+# checks/sshdir stays until main runs checks/owned; it goes under issue 1035.
+(cd checks/sshdir && go test -count=1 . && go run . ../..)
+# Owned paths (novox/hq ADR 0422 §8): unknown files named per directory; no path inside another module's directory.
+(cd checks/owned && go test -count=1 . && go run . ../..)
 # The secrets (novox/hq issue 342): a password is not a setting, so no setting can replace the vault's. The
 # known list only shrinks: judged against the trunk's copy at the merge base, a line it does not hold is refused.
 secrets_base=""
@@ -51,6 +88,42 @@ else
 	echo "NOT COMPARED WITH THE TRUNK: no merge base with $secrets_ref; checks/secrets/known is held to the list it was first written with"
 fi
 (cd checks/secrets && go test -count=1 . && if [ -n "$secrets_base" ]; then go run . -base "$secrets_base" ../..; else go run . ../..; fi)
+# The list of predefined keys (novox/hq ADR 0348 clause 7): no key removed that a module still names. The trunk's
+# list at the merge base is what it is judged against; a trunk without the file had none.
+predefined_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	predefined_base=$(mktemp)
+	if ! git show "$merge_base:predefined.json" >"$predefined_base" 2>/dev/null; then
+		echo '{}' >"$predefined_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; no removal from predefined.json can be seen"
+fi
+(cd checks/predefined && go test -count=1 . && if [ -n "$predefined_base" ]; then go run . -base "$predefined_base" ../..; else go run . ../..; fi)
+# The config form (novox/hq ADR 0348 §1, §11): a moved module says no old name, and the list of modules not yet moved
+# only shrinks, judged against the trunk's copy at the merge base; a trunk without one is the list's first copy.
+unmoved_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	if git cat-file -e "$merge_base:checks/config/unmoved" 2>/dev/null; then
+		unmoved_base=$(mktemp)
+		git show "$merge_base:checks/config/unmoved" >"$unmoved_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; checks/config/unmoved is held to the list it was first written with"
+fi
+(cd checks/config && go test -count=1 . && if [ -n "$unmoved_base" ]; then go run . -base "$unmoved_base" ../..; else go run . ../..; fi)
+# The file text (novox/hq ADR 0349 §2): a file's text is a template in files/, outside the modules not yet moved; the
+# list of those only shrinks, judged against the trunk's copy at the merge base, a trunk without one being its first.
+inline_base=""
+if merge_base=$(git merge-base HEAD "origin/${MESH_CHECK_BASE:-main}" 2>/dev/null); then
+	if git cat-file -e "$merge_base:checks/templates/inline" 2>/dev/null; then
+		inline_base=$(mktemp)
+		git show "$merge_base:checks/templates/inline" >"$inline_base"
+	fi
+else
+	echo "NOT COMPARED WITH THE TRUNK: no merge base with origin/${MESH_CHECK_BASE:-main}; checks/templates/inline is held to the list it was first written with"
+fi
+(cd checks/templates && go test -count=1 . && if [ -n "$inline_base" ]; then go run . -base "$inline_base" ../..; else go run . ../..; fi)
 # The lists that narrow the paths check may not grow unseen: the base branch's copies are what they are
 # judged against (MESH_CHECK_BASE, main when unset), read from the clone the check runs in.
 base_lists=""
@@ -124,8 +197,23 @@ for m in $touched; do
 	fi
 	cgo=0
 	[ -n "$race" ] && cgo=1
-	(cd "modules/$m" && CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go vet ${modfile:+"-modfile=$modfile"} ./... &&
-		CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go test ${modfile:+"-modfile=$modfile"} $race -count=1 ./...)
+	# The integration tests (a file whose first line is `//go:build integration`: a test that starts a bus, a store or
+	# another process) run here and nowhere else: the unit suite stays under a second (novox/hq playbook 07).
+	(cd "modules/$m" && CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go vet -tags integration ${modfile:+"-modfile=$modfile"} ./... &&
+		CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go test -tags integration ${modfile:+"-modfile=$modfile"} $race -count=1 ./...)
+	# The docker tests of the bus's snapshot program and entrypoint (novox/hq ADR 0480 clause 6) start throwaway nats
+	# containers, and the Go toolchain container holds no docker, so above they skip with a "NOT RUN" line. Where the
+	# build seat says docker exists (MESH_CHECK_DOCKER=1) they run here by name, and a missing docker fails the check
+	# (MESH_REQUIRE_DOCKER=1 makes the tests fail instead of skip). Without it the step says it did not run.
+	if [ "$m" = nats ]; then
+		if [ "${MESH_CHECK_DOCKER:-}" = 1 ]; then
+			(cd modules/nats && MESH_REQUIRE_DOCKER=1 CGO_ENABLED=$cgo GOPRIVATE=git.novox.be go test -tags integration ${modfile:+"-modfile=$modfile"} -count=1 \
+				-run 'TestTheDeclaredDumpRunsInTheBussImage|TestTheEntrypointReloadsTheServerWithoutDroppingAConnection|TestTheStoreSurvivesTheNewDeclarationTheOldAndTheNewAgain|TestASnapshotOfALiveBusRestoresToTheSameContent|TestTheSnapshotUserCannotChangeTheBus' \
+				./cmd/mesh-nats-snapshot) || { echo "the bus's docker tests failed"; exit 1; }
+		else
+			echo "NOT RUN: the bus's five docker tests (modules/nats/cmd/mesh-nats-snapshot) skipped: this check has no docker (MESH_CHECK_DOCKER is not 1)"
+		fi
+	fi
 done
 if [ -n "$untestable" ]; then
 	echo "the check fails: the tests of$untestable could not run (novox/hq issue 385)"

modules/adwaita/README.md

@@ -22,11 +22,11 @@ for GTK, Qt, the portal and the cursor, dark by default. It claims no seat, beca
 
 | path | class | from |
 |---|---|---|
-| `~/.config/gtk-3.0/settings.ini` | owned (the found file kept once) | [`config/gtk-settings.ini`](config/gtk-settings.ini) |
+| `~/.config/gtk-3.0/settings.ini` | owned (the found file kept once) | [`files/gtk-settings.ini`](files/gtk-settings.ini) |
 | `~/.config/gtk-4.0/settings.ini` | owned | the same file |
-| `~/.config/qt6ct/qt6ct.conf` | owned | [`config/qt6ct.conf`](config/qt6ct.conf) |
-| `~/.config/xdg-desktop-portal/portals.conf` | owned | [`config/portals.conf`](config/portals.conf) |
-| `~/.icons/default/index.theme` | owned | [`config/cursor-index.theme`](config/cursor-index.theme): the cursor for programs that read neither `XCURSOR_THEME` nor the resources |
+| `~/.config/qt6ct/qt6ct.conf` | owned | [`files/qt6ct.conf`](files/qt6ct.conf) |
+| `~/.config/xdg-desktop-portal/portals.conf` | owned | [`files/portals.conf`](files/portals.conf) |
+| `~/.icons/default/index.theme` | owned | [`files/cursor-index.theme`](files/cursor-index.theme): the cursor for programs that read neither `XCURSOR_THEME` nor the resources |
 
 **`qt6ct.conf` is the mesh's now.** A change made in qt6ct's own window is replaced at the next push,
 and the window's saved geometry goes with it. The theme is this module's to say. Settings will make it

modules/adwaita/cmd/adwaita-tools/adwaita_test.go

@@ -18,10 +18,18 @@ type manifest struct {
 	Environment  struct {
 		Variables map[string]string `json:"variables"`
 	} `json:"environment"`
+	Items []struct {
+		Collection string            `json:"collection"`
+		Attributes map[string]string `json:"attributes"`
+		Template   string            `json:"template"`
+	} `json:"items"`
 	Shell []struct {
 		For, Slot, Code string
 	} `json:"shell"`
 	Resources []map[string]any `json:"resources"`
+	Build     struct {
+		Artifacts []map[string]any `json:"artifacts"`
+	} `json:"build"`
 }
 
 func readManifest(t *testing.T) manifest {
@@ -33,6 +41,23 @@ func readManifest(t *testing.T) manifest {
 	if err := json.Unmarshal(raw, &m); err != nil {
 		t.Fatal(err)
 	}
+	// The module's code and variables are the templates of its items (design 57 L3, issues 795 and 807).
+	for _, it := range m.Items {
+		text, err := os.ReadFile(filepath.Join("..", "..", it.Template))
+		if err != nil {
+			t.Fatal(err)
+		}
+		parts := strings.Split(it.Collection, ":")
+		switch {
+		case len(parts) == 3 && parts[0] == "shell":
+			m.Shell = append(m.Shell, struct{ For, Slot, Code string }{parts[1], parts[2], string(text)})
+		case it.Collection == "environment" && it.Attributes["kind"] == "variable":
+			if m.Environment.Variables == nil {
+				m.Environment.Variables = map[string]string{}
+			}
+			m.Environment.Variables[it.Attributes["name"]] = strings.TrimSuffix(string(text), "\n")
+		}
+	}
 	return m
 }
 
@@ -96,9 +121,10 @@ func TestItOwnsTheFilesItsSourcesHoldAndNoQt5Duplicate(t *testing.T) {
 			pkgs = append(pkgs, r["package"].(string))
 			continue
 		}
-		raw, _ := os.ReadFile(filepath.Join("..", "..", "config", sources[id]))
-		if r["content"] != string(raw) || r["into"] != nil || r["owner"] != "${machine:account}" {
-			t.Errorf("%s is not config/%s, whole and the account's", id, sources[id])
+		_, inline := r["content"]
+		if _, err := os.Stat(filepath.Join("..", "..", "files", sources[id])); err != nil || inline ||
+			r["template"] != "files/"+sources[id] || r["into"] != nil || r["owner"] != "${machine:account}" {
+			t.Errorf("%s is not files/%s, whole, as its template, and the account's", id, sources[id])
 		}
 		if strings.Contains(r["path"].(string), "qt5ct") {
 			t.Error("qt5ct: both workstations run Qt 6 programs through qt6ct; a second tool is a duplicate")
@@ -107,7 +133,7 @@ func TestItOwnsTheFilesItsSourcesHoldAndNoQt5Duplicate(t *testing.T) {
 	if strings.Join(pkgs, ",") != "gnome-themes-extra,adwaita-icon-theme,adwaita-cursors,qt6ct,xdg-desktop-portal-gtk" {
 		t.Fatalf("%v", pkgs)
 	}
-	qt := readINI(filepath.Join("..", "..", "config", "qt6ct.conf"))
+	qt := readINI(filepath.Join("..", "..", "files", "qt6ct.conf"))
 	if qt["Appearance"]["style"] != "Fusion" || qt["Appearance"]["custom_palette"] != "true" || !strings.Contains(qt["Fonts"]["general"], "Inter,11") {
 		t.Fatalf("%v", qt)
 	}
@@ -116,7 +142,7 @@ func TestItOwnsTheFilesItsSourcesHoldAndNoQt5Duplicate(t *testing.T) {
 			t.Fatalf("qt6ct ships no %s", qt["Appearance"]["color_scheme_path"])
 		}
 	}
-	gtk := readINI(filepath.Join("..", "..", "config", "gtk-settings.ini"))["Settings"]
+	gtk := readINI(filepath.Join("..", "..", "files", "gtk-settings.ini"))["Settings"]
 	if gtk["gtk-theme-name"] != "Adwaita" || gtk["gtk-application-prefer-dark-theme"] != "1" || gtk["gtk-font-name"] != "Inter 11" {
 		t.Fatalf("%v", gtk)
 	}
@@ -244,3 +270,31 @@ func asJSON(v any) string {
 	b, _ := json.Marshal(v)
 	return string(b)
 }
+
+// No file resource carries its text inline: each names its template in files/, and the build packs files/
+// into the one archive the controller reads the templates back from (novox/hq ADR 0349 §2).
+func TestEveryFileTakesItsTextFromATemplate(t *testing.T) {
+	m := readManifest(t)
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in files/ and name it as the template", r["id"])
+		}
+		if name, ok := r["template"].(string); ok {
+			if _, err := os.Stat(filepath.Join("..", "..", name)); err != nil {
+				t.Errorf("resource %v names %s: %v", r["id"], name, err)
+			}
+		}
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "files" {
+			packs++
+			if a["name"] != "files" {
+				t.Errorf("the templates archive is named %v, not files", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Errorf("the build packs files/ into %d archives, not one", packs)
+	}
+}

modules/adwaita/files/env-gtk-theme

@@ -0,0 +1 @@
+Adwaita:dark

modules/adwaita/files/env-gtk2-rc-files

@@ -0,0 +1 @@
+/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc

modules/adwaita/files/env-qt-qpa-platformtheme

@@ -0,0 +1 @@
+qt6ct

modules/adwaita/files/env-qt-select

@@ -0,0 +1 @@
+6

modules/adwaita/files/env-qt-style-override

@@ -0,0 +1 @@
+Fusion

modules/adwaita/files/env-xcursor-size

@@ -0,0 +1 @@
+24

modules/adwaita/files/env-xcursor-theme

@@ -0,0 +1 @@
+Adwaita

modules/adwaita/files/xinitrc-normal

@@ -0,0 +1,10 @@
+# The appearance (module adwaita): GSettings is where the portal reads dark or light, and the portal is
+# the only way it reaches Electron, Chromium, Firefox and flatpaks. Set at every session start to the
+# module's default; adwaita_appearance switches it for a session.
+gsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' || true
+gsettings set org.gnome.desktop.interface gtk-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface icon-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface cursor-theme 'Adwaita' || true
+gsettings set org.gnome.desktop.interface cursor-size 24 || true
+gsettings set org.gnome.desktop.interface font-name 'Inter 11' || true
+gsettings set org.gnome.desktop.interface monospace-font-name 'JetBrainsMono Nerd Font 11' || true

modules/adwaita/files/xresources-normal

@@ -0,0 +1,3 @@
+! adwaita: the cursor, for X programs that take it from the resources.
+Xcursor.theme: Adwaita
+Xcursor.size: 24

modules/adwaita/module.json

@@ -1,6 +1,7 @@
 {
   "module": "adwaita",
   "version": "1",
+  "moved": true,
   "capabilities": [
     "package-manager"
   ],
@@ -10,27 +11,79 @@
     "adwaita_icons",
     "adwaita_portal_check"
   ],
-  "environment": {
-    "variables": {
-      "GTK_THEME": "Adwaita:dark",
-      "GTK2_RC_FILES": "/usr/share/themes/Adwaita-dark/gtk-2.0/gtkrc",
-      "QT_QPA_PLATFORMTHEME": "qt6ct",
-      "QT_STYLE_OVERRIDE": "Fusion",
-      "QT_SELECT": "6",
-      "XCURSOR_THEME": "Adwaita",
-      "XCURSOR_SIZE": "24"
-    }
-  },
-  "shell": [
+  "items": [
     {
-      "for": "xresources",
-      "slot": "normal",
-      "code": "! adwaita: the cursor, for X programs that take it from the resources.\nXcursor.theme: Adwaita\nXcursor.size: 24\n"
+      "collection": "environment",
+      "name": "gtk-theme",
+      "attributes": {
+        "kind": "variable",
+        "name": "GTK_THEME"
+      },
+      "template": "files/env-gtk-theme"
     },
     {
-      "for": "xinitrc",
-      "slot": "normal",
-      "code": "# The appearance (module adwaita): GSettings is where the portal reads dark or light, and the portal is\n# the only way it reaches Electron, Chromium, Firefox and flatpaks. Set at every session start to the\n# module's default; adwaita_appearance switches it for a session.\ngsettings set org.gnome.desktop.interface color-scheme 'prefer-dark' || true\ngsettings set org.gnome.desktop.interface gtk-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface icon-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface cursor-theme 'Adwaita' || true\ngsettings set org.gnome.desktop.interface cursor-size 24 || true\ngsettings set org.gnome.desktop.interface font-name 'Inter 11' || true\ngsettings set org.gnome.desktop.interface monospace-font-name 'JetBrainsMono Nerd Font 11' || true\n"
+      "collection": "environment",
+      "name": "gtk2-rc-files",
+      "attributes": {
+        "kind": "variable",
+        "name": "GTK2_RC_FILES"
+      },
+      "template": "files/env-gtk2-rc-files"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-qpa-platformtheme",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_QPA_PLATFORMTHEME"
+      },
+      "template": "files/env-qt-qpa-platformtheme"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-style-override",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_STYLE_OVERRIDE"
+      },
+      "template": "files/env-qt-style-override"
+    },
+    {
+      "collection": "environment",
+      "name": "qt-select",
+      "attributes": {
+        "kind": "variable",
+        "name": "QT_SELECT"
+      },
+      "template": "files/env-qt-select"
+    },
+    {
+      "collection": "environment",
+      "name": "xcursor-theme",
+      "attributes": {
+        "kind": "variable",
+        "name": "XCURSOR_THEME"
+      },
+      "template": "files/env-xcursor-theme"
+    },
+    {
+      "collection": "environment",
+      "name": "xcursor-size",
+      "attributes": {
+        "kind": "variable",
+        "name": "XCURSOR_SIZE"
+      },
+      "template": "files/env-xcursor-size"
+    },
+    {
+      "collection": "shell:xresources:normal",
+      "name": "xresources-normal",
+      "template": "files/xresources-normal"
+    },
+    {
+      "collection": "shell:xinitrc:normal",
+      "name": "xinitrc-normal",
+      "template": "files/xinitrc-normal"
     }
   ],
   "resources": [
@@ -65,7 +118,7 @@
       "path": "${machine:account-home}/.config/gtk-3.0/settings.ini",
       "owner": "${machine:account}",
       "mode": "0644",
-      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208), for GTK 3 and GTK 4 alike. Replaced at\n# every push; adwaita_appearance switches dark and light for the running session.\n[Settings]\ngtk-theme-name=Adwaita\ngtk-icon-theme-name=Adwaita\ngtk-cursor-theme-name=Adwaita\ngtk-cursor-theme-size=24\ngtk-font-name=Inter 11\ngtk-application-prefer-dark-theme=1\n"
+      "template": "files/gtk-settings.ini"
     },
     {
       "id": "gtk4",
@@ -73,7 +126,7 @@
       "path": "${machine:account-home}/.config/gtk-4.0/settings.ini",
       "owner": "${machine:account}",
       "mode": "0644",
-      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208), for GTK 3 and GTK 4 alike. Replaced at\n# every push; adwaita_appearance switches dark and light for the running session.\n[Settings]\ngtk-theme-name=Adwaita\ngtk-icon-theme-name=Adwaita\ngtk-cursor-theme-name=Adwaita\ngtk-cursor-theme-size=24\ngtk-font-name=Inter 11\ngtk-application-prefer-dark-theme=1\n"
+      "template": "files/gtk-settings.ini"
     },
     {
       "id": "qt6ct",
@@ -81,7 +134,7 @@
       "path": "${machine:account-home}/.config/qt6ct/qt6ct.conf",
       "owner": "${machine:account}",
       "mode": "0644",
-      "content": "[Appearance]\ncolor_scheme_path=/usr/share/qt6ct/colors/darker.conf\ncustom_palette=true\nicon_theme=Adwaita\nstandard_dialogs=default\nstyle=Fusion\n\n[Fonts]\nfixed=\"JetBrainsMono Nerd Font,11,-1,5,50,0,0,0,0,0\"\ngeneral=\"Inter,11,-1,5,50,0,0,0,0,0\"\n\n[Interface]\nactivate_item_on_single_click=1\nbuttonbox_layout=0\ncursor_flash_time=1000\ndialog_buttons_have_icons=1\ndouble_click_interval=400\ngui_effects=@Invalid()\nkeyboard_scheme=2\nmenus_have_icons=true\nshow_shortcuts_in_context_menus=true\nstylesheets=@Invalid()\ntoolbutton_style=4\nunderline_shortcut=1\nwheel_scroll_lines=3\n\n[Troubleshooting]\nforce_raster_widgets=1\nignored_applications=@Invalid()\n"
+      "template": "files/qt6ct.conf"
     },
     {
       "id": "portals",
@@ -89,7 +142,7 @@
       "path": "${machine:account-home}/.config/xdg-desktop-portal/portals.conf",
       "owner": "${machine:account}",
       "mode": "0644",
-      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208). Replaced at every push.\n#\n# Which portal backend answers each interface. i3 is not a desktop xdg-desktop-portal knows, so with\n# no preference it uses whichever backend happens to be installed: fine while gtk is the only one,\n# wrong the day another arrives as somebody else's dependency. Named instead. gtk also serves\n# org.freedesktop.appearance (dark or light) from GSettings, which the session's start sets.\n[preferred]\ndefault=gtk\n# Secrets for sandboxed programs come from the keyring's backend. Without this line no backend answers\n# the interface: gtk does not implement it, and gnome-keyring's names only GNOME as its desktop.\norg.freedesktop.impl.portal.Secret=gnome-keyring\n"
+      "template": "files/portals.conf"
     },
     {
       "id": "cursor",
@@ -97,7 +150,7 @@
       "path": "${machine:account-home}/.icons/default/index.theme",
       "owner": "${machine:account}",
       "mode": "0644",
-      "content": "# Written by the mesh (module adwaita, novox/hq ADR 0208): the default cursor theme, for programs that\n# read neither XCURSOR_THEME nor the X resources.\n[Icon Theme]\nName=Default\nInherits=Adwaita\n"
+      "template": "files/cursor-index.theme"
     }
   ],
   "build": {
@@ -112,6 +165,11 @@
         "loads": [
           "adwaita-tools"
         ]
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
       }
     ]
   }

modules/artifact-store-tools/README.md

@@ -109,3 +109,9 @@ store's current or an older name, a definition not read said first, escalation t
 tools served are exactly the manifest's `tools` and its `invokes` exactly the two controller verbs and the
 catalogue's two tools.
 Any command other than the two read-only scripts fails the test.
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/artifact-store-tools/cmd/artifact-store-tools/templates_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The module's directory, where its manifest and its files/ are.
+const moduleDir = "../.."
+
+// templateText is the text a file resource places on the machine: its template's, in the module's files/
+// (novox/hq ADR 0349 §2). A resource that names no template, or a template that is not there, fails the test.
+func templateText(t *testing.T, r map[string]any) string {
+	t.Helper()
+	name, _ := r["template"].(string)
+	if name == "" {
+		t.Fatalf("resource %v names no template", r["id"])
+	}
+	raw, err := os.ReadFile(filepath.Join(moduleDir, filepath.FromSlash(name)))
+	if err != nil {
+		t.Fatalf("resource %v names %s: %v", r["id"], name, err)
+	}
+	return string(raw)
+}
+
+// No file resource carries its text inline: each names its template in files/, and the build packs files/
+// into the one archive the controller reads the templates back from (novox/hq ADR 0349 §2).
+func TestEveryFileTakesItsTextFromATemplate(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join(moduleDir, "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Resources []map[string]any `json:"resources"`
+		Build     struct {
+			Artifacts []map[string]any `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in files/ and name it as the template", r["id"])
+		}
+		if r["type"] == "file" {
+			templateText(t, r)
+		}
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "files" {
+			packs++
+			if a["name"] != "files" {
+				t.Errorf("the templates archive is named %v, not files", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Errorf("the build packs files/ into %d archives, not one", packs)
+	}
+}

modules/artifact-store-tools/files/store-names

@@ -0,0 +1,4 @@
+# The names the artifact store had before, from the setting older-store-names, written by the mesh.
+# artifact_store_references reads every definition under these too (novox/hq issue 323).
+# Replaced on every push; change the setting, never this file.
+older=${config:older-store-names}

modules/artifact-store-tools/module.json

@@ -13,19 +13,21 @@
     "artifact_store_references",
     "artifact_store_collect"
   ],
-  "settings": {
-    "older-store-names": {
-      "kind": "preference",
-      "default": "none",
-      "why": "the names the artifact store had before, as a definition may still pin an image under them: host names or host:port, separated by spaces; none when it had no other. artifact_store_references reads every definition under these as well as under the store's current name, so an image a definition pins under one is said to be named by a definition (novox/hq issue 323)"
-    }
-  },
+    "config": {
+      "older-store-names": {
+        "type": "string",
+        "description": "The names the artifact store had before, as host names or host:port separated by spaces, or none when it had no other. artifact_store_references reads every definition under these as well as under the store's current name, so an image a definition pins under one is said to be named by a definition (novox/hq issue 323).",
+        "pattern": "none|[A-Za-z0-9.:-]+( [A-Za-z0-9.:-]+)*",
+        "default": "none"
+      }
+    },
   "resources": [
     {
       "id": "state",
       "type": "directory",
       "mode": "0700",
-      "place": "."
+      "place": ".",
+      "unknown": "program"
     },
     {
       "id": "store-names",
@@ -33,7 +35,7 @@
       "path": "${dir:state}/store-names",
       "mode": "0600",
       "trusted": false,
-      "content": "# The names the artifact store had before, from the setting older-store-names, written by the mesh.\n# artifact_store_references reads every definition under these too (novox/hq issue 323).\n# Replaced on every push; change the setting, never this file.\nolder=${setting:older-store-names}\n"
+      "template": "files/store-names"
     }
   ],
   "build": {
@@ -52,6 +54,11 @@
           "MESH_ARTIFACT_STORE_CONTAINER": "mesh-registry",
           "MESH_ARTIFACT_STORE_NAMES_FILE": "${dir:state}/store-names"
         }
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
       }
     ]
   }

modules/asus-zephyrus-g14/README.md

@@ -385,3 +385,15 @@ The module no longer writes a file into i3's `config.d`. Its window-manager line
 under `files/i3/` where it had one) are a contribution to `node-display-session`. The i3 module places
 them in its own configuration under a `# <module>` line, so this module depends on a window manager
 being assigned beside it.
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `/usr/local/lib/asus-zephyrus-g14`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/systemd/system/systemd-suspend.service.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/systemd/system/systemd-hibernate.service.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/systemd/system/systemd-suspend-then-hibernate.service.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/systemd/system/nvidia-powerd.service.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/UPower/UPower.conf.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/etc/X11/xorg.conf.d`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/asus-zephyrus-g14/cmd/zephyrus/keys_test.go

@@ -34,11 +34,9 @@ func TestKeysListsTriggersI3LinesAndFirmwareKeys(t *testing.T) {
 	home := "/home/operator"
 	t.Setenv("MESH_OPERATOR_HOME", home)
 	// The i3 module's file as the controller composes it: other modules' lines around this one's.
-	var own string
-	for _, c := range m.Contributions {
-		if c.Seat == "node-display-session" {
-			own += c.Content
-		}
+	own := m.i3Lines()
+	if own == "" || len(m.Contributions) != 0 {
+		t.Fatalf("the lines for the window manager are one item, and no contribution is left: %q %v", own, m.Contributions)
 	}
 	put(t, f.root, home+"/"+I3Config, "set $mod Mod4\n# rofi\nbindsym $mod+d exec rofi\n# "+ModuleName+"\n"+own+
 		"# triggerhappy-not-here\nbindsym $mod+Shift+z exec other\n#########################################\ninclude x\n")

modules/asus-zephyrus-g14/cmd/zephyrus/manifest_test.go

@@ -15,19 +15,41 @@ type manifest struct {
 	Tools     []string         `json:"tools"`
 	Emits     []string         `json:"emits"`
 	Resources []map[string]any `json:"resources"`
-	// Contributions to other modules' seats (novox/hq ADR 0212): the vendor keys go to node-hotkeys.
-	Contributions []struct {
-		Seat    string `json:"seat"`
-		Kind    string `json:"kind"`
-		Content string `json:"content"`
-	} `json:"contributions"`
+	// Items of collections (novox/hq ADR 0349 clause 13): the vendor keys are an item of the node-hotkeys
+	// triggers, its text the template file beside the manifest.
+	Items []struct {
+		Collection string `json:"collection"`
+		Template   string `json:"template"`
+	} `json:"items"`
+	// Old-form contributions to other modules' seats (novox/hq ADR 0212): none is left.
+	Contributions []any `json:"contributions"`
 }
 
-// triggers is the module's contribution to node-hotkeys: its vendor keys.
+// i3Lines is the module's lines for the window manager: the text of the template of its item of the collection
+// contribution:node-display-session:config (design 57 L3, issue 848).
+func (m manifest) i3Lines() string {
+	for _, it := range m.Items {
+		if it.Collection == "contribution:node-display-session:config" {
+			raw, err := os.ReadFile(filepath.Join("..", "..", it.Template))
+			if err != nil {
+				return ""
+			}
+			return string(raw)
+		}
+	}
+	return ""
+}
+
+// triggers is the module's contribution to node-hotkeys: its vendor keys, the text of the template of its
+// item of the collection contribution:node-hotkeys:trigger.
 func (m manifest) triggers() string {
-	for _, c := range m.Contributions {
-		if c.Seat == "node-hotkeys" && c.Kind == "trigger" {
-			return c.Content
+	for _, it := range m.Items {
+		if it.Collection == "contribution:node-hotkeys:trigger" {
+			raw, err := os.ReadFile(filepath.Join("..", "..", it.Template))
+			if err != nil {
+				return ""
+			}
+			return string(raw)
 		}
 	}
 	return ""

modules/asus-zephyrus-g14/cmd/zephyrus/templates_test.go

@@ -0,0 +1,83 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// Each file's text is a template in templates/, the directory the manifest names (novox/hq ADR 0349 §2, issue 731),
+// never in files/: files/ is the archive the machine unpacks, and stays exactly what the machine is given.
+func TestEveryFileTakesItsTextFromATemplateOutsideTheUnpackedFiles(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Templates string           `json:"templates"`
+		Resources []map[string]any `json:"resources"`
+		Build     struct {
+			Artifacts []map[string]any `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	if m.Templates != "templates" {
+		t.Fatalf("the manifest names the templates directory %q, not templates", m.Templates)
+	}
+	files := 0
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in templates/ and name it as the template", r["id"])
+		}
+		if r["type"] != "file" {
+			continue
+		}
+		files++
+		name, _ := r["template"].(string)
+		if !strings.HasPrefix(name, "templates/") {
+			t.Errorf("resource %v names the template %q, not one in templates/", r["id"], name)
+			continue
+		}
+		if st, err := os.Lstat(filepath.Join("../..", name)); err != nil || !st.Mode().IsRegular() {
+			t.Errorf("resource %v names the template %s, which is not a plain file: %v", r["id"], name, err)
+		}
+	}
+	if files == 0 {
+		t.Fatal("no file resource")
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "templates" {
+			packs++
+			if a["name"] != "templates" {
+				t.Errorf("the templates archive is named %v, not templates", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Fatalf("the build packs templates/ into %d archives, not one", packs)
+	}
+	// The templates archive is read by the controller, never unpacked onto the machine.
+	for _, r := range m.Resources {
+		if r["artifact"] == "templates" {
+			t.Errorf("resource %v places the templates archive on the machine", r["id"])
+		}
+	}
+	// And files/ holds what the machine runs, no template.
+	err = filepath.WalkDir("../../files", func(at string, d os.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if !d.IsDir() && !strings.HasPrefix(filepath.ToSlash(at), "../../files/bin/") {
+			t.Errorf("files/ holds %s, which is not one of the scripts the machine unpacks", at)
+		}
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+}

modules/asus-zephyrus-g14/module.json

@@ -1,6 +1,8 @@
 {
   "module": "asus-zephyrus-g14",
   "version": "1",
+  "moved": true,
+  "templates": "templates",
   "capabilities": [
     "package-manager",
     "service-manager"
@@ -52,80 +54,85 @@
       "id": "scripts",
       "type": "archive",
       "path": "/usr/local/lib/asus-zephyrus-g14",
-      "artifact": "scripts"
+      "artifact": "scripts",
+      "unknown": "program"
     },
     {
       "id": "nvidia-options",
       "type": "file",
       "path": "/etc/modprobe.d/g14-nvidia-power.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The discrete GPU's driver options on the ROG Zephyrus G14 (GA403, RTX 40 series, hybrid graphics).\n#\n# NVreg_DynamicPowerManagement=0x00 turns runtime D3 off. With it on, a change of power source sends\n# the driver an ACPI notification it fails to handle on this model (\"RmHandleDNotifierEvent: Failed to\n# handle ACPI D-Notifier event, status=0x62\"), and the GPU stops making progress until the machine is\n# powered off. Off costs a few idle watts in hybrid mode and keeps the machine up.\n#\n# NVreg_PreserveVideoMemoryAllocations=1 saves video memory across suspend, so what used the GPU still\n# works after waking. It needs nvidia-suspend, -hibernate and -resume to run around a sleep, which this\n# module's drop-ins on the sleep services ask for.\n#\n# A change here applies when the driver next loads: at the next boot.\noptions nvidia NVreg_PreserveVideoMemoryAllocations=1\noptions nvidia NVreg_DynamicPowerManagement=0x00\n"
+      "template": "templates/modprobe.d/g14-nvidia-power.conf"
     },
     {
       "id": "video-options",
       "type": "file",
       "path": "/etc/modprobe.d/video-brightness-switch.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The ACPI video driver does not change the backlight itself on the brightness keys: on this model it\n# moves the wrong one. The keys are triggerhappy's (see /etc/triggerhappy/triggers.d/asus-g14.conf).\n# Applies when the module next loads: at the next boot.\noptions video brightness_switch_enabled=0\n"
+      "template": "templates/modprobe.d/video-brightness-switch.conf"
     },
     {
       "id": "suspend-drop-ins",
       "type": "directory",
       "path": "/etc/systemd/system/systemd-suspend.service.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "nvidia-on-suspend",
       "type": "file",
       "path": "/etc/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend.service nvidia-resume.service\n"
+      "template": "templates/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf"
     },
     {
       "id": "hibernate-drop-ins",
       "type": "directory",
       "path": "/etc/systemd/system/systemd-hibernate.service.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "nvidia-on-hibernate",
       "type": "file",
       "path": "/etc/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-hibernate.service nvidia-resume.service\n"
+      "template": "templates/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf"
     },
     {
       "id": "suspend-then-hibernate-drop-ins",
       "type": "directory",
       "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "nvidia-on-suspend-then-hibernate",
       "type": "file",
       "path": "/etc/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as\n# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service\n# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.\n[Unit]\nWants=nvidia-suspend-then-hibernate.service nvidia-resume.service\n"
+      "template": "templates/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf"
     },
     {
       "id": "powerd-drop-ins",
       "type": "directory",
       "path": "/etc/systemd/system/nvidia-powerd.service.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "powerd-opt-in",
       "type": "file",
       "path": "/etc/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# nvidia-powerd (Dynamic Boost) was the first error in the chain that hung this model's GPU on a change\n# of power source, and asusd starts it on mains. It runs only when the kernel command line says\n# zephyrus.nvidia-powerd — an explicit opt-in, at boot.\n[Unit]\nConditionKernelCommandLine=zephyrus.nvidia-powerd\n"
+      "template": "templates/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf"
     },
     {
       "id": "backlight-rule",
       "type": "file",
       "path": "/etc/udev/rules.d/90-backlight.rules",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The backlights are writable by the video group, so the brightness keys and the module's brightness tool\n# move the panel without root.\nACTION==\"add\", SUBSYSTEM==\"backlight\", RUN+=\"/usr/bin/chgrp video /sys/class/backlight/%k/brightness\", RUN+=\"/usr/bin/chmod g+w /sys/class/backlight/%k/brightness\"\n"
+      "template": "templates/udev/rules.d/90-backlight.rules"
     },
     {
       "id": "udev",
@@ -144,14 +151,15 @@
       "id": "upower-drop-ins",
       "type": "directory",
       "path": "/etc/UPower/UPower.conf.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "low-battery",
       "type": "file",
       "path": "/etc/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# On low battery the machine suspends rather than powering off, at 7 % — s2idle still draws a little,\n# so it leaves headroom. A drop-in over the package's own UPower.conf, which stays the package's.\n[UPower]\nUsePercentageForPolicy=true\nPercentageLow=15.0\nPercentageCritical=10.0\nPercentageAction=7.0\nCriticalPowerAction=Suspend\nAllowRiskyCriticalPowerAction=true\n"
+      "template": "templates/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf"
     },
     {
       "id": "upower",
@@ -167,14 +175,30 @@
       "id": "xorg-drop-ins",
       "type": "directory",
       "path": "/etc/X11/xorg.conf.d",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "program"
     },
     {
       "id": "touchpad",
       "type": "file",
       "path": "/etc/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf",
       "mode": "0644",
-      "content": "# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.\n#\n# The touchpad's settings, applied by X every time the device appears — at login and after every\n# resume, when the device is initialised again. This replaces the predecessor's sleep hook, which ran\n# xinput after a resume as a named person on a guessed display.\nSection \"InputClass\"\n    Identifier \"asus-zephyrus-g14 touchpad\"\n    MatchIsTouchpad \"on\"\n    Option \"Tapping\" \"on\"\n    Option \"NaturalScrolling\" \"true\"\n    Option \"AccelSpeed\" \"0.15\"\nEndSection\n"
+      "template": "templates/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf"
+    }
+  ],
+  "items": [
+    {
+      "collection": "shell:after-wake:normal",
+      "template": "templates/after-wake"
+    },
+    {
+      "collection": "contribution:node-hotkeys:trigger",
+      "template": "templates/hotkeys-triggers"
+    },
+    {
+      "collection": "contribution:node-display-session:config",
+      "name": "display-session",
+      "template": "templates/display-session"
     }
   ],
   "build": {
@@ -194,31 +218,12 @@
         "name": "scripts",
         "kind": "archive",
         "from": "files"
+      },
+      {
+        "name": "templates",
+        "kind": "archive",
+        "from": "templates"
       }
     ]
-  },
-  "contributions": [
-    {
-      "seat": "node-hotkeys",
-      "kind": "trigger",
-      "content": "# The ROG Zephyrus G14's vendor keys, which reach no X client: media (the M-keys), panel brightness,\n# and the touchpad key. Each runs this module's own script, as the operator's account.\nKEY_PROG1\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media play-pause\nKEY_PROG3\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media previous\nKEY_PROG4\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media next\nKEY_BRIGHTNESSDOWN\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSDOWN\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -\nKEY_BRIGHTNESSUP\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_BRIGHTNESSUP\t2\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +\nKEY_F21\t1\t/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
-    },
-    {
-      "seat": "node-display-session",
-      "kind": "config",
-      "content": "# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the\n# mesh: replaced at every push. Once the controller places contributions to node-display-session\n# (ADR 0210), these become the module's contribution instead of a file in i3's directory.\n#\n# The keys the firmware turns into ordinary key presses. The vendor keys that reach no X client are\n# triggerhappy's (/etc/triggerhappy/triggers.d/asus-g14.conf): M4 and Fn+F4/F5 for media, Fn+F7/F8 for\n# the panel, Fn+F10 for the touchpad. The keyboard backlight (Fn+F2/F3) is the firmware's and asusd's.\n\n# Fn+F6, the screenshot key: the firmware sends Super+Shift+S. Released before it runs, because the\n# screenshot grabs the pointer to select a region, which fails while the key is still held.\nbindsym --release $mod+Shift+s exec --no-startup-id $XDG_CONFIG_HOME/i3/scripts/screenshot.sh\n\n# Fn+F9, the display key: the firmware sends Super+P. Odd workspaces to the panel, even ones to the\n# external output.\nbindsym $mod+p exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display order\n\n# The keyboard backlight's level, shown when it changes.\nexec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-kbd-notify\n"
-    },
-    {
-      "seat": "node-display-session",
-      "kind": "config",
-      "content": "# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the\n# mesh: replaced at every push. Once the controller places contributions to node-display-session\n# (ADR 0210), these become the module's contribution instead of a file in i3's directory.\n#\n# The model's panel and touchpad.\n\n# The internal panel is the primary output, where the bars' tray goes. Which monitors are on and where\n# is the display server's (autorandr, run at every session start).\nexec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display primary\n\n# The touchpad's settings again, by hand. X applies them itself whenever the device appears.\nbindsym $mod+Shift+x exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\n"
-    }
-  ],
-  "shell": [
-    {
-      "for": "after-wake",
-      "slot": "normal",
-      "code": "# The touchpad's settings again after waking, in the operator's session: X applies the module's\n# input class when the device appears, and this covers a wake that does not initialise it again.\n# Runs as root from the power module; the reset itself runs as the session's owner.\nsleep 2\nowner=$(ps -o user= -C i3 | head -n 1)\n[ -n \"$owner\" ] && runuser -u \"$owner\" -- /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset\ntrue\n"
-    }
-  ]
+  }
 }

modules/asus-zephyrus-g14/templates/UPower/UPower.conf.d/50-asus-zephyrus-g14.conf

@@ -0,0 +1,11 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# On low battery the machine suspends rather than powering off, at 7 % — s2idle still draws a little,
+# so it leaves headroom. A drop-in over the package's own UPower.conf, which stays the package's.
+[UPower]
+UsePercentageForPolicy=true
+PercentageLow=15.0
+PercentageCritical=10.0
+PercentageAction=7.0
+CriticalPowerAction=Suspend
+AllowRiskyCriticalPowerAction=true

modules/asus-zephyrus-g14/templates/X11/xorg.conf.d/30-asus-zephyrus-g14-touchpad.conf

@@ -0,0 +1,12 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The touchpad's settings, applied by X every time the device appears — at login and after every
+# resume, when the device is initialised again. This replaces the predecessor's sleep hook, which ran
+# xinput after a resume as a named person on a guessed display.
+Section "InputClass"
+    Identifier "asus-zephyrus-g14 touchpad"
+    MatchIsTouchpad "on"
+    Option "Tapping" "on"
+    Option "NaturalScrolling" "true"
+    Option "AccelSpeed" "0.15"
+EndSection

modules/asus-zephyrus-g14/templates/after-wake

@@ -0,0 +1,7 @@
+# The touchpad's settings again after waking, in the operator's session: X applies the module's
+# input class when the device appears, and this covers a wake that does not initialise it again.
+# Runs as root from the power module; the reset itself runs as the session's owner.
+sleep 2
+owner=$(ps -o user= -C i3 | head -n 1)
+[ -n "$owner" ] && runuser -u "$owner" -- /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset
+true

modules/asus-zephyrus-g14/templates/display-session

@@ -0,0 +1,30 @@
+# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the
+# mesh: replaced at every push. Once the controller places contributions to node-display-session
+# (ADR 0210), these become the module's contribution instead of a file in i3's directory.
+#
+# The keys the firmware turns into ordinary key presses. The vendor keys that reach no X client are
+# triggerhappy's (/etc/triggerhappy/triggers.d/asus-g14.conf): M4 and Fn+F4/F5 for media, Fn+F7/F8 for
+# the panel, Fn+F10 for the touchpad. The keyboard backlight (Fn+F2/F3) is the firmware's and asusd's.
+
+# Fn+F6, the screenshot key: the firmware sends Super+Shift+S. Released before it runs, because the
+# screenshot grabs the pointer to select a region, which fails while the key is still held.
+bindsym --release $mod+Shift+s exec --no-startup-id $XDG_CONFIG_HOME/i3/scripts/screenshot.sh
+
+# Fn+F9, the display key: the firmware sends Super+P. Odd workspaces to the panel, even ones to the
+# external output.
+bindsym $mod+p exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display order
+
+# The keyboard backlight's level, shown when it changes.
+exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-kbd-notify
+# The laptop's own lines in i3 (module asus-zephyrus-g14, novox/hq ADR 0208, ADR 0210). Owned by the
+# mesh: replaced at every push. Once the controller places contributions to node-display-session
+# (ADR 0210), these become the module's contribution instead of a file in i3's directory.
+#
+# The model's panel and touchpad.
+
+# The internal panel is the primary output, where the bars' tray goes. Which monitors are on and where
+# is the display server's (autorandr, run at every session start).
+exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-display primary
+
+# The touchpad's settings again, by hand. X applies them itself whenever the device appears.
+bindsym $mod+Shift+x exec --no-startup-id /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset

modules/asus-zephyrus-g14/templates/hotkeys-triggers

@@ -0,0 +1,10 @@
+# The ROG Zephyrus G14's vendor keys, which reach no X client: media (the M-keys), panel brightness,
+# and the touchpad key. Each runs this module's own script, as the operator's account.
+KEY_PROG1	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media play-pause
+KEY_PROG3	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media previous
+KEY_PROG4	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-session /usr/local/lib/asus-zephyrus-g14/bin/zephyrus-media next
+KEY_BRIGHTNESSDOWN	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -
+KEY_BRIGHTNESSDOWN	2	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight -
+KEY_BRIGHTNESSUP	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +
+KEY_BRIGHTNESSUP	2	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-backlight +
+KEY_F21	1	/usr/local/lib/asus-zephyrus-g14/bin/zephyrus-touchpad reset

modules/asus-zephyrus-g14/templates/modprobe.d/g14-nvidia-power.conf

@@ -0,0 +1,16 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The discrete GPU's driver options on the ROG Zephyrus G14 (GA403, RTX 40 series, hybrid graphics).
+#
+# NVreg_DynamicPowerManagement=0x00 turns runtime D3 off. With it on, a change of power source sends
+# the driver an ACPI notification it fails to handle on this model ("RmHandleDNotifierEvent: Failed to
+# handle ACPI D-Notifier event, status=0x62"), and the GPU stops making progress until the machine is
+# powered off. Off costs a few idle watts in hybrid mode and keeps the machine up.
+#
+# NVreg_PreserveVideoMemoryAllocations=1 saves video memory across suspend, so what used the GPU still
+# works after waking. It needs nvidia-suspend, -hibernate and -resume to run around a sleep, which this
+# module's drop-ins on the sleep services ask for.
+#
+# A change here applies when the driver next loads: at the next boot.
+options nvidia NVreg_PreserveVideoMemoryAllocations=1
+options nvidia NVreg_DynamicPowerManagement=0x00

modules/asus-zephyrus-g14/templates/modprobe.d/video-brightness-switch.conf

@@ -0,0 +1,6 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The ACPI video driver does not change the backlight itself on the brightness keys: on this model it
+# moves the wrong one. The keys are triggerhappy's (see /etc/triggerhappy/triggers.d/asus-g14.conf).
+# Applies when the module next loads: at the next boot.
+options video brightness_switch_enabled=0

modules/asus-zephyrus-g14/templates/systemd/system/nvidia-powerd.service.d/asus-zephyrus-g14.conf

@@ -0,0 +1,7 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# nvidia-powerd (Dynamic Boost) was the first error in the chain that hung this model's GPU on a change
+# of power source, and asusd starts it on mains. It runs only when the kernel command line says
+# zephyrus.nvidia-powerd — an explicit opt-in, at boot.
+[Unit]
+ConditionKernelCommandLine=zephyrus.nvidia-powerd

modules/asus-zephyrus-g14/templates/systemd/system/systemd-hibernate.service.d/asus-zephyrus-g14-nvidia.conf

@@ -0,0 +1,7 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as
+# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service
+# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.
+[Unit]
+Wants=nvidia-hibernate.service nvidia-resume.service

modules/asus-zephyrus-g14/templates/systemd/system/systemd-suspend-then-hibernate.service.d/asus-zephyrus-g14-nvidia.conf

@@ -0,0 +1,7 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as
+# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service
+# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.
+[Unit]
+Wants=nvidia-suspend-then-hibernate.service nvidia-resume.service

modules/asus-zephyrus-g14/templates/systemd/system/systemd-suspend.service.d/asus-zephyrus-g14-nvidia.conf

@@ -0,0 +1,7 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The NVIDIA driver's own sleep actions, asked for by the sleep itself rather than enabled as
+# links: the mesh declares files and never makes links (novox/hq ADR 0012), and the host's service
+# shape must not start these units by hand, which would put the GPU to sleep with the machine awake.
+[Unit]
+Wants=nvidia-suspend.service nvidia-resume.service

modules/asus-zephyrus-g14/templates/udev/rules.d/90-backlight.rules

@@ -0,0 +1,5 @@
+# Managed by the mesh (module asus-zephyrus-g14). Replaced on every push; edit the catalogue instead.
+#
+# The backlights are writable by the video group, so the brightness keys and the module's brightness tool
+# move the panel without root.
+ACTION=="add", SUBSYSTEM=="backlight", RUN+="/usr/bin/chgrp video /sys/class/backlight/%k/brightness", RUN+="/usr/bin/chmod g+w /sys/class/backlight/%k/brightness"

modules/audit-logger/README.md

@@ -0,0 +1,11 @@
+# audit-logger
+
+The `audit-logger` module of the mesh catalogue: declares directories on the node.
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `${dir:trail}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `${dir:spool}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/audit-logger/module.json

@@ -47,17 +47,20 @@
       "id": "state",
       "type": "directory",
       "mode": "0700",
-      "place": "."
+      "place": ".",
+      "unknown": "program"
     },
     {
       "id": "trail",
       "type": "directory",
-      "mode": "0700"
+      "mode": "0700",
+      "unknown": "program"
     },
     {
       "id": "spool",
       "type": "directory",
-      "mode": "0700"
+      "mode": "0700",
+      "unknown": "program"
     }
   ],
   "capabilities": [

modules/baserow/README.md

@@ -0,0 +1,11 @@
+# baserow
+
+The `baserow` module of the mesh catalogue: runs the container image `baserow/baserow`.
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:mesh-state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `${dir:data}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/baserow/files/config.json

@@ -0,0 +1,4 @@
+{
+  "password": "${secret:admin}",
+  "host": "${bound:route:name}"
+}

modules/baserow/files/server.env

@@ -0,0 +1,7 @@
+DATABASE_HOST=${bound:postgres-database:at}
+DATABASE_PORT=${bound:postgres-database:port}
+DATABASE_NAME=${bound:postgres-database:as}
+DATABASE_USER=${bound:postgres-database:as}
+DATABASE_PASSWORD_FILE=/run/secrets/database
+DISABLE_EMBEDDED_PSQL=true
+BASEROW_PUBLIC_URL=https://${bound:route:name}

modules/baserow/module.json

@@ -46,31 +46,54 @@
       }
     ]
   },
+  "config": {
+    "host": {
+      "type": "string",
+      "description": "The Host header the module's tools send to Baserow, a host name; the file's default is the name the module's route was given.",
+      "trusted": true,
+      "default": "${bound:route:name}"
+    },
+    "email": {
+      "type": "string",
+      "description": "The email address of the Baserow account the module's tools sign in as; unset, the code falls back to its environment.",
+      "trusted": true,
+      "default": ""
+    },
+    "url": {
+      "type": "string",
+      "description": "The address the module's tools reach Baserow at, as a URL; unset, the code falls back to its environment, else this machine's Baserow on port 80.",
+      "trusted": true,
+      "default": ""
+    }
+  },
   "resources": [
     {
       "id": "mesh-state",
       "type": "directory",
       "mode": "0700",
-      "place": "mesh"
+      "place": "mesh",
+      "unknown": "program"
     },
     {
       "id": "state",
       "type": "directory",
       "mode": "0700",
-      "place": "."
+      "place": ".",
+      "unknown": "program"
     },
     {
       "id": "data",
       "type": "directory",
       "mode": "0755",
-      "owner": "9999:9999"
+      "owner": "9999:9999",
+      "unknown": "program"
     },
     {
       "id": "server-env",
       "type": "file",
       "path": "${dir:state}/server.env",
       "mode": "0600",
-      "content": "DATABASE_HOST=${bound:postgres-database:at}\nDATABASE_PORT=${bound:postgres-database:port}\nDATABASE_NAME=${bound:postgres-database:as}\nDATABASE_USER=${bound:postgres-database:as}\nDATABASE_PASSWORD_FILE=/run/secrets/database\nDISABLE_EMBEDDED_PSQL=true\nBASEROW_PUBLIC_URL=https://${bound:route:name}\n"
+      "template": "files/server.env"
     },
     {
       "id": "net",
@@ -102,8 +125,9 @@
       "type": "file",
       "path": "${dir:mesh-state}/config.json",
       "mode": "0600",
-      "content": "{\n  \"password\": \"${secret:admin}\",\n  \"host\": \"${bound:route:name}\"\n}\n",
+      "template": "files/config.json",
       "merge": "json",
+      "takes-config": ["host", "email", "url"],
       "protected": ["password"]
     }
   ],
@@ -123,6 +147,11 @@
           "MESH_BASEROW_URL": "http://127.0.0.1:${port:80}",
           "MESH_BASEROW_CONFIG_FILE": "${dir:mesh-state}/config.json"
         }
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
       }
     ]
   }

modules/betterbird/README.md

@@ -208,7 +208,7 @@ node set up from nothing, the declared accounts are written at the second start
 
 Five more settings, mesh-wide with a node's layer over each (an entry set to `null` in a node's layer is not on
 that node). `identities`, `calendars`, `address-books` and `filters` reach the machine as
-`~/.config/betterbird/configuration.json`, trusted as `accounts` is; `tags` as `tags.json`, not trusted (§5).
+`~/.config/betterbird/configuration.json`, trusted as `accounts` is; `tags` as `tags.json`, trusted too since issue 751 (the operator's decision), so a change to it is the operator's to approve.
 **No value holds a password, a token or a cookie**: a key shaped like one is refused, and so is an address whose
 user part carries a password (§2). A setting holds no line break, so a signature is a list of its lines.
 
@@ -347,3 +347,14 @@ outside the mesh. With this version, a push to a node (each waits for the operat
 - The controller's `settings` verb, for every proposal and to read a layer as it stands; its `nodes` and `node`
   verbs, for which machines hold the module; and the module's own `betterbird_derive` on those machines
   (`invokes`).
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `~/.config/betterbird`: holds only what this module declares and its own tools' records: `accounts-record.json` (`cmd/betterbird-tools/adoption.go:36`), `configuration-record.json` (`owned.go:33`) and the `kept/` folder of replaced filter files (`filters.go:261`); anything else is moved out by the node-engine to `~/.local/state/mesh-moved/betterbird/` with a list, never deleted (ADR 0422 §4).
+- `/opt/betterbird`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/opt/betterbird/owl`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/opt/betterbird/distribution`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/opt/betterbird/defaults/pref`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- `/usr/local/lib/mesh-betterbird`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).

modules/betterbird/cmd/betterbird-tools/configuration.go

@@ -7,7 +7,8 @@ package main
 //
 //   - ~/.config/betterbird/configuration.json: identities, calendars, address-books and filters, trusted as
 //     accounts is (§5), because each names where a password, a reply or forwarded mail goes;
-//   - ~/.config/betterbird/tags.json: tags, which names no server and sends no mail, and is not trusted.
+//   - ~/.config/betterbird/tags.json: tags, which names no server and sends no mail; trusted too since issue 751,
+//     so a change to it is the operator's to approve.
 //
 // An entry is keyed by a name of the operator's (lower-case letters and digits, as an account's), a tag by its
 // own key. A node's layer may set an entry to null to take it out on that node, and may give an identity, a

modules/betterbird/cmd/betterbird-tools/manifest_test.go

@@ -25,7 +25,7 @@ type manifest struct {
 	Upgrade   map[string]string `json:"upgrade"`
 	Requires  []string          `json:"requires"`
 	Invokes   []string          `json:"invokes"`
-	Settings  map[string]any    `json:"settings"`
+	Config    map[string]any    `json:"config"`
 	Tools     []string          `json:"tools"`
 	Resources []map[string]any  `json:"resources"`
 	Build     struct {
@@ -114,13 +114,21 @@ func TestItPlacesBetterbirdWhereTheCommunityPackageDidAndOnlyAfterItIsGone(t *te
 	}
 }
 
-// ADR 0329 §4–§6, ADR 0326, issue 586: every setting reaches the machine as a mergeable file of the account's that
-// names the keys it takes; four kinds and accounts and prefs are trusted, tags is not; no setting has a default in the
-// definition, since each is the operator's own value; and each file's default declares nothing.
-func TestTheSettingsAreMergeableFilesThatNameTheirKeysAndTagsAloneIsUntrusted(t *testing.T) {
+// ADR 0329 §4–§6, ADR 0326, issue 586, ADR 0348: every value reaches the machine as a mergeable file of the
+// account's that names the keys it takes, and every one is trusted, tags too since issue 751 (the operator's
+// decision); each is an object whose default is the file's own, empty, never required, since a node without the
+// operator's setup still runs Betterbird; and each file's default declares nothing.
+func TestTheValuesAreTrustedMergeableFilesThatNameTheirKeys(t *testing.T) {
 	m, _ := readManifest(t)
-	if len(m.Settings) != 0 {
-		t.Fatalf("no setting has a default in the definition: the operator's setup is the settings' mesh-wide layer (issue 586, ADR 0262): %v", m.Settings)
+	if _, said := m.Config["tags"]; !said || len(m.Config) != 7 {
+		t.Fatalf("the seven values are declared under config: %v", m.Config)
+	}
+	for key, raw := range m.Config {
+		d, _ := raw.(map[string]any)
+		def, _ := d["default"].(map[string]any)
+		if d["type"] != "object" || d["trusted"] != true || d["required"] != nil || def == nil || len(def) != 0 {
+			t.Errorf("%s is a trusted object whose default is empty and which is not required: %v", key, d)
+		}
 	}
 	files := map[string]struct {
 		path, mode string
@@ -130,7 +138,7 @@ func TestTheSettingsAreMergeableFilesThatNameTheirKeysAndTagsAloneIsUntrusted(t
 		"prefs":         {prefsFile, "0644", []any{"prefs"}, true},
 		"accounts":      {accountsFile, "0600", []any{"accounts"}, true},
 		"configuration": {configurationFile, "0600", []any{"identities", "calendars", "address-books", "filters"}, true},
-		"tags":          {tagsFile, "0644", []any{"tags"}, false},
+		"tags":          {tagsFile, "0644", []any{"tags"}, true},
 	}
 	merging := 0
 	for _, r := range m.Resources {
@@ -144,27 +152,27 @@ func TestTheSettingsAreMergeableFilesThatNameTheirKeysAndTagsAloneIsUntrusted(t
 	for id, want := range files {
 		r := resource(t, m, id)
 		if r["path"] != "${machine:account-home}/"+want.path || r["merge"] != "json" || r["trusted"] != want.trusted ||
-			r["mode"] != want.mode || r["owner"] != "${machine:account}" || !reflect.DeepEqual(r["takes-settings"], want.takes) {
+			r["mode"] != want.mode || r["owner"] != "${machine:account}" || !reflect.DeepEqual(r["takes-config"], want.takes) {
 			t.Errorf("%s: %v", id, r)
 		}
 		var content map[string]any
-		if err := json.Unmarshal([]byte(r["content"].(string)), &content); err != nil || len(content) != len(want.takes) {
+		if err := json.Unmarshal([]byte(templateText(t, r)), &content); err != nil || len(content) != len(want.takes) {
 			t.Errorf("%s's default holds each key it takes, empty: %v %v", id, content, err)
 		}
 	}
-	got, err := parseAccounts([]byte(resource(t, m, "accounts")["content"].(string)))
+	got, err := parseAccounts([]byte(templateText(t, resource(t, m, "accounts"))))
 	if err != nil || len(got) != 0 {
 		t.Fatalf("its default declares no account: %v %v", got, err)
 	}
-	prefs, err := parseDeclaredPrefs([]byte(resource(t, m, "prefs")["content"].(string)))
+	prefs, err := parseDeclaredPrefs([]byte(templateText(t, resource(t, m, "prefs"))))
 	if err != nil || len(prefs) != 0 {
 		t.Fatalf("its default declares no preference: %v %v", prefs, err)
 	}
 	var c Configuration
-	if err := decodeInto([]byte(resource(t, m, "configuration")["content"].(string)), configurationFile, &c); err != nil {
+	if err := decodeInto([]byte(templateText(t, resource(t, m, "configuration"))), configurationFile, &c); err != nil {
 		t.Fatal(err)
 	}
-	if err := decodeInto([]byte(resource(t, m, "tags")["content"].(string)), tagsFile, &c); err != nil {
+	if err := decodeInto([]byte(templateText(t, resource(t, m, "tags"))), tagsFile, &c); err != nil {
 		t.Fatal(err)
 	}
 }
@@ -268,13 +276,13 @@ func TestThePolicyTurnsTheUpdaterOffAndInstallsTheMeshsOwlEverywhere(t *testing.
 func TestTheStartPreparesThenStartsBetterbirdAndTheLauncherUsesIt(t *testing.T) {
 	m, _ := readManifest(t)
 	start := resource(t, m, "start")
-	content := start["content"].(string)
+	content := templateText(t, start)
 	if start["path"] != "/usr/local/bin/betterbird" || start["mode"] != "0755" ||
 		!strings.Contains(content, "\n"+preparation+" prepare ||") || !strings.HasSuffix(content, "\nexec "+startBin+" \"$@\"\n") {
 		t.Fatalf("the start runs the preparation, says when it did not complete, and starts Betterbird either way: %v", start)
 	}
 	launcher := resource(t, m, "launcher")
-	lc := launcher["content"].(string)
+	lc := templateText(t, launcher)
 	if launcher["path"] != "/usr/local/share/applications/eu.betterbird.Betterbird.desktop" ||
 		!strings.Contains(lc, "\nExec=/usr/local/bin/betterbird %u\n") || !strings.Contains(lc, "\nIcon="+installDir+"/") ||
 		!strings.Contains(lc, "\nStartupWMClass=eu.betterbird.Betterbird\n") {

modules/betterbird/cmd/betterbird-tools/templates_test.go

@@ -0,0 +1,64 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// The module's directory, where its manifest and its files/ are.
+const moduleDir = "../.."
+
+// templateText is the text a file resource places on the machine: its template's, in the module's files/
+// (novox/hq ADR 0349 §2). A resource that names no template, or a template that is not there, fails the test.
+func templateText(t *testing.T, r map[string]any) string {
+	t.Helper()
+	name, _ := r["template"].(string)
+	if name == "" {
+		t.Fatalf("resource %v names no template", r["id"])
+	}
+	raw, err := os.ReadFile(filepath.Join(moduleDir, filepath.FromSlash(name)))
+	if err != nil {
+		t.Fatalf("resource %v names %s: %v", r["id"], name, err)
+	}
+	return string(raw)
+}
+
+// No file resource carries its text inline: each names its template in files/, and the build packs files/
+// into the one archive the controller reads the templates back from (novox/hq ADR 0349 §2).
+func TestEveryFileTakesItsTextFromATemplate(t *testing.T) {
+	raw, err := os.ReadFile(filepath.Join(moduleDir, "module.json"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var m struct {
+		Resources []map[string]any `json:"resources"`
+		Build     struct {
+			Artifacts []map[string]any `json:"artifacts"`
+		} `json:"build"`
+	}
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range m.Resources {
+		if _, inline := r["content"]; inline {
+			t.Errorf("resource %v keeps its text inline: keep it in files/ and name it as the template", r["id"])
+		}
+		if r["type"] == "file" {
+			templateText(t, r)
+		}
+	}
+	packs := 0
+	for _, a := range m.Build.Artifacts {
+		if a["kind"] == "archive" && a["from"] == "files" {
+			packs++
+			if a["name"] != "files" {
+				t.Errorf("the templates archive is named %v, not files", a["name"])
+			}
+		}
+	}
+	if packs != 1 {
+		t.Errorf("the build packs files/ into %d archives, not one", packs)
+	}
+}

modules/betterbird/files/accounts.json

@@ -0,0 +1,3 @@
+{
+  "accounts": {}
+}

modules/betterbird/files/betterbird

@@ -0,0 +1,10 @@
+#!/bin/sh
+# Betterbird's start, written by the mesh (module betterbird, novox/hq ADR 0316). Replaced at every push.
+#
+# Before Betterbird starts, the module's tools place its user.js in the profile (the settings prefs, accounts, identities, calendars,
+# address-books and tags) and write what Betterbird rewrites itself: the account lists and each declared account's filters. They do
+# it only while no Betterbird of this account runs, because Betterbird rewrites its saved preferences when it quits; a
+# second start while one runs only hands over to it. What the preparation could not do it says here, and
+# betterbird_check says it too. Betterbird starts either way: its configuration never holds the mail back.
+/usr/local/lib/mesh-betterbird/betterbird-tools prepare || echo "betterbird: the mesh's preparation did not complete; betterbird_check says why" >&2
+exec /opt/betterbird/betterbird "$@"

modules/betterbird/files/configuration.json

@@ -0,0 +1,6 @@
+{
+  "identities": {},
+  "calendars": {},
+  "address-books": {},
+  "filters": {}
+}

modules/betterbird/files/eu.betterbird.Betterbird.desktop

@@ -0,0 +1,25 @@
+[Desktop Entry]
+Version=1.0
+Type=Application
+Name=Betterbird
+GenericName=Mail Client
+Comment=Send and receive mail with Betterbird
+Exec=/usr/local/bin/betterbird %u
+Icon=/opt/betterbird/chrome/icons/default/default128.png
+Terminal=false
+Categories=Network;Email;
+MimeType=message/rfc822;x-scheme-handler/mailto;application/x-xpinstall;application/x-extension-ics;text/calendar;text/vcard;text/x-vcard;x-scheme-handler/webcal;x-scheme-handler/webcals;x-scheme-handler/mid;
+StartupNotify=true
+StartupWMClass=eu.betterbird.Betterbird
+Keywords=Email;E-mail;Calendar;Thunderbird;
+Actions=ComposeMessage;OpenAddressBook;
+# Written by the mesh (module betterbird, novox/hq ADR 0316 §3), in place of the community package's entry:
+# it starts Betterbird through the module's start, and names the icon in the installation, with no link.
+
+[Desktop Action ComposeMessage]
+Name=Write new message
+Exec=/usr/local/bin/betterbird -compose
+
+[Desktop Action OpenAddressBook]
+Name=Open address book
+Exec=/usr/local/bin/betterbird -addressbook

modules/betterbird/files/prefs.json

@@ -0,0 +1,3 @@
+{
+  "prefs": {}
+}

modules/betterbird/files/tags.json

@@ -0,0 +1,3 @@
+{
+  "tags": {}
+}

modules/betterbird/module.json

@@ -33,13 +33,59 @@
     "betterbird_drift",
     "betterbird_reminder_test"
   ],
+  "config": {
+    "prefs": {
+      "type": "object",
+      "description": "Betterbird's preferences the operator sets, by their own names (mailnews.*, calendar.* and the like), laid into prefs.json; an account's, a server's and a tag's are refused, as accounts, the four kinds and tags own them (novox/hq ADR 0329 §6).",
+      "trusted": true,
+      "default": {}
+    },
+    "accounts": {
+      "type": "object",
+      "description": "The mail accounts Betterbird is set up with, each by a name of the operator's: its address, its sender's name and its incoming and outgoing servers; no password, token or cookie (novox/hq ADR 0329 §2).",
+      "trusted": true,
+      "default": {}
+    },
+    "identities": {
+      "type": "object",
+      "description": "The identities beside an account's own, each by a name of the operator's: the address and name it sends as, its signature as a list of lines, and the profile's key to adopt on a node.",
+      "trusted": true,
+      "default": {}
+    },
+    "calendars": {
+      "type": "object",
+      "description": "The calendars Betterbird shows, each by a name of the operator's: where it is and how it is reached, and the profile's key to adopt on a node.",
+      "trusted": true,
+      "default": {}
+    },
+    "address-books": {
+      "type": "object",
+      "description": "The address books Betterbird uses, each by a name of the operator's: where it is and how it is reached, and the profile's key to adopt on a node.",
+      "trusted": true,
+      "default": {}
+    },
+    "filters": {
+      "type": "object",
+      "description": "The message filters of each account, by account: what each matches and what it does with the mail.",
+      "trusted": true,
+      "default": {}
+    },
+    "tags": {
+      "type": "object",
+      "description": "The tags Betterbird offers, each by its own key: its name, colour and order; trusted since issue 751, so a change to it is the operator's to approve.",
+      "trusted": true,
+      "default": {}
+    }
+  },
   "resources": [
     {
       "id": "configuration-dir",
       "type": "directory",
       "path": "${machine:account-home}/.config/betterbird",
       "owner": "${machine:account}",
-      "mode": "0755"
+      "mode": "0755",
+      "unknown": "move-out",
+      "knows": ["accounts-record.json", "configuration-record.json", "kept/"]
     },
     {
       "id": "prefs",
@@ -48,10 +94,10 @@
       "owner": "${machine:account}",
       "mode": "0644",
       "merge": "json",
-      "takes-settings": [
+      "takes-config": [
         "prefs"
       ],
-      "content": "{\n  \"prefs\": {}\n}\n",
+      "template": "files/prefs.json",
       "trusted": true
     },
     {
@@ -61,10 +107,10 @@
       "owner": "${machine:account}",
       "mode": "0600",
       "merge": "json",
-      "takes-settings": [
+      "takes-config": [
         "accounts"
       ],
-      "content": "{\n  \"accounts\": {}\n}\n",
+      "template": "files/accounts.json",
       "trusted": true
     },
     {
@@ -74,13 +120,13 @@
       "owner": "${machine:account}",
       "mode": "0600",
       "merge": "json",
-      "takes-settings": [
+      "takes-config": [
         "identities",
         "calendars",
         "address-books",
         "filters"
       ],
-      "content": "{\n  \"identities\": {},\n  \"calendars\": {},\n  \"address-books\": {},\n  \"filters\": {}\n}\n",
+      "template": "files/configuration.json",
       "trusted": true
     },
     {
@@ -90,11 +136,11 @@
       "owner": "${machine:account}",
       "mode": "0644",
       "merge": "json",
-      "takes-settings": [
+      "takes-config": [
         "tags"
       ],
-      "content": "{\n  \"tags\": {}\n}\n",
-      "trusted": false
+      "template": "files/tags.json",
+      "trusted": true
     },
     {
       "id": "community-package",
@@ -106,45 +152,50 @@
       "id": "installation",
       "type": "archive",
       "path": "/opt/betterbird",
-      "artifact": "archive"
+      "artifact": "archive",
+      "unknown": "program"
     },
     {
       "id": "owl",
       "type": "archive",
       "path": "/opt/betterbird/owl",
-      "artifact": "owl"
+      "artifact": "owl",
+      "unknown": "program"
     },
     {
       "id": "policies",
       "type": "archive",
       "path": "/opt/betterbird/distribution",
-      "artifact": "distribution"
+      "artifact": "distribution",
+      "unknown": "program"
     },
     {
       "id": "spelling",
       "type": "archive",
       "path": "/opt/betterbird/defaults/pref",
-      "artifact": "defaults"
+      "artifact": "defaults",
+      "unknown": "program"
     },
     {
       "id": "preparation",
       "type": "archive",
       "path": "/usr/local/lib/mesh-betterbird",
-      "artifact": "tools"
+      "artifact": "tools",
+      "unknown": "program"
     },
     {
       "id": "start",
       "type": "file",
       "path": "/usr/local/bin/betterbird",
       "mode": "0755",
-      "content": "#!/bin/sh\n# Betterbird's start, written by the mesh (module betterbird, novox/hq ADR 0316). Replaced at every push.\n#\n# Before Betterbird starts, the module's tools place its user.js in the profile (the settings prefs, accounts, identities, calendars,\n# address-books and tags) and write what Betterbird rewrites itself: the account lists and each declared account's filters. They do\n# it only while no Betterbird of this account runs, because Betterbird rewrites its saved preferences when it quits; a\n# second start while one runs only hands over to it. What the preparation could not do it says here, and\n# betterbird_check says it too. Betterbird starts either way: its configuration never holds the mail back.\n/usr/local/lib/mesh-betterbird/betterbird-tools prepare || echo \"betterbird: the mesh's preparation did not complete; betterbird_check says why\" >&2\nexec /opt/betterbird/betterbird \"$@\"\n"
+      "template": "files/betterbird"
     },
     {
       "id": "launcher",
       "type": "file",
       "path": "/usr/local/share/applications/eu.betterbird.Betterbird.desktop",
       "mode": "0644",
-      "content": "[Desktop Entry]\nVersion=1.0\nType=Application\nName=Betterbird\nGenericName=Mail Client\nComment=Send and receive mail with Betterbird\nExec=/usr/local/bin/betterbird %u\nIcon=/opt/betterbird/chrome/icons/default/default128.png\nTerminal=false\nCategories=Network;Email;\nMimeType=message/rfc822;x-scheme-handler/mailto;application/x-xpinstall;application/x-extension-ics;text/calendar;text/vcard;text/x-vcard;x-scheme-handler/webcal;x-scheme-handler/webcals;x-scheme-handler/mid;\nStartupNotify=true\nStartupWMClass=eu.betterbird.Betterbird\nKeywords=Email;E-mail;Calendar;Thunderbird;\nActions=ComposeMessage;OpenAddressBook;\n# Written by the mesh (module betterbird, novox/hq ADR 0316 §3), in place of the community package's entry:\n# it starts Betterbird through the module's start, and names the icon in the installation, with no link.\n\n[Desktop Action ComposeMessage]\nName=Write new message\nExec=/usr/local/bin/betterbird -compose\n\n[Desktop Action OpenAddressBook]\nName=Open address book\nExec=/usr/local/bin/betterbird -addressbook\n"
+      "template": "files/eu.betterbird.Betterbird.desktop"
     }
   ],
   "build": {
@@ -191,6 +242,11 @@
         "name": "defaults",
         "kind": "archive",
         "from": "install/defaults-pref"
+      },
+      {
+        "name": "files",
+        "kind": "archive",
+        "from": "files"
       }
     ]
   }

modules/brother/README.md

@@ -0,0 +1,144 @@
+# brother — the Brother multifunction device: scan, printer state, admin pages
+
+One module for one device (novox/hq ADR 0467, issue 1453): the scanner and the printer are one machine on the
+network, so one module serves both. It claims two seats, each held once for the mesh: `scanner` (verbs `scan`,
+`status`, `list`, `document`) and `printer` (verbs `status`, `settings`, `print`, `upload`; `restart` follows in a later round). It replaces the
+`scan` module of issue 1440 (ADR 0464), which ran on no node and is gone from the catalogue.
+
+## The scanner seat
+
+Built for issue 1440 as novox/hq ADR 0464 decides. It scans the glass of a network scanner (any scanner that
+speaks eSCL, also called AirScan or Mopria), cuts the document out of the lid's white, files it as a one-page PDF
+in a folder and says `scan.added` on the bus, so other modules can react. A scan happens when a tool is called:
+the module runs no process of its own, and it runs as the node's operator account.
+
+## What a scan does
+
+1. Asks the scanner for its sizes and puts one job to it (`POST <scanner>/ScanJobs`) at the configured resolution
+   and colour mode, as a JPEG: from the glass (`source` glass, the default) or from the document feeder (`source`
+   feeder, with `duplex` true for both sides of each sheet; refused on the glass). The region is A4, cut to what the
+   input can scan (the glass is 3507 high, not A4's 3508). The body is written on one line: the Brother ignores the
+   whole body, and runs its default job, when it holds a line break (issue 1452). The glass page is fetched once;
+   a feeder job is asked `NextDocument` until the scanner answers 404, at most 100 pages. A job that fails is deleted.
+2. Reads the resolution from the image's own JFIF density, never from the request: a scanner may answer a
+   300 dpi request with 200 dpi, and the page size and the event's millimetres follow what it gave.
+3. Crops the glass page (a feeder page is a whole sheet and is never cropped): the lid's level is measured in the corner farthest from where documents lie, a pixel is document when
+   it is darker than the lid, and the rows and columns holding enough of them give the box. No document, or one
+   filling nearly the whole glass, keeps the whole image (`cropped` false), and so does `crop` false.
+   With `apart` true (opt-in; without it the glass gives one document, as it always did), several documents lying apart on the glass are each cut out and filed as a one-page PDF of its own (own
+   object, own `scan.added`, own file); the answer then lists them as `documents` (each with its `path`) and
+   `count`, in reading order, and one that could not be kept or filed is named in `failed` without holding back
+   the others. The rule (`Boxes` in `crop.go`): the picture is cut into blocks of 1 mm; a block is document when a
+   quarter of its pixels are darker than the lid; blocks not at least three across (dust, JPEG ringing) are dropped;
+   blocks within 10 mm of each other are one region, so a white band narrower than that does not split a document;
+   a region under 20 mm on a side is a stain, not a document; regions whose boxes overlap are one document (a frame
+   and the text inside it). One document, or none, is cropped exactly as before.
+4. Files a PDF holding the JPEGs, one page for the glass and one per image for the feeder (so six for three
+   sheets both sides), each page as large as its image really is: written whole beside its place as `.scan-*.tmp` and renamed to
+   `scan-YYYY-MM-DD-HHMMSS.pdf` (local time); a taken name gets `-2`, `-3`, and no file is ever overwritten.
+5. Says `scan.added` once, after the rename, under the file's sha256 as its message id. It never carries the image.
+
+A scanner that refuses or gives no page files nothing and says nothing on the bus; the tool's error says why.
+
+## Config
+
+| key | meaning | default |
+|---|---|---|
+| `scanner` | the scanner's eSCL address, such as `http://192.0.2.10/eSCL` (required, trusted) | none |
+| `scan-folder` | the absolute path the PDFs are filed in (required, trusted) | none |
+| `printer` | the printer's host, such as `192.0.2.10`, for its admin page and IPP (required, trusted) | none |
+| `printer-certificate` | the SHA-256 fingerprint of the certificate the admin page may serve, `AA:BB:...`; several, separated by commas, when it serves more than one (required, trusted) | none |
+| `resolution` | dpi asked: 100, 200, 300 or 600 | 300 |
+| `color-mode` | `color` or `gray` | `color` |
+| `crop` | cut the document out of the lid's white | true |
+
+The values reach the code in one file, `settings.json` in the module's state directory, which the mesh writes
+from the config; the code reads it at every call. With `scanner` or `scan-folder` unset, every scanner verb says which and
+writes and asks nothing; `printer` and `printer-certificate` are the printer verbs' to say.
+
+The scan folder is not a manifest resource: a directory's path cannot take a config value (issue 1441), so the code
+makes it (mode 0755) when it files the first scan.
+
+## Tools
+
+| verb (tool) | does |
+|---|---|
+| `scanner.scan` | `source` (`glass`, default, or `feeder`), `duplex` (feeder only) and `apart` (glass only): asks the device process to scan, crop (glass only), keep the PDF in the bucket under its sha256 and say `scan.added`; then fetches it in parts, checks the sha256 and files it in `scan-folder`, in the background, so a scan is filed whether or not the caller still waits. A glass scan is waited for up to 180 s. Several glass pages in one PDF (a page turned over, a stapled document): `document` `start` scans page 1 into a new document and answers its id (nothing is filed yet), `document` with that id scans the next page, and `document` with the id and `finish` true closes it into one multi-page PDF, filed once with one `scan.added` (nothing is scanned). The pages are kept in the bucket under `pending/<id>/` (not in memory, so a restart of the device process loses none); a document that gets no page for 30 minutes is closed and filed so by the tool process (a restart of the tool process forgets that timer; `finish` still works). The pages in the bucket are not deleted, the bucket having no delete. A feeder scan is waited for 25 s (the mesh console gives up after 30 s); if it is not done, the answer is `started: true` with its `id`, and `scanner.scan {id}` reads the outcome (`state` running, done with the event's body and `path`, or failed with `why`). The device process ends a feeder job at 20 s a page (at least 3 min, at most 30 min). A scan whose PDF the tool could not fetch (over 100 MiB) is refused before it is kept or announced. Answers the event's body and `path` |
+| `scanner.document` | one part of a kept scan (`object`, `part` from 1): `part`, `parts`, `size`, `sha256` (of the whole), `data` (base64). Join the parts and check the sha256 |
+| `scanner.status` | whether the scanner answers, its state (Idle or Processing) and its document feeder's state; a scanner that does not answer is `answers: false` with why. |
+| `brother_health` | the module's health, asked by the node-engine every 60 s (ADR 0240) as the tool check of the `watch` process, beside the device process's unit check: the certificates the printer serves, one for each key type (ECDSA and RSA, told apart by the cipher suites offered under TLS 1.2), read with no login and compared with the pinned `printer-certificate` list. Unhealthy when one is not pinned, `why` naming the new fingerprint, so the pin can be changed before the admin pages are needed. With `printer` or `printer-certificate` not given it answers `state: waits` with `waits` naming each setting (the SDK's health.Waiting, ADR 0283), not an error. Each handshake is bounded by 3 s and the whole check by 7 s. A printer that does not answer is healthy, with `why` saying nothing was compared (it may be switched off). The process's liveness is judged by the node-engine without a declaration |
+| `scanner.list` | the newest filed scans, newest first (`limit`, default 20). Read-only |
+
+## The printer seat
+
+| verb (tool) | does |
+|---|---|
+| `printer.status` | without a login: over IPP (`Get-Printer-Attributes`, encoded by hand, on port 631) the state (idle, processing, stopped), the state reasons (such as `toner-low-warning`) and the markers' names, levels (percent; below 0 is unknown) and colours; over eSCL the scanner's state and its feeder's. A part that does not answer is `answers: false` with why. Needs `printer` and `scanner` |
+| `printer.upload` | one part of a document to print later (`upload` id, `part`, `parts`, `sha256` of the whole, `data` base64): stored as `uploads/<upload>.pdf` or `.jpg` once all parts came and the sha256 matches; a wrong sha256, a part out of range or a document that is neither PDF nor JPEG stores nothing |
+| `printer.print` | prints a file on the machine the tool runs on (`path`, absolute, a regular file under the tool account's home folder after symbolic links are resolved; any other path is refused with the one message "path refused: only a file under the home folder", which says nothing of whether it exists: the tool reads it, uploads it in parts and prints it in one call; PDF or JPEG by its bytes, never its name), a kept scan (`object`) or a completed upload (`upload`, for modules that send bytes over the bus) as an IPP Print-Job (operation 0x0002, port 631) in its own format, `copies` 1 to 99 (default 1), `sides` one-sided, two-sided-long-edge or two-sided-short-edge (default one-sided), `media` (default `iso_a4_210x297mm`); answers the job's id and state (with `path`, the upload id and the size when `path` was given) |
+| `printer.settings` | asks the device process (below) to log in, read one admin page and log out, and waits up to 60 s for its answer. Argument `page`: a path on the admin site, starting with `/` and ending in `.html` (default `/general/status.html`). Answers the page's title and forms with their fields, each with its current value (a radio group as one field with the checked button's value, a checkbox with `checked`, a select with the selected option) and `options`; the page's links only with `links: true`, hidden fields only with `hidden: true`; a password field's value is never given. Read-only: it sends the login and the logout and nothing else |
+
+### Trust and the password
+
+The admin page is HTTPS with a self-signed certificate. The module verifies no chain: it accepts the one certificate
+whose SHA-256 fingerprint is one of those in `printer-certificate` and refuses any other, in the handshake, so no
+password is sent to it; the error names the served and the pinned fingerprints. Give each as 32 upper-case hex pairs
+joined by colons, several separated by commas. The printer serves two self-signed certificates for one name, an
+ECDSA one and an RSA one, and which it serves depends on the signature algorithms the client offers, so pin both
+(issue 1503): read them with `openssl s_client -connect <printer>:443 -sigalgs ECDSA+SHA256` and `-sigalgs
+RSA-PSS+SHA256`, each piped to `openssl x509 -noout -fingerprint -sha256`.
+
+The admin password is the module's own secret `admin-password` (ADR 0467 clause 4; ADR 0283): the operator gives it
+at their desk, and the mesh never generates or rotates it. It is owned by the account `brother-device`, which the
+module makes, because the tools run as the operator account and must never read it (ADR 0436 §1, §12; the shape of
+mesh-mail's sender). The file is `${dir:state}/admin-password.secret`, mode 0600, and `BROTHER_ADMIN_PASSWORD` names
+it for the device process alone; the tools' bundle is given no such name, and `admin_boundary_test.go` checks that
+no tool file imports the package that reads it. While it is not given, `printer.settings` answers that the secret
+is not given, and the printer is not contacted.
+
+### Documents in parts
+
+The bus refuses a message over 1 MiB, so a document crosses it in parts of at most 700 KiB (both the size this module
+cuts and the most it accepts, as ADR 0468 clause 3 says),
+counted from 1, each carried base64-encoded in JSON. A caller joins the parts and checks the SHA-256. The bucket
+(`s3-bucket`, from `minio`) is spoken to by the device process alone, from `store.json` (owner `brother-device`, mode
+0600), with the S3 client mesh-mail uses; a scan is kept once as `<sha256>.pdf` and an upload as `uploads/<id>.<ext>`.
+
+### The device process
+
+`brother device` runs as `brother-device` with a bus account of its own (the own secret `broker-device`), never a
+seat, and does all the device and bucket work: the scan (and `scan.added`, emitted by it with the object's key and no
+path, since filing in the scan folder is the tool's), the documents, the printing, and the admin pages. It consumes the work-queue stream `device-asks` (event `device.asked`, body `id`, `page`, `asked-at`) and
+writes each answer, once, into the state `device-answers` under the ask's id (ten minutes' life): the page's
+title, links and form fields, or `error`. It alone reads the password, pins the certificate, logs in, reads the
+page and logs out. An ask older than two minutes is dropped without contacting the printer; at most three
+deliveries. It reads `settings.json` (mode 0644, no secret in it) and the state directory is 0711 so that it can
+reach its own files; both are the choices that let its account read what it needs. The device process is judged by its unit; `brother_health` (the printer's certificates against the pins) is the tool check of the `watch` process beside it.
+
+The login reads the form each time: the device generates the password field's name, so the code takes the name from
+the form, posts it with the form's hidden fields, and keeps the session cookie. A login is failed when the answer is
+the login page again. The logout follows a logout link or form on the page; a page with none is said in the answer
+(`logout`), and the session is left to expire on the device.
+
+## The event
+
+`scan.added`, said by the device process once the PDF is stored, before the file is written (the tool side files it afterwards, from the store, by a link the device signed; the verb's answer adds the file's `path`), on the wire `mesh.mod.brother.event.scan.added`; a consumer declares `brother.scan.added`. Its body:
+`object` (the key of the stored PDF), `node`, `bytes`, `sha256`, `width-mm`, `height-mm`, `resolution` (dpi, as the scanner gave it),
+`color-mode`, `cropped`, `pages` (1 for the glass), `scanned-at` (RFC 3339, UTC).
+
+## Files it does not know
+
+Each directory or archive this module declares says how it treats a file it did not write (ADR 0422, ADR 0416).
+
+- `${dir:state}`: everything in it is the program's; the mesh moves nothing out (ADR 0422 §2).
+- The scan folder (`scan-folder`) is declared by no manifest. The module writes only the `scan-*.pdf` files it
+  files and their `.scan-*.tmp` while they are written; it never changes, moves or removes any other file there,
+  and `scanner.list` only reads.
+
+## Tests
+
+The unit tests use the captured answers of a real scanner (`cmd/brother/testdata/escl`, captured 2026-10-20) served
+by a test HTTP server, the captured IPP exchange (`testdata/ipp`) replayed, and the captured login page
+(`testdata/admin/login-page.html`) served by a test TLS server with its own certificate. The pages behind the login
+are synthetic (`testdata/admin/synthetic-*.html`) until round 2 captures the real ones. No test reaches the real
+device.

modules/brother/cmd/brother/admin.go

@@ -0,0 +1,231 @@
+package main
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/cookiejar"
+	"net/url"
+	"strings"
+	"time"
+)
+
+// Admin is a session on the printer's admin web page, over HTTPS to the one certificate pinned (ADR 0467
+// clauses 3 and 4). The device names the password field itself, so every login reads the form first.
+type Admin struct {
+	Host     string
+	Password string
+	HTTP     *http.Client
+}
+
+// loginStart is where a login starts: the root, which the printer answers with a redirect to the page it serves
+// its login form on (/home/status.html). Asking for a page behind the login instead is answered by a redirect
+// to an error page, and a loginurl naming a page this firmware lacks is a 404 after the login (issue 1514).
+const loginStart = "/"
+
+// maxPage bounds a page of the admin site.
+const maxPage = 4 << 20
+
+// NewAdmin is a client for the printer's host that trusts the certificate with this fingerprint alone, with a
+// cookie jar for the session.
+func NewAdmin(host, fingerprint, password string) (*Admin, error) {
+	jar, err := cookiejar.New(nil)
+	if err != nil {
+		return nil, err
+	}
+	return &Admin{
+		Host:     host,
+		Password: password,
+		HTTP: &http.Client{
+			Timeout: 30 * time.Second,
+			Jar:     jar,
+			CheckRedirect: func(req *http.Request, via []*http.Request) error {
+				return checkRedirect(host, req, via)
+			},
+			Transport: &http.Transport{
+				TLSClientConfig:   pinnedTLS(fingerprint),
+				DisableKeepAlives: true,
+			},
+		},
+	}, nil
+}
+
+// checkRedirect follows a redirect only on https on the printer's own host, and never with a body: a 307 or 308
+// answer to the login post would make the client send the post again, the password with it (issue 1515).
+func checkRedirect(host string, req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return errors.New("the printer redirected more than ten times")
+	}
+	if req.URL.Scheme != "https" || req.URL.Host != host {
+		return fmt.Errorf("the printer redirected to %s, not to https on the printer %s: not followed", req.URL.Scheme+"://"+req.URL.Host, host)
+	}
+	if req.Method != http.MethodGet && req.Method != http.MethodHead {
+		return fmt.Errorf("the printer redirected a %s with its body (a 307 or 308): not followed, so the password is not sent again", via[len(via)-1].Method)
+	}
+	return nil
+}
+
+func (a *Admin) url(path string) string { return "https://" + a.Host + path }
+
+// fetch is one request; the body is read whole, up to maxPage. The final URL is the one after redirects.
+func (a *Admin) fetch(ctx context.Context, method, rawURL string, form url.Values) ([]byte, *url.URL, error) {
+	var req *http.Request
+	var err error
+	if form != nil {
+		req, err = http.NewRequestWithContext(ctx, method, rawURL, strings.NewReader(form.Encode()))
+		if err == nil {
+			req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+		}
+	} else {
+		req, err = http.NewRequestWithContext(ctx, method, rawURL, nil)
+	}
+	if err != nil {
+		return nil, nil, err
+	}
+	resp, err := a.HTTP.Do(req)
+	if err != nil {
+		return nil, nil, err
+	}
+	defer resp.Body.Close()
+	buf, err := io.ReadAll(io.LimitReader(resp.Body, maxPage+1))
+	if err != nil {
+		return nil, nil, fmt.Errorf("the page %s cannot be read: %w", rawURL, err)
+	}
+	if len(buf) > maxPage {
+		return nil, nil, fmt.Errorf("the page %s is larger than %d bytes", rawURL, maxPage)
+	}
+	if resp.StatusCode >= 400 {
+		if resp.StatusCode == http.StatusNotFound {
+			return nil, nil, &notFoundError{Path: resp.Request.URL.Path}
+		}
+		return nil, nil, fmt.Errorf("the printer answered %s for %s", resp.Status, resp.Request.URL.Path)
+	}
+	return buf, resp.Request.URL, nil
+}
+
+// passwordForm is the form of a page that holds a password field, or nil.
+func passwordForm(p Page) (*Form, *Field) {
+	for i := range p.Forms {
+		for j := range p.Forms[i].Fields {
+			if p.Forms[i].Fields[j].Type == "password" {
+				return &p.Forms[i], &p.Forms[i].Fields[j]
+			}
+		}
+	}
+	return nil, nil
+}
+
+func hasField(f *Form, name string) bool {
+	for _, fl := range f.Fields {
+		if fl.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
+// Login asks for the printer's login page, reads its login form, and posts the form's own fields with the
+// password in the field the form names and the form's loginurl set to the default page, which every firmware has; the page asked for is a request of its own afterwards. A login
+// is failed when the answer is a login page again.
+func (a *Admin) Login(ctx context.Context) error {
+	body, at, err := a.fetch(ctx, http.MethodGet, a.url(loginStart), nil)
+	if err != nil {
+		return fmt.Errorf("the printer's admin page cannot be asked for its login: %w", err)
+	}
+	form, pw := passwordForm(ParsePage(body))
+	if form == nil {
+		return fmt.Errorf("the printer's answer to %s holds no login form with a password field", at.Path)
+	}
+	target, err := at.Parse(form.Action)
+	if err != nil {
+		return fmt.Errorf("the login form's action %q is not a URL: %w", form.Action, err)
+	}
+	if target.Scheme != "https" || target.Host != a.Host {
+		return fmt.Errorf("the login form posts to %s, not to https on the printer %s: the password is not sent", target.Scheme+"://"+target.Host, a.Host)
+	}
+	vals := url.Values{}
+	for _, f := range form.Fields {
+		if f.Type == "hidden" {
+			vals.Set(f.Name, f.Value)
+		}
+	}
+	if _, ok := vals["loginurl"]; ok {
+		vals.Set("loginurl", DefaultPage)
+	}
+	vals.Set(pw.Name, a.Password)
+	answer, _, err := a.fetch(ctx, http.MethodPost, target.String(), vals)
+	if err != nil {
+		// The post may have opened a session before its answer failed: end it if there is one.
+		if home, hat, herr := a.Get(context.Background(), DefaultPage); herr == nil {
+			a.Logout(context.Background(), home, hat)
+		}
+		return fmt.Errorf("the login was not answered: %w", err)
+	}
+	// A login page again is a form with a password field and the loginurl field; a page that was asked for may
+	// hold a password field of its own.
+	if again, _ := passwordForm(ParsePage(answer)); again != nil && hasField(again, "loginurl") {
+		return fmt.Errorf("the login failed: the printer showed its login page again, so the secret admin-password is not its password")
+	}
+	return nil
+}
+
+// Get is a page of the admin site, after a login.
+func (a *Admin) Get(ctx context.Context, path string) ([]byte, *url.URL, error) {
+	return a.fetch(ctx, http.MethodGet, a.url(path), nil)
+}
+
+// Logout ends the session through the logout link or form of a page of it, and says what it did. A page with
+// none leaves the session to expire, and the answer says so.
+func (a *Admin) Logout(ctx context.Context, page []byte, at *url.URL) string {
+	p := ParsePage(page)
+	isLogout := func(s string) bool {
+		s = strings.ToLower(strings.ReplaceAll(s, " ", ""))
+		return strings.Contains(s, "logout") || strings.Contains(s, "logoff")
+	}
+	for _, f := range p.Forms {
+		if !isLogout(f.Action) {
+			continue
+		}
+		target, err := at.Parse(f.Action)
+		if err != nil || target.Host != a.Host {
+			continue
+		}
+		vals := url.Values{}
+		for _, fl := range f.Fields {
+			if fl.Type == "hidden" {
+				vals.Set(fl.Name, fl.Value)
+			}
+		}
+		method := http.MethodPost
+		var send url.Values = vals
+		if f.Method == "get" {
+			method, send = http.MethodGet, nil
+			target.RawQuery = vals.Encode()
+		}
+		if _, _, err := a.fetch(ctx, method, target.String(), send); err != nil {
+			return "logout failed: " + err.Error()
+		}
+		return "logged out"
+	}
+	for _, l := range p.Links {
+		if !isLogout(l.Href) && !isLogout(l.Text) {
+			continue
+		}
+		target, err := at.Parse(l.Href)
+		if err != nil || target.Host != a.Host {
+			continue
+		}
+		if _, _, err := a.fetch(ctx, http.MethodGet, target.String(), nil); err != nil {
+			return "logout failed: " + err.Error()
+		}
+		return "logged out"
+	}
+	return "no logout link or form on the page: the session is left to expire on the printer"
+}
+
+// notFoundError is the printer's 404 for a page.
+type notFoundError struct{ Path string }
+
+func (e *notFoundError) Error() string { return "the printer answered 404 Not Found for " + e.Path }

modules/brother/cmd/brother/admin_test.go

@@ -0,0 +1,351 @@
+package main
+
+import (
+	"context"
+	"crypto/tls"
+	"net"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// fakePrinter is a TLS server standing in for the printer's admin page. Its login page is the captured one
+// (testdata/admin/login-page.html, 2026-10-20) with the password field's name changed to the one the test
+// chooses, as the real device generates it. The pages behind the login are SYNTHETIC (testdata/admin/
+// synthetic-*.html): the real ones arrive in round 2 of issue 1453.
+type fakePrinter struct {
+	*httptest.Server
+	field    string // the password field's name the login form gives
+	password string
+	mu       sync.Mutex
+	conns    int               // connections opened to it
+	requests []string          // method and path of every request
+	posted   []url.Values      // every form body posted
+	session  string            // the cookie value of the one logged-in session
+	loggedIn map[string]bool   // cookie values that are logged in
+	pages    map[string]string // path -> body behind the login
+}
+
+func adminFixture(t *testing.T, name string) string {
+	t.Helper()
+	b, err := os.ReadFile(filepath.Join("testdata", "admin", name))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return string(b)
+}
+
+func newFakePrinter(t *testing.T, field, password string) *fakePrinter {
+	t.Helper()
+	f := &fakePrinter{field: field, password: password, loggedIn: map[string]bool{}, pages: map[string]string{}}
+	login := strings.ReplaceAll(adminFixture(t, "login-page.html"), "B1891", field)
+	// The login page the printer serves at /home/status.html carries that page as its loginurl (captured live
+	// 2026-10-20, testdata/admin/live/home_status_html.body); the page it serves at /etc/loginerror.html carries
+	// the page that was asked for.
+	homeLogin := strings.ReplaceAll(login, `value="/general/status.html"`, `value="/home/status.html"`)
+	synthetic := adminFixture(t, "synthetic-status.html")
+	// This firmware has no /general/status.html behind the login (issue 1514): asking for it is a 404.
+	f.pages["/home/status.html"] = synthetic
+	f.pages["/general/other.html"] = adminFixture(t, "synthetic-settings.html")
+	authed := func(r *http.Request) bool {
+		c, err := r.Cookie("session")
+		return err == nil && f.loggedIn[c.Value]
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/etc/loginerror.html", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		w.Write([]byte(login))
+	})
+	mux.HandleFunc("/home/status.html", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.Method != http.MethodPost {
+			if authed(r) {
+				w.Write([]byte(synthetic))
+				return
+			}
+			w.Write([]byte(homeLogin))
+			return
+		}
+		r.ParseForm()
+		f.posted = append(f.posted, r.PostForm)
+		if r.PostForm.Get(field) != password || r.PostForm.Get("loginurl") == "" {
+			w.Write([]byte(login))
+			return
+		}
+		f.session = "s" + field
+		f.loggedIn[f.session] = true
+		http.SetCookie(w, &http.Cookie{Name: "session", Value: f.session, Path: "/"})
+		// Like Brother's form, a good login goes on to the page named in loginurl.
+		http.Redirect(w, r, r.PostForm.Get("loginurl"), http.StatusFound)
+	})
+	mux.HandleFunc("/home/logout.html", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if c, err := r.Cookie("session"); err == nil {
+			delete(f.loggedIn, c.Value)
+		}
+		w.Write([]byte(login))
+	})
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		f.mu.Lock()
+		defer f.mu.Unlock()
+		if r.URL.Path == "/" {
+			http.Redirect(w, r, "/home/status.html", http.StatusMovedPermanently)
+			return
+		}
+		f.requests = append(f.requests, r.Method+" "+r.URL.Path)
+		// Captured: a page behind the login is answered by a redirect to the login page whether it exists or not.
+		if !authed(r) {
+			http.Redirect(w, r, "/etc/loginerror.html?url="+url.QueryEscape(r.URL.Path), http.StatusFound)
+			return
+		}
+		body, ok := f.pages[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		w.Write([]byte(body))
+	})
+	f.Server = httptest.NewUnstartedServer(mux)
+	f.Config.ConnState = func(_ net.Conn, st http.ConnState) {
+		if st == http.StateNew {
+			f.mu.Lock()
+			f.conns++
+			f.mu.Unlock()
+		}
+	}
+	f.StartTLS()
+	t.Cleanup(f.Close)
+	return f
+}
+
+func (f *fakePrinter) host() string { return strings.TrimPrefix(f.URL, "https://") }
+
+// print is the fingerprint of the certificate the server serves.
+func (f *fakePrinter) print() string { return Fingerprint(f.TLS.Certificates[0].Certificate[0]) }
+
+func (f *fakePrinter) connsNow() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.conns
+}
+
+func (f *fakePrinter) loggedInNow() int {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return len(f.loggedIn)
+}
+
+// 1453/AC2: a certificate whose fingerprint is not the pinned one is refused, the error names both
+// fingerprints, and the server saw no request at all, so no password was sent.
+func TestACertificateOtherThanThePinnedOneIsRefusedBeforeAnythingIsSent(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	other := strings.Repeat("AA:", 31) + "AA"
+	a, err := NewAdmin(f.host(), other, "hunter2")
+	if err != nil {
+		t.Fatal(err)
+	}
+	err = a.Login(context.Background())
+	if err == nil {
+		t.Fatal("a certificate that is not the pinned one was accepted")
+	}
+	for _, want := range []string{f.print(), other} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("error %q does not name the fingerprint %s", err, want)
+		}
+	}
+	if len(f.requests) != 0 || len(f.posted) != 0 {
+		t.Errorf("the server was sent %v and the forms %v: the password may have gone", f.requests, f.posted)
+	}
+}
+
+// 1453/AC2: the pinned certificate itself is accepted, in either case of hex digits.
+func TestThePinnedCertificateIsAccepted(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "hunter2")
+	a, _ := NewAdmin(f.host(), strings.ToLower(f.print()), "hunter2")
+	if err := a.Login(context.Background()); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// 1453/AC3: the login posts the password in the field the form names, whatever the name is (the test changes
+// it), along with the form's hidden fields, and the session cookie it gets is the one later pages are asked with.
+func TestLoginUsesThePasswordFieldNameTheFormGives(t *testing.T) {
+	for _, name := range []string{"B1891", "Zq77x"} {
+		f := newFakePrinter(t, name, "s3cret pass")
+		a, _ := NewAdmin(f.host(), f.print(), "s3cret pass")
+		ctx := context.Background()
+		if err := a.Login(ctx); err != nil {
+			t.Fatalf("field %s: %v", name, err)
+		}
+		if len(f.posted) != 1 {
+			t.Fatalf("field %s: %d forms posted", name, len(f.posted))
+		}
+		if got := f.posted[0].Get(name); got != "s3cret pass" {
+			t.Errorf("field %s: the password field holds %q", name, got)
+		}
+		if f.posted[0].Get("loginurl") != DefaultPage {
+			t.Errorf("field %s: the form's hidden loginurl was %q", name, f.posted[0].Get("loginurl"))
+		}
+		if len(f.posted[0]) != 2 {
+			t.Errorf("field %s: posted %v, want the password and loginurl only", name, f.posted[0])
+		}
+		body, _, err := a.Get(ctx, "/general/other.html")
+		if err != nil || !strings.Contains(string(body), "Synthetic settings") {
+			t.Errorf("field %s: a page behind the login was not given with the session cookie: %v %.60s", name, err, body)
+		}
+	}
+}
+
+// 1453/AC4: a wrong password is a failed login, said so: the login page comes back.
+func TestAWrongPasswordIsAFailedLogin(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "right")
+	a, _ := NewAdmin(f.host(), f.print(), "wrong")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "login failed") {
+		t.Fatalf("error = %v, want a failed login", err)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("a session was opened")
+	}
+}
+
+// 1453: the logout link on a page ends the session; a page with none says so.
+func TestLogoutEndsTheSessionAndAPageWithoutOneSaysSo(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	a, _ := NewAdmin(f.host(), f.print(), "pw")
+	ctx := context.Background()
+	if err := a.Login(ctx); err != nil {
+		t.Fatal(err)
+	}
+	body, at, err := a.Get(ctx, DefaultPage)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := a.Logout(ctx, body, at); got != "logged out" {
+		t.Errorf("logout = %q", got)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("the session is still open")
+	}
+	if got := a.Logout(ctx, []byte("<html><body>nothing</body></html>"), at); !strings.Contains(got, "no logout") {
+		t.Errorf("logout without a link = %q", got)
+	}
+}
+
+// 1453: the module never sends the password to a host other than the printer, even if the form says so.
+func TestThePasswordIsNotPostedToAnotherHost(t *testing.T) {
+	// A login form whose action names another host.
+	srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`<form method="post" action="https://elsewhere.example/x"><input type="password" name="p"/></form>`))
+	}))
+	srv.TLS = &tls.Config{}
+	srv.StartTLS()
+	defer srv.Close()
+	host := strings.TrimPrefix(srv.URL, "https://")
+	a, _ := NewAdmin(host, Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "pw")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "not sent") {
+		t.Fatalf("error = %v", err)
+	}
+}
+
+// 1514 review: a page the printer does not have leaves no session open, and the error says the page is missing,
+// not that the login failed.
+func TestAMissingPageLeavesNoSessionOpenAndSaysSo(t *testing.T) {
+	f := newFakePrinter(t, "B1891", "pw")
+	_, run := printerTools(t, f, "pw")
+	_, err := run(map[string]any{"page": "/general/nope.html"})
+	if err == nil || !strings.Contains(err.Error(), "the printer has no page /general/nope.html") {
+		t.Fatalf("error = %v, want the printer has no page", err)
+	}
+	if strings.Contains(err.Error(), "login was not answered") {
+		t.Errorf("a missing page is said to be a failed login: %v", err)
+	}
+	if f.loggedInNow() != 0 {
+		t.Errorf("%d sessions are still open on the printer", f.loggedInNow())
+	}
+}
+
+// 1514 review: the password is posted to https on the printer's host only. A form whose action is plain http
+// on the same host, or a root that redirects to plain http, is refused and nothing is posted.
+func TestThePasswordIsNotPostedOverPlainHTTP(t *testing.T) {
+	var posted int
+	mux := http.NewServeMux()
+	page := func(action string) string {
+		return `<html><body><form method="post" action="` + action + `"><input type="password" name="B1891"/><input type="hidden" name="loginurl" value="/home/status.html"/></form></body></html>`
+	}
+	var host string
+	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPost {
+			posted++
+		}
+		w.Write([]byte(page("http://" + host + "/home/status.html")))
+	})
+	srv := httptest.NewTLSServer(mux)
+	defer srv.Close()
+	host = strings.TrimPrefix(srv.URL, "https://")
+	a, _ := NewAdmin(host, Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "pw")
+	err := a.Login(context.Background())
+	if err == nil || !strings.Contains(err.Error(), "password is not sent") {
+		t.Errorf("error = %v, want the plain http action refused", err)
+	}
+	if posted != 0 {
+		t.Errorf("%d posts reached the server", posted)
+	}
+}
+
+// 1515: a 307 or 308 after the login post would make the HTTP client send the post again, the password with
+// it, to the place the answer names; a redirect off https or off the printer's host is refused as well.
+func TestNoRedirectResendsThePasswordOrLeavesHTTPSOnThePrinter(t *testing.T) {
+	const loginPage = `<html><body><form action="/login" method="post"><input type="password" name="pw"><input type="hidden" name="loginurl" value="/x"></form></body></html>`
+	cases := []struct {
+		name     string
+		status   int
+		location string // "SAME" is a path on the printer itself
+	}{
+		{"307 on the printer", 307, "/again"},
+		{"308 on the printer", 308, "/again"},
+		{"307 to plain http", 307, "http://192.0.2.1/steal"},
+		{"302 to another host", 302, "https://192.0.2.1/steal"},
+		{"302 to plain http", 302, "http://192.0.2.1/steal"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			var mu sync.Mutex
+			var posts []string
+			srv := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				mu.Lock()
+				defer mu.Unlock()
+				switch {
+				case r.Method == http.MethodGet && r.URL.Path == "/":
+					w.Write([]byte(loginPage))
+				case r.Method == http.MethodPost:
+					r.ParseForm()
+					posts = append(posts, r.URL.Path+" "+r.PostForm.Get("pw"))
+					http.Redirect(w, r, c.location, c.status)
+				default:
+					w.Write([]byte("ok"))
+				}
+			}))
+			srv.StartTLS()
+			defer srv.Close()
+			a, _ := NewAdmin(strings.TrimPrefix(srv.URL, "https://"), Fingerprint(srv.TLS.Certificates[0].Certificate[0]), "hunter2")
+			err := a.Login(context.Background())
+			if err == nil {
+				t.Fatalf("the login went on after a %d to %s", c.status, c.location)
+			}
+			mu.Lock()
+			defer mu.Unlock()
+			if len(posts) != 1 {
+				t.Errorf("the password was posted %d times: %v", len(posts), posts)
+			}
+		})
+	}
+}