numbl 0.2.0 → 0.3.0

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 the C-JIT compiles a function, with a description and the generated C. */
-    onCJitCompile?: (description: string, cSource: 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;
     /** Initial hold state for plotting (persisted across REPL executions). */
     initialHoldState?: boolean;
     /** Override or add builtins for this execution only. */
@@ -43,16 +43,8 @@ export interface ExecOptions {
      * `optimization` is still the base level (typically 1).
      */
     experimental?: string;
-    /** Emit fused per-element loops in C-JIT (requires --opt 2). */
-    fuse?: boolean;
     /** Parallelize fused loops with OpenMP threads (--par flag). */
     par?: boolean;
-    /**
-     * Diagnostic mode (`--check-c-jit-parity`, only meaningful with `--opt 2`):
-     * throw on any C-JIT miss where JS-JIT would have compiled. Lets us
-     * enumerate parity gaps as hard errors rather than silent fallbacks.
-     */
-    checkCJitParity?: 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.
@@ -93,6 +85,7 @@ export interface ProfileData {
 export interface ExecResult {
     output: string[];
     generatedJS: string;
+    /** Concatenated C-kernel source for all e2 compilations during the run. */
     generatedC: string;
     plotInstructions: PlotInstruction[];
     returnValue: RuntimeValue;

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

@@ -62,6 +62,8 @@ export interface FileIOAdapter {
     unzip?(zipfilename: string, outputfolder: string): string[];
     /** Return the temporary directory path. Optional. */
     tempdir?(): string;
+    /** Return the numbl user/config directory path. Optional. */
+    userpath?(): string;
     /** List directory entries. Returns array of {name, folder, bytes, isdir, mtimeMs}. Optional. */
     listDir?(dirPath: string): {
         name: string;

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

@@ -53,49 +53,53 @@ export declare class Interpreter {
         fn: (...args: unknown[]) => unknown;
         source: string;
     } | null>;
-    /** @internal Per-instance cache for C-JIT-compiled loops (parallel to loopJitCache). */
-    loopCJitCache: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-    } | null>;
     /** @internal Progressive type widening for loop JIT: location -> last unified input types. */
     loopLastInputTypes: Map<string, import("../jit/jitTypes.js").JitType[]>;
     /** @internal Sibling stmts of the currently-executing stmt (set by execStmts). */
     _postSiblings: import("../parser/types.js").Stmt[] | null;
     /** @internal Index in _postSiblings of the next stmt after the current one. */
     _postSiblingsIdx: number;
+    /** @internal Number of EXTRA sibling stmts that the current execStmt
+     *  consumed beyond the one passed in. The surrounding sibling loop
+     *  reads this after each execStmt and advances its index by this
+     *  many. Used by `--opt e2` chain fusion to atomically execute a run
+     *  of consecutive Assigns as one C kernel. The interpreter must
+     *  reset this to 0 before each execStmt call. */
+    _e2ChainAdvance: number;
+    /** @internal The stmt list of the innermost enclosing function body
+     *  (or top-level script body). Used by `--opt e2` chain liveness
+     *  analysis to decide whether a chain LHS is actually referenced
+     *  outside the chain — if not, the LHS becomes a per-element stack-
+     *  local rather than a materialized output buffer. Pushed on call
+     *  frame entry, popped on exit. */
+    _currentScopeBody: import("../parser/types.js").Stmt[] | null;
+    /** @internal Names that "escape" the current scope regardless of
+     *  textual usage. For functions: the declared output names (plus
+     *  `varargout`). For top-level scripts: `null`, meaning every name
+     *  escapes (the surrounding caller can read all script-level vars
+     *  via `result.variableValues`). Pushed/popped alongside
+     *  `_currentScopeBody`. */
+    _currentScopeExports: Set<string> | null;
     /**
      * Optimization level:
      *   0 — pure AST interpreter, no JIT.
      *   1 — JS-JIT (default): type-specialize hot functions/loops to JS via `new Function()`.
-     *   2 — C-JIT: additionally emit C for feasible scalar specializations,
-     *       compile to a native `.node` module, and invoke via N-API.
-     *       Infeasible IR transparently falls back to the JS-JIT path.
      */
     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. Undefined for the standard `--opt <n>` path.
+     * Experimental opt variant selector — e.g. `"e1"` for the mode that
+     * keeps JS-JIT as the outer and emits on-demand C kernels for fusible
+     * tensor chains and pure-scalar user functions. Undefined for the
+     * standard `--opt <n>` path.
      */
     experimental?: string;
-    /** Emit fused per-element loops in C-JIT (--fuse flag). */
-    fuse: boolean;
     /** Parallelize fused loops with OpenMP threads (--par flag). */
     par: boolean;
-    /**
-     * Diagnostic mode (`--check-c-jit-parity`, only meaningful with `--opt 2`).
-     * When set, any C-JIT miss where JS-JIT would have compiled throws a
-     * `CJitParityError` instead of silently falling back — surfacing parity
-     * gaps as a punch list of features to implement in the C-JIT. Env
-     * failures (missing `cc`, compile failure) also throw, since the user
-     * explicitly asked to audit C-JIT coverage.
-     */
-    checkCJitParity: boolean;
     /** Callback for JIT compilation logging (JS codegen). */
     onJitCompile?: (description: string, jsCode: string) => void;
-    /** Callback for C-JIT compilation logging (--dump-c). */
-    onCJitCompile?: (description: string, cSource: string) => void;
-    /** Verbose log sink (plumbed from ExecOptions.log; used by C-JIT for diagnostics). */
+    /** Callback for C-kernel compilation logging (--opt e2 / --dump-c). */
+    onCCompile?: (description: string, cCode: string) => void;
+    /** Verbose log sink (plumbed from ExecOptions.log). */
     log?: (message: string) => void;
     constructor(rt: Runtime, ctx: LoweringContext, functionIndex: FunctionIndex, mainFileName: string, initialVariableValues?: Record<string, RuntimeValue>);
     /** Clear all JIT and function resolution caches. Called after addpath/rmpath. */

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/kernelEmit.d.ts

@@ -51,4 +51,4 @@ export interface KernelEmitResult {
      *  caller emits something like `$h.<kernelName>(${jsCallArgs.join(",")})`. */
     jsCallArgs: string[];
 }
-export declare function emitChainKernel(chain: FusibleChain, allTensorVars: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>): KernelEmitResult | null;
+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/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;