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)

adr/ADR-019-recover-interrupted-updates-from-durable-state.md

@@ -0,0 +1,59 @@
+# ADR-019: Recover Interrupted Updates From Durable State
+
+## Context
+
+Boot control and the OTA manager save different records. A restart can happen after one record changes but before another does. For example, a saved trial request can exist while installation progress still says prepared.
+
+This example must continue locally without a server connection. Both retained software versions must understand the records needed during recovery.
+
+## Decision
+
+Assign one owner to each state transition. Boot control owns boot selection, trial attempts, and confirmation. The OTA manager owns installation progress and pending reports. Progress does not override boot state.
+
+Save recovery information outside replaceable software as required by ADR-017. Define record validation, supported formats, and the action taken when a record is invalid. Use a storage method with a stated interruption contract and check write errors.
+
+Before continuing an interrupted operation, read authoritative boot state and inspect the target release. Reconcile old progress with a saved boot request or outcome. Do not rewrite a pending or running target, reset trial attempts, or begin a fresh trial merely because a progress record is old.
+
+For each operation, define whether to repeat it, verify its result, abandon it, or enter recovery. Bind progress to the release and target. A flag without this identity is not enough.
+
+If no valid boot record remains, use the platform's separate recovery policy. Never infer confirmation from unreadable state. Retain results until reporting and recovery policies allow removal.
+
+## Alternatives Considered
+
+### Restart Installation Without Reading Boot State
+
+This may overwrite a selected target or reset the trial limit. It is unsuitable for the separate-record design used here.
+
+### Put Every State Change in One Transaction
+
+This can work if all readers and writers share suitable storage and transaction support. It is not assumed here because boot control and Linux may use different storage interfaces.
+
+### Ask the Server What to Do After Every Restart
+
+The server can help with deployment policy, but connectivity may be absent during boot and recovery. Local decisions must remain possible.
+
+## Consequences
+
+### Positive
+
+- A gap between state writes has a defined recovery path.
+- Old progress does not undo a saved boot decision.
+- Interrupted operations can be handled offline.
+
+### Negative
+
+- Record compatibility and ownership must be maintained across releases.
+- Recovery needs more than a single progress flag.
+- Storage behavior and interruption handling need platform tests.
+
+## Applicability and Limits
+
+Use this approach when an update spans several persistent records or operations. It does not make those writes one atomic transaction.
+
+Checksums, redundant records, and file replacement are possible parts of a storage design. None is a complete power-loss solution without defined storage assumptions and tests. Package scripts and data migrations need their own repeat and recovery rules.
+
+## Related Documents
+
+- [Chapter 06: Atomic Updates](../docs/06-atomic-updates.md)
+- [ADR-017: Keep Recovery State Outside Replaceable Software](ADR-017-keep-recovery-state-outside-replaceable-software.md)
+- [ADR-018: Prepare and Verify Before Activation](ADR-018-prepare-and-verify-before-activation.md)