Contingency Rollforward & Adequacy

Architecture

Key specifications

What it does for you

Every active development project carries two contingency buckets, and every period the status block for each is restated by hand: six numbers and a word. The prior balance, the amount allocated this period, the amount allocated to date, the balance remaining, the projected potential use, and whether what is left is adequate. The same three failures recur every period. First, the rollforward stops rolling: prior balance less allocated this period is the balance remaining, until somebody types over the current figure for one project, and from then on the block is a mixture of rolled and typed balances that no longer follows from the period before it -- and it survives every period after. Second, the allocated total stops matching the draws: it is maintained beside the draw detail rather than footed from it, so a draw never reaches the total, or a single draw is written for more than the balance it draws against and the bucket goes overdrawn in a column nobody re-added. Third, the adequacy word goes stale: adequate is a comparison, not a label, and it gets carried forward from a period in which it was true while the projected potential use climbs past the balance behind it. None of these are judgment calls -- whether the projection is a sound estimate is a judgment no engine makes, and this engine does not attempt it. They are equalities and comparisons: a stated balance against a subtraction, a period total against the sum of its line items, a bucket against the budget that funded it, a draw against what earlier draws left, a word against the comparison of two amounts, and a rollup against a re-summation. A deterministic control settles those better than a block restated by hand every period for every active project.

The seeded demo runs every control over every period file⁷. The CLI generates twenty-four fictional period files -- one clean baseline and one carrying each of the twenty-three planted defects -- then runs all twenty-two 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 stale adequacy word is caught by re-striking the comparison⁸. A defect file leaves a bucket's adequacy word reading adequate while raising the projected potential use past the balance remaining, and changes nothing else -- the rollforward still foots and the draw detail still ties. adq_flag_recomputes strikes the comparison itself, finds the balance no longer covers the projection, and reports the word against the two amounts that contradict it.

The overdraw walk measures against what earlier draws left⁹. One project takes two draws against the same construction bucket. A boundary test sizes the second to fit the opening balance but not what the first one left, so the period total still looks reasonable and only the walk catches it. ctg_no_overdraw reports the second draw by id against the balance actually in front of it, and a draw exactly equal to that balance spends the bucket to zero and is allowed.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: period 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 derived figure, and a cent off the re-derivation is reported as a break.
• One rollforward kernel: the controls and the generator share the arithmetic in contingency_engine.rollforward, so a balance cannot disagree with the data that produced it.
• Adequacy is recomputed from the balance remaining and the projected use rather than read as a word, so a label carried forward from a period in which it was true cannot survive the period in which it stopped being true.
• The overdraw test walks each draw against what earlier draws left rather than against the opening balance, which is the direction that catches a bucket drawn past empty while the period total still looks reasonable.
• The inadequate count in the rollup is recounted from the recomputed adequacy calls, not from the stated words, so a rollup cannot agree with a block that is itself wrong.
• 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.
• Every draw is tested against the reporting period the file carries, never against the system clock, so a run in a later period returns the same findings.
• 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 posts a journal entry, approves a draw, tops up a contingency or writes to a source artifact. It reads the period file and stops.¹⁴
• It reads the six artifacts the periodic contingency record emits. It does not connect to a general ledger, a job-cost system, a change-order log, or the construction contracts the draws were released against.¹⁵
• It proves the block is arithmetically true and internally reconciled, not that the projected potential use is a sound estimate. Nothing here forecasts, and whether the remaining contingency will in fact be enough is a judgment no engine makes.¹⁶
• It tests each draw against the reporting period and the balance in front of it; it does not decide whether that draw should have been approved, or whether the cost it funded belonged in contingency rather than in the base budget.¹⁷
• It takes the stated projections and budgets at face value, confirming only that the block foots to them and reconciles to what was funded. All shipped data is fictional -- the developers, projects, budgets, draw numbers, balances, projections and reporting dates are invented, and the reporting period is set in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.