Story: Refactor conventions onto families and bundles

Table of Contents

This page documents a story in Sprint 28. It captures the goal, current status, acceptance criteria, and the tasks that compose it.

1. Goal

A convention is declared once, in its own entity, and carries only its own fields. When this story closes, nothing in the code holds every family at the same time, so a change to one family cannot break another family's build. An import applies the families it carries as one unit of work, and a failure names the family that failed. The ORE conventions file is a package the boundary maps, not a type the components share.

2. Status

Field Value
State DONE
Parent sprint Sprint 28
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-10-24

3. Acceptance

The story closes on the tasks it finished:

  • Model each convention family on its own.
  • Generate a protocol and handler per family.
  • Declare the conventions bundle.
  • Rewire the ORE path to families and packages.
  • Replace the web family list with the registry.
  • Reconcile the record with the merged work.
  • Split the ORE side into per-family units.

4. Tasks

Task State Start End Description
Model each convention family on its own DONE 2026-10-17 2026-10-19 Replace the hand-listed document model with one operation model per convention family, so a family is declared once and carries its own fields. No aggregate of unrelated families survives.
Generate a protocol and handler per family DONE 2026-10-17 2026-10-17 Codegen emits each family's messaging in one registrar translation unit, which includes the generated handler header. The aggregate translation unit still compiles, so the MSVC limit is narrowed and not yet gone.
Declare the conventions bundle DONE 2026-10-17 2026-10-18 A bundle is a set of related families of one owner applied as one unit. The import applies every family refdata owns in one unit of work, atomically, and reports per family.
Rewire the ORE path to families and packages DONE 2026-10-17 2026-10-19 The importer maps a conventions file into per-family messages or one bundle request. The ORE file is a package at the boundary, never a wire type. The exporter reassembles from per-family reads taken at one instant.
Replace the web family list with the registry DONE 2026-10-19 2026-10-19 The web BFF stops carrying a hand-maintained family table and reads the generated registry, so adding a family needs no edit there.
Reconcile the record with the merged work DONE 2026-10-18 2026-10-18 Correct the story and its tasks so the record states what merged and what remains. Stamp the delivered tasks DONE, record their PRs, write the acceptance criteria and results the scaffold left blank, and name the decisions the tasks settled.
Split the ORE side into per-family units DONE 2026-10-19 2026-10-19 Task for: Refactor conventions onto families and bundles

5. Decisions

  • Closed at sprint 28 close with its 7 done tasks. The 3 open tasks and the original acceptance moved to Refactor conventions onto families and bundles — the remaining work in the product backlog inbox.
  • A bundle is the largest atomic unit. The import stages one row per family and applies them in one unit of work, so a reader sees either all of the bundle or none of it. Nothing smaller is atomic and nothing larger is offered.
  • The family list is generated once and every consumer derives from it. A hand-maintained list beside it is a second source of truth and drifts.
  • The registry cannot dispatch by itself. A table of strings cannot call a typed repository, so the same generation emits the per-family apply, and the service calls generated functions instead of listing families by hand.
  • The ORE FX convention is a projection, not an entity. It is a currency pair, that pair's convention, a spot lag and the pair's advance calendars, all of which are entities, so fx stays out of the registry and the boundary mapper derives it.
  • The tenor basis swap convention spans the shared convention row and its two part families, because that is what the document carried. Collapsing it to one registry entry is a later decision.
  • The MSVC failure is accumulated context in the handler translation unit, not one over-wide literal. The investigation in Fix the tenor basis swap convention model and the document TU measured it, and task 8 follows that finding.
  • The conventions import owns no state of its own beyond the staging rows. A retried begin names the import it already opened, and a commit on an import that is not staging is refused, so a crash mid-import leaves an import that can be read and committed. Its expires_at is stamped at begin, 24 hours ahead by default, though nothing sweeps an expired staging import yet.

6. Out of scope

  • Collapsing the tenor basis swap family into one registry entry.
  • Changing the ORE XML model. The generated conventions.hpp stays as it is. This story changes what crosses a component boundary, not the file format.

Emacs 29.3 (Org mode 9.6.15)