Task: Bring ores.connections to the clean standard

Table of Contents

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

1. Goal

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

The inventory below shows that the component had no consumer left, so the task reached the standard by removing it. The item table records that outcome item by item. The story carries the decision.

2. Status

Field Value
State DONE
Parent story Clean ores.connections to the component clean standard
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-09-23

3. Acceptance

  • Every checklist item that applies to a component of kind All passes, or is recorded with the reason it does not apply.
  • Every item that cannot pass is recorded as an exception with its reason.
  • Every generator defect found is fixed at its source, with a regression test.
  • No consumer is left without the component. The whole tree builds without it.

The original acceptance asked that ores.connections join COMPONENTS_UNDER_TEST. That cannot be met and is superseded. The component no longer exists.

4. Plan

Work the Component Clean Standard in its section order and record each item's result in the table below.

Item Result Evidence
B01 pass Baseline taken before any edit. check_component_drift.py --component connections --dry-run answers Unknown component: 'connections', because the component is absent from component_catalogue.org. regenerate_cmake_component_files.py --component ores.connections --check reports 2 stale files: src/component_files.cmake and tests/component_files.cmake differ only by the generated-file marker.
B02 pass Every model file classified by metatype. projects/ores.connections/modeling/ held component_overview.org (#+type: ores.codegen.component), ores.connections.puml and ores.connections.png. 0 entities, 0 junctions, 0 operations, 0 messages.
B03 pass All 70 non-test C++ files classified. 66 match a codegen archetype's output shape. 4 are hand-written C++ infrastructure: repository/sqlite_context.{hpp,cpp}, export.hpp and the umbrella header. The CMakeLists.txt files are build files rather than C++ files. None is dead by the within-tree rule, and all 70 are unreachable from outside.
B04 not applicable The component serves and sends no NATS subject and has no protocol header. Its one subject_prefix field is a string a user types into a bookmark, not a subject the component publishes on.
B05 pass Captures and in-flight branches read. Two live captures under doc/agile/product_backlog/next/ name the component. persist_tag_colour_and_tag_dialog.org is Qt-only and carries the ores.qt tag. fix_component_doc_drift.org names it in an affected components at time of writing snapshot that also names ores.controller and ores.wt.service, which projects/ no longer holds either. Both are recorded under Out of scope on the story. origin/feature/remove-the-legacy-qt-remnants (PR #2138, now merged) does not touch the component.
M01 not applicable No org model. The component held only its overview.
M02 not applicable No entity model, so no variability profile to bind.
M03 not applicable No model states a property, so none can repeat its profile.
M04 not applicable No model feature to place in a namespace.
M05 not applicable No entity, so no table to describe.
M06 not applicable The component exchanges no wire type. 0 messaging headers, 0 of them hand-written.
M07 not applicable No junction.
M08 not applicable No org model custom type binding.
M09 not applicable No model, so no legacy fragment to find in one.
M10 not applicable The overview is removed with the component. validate_docs.py passes on the tree apart from one pre-existing finding for ores.shell.iam.
P01 not applicable No entity and no protocol.
P02 not applicable No subject is owned. No raw subject literal exists in the component.
P03 not applicable No registrar and no declared message.
P04 not applicable No operation model and no hand-written protocol header.
P05 not applicable No protocol change reaches a consumer.
P06 not applicable No event cache.
G01 not applicable No model, so nothing regenerates. The drift gate cannot name the component: Unknown component, as B01 records.
G02 pass No hand-written file the generation supersedes remains. The whole component is deleted.
G03 pass No generated file and no hand-written file carries the marker. The 2 CMake source lists that lacked it are deleted with the component.
G04 not applicable No generated code to review against the component's best hand-written code.
G05 pass No generator defect was found. The codegen has no SQLite target, and closing that gap for a component with no consumer would be new capability, not a fix.
G06 pass The 2 stale source lists are gone with the component. The repo-wide check still reports 149 stale lists in other components. That is inherited from main, where commit 3a40c9c57e added the marker to the templates on 2026-09-23, and it belongs to each of those components' stories.
W01 not applicable No registrar family, so no composition point.
W02 not applicable No handler checks a permission.
W03 not applicable No populate script names the component.
W04 not applicable The component owns no SQL script. Its storage was a local SQLite file, not a service schema.
S01 not applicable No entity or junction, so no shell command unit.
S02 not applicable No command, so no recipe and no destructive flag.
H01 not applicable The component is deleted, so it cannot be audited, and its record is this task. The audit's automated half, validate_docs.py, covers the tree and passes apart from the pre-existing ores.shell.iam finding. The manual checks ran against projects/ores.connections before the removal, where they were clean: no leftover artefact, no platform macro, and every source file name snake_case apart from the umbrella header and CMakeLists.txt. A repo-wide run of those same greps reports pre-existing hits outside this component, since five files outside ores.platform use _WIN32 and *stub* matches 21 files, eight of them codegen templates. Those belong to their own audits.
H02 pass No legacy code remains. The component and every code and ground-truth reference to it are gone. Two references stay on purpose and are recorded under Out of scope.
H03 pass The change deletes code and removes a generated env block, so no comment survives to review. The one surviving source edit, env_init.py, was read against the comment rules. Its removed block took its comments with it, and no comment was added.
V01 pass compass build over the whole tree reached 100% with exit code 0, with projects/CMakeLists.txt no longer adding the component. Nothing linked what was removed.
V02 pass The ores.codegen suite passes at 522 passed, and the ores.compass suite at 215 passed and 1 skipped. No test covers the env_init.py edit. The removed block lay inside env_init.run, and the only test module that imports that file calls _env_value and _resolve_web_env_id, so the suite passes without touching the change. The 522 is 14 fewer than the 536 measured before the rebase, because trunk's PR #2138 removed test_as_of_combo_fields.py and test_view_groups.py. The component's own suites are deleted with it.
V03 not applicable No entity and no service, so the database has nothing of this component to recreate.
V04 not applicable No generated shell command, so nothing to run against the fleet.
V05 pass Every gate run and green, apart from one inherited repo-wide finding: component drift (iam), model drift (2 known exceptions), protocol twin coverage, handler permissions, populate references, shell recipe inventory, validate_docs.py (apart from ores.shell.iam), compass lint, and the six checks of .github/workflows/doc-lint.yml (build/scripts/rename_skills_to_compass_namespace.py, generate_skills_catalogue.py, generate_skill_type_tables.py, apply_skill_levels.py, link_skill_recipes.py and link_structure_notes.py, each with --check). The inherited finding is the cmake source-list drift that G06 records.
V06 not applicable The component does not join COMPONENTS_UNDER_TEST, because it does not exist. This is the exception that supersedes the original acceptance.

5. Notes

  • Inventory, 2026-09-23. 0 entity, junction or operation models. 70 C++ files outside tests, 0 of them generated (0%). 0 messaging headers, 0 of them hand-written.
  • Consumer census. The only reference in the tree was projects/CMakeLists.txt line 124, add_subdirectory(.../ores.connections). #include <ores.connections/...> appears nowhere outside the component. A grep for ores.connections, ores.connections/ and connection_manager across every .cpp, .hpp, CMakeLists.txt, *.cmake, *.ts and *.py outside the component returns nothing.
  • The component is not a codegen component. It has no row in projects/ores.codegen/library/component_catalogue.org, and the codegen has no SQLite target. The generated entity, domain and repository templates hard-code the PostgreSQL shape: schema = "public", tenant, version and audit columns, and sqlgen::session on a connection pool. This component uses sqlgen::sqlite with a file path. So 66 of its files are generatable only after new generator capability, which a component with no consumer does not earn.
  • 6 files are transitively dead inside the component as well: domain/recent_party.hpp, repository/recent_party_entity.hpp, repository/recent_party_mapper.{hpp,cpp} and repository/recent_party_repository.{hpp,cpp}. The only caller of that family, connection_manager::get_recent_parties, has no caller of its own. get_child_folders has no caller either, and resolve_connection has no production caller, only two cases in the service test.
  • Stale reference sweep. projects/modeling/ (component_architecture.org, system_model_infrastructure.org, system_model_foundation.org, ores.puml), projects/ores.security/modeling/component_overview.org, projects/ores.compass/src/env_init.py, the .env-format log, and projects/ores.web/package-lock.json.
  • Two sprint-history pages linked the deleted component's :ID:. The links are now plain text, so compass lint passes and the history still reads.

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.

No scenario applies. No user reaches the component, and a deletion has no behaviour to walk through. The build and the gates are the evidence.

Scenario State Notes
     

7. PRs

PR Title
#2139 [connections] Remove the dead ores.connections component

8. Review

# Comment summary File Decision Notes
1 The System Model diagram still drew connections --> security after the component node was removed, so PlantUML would create a ghost component projects/modeling/ores.puml:285 fixed The third commit removes the edge, and the source now has no reference to the alias. Its blocks and notes balance.
2 The two sprint-history de-links existed only in the working tree, so both commits still carried a dangling id link doc/agile/versions/v0/sprint_02/client_server_foundations/story.org, doc/agile/versions/v0/sprint_03/client_console_qt_integration/story.org fixed The third commit commits them.
3 doc/knowledge/ui/icon_guidelines.org still describes the Qt Connection Browser under its Server Link icon doc/knowledge/ui/icon_guidelines.org:474,479 fixed after the rebase Inherited from the Qt deletion. PR #2138 reworked that page and merged without correcting this entry, so the rebased branch rewrites the usage prose and the icon keeps its name.
4 A second live backlog capture names the component, and the B05 evidence claimed only one capture does doc/agile/product_backlog/next/fix_component_doc_drift.org:24 fixed, record corrected Real. The B05 row now names both captures, and the story records this one under Out of scope. Its snapshot also lists ores.controller and ores.wt.service, which projects/ no longer holds, so the list is stale beyond this story.
5 The record's V02, B03, H01 and Notes rows stated numbers and claims the tree does not support doc/agile/versions/v0/sprint_26/clean-connections/task_clean_connections.org:60,91,95,120 fixed Real, all four, and each reproduced. V02 said 536 codegen tests where the tree gives 522, because trunk's PR #2138 removed 14. B03 folded 3 CMakeLists.txt into a count of C++ files, so 66 C++ files are archetype-shaped rather than 63. The Notes said 7 transitively dead files and named a recent_party_entity.cpp that never existed, so the family is 6. H01 stated component-scoped negative checks as repo-wide, and five files outside ores.platform use _WIN32.
6 The record said the compass suite covers the env_init.py edit, which no test can cover doc/agile/versions/v0/sprint_26/clean-connections/task_clean_connections.org:95,174 fixed Real. The removed block lay inside env_init.run, and the only test module importing that file calls _env_value and _resolve_web_env_id. V02 and the Result now say the suite passes without covering the edit. Three precision notes are fixed with it: the repo-wide *stub* count is 21, snake_case holds for source files apart from the umbrella header and CMakeLists.txt, and resolve_connection has no production caller but two test cases.

9. Result

ores.connections is removed, together with the references it left behind.

The clean standard is met by subtraction. H02 forbids dead code, and the component was dead by every measure: no C++ consumer, no web or shell role, no org model, and no codegen target.

Verification. The whole tree builds with compass build, exit 0, re-proved on the rebased tree. The ores.compass suite passes at 215 passed and 1 skipped, and the ores.codegen suite at 522. No test covers the env_init.py edit, because the removed block lay inside env_init.run and no test calls it, so that edit rests on the diff and the build. Every codegen gate passes, apart from the inherited repo-wide CMake source-list drift that G06 records. compass lint passes.

Verification rounds found defects, and every one is fixed. The first independent verifier read the first patch and found two, fixed in the follow-up commit. A Claude review found a stale backlog capture, fixed next. The rebase onto trunk surfaced the icon inventory entry. A second independent verifier confirmed the removal is sound and then failed the patch on statements in this record. Each finding is corrected here after I reproduced it. The last one matters most: no test covers the env_init.py edit, so that change rests on the diff and the build.

The removal is one commit and reverts on its own. The reference sweep is a second commit.

Emacs 29.3 (Org mode 9.6.15)