Task: Replace the web family list with the registry

Table of Contents

This page documents a task in the Refactor conventions onto families and bundles story. It captures the goal, current status, acceptance, and any notes or results.

1. Goal

The web layer stops keeping its own list of convention families. It reads the list the codegen renders, so adding a family needs no edit in the BFF and the browser cannot disagree with the server about which families exist.

2. Status

Field Value
State DONE
Parent story Refactor conventions onto families and bundles
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-10-19

3. Acceptance

  • The BFF builds its list of plain document families from the generated registry. conventions.ts holds no hand-written entry for a plain document family. It keeps three stated screen choices: the composite family, the kinds the document does not carry, and the writable keys.
  • The C++ header and the TypeScript module come from the same facet and are rendered together, so one regeneration updates both.
  • The generated TypeScript lives under source control, so a regeneration cannot delete the file the BFF imports.
  • npm run typecheck and the BFF suite pass with the generated list in place.

4. Plan

Add a TypeScript facet that renders the registry from the same derivation as the C++ header, commit the module, then have the BFF read it. The registry cannot say which entries the screen shows, so the BFF keeps a short table of screen choices beside the generated list.

5. Measurements

Every number this task claims about a tree, with the command that produced it and the commit it was measured at. A number without both is not a measurement, because a clean-up record describes a tree and trunk moves under a branch: a consumer count, a gate's component count and a suite's size all change with no code changing, and the reader of a bare number cannot tell which tree it came from. Where the raw output matters, put it in an evidence/ file beside the task and name that file in the Command column.

What Value Command Commit
Registry entries 26, of which 3 are absorbed by the composite and 23 are listed as plain families grep -c "key: '" on the generated module 7515c50292 plus this change
Families on the screen 25 before (table rows in origin/main conventions.ts), 26 after: 23 plain, 1 composite, 2 screen-only grep -c on the old table and the BFF test names each family once 7515c50292 plus this change
BFF suite 67 files, 795 tests passed npm test in packages/bff 7515c50292 plus this change
Web suite 1656 tests passed npm test in packages/web 7515c50292 plus this change
Registry module tests 12 passed venv/bin/python -m pytest tests/test_convention_family_registry.py in projects/ores.codegen 7515c50292 plus this change

6. Notes

  • The first attempt was PR #3479. It built the family tables from a generated TypeScript twin and passed on that branch. It was closed unmerged because it was raised outside the process, with no environment tag and no task trailer.
  • That attempt also conflicted with #3474 in the generator both changed. The generator has since been retired for a facet, so the conflict is gone and the retry extends the facet rather than a script.
  • The TypeScript twin must be committed. The staging branch generated the C++ and SQL addresses only, and the web build then failed to resolve the domain modules it imports.
  • The registry and the screen do not describe the same set, so a straight swap was not possible. The registry has 26 entries. The screen drops three of them, convention, tenor_basis_swap_pay_receive and tenor_basis_swap_long_short, because the composite tenor-basis-swap stands for them. The screen also lists tenor and currency-pair, which the conventions document does not carry. The registry has no writable field.
  • The screen order is now alphabetical by key. It was the order of the hand-written table.
  • zero_inflation_index is a document family that the old table omitted. It now appears on the screen, and the three locale files carry its label.
  • The data classification page does not support a bundle of these kinds. A set that needs a screen to be true fails the relatedness test. The capture name-a-set-of-kinds-that-a-screen-groups records the open question.
  • A stale twin survives in projects/ores.web/packages/wire-protocol/dist/generated/refdata/domain/convention_family_registry.js on this checkout. dist is ignored and untracked, so the file is a leftover compile artefact and not a second copy of the registry. Nothing reads it once the source module exists.

7. 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
     

8. PRs

PR Title
#3578 [web] Read the convention family list from the generated registry
#3479 [web,refdata] Read the conventions families from the registry (closed)
#3480 [agile] Record where the BFF registry work stands

9. Review

# Comment summary File Decision Notes
1 The test repeats the absorbed keys that conventions.ts already lists conventions.test.ts Accepted ABSORBED_REGISTRY_KEYS is exported and the test reads it.
2 The SCREEN_ONLY.every check repeats the toEqual check conventions.test.ts Accepted Removed.
3 A mistyped registryKeys entry hides nothing and no test fails conventions.test.ts Accepted A test requires every absorbed key to be a registry key.
4 Use localeCompare in the sort conventions.ts Declined Plain < order does not depend on the locale, so the list order is the same everywhere.
5 Confirm the target allows replaceAll conventions.ts No change The typecheck passes, so the target allows it.
6 Check the alphabetical order in a browser PR Recorded Already a stated limitation of the PR.

10. Result

The BFF no longer holds a list of plain document families. A new TypeScript facet, ores.ts.convention-registry, renders convention_family_registry.ts from the derivation that renders the C++ header, so one regeneration updates both. The module is committed under wire-protocol/src/generated/refdata/domain. conventions.ts filters out the three registry entries that the composite stands for, adds the composite and the two kinds the document does not carry, and sorts the result by key.

The acceptance line was reworded with the owner's agreement. The registry cannot state which entries the screen shows or which it writes, so three screen choices stay hand-written and the code says so. The gain is that a plain document family reaches the screen with no edit. zero-inflation-index is the first, and its label is in the English, Portuguese and French locale files.

Five tests in conventions.test.ts guard the link. They check that every registry family is listed or absorbed, that every absorbed key is a registry key, that the only extra entries are the composite and the two screen-only kinds, that each family's subject prefix matches the registry's subject stem, and that no key repeats. The BFF suite, the web suite and the registry tests pass.

The data classification page does not name the set the screen groups. The capture name-a-set-of-kinds-that-a-screen-groups holds that question.

Emacs 29.3 (Org mode 9.6.15)