# Document Reconciliation v2

After a group is completely classified, `opportunity_document_links` is the
sole authority for document selection. During rollout the canonical resolver
uses legacy fields for a whole `(opportunity_id, document_kind)` group until
every legacy document in that group has a current v2 link. It never mixes both
authorities inside a group. `commercial_documents.opportunity_id`, `role`,
`is_primary` and `is_active` are dual-write compatibility fields only.

## Deployment

1. Deploy this compatibility code first. It can run before migration 007.
2. Run `python scripts/preflight_document_reconciliation_v2.py`; stop on any blocker.
3. Run `python scripts/apply_migrations.py --dry-run` and review the pending migration.
4. Run `python scripts/apply_migrations.py` against the intended database.
5. Keep all consumers on this compatible release. Do not deploy v2-exclusive readers.
6. Dry-run group batches and archive JSON/CSV: `python scripts/migrate_document_reconciliation_v2.py --dry-run --batch-size 500 --output-json /safe/path/batch.json`.
7. Apply complete group batches. Resume with the emitted composite checkpoint,
   `--resume-from 'OPPORTUNITY_UUID|document_kind'`. A group is checkpointed only
   after all its documents commit.
8. `--only-unambiguous` still writes `REVIEW_REQUIRED` links (option B), so groups
   never become partially invisible. Resolve reviews in the admin UI.
9. Verify no legacy-resolved groups remain, then v2-exclusive readers may be deployed.

## Rollback

Rollback application code first and stop every v2 consumer. Export
`opportunity_document_link_events`; confirm all legacy compatibility fields are
filled. In a dedicated psql session set
`clientflow.v2_consumers_active='off'` and
`clientflow.document_ledger_exported='on'`, then execute
`migrations/007_document_reconciliation_v2_down.sql`. The down migration checks
these conditions and removes dependent line columns, trigger/function, events,
command claims and links in dependency order. The ledger is lost after export;
manual decisions made only in v2 must be reconciled before rollback. Neither
migration changes remote Jasmin documents.

CSRF remains separate security debt; this change reuses existing admin
authentication and does not claim to add CSRF protection.