numbl 0.1.7 → 0.3.0

package/dist-lib/numbl-core/jit/c/visit.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Lightweight IR traversal helpers shared across the C-JIT subsystem.
+ *
+ * Several places in `jit/c/` need to walk a lowered IR body observing
+ * (but not transforming) expressions and statements: the feasibility
+ * fall-through paths, tensor-classification, hybrid-loop live-in/out
+ * analysis, and the shape-propagation / callee-discovery / complex-
+ * scalar scans in [assemble.ts](./assemble.ts). Each used to
+ * reimplement the same switch-on-tag descent.
+ *
+ * This module centralizes the descent. Three primitives, composable:
+ *
+ *   - `walkExprNodes(expr, visit)` — post-order walk of every sub-node
+ *     of `expr` (including `expr` itself). Every leaf calls `visit`
+ *     once; nothing is skipped. Adding a new JitExpr tag means editing
+ *     this one function.
+ *
+ *   - `walkStmts(body, visit)` — pre-order walk of every statement in
+ *     `body`, recursing into If/For/While nested bodies. Does NOT
+ *     traverse expressions inside the stmt — callers that need that
+ *     compose with `walkStmtExprs` + `walkExprNodes`.
+ *
+ *   - `walkStmtExprs(stmt, visit)` — call `visit` on each top-level
+ *     expression attached to `stmt` (the `expr` in an Assign, the
+ *     `cond` in an If, the `start`/`end`/`step` in a For, etc.). Does
+ *     NOT recurse into nested expression sub-nodes (use `walkExprNodes`
+ *     for that) and does NOT walk into nested stmt bodies.
+ *
+ * The dispatchers in `feasibility.ts`, `emit/stmt.ts`, and
+ * `emit/fused.ts` keep their native switches — they produce structured
+ * results (feasibility verdicts, emitted C lines), so a callback-based
+ * observer doesn't fit their shape.
+ */
+import type { JitExpr, JitStmt } from "../jitTypes.js";
+/**
+ * Walk every sub-node of `expr` in post-order (children first, then
+ * `expr` itself), calling `visit` on each. Leaves (NumberLiteral,
+ * ImagLiteral, Var, StringLiteral, MemberRead) are still visited once.
+ *
+ * Adding a new JitExpr tag: add a case here. Observer callers (which
+ * is all of them) don't need to know about tag-specific sub-node
+ * fields — this is the one place those are encoded.
+ */
+export declare function walkExprNodes(expr: JitExpr, visit: (e: JitExpr) => void): void;
+/**
+ * Walk every statement in `body`, recursing into nested If / For /
+ * While bodies. Pre-order: `visit` is called on each stmt before
+ * descending. Does NOT traverse expressions inside the stmt.
+ */
+export declare function walkStmts(body: JitStmt[], visit: (s: JitStmt) => void): void;
+/**
+ * Call `visit` on every top-level expression attached to `stmt` — the
+ * RHS of an Assign, the indices + value of an AssignIndex, the start /
+ * end / step of a For, the cond of an If / While, and so on. Does
+ * NOT recurse into expression sub-nodes (compose with `walkExprNodes`)
+ * and does NOT descend into nested stmt bodies (compose with
+ * `walkStmts`).
+ *
+ * For If, the `cond` of the primary branch AND each elseif is visited;
+ * the bodies themselves are stmt-trees, not exprs, and are reached via
+ * `walkStmts` recursion.
+ */
+export declare function walkStmtExprs(stmt: JitStmt, visit: (e: JitExpr) => void): void;

package/dist-lib/numbl-core/jit/e1/complexKernelEmit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * e1 (experimental) — complex-tensor standalone C-kernel emission.
+ *
+ * Sister module to `kernelEmit.ts` (which handles real-tensor chains).
+ * Given a FusibleChain that produces at least one complex tensor, emit
+ * a paired-buffer C kernel of the form
+ *
+ *   void k_<hash>(int64_t n,
+ *                 const double *in_<a>_re, const double *in_<a>_im,  // complex tensor
+ *                 const double *in_<b>,                              // real tensor (widened)
+ *                 double s_<c>_re, double s_<c>_im,                  // complex scalar
+ *                 double s_<d>,                                      // real scalar
+ *                 double *out_<y>_re, double *out_<y>_im)            // complex output
+ *   {
+ *       #pragma omp simd
+ *       for (int64_t i = 0; i < n; i++) {
+ *           double __f_y_re = ...;
+ *           double __f_y_im = ...;
+ *           out_<y>_re[i] = __f_y_re;
+ *           out_<y>_im[i] = __f_y_im;
+ *       }
+ *   }
+ *
+ * Supports the same fusion envelope as emitComplexPerElem in
+ * `c/emit/fused.ts`:
+ *   - Binary: + - * .*
+ *   - Unary: + -
+ *   - Call: conj, real, imag
+ *   - Operand widening: real tensor / real scalar read with im = 0
+ *   - ImagLiteral: (0.0, 1.0) pair
+ *
+ * Complex chains do NOT carry a trailing reduction — `fusion.ts` drops
+ * the absorption for complex chains because the inline scalar
+ * accumulator can't hold a complex value. Kernels emitted here have no
+ * reduction output.
+ */
+import type { FusibleChain } from "../fusion.js";
+import type { KernelEmitResult } from "./kernelEmit.js";
+/**
+ * Emit a complex-tensor fused chain as a standalone C kernel.
+ *
+ * Returns null when the chain contains an expression the per-element
+ * walker doesn't support (abs, complex divide, transcendental on
+ * complex, etc.) — the caller falls back to the JS-JIT per-op path.
+ */
+export declare function emitComplexChainKernel(chain: FusibleChain, allTensorVars: ReadonlySet<string>, complexTensorNames: ReadonlySet<string>, complexScalarVars: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>): KernelEmitResult | null;

package/dist-lib/numbl-core/jit/e1/hash.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared content-hash helper for the e1 codegen.
+ *
+ * 64-bit FNV-1a over UTF-8 code units, returned as 16 hex chars.
+ * Deterministic, fully self-contained, and browser-safe (no Node
+ * `crypto` dependency). Cryptographic strength isn't needed — the
+ * hash is a content-addressed suffix for kernel names and
+ * `$h.$kernels[...]` cache keys.
+ */
+export declare function fnv1a64Hex(s: string): string;

package/dist-lib/numbl-core/jit/e1/install.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Node-only install shim for the e1 (experimental) kernel pipeline.
+ *
+ * Side-effect import from `cli.ts`. Replaces the `compileKernel` stub on
+ * the module-level `jitHelpers` object with a real implementation that
+ * shells out to `cc` via `compile.ts` and loads the result through koffi.
+ *
+ * Registration is idempotent — re-importing this module in tests won't
+ * re-install. The kernel cache on `jitHelpers.$kernels` is shared across
+ * all specializations in the process so the same fused chain used from
+ * two different JIT'd functions compiles only once.
+ */
+export {};

package/dist-lib/numbl-core/jit/e1/kernelEmit.d.ts

@@ -0,0 +1,54 @@
+/**
+ * e1 (experimental) — standalone C-kernel emission for fusible tensor
+ * chains used by the JS-JIT.
+ *
+ * Given a `FusibleChain` the normal JS fused codegen would emit, this
+ * module produces an equivalent standalone C function of the form
+ *
+ *   void k_<hash>(int64_t n,
+ *                 const double *in_<x>, ...,
+ *                 double s_<scalar>, ...,
+ *                 double *out_<y>, ...)
+ *   {
+ *       #pragma omp simd
+ *       for (int64_t i = 0; i < n; i++) {
+ *           double f_tmp1 = <expr>;
+ *           ...
+ *           out_<y>[i] = <final>;
+ *       }
+ *   }
+ *
+ * It returns the full C source, a koffi signature string, a content-
+ * addressed hash, and the ordered list of JS expressions the generated
+ * code should pass as arguments — everything the JS codegen needs to
+ * emit a `$h.compileKernel(source, sig); kernel(n, x_data, y_data)`
+ * dispatch.
+ *
+ * The prototype deliberately handles only the common real-tensor chain
+ * shape: no reductions, no complex tensors, no dynamic-shape outputs.
+ * Any chain that falls outside that envelope causes `emitChainKernel`
+ * to return `null`, which signals the caller to fall back to the plain
+ * inline JS fused loop.
+ */
+import type { FusibleChain } from "../fusion.js";
+/**
+ * A fused chain compiled to a standalone C kernel.  The caller (the JS
+ * codegen) combines this with a runtime size threshold to emit
+ *
+ *     if (n >= THRESHOLD) $h.<kernelName>(n, x_data, y_data)
+ *     else <plain JS fused loop>
+ */
+export interface KernelEmitResult {
+    /** Hash-derived C function name, e.g. `nk_3a7f81b2`. */
+    kernelName: string;
+    /** Full C source: `#include` + function definition. */
+    cSource: string;
+    /** koffi function signature, e.g. `"void nk_3a7f81b2(int64_t, ...)"`. */
+    koffiSig: string;
+    /** Content hash over the final C source (stable id for caching). */
+    hash: string;
+    /** Ordered list of JS expressions to pass as call arguments. The
+     *  caller emits something like `$h.<kernelName>(${jsCallArgs.join(",")})`. */
+    jsCallArgs: string[];
+}
+export declare function emitChainKernel(chain: FusibleChain, allTensorVars: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>, par: boolean): KernelEmitResult | null;

package/dist-lib/numbl-core/jit/e1/multiReductionKernel.d.ts

@@ -0,0 +1,66 @@
+/**
+ * e1 — C kernel for multi-reduction scalar assigns.
+ *
+ * A MATLAB line like
+ *
+ *   red_acc = red_acc + (sum(x) + mean(x) + max(x) + min(x));
+ *
+ * has four reductions over the same vector. The default JS-JIT path
+ * emits four `$h.tSum` / `$h.ib_*` helper calls, each of which scans
+ * the whole vector. This module emits a single-pass C kernel that
+ * computes every requested reduction in one loop and writes results
+ * into caller-allocated scalar slots.
+ *
+ * Specialised per op-set: a group of `{sum, max, min}` compiles to a
+ * different kernel than `{sum, mean, max, min}`. Source-addressed by
+ * FNV-1a hash so the JS `$h.$kernels[...]` cache dedupes repeated call
+ * sites.
+ *
+ * NaN handling: `-ffast-math` is on for the compile (matches the other
+ * e1 kernels), so naive `isnan` is folded to `false`. The kernel uses
+ * an inline bit-pattern NaN check to drive MATLAB's omit-NaN semantics
+ * for `max`/`min` and records an `any_non_nan` flag the JS side uses
+ * to map an all-NaN input to NaN.
+ */
+/** Reductions we can fuse into one pass. `any` / `all` are excluded
+ *  because their short-circuit `break` would prematurely stop the
+ *  other accumulators. */
+export type MultiReduceOp = "sum" | "prod" | "max" | "min" | "mean";
+export interface MultiReductionKernelInfo {
+    /** Hash-derived C function name, e.g. `mr_3a7f81b2...`. */
+    kernelName: string;
+    /** Full C source string. */
+    cSource: string;
+    /** koffi function signature. */
+    koffiSig: string;
+    /** Content hash. */
+    hash: string;
+    /**
+     * Output slot layout. Each reduction in the kernel writes to its own
+     * Float64 slot, in the order of this array. `any_non_nan` (a 0/1 flag
+     * stored as double) is at the end when `hasMinOrMax` is true.
+     * The JS caller allocates a `Float64Array(slotCount)` and reads slots
+     * by index after the call.
+     */
+    slotNames: string[];
+    /** True when the kernel emits an `any_non_nan` slot at index
+     *  `slotNames.length - 1`. */
+    hasAnyNonNan: boolean;
+}
+/**
+ * Build a multi-reduction kernel for the given op set. `ops` should be
+ * a deduplicated list of reductions to compute (e.g. ["sum", "max"]).
+ * The returned `slotNames` preserves insertion order for indexing; if
+ * the op set contains `max`/`min`, an extra `any_non_nan` slot is
+ * appended (the JS side uses it to override the sentinel max/min with
+ * NaN when every input element was NaN).
+ *
+ * When `par` is true, the per-element loop is emitted as
+ * `#pragma omp parallel for simd reduction(...)` with one reduction
+ * clause per accumulator and an `if(n >= T)` gate that falls back to
+ * serial below the threshold. Requires the caller to link with
+ * `-fopenmp`; e1's `install.ts` already does this when libgomp is
+ * available. When `par` is false, the loop is emitted as plain
+ * `#pragma omp simd` (SIMD-only, single-threaded).
+ */
+export declare function emitMultiReductionKernel(ops: readonly MultiReduceOp[], par?: boolean): MultiReductionKernelInfo;

package/dist-lib/numbl-core/jit/e1/openmpFlag.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Runtime-overridable OpenMP availability flag for the e1 codegen path.
+ *
+ * `scalarFnKernel.ts` is transitively reachable from the JS-JIT module
+ * graph that Vite bundles for the web REPL, but `c/compile.ts` is
+ * Node-only (child_process, fs, ...). Importing `cJitOpenmpAvailable`
+ * directly from `compile.ts` would drag all of that into the browser
+ * bundle. Instead we default to `false` here and let Node-only
+ * `e1/install.ts` override the getter at install time — the same
+ * pattern used for the `compileKernel` stub in `jitHelpers.ts`.
+ */
+export declare function setOpenmpAvailableGetter(fn: () => boolean): void;
+export declare function isOpenmpAvailable(): boolean;

package/dist-lib/numbl-core/jit/e1/scalarFnKernel.d.ts

@@ -0,0 +1,44 @@
+/**
+ * e1 (experimental) — whole-function scalar kernel emission.
+ *
+ * Complements [kernelEmit.ts](./kernelEmit.ts) (which handles tensor
+ * fusible chains) by covering the other big win case: a user function
+ * that is entirely scalar arithmetic — e.g. the inner loop of a
+ * Horner-style series, a Runge-Kutta step on a handful of doubles,
+ * benchmarks/scalar_bench.m's `run_bench(N, M)`.
+ *
+ * Under `--opt e1`, when a JIT-able function's signature and body are
+ * purely scalar, we call `generateC()` (the same emitter the C-JIT
+ * uses at `--opt 2`) and wrap its output with a thin inline JS
+ * function that shells out to `$h.compileKernel(...)`. The C source
+ * and koffi signature are inlined as JS string literals, so
+ * `--dump-js` shows the complete picture.
+ *
+ * Scope for the prototype:
+ *   - All params are scalar doubles / booleans (CParamDesc.kind === "scalar")
+ *   - All outputs are scalar / boolean (COutputDesc.kind === "scalar" | "boolean")
+ *   - No tic/toc, no Index reads (no errFlag), no disp(...) calls
+ *
+ * Anything outside that envelope returns `null` and the caller falls
+ * back to the plain JS-JIT path, which still benefits from e1's
+ * per-chain tensor kernels.
+ */
+import type { FunctionDef } from "../../interpreter/types.js";
+import type { JitStmt, JitType } from "../jitTypes.js";
+import type { GeneratedFn } from "../jitLower.js";
+import type { Interpreter } from "../../interpreter/interpreter.js";
+export interface ScalarFnKernelResult {
+    /** The inline-compileKernel JS source. The JIT caller splices this
+     *  in place of the normal JS-JIT body. */
+    jsSource: string;
+    /** Content-addressed kernel name from generateC, for logging. */
+    kernelName: string;
+    /** Raw C source (also embedded in `jsSource` as a string literal).
+     *  Exposed for `--dump-c` / logging. */
+    cSource: string;
+}
+/**
+ * Try to emit a whole-function scalar kernel for the given lowered IR.
+ * Returns null when the function is not a pure-scalar candidate.
+ */
+export declare function tryEmitScalarFnKernel(interp: Interpreter, fn: FunctionDef, body: JitStmt[], outputNames: string[], localVars: Set<string>, outputType: JitType | null, outputTypes: JitType[], argTypes: JitType[], nargout: number, generatedIRBodies: Map<string, GeneratedFn>): ScalarFnKernelResult | null;

package/dist-lib/numbl-core/jit/e2/assignKernel.d.ts

@@ -0,0 +1,34 @@
+/**
+ * e2 — per-assign / chain kernel driver.
+ *
+ * Entry point `tryE2Assign` is called from `interpreterExec.ts` for
+ * every `Assign` statement when `interp.experimental === "e2"`.
+ *
+ * Multi-LHS chain detection: scans consecutive suppressed Assigns
+ * regardless of LHS name. For each chain LHS, uses scope-body liveness
+ * (via `interp._currentScopeBody`) to decide whether the LHS escapes
+ * (materializes as an `out_<name>` buffer) or is purely chain-local
+ * (kept as a per-element stack-local). Reads of a chain LHS before
+ * its first assign in the chain become `in_<name>` parameters.
+ *
+ * On success:
+ *   - Single chain assign: handled like a one-stmt chain.
+ *   - Multi-stmt chain: one C kernel runs all assigns, only escape
+ *     LHSs materialize back to env. `interp._e2ChainAdvance` is set
+ *     so the surrounding loop skips the consumed sibling stmts.
+ *
+ * Compilation failures are hard errors (RuntimeError). Classification
+ * bails (non-classifiable RHS, mismatched lengths, etc.) silently fall
+ * through to the regular interpreter path.
+ */
+import type { Stmt } from "../../parser/types.js";
+import type { Interpreter } from "../../interpreter/interpreter.js";
+/**
+ * Try to compile a chain (1+ stmts) starting at `stmt`. Returns true
+ * on success — `interp._e2ChainAdvance` is set to the count of EXTRA
+ * sibling stmts the kernel consumed (0 for a single-stmt chain).
+ * Returns false to fall back to the regular interpreter path.
+ */
+export declare function tryE2Assign(interp: Interpreter, stmt: Stmt & {
+    type: "Assign";
+}): boolean;

package/dist-lib/numbl-core/jit/e2/astToJitExpr.d.ts

@@ -0,0 +1,25 @@
+/**
+ * e2 — minimal AST `Expr` → `JitExpr` lowerer.
+ *
+ * Only handles the whitelist that `classify.ts` accepts: Number, Ident,
+ * whitelisted Binary/Unary, whitelisted FuncCall. Types are read from
+ * the live runtime environment (the caller passes in a per-name
+ * `JitType` lookup), so there's no cross-branch unification.
+ *
+ * The classifier already replaced opaque subtrees with synthetic Ident
+ * nodes whose `name` is also in `envTypes`, so this lowerer doesn't need
+ * to know about opacity — every Ident it sees has a known runtime type.
+ */
+import type { Expr } from "../../parser/types.js";
+import type { JitExpr, JitType } from "../jitTypes.js";
+export declare class E2LowerError extends Error {
+}
+export interface LowerOptions {
+    /** When a `FuncCall{name, args}` has `name` in `envTypes` as a tensor,
+     *  treat it as tensor indexing and lower to an `Index` node instead
+     *  of looking up a builtin. Used by the e2 whole-loop kernel — the
+     *  chain emitters don't set this (their classifier has already
+     *  marked tensor-access FuncCalls as opaque). */
+    resolveFuncCallAsTensorIndex?: boolean;
+}
+export declare function lowerAstToJitExpr(expr: Expr, envTypes: ReadonlyMap<string, JitType>, options?: LowerOptions): JitExpr;

package/dist-lib/numbl-core/jit/e2/cache.d.ts

@@ -0,0 +1,80 @@
+/**
+ * e2 — per-AST-node compiled-kernel cache.
+ *
+ * Each AST `Expr` (the RHS of an `Assign` we've seen at least once) maps
+ * to a per-signature cache: the same expression visited with a different
+ * runtime type signature produces a different specialization. The
+ * signature includes input names, scalar-vs-tensor, complex-or-not, and
+ * the LHS name (since the kernel hard-codes which output to write).
+ *
+ * The Map is keyed by the AST node identity, not by source text — two
+ * identical-looking `r = r .* y` statements at different file:line
+ * positions get separate cache entries, so a recompile from a
+ * different call-site doesn't poison earlier ones.
+ *
+ * The cache holds either an `E2CacheEntry` or the `E2_BAILED` sentinel
+ * indicating that classification or compilation failed for this
+ * signature; the sentinel prevents re-attempting the same hopeless
+ * lowering on every invocation.
+ */
+import type { Stmt, BinaryOperation } from "../../parser/types.js";
+export type CompiledKernelFn = (...args: unknown[]) => unknown;
+export declare const E2_BAILED: unique symbol;
+export interface E2ReductionInfo {
+    /** Reduction op name (sum / prod / max / min / mean / any / all). */
+    reduceName: string;
+    /** Accumulator variable name in env. */
+    accName: string;
+    /** When true, the source pattern was `acc = acc OP reduce(...)`;
+     *  the driver applies the same OP to combine the kernel's scalar
+     *  output with the existing env value of `acc`. When false, the
+     *  source pattern was `acc = reduce(...)` and the kernel output is
+     *  written directly. */
+    hasAccumulate: boolean;
+    /** Only meaningful when `hasAccumulate` is true. */
+    accOp?: BinaryOperation;
+}
+/** Complex-path partitioning info. Present iff the kernel was compiled
+ *  via the paired-buffer complex emitter. The driver uses these lists
+ *  to marshal complex tensors (two pointers per tensor), complex
+ *  scalars (two doubles per scalar), and to allocate complex output
+ *  buffers (data + imag Float64Arrays). */
+export interface E2ComplexInfo {
+    complexTensorNames: string[];
+    realTensorNames: string[];
+    complexInputLhsNames: string[];
+    realInputLhsNames: string[];
+    complexScalarNames: string[];
+    realScalarNames: string[];
+    complexEscapeLhsNames: string[];
+    realEscapeLhsNames: string[];
+}
+export interface E2CacheEntry {
+    fn: CompiledKernelFn;
+    /** Env tensor input names (combined — for diagnostics). When
+     *  `complex` is defined, the complex marshaling code uses
+     *  `complex.complexTensorNames` and `complex.realTensorNames`
+     *  instead of this. */
+    tensorNames: string[];
+    /** Chain LHS names that need `in_<name>` (between tensors and scalars). */
+    inputLhsNames: string[];
+    /** Ordered scalar input names. */
+    scalarNames: string[];
+    /** Chain LHS names that materialize via `out_<name>` (escape names). */
+    escapeLhsNames: string[];
+    /** Number of chain assigns this entry encodes (0 for a standalone
+     *  reduction kernel, 1 for a single-assign chain kernel, >=2 for
+     *  multi-stmt chains). */
+    chainLength: number;
+    /** Set when the kernel produces a trailing scalar reduction output.
+     *  The driver allocates a `Float64Array(1)` for `out_acc`, calls the
+     *  kernel, then combines the result with `env[accName]` per the
+     *  `accOp` and `hasAccumulate` fields. Complex chains never set this
+     *  — the complex emitter rejects trailing reductions. */
+    reduction?: E2ReductionInfo;
+    /** Paired-buffer complex path info. When set, the marshaling code
+     *  takes the complex branch. */
+    complex?: E2ComplexInfo;
+}
+export declare function chainCacheGet(firstStmt: Stmt, sig: string): E2CacheEntry | typeof E2_BAILED | undefined;
+export declare function chainCacheSet(firstStmt: Stmt, sig: string, entry: E2CacheEntry | typeof E2_BAILED): void;

package/dist-lib/numbl-core/jit/e2/chainKernelEmit.d.ts

@@ -0,0 +1,55 @@
+/**
+ * e2 — multi-LHS fused chain C kernel emission.
+ *
+ * Given a sequence of `JitExpr` RHSs each writing to a (possibly
+ * distinct) chain LHS, produces one C function that runs every assign
+ * in a single per-element loop. Each chain LHS becomes a stack-local
+ * `double <name>` declared once at the top of the loop body. Within
+ * the body, references to a chain-LHS name resolve to the stack-local
+ * once the corresponding assign has run; before that point they
+ * resolve to `in_<name>[i]` (so the kernel signature includes
+ * `in_<lhsName>` for any chain LHS that's read before being written).
+ *
+ * After the per-iter assigns, every "escape" LHS (one that's actually
+ * referenced by the rest of the function body) gets written to its
+ * `out_<name>[i]` pointer. Chain-locals (only used inside the chain)
+ * are dropped at the end of the iteration with no buffer materialized.
+ *
+ *     void e2c_<hash>(int64_t n,
+ *                     const double *in_<input1>, ...,
+ *                     [const double *in_<lhs_needing_input>, ...,]
+ *                     double s_<scalar1>, ...,
+ *                     double *out_<escape_lhs1>, ...)
+ *     {
+ *         #pragma omp simd
+ *         for (int64_t i = 0; i < n; i++) {
+ *             double <chain_lhs1>, <chain_lhs2>, ...;
+ *             <chain_lhs1> = <stmt0_rhs_C>;
+ *             <chain_lhs2> = <stmt1_rhs_C>;
+ *             ...
+ *             out_<escape_lhs1>[i] = <escape_lhs1>;
+ *             out_<escape_lhs2>[i] = <escape_lhs2>;
+ *         }
+ *     }
+ */
+import { type ChainAssignSpec, type KernelInputs } from "./emitShared.js";
+export type { ChainAssignSpec } from "./emitShared.js";
+export interface E2ChainEmitResult {
+    kernelName: string;
+    cSource: string;
+    koffiSig: string;
+    hash: string;
+    /** Tensor input names in signature order — does NOT include any
+     *  in_<lhs> entries. */
+    inputTensors: string[];
+    /** Chain LHS names that appear as `in_<name>` in the signature, in
+     *  order. */
+    inputLhsNames: string[];
+    /** Scalar input names in signature order. */
+    inputScalars: string[];
+    /** Chain LHS names that appear as `out_<name>` in the signature,
+     *  in order. */
+    escapeLhsNames: string[];
+    chainLength: number;
+}
+export declare function emitE2ChainKernel(assigns: ChainAssignSpec[], inputs: KernelInputs, par?: boolean): E2ChainEmitResult;

package/dist-lib/numbl-core/jit/e2/classify.d.ts

@@ -0,0 +1,119 @@
+/**
+ * e2 (experimental) — per-assign expression classifier.
+ *
+ * Walks an AST `Expr` and decides whether it can be compiled into a
+ * single per-element C kernel. The classifier never evaluates anything
+ * — it only inspects the AST shape and the names referenced.
+ *
+ * Whitelist:
+ *   - Number, Ident
+ *   - Binary with arithmetic / comparison ops
+ *   - Unary Plus, Minus, Not
+ *   - FuncCall to a whitelisted scalar math builtin
+ *
+ * Anything outside the whitelist is recorded as an "opaque root": the
+ * driver is expected to evaluate that subtree via the interpreter and
+ * bind the result to a fresh synthetic name, then re-classify with that
+ * name in scope.
+ *
+ * The classifier returns a list of opaque-root subtrees and the
+ * "rewritten" expression that uses synthetic names where the opaque
+ * roots used to be. The driver is responsible for runtime type checks
+ * and for actually evaluating the opaque subtrees.
+ */
+import type { Expr } from "../../parser/types.js";
+import { BinaryOperation } from "../../parser/types.js";
+export { BinaryOperation } from "../../parser/types.js";
+/** Scalar math builtins that map cleanly to C99. Mirrors the JS-JIT
+ *  Math.* table plus pow / hypot / atan2 / etc. */
+export declare const E2_BUILTIN_WHITELIST: ReadonlySet<string>;
+/** One opaque subtree the driver must evaluate before invoking the
+ *  kernel. The classifier replaces it in `emittableExpr` with an Ident
+ *  named `syntheticName`. */
+export interface OpaqueRoot {
+    syntheticName: string;
+    expr: Expr;
+}
+export interface ClassifyResult {
+    /** AST with opaque subtrees replaced by Ident(syntheticName) nodes. */
+    emittableExpr: Expr;
+    /** Subtrees the driver must evaluate via the interpreter. */
+    opaqueRoots: OpaqueRoot[];
+    /** Identifiers referenced in `emittableExpr` that originated from the
+     *  user's environment (i.e. NOT synthetic opaque-root bindings). The
+     *  driver looks these up in the env to determine input types. */
+    envIdents: Set<string>;
+}
+/** Classify an expression. Always succeeds — the worst case is the
+ *  whole expression becomes a single opaque root, which the driver
+ *  will reject. */
+export declare function classifyExpr(expr: Expr): ClassifyResult;
+/** Heuristic gate: an expression is "worth" JIT'ing only when it does
+ *  some work — a bare Ident or Number is not. The driver also gates
+ *  on tensor size at runtime; this is just a structural pre-filter to
+ *  skip the cost of lowering trivial expressions. */
+export declare function isWorthCompiling(emittableExpr: Expr): boolean;
+/** A single classification entry for one assign in a chain. The chain
+ *  emitter consumes one of these per assign in order. */
+export interface ChainAssignClassification {
+    /** The original AST stmt (kept so the cache can key on it). */
+    stmt: import("../../parser/types.js").Stmt & {
+        type: "Assign";
+    };
+    /** The classifier's rewritten RHS — opaque subtrees replaced by
+     *  Ident(syntheticName). */
+    emittableExpr: Expr;
+    /** Opaque subtrees this assign contributed (driver evaluates these
+     *  before the kernel call). */
+    opaqueRoots: OpaqueRoot[];
+    /** Identifiers referenced by this assign's emittableExpr. Includes
+     *  synthetic opaque-root names. */
+    envIdents: Set<string>;
+    /** True if the assign reads its own LHS (e.g. `r = r + x`). For the
+     *  first stmt of a chain this means the kernel needs `in_<lhs>` as
+     *  an input pointer; for later stmts it just means a chain-local
+     *  read. */
+    selfReadsLhs: boolean;
+}
+export interface ChainClassification {
+    /** Chain assigns, in source order. May have multiple distinct LHSs. */
+    assigns: ChainAssignClassification[];
+}
+/** Detect a chain of consecutive suppressed classifiable Assigns
+ *  starting at `stmts[startIdx]`. Each LHS may be a different name;
+ *  the driver decides — using full-scope liveness — whether each LHS
+ *  becomes a chain-local or a materialized output buffer.
+ *
+ *  The chain ends at the first non-Assign, the first unsuppressed
+ *  Assign, or the first Assign whose RHS classification is not worth
+ *  compiling.
+ *
+ *  Returns null if the very first stmt isn't a chainable Assign. */
+export declare function classifyAssignChain(stmts: import("../../parser/types.js").Stmt[], startIdx: number): ChainClassification | null;
+/** Reduction op names whose semantics the e2 reduction emitter knows. */
+export declare const E2_REDUCTION_OPS: ReadonlySet<string>;
+export interface TrailingReductionMatch {
+    /** The original Assign stmt — pinned for cache identity. */
+    stmt: import("../../parser/types.js").Stmt & {
+        type: "Assign";
+    };
+    /** LHS = accumulator name. */
+    accName: string;
+    /** Reduction op name. */
+    reduceName: string;
+    /** AST expression argument to the reduction call. The driver decides
+     *  whether to treat it as a Var-targeting-chain-local (for trailing-
+     *  after-chain) or as a standalone elemwise expression. */
+    targetExpr: Expr;
+    /** True for `acc = acc OP reduce(...)`; false for `acc = reduce(...)`. */
+    hasAccumulate: boolean;
+    /** The accumulate op (only meaningful when `hasAccumulate` is true). */
+    accOp?: BinaryOperation;
+}
+/** Match an Assign of the form:
+ *    acc = reduce(arg)
+ *    acc = acc OP reduce(arg)
+ *    acc = reduce(arg) OP acc        (commutative ops only)
+ *  where `reduce` is a single-argument call to a known reduction op.
+ *  Returns the matched details or null. */
+export declare function matchTrailingReduction(stmt: import("../../parser/types.js").Stmt): TrailingReductionMatch | null;

package/dist-lib/numbl-core/jit/e2/compileFn.d.ts

@@ -0,0 +1,16 @@
+/**
+ * e2 — browser-safe indirection for the C compile driver.
+ *
+ * The driver in `c/compile.ts` is Node-only (it shells out to `cc` and
+ * loads via koffi). The browser bundle includes the e2 modules but
+ * NOT this driver — `setE2CompileFn` from `e2/install.ts` (Node only)
+ * swaps in the real implementation. In the browser, the stub throws.
+ */
+export type E2CompileFn = (cSource: string, koffiSig: string, kernelName: string, log?: (msg: string) => void) => ((...args: unknown[]) => unknown) | null;
+export declare function setE2CompileFn(fn: E2CompileFn): void;
+export declare function getE2CompileFn(): E2CompileFn;
+/** Minimum element count of the largest tensor input before we'll
+ *  consider compiling an e2 kernel. Below this, koffi overhead dwarfs
+ *  the work and falling through to the interpreter is faster.
+ *  Overridable via `NUMBL_E2_MIN_ELEMS`. */
+export declare function e2MinElems(): number;