Task: Shell, wiring, hygiene and verification for ores.trading
Table of Contents
This page documents a task in the Clean ores.trading to the component clean standard story. It captures the goal, current status, acceptance, and any notes or results.
1. Goal
Close the shell, wiring, hygiene and verification items, and enter
ores.trading in COMPONENTS_UNDER_TEST, which is the last step of the
Component Clean Standard.
This is item group S, items W02 and W04, items B06 and H01 to H05, and
the whole V group.
The entry in the registry is a claim that regeneration is byte identical, that every protocol header has its twin, and that every applicable item passes. Four of the gates read green today only because the component is absent from their registries, so this task must state which green is real and which became real here. The CMake source list check is the one that already fails and is therefore honest.
2. Status
| Field | Value |
|---|---|
| State | BACKLOG |
| Parent story | Clean ores.trading to the component clean standard |
| Now | Not yet started. |
| Waiting on | PR 5 merged. |
| Next | Enable the shell facet for every entity, then seed the permissions. |
| Last touched | 2026-09-26 |
3. Acceptance
- S01: every entity and junction verb has a generated shell command unit
and a test. Twenty-two of fifty-seven entities set
:ores.cpp.shell-command.enabled: truetoday. The scheduler pass recorded that theores.cpp.shell-commandfacet has no component-scoped aggregator archetype, so this needs generator work and not only a regeneration. Every hand-written unit the generation replaces is deleted. - S02: every command has a generated literate recipe under
doc/recipes/shell/, andregenerate_shell_recipe_inventory.py --checkpasses. Twenty-two recipes are wanted and none exist today. - W02: the 92 unseeded permission codes are seeded, the roles that need
them are granted them, and ores.trading is added to the
REGISTRYincheck_handler_permissions.pyso the gate stops reading green by exclusion. The component checks 98 codes and 6 are seeded today. - W04: the service grants cover every table the service reads, and
compass db recreate -y -kfollowed by the fleet start proves it. - B06: every public symbol is classified by its consumer, production, test only or none. A test-only consumer counts as dead code and the symbol and its test are deleted. The census covers the 126 headers consumed outside the component.
- H01: the Component Architecture Audit is run and its record written, and the three diagrams are authored in two passes: the automated pass, then the manual pass below the sentinel, and the rendered image is read rather than only regenerated.
- H02: no dead code, no commented-out code, no hand-written duplicate of
a generated artefact. The two generator trees,
api/.../generator/with 25 files andapi/.../generators/with 38, collapse into one. The 24 unmodelled domain types from PR 3 are resolved or explained. - H03: the comment rules pass over the component.
- H05: the component overviews carry the six sections and a current
diagram. The stale
ores_schema.pumlER diagram is a repository-wide sweep with a generator that has no dry run; record it as a named sweep finding rather than a trading fix. - V01: the whole tree builds with the component's tests and every consumer.
- V02: the codegen suite passes and the component's three suites pass with the fleet up.
- V03: the database recreates from scratch and the fleet starts and serves.
- V04: every generated shell command runs against the live fleet and answers, and any command that cannot run is recorded with the reason.
- V05: every codegen gate is green with the component added: component drift, model drift, protocol twin coverage, handler permissions, populate references, recipe inventory and CMake source lists.
- V06: ores.trading is listed in
COMPONENTS_UNDER_TESTandcheck_component_drift.py --allpasses with it listed. - V07: no vacuous test. Every test fails when its subject does nothing. The scheduler pass found that a test which passes on a failed lookup reports confidence it did not earn.
- V08: every source file has a test that exercises it, or is recorded with the reason it does not. The survey runs over 732 non-test sources against 58 test files, and the list of untouched files is the coverage work item.
- P04 is decided:
trading.v1.trades.export-to-storageandtrading.v1.trades.portfolio.exportare hand-written operations with no operation model. Either they become operation models or the item is recorded as not applicable with the reason. - M07 is recorded as not applicable, with the junction-shaped entities named so a later reclassification opens it.
4. Plan
4.1. 1. Enable the shell facet and generate
Set :ores.cpp.shell-command.enabled: true on the entities that should
have commands, or record the reason an entity has none. Generate the
units and their tests, then delete the hand-written units the generation
replaces. If the facet still has no aggregator archetype, build it in
the codegen library with a regression test.
4.2. 2. Generate the recipes
Generate one recipe per command, regenerate the inventory, and run every recipe against the live fleet. Record the run.
4.3. 3. Seed the permissions
Take the 98 codes the handlers check, find the 92 that no populate script seeds, seed them, grant them to the roles that need them, and add the component to the permissions gate's registry. Then run the gate.
4.4. 4. Run the audits and the surveys
- The Component Architecture Audit, with its record.
- The two-pass diagrams, reading the rendered image.
- The B06 consumer census over every public symbol.
- The H03 comment pass.
- The V08 per-file coverage survey.
- The V07 stub test: stub the subject and require the test to fail.
4.5. 5. Recreate, start and run live
./compass.sh db recreate -y -k
./compass.sh services start
ctest --test-dir build/output/linux-clang-debug-make -R "ores.trading" --output-on-failure
Run every generated shell command against the fleet. Record any command that cannot run.
4.6. 6. Enter the registry
Add the component to COMPONENTS_UNDER_TEST in
projects/ores.codegen/scripts/component_registry.py and run
check_component_drift.py --all. This is the last step, and it turns
every vacuous green into a real one.
4.7. 7. Record every item
Fill the story's checklist with the final result per item, the evidence file, and the reason for each not-applicable.
5. Notes
- The eleven untracked shell library directories from the scheduler pass
are that task's open item 10. They are not trading's, but they make an
in-place drift check fail. Sweep them or record them as still open
before the
--allrun. - Four gates read green today because ores.trading is absent from their registries: component drift, handler permissions, protocol twin coverage and recipe inventory. The CMake source list check is the one that fails honestly. Recording both is part of V05.
- The twin gate cannot be satisfied by trading without TypeScript twins, and the component has no web consumer. Decide whether the protocol twin item applies, and record the reason either way.
- The scheduler pass learned that a private constructor is an invariant rather than an obstacle, that a cited figure is evidence, and that only a live run finds some defects. Apply all three here.
6. Test Scenarios
| Scenario | State | Notes |
|---|---|---|
7. PRs
| PR | Title |
|---|---|
| Shell, wiring, hygiene and verification for ores.trading |
8. Review
| Comment summary | File | Decision | Notes |
|---|---|---|---|