--- id: DOM-ACC-REC-003 title: Payout Reconciliation realises: CON-ACC-REC-003 product_area: accounting module: reconciliation revision: 3 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-ACC-REC-reconciliation readable_by: [] lifecycle: STATE-ACC-REC-003 custom_fields: none identity: >- A generated identity and unique workspace number identify the explanation. Its unit, merchant and currency remain fixed and accompany the references to its holdings. attributes: - name: number kind: number required: true computed: true notes: Creation assigns a permanent workspace number. - name: 'business unit, merchant account and currency' kind: reference required: true computed: true notes: >- The first payout supplies the immutable financial context shared by every holding. - name: state kind: enum required: true computed: false notes: >- Only open, finalized, reversed and voided are persisted lifecycle decisions. - name: display status kind: computed required: true computed: true notes: >- Open records display draft with no claims, balanced with claims and zero difference, or in progress otherwise. - name: payouts kind: collection required: true computed: false notes: >- Creation links one to fifty payouts at their amounts; released links retain their release details. - name: claims kind: collection required: false computed: false notes: >- Up to ten thousand active claims retain matching evidence, source batch and actor; released rows remain historical. - name: manual entries kind: collection required: false computed: false notes: >- The lifetime manual-entry limit is two hundred, including entries later withdrawn. - name: dismissals kind: collection required: false computed: false notes: >- A dismissal belongs only to this draft and can be removed while the draft is open. - name: totals and difference kind: computed required: true computed: true notes: >- Preparation maintains claimed and payout sums; finalization recomputes them from holdings. - name: counts kind: number required: true computed: true notes: >- Bounded counters track claims, lifetime manual entries, payouts and evidence. - name: notes kind: text required: false computed: false notes: A versioned note replacement accepts up to four thousand characters. - name: preparer kind: reference required: true computed: true notes: The creator and qualifying audit contributors make up the preparer set. - name: finalization kind: collection required: false computed: false notes: 'Finalizer, time, effect key and waiver mark document approval.' - name: reversal kind: collection required: false computed: false notes: >- Request reason and actors distinguish pending reversal from completed reversal. - name: void kind: collection required: false computed: false notes: Abandonment retains the actor and time. - name: accounting requests kind: collection required: false computed: false notes: >- Approval and reversal retain immutable balanced requests; operational batch postings determine whether they reached the ledger. - name: available and unavailable actions kind: computed required: true computed: true notes: Reads return allowed commands and explanations for withheld approval. - name: version kind: number required: true computed: true notes: >- Financial changes and notes compare versions; dismissals leave the version unchanged. relationships: - to: DOM-ACC-REC-001 cardinality: one-to-many (one to fifty payouts) ownership: >- The explanation owns links and claims; settlement records remain in the outstanding ledger. cross_service: false - to: DOM-ACC-REC-002 cardinality: one-to-many claims; one-to-many manual entries it created ownership: >- The explanation owns links and claims; settlement records remain in the outstanding ledger. cross_service: false - to: DOM-ACC-REC-004 cardinality: one-to-many ownership: The concern retains its own references to affected records. cross_service: false - to: DOM-ACC-REC-005 cardinality: many-to-one per period ownership: Assessment reads the relationship without owning the underlying record. cross_service: false invariants: - id: INV-DOM-ACC-REC-003-01 statement: >- Every payout link and claim shares its reconciliation’s fixed unit, merchant and currency. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-batches.table.ts:reconciliation_batches_link_target_uq - id: INV-DOM-ACC-REC-003-02 statement: >- Finalization requires an exact zero difference recomputed from integer claim and payout amounts. enforced_at: - service - database provenance: documented source: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#4. Assumptions (from the design; each becomes a rule in the catalog if not already) - id: INV-DOM-ACC-REC-003-03 statement: >- Stored lifecycle permits open to finalized or voided, then finalized to reversed. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/services/rules/transitions.ts:BATCH_TRANSITIONS - id: INV-DOM-ACC-REC-003-04 statement: >- Approval seals the record and holdings; reversal permits release, while reversed and voided records remain terminal. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-batches.table.ts:reconciliation_batches_seal_trigger - id: INV-DOM-ACC-REC-003-05 statement: New holdings require an open record and whole-item claim amounts. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-batch-links.table.ts:seal_reconciliation_batch_children - id: INV-DOM-ACC-REC-003-06 statement: >- The default independence requirement excludes preparers; disabling it marks every approval waived. enforced_at: - service provenance: documented source: >- services-accounting:docs/milestones/plans/ACCT-M8-plan.md#D3. Whether the preparer may finalize - id: INV-DOM-ACC-REC-003-07 statement: A reversal approver must differ from the requester. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-batches.table.ts:reconciliation_batches_reversal_approver_check - id: INV-DOM-ACC-REC-003-08 statement: Unique effect keys prevent duplicate accounting requests in the workspace. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-postings.table.ts:reconciliation_postings_event_key_uq - id: INV-DOM-ACC-REC-003-09 statement: >- Immutable requests stay within a unit, contain one to twenty lines and balance per currency at commit. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-postings.table.ts:reconciliation_postings_balance_trigger - id: INV-DOM-ACC-REC-003-10 statement: >- Batch Management writes ledger entries; unreversed operational posting determines request completion. enforced_at: - service provenance: documented source: >- services-accounting:docs/reconciliation/architecture.md#16.2 The route: ledger requests ride in batches (agreed 2026-10-17) - id: INV-DOM-ACC-REC-003-11 statement: >- Collection bounds are ten thousand claims, two hundred lifetime manual entries, fifty payouts and fifty evidence files. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/reconciliation-batches.table.ts:MAX_BATCH_CLAIMS - id: INV-DOM-ACC-REC-003-12 statement: >- Preparation updates totals atomically with its financial changes; finalization can replace counters with recomputed holdings. enforced_at: - service provenance: observed source: >- services-accounting:modules/reconciliation/services/batch-lifecycle/finalize-batch.ts:finalizeReconciliationBatch physical: - accounting.reconciliation_batches - accounting.reconciliation_batch_payouts - accounting.reconciliation_allocations - accounting.reconciliation_dismissals - accounting.reconciliation_postings - accounting.reconciliation_posting_lines - accounting.reconciliation_evidence_files - accounting.reconciliation_events - accounting.idempotency_keys evidence: - >- services-accounting at f47cb263: modules/reconciliation/db/reconciliation-batches.table.ts, reconciliation-batch-links.table.ts, reconciliation-postings.table.ts, reconciliation-events.table.ts, idempotency-keys.table.ts; services/persistence/reconciliation-workspaces.ts, reconciliation-allocations.ts, reconciliation-batch-lifecycles.ts, reconciliation-ledger-postings.ts, reconciliation-dismissals.ts; services/batch-lifecycle/*; services/rules/segregation.ts, batch-status.ts, transitions.ts, posting-plans.ts; services/reconciliation-batches/batch-views.ts; docs/reconciliation/architecture.md §6, §7.3.5 to §7.3.8, §9.3, §14, §16. - >- services-accounting: docs/milestones/plans/ACCT-M8-plan.md (D1, D3, D7, §4; approved 2026-10-22). - >- react-console at baf6dae3: components/accounting/reconciliation/workspace/*.tsx, batches-screen.tsx; lib/accounting/reconciliation/store.tsx. --- # Payout Reconciliation ## What It Models A reconciliation retains the explanation of one or more deposits from the same merchant. Preparation selects effects and records deductions; approval seals the explanation and creates its accounting requests. ## Identity and Attributes The numbered record keeps immutable financial context. Open display states describe preparation, and approval recomputes holdings rather than trusting maintained counters. ## Relationships The explanation owns payout links, settlement claims and dismissals, including retained release history. Manual effects stay in the settlement collection, while concerns and readiness refer to the explanation. ## Invariants The structured invariants define compatibility, exclusive holdings, approval independence, sealing and request integrity. Dismissals have no version effect, and finalization can repair counters from actual holdings. ## How It Is Stored and Shared Batch Management consumes ledger requests and determines their posted status. Close consumes readiness; Reconciliation also hosts shared Accounting request-key infrastructure without owning other modules’ commands. ## Open Design Questions The independence waiver lacks an audited setting command. Contributor eligibility and atomic draft saving remain product decisions.