Task: Bring ores.scheduler to the clean standard

ores.scheduler passes the Component Clean Standard for a component of kind Entity.

• Every checklist item that applies to a component of kind Entity passes, with its evidence recorded on the task.
• Every item that does not apply is recorded as not applicable, with the reason.
• Every generator defect found is fixed at its source, with a regression test.
• ores.scheduler passes its own gate, check_component_drift.py --component scheduler-cpp. It joins COMPONENTS_UNDER_TEST, and with it the shared --all list, in the job_instance unit (V06); the shared list deliberately covers only a component whose regeneration leaves the tree fully clean.

Work the Component Clean Standard in its section order, one entity at a time, and record each item's result in the table below. The standard held 48 items when this task was planned and holds 49 now: H05 arrived on main while the branch was open, and the verification pass found it missing from the table and worked it rather than letting a clean-looking 48 stand. scheduler is an Entity component, so the Entity and Protocol items apply as well as the All items.

1. Baseline and inventory (B01 to B06). Record the baseline before any edit.
2. Models (M01 to M10).
3. Protocol (P01 to P06).
4. Generation (G01 to G08).
5. Wiring and data (W01 to W04).
6. Shell (S01, S02).
7. Structure and hygiene (H01 to H05).
8. Verification (V01 to V08), ending with the registry entry.

The defects the survey found, each with the item that fixes it.

1. The model carried an instruction to the generator, warning that no facet of it was safe to regenerate. The generator read that prose as the entity description, so it was projected into the generated domain header. A model is the source of both the code and its documentation: an instruction to the generator belongs in a task, never in the model. (M01, M09)
2. generator_facet_name said generator where the tree says generators/ and the codegen default is plural. A regeneration would have created a second generator folder beside the real one. Measured with git grep -hoP ':generator_facet_name:\s*\K\S+' <rev> -- 'projects/*/modeling/*.org' 'projects/*/*/modeling/*.org', which is the component modeling directories and not the whole tree: at the branch point f7fc9396b7, 26 said generator and 26 said generators; at this head 25 say generator and 27 say generators, because this pass fixed one of the singular ones. All 25 remaining singular spellings are in ores.trading, so this is a latent defect there as well. The count depends on the file set – a recursive search over all of projects/ also finds the template-library prose that documents the property, which is not a model, and returns one more of each – so the set is stated here and the numbers are not portable. It is recorded here and fixed in scheduler only. (G07)
3. nullable_tenant_id: true makes the SQL column nullable but leaves the C++ projection non-optional, so a nullable-tenant entity cannot be generated at all: the domain carries a tenant_id::system() default and the mapper parses the empty string a NULL row yields. Fixed at source in the templates with a regression test. (G05)
4. core/src/builder/job_definition_builder is not a signed-off facet name, it exists in no other component, and its only caller is its own test file. A test-only consumer is not a consumer, so the facet, both files and the test are deleted. (H02)
5. The custom history handler called the service for the definition history, discarded the result and replied success with an empty instance vector: it reported a history it never sent, for a shape it never fetched. The generated history provider registrar replaces it. (W01)
6. rfl::Reflector<cron_expression> was specialised twice, once in the component's reflector header and again inside the handler. Two definitions of one explicit specialisation are an ODR hazard the moment both headers meet in one translation unit. The handler's copy goes with the handler. (H02)
7. scheduler.v1.job-instance-events is published by the scheduler loop and declared in no protocol header and no reference row. (P02, P03)
8. Three of the seven registered handlers — schedule-batch, job-instances.list and status — had no row in the component's messaging reference, and the history row described execution history that the handler did not return. (P03)
9. The model's Presentation drawer named Qt widgets, a database_name field that is not a column, and the request and response classes of the retired hand-written protocol. No output template reads those knobs, so the drawer is removed rather than repaired. (M09)
10. schedule, schedule_batch and unschedule are the canonical put, put_many and delete verbs under legacy subjects, with a request shape that restates the change reason the canonical protocol already carries. The protocol retires them and ores.reporting, their one consumer, moves to the canonical verbs in the same change. (P01, P03, P05)
11. job_instance has a table, a hand-written entity, mapper and repository, and two wire views, but no model, and the two views read a denormalised shape that is a message and not an entity. Modelling it is the next unit of this task, and the registry entry is held until it lands. (M06, V06)

Each of these is a unit of its own, in the order the standard's sections want them.

1. The diagram generator, an H01 follow-up. The diagram pass itself is done; what remains is the tool. build/scripts/generate_component_puml.py cannot regenerate a composite component's module diagrams at all. It resolves projects/<name>/include/ and writes projects/<name>/modeling/<name>.puml, so for ores.scheduler.core there is no such directory. Measured at this head: generate_component_puml.py --project ores.scheduler --dry-run prints "[WARN] No include/ directory found for ores.scheduler" and reports 0 of 1 projects would change, and --project projects/ores.scheduler/core --dry-run prints the same warning for that path, because the script joins the name under projects/ and neither the composite's name nor a module path resolves to the module's own include/ tree. The three scheduler diagrams therefore had to be authored by hand, and they are now hand-owned above the sentinel too. Either the script learns the composite layout or those diagrams lose their automated pass; that is a tooling unit of its own.
2. The shell commands (S01, S02, and then V04). This unit carries a generator gap, which the survey found by reading the facet rather than by trying it. The facet is ores.cpp.shell-command, and its own documentation states that the per-unit files are generated but the aggregator that calls each unit's register_commands "needs a component-scoped archetype and a render-time list", and that archetype does not exist yet. So the unit is not only: add projects/ores.shell/scheduler/ as an adapter part with its four CMakeLists and its overview, add it to the composite's #+parts: and its add_subdirectory list. It is also: write the aggregator archetype, and regenerate the scheduler part's command units for the two operation models and the job_definition entity. Only then can the model enable the facet, which would also close V04, since a generated command is a command to run against the live fleet. The model states the reason for the delay in its * Physical space table, so the facet stays off by a recorded decision rather than by omission.
3. The job_instance entity (M06, V06). Model the table, regenerate the stack, delete the hand-written job-instance entity, mapper and repository, and give the execution event the canonical subject its entity traits generate. ores.scheduler joins COMPONENTS_UNDER_TEST in that unit. This unit is larger than it first reads, and the reason is in the table the entity describes. ores_scheduler_job_instances_tbl is written for TimescaleDB: its primary key is the composite (id, triggered_at), because a hypertable requires the partition column in every unique index, and id is a bigserial, not a uuid. The generated stack assumes one uuid primary key, so two generator features are needed before the model can state this table – an integer surrogate key, and a composite key that a hypertable accepts – and a third for the read policy, which treats SQL NULL as the system scope and is not a variant the RLS template emits. Until all three exist, hand-writing this one table is the honest placement, and the table's own header already says it is designed for a hypertable.
4. The scheduler loop's I/O path (V08). The loop's two decisions now live in core/src/service/schedule_decision.cpp, a file with no database, no timer and no message bus, and it is tested directly against fixed instants: whether a job is due given the instant it last ran, and the next minute boundary. What the loop itself still does untested is the part that needs the database and NATS together – seeding last_run from the job-instance table, writing the instance on each firing, publishing the instance event, and choosing the handler by action type. Testing that needs a driven tick and a database fixture, which is a unit of its own rather than a paragraph of this one.
5. The model-property reference. Neither is_enum nor the is_value_type added here is documented in a meta-model page; the backlog already records the gap as "Update the codegen key and columns meta-model doc", and the template variable reference now carries both rows.
6. The drift check's comparison, which is repository-wide. The in-place check_component_drift.py runs git diff with no path filter, so an uncommitted edit anywhere in the repository fails it, whatever the edit is. The message blames "a generated file was hand-edited, or its .org model changed", which is not what happened. The check was run with one uncommitted documentation edit in the tree and it failed on that file, naming it in its --verbose diff; once the edit was committed, the same command reported no drift. This is a tool defect rather than a scheduler one, and it is recorded here rather than fixed here: scoping the comparison needs the component's output paths, and the change belongs to the codegen tool with its own verification, not to a component pass. Its --dry-run mode is unaffected, and its message already points at the right command.
7. Ninety-three stale CMake source lists, in twenty-three other components. regenerate_cmake_component_files.py --all --check exits 1 at this revision over 93 component_files.cmake files, none of them scheduler's; scheduler's own two lists are current. The cause is one template change that other components have not regenerated against, which is the same shape as the inventory-table staleness this pass did fix: a generated file whose generator moved on. It is a sweep across twenty-three components, not this component's business, so it is recorded rather than fixed. The component-scoped claim in G06 and V05 is what this pass can stand behind.
8. The SQL ER diagram, which no gate covers. projects/ores.sql/modeling/ores_schema.puml is generated by projects/ores.codegen/plantuml_er_generate.sh and carries each entity's model prose as a note. The committed diagram is dated 2026-09-17 and predates several model changes: it still held this component's deleted "DO NOT regenerate" note, which is how the staleness was found. Regenerating it here was tried and reverted, because the change is not this component's: measured at this head with ./projects/ores.codegen/plantuml_er_generate.sh and then undone with git checkout -- projects/ores.sql/modeling/, the regeneration rewrites the .puml by 510 insertions and 112 deletions across 38 hunks — 930 lines of unified diff — and only 6 of those changed lines mention the scheduler at all, so the rest is other components' notes and column order — the same one-cause sweep as the stale component_files.cmake files, not this component's business. The scheduler note is one instance of it. No workflow runs the script, so nothing reports the drift; the fix belongs to the sweep, or to a new gate over plantuml_er_generate.sh.
9. The migrated consumer has no test of its own. ores.reporting's report_scheduling_service.cpp is the one file this pass rewrote outside the component, and its correctness rests on the build and the live run. A test belongs with that component's fixtures. While checking it, this pass found its eventing suite failing four cases in this environment – report_instance, report_definition, report_type and concurrency_policy each wait for a NATS notification that never arrives. The failures are not this pass's: git stash of the one file this pass changes leaves the same four failing, the branch touches nothing in that component's eventing path, and the test files are unchanged from main. The likely cause is the same sandbox limit that keeps the domain services from starting.
10. The shell script library is incomplete, and nothing gates it. The tangle writes 1202 scripts into projects/ores.shell/scripts/library/, and the committed tree holds 1085: 12 recipe groups' scripts were never committed, so a person reading the library from a clean checkout does not find them. This unit commits its own six and leaves the rest, because they belong to other components' recipes, but the gap is worth a sweep of its own: the inventory check gates doc/recipes/shell/shell.org and no check compares the library with the recipes that generate it. The same file carried six merge-conflict markers from an unresolved merge that was committed; this unit removed them and regenerated the file.

Every source file under src/ in the three modules, against the component's three test binaries. "Generated" is a reason in its own right: the file is the output of a template, so a test of it tests the template, and the template is covered by the codegen suite that every component shares. The hand-written files with no test are the ones that need a live database, a live NATS server or a driven event loop to be exercised at all, and they are the V08 work item; each carries its reason in the table.

The branch was rebased twice while it was open, the second time onto 24 newer commits. Those commits are other environments' work, and three of them bear on this task:

1. H05 arrived. The standard gained the documentation item after this checklist was written. The table therefore held 48 rows for a 49-item standard, and the prose in the plan said 48. Both are corrected, the item is worked, and its ER clause is recorded as an open finding. This is the reason the record's plan sentence now reads "held 48 items when this task was planned and holds 49 now".
2. ores.testing deleted= run_coroutine_test.hpp *as unused – "no consumer anywhere in the tree, not even its own test", its commit says. That was true of main and false of this branch: the three handler tests added here are its consumers, and without it the component's core suite does not compile. The header is restored with those consumers, and ores.testing's generated source list carries it again. The deletion's premise was sound when it was written; what changed is that a branch in flight added the user.
3. A stale inventory table, one line of it. regenerate_physical_space_inventories.py --check arrived on main red: the ores.doc.knowledge group's table still described ores.doc.knowledge.investigation with the prose from before commit 822a433087 changed that archetype's description without regenerating the parent that lists it. This branch touches neither file, and the table is generated, so the check was run in its writing mode and the one-line result is part of this branch. The alternative – record the red gate and leave it – would make this task's V05 claim false for a reason that is not its own.
4. A build failure that did not reproduce. The first whole-tree build after the rebase failed in the eventing test with twenty errors, the first of them "#include nested too deeply". The same file compiles on its own from the same tree, and the next whole-tree build passed that file. The one difference was that an in-place drift check was regenerating the component's files while the build read them. That is a caution, not a proven cause: the failure is not reproducible with the tree still, and the drift check has a --dry-run mode for exactly this reason. The real failure underneath it was the deleted header, which is item 2 and did reproduce.

Recorded because they were mine, not the generator's, and because two of the three were silent.

1. default_value: "true" on a boolean column. The model quoted the value, and the generator renders {{default_value}} verbatim, so both generated headers carried bool is_active = "true"; – a string literal initialising a bool. It compiles by pointer-to-bool conversion, with no diagnostic under this project's flags, and happens to mean true, which is why no gate saw it. The sibling model ores.marketdata.feed_binding writes the value unquoted and generates the clean bool enabled = true;. The scheduler model now does the same. No check in the codegen suite covered the class – a string default on a scalar column – so the defect reached the tree twice over, once through the model and once through the absence of a guard. The guard now exists: org_loader refuses a quoted :default_value: on a bool, an int or a float rather than stripping the quotes, so the model reads the way the C++ does. Regression test test_quoted_scalar_default.py, three cases: the quoted bool is refused, the unquoted one renders as a scalar, and a quoted string default still renders quoted.
2. A dead symbol the census missed. cron_scheduler had no consumer anywhere: not the service, not a test, only its own source and the CMake file list. The census classified symbols by their consumer outside the component, so a public class with no consumer at all still read as "component infrastructure". Its four methods duplicated the generated service and repository, so it is deleted.
3. A behaviour the protocol move cost. Reconciliation lost per-job failure reporting: the retired batch subject reported failures by id, and the canonical put_many is all-or-nothing. Reconciliation now sends one put per definition. Neither the task nor the PR description admitted this before the verification pass named it.

The single-natural-key index now scopes on has_tenant_in_pk OR nullable_tenant_id, while its composite-natural-key sibling scopes on has_tenant_id. The two agree for every nullable-tenant entity, which is what this component needed and what the regression test pins. They would disagree for an entity that has a tenant and a single natural key but keeps the tenant out of the primary key for another reason – a current_state or system_scope table – which would get an unscoped index where its composite sibling would be scoped. No such model exists in the tree today, so this is a hole rather than a live defect, and it is recorded here instead of widened into a template change with no entity to test it against. A {{! ... }} comment now sits above the single-key branch in ores.sql.schema.domain_entity_create.org telling the next reader to read the two branches together; it emits nothing into the SQL and changes no output, which the shared gate confirms.

The same branch had a second, live defect that the review found: scoping the index by tenant does not make SQL NULL one tenant, because PostgreSQL treats NULLs as distinct in a unique index. Two system-scope rows could therefore share a job_name, which the model prose says they cannot. That one is fixed: the index states nulls not distinct, the live database refused the duplicate it had accepted, and two tests pin the clause. The asymmetry above remains a hole because no model exercises it; this one was exercised by every scheduler deployment.

The generated sample value for a jsonb column was a faker word, because the column's C++ type is a string and the generator template falls back to a word for a string. A word is not JSON, so the insert the generated eventing test performs was refused by PostgreSQL: invalid input syntax for type json, Token "CD" is invalid. Nothing before the live run could see it – the SQL was valid, the model was valid, the C++ compiled, and every gate compared generated text with generated text. Codegen now fills an empty object for a jsonb column that states no generator expression, in one place, so every template site that falls back to a faker word picks it up; regression test test_jsonb_sample_value.py. The two components that also have jsonb columns, marketdata and workflow, will pick it up when their own refresh happens – both already carry pre-existing drift, workflow by 65 files, so refreshing them here would bury this change in unrelated work.

The three that the regeneration depends on. Each is fixed at source with its own regression test, before the regeneration that uses it. The pass went on to find two more, later and in other places – the quoted-scalar-default guard, in the section on what the verification pass found, and the jsonb sample value, in the section on the live run – so G05 and the Result count five in total and name five test files. This section details the three without which the regenerated artefacts would have been wrong.

1. A nullable tenant had no C++ representation. nullable_tenant_id made the SQL column nullable and left the domain member a non-optional tenant_id::system()=, so a NULL row either threw in the mapper or was read back as the system tenant. The domain and entity tenant is now an optional and the mapper round-trips NULL to nullopt. The flag is lifted from the SQL drawer onto the entity as nullable_tenant_id. Regression test: test_nullable_tenant_optional.py.
2. A nullable-tenant natural key was not tenant-scoped. The single natural-key unique index was scoped by has_tenant_in_pk, which is false for every nullable-tenant entity, so job_name came out globally unique rather than unique within a tenant – while the composite-natural-key branch beside it already scoped by has_tenant_id. The two branches now agree for a nullable tenant. Regression test: test_nullable_tenant_natural_key_index.py.
3. A value type had no entity representation. A column whose :cpp_type: is a domain class – cron_expression, which wraps a validated string – was passed through to the repository entity, where sqlgen rejects it with a static assertion. The model now opts in with :is_value_type: true: the entity member is the string the type wraps and the mapper converts through the type's own to_string() and from_string(), the idiom the tenant uuid already uses. Regression test: test_value_type_column.py.

The component also needed two hand-written pieces of plumbing that generation does not reach: the core target links ores.history.core for the generic history provider, and the service target links ores.eventing.core and registers the generated change-event mapping in its application, as ores.compute does.

Manual QA scenarios (scaffolded via compass add test_scenario) that verify this task. Link new ones here as they're created; the scenario doc itself links back via its "Verifies task" field.

The repository's Claude review job reviewed the PR on 2026-09-26 at revision f18c4e0c87, and the commits after it answer every item. Each item and its decision:

The pass is complete for the component's existing surface, and verified at the head after the rebase onto the current main.

What it produced:

• job_definition, the component's one entity, is described by its model and generated end to end: domain, JSON, table and table I/O, entity, mapper, repository, service, handler and the canonical protocol. The hand-written versions of all of those are deleted, and so are the builder facet whose only caller was its own test, the dead cron_scheduler, the second reflector for cron_expression, and the hand-written protocol header.
• The generated tree matches the models: the drift check passes in its writing mode and the shared list passes in dry-run mode.
• The suites pass: the codegen suite at 612, and the component's three at 38 assertions in 8 cases, 84 in 22, and 26 in 10.
• The database recreates from scratch and the schema reads back as the model says: a nullable tenant_id, a tenant-scoped unique index on the natural key, both triggers, and the job-instance policies.
• Six generator defects were found and fixed at source, each with a regression test, one more shape is refused rather than generated wrongly, and the whole tree builds with the component and its consumer.

What it does not do, and why:

• job_instance stays hand-written. Its table is a TimescaleDB hypertable with a composite primary key and a bigserial surrogate, which the generator cannot state yet, and its read policy treats SQL NULL as the system scope, which the RLS template does not emit. Modelled generation for it is the first follow-up unit.
• The shell part is absent. The ores.cpp.shell-command facet generates the command units but not the per-component aggregator that registers them, so the unit needs a template that does not exist. The model disables the facet with that reason in its * Physical space table.
• Every other open item, with its size, is in "What this unit leaves open".

Nothing in this record is a plan. Each row names what it rests on: a check that was run, with its file under evidence/ where the output is a file, and a census, a review or a registry where that is what the item asks for and no command produces a transcript. The rows whose evidence is a census or a review say so in their own text.