The mesh assigns the port, and a module says it once

novox/hq ADR 0038. A module cannot choose a port: it is written once and
assigned anywhere, so any number it picks is a guess about a machine it
has never seen. A database module met the mesh's own store on 5432 and
was told, by a container runtime three layers down, that the port was
already allocated.

The number used to appear three times in every module — the rule set,
what a consumer is told, and what the runtime publishes — agreeing only
because one person wrote all three. Now it appears once, in `listens`,
and the other two are derived: the container publishes `20000:5432`, the
consumer is told 20000, and the rule set opens 20000.

An assignment is made once and kept, as a credential is. A port that
moved on every declaration would restart both ends each time and hand a
consumer a number that was true when it was read.

Ports the protocol fixes — mail on 25, submission on 587, DNS on 53 —
say so, and are then claims: one holder per machine, and the second is
refused by name at assignment. That is the mechanism the mesh already
has for what is singular on a machine, pointed at ports.

A mapping written the long way is left exactly as it is. Some things
must be pinned by hand, and quietly overruling somebody who wrote both
halves would be worse than not offering the short form.

Still open, and known: the substrate is not a module, so the mesh has
never heard of its own store and cannot yet assign around it. That is
what 028 will still be about after this.

internal/catalogue/declaration.go

@@ -12,6 +12,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"sort"
+	"strconv"
 	"strings"
 )
 
@@ -97,6 +98,24 @@ type Rendering struct {
 	// rather than resolved, because who consumes a node is a fact about the rest of the mesh and
 	// resolution answers questions about one machine.
 	Grants []Grant
+
+	// Ports is where this machine puts what each module needs reachable, by module and by the
+	// port the software itself uses (novox/hq ADR 0038).
+	//
+	// **The one place the number now lives.** A module used to write it three times — for the rule
+	// set, for what a consumer is told, and for what the runtime publishes — and nothing checked
+	// that the three agreed. They are all derived from this.
+	Ports map[string]map[int]int
+}
+
+// machinePort is where a module's port lives on this machine, or the port itself when the mesh has
+// not been asked. Unassigned is not an error here: a module with no `listens` never needed one,
+// and a caller composing a declaration without a store still gets something coherent.
+func (r Rendering) machinePort(module string, wanted int) int {
+	if at, known := r.Ports[module][wanted]; known {
+		return at
+	}
+	return wanted
 }
 
 // Declaration is everything the resolved modules put on the node, with settings applied.
@@ -120,7 +139,7 @@ func (r Resolution) Declaration(with Rendering) ([]map[string]any, error) {
 
 	// Once, from every module's listens -- not per module. A module receiving only its own ports
 	// would write a rule set that closed every other module on the machine.
-	rules, err := r.Filtering(with.Generators)
+	rules, err := r.Filtering(with.Generators, with.Ports)
 	if err != nil {
 		return nil, err
 	}
@@ -345,6 +364,7 @@ func (r Resolution) Declaration(with Rendering) ([]map[string]any, error) {
 			if err := pinned(copied, m.Module); err != nil {
 				return nil, err
 			}
+			publishedOn(copied, m.Module, with)
 			copied["id"] = m.Module + "." + fmt.Sprint(resource["id"])
 			// A service saying what it reflects names resources within its own module, so those
 			// are prefixed too or they would point at nothing.
@@ -593,7 +613,8 @@ func (r Resolution) ContributionsFrom(requirement, module string, settings Setti
 // nothing resolves would be worse than naming it by an address that always works.
 func here(r Resolution, requirement string) *Needed {
 	for _, m := range r.Modules {
-		serves, said := m.Serves[requirement]
+		_, said := m.Serves[requirement]
+		serves := ServedOn(m, requirement, nil)
 		if !said || len(serves) == 0 {
 			continue
 		}
@@ -667,3 +688,90 @@ func pinned(resource map[string]any, module string) error {
 			"image — it would be fetched and fail there. Resolve the tag to a digest first",
 		module, resource["id"])
 }
+
+// publishedOn puts the machine's own port on the outside of a container's mapping.
+//
+// **A module writes the port the software uses; the mesh says where the machine puts it**
+// (novox/hq ADR 0038). So `"5432"` means *publish what the software calls 5432*, and this fills in
+// the half only the mesh can know.
+//
+// A mapping written the long way — `"5433:5432"` — is left exactly as it is. Some things genuinely
+// must be pinned down by hand, and quietly overruling somebody who wrote both halves would be
+// worse than not offering the short form at all.
+func publishedOn(resource map[string]any, module string, with Rendering) {
+	if fmt.Sprint(resource["type"]) != "container" {
+		return
+	}
+	listed, ok := resource["ports"].([]any)
+	if !ok {
+		return
+	}
+	out := make([]any, 0, len(listed))
+	for _, entry := range listed {
+		written := fmt.Sprint(entry)
+		if strings.Contains(written, ":") {
+			out = append(out, written)
+			continue
+		}
+		wanted, err := strconv.Atoi(strings.TrimSpace(written))
+		if err != nil {
+			// Not a port at all. Passed through, so the host refuses it with its own words rather
+			// than this quietly dropping something somebody meant.
+			out = append(out, written)
+			continue
+		}
+		out = append(out, fmt.Sprintf("%d:%d", with.machinePort(module, wanted), wanted))
+	}
+	resource["ports"] = out
+}
+
+// ServedOn is what a provider tells a consumer, with the port that machine actually uses.
+//
+// **The module writes the port once, in `listens`** (novox/hq ADR 0038). It used to write it three
+// times — for the rule set, for what a consumer is told, and for what the runtime publishes — and
+// nothing checked that the three agreed. This is what fills the second in.
+//
+// The assignment wins when there is one, and the declared port stands in when there is not: a
+// caller composing without a store still gets something coherent, and a mesh that has assigned one
+// tells the truth about where it put it.
+//
+// Only when the module offers exactly one port. A module offering several has not said which
+// belongs to which provision, and guessing would give a consumer a port that answers something
+// else — so it keeps whatever the manifest said, which may be nothing.
+func ServedOn(m Manifest, provision string, ports map[int]int) map[string]any {
+	serves := m.Serves[provision]
+
+	out := make(map[string]any, len(serves)+1)
+	for k, v := range serves {
+		out[k] = v
+	}
+	if _, said := out["port"]; said {
+		// Written by hand. Redirected to wherever the machine put it, and otherwise left alone.
+		if number, ok := asPort(out["port"]); ok {
+			if at, known := ports[number]; known {
+				out["port"] = at
+			}
+		}
+		return out
+	}
+	if len(m.Listens) != 1 {
+		return out
+	}
+	wanted := m.Listens[0].Port
+	if at, known := ports[wanted]; known {
+		out["port"] = at
+	} else {
+		out["port"] = wanted
+	}
+	return out
+}
+
+func asPort(v any) (int, bool) {
+	switch n := v.(type) {
+	case int:
+		return n, true
+	case float64:
+		return int(n), true
+	}
+	return 0, false
+}