10,4201
Tests
the collected checks that pin this engine's behavior
ENGINE 16
SFS-E16-BND · SURETY & COLLATERAL · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Surety Bond & Collateral
Cash that never comes back
A developer cannot pull a permit, record a plat or hand a finished street over to a city without first posting surety, so the bonds accumulate: a statutory licence bond per operating entity, a performance bond per set of subdivision improvements, a maintenance bond that runs through the warranty period after the work is accepted, a street-use bond for the right of way. Each carries its own obligee, term and premium, and some are backed by the developer's own cash lodged as collateral. This engine reads the eight artifacts a bond programme emits and runs twenty-nine deterministic controls over them across the whole lifecycle: is the register itself sound, does each bond meet its statute and take the right obligee, is it in force and continuously renewed, was it released only after the obligation ended, did the collateral follow the bond and come back, did premium stop at release, and does aggregate exposure still fit inside the facility. It reads and reports; it never writes to a bond, a ledger or the surety.
The money at risk here is not owed, it is already paid, and that is exactly why nothing catches it. A bond does its job, the city accepts the work, the obligation ends, the register is marked released -- and unless someone writes to the surety the collateral simply stays where it is, raising no payable, ageing on no report, sitting in restricted cash indistinguishable from cash. The mirror failure is a bond nobody released: premium renews on an obligation that ended two years ago and its penal sum keeps consuming the facility's aggregate limit until the next project's bond is declined for capacity the programme does not need. Neither leaves a single account out of balance, which is why a person closing the books cannot see them; both are lifecycle breaks, visible only when the collateral, the premium and the exposure are each tested against the life of the bond rather than against themselves. The engine ships a planted-defect file for every registered control, so the benchmark is 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; the rest walk the bond from the register it lives in to the exposure it consumes.
Key specifications
at a glanceWhat it does for you
plain termsA residential developer cannot pull a permit, record a plat or hand a finished street over to a city without posting surety, so the bonds accumulate into a portfolio of obligations with staggered terms and different obligees, and the cash attached to them moves in two directions: premium out, collateral out, and then -- if anyone remembers to ask -- collateral back. Nothing in the ordinary accounting cycle notices when that last step does not happen. A bond does its job, the work is accepted, the obligation ends and the register is marked released, and unless someone writes to the surety the collateral simply stays where it is: it raises no payable, ages on no report, and sits in restricted cash indistinguishable from cash until the register is reconciled to the restricted-cash ledger and someone finds a released bond still carrying a balance. The mirror failure is a bond nobody released, still consuming the facility's aggregate limit and still renewing premium on an obligation that ended two years ago, until the next project's bond is declined for capacity the programme does not actually need. None of these move a single account out of balance, which is exactly why a person closing the books cannot see them -- they are lifecycle breaks, and a lifecycle break is only visible when the collateral, the premium and the exposure are each tested against the life of the bond rather than against themselves. These are not judgment calls; they are equalities and date comparisons -- a release date against an obligation end, an outstanding balance against zero, a stated total against restricted cash -- which is what a deterministic control settles better than a reviewer working one bond at a time.
The seeded demo runs every control over every programme file7. The CLI regenerates 31 fictional programme files -- one clean baseline and one carrying each planted defect -- then runs all 29 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 released bond with collateral and nobody chasing it8. A test drops a single refund entry so a released bond keeps an outstanding collateral balance with no refund recorded as in flight. life_no_release_while_collateral_outstanding fires -- the cash sits in restricted cash looking exactly like cash -- while the same defect with a refund status recorded stays silent, because the control asks for a chase, not for the money to already be back.
The unbonded window between two valid renewals9. A boundary test slides a renewal's effective date across the day after the prior term expired. Starting the same day or the next day passes as continuous cover; one clear day later fails, because that gap -- invisible afterwards, since both bonds look valid on their own -- is exactly the window in which the obligation was unbonded.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Programme Files. fictional bond programme files enter the control registry
- Structural Precondition. is the programme file complete, and is the review date legible
- Register. is the register itself sound
- Statutory Status. does each bond meet its statute and take the right obligee
- Bond Lifecycle. is the bond in force, renewed, and released only when the obligation ended
- Collateral. did the collateral follow the bond, and did it come back
- Premium. is the premium rated, amortised and stopped at release
- Aggregate Exposure. does exposure fit the facility, and does the summary foot
- Bond Register. the register every rule resolves bond numbers 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 30 planted-defect files, at least one for every registered control, 31 files in total. Only the facility, the rate card, the statutory minimums, the projects, the bonds and the two ledgers are stated; every premium, outstanding-collateral, restricted-cash and prepaid figure the engine later checks as a tie-out is derived by the generator from those inputs, so the relationships it tests are the same ones that produced the data.
- Structural Precondition. One control, run first. FAILs a file missing or duplicating any of the eight artifacts, or carrying an unreadable as_of, so no downstream rule holds vacuously on absent evidence.
- Register. Five controls: unique bond numbers, required fields present, status, type and obligee kind in vocabulary, terms running forwards, and every bond mapped to a real project.
- Statutory Status. Three controls over the statutory minimum penal sum, the obligee kind matching the bond type, and a permit reference on permit-linked bonds.
- Bond Lifecycle. Seven controls over expiry, the renewal horizon, continuity of cover, release evidence, release timing against the obligation end, maintenance inception, and the headline collateral-outstanding-on-a-released-bond control.
- Collateral. Six controls tying collateral to the penal sum, to its own ledger and to restricted cash at zero tolerance, plus refund-over-posted, ageing and custodian checks.
- Premium. Five controls: the one tolerant rate-card band, no premium after release, straight-line prepaid amortisation tied to the GL, a rider on every return premium, and entry types in vocabulary.
- Aggregate Exposure. Two controls: active penal sums inside the aggregate limit, and the exposure-by-obligee summary footing to the register it was drawn from.
- Bond Register. Each bond's number, project, type, obligee, status, term, penal sum and stated collateral. The bond number is the join key to both ledgers, so the three-way tie between register, ledger and general ledger is evaluated against this one authority.
- 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-nine 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 | bond_report.md, bond_report.json, samples/ |
python -m bond_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 bond_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 | 10420 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,420 tests collected live collection from the engine directory |
| Registered controls11 | 29 controls counted from the registry, not from documentation |
| Planted defects12 | 30 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 to write to the surety, release a bond or recover the collateral.
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 programme into the documented bond and collateral review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; a premium off the rate card, a bond nearing expiry, a stale refund ageing, and a return premium with no rider all land here |
| One or more FAIL | FAIL | the programme does not go to review until the failing control is cleared -- collateral outstanding on a released bond, a renewal gap, exposure over the facility, or a register that does not tie to restricted cash |
- 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; the only tolerance is prem_rate_within_schedule, which reads its band from the rate schedule 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.
- Deterministic and byte-stable: every date test is made against the as_of carried in the file, never the system clock, so the same inputs produce the same findings in the same order with no timestamps or absolute paths.
- Absent evidence is never a passing control; a missing artifact fails set_complete rather than letting the controls that read it pass unread.
Operating limits
what it refuses to do- The engine never writes to a bond, a ledger, the surety or the general ledger. It reports and stops.14
- It reads the eight artifacts a bond programme emits. It does not connect to the surety's system, a bank, or the general ledger it ties out against.15
- It tests that a bond meets its statute and that its collateral, premium and exposure follow its lifecycle, not whether the bond should have been written or the collateral was commercially reasonable. That judgment is a reviewer's.16
- One control is deliberately tolerant and says so: premium against the rate card is a reasonableness band read from the schedule, a FLAG rather than a FAIL. Everything else compares at zero tolerance.17
- All shipped data is fictional and the review period is set in a fictional future. The corpus demonstrates the controls; it is not a record of any real developer, surety, state, city, project, bond or amount.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
Substantiation
- 1python -m pytest bond_engine/tests -q (surety-bond-automation/)
- 2len(bond_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in bond_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(bond_engine.model.DOC_TYPES)
- 6bond_engine/tests/test_control_semantics.py
- 7python run.py (surety-bond-automation/); output re-run on demand
- 8bond_engine/tests/test_control_semantics.py::test_released_bond_with_outstanding_collateral_and_no_status_fails
- 9bond_engine/tests/test_control_semantics.py::test_renewal_continuity_allows_only_a_seamless_handover
- 10python -m pytest --collect-only -q -o addopts= (surety-bond-automation/)
- 11len(bond_engine.engine.REGISTRY)
- 12len(bond_engine.generate.DEFECTS)
- 13bond_engine/tests/test_planted_defects.py::test_every_registered_rule_has_a_planted_defect
- 14surety-bond-automation/README.md and bond_engine/tests/test_readonly_and_determinism.py
- 15bond_engine/model.py DOC_TYPES
- 16bond_engine/engine.py check_stat_licence_minimum
- 17bond_engine/engine.py check_prem_rate_within_schedule
- 18bond_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