Component Clean Standard

Each item has an identifier, the kind of component it applies to, and the evidence that proves it. The kinds are:

• All: every C++ component.
• Protocol: a component that serves or sends NATS messages.
• Entity: a component with entity, junction or operation models, and so with SQL, a repository and a service.

An item that does not apply to a component is recorded as "not applicable" with the reason, never skipped in silence. An item that cannot pass is recorded as an accepted exception: the component joins the registry, every gate runs against it, and the item it does not pass is named in ACCEPTED_EXCEPTIONS in projects/ores.codegen/scripts/component_registry.py with its reason and the person who accepted it.

Keeping the component out until every item passes is the alternative, and it withholds every gate from the component in the meantime. A component with one unverifiable item is then checked by nothing at all, which is worse than the gap it was excluded for. So the registry records the gap instead, and check_registry_exceptions.py refuses an exception that names an item the standard does not define, states no reason, names nobody or carries no date, against the standard's own item list. What it cannot do is decide whether a reason is good enough; that is the reviewer's, and the record is written so the reviewer can see it.

Take an exception only when the item cannot be made to pass where the work is done – a check that needs a live fleet, a tool that cannot draw what the item asks for. An item that is merely unfinished is not an exception; it is unfinished work, and the component waits.

Work in the order of the sections. Fix every defect at its source: a template, org_loader.py, a profile or a model. Never edit generated output, and never carry a shim for backwards compatibility: the database is recreated from scratch, so there is no migration to protect.

Work one entity at a time. Regenerate, build and test after each one. Sprint 25 found five generator defects that a diff, the drift check and a typecheck all missed; only a build and a test run found them.

• A check that writes is a check that damages. Run the drift check with --dry-run while a model is being drafted: an in-place --all run overwrote sixteen hand-written files. Never run a writing gate while a build is reading the tree: a whole-tree build failed with "#include nested too deeply" while the in-place drift check regenerated that component's files under it, and the same file compiled once the tree was still.
• The drift gate cannot see an unwired registrar, and the eventing tests register their own mappings. Check W01 by reading the composition points.
• A rename that the templates cannot carry yet is undone, not forced. Rename the hand-written half of a pair before the generated half supersedes it.
• Only a live run finds some defects: the service grant and the notify trigger wiring were found by a running fleet, not by ctest.
• An unattended replay of commands can destroy an environment. Declare destructive commands in their models.

A survey of four model-free infrastructure components, ores.platform, ores.utility, ores.security and ores.geo, run on 2026-09-25 by agents that did not write them, added items B06, H04, G07, V07 and V08; the ores.security pass added G08; and a later codegen pass made the documentation requirement explicit as H05. The standard now holds 49 items. The findings behind the new items:

• A component can pass every gate and still be unclean. All four passed validate_docs.py, carried no leftover artefact and broke no naming rule, and still held dead public API, an overview that contradicts the tree, and tests that cannot fail. The gates check structure, not truth.
• A consumer census finds what a compile cannot. Code whose only caller is its own test compiles, links and passes forever. In ores.utility six sub-trees, about 1560 lines, exist only to satisfy their own tests.
• A test that cannot fail is worse than no test, because it reports confidence it did not earn. The ores.geo suite passes whenever its lookup fails for any reason, and a backlog capture had already recorded the bug the suite was meant to catch.
• A generator defect can make the obvious fix destructive. Refreshing ores.platform's diagram deletes correct content, because the parser loses brace sync on a one-line enum class. Seven components hold a one-line enum class in a header, which is what the parser reads, so the defect reaches all seven. Run the generator's dry run and read its diff before accepting a refresh.
• An automated diagram pass is a skeleton, so the manual pass is not optional polish. The pass reads data members only. An interface, and any class whose content is methods, arrives as an empty box; a class with state arrives with its fields and no API; and a facet of free functions does not arrive at all. The first ores.platform diagram passed a refresh check, a render and a file review, and still showed an environment_provider with no methods and a class relationship the code does not have. Read the rendered image before calling a diagram done.
• The same defect recurs across components. 147 component_files.cmake files are stale for one reason: the marker template landed in commit 3a40c9c57e and no component regenerated. Where a defect has one cause, fix it once and record the sweep, rather than 147 times.
• A registry that admits only model-bearing components excludes the whole infrastructure tier. COMPONENTS_UNDER_TEST lists model-bearing catalogue entries, so a component with no models can never join it, and deleting one leaves the same gap. Six components now share it, the two retired by deletion and the four surveyed.
• Prefer the standard facility. ORES_NO_UNIQUE_ADDRESS and a hand-rolled unreachable() existed beside [[no_unique_address]] and std::unreachable(), which MSVC, AppleClang and GCC all provide. A shim that outlives its need is dead weight with a portability excuse.
• A duplicated implementation is one finding, not two. Two near-identical functions that differ only in the shape they return are one behaviour, so the fix is one helper behind both public functions, and the survivor keeps the consumers the pair had. In ores.platform the two MAC enumerators looked test-only from outside, and each was in fact load-bearing through a different production caller, so deleting either half would have broken the telemetry trace identifier.
• A rule that names no exemption deletes what it should keep. G02 said dead headers go, and two passes read that as licence to delete twelve namespace documentation headers: ores.utility.hpp with its ten facet headers, and ores.security.hpp. Their content is an empty namespace and the @brief doxygen renders, and the outermost one is the description the diagram conventions read, so a consumer census reports them as dead when they are the documentation. G08 states the exemption, and the maintainer caught the second deletion.
• Verify with an agent that did not write the code, and expect it to fail the record rather than the patch. The deletion this standard's first story performed was sound; what the verifier failed was the record's own claims about it.

ores.scheduler is the first component of kind Entity to run the standard, and the first whose model defines one entity while the rest of the component stays hand-written. What it added:

• A source that needs a clock, a database and a message bus at once is not untestable; it is welded. Extract the decision into a unit that takes the clock as an argument, test it against fixed instants, and record the I/O that remains. The scheduler loop's two rules – is this job due, and when is the next minute boundary – moved into schedule_decision.cpp, which holds no timer and opens no connection, and the loop was left with one recorded reason instead of being the coverage gap.
• A class no test can link is a finding, not an internal detail. The one hand-written repository class without the core export macro was the one class with no test, and its generated siblings all carry that macro. Where a hand-written twin of a generated artefact differs from it, the difference is the defect.
• A cited figure is evidence, so a stale one is a defect. An evidence file kept the core suite at the count it held before the hand-written cases were added, while the record row beside it carried the current count. Re-measure every number at the head the record names, and re-measure the set together.
• A private constructor is an invariant, not an obstacle. The cron expression admits no unvalidated instance, so its test enters through from_string and asserts the parse, rather than reaching past the guard or befriending it.
• Model prose is the generated documentation. An instruction to the generator written into a model arrives in the generated header as the entity description, so a model states facts and a task states instructions.
• A unique index on a nullable tenant does not make NULL one tenant. PostgreSQL treats NULLs as distinct in a unique index unless the index says nulls not distinct, so a tenant-scoped natural key still admits duplicate system-scope rows. The ores.scheduler pass shipped the index, its own verification passed it, and only a live duplicate insert – two NULL-tenant rows with the same name, accepted – and then the reviewer found it. Where a scope value can be NULL, say what NULL means to every constraint that reads it, and prove it against the database rather than the generated text.