@defold-typescript/types 0.40.0 → 0.41.0

package/scripts/shared-handle-methods.ts

@@ -0,0 +1,53 @@
+import type { ModuleManifestEntry } from "./regen";
+
+// A method the engine shares across several handle classes where a release's
+// ref-doc documents it on only some of them. The handles it omits are restored
+// from the documented one, so a doc omission never drops a method the engine
+// still binds. Applies only where the source handle documents it.
+export interface SharedHandleMethod {
+  readonly namespace: string;
+  readonly method: string;
+  readonly source: string;
+  readonly handles: readonly string[];
+  readonly evidence: string;
+}
+
+const TCP_ANY =
+  'LuaSocket tcp.c binds it in the one method table every tcp class shares, and checks its argument with auxiliar_checkgroup(L, "tcp{any}", 1)';
+
+export const SHARED_HANDLE_METHODS: readonly SharedHandleMethod[] = (
+  ["getstats", "setstats"] as const
+).map((method) => ({
+  namespace: "socket",
+  method,
+  source: "client",
+  handles: ["master", "server"],
+  evidence: TCP_ANY,
+}));
+
+interface DocElement {
+  readonly name: string;
+}
+
+export function restoreSharedHandleMethods(
+  modules: readonly ModuleManifestEntry[],
+): ModuleManifestEntry[] {
+  return modules.map((entry) => {
+    const shared = SHARED_HANDLE_METHODS.filter((row) => row.namespace === entry.namespace);
+    if (shared.length === 0) return entry;
+    const doc = entry.doc as { elements: DocElement[] };
+    const declared = new Set(doc.elements.map((element) => element.name));
+    const restored: DocElement[] = [];
+    for (const { method, source, handles } of shared) {
+      const documented = doc.elements.find((element) => element.name === `${source}:${method}`);
+      if (documented === undefined) continue;
+      for (const handle of handles) {
+        const name = `${handle}:${method}`;
+        if (!declared.has(name)) restored.push({ ...documented, name });
+      }
+    }
+    return restored.length === 0
+      ? entry
+      : { ...entry, doc: { ...doc, elements: [...doc.elements, ...restored] } };
+  });
+}

package/scripts/signature-store-fs.ts

@@ -25,6 +25,7 @@ export const VMATH_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures"
 export const GO_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "go.json");
 export const MSG_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "msg.json");
 export const RENDER_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "render.json");
+export const SYS_SIGNATURES_PATH = resolve(import.meta.dir, "..", "signatures", "sys.json");
 
 export function loadSignatureFile(path: string): SignatureStore {
   let raw: string;

package/scripts/sync-api-docs.ts

@@ -11,7 +11,7 @@ import { MODULE_MANIFEST } from "./regen";
 // model because the per-package `rootDir` boundary forbids a types-package
 // module importing outside its own tree; `scripts/release-model.test.ts`
 // correspondence-guards these against the model so drift fails CI.
-export const DEFOLD_VERSION = "1.13.1";
+export const DEFOLD_VERSION = "1.13.2";
 export const refDocUrl = (version = DEFOLD_VERSION): string =>
   `https://github.com/defold/defold/releases/download/${version}/ref-doc.zip`;
 
@@ -52,13 +52,24 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
     "doc/scripts-box2d-v3-script_box2d_world_v3.cpp_doc.json",
   ]),
   entry("buffer", "doc/scripts-script_buffer.cpp_doc.json"),
+  entry("bullet3d", "doc/scripts-bullet3d-script_bullet3d.cpp_doc.json"),
+  entry(
+    "bullet3d.collision_object",
+    "doc/scripts-bullet3d-script_bullet3d_collision_object.cpp_doc.json",
+  ),
+  entry("bullet3d.constraint", "doc/scripts-bullet3d-script_bullet3d_constraint.cpp_doc.json"),
+  entry("bullet3d.rigid_body", "doc/scripts-bullet3d-script_bullet3d_rigid_body.cpp_doc.json"),
+  entry("bullet3d.shape", "doc/scripts-bullet3d-script_bullet3d_shape.cpp_doc.json"),
+  entry("bullet3d.world", "doc/scripts-bullet3d-script_bullet3d_world.cpp_doc.json"),
   // Camera and component namespaces merge their DDF messages/properties into
   // the callable script API so release snapshots retain every declared symbol.
   entry("camera", "doc/gamesys-camera_ddf.proto_doc.json", undefined, [
     "doc/render-render_script_camera.cpp_doc.json",
   ]),
   entry("collectionfactory", "doc/scripts-script_collection_factory.cpp_doc.json"),
-  entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json"),
+  entry("collectionproxy", "doc/scripts-script_collectionproxy.cpp_doc.json", undefined, [
+    "doc/gamesys-collectionproxy_ddf.proto_doc.json",
+  ]),
   entry("compute", "doc/scripts-script_compute.cpp_doc.json"),
   entry("crash", "doc/script_crash.cpp_doc.json"),
   entry("factory", "doc/scripts-script_factory.cpp_doc.json"),
@@ -115,11 +126,11 @@ export const SYNC_MANIFEST: readonly SyncManifestEntry[] = [
 export const UNMAPPED: ReadonlyMap<string, string> = new Map();
 
 // A Lua script namespace is a lowercase, dot-separated identifier (`sys`,
-// `b2d.body`). The native C/C++ SDK docs (`dmGraphics`, …), the C# bindings
+// `b2d.body`, `bullet3d.rigid_body`). The native C/C++ SDK docs (`dmGraphics`, …), the C# bindings
 // (`cs-*`), and the struct-only docs (empty `info.namespace`) fail this shape,
 // so the upstream-coverage guard skips them structurally rather than listing
 // each by hand — that keeps the guard self-maintaining as the SDK grows.
-const LUA_NAMESPACE = /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/;
+const LUA_NAMESPACE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
 
 // Lowercase-identifier namespaces that pass LUA_NAMESPACE but are intentionally
 // not wired through SYNC_MANIFEST, each with a sourced reason (mirrors the
@@ -205,7 +216,7 @@ function editorVm(namespace: string): SyncManifestEntry {
 function entry(
   namespace: string,
   zipEntry: string,
-  fixture: string = `fixtures/defold-1.13.1/${namespace.replace(/\./g, "_")}_doc.json`,
+  fixture: string = `fixtures/defold-1.13.2/${namespace.replace(/\./g, "_")}_doc.json`,
   mergeEntries?: readonly string[],
 ): SyncManifestEntry {
   return { namespace, zipEntry, fixture, ...(mergeEntries ? { mergeEntries } : {}) };

package/src/api-doc.ts

@@ -1,3 +1,5 @@
+import { correctedDoc, docCorrectionKey } from "./doc-corrections";
+
 export interface ApiModule {
   namespace: string;
   brief: string;
@@ -7,6 +9,39 @@ export interface ApiModule {
   constants: ApiConstant[];
   properties: ApiProperty[];
   typedefs: ApiTypedef[];
+  /**
+   * Each ref-doc `ENUM`, whose members are also lowered into `constants`. Absent
+   * on a hand-built module, which reads the same as an empty list.
+   */
+  enums?: ApiEnum[];
+  /** Each ref-doc `STRUCT`. Absent on a hand-built module, read as an empty list. */
+  structs?: ApiStruct[];
+}
+
+/** A ref-doc `STRUCT`: a named table shape. */
+export interface ApiStruct {
+  name: string;
+  brief: string;
+  description: string;
+  members: ApiStructMember[];
+}
+
+/** One `STRUCT` member; upstream marks an optional one with a `name?` suffix. */
+export interface ApiStructMember {
+  name: string;
+  doc: string;
+  /** One LuaLS type expression. */
+  type: string;
+  isOptional: boolean;
+}
+
+/** A ref-doc `ENUM`: a named set of constants, each lowered into `constants`. */
+export interface ApiEnum {
+  name: string;
+  brief: string;
+  description: string;
+  /** The member FQNs, in documentation order. */
+  members: string[];
 }
 
 export interface ApiProperty {
@@ -24,6 +59,11 @@ export interface ApiTypedef {
   types?: string[];
   /** The type text of each parent an interface-backed typedef extends. */
   extends?: string[];
+  /**
+   * The type an engine ref-doc `TYPEDEF` aliases (`parameters[0].types`): a
+   * handle's `userdata`/`number`, or the arms of a union, literal or record alias.
+   */
+  aliasOf?: string[];
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -32,6 +72,16 @@ export interface ApiConstant {
   name: string;
   brief: string;
   description: string;
+  /**
+   * Present when the constant is a member of an `ENUM` whose value type is
+   * `string` (`parameters[0].types`); absence means a number, as every
+   * pre-`ENUM` constant is.
+   */
+  valueType?: "string";
+  /** Present when an `ENUM` member is typed `<ENUM>|nil`: some platforms leave it unset. */
+  nilable?: true;
+  /** The documented constant a back-filled one shares its value, and so its type, with. */
+  aliasOf?: string;
   /** See {@link ApiFunction.global}. */
   global?: true;
 }
@@ -122,6 +172,27 @@ function docSourceKey(element: Record<string, unknown>): { docSource?: "upstream
   return element.docSource === "upstream" ? { docSource: "upstream" } : {};
 }
 
+// A function the ref-doc names differently from the name its engine binding
+// registers, so the documented call raises "attempt to call a nil value". Keyed
+// by the ref-doc FQN; `name` is the registered FQN and `evidence` the
+// registration. The parse renames the element, so the declaration, the signature
+// store, the example translations and every audit read the bound name. An entry
+// is deleted once no retained target documents the old name.
+export interface FunctionNameCorrection {
+  readonly name: string;
+  readonly evidence: string;
+}
+
+export const FUNCTION_NAME_CORRECTIONS: ReadonlyMap<string, FunctionNameCorrection> = new Map([
+  [
+    "sys.set_render_enable",
+    {
+      name: "sys.set_render_enabled",
+      evidence: 'script_engine.cpp registers {"set_render_enabled", EngineSys_SetRenderEnabled}',
+    },
+  ],
+]);
+
 export function parseDefoldApiDoc(input: unknown): ApiModule {
   if (!isRecord(input)) {
     throw new Error(`parseDefoldApiDoc: expected object, got ${describeKind(input)}`);
@@ -145,24 +216,99 @@ export function parseDefoldApiDoc(input: unknown): ApiModule {
   const constants: ApiConstant[] = [];
   const properties: ApiProperty[] = [];
   const typedefs: ApiTypedef[] = [];
+  const enums: ApiEnum[] = [];
+  const structs: ApiStruct[] = [];
 
   for (const element of elements) {
     if (!isRecord(element)) continue;
     const type = element.type;
     if (type === "FUNCTION") {
-      functions.push(parseFunction(element));
+      const fn = withDocCorrections(parseFunction(element));
+      const corrected = FUNCTION_NAME_CORRECTIONS.get(fn.name);
+      functions.push(corrected === undefined ? fn : { ...fn, name: corrected.name });
     } else if (type === "VARIABLE") {
       variables.push(parseVariable(element));
     } else if (type === "CONSTANT") {
       constants.push(parseConstant(element));
     } else if (type === "PROPERTY") {
-      properties.push(parseProperty(element));
+      const property = parseProperty(element);
+      const doc = correctedDoc(
+        docCorrectionKey(namespace, "property", property.name),
+        property.description,
+      );
+      properties.push(doc === property.description ? property : { ...property, description: doc });
     } else if (type === "TYPEDEF") {
       typedefs.push(parseTypedef(element));
+    } else if (type === "ENUM") {
+      const members = parseEnumMembers(element);
+      constants.push(...members);
+      enums.push({
+        name: stringOr(element.name, ""),
+        brief: stringOr(element.brief, ""),
+        description: stringOr(element.description, ""),
+        members: members.map((m) => m.name),
+      });
+    } else if (type === "STRUCT") {
+      structs.push(parseStruct(element));
+    }
+  }
+
+  return {
+    namespace,
+    brief,
+    description,
+    functions,
+    variables,
+    constants,
+    properties,
+    typedefs,
+    enums,
+    structs,
+  };
+}
+
+// Withholds one overload of a documented function — the one whose `param` has
+// exactly the upstream type `type` — while its same-named siblings still emit.
+// `name` is the local name, like a `skipFunctions` rule.
+export interface SkipOverloadRule {
+  readonly name: string;
+  readonly param: string;
+  readonly type: string;
+}
+
+export function withholdOverloads(
+  module: ApiModule,
+  rules: readonly SkipOverloadRule[],
+): ApiModule {
+  let functions = module.functions;
+  for (const rule of rules) {
+    const fqn = `${module.namespace}.${rule.name}`;
+    const kept = functions.filter(
+      (fn) =>
+        fn.name !== fqn ||
+        !fn.parameters.some(
+          (p) => p.name === rule.param && p.types.length === 1 && p.types[0] === rule.type,
+        ),
+    );
+    if (kept.length === functions.length) {
+      throw new Error(`skipOverloads: ${fqn} has no overload whose ${rule.param} is ${rule.type}`);
     }
+    functions = kept;
   }
+  return functions === module.functions ? module : { ...module, functions };
+}
 
-  return { namespace, brief, description, functions, variables, constants, properties, typedefs };
+// Keyed by the ref-doc FQN, before any `FUNCTION_NAME_CORRECTIONS` rename.
+function withDocCorrections(fn: ApiFunction): ApiFunction {
+  const correct = (slot: "param" | "return") => (p: ApiParameter) => {
+    const doc = correctedDoc(docCorrectionKey(fn.name, slot, p.name), p.doc);
+    return doc === p.doc ? p : { ...p, doc };
+  };
+  return {
+    ...fn,
+    parameters: fn.parameters.map(correct("param")),
+    returnValues: fn.returnValues.map(correct("return")),
+  };
 }
 
 function parseTypedef(element: Record<string, unknown>): ApiTypedef {
@@ -170,16 +316,41 @@ function parseTypedef(element: Record<string, unknown>): ApiTypedef {
   const properties = parseVariableList(element.properties);
   const types = parseStringArray(element.types);
   const parents = parseStringArray(element.extends);
+  const [aliased] = parseParameterList(element.parameters);
+  const aliasOf = aliased?.types ?? [];
   return {
     name: stringOr(element.name, ""),
     ...(functions.length > 0 ? { functions } : {}),
     ...(properties.length > 0 ? { properties } : {}),
     ...(types.length > 0 ? { types } : {}),
     ...(parents.length > 0 ? { extends: parents } : {}),
+    ...(aliasOf.length > 0 ? { aliasOf } : {}),
     ...globalKey(element),
   };
 }
 
+function parseStruct(element: Record<string, unknown>): ApiStruct {
+  const raw = Array.isArray(element.members) ? element.members : [];
+  const members: ApiStructMember[] = [];
+  for (const member of raw) {
+    if (!isRecord(member)) continue;
+    const name = stringOr(member.name, "");
+    const isOptional = name.endsWith("?");
+    members.push({
+      name: isOptional ? name.slice(0, -1) : name,
+      doc: stringOr(member.doc, ""),
+      type: stringOr(member.type, ""),
+      isOptional,
+    });
+  }
+  return {
+    name: stringOr(element.name, ""),
+    brief: stringOr(element.brief, ""),
+    description: stringOr(element.description, ""),
+    members,
+  };
+}
+
 function parseProperty(element: Record<string, unknown>): ApiProperty {
   const brief = stringOr(element.brief, "");
   const span = /<span class="type">([^<]+)<\/span>/.exec(brief);
@@ -207,6 +378,33 @@ function parseConstant(element: Record<string, unknown>): ApiConstant {
   };
 }
 
+// A member carries one `doc` string where a constant carried `brief` and
+// `description`; both take it.
+function parseEnumMembers(element: Record<string, unknown>): ApiConstant[] {
+  // A member named bare (1.13.2's bullet3d enums) is registered on the enum's
+  // own namespace, so it takes that prefix.
+  const enumName = stringOr(element.name, "");
+  const owner = enumName.includes(".") ? enumName.slice(0, enumName.lastIndexOf(".")) : "";
+  const qualify = (name: string): string =>
+    name.includes(".") || owner === "" ? name : `${owner}.${name}`;
+  const [value] = parseParameterList(element.parameters);
+  const valueType = value?.types.length === 1 && value.types[0] === "string" ? "string" : null;
+  const raw = Array.isArray(element.members) ? element.members : [];
+  const out: ApiConstant[] = [];
+  for (const member of raw) {
+    if (!isRecord(member)) continue;
+    const doc = stringOr(member.doc, "");
+    out.push({
+      name: qualify(stringOr(member.name, "")),
+      brief: doc,
+      description: doc,
+      ...(valueType === null ? {} : { valueType }),
+      ...(stringOr(member.type, "").endsWith("|nil") ? { nilable: true } : {}),
+    });
+  }
+  return out;
+}
+
 function parseFunction(element: Record<string, unknown>): ApiFunction {
   return {
     name: stringOr(element.name, ""),

package/src/api-identity.ts

@@ -0,0 +1,252 @@
+import type { ApiFunction, ApiModule, ApiParameter } from "./api-doc";
+import { DEFOLD_TYPE_MAP } from "./core-types";
+import { pinMatches } from "./correction-pins";
+import { splitTopLevel } from "./luals-type-expr";
+
+/**
+ * A type correction as identity applies it: where the slot still declares one of
+ * `pins`, its values are the declared ones less `removes` plus `adds`, or
+ * `replaces` outright. Every list is written in ref-doc or TypeScript spelling;
+ * both canonicalize to the same values.
+ */
+export interface IdentityCorrection {
+  readonly pins: readonly (readonly string[])[];
+  readonly adds?: readonly string[];
+  readonly removes?: readonly string[];
+  readonly replaces?: readonly string[];
+  /** A return correction's slot name, when it rewrites one of several returns. */
+  readonly slot?: string;
+}
+
+/**
+ * The corrections this repo records from verified engine behavior. Identity
+ * follows them rather than each release's markup, so a release whose ref-doc
+ * starts stating what a correction already did is not a change.
+ */
+export interface IdentityCorrections {
+  /** `<element>:param:<slot>` keys a correction makes optional. */
+  readonly optionalSlots: readonly string[];
+  /** `<element>:param:<slot>` keys a correction keeps required. */
+  readonly requiredSlots: readonly string[];
+  /** Keyed `<element>:param:<slot>`. */
+  readonly parameterCorrections: Readonly<Record<string, IdentityCorrection>>;
+  /** Keyed by element. */
+  readonly returnCorrections: Readonly<Record<string, IdentityCorrection>>;
+  /** Constant-family aliases a correction may name (`window.DimModeStateSettable`), with members. */
+  readonly constantFamilies: Readonly<Record<string, readonly string[]>>;
+}
+
+/**
+ * The names a ref-doc type token may refer to, gathered across every committed
+ * target so each release's spelling resolves the same way, plus the corrections.
+ * A name keeps its kind across releases: a 1.13.2 `STRUCT` is a table wherever
+ * it appears.
+ */
+export interface IdentityVocabulary extends Omit<IdentityCorrections, "constantFamilies"> {
+  /** `STRUCT` names: a table at runtime. */
+  readonly tables: readonly string[];
+  /** `ENUM` names and constant families, with the runtime type of their members. */
+  readonly enums: Readonly<Record<string, "number" | "string">>;
+  /** Constants whose value is a string; every other constant is a number. */
+  readonly stringConstants: readonly string[];
+  /** Non-handle `TYPEDEF` names and the tokens they alias. */
+  readonly aliases: Readonly<Record<string, readonly string[]>>;
+}
+
+export const NO_IDENTITY_CORRECTIONS: IdentityCorrections = {
+  optionalSlots: [],
+  requiredSlots: [],
+  parameterCorrections: {},
+  returnCorrections: {},
+  constantFamilies: {},
+};
+
+const sortedRecord = <T>(entries: Iterable<[string, T]>): Record<string, T> =>
+  Object.fromEntries([...entries].sort(([a], [b]) => a.localeCompare(b)));
+
+export function buildIdentityVocabulary(
+  modules: readonly ApiModule[],
+  corrections: IdentityCorrections = NO_IDENTITY_CORRECTIONS,
+): IdentityVocabulary {
+  const tables = new Set<string>();
+  const stringConstants = new Set<string>();
+  const aliases = new Map<string, readonly string[]>();
+  const enumMembers = new Map<string, readonly string[]>(
+    Object.entries(corrections.constantFamilies),
+  );
+  for (const module of modules) {
+    for (const struct of module.structs ?? []) tables.add(struct.name);
+    for (const constant of module.constants) {
+      if (constant.valueType === "string") stringConstants.add(constant.name);
+    }
+    for (const enumeration of module.enums ?? []) {
+      enumMembers.set(enumeration.name, enumeration.members);
+    }
+    for (const typedef of module.typedefs) {
+      const aliasOf = typedef.aliasOf;
+      if (aliasOf === undefined || (aliasOf.length === 1 && aliasOf[0] === "userdata")) continue;
+      aliases.set(typedef.name, aliasOf);
+    }
+  }
+  const enums = [...enumMembers].map(([name, members]): [string, "number" | "string"] => [
+    name,
+    members.length > 0 && members.every((member) => stringConstants.has(member))
+      ? "string"
+      : "number",
+  ]);
+  return {
+    tables: [...tables].sort(),
+    enums: sortedRecord(enums),
+    stringConstants: [...stringConstants].sort(),
+    aliases: sortedRecord(aliases),
+    optionalSlots: [...corrections.optionalSlots].sort(),
+    requiredSlots: [...corrections.requiredSlots].sort(),
+    parameterCorrections: sortedRecord(Object.entries(corrections.parameterCorrections)),
+    returnCorrections: sortedRecord(Object.entries(corrections.returnCorrections)),
+  };
+}
+
+// Tokens a later release renamed without changing what they denote.
+const RENAMED_TOKENS: Readonly<Record<string, string>> = {
+  // 1.13.2 names the lifecycle callbacks' `self` after what it is.
+  script_instance: "userdata",
+};
+
+const CONSTANT_FQN = /^[a-z_][\w.]*\.[A-Z][A-Z0-9_]*$/;
+const NUMERIC_LITERAL = /^-?\d+(\.\d+)?$/;
+const STRING_LITERAL = /^(".*"|'.*')$/;
+// The TypeScript table types a correction writes.
+const TS_TABLE = /^(Record|LuaMap|ReadonlyLuaMap|LuaTable)\b/;
+
+function canonicalLeaves(
+  token: string,
+  vocabulary: IdentityVocabulary,
+  expanding: ReadonlySet<string>,
+): string[] {
+  const trimmed = token.trim();
+  const arms = splitTopLevel(trimmed, "|");
+  if (arms.length > 1) return arms.flatMap((arm) => canonicalLeaves(arm, vocabulary, expanding));
+  if (trimmed.endsWith("?")) {
+    return [...canonicalLeaves(trimmed.slice(0, -1), vocabulary, expanding), "nil"];
+  }
+  if (/^(fun|function)\b/.test(trimmed) || trimmed.includes("=>")) return ["function"];
+  if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
+    return canonicalLeaves(trimmed.slice(1, -1), vocabulary, expanding);
+  }
+  if (trimmed.startsWith("typeof ")) {
+    return canonicalLeaves(trimmed.slice("typeof ".length), vocabulary, expanding);
+  }
+  if (trimmed === "nil" || trimmed === "undefined") return ["nil"];
+  // Every table shape — a bare or typed `table`, a list, an inline record, a
+  // struct, a built-in message payload — is one Lua table at runtime; its
+  // documented fields are not part of what identifies the call.
+  if (
+    trimmed === "table" ||
+    trimmed.startsWith("table<") ||
+    trimmed.startsWith("{") ||
+    trimmed.endsWith("[]") ||
+    trimmed.startsWith("message.") ||
+    TS_TABLE.test(trimmed) ||
+    vocabulary.tables.includes(trimmed)
+  ) {
+    return ["table"];
+  }
+  if (STRING_LITERAL.test(trimmed)) return ["string"];
+  if (NUMERIC_LITERAL.test(trimmed)) return ["number"];
+  if (trimmed === "true" || trimmed === "false") return ["boolean"];
+  // An enum, one of its constants, or the untyped `constant` older releases
+  // wrote are all the value the engine registered: a number unless declared a
+  // string.
+  const enumType = vocabulary.enums[trimmed];
+  if (enumType !== undefined) return [enumType];
+  if (vocabulary.stringConstants.includes(trimmed)) return ["string"];
+  if (trimmed === "constant" || CONSTANT_FQN.test(trimmed)) return ["number"];
+  const aliasOf = vocabulary.aliases[trimmed];
+  if (aliasOf !== undefined && !expanding.has(trimmed)) {
+    const next = new Set(expanding).add(trimmed);
+    return aliasOf.flatMap((aliased) => canonicalLeaves(aliased, vocabulary, next));
+  }
+  const renamed = RENAMED_TOKENS[trimmed] ?? trimmed;
+  // Primitive synonyms (`integer` and `number`, `buffer_data` and `buffer`) are
+  // the tokens the engine vocabulary maps to one TypeScript type.
+  return [
+    Object.hasOwn(DEFOLD_TYPE_MAP, renamed)
+      ? ((DEFOLD_TYPE_MAP as Readonly<Record<string, string>>)[renamed] as string)
+      : renamed,
+  ];
+}
+
+/**
+ * A slot's ref-doc tokens in a vocabulary-neutral form: the runtime values the
+ * slot takes, sorted and without duplicates, so a release that only respells a
+ * slot keeps its identity while one that changes what it takes does not.
+ */
+export function canonicalIdentityTypes(
+  types: readonly string[],
+  vocabulary: IdentityVocabulary,
+): string[] {
+  return [
+    ...new Set(types.flatMap((token) => canonicalLeaves(token, vocabulary, new Set()))),
+  ].sort();
+}
+
+function correctedTypes(
+  types: readonly string[],
+  correction: IdentityCorrection | undefined,
+  vocabulary: IdentityVocabulary,
+): string[] {
+  if (correction === undefined || !pinMatches(types, correction.pins)) {
+    return canonicalIdentityTypes(types, vocabulary);
+  }
+  if (correction.replaces !== undefined) {
+    return canonicalIdentityTypes(correction.replaces, vocabulary);
+  }
+  const removed = new Set(canonicalIdentityTypes(correction.removes ?? [], vocabulary));
+  return [
+    ...new Set([
+      ...canonicalIdentityTypes(types, vocabulary).filter((value) => !removed.has(value)),
+      ...canonicalIdentityTypes(correction.adds ?? [], vocabulary),
+    ]),
+  ].sort();
+}
+
+export interface IdentitySlot {
+  readonly types: readonly string[];
+  readonly isOptional: boolean;
+}
+
+/** A parameter as identity reads it: its corrected values and effective optionality. */
+export function identityParameter(
+  fn: ApiFunction,
+  parameter: ApiParameter,
+  vocabulary: IdentityVocabulary,
+): IdentitySlot {
+  const key = `${fn.name}:param:${parameter.name}`;
+  const types = correctedTypes(parameter.types, vocabulary.parameterCorrections[key], vocabulary);
+  // A slot a correction keeps required may still take an explicit nil, which
+  // stays part of what it takes; anywhere else, taking nil is being omissible.
+  if (vocabulary.requiredSlots.includes(key)) return { types, isOptional: false };
+  return {
+    types: types.filter((value) => value !== "nil"),
+    isOptional:
+      parameter.isOptional || types.includes("nil") || vocabulary.optionalSlots.includes(key),
+  };
+}
+
+/** A return value as identity reads it, with a return correction applied where it holds. */
+export function identityReturn(
+  fn: ApiFunction,
+  returned: ApiParameter,
+  vocabulary: IdentityVocabulary,
+): IdentitySlot {
+  const correction = vocabulary.returnCorrections[fn.name];
+  const applies =
+    correction !== undefined &&
+    (correction.slot === undefined
+      ? fn.returnValues.length === 1
+      : correction.slot === returned.name);
+  return {
+    types: correctedTypes(returned.types, applies ? correction : undefined, vocabulary),
+    isOptional: returned.isOptional,
+  };
+}