Back to portfolio

Chapter 06 - Settlement reconciliation

Selaras - Settlement Reconciliation

v1 shipped

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 tests
Proof stripEvidence trail
Selaras reconciliation flowSettlement files and Arus records flow through ingest, matching, break classification, and balanced reports.parsestagecomparesummarizematchedbreaksSettlement fileexternal linesIngest jobrun versionArus read sideHTTP pullMatcherone-to-oneReport jobJSON + CSVMatch rowsdeterministic pairsBreak rowsclosed taxonomyInvariant: matched + break rows must account for both external and internal line counts.
5/5

v1 break classes detected in demo transcript and seeded integration test

0

false matches: planted broken records stay out of match rows

Balance

report fails unless matched + breaks equals each side line count

Why Selaras

Assurance after the ledger

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.md

Why Selaras

Closed taxonomy, not a vague mismatch bucket

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.java

Break taxonomy

Every v1 break has a named operational meaning.

Break classReport shapeSource
DUPLICATE_EXTERNALExternal duplicate row, one side counted in the break summary.reconciliation/backend/build/demo/m3-demo-transcript.txt
AMOUNT_MISMATCHExternal and internal sides both counted, with the signed delta exposed.reconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M2SeededBreakIntegrationTest.java
UNMATCHED_EXTERNALExternal-only settlement rows remain open for investigation.reconciliation/backend/src/test/java/dev/arimu/reconciliation/match/MatcherTest.java
UNMATCHED_INTERNALInternal-only Arus postings remain open for investigation.reconciliation/backend/src/test/java/dev/arimu/reconciliation/match/MatcherTest.java
TIMING_DIFFERENCEAdjacent-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

Contract-first fan-out, convergence gate.

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.

Shared contract

Commit `2825454` froze domain types, staging interfaces, Arus client boundaries, and guard tests.

Source: git:reconciliation/backend 2825454 feat: freeze m2 reconciliation contract

M2a Arus pull

Commit `d267a1b` implemented the HTTP Arus read adapter and pull job into `internal_record`.

Source: git:reconciliation/backend d267a1b feat: implement m2a arus pull job

M2b matcher

Commit `ef54a1d` implemented deterministic matching, classification, and reconcile job wiring.

Source: git:reconciliation/backend ef54a1d feat: implement deterministic matcher

Seeded convergence gate

Commit `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 gate

Review findings fixed

Commit `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 findings

Report and rerun gates

The report is allowed to fail before the operator is allowed to believe it.

JSON and CSV reportJob

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.java

Balance enforcement

The 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.java

Rerun discipline

Same-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.java

Metrics surface

Micrometer exposes match-rate, break-count, and last-run timestamp gauges; the demo transcript shows Prometheus output.

Source: reconciliation/backend/build/demo/m3-demo-transcript.txt

Honesty line

Useful constraints stay visible.

Matching is one-to-one only in v1; grouped one-to-many settlement remains v2 work.
Ambiguous multi-candidate cases degrade to paired unmatched breaks; Selaras never force-matches equal candidates.
The demo evidence uses FixtureArusClient by default, not production settlement data.
There is no operator UI in v1; the report is JSON/CSV by design.
Cloud Run job preparation is scripted but gated, not live.
Source: reconciliation/docs/adr/2026-06-11-v01-adr-003-matching-and-break-model.md; reconciliation/docs/runbooks/2026-06-12-v01-selaras-m3-walkthrough.md; reconciliation/docs/runbooks/2026-06-12-v01-selaras-phase-b-publish-gate.md

Roadmap

The next work is named without pretending it already shipped.

Grouped matching

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.md

Event-driven Arus mirror

ADR-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.md

Cloud Run job

Cloud 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.md

Arus platform links

Selaras ships beside Arus, not above it.

Read Arus ledger

Selaras consumes the Arus read side; the ledger case study remains the featured portfolio project.

Source: family-finance/web/src/components/portfolio/portfolioRegistry.ts
Open Arus roadmap

The Arus roadmap now marks reconciliation as shipped and points here for Chapter 06 proof.

Source: family-finance/web/src/components/portfolio/arusLedgerCaseStudyData.ts

Evidence trail

Every public claim points to a real artifact.

  1. Phase-0 evidence SAfamily-finance/docs/docs/system-analysis/2026-06-12-v01-selaras-case-study-evidence-sa.md
  2. PR #3 merge historygit:reconciliation/backend origin/main ad16960 Merge pull request #3
  3. Current Selaras main with publish gategit:reconciliation/backend origin/main 86f1447 docs: add phase b publish gate
  4. PR #3 review-fix commitgit:reconciliation/backend 179b786 Fix exception supersede review findings
  5. M3 compose demo transcriptreconciliation/backend/build/demo/m3-demo-transcript.txt
  6. M2 seeded-break integration testreconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M2SeededBreakIntegrationTest.java
  7. Matcher unit testsreconciliation/backend/src/test/java/dev/arimu/reconciliation/match/MatcherTest.java
  8. Report service balance enforcementreconciliation/backend/src/main/java/dev/arimu/reconciliation/report/ReconReportService.java
  9. Report integration testreconciliation/backend/src/test/java/dev/arimu/reconciliation/report/ReconReportServiceIntegrationTest.java
  10. M3 rerun and supersede integration testreconciliation/backend/src/test/java/dev/arimu/reconciliation/reconcile/M3ReconciliationIdempotencyIntegrationTest.java
  11. M2 parallel handover promptreconciliation/docs/implementation-plans/2026-06-12-v01-selaras-m2-parallel-handover-prompt.md
  12. M2 walkthrough reviewer verificationreconciliation/docs/runbooks/2026-06-12-v01-selaras-m2-walkthrough.md
  13. M3 walkthroughreconciliation/docs/runbooks/2026-06-12-v01-selaras-m3-walkthrough.md
  14. Phase B publish gatereconciliation/docs/runbooks/2026-06-12-v01-selaras-phase-b-publish-gate.md
  15. Matching ADRreconciliation/docs/adr/2026-06-11-v01-adr-003-matching-and-break-model.md
  16. Default fixture Arus clientreconciliation/backend/src/main/java/dev/arimu/reconciliation/arus/DemoFixtureArusClient.java
  17. Portfolio registryfamily-finance/web/src/components/portfolio/portfolioRegistry.ts
  18. Arus roadmap datafamily-finance/web/src/components/portfolio/arusLedgerCaseStudyData.ts