10,4491
Tests
the collected checks that pin this engine's behavior
ENGINE 22
SFS-E22-WFL · EQUITY WATERFALL · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Equity Waterfall & JV Promote
Does the schedule pay what the agreement promises?
A real-estate joint venture pools an investor's and a developer's capital, accrues a preferred return on it month by month, then distributes the sale proceeds down a contractual waterfall whose tiers pay in a strict order and whose upper tiers split the upside on a promote. Every number in that chain is derived from the ones above it, so a single wrong figure -- a mis-compounded month of preferred return, a tier paid out of order, a pari-passu split struck off the wrong weights, a promote entered as though the hurdle were already cleared -- travels silently to the developer's carry and the investor's multiple, and none of it looks wrong in a spreadsheet. This engine reads the seven artifacts a distribution emits -- the deal terms, the member register, the capital ledger, the waterfall schedule, the dilution worksheet, the returns summary and the loan covenant -- and runs thirty deterministic controls over them in registry order. Is the deal file complete and the review month legible; is the member register sound and the venture a well-formed two sides; does each preferred-return balance recompute from the contribution history compounded monthly; does each capital account roll forward and zero out; do the tiers pay in the contractual order and split pari passu on the balances; is the hurdle boundary re-solved from the investor's contributions; do the promote splits sum to 100% and does the carry tie its upper-tier receipts; are the member and default loan rates sound and the loan repaid off the top before any distribution; does the capital-call dilution recompute by its own named method; is every distributed cent accounted for with no leakage and none paid beyond the proceeds available; and does the realized-returns table -- equity multiple, preferred return, profit split -- recompute from the waterfall beneath it rather than being read back as an assertion. It rebuilds every figure through the one shared arithmetic kernel that also produced the data, compares with exact integer-cent equality and no tolerance band, and never writes to a source artifact.
A JV waterfall is a chain of dependent computations in which a wrong number early travels silently to the bottom line, and the three ways it goes wrong all look right in a folder of worksheets. The accrual drifts: the preferred return is meant to compound monthly on unreturned capital, and a single mis-set month, or simple interest where the agreement says compound, moves every downstream tier and the promote with it. The split leaks: a tier pays out of order, a pari-passu split is struck off the wrong weights, or the promote tier is entered as though the hurdle were already cleared, and the developer's carry is larger than the contract earns. The summary asserts: the realized-returns table reports an equity multiple, a preferred return and a profit split that nobody recomputed from the waterfall underneath it. The engine rebuilds every accrued balance, every tier allocation, every promote dollar and every reported return from the contribution history through the same kernel that generated the data, compares with exact integer-cent equality, ships a planted-defect deal file for every registered control, and states its benchmark as a command rather than a claim. It is a re-derivation engine, not a negotiation: it takes the executed agreement's mechanics as given and asks only whether the money the schedule pays is the money the agreement promises.
Architecture
functional block stack · static overviewSelect a layer
Thirteen control families run in registry order over each deal file, following the dependency chain from the base facts to the reported return. The first proves the others had something to read and that the review month is legible, because a control that passes on absent evidence reports assurance it never performed.
Key specifications
at a glance75
Artifacts read
deal terms, member register, capital ledger, waterfall schedule, dilution worksheet, returns summary, loan covenant
What it does for you
plain termsA real-estate joint venture pools an investor's and a developer's capital, accrues a preferred return on it month by month, then distributes the sale proceeds down a contractual waterfall whose tiers pay in a strict order and whose upper tiers split the upside between the two on a promote. Every one of those numbers is derived from the ones above it, so a wrong figure early travels silently to the developer's carry and the investor's multiple, and three failures hide inside that, none of which look wrong in a folder of worksheets. The accrual drifts: the preferred return is meant to compound monthly on unreturned capital, and a single mis-set month, or simple interest where the agreement says compound, moves every downstream tier and the promote with it. The split leaks: a tier pays out of order, a pari-passu split is struck off the wrong weights, or the promote tier is entered as though the hurdle were already cleared, and the developer's carry is larger than the contract earns. The summary asserts: the realized-returns table reports an equity multiple, a preferred return and a profit split that nobody recomputed from the waterfall underneath it. None of these are judgment calls. They are equalities and comparisons -- an accrued balance against its re-derivation, a tier allocation against the base facts, a stated return against the recomputed distribution -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks the deal this year. This is a re-derivation engine, not a negotiation: it takes the executed agreement's mechanics as given and asks only whether the money the schedule pays is the money the agreement promises.
The seeded demo runs every control over every deal file7. The CLI generates thirty-two fictional deal files -- one clean baseline and one carrying each of the thirty-one planted defects -- then runs all thirty 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.
A preferred-return balance that does not recompute is a break, not a rounding band8. A control rebuilds each member's Investment Return Account from its contribution history compounded monthly on unreturned capital, and pref_accrual_recomputes FAILs a stated balance that differs from the re-derivation by even a cent, because the comparison is exact integer-cent equality -- a preferred balance a cent off the accrual is a balance nobody can stand behind, and it moves every tier below it.
The realized return is recomputed, not read back9. A test flips a member's stated profit split to contradict its promote receipts. ret_profit_split_ties rebuilds the split from the recomputed waterfall's upper hurdle and promote tiers and FAILs because the stated figure no longer matches the evidence, proving the returns summary is recomputed rather than trusted.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Deal Files. fictional real-estate JV deal files enter the control registry
- Structural Precondition. is the deal file complete and the review month legible
- Member Register. is the register sound and the venture a well-formed two sides
- Preferred-Return Accrual. does the preferred return re-derive, compounded monthly
- Capital-Account Roll-Forward. does each capital account roll forward and zero out
- Waterfall Tiers. do the tiers pay in order and split pari passu, and recompute
- Hurdle Boundary. is the hurdle above the preferred and re-solved from contributions
- Promote Split. do the promote splits sum, and does the carry tie
- Member & Default Loans. is the loan sound and repaid off the top before distribution
- Capital-Call Dilution. does the dilution recompute by its own named method
- Distribution Completeness. does every distributed cent tie out with no leakage
- Realized-Returns Tie-out. does the returns summary recompute from the waterfall
- Financing Covenants. is loan-to-cost within the covenant, and what is maturing
- Syndicate. does the syndicate draw re-derive, and what report is due
- Waterfall Kernel & Artifacts. the shared arithmetic and the seven artifacts every rule resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Deal Files. generate_corpus writes one clean baseline plus one planted-defect deal file for every registered control, thirty-two files in total. Only the base facts -- the deal terms, the member register and each member's contributions -- are stated freely; the capital ledger, the waterfall schedule, the returns summary and the dilution and loan figures are all derived through the same waterfall kernel the engine later recomputes with, so the relationships the engine tests are the relationships that produced the data.
- Structural Precondition. One control. FAILs a deal file missing any of the seven artifact types or carrying a duplicate, and FAILs an unreadable as_of_period, so no downstream rule holds vacuously on absent evidence.
- Member Register. Four controls: unique member ids, a known role per member, exactly one investor and one developer, and no member funded beyond its commitment.
- Preferred-Return Accrual. Two controls: a positive preferred-return rate, and each stated Investment Return Account rebuilt from the contribution history compounded monthly to the as_of month.
- Capital-Account Roll-Forward. Two controls: each Contribution Account equals funded capital, and each ending account rolls to zero once tier-A and tier-B receipts are applied.
- Waterfall Tiers. Three controls: tiers in the contractual order, tiers A and B split on the account balances, and every tier/member allocation rebuilt from the base facts and compared entry by entry.
- Hurdle Boundary. Two controls: the hurdle rate sits strictly above the preferred, and the hurdle target re-solves from the investor's contributions grown at the hurdle rate.
- Promote Split. Two controls: the hurdle and promote splits each allocate 100%, and the stated developer promote equals its receipts across the hurdle and promote tiers.
- Member & Default Loans. Two controls: the default-loan rate sits above the member-loan rate, and the member loan's principal-plus-interest is repaid before the waterfall runs, with proceeds-after-loans net of it.
- Capital-Call Dilution. Three controls: a known dilution method, the statutory 200% penalty on the substitute contribution, and the penalized substitute and diluted interest rebuilt through the named formula variant.
- Distribution Completeness. Two controls: the entries sum to the total distributed which equals the proceeds after loans, and the total distributed never exceeds the proceeds available.
- Realized-Returns Tie-out. Three controls: each member's equity multiple, preferred return and profit split rebuilt from the recomputed waterfall and compared to the reported figure.
- Financing Covenants. Two controls, secondary: the re-derived loan-to-cost is within the covenant maximum, and a financing maturing inside its warning window is flagged for a refinance or extension chase.
- Syndicate. Two controls, secondary: the syndicate draw is the fixed 33.5% of the commitment, and a quarterly investor report due inside its lead window is flagged to prepare.
- Waterfall Kernel & Artifacts. The deal terms carry the rates, tier splits, hurdle and dilution penalty; the member register carries each member's role, commitment and funded contributions; the capital ledger, waterfall schedule, dilution worksheet, returns summary and loan covenant carry the derived figures. The accrual, roll-forward, hurdle, waterfall, loan and dilution controls all resolve against these through one shared kernel in waterfall.py that the generator also imports, so a figure the engine recomputes cannot disagree with the arithmetic that produced the data.
- Verdict and Findings. Findings roll up per deal 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 thirty 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 | waterfall_report.json, waterfall_report.md, samples/ |
python -m waterfall_engine samples | analyze an existing folder of deal 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 waterfall_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 | run the full test suite for this engine | 10449 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,449 tests collected live collection from the engine directory |
| Registered controls11 | 30 controls counted from the registry, not from documentation |
| Planted defects12 | 31 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 distribution is treated as sound and whether the schedule is paid.
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 deal file into the documented distribution sign-off and investor reporting |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; a financing maturing inside its warning window and a syndicate report due inside its lead time both land here |
| One or more FAIL | FAIL | the distribution is not treated as sound until the failing control is cleared -- a drifted accrual, a tier out of order, a leaked split, an overstated promote, a mis-recomputed dilution, or a returns table that does not recompute |
- Read-only: deal files are parsed and never written back, so the engine cannot introduce the break it reports.
- Integer cents throughout, compared with exact equality; there is no tolerance band on a distributed figure, and a cent off the re-derivation is reported as a break.
- 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 waterfall kernel: the controls and the generator share the arithmetic in waterfall_engine.waterfall, so a recomputed figure cannot disagree with the data that produced it.
- Deterministic and byte-stable: same inputs produce the same findings in the same order, with no timestamps or absolute paths in any output.
- Time is an explicit as_of_period month index carried in the file, never the system clock, so every accrual and covenant window is measured against a stated review point.
- 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 pays a distribution, funds a capital call, files an investor report, or writes to a source artifact. It reads the deal file and stops.14
- It reads the seven artifacts a distribution emits. It does not connect to an accounting system, a fund-administration platform, a bank, or the executed operating agreement itself.15
- It re-derives whether the schedule pays what the agreement's stated mechanics promise, not whether those mechanics are wise: the preferred rate, tier order, hurdle, promote split and dilution penalty are taken as given, and whether they are the right terms for a given deal is a reviewer's judgment.16
- It takes the base facts at face value: it confirms the derived figures recompute from the stated contributions and proceeds, not that the contributions were truly funded or the sale proceeds genuine.17
- The financing-covenant and syndicate families are secondary: they capture loan-to-cost, maturity, the syndicate draw and reporting cadence, not a full credit review. 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.
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (equity-waterfall-automation/)
- 2len(waterfall_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in waterfall_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(waterfall_engine.model.DOC_TYPES)
- 6waterfall_engine/tests comparing recomputed figures with exact integer-cent equality
- 7python run.py (equity-waterfall-automation/); waterfall_engine/tests/test_planted_defects.py
- 8waterfall_engine/tests/test_control_semantics.py
- 9waterfall_engine/tests/test_control_semantics.py
- 10python -m pytest --collect-only -q -o addopts= (equity-waterfall-automation/)
- 11len(waterfall_engine.engine.REGISTRY)
- 12len(waterfall_engine.generate.DEFECTS)
- 13waterfall_engine/tests/test_planted_defects.py
- 14equity-waterfall-automation/README.md and waterfall_engine/tests/test_readonly_and_determinism.py
- 15waterfall_engine/model.py DOC_TYPES
- 16waterfall_engine/model.py module docstring (Scope)
- 17waterfall_engine/generate.py
- 18waterfall_engine/engine.py (cov_ and syn_ families)
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