# ADR-012: Separate Update Management from Installation

* **Status:** Proposed
* **Date:** 2026-09-21

## Context

This educational example considers a device with product-specific update conditions and an installation mechanism that already understands its artifact format. The device may later need more than one mechanism, such as a system image installer and an application package manager.

Product policy includes when updates are allowed, which local conditions must hold, and how installation relates to activation and health assessment. Installation requires different knowledge: how to validate and prepare a particular artifact and what state remains after interruption.

[ADR-005](ADR-005-package-based-updates.md) introduces this distinction for package-based updates. This decision applies the same reasoning to the wider device architecture.

## Decision

Separate update coordination and product policy from artifact-specific installation responsibilities.

The update manager evaluates assignments and local conditions, coordinates execution, and tracks the overall operation. The installer owns the artifact-specific operations it implements and reports their results and recoverable state.

Assign downloading, verification, activation, and recovery integration explicitly according to the selected mechanism. Reuse capabilities already provided by the installer or framework. Do not introduce a second coordinator where an existing framework already fulfills the required management role.

This is a logical separation. The roles may be modules in one program, existing framework components, or separate processes.

## Decision Drivers

- Product operating policy should be understandable independently of artifact-writing code.
- Existing installers should retain responsibility for the operations they support.
- An installer completing its work does not necessarily mean that the new software is active or healthy.
- Interruption handling requires accurate information from the component that performs the operation.
- Multiple update channels need coordinated access to resources and activation.

## Alternatives Considered

### Put All Product Policy in the Installer

One component evaluates operating conditions, installs artifacts, activates software, and reports the outcome.

This can be sufficient for a small product with one mechanism. In the assumed system, embedding policy into installation code makes it harder to reuse that policy across update channels or change the mechanism independently.

### Let the Backend Coordinate Installer Commands Directly

The backend issues low-level commands while the device exposes installation operations.

This shifts coordination away from local operating state and makes communication failures part of the execution path. It also leaves the device needing local protection against unsafe commands and interrupted operations. [ADR-011](ADR-011-device-controlled-update-execution.md) discusses the execution boundary.

### Introduce a Universal Installer Interface Immediately

Every mechanism is hidden behind an identical install-and-rollback interface.

This appears to simplify coordination but can obscure meaningful differences: a package operation may modify a live filesystem, while an image installer may prepare an inactive target. Recovery guarantees are not interchangeable. Define interfaces around actual requirements and capabilities rather than assuming all mechanisms behave alike.

## Consequences

### Positive

- Product policy has an explicit owner.
- Existing installation and verification capabilities can be reused.
- Different update channels can participate in a coordinated operation.
- Installation completion remains distinct from activation and health acceptance.

### Negative

- The boundary needs a defined contract for progress, errors, and interrupted operations.
- Manager and installer state can diverge after a crash and must be reconciled.
- A generic interface may need mechanism-specific capabilities or restrictions.
- Separate processes, if used, introduce communication and permission management costs.

## Notes

For each integration, establish:

- how an operation is identified and its current state queried;
- which component retrieves content and performs each required verification;
- whether installation prepares an inactive candidate or changes running software;
- what “completed” means and what remains before activation;
- whether retry, cancellation, and recovery are supported at each stage;
- which component owns activation and confirmation;
- how concurrent operations are prevented from conflicting.

The manager must not infer that installation failed solely because its connection to the installer was lost. It must inspect or reconcile the actual state before retrying.

Likewise, the manager cannot promise rollback merely because an installer exposes a downgrade command. Software, persistent data, and compatibility requirements determine whether recovery is possible.

## Applicability

This separation is useful when product policy is substantial, when existing installation tools are reused, or when several update channels need coordination.

A small single-purpose updater may implement both responsibilities together. Preserve clear ownership without adding processes or abstraction layers solely to match the diagram.