@tsonic/frontend 0.0.14 → 0.0.16

package/dist/ir/binding/index.js

@@ -0,0 +1,1035 @@
+/**
+ * Binding Layer — TS Symbol Resolution with Opaque Handles
+ *
+ * This module wraps TypeScript's symbol resolution APIs and returns opaque
+ * handles (DeclId, SignatureId, MemberId) instead of ts.Symbol/ts.Signature.
+ *
+ * ALLOWED APIs (symbol resolution only):
+ * - checker.getSymbolAtLocation(node) — Find symbol at AST node
+ * - checker.getAliasedSymbol(symbol) — Resolve import alias
+ * - checker.getExportSymbolOfSymbol(symbol) — Resolve export
+ * - symbol.getDeclarations() — Get AST declaration nodes
+ * - checker.getResolvedSignature(call) — Pick overload (type from declaration)
+ *
+ * BANNED APIs (these produce ts.Type, which violates INV-0):
+ * - checker.getTypeAtLocation
+ * - checker.getTypeOfSymbolAtLocation
+ * - checker.getContextualType
+ * - checker.typeToTypeNode
+ */
+import ts from "typescript";
+import { makeDeclId, makeSignatureId, makeMemberId, makeTypeSyntaxId, } from "../type-system/types.js";
+// ═══════════════════════════════════════════════════════════════════════════
+// BINDING IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Create a Binding instance for a TypeScript program.
+ *
+ * Returns BindingInternal which includes _getHandleRegistry() for TypeSystem.
+ * Cast to Binding when passing to regular converters.
+ */
+export const createBinding = (checker) => {
+    // Internal registries mapping handles to underlying TS objects
+    const declMap = new Map();
+    const signatureMap = new Map();
+    const memberMap = new Map(); // key: "declId:name"
+    const typeSyntaxMap = new Map(); // TypeSyntaxId → TypeNode
+    // Auto-increment IDs
+    const nextDeclId = { value: 0 };
+    const nextSignatureId = { value: 0 };
+    const nextTypeSyntaxId = { value: 0 };
+    // Symbol to DeclId cache (avoid duplicate DeclIds for same symbol)
+    const symbolToDeclId = new Map();
+    const signatureToId = new Map();
+    // ─────────────────────────────────────────────────────────────────────────
+    // INTERNAL HELPERS
+    // ─────────────────────────────────────────────────────────────────────────
+    const getOrCreateDeclId = (symbol) => {
+        const existing = symbolToDeclId.get(symbol);
+        if (existing)
+            return existing;
+        const id = makeDeclId(nextDeclId.value++);
+        symbolToDeclId.set(symbol, id);
+        // Get declaration info.
+        //
+        // IMPORTANT:
+        // Some symbols (notably tsbindgen facades) intentionally merge a value export
+        // and a type export under the same name, e.g.:
+        //   export const Task: typeof Internal.Task;
+        //   export type Task<T1 = __> = ... Internal.Task_1<T1> ...
+        //
+        // For expression identifiers we want the value declaration, while for type
+        // references we must be able to access the type declaration. We capture both.
+        const decls = symbol.getDeclarations() ?? [];
+        const valueDecl = decls.find((d) => ts.isVariableDeclaration(d) ||
+            ts.isFunctionDeclaration(d) ||
+            ts.isParameter(d) ||
+            ts.isPropertyDeclaration(d) ||
+            ts.isPropertySignature(d) ||
+            ts.isMethodDeclaration(d) ||
+            ts.isMethodSignature(d));
+        const typeDecl = decls.find((d) => ts.isTypeAliasDeclaration(d) ||
+            ts.isInterfaceDeclaration(d) ||
+            ts.isClassDeclaration(d) ||
+            ts.isEnumDeclaration(d) ||
+            ts.isTypeParameterDeclaration(d));
+        const decl = valueDecl ?? typeDecl ?? decls[0];
+        // Capture class member names for override detection (TS-version safe)
+        const classMemberNames = decl && ts.isClassDeclaration(decl)
+            ? extractClassMemberNames(decl)
+            : undefined;
+        const entry = {
+            symbol,
+            decl,
+            typeDeclNode: typeDecl,
+            valueDeclNode: valueDecl,
+            typeNode: decl ? getTypeNodeFromDeclaration(decl) : undefined,
+            kind: decl ? getDeclKind(decl) : "variable",
+            fqName: symbol.getName(),
+            classMemberNames,
+        };
+        declMap.set(id.id, entry);
+        return id;
+    };
+    const getOrCreateSignatureId = (signature) => {
+        const existing = signatureToId.get(signature);
+        if (existing)
+            return existing;
+        const id = makeSignatureId(nextSignatureId.value++);
+        signatureToId.set(signature, id);
+        // Extract signature info from declaration
+        const decl = signature.getDeclaration();
+        // Extract declaring identity (CRITICAL for Alice's spec: resolveCall needs this)
+        const declaringIdentity = extractDeclaringIdentity(decl, checker);
+        // Extract type predicate from return type (ALICE'S SPEC: pure syntax inspection)
+        const returnTypeNode = getReturnTypeNode(decl);
+        const typePredicate = extractTypePredicate(returnTypeNode, decl);
+        const entry = {
+            signature,
+            decl,
+            parameters: extractParameterNodes(decl),
+            returnTypeNode,
+            typeParameters: extractTypeParameterNodes(decl),
+            declaringTypeTsName: declaringIdentity?.typeTsName,
+            declaringMemberName: declaringIdentity?.memberName,
+            typePredicate,
+        };
+        signatureMap.set(id.id, entry);
+        return id;
+    };
+    const getOrCreateMemberId = (ownerDeclId, memberName, memberSymbol) => {
+        const key = `${ownerDeclId.id}:${memberName}`;
+        const existing = memberMap.get(key);
+        if (existing)
+            return existing.memberId;
+        const id = makeMemberId(ownerDeclId, memberName);
+        const decl = memberSymbol.getDeclarations()?.[0];
+        const entry = {
+            memberId: id,
+            symbol: memberSymbol,
+            decl,
+            name: memberName,
+            typeNode: decl ? getMemberTypeAnnotation(decl) : undefined,
+            isOptional: isOptionalMember(memberSymbol),
+            isReadonly: isReadonlyMember(decl),
+        };
+        memberMap.set(key, entry);
+        return id;
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // BINDING IMPLEMENTATION
+    // ─────────────────────────────────────────────────────────────────────────
+    const resolveIdentifier = (node) => {
+        const symbol = checker.getSymbolAtLocation(node);
+        if (!symbol)
+            return undefined;
+        // Follow aliases for imports
+        const resolvedSymbol = symbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(symbol)
+            : symbol;
+        return getOrCreateDeclId(resolvedSymbol);
+    };
+    const resolveTypeReference = (node) => {
+        const typeName = node.typeName;
+        const symbol = ts.isIdentifier(typeName)
+            ? checker.getSymbolAtLocation(typeName)
+            : checker.getSymbolAtLocation(typeName.right);
+        if (!symbol)
+            return undefined;
+        // Follow aliases
+        const resolvedSymbol = symbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(symbol)
+            : symbol;
+        return getOrCreateDeclId(resolvedSymbol);
+    };
+    const resolvePropertyAccess = (node) => {
+        const rawPropSymbol = checker.getSymbolAtLocation(node.name);
+        if (!rawPropSymbol)
+            return undefined;
+        const propSymbol = rawPropSymbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(rawPropSymbol)
+            : rawPropSymbol;
+        // Get owner type's declaration
+        const rawOwnerSymbol = checker.getSymbolAtLocation(node.expression);
+        // Note: `getSymbolAtLocation(node.expression)` can be undefined for receivers
+        // that are not identifiers/member-accesses (e.g., `xs.where(...).select`).
+        // In that case we still want a stable MemberId for the member symbol itself,
+        // so we key the member entry off the member symbol's own DeclId.
+        const ownerSymbol = rawOwnerSymbol
+            ? rawOwnerSymbol.flags & ts.SymbolFlags.Alias
+                ? checker.getAliasedSymbol(rawOwnerSymbol)
+                : rawOwnerSymbol
+            : undefined;
+        const ownerDeclId = getOrCreateDeclId(ownerSymbol ?? propSymbol);
+        return getOrCreateMemberId(ownerDeclId, node.name.text, propSymbol);
+    };
+    const resolveElementAccess = (_node) => {
+        // Element access member resolution requires type-level analysis
+        // Return undefined (member not resolved via handles)
+        return undefined;
+    };
+    const resolveCallSignature = (node) => {
+        const signature = checker.getResolvedSignature(node);
+        if (!signature)
+            return undefined;
+        // TypeScript can produce a resolved signature without a declaration for
+        // implicit default constructors (e.g., `super()` when the base class has
+        // no explicit constructor). We still want a SignatureId so TypeSystem can
+        // treat this call deterministically as `void`.
+        if (signature.declaration === undefined) {
+            // Special case: `super()` implicit base constructor
+            if (node.expression.kind === ts.SyntaxKind.SuperKeyword) {
+                return getOrCreateSignatureId(signature);
+            }
+            // Recovery: calls through variables/properties typed as functions can
+            // yield signatures without declarations. Attempt to re-anchor to a
+            // function-like declaration we can capture syntactically.
+            const symbol = (() => {
+                const expr = node.expression;
+                if (ts.isIdentifier(expr))
+                    return checker.getSymbolAtLocation(expr);
+                if (ts.isPropertyAccessExpression(expr)) {
+                    return checker.getSymbolAtLocation(expr.name);
+                }
+                return undefined;
+            })();
+            const resolvedSymbol = symbol && symbol.flags & ts.SymbolFlags.Alias
+                ? checker.getAliasedSymbol(symbol)
+                : symbol;
+            const decls = resolvedSymbol?.getDeclarations() ?? [];
+            for (const decl of decls) {
+                // Direct function-like declarations (function/method/signature)
+                if (ts.isFunctionLike(decl)) {
+                    const sig = checker.getSignatureFromDeclaration(decl);
+                    if (sig)
+                        return getOrCreateSignatureId(sig);
+                    continue;
+                }
+                // Variable initializers: const f = (x) => ...
+                if (ts.isVariableDeclaration(decl)) {
+                    const init = decl.initializer;
+                    if (init && (ts.isArrowFunction(init) || ts.isFunctionExpression(init))) {
+                        const sig = checker.getSignatureFromDeclaration(init);
+                        if (sig)
+                            return getOrCreateSignatureId(sig);
+                    }
+                }
+            }
+            return undefined;
+        }
+        const resolvedId = getOrCreateSignatureId(signature);
+        // Airplane-grade overload selection for erased TS types:
+        // In TypeScript, `char` is `string`, so overload sets that differ only by
+        // `char` vs `string` can be resolved "wrong" due to declaration order
+        // (e.g., string.split("/") picking the `char` overload).
+        //
+        // We apply a deterministic, syntax-driven tie-breaker:
+        // - Prefer `string` parameters for non-charish arguments (string literals, etc.)
+        // - Prefer `char` parameters only when the argument is explicitly marked char
+        //   (e.g., `expr as char`, or identifier declared `: char`).
+        const candidates = resolveCallSignatureCandidates(node);
+        if (!candidates || candidates.length < 2)
+            return resolvedId;
+        const stripParens = (expr) => {
+            let current = expr;
+            while (ts.isParenthesizedExpression(current)) {
+                current = current.expression;
+            }
+            return current;
+        };
+        const isCharTypeNode = (typeNode) => {
+            if (ts.isTypeReferenceNode(typeNode)) {
+                const tn = typeNode.typeName;
+                if (ts.isIdentifier(tn))
+                    return tn.text === "char";
+                return tn.right.text === "char";
+            }
+            return false;
+        };
+        const isCharishArgument = (arg) => {
+            const expr = stripParens(arg);
+            // Explicit `as char` / `<char>` assertions.
+            if (ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr)) {
+                return isCharTypeNode(expr.type);
+            }
+            // Identifier declared with `: char`.
+            if (ts.isIdentifier(expr)) {
+                const sym = checker.getSymbolAtLocation(expr);
+                if (!sym)
+                    return false;
+                const resolvedSym = sym.flags & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(sym) : sym;
+                const decls = resolvedSym.getDeclarations() ?? [];
+                for (const decl of decls) {
+                    const typeNode = getTypeNodeFromDeclaration(decl);
+                    if (typeNode && isCharTypeNode(typeNode))
+                        return true;
+                }
+            }
+            return false;
+        };
+        const prefersStringOverChar = (arg) => {
+            const expr = stripParens(arg);
+            if (isCharishArgument(expr))
+                return false;
+            return ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr);
+        };
+        const classifyParamTypeNode = (typeNode) => {
+            if (!typeNode)
+                return "other";
+            const node = typeNode;
+            if (node.kind === ts.SyntaxKind.StringKeyword)
+                return "string";
+            if (isCharTypeNode(node))
+                return "char";
+            if (ts.isArrayTypeNode(node)) {
+                return isCharTypeNode(node.elementType) ? "char" : "other";
+            }
+            return "other";
+        };
+        const paramClassForArgIndex = (entry, argIndex) => {
+            const params = entry.parameters;
+            const direct = params[argIndex];
+            if (direct)
+                return classifyParamTypeNode(direct.typeNode);
+            // Rest parameter: map extra args to last param if it is rest.
+            const last = params[params.length - 1];
+            if (last && last.isRest)
+                return classifyParamTypeNode(last.typeNode);
+            return "other";
+        };
+        const args = node.arguments;
+        const wantsStringAt = [];
+        const wantsCharAt = [];
+        for (let i = 0; i < args.length; i++) {
+            const arg = args[i];
+            if (!arg)
+                continue;
+            if (ts.isSpreadElement(arg))
+                continue;
+            if (isCharishArgument(arg)) {
+                wantsCharAt.push(i);
+            }
+            else if (prefersStringOverChar(arg)) {
+                wantsStringAt.push(i);
+            }
+        }
+        if (wantsStringAt.length === 0 && wantsCharAt.length === 0)
+            return resolvedId;
+        const scoreSignature = (sigId) => {
+            const entry = signatureMap.get(sigId.id);
+            if (!entry)
+                return 0;
+            let score = 0;
+            for (const i of wantsStringAt) {
+                const pc = paramClassForArgIndex(entry, i);
+                if (pc === "string")
+                    score += 2;
+                if (pc === "char")
+                    score -= 2;
+            }
+            for (const i of wantsCharAt) {
+                const pc = paramClassForArgIndex(entry, i);
+                if (pc === "char")
+                    score += 2;
+                if (pc === "string")
+                    score -= 2;
+            }
+            return score;
+        };
+        const resolvedScore = scoreSignature(resolvedId);
+        let bestId = resolvedId;
+        let bestScore = resolvedScore;
+        for (const candidate of candidates) {
+            const s = scoreSignature(candidate);
+            if (s > bestScore) {
+                bestScore = s;
+                bestId = candidate;
+            }
+        }
+        return bestId;
+    };
+    const resolveCallSignatureCandidates = (node) => {
+        const expr = node.expression;
+        const symbol = (() => {
+            if (ts.isIdentifier(expr))
+                return checker.getSymbolAtLocation(expr);
+            if (ts.isPropertyAccessExpression(expr)) {
+                return checker.getSymbolAtLocation(expr.name);
+            }
+            return undefined;
+        })();
+        if (!symbol)
+            return undefined;
+        const resolvedSymbol = symbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(symbol)
+            : symbol;
+        const decls = resolvedSymbol.getDeclarations();
+        if (!decls || decls.length === 0)
+            return undefined;
+        const argCount = node.arguments.length;
+        const candidates = [];
+        for (const decl of decls) {
+            if (!ts.isFunctionLike(decl))
+                continue;
+            // Exclude construct signatures / constructors for call expressions.
+            if (ts.isConstructSignatureDeclaration(decl) || ts.isConstructorDeclaration(decl)) {
+                continue;
+            }
+            // Arity filtering (optional/rest aware)
+            const params = extractParameterNodes(decl);
+            const required = params.filter((p) => !p.isOptional && !p.isRest).length;
+            const hasRest = params.some((p) => p.isRest);
+            if (argCount < required)
+                continue;
+            if (!hasRest && argCount > params.length)
+                continue;
+            const sig = checker.getSignatureFromDeclaration(decl);
+            if (!sig)
+                continue;
+            candidates.push(getOrCreateSignatureId(sig));
+        }
+        return candidates.length > 0 ? candidates : undefined;
+    };
+    const resolveConstructorSignature = (node) => {
+        const signature = checker.getResolvedSignature(node);
+        if (!signature)
+            return undefined;
+        const sigId = getOrCreateSignatureId(signature);
+        // For implicit default constructors, TypeScript may return a signature with no declaration.
+        // We still need a SignatureEntry that identifies the constructed type so TypeSystem can
+        // synthesize the constructor return type deterministically.
+        const entry = signatureMap.get(sigId.id);
+        if (entry && !entry.decl) {
+            const expr = node.expression;
+            const symbol = (() => {
+                if (ts.isIdentifier(expr))
+                    return checker.getSymbolAtLocation(expr);
+                if (ts.isPropertyAccessExpression(expr)) {
+                    return checker.getSymbolAtLocation(expr.name);
+                }
+                return undefined;
+            })();
+            const resolvedSymbol = symbol && symbol.flags & ts.SymbolFlags.Alias
+                ? checker.getAliasedSymbol(symbol)
+                : symbol;
+            const decl = resolvedSymbol?.getDeclarations()?.[0];
+            const declaringTypeTsName = (() => {
+                if (decl && ts.isClassDeclaration(decl) && decl.name)
+                    return decl.name.text;
+                if (resolvedSymbol)
+                    return resolvedSymbol.getName();
+                if (ts.isIdentifier(expr))
+                    return expr.text;
+                if (ts.isPropertyAccessExpression(expr))
+                    return expr.name.text;
+                return undefined;
+            })();
+            if (declaringTypeTsName) {
+                signatureMap.set(sigId.id, {
+                    ...entry,
+                    declaringTypeTsName,
+                    declaringMemberName: "constructor",
+                    typeParameters: decl && ts.isClassDeclaration(decl)
+                        ? convertTypeParameterDeclarations(decl.typeParameters)
+                        : undefined,
+                });
+            }
+        }
+        return sigId;
+    };
+    const resolveConstructorSignatureCandidates = (node) => {
+        const expr = node.expression;
+        const symbol = (() => {
+            if (ts.isIdentifier(expr))
+                return checker.getSymbolAtLocation(expr);
+            if (ts.isPropertyAccessExpression(expr)) {
+                return checker.getSymbolAtLocation(expr.name);
+            }
+            return undefined;
+        })();
+        if (!symbol)
+            return undefined;
+        const resolvedSymbol = symbol.flags & ts.SymbolFlags.Alias
+            ? checker.getAliasedSymbol(symbol)
+            : symbol;
+        const decls = resolvedSymbol.getDeclarations();
+        if (!decls || decls.length === 0)
+            return undefined;
+        const argCount = node.arguments?.length ?? 0;
+        const candidates = [];
+        for (const decl of decls) {
+            if (!ts.isFunctionLike(decl))
+                continue;
+            // Only include construct signatures / constructors for new expressions.
+            if (!ts.isConstructSignatureDeclaration(decl) && !ts.isConstructorDeclaration(decl)) {
+                continue;
+            }
+            const params = extractParameterNodes(decl);
+            const required = params.filter((p) => !p.isOptional && !p.isRest).length;
+            const hasRest = params.some((p) => p.isRest);
+            if (argCount < required)
+                continue;
+            if (!hasRest && argCount > params.length)
+                continue;
+            const sig = checker.getSignatureFromDeclaration(decl);
+            if (!sig)
+                continue;
+            candidates.push(getOrCreateSignatureId(sig));
+        }
+        return candidates.length > 0 ? candidates : undefined;
+    };
+    const resolveImport = (node) => {
+        const symbol = checker.getSymbolAtLocation(node.name);
+        if (!symbol)
+            return undefined;
+        const aliased = checker.getAliasedSymbol(symbol);
+        return getOrCreateDeclId(aliased);
+    };
+    const resolveShorthandAssignment = (node) => {
+        const symbol = checker.getShorthandAssignmentValueSymbol(node);
+        if (!symbol)
+            return undefined;
+        return getOrCreateDeclId(symbol);
+    };
+    const getDeclaringTypeNameOfMember = (member) => {
+        const key = `${member.declId.id}:${member.name}`;
+        const entry = memberMap.get(key);
+        const decl = entry?.decl;
+        if (!decl)
+            return undefined;
+        const parent = decl.parent;
+        if (ts.isInterfaceDeclaration(parent) && parent.name)
+            return parent.name.text;
+        if (ts.isClassDeclaration(parent) && parent.name)
+            return parent.name.text;
+        if (ts.isTypeAliasDeclaration(parent) && parent.name)
+            return parent.name.text;
+        // tsbindgen static containers can be emitted as:
+        //   export const Foo: { bar(...): ... }
+        //
+        // In this case, member declarations live under a TypeLiteralNode whose parent
+        // is the VariableDeclaration for `Foo`. We treat `Foo` as the declaring "type"
+        // name for binding disambiguation purposes.
+        if (ts.isTypeLiteralNode(parent)) {
+            const container = parent.parent;
+            if (ts.isVariableDeclaration(container) && ts.isIdentifier(container.name)) {
+                return container.name.text;
+            }
+        }
+        return undefined;
+    };
+    const getSourceFilePathOfMember = (member) => {
+        const key = `${member.declId.id}:${member.name}`;
+        const entry = memberMap.get(key);
+        const decl = entry?.decl;
+        if (!decl)
+            return undefined;
+        return decl.getSourceFile().fileName;
+    };
+    const getFullyQualifiedName = (declId) => {
+        const entry = declMap.get(declId.id);
+        if (!entry)
+            return undefined;
+        return checker.getFullyQualifiedName(entry.symbol);
+    };
+    const getTypePredicateOfSignature = (sigId) => {
+        const entry = signatureMap.get(sigId.id);
+        if (!entry)
+            return undefined;
+        const predicate = checker.getTypePredicateOfSignature(entry.signature);
+        if (!predicate || predicate.kind !== ts.TypePredicateKind.Identifier) {
+            return undefined;
+        }
+        return {
+            kind: "typePredicate",
+            parameterIndex: predicate.parameterIndex ?? 0,
+            typeNode: predicate.type
+                ? checker.typeToTypeNode(predicate.type, undefined, ts.NodeBuilderFlags.None)
+                : undefined,
+        };
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // HANDLE REGISTRY IMPLEMENTATION
+    // ─────────────────────────────────────────────────────────────────────────
+    const handleRegistry = {
+        getDecl: (id) => {
+            const entry = declMap.get(id.id);
+            if (!entry)
+                return undefined;
+            return {
+                typeNode: entry.typeNode,
+                kind: entry.kind,
+                fqName: entry.fqName,
+                declNode: entry.decl,
+                typeDeclNode: entry.typeDeclNode,
+                valueDeclNode: entry.valueDeclNode,
+                classMemberNames: entry.classMemberNames,
+            };
+        },
+        getSignature: (id) => {
+            const entry = signatureMap.get(id.id);
+            if (!entry)
+                return undefined;
+            return {
+                parameters: entry.parameters,
+                returnTypeNode: entry.returnTypeNode,
+                typeParameters: entry.typeParameters,
+                // CRITICAL for Alice's spec: declaring identity for resolveCall()
+                // Uses simple TS name, resolved via UnifiedTypeCatalog.resolveTsName()
+                declaringTypeTsName: entry.declaringTypeTsName,
+                declaringMemberName: entry.declaringMemberName,
+                // Type predicate extracted at registration time (Alice's spec)
+                typePredicate: entry.typePredicate,
+            };
+        },
+        getMember: (id) => {
+            const key = `${id.declId.id}:${id.name}`;
+            const entry = memberMap.get(key);
+            if (!entry)
+                return undefined;
+            return {
+                name: entry.name,
+                declNode: entry.decl,
+                typeNode: entry.typeNode,
+                isOptional: entry.isOptional,
+                isReadonly: entry.isReadonly,
+            };
+        },
+        getTypeSyntax: (id) => {
+            const entry = typeSyntaxMap.get(id.id);
+            if (!entry)
+                return undefined;
+            return {
+                typeNode: entry.typeNode,
+            };
+        },
+    };
+    // ─────────────────────────────────────────────────────────────────────────
+    // TYPE SYNTAX CAPTURE (Phase 2: TypeSyntaxId)
+    // ─────────────────────────────────────────────────────────────────────────
+    /**
+     * Capture a type syntax node for later conversion.
+     *
+     * This creates an opaque TypeSyntaxId handle that can be passed to
+     * TypeSystem.typeFromSyntax() for conversion. Used for inline type syntax
+     * that cannot be captured at catalog-build time.
+     */
+    const captureTypeSyntax = (node) => {
+        const id = makeTypeSyntaxId(nextTypeSyntaxId.value++);
+        typeSyntaxMap.set(id.id, { typeNode: node });
+        return id;
+    };
+    /**
+     * Capture multiple type arguments.
+     *
+     * Convenience method for capturing generic type arguments.
+     */
+    const captureTypeArgs = (nodes) => {
+        return nodes.map((node) => captureTypeSyntax(node));
+    };
+    return {
+        resolveIdentifier,
+        resolveTypeReference,
+        resolvePropertyAccess,
+        resolveElementAccess,
+        resolveCallSignature,
+        resolveCallSignatureCandidates,
+        resolveConstructorSignature,
+        resolveConstructorSignatureCandidates,
+        resolveImport,
+        resolveShorthandAssignment,
+        getDeclaringTypeNameOfMember,
+        getSourceFilePathOfMember,
+        getFullyQualifiedName,
+        getTypePredicateOfSignature,
+        // Type syntax capture (Phase 2: TypeSyntaxId)
+        captureTypeSyntax,
+        captureTypeArgs,
+        // Internal method for TypeSystem construction only
+        _getHandleRegistry: () => handleRegistry,
+    };
+};
+// ═══════════════════════════════════════════════════════════════════════════
+// HELPER FUNCTIONS
+// ═══════════════════════════════════════════════════════════════════════════
+const getTypeNodeFromDeclaration = (decl) => {
+    if (ts.isVariableDeclaration(decl) && decl.type) {
+        return decl.type;
+    }
+    if (ts.isFunctionDeclaration(decl) || ts.isMethodDeclaration(decl)) {
+        return decl.type;
+    }
+    if (ts.isParameter(decl) && decl.type) {
+        return decl.type;
+    }
+    if (ts.isPropertyDeclaration(decl) && decl.type) {
+        return decl.type;
+    }
+    if (ts.isPropertySignature(decl) && decl.type) {
+        return decl.type;
+    }
+    if (ts.isTypeAliasDeclaration(decl)) {
+        return decl.type;
+    }
+    return undefined;
+};
+const getMemberTypeAnnotation = (decl) => {
+    if (ts.isPropertyDeclaration(decl) || ts.isPropertySignature(decl)) {
+        return decl.type;
+    }
+    if (ts.isMethodDeclaration(decl) || ts.isMethodSignature(decl)) {
+        // For methods, we could return a function type node if needed
+        return decl.type;
+    }
+    if (ts.isGetAccessorDeclaration(decl)) {
+        return decl.type;
+    }
+    if (ts.isSetAccessorDeclaration(decl)) {
+        // Setter declarations have no return type; use the value parameter type.
+        const valueParam = decl.parameters[0];
+        return valueParam?.type;
+    }
+    return undefined;
+};
+const getDeclKind = (decl) => {
+    if (ts.isVariableDeclaration(decl))
+        return "variable";
+    if (ts.isFunctionDeclaration(decl))
+        return "function";
+    if (ts.isClassDeclaration(decl))
+        return "class";
+    if (ts.isInterfaceDeclaration(decl))
+        return "interface";
+    if (ts.isTypeAliasDeclaration(decl))
+        return "typeAlias";
+    if (ts.isEnumDeclaration(decl))
+        return "enum";
+    if (ts.isParameter(decl))
+        return "parameter";
+    if (ts.isPropertyDeclaration(decl) || ts.isPropertySignature(decl))
+        return "property";
+    if (ts.isGetAccessorDeclaration(decl) || ts.isSetAccessorDeclaration(decl))
+        return "property";
+    if (ts.isMethodDeclaration(decl) || ts.isMethodSignature(decl))
+        return "method";
+    return "variable";
+};
+const getReturnTypeNode = (decl) => {
+    if (!decl)
+        return undefined;
+    return decl.type;
+};
+/**
+ * Extract and normalize parameter nodes from a signature declaration.
+ *
+ * ALICE'S SPEC: Parameter mode detection happens HERE during signature registration.
+ * If the parameter type is `ref<T>`, `out<T>`, or `in<T>`:
+ * - Set `mode` to that keyword
+ * - Set `typeNode` to the INNER T node (unwrapped)
+ *
+ * This is PURE SYNTAX inspection, no TS type inference.
+ */
+const extractParameterNodes = (decl) => {
+    if (!decl)
+        return [];
+    return decl.parameters.map((p) => {
+        const normalized = normalizeParameterTypeNode(p.type);
+        return {
+            name: ts.isIdentifier(p.name) ? p.name.text : "param",
+            typeNode: normalized.typeNode,
+            isOptional: !!p.questionToken || !!p.initializer,
+            isRest: !!p.dotDotDotToken,
+            mode: normalized.mode,
+        };
+    });
+};
+/**
+ * Normalize a parameter type node by detecting ref<T>/out<T>/in<T> wrappers.
+ *
+ * This is PURE SYNTAX analysis - we look at the TypeNode AST structure:
+ * - If it's a TypeReferenceNode with identifier name "ref"/"out"/"in"
+ * - And exactly one type argument
+ * - Then unwrap to get the inner type
+ *
+ * @param typeNode The parameter's type node
+ * @returns { mode, typeNode } where typeNode is unwrapped if wrapper detected
+ */
+const normalizeParameterTypeNode = (typeNode) => {
+    if (!typeNode) {
+        return { mode: "value", typeNode: undefined };
+    }
+    // Mirror IR conversion rules: wrappers may be nested and may appear in any order.
+    // - thisarg<T> marks an extension-method receiver parameter (erases for typing)
+    // - ref<T>/out<T>/in<T>/inref<T> set passing mode and erase to T for typing
+    let mode = "value";
+    let current = typeNode;
+    while (current) {
+        if (ts.isParenthesizedTypeNode(current)) {
+            current = current.type;
+            continue;
+        }
+        if (!ts.isTypeReferenceNode(current))
+            break;
+        if (!ts.isIdentifier(current.typeName))
+            break;
+        if (!current.typeArguments || current.typeArguments.length !== 1)
+            break;
+        const inner = current.typeArguments[0];
+        if (!inner)
+            break;
+        const wrapperName = current.typeName.text;
+        if (wrapperName === "thisarg") {
+            current = inner;
+            continue;
+        }
+        if (wrapperName === "ref" || wrapperName === "out") {
+            mode = wrapperName;
+            current = inner;
+            continue;
+        }
+        if (wrapperName === "in" || wrapperName === "inref") {
+            mode = "in";
+            current = inner;
+            continue;
+        }
+        break;
+    }
+    // No wrapper detected - regular parameter
+    return { mode, typeNode: current ?? typeNode };
+};
+const convertTypeParameterDeclarations = (typeParameters) => {
+    if (!typeParameters || typeParameters.length === 0)
+        return undefined;
+    return typeParameters.map((tp) => ({
+        name: tp.name.text,
+        constraintNode: tp.constraint,
+        defaultNode: tp.default,
+    }));
+};
+const extractTypeParameterNodes = (decl) => {
+    if (!decl)
+        return undefined;
+    // Constructor declarations don't have their own type parameters in TS syntax,
+    // but the enclosing class may be generic (class Box<T> { constructor(x: T) {} }).
+    // For constructor signature typing/inference, the relevant type parameters are the
+    // class type parameters.
+    if (ts.isConstructorDeclaration(decl)) {
+        const parent = decl.parent;
+        if (ts.isClassDeclaration(parent)) {
+            return convertTypeParameterDeclarations(parent.typeParameters);
+        }
+        return undefined;
+    }
+    return convertTypeParameterDeclarations(decl.typeParameters);
+};
+/**
+ * Extract type predicate from a signature's return type.
+ *
+ * ALICE'S SPEC: This is PURE SYNTAX inspection at registration time.
+ * We check if the return TypeNode is a TypePredicateNode (x is T or this is T).
+ * No TS type inference is used.
+ *
+ * @param returnTypeNode The signature's return type node
+ * @param decl The signature declaration (to find parameter index)
+ * @returns SignatureTypePredicate or undefined if not a predicate
+ */
+const extractTypePredicate = (returnTypeNode, decl) => {
+    // Return type must be a TypePredicateNode
+    if (!returnTypeNode || !ts.isTypePredicateNode(returnTypeNode)) {
+        return undefined;
+    }
+    const predNode = returnTypeNode;
+    // Must have a target type
+    if (!predNode.type) {
+        return undefined;
+    }
+    // Check if it's "this is T" predicate
+    if (predNode.parameterName.kind === ts.SyntaxKind.ThisType) {
+        return {
+            kind: "this",
+            targetTypeNode: predNode.type,
+        };
+    }
+    // Check if it's "param is T" predicate
+    if (ts.isIdentifier(predNode.parameterName)) {
+        const paramName = predNode.parameterName.text;
+        // Find parameter index
+        const paramIndex = decl?.parameters.findIndex((p) => ts.isIdentifier(p.name) && p.name.text === paramName) ?? -1;
+        if (paramIndex >= 0) {
+            return {
+                kind: "param",
+                parameterName: paramName,
+                parameterIndex: paramIndex,
+                targetTypeNode: predNode.type,
+            };
+        }
+    }
+    return undefined;
+};
+const isOptionalMember = (symbol) => {
+    return (symbol.flags & ts.SymbolFlags.Optional) !== 0;
+};
+const isReadonlyMember = (decl) => {
+    if (!decl)
+        return false;
+    if (ts.isPropertyDeclaration(decl) || ts.isPropertySignature(decl)) {
+        return (decl.modifiers?.some((m) => m.kind === ts.SyntaxKind.ReadonlyKeyword) ??
+            false);
+    }
+    return false;
+};
+/**
+ * Extract declaring identity from a signature declaration.
+ *
+ * CRITICAL for Alice's spec: Without this, resolveCall() cannot compute
+ * inheritance substitution. It would have to "guess" the method name
+ * from the signature, which breaks on overloads, aliases, etc.
+ *
+ * DESIGN (Phase 5 Step 4): Store the declaring type as a **simple TS name**
+ * (identifier text like "Box"), NOT a TS "fully qualified name". TypeSystem
+ * uses UnifiedTypeCatalog.resolveTsName() to resolve this to the proper
+ * CLR FQ name for inheritance substitution.
+ *
+ * @param decl The signature declaration (method, function, etc.)
+ * @param _checker TypeChecker (kept for backwards compatibility, unused)
+ * @returns { typeTsName, memberName } or undefined if not a member
+ */
+const extractDeclaringIdentity = (decl, _checker) => {
+    if (!decl)
+        return undefined;
+    const normalizeTsbindgenTypeName = (name) => {
+        if (name.endsWith("$instance")) {
+            return name.slice(0, -"$instance".length);
+        }
+        if (name.startsWith("__") && name.endsWith("$views")) {
+            return name.slice(2, -"$views".length);
+        }
+        return name;
+    };
+    // Check if this is a method (class or interface member)
+    if (ts.isMethodDeclaration(decl) || ts.isMethodSignature(decl)) {
+        const parent = decl.parent;
+        // Get the method name
+        const memberName = ts.isIdentifier(decl.name)
+            ? decl.name.text
+            : (decl.name?.getText() ?? "unknown");
+        // Get the containing type's simple name (identifier text)
+        if (ts.isClassDeclaration(parent) || ts.isInterfaceDeclaration(parent)) {
+            if (parent.name) {
+                // Use the simple identifier text, not checker.getFullyQualifiedName
+                const typeTsName = normalizeTsbindgenTypeName(parent.name.text);
+                return { typeTsName, memberName };
+            }
+        }
+        // tsbindgen static containers are commonly emitted as:
+        //   export const Foo: { bar(...): ... }
+        //
+        // In this case, method signatures live under a TypeLiteralNode whose parent is
+        // the variable declaration for `Foo`. We still need declaring identity so
+        // TypeSystem can apply airplane-grade overload correction using CLR metadata.
+        if (ts.isTypeLiteralNode(parent)) {
+            const container = parent.parent;
+            if (ts.isVariableDeclaration(container) && ts.isIdentifier(container.name)) {
+                const typeTsName = normalizeTsbindgenTypeName(container.name.text);
+                return { typeTsName, memberName };
+            }
+        }
+        // Object literal method - use parent context
+        if (ts.isObjectLiteralExpression(parent)) {
+            // For object literals, we don't have a named type
+            return undefined;
+        }
+    }
+    // Constructor declarations
+    if (ts.isConstructorDeclaration(decl)) {
+        const parent = decl.parent;
+        if (ts.isClassDeclaration(parent) && parent.name) {
+            // Use the simple identifier text
+            const typeTsName = normalizeTsbindgenTypeName(parent.name.text);
+            return { typeTsName, memberName: "constructor" };
+        }
+    }
+    // Getter/setter declarations
+    if (ts.isGetAccessorDeclaration(decl) || ts.isSetAccessorDeclaration(decl)) {
+        const parent = decl.parent;
+        const memberName = ts.isIdentifier(decl.name)
+            ? decl.name.text
+            : (decl.name?.getText() ?? "unknown");
+        if (ts.isClassDeclaration(parent) || ts.isInterfaceDeclaration(parent)) {
+            if (parent.name) {
+                // Use the simple identifier text
+                const typeTsName = normalizeTsbindgenTypeName(parent.name.text);
+                return { typeTsName, memberName };
+            }
+        }
+    }
+    // Standalone functions don't have a declaring type
+    return undefined;
+};
+/**
+ * Extract class member names from a ClassDeclaration.
+ *
+ * ALICE'S SPEC: This is PURE SYNTAX inspection at registration time.
+ * We iterate class members and collect method/property names.
+ * This data is used by TypeSystem.checkTsClassMemberOverride without
+ * needing to inspect TS AST nodes or use hardcoded SyntaxKind numbers.
+ *
+ * @param classDecl The class declaration node
+ * @returns ClassMemberNames with method and property name sets
+ */
+const extractClassMemberNames = (classDecl) => {
+    const methods = new Set();
+    const properties = new Set();
+    for (const member of classDecl.members) {
+        // Get member name if it has an identifier
+        const name = ts.isMethodDeclaration(member)
+            ? ts.isIdentifier(member.name)
+                ? member.name.text
+                : undefined
+            : ts.isPropertyDeclaration(member)
+                ? ts.isIdentifier(member.name)
+                    ? member.name.text
+                    : undefined
+                : ts.isGetAccessorDeclaration(member) ||
+                    ts.isSetAccessorDeclaration(member)
+                    ? ts.isIdentifier(member.name)
+                        ? member.name.text
+                        : undefined
+                    : undefined;
+        if (!name)
+            continue;
+        if (ts.isMethodDeclaration(member)) {
+            methods.add(name);
+        }
+        else if (ts.isPropertyDeclaration(member)) {
+            properties.add(name);
+        }
+        else if (ts.isGetAccessorDeclaration(member) ||
+            ts.isSetAccessorDeclaration(member)) {
+            // Accessors are treated as properties for override detection
+            properties.add(name);
+        }
+    }
+    return { methods, properties };
+};
+//# sourceMappingURL=index.js.map