---
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