feat: add file cache mapping diagnostic

docs/source-discovery/2026-07-10-file-cache-mapping-diagnostic.md

@@ -0,0 +1,73 @@
+# File Cache Mapping Diagnostic
+
+Date: 2026-07-10
+
+## Goal
+
+Run the R3b local-only diagnostic to determine whether copied MsgLib received-file metadata can be mapped to the available ignored cache/archive listing without printing file paths, raw rows, message bodies, or attachment contents.
+
+## Diagnostic command shape
+
+The diagnostic script is:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-file-cache-mapping.ps1 \
+  -ArchiveListPath <ignored-archive-list>
+```
+
+The script can also accept `ISPHERE_MSGLIB_SQLITE_DLL` and `ISPHERE_MSGLIB_DB` from the environment. The committed note intentionally omits local DB, DLL, and archive-list path values.
+
+## Sanitized result
+
+Safe summary from the available copied DB plus ignored archive-list metadata:
+
+```json
+{
+  "ok": true,
+  "verification": "file_cache_mapping",
+  "db_checked": true,
+  "db_table_available": true,
+  "db_record_count": 166,
+  "db_filename_present_count": 166,
+  "db_size_present_count": 166,
+  "db_source_id_present_count": 166,
+  "db_receive_msg_guid_present_count": 166,
+  "cache_checked": true,
+  "cache_candidate_count": 11,
+  "hash_dir_length_counts": {"32": 11},
+  "filename_only_match_count": 0,
+  "filename_size_match_count": 0,
+  "unique_filename_size_match_count": 0,
+  "source_id_hash_dir_match_count": 0,
+  "mapping_validated": false,
+  "recommended_next_node": "additional evidence request",
+  "raw_paths_printed": false,
+  "file_contents_read": false,
+  "file_paths_returned": false,
+  "raw_rows_returned": false,
+  "message_body_values_printed": false
+}
+```
+
+Extension counts are allowed as coarse metadata. The diagnostic normalizes abnormal extensions to `.other` so file-name fragments are not printed.
+
+## Decision
+
+Do not implement R4 receive-file download mode from the current evidence.
+
+Reason:
+
+- MsgLib received-file metadata exists and is internally complete enough for metadata analysis: filename, size, source id, and receive message id are present for 166 inspected rows.
+- The available cache/archive listing has 11 hash-shape cache candidates.
+- The diagnostic found 0 filename-only matches, 0 filename+size matches, and 0 source-id-to-hash-dir matches.
+- Therefore no unique or repeatable cache-file resolver can be claimed.
+
+## Next route
+
+File download remains blocked until one of these is available:
+
+1. A better operator-local cache root or fresh archive-list that actually contains the same received files as `TD_ReceiveFileRecord`.
+2. A known recent received-file sample where the operator can confirm the message/file metadata and resulting local cache object, with committed output still limited to counts and booleans.
+3. A UI/client download connector path that can trigger download without relying on cache guessing.
+
+The broader roadmap should skip R4 for now and continue with R5 send-message connector discovery.