Merge pull request 'Issue 264: a self-updating engine lost the report of the apply that delivered it' (#120) from issues/264-self-update-lost-report into main

2026-10-05 22:31:47 +00:00
parent fd4df96c21 3a8c23ef1a
commit 9bcd714ee6
1 changed files with 72 additions and 0 deletions
@@ -0,0 +1,72 @@
+---
+status: located
+opened: 2026-10-06
+located-in: [mesh-host]
+fixed-by:
+amended-design:
+---
+
+# 264. A self-updating engine lost the report of the apply that delivered it
+
+## Symptom
+
+One declaration for the anchor carried both a new controller and a new version of the host. The
+host applied it and said, in its journal:
+
+- `host <version> is delivered; standing aside so the launcher runs it`
+- `applied, and could not tell the mesh: reporting: context canceled`
+
+The new host started and said `in the mesh, hearing what this node should be`, and nothing more
+about that declaration. The controller's release plan waits for the first machine to report the
+exact digest of the declaration it was sent. That report never came, so the plan waited until a
+person pushed again by hand.
+
+This is the same family as [issue 257](../257-a-plan-waited-on-a-declaration-its-first-machine-never-reported/00-report.md)
+and [issue 261](../261-a-module-was-applied-and-given-back-half-a-minute-later/00-report.md): the
+machine did what it was sent, and the report the plan waits on did not say so.
+
+## Cause
+
+Standing aside for a successor ([ADR 0141](../../02-DECISIONS/0141-the-host-delivers-its-own-successor.md)) is
+decided inside the apply, once the apply has finished, and it cancels the link's context. The link
+then published the apply's report on that same cancelled context, and the bus refused it before it
+left. The declaration was then acknowledged anyway, so the mesh did not deliver it again, and the
+new host had nothing that told it a report was owed.
+
+A crash or power cut between the apply and the report has the same shape. The declaration is
+delivered again in that case only because it was not yet acknowledged, and nothing on the machine
+records that a report is owed.
+
+## Fix
+
+Two parts, in the host:
+
+1. The report of an apply, and of a declaration set aside for a newer one, is published on a context
+   that standing aside does not cancel. It is still limited by the host's timeout, and it is sent
+   before the connection is closed. After an apply that stood aside, nothing further is applied.
+2. The report of the last apply of a declaration from the mesh is kept beside the node's state until
+   the broker has taken it. When a host links, it first sends any report still kept, before it applies
+   anything newly delivered, so the re-sent report cannot arrive after a newer one. What is re-sent
+   is exactly the report the apply made, with the same digest and the same outcome. It is never a new
+   description of the machine, so it cannot claim that something was applied when it was not. A
+   report that names no declaration, such as a refused one, clears what was kept. A node that never
+   applied anything sends nothing.
+
+## How it is checked
+
+These tests in the host fail without the fix:
+
+- `TestAnApplyThatEndsTheLinkIsStillReported`: an apply that cancels the link still has its report
+  delivered, and its declaration is settled after the report.
+- `TestAReportLostAfterTheApplyIsSaidOnTheNextLink`: a report the broker refused is sent again on the
+  next link, unchanged.
+
+These tests guard the edges:
+
+- `TestNothingIsSaidAgainWhenNothingWasLost`: nothing is re-sent when nothing was lost.
+- `TestTheKeptReportSurvivesTheHost` and `TestNothingKeptWhenNothingWasApplied`: the kept report
+  survives a restart exactly as it was made, and it is cleared only by a report about the same
+  declaration.
+
+Once the fix is rolled out, the live check is the next declaration that carries a new host version.
+The first machine's report should reach the plan without anyone pushing by hand.