next chapter

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)