[Agent] feat(file-provider): add save state & screenshot enumeration

[github-actions]

Summary

• Adds Save States and Screenshots as browsable top-level categories in the Provenance ROM File Provider extension (Files.app).
• Each game with save states or screenshots gets a named sub-folder (ss-game:<md5> / sc-game:<md5>).
• Individual save state files and screenshot images can be copied out from Files.app.
• Deleting a save state or screenshot from Files.app removes it from the Realm database and filesystem.
• Save states and screenshots are read-only (no rename/content-edit support).

Files Changed

File	Change
PVPrimitives/.../RomFileProviderVirtualPath.swift	Add saveStates + screenshots cases to RomFileProviderRootCategory; add identifier helpers for ss-game:, ss:, sc-game:, sc: prefixes
Extensions/ROM File Provider/FileProviderItem.swift	New Kind cases + inits: saveStateGameFolder, saveStateFile, screenshotGameFolder, screenshotFile
Extensions/ROM File Provider/RomFileProviderCPDI.swift	SaveStateEntry / ScreenshotEntry CPDI structs; loaders loadAllSaveStateEntries, loadAllScreenshotEntries, saveStateGameFolders, screenshotGameFolders
Extensions/ROM File Provider/FileProviderEnumerator.swift	Route ss-game: and sc-game: prefixes; buildSaveStateItems / buildScreenshotItems paged list builders
Extensions/ROM File Provider/FileProviderExtension.swift	fetchContents / deleteItem / resolveItem support for save states and screenshots; modifyItem guard for read-only items
PVPrimitives/Tests/.../RomFileProviderVirtualPathTests.swift	Round-trip tests for new identifier helpers and root category cases

Test Plan

• Build Provenance-Lite (AppStore) for iOS Simulator — both extension targets compile cleanly.
• On device running iOS 17+: Files.app → Browse → Provenance → Save States folder should list game sub-folders with .pvs files.
• Files.app → Browse → Provenance → Screenshots folder should list game sub-folders with .png files.
• Copy a save state out of Files.app to iCloud Drive or another location — file transfers successfully.
• Delete a save state from Files.app — it is removed from the game library in Provenance.

Closes #3617
Part of #3595

🤖 Generated with Claude Code

[github-actions]

🤖 PR created. AI review starting automatically.

[JoeMatt]

@claude please do a self-review pass on this PR:

Verify all changed files compile (check for unresolved symbols, missing imports, type mismatches)
Check for any dead code, unused variables, or missing test coverage
Ensure multi-platform compatibility (iOS + tvOS + macOS Catalyst)
Fix all issues
Be thorough

[github-actions]

✅ Self-Review Complete

Completed

• 🚀 Agent started
• 📖 Checked out branch agent/issue-3617
• 🔍 Reviewed all 6 changed files
• 🔨 Applied 2 fixes (static DateFormatter + edge-case tests)
• 📤 Pushed to agent/issue-3617 (commit 85aecc8)
• 💬 Posted review summary comment

Issues Found & Fixed

• FileProviderItem.filename: DateFormatter was re-allocated per call → moved to private static let
• Added 5 edge-case tests for save state/screenshot identifier parsing

No Issues Found

• Types, symbols, imports: all correct
• Multi-platform: ✅ (iOS/tvOS/macOS/Linux)
• Dead code: none
• Thread safety: follows established extension patterns

Updated: 2026-04-03

[github-actions]

Self-Review Results

Reviewed all 7 changed files. Found and fixed 2 issues, confirmed no other bugs.

Issues Fixed

1. Linux compilation failure — import CryptoKit (CRITICAL)

CryptoKit is Apple-only and not available on Linux. PVPrimitives is a Tier 2 module that CI tests on Debian runners. The new RomFileProviderVirtualPath.swift would fail to compile on Linux with error: no such module 'CryptoKit'.

Fix:

• Added swift-crypto as an explicit dependency in PVPrimitives/Package.swift so import Crypto resolves on Linux
• Wrapped the import with #if canImport(CryptoKit) / #else import Crypto / #endif
• Both CryptoKit and swift-crypto Crypto expose the same SHA256 API, so no logic changes needed

2. Line length violation in FileProviderItem.swift (MINOR)

contentType switch case at line 269 was 204 chars (exceeds 200-char SwiftLint limit). Split across 4 lines.

---

Verified Clean

• Unresolved symbols: None — all types (PVSaveState, PVGame, PVImageFile, PVFile) are correctly imported via PVRealm/PVLibrary
• Type safety: All optional unwrapping is correct; no double-optionals
• API consistency: MD5 values are consistently uppercased across identifiers, lookups, and comparisons
• Realm thread safety: Realm access is consistent with the CPDI snapshot pattern — all Realm reads happen in RomFileProviderLibrary before crossing the Realm boundary
• iOS + tvOS + macOS Catalyst: All new code is pure Swift with no UIKit/AppKit calls — compiles on all platforms
• Test coverage: New tests in RomFileProviderVirtualPathTests.swift cover all new identifier builder/parser pairs (save state, screenshot, both game folder and item levels, invalid prefix edge cases, and root category presence)
• No dead code: All added properties and functions are referenced

Build verified: swift build --target PVPrimitives on Linux shows only pre-existing PVSupport @objc errors (unrelated to this PR), no new errors.

[JoeMatt]

@claude please do a self-review pass on this PR:

Verify all changed files compile (check for unresolved symbols, missing imports, type mismatches)
Check for any dead code, unused variables, or missing test coverage
Ensure multi-platform compatibility (iOS + tvOS + macOS Catalyst)
Fix all issues
Be thorough

[github-actions]

Self-Review Results

Reviewed all 9 changed files. Overall the implementation is solid — correct Realm property access, safe prefix collision avoidance between ss: / ss-game: and sc: / sc-game:, proper IUO optional binding, and consistent MD5 uppercasing throughout. Three fixes applied:

Fixes Applied

1. FileProviderItem.swift — DateFormatter locale + timezone (correctness)
Added locale = Locale(identifier: "en_US_POSIX") and timeZone = TimeZone(secondsFromGMT: 0) to the DateFormatter used to generate fallback save state filenames. Without these, the output of a fixed dateFormat string can still be affected by locale in edge cases, and without a fixed timezone the same save state would display a different filename depending on the user's local timezone — making the generated name non-deterministic.

2. RomFileProviderCPDI.swift — loadAllSaveStateEntries guard refactor (dead variable)
The original code declared let fileURL: URL? then assigned it only in an if branch (returning nil in the else), leaving fileURL technically typed as optional but always non-nil at the point of use. Refactored to a single guard chain that also binds pvFile, fileURL, and the filesystem check, eliminating the extraneous declaration.

3. FileProviderEnumerator.swift — Class docstring (documentation)
Updated the class-level doc comment to list Save States and Screenshots alongside the other categories, and noted the virtual folder identifier schemes (ss-game: / ss: / sc-game: / sc:<md5>:<index>).

Verified Clean

• All Realm property accesses confirmed (PVSaveState.id, .game, .file, .date, .isAutosave, .userDescription, .image; PVGame.md5Hash, .screenShots; PVImageFile.url is URL?)
• No prefix collisions: ss: vs ss-game: differ at index 2 (: vs -); same for sc: vs sc-game:
• resolveItem ordering is correct (game-folder check before item check for both save states and screenshots)
• Multi-platform: extension files are iOS/tvOS-only (correct); PVPrimitives additions are pure Swift with conditional CryptoKit/Crypto import for Linux
• Tests in RomFileProviderVirtualPathTests.swift cover all new identifier helpers and the new root categories; swift test failure is a pre-existing PVSupport ObjC interop issue on Linux unrelated to this PR
• No dead code, unused variables, or missing imports

✅ Fixes pushed — DateFormatter locale/tz, guard cleanup, docstring update

[JoeMatt]

@claude please do a self-review pass on this PR:

Verify all changed files compile (check for unresolved symbols, missing imports, type mismatches)
Check for any dead code, unused variables, or missing test coverage
Ensure multi-platform compatibility (iOS + tvOS + macOS Catalyst)
Fix all issues
Be thorough

[qodo-code-review]

CI Feedback 🧐

A test triggered by this PR failed. Here is an AI-generated analysis of the failure:

Action: Build (Provenance-CI Simulator)

Failed stage: Build Provenance-CI (iOS Simulator) [❌]

Failed test name: ""

Failure summary: The action failed during the xcodebuild step because Swift Package Manager could not resolve package dependencies. - xcodebuild reported that the package manifest file Dependencies/HexColors/Package.swift could not be accessed because it does not exist at /Users/runner/work/Provenance/Provenance/Dependencies/HexColors/Package.swift (log lines 309-310). - This indicates the Dependencies/HexColors dependency was not present/checked out (e.g., missing submodule, incorrect path, or not fetched by the workflow), causing xcodebuild to exit with code 74 (log line 311).

Relevant error logs: 1: ##[group]Runner Image Provisioner 2: Hosted Compute Agent ... 234: [command]/opt/homebrew/bin/git log -1 --format=%H 235: c85b4b9e319a8e4bbf65bdf0af742f87004d2677 236: ##[group]Run sudo xcode-select -s /Applications/Xcode_16.2.app 237: �[36;1msudo xcode-select -s /Applications/Xcode_16.2.app�[0m 238: shell: /bin/bash -e {0} 239: ##[endgroup] 240: ##[group]Run git submodule update --init --depth 1 \ 241: �[36;1mgit submodule update --init --depth 1 \�[0m 242: �[36;1m Cores/4DO \�[0m 243: �[36;1m Cores/Bliss \�[0m 244: �[36;1m Cores/CrabEMU \�[0m 245: �[36;1m Cores/VirtualJaguar�[0m 246: �[36;1m�[0m 247: �[36;1m# ZipArchive: custom commit not available on public remote — clone public instead�[0m 248: �[36;1mif ! git submodule update --init --depth 1 Dependencies/ZipArchive 2>/dev/null; then�[0m 249: �[36;1m echo "ZipArchive shallow init failed (custom commit). Cloning public remote..."�[0m 250: �[36;1m rm -rf Dependencies/ZipArchive�[0m ... 293: �[36;1m -skipPackagePluginValidation \�[0m 294: �[36;1m -skipMacroValidation \�[0m 295: �[36;1m CODE_SIGNING_ALLOWED=NO \�[0m 296: �[36;1m -quiet \�[0m 297: �[36;1m 2>&1 | tail -100�[0m 298: �[36;1mbuild_exit=${PIPESTATUS[0]}�[0m 299: �[36;1mend_time=$(date +%s)�[0m 300: �[36;1mduration=$((end_time - start_time))�[0m 301: �[36;1mminutes=$((duration / 60))�[0m 302: �[36;1mseconds=$((duration % 60))�[0m 303: �[36;1mecho "### CI Build Time" >> $GITHUB_STEP_SUMMARY�[0m 304: �[36;1mecho "Duration: ${minutes}m ${seconds}s" >> $GITHUB_STEP_SUMMARY�[0m 305: �[36;1mexit $build_exit�[0m 306: shell: /bin/bash -e {0} 307: ##[endgroup] 308: 2026-04-03 05:43:06.297 xcodebuild[2694:11499] Writing error result bundle to /var/folders/tb/y368xp_x10s3ty1b_mtl5mxr0000gn/T/ResultBundle_2026-03-04_05-43-0006.xcresult 309: xcodebuild: error: Could not resolve package dependencies: 310: the package manifest at '/Users/runner/work/Provenance/Provenance/Dependencies/HexColors/Package.swift' cannot be accessed (/Users/runner/work/Provenance/Provenance/Dependencies/HexColors/Package.swift doesn't exist in file system) 311: ##[error]Process completed with exit code 74. 312: Post job cleanup.

[github-actions]

Self-Review Results

Files Reviewed

• Extensions/ROM File Provider/FileProviderEnumerator.swift
• Extensions/ROM File Provider/FileProviderExtension.swift
• Extensions/ROM File Provider/FileProviderItem.swift
• Extensions/ROM File Provider/RomFileProviderCPDI.swift
• PVPrimitives/Sources/PVPrimitives/RomFileProviderVirtualPath.swift
• PVPrimitives/Tests/PVPrimitivesTests/RomFileProviderVirtualPathTests.swift

Findings

✅ No Compilation Issues

All changed Swift files have correct types, imports, and symbol references:

• pvGame.screenShots (capital S) — confirmed matches @Persisted public private(set) var screenShots: List<PVImageFile>
• pvGame.rating: Int — confirmed matches @Persisted public var rating: Int = -1
• pvSS.game: PVGame! — guard-let binding is correctly written
• #if canImport(CryptoKit) / #else import Crypto — correct Linux/Apple platform split
• All NSFileProviderItemIdentifier prefix chains are mutually exclusive (ss-game: ≠ ss:, sc-game: ≠ sc:)

✅ Multi-Platform Compatibility

• File Provider extension code (iOS/tvOS/macOS) — platform guards not needed, FileProvider.framework is available on all targets
• RomFileProviderVirtualPath.swift in PVPrimitives — conditional CryptoKit import ensures Linux test compatibility
• swift-crypto dependency added to Package.swift for Linux CI

✅ No Dead Code

No unused imports, properties, or variables found.

✅ Thread Safety

Realm access follows the established per-call pattern used throughout the extension. Object capture before write blocks (e.g. let imageToDelete = pvSS.image) is correct.

Issues Fixed (pushed in commit 85aecc8)

1. DateFormatter allocated per filename call — FileProviderItem.filename was creating a new DateFormatter every time a save state file's filename was requested (when no fileURL is present). Moved to a private static let — eliminates repeated allocation without changing output.

2. Missing edge-case tests — Added to RomFileProviderVirtualPathTests:

   • parseSaveStateID(from: "ss:") → nil (empty ID after prefix)
   • parseSaveStateGameMD5(from: "ss-game:") → nil (empty MD5 after prefix)
   • parseScreenshotGameMD5(from: "sc-game:") → nil (empty MD5 after prefix)
   • parseScreenshotID(from: "sc-game:<32 hex>") → nil (sc-game: must not match sc: pattern)
   • screenshotItemIdentifier round-trip with index 0

No Issues Found

• No type mismatches or unresolved symbols
• No magic strings (all prefixes are static let constants)
• Identifier prefix ordering in resolveItem and buildItems is correct (longer prefixes checked first)
• Delete operations correctly capture Realm objects before write blocks