docs/v0.24-validation.md

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

# v0.24 validation

## v0.24.0 release preparation

The release source baseline is `0597565259d50ba28b1935bab23f5e668366c506`.
The release changes update the package version to `0.24.0`, contributor credits,
and release documentation. They do not change production behavior.

On 2026-09-16, the operator explicitly accepted the documented limitations for
v0.24.0, including incorrect streaming counters (#818), optimized-test fixture
gaps (#819), and unmeasured HEIF memory and worker-budget risks (#761/#817).
This accepts those risks for this release; it does not establish a memory
ceiling, fix the counters, or turn unavailable checks into passes. The operator
separately approved tagging and publication after reviewing the release diff
and local validation results.

The recorded full-test run on the clean source baseline passed 21 phases and
counted 7,348 tests, including authenticated live tests. One live HEIF test was
skipped with operator approval because its fixture was unavailable. The run
started and ended at the same commit. This evidence predates the version change;
it is not a new full-test run on the release commit.

Fresh checks on the v0.24.0 release worktree:

| Check | Result |
| --- | --- |
| `cargo check` | Passed |
| `just gate` | Passed: 3,618 all-feature and 3,390 no-default-feature tests; ignored tests were not run |
| `cargo run -- --version` | Reported `kei 0.24.0` |
| `KEI_FULL_TEST_EXPECT_VERSION=0.24.0 just test packaging` | Passed: optimized build, host archive extraction, exact version, help, and example-config smoke |
| Release binary help | Confirmed sync repair options, one-shot restrictions, and session-reset scope |
| Release-note extraction | Passed the workflow's extraction and link checks; Cargo manifest and lockfile matched |
| Fuzz lockfile | Updated the path dependency to 0.24.0; locked offline Cargo metadata resolution passed |

The gate includes schema migration and date round-trip tests, file-backed
reconciliation retry/steady-state tests, and binary checks for repair help,
the maintenance example, and report schema `"3"`. The merged-range coherence
pass checked schema keys, unknown-content reservations, date readers/writers,
report consumers, and CLI/distribution references. It found no new blocker in
those inspected invariants; the accepted limitations above remain.

No fresh authenticated live run, complete optimized test suite, or representative
large-HEIF memory campaign was performed for the version-only changes. Published
archives, GHCR images, and Homebrew still need verification after tagging.

## Historical documentation audit

The sections below retain the documentation audit's original scope and results.
Statements about pending work describe that audit, not the later release
preparation above.

This is documentation evidence for [#744](https://github.com/rhoopr/kei/issues/744),
not release clearance. The large-file memory checkpoint is unavailable, wiki
publication is pending, and remaining release defects need explicit disposition.

## Provenance

- Source baseline: `28fac209fa619554cb3f7cd8c0364fabddbf3ab3`, after #810, #811,
  and #812 merged. The documentation diff changes CLI help, not sync behavior.
- Package/binary version: `0.23.2-dev`; Rust edition 2024, MSRV 1.91.
- Builds checked: default `xmp` debug and release; gate tests and lints also
  cover all features and no default features.
- SQLite schema: 25. Report schema: string `"3"`. The issue's assumed schema-23
  baseline is superseded; v24/v25 reservations must be included in upgrade text.
- Wiki base: `7c313a065fa84870b7cad19a1bf3226b13d88162`. Local edits are not yet
  published. Record the resulting wiki commit when publication is approved.
- Latest release and Homebrew formula checked on 2026-09-16: `v0.23.1`.
  Docker tag contents and final v0.24 artifacts were not claimed as verified.

Checks apply to this documentation diff over the source baseline, not to the
older heads quoted in the issue. Record the merged repository commit and wiki
commit in #744 before closing it. Revalidate if the candidate changes.

## Acceptance coverage

Numbers below identify checklist items in their order in the September 14 issue
body. They map evidence; they do not mark unpublished work complete.

| Items | Claims and documentation | Production owners / evidence |
| --- | --- | --- |
| 1-6 | Schema 25, migration limits, backup/restore, fractional timestamps, distinct compatibility identifiers: [Upgrade](v0.24-upgrade.md) and wiki State Tracking | `src/state/schema.rs`, `src/state/db.rs`, `src/report.rs`; schema migration and date round-trip tests |
| 7-14 | Eligibility versus path changes, retained copies, safe leaves/parents, same-path handling, sidecars, content-specific reservations, blocking failures and retry: [Maintenance](backup-maintenance.md#change-the-backup-layout) | `src/sync_cycle.rs`, `src/download/mod.rs`, `src/download/file.rs`, `src/state/db.rs`; file-backed reconciliation transition tests |
| 15-21 | Automatic capture versus opt-in outputs, 500-asset batches, one-shot repairs, rejected combinations, capture dates: [Maintenance](backup-maintenance.md), [Metadata](metadata.md), README links and CLI help | `src/config.rs`, `src/cli.rs`, `src/sync_loop.rs`, `src/download/metadata_rewrite.rs`; binary help and executable guide example tests |
| 22-30 | HEIF item-map writer, safe refusals, guarded publication, sidecar ownership, feature support, membership/rendition facts, GPS provenance, no output sweep/container repair: [Metadata](metadata.md) | `src/download/heif.rs`, `src/download/metadata.rs`, `src/download/metadata_rewrite.rs`, `src/icloud/photos/`; fixture, ownership, fingerprint, and source-provenance tests. Large-file memory evidence remains unavailable |
| 31-35 | Headless exits, wait/resume, supervisor distinctions, session reset and password sources: wiki Authentication/Login/Service/Watch/Docker/Synology/Reset/Password/Credentials | `src/lib.rs`, `src/auth/`, `src/commands/reset.rs`, `src/commands/password.rs`, `src/service/`; offline binary auth/password tests and service renderer tests |
| 36-41 | Targeted retries, policy exclusions, checkpoint gates, distinct hashes, owned cleanup, report v3/capture fields and counter limits: [Maintenance](backup-maintenance.md#interpret-recovery-evidence), wiki State Tracking/Retry/Reports/Download Pipeline | `src/download/retry.rs`, `src/sync_cycle.rs`, `src/download/finalize.rs`, `src/cycle_reporter.rs`, `src/report.rs`; retry, checkpoint, report, and cleanup tests |
| 42-45 | Memory checkpoint, validation categories, defect scope: [limitations](v0.24-upgrade.md#known-limitations) and dispositions below | Representative large fixtures unavailable; no OOM threshold or safe memory ceiling established. Deferred fixes remain in their owning issues |
| 46-51 | Whole release-range narrative, frozen roadmap, examples/distribution, diagnostics, navigation: CHANGELOG, roadmap, example config, wiki Home/sidebar and affected options | Compared `v0.23.1..28fac20`, source/help/config, Docker files, service renderers, release metadata and Homebrew formula. Historical migration/release pages remain historical |
| 52-56 | Publication, final SHAs, sample, claim mapping and release dispositions | This record and the publishing PR. Wiki/issue publication, final artifact checks and release approval remain pending |

The reconciliation evidence includes
`path_reconciliation_preserves_mtime_and_metadata_across_retry`,
`path_reconciliation_equivalent_roots_preserve_files_across_retry`,
`path_reconciliation_live_resolution_change_preserves_rendition_ownership`, and
`path_reconciliation_reservations_survive_lookup_and_state_failure`. These use
production paths and durable state; documentation checks alone do not replace
them. No new sync/state behavior is introduced by this documentation change.

## Commands and checks

Local results on the documentation branch, checked 2026-09-16:

| Check | Result |
| --- | --- |
| `cargo check` | Passed |
| `cargo build --locked --release` | Passed |
| `just gate` | Passed: static checks, all-feature and no-default-feature offline suites; live tests remained ignored |
| `just test scenario config-docs` | Passed: 3 focused checks |
| `cargo test --test behavioral repair_help_explains_one_shot_scope_and_datetime_requirement` | Passed |
| `cargo test --test behavioral maintenance_refresh_example_accepts_complete_sweep` | Passed |
| `cargo test --test behavioral sync_report_json_offline_binary_boundary_writes_current_schema` | Passed |
| `cargo fmt --all --check` | Passed |
| `cargo clippy --all-targets --all-features -- -D warnings` | Passed |
| `docker compose config --quiet` and `bash -n docker/entrypoint.sh` | Passed; parser/syntax checks, not a container runtime test |

Binary probes use isolated temporary configuration and a fake account, not the
operator's credentials. Help was checked for sync, service run, password,
session reset, verify, reconcile, config show, install, and login. Config examples
were parsed with `config show`. Changed TOML fences and local documentation link
targets were also checked, including 39 changed/new wiki pages. The full-refresh
guide example also reaches the real runtime selection guards through the existing debug-only offline report
seam; no authentication or provider download is claimed by that probe.

Debug and release help matched the revised source. Release probes also confirmed
the service repair refusals and capture-repair requirements.

Expected repair refusals were checked separately: standalone capture repair and
conflicting refresh/recent, truncated/refresh, and truncated/dry-run flags exit 2.
Service refresh, service truncated repair, and capture repair without the
datetime writer exit 1 before authentication. The help regression test covers
both the sync and shared service help. The guide must omit `albums` and
`smart_folders` keys entirely: explicit `all`/`none` still reject full refresh.

Docker's shipped CMD is `service run --config /config/config.toml`. Generated
systemd, launchd, and Windows arguments use `service run --config <path>`.
Systemd uses `Restart=on-failure`; launchd uses a NetworkState KeepAlive condition;
Windows configures SCM failure actions. Compose uses `restart: unless-stopped`,
which also restarts after terminal-auth exit 4. These policies do not establish
backup completeness. Linux renderer tests run in the gate; macOS/Windows runtime
installation is not claimed on this Linux host.

The Homebrew formula installs `kei` into `bin` from versioned release archives.
Final tags, checksums, Docker platforms, and package versions belong to the release
owner. Source/default-feature builds do not validate every published package.

`KEI_REQUEST_DUMP_DIR` remains a debug-assertion-only diagnostic. Its Photos
bodies are unredacted and require private local storage and manual redaction
before sharing. Release builds without debug assertions do not provide it.
It is not a redacted doctor bundle.

## Serializer-backed sample

The following is a projection of the actual JSON emitted through the existing
`KEI_UNSTABLE_FAKE_SYNC_REPORT_FOR_TESTS=1` debug-only binary seam. Only unrelated
fields were omitted. This is a deterministic offline fixture, not corrected
transfer totals or evidence that #818 is fixed. The same schema path is checked
by `sync_report_json_offline_binary_boundary_writes_current_schema`.

```json
{
  "version": "3",
  "stats": {
    "metadata_capture_refreshed": 0,
    "metadata_capture_failures": 0,
    "metadata_capture_remaining": 0
  }
}
```

`metadata_capture_revision` is absent in this sample, because it is unavailable.
When present it is an integer, not the report version. Capture counters remain
integers, including zero. The unit serialization test checks an integer revision;
this binary fixture checks its omission. The sample does not stand in for an
authenticated sync or a large-file test.

## Unavailable, excluded, and unresolved checks

- Representative constrained-memory HEIC/HEIF/AVIF campaign: unavailable. The
  repository fixtures are only about 234-257 KiB for HEIC and 305 bytes for AVIF.
  The operator confirmed no large fixtures are available and excluded fixture
  acquisition work from this task. Small-fixture correctness tests do not prove
  a memory ceiling. No memory limit, measured peak, or ordinary-concurrency OOM
  disposition is claimed. #761/#817 remain release-checkpoint work.
- Authenticated iCloud/live tests: not run. Required account/album/media fixtures
  and #763's fixture migration remain separate. Ignored live tests are not passes.
- Complete optimized suite: not run; #819 remains open. The release binary build
  and help checks do not establish an optimized-suite pass or clear its fixtures.
- macOS, Windows, FreeBSD, real NAS/service installation, and published Docker/
  archive smoke tests: not run here. Parser and source checks are identified
  separately above; final artifact checks remain with the release owner.
- #770, #773, #799, #803, #817, #818, #761, #763, and #819 remained open at the
  live issue recheck. Their operator impacts are recorded in the upgrade guide.
  No production fix, priority change, or implicit release waiver is part of #744.
- Wiki and issue publication: pending approval. Publish wiki links to these guides
  after the repository documentation is available on main. Record both published
  SHAs in #744; do not close it based on repository changes alone.
- Release disposition: not granted. The operator's decision to defer fixture work
  is a scope decision, not acceptance of an unmeasured memory risk. Obtain explicit
  release decisions for remaining defects and checks before release.