A module names its endpoints, and a route names the one it serves

novox/hq ADR 0138's remaining half, and the words ship one release before any
manifest uses them.

A port number is not a name. Three facts have to be said about an endpoint when a
module is assigned — which machine port it lands on, the subdomain a proxy serves
it under, and how far it reaches — and they were said in three places keyed by the
port. A module with two endpoints of different shapes cannot be configured that way
without a reader joining numbers by hand: a web surface behind the proxy, whose
port only the proxy need reach, and a protocol port clients dial directly because
the client expects that number.

So a listen carries a name, lowercase and unique within the module, and a route
names the endpoint it serves instead of repeating its port. Two endpoints with one
name are refused, because an assignment configuring one would silently configure
whichever the mesh read last. A route naming an endpoint the module does not declare
is refused where it is written rather than resolving to no port and serving nothing.

An unnamed endpoint stays valid and a route repeating a port still resolves, which
is every module in the catalogue today.

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, endpointPorts(m))
 			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, endpointPorts(m))
 				out[to] = append(out[to], Contribution{From: m.Module, Values: values})
 			}
 		}
@@ -1110,10 +1147,35 @@ 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,
+	ports map[string]int) {
 	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 := endpointPortOf(values, ports); 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
@@ -1733,3 +1795,28 @@ func prepared(from map[string]any) map[string]any {
 	delete(step, "reload-on")
 	return step
 }
+
+// endpointPortOf is the port the endpoint a route serves listens on: looked up by the name the route
+// gives, or read from the port it repeats (novox/hq ADR 0138).
+//
+// `ports` maps this module's endpoint names to their ports, computed once per module rather than
+// re-scanned per contribution.
+func endpointPortOf(values map[string]any, ports map[string]int) (int, bool) {
+	if name, ok := values[RouteEndpoint].(string); ok {
+		if port, found := ports[strings.TrimSpace(name)]; found {
+			return port, true
+		}
+	}
+	return asPort(values["port"])
+}
+
+// endpointPorts is a module's endpoint names against the ports they listen on.
+func endpointPorts(m Manifest) map[string]int {
+	out := map[string]int{}
+	for _, l := range m.Listens {
+		if name := strings.TrimSpace(l.Name); name != "" {
+			out[name] = l.Port
+		}
+	}
+	return out
+}

internal/catalogue/endpoint_test.go

@@ -0,0 +1,141 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// aMediaServer is the shape one port number per key cannot express: two endpoints of different kinds.
+// A web surface a proxy serves under a subdomain, and a protocol port clients dial directly because
+// the client expects that number.
+func aMediaServer() Manifest {
+	return Manifest{
+		Module: "media",
+		Listens: []Listening{
+			{Name: "web", Port: 80, From: FromMesh, Why: "the app, behind the proxy"},
+			{Name: "stream", Port: 32400, From: FromEverywhere, Fixed: true,
+				Why: "the client dials this number; the protocol chose it"},
+		},
+		Contributes: map[string]map[string]any{
+			"route": {"label": "media", RouteEndpoint: "web"},
+		},
+	}
+}
+
+// **A route names the endpoint it serves.** A route and a listen both carried a port and nothing said
+// they were the same thing; now one of them says so.
+func TestARouteNamesTheEndpointItServes(t *testing.T) {
+	m := aMediaServer()
+	if port, ok := EndpointPort(m, "web"); !ok || port != 80 {
+		t.Fatalf("the web endpoint resolves to %d (%v), want 80", port, ok)
+	}
+	if port, ok := EndpointPort(m, "stream"); !ok || port != 32400 {
+		t.Fatalf("the stream endpoint resolves to %d (%v), want 32400", port, ok)
+	}
+	if _, ok := EndpointPort(m, "absent"); ok {
+		t.Fatal("an endpoint the module does not declare resolved to a port")
+	}
+}
+
+// And the routed set is read through the name, so the endpoint the proxy serves is known without a
+// reader joining two numbers.
+func TestTheRoutedEndpointIsFoundByName(t *testing.T) {
+	routed := RoutedPorts(aMediaServer())
+	if !routed[80] {
+		t.Fatalf("the routed endpoint was not found by name: %v", routed)
+	}
+	// And the directly-dialled one is not routed, which is what lets its reach govern its port.
+	if routed[32400] {
+		t.Fatalf("the endpoint clients dial directly reads as routed: %v", routed)
+	}
+}
+
+// **Two endpoints of different shapes, configured as themselves.** The web endpoint's reach asks for
+// names and leaves its port to the proxy; the stream endpoint's reach governs its port, because
+// clients dial it and there is no name.
+func TestTwoEndpointsOfDifferentShapesAreConfiguredSeparately(t *testing.T) {
+	m := aMediaServer()
+	settings := SettingsBy{"media": {{From: "node anchor", Values: map[string]any{
+		ReachSetting: map[string]any{"80": ReachBoth, "32400": ReachPublic},
+	}}}}
+
+	r := Resolution{Node: "anchor", Modules: []Manifest{m},
+		PublicDomain: "example.test", At: "anchor.internal"}
+	rules, err := r.Rules(Rendering{Settings: settings})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, rule := range rules {
+		switch rule.Port {
+		case 80:
+			if rule.From != FromMesh {
+				t.Fatalf("the routed endpoint's port opened to %q; the proxy is how it is reached",
+					rule.From)
+			}
+		case 32400:
+			if rule.From != FromEverywhere {
+				t.Fatalf("the directly-dialled endpoint's port is %q, want anywhere", rule.From)
+			}
+		}
+	}
+
+	// And the routed one carries both names, asked for by the same statement.
+	given, err := r.contributions(settings, nil, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var public, internal string
+	for _, c := range given["route"] {
+		public, _ = c.Values["name"].(string)
+		internal, _ = c.Values["internal-name"].(string)
+	}
+	if public != "media.example.test" || internal != "media.anchor.internal" {
+		t.Fatalf("names are %q and %q, want both", public, internal)
+	}
+}
+
+// A route naming an endpoint the module does not declare reaches nothing, and is refused where it is
+// written rather than resolving to no port and serving nothing.
+func TestARouteNamingAnEndpointTheModuleLacksIsRefused(t *testing.T) {
+	m := aMediaServer()
+	m.Contributes["route"][RouteEndpoint] = "absent"
+	got := strings.Join(RouteProblems(m), "\n")
+	if !strings.Contains(got, "does not declare") {
+		t.Fatalf("a route naming an absent endpoint was accepted:\n%s", got)
+	}
+}
+
+// **Two endpoints called the same would make an assignment configure whichever was read last.** The
+// point of a name is that it identifies one thing.
+func TestTwoEndpointsWithOneNameAreRefused(t *testing.T) {
+	m := Manifest{Module: "twice", Listens: []Listening{
+		{Name: "web", Port: 80, From: FromMesh},
+		{Name: "web", Port: 8080, From: FromMesh},
+	}}
+	got := strings.Join(endpointNameProblems(m), "\n")
+	if !strings.Contains(got, "could mean either") {
+		t.Fatalf("two endpoints with one name were accepted:\n%s", got)
+	}
+}
+
+// A name that is not a name is refused where it is written: it ends up in something a person types.
+func TestAnEndpointNameIsHeldToItsShape(t *testing.T) {
+	for _, wrong := range []string{"Web", "web port", "3000", "-web", "web_surface"} {
+		m := Manifest{Module: "odd", Listens: []Listening{{Name: wrong, Port: 80, From: FromMesh}}}
+		if got := strings.Join(endpointNameProblems(m), "\n"); !strings.Contains(got, "a name is lowercase") {
+			t.Fatalf("%q was accepted as an endpoint name:\n%s", wrong, got)
+		}
+	}
+}
+
+// **Every endpoint in the catalogue is unnamed today, and must stay valid.** The word ships one
+// release before anything uses it.
+func TestAnUnnamedEndpointIsStillValid(t *testing.T) {
+	m := Manifest{Module: "ordinary", Listens: []Listening{{Port: 443, From: FromEverywhere}}}
+	if got := endpointNameProblems(m); len(got) != 0 {
+		t.Fatalf("an unnamed endpoint was refused: %v", got)
+	}
+	if got := RouteProblems(m); len(got) != 0 {
+		t.Fatalf("a module with no route was refused: %v", got)
+	}
+}

internal/catalogue/filtering.go

@@ -701,3 +701,198 @@ 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) {
+		// **The endpoint it serves, by name where it says one.** A route repeating a port number is
+		// the older shape and still read: 35 of the catalogue's 36 route entries name a port their
+		// module declares a listen on (novox/hq ADR 0138).
+		if name, ok := values[RouteEndpoint].(string); ok {
+			if port, found := EndpointPort(m, name); found {
+				out[port] = true
+				return
+			}
+		}
+		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
+}
+
+// RouteEndpoint is the key a route contribution names the endpoint it serves with, instead of
+// repeating that endpoint's port (novox/hq ADR 0138).
+//
+// **A route and a listen both carried a port, and nothing said they were the same thing.** They
+// always were — a route serves one of the module's own endpoints — but a reader had to join two
+// numbers, and an assignment configuring "the web endpoint" had to know which number that was. A
+// route that names the endpoint says what it means, and the mesh looks the port up.
+const RouteEndpoint = "endpoint"
+
+// RouteProblems holds a module's route contributions to naming an endpoint it actually has.
+//
+// A route naming an endpoint the module does not declare reaches nothing, and is refused where it is
+// written rather than resolving to no port and serving nothing — the fault this repository names most
+// often, a declaration that reads as though it did something.
+func RouteProblems(m Manifest) []string {
+	var problems []string
+	check := func(where string, values map[string]any) {
+		name, ok := values[RouteEndpoint].(string)
+		if !ok || strings.TrimSpace(name) == "" {
+			return
+		}
+		if _, found := EndpointPort(m, name); !found {
+			problems = append(problems, fmt.Sprintf(
+				"%s routes %s to the endpoint %q, which it does not declare", m.Module, where, name))
+		}
+	}
+	if values, ok := m.Contributes["route"]; ok {
+		check("a name", values)
+	}
+	for local, values := range m.ContributesMany["route"] {
+		check(local, values)
+	}
+	return problems
+}

internal/catalogue/manifest.go

@@ -657,8 +657,23 @@ const (
 // on is a fact, and it should be written once.
 const ArtifactStoreProvision = "artifact-store"
 
-// Listening is one port a module accepts connections on.
+// Listening is one endpoint a module serves: a port it accepts connections on, and what may be said
+// about that port from outside the module.
 type Listening struct {
+	// Name is what this endpoint is called, so an assignment and a route can refer to it as one thing
+	// (novox/hq ADR 0138).
+	//
+	// **Because a port number is not a name.** Three facts have to be said about an endpoint when a
+	// module is assigned — which machine port it lands on, the subdomain a proxy serves it under, and
+	// how far it reaches — and they were said in three places keyed by the port. A module with two
+	// endpoints of different shapes, a web surface behind a proxy and a protocol port clients dial
+	// directly, cannot be configured that way without a reader joining numbers by hand.
+	//
+	// The module's to choose, like the route's label: it names its own parts. Lowercase, and unique
+	// within the module, so a reference to it is unambiguous. Empty is allowed and means an endpoint
+	// nothing refers to by name, which is every endpoint in the catalogue until they are named.
+	Name string `json:"name,omitempty"`
+
 	Port int `json:"port"`
 	// Protocol is "tcp" or "udp". Absent means tcp, which is what almost everything is — and a
 	// field that had to be written every time would be written wrongly some of the time.
@@ -1265,6 +1280,8 @@ func ParseManifest(raw []byte) (Manifest, error) {
 				"%s listens on %d over %q, which is tcp or udp", m.Module, l.Port, p))
 		}
 	}
+	problems = append(problems, endpointNameProblems(m)...)
+	problems = append(problems, RouteProblems(m)...)
 	for _, port := range m.Guards {
 		if port < 1 || port > 65535 {
 			problems = append(problems, fmt.Sprintf(
@@ -1689,3 +1706,53 @@ func (m Manifest) undeclaredMounts() []string {
 	}
 	return problems
 }
+
+// endpointName is what an endpoint may be called: lowercase letters, digits and dashes, starting
+// with a letter. The same shape a label has, because both end up in something a person types.
+var endpointName = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
+
+// endpointNameProblems holds a module's endpoint names to being usable as references (novox/hq ADR
+// 0138).
+//
+// **Unique, because the point of a name is that it identifies one thing.** Two endpoints called the
+// same would make an assignment that configures one silently configure whichever the mesh read last
+// — the shape of fault this repository keeps finding, where a declaration appears to say something
+// and says something else.
+func endpointNameProblems(m Manifest) []string {
+	var problems []string
+	seen := map[string]int{}
+	for _, l := range m.Listens {
+		name := strings.TrimSpace(l.Name)
+		if name == "" {
+			continue
+		}
+		if !endpointName.MatchString(name) {
+			problems = append(problems, fmt.Sprintf(
+				"%s calls the endpoint on port %d %q; a name is lowercase letters, digits and "+
+					"dashes, starting with a letter", m.Module, l.Port, l.Name))
+			continue
+		}
+		if before, already := seen[name]; already {
+			problems = append(problems, fmt.Sprintf(
+				"%s calls both port %d and port %d %q, so anything naming that endpoint could mean "+
+					"either", m.Module, before, l.Port, name))
+			continue
+		}
+		seen[name] = l.Port
+	}
+	return problems
+}
+
+// EndpointPort is the port of the endpoint a module calls this, and whether it has one.
+func EndpointPort(m Manifest, name string) (int, bool) {
+	want := strings.TrimSpace(name)
+	if want == "" {
+		return 0, false
+	}
+	for _, l := range m.Listens {
+		if strings.TrimSpace(l.Name) == want {
+			return l.Port, true
+		}
+	}
+	return 0, false
+}

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))