Story: Clean ores.trading to the component clean standard

ores.trading meets the Component Clean Standard: every item: All, Protocol and Entity pass, each item that does not apply is recorded with its reason, and ores.trading joins COMPONENTS_UNDER_TEST. Order 32 of 35 in the sprint 26 component clean-up, tier 3 (domain component).

ores.trading is the largest component in the tree and the last one whose regeneration no gate has ever measured. It cannot pass the standard by running the same pass the smaller components ran, because a single regeneration touches 1751 files and the component's data model still carries an unresolved identity question inherited from sprint 25. This story therefore lands in six PRs, and it records the decisions that bound each one.

• Every checklist item that applies to a component of kind Entity 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.trading is listed in COMPONENTS_UNDER_TEST, and check_component_drift.py --all passes.

Every figure below was measured on 2026-09-26 at commit b79609d808, on a still tree, with the codegen virtual environment. The commands and their raw output are in the task's evidence/ folder.

The refactor the user asked about is four threads, and sprint 25 closed all of them as story wrappers rather than as work. Thirteen of twenty tasks in the first story are DONE, and every task in the second is DONE. What was abandoned is the part that changed the shape of the data.

Measured 2026-09-26 and 2026-09-27. The database would not rebuild from main's tree, and the default build would not compile, for eight defects. None of them is trading's. Six stopped the rebuild, and each repair revealed the next: five dq population-function scripts that never close their header comment; the storage service missing from SERVICE_NAMES, from the service account seed and from the service registry; a missing unique constraint on ores_dq_tags_artefact_tbl; a catalogue upsert that relied on an ON CONFLICT the versioning trigger pre-empts, which this programme's PR #2232 fixed; and a publish function that states version 0. Two stopped the default build, which had been red since PR #2216: the FSM remodelling deleted fsm_protocol.hpp and the machine filter with it, and the dataset remodelling replaced get_datasets_request, while the workflow, reporting and iam consumers stayed behind. Main's PR #2240 migrated those consumers and cleared the SQL. On that base the rebuild needs no workaround, the build exits zero, and the fleet reaches twenty-four units in two seconds.

task_model-missing-trading-families.org §2d holds the defect table, with each symptom and its state.

• One trade identity, one instrument identity and one security issue identity, per trade_modeling.org: the trade id identifies the trade and its instrument, and the security issue is a separate reference datum where the product has one.
• Every table that carries persisted trading data has an org model, and every model is on the current format and bound to a profile or recorded as a no-match.
• Every wire type is a projection of a model. The nine rates families ship as generated per-family protocols. Hand consolidation is deleted. Expressing consolidation in the model is a later option, recorded as a decision.
• The database declares its relationships. A foreign key replaces every soft link the schema can hold.
• Regeneration is byte-identical and idempotent across SQL, C++, shell units, shell recipes and the CMake source lists.

One row per item of the Component Clean Standard, with the result measured on 2026-09-26 and the task that owns it. The rows PR 3 owns were re-measured on 2026-09-28. The row is updated as each PR lands.

• D1, the rates wire. The nine consolidated rates families ship as generated per-family protocols. The hand consolidation is deleted: the per-family sections of instrument_protocol.hpp, rates_instrument_handler.hpp, and registrar_rates.cpp is rewritten to call the nine generated registrar functions. The generated protocol renames two verbs per family, save to put and history to _versions.list, so the nine hand-written shell units and the ORE import handler migrate in the same PR. The alternative, making consolidation a model decision, needs generator work and is recorded as a later option rather than taken here. Reason: the generator already emits the per-family shape, and leaving both shapes in place registers the same subjects twice.
• D2, the instrument identity. Implement the documented rule. The trade id identifies the trade and its instrument. The security issue is a separate reference datum. Collapse the identity first, then split the bond security, in that order, because the reverse reshapes the same tables twice.
• D3, the unmodelled families. Model all of them in PR 3: commodity, composite, composite leg, credit, scripted, swap legs and product type. The registry entry depends on it. Record each as a profile no-match with its feature values where no profile fits.
• D4, M07. Record the item as not applicable, because the component has no junction metatype. Record that bond_leg, trade_party_role, trade_identifier and instrument_option are junction shaped, so a later reclassification opens the item rather than leaving it silently skipped.
• D5, the sixteen trade model defects. Fold the model-shape defects into PR 3 and PR 4 as the table above assigns them. Leave defect 11 and defect 12 with the reference-data and dq work and record them as out of scope here.
• D6, the stale remote branch. Record feature/trading-model-cleanup and do not delete it. It is not this worktree's branch, and the story it scaffolds is superseded.
• D7, the shape of PR 1. Documentation and evidence only, so that the decisions are on the record before 1751 files move.
• D8, how a rollback names a trade. The trade model declares its wire key as external_id, so the canonical protocol cannot remove a row by the uuid the import rollback held. Decided, on the reviewer's ruling, to record the external ids: the handler has the value in hand at the save site, so it stores the external identifier, and the rollback builds a trade_removal whose key is that identifier. Because the field now carries a key and not a uuid, the ores.ore model renames it saved_trade_external_ids, and its generated C++ and TypeScript and the hand-drawn diagram follow it. The trading protocol does not change. The trading model changes in one place: the trade key's fixture generator gains a value, which is defect 17's PR 2 half; no column and no shape change. The other two options stay recorded: declaring the storage key as the wire key is PR 3 model work, and a removal by storage key is a generator change. If PR 3 settles the key the other way, the handler change is what reverts, and it is one line. The key's nullability is the same thread and is recorded as defect 17.
• D9, the shape of the rollback's saved lists. The rollback request carries one string list per entity kind: saved_currency_iso_codes, saved_portfolio_ids, saved_book_ids and saved_trade_external_ids. A single ordered collection of kind-and-key entries is the cleaner shape long term: an enumerated kind with its keys, or a flat list of key-value pairs. Adding a kind then changes one model field instead of four lists, two handlers and a wire name, and the order the rollback traverses becomes explicit. It is deferred, because the rollback must dispatch a different delete request per kind whatever the payload shape, so a generic bag trades a typed field for a stringly kind and moves exhaustiveness from the compiler to a switch. Recommendation: take it up when the ore import workflow is next revised, not inside PR 2. Recorded as a capture on the product backlog.
• D10, the swap legs shape. One model over the shared table, not one per family. ores_trading_swap_legs_tbl is one table with one surrogate key, one parent column (instrument_id) and a leg_type_code discriminator; the leg type is data, not a table. The generator holds one entity per table, so several models would each claim the same DDL and drift against each other. The model is swap_leg, child-shaped: uuid key, tenant and workspace scope, a parent foreign key to the instrument. PR 3 authors it.
• D11, monetary amounts. An amount is a decimal, built on boost::multiprecision, never a double. The database already stores these columns as numeric, so the SQL does not change: the C++ domain type, the JSON and table I/O, the mapper and the generator's type separation move to it. The 87 double columns that carry a price, strike, premium, payout or notional adopt it; rates, volatilities and correlations stay double, because they are not money. The type lands before the columns move, and the generator must first separate an entity's type from its domain type, which is the same seam the plain date column needs. The wire carries a decimal as its exact text, read and written by a custom rfl::Reflector with ReflType = std::string, the way dates and uuids already travel. The repository entity keeps a string member, because sqlgen binds a fixed set of types and boost::multiprecision is not one of them; the mapper parses and formats at that boundary.
• D12, collections. The trading domain model carries no JSON collection. A collection is a child table with a foreign key to its parent. The four columns that still hold JSON – call_dates_json on callable_swap_instrument, basket_json on commodity_instrument and equity_swap_instrument, and option_data_json on equity_position_instrument – become child entities, and any other serialised collection the census finds goes the same way. The model states the shape and the database enforces it.
• D13, enumerations. A closed set of values gets a reference table and a foreign key, and its check leaves the PL/pgSQL functions for the schema. The missing reference tables are populated from the standard, FpML or ORE, never invented; where the data belongs to another component the dependency is recorded instead of a local copy. This closes defects 4, 5 and 8 as one thread.
• D14, the instrument key. The instrument's key is the trade it belongs to. instrument_identity drops instrument_id, every instrument table is keyed by a non-null trade_id, every fact and child table that named an instrument names that trade, and trade.instrument_id is deleted. Reason: ORE carries two identities, the trade and the security, and a one-to-one relationship modelled as two nullable pointers has nothing that can make them agree. This closes defect 13.
• D15, the relationship the schema can hold. The instrument-to-trade link is declared in the model and enforced by the generated insert trigger's existence check (errcode 23503), not by a DDL references clause. A foreign key cannot be held against a bi-temporal parent: the only unique index on (tenant_id, id) is partial, and PostgreSQL refuses a foreign key to a partial unique index, which was proven against the live database. The shape that would allow one – the child carrying the parent version's valid_from and the insert trigger deriving it instead of stamping clock_timestamp() – pins the two version histories together and is recorded rather than taken here. Defect 7 is partly closed by this and the remainder is recorded.
• D16, the standalone instrument. An instrument with no real trade is expressed as a trade of a reserved type, so there is one shape and no nullable back door. The nullability is gone with D14; ORE's own placeholder type is Failed, deliberately absent from the product catalogue, and no caller in the tree writes an instrument without a trade after the collapse, so no reserved type is seeded.
• D17, the bond security split moves out of PR 4. It reshapes the bond family around a security identity and is the largest part of the diff, so it becomes task_split-bond-security-from-trade.org and PR 5. PR 4 stops after the collapse with the tree green, which the task's own note authorises. The story ladder grows by one: the split is PR 5, the bond pilot PR 6 and the shell and verification work PR 7. By the owner's ruling of 2026-09-28, defects 14 and 16 move to the bond pilot and defect 15 to the split.
• D22, how the sweep holds the corpus to one statement per security. The round-trip gate imports one document and exports it again, so the source it compares has to be a document the database can hold. The corpus is not one: it states five security ids across ten documents that disagree about the issuer, the credit curve, the issue date and the leg schedule, and about 117 trades name SECURITY_1 between them. Our model holds one issue per security – that is the split's point – so a comparison against every restatement reads the corpus's own contradiction as a loss. The sweep therefore folds the union before it imports it: the first trade that names a security states the issue, and every later trade is rewritten to that statement, leaving the two members the model keeps on the trade's own instrument, SecurityId and BondNotional, as the trade stated them. The sweep prints what it overrode, by member, and --raw-corpus skips the fold so the contradiction can be measured. The gate is then a statement about the code, and the contradiction is recorded as the corpus's own.
• D23, the KnockOutSwap's home. swap_leg names the knock-out swap among the nine rates families whose legs it holds, and knock_out_swap_instrument holds the barrier, the start and the maturity as typed columns. The import sent the type to scripted_instrument instead, where the closed trade-type check refused the row, so the corpus's one trade of the type never reached the database and the export dropped the trade it could not rebuild. KnockOutSwap is routed to the swap family, which is what the legs table states, and scripted_instrument stops naming it. ORE's own AmericanMonteCarlo readme lists KnockOutSwap under "Scripted Trade Types (AMC)", which is how the wrong home was available; D12's ban on a JSON collection decides it the other way, because the type's two LegData elements have nowhere to go in a flat scripted row.
• D24, what an empty element states. ORE's date type spells an unset date as the empty string and the elements that carry one are minOccurs"0", so a document may write an unset date as an empty element or omit the element, and the corpus does both: 414 =FirstDate=/=LastDate elements corpus-wide are empty and 278 are absent. Both spell the same statement – ORE's own reader resolves either to an unset date – so the gate compares content rather than element presence: an empty element is no difference whichever side states it, and a boolean spelling is paired first, because an empty element is also how ORE spells true and that one has to be echoed as a boolean. The model therefore needs one state and not three, and no presence flag is modelled for an unset date. Where a member's value equals its type's default, the optional column is the presence record: absent is null and a stated false or 0 is the value, which is what the bond future's two optional booleans rely on (definition of done, presence bullet).
• D25, the bond future's columns. The synced XSD is the ground truth and the table is older than it. bondFutureData states three required members – ContractName, ContractNotional and LongShort – and two optional booleans, ApplyConversionFactor and UseFuturePrice, which the mapper has never read and the table has never held. The other thirteen columns leave the table: twelve of them are elements of bondFutureReferenceDatum, which v17 moved the contract terms to, and the thirteenth, fair_price, is not in the schema at all. None of them can be read from a trade, because the reference datum reaches only the ReferenceData document root and the generated ORE bindings cover the Portfolio root, so input.xsd never emits the type. The shared entity that will hold them is keyed by the contract name, the way bond_issue is keyed by the security id, and it lands with the reference-data import; recorded rather than invented. bond_future_delivery_basket is in the same position and is retired separately: ORE's DeliveryBasket is that datum's element, the table is keyed by the trade, and the exporter never writes it, so nothing fills it from a trade and nothing reads it back. Removing a generated entity touches five components and no tool prunes the files it leaves behind, so it is its own unit rather than a footnote of this one. The two optional booleans are nullable, so a stated false and an absent element stay different values, which is D24's rule.
• D26, the underlyings table. D21 settled its shape – keyed by the trade, holding an oresmd URI and an optional weight – and left the second arm, for an underlying that is itself a product, to the pilot. The pilot records the table as out of scope for the bond rebuild, with the reason: no bond product states an underlying. underlyingTypes is referenced by eleven sites and every one is another family's – varianceSwapData, cliquetOptionData, settlementData, pricesType, equityOptionData, eqBarrierOptionData, equityFutureOptionData, eqDigitalOptionData, eqTouchOptionData, equityForwardData and genericBarrierOptionData – while the bond family's own types (bondData, bondOptionData, bondFutureData, bondRepoData, convertibleBondData, callableBondData and ascotData) state none. A table built here would have no producer and no consumer, which is the shape this pilot is retiring elsewhere (bond_future_delivery_basket). The defect 15 fix is a producer change across nine families and about sixteen trade types, which the split task already recorded as not a bond reshape. D21's shape stands as the design for that work; the second arm is recorded as a kind that says URI or product, the URI, and the product's own name.
• D27, how a delete removes the family. The row a caller deletes is the header of a family, so the store closes the family with it rather than leaving it to each caller to remember. An entity names the rows it owns in a * Delete cascade section – a table and the column in it that names the entity's key – and the generated delete rule calls a generated function that closes them. An optional :cascade_orphan: on a foreign key takes the referenced row too when the deleted row was the last to name it, which is what a parent shared by security id needs. The cascade is a plpgsql function the rule calls and not a rule body, because a rule resolves the tables it names when it is created and a child may be created after its parent. The rule is D15's, applied to the delete side: the relationship is enforced where the schema can hold it, so the shell verb, the import rollback and every later caller get it without repeating it.
• D28, what defect 14's coverage declaration now says. Every instrument table but one carries a trade_type_code constraint, and the union of the lists covers every code in ores_trading_trade_types_tbl, so a generator can ask each table what it holds. The bond table is the tightest: bond_instruments names exactly the ten bond codes. But ten tables – the rates, credit and commodity general tables – share one identical list of all 121 codes, so their lists do not separate the products they hold from the ones they do not, and rpa_instruments carries no constraint at all because nothing writes it: the mapper sends RiskParticipationAgreement to credit_instruments. The defect's prescription, "declare coverage everywhere first", is met; what remains is giving each table its own list and deciding the unproduced table, which is the exclusive-or split defect 9 asks for and belongs to the families that own those tables, not to the bond pilot.
• D29, where defect 16's observation schedule lives. instrument_schedules holds one row per schedule an instrument's owner states, keyed by the trade, the owner, the schedule's role and the entry's ordinal, with schedule_kind choosing the rule arm or the date arm and schedule_role naming schedule, payment_schedule, fixing_schedule or reset_schedule. It is keyed by the instrument rather than by a bond row, so any family whose product states a schedule writes there without a new table; the bond family's trade-owned schedules already do, and its security-owned leg schedules live in bond_issue_leg_schedule. The scalars the defect names are still spread over four tables (commodity_instruments, equity_asian_option_instruments, equity_accumulator_instruments and equity_option_instruments), and the twelve products that need an observation schedule are equity, fx and commodity. Moving those scalars into the shared table is those families' reshape work, not the bond pilot's.
• D30, the story closes with two accepted exceptions. The owner ruled on 2026-10-02 to close the story with P04 and G04 open, each with a capture. P04: the two export verbs are not operation models (capture); the same two messages are M06's only gap. G04: the stamp loop in the service template repeats its comment and reason expression once per member (capture). Its fix regenerates every grouped entity in every component and needs the clang-format that CI pins. Reason: both are bounded, recorded and owned by a capture, and neither changes behaviour. Every other applicable row is met, measured on main on 2026-10-02.

• The PR 2 regeneration is large. A whole-tree build and the four suites, not the diff, are the evidence that it is safe.
• Regenerating the nine rates families while the consolidated handler remains would register the same NATS subjects twice. D1 must be applied inside PR 2, not after it.
• The identity reshape in PR 4 is the largest model change. It must land in one PR with its regeneration, and the ORE round trip must stay at zero loss.
• The in-place drift check diffs the whole repository, so any untracked file makes it fail. Use --dry-run, keep the tree still, and never run a writing gate while a build reads the tree.
• Eleven untracked shell library directories exist from the scheduler pass. They are the recorded open item 10 of that task and they break an in-place drift check until they are swept.

• The reference-data and publish defects 11 and 12 of trade_model_defects.org. They belong to the dq and reference-data work.
• The Qt estate. It was deleted at af67db3062.
• Numerical kernels. Trading consumes their results.
• The models of other components, except the org keys the trading models need.
• The stale ores_schema.puml ER diagram, which is a repository-wide sweep and not a trading fix. PR 6 records it.

ores.trading meets the Component Clean Standard, with two accepted exceptions (D30). Seven PRs delivered it, #2496 the last of them.

• The component is in COMPONENTS_UNDER_TEST, and the drift gate checks it at every address with no drift. 2365 of its 2448 C++ files are generated; the 83 hand-written ones are the composition root, the two readers, the instrument variants, the service host and the tests.
• All 85 protocol headers are generated and twinned in TypeScript. No hand-written file names a subject.
• The shell surface, its recipes and its inventory are generated. The V04 replay answers 449 of 452 replayed recipes; the three that do not are the enum sentinel capture.
• Every generator defect the story found is fixed at source with a regression test in the codegen suite.
• Open: P04, the two export verbs as operation models, and G04, the stamp-loop template defect. Each has a capture in the inbox.