Subcontract SOV & Change Orders

Architecture

Key specifications

What it does for you

A residential developer buys construction through subcontract commitments: a contract with a schedule of values breaking the price into lines, change orders that amend it, and a monthly pay application that bills against it line by line. Every column on that chain is derived from a column beneath it, and every one of them is typed by hand somewhere. Three failures hide inside that, and none of them look wrong on the page. The contract drifts from its paper: the revised commitment stops equalling original plus net approved change orders -- a pending order counted early, a soft-cost credit booked as a brand-new commitment instead of a #-N amendment -- and the committed-cost roster no longer states what was signed. The billing chain breaks a line at a time: a completed-to-date that stops equalling previously billed plus this period, a line that quietly bills past its scheduled value, a month whose previously billed no longer equals last month's total completed -- and the overbilling compounds under a header that still foots. The money math is asserted, not derived: retention off the contract rate, sales tax off the rate on the taxable request, a payment due that is not request minus retention plus tax, and a conditional release signed for an amount nobody recomputed. None of these are judgment calls. They are equalities and a cap -- a completed against previously billed plus this period with exact ==, a line completed against its scheduled value with exact <=, a revised contract against original plus net approved changes -- which a deterministic control settles better than a workbook inherited by whoever bills the job this month.

The seeded demo runs every control over every billing file⁷. The CLI generates thirty fictional billing files -- one clean baseline and one carrying each of the twenty-nine planted defects, on the fictional Brightwater Commons project -- then runs all twenty-nine 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.

Only an approved change order moves the contract, and the cap is per line⁸. One defect file counts the pending winter-protection order as if approved, and cmt_revised_rederives recomputes the net from the change-order log through the shared kernel -- approved orders only -- and fails. Another bills the electrical rough-in line to 90,000 against its scheduled value, and because the whole chain is re-derived, only cap_not_overbilled fires at exact <= while every footing figure stays consistent.

The billing chain is recomputed, not read back⁹. A defect file re-types this period's work on a concrete line after the completed column was footed, so completed-to-date no longer equals previously billed plus this period. line_completed_rederives rebuilds the figure as D+E and fails, proving the pay app is recomputed from the base facts beneath it rather than trusted as stated.

Functional block diagram

Instruction set

Benchmarks

Control characteristics

• Read-only: billing files are parsed and never written back, so the engine cannot introduce the break it reports.
• Integer cents throughout, compared with exact ==, and the per-line billing cap tested with exact <=; there is no tolerance band, 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 billing kernel: the controls and the generator share the formulas in sov_engine.billing, so a derived figure cannot disagree with the data that produced it.
• Only approved change orders move the revised contract: a pending or void order re-priced any number of times moves nothing until it is approved.
• 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 certifies a pay application, cuts a payment, approves a change order, signs a lien release, or writes to a source artifact. It reads the billing file and stops.¹⁴
• It reads the six artifacts the commitment billing record emits. It does not connect to a general ledger, a lender draw system, a job-cost report or the underlying contracts and waivers.¹⁵
• It proves the arithmetic chain re-derives -- the SOV foots, the columns recompute, the cap holds, the release ties -- not that the billed work was actually performed or that a change order was authorized outside the log it reads.¹⁶
• It keeps only the arithmetic cross-tie: the conditional release amount equals the certified payment due. Which lender draw funds a pay application and whether a lien waiver's statutory form is correct stay with their own engines.¹⁷
• It re-derives retention and tax at the contract rates the file carries; it does not decide whether those rates are correct, and it treats the standard 5% / 10% retention menu as a review flag rather than a hard failure. All shipped data is fictional and every billing period sits in a fictional future.¹⁸

See it run

Integration

Distribution: public repository, MIT license.