numbl 0.3.0 → 0.3.3

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

@@ -22,8 +22,8 @@ export interface ExecOptions {
     profile?: boolean;
     /** Called each time a JIT function is compiled, with a description and the generated JS. */
     onJitCompile?: (description: string, jsCode: string) => void;
-    /** Called each time an e2 C kernel is compiled, with a description and the generated C source. */
-    onCCompile?: (description: string, cCode: string) => void;
+    /** Called each time a C-JIT artifact is compiled, with a description and the generated C source. */
+    onCJitCompile?: (description: string, cCode: string) => void;
     /** Initial hold state for plotting (persisted across REPL executions). */
     initialHoldState?: boolean;
     /** Override or add builtins for this execution only. */
@@ -34,17 +34,13 @@ export interface ExecOptions {
     system?: SystemAdapter;
     /** Synchronous callback for the `input()` builtin. Displays prompt, returns user's line. */
     onInput?: (prompt: string) => string;
-    /** Optimization level for interpreter (0 = none, >=1 = JIT scalar functions). */
-    optimization?: number;
-    /**
-     * Experimental opt variant selector — e.g. `"e1"` for the prototype
-     * that keeps JS-JIT as the outer and emits on-demand C kernels for
-     * fusible tensor chains. Orthogonal to `optimization`; when set,
-     * `optimization` is still the base level (typically 1).
-     */
-    experimental?: string;
-    /** Parallelize fused loops with OpenMP threads (--par flag). */
-    par?: boolean;
+    /** Optimization mode: `"0"` interpreter, `"1"` JS-JIT, `"e3"` C-JIT
+     *  scalar-loop only. */
+    optimization?: import("./executors/plugins.js").OptLevel;
+    /** Compile C-JIT kernels with `-ffast-math` (libmvec-vectorized
+     *  transcendentals; reductions are reorder-allowed). Default true;
+     *  opt out via the CLI's `--no-fast-math` flag. */
+    fastMath?: boolean;
     /**
      * Initial implicit cwd path for the MATLAB-style "cwd is the first search path" feature.
      * - undefined → auto-detect from `system.cwd()` and scan its files.
@@ -85,7 +81,8 @@ export interface ProfileData {
 export interface ExecResult {
     output: string[];
     generatedJS: string;
-    /** Concatenated C-kernel source for all e2 compilations during the run. */
+    /** Collected C source from C-JIT compilations during this run, or
+     *  empty when no C-JIT artifact was produced. */
     generatedC: string;
     plotInstructions: PlotInstruction[];
     returnValue: RuntimeValue;

package/dist-lib/numbl-core/executors/cJit/builtins.d.ts

@@ -0,0 +1,30 @@
+/**
+ * C-JIT builtin registry — the single source of truth for which
+ * builtins each C-JIT context can emit.
+ *
+ * Two contexts:
+ *
+ *   - **Elementwise** (`c-jit-fuse`, `c-jit-chain`): unary real-math
+ *     builtins that compile to a single C function call inside an
+ *     element-wise loop. Real-only — no complex args.
+ *
+ *   - **Scalar loop** (`c-jit-loop`): a superset that adds `atan2`
+ *     (binary) and the complex projection builtins (`real`, `imag`,
+ *     `conj`, which accept either real or complex args).
+ *
+ * Adding a new builtin: extend the relevant set here, make sure the
+ * C name is right (override `cBuiltinName` if it differs), and add a
+ * test or benchmark that exercises it. See
+ * `docs/developer_reference/jit/cjit-substrate.md` for the broader
+ * substrate contract.
+ */
+/** Real-only unary math builtins emittable in an element-wise loop. */
+export declare const ELEMWISE_REAL_BUILTINS: ReadonlySet<string>;
+/** Real-only math builtins emittable in a scalar loop body.
+ *  Superset of the elementwise set; adds `atan2` (binary). */
+export declare const LOOP_REAL_MATH_BUILTINS: ReadonlySet<string>;
+/** Projection builtins that accept real OR complex args. */
+export declare const LOOP_COMPLEX_PROJECTION_BUILTINS: ReadonlySet<string>;
+/** Map a numbl/MATLAB builtin name to its math.h C name. Identity for
+ *  most; `abs` maps to `fabs` because C's `abs` is integer-typed. */
+export declare function cBuiltinName(name: string): string;

package/dist-lib/numbl-core/executors/cJit/chainCodegen.d.ts

@@ -0,0 +1,59 @@
+/**
+ * c-jit-chain codegen — combine N adjacent fusable Assigns into one
+ * C kernel with a single i-loop.
+ *
+ * Each per-name role is decided by walking the chain in source order:
+ *   - input-tensor   : first occurrence is RHS, env says it's a tensor
+ *   - input-scalar   : first occurrence is RHS, env says it's a scalar
+ *   - local-tensor   : first occurrence is LHS (writes the value
+ *                      without reading any prior value); becomes a
+ *                      per-iter `double` local
+ *   - input+local    : first occurrence is RHS but the chain also
+ *                      writes it — read from input pointer, then
+ *                      writes update the local
+ *
+ * Live-outs (any LHS of any Assign in the chain) get their own `double *`
+ * out parameter and a writeback at the end of the loop body.
+ *
+ * Today: every RHS expression must be element-wise on tensors of the
+ * chain's numel (scalars broadcast). The executor's propose() rejects
+ * chains where this can't be guaranteed.
+ *
+ * ABI:
+ *   void <fnName>(
+ *       long n,
+ *       double *out_<name1>, double *out_<name2>, ...,   // live-outs
+ *       const double *in_<nameA>, const double *in_<nameB>, ...,
+ *       double <nameC>, double <nameD>, ...);
+ */
+import type { ChainAnalysis } from "./chainPass.js";
+/** Per-name role (decided at compile time using env types). */
+export type NameRole = {
+    kind: "input-tensor";
+} | {
+    kind: "input-scalar";
+} | {
+    kind: "local-tensor";
+    readsFromInput: boolean;
+};
+/** Resolved per-name info carried from compile() into codegen. */
+export interface ChainResolution {
+    /** Role for every name referenced in the chain. */
+    readonly roles: ReadonlyMap<string, NameRole>;
+    /** Names whose final value is live-out (written somewhere in the
+     *  chain). For Phase A: every Assign LHS is conservatively
+     *  live-out. */
+    readonly liveOuts: readonly string[];
+    /** Tensor input names in stable order (for koffi declaration). */
+    readonly tensorInputs: readonly string[];
+    /** Scalar input names in stable order. */
+    readonly scalarInputs: readonly string[];
+}
+/** Decide each name's role from the AST + a "is this var a tensor?"
+ *  classifier. Returns null if any per-stmt structure is incompatible
+ *  with the codegen — caller should bail. */
+export declare function resolveChain(cls: ChainAnalysis, isTensor: (name: string) => boolean | null): ChainResolution | null;
+/** Build the koffi function declaration string. */
+export declare function buildChainDeclaration(fnName: string, res: ChainResolution): string;
+/** Emit the C source. */
+export declare function generateChainCSource(fnName: string, cls: ChainAnalysis, res: ChainResolution): string;

package/dist-lib/numbl-core/executors/cJit/chainExecutor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * c-jit-chain — element-wise chain executor.
+ *
+ *   - `propose()` filters on Synth stmts with `tag === "c-jit-chain"`.
+ *     Reads each tensor input's `numel` from env and verifies they
+ *     all match. Declines below `CHAIN_MIN_NUMEL`.
+ *
+ *   - `compile()` resolves per-name roles using runtime env types,
+ *     emits the combined C kernel, builds the koffi declaration,
+ *     calls compileAndLoad. Surfaces source via `interp.onCJitCompile`.
+ *
+ *   - `run()` gathers tensor data + scalars, allocates one
+ *     `Float64Array(numel)` per live-out, invokes the kernel, writes
+ *     each live-out back to env as a `RuntimeTensor` with the input
+ *     tensors' shape.
+ */
+import type { Executor } from "../types.js";
+import type { SynthLoweredStmt } from "../lowering.js";
+import { type ChainResolution } from "./chainCodegen.js";
+import { type CompiledC } from "./compile.js";
+interface ChainCompiled {
+    readonly compiled: CompiledC;
+    readonly resolution: ChainResolution;
+    readonly source: string;
+}
+export declare const cJitChainExecutor: Executor<SynthLoweredStmt, ChainCompiled | null>;
+export {};

package/dist-lib/numbl-core/executors/cJit/chainPass.d.ts

@@ -0,0 +1,42 @@
+/**
+ * c-jit-chain AST transformer.
+ *
+ * Walks a stmt list once and identifies maximal contiguous runs of
+ * adjacent stmts that are individually candidates for fusion (today:
+ * tensor element-wise Assigns whose RHS is a fusable expression
+ * tree). Wraps each non-trivial run (length >= 2) in a `Synth` node
+ * with `tag: "c-jit-chain"`; the matching `cJitChainExecutor` will
+ * compile the whole chain to one C kernel at dispatch time.
+ *
+ * Singletons (chains of length 1) are left as the original Assign so
+ * the existing `c-jit-fuse` per-stmt path handles them. That keeps
+ * the win path narrow: chains exist only where multiple adjacent
+ * fusable Assigns can amortize per-call overhead and share memory
+ * traversal.
+ *
+ * Purely structural — no env access. Runtime decisions (size,
+ * type-shape match) happen in the executor's `propose()`.
+ *
+ * Recursive descent: For/While/If bodies are transformed lazily via
+ * `Registry.transformStmts` when the interpreter walks them. This
+ * pass just operates on the immediate stmt list.
+ */
+import { type Stmt } from "../../parser/types.js";
+/** Per-stmt classification used by the chain executor. The data
+ *  carried on each Synth node is `ChainAnalysis`. */
+export interface ChainAnalysis {
+    /** Original Assigns in source order. */
+    readonly assigns: readonly (Stmt & {
+        type: "Assign";
+    })[];
+    /** Stable shape hash — combines per-stmt RHS structures and LHS
+     *  names, used by the executor's cacheKey. Sizes / runtime types
+     *  are NOT included; those affect cost, not codegen shape. */
+    readonly cacheKey: string;
+}
+/**
+ * Transform a stmt list, wrapping maximal fusable runs (length >= 2)
+ * in `Synth` nodes. Returns a new list when any transformation
+ * happens; returns the input unchanged otherwise.
+ */
+export declare function chainPass(stmts: readonly Stmt[]): Stmt[];

package/dist-lib/numbl-core/executors/cJit/codegen.d.ts

@@ -0,0 +1,44 @@
+/**
+ * c-jit-loop codegen — JIT IR → C source.
+ *
+ * Emits one C function per loop. Each scalar variable is encoded
+ * either as a single `double` (real) or a pair `<name>_re`, `<name>_im`
+ * (complex). Inputs are passed by value (real → 1 arg, complex →
+ * 2 args); outputs are written through a `double *out` pointer
+ * (real → 1 slot, complex → 2 slots).
+ *
+ * Codegen is deliberately narrow — see `whitelist.ts` for the set of
+ * IR nodes accepted. Anything outside that set is a programming error
+ * here (the executor's `propose()` must reject before reaching this
+ * module).
+ */
+import type { JitStmt, JitType } from "../../jitTypes.js";
+/** Per-variable C encoding. */
+export type VarEncoding = "real" | "complex";
+/** Resolved (input + local) variable types. Codegen keys lookups on
+ *  the variable name; both Vars and Assigns consult this map. */
+export type VarTypeMap = ReadonlyMap<string, VarEncoding>;
+/** Emitted scalar value. Real values are a single C expression;
+ *  complex values are a (re, im) pair. */
+export type Emitted = {
+    kind: "real";
+    expr: string;
+} | {
+    kind: "complex";
+    re: string;
+    im: string;
+};
+/** Walk the IR + input typings and produce a per-name encoding map.
+ *  A name is "complex" iff at least one read or write of it has a
+ *  complex_or_number type. Otherwise "real".
+ *
+ *  This mirrors the JIT's type widening: by the time the IR is
+ *  produced, every Var / Assign for the same name has been unified
+ *  to a single type. The walker just records that type. */
+export declare function inferVarEncodings(inputs: readonly string[], inputTypes: readonly JitType[], body: readonly JitStmt[]): Map<string, VarEncoding>;
+/** Per-variable slot count in the marshaling ABI: real → 1, complex → 2. */
+export declare function varSlotCount(enc: VarEncoding): number;
+/** Total number of `double` slots a variable list consumes. */
+export declare function totalSlotCount(names: readonly string[], varTypes: VarTypeMap): number;
+/** Emit a complete C source file. */
+export declare function generateCSource(fnName: string, inputs: readonly string[], outputs: readonly string[], body: readonly JitStmt[], varTypes: VarTypeMap): string;

package/dist-lib/numbl-core/executors/cJit/compile.d.ts

@@ -0,0 +1,45 @@
+/**
+ * c-jit compile + cache + load.
+ *
+ * Cache layout: `~/.cache/numbl/c-jit/<sha>.so` (one per unique
+ * (declaration, source) pair). On hit, dlopen and reuse — no `cc`
+ * invocation. On miss, write `<sha>.c`, exec `cc`, dlopen.
+ *
+ * The koffi function declaration is fully owned by the caller —
+ * different executors (c-jit-loop, c-jit-fuse, ...) emit the
+ * declaration that matches their ABI. This module only handles
+ * source-string-in / koffi-callable-out.
+ */
+import type { NativeBridge } from "../../workspace/types.js";
+/**
+ * The koffi function reference returned by `lib.func(decl)`. The
+ * actual call signature is controlled by the caller's declaration —
+ * type as variadic and let the caller cast as needed.
+ */
+export type CFn = (...args: unknown[]) => unknown;
+export interface CompiledC {
+    readonly fn: CFn;
+    /** Path to the .so on disk — useful for diagnostics. */
+    readonly libPath: string;
+    /** Cache hit (true) vs. fresh cc invocation (false). */
+    readonly cacheHit: boolean;
+}
+export interface CompileOptions {
+    /** Enable `-ffast-math`. On by default for ~30% speedup on
+     *  element-wise tensor benchmarks (libmvec vectorization of
+     *  transcendentals). Opt out via the CLI's `--no-fast-math` flag
+     *  to keep FP semantics bitwise-deterministic. */
+    readonly fastMath?: boolean;
+}
+/**
+ * Compile (or look up cached) and load. The cache key is the SHA of
+ * `(declaration, source)` so the same source compiled with different
+ * koffi declarations gets distinct cache entries (defensive — usually
+ * the declaration matches the source's signature).
+ */
+export declare function compileAndLoad(source: string, declaration: string, bridge: NativeBridge, options?: CompileOptions): CompiledC;
+/**
+ * Read a previously-compiled C source from disk. Diagnostic helper
+ * for verifying cache hits.
+ */
+export declare function readCachedSource(hash: string): string | null;

package/dist-lib/numbl-core/executors/cJit/elemwiseCodegen.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared codegen helpers for the element-wise C-JIT executors
+ * (`c-jit-fuse`, `c-jit-chain`).
+ *
+ * Both executors lower the same AST subset (the one accepted by
+ * `elemwiseStructural.isElemwiseStructuralExpr`) to C; they only
+ * differ in how an `Ident` leaf maps to a C expression (tensor pointer
+ * indexing vs. local-name vs. scalar parameter). This module owns the
+ * shared structural emitter and a few utility helpers; the per-executor
+ * codegen is reduced to a thin wrapper that supplies the leaf mapping.
+ */
+import { type Expr } from "../../parser/types.js";
+/** Emit a C `double` literal that's unambiguous to the compiler.
+ *  Handles NaN, ±Inf, integer-valued doubles. */
+export declare function formatDouble(v: number): string;
+/** Walk `e` and add every `Ident` name to `out`. Whitelisted to the
+ *  element-wise AST subset — anything outside (e.g. `Index`) is a
+ *  programming error (the structural classifier should have rejected). */
+export declare function collectIdents(e: Expr, out: Set<string>): void;
+/** Lower an element-wise AST expression to a C string. The caller
+ *  supplies `identToC` to map each `Ident` name to its in-loop C form
+ *  (e.g. `t0[i]`, `in_x[i]`, `s2`, or a bare local name). */
+export declare function emitElemwiseExpr(e: Expr, identToC: (name: string) => string): string;

package/dist-lib/numbl-core/executors/cJit/elemwiseStructural.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared structural classifier for element-wise C-JIT.
+ *
+ * The "is this AST expression element-wise lowerable?" check, in two
+ * pieces:
+ *
+ *   - `isElemwiseStructuralExpr(e)` — fully structural, no env access.
+ *     Used by `chainPass` (runs at stmt-list-entry time, before env
+ *     types are known).
+ *
+ *   - `isElemwiseBinaryOp(op)` / `binaryOpNeedsScalarCheck(op)` — the
+ *     binary-op subset, exposed so env-aware walkers (`fuseAnalyze`)
+ *     can apply runtime-scalar checks on top of the structural shape.
+ *
+ * Pairs with `builtins.ts` (which owns the unary builtin set). Anything
+ * not accepted here is rejected at propose-time.
+ */
+import { BinaryOperation, type Expr, UnaryOperation } from "../../parser/types.js";
+/** Binary ops the element-wise codegen can emit. `Mul`/`Div` are matrix
+ *  ops in MATLAB but degenerate to element-wise when at least one
+ *  operand is a scalar — env-aware callers should additionally apply
+ *  `binaryOpNeedsScalarCheck`. */
+export declare function isElemwiseBinaryOp(op: BinaryOperation): boolean;
+/** True iff `op` requires a runtime scalar-operand check before being
+ *  emitted element-wise (i.e. plain `*` and `/`). */
+export declare function binaryOpNeedsScalarCheck(op: BinaryOperation): boolean;
+/** Unary ops the element-wise codegen can emit. */
+export declare function isElemwiseUnaryOp(op: UnaryOperation): boolean;
+/** Structural check: is `e` element-wise lowerable as a tree shape?
+ *  Does NOT consult env. Leaves (`Ident`, `Number`) are accepted
+ *  unconditionally; runtime classification of identifiers (tensor vs.
+ *  scalar) is the caller's responsibility. */
+export declare function isElemwiseStructuralExpr(e: Expr): boolean;

package/dist-lib/numbl-core/executors/cJit/fuseAnalyze.d.ts

@@ -0,0 +1,39 @@
+/**
+ * c-jit-fuse — structural feasibility analysis on a single AST `Assign`.
+ *
+ * Walks the AST directly (not the JS-JIT IR — that pipeline is sized
+ * for whole-function lowering). Determines whether the RHS expression
+ * tree can be compiled to a single-pass element-wise C kernel, and
+ * extracts the tensor / scalar input identifiers in a stable order.
+ *
+ * Returns `null` when the stmt isn't a fusable shape — caller (the
+ * lowering pipeline) then leaves the stmt for the interpreter.
+ *
+ * Today's scope: real-only, plain-Ident LHS, same-shape tensor
+ * leaves. Broadcasting, complex tensors, and in-place mutation are
+ * not handled yet.
+ */
+import { type Expr, type Stmt } from "../../parser/types.js";
+import type { Environment } from "../../interpreter/types.js";
+/** Per-leaf classification: tensor, scalar (number), or literal. */
+export type LeafKind = "tensor" | "scalar";
+export interface FuseClassification {
+    /** Output variable name (LHS of the Assign). */
+    readonly outputName: string;
+    /** Tensor inputs in the order they should appear as C parameters. */
+    readonly tensorInputs: readonly string[];
+    /** Scalar inputs in the order they should appear as C parameters. */
+    readonly scalarInputs: readonly string[];
+    /** The RHS expression, kept as AST for codegen to walk. */
+    readonly rhs: Expr;
+    /** Stable cache key projected from the AST shape and per-leaf
+     *  classification. Drops sizes — those are runtime-only and live
+     *  in `propose()`. */
+    readonly cacheKey: string;
+    /** Per-name kind, used by codegen to map identifiers to either
+     *  `tN[i]` (tensor) or `sN` (scalar). */
+    readonly kindOf: ReadonlyMap<string, LeafKind>;
+}
+/** Determine whether `stmt` is a fusable Assign and, if so, return
+ *  its classification. Returns null on any structural mismatch. */
+export declare function analyzeFuse(stmt: Stmt, env: Environment): FuseClassification | null;

package/dist-lib/numbl-core/executors/cJit/fuseCodegen.d.ts

@@ -0,0 +1,16 @@
+/**
+ * c-jit-fuse codegen — single-pass element-wise C kernel.
+ *
+ * Emits one C function whose body is a single `for (long i = 0; i < n; i++)`
+ * loop with `out[i] = <fused expression>;`. The fused expression is
+ * the AST RHS, with each `Ident` mapped to either `tN[i]` (tensor)
+ * or `sN` (scalar) via `emitElemwiseExpr`'s leaf callback.
+ *
+ * ABI:
+ *   void <fnName>(double *out, long n,
+ *                 const double *t0, const double *t1, ...,
+ *                 double s0, double s1, ...);
+ */
+import type { FuseClassification } from "./fuseAnalyze.js";
+/** Emit a complete C source file for a fuse classification. */
+export declare function generateFuseCSource(fnName: string, cls: FuseClassification): string;

package/dist-lib/numbl-core/executors/cJit/fuseExecutor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * c-jit-fuse — element-wise tensor op fusion.
+ *
+ *   - `propose()` filters on `lowered.kind === "fuse"`. Reads each
+ *     tensor input's `numel` from env and verifies they all match;
+ *     declines below a per-call threshold so small tensors stay on
+ *     the interpreter path.
+ *
+ *   - `compile()` emits a single-pass C kernel, builds the koffi
+ *     declaration, calls `compileAndLoad`. Surfaces the source via
+ *     `interp.onCJitCompile` for `--dump-c`.
+ *
+ *   - `run()` gathers tensor data + scalar values, allocates an
+ *     output `Float64Array(numel)`, invokes the kernel, wraps the
+ *     output as a real `RuntimeTensor` whose shape mirrors the first
+ *     tensor input's, and writes back.
+ */
+import type { Executor } from "../types.js";
+import type { FuseLoweredStmt } from "../lowering.js";
+import { type CompiledC } from "./compile.js";
+interface CFuseCompiled {
+    readonly compiled: CompiledC;
+    readonly tensorInputs: readonly string[];
+    readonly scalarInputs: readonly string[];
+    readonly source: string;
+}
+export declare const cJitFuseExecutor: Executor<FuseLoweredStmt, CFuseCompiled | null>;
+export {};

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

@@ -0,0 +1,32 @@
+/**
+ * c-jit-loop — C codegen executor for scalar for/while loops.
+ *
+ *   - `propose()` filters on `lowered.kind === "loop"`, requires a
+ *     wired `nativeBridge`, applies the C feasibility whitelist, and
+ *     rejects loops containing IO + bail-risk.
+ *
+ *   - `compile()` generates C source from the lowered IR, caches the
+ *     compiled `.so` under `~/.cache/numbl/c-jit/<sha>.so`, and loads
+ *     via koffi.
+ *
+ *   - `run()` reads loop inputs from the interpreter env, marshals
+ *     complex values to (re, im) pairs, invokes the compiled C
+ *     function with an output Float64Array, and writes the outputs
+ *     back to env.
+ */
+import type { Executor } from "../types.js";
+import type { LoopLowered } from "../jsJit/jitLoop.js";
+import { type VarEncoding } from "./codegen.js";
+import { type CompiledC } from "./compile.js";
+interface CLoopCompiled {
+    readonly compiled: CompiledC;
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputEncodings: readonly VarEncoding[];
+    readonly outputEncodings: readonly VarEncoding[];
+    /** Total `double` slots in `out` — sum of per-output slot counts. */
+    readonly outputSlots: number;
+    readonly source: string;
+}
+export declare const cJitLoopExecutor: Executor<LoopLowered, CLoopCompiled | null>;
+export {};

package/dist-lib/numbl-core/executors/cJit/register.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Node-only entry that wires the C-JIT executors into the shared
+ * `plugins.ts` registrar slot. Importing this module for its side
+ * effect (from `cli.ts`) is what makes `--opt e3` work in the CLI.
+ *
+ * The browser worker bundle deliberately does not import this file,
+ * keeping `compile.ts` (and its `node:fs`/`node:os`/`node:child_process`
+ * imports) out of the web build's module graph.
+ */
+export {};

package/dist-lib/numbl-core/executors/cJit/whitelist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * c-jit-loop feasibility whitelist.
+ *
+ * Walks a `LoopLowered` IR body and returns true iff every node is
+ * something the C codegen can emit. Nodes outside the whitelist
+ * (tensor ops, struct field access, etc.) cause `propose()` to
+ * decline so the dispatcher falls through to the interpreter.
+ *
+ * Today's scope: scalar-only loops, real or complex (pair-of-doubles
+ * encoding). Math builtins on complex args are NOT supported except
+ * `real`, `imag`, and `conj`.
+ */
+import type { JitStmt, JitType } from "../../jitTypes.js";
+export declare function isCScalarType(t: JitType): boolean;
+export declare function isCJitFeasible(body: readonly JitStmt[]): boolean;

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

@@ -0,0 +1,26 @@
+/**
+ * Per-executor compilation cache.
+ *
+ * Keyed by (executor, owner, cacheKey). The `owner` is the object the
+ * cache entry's lifetime is tied to:
+ *   - For stmt dispatch: the head Stmt at `siblings[i]`.
+ *   - For function-call dispatch: the FunctionDef.
+ *
+ * WeakMap scoping ensures entries are reclaimed when the owner is
+ * garbage-collected (e.g., when an AST is dropped after addpath).
+ *
+ * Each registered executor gets its own slot in the cache; a single
+ * owner can host entries from multiple executors with different
+ * specializations.
+ */
+declare const BAILED: unique symbol;
+type Bailed = typeof BAILED;
+export declare class ExecutorCache {
+    /** owner → executorName → cacheKey → compiled artifact (or BAILED) */
+    private readonly slots;
+    get(executorName: string, owner: object, key: string): unknown | undefined;
+    set(executorName: string, owner: object, key: string, compiled: unknown): void;
+    markBailed(executorName: string, owner: object, key: string): void;
+    isBailed(value: unknown): value is Bailed;
+}
+export {};

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

@@ -0,0 +1,76 @@
+/**
+ * Dispatch context — passed to every executor call.
+ *
+ * Provides env access, type-info queries, sub-dispatch into the
+ * registry, and runtime callbacks. Memoizes type-info lookups for the
+ * lifetime of a single dispatch so repeated `typeOf(name)` calls from
+ * different executors don't re-infer.
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
+import type { ControlSignal } from "../interpreter/types.js";
+import type { Registry } from "./registry.js";
+import { type JitType } from "../jitTypes.js";
+export declare class DispatchContext {
+    readonly interp: Interpreter;
+    readonly registry: Registry;
+    /** When true, only no-bail executors are eligible. Set when the
+     *  caller's compiled artifact has emitted observable side effects
+     *  that mustn't repeat. */
+    readonly requireNoBail: boolean;
+    /** Per-dispatch memoization of typeOf(name) lookups. */
+    private readonly typeCache;
+    /** Re-entrancy guard: which executors are currently running on
+     *  which head stmts. Prevents an executor sub-dispatching back into
+     *  itself on the same stmt. */
+    private readonly active;
+    /** Sibling list and head index for the current dispatch. Set by
+     *  Registry.dispatch before calling executors; read by peekSibling.
+     *  Most executors don't read these directly. */
+    private _siblings;
+    private _i;
+    constructor(interp: Interpreter, registry: Registry, requireNoBail: boolean, active?: Set<string>);
+    /** Look up a name's JitType from the interpreter env, memoized. */
+    typeOf(name: string): JitType;
+    /** Read a value from env (no inference). Returns undefined if unbound. */
+    envValue(name: string): unknown;
+    /** Peek at a sibling stmt at `offset` from the current head.
+     *  offset=0 is the current stmt; positive values look ahead.
+     *  Returns null if the offset is past the end of the scope. Used by
+     *  chain-style executors that may consume multiple consecutive
+     *  stmts. */
+    peekSibling(offset: number): Stmt | null;
+    /** Sibling list of the current scope. The head stmt is at
+     *  `siblings[headIndex]`. Most executors don't need this directly —
+     *  use `peekSibling(offset)` for lookahead. The rare cases that
+     *  forward the raw list to a legacy adapter (the chain executor) or
+     *  claim the whole scope (the top-level executor) read these. */
+    get siblings(): readonly Stmt[];
+    get headIndex(): number;
+    /** @internal Set the position state for an upcoming dispatch. Only
+     *  the registry calls this. */
+    _setPosition(siblings: readonly Stmt[], i: number): void;
+    /** Reset per-dispatch state so this context can be reused for the
+     *  next stmt in a sibling loop. The reentrancy guard is expected to
+     *  already be empty (every pushActive is paired with a popActive in
+     *  Registry.runCandidate's finally). */
+    resetForNextDispatch(): void;
+    /** Construct a child context for sub-dispatch. `requireNoBail` is
+     *  the OR of the parent flag and the parent executor's
+     *  `requireNoBailInChildren` declaration. */
+    childContext(requireNoBail: boolean): DispatchContext;
+    /** @internal Whether the reentrancy guard has any entries. The
+     *  registry uses this to skip the guard check on the hot path —
+     *  when nothing is active there's nothing to detect. */
+    get hasActive(): boolean;
+    /** @internal Used by the registry's reentrancy guard. Pre-checked
+     *  with hasActive on the hot path, so the actual `has` only fires
+     *  during sub-dispatch. */
+    isActive(executorName: string, stmt: Stmt): boolean;
+    /** @internal */
+    pushActive(executorName: string, stmt: Stmt): void;
+    /** @internal */
+    popActive(executorName: string, stmt: Stmt): void;
+}
+/** Re-export for the runner's signal type. */
+export type { ControlSignal };

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

@@ -0,0 +1,17 @@
+/**
+ * Executor registry — public surface.
+ *
+ * See docs/developer_reference/executors.md for the design.
+ */
+export type { Executor, CostEstimate, BailReason, RunResult, Proposal, } from "./types.js";
+export { Registry, makeRootContext } from "./registry.js";
+export type { DispatchResult, CallDispatchResult, WholeScopeResult, } from "./registry.js";
+export { DispatchContext } from "./context.js";
+export { ExecutorCache } from "./cache.js";
+export type { JitType, SignCategory } from "../jitTypes.js";
+export { jitTypeKey, unifyJitTypes, isScalarType, isTensorType, isComplexType, isKnownInteger, } from "../jitTypes.js";
+export { inferJitType } from "../interpreter/builtins/types.js";
+export { jsJitTopLevelExecutor } from "./jsJit/topLevelExecutor.js";
+export { jsJitLoopExecutor } from "./jsJit/loopExecutor.js";
+export { jsJitCallExecutor } from "./jsJit/callExecutor.js";
+export { registerExecutorsForOpt } from "./plugins.js";

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

@@ -0,0 +1,25 @@
+/**
+ * js-jit-call — JS codegen executor for the call shape.
+ *
+ * Lowering is the dispatcher's job. The call executor receives the
+ * lowered IR (with pre-computed feasibility flags) as the first arg
+ * to propose, decides whether to commit, and produces a compiled JS
+ * artifact on commit.
+ *
+ *   - `propose()` filters on `lowered.kind === "call"`, applies
+ *     IO+bail-risk feasibility check. Returns null to decline.
+ *
+ *   - `compile()` calls `generateCallJS` against the lowered IR.
+ *     Cached by the registry under the classification's cacheKey.
+ *
+ *   - `run()` calls `runCallCompiled`. JitBailToInterpreter →
+ *     transient bail.
+ */
+import type { Executor } from "../types.js";
+import { type CallLowered, type CallCompiled } from "./jitCall.js";
+interface JsJitCallData {
+    readonly lowered: CallLowered;
+    readonly args: readonly unknown[];
+}
+export declare const jsJitCallExecutor: Executor<JsJitCallData, CallCompiled | null>;
+export {};