$50.00 (default)1
Materiality threshold
differences at or under $50 are timing noise; above becomes a numbered flag
ENGINE 02
SFS-E02-RCN · RECONCILIATION · REV 2026-07-20 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Cash & Debt Reconciliation
Deterministic cash & debt reconciliation, keyed by account number, materiality-gated.
The engine ties each entity's GL cash to the bank ending balance and each GL loan to a 3-part lender total (principal + interest/reserve + late paydown), matching by account number so a figure never lands on the wrong row. Differences at or under a $50 materiality threshold are logged as timing noise; anything larger becomes a numbered flag for review. Every run emits the same 5-section evidence log — a Markdown file and a color-coded Excel workbook. An optional assurance loop restores a drifted package back to the seeded source of record and applies a materiality gate before it ships.
A reconciliation is only as trustworthy as the evidence trail behind it. Every figure on this page re-derives from the public repository — the demo is a command you run, not a claim you take on faith.
Architecture
functional block stack · static overviewSelect a layer
Each layer is an independent stage, from the seeded substrate up to the optional assurance loop. Select a layer for its plain-terms and engineering detail.
Key specifications
at a glance9 (4 cash / 4 debt / 1 skipped)2
Accounts in scope
the fixed seeded scenario across four fictional entities
What it does for you
plain termsReconciling cash and debt means tying every bank and lender movement to the general ledger, explaining the differences, and keeping audit-ready evidence across many entities. Performed by hand the work is repetitive and slow, and the evidence trail comes out inconsistent from month to month. This engine automates the tie-out on a repeatable cadence, builds materiality and escalation into the process so reviewers see signal instead of noise, and produces a consistent, audit-ready evidence log every cycle.
March 2026 base reconciliation7. python -m recon_engine reconciles the seeded March-2026 books: 9 accounts (4 cash, 4 debt, 1 dormant skipped) resolve to 5 clean, 1 timing, 2 flagged. FLAG-001 CASH-1001 (Maple Fund LP) is a -1,875.40 deposit-in-transit; FLAG-002 DEBT-2003 (Cedar Ridge Partners LLC) is a +12,500.00 keying error. The process exits 0.
The 3-part debt formula ties out8. The debt section proves the optional third leg is wired through. DEBT-2000 (Demo Holdings LLC) carries a 7,500.00 late-paydown mirrored GL-to-lender and still ties clean at 0.00; DEBT-2002 (Birchwood Op Co) shows an 18.75 interest accrual booked in GL but not yet on the lender statement, which is under $50 and therefore a yellow timing item, not a flag.
The assurance loop restores a drifted package9. python -m recon_engine.loop --demo injects three faults on baseline-clean accounts: CASH-1002 GL fat-fingered +4,830.25, DEBT-2000 lender statement dropped, DEBT-2001 mis-marked dormant. The loop resyncs those three accounts in three turns (budget 11), driving deviations from 3 to 0. Gross corrective movement of 4,831.25 exceeds the $50 materiality, so the verdict is FLAG with exit 0, and the scenario's genuine flags are left untouched.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded generator. Builds the fictional GL, bank, and lender books with known discrepancies injected.
- Scope & account-number index. Filters out dormant zero-activity rows and indexes each source by account number.
- Variance + 3-part debt total. Computes GL-minus-source for cash, and GL vs the 3-part lender total for debt.
- Materiality classify + flag ids. Labels each line clean, timing, or flagged and numbers the flags.
- 5-section evidence log. Renders Summary / Cash / Debt / Flagged / Notes as Markdown and a color-coded xlsx.
- CLI summary + exit 0. Prints the run summary and flagged list; exits 0 even with flags.
- Baseline reconcile (source of record). Reconciles the pristine seeded dataset once to establish the authoritative outcomes.
- Deviation sensor. Compares each account's current outcome to the baseline and lists what drifted.
- Resync to source. Restores every record the lowest-numbered deviating account owns back to the seeded truth.
- Materiality gate -> verdict + exit code. Once nothing deviates, it decides PASS / FLAG / FAIL and sets the process exit code.
Engineering
- Seeded generator. generate_dataset(seed=20260331) -> SyntheticDataset (gl_records, bank_statements, lender_statements, injected).
- Scope & account-number index. reconcile() loop: _is_zero_activity / dormant -> _skip_line; _index_banks / _index_lenders build {account_number: statement}.
- Variance + 3-part debt total. _reconcile_cash vs bank.ending_balance; _reconcile_debt vs lender_three_part_total; compute_variance rounds to cents.
- Materiality classify + flag ids. classify(): |var| <= 0.005 clean, <= threshold timing, else flag; _assign_flag_ids -> FLAG-001.. across cash then debt.
- 5-section evidence log. render_markdown + write_xlsx (openpyxl, green/yellow/red/grey status fills).
- CLI summary + exit 0. cli.main prints period / materiality / counts / flagged and returns 0 (flags are expected, not failures).
- Baseline reconcile (source of record). assurance_loop: pristine = generate_dataset(seed); baseline = reconcile(pristine); budget = len(gl_records) + 2.
- Deviation sensor. _outcomes() fingerprint (classification + variance + source_label), then deviations(current, baseline) sorted by account.
- Resync to source. resync_account -> _resync_records for gl/bank/lender; books each field change as an Adjustment; removes or restores whole records.
- Materiality gate -> verdict + exit code. total = sum(adjustment magnitudes); not converged -> FAIL (exit 1); total > materiality -> FLAG (exit 0); else PASS (exit 0). verdict_exit_code().
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python -m recon_engine | generate synthetic data, reconcile, write both logs | console summary: period, seed, materiality, in-scope counts, clean/timing/flagged, and the flagged list | 0 | evidence-log.md (committed), output/evidence-log.xlsx (gitignored) |
python run.py | convenience alias for python -m recon_engine (same args) | same console summary | 0 | evidence-log.md, output/evidence-log.xlsx |
python -m recon_engine --threshold 25 | tighten materiality to $25 | borderline variances reclassify between timing and flag | 0 | evidence-log.md (+ xlsx) |
python -m recon_engine --seed 7 | regenerate synthetic data with a different seed | a new byte-deterministic dataset and log | 0 | evidence-log.md (+ xlsx) |
python -m recon_engine --no-xlsx | Markdown only; skip the workbook | console summary without the XLSX line | 0 | evidence-log.md |
python -m recon_engine.loop --demo | inject the drift profile and run the assurance loop | turn-by-turn Markdown; verdict PASS/FLAG/FAIL with gross movement vs materiality | 0 (PASS/FLAG) or 1 (FAIL) | assurance_loop_report.md when --out DIR is given; otherwise stdout only |
python -m pytest -q | run the default test suite (the SWEEP-gated bulk grid is excluded) | pass/fail summary over 7,511 collected tests | 0 on pass | none (.pytest_cache only) |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Tests collected10 | 7,511 tests (default) an exhaustive bulk invariant grid raises this to 162,479 with SWEEP=1 |
| Seeded reconciliation11 | 9 accounts (8 active + 1 skipped; 2 flagged) 5 clean, 1 timing, 2 flagged in the March-2026 seed |
| Loop convergence12 | 3 -> 0 deviations in 3 turns / budget 11 restores three injected faults to the source of record |
| Loop gross correction13 | 4,831.25 USD across 3 booked corrections material, so the verdict is FLAG (converged, exit 0) rather than PASS |
Control characteristics
engineeringPlain terms
The base engine always exits 0 — a flag is an expected reconciliation outcome, not a program failure. The assurance loop adds an automated materiality gate: PASS and FLAG both exit 0 (FLAG surfaces material corrections so a reviewer sees what moved before the package ships), while FAIL exits 1 only on non-convergence. The gate labels and routes the output; it does not stand in for a human sign-off.
Engineering
Deterministic envelope. seeded fictional inputs, offline default mode.
Demo gate. automated-materiality-gate
| Severity | Verdict | Action |
|---|---|---|
| |variance| <= $0.005 (tie tolerance) | clean (green) | note 'ties to source'; no action |
| $0.005 < |variance| <= threshold ($50) | timing (yellow) | comment as timing/noise, expected to clear; not escalated |
| |variance| > threshold | flag (red, FLAG-###) | assign a sequential flag id; escalate for review |
| dormant / zero-activity account | skipped (grey) | skip with a documented note; no reconciliation required |
| loop: converged, total corrections <= materiality | PASS | clean to file; exit 0 |
| loop: converged, total corrections > materiality | FLAG | ship with a note of what moved; exit 0 |
| loop: not converged within the turn budget | FAIL | escalate; exit 1 |
- Deterministic: random.Random(seed) yields byte-identical GL/bank/lender data, so a given seed always reproduces the same log (generate.py; --seed).
- Account-number targeting: every value is resolved by account number in the key column, never by row index, which defeats off-by-one corruption (engine._index_banks / _index_lenders).
- Integer-cent discipline: all money is round(..., 2) at every step (compute_variance, lender_three_part_total, ReconLine fields), with a $0.005 tie tolerance guarding float noise (engine.TIE_TOLERANCE).
- Materiality gate: |variance| <= threshold is timing/noise; above becomes a numbered FLAG-### escalation (engine.classify, _assign_flag_ids).
- 3-part debt formula: the GL loan is reconciled against principal + current_interest_reserve + late_paydown, the optional third leg included (engine.lender_three_part_total).
- Loop fidelity: the assurance loop never invents a number; every correction restores a seeded record, and the settled reconciliation is identical to a pristine run (loop.py).
- Exit contract: the base engine returns 0 even when lines are flagged, since a flag is an expected outcome; the loop returns 1 only on non-convergence (cli.main, loop.verdict_exit_code).
Operating limits
what it refuses to do- It refuses to force a tie on dormant, zero-activity accounts: they are skipped with a documented note rather than reconciled, keeping padding out of the population.14
- The assurance loop refuses to converge by zeroing genuine reconciling items: the scenario's real flags (deposit-in-transit, keying error) are part of the baseline and survive the loop; it restores fidelity to source, not 'all clean'.15
- The loop refuses to invent a number: every correction is a restoration of a seeded source record, so the settled reconciliation is byte-identical to a pristine run.16
See it run
animated overview
Integration
how to run itDistribution: public repository, MIT license.
git clone https://github.com/sophonfinance-wq/finance-automation-portfolio.git && cd finance-automation-portfolio/cash-reconciliation && python -m recon_engine
python -m recon_engine.loop --demo
Substantiation
- 1recon_engine/__init__.py (MATERIALITY_THRESHOLD = 50.0); overridable via --threshold
- 2python -m recon_engine console summary; evidence-log.md summary section
- 3recon_engine/engine.py (lender_three_part_total)
- 4recon_engine/engine.py (TIE_TOLERANCE)
- 5python -m pytest --collect-only -q (cash-reconciliation/); verified 2026-07-20 and pinned in site-datasheets/counts.json
- 6cash-reconciliation/pyproject.toml (openpyxl>=3.1)
- 7README.md 'Real example output'; evidence-log.md summary and flagged sections
- 8README.md debt example table; recon_engine/generate.py (injected late-paydown and timing difference)
- 9README.md 'Reconciliation Assurance Loop'; recon_engine/loop.py (demo_setup, assurance_loop)
- 10python -m pytest --collect-only -q in cash-reconciliation/ (measured, SWEEP unset); pinned in site-datasheets/counts.json
- 11python -m recon_engine console summary (measured, exit 0)
- 12python -m recon_engine.loop --demo (measured)
- 13python -m recon_engine.loop --demo (measured: 4,830.25 GL fat-finger + 1.00 dormant-flag restore)
- 14recon_engine/engine.py (_is_zero_activity, _skip_line); evidence-log.md dormant-account note
- 15recon_engine/loop.py (docstring; demo_setup targets only baseline-clean accounts)
- 16recon_engine/loop.py (resync_account; fields are only ever set back to pristine truth)
Show us where the hours go.
One conversation: you describe the work that consumes your team's month; we tell you plainly what this engine can take over, what it can't, and what a scoped first phase would cost. Your people keep approval authority.
Book a free consultation