catalogue: compose a route's name from a label and its node's domain, and resolve it in-mesh

A public route used to carry its whole hostname as a literal in the module
manifest, so running the same catalogue against a different domain meant
overriding that literal on every routed module, per node. The mesh was, in
effect, holding a map of names to services: the one thing it should never hold,
because the subdomain is the operator's choice and the domain is the node's.

Compose instead. A route contribution carries a `label` (the subdomain); a node
carries its `public_domain` as node-level configuration; the mesh joins
`<label>.<public-domain>` and grants exactly that, interpreting neither half.
Held as a node property beside the node's other node-level facts (endpoint,
site, overlay address), not in a module's settings — the ADR calls it
node-level, and the settings table is keyed per module.

Additive, so an unmigrated catalogue keeps working: a contribution that still
carries a full `name` and no `label` passes through unchanged, and the catalogue
can migrate module by module. A labelled contribution on a node with no public
domain composes nothing, reading downstream as a route that named no host.

And propagate: each granted route name is published into internal resolution
mesh-wide, mapped to the node that serves it, alongside the `<node>.internal`
names every container already gets. So a container — and an internal ACME
validator, which cannot complete a challenge for a name it cannot reach —
resolves a routed name to the proxy that serves it. Name-agnostic throughout:
the mesh propagates whatever names it was told to serve and knows nothing about
what they mean.

novox/hq 02-DECISIONS/0056

Claude-Session: https://claude.ai/code/session_01LrgweAeERJYBg88c5cKDzF

internal/catalogue/declaration.go

@@ -560,12 +560,45 @@ 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)
 			out[to] = append(out[to], Contribution{From: m.Module, Values: values})
 		}
 	}
 	return out, nil
 }
 
+// composeName joins a contribution's label with a node's public domain, in place (novox/hq ADR
+// 0056).
+//
+// **The whole of what the mesh does with a route's name: join two given strings.** A contribution
+// carries a `label` — the subdomain its operator chose — and the node carries its public domain;
+// the granted name is `<label>.<public-domain>` and the mesh interprets neither half. It runs on
+// any contribution carrying a label, not only a route's, because the mesh does not know what a
+// provision means — a name it can compose from parts it was given is the point, whatever the
+// provision is called.
+//
+// **Additive, so an unmigrated catalogue still works.** A contribution that already carries a full
+// `name` and no `label` is left exactly as it is: the catalogue can migrate module by module while
+// 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 string) {
+	if values == nil || publicDomain == "" {
+		return
+	}
+	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
+		// has said what it wants and the mesh does not second-guess it.
+		return
+	}
+	label, ok := values["label"].(string)
+	if !ok || strings.TrimSpace(label) == "" {
+		return
+	}
+	values["name"] = strings.TrimSpace(label) + "." + publicDomain
+}
+
 // receivedFile is the file a provider is given its consumers' contributions in.
 func receivedFile(requirement, path string, given []Contribution) (map[string]any, error) {
 	if given == nil {

internal/catalogue/resolve.go

@@ -24,6 +24,10 @@ type Node struct {
 	// At is this machine's own name on the private network, empty if it is not on one. Needed to
 	// tell whether it can reach the node answering its requirements at all.
 	At string
+	// PublicDomain is the domain this node composes its routed names under, empty if it has none
+	// (novox/hq ADR 0056). A route contribution carries only a label — the subdomain — and the mesh
+	// joins <label>.<public-domain> to make the name it grants, interpreting neither half.
+	PublicDomain string
 }
 
 // World is what the rest of the mesh already has.
@@ -102,6 +106,10 @@ type Resolution struct {
 	// because a consumer bound to something answered on this same machine still has to be told
 	// where it is — the answer being local does not make the port guessable.
 	At string
+	// PublicDomain is the domain this node composes its routed names under, empty if it has none
+	// (novox/hq ADR 0056). Carried from the node so that composing <label>.<public-domain> for a
+	// route contribution needs no store lookup here — the join is a fact about this one machine.
+	PublicDomain string
 
 	// Modules in the order they were resolved: assigned first, then what they pulled in.
 	Modules []Manifest
@@ -504,8 +512,8 @@ func Resolve(catalogue map[string]Manifest, assigned []string, node Node, world
 		}
 	}
 
-	resolution := Resolution{Node: node.Name, At: node.At, Because: because, Needs: needs,
-		Unhostable: unhostable}
+	resolution := Resolution{Node: node.Name, At: node.At, PublicDomain: node.PublicDomain,
+		Because: because, Needs: needs, Unhostable: unhostable}
 	for _, n := range providersFirst(order, catalogue) {
 		resolution.Modules = append(resolution.Modules, catalogue[n])
 	}

internal/catalogue/routing_test.go

@@ -0,0 +1,152 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// novox/hq ADR 0056 — public routing is name-agnostic.
+//
+// A route contribution carries a label (the subdomain the operator chose); the node carries its
+// public domain; the mesh composes <label>.<public-domain> and interprets neither half. The
+// checks here are the ADR's own: the same catalogue resolves against two domains by changing one
+// node setting and nothing else, and a legacy full-name contribution passes through untouched so
+// the catalogue can migrate module by module.
+
+// labelled is a module that asks to be published under a subdomain rather than a full hostname.
+func labelled(module, label string, port int) Manifest {
+	return Manifest{Module: module, Version: "1",
+		Contributes: map[string]map[string]any{
+			"reverse-proxy": {"label": label, "port": port},
+		}}
+}
+
+// withDomain is a workstation that composes its routed names under one public domain.
+func withDomain(domain string) Node {
+	n := workstation()
+	n.PublicDomain = domain
+	return n
+}
+
+func TestALabelComposesWithTheNodesPublicDomain(t *testing.T) {
+	got, err := Resolve(shelf(proxy(), labelled("board", "git", 8080)),
+		[]string{"board"}, withDomain("example.tld"), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, mustDeclare(t, got))
+	if len(given) != 1 {
+		t.Fatalf("the proxy was told about %d of 1: %v", len(given), given)
+	}
+	if given[0].Values["name"] != "git.example.tld" {
+		t.Fatalf("the label did not compose with the domain: %v", given[0].Values)
+	}
+	// The port the module gave is still there — composing the name must not drop what the proxy
+	// needs to reach the workload.
+	if given[0].Values["port"] != float64(8080) {
+		t.Fatalf("composing the name dropped the port: %v", given[0].Values)
+	}
+}
+
+func TestOneNodeSettingMovesTheCatalogueBetweenDomains(t *testing.T) {
+	// The ADR's name-agnostic check: the same catalogue resolves against two different public
+	// domains by changing one node setting and nothing else.
+	one, err := Resolve(shelf(proxy(), labelled("board", "git", 8080)),
+		[]string{"board"}, withDomain("example.tld"), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	two, err := Resolve(shelf(proxy(), labelled("board", "git", 8080)),
+		[]string{"board"}, withDomain("other.example"), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	first := received(t, mustDeclare(t, one))[0].Values
+	second := received(t, mustDeclare(t, two))[0].Values
+
+	if first["name"] != "git.example.tld" || second["name"] != "git.other.example" {
+		t.Fatalf("the name did not track the domain: %v then %v", first["name"], second["name"])
+	}
+	// And nothing else moved: same label, same port. The domain is the one fact that changed.
+	if first["label"] != second["label"] || first["label"] != "git" {
+		t.Fatalf("the label changed with the domain: %v then %v", first["label"], second["label"])
+	}
+	if first["port"] != second["port"] {
+		t.Fatalf("the port changed with the domain: %v then %v", first["port"], second["port"])
+	}
+}
+
+func TestALegacyFullNameContributionPassesThroughUnchanged(t *testing.T) {
+	// Backward compatibility: a contribution that still carries a full `name` and no `label` is
+	// granted that name as-is, even on a node that has a public domain. This is what lets the
+	// catalogue migrate one module at a time while the running mesh keeps working.
+	legacy := Manifest{Module: "board", Version: "1",
+		Contributes: map[string]map[string]any{
+			"reverse-proxy": {"name": "git.pinned.example", "port": 8080},
+		}}
+	got, err := Resolve(shelf(proxy(), legacy), []string{"board"}, withDomain("example.tld"), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, mustDeclare(t, got))
+	if given[0].Values["name"] != "git.pinned.example" {
+		t.Fatalf("a full name was rewritten: %v", given[0].Values)
+	}
+	if _, grewLabel := given[0].Values["label"]; grewLabel {
+		t.Fatalf("a legacy contribution grew a label: %v", given[0].Values)
+	}
+}
+
+func TestALabelWithNoPublicDomainComposesNothing(t *testing.T) {
+	// A routed module on a node with no public domain has nothing to join its label to. It composes
+	// no name — which reads downstream exactly as a route that named no host, the same as before
+	// this existed — rather than an fabricated `git.` with a dangling dot.
+	got, err := Resolve(shelf(proxy(), labelled("board", "git", 8080)),
+		[]string{"board"}, workstation(), World{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	given := received(t, mustDeclare(t, got))
+	if _, named := given[0].Values["name"]; named {
+		t.Fatalf("a name was composed with no domain to compose it from: %v", given[0].Values)
+	}
+	if given[0].Values["label"] != "git" {
+		t.Fatalf("the label was lost: %v", given[0].Values)
+	}
+}
+
+func TestARoutedNameResolvesToTheServingNode(t *testing.T) {
+	// novox/hq ADR 0056 propagate: a granted route name is published into internal resolution,
+	// mapped to the node that serves it, alongside the `<node>.internal` names — so every
+	// container, and an in-mesh ACME validator, resolves a routed name to the proxy that serves it.
+	// The names map is what withMeshNames writes into every container as `--add-host`; a route name
+	// mapped to the serving node's address rides the same mechanism.
+	got := containersOf(t, Resolution{Node: "anchor", Modules: []Manifest{{
+		Module: "app",
+		Resources: []map[string]any{{"id": "web", "type": "container", "name": "web",
+			"image": "registry.example/web@sha256:" + strings.Repeat("a", 64)}},
+	}}}, Rendering{Names: map[string]string{
+		"anchor.internal": "10.42.0.1",
+		"git.example.tld": "10.42.0.1",
+	}})
+	if len(got) != 1 {
+		t.Fatalf("expected one container, got %d", len(got))
+	}
+	given := namesOf(got[0])
+	var sawNode, sawRoute bool
+	for _, h := range given {
+		if h == "anchor.internal:10.42.0.1" {
+			sawNode = true
+		}
+		if h == "git.example.tld:10.42.0.1" {
+			sawRoute = true
+		}
+	}
+	if !sawNode {
+		t.Fatalf("the container lost the mesh's node names: %v", given)
+	}
+	if !sawRoute {
+		t.Fatalf("the routed name was not published to the serving node: %v", given)
+	}
+}

internal/inventory/migrations/0019-a-nodes-public-domain.sql

@@ -0,0 +1,16 @@
+-- The public domain a node's routed names are composed under.
+--
+-- novox/hq ADR 0056. A public route used to carry its whole hostname in the module manifest, so
+-- running the same catalogue against a different domain — a lab standing in for production, a
+-- second operator's mesh — meant overriding that literal on every routed module. That made the
+-- mesh hold a map of names to services: the one thing it must not, because the subdomain is the
+-- operator's choice and the domain is the node's.
+--
+-- So the domain becomes a fact about the node, held here beside the node's other node-level
+-- configuration (its endpoint, its site, its overlay address). A module contributes only the label
+-- (the subdomain); the mesh composes <label>.<public-domain> and never interprets what it means.
+--
+-- Null for a node with no public domain, which is the ordinary case: most machines serve nothing
+-- to the outside. A routed module on such a node composes no name and the proxy simply has nothing
+-- to serve for it — additive, so an unmigrated catalogue carrying full hostnames is untouched.
+alter table node add column public_domain text;

internal/inventory/nodes.go

@@ -350,6 +350,40 @@ func (i *Inventory) SealingKeyOf(ctx context.Context, name string) (string, erro
 	return *key, nil
 }
 
+// SetPublicDomain records the domain a node's routed names are composed under.
+//
+// A node-level fact (novox/hq ADR 0056), kept beside the node's other node-level configuration
+// rather than in a module's settings: the subdomain is a module's to choose and the domain is the
+// node's, and the mesh joins the two without interpreting either. An empty domain clears it — a
+// node that stops facing the outside composes no names — which is why this writes null rather than
+// refusing.
+func (i *Inventory) SetPublicDomain(ctx context.Context, name, domain string) error {
+	node, err := i.NodeByName(ctx, name)
+	if err != nil {
+		return err
+	}
+	_, err = i.store.Pool().Exec(ctx,
+		`update node set public_domain = nullif($2, '') where id = $1`, node.ID, strings.TrimSpace(domain))
+	return err
+}
+
+// PublicDomainOf is the domain a node composes its routed names under, empty if it has none.
+func (i *Inventory) PublicDomainOf(ctx context.Context, name string) (string, error) {
+	var domain *string
+	err := i.store.Pool().QueryRow(ctx,
+		`select public_domain from node where name = $1`, name).Scan(&domain)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", fmt.Errorf("%w: %s", ErrNoSuchNode, name)
+	}
+	if err != nil {
+		return "", err
+	}
+	if domain == nil {
+		return "", nil
+	}
+	return *domain, nil
+}
+
 // RecordOverlayKey keeps the public half a node generated.
 func (i *Inventory) RecordOverlayKey(ctx context.Context, node, key string) error {
 	if strings.TrimSpace(key) == "" {

internal/inventory/public_domain_test.go

@@ -0,0 +1,72 @@
+package inventory
+
+import (
+	"testing"
+)
+
+// novox/hq ADR 0056 — a node's public domain is a node-level fact, held here beside its other
+// node-level configuration rather than in a module's settings. These check it round-trips, that a
+// node with none reports empty rather than failing, and that clearing it works — the setting the
+// ADR names as the whole of moving a catalogue between a lab and production.
+
+func TestAPublicDomainRoundTrips(t *testing.T) {
+	inv := fresh(t)
+	if _, err := inv.AddNode(t.Context(), "anchor"); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetPublicDomain(t.Context(), "anchor", "example.tld"); err != nil {
+		t.Fatal(err)
+	}
+	domain, err := inv.PublicDomainOf(t.Context(), "anchor")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if domain != "example.tld" {
+		t.Fatalf("set example.tld and read %q", domain)
+	}
+}
+
+func TestANodeWithNoPublicDomainReportsEmpty(t *testing.T) {
+	// Empty, not an error: most machines serve nothing to the outside, and a routed module on such
+	// a node simply composes no name.
+	inv := fresh(t)
+	if _, err := inv.AddNode(t.Context(), "workstation"); err != nil {
+		t.Fatal(err)
+	}
+	domain, err := inv.PublicDomainOf(t.Context(), "workstation")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if domain != "" {
+		t.Fatalf("a node that was never given a domain reported %q", domain)
+	}
+}
+
+func TestAPublicDomainCanBeCleared(t *testing.T) {
+	// A node that stops facing the outside composes no names. Clearing with an empty value is how
+	// that is said, and it must actually clear rather than store the empty string.
+	inv := fresh(t)
+	if _, err := inv.AddNode(t.Context(), "anchor"); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetPublicDomain(t.Context(), "anchor", "example.tld"); err != nil {
+		t.Fatal(err)
+	}
+	if err := inv.SetPublicDomain(t.Context(), "anchor", ""); err != nil {
+		t.Fatal(err)
+	}
+	domain, err := inv.PublicDomainOf(t.Context(), "anchor")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if domain != "" {
+		t.Fatalf("cleared the domain and read %q", domain)
+	}
+}
+
+func TestPublicDomainOfAnUnknownNodeFails(t *testing.T) {
+	inv := fresh(t)
+	if _, err := inv.PublicDomainOf(t.Context(), "never-seen"); err == nil {
+		t.Fatal("reading the domain of a node that does not exist was not refused")
+	}
+}