numbl 0.2.0 → 0.3.3

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

@@ -0,0 +1,25 @@
+/**
+ * js-jit-call — JS codegen executor for the call shape.
+ *
+ * Lowering is the dispatcher's job. The call executor receives the
+ * lowered IR (with pre-computed feasibility flags) as the first arg
+ * to propose, decides whether to commit, and produces a compiled JS
+ * artifact on commit.
+ *
+ *   - `propose()` filters on `lowered.kind === "call"`, applies
+ *     IO+bail-risk feasibility check. Returns null to decline.
+ *
+ *   - `compile()` calls `generateCallJS` against the lowered IR.
+ *     Cached by the registry under the classification's cacheKey.
+ *
+ *   - `run()` calls `runCallCompiled`. JitBailToInterpreter →
+ *     transient bail.
+ */
+import type { Executor } from "../types.js";
+import { type CallLowered, type CallCompiled } from "./jitCall.js";
+interface JsJitCallData {
+    readonly lowered: CallLowered;
+    readonly args: readonly unknown[];
+}
+export declare const jsJitCallExecutor: Executor<JsJitCallData, CallCompiled | null>;
+export {};

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, fuse?: boolean, experimental?: 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): 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/executors/jsJit/codegen/jsMultiReduction.d.ts

@@ -0,0 +1,67 @@
+/**
+ * JS-side multi-reduction block emission.
+ *
+ * Detection + dispatch for scalar Assigns of the form
+ *
+ *   acc = <expr tree with >=2 reductions over a single tensor Var>
+ *
+ * On match, the JS codegen emits a block that runs a single-pass
+ * 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)
+ *   - a single tensor Var argument to every reduction
+ *   - all reductions read the same tensor name
+ *   - the tensor is real-typed
+ *   - at least two reductions in the RHS
+ *
+ * NaN semantics for max/min are matched to MATLAB omit-NaN behaviour:
+ * 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";
+type MultiReduceOp = "sum" | "prod" | "max" | "min" | "mean";
+export interface MultiReductionMatch {
+    /** The scalar Assign being emitted (target + original RHS). */
+    stmt: JitStmt & {
+        tag: "Assign";
+    };
+    /** The tensor variable name all reductions read. */
+    tensorName: string;
+    /** Distinct ops that actually appear, in first-occurrence order. Used
+     *  to size the kernel's output buffer and decide which accumulators
+     *  to declare on the JS fallback path. */
+    ops: MultiReduceOp[];
+    /** Every reduction Call node found in the RHS, paired with its op.
+     *  The JS emitter builds a substitution map from each Call to the
+     *  local that holds its result. */
+    sites: {
+        call: JitExpr & {
+            tag: "Call";
+        };
+        op: MultiReduceOp;
+    }[];
+}
+/** Try to match the multi-reduction pattern on a single statement. */
+export declare function tryMatchMultiReduction(stmt: JitStmt): MultiReductionMatch | null;
+/**
+ * Emit the multi-reduction block. Writes into `lines`.
+ *
+ * The block:
+ *   1. Aliases `<tensorName>.data` to a local and reads its length.
+ *   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): 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;