Reconciliation Scoping — Design Spec

Issue: #332 Date: 2026-03-30

Problem

Reconciliation findings are displayed at the cluster level on every document in the cluster. When a cluster grows large (especially via contracts acting as hub nodes), the reconciliation section becomes noisy and irrelevant to the document being viewed.

Solution

Two changes:

1. Contracts don't merge clusters

When a match edge involves a contract, skip cluster assignment entirely. The match edge is still written to ap_document_match (the relationship is preserved), but neither document's cluster_id is affected.

Effect: contracts never have a cluster_id. Invoice/PO/GRN clusters form purely through their own match relationships. Clusters stay small and focused (typically 2-5 documents).

Reconciliation prompt: unchanged. Contracts simply won't be in any cluster, so they won't appear in any reconciliation run.

Contract detail page: matches section still shows matched documents (from ap_document_match). No reconciliation badge or issues section — contracts have no cluster, so there's no reconciliation to display. A TODO comment marks where contract-level compliance reconciliation would go in the future.

Existing clusters containing contracts: left as-is. They'll resolve naturally as documents get re-matched over time.

2. Document-scoped reconciliation filtering

When viewing a document, only show reconciliation issues where that document's ID appears in the issue's document-ids array.

Rule: an issue is relevant to a document if and only if the document is a party to the discrepancy.

UI changes (in shared.clj):

• reconciliation-badge and reconciliation-issues gain a document-id parameter
• Filter (:issues reconciliation) to issues where document-id ∈ :document-ids
• Filtered result determines display:
  • No issues for this document → "Reconciled" badge
  • Issues exist → count badge + issue details
• matches-section threads document-id through to both functions
• SSE handler (matching-complete event) does the same

No backend changes — reconciliation JSONB stays cluster-level. Filtering is at render time.

Out of scope

• P1–P6 display improvements (Expected/Actual semantics, document attribution, aggregation transparency, summary weighting, field normalization, type ordering)
• P7 traffic-light badge on list views
• Contract-level compliance reconciliation (second tier) — left as a TODO

Files involved

• orcha/src/com/getorcha/workers/ap/matching/core.clj — assign-cluster!: skip cluster merge for contract edges
• orcha/src/com/getorcha/app/http/documents/view/shared.clj — reconciliation-badge, reconciliation-issues, matches-section: add document-id filtering
• orcha/src/com/getorcha/app/http/documents/view/shared.clj — SSE handler: thread document-id through matching-complete event