@defold-typescript/types 0.50.0 → 0.51.0

package/src/emit-dts.ts

@@ -21,6 +21,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 +31,12 @@ import {
   indexBaseNoteResolver,
   OVERRIDE_RETURN_SLOT,
 } from "./index-slot-classifications";
-import { type LualsPosition, mapLualsExpression, needsArrayParens } from "./luals-type-expr";
+import {
+  isLualsFunctionToken,
+  type LualsPosition,
+  mapLualsExpression,
+  needsArrayParens,
+} from "./luals-type-expr";
 import { classifyUrlParameter, type UrlParameterTable } from "./url-parameters";
 
 export { summaryFor };
@@ -75,6 +81,14 @@ 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 functions a target's skip rules removed from the module, read only to
+  // type an `OVERLOAD_SLOT_ALIASES` slot.
+  withheldFunctions?: readonly ApiFunction[];
 }
 
 export const TS_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -362,8 +376,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 +399,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",
     {
@@ -439,6 +490,147 @@ 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"),
+    },
+  ],
+  [
+    "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
@@ -1553,6 +1745,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;
 
@@ -2267,10 +2466,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 +2483,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 +2905,103 @@ 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.
+// `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 }) => 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,
+    },
   ],
 ]);
 
@@ -2899,32 +3162,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 +3219,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 +3246,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 +3382,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,
@@ -3611,7 +3907,10 @@ function typedefAlias(
   const brand = `Opaque<"${typedef.name}">`;
   const aliasOf = typedef.aliasOf ?? [];
   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 +3941,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 +3965,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 +4018,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 +4043,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,6 +4247,7 @@ 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 baseNotes = indexBaseNoteResolver(options?.indexBaseSource ?? "engine");
   const { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
@@ -3991,7 +4304,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 +4332,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 +4356,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}}`);
@@ -4058,7 +4387,15 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
     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);
+    const line = emitFunction(
+      fn,
+      emitName,
+      mapType,
+      resolver,
+      constantTokens,
+      urlParameters,
+      bindingEvidence,
+    );
     lines.push(`${INDENT}${reserved ? "" : decl}${line}`);
     const alternative = firstSlotAlternative(fn, module.namespace);
     if (alternative !== null) {
@@ -4074,6 +4411,7 @@ export function emitDeclarations(documented: ApiModule, options?: EmitOptions):
         resolver,
         constantTokens,
         urlParameters,
+        bindingEvidence,
       );
       lines.push(`${INDENT}${reserved ? "" : decl}${overload}`);
     }
@@ -4148,7 +4486,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 +4517,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,6 +4619,7 @@ 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 { rawMapType, mapType } = moduleTypeMappers(module, constantsByFqn, options);
   const constantTokens = constantSlotTokenResolver(
     module,
@@ -4269,6 +4657,7 @@ export function emitSymbolSignatures(
       resolver,
       constantTokens,
       urlParameters,
+      bindingEvidence,
       slotTypes,
     );
     const alternative = firstSlotAlternative(prepared, module.namespace);
@@ -4282,6 +4671,7 @@ export function emitSymbolSignatures(
             resolver,
             constantTokens,
             urlParameters,
+            bindingEvidence,
           )}`;
     out.push({ identity: fnIdentity(fn), tsSignature, slotTypes });
   }
@@ -4323,6 +4713,7 @@ export function emitSymbolSignatures(
         resolver,
         constantTokens,
         urlParameters,
+        bindingEvidence,
         slotTypes,
       ),
       slotTypes,
@@ -4341,6 +4732,7 @@ export function emitSymbolSignatures(
           resolver,
           constantTokens,
           urlParameters,
+          bindingEvidence,
           slotTypes,
         ),
         slotTypes,
@@ -4389,6 +4781,7 @@ export function emitSymbolSignatures(
     new Set(handleGroups.keys()),
     rawMapType,
     mapType,
+    bindingEvidence,
   )) {
     out.push({
       identity: {
@@ -4846,6 +5239,7 @@ function memberSignature(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
   slotSink?: Record<string, SlotType>,
 ): string {
   const original = prepared.original.parameters;
@@ -4874,6 +5268,7 @@ function memberSignature(
     resolver,
     constantTokens,
     elementName,
+    bindingEvidence,
   );
   const predicateToken = TYPE_PREDICATES.get(elementName);
   const soleParam = original[0];
@@ -4911,9 +5306,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 +5321,7 @@ function emitMethod(
   resolver: TableDocResolver,
   constantTokens: ConstantSlotTokens,
   urlParameters: UrlParameterTable,
+  bindingEvidence: ReadonlySet<string>,
   slotSink?: Record<string, SlotType>,
 ): string {
   return memberSignature(
@@ -4934,6 +5331,7 @@ function emitMethod(
     resolver,
     constantTokens,
     urlParameters,
+    bindingEvidence,
     slotSink,
   );
 }
@@ -4956,13 +5354,18 @@ 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 notedReturns =
     multiReturnDoc(fn, translations, baseNotes) ?? overrideReturnDoc(fn, baseNotes);
@@ -5273,12 +5676,24 @@ function emitParameter(
   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 +5702,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 +5735,9 @@ function emitReturn(
                 "return",
                 rv.name,
               )
-            : "unknown",
-    }));
+            : "unknown"),
+      };
+    });
     return {
       type: `LuaMultiReturn<[${emitted.map((slot) => slot.ts).join(", ")}]>`,
       trailing: "",
@@ -5323,21 +5746,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 +5787,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,7 +5827,14 @@ 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};`);
 }
 
@@ -5521,11 +5974,17 @@ 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);
   }
@@ -5690,7 +6149,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 +6165,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 {