Merge pull request 'ADR 0194: the mesh has one resolver, and every node asks it for the mesh's names' (#326) from decision/0194-the-mesh-has-one-resolver into main

03-DESIGN/01-to-be/08-connectivity.md

@@ -10,6 +10,7 @@ code:
   - mesh-host internal/apply (the service that reflects a rule set)
 updated: 2026-10-03
 decisions:
+  - 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
   - 02-DECISIONS/0191-the-meshs-resolver-holds-only-the-meshs-own-names.md
   - 02-DECISIONS/0180-the-found-front-end-is-uninstalled-once-a-machine-is-converged.md
   - 02-DECISIONS/0170-the-firewall-seat-serves-its-verbs.md
@@ -290,8 +291,9 @@ expensively enough to be worth restating:
 - **A node must not pin its own public name locally.** The duplicate record breaks resolution of
   that name for everything else that needs it.
 
-**What the host receives:** the resolver's configuration, as files, listing every peer's internal
-name and overlay address.
+**What the host receives:** what to ask, not what to answer. The mesh has **one resolver**, holding
+every node's internal domain; a node routes the mesh's suffix to it and every other name to public
+resolvers ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).
 
 **What goes away:** the `/etc/hosts` floor. It exists because a node had to reach the mesh
 database before its own DNS existed; with [ADR 0004](../../02-DECISIONS/0004-a-node-and-how-it-joins.md)
@@ -349,6 +351,29 @@ not a list of containers.
 somebody starts by hand is not the mesh's to configure, and reaching into every container on a
 machine — declared or not — is what a nameserver in `resolv.conf` would be for.
 
+### One resolver for the mesh
+
+*2026-10-03.* **The mesh's names live in one place: the module holding `mesh-resolver`**, a mesh-scoped
+seat of capacity one, placed on the node every tunnel converges on. It holds one wildcard per node —
+`<node>.internal` and everything under it — and listens on the private network only. Every node's
+`node-resolver-config` routes the mesh's suffix to it and leaves every other name with public
+resolvers; plain `resolv.conf` cannot route by domain, so the asking side is a stub that can — a
+`systemd-resolved` module claiming `node-resolver-config` in place of `resolv-conf`, routing the
+suffix to `mesh-resolver`. The container runtime cannot use a loopback stub, so its `dns` names
+`mesh-resolver`, which forwards public names for containers — the one place a public name passes
+through the mesh
+([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).
+
+**No node holds a copy.** The per-node resolver, its zones file and the mesh's region of `/etc/hosts`
+go: every resolution fault found on 2026-10-03 was a copy disagreeing with the truth — a hosts file
+read once at start, an operator's old line beside the mesh's, a node's resolver lent to a LAN. No
+member's resolver answers a LAN; a router pointing at one is moved first. *Checked by `resolvectl` on
+each node (the tunnel's link, `mesh-resolver`, the suffix as routing domain), by no node but the
+holder answering DNS on a private or LAN address, and by the router's DHCP DNS option naming no node.*
+
+*What follows describes the per-node resolver this replaces — how it was built and why the roles were
+split. The split stands; the serving role's scope is what moved.*
+
 ### The resolver, built
 
 *2026-08-31.* **A service is reached at `<service>.<node>.internal`** — the first label is the
@@ -988,6 +1013,9 @@ The list is worth having in one place, because it is most of the argument:
 
 ## Open
 
+- **One resolver ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)).** Not built: every node still runs
+  `node-dns-resolver`. The migration's four steps are in the record, in order.
+
 - ~~**What happens when the hub is down.**~~ **Resolved** by
   [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md), together with `06`'s
   matching question — they were one question. Nothing takes over. WireGuard has no failover, the

03-DESIGN/01-to-be/26-the-seats.md

@@ -1,6 +1,6 @@
 ---
 layer: to-be
-status: implemented
+status: in-progress
 code:
   - mesh-controller internal/catalogue/seats.go
   - mesh-controller internal/catalogue/resolve.go
@@ -10,8 +10,9 @@ code:
   - mesh-controller cmd/mesh-controller/source.go
   - mesh-controller internal/inventory/migrations/0032-a-source-may-live-on-a-seat.sql
   - mesh-catalog modules/gitea/module.json
-updated: 2026-10-01
+updated: 2026-10-03
 decisions:
+  - 02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md
   - 02-DECISIONS/0161-what-deserves-a-seat.md
   - 02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md
   - 02-DECISIONS/0126-a-module-declares-its-own-seats.md
@@ -126,7 +127,8 @@ convention, which later seats departed from.
 | `mesh-npm-package-registry` | `npm-package-registry` | mesh | `npm-package-registry` | the forge |
 | `mesh-git` | `git` | mesh | `git` | the forge |
 | `mesh-build-machine` | `the-build-machine` | node | — | a builder |
-| `mesh-dns-port` | `the-dns-port` | node | — | the local resolver |
+| `mesh-resolver` | — | mesh | — | the mesh's one resolver, holding every node's internal domain ([ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)) |
+| ~~`mesh-dns-port`~~ | `the-dns-port` | node | — | retired by [ADR 0194](../../02-DECISIONS/0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md): the local resolver became the mesh's one |
 | `mesh-intrusion-prevention` | `the-intrusion-prevention` | node | — | an intrusion-prevention service |
 | `mesh-packet-filter` | `the-packet-filter` | node | — | the packet filter |
 | `mesh-private-network` | `the-private-network` | node | — | the private network the mesh runs over |