docs/v0.25-upgrade.md
Rama main · réplica de lectura del repositorio original.
# v0.25.0 upgrade and compatibility
v0.25.0 introduces account-bound state and authentication and advances the
SQLite schema from 28 to 34. Existing unowned legacy databases require explicit
adoption and a fresh login before ordinary state access. Read these steps before
replacing a working binary or container. Obtain release archives from the
[release page](https://github.com/rhoopr/kei/releases/tag/v0.25.0).
## Back up and adopt existing state
1. Stop every kei worker, scheduler and automatic updater using the configuration,
state or media directories. Stop other media writers for the backup. Offline
state commands must also stop. Record the old binary or immutable image digest,
configuration, mounts and permissions privately; retain that binary or image.
2. Take and verify a matched cold backup of the complete configuration/state
directory and media/sidecars. Include SQLite WAL/SHM/journal companions and auth
files. Preserve permissions and timestamps. Keep the backup unchanged, private
and outside the working directories. Check space for the backup, database copy
and any independent media copies required by existing recovery work.
3. Independently verify that the complete legacy database belongs to the exact
configured username and iCloud realm (`com` or `cn`). Case, punctuation and
Unicode spelling are significant. A filename, asset name, zone or checkpoint
is not ownership evidence. Do not confirm mixed or unknown ownership.
4. Upgrade one worker. Keep the existing account, data directory, selection,
templates and metadata-write options. For an unowned legacy database, run:
```sh
kei migrate-state --legacy-db /path/to/legacy.db --confirm-ownership
```
Use the same configuration as ordinary commands. Adoption requires a fresh
password login and may need 2FA even with an old cached session. Noninteractive
password sources and `--code` are supported. A failed login publishes no state
database. An existing destination is never overwritten or merged; if filesystem
publication is uncertain, inspect the destination before retrying.
5. Legacy session/cookie/cache and encrypted credential files are preserved and
ignored. Do not rename them into the new namespace. Users of the encrypted
password backend must save their password again with `kei password set`.
Existing exact-username OS keyring entries and configured password sources
remain usable. Ordinary session reuse resumes after binding.
6. Inspect `kei status` and `kei manifest`, then a normal cycle and an unchanged
cycle after reopening that worker. Check expected files and retained work.
Stop on unexpected changes or state-write errors and retain all evidence.
Do not enable metadata rewrites, reset state or clear checkpoints to remove a
hold. Resume other workers only after reviewing the result.
Adoption preserves the source database and its companions. SQLite backup includes
committed WAL content, rows, unknown tables, mappings, checkpoints and retry debt.
The staged copy is account-bound, migrated, integrity-checked and published without
replacement. Conflicting account or realm provenance stops adoption. Bound
intermediate-development databases do not become legacy sources. A new account
with no legacy database follows the normal login flow. See
[account-state migration](account-state-migration.md) for the full boundary.
## Rollback
Stop all writers and retain the post-upgrade set before restoring anything.
Restore the matched pre-upgrade configuration/state and media/sidecars together
with the retained old binary or image. The preserved legacy source is a historical
snapshot after adoption; do not resume an older binary against it while current
media has changed. A binary-only downgrade or database-only restore is unsafe.
Do not lower the schema version, mix SQLite companions from different snapshots
or reset state as a rollback shortcut.
## Compatibility and recovery
| Identifier | v0.25.0 value | Effect |
| --- | --- | --- |
| Package version | `0.25.0` | Release build identity |
| SQLite schema | 34 | Older schema-28 binaries cannot read the upgraded database |
| Account owner format | 1 | Checked independently before schema migration |
| JSON sync report | string `"3"` | Existing report contract |
| Sidecar output revision | No automatic sweep | Untouched-sidecar catch-up remains separate work |
Even offline state commands enforce account ownership. A missing or mismatched
owner stops access before migration. Opening a correctly bound database can
migrate it to schema 34; an apparently read-only command is not a backup step.
Authentication also pins provider identity for sync/import and watch handoffs.
Unknown identity cannot be repaired by changing a filename or fabricating ownership.
Supported private named-album and Unfiled selections retain account-bound work
and per-destination recovery evidence. Unfinished media and metadata obligations
can resume after reopen; existing checkpoint and filesystem guards remain.
Unsupported, mixed, shared and smart-folder selections keep their existing paths.
Observed pages, rank EOF and delta bridges are not an atomic provider snapshot,
proof of historical completeness or permission to delete local media. Source
capture refuses capacity or incompatible-state failures; no automatic pruning or
general power-loss guarantee is added. SQLite WAL/NORMAL durability is unchanged.
Sparse identities, unattributed legacy owners, failed metadata and incomplete
checkpoints can remain pending while other work succeeds. Zero failed downloads
is not proof of a complete backup. Keep original bytes, databases and recovery
artifacts; do not remove temporary files by suffix or age. See
[maintenance guidance](backup-maintenance.md#interpret-recovery-evidence).
## Validation scope and limitations
The reporter accepted main `386e68cdb0b2302933946ba821327f616f73ce81` on the
affected Windows/NTFS library: [#913 import and reopened sync](https://github.com/rhoopr/kei/issues/913#issuecomment-6032510185)
and [#914 five concurrent-twin runs](https://github.com/rhoopr/kei/issues/914#issuecomment-6032593450).
Those results used the qualified development artifact, not the future release
archive. Release qualification and publication must identify their own exact
heads, checks, platform archives and hashes, image digests and Homebrew update.
Hard-linked originals remain unsupported for legacy preservation in
[#853](https://github.com/rhoopr/kei/issues/853)/[#884](https://github.com/rhoopr/kei/issues/884).
Do not unlink them or bypass the guard. Existing duplicates, damaged media,
overwritten dates and unknown historical ownership are not automatically repaired.
Physical NFS/NAS testing, OS flush-fault injection, real host-service lifecycle,
cross-zone live fixtures and representative large-HEIF memory qualification are
separate checks. No general memory ceiling is established. The release run must
record unavailable checks explicitly; offline tests and historical reporter
results do not substitute for them.