# Pathrule Pattern: Payment Reconciliation Ledger (1.0.0) # ::pathrule:package:payment-reconciliation-ledger ### [RULE] Post processor movements through clearing accounts (path: /src/ledger/reconciliation) A processor payout is a net settlement assembled from many balance movements, not a substitute for customer payment detail. Represent processor cash as one or more clearing accounts and post each charge, fee, refund, dispute, reserve, currency conversion, and payout movement separately using stable provider references. - Keep debit and credit entries immutable and balanced per currency, with effective and available dates retained. - Link application order ids, provider object ids, balance transaction ids, payout ids, and bank references without collapsing them. - Record corrections as compensating entries and never change a closed movement to make totals agree. - Clear the processor account only when the bank deposit and its exact payout composition are proven. Verification: Reconstruct a payout containing fees, refunds, a dispute, and transactions from several days; confirm ledger balances reach the bank amount without an unexplained plug. --- ### [RULE] Matching never hides an unresolved difference (path: /src/ledger/reconciliation) Reconciliation is evidence, not a nearest-number search. Define deterministic match rules in priority order and record which rule matched each pair or group. An amount and date tolerance may help locate candidates, but it cannot silently decide between several plausible records or explain a currency, fee, or timing difference. - Prefer shared immutable ids, then documented composite keys with currency and expected lifecycle state. - Keep one-to-many and many-to-one matches explicit so a payout, partial capture, or grouped deposit remains traceable. - Route ambiguous, unmatched, duplicated, and amount-different items into named exception classes. - Require an owner, evidence, disposition, and aging status before an exception leaves the queue. Verification: Seed duplicates, partial captures, delayed refunds, two same-amount orders, and a missing fee; confirm only deterministic cases auto-match and every remainder stays reportable. --- ### [MEMORY] Provider balance transactions are settlement evidence (path: /src/payments) A charge or refund object describes a business operation, while the processor's balance transaction or equivalent settlement record explains how that operation affected the provider balance. Preserve both. The settlement record supplies fees, net amount, availability timing, payout association, and often the actual conversion applied. Import provider evidence incrementally with a stable cursor or time overlap, deduplicate by immutable id, and retain the raw source fields needed to reproduce derived postings. Never replace historical imports with a current object snapshot. Separate retrieval time from the provider's effective and available times so delayed records are assigned to the correct operational and accounting periods. See /src/ledger/reconciliation for matching and clearing policy. --- ### [MEMORY] Period close is a reproducible evidence set (path: /ops/finance) A dashboard that shows zero today is not proof of what was reconciled yesterday. For every close, preserve the processor report parameters or immutable export, bank statement boundary, application query boundary, importer version, matching-rule version, exchange-rate source, exception snapshot, approvals, and resulting account balances. Define how late-arriving events enter a later period or trigger a controlled reopen. Keep materiality thresholds explicit without using them to erase differences. The close artifact should let another reviewer rerun the process from the same inputs and obtain the same matches and totals. See /src/payments for imported settlement evidence and /src/ledger/reconciliation for the deterministic match record. --- ### [MEMORY] Reconciliation completeness is measured at every import boundary (path: /src/ledger/reconciliation) A successful request or advanced cursor can still hide a skipped page, narrowed filter, changed account, delayed provider record, or partial report. Define completeness controls for each source: expected account and currency set, report or payout totals, first and last effective time, row count, pagination evidence, overlap window, and source identifier or hash. Run imports idempotently and compare source control totals with stored raw evidence before matching begins. Keep retrieval failures and late-arriving movements visible across period boundaries. If the provider offers both API objects and financial reports, document which source closes which gap rather than mixing them silently. See /src/payments for settlement evidence and /ops/finance for the frozen period close artifact. --- ### [SKILL] close-payment-reconciliation (path: /ops/finance) --- name: close-payment-reconciliation description: Run a processor-to-ledger-to-bank close with frozen evidence and classified exceptions. --- # Close Payment Reconciliation 1. Freeze the application, processor, ledger, and bank boundaries for the period, including timezone, currencies, and late-event policy. 2. Import immutable provider balance movements and confirm completeness through report totals, pagination evidence, and last successful cursor overlap. 3. Run deterministic matching, then reconcile processor clearing balances to payouts and payouts to bank deposits. 4. Review every unmatched, ambiguous, duplicate, timing, currency, and amount exception; attach evidence, disposition, and owner. 5. Record approvals, source hashes or export ids, rule versions, final balances, and the command needed to reproduce the close. Do not close by inserting a generic balancing entry. A remaining difference is either classified and approved under policy or the period stays open. --- ### [SKILL] triage-reconciliation-break (path: /src/ledger/reconciliation) --- name: triage-reconciliation-break description: Locate the first boundary where payment evidence stops agreeing without hiding the difference. --- # Triage Reconciliation Break 1. Capture the exact account, currency, period, mismatch amount, report version, and latest successful close before changing data. 2. Compare counts and sums at each boundary: order to payment object, payment object to balance movement, movement to payout, payout to bank, and postings to ledger. 3. Check missing pages, cursor gaps, duplicate imports, timezone edges, delayed availability, conversion records, manual provider changes, and changed match rules. 4. Reproduce the smallest mismatching group from raw evidence and identify the first incorrect or absent record. 5. Repair through an idempotent import or compensating posting, document cause and prevention, then rerun the full bounded reconciliation. Never rewrite source evidence or broaden tolerances merely to make the report green.