The mesh's knowledge is a fact a module asks for, not three modules

mesh-names, mesh-resolver and the names half of the overlay generators are gone.
They ran no software and could not be swapped for anything, which is the test of
whether something is a module at all — they existed because computed output
needed somewhere to live, and the control plane's only shape for output was a
module.

Now a module says where it wants what the mesh knows:

  facts: { node-zones: /etc/mesh-resolver/nodes.conf }

and is given a file, under its own name, applied and removed like anything else
it declares. Two facts exist: node-names (a hosts file — exact names) and
node-zones (every machine as a wildcard, *.homer.internal is homer). Asking for
a fact the mesh does not compute is refused naming what would have worked,
because a daemon that starts and reads a file nobody wrote is a worse way to
find out.

The names ride with the network now: wireguard's manifest asks for node-names
into /etc/hosts, because being on the private network is what gives a machine a
name. networking no longer requires name-resolution — names are not a provision,
and the module that answered it ran nothing.

One behaviour inverted, deliberately: choosing another VPN used to drag
WireGuard in anyway, because only WireGuard provided the addressing the names
module required — the node-scope claim existed to at least make that loud. With
names as a fact there is nothing to drag in: tailscale assigned means tailscale,
alone. The claim still catches two VPNs assigned explicitly.

And a machine the mesh cannot place is left out of both files rather than named
at nothing: a name resolving to nothing hangs a connection, where an unknown
name fails at once and says so. In practice that is only ever a token issued and
not yet used — a machine that has announced itself has an address.

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

internal/catalogue/declaration.go

@@ -498,6 +498,19 @@ func (r Resolution) Declaration(with Rendering) ([]map[string]any, error) {
 			}
 			out = append(out, copied)
 		}
+
+		// **What only the mesh knows, where this module asked for it.** The graph is the control
+		// plane's; making a name resolve is the module's software. Emitted as ordinary files under
+		// this module's name, so they are applied, reported and removed exactly as anything else
+		// it declares.
+		given, err := FactsInto(m, r, with.Names)
+		if err != nil {
+			return nil, err
+		}
+		for _, fact := range given {
+			fact["id"] = m.Module + "." + fmt.Sprint(fact["id"])
+			out = append(out, fact)
+		}
 	}
 	return out, nil
 }

internal/catalogue/facts.go

@@ -0,0 +1,145 @@
+package catalogue
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// What only the mesh knows, written where a module asks for it.
+//
+// **The graph is the control plane's; using it is the module's.** The mesh knows which machines
+// exist, what they are called, and where they are. Turning that into a name that resolves is
+// somebody's software, and which software is a choice the mesh should not be making.
+//
+// This replaced three modules — names, a resolver's data, and the private network's own
+// configuration — that existed only because computed output needed somewhere to live. They ran no
+// software and could not be swapped for anything, which is the test of whether something is a
+// module at all (novox/hq ADR 0040).
+
+const (
+	// FactNodeNames is every machine's name and address, as a hosts file.
+	//
+	// Exact names only: `homer` and `homer.internal` resolve to homer. Anything *under* a machine
+	// is a wildcard, which a hosts file cannot express — that is FactNodeZones.
+	FactNodeNames = "node-names"
+
+	// FactNodeZones is every machine as a wildcard: `*.homer.internal` is homer.
+	//
+	// Written in the form a resolver reads. A machine's own name and everything under it are one
+	// fact — if homer is at an address, so is anything homer serves.
+	FactNodeZones = "node-zones"
+)
+
+// facts is every fact the mesh computes, and what writes it.
+//
+// **A closed list.** A module asking for a fact the mesh does not have is asking for a file nobody
+// will write, and finding that out on a machine — as a daemon that starts, reads nothing, and
+// answers no queries — is worse than being told where the manifest is.
+var facts = map[string]func(Resolution, map[string]string) string{
+	FactNodeNames: nodeNames,
+	FactNodeZones: nodeZones,
+}
+
+// FactsInto renders the facts a module asked for, as files it will be given.
+//
+// The module owns everything after the file exists: loading it, restarting on it, what a resolver
+// does with it. This only puts it there.
+func FactsInto(m Manifest, r Resolution, addresses map[string]string) ([]map[string]any, error) {
+	if len(m.Facts) == 0 {
+		return nil, nil
+	}
+	names := make([]string, 0, len(m.Facts))
+	for name := range m.Facts {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	out := make([]map[string]any, 0, len(names))
+	for _, name := range names {
+		write, known := facts[name]
+		if !known {
+			return nil, fmt.Errorf(
+				"%s asks the mesh for %q, which it does not compute. It has %s",
+				m.Module, name, spokenFacts())
+		}
+		path := m.Facts[name]
+		if !strings.HasPrefix(path, "/") {
+			return nil, fmt.Errorf(
+				"%s asks for %q at %q, which is not an absolute path", m.Module, name, path)
+		}
+		out = append(out, map[string]any{
+			"id": "fact-" + name, "type": "file", "path": path, "mode": "0644",
+			"content": write(r, addresses),
+		})
+	}
+	return out, nil
+}
+
+// spokenFacts lists them, so a refusal says what would have worked.
+func spokenFacts() string {
+	names := make([]string, 0, len(facts))
+	for name := range facts {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return strings.Join(names, ", ")
+}
+
+// nodeNames is every machine's name and address, as a hosts file.
+//
+// **A machine with no address is left out.** The mesh has a record for it — somebody added it —
+// and does not yet know where it is, which is the ordinary state between adding a machine and it
+// joining. Writing the name anyway would give a name that resolves to nothing, and a connection to
+// that hangs; leaving it out fails at once and says the name is unknown.
+func nodeNames(r Resolution, addresses map[string]string) string {
+	var b strings.Builder
+	b.WriteString("# Generated by the mesh. Do not edit — this file is replaced whenever a machine\n")
+	b.WriteString("# joins or leaves, and an edit would survive until then and vanish.\n\n")
+	// The floor every Linux expects, and which removing would break things that have nothing to do
+	// with the mesh.
+	b.WriteString("127.0.0.1\tlocalhost\n")
+	b.WriteString("::1\t\tlocalhost ip6-localhost ip6-loopback\n")
+	if r.Node != "" {
+		fmt.Fprintf(&b, "127.0.1.1\t%s\n", r.Node)
+	}
+	b.WriteString("\n")
+	for _, name := range sortedNames(addresses) {
+		at := addresses[name]
+		// Its mesh name resolves to its address on the private network rather than to loopback,
+		// so a service binding the name it was given stays reachable from everywhere else.
+		fmt.Fprintf(&b, "%s\t%s.internal\t%s", at, name, name)
+		if name == r.Node {
+			b.WriteString("\t# this machine")
+		}
+		b.WriteString("\n")
+	}
+	return b.String()
+}
+
+// nodeZones is every machine as a wildcard, in the form a resolver reads.
+//
+// `*.homer.internal` is homer, which is the whole rule: if homer is at an address, so is anything
+// homer serves. A module wanting this runs the resolver; the mesh only says what is true.
+func nodeZones(_ Resolution, addresses map[string]string) string {
+	var b strings.Builder
+	b.WriteString("# Generated by the mesh. Do not edit — this file is replaced whenever a machine\n")
+	b.WriteString("# joins or leaves, and an edit would survive until then and vanish.\n\n")
+	for _, name := range sortedNames(addresses) {
+		fmt.Fprintf(&b, "address=/%s.internal/%s\n", name, addresses[name])
+	}
+	return b.String()
+}
+
+func sortedNames(addresses map[string]string) []string {
+	out := make([]string, 0, len(addresses))
+	for name, at := range addresses {
+		// See nodeNames: a machine the mesh cannot place is left out rather than named at nothing.
+		if at == "" {
+			continue
+		}
+		out = append(out, name)
+	}
+	sort.Strings(out)
+	return out
+}

internal/catalogue/facts_test.go

@@ -0,0 +1,97 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+var threeMachines = map[string]string{"homer": "10.42.0.1", "marge": "10.42.0.2", "bart": ""}
+
+// **`*.homer.internal` is homer. That is the whole rule.**
+func TestEveryMachineIsAWildcardUnderItsOwnName(t *testing.T) {
+	out := nodeZones(Resolution{Node: "homer"}, threeMachines)
+	for _, want := range []string{
+		"address=/homer.internal/10.42.0.1",
+		"address=/marge.internal/10.42.0.2",
+	} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("missing %q:\n%s", want, out)
+		}
+	}
+}
+
+// A machine the mesh has a record for and cannot place is left out of both.
+//
+// **Not an oversight — the alternative is worse.** A name written with no address resolves to
+// nothing, and a connection to that hangs. Leaving it out fails at once and says the name is
+// unknown, which is a thing somebody can act on.
+func TestAMachineWithNoAddressIsNotNamed(t *testing.T) {
+	for _, out := range []string{
+		nodeNames(Resolution{Node: "homer"}, threeMachines),
+		nodeZones(Resolution{Node: "homer"}, threeMachines),
+	} {
+		if strings.Contains(out, "bart") {
+			t.Fatalf("a machine with no address was named, so its name resolves to nothing:\n%s", out)
+		}
+	}
+}
+
+// A machine's own mesh name points at its address on the private network, not at loopback — or a
+// service binding the name it was given is unreachable from everywhere else.
+func TestAMachinesOwnNameIsItsMeshAddress(t *testing.T) {
+	out := nodeNames(Resolution{Node: "homer"}, threeMachines)
+	var line string
+	for _, l := range strings.Split(out, "\n") {
+		if strings.Contains(l, "homer.internal") {
+			line = l
+		}
+	}
+	if !strings.HasPrefix(line, "10.42.0.1") {
+		t.Fatalf("a machine's own mesh name is not its mesh address: %q", line)
+	}
+	// And the loopback floor is still there, or things with nothing to do with the mesh break.
+	if !strings.Contains(out, "127.0.0.1\tlocalhost") {
+		t.Fatalf("the loopback floor was removed:\n%s", out)
+	}
+}
+
+// A module says where it wants a fact, and is given a file.
+func TestAModuleIsGivenTheFactsItAskedFor(t *testing.T) {
+	m := Manifest{Module: "dnsmasq", Facts: map[string]string{FactNodeZones: "/etc/mesh/zones.conf"}}
+	given, err := FactsInto(m, Resolution{Node: "homer"}, threeMachines)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(given) != 1 {
+		t.Fatalf("expected one file, got %d", len(given))
+	}
+	if given[0]["path"] != "/etc/mesh/zones.conf" || given[0]["type"] != "file" {
+		t.Fatalf("not written where it was asked for: %v", given[0])
+	}
+	if !strings.Contains(given[0]["content"].(string), "homer.internal") {
+		t.Fatalf("the file does not hold the fact: %v", given[0]["content"])
+	}
+}
+
+// **Asking for a fact the mesh does not have is refused here, not on a machine.** A daemon that
+// starts, reads a file nobody wrote, and answers no queries is a much worse way to find out.
+func TestAskingForAFactTheMeshDoesNotHaveIsRefused(t *testing.T) {
+	m := Manifest{Module: "dnsmasq", Facts: map[string]string{"the-weather": "/etc/weather"}}
+	_, err := FactsInto(m, Resolution{}, nil)
+	if err == nil {
+		t.Fatal("a module asked for something nobody computes and was given nothing, silently")
+	}
+	for _, known := range []string{FactNodeNames, FactNodeZones} {
+		if !strings.Contains(err.Error(), known) {
+			t.Fatalf("the refusal does not say what would have worked: %v", err)
+		}
+	}
+}
+
+// And a relative path is refused, or a module decides where the mesh writes on a machine.
+func TestAFactMustBeAskedForAtAnAbsolutePath(t *testing.T) {
+	m := Manifest{Module: "dnsmasq", Facts: map[string]string{FactNodeNames: "etc/hosts"}}
+	if _, err := FactsInto(m, Resolution{}, nil); err == nil {
+		t.Fatal("a relative path was accepted")
+	}
+}

internal/catalogue/manifest.go

@@ -315,6 +315,25 @@ type Manifest struct {
 	// that could only see its own ports would write a rule set that closed everything else.
 	Filtering *Filtering `json:"filtering,omitempty"`
 
+	// Facts are things only the mesh knows, written where this module asks for them.
+	//
+	// **The graph is the control plane's; how a machine uses it is the module's.** The mesh knows
+	// which machines exist, what they are called and where they are. Making a name resolve, or a
+	// peer reachable, is somebody's software — dnsmasq, a resolver, a VPN — and the mesh has no
+	// business shipping one, choosing which, or knowing its configuration language.
+	//
+	// So a module says *put the node names here* and owns everything after that. The same shape as
+	// `filtering`, generalised: a fact, and a path.
+	//
+	// It replaces three modules that existed only because computed output needed somewhere to
+	// live — they ran no software, could not be swapped for anything, and appeared in the graph as
+	// modules while being a data channel wearing a costume.
+	//
+	// Keyed by fact name; the names are a closed list, because a module asking for one the mesh
+	// does not compute is asking for something nobody will write, and finding that out on a machine
+	// is worse than being told here.
+	Facts map[string]string `json:"facts,omitempty"`
+
 	// Certificate is where this module wants a certificate for its machine's name inside the
 	// mesh, and where the key that goes with it can be found.
 	//

internal/catalogue/provided_test.go

@@ -19,7 +19,7 @@ func provided(t *testing.T) map[string]catalogue.Manifest {
 	t.Helper()
 	out := map[string]catalogue.Manifest{}
 	for _, raw := range []map[string]any{
-		overlay.Manifest(), overlay.NamesManifest(), overlay.DomainManifest(),
+		overlay.Manifest(), overlay.DomainManifest(),
 	} {
 		b, err := json.Marshal(raw)
 		if err != nil {
@@ -44,22 +44,51 @@ func TestTheShippedNetworkingModulesResolveOnTheirOwn(t *testing.T) {
 	for _, m := range got.Modules {
 		have = append(have, m.Module)
 	}
-	for _, want := range []string{overlay.Domain, overlay.Name, overlay.Names} {
+	for _, want := range []string{overlay.Domain, overlay.Name} {
 		if !strings.Contains(strings.Join(have, " "), want) {
 			t.Fatalf("%s did not bring in %s: %v", overlay.Domain, want, have)
 		}
 	}
+
+	// **The names come WITH the network now, not from a third module.** Being on the private
+	// network is what gives a machine a name, so the provider asks for the node-names fact and
+	// there is nothing else to bring in. A module that ran nothing used to be here.
+	for _, m := range got.Modules {
+		if m.Module == overlay.Name && m.Facts["node-names"] == "" {
+			t.Fatalf("the network's provider does not ask for the names: %+v", m.Facts)
+		}
+	}
 }
 
-func TestTheShippedWireGuardModuleClaimsBeingTheNetwork(t *testing.T) {
-	// Without this, a person who chose another VPN gets WireGuard as well, dragged in by the
-	// names, and is not told. The claim is the only thing that catches it.
+func TestAnotherVPNSatisfiesNetworkingWithoutDraggingWireGuardIn(t *testing.T) {
+	// **This inverted, and the inversion is the improvement.** The names used to be a module that
+	// required the mesh's own addressing, which only WireGuard provided — so choosing another VPN
+	// dragged WireGuard in anyway, and the node-scoped claim existed to at least make that
+	// collision loud. With the names a fact rather than a provision, a person who chose tailscale
+	// gets tailscale, and there is nothing left to collide.
 	shipped := provided(t)
-	_, err := catalogue.Resolve(
+	got, err := catalogue.Resolve(
 		withTailscale(shipped),
 		[]string{overlay.Domain, "tailscale"},
 		catalogue.Node{Name: "workstation", Site: "house"}, catalogue.World{})
+	if err != nil {
+		t.Fatalf("choosing another VPN was refused: %v", err)
+	}
+	for _, m := range got.Modules {
+		if m.Module == overlay.Name {
+			t.Fatalf("the other VPN was chosen and WireGuard came anyway: %v", got.Modules)
+		}
+	}
+}
 
+func TestTwoVPNsAssignedTogetherStillCollide(t *testing.T) {
+	// The claim still guards the case it was always for: both assigned EXPLICITLY, which is a
+	// machine with two private networks and a coin toss about which one a peer reaches it on.
+	shipped := provided(t)
+	_, err := catalogue.Resolve(
+		withTailscale(shipped),
+		[]string{overlay.Name, "tailscale"},
+		catalogue.Node{Name: "workstation", Site: "house"}, catalogue.World{})
 	if err == nil {
 		t.Fatal("a machine was given two private networks and nobody was told")
 	}
@@ -68,20 +97,9 @@ func TestTheShippedWireGuardModuleClaimsBeingTheNetwork(t *testing.T) {
 	}
 }
 
-func TestTheShippedNamesModuleNeedsTheMeshsOwnAddresses(t *testing.T) {
-	// Over a VPN whose addresses the mesh does not hand out, it has no names to write. Refusing
-	// is what stops a machine getting a hosts file that means nothing on it.
-	shipped := provided(t)
-	delete(shipped, overlay.Name)
-	_, err := catalogue.Resolve(shipped, []string{overlay.Names}, catalogue.Node{Name: "workstation", Site: "house"}, catalogue.World{})
-
-	if err == nil {
-		t.Fatal("the mesh's names resolved with nothing handing out the mesh's addresses")
-	}
-	if !strings.Contains(err.Error(), overlay.Addressing) {
-		t.Fatalf("the refusal does not name what is missing: %v", err)
-	}
-}
+// The names-need-addressing test went with the names module: names are a fact now, and a machine
+// the mesh cannot place is simply left out of the file (facts_test.go) — which is the same
+// protection, enforced where the file is written rather than by a provision refusing.
 
 func withTailscale(shelf map[string]catalogue.Manifest) map[string]catalogue.Manifest {
 	out := map[string]catalogue.Manifest{}