Chapter 06 - Settlement reconciliation
A Java/Spring Batch reconciliation engine that closes the Arus v1 control loop with deterministic matching, seeded break proof, report balance enforcement, rerun discipline, and gated cloud preparation.
Source: reconciliation/backend origin/main 86f1447; PR #3 merge ad16960; M3 walkthrough reports 32/32 testsv1 break classes detected in demo transcript and seeded integration test
false matches: planted broken records stay out of match rows
report fails unless matched + breaks equals each side line count
Why Selaras
Arus proves postings balance; Selaras checks the settlement file against the Arus read side so missing, duplicated, late, or mismatched settlement records become named operational work.
Source: reconciliation/docs/product-requirements/2026-06-11-v01-selaras-v1-prd.mdWhy Selaras
v1 keeps five break classes as a code enum and ADR-backed contract, so new classes require a deliberate code and architecture decision.
Source: reconciliation/backend/src/main/java/dev/arimu/reconciliation/domain/BreakType.javaBreak taxonomy
| Break class | Report shape | Source |
|---|---|---|
| DUPLICATE_EXTERNAL | External duplicate row, one side counted in the break summary. | reconciliation/backend/build/demo/m3-demo-transcript.txt |
| AMOUNT_MISMATCH | External and internal sides both counted, with the signed delta exposed. | reconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M2SeededBreakIntegrationTest.java |
| UNMATCHED_EXTERNAL | External-only settlement rows remain open for investigation. | reconciliation/backend/src/test/java/dev/arimu/reconciliation/match/MatcherTest.java |
| UNMATCHED_INTERNAL | Internal-only Arus postings remain open for investigation. | reconciliation/backend/src/test/java/dev/arimu/reconciliation/match/MatcherTest.java |
| TIMING_DIFFERENCE | Adjacent-cycle matches are carried forward rather than forced into today's match. | reconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M2SeededBreakIntegrationTest.java |
Engineering leadership
The leadership move was to freeze the M2 contract first, fan out M2a Arus pull and M2b matcher streams over disjoint packages, then converge with the seeded-break gate. Git history shows those as separate commits before the M2 merge.
Commit `2825454` froze domain types, staging interfaces, Arus client boundaries, and guard tests.
Source: git:reconciliation/backend 2825454 feat: freeze m2 reconciliation contractCommit `d267a1b` implemented the HTTP Arus read adapter and pull job into `internal_record`.
Source: git:reconciliation/backend d267a1b feat: implement m2a arus pull jobCommit `ef54a1d` implemented deterministic matching, classification, and reconcile job wiring.
Source: git:reconciliation/backend ef54a1d feat: implement deterministic matcherCommit `09d6f99` added the integration gate that proves every planted break class, zero false matches, and balanced side counts.
Source: git:reconciliation/backend 09d6f99 test: add m2 seeded break gateCommit `179b786` preserved terminal operator decisions during supersede, made aging recompute one SQL statement, split break-count gauges per source, quoted CSV, and removed the real project default from cloud prep.
Source: git:reconciliation/backend 179b786 Fix exception supersede review findingsReport and rerun gates
The chained demo prints JSON and CSV report paths for `demo-acquirer` and the integration test asserts both files are written.
Source: reconciliation/backend/src/test/java/dev/arimu/reconciliation/report/ReconReportServiceIntegrationTest.javaThe report service recomputes side counts and throws if matched plus break rows do not equal both external and internal totals.
Source: reconciliation/backend/src/main/java/dev/arimu/reconciliation/report/ReconReportService.javaSame-version reruns wipe and rewrite derived rows; changed files create a new version and supersede only active prior exceptions.
Source: reconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M3ReconciliationIdempotencyIntegrationTest.javaMicrometer exposes match-rate, break-count, and last-run timestamp gauges; the demo transcript shows Prometheus output.
Source: reconciliation/backend/build/demo/m3-demo-transcript.txtHonesty line
Roadmap
One-to-many and many-to-one settlement are the documented v2 extension once a real source needs split or batched settlement.
Source: reconciliation/docs/adr/2026-06-11-v01-adr-003-matching-and-break-model.mdADR-002 keeps v1 on a scheduled read-API pull, with Arus `entry.committed` event consumption deferred for higher-cadence reconciliation.
Source: reconciliation/docs/adr/2026-06-11-v01-adr-002-pull-arus-via-api.mdCloud Run Job and Scheduler commands are generated as a plan only; publishing/deploying remains behind the explicit human gate.
Source: reconciliation/docs/runbooks/2026-06-12-v01-selaras-phase-b-publish-gate.mdArus platform links
Selaras consumes the Arus read side; the ledger case study remains the featured portfolio project.
Source: family-finance/web/src/components/portfolio/portfolioRegistry.tsThe Arus roadmap now marks reconciliation as shipped and points here for Chapter 06 proof.
Source: family-finance/web/src/components/portfolio/arusLedgerCaseStudyData.tsEvidence trail