10,3401
Tests
the collected checks that pin this engine's behavior
ENGINE 18
SFS-E18-COI · INSURANCE COMPLIANCE · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Insurance Compliance
Is the certificate still good?
A residential developer requires every consultant, general contractor and subcontractor it hires to carry insurance per its contract, and it has to prove, party by party, that each one's certificate is on file, unexpired, and meets the required limits and endorsements for that party's type. A certificate of insurance is a one-page snapshot of coverage that was true the day the broker issued it, and it goes stale in ways nobody watches. This engine reads the six artifacts the compliance file carries -- the party register, the requirement matrix, the certificate register, the coverage summary, the renewal watchlist and the monthly compliance report -- and runs twenty-two deterministic controls over them. Is the party register sound and every requirement lookupable, is each certificate well-formed and attributable, does every required coverage have a governing certificate that is in force, adequate on both the per-occurrence and the aggregate limit, and carrying the additional-insured and waiver-of-subrogation endorsements the matrix demands, is there no uninsured day between a lapse and the renewal that followed it, and does the monthly rollup recompute from the certificates underneath it rather than being read back as an assertion. It selects the governing certificate as the one whose term reaches furthest forward -- the renewal, not the policy it replaced -- compares every limit with exact >=, and never writes to a source artifact.
This is the compliance half of the insurance story that the allocation engine explicitly declines to check: where a master premium lands on each project's job cost is one question, and whether a certificate is on file at all is another, and the allocation engine owns only the first. None of the failures here look wrong in a folder of one-page certificates. A policy expires and the renewal never arrives, so a party is uninsured on the developer's own job while its file still shows a certificate -- an expired one. A certificate is current but a cent short of the contract limit, or missing the additional-insured endorsement the contract demanded, so the paper looks complete and the protection is not there. And the monthly report calls a party compliant on a determination nobody recomputed from the certificates beneath it. The engine rebuilds every compliant flag from the requirement matrix and the governing certificates, walks each renewal succession for the single uninsured day, ships a planted-defect file for every registered control, and states its benchmark as a command rather than a claim. A certificate that lapsed, or was accepted a limit short, is invisible until a claim lands on cover nobody actually had.
Architecture
functional block stack · static overviewSelect a layer
Seven control families run in registry order over each compliance 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 glance65
Artifacts read
party register, requirement matrix, certificate register, coverage summary, renewal watchlist, compliance report
What it does for you
plain termsA residential developer requires every consultant, general contractor and subcontractor it hires to carry insurance per its contract, and it has to prove, party by party, that each one's certificate of insurance is on file, unexpired, and meets the required limits and endorsements for that party's type. A certificate is a one-page snapshot of coverage that was true the day the broker issued it, and three failures hide inside that, none of which look wrong in a folder of one-page certificates. A policy expires and the renewal certificate never arrives, so the party is uninsured on the developer's own job while its file still shows a certificate -- an expired one; and between two valid renewals the same gap can open for a single day, and an occurrence lands in it with nothing to respond. The certificate is current but the per-occurrence or aggregate limit is a cent below what the contract required for that party type, or the additional-insured and waiver-of-subrogation endorsements the contract demanded were never added -- the paper looks complete and the protection is not there. And the monthly report calls a party compliant, or counts a portfolio as clean, on a determination nobody recomputed from the certificates underneath it. None of these are judgment calls. They are equalities and comparisons -- a governing certificate against the review date, a limit against the requirement with exact >=, a stated flag against its re-derivation -- which a deterministic control settles better than a spreadsheet inherited by whoever tracks certificates this year. This is the compliance half of the insurance story; a separate engine allocates the premium across projects and explicitly declines to check whether a certificate is on file at all.
The seeded demo runs every control over every compliance file7. The CLI generates twenty-four fictional compliance 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 limit a cent short of the contract is a shortfall, not a rounding band8. A boundary test sets a governing certificate's per-occurrence limit one cent below, exactly at, and one cent above the matrix requirement. cov_per_occurrence_meets fires only on the cent-short case and stays silent at the requirement and above, because the comparison is exact >= -- a limit a cent under the contract is a limit under the contract, invisible in a column of six-figure numbers until a claim tests it.
The determination is recomputed, not read back9. A test flips a party's stated compliant flag to contradict its certificates. rpt_party_compliant_recomputes rebuilds the flag from the requirement matrix and the governing certificates -- currency, limits and endorsements -- and fails because the stated determination no longer matches the evidence, proving the rollup is recomputed rather than trusted.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Compliance Files. fictional certificate-of-insurance compliance files enter the control registry
- Structural Precondition. is the compliance file complete and the review date legible
- Party Register. is the register sound and every requirement lookupable
- Certificate Register. is every certificate well-formed and attributable
- Coverage & Limits. is each required coverage present, adequate, and gap-free
- Endorsements. are the required endorsements on the governing certificate
- Expiry & Renewal. is the coverage in force now, and what is due to renew
- Compliance Report. does the rollup recompute from the certificates
- Registers & Requirement Matrix. the register, matrix and certificates every rule resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Compliance Files. generate_corpus writes one clean baseline plus one planted-defect file for every registered control, twenty-four files in total. Only the parties, the requirement matrix and the certificates are stated; each party's compliant determination, the renewal watchlist and the portfolio compliant / non-compliant counts are derived through the same compliance kernel the engine later recomputes with, 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 six artifact types or carrying a duplicate, and FAILs an unreadable as_of, so no downstream rule holds vacuously on absent evidence.
- Party Register. Four controls: unique party ids, a known party type, a non-empty known required-coverage set, and a requirement-matrix row for every coverage a party must carry.
- Certificate Register. Four controls: required descriptive fields present, unique policy numbers, forward-running terms, and a party in the register for every certificate.
- Coverage & Limits. Five controls: a known coverage line, a certificate on file for every required coverage, the per-occurrence and aggregate limits met at the requirement with exact >=, and no uninsured day between successive renewals.
- Endorsements. Two controls: the additional-insured and waiver-of-subrogation endorsements the matrix requires are present on the certificate in force, read on the renewal rather than the policy it replaced.
- Expiry & Renewal. Three controls: the governing certificate is unexpired at as_of, one expiring inside the lead window is flagged for chase, and every party carries unexpired workers' comp as a statutory floor.
- Compliance Report. Three controls: each party's compliant flag re-derives from the matrix and the governing certificates, the report counts tie the summary, and the renewal watchlist ties the evidence.
- Registers & Requirement Matrix. The party register carries each party's id, type and contract-required coverage set; the requirement matrix carries the per-occurrence and aggregate limits and the endorsement flags keyed by party type and coverage line; the certificate register carries every certificate. Coverage, endorsement, expiry and rollup controls all resolve against these, and the governing certificate for a line is the one whose term reaches furthest forward -- the renewal, not the policy it replaced.
- Verdict and Findings. Findings roll up per compliance 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-two 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 | coi_report.json, coi_report.md, samples/ |
python -m coi_engine samples | analyze an existing folder of compliance 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 coi_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 | 10340 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,340 tests collected live collection from the engine directory |
| Registered controls11 | 22 controls counted from the registry, not from documentation |
| Planted defects12 | 23 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 a party is treated as compliant and whether a renewal is chased.
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 compliance file into the documented sign-off and renewal review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; a governing certificate inside the renewal lead-time window and a watchlist that does not tie the evidence both land here |
| One or more FAIL | FAIL | the party is not treated as compliant until the failing control is cleared -- an expired or short certificate, a missing endorsement, an uninsured gap, or a rollup that does not recompute |
- Read-only: compliance 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 limit, and a cent short of the contract requirement is reported as a shortfall.
- A limit that should be integer cents but is not produces an AMOUNT_INVALID finding contained to the one certificate row it was read on, rather than being coerced into the number the engine is meant to audit.
- One compliance predicate: the controls and the generator share the kernel in coi_engine.compliance, so a determination cannot disagree with the data 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
what it refuses to do- The engine never issues a certificate, contacts a carrier or broker, chases a renewal, or writes to a source artifact. It reads the compliance file and stops.14
- It reads the six artifacts the compliance process emits. It does not connect to a broker system, a carrier portal, a certificate-tracking platform or the underlying contracts.15
- It is about whether the paper in the file satisfies the contract, not where an insurance cost lands: premium allocation across projects is a separate engine's job, and that engine explicitly declines to check a certificate.16
- It proves a certificate meets the requirement matrix, not that the matrix asks for the right limits or endorsements for a given party's risk. That judgment is a reviewer's.17
- It takes the certificate at face value: it confirms the paper on file is current, adequate and endorsed, not that the certificate is genuine or the underlying policy truly in force. All shipped data is fictional and the compliance period is set in a fictional future.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (coi-compliance-automation/)
- 2len(coi_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in coi_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(coi_engine.model.DOC_TYPES)
- 6coi_engine/tests/test_control_semantics.py::test_per_occurrence_meets_at_the_cent
- 7python run.py (coi-compliance-automation/); coi_engine/tests/test_planted_defects.py::test_defect_fires_its_intended_rule
- 8coi_engine/tests/test_control_semantics.py::test_per_occurrence_meets_at_the_cent
- 9coi_engine/tests/test_control_semantics.py::test_compliant_flag_must_recompute
- 10python -m pytest --collect-only -q -o addopts= (coi-compliance-automation/)
- 11len(coi_engine.engine.REGISTRY)
- 12len(coi_engine.generate.DEFECTS)
- 13coi_engine/tests/test_planted_defects.py::test_every_registered_rule_has_a_planted_defect
- 14coi-compliance-automation/README.md and coi_engine/tests/test_readonly_and_determinism.py::test_analysis_does_not_touch_the_source
- 15coi_engine/model.py DOC_TYPES
- 16coi_engine/engine.py module docstring (Scope)
- 17coi_engine/engine.py check_rpt_party_compliant_recomputes
- 18coi_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