Task: Bring ores.compute to the clean standard

The automated half is validate_docs.sh, which passes all 41 components. The manual half was walked item by item and produced two findings, both in the diagrams beside the part overviews. ores.compute.service.puml was written in June and had never been refreshed, so it carried neither the seven generated *_event_registrar units in the new messaging facet nor workunit_dispatcher; ores.compute.wrapper.puml was missing log_publisher. Both are refreshed above the sentinel line, the hand-authored region below it is byte-identical, and both render to their .png again.

The capture script, build/scripts/generate_component_puml.py, resolves simple components only, so a part of a composite is refreshed by hand. That is a codegen-wide finding, and it is recorded here.

Two items that look like findings are not.

• The composite root has no .puml. The audit asks for a diagram beside every component overview, and validate_docs.py inspects part modeling/ dirs only; a composite root's modeling/ holds the group index and the models, and no other composite root in the repository carries one either.
• The client part has no tests/ directory, so it exposes no ctest target. Its own overview already records that as a deliberate gap, and ores.iam/client, ores.workspace/{api,core,service} and ores.http/core share it.

One audit finding was wrong and is not acted on: the reviewer expected wrapper/include/ores.compute.wrapper/app/application_exception.hpp. No such header exists in the wrapper, and none is missing.

The scan covered Qt and Wt code fragments, commented-out code and hand-written duplicates of generated artefacts. It found one of the three: wrapper/src/app/log_publisher.hpp, a two-line redirect to the real header in include/, included by nobody and not listed in the generated source list. It is deleted.

The Qt and Wt hits that remain are prose. Two of them were edit history and are rewritten with the rest of the comment pass. The rest name the retired technology only to say the component does not use it, which the comment rules allow.

The review covered every hand-written and generated file under projects/ores.compute/ plus its org models, against the project comment rules. It found 65 violations in four classes: 10 comments that restate the code, 20 that narrate edit history, 21 end-of-line comments, and 14 that name a technology the component no longer uses.

The fixes split by where the text lives. Comments in hand-written sources and tests are edited in place. Comments in generated files are not touched at all: the prose lives in the org model, so the model is rewritten and the tree is regenerated, which is what carries the fix into the C++ header and the SQL schema comment together.

One violation lived in a template rather than in the component. The generated component_files.cmake files carried "Headers must be listed for AUTOMOC to find Q_OBJECT declarations.", and the text comes from library/templates/ores.cmake.component.files_src.org. The line is corrected in the org source, re-tangled, and the source lists of compute, iam and shell are regenerated, so compute carries no retired-technology comment at all.

The rest of that regeneration is deferred, and this is a codegen-wide finding. The same one-line template change reaches 145 source lists across 22 components, and 123 of them are stale for unrelated reasons and would pull their own drift into this branch. So the components the branch owns are regenerated and the rest are recorded. regenerate_cmake_component_files.py --all --check now reports 123 stale lists outside the branch against 0 for compute, iam and shell.

This item was carried for two rounds as a codegen gap. It was not one, and the way it resolved is worth keeping.

V03 needs a session, and a session needs an account. The commands that create one reported success and left the tables empty, so the fault read as a database problem. It was not.

A principal is "username@hostname". The hostname routes a request to a tenant; the username is what an account row is stored under and what a login looks up. The login handler split the principal on its last '@' and looked up the part before it. The bootstrap handler did not split it at all, so `create-initial-admin super_admin@localhost` wrote an account whose username was `super_admin@localhost`, and every login looked for `super_admin` and found nothing. The provisioning path had the same gap, in the account and in the party association's audit columns.

The rule was written out at five other call sites and missing at these two, which is exactly how a rule that lives nowhere gets forgotten. It now lives in one place, ores.iam.core/messaging/principal.hpp, as split_principal and username_of, and all seven sites call it. The bootstrap handler keeps the full principal only where a principal is genuinely wanted.

Running every generated compute command against the live fleet found three defects the codegen suite did not, because the suite read the projection and never ran the command.

• A create stated one argument more than it read. The `add` command checked for and printed `write_arity + 2` positionals, where `write_arity` counted the whole write record, but the id is minted and never read. The command therefore refused the invocation its own help printed, and accepted one only if the first value was a decoy. The count is now the fields a caller types.
• A replace could not address a row. `set` minted a fresh id, so the store's trigger saw a row no current row matched, took the write for a create, and collided with the natural key's unique index. A replace now takes the id from the caller, which is what the read it follows returns, and its help says so.
• The platform menu was never registered. The platform model generated platform_commands and nothing added it to the repl, so every platform command answered "Wrong command". S01 counted seven units; there are eight.

All three are fixed in the generator, with cases in test_shell_entities.py, and the whole sweep passes.

The fleet was started for V03 and the compute service log showed the node samples arriving and failing:

[WARN] [ores.compute.messaging.telemetry_handler] Failed to decode
node_sample_message: Could not parse document: unexpected character,
expected a JSON value

The process wire format is msgpack (ORES_NATS_WIRE_FORMAT in .env), and every other handler decodes through ores::service::messaging::decode, which reads the process codec. telemetry_handler::ingest_node_sample was the one handler that called rfl::json::read on the raw bytes, so it could only ever read a JSON body. Every node sample the wrappers published was dropped, and nothing failed loudly, because a handler that cannot decode a fire-and-forget publish has nobody to tell.

The handler now calls decode<node_sample_message>(msg) like its siblings, so it follows the codec the publisher used. No test covered this: the handler has no unit test, and the eventing integration tests register their own mappings and never exercise the telemetry ingest path. Only the running fleet showed it, which is the lesson sprint 25 recorded.

The blocker above stops the telemetry entities, not the telemetry protocol. The two are separate models, and the protocol does not need the repository read that the entities do. ores.compute.telemetry is an operation model (#+type: ores.codegen.operation) with three messages: a request and reply pair for the grid summary, and a fire-and-forget publish for the node samples. The generated header keeps the hand-written file's name, order and fields, so no consumer changed, and the check-in diff is the generated marker, the doc comments and one added constant.

The handler stays hand-written beside the model. An operation model generates its protocol, its TypeScript twin and, when :ores.cpp.shell-command.enabled: is true, its shell command units. It does not generate a service handler. ores.iam.account_messages shows this: account_operations_protocol.hpp carries the generated marker and account_operations_handler.hpp does not. So the read the codegen lacks does not block the protocol, and the model lands while the entity question stays open.

The model states :auth: none on node_sample_message. A wrapper node publishes a sample before it has a session, and ingest_node_sample reads it without one, so the message is public. The loader copies that fact to requires_session, which both protocol twins emit and which the shell command generator reads. The hand-written header stated nothing, so both twins claimed a session the publisher never sends.

pull, heartbeat, reap and submit are orchestrations rather than entity verbs, so P04 puts them in an operation model (#+type: ores.codegen.operation) rather than an entity. iam's account_messages.org is the template. The model generates the protocol and, when the shell flag is set, the shell command units. It does not generate the service handler, so work_handler.hpp stays hand-written beside the model and only the protocol moves. That removes the four raw subject literals in work_protocol.hpp, so P02 follows it.

An earlier version of this note said the operation model generates a handler too. The telemetry model disproved that, and the account model confirms the correction.

platform was the component's last hand-written entity, and the smallest: a domain class, a protocol header with one message pair, an entity row, a repository with one read, and a handler with one verb. That is why it went first.

Two decisions shaped the model. is_active is a plain column and not a declared filter, because the generated read answers a filter with filter_not_supported, and advertising a filter the service refuses is worse than offering none. And the natural key is code, declared on the model root, so callers address a platform by its triplet.

The coupling that could have blocked it did not. The junction surfaces the platform code through a join, and that join is declared on the junction with enrich_code, references and code_column, so it is generated and names the platform table directly. A platform model does not disturb it.

The table and the seed are unchanged, so the recreation is unchanged, and the generated SQL now carries the natural-key uniqueness index the hand-written table did not.

Still hand-written: the telemetry handler, and work_protocol.hpp with its three handlers. The work surface is the harder of the two, because pull, heartbeat, reap and submit are operations rather than entity verbs, so it wants an operation model under P04 rather than an entity.

The junction history gap shows up in iam as well, so it is not a compute defect and it is not fixed here.

• A temporal junction exposes no history read. ores_compute_app_version_platforms_tbl carries version, valid_from and valid_to, but its protocol has no versions facet, and neither does any other junction. So a junction's rows have history that no read reaches. P01 only requires the point-in-time read where the model offers it, which is why the item passes, but the offer is missing for a table that keeps the history.

The junction protocol declared app_version_platform_event, and the same defect shows in iam's account_party_protocol.hpp. An entity's announcement earns its place because a generated event registrar publishes it on three action subjects. No event registrar is emitted for a junction, so the record was a wire type no code path read and no subject carried.

P03 says to remove what nothing serves, so the removal is in the derivation: junction_protocol_messages drops the announcement from the entity shape it projects a junction onto. The fix serves dq, iam, marketdata and refdata as well, because they have junctions too. Only compute and iam have a drift-free C++ tree, so only those two were regenerated; dq, marketdata and refdata already differ from their models and carry the stale record until their own clean-up regenerates them.

The check is a rerunnable lever rather than a reading. inventory.py walks from each subject-bearing request, follows every record a served record carries, and adds every record named in a file other than the one that declares it. It reports the records nothing reaches, and it reports zero for compute. Before the fix it reported exactly one.

The regression test asserts the junction derives no announcement on either twin, and the message-set test now expects the record's absence rather than its presence.

Two properties in the drawer were load-bearing and could not be deleted with it. key_field is the entity's declared key on the wire, read by declared_key_field and driving the protocol key record. It now sits on the model root, and the loader reads the root first and falls back to the drawer, so a model can drop the drawer without losing its key. has_change_reason_cache: false on result is a deliberate override the model documents; it moved to the root too and the model-drift gate still counts it as the same accepted exception.

The test that settled it. Removing the drawer alone changed eleven files, all through the key. Removing it with key_field on the root changes none: the regeneration is byte-identical, so the drawer was inert once its two properties were rehomed.

One gap remains outside this component. projects/ores.codegen/modeling/entity_meta_model_cpp_qt.org is the meta-model a new entity is scaffolded from, and it still writes window_title, settings_group, icon and item_var into the drawer it emits. A model scaffolded from it today would reintroduce exactly what M09 removes. That file is codegen's own model, so it belongs to a tooling change, not to this story.

The component's whole generated tree drifted from its models, so the first move was to regenerate it and build. The build failed in ores.compute.core.lib with 13 errors. Five generator defects were behind them, all in projects/ores.codegen/src/codegen/org_loader.py and the templates it feeds. Each is fixed at source, with eleven cases in projects/ores.codegen/tests/test_protocol_name_collisions.py.

• The version facet collides with a real sibling entity. The loader derives app_version_key and list_app_versions_request for the app entity's version history, and the app_version entity derives the same names for itself. The facet now reads the component's entity set and takes the plural as its stem when a sibling named <singular>_version exists. iam hides this because it has no entity named account_version.
• The response payload member collides with the envelope result member. Every response carries ores::utility::domain::result result beside a payload member named after the entity singular. For the result entity both members were named result. The payload member is now result_value, derived once in response_payload_member.
• The versions verb was inferred from a name suffix. A request whose name ended in _versions_request was read as the versions sub-resource, so the app_version entity's own list rendered the version body and could not compile: no request.key, no response.versions. The verb is now stated on the message that answers a sub-resource.
• The service body assumed the payload member was the entity name. It assigned into response.result for the result entity. Both payload sites now read payload_member from the same derivation the protocol header reads.
• The modified-by key could not be built. result.org declared :key_field: modified_by in its presentation drawer. modified_by is an audit column and not a column of the model, so the key record fell back to the primary key while the finders still built key.modified_by and read_any_by_modified_by. The declaration is removed, so result is addressed by its storage key.

check_component_drift.py --component iam-cpp reports no drift both times it was run, so the shared codegen is self-consistent for the component already under test and every change is confined to the shapes compute exposes. Control output in evidence/g01_iam_drift_control.txt.

The hand-written handlers then had to follow the regenerated services, which take a uuid where they took a string. Six call sites in result_submit_handler.hpp, work_handler.hpp, workunit_dispatcher.cpp and batch_workflow_bridge.cpp were migrated.

With all of that, the component regenerates and all five of its libraries build. The regeneration was reverted once, before the fixes, because a commit that does not build is not a verifiable unit.

compute_commands.cpp needs three kinds of edit.

1. Rename the retired request types. get_apps_request becomes list_apps_request, and the same for app_versions, hosts, batches, workunits and results. get_app_version_platforms_by_app_version_request becomes list_app_version_platforms_by_app_version_id_request. save_app_request, save_app_version_request, save_batch_request and save_workunit_request become their put_ counterparts.
2. Read the outcome from the envelope. The retired responses carried success and message; the canonical response carries result of type ores::utility::domain::result. So !resp->success becomes resp->result.outcome ! ores::utility::domain::outcome::ok=, and resp->message becomes resp->result.message.
3. Reshape the writes. The retired save request wrapped the domain object in a data member with a from helper. The canonical put request carries a change record, which is a write plus a precondition, and an intent. The generated apps add unit in projects/ores.shell/compute/src/app/commands/compute/app_commands.cpp builds exactly that, so the migration follows it.

The replace_app_version_platforms_by_app_version operation is retired with no replacement, so publish_package composes its writes and removals, or drops the replace step.

The migration is done. The seven generated units are registered in repl.cpp and linked into ores.shell.application, and the commands they supersede are deleted: list-apps, list-app-versions, list-hosts, list-batches, list-workunits, list-results, add-batch and delete-host. publish-package, dispatch-batch, list-platforms, grid-stats, download-input and download-output stay, because no generated unit covers them.

ores.cli was a second consumer of the retired replace-by-app-version operation, in its app-version import, and it writes its junction rows through the canonical per-row write.

publish-package also lost its read-and-preserve step. That step existed because the retired replace swapped the whole platform set for a version; a per-row write replaces one row, so the other platforms are untouched and there is nothing left to preserve.

The baseline held 69, and 17 are generated now. The platform model replaced five at their own paths, the two operation models replaced three protocol headers, and the telemetry tables and the workflow batch link replaced nine more domain, entity, mapper and repository files when their entity models landed.

Nothing generatable is left. The 52 fall into five classes.

• Messaging handlers the operation models leave hand-written: telemetry_handler.hpp, work_handler.hpp, report_submit_handler.hpp and result_submit_handler.hpp. An operation model generates its protocol and its shell commands, not a service handler.
• The registrar composition point: registrar.hpp and registrar.cpp fold the generated per-entity registrars together. A registrar is generated per entity; the point that composes them is not.
• Analytical reads the codegen does not express: compute_telemetry_repository.hpp/.cpp. A per-node newest row is a DISTINCT ON (host_id) and the live summary calls ores_compute_grid_stats_fn.
• Service and wrapper plumbing: application, host, main.cpp, compute_grid_poller, batch_workflow_bridge, workunit_dispatcher, package_publisher, log_publisher, archiver and http_client. These are processes and transports, not rows.
• Scaffolding: the export.hpp files, the component umbrella headers, compute_storage.hpp and every config/ options and parser pair. A build and a command line are not a model.

Nothing in the component is dead: every file that remains is reached by a caller.

The model binds to none of the thirteen profiles, and it is recorded as a no-match rather than forced onto the nearest one. The table is a tenant-scoped current-state entity with no audit tail. The closest profile, tenant-scoped-junction, assigns only has_tenant_id: and is defined for a junction's two-sided link, not for an entity keyed by one column. readonly-timeseries is for an append-only measurement table, and the link is deleted rather than kept. uuid-identified-lookup fixes a change-reason cache this table has no column for, which the model-drift gate would report as an override.

The model states its own features instead, and check_model_drift.py reports no drift because an unbound model makes no claim the gate can check. ores.iam.login_info and ores.iam.session are current-state entities that bind no profile either, so the no-match is the established treatment rather than a new one.

Regeneration created projects/ores.shell/compute/ with the seven entity command units and their recipes and nothing else: no CMakeLists.txt, no modeling/ directory and no tests/main.cpp, and projects/ores.shell/CMakeLists.txt did not list compute. Every other shell component has that scaffold, so the units could not compile until it was added. ores.compute joined the shell under compute/ with its own group overview and diagram, and the eight units, including the platform unit the model later generated, are registered in the repl and linked into ores.shell.application.

A hand-written compute command family sat beside them, listing apps, app versions, platforms, hosts, batches, workunits and results, publishing a package and downloading bundles. The generated units supersede the list verbs, so those commands are deleted and the hand-written file keeps the five verbs no entity model covers: publish a package, dispatch a batch, watch the grid, and download a job's input or a result's output. Each orchestrates several entities rather than one, which is why no unit carries it. The hand-written list-platforms verb went as well, once the platform model generated a menu that streams the same table.

An independent review of the branch ran before the PR, on the standards axis and the spec axis. It found six things worth acting on, and all six are fixed.

• The bridge removed a link as the wrong tenant. batch_workflow_bridge read every tenant's pending links as the system tenant, then removed the finished link as the system tenant too. The generated removal is tenant-scoped, so that DELETE matched nothing while returning removed: the link survived and the bridge republished step_completed_event on every poll. The stale-link path two lines above already used the link's own tenant; the success path now does too, and it reads the returned status and warns when the removal did not happen. G02's note recorded the intent correctly all along; the code did not follow it everywhere.
• The platform event mapping was never registered. The platform model generated a registrar, and the application wired the other six but not that one, so a platform change reached the in-process bus and never NATS. W01 claimed the pipeline was complete; it was not. The registrar is registered with its siblings now.
• The platform policy let a tenant delete a system row. The policy was widened to for all so a tenant could insert its own platform row, but a single for all policy uses one using clause for select, update and delete, so it also allowed deleting or re-tenanting the seeded system rows. It is now one policy per command: reads see the system rows, and every write is the tenant's own.
• Five of the standard's items were unrecorded. The standard gained B06, G07, H04, V07 and V08 on 2026-09-25, after the Plan table was written. All five apply to any component, so all five were run and recorded, with evidence. The table now carries 47 items: 46 pass, one N/A.
• Two records contradicted the code. The registry comment still called G02 the one item compute does not close, and V04 counted 57 commands where the evidence has 56. Both are corrected.
• Comment and dead-code findings. The bridge and application carried history narration, application.cpp included seven headers it no longer used, postgres_event_source kept an unreachable on_entity_change, validation_ignore.txt kept a dangling comment block, and three documents named things the tree does not have (save_app_request, ir-swap, and a claim that a missing package logs nothing). All are fixed.

The review also confirmed the parts that matter: the runbook's command signatures match the shell, the seed's SHA256 equals the vendored tarball's, the CSV row and column counts match the Academy example, and COMPONENTS_UNDER_TEST carries compute-cpp with the drift gate clean.