@defold-typescript/types 0.39.0 → 0.41.0

package/scripts/regen.ts

@@ -1,20 +1,34 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
-import { type ApiModule, parseDefoldApiDoc } from "../src/api-doc";
 import {
-  defaultMapType,
+  type ApiModule,
+  parseDefoldApiDoc,
+  type SkipOverloadRule,
+  withholdOverloads,
+} from "../src/api-doc";
+import {
+  declaredTypePaths,
   emitDeclarations,
   emitSymbolSignatures,
+  routeTypeDeclarations,
   type SymbolSignature,
 } from "../src/emit-dts";
 import {
   applyMessageDeprecations,
+  applyMessageFieldCorrections,
   type EmitBuiltinMessagesOptions,
   emitBuiltinMessages,
   parseMessagesDoc,
 } from "../src/emit-messages";
 import type { TranslationStore } from "../src/example-store";
+import {
+  type FieldCorrectionGap,
+  type FieldCorrectionTables,
+  fieldCorrectionGaps,
+  formatFieldCorrectionGaps,
+} from "../src/field-correction-coverage";
+import type { IndexBaseSource } from "../src/index-slot-classifications";
 import { wrapAsAmbientGlobal, wrapAsModule } from "../src/publish-dts";
 import type { UrlParameterTable } from "../src/url-parameters";
 import {
@@ -26,6 +40,8 @@ import {
   resolveRefDoc,
 } from "./doc-source";
 import { loadTranslations } from "./example-store-io";
+import { synthesizeProseConstants } from "./prose-constants";
+import { restoreSharedHandleMethods } from "./shared-handle-methods";
 import { type readZip, SYNC_MANIFEST, type SyncManifestEntry } from "./sync-api-docs";
 
 export interface ApiTargetModule {
@@ -33,6 +49,7 @@ export interface ApiTargetModule {
   readonly fixture: string;
   readonly outFile: string;
   readonly skipFunctions?: readonly string[];
+  readonly skipOverloads?: readonly SkipOverloadRule[];
 }
 
 // An editor-VM document declared by a target. It carries two things a runtime
@@ -95,11 +112,19 @@ export function loadApiTargets(
   return targets;
 }
 
+function withSkipRules(entry: ModuleManifestEntry, module: ApiTargetModule): ModuleManifestEntry {
+  return {
+    ...entry,
+    ...(module.skipFunctions ? { skipFunctions: module.skipFunctions } : {}),
+    ...(module.skipOverloads ? { skipOverloads: module.skipOverloads } : {}),
+  };
+}
+
 export function loadTargetModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
 ): ModuleManifestEntry[] {
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const path = resolve(packageRoot, target.fixturesDir, module.fixture);
     let raw: string;
     try {
@@ -115,26 +140,34 @@ export function loadTargetModules(
       outFile: module.outFile,
       importsFrom: target.coreTypesImport,
     };
-    return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
+    return withSkipRules(entry, module);
   });
+  return restoreSharedHandleMethods(synthesizeProseConstants(modules));
 }
 
 export interface ModuleManifestEntry {
   readonly namespace: string;
   readonly doc: unknown;
   readonly outFile: string;
-  // Each item drops one member of any element kind — a FUNCTION or a VARIABLE —
-  // by an exact stripped local (`get`), or — when it ends in `.` — a segment
-  // prefix dropping everything beneath it (`ui.`). The field keeps its historic
-  // name; its reach is not limited to functions.
+  // Each item drops one member of any element kind — a FUNCTION, a VARIABLE, a
+  // CONSTANT, an ENUM member, a STRUCT or an aliasing TYPEDEF — by an exact
+  // stripped local (`get`), or — when it ends in `.` — a segment prefix dropping
+  // everything beneath it (`ui.`). An ENUM whose every member is dropped emits no
+  // alias either. The field keeps its historic name; its reach is not limited to
+  // functions.
   readonly skipFunctions?: readonly string[];
+  readonly skipOverloads?: readonly SkipOverloadRule[];
   readonly importsFrom?: string;
   readonly moduleId?: string;
   readonly sourceProvenance?: DocSourceProvenance;
-  // Overrides the shared token -> TS type mapping for this entry alone. Reserved
-  // for tokens no runtime namespace uses, so `DEFOLD_TYPE_MAP` keeps describing
-  // only the runtime surface.
-  readonly mapType?: (token: string) => string;
+  // Extra token -> TS type leaves for this entry alone, resolved ahead of the
+  // shared mapping and beside the module's declared types. Reserved for tokens no
+  // runtime namespace uses, so `DEFOLD_TYPE_MAP` keeps describing only the
+  // runtime surface.
+  readonly typeLeaves?: Readonly<Record<string, string>>;
+  // The classification map this entry's index notes read; absent means the
+  // engine map. A library or extension declaration names its page keys.
+  readonly indexBaseSource?: IndexBaseSource;
 }
 
 export interface ResolveTargetOptions {
@@ -168,7 +201,7 @@ export async function resolveTargetModules(
     ...(opts.fetchChannelInfo ? { fetchChannelInfo: opts.fetchChannelInfo } : {}),
   });
   const syncManifest = opts.syncManifest ?? SYNC_MANIFEST;
-  return target.modules.map((module) => {
+  const modules = target.modules.map((module) => {
     const sync = syncManifest.find((s) => s.namespace === module.namespace);
     if (!sync) {
       throw new Error(
@@ -182,8 +215,9 @@ export async function resolveTargetModules(
       importsFrom: target.coreTypesImport,
       sourceProvenance: provenance,
     };
-    return module.skipFunctions ? { ...entry, skipFunctions: module.skipFunctions } : entry;
+    return withSkipRules(entry, module);
   });
+  return synthesizeProseConstants(modules);
 }
 
 const API_TARGETS = loadApiTargets();
@@ -218,17 +252,18 @@ const EDITOR_TYPE_MAP: Readonly<Record<string, string>> = {
   // `string[`, this token means one thing everywhere it appears — a list of
   // values to render — so `unknown[]` is sound at all three of its slots.
   "any[": "unknown[]",
+  // 1.13.2 names the same handles with their namespace prefix, slot for slot.
+  "editor.command": 'Opaque<"command">',
+  "editor.component": 'Opaque<"component">',
+  "editor.transaction_step": 'Opaque<"transaction_step">',
+  "editor.message": 'Opaque<"message">',
 };
 
-function mapEditorType(token: string): string {
-  return EDITOR_TYPE_MAP[token] ?? defaultMapType(token);
-}
-
 // The named type maps an `editorModules` entry may select. A closed set, so an
 // unknown selector fails loudly instead of silently falling back to the runtime
 // token mapping and emitting `unknown` for every editor handle.
-const NAMED_TYPE_MAPS: Readonly<Record<string, (token: string) => string>> = {
-  editor: mapEditorType,
+const NAMED_TYPE_MAPS: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+  editor: EDITOR_TYPE_MAP,
 };
 
 // The subdirectory the namespace-shaped libraries the editor VM exposes
@@ -259,7 +294,20 @@ function oneLevelDeeper(importPath: string): string {
 // The `skipFunctions` rules a target declares in `api-targets.json` withhold
 // members for reasons the registry data alone cannot state. Rules are local
 // names — the `<namespace>.` prefix is stripped before matching — and they
-// withhold VARIABLEs as well as FUNCTIONs.
+// withhold any member: FUNCTIONs, VARIABLEs, CONSTANTs, ENUM members, STRUCTs
+// and aliasing TYPEDEFs alike. A TYPEDEF that names no aliased type keeps its
+// flat handle path and is never withheld.
+// An ENUM whose every member is withheld emits no alias.
+//
+// On a `b2d.body` entry they withhold what that release documents but neither
+// Box2D binding registers, so the call would raise: `get_user_data`,
+// `set_user_data` and `get_contact_list` from 1.13, `reset_mass_data` from
+// 1.12.4. The engine-binding diff reports a missing binding the moment one is
+// declared again.
+//
+// On the 1.13.2 `http` entry, `response` withholds the runtime response table:
+// the editor VM's `http.response` handle takes that name in the same global
+// namespace, and the `http.request` callback already types the table inline.
 //
 // On the `editor` entry, the editor VM's own `http`/`json`/`zip`/`zlib`/
 // `pprint`/`localization`/`tilemap.tiles` sit in that same upstream document
@@ -285,7 +333,9 @@ function oneLevelDeeper(importPath: string): string {
 // and `ZipPackOptions.method?: string` rejects that. Their brief is the literal
 // value, which looks like a string-literal type until you notice upstream's own
 // `zip.ON_CONFLICT.OVERWRITE` reads `"skip"`, so no type is derived from it.
-// The hand-authored declarations stay authoritative and these stay withheld.
+// Where upstream ships them as ENUM members (1.13.2) they carry a string type,
+// and the same rules still withhold them: the hand-authored declarations stay
+// authoritative and these stay withheld.
 export function loadTargetEditorModules(
   target: ApiTarget,
   packageRoot: string = PACKAGE_ROOT,
@@ -319,7 +369,7 @@ export function loadTargetEditorModules(
           ? oneLevelDeeper(target.coreTypesImport)
           : target.coreTypesImport),
       ...(module.skipFunctions ? { skipFunctions: module.skipFunctions } : {}),
-      ...(module.mapType ? { mapType: NAMED_TYPE_MAPS[module.mapType] } : {}),
+      ...(module.mapType ? { typeLeaves: NAMED_TYPE_MAPS[module.mapType] } : {}),
     };
     return entry;
   });
@@ -355,7 +405,10 @@ export function generateBuiltinMessagesDeclaration(
   entry: MessagesManifestEntry,
   opts: EmitBuiltinMessagesOptions = {},
 ): string {
-  return emitBuiltinMessages(applyMessageDeprecations(parseMessagesDoc(entry.doc)), opts);
+  return emitBuiltinMessages(
+    applyMessageFieldCorrections(applyMessageDeprecations(parseMessagesDoc(entry.doc))),
+    opts,
+  );
 }
 
 export interface GenerateResult {
@@ -397,6 +450,7 @@ export interface GenerateOptions {
   knownConstantFqns?: ReadonlySet<string>;
   translations?: TranslationStore;
   urlParameters?: UrlParameterTable;
+  registeredConstants?: ReadonlySet<string>;
 }
 
 interface PreparedGeneratedModule {
@@ -404,11 +458,13 @@ interface PreparedGeneratedModule {
   knownConstantFqns: ReadonlySet<string>;
   translations: TranslationStore;
   urlParameters: UrlParameterTable;
-  mapType: ((token: string) => string) | undefined;
+  registeredConstants: ReadonlySet<string> | undefined;
+  typeLeaves: Readonly<Record<string, string>> | undefined;
+  declaredTypes: ReadonlyMap<string, string> | undefined;
   dropped: string[];
 }
 
-// Parse a manifest entry, apply its `skipFunctions` filter, and resolve the
+// Parse a manifest entry, apply its `skipFunctions` and `skipOverloads` filters, and resolve the
 // shared constant-brand universe and translations. Both the `.d.ts` emit and
 // the authoritative-signature emit run off this identical prepared module, so a
 // dropped member never appears in either surface.
@@ -416,44 +472,251 @@ function prepareGeneratedModule(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): PreparedGeneratedModule {
-  const module = parseDefoldApiDoc(entry.doc);
+  const routed = routedModuleOf(entry);
+  const { module, dropped } = routed?.prepared ?? withheldApiModule(entry);
+  const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
+  const translations = options?.translations ?? loadTranslations();
+  const urlParameters = options?.urlParameters ?? committedUrlParameters();
+  return {
+    module,
+    knownConstantFqns,
+    translations,
+    urlParameters,
+    registeredConstants: options?.registeredConstants,
+    typeLeaves: entry.typeLeaves,
+    declaredTypes: routed?.declaredTypes,
+    dropped,
+  };
+}
+
+interface RoutedSurface {
+  readonly modules: ReadonlyMap<ModuleManifestEntry, { module: ApiModule; dropped: string[] }>;
+  readonly declaredTypes: ReadonlyMap<string, string>;
+}
+
+const routedSurfaces = new Map<string, RoutedSurface>();
+
+// A doc may declare a type another module owns (`b2d.joint.revolute_definition`
+// in the `b2d` doc) or name one another doc declares (`material.constant_info`
+// in `compute`), so each committed surface is routed as a whole: the runtime
+// modules and the editor modules of one target, never across targets. An entry
+// outside every committed manifest routes alone, as a single-module surface.
+function routedModuleOf(entry: ModuleManifestEntry):
+  | {
+      prepared: { module: ApiModule; dropped: string[] };
+      declaredTypes: ReadonlyMap<string, string>;
+    }
+  | undefined {
+  const located = committedSurfaceOf(entry);
+  if (located === undefined) return undefined;
+  let surface = routedSurfaces.get(located.key);
+  if (surface === undefined) {
+    const withheld = located.entries.map(withheldApiModule);
+    const routed = routeTypeDeclarations(withheld.map(({ module }) => module));
+    surface = {
+      modules: new Map(
+        located.entries.map((member, index) => [
+          member,
+          {
+            module: routed[index] as ApiModule,
+            dropped: (withheld[index] as { dropped: string[] }).dropped,
+          },
+        ]),
+      ),
+      declaredTypes: declaredTypePaths(routed),
+    };
+    routedSurfaces.set(located.key, surface);
+  }
+  const prepared = surface.modules.get(located.member);
+  return prepared === undefined ? undefined : { prepared, declaredTypes: surface.declaredTypes };
+}
+
+const committedDocText = new WeakMap<ModuleManifestEntry, string>();
+
+// The committed entry `entry` stands for: itself, or — for an entry a caller
+// re-loaded from the registry — the committed one with the same module, output,
+// import root, skip rules and document.
+function committedMemberOf(
+  entry: ModuleManifestEntry,
+  candidates: readonly ModuleManifestEntry[],
+): ModuleManifestEntry | undefined {
+  if (candidates.includes(entry)) return entry;
+  const shape = (member: ModuleManifestEntry) =>
+    JSON.stringify([
+      member.namespace,
+      member.outFile,
+      member.importsFrom,
+      member.moduleId,
+      member.skipFunctions,
+      member.skipOverloads,
+    ]);
+  const same = candidates.filter((candidate) => shape(candidate) === shape(entry));
+  if (same.length === 0) return undefined;
+  const text = JSON.stringify(entry.doc);
+  return same.find((candidate) => {
+    let committed = committedDocText.get(candidate);
+    if (committed === undefined) {
+      committed = JSON.stringify(candidate.doc);
+      committedDocText.set(candidate, committed);
+    }
+    return committed === text;
+  });
+}
+
+function committedSurfaceOf(
+  entry: ModuleManifestEntry,
+):
+  | { key: string; member: ModuleManifestEntry; entries: readonly ModuleManifestEntry[] }
+  | undefined {
+  const runtime = committedMemberOf(entry, MODULE_MANIFEST);
+  if (runtime !== undefined) return { key: "default", member: runtime, entries: MODULE_MANIFEST };
+  const editor = committedMemberOf(entry, DEFAULT_EDITOR_MODULES);
+  if (editor !== undefined) {
+    return { key: "default/editor", member: editor, entries: DEFAULT_EDITOR_MODULES };
+  }
+  const versioned = committedMemberOf(entry, VERSIONED_MODULE_MANIFEST) as
+    | VersionedModuleManifestEntry
+    | undefined;
+  if (versioned === undefined) return undefined;
+  const isEditor = versioned.editor === true;
+  return {
+    key: `${versioned.versionId}${isEditor ? "/editor" : ""}`,
+    member: versioned,
+    entries: VERSIONED_MODULE_MANIFEST.filter(
+      (member) => member.versionId === versioned.versionId && (member.editor === true) === isEditor,
+    ),
+  };
+}
+
+// The parsed module with the entry's `skipFunctions` and `skipOverloads` applied.
+function withheldApiModule(entry: ModuleManifestEntry): { module: ApiModule; dropped: string[] } {
+  let module = parseDefoldApiDoc(entry.doc);
   const prefix = `${module.namespace}.`;
   const dropped: string[] = [];
   const rules = entry.skipFunctions ?? [];
   const exact = new Set(rules.filter((rule) => !rule.endsWith(".")));
   const segments = rules.filter((rule) => rule.endsWith("."));
+  const localOf = (name: string): string =>
+    name.startsWith(prefix) ? name.slice(prefix.length) : name;
   const withheld = (name: string): boolean => {
-    const local = name.startsWith(prefix) ? name.slice(prefix.length) : name;
+    const local = localOf(name);
     if (!exact.has(local) && !segments.some((segment) => local.startsWith(segment))) return false;
     dropped.push(name);
     return true;
   };
+  // An exact rule a value and a type both answer to (`render_target`) names the
+  // value, the member every such rule was written to withhold; a segment rule
+  // still takes the whole subtree, types included.
+  const valueLocals = new Set(
+    [...module.functions, ...module.variables, ...module.constants].map((m) => localOf(m.name)),
+  );
+  const withheldType = (name: string): boolean => {
+    const local = localOf(name);
+    if (valueLocals.has(local) && !segments.some((segment) => local.startsWith(segment))) {
+      return false;
+    }
+    return withheld(name);
+  };
   module.functions = module.functions.filter((fn) => !withheld(fn.name));
   module.variables = module.variables.filter((v) => !withheld(v.name));
-  const knownConstantFqns = options?.knownConstantFqns ?? collectConstantFqns();
-  const translations = options?.translations ?? loadTranslations();
-  const urlParameters = options?.urlParameters ?? committedUrlParameters();
-  return {
-    module,
-    knownConstantFqns,
-    translations,
-    urlParameters,
-    mapType: entry.mapType,
-    dropped,
-  };
+  const withheldConstants = new Set<string>();
+  module.constants = module.constants.filter((c) => {
+    if (!withheld(c.name)) return true;
+    withheldConstants.add(c.name);
+    return false;
+  });
+  if (module.enums) {
+    module.enums = module.enums.filter(
+      (e) => e.members.length === 0 || !e.members.every((member) => withheldConstants.has(member)),
+    );
+  }
+  if (module.structs) module.structs = module.structs.filter((s) => !withheldType(s.name));
+  module.typedefs = module.typedefs.filter((t) => t.aliasOf === undefined || !withheldType(t.name));
+  module = withholdOverloads(module, entry.skipOverloads ?? []);
+  return { module, dropped };
+}
+
+// The field corrections one target's runtime entries leave inert: every entry is
+// parsed with its skip rules first, so a withheld overload's slot is not judged.
+export function targetFieldCorrectionGaps(
+  entries: readonly ModuleManifestEntry[],
+  tables?: FieldCorrectionTables,
+): FieldCorrectionGap[] {
+  return fieldCorrectionGaps(
+    entries.map((entry) => withheldApiModule(entry).module),
+    tables,
+  );
+}
+
+export interface FieldCorrectionTarget {
+  readonly id: string;
+  readonly entries: readonly ModuleManifestEntry[];
+}
+
+// The runtime surfaces committed generation writes: the default target's, then
+// each fixture-backed version's. ref-doc targets are never pre-baked, and an
+// editor document carries no field correction.
+export function committedFieldCorrectionTargets(
+  targets: readonly ApiTarget[] = API_TARGETS,
+  runtime: readonly ModuleManifestEntry[] = MODULE_MANIFEST,
+  versioned: readonly VersionedModuleManifestEntry[] = VERSIONED_MODULE_MANIFEST,
+): FieldCorrectionTarget[] {
+  const defaultTarget = targets.find((target) => target.default === true);
+  return [
+    ...(defaultTarget ? [{ id: defaultTarget.id, entries: runtime }] : []),
+    ...targets
+      .filter((target) => target.default !== true && (target.source ?? null) == null)
+      .map((target) => ({
+        id: target.id,
+        entries: versioned.filter(
+          (entry) => entry.versionId === target.id && entry.editor !== true,
+        ),
+      })),
+  ];
+}
+
+// Every committed target is judged before any rejection, so one failure names
+// all the stranded corrections at once. Returns how many targets it judged.
+export function assertCommittedFieldCorrectionCoverage(
+  targets: readonly FieldCorrectionTarget[] = committedFieldCorrectionTargets(),
+  tables?: FieldCorrectionTables,
+): number {
+  const failures = targets.flatMap(({ id, entries }) => {
+    const gaps = targetFieldCorrectionGaps(entries, tables);
+    return gaps.length === 0
+      ? []
+      : [
+          `target "${id}": field corrections no slot or member carries:\n${formatFieldCorrectionGaps(gaps)}`,
+        ];
+  });
+  if (failures.length > 0) {
+    throw new Error(failures.join("\n"));
+  }
+  return targets.length;
 }
 
 export function generateModuleDeclaration(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): GenerateResult {
-  const { module, knownConstantFqns, translations, urlParameters, mapType, dropped } =
-    prepareGeneratedModule(entry, options);
+  const {
+    module,
+    knownConstantFqns,
+    translations,
+    urlParameters,
+    registeredConstants,
+    typeLeaves,
+    declaredTypes,
+    dropped,
+  } = prepareGeneratedModule(entry, options);
   const emitted = emitDeclarations(module, {
     knownConstantFqns,
     translations,
     urlParameters,
-    ...(mapType ? { mapType } : {}),
+    ...(registeredConstants ? { registeredConstants } : {}),
+    ...(typeLeaves ? { typeLeaves } : {}),
+    ...(declaredTypes ? { declaredTypes } : {}),
+    ...(entry.indexBaseSource ? { indexBaseSource: entry.indexBaseSource } : {}),
   });
   const importsFrom = entry.importsFrom ?? "../src/core-types";
   const contents = entry.moduleId
@@ -470,14 +733,20 @@ export function generateModuleSignatures(
   entry: ModuleManifestEntry,
   options?: GenerateOptions,
 ): SymbolSignature[] {
-  const { module, knownConstantFqns, urlParameters, mapType } = prepareGeneratedModule(
-    entry,
-    options,
-  );
+  const {
+    module,
+    knownConstantFqns,
+    urlParameters,
+    registeredConstants,
+    typeLeaves,
+    declaredTypes,
+  } = prepareGeneratedModule(entry, options);
   return emitSymbolSignatures(module, {
     knownConstantFqns,
     urlParameters,
-    ...(mapType ? { mapType } : {}),
+    ...(registeredConstants ? { registeredConstants } : {}),
+    ...(typeLeaves ? { typeLeaves } : {}),
+    ...(declaredTypes ? { declaredTypes } : {}),
   });
 }
 
@@ -556,8 +825,10 @@ const UNIVERSAL_EXTRA_IMPORTS: readonly UniversalExtraImport[] = [
   { specifier: "../../src/window-event-guard" },
   { specifier: "../../src/scene-addresses" },
   { specifier: "../../src/go-overloads" },
+  { specifier: "../../src/component-properties" },
   { specifier: "../../src/render-overloads", restrictedTo: "render" },
   { specifier: "../../src/vmath-overloads" },
+  { specifier: "../../src/sys-overloads" },
 ];
 
 const SRC_IMPORT_PREFIX = "../../src/";
@@ -784,47 +1055,85 @@ export async function assertSrcAugmentationScoping(
   return files.length;
 }
 
-if (import.meta.main) {
+export interface RegenIo {
+  mkdir(path: string): void;
+  write(path: string, contents: string): void;
+  log(line: string): void;
+}
+
+export const nodeRegenIo: RegenIo = {
+  mkdir: (path) => mkdirSync(path, { recursive: true }),
+  write: (path, contents) => writeFileSync(path, contents),
+  log: (line) => console.log(line),
+};
+
+export async function regenerate(
+  options: { io?: RegenIo; fieldCorrectionTables?: FieldCorrectionTables } = {},
+): Promise<void> {
+  const io = options.io ?? nodeRegenIo;
   // Ordering contract: `regen-entrypoint.test.ts` reads this line's prefix to
   // prove the guard runs before the first write. The count comes from the guard's
   // own return value so the marker cannot be printed without a completed guard
   // run — do not simplify it back to `SRC_AUGMENTATION_MODULES.length`, which
   // would let the guard be deleted or reordered with the line still intact.
   const checked = await assertSrcAugmentationScoping();
-  console.log(`src augmentation scoping checked: ${checked} file(s)`);
+  io.log(`src augmentation scoping checked: ${checked} file(s)`);
+  // Ordering contract: `regen-entrypoint.test.ts` reads this line's prefix to
+  // prove the coverage gate runs before the first write. Print the count the gate
+  // returns — never `committedFieldCorrectionTargets().length` or any other count
+  // not taken from the gate, which would keep the line alive with the gate gone.
+  // The `regenerate` rejection test injects stranded tables and asserts that no
+  // directory or file is written, so the gate must receive `fieldCorrectionTables`
+  // and throw before the first `io.mkdir`.
+  const targets = assertCommittedFieldCorrectionCoverage(
+    committedFieldCorrectionTargets(),
+    options.fieldCorrectionTables,
+  );
+  io.log(`field correction coverage checked: ${targets} target(s)`);
 
+  // Imported here rather than at module scope: the vendored engine bindings are
+  // not published, and `resolve` loads this module from an installed package.
+  const { registeredConstantFqns } = await import("./engine-binding-extract");
   const generated = resolve(import.meta.dir, "..", "generated");
-  mkdirSync(resolve(generated, "editor-vm"), { recursive: true });
-  for (const entry of [
-    ...MODULE_MANIFEST,
-    ...EDITOR_MODULE_MANIFEST,
-    ...EDITOR_VM_MODULE_MANIFEST,
-  ]) {
+  io.mkdir(resolve(generated, "editor-vm"));
+  const defaultRegistered = registeredConstantFqns(DEFAULT_TARGET);
+  for (const entry of MODULE_MANIFEST) {
+    const { contents, dropped } = generateModuleDeclaration(entry, {
+      ...(defaultRegistered ? { registeredConstants: defaultRegistered } : {}),
+    });
+    if (dropped.length > 0) {
+      io.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+    }
+    const out = resolve(generated, entry.outFile);
+    io.write(out, contents);
+    io.log(`wrote ${out}`);
+  }
+  for (const entry of [...EDITOR_MODULE_MANIFEST, ...EDITOR_VM_MODULE_MANIFEST]) {
     const { contents, dropped } = generateModuleDeclaration(entry);
     if (dropped.length > 0) {
-      console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+      io.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
     }
     const out = resolve(generated, entry.outFile);
-    writeFileSync(out, contents);
-    console.log(`wrote ${out}`);
+    io.write(out, contents);
+    io.log(`wrote ${out}`);
   }
   const messagesOut = resolve(generated, MESSAGES_MANIFEST.outFile);
-  writeFileSync(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
-  console.log(`wrote ${messagesOut}`);
+  io.write(messagesOut, generateBuiltinMessagesDeclaration(MESSAGES_MANIFEST));
+  io.log(`wrote ${messagesOut}`);
 
   // Imported here rather than at module scope: its fixtures are not published,
   // and `resolve` loads this module from an installed package.
   const { EXTENSION_GOLDENS_DIR, EXTENSION_GOLDEN_MANIFEST } = await import("./extension-goldens");
   const goldens = resolve(PACKAGE_ROOT, EXTENSION_GOLDENS_DIR);
-  mkdirSync(goldens, { recursive: true });
+  io.mkdir(goldens);
   for (const entry of EXTENSION_GOLDEN_MANIFEST) {
     const { contents, dropped } = generateModuleDeclaration(entry);
     if (dropped.length > 0) {
-      console.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
+      io.log(`note: dropped skipped member(s) from ${entry.namespace}: ${dropped.join(", ")}`);
     }
     const out = resolve(goldens, entry.outFile);
-    writeFileSync(out, contents);
-    console.log(`wrote ${out}`);
+    io.write(out, contents);
+    io.log(`wrote ${out}`);
   }
 
   // The target's own `generatedDir` is where a version lands, so a declaring
@@ -839,21 +1148,26 @@ if (import.meta.main) {
     return resolve(PACKAGE_ROOT, target.generatedDir);
   };
   for (const entry of VERSIONED_MODULE_MANIFEST) {
-    const { contents, dropped } = generateModuleDeclaration(entry);
+    const target = versionedTargets.find((t) => t.id === entry.versionId);
+    const registeredConstants = target ? registeredConstantFqns(target) : undefined;
+    const { contents, dropped } = generateModuleDeclaration(
+      entry,
+      registeredConstants ? { registeredConstants } : undefined,
+    );
     if (dropped.length > 0) {
-      console.log(
+      io.log(
         `note: dropped skipped member(s) from ${entry.versionId}/${entry.namespace}: ${dropped.join(", ")}`,
       );
     }
     const out = resolve(versionDirOf(entry.versionId), entry.outFile);
-    mkdirSync(dirname(out), { recursive: true });
-    writeFileSync(out, contents);
-    console.log(`wrote ${out}`);
+    io.mkdir(dirname(out));
+    io.write(out, contents);
+    io.log(`wrote ${out}`);
   }
   for (const target of versionedTargets) {
     const indexOut = resolve(versionDirOf(target.id), "index.d.ts");
-    mkdirSync(dirname(indexOut), { recursive: true });
-    writeFileSync(
+    io.mkdir(dirname(indexOut));
+    io.write(
       indexOut,
       generateVersionIndex(
         target.id,
@@ -861,24 +1175,28 @@ if (import.meta.main) {
         versionSrcAugmentationImports(target),
       ),
     );
-    console.log(`wrote ${indexOut}`);
+    io.log(`wrote ${indexOut}`);
 
     const editorKinds = targetKindManifest(target).filter((entry) => entry.only !== undefined);
     if (editorKinds.length === 0) continue;
     const versionKindsDir = resolve(versionDirOf(target.id), "kinds");
-    mkdirSync(versionKindsDir, { recursive: true });
+    io.mkdir(versionKindsDir);
     for (const entry of editorKinds) {
       const out = resolve(versionKindsDir, `${entry.kind}.d.ts`);
-      writeFileSync(out, generateKindIndex(entry.kind, target));
-      console.log(`wrote ${out}`);
+      io.write(out, generateKindIndex(entry.kind, target));
+      io.log(`wrote ${out}`);
     }
   }
 
   const kindsDir = resolve(generated, "kinds");
-  mkdirSync(kindsDir, { recursive: true });
+  io.mkdir(kindsDir);
   for (const entry of KIND_MODULE_MANIFEST) {
     const out = resolve(kindsDir, `${entry.kind}.d.ts`);
-    writeFileSync(out, generateKindIndex(entry.kind));
-    console.log(`wrote ${out}`);
+    io.write(out, generateKindIndex(entry.kind));
+    io.log(`wrote ${out}`);
   }
 }
+
+if (import.meta.main) {
+  await regenerate();
+}