test: add file download resolver v2 diagnostic

docs/source-discovery/2026-07-10-file-download-mapping-v2.md

@@ -0,0 +1,49 @@
+# File download mapping v2 diagnostic - 2026-07-10
+
+## Purpose
+
+R10 checks whether received-file metadata can be mapped to an operator-local cache/download file strongly enough for a future `isphere_receive_files` download path.
+
+## What changed
+
+`scripts/verify-file-cache-mapping.ps1` now has a fixture-backed scoring mode:
+
+- `-FixtureRecordsPath`: JSON records with `file_name`, `size_bytes`, `source_id`, and `created_at`.
+- `-CacheRoot`: operator-local cache root or fixture cache root.
+- `-SanitizedOutputPath`: writes a compact JSON summary without raw paths or file contents.
+
+Scoring rules:
+
+| Rule | Score | Accepted |
+| --- | ---: | --- |
+| exact filename + exact size + close timestamp | 100 | yes, if unique |
+| exact size + source id appears in cache name/ref | 80 | yes, if unique |
+| filename only | 40 | no |
+
+## Fixture result
+
+`powershell -NoProfile -ExecutionPolicy Bypass -File scripts\test-verify-file-cache-mapping.ps1` produced:
+
+```json
+{"ok":true,"archive_candidate_count":2,"records_checked":3,"cache_candidates_checked":4,"accepted_matches":2,"ambiguous_matches":0,"score_100_matches":1,"score_80_matches":1,"score_40_only_matches":1,"raw_paths_printed":false,"file_contents_read":false}
+```
+
+Interpretation:
+
+- The resolver algorithm can produce accepted matches when file metadata is strong.
+- One weak filename-only case is intentionally not accepted.
+- The diagnostic output stays committed-safe: no raw operator paths and no file contents.
+
+## Production decision
+
+This round proves the resolver logic, not a real iSphere cache mapping on this machine. The local machine still cannot log in to iSphere, and no real returned receive-file package in this repository state proves a stable cache/download mapping.
+
+Therefore:
+
+- `isphere_receive_files` list mode remains usable.
+- Real file download/copy remains blocked until a real cache mapping package produces accepted, non-ambiguous matches.
+- R11 should implement a download preview/blocked contract so digital employees get machine-readable status instead of a generic failure.
+
+## Next node
+
+R11: `Receive-file download preview contract`.