@defold-typescript/types 0.50.1 → 0.52.0

package/src/emit-dts.ts

@@ -1,5 +1,9 @@
 import messagesDoc from "../fixtures/messages_doc.json" with { type: "json" };
-import { type ApiSymbolIdentity, normalizedFunctionSignature } from "./api-availability";
+import {
+  type ApiSymbolIdentity,
+  type Box2dBackend,
+  normalizedFunctionSignature,
+} from "./api-availability";
 import type {
   ApiConstant,
   ApiFunction,
@@ -21,6 +25,7 @@ import {
   splitExampleSources,
   summaryFor,
 } from "./doc-comment";
+import { applyMessageOverlays, parseMessagesDoc } from "./emit-messages";
 import type { TranslationStore } from "./example-store";
 import { lookupExampleSegments, translateProseFences } from "./example-store";
 import {
@@ -30,7 +35,13 @@ import {
   indexBaseNoteResolver,
   OVERRIDE_RETURN_SLOT,
 } from "./index-slot-classifications";
-import { type LualsPosition, mapLualsExpression, needsArrayParens } from "./luals-type-expr";
+import {
+  isLualsFunctionToken,
+  type LualsPosition,
+  mapLualsExpression,
+  needsArrayParens,
+  splitTopLevel,
+} from "./luals-type-expr";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
 export { summaryFor };
@@ -75,6 +86,21 @@ export interface EmitOptions {
   // `UNDOCUMENTED_CONSTANTS` back-fill. Absent for a surface with no vendored
   // bindings (a ref-doc target), where every entry the ref-doc omits is emitted.
   registeredConstants?: ReadonlySet<string>;
+  // The `RETURN_TYPE_CORRECTIONS` and `STRUCT_MEMBER_ADDITIONS` keys whose binding
+  // pin holds in the target's vendored engine source. A binding-pinned entry
+  // applies only when its key is here, so a surface with no vendored bindings
+  // (absent) applies none of them.
+  bindingEvidence?: ReadonlySet<string>;
+  // The 1-based parameter slots, keyed by function FQN, that the target's engine
+  // bindings let a call omit but raise on when passed nil. Each optional one
+  // splits its function into a call without the slot and a call requiring it,
+  // so a possibly-undefined value is a compile error. Absent for a surface with
+  // no vendored bindings (a ref-doc target), which keeps every `?`.
+  nilRaisingSlots?: ReadonlyMap<string, readonly number[]>;
+  // The functions a target's skip rules removed from the module, read only to
+  // type an `OVERLOAD_SLOT_ALIASES` slot and to resolve a
+  // `CONSTANT_SLOT_RESOLUTIONS` borrow from their docs.
+  withheldFunctions?: readonly ApiFunction[];
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -165,14 +191,12 @@ export const ARBITRARY_TABLE_SLOTS = new Set([
   // runtime-owned passthrough: the table is filled by user code at runtime, never
   // by Defold's API contract. factory.create/collectionfactory.create `properties`
   // are spawn-time overrides keyed by the spawned object's own script-property
-  // names; bare `on_message`'s receive `message` is the pre-hashed, user-routed
-  // payload (mitigated for authored code by isMessage/onMessage). No static shape
-  // exists, so `Record<string | number, unknown>` is faithful, not a loss.
-  // collectionfactory.create curates the instance-id layer of `properties` as a
-  // mapping; each per-instance property table stays that faithful `Record`.
+  // names. No static shape exists, so `Record<string | number, unknown>` is
+  // faithful, not a loss. collectionfactory.create curates the instance-id layer
+  // of `properties` as a mapping; each per-instance property table stays that
+  // faithful `Record`.
   "factory.create",
   "collectionfactory.create",
-  "on_message",
   // engine-formatted blob: the engine produces the value at runtime and no
   // field list is documented, so the whole-slot `Record` is faithful, not a
   // loss. crash.get_backtrace is "table containing the backtrace",
@@ -245,6 +269,11 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "go.get",
   "go.set",
   "go.property",
+  // gui-overloads.d.ts closes the node property names and types each value per
+  // name, with a hash form for material constants.
+  "gui.animate",
+  "gui.get",
+  "gui.set",
   // msg-overloads.d.ts supplies the typed msg.post shape.
   "msg.post",
   // msg-overloads.d.ts supplies the typed msg.url shape (0 / 1-string / 3-arg
@@ -263,6 +292,7 @@ export const OVERLOAD_COVERED_SKIPS = new Set([
   "vmath.slerp",
   "vmath.mul_per_elem",
   "vmath.normalize",
+  "vmath.dot",
   // sys-overloads.d.ts supplies the disabling form and the form that takes the
   // cooldown the engine requires when enabling.
   "sys.set_engine_throttle",
@@ -320,13 +350,10 @@ export const MAPPING_TABLE_SLOTS: ReadonlyMap<string, { key: string; value: stri
 ]);
 
 // FQN-keyed return-type overrides for functions whose doc `returnvalues` are
-// empty yet the engine returns a value. `gui.get`'s doc lists no return, but it
-// yields the property value (a vmath.vector4 or a number); `unknown` is the
-// honest, ts-defold-matching shape. Per-FQN, not a blanket "empty returnvalues
-// -> unknown" rule: `gui.set` also has empty returnvalues and `void` is correct
-// there.
+// empty yet the engine returns a value. Per-FQN, not a blanket "empty
+// returnvalues -> unknown" rule: most functions with empty returnvalues return
+// nothing, and `void` is correct there.
 export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
-  ["gui.get", "unknown"],
   // Upstream documents the returned transaction step in prose only — its
   // `returnvalues` is empty while every sibling `editor.tx.*` builder declares
   // one, and `editor.transact()` takes exactly that.
@@ -362,8 +389,22 @@ export const RETURN_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
 // destructured into separate arguments; a boxed `LuaMultiReturn` is rejected
 // because TSTL passes it as one table, which is always truthy. `reason` quotes
 // the slot prose the provenance test searches for, as for the `nil` entries.
-export interface ReturnTypeCorrection {
-  readonly ts: string;
+//
+// An entry with a `binding` rests on the engine source instead of the prose:
+// it applies only on a target whose vendored binding shows the pin (the
+// `EmitOptions.bindingEvidence` keys), and `reason` names that binding in words.
+// A nil push proves nil-ability and nothing about the base type, so such an
+// entry usually carries `nullable` rather than `ts`.
+export interface BindingPin {
+  // Relative to the target's vendored `engine/` tree.
+  readonly file: string;
+  readonly cFunction: string;
+  // Token snippets the function body must contain and must lack; at least one.
+  readonly contains?: string;
+  readonly lacks?: string;
+}
+
+interface ReturnCorrectionBase {
   readonly upstream: readonly string[];
   // A later release's spelling of the same defect; see `correction-pins.ts`.
   readonly retypedUpstream?: readonly (readonly string[])[];
@@ -371,10 +412,33 @@ export interface ReturnTypeCorrection {
   // The named value of a multi-return the correction rewrites; `ts` is then
   // that value's type. Absent, the correction rewrites a single return.
   readonly slot?: string;
+  readonly binding?: BindingPin;
+}
+
+// `ts` replaces the emitted type. `nullable` keeps the type each target maps
+// from its own tokens and only adds or drops the `nil`, so a target whose
+// spelling differs keeps its own base.
+export type ReturnTypeCorrection = ReturnCorrectionBase &
+  (
+    | { readonly ts: string; readonly nullable?: undefined }
+    | { readonly nullable: boolean; readonly ts?: undefined }
+  );
+
+// The early nil return both tilemap readers take for an unknown layer, and
+// `TileMap_Get` for a cell out of range too.
+function tilemapEarlyNil(cFunction: string): BindingPin {
+  return {
+    file: "gamesys/src/gamesys/scripts/script_tilemap.cpp",
+    cFunction,
+    contains: "lua_pushnil(L); assert(top + 1 == lua_gettop(L)); return 1;",
+  };
 }
 
 // Keyed by FQN, mirroring PROPERTY_TYPE_CORRECTIONS.
-export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection> = new Map([
+export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection> = new Map<
+  string,
+  ReturnTypeCorrection
+>([
   [
     "b2d.get_body",
     {
@@ -408,8 +472,8 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       slot: "code",
     },
   ],
-  // 1.13.2 declares `render_predicate`, whose TYPEDEF aliases `userdata`, and
-  // that still emits `number`.
+  // 1.13.2 retypes the return to `render_predicate`, whose TYPEDEF aliases
+  // `userdata`; its type mapping emits the same brand.
   [
     "render.predicate",
     {
@@ -439,6 +503,161 @@ export const RETURN_TYPE_CORRECTIONS: ReadonlyMap<string, ReturnTypeCorrection>
       reason: "the customized try function.",
     },
   ],
+  [
+    "factory.create",
+    {
+      nullable: true,
+      upstream: ["hash"],
+      reason: "script_factory.cpp:FactoryComp_Create pushes nil when the spawn fails",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/script_factory.cpp",
+        cFunction: "FactoryComp_Create",
+        contains: "dmScript::PushHash(L, id); } else { lua_pushnil(L); }",
+      },
+    },
+  ],
+  // 1.13.2 retypes each tilemap return to a precise spelling of the same value
+  // and still omits the nil.
+  ...(
+    [
+      ["tilemap.get_tile", ["number"], ["integer"]],
+      [
+        "tilemap.get_tile_info",
+        ["table"],
+        ["{ index:integer, h_flip:boolean, v_flip:boolean, rotate_90:boolean }"],
+      ],
+    ] as const
+  ).map(
+    ([key, upstream, retyped]) =>
+      [
+        key,
+        {
+          nullable: true,
+          upstream,
+          retypedUpstream: [retyped],
+          reason:
+            "script_tilemap.cpp:TileMap_Get pushes nil for an unknown layer or a cell out of range",
+          binding: tilemapEarlyNil("TileMap_Get"),
+        },
+      ] as const,
+  ),
+  [
+    "tilemap.get_tiles",
+    {
+      nullable: true,
+      upstream: ["table"],
+      retypedUpstream: [["table<integer, table<integer, integer>>"]],
+      reason: "script_tilemap.cpp:TileMap_GetTiles pushes nil for an unknown layer",
+      binding: tilemapEarlyNil("TileMap_GetTiles"),
+    },
+  ],
+  [
+    "bullet3d.shape.get_shape",
+    {
+      ts: "bullet3d.shape.definition | { type: typeof bullet3d.shape.SHAPE_TYPE_MESH }",
+      upstream: ["bullet3d.shape.definition"],
+      reason:
+        "script_bullet3d_shape.cpp:Shape_GetShape sets only `type` for a triangle mesh, which no shape definition arm matches",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/bullet3d/script_bullet3d_shape.cpp",
+        cFunction: "Shape_GetShape",
+        contains: "case TRIANGLE_MESH_SHAPE_PROXYTYPE: case GIMPACT_SHAPE_PROXYTYPE: break;",
+      },
+    },
+  ],
+  [
+    "collectionproxy.set_collection",
+    {
+      nullable: true,
+      upstream: ["number"],
+      retypedUpstream: [["collectionproxy.RESULT"]],
+      reason:
+        "script_collectionproxy.cpp:CollectionProxy_SetCollection pushes true, nil when the change succeeds",
+      slot: "code",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/script_collectionproxy.cpp",
+        cFunction: "CollectionProxy_SetCollection",
+        contains: "case SET_COLLECTION_PATH_RESULT_OK: lua_pushboolean(L, 1); lua_pushnil(L);",
+      },
+    },
+  ],
+  [
+    "image.get_astc_header",
+    {
+      nullable: false,
+      upstream: ["table", "nil"],
+      retypedUpstream: [["image.astc_header", "nil"]],
+      reason: "script_image.cpp:Image_GetAstcHeader raises on invalid data and never pushes nil",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/script_image.cpp",
+        cFunction: "Image_GetAstcHeader",
+        contains: 'return luaL_error(L, "Data is not a valid .astc file");',
+        lacks: "lua_pushnil(L);",
+      },
+    },
+  ],
+  // `PushRayCastResponse` has two definitions; `Physics_RayCast` calls the one
+  // that takes the world, which sets every payload field but `request_id`.
+  [
+    "physics.raycast",
+    {
+      ts: 'Omit<BuiltinMessages["ray_cast_response"], "request_id">[] | Omit<BuiltinMessages["ray_cast_response"], "request_id"> | undefined',
+      upstream: ["table", "nil"],
+      retypedUpstream: [
+        ["message.physics.ray_cast_response[]", "message.physics.ray_cast_response", "nil"],
+      ],
+      reason:
+        "script_physics.cpp:Physics_RayCast pushes each hit through PushRayCastResponse(L, world, hit), which sets no request_id",
+      binding: {
+        file: "gamesys/src/gamesys/scripts/script_physics.cpp",
+        cFunction: "Physics_RayCast",
+        contains: "PushRayCastResponse(L, world, hits[i]);",
+        lacks: '"request_id"',
+      },
+    },
+  ],
+  ...(
+    [
+      [
+        "collectionfactory.create",
+        "Hash",
+        ["table<hash, hash>"],
+        "gamesys/src/gamesys/scripts/script_collection_factory.cpp",
+        "CollectionFactoryComp_Create",
+      ],
+      [
+        "gui.get_tree",
+        'Opaque<"node">',
+        ["table<hash, node>"],
+        "gui/src/gui_script.cpp",
+        "LuaGetTree",
+      ],
+      [
+        "gui.clone_tree",
+        'Opaque<"node">',
+        ["table<hash, node>"],
+        "gui/src/gui_script.cpp",
+        "LuaCloneTree",
+      ],
+    ] as const
+  ).map(
+    ([key, value, retyped, file, cFunction]) =>
+      [
+        key,
+        {
+          ts: `LuaTable<Hash, ${value}> & { get: LuaTableGetMethod<string, ${value}> }`,
+          upstream: ["table"],
+          retypedUpstream: [retyped],
+          reason: `${file.slice(file.lastIndexOf("/") + 1)}:${cFunction} sets HashTableIndex as the id table's __index, which hashes a string key`,
+          binding: {
+            file,
+            cFunction,
+            contains:
+              'lua_pushcfunction(L, HashTableIndex); lua_setfield(L, -2, "__index"); lua_setmetatable(L, -2);',
+          },
+        },
+      ] as const,
+  ),
 ]);
 
 // A parameter whose declared `types` disagree with what the same element's
@@ -565,6 +784,35 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
         },
       ] as const,
   ),
+  ...(
+    [
+      ["clone_tree", "LuaCloneTree"],
+      ["get_tree", "LuaGetTree"],
+    ] as const
+  ).map(
+    ([name, cFunction]) =>
+      [
+        `gui.${name}:param:node`,
+        {
+          adds: "undefined",
+          upstream: ["node"],
+          reason: `gui_script.cpp:${cFunction} pushes its result table before testing argument 1 with lua_isnil, so nil selects the whole scene and an absent argument reaches LuaCheckNodeInternal and raises`,
+        },
+      ] as const,
+  ),
+  ...(["get_slider_motor", "set_slider_motor"] as const).map(
+    (name) =>
+      [
+        `bullet3d.constraint.${name}:param:motor`,
+        {
+          adds: '"linear" | "angular"',
+          removes: ["string"],
+          upstream: ["string"],
+          reason:
+            "script_bullet3d_constraint.cpp:CheckSliderMotorAxis raises \"motor must be 'linear' or 'angular'\" on any other string",
+        },
+      ] as const,
+  ),
   [
     "sound.get_group_name:param:group",
     {
@@ -643,9 +891,10 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
     "render.disable_texture:param:binding",
     {
       adds: "number",
+      removes: ['Opaque<"texture">'],
       upstream: ["texture", "string", "hash"],
       reason:
-        '"texture binding, either by texture unit, string or hash"; example `render.disable_texture(0)`',
+        "render_script.cpp:RenderScript_DisableTexture reads a number as a texture unit with lua_isnumber and anything else with CheckHashOrString; a texture handle is a number, so it is read as a unit",
     },
   ],
   [
@@ -663,11 +912,42 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
       adds: 'Opaque<"render_predicate">',
       removes: ["number"],
       upstream: ["number"],
-      retypedUpstream: [["render_predicate"]],
       reason:
-        "render_script.cpp:RenderScript_Draw reads the predicate with RenderScriptPredicate_Check, the userdata render.predicate returns; 1.13.2's `render_predicate` still emits `number`",
+        "render_script.cpp:RenderScript_Draw reads the predicate with RenderScriptPredicate_Check, the userdata render.predicate returns; 1.13.2 types the slot `render_predicate`, whose type mapping is that brand",
     },
   ],
+  ...(["enable_state", "disable_state"] as const).map(
+    (name) =>
+      [
+        `render.${name}:param:state`,
+        {
+          adds: "graphics.State",
+          removes: ["graphics.STATE"],
+          upstream: ["graphics.STATE"],
+          reason: `render_script.cpp:RenderScript_${name === "enable_state" ? "Enable" : "Disable"}State raises "Invalid state" on any state but the six it lists, so graphics.STATE_SCISSOR_TEST and graphics.STATE_ALPHA_TEST_SUPPORTED are rejected`,
+        },
+      ] as const,
+  ),
+  ...(
+    [
+      "source_factor_color",
+      "destination_factor_color",
+      "source_factor_alpha",
+      "destination_factor_alpha",
+    ] as const
+  ).map(
+    (slot) =>
+      [
+        `render.set_blend_func_separate:param:${slot}`,
+        {
+          adds: "graphics.BlendFactor",
+          removes: ["number"],
+          upstream: ["number"],
+          reason:
+            'render_script.cpp:RenderScript_SetBlendFuncSeparate raises "Invalid blend factor" on any value CheckBlendFactor does not list',
+        },
+      ] as const,
+  ),
   [
     "go.delete:param:id",
     {
@@ -686,15 +966,6 @@ export const PARAM_TYPE_CORRECTIONS: ReadonlyMap<string, ParamTypeCorrection> =
       reason: 'sys.load_buffer example `buffer.get_bytes(my_buffer, "data")`',
     },
   ],
-  [
-    "gui.set:param:value",
-    {
-      adds: "Matrix4 | Hash",
-      upstream: ["number", "vector4", "vector3", "quaternion"],
-      reason:
-        'example `gui.set(node, "light_matrix", vmath.matrix4())` ("matrix4 is also supported"); example `gui.set(msg.url(), "textures", atlas_id, {key = "runtime_texture"})` passes the hash `resource.create_atlas` returns',
-    },
-  ],
   [
     "gui.set_rotation:param:rotation",
     {
@@ -903,6 +1174,10 @@ export const OPTIONAL_SLOT_CORRECTIONS: ReadonlyMap<string, string> = new Map([
     "render.set_render_target:param:render_target",
     "render_script.cpp:RenderScript_SetRenderTarget sets the default target when lua_gettop(L) == 0",
   ],
+  [
+    "buffer.get_bytes:param:stream_name",
+    "script_buffer.cpp:GetBytes reads only argument 1 with CheckBufferUnpack and returns every byte of the buffer",
+  ],
   ["socket.newtry:param:finalizer", "socket.protect's example `local try = socket.newtry()`"],
   ...(
     [
@@ -1045,13 +1320,6 @@ export const REQUIRED_SLOT_CORRECTIONS: ReadonlyMap<string, RequiredSlotCorrecti
       evidence: "gui_script.cpp:LuaSetParent reads a node from argument 2 unless lua_isnil(L, 2)",
     },
   ],
-  [
-    "gui.set:param:value",
-    {
-      nil: true,
-      evidence: "gui_script.cpp:LuaSet converts argument 3 with LuaToVar unless lua_isnil(L, 3)",
-    },
-  ],
   [
     "window.set_listener:param:callback",
     {
@@ -1141,6 +1409,335 @@ function firstSlotAlternative(
   return original === null ? null : { ...prepared, original };
 }
 
+// The calls a function splits into at its optional nil-raising slots
+// (`EmitOptions.nilRaisingSlots`): one ending before each such slot, then one
+// taking them all, every such slot before an arm's end declared required. A
+// required slot, or one a rest parameter folds in, splits nothing.
+function nilRaisingArms(
+  prepared: PreparedFunction,
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]>,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const firstVararg = parameters.findIndex(isVarargParameter);
+  const positional = firstVararg === -1 ? parameters.length : firstVararg;
+  const split = [...new Set(nilRaisingSlots.get(name) ?? [])]
+    .map((slot) => slot - 1)
+    .filter((index) => {
+      const p = parameters[index];
+      return index < positional && p !== undefined && isDocOptional(p, name);
+    })
+    .sort((a, b) => a - b);
+  if (split.length === 0) return [prepared];
+  const shorter = split.map((end, k) => ({
+    ...prepared,
+    original: { ...prepared.original, parameters: parameters.slice(0, end) },
+    required: new Set(split.slice(0, k)),
+  }));
+  return [...shorter, { ...prepared, required: new Set(split) }];
+}
+
+// Table fields a binding reads as required only when `argument` is non-nil,
+// keyed by FQN. A curated function splits into a call whose `table` slot requires
+// `fields`, with `argument` as declared, then a call whose `argument` is nil, so
+// a possibly-nil argument must carry them.
+export interface PresenceRequiredFields {
+  readonly argument: string;
+  readonly table: string;
+  readonly fields: readonly string[];
+  readonly reason: string;
+}
+
+const FRAME_B_FIELDS = ["frame_b_position", "frame_b_rotation"] as const;
+
+export const PRESENCE_REQUIRED_FIELDS: ReadonlyMap<string, PresenceRequiredFields> = new Map<
+  string,
+  PresenceRequiredFields
+>([
+  [
+    "bullet3d.constraint.create_point_to_point",
+    {
+      argument: "body_b",
+      table: "params",
+      fields: ["pivot_b"],
+      reason:
+        "script_bullet3d_constraint.cpp:Constraint_CreatePointToPoint reads pivot_b as required when input.m_BodyB != 0",
+    },
+  ],
+  ...(
+    [
+      ["create_hinge", "Constraint_CreateHinge"],
+      ["create_cone_twist", "Constraint_CreateConeTwist"],
+      ["create_generic_6dof", "Constraint_CreateGeneric6Dof"],
+      ["create_slider", "Constraint_CreateSlider"],
+    ] as const
+  ).map(
+    ([name, cFunction]) =>
+      [
+        `bullet3d.constraint.${name}`,
+        {
+          argument: "body_b",
+          table: "params",
+          fields: FRAME_B_FIELDS,
+          reason: `script_bullet3d_constraint.cpp:${cFunction} reads frame B as required under if (input.m_BodyB)`,
+        },
+      ] as const,
+  ),
+]);
+
+// The calls PRESENCE_REQUIRED_FIELDS splits `prepared` into: the declared one
+// with its fields required, then the one whose argument is nil.
+function presenceArms(
+  prepared: PreparedFunction,
+  structs: readonly ApiStruct[],
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const entry = PRESENCE_REQUIRED_FIELDS.get(name);
+  if (entry === undefined) return [prepared];
+  const argument = parameters.findIndex((p) => p.name === entry.argument);
+  const table = parameters.findIndex((p) => p.name === entry.table);
+  const struct = structs.find((s) => parameters[table]?.types.includes(s.name));
+  if (argument === -1 || struct === undefined) {
+    throw new Error(
+      `presence-required fields ${name}: no ${entry.argument} parameter or ${entry.table} table`,
+    );
+  }
+  const missing = entry.fields.filter((field) => !struct.members.some((m) => m.name === field));
+  if (missing.length > 0) {
+    throw new Error(`presence-required fields ${name}: ${struct.name} lacks ${missing.join(", ")}`);
+  }
+  const picked = entry.fields.map((field) => `"${field}"`).join(" | ");
+  const requireFields = (type: string): string => {
+    const operand = /^[\w$.]+$/.test(type) ? type : `(${type})`;
+    return `${operand} & Required<Pick<${operand}, ${picked}>>`;
+  };
+  const strict: PreparedFunction = { ...prepared, retype: new Map([[table, requireFields]]) };
+  // Declared required, the nil argument emits as `undefined` alone rather than
+  // gaining the `| undefined` of an interior optional slot.
+  const absent: PreparedFunction = {
+    ...prepared,
+    required: new Set([...(prepared.required ?? []), argument]),
+    retype: new Map([[argument, () => "undefined"]]),
+  };
+  return [strict, absent];
+}
+
+// A rule an engine binding enforces on one parameter that no ref-doc token
+// states, keyed `<fqn>:param:<name>`. Each rewrites the slot's mapped type, so
+// one entry holds on every target whatever token spelling produced that type.
+export type EngineSlotRule =
+  // `E[]` becomes `[E, ...E[]]`: the binding raises on an empty list.
+  | { readonly kind: "non-empty"; readonly reason: string }
+  // The constants the binding raises on leave the slot's type.
+  | { readonly kind: "excludes"; readonly constants: readonly string[]; readonly reason: string }
+  // With `flag` true the table must carry `fields`, which the binding then reads
+  // without a default.
+  | {
+      readonly kind: "flag-requires";
+      readonly flag: string;
+      readonly fields: readonly string[];
+      readonly reason: string;
+    }
+  // In each call that requires `slot`, this slot is required too and its
+  // top-level union loses `drops`.
+  | {
+      readonly kind: "alongside";
+      readonly slot: string;
+      readonly drops: readonly string[];
+      readonly reason: string;
+    };
+
+export const ENGINE_SLOT_RULES: ReadonlyMap<string, EngineSlotRule> = new Map<
+  string,
+  EngineSlotRule
+>([
+  [
+    "buffer.create:param:declaration",
+    {
+      kind: "non-empty",
+      reason:
+        'script_buffer.cpp:Create raises "You must specify at least one stream declaration" when the list holds fewer than one entry',
+    },
+  ],
+  [
+    "buffer.set_metadata:param:values",
+    {
+      kind: "non-empty",
+      reason:
+        'script_buffer.cpp:SetMetadata raises "invalid metadata" when lua_objlen of values is 0',
+    },
+  ],
+  [
+    "buffer.set_metadata:param:value_type",
+    {
+      kind: "excludes",
+      constants: ["buffer.VALUE_TYPE_INT64", "buffer.VALUE_TYPE_UINT64"],
+      reason:
+        'script_buffer.cpp:SetMetadata raises "64 bit integer metadata are not supported." on VALUE_TYPE_UINT64 and VALUE_TYPE_INT64',
+    },
+  ],
+  [
+    "resource.create_sound_data:param:options",
+    {
+      kind: "flag-requires",
+      flag: "partial",
+      fields: ["filesize"],
+      reason:
+        "script_resource.cpp:CreateSoundData reads filesize with the no-default CheckFieldValue<int> when partial is true, and CheckValue<int> raises on a non-number",
+    },
+  ],
+  [
+    "go.delete:param:id",
+    {
+      kind: "alongside",
+      slot: "recursive",
+      drops: ["boolean"],
+      reason:
+        "gameobject_script.cpp:Script_Delete raises on a boolean id with a second argument, and on a nil id once recursive is popped",
+    },
+  ],
+]);
+
+// `prepared` with `rewrite` applied after any rewrite it already makes at `index`.
+function withRetype(
+  prepared: PreparedFunction,
+  index: number,
+  rewrite: (type: string) => string,
+): PreparedFunction {
+  const retype = new Map(prepared.retype);
+  const prior = retype.get(index);
+  retype.set(index, prior === undefined ? rewrite : (type) => rewrite(prior(type)));
+  return { ...prepared, retype };
+}
+
+// `E[]` as `[E, ...E[]]`; the element keeps its own parentheses.
+function nonEmptyList(type: string, key: string): string {
+  const element = type.endsWith("[]") ? type.slice(0, -2) : "";
+  const single =
+    splitTopLevel(type, "|").length === 1 &&
+    splitTopLevel(type, "&").length === 1 &&
+    !isFunctionTypeText(type);
+  if (element === "" || !single) {
+    throw new Error(`engine slot rule ${key}: ${type} is not one array`);
+  }
+  return `[${element}, ...${element}[]]`;
+}
+
+function withoutMembers(type: string, drops: readonly string[], key: string): string {
+  const members = splitTopLevel(type, "|").map((member) => member.trim());
+  const missing = drops.filter((drop) => !members.includes(drop));
+  if (missing.length > 0) {
+    throw new Error(`engine slot rule ${key}: ${type} has no ${missing.join(", ")} to drop`);
+  }
+  return members.filter((member) => !drops.includes(member)).join(" | ");
+}
+
+// The field names a table slot declares: its STRUCT's members, else the fields
+// parsed from its own doc.
+function slotFieldNames(parameter: ApiParameter, structs: readonly ApiStruct[]): string[] {
+  const struct = structs.find((s) => parameter.types.includes(s.name));
+  if (struct !== undefined) return struct.members.map((member) => member.name);
+  const fields = parameter.fields ?? parseTableFields(parameter.doc) ?? [];
+  return fields.map((field) => field.name);
+}
+
+function engineSlotRuleArms(
+  prepared: PreparedFunction,
+  arms: readonly PreparedFunction[],
+  key: string,
+  rule: EngineSlotRule,
+  index: number,
+  structs: readonly ApiStruct[],
+  bindingsRead: boolean,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const takes = (arm: PreparedFunction): boolean => index < arm.original.parameters.length;
+  const rewriteEach = (rewrite: (type: string) => string): PreparedFunction[] =>
+    arms.map((arm) => (takes(arm) ? withRetype(arm, index, rewrite) : arm));
+  switch (rule.kind) {
+    case "non-empty":
+      return rewriteEach((type) => nonEmptyList(type, key));
+    case "excludes": {
+      const excluded = rule.constants.map((constant) => `typeof ${constant}`).join(" | ");
+      return rewriteEach((type) => `Exclude<${type}, ${excluded}>`);
+    }
+    case "flag-requires": {
+      const declared = slotFieldNames(parameters[index] as ApiParameter, structs);
+      const missing = [rule.flag, ...rule.fields].filter((field) => !declared.includes(field));
+      if (missing.length > 0) {
+        throw new Error(`engine slot rule ${key}: the table declares no ${missing.join(", ")}`);
+      }
+      const picked = rule.fields.map((field) => `"${field}"`).join(" | ");
+      return rewriteEach((type) => {
+        const operand =
+          splitTopLevel(type, "|").length > 1 || isFunctionTypeText(type) ? `(${type})` : type;
+        return `${operand} & ({ ${rule.flag}?: false } | ({ ${rule.flag}: true } & Required<Pick<${type}, ${picked}>>))`;
+      });
+    }
+    case "alongside": {
+      const partner = parameters.findIndex((p) => p.name === rule.slot);
+      const partnerParameter = parameters[partner];
+      const requires = (arm: PreparedFunction): boolean =>
+        partnerParameter !== undefined &&
+        partner < arm.original.parameters.length &&
+        (arm.required?.has(partner) === true || !isDocOptional(partnerParameter, name));
+      if (!arms.some(requires)) {
+        // Without the target's nil-raising slots no call was split out to
+        // require the partner, so there is no binding to have stopped marking it.
+        if (!bindingsRead) return [...arms];
+        throw new Error(
+          partnerParameter === undefined
+            ? `engine slot rule ${key}: ${name} has no ${rule.slot} parameter`
+            : `engine slot rule ${key}: no call of ${name} requires ${rule.slot}`,
+        );
+      }
+      return arms.map((arm) =>
+        requires(arm)
+          ? {
+              ...withRetype(arm, index, (type) => withoutMembers(type, rule.drops, key)),
+              required: new Set([...(arm.required ?? []), index]),
+            }
+          : arm,
+      );
+    }
+  }
+}
+
+// `arms` with every ENGINE_SLOT_RULES entry keyed to `prepared` applied.
+// `bindingsRead` says the emit was given the target's nil-raising slots.
+function applyEngineSlotRules(
+  prepared: PreparedFunction,
+  arms: readonly PreparedFunction[],
+  structs: readonly ApiStruct[],
+  bindingsRead: boolean,
+): PreparedFunction[] {
+  const { name, parameters } = prepared.original;
+  const prefix = `${name}:param:`;
+  let ruled = [...arms];
+  for (const [key, rule] of ENGINE_SLOT_RULES) {
+    if (!key.startsWith(prefix)) continue;
+    const slot = key.slice(prefix.length);
+    const index = parameters.findIndex((p) => p.name === slot);
+    if (index === -1) {
+      throw new Error(`engine slot rule ${key}: ${name} has no ${slot} parameter`);
+    }
+    ruled = engineSlotRuleArms(prepared, ruled, key, rule, index, structs, bindingsRead);
+  }
+  return ruled;
+}
+
+// Every call a function declares, in order: its nil-raising arms, each split
+// at its presence-required fields, then narrowed by its engine slot rules.
+function callArms(
+  prepared: PreparedFunction,
+  nilRaisingSlots: ReadonlyMap<string, readonly number[]> | undefined,
+  structs: readonly ApiStruct[],
+): PreparedFunction[] {
+  const arms = nilRaisingArms(prepared, nilRaisingSlots ?? new Map()).flatMap((arm) =>
+    presenceArms(arm, structs),
+  );
+  return applyEngineSlotRules(prepared, arms, structs, nilRaisingSlots !== undefined);
+}
+
 export type ConstantSlotResolution =
   | { readonly borrow: string }
   | { readonly family: string; readonly evidence: string }
@@ -1155,8 +1752,6 @@ export const CONSTANT_SLOT_RESOLUTIONS: ReadonlyMap<string, ConstantSlotResoluti
   string,
   ConstantSlotResolution
 >([
-  ["gui.get:param:property", { borrow: "gui.animate:param:property" }],
-  ["gui.set:param:property", { borrow: "gui.animate:param:property" }],
   ["gui.cancel_animations:param:property", { borrow: "gui.animate:param:property" }],
   [
     "buffer.set_metadata:param:value_type",
@@ -1285,6 +1880,29 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
       "go.PLAYBACK_LOOP_PINGPONG",
     ],
   },
+  // The factors render_script.cpp:CheckBlendFactor accepts, in its order. Every
+  // target defines the constants; only the newer ones name the union.
+  {
+    home: "graphics",
+    name: "BlendFactor",
+    members: [
+      "graphics.BLEND_FACTOR_ZERO",
+      "graphics.BLEND_FACTOR_ONE",
+      "graphics.BLEND_FACTOR_SRC_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_SRC_COLOR",
+      "graphics.BLEND_FACTOR_DST_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_DST_COLOR",
+      "graphics.BLEND_FACTOR_SRC_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_SRC_ALPHA",
+      "graphics.BLEND_FACTOR_DST_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_DST_ALPHA",
+      "graphics.BLEND_FACTOR_SRC_ALPHA_SATURATE",
+      "graphics.BLEND_FACTOR_CONSTANT_COLOR",
+      "graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_COLOR",
+      "graphics.BLEND_FACTOR_CONSTANT_ALPHA",
+      "graphics.BLEND_FACTOR_ONE_MINUS_CONSTANT_ALPHA",
+    ],
+  },
   {
     home: "graphics",
     name: "BufferType",
@@ -1498,6 +2116,12 @@ export const CONSTANT_UNION_ALIASES: readonly ConstantUnionAlias[] = [
       "graphics.BUFFER_TYPE_STENCIL_BIT",
     ],
   },
+  // The render-target creator raises on any other texture type.
+  {
+    home: "render",
+    name: "RenderTargetTextureType",
+    members: ["graphics.TEXTURE_TYPE_2D", "graphics.TEXTURE_TYPE_CUBE_MAP"],
+  },
   {
     home: "sys",
     name: "NetworkConnectivity",
@@ -1553,6 +2177,13 @@ function unionAliasDeclaration(
   return `type ${name} = ${members.map(arm).join(" | ")};`;
 }
 
+// A slot of a function the authored-overload lane declares, published under
+// one alias on every target so the version-independent overload file can
+// name the type each target's own reference gives that slot.
+export const OVERLOAD_SLOT_ALIASES: ReadonlyMap<string, string> = new Map([
+  ["render.render_target:param:parameters", "RenderTargetParams"],
+]);
+
 const DOC_CONSTANT_TOKEN =
   /(?<![A-Za-z0-9_.])([a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)*\.[A-Z][A-Z0-9_]*)(\*)?/g;
 
@@ -1602,9 +2233,14 @@ function constantSlotTokens(
   return documentedConstantTokens(entry.family, universe);
 }
 
-function slotDocLookup(module: ApiModule): SlotDocLookup {
+// A borrow reads the ref-doc, so a slot of a function the skip rules withheld
+// (`gui.animate`, which gui-overloads.d.ts declares) still lends its doc.
+function slotDocLookup(
+  module: ApiModule,
+  withheldFunctions: readonly ApiFunction[] = [],
+): SlotDocLookup {
   const docs = new Map<string, string>();
-  for (const fn of module.functions) {
+  for (const fn of [...module.functions, ...withheldFunctions]) {
     for (const p of fn.parameters) {
       const key = tableSlotKey(fn.name, "param", p.name);
       if (!docs.has(key)) docs.set(key, p.doc);
@@ -1624,8 +2260,9 @@ export function resolveConstantSlotTokens(
   module: ApiModule,
   slotKey: string,
   universe: ReadonlySet<string>,
+  withheldFunctions: readonly ApiFunction[] = [],
 ): string[] {
-  const lookupDoc = slotDocLookup(module);
+  const lookupDoc = slotDocLookup(module, withheldFunctions);
   return constantSlotTokens(lookupDoc(slotKey) ?? "", slotKey, lookupDoc, universe);
 }
 
@@ -1639,21 +2276,23 @@ type ConstantSlotTokens = (
 function constantSlotTokenResolver(
   module: ApiModule,
   universe: ReadonlySet<string>,
+  withheldFunctions: readonly ApiFunction[] = [],
 ): ConstantSlotTokens {
-  const lookupDoc = slotDocLookup(module);
+  const lookupDoc = slotDocLookup(module, withheldFunctions);
   return (elementName, slotKind, slotName, doc) =>
     constantSlotTokens(doc, tableSlotKey(elementName, slotKind, slotName), lookupDoc, universe);
 }
 
-// FQN-keyed allowlist of the `types.is_*` checks that genuinely narrow their
-// argument, mapped to the `DEFOLD_TYPE_MAP` token whose interface they prove.
-// Emitting these as user-defined type guards (`var_ is Vector3`) is the only way
-// to narrow an engine userdata value, which `typeof` cannot. An allowlist, not a
-// blanket `is_*` match: `b2d.body.is_active`, `gui.is_enabled`,
-// `sound.is_music_playing`, `go.exists`, `sys.exists` are runtime-state /
-// existence checks on already-typed arguments and must stay `boolean`. An
-// unlisted future `types.is_*` also stays a visible `boolean` until curated here,
-// matching the ARBITRARY_TABLE_SLOTS deliberate-opt-in precedent.
+// FQN-keyed allowlist of the checks that genuinely narrow their argument, mapped
+// to the `DEFOLD_TYPE_MAP` token whose type they prove: the `types.is_*` checks,
+// and `bullet3d.collision_object.is_rigid_body`, whose binding is a
+// `btRigidBody::upcast` test. Emitting these as user-defined type guards
+// (`var_ is Vector3`) is the only way to narrow an engine userdata value, which
+// `typeof` cannot. An allowlist, not a blanket `is_*` match: `b2d.body.is_active`,
+// `gui.is_enabled`, `sound.is_music_playing`, `go.exists`, `sys.exists` are
+// runtime-state / existence checks on already-typed arguments and must stay
+// `boolean`. An unlisted future `types.is_*` also stays a visible `boolean` until
+// curated here, matching the ARBITRARY_TABLE_SLOTS deliberate-opt-in precedent.
 export const TYPE_PREDICATES: ReadonlyMap<string, string> = new Map([
   ["types.is_hash", "hash"],
   ["types.is_matrix4", "matrix4"],
@@ -1662,13 +2301,47 @@ export const TYPE_PREDICATES: ReadonlyMap<string, string> = new Map([
   ["types.is_vector", "vector"],
   ["types.is_vector3", "vector3"],
   ["types.is_vector4", "vector4"],
+  ["bullet3d.collision_object.is_rigid_body", "btRigidBody"],
+]);
+
+// The merged ref-doc gives each Box2D backend's form of these queries one
+// parameter list, so the first (v2) arm always wins and a v3 hit is unreachable.
+// A type parameter tells them apart: v2/script_box2d_world_v2.cpp:PushCastHit
+// sets `fixture` and `shape` to one PushFixtureInfo table, while
+// v3/script_box2d_world_v3.cpp:PushCastHit sets `shape` alone from
+// PushShapeInfoForShape. The v2 arm is declared first, so a call with no type
+// argument keeps the v2 hits; its `= "v2"` default only states that. Keyed by
+// `box2dBackendArmKey`.
+export const BOX2D_BACKEND_ARMS: ReadonlyMap<string, Box2dBackend> = new Map<string, Box2dBackend>([
+  ["b2d.world.cast_ray:b2d.fixture_cast_hit[]", "v2"],
+  ["b2d.world.cast_ray:b2d.shape_cast_hit[]", "v3"],
+  ["b2d.world.cast_ray_closest:b2d.fixture_cast_hit", "v2"],
+  ["b2d.world.cast_ray_closest:b2d.shape_cast_hit", "v3"],
+  ["b2d.world.cast_shape:b2d.fixture_cast_hit[]", "v2"],
+  ["b2d.world.cast_shape:b2d.shape_cast_hit[]", "v3"],
+  ["b2d.world.overlap_aabb:b2d.fixture_info[]", "v2"],
+  ["b2d.world.overlap_aabb:b2d.shape_info[]", "v3"],
+  ["b2d.world.overlap_shape:b2d.fixture_info[]", "v2"],
+  ["b2d.world.overlap_shape:b2d.shape_info[]", "v3"],
 ]);
 
+// `<fqn>:<first non-nil type of the first return>`: the two arms of each
+// `BOX2D_BACKEND_ARMS` query share every parameter and differ only there.
+export function box2dBackendArmKey(fn: ApiFunction): string {
+  const first = fn.returnValues[0]?.types.find((type) => type !== "nil") ?? "";
+  return `${fn.name}:${first}`;
+}
+
+function box2dBackendTypeParameters(fn: ApiFunction): string {
+  const backend = BOX2D_BACKEND_ARMS.get(box2dBackendArmKey(fn));
+  if (backend === undefined) return "";
+  return backend === "v2" ? '<Backend extends "v2" = "v2">' : '<Backend extends "v3">';
+}
+
 // Element names whose `table` slot is a prose-only `array/list/table of <T>` shape
 // the field-list parser cannot read, but whose element type a human curated from
 // the doc. The value is a single element token (`T[]`) or a token list when the
-// element is itself a union — `go.delete`'s "table of id's" is the id union
-// `string | hash | url`, emitted `(string | Hash | Url)[]`. Emitted as a plain
+// element is itself a union, emitted `(A | B)[]`. Emitted as a plain
 // array, never `LuaMap`: an array element carries no illegal-index-key problem so
 // no TSTL wiring is needed. The audit consults this map too, so the gate and the
 // emitted surface stay coupled; a slot not curated here still surfaces under
@@ -1683,7 +2356,6 @@ export const HOMOGENEOUS_ARRAY_SLOTS: ReadonlyMap<string, string | readonly stri
   ["vmath.vector", "number"],
   ["sound.get_groups", "hash"],
   ["iap.list", "string"],
-  ["go.delete", ["string", "hash", "url"]],
   // push.register's `notifications` is a prose-only array of push.NOTIFICATION_*
   // bitmask constants (the ref example sums NOTIFICATION_BADGE/SOUND/ALERT). The
   // vendored push_doc.json fixture declares no NOTIFICATION_* constant elements, so
@@ -1706,7 +2378,11 @@ export type NestedMapping = { key: string; value: string };
 // for `collectionfactory.create`'s properties.
 export type TableSlotCuration = (
   | { kind: "mapping"; key: string; value: string | readonly TableField[] | NestedMapping }
-  | { kind: "array"; element: string | readonly string[] }
+  // `pairs` also admits any table whose values are the element, for a binding
+  // that walks the table with lua_next and reads only its values. The extra arm
+  // is `LuaPairsIterable`, which is covariant in its value; `LuaTable` is
+  // invariant through `set`, so it would reject a `LuaTable<Hash, Hash>`.
+  | { kind: "array"; element: string | readonly string[]; pairs?: true }
   | { kind: "object"; fields: readonly TableField[] }
   | { kind: "array-object"; fields: readonly TableField[] }
   // A `<key> -> <args table>` slot: the doc's `<dl>` describes the *value* shape,
@@ -1883,25 +2559,6 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   string,
   TableSlotCuration
 >([
-  // gui_script.cpp:LuaGet and LuaSet read the `key` and `keys` options. On a
-  // prose `table` slot TABLE_SLOT_FIELD_ADDITIONS supplies them; 1.13.2 types the
-  // slots as an inline record and a struct that omit them.
-  ...(
-    [
-      ["gui.get:param:options", "{ index?:integer }"],
-      ["gui.set:param:options", "gui.set_options"],
-    ] as const
-  ).map(
-    ([key, retyped]) =>
-      [
-        key,
-        {
-          kind: "verbatim",
-          ts: "{ index?: number; key?: string | Hash; keys?: (Hash | string)[] }",
-          retypedUpstream: [retyped],
-        },
-      ] as const,
-  ),
   // buffer.create's `declaration` is "a table where each entry (table) describes
   // a stream", and upstream's example passes a list of stream records whose
   // `type` is a buffer.VALUE_TYPE_* constant.
@@ -1929,6 +2586,19 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
     },
   ],
   ["collectionfactory.create:return:ids", { kind: "mapping", key: "hash", value: "hash" }],
+  // go.delete's "table of id's": gameobject_script.cpp:DeleteGOTable walks any
+  // table with lua_next and resolves each value with ResolveURL, so the id table
+  // collectionfactory.create returns deletes as it is. 1.13.2 retypes the slot
+  // to an id array, which still rejects that table.
+  [
+    "go.delete:param:id",
+    {
+      kind: "array",
+      element: ["string", "hash", "url"],
+      pairs: true,
+      retypedUpstream: ["(string|hash|url)[]"],
+    },
+  ],
   // font.get_info's `info` return is a `<dl>` with `path: hash` and a nested
   // `fonts` field whose `<dd>` is itself a `<dl>` (`path: string`, `path_hash:
   // hash`). parseTableFields flattens the inner `<dl>` to the top level, which
@@ -2186,62 +2856,6 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
       value: "number | vector4",
     },
   ],
-  // go.on_input and gui.on_input share the same well-known InputAction shape
-  // (the on_input function description lists the well-known fields: value,
-  // pressed, released, repeated, x/y/screen_x/screen_y/dx/dy/screen_dx/screen_dy,
-  // plus gamepad/touch/text multi-touch fields). The doc markup carries no
-  // field list of its own, so the shape is curated verbatim from the prose.
-  // Param-side optional fields: each input kind (mouse/key/text/gamepad) sets a
-  // different subset, so the call site always sees an `?` on every field.
-  // `touch` stays `table` (the nested multi-touch table has no machine-readable
-  // field list; mirrors the render.set_render_target.transient recursive case).
-  // The element is the bare `on_input` script hook (no namespace prefix), the
-  // same form the `on_message` arbitrary-table entry uses. The doc carries a
-  // well-formed touch input table, so `touch` is curated as a nested
-  // array-of-touch-records (the field has its own `<table>` listing id,
-  // pressed, released, tap_count, x, y, dx, dy, acc_x/y/z).
-  [
-    "on_input:param:action",
-    {
-      kind: "object",
-      fields: [
-        { name: "value", types: ["number"], optional: true },
-        { name: "pressed", types: ["boolean"], optional: true },
-        { name: "released", types: ["boolean"], optional: true },
-        { name: "repeated", types: ["boolean"], optional: true },
-        { name: "x", types: ["number"], optional: true },
-        { name: "y", types: ["number"], optional: true },
-        { name: "screen_x", types: ["number"], optional: true },
-        { name: "screen_y", types: ["number"], optional: true },
-        { name: "dx", types: ["number"], optional: true },
-        { name: "dy", types: ["number"], optional: true },
-        { name: "screen_dx", types: ["number"], optional: true },
-        { name: "screen_dy", types: ["number"], optional: true },
-        { name: "gamepad", types: ["number"], optional: true },
-        { name: "gamepad_axis", types: ["vector3"], optional: true },
-        {
-          name: "touch",
-          types: ["table"],
-          optional: true,
-          isList: true,
-          fields: [
-            { name: "id", types: ["number"] },
-            { name: "pressed", types: ["boolean"] },
-            { name: "released", types: ["boolean"] },
-            { name: "tap_count", types: ["number"] },
-            { name: "x", types: ["number"] },
-            { name: "y", types: ["number"] },
-            { name: "dx", types: ["number"] },
-            { name: "dy", types: ["number"] },
-            { name: "acc_x", types: ["number"] },
-            { name: "acc_y", types: ["number"] },
-            { name: "acc_z", types: ["number"] },
-          ],
-        },
-        { name: "text", types: ["string"], optional: true },
-      ],
-    },
-  ],
   // physics.create_joint and physics.set_joint_properties both declare
   // `properties` as a joint-type-specific table; the only universal field is
   // `collide_connected` (parseTableFields already recovers it from the
@@ -2267,10 +2881,13 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
   // buildTableDocResolver resolves only FUNCTION elements so the cross-ref
   // cannot fire (the message payload lives in messages_doc.json, not the
   // FUNCTION slot pool). The shape is curated directly from the message
-  // catalog (the six ray_cast_response payload fields). The doc declares a
+  // catalog: the ray_cast_response payload fields but `request_id`, which
+  // `Physics_RayCast` never sets. The doc declares a
   // `nil` branch ("If missed it returns <code>nil</code>"), so the existing
   // nil-aware emit already projects the curated array onto the
   // `array-object | nil` return type — no curation change needed there.
+  // Where its binding pin holds, the `physics.raycast` RETURN_TYPE_CORRECTIONS
+  // entry replaces the whole return.
   [
     "physics.raycast:return:result",
     {
@@ -2281,7 +2898,6 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
         { name: "normal", types: ["vector3"] },
         { name: "id", types: ["hash"] },
         { name: "group", types: ["hash"] },
-        { name: "request_id", types: ["number"] },
       ],
     },
   ],
@@ -2704,41 +3320,105 @@ export const TABLE_SLOT_CURATIONS: ReadonlyMap<string, TableSlotCuration> = new
 ]);
 
 // Slot-keyed (`element:param:name`, mirroring TABLE_SLOT_CURATIONS) replacements
-// for a callback parameter's recovered signature, used where the generic
-// `recoverCallbackSignature` `unknown`-everywhere form leaves real engine type
-// information on the table. The value is the full emitted function type. Honest
-// only: `window.set_listener` discriminates `event` by the union of the
-// `WINDOW_EVENT_*` constants the surface's own `window` namespace declares, and
-// its `data` is a bare record (only resize carries fields — `isWindowEvent` is the
-// path to typed `data`), mirroring the `msg.post` (send, typed) / `isMessage`
-// (receive, narrow) split.
+// for a callback parameter's signature. Each entry carries two forms, chosen by
+// the token the reference gives the slot. `untyped` answers a bare
+// `function(a, b, c)` token, where the generic `recoverCallbackSignature`
+// `unknown`-everywhere form leaves real engine type information on the table.
+// `typed` answers a `fun(a:T, ...)` token, where the reference names a type for
+// each parameter; `null` there emits the reference's own signature. Each form
+// is the full emitted function type. Honest only.
 //
-// The other entries type what the slot's own prose lists and nothing more.
+// `window.set_listener` discriminates `event` by the union of the
+// `WINDOW_EVENT_*` constants the surface's own `window` namespace declares, on
+// both forms: the union is derived from the surface, so each version accepts
+// exactly the constants it declares. Its untyped `data` is a bare record (only
+// resize carries fields) and its typed `data` is the reference's
+// `window.event_data`; `isWindowEvent` narrows either to the event's payload,
+// mirroring the `msg.post` (send, typed) / `isMessage` (receive, narrow) split.
+//
+// The other untyped forms type what the slot's own prose lists and nothing more.
 // `http.request`'s response fields are the `<ul>` under "The response data.
 // Contains the fields:"; each is conditional ("if not saved on disc", "only if
 // option report_progress is true") except `status`, and `headers` is the same
-// string map the request sends. `sprite.play_flipbook`'s message is the
-// "Information about the completion" list. `collectionproxy.load` documents
+// string map the request sends. The prose omits two fields the engine sets:
+// `url`, which every final response carries (script_http_util.h), and
+// `bytes_sent`, which a report_progress event carries beside `bytes_received`,
+// `bytes_total` and `url` (http_ddf.proto `HttpRequestProgress`). That event has
+// no `status`; typing it as its own shape needs a per-target authored overload,
+// so `status` stays required and the slot's `note` says how to tell the two
+// apart. Its typed form is the same signature: the typed reference names
+// `http.response`, which the runtime surface withholds. Both forms add the
+// `sender` no reference lists: comp_script.cpp delivers the response as a
+// message, with `PushURL(L, message->m_Sender)` then `PCall(L, 4, 0)`.
+// `model.play_anim`'s completion callback receives self, the message id and the
+// message only: script_model.cpp calls it with `PCall(L, 3, 0)`, so both forms
+// drop the `sender` every reference lists and type the message as the typed
+// reference's `model_animation_done`.
+// `sprite.play_flipbook`'s message is the "Information about the completion"
+// list. Its typed form is the same signature: the typed reference names the
+// built-in `animation_done` message, which has this shape, and the inline form
+// keeps the fields visible in the signature. `collectionproxy.load` documents
 // only that the callback receives `proxy_loading`, `proxy_ready` or
-// `proxy_error` messages and lists no fields, so its message is the bare record
-// `window.set_listener`'s `data` is.
-export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, string> = new Map([
+// `proxy_error` messages and lists no fields on the untyped reference, so its
+// untyped message is the bare record `window.set_listener`'s untyped `data` is;
+// the typed reference names `collectionproxy.load_data`, so its typed form
+// defers to the reference.
+export interface CallbackSignatureCuration {
+  /** Emitted for a bare `function(...)` token. */
+  readonly untyped: string;
+  /** Emitted for a typed `fun(...)` token; `null` emits the reference's own signature. */
+  readonly typed: string | null;
+  /** Appended to the parameter's doc, for what the signature cannot express. */
+  readonly note?: string;
+}
+
+const onBothForms = (signature: string, note?: string): CallbackSignatureCuration => ({
+  untyped: signature,
+  typed: signature,
+  ...(note === undefined ? {} : { note }),
+});
+
+export const CALLBACK_SIGNATURE_CURATIONS: ReadonlyMap<string, CallbackSignatureCuration> = new Map<
+  string,
+  CallbackSignatureCuration
+>([
   [
     "window.set_listener:param:callback",
-    // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted verbatim as a TS template literal type
-    "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: Record<string | number, unknown>) => void",
+    {
+      untyped:
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted verbatim as a TS template literal type
+        "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: Record<string | number, unknown>) => void",
+      typed:
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: emitted verbatim as a TS template literal type
+        "(self: unknown, event: (typeof window)[Extract<keyof typeof window, `WINDOW_EVENT_${string}`>], data: window.event_data) => void",
+    },
   ],
   [
     "http.request:param:callback",
-    "(self: unknown, id: Hash, response: { status: number; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }) => void",
+    onBothForms(
+      "(self: unknown, id: Hash, response: { status: number; url: string; response?: string; headers?: LuaMap<string, string>; path?: string; error?: string; bytes_sent?: number; bytes_received?: number; bytes_total?: number; range_start?: number; range_end?: number; document_size?: number }, sender: Url) => void",
+      "With `report_progress` set, the callback also receives progress events carrying `bytes_sent`, `bytes_received`, `bytes_total` and `url` but no `status`; `response.bytes_received !== undefined` marks a progress event, since a final response never carries it.",
+    ),
+  ],
+  [
+    "model.play_anim:param:complete_function",
+    onBothForms(
+      '(self: unknown, message_id: Hash, message: BuiltinMessages["model_animation_done"]) => void',
+    ),
   ],
   [
     "sprite.play_flipbook:param:complete_function",
-    "(self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void",
+    onBothForms(
+      "(self: unknown, message_id: Hash, message: { current_tile: number; id: Hash }, sender: Url) => void",
+    ),
   ],
   [
     "collectionproxy.load:param:callback",
-    "(self: unknown, message_id: Hash, message: Record<string | number, unknown>, sender: Url) => void",
+    {
+      untyped:
+        "(self: unknown, message_id: Hash, message: Record<string | number, unknown>, sender: Url) => void",
+      typed: null,
+    },
   ],
 ]);
 
@@ -2801,11 +3481,11 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
   ["resource.set_atlas:param:table:animations[].playback", "go.Playback"],
   ["resource.create_atlas:param:table:animations[].playback", "go.Playback"],
   ["resource.get_atlas:return:data:animations[].playback", "go.Playback"],
-  ["gui.set:param:options:key", "string | Hash"],
   ["render.set_render_target:param:options:transient", "graphics.BufferType[]"],
   ["resource.create_sound_data:param:options:data", 'string | Opaque<"buffer">'],
-  // The same two slots where 1.13.2 types the option bag as a STRUCT, whose
-  // members still carry the narrower upstream types.
+  // The option bags 1.13.2 types as a STRUCT, whose members still carry the
+  // narrower upstream types: `gui.set`'s (its slot is declared in
+  // gui-overloads.d.ts) and `resource.create_sound_data`'s.
   ["gui.set_options:member:key", "string | Hash"],
   ["resource.sound_data_options:member:data", 'string | Opaque<"buffer">'],
   // Bitmasks typed as their flag enum: the create_texture example passes
@@ -2820,6 +3500,11 @@ export const TABLE_FIELD_TYPE_OVERRIDES: ReadonlyMap<string, string> = new Map([
     ] as const
   ).map((struct) => [`${struct}:member:flags`, "graphics.TEXTURE_USAGE_FLAG | number"] as const),
   ["render.render_target_buffer_params:member:flags", "render.RENDER_TARGET_FLAG | number"],
+  // gamesys_script.cpp:PushSampler, behind both get_samplers, pushes the raw
+  // texture type; NormalizeBindableTextureType never runs there. A separate
+  // sampler reports TEXTURE_TYPE_SAMPLER (6) and a separate texture binding one
+  // of the four TEXTURE_TYPE_TEXTURE_* (7-10), none of which has a Lua constant.
+  ["material.sampler_info:member:type", "graphics.TEXTURE_TYPE | 6 | 7 | 8 | 9 | 10"],
 ]);
 
 // A field the engine accepts on an option bag whose `<dl>` upstream otherwise
@@ -2839,13 +3524,6 @@ export interface TableFieldAddition {
   readonly evidence: readonly string[];
 }
 
-const PROPERTY_OPTION_KEYS: TableField = {
-  name: "keys",
-  types: ["table"],
-  optional: true,
-  tsType: "(Hash | string)[]",
-};
-
 export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition> = new Map<
   string,
   TableFieldAddition
@@ -2860,24 +3538,6 @@ export const TABLE_SLOT_FIELD_ADDITIONS: ReadonlyMap<string, TableFieldAddition>
       ],
     },
   ],
-  [
-    "gui.get:param:options",
-    {
-      fields: [{ name: "key", types: ["string", "hash"], optional: true }, PROPERTY_OPTION_KEYS],
-      evidence: [
-        "gui_script.cpp:LuaGet reads its options through dmGameObject::LuaToPropertyOptions, which reads index, key and keys",
-      ],
-    },
-  ],
-  [
-    "gui.set:param:options",
-    {
-      fields: [PROPERTY_OPTION_KEYS],
-      evidence: [
-        "gui_script.cpp:LuaSet reads its options through dmGameObject::LuaToPropertyOptions, which reads index, key and keys",
-      ],
-    },
-  ],
 ]);
 
 // A return-slot field upstream documents as platform-gated or nil-valued while
@@ -2899,32 +3559,13 @@ export interface ReturnFieldOptionalityCorrection {
   readonly evidence: string;
 }
 
-// The platform-gate markers upstream renders as `<span class="icon-*">` decode
-// to `[ios]`, `[android]`, `[html5]` — `user_agent` states its gate through the
-// marker alone, with no availability sentence to pin.
+// A platform gate alone is not evidence: `sys.get_sys_info` gates four fields
+// on a platform, yet `Sys_GetSysInfo` pushes each from a zero-filled char array,
+// so off-platform they are empty strings, never nil.
 export const RETURN_FIELD_OPTIONALITY_CORRECTIONS: ReadonlyMap<
   string,
   ReturnFieldOptionalityCorrection
 > = new Map([
-  [
-    "sys.get_sys_info:return:sys_info:device_model",
-    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
-  ],
-  [
-    "sys.get_sys_info:return:sys_info:manufacturer",
-    { upstream: ["string"], evidence: "[ios][android] Only available on iOS and Android." },
-  ],
-  [
-    "sys.get_sys_info:return:sys_info:device_ident",
-    {
-      upstream: ["string"],
-      evidence: '[ios] "identifierForVendor" on iOS. [android] "android_id" on Android.',
-    },
-  ],
-  [
-    "sys.get_sys_info:return:sys_info:user_agent",
-    { upstream: ["string"], evidence: "[html5] The HTTP user agent" },
-  ],
   [
     "sys.get_ifaddrs:return:ifaddrs:address",
     { upstream: ["string"], evidence: "might be nil if not available." },
@@ -2975,8 +3616,10 @@ export function applyFieldOptionalityCorrections(
 // `<element>:param:<slot>:<field>`, the TABLE_FIELD_TYPE_OVERRIDES shape, with
 // `<field>.<member>` or `<field>[].<member>` one level down. A `STRUCT` member
 // is keyed `<struct>:member:<field>`, for a target whose slot names that struct
-// (`field-correction-coverage.ts` pairs the two). The value is the evidence: the
-// C++ binding, `<file>:<cFunction>`, and how it reads the field.
+// (`field-correction-coverage.ts` pairs the two), or for a returned struct whose
+// binding always sets a member upstream marks optional. The value is the
+// evidence: the C++ binding, `<file>:<cFunction>`, and how it reads or sets the
+// field.
 const CHECK_SHAPE_DEF = "CheckShapeDef reads the shape table with luaL_checkinteger(type)";
 const V2_FILTER_DATA =
   "v2/script_box2d_fixture_v2.cpp:CheckFilterData reads each with luaL_checkinteger";
@@ -3000,6 +3643,49 @@ export const OPTIONAL_MEMBER_CORRECTIONS: ReadonlyMap<string, string> = new Map(
   ],
 ]);
 
+// A `STRUCT` member the engine binding sets while the target's reference omits
+// it, keyed `<struct>:member:<field>`. It applies only where its binding pin
+// holds (the `EmitOptions.bindingEvidence` keys), and a struct that already
+// declares the member throws, so no entry outlives upstream's fix.
+export interface StructMemberAddition {
+  readonly member: Omit<ApiStructMember, "name">;
+  readonly binding: BindingPin;
+}
+
+export const STRUCT_MEMBER_ADDITIONS: ReadonlyMap<string, StructMemberAddition> = new Map([
+  [
+    memberCorrectionKey("graphics.adapter_limits", "max_storage_buffers_per_stage"),
+    {
+      member: {
+        type: "integer",
+        isOptional: false,
+        doc: "Maximum number of storage buffers per shader stage.",
+      },
+      binding: {
+        file: "script/src/script_graphics.cpp",
+        cFunction: "Graphics_GetAdapterInfo",
+        contains: 'lua_setfield(L, -2, "max_storage_buffers_per_stage");',
+      },
+    },
+  ],
+  [
+    memberCorrectionKey("sys.interface_info", "family"),
+    {
+      member: {
+        type: '"ipv4"|"ipv6"',
+        isOptional: true,
+        doc: "Address family, absent for an interface that is neither IPv4 nor IPv6.",
+      },
+      binding: {
+        file: "script/src/script_sys.cpp",
+        cFunction: "Sys_GetIfaddrs",
+        contains:
+          'lua_pushliteral(L, "ipv6"); } else { lua_pushnil(L); } lua_setfield(L, -2, "family");',
+      },
+    },
+  ],
+]);
+
 export const REQUIRED_FIELD_CORRECTIONS: ReadonlyMap<string, string> = new Map<string, string>([
   ...(["mass", "center", "inertia"] as const).map(
     (field) =>
@@ -3093,6 +3779,13 @@ export const REQUIRED_FIELD_CORRECTIONS: ReadonlyMap<string, string> = new Map<s
     "resource.sound_data_options:member:data",
     "script_resource.cpp:CreateSoundData reads the data with CheckBufferOrString",
   ],
+  ...(["device_model", "manufacturer", "device_ident", "user_agent"] as const).map(
+    (field) =>
+      [
+        `sys.sys_info:member:${field}`,
+        'script_sys.cpp:Sys_GetSysInfo pushes it with lua_pushstring from a zero-filled char array (user_agent falls back to "")',
+      ] as const,
+  ),
 ]);
 
 // Mark the fields REQUIRED_FIELD_CORRECTIONS names for this slot required,
@@ -3594,6 +4287,58 @@ function groupFlattenedTableFields(fields: readonly TableField[]): TableField[]
   return grouped;
 }
 
+// A TYPEDEF whose aliased type the engine binding contradicts, replaced verbatim.
+// Member overrides reach only a STRUCT, and these alias inline LuaLS tables.
+// Each applies only while the typedef still aliases exactly its `upstream` tokens,
+// in order, so a changed upstream typedef is emitted as written rather than
+// shadowed; `typedef-correction-provenance.test.ts` pins every entry against the
+// retained ref-docs. Keyed by the typedef's ref-doc name.
+export interface TypedefAliasCorrection {
+  readonly upstream: readonly string[];
+  readonly ts: string;
+  readonly reason: string;
+}
+
+// One arm per shape a script can build, in upstream's order, each keyed by its
+// own shape-type constant.
+const BULLET3D_SHAPE_ARMS = [
+  ["SPHERE", "diameter: number"],
+  ["BOX", "dimensions: Vector3"],
+  ["CAPSULE", "diameter: number; height: number"],
+  ["HULL", "vertices: Vector3[]"],
+] as const;
+
+export const TYPEDEF_ALIAS_CORRECTIONS: ReadonlyMap<string, TypedefAliasCorrection> = new Map([
+  [
+    "render.render_target_params",
+    {
+      upstream: [
+        "{ type?:graphics.TEXTURE_TYPE, sample_count?:integer, [graphics.BUFFER_TYPE]:render.render_target_buffer_params }",
+      ],
+      ts: "{ type?: render.RenderTargetTextureType; sample_count?: number } & { [key: number]: render.render_target_buffer_params }",
+      reason:
+        'render_script.cpp:RenderScript_RenderTarget raises "Invalid render target texture type" on any `type` but graphics.TEXTURE_TYPE_2D and graphics.TEXTURE_TYPE_CUBE_MAP',
+    },
+  ],
+  [
+    "bullet3d.shape.definition",
+    {
+      upstream: [
+        "{ type:bullet3d.shape.SHAPE_TYPE, diameter:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, dimensions:vector3, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, diameter:number, height:number, position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+        "{ type:bullet3d.shape.SHAPE_TYPE, vertices:vector3[], position?:vector3, rotation?:quaternion, target_rotation?:quaternion }",
+      ],
+      ts: BULLET3D_SHAPE_ARMS.map(
+        ([kind, fields]) =>
+          `{ type: typeof bullet3d.shape.SHAPE_TYPE_${kind}; ${fields}; position?: Vector3; rotation?: Quaternion; target_rotation?: Quaternion }`,
+      ).join(" | "),
+      reason:
+        'script_bullet3d_shape.cpp:CheckBullet3DShapeDef reads only the fields of the table\'s own `type` and raises "Unsupported shape type" on any other, a mesh included',
+    },
+  ],
+]);
+
 // A handle the type map widens (`constant_buffer` takes named constants) keeps
 // that shape, so annotating with the alias loses nothing the handle-returning
 // function yields.
@@ -3610,8 +4355,19 @@ function typedefAlias(
 ): string {
   const brand = `Opaque<"${typedef.name}">`;
   const aliasOf = typedef.aliasOf ?? [];
+  const correction = TYPEDEF_ALIAS_CORRECTIONS.get(typedef.name);
+  if (
+    correction !== undefined &&
+    aliasOf.length === correction.upstream.length &&
+    aliasOf.every((token, i) => token === correction.upstream[i])
+  ) {
+    return `type ${local} = ${correction.ts};`;
+  }
   if (aliasOf.length > 0 && !isHandleAlias(aliasOf)) {
-    return `type ${local} = ${unionFromTokens(aliasOf, mapType)};`;
+    const armType: DefoldTypeMapper = DISCRIMINATED_MESSAGE_UNIONS.has(typedef.name)
+      ? (token, position) => discriminatedMessageArm(token) ?? mapType(token, position)
+      : mapType;
+    return `type ${local} = ${unionFromTokens(aliasOf, armType)};`;
   }
   const mapped = rawMapType(typedef.name);
   if (mapped.startsWith(brand)) return `type ${local} = ${mapped};`;
@@ -3642,6 +4398,7 @@ function collectTypeDeclarations(
   skip: ReadonlySet<string>,
   rawMapType: (token: string) => string,
   mapType: DefoldTypeMapper,
+  bindingEvidence: ReadonlySet<string>,
 ): TypeDeclaration[] {
   const prefix = `${module.namespace}.`;
   const out: TypeDeclaration[] = [];
@@ -3665,7 +4422,7 @@ function collectTypeDeclarations(
   for (const struct of module.structs ?? []) {
     const local = localOf(struct.name);
     if (local === null || skip.has(local)) continue;
-    out.push(structDeclaration(struct, local, mapType, module.structs ?? []));
+    out.push(structDeclaration(struct, local, mapType, module.structs ?? [], bindingEvidence));
   }
   return out;
 }
@@ -3718,10 +4475,22 @@ function structDeclaration(
   path: string,
   mapType: DefoldTypeMapper,
   structs: readonly ApiStruct[],
+  bindingEvidence: ReadonlySet<string>,
 ): TypeDeclaration {
   const name = path.slice(path.lastIndexOf(".") + 1);
   const memberPrefix = memberCorrectionKey(struct.name, "");
   const declared = new Set(struct.members.map((member) => member.name));
+  const redundant = [...STRUCT_MEMBER_ADDITIONS.keys()].filter(
+    (key) => key.startsWith(memberPrefix) && declared.has(key.slice(memberPrefix.length)),
+  );
+  if (redundant.length > 0) {
+    throw new Error(
+      `struct member addition names a declared member: ${redundant.sort().join(", ")}`,
+    );
+  }
+  const added = [...STRUCT_MEMBER_ADDITIONS]
+    .filter(([key]) => key.startsWith(memberPrefix) && bindingEvidence.has(key))
+    .map(([key, addition]) => ({ ...addition.member, name: key.slice(memberPrefix.length) }));
   const stale = [
     ...REQUIRED_FIELD_CORRECTIONS.keys(),
     ...LIST_FIELD_CORRECTIONS.keys(),
@@ -3731,7 +4500,7 @@ function structDeclaration(
   if (stale.length > 0) {
     throw new Error(`member-keyed field correction names no member: ${stale.sort().join(", ")}`);
   }
-  const members = struct.members.map((member) => {
+  const members = [...struct.members, ...added].map((member) => {
     const key = memberCorrectionKey(struct.name, member.name);
     const list = LIST_FIELD_CORRECTIONS.get(key);
     const retyped = TABLE_FIELD_TYPE_OVERRIDES.get(key);
@@ -3935,11 +4704,14 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   const knownConstantFqns = options?.knownConstantFqns;
   const translations = options?.translations ?? {};
   const urlParameters = options?.urlParameters ?? [];
+  const bindingEvidence = options?.bindingEvidence ?? new Set<string>();
+  const nilRaisingSlots = options?.nilRaisingSlots;
   const baseNotes = indexBaseNoteResolver(options?.indexBaseSource ?? "engine");
   const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
     new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
+    options?.withheldFunctions,
   );
 
   const constants = module.constants
@@ -3991,7 +4763,13 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   // A typedef that also has colon methods is emitted as a method-bearing
   // interface below, not an opaque brand alias.
   const typeDeclarations = placeTypeDeclarations(
-    collectTypeDeclarations(module, new Set(handleGroups.keys()), rawMapType, mapType),
+    collectTypeDeclarations(
+      module,
+      new Set(handleGroups.keys()),
+      rawMapType,
+      mapType,
+      bindingEvidence,
+    ),
     nestedRoot,
   );
 
@@ -4013,6 +4791,16 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   for (const aliasDecl of constantUnionAliasDeclarations(module.namespace)) {
     lines.push(`${INDENT}${decl}${aliasDecl}`);
   }
+  for (const aliasDecl of overloadSlotAliasDeclarations(
+    [...module.functions, ...(options?.withheldFunctions ?? [])],
+    prefix,
+    mapType,
+    constantTokens,
+    urlParameters,
+    bindingEvidence,
+  )) {
+    lines.push(`${INDENT}${decl}${aliasDecl}`);
+  }
   for (const alias of enumAliases.topLevel) {
     lines.push(
       `${INDENT}${decl}${unionAliasDeclaration(alias.name, alias.members, alias.nilable)}`,
@@ -4027,7 +4815,7 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
         lines.push(docLine);
       }
       lines.push(
-        `${handleIndent}${emitMethod(fn, mapType, resolver, constantTokens, urlParameters)}`,
+        `${handleIndent}${emitMethod(fn, mapType, resolver, constantTokens, urlParameters, bindingEvidence)}`,
       );
     }
     lines.push(`${INDENT}}`);
@@ -4056,10 +4844,20 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   for (const fn of functions) {
     const reserved = TS_RESERVED_NAMES.has(fn.name);
     const emitName = aliasName(fn.name, aliases);
-    for (const docLine of functionDocLines(fn.original, translations, baseNotes))
-      lines.push(docLine);
-    const line = emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters);
-    lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
+    for (const arm of callArms(fn, nilRaisingSlots, module.structs ?? [])) {
+      for (const docLine of functionDocLines(fn.original, translations, baseNotes))
+        lines.push(docLine);
+      const line = emitFunction(
+        arm,
+        emitName,
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+        bindingEvidence,
+      );
+      lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
+    }
     const alternative = firstSlotAlternative(fn, module.namespace);
     if (alternative !== null) {
       // The overload documents its own parameters, so its hover names the base
@@ -4074,6 +4872,7 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
         resolver,
         constantTokens,
         urlParameters,
+        bindingEvidence,
       );
       lines.push(`${INDENT}${reserved ? "" : decl}${overload}`);
     }
@@ -4148,7 +4947,7 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
           lines.push(docLine);
         }
         lines.push(
-          `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters)}`,
+          `${bodyIndent}${reserved ? "" : segmentDecl}${emitFunction(fn, emitName, mapType, resolver, constantTokens, urlParameters, bindingEvidence)}`,
         );
       }
       aliasReservedSegments(group.children.keys(), segmentAliases);
@@ -4179,6 +4978,55 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
   return `${lines.join("\n")}\n`;
 }
 
+// One `type <alias> = <slot type>;` per `OVERLOAD_SLOT_ALIASES` slot these
+// functions carry, in alias order. The type is the one `emitFunction` reports
+// for the slot, so it reads as the function's own signature would. The
+// resolver spans these functions alone, leaving the module's own untouched.
+function overloadSlotAliasDeclarations(
+  functions: readonly ApiFunction[],
+  prefix: string,
+  mapType: DefoldTypeMapper,
+  constantTokens: ConstantSlotTokens,
+  urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
+): string[] {
+  const resolver = buildTableDocResolver(
+    functions.map((fn) => ({ name: fn.name, slots: [...fn.parameters, ...fn.returnValues] })),
+  );
+  const types = new Map<string, string>();
+  for (const fn of functions) {
+    for (const [position, p] of fn.parameters.entries()) {
+      const alias = OVERLOAD_SLOT_ALIASES.get(tableSlotKey(fn.name, "param", p.name));
+      if (alias === undefined) continue;
+      const prepared = prepareFunction(fn, prefix);
+      if (prepared === null) continue;
+      const slots: Record<string, SlotType> = {};
+      emitFunction(
+        prepared,
+        prepared.name,
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+        bindingEvidence,
+        slots,
+      );
+      const slot = slots[slotKey("param", position, p.name)];
+      if (slot === undefined) {
+        throw new Error(`${fn.name} reports no type for its aliased slot "${p.name}"`);
+      }
+      const seen = types.get(alias);
+      if (seen !== undefined && seen !== slot.type) {
+        throw new Error(`${alias} is typed both ${seen} and ${slot.type}`);
+      }
+      types.set(alias, slot.type);
+    }
+  }
+  return [...types]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([alias, type]) => `type ${alias} = ${type};`);
+}
+
 /**
  * Every documented slot's rendered TS type and optionality, keyed
  * `param|return:<position>:<raw ref-doc name>`. The position is part of the key
@@ -4232,10 +5080,13 @@ export function emitSymbolSignatures(
   const constantsByFqn = new Map(module.constants.map((c) => [c.name, c]));
   const knownConstantFqns = options?.knownConstantFqns;
   const urlParameters = options?.urlParameters ?? [];
+  const bindingEvidence = options?.bindingEvidence ?? new Set<string>();
+  const nilRaisingSlots = options?.nilRaisingSlots;
   const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
     new Set([...constantsByFqn.keys(), ...(knownConstantFqns ?? [])]),
+    options?.withheldFunctions,
   );
   const resolver = buildTableDocResolver(
     module.functions.map((fn) => ({
@@ -4262,27 +5113,30 @@ export function emitSymbolSignatures(
     const prepared = prepareFunction(fn, prefix);
     if (prepared === null) continue;
     const slotTypes: Record<string, SlotType> = {};
+    const [first = prepared, ...later] = callArms(prepared, nilRaisingSlots, module.structs ?? []);
     const primary = emitFunction(
-      prepared,
+      first,
       emitName(prepared.name),
       mapType,
       resolver,
       constantTokens,
       urlParameters,
+      bindingEvidence,
       slotTypes,
     );
     const alternative = firstSlotAlternative(prepared, module.namespace);
-    const tsSignature =
-      alternative === null
-        ? primary
-        : `${primary}\n${emitFunction(
-            alternative,
-            emitName(prepared.name),
-            mapType,
-            resolver,
-            constantTokens,
-            urlParameters,
-          )}`;
+    const arms = [...later, ...(alternative === null ? [] : [alternative])].map((arm) =>
+      emitFunction(
+        arm,
+        emitName(prepared.name),
+        mapType,
+        resolver,
+        constantTokens,
+        urlParameters,
+        bindingEvidence,
+      ),
+    );
+    const tsSignature = [primary, ...arms].join("\n");
     out.push({ identity: fnIdentity(fn), tsSignature, slotTypes });
   }
 
@@ -4323,6 +5177,7 @@ export function emitSymbolSignatures(
         resolver,
         constantTokens,
         urlParameters,
+        bindingEvidence,
         slotTypes,
       ),
       slotTypes,
@@ -4341,6 +5196,7 @@ export function emitSymbolSignatures(
           resolver,
           constantTokens,
           urlParameters,
+          bindingEvidence,
           slotTypes,
         ),
         slotTypes,
@@ -4389,6 +5245,7 @@ export function emitSymbolSignatures(
     new Set(handleGroups.keys()),
     rawMapType,
     mapType,
+    bindingEvidence,
   )) {
     out.push({
       identity: {
@@ -4436,6 +5293,12 @@ interface PreparedConstant {
 interface PreparedFunction {
   name: string;
   original: ApiFunction;
+  // Parameter positions declared required whatever their doc says: the
+  // nil-raising slots an arm of `nilRaisingArms` takes.
+  required?: ReadonlySet<number>;
+  // A rewrite of the mapped type at a parameter position: the fields an arm of
+  // `presenceArms` requires.
+  retype?: ReadonlyMap<number, (type: string) => string>;
 }
 
 interface PreparedVariable {
@@ -4719,10 +5582,13 @@ export const NIL_CONSTANTS: ReadonlyMap<string, string> = new Map([
 // `undocumented-constant-provenance.test.ts` reds an entry no committed target
 // still needs. `sameValueAs` names the documented constant the engine registers
 // with the same value; where the surface declares it, the back-fill takes its
-// type, so a value compares equal to either spelling.
+// type, so a value compares equal to either spelling. `memberOf` names the
+// ref-doc `ENUM` the engine returns the constant through; the back-fill joins it
+// only on a surface whose ref-doc declares that enum, so an older surface
+// without one keeps a plain constant.
 export const UNDOCUMENTED_CONSTANTS: ReadonlyMap<
   string,
-  { readonly doc: string; readonly sameValueAs?: string }
+  { readonly doc: string; readonly sameValueAs?: string; readonly memberOf?: string }
 > = new Map([
   [
     "render.CONTEXT_EVENT_CONTEXT_LOST",
@@ -4743,6 +5609,13 @@ export const UNDOCUMENTED_CONSTANTS: ReadonlyMap<
       sameValueAs: "window.WINDOW_EVENT_ICONIFIED",
     },
   ],
+  [
+    "liveupdate.LIVEUPDATE_NOT_INITIALIZED",
+    {
+      doc: "Live update is not initialized. `liveupdate.add_mount` and `liveupdate.remove_mount` return it while live update is disabled.",
+      memberOf: "liveupdate.LIVEUPDATE",
+    },
+  ],
 ]);
 
 function withUndocumentedConstants(
@@ -4752,7 +5625,8 @@ function withUndocumentedConstants(
   const prefix = `${module.namespace}.`;
   const documented = new Set(module.constants.map((c) => c.name));
   const backfill: ApiConstant[] = [];
-  for (const [fqn, { doc, sameValueAs }] of UNDOCUMENTED_CONSTANTS) {
+  const joined = new Map<string, string[]>();
+  for (const [fqn, { doc, sameValueAs, memberOf }] of UNDOCUMENTED_CONSTANTS) {
     if (!fqn.startsWith(prefix) || fqn.slice(prefix.length).includes(".")) continue;
     if (documented.has(fqn)) continue;
     if (registered !== undefined && !registered.has(fqn)) continue;
@@ -4764,10 +5638,18 @@ function withUndocumentedConstants(
       description: "",
       ...(aliasOf === undefined ? {} : { aliasOf }),
     });
+    if (memberOf !== undefined) joined.set(memberOf, [...(joined.get(memberOf) ?? []), fqn]);
   }
-  return backfill.length === 0
-    ? module
-    : { ...module, constants: [...module.constants, ...backfill] };
+  if (backfill.length === 0) return module;
+  const enums = module.enums?.map((e) => {
+    const members = joined.get(e.name);
+    return members === undefined ? e : { ...e, members: [...e.members, ...members] };
+  });
+  return {
+    ...module,
+    constants: [...module.constants, ...backfill],
+    ...(enums === undefined ? {} : { enums }),
+  };
 }
 
 // `constant` is the module's own element for `fqn`, absent for a constant another
@@ -4846,14 +5728,30 @@ function memberSignature(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
   slotSink?: Record<string, SlotType>,
 ): string {
   const original = prepared.original.parameters;
   const elementName = prepared.original.name;
-  const cutoff = trailingOptionalCutoff(original, elementName);
+  const required = prepared.required ?? new Set<number>();
+  const cutoff = Math.max(
+    trailingOptionalCutoff(original, elementName),
+    ...[...required].map((index) => index + 1),
+  );
   const varargIndex = original.findIndex(isVarargParameter);
   const positional = (varargIndex === -1 ? original : original.slice(0, varargIndex)).map((p, i) =>
-    emitParameter(p, i, i >= cutoff, mapType, resolver, constantTokens, elementName, urlParameters),
+    emitParameter(
+      p,
+      i,
+      i >= cutoff,
+      mapType,
+      resolver,
+      constantTokens,
+      elementName,
+      urlParameters,
+      required.has(i),
+      prepared.retype?.get(i),
+    ),
   );
   const rest =
     varargIndex === -1
@@ -4874,6 +5772,7 @@ function memberSignature(
     resolver,
     constantTokens,
     elementName,
+    bindingEvidence,
   );
   const predicateToken = TYPE_PREDICATES.get(elementName);
   const soleParam = original[0];
@@ -4901,7 +5800,7 @@ function memberSignature(
   if (isPredicate && soleParam !== undefined && predicateToken !== undefined) {
     return `${name}(${params}): ${safeParamName(soleParam.name, 0)} is ${mapType(predicateToken)};`;
   }
-  return `${name}(${params}): ${ret.type};${ret.trailing}`;
+  return `${name}${box2dBackendTypeParameters(prepared.original)}(${params}): ${ret.type};${ret.trailing}`;
 }
 
 function emitFunction(
@@ -4911,9 +5810,10 @@ function emitFunction(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
   slotSink?: Record<string, SlotType>,
 ): string {
-  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters, slotSink)}`;
+  return `function ${memberSignature(prepared, name, mapType, resolver, constantTokens, urlParameters, bindingEvidence, slotSink)}`;
 }
 
 // A colon-method member of a handle interface: identical signature machinery to a
@@ -4925,6 +5825,7 @@ function emitMethod(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
   slotSink?: Record<string, SlotType>,
 ): string {
   return memberSignature(
@@ -4934,6 +5835,7 @@ function emitMethod(
     resolver,
     constantTokens,
     urlParameters,
+    bindingEvidence,
     slotSink,
   );
 }
@@ -4956,14 +5858,20 @@ function functionDocLines(
   baseNotes: IndexBaseNoteResolver,
   indent: string = INDENT,
 ): string[] {
-  const params = fn.parameters.map((p, index) => ({
-    name: emittedParamName(p, index),
-    doc: appendNotes(
-      translateProseFences(htmlToDocText(p.doc), fn.name, translations),
-      baseNotes(fn.name, "param", p.name),
-    ),
-  }));
+  const params = fn.parameters.map((p, index) => {
+    const curationNote = CALLBACK_SIGNATURE_CURATIONS.get(
+      tableSlotKey(fn.name, "param", p.name),
+    )?.note;
+    return {
+      name: emittedParamName(p, index),
+      doc: appendNotes(translateProseFences(htmlToDocText(p.doc), fn.name, translations), [
+        ...baseNotes(fn.name, "param", p.name),
+        ...(curationNote === undefined ? [] : [curationNote]),
+      ]),
+    };
+  });
   const onlyReturn = fn.returnValues.length === 1 ? fn.returnValues[0] : undefined;
+  const sparseNote = SPARSE_ARRAY_RETURNS.get(fn.name)?.note;
   const notedReturns =
     multiReturnDoc(fn, translations, baseNotes) ?? overrideReturnDoc(fn, baseNotes);
   const lua = htmlToCodeText(fn.examples ?? "");
@@ -4996,7 +5904,10 @@ function functionDocLines(
       ? {
           returns: appendNotes(
             translateProseFences(htmlToDocText(onlyReturn.doc), fn.name, translations),
-            baseNotes(fn.name, "return", onlyReturn.name),
+            [
+              ...baseNotes(fn.name, "return", onlyReturn.name),
+              ...(sparseNote === undefined ? [] : [sparseNote]),
+            ],
           ),
         }
       : notedReturns !== undefined
@@ -5258,27 +6169,43 @@ function emitParameter(
   constantTokens: ConstantSlotTokens,
   elementName: string,
   urlParameters: UrlParameterTable,
+  required = false,
+  retype: (type: string) => string = (type) => type,
 ): { text: string; type: string; optional: boolean } {
   const name = safeParamName(p.name, index);
-  const ts = parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters);
+  const ts = retype(
+    parameterType(p, mapType, resolver, constantTokens, elementName, urlParameters),
+  );
   // An interior doc-optional param (a required param follows, so the trailing-`?`
   // projection cannot mark it) keeps its optionality as `| undefined` — TSTL
   // lowers `undefined` to `nil`, the faithful call. Trailing optionals keep the
   // `?` form; required params are untouched.
   const nilRequired = requiredSlotCorrection(p, elementName)?.nil === true;
-  const interiorOptional = !optional && (isDocOptional(p, elementName) || nilRequired);
+  const interiorOptional = !optional && !required && (isDocOptional(p, elementName) || nilRequired);
   // `(a) => void | undefined` reads as a function returning `void | undefined`.
   const operand = interiorOptional && isFunctionTypeText(ts) ? `(${ts})` : ts;
   const type = `${operand}${interiorOptional ? " | undefined" : ""}`;
   return { text: `${name}${optional ? "?" : ""}: ${type}`, type, optional };
 }
 
+// A `nullable` correction rewrites only the `nil` in the declared tokens and
+// leaves the rest to the ordinary mapping and its top-level `nil` projection.
+function correctedReturnTokens(
+  types: readonly string[],
+  correction: ReturnTypeCorrection | undefined,
+): readonly string[] {
+  if (correction?.nullable === undefined) return types;
+  const base = types.filter((token) => token !== "nil");
+  return correction.nullable ? [...base, "nil"] : base;
+}
+
 function emitReturn(
   returnValues: ApiParameter[],
   mapType: DefoldTypeMapper,
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   elementName: string,
+  bindingEvidence: ReadonlySet<string>,
 ): { type: string; trailing: string; slots: EmittedSlot[] } {
   // An authored whole-return override is not a per-slot render, so it reports no
   // slots and leaves the consumer on its token-derived fallback.
@@ -5287,23 +6214,30 @@ function emitReturn(
   // Kept beside the override lookup so the two stay visibly distinct: this one
   // contradicts a declared token rather than filling an empty `returnvalues`,
   // and it is a per-slot render, so it reports its slot.
-  const correction = RETURN_TYPE_CORRECTIONS.get(elementName);
+  const listed = RETURN_TYPE_CORRECTIONS.get(elementName);
+  const correction =
+    listed?.binding === undefined || bindingEvidence.has(elementName) ? listed : undefined;
   if (returnValues.length === 0) return { type: "void", trailing: "", slots: [] };
   if (returnValues.length > 1) {
     // Defold multi-returns are positional and always present; each slot maps
     // straight through (unknown when the doc lists no type) into a tuple that
     // typescript-to-lua erases to `local a, b = fn()`.
-    const emitted = returnValues.map((rv, index) => ({
-      position: index,
-      name: rv.name,
-      ts:
+    const emitted = returnValues.map((rv, index) => {
+      const applied =
         correction?.slot !== undefined &&
         correction.slot === rv.name &&
         pinMatches(rv.types, correctionPins(correction))
-          ? correction.ts
-          : rv.types.length > 0
+          ? correction
+          : undefined;
+      const types = correctedReturnTokens(rv.types, applied);
+      return {
+        position: index,
+        name: rv.name,
+        ts:
+          applied?.ts ??
+          (types.length > 0
             ? mapSlotUnion(
-                rv.types,
+                types,
                 rv.doc,
                 mapType,
                 false,
@@ -5313,8 +6247,9 @@ function emitReturn(
                 "return",
                 rv.name,
               )
-            : "unknown",
-    }));
+            : "unknown"),
+      };
+    });
     return {
       type: `LuaMultiReturn<[${emitted.map((slot) => slot.ts).join(", ")}]>`,
       trailing: "",
@@ -5323,21 +6258,24 @@ function emitReturn(
   }
   const first = returnValues[0];
   if (!first) return { type: "void", trailing: "", slots: [] };
-  if (
+  const applied =
     correction !== undefined &&
     correction.slot === undefined &&
     pinMatches(first.types, correctionPins(correction))
-  ) {
+      ? correction
+      : undefined;
+  if (applied?.ts !== undefined) {
     return {
-      type: correction.ts,
+      type: applied.ts,
       trailing: "",
-      slots: [{ position: 0, name: first.name, ts: correction.ts }],
+      slots: [{ position: 0, name: first.name, ts: applied.ts }],
     };
   }
+  const types = correctedReturnTokens(first.types, applied);
   const ts =
-    first.types.length > 0
+    types.length > 0
       ? mapSlotUnion(
-          first.types,
+          types,
           first.doc,
           mapType,
           false,
@@ -5361,6 +6299,26 @@ function emitReturn(
 // only".
 const READ_ONLY_MARK = /^\s*<span class="mark">READ ONLY<\/span>/;
 
+// A property the engine reads but refuses to write while upstream omits the
+// READ ONLY mark. `evidence` names the component source that shows the missing
+// write branch. The emit throws once upstream adds the mark, so the entry is
+// deleted rather than outliving the defect it corrects.
+export interface ReadOnlyPropertyCorrection {
+  readonly evidence: string;
+}
+
+// Keyed `<namespace>.<property>`, mirroring PROPERTY_TYPE_CORRECTIONS.
+export const READ_ONLY_PROPERTY_CORRECTIONS: ReadonlyMap<string, ReadOnlyPropertyCorrection> =
+  new Map([
+    [
+      "model.animation",
+      {
+        evidence:
+          "comp_model.cpp:CompModelSetProperty has no animation branch, so the write falls through to the material-constant lookup and fails",
+      },
+    ],
+  ]);
+
 function emitPropertyMembers(
   p: ApiProperty,
   mapType: DefoldTypeMapper,
@@ -5381,10 +6339,59 @@ function emitPropertyMembers(
       : p.types.length > 0
         ? unionFromTokens(p.types, mapType)
         : "unknown";
-  const modifier = READ_ONLY_MARK.test(p.description) ? "readonly " : "";
+  const marked = READ_ONLY_MARK.test(p.description);
+  const readOnlyCorrected = READ_ONLY_PROPERTY_CORRECTIONS.has(`${namespace}.${p.name}`);
+  if (marked && readOnlyCorrected) {
+    throw new Error(
+      `read-only property correction ${namespace}.${p.name}: upstream marks the property READ ONLY`,
+    );
+  }
+  const modifier = marked || readOnlyCorrected ? "readonly " : "";
   return keys.map((key) => `${modifier}${key}: ${ts};`);
 }
 
+// A function whose returned table the engine binding keys by a sparse integer,
+// so the sequence its reference declares is a map with holes: `ipairs` stops at
+// the first hole, and `#t` may return any border. Keyed by function name, since the return slot is named
+// `table` in 1.13.0/1.13.1 and `textures` from 1.13.2. The return's `T[]` member
+// emits as `LuaMap<number, T>`, which `for...of` lowers to `pairs`, and `note`
+// joins its `@returns`.
+export const SPARSE_ARRAY_RETURNS: ReadonlyMap<string, { note: string; reason: string }> = new Map([
+  [
+    "material.get_textures",
+    {
+      note: "Keyed by sampler slot from 1; a slot with no texture has no entry, so iterate with `for (const [slot, info] of textures)`.",
+      reason:
+        "script_material.cpp:Material_GetTextures pushes key i+1 only for a slot that has a texture, unlike Compute_GetTextures, which packs its keys",
+    },
+  ],
+]);
+
+function sparseArrayMap(ts: string, elementName: string): string {
+  const members = unionMembers(ts);
+  const arrays = members.filter((member) => member.endsWith("[]"));
+  if (arrays.length === 0) {
+    throw new Error(`SPARSE_ARRAY_RETURNS ${elementName}: the return emits no array (${ts})`);
+  }
+  return members
+    .map((member) => {
+      if (!member.endsWith("[]")) return member;
+      const element = member.slice(0, -2);
+      return `LuaMap<number, ${wrappedInParens(element) ? element.slice(1, -1) : element}>`;
+    })
+    .join(" | ");
+}
+
+function wrappedInParens(text: string): boolean {
+  if (!text.startsWith("(")) return false;
+  let depth = 0;
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] === "(") depth++;
+    else if (text[i] === ")" && --depth === 0) return i === text.length - 1;
+  }
+  return false;
+}
+
 // Like `unionFromTokens`, but a `table` token whose slot doc carries a parseable
 // `<dl>` field list emits an inline object type instead of the opaque `Record`
 // fallback. Other tokens in the union map unchanged. `optionalFields` marks the
@@ -5465,6 +6472,10 @@ function mapSlotUnion(
         }
       } else if (element !== undefined) {
         ts = arrayTypeFromTokens(element, mapType);
+        if (curation?.kind === "array" && curation.pairs === true) {
+          const tokens = typeof element === "string" ? [element] : element;
+          ts = `${ts} | LuaPairsIterable<AnyNotNil, ${unionFromTokens(tokens, mapType)}>`;
+        }
       } else if (curation?.kind === "verbatim") {
         ts = curation.ts;
       } else if (curation?.kind === "object" || curation?.kind === "array-object") {
@@ -5521,19 +6532,27 @@ function mapSlotUnion(
       // return slots.
       ts = "undefined";
     } else {
-      const curated =
+      const curation =
         slotKind !== undefined && slotName !== undefined
           ? CALLBACK_SIGNATURE_CURATIONS.get(tableSlotKey(elementName, slotKind, slotName))
           : undefined;
-      ts = curated ?? mapType(token);
+      if (curation === undefined) {
+        ts = mapType(token);
+      } else if (isLualsFunctionToken(token)) {
+        ts = curation.typed ?? mapType(token);
+      } else {
+        ts = curation.untyped;
+      }
     }
     push(ts);
   }
   // A genuine `unknown` member (an `any` slot, including `any | nil`) absorbs
   // every other union member, so collapse to exactly `unknown` rather than emit
   // a redundant `T | unknown` or `unknown | undefined`.
-  if (mapped.includes("unknown")) return "unknown";
-  return joinUnionArms(mapped);
+  const joined = mapped.includes("unknown") ? "unknown" : joinUnionArms(mapped);
+  return slotKind === "return" && SPARSE_ARRAY_RETURNS.has(elementName)
+    ? sparseArrayMap(joined, elementName)
+    : joined;
 }
 
 function tableSlotKey(elementName: string, slotKind: "param" | "return", slotName: string): string {
@@ -5690,7 +6709,7 @@ function joinUnionArms(mapped: readonly string[]): string {
 }
 
 const BUILTIN_MESSAGE_NAMES: ReadonlySet<string> = new Set(
-  messagesDoc.messages.map((message) => message.name),
+  applyMessageOverlays(parseMessagesDoc(messagesDoc)).entries.map((entry) => entry.name),
 );
 const MESSAGE_REFERENCE = /^message\.[a-z_]+\.([a-z_]+)$/;
 
@@ -5706,6 +6725,18 @@ function resolveDefoldLeaf(leaf: string): string | undefined {
   return undefined;
 }
 
+// The union typedefs whose message arms each carry the engine's message-name
+// hash in `type`: script_physics.cpp sets it on every `physics.set_event_listener`
+// event. The same message referenced anywhere else (`physics.raycast`) has none.
+const DISCRIMINATED_MESSAGE_UNIONS: ReadonlySet<string> = new Set(["physics.event"]);
+
+function discriminatedMessageArm(token: string): string | undefined {
+  const name = MESSAGE_REFERENCE.exec(token)?.[1];
+  const payload = resolveDefoldLeaf(token);
+  if (name === undefined || payload === undefined) return undefined;
+  return `${payload} & { type: Hash<"${name}"> }`;
+}
+
 // Whole-token lookup and callback recovery run first, so the grammar sees only
 // what they miss; every pre-1.13.2 token resolves before it is reached.
 function wholeTokenMapping(token: string): string | undefined {