numbl 0.3.0 → 0.4.0

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

@@ -0,0 +1,103 @@
+/**
+ * Executor registry — core types.
+ *
+ * See docs/developer_reference/executors.md for the design overview.
+ *
+ * The interpreter delegates each statement (or run of statements) — and
+ * each user-function call — to a registry of Executors. Each executor
+ * implements one strategy (interpreter, JS-JIT, C-kernel, ...). On each
+ * dispatch, every executor may submit a Proposal; the dispatcher picks
+ * the lowest-cost. Stmt-shape and call-shape work share the same
+ * Executor interface — they're discriminated via the lowered statement
+ * passed to propose().
+ */
+import type { DispatchContext } from "./context.js";
+import type { LoweredStmt } from "./lowering.js";
+/** Estimated cost of using this executor for the proposed work.
+ *  Numbers can be very rough at first; the dispatcher's policy is
+ *  refined separately from executors. */
+export interface CostEstimate {
+    /** One-time compile cost on cache miss. */
+    compileMs: number;
+    /** Per-call dispatch overhead (marshaling, frame setup, ...). */
+    perCallNs: number;
+    /** Estimated work done by the compiled artifact for the proposed
+     *  input sizes. */
+    runNs: number;
+}
+/** Reason a `run` invocation could not complete. The dispatcher
+ *  invalidates the cache entry and tries the next-best candidate. */
+export interface BailReason {
+    message: string;
+    cause?: unknown;
+}
+export type RunResult = 
+/** Stmt-shape success — handled the head stmt. Registered executors
+ *  don't produce control signals (break/continue/return); only the
+ *  hardcoded interpreter fallback in `Registry.dispatch` does.
+ *  The dispatcher always advances by exactly one stmt on success. */
+{
+    ok: true;
+}
+/** Call-shape success — used by executors that handle a
+ *  CallLoweredStmt. The dispatcher's call entry point
+ *  (`dispatchCall`) returns this `result` to the caller. */
+ | {
+    result: unknown;
+} | {
+    bail: BailReason;
+    /** When true, the bail is not cached: future dispatches re-enter
+     *  the executor as if cache had never been touched. Use for
+     *  shim/wrapper executors whose internal classify logic must
+     *  re-run on every call (e.g., because the wrapped layer caches
+     *  on its own keying scheme). Default false. */
+    transient?: boolean;
+};
+/** An executor's bid to handle the current dispatch. The dispatcher
+ *  picks the lowest-cost proposal; the executor's own `data` flows
+ *  through to compile() and run() unchanged. */
+export interface Proposal<D> {
+    /** Opaque per-executor data; passed to compile() and run(). */
+    data: D;
+    cost: CostEstimate;
+    /** Whether this specific proposal's compiled artifact may fail an
+     *  invariant mid-execution (and thus need re-running by a fallback).
+     *  The dispatcher filters bail-risk proposals out of contexts marked
+     *  `requireNoBail`. Per-proposal because a single executor may
+     *  produce both bail-risky and bail-safe proposals depending on the
+     *  inputs it sees. */
+    bailRisk: boolean;
+}
+export interface Executor<D = unknown, C = unknown> {
+    /** Stable identifier for logging, cache keys, and test selection. */
+    readonly name: string;
+    /** Submit a bid to handle this stmt. Runs on every dispatch — must
+     *  be cheap.
+     *
+     *  Receives the lowered statement produced by the dispatcher's
+     *  pre-propose lowering pass. The `kind` field discriminates: a
+     *  specialized shape (e.g. `"top-level"`) carries a lowered IR
+     *  plus pre-computed feasibility flags; the fallback `"stmt"` kind
+     *  carries the raw AST stmt for executors that classify from the
+     *  AST directly.
+     *
+     *  Codegen-feasibility decisions (display mode, IO+bail-risk, etc.)
+     *  belong here — the lowering pipeline produces an IR; the
+     *  executor decides whether to commit. For lookahead across
+     *  multiple stmts, use `ctx.peekSibling(offset)` or `ctx.siblings`.
+     *
+     *  Returns null to decline. */
+    propose(lowered: LoweredStmt, ctx: DispatchContext): Proposal<D> | null;
+    /** Stable cache key projected from the proposal data. Drops
+     *  volatile bits (e.g., exact scalar values; tensor shape if
+     *  codegen is shape-agnostic) so unrelated runs of the same code
+     *  reuse compiled artifacts. */
+    cacheKey(data: D): string;
+    /** Compile to a runnable artifact. Called only on cache miss.
+     *  Cached under (executor, headStmt, cacheKey). */
+    compile(data: D, ctx: DispatchContext): C;
+    /** Execute. Returns the number of consumed sibling stmts on success,
+     *  or a Bail signalling the cache entry should be invalidated and
+     *  the next-best candidate tried. */
+    run(compiled: C, data: D, ctx: DispatchContext): RunResult;
+}

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

@@ -43,6 +43,13 @@ export type ResolvedTarget = {
     kind: "jsUserFunction";
     name: string;
     argTypes: ItemType[];
+} | {
+    /** mtoc2-only user function (.mtoc2.js). Numbl's interpreter
+     *  rejects calls to this kind; mtoc2's loader picks up the source
+     *  from the workspace registry and evaluates it. */
+    kind: "mtoc2UserFunction";
+    name: string;
+    argTypes: ItemType[];
 } | {
     kind: "workspaceClassConstructor";
     className: string;

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

@@ -2,10 +2,9 @@
  * Helpers for writing builtin check functions.
  * These make check implementations shorter and easier to read.
  */
-import { type FloatXArrayType } from "../runtime/types.js";
 import { RTV, RuntimeValue } from "../runtime/index.js";
 /** Ensure data is Float64Array (needed by LAPACK bridges). */
-export declare function toF64(data: FloatXArrayType): Float64Array;
+export declare function toF64(data: Float64Array): Float64Array;
 /**
  * Extract and normalize a string argument at runtime.
  * Strips surrounding quotes and lowercases the result.
@@ -31,18 +30,18 @@ export declare function buildEigenvectorMatrix(packedV: Float64Array, wi: Float6
  * Build a tensor, attaching the imaginary part only when it contains non-zero values.
  * Replaces the repeated `hasComplex ? RTV.tensor(re, shape, im) : RTV.tensor(re, shape)` pattern.
  */
-export declare function maybeComplexTensor(re: FloatXArrayType | Float64Array, shape: number[], im: FloatXArrayType | Float64Array | undefined): ReturnType<typeof RTV.tensor>;
+export declare function maybeComplexTensor(re: Float64Array | Float64Array, shape: number[], im: Float64Array | Float64Array | undefined): ReturnType<typeof RTV.tensor>;
 /**
  * Build a diagonal matrix from a vector of values (column-major).
  * For square matrices pass just n; for rectangular pass [rows, cols].
  * Optionally includes an imaginary diagonal.
  */
-export declare function buildDiagMatrix(realVals: Float64Array | FloatXArrayType, imagVals: Float64Array | FloatXArrayType | undefined, size: number | [number, number]): ReturnType<typeof RTV.tensor>;
+export declare function buildDiagMatrix(realVals: Float64Array | Float64Array, imagVals: Float64Array | Float64Array | undefined, size: number | [number, number]): ReturnType<typeof RTV.tensor>;
 /**
  * In-place Gauss-Jordan elimination with partial pivoting on a column-major
  * augmented matrix [A | B] of size `rows × totalCols`.
  */
-export declare function gaussJordanEliminate(aug: FloatXArrayType, rows: number, totalCols: number): void;
+export declare function gaussJordanEliminate(aug: Float64Array, rows: number, totalCols: number): void;
 /**
  * Call a registered builtin from within another builtin's apply().
  * Convenience wrapper that includes the caller name in error messages.

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

@@ -9,18 +9,17 @@
  * Both the native LAPACK addon and the ts-lapack TypeScript fallback are
  * supported; the native addon is preferred when available.
  */
-import { FloatXArrayType } from "../runtime/types.js";
 /**
  * Dispatch linsolve to the native addon (preferred) or ts-lapack fallback.
  * Returns null only when neither bridge exposes `linsolve` (should not happen
  * in practice since ts-lapack always has it).
  */
-export declare function linsolveLapack(A: FloatXArrayType, m: number, n: number, B: FloatXArrayType, nrhs: number): Float64Array | null;
+export declare function linsolveLapack(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array | null;
 /**
  * Dispatch complex linsolve to the native addon (preferred) or ts-lapack fallback.
  * The ts-lapack fallback throws — native addon is required for complex linsolve.
  */
-export declare function linsolveComplexLapack(ARe: FloatXArrayType, AIm: FloatXArrayType, m: number, n: number, BRe: FloatXArrayType, BIm: FloatXArrayType, nrhs: number): {
+export declare function linsolveComplexLapack(ARe: Float64Array, AIm: Float64Array, m: number, n: number, BRe: Float64Array, BIm: Float64Array, nrhs: number): {
     re: Float64Array;
     im: Float64Array;
 };

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

@@ -2,7 +2,6 @@
  * Seedable PRNG (xoshiro128**) for random number generation
  */
 import { RuntimeValue } from "../runtime/index.js";
-import { type FloatXArrayType } from "../runtime/types.js";
 export declare function setRngShuffle(): void;
 export declare function setRngSeed(seed: number): void;
 export declare function seedRng(seed: number): void;
@@ -10,7 +9,7 @@ export declare function seedRng(seed: number): void;
 export declare function rngRandom(): number;
 export declare function boxMullerRandom(): number;
 /** Fill a typed array with normal random values (bulk polar method) */
-export declare function fillRandn(data: FloatXArrayType): void;
+export declare function fillRandn(data: Float64Array): void;
 /** Return the current RNG state as a struct {Type, Seed, State} */
 export declare function getRngStateStruct(): RuntimeValue;
 /** Restore RNG state from a struct previously returned by rng() */

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/datetime.d.ts

@@ -27,7 +27,8 @@
  * `seconds(d)` returns the numeric seconds of a duration, or wraps a
  * number as a duration.
  */
-import type { RuntimeValue, RuntimeClassInstance } from "../../runtime/types.js";
+import type { RuntimeValue } from "../../runtime/types.js";
+import { RuntimeClassInstance } from "../../runtime/types.js";
 export declare function makeDatetime(year: number, month: number, day: number, hour: number, minute: number, second: number): RuntimeClassInstance;
 export declare function makeDuration(totalSeconds: number): RuntimeClassInstance;
 /**

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/misc.d.ts

@@ -1,4 +1,7 @@
 import type { RuntimeValue } from "../../runtime/types.js";
-/** Clear all appdata — called at the start of each executeCode to isolate runs. */
+/** Clear all appdata — called at the start of each executeCode to isolate
+ *  runs. Decrefs every stored value so the previous run's containers can
+ *  hit rc=0 cleanly; if the previous runtime is gone (test harness), we
+ *  just drop the JS references and let GC reclaim them. */
 export declare function resetAppdataStore(): void;
 export declare function convertJsonValue(val: unknown): RuntimeValue;

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

@@ -1,9 +1,9 @@
 /**
  * IBuiltin interface, registry, and shared helpers for interpreter builtins.
  */
-import type { RuntimeValue, RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
-import { FloatXArray } from "../../runtime/types.js";
-import { type JitType } from "../../jit/jitTypes.js";
+import type { RuntimeValue } from "../../runtime/types.js";
+import { RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
+import { type JitType } from "../../jitTypes.js";
 export interface IBuiltinResolution {
     outputTypes: JitType[];
     apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
@@ -17,56 +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;
-    /**
-     * Optional fast-path C code emission for the C-JIT. Return null if the
-     * builtin can't be emitted as a C expression for the given arg types
-     * — the C-JIT will bail to JS-JIT for this call site. Covers the
-     * scalar-argument case only (tensor-argument emission is handled by
-     * separate tensor-op dispatch in assemble.ts / emit/fused.ts).
-     */
-    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
-    /**
-     * Optional C-JIT tensor-op dispatch metadata. When a field is present,
-     * both the C feasibility check and C codegen read it directly —
-     * adding a new tensor-unary / tensor-binary / tensor-reduction builtin
-     * is one edit here (plus the matching native-side enum or C function).
-     * Previously these were three parallel hardcoded tables (one in
-     * feasibility.ts, two in context.ts) that could silently drift
-     * from the native-side opcode enums. Centralizing on the IBuiltin
-     * registration removes that drift risk.
-     */
-    jitCapabilities?: JitCapabilities;
-}
-/** Per-builtin C-JIT tensor-op dispatch metadata. See IBuiltin.jitCapabilities. */
-export interface JitCapabilities {
-    /**
-     * libnumbl_ops opcode enum name (e.g. "NUMBL_UNARY_EXP") for
-     * element-wise unary tensor builtins routed through
-     * `numbl_realUnaryElemwise`. Set this on element-wise unary functions
-     * that have a libnumbl_ops opcode and are safe to invoke on any real
-     * input (domain-restricted ones like log/sqrt stay excluded).
-     */
-    tensorUnaryOp?: string;
-    /**
-     * C function name (e.g. "fmax", "atan2", "numbl_mod") for 2-arg
-     * element-wise tensor builtins. The C-JIT emits an inline per-element
-     * loop calling this function; it must match the interpreter's
-     * scalar-apply semantics exactly.
-     */
-    tensorBinaryFn?: string;
-    /**
-     * libnumbl_ops opcode enum name (e.g. "NUMBL_REDUCE_SUM") for
-     * tensor→scalar reductions routed through `numbl_tensor_reduce_op`.
-     * Set on reduction builtins (sum / prod / max / min / any / all / mean).
-     */
-    tensorReductionOp?: string;
 }
 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;
@@ -78,12 +31,8 @@ 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: InstanceType<typeof FloatXArray>, imag: InstanceType<typeof FloatXArray> | undefined, shape: number[]): RuntimeTensor;
+export declare function makeTensor(data: Float64Array, imag: Float64Array | undefined, shape: number[]): RuntimeTensor;
 /** Type rule requiring two scalar numbers */
 export declare function binaryNumberOnly(argTypes: JitType[]): JitType[] | null;
 export declare function applyUnaryElemwise(v: RuntimeValue, realFn: (x: number) => number, complexFn: (re: number, im: number) => {
@@ -109,9 +58,6 @@ export declare function defineBuiltin(opts: {
     name: string;
     help?: BuiltinHelp;
     cases: BuiltinCase[];
-    jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
-    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
-    jitCapabilities?: JitCapabilities;
 }): void;
 type NumberJitType = Extract<JitType, {
     kind: "number";
@@ -149,55 +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;
-/** Fast-path C emitter for unary math functions on a scalar.
- *  Emits `cFn(x)` for scalar number/boolean; returns null otherwise
- *  (tensor emission is handled separately by emit/tensor.ts).
- *  If `requireNonneg` is set, rejects values whose sign isn't known
- *  to be nonneg — matches the JS guard for domain-restricted functions. */
-export declare function unaryMathJitEmitC(cFn: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[]) => string | null;
-/** Fast-path C emitter for binary math functions on two scalar numbers. */
-export declare function binaryMathJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar builtins that collapse to a
- * compile-time constant given the arg's kind. Common for shape/type
- * predicates where the answer is fully determined by the type
- * (e.g. `isnumeric(number) -> 1.0`, `isscalar(number) -> 1.0`,
- *       `ndims(number) -> 2.0`, `numel(number) -> 1.0`).
- *
- * `valueByKind` maps each supported JitType kind to its C constant.
- * Arg kinds not in the map return null, which bails the C-JIT to
- * JS-JIT for that call site. All values must be valid C double
- * literals (`"1.0"`, `"0.0"`, `"2.0"`, ...).
- */
-export declare function scalarConstantJitEmitC(valueByKind: Partial<Record<JitType["kind"], string>>): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar predicates backed by a runtime
- * helper whose return value is int (e.g. `numbl_is_nan`,
- * `numbl_is_inf`, `numbl_is_finite`). The int is cast to double for
- * the C-JIT's uniform boolean-as-double representation. Returns null
- * for non-scalar args.
- *
- * Note: `isnan` / `isinf` / `isfinite` from `<math.h>` can't be used
- * directly because the JIT compiles with `-ffast-math`, which implies
- * `-ffinite-math-only` and constant-folds those macros to false/true.
- * The `numbl_is_nan` / `_is_inf` / `_is_finite` helpers in
- * `jit_runtime` use bit-pattern inspection and live in a separately
- * compiled archive, so the caller's `-ffast-math` can't defeat them.
- */
-export declare function unaryPredicateJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar builtins that are the identity
- * on real scalars (e.g. `double(x)`, `real(x)`, `conj(x)`). Returns
- * `(x)` for `number`/`boolean`, null otherwise.
- */
-export declare function scalarIdentityJitEmitC(): (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. */
@@ -48,59 +65,43 @@ export declare class Interpreter {
     fileSources: Map<string, string>;
     /** @internal Guard against infinite recursion in compileSpecialized */
     compileInProgress: Set<string>;
-    /** @internal Per-instance cache for JIT-compiled loops (avoids cross-execution collisions). */
-    loopJitCache: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-        source: string;
-    } | null>;
-    /** @internal Progressive type widening for loop JIT: location -> last unified input types. */
-    loopLastInputTypes: Map<string, import("../jit/jitTypes.js").JitType[]>;
-    /** @internal Sibling stmts of the currently-executing stmt (set by execStmts). */
-    _postSiblings: import("../parser/types.js").Stmt[] | null;
-    /** @internal Index in _postSiblings of the next stmt after the current one. */
-    _postSiblingsIdx: number;
-    /** @internal Number of EXTRA sibling stmts that the current execStmt
-     *  consumed beyond the one passed in. The surrounding sibling loop
-     *  reads this after each execStmt and advances its index by this
-     *  many. Used by `--opt e2` chain fusion to atomically execute a run
-     *  of consecutive Assigns as one C kernel. The interpreter must
-     *  reset this to 0 before each execStmt call. */
-    _e2ChainAdvance: number;
-    /** @internal The stmt list of the innermost enclosing function body
-     *  (or top-level script body). Used by `--opt e2` chain liveness
-     *  analysis to decide whether a chain LHS is actually referenced
-     *  outside the chain — if not, the LHS becomes a per-element stack-
-     *  local rather than a materialized output buffer. Pushed on call
-     *  frame entry, popped on exit. */
-    _currentScopeBody: import("../parser/types.js").Stmt[] | null;
-    /** @internal Names that "escape" the current scope regardless of
-     *  textual usage. For functions: the declared output names (plus
-     *  `varargout`). For top-level scripts: `null`, meaning every name
-     *  escapes (the surrounding caller can read all script-level vars
-     *  via `result.variableValues`). Pushed/popped alongside
-     *  `_currentScopeBody`. */
-    _currentScopeExports: Set<string> | null;
     /**
-     * Optimization level:
-     *   0 — pure AST interpreter, no JIT.
-     *   1 — JS-JIT (default): type-specialize hot functions/loops to JS via `new Function()`.
+     * Optimization mode:
+     *   "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: number;
-    /**
-     * Experimental opt variant selector — e.g. `"e1"` for the mode that
-     * keeps JS-JIT as the outer and emits on-demand C kernels for fusible
-     * tensor chains and pure-scalar user functions. Undefined for the
-     * standard `--opt <n>` path.
-     */
-    experimental?: string;
-    /** Parallelize fused loops with OpenMP threads (--par flag). */
-    par: boolean;
-    /** Callback for JIT compilation logging (JS codegen). */
-    onJitCompile?: (description: string, jsCode: string) => void;
-    /** Callback for C-kernel compilation logging (--opt e2 / --dump-c). */
-    onCCompile?: (description: string, cCode: string) => void;
+    optimization: import("../executors/plugins.js").OptLevel;
+    /** 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;
+    /** 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",
+     *  ...). Hot path — keep the callback cheap. */
+    onExecutorFired?: (name: string, kind: string) => void;
     /** Verbose log sink (plumbed from ExecOptions.log). */
     log?: (message: string) => void;
+    /** Executor registry. Holds the strategies (JS-JIT, C-kernel, ...)
+     *  the dispatcher selects among at runtime. The AST interpreter is
+     *  the dispatcher's hardcoded fallback (not a registered executor).
+     *  Mode-driven plugins (`--opt 1`, `--opt 2`, ...) register
+     *  executors during `executeCode` setup. See
+     *  docs/developer_reference/executors.md. */
+    readonly registry: import("../executors/registry.js").Registry;
     constructor(rt: Runtime, ctx: LoweringContext, functionIndex: FunctionIndex, mainFileName: string, initialVariableValues?: Record<string, RuntimeValue>);
     /** Clear all JIT and function resolution caches. Called after addpath/rmpath. */
     clearAllCaches(): void;
@@ -112,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, {

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/interpreterSpecialBuiltins.d.ts

@@ -12,15 +12,18 @@ export interface InterpreterContext {
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
     callFunction: (name: string, args: unknown[], nargout: number) => unknown;
     rt: Runtime;
-    /** Optimization level (0 = JIT disabled, 1 = JIT scalar functions). */
-    optimization: number;
+    /** Optimization mode: "0" = no JIT, "1" = JS-JIT, "2" = C-JIT. */
+    optimization: import("../executors/plugins.js").OptLevel;
     /** Resolve a workspace function or class name to its source file,
      *  or undefined if no workspace file provides that name.
      *  `kind` distinguishes a regular .m function from a .numbl.js
-     *  user function (treated as a MEX-equivalent) or a class file. */
+     *  user function (treated as a MEX-equivalent) or a class file.
+     *  `source` is the raw .m source for "function"/"class" kinds, or empty
+     *  for "jsfunction" (where the implementation is JS, not .m text). */
     lookupWorkspaceFile: (name: string) => {
         path: string;
         kind: "function" | "jsfunction" | "class";
+        source: string;
     } | undefined;
 }
 export declare const FALL_THROUGH: unique symbol;

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

@@ -4,7 +4,6 @@
 import type { Stmt, ArgumentsBlock } from "../parser/types.js";
 import type { Runtime } from "../runtime/runtime.js";
 import type { RuntimeValue } from "../runtime/types.js";
-import type { JitType } from "../jit/jitTypes.js";
 export declare class BreakSignal {
     readonly _tag = "break";
 }
@@ -18,8 +17,8 @@ export declare class ReturnSignal {
 }
 export type ControlSignal = BreakSignal | ContinueSignal | ReturnSignal;
 export declare class Environment {
-    private parent?;
-    private vars;
+    parent?: Environment | undefined;
+    vars: Map<string, RuntimeValue>;
     /** When true, writes to variables found in parent go to the parent (nested function semantics). */
     isNested: boolean;
     /** Nested function definitions registered during execution. Lazy-initialized. */
@@ -44,12 +43,27 @@ export declare class Environment {
     persistentFuncId: string | undefined;
     /** Back-reference to the runtime (needed for global/persistent access) */
     rt: Runtime | null;
+    /** Set when a `@nestedFn` handle has been created that captures this env
+     *  (or an ancestor). Tells the function-exit cleanup that clearing this
+     *  env would strand the handle's closure, so locals must be left alive. */
+    nestedHandleCreated: boolean;
     constructor(parent?: Environment | undefined);
     get(name: string): RuntimeValue | undefined;
-    /** Set variable — for nested scopes, writes to parent if variable exists there. */
+    /** Set variable — for nested scopes, writes to parent if variable
+     *  exists there. Maintains refcounts: increfs the new value, decrefs
+     *  the slot's prior occupant (in that order so self-rebind is safe). */
     set(name: string, value: RuntimeValue): void;
     /** Always writes to this scope (for parameter binding). */
     setLocal(name: string, value: RuntimeValue): void;
+    /** Remove a variable from this scope's local map.
+     *  Returns true if the name was present locally. Does not touch
+     *  the parent scope, globals, or persistent registrations — those
+     *  are removed via `clear global` / `clear functions` (not yet
+     *  implemented). */
+    delete(name: string): boolean;
+    /** Remove all local variables from this scope. Globals,
+     *  persistents, and nested function defs are preserved. */
+    clearLocals(): void;
     has(name: string): boolean;
     /** Check if this scope directly owns a variable (not parent). */
     hasLocal(name: string): boolean;
@@ -60,9 +74,17 @@ export declare class Environment {
         fn: FunctionDef;
         env: Environment;
     } | undefined;
+    /** Mark this env and every ancestor up to (and including) the env that
+     *  defines `name` as having had a nested-function handle created. The
+     *  handle's closure references this env, so any of those scopes' locals
+     *  must stay alive after the function exits. Returns true if `name`
+     *  was found as a nested-function definition somewhere in the chain. */
+    markChainForNestedHandle(name: string): boolean;
     localNames(): string[];
     /** Create a snapshot of this environment (copies all variables by value).
-     *  Used for anonymous functions which capture values at definition time. */
+     *  Used for anonymous functions which capture values at definition time.
+     *  Each captured value is incref'd so it survives the source env's
+     *  clearLocals when the original frame returns. */
     snapshot(): Environment;
     toRecord(): Record<string, RuntimeValue>;
 }
@@ -72,13 +94,6 @@ export interface FunctionDef {
     outputs: string[];
     body: Stmt[];
     argumentsBlocks?: ArgumentsBlock[];
-    /** JIT compilation cache: maps signature key -> compiled entry or null (failed). */
-    _jitCache?: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-        source: string;
-    } | null>;
-    /** Progressive type widening: last unified arg types, keyed by nargout. */
-    _lastJitArgTypes?: Map<number, JitType[]>;
 }
 /** Create a FunctionDef from an AST Function statement. */
 export declare function funcDefFromStmt(stmt: Stmt & {