numbl 0.2.0 → 0.3.3

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

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

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

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

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

@@ -0,0 +1,166 @@
+/**
+ * Shared lowering pipeline.
+ *
+ * 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").
+ *
+ * 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.
+ *
+ * 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`
+ *     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).
+ *
+ * Lowerings are cached by (head Stmt or FunctionDef, classification
+ * cacheKey).
+ */
+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";
+/** 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 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. */
+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. */
+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
+ *  multiple registered transformers. */
+export interface SynthLoweredStmt {
+    readonly kind: "synth";
+    readonly tag: string;
+    readonly data: unknown;
+}
+declare const BAILED: unique symbol;
+type Bailed = typeof BAILED;
+/** Per-owner lowering cache. Owner is either the head Stmt
+ *  (stmt-shape lowerings) or the FunctionDef (call-shape lowerings).
+ *  WeakMap-scoped so entries are reclaimed when the AST is dropped.
+ *
+ *  Also tracks per-owner type-widening state: the most recent input
+ *  type signature seen for a given (owner, slot). Classify phases
+ *  consult this so a callee invoked with shifting input types
+ *  converges to a single specialization rather than thrashing the
+ *  cache. The slot string lets one owner host multiple widening
+ *  trackers (e.g. one per nargout for call-shape). */
+export declare class LoweringCache {
+    private readonly slots;
+    private readonly widening;
+    get(owner: object, cacheKey: string): LoweredStmt | Bailed | undefined;
+    set(owner: object, cacheKey: string, value: LoweredStmt): void;
+    markBailed(owner: object, cacheKey: string): void;
+    isBailed(value: unknown): value is Bailed;
+    /** Most recent input-type signature recorded for (owner, slot), or
+     *  undefined when nothing has been recorded yet. */
+    getLastInputTypes(owner: object, slot: string): import("../jitTypes.js").JitType[] | undefined;
+    /** Record the latest unified input-type signature for (owner, slot). */
+    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.
+ *
+ * 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;
+/**
+ * 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
+ * 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).
+ */
+export declare function tryLowerCall(fn: FunctionDef, args: unknown[], nargout: number, interp: Interpreter, cache: LoweringCache): CallLoweredStmt | null;
+export {};

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

@@ -0,0 +1,39 @@
+/**
+ * Mode-driven executor registration.
+ *
+ * `registerExecutorsForOpt(registry, opt)` is the single switch from
+ * an `--opt` value to a set of registered executors. Adding a new
+ * mode means extending the switch here — no other call-site changes.
+ *
+ * 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";
+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/executors/registry.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Executor registry and dispatch.
+ *
+ * Three entry points, three concerns:
+ *   - `dispatch(siblings, i, ctx)` — per-stmt dispatch. Each executor
+ *     handles exactly one stmt (no consumed-N).
+ *   - `dispatchCall(fn, args, nargout, interp)` — user-function call.
+ *   - `tryRunWholeScope(siblings, interp)` — whole-script attempt,
+ *     called once before the per-stmt loop runs. Top-level executors
+ *     register here separately from per-stmt ones.
+ *
+ * Plugins register executors at startup; the dispatcher selects among
+ * them at runtime based on cost estimates. The AST interpreter is the
+ * always-matching last-resort fallback for per-stmt dispatch and isn't
+ * a registered executor.
+ */
+import type { Stmt } from "../parser/types.js";
+import type { ControlSignal, FunctionDef } from "../interpreter/types.js";
+import type { Executor } from "./types.js";
+import { DispatchContext } from "./context.js";
+/** AST stmt-list transformer. Receives a stmt list and returns a
+ *  list of the same semantics, possibly with `Synth` stmts inserted
+ *  where the transformer can collapse a contiguous run of stmts into
+ *  a unit handled by a specialized executor. The transform is
+ *  shallow — recursive descent into For/While/If bodies happens
+ *  lazily on the next call to `transformStmts`, cached separately. */
+export type StmtTransformer = (stmts: readonly Stmt[]) => Stmt[];
+export interface DispatchResult {
+    /** Control signal from interpreter execution (break/continue/return),
+     *  if any. */
+    signal: ControlSignal | null;
+}
+/** Result from `dispatchCall`. `null` means no executor handled the
+ *  call — the caller should fall through to its own
+ *  interpreter-execution path. */
+export type CallDispatchResult = {
+    result: unknown;
+} | null;
+/** Result from `tryRunWholeScope`. `null` means no whole-scope
+ *  executor matched (or all bailed) — the caller should fall through
+ *  to the per-stmt dispatch loop. */
+export type WholeScopeResult = {
+    signal: ControlSignal | null;
+} | null;
+export declare class Registry {
+    /** Per-stmt executors (loop, call, fuse). */
+    private readonly executors;
+    /** Whole-scope executors (top-level). Iterated only by
+     *  `tryRunWholeScope`, separate from per-stmt dispatch. */
+    private readonly wholeScopeExecutors;
+    /** AST stmt-list transformers. Run lazily on each stmt list before
+     *  the per-stmt loop walks it; result cached per input list. */
+    private readonly transformers;
+    /** Memoize transformed lists by input list identity. WeakMap so
+     *  entries vanish when the AST is dropped. The transformed list
+     *  is also stored mapped to itself so a second call with the
+     *  result hits the cache (idempotency). */
+    private transformCache;
+    private cache;
+    private loweringCache;
+    /** Pre-allocated context reused for `dispatchCall`. Avoids the
+     *  per-call Map+Set allocation cost that previously motivated
+     *  bypassing ctx entirely on call-heavy workloads. Safe to reuse
+     *  because dispatchCall isn't reentrant within itself: each call's
+     *  propose/compile/run touches the context synchronously, and any
+     *  nested call dispatch goes through `Interpreter.callUserFunction`
+     *  which re-enters dispatchCall and re-resets the context. */
+    private callCtx;
+    register(executor: Executor): void;
+    /** Register an executor that handles a whole stmt list as a unit
+     *  (e.g. JS-JIT top-level). Iterated only by `tryRunWholeScope`
+     *  and never seen by per-stmt dispatch. */
+    registerWholeScope(executor: Executor): void;
+    /** Register an AST stmt-list transformer. Transformers run on every
+     *  stmt list the interpreter is about to walk (script body, function
+     *  body, loop body, if branch, ...) before the per-stmt loop kicks
+     *  in. They typically wrap contiguous runs of stmts in `Synth`
+     *  nodes that a matching executor will recognize. Adding new
+     *  transformers is additive — they compose in registration order. */
+    registerStmtTransformer(fn: StmtTransformer): void;
+    /** Transform a stmt list, applying all registered transformers in
+     *  registration order. Cached per input-list identity (WeakMap).
+     *  When no transformers are registered, returns the input unchanged
+     *  without populating the cache (saves a Map lookup per dispatch). */
+    transformStmts(stmts: readonly Stmt[]): Stmt[];
+    /** Number of registered per-stmt executors. Mainly for tests. */
+    get size(): number;
+    /** Drop all cached compiled artifacts. Called from
+     *  `Interpreter.clearAllCaches()` after addpath/rmpath etc. */
+    clearCache(): void;
+    /**
+     * Dispatch one statement at `siblings[i]`. Each executor handles
+     * exactly one stmt — the dispatcher always advances by one on
+     * success.
+     *
+     * Hot path. Two optimizations matter for the chunkie-helmholtz-
+     * scale workloads:
+     *
+     *   1. The AST interpreter is the always-applicable last-resort
+     *      fallback. It is *not* a registered executor — the dispatcher
+     *      hardcodes a direct call to `ctx.interp.execStmt(stmt)` when
+     *      no specialized executor matches or all of them bail. This
+     *      avoids per-dispatch match/Candidate/cache/result allocations
+     *      for the most common path (where only the interpreter would
+     *      fit anyway).
+     *
+     *   2. The reentrancy guard (`pushActive`/`popActive` /
+     *      `isActive`) is short-circuited when the active set is
+     *      empty — no sub-dispatch in flight means the bookkeeping is
+     *      pure overhead.
+     */
+    dispatch(siblings: readonly Stmt[], i: number, ctx: DispatchContext): DispatchResult;
+    private runStmtCandidate;
+    /** Cache lookup + compile-on-miss + run + bail handling. Returns
+     *  the executor's success RunResult, or null when the candidate
+     *  bailed (cache may have been marked BAILED). When `guardKey` is
+     *  non-null, the reentrancy guard pushes/pops around `run()` —
+     *  passed by the stmt path; the call path passes null because
+     *  `dispatchCall` isn't reentrant within itself. */
+    private executeCandidate;
+    /**
+     * Dispatch a user-function call. Iterates the same `executors`
+     * array as stmt dispatch — call-shape executors filter on
+     * `lowered.kind === "call"`. Returns `{ result }` when one of them
+     * handles the call, or `null` so the caller (callUserFunction)
+     * falls through to the AST interpreter.
+     *
+     * Reuses a pre-allocated DispatchContext (`callCtx`) to avoid the
+     * per-call Map+Set allocation that previously motivated bypassing
+     * ctx for call dispatch entirely.
+     */
+    dispatchCall(fn: FunctionDef, args: unknown[], nargout: number, interp: import("../interpreter/interpreter.js").Interpreter): CallDispatchResult;
+    private runCallCandidate;
+    private getCallCtx;
+    /**
+     * Whole-scope dispatch: try to handle the entire stmt list as a
+     * single unit (e.g. JS-JIT top-level). Called by the Interpreter
+     * once before the per-stmt loop runs. Returns:
+     *   - `{ signal }` when a whole-scope executor handled the body.
+     *     The caller should skip the per-stmt loop entirely.
+     *   - `null` when no whole-scope executor matched (or all bailed).
+     *     The caller falls through to per-stmt dispatch.
+     */
+    tryRunWholeScope(siblings: readonly Stmt[], interp: import("../interpreter/interpreter.js").Interpreter): WholeScopeResult;
+    private finishWholeScope;
+}
+/** Build a fresh dispatch context. */
+export declare function makeRootContext(interp: import("../interpreter/interpreter.js").Interpreter, registry: Registry): DispatchContext;

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

@@ -62,6 +62,8 @@ export interface FileIOAdapter {
     unzip?(zipfilename: string, outputfolder: string): string[];
     /** Return the temporary directory path. Optional. */
     tempdir?(): string;
+    /** Return the numbl user/config directory path. Optional. */
+    userpath?(): string;
     /** List directory entries. Returns array of {name, folder, bytes, isdir, mtimeMs}. Optional. */
     listDir?(dirPath: string): {
         name: string;

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.