06 - atomic update

adr/ADR-018-prepare-and-verify-before-activation.md

@@ -0,0 +1,57 @@
+# ADR-018: Prepare and Verify Before Activation
+
+## Context
+
+This example uses two system slots. A is confirmed and running. B is inactive and may be replaced. There is no pending trial, and the installer has exclusive access to B.
+
+Power may stop during installation. A and shared device data must remain usable. Boot control provides an interface for saving a trial request separately from normal installation progress.
+
+## Decision
+
+Prepare B without changing the normal boot choice A. Save the target and release identity before writing. Complete the required storage operations and verify the installed contents against trusted release information before saving prepared state.
+
+Request a trial through boot control only after the software and required preparation state have been saved. Boot control owns the trial target and attempts. Its storage method must have a defined result after interruption.
+
+If an operation fails or its result is unknown, inspect saved state before retrying. After a restart, verify the installed release again before making a new activation request. Do not rewrite a slot already selected for a trial or running.
+
+Keep confirmation separate. A prepared release can still fail startup checks. Preserve A and the data it needs during the supported recovery period.
+
+## Alternatives Considered
+
+### Replace the Running Slot
+
+This uses less storage, but an interrupted installation may damage the only runnable system. It requires another installation and recovery design.
+
+### Select B Before Preparation Ends
+
+This permits boot control to select incomplete software. It does not meet this example's recovery requirement.
+
+### Treat Installation Success as Confirmation
+
+Installation checks do not show that services start and work on the device. A trial remains necessary here.
+
+## Consequences
+
+### Positive
+
+- Interrupted preparation leaves A available.
+- Activation has a clear precondition.
+- Installation checks and startup checks have separate roles.
+
+### Negative
+
+- Two system slots require space.
+- Storage completion, verification, and state writes need explicit ordering.
+- Shared data and shared boot components still need their own recovery rules.
+
+## Applicability and Limits
+
+Use this approach when a complete release can be prepared away from the running system. The platform must define write completion and boot-state recovery. This ADR does not select a filesystem or prove power-loss safety.
+
+A package installed into the running filesystem does not gain this property without a separate preparation and activation mechanism.
+
+## Related Documents
+
+- [Chapter 06: Atomic Updates](../docs/06-atomic-updates.md)
+- [ADR-014: Trial Boot and Confirmation](ADR-014-trial-boot-and-confirmation.md)
+- [ADR-019: Recover Interrupted Updates From Durable State](ADR-019-recover-interrupted-updates-from-durable-state.md)