SYS.22 / CONSTRAINTS
The Constraints Engine
The Constitution is judged. Constraints are the part of it that can be measured — and run.
What a constraint is
A check this product already knows how to perform, plus something to compare against.
A constraint names a check — usually one of the detectors — a threshold or a ratchet, a severity, an enforcement level (report, warn or block), where it came from, and what class of check it is. It never carries a command.
What it can check
Four kinds of check, and one that always declines.
| Kind | What happens |
|---|---|
| detector | A Finding Engine run’s status is mirrored; a succeeded run counts findings in scope. A capped run is UNKNOWN |
| custom rule | The same, for one of your own rules. A rule that does not exist is NOT_SUPPORTED |
| metric | A measured number, against a threshold and/or a ratchet |
| manifest script | NOT_SUPPORTED — this installation does not execute project scripts |
| none | NOT_SUPPORTED, always. Recorded so that the gap is visible |
Measured metrics include finding counts, critical findings, vulnerable dependencies, import cycles, hub nodes, deleted test files, suppression counts, and whether strict type checking, linting, a test runner and CI are configured. Coverage metrics are NOT_SUPPORTED with the reason stated, because reading them would mean running your suite.
How a set of constraints concludes
One rule, and it is the conservative one.
concluded: PASS · WARN · FAIL did not: NOT_RUN · RUNNING · SKIPPED · NOT_SUPPORTED · UNKNOWN
A set folds to PASS, WARN, FAIL, INCOMPLETE or NONE. Any enabled constraint without a conclusion makes the set INCOMPLETE; FAIL beats INCOMPLETE; INCOMPLETE beats WARN and PASS. A disabled constraint is ignored entirely.
In other words, a set cannot come out green while something in it did not run. That is the whole design.
Where constraints come from
Discovery seeds what is absent and never overwrites what exists.
- Detected
VERIFIED, with the file as evidence: test, lint and typecheck scripts from a manifest; strict type checking from a compiler configuration; the presence of lint, test-runner and CI configuration.- Generated
INFERRED, and always a floor rather than an aspiration: no committed secrets; vulnerable dependencies, critical findings, suppressions and import cycles do not increase; no test file deleted. The ratchets are set from the first measurement, so they encode where you are rather than where somebody hopes you will be.- Yours
- Constraints you add or edit. Versions are appended rather than replaced, so a threshold that moved leaves a record of having moved.