numbl 0.1.7 → 0.3.0

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

@@ -0,0 +1,25 @@
+/**
+ * Shared fusible-operation name sets for JIT fusion analysis.
+ *
+ * Both the C-JIT and JS-JIT fusion paths use these to determine which
+ * tensor Call nodes are fusible element-wise unary ops or absorbable
+ * trailing reductions. The numeric op codes live in their respective
+ * backend files (feasibility.ts for C, jitHelpersTensor.ts for JS).
+ */
+/** Tensor unary builtins fusible into per-element loops. */
+export declare const FUSIBLE_TENSOR_UNARY_OPS: ReadonlySet<string>;
+/**
+ * JS-JIT-safe subset: excludes transcendentals (exp, sin, cos, tan, etc.)
+ * which V8 can't SIMD-vectorize. Fusing these into a scalar per-element
+ * loop is slower than calling libnumbl_ops per-op (which uses -fopenmp-simd).
+ * The C-JIT uses the full set because GCC/Clang vectorize via #pragma omp simd.
+ */
+export declare const FUSIBLE_TENSOR_UNARY_OPS_JS: ReadonlySet<string>;
+/**
+ * Two-argument tensor element-wise builtins fusible into per-element loops.
+ * These are parsed as Call nodes (not Binary nodes) and need separate
+ * recognition in isPureElementwise / emitScalarExpr.
+ */
+export declare const FUSIBLE_TENSOR_BINARY_OPS: ReadonlySet<string>;
+/** Tensor reduction builtins absorbable as trailing reductions. */
+export declare const FUSIBLE_TENSOR_REDUCTION_OPS: ReadonlySet<string>;

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

@@ -0,0 +1,15 @@
+/**
+ * Shared heavy-op heuristic for fused-loop emitters (e1 and e2).
+ *
+ * Counts the number of "expensive" math operations in a JitExpr — the
+ * kind of work that's heavy enough per element that OpenMP thread-
+ * spawn overhead pays off at N >= 100k. Arithmetic-only chains skip
+ * the parallel-for pragma because threads slow them down: the body
+ * becomes memory-bandwidth-bound and adding threads only adds overhead.
+ */
+import type { JitExpr } from "./jitTypes.js";
+export declare function countHeavyOps(expr: JitExpr): number;
+/** Minimum element count before `#pragma omp parallel for simd` kicks
+ *  in. Below this the thread-spawn cost dominates the work.
+ *  Overridable via `NUMBL_OMP_THRESHOLD` for benchmarks. */
+export declare function ompParallelThreshold(): number;

package/dist-lib/numbl-core/{interpreter/jit → jit}/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * JIT compilation entry point for interpreter function calls.
  */
-import type { Interpreter } from "../interpreter.js";
-import type { FunctionDef } from "../types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { FunctionDef } from "../interpreter/types.js";
 export declare const JIT_SKIP: unique symbol;
 export declare function tryJitCall(interp: Interpreter, fn: FunctionDef, args: unknown[], nargout: number): unknown | typeof JIT_SKIP;

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

@@ -0,0 +1,41 @@
+/**
+ * Bail-safety gate for JIT bodies that contain I/O side effects.
+ *
+ * Mid-execution bails (JitBailToInterpreter / JitFuncHandleBailError)
+ * cause the interpreter to re-run the body from the top. If the body
+ * already emitted I/O before the bail, that output gets duplicated —
+ * which the user would notice.
+ *
+ * Rule: a body with any I/O statement may only be JIT-compiled if we
+ * can prove no bail can happen during execution. If there's no I/O,
+ * the body can be JIT'd normally (a bail just restarts silently).
+ *
+ * Walkers are IR-level — they see the actual lowered constructs that
+ * map 1:1 to runtime bail sites. The walkers recurse into the bodies
+ * of `UserCall`-ed functions (via `generatedIRBodies`), since a bail
+ * inside a callee still forces the caller to re-run.
+ */
+import type { JitStmt } from "./jitTypes.js";
+import type { GeneratedFn } from "./jitLower.js";
+/**
+ * Names of I/O-emitting builtins that the JIT is willing to lower as
+ * ExprStmt calls. Any `Call` to one of these in the lowered IR marks
+ * the body as having observable I/O.
+ */
+export declare const JIT_IO_BUILTINS: Set<string>;
+/**
+ * Walk a body + its transitively called function bodies and return
+ * whether the combined execution graph contains an I/O call.
+ */
+export declare function irHasIO(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;
+/**
+ * Walk a body + its transitively called function bodies and return
+ * whether any construct exists that can throw `JitBailToInterpreter`
+ * or `JitFuncHandleBailError` at runtime.
+ *
+ * Bail-risky constructs:
+ *   - AssignIndex / AssignIndexCol: may bail on out-of-bounds grow.
+ *   - FuncHandleCall / UserDispatchCall: return-type check may bail.
+ *   - UserCall: recurse into callee body.
+ */
+export declare function irHasBailRisk(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;

package/dist-lib/numbl-core/{interpreter/jit → jit}/jitLoop.d.ts

@@ -7,8 +7,8 @@
  * inside the loop body. On success the compiled code runs and output
  * values are written back to the interpreter environment.
  */
-import type { Interpreter } from "../interpreter.js";
-import type { Stmt } from "../../parser/types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
 /**
  * Attempt to JIT-compile and execute a for-loop statement.
  * Returns true if JIT succeeded, false to fall back to interpretation.

package/dist-lib/numbl-core/{interpreter/jit → jit}/jitLoopAnalysis.d.ts

@@ -6,7 +6,7 @@
  * - referenced: variables read inside the loop
  * - hasReturn: whether the loop body contains a return statement
  */
-import type { Stmt } from "../../parser/types.js";
+import type { Stmt } from "../parser/types.js";
 export interface LoopVarInfo {
     /** Variables referenced in the loop that must come from enclosing scope */
     inputs: string[];
@@ -26,6 +26,11 @@ export declare function analyzeForLoop(stmt: Stmt & {
  * back when no later code reads them.
  */
 export declare function collectReadsFromSiblings(stmts: Stmt[], startIdx: number, out: Set<string>): void;
+/**
+ * Analyze a top-level script body (list of statements) for JIT compilation.
+ * Used by `tryJitTopLevel` to wrap the whole main script as a synthetic fn.
+ */
+export declare function analyzeTopLevel(stmts: Stmt[]): LoopVarInfo;
 /** Analyze a while loop statement for JIT compilation. */
 export declare function analyzeWhileLoop(stmt: Stmt & {
     type: "While";

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/{interpreter/jit → jit}/jitLowerTypes.d.ts

@@ -9,8 +9,8 @@
  *
  * These have no dependency on LowerCtx or the lowering state.
  */
-import { BinaryOperation, UnaryOperation } from "../../parser/types.js";
-import { type JitType, type SignCategory } from "./jitTypes.js";
+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;
@@ -21,5 +21,9 @@ 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): JitType | null;
+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/{interpreter/jit → jit}/jitTypes.d.ts

@@ -1,7 +1,7 @@
 /**
  * JIT type system and IR node definitions.
  */
-import type { BinaryOperation, UnaryOperation } from "../../parser/types.js";
+import type { BinaryOperation, UnaryOperation } from "../parser/types.js";
 export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
 export type JitType = {
     kind: "number";
@@ -55,6 +55,8 @@ export type JitType = {
     shape?: number[];
 } | {
     kind: "dictionary";
+} | {
+    kind: "function_handle";
 } | {
     kind: "unknown";
 };
@@ -125,6 +127,29 @@ export type JitExpr = {
     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[][];
@@ -181,6 +206,40 @@ export type JitExpr = {
     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";
@@ -217,6 +276,56 @@ export type JitStmt = {
     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;
@@ -252,9 +361,32 @@ export type JitStmt = {
     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;

package/dist-lib/numbl-core/{interpreter/jit → jit/js}/jitCodegen.d.ts

@@ -3,5 +3,5 @@
  *
  * 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): string;
+import { type JitStmt } from "../jitTypes.js";
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string, experimental?: string, par?: boolean): string;

package/dist-lib/numbl-core/{interpreter/jit → jit/js}/jitCodegenHoist.d.ts

@@ -5,7 +5,7 @@
  * 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";
+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
@@ -33,6 +33,24 @@ export interface TensorUsage {
  * 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

package/dist-lib/numbl-core/{interpreter/jit → jit/js}/jitHelpers.d.ts

@@ -11,10 +11,22 @@
  * creates a fresh snapshot via a single spread expression.
  */
 export { re, im, mkc, cAdd, cSub, cMul, cDiv, cNeg, cConj, cAngle, cTruthy, } from "./jitHelpersComplex.js";
-export { bce, idx1, idx2, idxN, idx1r, idx2r, idx3r, idx1r_h, idx2r_h, idx3r_h, set1r_h, set2r_h, set3r_h, setRange1r_h, } from "./jitHelpersIndex.js";
-export { makeTensor, tensorBinaryOp, tensorCompareOp, tensorUnary, tensorNeg, vconcatGrow1r, unshare, asTensor, tAdd, tSub, tMul, tDiv, tPow, tEq, tNeq, tLt, tLe, tGt, tGe, } from "./jitHelpersTensor.js";
+export { bce, idx1, idx2, idxN, idx1r, idx2r, idx3r, idx1r_h, idx2r_h, idx3r_h, set1r_h, set2r_h, set3r_h, setRange1r_h, setCol2r_h, subarrayCopy1r, subarrayCopy1rRow, } from "./jitHelpersIndex.js";
+export { makeTensor, tensorBinaryOp, tensorCompareOp, tensorUnary, tensorNeg, vconcatGrow1r, unshare, shareTensor, asTensor, tDouble, tSum, tAdd, tSub, tMul, tDiv, tPow, tEq, tNeq, tLt, tLe, tGt, tGe, } from "./jitHelpersTensor.js";
+export { JitBailToInterpreter } from "./jitHelpersIndex.js";
+/**
+ * Thrown when a function handle called from JIT code returns a type
+ * different from what the JIT expected (determined by probing at compile
+ * time). The loop runner catches this and falls back to interpretation.
+ */
+export declare class JitFuncHandleBailError extends Error {
+    readonly fnName: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    constructor(fnName: string, expectedType: string, actualType: string);
+}
 export declare const jitHelpers: Record<string, unknown>;
-import type { IBuiltin } from "../builtins/index.js";
+import type { IBuiltin } from "../../interpreter/builtins/index.js";
 /**
  * Build a per-runtime jitHelpers snapshot. Uses a single spread expression
  * for a fresh V8 hidden class (critical for inline-cache performance).

package/dist-lib/numbl-core/{interpreter/jit → jit/js}/jitHelpersIndex.d.ts

@@ -10,6 +10,10 @@
  * checks to ensure consistency with the interpreter.
  */
 import { type FloatXArrayType, type RuntimeTensor } from "../../runtime/types.js";
+export declare class JitBailToInterpreter extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
 export declare function bce(): never;
 export declare function idx1(base: unknown, i: number): unknown;
 export declare function idx2(base: unknown, ri: number, ci: number): unknown;
@@ -24,3 +28,6 @@ export declare function set1r_h(data: FloatXArrayType, len: number, i: number, v
 export declare function set2r_h(data: FloatXArrayType, len: number, rows: number, ri: number, ci: number, v: number): void;
 export declare function set3r_h(data: FloatXArrayType, len: number, d0: number, d1: number, i1: number, i2: number, i3: number, v: number): void;
 export declare function setRange1r_h(dstData: FloatXArrayType, dstLen: number, dstStart: number, dstEnd: number, srcData: FloatXArrayType, srcLen: number, srcStart: number, srcEnd: number): void;
+export declare function subarrayCopy1r(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function subarrayCopy1rRow(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function setCol2r_h(dstData: FloatXArrayType, dstRows: number, dstLen: number, col: number, srcData: FloatXArrayType, srcLen: number): void;

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

@@ -0,0 +1,34 @@
+/**
+ * Tensor operation helpers for JIT-compiled code.
+ * Handles element-wise binary/unary ops, comparison ops, concat, and
+ * tensor coercion for struct-array field access.
+ */
+import { type FloatXArrayType, type RuntimeTensor } from "../../runtime/types.js";
+import type { RuntimeComplexNumber } from "../../runtime/types.js";
+export declare function makeTensor(data: FloatXArrayType, imag: FloatXArrayType | undefined, shape: number[]): RuntimeTensor;
+/** Bump rc on a tensor (no-op for non-tensor values). Used for var-to-var
+ *  JIT assignments so the aliased tensor is no longer eligible for
+ *  in-place buffer reuse. */
+export declare function shareTensor(v: unknown): unknown;
+type ScalarVal = number | RuntimeComplexNumber;
+export declare function tensorBinaryOp(a: unknown, b: unknown, realOp: (x: number, y: number) => number, complexOp: (a: ScalarVal, b: ScalarVal) => ScalarVal): RuntimeTensor | ScalarVal;
+export declare function tensorCompareOp(a: unknown, b: unknown, cmp: (x: number, y: number) => boolean): RuntimeTensor;
+export declare function tensorUnary(dest: unknown, a: RuntimeTensor, fn: (x: number) => number): RuntimeTensor;
+export declare function tensorNeg(dest: unknown, a: RuntimeTensor): RuntimeTensor;
+export declare function tDouble(v: unknown): unknown;
+export declare function tSum(v: unknown): unknown;
+export declare function vconcatGrow1r(base: unknown, v: number): RuntimeTensor;
+export declare function unshare(t: unknown): RuntimeTensor;
+export declare function asTensor(v: unknown): RuntimeTensor;
+export declare const tAdd: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tSub: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tMul: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tDiv: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tPow: (_dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tEq: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tNeq: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tLt: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tLe: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tGt: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tGe: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * Fused per-element loop emission for the JS-JIT.
+ *
+ * Given a FusibleChain (from fusion.ts), emits a single block-scoped
+ * JavaScript `for` loop that evaluates all the chain's tensor assigns
+ * as inline scalar expressions per element — no $h.tAdd / $h.tMul
+ * helper calls, no intermediate tensor allocations.
+ *
+ * Tensor var references become either:
+ *   - `__<name>_data[__i]`  for input params / pre-existing tensors
+ *   - `__f_<name>`           for chain-produced intermediates (scalar local)
+ *
+ * The optional trailing reduction is absorbed as an inline accumulator
+ * inside the same loop.
+ */
+import type { FusibleChain } from "../fusion.js";
+export declare function emitJsFusedChain(lines: string[], indent: string, chain: FusibleChain, allTensorVars: ReadonlySet<string>, paramTensors: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>, _localTensorNames: ReadonlySet<string>, complexTensorNames: ReadonlySet<string>, complexScalarVars: ReadonlySet<string>, mangle: (n: string) => string, experimental?: string, par?: boolean): void;