numbl 0.3.0 → 0.4.0

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;

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

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

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

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

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

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

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

@@ -0,0 +1,120 @@
+/**
+ * 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.
+ *
+ * Lowering here is *classification only*: it analyses inputs/outputs,
+ * infers types, and synthesizes a cacheKey. It does NOT make
+ * codegen-feasibility decisions — those live in the codegen executor's
+ * `propose`. This keeps the dispatcher free of dependencies on the
+ * JIT backend's internals (the in-tree compiler under
+ * `src/numbl-core/jit`).
+ *
+ * Shapes today:
+ *   - `top-level` — script body (top-level scope). Whole script
+ *     analysed as a synthetic FunctionDef.
+ *   - `call`      — user-function call. Produced by `tryLowerCall`
+ *     from `dispatchCall`.
+ *   - `synth`     — a `Synth` AST stmt produced by a registered AST
+ *     transformer (no further analysis here).
+ *
+ * Lowerings are cached by (head Stmt or FunctionDef, classification
+ * cacheKey).
+ */
+import type { Stmt } from "../parser/types.js";
+import type { FunctionDef } from "../interpreter/types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import { type TopLevelClassification, type CallClassification, type LoopClassification } from "./classification.js";
+/** What `propose()` receives — a discriminated union of the
+ *  specialized shapes the dispatcher knows how to lower. Stmts with
+ *  no specialized shape don't reach `propose()` at all; the dispatcher
+ *  falls through to its hardcoded interpreter path. */
+export type LoweredStmt = TopLevelLoweredStmt | LoopLoweredStmt | CallLoweredStmt | SynthLoweredStmt;
+/** Top-level shape: script body analysed for whole-scope codegen. */
+export interface TopLevelLoweredStmt {
+    readonly kind: "top-level";
+    readonly classification: TopLevelClassification;
+}
+/** Loop shape: a single For/While stmt analysed for loop codegen.
+ *  Produced by `tryLower` when the head stmt is a For/While. */
+export interface LoopLoweredStmt {
+    readonly kind: "loop";
+    readonly classification: LoopClassification;
+}
+/** Call shape: a user-function call analysed for call codegen.
+ *  Produced by `tryLowerCall`, not `tryLower` — function calls fire
+ *  from expression evaluation, not from the stmt loop. */
+export interface CallLoweredStmt {
+    readonly kind: "call";
+    readonly classification: CallClassification;
+    /** 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[];
+}
+/** 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]`. 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, interp: Interpreter, cache: LoweringCache): LoweredStmt | null;
+/**
+ * Lower a script body as a whole-scope unit. Called by the registry
+ * before the per-stmt dispatch loop runs; returns a TopLevelLoweredStmt
+ * for whole-scope executors to consider, or null when the classification
+ * declines.
+ */
+export declare function tryLowerTopLevel(interp: Interpreter, siblings: readonly Stmt[], cache: LoweringCache): TopLevelLoweredStmt | null;
+/**
+ * Try to lower a user-function call. Always returns a
+ * `CallLoweredStmt` when classification succeeds; null when the
+ * classify declines (`~` params, type-unknown args, varargin
+ * arity mismatch).
+ */
+export declare function tryLowerCall(fn: FunctionDef, args: unknown[], nargout: number, cache: LoweringCache): CallLoweredStmt | null;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+import type { Registry } from "./registry.js";
+/** Optimization mode label.
+ *
+ *   - `"0"` — pure AST interpreter, no executors registered.
+ *   - `"1"` — JS-JIT: all three shapes (top-level, loop,
+ *     call) emit JS via `compileSpec`. JIT declines
+ *     (`UnsupportedConstruct` / `JitTypeError`) fall back to the
+ *     interpreter cleanly.
+ *   - `"2"` — C-JIT-first with JS-JIT fallback. Both backends
+ *     register their executors; the dispatcher picks based on cost,
+ *     so the C path wins where it applies (scalar / tensor numeric
+ *     types with a wired `nativeBridge`) and the JS path picks up
+ *     the slack (struct / class / handle / no-cc-available).
+ *     Requires `cc` on the PATH and `koffi` installed; without
+ *     either, the C executors decline and `"2"` collapses to the
+ *     same behaviour as `"1"`. */
+export type OptLevel = "0" | "1" | "2";
+export declare const OPT_LEVELS: readonly OptLevel[];
+export declare function isOptLevel(s: string): s is OptLevel;
+/** Register the executors for a given optimization mode. */
+export declare function registerExecutorsForOpt(registry: Registry, opt: OptLevel): void;

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;