10,3641
Tests
the collected checks that pin this engine's behavior
ENGINE 17
SFS-E17-INS · INSURANCE ALLOCATION · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Insurance Cost Allocation
One premium, many projects
A developer does not buy insurance one project at a time; it buys a programme -- a liability tower, a builder's risk policy over whatever is under construction, an excess layer above the primary. One premium arrives, and it has to become a number on each project's job cost: correctly, reproducibly, and summing back to what was actually paid. This engine reads the artifacts that allocation emits -- the policy register and its tower, the project register and its bases, the allocation schedule, the carrier audits, the job-cost ledger, the reporting summary and the general-ledger positions -- and runs twenty-four deterministic controls over them. Is the tower gap-free and every term continuous, does every project's share re-derive from its declared basis to the cent and reach only the projects the policy covers, did the carrier audit true-up return to the projects that bore the deposit on the basis they bore it, and does the allocation reach job cost and tie the ledger. It re-derives every share by the same largest-remainder method that produced it, compares each one with exact equality, and never writes to a source artifact.
The failures here do not look wrong in a column of six-figure numbers, which is exactly why they survive to the job-cost tie-out. An allocation of one premium across N projects leaves a residual cent; dropped it foots a penny short, double-counted a penny long, and either way the break surfaces months later as a tie-out nobody can source. A covered project whose basis value never arrived drops out of the weighting and silently moves every other project's share while the total still ties -- every individual share is wrong and nothing footed loudly. And a carrier audit lands after the term, when the open projects are not the ones that paid the deposit; crediting whoever is open today takes money from the wrong job. Footing to the premium is necessary and not sufficient. The engine re-derives each share where the penny actually landed, ships a planted-defect file for every registered control, and states its benchmark as a command rather than a claim.
Architecture
functional block stack · static overviewSelect a layer
Seven control families run in registry order over each programme file. The first proves the others had something to read and that the review date is legible, because a control that passes on absent evidence reports assurance it never performed.
Key specifications
at a glance75
Artifacts read
project register, policy register, allocation schedule, audit register, job cost, summary, GL positions
What it does for you
plain termsA residential developer does not buy insurance one project at a time; it buys a programme -- a general liability tower, a builder's risk policy over whatever is under construction, an excess layer above the primary. One premium arrives, and it has to become a number on each project's job cost, correctly and summing back to what was actually paid. Three failures hide inside that, and none of them look wrong in a column of six-figure numbers. Any allocation of one amount across N projects leaves a residual cent: dropped it foots a penny short, assigned twice it foots a penny long, and both surface later as a job-cost tie-out nobody can source. A covered project whose basis value never arrived drops out of the weighting and quietly redistributes every other project's share, while the total still ties to the premium -- every individual share is wrong and nothing failed loudly. And a carrier audit true-up lands months after the term, by which time the projects open today are not the projects that bore the deposit; crediting whoever is open takes money from the wrong job and never makes a closed one whole. None of these are judgment calls. They are equalities -- a share against its re-derivation, an allocation against the premium, a credit against the deposit bearers -- which a deterministic control settles better than a spreadsheet inherited by whoever holds it this year.
The seeded demo runs every control over every programme file7. The CLI generates 26 fictional programme files -- one clean baseline and one carrying each of the 25 planted defects -- then runs all 24 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 cent moved between two projects keeps the footing8. A test moves one cent from one project's share to another's on the same policy. The footing control alloc_sums_to_premium stays silent because the total is intact by construction, and alloc_shares_recompute is the only control that sees the misplaced penny -- proof that summing to the premium is necessary but not sufficient.
The true-up returns to the projects that paid9. A test moves a credit between two deposit bearers: aud_uses_deposit_basis fires because the split no longer re-derives on the deposit basis, while aud_true_up_sums stays silent because the reallocation still foots to the audit amount -- the same two-control structure that catches a credit routed to a project that never bore the deposit.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Programme Files. fictional insurance programme files enter the control registry
- Structural Precondition. is the programme file complete and the review date legible
- Policy Register & Tower. is the register sound and does the tower hold with no gap
- Allocation. does every share re-derive from its basis, to the cent
- Builder's Risk. is the right thing insured, for the right term, at the right value
- Carrier Audit True-Up. did the true-up return to the projects that bore the deposit
- Job Cost & Ledger. does the allocation reach job cost and tie the ledger
- Reporting. does the per-unit board-pack metric recompute
- Project & Policy Registers. the register and bases every allocation rule resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Programme Files. generate_corpus writes one clean baseline plus 25 planted-defect files, at least one for every registered control, 26 files in total. Only the projects, the policies and the audits are stated; every share, every reallocation, what lands on job cost, the per-unit metric, the prepaid balance and the programme total are derived, so the relationships the engine tests are the same relationships that produced the data.
- Structural Precondition. One control. FAILs a file missing any of the seven artifact types or carrying a duplicate, and FAILs an unreadable as_of, so no downstream rule holds vacuously on absent evidence.
- Policy Register & Tower. Five controls: required fields and a known line/layer, unique policy numbers, forward-running terms, seamless renewals, and an excess layer attaching no higher than the primary limit beneath it.
- Allocation. Seven controls: basis declared and its data complete, projects known and only covered ones charged, footing to the premium, each share re-derived by largest remainder, and no negative share.
- Builder's Risk. Three controls: insured value tracks the budget within the policy's own band, the term brackets construction to the day, and a completed project is off the schedule.
- Carrier Audit True-Up. Four controls: the reallocation foots to the audit amount, credits only the deposit bearers, splits on the historical deposit basis, and restates the final exposure it settled on.
- Job Cost & Ledger. Three controls: allocated cost equals what landed on each project's job cost, prepaid re-derives straight-line to the review date, and the programme total ties the ledger.
- Reporting. One control: the per-unit figure re-derives as allocated cost floor-divided by unit count, FLAGged rather than failed because it is a derived presentation number.
- Project & Policy Registers. The project register carries each project's code, stage, unit count and every basis value -- hard cost, insured value, unit count. The policy register carries each policy's line, tower position, term, premium, covered schedule and declared basis. Allocation, builder's risk and audit are all evaluated against these two authorities.
- Verdict and Findings. Findings roll up per programme 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 twenty-four 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 | insurance_report.json, insurance_report.md, samples/ |
python -m insurance_engine samples | analyze an existing folder of programme 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 insurance_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 | 10364 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,364 tests collected live collection from the engine directory |
| Registered controls11 | 24 controls counted from the registry, not from documentation |
| Planted defects12 | 25 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 an allocation goes to job cost.
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 allocation into the documented job-cost and reporting review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; an insured value adrift of the budget, an audit with no restated basis, and a per-unit metric that does not recompute all land here |
| One or more FAIL | FAIL | the allocation does not go to job cost until the failing control is cleared |
- Read-only: programme 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 the allocation, and the single tolerant control reads its band from the policy rather than inventing one.
- A value 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.
- 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
what it refuses to do- The engine never posts an allocation, moves a premium, or writes to a source artifact. It reports and stops.14
- It reads the seven artifacts the allocation process emits. It does not connect to a broker system, a carrier portal, a policy-admin platform or the general ledger.15
- It is about where the cost lands, not whether a certificate is on file: certificate currency, limits and endorsements gate a payment, and the accounts-payable engine owns that gate. Nothing here re-checks a certificate.16
- It proves a share re-derives from the declared basis and ties, not whether that basis -- hard cost, insured value, unit count -- is the right one to have chosen. That judgment is a reviewer's.17
- All shipped data is fictional and the policy year is set in a fictional future. The corpus demonstrates the controls; it is not a record of any real programme, carrier, project, policy number or premium.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (insurance-allocation-automation/)
- 2len(insurance_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in insurance_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(insurance_engine.model.DOC_TYPES)
- 6insurance_engine/tests/test_control_semantics.py::test_each_share_is_re_derived_to_the_cent
- 7python run.py (insurance-allocation-automation/); insurance_engine/tests/test_planted_defects.py::test_defect_fires_its_intended_rule
- 8insurance_engine/tests/test_control_semantics.py::test_each_share_is_re_derived_to_the_cent
- 9insurance_engine/tests/test_control_semantics.py::test_true_up_splits_on_the_deposit_basis_to_the_cent
- 10python -m pytest --collect-only -q -o addopts= (insurance-allocation-automation/)
- 11len(insurance_engine.engine.REGISTRY)
- 12len(insurance_engine.generate.DEFECTS)
- 13insurance_engine/tests/test_planted_defects.py::test_every_registered_rule_has_a_planted_defect
- 14insurance-allocation-automation/README.md and insurance_engine/tests/test_readonly_and_determinism.py::test_analysis_does_not_touch_the_source
- 15insurance_engine/model.py DOC_TYPES
- 16insurance_engine/engine.py module docstring (Scope)
- 17insurance_engine/engine.py check_alloc_shares_recompute
- 18insurance_engine/generate.py
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