List every module's preferences in the settings verb (hq ADR 0262)

One verb is the interface to every preference, so no module builds a settings tool of its own: each
key, its default and why, and every assigned machine's value with its source.

cmd/mesh-controller/modules.go

@@ -547,12 +547,6 @@ func settingsCommand(ctx context.Context, args []string) error {
 		if len(positionals) == 1 {
 			only = positionals[0]
 		}
-		if *node != "" {
-			// A machine the mesh does not know is refused, never answered with an empty listing.
-			if _, err := inv.NodeByName(ctx, *node); err != nil {
-				return err
-			}
-		}
 		entries, err := inv.Catalogued(ctx)
 		if err != nil {
 			return err
@@ -563,10 +557,6 @@ func settingsCommand(ctx context.Context, args []string) error {
 			if len(m.Settings) == 0 || (only != "" && m.Module != only) {
 				continue
 			}
-			if *node != "" && !containsString(e.On, *node) {
-				// Asked for one machine: a module not on it has no value there to say.
-				continue
-			}
 			p := preferencesOf{Manifest: m, On: map[string][]catalogue.SettingSource{}}
 			for _, n := range e.On {
 				if *node != "" && n != *node {
@@ -582,11 +572,7 @@ func settingsCommand(ctx context.Context, args []string) error {
 			listed = append(listed, p)
 		}
 		if only != "" && len(listed) == 0 {
-			fmt.Printf("%s declares no preferences%s\n", only, onNode(*node))
-			return nil
-		}
-		if len(listed) == 0 && *node != "" {
-			fmt.Printf("no module on %s declares a preference\n", *node)
+			fmt.Printf("%s declares no preferences\n", only)
 			return nil
 		}
 		fmt.Print(describePreferences(listed))
@@ -624,14 +610,6 @@ func describeEffective(module, where string, values []catalogue.SettingSource) s
 	return b.String()
 }
 
-// onNode is ` on <node>` for one machine, nothing for the whole mesh.
-func onNode(node string) string {
-	if node == "" {
-		return ""
-	}
-	return " on " + node
-}
-
 // preferencesOf is one module's preferences and its value on each machine it is assigned to.
 type preferencesOf struct {
 	Manifest catalogue.Manifest

cmd/mesh-controller/pending.go

@@ -478,9 +478,6 @@ func settlingPending(ctx context.Context, open *stores) {
 		for _, line := range settlePending(ctx, open, time.Now()) {
 			fmt.Println(line)
 		}
-		for _, line := range raiseUnknownFields(ctx, open.inventory) {
-			fmt.Println(line)
-		}
 		select {
 		case <-ctx.Done():
 			return

cmd/mesh-controller/plain_words.go

@@ -387,7 +387,10 @@ var plainWordings = map[string]func(conditions.Observation) words{
 			Resolved:    "Resolved: " + m + " runs a good build again"}
 	}),
 	"release-held": worded(func(o conditions.Observation) words {
-		return releaseHeldWords(nil, o.Also)
+		return words{Headline: "Updates wait for your release",
+			Needs:       "release them, or leave them held.",
+			Explanation: "Some module updates wait for a person to release them, and are not delivered until then.",
+			Resolved:    "Resolved: the held updates are released"}
 	}),
 	"facts-stale": worded(func(o conditions.Observation) words {
 		return words{Headline: "Merge checks use outdated facts",
@@ -399,21 +402,21 @@ var plainWordings = map[string]func(conditions.Observation) words{
 	// The controller and the core.
 	"controller-deaf": worded(func(o conditions.Observation) words {
 		return words{Headline: "The controller stopped listening",
-			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
+			Needs: "restart the controller if this stays.",
 			Explanation: "The controller, which coordinates the mesh, has taken no messages for minutes while some " +
 				"wait. Changes and repairs do not happen until it recovers.",
 			Resolved: "The controller listens again"}
 	}),
 	"self-check-silent": worded(func(o conditions.Observation) words {
 		return words{Headline: "The mesh's self-check stopped",
-			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
+			Needs: "restart the controller if this stays.",
 			Explanation: "The self-check, which looks over the whole mesh every few minutes, has not finished a run. " +
 				"Problems may go unnoticed until it runs again.",
 			Resolved: "The self-check runs again"}
 	}),
 	"watchdogs-silent": worded(func(o conditions.Observation) words {
 		return words{Headline: "The mesh's watchdogs stopped",
-			Needs: "restart the controller if this stays, " + FromMeshMCPServer,
+			Needs: "restart the controller if this stays.",
 			Explanation: "The watchdogs, which notice when something expected does not happen, have not run, so " +
 				"missed signals are not noticed.",
 			Resolved: "The watchdogs run again"}
@@ -680,32 +683,6 @@ func moduleNeeds(node string, rs []inventory.ResourceHealth) string {
 // authorised (to-be 46 phases 5 and 6).
 const FromMeshMCPServer = "from the mesh MCP server; this notification cannot do it."
 
-// releaseHeldWords are the plain words of updates held after a walk failed: which modules wait,
-// on which machines, and where the operator releases them (ADR 0258: a release is not an acknowledgement, so
-// no notification gives it). Raised with the modules and machines (backlogObservation); the kind's fallback
-// knows neither.
-func releaseHeldWords(modules, machines []string) words {
-	what := "Some module updates"
-	headline := "Updates wait for your release"
-	if len(modules) > 0 {
-		what = "Updates of " + namesWords(modules, 3)
-		if h := what + " wait for your release"; len(h) <= conditions.HeadlineMax {
-			headline = h
-		} else if h := fmt.Sprintf("%d module updates wait for your release", len(modules)); len(h) <= conditions.HeadlineMax {
-			headline = h
-		}
-	}
-	where := ""
-	if len(machines) > 0 {
-		where = " on " + namesWords(machines, 4)
-	}
-	return words{Headline: headline,
-		Needs: "release them " + FromMeshMCPServer,
-		Explanation: fmt.Sprintf("%s%s wait for a person to release them, because the last walk failed."+
-			" They are not delivered until then, and stay held if you leave them.", what, where),
-		Resolved: "Resolved: the held updates are released"}
-}
-
 // reloginNeeds is what an account waiting for its groups needs (ADR 0252).
 func reloginNeeds(node string) string {
 	return fmt.Sprintf("log out of %s completely and log in again, or restart it.", node)

cmd/mesh-controller/plain_words_test.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"regexp"
 	"strings"
 	"testing"
 	"time"
@@ -223,89 +222,3 @@ func TestDataLossOffersNoSilence(t *testing.T) {
 		}
 	}
 }
-
-// **Updates held after a failed release** (2026-10-08): the popup read "Needs you: release them, or leave
-// them held." — naming neither what waits nor where it is released. It names the modules and machines, and
-// the mesh MCP server.
-func TestUpdatesHeldNameWhatWaitsAndWhereItIsReleased(t *testing.T) {
-	saved := backlogNow
-	t.Cleanup(func() { backlogNow = saved })
-	backlogNow.held = "release-1791457717307061152 failed (failed its gate on g14); what waits is released again by a person"
-	backlogNow.waiting = map[string][]inventory.CarriedMove{
-		"shanks": {{Module: "openrazer"}},
-		"g14":    {{Module: "openrazer"}, {Module: "sensors"}},
-	}
-	got := backlogObservation()
-	if len(got) != 1 {
-		t.Fatalf("raised %d", len(got))
-	}
-	plainExample(t, got[0], "Updates of openrazer and sensors wait for your release",
-		"Needs you: release them from the mesh MCP server; this notification cannot do it. Updates of openrazer and "+
-			"sensors on g14 and shanks wait for a person to release them, because the last walk failed. "+
-			"They are not delivered until then, and stay held if you leave them.")
-}
-
-// **What held them is said in the glossary's words** (2026-10-08 review): the backlog is held after any
-// walk failed, not a release, and a "check" is a pull request's status. So the words say the walk failed,
-// and never that a release failed or a check did — with the modules and machines named or not.
-func TestUpdatesHeldSayTheWalkFailed(t *testing.T) {
-	for _, w := range []words{
-		releaseHeldWords([]string{"openrazer"}, []string{"g14"}),
-		releaseHeldWords(nil, nil),
-		plainWordings["release-held"](conditions.Observation{Scope: conditions.ScopeMesh, ID: "release"}),
-	} {
-		if !strings.Contains(w.Explanation, "because the last walk failed.") {
-			t.Errorf("does not say the walk failed: %q", w.Explanation)
-		}
-		for _, wrong := range []string{"release failed", "check"} {
-			if strings.Contains(w.Explanation, wrong) {
-				t.Errorf("says %q: %q", wrong, w.Explanation)
-			}
-		}
-	}
-}
-
-// mcpVerb is a need that opens with a verb only the mesh MCP server performs (ADR 0258 §1): release, stop,
-// start, restart, and a restore.
-var mcpVerb = regexp.MustCompile(`^(release|stop|start|restart|restore)\b`)
-
-// **A need no notification can answer says where it is answered** (ADR 0258 §1): every wording whose need
-// opens with a verb the mesh MCP server performs, and offers no action, ends with FromMeshMCPServer — the
-// kinds worded here for every subject shape, and those worded where they are raised. A new kind that misses
-// it fails here; release-held did (2026-10-08).
-func TestANeedNoNotificationAnswersNamesTheMeshMCPServer(t *testing.T) {
-	check := func(what string, w words) {
-		t.Helper()
-		if w.Needs == "" || len(w.Actions) > 0 || !mcpVerb.MatchString(w.Needs) {
-			return
-		}
-		if !strings.HasSuffix(w.Needs, FromMeshMCPServer) {
-			t.Errorf("%s needs %q without %q", what, w.Needs, FromMeshMCPServer)
-		}
-	}
-	subjects := []conditions.Observation{
-		{Scope: conditions.ScopeMachine, ID: "ace", Machine: "ace"},
-		{Scope: conditions.ScopeMachine, ID: "ace.immich.library", Machine: "ace"},
-		{Scope: conditions.ScopeModule, ID: "openrazer.g14", Machine: "g14"},
-		{Scope: conditions.ScopeDelivery, ID: "novox/hq@055550802096"},
-		{Scope: conditions.ScopeCore, ID: "controller.anchor", Machine: "anchor"},
-		{Scope: conditions.ScopeMesh, ID: "release", Also: []string{"g14"}},
-	}
-	for kind, fn := range plainWordings {
-		for _, s := range subjects {
-			for _, sev := range []conditions.Severity{conditions.Warning, conditions.Urgent} {
-				s.Kind, s.Severity, s.Resolver = kind, sev, conditions.ResolverOperator
-				check(kind+" about "+s.ID, fn(s))
-			}
-		}
-	}
-	check("a walk waiting", words{Needs: waitingNeeds(conditions.Urgent)})
-	check("a module's failed service", words{Needs: moduleNeeds("g14",
-		[]inventory.ResourceHealth{{Kind: link.KindUnit, Target: "openrazer-daemon.service"}})})
-	for _, state := range []string{"held", "ready", "failing"} {
-		_, _, _, needs, actions := stalledWords(stalledLine{ID: "novox/hq@055550802096", State: state, For: "36h"},
-			conditions.Observation{Resolver: conditions.ResolverOperator})
-		check("a delivery "+state, words{Needs: needs, Actions: actions})
-	}
-	check("updates held", releaseHeldWords([]string{"openrazer"}, []string{"g14"}))
-}

cmd/mesh-controller/plan.go

@@ -515,8 +515,9 @@ func sortedKeysOf(m map[string]string) []string {
 // 0163, rule 6), one line each: the machine is told everything else, and is told it was left out.
 func reportLeftOut(node string, declared sendable) {
 	for _, m := range declared.LeftOut {
-		fmt.Printf("%s: %s left out — what the machine holds for it is kept and its containers are "+
-			"untouched. %s\n", node, m, declared.leftOutWhy[m])
+		fmt.Printf("%s: %s left out — a setting stored for it cannot compose with its definition; "+
+			"what the machine holds for it is kept and its containers are untouched. %s\n",
+			node, m, declared.leftOutWhy[m])
 	}
 	// And whom it serves nothing, because their identity overflows what the provision keeps (ADR
 	// 0225): the machine is sent everything else, and the consumer is named.

cmd/mesh-controller/release.go

@@ -710,27 +710,15 @@ func backlogObservation() []conditions.Observation {
 	}
 	n := 0
 	var machines []string
-	seen := map[string]bool{}
-	var modules []string
 	for node, moves := range backlogNow.waiting {
 		n += len(moves)
 		machines = append(machines, node)
-		for _, mv := range moves {
-			if !seen[mv.Module] {
-				seen[mv.Module] = true
-				modules = append(modules, mv.Module)
-			}
-		}
 	}
 	sort.Strings(machines)
-	sort.Strings(modules)
-	o := conditions.Observation{Scope: conditions.ScopeMesh, ID: "release", Token: "held", Kind: "release-held",
-		Severity: conditions.Warning, Resolver: conditions.ResolverOperator, Also: machines,
+	return []conditions.Observation{{Scope: conditions.ScopeMesh, ID: "release", Token: "held", Kind: "release-held",
+		Severity: conditions.Warning, Resolver: conditions.ResolverOperator,
 		Summary: fmt.Sprintf("%d build move(s) on %s wait for a gate and are not released: %s — `upgrade backlog` lists "+
-			"them, `upgrade release-backlog --why …` releases them", n, strings.Join(machines, ", "), backlogNow.held)}
-	w := releaseHeldWords(modules, machines)
-	o.Headline, o.Explanation, o.Resolved, o.Needs = w.Headline, w.Explanation, w.Resolved, w.Needs
-	return []conditions.Observation{o}
+			"them, `upgrade release-backlog --why …` releases them", n, strings.Join(machines, ", "), backlogNow.held)}}
 }
 
 // backlogCommand is `upgrade backlog`, read-only, and `upgrade release-backlog --why`.

cmd/mesh-controller/seatverbs.go

@@ -764,12 +764,6 @@ func (a *verbArguments) commandLine() ([]string, error) {
 		// Every module's preferences, their defaults and each machine's value (novox/hq ADR 0262):
 		// the one interface for them, so no module builds a settings tool of its own. Asked for by
 		// name, or by naming no module, since a layer is always some module's.
-		if str("module") == "" && str("values") != "" {
-			return nil, errors.New("settings: a module is needed to set values; name it with module")
-		}
-		if str("module") == "" && on("clear") {
-			return nil, errors.New("settings: a module is needed to clear a layer; name it with module")
-		}
 		if list := str("list"); list != "" || str("module") == "" {
 			if list != "" && list != "preferences" {
 				return nil, fmt.Errorf("settings lists %q only; %q is not a listing", "preferences", list)

cmd/mesh-controller/settings_effective_test.go

@@ -37,14 +37,6 @@ func TestSettingsListPreferences(t *testing.T) {
 			t.Errorf("%v: %v %v, want %s", c.args, argv, err, c.want)
 		}
 	}
-	for args, want := range map[string]map[string]any{
-		"a module is needed to set values":    {"values": `{"width": 300}`},
-		"a module is needed to clear a layer": {"clear": "true"},
-	} {
-		if _, err := argvFor("settings", want); err == nil || !strings.Contains(err.Error(), args) {
-			t.Errorf("%v: %v, want %q", want, err, args)
-		}
-	}
 	if _, err := argvFor("settings", map[string]any{"list": "everything"}); err == nil {
 		t.Error("a listing other than preferences was taken")
 	}
@@ -77,33 +69,3 @@ func TestPreferencesSayEachMachinesValueAndItsSource(t *testing.T) {
 		t.Fatal("an empty listing")
 	}
 }
-
-// The listing over the real stores: each machine's value with its source; a machine names only the
-// modules on it; a machine the mesh does not know is refused (novox/hq ADR 0262).
-func TestPreferencesListedFromTheStores(t *testing.T) {
-	open := aMesh(t)
-	ctx := t.Context()
-	register(t, open, catalogue.Manifest{Module: "notes", Version: "1",
-		Settings: map[string]catalogue.SettingDeclaration{
-			"font-size": {Kind: catalogue.KindPreference, Default: float64(10), Why: "readable at 100 DPI"},
-		},
-		Resources: []map[string]any{{"id": "rc", "type": "file", "path": "/etc/notes.conf", "mode": "0644",
-			"content": "font = ${setting:font-size}\n"}}})
-	if _, err := assign(ctx, open, "laptop", "notes"); err != nil {
-		t.Fatal(err)
-	}
-	if err := open.inventory.SetSettings(ctx, "laptop", "notes", map[string]any{"font-size": float64(16)}); err != nil {
-		t.Fatal(err)
-	}
-	all := stdoutOf(t, func() error { return settingsCommand(ctx, []string{"preferences"}) })
-	if !strings.Contains(all, "notes (on laptop)") || !strings.Contains(all, "laptop: 16 (the node)") ||
-		!strings.Contains(all, "font-size, default 10: readable at 100 DPI") {
-		t.Fatalf("the listing:\n%s", all)
-	}
-	if got := stdoutOf(t, func() error { return settingsCommand(ctx, []string{"preferences", "--node", "anchor"}) }); got != "no module on anchor declares a preference\n" {
-		t.Fatalf("a machine without the module:\n%s", got)
-	}
-	if err := settingsCommand(ctx, []string{"preferences", "--node", "nowhere"}); err == nil {
-		t.Fatal("a machine the mesh does not know was answered")
-	}
-}

cmd/mesh-controller/unknown_fields.go

@@ -1,64 +0,0 @@
-package main
-
-import (
-	"context"
-	"fmt"
-	"sort"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-	"github.com/novox/mesh-controller/internal/inventory"
-)
-
-// A stored manifest with a key this controller does not know (novox/hq ADR 0262). The module is left out
-// of every machine's declaration by name; this is the loud half: a condition per module until the
-// controller is updated, or the module is registered again in a shape this controller reads.
-
-const (
-	sourceUnknownFields = "the catalogue"
-	kindUnknownField    = "unknown-field"
-)
-
-// unknownFieldObservations is one condition for each module of the catalogue whose stored manifest has
-// a key this controller does not know.
-func unknownFieldObservations(known map[string]catalogue.Manifest) []conditions.Observation {
-	names := make([]string, 0, len(known))
-	for name, m := range known {
-		if m.UnknownField() != "" {
-			names = append(names, name)
-		}
-	}
-	sort.Strings(names)
-	var out []conditions.Observation
-	for _, name := range names {
-		m := known[name]
-		out = append(out, conditions.Observation{
-			Scope: conditions.ScopeMesh, ID: name, Kind: kindUnknownField, Severity: conditions.Warning,
-			Resolver: conditions.ResolverOperator, Source: sourceUnknownFields,
-			Summary:     catalogue.UnknownFieldReason(m),
-			Said:        m.UnknownField(),
-			Headline:    name + " is left out until the controller is updated",
-			Explanation: name + " uses a field this controller does not know, so it is left out of every machine it is on, and nothing of it changes there until the controller is updated.",
-			Needs:       "update the controller, or register " + name + " again at a version this controller knows.",
-			Resolved:    "the controller reads " + name + " again",
-		})
-	}
-	return out
-}
-
-// raiseUnknownFields raises those conditions and clears the ones no longer true, on the controller's
-// tick. A catalogue that could not be read raises and clears nothing: "none" is not said for "could not
-// tell" (ADR 0227 rule 4).
-func raiseUnknownFields(ctx context.Context, inv *inventory.Inventory) []string {
-	if conditionsFrom == nil {
-		return nil
-	}
-	known, err := inv.Catalogue(ctx)
-	if err != nil {
-		return []string{fmt.Sprintf("the catalogue could not be read to say which modules it cannot read: %v", err)}
-	}
-	if err := conditionsFrom.Reconcile(ctx, sourceUnknownFields, unknownFieldObservations(known)); err != nil {
-		return []string{fmt.Sprintf("the modules with a field this controller does not know could not be kept as conditions: %v", err)}
-	}
-	return nil
-}

cmd/mesh-controller/unknown_fields_test.go

@@ -1,50 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"testing"
-
-	"github.com/novox/mesh-controller/internal/catalogue"
-	"github.com/novox/mesh-controller/internal/conditions"
-)
-
-// A module whose stored manifest has a key this controller does not know is a condition, in plain
-// words, until it is read again; every other module raises nothing (novox/hq ADR 0262).
-func TestAModuleWithAnUnknownFieldIsACondition(t *testing.T) {
-	var later, now catalogue.Manifest
-	if err := json.Unmarshal([]byte(`{"module": "dunst", "version": "2", "settings": {}, "a-field-from-later": 1}`), &later); err != nil {
-		t.Fatal(err)
-	}
-	if err := json.Unmarshal([]byte(`{"module": "xorg", "version": "1"}`), &now); err != nil {
-		t.Fatal(err)
-	}
-	observed := unknownFieldObservations(map[string]catalogue.Manifest{"dunst": later, "xorg": now})
-	if len(observed) != 1 || observed[0].ID != "dunst" || observed[0].Kind != kindUnknownField {
-		t.Fatalf("observed: %+v", observed)
-	}
-	o := observed[0]
-	if why, ok := conditions.PlainWords(conditions.Words{Headline: o.Headline, Explanation: o.Explanation,
-		Resolved: o.Resolved, Needs: o.Needs}); !ok {
-		t.Fatalf("not plain: %s", why)
-	}
-
-	k, _ := withConditionsInMemory(t)
-	if err := k.Reconcile(t.Context(), sourceUnknownFields, observed); err != nil {
-		t.Fatal(err)
-	}
-	if _, open, _ := k.Get(t.Context(), o.Key()); !open {
-		t.Fatal("not raised")
-	}
-	if err := k.Reconcile(t.Context(), sourceUnknownFields, unknownFieldObservations(map[string]catalogue.Manifest{"xorg": now})); err != nil {
-		t.Fatal(err)
-	}
-	still, err := k.Open(t.Context())
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, c := range still {
-		if c.Key == o.Key() {
-			t.Fatalf("not cleared once read again: %+v", c)
-		}
-	}
-}

internal/catalogue/data.go

@@ -159,7 +159,7 @@ func (b *DataBackup) UnmarshalJSON(raw []byte) error {
 	dec := json.NewDecoder(bytes.NewReader(raw))
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&full); err != nil {
-		return fmt.Errorf("a data item's backup is \"copy\", \"none\" or {dump, into}: %w", typedUnknown(err))
+		return fmt.Errorf("a data item's backup is \"copy\", \"none\" or {dump, into}: %w", err)
 	}
 	*b = DataBackup{Dump: full.Dump, Into: full.Into}
 	return nil

internal/catalogue/declaration.go

@@ -318,10 +318,6 @@ func (e *NotMadeError) Error() string {
 func (r Resolution) LeftOut(settings SettingsBy, adopted bool) map[string]string {
 	out := map[string]string{}
 	for _, m := range r.Modules {
-		if why := UnknownFieldReason(m); why != "" {
-			out[m.Module] = why
-			continue
-		}
 		if err := JudgeSettings(m, settings[m.Module], adopted); err != nil {
 			out[m.Module] = err.Error()
 		}

internal/catalogue/manifest.go

@@ -197,7 +197,7 @@ func (i *OfferIdentity) UnmarshalJSON(raw []byte) error {
 	dec := json.NewDecoder(bytes.NewReader(raw))
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&full); err != nil {
-		return fmt.Errorf("an offer's identity is false or {max, in}: %w", typedUnknown(err))
+		return fmt.Errorf("an offer's identity is false or {max, in}: %w", err)
 	}
 	*i = OfferIdentity{Max: full.Max, In: full.In}
 	return nil
@@ -316,7 +316,7 @@ func (o *Offer) UnmarshalJSON(raw []byte) error {
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&full); err != nil {
 		return fmt.Errorf("a provided name is either a string or {name, scope, credential, reach, identity, "+
-			"keeps-consumer-data}: %w", typedUnknown(err))
+			"keeps-consumer-data}: %w", err)
 	}
 	o.Name, o.Scope, o.Credential, o.Reach, o.Identity = full.Name, full.Scope, full.Credential, full.Reach, full.Identity
 	o.KeepsConsumerData = full.Keeps
@@ -465,10 +465,9 @@ type Manifest struct {
 	// stays refused by name until a layer sets it. The mesh's layer, then the node's, override it.
 	Settings map[string]SettingDeclaration `json:"settings,omitempty"`
 
-	// unknown is the first key this manifest has that this controller does not know, at any depth, when
-	// it was read from the store (novox/hq ADR 0262): a manifest a newer controller registered.
-	// ParseManifest refuses it; the store's catalogue still loads, and the module is left out of every
-	// machine's declaration by name until the controller is updated (LeftOut).
+	// unknown is the first key this manifest has that this controller does not know, when it was read
+	// leniently (novox/hq ADR 0262): a stored manifest written for a newer controller. ParseManifest
+	// refuses it; reading the stored catalogue keeps the rest of the manifest.
 	unknown string
 
 	// Data is every kind of data this module keeps — its own, by directory, and what it keeps for
@@ -1280,19 +1279,13 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 	var fields manifestFields
 	unknown := ""
 	if err := decoder.Decode(&fields); err != nil {
-		if asUnknownField(err) == nil {
+		if !strings.HasPrefix(err.Error(), "json: unknown field ") {
 			return err
 		}
-		// Read without it where the key is at the top; where it is inside a block, the block's own
-		// decoder refuses it again, and the manifest keeps its name and version alone. Either way the
-		// module is left out of every declaration by name (LeftOut), so nothing runs on a part-read
-		// manifest.
 		unknown = err.Error()
 		fields = manifestFields{}
-		if json.Unmarshal(rest, &fields) != nil {
-			fields = manifestFields{}
-			_ = json.Unmarshal(keys["module"], &fields.Module)
-			_ = json.Unmarshal(keys["version"], &fields.Version)
+		if err := json.Unmarshal(rest, &fields); err != nil {
+			return err
 		}
 	}
 	*m = Manifest(fields)
@@ -2486,7 +2479,7 @@ func (o *OwnSecrets) UnmarshalJSON(raw []byte) error {
 		dec := json.NewDecoder(bytes.NewReader(body))
 		dec.DisallowUnknownFields()
 		if err := dec.Decode(&long); err != nil {
-			return fmt.Errorf("own-secrets.%s: a path, or {\"path\", \"taken\", \"issued-by\"}: %w", name, typedUnknown(err))
+			return fmt.Errorf("own-secrets.%s: a path, or {\"path\", \"taken\", \"issued-by\"}: %w", name, err)
 		}
 		out[name] = OwnSecret{Path: long.Path, Taken: long.Taken, IssuedBy: long.IssuedBy}
 	}

internal/catalogue/setting_defaults.go

@@ -46,54 +46,32 @@ var meshWords = map[string]bool{
 	PlacesSetting: true, AccessesSetting: true, NetworksSetting: true,
 }
 
-// operatorsOwn are the words that, as what a key's name is about, say its value is the operator's and
-// never a preference: a default for one would be the literal ADR 0112 removed from definitions.
+// operatorsOwn are words that, as a whole word of a key's name, say its value is the operator's and
+// never a preference: a default for one would be the literal ADR 0112 removed from definitions. Whole
+// words, split at dashes, underscores and dots, so `max-tokens`, `show-hostname` and `mailbox-size` are
+// preferences and `api-token`, `host` and `mail-domain` are not.
 var operatorsOwn = map[string]bool{
-	"domain": true, "host": true, "hostname": true, "servername": true, "fqdn": true, "zone": true,
-	"realm": true, "tenant": true, "site": true, "timezone": true,
-	"issuer": true, "url": true, "uri": true, "webhook": true, "origin": true, "dsn": true,
-	"ip": true, "ipv4": true, "ipv6": true,
+	"domain": true, "host": true, "fqdn": true, "zone": true, "realm": true, "tenant": true,
+	"issuer": true, "url": true, "uri": true, "webhook": true, "origin": true, "dsn": true, "ip": true,
 	"email": true, "mail": true, "phone": true, "address": true,
 	"identity": true, "login": true, "user": true, "username": true, "account": true, "owner": true,
 	"uid": true, "gid": true, "puid": true, "pgid": true,
 	"password": true, "pass": true, "passwd": true, "passphrase": true, "secret": true, "token": true,
-	"key": true, "apikey": true, "bearer": true, "cert": true, "credential": true,
+	"key": true, "credential": true,
 }
 
-// operatorsCompounds are names of two words that are the operator's though neither word alone says so
-// at the end of a key: a client's identifier, and a name the world knows a site or server by.
-var operatorsCompounds = map[string]bool{
-	"client-id": true, "site-name": true, "server-name": true, "public-name": true, "smtp-relay": true,
-}
-
-// aboutAnAmount are first words that make a key about how many or whether, never about whom:
-// `max-tokens` is a number, `show-hostname` a switch.
-var aboutAnAmount = map[string]bool{
-	"max": true, "min": true, "num": true, "count": true, "show": true, "hide": true, "enable": true,
-	"disable": true, "use": true, "allow": true,
-}
-
-// operatorsWord is what in a key's name says its value is the operator's, or "". A key is about its
-// last word — `url-timeout` is a timeout, `user-agent` an agent, `mail-domain` a domain — or its last two
-// as one of operatorsCompounds. A plural is read as its singular.
+// operatorsWord is the word of a key's name that says its value is the operator's, or "".
 func operatorsWord(key string) string {
 	words := strings.FieldsFunc(key, func(r rune) bool { return r == '-' || r == '_' || r == '.' })
-	if len(words) == 0 || (len(words) > 1 && aboutAnAmount[words[0]]) {
-		return ""
-	}
 	for i, w := range words {
-		if !operatorsOwn[w] && strings.HasSuffix(w, "s") && operatorsOwn[strings.TrimSuffix(w, "s")] {
-			words[i] = strings.TrimSuffix(w, "s")
+		if operatorsOwn[w] {
+			return w
 		}
-	}
-	if n := len(words); n > 1 {
-		if pair := words[n-2] + "-" + words[n-1]; operatorsCompounds[pair] {
-			return pair
+		// An identifier a client is known by: `client-id`, `oauth-client-id`.
+		if w == "client" && i+1 < len(words) && words[i+1] == "id" {
+			return "client-id"
 		}
 	}
-	if last := words[len(words)-1]; operatorsOwn[last] {
-		return last
-	}
 	return ""
 }
 

internal/catalogue/setting_defaults_test.go

@@ -218,24 +218,18 @@ func TestANodeCalledDefaultIsANodesLayer(t *testing.T) {
 	}
 }
 
-// The operator's own value is told by what a key's name is about: its last word, or its last two as
-// a known compound; a plural as its singular; and never a number or a switch.
-func TestAKeyIsTheOperatorsByWhatItIsAbout(t *testing.T) {
+// The operator's own value is told by a whole word of the key's name, not by a part of one.
+func TestAKeyIsTheOperatorsByAWholeWord(t *testing.T) {
 	for _, key := range []string{"max-tokens", "show-hostname", "ghost-opacity", "users-per-page", "mailbox-size",
-		"font-size", "width", "keyboard-delay", "ipv6-preferred", "client-width", "user-agent", "url-timeout",
-		"site-title", "cert-renewal-days", "name", "font-name"} {
+		"font-size", "width", "keyboard-delay", "ipv6-preferred", "client-width"} {
 		if w := operatorsWord(key); w != "" {
 			t.Errorf("%s read as the operator's (%s)", key, w)
 		}
 	}
-	for key, word := range map[string]string{"mail-domain": "domain", "api-key": "key", "admin-password": "password",
+	for key, word := range map[string]string{"mail-domain": "mail", "site-domain": "domain", "api-key": "key", "admin-password": "password",
 		"oauth-client-id": "client-id", "db-dsn": "dsn", "public-ip": "ip", "puid": "puid", "dns-zone": "zone",
 		"webhook": "webhook", "notify_phone": "phone", "cors.origin": "origin", "smtp-pass": "pass",
-		"backup-passphrase": "passphrase", "data-owner": "owner", "fqdn": "fqdn", "tenant": "tenant", "host": "host",
-		"allowed-hosts": "host", "admin-emails": "email", "tokens": "token", "hostname": "hostname",
-		"apikey": "apikey", "servername": "servername", "tls-cert": "cert", "site": "site", "timezone": "timezone",
-		"bearer": "bearer", "bind-ipv4": "ipv4", "listen-ipv6": "ipv6", "site-name": "site-name",
-		"server-name": "server-name", "public-name": "public-name", "smtp-relay": "smtp-relay"} {
+		"backup-passphrase": "passphrase", "data-owner": "owner", "fqdn": "fqdn", "tenant": "tenant", "host": "host"} {
 		if w := operatorsWord(key); w != word {
 			t.Errorf("%s: read %q, want %q", key, w, word)
 		}
@@ -285,50 +279,22 @@ func TestADefaultFillsAContributionAndAServedFactButNotALiteral(t *testing.T) {
 	}
 }
 
-// A stored manifest with a key this controller does not know, at the top or inside any block, is read
-// and its module is left out of every declaration by name; the rest of the catalogue is read; the module
-// check refuses it. One case per block whose decoder wraps the decoder's words in its own.
-func TestAStoredManifestWithAnUnknownKeyIsLeftOutAndRegistrationRefusesIt(t *testing.T) {
-	for where, raw := range map[string]string{
-		"the top":             `{"module": "later", "version": "2", "a-field-from-later": {"x": 1}}`,
-		"a state":             `{"module": "later", "version": "2", "state": [{"name": "s", "a-field-from-later": 1}]}`,
-		"a provided name":     `{"module": "later", "version": "2", "provides": [{"name": "p", "a-field-from-later": 1}]}`,
-		"an offer's identity": `{"module": "later", "version": "2", "provides": [{"name": "p", "identity": {"in": "x", "a-field-from-later": 1}}]}`,
-		"a backup":            `{"module": "later", "version": "2", "data": {"own": [{"id": "d", "path": "${dir:d}", "class": "valuable", "backup": {"dump": "x", "into": "y", "a-field-from-later": 1}}]}}`,
-		"an own secret":       `{"module": "later", "version": "2", "own-secrets": {"s": {"path": "/x", "a-field-from-later": 1}}}`,
-		"a seat's verb":       `{"module": "later", "version": "2", "seats": [{"name": "later-seat", "serves": [{"name": "v", "a-field-from-later": 1}]}]}`,
-	} {
-		var m Manifest
-		if err := json.Unmarshal([]byte(raw), &m); err != nil {
-			t.Errorf("%s: the stored manifest was not read: %v", where, err)
-			continue
-		}
-		if m.Module != "later" || m.Version != "2" || !strings.Contains(m.UnknownField(), `"a-field-from-later"`) {
-			t.Errorf("%s: read as %q %q, unknown %q", where, m.Module, m.Version, m.UnknownField())
-			continue
-		}
-		if where != "the top" && !strings.Contains(m.UnknownField(), ": json: unknown field") {
-			t.Errorf("%s: the block's decoder did not say it: %q", where, m.UnknownField())
-		}
-		left := Resolution{Node: "laptop", Modules: []Manifest{m, notifier()}}.LeftOut(nil, false)
-		if why := left["later"]; !strings.Contains(why, "uses a field this controller does not know") ||
-			!strings.Contains(why, "a-field-from-later") {
-			t.Errorf("%s: not left out by name: %v", where, left)
-		}
-		if _, notifierLeft := left["notifier"]; notifierLeft {
-			t.Errorf("%s: another module was left out with it: %v", where, left)
-		}
-		if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), "a-field-from-later") {
-			t.Errorf("%s: the module check took it: %v", where, err)
-		}
+// A stored manifest with a key this controller does not know is read without it, and said; the module
+// check still refuses it.
+func TestAStoredManifestWithAnUnknownKeyIsReadAndRegistrationRefusesIt(t *testing.T) {
+	raw := []byte(`{"module": "later", "version": "1", "tools": ["later_x"], "a-field-from-later": {"x": 1}}`)
+	var m Manifest
+	if err := json.Unmarshal(raw, &m); err != nil {
+		t.Fatalf("a stored manifest with an unknown key was not read: %v", err)
+	}
+	if m.Module != "later" || len(m.Tools) != 1 || !strings.Contains(m.UnknownField(), `"a-field-from-later"`) {
+		t.Fatalf("read as %+v, unknown %q", m, m.UnknownField())
+	}
+	if _, err := ParseManifest(raw); err == nil || !strings.Contains(err.Error(), `unknown field "a-field-from-later"`) {
+		t.Fatalf("registration took it: %v", err)
 	}
 	var known Manifest
-	if err := json.Unmarshal([]byte(`{"module": "now", "state": [{"name": "s"}]}`), &known); err != nil || known.UnknownField() != "" {
+	if err := json.Unmarshal([]byte(`{"module": "now"}`), &known); err != nil || known.UnknownField() != "" {
 		t.Fatalf("a known manifest: %v %q", err, known.UnknownField())
 	}
-	// A malformed manifest is still refused: only an unknown key is read past.
-	var bad Manifest
-	if err := json.Unmarshal([]byte(`{"module": "bad", "state": [{"name": 3}]}`), &bad); err == nil {
-		t.Fatal("a malformed stored manifest was read")
-	}
 }

internal/catalogue/state.go

@@ -49,7 +49,7 @@ func (s *StateDeclaration) UnmarshalJSON(raw []byte) error {
 	dec := json.NewDecoder(bytes.NewReader(trimmed))
 	dec.DisallowUnknownFields()
 	if err := dec.Decode(&full); err != nil {
-		return fmt.Errorf("a state is either a name or {name, history, ttl-seconds, per-machine}: %w", typedUnknown(err))
+		return fmt.Errorf("a state is either a name or {name, history, ttl-seconds, per-machine}: %w", err)
 	}
 	*s = StateDeclaration(full)
 	return nil

internal/catalogue/unknown_field.go

@@ -1,58 +0,0 @@
-package catalogue
-
-import (
-	"errors"
-	"regexp"
-)
-
-// A key this controller does not know, in a manifest (novox/hq ADR 0262).
-//
-// Registration refuses it, as it always has. A manifest the store already holds was registered by a newer
-// controller, and is read by this one after a rollback: refusing it there failed the whole catalogue, and
-// with it every plan and every send. Dropping the key silently would be worse — a module running without
-// something its manifest says. So the manifest is read, the module is left out of every machine's
-// declaration by name, and the controller raises a condition until it is updated.
-
-// UnknownFieldError is a key a manifest has that this controller does not know, wherever it is: at the
-// top of the manifest or inside a block (a state, an offer, a data item's backup, an own secret, a verb).
-// Typed, because the blocks' decoders wrap the decoder's words in their own.
-type UnknownFieldError struct {
-	Field string
-	err   error
-}
-
-func (e *UnknownFieldError) Error() string { return e.err.Error() }
-func (e *UnknownFieldError) Unwrap() error { return e.err }
-
-// unknownFieldText is how the JSON decoder words a key its target does not have.
-var unknownFieldText = regexp.MustCompile(`^json: unknown field "([^"]*)"$`)
-
-// typedUnknown is err as an UnknownFieldError when it is the decoder refusing an unknown key, else err.
-func typedUnknown(err error) error {
-	if err == nil {
-		return nil
-	}
-	if m := unknownFieldText.FindStringSubmatch(err.Error()); m != nil {
-		return &UnknownFieldError{Field: m[1], err: err}
-	}
-	return err
-}
-
-// asUnknownField is the unknown key err is about, at any depth, or nil.
-func asUnknownField(err error) *UnknownFieldError {
-	var u *UnknownFieldError
-	if errors.As(typedUnknown(err), &u) {
-		return u
-	}
-	return nil
-}
-
-// UnknownFieldReason is why a module whose stored manifest has a key this controller does not know is
-// left out of a machine's declaration, or "" when it has none.
-func UnknownFieldReason(m Manifest) string {
-	if m.unknown == "" {
-		return ""
-	}
-	return m.Module + " uses a field this controller does not know (" + m.unknown + "); it is left out " +
-		"until the controller is updated (novox/hq ADR 0262)"
-}

internal/catalogue/verbs.go

@@ -56,7 +56,7 @@ func (v *Verb) UnmarshalJSON(raw []byte) error {
 	decoder := json.NewDecoder(bytes.NewReader(trimmed))
 	decoder.DisallowUnknownFields()
 	if err := decoder.Decode(&p); err != nil {
-		return fmt.Errorf("a served verb is a name or {name, description, input, output}: %w", typedUnknown(err))
+		return fmt.Errorf("a served verb is a name or {name, description, input, output}: %w", err)
 	}
 	if p.Name == "" {
 		return fmt.Errorf("a served verb has no name: %s", trimmed)

internal/inventory/catalogue.go

@@ -20,9 +20,8 @@ import (
 var noted sync.Map
 
 // noteUnknown says, once per module and key, that a stored manifest has a key this controller does not
-// know (novox/hq ADR 0262). A manifest registered under a newer controller is read by an older one after
-// a rollback; refusing it here failed the whole catalogue. The module is left out of every machine by name
-// (catalogue.LeftOut), and the controller's tick raises a condition for it.
+// know and that it was read without it (novox/hq ADR 0262). A manifest registered under a newer
+// controller is read by an older one after a rollback; refusing it here failed the whole catalogue.
 func noteUnknown(m catalogue.Manifest) {
 	u := m.UnknownField()
 	if u == "" {
@@ -31,9 +30,8 @@ func noteUnknown(m catalogue.Manifest) {
 	if _, said := noted.LoadOrStore(m.Module+"\x00"+u, true); said {
 		return
 	}
-	log.Printf("the stored manifest of %s has a key this controller does not know (%s): a newer controller "+
-		"registered it, and %s is left out of every machine until this controller is updated (novox/hq ADR 0262)",
-		m.Module, u, m.Module)
+	log.Printf("the stored manifest of %s has a key this controller does not know (%s); read without it — "+
+		"a newer controller registered it (novox/hq ADR 0262)", m.Module, u)
 }
 
 // ErrNoSuchModule is what the mesh says about a module it has never been told about.

internal/inventory/unknown_field_test.go

@@ -1,34 +0,0 @@
-package inventory
-
-import (
-	"strings"
-	"testing"
-)
-
-// A manifest a newer controller registered, with a key this one does not know, does not stop the
-// catalogue from loading: it is read, marked, and every other module is read as before (novox/hq ADR 0262).
-func TestTheCatalogueLoadsAroundAManifestWithAnUnknownKey(t *testing.T) {
-	inv := fresh(t)
-	if err := inv.RegisterModule(t.Context(), manifest("thing", nil, nil), Source{}); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := inv.store.Pool().Exec(t.Context(),
-		`insert into module (name, manifest) values ($1, $2)`, "later",
-		`{"module": "later", "version": "2", "state": [{"name": "s", "a-field-from-later": 1}]}`); err != nil {
-		t.Fatal(err)
-	}
-	known, err := inv.Catalogue(t.Context())
-	if err != nil {
-		t.Fatalf("one manifest with an unknown key failed the whole catalogue: %v", err)
-	}
-	if known["thing"].Module != "thing" || known["thing"].UnknownField() != "" {
-		t.Fatalf("the other module: %+v", known["thing"])
-	}
-	if !strings.Contains(known["later"].UnknownField(), "a-field-from-later") {
-		t.Fatalf("the newer manifest is not marked: %q", known["later"].UnknownField())
-	}
-	entries, err := inv.Catalogued(t.Context())
-	if err != nil || len(entries) < 2 {
-		t.Fatalf("the listing: %v %d", err, len(entries))
-	}
-}