# ADR-001 - Backups, Firmware Fingerprint and Progress Semantics

Date: 2026-07-14

## Status

Accepted.

## Context

ESP Platform backups can capture a complete ESP32 flash image. A complete device dump is useful for restoration, but it includes mutable and sensitive state such as NVS, OTA metadata and coredump. Therefore, the SHA-256 of a complete dump can change even when the installed firmware has not changed.

The UI also performs flash operations in chunks. A single progress bar tied to the current chunk is misleading because it reaches 100% and then restarts for the next chunk.

## Decision

ESP Platform keeps two separate hashes for backups:

- Device Backup SHA-256: SHA-256 of the full captured flash image.
- Firmware Fingerprint SHA-256: SHA-256 over reusable firmware regions only, concatenated in flash offset order.

The firmware fingerprint excludes by default:

- NVS;
- OTA data;
- coredump;
- NVS keys;
- regions classified as Sensitive, Device state or Diagnostic.

The firmware fingerprint includes by default:

- bootloader;
- partition table;
- application partitions;
- reusable filesystem partitions, with warning that filesystems can still contain private data.

Backup UI progress uses two bars:

- Total progress: the full operation, monotonic and never reset during one operation.
- Current step: the active block, region, upload chunk or segment.

## Consequences

A full backup can differ because NVS changed while the firmware fingerprint still matches. This allows ESP Platform to detect exact firmware equivalence even when device-specific state changes.

Restore and Import are intentionally outside this ADR's implementation scope. The same progress model must be reused when those features are implemented.

## Validation

Physical validation on 2026-07-14 confirmed the decision. A complete 4 MB local dump was read through Web Serial over HTTPS, with monotonic total progress and per-block current-step progress. The resulting local dump had SHA-256 `a9ea663ba7afc32f90e73bf25d4e535aeeb182e9285ec5e7c974e4cc67d58600` and exact size `4,194,304` bytes.

The persisted server backup has Device Backup SHA-256 `ca965603a5c02668e63721b34c05fba0dc2494e3050edcb36b1c621bcafe785a`. The difference is accepted because mutable NVS/device state can change independently of reusable firmware. The persisted Firmware Fingerprint SHA-256 is `4ee0ccd14c1d85ed814cfe8067e6834bec7081a1bf5005768a087cd2e8e6283f`, with fingerprint size `4,096,000` bytes.

A real `app0` partition read was also validated: offset `0x10000`, size `1,310,720` bytes, SHA-256 `d79d4b3db73b490429122d64e076dedecf3c3a198497374ce3a8fa4b575fd948`. Manual device validation confirmed that the ESP32 resets and boots normally after read-only operations.

This ADR is therefore validated for Backups Stage 1 and the approved Backups Stage 2 package/fingerprint base. Restore and Import remain separate future decisions and are not implemented by this ADR.