Merge pull request 'ADR 0163: taking a module over is a comparison (group 6)' (#266) from decision/0163-taking-a-module-over-is-a-comparison into main

02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md

@@ -0,0 +1,138 @@
+---
+topic: the mesh
+status: accepted
+date: 2026-10-01
+deciders: jochen
+reconstructed: false
+extends: 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
+---
+
+# 163. Taking a module over is a comparison: what it compares, what it refuses, and what it carries
+
+## Context
+
+On an adopted machine the mesh holds what it finds until the module is taken, and taking is the
+cutover ([ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md)). The whole-node flip
+is previewed and confirmed by digest; the per-module cutover, the step that actually replaces a
+running service, previews nothing. `take` names the held things the next push will replace and
+where each original is kept. It does not say how the module's version of each differs from what
+runs. Ten issues from the first migrations are the same omission seen from ten sides:
+
+- a port narrowed from everywhere to the private network, unannounced ([086](../04-ISSUES/086-taking-a-module-narrows-a-port-without-saying-so/00-report.md));
+- a configuration file replaced whole, dropping the one line that was the installation's own ([098](../04-ISSUES/098-taking-a-module-replaces-a-configuration-nobody-compared/00-report.md));
+- an image pin that had aged into a downgrade, discovered by three minutes of outage ([099](../04-ISSUES/099-a-modules-image-pin-ages-into-a-downgrade/00-report.md));
+- a secret minted for a service that already had one, with no way to carry the existing value in because it was a required secret and not the module's own ([100](../04-ISSUES/100-a-minted-secret-cannot-be-the-one-the-service-already-uses/00-report.md));
+- a container moved onto the module's own network, out of reach of the neighbour that called it by name ([101](../04-ISSUES/101-taking-a-service-reached-by-container-name-cuts-its-neighbours-off/00-report.md));
+- a resource whose target changed, leaving the old container running with no record naming it ([097](../04-ISSUES/097-a-resource-that-changes-target-leaves-the-old-one-behind/00-report.md));
+- a volume path that changed without the running container noticing, because the host does not compare that field ([126](../04-ISSUES/126-a-volume-path-is-not-in-the-spec-comparison/00-report.md));
+- a build that deployed at once because the module's policy said so, racing a data move ([126](../04-ISSUES/126-a-volume-path-is-not-in-the-spec-comparison/00-report.md));
+- a setting accepted where it was set and refusing the whole machine where it was read ([096](../04-ISSUES/096-a-setting-that-cannot-work-is-stored-and-stops-the-node/00-report.md));
+- a module that could not take over what genesis raised, because the two differed in name, network, data and image ([090](../04-ISSUES/090-the-forge-module-does-not-take-over-the-forge-genesis-raised/00-report.md));
+- a successor that could not stand beside its predecessor at all, answered by [ADR 0104](0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md)'s adapter ([093](../04-ISSUES/093-the-successor-proxy-cannot-serve-what-the-predecessor-still-serves/00-report.md)).
+
+What the host records of a found thing is enough to compare from: a file's original, kept, with
+its digest, mode and owner; a container's id and whether it ran; whether anything changed it
+since. What it does not yet record is what a comparison needs most: the found container's image
+and when that image was made, the networks it is on and who else is on them, what it mounts, what
+it publishes. And the controller's rule that a machine is told everything or nothing turns one
+impossible statement into a machine nobody can talk to.
+
+## Decision
+
+**1. A take is previewed, and the preview is a comparison.** For every held thing the module would
+replace, `take` puts what runs beside what the module declares and says the difference:
+
+- a **container**: its image against the module's, with each image's creation date so older and
+  newer have a meaning; its name; its networks, and the other containers on each found network
+  that is not the module's; its published ports and the reach of each, found firewall and guard
+  included; its mounts against the module's volumes and paths;
+- a **file**: the kept original against the declared content, as a difference, not two digests;
+- a **secret** the module takes that the mesh minted and nobody accepted, when the service's data
+  was found — a service that already runs already has a value;
+- the module's **settings** on that machine, composed against its definition.
+
+`take` without `--yes` prints the comparison and stops; `take --yes <digest>` cuts over exactly
+what was previewed, the way the flip is confirmed, and a preview whose account of the machine is
+older than the flip allows is refused the same way. The host supplies the facts in its report of
+what it holds: the found container's image and its creation date, its networks and their members,
+its mounts and published ports.
+
+**2. Three differences refuse by default, each overridden by naming it.** An image **older** than
+the one running, by creation date — `--downgrade`, said once and recorded. A declared file that
+**differs** from the kept original — `--replace <path>`, or the module declares the file partially
+and writes into it ([ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md)), which is
+the right answer wherever the file is the service's own and the format allows it. A **minted,
+unaccepted secret** for a service whose data was found — accept the value first, or `--mint
+<name>` to say the service shall take a new one. Two differences are said and not refused: a port
+whose reach **narrows**, and a found network whose other members may reach the container **by
+name**, each member named; both are the operator's to weigh, and the words are there to weigh them.
+
+**3. A secret the mesh would mint may be accepted instead, own or required.** `secret accept`
+reaches a module's required secrets, not only its own: the value is a fact about the machine, and
+the mesh's job at a take is to learn it. The accepted value is sealed to the module as a minted one
+would be, and the provider that would have minted it is told it has one. Whether one accepted
+value should reach every consumer of a provider at once is [issue 165](../04-ISSUES/165-one-accepted-value-must-be-accepted-once-per-consumer/00-report.md)'s
+question and the next group's.
+
+**4. A taken container may keep a found network, for a while, by a setting.** A per-machine
+setting names a found network the module's container also joins, so a neighbour that resolves it
+by name keeps resolving it. It is migration scaffolding in the sense of
+[ADR 0104](0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md): assigned only on an
+adopted machine, reported while it stands, removed when the neighbours are taken, and the preview
+names it. Taking a group of modules at once is not decided here; the setting makes the order free.
+
+**5. The host compares every field it writes, and removes what it can no longer name.** A
+container is current when every field the host would write agrees with the one running — volumes
+and paths included; a field the host cannot compare recreates rather than passes. The host's
+record keeps a resource's former targets: a container or file the host **wrote** under a name or
+path the declaration no longer names is removed on the next apply and said; what was **found** is
+never removed, as ADR 0100 says. And the host answers the question nothing answered on
+2026-09-23: its report lists what runs on the machine that the mesh neither wrote nor holds —
+containers and listeners — as *strays*, so a thing left behind is seen the day it is left.
+
+**6. A setting is judged where it is stored, and an impossible one costs a module, not a machine.**
+Storing a setting composes it against the module's current definition and refuses with the node,
+module, layer and key when it cannot work. A definition that later moves under a stored setting
+makes composition leave *that module* out of the machine's declaration — its held things kept, its
+containers untouched — and say the statement by name; the machine is still told everything else.
+A machine is told everything or nothing about what it *is* told; what it is not told is said.
+
+**7. What genesis raises, it raises as the module that succeeds it declares** — name, network,
+data directory and image — so the module adopts it by the found rule that already exists, and a
+module meant to succeed a bootstrap service that it cannot adopt is a fault of genesis, found by a
+test that raises and then assigns. **`build` says when a policy will act on its result**, so a
+person choreographing a data move knows which module will not wait; under
+[ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md) the roll-out is the plan's, and
+the plan says it too.
+
+## Consequences
+
+- `take` becomes the per-module twin of the flip: preview, digest, confirm. The flip's own preview
+  gains the same comparisons for every module it takes.
+- The host's report of what it holds grows by the found container's image and creation date,
+  networks and members, mounts and published ports; its store keeps former targets and strays.
+- Issues 086, 098, 099, 100, 101 close on rule 1 and 2; 097 and 126 on rule 5; 096 on rule 6;
+  090 on rule 7; 093 is closed by ADR 0104's adapter, which runs.
+- Nothing here changes what an adopted machine keeps or when: found stays held, held is never
+  removed, the original is kept before anything is written.
+
+## How this is checked
+
+| Rule | Checked by |
+|---|---|
+| The host reports a found container's image and creation date, networks and their members, mounts and published ports | host unit tests over a fake runtime; the adoption bed's report |
+| `take` without `--yes` previews every held thing's difference and changes nothing; `--yes` with the digest cuts over; a stale account is refused | controller tests over a fixture report: a differing file, an older image, a narrowed port, a shared network, a minted secret |
+| An older image, a differing file and a minted secret for found data refuse without their override | the same tests |
+| A found network kept by a setting is joined, reported and named in the preview | a host test and a controller resolution test |
+| `secret accept` takes a required secret | an inventory test; the provider is told |
+| Every container field is compared; a former target the host wrote is removed and said; what was found is not | host tests: a volume path change recreates; a renamed container's predecessor is removed; a found one under the old name is kept |
+| Strays are reported | a host test over a fake runtime with a container nobody declared |
+| A setting that cannot compose is refused where stored, naming node, module, layer, key; a definition moving under one leaves that module out and says so | controller tests |
+| Genesis raises the forge as its module declares it | a genesis test that raises, assigns, and finds the module holding rather than raising a second |
+| Live | the next cutover on an adopted machine: `take` shows the comparison, refuses the downgrade if there is one, and the service keeps its configuration and its secret |
+
+## References
+
+- [ADR 0100](0100-a-node-in-use-is-adopted-before-it-is-converged.md), [ADR 0102](0102-the-mesh-writes-into-a-shared-file-never-over-it.md), [ADR 0103](0103-what-an-adopted-node-holds-and-what-its-guard-refuses.md), [ADR 0104](0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md), [ADR 0162](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
+- [Design 05 — The node host](../03-DESIGN/01-to-be/05-the-node-host.md), [Design 09 — The node lifecycle](../03-DESIGN/01-to-be/09-the-node-lifecycle.md)
+- Issues 086, 090, 093, 096, 097, 098, 099, 100, 101, 126

02-DECISIONS/README.md

@@ -176,6 +176,7 @@ python3 00-META/checks/index.py            fail if stale
 - **0160** — [The mesh issues an assignment's subjects, and a runtime serves what it is issued](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
 - **0161** — [What deserves a seat: a role of a module is a seat, a singular fact about machines is a placement with a capacity of one, and a holder's software is the machine's](0161-what-deserves-a-seat.md)
 - **0162** — [A merge produces a tiered plan the mesh keeps, and a module's dependencies are one relation in the catalogue](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
+- **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
 
 ### Its tiers, from the bottom up
 

03-DESIGN/01-to-be/05-the-node-host.md

@@ -2,8 +2,9 @@
 layer: to-be
 status: in-progress
 code: [mesh-host]
-updated: 2026-09-29
+updated: 2026-10-01
 decisions:
+  - 02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md
   - 02-DECISIONS/0141-the-host-delivers-its-own-successor.md
   - 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
   - 02-DECISIONS/0102-the-mesh-writes-into-a-shared-file-never-over-it.md
@@ -153,6 +154,15 @@ checked:* unit tests hold the host to keeping a found file and container, conver
 taken, never removing a held file and reporting one that changed; the adoption bed asserts a found
 file byte for byte unchanged until its module is taken.
 
+**What the host says of a found container, and what it removes** — revision, 2026-10-01
+([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md)). Its report of a held
+container carries the image and the image's creation date, the networks it is on and the other
+containers on each, its mounts and its published ports — the facts a take compares. The host compares
+every field it writes before calling a container current, volumes and paths included; its record keeps
+a resource's former targets, removes a container or file it wrote under a name the declaration no
+longer names, never removes what was found, and reports what runs on the machine that it neither
+wrote nor holds. *How it is checked:* ADR 0163's table.
+
 **Found reaches every kind that can touch what the machine has**
 ([ADR 0103](../../02-DECISIONS/0103-what-an-adopted-node-holds-and-what-its-guard-refuses.md)). For a module not yet taken, a directory present with no record
 keeps its mode and owner, a unit present with no record keeps its state and boot setting, a

03-DESIGN/01-to-be/09-the-node-lifecycle.md

@@ -8,8 +8,9 @@ code:
   - mesh-host packaging/nox-mesh-host-network.sh
   - mesh-controller internal/token
   - mesh-controller internal/inventory/nodes.go
-updated: 2026-09-23
+updated: 2026-10-01
 decisions:
+  - 02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md
   - 02-DECISIONS/0100-a-node-in-use-is-adopted-before-it-is-converged.md
   - 02-DECISIONS/0004-a-node-and-how-it-joins.md
   - 02-DECISIONS/0005-the-node-host.md
@@ -311,6 +312,17 @@ found firewall again and converges the openings through it; what was taken stays
 a predecessor leaves one and asserts nothing that serves changes until a module is taken or the
 node is converged, and that the flip closes exactly what the preview said.
 
+**Taking a module is previewed, and the preview is a comparison** — revision, 2026-10-01
+([ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md)). For every held thing a
+module would replace, `take` puts what runs beside what the module declares: a container's image and
+its age, name, networks and their other members, published ports and their reach, mounts; a file's
+kept original against the declared content, as a difference; a secret the mesh minted for a service
+that already has one; the module's settings composed against its definition. An older image, a
+differing file and a minted secret for found data refuse unless named; a narrowed port and a shared
+network are said. `take --yes <digest>` cuts over what was previewed, as the flip does. A taken
+container may keep a found network by a per-machine setting while its neighbours are not yet taken.
+*How it is checked:* ADR 0163's table.
+
 A candidate machine is not empty. It has a package manager, probably a container runtime,
 configuration somebody chose. [ADR 0005](../../02-DECISIONS/0005-the-node-host.md)
 says the host never touches what it did not create — adoption is the deliberate act of taking

04-ISSUES/086-taking-a-module-narrows-a-port-without-saying-so/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-22
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -35,3 +35,8 @@ it changes before it changes it, and for taking a module this one does not.
   included, and ask for the same kind of confirmation as the flip?
 - Or should taking refuse while a port of the module is reachable more widely than the module
   declares, until the operator either changes the module's exposure or confirms the narrowing?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 1 and 2: the preview names a narrowing. Building follows,
+host first, then the controller's `take`.

04-ISSUES/090-the-forge-module-does-not-take-over-the-forge-genesis-raised/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-22
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -48,3 +48,8 @@ network, or it is not a takeover.
   directory — so the module adopts it by the rule that already exists?
 - Should something refuse to call a module the successor of a bootstrap service it cannot adopt?
 - Is the forge's own address better resolved than set, which is [issue 088](../088-the-forges-own-address-names-a-port-it-may-not-have/00-report.md)?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rule 7: genesis raises as the module declares. Building follows,
+host first, then the controller's `take`.

04-ISSUES/093-the-successor-proxy-cannot-serve-what-the-predecessor-still-serves/00-report.md

@@ -1,8 +1,8 @@
 ---
-status: located
+status: resolved
 opened: 2026-09-22
 located-in: [mesh-catalog, mesh-controller internal/catalogue]
-fixed-by:
+fixed-by: ADR 0104 — the route adapter module (mesh-catalog modules/route-adapter) writes each migrated route into the predecessor's proxy; it runs on the home server's migration
 amended-design:
 ---
 
@@ -71,3 +71,10 @@ answered by an **adapter** that writes into the predecessor's own configuration.
 the predecessor's proxy keeps serving every name and keeps its certificates, while each migrated
 module's name is pointed at the mesh's container. The proxy is the last cutover again, and by then
 every route is one the mesh contributed.
+
+## Resolved, 2026-10-01
+
+The adapter ADR 0104 decided exists and runs: `route-adapter` provides `route` on an adopted
+machine by writing each migrated module's route where the predecessor's proxy reads it, and the
+proxy itself is the last cutover. [ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md)
+records the rest of what a take compares.

04-ISSUES/096-a-setting-that-cannot-work-is-stored-and-stops-the-node/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -58,3 +58,8 @@ knowing the code.
   an operator to undo it without reading the source?
 - Is there anything a node must never be pushed without, such that sending a partial declaration is
   worse than sending none?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rule 6: judged where stored; an impossible statement costs a module. Building follows,
+host first, then the controller's `take`.

04-ISSUES/097-a-resource-that-changes-target-leaves-the-old-one-behind/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -75,3 +75,8 @@ found, and so would be kept for ever on purpose.
   module unassigned between the two declarations?
 - What reports this? Nothing on the machine currently answers "what is running here that the mesh
   did not ask for", which is the question that would have found this in seconds.
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rule 5: former targets are removed and strays reported. Building follows,
+host first, then the controller's `take`.

04-ISSUES/098-taking-a-module-replaces-a-configuration-nobody-compared/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -63,3 +63,8 @@ written.
   substitutes settings into content today.
 - Is the kept original enough of an answer, given nothing restores it and nothing points at it
   when the service starts behaving differently?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 1 and 2: the difference is shown and a differing file refuses. Building follows,
+host first, then the controller's `take`.

04-ISSUES/099-a-modules-image-pin-ages-into-a-downgrade/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -60,3 +60,8 @@ expected rate.
   nothing answers the first.
 - Is a digest pin the right thing for a module that takes over an existing service at all, or
   should a cutover be able to say *keep what is running* and record what that was?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 1 and 2: the images are compared by age and a downgrade refuses. Building follows,
+host first, then the controller's `take`.

04-ISSUES/100-a-minted-secret-cannot-be-the-one-the-service-already-uses/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -65,3 +65,8 @@ the module can only be installed fresh.
   Should it, so the dangerous case can be refused rather than discovered?
 - What is the reverse path: the mesh has minted one, the service ignored it, and the working value
   is still on the machine. Nothing reconciles those.
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 2 and 3: a minted secret for found data refuses; secret accept reaches required secrets. Building follows,
+host first, then the controller's `take`.

04-ISSUES/101-taking-a-service-reached-by-container-name-cuts-its-neighbours-off/00-report.md

@@ -1,7 +1,7 @@
 ---
-status: open
+status: located
 opened: 2026-09-23
-located-in: []
+located-in: [mesh-controller cmd/mesh-controller/adoption.go (take previews nothing), mesh-host internal/apply (the comparison and the record)]
 fixed-by:
 amended-design:
 ---
@@ -61,3 +61,8 @@ exercise.
   learn to take a group atomically? Nothing takes more than one module at a time today.
 - Does the same hole exist for anything else the predecessor's runtime resolves and the mesh's does
   not — a network alias, a `depends_on`, a name in a shared `/etc/hosts`?
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 1 and 4: the neighbours are named; a found network may be kept by a setting. Building follows,
+host first, then the controller's `take`.

04-ISSUES/126-a-volume-path-is-not-in-the-spec-comparison/00-report.md

@@ -1,5 +1,5 @@
 ---
-status: open
+status: located
 opened: 2026-09-26
 located-in: [mesh-host internal/apply]
 ---
@@ -45,3 +45,8 @@ Instant renames both ways broke the circular dependency (forge needed for builds
 builds needed for the push, push needed for the forge): data back to the old path,
 old-spec forge started, artifacts rebuilt, data renamed forward, push. Nothing lost;
 the install-page junk was discarded twice.
+
+## Decided, 2026-10-01
+
+[ADR 0163](../../02-DECISIONS/0163-taking-a-module-over-is-a-comparison.md), rules 5 and 7: every field compared; build says the policy. Building follows,
+host first, then the controller's `take`.