ADR 0269: what the mesh's own declaration stopped is started again when it goes #238

Merged

mesh-admin merged 5 commits from decision/0269-what-the-meshs-own-declaration-stopped-is-started-again into main 2026-10-09 00:20:32 +00:00

Conversation 1 Commits 5 Files Changed 3

+127 -1

mesh-admin commented 2026-10-08 23:45:53 +00:00

Contributor

Copy Link

Copy Source

Accepted by the operator on 2026-10-09. This record narrows ADR 0118's rule "never started on the way out".

Why. The zfs module (mesh-catalog #147) owns the home server's scrub schedule. To leave exactly one schedule, it holds the distribution's zfs-scrub-weekly@<pool>.timer stopped and disabled. That timer had been enabled by hand, so the mesh found it running and enabled. Under ADR 0118 alone, unassigning the module would leave the timer stopped and disabled: the pool would have no scrub schedule, and nothing would say so.

Decision. The host records what the mesh declared for a service with a state. When that declaration goes:

• a unit found running and declared stopped is started again;
• a unit found enabled and declared disabled is enabled again.

This happens only while the unit is still exactly as the mesh held it. A masked unit, or one changed since, is left as it is, and the report says why. A restore that fails waits for the next apply and is never fatal.

Consequences.

• A unit that a person also stopped by hand while the mesh held it cannot be told apart, so it is started again on removal.
• A restored timer with Persistent=true catches up at once. On the home server that is a scrub of about 46 hours, if the timer's last run is more than a week back.

In this pull request:

• the record, status accepted;
• a dated "Narrowed, not replaced" note on ADR 0118;
• the node-engine's to-be design (03-DESIGN/01-to-be/05-the-node-host.md) names the decision and says what it changes.

Implementation: mesh-host #66. The records, index, cycle and words checks pass locally.

**Accepted** by the operator on 2026-10-09. This record narrows ADR 0118's rule "never started on the way out". **Why.** The `zfs` module (mesh-catalog #147) owns the home server's scrub schedule. To leave exactly one schedule, it holds the distribution's `zfs-scrub-weekly@<pool>.timer` stopped and disabled. That timer had been enabled by hand, so the mesh found it running and enabled. Under ADR 0118 alone, unassigning the module would leave the timer stopped and disabled: the pool would have no scrub schedule, and nothing would say so. **Decision.** The host records what the mesh declared for a service with a state. When that declaration goes: - a unit found running and declared stopped is started again; - a unit found enabled and declared disabled is enabled again. This happens only while the unit is still exactly as the mesh held it. A masked unit, or one changed since, is left as it is, and the report says why. A restore that fails waits for the next apply and is never fatal. **Consequences.** - A unit that a person also stopped by hand while the mesh held it cannot be told apart, so it is started again on removal. - A restored timer with `Persistent=true` catches up at once. On the home server that is a scrub of about 46 hours, if the timer's last run is more than a week back. **In this pull request:** - the record, status accepted; - a dated "Narrowed, not replaced" note on ADR 0118; - the node-engine's to-be design (`03-DESIGN/01-to-be/05-the-node-host.md`) names the decision and says what it changes. **Implementation:** mesh-host #66. The records, index, cycle and words checks pass locally.

mesh-admin added 1 commit 2026-10-08 23:45:53 +00:00

ADR 0269 (proposed): what the mesh's own declaration stopped is started again when it goes ... 68018c7c1b

Unassigning the zfs module would leave the home server's pool with no scrub schedule: ADR 0118 never
starts a unit on the way out, so the distribution's timer the module held stopped would stay stopped.
The host now records what it declared beside what it found, and gives back only what the mesh's own
declaration stopped.

mesh-admin commented 2026-10-08 23:45:58 +00:00

Author

Contributor

Copy Link

Copy Source

Delivery novox/hq@a11b14f7ae78 — delivered since 2026-10-09T00:20:37Z

Delivery plan — builds nothing: the change touches no module of the mesh's graph

Transitions

• 2026-10-09 00:17 (new) → proposed (announced): novox/hq#238's head announced
• 2026-10-09 00:18 proposed → checked (checked): the verdict names this commit
• 2026-10-09 00:18 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
• 2026-10-09 00:20 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
• 2026-10-09 00:20 published → delivered (done): nothing for a walk to move

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/hq@a11b14f7ae78` — **delivered** since 2026-10-09T00:20:37Z **Delivery plan** — builds nothing: the change touches no module of the mesh's graph **Transitions** - 2026-10-09 00:17 (new) → proposed (announced): novox/hq#238's head announced - 2026-10-09 00:18 proposed → checked (checked): the verdict names this commit - 2026-10-09 00:18 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-09 00:20 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-09 00:20 published → delivered (done): nothing for a walk to move The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.

jschoubben added 1 commit 2026-10-08 23:54:45 +00:00

ADR 0269: say that a unit stopped by hand while held cannot be told apart, that a restored Persistent timer catches up at once, and what is left alone ... 2e2be955e9

Third review: a person's stopping a unit the mesh also held stopped leaves no trace, so it is started
again on removal; the home server's restored weekly timer would start a scrub of about 46 hours at once.
A masked or since-changed unit is left alone, and a failed restore waits.

jschoubben added 1 commit 2026-10-08 23:54:53 +00:00

ADR 0269: the catch-up happens when the timer's last run is more than a week back 61ab74c70e

jschoubben added 1 commit 2026-10-09 00:03:34 +00:00

ADR 0269: the -- check covers the calls in internal/system that name a service resource's unit 1a813ba313

jschoubben added 1 commit 2026-10-09 00:17:34 +00:00

ADR 0269 accepted: note the narrowing on ADR 0118, and give it a home in the node-engine's design ... a11b14f7ae

The operator accepted ADR 0269 on 2026-10-09. ADR 0118 gets the dated note the README asks for where a
later record narrows its mechanism. The node-engine's to-be design names the decision and says what it
changes, which the cycle check requires of an accepted record.

mesh-admin changed title from ADR 0269 (proposed): what the mesh's own declaration stopped is started again when it goes to ADR 0269: what the mesh's own declaration stopped is started again when it goes 2026-10-09 00:17:40 +00:00

mesh-admin merged commit 171ac2a163 into main 2026-10-09 00:20:32 +00:00

mesh-admin deleted branch decision/0269-what-the-meshs-own-declaration-stopped-is-started-again 2026-10-09 00:20:32 +00:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

mesh/ready

Reviewed and ready: mesh-delivery merges at the marked head once its checks pass (hq ADR 0364)

No labels

Milestone

No items

No Milestone

Assignees

Clear assignees

agent-ace agent-g14 agent-novox agent-shanks jschoubben mesh-tools miel.truyen nox-agent

No Assignees

2 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/hq#238