numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/executors/jit/typeAdapterC.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Type adapter for the mtoc2 C-JIT path.
+ *
+ *   - `compilerTypeToCDecl(ty)` returns the C type string that goes in the
+ *     koffi prototype for a value of that type, or `null` when the
+ *     type isn't supported across the FFI today.
+ *   - `registerTensorStruct(koffi)` registers `mtoc2_tensor_t`
+ *     with koffi (idempotent across calls — koffi's `struct` returns
+ *     the existing definition on re-registration of the same name).
+ *   - `buildCDeclaration(signature)` assembles the full koffi prototype
+ *     string from a `SpecCSignature`.
+ *
+ * Supported today:
+ *   - Scalar real numeric → `double`
+ *   - Scalar complex → `mtoc2_cscalar_t` (a `{double re; double im;}`
+ *     koffi struct). The emitted C signature uses `double _Complex` by
+ *     value, but on the SysV-x86-64 / AAPCS64 ABIs a 2-double struct
+ *     and `double _Complex` share the same by-value calling convention
+ *     (two SSE / SIMD registers, returned in xmm0:xmm1), so koffi
+ *     marshals the struct against the real `_Complex` function — koffi's
+ *     own prototype parser doesn't accept the `double _Complex` token.
+ *   - Scalar logical → `double` (shares the `double` ABI)
+ *   - Tensor (real or complex) → `mtoc2_tensor_t` (koffi struct)
+ *   - Void return → `void`
+ *
+ * Everything else (Struct / Class / Handle / String / Char / Cell)
+ * returns null so the C-JIT executor declines and JS-JIT picks up.
+ */
+import type { SpecCSignature, Type } from "../../jit/index.js";
+/** koffi's runtime-shaped api object. Loose typing because koffi
+ *  doesn't ship TS types for its declaration-string API. */
+interface Koffi {
+    struct(name: string, fields: Record<string, unknown>): any;
+    array(elemType: string, count: number, encoding?: string): any;
+    resolve(name: string): any | undefined;
+}
+/** Register the `mtoc2_tensor_t` struct with koffi. Idempotent — safe
+ *  to call from each compile() invocation; the second call short-
+ *  circuits.
+ *
+ *  Layout MUST match `mtoc2/src/builtins/runtime/tensor/tensor.h`:
+ *  ```
+ *  typedef struct {
+ *    double *real;
+ *    double *imag;
+ *    int  ndim;
+ *    long dims[JIT_MAX_NDIM];   // JIT_MAX_NDIM == 8
+ *  } mtoc2_tensor_t;
+ *  ```
+ *  Field order and padding match the C struct's natural alignment;
+ *  koffi handles the platform-specific alignment automatically when
+ *  asked for the same field types.
+ */
+export declare const JIT_MAX_NDIM = 8;
+export declare function registerTensorStruct(koffi: Koffi): void;
+/** Register the `mtoc2_cscalar_t` struct — `{double re; double im;}` —
+ *  used as the koffi stand-in for `double _Complex` scalar params and
+ *  returns (ABI-compatible by-value; see header). Idempotent. */
+export declare function registerCScalarStruct(koffi: Koffi): void;
+/** Map an mtoc2 `Type` to the C-type token used in the koffi
+ *  declaration string. Returns `null` for unsupported shapes. */
+export declare function compilerTypeToCDecl(ty: Type): string | null;
+/** Assemble the koffi prototype string for a `SpecCSignature`.
+ *
+ *  Convention (mirrors mtoc2's `fnRetType` + `fnParamList`):
+ *   - 0 outputs ⇒ `void <cName>(<params>)`
+ *   - 1 output  ⇒ `<retType> <cName>(<params>)`
+ *   - ≥2 outputs ⇒ `void <cName>(<params>, <outTy> *_mtoc2_o<i>...)`
+ *
+ *  Returns `null` if any param or output type fails the C-FFI
+ *  feasibility check — the executor must decline. */
+export declare function buildCDeclaration(signature: SpecCSignature): string | null;
+export {};

package/dist-lib/numbl-core/executors/jit/valueAdapter.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Adapter: numbl `RuntimeValue` ↔ mtoc2 emit-JS value shape.
+ *
+ * Numbl wraps tensors / chars / complex / structs in Refcounted
+ * classes (`RuntimeTensor`, `RuntimeChar`, `RuntimeComplexNumber`)
+ * keyed by a `kind:` discriminator. mtoc2's emitted JS uses plain
+ * objects keyed by `mtoc2Tag:` (no class wrapper, no refcount).
+ *
+ * **Pass-by-value at the boundary.** MATLAB function calls are
+ * pass-by-value; a JIT'd function that mutates its argument must
+ * not leak the mutation to the caller. mtoc2's whole-program
+ * codegen handles this by wrapping every call-site argument in
+ * `mtoc2_deep_clone(...)` — but the JIT executor is a *new* call
+ * site that mtoc2 doesn't know about, so we have to clone the
+ * tensor data buffer ourselves on the way in. On the way out, we
+ * take ownership of the returned buffer directly (mtoc2's spec
+ * always returns a freshly-owned tensor).
+ *
+ * The executor only invokes these adapters on values whose JitType
+ * was accepted by `jitTypeToCompilerType`. Unsupported value kinds
+ * arriving here are a programmer error — the type adapter should
+ * have caused `propose()` to decline earlier.
+ */
+import { type RuntimeValue } from "../../runtime/types.js";
+import type { JitType } from "../../jitTypes.js";
+/** numbl RuntimeValue → mtoc2 emit-JS value shape. Owned-typed
+ *  values (tensors) get their data buffer cloned so mtoc2's spec
+ *  body can mutate freely without leaking the change back through
+ *  numbl's caller-side env.
+ *
+ *  `targetType` is the JitType the spec was COMPILED for at this
+ *  parameter. Type-widening can reuse a complex specialization for a
+ *  later real/boolean scalar call (both keys collapse to
+ *  `complex_or_number`); the complex-typed body reads `.re`/`.im`, so a
+ *  bare JS number arriving there yields `undefined` → NaN. Box such a
+ *  scalar into `{re, im:0}` to mirror the C adapter (valueAdapterC),
+ *  which already boxes a real as a complex with `im=0`. */
+export declare function numblToJit(v: RuntimeValue, targetType?: JitType): unknown;
+/** mtoc2 emit-JS return value → numbl RuntimeValue. */
+export declare function jitToNumbl(v: unknown): RuntimeValue;
+/** True if `e` is the grow-bail sentinel thrown by the emitted JS
+ *  store helpers (`mtoc2_idx_*_grow_js` in `scalar_index.js`) — an
+ *  indexed store whose index exceeds the runtime extent, which would
+ *  grow the array (unsupported in the JIT). The JS executors recognize
+ *  it to surface a one-time warning; they bail on it (and on any other
+ *  runtime error) so the interpreter re-runs the scope with full
+ *  MATLAB grow semantics. */
+export declare function isGrowBail(e: unknown): boolean;

package/dist-lib/numbl-core/executors/jit/valueAdapterC.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Value adapter for the mtoc2 C-JIT path.
+ *
+ * Mirrors `valueAdapter.ts` (JS path) but converts numbl
+ * `RuntimeValue` to / from the C ABI mtoc2 expects across the koffi
+ * FFI boundary.
+ *
+ * **Copy budget** (see CLAUDE memo `feedback-no-silent-bails.md`
+ * and the user's "no extra copies" guideline):
+ *   - Scalars: zero copies; passed by value in koffi's args array.
+ *   - Tensors: one copy in, one copy out. mtoc2's call convention
+ *     requires the callee own its tensor params (it frees them at
+ *     scope exit), so the input data must be copied into a
+ *     `koffi.alloc`'d malloc-backed buffer that mtoc2 can free.
+ *     Reused / shared buffer would either (a) get freed under
+ *     numbl's still-live Float64Array, or (b) require extending
+ *     mtoc2 with borrowed-param semantics — deferred.
+ *
+ *   - Output tensors arrive as `mtoc2_tensor_t` with mtoc2_alloc'd
+ *     `real`/`imag` pointers. Caller (this adapter) copies the data
+ *     into a fresh `Float64Array`, then calls `free()` on the
+ *     pointers (`koffi`-bound `free` from libc) to release mtoc2's
+ *     buffers.
+ */
+import { RuntimeTensor, type RuntimeValue } from "../../runtime/types.js";
+import type { Type, NumericType } from "../../jit/index.js";
+import type { KoffiLib } from "./compileC.js";
+/** Loose koffi typing — same shape as in typeAdapterC.ts. */
+type KoffiAny = any;
+interface Koffi {
+    alloc(type: string, count: number): any;
+    decode(ptr: unknown, type: string, count: number): any;
+    encode(buf: any, type: string, value: any): void;
+    address(buf: any): any;
+}
+/** A function that frees the `mtoc2_alloc`'d buffer at the given
+ *  pointer. Resolved via koffi against libc's `free`. The .so we
+ *  dlopen pulls in libc anyway, so binding through the same lib is
+ *  zero-cost. */
+type FreeFn = (ptr: unknown) => void;
+interface MarshalCtx {
+    readonly koffi: Koffi;
+    readonly free: FreeFn;
+}
+/** Bind numbl's output sink into an emitted C `.so` so program output
+ *  (disp / fprintf / …) routes through `write` instead of libc stdout
+ *  — see `runtime/io/host_output.h`. Returns a `dispose()` the caller
+ *  MUST invoke after the C call returns (success or throw) to unbind
+ *  and free the koffi callback.
+ *
+ *  When the spec emitted no output, `mtoc2_set_host_write` is absent
+ *  from the `.so`; binding then no-ops (the C code never writes). */
+export declare function bindHostWrite(koffi: KoffiAny, lib: KoffiLib, write: (s: string) => void): {
+    dispose(): void;
+};
+/** Bind the emitted `.so`'s grow-bail flag accessors. A runtime
+ *  indexed-store grow (`v(k) = x`, k past the runtime extent) sets a
+ *  flag in the `.so` and `longjmp`s back to the host-entry function's
+ *  guard (see `grow_bail.h`), which returns normally. The host calls
+ *  `reset()` before each invocation and `bailed()` after; when
+ *  `bailed()` is true it discards the outputs and bails to the
+ *  interpreter (which has full MATLAB grow semantics).
+ *
+ *  When the spec emitted no scalar indexed store, `mtoc2_grow_bail_*`
+ *  are absent from the `.so`; binding then no-ops (`bailed()` is always
+ *  false — the code can't grow). */
+export declare function bindGrowBail(lib: KoffiLib): {
+    reset(): void;
+    bailed(): boolean;
+};
+/** Build a marshaling context from a koffi lib handle. The host
+ *  passes the lib it got from `compileAndLoadC`; we resolve `free`
+ *  against that same lib (libc symbols are reachable through any
+ *  dlopen'd .so). */
+export declare function makeCMarshalCtx(koffi: Koffi, lib: KoffiLib): MarshalCtx;
+/** Marshaled-input bookkeeping returned by `marshalInputs`. The
+ *  caller is responsible for invoking `release()` once the C call
+ *  has returned (success or throw). `release` does nothing for
+ *  scalar inputs (no allocation); for tensor inputs it's also a
+ *  no-op: mtoc2's spec body frees the buffers at its scope exit.
+ *  Kept as an explicit handle so a future change to lifetime
+ *  semantics has a single place to update. */
+export interface MarshaledInputs {
+    /** The values to splat into the koffi call, in order. */
+    readonly args: unknown[];
+    release(): void;
+}
+/** Convert a numbl `RuntimeValue` to the matching koffi-callable
+ *  arg for a parameter of mtoc2 `Type`. */
+export declare function marshalInputs(ctx: MarshalCtx, paramTypes: ReadonlyArray<Type>, values: ReadonlyArray<RuntimeValue | undefined>): MarshaledInputs | null;
+/** Convert a returned C tensor struct (decoded by koffi into a JS
+ *  object with `{real, imag, ndim, dims}`) to a numbl RuntimeTensor.
+ *  Reads `n = product(dims[0..ndim])` doubles from each lane, then
+ *  frees mtoc2's buffers.
+ *
+ *  For `Numeric` outputs that aren't multi-element (scalars), the
+ *  caller passes the bare value through `unmarshalScalarOutput`
+ *  instead — koffi unboxes them automatically.
+ */
+export declare function unmarshalTensorOutput(ctx: MarshalCtx, ret: KoffiAny, ty: NumericType): RuntimeTensor;
+/** Convert a bare scalar return value to a numbl RuntimeValue.
+ *
+ *  Real / logical scalars ride the `double` ABI, so koffi hands us a
+ *  JS number (logical coerces to `Boolean`). Complex scalars ride the
+ *  `mtoc2_cscalar_t` struct, so koffi hands us a `{re, im}` object,
+ *  which becomes a `RuntimeComplexNumber`. */
+export declare function unmarshalScalarOutput(v: unknown, ty: NumericType): RuntimeValue;
+export {};

package/dist-lib/numbl-core/executors/lowering.d.ts

@@ -1,31 +1,27 @@
 /**
  * Shared lowering pipeline.
  *
- * The dispatcher calls `tryLower` once per stmt-dispatch (and
- * `tryLowerCall` per function-call dispatch), before any executor is
+ * The dispatcher calls `tryLower` once per stmt-dispatch and
+ * `tryLowerCall` per function-call dispatch, before any executor is
  * asked to propose. The result — a `LoweredStmt` — is passed to every
  * executor's `propose()` as the first argument. `tryLower` returns
  * `null` for stmts with no specialized lowering shape; the dispatcher
- * falls through to its hardcoded `interp.execStmt` path in that case
- * (no executor needs to filter on "raw stmt").
+ * falls through to its hardcoded `interp.execStmt` path in that case.
  *
- * Lowering produces an IR; it does NOT make codegen-feasibility
- * decisions. "Can this be JS-JIT'd?" lives in the JS-JIT executor's
- * propose. Lowering's only "no" is structural: type-unknown inputs,
- * lowerFunction declined.
+ * Lowering here is *classification only*: it analyses inputs/outputs,
+ * infers types, and synthesizes a cacheKey. It does NOT make
+ * codegen-feasibility decisions — those live in the codegen executor's
+ * `propose`. This keeps the dispatcher free of dependencies on the
+ * JIT backend's internals (the in-tree compiler under
+ * `src/numbl-core/jit`).
  *
  * Shapes today:
- *   - `top-level` — script body (top-level scope, first stmt). Whole
- *     script lowered as a synthetic FunctionDef.
- *   - `loop`      — for/while loop stmt. Loop lowered as a synthetic
- *     FunctionDef that wraps just that stmt.
- *   - `call`      — user-function call. Lowered via `tryLowerCall`
+ *   - `top-level` — script body (top-level scope). Whole script
+ *     analysed as a synthetic FunctionDef.
+ *   - `call`      — user-function call. Produced by `tryLowerCall`
  *     from `dispatchCall`.
- *
- * Top-level and loop share the same underlying mechanics
- * (`shared.ts`); they're modeled as separate kinds because they have
- * distinct trigger conditions (script-root vs. control-flow stmt) and
- * runtime semantics (claim entire stmt list vs. consume one stmt).
+ *   - `synth`     — a `Synth` AST stmt produced by a registered AST
+ *     transformer (no further analysis here).
  *
  * Lowerings are cached by (head Stmt or FunctionDef, classification
  * cacheKey).
@@ -33,78 +29,35 @@
 import type { Stmt } from "../parser/types.js";
 import type { FunctionDef } from "../interpreter/types.js";
 import type { Interpreter } from "../interpreter/interpreter.js";
-import type { DispatchContext } from "./context.js";
-import { type TopLevelClassification, type TopLevelLowered } from "./jsJit/jitTopLevel.js";
-import { type LoopClassification, type LoopLowered } from "./jsJit/jitLoop.js";
-import { type CallClassification, type CallLowered } from "./jsJit/jitCall.js";
-import { type FuseClassification } from "./cJit/fuseAnalyze.js";
+import { type TopLevelClassification, type CallClassification, type LoopClassification } from "./classification.js";
 /** What `propose()` receives — a discriminated union of the
  *  specialized shapes the dispatcher knows how to lower. Stmts with
  *  no specialized shape don't reach `propose()` at all; the dispatcher
  *  falls through to its hardcoded interpreter path. */
-export type LoweredStmt = TopLevelLoweredStmt | LoopLoweredStmt | CallLoweredStmt | FuseLoweredStmt | SynthLoweredStmt;
-/** Top-level shape: script body lowered to JS-JIT IR. */
+export type LoweredStmt = TopLevelLoweredStmt | LoopLoweredStmt | CallLoweredStmt | SynthLoweredStmt;
+/** Top-level shape: script body analysed for whole-scope codegen. */
 export interface TopLevelLoweredStmt {
     readonly kind: "top-level";
     readonly classification: TopLevelClassification;
-    readonly lowered: TopLevelLowered;
-    readonly flags: TopLevelFlags;
-}
-/** Pre-computed feasibility flags for top-level codegen executors. */
-export interface TopLevelFlags {
-    /** Body contains a `return` statement. JIT cannot model
-     *  early-return from the synthetic top-level fn. */
-    readonly hasReturn: boolean;
-    /** Source body contains an unsuppressed assign / multiassign /
-     *  non-void-call ExprStmt. In display-mode the JIT must bail —
-     *  it has no emit for auto-display. */
-    readonly hasUnsuppressedAssign: boolean;
-    /** Lowered IR contains an I/O builtin (disp, fprintf, ...). */
-    readonly hasIO: boolean;
-    /** Lowered IR contains a possibly-bailing operation. Combined
-     *  with hasIO, signals a body that mustn't be retried after a
-     *  partial run (already-emitted output would duplicate). */
-    readonly hasBailRisk: boolean;
 }
-/** Loop shape: a For/While stmt lowered to JS-JIT IR. */
+/** Loop shape: a single For/While stmt analysed for loop codegen.
+ *  Produced by `tryLower` when the head stmt is a For/While. */
 export interface LoopLoweredStmt {
     readonly kind: "loop";
     readonly classification: LoopClassification;
-    readonly lowered: LoopLowered;
-    readonly flags: LoopFlags;
-}
-/** Pre-computed feasibility flags for loop codegen executors. */
-export interface LoopFlags {
-    readonly hasReturn: boolean;
-    readonly hasIO: boolean;
-    readonly hasBailRisk: boolean;
 }
-/** Call shape: a user-function call lowered to JS-JIT IR. Produced
- *  by `tryLowerCall`, not `tryLower` — function calls fire from
- *  expression evaluation, not from the stmt loop. */
+/** Call shape: a user-function call analysed for call codegen.
+ *  Produced by `tryLowerCall`, not `tryLower` — function calls fire
+ *  from expression evaluation, not from the stmt loop. */
 export interface CallLoweredStmt {
     readonly kind: "call";
     readonly classification: CallClassification;
-    readonly lowered: CallLowered;
-    readonly flags: CallFlags;
     /** Runtime arg values. Carried alongside the classification
      *  because the executor needs them at runCall time; unlike
      *  stmt-shape executors, the call executor can't re-fetch them
      *  from env. */
     readonly args: readonly unknown[];
 }
-/** Pre-computed feasibility flags for call codegen executors. */
-export interface CallFlags {
-    readonly hasIO: boolean;
-    readonly hasBailRisk: boolean;
-}
-/** Fuse shape: a single AST `Assign` whose RHS is a fusable
- *  element-wise expression tree. Produced by `analyzeFuse` over the
- *  raw AST stmt. */
-export interface FuseLoweredStmt {
-    readonly kind: "fuse";
-    readonly classification: FuseClassification;
-}
 /** Synth shape: a `Synth` AST stmt produced by a registered AST
  *  transformer. The matching executor reads `data` (analysis the
  *  transformer pre-computed) and the `tag` discriminates among
@@ -140,27 +93,28 @@ export declare class LoweringCache {
     setLastInputTypes(owner: object, slot: string, types: readonly import("../jitTypes.js").JitType[]): void;
 }
 /**
- * Try to lower the stmt at `siblings[i]` based on current runtime
- * info. Returns a `LoweredStmt` for stmts that match a specialized
- * shape, or `null` for stmts with no shape — the dispatcher falls
- * through to its hardcoded interpreter path in that case.
+ * Try to lower the stmt at `siblings[i]`. Returns a `LoweredStmt` for
+ * stmts that match a specialized shape, or `null` for stmts with no
+ * shape — the dispatcher falls through to its hardcoded interpreter
+ * path in that case.
  *
  * Whole-scope shapes (`top-level`) are NOT produced here — they're
  * lowered separately via `tryLowerTopLevel` and dispatched through
  * `Registry.tryRunWholeScope` before the per-stmt loop runs.
  */
-export declare function tryLower(siblings: readonly Stmt[], i: number, ctx: DispatchContext, cache: LoweringCache): LoweredStmt | null;
+export declare function tryLower(siblings: readonly Stmt[], i: number, interp: Interpreter, cache: LoweringCache): LoweredStmt | null;
 /**
  * Lower a script body as a whole-scope unit. Called by the registry
  * before the per-stmt dispatch loop runs; returns a TopLevelLoweredStmt
- * for whole-scope executors to consider, or null when the lowering
+ * for whole-scope executors to consider, or null when the classification
  * declines.
  */
 export declare function tryLowerTopLevel(interp: Interpreter, siblings: readonly Stmt[], cache: LoweringCache): TopLevelLoweredStmt | null;
 /**
  * Try to lower a user-function call. Always returns a
  * `CallLoweredStmt` when classification succeeds; null when the
- * cheap classify declines (`~` params, type-unknown args).
+ * classify declines (`~` params, type-unknown args, varargin
+ * arity mismatch).
  */
-export declare function tryLowerCall(fn: FunctionDef, args: unknown[], nargout: number, interp: Interpreter, cache: LoweringCache): CallLoweredStmt | null;
+export declare function tryLowerCall(fn: FunctionDef, args: unknown[], nargout: number, cache: LoweringCache): CallLoweredStmt | null;
 export {};

package/dist-lib/numbl-core/executors/plugins.d.ts

@@ -8,32 +8,25 @@
  * The AST interpreter is the dispatcher's hardcoded last-resort
  * fallback (see `Registry.dispatch`); it doesn't need to be a
  * registered executor.
- *
- * The C-JIT (e3) executors are registered via an injected callback
- * (`setCJitRegistrar`). A Node-only entry point (`cli.ts`) imports
- * `executors/cJit/register.ts`, which calls `setCJitRegistrar` at
- * load time. The browser worker never imports that module, so the
- * cJit subtree (which pulls in `node:fs`/`node:os`/`node:child_process`
- * via `compile.ts`) stays out of the web bundle.
  */
 import type { Registry } from "./registry.js";
 /** Optimization mode label.
  *
- *   - `"0"`  — pure AST interpreter, no executors registered.
- *   - `"1"`  — JS-JIT suite (top-level / loop / call).
- *   - `"e3"` — C-JIT scalar-loop only. Targets compute-bound scalar
- *     loops by compiling the loop body to C and loading via koffi.
- *     Does NOT register the JS-JIT suite — the C-JIT loop executor
- *     either matches (and runs in C) or falls back to the AST
- *     interpreter. */
-export type OptLevel = "0" | "1" | "e3";
+ *   - `"0"` — pure AST interpreter, no executors registered.
+ *   - `"1"` — JS-JIT: all three shapes (top-level, loop,
+ *     call) emit JS via `compileSpec`. JIT declines
+ *     (`UnsupportedConstruct` / `JitTypeError`) fall back to the
+ *     interpreter cleanly.
+ *   - `"2"` — C-JIT-first with JS-JIT fallback. Both backends
+ *     register their executors; the dispatcher picks based on cost,
+ *     so the C path wins where it applies (scalar / tensor numeric
+ *     types with a wired `nativeBridge`) and the JS path picks up
+ *     the slack (struct / class / handle / no-cc-available).
+ *     Requires `cc` on the PATH and `koffi` installed; without
+ *     either, the C executors decline and `"2"` collapses to the
+ *     same behaviour as `"1"`. */
+export type OptLevel = "0" | "1" | "2";
 export declare const OPT_LEVELS: readonly OptLevel[];
 export declare function isOptLevel(s: string): s is OptLevel;
-type CJitRegistrar = (registry: Registry) => void;
-/** Wire up the C-JIT (e3) executors. Called from a Node-only entry
- *  point at startup so the browser bundle never reaches the cJit
- *  module graph. */
-export declare function setCJitRegistrar(fn: CJitRegistrar): void;
 /** Register the executors for a given optimization mode. */
 export declare function registerExecutorsForOpt(registry: Registry, opt: OptLevel): void;
-export {};

package/dist-lib/numbl-core/helpers/reduction-helpers.d.ts

@@ -13,7 +13,10 @@ export declare function forEachSlice(shape: number[], dim: number, callback: (ou
     resultShape: number[];
     totalElems: number;
 } | null;
-/** Return 1-based dim to reduce along (first non-singleton), or 0 for "reduce to scalar". */
+/** Return 1-based dim to reduce along (first dim whose size != 1), or 0 for
+ *  "reduce to scalar". A size-0 dimension counts as non-singleton (MATLAB
+ *  reduces along it), so `sum(zeros(0,3))` is `[0 0 0]` not a scalar — the
+ *  previous `d > 1` test wrongly treated a size-0 dim as singleton. */
 export declare function firstReduceDim(shape: number[]): number;
 /** Return a deep copy of a tensor (data + shape + optional imag). */
 export declare function copyTensor(v: RuntimeTensor): RuntimeValue;

package/dist-lib/numbl-core/interpreter/builtins/index.d.ts

@@ -31,6 +31,6 @@ import "./special-math.js";
 import "./misc.js";
 import "./dictionary.js";
 import "./help-text.js";
-export { getIBuiltin, getIBuiltinHelp, getIBuiltinNargin, getAllIBuiltinNames, buildIBuiltinHelpers, setDynamicRegisterHook, registerBuiltinHelp, inferJitType, } from "./types.js";
+export { getIBuiltin, getIBuiltinHelp, getIBuiltinNargin, getAllIBuiltinNames, registerBuiltinHelp, inferJitType, } from "./types.js";
 export type { IBuiltin, IBuiltinResolution, BuiltinHelp } from "./types.js";
 export { resetAppdataStore, convertJsonValue } from "./misc.js";

package/dist-lib/numbl-core/interpreter/builtins/types.d.ts

@@ -17,13 +17,9 @@ export interface IBuiltin {
     help?: BuiltinHelp;
     /** Given input JIT types + nargout, return output types and a specialized apply, or null. */
     resolve: (argTypes: JitType[], nargout: number) => IBuiltinResolution | null;
-    /** Optional fast-path JS code emission for JIT. Return null to fall back to $h.ib_<name>. */
-    jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
 }
 export declare function getIBuiltin(name: string): IBuiltin | undefined;
 export declare function registerIBuiltin(b: IBuiltin): void;
-/** Set a callback for dynamic IBuiltin registration (called by jitHelpers setup). */
-export declare function setDynamicRegisterHook(hook: ((b: IBuiltin) => void) | null): void;
 /** Register a dynamic IBuiltin (e.g. .js user functions), replacing any
  *  existing entry with the same name without error. */
 export declare function registerDynamicIBuiltin(b: IBuiltin): void;
@@ -35,10 +31,6 @@ export declare function registerBuiltinHelp(name: string, help: BuiltinHelp): vo
  *  Tries resolve with 1, 2, 3 number-type args to find the accepted count. */
 export declare function getIBuiltinNargin(name: string): number | undefined;
 export declare function inferJitType(value: unknown): JitType;
-/** Build the ib_* entries for the jitHelpers object.
- *  The returned object also has _profileEnter/_profileLeave hooks (no-ops by default)
- *  that the runtime replaces when profiling is enabled. */
-export declare function buildIBuiltinHelpers(): Record<string, any>;
 export declare function mkc(re: number, im: number): number | RuntimeComplexNumber;
 export declare function makeTensor(data: Float64Array, imag: Float64Array | undefined, shape: number[]): RuntimeTensor;
 /** Type rule requiring two scalar numbers */
@@ -66,7 +58,6 @@ export declare function defineBuiltin(opts: {
     name: string;
     help?: BuiltinHelp;
     cases: BuiltinCase[];
-    jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
 }): void;
 type NumberJitType = Extract<JitType, {
     kind: "number";
@@ -104,13 +95,4 @@ export declare function unaryElemwiseCases(spec: UnaryElemwiseSpec, name: string
 export declare function unaryRealResultCases(realFn: (x: number) => number, complexFn: (re: number, im: number) => number, name: string): BuiltinCase[];
 /** Build cases for numeric predicates (isnan, isinf, isfinite) that return logical. */
 export declare function predicateCases(scalarTest: (x: number) => boolean, complexTest: (re: number, im: number) => boolean, tensorTest: (x: number) => boolean, tensorComplexTest: (re: number, im: number) => boolean, name: string): BuiltinCase[];
-/** Fast-path emitter for unary Math.* functions.
- *  Emits Math.fn(x) for scalar numbers, $h.tHelper(dest, x) for real
- *  tensors. `getDest` is a lazy callback returning the dest local: either
- *  a mangled LHS (top-level Assign) or a fresh scratch (inner tensor
- *  sub-expression). It's only invoked when the tensor fast path is
- *  actually taken, so scalar / rejected paths don't burn a scratch. */
-export declare function unaryMathJitEmit(mathFn: string, tensorHelper: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
-/** Fast-path emitter for binary Math.* functions on two scalar numbers. */
-export declare function binaryMathJitEmit(mathFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
 export {};

package/dist-lib/numbl-core/interpreter/interpreter.d.ts

@@ -40,6 +40,23 @@ export declare class Interpreter {
         dimIndex: number;
         numIndices: number;
     }>;
+    /** @internal Number of enclosing `for` / `while` loop bodies the
+     *  interpreter is currently inside. Bumped on body entry, decremented
+     *  on exit. Read by the executor registry's `propose()` to gate JIT
+     *  attempts: when `loopDepth > 0`, the interpreter is iterating a
+     *  hot loop and per-call JIT lookup overhead / spec-cache thrashing
+     *  is a net loss. Once mtoc2 successfully JITs an outer call, the
+     *  nested loops execute inside the compiled artifact and the
+     *  interpreter never sees them, so this gate only fires on calls
+     *  that genuinely happen at the interpreter level inside a loop. */
+    loopDepth: number;
+    /** @internal Number of enclosing conditional blocks (`if` / `switch` /
+     *  `try`) whose bodies the interpreter is currently executing. Used by
+     *  the loop classifier: when a loop is dispatched with `condBlockDepth >
+     *  0` (or `loopDepth > 0`), its sibling list is a nested block, so the
+     *  post-loop liveness scan can't see reads after the enclosing block —
+     *  the classifier must then keep every loop-assigned name live-out. */
+    condBlockDepth: number;
     /** @internal */
     functionDefCache: Map<string, FunctionDef>;
     /** @internal Pre-built line break tables for offset→line lookup per file. */
@@ -50,29 +67,27 @@ export declare class Interpreter {
     compileInProgress: Set<string>;
     /**
      * Optimization mode:
-     *   "0"  — pure AST interpreter, no JIT.
-     *   "1"  — JS-JIT (default): type-specialize hot functions/loops to JS
-     *          via `new Function()`.
-     *   "e3" — C-JIT scalar-loop only (Node only). No JS-JIT suite is
-     *          registered alongside; loops either match the C-JIT
-     *          executor or fall back to the AST interpreter.
+     *   "0" — pure AST interpreter, no JIT.
+     *   "1" — JS-JIT (default): top-level + call shapes get
+     *         type-specialized JS via the JIT's `compileSpec`.
+     *   "2" — C-JIT: scalar/tensor kernels via `compileSpecC` + koffi.
      */
     optimization: import("../executors/plugins.js").OptLevel;
-    /** Callback for JIT compilation logging (JS codegen). */
-    onJitCompile?: (description: string, jsCode: string) => void;
-    /** Callback for C-JIT compilation logging (C codegen). Invoked once
-     *  per cache miss, before the C source is compiled. */
-    onCJitCompile?: (description: string, cCode: string) => void;
-    /** Bridge for loading native shared libraries — used by the C-JIT
-     *  loop executor (`--opt e3`) to dlopen freshly-compiled `.so`
-     *  artifacts via koffi. Undefined in browser contexts; the executor
-     *  declines when undefined. */
+    /** Callback for JIT compilation logging. `lang` distinguishes the
+     *  emitted source: `"js"` for the JS-JIT backend, `"c"` for the
+     *  C-JIT backend (both can fire in a single `--opt 2` run). */
+    onJitCompile?: (description: string, code: string, lang: "js" | "c") => void;
+    /** Called when a JIT-compiled unit bails back to the interpreter at
+     *  RUNTIME (as opposed to declining at compile time). Today the sole
+     *  trigger is an indexed-store array growth that's only detectable at
+     *  runtime — the JIT can't model the grown shape, so it bails and the
+     *  interpreter re-runs the whole scope with full MATLAB semantics.
+     *  Surfaced as a warning (the CLI routes it to stderr); a compile-time
+     *  decline stays silent (it's the normal "not JIT-able" path). */
+    onJitBail?: (message: string) => void;
+    /** Bridge for loading native shared libraries. Undefined in browser
+     *  contexts. */
     nativeBridge?: import("../workspace/types.js").NativeBridge;
-    /** Compile c-jit kernels with `-ffast-math`. On by default for
-     *  libmvec-vectorized transcendentals (~30% speedup on element-wise
-     *  tensor benchmarks); opt out via the CLI's `--no-fast-math` flag
-     *  to keep reductions bitwise-deterministic. */
-    fastMath: boolean;
     /** Telemetry: invoked after a registered executor's `run()` succeeds.
      *  Used to track which optimizers fire in a session. The kind is the
      *  LoweredStmt kind the executor handled ("top-level", "loop", "call",
@@ -98,6 +113,7 @@ export declare class Interpreter {
     getVariableValues(): Record<string, RuntimeValue>;
     execStmt: (stmt: Stmt) => ControlSignal | null;
     execStmts: (stmts: Stmt[]) => ControlSignal | null;
+    execBlockStmts: (stmts: Stmt[]) => ControlSignal | null;
     evalExpr: (expr: Expr) => unknown;
     evalExprNargout: (expr: Expr, nargout: number) => unknown;
     evalBinary: (expr: Extract<Expr, {
@@ -173,5 +189,5 @@ export declare class Interpreter {
     };
     isHandleClass: (classInfo: ClassInfo) => boolean;
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
-    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => unknown[];
+    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => void;
 }

package/dist-lib/numbl-core/interpreter/interpreterExec.d.ts

@@ -8,6 +8,12 @@ import { type ControlSignal } from "./types.js";
 import type { Interpreter } from "./interpreter.js";
 export declare function execStmt(this: Interpreter, stmt: Stmt): ControlSignal | null;
 export declare function execStmts(this: Interpreter, stmts: Stmt[]): ControlSignal | null;
+/** Execute a conditional-block body (`if` / `switch` / `try`), tracking
+ *  `condBlockDepth` so a loop dispatched inside knows its sibling list is
+ *  a nested block — the loop classifier then keeps every loop-assigned
+ *  name live-out (the post-loop liveness scan can't see reads after the
+ *  enclosing block). */
+export declare function execBlockStmts(this: Interpreter, stmts: Stmt[]): ControlSignal | null;
 export declare function evalExpr(this: Interpreter, expr: Expr): unknown;
 export declare function evalExprNargout(this: Interpreter, expr: Expr, nargout: number): unknown;
 export declare function evalArgs(this: Interpreter, argExprs: Expr[]): unknown[];

package/dist-lib/numbl-core/interpreter/interpreterFunctions.d.ts

@@ -41,4 +41,16 @@ export declare function collectClassProperties(this: Interpreter, classInfo: Cla
 };
 export declare function isHandleClass(this: Interpreter, classInfo: ClassInfo): boolean;
 export declare function evalInLocalScope(this: Interpreter, codeArg: unknown, fileName?: string): unknown;
-export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): unknown[];
+/**
+ * Apply `arguments`-block defaults and build name-value struct parameters,
+ * binding the results into the *current* function environment.
+ *
+ * Must be called with `this.env` already set to the function scope and the
+ * caller-supplied positional arguments already bound to their parameters.
+ * Default expressions are evaluated in that scope so they can reference
+ * earlier arguments (e.g. `mergeIdx = surfaceop.defaultIdx(dom)`), matching
+ * MATLAB. Entries are matched to parameters by name via `fn.params`, which
+ * also handles the constructor case where the output variable is prepended
+ * to `params` (shifting argument positions by one).
+ */
+export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): void;