03-system-architecture. Initial commit

adr/ADR-011-device-controlled-update-execution.md

@@ -0,0 +1,80 @@
+# ADR-011: Device-Controlled Update Execution
+
+* **Status:** Proposed
+* **Date:** 2026-09-21
+
+## Context
+
+This educational example considers remotely deployed embedded Linux devices with intermittent connectivity. A backend assigns authorized releases, but a device may lose contact after receiving an assignment or preparing an update.
+
+The device can evaluate local operating conditions and has a locally available activation and recovery mechanism. Its essential post-update health checks can be evaluated without contacting the deployment service.
+
+The architectural question is which participant controls execution once the device has accepted an update assignment. Requiring a remote command for every step would make progress and recovery depend on continued connectivity.
+
+## Decision
+
+Let the backend manage release assignment and fleet deployment policy. Let the device coordinate the local execution of an accepted update within that authorization and its local operating policy.
+
+After the required content and verification information are available, local activation, health acceptance, and recovery must not require a live connection to the deployment service.
+
+Keep enough durable local state to reconcile an interrupted operation with installation and boot state. Report progress and the resulting software state when connectivity permits. Treat backend knowledge as a potentially delayed observation of the device.
+
+This decision assigns responsibility to the device as a whole. It does not require the userspace update manager to handle failures that occur before it can run.
+
+## Decision Drivers
+
+- Connectivity may disappear during an update.
+- Local conditions determine when disruptive operations are permissible.
+- A candidate that fails to boot cannot rely on its own update agent for recovery.
+- Loss of reporting connectivity should not alone invalidate a locally healthy release.
+- Operators need to distinguish intended deployment state from observed device state.
+
+## Alternatives Considered
+
+### Server-Controlled Execution of Every Step
+
+The server authorizes each transition separately, including activation and confirmation.
+
+This provides tighter online coordination, but a communication outage can leave an operation waiting for a command. It does not remove the need for local handling of boot failures or interrupted writes. It is less suitable for the assumed connectivity model.
+
+### Local Execution with Mandatory Remote Acceptance
+
+The device installs and boots independently but requires the backend to accept the candidate before confirmation.
+
+This can be appropriate when external service behavior is part of release acceptance. In this example, it would couple an otherwise healthy local update to network availability. Such a design also needs an explicit timeout and recovery policy for unavailable remote acceptance.
+
+### Fully Autonomous Release Selection
+
+The device selects any compatible authorized release without a backend assignment.
+
+This can fit simpler products, but does not meet the example's need for centrally controlled release assignment. Local execution autonomy does not imply authority to select arbitrary releases.
+
+## Consequences
+
+### Positive
+
+- Prepared updates can complete or recover during a backend outage.
+- Local operational constraints can delay activation without a remote command round trip.
+- Boot failure handling remains available independently of the deployment service.
+- Requested and observed software states have explicit meanings.
+
+### Negative
+
+- The device needs durable execution state and interruption handling.
+- Backend status may remain uncertain until the device reconnects.
+- Remote cancellation cannot take effect immediately on an offline device.
+- Backend and device policies need clear precedence and reconciliation rules.
+
+## Notes
+
+The implementation must define when an assignment is accepted, any expiry or cancellation rules, and the points at which an operation may safely be stopped. A backend cancellation cannot undo an activation that already occurred while the device was offline.
+
+Repeated assignments and repeated reports must be reconciled with the operation identity and actual device state. They must not blindly repeat destructive installation steps.
+
+This decision does not choose polling, push notifications, storage layout, or the boot failure detection mechanism. It assumes those mechanisms can support the stated local responsibilities; later chapters must establish how.
+
+## Applicability
+
+This choice fits devices whose local health can be assessed offline and whose recovery must remain available during communication failures.
+
+Consider external acceptance when successful operation fundamentally depends on a remote system. Specify how to distinguish failure of the candidate from failure of that system or the network.