Project Proforma Integrity

Architecture

Key specifications

What it does for you

A real-estate developer reports every active project each quarter, and the reporting deck is built on a proforma workbook per project -- a grid of formatted numbers that was internally consistent the day a formula last recalculated, and that drifts silently when cells are overtyped or tabs are rolled forward without their precedents. The workbook carries its own error-check tab, but the zeros on it are cells like any other and can be typed over the break they were meant to catch. Three families of drift hide inside a clean-looking workbook, none of which look wrong in a grid of formatted numbers. The balances stop balancing: total sources drift a cent from total uses, hard plus soft stops equalling total project cost, the dev-cost budget no longer matches the proforma's unlevered cost. The profit chain stops tying: net profit no longer equals revenue minus cost, the waterfall's distributed profit stops matching the budgeted profit, the sponsor and investor splits stop summing to the whole -- the distribution looks funded and the arithmetic underneath it does not close. And the report drifts from the evidence: a margin is quoted off a stale cost, a variance column is typed rather than subtracted, a project's QPR misses its cycle or lands after its region's due date, and the cycle count is maintained beside the filings rather than derived from them. None of these are judgment calls. They are equalities and comparisons -- a stated total against the sum of its lines, a limit against a reserve with exact <=, a stated figure against its re-derivation from the base ledger, a filed date against a due date -- which a deterministic control settles better than an error-check tab whose zeros were typed. This engine is about integrity, not valuation: it does not underwrite a rent or a cap rate or decide whether a project should be built, only whether the workbook still ties to itself and whether every deliverable made its cycle on time.

The seeded demo runs every control over every proforma file⁷. The CLI generates twenty-eight fictional proforma files -- one clean baseline and one carrying each of the twenty-seven planted defects -- then runs all twenty-six 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 source-and-use error of a single cent is a break, not a rounding band⁸. A boundary defect appends an unfunded use line so that uses exceed sources by one cent, and re-derives the file so the stated totals still tie their own lines -- leaving only the balance broken. src_source_use_balance recomputes total sources and total uses from the ledger and fails on the single cent, because the source-and-use error is re-derived rather than read off an error-check tab whose zero was typed.

The materiality swing is real, re-derived, and a reviewer's call⁹. A defect raises a project's revenue so net profit swings far beyond the file's materiality band against prior, then re-derives the file so every tie-out stays intact. var_materiality_flag raises a FLAG rather than a FAIL: the swing is correctly derived and the arithmetic closes, but a move this large between quarters wants a human's eyes, so the file rolls up to REVIEW rather than FAIL.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: proforma 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 a tie-out, and a cent off the requirement is reported as a break.
• An amount that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one ledger row it was read on, rather than being coerced into the number the engine is meant to audit.
• One derivation kernel: the controls and the generator share the arithmetic in proforma_engine.proforma, so a stated figure cannot disagree with the logic 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.
• Absent evidence is never a passing control; a missing artifact fails completeness rather than letting the controls that read it pass unread.

Operating limits

• The engine never edits a proforma, recalculates a workbook, files a deliverable, or writes to a source artifact. It reads the proforma file and stops.¹⁴
• It reads the six artifacts a reporting cycle emits. It does not connect to the spreadsheet the proforma lives in, a document-management system, or the underwriting model behind the ledger.¹⁵
• It is about whether the workbook still ties to itself, not whether the project is a good investment: underwriting a rent or a cap rate is a different job the engine explicitly declines.¹⁶
• It proves each stated figure re-derives from the base ledger, not that the base ledger's own raw costs, revenues and dates are correct. That judgment is a reviewer's.¹⁷
• It takes the filing register at face value: it confirms a QPR is recorded as filed on or before the due date, not that the filed document itself is complete or correct. All shipped data is fictional and the reporting period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.