Name the issue that holds the refusal back (hq issue 574)

betterbird declares a preference and owns a mergeable file that names no
keys, and the catalogue can only name them once this controller runs: the
refusal made the catalogue check fail against catalogue main. It follows
once mesh-catalog names the keys.

.gitignore

@@ -6,3 +6,5 @@
 /mesh-controller
 /postgres-provisioner
 /redis-provisioner
+# And where `go build` in cmd/mesh-controller leaves it (novox/hq issue 233).
+/cmd/mesh-controller/mesh-controller

cmd/mesh-controller/apply_failing.go

@@ -0,0 +1,118 @@
+package main
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// kindApplyFailing is S21's kind: a machine whose declarations have been refused, or applied only in part,
+// for longer than one apply interval (novox/hq issue 233).
+const kindApplyFailing = "apply-failing"
+
+// applyEvery is how often a node-engine applies what it was last told when nothing new arrives: its
+// ReconcileEvery. A failure still there after one more of them is not one the next apply clears.
+const applyEvery = 5 * time.Minute
+
+// packageManagerKey is how a node-engine names a package manager that does not answer among what failed
+// (mesh-host's probe.go): "the package manager (pacman)".
+const packageManagerKey = "the package manager ("
+
+// watchApplyFailing is S21: **a machine that does not apply what it was sent is said by the mesh, not only
+// to someone who asks for `status`** (novox/hq issue 233, issue 187's family). A workstation refused every
+// declaration for an hour and a half because its package manager did not answer, and the mesh's only word
+// on it was a line in `status`. Raised once the machine's first report of this failure is older than one apply
+// interval **while the machine is heard** — judged by time, not by how many reports said it: a node-engine
+// says a re-apply only when how it went changed, so the same failure is one report however long it lasts.
+// Names the refusal's or the failure's words; cleared by the clean apply the node-engine then says. Not while
+// the machine is silent, asleep or not known: S1 says silent, and asleep is not lost.
+func watchApplyFailing(f *signalFacts) []conditions.Observation {
+	heard := map[string]bool{}
+	for _, m := range f.machines {
+		if !m.asleep() && !m.lastHeard.IsZero() && f.now.Sub(m.lastHeard) <= heartbeatBound(m.every) {
+			heard[m.name] = true
+		}
+	}
+	var out []conditions.Observation
+	for _, d := range f.doing {
+		if !d.Wrong() || d.Since == nil || f.now.Sub(*d.Since) <= applyEvery || !heard[d.Node] {
+			continue
+		}
+		out = append(out, applyFailing(d, f.now))
+	}
+	return out
+}
+
+// applyFailing is one machine's S21 condition.
+func applyFailing(d inventory.Doing, now time.Time) conditions.Observation {
+	m := d.Node
+	since := d.Since.UTC().Format("2006-01-02 15:04 MST")
+	o := conditions.Observation{Scope: conditions.ScopeMachine, ID: m, Kind: kindApplyFailing, Machine: m,
+		Severity: conditions.Warning, Said: doingWords(d),
+		Resolved: m + " applies what it is sent again"}
+	how := "refused its declaration whole"
+	if d.Outcome != inventory.OutcomeRefused {
+		how = "applied its declaration only in part"
+	}
+	o.Summary = fmt.Sprintf("%s has %s since %s (bound %s): %s", m, how, since, ago(applyEvery), failedNames(d))
+	o.Headline = m + " is not applying its update"
+	o.Explanation = fmt.Sprintf("%s has %s for %s, and trying again has not helped. The details say what fails.",
+		m, plainHow(d), humanDuration(now.Sub(*d.Since)))
+	if tool := unansweringTool(d); tool != "" {
+		o.Summary = fmt.Sprintf("%s: %s does not answer, so no package reaches it; everything else it was sent "+
+			"is applied, since %s (bound %s)", m, tool, since, ago(applyEvery))
+		o.Headline = fmt.Sprintf("%s cannot install packages", m)
+		o.Explanation = fmt.Sprintf("The package manager on %s (%s) has not answered for %s, so no package reaches "+
+			"it. Everything else is still applied, so an update that repairs it can land; if none does, it needs a "+
+			"look on the machine.", m, tool, humanDuration(now.Sub(*d.Since)))
+	}
+	return o
+}
+
+// plainHow is how a machine failed, as the operator reads it.
+func plainHow(d inventory.Doing) string {
+	if d.Outcome == inventory.OutcomeRefused {
+		return "refused every update"
+	}
+	return "applied its updates only in part"
+}
+
+// unansweringTool is the package manager a machine said does not answer, or "".
+func unansweringTool(d inventory.Doing) string {
+	for _, r := range d.Failed {
+		if rest, ok := strings.CutPrefix(r.ID, packageManagerKey); ok {
+			return strings.TrimSuffix(rest, ")")
+		}
+	}
+	return ""
+}
+
+// failedNames is what failed, by name: the refusal, or the failed resources' ids.
+func failedNames(d inventory.Doing) string {
+	if d.Outcome == inventory.OutcomeRefused {
+		return "refused"
+	}
+	ids := make([]string, 0, len(d.Failed))
+	for _, r := range d.Failed {
+		ids = append(ids, r.ID)
+	}
+	sort.Strings(ids)
+	return "failed " + strings.Join(ids, ", ")
+}
+
+// doingWords is the machine's own words on what failed: the evidence, kept inside the mesh.
+func doingWords(d inventory.Doing) string {
+	if d.Outcome == inventory.OutcomeRefused {
+		return "refused: " + oneLine(d.Refused)
+	}
+	var parts []string
+	for _, r := range d.Failed {
+		parts = append(parts, r.ID+": "+oneLine(r.Error))
+	}
+	sort.Strings(parts)
+	return strings.Join(parts, "; ")
+}

cmd/mesh-controller/apply_failing_test.go

@@ -0,0 +1,123 @@
+package main
+
+import (
+	"context"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/novox/mesh-controller/internal/conditions"
+	"github.com/novox/mesh-controller/internal/inventory"
+)
+
+// unansweringPackageManager is anchor's last report as the workstation's read on 2026-10-04, once its
+// node-engine applies the rest (novox/hq issue 233): the package failed and the package manager did not answer,
+// the same failure on times reports since for before now.
+func unansweringPackageManager(now time.Time, forHowLong time.Duration, times int) inventory.Doing {
+	since := now.Add(-forHowLong)
+	return inventory.Doing{Node: "anchor", Outcome: inventory.OutcomeFailed, At: now.Add(-time.Second),
+		Since: &since, Times: times, Applied: 41, Failed: []inventory.FailedResource{
+			{ID: "apply", Error: `applying "pacman.base": nothing can be said about "base": this is the arch host and ` +
+				"pacman does not answer here. Either this machine is not Arch, or its package database is broken: " +
+				"pacman exited 1: error: config file /etc/pacman.conf could not be read: No such file or directory"},
+			{ID: "the package manager (pacman)", Error: "pacman does not answer here, so every package in this " +
+				"declaration fails and the rest of it is applied (novox/hq issue 233): pacman exited 1: error: config " +
+				"file /etc/pacman.conf could not be read: No such file or directory"}}}
+}
+
+// **A machine whose package manager does not answer is raised by the mesh itself, naming the tool and the
+// probe's words** (novox/hq issue 233): the words in the evidence, the path kept out of the summary.
+func TestAPackageManagerThatDoesNotAnswerIsRaisedNamingItsWords(t *testing.T) {
+	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
+	f := calm(now)
+	f.doing = []inventory.Doing{unansweringPackageManager(now, 90*time.Minute, 18)}
+	got := watchApplyFailing(f)
+	if len(got) != 1 {
+		t.Fatalf("raised %d conditions, want one: %+v", len(got), got)
+	}
+	o := got[0]
+	if o.Key() != "machine.anchor.apply-failing" || o.Machine != "anchor" {
+		t.Errorf("the condition is not the machine's: %s", o.Key())
+	}
+	if !strings.Contains(o.Summary, "pacman does not answer") || !strings.Contains(o.Summary, "since 2026-10-04 12:30") {
+		t.Errorf("the summary does not name the tool and since when: %s", o.Summary)
+	}
+	if strings.Contains(o.Summary, "/etc/") {
+		t.Errorf("the summary carries a path, which belongs in the evidence: %s", o.Summary)
+	}
+	if !strings.Contains(o.Said, "could not be read") {
+		t.Errorf("the evidence does not carry the probe's words: %s", o.Said)
+	}
+	if !strings.Contains(o.Headline, "cannot install packages") || o.Explanation == "" || o.Resolved == "" {
+		t.Errorf("the plain words do not say it: %+v", o)
+	}
+}
+
+// **A whole refusal is raised too**, with the node-engine's words: what the workstation's report said before the
+// node-engine applied the rest.
+func TestARefusalThatGoesOnIsRaised(t *testing.T) {
+	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
+	since := now.Add(-time.Hour)
+	f := calm(now)
+	f.doing = []inventory.Doing{{Node: "anchor", Outcome: inventory.OutcomeRefused, Since: &since, Times: 12,
+		Refused: "this is the arch host and pacman does not answer here", At: now.Add(-time.Minute)}}
+	got := watchApplyFailing(f)
+	if len(got) != 1 || !strings.Contains(got[0].Summary, "refused its declaration whole") ||
+		!strings.Contains(got[0].Said, "pacman does not answer") {
+		t.Fatalf("a refusal that went on for an hour was not raised with its words: %+v", got)
+	}
+}
+
+// **Judged by time while the machine is heard, not by how many reports said it** (review of novox/hq issue 233):
+// a node-engine says the same failure once, so one report an apply interval old is a fault that goes on; one
+// younger is not yet; and a silent or sleeping machine is S1's.
+func TestOneReportOlderThanAnApplyIsRaisedAndAQuietMachineIsNot(t *testing.T) {
+	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
+	f := calm(now)
+	f.doing = []inventory.Doing{unansweringPackageManager(now, 6*time.Minute, 1)}
+	if got := watchApplyFailing(f); len(got) != 1 {
+		t.Errorf("one report of a failure six minutes old was not raised: %+v", got)
+	}
+	f.doing = []inventory.Doing{unansweringPackageManager(now, 4*time.Minute, 1)}
+	if got := watchApplyFailing(f); len(got) != 0 {
+		t.Errorf("a failure four minutes old was raised before one apply could clear it: %+v", got)
+	}
+	f.doing = []inventory.Doing{unansweringPackageManager(now, time.Hour, 1)}
+	f.machines[0].lastHeard = now.Add(-time.Hour)
+	if got := watchApplyFailing(f); len(got) != 0 {
+		t.Errorf("a silent machine was raised for its last report: %+v", got)
+	}
+	f = calm(now)
+	f.doing = []inventory.Doing{unansweringPackageManager(now, time.Hour, 1)}
+	f.doing[0].Node = "a-machine-the-mesh-does-not-know"
+	if got := watchApplyFailing(f); len(got) != 0 {
+		t.Errorf("a machine not heard of was raised: %+v", got)
+	}
+}
+
+// **A failed re-apply followed by a clean one clears S21** (review of novox/hq issue 233): the node-engine says
+// the clean re-apply, the store keeps it as applied with no failure since, and the condition the failure raised
+// is cleared through the keeper on the next tick.
+func TestACleanReapplyAfterAFailedOneClearsTheCondition(t *testing.T) {
+	now := time.Date(2026, 10, 4, 14, 0, 0, 0, time.UTC)
+	store := conditions.NewInMemory()
+	k := conditions.NewKeeper(t.Context(), conditions.Options{Store: store, History: store,
+		Teller: &conditions.Told{}, Now: func() time.Time { return now }})
+	defer k.Close(context.Background())
+	w := &watchdogs{keeper: k, started: now.Add(-time.Hour)}
+
+	failing := calm(now)
+	failing.doing = []inventory.Doing{unansweringPackageManager(now, 20*time.Minute, 1)}
+	w.see(t.Context(), failing)
+	open, err := k.Open(t.Context())
+	if err != nil || len(open) != 1 || open[0].Kind != kindApplyFailing {
+		t.Fatalf("the failed re-apply raised %+v (%v), want apply-failing", open, err)
+	}
+
+	clean := calm(now.Add(5 * time.Minute))
+	clean.doing = nil // the clean re-apply recorded: NotDoingWhatTheyWereTold no longer lists the machine
+	w.see(t.Context(), clean)
+	if open, _ := k.Open(t.Context()); len(open) != 0 {
+		t.Fatalf("the condition stayed open after the clean re-apply: %+v", open)
+	}
+}

cmd/mesh-controller/batches.go

@@ -1109,16 +1109,6 @@ const resolverSeat = "mesh-dns-resolver"
 // classOf is a walk's class (novox/hq ADR 0282 decision 1): core when it walks a module on the controller's own
 // path or one holding the mesh's resolver, leaf otherwise.
 func classOf(walk inventory.Plan, entries []inventory.Entry) string {
-	modules := make([]string, 0, len(walk.Modules))
-	for m := range walk.Modules {
-		modules = append(modules, m)
-	}
-	return classOfModules(modules, entries)
-}
-
-// classOfModules is the class of modules moved together: core when one is on the controller's own path or holds
-// the mesh's resolver, leaf otherwise (ADR 0282 decision 1).
-func classOfModules(modules []string, entries []inventory.Entry) string {
 	resolvers := map[string]bool{}
 	for _, e := range entries {
 		for _, c := range e.Manifest.Claims {
@@ -1127,7 +1117,7 @@ func classOfModules(modules []string, entries []inventory.Entry) string {
 			}
 		}
 	}
-	for _, m := range modules {
+	for m := range walk.Modules {
 		if _, own := onTheControllersPath[m]; own || resolvers[m] {
 			return inventory.ClassCore
 		}

cmd/mesh-controller/changeplan.go

@@ -2,7 +2,6 @@ package main
 
 import (
 	"fmt"
-	"path"
 	"slices"
 	"sort"
 	"strings"
@@ -106,32 +105,9 @@ func changePlanOf(repository, base, head string, r mergeReach, entries []invento
 		p.Machines = append(p.Machines, *machines[name])
 	}
 	p.Summary = summaryOf(p)
-	p.Class = changeClassOf(p, entries)
 	return p
 }
 
-// classNone is the class of a change that moves no module: nothing for a walk to move (novox/hq ADR 0313 §2).
-const classNone = "none"
-
-// changeClassOf is a change plan's class (novox/hq ADR 0313 §2): that of the slowest-budgeted module it moves,
-// itself or as a dependent — core when one is on the controller's own path or holds the mesh's resolver, leaf
-// otherwise — and none when it moves nothing. A module it adds a directory for counts by its own class: the
-// catalogue names a module's directory by the module, so the directory's last element is its name. The graph holds
-// no manifest of it yet, so a new module is core by its name alone (on the controller's own path), never by a
-// resolver claim its manifest makes.
-func changeClassOf(p link.ChangePlan, entries []inventory.Entry) string {
-	if len(p.Moved) == 0 && len(p.Dependents) == 0 && len(p.New) == 0 {
-		return classNone
-	}
-	modules := append(append([]string{}, p.Moved...), p.Dependents...)
-	for _, dir := range p.New {
-		if name := path.Base(strings.Trim(dir, "/")); name != "." && name != "/" && name != "" {
-			modules = append(modules, name)
-		}
-	}
-	return classOfModules(modules, entries)
-}
-
 // grantsStepWord names the grants step (novox/hq issue 490): the bus's user list sent alone to the machine
 // holding the bus ahead of a walk's gate. Not the bus step, which replaces the bus itself.
 const grantsStepWord = "grants step"

cmd/mesh-controller/fixclass_test.go

@@ -1,54 +0,0 @@
-package main
-
-import (
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/inventory"
-	"github.com/novox/mesh-controller/internal/link"
-)
-
-// **A change plan says its class** (novox/hq ADR 0313 §2): the issue tracker holds a fix to the budget of the
-// slowest-budgeted module the fix moves, and a fix that moves no module has no fix budget. The plan says core,
-// leaf or none, so mesh-delivery can pass it on with the fix's delivery.
-func TestAChangePlanSaysTheClassOfWhatItMoves(t *testing.T) {
-	const repo = "http://forge.internal:20000/novox/mesh-catalog.git"
-	entry := func(name, path string) inventory.Entry {
-		e := fromRepo(name, repo, path)
-		e.Source.BuiltFrom = "old"
-		e.On = []string{"anchor"}
-		return e
-	}
-	gitea := entry("gitea", "modules/gitea")
-	resolver := entry("dnsmasq", "modules/dnsmasq")
-	resolver.Manifest.Claims = []catalogue.Claim{{Name: resolverSeat}}
-	delivery := entry(catalogue.DeliverySeat, "modules/mesh-delivery")
-	webApp := entry("photos", "modules/photos")
-	entries := []inventory.Entry{gitea, resolver, delivery, webApp}
-	// photos stands on gitea: a change to gitea moves photos as its dependent.
-	edges := []inventory.Edge{{From: "photos", To: "gitea", Kind: inventory.EdgeStandsOn}}
-	policy := func(string) (inventory.Upgrade, bool) { return inventory.Upgrade{RollOut: true}, true }
-	plan := func(paths ...string) link.ChangePlan {
-		m := link.SourceMoved{Owner: "novox", Repo: "mesh-catalog", Base: "main", Commit: "head", Paths: paths}
-		return changePlanOf("novox/mesh-catalog", "main", "head", reachOfMerge(m, entries, nil, edges), entries, policy)
-	}
-
-	for _, c := range []struct {
-		why   string
-		paths []string
-		want  string
-	}{
-		{"a leaf module and its dependent", []string{"modules/gitea/index.ts"}, inventory.ClassLeaf},
-		{"the delivery's owner, on the controller's own path", []string{"modules/mesh-delivery/cmd/x.go"}, inventory.ClassCore},
-		{"the mesh's resolver", []string{"modules/dnsmasq/module.json"}, inventory.ClassCore},
-		{"a leaf and a core module together: the slowest-budgeted", []string{"modules/gitea/index.ts", "modules/dnsmasq/module.json"}, inventory.ClassCore},
-		{"nothing any module's build reads", []string{"README.md"}, "none"},
-		{"a new leaf module alone", []string{"modules/weather/module.json"}, inventory.ClassLeaf},
-		{"a new module on the controller's own path, by its own class", []string{"next/mesh-delivery/module.json"}, inventory.ClassCore},
-		{"a new leaf module beside a core one moved", []string{"modules/weather/module.json", "modules/dnsmasq/module.json"}, inventory.ClassCore},
-	} {
-		if got := plan(c.paths...).Class; got != c.want {
-			t.Errorf("%s: class %q, want %q", c.why, got, c.want)
-		}
-	}
-}

cmd/mesh-controller/plain_words.go

@@ -81,6 +81,13 @@ var plainWordings = map[string]func(conditions.Observation) words{
 				"It usually catches up by itself.", m, m),
 			Resolved: m + " applied the change"}
 	}),
+	kindApplyFailing: worded(func(o conditions.Observation) words {
+		m := machineOr(o, "a machine")
+		return words{Headline: m + " is not applying its update",
+			Explanation: fmt.Sprintf("%s has refused or only partly applied what the mesh sent it, again and again. "+
+				"The details say what fails.", conditions.Capital(m)),
+			Resolved: m + " applies what it is sent again"}
+	}),
 	"tools-silent": worded(func(o conditions.Observation) words {
 		m := machineOr(o, "a machine")
 		return words{Headline: "Tools on " + m + " are not answering",

cmd/mesh-controller/signals.go

@@ -254,6 +254,16 @@ var signalsTable = []signalRow{
 		newest: func(f *signalFacts) time.Time {
 			return newestOf(f.bus.waits, func(w busWaitFacts) time.Time { return w.since })
 		}},
+	{Row: "S21", Signal: "a clean apply", Emitter: "node-engine", Trigger: "each report of a declaration refused or applied only in part (novox/hq issue 233)",
+		Bound: "one apply interval (5 min) past the first report of the same failure, judged by time while the machine " +
+			"is heard — the node-engine says a re-apply only when how it went changed; not while it is silent or " +
+			"asleep; naming the refusal, or the package manager that does not answer with its words; cleared by the " +
+			"clean apply it then says",
+		Kind: kindApplyFailing, Severity: conditions.Warning, Phase: 2,
+		needs: func(f *signalFacts) error { return f.doingErr }, watch: watchApplyFailing,
+		newest: func(f *signalFacts) time.Time {
+			return newestOf(f.doing, func(d inventory.Doing) time.Time { return d.At })
+		}},
 }
 
 // watchFacts is S14: the snapshot a merge check is fed is older than its bound, or none was kept since

cmd/mesh-controller/signals_test.go

@@ -186,6 +186,14 @@ var suppressions = map[string]suppression{
 		},
 		past: func(f *signalFacts) { f.refusedSends = []inventory.Send{refusedSend(f.now.Add(-time.Second))} },
 	},
+	// A machine whose package manager does not answer (novox/hq issue 233): said once its first report of the
+	// failure is older than one apply interval while it is heard. Inside: exactly five minutes old.
+	"S21": {
+		inside: func(f *signalFacts) { f.doing = []inventory.Doing{unansweringPackageManager(f.now, 5*time.Minute, 1)} },
+		past: func(f *signalFacts) {
+			f.doing = []inventory.Doing{unansweringPackageManager(f.now, 5*time.Minute+time.Second, 1)}
+		},
+	},
 	// Twice by hand within a fortnight is a healer wanted; once, or the first of two a day too old, is not.
 	"S15": {
 		inside: func(f *signalFacts) {

cmd/mesh-controller/terminal_settings_test.go

@@ -344,3 +344,58 @@ func TestAnyKeyOfAModuleWithATrustedMergeableFileIsRefusedThroughAVerb(t *testin
 		t.Fatalf("a file marked untrusted through the verb: %v", err)
 	}
 }
+
+// Who owns a module's directory is said at the terminal alone (novox/hq issue 279): a directory's owner may name
+// the settings the module runs as, root chowns the folder to them at the next push, and through the settings verb
+// any caller could have set puid to 0 or to its own uid. The key is refused through every verb route even where a
+// file nothing trusts also asks for it, and taken at the terminal; the layer a refused call meets is unchanged.
+func TestADirectoryOwnersKeyIsRefusedThroughAVerb(t *testing.T) {
+	open := aMesh(t)
+	ctx := t.Context()
+	register(t, open, catalogue.Manifest{Module: "sonarr", Version: "1",
+		Resources: []map[string]any{
+			{"id": "recycle-bin", "type": "directory", "mode": "0755", "owner": "${setting:puid}:${setting:pgid}"},
+			{"id": "identity", "type": "file", "path": "/etc/sonarr.env", "mode": "0644", "trusted": false,
+				"content": "PUID=${setting:puid}\nPGID=${setting:pgid}\nX=${setting:x}\n"}}})
+	if err := atTheTerminal(t, "settings", "set", "sonarr", `{"puid":1001,"pgid":2000,"x":0}`,
+		"--node", "anchor"); err != nil {
+		t.Fatalf("the owner at the terminal: %v", err)
+	}
+	if _, err := assign(ctx, open, "anchor", "sonarr"); err != nil {
+		t.Fatal(err)
+	}
+	layer := func() string {
+		t.Helper()
+		values, _, err := open.inventory.Layer(ctx, "anchor", "sonarr")
+		if err != nil {
+			t.Fatal(err)
+		}
+		raw, _ := json.Marshal(values)
+		return string(raw)
+	}
+	kept := layer()
+	refused := func(what string, err error) {
+		t.Helper()
+		if err == nil || !strings.Contains(err.Error(), "controller's terminal") {
+			t.Fatalf("%s: %v", what, err)
+		}
+	}
+	refused("puid 0 through the verb", throughVerb(t, "settings", map[string]any{"module": "sonarr",
+		"node": "anchor", "values": `{"puid":0,"pgid":2000,"x":0}`}))
+	refused("pgid through the verb, mesh-wide", throughVerb(t, "settings", map[string]any{"module": "sonarr",
+		"values": `{"pgid":0}`}))
+	refused("cleared through the verb", throughVerb(t, "settings", map[string]any{"module": "sonarr",
+		"node": "anchor", "clear": "true"}))
+	if err := throughVerb(t, "command", map[string]any{
+		"command": `settings set sonarr '{"puid":0,"pgid":2000,"x":0}' --node anchor`}); err == nil {
+		t.Fatal("the command verb set the owner")
+	}
+	if got := layer(); got != kept {
+		t.Fatalf("a refused call changed the layer: %s, was %s", got, kept)
+	}
+	// Another key, the owner kept, is still the verb's.
+	if err := throughVerb(t, "settings", map[string]any{"module": "sonarr", "node": "anchor",
+		"values": `{"puid":1001,"pgid":2000,"x":1}`}); err != nil {
+		t.Fatalf("another key through the verb, the owner kept: %v", err)
+	}
+}

cmd/mesh-controller/watchdogs.go

@@ -59,6 +59,10 @@ type signalFacts struct {
 	// from, each naming its sender (S20, novox/hq issue 234).
 	refusedSends    []inventory.Send
 	refusedSendsErr error
+	// doing is every machine whose last report was not a clean apply, with since when it has said the same
+	// failure (S21, novox/hq issue 233).
+	doing    []inventory.Doing
+	doingErr error
 
 	loop    loopFacts
 	loopErr error
@@ -369,6 +373,7 @@ func (w *watchdogs) gather(ctx context.Context) *signalFacts {
 	}
 	f.handActs, f.handActsErr = w.gatherHandActs(ctx, now)
 	f.refusedSends, f.refusedSendsErr = inv.RefusedSendsSince(ctx, now.Add(-generationRefusalsSaid))
+	f.doing, f.doingErr = inv.NotDoingWhatTheyWereTold(ctx)
 	f.facts.taken, _, f.facts.began, f.facts.err = exportedFacts.last()
 	return f
 }

internal/catalogue/manifest.go

@@ -1693,6 +1693,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	problems = append(problems, LogProblems(m)...)
 	// And the defaults it gives its settings (setting_defaults.go, novox/hq ADR 0262).
 	problems = append(problems, SettingProblems(m)...)
+	// And which setting keys each mergeable file takes (setting_takes.go, novox/hq ADR 0326).
+	problems = append(problems, TakenSettingsProblems(m)...)
 	wellFormed := true
 	for _, c := range m.Claims {
 		if !name.MatchString(c.Name) {
@@ -1859,6 +1861,7 @@ func ParseManifest(raw []byte) (Manifest, error) {
 	problems = append(problems, invokeProblems(m)...)
 	problems = append(problems, replacesProblems(m)...)
 	problems = append(problems, UnitSettingProblems(m)...)
+	problems = append(problems, OwnerSettingProblems(m)...)
 	problems = append(problems, endpointNameProblems(m)...)
 	problems = append(problems, RouteProblems(m)...)
 	for _, port := range m.Guards {

internal/catalogue/setting_in_owner_test.go

@@ -0,0 +1,181 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A declared directory may be owned by the account its module runs as (novox/hq issue 279): a media
+// manager runs as the puid and pgid its assignment sets per node, and a folder it must write was owned
+// by the manifest's literal, so the app refused it on a machine whose identity was not the image's.
+
+func recycler() Manifest {
+	return Manifest{Module: "sonarr",
+		Resources: []map[string]any{
+			{"id": "recycle-bin", "type": "directory", "path": "/srv/sonarr/recycle", "mode": "0755",
+				"owner": "${setting:puid}:${setting:pgid}"},
+			{"id": "identity", "type": "file", "path": "/srv/sonarr/identity.env", "mode": "0644",
+				"content": "PUID=${setting:puid}\nPGID=${setting:pgid}\n"},
+		},
+	}
+}
+
+func copied(r map[string]any) map[string]any {
+	out := map[string]any{}
+	for k, v := range r {
+		out[k] = v
+	}
+	return out
+}
+
+// The node's identity reaches the directory's owner, the node's layer over the mesh's, a number given
+// as a string or as a JSON number alike.
+func TestASettingOwnsADirectory(t *testing.T) {
+	m := recycler()
+	layers := []Layer{
+		{From: "the mesh", Values: map[string]any{"puid": "1000", "pgid": "1000"}},
+		{From: "this node", Values: map[string]any{"puid": float64(1001), "pgid": "2000"}},
+	}
+	r := copied(m.Resources[0])
+	if err := settingInto(r, layers, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if r["owner"] != "1001:2000" {
+		t.Fatalf("owned by %q, not 1001:2000", r["owner"])
+	}
+	user := copied(m.Resources[0])
+	user["owner"] = "${setting:puid}"
+	if err := settingInto(user, layers, m.Module); err != nil || user["owner"] != "1001" {
+		t.Fatalf("user alone: %v, %v", user["owner"], err)
+	}
+}
+
+// Composed for a machine, the way a push writes it: the directory reaches the node-engine owned by the
+// number the node's settings name, never by the placeholder.
+func TestAComposedMachineGetsTheOwnerTheSettingNames(t *testing.T) {
+	r := anAdoptedAnchor()
+	r.Modules = append(r.Modules, recycler())
+	with := anchorRendering(false)
+	with.Settings["sonarr"] = []Layer{{From: "anchor", Values: map[string]any{"puid": "1001", "pgid": "2000"}}}
+	composed, err := r.Compose(with)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if why, left := composed.LeftOut["sonarr"]; left {
+		t.Fatalf("left out: %s", why)
+	}
+	got := byID(composed.Resources)["sonarr.recycle-bin"]
+	if got["owner"] != "1001:2000" {
+		t.Fatalf("composed owned by %v, not 1001:2000", got["owner"])
+	}
+}
+
+// Only a whole number owns a directory: an account's name, text, a sign, a fraction or a value past the
+// kernel's ids is refused by name, and the directory is left as it was. So is a key nothing sets.
+func TestAnOwnerSettingThatIsNoNumberIsRefused(t *testing.T) {
+	m := recycler()
+	for _, bad := range []any{"abc", "root", "", "-1", "+5", "1000:1000", "10 00", "1000\nx", float64(1.5),
+		float64(-3), "4294967295", "99999999999", true} {
+		r := copied(m.Resources[0])
+		err := settingInto(r, []Layer{{From: "ace", Values: map[string]any{"puid": bad, "pgid": "1000"}}}, m.Module)
+		if err == nil || !strings.Contains(err.Error(), `"puid"`) || !strings.Contains(err.Error(), "whole number") {
+			t.Errorf("%v: %v", bad, err)
+		}
+		if r["owner"] != m.Resources[0]["owner"] {
+			t.Errorf("%v: the owner was changed on refusal: %v", bad, r["owner"])
+		}
+	}
+	r := copied(m.Resources[0])
+	if err := settingInto(r, nil, m.Module); err == nil || !strings.Contains(err.Error(), "${setting:puid}") {
+		t.Errorf("nothing set: %v", err)
+	}
+	if err := JudgeSettings(m, []Layer{{From: "ace", Values: map[string]any{"puid": "media", "pgid": "1000"}}}, false); err == nil ||
+		!strings.Contains(err.Error(), "whole number") {
+		t.Errorf("a stored name is not refused when judged: %v", err)
+	}
+}
+
+// Where the manifest is read: an owner holding a setting is a whole placeholder or a whole number on
+// each side of the colon, and every key is one the module asks for elsewhere or declares a default for.
+func TestAnOwnerSettingIsJudgedWhereTheManifestIsRead(t *testing.T) {
+	ok := []string{"${setting:puid}:${setting:pgid}", "${setting:puid}", "${setting:puid}:1000", "1000:${setting:pgid}",
+		"1000:1000", "media:media"}
+	bad := []string{
+		"${setting:puid}x",
+		"x${setting:puid}",
+		"${setting:puid}:${setting:pgid}:1",
+		"${setting:puid}${setting:pgid}",
+		"media:${setting:pgid}",
+		"${setting:puid}:",
+		"${setting:other}:${setting:pgid}",
+	}
+	for _, owner := range append(ok, bad...) {
+		m := recycler()
+		m.Resources[0] = copied(m.Resources[0])
+		m.Resources[0]["owner"] = owner
+		err := parsed(t, m)
+		refused := err != nil && strings.Contains(err.Error(), "owner")
+		want := false
+		for _, b := range bad {
+			want = want || b == owner
+		}
+		if refused != want {
+			t.Errorf("%s: refused %v, want %v (%v)", owner, refused, want, err)
+		}
+	}
+	// A key with a default is declared, though nothing else asks for it.
+	m := recycler()
+	m.Resources = m.Resources[:1]
+	m.Resources[0] = copied(m.Resources[0])
+	m.Resources[0]["owner"] = "${setting:workers}"
+	m.Settings = map[string]SettingDeclaration{"workers": {Kind: KindPreference, Default: float64(4), Why: "a test"}}
+	if err := parsed(t, m); err != nil && strings.Contains(err.Error(), "owner") {
+		t.Errorf("a declared key was refused: %v", err)
+	}
+	// A file's owner takes no setting: the sweep says so.
+	f := recycler()
+	f.Resources[1] = copied(f.Resources[1])
+	f.Resources[1]["owner"] = "${setting:puid}"
+	if err := parsed(t, f); err == nil || !strings.Contains(err.Error(), "not filled in this field") {
+		t.Errorf("a file's owner setting passed: %v", err)
+	}
+}
+
+// A key a directory's owner asks for is a destination, so setting it is not called stray.
+func TestASettingAnOwnerAsksForIsNotStray(t *testing.T) {
+	m := recycler()
+	m.Resources = m.Resources[:1]
+	stray := strings.Join(UnusedSettings(m, []Layer{{From: "ace", Values: map[string]any{"puid": "1001", "pgid": "2000"}}}), "; ")
+	if strings.Contains(stray, "puid") || strings.Contains(stray, "pgid") {
+		t.Errorf("called stray: %s", stray)
+	}
+}
+
+// An owner is written as the number parsed: "0001" and "00" reach the node-engine as 1 and 0, never as text.
+// Uid 0 is allowed, because a key an owner asks for is the terminal's alone.
+func TestAnOwnerSettingIsWrittenAsTheNumber(t *testing.T) {
+	m := recycler()
+	r := copied(m.Resources[0])
+	if err := settingInto(r, []Layer{{From: "ace", Values: map[string]any{"puid": "0001", "pgid": "00"}}}, m.Module); err != nil {
+		t.Fatal(err)
+	}
+	if r["owner"] != "1:0" {
+		t.Fatalf("owned by %q, not 1:0", r["owner"])
+	}
+}
+
+// Every key a directory's owner asks for is the controller's terminal's alone (novox/hq issue 279, issue 339):
+// root chowns the folder to it, so it is terminal-only whatever else asks for it — a file nothing trusts, a
+// default, or nothing at all.
+func TestAnOwnersKeyIsTheTerminals(t *testing.T) {
+	m := recycler()
+	m.Resources[1] = copied(m.Resources[1])
+	m.Resources[1]["trusted"] = false
+	m.Settings = map[string]SettingDeclaration{"pgid": {Kind: KindPreference, Default: "1000", Why: "a test"}}
+	keys := strings.Join(TerminalKeys(m), ",")
+	for _, k := range []string{"puid", "pgid"} {
+		if !strings.Contains(","+keys+",", ","+k+",") {
+			t.Errorf("%s is not the terminal's: %s", k, keys)
+		}
+	}
+}

internal/catalogue/setting_into.go

@@ -4,6 +4,7 @@ import (
 	"fmt"
 	"regexp"
 	"sort"
+	"strconv"
 	"strings"
 )
 
@@ -15,7 +16,8 @@ import (
 // (novox/hq issues 122, 134). ADR 0112 names the operator as one of the four providers; this is the
 // operator answering.
 //
-// `${setting:<key>}` in a file's content, and in a service's unit name, is filled from the module's settings layers — the mesh's,
+// `${setting:<key>}` in a file's content, in a service's unit name and in a directory's owner (a uid or
+// gid only, issue 279) is filled from the module's settings layers — the mesh's,
 // then this node's — the same layers a mergeable JSON file and a contribution already take, so
 // `settings set <module>` is the one place a person's values go. **Refused when no layer sets it**,
 // naming the key and the remedy: a definition that carried a default for a mail domain would be
@@ -59,6 +61,9 @@ func settingInto(resource map[string]any, layers []Layer, module string) error {
 	if fmt.Sprint(resource["type"]) == "service" {
 		return settingIntoUnit(resource, layers, module)
 	}
+	if fmt.Sprint(resource["type"]) == "directory" {
+		return settingIntoOwner(resource, layers, module)
+	}
 	if fmt.Sprint(resource["type"]) != "file" {
 		return nil
 	}
@@ -143,6 +148,107 @@ func settingIntoUnit(resource map[string]any, layers []Layer, module string) err
 	return nil
 }
 
+// A declared directory may be owned by the account its module runs as (novox/hq issue 279).
+//
+// A containerised module runs as the identity its assignment sets per node — its puid and pgid
+// settings, written into the environment file its image reads (ADR 0112, issue 153) — and a directory
+// its app must write, beyond the one its image re-owns at start, was owned by whatever the manifest
+// spelt: right on a machine whose identity matched the image's default, refused by the app on one whose
+// did not. So a directory's `owner` may name the settings that identity is: `${setting:<key>}` for the
+// user alone, `${setting:<user>}:${setting:<group>}` for both, filled from the same layers at
+// composition.
+//
+// **Whole numbers only.** An owner a setting fills is a uid or a gid — never an account's name, never
+// text — so no value can put anything into the ownership the node-engine applies but a number; one that
+// is not is refused at composition, naming the key, and the directory is left as it was. The shape is
+// judged where the manifest is read (OwnerSettingProblems): each side of the colon a whole placeholder
+// or a whole number, and every key one the module itself asks for elsewhere — in a file, a unit, a
+// contribution or a served fact — or declares a default for, so the owner follows the identity its
+// process is told it runs as, never a key that reaches nothing else.
+
+// ownerSide is one side of an owner a setting may fill: a whole placeholder or a whole number.
+var ownerSide = `(?:\$\{setting:[a-z0-9][a-z0-9_.-]*\}|[0-9]+)`
+
+// ownerWithSetting is the only shape an owner holding a setting may have: user, or user:group.
+var ownerWithSetting = regexp.MustCompile(`^` + ownerSide + `(?::` + ownerSide + `)?$`)
+
+// wholeID is a value as a uid or a gid, and whether it is one: a whole number below the kernel's "no id"
+// (2^32-1). Uid 0 is one: a key an owner asks for is the controller's terminal's alone (TerminalKeys).
+func wholeID(v string) (uint64, bool) {
+	if v == "" || strings.TrimLeft(v, "0123456789") != "" {
+		return 0, false
+	}
+	n, err := strconv.ParseUint(v, 10, 32)
+	return n, err == nil && n < 1<<32-1
+}
+
+// OwnerSettingProblems refuses, where a manifest is read, a directory whose owner carries a setting
+// in any shape but a whole placeholder or number on each side of the colon, or names a key the module
+// asks for nowhere else and declares no default for.
+func OwnerSettingProblems(m Manifest) []string {
+	var problems []string
+	asked := settingKeysAskedOutsideOwners(m)
+	for k := range m.Settings {
+		asked[k] = true
+	}
+	for _, r := range m.Resources {
+		owner, _ := r["owner"].(string)
+		if !strings.Contains(owner, "${setting:") {
+			continue
+		}
+		if fmt.Sprint(r["type"]) != "directory" {
+			// Said by the placeholder sweep: only a directory's owner takes a setting.
+			continue
+		}
+		if !ownerWithSetting.MatchString(owner) {
+			problems = append(problems, fmt.Sprintf("%s: the directory %v's owner %q carries a setting in a shape "+
+				"the mesh does not fill; an owner names the account by number only, each side of the colon a whole "+
+				"${setting:key} or a whole number (${setting:puid}:${setting:pgid}) (novox/hq issue 279)",
+				m.Module, r["id"], owner))
+			continue
+		}
+		for _, key := range settingsUsed(owner) {
+			if !asked[key] {
+				problems = append(problems, fmt.Sprintf("%s: the directory %v's owner says ${setting:%s}, and the "+
+					"module asks for %q nowhere else and declares no default for it: an owner follows the identity "+
+					"the module's process is told it runs as (its identity file's ${setting:%s}), never a key of its "+
+					"own (novox/hq issue 279)", m.Module, r["id"], key, key, key))
+			}
+		}
+	}
+	return problems
+}
+
+// settingIntoOwner fills ${setting:…} in a directory's owner, refusing — with the key and why, the
+// resource left as it was — a key nothing sets and a value that is not a whole number.
+func settingIntoOwner(resource map[string]any, layers []Layer, module string) error {
+	owner, ok := resource["owner"].(string)
+	if !ok {
+		return nil
+	}
+	for _, key := range settingsUsed(owner) {
+		value, set := settingValue(layers, key)
+		if !set {
+			return &UnsetSettingError{Module: module, Setting: key, said: fmt.Sprintf(
+				"%s has a directory %v whose owner says ${setting:%s}, and nothing sets %q for it — an operator's "+
+					"value is the assignment's, never the definition's (novox/hq ADR 0112): "+
+					"`settings set %s <file>` with {%q: …}%s",
+				module, resource["id"], key, key, module, key, orNoSettings(layers))}
+		}
+		v := plainly(value)
+		id, whole := wholeID(v)
+		if !whole {
+			return fmt.Errorf("%s: the setting %q is %q, which cannot own the directory %v: an owner a setting "+
+				"names is a uid or a gid, a whole number, never an account's name or other text (novox/hq issue 279)",
+				module, key, v, resource["id"])
+		}
+		// Written as the number parsed, so "0001" reaches the node-engine as 1, never as text.
+		owner = strings.ReplaceAll(owner, "${setting:"+key+"}", strconv.FormatUint(id, 10))
+	}
+	resource["owner"] = owner
+	return nil
+}
+
 func settingValue(layers []Layer, key string) (any, bool) {
 	var value any
 	set := false
@@ -171,9 +277,25 @@ func orNoSettings(layers []Layer) string {
 	return "; set today: " + strings.Join(keys, ", ")
 }
 
-// settingKeysUsedBy is every key a module's files, contributions and served facts ask for, so a
-// setting that lands in one is not called stray.
+// settingKeysUsedBy is every key a module's files, units, directory owners, contributions and served
+// facts ask for, so a setting that lands in one is not called stray.
 func settingKeysUsedBy(m Manifest) map[string]bool {
+	used := settingKeysAskedOutsideOwners(m)
+	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "directory" {
+			if owner, ok := r["owner"].(string); ok {
+				for _, k := range settingsUsed(owner) {
+					used[k] = true
+				}
+			}
+		}
+	}
+	return used
+}
+
+// settingKeysAskedOutsideOwners is every key a module's files, units, contributions and served facts
+// ask for: what a directory's owner may follow (OwnerSettingProblems).
+func settingKeysAskedOutsideOwners(m Manifest) map[string]bool {
 	used := map[string]bool{}
 	note := func(s string) {
 		for _, k := range settingsUsed(s) {

internal/catalogue/setting_takes.go

@@ -0,0 +1,176 @@
+package catalogue
+
+import (
+	"fmt"
+	"strings"
+	"unicode"
+)
+
+// A mergeable file names the setting keys it takes (novox/hq ADR 0326, issue 168).
+//
+// Before this, every key of a module's layers merged into every one of its mergeable files: the
+// mesh's own words, a key meant for a `${setting:<key>}` in another file, a key for a second
+// configuration file. So a module could not own two configurable files, and every receiver had to
+// ignore what it did not know. ADR 0164 §11 decided that a setting names the files that read it; this
+// is that relation, stated from the file's side, so the operator's own values stay declared nowhere
+// (ADR 0262 §2).
+
+// TakesSettingsField is the key a mergeable file carries to name the top-level setting keys it takes.
+const TakesSettingsField = "takes-settings"
+
+// takenKeys is the keys a resource names in takes-settings, and whether it names any list at all. An
+// empty list is a list: that file takes no setting.
+func takenKeys(resource map[string]any) (map[string]bool, bool) {
+	raw, said := resource[TakesSettingsField]
+	if !said {
+		return nil, false
+	}
+	keys := map[string]bool{}
+	for _, k := range stringsOf(raw) {
+		keys[k] = true
+	}
+	return keys, true
+}
+
+// onlyTaken is the layers with every key the file does not name left out. The file's own defaults and
+// what the mesh reads itself are not touched here: settle already keeps both out of a file.
+func onlyTaken(layers []Layer, taken map[string]bool) []Layer {
+	kept := make([]Layer, 0, len(layers))
+	for _, layer := range layers {
+		values := map[string]any{}
+		for key, value := range layer.Values {
+			if taken[key] {
+				values[key] = value
+			}
+		}
+		kept = append(kept, Layer{From: layer.From, Values: values, Default: layer.Default})
+	}
+	return kept
+}
+
+// namesItsKeys says whether a module's mergeable files name the keys they take (ADR 0326 §2): true
+// only when it has one and every one carries takes-settings. A module with a silent mergeable file
+// keeps today's form (§3), where every key reaches every mergeable file.
+func namesItsKeys(m Manifest) bool {
+	merging := 0
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how == "" {
+			continue
+		}
+		merging++
+		if _, said := r[TakesSettingsField]; !said {
+			return false
+		}
+	}
+	return merging > 0
+}
+
+// TakenSettingsProblems is every way a definition's takes-settings is wrong (ADR 0326 §2 and §4), in
+// its own words: on a file that does not merge, not a list of keys, a key named twice, one the mesh
+// reads itself, one the file keeps for itself, or one mergeable file naming its keys beside another
+// that names none.
+func TakenSettingsProblems(m Manifest) []string {
+	// Not yet here: refusing a module that declares a setting and owns a mergeable file naming no keys
+	// (ADR 0326 §3). betterbird is one, and the catalogue cannot name its keys before this controller
+	// runs, so that refusal follows once the catalogue does (novox/hq issue 574).
+	return takenSettingsProblems(m)
+}
+
+// takenSettingsProblems is every rule of ADR 0326 §2 and §4, judged where a definition is checked and
+// where a stored one is composed.
+func takenSettingsProblems(m Manifest) []string {
+	var problems []string
+	var naming, silent []string
+	for _, r := range m.Resources {
+		id := fmt.Sprint(r["id"])
+		how, _ := r["merge"].(string)
+		raw, said := r[TakesSettingsField]
+		if how == "" {
+			if said {
+				problems = append(problems, fmt.Sprintf("%s's %s says %s and does not merge: only a mergeable "+
+					"file takes settings by key (novox/hq ADR 0326)", m.Module, id, TakesSettingsField))
+			}
+			continue
+		}
+		if !said {
+			silent = append(silent, id)
+			continue
+		}
+		naming = append(naming, id)
+		list, isList := raw.([]any)
+		if !isList {
+			problems = append(problems, fmt.Sprintf("%s's %s: %s is a list of setting keys, and this is %T",
+				m.Module, id, TakesSettingsField, raw))
+			continue
+		}
+		protected := map[string]bool{}
+		for _, k := range stringsOf(r["protected"]) {
+			protected[k] = true
+		}
+		seen := map[string]bool{}
+		for _, item := range list {
+			key, isString := item.(string)
+			switch {
+			case !isString || !usableKey(key):
+				problems = append(problems, fmt.Sprintf("%s's %s: %v in %s is not a usable setting key",
+					m.Module, id, item, TakesSettingsField))
+			case seen[key]:
+				problems = append(problems, fmt.Sprintf("%s's %s names %q twice in %s",
+					m.Module, id, key, TakesSettingsField))
+			case meshWords[key]:
+				problems = append(problems, fmt.Sprintf("%s's %s names %q in %s, and the mesh reads %q itself "+
+					"(novox/hq ADR 0164 §14)", m.Module, id, key, TakesSettingsField, key))
+			case protected[key]:
+				problems = append(problems, fmt.Sprintf("%s's %s names %q in %s and keeps it as protected: a "+
+					"key is the file's or the setting's, never both", m.Module, id, key, TakesSettingsField))
+			}
+			if isString {
+				seen[key] = true
+			}
+		}
+	}
+	if len(naming) > 0 {
+		for _, id := range silent {
+			problems = append(problems, fmt.Sprintf("%s's %s merges and names no %s while %s does: once one "+
+				"mergeable file of a module names the keys it takes, every one does, an empty list for none "+
+				"(novox/hq ADR 0326)", m.Module, id, TakesSettingsField, strings.Join(naming, ", ")))
+		}
+	}
+	return problems
+}
+
+// usableKey is a key a file can be said to take: not empty, and no space, line end or control
+// character. Not the lower-case rule of a `${setting:<key>}`: a file's own keys are its software's
+// spelling, such as `timeZone`.
+func usableKey(key string) bool {
+	if key == "" {
+		return false
+	}
+	for _, r := range key {
+		if unicode.IsSpace(r) || unicode.IsControl(r) || !unicode.IsPrint(r) {
+			return false
+		}
+	}
+	return true
+}
+
+// takenSaid is what a stray key's message adds for a module whose files name their keys: which keys
+// each file takes, so the person sees where the key would have had to be named.
+func takenSaid(m Manifest) string {
+	if !namesItsKeys(m) {
+		return ""
+	}
+	var files []string
+	for _, r := range m.Resources {
+		if how, _ := r["merge"].(string); how == "" {
+			continue
+		}
+		keys := stringsOf(r[TakesSettingsField])
+		if len(keys) == 0 {
+			files = append(files, fmt.Sprintf("%v takes none", r["id"]))
+			continue
+		}
+		files = append(files, fmt.Sprintf("%v takes %s", r["id"], strings.Join(keys, ", ")))
+	}
+	return " (" + strings.Join(files, "; ") + ")"
+}

internal/catalogue/setting_takes_test.go

@@ -0,0 +1,196 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// twoFiles is a module that owns two configurable files, which issue 168 said no module could:
+// every key of every layer reached both.
+func twoFiles(app, sidecar []any) Manifest {
+	appFile := map[string]any{"id": "app", "type": "file", "path": "/etc/app.json", "merge": MergeJSON,
+		"content": `{"server":{"port":8080},"search":{"safe":1}}`}
+	sideFile := map[string]any{"id": "sidecar", "type": "file", "path": "/etc/sidecar.json", "merge": MergeJSON,
+		"content": `{"url":"http://127.0.0.1:8080"}`}
+	if app != nil {
+		appFile[TakesSettingsField] = app
+	}
+	if sidecar != nil {
+		sideFile[TakesSettingsField] = sidecar
+	}
+	return Manifest{Module: "search", Resources: []map[string]any{
+		appFile, sideFile,
+		{"id": "env", "type": "file", "path": "/etc/search.env", "content": "SITE=${setting:site-name}\n"},
+	}}
+}
+
+func settledContent(t *testing.T, resource map[string]any, layers []Layer) map[string]any {
+	t.Helper()
+	out, err := ApplySettings(resource, layers)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, kept := out[TakesSettingsField]; kept {
+		t.Errorf("%v still carries %s; the host knows no such field", out["id"], TakesSettingsField)
+	}
+	var parsed map[string]any
+	if err := json.Unmarshal([]byte(out["content"].(string)), &parsed); err != nil {
+		t.Fatalf("%v is not JSON after settling: %v", out["id"], err)
+	}
+	return parsed
+}
+
+func TestEachMergeableFileTakesOnlyTheKeysItNames(t *testing.T) {
+	// novox/hq ADR 0326 §1, issue 168: two configurable files, each taking its own keys. A key for
+	// the other file, for a ${setting:…} elsewhere or for the mesh itself lands in neither.
+	m := twoFiles([]any{"server", "search"}, []any{"url"})
+	layers := []Layer{
+		{From: "the mesh", Values: map[string]any{
+			"server": map[string]any{"base_url": "https://search.example.tld/"},
+			"url":    "http://127.0.0.1:9090", "site-name": "Search",
+			"endpoints": map[string]any{"web": map[string]any{"reach": "public"}}}},
+		{From: "node-a", Values: map[string]any{"search": map[string]any{"safe": 0.0}}},
+	}
+
+	app := settledContent(t, m.Resources[0], layers)
+	for _, stray := range []string{"url", "site-name", "endpoints"} {
+		if _, in := app[stray]; in {
+			t.Errorf("app took %q, which it does not name: %v", stray, app)
+		}
+	}
+	server, _ := app["server"].(map[string]any)
+	if server["base_url"] != "https://search.example.tld/" || server["port"] != 8080.0 {
+		t.Errorf("app's server block is %v; the setting should merge into the file's own", server)
+	}
+	if search, _ := app["search"].(map[string]any); search["safe"] != 0.0 {
+		t.Errorf("app's search block is %v; the node's layer should win", search)
+	}
+
+	side := settledContent(t, m.Resources[1], layers)
+	if side["url"] != "http://127.0.0.1:9090" {
+		t.Errorf("sidecar's url is %v; it names url", side["url"])
+	}
+	if len(side) != 1 {
+		t.Errorf("sidecar took keys it does not name: %v", side)
+	}
+}
+
+func TestAnEmptyListTakesNoSetting(t *testing.T) {
+	// ADR 0164 §12: a file that names no setting takes none.
+	m := twoFiles([]any{"server"}, []any{})
+	side := settledContent(t, m.Resources[1], []Layer{{From: "the mesh", Values: map[string]any{
+		"server": map[string]any{"port": 1.0}, "url": "x"}}})
+	if len(side) != 1 || side["url"] != "http://127.0.0.1:8080" {
+		t.Errorf("a file taking none was changed: %v", side)
+	}
+}
+
+func TestAFileThatNamesNothingKeepsTodaysForm(t *testing.T) {
+	// ADR 0326 §3, ADR 0164 §15: a module none of whose files names keys is left as it was.
+	m := twoFiles(nil, nil)
+	app := settledContent(t, m.Resources[0], []Layer{{From: "the mesh", Values: map[string]any{"url": "x"}}})
+	if app["url"] != "x" {
+		t.Errorf("a silent file should still take every key until its module names them: %v", app)
+	}
+	if unused := UnusedSettings(m, []Layer{{From: "the mesh", Values: map[string]any{"anything": 1}}}); len(unused) != 0 {
+		t.Errorf("today's form has nothing stray, and said: %v", unused)
+	}
+}
+
+func TestAKeyNoFileNamesIsStray(t *testing.T) {
+	// ADR 0326 §5: once the files name their keys, a key none of them names — and nothing else
+	// takes — is stray, and is said with what each file takes.
+	m := twoFiles([]any{"server", "search"}, []any{"url"})
+	unused := UnusedSettings(m, []Layer{{From: "the mesh", Values: map[string]any{
+		"server": 1, "url": "x", "site-name": "Search", "ui": map[string]any{"theme": "dark"}}}})
+	if len(unused) != 1 || !strings.Contains(unused[0], `"ui"`) {
+		t.Fatalf("only ui reaches nothing; named: %v", unused)
+	}
+	if !strings.Contains(unused[0], "app takes server, search") || !strings.Contains(unused[0], "sidecar takes url") {
+		t.Errorf("the stray key's message does not say what each file takes: %s", unused[0])
+	}
+}
+
+func TestOneNamingFileMakesEveryMergeableFileName(t *testing.T) {
+	// ADR 0326 §2: a module with one naming and one silent mergeable file is refused, naming the
+	// silent one — the silent one would otherwise still take every key.
+	m := twoFiles([]any{"server"}, nil)
+	problems := TakenSettingsProblems(m)
+	if len(problems) != 1 || !strings.Contains(problems[0], "sidecar merges and names no takes-settings") {
+		t.Fatalf("problems: %v", problems)
+	}
+	if err := JudgeSettings(m, nil, false); err == nil || !strings.Contains(err.Error(), "sidecar") {
+		t.Errorf("composing it should refuse it too, and said: %v", err)
+	}
+	raw, err := json.Marshal(map[string]any{"module": m.Module, "version": "1", "resources": m.Resources})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ParseManifest(raw); err == nil || !strings.Contains(err.Error(), "sidecar merges and names no") {
+		t.Errorf("the module check does not say it: %v", err)
+	}
+}
+
+func TestTakesSettingsIsRefusedWhereItCannotMeanAnything(t *testing.T) {
+	// ADR 0326 §4.
+	cases := map[string]struct {
+		resource map[string]any
+		says     string
+	}{
+		"on a file that does not merge": {
+			map[string]any{"id": "plain", "type": "file", "path": "/x", "content": "x",
+				TakesSettingsField: []any{"a"}},
+			"does not merge"},
+		"not a list": {
+			map[string]any{"id": "conf", "type": "file", "path": "/x", "merge": MergeJSON, "content": "{}",
+				TakesSettingsField: "server"},
+			"is a list of setting keys"},
+		"a mesh word": {
+			map[string]any{"id": "conf", "type": "file", "path": "/x", "merge": MergeJSON, "content": "{}",
+				TakesSettingsField: []any{"endpoints"}},
+			"the mesh reads"},
+		"a protected key": {
+			map[string]any{"id": "conf", "type": "file", "path": "/x", "merge": MergeJSON, "content": "{}",
+				"protected": []any{"secret"}, TakesSettingsField: []any{"secret"}},
+			"keeps it as protected"},
+		"named twice": {
+			map[string]any{"id": "conf", "type": "file", "path": "/x", "merge": MergeJSON, "content": "{}",
+				TakesSettingsField: []any{"a", "a"}},
+			"twice"},
+		"not a key": {
+			map[string]any{"id": "conf", "type": "file", "path": "/x", "merge": MergeJSON, "content": "{}",
+				TakesSettingsField: []any{"two words"}},
+			"not a usable setting key"},
+	}
+	for name, c := range cases {
+		problems := TakenSettingsProblems(Manifest{Module: "m", Resources: []map[string]any{c.resource}})
+		if !containsText(problems, c.says) {
+			t.Errorf("%s: want a problem saying %q, got %v", name, c.says, problems)
+		}
+	}
+	// And a file that does not merge is refused where it is settled, not handed to the host.
+	plain := map[string]any{"id": "plain", "type": "file", "path": "/x", "content": "x",
+		TakesSettingsField: []any{"a"}}
+	if _, err := ApplySettings(plain, nil); err == nil {
+		t.Error("a file that does not merge and names keys was settled")
+	}
+}
+
+func TestASoftwareSpelledKeyIsUsable(t *testing.T) {
+	// A file's keys are its software's: nodered's timeZone is not lower case and is still a key.
+	m := Manifest{Module: "flows", Resources: []map[string]any{{"id": "settings", "type": "file",
+		"path": "/x", "merge": MergeJSON, "content": "{}", TakesSettingsField: []any{"timeZone"}}}}
+	if problems := TakenSettingsProblems(m); len(problems) != 0 {
+		t.Errorf("timeZone was refused: %v", problems)
+	}
+}
+
+func containsText(list []string, text string) bool {
+	for _, s := range list {
+		if strings.Contains(s, text) {
+			return true
+		}
+	}
+	return false
+}

internal/catalogue/settings.go

@@ -46,11 +46,24 @@ type Layer struct {
 // rather than by repeating everything the rest already say.
 func ApplySettings(resource map[string]any, layers []Layer) (map[string]any, error) {
 	how, _ := resource["merge"].(string)
+	taken, names := takenKeys(resource)
 	if how == "" {
+		if names {
+			// Refused by the module check too (TakenSettingsProblems); said here as well, for a
+			// definition stored by an older binary, rather than handed to the host, which knows no
+			// such field.
+			return nil, fmt.Errorf("%v says %s and does not merge: only a mergeable file takes "+
+				"settings by key (novox/hq ADR 0326)", resource["id"], TakesSettingsField)
+		}
 		// Not a mergeable file. Settings for it are ignored rather than silently doing nothing
 		// somewhere else — see UnusedSettings, which is what says so.
 		return resource, nil
 	}
+	if names {
+		// **The file takes the keys it names, and no other** (novox/hq ADR 0326, issue 168): a key
+		// for another file, for a `${setting:<key>}` or for the mesh itself does not land here.
+		layers = onlyTaken(layers, taken)
+	}
 	if how != MergeJSON {
 		return nil, fmt.Errorf(
 			"%v says it merges as %q, and this control plane knows how to merge %q",
@@ -91,6 +104,7 @@ func ApplySettings(resource map[string]any, layers []Layer) (map[string]any, err
 	delete(out, "merge")
 	delete(out, "protected")
 	delete(out, TrustedField)
+	delete(out, TakesSettingsField)
 	return out, nil
 }
 
@@ -324,8 +338,11 @@ func sortedKeysAny(m map[string]any) []string {
 // (novox/hq 04-ISSUES/173); and the mesh's own words — `expose`, `ports`, `reach`, `endpoints` —
 // are read by the mesh. A key none of those takes is stray, and is said so rather than dropped.
 func UnusedSettings(m Manifest, layers []Layer) []string {
+	named := namesItsKeys(m)
 	for _, r := range m.Resources {
-		if how, _ := r["merge"].(string); how != "" {
+		if how, _ := r["merge"].(string); how != "" && !named {
+			// Today's form (novox/hq ADR 0326 §3, ADR 0164 §15): a mergeable file that names no
+			// keys takes every key, so nothing is stray.
 			return nil
 		}
 	}
@@ -337,6 +354,13 @@ func UnusedSettings(m Manifest, layers []Layer) []string {
 	}
 
 	lands := settingKeysUsedBy(m)
+	// A mergeable file takes the keys it names (novox/hq ADR 0326 §5).
+	for _, r := range m.Resources {
+		taken, _ := takenKeys(r)
+		for key := range taken {
+			lands[key] = true
+		}
+	}
 	// A key the module gives a default reaches what asks for it (novox/hq ADR 0262): setting it
 	// overrides the default, which is how a running module gains a setting without a gap between.
 	for key := range m.Settings {
@@ -401,8 +425,8 @@ func UnusedSettings(m Manifest, layers []Layer) []string {
 			}
 			unused = append(unused, fmt.Sprintf(
 				"%s sets %q, and %s has no file that merges it, asks for no ${setting:%s}, and "+
-					"declares no %q in what it contributes or serves",
-				layer.From, key, m.Module, key, key))
+					"declares no %q in what it contributes or serves%s",
+				layer.From, key, m.Module, key, key, takenSaid(m)))
 		}
 	}
 	sort.Strings(unused)
@@ -512,6 +536,11 @@ func JudgeSettings(m Manifest, layers []Layer, adopted bool) error {
 	if err := settingsHoldOneLine(m.Module, layers); err != nil {
 		return err
 	}
+	// Which keys each mergeable file takes is the definition's to say right (novox/hq ADR 0326);
+	// judged here too for a definition stored by an older binary.
+	if problems := takenSettingsProblems(m); len(problems) > 0 {
+		return fmt.Errorf("%s", problems[0])
+	}
 	// With no layers too: a definition may ask for a setting nobody made — an access placed by
 	// nobody, a file's ${setting:…} nothing sets — and that is the same statement, missing.
 	if _, err := GivenPorts(m, layers); err != nil {

internal/catalogue/terminal_keys.go

@@ -33,6 +33,9 @@ import (
 //  4. **A module's whole layer, when it has a mergeable file not marked `"trusted": false`** (novox/hq issue 340,
 //     TrustedMergeable). A mergeable file takes any key a layer sets, not only those its content names, so no list
 //     of keys covers it: an empty runtime configuration a provider reads would take a `url` of the caller's.
+//  5. **Every setting a directory's owner asks for** (novox/hq issue 279): root chowns the directory to the number
+//     at the next push, so through a verb any caller could hand itself — or uid 0 — a module's folder. Whatever
+//     else asks for the key, a file marked `"trusted": false` included, the owner makes it the terminal's.
 //
 // Derived from the manifest, never listed by hand, so a provider or a trusted file added tomorrow is covered.
 
@@ -42,8 +45,8 @@ import (
 const TrustedField = "trusted"
 
 // TerminalKeys are the settings keys of a module that are set at the controller's terminal alone: places and
-// accesses, every key its provisions serve and every setting a served value asks for, and every setting a file
-// asks for unless it says `"trusted": false`. Places and accesses first, then the rest sorted.
+// accesses, every key its provisions serve and every setting a served value asks for, every setting a file
+// asks for unless it says `"trusted": false`, and every setting a directory's owner asks for. Places and accesses first, then the rest sorted.
 func TerminalKeys(m Manifest) []string {
 	keys := map[string]bool{}
 	for _, served := range m.Serves {
@@ -57,6 +60,13 @@ func TerminalKeys(m Manifest) []string {
 		}
 	}
 	for _, r := range m.Resources {
+		if fmt.Sprint(r["type"]) == "directory" {
+			owner, _ := r["owner"].(string)
+			for _, asked := range settingsUsed(owner) {
+				keys[asked] = true
+			}
+			continue
+		}
 		if fmt.Sprint(r["type"]) != "file" {
 			continue
 		}

internal/catalogue/unconsumed_placeholder.go

@@ -56,7 +56,7 @@ type filler struct {
 // seatInto, machineInto and contributionsInto. A pass that comes to read another field adds it here,
 // or the sweep refuses the placeholder it would have filled.
 var fillers = []filler{
-	{namespace: "setting", patterns: []*regexp.Regexp{settingRef}, fields: map[string][]string{"file": {"content"}, "service": {"unit"}}},
+	{namespace: "setting", patterns: []*regexp.Regexp{settingRef}, fields: map[string][]string{"file": {"content"}, "service": {"unit"}, "directory": {"owner"}}},
 	{namespace: "dir", patterns: []*regexp.Regexp{dirRef}, fields: map[string][]string{"*": {"path", "content", "volumes", "env", "env-file"}}},
 	{namespace: "access", patterns: []*regexp.Regexp{accessRef}, fields: map[string][]string{"*": {"path", "content", "volumes", "env", "env-file"}}},
 	{namespace: "secret", patterns: []*regexp.Regexp{placeholder}, fields: map[string][]string{"file": {"content"}},

internal/link/events.go

@@ -311,9 +311,6 @@ type ChangePlan struct {
 	Steps []string `json:"steps,omitempty"`
 	// Summary is the plan in one line, for a commit status.
 	Summary string `json:"summary"`
-	// Class is the class of the slowest-budgeted module the change moves (novox/hq ADR 0282 §1, ADR 0313 §2):
-	// core, leaf, or none when it moves no module at all — a fix that moves nothing has no fix budget.
-	Class string `json:"class,omitempty"`
 }
 
 // MachinePlan is one machine's part of a change plan.

testdata/store-tests

@@ -26,3 +26,4 @@
 ./cmd/mesh-controller TestAnUnassignThatLeavesItsNodeUnresolvedSaysSoOnceInItsAnswer
 ./cmd/mesh-controller TestAnUnassignThatLeavesItsNodeResolvedSaysNothingOfIt
 ./cmd/mesh-controller TestAnAssignThatLeavesItsNodeUnresolvedSaysOnlyThePlansRefusal
+./cmd/mesh-controller TestADirectoryOwnersKeyIsRefusedThroughAVerb