Flow — Document lifecycle · Fuzzy entity match

Summary

Owner is correct but the bank / broker entity link is ambiguous (match score < 0.85). The user confirms the best-match entity or picks an alternate.

Audience

end-user

Entry

Document marked pending_identity_confirmation (the single collapsed status from 2026-07-11-user-identity-entry-model) from the document-lifecycle-ingest branch; identity registry per user-identity-entry (was: 2026-05-31-accounts-master-table — superseded).

Steps

#	Step	Surface	Notes
1	Document is pending_entity_confirmation	review-confirm-doc	Shows best-match account + "Other account" alternative
2a	User confirms best-match entity	review-document	→ confirmed (EXIT)
2b	User selects alternate entity	review-document	→ confirmed with updated account_id (EXIT)

Exit

Document confirmed with a resolved account_id; fields flow into pillar-tax / pillar-expense / pillar-portfolio rollups via onDocumentConfirmed.

Escapes

• Confirm gate: pending_entity_confirmation IS confirmable — user's selection is the confirm action. See the shared confirm-gate rule in document-lifecycle-ingest.
• No suitable account in picker: user can create a new account via the "Other account" path; downstream creates a new entity record.
• User picks wrong entity: re-upload to correct, since no-manual-entry forbids inline editing.

Sources

• .context/wiki/flows/* § "Flow 12 — Document lifecycle state machine" · "H. Fuzzy entity match"