---
id: ADR-ACC-REC-002
title: Settlement Items Are Written in the Causing Transaction
product_area: accounting
module: reconciliation
revision: 2
status: proposed
design_intent: confirmed
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
decision: >-
  Record document-caused settlement effects through a function that joins the
  caller’s existing transaction.
constrains:
  - DOM-ACC-REC-002
  - WF-ACC-REC-001
  - SVC-ACC-REC-reconciliation
origin: >-
  ACCT-M8 plan §4 assumptions and D10, approved by Andrew 2026-10-22;
  architecture §6 INV-20
alternatives:
  - option: Build the ledger entirely from source-document reads.
    why_not: >-
      Manual fees and reserves lack matching documents, and arrival timing needs
      retained facts.
  - option: Create effects from asynchronous document notifications.
    why_not: >-
      Delayed or failed handling would separate visible outstanding money from
      committed document effects.
consequences:
  - >-
    Eligible recording can refuse the document change when timing is
    unavailable.
  - >-
    Transactions uses a replaceable port with an explicit Reconciliation
    contract.
  - >-
    Future imports should reconcile effect identity rather than create a
    separate competing money ledger.
supersedes: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/reconciliation/services/settlement-items/settlement-item-recording.ts;
    modules/transactions/services/payments/ports/settlement-items.ts;
    docs/reconciliation/architecture.md §5.2, §6, §9.4.
---
# Settlement Items Are Written in the Causing Transaction

## Context

A retained outstanding effect must agree with the document change that created it.

## Decision

Record document-caused settlement effects through a function that joins the caller’s existing transaction.

## Alternatives Considered

Build the ledger entirely from source-document reads. Manual fees and reserves lack matching documents, and arrival timing needs retained facts.

Create effects from asynchronous document notifications. Delayed or failed handling would separate visible outstanding money from committed document effects.

## Consequences

Eligible recording can refuse the document change when timing is unavailable. Transactions uses a replaceable port with an explicit Reconciliation contract. Future imports should reconcile effect identity rather than create a separate competing money ledger.