lemmascript 0.4.0 → 0.5.1

package/tools/dist/extract.js

@@ -5,9 +5,133 @@
  * The only strings are //@ annotation expressions (parsed later by specparser).
  */
 import { Project, Node, SyntaxKind, ScriptTarget } from "ts-morph";
+import { initTypeParser } from "./types.js";
 // ── Expression extraction ────────────────────────────────────
 /** When set, calls whose function/method name matches this key are replaced with havoc. */
 let _havocKey = null;
+/** Auto-detected cross-file calls. Populated by `extractExpr` whenever it sees
+ *  a call `Obj.method(...)` or `foo(...)` whose ts-morph symbol resolves to a
+ *  different `.ts` source file. Emitted in Dafny as `function {:axiom} <flat>`.
+ *  Cleared at the start of every `extractModule`. */
+const _externs = new Map();
+let _currentSourceFile = null;
+/** True only while extracting a function body. Module-level constants that
+ *  reference cross-file callees (e.g., `BusEvent.define(...)` inside a
+ *  module-level record) would otherwise pollute the output with externs
+ *  that no verified function actually calls — and whose TS return types
+ *  often don't translate to valid Dafny. */
+let _inFunctionExtraction = false;
+/** Counter for synthetic names used by let-statement array destructuring
+ *  when the initializer isn't a bare variable (single-eval temp). */
+let _destrCounter = 0;
+/** Register the call's callee as a cross-file extern if applicable, then
+ *  walk the source declaration's body for nested cross-file calls (so the
+ *  lifted `requires`/`ensures` see all the symbols they reference). Idempotent
+ *  via the `_externs` dedup. */
+function registerExternIfCrossFile(callee, sourceFile) {
+    const ext = detectCrossFileExtern(callee, sourceFile);
+    if (!ext || _externs.has(ext.qualified))
+        return;
+    _externs.set(ext.qualified, ext);
+    // Recurse: scan the source decl's body for nested cross-file calls so any
+    // symbol referenced by the copied spec is itself declared in the output.
+    let symbol = callee.getSymbol();
+    if (!symbol)
+        return;
+    const aliased = symbol.getAliasedSymbol();
+    if (aliased)
+        symbol = aliased;
+    const sourceDecl = symbol.getDeclarations().find(d => d.getSourceFile().getFilePath() !== sourceFile.getFilePath());
+    if (!sourceDecl)
+        return;
+    const sourceSF = sourceDecl.getSourceFile();
+    const body = sourceDecl.getBody?.();
+    if (!body)
+        return;
+    for (const inner of body.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const innerCallee = inner.getExpression();
+        if (Node.isPropertyAccessExpression(innerCallee) || Node.isIdentifier(innerCallee)) {
+            registerExternIfCrossFile(innerCallee, sourceSF);
+        }
+    }
+}
+function detectCrossFileExtern(callee, sourceFile) {
+    let symbol = callee.getSymbol();
+    if (!symbol)
+        return null;
+    // For bare imports `import { foo } from "..."`, the call-site symbol is the
+    // local ImportSpecifier — declared in the current file. Follow the alias to
+    // the original `export function` declaration.
+    const aliased = symbol.getAliasedSymbol();
+    if (aliased)
+        symbol = aliased;
+    const decls = symbol.getDeclarations();
+    if (decls.length === 0)
+        return null;
+    const currentPath = sourceFile.getFilePath();
+    const externalDecl = decls.find(d => d.getSourceFile().getFilePath() !== currentPath);
+    if (!externalDecl)
+        return null;
+    // Skip stdlib / typings — those have built-in dispatch elsewhere or are
+    // genuinely out of LS's verification model.
+    if (externalDecl.getSourceFile().getFilePath().endsWith(".d.ts"))
+        return null;
+    const sig = callee.getType().getCallSignatures()[0];
+    if (!sig)
+        return null;
+    // Generic type parameters (e.g. `step<S, A>`). ts-morph reports param/return
+    // types in the callee's own type-parameter namespace, so these names match
+    // what `params`/`returnType` reference — declare them on the emitted axiom.
+    const typeParams = sig.getTypeParameters().map(tp => tp.getText());
+    const params = sig.getParameters().map(p => ({
+        name: p.getName(),
+        tsType: p.getTypeAtLocation(callee).getText(),
+    }));
+    const returnType = sig.getReturnType().getText();
+    let qualified;
+    if (Node.isPropertyAccessExpression(callee)) {
+        qualified = `${callee.getExpression().getText()}.${callee.getName()}`;
+    }
+    else {
+        qualified = callee.getText();
+    }
+    const flat = qualified.replace(/\./g, "_");
+    // Lift `//@ requires`/`//@ ensures` from the source declaration so callers
+    // reason against the source's verified contract, not an unconstrained axiom.
+    const annots = collectFunctionAnnotations(externalDecl);
+    const requires = annots.filter(a => a.kind === "requires").map(a => a.expr);
+    const ensures = annots.filter(a => a.kind === "ensures").map(a => a.expr);
+    return { qualified, flat, typeParams, params, returnType, requires, ensures };
+}
+/** Build a concat-tree from a mixed list of literal and SpreadElement nodes.
+ *  Literals collapse into arrayLiteral segments; spreads become bare expressions;
+ *  segments are joined with `arrayConcat`. Used by array-literal and Math.max/min
+ *  call-arg spread.
+ *  Precondition: at least one element. */
+function buildSpreadConcat(elems) {
+    const segments = [];
+    let currentLiterals = [];
+    for (const e of elems) {
+        if (Node.isSpreadElement(e)) {
+            if (currentLiterals.length > 0) {
+                segments.push({ kind: "arrayLiteral", elems: currentLiterals });
+                currentLiterals = [];
+            }
+            segments.push(extractExpr(e.getExpression()));
+        }
+        else {
+            currentLiterals.push(extractExpr(e));
+        }
+    }
+    if (currentLiterals.length > 0) {
+        segments.push({ kind: "arrayLiteral", elems: currentLiterals });
+    }
+    let result = segments[0];
+    for (let i = 1; i < segments.length; i++) {
+        result = { kind: "binop", op: "arrayConcat", left: result, right: segments[i] };
+    }
+    return result;
+}
 /**
  * Maps property-name fingerprints to type alias names for collapsed single-variant unions.
  * TypeScript collapses `type X = | { kind: 'A'; ... }` to the underlying object type,
@@ -15,8 +139,116 @@ let _havocKey = null;
  * Populated in extractModule before type extraction; used by typeToString.
  */
 let _collapsedUnionMap = new Map();
+/**
+ * Accumulator for synthesized `T[] | U` array-union datatypes.
+ *
+ * Plain TS unions like `string | Part[]` have no backend image (LemmaScript
+ * models tagged unions only). When typeToString encounters a binary union
+ * where one member is an array and the other is not array/undefined/null,
+ * it synthesizes a discriminated-union TypeDeclInfo with variants
+ * ArrayBranch(arr: T[]) and NonArrayBranch(val: U) and returns the synthetic
+ * name in place of "T[] | U". The runtime discriminator is `Array.isArray`,
+ * lowered to a tag predicate by narrow/transform.
+ *
+ * Set in extractModule to the module's typeDecls; cleared at end. When null,
+ * typeToString falls through to the existing union path.
+ */
+let _synthArrayUnions = null;
+/** Sanitize an arbitrary type-string fragment for use inside a generated identifier. */
+function _synthName(elemName, otherName) {
+    const sanitize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+    return `ArrayOf_${sanitize(elemName)}_Or_${sanitize(otherName)}`;
+}
+/**
+ * String-level fallback for synth detection on a `T[] | U` shape, used by
+ * declare-type field parsing (where no ts-morph TypeNode is available). The
+ * format inside declare-type is user-controlled and structurally simple, so
+ * a split-on-` | ` is acceptable in that bounded context. Returns the synth
+ * name if matched, registers a TypeDeclInfo into the accumulator, else null.
+ */
+function _synthFromTsTypeString(ts) {
+    if (_synthArrayUnions === null)
+        return null;
+    if (!ts.includes(" | "))
+        return null;
+    const arms = ts.split(" | ").map(s => s.trim());
+    if (arms.length !== 2)
+        return null;
+    if (arms.some(a => a === "undefined" || a === "null"))
+        return null;
+    const arrIdx = arms.findIndex(a => a.endsWith("[]"));
+    if (arrIdx === -1)
+        return null;
+    const otherIdx = 1 - arrIdx;
+    if (arms[otherIdx].endsWith("[]"))
+        return null;
+    const elem = arms[arrIdx].slice(0, -2);
+    const other = arms[otherIdx];
+    const synthName = _synthName(elem, other);
+    if (!_synthArrayUnions.some(d => d.name === synthName)) {
+        _synthArrayUnions.push({
+            name: synthName,
+            kind: "discriminated-union",
+            discriminant: "__isArray__",
+            variants: [
+                { name: "ArrayBranch", fields: [{ name: "arr", tsType: `${elem}[]` }] },
+                { name: "NonArrayBranch", fields: [{ name: "val", tsType: other }] },
+            ],
+        });
+    }
+    return synthName;
+}
+/**
+ * Compute a tsType string from a syntactic union TypeNode (`T | U`), preserving
+ * the member nodes' source text (so `type ListId = number` stays `ListId`,
+ * which ts-morph erases when you read the resolved Type). When the union matches
+ * the `T[] | U` synth shape (U not array/undefined/null), registers a synth-
+ * array-union TypeDeclInfo and returns its synthetic name. Otherwise returns
+ * the syntactic join (so `ListId | undefined` stays a recognizable union for
+ * parseTsType to wrap as Option<ListId>).
+ *
+ * This is the param/return-type counterpart of the typeToString synthesis hook,
+ * which handles record/interface field types via the Type-driven path.
+ */
+function _tsTypeFromUnionNode(tn) {
+    if (!Node.isUnionTypeNode(tn))
+        return tn.getText();
+    const members = tn.getTypeNodes();
+    if (_synthArrayUnions !== null && members.length === 2) {
+        const arrIdx = members.findIndex(m => m.getType().isArray());
+        if (arrIdx !== -1) {
+            const other = members[1 - arrIdx];
+            const ot = other.getType();
+            if (!ot.isArray() && !ot.isUndefined() && !ot.isNull()) {
+                const arrNode = members[arrIdx];
+                const elemName = Node.isArrayTypeNode(arrNode)
+                    ? arrNode.getElementTypeNode().getText()
+                    : typeToString(arrNode.getType().getArrayElementTypeOrThrow());
+                const otherName = other.getText();
+                const synthName = _synthName(elemName, otherName);
+                if (!_synthArrayUnions.some(d => d.name === synthName)) {
+                    _synthArrayUnions.push({
+                        name: synthName,
+                        kind: "discriminated-union",
+                        discriminant: "__isArray__",
+                        variants: [
+                            { name: "ArrayBranch", fields: [{ name: "arr", tsType: `${elemName}[]` }] },
+                            { name: "NonArrayBranch", fields: [{ name: "val", tsType: otherName }] },
+                        ],
+                    });
+                }
+                return synthName;
+            }
+        }
+    }
+    return members.map(m => m.getText()).join(" | ");
+}
 /** Generic bounds erasure map — set during extractFunction, applied in extractStmts. */
 let _typeParamMap = new Map();
+// Fresh for-counter names allocated in the current function — so two sibling
+// loops that both need renaming don't independently pick the same `<name>_N`
+// (detection is read-only, so the source still shows the original names).
+let _reservedForCounterNames = new Set();
 function _eraseGenerics(tsType) {
     if (_typeParamMap.size === 0)
         return tsType;
@@ -125,6 +357,28 @@ function extractExpr(node) {
             node.getArguments().length === 1) {
             return extractExpr(node.getArguments()[0]);
         }
+        // Math.max(...) / Math.min(...) with spread args → MaxOfSeq(seq) / MinOfSeq(seq)
+        // The spread is desugared at extract time; resolve and downstream passes
+        // see an ordinary function call.
+        if (Node.isPropertyAccessExpression(callee) &&
+            callee.getExpression().getText() === "Math" &&
+            (callee.getName() === "max" || callee.getName() === "min")) {
+            const argNodes = node.getArguments();
+            if (argNodes.some(a => Node.isSpreadElement(a))) {
+                const combined = buildSpreadConcat(argNodes);
+                const fnName = callee.getName() === "max" ? "MaxOfSeq" : "MinOfSeq";
+                return { kind: "call", fn: { kind: "var", name: fnName }, args: [combined] };
+            }
+        }
+        // Auto-extern: if the callee resolves (via ts-morph) to a symbol declared
+        // in a different `.ts` file, register it as an opaque extern. Covers both
+        // `Obj.method(...)` and bare `foo(...)` imports. Skipped for stdlib/.d.ts
+        // declarations — those are either built-in methods (handled in dafny-emit)
+        // or genuinely out of scope.
+        if (_currentSourceFile && _inFunctionExtraction &&
+            (Node.isPropertyAccessExpression(callee) || Node.isIdentifier(callee))) {
+            registerExternIfCrossFile(callee, _currentSourceFile);
+        }
         const fn = extractExpr(callee);
         const args = node.getArguments().map(a => extractExpr(a));
         if (node.hasQuestionDotToken()) {
@@ -193,30 +447,8 @@ function extractExpr(node) {
         if (!hasSpread) {
             return { kind: "arrayLiteral", elems: elems.map(e => extractExpr(e)) };
         }
-        // Build concatenation: [a, ...b, c] → [a] + b + [c]
-        // Group consecutive non-spread elements into array literals, spreads are bare
-        const segments = [];
-        let currentLiterals = [];
-        for (const e of elems) {
-            if (Node.isSpreadElement(e)) {
-                if (currentLiterals.length > 0) {
-                    segments.push({ kind: "arrayLiteral", elems: currentLiterals });
-                    currentLiterals = [];
-                }
-                segments.push(extractExpr(e.getExpression()));
-            }
-            else {
-                currentLiterals.push(extractExpr(e));
-            }
-        }
-        if (currentLiterals.length > 0) {
-            segments.push({ kind: "arrayLiteral", elems: currentLiterals });
-        }
-        // Fold segments with arrayConcat
-        let result = segments[0];
-        for (let i = 1; i < segments.length; i++) {
-            result = { kind: "binop", op: "arrayConcat", left: result, right: segments[i] };
-        }
+        // [a, ...b, c] → [a] + b + [c] via shared helper
+        const result = buildSpreadConcat(elems);
         return result;
     }
     // Object literal: { res: true, done: false } or { ...obj, res: true }
@@ -239,7 +471,10 @@ function extractExpr(node) {
                     computedFields.push({ key: extractExpr(nameNode.getExpression()), value: extractExpr(init) });
                 }
                 else if (init) {
-                    fields.push({ name: prop.getName(), value: extractExpr(init) });
+                    // String-literal keys (e.g. `"bun run": 3`) — use the unquoted literal
+                    // value; otherwise `prop.getName()` may include surrounding quotes.
+                    const name = Node.isStringLiteral(nameNode) ? nameNode.getLiteralValue() : prop.getName();
+                    fields.push({ name, value: extractExpr(init) });
                 }
             }
         }
@@ -345,6 +580,27 @@ function collectAnnotations(node, body) {
         return [...own, ...parseAnnotations(body[0])];
     return own;
 }
+// A loop's `//@ invariant`/`decreases`/`done_with` annotations live as leading
+// comments of its first body statement — never on the loop node itself. (The
+// loop node's own leading comments belong to whatever precedes it; when the
+// loop is the first statement of an *enclosing* loop, those comments are the
+// enclosing loop's invariants, which must not leak in.) So collect from the
+// body alone, unlike `collectAnnotations`, which also reads the node (needed for
+// functions, whose specs may precede the declaration).
+function collectLoopAnnotations(body) {
+    return body.length > 0 ? parseAnnotations(body[0]) : [];
+}
+/** All `//@ ` annotations for a function-like node, regardless of whether its
+ *  body is a block (annotations on the first statement) or an expression-body
+ *  arrow (annotations only on the declaration). Used both for in-file function
+ *  extraction and for pulling specs off cross-file externs. */
+function collectFunctionAnnotations(fn) {
+    const body = fn.getBody?.();
+    if (body && Node.isBlock(body)) {
+        return collectAnnotations(fn, body.getStatements());
+    }
+    return collectAnnotations(fn);
+}
 /** Check for bare `//@ pure` annotation (no expression). */
 function hasPureAnnotation(node, body) {
     const nodes = body && body.length > 0 ? [node, body[0]] : [node];
@@ -362,6 +618,12 @@ function extractTypeDecl(decl, extraDecls) {
     const type = decl.getType();
     const typeParams = decl.getTypeParameters().map(tp => tp.getName());
     const tpField = typeParams.length > 0 ? typeParams : undefined;
+    // Leading `//@ type <ty>` overrides extraction — the declared TS type is
+    // replaced by the annotated backend type. Used to coerce literal unions
+    // (`5 | 15 | 30` → `nat`) and other types LS can't model precisely.
+    const override = parseAnnotations(decl).find(a => a.kind === "type");
+    if (override)
+        return { name, typeParams: tpField, kind: "alias", aliasOf: override.expr };
     if (type.isUnion()) {
         const members = type.getUnionTypes();
         if (members.every(m => m.isStringLiteral())) {
@@ -379,7 +641,12 @@ function extractTypeDecl(decl, extraDecls) {
                     for (const prop of m.getProperties()) {
                         if (prop.getName() === discriminant)
                             continue;
-                        fields.push({ name: prop.getName(), tsType: typeToString(prop.getTypeAtLocation(decl)) });
+                        let tsType = typeToString(prop.getTypeAtLocation(decl));
+                        const propDecl = prop.getDeclarations()[0];
+                        if (propDecl && propDecl.hasQuestionToken?.() && !tsType.includes(" | undefined")) {
+                            tsType = `${tsType} | undefined`;
+                        }
+                        fields.push({ name: prop.getName(), tsType });
                     }
                     return { name: tag, fields };
                 });
@@ -411,6 +678,29 @@ function extractTypeDecl(decl, extraDecls) {
             }
         }
     }
+    // Function-type alias: `type Comparator = (a: T, b: T) => boolean` —
+    // ts-morph reports these as object-typed with a call signature and no
+    // user-visible properties. Emit as a Dafny `type X = (...) -> R` alias.
+    if (type.isObject()) {
+        const sig = type.getCallSignatures()[0];
+        const hasProps = type.getProperties().length > 0;
+        if (sig && !hasProps) {
+            // Synthesize fresh param names — the ts-morph parser used downstream
+            // needs `name: T` syntax; bare `T` is read as a param name with `any`.
+            const params = sig.getParameters().map((p, i) => `_p${i}: ${typeToString(p.getTypeAtLocation(decl))}`);
+            const ret = typeToString(sig.getReturnType());
+            return { name, kind: "alias", aliasOf: `(${params.join(", ")}) => ${ret}` };
+        }
+    }
+    // Array-type alias: `type Board = number[]` → alias to the seq type, not a
+    // record. Arrays report as object types, so this must precede the record
+    // branch, which would otherwise enumerate the Array prototype as fields.
+    // Build the element type directly: typeToString(type) would return the
+    // alias's own name (via getAliasSymbol), yielding a self-referential alias.
+    if (type.isArray()) {
+        const elem = type.getArrayElementTypeOrThrow();
+        return { name, typeParams: tpField, kind: "alias", aliasOf: `${typeToString(elem)}[]` };
+    }
     if (type.isObject() || type.isIntersection())
         return extractRecord(name, type, decl, undefined, extraDecls);
     // Primitive type alias: type TaskId = number → alias
@@ -445,6 +735,13 @@ function extractRecord(name, type, locationNode, overrides, extraDecls) {
         }
         const propType = prop.getTypeAtLocation(locationNode);
         let tsType = typeToString(propType);
+        // Optional property: `foo?: T` reports as `T` (ts-morph strips the
+        // `| undefined` from a question-token type). Add it back so the field
+        // resolves to `Optional<T>`.
+        const propDecl = prop.getDeclarations()[0];
+        if (propDecl && propDecl.hasQuestionToken?.() && !tsType.includes(" | undefined")) {
+            tsType = `${tsType} | undefined`;
+        }
         // Inline anonymous object types: ts-morph names them __type.
         // Generate a synthetic named record and reference it by name instead.
         if (extraDecls && tsType.includes("__type")) {
@@ -510,7 +807,37 @@ function typeToString(type) {
         return name;
     }
     if (type.isUnion()) {
-        const parts = [...new Set(type.getUnionTypes().map(typeToString))];
+        const unionTypes = type.getUnionTypes();
+        // `T[] | U` synthesis: exactly two members, one array, the other not
+        // array/undefined/null. Detected via ts-morph type predicates (no string
+        // parsing). Registers a discriminated-union TypeDeclInfo with variants
+        // ArrayBranch(arr: T[]) and NonArrayBranch(val: U); returns the synthetic
+        // name so all downstream tsType slots agree. `T[] | undefined` and
+        // `T[] | T[]` fall through to the existing path unchanged.
+        if (_synthArrayUnions !== null && unionTypes.length === 2) {
+            const [m0, m1] = unionTypes;
+            const arrayMember = m0.isArray() ? m0 : (m1.isArray() ? m1 : null);
+            const otherMember = arrayMember === m0 ? m1 : m0;
+            if (arrayMember && otherMember && !otherMember.isArray()
+                && !otherMember.isUndefined() && !otherMember.isNull()) {
+                const elemName = typeToString(arrayMember.getArrayElementTypeOrThrow());
+                const otherName = typeToString(otherMember);
+                const synthName = _synthName(elemName, otherName);
+                if (!_synthArrayUnions.some(d => d.name === synthName)) {
+                    _synthArrayUnions.push({
+                        name: synthName,
+                        kind: "discriminated-union",
+                        discriminant: "__isArray__",
+                        variants: [
+                            { name: "ArrayBranch", fields: [{ name: "arr", tsType: `${elemName}[]` }] },
+                            { name: "NonArrayBranch", fields: [{ name: "val", tsType: otherName }] },
+                        ],
+                    });
+                }
+                return synthName;
+            }
+        }
+        const parts = [...new Set(unionTypes.map(typeToString))];
         return parts.join(" | ");
     }
     if (type.isTuple()) {
@@ -540,7 +867,171 @@ function typeToString(type) {
 }
 const COMPOUND_OPS = {
     "+=": "+", "-=": "-", "*=": "*", "/=": "/", "%=": "%",
+    "<<=": "<<", ">>=": ">>", "|=": "|", "&=": "&", "^=": "^", "**=": "**",
 };
+/** Desugar a statement-position side-effecting expression — `x = e`, `x += e`,
+ *  `i++`, `arr[i] = v`, etc. — into a `RawAssign`. Returns null when no shape
+ *  match (caller emits a plain `{kind: "expr"}` or errors). Called by both
+ *  `ExpressionStatement` extraction (wrapped) and the C-style for-loop
+ *  incrementor (bare Expression — same shape, no `;` wrapper). */
+function desugarStmtExpr(expr, line) {
+    if (Node.isBinaryExpression(expr)) {
+        const opText = expr.getOperatorToken().getText();
+        const left = expr.getLeft();
+        if (opText === "=" && Node.isElementAccessExpression(left)) {
+            const obj = extractExpr(left.getExpression());
+            const idx = extractExpr(left.getArgumentExpression());
+            const val = extractExpr(expr.getRight());
+            const target = left.getExpression().getText();
+            const withCall = { kind: "call", fn: { kind: "field", obj, field: "with" }, args: [idx, val] };
+            return { kind: "assign", target, value: withCall, line };
+        }
+        if (opText === "=") {
+            return { kind: "assign", target: left.getText(), value: extractExpr(expr.getRight()), line };
+        }
+        const compound = COMPOUND_OPS[opText];
+        if (compound) {
+            const target = left.getText();
+            return {
+                kind: "assign", target,
+                value: { kind: "binop", op: compound, left: { kind: "var", name: target }, right: extractExpr(expr.getRight()) },
+                line,
+            };
+        }
+    }
+    if ((Node.isPostfixUnaryExpression(expr) || Node.isPrefixUnaryExpression(expr)) &&
+        (expr.getOperatorToken() === SyntaxKind.PlusPlusToken || expr.getOperatorToken() === SyntaxKind.MinusMinusToken)) {
+        const target = expr.getOperand().getText();
+        const op = expr.getOperatorToken() === SyntaxKind.PlusPlusToken ? "+" : "-";
+        return {
+            kind: "assign", target,
+            value: { kind: "binop", op, left: { kind: "var", name: target }, right: { kind: "num", value: 1 } },
+            line,
+        };
+    }
+    return null;
+}
+// A C-style `for (let i …)` counter is hoisted out of its loop scope into the
+// enclosing block (the desugar runs `init; while (cond) { body; update }`). If
+// another binding of that name shares the hoisted scope — a sibling `let i`, or
+// an enclosing for-loop whose own `i` stays live where the inner counter and the
+// outer update sit — the two collapse to one Dafny `var i` ("Duplicate
+// local-variable name", or a silently-misbound update). When that happens we
+// rename this counter to a fresh `<name>_N` in the loop's own desugared pieces.
+//
+// `forCounterRename` is a read-only scope check (no AST mutation): it returns the
+// fresh name when this counter would collide, else null — so a non-conflicting
+// loop keeps its name and output is byte-identical. The rename itself is applied
+// to the extracted Raw IR by `renameRawStmts` / `renameRawExpr` (code) and
+// `renameSpec` (the `//@` strings, still unparsed at this phase).
+function forCounterRename(decl, forStmt) {
+    const name = decl.getName();
+    const fnLike = forStmt.getFirstAncestor(a => Node.isFunctionDeclaration(a) || Node.isArrowFunction(a) ||
+        Node.isFunctionExpression(a) || Node.isMethodDeclaration(a));
+    const scopeRoot = fnLike ?? forStmt.getSourceFile();
+    const isScope = (a) => Node.isBlock(a) || Node.isSourceFile(a) ||
+        Node.isForStatement(a) || Node.isForOfStatement(a) || Node.isForInStatement(a);
+    // Scopes that enclose this loop — its counter, once hoisted, lives in one of
+    // these, so a same-named binding scoped here would collide.
+    const enclosing = new Set(forStmt.getAncestors());
+    const paramClash = fnLike?.getParameters?.().some((p) => p.getName() === name) ?? false;
+    const declClash = scopeRoot.getDescendantsOfKind(SyntaxKind.VariableDeclaration).some(d => {
+        if (d === decl || d.getName() !== name)
+            return false;
+        const scope = d.getFirstAncestor(isScope);
+        return !!scope && enclosing.has(scope);
+    });
+    if (!paramClash && !declClash)
+        return null;
+    const used = new Set(scopeRoot.getDescendantsOfKind(SyntaxKind.Identifier).map(i => i.getText()));
+    let n = 2;
+    while (used.has(`${name}_${n}`) || _reservedForCounterNames.has(`${name}_${n}`))
+        n++;
+    const fresh = `${name}_${n}`;
+    _reservedForCounterNames.add(fresh);
+    return fresh;
+}
+/** Whole-word rename of an identifier inside an unparsed `//@` spec string. */
+function renameSpec(s, from, to) {
+    return s.replace(new RegExp(`\\b${from}\\b`, "g"), to);
+}
+/** Rename free references to `from` → `to` in a Raw expression, stopping under a
+ *  lambda / quantifier that re-binds the name (it shadows). */
+function renameRawExpr(e, from, to) {
+    const r = (x) => renameRawExpr(x, from, to);
+    switch (e.kind) {
+        case "var": return e.name === from ? { kind: "var", name: to } : e;
+        case "num":
+        case "str":
+        case "bool":
+        case "result":
+        case "havoc":
+        case "emptyCollection": return e;
+        case "binop": return { ...e, left: r(e.left), right: r(e.right) };
+        case "unop": return { ...e, expr: r(e.expr) };
+        case "call": return { ...e, fn: r(e.fn), args: e.args.map(r) };
+        case "index": return { ...e, obj: r(e.obj), idx: r(e.idx) };
+        case "field": return { ...e, obj: r(e.obj) };
+        case "record": return { ...e, spread: e.spread ? r(e.spread) : null, fields: e.fields.map(f => ({ ...f, value: r(f.value) })) };
+        case "arrayLiteral": return { ...e, elems: e.elems.map(r) };
+        case "conditional": return { ...e, cond: r(e.cond), then: r(e.then), else: r(e.else) };
+        case "nullish": return { ...e, left: r(e.left), right: r(e.right) };
+        case "nonNull": return { ...e, expr: r(e.expr) };
+        case "optChain": return { ...e, obj: r(e.obj), chain: e.chain.map(c => c.kind === "call" ? { ...c, args: c.args.map(r) } : c.kind === "index" ? { ...c, idx: r(c.idx) } : c) };
+        case "lambda": return e.params.some(p => p.name === from) ? e
+            : { ...e, body: Array.isArray(e.body) ? renameRawStmts(e.body, from, to) : r(e.body) };
+        case "forall":
+        case "exists": return e.var === from ? e : { ...e, body: r(e.body) };
+    }
+}
+/** Rename references to `from` → `to` across a Raw statement (code refs via
+ *  `renameRawExpr`, `//@` strings via `renameSpec`). Statement lists stop
+ *  renaming once a `let from` re-declares the name (it shadows). */
+function renameRawStmt(s, from, to) {
+    const r = (x) => renameRawExpr(x, from, to);
+    const sp = (x) => renameSpec(x, from, to);
+    switch (s.kind) {
+        case "let": return { ...s, init: r(s.init) }; // name kept: a shadowing binding is a different variable
+        case "assign": return { ...s, target: s.target === from ? to : s.target, value: r(s.value) };
+        case "return": return { ...s, value: r(s.value) };
+        case "expr": return { ...s, expr: r(s.expr) };
+        case "if": return { ...s, cond: r(s.cond), then: renameRawStmts(s.then, from, to), else: renameRawStmts(s.else, from, to) };
+        case "while": return { ...s, cond: r(s.cond), invariants: s.invariants.map(sp),
+            decreases: s.decreases ? sp(s.decreases) : null, doneWith: s.doneWith ? sp(s.doneWith) : null,
+            body: renameRawStmts(s.body, from, to) };
+        case "forof": return e_forof(s);
+        case "switch": return { ...s, expr: r(s.expr), cases: s.cases.map(c => ({ ...c, body: renameRawStmts(c.body, from, to) })),
+            defaultBody: renameRawStmts(s.defaultBody, from, to) };
+        case "ghostLet": return { ...s, init: sp(s.init) };
+        case "ghostAssign": return { ...s, target: s.target === from ? to : s.target, value: sp(s.value) };
+        case "assert": return { ...s, expr: sp(s.expr) };
+        case "break":
+        case "continue":
+        case "throw": return s;
+    }
+    function e_forof(f) {
+        // for-of names bind in the body; if one shadows `from`, leave the body alone.
+        const body = f.names.includes(from) ? f.body : renameRawStmts(f.body, from, to);
+        return { ...f, iterable: r(f.iterable), invariants: f.invariants.map(sp),
+            doneWith: f.doneWith ? sp(f.doneWith) : null, body };
+    }
+}
+/** Rename `from` → `to` through a statement list, stopping after a `let from`
+ *  shadows it (subsequent references are a different variable). */
+function renameRawStmts(stmts, from, to) {
+    const out = [];
+    let active = true;
+    for (const s of stmts) {
+        if (!active) {
+            out.push(s);
+            continue;
+        }
+        out.push(renameRawStmt(s, from, to));
+        if (s.kind === "let" && s.name === from)
+            active = false;
+    }
+    return out;
+}
 // ── Statement extraction ─────────────────────────────────────
 /** Parse ghost and assert annotations from comment ranges. */
 function parseSpecComments(ranges, line) {
@@ -555,13 +1046,19 @@ function parseSpecComments(ranges, line) {
             result.push({ kind: "assert", expr: content.slice(7).trim(), line });
             continue;
         }
+        // assume expr — trusted form of assert; emitted as `assume P;` in Dafny.
+        if (content.startsWith("assume ")) {
+            result.push({ kind: "assert", expr: content.slice(7).trim(), line, assumed: true });
+            continue;
+        }
         if (!content.startsWith("ghost "))
             continue;
         const ghostBody = content.slice(6).trim();
         // ghost let varName: type = expr  OR  ghost let varName = expr
-        const letMatch = ghostBody.match(/^let\s+(\w+)(?:\s*:\s*(\w+))?\s*=\s*(.+)$/);
+        // Type segment accepts compound forms like `number[]`, `Map<K,V>`, etc.
+        const letMatch = ghostBody.match(/^let\s+(\w+)(?:\s*:\s*([^=]+?))?\s*=\s*(.+)$/);
         if (letMatch) {
-            result.push({ kind: "ghostLet", name: letMatch[1], tsType: letMatch[2] ?? null, init: letMatch[3].trim(), line });
+            result.push({ kind: "ghostLet", name: letMatch[1], tsType: letMatch[2]?.trim() ?? null, init: letMatch[3].trim(), line });
             continue;
         }
         // ghost varName = expr
@@ -572,6 +1069,34 @@ function parseSpecComments(ranges, line) {
     }
     return result;
 }
+/** Splice `update` before each `continue` in the same loop scope. Recurses
+ *  into `if`/`switch` (same scope) but not nested `while`/`forof` (they own
+ *  their own continue). Used by the C-style `for` desugar so a `continue`
+ *  doesn't skip the loop update. The `update` node is shared by reference —
+ *  the IR is transformed functionally downstream (no in-place mutation), so
+ *  aliasing it across the body is safe. */
+function insertUpdateBeforeContinue(stmts, update) {
+    const out = [];
+    for (const s of stmts) {
+        if (s.kind === "continue") {
+            out.push(update, s);
+        }
+        else if (s.kind === "if") {
+            out.push({ ...s, then: insertUpdateBeforeContinue(s.then, update), else: insertUpdateBeforeContinue(s.else, update) });
+        }
+        else if (s.kind === "switch") {
+            out.push({
+                ...s,
+                cases: s.cases.map(c => ({ ...c, body: insertUpdateBeforeContinue(c.body, update) })),
+                defaultBody: insertUpdateBeforeContinue(s.defaultBody, update),
+            });
+        }
+        else {
+            out.push(s);
+        }
+    }
+    return out;
+}
 function extractStmts(stmts) {
     const result = [];
     for (const s of stmts) {
@@ -609,6 +1134,89 @@ function extractStmts(stmts) {
                     }
                     continue;
                 }
+                // Array destructuring: const [a, , c, ...rest] = arr → individual lets,
+                // each picking from `arr` by position. Rest (if present) must be last
+                // and emits as `arr.slice(N)`. Omitted slots (`,,`) are skipped. Nested
+                // binding patterns throw — extend the helper here when a case study
+                // hits them.
+                if (!isHavoc && Node.isArrayBindingPattern(nameNode)) {
+                    const elements = nameNode.getElements();
+                    const initializer = d.getInitializer();
+                    if (initializer) {
+                        let initExpr = extractExpr(initializer);
+                        let initVar = initExpr;
+                        if (initExpr.kind !== "var") {
+                            const tempName = `_destr${_destrCounter++}`;
+                            const initTs = _eraseGenerics(typeToString(initializer.getType()));
+                            result.push({ kind: "let", name: tempName, mutable: false, tsType: initTs, init: initExpr, line });
+                            initVar = { kind: "var", name: tempName };
+                        }
+                        for (let i = 0; i < elements.length; i++) {
+                            const el = elements[i];
+                            if (Node.isOmittedExpression(el))
+                                continue;
+                            if (!Node.isBindingElement(el))
+                                continue;
+                            const inner = el.getNameNode();
+                            if (!Node.isIdentifier(inner)) {
+                                throw new Error(`nested binding pattern in array destructuring not yet supported: ${el.getText()}`);
+                            }
+                            const name = inner.getText();
+                            const isRest = !!el.getDotDotDotToken();
+                            const elTs = _eraseGenerics(typeToString(el.getType()));
+                            const init = isRest
+                                ? { kind: "call",
+                                    fn: { kind: "field", obj: initVar, field: "slice" },
+                                    args: [{ kind: "num", value: i }] }
+                                : { kind: "index", obj: initVar, idx: { kind: "num", value: i } };
+                            result.push({ kind: "let", name, mutable: s.getDeclarationKind() === "let", tsType: elTs, init, line });
+                        }
+                        continue;
+                    }
+                }
+                // Plain object destructuring: const { a, b, c } = obj → field access lets.
+                // Skipped if any element has a computed property (handled by the rest+
+                // computed branch below) or a rest element (also handled below).
+                if (!isHavoc && Node.isObjectBindingPattern(nameNode)) {
+                    const elements = nameNode.getElements();
+                    const hasRest = elements.some(el => el.getDotDotDotToken());
+                    const hasComputed = elements.some(el => {
+                        const pn = el.getPropertyNameNode();
+                        return pn && Node.isComputedPropertyName(pn);
+                    });
+                    if (!hasRest && !hasComputed) {
+                        const initializer = d.getInitializer();
+                        if (initializer) {
+                            let initExpr = extractExpr(initializer);
+                            let initVar = initExpr;
+                            if (initExpr.kind !== "var") {
+                                const tempName = `_destr${_destrCounter++}`;
+                                const initTs = _eraseGenerics(typeToString(initializer.getType()));
+                                result.push({ kind: "let", name: tempName, mutable: false, tsType: initTs, init: initExpr, line });
+                                initVar = { kind: "var", name: tempName };
+                            }
+                            for (const el of elements) {
+                                const inner = el.getNameNode();
+                                if (!Node.isIdentifier(inner)) {
+                                    throw new Error(`nested binding pattern in object destructuring not yet supported: ${el.getText()}`);
+                                }
+                                const localName = inner.getText();
+                                const propNode = el.getPropertyNameNode();
+                                const fieldName = propNode ? propNode.getText() : localName;
+                                const elTs = _eraseGenerics(typeToString(el.getType()));
+                                result.push({
+                                    kind: "let",
+                                    name: localName,
+                                    mutable: s.getDeclarationKind() === "let",
+                                    tsType: elTs,
+                                    init: { kind: "field", obj: initVar, field: fieldName },
+                                    line,
+                                });
+                            }
+                            continue;
+                        }
+                    }
+                }
                 // Destructuring rest: const { [k]: _, ...rest } = map → let rest = map.delete(k)
                 if (!isHavoc && Node.isObjectBindingPattern(nameNode)) {
                     const elements = nameNode.getElements();
@@ -651,14 +1259,56 @@ function extractStmts(stmts) {
                 else {
                     const initializer = d.getInitializer();
                     _havocKey = havocKey;
-                    init = initializer ? extractExpr(initializer) : { kind: "var", name: "default" };
+                    if (initializer) {
+                        init = extractExpr(initializer);
+                    }
+                    else {
+                        // No initializer — emit a type-appropriate default so the emitted
+                        // Dafny binding `var x: T := <default>;` typechecks. The empty-
+                        // collection cases are picked up by dafny-emit's let case, which
+                        // adds an explicit `: T` annotation for inference.
+                        const tsType = _eraseGenerics(d.getTypeNode()?.getText() ?? typeToString(declType));
+                        const isOptional = / \| (null|undefined)\b/.test(tsType)
+                            || /^(null|undefined) \| /.test(tsType)
+                            || tsType.endsWith(" | undefined") || tsType.endsWith(" | null");
+                        const isArray = tsType.endsWith("[]") || /^Array</.test(tsType) || /^readonly /.test(tsType);
+                        const isMap = /^Map</.test(tsType);
+                        const isSet = /^Set</.test(tsType);
+                        if (isOptional)
+                            init = { kind: "var", name: "undefined" };
+                        else if (isArray)
+                            init = { kind: "arrayLiteral", elems: [] };
+                        else if (isMap)
+                            init = { kind: "emptyCollection", collectionType: "Map", tsType };
+                        else if (isSet)
+                            init = { kind: "emptyCollection", collectionType: "Set", tsType };
+                        else if (tsType === "number")
+                            init = { kind: "num", value: 0 };
+                        else if (tsType === "boolean")
+                            init = { kind: "bool", value: false };
+                        else if (tsType === "string")
+                            init = { kind: "str", value: "" };
+                        else
+                            init = { kind: "var", name: "default" };
+                    }
                     _havocKey = null;
                 }
+                // Use the source-level type annotation if present — ts-morph's
+                // `d.getType()` strips `| undefined` from optional annotations.
+                // When no annotation, fall back to ts-morph's inferred type — except
+                // when the inference collapses to `any` (e.g. brownfield imports
+                // where the imported declaration's shape is opaque to LS): in that
+                // case leave null so resolve infers from the initializer's IR type
+                // (which sees the declare-type stubs).
+                const annotatedText = d.getTypeNode()?.getText();
+                const inferred = annotatedText ? null : _eraseGenerics(typeToString(declType));
+                const tsType = havocType
+                    ?? (annotatedText ? _eraseGenerics(annotatedText) : (inferred === "any" ? null : inferred));
                 result.push({
                     kind: "let",
                     name: d.getName(),
                     mutable: s.getDeclarationKind() === "let",
-                    tsType: havocType ?? _eraseGenerics(typeToString(declType)),
+                    tsType,
                     init,
                     line,
                 });
@@ -667,8 +1317,10 @@ function extractStmts(stmts) {
         }
         if (Node.isWhileStatement(s)) {
             const bodyNode = s.getStatement();
-            const bodyStmts = Node.isBlock(bodyNode) ? bodyNode.getStatements() : [];
-            const annots = collectAnnotations(s, bodyStmts);
+            // A braceless body (`while (c) stmt`) is a single statement, not a Block;
+            // wrap it so it isn't dropped (mirrors the for / for-of / if handlers).
+            const bodyStmts = Node.isBlock(bodyNode) ? bodyNode.getStatements() : [bodyNode];
+            const annots = collectLoopAnnotations(bodyStmts);
             result.push({
                 kind: "while",
                 cond: extractExpr(s.getExpression()),
@@ -719,7 +1371,7 @@ function extractStmts(stmts) {
             }
             const bodyNode = s.getStatement();
             const bodyStmts = Node.isBlock(bodyNode) ? bodyNode.getStatements() : [bodyNode];
-            const annots = collectAnnotations(s, bodyStmts);
+            const annots = collectLoopAnnotations(bodyStmts);
             result.push({
                 kind: "forof",
                 names,
@@ -731,6 +1383,83 @@ function extractStmts(stmts) {
             });
             continue;
         }
+        // C-style for(init; cond; update) — desugar to:
+        //   init;
+        //   while (cond) { body; update }
+        // The init's binding is forced mutable (update mutates it). The update is
+        // a bare Expression in ts-morph (not wrapped in an ExpressionStatement),
+        // so we route it through the same `desugarStmtExpr` helper that the
+        // ExpressionStatement branch above uses — `i++` etc. end up as RawAssign
+        // exactly as they would if written as their own statement.
+        if (Node.isForStatement(s)) {
+            const init = s.getInitializer();
+            const cond = s.getCondition();
+            const incrementor = s.getIncrementor();
+            const bodyNode = s.getStatement();
+            const bodyStmts = Node.isBlock(bodyNode) ? bodyNode.getStatements() : [bodyNode];
+            const annots = collectLoopAnnotations(bodyStmts);
+            if (!init || !Node.isVariableDeclarationList(init))
+                throw new Error(`for(...) at line ${line}: only variable-declaration init supported`);
+            // Hoist the counter declarations, renaming any that would collide once
+            // lifted out of the loop scope (see forCounterRename). The renames are
+            // then applied to the loop's own desugared pieces below.
+            const hoisted = [];
+            const renames = [];
+            for (const decl of init.getDeclarations()) {
+                const fresh = forCounterRename(decl, s);
+                const name = fresh ?? decl.getName();
+                if (fresh)
+                    renames.push([decl.getName(), fresh]);
+                const tsType = decl.getTypeNode()?.getText() ?? typeToString(decl.getType());
+                const initExpr = decl.getInitializer();
+                if (!initExpr)
+                    throw new Error(`for(...) at line ${line}: missing initializer for ${name}`);
+                hoisted.push({
+                    kind: "let", name, mutable: true, tsType,
+                    init: extractExpr(initExpr),
+                    line: decl.getStartLineNumber(),
+                });
+            }
+            let extractedBody = extractStmts(bodyStmts);
+            if (incrementor) {
+                const incLine = incrementor.getStartLineNumber();
+                const asStmt = desugarStmtExpr(incrementor, incLine);
+                if (!asStmt)
+                    throw new Error(`for(...) at line ${line}: incrementor must be an assignment, compound assignment, or ++/--`);
+                // The loop variable update runs at the bottom of every iteration. A
+                // `continue` in the body would skip it, so emit a copy of the update
+                // immediately before each same-scope `continue` (transform's
+                // eliminateTopLevelContinue then turns `if (X) { update; continue }`
+                // into `if (X) { update } else { rest }`). Nested `while`/`for-of`
+                // loops own their continue scope and are left untouched.
+                extractedBody = insertUpdateBeforeContinue(extractedBody, asStmt);
+                extractedBody.push(asStmt);
+            }
+            let condExpr = cond ? extractExpr(cond) : { kind: "bool", value: true };
+            let invariants = annots.filter(a => a.kind === "invariant").map(a => a.expr);
+            let decreases = annots.find(a => a.kind === "decreases")?.expr ?? null;
+            let doneWith = annots.find(a => a.kind === "done_with")?.expr ?? null;
+            for (const [from, to] of renames) {
+                for (let k = 0; k < hoisted.length; k++)
+                    hoisted[k] = renameRawStmt(hoisted[k], from, to);
+                condExpr = renameRawExpr(condExpr, from, to);
+                extractedBody = renameRawStmts(extractedBody, from, to);
+                invariants = invariants.map(inv => renameSpec(inv, from, to));
+                decreases = decreases ? renameSpec(decreases, from, to) : null;
+                doneWith = doneWith ? renameSpec(doneWith, from, to) : null;
+            }
+            result.push(...hoisted);
+            result.push({
+                kind: "while",
+                cond: condExpr,
+                invariants,
+                decreases,
+                doneWith,
+                body: extractedBody,
+                line,
+            });
+            continue;
+        }
         // for...in: for (const k in obj) → treat as forof with single key name
         if (Node.isForInStatement(s)) {
             const init = s.getInitializer();
@@ -740,7 +1469,7 @@ function extractStmts(stmts) {
             }
             const bodyNode = s.getStatement();
             const bodyStmts = Node.isBlock(bodyNode) ? bodyNode.getStatements() : [bodyNode];
-            const annots = collectAnnotations(s, bodyStmts);
+            const annots = collectLoopAnnotations(bodyStmts);
             result.push({
                 kind: "forof",
                 names: [name],
@@ -773,23 +1502,50 @@ function extractStmts(stmts) {
             const switchExpr = exprAst.kind === "field" ? exprAst.obj : exprAst;
             const cases = [];
             let defaultBody = [];
+            // Two JS-`switch` faithfulness concerns the Dafny `match` doesn't share:
+            //  (1) Fall-through: stacked `case A: case B: body` is several clauses
+            //      where the leading ones have no statements; those labels share the
+            //      next clause's body (we duplicate it per label).
+            //  (2) `break` is the switch exit, not a loop break. We extract the full
+            //      body (extractStmts flattens `{ }` blocks but keeps loop bodies
+            //      nested) and strip the *top-level* breaks — so a `break` written
+            //      inside a `{ }` case block is stripped, while a `break` inside a
+            //      nested loop stays put.
+            const stripExitBreaks = (b) => b.filter(st => st.kind !== "break");
+            let fallthrough = [];
             for (const clause of s.getClauses()) {
                 if (Node.isCaseClause(clause)) {
                     const label = clause.getExpression().getText().replace(/^["']|["']$/g, "");
-                    const bodyStmts = clause.getStatements().filter(st => !Node.isBreakStatement(st));
-                    cases.push({ label, body: extractStmts(bodyStmts) });
+                    if (clause.getStatements().length === 0) {
+                        fallthrough.push(label);
+                        continue;
+                    }
+                    const body = stripExitBreaks(extractStmts(clause.getStatements()));
+                    for (const l of fallthrough)
+                        cases.push({ label: l, body });
+                    cases.push({ label, body });
+                    fallthrough = [];
                 }
                 else {
-                    const bodyStmts = clause.getStatements().filter(st => !Node.isBreakStatement(st));
-                    defaultBody = extractStmts(bodyStmts);
+                    defaultBody = stripExitBreaks(extractStmts(clause.getStatements()));
+                    for (const l of fallthrough)
+                        cases.push({ label: l, body: defaultBody });
+                    fallthrough = [];
                 }
             }
+            for (const l of fallthrough)
+                cases.push({ label: l, body: [] });
             result.push({ kind: "switch", expr: switchExpr, discriminant, cases, defaultBody, line });
             continue;
         }
         if (Node.isReturnStatement(s)) {
             const expr = s.getExpression();
-            result.push({ kind: "return", value: expr ? extractExpr(expr) : { kind: "var", name: "()" }, line });
+            // Bare `return;` in a `T | undefined` function → emit `return None;`
+            // ("undefined" is mapped to None by dafny-emit). For void-returning
+            // functions this would emit the wrong shape, but lsc has no current
+            // examples of explicit bare return in void functions; revisit if one
+            // appears.
+            result.push({ kind: "return", value: expr ? extractExpr(expr) : { kind: "var", name: "undefined" }, line });
             continue;
         }
         if (Node.isBreakStatement(s)) {
@@ -802,41 +1558,22 @@ function extractStmts(stmts) {
         }
         if (Node.isExpressionStatement(s)) {
             const expr = s.getExpression();
-            // arr[i] = v → arr = arr.with(i, v)
-            if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === "=" && Node.isElementAccessExpression(expr.getLeft())) {
-                const left = expr.getLeft();
-                const obj = extractExpr(left.getExpression());
-                const idx = extractExpr(left.getArgumentExpression());
-                const val = extractExpr(expr.getRight());
-                const target = left.getExpression().getText();
-                const withCall = { kind: "call", fn: { kind: "field", obj, field: "with" }, args: [idx, val] };
-                result.push({ kind: "assign", target, value: withCall, line });
-                // x = e
-            }
-            else if (Node.isBinaryExpression(expr) && expr.getOperatorToken().getText() === "=") {
-                result.push({ kind: "assign", target: expr.getLeft().getText(), value: extractExpr(expr.getRight()), line });
-                // x += e, x -= e, etc.
-            }
-            else if (Node.isBinaryExpression(expr) && COMPOUND_OPS[expr.getOperatorToken().getText()]) {
-                const op = COMPOUND_OPS[expr.getOperatorToken().getText()];
+            // //@ havoc before `x = e` — discard the RHS, assign a nondeterministic
+            // value of x's type. Only applies to plain `=` with an identifier LHS;
+            // compound assigns, `arr[i] = v`, and `x++` fall through to desugaring.
+            const havocMatch = s.getLeadingCommentRanges()
+                .map(r => r.getText().trim().match(/^\/\/@ havoc(?:\s*:\s*(.+))?$/))
+                .find(m => m !== null);
+            if (havocMatch && Node.isBinaryExpression(expr)
+                && expr.getOperatorToken().getText() === "="
+                && Node.isIdentifier(expr.getLeft())) {
                 const target = expr.getLeft().getText();
-                result.push({ kind: "assign", target, value: { kind: "binop", op, left: { kind: "var", name: target }, right: extractExpr(expr.getRight()) }, line });
-                // i++, i--
-            }
-            else if (Node.isPostfixUnaryExpression(expr)) {
-                const target = expr.getOperand().getText();
-                const op = expr.getOperatorToken() === SyntaxKind.PlusPlusToken ? "+" : "-";
-                result.push({ kind: "assign", target, value: { kind: "binop", op, left: { kind: "var", name: target }, right: { kind: "num", value: 1 } }, line });
-                // ++i, --i
-            }
-            else if (Node.isPrefixUnaryExpression(expr) && (expr.getOperatorToken() === SyntaxKind.PlusPlusToken || expr.getOperatorToken() === SyntaxKind.MinusMinusToken)) {
-                const target = expr.getOperand().getText();
-                const op = expr.getOperatorToken() === SyntaxKind.PlusPlusToken ? "+" : "-";
-                result.push({ kind: "assign", target, value: { kind: "binop", op, left: { kind: "var", name: target }, right: { kind: "num", value: 1 } }, line });
-            }
-            else {
-                result.push({ kind: "expr", expr: extractExpr(expr), line });
+                const tsType = havocMatch[1]?.trim() ?? _eraseGenerics(typeToString(expr.getLeft().getType()));
+                result.push({ kind: "assign", target, value: { kind: "havoc", tsType }, line });
+                continue;
             }
+            const asAssign = desugarStmtExpr(expr, line);
+            result.push(asAssign ?? { kind: "expr", expr: extractExpr(expr), line });
             continue;
         }
         if (Node.isThrowStatement(s)) {
@@ -864,12 +1601,17 @@ function extractStmts(stmts) {
                 result.push({ kind: "assert", expr: content.slice(7).trim(), line });
                 continue;
             }
+            // assume expr — trusted form of assert; emitted as `assume P;` in Dafny.
+            if (content.startsWith("assume ")) {
+                result.push({ kind: "assert", expr: content.slice(7).trim(), line, assumed: true });
+                continue;
+            }
             if (!content.startsWith("ghost "))
                 continue;
             const ghostBody = content.slice(6).trim();
-            const letMatch = ghostBody.match(/^let\s+(\w+)(?:\s*:\s*(\w+))?\s*=\s*(.+)$/);
+            const letMatch = ghostBody.match(/^let\s+(\w+)(?:\s*:\s*([^=]+?))?\s*=\s*(.+)$/);
             if (letMatch) {
-                result.push({ kind: "ghostLet", name: letMatch[1], tsType: letMatch[2] ?? null, init: letMatch[3].trim(), line });
+                result.push({ kind: "ghostLet", name: letMatch[1], tsType: letMatch[2]?.trim() ?? null, init: letMatch[3].trim(), line });
                 continue;
             }
             const assignMatch = ghostBody.match(/^(\w+)\s*=\s*(.+)$/);
@@ -882,9 +1624,20 @@ function extractStmts(stmts) {
 }
 // ── Function extraction ──────────────────────────────────────
 function extractFunction(fn, parentAnnotations) {
+    const prevInFn = _inFunctionExtraction;
+    _inFunctionExtraction = true;
+    try {
+        return extractFunctionInner(fn, parentAnnotations);
+    }
+    finally {
+        _inFunctionExtraction = prevInFn;
+    }
+}
+function extractFunctionInner(fn, parentAnnotations) {
     // Generic bounds erasure: <T extends Base> → substitute T with Base everywhere
     // Unbounded type params are preserved as Dafny type parameters
     _typeParamMap = new Map();
+    _reservedForCounterNames = new Set();
     const unboundedTypeParams = [];
     for (const tp of fn.getTypeParameters?.() ?? []) {
         const constraint = tp.getConstraint();
@@ -900,12 +1653,11 @@ function extractFunction(fn, parentAnnotations) {
     if (body && !Node.isBlock(body)) {
         const expr = extractExpr(body);
         extractedBody = [{ kind: "return", value: expr, line: body.getStartLineNumber() }];
-        annots = parentAnnotations ?? collectAnnotations(fn);
+        annots = parentAnnotations ?? collectFunctionAnnotations(fn);
     }
     else if (body && Node.isBlock(body)) {
-        const bodyStmts = body.getStatements();
-        extractedBody = extractStmts(bodyStmts);
-        annots = collectAnnotations(fn, bodyStmts);
+        extractedBody = extractStmts(body.getStatements());
+        annots = collectFunctionAnnotations(fn);
     }
     else {
         throw new Error(`${fn.getName?.() ?? "arrow"}: function has no body`);
@@ -932,14 +1684,29 @@ function extractFunction(fn, parentAnnotations) {
                     return { name, tsType: propType ? typeToString(propType) : "unknown" };
                 });
             }
-            let tsType = _eraseGenerics(p.getTypeNode()?.getText() ?? "unknown");
-            // Optional parameters (foo?: T) need | undefined in the type string
+            // Syntactic union nodes go through _tsTypeFromUnionNode so synth fires
+            // and aliases are preserved. Non-union nodes use the syntactic text;
+            // when no annotation is present, fall back to the computed type
+            // (e.g., `eof = false` infers `boolean` from the default value).
+            const tn = p.getTypeNode();
+            let tsType;
+            if (tn && Node.isUnionTypeNode(tn)) {
+                tsType = _eraseGenerics(_tsTypeFromUnionNode(tn));
+            }
+            else if (tn) {
+                tsType = _eraseGenerics(tn.getText());
+            }
+            else {
+                tsType = _eraseGenerics(typeToString(p.getType()));
+            }
             if (p.hasQuestionToken())
                 tsType = `${tsType} | undefined`;
             return [{ name: p.getName(), tsType }];
         }),
         returnType: (() => {
             const node = fn.getReturnTypeNode();
+            if (node && Node.isUnionTypeNode(node))
+                return _eraseGenerics(_tsTypeFromUnionNode(node));
             if (node)
                 return _eraseGenerics(node.getText());
             const inferred = fn.getReturnType();
@@ -959,41 +1726,65 @@ function extractFunction(fn, parentAnnotations) {
 // ── Module extraction ────────────────────────────────────────
 export function extractModule(sourceFile) {
     const typeDecls = [];
-    // Parse //@ declare-type directives from file comments
+    // Cross-file calls are auto-externed: ts-morph resolves the call's symbol;
+    // if it's defined in a different source file we treat the symbol as opaque
+    // and emit a body-less `function {:axiom}` in Dafny. Populated by
+    // `extractExpr` during call extraction (only symbols *actually used* end up
+    // here), deduped by qualified name.
+    _externs.clear();
+    // Share the module's ts-morph Project with parseTsType (scratch source file
+    // for type-string parsing). Done before declare-type parsing so any
+    // parseTsType call downstream uses the same Project.
+    initTypeParser(sourceFile.getProject());
+    // Activate the synthesized-array-union accumulator. typeToString registers
+    // a discriminated-union TypeDeclInfo for any `T[] | U` shape it encounters,
+    // pushing into `typeDecls` so resolve sees the synth as a regular user type.
+    // Set before declare-type parsing so declare-type field types can also synth.
+    _synthArrayUnions = typeDecls;
+    // `//@ declare-type Name { f1: T1, ... }` — record form.
+    // `//@ declare-type Name = TsType`         — alias form (e.g. `Ruleset = Rule[]`).
+    function parseDeclareType(body) {
+        const recordMatch = body.match(/^(\w+)\s*\{(.+)\}$/);
+        if (recordMatch) {
+            const name = recordMatch[1];
+            const fields = recordMatch[2].split(",").map(f => f.trim()).filter(Boolean).map(f => {
+                const [fname, ftype] = f.split(":").map(s => s.trim());
+                const synth = _synthFromTsTypeString(ftype);
+                return { name: fname, tsType: synth ?? ftype };
+            });
+            typeDecls.push({ name, kind: "record", fields });
+            return;
+        }
+        const aliasMatch = body.match(/^(\w+)\s*=\s*(.+)$/);
+        if (aliasMatch) {
+            const rhs = aliasMatch[2].trim();
+            // A string-literal union (`= "a" | "b" | …`) becomes an enum datatype —
+            // the same shape a real string-union alias resolves to. Dafny has no
+            // string-literal type, so a plain alias (`type X = "a" | "b"`) would be
+            // invalid. Other RHS forms (`Rule[]`, `number`, `A | B`) fall through.
+            const parts = rhs.split("|").map(s => s.trim());
+            const lits = parts.map(p => p.match(/^["'](.+)["']$/));
+            if (parts.length >= 2 && lits.every(m => m !== null)) {
+                typeDecls.push({ name: aliasMatch[1], kind: "string-union", values: lits.map(m => m[1]) });
+            }
+            else {
+                typeDecls.push({ name: aliasMatch[1], kind: "alias", aliasOf: rhs });
+            }
+        }
+    }
     for (const range of sourceFile.getLeadingCommentRanges()) {
         const text = range.getText().trim();
-        if (!text.startsWith("//@ declare-type "))
-            continue;
-        const body = text.slice("//@ declare-type ".length);
-        const match = body.match(/^(\w+)\s*\{(.+)\}$/);
-        if (!match)
-            continue;
-        const name = match[1];
-        const fieldsStr = match[2];
-        const fields = fieldsStr.split(",").map(f => f.trim()).filter(Boolean).map(f => {
-            const [fname, ftype] = f.split(":").map(s => s.trim());
-            return { name: fname, tsType: ftype };
-        });
-        typeDecls.push({ name, kind: "record", fields });
+        if (text.startsWith("//@ declare-type "))
+            parseDeclareType(text.slice("//@ declare-type ".length));
     }
-    // Also scan statement-level comments for declare-type
     for (const stmt of sourceFile.getStatements()) {
         for (const range of stmt.getLeadingCommentRanges()) {
             const text = range.getText().trim();
-            if (!text.startsWith("//@ declare-type "))
-                continue;
-            const body = text.slice("//@ declare-type ".length);
-            const match = body.match(/^(\w+)\s*\{(.+)\}$/);
-            if (!match)
-                continue;
-            const name = match[1];
-            const fields = match[2].split(",").map(f => f.trim()).filter(Boolean).map(f => {
-                const [fname, ftype] = f.split(":").map(s => s.trim());
-                return { name: fname, tsType: ftype };
-            });
-            typeDecls.push({ name, kind: "record", fields });
+            if (text.startsWith("//@ declare-type "))
+                parseDeclareType(text.slice("//@ declare-type ".length));
         }
     }
+    _currentSourceFile = sourceFile;
     // Pre-scan for collapsed single-variant unions so typeToString can recover alias names.
     // TypeScript collapses `type X = | { kind: 'A'; ... }` to a plain object type, losing
     // the alias. We record a fingerprint (sorted property names) → alias name mapping.
@@ -1040,11 +1831,17 @@ export function extractModule(sourceFile) {
                     // Skip huge string constants — they crash the verifier and have no verification value
                     const initType = decl.getType();
                     const isHugeString = (initType.isString() || initType.isStringLiteral()) && init.getText().length > 200;
-                    if (init && !isHugeString && !Node.isArrowFunction(init)) {
+                    // Skip anonymous-object consts (e.g., `const Util = { dotMatch(s, p) { ... } }`).
+                    // ts-morph names these `__type` / `__object`; Dafny has no model for
+                    // object-namespace-with-methods. The methods themselves should be
+                    // extracted via the function path if marked `//@ verify`.
+                    const declTsType = typeToString(decl.getType());
+                    const isAnonObject = declTsType.startsWith("__");
+                    if (init && !isHugeString && !isAnonObject && !Node.isArrowFunction(init)) {
                         try {
                             constants.push({
                                 name: decl.getName(),
-                                tsType: typeToString(decl.getType()),
+                                tsType: declTsType,
                                 value: extractExpr(init),
                             });
                         }
@@ -1072,6 +1869,42 @@ export function extractModule(sourceFile) {
             }
         }
     }
+    // `//@ extern` on a same-file declaration: register the function as an
+    // opaque axiom (signature + any //@ requires/ensures), skip its body. Use
+    // when the function is outside LS's verification model — e.g., wraps a
+    // regex — but its callers should still be verifiable against an
+    // uninterpreted predicate. Parallel to auto-extern for cross-file calls,
+    // and emitted the same way (`function {:axiom} foo(...)` in Dafny).
+    function hasExtern(f) {
+        if (f.node.getFullText().includes('//@ extern'))
+            return true;
+        if (f.parentStmt) {
+            for (const r of f.parentStmt.getLeadingCommentRanges()) {
+                if (r.getText().includes('//@ extern'))
+                    return true;
+            }
+        }
+        return false;
+    }
+    for (const f of allFns) {
+        if (!hasExtern(f))
+            continue;
+        if (_externs.has(f.name))
+            continue;
+        const sig = f.node.getType().getCallSignatures()[0];
+        if (!sig)
+            continue;
+        const typeParams = sig.getTypeParameters().map(tp => tp.getText());
+        const params = sig.getParameters().map(p => ({
+            name: p.getName(),
+            tsType: p.getTypeAtLocation(f.node).getText(),
+        }));
+        const returnType = sig.getReturnType().getText();
+        const annots = collectFunctionAnnotations(f.node);
+        const requires = annots.filter(a => a.kind === "requires").map(a => a.expr);
+        const ensures = annots.filter(a => a.kind === "ensures").map(a => a.expr);
+        _externs.set(f.name, { qualified: f.name, flat: f.name, typeParams, params, returnType, requires, ensures });
+    }
     // If any function has //@ verify, only extract those (brownfield mode).
     // For expression-body arrows, //@ verify may be on the parent variable statement.
     function hasVerify(f) {
@@ -1086,7 +1919,8 @@ export function extractModule(sourceFile) {
         return false;
     }
     const hasVerifyDirective = sourceFile.getFullText().includes('//@ verify');
-    const fnsToExtract = hasVerifyDirective ? allFns.filter(hasVerify) : allFns;
+    const nonExternFns = allFns.filter(f => !hasExtern(f));
+    const fnsToExtract = hasVerifyDirective ? nonExternFns.filter(hasVerify) : nonExternFns;
     const functions = fnsToExtract.map(f => {
         // For expression-body arrows, annotations come from the parent variable statement
         const parentAnnots = f.parentStmt ? parseAnnotations(f.parentStmt) : undefined;
@@ -1094,61 +1928,97 @@ export function extractModule(sourceFile) {
         raw.name = f.name; // use the const name, not "<anonymous>"
         return raw;
     });
-    // Resolve imported type names referenced in function signatures and type fields
+    // Resolve type references in function signatures via ts-morph's type
+    // checker — walk the TypeNode tree, resolve each TypeReferenceNode to its
+    // declaration through symbol resolution, recurse. This is the principled
+    // replacement for an earlier regex-based walker that extracted identifier
+    // names from tsType strings and searched the whole project by name — that
+    // approach had ambiguous resolution (name collisions in generated files
+    // could shadow what the user actually imported).
     const knownTypeNames = new Set(typeDecls.map(d => d.name));
-    const primitives = new Set(["number", "string", "boolean", "void", "unknown", "undefined"]);
-    const builtinTypes = new Set(["Map", "Set", "Array", "Record", "Promise", "Date", "RegExp", "Error"]);
-    function resolveTypeName(name) {
-        if (knownTypeNames.has(name) || primitives.has(name) || builtinTypes.has(name))
+    function resolveTypeNodeRefs(tn) {
+        if (!tn)
             return;
-        for (const sf2 of sourceFile.getProject().getSourceFiles()) {
-            for (const stmt of sf2.getStatements()) {
-                if (Node.isTypeAliasDeclaration(stmt) && stmt.getName() === name) {
-                    const extra = [];
-                    const info = extractTypeDecl(stmt, extra);
-                    typeDecls.push(...extra);
-                    if (info) {
-                        typeDecls.push(info);
-                        knownTypeNames.add(name);
+        if (Node.isTypeReference(tn)) {
+            const sym = tn.getTypeName().getSymbol();
+            if (sym) {
+                for (const d of sym.getDeclarations()) {
+                    // Skip ambient/built-in declarations: `.d.ts` files (lib.dom.d.ts,
+                    // node_modules typings) describe runtime/host types, not user code
+                    // — backends map these directly (`Map<K,V>` → `map<K,V>`) without
+                    // needing the interface dump.
+                    if (d.getSourceFile().getFilePath().endsWith(".d.ts"))
+                        continue;
+                    let added = null;
+                    if (Node.isTypeAliasDeclaration(d) && !knownTypeNames.has(d.getName())) {
+                        const extra = [];
+                        added = extractTypeDecl(d, extra);
+                        typeDecls.push(...extra);
+                        if (added) {
+                            typeDecls.push(added);
+                            knownTypeNames.add(d.getName());
+                        }
                     }
-                }
-                if (Node.isInterfaceDeclaration(stmt) && stmt.getName() === name && !knownTypeNames.has(name)) {
-                    const extra = [];
-                    const info = extractInterface(stmt, extra);
-                    typeDecls.push(...extra);
-                    if (info) {
-                        typeDecls.push(info);
-                        knownTypeNames.add(name);
+                    else if (Node.isInterfaceDeclaration(d) && !knownTypeNames.has(d.getName())) {
+                        const extra = [];
+                        added = extractInterface(d, extra);
+                        typeDecls.push(...extra);
+                        if (added) {
+                            typeDecls.push(added);
+                            knownTypeNames.add(d.getName());
+                        }
+                    }
+                    // Recurse into the newly-added declaration's TypeNodes — preferring
+                    // the actual AST over re-parsing tsType strings.
+                    if (added) {
+                        if (Node.isTypeAliasDeclaration(d))
+                            resolveTypeNodeRefs(d.getTypeNode());
+                        else if (Node.isInterfaceDeclaration(d)) {
+                            for (const m of d.getProperties())
+                                resolveTypeNodeRefs(m.getTypeNode());
+                        }
                     }
                 }
             }
-            if (knownTypeNames.has(name))
-                break;
+            for (const a of tn.getTypeArguments())
+                resolveTypeNodeRefs(a);
+            return;
         }
-        // Recursively resolve types referenced by the newly added type's fields
-        const decl = typeDecls.find(d => d.name === name);
-        if (decl?.fields) {
-            for (const f of decl.fields) {
-                for (const m of f.tsType.matchAll(/\b([A-Z]\w*)\b/g))
-                    resolveTypeName(m[1]);
-            }
+        if (Node.isUnionTypeNode(tn) || Node.isIntersectionTypeNode(tn)) {
+            for (const arm of tn.getTypeNodes())
+                resolveTypeNodeRefs(arm);
+            return;
         }
-        if (decl?.variants) {
-            for (const v of decl.variants) {
-                for (const f of v.fields) {
-                    for (const m of f.tsType.matchAll(/\b([A-Z]\w*)\b/g))
-                        resolveTypeName(m[1]);
-                }
-            }
+        if (Node.isArrayTypeNode(tn)) {
+            resolveTypeNodeRefs(tn.getElementTypeNode());
+            return;
         }
-    }
-    for (const fn of functions) {
-        const refs = [fn.returnType, ...fn.params.map(p => p.tsType)];
-        for (const ref of refs) {
-            for (const m of ref.matchAll(/\b([A-Z]\w*)\b/g))
-                resolveTypeName(m[1]);
+        if (Node.isTupleTypeNode(tn)) {
+            for (const el of tn.getElements())
+                resolveTypeNodeRefs(el);
+            return;
+        }
+        if (Node.isParenthesizedTypeNode(tn)) {
+            resolveTypeNodeRefs(tn.getTypeNode());
+            return;
+        }
+        if (Node.isFunctionTypeNode(tn)) {
+            for (const p of tn.getParameters())
+                resolveTypeNodeRefs(p.getTypeNode());
+            resolveTypeNodeRefs(tn.getReturnTypeNode());
+            return;
+        }
+        if (Node.isTypeLiteral(tn)) {
+            for (const m of tn.getProperties())
+                resolveTypeNodeRefs(m.getTypeNode());
+            return;
         }
     }
+    for (const f of fnsToExtract) {
+        for (const p of f.node.getParameters())
+            resolveTypeNodeRefs(p.getTypeNode());
+        resolveTypeNodeRefs(f.node.getReturnTypeNode());
+    }
     // Resolve union param types: A | B → intersection of fields
     const typeDeclMap = new Map(typeDecls.map(d => [d.name, d]));
     for (const fn of functions) {
@@ -1188,7 +2058,8 @@ export function extractModule(sourceFile) {
         function collectNames(stmts) {
             for (const s of stmts) {
                 if (s.kind === "let") {
-                    referencedNames.add(s.tsType);
+                    if (s.tsType)
+                        referencedNames.add(s.tsType);
                     collectNamesExpr(s.init);
                 }
                 if (s.kind === "assign") {
@@ -1297,6 +2168,12 @@ export function extractModule(sourceFile) {
         const alias = t.getAliasSymbol();
         if (alias) {
             const aliasName = alias.getName();
+            // A //@ declare-type already defines the verification surface for this
+            // alias. Don't walk the imported structure — its union members would
+            // leak unrelated variant datatypes (and the types those reference, which
+            // we don't model) into the output. See examples/declareTypeShadow.ts.
+            if (declaredNames.has(aliasName))
+                return;
             if (!knownTypes.has(aliasName) && !builtins.has(aliasName) && !aliasName.startsWith("__")) {
                 const decls = alias.getDeclarations();
                 if (decls.length > 0 && Node.isTypeAliasDeclaration(decls[0])) {
@@ -1343,9 +2220,19 @@ export function extractModule(sourceFile) {
             }
         }
     }
-    for (const f of fnsToExtract) {
-        for (const p of f.node.getParameters())
+    for (let i = 0; i < fnsToExtract.length; i++) {
+        const f = fnsToExtract[i];
+        const fn = functions[i];
+        // Skip params whose TS type was overridden by `//@ type <param> <Override>`
+        // — the verification works against the override, so cross-file resolving
+        // the original type pulls in unused datatypes (often with unsupported
+        // shapes the override exists precisely to avoid).
+        const overriddenNames = new Set(fn.typeAnnotations.map(a => a.name));
+        for (const p of f.node.getParameters()) {
+            if (overriddenNames.has(p.getName()))
+                continue;
             resolveType(p.getType(), p);
+        }
     }
     // Resolve anonymous object return types into synthetic named types
     for (let i = 0; i < fnsToExtract.length; i++) {
@@ -1355,9 +2242,15 @@ export function extractModule(sourceFile) {
         // Prefer alias symbol (named type aliases) over underlying object symbol (__type)
         const aliasSym = retType.getAliasSymbol();
         if (aliasSym && !aliasSym.getName().startsWith("__")) {
-            // Named type alias — resolve it instead of generating a synthetic name
-            resolveType(retType, f.node);
             const aliasName = aliasSym.getName();
+            // If the alias name is already locally declared (e.g. via `//@ declare-type
+            // Ruleset = Rule[]`), don't unwrap further — the declared shape is the
+            // verification surface, and walking the original cross-file alias pulls
+            // unused datatypes (often with unsupported shapes) into the gen.
+            if (!knownTypes.has(aliasName)) {
+                // Named type alias — resolve it instead of generating a synthetic name
+                resolveType(retType, f.node);
+            }
             if (knownTypes.has(aliasName)) {
                 // Preserve type arguments: Result<Model, Err> not just Result
                 const typeArgs = retType.getAliasTypeArguments();
@@ -1367,27 +2260,58 @@ export function extractModule(sourceFile) {
             }
             continue;
         }
+        // Inline-anon return type — bare `{...}` (no union wrapping).
+        //
+        // ts-morph's `fn.getReturnType()` returns the COMPUTED type, which strips
+        // `| null` in non-strict mode (and sometimes `| undefined`). The source
+        // annotation, however, encodes the user's actual intent. Check the
+        // already-extracted `fn.returnType` string for nullish suffixes to detect
+        // the wrap-in-Optional case.
+        let innerType = null;
+        let wrapOptional = false;
+        const sourceReturnText = fn.returnType ?? "";
+        const sourceHadNullish = / \| (null|undefined)$/.test(sourceReturnText)
+            || sourceReturnText.includes(" | null ") || sourceReturnText.includes(" | undefined ")
+            || sourceReturnText.includes(" | null|") || sourceReturnText.includes(" | undefined|");
         const sym = retType.getSymbol();
         if (sym?.getName() === "__type" && retType.isObject() && !retType.isArray()) {
+            innerType = retType;
+            if (sourceHadNullish)
+                wrapOptional = true;
+        }
+        else if (retType.isUnion()) {
+            const arms = retType.getUnionTypes();
+            const nullish = arms.filter(t => t.isNull() || t.isUndefined());
+            const others = arms.filter(t => !t.isNull() && !t.isUndefined());
+            if (nullish.length >= 1 && others.length === 1) {
+                const onlyOther = others[0];
+                const otherSym = onlyOther.getSymbol();
+                if (otherSym?.getName() === "__type" && onlyOther.isObject() && !onlyOther.isArray()) {
+                    innerType = onlyOther;
+                    wrapOptional = true;
+                }
+            }
+        }
+        if (innerType) {
             // Try typeToString first — it resolves collapsed single-variant unions
-            const resolved = typeToString(retType);
+            const resolved = typeToString(innerType);
             if (resolved !== "__type" && !resolved.includes("__type") && knownTypes.has(resolved)) {
-                fn.returnType = resolved;
+                fn.returnType = wrapOptional ? `${resolved} | undefined` : resolved;
                 continue;
             }
             const synName = fn.name.charAt(0).toUpperCase() + fn.name.slice(1) + "Result";
             if (!knownTypes.has(synName)) {
                 const extra = [];
-                const info = extractRecord(synName, retType, f.node, undefined, extra);
+                const info = extractRecord(synName, innerType, f.node, undefined, extra);
                 if (info) {
                     typeDecls.push(...extra);
                     typeDecls.push(info);
                     knownTypes.add(synName);
                 }
             }
-            fn.returnType = synName;
+            fn.returnType = wrapOptional ? `${synName} | undefined` : synName;
             // Also resolve imported types referenced in the return type's fields
-            for (const prop of retType.getProperties()) {
+            for (const prop of innerType.getProperties()) {
                 resolveType(prop.getTypeAtLocation(f.node), f.node);
             }
         }
@@ -1409,9 +2333,13 @@ export function extractModule(sourceFile) {
         }
         classes.push({ name: cls.getName() ?? "Anonymous", fields, methods });
     }
+    // Clear the synth-union accumulator so typeToString reverts to plain
+    // union stringification outside of an extractModule call.
+    _synthArrayUnions = null;
     return {
         file: sourceFile.getFilePath(),
         typeDecls,
+        externs: Array.from(_externs.values()),
         constants,
         functions,
         classes,