numbl 0.3.0 → 0.3.3

package/dist-lib/numbl-core/{jit/js → executors/jsJit/codegen}/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, experimental?: string, par?: boolean): string;
+import { type JitStmt } from "../../../jitTypes.js";
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string): string;

package/dist-lib/numbl-core/{jit/js → executors/jsJit/codegen}/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

package/dist-lib/numbl-core/{jit/js → executors/jsJit/codegen}/jsMultiReduction.d.ts

@@ -6,12 +6,11 @@
  *   acc = <expr tree with >=2 reductions over a single tensor Var>
  *
  * On match, the JS codegen emits a block that runs a single-pass
- * reduction loop (either an inline JS loop, or a compiled C kernel
- * under --opt e1), stashes each reduction result in a local, and then
- * emits the Assign's RHS with each reduction Call substituted by the
- * local that holds its value. The RHS-substitution contract lives in
- * `jitCodegen._multiReductionSubst`, which this module installs and
- * clears around the `emitExpr` call the caller provides.
+ * inline JS reduction loop, stashes each reduction result in a local,
+ * and then emits the Assign's RHS with each reduction Call substituted
+ * by the local that holds its value. The RHS-substitution contract
+ * lives in `jitCodegen._multiReductionSubst`, which this module
+ * installs and clears around the `emitExpr` call the caller provides.
  *
  * Limited to:
  *   - sum / prod / max / min / mean (short-circuit any/all excluded)
@@ -24,8 +23,8 @@
  * IEEE unordered compare already skips NaN, and an `any_non_nan` flag
  * drives the all-NaN → NaN fallback.
  */
-import type { JitExpr, JitStmt } from "../jitTypes.js";
-import { type MultiReduceOp } from "../e1/multiReductionKernel.js";
+import type { JitExpr, JitStmt } from "../../../jitTypes.js";
+type MultiReduceOp = "sum" | "prod" | "max" | "min" | "mean";
 export interface MultiReductionMatch {
     /** The scalar Assign being emitted (target + original RHS). */
     stmt: JitStmt & {
@@ -54,17 +53,15 @@ export declare function tryMatchMultiReduction(stmt: JitStmt): MultiReductionMat
  *
  * The block:
  *   1. Aliases `<tensorName>.data` to a local and reads its length.
- *   2. Under e1, compiles/dispatches a single-pass C kernel that fills
- *      a Float64Array scratch with the accumulator values, with an
- *      inline JS fallback at small `n`. Under non-e1, emits just the
- *      JS loop.
+ *   2. Emits a single-pass JS loop that updates each accumulator.
  *   3. Post-loop: `mean = sum / n`, and a NaN fixup for max/min when
  *      every input element was NaN.
  *   4. Installs `_multiReductionSubst` pointing each reduction Call at
  *      its local, emits the Assign's RHS via the caller-provided
  *      `emitExpr`, and writes the final `<target> = <rhs>;`.
  */
-export declare function emitMultiReductionBlock(lines: string[], indent: string, match: MultiReductionMatch, mangleName: (n: string) => string, emitExprWithSubst: (expr: JitExpr, subst: Map<JitExpr, string>) => string, experimental: string | undefined, par: boolean): void;
+export declare function emitMultiReductionBlock(lines: string[], indent: string, match: MultiReductionMatch, mangleName: (n: string) => string, emitExprWithSubst: (expr: JitExpr, subst: Map<JitExpr, string>) => string): void;
 /** Reset per-function counter so generated names stay stable between
  *  compiles of the same IR. Called from `generateJS`. */
 export declare function resetMultiReductionState(): void;
+export {};

package/dist-lib/numbl-core/executors/jsJit/helpers/alloc.d.ts

@@ -0,0 +1,12 @@
+/** Allocate a Float64Array. Thin wrapper around `new Float64Array(x)`
+ *  kept as a single allocation site so future strategies (pooling,
+ *  COW-aware allocation, etc.) can be reintroduced without touching
+ *  every callsite. */
+export declare function allocFloat64Array(x: number | number[] | Float64Array): Float64Array;
+/** No-op. Kept as a placeholder for future explicit-release strategies
+ *  (e.g. pool release, arena reset). With pure JS GC, scratch buffers
+ *  are reclaimed when the wrapper goes out of scope. */
+export declare function releaseFloat64Array(_buf: Float64Array): void;
+/** Pass-through. Kept as a placeholder for future scratch-arena
+ *  strategies. Today it just runs `fn` and returns its result. */
+export declare function withScratch<T>(fn: () => T): T;

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

@@ -12,7 +12,7 @@
  */
 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, 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 { makeTensor, tensorBinaryOp, tensorCompareOp, tensorUnary, tensorNeg, vconcatGrow1r, unshare, 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
@@ -26,7 +26,7 @@ export declare class JitFuncHandleBailError extends Error {
     constructor(fnName: string, expectedType: string, actualType: string);
 }
 export declare const jitHelpers: Record<string, unknown>;
-import type { IBuiltin } from "../../interpreter/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/{jit/js → executors/jsJit/helpers}/jitHelpersComplex.d.ts

@@ -2,7 +2,7 @@
  * Complex number arithmetic helpers for JIT-compiled code.
  * These are pure functions used by the $h helpers object.
  */
-import type { RuntimeComplexNumber } from "../../runtime/types.js";
+import { RuntimeComplexNumber } from "../../../runtime/types.js";
 export declare function re(v: unknown): number;
 export declare function im(v: unknown): number;
 export declare function mkc(r: number, i: number): number | RuntimeComplexNumber;

package/dist-lib/numbl-core/executors/jsJit/helpers/jitHelpersIndex.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tensor indexing helpers for JIT-compiled code.
+ *
+ * Three tiers of helpers, from most general to most specialized:
+ * 1. Generic (idx1, idx2, idxN) — handle any base type, real or complex
+ * 2. Real-tensor fast path (idx1r, idx2r, idx3r) — skip type/imag checks
+ * 3. Hoisted-base (idx*r_h, set*r_h) — take pre-extracted data/len/shape
+ *
+ * All helpers use 1-based MATLAB indexing and include per-dimension bounds
+ * checks to ensure consistency with the interpreter.
+ */
+import { 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;
+export declare function idxN(base: unknown, indices: number[]): unknown;
+export declare function idx1r(base: RuntimeTensor, i: number): number;
+export declare function idx2r(base: RuntimeTensor, ri: number, ci: number): number;
+export declare function idx3r(base: RuntimeTensor, i1: number, i2: number, i3: number): number;
+export declare function idx1r_h(data: Float64Array, len: number, i: number): number;
+export declare function idx2r_h(data: Float64Array, len: number, rows: number, ri: number, ci: number): number;
+export declare function idx3r_h(data: Float64Array, len: number, d0: number, d1: number, i1: number, i2: number, i3: number): number;
+export declare function set1r_h(data: Float64Array, len: number, i: number, v: number): void;
+export declare function set2r_h(data: Float64Array, len: number, rows: number, ri: number, ci: number, v: number): void;
+export declare function set3r_h(data: Float64Array, len: number, d0: number, d1: number, i1: number, i2: number, i3: number, v: number): void;
+export declare function setRange1r_h(dstData: Float64Array, dstLen: number, dstStart: number, dstEnd: number, srcData: Float64Array, srcLen: number, srcStart: number, srcEnd: number): void;
+export declare function subarrayCopy1r(srcData: Float64Array, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function subarrayCopy1rRow(srcData: Float64Array, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function setCol2r_h(dstData: Float64Array, dstRows: number, dstLen: number, col: number, srcData: Float64Array, srcLen: number): void;

package/dist-lib/numbl-core/{jit/js → executors/jsJit/helpers}/jitHelpersTensor.d.ts

@@ -3,13 +3,9 @@
  * 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;
+import { RuntimeTensor } from "../../../runtime/types.js";
+import type { RuntimeComplexNumber } from "../../../runtime/types.js";
+export declare function makeTensor(data: Float64Array, imag: Float64Array | undefined, shape: number[]): RuntimeTensor;
 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;
@@ -18,6 +14,10 @@ export declare function tensorNeg(dest: unknown, a: RuntimeTensor): RuntimeTenso
 export declare function tDouble(v: unknown): unknown;
 export declare function tSum(v: unknown): unknown;
 export declare function vconcatGrow1r(base: unknown, v: number): RuntimeTensor;
+/** Unconditionally allocate a fresh wrapper + buffer for `t`. The caller
+ *  can mutate the result without affecting any other alias of the input.
+ *  Used by the JIT path on entry to a write-target hoisted alias; the
+ *  runtime indexed-store path uses the sweep instead. */
 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;

package/dist-lib/numbl-core/executors/jsJit/jitCall.d.ts

@@ -0,0 +1,59 @@
+/**
+ * User-function call — phased pipeline.
+ *
+ *   1. `classifyCall`  — cheap classification + cacheKey synthesis.
+ *      Type-infer args, prune `exact` for numeric scalars, type
+ *      widening using fn._lastJitArgTypes. Returns null on
+ *      type-unknown args or `~` placeholder params.
+ *
+ *   2. `lowerCall`     — IR lowering.
+ *
+ *   3. `generateCallJS` — JS codegen + `new Function`.
+ *
+ *   4. `runCallCompiled` — push call frame + cleanup scope, invoke
+ *      compiled fn, pop frame. Translates JitBailToInterpreter into
+ *      a transient bail.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import { type JitType } from "../../jitTypes.js";
+import { type LoweringResult } from "./lower/jitLower.js";
+/** Cheap pre-lowering data. */
+export interface CallClassification {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly cacheKey: string;
+    /**
+     * Effective JS parameter names for this specialization. Mirrors
+     * `fn.params` for non-varargin functions. For varargin functions,
+     * the trailing `varargin` is replaced with one synthetic name per
+     * variadic arg (`$va_0`, `$va_1`, …) so each variadic arg becomes
+     * a regular JS function parameter. argTypes is one-to-one with
+     * effectiveParams.
+     */
+    readonly effectiveParams: readonly string[];
+    /** Number of variadic args (0 when fn has no varargin). */
+    readonly nVarargin: number;
+}
+/** Lowered IR plus the classification it came from. */
+export interface CallLowered {
+    readonly classification: CallClassification;
+    readonly result: LoweringResult;
+}
+/** A compiled JS artifact ready to run. */
+export interface CallCompiled {
+    readonly fn: (...args: unknown[]) => unknown;
+    readonly source: string;
+}
+export declare function classifyCall(fn: FunctionDef, args: unknown[], nargout: number, prevArgTypes: readonly JitType[] | undefined): CallClassification | null;
+export declare function lowerCall(interp: Interpreter, classification: CallClassification): CallLowered | null;
+export declare function generateCallJS(interp: Interpreter, lowered: CallLowered): CallCompiled | null;
+export type CallRunOutcome = {
+    ok: true;
+    result: unknown;
+} | {
+    ok: false;
+    transient: boolean;
+};
+export declare function runCallCompiled(interp: Interpreter, fn: FunctionDef, compiled: CallCompiled, args: unknown[]): CallRunOutcome;

package/dist-lib/numbl-core/executors/jsJit/jitLoop.d.ts

@@ -0,0 +1,53 @@
+/**
+ * For/while loop body — phased pipeline.
+ *
+ *   1. `classifyLoop`   — analyze loop, gather typed env inputs,
+ *      live-out filter on outputs (using post-siblings), type
+ *      widening, cacheKey synthesis.
+ *
+ *   2. `lowerLoop`      — wrap as a synthetic `FunctionDef` and
+ *      lower via `lowerSyntheticFn`.
+ *
+ *   3. `generateLoopJS` — `generateSyntheticFnJS` + diagnostics.
+ *
+ *   4. `runLoopCompiled` — `runSyntheticFnAgainstEnv`.
+ *
+ * Shared with top-level via `shared.ts`. What's loop-specific is
+ * the analysis (For/While discrimination), the live-out filter
+ * against post-siblings, the cacheKey location (per loop AST
+ * span), and the `$loop_for` / `$loop_while` synthetic name.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { Stmt } from "../../parser/types.js";
+import type { JitType } from "../../jitTypes.js";
+import type { LoweringResult } from "./lower/jitLower.js";
+import { type SyntheticFnRunResult } from "./shared.js";
+export type LoopKind = "for" | "while";
+export interface LoopClassification {
+    readonly stmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly kind: LoopKind;
+    readonly inputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly outputs: readonly string[];
+    readonly hasReturn: boolean;
+    readonly cacheKey: string;
+}
+export interface LoopLowered {
+    readonly classification: LoopClassification;
+    readonly result: LoweringResult;
+}
+export interface LoopCompiled {
+    readonly fn: (...args: unknown[]) => unknown;
+    readonly source: string;
+}
+export type LoopRunResult = SyntheticFnRunResult;
+/** `postSiblings` / `postIdx` describe the stmt list this loop sits
+ *  in; used to compute the live-out filter on outputs. */
+export declare function classifyLoop(interp: Interpreter, stmt: Stmt & {
+    type: "For" | "While";
+}, postSiblings: readonly Stmt[], postIdx: number, prevInputTypes: readonly JitType[] | undefined): LoopClassification | null;
+export declare function lowerLoop(interp: Interpreter, classification: LoopClassification): LoopLowered | null;
+export declare function generateLoopJS(interp: Interpreter, lowered: LoopLowered): LoopCompiled | null;
+export declare function runLoopCompiled(interp: Interpreter, compiled: LoopCompiled, classification: LoopClassification): LoopRunResult;

package/dist-lib/numbl-core/executors/jsJit/jitTopLevel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Top-level script body — phased pipeline.
+ *
+ *   1. `classifyTopLevel`  — analyze script body, gather typed env
+ *      inputs, type widening, cacheKey synthesis.
+ *
+ *   2. `lowerTopLevel`     — wrap as a synthetic `FunctionDef` and
+ *      lower via `lowerSyntheticFn`.
+ *
+ *   3. `generateTopLevelJS` — `generateSyntheticFnJS` + diagnostics.
+ *
+ *   4. `runTopLevelCompiled` — `runSyntheticFnAgainstEnv`.
+ *
+ * The shared mechanics live in `shared.ts`; this module spells out
+ * what's actually top-level-specific (whole-script body, no
+ * post-loop liveness filter, `$top` synthetic name).
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { Stmt } from "../../parser/types.js";
+import type { JitType } from "../../jitTypes.js";
+import type { LoweringResult } from "./lower/jitLower.js";
+import { type SyntheticFnRunResult } from "./shared.js";
+export interface TopLevelClassification {
+    readonly stmts: readonly Stmt[];
+    readonly inputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly outputs: readonly string[];
+    readonly currentFile: string;
+    readonly hasReturn: boolean;
+    readonly cacheKey: string;
+}
+export interface TopLevelLowered {
+    readonly classification: TopLevelClassification;
+    readonly result: LoweringResult;
+}
+export interface TopLevelCompiled {
+    readonly fn: (...args: unknown[]) => unknown;
+    readonly source: string;
+}
+export type TopLevelRunResult = SyntheticFnRunResult;
+export declare function classifyTopLevel(interp: Interpreter, stmts: readonly Stmt[], prevInputTypes: readonly JitType[] | undefined): TopLevelClassification | null;
+export declare function lowerTopLevel(interp: Interpreter, classification: TopLevelClassification): TopLevelLowered | null;
+export declare function generateTopLevelJS(interp: Interpreter, lowered: TopLevelLowered): TopLevelCompiled | null;
+export declare function runTopLevelCompiled(interp: Interpreter, compiled: TopLevelCompiled, classification: TopLevelClassification): TopLevelRunResult;

package/dist-lib/numbl-core/executors/jsJit/loopExecutor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * js-jit-loop — JS codegen executor for the loop shape.
+ *
+ *   - `propose()` filters on `lowered.kind === "loop"`, applies
+ *     JIT-feasibility checks (hasReturn, IO+bail-risk).
+ *
+ *   - `compile()` calls `generateLoopJS`. Cached by the registry
+ *     under the classification's cacheKey.
+ *
+ *   - `run()` calls `runLoopCompiled`. JitBailToInterpreter →
+ *     transient bail; JitFuncHandleBailError → permanent bail.
+ */
+import type { Executor } from "../types.js";
+import { type LoopLowered, type LoopCompiled } from "./jitLoop.js";
+export declare const jsJitLoopExecutor: Executor<LoopLowered, LoopCompiled | null>;

package/dist-lib/numbl-core/{jit/jitLoopAnalysis.d.ts → executors/jsJit/lower/blockAnalysis.d.ts}

@@ -6,8 +6,8 @@
  * - referenced: variables read inside the loop
  * - hasReturn: whether the loop body contains a return statement
  */
-import type { Stmt } from "../parser/types.js";
-export interface LoopVarInfo {
+import type { Stmt } from "../../../parser/types.js";
+export interface BlockVarInfo {
     /** Variables referenced in the loop that must come from enclosing scope */
     inputs: string[];
     /** Variables assigned in the loop body (written back after JIT execution) */
@@ -18,7 +18,7 @@ export interface LoopVarInfo {
 /** Analyze a for loop statement for JIT compilation. */
 export declare function analyzeForLoop(stmt: Stmt & {
     type: "For";
-}): LoopVarInfo;
+}): BlockVarInfo;
 /**
  * Collect the names of all variables read in a sibling-tail starting at
  * `startIdx` of the given stmt list. Used by the loop JIT to filter the
@@ -30,8 +30,8 @@ export declare function collectReadsFromSiblings(stmts: Stmt[], startIdx: number
  * 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;
+export declare function analyzeTopLevel(stmts: Stmt[]): BlockVarInfo;
 /** Analyze a while loop statement for JIT compilation. */
 export declare function analyzeWhileLoop(stmt: Stmt & {
     type: "While";
-}): LoopVarInfo;
+}): BlockVarInfo;

package/dist-lib/numbl-core/{jit → executors/jsJit/lower}/jitBailSafety.d.ts

@@ -15,7 +15,7 @@
  * 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 { JitStmt } from "../../../jitTypes.js";
 import type { GeneratedFn } from "./jitLower.js";
 /**
  * Names of I/O-emitting builtins that the JIT is willing to lower as

package/dist-lib/numbl-core/{jit → executors/jsJit/lower}/jitLower.d.ts

@@ -9,9 +9,9 @@
  * 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 { 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.
@@ -111,6 +111,17 @@ export interface LowerCtx {
      *  the body reads the `nargout` identifier, since the JIT specializes per
      *  nargout already. */
     nargout?: number;
+    /** The nargin this specialization was requested with. Set whenever the
+     *  function is varargin (the call shape pins down nargin per spec).
+     *  Reads of bare `nargin` get inlined to this constant; `nargin > K`
+     *  guards then constant-fold so dead branches don't have to lower. */
+    nargin?: number;
+    /** Number of variadic args bound for this specialization (0 for
+     *  non-varargin callees). Used by `varargin{i}` lowering to redirect to
+     *  the synthetic `$va_*` param holding the i-th variadic arg. The
+     *  varargin lowering only needs the count — the synthetic name is
+     *  derived from the literal index alone. */
+    nVarargin?: number;
     generatedFns: Map<string, string>;
     generatedIRBodies: Map<string, GeneratedFn>;
     loweringInProgress: Set<string>;
@@ -119,4 +130,7 @@ export interface LowerCtx {
 }
 /** 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;
+export declare function lowerFunction(fn: FunctionDef, argTypes: JitType[], nargout: number, interp?: Interpreter, generatedFns?: Map<string, string>, loweringInProgress?: Set<string>, generatedIRBodies?: Map<string, GeneratedFn>, varargs?: {
+    effectiveParams: string[];
+    nVarargin: number;
+}): LoweringResult | null;

package/dist-lib/numbl-core/{jit → executors/jsJit/lower}/jitLowerExpr.d.ts

@@ -4,8 +4,9 @@
  * 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 { Expr } from "../../../parser/types.js";
+import type { Interpreter } from "../../../interpreter/interpreter.js";
+import { type JitType, type JitExpr } from "../../../jitTypes.js";
 import type { LowerCtx } from "./jitLower.js";
 export declare function lowerExpr(ctx: LowerCtx, expr: Expr): JitExpr | null;
 /**
@@ -25,3 +26,11 @@ export declare function tryLowerRangeSliceRead(ctx: LowerCtx, baseName: string,
 export declare function lowerIBuiltinCall(ctx: LowerCtx, expr: Expr & {
     type: "FuncCall";
 }): JitExpr | null;
+/**
+ * Multi-output variant of probeFuncHandleReturnType. Calls the handle
+ * with the requested nargout and returns one JitType per output. Bails
+ * (returns null) on the same conditions as the single-output probe
+ * (handle without jsFn, args we can't synthesize, output containing
+ * unknown), or when the result isn't an array of the expected length.
+ */
+export declare function probeFuncHandleMultiReturnTypes(interp: Interpreter, fnName: string, loweredArgs: JitExpr[], nargout: number): JitType[] | null;

package/dist-lib/numbl-core/{jit → executors/jsJit/lower}/jitLowerStmt.d.ts

@@ -3,7 +3,7 @@
  * 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 { 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 → executors/jsJit/lower}/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 JitExpr, 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;

package/dist-lib/numbl-core/{jit → executors/jsJit/lower}/scalarEmit.d.ts

@@ -11,8 +11,8 @@
  * Complex-scalar and tensor ops are *not* covered here — those remain
  * backend-specific (JS uses `$h.cAdd` etc.; C-JIT bails on complex).
  */
-import { BinaryOperation, UnaryOperation } from "../parser/types.js";
-import type { JitExpr } from "./jitTypes.js";
+import { BinaryOperation, UnaryOperation } from "../../../parser/types.js";
+import type { JitExpr } from "../../../jitTypes.js";
 export interface ScalarOpTarget {
     binAdd(l: string, r: string): string;
     binSub(l: string, r: string): string;

package/dist-lib/numbl-core/executors/jsJit/shared.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared helpers for the JS-JIT shape modules.
+ *
+ * The three shape modules (`jitTopLevel.ts`, `jitLoop.ts`,
+ * `jitCall.ts`) all do the same handful of things — type inference
+ * with `exact` pruning, progressive type widening, JS body assembly,
+ * `new Function` instantiation, env writeback. Those bits live here
+ * so the shape modules can stay focused on what's actually different
+ * between them (synthetic-fn shape, cacheKey scheme, run-time entry).
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { Runtime } from "../../runtime/runtime.js";
+import type { JitType } from "../../jitTypes.js";
+import { type LoweringResult } from "./lower/jitLower.js";
+import type { Stmt } from "../../parser/types.js";
+/** Names that look like variables but never resolve to env values
+ *  inside the JIT (constants, literals, the special `end` slot, the
+ *  imaginary unit). Skipped when collecting env inputs. */
+export declare const KNOWN_CONSTANTS: ReadonlySet<string>;
+/**
+ * Drop `exact` from a numeric scalar `JitType`. Numeric `exact` only
+ * survives unification when two consecutive specializations see the
+ * *same* literal — almost never the case for variables — so stripping
+ * up front means the first specialization's cacheKey already matches
+ * later calls.
+ */
+export declare function pruneArgType(t: JitType): JitType;
+/**
+ * Progressive type widening: in-place unify each entry of `types`
+ * with the corresponding entry of `prev`. No-op when shapes don't
+ * match (different arity → different specialization, no widening).
+ *
+ * Widening that would collapse a known type to `unknown` is rejected
+ * — keep this call's concrete type so a fresh, specific spec gets
+ * built. Without this, a 1st call with (number, …) followed by a 2nd
+ * call with (tensor, …) would unify the first arg to `unknown` and
+ * poison every subsequent specialization with the same arg shape
+ * (chunkie hits this with `fcurve(ta)` (scalar discovery) followed
+ * by `fcurve(ts)` (tensor)).
+ */
+export declare function widenAgainst(types: JitType[], prev: readonly JitType[] | undefined): void;
+/**
+ * Gather env inputs for the synthetic FunctionDef of a top-level or
+ * loop block. For each candidate name: skip known constants, skip
+ * names not in env (likely fn names), infer the JIT type, prune
+ * `exact`. Returns null if any candidate has an unknown type — that's
+ * a structural blocker for lowering.
+ */
+export declare function gatherTypedEnvInputs(interp: Interpreter, candidates: readonly string[]): {
+    inputs: string[];
+    inputTypes: JitType[];
+} | null;
+/**
+ * Build a `// File: …` + indented source-slice comment block for the
+ * code being JIT-compiled. Used by `--dump-js` so each emitted JS
+ * section is annotated with the .m source it came from. Falls back
+ * gracefully when the source isn't in `interp.fileSources`.
+ *
+ * `start` is rewound to the beginning of its line so the first line
+ * keeps its original indentation (Stmt spans start at the first
+ * non-whitespace char, which would otherwise leave the first line
+ * dedented relative to the rest).
+ */
+export declare function buildJitSourceComment(interp: Interpreter, file: string, start: number, end: number): string;
+/**
+ * Read the live env values for `inputs` in order. Used at run time
+ * to bind the compiled fn's parameters before invocation.
+ */
+export declare function gatherEnvValues(interp: Interpreter, inputs: readonly string[]): unknown[];
+/**
+ * Build the JS body for a synthetic FunctionDef: prepend each
+ * generated callee body (indented 2 spaces to nest inside the
+ * outer function), then append the main body.
+ */
+export declare function assembleJsBody(result: LoweringResult, mainBody: string): string;
+/**
+ * Wrap a JS body string in a `new Function(...)` and bind it to the
+ * runtime's helpers and `$rt`. Returns null when the body fails to
+ * parse (defensive — should not happen for IR that lowering accepted).
+ */
+export declare function instantiateJsFn(rt: Runtime, paramNames: readonly string[], jsBody: string): ((...args: unknown[]) => unknown) | null;
+/**
+ * Write a compiled fn's return value back into the interpreter env.
+ * The compiled fn returns either a single value (for one-output fns)
+ * or an array of values (for multi-output) — matching the JS-JIT
+ * convention used in the wrapper layer.
+ */
+export declare function writeBackOutputs(interp: Interpreter, outputs: readonly string[], result: unknown): void;
+/**
+ * Build a synthetic `FunctionDef` from (name, inputs, outputs, body)
+ * and lower it through `lowerFunction`. Returns null when lowering
+ * declines (constructs the JS-JIT IR doesn't model).
+ */
+export declare function lowerSyntheticFn(interp: Interpreter, name: string, inputs: readonly string[], inputTypes: readonly JitType[], outputs: readonly string[], body: Stmt[]): LoweringResult | null;
+/**
+ * Generate JS for a synthetic-fn lowered IR and instantiate it.
+ * Returns null when `new Function` throws (defensive — should not
+ * happen for IR that lowering accepted). Both top-level and loop
+ * codegen use this; the shape module then wraps the returned fn in
+ * its `*Compiled` shape and emits its own source/diagnostics.
+ */
+export declare function generateSyntheticFnJS(interp: Interpreter, result: LoweringResult, inputs: readonly string[], outputCount: number): {
+    fn: (...args: unknown[]) => unknown;
+    jsBody: string;
+} | null;
+/** Outcome of `runSyntheticFnAgainstEnv`. `transient` distinguishes
+ *  the recoverable JitBailToInterpreter case (cache preserved) from
+ *  the hard JitFuncHandleBailError case (cache invalidated). */
+export type SyntheticFnRunResult = {
+    ok: true;
+} | {
+    ok: false;
+    transient: boolean;
+};
+/**
+ * Gather input values from env, invoke the compiled fn, write back
+ * outputs. Translates JIT bails to a SyntheticFnRunResult. Used by
+ * both top-level and loop run phases.
+ */
+export declare function runSyntheticFnAgainstEnv(interp: Interpreter, fn: (...args: unknown[]) => unknown, inputs: readonly string[], outputs: readonly string[]): SyntheticFnRunResult;

package/dist-lib/numbl-core/executors/jsJit/topLevelExecutor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * js-jit-top-level — JS codegen executor for the top-level shape.
+ *
+ *   - `propose()` filters on `lowered.kind === "top-level"`, applies
+ *     JIT-feasibility checks (hasReturn, display mode + unsuppressed
+ *     assigns, IO+bail-risk).
+ *
+ *   - `compile()` calls `generateTopLevelJS`. Cached by the registry
+ *     under the classification's cacheKey.
+ *
+ *   - `run()` calls `runTopLevelCompiled`. JitBailToInterpreter →
+ *     transient bail; JitFuncHandleBailError → permanent bail.
+ *     `consumed` claims the entire script body.
+ */
+import type { Executor } from "../types.js";
+import { type TopLevelLowered, type TopLevelCompiled } from "./jitTopLevel.js";
+export declare const jsJitTopLevelExecutor: Executor<TopLevelLowered, TopLevelCompiled | null>;