docs/v0.24-upgrade.md

Rama main · réplica de lectura del repositorio original.

# v0.24 upgrade and compatibility

This guide covers v0.24.0. For v0.24.1, see the
[current upgrade guide](v0.24.1-upgrade.md). Check the
[releases](https://github.com/rhoopr/kei/releases) for published builds and the
[validation record](v0.24-validation.md) for evidence and accepted limitations.
A source version change does not update release archives, Docker `latest`,
or Homebrew.

## Back up before upgrading

1. Stop every kei process that uses the state directory, including containers
   and scheduled jobs. Keep them stopped while making or restoring a backup.
2. Find the resolved `data_dir` and state database with `kei config show` and
   `kei doctor`. Protect this directory: it also holds authentication material.
3. Make a private backup of the complete stopped data directory, including any
   SQLite `-wal` and `-shm` companions. Do not copy only a live database file.
   Alternatively, use SQLite's backup API to make a consistent database backup.
4. Record the old binary version and save its TOML configuration. Keep an
   independent backup of media and sidecars before enabling local rewrites.
5. Upgrade, run `kei status`, and inspect the next sync result. Use
   [maintenance checks](backup-maintenance.md) when local files need validation.

Migrations run automatically. Older binaries reject schemas newer than they
support. To downgrade, stop all workers and preserve the current state first.
Restore the compatible pre-upgrade data backup into a separate directory;
point the saved configuration and old binary at that restored directory.
Do not combine its database with WAL files from the upgraded database.

A state restore does not roll back media, sidecars, or later provider changes.
Reconcile those differences before resuming normal operation. `kei reset state`
discards ownership, retry, and recovery evidence; it is not a downgrade method
or a substitute for a compatible backup.

## Compatibility identifiers

| Identifier | v0.24.0 value | Purpose |
| --- | --- | --- |
| Package version | `0.24.0` | Identifies the build, not release publication |
| SQLite schema | 25 | Durable tables, keys, and migrations |
| JSON sync report | string `"3"` | Report serialization contract |
| Metadata-capture revision | Reported separately | Provider decoding and bounded catalogue repair |
| Sidecar output revision | No automatic sweep | Untouched-output upgrades remain deferred in #799 |

### Migration history

Earlier migrations remain documented in [State Tracking](https://github.com/rhoopr/kei/wiki/State-Tracking).

| Schema | Added evidence |
| --- | --- |
| 16 | Unknown/transient provider-verification state for pending retries |
| 17 | Durable ownership of legacy master-keyed rows |
| 18 | Metadata-capture revisions and per-library repair state |
| 19 | Owned temporary-file paths |
| 20 | Capture-timestamp repair intent and prepared-output receipts |
| 21 | Per-path metadata evidence and independent retry receipts |
| 22 | Reverse lookup index for legacy owners |
| 23 | Nullable verified original-source checksum provenance |
| 24 | Durable reconciliation destination reservations |
| 25 | Content-specific reservations keyed by provider checksum and size |

Per-path migration seeds known catalogue paths. It does not discover or claim
every historical copy. Schema 23 leaves old source provenance unknown rather
than deriving it from local or download hashes. Schema 25 retains schema-24
reservations as occupied paths with unknown content. A current rendition may
need a separate sibling; migration does not infer its bytes from a newer row.
Old copies and their reservations remain. None of these migrations authorizes
overwrite or deletion.

### Fractional timestamps

Capture and addition dates now retain milliseconds in the existing non-STRICT
SQLite columns. This representation change needs no schema migration, but old
readers cannot decode rows containing fractional values. Schema compatibility
alone therefore does not establish downgrade compatibility.

There is no automatic historical precision backfill. An explicit
[metadata refresh](backup-maintenance.md#refresh-catalogue-and-configured-outputs)
can recover fractions still available from Apple; enable sidecars to update
those capture dates too. Native embedded subsecond output is unchanged.
Modification/deletion precision, hash behavior, and ordinary capture-only drift
detection remain separate work in [#803](https://github.com/rhoopr/kei/issues/803).

## Known limitations

These issues were open at the candidate audit. Recheck their disposition for
the release you install. Documentation does not waive a release blocker.

| Issue | Operator impact |
| --- | --- |
| [#770](https://github.com/rhoopr/kei/issues/770) | Selected smart-folder passes can leave path reconciliation pending and repeat work. Do not assume steady-state completion. |
| [#773](https://github.com/rhoopr/kei/issues/773) | Enabling Live Photo movies after still-only downloads can produce inconsistent companion stems. Existing stills remain; there is no automatic rename or cleanup. |
| [#799](https://github.com/rhoopr/kei/issues/799) | No automatic output-revision sweep for untouched sidecars. |
| [#803](https://github.com/rhoopr/kei/issues/803) | Millisecond capture/addition storage does not complete all timestamp-precision work. |
| [#817](https://github.com/rhoopr/kei/issues/817) | Concurrent full-enumeration passes can exceed the configured download-worker budget. The setting is an intended maximum, not a measured global cap. |
| [#818](https://github.com/rhoopr/kei/issues/818) | Streaming aggregation can undercount transfer bytes and media types. Affected reports and metrics are not authoritative totals. No media loss was demonstrated by that report. |
| [#761](https://github.com/rhoopr/kei/issues/761) | HEIF embedded writes buffer whole files and can amplify memory use. No general memory ceiling is established. |
| [#763](https://github.com/rhoopr/kei/issues/763) | Live release tests still depend on named album/media fixtures. A missing fixture is not a pass. |
| [#819](https://github.com/rhoopr/kei/issues/819) | Optimized test fixtures have cleanup races, a non-terminating truncated-response case, and debug-only 2FA assumptions. These are not established production defects. |

Repeated OOM under ordinary supported settings requires a narrow guard before
release. A warning alone does not satisfy that checkpoint. Release approval
also needs explicit dispositions for the remaining defects and unavailable
checks. See [validation evidence](v0.24-validation.md).

## Distribution checks at release time

The release owner must verify the final tag, binary version and build features,
archive names and checksums, Docker tags/platforms, and Homebrew version and
paths. Source builds use `cargo build --locked --release`; disabling default
features removes XMP/HEIF output capability, not just a default setting.
Do not copy candidate validation results onto a different release SHA.