@henols/vice-mcp 0.2.2 → 0.2.3

package/anno-enum-gen.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 // anno-enum-gen.ts -- the ONE authoritative place in this repo for value ->
 // variant naming, the adjacent-pair rule, identifier sanitization, the
-// per-register enum plan and the coverage report's wording contract
-// (D-20/D-22/D-23, ANNO-13).
+// per-register enum plan, the coverage report's wording contract, and (as of
+// phase 45 plan 45-03) the multi-bit register DECOMPOSITION into named,
+// OR-able terms (D-15/D-16/D-17/D-20/D-22/D-23, ANNO-13).
 //
 // WHAT LEFT, WHAT STAYED, AND WHERE THE ROUTE RETURNS (plan 29-10, D-01,
 // 2026-08-30). Read this paragraph before looking for a function that is not
@@ -39,17 +40,34 @@
 //       leaving it to be inferred from a row count.
 //     - `sanitizeVariantMap()` and the identifier gate it runs, unchanged.
 //
-//   WHERE THE ROUTE RETURNS: **NO PHASE CURRENTLY OWNS ITS RETURN**, and this
-//   line used to say otherwise. It forecast a rebuild of the fetch and the
-//   install over this project's own annotation store, rendering the enums into
-//   the ACME export. The ACME export route itself did come back on 2026-08-31,
-//   as the `anno export-asm` CLI verb -- but the work that rebuilt it covered
-//   that route ONLY: no requirement and no success criterion of it mentioned
-//   `gen-enums`, and no phase currently owns rebuilding it. The forecast was
-//   therefore wrong, and it is CORRECTED here
-//   rather than deleted, because deleting the notice would erase the record
-//   that the capability went missing. Everything above is the specification
-//   whoever eventually rebuilds it builds against.
+//   WHERE THE ROUTE RETURNS: this line used to say "NO PHASE CURRENTLY OWNS
+//   ITS RETURN", and that too is now CORRECTED rather than deleted, for the
+//   same reason the paragraph above was: deleting a withdrawal notice erases
+//   the record that a capability went missing, and deleting a return notice
+//   would erase the record of when and why it came back. The first
+//   correction (recorded here, kept for the history): it forecast a rebuild
+//   of the fetch and the install over this project's own annotation store,
+//   rendering the enums into the ACME export. The ACME export route itself
+//   did come back on 2026-08-31, as the `anno export-asm` CLI verb -- but the
+//   work that rebuilt it covered that route ONLY: no requirement and no
+//   success criterion of it mentioned `gen-enums`, and at that time no phase
+//   owned rebuilding it.
+//
+//   THE SECOND CORRECTION, dated 2026-09-11 (phase 45 plan 45-03, D-15):
+//   Phase 45 owns it now, and has returned it -- the ENUM half of `ANNO-13`
+//   only. `fetchRegisterSearchRows()` walks a store's own `code`-typed ranges
+//   through the same `disasm-decoder.ts` `decode()` `anno_disassemble` uses,
+//   `generateEnumsFromStore()` strings fetch -> `pairSearchRows()` ->
+//   `planEnumsForPairing()` -> `sanitizeVariantMap()` -> `installPlannedEnums()`
+//   -> `buildEnumGenerationReport()`, and `installPlannedEnums()` installs
+//   through the same `createProjectEnum()`/`updateProjectEnum()`/
+//   `applyEnumUsage()` write path the by-hand route already used. The symbol
+//   round trip (`ANNO-14`/`ANNO-15`, `export-lbl`/`import-lbl`) is a SEPARATE
+//   capability this phase does not touch and remains unowned -- see
+//   `.planning/PROJECT.md`'s own withdrawal notice, corrected in the same
+//   plan. Everything above this paragraph is the specification this rebuild
+//   was built against, and it needed no changes to build against: every
+//   surviving heuristic is called here unmodified.
 //
 // MEASURED MECHANISM FACTS, PAST TENSE -- kept because they are WHY the
 // heuristics have the shape they have, not because anything still calls the
@@ -115,6 +133,11 @@ import { fileURLToPath } from "node:url";
 
 import type { RegBitsField, RegBitsTable } from "./anno-regbits-gen.ts";
 import { MAX_ACME_IDENTIFIER_LENGTH, assertLegalAcmeIdentifier } from "./anno-acme-ident.ts";
+import { decode } from "./disasm-decoder.ts";
+import type { Instruction } from "./disasm-decoder.ts";
+import { applyEnumUsage, createProjectEnum, listRanges, updateProjectEnum } from "./anno-store.ts";
+import type { AnnoStoreHandle } from "./anno-store.ts";
+import { AnnoLabelError } from "./anno-types.ts";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REGBITS_PATH = join(HERE, "anno-regbits.json");
@@ -182,32 +205,85 @@ export function registerKeyFor(address: number): string {
  * The measured target this function is pinned against:
  * `variantNameFor(0xd011, 0x1b) === "YSCROLL3_ROW25_SCREENON_TEXT"`.
  */
-export function variantNameFor(register: number, value: number): string {
+/** Looks up `register`'s bit-name table entry, or throws naming the register
+ * and the remedy -- the ONE lookup+refusal both `variantNameFor()` and
+ * `decomposeRegisterValue()` share, so the two can never disagree about
+ * which registers are decodable at all. */
+function requireRegBitsEntry(key: string, callerName: string): RegBitsField[] {
   const table = loadRegBits();
-  const key = registerKeyFor(register);
   const entry = table[key];
   if (!entry) {
     throw new Error(
-      `variantNameFor: no bit-name table entry for register ${key} -- anno-regbits.json has no fields ` +
+      `${callerName}: no bit-name table entry for register ${key} -- anno-regbits.json has no fields ` +
         "for this address (add an OVERRIDES entry in anno-regbits-gen.ts, or exclude it from generation).",
     );
   }
+  return entry.fields as RegBitsField[];
+}
+
+/**
+ * THE ONE MEMBERSHIP-TEST PREDICATE (45-REVIEW CR-01): answers "does
+ * `anno-regbits.json` have an entry for this register at all", independent
+ * of whether that entry, once found, can fully decompose any particular
+ * value. `pairSearchRows()` above already narrows candidate `sta` targets
+ * this same way (`knownRegisters.has(key)`, built from this table's own
+ * keys) before ever treating one as a register; this export gives the two
+ * D-16 render surfaces (`anno-export-asm.ts`, `anno-tools.ts`'s
+ * `renderDisassembleListing()`) the identical membership check so a
+ * register-SHAPED enum name for a register the table simply does not cover
+ * (e.g. `D020`, `D021` -- confirmed absent, `docs/phase45-closure-dxa-family.md`)
+ * falls through to the plain single-symbol path instead of being attempted,
+ * and failing, through `decomposeRegisterValue()`.
+ *
+ * `key` is the SAME `$`-prefixed shape `registerKeyFor()` produces and the
+ * table's own keys use (e.g. `"$D011"`) -- callers holding only the bare
+ * `regKey.slice(1)` enum name (e.g. `"D011"`) must prefix it with `$` before
+ * calling this, exactly as `requireRegBitsEntry()`'s own callers already do
+ * via `registerKeyFor()`.
+ *
+ * Deliberately NOT folded into `requireRegBitsEntry()`: that function's job
+ * is "fetch or throw naming the remedy" for a caller that already believes
+ * the register IS decodable; this function's job is "may I even ask" for a
+ * caller that does not yet know. Collapsing them would force every
+ * membership check to pay for (and catch) a thrown error it does not want.
+ */
+export function hasRegBitsEntry(key: string): boolean {
+  return loadRegBits()[key] !== undefined;
+}
+
+/**
+ * Decodes ONE field of `register`'s value against `field` -- the single
+ * decode step `variantNameFor()` and `decomposeRegisterValue()` BOTH walk in
+ * the same ascending bit order (Task 1's own rule: "do not write a second
+ * decode"). A numeric field ALWAYS returns a non-empty token (total by
+ * construction). A flag/enum field's token is looked up in `field.tokens`;
+ * an explicitly-silent state (empty string) is returned as `""`, never
+ * treated as absent; a genuinely missing token throws, naming the register,
+ * the field and the decoded value, exactly as before this extraction.
+ */
+function decodeField(key: string, field: RegBitsField, value: number): { decoded: number; token: string } {
+  const decoded = (value & field.mask) >>> field.shift;
+  if (field.kind === "numeric") {
+    return { decoded, token: `${field.name}${decoded}` };
+  }
+  const token = field.tokens?.[decoded];
+  if (token === undefined) {
+    throw new Error(
+      `variantNameFor: register ${key} field "${field.name}" (kind ${field.kind}) has no token for decoded ` +
+        `value ${decoded} (full register value 0x${value.toString(16)}) -- refusing rather than silently ` +
+        "dropping a field, which could make two distinct register values decode to the same name.",
+    );
+  }
+  return { decoded, token };
+}
+
+export function variantNameFor(register: number, value: number): string {
+  const key = registerKeyFor(register);
+  const fields = requireRegBitsEntry(key, "variantNameFor");
 
   const tokens: string[] = [];
-  for (const field of entry.fields as RegBitsField[]) {
-    const decoded = (value & field.mask) >>> field.shift;
-    if (field.kind === "numeric") {
-      tokens.push(`${field.name}${decoded}`);
-      continue;
-    }
-    const token = field.tokens?.[decoded];
-    if (token === undefined) {
-      throw new Error(
-        `variantNameFor: register ${key} field "${field.name}" (kind ${field.kind}) has no token for decoded ` +
-          `value ${decoded} (full register value 0x${value.toString(16)}) -- refusing rather than silently ` +
-          "dropping a field, which could make two distinct register values decode to the same name.",
-      );
-    }
+  for (const field of fields) {
+    const { token } = decodeField(key, field, value);
     if (token !== "") tokens.push(token);
   }
   if (tokens.length === 0) {
@@ -226,6 +302,150 @@ export function variantNameFor(register: number, value: number): string {
   return tokens.join("_");
 }
 
+// ---------------------------------------------------------------------------
+// The ONE owning multi-bit decoder (Task 1, D-16/D-17). `variantNameFor()`
+// above already decodes a value into per-field tokens and joins them with
+// `_` into ONE total name; this is that SAME token list, unjoined, each term
+// carrying its own masked value -- so the OR-ed decomposition and the
+// whole-value enum member are provably one vocabulary, never two.
+// ---------------------------------------------------------------------------
+
+/** One named, OR-able term of a decomposed register write. `name` is the
+ * emitted ACME identifier (`<enumName>_<field token>`, the same
+ * `regKey.slice(1)` prefix `planEnumsForPairing()` already uses for its own
+ * `enumName`). `value` is this term's own masked contribution
+ * (`value & field.mask`) -- the bitwise OR of every term's `value` in a
+ * `RegisterDecomposition` reconstructs the original byte exactly, or
+ * `decomposeRegisterValue()` refuses rather than return the lossy result. */
+export interface RegisterTerm {
+  name: string;
+  value: number;
+  fieldName: string;
+  decoded: number;
+}
+
+/** The full decomposition of one register write. `comment` is the
+ * mechanical decode text (`<REGKEY>: <FIELD>=<decoded>`, comma-separated, in
+ * ascending bit order) -- D-17's readability half; `terms` is the OR-able
+ * half. `multiField` is true when the register's own table entry has two or
+ * more fields, regardless of how many terms a particular value happened to
+ * produce (a single-field register, or a value that silenced every
+ * flag/enum field but one, is not "multi-bit" in the sense D-17 cares
+ * about). */
+export interface RegisterDecomposition {
+  terms: RegisterTerm[];
+  comment: string;
+  multiField: boolean;
+}
+
+/**
+ * THE ONE OWNING DECODER (D-16): splits `value` into one named term per
+ * bit-field of `register`, arithmetically exact. Both render surfaces
+ * (`anno-export-asm.ts`'s OR-ed constants, plan 45-05; `anno_disassemble`'s
+ * readable comment, plan 45-05) consume THIS function rather than decoding
+ * independently -- see this module's own header for why that is the whole
+ * point.
+ *
+ * Rules, each pinned by a test in `anno-enum-gen.test.ts`:
+ *   - Walks the SAME field loop, in the SAME ascending bit order, and the
+ *     SAME per-field decode (`decodeField()` above) that `variantNameFor()`
+ *     walks -- never a second decode.
+ *   - A field whose token is the explicit empty string AND whose masked
+ *     contribution is zero is OMITTED: it contributes nothing to the OR and
+ *     nothing to the name (the silent-by-design case).
+ *   - A field whose token is the empty string but whose masked contribution
+ *     is NON-zero is a DATA ERROR in `anno-regbits.json`'s own OVERRIDES
+ *     table -- refused by name, exactly like the missing-token case
+ *     `decodeField()` already refuses.
+ *   - After building the terms, the OR of every term's `value` MUST equal
+ *     the input `value`. When it does not -- the table's fields do not cover
+ *     every set bit of `value` -- this REFUSES, naming the register, the
+ *     value and the uncovered bits in hex, with the remedy. Never emits a
+ *     residual hex literal into the term list: a magic number in the OR
+ *     expression is exactly what criterion 5 forbids.
+ *   - The degenerate all-silent case (every field decodes to a silent
+ *     token) returns the single `V<value>` term rather than an empty list,
+ *     mirroring `variantNameFor()`'s own fallback so the two never disagree
+ *     about what that value is called. This can only happen when `value`
+ *     itself is `0` for a register whose fields fully cover the byte (every
+ *     silent field's masked contribution is, by the rule above, zero) --
+ *     the OR-reconstruction check above still runs FIRST, so a value this
+ *     branch would otherwise mis-accept as "all silent" but that actually
+ *     has uncovered bits is refused there instead, never silently treated
+ *     as degenerate.
+ */
+export function decomposeRegisterValue(register: number, value: number): RegisterDecomposition {
+  const key = registerKeyFor(register);
+  const fields = requireRegBitsEntry(key, "decomposeRegisterValue");
+  const enumName = key.slice(1); // "$D011" -> "D011", the SAME prefix planEnumsForPairing() derives.
+
+  const terms: RegisterTerm[] = [];
+  const commentParts: string[] = [];
+  let orAccumulator = 0;
+
+  for (const field of fields) {
+    const { decoded, token } = decodeField(key, field, value);
+    const masked = value & field.mask;
+    commentParts.push(`${field.name}=${decoded}`);
+
+    if (token === "") {
+      if (masked !== 0) {
+        throw new Error(
+          `decomposeRegisterValue: register ${key} field "${field.name}" decoded a NON-ZERO contribution ` +
+            `(0x${masked.toString(16)}) from an explicitly-silent token at decoded value ${decoded} (full register ` +
+            `value 0x${value.toString(16)}) -- a silent token must correspond to a zero masked contribution, or the ` +
+            "OR-reconstruction below would silently drop a real bit. This is a data error in anno-regbits.json's " +
+            "OVERRIDES table (anno-regbits-gen.ts), not a value this function can decompose.",
+        );
+      }
+      continue; // silent-by-design, zero contribution -- omitted from both the OR and the name.
+    }
+
+    terms.push({ name: `${enumName}_${token}`, value: masked, fieldName: field.name, decoded });
+    orAccumulator |= masked;
+  }
+
+  if (orAccumulator !== value) {
+    const uncovered = value & ~orAccumulator & 0xff;
+    throw new Error(
+      `decomposeRegisterValue: register ${key} value 0x${value.toString(16)} is not fully covered by its fields -- the ` +
+        `OR of the decomposed terms is 0x${orAccumulator.toString(16)}, leaving bits 0x${uncovered.toString(16)} unaccounted ` +
+        "for. Refusing to emit a lossy decomposition rather than a residual hex literal (add an OVERRIDES entry in " +
+        "anno-regbits-gen.ts and regenerate anno-regbits.json).",
+    );
+  }
+
+  if (terms.length === 0) {
+    // Every field decoded to an explicitly-silent, zero-contribution token --
+    // the invariant check above already proved value === 0 in this branch
+    // (orAccumulator is the OR of zeros), so this mirrors variantNameFor()'s
+    // own V<value> fallback exactly, never disagreeing about what value 0
+    // (or any all-silent value) is called.
+    terms.push({ name: `${enumName}_V${value}`, value, fieldName: "", decoded: value });
+  }
+
+  // T-45-10's mitigation, run here rather than left to a downstream caller:
+  // MEASURED against the real committed table (register $0001, "MOS 6510
+  // Micro-Processor On-Chip I/O Port") that a numeric-leading `enumName`
+  // (`registerKeyFor(1).slice(1)` is the all-digit string "0001") produces
+  // an illegal ACME identifier for EVERY term of that register, regardless
+  // of value -- `sanitizeVariantMap()` never catches this because it only
+  // validates a bare variant name, never the enum-name prefix this
+  // function's own OR-emission shape adds. Refusing here, before returning
+  // anything, is the same client-side-before-I/O property
+  // `sanitizeVariantMap()` already holds -- an illegal name provably never
+  // reaches a render surface.
+  for (const term of terms) {
+    assertLegalAcmeIdentifier(term.name, `decomposeRegisterValue term for register ${key} value 0x${value.toString(16)}`);
+  }
+
+  return {
+    terms,
+    comment: `${key}: ${commentParts.join(", ")}`,
+    multiField: fields.length >= 2,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // The two-pass search + adjacent-pair (D-23).
 // ---------------------------------------------------------------------------
@@ -531,3 +751,169 @@ export function buildEnumGenerationReport(
   };
 }
 
+// ---------------------------------------------------------------------------
+// Task 2 (D-15): THE REBUILT FETCH AND INSTALL, over this project's own
+// disassembler and store. Everything above this line is a surviving
+// heuristic, called here but never edited (`variantNameFor()`,
+// `pairSearchRows()`, `planEnumsForPairing()`, `sanitizeVariantMap()`,
+// `buildEnumGenerationReport()`).
+// ---------------------------------------------------------------------------
+
+/** The minimal shape this module's fetch needs from a loaded image: the
+ * origin address and the raw body bytes. Deliberately NOT importing
+ * `anno-tools.ts`'s own `LoadedImage` (a private, tool-layer interface) --
+ * that would pull the tool-dispatch module into this one, and all this fetch
+ * needs from it is these two fields. */
+interface EnumSourceImage {
+  origin: number;
+  body: Uint8Array;
+}
+
+const IMMEDIATE_LOAD_MNEMONICS: ReadonlySet<string> = new Set(["lda", "ldx", "ldy"]);
+const ABSOLUTE_STORE_MNEMONICS: ReadonlySet<string> = new Set(["sta", "stx", "sty"]);
+
+/** The slice of `image` covering `[start, endInclusive]`, or `null` when the
+ * span is not entirely inside the image -- mirrors `anno-tools.ts`'s own
+ * `sliceSpan()` bounds discipline (never a short slice, never a fabricated
+ * byte for a range this image does not cover) without importing that
+ * private function. */
+function sliceImageRange(image: EnumSourceImage, start: number, endInclusive: number): Uint8Array | null {
+  const from = start - image.origin;
+  const to = endInclusive - image.origin;
+  if (from < 0 || to >= image.body.length || from > to) return null;
+  return image.body.subarray(from, to + 1);
+}
+
+function searchRowAddress(instr: Instruction): string {
+  return `$${instr.address.toString(16).toUpperCase().padStart(4, "0")}`;
+}
+
+function toSearchRow(instr: Instruction, operand: string): DisasmSearchRow {
+  return { address: searchRowAddress(instr), address_decimal: instr.address, label: "", mnemonic: instr.mnemonic, operand, comment: "" };
+}
+
+export interface FetchRegisterSearchRowsOptions {
+  maxResults?: number;
+}
+
+export interface FetchRegisterSearchRowsResult {
+  ldaRows: DisasmSearchRow[];
+  staRows: DisasmSearchRow[];
+}
+
+/**
+ * THE REBUILT FETCH (D-15). Walks `handle`'s own `code`-typed ranges,
+ * decoding each through the SAME `disasm-decoder.ts` `decode()` function
+ * `anno_disassemble` uses -- never a second decoder, never a regex over
+ * rendered text. Returns two plain row arrays in the exact `DisasmSearchRow`
+ * shape `pairSearchRows()` already consumes: pass 1, immediate loads
+ * (`lda`/`ldx`/`ldy`); pass 2, absolute stores (`sta`/`stx`/`sty`) whose
+ * target is a register `anno-regbits.json` knows.
+ *
+ * `maxResults` bounds EACH pass independently AS IT IS FETCHED, not merely
+ * reported afterwards -- that is what makes `pairSearchRows()`'s own
+ * truncation signal (a returned row count equal to the ceiling) a true
+ * measurement rather than a coincidence: capping here is the only way a
+ * caller comparing the returned length against the same ceiling can trust
+ * what it sees (D-23's "no silent caps").
+ */
+export function fetchRegisterSearchRows(
+  handle: AnnoStoreHandle,
+  image: EnumSourceImage,
+  opts: FetchRegisterSearchRowsOptions = {},
+): FetchRegisterSearchRowsResult {
+  const maxResults = opts.maxResults ?? DEFAULT_MAX_RESULTS;
+  const knownRegisters = new Set(Object.keys(loadRegBits()));
+
+  const ldaRows: DisasmSearchRow[] = [];
+  const staRows: DisasmSearchRow[] = [];
+
+  for (const range of listRanges(handle)) {
+    if (range.dataType !== "code") continue;
+    const bytes = sliceImageRange(image, range.start, range.endInclusive);
+    if (bytes === null) continue; // this image does not cover the range -- never fabricate bytes for it
+    const instructions = decode(bytes, range.start, { end: range.endInclusive });
+    for (const instr of instructions) {
+      if (ldaRows.length < maxResults && instr.mode === "immediate" && instr.operand && IMMEDIATE_LOAD_MNEMONICS.has(instr.mnemonic)) {
+        ldaRows.push(toSearchRow(instr, `#$${instr.operand.value.toString(16).padStart(2, "0")}`));
+      } else if (staRows.length < maxResults && instr.mode === "absolute" && instr.operand && ABSOLUTE_STORE_MNEMONICS.has(instr.mnemonic)) {
+        const key = registerKeyFor(instr.operand.value);
+        if (knownRegisters.has(key)) {
+          staRows.push(toSearchRow(instr, `$${instr.operand.value.toString(16).padStart(4, "0")}`));
+        }
+      }
+    }
+  }
+
+  return { ldaRows, staRows };
+}
+
+/**
+ * THE REBUILT INSTALL (D-15): create-or-update each planned enum through the
+ * shipped `createProjectEnum()`/`updateProjectEnum()` write path -- the SAME
+ * functions `anno_create_project_enum`/`anno_update_project_enum` dispatch
+ * to, never a second install path -- and bind every occurrence through
+ * `applyEnumUsage()`, at the `lda` address (never the store address -- the
+ * measured binding fact in this module's header). `sanitizeVariantMap()`
+ * runs FIRST, before any I/O, so an illegal identifier provably never
+ * reaches the store (the same client-side-first property the deleted
+ * installer proved with a spy binary).
+ *
+ * CREATE-THEN-UPDATE, never a delete: `createProjectEnum()` no-ops on a
+ * byte-identical repeat and THROWS `AnnoLabelError` when the same name
+ * already holds DIFFERENT content -- caught here and retried through
+ * `updateProjectEnum()`, which replaces the variant map wholesale. This is
+ * `EnumInstallAction`'s own documented re-runnability precedent (see its
+ * comment above); an installer that could only ever report "created" would
+ * have quietly dropped ANNO-13's re-runnability requirement.
+ */
+export function installPlannedEnums(handle: AnnoStoreHandle, planned: readonly PlannedEnum[]): EnumInstallSummary[] {
+  const summaries: EnumInstallSummary[] = [];
+  for (const plan of planned) {
+    const sanitized = sanitizeVariantMap(plan.regKey, plan.variants);
+    const description = `Generated by anno-enum-gen.ts (D-15) from ${plan.occurrences.length} observed write(s) to ${plan.regKey}.`;
+
+    let action: EnumInstallAction;
+    try {
+      createProjectEnum(handle, { name: plan.enumName, variants: sanitized, description });
+      action = "created";
+    } catch (err) {
+      if (!(err instanceof AnnoLabelError)) throw err;
+      updateProjectEnum(handle, { name: plan.enumName, variants: sanitized, description });
+      action = "updated";
+    }
+
+    let usagesApplied = 0;
+    for (const occ of plan.occurrences) {
+      applyEnumUsage(handle, { address: occ.ldaAddr, name: plan.enumName });
+      usagesApplied += 1;
+    }
+
+    summaries.push({ regKey: plan.regKey, enumName: plan.enumName, variantCount: plan.variants.size, action, usagesApplied });
+  }
+  return summaries;
+}
+
+export interface GenerateEnumsFromStoreOptions {
+  maxResults?: number;
+}
+
+/**
+ * THE REBUILT PASS (D-15): fetch -> `pairSearchRows()` -> `planEnumsForPairing()`
+ * -> `installPlannedEnums()` (which itself calls `sanitizeVariantMap()`) ->
+ * `buildEnumGenerationReport()`. The three middle heuristics are called,
+ * never edited, exactly per this module's own header specification.
+ */
+export function generateEnumsFromStore(
+  handle: AnnoStoreHandle,
+  image: EnumSourceImage,
+  opts: GenerateEnumsFromStoreOptions = {},
+): EnumGenerationReport {
+  const maxResults = opts.maxResults ?? DEFAULT_MAX_RESULTS;
+  const { ldaRows, staRows } = fetchRegisterSearchRows(handle, image, { maxResults });
+  const pairing = pairSearchRows(ldaRows, staRows, maxResults);
+  const planned = planEnumsForPairing(pairing);
+  const installed = installPlannedEnums(handle, planned);
+  return buildEnumGenerationReport(pairing, installed, maxResults);
+}
+