numbl 0.4.21 → 0.4.22

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

@@ -1,120 +1,62 @@
 /**
  * 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.
+ * The registry lowers each unit once, before any executor is asked to
+ * propose, and passes the resulting `LoweredStmt` to every executor
+ * registered for that shape:
  *
- * 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).
+ *   - `top-level` — a script body (`tryLowerTopLevel`), analysed as a
+ *     synthetic FunctionDef.
+ *   - `loop`      — a For/While stmt (`tryLowerLoop`).
+ *   - `call`      — a user-function call (`tryLowerCall`).
  *
- * Lowerings are cached by (head Stmt or FunctionDef, classification
- * cacheKey).
+ * Lowering here is *classification only*: it analyses inputs/outputs,
+ * infers types, and synthesizes a cacheKey. Codegen-feasibility decisions
+ * live in each executor's `propose`, which keeps this layer free of
+ * dependencies on the JIT compiler (`src/numbl-core/jit`).
  */
 import type { Stmt } from "../parser/types.js";
 import type { FunctionDef } from "../interpreter/types.js";
 import type { Interpreter } from "../interpreter/interpreter.js";
+import type { JitType } from "../jitTypes.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. */
+/** What `propose()` receives — a discriminated union of the shapes the
+ *  registry knows how to lower. */
+export type LoweredStmt = TopLevelLoweredStmt | LoopLoweredStmt | CallLoweredStmt;
 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. */
+    /** Runtime arg values. Unlike the env-reading shapes, a call executor
+     *  cannot re-fetch its inputs from the 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;
+/** Per-owner type-widening state: the most recent input type signature
+ *  seen for (owner, slot), where owner is the head Stmt (top-level, loop)
+ *  or the FunctionDef (call). Classification widens against it so a unit
+ *  invoked with shifting input types converges to a single specialization
+ *  rather than thrashing the compile cache. The slot lets one owner host
+ *  several trackers (one per nargout for calls). WeakMap-scoped so entries
+ *  are reclaimed when the AST is dropped. */
+export declare class WideningState {
+    private readonly last;
+    get(owner: object, slot: string): JitType[] | undefined;
+    set(owner: object, slot: string, types: readonly JitType[]): void;
 }
-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 {};
+/** Lower a For/While stmt at `siblings[i]`. Classification needs the
+ *  post-loop tail of the sibling list (to filter outputs) and the env
+ *  (for input types). Null when classification declines. */
+export declare function tryLowerLoop(interp: Interpreter, siblings: readonly Stmt[], i: number, widening: WideningState): LoopLoweredStmt | null;
+/** Lower a script body as a whole-scope unit. Null when classification
+ *  declines. */
+export declare function tryLowerTopLevel(interp: Interpreter, siblings: readonly Stmt[], widening: WideningState): TopLevelLoweredStmt | null;
+/** Lower a user-function call. Null when classification declines (`~`
+ *  params, type-unknown args, varargin arity mismatch). */
+export declare function tryLowerCall(fn: FunctionDef, args: unknown[], nargout: number, widening: WideningState): CallLoweredStmt | null;

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

@@ -1,39 +1,25 @@
 /**
  * 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.
+ * `registerExecutorsForOpt(registry, opt)` is the single switch from an
+ * `--opt` value to a set of registered executors. Each JIT backend
+ * contributes one executor per shape (top-level, loop, call); the
+ * registry tries them in registration order. The AST interpreter is the
+ * registry's last-resort fallback and isn't registered.
  */
 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;
+import type { JitBackend } from "./jit/backend.js";
+/** Register the C backend. Called once at Node bootstrap. */
+export declare function registerCJitBackend(backend: JitBackend): 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"`. */
+ *   - `"1"` — JS-JIT for all three shapes.
+ *   - `"2"` — C-JIT first, JS-JIT as fallback, per shape. C-JIT takes
+ *     what it can marshal (scalar / tensor numeric types with a wired
+ *     `nativeBridge`); JS-JIT picks up the rest (struct / class / handle).
+ *     Without `cc` + `koffi` the C executors decline and `"2"` behaves
+ *     like `"1"`. */
 export type OptLevel = "0" | "1" | "2";
 export declare const OPT_LEVELS: readonly OptLevel[];
 export declare function isOptLevel(s: string): s is OptLevel;

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

@@ -1,115 +1,41 @@
 /**
  * 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).
+ * Three entry points, one per lowered shape:
+ *   - `tryRunWholeScope(siblings, interp)` — whole-script attempt, called
+ *     once before the per-stmt loop runs.
+ *   - `dispatch(siblings, i, interp)` — per-stmt dispatch; loops are
+ *     offered to the loop executors, everything else is interpreted.
  *   - `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.
+ * Executors are tried in registration order (at `--opt 2`: C-JIT, then
+ * JS-JIT). The first that proposes and runs without bailing wins. The AST
+ * interpreter is the last-resort fallback 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;
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Executor, RunResult, ShapeKind } from "./types.js";
 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;
+    private widening;
+    /** Register an executor for its shape. Order matters: earlier
+     *  executors are tried first. */
+    register<K extends ShapeKind>(executor: Executor<K>): void;
+    /** Whether any call executor is registered. */
+    get hasCallExecutors(): boolean;
     /** 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;
+    /** Try to handle the entire script body as a unit. Returns false when
+     *  no executor took it; the caller then runs the per-stmt loop. */
+    tryRunWholeScope(siblings: readonly Stmt[], interp: Interpreter): boolean;
+    /** Dispatch the stmt at `siblings[i]`. Returns its control signal. */
+    dispatch(siblings: readonly Stmt[], i: number, interp: Interpreter): ControlSignal | null;
+    /** Dispatch a user-function call. Returns `{ result }` when an executor
+     *  handled it, or `null` so the caller runs the interpreter's call path. */
+    dispatchCall(fn: FunctionDef, args: unknown[], nargout: number, interp: Interpreter): RunResult;
     /** Run one stmt on the AST interpreter.
      *
      *  When that stmt is a loop, the interpreter is about to walk its body,
@@ -118,39 +44,12 @@ export declare class Registry {
      *  that for the duration of the body so nested loops and calls can bid for
      *  themselves instead of running interpreted all the way down. */
     private interpretFallback;
-    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;
+    /** Try `executors` in order; return the first success, or null when
+     *  all declined or bailed. `owner` scopes the compile cache (head Stmt
+     *  or FunctionDef). */
+    private runFirst;
+    /** Cache lookup + compile-on-miss + run. A bail (including a compile
+     *  that declined, which the executor reports as a bail from `run`) is
+     *  cached so the same (executor, owner, key) is not retried. */
+    private execute;
 }
-/** 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

@@ -3,101 +3,39 @@
  *
  * 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().
+ * The interpreter delegates whole-script bodies, loops, and user-function
+ * calls to a registry of Executors. Each executor handles one lowered shape
+ * (`top-level`, `loop`, or `call`). The registry tries the executors
+ * registered for a shape in order; the first that proposes and runs
+ * without bailing wins, and the AST interpreter handles the rest.
  */
-import type { DispatchContext } from "./context.js";
+import type { Interpreter } from "../interpreter/interpreter.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. */
- | {
+export type ShapeKind = LoweredStmt["kind"];
+export type LoweredOf<K extends ShapeKind> = Extract<LoweredStmt, {
+    kind: K;
+}>;
+/** Outcome of `run`. `{ result }` on success (the call's return value
+ *  for the `call` shape; `undefined` otherwise). `null` is a bail: the
+ *  registry discards any captured output, caches the bail, and tries
+ *  the next executor (or the interpreter). */
+export type RunResult = {
     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. */
+} | null;
+export interface Executor<K extends ShapeKind = ShapeKind, D = unknown, C = unknown> {
+    /** Stable identifier for diagnostics and the compile cache. */
     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. */
+    /** The lowered shape this executor handles. */
+    readonly kind: K;
+    /** Decide whether to take this unit. Runs on every dispatch, so it
+     *  must be cheap. Returns per-executor data passed to `compile` and
+     *  `run`, or null to decline. */
+    propose(lowered: LoweredOf<K>, interp: Interpreter): D | null;
+    /** Stable cache key projected from the proposal data. Drops volatile
+     *  bits (e.g. exact scalar values) so repeated runs reuse 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;
+    /** Compile to a runnable artifact. Called only on cache miss; cached
+     *  under (executor, owner, cacheKey). */
+    compile(data: D, interp: Interpreter): C;
+    run(compiled: C, data: D, interp: Interpreter): RunResult;
 }

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

@@ -11,12 +11,10 @@ export type ResolvedTarget = {
     kind: "classMethod";
     className: string;
     methodName: string;
-    compileArgTypes: ItemType[];
     stripInstance: boolean;
 } | {
     kind: "localFunction";
     name: string;
-    argTypes: ItemType[];
     source: {
         from: "main";
     } | {
@@ -33,31 +31,23 @@ export type ResolvedTarget = {
 } | {
     kind: "privateFunction";
     name: string;
-    argTypes: ItemType[];
     callerFile: string;
 } | {
     kind: "workspaceFunction";
     name: string;
-    argTypes: ItemType[];
 } | {
     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;
-    argTypes: ItemType[];
 } | {
     kind: "builtin";
     name: string;
 };
+/** The argument type that resolution needs: only an object's class affects
+ *  which function a name resolves to. */
+export declare function resolutionArgType(v: unknown): ItemType;
 /**
  * Definitively resolve a function name to a single target using the FunctionIndex.
  * Returns null only if the function is truly not found.

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

@@ -37,11 +37,6 @@ export declare function maybeComplexTensor(re: Float64Array | Float64Array, shap
  * Optionally includes an imaginary diagonal.
  */
 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: Float64Array, rows: number, totalCols: number): void;
 /**
  * Call a registered builtin from within another builtin's apply().
  * Convenience wrapper that includes the caller name in error messages.

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

@@ -0,0 +1,14 @@
+/**
+ * Compile a wildcard pattern to an anchored RegExp.
+ *
+ * Default (single name): `*` matches any run of characters and `?` any one
+ * character, as in `dir('*.m')`, `delete('*.txt')` or `who('a*')`.
+ *
+ * `paths: true` matches slash-separated paths: `*` and `?` stay within one
+ * segment, `**` matches anything, and `**` followed by `/` matches zero or
+ * more directory levels (so a double-star prefix before `x.m` also matches a
+ * top-level `x.m`).
+ */
+export declare function globToRegExp(pattern: string, opts?: {
+    paths?: boolean;
+}): RegExp;