Merge origin/main into feat/335, and pin mesh-host at #98's new head

internal/catalogue/adoption.go

@@ -87,6 +87,11 @@ func Openings(rules []Rule, foundation []int, published map[string]map[int]int)
 			widen(key{rule.Protocol, rule.Port}, OpeningFromEverywhere)
 		case FromMesh:
 			widen(key{rule.Protocol, rule.Port}, OpeningFromMesh)
+		case FromLocalNetwork:
+			// The private network's part only (novox/hq ADR 0340). An adopted node's found firewall
+			// stays, and it is what admits the machine's local network; an opening has no word for a
+			// local network, and widening it to everywhere would open the port to the internet.
+			widen(key{rule.Protocol, rule.Port}, OpeningFromMesh)
 		}
 	}
 	for _, port := range foundation {

internal/catalogue/bound.go

@@ -127,6 +127,7 @@ func boundNeed(n Needed, bound Chosen, catalogue map[string]Manifest, node Node,
 		identity = pm.IdentityBoundOf(n.Name)
 	}
 	held.From, held.At, held.Module, held.Serves, held.Identity = p.Node, p.At, p.Module, p.Serves, identity
+	held.LeftOut = p.LeftOut
 	return held, true, ""
 }
 

internal/catalogue/bound_into_files.go

@@ -26,21 +26,10 @@ import (
 // serves — whose keys are agreed by the requirement's name, not by this file.
 
 // bound is where a module says a value from one of its bindings belongs:
-// ${bound:<provision>.<key>}.
-var bound = regexp.MustCompile(`\$\{bound:([a-z0-9][a-z0-9.-]*[a-z0-9]):([a-z0-9][a-z0-9_-]*)\}`)
-
-// boundUsed are the (provision, key) pairs a file's content asks for, first appearance first.
-func boundUsed(content string) [][2]string {
-	var used [][2]string
-	seen := map[string]bool{}
-	for _, m := range bound.FindAllStringSubmatch(content, -1) {
-		if key := m[1] + ":" + m[2]; !seen[key] {
-			seen[key] = true
-			used = append(used, [2]string{m[1], m[2]})
-		}
-	}
-	return used
-}
+// ${bound:<provision>:<key>}, and for an optional requirement the value it takes while absent,
+// ${bound:<provision>:<key>|default:<value>} (novox/hq ADR 0330 §4). A default is never empty: an
+// absent requirement is never rendered as an empty string.
+var bound = regexp.MustCompile(`\$\{bound:([a-z0-9][a-z0-9.-]*[a-z0-9]):([a-z0-9][a-z0-9_-]*)(?:\|default:([^}\n]+))?\}`)
 
 // knownFor is everything a module may name from one of its bindings.
 //
@@ -125,7 +114,11 @@ func plainly(value any) string {
 // serve, is refused. Left as it was, the literal `${bound:x:y}` would be written into a
 // configuration file and read as a value — a connection to a host called `${bound:x:y}`, failing
 // somewhere that names neither the module nor the mesh.
-func boundInto(resource map[string]any, known map[string]map[string]string, module string) error {
+//
+// **An optional requirement left absent takes the default its placeholder names** (novox/hq ADR
+// 0330 §4), and one that names none is refused rather than rendered empty. The module check refuses
+// that already; this is the same rule where the file is made, for a manifest registered before it.
+func boundInto(resource map[string]any, known map[string]map[string]string, module string, absent map[string]bool) error {
 	if fmt.Sprint(resource["type"]) != "file" {
 		return nil
 	}
@@ -133,24 +126,43 @@ func boundInto(resource map[string]any, known map[string]map[string]string, modu
 	if !ok {
 		return nil
 	}
-	for _, pair := range boundUsed(content) {
-		provision, key := pair[0], pair[1]
+	var refused error
+	filled := bound.ReplaceAllStringFunc(content, func(token string) string {
+		if refused != nil {
+			return token
+		}
+		m := bound.FindStringSubmatch(token)
+		provision, key, fallback := m[1], m[2], m[3]
 		values, has := known[provision]
 		if !has {
-			return fmt.Errorf(
+			if absent[provision] {
+				if fallback != "" {
+					return fallback
+				}
+				refused = fmt.Errorf(
+					"%s has a file that says ${bound:%s:%s}, and %q is optional and absent here: it names no "+
+						"value for then (${bound:%s:%s|default:<value>}), so it would be written empty "+
+						"(novox/hq ADR 0330 §4)", module, provision, key, provision, provision, key)
+				return token
+			}
+			refused = fmt.Errorf(
 				"%s has a file that says ${bound:%s:%s}, and %s does not require %q. It may name %s",
 				module, provision, key, module, provision, orNothing(namesOfBindings(known)))
+			return token
 		}
 		value, said := values[key]
 		if !said {
-			return fmt.Errorf(
+			refused = fmt.Errorf(
 				"%s asks its %s binding for %q, and what answers it says %s",
 				module, provision, key, orNothing(namesOfKeys(values)))
+			return token
 		}
-		resource["content"] = strings.ReplaceAll(
-			content, fmt.Sprintf("${bound:%s:%s}", provision, key), value)
-		content = resource["content"].(string)
+		return value
+	})
+	if refused != nil {
+		return refused
 	}
+	resource["content"] = filled
 	return nil
 }
 

internal/catalogue/consumer_into_serves.go

@@ -135,6 +135,9 @@ func CheckServes(m Manifest) []string {
 		for _, key := range sortedAnyKeys(m.Serves[provision]) {
 			text, ok := m.Serves[provision][key].(string)
 			if !ok {
+				// A provider's own name is filled only in a value of its own (novox/hq ADR 0346): one
+				// nested in a list or an object would be served as the placeholder, unsaid.
+				problems = append(problems, nestedOwnNames(m, provision, key, m.Serves[provision][key])...)
 				continue
 			}
 			// A probe identity, because what is checked is the shape of the statement and not
@@ -143,6 +146,8 @@ func CheckServes(m Manifest) []string {
 				problems = append(problems, fmt.Sprintf(
 					"%s serves %s, and the value it serves as %q %s", m.Module, provision, key, err))
 			}
+			// And the provider's own names it may serve (novox/hq ADR 0346).
+			problems = append(problems, checkServedOwnNames(m, provision, key, text)...)
 			// A label longer than DNS keeps is not truncated here (asDNSLabel), so the offer's own
 			// bound has to keep the identity inside one (ADR 0225).
 			if strings.Contains(text, "${consumer:as:dns}") {

internal/catalogue/declaration.go

@@ -135,6 +135,12 @@ type Rendering struct {
 	// composes no filter for it rather than writing a rule around a link with no name.
 	OutwardLinks []string
 
+	// LocalNetworks is this machine's local networks (novox/hq ADR 0340): the networks it reported on a
+	// link facing outside it that lie wholly in a private range (JudgeLocalNetworks), which a port
+	// reached from `local-network` is admitted from beside the private network. Empty when it reported
+	// none, and the rule set then says so rather than widening the port or dropping it.
+	LocalNetworks []string
+
 	// TunnelInterface is the interface the mesh's private network runs on, named here rather than
 	// imported because the overlay package rests on this one. Traffic arriving on it is the mesh's,
 	// not this machine's own guest, so the filter admits it only by a rule.
@@ -532,8 +538,8 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 				"`node show %s` says whether it has. Until then %s is not sent, and the machine "+
 				"keeps the filter it has", r.Node, r.Node, filters)
 	}
-	filtering := AsNftables(rules, with.Mesh, r.PublicDomain != "", with.Foundation,
-		with.OutwardLinks, with.TunnelInterface)
+	filtering := AsNftablesWithLocal(rules, with.Mesh, r.PublicDomain != "", with.Foundation,
+		with.OutwardLinks, with.TunnelInterface, with.LocalNetworks)
 
 	// **A variable two modules set is refused whether or not anything places it** (novox/hq ADR
 	// 0203 §5): the account has one environment, and a machine whose holder arrives later should not
@@ -855,6 +861,11 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 		// An account depends on nothing the mesh computes.
 		accounts, rest := accountsFirst(resources)
 		resources = append(append(accounts, first...), rest...)
+		// **A file delivered only while its optional requirement is bound is left out while it is
+		// absent** (novox/hq ADR 0330 §5), and the field is dropped from the rest: the node-engine
+		// parses strictly and knows no such field.
+		absent := r.AbsentFor(m.Module)
+		resources = withoutAbsent(resources, absent)
 
 		// No container is given the mesh's names (novox/hq ADR 0148). It used to be: every
 		// container got the whole roster as `--add-host` entries at creation, and a name that
@@ -1018,7 +1029,7 @@ func (r Resolution) compose(with Rendering, owner map[string]string,
 			// **Substituted here, not on the machine.** A bound value is not secret — the mesh
 			// holds it in the clear — so there is nothing for the host to be the only witness of,
 			// and sending it already filled in means the host learns no new field.
-			if err := boundInto(copied, known, m.Module); err != nil {
+			if err := boundInto(copied, known, m.Module, absent); err != nil {
 				return nil, err
 			}
 			// And what the module could not have written: the machine it turned out to be
@@ -2035,7 +2046,13 @@ func (r Resolution) servedOnThisMachine(provision string, with Rendering) (map[s
 		if err != nil {
 			return nil, false, fmt.Errorf("%s serving %s: %w", m.Module, provision, err)
 		}
-		return settled, true, nil
+		// And the provider's own names, as this machine composes them (novox/hq ADR 0346); one it does
+		// not compose leaves its key out, said by the plan on this machine (ServedLeftOut).
+		named, _, err := r.ServedOwnNames(m, provision, settled, WithDefaults(m, with.Settings[m.Module]))
+		if err != nil {
+			return nil, false, fmt.Errorf("%s serving %s: %w", m.Module, provision, err)
+		}
+		return named, true, nil
 	}
 	return nil, false, nil
 }
@@ -2553,8 +2570,8 @@ func onlyGroups(r map[string]any) bool {
 
 // generatedHere is what each computed module's generator answers for this machine, by module —
 // absent for a module whose machine is not yet part of what it generates — held to the rule every
-// module is held to: no two modules on a machine declare one path, unit, name or package (novox/hq
-// issue 190, step 5; ADR 0222).
+// module is held to: no two modules on a machine declare one path, unit or name, nor one package present
+// and absent (novox/hq issue 190, step 5; ADR 0222, ADR 0303).
 //
 // Resolution checks the catalogue's manifests, and a computed module's manifest has none of the
 // resources it will declare — they exist only once its generator has answered for this machine,

internal/catalogue/filtering.go

@@ -152,9 +152,10 @@ func Exposure(m Manifest, layers []Layer) (map[int]string, error) {
 					m.Module, port)
 			}
 			source, ok := value.(string)
-			if !ok || (source != FromMesh && source != FromEverywhere && source != FromMachine) {
-				return nil, fmt.Errorf("%s exposes port %d as %v; it is %q, %q or %q",
-					m.Module, port, value, FromMesh, FromEverywhere, FromMachine)
+			if !ok || (source != FromMesh && source != FromEverywhere && source != FromMachine &&
+				source != FromLocalNetwork) {
+				return nil, fmt.Errorf("%s exposes port %d as %v; it is %q, %q, %q or %q",
+					m.Module, port, value, FromMesh, FromEverywhere, FromMachine, FromLocalNetwork)
 			}
 			out[port] = source
 		}
@@ -172,7 +173,9 @@ func Exposure(m Manifest, layers []Layer) (map[int]string, error) {
 // the appearance-of-restriction this mechanism exists to remove. The narrower rule's sources are
 // carried onto the wider one, so the module that wanted it is still named.
 func widest(rules []Rule) []Rule {
-	reach := map[string]int{FromMachine: 0, FromMesh: 1, FromEverywhere: 2}
+	// The local network is the private network and the machine's own local networks (novox/hq ADR
+	// 0340 §4), so it covers `mesh` and is covered by `anywhere`.
+	reach := map[string]int{FromMachine: 0, FromMesh: 1, FromLocalNetwork: 2, FromEverywhere: 3}
 	var out []Rule
 	for _, rule := range rules {
 		covered := false
@@ -232,6 +235,15 @@ const SSHPort = 22
 // any module asks for, and neither may be derived away.
 func AsNftables(rules []Rule, mesh []string, outward bool, foundation []int,
 	outwardLinks []string, tunnel string) string {
+	return AsNftablesWithLocal(rules, mesh, outward, foundation, outwardLinks, tunnel, nil)
+}
+
+// AsNftablesWithLocal is AsNftables with the machine's local networks: the networks it reported on a
+// link facing outside that count (novox/hq ADR 0340, JudgeLocalNetworks), which a rule from
+// `local-network` admits on its own port alone, beside the private network. None is not widened to
+// anywhere and not dropped silently: the rule set says the port wanted the local network and found none.
+func AsNftablesWithLocal(rules []Rule, mesh []string, outward bool, foundation []int,
+	outwardLinks []string, tunnel string, local []string) string {
 	// The links that are not this machine's own: the ones facing outside, and the mesh's tunnel.
 	// Traffic arriving on any of them is admitted only by a rule below; traffic arriving anywhere
 	// else is this machine's own guest and is not something the mesh has a position on.
@@ -394,6 +406,31 @@ func AsNftables(rules []Rule, mesh []string, outward bool, foundation []int,
 				b.WriteString(fmt.Sprintf("\t\tip6 saddr { %s } %s dport %d accept\n",
 					strings.Join(six, ", "), rule.Protocol, rule.Port))
 			}
+		case FromLocalNetwork:
+			// The private network and the machine's own local networks, on this port alone (novox/hq
+			// ADR 0340 §5).
+			four, six := byFamily(mesh)
+			lfour, lsix := byFamily(local)
+			four, six = append(four, lfour...), append(six, lsix...)
+			if len(lfour) == 0 && len(lsix) == 0 {
+				b.WriteString(fmt.Sprintf(
+					"\t\t# %s/%d wanted the local network, and this machine reported no private network "+
+						"on a link facing outside; admitted from no local network\n", rule.Protocol, rule.Port))
+			}
+			if len(four) == 0 && len(six) == 0 {
+				b.WriteString(fmt.Sprintf(
+					"\t\t# %s/%d wanted the local network, and this node knows neither mesh addresses nor a "+
+						"local network; closed\n", rule.Protocol, rule.Port))
+				break
+			}
+			if len(four) > 0 {
+				b.WriteString(fmt.Sprintf("\t\tip saddr { %s } %s dport %d accept\n",
+					strings.Join(four, ", "), rule.Protocol, rule.Port))
+			}
+			if len(six) > 0 {
+				b.WriteString(fmt.Sprintf("\t\tip6 saddr { %s } %s dport %d accept\n",
+					strings.Join(six, ", "), rule.Protocol, rule.Port))
+			}
 		case FromEverywhere:
 			b.WriteString(fmt.Sprintf("\t\t%s dport %d accept\n", rule.Protocol, rule.Port))
 		}
@@ -487,6 +524,18 @@ func AsNftables(rules []Rule, mesh []string, outward bool, foundation []int,
 				b.WriteString(fmt.Sprintf("\t\tip6 saddr { %s } ct original proto-dst %d accept\n",
 					strings.Join(six, ", "), rule.Port))
 			}
+		case FromLocalNetwork:
+			four, six := byFamily(mesh)
+			lfour, lsix := byFamily(local)
+			four, six = append(four, lfour...), append(six, lsix...)
+			if len(four) > 0 {
+				b.WriteString(fmt.Sprintf("\t\tip saddr { %s } ct original proto-dst %d accept\n",
+					strings.Join(four, ", "), rule.Port))
+			}
+			if len(six) > 0 {
+				b.WriteString(fmt.Sprintf("\t\tip6 saddr { %s } ct original proto-dst %d accept\n",
+					strings.Join(six, ", "), rule.Port))
+			}
 		case FromEverywhere:
 			b.WriteString(fmt.Sprintf("\t\tct original proto-dst %d accept\n", rule.Port))
 		}
@@ -793,10 +842,14 @@ const (
 	// are a subset of anywhere. What differs is the names, which is the whole reason reach is not
 	// simply the filter's vocabulary with nicer words.
 	ReachBoth = "both"
+	// ReachLocalNetwork is `internal` with the machine's own local networks added to what the filter
+	// opens (novox/hq ADR 0340 §4): the internal name and not the public one, the mesh's own authority,
+	// and the port opened to the private network and to the private networks the machine is attached to.
+	ReachLocalNetwork = "local-network"
 )
 
 // reaches is every value, in the order a refusal lists them.
-var reaches = []string{ReachMachine, ReachInternal, ReachPublic, ReachBoth}
+var reaches = []string{ReachMachine, ReachInternal, ReachPublic, ReachBoth, ReachLocalNetwork}
 
 // RoutedPorts are the ports a module serves through a proxy, taken from its route contributions.
 //
@@ -845,6 +898,8 @@ func FilterSource(reach string) (string, bool) {
 		return FromMesh, true
 	case ReachPublic, ReachBoth:
 		return FromEverywhere, true
+	case ReachLocalNetwork:
+		return FromLocalNetwork, true
 	default:
 		return "", false
 	}
@@ -854,7 +909,9 @@ func FilterSource(reach string) (string, bool) {
 func WantsPublicName(reach string) bool { return reach == ReachPublic || reach == ReachBoth }
 
 // WantsInternalName is whether a reach asks for the route's internal name to be composed.
-func WantsInternalName(reach string) bool { return reach == ReachInternal || reach == ReachBoth }
+func WantsInternalName(reach string) bool {
+	return reach == ReachInternal || reach == ReachBoth || reach == ReachLocalNetwork
+}
 
 // Reaches reads a module's per-node reach settings: declared port → how far it reaches.
 //

internal/catalogue/generated_collision_test.go

@@ -6,7 +6,8 @@ import (
 )
 
 // novox/hq issue 190, step 5 (ADR 0222): what the mesh computes for a module is held to the rule
-// every module is — no two modules on a machine declare one path, unit, name or package. The
+// every module is — no two modules on a machine declare one path, unit or name (a package may be declared by
+// several, novox/hq ADR 0303). The
 // private network once declared the container runtime's file and service beside the runtime's own
 // module, and nothing refused it, because the collision check only ever saw catalogue manifests.
 

internal/catalogue/genesis_registry_test.go

@@ -0,0 +1,85 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// Genesis assigns the build agent before the package registry exists (novox/hq ADR 0336, issue 121),
+// judged over the real catalogue. Genesis's step 13 was refused with "nothing provides
+// \"npm-package-registry\", wanted by build-agent": the forge genesis raises at its packages step is a
+// container, not the gitea module, and provides nothing.
+
+// agentBuilt is the build agent as the mesh holds it once built: its image pinned.
+func agentBuilt(t *testing.T) Manifest {
+	t.Helper()
+	agent := catalogueManifest(t, "build-agent")
+	built, err := agent.Resolve([]Built{{Name: "server", Kind: ArtifactImage,
+		Reference: "mesh-builder@sha256:" + strings.Repeat("a", 64)}})
+	if err != nil {
+		t.Fatalf("the build agent does not resolve against its own build: %v", err)
+	}
+	return built
+}
+
+func TestGenesisAssignsTheBuildAgentWithNothingProvidingTheRegistry(t *testing.T) {
+	agent := agentBuilt(t)
+	if !agent.IsOptional("npm-package-registry") {
+		t.Fatalf("the build agent's npm-package-registry is hard (ADR 0336 §1): %v", agent.Requires)
+	}
+	if agent.IsOptional("artifact-store") {
+		t.Fatal("the build agent's artifact-store is optional; it stays hard")
+	}
+	store := map[string][]Provider{"artifact-store": {
+		{Node: "anchor", At: "anchor.internal", Module: "distribution", Serves: map[string]any{"port": float64(5000)}}}}
+	books := shelf(agent, catalogueManifest(t, "gitea"), catalogueManifest(t, "distribution"))
+
+	// Genesis's node at step 13: the store answers, nothing provides the registry.
+	got, err := Resolve(books, []string{"build-agent"}, reachable(), World{Offered: store})
+	if err != nil {
+		t.Fatalf("assigning the build agent with no registry was refused: %v", err)
+	}
+	if have := strings.Join(names(got), " "); have != "build-agent" {
+		t.Fatalf("assigning the build agent put %s on the machine; nothing is installed for the registry", have)
+	}
+	if len(got.Absent) != 1 || got.Absent[0] != (Absent{Consumer: "build-agent", Requirement: "npm-package-registry"}) {
+		t.Fatalf("the registry is not listed unbound for the build agent: %+v", got.Absent)
+	}
+	out, err := got.Declaration(Rendering{ArtifactStore: "anchor.internal:5000",
+		Needed: map[string]map[string]string{"build-agent": {"broker": "sealed-broker"}}})
+	if err != nil {
+		t.Fatalf("the build agent does not compose with the registry unbound: %v", err)
+	}
+	for _, id := range []string{"build-agent." + BoundID("npm-package-registry"), "build-agent." + SecretID("npm-package-registry"),
+		"build-agent." + NeedID("genesis-package-registry")} {
+		if fileNamed(out, id) != nil {
+			t.Errorf("%s was delivered with the registry unbound and no genesis document given", id)
+		}
+	}
+
+	// The genesis document, once the installer seals it at the packages step (ADR 0336 §3).
+	out, err = got.Declaration(Rendering{ArtifactStore: "anchor.internal:5000",
+		Needed: map[string]map[string]string{"build-agent": {"broker": "sealed-broker", "genesis-package-registry": "sealed-genesis"}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	doc := fileNamed(out, "build-agent."+NeedID("genesis-package-registry"))
+	if doc == nil || doc["sealed"] != "sealed-genesis" || !strings.HasSuffix(doc["path"].(string), "/genesis-package-registry.json") {
+		t.Fatalf("the genesis document is not delivered where the agent reads it: %v", doc)
+	}
+
+	// The gitea module assigned: the requirement binds, with no act on the build agent (ADR 0336 §2).
+	registry := map[string][]Provider{"artifact-store": store["artifact-store"], "npm-package-registry": {
+		{Node: "anchor", At: "anchor.internal", Module: "gitea",
+			Serves: map[string]any{"port": float64(3000), "scheme": "http", "npm-path": "/api/packages/novox/npm/"}}}}
+	bound, err := Resolve(books, []string{"build-agent"}, reachable(), World{Offered: registry})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := boundFrom(t, bound, "build-agent", "npm-package-registry"); n.Module != "gitea" {
+		t.Fatalf("bound to %s", n.Module)
+	}
+	if len(bound.Absent) != 0 {
+		t.Fatalf("the registry is still listed unbound once gitea is assigned: %+v", bound.Absent)
+	}
+}

internal/catalogue/issued_credential_test.go

@@ -25,13 +25,13 @@ func TestAnOfferMaySayItsSoftwareIssuesTheCredential(t *testing.T) {
 	}
 
 	for want, raw := range map[string]string{
-		"the one issuer an offer may name": `{"module":"d","version":"1",
+		"the issuers an offer may name": `{"module":"d","version":"1",
 			"provides":[{"name":"d-api","credential":{"issued-by":"vendor","tool":"d_token"}}]}`,
 		"names no tool that answers it": `{"module":"d","version":"1",
 			"provides":[{"name":"d-api","credential":{"issued-by":"software"}}]}`,
 		"names its own secret": `{"module":"d","version":"1","own-secrets":{"token":{"path":"/p","taken":"at-start"}},
 			"provides":[{"name":"d-api","credential":{"issued-by":"software","tool":"d_token","own":"token"}}]}`,
-		"the one issuer an offer may name ": `{"module":"d","version":"1",
+		"the issuers an offer may name ": `{"module":"d","version":"1",
 			"provides":[{"name":"d-api","credential":{"tool":"d_token"}}]}`,
 	} {
 		want = strings.TrimSpace(want)

internal/catalogue/issued_outside_test.go

@@ -0,0 +1,46 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A provision's credential may be one only a person outside the mesh can give (novox/hq ADR 0337 §1, issue 164):
+// the offer says `issued-by: outside` and names neither an own secret nor a tool, and the parser refuses it beside
+// either. An offer that says `software` keeps ADR 0305's shape.
+func TestAnOfferMaySayAPersonOutsideTheMeshIssuesItsCredential(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"tv","version":"1",
+		"provides":[{"name":"tv-api","scope":"mesh","credential":{"issued-by":"outside"}}],
+		"serves":{"tv-api":{"port":8989}}}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !m.IssuedOutsideOf("tv-api") {
+		t.Fatal("the offer's credential issued outside was not read")
+	}
+	if m.IssuedOutsideOf("other") {
+		t.Fatal("a provision the module does not offer reads as issued outside")
+	}
+	if _, issued := m.IssuedCredentialOf("tv-api"); issued {
+		t.Fatal("a credential issued outside was read as issued by the software")
+	}
+	if _, shared := m.SharedCredentialOf("tv-api"); shared {
+		t.Fatal("a credential issued outside was read as an own secret shared")
+	}
+	if who, offered := OffersIssuedOutside(map[string]Manifest{"tv": m}, "tv-api"); !offered || who != "tv" {
+		t.Fatalf("the catalogue does not say tv offers tv-api issued outside: %q %v", who, offered)
+	}
+
+	for want, raw := range map[string]string{
+		"names its own secret": `{"module":"d","version":"1","own-secrets":{"key":{"path":"/p","taken":"at-start"}},
+			"provides":[{"name":"d-api","credential":{"issued-by":"outside","own":"key"}}]}`,
+		"names the tool": `{"module":"d","version":"1",
+			"provides":[{"name":"d-api","credential":{"issued-by":"outside","tool":"d_key"}}]}`,
+		"the issuers an offer may name": `{"module":"d","version":"1",
+			"provides":[{"name":"d-api","credential":{"issued-by":"a-person"}}]}`,
+	} {
+		if _, err := ParseManifest([]byte(raw)); err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("expected a refusal saying %q, got %v", want, err)
+		}
+	}
+}

internal/catalogue/localnetwork.go

@@ -0,0 +1,154 @@
+package catalogue
+
+import (
+	"fmt"
+	"net/netip"
+	"slices"
+	"sort"
+	"strings"
+)
+
+// AttachedNetwork is one network a machine said it is directly attached to: the link it is on and the
+// network as address and prefix (novox/hq ADR 0340 §7), as the node-engine reports it among its facts.
+type AttachedNetwork struct {
+	Link    string `json:"link"`
+	Network string `json:"network"`
+}
+
+// LocalNetwork is one attached network judged: whether it counts as this machine's local network for a
+// port reached from `local-network`, and why — said for one that counts as well as for one that does
+// not, so `node` can show which counted and why the others did not (ADR 0340 §8).
+type LocalNetwork struct {
+	Link    string
+	Network string
+	Counts  bool
+	Why     string
+}
+
+// privateRanges are the only ranges a local network may lie in (ADR 0340 §2): RFC 1918 for IPv4 and the
+// unique local addresses for IPv6. A network counts only when it lies wholly inside one of them.
+var privateRanges = []struct {
+	prefix netip.Prefix
+	name   string
+}{
+	{netip.MustParsePrefix("10.0.0.0/8"), "a private range (RFC 1918, 10.0.0.0/8)"},
+	{netip.MustParsePrefix("172.16.0.0/12"), "a private range (RFC 1918, 172.16.0.0/12)"},
+	{netip.MustParsePrefix("192.168.0.0/16"), "a private range (RFC 1918, 192.168.0.0/16)"},
+	{netip.MustParsePrefix("fc00::/7"), "the IPv6 unique local range (fc00::/7)"},
+}
+
+// JudgeLocalNetworks says, for each network a machine reported, whether it counts as its local network.
+//
+// **A public subnet never counts** (ADR 0340 §2): a network counts only when it lies wholly in a private
+// range, so `local-network` can never open a port to the internet — a machine sitting on a public /24 has
+// that /24 judged and refused, never rendered. A link-local network does not count either. And only a
+// link the machine reported as facing outside it counts (§3): the private network's own link and a
+// container bridge are this machine's own, not its local network, whatever their addresses.
+//
+// Sorted by link and then network, one entry per (link, network), so what `node` shows and what the
+// filter is rendered from do not depend on the order a machine happened to say them in.
+func JudgeLocalNetworks(attached []AttachedNetwork, outward []string, tunnel string) []LocalNetwork {
+	seen := map[[2]string]bool{}
+	var out []LocalNetwork
+	for _, a := range attached {
+		key := [2]string{a.Link, a.Network}
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		out = append(out, judgeOne(a, outward, tunnel))
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Link != out[j].Link {
+			return out[i].Link < out[j].Link
+		}
+		return out[i].Network < out[j].Network
+	})
+	return out
+}
+
+func judgeOne(a AttachedNetwork, outward []string, tunnel string) LocalNetwork {
+	j := LocalNetwork{Link: a.Link, Network: a.Network}
+	prefix, err := netip.ParsePrefix(strings.TrimSpace(a.Network))
+	if err != nil {
+		j.Why = "not a network the mesh can read (" + err.Error() + ")"
+		return j
+	}
+	prefix = prefix.Masked()
+	j.Network = prefix.String()
+	switch {
+	case tunnel != "" && a.Link == tunnel:
+		j.Why = "the private network's own link, not the local network"
+		return j
+	case !slices.Contains(outward, a.Link):
+		j.Why = fmt.Sprintf("%s does not face outside this machine (a bridge or a link of its own)", a.Link)
+		return j
+	case prefix.Addr().IsLoopback():
+		j.Why = "loopback"
+		return j
+	case prefix.Addr().IsLinkLocalUnicast():
+		j.Why = "link-local, never counted"
+		return j
+	}
+	for _, r := range privateRanges {
+		if r.prefix.Contains(prefix.Addr()) && prefix.Bits() >= r.prefix.Bits() {
+			j.Counts = true
+			j.Why = "in " + r.name
+			return j
+		}
+	}
+	if prefix.Addr().IsPrivate() {
+		// Overlaps a private range without lying wholly inside it (a /7 around 10.0.0.0/8, say).
+		j.Why = "not wholly in a private range, so never counted"
+		return j
+	}
+	j.Why = "public, never counted: local-network may not open a port to the internet"
+	return j
+}
+
+// CountedLocalNetworks is the networks that count, as the filter renders them: sorted, without repeats.
+func CountedLocalNetworks(judged []LocalNetwork) []string {
+	var out []string
+	for _, j := range judged {
+		if j.Counts && !slices.Contains(out, j.Network) {
+			out = append(out, j.Network)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// LocalNetworkPort is one port the filter admits from `local-network`, and what that resolved to on this
+// machine (ADR 0340 §8): what `plan` shows for it.
+type LocalNetworkPort struct {
+	Port     int
+	Protocol string
+	Because  []string
+	// Networks is the local networks it is admitted from; empty when the machine reported none (§6).
+	Networks []string
+}
+
+// LocalNetworkPorts is every rule admitted from `local-network`, with the networks it resolved to.
+func LocalNetworkPorts(rules []Rule, networks []string) []LocalNetworkPort {
+	var out []LocalNetworkPort
+	for _, rule := range rules {
+		if rule.From != FromLocalNetwork {
+			continue
+		}
+		out = append(out, LocalNetworkPort{Port: rule.Port, Protocol: rule.Protocol,
+			Because: rule.Because, Networks: networks})
+	}
+	return out
+}
+
+// Said is how `plan` says one such port: the networks, or that there are none and the port is admitted
+// from the private network only.
+func (p LocalNetworkPort) Said() string {
+	by := strings.Join(p.Because, ", ")
+	if len(p.Networks) == 0 {
+		return fmt.Sprintf("%s/%d (%s) from the local network: none — this machine reported no private "+
+			"network on a link facing outside, so it is admitted from the private network only", p.Protocol, p.Port, by)
+	}
+	return fmt.Sprintf("%s/%d (%s) from the local network: %s, and the private network", p.Protocol, p.Port, by,
+		strings.Join(p.Networks, ", "))
+}

internal/catalogue/localnetwork_test.go

@@ -0,0 +1,195 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// The home server's case (novox/hq issue 154): it sits on 192.168.1.0/24, and also on a public /24 a
+// provider handed it, beside the private network's own link and a container bridge.
+var homeServer = []AttachedNetwork{
+	{Link: "eth0", Network: "192.168.1.10/24"},
+	{Link: "eth1", Network: "203.0.113.7/24"},
+	{Link: "eth0", Network: "fe80::1/64"},
+	{Link: "eth0", Network: "fd12:3456:789a::5/64"},
+	{Link: "wg-mesh", Network: "10.10.0.4/24"},
+	{Link: "docker0", Network: "172.17.0.1/16"},
+}
+
+func judged(t *testing.T) []LocalNetwork {
+	t.Helper()
+	return JudgeLocalNetworks(homeServer, []string{"eth0", "eth1"}, "wg-mesh")
+}
+
+// **A public subnet never counts** (ADR 0340 §2), and only a private one on a link facing outside does
+// (§3): the tunnel's and a bridge's are this machine's own, whatever their addresses.
+func TestOnlyAPrivateNetworkOnALinkFacingOutsideCounts(t *testing.T) {
+	got := CountedLocalNetworks(judged(t))
+	want := []string{"192.168.1.0/24", "fd12:3456:789a::/64"}
+	if strings.Join(got, " ") != strings.Join(want, " ") {
+		t.Fatalf("counted %v, want %v", got, want)
+	}
+	for _, j := range judged(t) {
+		if j.Why == "" {
+			t.Errorf("%s on %s is judged without a why", j.Network, j.Link)
+		}
+		switch j.Network {
+		case "203.0.113.0/24":
+			if j.Counts || !strings.Contains(j.Why, "public") {
+				t.Errorf("the public subnet is judged %v (%s), want never counted as public", j.Counts, j.Why)
+			}
+		case "fe80::/64":
+			if j.Counts || !strings.Contains(j.Why, "link-local") {
+				t.Errorf("a link-local network is judged %v (%s)", j.Counts, j.Why)
+			}
+		case "10.10.0.0/24", "172.17.0.0/16":
+			if j.Counts {
+				t.Errorf("%s on %s counts, and it is not the local network", j.Network, j.Link)
+			}
+		}
+	}
+}
+
+// A network overlapping a private range without lying wholly inside it does not count either, so a
+// wide prefix around a private range cannot carry the internet with it.
+func TestANetworkNotWhollyInAPrivateRangeDoesNotCount(t *testing.T) {
+	for _, n := range []string{"10.0.0.0/7", "172.0.0.0/8", "100.64.0.0/10", "0.0.0.0/0", "::/0"} {
+		got := JudgeLocalNetworks([]AttachedNetwork{{Link: "eth0", Network: n}}, []string{"eth0"}, "")
+		if len(got) != 1 || got[0].Counts {
+			t.Errorf("%s counts as a local network: %+v", n, got)
+		}
+	}
+}
+
+// **The filter admits the local network on that port's rule alone** (§5), beside the private network,
+// in both chains, and never the public subnet.
+func TestALocalNetworkPortIsAdmittedFromItsNetworksAndTheMesh(t *testing.T) {
+	rules := []Rule{
+		{Port: 1883, Protocol: "tcp", From: FromLocalNetwork, Because: []string{"mosquitto"}},
+		{Port: 5432, Protocol: "tcp", From: FromMesh, Because: []string{"postgres"}},
+	}
+	local := CountedLocalNetworks(judged(t))
+	out := AsNftablesWithLocal(rules, []string{"10.10.0.1", "10.10.0.4"}, false, nil,
+		[]string{"eth0", "eth1"}, "wg-mesh", local)
+
+	for _, want := range []string{
+		"ip saddr { 10.10.0.1, 10.10.0.4, 192.168.1.0/24 } tcp dport 1883 accept",
+		"ip6 saddr { fd12:3456:789a::/64 } tcp dport 1883 accept",
+		"ip saddr { 10.10.0.1, 10.10.0.4, 192.168.1.0/24 } ct original proto-dst 1883 accept",
+		// The mesh-only port is not widened by the machine having a local network.
+		"ip saddr { 10.10.0.1, 10.10.0.4 } tcp dport 5432 accept",
+	} {
+		if !strings.Contains(out, want) {
+			t.Errorf("the rule set lacks %q:\n%s", want, out)
+		}
+	}
+	if strings.Contains(out, "203.0.113") {
+		t.Errorf("the public subnet reached the rule set:\n%s", out)
+	}
+	if strings.Contains(out, "tcp dport 1883 accept\n") && !strings.Contains(out, "saddr") {
+		t.Errorf("1883 is open to anywhere:\n%s", out)
+	}
+	for _, line := range strings.Split(out, "\n") {
+		if strings.TrimSpace(line) == "tcp dport 1883 accept" {
+			t.Fatalf("1883 is open to anywhere:\n%s", out)
+		}
+	}
+}
+
+// **Nothing resolved is closed and said** (§6): a machine that reported no private network admits the
+// port from the private network only, and the rule set says it found none — never widened to anywhere.
+func TestNoLocalNetworkIsSaidAndNotWidened(t *testing.T) {
+	rules := []Rule{{Port: 1883, Protocol: "tcp", From: FromLocalNetwork, Because: []string{"mosquitto"}}}
+	out := AsNftablesWithLocal(rules, []string{"10.10.0.1"}, false, nil, []string{"eth0"}, "wg-mesh", nil)
+	if !strings.Contains(out, "1883 wanted the local network, and this machine reported no private network") {
+		t.Errorf("the rule set does not say the local network resolved to nothing:\n%s", out)
+	}
+	if !strings.Contains(out, "ip saddr { 10.10.0.1 } tcp dport 1883 accept") {
+		t.Errorf("the port is not admitted from the private network:\n%s", out)
+	}
+	for _, line := range strings.Split(out, "\n") {
+		if strings.TrimSpace(line) == "tcp dport 1883 accept" {
+			t.Fatalf("an unresolved local network was widened to anywhere:\n%s", out)
+		}
+	}
+	said := LocalNetworkPorts(rules, nil)[0].Said()
+	if !strings.Contains(said, "none") {
+		t.Errorf("plan says %q, want it to say no local network was found", said)
+	}
+}
+
+// `local-network` is a source a manifest may name (§1, changing ADR 0045 §3), and an unknown source is
+// still refused.
+func TestAManifestMayListenFromTheLocalNetwork(t *testing.T) {
+	if _, err := ParseManifest([]byte(`{"module":"mosquitto","version":"1",
+		"listens":[{"port":1883,"from":"local-network"}]}`)); err != nil {
+		t.Fatalf("a listen from the local network is refused: %v", err)
+	}
+	_, err := ParseManifest([]byte(`{"module":"mosquitto","version":"1",
+		"listens":[{"port":1883,"from":"lan"}]}`))
+	if err == nil || !strings.Contains(err.Error(), `from "lan"`) {
+		t.Fatalf("a source the mesh cannot render is not refused: %v", err)
+	}
+}
+
+// **A fourth reach** (§4, changing ADR 0138 §4): `internal` with the local networks added to what the
+// filter opens — the internal name, not the public one.
+func TestTheLocalNetworkReachIsInternalWithTheLocalNetworkAdded(t *testing.T) {
+	public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachLocalNetwork))
+	if public != "" || internal != "app.anchor.internal" {
+		t.Fatalf("names are %q and %q, want the internal name only", public, internal)
+	}
+	bare := aRoutedWeb()
+	bare.Contributes = nil
+	r := Resolution{Node: "anchor", Modules: []Manifest{bare}}
+	rules, err := r.Rules(Rendering{Settings: reachSet(ReachLocalNetwork)})
+	if err != nil {
+		t.Fatalf("rules: %v", err)
+	}
+	if len(rules) != 1 || rules[0].From != FromLocalNetwork {
+		t.Fatalf("reach local-network made the filter say %+v", rules)
+	}
+}
+
+// Two modules wanting one port, one from the mesh and one from the local network, render one rule from
+// the local network: it covers the mesh, and anywhere covers it.
+func TestTheLocalNetworkSitsBetweenTheMeshAndAnywhere(t *testing.T) {
+	got := widest([]Rule{
+		{Port: 53, Protocol: "udp", From: FromMesh, Because: []string{"a"}},
+		{Port: 53, Protocol: "udp", From: FromLocalNetwork, Because: []string{"b"}},
+	})
+	if len(got) != 1 || got[0].From != FromLocalNetwork || len(got[0].Because) != 2 {
+		t.Fatalf("got %+v", got)
+	}
+	got = widest(append(got, Rule{Port: 53, Protocol: "udp", From: FromEverywhere, Because: []string{"c"}}))
+	if len(got) != 1 || got[0].From != FromEverywhere {
+		t.Fatalf("got %+v", got)
+	}
+}
+
+// On an adopted node the opening is the private network's part only: the found firewall admits the
+// local network, and an opening that widened to everywhere would open the port to the internet.
+func TestAnAdoptedNodeOpensTheLocalNetworkPortToTheMeshOnly(t *testing.T) {
+	out := Openings([]Rule{{Port: 1883, Protocol: "tcp", From: FromLocalNetwork}}, nil, nil)
+	if len(out) != 1 || out[0]["from"] != OpeningFromMesh {
+		t.Fatalf("openings %v", out)
+	}
+}
+
+// A global unicast IPv6 subnet on a link facing outside is public, and never counts: the IPv6 side of the
+// rule that `local-network` cannot open a port to the internet (ADR 0340 §2).
+func TestAGlobalIPv6SubnetIsPublicAndNeverCounts(t *testing.T) {
+	got := JudgeLocalNetworks([]AttachedNetwork{{Link: "eth0", Network: "2001:db8:1234::7/48"}}, []string{"eth0"}, "wg-mesh")
+	if len(got) != 1 {
+		t.Fatalf("judged %+v", got)
+	}
+	if got[0].Counts {
+		t.Fatalf("the global IPv6 subnet %s counts as a local network", got[0].Network)
+	}
+	if got[0].Network != "2001:db8:1234::/48" || !strings.Contains(got[0].Why, "public, never counted") {
+		t.Fatalf("judged %s with why %q, want it named public and never counted", got[0].Network, got[0].Why)
+	}
+	if n := CountedLocalNetworks(got); len(n) != 0 {
+		t.Fatalf("counted %v", n)
+	}
+}

internal/catalogue/manifest.go

@@ -269,7 +269,8 @@ func KeepsConsumerData(catalogue map[string]Manifest, provision string) bool {
 func (o Offer) MachineReach() bool { return o.Reach == ReachMachine }
 
 // OfferCredential names which of the provider's own secrets a provision's consumers receive — or, with
-// IssuedBy, that the provider's software issues the provision's one credential itself (novox/hq ADR 0305,
+// IssuedBy "outside", that only a person can give the provision's credential (novox/hq ADR 0337, issue 164) — or,
+// with IssuedBy "software", that the provider's software issues the provision's one credential itself (novox/hq ADR 0305,
 // issue 526): a media server's sign-in token from its vendor, which the mesh can neither make nor rotate.
 // Tool is then the provider's own tool that answers that value, sealed to a key made for the controller's
 // one call, and to the controller alone.
@@ -293,6 +294,34 @@ func (m Manifest) IssuedCredentialOf(provision string) (string, bool) {
 	return "", false
 }
 
+// IssuedOutsideOf is whether this module's offer of a provision says only a person outside the mesh can give its
+// credential (novox/hq ADR 0337): the mesh never makes a value for it, and a consumer holds one only once a person
+// gave it with `secret accept`.
+func (m Manifest) IssuedOutsideOf(provision string) bool {
+	for _, o := range m.Provides {
+		if o.Name == provision && o.Credential != nil && o.Credential.IssuedBy == IssuedOutside {
+			return true
+		}
+	}
+	return false
+}
+
+// OffersIssuedOutside is whether any module of a catalogue offers the provision with a credential issued outside
+// the mesh (novox/hq ADR 0337), and the first such module by name.
+func OffersIssuedOutside(shelf map[string]Manifest, provision string) (string, bool) {
+	var names []string
+	for name, m := range shelf {
+		if m.IssuedOutsideOf(provision) {
+			names = append(names, name)
+		}
+	}
+	if len(names) == 0 {
+		return "", false
+	}
+	sort.Strings(names)
+	return names[0], true
+}
+
 // SharedCredentialOf is the own secret an offer of this module names as the provision's credential,
 // and whether it names one.
 func (m Manifest) SharedCredentialOf(provision string) (string, bool) {
@@ -385,6 +414,10 @@ type Manifest struct {
 
 	// Requires are names that must be provided by something assigned to the same node.
 	Requires []string `json:"requires,omitempty"`
+	// OptionalRequires is which of Requires the module can run without (novox/hq ADR 0330): filled
+	// by UnmarshalJSON from the long form of a `requires` entry, {name, optional}, or from the stored
+	// form's `optional-requires` list; never written by hand.
+	OptionalRequires map[string]bool `json:"-"`
 
 	// Emits are the events this module publishes, named **locally**: `order.placed`, not a subject
 	// and not a routing key. The mesh derives where it lands (design 29 §1), so reorganising the
@@ -1132,6 +1165,12 @@ const (
 	FromEverywhere = "anywhere"
 	// FromMachine is this machine only — a port bound for something else on the same host.
 	FromMachine = "machine"
+	// FromLocalNetwork is the private network and the networks this machine is directly attached to
+	// through its uplink, as it reports them, and only those wholly in a private range (novox/hq ADR
+	// 0340): a local service reached by devices that will never be nodes, said as exactly that rather
+	// than as `anywhere`. A public subnet the machine sits on never counts, so it cannot open a port to
+	// the internet.
+	FromLocalNetwork = "local-network"
 )
 
 // At is this port's protocol, with the default applied.
@@ -1354,6 +1393,35 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 		}
 		delete(keys, "contributes")
 	}
+	var optionalRequires map[string]bool
+	if requires, ok := keys["requires"]; ok && string(requires) != "null" {
+		names, optional, err := readRequires(requires)
+		if err != nil {
+			return err
+		}
+		plainNames, err := json.Marshal(names)
+		if err != nil {
+			return err
+		}
+		keys["requires"] = plainNames
+		optionalRequires = optional
+	}
+	// The stored form: `requires` plain, and which are optional beside it (OptionalRequiresKey).
+	if stored, ok := keys[OptionalRequiresKey]; ok {
+		if string(stored) != "null" {
+			optional, err := readOptionalRequires(stored)
+			if err != nil {
+				return err
+			}
+			for name := range optional {
+				if optionalRequires == nil {
+					optionalRequires = map[string]bool{}
+				}
+				optionalRequires[name] = true
+			}
+		}
+		delete(keys, OptionalRequiresKey)
+	}
 	rest, err := json.Marshal(keys)
 	if err != nil {
 		return err
@@ -1385,6 +1453,7 @@ func (m *Manifest) UnmarshalJSON(raw []byte) error {
 	}
 	*m = Manifest(fields)
 	m.unknown = unknown
+	m.OptionalRequires = optionalRequires
 	if len(plain) > 0 {
 		m.Secrets = plain
 	}
@@ -1407,13 +1476,22 @@ func (m Manifest) MarshalJSON() ([]byte, error) {
 	if err != nil {
 		return nil, err
 	}
-	if len(m.SecretsMany) == 0 && len(m.ContributesMany) == 0 {
+	if len(m.SecretsMany) == 0 && len(m.ContributesMany) == 0 && len(m.OptionalRequires) == 0 {
 		return raw, nil
 	}
 	var keys map[string]json.RawMessage
 	if err := json.Unmarshal(raw, &keys); err != nil {
 		return nil, err
 	}
+	if optional := optionalRequiresList(m); len(optional) > 0 {
+		// Beside `requires`, never inside it: an older controller reads `requires` as plain names, and one
+		// manifest it cannot read stops the whole catalogue (OptionalRequiresKey).
+		listed, err := json.Marshal(optional)
+		if err != nil {
+			return nil, err
+		}
+		keys[OptionalRequiresKey] = listed
+	}
 	if len(m.ContributesMany) > 0 {
 		mergedContributes := map[string]any{}
 		for to, values := range m.Contributes {
@@ -1604,14 +1682,28 @@ func ParseManifest(raw []byte) (Manifest, error) {
 						"makes is %d", m.Module, p, id.Max, shortest))
 			}
 		}
-		if c := offer.Credential; c != nil && (c.IssuedBy != "" || c.Tool != "") {
+		if c := offer.Credential; c != nil && c.IssuedBy == IssuedOutside {
+			// Only a person can give it (novox/hq ADR 0337 §1, issue 164): the software holds a value the mesh can
+			// neither make nor fetch, so the offer names nothing that would answer it — no own secret, no tool.
+			switch {
+			case c.Own != "":
+				problems = append(problems, fmt.Sprintf(
+					"%s provides %q with a credential issued outside the mesh and names its own secret %q too; a "+
+						"person gives the value with `secret accept`, so the offer names no own secret (ADR 0337)",
+					m.Module, p, c.Own))
+			case c.Tool != "":
+				problems = append(problems, fmt.Sprintf(
+					"%s provides %q with a credential issued outside the mesh and names the tool %q; only a "+
+						"person gives it, so the offer names no tool (ADR 0337)", m.Module, p, c.Tool))
+			}
+		} else if c := offer.Credential; c != nil && (c.IssuedBy != "" || c.Tool != "") {
 			// The software issues it (novox/hq ADR 0305): named by the tool that answers it, never by an own
 			// secret, which would be a second copy for the mesh to keep in step with the software's.
 			switch {
 			case c.IssuedBy != IssuedBySoftware:
 				problems = append(problems, fmt.Sprintf(
-					"%s provides %q with a credential issued by %q; the one issuer an offer may name is %q (ADR 0305)",
-					m.Module, p, c.IssuedBy, IssuedBySoftware))
+					"%s provides %q with a credential issued by %q; the issuers an offer may name are %q and %q "+
+						"(ADR 0305, ADR 0337)", m.Module, p, c.IssuedBy, IssuedBySoftware, IssuedOutside))
 			case c.Own != "":
 				problems = append(problems, fmt.Sprintf(
 					"%s provides %q with a credential its software issues and names its own secret %q too; the "+
@@ -1693,6 +1785,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 what it requires optionally, and the files it delivers only while bound (novox/hq ADR 0330).
+	problems = append(problems, OptionalProblems(m)...)
 	// And which setting keys each mergeable file takes (setting_takes.go, novox/hq ADR 0326).
 	problems = append(problems, TakenSettingsProblems(m)...)
 	wellFormed := true
@@ -1841,17 +1935,17 @@ func ParseManifest(raw []byte) (Manifest, error) {
 				"%s listens on port %d, which is not a port", m.Module, l.Port))
 		}
 		switch l.From {
-		case FromMesh, FromEverywhere, FromMachine:
+		case FromMesh, FromEverywhere, FromMachine, FromLocalNetwork:
 		case "":
 			// The fault this field exists to prevent. A rule with no source is open, and a
 			// manifest that omitted it would read as a restriction and be none.
 			problems = append(problems, fmt.Sprintf(
-				"%s listens on %d and does not say from where; it is %q, %q or %q",
-				m.Module, l.Port, FromMesh, FromEverywhere, FromMachine))
+				"%s listens on %d and does not say from where; it is %q, %q, %q or %q",
+				m.Module, l.Port, FromMesh, FromEverywhere, FromMachine, FromLocalNetwork))
 		default:
 			problems = append(problems, fmt.Sprintf(
-				"%s listens on %d from %q; it is %q, %q or %q",
-				m.Module, l.Port, l.From, FromMesh, FromEverywhere, FromMachine))
+				"%s listens on %d from %q; it is %q, %q, %q or %q",
+				m.Module, l.Port, l.From, FromMesh, FromEverywhere, FromMachine, FromLocalNetwork))
 		}
 		if p := l.At(); p != "tcp" && p != "udp" {
 			problems = append(problems, fmt.Sprintf(

internal/catalogue/optional_requirements.go

@@ -0,0 +1,282 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// A requirement a module can run without (novox/hq ADR 0330, issue 166).
+//
+// **Hard stays the default.** A requirement written as a bare name is hard, exactly as before: it
+// resolves, or the assignment is refused, and a single catalogue candidate is installed for it. One
+// written `{"name": "influxdb-api", "optional": true}` resolves the same way when a provider is
+// already assigned in the mesh or reachable from the consumer (§2), and is otherwise **absent**: not
+// refused, and nothing is installed for it, on this machine or elsewhere (§3).
+//
+// **An absent requirement is never rendered as an empty value** (§4–§6). Its binding, its pair
+// credential and its grant are not composed, so a file that names one of them is delivered only while
+// the requirement is bound (`only-when-bound`), and a `${bound:…}` placeholder of it outside such a
+// file names the value it takes while absent: `${bound:<provision>:<key>|default:<value>}`. The
+// module check refuses anything else, so the gap is found when the manifest is written, not on a
+// machine where it reads as a blank.
+
+// OnlyWhenBound is a resource's field naming the optional requirement it is delivered only while
+// bound (ADR 0330 §5). Said in the catalogue and dropped before the declaration is sent: the
+// node-engine parses strictly and knows no such field.
+const OnlyWhenBound = "only-when-bound"
+
+// requirementForm is one entry of `requires` in its long form.
+type requirementForm struct {
+	Name     string `json:"name"`
+	Optional bool   `json:"optional,omitempty"`
+}
+
+// readRequires reads `requires` in both of its forms — a bare name, or {name, optional} — into the
+// names and which of them are optional.
+func readRequires(raw json.RawMessage) ([]string, map[string]bool, error) {
+	var entries []json.RawMessage
+	if err := json.Unmarshal(raw, &entries); err != nil {
+		return nil, nil, fmt.Errorf("requires: a list of names, or of {name, optional}: %w", err)
+	}
+	var names []string
+	optional := map[string]bool{}
+	for i, e := range entries {
+		var plain string
+		if err := json.Unmarshal(e, &plain); err == nil {
+			names = append(names, plain)
+			continue
+		}
+		var full requirementForm
+		dec := json.NewDecoder(bytes.NewReader(e))
+		dec.DisallowUnknownFields()
+		if err := dec.Decode(&full); err != nil {
+			return nil, nil, fmt.Errorf("requires[%d]: a name, or {name, optional} (novox/hq ADR 0330): %w", i, err)
+		}
+		if strings.TrimSpace(full.Name) == "" {
+			return nil, nil, fmt.Errorf("requires[%d] names no requirement: {name, optional}", i)
+		}
+		names = append(names, full.Name)
+		if full.Optional {
+			optional[full.Name] = true
+		}
+	}
+	if len(optional) == 0 {
+		optional = nil
+	}
+	return names, optional, nil
+}
+
+// OptionalRequiresKey is where a stored manifest keeps which of its requirements are optional: beside
+// `requires`, which stays a plain list of names (mesh-controller #281's review). A controller older than
+// optional requirements reads `requires` as names; the long form inside it failed that read, and with it
+// the whole catalogue, so a rollback below this controller would have composed no machine. An older
+// controller sets this unknown key aside instead and leaves only the module that carries it out. A
+// manifest may be written either way; it is stored this way.
+const OptionalRequiresKey = "optional-requires"
+
+// readOptionalRequires reads the stored form's list of optional requirements.
+func readOptionalRequires(raw json.RawMessage) (map[string]bool, error) {
+	var names []string
+	if err := json.Unmarshal(raw, &names); err != nil {
+		return nil, fmt.Errorf("%s: a list of the names in `requires` that are optional: %w", OptionalRequiresKey, err)
+	}
+	out := map[string]bool{}
+	for _, n := range names {
+		out[n] = true
+	}
+	return out, nil
+}
+
+// optionalRequiresList is the stored form's list: the optional requirements, sorted.
+func optionalRequiresList(m Manifest) []string {
+	var out []string
+	for name, optional := range m.OptionalRequires {
+		if optional {
+			out = append(out, name)
+		}
+	}
+	sort.Strings(out)
+	return out
+}
+
+// IsOptional is whether this module requires the name optionally (ADR 0330 §1). A name it contributes
+// to without requiring, or requires as a bare name, is hard.
+func (m Manifest) IsOptional(requirement string) bool { return m.OptionalRequires[requirement] }
+
+// wantsHard is whether this module wants the name as a hard requirement: required without
+// `optional`, or contributed to.
+func (m Manifest) wantsHard(name string) bool {
+	for _, w := range m.Wants() {
+		if w == name {
+			return !m.IsOptional(name)
+		}
+	}
+	return false
+}
+
+// Absent is one optional requirement of one consumer that nothing assigned answers (ADR 0330 §3):
+// left unbound rather than refused, and listed by `plan` and `node` (§7).
+type Absent struct {
+	// Consumer is the module that requires it optionally.
+	Consumer string `json:"consumer"`
+	// Requirement is what it requires.
+	Requirement string `json:"requirement"`
+}
+
+// AbsentFor is the optional requirements of one module this resolution leaves unbound.
+func (r Resolution) AbsentFor(module string) map[string]bool {
+	out := map[string]bool{}
+	for _, a := range r.Absent {
+		if a.Consumer == module {
+			out[a.Requirement] = true
+		}
+	}
+	return out
+}
+
+// absentOf is, for each requirement left absent, every module of the set that requires it
+// optionally, sorted by consumer then requirement.
+func absentOf(names map[string]bool, order []string, catalogue map[string]Manifest) []Absent {
+	var out []Absent
+	for _, module := range order {
+		m := catalogue[module]
+		for _, r := range m.Requires {
+			if names[r] && m.IsOptional(r) {
+				out = append(out, Absent{Consumer: module, Requirement: r})
+			}
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if out[i].Consumer != out[j].Consumer {
+			return out[i].Consumer < out[j].Consumer
+		}
+		return out[i].Requirement < out[j].Requirement
+	})
+	return out
+}
+
+// withoutAbsent drops the resources delivered only while a requirement is bound whose requirement is
+// absent here (ADR 0330 §5), and the field itself from every resource that keeps it.
+func withoutAbsent(resources []map[string]any, absent map[string]bool) []map[string]any {
+	out := make([]map[string]any, 0, len(resources))
+	for _, r := range resources {
+		when, has := r[OnlyWhenBound]
+		if !has {
+			out = append(out, r)
+			continue
+		}
+		if absent[fmt.Sprint(when)] {
+			continue
+		}
+		kept := make(map[string]any, len(r))
+		for k, v := range r {
+			if k != OnlyWhenBound {
+				kept[k] = v
+			}
+		}
+		out = append(out, kept)
+	}
+	return out
+}
+
+// secretNamesOf is every `${secret:…}` name that carries a credential of this requirement: its own
+// name, and each local name it keeps several under (ADR 0094).
+func secretNamesOf(m Manifest, requirement string) []string {
+	names := []string{requirement}
+	for local := range m.SecretsMany[requirement] {
+		names = append(names, local)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// OptionalProblems is what the module check refuses of a manifest's optional requirements and its
+// only-when-bound resources (ADR 0330 §4–§6).
+func OptionalProblems(m Manifest) []string {
+	var problems []string
+	required := map[string]bool{}
+	for _, r := range m.Requires {
+		if required[r] && m.IsOptional(r) {
+			problems = append(problems, fmt.Sprintf("%s requires %q twice; say it once, optional or not", m.Module, r))
+		}
+		required[r] = true
+	}
+	for _, r := range optionalRequiresList(m) {
+		if !required[r] {
+			problems = append(problems, fmt.Sprintf(
+				"%s says %q is optional in %s and does not require it", m.Module, r, OptionalRequiresKey))
+		}
+	}
+	// A contribution is to whoever answers the requirement, so it goes with it: contributing to one
+	// that is optional is allowed, and composed only while it is bound.
+	for _, r := range m.Resources {
+		id := fmt.Sprint(r["id"])
+		when, marked := r[OnlyWhenBound]
+		on := ""
+		if marked {
+			name, ok := when.(string)
+			switch {
+			case !ok || name == "":
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %s says %s %v; it names one requirement the module requires optionally",
+					m.Module, id, OnlyWhenBound, when))
+				continue
+			case fmt.Sprint(r["type"]) != "file":
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %s is a %v and says %s: only a file is left out while a requirement is "+
+						"absent (novox/hq ADR 0330 §5)", m.Module, id, r["type"], OnlyWhenBound))
+				continue
+			case !required[name]:
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %s is delivered only when %q is bound, and %s does not require it",
+					m.Module, id, name, m.Module))
+				continue
+			case !m.IsOptional(name):
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %s is delivered only when %q is bound, which is a hard requirement and "+
+						"always bound: mark the requirement optional, or drop %s", m.Module, id, name, OnlyWhenBound))
+				continue
+			}
+			on = name
+		}
+		if fmt.Sprint(r["type"]) != "file" {
+			continue
+		}
+		content, _ := r["content"].(string)
+		for _, use := range bound.FindAllStringSubmatch(content, -1) {
+			provision, key, hasDefault := use[1], use[2], use[3] != ""
+			if !m.IsOptional(provision) {
+				if hasDefault {
+					problems = append(problems, fmt.Sprintf(
+						"%s's resource %s gives ${bound:%s:%s} a default, and %q is a hard requirement, always "+
+							"bound: a default it never renders only misleads a reader", m.Module, id, provision, key, provision))
+				}
+				continue
+			}
+			if !hasDefault && on != provision {
+				problems = append(problems, fmt.Sprintf(
+					"%s's resource %s says ${bound:%s:%s}, and %q is optional: while it is absent this would "+
+						"be empty. Name its value then — ${bound:%s:%s|default:<value>} — or deliver the file "+
+						"only while it is bound, with \"%s\": %q (novox/hq ADR 0330 §4)",
+					m.Module, id, provision, key, provision, provision, key, OnlyWhenBound, provision))
+			}
+		}
+		for _, provision := range m.Requires {
+			if !m.IsOptional(provision) || on == provision {
+				continue
+			}
+			for _, name := range secretNamesOf(m, provision) {
+				if strings.Contains(content, "${secret:"+name+"}") {
+					problems = append(problems, fmt.Sprintf(
+						"%s's resource %s says ${secret:%s}, the credential of %q, which is optional and not "+
+							"delivered while absent: deliver the file only while it is bound, with \"%s\": %q "+
+							"(novox/hq ADR 0330 §6)", m.Module, id, name, provision, OnlyWhenBound, provision))
+				}
+			}
+		}
+	}
+	return problems
+}

internal/catalogue/optional_requirements_test.go

@@ -0,0 +1,301 @@
+package catalogue
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+// A requirement a module can run without (novox/hq ADR 0330, issue 166). The shape of the issue:
+// grafana runs without a data source and requires `influxdb-api` softly; a mesh without influxdb
+// could not assign grafana at all, and one with influxdb in its catalogue would have had it installed
+// for grafana.
+
+func optionalShelf() map[string]Manifest {
+	grafana := Manifest{Module: "grafana", Version: "1", Requires: []string{"influxdb-api", "shell"},
+		OptionalRequires: map[string]bool{"influxdb-api": true, "shell": true}}
+	return shelf(
+		Manifest{Module: "influxdb", Version: "1", Provides: FromAnywhere("influxdb-api")},
+		Manifest{Module: "zsh", Version: "1", Provides: Offers("shell")},
+		grafana,
+		// What wants the same names hard, for the cases where one consumer's optional is another's hard.
+		Manifest{Module: "telegraf", Version: "1", Requires: []string{"influxdb-api"}},
+		Manifest{Module: "editor", Version: "1", Requires: []string{"shell"}},
+		Manifest{Module: "suite", Version: "1", Requires: []string{"editor"}},
+	)
+}
+
+func TestARequirementIsHardUnlessMarkedOptional(t *testing.T) {
+	m := mustParse(t, `{"module":"grafana","version":"1",
+		"requires":["route",{"name":"influxdb-api","optional":true},{"name":"oidc-client"}]}`)
+	if strings.Join(m.Requires, " ") != "route influxdb-api oidc-client" {
+		t.Fatalf("the requirements read as %v", m.Requires)
+	}
+	if m.IsOptional("route") || m.IsOptional("oidc-client") {
+		t.Error("a requirement without `optional` read as optional; hard is the default (ADR 0330 §1)")
+	}
+	if !m.IsOptional("influxdb-api") {
+		t.Error("a requirement marked optional read as hard")
+	}
+	// And written back as it was read, so a manifest through the store keeps its form.
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var again Manifest
+	if err := json.Unmarshal(raw, &again); err != nil {
+		t.Fatal(err)
+	}
+	if !again.IsOptional("influxdb-api") || again.IsOptional("route") || len(again.Requires) != 3 {
+		t.Fatalf("written and read back, it says %v optional %v (%s)", again.Requires, again.OptionalRequires, raw)
+	}
+	if strings.Contains(string(raw), `"name":`) {
+		t.Errorf("a requirement was stored in the long form: %s", raw)
+	}
+}
+
+// The stored form reads on a controller older than optional requirements (review of mesh-controller
+// #281). Inventory.Catalogue stops at the first manifest it cannot read, so a long-form entry inside
+// `requires` would have stopped every plan after a rollback. Stored, `requires` is plain names, as main's
+// manifest type reads it, and which are optional sits beside it in a key such a controller sets aside.
+func TestTheStoredFormReadsWhereRequiresIsAListOfNames(t *testing.T) {
+	m := mustParse(t, `{"module":"grafana","version":"1",
+		"requires":["route",{"name":"influxdb-api","optional":true}]}`)
+	raw, err := json.Marshal(m)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// main's field, exactly: `Requires []string`.
+	var older struct {
+		Requires []string `json:"requires"`
+	}
+	if err := json.Unmarshal(raw, &older); err != nil {
+		t.Fatalf("a controller reading requires as names cannot read the stored form: %v\n%s", err, raw)
+	}
+	if strings.Join(older.Requires, " ") != "route influxdb-api" {
+		t.Fatalf("it reads the requirements as %v", older.Requires)
+	}
+	var keys map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &keys); err != nil {
+		t.Fatal(err)
+	}
+	if string(keys[OptionalRequiresKey]) != `["influxdb-api"]` {
+		t.Fatalf("which are optional is stored as %s", keys[OptionalRequiresKey])
+	}
+	// And this controller reads the stored form back the same, leniently and strictly.
+	var back Manifest
+	if err := json.Unmarshal(raw, &back); err != nil {
+		t.Fatal(err)
+	}
+	strict, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, got := range []Manifest{back, strict} {
+		if !got.IsOptional("influxdb-api") || got.IsOptional("route") || len(got.Requires) != 2 {
+			t.Fatalf("read back as %v optional %v", got.Requires, got.OptionalRequires)
+		}
+	}
+	// A stored list naming something the module does not require is refused.
+	if _, err := ParseManifest([]byte(`{"module":"x","version":"1","requires":["route"],"optional-requires":["mqtt-topic"]}`)); err == nil {
+		t.Error("an optional requirement the module does not require passed the check")
+	}
+}
+
+func TestARequirementsLongFormRefusesWhatItDoesNotKnow(t *testing.T) {
+	for _, raw := range []string{
+		`{"module":"x","version":"1","requires":[{"name":"influxdb-api","optinal":true}]}`,
+		`{"module":"x","version":"1","requires":[{"optional":true}]}`,
+	} {
+		if _, err := ParseManifest([]byte(raw)); err == nil {
+			t.Errorf("accepted %s", raw)
+		}
+	}
+}
+
+func TestAnOptionalRequirementWithNoProviderIsAbsentAndNothingIsInstalled(t *testing.T) {
+	// Exactly one catalogue module could answer each — the case where a hard requirement installs it.
+	// Brokered (influxdb-api, from anywhere) and on this machine (shell); both passes.
+	for _, world := range []World{{}, {Unchecked: true}} {
+		got, err := Resolve(optionalShelf(), []string{"grafana"}, reachable(), world)
+		if err != nil {
+			t.Fatalf("an optional requirement with no provider refused the assignment: %v", err)
+		}
+		if have := strings.Join(names(got), " "); have != "grafana" {
+			t.Fatalf("assigning grafana put %s on the machine; nothing is installed for an optional requirement (ADR 0330 §3)", have)
+		}
+		if world.Unchecked {
+			continue
+		}
+		want := []Absent{{Consumer: "grafana", Requirement: "influxdb-api"}, {Consumer: "grafana", Requirement: "shell"}}
+		if len(got.Absent) != 2 || got.Absent[0] != want[0] || got.Absent[1] != want[1] {
+			t.Fatalf("absent: %+v, want %+v", got.Absent, want)
+		}
+		if len(got.Needs) != 0 {
+			t.Fatalf("an absent requirement was given a binding: %+v", got.Needs)
+		}
+	}
+}
+
+func TestAnOptionalRequirementWithAProviderBindsAsAHardOne(t *testing.T) {
+	world := World{Offered: map[string][]Provider{"influxdb-api": {
+		{Node: "anchor", At: "anchor.internal", Module: "influxdb", Serves: map[string]any{"port": 8086}}}}}
+	got, err := Resolve(optionalShelf(), []string{"grafana", "zsh"}, reachable(), world)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if n := boundFrom(t, got, "grafana", "influxdb-api"); n.From != "anchor" || n.Module != "influxdb" {
+		t.Fatalf("bound to %s/%s", n.From, n.Module)
+	}
+	if len(got.Absent) != 0 {
+		t.Fatalf("a requirement with a provider was left absent: %+v", got.Absent)
+	}
+	// And the same assignment without the provider is absent: what binds it later is only the
+	// provider being assigned, with no act on grafana (ADR 0330 §7).
+	before, err := Resolve(optionalShelf(), []string{"grafana", "zsh"}, reachable(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(before.Absent) != 1 || before.Absent[0].Requirement != "influxdb-api" {
+		t.Fatalf("absent before the provider was assigned: %+v", before.Absent)
+	}
+}
+
+func TestOneConsumersOptionalRequirementIsAnothersHardOne(t *testing.T) {
+	// telegraf wants influxdb-api hard: with nothing offering it, the assignment is refused as
+	// before, naming what to assign — grafana's optional does not soften telegraf's.
+	_, err := Resolve(optionalShelf(), []string{"grafana", "telegraf"}, reachable(), World{})
+	if err == nil || !strings.Contains(err.Error(), "assign influxdb") {
+		t.Fatalf("a hard requirement with no provider was not refused naming the candidate: %v", err)
+	}
+	// And the refusal names telegraf, whose remedy it is, not grafana, which met the name first.
+	if !strings.Contains(err.Error(), "wanted by telegraf") {
+		t.Errorf("the refusal does not name the module that wants it hard: %v", err)
+	}
+	// And a module pulled in later (suite → editor) that wants the shell hard installs it, even
+	// though grafana, met first, wanted it only optionally — and grafana is then bound to it.
+	got, err := Resolve(optionalShelf(), []string{"grafana", "suite"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if have := strings.Join(names(got), " "); !strings.Contains(have, "zsh") {
+		t.Fatalf("a hard requirement met after an optional one was not installed: %s", have)
+	}
+	for _, a := range got.Absent {
+		if a.Requirement == "shell" {
+			t.Fatalf("the shell is installed and still listed absent: %+v", got.Absent)
+		}
+	}
+}
+
+func TestAHardRequirementWithNoProviderIsStillRefused(t *testing.T) {
+	_, err := Resolve(optionalShelf(), []string{"telegraf"}, reachable(), World{})
+	if err == nil || !strings.Contains(err.Error(), "influxdb") {
+		t.Fatalf("got %v", err)
+	}
+}
+
+func optionalModule(resources string) string {
+	return `{"module":"grafana","version":"1",
+		"requires":["route",{"name":"influxdb-api","optional":true}],
+		"secrets":{"influxdb-api":"/var/lib/grafana/influxdb-api"},
+		"resources":[` + resources + `]}`
+}
+
+func TestTheModuleCheckRefusesAnOptionalPlaceholderThatCouldRenderEmpty(t *testing.T) {
+	refused := map[string]string{
+		"a placeholder without a default": `{"id":"ds","type":"file","path":"/a","mode":"0644",
+			"content":"url: ${bound:influxdb-api:at}"}`,
+		"a secret outside an only-when-bound file": `{"id":"s","type":"file","path":"/a","mode":"0400",
+			"content":"${secret:influxdb-api}"}`,
+		"only-when-bound on a hard requirement": `{"id":"r","type":"file","path":"/a","mode":"0644",
+			"content":"x","only-when-bound":"route"}`,
+		"only-when-bound on something not required": `{"id":"r","type":"file","path":"/a","mode":"0644",
+			"content":"x","only-when-bound":"mqtt-topic"}`,
+		"only-when-bound on a directory": `{"id":"d","type":"directory","mode":"0700",
+			"only-when-bound":"influxdb-api"}`,
+		"a default on a hard requirement": `{"id":"r","type":"file","path":"/a","mode":"0644",
+			"content":"${bound:route:name|default:x}"}`,
+	}
+	for what, resource := range refused {
+		if _, err := ParseManifest([]byte(optionalModule(resource))); err == nil {
+			t.Errorf("%s passed the module check", what)
+		} else if what == "a placeholder without a default" && !strings.Contains(err.Error(), "|default:") {
+			t.Errorf("the refusal does not say how to write it: %v", err)
+		}
+	}
+	accepted := map[string]string{
+		"a placeholder with a default": `{"id":"ds","type":"file","path":"/a","mode":"0644",
+			"content":"url: ${bound:influxdb-api:at|default:none}"}`,
+		"a placeholder and a secret inside an only-when-bound file": `{"id":"ds","type":"file","path":"/a",
+			"mode":"0400","content":"url: ${bound:influxdb-api:at}\npassword: ${secret:influxdb-api}",
+			"only-when-bound":"influxdb-api"}`,
+	}
+	for what, resource := range accepted {
+		if _, err := ParseManifest([]byte(optionalModule(resource))); err != nil {
+			t.Errorf("%s was refused: %v", what, err)
+		}
+	}
+}
+
+func absentGrafana(t *testing.T, absent bool) Resolution {
+	t.Helper()
+	m := mustParse(t, optionalModule(`
+		{"id":"env","type":"file","path":"/var/lib/grafana/env","mode":"0644",
+		 "content":"INFLUX=${bound:influxdb-api:at|default:none}:${bound:influxdb-api:port|default:0}\n"},
+		{"id":"ds","type":"file","path":"/var/lib/grafana/ds.yaml","mode":"0400",
+		 "content":"url: ${bound:influxdb-api:at}\npassword: ${secret:influxdb-api}\n","only-when-bound":"influxdb-api"}`))
+	m.Requires = []string{"influxdb-api"}
+	m.Binds = map[string]string{"influxdb-api": "/var/lib/grafana/influxdb.json"}
+	r := Resolution{Node: "workstation", Modules: []Manifest{m}}
+	if absent {
+		r.Absent = []Absent{{Consumer: "grafana", Requirement: "influxdb-api"}}
+	} else {
+		r.Needs = []Needed{{Name: "influxdb-api", From: "anchor", At: "anchor.internal", For: "grafana",
+			Module: "influxdb", Sealed: "sealed-influx", Serves: map[string]any{"port": float64(8086)}}}
+	}
+	return r
+}
+
+func TestAnAbsentRequirementIsComposedWithItsDefaultsAndWithoutItsFiles(t *testing.T) {
+	out, err := absentGrafana(t, true).Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	env := fileNamed(out, "grafana.env")
+	if env == nil || env["content"] != "INFLUX=none:0\n" {
+		t.Fatalf("the defaults were not rendered: %v", env)
+	}
+	for _, id := range []string{"grafana.ds", "grafana." + SecretID("influxdb-api"), "grafana." + BoundID("influxdb-api")} {
+		if fileNamed(out, id) != nil {
+			t.Errorf("%s was delivered while influxdb-api is absent (ADR 0330 §5, §6)", id)
+		}
+	}
+	for _, r := range out {
+		if _, has := r[OnlyWhenBound]; has {
+			t.Errorf("%v carries %s to the node-engine, which knows no such field", r["id"], OnlyWhenBound)
+		}
+	}
+}
+
+func TestABoundOptionalRequirementIsComposedAsAHardOne(t *testing.T) {
+	out, err := absentGrafana(t, false).Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if env := fileNamed(out, "grafana.env"); env == nil || env["content"] != "INFLUX=anchor.internal:8086\n" {
+		t.Fatalf("the bound values were not rendered: %v", env)
+	}
+	ds := fileNamed(out, "grafana.ds")
+	if ds == nil {
+		t.Fatalf("the only-when-bound file was left out while bound: %v", out)
+	}
+	if _, has := ds[OnlyWhenBound]; has {
+		t.Errorf("the file carries %s to the node-engine", OnlyWhenBound)
+	}
+	for _, id := range []string{"grafana." + SecretID("influxdb-api"), "grafana." + BoundID("influxdb-api")} {
+		if fileNamed(out, id) == nil {
+			t.Errorf("%s was not delivered while bound", id)
+		}
+	}
+}

internal/catalogue/replay166_test.go

@@ -0,0 +1,44 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// Replay of novox/hq issue 166: every soft dependency had become a hard requirement. grafana runs without a
+// data source, yet a manifest could not say so: a mesh without influxdb could not register a grafana that
+// said its influxdb-api was optional, and with influxdb only in the catalogue, assigning grafana installed
+// influxdb for it. Written only with what the catalogue had before its fix (mesh-controller #281):
+// ParseManifest, Resolve, and the resolve tests' shelf, reachable machine and names, so it is laid over the
+// commit before.
+func TestReplay166(t *testing.T) {
+	grafana, err := ParseManifest([]byte(`{"module":"grafana","version":"1",
+		"requires":[{"name":"influxdb-api","optional":true}]}`))
+	if err != nil {
+		t.Fatalf("a manifest cannot say grafana runs without influxdb-api: %v", err)
+	}
+	catalogue := shelf(
+		Manifest{Module: "influxdb", Version: "1", Provides: FromAnywhere("influxdb-api")},
+		grafana,
+	)
+	// Nothing in the mesh runs influxdb; it is only in the catalogue.
+	got, err := Resolve(catalogue, []string{"grafana"}, reachable(), World{})
+	if err != nil {
+		t.Fatalf("grafana could not be assigned on a mesh without influxdb: %v", err)
+	}
+	if have := strings.Join(names(got), " "); have != "grafana" {
+		t.Fatalf("assigning grafana put %s on the machine; nothing is installed for an optional requirement", have)
+	}
+	if len(got.Needs) != 0 {
+		t.Fatalf("grafana was given a binding with nothing providing it: %+v", got.Needs)
+	}
+	// And once influxdb runs somewhere, grafana binds to it as before.
+	got, err = Resolve(catalogue, []string{"grafana"}, reachable(), World{Offered: map[string][]Provider{
+		"influxdb-api": {{Node: "anchor", At: "anchor.internal", Module: "influxdb"}}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got.Needs) != 1 || got.Needs[0].From != "anchor" || got.Needs[0].For != "grafana" {
+		t.Fatalf("grafana did not bind to influxdb on anchor: %+v", got.Needs)
+	}
+}

internal/catalogue/replay279_test.go

@@ -0,0 +1,36 @@
+package catalogue
+
+import "testing"
+
+// Replay of novox/hq issue 279 (2026-10-06): the media managers' recycle-bin folders were declared owned by
+// a literal user and group, and on a machine whose puid and pgid settings named another account the apps
+// refused them as not writable. A directory's owner could not follow the account its module runs as. Written
+// only with what the catalogue had before its fix (mesh-controller #260): Compose, LeftOut, a setting layer,
+// and the adoption tests' anchor, so it is laid over the commit before.
+func TestReplay279(t *testing.T) {
+	r := anAdoptedAnchor()
+	r.Modules = append(r.Modules, 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"},
+		},
+	})
+	with := anchorRendering(false)
+	with.Settings["sonarr"] = []Layer{{From: "node anchor", Values: map[string]any{"puid": "1001", "pgid": "2000"}}}
+	composed, err := r.Compose(with)
+	if err != nil {
+		t.Fatalf("the machine did not compose: %v", err)
+	}
+	if why, left := composed.LeftOut["sonarr"]; left {
+		t.Fatalf("the module was left out: %s", why)
+	}
+	got, ok := byID(composed.Resources)["sonarr.recycle-bin"]
+	if !ok {
+		t.Fatal("the recycle bin was not declared")
+	}
+	if got["owner"] != "1001:2000" {
+		t.Fatalf("the recycle bin reaches the node-engine owned by %v, not the account the module runs as (1001:2000)", got["owner"])
+	}
+}

internal/catalogue/replay412_test.go

@@ -0,0 +1,36 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// Replay of novox/hq issue 412 (2026-10-10): which module owns /etc/hosts was enforced only after the fact,
+// when two modules on one machine declared it; a module that did not claim node-hostname could declare
+// /etc/hosts, and a module could claim node-hostname declaring none of its paths, and nothing refused either.
+// Written only with what the catalogue had before its fix (mesh-controller #267): CatalogueProblems, Shelf,
+// SeatNamed and CanHold, so it is laid over the commit before.
+func TestReplay412(t *testing.T) {
+	stranger := Manifest{Module: "stranger", Version: "1", Resources: []map[string]any{
+		{"id": "hosts", "type": "file", "path": "/etc/hosts", "into": "block", "content": "10.0.0.1 x\n"}}}
+	got := strings.Join(CatalogueProblems(Shelf{"stranger": stranger}), "; ")
+	if !strings.Contains(got, "node-hostname") {
+		t.Errorf("a module declaring /etc/hosts without claiming node-hostname was not refused: %q", got)
+	}
+
+	seat, ok := SeatNamed("node-hostname")
+	if !ok {
+		t.Fatal("no node-hostname seat")
+	}
+	holder := Manifest{Module: "names", Version: "1", Claims: []Claim{{Name: "node-hostname", Scope: ScopeNode,
+		Serves: []string{"entries", "add", "remove"}}}}
+	err := CanHold(holder, seat)
+	if err == nil {
+		t.Fatal("a holder of node-hostname declaring neither /etc/hosts nor /etc/hostname was accepted")
+	}
+	for _, want := range []string{"/etc/hosts", "/etc/hostname"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("the refusal does not name %s: %v", want, err)
+		}
+	}
+}

internal/catalogue/resolve.go

@@ -111,6 +111,9 @@ type Provider struct {
 	// (novox/hq to-be 23), and the pair is what tells the holder of a seat apart from another module
 	// providing the same thing (ADR 0110).
 	Module string
+	// LeftOut says each served key left out of Serves because that node composes no name it asks
+	// for (novox/hq ADR 0346 §3): said under each consumer's need.
+	LeftOut []string
 }
 
 // Held is a claim somebody already has, used for the scopes wider than one node.
@@ -183,6 +186,10 @@ type Resolution struct {
 	// that keeps its data, and did not (novox/hq ADR 0232): it stays bound where its data is, and the
 	// controller raises an urgent condition naming the move until a person pins one or the other.
 	Kept []KeptBinding
+	// Absent is every optional requirement of this node's modules that nothing assigned answers
+	// (novox/hq ADR 0330 §3): left unbound rather than refused, with nothing installed for it, and
+	// listed by `plan` and `node` (§7). It binds on the first composition after a provider is assigned.
+	Absent []Absent
 }
 
 // Unhostable is one directly-assigned module the machine cannot run.
@@ -226,6 +233,9 @@ type Needed struct {
 	// state, not a consumer missing its key. Set by the plan, which is the only layer that knows a
 	// licence's manager; empty for every consumer.
 	Manager bool
+	// LeftOut says each served key the provider left out, because its machine composes no name the
+	// value asks for (novox/hq ADR 0346 §3).
+	LeftOut []string
 	// Module is the providing module on From, empty for a need answered by a record or by nothing
 	// that serves it. A provider is a (node, module) pair (novox/hq to-be 23), and a binding to data
 	// is a binding to the pair (ADR 0232).
@@ -374,12 +384,80 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 	// identical lines before realising there is none.
 	reported := map[string]bool{}
 
-	for len(queue) > 0 {
+	// **An optional requirement is settled last** (novox/hq ADR 0330). Whether a name is optional is
+	// a question about every module that wants it, and a module pulled in later may want it hard; so
+	// a name only optional modules want so far is put aside until the walk has nothing else, and only
+	// then, if still nobody wants it hard, settled by the optional rule: bound to a provider that is
+	// already assigned or reachable, exactly as a hard one, and otherwise absent — never refused,
+	// and never answered by installing anything.
+	var deferred []string
+	settling := map[string]bool{}
+	absent := map[string]bool{}
+	wantedHard := func(want string) bool {
+		for _, name := range order {
+			if catalogue[name].wantsHard(want) {
+				return true
+			}
+		}
+		return false
+	}
+	wantedOptionally := func(want string) bool {
+		for _, name := range order {
+			if catalogue[name].IsOptional(want) {
+				return true
+			}
+		}
+		return false
+	}
+	leaveAbsent := func(want string) {
+		absent[want] = true
+		reported[want] = true
+	}
+
+	for {
+		if len(queue) == 0 {
+			if len(deferred) == 0 {
+				break
+			}
+			// What a module chosen since wants hard goes back to the walk, which may install for
+			// it; only when none does is the rest settled, since settling installs nothing and so
+			// can change no other name's answer.
+			var hard, optional []string
+			for _, d := range deferred {
+				if wantedHard(d) {
+					hard = append(hard, d)
+				} else {
+					optional = append(optional, d)
+				}
+			}
+			if len(hard) > 0 {
+				queue, deferred = hard, optional
+				continue
+			}
+			for _, d := range optional {
+				settling[d] = true
+			}
+			queue, deferred = optional, nil
+		}
 		want := queue[0]
 		queue = queue[1:]
 		if chosen[want] || reported[want] {
 			continue
 		}
+		if !settling[want] && because[want] != "assigned" && !wantedHard(want) && wantedOptionally(want) {
+			deferred = append(deferred, want)
+			continue
+		}
+		// Walked as a hard requirement: a refusal names a module that wants it hard, never one that
+		// wanted it only optionally and met it first — whose remedy it is not.
+		if first, known := catalogue[because[want]]; !settling[want] && known && !first.wantsHard(want) {
+			for _, name := range order {
+				if catalogue[name].wantsHard(want) {
+					because[want] = name
+					break
+				}
+			}
+		}
 		// Already answered by something in the set. This is the case that makes assigning zsh do
 		// what a person meant by it.
 		//
@@ -483,6 +561,12 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 		if brokered[want] {
 			reported[want] = true
 			where := world.Offered[want]
+			if settling[want] && len(where) == 0 {
+				// Nothing assigned anywhere answers it: absent, and nothing is put on a machine
+				// for it (ADR 0330 §3), however few modules in the catalogue could.
+				leaveAbsent(want)
+				continue
+			}
 			names := providerNames(where)
 			take := func(p Provider) {
 				if node.At != "" && p.At == "" || node.At == "" && p.At != "" || node.At == "" && p.At == "" {
@@ -504,7 +588,7 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 					bound = pm.IdentityBoundOf(want)
 				}
 				needs = append(needs, Needed{Name: want, From: p.Node, At: p.At, Module: p.Module,
-					Serves: p.Serves, For: because[want], SharedOwn: shared, Identity: bound})
+					Serves: p.Serves, For: because[want], SharedOwn: shared, Identity: bound, LeftOut: p.LeftOut})
 			}
 			switch {
 			case world.Unchecked:
@@ -579,6 +663,10 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 		// research 026 found. Another node's provider never counts — node scope is never brokered.
 		if machineReach[want] && !isModule(catalogue, want) {
 			reported[want] = true
+			if settling[want] {
+				leaveAbsent(want)
+				continue
+			}
 			if world.Unchecked {
 				// The first pass's refusals take a machine off the network; the second says it.
 				continue
@@ -591,6 +679,13 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 		}
 
 		candidates := offers[want]
+		if settling[want] && !(len(candidates) == 0 && len(world.Licences[want]) > 0) {
+			// Not answered by anything in this node's set, and only installing could answer it
+			// here — which is never done for an optional requirement (ADR 0330 §3), not even
+			// for the only candidate. A licence record still answers it, in the post-pass.
+			leaveAbsent(want)
+			continue
+		}
 		switch len(candidates) {
 		case 0:
 			if len(world.Licences[want]) > 0 {
@@ -724,7 +819,8 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 	resolution := Resolution{Node: node.Name, At: node.At, PublicDomain: node.PublicDomain,
 		Account: node.Account, AccountHome: node.AccountHome, AgentAccount: node.AgentAccount,
 		AgentAccountHome: node.AgentAccountHome, Capabilities: node.Capabilities,
-		Because: because, Needs: needs, Unhostable: unhostable, Kept: kept}
+		Because: because, Needs: needs, Unhostable: unhostable, Kept: kept,
+		Absent: absentOf(absent, order, catalogue)}
 	for _, n := range providersFirst(order, catalogue) {
 		resolution.Modules = append(resolution.Modules, catalogue[n])
 	}

internal/catalogue/resolver_manifests_test.go

@@ -63,13 +63,17 @@ func TestTheResolverForwardsToFixedUpstreamsAndNeverReadsResolvConf(t *testing.T
 			t.Errorf("the resolver's configuration lacks %q:\n%s", strings.TrimSpace(want), config)
 		}
 	}
-	// Bound to its addresses, one way or the other. mesh-catalog PR 161 (novox/hq issue 348) moves it from
-	// bind-dynamic, which closed the private address's listener when a bridge teardown failed its re-read
-	// of the machine's addresses, to bind-interfaces. This test reads the catalogue beside it, which may be
-	// on either side of that merge, so it takes both; once the catalogue's main has it, bind-dynamic is
-	// refused here.
-	if !strings.Contains(config, "\nbind-interfaces\n") && !strings.Contains(config, "\nbind-dynamic\n") {
-		t.Errorf("the resolver's configuration binds neither by bind-interfaces nor by bind-dynamic:\n%s", config)
+	// Bound to each address once, at start, and never by bind-dynamic (novox/hq issue 348): bind-dynamic
+	// re-reads the machine's addresses on every change of any link and closes each listener that reading
+	// did not find, and a reading made while the container runtime tears down a bridge's virtual links
+	// fails, so the private address was left unbound for twenty minutes, the daemon running and silent.
+	// The catalogue's main binds once since mesh-catalog PR 161 (105cc7c0).
+	if !strings.Contains(config, "\nbind-interfaces\n") {
+		t.Errorf("the resolver's configuration does not bind its addresses once (bind-interfaces):\n%s", config)
+	}
+	if strings.Contains(config, "\nbind-dynamic\n") {
+		t.Errorf("the resolver's configuration says bind-dynamic, which closes its listeners when a bridge is "+
+			"torn down (novox/hq issue 348):\n%s", config)
 	}
 	// By address and never by interface: dnsmasq admits a query by the interface it arrives on
 	// when told one, and a container's query to the private address arrives on the runtime's

internal/catalogue/seat_dependencies.go

@@ -331,12 +331,13 @@ func UnassignRefusal(catalogue map[string]Manifest, node string, assigned, remov
 }
 
 // CollisionRefusal is why assigning `adding` beside `assigned` is refused for what two modules
-// would both declare, or nothing (novox/hq ADR 0210 §1, 04-ISSUES/235).
+// would both declare, or nothing (novox/hq ADR 0210 §1, 04-ISSUES/235): one path, unit or name, or a package one
+// declares present and another absent. A package several modules declare present is no collision (ADR 0303).
 //
 // **Refused, not kept like an unresolved provision.** An assignment is otherwise kept when the
 // node does not resolve, because assignment is not an ordering: a consumer's provider can follow.
 // A collision is not an order anything can complete — no further assignment makes two owners of one
-// package one owner — and kept, it leaves the node unresolvable, so the next push of anything drops
+// file one owner — and kept, it leaves the node unresolvable, so the next push of anything drops
 // it from the mesh. Only collisions involving a module being added are refused; one already on the
 // node is `status`'s, and refusing an unrelated assignment for it would block its own remedy.
 func CollisionRefusal(catalogue map[string]Manifest, node string, assigned, adding []string) error {

internal/catalogue/served_own_names.go

@@ -0,0 +1,202 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// A provider may tell its consumers its own composed names (novox/hq ADR 0346, issue 624).
+//
+// **The name is already the mesh's.** A module contributes a label to a requirement — a route — and
+// the mesh joins it with the providing machine's domains; the module reads the result in its own files
+// as `${bound:<requirement>:name}` (novox/hq 04-ISSUES/122). Its consumers could not be told it: a
+// served value named only the consumer (ADR 0202) and settings. The forge's package registry writes
+// every tarball at its public name, and a consumer that must trust that name had no source for it but a
+// second copy kept by hand. So a served value may say `${bound:<requirement>:<name>}` for a requirement
+// the provider contributes to, and the mesh fills it from the same composition the provider's own files
+// and its proxy receive.
+//
+// **A name the providing machine does not compose leaves the key out** (ADR 0346 §3): a machine with
+// no public domain has no public name to give, and an empty value or a refusal would be worse than a
+// consumer told nothing — a refused provider machine takes every provision it offers down with it. The
+// plan says which key was left out, and why, on the provider's machine and under each consumer's need.
+
+// ownNameFacts are what a served value may name of the provider's own composition: the names, as its
+// own files read them (withOwnNames).
+var ownNameFacts = []string{"name", "internal-name"}
+
+// requirementsContributedTo is every requirement m contributes to, sorted.
+func requirementsContributedTo(m Manifest) []string {
+	seen := map[string]bool{}
+	for to := range m.Contributes {
+		seen[to] = true
+	}
+	for to := range m.ContributesMany {
+		seen[to] = true
+	}
+	out := make([]string, 0, len(seen))
+	for to := range seen {
+		out = append(out, to)
+	}
+	sort.Strings(out)
+	return out
+}
+
+// ownNameKeys is every name a served value of m may say for one requirement it contributes to:
+// `name` and `internal-name`, and `name-<local>` and `internal-name-<local>` for each local name it
+// contributes under.
+func ownNameKeys(m Manifest, to string) []string {
+	keys := append([]string{}, ownNameFacts...)
+	for _, local := range sortedKeys(m.ContributesMany[to]) {
+		for _, fact := range ownNameFacts {
+			keys = append(keys, fact+"-"+local)
+		}
+	}
+	return keys
+}
+
+// ServedOwnNames fills the provider's own composed names into what it serves one provision's
+// consumers, from this resolution's composition of the provider's machine (ADR 0346).
+//
+// A value naming a name this machine does not compose is left out, with its key, and said. The map is
+// copied only when something changes, as ServedTo does: the caller's may be the manifest's.
+func (r Resolution) ServedOwnNames(m Manifest, provision string, serves map[string]any, layers []Layer) (
+	map[string]any, []string, error) {
+	var asking []string
+	for _, key := range sortedAnyKeys(serves) {
+		if text, ok := serves[key].(string); ok && bound.MatchString(text) {
+			asking = append(asking, key)
+		}
+	}
+	if len(asking) == 0 {
+		return serves, nil, nil
+	}
+	own := map[string]map[string]string{}
+	for _, to := range requirementsContributedTo(m) {
+		names, err := r.ownNames(m, to, layers)
+		if err != nil {
+			return nil, nil, err
+		}
+		values := map[string]string{}
+		withOwnNames(values, names)
+		own[to] = values
+	}
+	out := make(map[string]any, len(serves))
+	for k, v := range serves {
+		out[k] = v
+	}
+	var said []string
+	for _, key := range asking {
+		text := serves[key].(string)
+		var missing string
+		filled := bound.ReplaceAllStringFunc(text, func(token string) string {
+			parts := bound.FindStringSubmatch(token)
+			if value := own[parts[1]][parts[2]]; value != "" && parts[3] == "" {
+				return value
+			}
+			if missing == "" {
+				missing = token
+			}
+			return token
+		})
+		if missing != "" {
+			delete(out, key)
+			said = append(said, fmt.Sprintf(
+				"%s serves %s without %q: it names %s, and %s composes no such name for %s (it has no "+
+					"public domain, or the endpoint is not reached publicly) (novox/hq ADR 0346)",
+				m.Module, provision, key, missing, orHere(r.Node), m.Module))
+			continue
+		}
+		out[key] = filled
+	}
+	return out, said, nil
+}
+
+func orHere(node string) string {
+	if node == "" {
+		return "this machine"
+	}
+	return node
+}
+
+// ServedLeftOut is what the providers in this node's own set leave out of what they serve, because
+// this machine composes no name a served value asks for (ADR 0346 §3): said on the provider's machine,
+// where the remedy is.
+func (r Resolution) ServedLeftOut(settings SettingsBy) []string {
+	var said []string
+	for _, m := range r.Modules {
+		for _, provision := range sortedServes(m.Serves) {
+			_, lines, err := r.ServedOwnNames(m, provision, m.Serves[provision], WithDefaults(m, settings[m.Module]))
+			if err != nil {
+				said = append(said, fmt.Sprintf("%s serves %s, and its own names could not be composed: %v",
+					m.Module, provision, err))
+				continue
+			}
+			said = append(said, lines...)
+		}
+	}
+	return said
+}
+
+// checkServedOwnNames refuses a served `${bound:…}` that names a requirement the module does not
+// contribute to, a fact other than its own names, or a local name it does not contribute under; and
+// one with a default, since a served value is left out rather than given one (ADR 0346 §3, §4).
+func checkServedOwnNames(m Manifest, provision, key, text string) []string {
+	var problems []string
+	contributes := requirementsContributedTo(m)
+	for _, parts := range bound.FindAllStringSubmatch(text, -1) {
+		to, fact, fallback := parts[1], parts[2], parts[3]
+		says := fmt.Sprintf("%s serves %s, and the value it serves as %q says %s", m.Module, provision, key, parts[0])
+		switch {
+		case fallback != "":
+			problems = append(problems, says+": a served name takes no default; one the machine does not "+
+				"compose leaves the key out (novox/hq ADR 0346)")
+		case !oneOf(contributes, to):
+			problems = append(problems, fmt.Sprintf(
+				"%s, and %s contributes to %s: a served value names only the provider's own names "+
+					"(novox/hq ADR 0346)", says, m.Module, orNothing(quoted(contributes))))
+		case !oneOf(ownNameKeys(m, to), fact):
+			problems = append(problems, fmt.Sprintf("%s, and what %s is called through %s is %s (novox/hq ADR 0346)",
+				says, m.Module, to, strings.Join(ownNameKeys(m, to), ", ")))
+		}
+	}
+	return problems
+}
+
+func quoted(values []string) []string {
+	out := make([]string, len(values))
+	for i, v := range values {
+		out[i] = fmt.Sprintf("%q", v)
+	}
+	return out
+}
+
+// nestedOwnNames refuses a `${bound:…}` inside a served list or object: only a string value of its own is
+// filled (ServedOwnNames), so a nested one would reach the consumer as the placeholder (ADR 0346 §5).
+func nestedOwnNames(m Manifest, provision, key string, value any) []string {
+	var found []string
+	var walk func(v any)
+	walk = func(v any) {
+		switch x := v.(type) {
+		case string:
+			found = append(found, bound.FindAllString(x, -1)...)
+		case []any:
+			for _, e := range x {
+				walk(e)
+			}
+		case map[string]any:
+			for _, k := range sortedAnyKeys(x) {
+				walk(x[k])
+			}
+		}
+	}
+	walk(value)
+	if len(found) == 0 {
+		return nil
+	}
+	return []string{fmt.Sprintf(
+		"%s serves %s, and the value it serves as %q holds %s inside a list or an object: a provider's own "+
+			"name is filled only in a string value of its own (novox/hq ADR 0346)",
+		m.Module, provision, key, strings.Join(found, ", "))}
+}

internal/catalogue/served_own_names_test.go

@@ -0,0 +1,168 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// novox/hq ADR 0346, issue 624: the forge's package registry writes every tarball at its public name,
+// and the lab, its consumer, must trust that name and no other. The name is the mesh's own composition
+// of the forge's route, which the forge's files read as ${bound:route:name-web}; a consumer can now be
+// served it.
+
+const aRegistryForge = `{"module":"forge","version":"1","requires":["route"],
+  "provides":[{"name":"npm-package-registry","scope":"mesh"}],
+  "contributes":{"route":{"web":{"label":"git","port":3000}}},
+  "serves":{"npm-package-registry":{"scheme":"http","port":3000,"npm-path":"/api/packages/novox/npm/",
+    "public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"}}}`
+
+func aForgeManifest(t *testing.T) Manifest {
+	t.Helper()
+	m, err := ParseManifest([]byte(aRegistryForge))
+	if err != nil {
+		t.Fatal(err)
+	}
+	return m
+}
+
+func TestAProviderServesItsOwnComposedName(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home", PublicDomain: "example.org"}
+	got, said, err := r.ServedOwnNames(m, "npm-package-registry", m.Serves["npm-package-registry"], nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got["public-root"] != "https://git.example.org/api/packages/novox/npm/" || len(said) != 0 {
+		t.Fatalf("the public root is the route's composed name: %v, said %v", got, said)
+	}
+	if got["npm-path"] != "/api/packages/novox/npm/" || got["port"] != float64(3000) {
+		t.Fatalf("the rest is served as it was: %v", got)
+	}
+	if m.Serves["npm-package-registry"]["public-root"] != "https://${bound:route:name-web}/api/packages/novox/npm/" {
+		t.Fatal("the manifest's own map was rewritten")
+	}
+}
+
+func TestANameTheMachineDoesNotComposeLeavesTheKeyOutAndSaysSo(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home"} // no public domain
+	got, said, err := r.ServedOwnNames(m, "npm-package-registry", m.Serves["npm-package-registry"], nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, there := got["public-root"]; there {
+		t.Fatalf("a name not composed is left out, never written as the placeholder or empty: %v", got)
+	}
+	if got["npm-path"] == nil {
+		t.Fatalf("only the key that names it is left out: %v", got)
+	}
+	if len(said) != 1 || !strings.Contains(said[0], `forge serves npm-package-registry without "public-root"`) ||
+		!strings.Contains(said[0], "home composes no such name") {
+		t.Fatalf("said: %v", said)
+	}
+	if lines := (Resolution{Node: "home", Modules: []Manifest{m}}).ServedLeftOut(nil); len(lines) != 1 {
+		t.Fatalf("the plan on the provider's machine says it: %v", lines)
+	}
+	if lines := (Resolution{Node: "home", PublicDomain: "example.org", Modules: []Manifest{m}}).ServedLeftOut(nil); len(lines) != 0 {
+		t.Fatalf("nothing to say when the name is composed: %v", lines)
+	}
+}
+
+// On the provider's own machine the consumer is served the same name (ADR 0346 §2).
+func TestAConsumerBesideTheProviderIsServedItsName(t *testing.T) {
+	m := aForgeManifest(t)
+	consumer := Manifest{Module: "lab", Version: "1", Requires: []string{"npm-package-registry"},
+		Binds: map[string]string{"npm-package-registry": "/var/lib/lab/package-registry.json"}}
+	node := workstation()
+	node.PublicDomain = "example.org"
+	got, err := Resolve(shelf(minimalRouteProxy(), m, consumer), []string{"route-proxy", "forge", "lab"}, node, World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	served, answered, err := got.servedOnThisMachine("npm-package-registry", Rendering{})
+	if err != nil || !answered {
+		t.Fatalf("answered %v: %v", answered, err)
+	}
+	if served["public-root"] != "https://git.example.org/api/packages/novox/npm/" {
+		t.Fatalf("served beside the provider: %v", served)
+	}
+	out, err := got.Declaration(Rendering{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var binding string
+	for _, r := range out {
+		if r["path"] == "/var/lib/lab/package-registry.json" {
+			binding, _ = r["content"].(string)
+		}
+	}
+	if !strings.Contains(binding, `"public-root": "https://git.example.org/api/packages/novox/npm/"`) &&
+		!strings.Contains(binding, `"public-root":"https://git.example.org/api/packages/novox/npm/"`) {
+		t.Fatalf("the consumer's binding carries the name:\n%s", binding)
+	}
+	if strings.Contains(binding, "${bound:") {
+		t.Fatalf("a placeholder reached the consumer:\n%s", binding)
+	}
+}
+
+// From another machine, the provider's served values carry what that machine composed, and a key it
+// left out is said on the consumer's need (ADR 0346 §2, §3).
+func TestAConsumerElsewhereIsToldWhatTheProviderLeftOut(t *testing.T) {
+	consumer := Manifest{Module: "lab", Version: "1", Requires: []string{"npm-package-registry"},
+		Binds: map[string]string{"npm-package-registry": "/var/lib/lab/package-registry.json"}}
+	node := workstation()
+	node.At = "workstation.internal"
+	world := World{Offered: map[string][]Provider{"npm-package-registry": {{Node: "home", At: "home.internal",
+		Module: "forge", Serves: map[string]any{"port": 3000},
+		LeftOut: []string{`forge serves npm-package-registry without "public-root"`}}}}}
+	got, err := Resolve(shelf(aForgeManifest(t), consumer), []string{"lab"}, node, world)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, n := range got.Needs {
+		if n.Name == "npm-package-registry" {
+			if len(n.LeftOut) != 1 {
+				t.Fatalf("the need carries what was left out: %+v", n)
+			}
+			return
+		}
+	}
+	t.Fatalf("no need: %+v", got.Needs)
+}
+
+func TestAServedNameIsCheckedWhenTheDefinitionIsRead(t *testing.T) {
+	for bad, want := range map[string]string{
+		`"public-root":"https://${bound:route:name-api}/x"`:           "what forge is called through route is name, internal-name, name-web, internal-name-web",
+		`"public-root":"https://${bound:postgres-database:name}/x"`:   `forge contributes to "route"`,
+		`"public-root":"https://${bound:route:name-web|default:x}/x"`: "takes no default",
+		`"public-root":"https://${bound:route:at}/x"`:                 "what forge is called through route",
+	} {
+		raw := strings.Replace(aRegistryForge, `"public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"`, bad, 1)
+		_, err := ParseManifest([]byte(raw))
+		if err == nil || !strings.Contains(err.Error(), want) {
+			t.Errorf("%s: want a refusal saying %q, got %v", bad, want, err)
+		}
+	}
+	nested := strings.Replace(aRegistryForge, `"public-root":"https://${bound:route:name-web}/api/packages/novox/npm/"`,
+		`"roots":["https://${bound:route:name-web}/x"]`, 1)
+	if _, err := ParseManifest([]byte(nested)); err == nil || !strings.Contains(err.Error(), "inside a list or an object") {
+		t.Errorf("a nested own name is refused, not served as the placeholder: %v", err)
+	}
+	if _, err := ParseManifest([]byte(aRegistryForge)); err != nil {
+		t.Fatalf("its own name is accepted: %v", err)
+	}
+}
+
+// The provider's contributions file carries no own name on a consumer's entry (ADR 0346 §4): only what
+// is derived for that consumer is there (ADR 0202 §5), and the provider reads its own names in its files.
+func TestAProvidersOwnNameIsNotOnItsConsumersEntry(t *testing.T) {
+	m := aForgeManifest(t)
+	r := Resolution{Node: "home", PublicDomain: "example.org", Modules: []Manifest{m}}
+	derived, err := r.derivedFor("npm-package-registry", "lab_home", "lab", "", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if derived != nil {
+		t.Fatalf("a consumer's entry carries only what was derived for it: %v", derived)
+	}
+}

internal/catalogue/setting_takes.go

@@ -70,12 +70,42 @@ func namesItsKeys(m Manifest) bool {
 // 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)
 }
 
+// WrittenSettingsProblems is ADR 0326 §3, judged only where a definition is written — the module
+// check, `module add`, a build taken in, the builder and the merge gate's registration — and never
+// where a stored one is read again (ParseManifest, a build's manifest at a commit, a module put back):
+// a module that declares a setting names the keys of every mergeable file it owns (novox/hq issue
+// 574, ADR 0164 §11 and §15). A build stored before the rule, such as betterbird's before its accounts
+// file named its keys, must still compose and still be put back; only its next change is held to it.
+//
+// Said only when none of the module's mergeable files names its keys: when one does, §2 already
+// names every file that does not, and a file is not reported twice.
+func WrittenSettingsProblems(m Manifest) []string {
+	if len(m.Settings) == 0 {
+		return nil
+	}
+	var silent []string
+	for _, r := range m.Resources {
+		how, _ := r["merge"].(string)
+		if how == "" {
+			continue
+		}
+		if _, said := r[TakesSettingsField]; said {
+			return nil
+		}
+		silent = append(silent, fmt.Sprint(r["id"]))
+	}
+	var problems []string
+	for _, id := range silent {
+		problems = append(problems, fmt.Sprintf("%s declares settings, and its mergeable %s names no %s: "+
+			"a module that declares a setting names the keys each mergeable file takes, an empty list "+
+			"for none (novox/hq ADR 0326 §3, ADR 0164 §11)", m.Module, id, TakesSettingsField))
+	}
+	return problems
+}
+
 // 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 {

internal/catalogue/setting_takes_test.go

@@ -194,3 +194,50 @@ func containsText(list []string, text string) bool {
 	}
 	return false
 }
+
+func TestAModuleThatDeclaresASettingNamesItsFilesKeys(t *testing.T) {
+	// ADR 0326 §3, ADR 0164 §15, novox/hq issue 574: only a module that declares no settings keeps
+	// today's form. One that declares a preference and owns a silent mergeable file is refused where
+	// a definition is written — and read and composed where a stored one is read again, so a build kept
+	// from before the rule is still sent and still put back.
+	declaring := func(app, sidecar []any) Manifest {
+		m := twoFiles(app, sidecar)
+		m.Resources[2]["content"] = "WORKERS=${setting:workers}\n"
+		m.Settings = map[string]SettingDeclaration{"workers": {Kind: KindPreference, Default: 4.0, Why: "a number"}}
+		return m
+	}
+	m := declaring(nil, nil)
+	problems := WrittenSettingsProblems(m)
+	if len(problems) != 2 || !containsText(problems, "mergeable app names no takes-settings") ||
+		!containsText(problems, "mergeable sidecar names no takes-settings") {
+		t.Errorf("where it is written: %v", problems)
+	}
+	if problems := TakenSettingsProblems(m); len(problems) != 0 {
+		t.Errorf("what a stored definition is read by refuses it: %v", problems)
+	}
+	raw, err := json.Marshal(map[string]any{"module": m.Module, "version": "1", "resources": m.Resources,
+		"settings": map[string]any{"workers": map[string]any{"kind": KindPreference, "default": 4, "why": "a number"}}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	read, err := ParseManifest(raw)
+	if err != nil {
+		t.Fatalf("a stored build from before the rule is not read again: %v", err)
+	}
+	if err := JudgeSettings(read, nil, false); err != nil {
+		t.Errorf("a stored definition is composed as before, and was refused: %v", err)
+	}
+
+	if problems := WrittenSettingsProblems(declaring([]any{"server"}, []any{})); len(problems) != 0 {
+		t.Errorf("every mergeable file names its keys, and was refused: %v", problems)
+	}
+	if problems := WrittenSettingsProblems(twoFiles(nil, nil)); len(problems) != 0 {
+		t.Errorf("a module declaring no setting was refused: %v", problems)
+	}
+	// One naming file and one silent: §2 names the silent one, and §3 does not name it again.
+	mixed := declaring([]any{"server"}, nil)
+	if written, taken := WrittenSettingsProblems(mixed), TakenSettingsProblems(mixed); len(written) != 0 || len(taken) != 1 {
+		t.Errorf("the silent file is reported %d times by §3 and %d by §2; want once, by §2: %v %v",
+			len(written), len(taken), written, taken)
+	}
+}

internal/catalogue/settings.go

@@ -192,6 +192,16 @@ func settle(base map[string]any, layers []Layer, protected map[string]bool, what
 					"%s sets %q on %v, and that module keeps %q for itself — it is not settable",
 					layer.From, key, what, key)
 			}
+			// **No layer replaces a secret the vault fills, at any depth** (novox/hq issue 610): a
+			// mergeable file's `${secret:<name>}` is the vault's value, and a layer that reached it —
+			// `server.secret_key` under a `server` the file takes — would put a value the operator or an
+			// agent chose where the vault's belongs. Judged against the file's own content, so it holds
+			// whatever a module's `protected` list says.
+			if at := secretReplacedBy(base[key], value, key); at != "" {
+				return nil, fmt.Errorf(
+					"%s sets %q on %v, which the vault fills (${secret:…}); a secret comes from the vault, "+
+						"never from a setting (novox/hq issues 342, 610)", layer.From, at, what)
+			}
 			merged[key] = mergeValue(merged[key], value)
 		}
 	}
@@ -576,3 +586,54 @@ func JudgeSettings(m Manifest, layers []Layer, adopted bool) error {
 	}
 	return nil
 }
+
+// secretReplacedBy is the path in a mergeable file's own content that a layer's value would replace while the
+// vault fills it — a string holding `${secret:` — or "" when the value leaves every such string as it is
+// (novox/hq issue 610). Maps merge key by key (mergeValue), so only the keys the value names are judged; any
+// other value replaces the whole of what it lands on.
+func secretReplacedBy(base, value any, at string) string {
+	if baseMap, isMap := base.(map[string]any); isMap {
+		if valueMap, also := value.(map[string]any); also {
+			keys := make([]string, 0, len(valueMap))
+			for k := range valueMap {
+				keys = append(keys, k)
+			}
+			sort.Strings(keys)
+			for _, k := range keys {
+				if found := secretReplacedBy(baseMap[k], valueMap[k], at+"."+k); found != "" {
+					return found
+				}
+			}
+			return ""
+		}
+	}
+	return secretIn(base, at)
+}
+
+// secretIn is the first path under v holding a vault placeholder, or "".
+func secretIn(v any, at string) string {
+	switch t := v.(type) {
+	case string:
+		if strings.Contains(t, "${secret:") {
+			return at
+		}
+	case map[string]any:
+		keys := make([]string, 0, len(t))
+		for k := range t {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+		for _, k := range keys {
+			if found := secretIn(t[k], at+"."+k); found != "" {
+				return found
+			}
+		}
+	case []any:
+		for i, item := range t {
+			if found := secretIn(item, fmt.Sprintf("%s[%d]", at, i)); found != "" {
+				return found
+			}
+		}
+	}
+	return ""
+}

internal/catalogue/settings_test.go

@@ -234,3 +234,29 @@ func TestAServedValueMayBeTheOperators(t *testing.T) {
 		t.Errorf("a setting a served fact asks for is not stray: %v", unused)
 	}
 }
+
+// No layer replaces a value the vault fills, at any depth (novox/hq issue 610): searxng's server.secret_key
+// sits under `server`, a key its file takes, and a layer reaching it was let through by a top-level-only check.
+func TestNoLayerReplacesAVaultSecretAtAnyDepth(t *testing.T) {
+	file := map[string]any{"id": "settings", "type": "file", "merge": MergeJSON,
+		"content": `{"server": {"secret_key": "${secret:secret}", "port": 8080}, "ui": {"theme": "simple"}, "token": "${secret:token}"}`}
+	layer := func(values map[string]any) []Layer { return []Layer{{From: "anchor", Values: values}} }
+
+	merged, err := ApplySettings(file, layer(map[string]any{"server": map[string]any{"port": float64(9000)}, "ui": map[string]any{"theme": "dark"}}))
+	if err != nil {
+		t.Fatalf("a key beside the secret was refused: %v", err)
+	}
+	if c := merged["content"].(string); !strings.Contains(c, `"secret_key": "${secret:secret}"`) || !strings.Contains(c, `"port": 9000`) {
+		t.Fatalf("the secret or the setting did not land as meant:\n%s", c)
+	}
+	for name, values := range map[string]map[string]any{
+		"the nested secret":        {"server": map[string]any{"secret_key": "chosen"}},
+		"the whole map holding it": {"server": "elsewhere"},
+		"a top-level secret":       {"token": "chosen"},
+		"the secret, emptied":      {"server": map[string]any{"secret_key": ""}},
+	} {
+		if _, err := ApplySettings(file, layer(values)); err == nil || !strings.Contains(err.Error(), "vault") {
+			t.Errorf("%s: %v, want a refusal naming the vault", name, err)
+		}
+	}
+}

internal/catalogue/terminal_keys.go

@@ -33,6 +33,10 @@ 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.
+//     **Unless the module's files name the keys they take** (novox/hq ADR 0326, ADR 0329 §5): then a mergeable
+//     file takes exactly its `takes-settings` and no other key, so those keys of a trusted file are terminal keys
+//     and the rest of the layer is not. A key no file names is stray and refused where it is set. So betterbird's
+//     `tags`, in a file nothing trusts, is set through the verb, while its `accounts` and `identities` are not.
 //  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.
@@ -109,8 +113,13 @@ func UnsaidTrust(m Manifest) []string {
 // TrustedMergeable is every mergeable file of a module not marked `"trusted": false`, by id (novox/hq issue 340).
 // A mergeable file takes any key a layer sets, not only those its content names: an empty runtime configuration a
 // provider reads takes a `url` of a caller's as surely as a declared one. So a module holding one has its whole
-// layer set at the controller's terminal; a verb may read it and change nothing.
+// layer set at the controller's terminal; a verb may read it and change nothing. A module whose mergeable files
+// name the keys they take (ADR 0326) has none here: each such file takes only its named keys, which TerminalKeys
+// holds for a trusted one (ADR 0329 §5).
 func TrustedMergeable(m Manifest) []string {
+	if namesItsKeys(m) {
+		return nil
+	}
 	var out []string
 	for _, r := range m.Resources {
 		if fmt.Sprint(r["type"]) != "file" {
@@ -135,6 +144,16 @@ func TrustedMergeable(m Manifest) []string {
 func asksFor(r map[string]any) []string {
 	content, _ := r["content"].(string)
 	asked := settingsUsed(content)
+	if how, _ := r["merge"].(string); how != "" {
+		if taken, names := takenKeys(r); names {
+			// The file takes exactly the keys it names (ADR 0326), whatever its content holds.
+			for key := range taken {
+				asked = append(asked, key)
+			}
+			sort.Strings(asked)
+			return asked
+		}
+	}
 	if how, _ := r["merge"].(string); how != "" && strings.TrimSpace(content) != "" {
 		var base map[string]any
 		if json.Unmarshal([]byte(content), &base) == nil {

internal/catalogue/terminal_settings_test.go

@@ -166,6 +166,33 @@ func TestTerminalKeysAreDerived(t *testing.T) {
 	}
 }
 
+// A module whose mergeable files name the keys they take (ADR 0326) has no whole layer at the terminal: a
+// trusted file's named keys are terminal keys, and a file nothing trusts leaves its keys to the verb (novox/hq
+// ADR 0329 §5, issue 586: betterbird's tags beside its trusted accounts, identities, calendars, address books
+// and filters). A module whose files name no keys keeps the whole layer at the terminal (issue 340).
+func TestOnlyANamedKeyOfATrustedFileIsTheTerminals(t *testing.T) {
+	betterbird := Manifest{Module: "betterbird", Resources: []map[string]any{
+		{"id": "prefs", "type": "file", "path": "/home/p/prefs.json", "merge": MergeJSON, "trusted": true,
+			TakesSettingsField: []any{"prefs"}, "content": `{"prefs": {}}`},
+		{"id": "accounts", "type": "file", "path": "/home/p/accounts.json", "merge": MergeJSON, "trusted": true,
+			TakesSettingsField: []any{"accounts"}, "content": `{"accounts": {}}`},
+		{"id": "configuration", "type": "file", "path": "/home/p/configuration.json", "merge": MergeJSON,
+			TakesSettingsField: []any{"identities", "calendars", "address-books", "filters"}, "content": `{}`},
+		{"id": "tags", "type": "file", "path": "/home/p/tags.json", "merge": MergeJSON, "trusted": false,
+			TakesSettingsField: []any{"tags"}, "content": `{"tags": {}}`}}}
+	if got := TrustedMergeable(betterbird); len(got) != 0 {
+		t.Fatalf("files that name their keys put no whole layer at the terminal: %v", got)
+	}
+	if got := strings.Join(TerminalKeys(betterbird), ","); got != "places,accesses,accounts,address-books,calendars,filters,identities,prefs" {
+		t.Fatalf("the named keys of the trusted files, unmarked counting as trusted, and not tags: %s", got)
+	}
+	silent := Manifest{Module: "keycloak", Resources: []map[string]any{{"id": "runtime", "type": "file",
+		"path": "/var/lib/kc/runtime.json", "merge": MergeJSON, "content": `{}`}}}
+	if got := TrustedMergeable(silent); len(got) != 1 {
+		t.Fatalf("a file that names no keys still takes any key, so its module's layer stays the terminal's: %v", got)
+	}
+}
+
 // A file that asks for a setting says whether what it asks is trusted (novox/hq issue 339): `trusted` is a
 // boolean, on a file alone, and a file asking for a setting without it is named.
 func TestAFileSaysWhetherItsSettingsAreTrusted(t *testing.T) {

internal/catalogue/verbs.go

@@ -217,14 +217,16 @@ var ControllerVerbs = []Verb{
 		Input: schema(map[string]string{"node": "the machine's name", "provision": "the provision"}, []string{"node", "provision"})},
 	{Name: "push", Description: "Send one machine everything it should be. With no machine named it is a push of the " +
 		"WHOLE mesh — every machine that is behind — and the answer says so first; behind says that outright. " +
-		"Answers at once that it is running, with a call id: `calls` with that id says what it sent " +
-		"(a push can reload the bus, which then refuses any answer still to come). A push by hand is a repair, " +
+		"Answers at once that it is running, with a call id: `calls` with that id says what it sent and, for a " +
+		"machine named, how that machine applied it — applied, refused with its reason, or each failed resource — " +
+		"once it reports within wait (a push can reload the bus, which then refuses any answer still to come). A push by hand is a repair, " +
 		"and says why: recorded in the hand-act log (novox/hq to-be 45 §7). A machine whose push would give a " +
 		"running module's data another directory is held and named, the others sent (novox/hq ADR 0217): read " +
 		"`plan` with diff, and name the machine with move to send it.",
 		Input: schema(map[string]string{
 			"node":   "the machine's name; without it, every machine that is behind",
 			"move":   "with node: the modules whose data may move with this push, comma-separated (optional)",
+			"wait":   "with node: how long the call waits for the machine to report how it applied what it was sent, as \"90s\" or \"2m\"; \"0\" waits for nothing; without it, the controller's setting push-wait (optional)",
 			"behind": "\"true\": every machine that is behind, the whole mesh — the same as naming none, said outright; not with node",
 			"why":    "why this is pushed by hand: recorded in the hand-act log",
 			"cause":  "the cause in a word, or a condition's kind — the word a second push for the same reason uses (optional)",
@@ -360,6 +362,12 @@ var ControllerVerbs = []Verb{
 			"register": "\"true\" to register what it builds",
 			"older":    "\"true\", with register: even though a newer build of the module is registered",
 		}, []string{"id"}, "register", "older")},
+	// novox/hq ADR 0350 §5: asked by the delivery's owner when the forge says a pull request closed unmerged.
+	{Name: "forget-checks", Description: "Let go of every build a pull request's merge checks made for its merge in " +
+		"the artifact store's scratch namespace (novox/hq ADR 0350 §5): asked when it closed unmerged; a merged one's go " +
+		"when the walk answering its merge ends, and any check build goes after a week.",
+		Input: schema(map[string]string{"owner": "the repository's owner", "repo": "the repository",
+			"number": "the pull request's number"}, []string{"owner", "repo", "number"})},
 	{Name: "kill", Description: "End a build where it runs: the machine that took it stops its commands and containers and " +
 		"announces it failed, killed by hand — settled, never handed to another machine.",
 		Input: schema(map[string]string{"id": "the build's id"}, []string{"id"})},