Make Photos PhotoKit-first

[jmcte]

Summary

• use bounded PhotoKit reads as the primary Photos logical-asset source
• return identifiers, media facts, dimensions, favorite/hidden state, album membership, and explicit provenance
• avoid pixels, thumbnails, network requests, and implicit iCloud downloads
• retain the existing package walk only as --degraded-filesystem

Governing Issue

Closes #94

Validation

• Relevant local checks passed

• Required PR checks are expected to satisfy CI Gate

• Skipped checks are explained below

• swift test --disable-sandbox (117 tests passed)

• bash scripts/ci/run-fast-checks.sh (passed)

• ./.build/debug/icloud-cli photos authorization --format json (exit 0, denied state, no access request)

No checks skipped.

Bootstrap Governance

• Changes are scoped to the linked issue
• Contributor or PR guidance changes are reflected in CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, and docs/bootstrap/onboarding.md when applicable
• PR author enabled auto-merge where GitHub allows it, or GitHub plan-limit evidence/unavailable reason is recorded and the fallback merge-readiness policy applies
• No real secrets, runtime auth, or machine-local env files are committed

No contributor guidance changed. Auto-merge will be enabled after stacked dependencies merge.

Flow Contract

• Owner lane: Hermes native provider
• Repair owner: jmcte
• Autonomy class: bounded implementation
• Risk class: high-sensitivity metadata; read-only

Flow Merge Readiness

• Every blocker has a next actor and next action
• No active blocking requested changes remain
• Non-author approval is present when required
• PR author enabled auto-merge where GitHub allows it, or recorded why it is unavailable/unsafe

Next actor: independent reviewer after #101 and #102 merge.

Merge Automation

• PR author enabled auto-merge with gh pr merge --auto --squash, or the reason it is unavailable/unsafe is noted below

This draft is stacked on the #89 provider manifest and #90 SQLite snapshot foundation. It can be rebased and enabled for auto-merge after those land.

Notes

• PhotoKit does not expose reliable local/cloud availability without attempting a media request, so that fact is explicitly unknown.
• Derived observations are separate from source facts and remain empty; no OCR or classification occurs.

[Hermes-omt]

The exact head passes swift test (117 tests), but this PR must be rebased onto current main before approval. Live main is d7f88dc01bd283b53c55fa59ed63f43f212a50a5; GitHub reports this PR unmergeable/dirty, and a local merge-tree reproduces conflicts in CommandLine.swift, CommandRunner.swift, ProviderManifest.swift, and provider-manifest tests. Resolve the rebase while preserving main's providers external-manifest support and combining this PR's PhotoKit/provider capability changes, then rerun CI on the rebased head.

[Hermes-omt]

Request changes: photos list --photos-library PATH parses and retains PATH, but CommandRunner only uses it inside if options.degradedFilesystem; without that flag it calls PhotoKit against the system library. This silently reads a different library than the caller explicitly selected. Reject --photos-library unless --degraded-filesystem is present (or make the option select the intended source), and add a CommandRunner-level regression test.

[jmcte]

Implemented the outstanding review repair in 70f13f6.

• photos list --photos-library PATH now fails unless --degraded-filesystem is also present, so a caller-selected source cannot be silently ignored by the PhotoKit path.
• Added a CommandRunner regression for the invalid option combination.
• The earlier rebase request is already satisfied: this branch is currently mergeable against main.

Verified locally:

• swift test — 121 tests passed
• bash scripts/ci/run-fast-checks.sh — passed (policy, security/fixture checks, coverage/mutation checks, debug/release builds)
• git diff --check

Please re-review when convenient.

[Hermes-omt]

Reviewed exact head 70f13f6. The prior Photo Library override repair is present, main is current and mergeable, and CI is green. Hermes validation passed: swift test, scripts/ci/run-fast-checks.sh, and git diff --check. Approve.

[athena-omt]

$P1: The new withSnapshot routine does not create a coherent SQLite snapshot of a live WAL-mode database. It copies the main database at lines 108-110 and then separately tests/copies -wal and -shm at 111-115, with no read transaction, SQLite backup API, or lock held on the source. A writer may checkpoint/truncate or append between those operations, so the copied main/WAL pair can represent different database states; SQLite can then return stale/inconsistent results or fail to open the purported snapshot. This affects the newly migrated Messages and Safari history reads. Please create the copy through SQLite while holding a read snapshot (for example using the backup API / VACUUM INTO in a read transaction), rather than copying live files independently, and add a race/regression test covering checkpoint or WAL mutation during snapshot creation.

[jmcte]

Addressed the current-head review request.

The snapshot engine now uses SQLite VACUUM INTO to materialize one coherent snapshot rather than independently copying a database and WAL. Added coverage for a live WAL-backed source and documented the invariant.

Local verification:

• swift test --filter snapshotQuery
• swift test (122 tests)

[Hermes-omt]

Reviewed exact head b4c2dd4 on Hermes. The live-WAL coherence repair now uses SQLite VACUUM INTO, with a single-file live-WAL regression test. Branch is current, clean, and mergeable against main; no inline review threads are present. Local swift test and git diff --check passed; CI Gate and PR Checks succeeded. Approve.

[Hermes-omt]

Reviewed exact head d199b09 on Hermes. The prior PhotoKit option and SQLite live-WAL concerns are repaired: caller-selected Photos libraries require the explicit degraded path, and snapshots use SQLite VACUUM INTO with live-WAL coverage. Local swift test and git diff --check passed. CI Gate and PR Checks are successful; the PR is clean and auto-merge is enabled. Approve.

[Hermes-omt]

Reviewed exact head 3a4bb221b72b22ef2e4a997e70009716e6673f59 on Hermes. The PhotoKit-first path, explicit filesystem fallback, and coherent SQLite VACUUM INTO snapshot path are correctly wired and covered by adjacent tests. swift test and git diff --check pass; live CI Gate and PR Checks are green. No actionable issues found.

[Hermes-omt]

Reviewed exact head 1f6e93c on Hermes. PhotoKit-first reads, explicit filesystem fallback, and coherent SQLite VACUUM INTO snapshots are correctly wired and covered. swift test and git diff --check passed; CI Gate and PR Checks are successful. No actionable issues found.

[athena-omt]

Exact-head re-review at 1f6e93cb9e2e4b15e6146550615c8bcf618665c6 — APPROVE.

photos list is now PhotoKit-first and fail-closed. Verified on exact head:

• PhotoKitProvider never requests authorization or media: authorization() reports requestsAccess=false; assets() throws unless state is .authorized/.limited — there is no silent filesystem fallback.
• Metadata-only: fetchAssets reads PHAsset facts (id, filename, media type, dates, pixel dimensions, favorite/hidden, album names); availability is honestly reported as .unknown; no pixels/thumbnails are requested.
• Filesystem path is opt-in via --degraded-filesystem, and --photos-library requires it (parser-enforced and error-tested).
• Provenance: degraded rows tagged photos-library-filesystem / degraded=true; PhotoKit rows tagged photokit / degraded=false.
• PermissionsDoctor now probes PhotoKit authorization (photokit-<state>) instead of a filesystem path probe.
• The SQLite snapshot engine on this head also uses SQLite-coordinated VACUUM INTO (no independent file copy).
• Regression tests cover: never-prompt, no-media, evidence/provenance, explicit-flag requirement, --photos-library rejection without the flag, and the doctor probe.
• Required checks green on exact head (CI Gate, PR Checks). git diff --check clean.

The earlier CHANGES_REQUESTED review was against stale head 70f13f6a; superseded by this approval.