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, andcheck_component_drift.py --allpasses.
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.
- Baseline and inventory (B01 to B05). Record the baseline before any edit.
- Models (M01 to M10).
- Protocol (P01 to P06).
- Generation (G01 to G06).
- Wiring and data (W01 to W04).
- Shell (S01, S02).
- Structure and hygiene (H01 to H03).
- 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.
- 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`.
- 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. - Delete `process::get_hostname()`. It duplicates the live `net::get_hostname()` byte for byte and has no caller.
- Delete `:open_c_file()`. No caller, not even a test.
- Delete `datetime::is_valid_iso8601_date()`. No caller. It was added for the retired Qt `validateInput()` path.
- Collapse the duplicated MAC enumerators in `network_info.cpp`. Two hundred and thirty lines to about sixty, one enumerator plus two formatters.
- 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.
- Add tests for untested public API on covered files, starting with `datetime::to_db_string`, which 32 C++ files outside the component call.
- Remove the vacuous tests and checks. Five `f == f` stability checks, two `has_value()` cases with no else, and three assert-nothing cases.
- 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`.
- Rewrite `component_overview.org`. Fix the dependency claim, list every facet, drop nothing that exists, fill `See also` with id links, and bump `#+updated`.
- 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.
- 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`.