docs/v0.25.1-upgrade.md

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

# v0.25.1 upgrade and compatibility

v0.25.1 is a maintenance release after v0.25.0. It advances SQLite schema 34 to
35 and includes opt-in managed edited-media paths, recovery changes and offline
support export. Obtain archives from the [release page](https://github.com/rhoopr/kei/releases/tag/v0.25.1).

## Upgrade from v0.25.0

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 the 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 or image and the
   unchanged backup outside the working directories.
3. Upgrade one worker using the same exact username, iCloud realm, data and
   media directories, selection and metadata options. Do not enable new write
   options during the first check. Opening an owned database, including through
   a state command, can migrate it to schema 35.
4. Inspect status and manifest output, then a normal cycle and an unchanged
   cycle after reopening that worker. Review pending work and expected media.
   Stop on unexpected changes or state-write errors and retain the evidence.
   Resume other workers only after reviewing the result.

Account binding and authentication filenames do not change from v0.25.0. For
v0.24.x or earlier, follow the [account-ownership adoption procedure](v0.25-upgrade.md#back-up-and-adopt-existing-state)
first; v0.25.1 ultimately opens schema 35. A filename or matching asset is not
proof of database ownership. Never adopt mixed or unknown state.

## Rollback

v0.25.0 and older binaries refuse schema 35. Stop all writers and retain the
post-upgrade set before restoring the matched pre-upgrade configuration/state
and media/sidecars with the retained old binary or image. A binary-only downgrade
or database-only restore can mismatch state and media. Do not lower
`PRAGMA user_version`, mix SQLite companions, or reset state as a rollback shortcut.

Managed edited-primary mode can intentionally change owned paths and retain
previous content in `.kei-history`. Its default remains the suffix naming policy.
Read [the mode and downstream-library limitations](edited-primary.md) before
opting in. No history pruning or general power-loss guarantee is added.

## MOV metadata workaround

[#947](https://github.com/rhoopr/kei/issues/947) remains unresolved in this release.
In-file metadata writing can damage existing metadata structures in some MOV
layouts. The reproduced example preserved encoded media bytes; individual lost
fields or playback failure have not been established. #948's proposed guard is
not included, and this release does not repair already affected files.

For libraries containing MOV files, keep all in-file metadata writing disabled:

```toml
[metadata]
set_exif_datetime = false
set_exif_rating = false
set_exif_gps = false
set_exif_description = false
embed_xmp = false
# Optional: writes a separate file without embedding into media bytes.
xmp_sidecar = true
```

All five disabled options matter: setting only `embed_xmp = false` does not
suppress the other embedded-field writers. Check effective configuration with
`kei config show` using the same configuration as sync; command-line or
environment overrides must not re-enable an embedded option. Apply this also
to workers processing pending metadata work. Do not clear pending markers or
checksums to conceal a hold. Sidecars do not repair existing MOV damage.

## Validation and remaining limits

Source CI, extracted release-package checks and real-library validation have
different scopes. Release qualification must identify its exact source heads,
archive hashes, image digests and platform results. Live, real-service, target
filesystem and downstream media-library checks that were unavailable remain
explicit limitations rather than passing tests.

Provider indexing can still cause service/container restart loops. Unsupported
Shared Photo Library identities, legacy attribution and checkpoint holds remain
visible recovery work; zero failed downloads does not prove a complete backup.
Physical NFS/NAS behavior and representative HEIF memory bounds remain separately
unqualified. Existing duplicates and historical damage are not automatically
repaired. See [backup maintenance](backup-maintenance.md) and
[privacy-safe support export](support-export.md) for inspection and reporting.