numbl 0.3.3 → 0.4.1

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

@@ -20,10 +20,13 @@ export interface ExecOptions {
     log?: (message: string) => void;
     /** Enable profiling of builtin function calls. */
     profile?: boolean;
-    /** Called each time a JIT function is compiled, with a description and the generated JS. */
-    onJitCompile?: (description: string, jsCode: string) => void;
-    /** Called each time a C-JIT artifact is compiled, with a description and the generated C source. */
-    onCJitCompile?: (description: string, cCode: string) => void;
+    /** Called each time a JIT function is compiled, with a description, the
+     *  generated source, and the backend language (`"js"` or `"c"`). */
+    onJitCompile?: (description: string, code: string, lang: "js" | "c") => void;
+    /** Called when a JIT-compiled unit bails to the interpreter at runtime
+     *  (e.g. an indexed-store array growth the JIT can't model). Surfaced
+     *  as a warning; the CLI routes it to stderr. */
+    onJitBail?: (message: string) => void;
     /** Initial hold state for plotting (persisted across REPL executions). */
     initialHoldState?: boolean;
     /** Override or add builtins for this execution only. */
@@ -34,13 +37,8 @@ export interface ExecOptions {
     system?: SystemAdapter;
     /** Synchronous callback for the `input()` builtin. Displays prompt, returns user's line. */
     onInput?: (prompt: string) => string;
-    /** Optimization mode: `"0"` interpreter, `"1"` JS-JIT, `"e3"` C-JIT
-     *  scalar-loop only. */
+    /** Optimization mode: `"0"` interpreter, `"1"` JS-JIT, `"2"` C-JIT. */
     optimization?: import("./executors/plugins.js").OptLevel;
-    /** Compile C-JIT kernels with `-ffast-math` (libmvec-vectorized
-     *  transcendentals; reductions are reorder-allowed). Default true;
-     *  opt out via the CLI's `--no-fast-math` flag. */
-    fastMath?: boolean;
     /**
      * Initial implicit cwd path for the MATLAB-style "cwd is the first search path" feature.
      * - undefined → auto-detect from `system.cwd()` and scan its files.
@@ -81,8 +79,8 @@ export interface ProfileData {
 export interface ExecResult {
     output: string[];
     generatedJS: string;
-    /** Collected C source from C-JIT compilations during this run, or
-     *  empty when no C-JIT artifact was produced. */
+    /** C source emitted by the C-JIT backend (`--opt 2`). Empty placeholder
+     *  when no C was generated (e.g. `--opt 0`/`1`). */
     generatedC: string;
     plotInstructions: PlotInstruction[];
     returnValue: RuntimeValue;

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

@@ -0,0 +1,134 @@
+/**
+ * Classification (JS-JIT-independent).
+ *
+ * Two classification phases — top-level (whole-script) and call
+ * (user-function-call) — produce the analysis records that codegen
+ * executors consume to decide whether they can lower a stmt list /
+ * call and to key their caches.
+ *
+ * The analysis is purely AST + type inference and is consumed by the
+ * JIT executors (`executors/jit/`) — no backend-specific IR involved.
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { FunctionDef } from "../interpreter/types.js";
+import type { Stmt, Expr } from "../parser/types.js";
+import { type JitType } from "../jitTypes.js";
+/** A capture-free function handle the JIT inlines into the spec body as
+ *  an in-scope `@...` constant instead of taking it as a runtime input.
+ *  `identity` keys the spec cache (distinct handles → distinct specs). */
+export interface ConstHandle {
+    readonly name: string;
+    readonly expr: Expr;
+    readonly identity: string;
+}
+/** Names that look like variables but never resolve to env values
+ *  (constants, the special `end` slot, the imaginary unit). Skipped
+ *  when collecting env inputs. */
+export declare const KNOWN_CONSTANTS: ReadonlySet<string>;
+/**
+ * Drop `exact` from a numeric scalar `JitType`. Numeric `exact` only
+ * survives unification when two consecutive specializations see the
+ * *same* literal — almost never the case for variables — so stripping
+ * up front means the first specialization's cacheKey already matches
+ * later calls.
+ */
+export declare function pruneArgType(t: JitType): JitType;
+/**
+ * Progressive type widening: in-place unify each entry of `types`
+ * with the corresponding entry of `prev`. No-op when shapes don't
+ * match (different arity → different specialization, no widening).
+ *
+ * Widening that would collapse a known type to `unknown` is rejected
+ * — keep this call's concrete type so a fresh, specific spec gets
+ * built. Without this, a 1st call with (number, …) followed by a 2nd
+ * call with (tensor, …) would unify the first arg to `unknown` and
+ * poison every subsequent specialization with the same arg shape.
+ */
+export declare function widenAgainst(types: JitType[], prev: readonly JitType[] | undefined): void;
+/**
+ * Gather env inputs for the synthetic FunctionDef of a top-level
+ * block. For each candidate name: skip known constants, skip names
+ * not in env (likely fn names), infer the JIT type, prune `exact`.
+ * Returns null if any candidate has an unknown type — that's a
+ * structural blocker for lowering.
+ */
+export declare function gatherTypedEnvInputs(interp: Interpreter, candidates: readonly string[]): {
+    inputs: string[];
+    inputTypes: JitType[];
+} | null;
+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;
+    /** Body contains a `%!numbl:assert_jit c` directive (the C-JIT
+     *  variant) — see `containsAssertJitC`. Makes the JS-JIT executors
+     *  decline at `--opt 2` so the unit must C-JIT (or fall to the
+     *  interpreter, which raises). */
+    readonly assertsCJit: boolean;
+    readonly cacheKey: string;
+}
+export declare function classifyTopLevel(interp: Interpreter, stmts: readonly Stmt[], prevInputTypes: readonly JitType[] | undefined): TopLevelClassification | null;
+export interface LoopClassification {
+    /** The single For/While stmt this classification describes. */
+    readonly stmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly inputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    /** Loop-local writes that are read by code AFTER the loop in the
+     *  same sibling list. Loop-internal-only temporaries are filtered
+     *  out so a JIT artifact doesn't need to write them back to env. */
+    readonly outputs: readonly string[];
+    readonly currentFile: string;
+    readonly hasReturn: boolean;
+    /** Loop body contains a `%!numbl:assert_jit c` directive (C-JIT variant). */
+    readonly assertsCJit: boolean;
+    /** Capture-free handle inputs to inline as in-scope `@...` constants
+     *  in the synthesized spec body (instead of runtime inputs). */
+    readonly constHandles: readonly ConstHandle[];
+    readonly cacheKey: string;
+}
+/**
+ * Classify a single For/While loop at `siblings[siblingIndex]`. The
+ * post-loop tail of the sibling list is scanned to filter the
+ * loop's assigned-set down to names that are actually live-out
+ * (read after the loop) — purely loop-internal scratch never makes
+ * it into the synthetic function's outputs.
+ */
+export declare function classifyLoop(interp: Interpreter, stmt: Stmt & {
+    type: "For" | "While";
+}, siblings: readonly Stmt[], siblingIndex: number, prevInputTypes: readonly JitType[] | undefined): LoopClassification | null;
+export interface CallClassification {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly cacheKey: string;
+    /**
+     * Effective 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`, …). argTypes is one-to-one with
+     * effectiveParams.
+     */
+    readonly effectiveParams: readonly string[];
+    /** Number of variadic args (0 when fn has no varargin). */
+    readonly nVarargin: number;
+    /** Function body contains a `%!numbl:assert_jit c` directive (C-JIT variant). */
+    readonly assertsCJit: boolean;
+}
+export declare function classifyCall(fn: FunctionDef, args: unknown[], nargout: number, prevArgTypes: readonly JitType[] | undefined): CallClassification | null;
+/** True if any statement in `stmts` is a `%!numbl:assert_jit c` directive
+ *  (the C-JIT variant), recursing into control-flow bodies (if / for /
+ *  while / switch / try) but NOT into nested function definitions — a
+ *  directive inside a nested function belongs to that function's own unit.
+ *
+ *  Only the `c` variant matters here: it requires C-JIT at `--opt 2`, so
+ *  the JS-JIT executors decline such a unit at `--opt 2` to force either
+ *  C-JIT or an interpreter fallthrough (which then raises). The plain
+ *  `%!numbl:assert_jit` (require JS-JIT at `--opt 1` only) needs no
+ *  executor change — the interpreter's `Directive` handler raises if it
+ *  reaches the directive at `--opt 1`. */
+export declare function containsAssertJitC(stmts: readonly Stmt[]): boolean;

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

@@ -0,0 +1,42 @@
+/**
+ * Function-handle inlining for the JIT.
+ *
+ * A function handle that crosses a compile boundary — a loop input
+ * (`f = @...; for ...; f(x); end`) or a call argument
+ * (`applyfn(@sq, x)`) — arrives at the executor as an opaque
+ * `function_handle` value the JIT can't type. But a *capture-free*
+ * handle is fully described by its source AST, so instead of marshaling
+ * it across the boundary we inline its `@...` definition as an in-scope
+ * handle constant inside the synthesized spec. That reduces the boundary
+ * case to the already-supported in-scope case (`lowerAnonFunc` /
+ * `lowerFuncHandle` + `dispatchHandleCall`), which lowers identically on
+ * the JS and C backends — no value-adapter or ABI work.
+ *
+ * "Capture-free" is the key constraint: a handle that closes over an
+ * outer variable can't be inlined, because the inlined copy would
+ * re-resolve that name in the spec's scope (a different value, or
+ * unresolved) rather than the by-value snapshot the handle took. We
+ * detect captures against the handle's own recorded definition
+ * environment, so the test reflects what the handle actually closed
+ * over, not a syntactic guess.
+ */
+import type { Expr } from "../parser/index.js";
+/**
+ * If `val` is a function handle the JIT can inline as a compile-time
+ * constant in a spec compiled for `compileFile`, return its `@...`
+ * defining Expr; otherwise return null.
+ *
+ * Inlinable iff:
+ *  - it's a `RuntimeFunction` carrying a recorded `handleAst`, AND
+ *  - it was defined in `compileFile` (so a `@name` target resolves to
+ *    the same function it did at definition — file-local functions can
+ *    shadow across files), AND
+ *  - for an anonymous handle, it is capture-free: no name its body
+ *    references (other than its own params) exists as a variable in the
+ *    handle's recorded definition environment.
+ *
+ * Named (`@name`) handles are always capture-free. Anything the lowerer
+ * ultimately can't compile (e.g. a builtin target) simply makes the
+ * enclosing unit decline to the interpreter — still correct.
+ */
+export declare function inlinableHandleExpr(val: unknown, compileFile: string): Expr | null;

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

@@ -11,7 +11,4 @@ export { ExecutorCache } from "./cache.js";
 export type { JitType, SignCategory } from "../jitTypes.js";
 export { jitTypeKey, unifyJitTypes, isScalarType, isTensorType, isComplexType, isKnownInteger, } from "../jitTypes.js";
 export { inferJitType } from "../interpreter/builtins/types.js";
-export { jsJitTopLevelExecutor } from "./jsJit/topLevelExecutor.js";
-export { jsJitLoopExecutor } from "./jsJit/loopExecutor.js";
-export { jsJitCallExecutor } from "./jsJit/callExecutor.js";
 export { registerExecutorsForOpt } from "./plugins.js";

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

@@ -0,0 +1,35 @@
+/**
+ * cjit-call — C-backed JIT executor for user-function calls.
+ *
+ * Mirrors `callExecutor.ts` (the JS-emit sibling) but routes the
+ * specialization's emitted code through `compileSpecC` →
+ * `cc -shared -fPIC -O3` → `dlopen` via koffi instead of
+ * `new Function(source)`. The dispatch, gating, and caching
+ * conventions are otherwise identical, so a sibling executor can
+ * register alongside the JS path at the same opt level without any
+ * arbitration in the dispatcher beyond cost-based selection.
+ *
+ * Declines when:
+ *   - `nativeBridge` / `koffi` are not available (browser).
+ *   - Any param or output type fails the C-FFI feasibility check
+ *     (`compilerTypeToCDecl` returns null).
+ *   - mtoc2 throws `UnsupportedConstruct` / `JitTypeError` at lowering.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitCallData {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly compilerArgTypes: readonly CompilerType[];
+    readonly args: readonly unknown[];
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitCallExecutor: Executor<CJitCallData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,31 @@
+/**
+ * cjit-loop — C-backed JIT executor for outermost For/While
+ * loops. Mirrors `loopExecutor.ts` (JS-emit sibling) but routes
+ * through `compileSpecC` → `cc -shared` → `koffi`. See
+ * `cJitCallExecutor.ts` for the marshaling protocol; this file just
+ * adapts the loop-shape `data` to the same C-side pipeline.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import type { ConstHandle } from "../classification.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitLoopData {
+    readonly loopStmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly constHandles: readonly ConstHandle[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitLoopExecutor: Executor<CJitLoopData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,29 @@
+/**
+ * cjit-top-level — C-backed JIT executor for whole-script bodies.
+ *
+ * Mirrors `topLevelExecutor.ts` (JS-emit sibling) but routes through
+ * `compileSpecC` → `cc -shared` → `koffi`. See `cJitCallExecutor.ts`
+ * for the marshaling protocol. Same `isAllSuppressed` gate as the JS
+ * sibling so `displayAssign`/`displayResult` semantics stay on the
+ * interpreter path.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitTopLevelData {
+    readonly stmts: readonly Stmt[];
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitTopLevelExecutor: Executor<CJitTopLevelData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,45 @@
+/**
+ * jit-call — executor that compiles user-function calls via mtoc2's
+ * `compileSpec` JIT entry point and runs the emitted JS in-process.
+ *
+ * Replaces the JS-JIT call executor at `--opt 1`. The shape of the
+ * fallback path is the same: on rejection (mtoc2's
+ * `UnsupportedConstruct` / `TypeError` during lowering, or a JitType
+ * the type adapter can't translate), `propose()` declines and the
+ * dispatcher falls through to the next executor / interpreter.
+ *
+ * Key differences from JS-JIT:
+ *
+ * - **No mid-run bailouts.** mtoc2 either lowers cleanly or rejects
+ *   statically. When `compile()` returns, the artifact will run to
+ *   completion. `bailRisk` is `false`.
+ * - **Shared `Lowerer.specializations` is the cache.** One Workspace
+ *   + Lowerer pair per LoweringContext (i.e. per execution session);
+ *   accumulating specs persist across calls so a function called
+ *   repeatedly with the same arg signature reuses the prior compile.
+ * - **Output-count support.** `nargout >= 1` (single-output and
+ *   multi-output `[a, b, ...] = f(x)`). `nargout === 0` (bare-stmt
+ *   `f();`) is declined because mtoc2's nargout=0 spec emits a no-
+ *   return body, but numbl's interpreter still uses the first
+ *   declared output for `ans` binding — let the interpreter handle.
+ * - **Loop-depth gate.** Declines when `interp.loopDepth > 0` so a
+ *   hot loop iterating function calls doesn't pay per-call JIT
+ *   propose / spec-cache overhead. Once an outer call is JIT'd, its
+ *   loops run inside mtoc2's compiled code anyway.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import { type Type as CompilerType } from "../../jit/index.js";
+interface JitCallData {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly compilerArgTypes: readonly CompilerType[];
+    readonly args: readonly unknown[];
+}
+interface CompiledArtifact {
+    readonly specFn: (...args: unknown[]) => unknown;
+}
+export declare const jitCallExecutor: Executor<JitCallData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,51 @@
+/**
+ * Browser-safe surface for the koffi C-JIT pipeline.
+ *
+ * The real implementation (`compileAndLoadCImpl`) lives in
+ * `compileC.node.ts` because it imports Node-only modules (`node:fs`,
+ * `node:child_process`, `node:os`, `node:crypto`) that vite/rollup
+ * cannot bundle for the browser. The CLI's bootstrap registers the
+ * Node implementation here at startup via `setCompileAndLoadCImpl()`;
+ * any browser bundle leaves it unregistered, so the koffi-backed
+ * executors decline (their proposals already gate on
+ * `bridge.koffi !== undefined`).
+ *
+ * Types stay in this file so the koffi executors can import them
+ * without dragging Node-only deps into the static dep graph.
+ */
+import type { NativeBridge } from "../../workspace/types.js";
+/** The koffi function reference returned by `lib.func(decl)`. The
+ *  actual call signature is controlled by the caller's declaration —
+ *  type as variadic and let the caller cast. */
+export type CFn = (...args: unknown[]) => unknown;
+export interface CompiledC {
+    readonly fn: CFn;
+    /** koffi `Lib` instance — useful for binding auxiliary symbols
+     *  (`free` from libc, allocator helpers, etc.) without re-opening
+     *  the .so. */
+    readonly lib: KoffiLib;
+    /** Path to the .so on disk — diagnostics only. */
+    readonly libPath: string;
+    /** Cache hit (true) vs. fresh cc invocation (false). */
+    readonly cacheHit: boolean;
+}
+/** koffi's runtime-shaped lib object. Loosely typed because koffi
+ *  doesn't ship TS types for its declaration-string API. */
+export interface KoffiLib {
+    func(declaration: string): CFn;
+}
+/** Signature of the real compile-and-load. The CLI registers an
+ *  implementation that shells out to `cc` and `dlopen`s the result
+ *  via koffi. */
+export type CompileAndLoadCImpl = (source: string, declaration: string, bridge: NativeBridge) => CompiledC;
+/** Install the Node-side C-JIT implementation. Called by `cli.ts`
+ *  during CLI bootstrap; browser bundles never call this, so `impl`
+ *  stays null and the koffi executors decline. */
+export declare function setCompileAndLoadCImpl(fn: CompileAndLoadCImpl): void;
+/** Compile (or look up cached) and load. Delegates to whatever was
+ *  registered via `setCompileAndLoadCImpl()`; throws if no
+ *  implementation is available (= running in a browser host that
+ *  somehow got past the koffi executor's `bridge.koffi` gate). */
+export declare function compileAndLoadC(source: string, declaration: string, bridge: NativeBridge): CompiledC;
+export declare function setReadCachedCSourceImpl(fn: (hash: string) => string | null): void;
+export declare function readCachedCSource(hash: string): string | null;

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

@@ -0,0 +1,25 @@
+/**
+ * Node-only implementation of the koffi C-JIT pipeline.
+ *
+ * Cache layout: `~/.cache/numbl/mtoc2-c-jit/<sha>.so` (one per unique
+ * `(declaration, source, flags)` triple). On hit, `dlopen` and reuse —
+ * no `cc` invocation. On miss, write `<sha>.c`, exec `cc`, then
+ * `dlopen`.
+ *
+ * This file is split out of `compileC.ts` so the browser bundle stays
+ * free of `node:fs` / `node:child_process` imports — vite/rollup
+ * cannot resolve them for the browser target. Browser bundles import
+ * only `compileC.ts` (types + a runtime-injected stub); the CLI
+ * imports this file at bootstrap and calls `setCompileAndLoadCImpl()`.
+ */
+import type { NativeBridge } from "../../workspace/types.js";
+import { type CompiledC } from "./compileC.js";
+/** Compile (or look up cached) and load. The cache key is the SHA of
+ *  `(flags, declaration, source)` so two different signatures or
+ *  compile-flag sets against the same source get distinct artifacts. */
+export declare function compileAndLoadC(source: string, declaration: string, bridge: NativeBridge): CompiledC;
+/** Read a previously-compiled C source from disk. Diagnostic helper. */
+export declare function readCachedCSource(hash: string): string | null;
+/** Register both implementations with the browser-safe surface. The
+ *  CLI imports this module at bootstrap to wire them in. */
+export declare function registerNodeCompileC(): void;

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

@@ -0,0 +1,27 @@
+/**
+ * Build the `$h` helpers object that mtoc2's emitted spec receives
+ * when invoked via the numbl JIT bridge.
+ *
+ *  - `write(s)` — output sink. Routed to `rt.output(...)` so `disp` /
+ *    `fprintf` / `warning` etc. land in numbl's output stream.
+ *  - `plotDispatch(name, args)` — host hook for plot builtins.
+ *    mtoc2's emitted `mtoc2_plot_dispatch(...)` calls this in
+ *    preference to the standalone-mode JSON-on-stdout wire format.
+ *    We translate args from mtoc2's emit shape into `RuntimeValue`
+ *    via `jitToNumbl` and call numbl's `dispatchPlotBuiltin`,
+ *    pushing the resulting instruction onto `rt.plotInstructions` —
+ *    so `colorbar('off')` / `pcolor(...)` / etc. produce the same
+ *    plot-instruction stream as the interpreter would.
+ *
+ * The unknown-name fallthrough (when `dispatchPlotBuiltin` returns
+ * false) is a programmer error: every name mtoc2's plot builtin
+ * registration covers is in `PLOT_ALL_NAMES`, which is sourced from
+ * the same list `dispatchPlotBuiltin` switches on. Throw so the
+ * mismatch is loud rather than silently dropping a side effect.
+ */
+import type { Runtime } from "../../runtime/runtime.js";
+export interface JitHostHelpers {
+    write: (s: string) => void;
+    plotDispatch: (name: string, args: unknown[]) => void;
+}
+export declare function buildHostHelpers(rt: Runtime): JitHostHelpers;

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

@@ -0,0 +1,41 @@
+/**
+ * jit-loop — compiles a single For/While stmt via mtoc2's
+ * `compileSpec` with the loop wrapped as a synthetic user function
+ * whose params are the variables the loop reads (env inputs) and
+ * whose outputs are the variables it assigns that are live after the
+ * loop (filtered in classification).
+ *
+ * Mirrors `topLevelExecutor.ts` — the only structural difference is
+ * that the synthetic body is a single-element `[loopStmt]` instead of
+ * a whole script body.
+ *
+ * Loop-depth gate: only fires when `interp.loopDepth === 0`. A loop
+ * dispatched while the interpreter is iterating an enclosing
+ * loop-body would pay per-iter propose/cache overhead with no
+ * speedup, because the *outer* loop is the natural JIT entry point
+ * (it captures the inner loop's body and runs it natively in mtoc2-
+ * emitted code). When the outer loop fires its own JIT, the inner
+ * loop never reaches the interpreter dispatcher at all.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import { type Type as CompilerType } from "../../jit/index.js";
+import type { ConstHandle } from "../classification.js";
+interface JitLoopData {
+    readonly loopStmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly constHandles: readonly ConstHandle[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly specFn: (...args: unknown[]) => unknown;
+}
+export declare const jitLoopExecutor: Executor<JitLoopData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,17 @@
+/**
+ * Per-LoweringContext mtoc2 session state shared between
+ * `jitCallExecutor` and `jitTopLevelExecutor`. One `Workspace`
+ * (built from numbl's existing `LoweringContext`) and one `Lowerer`
+ * per execution session, so the `Lowerer.specializations` cache
+ * persists across whole-scope + per-call dispatches.
+ *
+ * The session is keyed on the LoweringContext object — WeakMap-cleared
+ * automatically when the context goes out of scope.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import { Workspace, Lowerer } from "../../jit/index.js";
+export interface SessionState {
+    workspace: Workspace;
+    lowerer: Lowerer;
+}
+export declare function getOrCreateSession(interp: Interpreter): SessionState;

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

@@ -0,0 +1,36 @@
+/**
+ * jit-top-level — compiles a script body via mtoc2's `compileSpec`
+ * with the body wrapped as a synthetic user function whose params are
+ * the variables the body reads (env inputs) and whose outputs are the
+ * variables it assigns (env outputs).
+ *
+ * The interpreter calls `Registry.tryRunWholeScope` once at script
+ * start; we register this via `registerWholeScope`. On compile
+ * success the entire script runs in mtoc2-emitted JS; on
+ * `UnsupportedConstruct` / `TypeError` we decline and the dispatcher
+ * falls through to per-stmt dispatch (where jit-call still handles
+ * individual user-function calls).
+ *
+ * Top-level loops *inside* the script execute as part of the
+ * compiled artifact, so `loopDepth` only gates dispatch-level calls,
+ * not this whole-scope attempt.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import { type Type as CompilerType } from "../../jit/index.js";
+interface JitTopLevelData {
+    readonly stmts: readonly Stmt[];
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly specFn: (...args: unknown[]) => unknown;
+    readonly nargout: number;
+}
+export declare const jitTopLevelExecutor: Executor<JitTopLevelData, CompiledArtifact | null>;
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Adapter: numbl `JitType` → mtoc2 `Type`.
+ *
+ * Called by the mtoc2 JIT executor at `propose()` time. Numbl observes
+ * each argument's `JitType` from the live runtime value (via
+ * `inferJitType`); the adapter translates it into the matching mtoc2
+ * Type so `compileSpec` can specialize on the same shape information.
+ *
+ * Two design rules:
+ *
+ * 1. **Always strip exact.** Runtime-observed scalars must NOT shard
+ *    mtoc2's spec cache by value. We never propagate `exact` through
+ *    the adapter — `compileSpec` calls `withoutExact` again
+ *    defensively, but doing it here makes the spec key wider one step
+ *    earlier.
+ * 2. **Reject unsupported kinds via `null`.** The executor's
+ *    `propose()` treats `null` from this adapter as "decline this
+ *    JIT proposal" — the dispatcher falls through to the next
+ *    executor (eventually the interpreter). First-cut coverage is
+ *    scalars + dense real/complex tensors + strings + chars. Structs,
+ *    cells, class instances, struct arrays, sparse, dictionaries, and
+ *    function handles return `null`; they can be added later.
+ */
+import type { JitType } from "../../jitTypes.js";
+import { type Type } from "../../jit/index.js";
+/** Translate a numbl `JitType` to the matching mtoc2 `Type`.
+ *  Returns `null` for kinds the mtoc2 JIT path doesn't accept (yet). */
+export declare function jitTypeToCompilerType(jt: JitType): Type | null;