feat(recall): a recalled document segment names its source file and version (#713, slice 2) - #899

Summary

Refs #713 (slice 2 of 4). A recall hit written by ingest_document now names the document it came from: document_sources lists the source file, the content version and the adapter kind.

Root cause. ingest_document already tagged every summary/section memory with doc-ingest:<kind>:<source>@<version> (document_provenance_dedup_tag). But recall returned only the raw tag list, so a caller had to parse tags to trace a segment back to a file version. No code read that tag back.

Change.

• core/document_model.parse_document_provenance_dedup_tag inverts the tag. The kind never holds :. The version is a hex digest, so the last @ starts it. A source path may hold either character (C:\docs\team@corp\guide.docx round-trips). Any other or malformed tag gives None.
• core/document_reference.annotate_document_sources (pure) adds document_sources to each hit that has such a tag. A non-document hit gets no key. The value is always a list, so a hit whose tags name two versions shows both instead of an arbitrary pick.
• recall_helpers.annotate_source_attribution, the read-side provenance surfacing recall already calls, now also calls it. I deliberately put the call outside recall._handler_impl: touching that function would have put all of it in scope for the ADR-1122 mutation gate. outputSchema documents the field.
• In the same function, mem.get("content", "") or "" becomes mem.get("content"). recall_confabulation_risk already normalizes content or "". The redundant defaults produced 4 equivalent mutants once the function was in scope.

Remaining slices (listed on the issue): trace a derived claim or wiki synthesis to its source segments, with missing references made explicit; and when a source is corrected or deleted, report the affected references without inventing new locations.

Type of change

• New feature (non-breaking change which adds functionality)

Test plan

• tests_py/handlers/test_recall_document_sources.py (new, 5 tests):
  • end to end on SQLite: ingest_document then recall, and the hit carries {source, version, source_kind}. It fails without the change (KeyError: 'document_sources').
  • tag round trip with : and @ in the path; 8 malformed or foreign tags give None; no key on a non-document hit; two versions both listed.
• pytest tests_py/handlers tests_py/core tests_py/server: 5549 passed, 242 skipped, 1 failed. The failure is test_wiki_coverage_dashboard.py::test_unreadable_page_is_skipped_not_fatal, and it fails the same way on origin/main in this container: the container runs as root, so chmod does not make the page unreadable.
• Mutation gate (ADR-1122), run locally with scripts/ci_mutation_diff.py's plan and run_job: document_model.py rc 0, document_reference.py rc 0, recall_helpers.py rc 0. Before the extra malformed-tag cases, 3 survivors in the validity check; before the content simplification, 4 equivalent survivors.
• ruff check and ruff format --check (ruff 0.17.3) pass on mcp_server, tests_py/handlers and tests_py/core. python scripts/check_craftsmanship.py: OK.

Audit notes

• No ranking change: the field is added after ordering and before budgeting. No retrieval benchmark is affected.
• Not verified here: the PostgreSQL-gated tests (no PostgreSQL in this session), the FlashRank reranker (the model download is refused by the proxy) and pyright (not run).

Coding-standards compliance

• Layer dependency direction preserved (core only imports core; handler imports core).
• No new file over 300 lines and no new function over 40 lines. check_craftsmanship.py OK.
• No new numeric constant.

Breaking changes

None: the field is additive and absent on non-document hits.

Reviewer checklist

• CHANGELOG.md updated (Unreleased / Added).

Generated by Claude Code