10,4071
Tests
the collected checks that pin this engine's behavior
ENGINE 37
SFS-E37-EMD · DEPOSIT TRUST · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Earnest-Money Deposit Trust
Do the ledger, the escrow agent and the loan describe the same money, to the cent?
A residential developer holds each for-sale buyer's earnest money in trust before the unit closes, and it has to prove, unit by unit, that three independent records describe the same money to the cent -- the internal deposit ledger, the escrow agent's open-escrow statement, and the construction-loan paydown register the earnest money is swept into as principal. This engine reads the seven artifacts the deposit record carries -- the deposit ledger, the escrow agent's statement, the loan paydown register, the cancellation register, the segregated trust-account balances, the sales matrix and the reconciliation summary -- and runs twenty-seven deterministic controls over them across ten families. Is the file complete and the ledger cut-off date readable, are the deposit ids unique and every row's fields present, does each row's cash split exactly into an upgrade deposit plus earnest money over non-negative components, do the ledger, the agent and the loan tie three ways per unit at zero variance and complete in both directions, does every swept deposit carry exactly one paydown and every queued deposit none, does each cancellation join a cancelled deposit and split into a retained fee plus a refund that sums to the earnest money, is the earlier sweep reversed once and the fee booked to forfeiture income, is every deposit in one known posting bucket and no closed unit still on the agent's open statement, do the segregated upgrade bank and forfeiture income recompute from the evidence, does each net sale price recompute as price plus a non-positive concession booked against revenue, and do the summary's per-unit variances, exception flags, total variance and bucket totals recompute from the deposits underneath them. It compares every figure with exact ==, holds zero as the only passing value on every reconciliation leg, and never writes to a source artifact.
A pre-close deposit trust looks like the easiest reconciliation on the books: three records of the same buyer money, each footed and internally consistent. That is exactly why it drifts. None of the ways it breaks look wrong on any single page. The escrow agent holds a deposit the ledger never booked, or the books carry pre-close money the agent no longer holds -- each side balances, and only the per-unit tie-out sees the gap. A deposit marked posted has no paydown behind it, one still queued was already swept so the next posting run applies the same money twice, or a cancelled buyer's earlier paydown was never reversed and the loan stays paid down with money that was refunded. And the reconciliation summary -- the variance column, the exception flags, the posting-bucket totals, the trust balances -- is stated on numbers nobody recomputed from the deposits beneath them. The engine rebuilds every determination from the ledger, the agent's record and the loan register through one shared reconciliation kernel and compares with exact ==, holds zero as the only passing variance because a cent is a cent, ships a planted-defect file for every registered control, and states its benchmark as a command rather than a claim. A deposit the agent holds and the books never booked, or a sweep applied twice, is invisible until someone re-derives the money the three records are supposed to share.
Architecture
functional block stack · static overviewSelect a layer
Ten control families run in registry order over each deposit file. The first proves the others had something to read and that the ledger cut-off date is legible, because a control that passes on absent evidence reports assurance it never performed.
Key specifications
at a glance75
Artifacts read
deposit ledger, escrow agent statement, loan paydown register, cancellation register, trust balances, sales matrix, reconciliation summary
What it does for you
plain termsA residential developer receipts each for-sale buyer's earnest money into escrow before the unit closes, splits it from any separate upgrade deposit, and sweeps the earnest money to the construction loan as a principal paydown; if the buyer cancels, the deposit decomposes into a retained termination fee, a refund, and a reversal of that earlier paydown. The trust is proved by three independent records agreeing, unit by unit, to the cent: the internal deposit ledger, the escrow agent's open-escrow statement, and the loan paydown register. Three failures hide inside that, none of which look wrong on any single page. The agent's record and the books disagree -- a deposit the agent holds that the ledger never booked, or pre-close money the ledger carries that the agent no longer holds -- each side internally consistent, the break visible only across them. The sweep drifts from the ledger's own status column -- a posted deposit with no paydown, a queued deposit already swept, a cancelled buyer's paydown never reversed. And the rollup -- the summary's variances, exception flags, bucket totals and trust balances -- is stated on numbers nobody recomputed from the deposits underneath them. None of these are judgment calls. They are equalities and comparisons -- an agent balance against the earnest money the ledger supports, a stated total against its re-derivation, a split against the deposit it decomposes -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks the trust this quarter.
The seeded demo runs every control over every deposit file7. The CLI generates twenty-nine fictional deposit files -- one clean baseline and one carrying each of the twenty-eight planted defects -- then runs all twenty-seven controls over each. The clean file returns PASS with no flags; every defect file returns REVIEW or FAIL and names the control it tripped along with the reason that control exists.
One defect trips exactly one control, and zero has no tolerance band8. Variance is agent-minus-books in integer cents and the only passing value is zero, so a one-cent break is a break. The controls are scoped so a single defect fires one control: a missing sweep trips swp_posted_has_paydown while tie_loan_leg_zero defers the same unit to it, and a paydown a thousand short of its receipt trips tie_loan_leg_zero alone -- each break landing on the control that owns it rather than cascading across the tie-out.
The summary is recomputed, not read back9. A defect edits a unit's stated variance in the reconciliation summary without touching the ledger or the agent's record beneath it. rpt_unit_variance_recomputes rebuilds the variance through the shared kernel and fails, proving the summary is re-derived from the deposits underneath it rather than trusted as stated.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Deposit Files. fictional pre-close deposit files enter the control registry
- Structural Precondition. is the deposit file complete and the ledger cut-off date legible
- Deposit Ledger. are the deposit ids unique and every row's fields present
- Segregation Identity. does each cash amount split into upgrade plus earnest money
- Three-Way Reconciliation. do the ledger, the agent and the loan tie three ways per unit
- Sweep Register. does the sweep match the ledger's own status column
- Cancellation Split. does every cancellation split, book and reverse correctly
- Status and Scope. is every deposit in one known bucket and only pre-close units on the agent
- Segregated Trust Balances. do the upgrade bank and forfeiture income recompute
- Concession Netting. does each net sale recompute from price plus a non-positive concession
- Reconciliation Summary. do the summary's variances, flags and totals recompute from the evidence
- Artifacts and Kernel. the seven artifacts and the shared kernel every rule resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Deposit Files. generate_corpus writes one clean baseline plus one planted-defect file for every registered control, twenty-nine files in total. Only the deposit ledger, the escrow agent's statement, the loan register, the cancellation register and the sales prices are stated; each unit's variance and exception flag, the total variance, the posting-bucket totals, the segregated trust balances and each net sale price are re-derived through the same reconciliation kernel the engine later recomputes with, so the relationships the engine tests are the same relationships that produced the data.
- Structural Precondition. One control. FAILs a file missing any of the seven artifact types or carrying a duplicate, or an unreadable as_of ledger cut-off date, so no downstream rule holds vacuously on absent evidence.
- Deposit Ledger. Two controls: no deposit id appears twice, and every ledger row carries the identity, date, status and amount fields the reconciliation reads.
- Segregation Identity. Two controls: the cash amount equals its upgrade plus earnest-money split, over non-negative components so the identity cannot be faked by moving money between the two streams.
- Three-Way Reconciliation. Four controls: the agent's earnest money ties the ledger at zero variance, every agent unit is on the books and every booked pre-close unit on the agent's statement, and the net loan paydown equals the swept earnest money per unit.
- Sweep Register. Three controls: every swept deposit carries exactly one paydown, every movement joins a coherent ledger deposit, and no deposit still queued need-to-post already carries a paydown.
- Cancellation Split. Four controls: each cancellation joins a cancelled deposit one-to-one, the fee plus refund sums to the earnest money, the earlier sweep is reversed once and exactly, and the fee lands in forfeiture income.
- Status and Scope. Two controls: every deposit sits in exactly one known posting bucket and lifecycle state, and a closed or cancelled unit still on the agent's open statement is flagged as stale escrow.
- Segregated Trust Balances. Two controls: the segregated upgrade-deposit bank balance ties the upgrade portion of every active, unclosed deposit, and forfeiture income to date ties the sum of the retained termination fees.
- Concession Netting. Three controls: the net sale price equals sales price plus concession, the concession is stored non-positive, and it is booked against revenue rather than a construction cost code.
- Reconciliation Summary. Four controls: each unit variance recomputes through the shared kernel, each exception flag ties its variance, the total variance foots the unit rows, and the three posting-bucket totals recompute from the ledger.
- Artifacts and Kernel. The deposit ledger carries each deposit's id, unit, buyer, receipt date, upgrade and earnest-money split, posting status and lifecycle state; the escrow agent's statement carries the earnest money held per open unit; the loan paydown register carries the principal paydowns and reversals; the cancellation register carries each forfeiture split; the trust-account balances carry the segregated upgrade bank and forfeiture income; the sales matrix carries the net-sale line; and the reconciliation summary carries the stated variances, flags and totals. Every tie-out, sweep, cancellation, trust-balance and rollup control resolves against these through the shared reconciliation kernel in deposit_engine.reconcile.
- Verdict and Findings. Findings roll up per deposit file: any FAIL is FAIL, FLAGs without FAILs are REVIEW, clean is PASS. The CLI exit code is the verdict, so a pipeline can gate on it. Reports carry no timestamps or absolute paths, which is what makes the committed report diffable.
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python run.py | regenerate the seeded fictional corpus, run all twenty-seven controls, write both reports | per-file verdicts and every actionable finding, then the overall verdict | 2 for the bundled corpus, which carries a planted defect for every control by design | emd_report.json, emd_report.md, samples/ |
python -m deposit_engine samples | analyze an existing folder of deposit files without regenerating it | per-file verdicts and findings | 0 PASS / 1 REVIEW / 2 FAIL / 3 usage | none unless --json or --md is passed |
python -m deposit_engine samples --generate --quiet | regenerate the corpus and print only the overall verdict | a single verdict line | 0 PASS / 1 REVIEW / 2 FAIL / 3 usage | samples/ |
python -m pytest deposit_engine/tests -q | run the full test suite for this engine | 10407 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,407 tests collected live collection from the engine directory |
| Registered controls11 | 27 controls counted from the registry, not from documentation |
| Planted defects12 | 28 defect files every registered control has at least one file that trips it |
| Control coverage13 | 100 percent of controls with a planted defect no control ships without a file demonstrating it firing |
Control characteristics
engineeringPlain terms
The engine has no write path and therefore no autonomy to gate. It produces findings; a person decides whether a deposit is carried into the trust reconciliation and whether a completeness gap or over-release is chased.
Engineering
Deterministic envelope. seeded fictional inputs, read-only operation, offline default mode.
Demo gate. FAIL on the bundled corpus, by design -- it carries a planted defect for every registered control
| Severity | Verdict | Action |
|---|---|---|
| No findings above PASS | PASS | carry the mechanically clean deposit file into the documented sign-off and reconciliation review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; a closed or cancelled unit still on the agent's open-escrow statement and an exception flag that does not tie its recomputed variance both land here |
| One or more FAIL | FAIL | the deposit or figure is not carried into the trust reconciliation until the failing control is cleared -- a nonzero three-way variance, a missing or premature sweep, a forfeiture split that does not sum, or a rollup that does not recompute |
- Read-only: deposit files are parsed and never written back, so the engine cannot introduce the break it reports.
- Integer cents throughout, compared with exact ==; there is no tolerance band on any reconciliation leg, and a variance of one cent is reported as a variance.
- A figure that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one row it was read on, rather than being coerced into the number the engine is meant to audit.
- One reconciliation kernel: the controls and the generator share deposit_engine.reconcile, so a stated determination cannot disagree with the logic that produced it.
- Controls are scoped to own their breaks: a structurally broken sweep is left to the swp_ and cxl_ controls and an unclassifiable row to sts_valid_bucket, so one defect fires one control instead of cascading across the tie-out.
- Deterministic and byte-stable: same inputs produce the same findings in the same order, with no timestamps or absolute paths in any output.
- Absent evidence is never a passing control; a missing artifact fails completeness rather than letting the controls that read it pass unread.
Operating limits
what it refuses to do- The engine never receipts a deposit, posts a sweep, books a cancellation, moves money, or writes to a source artifact. It reads the deposit file and stops.14
- It reads the seven artifacts the deposit record emits. It does not connect to the escrow agent's system, the construction lender, the trust bank or the general ledger.15
- It proves the three records tie to the cent; it does not prove the escrow agent's own balance is correct, that a closing actually occurred, or that a cancellation was properly authorised. That judgment is a reviewer's.16
- It confirms a fee lands in forfeiture income and a concession against revenue; it does not decide whether those account codes are the correct ones for this developer's chart of accounts.17
- It takes the deposit ledger, the agent's statement and the loan register at face value: it reconciles what they state, not whether the underlying cash actually moved. All shipped data is fictional and the reporting period is set in a fictional future.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
python run.py
python -m pytest deposit_engine/tests -q
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (deposit-trust-automation/)
- 2len(deposit_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in deposit_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(deposit_engine.model.DOC_TYPES)
- 6deposit_engine/tests boundary tests on the cent
- 7python run.py (deposit-trust-automation/); deposit_engine/tests planted-defect suite
- 8deposit_engine/generate.py DEFECTS sweep_missing / paydown_leg_short; deposit_engine/tests boundary tests on the cent
- 9deposit_engine/generate.py DEFECTS summary_variance_wrong -> rpt_unit_variance_recomputes
- 10python -m pytest --collect-only -q -o addopts= (deposit-trust-automation/)
- 11len(deposit_engine.engine.REGISTRY)
- 12len(deposit_engine.generate.DEFECTS)
- 13deposit_engine/tests: every registered rule has a planted defect
- 14deposit-trust-automation/README.md and deposit_engine read-only / determinism tests
- 15deposit_engine/model.py DOC_TYPES
- 16deposit_engine/engine.py tie_ and cxl_ families
- 17deposit_engine/engine.py cxl_fee_account and net_concession_account
- 18deposit_engine/generate.py
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