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/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
+}