Task: Bring ores.platform to the clean standard

Table of Contents

This page documents a task in the Clean ores.platform to the component clean standard story. It captures the goal, current status, acceptance, and any notes or results.

1. Goal

ores.platform passes the Component Clean Standard for a component of kind All.

2. Status

Field Value
State DONE
Parent story Clean ores.platform to the component clean standard
Now Nothing. The work is done and verified.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-25

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.platform is listed in COMPONENTS_UNDER_TEST, and check_component_drift.py --all passes.

4. Plan

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 B05). Record the baseline before any edit.
  2. Models (M01 to M10).
  3. Protocol (P01 to P06).
  4. Generation (G01 to G06).
  5. Wiring and data (W01 to W04).
  6. Shell (S01, S02).
  7. Structure and hygiene (H01 to H03).
  8. Verification (V01 to V06), ending with the registry entry.
Item Result Evidence
B01 pass Baseline before any edit. `check_component_drift.py –component platform –dry-run` reports a component it cannot name, because there is no catalogue row. `regenerate_cmake_component_files.py –component ores.platform –check` reports 2 stale files, `src/component_files.cmake` and `tests/component_files.cmake`, each missing the generated marker.
B02 pass 0 entity, junction, operation and message models. `modeling/` holds `component_overview.org`, `ores.platform.puml` and `ores.platform.png`.
B03 pass 32 production C++ files classified at baseline, 23 headers and 9 sources, plus 7 files under `tests/`. The deletions leave 30, which is 21 headers and 9 sources. Five public artefacts have no consumer anywhere: `unreachable.hpp`, `attributes.hpp`, `process::get_hostname()`, `:open_c_file()` and `datetime::is_valid_iso8601_date()`. `network_info.cpp` duplicates the MAC enumeration in two near-identical functions. Three of the nine source files have no test.
B04 not applicable The component serves and sends no NATS subject and has no protocol header.
B05 pass The only live capture naming the component is this story. No in-flight branch touches it.
M01 to M08 not applicable No org model, so there is no format to migrate, no profile to bind, no feature namespace, no table, no wire type, no junction, no custom type binding and no model fragment.
M09 not applicable No model, so no legacy fragment to find in one.
M10 pass The overview now states the real dependencies, Boost and reflectcpp rather than ores.utility, lists all five facets, explains why a model-free component has no generated types, links eight related documents, and carries `#+updated: 2026-09-25`. `validate_docs.py` passes.
P01 to P06 not applicable No entity and no protocol, so no canonical verb, no owned subject, no registrar, no operation model, no consumer to migrate and no event cache.
G01 not applicable No model, so nothing regenerates.
G02 pass The dead public API is gone, and the duplicated MAC enumeration has collapsed to one helper.
G03 pass The two `component_files.cmake` files are regenerated and carry the generated marker.
G04 not applicable No generated code to review against the component's best hand-written code.
G05 pass Two parser defects are fixed at the source, each with a regression test in the codegen suite. A one-line `enum class` no longer desynchronises the brace tracker, and a wrapped parameter list no longer reads as a field. The enum test fails five of six against the unfixed parser and the wrapped-declaration test fails both cases, so both gates are real.
G06 pass `regenerate_cmake_component_files.py –component ores.platform –check` reports all source lists up to date, exit 0.
W01 to W04 not applicable No entity, registrar, handler, populate script or SQL script.
S01, S02 not applicable No entity and no shell unit.
H01 pass `validate_docs.py` passes for the component. The leftover-artefact, naming and platform-placement checks are clean. The diagram was authored in two passes. The automated pass was regenerated from a corrected generator, and the manual pass then filled every interface and every class whose content is methods, which is what that pass leaves empty, and drew the realizations and throws edges. One edge the first manual pass carried, `net` to `time`, was removed because `network_info.cpp` does not use the time facet. A refresh returns the file byte-identically. The audit page now names the facets that survive.
H02 pass No dead code and no duplicate implementation remains. The five dead public artefacts are deleted, the MAC enumerators have collapsed to one, and the seven `file` members with no consumer, across four overloaded names, are gone.
H03 pass The five end-of-line comments are gone or moved above their code, the six narration comments are deleted, and the stale `k_timestamp_format` claim is corrected.
V01 pass `./compass.sh build` reaches 100 percent with exit code 0, run after the last source edit.
V02 pass `ores.platform.tests` passes at 253 assertions in 119 test cases. Before this work the same suite reported 201 assertions in 88 test cases, both figures read from its own output, and no vacuous case is left. Three previously untested source files now have tests, and the shared scoped temp types add nineteen cases of their own.
V03, V04 not applicable No entity, no SQL and no generated shell command.
V05 pass Every gate run and green. `regenerate_cmake_component_files.py –component ores.platform –check` reports none stale. `validate_docs.py` reports only the pre-existing `ores.shell.iam` finding. `./compass.sh lint` passes. The codegen suite passes at 530 tests, which is the 522 baseline plus the eight new regression cases. `clang-format –dry-run –Werror` is clean on every changed and added C++ file.
V06 not applicable No catalogue row and no models, so the component cannot join `COMPONENTS_UNDER_TEST`. Recorded as the programme gap, not a defect of this component.

5. Notes

Survey, 2026-09-25, at trunk `5de59e3fb8`. Run by an agent that did not write the component, against the clean standard.

  • Scale, at baseline. 32 production C++ files in 23 headers and 9 sources, with 7 files under `tests/`. 88 test cases and 201 assertions. 458 C++ files outside the component reference `ores.platform/`, and 383 of them include `ores.platform/time/datetime.hpp`, which makes time the largest surface by a wide margin. The deletions leave 30 production files, 21 headers and 9 sources.
  • Suites pass. `ores.platform.tests` runs green from the last build, 201 assertions in 88 test cases.
  • What is already clean. No leftover artefact, no commented-out code, no TODO, every file and type name snake_case, folder morphology matches the signed-off catalogue, and the tests target is registered with `add_test` and `add_dependencies(run_all_tests …)`.

Work items, in the order they land.

  1. Delete `include/ores.platform/unreachable.hpp`. It has no includer, and `std::unreachable()` is the portable C++23 facility the repo already uses at `ores.nats/src/domain/wire_format.cpp:53`.
  2. Delete `include/ores.platform/attributes.hpp`. `ORES_NO_UNIQUE_ADDRESS` is used only by its own three `#define`s, and [[no_unique_address]] is the standard attribute every supported compiler has. Update the audit page, which names the header.
  3. Delete `process::get_hostname()`. It duplicates the live `net::get_hostname()` byte for byte and has no caller.
  4. Delete `:open_c_file()`. No caller, not even a test.
  5. Delete `datetime::is_valid_iso8601_date()`. No caller. It was added for the retired Qt `validateInput()` path.
  6. Collapse the duplicated MAC enumerators in `network_info.cpp`. Two hundred and thirty lines to about sixty, one enumerator plus two formatters.
  7. Add tests for the three untested source files, `environment.cpp`, `real_environment_provider.cpp` and `executable.cpp`. The environment facet already ships the test seam its own suite never uses.
  8. Add tests for untested public API on covered files, starting with `datetime::to_db_string`, which 32 C++ files outside the component call.
  9. Remove the vacuous tests and checks. Five `f == f` stability checks, two `has_value()` cases with no else, and three assert-nothing cases.
  10. Hygiene. Move the five end-of-line comments above their code, drop the six narration comments, correct the `k_timestamp_format` doc claim, and add the missing `<vector>` include to `file.hpp`.
  11. Rewrite `component_overview.org`. Fix the dependency claim, list every facet, drop nothing that exists, fill `See also` with id links, and bump `#+updated`.
  12. Fix the generator defect, then refresh the diagram. The automated pass must not delete content, so the generator is fixed at its source with a regression test in the codegen suite, and only then is the diagram refreshed. The `net` and `process` facets hold free functions the automated pass cannot draw, so they are hand-authored below the sentinel.
  13. Regenerate the two `component_files.cmake` files, which closes G03 and G06 for this component.

Not this component's work. The other 145 stale `component_files.cmake` files are one repo-wide sweep, and the registry gap needs one programme decision. Both are recorded on the programme story.

All thirteen items landed. Two more defects surfaced while the work was reviewed, and both are fixed here.

  • The component-diagram parser had a second defect. A wrapped parameter list leaves a line holding a type, a name and a closing parenthesis, and the member reader took it for a field, so the diagram showed a `format` member that `datetime` does not declare. A candidate field line now needs balanced parentheses of its own, with a regression test.
  • `real_environment_provider` had no `ORES_PLATFORM_EXPORT`, and the library builds with `-fvisibility=hidden`, so the class had no external linkage and no test binary could reach it. Every other exported class in the component carries the macro, so this is a latent defect rather than a test convenience.
  • Four test files were not clang-format clean. They are now, and `clang-format –dry-run –Werror` is clean on every changed file.

6. Test Scenarios

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.

Scenario State Notes
     

7. PRs

PR Title
#2148 [platform] Clean ores.platform to the component clean standard

8. Review

# Comment summary File Decision Notes
1 The refreshed diagram still showed a `format` member that `datetime` never declares, because the parser read a wrapped parameter list as a field build/scripts/generate_component_puml.py fixed A second parser defect. Fixed with a balance guard and a regression test that fails both of its cases against the unfixed parser.
2 Four of the five changed test files were not clang-format clean, and the nightly format job would have rewritten them projects/ores.platform/tests/net_network_info_tests.cpp, time_datetime_tests.cpp, environment_environment_tests.cpp, process_executable_tests.cpp fixed Formatted, and `clang-format –dry-run –Werror` is now clean on every changed and added C++ file.
3 `real_environment_provider` had no export macro, so the library gave it no external linkage under `-fvisibility=hidden` and no test binary could reach it projects/ores.platform/include/ores.platform/environment/real_environment_provider.hpp fixed, kept A production fix, not a test convenience. Its siblings all carry the macro, and without it the class is unusable from a consumer on Windows.
4 The record carried six statements the tree does not support doc/agile/versions/v0/sprint_26/clean-platform/task_clean_platform.org, story.org, doc/knowledge/architecture/component_clean_standard.org fixed Found by the independent verifier and reproduced by me before correcting. The baseline and current file counts are now separate; the base assertion figure is attributed to the suite's own earlier output; the external-reference numbers name their metric, which is C++ files; the one-line enum count says "in a header", which is what the parser reads; the deleted `file` members are seven across four names, not eight; and the format finding says four of the five changed test files. The `to_db_string` figure became the 32 C++ callers, because nine of the 41 references are templates and docs.
5 The bookkeeping commit that `compass pr record` created carries no `Story-ID:`, `Task-ID:`, `Environment:` or `Co-Authored-By:` trailer commit 0398bf4613 recorded, not fixed The tool generates that commit. Rewriting a pushed commit to fix a message is a force-push this story should not perform while it is under review, so the gap is recorded. It belongs to `compass pr record`, which should emit the trailers every hand-written commit carries.
6 The diagram was a skeleton. Every class whose content is methods was an empty box, so `environment_provider` showed no methods, and it carried an edge the code does not support projects/ores.platform/modeling/ores.platform.puml fixed Raised by the maintainer reading the render. The automated pass reads data members only, so the manual pass that H01 requires had not been done. Every class now carries its API, the two providers realize the interface, and `file` throws `io_error` and `file_not_found`. The `net` to `time` edge went, because nothing in `network_info.cpp` uses the time facet. Only one of the two edges the first pass drew was supported. The rendered image grew from 110 KB to 268 KB, and it was read rather than merely regenerated.
7 The maintainer asked for the temp file and temp directory helpers to be shared and production-usable rather than test-local projects/ores.platform/tests/filesystem_file_tests.cpp fixed The `scoped_temp_file` and `scoped_temp_directory` types landed in `ores.platform::filesystem`, the facet the audit assigns to filesystem concerns, and the component's own tests migrated to them. Review of the first cut then found that the move assignment orphaned the path the guard already held, so both types now release the evicted path first and two assertions cover it. The earlier tests missed it because they observed the survivor and not the evicted path. The other six call sites are captured as `doc/agile/product_backlog/next/migrate-temp-path-duplicates.org`.
8 The message of commit `b6bf205558` asserts that "two of them [are] production code that never cleans up after a failed run", which the code contradicts; the temp path capture repeated the same claim commits b6bf205558, a2d28f752b recorded, not fixed Raised by the independent verifier once the capture was corrected. The claim is wrong in both directions: the four `storage_transfer.cpp` paths remove their archive on success and again in `catch (…)`, and `report_package_handler.cpp` removes its staging directory after the upload. The defect is that cleanup is a per-site obligation, so that one site leaks only when a throw lands between `create_directories` and the trailing `remove_all`. Rewriting a pushed commit under review takes a force-push, which this story does not perform, so the message stands and this row plus the corrected capture are the durable record. The same applies to `a2d28f752b`, whose message counts the branch's `[platform]` commits as seven; it holds eight, because `5c6f8aa9c1` was missed, and the Result and the story carry the corrected figure.

9. Result

ores.platform meets the standard for the items that apply to a model-free component. Thirteen work items landed, plus the shared scoped temp types and the diagram corrections, across eight `[platform]` commits.

The component lost five dead public artefacts, seven `file` members with no consumer across four names, and about a hundred lines of duplicated MAC enumeration. It gained tests for three source files that had none, a test for `to_db_string` that 32 C++ files outside the component call, and an assertion count that rose from 201 to 253 with no vacuous case left, and the shared scoped temp file and directory types, which replace seven ad-hoc implementations across the tree once the other components migrate. Two diagram parser defects are fixed at their source with regression tests. The first had made a refresh delete correct content in the seven components that declare a one-line `enum class` in a header, which is what the generator reads.

Two items stay out of scope, both programme-level. The other 145 stale `component_files.cmake` files are one sweep. The registry cannot admit a component with no models, so V06 is the accepted exception and platform does not join `COMPONENTS_UNDER_TEST`.

Emacs 29.3 (Org mode 9.6.15)