10,3821
Tests
the collected checks that pin this engine's behavior
ENGINE 20
SFS-E20-LAB · LABOR ALLOCATION · REV 2026-07-24 · PRODUCTION
PRODUCTION = runnable end-to-end, CI-backed, full test suite passing. All data fictional and seeded.
Project Labor Charge
Charged only when authorized
An employee's time is not free to a project just because the company already pays the salary; the fully-burdened cost -- salary plus payroll taxes plus benefits -- has to be charged over, and only where a project manager authorized it in advance. Before a charge lands, the manager notifies the project accountant with a start date, a cost code, a budget confirmation, and the monthly charge -- a fixed amount or a percentage of the burdened cost. This engine reads the artifacts a monthly charge run emits -- the employee register, the project register, the authorizations, the charge ledger, the monthly invoices and the general-ledger positions -- and runs twenty-six deterministic controls over them. Does every monthly charge trace to a valid authorization, noticed in advance and on a real cost code with budget confirmed; does the amount re-derive from the authorization to the cent; is nothing charged before the authorized start; does cumulative project labor stay inside the budget parameter; and does each monthly invoice foot to its charges and tie the ledger. It re-derives every percentage charge with the same truncating-rate primitive that produced it, compares each figure with exact equality, and never writes to a source artifact.
The failures here do not look wrong in a monthly invoice run, which is exactly why they survive to the job that ends up underwater. A fixed amount was authorized and the ledger charges a different one, or a percentage charge drifts a cent from what the burdened cost resolves to -- the invoice still totals cleanly and the project simply carries the wrong number. A charge lands for a month before the authorized start, because the notice was late or the start slipped and the charge did not: the month is real, the amount is right, and the charge should not exist at all. A charge posts to a project or a cost code nobody named, and the money is on the wrong job. And the cumulative charge crosses the labor budget while every individual month looked ordinary. Footing into an invoice is necessary and not sufficient. The engine re-derives each charge where the authorization put it, 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
Eight control families run in registry order over each charge-run 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
employee register, project register, charge authorizations, charge ledger, monthly invoice, GL positions
What it does for you
plain termsA contractor charges its own employees' labor to the projects they work on, and the cost is not free just because payroll already paid it -- the fully-burdened figure has to be charged over, and only where a project manager authorized it in advance. The manager notifies the project accountant ahead of time: a start date, a cost code, a confirmation the labor budget can carry it, and the monthly charge as a fixed amount or a percentage of the burdened cost. Four failures hide inside the monthly run, and none of them look wrong in a column of ordinary numbers. The charge outruns the authorization -- a fixed amount charged at a different figure, or a percentage a cent adrift of what the burden resolves to -- and the invoice still totals cleanly. The charge predates the authorized start, because the notice was late or the start slipped and the charge did not follow it; the month is real, the amount is right, and the charge should not exist at all. The charge lands on a project or a cost code nobody named, and the money is on the wrong job. And the cumulative charge crosses the project's labor budget while each individual month looked ordinary, so nobody notices until the job is underwater. None of these are judgment calls. They are equalities -- a charge against its re-derivation, a charge date against the authorized start, a pair against the authorizations on file, a cumulative total against the budget -- which a deterministic control settles better than a spreadsheet inherited by whoever holds it this year.
The seeded demo runs every control over every charge-run file7. The CLI generates 28 fictional charge-run files -- one clean baseline and one carrying each of the 27 planted defects -- then runs all 26 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 charge foots into its invoice but is a cent adrift of the authorization8. A boundary test moves the monthly charge for one employee-project-period a single cent either side of the resolved figure. chg_amount_matches_auth fires on the cent above and the cent below and stays silent exactly at it -- a charge can foot perfectly into its invoice and still be a cent adrift of the authorization that permits it, and this is the control that catches it.
Nothing is charged before the authorized start9. The whole process exists so the accountant is told in advance, and two boundary tests bracket it: a start anywhere within a charged month still allows that month's charge, while a start the following month makes chg_not_before_start fire; separately, a notice dated the day after the authorized start makes auth_notice_before_start fire, because that is a charge authorized in arrears.
Functional block diagram
engineering · each block links to its sourcePlain terms
- Seeded Charge-Run Files. fictional monthly charge-run files enter the control registry
- Structural Precondition. is the charge-run file complete and the review date legible
- Employee Register. is the employee register sound
- Project Register. is the project register sound
- Charge Authorization. is each authorization complete, in advance, and correctly resolved
- Monthly Charge. does every monthly charge match the authorization that permits it
- Budget. does cumulative labor stay inside the project's budget
- Monthly Invoice. does each invoice foot to its charges
- Ledger. does the ledger tie the general ledger
- Employee, Project & Authorization Registers. the registers and authorizations every charge control resolves against
- Verdict and Findings. every finding, with the reason it exists, ends at a person
Engineering
- Seeded Charge-Run Files. generate_corpus writes one clean baseline plus 27 planted-defect files, at least one for every registered control, 28 files in total. Only the employees, the projects and the authorizations are stated; every authorization's resolved monthly charge, the monthly charge lines, the invoice totals they foot into and the two general-ledger control totals 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 six artifact types or carrying a duplicate, and FAILs an unreadable as_of, so no downstream rule holds vacuously on absent evidence.
- Employee Register. Three controls: every employee fully described, ids unique, and a positive fully-burdened monthly cost -- the base a percentage charge multiplies.
- Project Register. Three controls: every project has a code, a name and at least one cost code, codes are unique, and the labor budget is a positive ceiling.
- Charge Authorization. Eight controls: required fields, a known employee and project, notice on or before the start, a cost code that exists on the project, budget confirmed, a valid method, and a resolved monthly charge that re-derives to the cent.
- Monthly Charge. Five controls: an authorized employee-project pair, no charge before the start month, the amount equal to the resolved charge, the cost code the authorization named, and a well-formed period.
- Budget. Two controls: a hard failure over the labor budget, and a review flag at or above the warning band the project itself carries.
- Monthly Invoice. Two controls: each invoice total equals the sum of that project-period's charges, and every charged project-period is invoiced exactly once.
- Ledger. Two controls: the labor-charge total re-sums every charge line, and the invoice-control total re-sums every monthly invoice.
- Employee, Project & Authorization Registers. The employee register carries each employee's id, name and fully-burdened monthly cost; the project register carries each project's code, name, cost codes, labor budget and warning band; the authorizations carry which employee, to which project, on what cost code, from what start, by what method, and the resolved monthly charge. The authorization, charge and budget controls are all evaluated against these three authorities.
- Verdict and Findings. Findings roll up per charge-run 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-six 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 | labor_report.json, labor_report.md, samples/ |
python -m labor_engine samples | analyze an existing folder of charge-run 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 labor_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 | 10382 passed | 0 when every test passes | none |
Benchmarks
measured demo results| Measure | Result |
|---|---|
| Engine tests10 | 10,382 tests collected live collection from the engine directory |
| Registered controls11 | 26 controls counted from the registry, not from documentation |
| Planted defects12 | 27 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 labor charge posts to a project.
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 charge run into the documented invoice and job-cost review |
| One or more FLAG, no FAIL | REVIEW | a human resolves each flag; a cumulative labor charge that has reached the project's warning band lands here before the next authorization is approved |
| One or more FAIL | FAIL | the charge does not post until the failing control is cleared -- an amount adrift of its authorization, a charge before the authorized start, a charge on an unauthorized project or cost code, an invoice that does not foot, a budget overrun, or a ledger that does not tie |
- Read-only: charge-run 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 any tie-out, and the single tolerant control reads its warning band from the project register rather than inventing one.
- One derivation: a percentage charge is re-derived with the same truncating-rate primitive that produced it, so a mismatch is a real difference and never an artifact of two roundings.
- 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 a charge, moves money, or writes to a source artifact. It reports and stops.14
- It reads the six artifacts a monthly charge run emits. It does not connect to a payroll system, a project-accounting platform, a billing system or the general ledger.15
- It is about whether a labor charge was authorized and computed correctly, not about how the employee was paid. Payroll owns the burdened rate; this engine owns the charge that rides on it.16
- It proves a charge re-derives from its authorization and ties, not whether the authorized method -- a fixed amount or a percentage of burdened cost -- was the right one to choose. That judgment is a reviewer's.17
- All shipped data is fictional and the charge cycle is set in a fictional future. The corpus demonstrates the controls; it is not a record of any real contractor, employee, project, cost code, burdened cost or authorization.18
See it run
control architecture
Integration
how to run itDistribution: public repository, MIT license.
Substantiation
- 1python -m pytest --collect-only -q -o addopts= (labor-charge-automation/)
- 2len(labor_engine.engine.REGISTRY)
- 3distinct rule-id prefixes in labor_engine.engine.REGISTRY
- 4samples/*.json after python run.py
- 5len(labor_engine.model.DOC_TYPES)
- 6labor_engine/tests/test_control_semantics.py::test_charge_matches_its_authorization_to_the_cent
- 7python run.py (labor-charge-automation/); labor_engine/tests/test_planted_defects.py::test_defect_fires_its_intended_rule
- 8labor_engine/tests/test_control_semantics.py::test_charge_matches_its_authorization_to_the_cent
- 9labor_engine/tests/test_control_semantics.py::test_a_charge_may_not_predate_the_start_month
- 10python -m pytest --collect-only -q -o addopts= (labor-charge-automation/)
- 11len(labor_engine.engine.REGISTRY)
- 12len(labor_engine.generate.DEFECTS)
- 13labor_engine/tests/test_planted_defects.py::test_every_registered_rule_has_a_planted_defect
- 14labor-charge-automation/README.md and labor_engine/tests/test_readonly_and_determinism.py::test_analysis_does_not_touch_the_source
- 15labor_engine/model.py DOC_TYPES
- 16labor_engine/model.py module docstring (Scope: authorization and arithmetic, not payroll)
- 17labor_engine/engine.py check_auth_charge_derives
- 18labor_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