test(spec): widen the readers of conversions/registry.ts to its per-entry modules (#29987)

The ADR-0087 registration gate, the affected-docs self-test, the ADR anchor
and the major-18 merge test read the split registry with its entries.

Claude-Session: https://claude.ai/code/session_01WGufzg1QFj9ukYzafVoAqg
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/spec/scripts/conversions-major18-merge.test.ts

@@ -21,6 +21,14 @@
 // end-appended list, the tail-appended definitions and the old array's tail are
 // the lit controls — each MUST conflict, or a clean result would be equally
 // explained by a harness that cannot see a conflict at all.
+//
+// [#29987 codemod] Since the codemod split (`scripts/codemod-split-conversions-registry.mjs`)
+// each conversion is DEFINED in a module of its own, `src/conversions/entries/18/<id>.ts`,
+// which a retirement adds as a new file and which therefore never conflicts. What a
+// retirement still edits in `registry.ts` is two lines: the import of its conversion and
+// its entry in the list. The imports stand in the order the definitions stood, so the
+// placement rule reads them where it read the definitions: an import is a definition's
+// place in this file, and the module it names is read for the definition itself.
 
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import { spawnSync } from 'node:child_process';
@@ -46,10 +54,14 @@ const CLOSE = '];\n';
 const ENTRY = /  \{ conversion: ([A-Za-z_$][\w$]*), order: (\d+(?:\.\d+)?) \},\n/y;
 /** A blank line — which is what a comment between entries is once `maskComments` has blanked it; it belongs to the entry below it. */
 const BLANK = /[ \t]*\n/y;
-/** A conversion definition and its id, which every definition in the file spells on the next line. */
-const DEFINITION = /^(?:export )?const ([A-Za-z_$][\w$]*): MetadataConversion = \{\n  id: '([^'\n]+)',$/gm;
-/** Where a conversion that sorts last is defined: directly above this declaration's doc comment. */
-const TAIL_ANCHOR = '\ninterface OrderedConversion {\n';
+/**
+ * A conversion's place in the file: its import, from the module named for its id
+ * (`./entries/<toMajor>/<id>.js`). The module itself is read for the definition
+ * ({@link definitionInModule}).
+ */
+const DEFINITION = /^import \{ ([A-Za-z_$][\w$]*) \} from '\.\/entries\/18\/([^'\n]+)\.js';$/gm;
+/** The module a conversion is defined in, from its id. */
+const MODULE_PATH = (id: string): string => path.resolve(HERE, `../src/conversions/entries/18/${id}.ts`);
 /** How `CONVERSIONS_BY_MAJOR` reads the entries (the annotation: see that table's docblock). */
 const WIRING = '  18: /* @__PURE__ */ inApplicationOrder(MAJOR_18_CONVERSIONS),\n';
 
@@ -128,11 +140,26 @@ function entriesOf(source: string): { entries: Entry[]; end: number } {
   return { entries, end: at };
 }
 
-/** Every conversion definition in the file, in file order — a commented-out one is not a definition. */
+/** Every conversion's import in the file, in file order — a commented-out one is not an import. */
 function definitionsOf(source: string): { ident: string; id: string; at: number }[] {
   return [...maskOnce(source).matchAll(DEFINITION)].map((m) => ({ ident: m[1]!, id: m[2]!, at: m.index! }));
 }
 
+/** Where a conversion that sorts last is imported: directly after every other conversion's import. */
+function definitionsTail(source: string): number {
+  const defs = definitionsOf(source);
+  expect(defs.length, 'the conversions\' imports').toBeGreaterThan(0);
+  const last = defs.at(-1)!;
+  return source.indexOf('\n', last.at) + 1;
+}
+
+/** The definition in a conversion's module: `const IDENT: MetadataConversion = {` with its id on the next line, exported by name. */
+function definitionInModule(ident: string, id: string): boolean {
+  const text = maskComments(readFileSync(MODULE_PATH(id), 'utf8'));
+  return text.includes(`\nconst ${ident}: MetadataConversion = {\n  id: '${id}',\n  toMajor: 18,\n`)
+    && text.endsWith(`\nexport { ${ident} };\n`);
+}
+
 /** Rule 1, as findings: the entries are sorted strictly by identifier. */
 function sortFindings(source: string): string[] {
   const idents = entriesOf(source).entries.map((e) => e.ident);
@@ -147,13 +174,13 @@ function placementFindings(source: string): string[] {
   return entries.flatMap((e, i) => {
     if (PLACED_BEFORE_THE_RULE.has(e.ident)) return [];
     const at = index.get(e.ident);
-    if (at === undefined) return [`${e.ident}: no \`const ${e.ident}: MetadataConversion\` definition in the file`];
+    if (at === undefined) return [`${e.ident}: no import of \`${e.ident}\` from its module in the file`];
     const want = entries[i + 1]?.ident;
     const next = defs[at + 1]?.ident;
     if (next === want) return [];
     return [
-      `${e.ident} is defined above ${next ?? 'nothing (it is the last conversion defined)'}; define it directly above `
-        + (want ? `${want}'s definition, the entry that follows it` : 'OrderedConversion, after every other conversion'),
+      `${e.ident} is imported above ${next ?? 'nothing (it is the last conversion imported)'}; import it directly above `
+        + (want ? `${want}'s import, the entry that follows it` : 'nothing, after every other conversion\'s import'),
     ];
   });
 }
@@ -165,17 +192,20 @@ function docStart(source: string, offset: number): number {
 }
 
 const kebab = (ident: string): string => `synthetic-${ident.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`)}`;
-const definition = (ident: string): string => `/** A synthetic major-18 retirement. */\nconst ${ident}: MetadataConversion = {\n`
+/** A retirement's line in `registry.ts`: the import of its conversion (the module is a new file, so it never conflicts). */
+const definition = (ident: string): string => `import { ${ident} } from './entries/18/${kebab(ident)}.js';\n`;
+/** The pre-split shape, for the old-shape control only: the definition itself, in the one file. */
+const legacyDefinition = (ident: string): string => `/** A synthetic major-18 retirement. */\nconst ${ident}: MetadataConversion = {\n`
   + `  id: '${kebab(ident)}',\n  toMajor: 18,\n  surface: 'synthetic.key',\n  summary: 'synthetic',\n`
   + '  apply: (stack) => stack,\n  fixture: { before: {}, after: {}, expectedNotices: 0 },\n};\n\n';
 const entry = (ident: string, order: number): string => `  { conversion: ${ident}, order: ${order} },\n`;
 
-/** Offset of the definition the doc comment asks for: above the next entry's, or above `OrderedConversion`. */
+/** Offset of the import the doc comment asks for: above the next entry's, or after every other conversion's. */
 function definitionSite(source: string, ident: string): number {
   const next = entriesOf(source).entries.find((e) => e.ident > ident);
-  if (!next) return docStart(source, source.indexOf(TAIL_ANCHOR) + 1);
+  if (!next) return definitionsTail(source);
   const def = definitionsOf(source).find((d) => d.ident === next.ident);
-  expect(def, `${next.ident}'s definition`).toBeDefined();
+  expect(def, `${next.ident}'s import`).toBeDefined();
   return docStart(source, def!.at);
 }
 
@@ -198,9 +228,9 @@ function retireAtListEnd(source: string, ident: string, order: number): string {
   return insert(withDefinition, entriesOf(withDefinition).end, entry(ident, order));
 }
 
-/** The definition half done the old way: defined after every other conversion (the entry still sorted). */
+/** The definition half done the old way: imported after every other conversion (the entry still sorted). */
 function retireAtDefinitionsEnd(source: string, ident: string, order: number): string {
-  const tail = docStart(source, source.indexOf(TAIL_ANCHOR) + 1);
+  const tail = definitionsTail(source);
   return sortedEntry(insert(source, tail, definition(ident)), ident, order);
 }
 
@@ -302,9 +332,10 @@ describe('major 18 in the conversions registry — the shape the merge needs (#2
     ).toEqual([]);
   });
 
-  it('each entry is a major-18 conversion defined in this file, and the list is all of them', () => {
+  it('each entry is a major-18 conversion imported from the module that defines it, and the list is all of them', () => {
     const ids = new Map(definitionsOf(SOURCE).map((d) => [d.ident, d.id]));
     expect(IDENTS.filter((i) => !ids.has(i))).toEqual([]);
+    expect(IDENTS.filter((i) => !definitionInModule(i, ids.get(i)!)), 'each module defines its conversion under its id').toEqual([]);
     expect(new Set(IDENTS.map((i) => ids.get(i)))).toEqual(new Set(APPLIED));
     expect(APPLIED).toHaveLength(IDENTS.length);
     expect(CONVERSIONS_BY_MAJOR[18]!.every((c) => c.toMajor === 18)).toBe(true);
@@ -321,7 +352,7 @@ describe('major 18 in the conversions registry — the shape the merge needs (#2
     expect(MIGRATIONS_BY_MAJOR[18]!.conversionIds).toEqual(order);
   });
 
-  it('a conversion added after the rule is defined directly above the entry that follows it', () => {
+  it('a conversion added after the rule is imported directly above the entry that follows it', () => {
     expect(PLACED_BEFORE_THE_RULE.size, '⛔ the exemption is closed: place a new conversion by the rule').toBe(46);
     expect(placementFindings(SOURCE)).toEqual([]);
   });
@@ -376,9 +407,9 @@ describe('major 18 in the conversions registry — two retirements, no merge dri
     expect(placementFindings(retireAtDefinitionsEnd(SOURCE, A, NEXT_ORDER))).toEqual([
       ...(PLACED_BEFORE_THE_RULE.has(neighbour)
         ? []
-        : [`${neighbour} is defined above ${IDENTS[k]}; define it directly above ${A}'s definition, the entry that follows it`]),
-      `${A} is defined above nothing (it is the last conversion defined); define it directly above ${IDENTS[k]}'s `
-        + 'definition, the entry that follows it',
+        : [`${neighbour} is imported above ${IDENTS[k]}; import it directly above ${A}'s import, the entry that follows it`]),
+      `${A} is imported above nothing (it is the last conversion imported); import it directly above ${IDENTS[k]}'s `
+        + 'import, the entry that follows it',
     ]);
   });
 
@@ -408,7 +439,7 @@ describe('major 18 in the conversions registry — two retirements, no merge dri
     expect(m.conflicted).toEqual([REL]);
   });
 
-  it('the same two conversions defined after every other conversion conflict — the definitions have a tail too', () => {
+  it('the same two conversions imported after every other conversion conflict — the imports have a tail too', () => {
     const m = repo.merge('definitions-end-a', 'definitions-end-b');
     expect(m.status).toBe(1);
     expect(m.conflicted).toEqual([REL]);
@@ -419,7 +450,7 @@ describe('major 18 in the conversions registry — two retirements, no merge dri
       + "  id: 'view-list-tabs-removed',\n};\n\n"
       + 'export const CONVERSIONS_BY_MAJOR = {\n  18: [\n    viewListTabsRemoved,\n  ],\n};\n';
     const append = (ident: string) => old
-      .replace('export const CONVERSIONS_BY_MAJOR', `${definition(ident)}export const CONVERSIONS_BY_MAJOR`)
+      .replace('export const CONVERSIONS_BY_MAJOR', `${legacyDefinition(ident)}export const CONVERSIONS_BY_MAJOR`)
       .replace('    viewListTabsRemoved,\n', `    viewListTabsRemoved,\n    ${ident},\n`);
     const legacy = new FileRepo(old);
     try {

scripts/adr-anchors/packages__spec__src__conversions__entries__18__declared-index-unique-scope.ts.json

@@ -0,0 +1,7 @@
+{
+  "file": "packages/spec/src/conversions/entries/18/declared-index-unique-scope.ts",
+  "adrs": [
+    "ADR-0120"
+  ],
+  "invariant": "`declared-index-unique-scope` (ADR-0120 D2, toMajor 18) rewrites a DECLARED index's bare `unique: true` to `'global'` — and nothing else: field-level `unique: true` is never converted (D1: it means per-organization and stays valid), and `false` / `'global'` / `'organization'` pass through untouched. It is lossless only because `'global'` IS the verbatim column list bare `true` built — the S4/S5 nine-key corpus is pinned byte-identical before and after in driver-sql's `sql-driver-unique-tenancy.test.ts`. ⛔ Never re-target it at `'organization'` (the #4986 trap in mirror image, a silent physical change) and never take it off `retiredFromLoadPath`: the authoring funnel must REFUSE the bare spelling so the author states the scope, while data-at-rest seams replay it."
+}

scripts/adr-anchors/packages__spec__src__conversions__registry.ts.json

@@ -1,7 +1,6 @@
 {
   "file": "packages/spec/src/conversions/registry.ts",
   "adrs": [
-    "ADR-0120",
     "ADR-0087"
   ],
   "invariant": "`declared-index-unique-scope` (ADR-0120 D2, toMajor 18) rewrites a DECLARED index's bare `unique: true` to `'global'` — and nothing else: field-level `unique: true` is never converted (D1: it means per-organization and stays valid), and `false` / `'global'` / `'organization'` pass through untouched. It is lossless only because `'global'` IS the verbatim column list bare `true` built — the S4/S5 nine-key corpus is pinned byte-identical before and after in driver-sql's `sql-driver-unique-tenancy.test.ts`. ⛔ Never re-target it at `'organization'` (the #4986 trap in mirror image, a silent physical change) and never take it off `retiredFromLoadPath`: the authoring funnel must REFUSE the bare spelling so the author states the scope, while data-at-rest seams replay it."

scripts/check-adr-0087-registration.mjs

@@ -475,6 +475,7 @@ const SELF_TEST_BATTERIES = Object.freeze({
   'V3: the real repository is the case that matters -- this gate\'s own vocabulary': 10,
   'W1-W6 (#22485): the parser-rot witness is GENERATED at head, never read from a committed copy': 9,
   'GR1-GR7 (#22554): the migration ledger is GENERATED at build, read from its template and entry files': 13,
+  'CR1-CR3 (#29987): the conversions ledger is split per entry, read from registry.ts and its modules': 3,
   'Unit pins on the two pattern-shaped judgements': 29,
   'the floors: what the new vocabulary must refuse': 9,
   'the floors: labels that are NOT mentions, and mentions that ARE evidenced': 9,
@@ -497,7 +498,7 @@ const SELF_TEST_BATTERIES = Object.freeze({
 
 // DELETING an entry silences that battery's floor exactly as effectively as
 // zeroing it, so the roster's own size is pinned too.
-const SELF_TEST_BATTERY_FLOOR = 59;
+const SELF_TEST_BATTERY_FLOOR = 60;
 
 // The key an assertion is filed under when no battery is open. It is not a
 // declared battery, so it reds by the same set difference rather than silently
@@ -531,6 +532,16 @@ export const MIGRATION_LEDGER_ENTRY_DIRS = [
   'packages/spec/src/migrations/entries/retired-defs',
 ];
 
+/**
+ * Where `LEDGER_SOURCES[1]`'s conversions live since the #29987 codemod split
+ * (`scripts/codemod-split-conversions-registry.mjs`): one module per conversion
+ * under this directory, plus the shared helpers. `registry.ts` itself still
+ * exists and lists them, but no conversion's `id:` line is in it any more. A rev
+ * that tracks no `.ts` file here is a rev from before the split, and the
+ * registry is the whole text. See `conversionLedgerTextAt`.
+ */
+export const CONVERSION_LEDGER_ENTRY_DIR = 'packages/spec/src/conversions/entries';
+
 /**
  * The generator whose output proves the source parser still matches (#4690), and
  * the inputs it reads, relative to the tree root. Since #22485 there is no
@@ -2341,7 +2352,7 @@ export function ledgerAt(rev, cwd) {
   const bySource = {};
   const missingSources = [];
   for (const path of LEDGER_SOURCES) {
-    const src = path === LEDGER_SOURCES[0] ? migrationLedgerTextAt(rev, cwd) : showOrNull(rev, path, cwd);
+    const src = path === LEDGER_SOURCES[0] ? migrationLedgerTextAt(rev, cwd) : conversionLedgerTextAt(rev, cwd);
     if (src === null) { missingSources.push(path); continue; }
     const found = extractIds(src);
     bySource[path] = found.length;
@@ -2381,6 +2392,33 @@ export function migrationLedgerTextAt(rev, cwd) {
   return [template, ...entries.map((p) => texts.get(p))].join('\n');
 }
 
+/**
+ * The text of the conversions ledger at a rev: `registry.ts` followed by every
+ * `.ts` module under `CONVERSION_LEDGER_ENTRY_DIR` (sorted), which `extractIds`
+ * reads as a set. Before the #29987 split no module exists there and the
+ * registry is the whole text; after it, the registry's own text carries no id.
+ * `null` when the rev has no registry: a red in `assertInputs`.
+ *
+ * Exported for the self-test's CR battery.
+ *
+ * @returns {string | null}
+ */
+export function conversionLedgerTextAt(rev, cwd) {
+  const registry = showOrNull(rev, LEDGER_SOURCES[1], cwd);
+  if (registry === null) return null;
+  let listed;
+  try {
+    listed = git(['ls-tree', '-r', '--name-only', rev, '--', CONVERSION_LEDGER_ENTRY_DIR], cwd);
+  } catch {
+    return null;
+  }
+  const entries = listed.split('\n').map((p) => p.trim()).filter((p) => p.endsWith('.ts')).sort();
+  if (entries.length === 0) return registry;
+  const texts = showManyOrNull(rev, entries, cwd);
+  if (texts.size !== entries.length) return null;
+  return [registry, ...entries.map((p) => texts.get(p))].join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Input assertions -- absence is never a pass (#4690)
 // ---------------------------------------------------------------------------
@@ -5837,7 +5875,7 @@ function ledgerTouchingCommits(path, head, cwd) {
     try { names = git(['show', '--name-only', '--format=', sha], cwd); } catch { continue; }
     // The generated era (#22554): a registration commit adds an entry file and
     // touches no registry, so the ledger's two committed sources count too.
-    if ([...LEDGER_SOURCES, MIGRATION_LEDGER_TEMPLATE, ...MIGRATION_LEDGER_ENTRY_DIRS].some((src) => names.includes(src))) hits.push(sha);
+    if ([...LEDGER_SOURCES, MIGRATION_LEDGER_TEMPLATE, ...MIGRATION_LEDGER_ENTRY_DIRS, CONVERSION_LEDGER_ENTRY_DIR].some((src) => names.includes(src))) hits.push(sha);
   }
   return { available: true, shas: hits };
 }
@@ -8871,6 +8909,46 @@ function selfTest() {
     red('GR7 transition: an entry carried over from the committed era is not new', transition('alpha'), [/none of those ids is NEW in this diff/]);
   }
 
+  // ---- CR1-CR3 (#29987): the conversions ledger is split per entry ----------
+  //
+  // After the codemod split, `registry.ts` imports and lists the conversions and
+  // each conversion's `id:` line lives in its own module under
+  // `CONVERSION_LEDGER_ENTRY_DIR`. A ledger read off `registry.ts` alone would
+  // find ZERO ids there -- every `registered` claim on a conversion would fail.
+  battery('CR1-CR3 (#29987): the conversions ledger is split per entry, read from registry.ts and its modules');
+  {
+    const splitRepo = (files) => {
+      const dir = mkdtempSync(join(tmpdir(), 'adr0087-conversions-split-'));
+      cleanup.push(dir);
+      const w = (rel, text) => { mkdirSync(dirname(join(dir, rel)), { recursive: true }); writeFileSync(join(dir, rel), text); };
+      git(['init', '-q', '-b', 'main'], dir);
+      git(['config', 'user.email', 't@t'], dir);
+      git(['config', 'user.name', 't'], dir);
+      for (const [rel, text] of Object.entries(files)) w(rel, text);
+      git(['add', '-A'], dir);
+      git(['commit', '-qm', 'split'], dir);
+      return dir;
+    };
+    const HOST = "import { a } from './entries/18/conv-a.js';\nexport const ALL = [a];\n";
+    const MODULE = (id) => `const a = {\n  id: '${id}',\n  toMajor: 18,\n};\n\nexport { a };\n`;
+    const c1 = splitRepo({
+      [LEDGER_SOURCES[1]]: HOST,
+      [`${CONVERSION_LEDGER_ENTRY_DIR}/18/conv-a.ts`]: MODULE('conv-a'),
+      [`${CONVERSION_LEDGER_ENTRY_DIR}/README.md`]: "  id: 'readme-example',\n",
+    });
+    // CR1 control: the host alone carries no id, so a green below is the modules'.
+    assert(extractIds(showOrNull('HEAD', LEDGER_SOURCES[1], c1)).length === 0, 'CR1 control: the split host must carry no id line');
+    const t1 = conversionLedgerTextAt('HEAD', c1);
+    assert(t1 !== null && extractIds(t1).join() === 'conv-a', `CR1: the split ledger reads the module's id -- got ${JSON.stringify(t1 && extractIds(t1))}`);
+    const l1 = ledgerAt('HEAD', c1);
+    assert(l1.ids.has('conv-a') && l1.bySource[LEDGER_SOURCES[1]] === 1, `CR1: ledgerAt reads the split ledger -- got ${JSON.stringify(l1.bySource)}`);
+    // CR2: a non-`.ts` file under the entries directory is not read.
+    assert(!extractIds(t1 ?? '').includes('readme-example'), 'CR2: an id-shaped line in a non-.ts file under entries/ must not be read');
+    // CR3: before the split (no module under entries/) the registry is the whole text.
+    const c3 = splitRepo({ [LEDGER_SOURCES[1]]: MODULE('pre-split') });
+    assert(conversionLedgerTextAt('HEAD', c3) === MODULE('pre-split'), 'CR3: an unsplit rev reads registry.ts alone');
+  }
+
   // ---- Unit pins on the two pattern-shaped judgements ----------------------
   //
   // P1-P3 are the LABEL branch, unchanged since #6148 -- the template placeholder