Skip to content

ADR 0020 — Settlement Source Reconciliation Authority

  • Status: ACCEPTED
  • Task: NS2-024
  • Date: 2026-08-26

Context

T_TRANSACTION and T_TRANSACTION_LIST already own local AP/AR headers, lines and posted amounts. The line schema can retain source UUID, rate-source UUID, billing-preset UUID and line origin, while the Logistics Workspace settlement projection already reads confirmed/closed active rows and separately lists commodity, trucking and Booking-linked packing rate facts. It deliberately does not claim margin.

Current rows do not provide a universal currency, FX, UOM conversion or correction-lineage contract. Inferring those values from display text, the newest rate row or AR - AP would turn missing evidence into accounting fact. Phase 2 needs a reproducible reconciliation boundary, not another posting owner.

Decision

The existing settlement module plus db-mysql adapter own one read-only reconciliation projection. The existing Billing transaction lifecycle remains the sole local AP/AR mutation owner.

  1. A posted fact is an active T_TRANSACTION_LIST row under an active T_TRANSACTION header whose type is AP or AR and status is CONFIRMED or CLOSED. TL.AMOUNT is posting truth; quantity × rate is a comparison, never an overwrite.
  2. Every reconcilable line retains its line UUID, transaction UUID, source class and source UUID. A derived rate additionally requires rate-source class/UUID, revision, line origin and preset UUID when applicable. Missing UUID/provenance is reported as a residual; it is never filled by guessing.
  3. Rate precedence for a newly reviewed line is: explicit reviewed override, then the frozen billing preset selection, then an explicit source rate effective on the transaction issue date. “Latest” is display evidence only. An undated or unversioned rate is UNPROVEN, not silently selected.
  4. Currency and UOM remain source facts. Conversion is permitted only with explicit source and target units plus a versioned FX or UOM factor effective on the issue date. Without all four facts the result is NOT_RECONCILABLE; no default currency, FX=1 or implicit unit equivalence is allowed.
  5. Monetary comparison rounds to two decimal places using half away from zero. The persisted amount, normalized comparison amount, rounding rule and difference are returned independently.
  6. Landed cost is the sum of attributable AP source facts only after source UUID, currency and UOM reconciliation pass. Otherwise its state is NOT_RECONCILABLE. AR - AP remains a source difference and is not named margin. Trade margin remains unapproved and hidden.
  7. Duplicate active (tenant, type, source class, source UUID, service/description) effects are a conflict, not a sum. Correction/reversal uses the existing Billing transaction boundary: preserve the old fact as inactive/reversed and create a replacement UUID with explicit lineage. Until that lineage exists, the projection reports LINEAGE_UNPROVEN and performs no destructive collapse.
  8. NS2-025 may add only the minimum projection fields, deterministic calculation and actual-role evidence needed to expose these states. It may not add a posting service, pricing framework, customer branch, provider effect or trade-margin formula.

Alternatives

Alternative 1 — Treat The Newest Rate As Authority

Rejected. Update order is not an effective-date or posting contract and makes historical totals drift.

Alternative 2 — Recalculate And Replace Posted Amounts

Rejected. It creates a second accounting writer and can erase reviewed overrides and rounding evidence.

Alternative 3 — Add A New Settlement Ledger Or Pricing Service

Rejected. The current transaction lines, provenance columns and settlement projection already cover the immediate reconciliation consumer. A second store would duplicate ownership without a caller.

Alternative 4 — Keep Source Totals Only

Rejected. Totals alone cannot distinguish missing provenance, rate mismatch, currency/UOM residuals, duplicate effects or unreconciled landed cost.

Consequences

  • NS2-025 stays a small read-only vertical over current tables and routes.
  • Missing currency, FX, UOM, rate version and correction lineage remain visible residuals.
  • Existing posted amounts remain unchanged; provider, QBO and payment effects stay separate.
  • Landed cost can be reported only for fully attributable AP facts; margin remains unapproved.

Revisit

Revisit only when an approved Task supplies a real mutation caller plus versioned currency/FX/UOM and correction-lineage storage. At that point extend the existing Billing transaction owner; do not create a parallel settlement writer.

---

Source: new-system/docs/decisions/0020-settlement-source-reconciliation-authority.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.