ADRs 0138 and 0139: an assignment binds an endpoint and says how far it reaches, and a network is forwarded because a module declared it

Both follow from the same rule the mesh is built on — a node's configuration is
composed from the modules assigned to it. Reach was settled separately by the
filter, the proxy's names and the certificate authority, so "this must not be
public" could not be written; it becomes one value on the assignment that all
three read. And the forward chain consulted two constants plus a typed list
although modules already declare their networks; it now forwards what they
declared, with the host rendering the addresses it allocated.

02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md

@@ -1,6 +1,6 @@
 ---
 topic: what runs on it
-status: proposed
+status: accepted
 date: 2026-09-25
 deciders: jochen
 reconstructed: false

02-DECISIONS/0137-a-machine-says-which-networks-it-routes.md

@@ -0,0 +1,116 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-09-28
+deciders: jochen
+extends: 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
+reconstructed: false
+---
+
+# 137. A machine says which networks it routes
+
+## Context
+
+The filter the mesh derives denies forwarding by default, because without a forward chain it says
+nothing about a container's published port
+([ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md), [issue 047](../04-ISSUES/047-the-firewall-does-not-cover-published-container-ports/00-report.md)).
+To keep a machine's own containers working it then allows two ranges: the container runtime's
+default bridge pool, and the pool its compose files are given. Those two are named in the
+controller's code, with a comment saying what the gap is:
+
+> A machine whose runtime is configured with something else needs this to say so — which is a thing
+> the mesh cannot derive and a reason this list is named here rather than computed.
+
+**There was no way to say so.** The list was a constant. A machine whose guests live anywhere else
+was filtered by a rule that looked deliberate and was a guess.
+
+**Measured, on the day a workstation was converged.** Flipping it cut egress for five of its
+container networks at once, and for every network its test beds create — the beds allocate a fresh
+range per run, from a pool neither default covers. Nothing reported a fault. The containers could
+not reach anything, the machine went on reporting that it had applied what it was told, and the
+converge preview had said nothing about it either, because the preview lists what *listens* and
+routing is not a listener.
+
+**And two questions, not one.** A guest also asks its host for an address and for names. Both arrive
+at the input chain, where nothing declared them, so denying by default left the guests of a routed
+network with no address and no resolution — which is not a closed port but a network that does not
+function, asked for by this machine's own guest.
+
+**Why the machine cannot simply be read.** A test bed creates its bridge while it runs, between one
+declaration and the next, so a filter derived from what the machine last reported would be correct
+only for the networks that already existed when it was composed. A declared range covers the ones
+that do not exist yet.
+
+## Decision
+
+**A machine says which networks it routes for what it hosts, and the filter forwards them.** A
+node-level fact, beside the node's public domain
+([ADR 0066](0066-public-routing-is-name-agnostic.md)) and for the same reason: the
+machine routes them, and the module that loads the filter holds a seat and may be replaced.
+
+**Added to the runtime's defaults, never replacing them.** A machine that names one range has not
+stopped hosting whatever was already on the runtime's own pools, and replacing would trade one
+silent breakage for another.
+
+**Their guests keep address and name service.** For a network that was named, the input chain admits
+that network's own DHCP and DNS, and nothing else: everything else a guest might want from its host
+is a port somebody declares, like every other port on this machine.
+
+**Said in CIDR form and checked when it is said.** An entry that does not parse is a line nftables
+refuses, and a refused ruleset is a machine filtering nothing while its unit reports a fault — so
+the refusal happens where a person can read it, not on the machine.
+
+**A machine that says nothing is filtered exactly as before.** Every machine already converged is
+untouched by this.
+
+## Options considered
+
+1. **Leave it constant and edit the code per installation.** Rejected: the value is a property of
+   one machine, the code is the whole mesh's, and the two ranges as they stand describe a machine
+   whose runtime was left at its defaults. It is also how this got here.
+2. **Derive it from what the machine reports.** Rejected as insufficient, not as wrong: it cannot
+   cover a network created between two declarations, which is precisely the case that was broken. It
+   would also make the filter follow whatever appeared on the machine, which is a firewall that
+   widens itself.
+3. **A per-node setting on the module that loads the filter.** Rejected: the machine routes the
+   networks. The filter module holds a node-scoped seat and is meant to be replaceable, and a
+   replacement must not lose the machine's own truth.
+4. **Replace the defaults with what is said.** Rejected: see the decision. The first machine to name
+   its bed range would lose its containers.
+5. **Admit all input from a routed network, not only address and name service.** Rejected: that is
+   every port on the machine open to anything it hosts, which is the derivation abandoned.
+
+## Consequences
+
+**The converge preview says what a machine routes**, including when it routes nothing but the
+defaults, with the command that changes it. The preview's own sentence about traffic it cannot
+preview stays, because a tunnel and the found firewall's NAT are still not previewable.
+
+**A machine whose guests are already broken by an earlier flip is fixed by saying its networks and
+pushing**, with no flip to undo.
+
+**The list is one more thing that can be wrong and stale.** A range removed from the machine and
+left here keeps forwarding for a network that no longer exists, which admits nothing, because there
+is no guest on it to admit. That is the safe direction of being out of date.
+
+## How this is checked
+
+- **What a machine says it routes is forwarded, and its guests keep address and name service.** A
+  test renders a ruleset for a machine that names one range and asserts both chains, per chain body
+  so a line in the wrong chain cannot pass it. It fails against the previous behaviour, which is how
+  it was written.
+- **The runtime's own defaults survive naming a range.** Asserted in the same test.
+- **A machine that names nothing renders byte-identically to one that names nil**, so every machine
+  already behind this filter is untouched.
+- **Each family is matched in its own syntax.** A test with one v4 and one v6 network asserts
+  `ip saddr` and `ip6 saddr`, because one set holding both is a syntax error and a ruleset that does
+  not load is a machine filtering nothing.
+- **An entry that is not a network is refused where it is said**, by the parse in the setter.
+
+## References
+
+- [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md) — the derived filter this completes
+- [ADR 0066](0066-public-routing-is-name-agnostic.md) — the precedent for a node-level fact
+- [issue 047](../04-ISSUES/047-the-firewall-does-not-cover-published-container-ports/00-report.md) — why there is a forward chain at all
+- [issue 137](../04-ISSUES/137-converging-a-machine-cut-off-its-own-guests/00-report.md) — the measurement that produced this
+- mesh-controller `internal/catalogue/filtering.go` — the constant whose own comment named this gap

02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md

@@ -0,0 +1,154 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-09-28
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md
+---
+
+# 138. An assignment binds an endpoint and says how far it reaches
+
+## Context
+
+[ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md) settled that a machine's
+packet filter is derived from what its modules declare they listen on, and that the `from` of a
+listen "is the whole of public-versus-internal". That was true of the packet filter, and it turned
+out to be true of nothing else.
+
+Reachability is now settled three times, in three places, by three mechanisms that cannot disagree
+out loud ([issue 140](../04-ISSUES/140-an-endpoints-reach-is-not-declared/00-report.md)):
+
+- **The filter** reads a listen's source, and a per-node setting may override it. That setting has
+  exactly one caller in the control plane — the function that builds the node's rules.
+- **The names** come from a route contribution, which names a label and a port and says nothing
+  about reach. The reverse proxy composes a **public** name and an **internal** name for every route
+  it is given, because it can.
+- **The certificate authority** follows from which names exist. Measured on the control-node: an
+  identity provider carries a public certificate valid 90 days and an internal one valid 24 hours and
+  renewed daily. No assignment asked for either.
+
+So *this endpoint must not be public* cannot be written. It is therefore enforced by nothing, while a
+public certificate for that very name is obtained automatically — the fault
+[how-we-build.md](../00-META/how-we-build.md) names, an unenforced rule being indistinguishable from
+a wrong one, with the additional cost that the wrong thing is done eagerly.
+
+And a port that is not routed cannot be spoken about at all beyond the filter. The forge serves git
+over ssh; that endpoint has no name, no certificate and no way to be called public except a key only
+the filter reads.
+
+**Two per-node settings already exist and are half of this.** One gives a module's declared port a
+machine port. One overrides a declared port's source. They key on port numbers, so nothing ties a
+port to the route that serves it: a route contribution names a port too, and the two are equal only
+by coincidence.
+
+**Where this belongs is already decided.** [ADR 0046](0046-a-module-configuration-is-its-assignments-not-its-manifest.md)
+says a module's configuration is its assignments. Whether the forge answers git-over-ssh from the
+public internet is a fact about one installation and one machine, not a property of the software —
+and [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md) already refuses an
+installation's decisions in a definition.
+
+## Considered Options
+
+1. **Leave reach in the manifest, as `from` today.** Rejected: it is an installation's decision
+   written into the definition, and it cannot differ between two machines running the same module —
+   which is exactly the case the forge presents.
+2. **Extend the existing source override to the names and the certificate, without naming
+   endpoints.** Rejected: it keys on a port number. A module's route contribution names a port as
+   well, and nothing says the two are the same thing, so one statement cannot be made to reach all
+   three mechanisms. Naming the endpoint is what makes that possible.
+3. **Derive reach from whether the node has a public domain recorded.** Rejected: that is a property
+   of the machine, and two endpoints on one machine differ — a database and a web front end on the
+   same host.
+4. **A fourth reach for "public name, internal authority"** — a name that resolves publicly and must
+   not appear in a public issuance log, obtained by DNS-01. Deferred, not rejected: it is a real case
+   and it is a question about which challenge an authority uses, not about how far an endpoint
+   reaches. Left to the certificate work as an open question.
+5. **Make the manifest silent on reach and require every assignment to state it.** Rejected for the
+   transition: every endpoint reachable today would close until an assignment named it, which is a
+   flag day across the whole catalogue.
+
+## Decision
+
+**A module declares named endpoints.** An endpoint is one port the module serves, with a name the
+module chooses, its protocol, and what it is for. A route contribution **names the endpoint it
+routes** rather than repeating a port number. The manifest says what the module serves and what it
+would serve it to by default; it does not say what this installation does with it.
+
+**An assignment binds each endpoint and says how far it reaches.** Per node: the machine port the
+endpoint is published on, and its **reach** — one of `internal`, `public` or `both`. An assignment
+that states nothing keeps the manifest's default, so no machine changes until an assignment says so.
+
+**Reach means all three mechanisms at once, and is the only thing that decides them.**
+
+- `internal` — the filter opens the machine port to the private network; the proxy serves the
+  internal name and not the public one; the certificate comes from the mesh's own authority.
+- `public` — the filter opens it to anywhere; the proxy serves the public name; the certificate
+  comes from the public authority.
+- `both` — both names, each from its own authority, and the filter opens to anywhere.
+
+**An endpoint that is not routed is reached but never named.** An endpoint with no route contribution
+yields filter rules and nothing else: no name is composed and no certificate is requested. Git over
+ssh is that case, and it is the case the model could not express.
+
+**The authority stops being chosen by which names happen to exist.** The proxy composes the names the
+assignments asked for, and asks each name's own authority for it. A name nobody asked for is not
+composed, so it is not certified.
+
+**The two existing settings are this, completed.** The per-node port mapping becomes the endpoint's
+binding. The per-node source override becomes its reach, widened from the filter alone to the names
+and the certificate as well.
+
+## Consequences
+
+- **A manifest gains endpoint names, and a route contribution names an endpoint instead of a port.**
+  Every routed module's manifest changes. The word ships one release before any manifest uses it, and
+  reaches the build machine and the control plane first.
+- **One derived value is read by three things** — the filter's rules, the proxy's contributions, the
+  certificate request — so they can no longer disagree, and a disagreement becomes a refusal at the
+  assignment rather than a surprise on a machine.
+- **A name that must not be public becomes writable, and therefore checkable.** It also gives
+  [issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md) a
+  declared answer to read: which endpoints are internal is what says whose root must be installed
+  where.
+- **[Issue 139](../04-ISSUES/139-an-internal-route-name-resolves-to-the-consumers-node/00-report.md)
+  becomes answerable**: the endpoint's assignment names the machine that serves it, which is the fact
+  the internal name should be composed from.
+- **Reach becomes reportable.** The mesh can say, per endpoint, where it is reachable from and which
+  authority holds its certificate — neither of which `status` can say today.
+- **This narrows [ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md).** Its
+  decision stands: the firewall is derived and host-applied, not a provider. What no longer holds is
+  that a listen's `from` is the whole of public-versus-internal; it is the filter's share of a
+  statement that also governs names and certificates.
+- **What got harder:** every endpoint needs a name, including a module that serves exactly one port
+  and had no reason to name it. And an installation that wants a module public must now say so on the
+  assignment rather than inheriting it from the definition, which is more to say and the reason it is
+  right.
+
+## How it is checked
+
+- **One module, two endpoints, different reach.** A module declaring an internal endpoint and a
+  public one renders a filter opening one to the private network and one to anywhere, asserted per
+  chain body so a rule in the wrong chain cannot pass.
+- **The names follow the reach.** The same module's routed endpoint composes the internal name only
+  when internal, the public name only when public, and both when both — and a certificate is
+  requested from the matching authority for each name composed and for no other. This fails against
+  the previous behaviour, where both names and both certificates are always composed, which is how
+  it is written.
+- **An unrouted endpoint is filtered and never named.** Asserted for an endpoint with reach and no
+  route contribution: rules rendered, no contribution, no certificate request.
+- **An assignment naming an endpoint the module does not declare is refused where it is said**, as is
+  a reach that is not one of the three — before it reaches a machine, because a ruleset that does not
+  load is a machine filtering nothing.
+- **An assignment that states nothing renders byte-identically to today**, so every machine already
+  converged is untouched until its assignment says otherwise.
+
+## References
+
+- [ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md) — narrowed here
+- [ADR 0046](0046-a-module-configuration-is-its-assignments-not-its-manifest.md) — where reach belongs
+- [ADR 0066](0066-public-routing-is-name-agnostic.md) — the public name this composes
+- [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md) — why reach is not a definition's
+- [issue 140](../04-ISSUES/140-an-endpoints-reach-is-not-declared/00-report.md) — the measurement
+- [issue 139](../04-ISSUES/139-an-internal-route-name-resolves-to-the-consumers-node/00-report.md),
+  [issue 129](../04-ISSUES/129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md)

02-DECISIONS/0139-a-network-is-forwarded-because-a-module-declared-it.md

@@ -0,0 +1,136 @@
+---
+topic: what runs on it
+status: accepted
+date: 2026-09-28
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0137-a-machine-says-which-networks-it-routes.md
+---
+
+# 139. A network is forwarded because a module declared it
+
+## Context
+
+[ADR 0137](0137-a-machine-says-which-networks-it-routes.md), decided the same week, gave a machine a
+way to say which networks it routes for its guests. It was written because the derived filter's
+forward chain allowed two ranges named as constants in the control plane's source — the container
+runtime's bridge pool, and part of the pool its compose files are given — with a comment admitting
+the gap: *a machine whose runtime is configured with something else needs this to say so, which is a
+thing the mesh cannot derive.*
+
+**It can be derived, and from the right place.** Measured on the last machine still to be converged
+([issue 141](../04-ISSUES/141-the-forward-chain-does-not-follow-the-modules/00-report.md)): twenty-one
+container networks, nine inside the runtime's bridge pool, twelve in the other private range, and six
+of those outside the constant's lower bound — so the flip would have cut their guests off exactly as
+it did on the workstation that produced 0137.
+
+Naming a range to cover the six is what 0137 provides for, and it is the wrong instrument. Of those
+six networks, **four are networks the mesh's own modules declare**, present as network resources in
+the node's plan and created by the host because a module asked for them. **Two are the predecessor's
+leftovers** — compose networks of services the mesh does not run. Any range wide enough to keep the
+four forwards the two as well: a firewall widened by hand to protect networks that should not exist.
+
+The mesh already knows which of the twenty-one are its own, because it made them.
+
+**And the node's configuration is meant to follow the modules assigned to it.** That is the mesh's
+founding shape — the machine runs modules, and its files, its filter and its accounts are composed
+from what runs there ([ADR 0005](0005-the-node-host.md),
+[ADR 0010](0010-delivery.md),
+[ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md)). The forward chain is the
+one derived thing that consults a constant and a list a person types.
+
+## Considered Options
+
+1. **Keep 0137 as it stands** — two constants plus a named list. Rejected: the list is written in
+   addresses, and addresses are what the runtime allocates, so the only entry safe enough to keep a
+   machine working is wider than the truth. It cannot distinguish a network the mesh made from one
+   left behind, which is the distinction that decides whether forwarding it is correct.
+2. **Derive it from what the machine reports.** Still rejected, on 0137's own grounds: a test bed
+   creates its bridge between one declaration and the next, and a filter that follows whatever
+   appeared on a machine is a firewall that widens itself. **This decision is not that** — see below.
+3. **Have the control plane allocate each module network's range from a pool it owns,** so it can
+   render the address itself. Rejected: more machinery for no gain. The runtime already allocates and
+   the host already knows, and taking allocation over means the mesh owning an address space it has no
+   other reason to own.
+4. **Have each module declare its network's range.** Rejected by
+   [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md): a definition names no address,
+   and the same definition runs on machines whose runtimes have allocated differently.
+
+## Decision
+
+**A network is forwarded because a module declared it.** Per node, the forward chain forwards the
+networks of the modules assigned there, and by default nothing else. A module unassigned stops being
+forwarded at the next reconcile.
+
+**The host resolves a declared network to its addresses.** A network resource carries a name; the
+runtime allocates the subnet when the network is created. So the control plane declares *forward the
+networks these modules asked for* and the host — which made them, and already resolves a container by
+its name — renders the addresses. [ADR 0005](0005-the-node-host.md) holds: the host applies, it does
+not decide.
+
+**Deriving from the declaration is not deriving from the machine.** Both of 0137's objections fall
+away. The set is known before the network exists, because a module declared it, so a network created
+between two declarations is already in the one that asked for it. And it cannot widen itself: a
+network nobody declared is never forwarded, however it appeared on the machine.
+
+**The runtime's own default bridge is forwarded, from what the runtime reports.** Containers that name
+no module network attach to it, and it belongs to the runtime rather than to any module — so the host
+renders it from what the runtime says, not from a range named in the control plane. The constants go.
+
+**What a machine says is for guests no module declares.** A test bed is not a module and its range is
+not a module's; that is the case 0137's mechanism is for, and it keeps it — added to the derived set,
+never replacing it, as 0137 decided. Narrowed to that, it is named for it.
+
+**Their guests keep address and name service**, per declared network, unchanged from
+[ADR 0137](0137-a-machine-says-which-networks-it-routes.md): the input chain admits that network's own
+DHCP and DNS and nothing else.
+
+## Consequences
+
+- **The two constants are removed**, and with them the class of fault that a machine's guests depend
+  on a range that describes some other machine.
+- **This is a behaviour change, not a refactor.** On the machine measured, the derived set and the
+  constant do not cover the same ground — that is the whole reason for the record. A machine whose
+  module networks happen to fall inside the old ranges renders the same rules.
+- **A range that exists only to keep a leftover alive becomes visible as such**, because it will not
+  be in the derived set and has to be said out loud to survive.
+- **`node networks` narrows** to guests no module declares, and the preview says which of a machine's
+  networks are the mesh's and which are not, so the difference is readable before a flip rather than
+  after.
+- **A module's declaration gains nothing.** It already declares its network; what changes is that the
+  filter reads it.
+- **What got harder:** the host renders part of the forward chain from what it created, so the
+  control plane no longer holds the whole rule set as text. The rule the mesh states is the set of
+  networks; the addresses are the machine's.
+
+## How it is checked
+
+- **Only declared networks are forwarded.** A node with two modules that declare networks renders
+  forward rules for exactly those two, and none for a third network present on the machine that no
+  module declared. This fails against the previous behaviour, which forwards by range and cannot tell
+  them apart, and that is how it is written.
+- **Unassigning a module removes its network's rule** at the next reconcile, asserted on the rendered
+  chain rather than on the intent.
+- **Guests of a declared network keep address and name service**, asserted per chain body so a line in
+  the wrong chain cannot pass — carried from 0137.
+- **The runtime's own default bridge comes from the runtime**, asserted by rendering for a runtime
+  whose default bridge is somewhere other than the range the constant named.
+- **A machine that names a range for guests no module declares still gets it**, added to the derived
+  set and not replacing it.
+- **Each family is matched in its own syntax**, carried from 0137: one set holding both is a syntax
+  error, and a ruleset that does not load is a machine filtering nothing while its unit reports a
+  fault.
+
+## References
+
+- [ADR 0137](0137-a-machine-says-which-networks-it-routes.md) — narrowed here; its mechanism keeps the
+  case it is right for
+- [ADR 0005](0005-the-node-host.md) — the host applies; the addresses are the machine's
+- [ADR 0045](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md) — the filter is derived from
+  what runs there
+- [ADR 0112](0112-a-module-definition-names-no-node-mesh-or-path.md) — why a module does not name its
+  range
+- [issue 141](../04-ISSUES/141-the-forward-chain-does-not-follow-the-modules/00-report.md) — the
+  measurement
+- [issue 137](../04-ISSUES/137-converging-a-machine-cut-off-its-own-guests/00-report.md) — the
+  breakage that produced 0137

02-DECISIONS/README.md

@@ -205,7 +205,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0091** — [A mount is declared, and there are three things it can be](0091-a-mount-is-declared-three-ways.md)
 - **0099** — [A step that runs once names what it reads, and runs again when it changed](0099-a-step-that-runs-once-names-what-it-reads.md)
 - **0110** — [A seat is held by one assignment, from a closed set, and it may deliver a provision](0110-a-seat-is-a-module-assignment-from-a-closed-set.md)
-- **0112** — [A module definition names no node, no mesh and no path: everything it needs is a requirement the mesh resolves](0112-a-module-definition-names-no-node-mesh-or-path.md)  *(proposed)*
+- **0112** — [A module definition names no node, no mesh and no path: everything it needs is a requirement the mesh resolves](0112-a-module-definition-names-no-node-mesh-or-path.md)
 - **0113** — [The vault makes every shared secret, a provider makes resources and data, and the mesh carries both](0113-the-vault-makes-every-secret.md)  *(proposed)*
 - **0114** — [A credential two parties hold rotates over two credentials; one a single party holds rotates in place, staged; and retiring a credential never removes what it reached](0114-a-shared-credential-rotates-over-two-credentials.md)  *(proposed)*
 - **0115** — [One assignment of a module per node: the module's name is the assignment's identity](0115-one-assignment-of-a-module-per-node.md)  *(proposed)*
@@ -217,6 +217,9 @@ python3 00-META/checks/index.py            fail if stale
 - **0133** — [A module owns its migrations, and the mesh owns when they run](0133-a-module-owns-its-migrations-and-the-mesh-owns-when-they-run.md)  *(superseded)*
 - **0135** — [A module version prepares its state before it runs](0135-a-module-version-prepares-its-state-before-it-runs.md)
 - **0136** — [A step gates its module, not the machine](0136-a-step-gates-its-module-not-the-machine.md)
+- **0137** — [A machine says which networks it routes](0137-a-machine-says-which-networks-it-routes.md)
+- **0138** — [An assignment binds an endpoint and says how far it reaches](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)
+- **0139** — [A network is forwarded because a module declared it](0139-a-network-is-forwarded-because-a-module-declared-it.md)
 
 ### How it is built
 

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

@@ -7,8 +7,10 @@ code:
   - mesh-controller internal/identity/authority.go
   - mesh-host internal/identity/serving.go
   - mesh-host internal/apply (the service that reflects a rule set)
-updated: 2026-09-27
+updated: 2026-09-28
 decisions:
+  - 02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md
+  - 02-DECISIONS/0139-a-network-is-forwarded-because-a-module-declared-it.md
   - 02-DECISIONS/0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md
   - 02-DECISIONS/0106-the-bus-is-nats.md
   - 02-DECISIONS/0105-the-mesh-adopts-the-predecessors-tunnel-in-place.md
@@ -625,6 +627,42 @@ the found firewall reloads and reachable from a container on the node, that a ma
 enrols through the openings before and after a reload and a reboot, and that after the flip the
 declared port is open and the undeclared one closed.
 
+### The networks it forwards are the ones its modules declared
+
+*2026-09-28, preparing the control-node's convergence —
+[issue 141](../../04-ISSUES/141-the-forward-chain-does-not-follow-the-modules/00-report.md), settled by
+[ADR 0139](../../02-DECISIONS/0139-a-network-is-forwarded-because-a-module-declared-it.md).*
+
+The forward chain denies by default, so a machine's own guests have to be allowed back in. Until now
+that was two ranges named in the control plane and, since
+[ADR 0137](../../02-DECISIONS/0137-a-machine-says-which-networks-it-routes.md), a list a machine could
+add to. On the machine measured here, six of its container networks fell outside those ranges — and
+four of the six were networks the mesh's own modules had declared and the host had created, while two
+were the predecessor's leftovers. A range wide enough to keep the four keeps the two: a filter widened
+by hand to protect what should not be there.
+
+**A network is forwarded because a module declared it.** The forward chain forwards the networks of the
+modules assigned to that node and, by default, nothing else; a module unassigned stops being forwarded
+at the next reconcile. The control plane says which networks, by name, and the host — which created
+them — renders their addresses, because the runtime allocates the subnet and the host is what knows it.
+That keeps §4's shape and this document's: the mesh decides, the host applies.
+
+**This is derivation from the declaration, not from the machine.** 0137 rejected reading the machine,
+for two reasons that do not apply here: a network created between two declarations is already named in
+the one that asked for it, and a network nobody declared is never forwarded however it appeared. What
+0137's mechanism keeps is the case it was right for — guests no module declares, a test bed's range —
+added to the derived set and never replacing it.
+
+The runtime's own default bridge, which a container attaches to when it names no module network, is the
+runtime's and not a module's, so the host renders it from what the runtime reports. With that, no range
+is named in the control plane at all.
+
+*How it is checked:* a node with two modules declaring networks renders rules for exactly those two and
+none for a third present on the machine that nothing declared — which fails against forwarding by
+range, and is how it was written; unassigning one removes its rule at the next reconcile; the default
+bridge is asserted for a runtime whose bridge is somewhere other than the old constant named; and the
+guests of a declared network keep address and name service, per chain body.
+
 ## 5 — Certificates
 
 **Two authorities, kept separate on purpose.**
@@ -710,6 +748,60 @@ that verifies against the internal root and nothing else — which cannot succee
 first reached the name to certify it*
 ([ADR 0066](../../02-DECISIONS/0066-public-routing-is-name-agnostic.md)).
 
+## 6 — One statement behind exposure, filtering and certificates
+
+*2026-09-28, preparing the control-node's convergence —
+[issue 140](../../04-ISSUES/140-an-endpoints-reach-is-not-declared/00-report.md), settled by
+[ADR 0138](../../02-DECISIONS/0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md).*
+
+The three sections above each decide, independently, how far a service reaches. §3 composes a name
+from a label and the node's domain. §4 opens a port to the source a listen named. §5 certifies the
+names that exist, from whichever authority the proxy holds. Each is coherent on its own, and together
+they mean **reachability is never stated anywhere** — it is the sum of three derivations, and a sum is
+not something anyone can review or refuse.
+
+What that costs, measured: an identity provider holding a public certificate valid 90 days and an
+internal one valid 24 hours, neither asked for by any assignment, because both names existed and a
+proxy certifies what it serves. And an endpoint that is not routed — git over ssh — which can be
+spoken about only in the filter's vocabulary, so *this must be reachable from outside* is a setting
+exactly one mechanism reads.
+
+**An endpoint is the thing that was missing.** A module declares named endpoints: one port it serves,
+what it is for, and what it would serve that to absent any instruction. A route contribution names an
+endpoint rather than repeating a port number. An assignment — which is where a module's configuration
+lives ([ADR 0046](../../02-DECISIONS/0046-a-module-configuration-is-its-assignments-not-its-manifest.md))
+— then binds each endpoint to a machine port and says how far it reaches.
+
+One value, three readers:
+
+| reach | the filter opens | the proxy serves | the certificate comes from |
+|---|---|---|---|
+| `internal` | the machine port, to the private network | the internal name | the mesh's own authority |
+| `public` | the machine port, to anywhere | the public name | the public authority |
+| `both` | the machine port, to anywhere | both names | each name's own authority |
+
+**An endpoint that is not routed is reached and never named.** No route contribution means no name is
+composed and no certificate requested, while the filter still acts on it. That is the case the model
+could not express at all, and it is the ordinary case for anything that is not HTTP.
+
+**Nothing moves until an assignment says so.** An endpoint whose assignment is silent keeps the
+default its manifest states, so every machine already converged renders exactly as it does today —
+the same property §4 needed when a machine gained a way to say which networks it routes.
+
+This is what the certificate questions were waiting for. Which authority signs a name, whether a name
+may appear in a public issuance log, and what must be trusted where are all answerable once an
+endpoint says whether it is internal — and unanswerable while the proxy decides by composing every
+name it can. It is also the fact
+[issue 139](../../04-ISSUES/139-an-internal-route-name-resolves-to-the-consumers-node/00-report.md)
+needs: an internal name should be composed from the machine serving the endpoint, which is the
+assignment that bound it.
+
+**How it is checked** is stated with the decision: one module with two endpoints of differing reach
+asserted per chain body; the names and the certificate requests following the reach and failing
+against today's behaviour, where both are always composed; an unrouted endpoint filtered and never
+named; an assignment naming an endpoint the module does not declare refused where it is said; and a
+silent assignment rendering byte-identically to today.
+
 ## What this removes
 
 The list is worth having in one place, because it is most of the argument:

03-DESIGN/01-to-be/32-what-a-module-declares.md

@@ -1,11 +1,20 @@
 ---
 layer: to-be
-status: proposed
-code: []
+status: in-progress
+code:
+  - mesh-controller internal/catalogue/declaration.go
+  - mesh-controller internal/catalogue/manifest.go
+  - mesh-controller internal/link/serve.go
+  - mesh-controller internal/link/bus.go
+  - mesh-controller internal/broker/nats.go
+  - mesh-controller internal/inventory/nodes.go
+  - mesh-host internal/apply/apply.go
+  - mesh-tools src/main.ts
+  - mesh-catalog modules/mesh-catalog
 updated: 2026-09-28
 decisions:
   - 02-DECISIONS/0126-a-module-declares-its-own-seats.md
-  - 02-DECISIONS/0127-amqp-is-a-provision-not-the-bus.md
+  - 02-DECISIONS/0131-everything-on-the-mesh-speaks-to-the-broker-seat.md
   - 02-DECISIONS/0128-the-mesh-bus-is-required-not-ambient.md
   - 02-DECISIONS/0106-the-bus-is-nats.md
   - 02-DECISIONS/0041-events-are-a-relationship.md
@@ -261,8 +270,8 @@ queue.
 and publishes it last-per-subject. A node that was away gets exactly the current one, never a
 queue of superseded ones, and a replayed older one is refused by sequence.
 
-**A version prepares its state before it runs.** A module version may declare an entrypoint that brings
-its state to the shape that version needs — the same vocabulary as the entrypoints it declares for its
+**A version prepares its state before it runs.** *Built 2026-09-28.* A module version may declare an
+entrypoint that brings its state to the shape that version needs — the same vocabulary as the entrypoints it declares for its
 tools and its provisioner, and nothing about how a machine runs it. The mesh runs that entrypoint as it
 runs the module's own code, to completion, in the module's own context, and a version whose preparation
 did not succeed does not run: the step gates that module and nothing else on the machine
@@ -277,7 +286,7 @@ mesh provisions is per consumer and preparation is too. No level to choose, and
 not to an address it was given at genesis. Held and retried while the store restarts
 ([ADR 0083](../../02-DECISIONS/0083-one-push-leaves-the-mesh-consistent.md)).
 
-**And the mesh says what it applied.** A report is control traffic only the control plane reads, so the
+**And the mesh says what it applied.** *Built 2026-09-28.* A report is control traffic only the control plane reads, so the
 chain above went dark at the moment it touched a machine: nothing said which version a machine now runs,
 or that it refused to. The control plane states those as facts under its own seat's namespace, when what
 a machine runs changes rather than on every convergence pass, and anything that cares subscribes the way

04-ISSUES/134-a-definition-may-still-name-the-mesh/00-report.md

@@ -0,0 +1,66 @@
+---
+status: open
+opened: 2026-09-28
+located-in: [mesh-catalog, mesh-controller internal/catalogue]
+fixed-by:
+amended-design:
+---
+
+# 134 — A definition may still name the mesh, and the check that would say so does not exist
+
+## What was observed
+
+[ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md) says a module
+definition names no node, no mesh and no host path, and states how that is checked:
+
+> A catalogue test finds no domain name in any definition value.
+
+There is no such test. Run by hand on 2026-09-28, across the 72 manifests in the catalogue, the
+question it asks has 15 answers. They are not all the same kind of thing, and the difference matters
+more than the count:
+
+**Values the mesh acts on** — seven:
+
+| module | where | what it names |
+|---|---|---|
+| keycloak | `env.KC_HOSTNAME` | this installation's public name for itself |
+| minio | `env.MINIO_BROWSER_REDIRECT_URL` | the same, for its console |
+| invoicing | a resource's `image` | a named registry rather than the mesh's artifact store |
+| builder | `build.artifacts[].context.repository` | the forge, by URL |
+| route-proxy | `build.artifacts[].context.repository` | the forge, by URL |
+| route-adapter | a resource's `content` | a proxy's dynamic configuration |
+| novox.be | `module` | the module is named after the domain it serves |
+
+**Prose** — eight, in `listens[].why`: de-spiegel, mailu, n8n, only-office, photos, photos-eef,
+photos-filip, portainer. Each explains what a port is for and mentions the public name it is reached
+by. Nothing reads these; a check written as a string search would report them, and reporting them as
+violations of the same rule would be wrong.
+
+## Why it matters beyond this instance
+
+**An unenforced rule is indistinguishable from a wrong one, and costs more, because people believe
+it.** The record says the mesh is name-agnostic, four design documents rest on that, and a reader
+checking whether it holds finds that it does not — in the places that matter most. The two forge URLs
+are what a build reaches into for its source; the two hostnames are what a service tells a browser
+about itself.
+
+**It is the difference between a mesh and this mesh.** A definition carrying `novox.be` is a
+definition that can only be installed here. The whole point of the rule is that the same catalogue
+raises a different mesh with a different name, and today seven modules would need editing to do it.
+
+**And the shape of the fix is not the same for each.** A public name is an operator's choice about an
+assignment, which ADR 0112 already provides for; a forge URL should be a path on the git seat
+([ADR 0111](../../02-DECISIONS/0111-a-build-source-is-on-the-git-seat-or-external.md)); an image from a named
+registry is a question about the artifact store, not about naming. Counting them together would hide
+that.
+
+## Open questions
+
+- Does a domain in a `why` string break the rule? It is documentation the mesh never reads, and a
+  check that cannot tell the two apart will either pass things it should catch or fail things nobody
+  should change.
+- Where does a service's public name live, concretely — a setting on the assignment, or a fact the
+  mesh composes from the node's domain? ADR 0112 says a requirement the mesh resolves; the two
+  hostnames above are the first real cases.
+- Should a build context name a repository on the git seat rather than by URL, and if so, what does
+  that mean for a context in *another* mesh's forge?

04-ISSUES/135-a-containers-mesh-names-are-not-compared/00-report.md

@@ -0,0 +1,70 @@
+---
+status: resolved
+opened: 2026-09-28
+located-in: [mesh-host internal/apply]
+fixed-by: mesh-host — a container's mesh names are part of the spec digest the host compares, sorted so the digest does not move for a reordering. A container whose names moved is now recreated like a container whose image moved, and the test fails against the previous behaviour.
+amended-design:
+---
+
+# 135 — A container's mesh names are not compared, so a moved address is never noticed
+
+## What was observed
+
+One container on this mesh had been restarting every thirty seconds for five days — 2286 times — and
+the mesh reported the machine as doing what it was told.
+
+Its logs said its database connected and then a query timed out. The database was reachable: the same
+query from the same network, with the same credential, answered in milliseconds. What differed was the
+name. Inside that container, `novox.internal` resolved to `10.42.0.1`; in every other container on the
+machine it resolved to `10.10.0.1`. The mesh's overlay range had moved, and this container still held
+the old one:
+
+```
+umami          created 2026-09-23   novox.internal:10.42.0.1
+mesh-catalog   created today        novox.internal:10.10.0.1
+```
+
+A container resolves other machines and public names through the entries the mesh gives it when it is
+created, and nothing re-reads them afterwards. The host compares a container against what was declared
+by a digest of its spec — image, name, environment, ports, volumes, arguments, resolver, address, and
+what it reads — and **the mesh's names were not in it**. So this container matched what was declared,
+was left alone, and kept an address that had not existed for five days.
+
+Forty-eight other containers had current names. Not because anything corrected them: each had been
+recreated for some other reason — a new image, a changed file — and picked up the current roster on the
+way. This one's image is an upstream release that had not moved, and nothing else about it changed, so
+nothing ever recreated it.
+
+## Why it matters beyond this instance
+
+**It is the exact fault [issue 045](../045-a-container-keeps-the-values-it-started-with/00-report.md)
+named, in the one field that was left out.** That issue is why the digest carries what a container
+reads: "a container whose configuration had since been rewritten compared equal and was left alone —
+running values the machine no longer holds, while every check reported success." The same sentence
+describes this, with *names* in place of *files*.
+
+**The failure is invisible in exactly the way that matters.** The container runs, so the machine
+reports it applied. It restarts, but a restarting container is a normal sight during an upgrade. The
+only account of the fault is inside the container's own log, in the words of the application rather
+than of the mesh — and what it says is that a query timed out, which points at the database.
+
+**And it is most likely to bite what changes least.** Every container that is rebuilt often repairs
+itself by accident. The victim is the module whose image is stable — which is to say, the module that
+was working fine.
+
+## What was done
+
+The mesh's names are part of the digest, sorted so the digest does not move for a reordering nobody
+made. A container whose names moved is now recreated exactly as one whose image moved.
+
+The first apply after this recreates every container that carries mesh names — one restart each,
+already the price the mesh pays for any image update — because their recorded digests predate the
+field.
+
+## What is still true
+
+The mesh gives a container its names at creation and has no way to change them in place. That is the
+container runtime's shape, not a choice; the answer is to recreate, which is what this does. A module
+that would rather re-read a roster from a file can already ask for one as a fact
+([ADR 0120](../../02-DECISIONS/0120-a-roster-fact-carries-its-format-as-a-template.md)) and restart on
+it.

04-ISSUES/136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md

@@ -0,0 +1,92 @@
+---
+status: resolved
+opened: 2026-09-28
+located-in: [mesh-catalog modules/fail2ban]
+fixed-by: mesh-catalog — the intrusion-prevention module bans through an action it ships itself, already in use on every machine, instead of naming a firewall front-end two of them do not have. The instance is closed; the class in "What is still true" is not.
+amended-design:
+---
+
+# 136 — A module may name a program the machine does not have, and everything reports success
+
+## What was observed
+
+Two machines were given the intrusion-prevention module on 2026-09-28. Both refused to start it:
+
+```
+ERROR Failed during configuration: Have not found any log file for 'recidive' jail.
+ERROR Async configuration of server failed
+fail2ban.service: Main process exited, code=exited, status=255/EXCEPTION
+```
+
+The jail that bans whoever keeps coming back reads the service's *own* log, and the service checks
+every jail's log file while it configures itself — before it has created that log. The module
+declared the jail and shipped the rotation for that log, and never declared the log. On the two
+machines where it had run for years the file was simply there, so nothing had ever noticed.
+
+That failure was loud. Fixing it uncovered a second one in the same module that is not.
+
+The module's defaults named `ufw` as the way to ban an address. Two of these four machines have no
+`ufw` — they filter with nftables — and nothing checks that until an address is banned. Asked to ban
+a documentation address on such a machine, the service accepted the instruction, counted it, ran the
+command, and wrote this to a log nobody reads:
+
+```
+ERROR   ... -- stderr: '/bin/sh: line 5: ufw: command not found'
+ERROR   ... -- returned 127
+ERROR   Failed to execute ban jail 'sshd' action 'ufw' ... Error banning 192.0.2.99
+```
+
+No rule existed afterwards. Throughout, the unit was `active`, the module was applied, and the
+machine's report said so. **A machine had been added to the mesh's intrusion prevention, reported as
+protected, and was banning nobody.**
+
+## Why it matters beyond this instance
+
+**The two faults are the same mistake with opposite symptoms.** Both are the module assuming
+something about the machine — a file that happens to exist, a program that happens to be installed.
+One stopped the service, which anybody notices. The other left it running and empty, which nobody
+does. A mesh that only catches the loud one is a mesh whose coverage is unknown.
+
+**"The unit is running" was taken for "the module is doing its job".** That is the only health a
+service resource has. It is the right answer for most modules and it is silent for any module whose
+work happens later, on an event — a ban, a renewal, a backup, a notification. The report cannot
+distinguish "protecting this machine" from "installed and inert".
+
+**And it is exactly the naming rule, one level down.**
+[ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md) says a
+definition names no node, no mesh and no host path, because the same definition has to raise a
+different mesh. `ufw` is not a node name, but it is the same class of assumption: a value the module
+cannot know, true on some machines and false on others, written as though it were a constant. The
+module already knew how to do better a few lines away — the mesh's own address range is named there
+as something the machine fills in.
+
+## What was done
+
+The module declares the log its own jail reads, created once and never touched again, since what
+grows in it is the service's and the rotation the module already ships is what keeps it small. And
+it bans through the action it ships itself, which every machine here can run, which was already in
+use by the other jail on all four, and which covers a container's published port as well as the
+host's own.
+
+All four machines now run it, with both jails, and a ban lands on each — verified by banning and
+unbanning a documentation address on every one.
+
+## What is still true
+
+**Nothing would have caught either fault before it shipped.** The control plane reads a manifest, not
+a machine; `ufw` and `/var/log/…` are strings in a file it has no way to evaluate. The host could in
+principle be asked whether a declared program exists, but no resource says "this file names a command
+that must be there", so there is nothing to check.
+
+**Two machines' bans from before this are stale rules in the old front-end**, which the service no
+longer knows about and will never lift. They reject two addresses for ever. Harmless, and a reminder
+that changing how a module enforces something leaves what it already enforced behind.
+
+## Open questions
+
+- What does a service resource's health mean for a module whose work is event-driven? A unit being
+  active is the weakest claim available, and four of this mesh's modules are of that kind.
+- Should a declaration be able to say that a resource depends on a program, so the machine can refuse
+  what it cannot carry out rather than reporting success?
+- Where should the packet filter a module bans through come from — the module's own choice, as now,
+  or the seat that owns the machine's filtering?

04-ISSUES/137-converging-a-machine-cut-off-its-own-guests/00-report.md

@@ -0,0 +1,74 @@
+---
+status: resolved
+opened: 2026-09-28
+located-in: [mesh-controller internal/catalogue]
+fixed-by: mesh-controller — a machine says which networks it routes and the derived filter forwards them, their guests keeping address and name service ([ADR 0137](../../02-DECISIONS/0137-a-machine-says-which-networks-it-routes.md)).
+amended-design:
+---
+
+# 137 — Converging a machine cut off its own guests, and nothing said so
+
+## What was observed
+
+A workstation was flipped from adopted to converged, so the mesh's derived filter replaced what was
+there. The flip reported success, the machine reported that it had applied its declaration, and every
+surface of the mesh read green.
+
+A container on one of that machine's networks could no longer reach anything:
+
+```
+192.168.64.2/20
+OUTBOUND BLOCKED
+```
+
+Five of the machine's container networks were affected, and every network its test beds create. The
+reason is in the filter's forward chain, which denies by default and then allows two ranges:
+
+```
+ip saddr 172.16.0.0/12 accept   # the container runtime's bridge networks
+ip saddr 192.168.128.0/17 accept # the networks its compose files are given
+```
+
+Those two are constants in the controller. The machine's guests were allocated from neither: its
+compose networks from other parts of `192.168/16`, and each test bed a fresh `10.x/24`. So the rules
+were correct for a machine whose runtime was left at its defaults, and a guess on this one.
+
+Two further things were closed by the same flip, and for the same reason nobody saw them: a guest asks
+its host for an address over DHCP and for names over DNS, both of which arrive at the input chain,
+where no module had declared them.
+
+## Why it matters beyond this instance
+
+**The preview could not have warned.** It lists what the machine reported as *listening*, and says so
+honestly: it ends with a line that traffic the machine routes is "not previewed". What it did not say
+is that routing was about to be denied by default, or which ranges would survive. An operator reading
+a 350-line preview approves what it shows.
+
+**It is the second time today that a constant stood in for something the mesh cannot know.** The
+intrusion-prevention module named a firewall front-end two machines do not have
+([issue 136](../136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md)), and the
+filter names the address ranges one runtime happens to use. Both were true where they were written and
+silently false elsewhere.
+
+**And the code already knew.** The comment above those two lines says a machine configured otherwise
+"needs this to say so — which is a thing the mesh cannot derive and a reason this list is named here
+rather than computed". The gap was documented at the point where it was introduced, and the way to say
+it was never built. A comment naming a missing mechanism is a rule that is not enforced.
+
+## What was done
+
+A machine says which networks it routes; the filter forwards them and admits their guests' address and
+name service. Added to the runtime's defaults rather than replacing them, so a machine that names one
+range keeps the others. Node-level, because the machine routes them and the module that loads the
+filter may be replaced. The converge preview now says what a machine routes, and what it will keep
+forwarding if it says nothing.
+
+## What is still true
+
+**The flip is still the moment a machine's unmanaged services close.** That is what converging means
+and the preview names each one. This issue is not about the ports that were meant to close; it is about
+the ones nothing could name.
+
+**Egress is still not previewed per network.** The preview says which ranges will be forwarded, not
+which of the machine's guests sit inside them. Deriving that would need the machine to report its
+bridges, and a bed's bridge does not exist until the bed runs.

04-ISSUES/138-two-modules-claim-one-seat-and-are-not-interchangeable/00-report.md

@@ -0,0 +1,56 @@
+---
+status: open
+opened: 2026-09-28
+located-in: [mesh-controller internal/catalogue, mesh-catalog]
+fixed-by:
+amended-design:
+---
+
+# 138 — Two modules claim one seat and are not interchangeable, and nothing says so
+
+## What was observed
+
+Three modules claim the node-scoped uplink seat: one for each network manager a machine here might
+run. [ADR 0117](../../02-DECISIONS/0117-a-machines-uplink-is-a-seat.md) gives each of them the same
+job — ask the manager the machine already runs to leave the resolver file alone and to leave the mesh's
+interface alone — and deliberately keeps the machine's own links out of the mesh's hands.
+
+A seat means one holder and an interchangeable holder. These are interchangeable in what they *ask*
+and not in what they *do*:
+
+- None installs, enables, starts or stops the manager. That is on purpose: stopping it takes every
+  link down, including the mesh's own way in.
+- None carries an address, a route or a wireless credential, for the same reason.
+- **Nothing checks that the module holding the seat names the manager the machine is actually
+  running.** Assigning the systemd-networkd holder to a machine running NetworkManager writes a file
+  for a daemon that is inactive and disabled, the seat reports held, and the two things the seat
+  exists to arrange are arranged for nobody. NetworkManager goes back to rewriting the resolver file
+  on every lease, which is the failure the module's own comment describes.
+
+The machine reports which service manager and which units are active, so the fact needed to catch this
+is already in the report the mesh holds.
+
+## Why it matters beyond this instance
+
+**A seat is the mesh's promise that a role is filled.** If the holder can be a module for software
+that is not running, the seat says a role is filled while nothing fills it — and the surface that
+would tell an operator says "held".
+
+**It is the same shape as two faults found the same day.** A module named a firewall front-end the
+machine does not have ([issue 136](../136-a-module-may-name-a-program-the-machine-does-not-have/00-report.md)),
+and the filter named address ranges one runtime happens to use
+([issue 137](../137-converging-a-machine-cut-off-its-own-guests/00-report.md)). Each is a claim about
+the machine that nothing on the machine checks.
+
+**And it decides whether the seat is worth having.** Either the holder must match what the machine
+runs, which is a condition the mesh can check from the report it already has, or the holders must be
+able to switch the manager, which ADR 0117 refuses for a reason that has not changed.
+
+## Open questions
+
+- Should a seat's conditions of holding include a capability the machine reports, so a holder naming
+  absent or inactive software is refused rather than recorded?
+- Is "the uplink" one seat at all, if its holders are three dialects of the same two requests? The
+  alternative is one module that speaks whichever dialect the machine needs, chosen from the report.
+- What should happen on a machine that switches manager afterwards? The seat would then be held by the
+  wrong module, and the machine is the only place that knows.

04-ISSUES/139-an-internal-route-name-resolves-to-the-consumers-node/00-report.md

@@ -0,0 +1,51 @@
+---
+status: open
+opened: 2026-09-28
+located-in: [mesh-controller internal/catalogue]
+fixed-by:
+amended-design:
+---
+
+# 139 — An internal route name resolves to the consumer's node, not the one that serves it
+
+## What was observed
+
+A module that requires a route is given two names: a public one composed under the serving node's
+domain, and an internal one composed under the consumer's own machine — `<label>.<node>.internal`.
+
+The two are published differently:
+
+- The **public** name is written into every machine's hosts file at the address of the node whose
+  proxy answers it. The mesh computes that deliberately, so any container resolving a routed name
+  reaches the proxy.
+- The **internal** name is resolved by the machine's own resolver, which answers every name under
+  `<node>.internal` with that node's address — the consumer's, because the name was composed from it.
+
+Where the proxy runs beside the consumer these are the same machine, which is every case on this mesh
+today, and both names work. Measured on 2026-09-28: the internal name of a service on the control node
+answers with a certificate from the mesh's internal authority, and the public name with one from the
+public authority.
+
+Where the proxy is on another machine they disagree. The internal name sends the client to a machine
+that runs no proxy and has nothing listening on the port, while the public name sends it to the one
+that does.
+
+## Why it matters beyond this instance
+
+**It is latent exactly where the mesh is heading.** `route` is provided mesh-wide precisely so a
+module can be routed by a proxy on another machine. The first module assigned that way gets an
+internal name that does not work, and the public one that does — with no error anywhere, because both
+names resolve.
+
+**A per-machine name is what an operator will reach for.** `<service>.<machine>.internal` reads like a
+promise that the service on that machine is reachable there, and the wildcard makes every such name
+resolve whether or not anything answers.
+
+## Open questions
+
+- Should the internal name be composed under the serving node, like the public one, or should it stay
+  the consumer's and be published at the serving node's address like the public name is?
+- Is a per-node route holder the real answer — a proxy on every machine that serves its own names —
+  and if so, is `route` still one mesh-wide provision or a node-scoped seat with a mesh-wide fallback?
+- What certifies the name in either case? The certificate is obtained by whoever terminates TLS, and
+  that is the question above in another form.

04-ISSUES/140-an-endpoints-reach-is-not-declared/00-report.md

@@ -0,0 +1,79 @@
+---
+status: located
+opened: 2026-09-28
+located-in:
+  - mesh-controller internal/catalogue/manifest.go
+  - mesh-controller internal/catalogue/filtering.go
+  - mesh-controller internal/catalogue/declaration.go
+  - mesh-controller examples/route-proxy
+  - mesh-catalog (every routed module manifest)
+fixed-by:
+amended-design: 03-DESIGN/01-to-be/08-connectivity.md
+---
+
+# 140 — An endpoint's reach is not declared, so three mechanisms each decide it separately
+
+## What was observed
+
+Preparing to converge the mesh's control-node — the last machine still running the firewall it
+had before the mesh — the question came up for one module: the forge serves git over ssh, and that
+port must stay reachable from outside the private network. Where is that said?
+
+The manifest declares the port with a source of `mesh`, so the derived filter would close it to
+everything but the private network. Looking for the place an assignment says otherwise, there are
+two per-node settings keys: one that gives a module's declared port a machine port, and one that
+overrides a declared port's source. The second has exactly one caller — the function that builds
+the node's filter rules. Nothing else in the control plane reads it.
+
+A module's routed endpoint is declared somewhere else entirely: a route contribution naming a label
+and a port. It says nothing about reach. The proxy composes a **public** name and an **internal**
+name for every route it is given, and obtains a certificate for each from a different authority.
+Measured on that machine the same day: an identity provider's public name signed by the public
+authority for 90 days, its internal name signed by the mesh's own intermediate for 24 hours and
+renewed daily. Both names exist, and both certificates, because the proxy makes every name it can.
+No assignment asked for either.
+
+So the forge's ssh endpoint has a firewall source and nothing else — no name, no certificate, and no
+way to say it should be public other than a key the filter alone reads. And the forge's web endpoint
+has two names and two certificates that nobody requested.
+
+## Why it matters beyond this instance
+
+**Reach is stated twice, in two vocabularies, in two places that cannot disagree out loud.** A port
+may be exposed to anywhere while the module contributes no public route; a public route may be served
+for a module whose own listen is private. Nothing reconciles the pair or refuses it. Each mechanism
+is separately defensible and the combination is unstated.
+
+**The vocabulary belongs to the filter, not to reachability.** *Public, internal, or both* cannot be
+expressed. A source of `anywhere` is one rule on one chain; it says nothing about which names should
+exist or which authority should sign them. So "this endpoint must not be public" has no way to be
+written, and is therefore enforced by nothing — while a public certificate for that very name is
+obtained automatically.
+
+**An endpoint is not a thing in the model.** A module has ports, and separately it has routes.
+Nothing binds a port to a name to a certificate, which is why three mechanisms each decide reach on
+their own and none of them is wrong. This is
+[ADR 0045](../../02-DECISIONS/0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md)'s fault
+one level up: that record closed "a declaration that reads as a restriction and restricts nothing"
+for the packet filter. Here the declaration is absent altogether and the mechanisms guess.
+
+**It blocks the certificate work.** The open question recorded for certificates — a name that must
+not be public needs either DNS-01 or the internal authority only — cannot be answered while no
+assignment states whether a name should be public. Neither can expiry reporting, revocation, or what
+happens to a name when a machine leaves: all of them need to know which names were *meant*.
+
+## Open questions
+
+- Should an assignment name each of a module's endpoints, bind it to a node-level port, and state
+  whether it is reachable publicly, internally or both — with the filter, the proxy's names and the
+  certificate authority all derived from that one statement?
+- What is an endpoint that is neither routed nor certified? Git over ssh is public reach with no name
+  and no certificate; the model has to hold that without inventing one.
+- Are the two existing settings keys the same statement, half-built? If so, is this a new declaration
+  or the completion of theirs?
+- Does an internal-only endpoint get a certificate at all, and from which authority — and does that
+  settle [issue 129](../129-nothing-makes-a-machine-trust-the-meshs-authority/00-report.md), where nothing
+  installs the mesh's own root?
+- Does declaring reach per assignment also settle
+  [issue 139](../139-an-internal-route-name-resolves-to-the-consumers-node/00-report.md), where an
+  internal name resolves to the consumer's machine instead of the one serving the endpoint?

04-ISSUES/141-the-forward-chain-does-not-follow-the-modules/00-report.md

@@ -0,0 +1,76 @@
+---
+status: located
+opened: 2026-09-28
+located-in:
+  - mesh-controller internal/catalogue/filtering.go
+  - mesh-host internal/apply
+fixed-by:
+amended-design: 03-DESIGN/01-to-be/08-connectivity.md
+---
+
+# 141 — The forward chain does not follow the modules, though the modules declare their networks
+
+## What was observed
+
+[ADR 0137](../../02-DECISIONS/0137-a-machine-says-which-networks-it-routes.md), decided the same
+week, gave a machine a way to say which networks it routes for its guests, because the derived
+filter's forward chain had until then allowed two ranges named as constants in the control plane's
+own source — the container runtime's default bridge pool, and half of the pool its compose files
+are given.
+
+Checking the last machine still to be converged, the same fault was found to be live there, and the
+declaration needed to work around it turned out to be wrong in kind.
+
+That machine hosts twenty-one container networks. Nine fall inside the runtime's bridge pool and
+are forwarded. Twelve sit in the other private range, and **six of those fall below the lower bound
+of the constant**, so the flip would have cut their guests off exactly as it did on the workstation
+that produced 0137.
+
+Naming a range to cover the six was the obvious move, and is what 0137 provides for. But of those
+six networks, **four are networks the mesh's own modules declare** — they appear as network
+resources in the node's plan, created by the host because a module asked for them — and **two are
+leftovers of the predecessor**, compose networks of services the mesh does not run. A range wide
+enough to keep the four would have forwarded the two as well: a firewall widened by hand to protect
+networks that should not exist.
+
+The mesh already knows which of the twenty-one are its own. It made them.
+
+## Why it matters beyond this instance
+
+**The node's configuration is supposed to follow the modules assigned to it.** That is the mesh's
+founding shape — the machine runs modules, and its files, its filter and its accounts are composed
+from what runs there. The forward chain is the one derived thing that does not: it consults two
+constants and, since 0137, a list a person types. A module added tomorrow brings a network the filter
+will not forward; a module deprecated leaves a range in the list that outlives it.
+
+**A typed range cannot distinguish the mesh's networks from what was left behind.** It is stated in
+addresses, and addresses are what the runtime allocates, so the only honest declaration is one wide
+enough to include whatever else the runtime has handed out. The derivation is narrower than anything
+a person can safely write, because it names networks rather than ranges.
+
+**0137 rejected deriving this, and was right about what it rejected.** It considered deriving the
+list from *what the machine reports* and refused, on two grounds: a test bed creates its bridge
+between one declaration and the next, and a filter that follows whatever appeared on the machine is a
+firewall that widens itself. Deriving from the **declaration** is neither. The set is known before
+the network exists, because a module declared it; and it cannot widen itself, because only a network
+some module asked for is ever forwarded. What remains genuinely for a machine to say is guests no
+module declares — a test bed's pool — which is a much smaller residue than the list as it stands.
+
+**The gap is invisible in the one place that should show it.** The converge preview lists what
+*listens*, and routing is not a listener. It says in one line what the machine routes, and a reader
+has to know the runtime's allocations to tell whether that line is sufficient. On the machine
+measured here it read as though nothing needed saying.
+
+## Open questions
+
+- Should the forward chain be derived from the network resources the node's modules declare, with the
+  host resolving each declared network to its address the way it already resolves a container by name?
+  The controller cannot render the address itself: a module's network resource carries a name, and the
+  runtime allocates the subnet at creation.
+- What remains of `node networks` once that exists — only guests no module declares, such as a test
+  bed's pool? And should it then be named for that, rather than for all routing?
+- The runtime's own default bridge, which containers attach to when no module network is named, is
+  not a module's network. Is it derived from the machine, declared by the module that owns the
+  runtime, or left as the one constant?
+- Should the preview say which of a machine's networks are the mesh's and which are not, so a range
+  that exists to protect a leftover is visible as such?