Story: Clean ores.utility to the component clean standard

Table of Contents

This page documents a story in Sprint 26. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

ores.utility meets the Component Clean Standard: the items marked All pass, each item that does not apply is recorded with its reason, and ores.utility joins COMPONENTS_UNDER_TEST. Order 3 of 35 in the sprint 26 component clean-up, tier 1 (foundation infrastructure).

2. Status

Field Value
State DONE
Parent sprint Sprint 26
Now Merged as `9b2427bfca` in PR #2155.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-26

3. Acceptance

  • Every checklist item that applies to a component of kind All 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.utility is listed in COMPONENTS_UNDER_TEST, and check_component_drift.py --all passes. The registry entry is the programme gap the task records: the component has no catalogue row and no models, so it cannot join, and V06 is the accepted exception.

4. Tasks

Task State Start End Description
Bring ores.utility to the clean standard DONE 2026-09-26 2026-09-26 Work ores.utility through the Component Clean Standard in order and record each item.

5. Notes

  • Survey on 2026-09-23: 0 entity, junction or operation models; 65 C++ files outside tests, 0 of them generated (0%); 0 messaging headers, 0 of them hand-written.
  • Survey on 2026-09-25, by an agent that did not write the component. 65 production C++ files in 44 headers and 21 sources, 15 files under `tests/`, 141 test cases, 476 assertions, and 1814 files outside the component include it. Both suites pass. Six sub-trees have no consumer outside their own test, about 1560 lines. Eleven umbrella headers have no consumer. The overview is materially false about the component's own shape, and the diagram is 19 days staler than the overview. Full findings and the work items are on the task.
  • Keep the component. The dead sub-trees are a minority, and `rfl` at 876 includers, `generation` at 464, `uuid` at 453, `domain` at 262, `streaming` at 80 and `version` at 45 are the repo's shared foundation.
  • `gzip` had no direct test in the component and sits on the NATS and storage wire. The survey's "zero coverage anywhere in the repo" was wrong: `ores.nats` covers it indirectly through its own compression suite.
  • Outcome, 2026-09-26. All twelve work items landed. The component lost 16 files and 1526 lines, gained a truthful overview and a rendered diagram whose boxes carry their APIs, and went from 476 assertions in 141 test cases to 614 in 128, with `gzip` covered directly for the first time in the component. One generator defect is fixed at source. The survey's per-facet figures above are pre-deletion; the current ones are on the task.
  • Correction, 2026-09-26. The first cut also deleted the eleven namespace documentation headers, 346 lines, on the reading that a header nothing includes is dead. They are restored with their claims corrected, so the component is 16 files and 1526 lines lighter rather than 27 and 1872. See Review row 18 on the task and G08 of the standard, which PR #2162 adds.
  • Verified PASS on `3d1a31520f` over four independent rounds, and merged as `9b2427bfca` in PR #2155 on 2026-09-26 with every CI check green. The verifier found no code defect; the findings and their dispositions are in the task's Review table.

6. Decisions

  • Decide the six dead or test-only sub-trees as a group. For each, either name the intended consumer in the overview or delete it with its test. Deciding file by file produces six inconsistent answers. Recorded as item B06 of the standard.
  • `domain/protocol.hpp` stays and needs a recorded M06 exception. It is a 245-C++-file wire envelope living in a foundation library, the codegen templates depend on it, and it cannot be generated per entity.
  • Prefer the standard facility over a hand-rolled shim. Recorded as item H04.

7. Out of scope

  • The misplaced concerns, which need their own work. `serialization/error_code.hpp` speaks the retired binary protocol and belongs to messaging. `string/short_code_generator` is counterparty-name logic that belongs to `ores.synthetic` or `ores.refdata`. `program_options/shared_domain_registry` is process-global mutable state in a foundation library.
  • The other 145 stale `component_files.cmake` files, which are one repo-wide sweep. This story fixes only utility's two.
  • The registry gap. utility has no catalogue row and no model, so it cannot join `COMPONENTS_UNDER_TEST`.
  • Seven other components' diagrams are stale against the fixed `generate_component_puml.py`, because their headers carry brace-initialised members. Each belongs to that component's own clean-up pass.
  • `to_iso8601_utc` emits a space separator, so its name and the platform overview overstate the format. Captured in the backlog; changing the separator moves the stored and transmitted shape.

Emacs 29.3 (Org mode 9.6.15)