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.tsholds 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 typecheckand 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_receiveandtenor_basis_swap_long_short, because the compositetenor-basis-swapstands for them. The screen also liststenorandcurrency-pair, which the conventions document does not carry. The registry has nowritablefield. - The screen order is now alphabetical by key. It was the order of the hand-written table.
zero_inflation_indexis 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-groupsrecords the open question. - A stale twin survives in
projects/ores.web/packages/wire-protocol/dist/generated/refdata/domain/convention_family_registry.json this checkout.distis 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
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.