numbl 0.1.6 → 0.2.0

package/dist-lib/numbl-core/jit/jitLower.d.ts

@@ -0,0 +1,122 @@
+/**
+ * AST -> JIT IR lowering with type propagation. Orchestrator that owns
+ * the shared context types (LowerCtx, SliceAlias), the public result
+ * types (GeneratedFn, LoweringResult), and the `lowerFunction` entry
+ * point. Actual statement and expression lowering lives in
+ * jitLowerStmt.ts and jitLowerExpr.ts; type-level helpers are in
+ * jitLowerTypes.ts.
+ *
+ * Returns null if any unsupported construct is encountered, causing the
+ * entire function to fall back to interpretation.
+ */
+import type { FunctionDef } from "../interpreter/types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { JitType, JitExpr, JitStmt } from "./jitTypes.js";
+import { type TypeEnv } from "./jitLowerTypes.js";
+/**
+ * Lowered IR for a user function reached during a top-level lowering.
+ *
+ * JS-JIT caches the callee as generated JS source in `generatedFns` and
+ * is done. C-JIT needs to re-analyze the callee's IR (for recursive
+ * feasibility + emitting a static C function per callee), so we also
+ * cache the raw IR here. One entry per unique `jitName`; matches the
+ * JS-JIT specialization key.
+ */
+export interface GeneratedFn {
+    fn: FunctionDef;
+    argTypes: JitType[];
+    outputNames: string[];
+    outputTypes: JitType[];
+    body: JitStmt[];
+    localVars: Set<string>;
+    nargout: number;
+}
+export interface LoweringResult {
+    body: JitStmt[];
+    outputNames: string[];
+    localVars: Set<string>;
+    hasTensorOps: boolean;
+    /** Generated JS code for called user functions: jitName → code */
+    generatedFns: Map<string, string>;
+    /** Lowered IR for called user functions: jitName → IR + metadata.
+     *  Populated alongside `generatedFns` by `lowerUserFuncCall`; the
+     *  C-JIT uses it for recursive feasibility and per-callee C emission. */
+    generatedIRBodies: Map<string, GeneratedFn>;
+    /** Type of the first output variable after lowering */
+    outputType: JitType | null;
+    /** Types of all output variables in outputNames order. Mirrors the
+     *  shape of JS-JIT's `return [out0, out1, ...]`. */
+    outputTypes: JitType[];
+    /** Final typed environment after lowering the body. The hybrid
+     *  loop-extraction pass uses this to look up live-in/live-out var
+     *  types without re-running type inference. */
+    endEnv: TypeEnv;
+}
+/**
+ * A "slice alias" records that a MATLAB local was bound to a colon-slice of
+ * a real tensor (e.g. `pt = pts(:, i)`). Rather than materializing the slice
+ * as a RuntimeTensor per iteration, we remember the base tensor and a
+ * per-dim "template" of indices — scalar expressions captured at bind time
+ * for the non-colon dims, and `"colon"` placeholders for the colon dims.
+ * Subsequent reads like `pt(k)` substitute `k` into the colon positions and
+ * emit a direct scalar read on the base tensor, which compiles cleanly
+ * through the existing hoisted `idx{1,2,3}r_h` fast path.
+ */
+export interface SliceAlias {
+    baseName: string;
+    baseType: JitType;
+    /**
+     * One entry per index of the original bind expression, in source order.
+     * A `"colon"` slot expects to be filled by the read-site's colon indices.
+     * An `"expr"` slot carries a JitExpr that will be substituted as-is.
+     */
+    template: ({
+        kind: "colon";
+    } | {
+        kind: "expr";
+        expr: JitExpr;
+    })[];
+    /** Sizes of the slice's colon dimensions, in source order. */
+    sliceShape: number[];
+    /** Indices into `template` where colon slots live, in source order. */
+    colonPositions: number[];
+}
+export interface LowerCtx {
+    env: TypeEnv;
+    localVars: Set<string>;
+    params: Set<string>;
+    /** First bail reason encountered during lowering; lets callers surface
+     *  a hint for why JS-JIT declined a function (purely diagnostic, only
+     *  consulted by the `NUMBL_LOG_CJIT_MISSES` tally). Writes should use
+     *  `setBailReason()` which is idempotent — only the first reason sticks. */
+    bailReason?: string;
+    bailLine?: number;
+    /** Type of the deepest expr whose lowering was attempted — used as a
+     *  last-resort bail reason hint when no more specific reason was set. */
+    lastExprType?: string;
+    lastExprLine?: number;
+    /** Variables that are actually assigned in the function body. */
+    assignedVars: Set<string>;
+    /**
+     * Map from a MATLAB local name to its slice alias, if any. A name is
+     * present here iff the most recent assignment to it was a whole-tensor
+     * colon slice. Reads of the name as a plain Ident bail; reads of
+     * `name(...)` substitute through the template and emit a direct scalar
+     * read of the base tensor. See `tryLowerAsSliceBind`.
+     */
+    sliceAliases: Map<string, SliceAlias>;
+    _hasTensorOps?: boolean;
+    interp?: Interpreter;
+    /** The nargout this specialization was requested with — inlined wherever
+     *  the body reads the `nargout` identifier, since the JIT specializes per
+     *  nargout already. */
+    nargout?: number;
+    generatedFns: Map<string, string>;
+    generatedIRBodies: Map<string, GeneratedFn>;
+    loweringInProgress: Set<string>;
+    /** Pre-built line break table for offset→line lookup. */
+    lineTable?: number[];
+}
+/** Idempotent bail-reason setter. Only the first reason per function sticks. */
+export declare function setBailReason(ctx: LowerCtx, reason: string, line?: number): void;
+export declare function lowerFunction(fn: FunctionDef, argTypes: JitType[], nargout: number, interp?: Interpreter, generatedFns?: Map<string, string>, loweringInProgress?: Set<string>, generatedIRBodies?: Map<string, GeneratedFn>): LoweringResult | null;

package/dist-lib/numbl-core/jit/jitLowerExpr.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Expression lowering for the JIT. Paired with jitLowerStmt.ts; the two
+ * sides are mutually recursive (stmt bodies contain exprs; function-call
+ * exprs may trigger nested lowering of a callee's body). jitLower.ts is
+ * the orchestrator that ties them together via LowerCtx + lowerFunction.
+ */
+import type { Expr } from "../parser/types.js";
+import { type JitExpr } from "./jitTypes.js";
+import type { LowerCtx } from "./jitLower.js";
+export declare function lowerExpr(ctx: LowerCtx, expr: Expr): JitExpr | null;
+/**
+ * Stage 21: lower `src(a:b)` on a real-tensor base into a
+ * `RangeSliceRead` IR node producing a fresh column-vector tensor.
+ *
+ * Accepts `Range` with no step (default step 1). `start` and `end`
+ * must lower to numeric/boolean scalar exprs. The result is a real
+ * tensor with shape `[?, 1]` — the exact length is runtime-dependent.
+ *
+ * Caller responsibility: match the parent expression shape
+ * `Index(Ident(src), [Range])` or `FuncCall(src, [Range])` before
+ * calling. Returns null if the source isn't a real tensor or the
+ * range isn't the expected shape.
+ */
+export declare function tryLowerRangeSliceRead(ctx: LowerCtx, baseName: string, rangeExpr: Expr): JitExpr | null;
+export declare function lowerIBuiltinCall(ctx: LowerCtx, expr: Expr & {
+    type: "FuncCall";
+}): JitExpr | null;

package/dist-lib/numbl-core/jit/jitLowerStmt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Statement lowering for the JIT. Paired with jitLowerExpr.ts; the two
+ * sides are mutually recursive. jitLower.ts is the orchestrator that ties
+ * them together via LowerCtx + lowerFunction.
+ */
+import type { Stmt } from "../parser/types.js";
+import { type JitStmt } from "./jitTypes.js";
+import type { LowerCtx } from "./jitLower.js";
+export declare function lowerStmts(ctx: LowerCtx, stmts: Stmt[]): JitStmt[] | null;

package/dist-lib/numbl-core/jit/jitLowerTypes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Type-level helpers for the JIT lowering pass.
+ *
+ * Pure functions for:
+ * - Sign algebra (how signs combine through arithmetic)
+ * - Binary/unary operation result type inference
+ * - Type environment management (clone, merge, equality)
+ * - Known MATLAB constants
+ *
+ * These have no dependency on LowerCtx or the lowering state.
+ */
+import { BinaryOperation, UnaryOperation } from "../parser/types.js";
+import { type JitExpr, type JitType, type SignCategory } from "./jitTypes.js";
+export declare const KNOWN_CONSTANTS: Record<string, number>;
+export type TypeEnv = Map<string, JitType>;
+export declare function cloneEnv(env: TypeEnv): TypeEnv;
+/** Merge two type environments at a join point. Returns null if any type becomes unknown. */
+export declare function mergeEnvs(a: TypeEnv, b: TypeEnv): TypeEnv | null;
+/** Check if two type environments are identical (by JSON comparison). */
+export declare function envsEqual(a: TypeEnv, b: TypeEnv): boolean;
+export declare function addSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
+export declare function mulSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
+export declare function combineSigns(a: SignCategory | undefined, b: SignCategory | undefined, op: BinaryOperation): SignCategory | undefined;
+export declare function binaryResultType(op: BinaryOperation, left: JitType, right: JitType, 
+/** Lowered operand exprs. Optional because tests / older callers pass
+ *  only types. When provided, enables structural nonneg detection for
+ *  patterns like `x .* x` that the type-only path can't see. */
+leftExpr?: JitExpr, rightExpr?: JitExpr): JitType | null;
+export declare function unaryResultType(op: UnaryOperation, operand: JitType): JitType | null;

package/dist-lib/numbl-core/jit/jitTopLevel.d.ts

@@ -0,0 +1,22 @@
+/**
+ * JIT compilation for the top-level script body (the main workspace).
+ *
+ * Wraps the list of non-function, non-classdef statements of a script as
+ * a synthetic `FunctionDef` whose parameters are the live-in env vars
+ * and whose outputs are every variable assigned in the script. On
+ * success the compiled code runs once and all output values are written
+ * back to the interpreter's workspace env.
+ *
+ * Mirrors `tryJitLoop` in jitLoop.ts — same lowering, same JS/C backend
+ * pipeline, same progressive type widening. The differences:
+ *   - the synthetic body is the list of stmts directly, not a single For/While
+ *   - every assigned variable is live-out (the whole workspace is live)
+ *   - cache key is per-Interpreter (a single script AST per interp run)
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
+/**
+ * Attempt to JIT-compile and execute the top-level script body.
+ * Returns true if JIT succeeded, false to fall back to interpretation.
+ */
+export declare function tryJitTopLevel(interp: Interpreter, stmts: Stmt[]): boolean;

package/dist-lib/numbl-core/jit/jitTypes.d.ts

@@ -0,0 +1,394 @@
+/**
+ * JIT type system and IR node definitions.
+ */
+import type { BinaryOperation, UnaryOperation } from "../parser/types.js";
+export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
+export type JitType = {
+    kind: "number";
+    exact?: number;
+    sign?: SignCategory;
+    isInteger?: boolean;
+} | {
+    kind: "boolean";
+    value?: boolean;
+} | {
+    kind: "complex_or_number";
+    pureImaginary?: boolean;
+} | {
+    kind: "tensor";
+    isComplex: boolean;
+    shape?: number[];
+    ndim?: number;
+    isLogical?: boolean;
+    nonneg?: boolean;
+} | {
+    kind: "string";
+    value?: string;
+} | {
+    kind: "char";
+    value?: string;
+} | {
+    kind: "struct";
+    fields?: Record<string, JitType>;
+} | {
+    /**
+     * A 1-D homogeneous array of structs (matlab struct array form
+     * `T.nodes(i)`). `elemFields` records the per-element field types
+     * unified across all elements. `length` is optional and carries
+     * the statically-known element count when available.
+     */
+    kind: "struct_array";
+    elemFields?: Record<string, JitType>;
+    length?: number;
+} | {
+    kind: "class_instance";
+    className: string;
+    isHandleClass?: boolean;
+    fields?: Record<string, JitType>;
+} | {
+    kind: "sparse_matrix";
+    isComplex: boolean;
+    m?: number;
+    n?: number;
+} | {
+    kind: "cell";
+    shape?: number[];
+} | {
+    kind: "dictionary";
+} | {
+    kind: "function_handle";
+} | {
+    kind: "unknown";
+};
+export declare function signFromNumber(v: number): SignCategory | undefined;
+export declare function isNonneg(t: JitType): boolean;
+export declare function flipSign(s?: SignCategory): SignCategory | undefined;
+export declare function unifySign(a?: SignCategory, b?: SignCategory): SignCategory | undefined;
+export declare function jitTypeKey(t: JitType): string;
+export declare function computeJitCacheKey(nargout: number, argTypes: JitType[]): string;
+/** Compute a unique JS function name for a JIT'd specialization. */
+export declare function computeJitFnName(identity: string, funcName: string): string;
+/** Widen/unify two types at control-flow join points. */
+export declare function unifyJitTypes(a: JitType, b: JitType): JitType;
+export declare function isScalarType(t: JitType): boolean;
+export declare function isNumericScalarType(t: JitType): boolean;
+export declare function isTensorType(t: JitType): boolean;
+export declare function isComplexType(t: JitType): boolean;
+/** True when the type guarantees an integer value at runtime (safe for |0). */
+export declare function isKnownInteger(t: JitType): boolean;
+/** Types that support arithmetic binary operations in the JIT. */
+export declare function isArithmeticType(t: JitType): boolean;
+export declare function shapeAfterReduction(shape: number[], dim?: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    shape: number[];
+};
+export type JitExpr = {
+    tag: "NumberLiteral";
+    value: number;
+    jitType: JitType;
+} | {
+    tag: "ImagLiteral";
+    jitType: JitType;
+} | {
+    tag: "Var";
+    name: string;
+    jitType: JitType;
+} | {
+    tag: "Binary";
+    op: BinaryOperation;
+    left: JitExpr;
+    right: JitExpr;
+    jitType: JitType;
+} | {
+    tag: "Unary";
+    op: UnaryOperation;
+    operand: JitExpr;
+    jitType: JitType;
+} | {
+    tag: "StringLiteral";
+    value: string;
+    isChar: boolean;
+    jitType: JitType;
+} | {
+    tag: "Call";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    tag: "UserCall";
+    jitName: string;
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    tag: "Index";
+    base: JitExpr;
+    indices: JitExpr[];
+    jitType: JitType;
+} | {
+    /**
+     * Range slice read on a real tensor: `src(a:b)` producing a fresh
+     * column-vector tensor of length `b - a + 1`. Stage 21 — unblocks
+     * chunkie's chunk_nearparam Newton loop which splits a Legendre
+     * expansion vector via `r0 = all0(1:dim)`.
+     *
+     * Codegen emits `$h.subarrayCopy1r(srcData, srcLen, start, end)`
+     * using the hoisted data/length aliases. Per-iter allocation is
+     * unavoidable without a range-alias extension to stage 5; small
+     * slices are cheap in V8 young-gen.
+     */
+    tag: "RangeSliceRead";
+    baseName: string;
+    start: JitExpr;
+    /** `null` when the range endpoint is the `end` keyword — codegen
+     *  substitutes the hoisted `.data.length` alias. */
+    end: JitExpr | null;
+    /** True when the source is a statically-known row vector
+     *  (shape `[1, n]`); the slice then preserves row orientation.
+     *  Otherwise the slice is a column vector (MATLAB semantics). */
+    isRow: boolean;
+    jitType: JitType;
+} | {
+    tag: "TensorLiteral";
+    rows: JitExpr[][];
+    nRows: number;
+    nCols: number;
+    jitType: JitType;
+} | {
+    /**
+     * Vertical concat growth: `[base; value]` where `base` is a real
+     * column-vector (or empty) tensor and `value` is a numeric scalar.
+     * Lowered from the chunkie grow-a-list pattern `it = [it; i]`.
+     * Codegens to `$h.vconcatGrow1r(base, value)` which allocates a
+     * fresh `(k+1, 1)` tensor and copies.
+     */
+    tag: "VConcatGrow";
+    base: JitExpr;
+    value: JitExpr;
+    jitType: JitType;
+} | {
+    /**
+     * Scalar read of a struct field: `s.f` where `s` has a struct type
+     * with a statically-known scalar field `f`. Lowered from `Member`
+     * exprs with an `Ident` base. The codegen hoists each unique
+     * `(baseName, fieldName)` pair to a local alias at function entry
+     * so per-iter reads are bare local loads (no `Map.get` per use).
+     * Mirrors the chunkie `opts.rho`, `chnkr.k`, `chnkr.nch` pattern.
+     */
+    tag: "MemberRead";
+    baseName: string;
+    fieldName: string;
+    jitType: JitType;
+} | {
+    /**
+     * Chained struct array member read: `T.nodes(i).leaf` where
+     * `T.nodes` is a struct array whose elements all share a field
+     * `leaf`. Lowered from the parser shape
+     * `Member(MethodCall(Ident(T), "nodes", [i]), "leaf")`.
+     *
+     * Codegen hoists `var $T_nodes_elements = T.fields.get("nodes").elements`
+     * at function entry (one alias per unique (structVarName,
+     * structArrayFieldName) pair) and emits
+     * `$T_nodes_elements[Math.round(i) - 1].fields.get("leaf")` per use.
+     *
+     * `leafFieldJitType` records the result type: either a scalar
+     * numeric type (number/boolean/complex_or_number) or a real tensor.
+     * Tensor-valued leaves work because the existing per-Assign hoist
+     * refresh picks up the newly-read tensor when the result flows
+     * into `chld = T.nodes(i).chld` and the callers then use
+     * `chld(k)` through the hoisted alias path.
+     */
+    tag: "StructArrayMemberRead";
+    structVarName: string;
+    structArrayFieldName: string;
+    indexExpr: JitExpr;
+    leafFieldName: string;
+    jitType: JitType;
+} | {
+    /**
+     * Indirect call through a function handle variable: `f(a, b)` where
+     * `f` has JitType `function_handle`. The codegen emits
+     * `$h.callFuncHandle($rt, f, arg1, arg2, ...)` which invokes the
+     * handle via its `jsFn` closure (or falls back to `rt.dispatch`).
+     * The `returnType` is determined at lowering time by probing the
+     * function handle's runtime value.
+     */
+    tag: "FuncHandleCall";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    /**
+     * User function call that bailed recursive lowering (stage 24 —
+     * soft-bail). Instead of bailing the containing loop, emit a
+     * runtime dispatch through the interpreter. Return type is
+     * determined at JIT compile time by probing (actually calling
+     * the function once with representative args). The helper
+     * `callUserFunc` verifies the actual return type on every call
+     * and throws `JitFuncHandleBailError` on mismatch so the loop
+     * runner can invalidate the cache entry and fall back to
+     * interpretation.
+     *
+     * Use case: `oneintp(...)` / `lege.exev(...)` in chunkie's adap
+     * inner loop — the callee body has tensor arithmetic the JIT
+     * can't inline, but the outer loop (scalar stack + col-slice
+     * writes + scalar compares) is a perfect JIT fit.
+     */
+    tag: "UserDispatchCall";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+};
+export type JitStmt = {
+    tag: "Assign";
+    name: string;
+    expr: JitExpr;
+} | {
+    tag: "AssignIndex";
+    /** Name of the tensor variable being written to (must be an Ident-based lvalue). */
+    baseName: string;
+    /** Scalar index expressions (1..3). */
+    indices: JitExpr[];
+    /** RHS scalar value to store. */
+    value: JitExpr;
+    /** Type of the base tensor (for codegen to choose the right helper). */
+    baseType: JitType;
+} | {
+    /**
+     * Range-slice write of the form `dst(a:b) = src(c:d)` or
+     * `dst(a:b) = src` (whole-tensor source). Both `dst` and `src` must
+     * be real tensors, and the LHS must use exactly one (linear) range
+     * index. Used by the loop JIT for the chunkie grow-and-copy pattern.
+     *
+     * When `srcStart` and `srcEnd` are both `null`, the source is used
+     * in its entirety — codegen substitutes `1` and `srcLen` (the
+     * source's hoisted length alias). This is stage 9's whole-tensor
+     * RHS form: `isp(1:nn) = itemp` where `itemp` is a plain Var.
+     */
+    tag: "AssignIndexRange";
+    baseName: string;
+    baseType: JitType;
+    dstStart: JitExpr;
+    dstEnd: JitExpr;
+    srcBaseName: string;
+    srcType: JitType;
+    srcStart: JitExpr | null;
+    srcEnd: JitExpr | null;
+} | {
+    /**
+     * Multi-dim column slice write `dst(:, j) = src` where both `dst`
+     * and `src` are real tensors. LHS must be `Index(Ident(dst),
+     * [Colon, scalar_j])` with `dst` having statically 2-D shape.
+     * RHS must be a plain Ident referencing a real-tensor var whose
+     * total element count matches `dst.shape[0]` at runtime.
+     *
+     * Used by the loop JIT for chunkie's adapgausskerneval column
+     * stack write: `vals(:, jj+1) = v2`. Also covers
+     * chunkerinterior's `rss(:, jj) = rval(:, k)` after a slice
+     * alias binds the RHS.
+     */
+    tag: "AssignIndexCol";
+    baseName: string;
+    baseType: JitType;
+    colIndex: JitExpr;
+    srcBaseName: string;
+    srcType: JitType;
+} | {
+    /**
+     * Page-slice write `dst(:, :, k) = rhs` where `dst` is a 3-D tensor
+     * and `rhs` is a 2-D tensor. Real-base + complex-rhs upgrades the
+     * base to complex in place.  Drives chunkie helm2d.green's
+     * `grad(:,:,k) = ...` / `hess(:,:,k) = ...` assignments.
+     */
+    tag: "AssignIndexPage3d";
+    baseName: string;
+    /** Base tensor type AFTER the write (may be complex even if the
+     *  initializer was real — the lowerer promotes in ctx.env). */
+    baseType: JitType;
+    /** Page index (1-based). */
+    pageIndex: JitExpr;
+    /** 2-D tensor RHS. */
+    value: JitExpr;
+} | {
+    /**
+     * Struct field assign lvalue `s.f = v`. When `needsPromote` is
+     * true, the base is (re)initialized as a fresh empty struct
+     * before the field is set — mirrors MATLAB's
+     * `s = []; s.f = v` idiom that promotes the empty matrix to a
+     * struct on first field write. `valueType` is the JIT type of
+     * `value` so stage 12 can hoist subsequent reads through a
+     * typed alias.
+     */
+    tag: "AssignMember";
+    baseName: string;
+    fieldName: string;
+    value: JitExpr;
+    needsPromote: boolean;
+} | {
+    tag: "If";
+    cond: JitExpr;
+    thenBody: JitStmt[];
+    elseifBlocks: {
+        cond: JitExpr;
+        body: JitStmt[];
+    }[];
+    elseBody: JitStmt[] | null;
+} | {
+    tag: "For";
+    varName: string;
+    start: JitExpr;
+    step: JitExpr | null;
+    end: JitExpr;
+    body: JitStmt[];
+} | {
+    tag: "While";
+    cond: JitExpr;
+    body: JitStmt[];
+} | {
+    tag: "Break";
+} | {
+    tag: "Continue";
+} | {
+    tag: "Return";
+} | {
+    tag: "ExprStmt";
+    expr: JitExpr;
+} | {
+    tag: "MultiAssign";
+    names: (string | null)[];
+    callName: string;
+    args: JitExpr[];
+    outputTypes: JitType[];
+} | {
+    /**
+     * Call a synthetic specialization (installed as a forwarder on $h)
+     * and write back multiple outputs into outer-scope vars. Only
+     * produced by the hybrid-loop pass in hybrid.ts, which
+     * replaces a For/While JitStmt with this call form when the
+     * extracted loop specialization compiled to native C.
+     *
+     * Semantics (0 / 1 / N outputs):
+     *   nargout==0 → emit `$h.callUser(...)` as a stmt (no writeback)
+     *   nargout==1 → emit `out = $h.callUser(...)`
+     *   nargout>=2 → emit `var $r = $h.callUser(...); out0=$r[0]; ...`
+     */
+    tag: "UserCallWriteback";
+    outputs: string[];
+    jitName: string;
+    name: string;
+    args: JitExpr[];
+    outputTypes: JitType[];
+} | {
+    tag: "SetLoc";
+    line: number;
+} | {
+    /** C-JIT assertion: if this JitStmt survives to JS codegen at --opt 2,
+     *  emit a runtime throw. The C-JIT codegen elides it. */
+    tag: "AssertCJit";
+};
+export interface JitCacheEntry {
+    fn: (...args: unknown[]) => unknown;
+    source: string;
+}

package/dist-lib/numbl-core/jit/js/jitCodegen.d.ts

@@ -0,0 +1,7 @@
+/**
+ * JIT IR -> JavaScript code generation.
+ *
+ * IR walkers for hoist-pass data collection are in jitCodegenHoist.ts.
+ */
+import { type JitStmt } from "../jitTypes.js";
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string, fuse?: boolean, experimental?: string): string;

package/dist-lib/numbl-core/jit/js/jitCodegenHoist.d.ts

@@ -0,0 +1,70 @@
+/**
+ * IR walkers for the JIT codegen hoist pass.
+ *
+ * These pure functions walk the JIT IR to collect information needed
+ * for hoisting tensor aliases, struct field reads, and struct array
+ * element reads to the top of the generated function.
+ */
+import type { JitStmt } from "../jitTypes.js";
+/**
+ * Hoisted aliases for a tensor variable read/written in the loop body.
+ * Maps the original variable name to local JS identifiers for its
+ * .data, .data.length, .shape[0], and .shape[1].
+ */
+export interface HoistedAlias {
+    data: string;
+    len: string;
+    d0: string;
+    d1: string;
+    maxDim: number;
+    isWriteTarget: boolean;
+    isParam: boolean;
+}
+export declare function structFieldKey(baseName: string, fieldName: string): string;
+export declare function structArrayElementsKey(structVarName: string, structArrayFieldName: string): string;
+export interface TensorUsage {
+    maxReadDim: number;
+    maxWriteDim: number;
+    isReal: boolean;
+}
+/**
+ * Walk the JIT IR collecting, for every variable that appears as the base
+ * of an Index read, AssignIndex write, or AssignIndexRange write, the
+ * maximum indexing arity and whether all uses are on a real tensor.
+ */
+export declare function collectTensorUsage(body: JitStmt[]): Map<string, TensorUsage>;
+/**
+ * Walk the JIT IR collecting every base name that is the target of an
+ * `AssignMember` stmt (stage 22 struct field write). Used by the
+ * codegen to emit a one-time `$h.structUnshare_h(s)` at function entry
+ * for any such name that is also a function parameter — this preserves
+ * MATLAB value semantics when structs are passed by value and the
+ * callee mutates a field.
+ */
+export declare function collectStructMemberWrites(body: JitStmt[]): Set<string>;
+/**
+ * Walk the JIT IR collecting every name that is the target of any
+ * plain `Assign` stmt. Used by the stage-12 struct-field-read hoist to
+ * decide whether a struct-typed param is safe to hoist: if the body
+ * ever reassigns the name (e.g. `s = [];` promoted to struct, or `s =
+ * struct()` inside the loop), the pre-loop hoisted field aliases would
+ * be stale and must be disabled.
+ */
+export declare function collectPlainAssignTargets(body: JitStmt[]): Set<string>;
+/**
+ * Walk the JIT IR collecting all unique (baseName, fieldName) pairs
+ * referenced by MemberRead nodes. The codegen hoists each pair as a
+ * local alias at function entry.
+ */
+export declare function collectStructFieldReads(body: JitStmt[]): Map<string, {
+    baseName: string;
+    fieldName: string;
+}>;
+/**
+ * Walk the JIT IR collecting all unique (structVarName, structArrayFieldName)
+ * pairs referenced by StructArrayMemberRead nodes.
+ */
+export declare function collectStructArrayElementReads(body: JitStmt[]): Map<string, {
+    structVarName: string;
+    structArrayFieldName: string;
+}>;