Clarify duplicate document identity as an explicit fail-fast corpus contract

[Copilot]

• Inspect the review feedback, current corpus chunk-key implementation, and relevant CI workflow runs
• Patch UUID-backed chunk-key derivation so it preserves authoritative doc_key identity without path canonicalization side effects
• Add focused corpus-contract regression coverage for UUID values that would collide under source-uri canonicalization
• Run targeted tests for corpus contract behavior, then run broader validation
• Run automated code review and security scanning, then reply to the review comment with the addressing commit hash

---

⌨️ Start Copilot coding agent tasks without leaving your editor — available in VS Code, Visual Studio, JetBrains IDEs and Eclipse.

[Copilot]

Pull request overview

This PR makes the corpus’ document identity rules explicit and operator-friendly by surfacing cross-source identity collisions as a typed error, and by ensuring UUID-backed notes can disambiguate same-relative-path notes across sources.

Changes:

• Add contract tests covering cross-source duplicate fallback identities (fail) and UUID disambiguation (pass, with distinct chunk IDs).
• Detect documents.doc_key uniqueness collisions during ingest and format an operator-readable DUPLICATE_DOCUMENT_IDENTITY error with remediation guidance.
• Document the strict global document identity rule and remediation steps in operator-facing docs.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_corpus_contract.py	Adds regression tests for duplicate fallback identity failures and UUID disambiguation behavior.
agent/corpus_db.py	Adds a helper query to locate an existing document by doc_key for better error reporting.
agent/corpus.py	Adds typed duplicate-identity error formatting and updates chunk-key derivation for UUID-backed notes.
README.md	Documents the strict, global document identity contract and supported remediations.
OPERATOR_QUICKREF.md	Adds an operator runbook entry for DUPLICATE_DOCUMENT_IDENTITY and remediation steps.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Chunk keys for UUID-backed notes are derived by passing doc_key into stable_chunk_key(source_uri=...), but stable_chunk_key canonicalizes source_uri like a path (e.g., backslashes -> '/', collapsing multiple '/'). That can unintentionally change user-provided UUID strings and can even cause chunk_key collisions for distinct doc_key values that canonicalize to the same string. Consider deriving the chunk-key source from an escaped/hashed form of the authoritative document identity (or adding a stable_chunk_key variant that does not path-canonicalize the identity) so chunk keys remain a true function of the stored doc_key.

[duck-lint]

@copilot apply changes based on this feedback

[Copilot]

Fixed in 9863e73. UUID-backed chunk keys now use a hashed doc_key: namespace instead of passing raw doc_key values through source-uri canonicalization, and I added a regression test covering explicit UUIDs that previously canonicalized to the same source token.