Deterministic reconciliation proposals and batch apply
Deterministic reconciliation proposals and batch apply
The reconciliation workflow is a two-phase command flow. First, the system generates deterministic proposal rows from bank and invoice or journal datasets. Second, operators review and approve proposal rows, then apply those approved rows in batch. This keeps candidate planning and write operations separate, reviewable, and script-friendly.
Two-phase flow (implemented)
bus reconcile propose and bus reconcile apply provide the flow. Direct writes via bus reconcile match, bus reconcile allocate, and bus reconcile list remain available for one-off use. Script-based candidate planning (e.g. exports/2024/025-reconcile-sales-candidates-2024.sh) remains an alternative where teams prefer it.
bus reconcile propose --out reconcile-proposals-2024.tsv
bus reconcile apply --in reconcile-proposals-2024-approved.tsv --dry-run
bus reconcile apply --in reconcile-proposals-2024-approved.tsv
Proposal output includes deterministic candidate rows with confidence and reason fields so reviewers can audit why each row was suggested. Apply consumes only approved rows, writes canonical reconciliation records deterministically, and supports idempotent re-apply so rerunning the same approved file does not create duplicates.
These artifacts feed migration-quality controls in Source import parity and journal gap checks. An optional CI-friendly extension is not yet specified: thresholds or strict exit codes for “no proposals” vs “partial apply” would let scripts fail on backlog or incomplete apply without parsing output; when adopted, exit codes and optional CI flags will be documented in the bus-reconcile module reference.
Scope and ownership
bus-reconcile owns proposal generation and apply behavior. bus-bank provides deterministic bank transaction identity and normalized read fields used as proposal input. When counterparty normalization is implemented in bus-bank, proposal inputs will include a normalized counterparty field so rules can key off canonical names; the config format and field semantics will be documented in the bus-bank SDD and module reference. When reference extractors from bank message/reference are implemented, bank list and export will expose normalized fields (e.g. erp_id, invoice_number_hint) so bus-reconcile and other modules can use them without parsing raw text; extractor config and new dataset fields will be documented in the bus-bank SDD and module reference. bus-reconcile would then use those fields in propose and match (optional match by extracted reference keys path) when joining to invoice or purchase-invoice ids; expected field names and match semantics would be documented in the bus-reconcile SDD and module reference. bus-invoices provides deterministic open-item invoice identity and status or amount semantics used as proposal input.