@tsonic/emitter 0.0.73 → 0.0.75

package/dist/types/references.js

@@ -5,111 +5,14 @@
  */
 import { escapeCSharpIdentifier } from "../emitter-types/index.js";
 import { emitTypeAst } from "./emitter.js";
-import { resolveLocalTypeInfo, substituteTypeArgs, } from "../core/semantic/type-resolution.js";
-/**
- * C# primitive type names that can be emitted directly without qualification.
- * These correspond to the types defined in @tsonic/core package.
- */
-const CSHARP_PRIMITIVES = new Set([
-    // Signed integers (from @tsonic/core)
-    "sbyte",
-    "short",
-    "int",
-    "long",
-    "nint",
-    "int128",
-    // Unsigned integers (from @tsonic/core)
-    "byte",
-    "ushort",
-    "uint",
-    "ulong",
-    "nuint",
-    "uint128",
-    // Floating-point (from @tsonic/core)
-    "half",
-    "float",
-    "double",
-    "decimal",
-    // Other primitives (from @tsonic/core)
-    "bool",
-    "char",
-    // Additional C# keywords that are valid type names
-    "string",
-    "object",
-    "void",
-]);
-/**
- * Normalize a CLR type name to global:: format
- */
-const toGlobalClr = (clr) => {
-    const trimmed = clr.trim();
-    return trimmed.startsWith("global::") ? trimmed : `global::${trimmed}`;
-};
-/**
- * Convert CLR metadata type names into C#-emittable type names.
- *
- * tsbindgen bindings use CLR "full names" that include:
- * - Generic arity markers: `Dictionary`2`, `Func`3`, etc.
- * - Nested type separators: `Outer+Inner`
- *
- * C# source code must not include arity markers, and nested types use `.`
- * in source (e.g. `Outer.Inner`).
- */
-const clrTypeNameToCSharp = (clr) => {
-    const prefix = "global::";
-    const hasGlobal = clr.startsWith(prefix);
-    const body = hasGlobal ? clr.slice(prefix.length) : clr;
-    const sanitized = body
-        // Strip generic arity markers (e.g. Dictionary`2 -> Dictionary)
-        .replace(/`\d+/g, "")
-        // CLR nested types use '+'; C# source uses '.'
-        .replace(/\+/g, ".");
-    return hasGlobal ? `${prefix}${sanitized}` : sanitized;
-};
-const resolveImportedTypeClrName = (typeName, context) => {
-    const candidates = getReferenceLookupCandidates(typeName);
-    for (const candidate of candidates) {
-        const binding = context.importBindings?.get(candidate);
-        if (!binding || binding.kind !== "type")
-            continue;
-        return clrTypeNameToCSharp(binding.clrName);
-    }
-    return undefined;
-};
-const getReferenceLookupCandidates = (typeName) => {
-    const candidates = new Set([typeName]);
-    if (typeName.endsWith("$instance")) {
-        const base = typeName.slice(0, -"$instance".length);
-        if (base.length > 0) {
-            candidates.add(base);
-            const unsuffixed = base.replace(/_\d+$/, "");
-            if (unsuffixed.length > 0) {
-                candidates.add(unsuffixed);
-            }
-        }
-    }
-    return Array.from(candidates);
-};
-const resolveCanonicalLocalTypeTarget = (typeName, context) => {
-    const namespace = context.moduleNamespace ?? context.options.rootNamespace;
-    const key = `${namespace}::${typeName}`;
-    return context.options.canonicalLocalTypeTargets?.get(key);
-};
-const emitQualifiedLocalType = (namespace, csharpName, typeArguments, context) => {
-    const qualified = `global::${namespace}.${csharpName}`;
-    if (typeArguments && typeArguments.length > 0) {
-        const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-        return [identifierTypeWithArgs(qualified, typeArgAsts), newContext];
-    }
-    return [{ kind: "identifierType", name: qualified }, context];
-};
-/**
- * Normalize a generic type argument AST: void → object.
- * C# generic type arguments cannot be void, so we substitute object.
- */
-const normalizeGenericTypeArgAst = (ast) => ast.kind === "predefinedType" && ast.keyword === "void"
-    ? { kind: "predefinedType", keyword: "object" }
-    : ast;
+import { resolveTypeAlias, resolveStructuralReferenceType, resolveLocalTypeInfo, substituteTypeArgs, } from "../core/semantic/type-resolution.js";
+import { resolveLocalTypeInfoWithoutBindings } from "../core/semantic/property-lookup-resolution.js";
+import { identifierType, nullableType, withTypeArguments, } from "../core/format/backend-ast/builders.js";
+import { clrTypeNameToTypeAst, isCSharpPredefinedTypeKeyword, } from "../core/format/backend-ast/utils.js";
+import { attachTypeArgumentsIfSupported, emitQualifiedLocalType, emitRecursiveAliasFallbackType, emitTypeArgAsts, identifierTypeWithArgs, getReferenceLookupCandidates, keyForResolvedLocalType, resolveCanonicalLocalTypeTarget, resolveImportedTypeAst, restoreResolvingTypeAliases, toGlobalClr, withResolvingTypeAlias, } from "./reference-lookup.js";
+import { resolveBindingBackedStructuralTypeAst, resolveCanonicalStructuralReferenceTypeAst, } from "./reference-structural-signatures.js";
+import { buildRuntimeUnionLayout, buildRuntimeUnionTypeAst, } from "../core/semantic/runtime-unions.js";
+import { areIrTypesEquivalent } from "../core/semantic/type-equivalence.js";
 /**
  * Check if a type name indicates an unsupported support type.
  *
@@ -130,30 +33,85 @@ const checkUnsupportedSupportType = (typeName) => {
     }
     return undefined;
 };
-/**
- * Emit type arguments as CSharpTypeAst[], with void→object normalization.
- */
-const emitTypeArgAsts = (typeArguments, context) => {
-    const typeArgAsts = [];
-    let currentContext = context;
-    for (const typeArg of typeArguments) {
-        const [paramAst, newContext] = emitTypeAst(typeArg, currentContext);
-        typeArgAsts.push(normalizeGenericTypeArgAst(paramAst));
-        currentContext = newContext;
-    }
-    return [typeArgAsts, currentContext];
+const EXACT_BCL_VALUE_TYPE_MAP = new Map([
+    ["half", "global::System.Half"],
+    ["int128", "global::System.Int128"],
+    ["uint128", "global::System.UInt128"],
+]);
+const POLYMORPHIC_THIS_MARKER = "__tsonic_polymorphic_this";
+const isQualifiedClrIdentity = (name) => {
+    if (!name) {
+        return false;
+    }
+    const trimmed = name.trim();
+    return (trimmed.startsWith("global::") ||
+        trimmed.includes(".") ||
+        trimmed.includes("+"));
 };
-/**
- * Build an identifierType with optional type arguments.
- */
-const identifierTypeWithArgs = (name, typeArgAsts) => typeArgAsts && typeArgAsts.length > 0
-    ? { kind: "identifierType", name, typeArguments: typeArgAsts }
-    : { kind: "identifierType", name };
+const isSystemObjectClrIdentity = (name) => name === "System.Object" || name === "global::System.Object";
+const getDeclaringTypeParameterAsts = (context) => (context.declaringTypeParameterNames ?? []).map((name) => identifierType(context.declaringTypeParameterNameMap?.get(name) ?? name));
 /**
  * Emit reference types as CSharpTypeAst
  */
 export const emitReferenceType = (type, context) => {
     const { name, typeArguments, resolvedClrType, typeId } = type;
+    const resolvedAlias = resolveTypeAlias(type, context, {
+        preserveObjectTypeAliases: true,
+    });
+    if (resolvedAlias !== type) {
+        if (resolvedAlias.kind === "unionType" &&
+            resolvedAlias.runtimeCarrierFamilyKey) {
+            const [layout, layoutContext] = buildRuntimeUnionLayout(type, context, emitTypeAst);
+            if (layout) {
+                return [buildRuntimeUnionTypeAst(layout), layoutContext];
+            }
+        }
+        return emitTypeAst(resolvedAlias, context);
+    }
+    const currentModuleNamespace = context.moduleNamespace ?? context.options.rootNamespace;
+    const currentModuleLocalResolution = resolveLocalTypeInfoWithoutBindings(type, context);
+    const currentModuleLocalType = currentModuleLocalResolution?.namespace === currentModuleNamespace
+        ? currentModuleLocalResolution.info
+        : undefined;
+    const currentModuleLocalName = currentModuleLocalResolution?.namespace === currentModuleNamespace
+        ? currentModuleLocalResolution.name
+        : undefined;
+    // Explicit import contracts are authoritative and must win before any
+    // structural or binding-backed rebound. Otherwise same-named sibling types
+    // can be reattached to an unrelated owner through registry aliasing.
+    const importedTypeAst = resolveImportedTypeAst(name, context);
+    if (importedTypeAst) {
+        if (typeArguments && typeArguments.length > 0) {
+            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
+            if (importedTypeAst.kind === "identifierType" ||
+                importedTypeAst.kind === "qualifiedIdentifierType") {
+                return [withTypeArguments(importedTypeAst, typeArgAsts), newContext];
+            }
+            return [importedTypeAst, newContext];
+        }
+        return [importedTypeAst, context];
+    }
+    const structuralReference = resolveStructuralReferenceType(type, context);
+    if (structuralReference &&
+        structuralReference.kind === "referenceType" &&
+        !areIrTypesEquivalent(structuralReference, type, context)) {
+        return emitReferenceType(structuralReference, context);
+    }
+    if (name === POLYMORPHIC_THIS_MARKER && context.declaringTypeName) {
+        const declaringTypeParameterAsts = getDeclaringTypeParameterAsts(context);
+        return emitReferenceType({
+            ...type,
+            name: context.declaringTypeName,
+            typeArguments: declaringTypeParameterAsts.length > 0
+                ? (context.declaringTypeParameterNames ?? []).map((paramName) => ({
+                    kind: "typeParameterType",
+                    name: paramName,
+                }))
+                : undefined,
+            resolvedClrType: undefined,
+            typeId: undefined,
+        }, context);
+    }
     // Check if this is a local type alias.
     //
     // C# has no general-purpose type alias syntax at the use-site, so type aliases must be
@@ -163,7 +121,7 @@ export const emitReferenceType = (type, context) => {
     // Examples:
     // - `type Pair = [number, number]`      → `global::System.ValueTuple<double, double>`
     // - `type Auth = { ok: true } | { error: string }`
-    //                                   → `global::Tsonic.Runtime.Union<Auth__0, Auth__1>`
+    //                                   → compiler-owned runtime union carrier
     // - `type Point = { x: number; y: number }`
     //                                   → `Point__Alias` (class emitted elsewhere)
     const typeInfo = context.localTypes?.get(name);
@@ -172,112 +130,70 @@ export const emitReferenceType = (type, context) => {
         // Resolve all non-object type aliases; object aliases are emitted as classes.
         const shouldResolve = underlyingKind !== "objectType";
         if (shouldResolve) {
-            // Substitute type arguments if present
-            const underlyingType = typeArguments && typeArguments.length > 0
+            const substitutedUnderlyingType = typeArguments && typeArguments.length > 0
                 ? substituteTypeArgs(typeInfo.type, typeInfo.typeParameters, typeArguments)
                 : typeInfo.type;
-            return emitTypeAst(underlyingType, context);
+            if (context.resolvingTypeAliases?.has(name)) {
+                return emitRecursiveAliasFallbackType(substitutedUnderlyingType, context);
+            }
+            const [resolvedAst, resolvedContext] = emitTypeAst(substitutedUnderlyingType, withResolvingTypeAlias(name, context));
+            return [
+                resolvedAst,
+                restoreResolvingTypeAliases(resolvedContext, context),
+            ];
         }
         // For `objectType` aliases - fall through and emit the alias name; it will be
         // rewritten to `__Alias` in the local-type handling below.
     }
-    // If the type has a pre-resolved CLR type (from IR), use it
-    if (resolvedClrType) {
-        const normalizedClr = clrTypeNameToCSharp(resolvedClrType);
-        const qualifiedClr = CSHARP_PRIMITIVES.has(normalizedClr)
-            ? normalizedClr
-            : toGlobalClr(normalizedClr);
-        if (typeArguments && typeArguments.length > 0) {
-            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-            return [identifierTypeWithArgs(qualifiedClr, typeArgAsts), newContext];
-        }
-        // For primitives, emit as predefinedType; for others, identifierType
-        return [
-            CSHARP_PRIMITIVES.has(normalizedClr)
-                ? { kind: "predefinedType", keyword: normalizedClr }
-                : { kind: "identifierType", name: qualifiedClr },
-            context,
-        ];
-    }
-    // Check if this type is imported - use pre-computed CLR name directly.
-    // This includes canonicalization for tsbindgen instance aliases (Foo$instance)
-    // so imported type identity remains stable even when global aliases collide.
-    const qualifiedName = resolveImportedTypeClrName(name, context);
-    if (qualifiedName) {
-        if (CSHARP_PRIMITIVES.has(qualifiedName)) {
-            return [{ kind: "predefinedType", keyword: qualifiedName }, context];
-        }
-        if (typeArguments && typeArguments.length > 0) {
-            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-            return [identifierTypeWithArgs(toGlobalClr(qualifiedName), typeArgAsts), newContext];
-        }
-        return [{ kind: "identifierType", name: toGlobalClr(qualifiedName) }, context];
-    }
     // Check for unsupported support types
     const unsupportedError = checkUnsupportedSupportType(name);
     if (unsupportedError) {
         throw new Error(`[Tsonic] ${unsupportedError}`);
     }
-    // Handle built-in types
-    // Array<T> emits as native T[] array, same as T[] syntax
-    // Users must explicitly use List<T> to get a List
-    if (name === "Array" && typeArguments && typeArguments.length > 0) {
-        const firstArg = typeArguments[0];
-        if (!firstArg) {
-            return [
-                {
-                    kind: "arrayType",
-                    elementType: { kind: "predefinedType", keyword: "object" },
-                    rank: 1,
-                },
-                context,
-            ];
-        }
-        const [elementTypeAst, newContext] = emitTypeAst(firstArg, context);
-        return [
-            { kind: "arrayType", elementType: elementTypeAst, rank: 1 },
-            newContext,
-        ];
-    }
     if (name === "Promise" && typeArguments && typeArguments.length > 0) {
         const firstArg = typeArguments[0];
         if (!firstArg) {
-            return [
-                {
-                    kind: "identifierType",
-                    name: "global::System.Threading.Tasks.Task",
-                },
-                context,
-            ];
+            return [identifierType("global::System.Threading.Tasks.Task"), context];
         }
         const [elementTypeAst, newContext] = emitTypeAst(firstArg, context);
         // Promise<void> should map to Task (not Task<void>)
         if (elementTypeAst.kind === "predefinedType" &&
             elementTypeAst.keyword === "void") {
             return [
-                {
-                    kind: "identifierType",
-                    name: "global::System.Threading.Tasks.Task",
-                },
+                identifierType("global::System.Threading.Tasks.Task"),
                 newContext,
             ];
         }
         return [
-            {
-                kind: "identifierType",
-                name: "global::System.Threading.Tasks.Task",
-                typeArguments: [elementTypeAst],
-            },
+            identifierType("global::System.Threading.Tasks.Task", [elementTypeAst]),
             newContext,
         ];
     }
     if (name === "Promise") {
+        return [identifierType("global::System.Threading.Tasks.Task"), context];
+    }
+    if (name === "Iterable" ||
+        name === "IterableIterator" ||
+        name === "Generator") {
+        const elementType = typeArguments?.[0] ?? { kind: "unknownType" };
+        const [elementTypeAst, newContext] = emitTypeAst(elementType, context);
         return [
-            {
-                kind: "identifierType",
-                name: "global::System.Threading.Tasks.Task",
-            },
-            context,
+            identifierType("global::System.Collections.Generic.IEnumerable", [
+                elementTypeAst,
+            ]),
+            newContext,
+        ];
+    }
+    if (name === "AsyncIterable" ||
+        name === "AsyncIterableIterator" ||
+        name === "AsyncGenerator") {
+        const elementType = typeArguments?.[0] ?? { kind: "unknownType" };
+        const [elementTypeAst, newContext] = emitTypeAst(elementType, context);
+        return [
+            identifierType("global::System.Collections.Generic.IAsyncEnumerable", [
+                elementTypeAst,
+            ]),
+            newContext,
         ];
     }
     // Map core Span<T> to System.Span<T>.
@@ -291,14 +207,7 @@ export const emitReferenceType = (type, context) => {
             throw new Error("ICE: Span<T> missing type argument");
         }
         const [innerTypeAst, newContext] = emitTypeAst(inner, context);
-        return [
-            {
-                kind: "identifierType",
-                name: "global::System.Span",
-                typeArguments: [innerTypeAst],
-            },
-            newContext,
-        ];
+        return [identifierType("global::System.Span", [innerTypeAst]), newContext];
     }
     // Map core ptr<T> to C# unsafe pointer type: T*
     if (name === "ptr") {
@@ -313,25 +222,127 @@ export const emitReferenceType = (type, context) => {
         return [{ kind: "pointerType", elementType: innerTypeAst }, newContext];
     }
     // NOTE: Map and Set must be explicitly imported (not ambient)
+    if (name === "JsPrimitive") {
+        return [{ kind: "predefinedType", keyword: "object" }, context];
+    }
+    if (name === "JsValue") {
+        return [
+            nullableType({ kind: "predefinedType", keyword: "object" }),
+            context,
+        ];
+    }
     // Map PromiseLike to Task
     if (name === "PromiseLike") {
-        // PromiseLike is in both globals packages - safe to map unconditionally
+        const firstArg = typeArguments?.[0];
+        if (!firstArg) {
+            return [identifierType("global::System.Threading.Tasks.Task"), context];
+        }
+        const [elementTypeAst, newContext] = emitTypeAst(firstArg, context);
+        if (elementTypeAst.kind === "predefinedType" &&
+            elementTypeAst.keyword === "void") {
+            return [
+                identifierType("global::System.Threading.Tasks.Task"),
+                newContext,
+            ];
+        }
         return [
-            {
-                kind: "identifierType",
-                name: "global::System.Threading.Tasks.Task",
-            },
-            context,
+            identifierType("global::System.Threading.Tasks.Task", [elementTypeAst]),
+            newContext,
         ];
     }
     // C# primitive types can be emitted directly
-    if (CSHARP_PRIMITIVES.has(name)) {
+    if (isCSharpPredefinedTypeKeyword(name)) {
         return [{ kind: "predefinedType", keyword: name }, context];
     }
+    const exactBclValueType = EXACT_BCL_VALUE_TYPE_MAP.get(name);
+    if (exactBclValueType) {
+        if (typeArguments && typeArguments.length > 0) {
+            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
+            return [
+                identifierTypeWithArgs(exactBclValueType, typeArgAsts),
+                newContext,
+            ];
+        }
+        return [identifierType(exactBclValueType), context];
+    }
     // Type parameters in scope can be emitted directly
     if (context.typeParameters?.has(name)) {
         const mappedName = context.typeParameterNameMap?.get(name) ?? name;
-        return [{ kind: "identifierType", name: mappedName }, context];
+        return [identifierType(mappedName), context];
+    }
+    // Source-package local types compiled in this program must win over imported CLR
+    // metadata names. Imported aliases/interfaces often carry a nominal resolvedClrType,
+    // but if their real definition is present in moduleMap we need to emit from that
+    // local definition instead of treating them as precompiled external CLR types.
+    //
+    // Do not route current-module locals through this path. Same-module locals need the
+    // later local-type handling because it intentionally keeps local references short
+    // unless `qualifyLocalTypes` is explicitly enabled.
+    if (!currentModuleLocalType) {
+        const crossModuleLocalType = resolveLocalTypeInfo(type, context);
+        if (crossModuleLocalType) {
+            const { info, namespace, name: resolvedLocalName } = crossModuleLocalType;
+            if (info.kind === "typeAlias") {
+                const underlyingKind = info.type.kind;
+                if (underlyingKind !== "objectType") {
+                    const substitutedUnderlyingType = typeArguments && typeArguments.length > 0
+                        ? substituteTypeArgs(info.type, info.typeParameters, typeArguments)
+                        : info.type;
+                    const aliasKey = keyForResolvedLocalType(name, namespace);
+                    if (context.resolvingTypeAliases?.has(aliasKey)) {
+                        return emitRecursiveAliasFallbackType(substitutedUnderlyingType, context);
+                    }
+                    const [resolvedAst, resolvedContext] = emitTypeAst(substitutedUnderlyingType, withResolvingTypeAlias(aliasKey, context));
+                    return [
+                        resolvedAst,
+                        restoreResolvingTypeAliases(resolvedContext, context),
+                    ];
+                }
+                return emitQualifiedLocalType(namespace, `${resolvedLocalName}__Alias`, typeArguments, context);
+            }
+            return emitQualifiedLocalType(namespace, resolvedLocalName, typeArguments, context);
+        }
+    }
+    // Check if this type is imported - use pre-computed type AST directly.
+    // Exact source/CLR import bindings are authoritative for imported simple names.
+    // resolvedClrType can carry stale nominal identity when frontend/binding paths
+    // collapse same-named exported types from sibling modules; the explicit import
+    // contract must win in that case.
+    //
+    // This includes canonicalization for tsbindgen instance aliases (Foo$instance)
+    // so imported type identity remains stable even when global aliases collide.
+    // If the type has a pre-resolved CLR type (from IR), use it
+    if ((!currentModuleLocalType ||
+        context.preferResolvedLocalClrIdentity ||
+        isSystemObjectClrIdentity(resolvedClrType)) &&
+        isQualifiedClrIdentity(resolvedClrType)) {
+        const typeAst = clrTypeNameToTypeAst(toGlobalClr(resolvedClrType));
+        if (typeArguments && typeArguments.length > 0) {
+            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
+            if (typeAst.kind === "identifierType" ||
+                typeAst.kind === "qualifiedIdentifierType") {
+                return [withTypeArguments(typeAst, typeArgAsts), newContext];
+            }
+            return [typeAst, newContext];
+        }
+        return [typeAst, context];
+    }
+    const bindingBackedStructuralTypeAst = !currentModuleLocalType
+        ? resolveBindingBackedStructuralTypeAst(type, context)
+        : undefined;
+    if (bindingBackedStructuralTypeAst) {
+        if (typeArguments && typeArguments.length > 0) {
+            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
+            if (bindingBackedStructuralTypeAst.kind === "identifierType" ||
+                bindingBackedStructuralTypeAst.kind === "qualifiedIdentifierType") {
+                return [
+                    withTypeArguments(bindingBackedStructuralTypeAst, typeArgAsts),
+                    newContext,
+                ];
+            }
+            return [bindingBackedStructuralTypeAst, newContext];
+        }
+        return [bindingBackedStructuralTypeAst, context];
     }
     const canonicalLocalTarget = resolveCanonicalLocalTypeTarget(name, context);
     if (canonicalLocalTarget) {
@@ -340,15 +351,16 @@ export const emitReferenceType = (type, context) => {
             const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
             return [identifierTypeWithArgs(qualified, typeArgAsts), newContext];
         }
-        return [{ kind: "identifierType", name: qualified }, context];
+        return [identifierType(qualified), context];
     }
     // IMPORTANT: Check local types BEFORE binding registry.
     // Local types take precedence over .NET types with the same name.
     // This ensures that a locally defined `Container<T>` is not resolved
     // to `System.ComponentModel.Container` from the binding registry.
-    const localTypeInfo = context.localTypes?.get(name);
+    const localTypeInfo = currentModuleLocalType;
     if (localTypeInfo) {
-        let csharpName = name;
+        let csharpName = currentModuleLocalName ?? name;
+        const shouldForceQualifiedLocalType = csharpName.startsWith("__Anon_") || csharpName.startsWith("__Rest_");
         // Type aliases with objectType underlying type are emitted as classes with __Alias suffix
         // (per spec/16-types-and-interfaces.md §3.4)
         if (localTypeInfo.kind === "typeAlias" &&
@@ -357,7 +369,7 @@ export const emitReferenceType = (type, context) => {
         }
         if (typeArguments && typeArguments.length > 0) {
             const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-            if (!context.qualifyLocalTypes) {
+            if (!context.qualifyLocalTypes && !shouldForceQualifiedLocalType) {
                 return [identifierTypeWithArgs(csharpName, typeArgAsts), newContext];
             }
             const moduleNamespace = context.moduleNamespace ?? context.options.rootNamespace;
@@ -374,8 +386,8 @@ export const emitReferenceType = (type, context) => {
                 newContext,
             ];
         }
-        if (!context.qualifyLocalTypes) {
-            return [{ kind: "identifierType", name: csharpName }, context];
+        if (!context.qualifyLocalTypes && !shouldForceQualifiedLocalType) {
+            return [identifierType(csharpName), context];
         }
         const moduleNamespace = context.moduleNamespace ?? context.options.rootNamespace;
         const container = context.moduleStaticClassName;
@@ -385,40 +397,44 @@ export const emitReferenceType = (type, context) => {
             ? `${moduleNamespace}.${container}`
             : moduleNamespace;
         return [
-            {
-                kind: "identifierType",
-                name: `global::${qualifiedPrefix}.${csharpName}`,
-            },
+            identifierType(`global::${qualifiedPrefix}.${csharpName}`),
             context,
         ];
     }
-    const crossModuleLocalType = resolveLocalTypeInfo(type, context);
-    const currentNamespace = context.moduleNamespace ?? context.options.rootNamespace;
-    if (crossModuleLocalType &&
-        !(crossModuleLocalType.namespace === currentNamespace)) {
-        const { info, namespace } = crossModuleLocalType;
-        if (info.kind === "typeAlias") {
-            const underlyingKind = info.type.kind;
-            if (underlyingKind !== "objectType") {
-                const underlyingType = typeArguments && typeArguments.length > 0
-                    ? substituteTypeArgs(info.type, info.typeParameters, typeArguments)
-                    : info.type;
-                return emitTypeAst(underlyingType, context);
-            }
-            return emitQualifiedLocalType(namespace, `${name}__Alias`, typeArguments, context);
+    // Handle built-in array-like contracts only after giving concrete local/source
+    // declarations a chance to win. Source packages such as @tsonic/js are allowed
+    // to define a real exported class named Array, and that must not be erased to T[].
+    if (name === "Array" || name === "ReadonlyArray" || name === "ArrayLike") {
+        if (resolvedClrType) {
+            return [clrTypeNameToTypeAst(toGlobalClr(resolvedClrType)), context];
         }
-        return emitQualifiedLocalType(namespace, name, typeArguments, context);
+        const firstArg = typeArguments?.[0];
+        if (!firstArg) {
+            return [
+                {
+                    kind: "arrayType",
+                    elementType: { kind: "predefinedType", keyword: "object" },
+                    rank: 1,
+                },
+                context,
+            ];
+        }
+        const [elementTypeAst, newContext] = emitTypeAst(firstArg, context);
+        return [
+            { kind: "arrayType", elementType: elementTypeAst, rank: 1 },
+            newContext,
+        ];
     }
     // Canonical nominal identity from the UnifiedUniverse.
     // When present, this is the authoritative source for CLR emission and
     // avoids relying on emitter-side registry plumbing for basic type names.
     if (typeId) {
-        const qualified = toGlobalClr(clrTypeNameToCSharp(typeId.clrName));
+        const typeAst = clrTypeNameToTypeAst(toGlobalClr(typeId.clrName));
         if (typeArguments && typeArguments.length > 0) {
             const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-            return [identifierTypeWithArgs(qualified, typeArgAsts), newContext];
+            return [attachTypeArgumentsIfSupported(typeAst, typeArgAsts), newContext];
         }
-        return [{ kind: "identifierType", name: qualified }, context];
+        return [typeAst, context];
     }
     // Resolve external types via binding registry (must be fully qualified)
     // This handles types from contextual inference (e.g., Action from Parallel.invoke)
@@ -427,12 +443,12 @@ export const emitReferenceType = (type, context) => {
         const regBinding = context.bindingsRegistry?.get(candidate);
         if (!regBinding)
             continue;
-        const qualified = toGlobalClr(clrTypeNameToCSharp(regBinding.name));
+        const typeAst = clrTypeNameToTypeAst(toGlobalClr(regBinding.name));
         if (typeArguments && typeArguments.length > 0) {
             const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
-            return [identifierTypeWithArgs(qualified, typeArgAsts), newContext];
+            return [attachTypeArgumentsIfSupported(typeAst, typeArgAsts), newContext];
         }
-        return [{ kind: "identifierType", name: qualified }, context];
+        return [typeAst, context];
     }
     // Synthetic cross-module types (e.g. compiler-generated anonymous types) are
     // declared in separate `__tsonic/*` modules. These do not appear in a given
@@ -445,10 +461,23 @@ export const emitReferenceType = (type, context) => {
             const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
             return [identifierTypeWithArgs(qualified, typeArgAsts), newContext];
         }
-        return [{ kind: "identifierType", name: qualified }, context];
+        return [identifierType(qualified), context];
+    }
+    const canonicalStructuralTypeAst = !currentModuleLocalType && type.kind === "referenceType"
+        ? resolveCanonicalStructuralReferenceTypeAst(type, context)
+        : undefined;
+    if (canonicalStructuralTypeAst) {
+        if (typeArguments && typeArguments.length > 0) {
+            const [typeArgAsts, newContext] = emitTypeArgAsts(typeArguments, context);
+            return [
+                attachTypeArgumentsIfSupported(canonicalStructuralTypeAst, typeArgAsts),
+                newContext,
+            ];
+        }
+        return [canonicalStructuralTypeAst, context];
     }
     // Hard failure: unresolved external reference type
     // This should never happen if the IR soundness gate is working correctly
-    throw new Error(`ICE: Unresolved reference type '${name}' (no resolvedClrType, no import binding, no registry binding, not local)`);
+    throw new Error(`ICE: Unresolved reference type '${name}' (no resolvedClrType, no import binding, no registry binding, not local; structuralMembers=${type.structuralMembers?.length ?? 0}; typeId=${type.typeId?.clrName ?? "none"})`);
 };
 //# sourceMappingURL=references.js.map