---
id: WF-ACC-REC-001
title: Record a settlement item with the money movement that caused it
trigger: >-
  Payment processing invokes the settlement port for a processor capture,
  refund, void, return or check clearing.
product_area: accounting
module: reconciliation
revision: 2
status: draft
design_intent: confirmed
origin: >-
  ACCT-M8 plan §4 assumptions (one settlement item per money effect, written in
  the causing transaction) and D10, approved by Andrew 2026-10-22;
  services-accounting docs/reconciliation/architecture.md §6 INV-20
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
implements:
  - CAP-ACC-REC-005
moves:
  - STATE-ACC-REC-004
crosses:
  - SVC-ACC-REC-reconciliation
idempotency: >-
  Effect keys reuse matching observations and reject materially different
  effects. Eligibility repeats return the existing dates.
concurrency: >-
  A unique workspace effect key converges concurrent inserts. Both recording and
  eligibility require the caller’s existing transaction.
hops:
  - 'n': 1
    actor_or_service: 'Transactions payment, refund or reversal command'
    action: >-
      Apply the document effect and invoke the settlement port in the same
      transaction.
    anchor: >-
      services-accounting:modules/transactions/services/payments/ports/settlement-items.ts
    seam: sync
    on_failure: >-
      A settlement refusal propagates to the document command and rolls back its
      transaction.
    left_inconsistent: Neither document change nor settlement effect commits.
    observer: The calling document operation reports the error.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/payments/ports/settlement-items.ts
  - 'n': 2
    actor_or_service: Reconciliation settlement recording
    action: >-
      Require an existing transaction and validate effect identity, financial
      compatibility and amount sign.
    anchor: >-
      services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:recordSettlementItem
    seam: sync
    on_failure: Validation throws to the caller.
    left_inconsistent: No partial financial write survives.
    observer: The caller receives the refusal.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:recordSettlementItem
  - 'n': 3
    actor_or_service: Reconciliation settlement recording
    action: >-
      Calculate eligibility and expected arrival using local cutoff, lead time
      and the bank calendar.
    anchor: 'services-accounting:modules/reconciliation/services/rules/business-days.ts'
    seam: sync
    on_failure: Missing timing prevents recording an eligible effect.
    left_inconsistent: The causing transaction rolls back.
    observer: The document caller sees the configuration problem.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-item-recordings.ts:insertSettlementItem
  - 'n': 4
    actor_or_service: Accounting database
    action: >-
      Insert the effect or reuse the matching effect key, subject to database
      constraints.
    anchor: >-
      services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_source_key_uq
    seam: sync
    on_failure: A database refusal aborts the caller’s transaction.
    left_inconsistent: No partial business result persists.
    observer: The mapped database error reaches the caller.
    provenance: observed
    source: 'services-accounting:modules/reconciliation/db/settlement-items.table.ts'
  - 'n': 5
    actor_or_service: Transactions electronic-check clearing
    action: >-
      On check clearing, fill the effect’s eligibility and expected arrival
      dates if still absent.
    anchor: >-
      services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:markSettlementItemEligible
    seam: sync
    on_failure: An eligibility error aborts the clearing transaction.
    left_inconsistent: The check and timing update do not commit separately.
    observer: The clearing operation reports failure.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/settlement-items/settlement-item-recording.ts:markSettlementItemEligible
branches:
  - Offline payments do not create processor settlement effects.
  - Dispute references currently have no database target check.
waits: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/reconciliation/services/settlement-items/settlement-item-recording.ts;
    services/persistence/settlement-item-recordings.ts;
    services/rules/business-days.ts, item-kinds.ts;
    modules/transactions/services/payments/ports/settlement-items.ts;
    docs/reconciliation/architecture.md §6, §9.4, §12.2.
controls: [TC-IAM-001, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-002, TC-LOG-003, TC-LOG-005, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002]
---
# Record a settlement item with the money movement that caused it

## What It Does

Processor payment effects enter the outstanding ledger through the document transaction. Repeated observation finds the same effect rather than another amount to reconcile.

## The Flow

```mermaid
sequenceDiagram
  participant T as Transactions command
  participant R as Settlement recording
  participant D as Accounting database
  T->>D: begin transaction, change the payment or refund
  T->>R: record the effect (same transaction)
  R->>R: validate, compute eligibility and expected day
  R->>D: insert or find by effect key
  D-->>T: commit both, or roll back both
  Note over T,R: an electronic check is marked eligible the same way when it clears
```

## When Something Fails

A recording error rolls back the document effect together with its settlement item. No asynchronous retry or compensation repairs a partially committed pair; missing timing instead prevents eligible recording.

## Open Design Questions

Dispute validation and the ownership of timing policy remain unresolved. Imports are deferred and do not establish a running workflow.