Reach asks for names on a routed endpoint, and its port stays the manifest's

A routed endpoint's port is how the proxy reaches it and nothing else (ADR 0045):
a public service listens from the mesh, only the proxy reaches it, and it is
exposed by name. So reach on a routed endpoint asks for names, and the port keeps
what the manifest said; on an unrouted one — git over ssh, a mail port, the bus —
it governs the port, because there is no name and the port is the only way in.

Found by trying to express a real module rather than by review: routed name public
because browsers post to it, machine-side port private because it serves a
dashboard in cleartext. Under one value for both there was no way to say it, and
'public' would have reopened a port narrowed an hour earlier.

novox/hq ADR 0138, corrected in place the same day.

internal/catalogue/build.go

@@ -153,6 +153,26 @@ func (b *Build) problems(module string) []string {
 					"%s: %q is a bundle and says no language, so nothing can choose a compiler "+
 						"for it", module, a.Name))
 			}
+			// **A system, for a language that compiles to a binary** (novox/hq ADR 0142). A binary
+			// is pinned to one operating system at link time so a host refuses to touch a machine
+			// it was not built for (novox/hq ADR 0005); an artifact that says nothing would be
+			// compiled for whatever the build machine happened to be, which reads as portable and
+			// is not.
+			if compiled := compilesToABinary(a.Language); compiled && strings.TrimSpace(a.System) == "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is compiled to a binary and says no system, so it would be built for "+
+						"whatever the build machine happens to be. Declare one artifact per "+
+						"system: %s", module, a.Name, spokenSystems()))
+			} else if !compiled && strings.TrimSpace(a.System) != "" {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q names the system %q and is written in %q, which compiles to code that "+
+						"runs anywhere — a system that decides nothing reads as though it did",
+					module, a.Name, a.System, a.Language))
+			} else if compiled && !knownSystem(a.System) {
+				problems = append(problems, fmt.Sprintf(
+					"%s: %q is built for %q, and a system is %s",
+					module, a.Name, a.System, spokenSystems()))
+			}
 		} else {
 			if a.From == "" {
 				problems = append(problems, fmt.Sprintf(
@@ -193,3 +213,42 @@ func oneOrOther(n int) string {
 	}
 	return "them"
 }
+
+// Systems the mesh builds binaries for, which is the set a host may be pinned to (novox/hq ADR 0005).
+//
+// **A closed list, and the host's own, not the compiler's.** These are not the values a Go toolchain
+// would call an operating system — the difference between two of them is a C library, not a kernel.
+// They are what a machine reports itself to be and what a host is linked to refuse, so the list that
+// matters is the one the host understands.
+var systems = []string{"alpine", "android", "arch"}
+
+// knownSystem is whether the mesh builds for it.
+func knownSystem(system string) bool {
+	want := strings.ToLower(strings.TrimSpace(system))
+	for _, s := range systems {
+		if s == want {
+			return true
+		}
+	}
+	return false
+}
+
+// spokenSystems is the list as a refusal says it, so a reader is one edit from right.
+func spokenSystems() string {
+	return strings.Join(systems, ", ")
+}
+
+// compilesToABinary is whether this language's bundle is a binary for one operating system rather
+// than code that runs wherever its interpreter does.
+//
+// **Asked of the language, not of the artifact.** A module says what it is written in; what that
+// implies is the mesh's to know, exactly as the compiler is (novox/hq ADR 0142). Asking the artifact
+// would let two artifacts in one language disagree about whether they are portable.
+func compilesToABinary(language string) bool {
+	switch strings.ToLower(strings.TrimSpace(language)) {
+	case "go":
+		return true
+	default:
+		return false
+	}
+}

internal/catalogue/build_system_test.go

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

internal/catalogue/declaration.go

@@ -897,6 +897,35 @@ func (r Resolution) Rules(with Rendering) ([]Rule, error) {
 		if err != nil {
 			return nil, err
 		}
+		// And how far each endpoint reaches, which says the same thing to the filter and more
+		// besides (novox/hq ADR 0138). Folded in here rather than beside: the filter has one
+		// question — from where — and a reach answers it, so giving it two inputs would let them
+		// disagree. Reaches refuses a port that both name, so this cannot silently prefer one.
+		reaches, err := Reaches(m, with.Settings[m.Module])
+		if err != nil {
+			return nil, err
+		}
+		// **Only for an endpoint the proxy does not serve.** A routed endpoint's port is how the
+		// proxy reaches it and nothing else (ADR 0045), so `public` there asks for a public name and
+		// says nothing about the port — opening it to the world as well would undo the arrangement
+		// the proxy exists for, and would silently reopen a port an operator had narrowed.
+		//
+		// Found by trying to express a real module: one whose routed name must be public and whose
+		// machine-side port must not be. Under one value for both, there was no way to say it.
+		routed := RoutedPorts(m)
+		for port, reach := range reaches {
+			if routed[port] {
+				continue
+			}
+			source, ok := FilterSource(reach)
+			if !ok {
+				return nil, fmt.Errorf("%s: %q is not a reach the filter can read", m.Module, reach)
+			}
+			if e == nil {
+				e = map[int]string{}
+			}
+			e[port] = source
+		}
 		if e != nil {
 			exposure[m.Module] = e
 		}
@@ -1065,7 +1094,11 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
 			if err != nil {
 				return nil, fmt.Errorf("%s contributing to %s: %w", m.Module, to, err)
 			}
-			composeName(values, r.PublicDomain, r.At)
+			reaches, err := Reaches(m, settings[m.Module])
+			if err != nil {
+				return nil, fmt.Errorf("%s contributing to %s: %w", m.Module, to, err)
+			}
+			composeName(values, r.PublicDomain, r.At, reaches)
 			out[to] = append(out[to], Contribution{From: m.Module, Values: values})
 		}
 		// Several contributions to one requirement (ADR 0094's sibling for `contributes`): an
@@ -1079,7 +1112,11 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
 				if err != nil {
 					return nil, fmt.Errorf("%s contributing %s to %s: %w", m.Module, local, to, err)
 				}
-				composeName(values, r.PublicDomain, r.At)
+				reaches, err := Reaches(m, settings[m.Module])
+				if err != nil {
+					return nil, fmt.Errorf("%s contributing %s to %s: %w", m.Module, local, to, err)
+				}
+				composeName(values, r.PublicDomain, r.At, reaches)
 				out[to] = append(out[to], Contribution{From: m.Module, Values: values})
 			}
 		}
@@ -1110,10 +1147,34 @@ func (r Resolution) contributions(settings SettingsBy, grants []Grant,
 // the running mesh keeps serving the full names it has. And a labelled contribution on a node with
 // no public domain composes nothing — there is nothing to join it to — which reads downstream as a
 // route that named no host, the same as it would have before this existed.
-func composeName(values map[string]any, publicDomain, internalDomain string) {
+func composeName(values map[string]any, publicDomain, internalDomain string, reaches map[int]string) {
 	if values == nil {
 		return
 	}
+	// **How far the endpoint this route serves reaches decides which names exist** (novox/hq ADR
+	// 0138). Both were composed whenever the node had both domains, so every routed module got a
+	// public name and an internal one whether anybody wanted them or not — and a certificate for
+	// each, because the proxy certifies the names it is given.
+	//
+	// Joined by the port: a route entry names the port it serves and the module declares a listen on
+	// it. An entry with no port is not an endpoint's route but a rule about a name — a path-level
+	// refusal shadowing another route — and it inherits whatever that route's names turned out to
+	// be, which is why it is left alone here.
+	//
+	// Nothing said is both names, as before. That is what keeps every mesh already running identical
+	// until an assignment speaks.
+	wantPublic, wantInternal := true, true
+	if port, ok := asPort(values["port"]); ok {
+		if reach, said := reaches[port]; said {
+			wantPublic, wantInternal = WantsPublicName(reach), WantsInternalName(reach)
+		}
+	}
+	if !wantPublic {
+		publicDomain = ""
+	}
+	if !wantInternal {
+		internalDomain = ""
+	}
 	if _, already := values["name"]; already {
 		// A full name was given rather than a label. Left as-is: this is the legacy shape, and the
 		// point of the label is to not have to write the full name — a contribution that wrote both

internal/catalogue/filtering.go

@@ -701,3 +701,154 @@ func sortedPorts(of map[int]int) []int {
 	sort.Ints(out)
 	return out
 }
+
+// ReachSetting is the settings key that says how far one of a module's endpoints reaches, per node
+// (novox/hq ADR 0138):
+//
+//	{"reach": {"3000": "internal"}}
+//
+// **One value, three readers.** Reachability used to be settled three times over: the filter read a
+// listen's source, which `expose` could override; the proxy composed a public name and an internal
+// name for every route it was given, because it could; and the certificate authority followed from
+// which names existed. Each was defensible and the combination was unstated, so "this endpoint must
+// not be public" could not be written and was therefore enforced by nothing — while a public
+// certificate for that very name was obtained anyway.
+//
+// It keys on the port the module declares, the same key `ports` and `expose` use. A route names that
+// port too, which is what lets one statement reach the names as well as the filter: of the 36 route
+// entries in the catalogue, 35 name a port that the same module declares a listen on, and the one
+// that does not is a path-level refusal — a rule about a name rather than an endpoint.
+const ReachSetting = "reach"
+
+// How far an endpoint reaches. Four values, because they have to cover everything `expose` could say
+// as well as the two names.
+const (
+	// ReachMachine is this machine only: not the private network, not the world, and no name.
+	ReachMachine = "machine"
+	// ReachInternal is the private network, under the internal name and not the public one.
+	ReachInternal = "internal"
+	// ReachPublic is the world, under the public name and not the internal one.
+	ReachPublic = "public"
+	// ReachBoth is the world, under both names — each certified by its own authority.
+	//
+	// The filter cannot distinguish this from ReachPublic, and should not try: the mesh's addresses
+	// 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"
+)
+
+// reaches is every value, in the order a refusal lists them.
+var reaches = []string{ReachMachine, ReachInternal, ReachPublic, ReachBoth}
+
+// RoutedPorts are the ports a module serves through a proxy, taken from its route contributions.
+//
+// **A routed endpoint's port is how the proxy reaches it, and nothing else.** That is ADR 0045's
+// decision and it is older than reach: a public service listens `from: mesh`, only the proxy reaches
+// it, and it is exposed by name. So `public` on a routed endpoint asks for a public *name*; opening
+// that port to the world as well would undo the arrangement the proxy exists for.
+//
+// Measured before this was written, not reasoned: a module's routed name answered from the internet
+// over TLS while its machine-side port was refused from the same place. The port is not the path.
+func RoutedPorts(m Manifest) map[int]bool {
+	out := map[int]bool{}
+	note := func(values map[string]any) {
+		if port, ok := asPort(values["port"]); ok {
+			out[port] = true
+		}
+	}
+	if values, ok := m.Contributes["route"]; ok {
+		note(values)
+	}
+	for _, values := range m.ContributesMany["route"] {
+		note(values)
+	}
+	return out
+}
+
+// FilterSource is the source a reach means to the packet filter.
+//
+// `public` and `both` are the same here. A reach that opened a port to the mesh and not to the world
+// would be `internal`; there is no reach that opens it to the world and *not* to the mesh, because a
+// filter cannot express "everyone except these" and nobody has asked for it.
+func FilterSource(reach string) (string, bool) {
+	switch reach {
+	case ReachMachine:
+		return FromMachine, true
+	case ReachInternal:
+		return FromMesh, true
+	case ReachPublic, ReachBoth:
+		return FromEverywhere, true
+	default:
+		return "", false
+	}
+}
+
+// WantsPublicName is whether a reach asks for the route's public name to be composed.
+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 }
+
+// Reaches reads a module's per-node reach settings: declared port → how far it reaches.
+//
+// It refuses a reach for a port the module does not listen on, or a value that is not one of the
+// four — the "reads as a restriction and is none" fault this whole mechanism exists to prevent
+// (novox/hq ADR 0043/0045). It also refuses a port that `expose` names as well: the two say the same
+// thing in different words, and a module whose reach and exposure disagree would have the filter
+// following one and the names following the other, which is the very confusion ADR 0138 removes.
+//
+// A module with no `reach` setting yields nothing, and everything behaves exactly as before: the
+// filter follows the manifest's `from`, and both names are composed. That is what keeps every machine
+// already running unchanged until an assignment says otherwise.
+func Reaches(m Manifest, layers []Layer) (map[int]string, error) {
+	listened := make(map[int]bool, len(m.Listens))
+	for _, l := range m.Listens {
+		listened[l.Port] = true
+	}
+
+	exposed, err := Exposure(m, layers)
+	if err != nil {
+		return nil, err
+	}
+
+	out := map[int]string{}
+	for _, layer := range layers {
+		raw, ok := layer.Values[ReachSetting]
+		if !ok {
+			continue
+		}
+		entries, ok := raw.(map[string]any)
+		if !ok {
+			return nil, fmt.Errorf("%s: %s is a { port: reach } map, and %q set it to something else",
+				m.Module, ReachSetting, layer.From)
+		}
+		for portText, value := range entries {
+			port, err := strconv.Atoi(portText)
+			if err != nil {
+				return nil, fmt.Errorf("%s says how far %q reaches, which is not a port", m.Module, portText)
+			}
+			if !listened[port] {
+				return nil, fmt.Errorf(
+					"%s says how far port %d reaches, which it does not listen on — the setting "+
+						"reaches nothing", m.Module, port)
+			}
+			reach, ok := value.(string)
+			if !ok || !slices.Contains(reaches, reach) {
+				return nil, fmt.Errorf("%s says port %d reaches %v; a reach is %s",
+					m.Module, port, value, strings.Join(reaches, ", "))
+			}
+			if _, both := exposed[port]; both {
+				return nil, fmt.Errorf(
+					"%s sets both %s and %s for port %d. They say the same thing in different "+
+						"words, and the filter would follow one while its names followed the other "+
+						"— which is what %s exists to stop. Keep %s",
+					m.Module, ReachSetting, ExposeSetting, port, ReachSetting, ReachSetting)
+			}
+			out[port] = reach
+		}
+	}
+	if len(out) == 0 {
+		return nil, nil
+	}
+	return out, nil
+}

internal/catalogue/manifest.go

@@ -571,6 +571,21 @@ type Artifact struct {
 	// image built from this same module's own repository, the same as every other artifact.
 	Context *ArtifactContext `json:"context,omitempty"`
 
+	// System is the operating system this artifact is compiled for, for a bundle whose output is a
+	// binary rather than portable code (novox/hq ADR 0142).
+	//
+	// **Named by the artifact, not by the recipe.** A toolchain deliberately accepts nothing from
+	// the module — anything a module could override there it would be writing a Dockerfile to
+	// override — and yet a compiled binary is per operating system, pinned at link time so a host
+	// refuses to touch a machine it was not built for (novox/hq ADR 0005). The way out is that the
+	// target is a property of the artifact: one artifact declared per system, one build each, and
+	// the recipe stays the mesh's.
+	//
+	// Empty for a bundle whose output runs anywhere, which is every interpreted language, and for
+	// every other kind. A bundle in a language that compiles to a binary must say one, because
+	// "compiled for whatever the build machine happened to be" is the fault this exists to prevent.
+	System string `json:"system,omitempty"`
+
 	// Language is what this module's code is written in, for a bundle.
 	//
 	// **Declared, never guessed.** Inferring it from what files happen to be present makes a

internal/catalogue/reach_test.go

@@ -0,0 +1,206 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// a web module with one routed endpoint, the shape almost every routed module in the catalogue has.
+func aRoutedWeb() Manifest {
+	return Manifest{
+		Module:  "web",
+		Listens: []Listening{{Port: 3000, From: FromMesh}},
+		Contributes: map[string]map[string]any{
+			"route": {"label": "app", "port": 3000},
+		},
+	}
+}
+
+func reachSet(reach string) SettingsBy {
+	return SettingsBy{"web": {{From: "node anchor",
+		Values: map[string]any{ReachSetting: map[string]any{"3000": reach}}}}}
+}
+
+// namesFor renders the contribution a routed module makes and returns the two names it carries.
+func namesFor(t *testing.T, m Manifest, settings SettingsBy) (public, internal string) {
+	t.Helper()
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	given, err := r.contributions(settings, nil, nil)
+	if err != nil {
+		t.Fatalf("contributions: %v", err)
+	}
+	for _, c := range given["route"] {
+		p, _ := c.Values["name"].(string)
+		i, _ := c.Values["internal-name"].(string)
+		return p, i
+	}
+	t.Fatal("the module contributed no route")
+	return "", ""
+}
+
+// **Nothing said composes both names, exactly as before.** This is the assertion that keeps every
+// mesh already running identical until an assignment speaks, and it is the one that would break first
+// if reach were read where it should not be.
+func TestAnEndpointWithNoReachKeepsBothNames(t *testing.T) {
+	public, internal := namesFor(t, aRoutedWeb(), nil)
+	if public != "app.example.test" || internal != "app.anchor.internal" {
+		t.Fatalf("names are %q and %q, want both composed as before", public, internal)
+	}
+}
+
+// An internal endpoint has an internal name and no public one — so the proxy serves it inside, and
+// the public authority is never asked for a name nobody wanted. This is what "must not be public"
+// could not say before.
+func TestAnInternalEndpointHasNoPublicName(t *testing.T) {
+	public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachInternal))
+	if public != "" {
+		t.Fatalf("an internal endpoint composed the public name %q", public)
+	}
+	if internal != "app.anchor.internal" {
+		t.Fatalf("internal name is %q, want app.anchor.internal", internal)
+	}
+}
+
+// And the mirror: a public endpoint gets the public name and not the internal one, so the mesh's own
+// authority is not asked to certify a name the service is not reached by.
+func TestAPublicEndpointHasNoInternalName(t *testing.T) {
+	public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachPublic))
+	if internal != "" {
+		t.Fatalf("a public endpoint composed the internal name %q", internal)
+	}
+	if public != "app.example.test" {
+		t.Fatalf("public name is %q, want app.example.test", public)
+	}
+}
+
+func TestBothComposesBothNames(t *testing.T) {
+	public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachBoth))
+	if public == "" || internal == "" {
+		t.Fatalf("both should compose both names, got %q and %q", public, internal)
+	}
+}
+
+// **The filter reads the same value — for an endpoint the proxy does not serve.**
+//
+// A routed endpoint's port is how the proxy reaches it and nothing else (ADR 0045): a public service
+// listens from the mesh, only the proxy reaches it, and it is exposed by name. So on a routed
+// endpoint the reach asks for a name and the port keeps what the manifest said.
+func TestAnUnroutedEndpointsPortFollowsItsReach(t *testing.T) {
+	// The same module with its route taken away: now the port is the only way in, so reach governs it.
+	bare := aRoutedWeb()
+	bare.Contributes = nil
+
+	for _, c := range []struct{ reach, want string }{
+		{ReachInternal, FromMesh},
+		{ReachPublic, FromEverywhere},
+		{ReachBoth, FromEverywhere},
+		{ReachMachine, FromMachine},
+	} {
+		r := Resolution{Node: "anchor", Modules: []Manifest{bare}}
+		rules, err := r.Rules(Rendering{Settings: reachSet(c.reach)})
+		if err != nil {
+			t.Fatalf("%s: rules: %v", c.reach, err)
+		}
+		found := false
+		for _, rule := range rules {
+			if rule.Port == 3000 {
+				found = true
+				if rule.From != c.want {
+					t.Fatalf("reach %q made the filter say %q, want %q", c.reach, rule.From, c.want)
+				}
+			}
+		}
+		if !found {
+			t.Fatalf("reach %q produced no rule for the port", c.reach)
+		}
+	}
+}
+
+// **A public name does not open the machine's port**, which is the case that found this.
+//
+// A module whose routed name must be public and whose machine-side port must not be had no way to say
+// so while one value drove both. Under one value it could not be expressed; the port would reopen.
+func TestAPublicNameLeavesARoutedPortAsTheManifestSaid(t *testing.T) {
+	r := Resolution{Node: "anchor", Modules: []Manifest{aRoutedWeb()},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	rules, err := r.Rules(Rendering{Settings: reachSet(ReachPublic)})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, rule := range rules {
+		if rule.Port == 3000 && rule.From != FromMesh {
+			t.Fatalf("a public reach opened a routed port to %q; the proxy is how it is reached",
+				rule.From)
+		}
+	}
+	// And the name it asked for is there, so the reach was not simply ignored.
+	public, internal := namesFor(t, aRoutedWeb(), reachSet(ReachPublic))
+	if public != "app.example.test" || internal != "" {
+		t.Fatalf("names are %q and %q, want the public one only", public, internal)
+	}
+}
+
+// A reach for a port the module does not listen on reaches nothing, and is refused where it is
+// written rather than accepted and ignored.
+func TestAReachForAPortTheModuleDoesNotListenOnIsRefused(t *testing.T) {
+	_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor",
+		Values: map[string]any{ReachSetting: map[string]any{"9999": ReachInternal}}}})
+	if err == nil || !strings.Contains(err.Error(), "reaches nothing") {
+		t.Fatalf("a reach naming an undeclared port was accepted: %v", err)
+	}
+}
+
+// A value that is not a reach is refused, and the refusal names the four so a reader is one edit from
+// right. "mesh" is the tempting wrong answer, because that is the filter's word for nearly the same
+// thing.
+func TestAValueThatIsNotAReachIsRefused(t *testing.T) {
+	for _, wrong := range []string{"mesh", "anywhere", "private", "true"} {
+		_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor",
+			Values: map[string]any{ReachSetting: map[string]any{"3000": wrong}}}})
+		if err == nil || !strings.Contains(err.Error(), "a reach is") {
+			t.Fatalf("%q was accepted as a reach: %v", wrong, err)
+		}
+	}
+}
+
+// **A port that says both reach and expose is refused.** They say the same thing in different words,
+// and accepting both would have the filter follow one while the names followed the other — the
+// disagreement ADR 0138 exists to remove, reintroduced by the migration away from the older word.
+func TestReachAndExposeForOnePortAreRefused(t *testing.T) {
+	_, err := Reaches(aRoutedWeb(), []Layer{{From: "node anchor", Values: map[string]any{
+		ReachSetting:  map[string]any{"3000": ReachInternal},
+		ExposeSetting: map[string]any{"3000": FromEverywhere},
+	}}})
+	if err == nil || !strings.Contains(err.Error(), "same thing in different") {
+		t.Fatalf("a port set both ways was accepted: %v", err)
+	}
+}
+
+// A path-level refusal carries no port: it is a rule about a name, not an endpoint, and it inherits
+// whatever that name turned out to be. Narrowing the endpoint must not silently drop it.
+func TestARuleWithNoPortIsLeftAlone(t *testing.T) {
+	m := aRoutedWeb()
+	m.ContributesMany = map[string]map[string]map[string]any{
+		"route": {"refused": {"label": "app", "path": "/internal", "deny": true}},
+	}
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	given, err := r.contributions(reachSet(ReachInternal), nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var sawDeny bool
+	for _, c := range given["route"] {
+		if deny, _ := c.Values["deny"].(bool); deny {
+			sawDeny = true
+			// It keeps both, because it named no endpoint to be narrowed by.
+			if c.Values["name"] == nil || c.Values["internal-name"] == nil {
+				t.Fatalf("the path rule lost a name it shadows: %v", c.Values)
+			}
+		}
+	}
+	if !sawDeny {
+		t.Fatal("the path rule was dropped")
+	}
+}

internal/catalogue/settings.go

@@ -186,6 +186,12 @@ func UnusedSettings(m Manifest, layers []Layer) []string {
 			if key == PortsSetting {
 				continue
 			}
+			// `reach` says how far one of this module's endpoints reaches (novox/hq ADR 0138) — the
+			// filter's source, which names are composed, and therefore which authority certifies
+			// them. Validated in Reaches, so not stray.
+			if key == ReachSetting && len(m.Listens) > 0 {
+				continue
+			}
 			unused = append(unused, fmt.Sprintf(
 				"%s sets %q, and %s has no file or contribution to merge it into",
 				layer.From, key, m.Module))