Preserve generated document namespace for audit identity

[nicho1ab]

Pull Request Evidence

Governing issue and intended outcome

• Governing issue: Make preserved-artifact backfills safely repeatable #475. Issue Make preserved-artifact backfills safely repeatable #475 remains open until deployed production acceptance proves the final 312-facility zero-update gate.
• Intended outcome: preserve the connector-generated source-document namespace long enough to translate unmatched extraction-audit identities into the correct historical persisted document scope.

Implementation scope

• Major files or components changed: preserved-artifact document/audit identity reconciliation, focused production-shaped regression coverage, and hosted-backfill developer documentation.

• Important behavior intentionally left unchanged or out of scope: schemas, migrations, connectors, source retrieval, importer semantics, reviewer-created state, deployment, production execution, and Issue Fix preserved-artifact backfill failures for 27 facilities #476.

• Existing source-document selection remains facility-scoped and persisted-identity ordered; no positional cross-document matching was introduced.

• Reviewer UI regression contracts: RT-RC-004 and RT-RC-006 remain protected invariants; no reviewer-facing presentation or interaction changed.

Root cause

Connector normalization generated a current document ID and audit IDs in that namespace. During preserved-artifact replay, persisted source-document original values replaced normalized source-document metadata before _preserve_stable_identities captured the generated document ID. As a result, unmatched audit IDs still carried the generated namespace, but the prefix-translation step no longer knew that generated namespace and emitted new source-record keys.

The correction captures the connector-generated document ID before persisted document metadata is restored. Existing audits continue to reconcile only within the correct persisted source document; genuinely unmatched audits are translated into that historical document scope.

Acceptance-criteria evidence

Acceptance criterion	Evidence and result
Production-shaped reproduction	PASS - base behavior generated new audit keys under ccld-...-inx-... namespaces.
Cross-document pairing ruled out	PASS - regression reverses persisted lexical document order relative to report order and preserves correct per-document source selection.
Historical source-document identities	PASS - complete source-document key set remains unchanged.
Historical extraction-audit identities	PASS - existing audit keys remain in their persisted document scope.
Newly materialized equivalent audits	PASS - unmatched equivalent audits are translated into the historical document namespace rather than creating replay-generated document keys.
Equivalent diagnostic	PASS - corrected production-shaped fixture reports zero differences after apply.
Repeat idempotence	PASS - repeat dry run and equivalent canonical-operation replay report updated=0 unchanged=1; second apply writes nothing.
Genuine changes	PASS - changed document evidence, changed audit evidence, new audits, removals, and ordinary new-document insertion remain detectable.
Protected state	PASS - reviewer-created state, existing source hashes, and existing import scope remain unchanged.
Production acceptance	Pending - human deployment must rerun the authoritative 312-facility diagnostic and governed repeat lifecycle before #475 closes.

Validation and failure classification

Exact command	Result	Failure classification, if applicable
C:\Repos\CCLD-complaints-poc\.venv\Scripts\python.exe -m pytest tests/unit/test_hosted_ccld_backfill.py::test_preserved_artifact_scopes_new_audits_to_historical_document_identity -q	Expected pre-fix FAIL - generated audit keys used ccld-...-inx-... prefixes	implementation-caused behavior reproduced before correction
C:\Repos\CCLD-complaints-poc\.venv\Scripts\python.exe -m pytest tests/unit/test_hosted_ccld_backfill.py::test_preserved_artifact_scopes_new_audits_to_historical_document_identity -q	PASS - 1 passed in 4.38s	none
C:\Repos\CCLD-complaints-poc\.venv\Scripts\python.exe -m pytest tests/unit/test_hosted_ccld_backfill.py tests/unit/test_hosted_seeded_corpus_import.py -q	PASS - 25 passed in 11.01s	none
C:\Repos\CCLD-complaints-poc\.venv\Scripts\python.exe -m ruff check src/ccld_complaints/hosted_app/ccld_backfill.py tests/unit/test_hosted_ccld_backfill.py	PASS - All checks passed	none
C:\Repos\CCLD-complaints-poc\.venv\Scripts\python.exe -m mypy src/ccld_complaints/hosted_app/ccld_backfill.py	PASS - no issues found	none
.\scripts\docs.ps1 with C:\Repos\CCLD-complaints-poc\.venv\Scripts prepended to PATH	PASS - Documentation check passed	none
git diff --check	PASS	none
Full local pytest suite	Not run - focused correction; required GitHub CI remains the repository-wide merge gate	none

• Implementation-caused failures: expected pre-fix regression reproduced the real namespace-loss defect.
• Test-fixture failures: one intermediate synthetic ordering issue did not model importer final-write order and was corrected before final validation.
• Environmental failures: a sandboxed process invocation was denied before execution; a plain docs invocation selected ambient Python without jsonschema, then the documented shared runtime passed.
• Tests intentionally not run and why: full local suite not repeated because scope remained narrow and required CI is the repository-wide gate.

UI and accessibility evidence (when applicable)

Not applicable - no UI or accessibility change.

Reviewer-facing redesign artifact classification (when applicable)

Not applicable - no reviewer-facing redesign.

Documentation, assumptions, and remaining risks

• Documentation impact: hosted-backfill documentation now describes preservation of the connector-generated document namespace during audit identity translation.
• Assumptions and limitations: local production-shaped regression evidence supports the namespace-loss correction, but production acceptance remains pending and no claim of corpus-wide idempotence is made before the deployed 312-facility gate passes.
• Remaining risks or follow-up: merged code still requires QNAP deployment and the exact authoritative 312-facility SELECT-only diagnostic before any apply is considered; Issue Fix preserved-artifact backfill failures for 27 facilities #476 remains separate and blocked until Make preserved-artifact backfills safely repeatable #475 acceptance completes.

Governed-boundary review

Governed boundary	Status	Specific explanation or evidence
Schemas and migrations	No change	No schema or migration changed.
Ingestion and source-connector contracts	No change	No source retrieval or connector contract changed.
Security and privacy	No change	No authentication, authorization, secret, or privacy behavior changed.
Production data and correction behavior	Authorized change	Preserved-artifact audit identity translation now retains the connector-generated namespace long enough to map unmatched audits into the correct historical document scope.
Deployment and infrastructure	No change	No deployment or infrastructure file changed.
Repository governance	No change	No governance mechanism changed.
Required GitHub workflows and checks	No change	validate, docs-check, fixtures, and security remain required.
Tests or checks weakened to obtain passage	Authorized change	No tests or checks were weakened; regression coverage was strengthened and all required GitHub checks remain required.

Required GitHub checks

• validate
• docs-check
• fixtures
• security