fix(cache): keep a converted pak's raw-fallback copy through prune; heal pruned entries (#250)

[dyoung522]

Fixes #250.

The bug

cache.PruneUnclaimed conflated two causes of "unclaimed": stale/superseded content — #210's actual target — and a converted pak's deployable copy, which is unclaimed only because the merged pak claims its content (members=nil, reconcilePakManifests' participating branch) while it remains the designated raw-fallback artifact. Any sibling-file ingest into the same version directory opened the prune gate (commitStagedCacheWithMarker → PruneUnclaimed(stagePath); staging is seeded from the existing entry, so every marker reads Recorded and the retained source is present) and deleted the copy. If the user later opted out of conversion, or the next merge failed for that mod, the raw-fallback branch found no member to claim, recorded an empty member set, and deployed nothing — silently, with the exact bytes still sitting in .lmm-source-<fileID>.

The fix — both directions from the issue

Prevent (internal/storage/cache): PruneUnclaimed now exempts any unclaimed file whose content matches a retained source (size compared first, MD5 only on a size match, each side hashed at most once). This is the same content-identity attribution rawPakMembers uses (#241) — the one identity that survives the convert flip erasing the ingest-time manifest. Genuinely stale files (including same-size/different-bytes ones) are still pruned; #210's behavior is otherwise unchanged.

Heal (internal/core): the raw-fallback branch of reconcilePakManifests restores the deployable copy from the fileID's retained source when no cache member matches it, then claims and deploys it — so entries already damaged by released versions converge on the next sync instead of staying silently broken forever. Restore naming:

• import-path fileIDs restore name-exact (the fileID is the archive filename, and ingest names the deployable copy identically);
• download-path fileIDs (the literal icarus "pak") get a deterministic <mod-id>_P.pak name — the original URL-derived name is durably recorded nowhere (the convert flip erased the manifest that carried it, and the DB stores only fileIDs), which I verified across domain/DB/fingerprint before settling on synthesis.

The restore refuses to overwrite an existing same-named file (it necessarily holds different content and could be a sibling's claimed member) — failing loudly beats corrupting it, and the next reconcile pass retries.

Tests (written first, run failing before any implementation)

• TestPruneUnclaimed_KeepsUnclaimedFileMatchingRetainedSource — unit-level prevent: the suppressed copy survives, a same-size/different-content stale file is still pruned (content, not size, decides).
• TestService_DownloadMod_SiblingReingestKeepsConvertedPakCopy — the issue's repro shape end-to-end through DownloadMod: pak ingest → convert flip → sibling exmodz ingest → copy survives.
• TestReconcilePakManifests_RawFallback_RestoresPrunedDeployableCopy — table-driven heal over both fileID shapes, asserting manifest claim, restored cache bytes, actual deploy, and second-pass convergence.
• TestSyncMergedPak_OptOutAfterPrunedConvertedPak_RestoresRawDeploy — the already-damaged case through the full SyncMergedPak opt-out flow (merged entry seeded present, as in any real damaged state).

Adjacent bug found and filed, not fixed here

Writing the sync-level test surfaced a pre-existing, unrelated bug: syncMergedPak's uninstall-to-zero branch hard-errors whenever the merged-pak cache entry is absent — which is the steady state after its own first zero-sources pass deletes the entry. Filed as #260 (in the zero branch since #197/v1.28.0; reproduced with a one-line probe). It interacts with #250's opt-out leg (sync 1 heals fine; later syncs on a fully opted-out profile error loudly) but is a separate defect with its own fix-direction trade-offs, so it stays out of this PR.

Verification

go build ./... && go vet ./... && gofmt -l . && go test ./... — all green, gofmt -l empty, trunk check on changed files: no new issues. CHANGELOG entry added under [Unreleased]; no version bump per repo convention.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fixes a cache-pruning regression affecting converted .pak mods by ensuring a converted pak’s raw-fallback deployable copy is not deleted during cache.PruneUnclaimed, and by adding self-healing in the raw-fallback reconcile path to restore previously-pruned deployable copies from retained sources.

Changes:

• Update cache.PruneUnclaimed to exempt unclaimed files whose bytes match any retained source (size check first; MD5 only on size match, hashed at most once per side).
• Add a heal path in reconcilePakManifests raw-fallback to restore a missing deployable pak copy from the retained source and claim/deploy it.
• Add unit + integration tests covering both “prevent” (prune exemption) and “heal” (restore + converge) behaviors, plus a CHANGELOG entry.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
internal/storage/cache/cache.go	Adds retained-source content matching to prevent pruning suppressed raw-fallback copies.
internal/storage/cache/cache_test.go	Adds a focused unit test ensuring same-size/different-bytes debris is still pruned while matching-bytes copy is retained.
internal/core/service_test.go	Adds an end-to-end DownloadMod repro test ensuring sibling ingest doesn’t delete a converted pak’s deployable fallback copy.
internal/core/merged_pak.go	Adds restore-and-claim logic when raw fallback has no matching cache member (heals already-pruned entries).
internal/core/merged_pak_test.go	Adds table-driven heal tests for both fileID shapes and a full SyncMergedPak opt-out recovery test.
CHANGELOG.md	Documents the #250 fix and healing behavior under [Unreleased].

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.