Task: Bring ores.service to the clean standard

ores.service passes the Component Clean Standard for a component of kind Protocol.

• Every checklist item that applies to a component of kind Protocol 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.service is listed in COMPONENTS_UNDER_TEST, and check_component_drift.py --all passes.

Work the Component Clean Standard in its section order, one entity at a time, and record each item's result in the table below.

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 standard grew while this task ran. It held 47 declared items when the task was planned, gained B06, G07, G08, H04, V07 and V08 in the 2026-09-25 infrastructure survey, and gained H05 on trunk during the work. This record covers every item of the 49-item checklist as it stands on the branch.

The record below was written by the agent that did the work. The survey it builds on is in the Notes, and it was run 2026-09-23 by an agent that did not.

Survey, 2026-09-23, at the sprint's start, by an agent that did not write the component: 0 entity, junction or operation models; 21 C++ files outside tests, 0 of them generated; 2 messaging headers, 2 of them hand-written. Every claim was re-verified on this branch, and the file count moved from 21 to 20 because the duplicate host runner pair was deleted.

• What the component is. It is the envelope around a service, not a service: the lifecycle, the host body, the JWT-to-context step, the handler helpers, the heartbeat and the readiness notification. It owns no model, no subject and no wire type, so the model, protocol-generation, SQL and shell items are not applicable rather than unexamined.
• Why it is not in the registry, and cannot be. COMPONENTS_UNDER_TEST lists component_catalogue.org entries, and a catalogue entry is a modeling directory codegen can read. ores.service has none. The standard records the gap and names the components that share it; this task adds ores.service to that list rather than inventing a second registry.
• The three duplications were the real findings. The lifecycle tail existed three times, the host-runner envelope twice, and the workflow header vocabulary twice across two components. Each is the kind of copy that agrees until someone edits one side.
• The generator defect was found by doing the diagram, not by looking for it. exit_code is the only enum in the tree that documents its enumerators with Doxygen trailing comments, and the parser dropped every value because of them. Only a refresh that was read line by line found it, which is the standard's own G07 caution in practice.
• The test suite is the largest single piece of work. The component had main.cpp and nothing else, so a surface that every service depends on had no executable specification at all. The new suite is 7 files and 42 cases, and it pins the things a refactor could break silently: the exit-code numbers, the permission wildcards, the JWT rejection classes, and the readiness datagram's exact bytes.
• The standard moved under the task, twice. It declared 47 items and held 48 when the survey ran, gained B06, H04, G07, V07 and V08 in the 2026-09-25 infrastructure survey, and gained H05 on trunk while this work was in flight. The count sentence was corrected on trunk at the same time, so the local correction this branch carried was dropped in the rebase as stale. The record below covers the 49-item checklist as it stands on the branch, H05 included.
• The whole-tree build earned its keep twice. The first tree-wide run failed on a defect no narrower target could see: boost::asio::signal_set is not movable, so the helper that returned one by value compiled for the library and for the component's tests – neither instantiates the template – and broke only where a service binary does. The helper now fills a set the caller constructs. The second run, on the next rebase, failed on trunk rather than on this branch: the workflow shell and api scaffold merged in PR #2173 left ores.shell.workflow.tests without a main.cpp and left the api library declared INTERFACE while its generated sources sit beside it uncompiled, so ores::workflow::domain::operator<< was undefined and every executable linking ores.workflow.core.lib failed, and ores.shell.workflow had no overview or diagram for validate_docs.sh to find. None was this branch's, all three were already being fixed on feature/clean-workflow, and PR #2179 landed that fix; the rebase onto 8a16c7a4f0 cleared all three, and V01 and V05 are green on the final tree. The local targets were green throughout, which is the argument for V01.
• The branch was rebased four times, last onto trunk cc279a2092, because trunk kept advancing past the base the work started from. The baseline in B01 is the trunk the survey ran against; two rounds of independent verification found that several counts had been measured on an earlier head rather than the final one, so B06, V02, V05, P03 and the Notes were re-measured on the branch tree rather than on an earlier head. These numbers describe the code this patch carries, so a later rebase onto a newer trunk does not change them; a change to the code does, and then they are measured again. Three trunk advances during the work moved the base under the branch and invalidated the numbers twice, which is the finding both verification rounds made.
• The independent verification failed the first cut, and it earned its keep. Two blocking findings: a generated refdata handler had been hand-edited while its model kept the deleted symbols, which the tree-wide drift gate cannot see because refdata is not in the registry, and all three readiness tests were compiled away by a feature guard placed above the include that defines the macro it tests. Four accuracy findings followed: three diagram gaps, three false documentation claims, four more tests that a stub would pass, and five census numbers measured on an older tree. All are fixed. The lesson worth keeping is the first: a change that renames a symbol used inside a generated file needs the per-component drift check for that component, because --all covers only the registry, and only the generated-file rule catches it. CI was green throughout, on every head, because its drift job is --all too. The second round confirmed both blockers fixed and failed the record again, on five numbers measured before the last rebase and on that one over-claimed test. The counts here are re-measured on the head that will land, and the lesson is explicit: measure on the tree you are about to push, not the one you built.

Work items, and their outcome.

1. Collapse the three service lifecycles onto one tail. Done, see H02.
2. Merge the two host-runner envelopes and their duplicate option struct. Done, see H02.
3. Declare the workflow step command headers once, at their owner. Done, see P03; the engine and four consumers follow.
4. Delete the public API nothing consumes. Done, see B06.
5. Move notify_systemd_ready() into its facet namespace. Done, see H01.
6. Fix the diagram generator, then refresh and hand-author the diagram. Done, see G05 and H01.
7. Rewrite the overview. Done, see M10.
8. Give the component an executable specification. Done, see V02, V07, V08.

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.

No scenario applies. No user reaches the component directly; it is a library that the service binaries and three tools link. The component suite, the whole-tree build and the codegen gates are the evidence.

ores.service meets the 49-item Component Clean Standard short of the registry entry, which the standard's own exception rule covers.

The component is hand-written infrastructure of kind Protocol. It owns no model, no subject and no wire type, so the model, generation, SQL and shell items are not applicable rather than unexamined, and the work is structural: three duplications collapsed, the public API nothing consumes deleted, one generator defect fixed at source, the missing test suite written, and the diagram and overview rebuilt.

What changed. The service lifecycle existed three times and is now one registration-and-drain tail in service_lifecycle.hpp. The two host runners declared byte-identical options structs and repeated the same envelope, and now share one. The workflow step command headers were declared in ores.service and written as raw literals in the workflow engine; they live in ores.workflow.api now and both sides use them. exit_code_name, to_exit_code, host_runner_sync_options and the exported make_context_from_jwt declaration had no consumer and are gone. notify_systemd_ready moved into the namespace of its facet.

What was found. The component-diagram parser dropped any enumerator carrying a Doxygen trailing comment, which is how exit_code is written, so a refresh would have deleted the seven values; the parser is fixed with a regression test. The whole-tree build found a defect no narrower target could compile, a boost::asio::signal_set returned by value. No item's evidence is a proxy, and three trunk advances forced the numbers to be measured again.

Verification. Two independent verification rounds failed the branch and both were right: a generated refdata handler had been hand-edited while its model kept the deleted symbols, which the tree-wide drift gate cannot see because refdata is not in COMPONENTS_UNDER_TEST, and the three readiness tests compiled to nothing because their feature guard preceded the include that defines the macro it tests. Both are fixed at source, and the record's numbers were re-measured twice. The third round returned PASS+NOTES, reproduced every number in this record, and falsified the strengthened tests by mutation. Its two notes are applied.

Evidence. The whole tree builds with exit code 0. The component's suite passes 42 cases and 118 assertions, ores.codegen 709, and ores.compass 255 with 1 skipped. Every codegen gate is green, including validate_docs.sh over all 40 components. The component changed no SQL and the database was not touched.

The one exception is V06. ores.service cannot join COMPONENTS_UNDER_TEST: the registry holds catalogue components, and a catalogue row is a modeling directory codegen can read. Listing the name would fail --all with "Unknown component" rather than exempt it from anything. That is the infrastructure-tier gap the standard records, and it stands in place of the acceptance criterion that names the registry entry.

The fleet was not provisioned in this environment, so the suites ran with PostgreSQL up and NATS down, and service_lifecycle.hpp's entry points are exercised only by a running fleet; the reason is recorded under V08.