next chapter

adr/ADR-020-define-rollback-eligibility-and-retention.md

@@ -0,0 +1,56 @@
+# ADR-020: Define Rollback Eligibility and Retention
+
+## Context
+
+An A/B device retains A while trying B. Keeping A's bytes does not guarantee that A can still run: shared data, configuration, boot components, or security policy may have changed. Confirmation and later slot reuse also affect what the product can promise.
+
+The reference design needs local recovery without downloading the old release. Boot control and Linux must understand the retained recovery state.
+
+## Decision
+
+Define an explicit rollback window and the conditions that make its target eligible. Retain the target release, matching boot artifacts, required dependencies, verification information, and a supported data path for that window. Record release identities and the window state outside replaceable software.
+
+Admit a trial only when its permitted operations preserve the early-boot recovery path. The eligibility contract covers artifact validity, shared components, configuration, data, recovery-state formats, and the platform's security policy. Reassess these conditions before a supervisor initiates recovery where possible. Early boot recovery must rely on a contract established before trial, not on checks that require the failed Linux system.
+
+Confirmation alone neither guarantees nor closes a post-confirmation rollback window. The product must state whether such a window exists. Save its closure before an incompatible change or slot reuse removes the promised recovery path. An interrupted closure may conservatively leave rollback unavailable; it must not leave a promise to use a removed target.
+
+If eligibility cannot be established, stop ordinary rollback and use the separate recovery policy. Check essential functions after starting the retained release before reporting success.
+
+## Alternatives Considered
+
+### Treat Any Retained Slot as Recoverable
+
+Simple, but ignores shared data and changes outside the slot. The slot may boot while the application remains unusable.
+
+### Keep Every Previous Release Indefinitely
+
+This needs more storage and still does not preserve compatibility or permission to run old software.
+
+### Download Recovery Software When Needed
+
+This can supplement local recovery, but cannot satisfy this design's offline requirement.
+
+## Consequences
+
+### Positive
+
+- The recovery promise has an explicit lifetime and prerequisites.
+- Cleanup and migrations cannot silently invalidate a retained target.
+- Confirmation, data compatibility, and slot retention can be reviewed separately.
+
+### Negative
+
+- Retained artifacts and compatible data consume resources.
+- Releases must maintain compatible recovery-state formats during the window.
+- Closing the window may require an alternative recovery path.
+
+## Applicability and Limits
+
+Use when a product promises a return to retained software. This decision defines policy, not an artifact verifier or a durable journal implementation. Hardware failure and damaged shared boot components need separate recovery support. Security policy can prohibit an otherwise operational old release.
+
+## Related Documents
+
+- [Chapter 07: Rollback and Recovery](../docs/07-rollback-and-recovery.md)
+- [ADR-014: Trial Boot and Confirmation](ADR-014-trial-boot-and-confirmation.md)
+- [ADR-017: Keep Recovery State Outside Replaceable Software](ADR-017-keep-recovery-state-outside-replaceable-software.md)
+- [ADR-021: Preserve Data Compatibility During Trial](ADR-021-preserve-data-compatibility-during-trial.md)

adr/ADR-021-preserve-data-compatibility-during-trial.md

@@ -0,0 +1,53 @@
+# ADR-021: Preserve Data Compatibility During Trial
+
+## Context
+
+The reference A/B design shares persistent application data and configuration between A and B. Boot control may return to A before a Linux recovery supervisor can run. A trial that makes shared data unreadable by A would invalidate that path.
+
+This example can keep a compatible format during trial. It does not require an incompatible migration before B can pass its checks.
+
+## Decision
+
+Keep shared application data and configuration usable by both retained releases throughout trial. Review writes as well as reads: B's output must remain usable by A. Include interrupted application writes in the platform's data-recovery tests.
+
+Reject or defer a trial requiring an incompatible mutation without another supported recovery path. Delay such a migration until confirmation and explicit closure of the old rollback window. If rollback remains promised after confirmation, preserve compatibility for that period too.
+
+Save window closure before beginning an incompatible migration. The migration still needs its own interruption and failure procedure; closing the window does not make the migration safe.
+
+## Alternatives Considered
+
+### Separate Data Copy for B
+
+Can isolate trial writes, but needs more space, a durable selection procedure, and a policy for merging or losing trial records. Suitable when compatible shared writes are impractical.
+
+### Restore a Backup Before Returning to A
+
+Can recover an older format, but requires a validated backup, interruption-safe restoration, and explicit authorization for any lost records. Early failures require a recovery environment that can restore data before A uses it. This is not assumed in the shared-data trial design.
+
+### Always Reverse the Migration
+
+A reverse migration may exist, but can fail or lose information. It must be implemented and tested for the specific schema; it cannot be assumed from the presence of an old image.
+
+## Consequences
+
+### Positive
+
+- Boot control can return to A without first running a data restore service.
+- Trial records remain available after rollback when both versions support them.
+- Compatibility becomes an admission condition for a release.
+
+### Negative
+
+- New features may need a staged schema change.
+- Compatibility tests must cover both versions' readers and writers.
+- A later incompatible migration ends this rollback path and needs another recovery plan.
+
+## Applicability and Limits
+
+Use when retained releases share data and compatible operation during trial is feasible. This does not protect against corruption or guarantee that a migration after confirmation succeeds. Products needing incompatible trial writes should choose and test a different data recovery design explicitly.
+
+## Related Documents
+
+- [Chapter 07: Rollback and Recovery](../docs/07-rollback-and-recovery.md)
+- [ADR-016: Separate System Software and Persistent Device Data](ADR-016-separate-system-software-and-persistent-device-data.md)
+- [ADR-020: Define Rollback Eligibility and Retention](ADR-020-define-rollback-eligibility-and-retention.md)

adr/ADR-022-bound-recovery-and-block-failed-system-releases.md

@@ -0,0 +1,59 @@
+# ADR-022: Bound Recovery and Block Failed System Releases
+
+## Context
+
+Returning to A can fail, and a server may offer failed B again after a successful return. Restarting a coordinator must not give either path unlimited new attempts. The device must recover locally and retain results while offline.
+
+Boot control owns boot selection and attempt accounting. A supervisor coordinates recovery checks and keeps policy records outside the slots.
+
+## Decision
+
+Save the failed system release's unambiguous identity and reason, its automatic retry block, and recovery intent before recovery actions. Apply the block on every automatic installation path. It survives reset and rediscovery of the same release. A different release is subject to normal admission checks. An authorized operator may clear the block after review, with the action recorded.
+
+Use a finite recovery budget and a defined check deadline. Boot control accounts for each recovery boot attempt durably before handing control to the target. A restart does not refresh this budget. The reset mechanism must cover hangs that would otherwise prevent progress.
+
+Reconcile the supervisor's progress with authoritative boot state after interruption. Exclude competing installs while recovery owns the target and data. Report recovery success only after the restored system passes its essential local checks.
+
+If the target is ineligible, checks fail, or the recovery budget expires, stop the ordinary A/B path. Enter a separately defined recovery policy rather than alternating releases. The platform must specify the available recovery environment or physical service path, behavior of affected functions, and diagnostics that remain possible.
+
+Retain the failed release, failure reason, recovery result, running release, active block, and any approved data loss for later reporting. Losing connectivity does not prevent local recovery.
+
+## Alternatives Considered
+
+### Retry Until One Slot Works
+
+Can leave a device switching indefinitely without providing its required functions or reaching a diagnosable terminal state.
+
+### Let Rediscovery Clear the Failure
+
+Normal polling could immediately repeat a known failing installation. A new offer alone is not evidence that the failure was corrected.
+
+### Block All Future Releases
+
+May fit stricter products, but prevents an otherwise acceptable corrective release from being considered. This example blocks the exact failed release on this device.
+
+## Consequences
+
+### Positive
+
+- Failed updates cannot automatically repeat without policy intervention.
+- Recovery has a finite outcome and continues offline.
+- Reports distinguish an update failure from a failed recovery.
+
+### Negative
+
+- Boot control and supervisor records need coordination and compatible formats.
+- Retry limits, check deadlines, and watchdog coverage need platform validation.
+- A separate recovery path and a block-removal process must be maintained.
+
+## Applicability and Limits
+
+Use for automatic system rollback with locally retained state. This extends the package retry-block pattern from ADR-015 to system release identities. It does not implement a rescue environment or a fleet rollout pause. The block is operational policy; it does not replace signature verification or security anti-rollback rules.
+
+## Related Documents
+
+- [Chapter 07: Rollback and Recovery](../docs/07-rollback-and-recovery.md)
+- [ADR-014: Trial Boot and Confirmation](ADR-014-trial-boot-and-confirmation.md)
+- [ADR-015: Service Checks and Package Downgrade](ADR-015-service-checks-and-package-downgrade.md)
+- [ADR-019: Recover Interrupted Updates From Durable State](ADR-019-recover-interrupted-updates-from-durable-state.md)
+- [ADR-020: Define Rollback Eligibility and Retention](ADR-020-define-rollback-eligibility-and-retention.md)