Closes #2

adr/ADR-016-separate-system-software-and-persistent-device-data.md

@@ -0,0 +1,74 @@
+# ADR-016: Separate System Software and Persistent Device Data
+
+## Context
+
+This example uses system images and an A/B layout. The device keeps the current system while preparing a new version in the other slot.
+
+An image installer can replace all contents of its target area. Device identity, calibration, settings, and application data must survive that operation. Both retained system versions may need these files.
+
+The device has enough storage for two system versions and a separate persistent data area. The product can define which data formats the retained versions support.
+
+## Decision
+
+Store system software in the system slots. Store device identity, calibration, device settings, and application data outside the areas replaced by ordinary system image updates.
+
+Keep the running system files read-only in this example. Programs write changing files to the persistent data area. The platform defines the locations and access rules for those files.
+
+An image may include default configuration. Device settings are stored separately, with a defined rule for how the application combines them with the defaults. A normal system release must not overwrite device identity or calibration.
+
+Share persistent data between the slots only when the supported recovery versions can use it. Before changing a data format, define and test compatibility or a restore path. If recovery uses a saved copy, define what happens to data written after that copy was made.
+
+The product must state when returning to an older system stops being supported. Confirmation alone does not prove that later data changes remain compatible with that system.
+
+## Decision Drivers
+
+- Installing a system image must not erase information that belongs to the device.
+- Returning to the previous system must preserve a usable data path.
+- The boundary between release files and changing device files must be clear.
+- Normal application writes should not change the system software under trial.
+
+## Alternatives Considered
+
+### Keep Device Data Inside Each System Image
+
+This is a simple layout, but replacing an image would erase the data unless the installer copies it elsewhere first. The copying and restore steps would need their own failure handling.
+
+### Keep a Separate Data Copy for Each Slot
+
+This can help isolate data changes during a trial. It needs more storage and rules for copying data, choosing the active copy, and handling new records after a return to the old slot. It may be appropriate when shared data cannot support both versions.
+
+### Keep One Writable System With All Data
+
+This can suit package-based updates. It does not meet this example's requirement to prepare and replace a complete system image while retaining the current system.
+
+## Consequences
+
+### Positive
+
+- System image replacement preserves device-specific files.
+- New application records can remain available after a return to the previous system.
+- The areas that the image installer may change are easier to define.
+
+### Negative
+
+- The platform must arrange paths and access to persistent files.
+- Shared data needs compatibility rules for retained software versions.
+- A shared data failure can affect both slots.
+- Copies or backups used for data recovery need extra storage and cleanup rules.
+
+## Applicability and Limits
+
+Use this approach when system software is replaced as an image and device data must survive that replacement.
+
+Separation may use partitions or other storage areas outside the installer's target. A directory inside a partition being overwritten is not sufficient.
+
+This choice does not protect against failure of the whole storage device. It also does not make data writes safe under power loss or make migrations reversible. Those need separate mechanisms and tests.
+
+Key storage and access protection need a security design. Placing identity files outside a system slot is only a rule about their lifetime.
+
+## Related Documents
+
+- [Chapter 05: Storage Layout](../docs/05-storage-layout.md)
+- [ADR-004: Full-System Image Updates](ADR-004-full-system-image-updates.md)
+- [ADR-014: Trial Boot and Confirmation for System Updates](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/ADR-017-keep-recovery-state-outside-replaceable-software.md

@@ -0,0 +1,74 @@
+# ADR-017: Keep Recovery State Outside Replaceable Software
+
+## Context
+
+Trial boot and service downgrade both depend on saved state. After a restart, the device needs to know which version is under trial, whether it was confirmed, and whether recovery is in progress.
+
+If that state exists only inside the software being replaced, installation or recovery may erase it. If boot control cannot read it before Linux starts, it cannot use it to handle an early startup failure.
+
+This example assumes that the platform provides storage accessible to boot control and persistent storage accessible to the OTA manager or service supervisor. These may be different areas.
+
+## Decision
+
+Keep state required for recovery outside the software areas that the relevant update or recovery operation replaces.
+
+Keep boot selection, trial attempts, and confirmation in a location and format supported by boot control. The Linux component that requests a trial or confirms the system must use the platform's defined boot control interface.
+
+Keep installation progress, service recovery progress, failed version blocks, and pending reports in persistent storage accessible to the OTA manager or supervisor. Package installation, removal scripts, and cleanup must preserve these records while they are needed.
+
+Do not require one common file for every reader. Define who writes each record and how the readers agree on its meaning. Both retained software versions must understand any state they need after recovery.
+
+Use a storage method that handles interrupted writes. Readers must detect invalid or incomplete records. The platform must define a recovery action when no valid record remains; unreadable state must not be interpreted as successful confirmation.
+
+Define when each record may be removed. A report may be removed after its delivery is acknowledged. A failed version block follows the explicit removal policy in ADR-015. Recovery progress must remain available until the recorded operation has reached a known outcome.
+
+## Decision Drivers
+
+- Restarting or replacing software must not erase the information needed to recover.
+- Boot control must make decisions before the OTA manager starts.
+- Offline recovery must retain progress and results locally.
+- Interrupted state writes must have a defined outcome.
+
+## Alternatives Considered
+
+### Store State Only Inside the Target System Slot
+
+Replacing that slot may erase the state. Boot control may also be unable to read it when the new system fails. This does not meet the recovery requirements.
+
+### Store All State in the Application's Data Files
+
+This may be convenient for reporting. It is unsuitable when boot control cannot read those files or when package operations can remove them. Separate records are used according to their readers and lifetime.
+
+### Keep the Authoritative State Only on the Server
+
+The server can track deployment progress, but it may be unreachable during boot or recovery. The device needs local state to complete those steps while offline.
+
+## Consequences
+
+### Positive
+
+- Boot and service recovery retain the information they need across replacement and restart.
+- Each reader has state it can access at the required time.
+- Reports can wait locally for the server connection to return.
+
+### Negative
+
+- The platform needs tested methods for saving and reading state under power loss.
+- Boot control and Linux must agree on state formats and ownership.
+- Multiple records may need coordination if an operation is interrupted between writes.
+- Persistent storage needs space limits and retention rules.
+
+## Applicability and Limits
+
+Use this approach when recovery decisions depend on state that must survive software replacement or an interrupted operation.
+
+This ADR defines where state belongs and who must read it. It does not select a filesystem, record format, or bootloader command. Those choices belong in the platform example and must be tested under power loss.
+
+Separating state from software does not guarantee that the state is valid. It also does not make several writes one atomic operation. The update design must handle the intermediate states those writes can leave behind.
+
+## Related Documents
+
+- [Chapter 05: Storage Layout](../docs/05-storage-layout.md)
+- [ADR-014: Trial Boot and Confirmation for System Updates](ADR-014-trial-boot-and-confirmation.md)
+- [ADR-015: Service Checks and Package Downgrade](ADR-015-service-checks-and-package-downgrade.md)
+- [ADR-016: Separate System Software and Persistent Device Data](ADR-016-separate-system-software-and-persistent-device-data.md)