7,4981
Tests
the collected checks that pin this engine's behavior
ENGINE 05
SFS-E05-SRP · CROSS-BORDER TAX · REV 2026-07-20 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Tax Surplus / ACB
Foreign-affiliate surplus pools and ACB, re-derived to a human gate
Tax Surplus / ACB rolls seeded fictional foreign-affiliate facts through per-entity, per-year surplus pools, a distribution waterfall, tier elevation, capital-event-only ACB, and per-layer FX. It emits traceable workpapers, independently rechecks structural identities, and can drive a drifted workpaper set back to a clean tie-out while reserving material changes for human review.
The public package exposes its intermediates, its reconciliation identities, and the exact commands behind the page. Its control claims can be re-run from the repository instead of accepted on presentation alone.
Architecture
functional block stack · static overviewSelect a layer
Each layer has one duty: source facts feed the calculation, the harness challenges its exposed intermediates, and the bounded loop stops at a human-review boundary.
Key specifications
at a glanceWhat it does for you
plain termsForeign-affiliate surplus and adjusted cost base are not one ending balance. They are connected roll-forwards across entities, years, ownership percentages, distributions, capital events, and exchange-rate layers. A spreadsheet can still look orderly while a stale opening, unsupported elevation, overdrawn pool, or mis-keyed ACB breaks the structure. This engine makes those mechanics explicit and gives a separate harness enough exposed detail to re-derive them.
A clean default run proves every implemented identity7. The seeded FY2021-2024 structure runs through the engine and the --check gate. The current repository reports Reconciliation: OK with 212 of 212 identity-check instances passing and exits 0.
Per-layer FX exposes a basis result hidden by one closing rate8. In the seeded Cedar Mezz example, a 2023 contribution of 35,502.71 is returned in 2024 at a different rate. Closing USD ACB and the single-rate CAD amount are both zero, while the event-by-event CAD layers net to (660.35). The functional-currency layers still tie to the engine.
The demo clears seeded drift but does not conceal material corrections9. The built-in loop profile starts with six reconciliation breaks. It locks FY2021, FY2022, and FY2023 in three turns, reducing breaks 6 -> 4 -> 2 -> 0. Four booked adjustments total CAD 107,088.50, above the CAD 1,000.00 default materiality, so the converged run returns FLAG for human review and exits 0.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Fictional Source Facts. seeded entities, years, ownership, capital events, distributions, and FX
- SurplusEngine. rolls surplus pools and ACB forward
- Workpapers + Workbook. writes per-entity workpapers, summaries, FX analysis, reconciliation, and optional Excel
- Independent Reconciliation. re-derives the identities and reports any break
- Bounded Remediation Loop. settles the earliest failing year and rechecks
- Human Review Boundary. reviews material changes or an unresolved failure
Engineering
- Fictional Source Facts. generate_structure returns Structure plus YearFacts from a reproducible seed
- SurplusEngine. bottom-up yearly computation; waterfall, elevation, ACB, and closing balances
- Workpapers + Workbook. report.py and workbook.py render the engine's exposed inputs, intermediates, and balances
- Independent Reconciliation. named checks compare expected and actual values within the implemented tolerance
- Bounded Remediation Loop. replaces drifted rows with authoritative engine results, journals field changes, locks the year, and repeats within a turn budget
- Human Review Boundary. FLAG is converged but material and requires review before sign-off; FAIL is a non-converged escalation
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python -m surplus_engine --start 2021 --end 2024 | run the default fictional structure and print the consolidated summary | Markdown summary on stdout | 0 for a valid run | none unless --out is supplied |
python -m surplus_engine --start 2021 --end 2024 --out out | write the traceable workpaper package | consolidated summary plus per-entity, FX-layer, and reconciliation reports | 0 for a valid run | out/workpaper_<ENTITY>.md, consolidated_summary.md, fx_layer_analysis.md, reconciliation_report.md |
python -m surplus_engine --start 2021 --end 2024 --out out --xlsx | add the Excel representation to the report package | the Markdown package plus surplus_model.xlsx | 0 for a valid run | out/surplus_model.xlsx and the Markdown reports |
python -m surplus_engine --start 2021 --end 2024 --check | run the reconciliation harness as a process gate | Reconciliation: OK (212/212 identity checks pass) on the default seeded run | 0 when all checks pass; 1 on any identity break | none unless --out is supplied |
python -m surplus_engine --seed N | select a reproducible fictional-data seed | consolidated summary for the selected seeded structure | 0 for a valid run | none unless --out is supplied |
python -m surplus_engine --exempt-cap FRACTION | set the configurable exempt-distribution cap within 0..1 | summary using the selected cap | 0 when valid; 2 outside 0..1 | none unless --out is supplied |
python -m surplus_engine.loop --demo --out out | inject the built-in drift profile and run bounded remediation | FLAG after three turns on the default demo | 0 because FLAG is converged | out/assurance_loop_report.md and out/assurance_loop.html |
python -m surplus_engine.loop --demo --budget 0 | demonstrate budget exhaustion without a remediation turn | FAIL with the seeded breaks unresolved | 1 | none unless --out is supplied |
python -m surplus_engine.loop --materiality CAD_AMOUNT | set the threshold that separates a converged PASS from FLAG | PASS or FLAG after reconciliation converges | 0 when converged; 1 if the turn budget is exhausted | none unless --out is supplied |
python -m pytest -q | run the engine test suite | pytest session summary | 0 when green | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 7,498 tests collected |
| Default structural gate11 | 212 / 212 identity checks pass |
| Seeded drift remediation12 | 3 turns; breaks 6 -> 4 -> 2 -> 0 |
| Per-layer FX sign difference13 | CAD (660.35) per-layer ACB versus CAD 0.00 at one closing rate |
Control characteristics
engineeringPlain terms
The loop can restore structural consistency, but a FLAG requires a person to review material booked adjustments before sign-off, and a FAIL escalates without claiming convergence.
Engineering
Deterministic envelope. seeded fictional inputs, offline default mode.
Demo gate. PASS and FLAG exit 0; FAIL exits 1
| Severity | Verdict | Action |
|---|---|---|
| Converged; booked adjustments at or below materiality | PASS | clean to present for sign-off; exits 0 |
| Converged; booked adjustments above materiality | FLAG | human reviews what changed before sign-off; exits 0 |
| Not converged within the turn budget | FAIL | escalate with structural breaks unresolved; exits 1 |
- Seeded fictional inputs make the public run reproducible without client or employer data.
- Surplus elevation occurs only when a subsidiary distributes and only at its ownership percentage; operating income alone does not elevate.
- ACB changes only for capital contributions and applied returns of capital; an excess return surfaces as a deemed gain and ACB is floored at zero.
- The reconciliation harness independently recomputes conservation, waterfall, continuity, elevation, and ACB FX-layer identities from exposed intermediates.
- A settled loop result is built from the same authoritative engine re-derivation as a clean run, with every changed tracked field recorded as an adjustment.
Operating limits
what it refuses to do- The repository package is a fictional reference implementation over generated entities, facts, and FX rates; it does not reproduce a client or employer methodology or dataset.14
- The default 0.60 exempt-distribution cap is explicitly a fictional, configurable modeling constraint, not a claim that one ceiling applies to every real tax fact pattern.15
- The --check gate proves the structural identities implemented in reconcile.py within its 0.02 tolerance; it does not replace tax judgment or human approval.16
- The loop remediates only by restoring source-derived engine values. It does not invent support for a value, and a non-converged run returns FAIL for escalation.17
See it run
brand animation
Integration
how to run itDistribution: public repository, MIT license.
git clone https://github.com/sophonfinance-wq/finance-automation-portfolio.git && cd finance-automation-portfolio/tax-surplus-engine && python -m surplus_engine --start 2021 --end 2024 --check
python -m surplus_engine.loop --demo --out out
Substantiation
- 1py -3 -m pytest --collect-only -q -o addopts= (tax-surplus-engine/); verified 2026-07-20 and pinned in site-datasheets/counts.json
- 2tax-surplus-engine/surplus_engine/cli.py -- --start defaults to 2021 and --end defaults to 2024
- 3tax-surplus-engine/surplus_engine/generate.py -- DEFAULT_SEED
- 4tax-surplus-engine/surplus_engine/model.py -- POOL_ORDER; surplus_engine/engine.py -- run_waterfall
- 5py -3 -m surplus_engine --start 2021 --end 2024 --check; reproduced 2026-07-20
- 6tax-surplus-engine/surplus_engine/loop.py -- _verdict and verdict_exit_code
- 7py -3 -m surplus_engine --start 2021 --end 2024 --check (tax-surplus-engine/); reproduced 2026-07-20
- 8tax-surplus-engine/README.md -- Per-layer FX; surplus_engine/fx.py -- acb_fx_reconciliations
- 9py -3 -m surplus_engine.loop --demo (tax-surplus-engine/); reproduced 2026-07-20; surplus_engine/loop.py -- DEMO_FAULTS and DEFAULT_MATERIALITY_CAD
- 10py -3 -m pytest --collect-only -q -o addopts= (tax-surplus-engine/); verified 2026-07-20 and pinned in site-datasheets/counts.json
- 11py -3 -m surplus_engine --start 2021 --end 2024 --check; reproduced 2026-07-20
- 12py -3 -m surplus_engine.loop --demo; reproduced 2026-07-20
- 13tax-surplus-engine/README.md -- seeded Cedar Mezz per-layer FX example; surplus_engine/fx.py
- 14tax-surplus-engine/README.md -- confidentiality posture; surplus_engine/generate.py
- 15tax-surplus-engine/surplus_engine/engine.py -- EXEMPT_CAP comment; surplus_engine/cli.py -- --exempt-cap
- 16tax-surplus-engine/surplus_engine/reconcile.py -- DEFAULT_TOLERANCE and reconcile; README.md -- human gate
- 17tax-surplus-engine/surplus_engine/loop.py -- _settle_year, assurance_loop, and _verdict
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