numbl 0.4.8 → 0.4.9

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

@@ -0,0 +1,31 @@
+/**
+ * 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;
+    /** One uniform double in [0, 1). Backed by numbl's process-global PRNG
+     *  (the same `rngRandom` the interpreter uses), so JIT'd and interpreted
+     *  `rand` draw from one shared, `rng(seed)`-controllable stream. */
+    rand: () => number;
+}
+export declare function buildHostHelpers(rt: Runtime): JitHostHelpers;

package/dist-browser/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-browser/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-browser/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-browser/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-browser/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-browser/numbl-core/executors/jit/valueAdapter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 { Type } from "../../jit/index.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.
+ *
+ *  `paramType` is the compiler `Type` the spec was COMPILED for at this
+ *  parameter. It reconciles two value/type mismatches at the boundary,
+ *  both mirroring the C adapter (valueAdapterC):
+ *
+ *   1. **1×1 tensor → scalar param.** The compiler collapses a [1,1]
+ *      tensor type to a scalar `double`/`complex` (`!isMultiElement`),
+ *      so scalar codegen reads a bare number / `{re, im}`. A 1×1
+ *      `RuntimeTensor` value must therefore be unwrapped to its element;
+ *      otherwise the tensor OBJECT leaks into scalar arithmetic and
+ *      `a.data[i] + b` becomes `number + object = NaN`.
+ *   2. **real → complex-scalar param.** Type-widening can reuse a complex
+ *      specialization for a later real/boolean scalar call; the
+ *      complex-typed body reads `.re`/`.im`, so a bare number must be
+ *      boxed into `{re, im:0}`. */
+export declare function numblToJit(v: RuntimeValue, paramType?: Type): 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-browser/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-browser/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-browser/numbl-core/executors/plugins.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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";
+import type { Executor } from "./types.js";
+/** The three C-JIT executors, registered at Node bootstrap. */
+export interface CJitExecutors {
+    topLevel: Executor;
+    loop: Executor;
+    call: Executor;
+}
+/** Register the C-JIT executors. Called once at Node bootstrap. */
+export declare function registerCJitExecutors(execs: CJitExecutors): void;
+/** 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;