Distinguish retrieved sources from cited references

[Paul Lizer (paullizer)]

Summary

Separates the complete set of retrieved workspace and web search results from the smaller set of references the final assistant response actually cites, so Used documents, conversation details, and export references stop presenting every retrieval candidate as a citation.

Sources stays the full retrieval/execution disclosure. New assistant responses additionally persist exact cited document and web subsets, so conversation reads and exports consume persisted data instead of reparsing message history.

Fixes #1249

Behavior

Surface	Before	After
Per-message Sources	All returned sources	Unchanged — all returned sources
Used documents drawer	Every retrieved document	Documents cited by active responses
Conversation details	Documents, no usage signal	All source documents + Cited badge on exact matches
Export references	Every returned source	Exact cited document/web records + executed tools
JSON export	Full source arrays	Full source arrays plus exact cited subsets

Persisted contract

Assistant messages keep hybrid_citations, web_search_citations, and agent_citations unchanged, and add citation_tracking_version, cited_hybrid_citations, and cited_web_search_citations. Conversations gain used_documents for exact active-response usage and legacy_used_documents for pre-tracking compatibility.

Matching uses exact [#citation-id] tokens, with strict filename/location matching as a fallback for the visible (Source: file, Page/Sheet/Location: value) format. Agent/tool records remain references because they represent executions that actually occurred; Foundry web-source proxies are deduplicated into web references.

Coverage

• Persisted across non-streaming, streaming, mixed-source, assigned-knowledge, document-action, canceled/interrupted partial, and workflow responses.
• Exact aggregates rebuilt after retry, edit, attempt switching, deletion, and conversation fork; a failed rebuild is marked and repaired on the next read.
• Propagated through collaboration conversion, synchronization, serialization, and stream mirroring, including persisted partial responses.
• Sheet, page, and workbook schema locations render and export consistently.

Compatibility

No database migration and no read-time history parsing. Conversations and messages without tracking keep their existing document list and prior export behavior, and are never falsely marked as exactly cited.

Validation

• test_chat_cited_source_tracking.py 15/15 (matching, aggregation, lifecycle, collaboration, UI/export contracts)
• test_per_message_export.py 16/16, test_per_message_powerpoint_export.py 7/7
• test_conversation_fork.py, test_chat_retry_edit_streaming_parity.py 4/4
• Route policy suites 12/12, XSS guardrails 4/4, version-assertion and release-docs guardrails
• Broken-access-control scan on all changed Python files, node --check on all changed JS, whitespace/diff checks

Authenticated Playwright tests were updated (drawer selection, details Cited badge, citation parsing) but skip in CI-less environments without a UI base URL and storage state.

Version bumped to 0.250.215 with release notes, fix documentation, and feature documentation updated.