--- id: DOM-ACC-REC-002 title: Outstanding Settlement Item realises: CON-ACC-REC-002 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-004 custom_fields: none identity: >- A workspace identity identifies the row, and a unique effect key identifies the money movement. Split parts extend the parent’s effect key with a part number. attributes: - name: effect kind kind: enum required: true computed: false notes: >- Captures, refunds, voids, disputes, returns, fees, reserves and adjustments distinguish the effect and constrain its sign. - name: amount kind: money required: true computed: false notes: >- The signed amount is fixed in whole currency minor units; positive money increases the payout. - name: source and effect key kind: text required: true computed: false notes: >- The origin and deterministic key distinguish recorded effects; reconciliation reserves manual keys. - name: 'business unit, merchant account, currency and processor' kind: reference required: false computed: false notes: >- The unit, merchant and currency must agree; processor identity can be absent. - name: causing document kind: reference required: false computed: false notes: >- An item may identify one payment, refund or dispute; payment and refund references are checked. - name: payment method kind kind: enum required: false computed: false notes: Card or electronic check selects the processor timing defaults. - name: occurred at kind: date required: true computed: false notes: >- Occurrence is fixed; manual entries use the start of the payout’s accounting day. - name: eligible on kind: date required: false computed: true notes: >- Eligibility is calculated in the workspace’s zone and is initially absent for an uncleared check. - name: expected settlement on kind: date required: false computed: true notes: >- Expected arrival adds business-day lead time; an untimed reserve may have no expected date. - name: operational batch kind: reference required: false computed: false notes: >- The causing document’s operational batch supports grouping and claim snapshots. - name: processor and bank references kind: collection required: false computed: false notes: 'External processor references can be supplied once, then remain fixed.' - name: note and evidence kind: collection required: false computed: false notes: >- Manual money needs explanatory text or evidence; an adjustment also needs a compatible ledger account. - name: entered in reconciliation kind: reference required: false computed: false notes: This reference identifies the draft that created a manual entry. - name: split parent kind: reference required: false computed: false notes: Parts identify their split original and must sum to its amount. - name: resolution kind: enum required: false computed: false notes: 'Resolution retains its outcome, reason, actor and time.' - name: outstanding state kind: computed required: true computed: true notes: >- Read-time precedence combines resolution, active holder, eligibility, timing and investigation for the requested day. - name: possible payouts kind: computed required: false computed: true notes: >- At most five compatible free payouts are suggested from the expected-date window. - name: version kind: number required: true computed: true notes: Split and resolution commands compare the item version they read. - name: timing rules · bank calendars and processor defaults kind: collection required: true computed: false notes: >- Read-only holiday calendars and timing seeds provide defaults; Books owns merchant overrides and timing bounds. relationships: - to: DOM-ACC-REC-003 cardinality: many-to-one active claim (any number of released claims) ownership: >- The explanation owns its holding references and preserves released history. cross_service: false - to: DOM-ACC-REC-001 cardinality: many-to-many through the claiming reconciliation ownership: >- The association is derived through the explanation or candidate read; neither record owns the other. cross_service: false - to: DOM-ACC-REC-004 cardinality: one-to-many (at most one open overdue problem at a time) 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-002-01 statement: >- A deterministic effect key identifies one item; a matching repeat reuses it and a materially different effect is refused. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_source_key_uq - id: INV-DOM-ACC-REC-002-02 statement: >- Caller-recorded payment, refund and reversal effects share the document’s commit or rollback. enforced_at: - service provenance: documented source: >- services-accounting:docs/reconciliation/architecture.md#6. Reconciliation financial invariants (INV-20) - id: INV-DOM-ACC-REC-002-03 statement: 'Effect kind constrains the sign, and an adjustment must be nonzero.' enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_signed_amount_check - id: INV-DOM-ACC-REC-002-04 statement: >- Database triggers protect financial identity and supplied processor references; service commands fill eligibility dates once. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_write_once_trigger; services-accounting:modules/reconciliation/services/persistence/settlement-item-recordings.ts:markItemEligible - id: INV-DOM-ACC-REC-002-05 statement: An item has one active claim across open and finalized reconciliations. enforced_at: - 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-002-06 statement: >- Split commands require same-sign parts; deferred database checks require their total to equal the original. enforced_at: - service - database provenance: observed source: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_split_trigger - id: INV-DOM-ACC-REC-002-07 statement: >- A manual effect uses a permitted fee, reserve or adjustment kind and retains text or evidence at commit. enforced_at: - database provenance: observed source: >- services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_manual_evidence_trigger - id: INV-DOM-ACC-REC-002-08 statement: >- Outstanding standing is derived for the requested day rather than persisted. enforced_at: - service provenance: documented source: >- services-accounting:docs/reconciliation/architecture.md#12.1 Decision: hybrid (persisted facts, derived timing) - id: INV-DOM-ACC-REC-002-09 statement: Changing timing defaults leaves existing expected dates intact. enforced_at: - service provenance: documented source: >- services-accounting:docs/reconciliation/architecture.md#12.2 Expected settlement date physical: - accounting.settlement_items - accounting.settlement_item_evidence_links - accounting.reconciliation_evidence_files - accounting.bank_holidays - accounting.settlement_lead_times evidence: - >- services-accounting at f47cb263: modules/reconciliation/db/settlement-items.table.ts, reconciliation-evidence.table.ts, bank-holidays.table.ts, settlement-lead-times.table.ts; services/settlement-items/settlement-item-recording.ts, settlement-item-commands.ts; services/persistence/settlement-items.ts, settlement-item-recordings.ts; services/rules/item-kinds.ts, business-days.ts, outstanding-state.ts; modules/transactions/services/payments/ports/settlement-items.ts; docs/reconciliation/architecture.md §5.2, §6, §7.3.2, §12. - >- react-console at baf6dae3: components/accounting/reconciliation/outstanding-screen.tsx; lib/accounting/reconciliation/adapter.ts. --- # Outstanding Settlement Item ## What It Models A settlement item records a single processor money effect that may increase or reduce a later deposit. The same collection supplies matching candidates and the outstanding-money view. ## Identity and Attributes Effect keys prevent repeated observation from creating another item. Financial facts remain fixed, arrival dates are calculated when eligibility is established, and outstanding standing is derived for the requested day. ## Relationships Reconciliations hold items through claims and create manual items within their drafts. Concerns investigate missing arrivals; readiness uses the effects to explain clearing and period positions. ## Invariants The structured invariants distinguish service checks from database constraints. In particular, service logic fills eligibility dates once, while database triggers protect financial identity and external references. ## How It Is Stored and Shared Transactions records effects through Reconciliation’s transaction-bound port. Rhythm supplies timing seeds and holiday calendars; Books owns merchant overrides, and these records have no customer-defined fields. ## Open Design Questions Product must distinguish timing policy from operational defaults. Dispute references remain unchecked, and write-off has no implemented undo command.