10,2241
Tests
the collected checks that pin this engine's behavior
ENGINE 52
SFS-E52-BDR · BUDGET INTEGRITY · REV 2026-08-26 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Baseline & Version Drift
Four copies of one budget, each internally perfect, reconciled against one another.
A joint venture is signed against a contractual exhibit. The sponsor maintains a working model. Draws are billed on an instrument carrying approved-plus-changes columns. A summary memo goes to a lender. Four copies of one budget -- and each can foot perfectly, re-derive its own margin, balance sources against uses, and still disagree with the other three. This engine reads the six artifacts a reporting cycle emits -- the governing agreement, every budget version in circulation, the amendment log, the milestone set, the derived schedules and the funding register -- and runs twenty-five deterministic controls across them. Is every artifact present and the period legible, does every version declare an id and a role and a prepared date, is there exactly one contractual baseline and does the agreement name it, was that baseline prepared on or after the agreement it is an exhibit to, was any version prepared after the period it reports on, do the category sets reconcile in both directions, does every paired line agree with the baseline, is a sub-threshold difference still surfaced, does every version's derived total equal the baseline's and its own stated figure, do the phase totals foot with no unphased line, are offsetting movements graded as re-carves rather than changes, is each reporting copy current to within the file's staleness band, does a summary predate the working model it restates, does every billing line re-derive from approved plus previous plus current, does every current change trace to an approved amendment for its exact amount, has a pending amendment been billed as though approved, has a locked line moved in any copy, does every schedule input exist and carry a date, do the instalments conserve the base over the declared periods, is the base net of advances taken, are advances inside the cap, do member commitments agree across copies, does the funding split match the agreement's ratio for the declared phase, and is every member inside commitment and cap. Every comparison is exact == in integer cents, and every date is tested against the reporting period the file carries rather than the system clock.
Every within-document control in a finance stack asks the same question: does this workbook foot? Four copies of one budget can each answer yes and still disagree by half a million. That is not a hypothetical failure mode; it is the ordinary condition of a project that has been running long enough to have a contractual exhibit, a working model that has moved since, a billing form carrying its own change columns, and a memo somebody circulated last quarter. Each artifact is maintained by a different person for a different purpose, each is internally consistent, and nothing in the stack compares them. The failures that follow are quiet by construction. A reclassification -- two lines moving by equal and opposite amounts -- reads as a change and buries the genuine ones. A line renamed in one copy has no counterpart in another, so a comparison that pairs on names walks straight past the line that moved. A copy goes stale rather than wrong: it was right when it was prepared, its cost-through date is months behind, and every figure read off it since has been quoted with confidence. A derived schedule loses a milestone and does not error -- it silently keeps its last amortisation. This engine is the reconciliation nobody performs: category sets paired before values, totals summed from lines rather than read from a stated figure, offsetting movements graded separately from changes, every movement traced to an approved amendment, and a materiality threshold used only to grade a difference that has already been found -- never to decide whether one exists.
Architecture
functional block stack · static overviewSelect a layer
Seven control families run in registry order over each cycle file. The first proves the others had something to read, because a control that passes on absent evidence reports assurance it never performed.
Key specifications
at a glanceWhat it does for you
plain termsA project budget does not exist once. It exists as a contractual exhibit the venture was signed against, a working model the sponsor maintains, a billing instrument draws are requested on, and a summary memo circulated to a lender -- four copies, four owners, four purposes. Each is internally consistent. Sources equal uses in all of them, each re-derives its own margin, each foots. Nothing in an ordinary finance stack compares them to one another, and five failures live in that gap. First, a copy is materially wrong while being internally perfect: the totals simply differ, and no within-document control can see it. Second, a reclassification reads as a change -- two lines move by equal and opposite amounts, the total never budges, and grading that as a budget revision buries the genuine revisions among the noise. Third, a category exists in one copy and not another, because a line was renamed or split; a comparison that walks one version's lines and looks each up in the other returns clean on everything it can pair and skips the one that moved. Fourth, a copy is stale rather than wrong: it was right when it was prepared, its cost-through date is months behind the period being reported, or its prepared date falls before the agreement it purports to be an exhibit to, and every figure read off it since has been quoted with confidence. Fifth, a derived schedule loses its inputs -- a fee amortised across a construction period depends on milestone dates, and blanking a milestone does not raise an error, it silently leaves the schedule on its last amortisation while the instalment it drives stops matching the term it spans. None of these announce themselves. Each survives every check that looks inside a single document, which is why the reconciliation between documents has to be a control of its own.
The seeded demo runs every control over every cycle file6. The CLI generates twenty-seven fictional cycle files -- one clean baseline and one carrying each of the twenty-six planted defects -- then runs all twenty-five 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.
Two lines move in opposite directions and the total holds7. One planted defect moves an amount out of one category and into another in the working model, leaving the grand total untouched. The engine grades it as a reclassification rather than a change, so it surfaces for review as a re-carve that still needs an approval behind it, instead of appearing in the same list as the genuine budget movements.
A category is renamed in one copy and the comparison does not skip it8. One planted defect renames a category in the working model. Because the category sets are reconciled in both directions before any value is compared, the engine reports the line as present in the baseline and absent from the copy -- rather than pairing on names, finding no match, and silently comparing everything else.
A milestone is blanked and the schedule keeps paying9. One planted defect removes the date from a milestone a fee amortisation declares as an input. The schedule does not error and its instalments still sum to its base, so every arithmetic control on it holds. The engine fails it anyway, because the term the amortisation spans is no longer defined.
A difference below materiality is reported rather than suppressed10. A sub-threshold line difference is carried as a review flag, not dropped. The materiality threshold grades a difference the engine has already found with exact ==; it never decides whether a difference exists, because a line nobody reconciles is how a small difference becomes a large one.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Cycle Files. fictional reporting-cycle files enter the control registry
- Derivation Kernel. one implementation of pairing, reclassification and amortisation
- Structural Precondition. every artifact present, period legible
- Version Inventory. one governing copy, plausibly dated
- Agreement Between Copies. category sets, then values, then totals
- Currency. is each copy still about this period
- Amendment Traceability. every movement re-derived and traced
- Derived Schedules. inputs present, base conserved
- Funding Consistency. commitments agree, split matches phase
- Findings. PASS, FLAG or FAIL with a location and a reason
- Reports. byte-stable JSON and markdown
Engineering
- Seeded Cycle Files. generate_corpus writes one clean baseline plus one planted-defect file for every registered control, twenty-seven files in total. Only the line set, the agreement and the amendment log are stated; every version's stated total, the billing instrument's change columns and the derived schedule's instalment stream are re-derived through the same kernel the engine later recomputes with, so the relationships the engine tests are the relationships that produced the data. The corpus deliberately carries an approved amendment and a pending one in the clean file, so the traceability controls are exercised by a passing file rather than only by their defects.
- Derivation Kernel. budget.py is the single place that knows how a version is read, how two versions are paired and how a schedule is amortised. Both the generator and the controls import it, so a control and the corpus it audits cannot quietly disagree about what agreement means. pair_lines returns three disjoint groups rather than a lookup, detect_reclassifications returns offsetting pairs only when the total is unchanged, and amortisation_schedule delegates to the shared money kernel so an instalment stream is derived the same way it was built.
- Structural Precondition. set_complete owns absence so no downstream rule reports it a second time.
- Version Inventory. Four controls establishing which copy variance is measured against.
- Agreement Between Copies. Six controls, ordered so the set reconciliation precedes any value comparison.
- Currency. Two controls covering staleness and superseded restatements.
- Amendment Traceability. Four controls over the billing instrument's change columns and the approval register.
- Derived Schedules. Five controls proving a schedule's inputs exist and carry dates before its output is trusted.
- Funding Consistency. Three controls over the funding register and the agreement's phase ratios.
- Findings. Every finding carries the rule that produced it, a location of the form doc_type:document_id/field, and a message that states the rationale rather than only the verdict. A file with any FAIL rolls up to FAIL; FLAGs without FAILs roll up to REVIEW.
- Reports. Two renderings of the same findings, with no timestamps, absolute paths or hash-ordered iteration anywhere in the output, so a change in the committed diff means a change in the controls rather than a change in when the report ran.
Instruction set
every public command| Command | Operation | Output | Exit | Artifacts |
|---|---|---|---|---|
python run.py | regenerate the seeded fictional corpus, run all twenty-five 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 | baseline_report.json, baseline_report.md, samples/ |
python -m baseline_engine samples | analyze an existing folder of cycle 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 baseline_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 baseline_engine/tests -q | run the engine's own test suite | pytest summary | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests11 | 10,224 tests collected live collection from the engine directory |
| Registered controls12 | 25 controls counted from the registry, not from documentation |
| Planted defects13 | 26 defect files every registered control has at least one file that trips it |
| Control coverage14 | 100 percent of controls with a planted defect no control ships without a corpus file proving it fires |
Control characteristics
engineeringPlain terms
A clean result means the implemented mechanical controls found nothing wrong in the set of budget copies they were given: every artifact is present and the period legible, exactly one copy governs and the agreement names it, no copy is dated before the agreement or after the period, the category sets reconcile in both directions, every paired line and every derived total agrees with the baseline, the phase split foots with no unphased line, every reporting copy is current to within the file's staleness band, every billing line re-derives from its own change columns and traces to an approved amendment for its exact amount, no pending amendment has been billed, no locked line has moved, every derived schedule's inputs exist and carry dates and its instalments conserve a base net of advances inside its cap, and every member's commitment agrees across copies and matches the phase ratio. It is not an opinion that the budget is correct, complete or approved.
Engineering
Deterministic envelope. seeded fictional inputs, read-only operation, offline default mode.
- Read-only: no control writes to a source artifact, and the read-only suite proves the corpus is byte-identical after a full registry run.
- Deterministic: the generator takes no seed and the reports carry no timestamps, absolute paths or hash-ordered iteration, so the same corpus produces the same bytes.
- Exact: every monetary comparison is integer cents with ==, and there is no tolerance band anywhere in the engine.
- Clock-free: every date is measured against the reporting period carried in the file, never the system clock, so a passing corpus cannot start failing because CI ran on a different day.
- Detection precedes grading: the materiality threshold grades a difference already found with ==; it never decides whether a difference exists.
- Amounts are integer cents end to end; floating point appears only at the formatting edge.
- A value that must be integer cents and is not raises AMOUNT_INVALID and is reported rather than coerced, so the engine never becomes the author of a figure it is auditing.
- Category sets are reconciled before values, so a comparison cannot silently skip a renamed or split line.
- Totals are summed from the lines rather than read from a stated figure, then compared to the stated figure.
- Instalment streams are derived through the same shared money kernel that built them, so a schedule is re-derived the way it was constructed.
Operating limits
what it refuses to do- The engine never prepares a budget, approves an amendment, issues a draw, or writes to a source artifact. It reads the cycle file and stops.15
- It does not check whether a single budget foots internally. Sources against uses, margin re-derivation and interest-reserve adequacy are a within-document question and SFS-E23-QPR owns it; this engine is the reconciliation between copies and nothing more.16
- It reads the six artifacts a reporting cycle emits. It does not connect to a general ledger, a spreadsheet, a document-management system or a counterparty's portal.17
- It audits the copies it is given. A copy that was never circulated to it cannot be reconciled, and the engine reports the set it can see rather than asserting that set is complete.18
- Which copy governs is read from the executed agreement's baseline_document_id. The engine verifies the declaration is internally consistent; it does not interpret the agreement.19
See it run
brand animation
Integration
how to run itDistribution: public repository, MIT license.
python run.py
python -m pytest baseline_engine/tests -q
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (baseline-drift-automation/)
- 2len(baseline_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in baseline_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(baseline_engine.model.DOC_TYPES)
- 6python run.py (baseline-drift-automation/); baseline_engine/tests planted-defect suite
- 7baseline_engine/generate.py _offsetting_reclass; budget.detect_reclassifications
- 8baseline_engine/generate.py _category_renamed_in_copy; budget.pair_lines
- 9baseline_engine/generate.py _milestone_blanked; engine.check_drv_milestones_populated
- 10baseline_engine/tests/test_control_semantics.py threshold boundary tests
- 11python -m pytest --collect-only -q -o addopts= (baseline-drift-automation/)
- 12len(baseline_engine.engine.REGISTRY)
- 13len(baseline_engine.generate.DEFECTS)
- 14baseline_engine/tests/test_planted_defects.py test_every_control_has_a_planted_defect
- 15baseline-drift-automation/README.md and baseline_engine read-only / determinism tests
- 16baseline-drift-automation/README.md scope statement
- 17baseline_engine/model.py DOC_TYPES
- 18baseline_engine/engine.py check_set_complete
- 19baseline_engine/engine.py check_ver_single_baseline
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