Update 02

adr/ADR-008-binary-delta-delivery.md

@@ -0,0 +1,86 @@
+# ADR-008: Binary Delta Delivery
+
+## Status
+
+Proposed
+
+## Context
+
+A device may need a large artifact even though much of its content is already present in the installed version. Transferring the complete artifact can be expensive or slow on a constrained connection.
+
+A binary delta encodes the changes needed to reconstruct a new artifact from a particular source artifact:
+
+```text
+Artifact A + Delta A-to-B = Artifact B
+```
+
+This educational example considers a known source version, a validated target artifact, and a device with enough resources to reconstruct the target. It addresses delivery cost rather than the choice of update unit.
+
+## Decision
+
+Use binary delta delivery when measured savings in transfer size or download time justify the added generation, reconstruction, and maintenance work.
+
+Keep the complete target artifact available as an alternative delivery path. Reconstruct and verify the intended target before activation, using the preparation and recovery mechanisms selected for that update unit.
+
+## Decision Drivers
+
+- Network traffic or download time is a significant constraint.
+- Consecutive artifacts contain enough unchanged content to make deltas worthwhile.
+- The expected source content is available on the device.
+- The device can afford reconstruction time and temporary storage.
+- The release process can maintain a bounded set of supported source-to-target transitions.
+
+## Consequences
+
+### Positive
+
+- Less data may need to cross the network.
+- Large artifacts can become more practical to deliver over slow links.
+- The target release remains the same artifact regardless of how it is delivered.
+
+### Negative
+
+- Deltas must be generated and tested for supported starting versions.
+- A missing or modified source can prevent reconstruction.
+- Reconstruction consumes device resources and may offset some download-time savings.
+- The delivery system must handle devices that cannot use the available delta.
+
+## Special Considerations
+
+### Delivery Is Separate from the Release Unit
+
+An image delivered through a delta is still an image release. The complete-system reasoning in [ADR-004](ADR-004-full-system-image-updates.md) remains relevant even when fewer bytes are transferred.
+
+Deltas can also apply to other artifacts. They do not establish component independence, atomic activation, or rollback by themselves.
+
+### Supported Starting Versions
+
+A delta from A to C is not interchangeable with a delta from B to C. Maintaining every possible transition may cost more than the saved traffic.
+
+A release process can provide deltas for common starting versions and use the complete artifact for others. When a full transfer is temporarily impractical, the update can be deferred rather than applying a delta to the wrong source.
+
+### Verification and Recovery
+
+The reconstructed artifact must match the intended, authenticated target. A smaller transfer does not reduce the need to verify what will be installed.
+
+A failed reconstruction should leave the working version available. The chosen installation mechanism determines how this is achieved; delta delivery does not supply that protection on its own.
+
+### Measure Representative Releases
+
+Savings depend on how artifacts change and how they are built and encoded. A small source-code edit does not necessarily produce a small binary delta.
+
+Compare complete delivery and delta delivery using representative releases, including reconstruction cost and the number of older versions that remain supported.
+
+## Applicability
+
+This approach fits systems where delivery cost is material and artifacts retain substantial unchanged content between releases.
+
+Prefer complete delivery when artifacts are small, connections are inexpensive, source versions are unpredictable, or reconstruction and maintenance costs outweigh the saving.
+
+## Alternatives Considered
+
+- Complete, optionally compressed artifact delivery keeps the transfer path simpler.
+- Smaller independent release units can reduce traffic when component lifecycles justify them; see [ADR-007](ADR-007-independent-application-updates.md).
+- [Versioned filesystem trees](ADR-009-versioned-filesystem-trees.md) can reuse content through a different storage and deployment model.
+
+Content reuse need not always use a precomputed source-to-target delta. For an implementation example of block reuse with a full image available, see [RAUC's adaptive update documentation](https://rauc.readthedocs.io/en/latest/advanced.html#adaptive-updates). This is a related mechanism, not the specific delta model selected here.