docs/v0.25.3-upgrade.md

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

# v0.25.3 upgrade and compatibility

v0.25.3 rolls the isolated v0.25.2 indexing and Rustls fixes into main's later
recovery, MOV protection, journal precision and diagnostic fixes. See the
[changelog](../CHANGELOG.md#0253---2026-10-16) for release notes. The historical
[v0.25.2 guide](v0.25.2-upgrade.md) describes that earlier isolated release.

## Upgrade

1. Stop every kei worker, scheduler, automatic updater and other writer using
   the configuration, state or media directories. Record the old binary or
   immutable image digest and effective configuration.
2. Take and verify a matched cold backup of the complete configuration/state
   directory and media/sidecars, including SQLite WAL/SHM/journal companions.
   Preserve permissions and timestamps. Keep the old binary/image and unchanged
   backup outside the working directories, including any `.kei-history` files.
3. Upgrade one worker with the same exact username, iCloud realm, directories,
   selection and metadata options. Do not enable new write options during the
   first check. From v0.25.1 or v0.25.2, schema remains 35; from v0.25.0, opening
   state can migrate schema 34 to 35. For v0.24.x or earlier, first follow the
   [account-ownership adoption procedure](v0.25-upgrade.md#back-up-and-adopt-existing-state).
4. Review `kei status`, pending work and expected media, then run a normal cycle
   and an unchanged cycle after reopening that worker. Stop on unexpected
   changes or state-write errors and retain the evidence. Resume other workers
   after reviewing the result. Zero failed downloads does not prove completeness.

During Apple `RUNNING` indexing, ordinary downloads are provisional. Keep the
state and media across restarts: trusted checkpoints stay held until complete
selected `FINISHED` inventory and retained-cursor replay succeed. Managed
layouts wait during `RUNNING` and additionally require protected materialization.
Missing or unknown readiness, expired retained cursors, incomplete work and
bounded selections can keep recovery held. Do not reset tokens or clear recovery
obligations to hide that hold.

## Rollback

Schema 35 does not guarantee compatibility with v0.25.1 or v0.25.2. Older
binaries can ignore indexing obligations or decode primary-layout journal floats
differently. v0.25.0 and older refuse schema 35. A binary-only downgrade or a
database-only restore can mismatch state and media.

Stop all writers and retain the post-upgrade set before restoring the matched
pre-upgrade configuration/state, SQLite companions and media/sidecars with the
retained old binary/image. Do not lower `PRAGMA user_version`, mix companions,
delete pending journals or reset state as a rollback shortcut.

## Metadata and remaining recovery limits

The MOV guard rejects the demonstrated unsafe embedded-rewrite layout and keeps
its original bytes and pending work. It does not repair already damaged files
or support every MOV layout. Operators keeping embedding disabled can retain the
[v0.25.1 configuration workaround](v0.25.1-upgrade.md#mov-metadata-workaround).
Sidecars do not repair existing damage. Verify effective options with
`kei config show` using the same configuration as sync before enabling writes.

Stale master-mapping recovery requires a complete current pair in the same scope.
Missing-parent and token-equivalence diagnostics add evidence without weakening
refusals. Sparse former-library references/token proof and missing-parent/metadata
attribution in [#953](https://github.com/rhoopr/kei/issues/953) and
[#954](https://github.com/rhoopr/kei/issues/954) remain unresolved; this release
does not establish full recovery of either account. The separate session-lock
test issue [#968](https://github.com/rhoopr/kei/issues/968) also remains open.
Physical NFS/NAS behavior, HEIF memory bounds, historical completeness and
downstream pairing remain unqualified. Existing duplicates remain untouched.