docs/v0.25.2-upgrade.md

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

# v0.25.2 provisional indexing patch

The [published v0.25.2 patch](https://github.com/rhoopr/kei/releases/tag/v0.25.2)
is based on the exact v0.25.1 tag, commit
`3adb55a7cd06ae8aeb930bdbe62fa323e1aaf656`. It excludes later main changes.
It addresses the [provisional indexing proposal](https://github.com/rhoopr/kei/issues/951#issuecomment-6173266761).
This guide describes that isolated release. Main also retains its later fixes
and diagnostics; a release binary cannot substitute for a pinned investigation build.

When Apple reports `RUNNING`, ordinary sync downloads may proceed with a warning.
The visible listing can omit photos. Kei keeps the last trusted sync token,
suppresses deletion-related state decisions from that listing, and saves a
per-library full-reconciliation requirement before downloading. Keep the state
database and existing media across restarts.

Once Apple reports `FINISHED`, kei refreshes the album plan, enumerates the full
selected scope and reuses verified downloads. After the final FINISHED check
qualifies that inventory, a durable replay requirement schedules the old trusted
cursor in the next cycle. That later trusted cycle applies source deletions and
may save a newer checkpoint only after the normal checkpoint gates succeed.
A failed, interrupted, bounded, or uncommitted reconciliation keeps the requirement. If the retained cursor has expired, the
existing retained-checkpoint safety hold still applies.

Managed `photos.edited_naming = "primary"` layouts, recorded layouts and pending
managed operations wait while Apple reports RUNNING, including after switching
to suffix naming. After FINISHED, a complete inventory first qualifies coverage
without changing managed files, metadata, journals or retry state. A durable
full-materialization requirement then drives the normal managed publication
owners across restarts, followed by replay of the old trusted cursor. This
recovers omitted assets even when the change feed has no later events. Failed
work retains that requirement and the old cursor. Local modifications, foreign
collisions and sidecars retain their existing protections.

Missing or unknown readiness stops the attempt. This patch adds no flag to
bypass the guard. Configured selection and date/recent bounds still apply.
Managed recovery requires an unbounded inventory and materialization before it
can complete.

The SQLite schema remains 35; recovery obligations use existing metadata rows.
A v0.25.1 downgrade does not honor this new obligation. Keep v0.25.2 and its state
until FINISHED reconciliation and retained-cursor replay complete; reverting
earlier can resume from a checkpoint without enforcing recovery of provisional omissions. Follow the
[v0.25.1 matched-backup and rollback guidance](v0.25.1-upgrade.md).

This does not establish why Apple reports indexing, guarantee API completeness,
repair unrelated historical gaps, or resolve the existing sparse Shared Library
ownership limitations. Synthetic tests are not live iCloud qualification.

The release lockfile updates Rustls from 0.23.45 to 0.23.46 for the four
RustSec advisories published on 2026-10-14. Existing audit policy is unchanged.