numbl 0.1.6 → 0.2.0

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

@@ -0,0 +1,15 @@
+/**
+ * Installs the C-JIT backend (koffi path). Side-effect import only.
+ *
+ * Must be imported exactly once from a Node-only entry point (currently
+ * src/cli.ts). The browser bundle never reaches this file, so the
+ * Node-only dependencies stay out of the web build.
+ *
+ * The JS wrapper handles:
+ *   - Extracting .data (Float64Array) and .data.length from RuntimeTensor args
+ *   - Pre-allocating output buffers (Float64Array for tensor outputs,
+ *     Float64Array(1) for scalar out-pointers)
+ *   - Buffer reuse for tensor outputs (same logic as jitHelpersTensor.ts)
+ *   - Wrapping results back into RuntimeTensor objects
+ */
+export {};

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

@@ -0,0 +1,26 @@
+/**
+ * Thrown under `--check-c-jit-parity` when the C-JIT declines to compile
+ * a function/loop whose IR the JS-JIT would have accepted. The message
+ * names the construct (from the feasibility checker) and the call site,
+ * giving us an actionable punch list of features to implement in the
+ * C-JIT so parity with JS-JIT holds.
+ */
+export declare class CJitParityError extends Error {
+    readonly reason: string;
+    readonly kind: "infeasible" | "env";
+    constructor(message: string, reason: string, kind: "infeasible" | "env");
+}
+/**
+ * Build a one-line parity-error message with the offending construct,
+ * the call site (function/loop name + file:line), and the arg-type
+ * signature that triggered the specialization.
+ */
+export declare function formatCJitParityMessage(opts: {
+    kind: "infeasible" | "env";
+    reason: string;
+    reasonLine?: number;
+    siteLabel: string;
+    file: string;
+    callSiteLine: number;
+    argsDesc: string;
+}): string;

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

@@ -0,0 +1,37 @@
+/**
+ * Function prelude emission.
+ *
+ * The prelude is the set of C declarations at the top of a generated
+ * function, written before any statement from the body: shadowed param
+ * locals (for param-output seeding + unshare-at-entry), local tensor
+ * declarations, complex-scalar imag companions, and scratch buffer
+ * slots.
+ *
+ * Exported as `buildPrelude` — called once per function by `generateC`
+ * in [assemble.ts](./assemble.ts).
+ *
+ * The epilogue (tensor frees, out-pointer writes) is in
+ * [epilogue.ts](./epilogue.ts); both read from the same shared state
+ * (`ClassificationResult` + `EmitCtx`) populated upstream.
+ */
+import type { JitType } from "../jitTypes.js";
+import type { ClassificationResult } from "./classify.js";
+import { type EmitCtx } from "./context.js";
+export interface PreludeInput {
+    cls: ClassificationResult;
+    ctx: EmitCtx;
+    params: string[];
+    argTypes: JitType[];
+    /** Names with `kind === "paramOutput"` (output name reuses a param name). */
+    paramOutputTensors: Set<string>;
+    /** Pure-input tensor params that need an unshare-at-entry malloc+memcpy
+     *  (the body writes to them, and we must not mutate the caller's buffer). */
+    unshareTensorParams: Set<string>;
+    /** Locals to declare — outer-scope `localVars` minus params, sorted. */
+    allLocals: string[];
+    /** Names carrying `complex_or_number` scalar values (paired re+im locals). */
+    complexScalarVars: Set<string>;
+    /** Indent string to prepend to each emitted line. */
+    indent: string;
+}
+export declare function buildPrelude(input: PreludeInput): string[];

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

@@ -0,0 +1,51 @@
+/**
+ * Registrable hook for the C-JIT backend.
+ *
+ * The C-JIT's implementation pulls in Node-only modules (`child_process`,
+ * `fs`, `path`, ...) that would pollute the browser bundle if imported
+ * statically from [jit/index.ts](./index.ts). This module defines a
+ * thin interface + a module-level slot; the real backend is installed
+ * from the CLI entry point via [install.ts](./install.ts),
+ * which is only pulled into the Node-targeted build.
+ *
+ * When no backend is registered (e.g. browser, or someone running the
+ * library API directly) `getCJitBackend()` returns null and
+ * `tryJitCall` silently falls through to JS-JIT.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import type { JitStmt, JitType } from "../jitTypes.js";
+import type { GeneratedFn } from "../jitLower.js";
+/**
+ * Outcome of a C-JIT compile attempt.
+ *
+ * - `ok: true`: compilation succeeded; `fn` is callable.
+ * - `ok: false, kind: "infeasible"`: the lowered IR contains a construct
+ *   the C-JIT doesn't handle (JS-JIT probably would). Carries a `reason`
+ *   and optional `line` from the feasibility checker; `--check-c-jit-parity`
+ *   treats this as a hard error.
+ * - `ok: false, kind: "env"`: the environment couldn't support C-JIT
+ *   (no C compiler, compile/link failed, header missing, etc.). Also a
+ *   hard error under `--check-c-jit-parity` because the user explicitly
+ *   asked for C-JIT.
+ */
+export type CJitCompileResult = {
+    ok: true;
+    fn: (...args: unknown[]) => unknown;
+} | {
+    ok: false;
+    kind: "infeasible" | "env";
+    reason: string;
+    line?: number;
+};
+export interface CJitBackend {
+    /**
+     * Attempt to emit + compile + load a C specialization for the given
+     * lowered IR. Returns a structured result: callers distinguish
+     * `infeasible` (parity gap with JS-JIT) from `env` (missing compiler)
+     * when `--check-c-jit-parity` is on.
+     */
+    tryCompile(interp: Interpreter, fn: FunctionDef, body: JitStmt[], outputNames: string[], localVars: Set<string>, outputType: JitType | null, outputTypes: JitType[], argTypes: JitType[], nargout: number, generatedIRBodies: Map<string, GeneratedFn>): CJitCompileResult;
+}
+export declare function registerCJitBackend(b: CJitBackend): void;
+export declare function getCJitBackend(): CJitBackend | null;

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/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>): KernelEmitResult | null;

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

@@ -0,0 +1,65 @@
+/**
+ * Chain-level helpers shared by the JS and C fused-codegen backends.
+ *
+ * The per-element scalar expression walker lives in `fusedScalarEmit.ts`;
+ * this module covers the surrounding logic that decides which chain dests
+ * need a write-back to their tensor buffer, and the reduction-accumulator
+ * init/combine snippets for inline reductions.
+ *
+ * Reductions are parameterized over a small `ReductionLiterals` record so
+ * each backend supplies its own spelling of `0` vs `0.0`, `===` vs `==`,
+ * `-Infinity` vs `(-1.0/0.0)`, etc. — the control structure is identical.
+ */
+import { BinaryOperation } from "../parser/types.js";
+import type { FusibleChain } from "./fusion.js";
+/**
+ * Compute the set of distinct dest names in a fused chain and which of
+ * them require a write-back into their tensor buffer.
+ *
+ * A dest normally needs write-back; the exception is the chain's last
+ * tensor if it is fully consumed by a trailing reduction (in which case
+ * the scalar reduction accumulator is the only output — materialising
+ * the tensor buffer would be wasted work). If that last-dest tensor is
+ * ALSO a named output of the enclosing function, the write-back is kept
+ * so the caller sees the updated buffer.
+ */
+export declare function determineWriteBack(chain: FusibleChain, outputTensorNames: ReadonlySet<string>): {
+    destNames: Set<string>;
+    writeBack: Set<string>;
+    reductionConsumes: boolean;
+};
+/**
+ * Target-specific literal spellings used by the reduction helpers.
+ *
+ * The structure of the reduction snippets is identical between JS and
+ * C, but the literals differ: JS uses `1`, `-Infinity`, `===`/`!==`,
+ * while C uses `1.0`, `(-1.0/0.0)`, `==`/`!=`. The caller picks a
+ * record for its target and reuses it.
+ */
+export interface ReductionLiterals {
+    /** Additive identity (`0` for JS, `0.0` for C). */
+    zero: string;
+    /** Multiplicative identity / truthy (`1` or `1.0`). */
+    one: string;
+    /** Positive infinity literal (`Infinity` or `(1.0/0.0)`). */
+    posInf: string;
+    /** Negative infinity literal (`-Infinity` or `(-1.0/0.0)`). */
+    negInf: string;
+    /** Strict-equality operator (`===` for JS, `==` for C). */
+    eq: string;
+    /** Strict-inequality operator (`!==` for JS, `!=` for C). */
+    neq: string;
+}
+export declare const JS_REDUCTION_LITERALS: ReductionLiterals;
+export declare const C_REDUCTION_LITERALS: ReductionLiterals;
+/** Initial value expression for a reduction accumulator. */
+export declare function reductionInit(reduceName: string, lits: ReductionLiterals): string;
+/** Statement that folds a per-element `valueExpr` into the accumulator. */
+export declare function reductionCombine(reduceName: string, accVar: string, valueExpr: string, lits: ReductionLiterals): string;
+/**
+ * Statement that folds a per-chain `val` into an enclosing accumulator
+ * `dest` via the outer-loop op (e.g. `ir_acc = ir_acc + sum(...)`).
+ *
+ * Target-neutral: `+=` / `-=` / `*=` have identical syntax in JS and C.
+ */
+export declare function accumulateOp(op: BinaryOperation, dest: string, val: string): string;

package/dist-lib/numbl-core/jit/fusedScalarEmit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Shared per-element scalar-expression emission for fused loops.
+ *
+ * Both the JS-JIT and C-JIT fused-chain emitters walk the chain's
+ * expression trees and emit each sub-expression in "per-element"
+ * form — tensor Vars become `data[__i]` reads (or a scalar local for
+ * chain-produced intermediates), Binary/Unary/Call map to scalar
+ * operations that will run once per element of the fused loop.
+ *
+ * The walk itself is identical between the two backends; only the
+ * leaf syntax differs (JS `Math.sin` vs C `sin`, integer literal
+ * formatting, mangling prefix). A backend supplies a `FusedTarget`
+ * describing those leaves and a value-form `ScalarOpTarget` for the
+ * arithmetic/comparison/logical switches.
+ *
+ * Note: the op target used here must emit comparison / logical ops
+ * in *numeric* form (result is a double 0.0/1.0 suitable for tensor
+ * write-back). For C this coincides with the regular value target;
+ * for JS a second target instance is needed because value-form
+ * comparisons return a JS boolean.
+ */
+import type { JitExpr } from "./jitTypes.js";
+import type { FusibleChain } from "./fusion.js";
+import { type ScalarOpTarget } from "./scalarEmit.js";
+/** Scalar local name for a chain-produced tensor intermediate. */
+export declare function fusedLocal(name: string): string;
+export interface FusedTarget {
+    /** Format a numeric literal (e.g. `1` for JS, `1.0` for C). */
+    formatNumber(v: number): string;
+    /** Mangle a scalar variable reference (non-tensor). */
+    mangle(name: string): string;
+    /**
+     * Emit a per-element read of tensor var `name` — i.e. the expression
+     * that yields `data[__i]` for that tensor. The backend decides how
+     * the data pointer is named and whether it's aliased locally.
+     */
+    tensorElemRead(name: string): string;
+    /**
+     * Emit a call to a scalar math builtin. The backend decides which
+     * builtins it supports and how they map to library functions (e.g.
+     * JS `Math.sin` vs C `sin`). Return `null` to reject.
+     *
+     * `name` is the builtin name (e.g. `"sin"`, `"mod"`, `"rem"`);
+     * `args` are already-emitted per-element scalar expressions.
+     */
+    emitBuiltinCall(name: string, args: string[]): string | null;
+}
+/** Shared walker: emit a JitExpr as a per-element scalar expression. */
+export declare function emitFusedScalarExpr(expr: JitExpr, chainLocals: ReadonlySet<string>, allTensorVars: ReadonlySet<string>, opTarget: ScalarOpTarget, fusedTarget: FusedTarget): string;
+/**
+ * Find the first tensor-param name referenced in a chain's assigns.
+ * Used by both backends to pick the length-determining tensor.
+ */
+export declare function findTensorParamInChain(chain: FusibleChain, paramTensors: ReadonlySet<string>, allTensorVars: ReadonlySet<string>): string | null;
+/**
+ * Collect distinct tensor names referenced in the chain's expression
+ * trees that are NOT produced by the chain itself (i.e. read from
+ * outside: params or pre-existing locals). Both backends need this to
+ * pick a length-reference tensor when no formal param is in the chain.
+ */
+export declare function collectInputTensors(chain: FusibleChain, allTensorVars: ReadonlySet<string>): Set<string>;

package/dist-lib/numbl-core/jit/fusion.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fusion analysis for JIT backends (shared by JS-JIT and C-JIT).
+ *
+ * Scans a statement list for runs of tensor element-wise assigns that
+ * can be collapsed into a single per-element `for` loop. Each such run
+ * is a "fusible chain."
+ *
+ * A chain breaks on:
+ *   - control flow (If/For/While)
+ *   - any non-Assign statement
+ *   - a tensor assign whose RHS references a tensor that is NOT an input
+ *     param and NOT previously assigned within the same chain
+ *   - a scalar assign (left for the per-op emitter)
+ *
+ * An optional **trailing reduction** is absorbed when the statement
+ * immediately after a tensor chain is of the form
+ *   `acc = acc + reduce(lastChainVar)`   or
+ *   `acc = reduce(lastChainVar)`
+ * where `reduce` is sum/prod/max/min/mean/any/all. Absorbing the
+ * reduction lets the fused loop emit an inline accumulator instead of
+ * materialising the intermediate buffer.
+ */
+import type { JitExpr, JitStmt } from "./jitTypes.js";
+import { BinaryOperation } from "../parser/types.js";
+/** One tensor assign inside a fusible chain. */
+export interface FusedAssign {
+    /** Destination tensor variable name. */
+    destName: string;
+    /** RHS expression tree (all tensor ops are element-wise). */
+    expr: JitExpr;
+}
+/** A trailing reduction absorbed into the fused loop. */
+export interface FusedReduction {
+    /** Scalar accumulator variable name (e.g. `chain_acc`). */
+    accName: string;
+    /** Reduction builtin name (e.g. `sum`). */
+    reduceName: string;
+    /** The tensor variable being reduced (last chain dest). */
+    tensorName: string;
+    /**
+     * When true, the scalar statement is `acc = acc OP reduce(tensor)`,
+     * and `accOp` says which binary op combines the old accumulator with
+     * the reduction result. When false, it's a plain `acc = reduce(tensor)`.
+     */
+    hasAccumulate: boolean;
+    accOp?: BinaryOperation;
+}
+/** Describes one fusible chain found in a statement list. */
+export interface FusibleChain {
+    /** Index of the first statement in the chain (within the parent list). */
+    startIdx: number;
+    /** Number of statements consumed (tensor assigns + optional reduction). */
+    length: number;
+    /** The tensor assigns to fuse. */
+    assigns: FusedAssign[];
+    /** Optional trailing reduction. */
+    reduction?: FusedReduction;
+}
+/**
+ * Scan a statement list and return all fusible chains.
+ *
+ * `paramTensors` is the set of tensor parameter names (input data that
+ * will be read via `data[i]` in the fused loop).
+ * `allTensorVars` is the full set of tensor-typed variables (params +
+ * locals + outputs).
+ * `allowedUnaryOps` optionally restricts which tensor unary Call names
+ * are fusible. Defaults to `FUSIBLE_TENSOR_UNARY_OPS` (full set).
+ * The JS backend passes a restricted set that excludes transcendentals
+ * (V8 can't vectorize them, so fusing them is slower than per-op calls).
+ */
+export declare function findFusibleChains(stmts: JitStmt[], paramTensors: ReadonlySet<string>, allTensorVars: ReadonlySet<string>, allowedUnaryOps?: ReadonlySet<string>): FusibleChain[];

package/dist-lib/numbl-core/jit/fusionOps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared fusible-operation name sets for JIT fusion analysis.
+ *
+ * Both the C-JIT and JS-JIT fusion paths use these to determine which
+ * tensor Call nodes are fusible element-wise unary ops or absorbable
+ * trailing reductions. The numeric op codes live in their respective
+ * backend files (feasibility.ts for C, jitHelpersTensor.ts for JS).
+ */
+/** Tensor unary builtins fusible into per-element loops. */
+export declare const FUSIBLE_TENSOR_UNARY_OPS: ReadonlySet<string>;
+/**
+ * JS-JIT-safe subset: excludes transcendentals (exp, sin, cos, tan, etc.)
+ * which V8 can't SIMD-vectorize. Fusing these into a scalar per-element
+ * loop is slower than calling libnumbl_ops per-op (which uses -fopenmp-simd).
+ * The C-JIT uses the full set because GCC/Clang vectorize via #pragma omp simd.
+ */
+export declare const FUSIBLE_TENSOR_UNARY_OPS_JS: ReadonlySet<string>;
+/**
+ * Two-argument tensor element-wise builtins fusible into per-element loops.
+ * These are parsed as Call nodes (not Binary nodes) and need separate
+ * recognition in isPureElementwise / emitScalarExpr.
+ */
+export declare const FUSIBLE_TENSOR_BINARY_OPS: ReadonlySet<string>;
+/** Tensor reduction builtins absorbable as trailing reductions. */
+export declare const FUSIBLE_TENSOR_REDUCTION_OPS: ReadonlySet<string>;

package/dist-lib/numbl-core/{interpreter/jit → jit}/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * JIT compilation entry point for interpreter function calls.
  */
-import type { Interpreter } from "../interpreter.js";
-import type { FunctionDef } from "../types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { FunctionDef } from "../interpreter/types.js";
 export declare const JIT_SKIP: unique symbol;
 export declare function tryJitCall(interp: Interpreter, fn: FunctionDef, args: unknown[], nargout: number): unknown | typeof JIT_SKIP;

package/dist-lib/numbl-core/jit/jitBailSafety.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bail-safety gate for JIT bodies that contain I/O side effects.
+ *
+ * Mid-execution bails (JitBailToInterpreter / JitFuncHandleBailError)
+ * cause the interpreter to re-run the body from the top. If the body
+ * already emitted I/O before the bail, that output gets duplicated —
+ * which the user would notice.
+ *
+ * Rule: a body with any I/O statement may only be JIT-compiled if we
+ * can prove no bail can happen during execution. If there's no I/O,
+ * the body can be JIT'd normally (a bail just restarts silently).
+ *
+ * Walkers are IR-level — they see the actual lowered constructs that
+ * map 1:1 to runtime bail sites. The walkers recurse into the bodies
+ * of `UserCall`-ed functions (via `generatedIRBodies`), since a bail
+ * inside a callee still forces the caller to re-run.
+ */
+import type { JitStmt } from "./jitTypes.js";
+import type { GeneratedFn } from "./jitLower.js";
+/**
+ * Names of I/O-emitting builtins that the JIT is willing to lower as
+ * ExprStmt calls. Any `Call` to one of these in the lowered IR marks
+ * the body as having observable I/O.
+ */
+export declare const JIT_IO_BUILTINS: Set<string>;
+/**
+ * Walk a body + its transitively called function bodies and return
+ * whether the combined execution graph contains an I/O call.
+ */
+export declare function irHasIO(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;
+/**
+ * Walk a body + its transitively called function bodies and return
+ * whether any construct exists that can throw `JitBailToInterpreter`
+ * or `JitFuncHandleBailError` at runtime.
+ *
+ * Bail-risky constructs:
+ *   - AssignIndex / AssignIndexCol: may bail on out-of-bounds grow.
+ *   - FuncHandleCall / UserDispatchCall: return-type check may bail.
+ *   - UserCall: recurse into callee body.
+ */
+export declare function irHasBailRisk(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;

package/dist-lib/numbl-core/{interpreter/jit → jit}/jitLoop.d.ts

@@ -7,8 +7,8 @@
  * inside the loop body. On success the compiled code runs and output
  * values are written back to the interpreter environment.
  */
-import type { Interpreter } from "../interpreter.js";
-import type { Stmt } from "../../parser/types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
 /**
  * Attempt to JIT-compile and execute a for-loop statement.
  * Returns true if JIT succeeded, false to fall back to interpretation.

package/dist-lib/numbl-core/{interpreter/jit → jit}/jitLoopAnalysis.d.ts

@@ -6,7 +6,7 @@
  * - referenced: variables read inside the loop
  * - hasReturn: whether the loop body contains a return statement
  */
-import type { Stmt } from "../../parser/types.js";
+import type { Stmt } from "../parser/types.js";
 export interface LoopVarInfo {
     /** Variables referenced in the loop that must come from enclosing scope */
     inputs: string[];
@@ -19,6 +19,18 @@ export interface LoopVarInfo {
 export declare function analyzeForLoop(stmt: Stmt & {
     type: "For";
 }): LoopVarInfo;
+/**
+ * Collect the names of all variables read in a sibling-tail starting at
+ * `startIdx` of the given stmt list. Used by the loop JIT to filter the
+ * loop's output set so that loop-internal temporaries don't get written
+ * back when no later code reads them.
+ */
+export declare function collectReadsFromSiblings(stmts: Stmt[], startIdx: number, out: Set<string>): void;
+/**
+ * Analyze a top-level script body (list of statements) for JIT compilation.
+ * Used by `tryJitTopLevel` to wrap the whole main script as a synthetic fn.
+ */
+export declare function analyzeTopLevel(stmts: Stmt[]): LoopVarInfo;
 /** Analyze a while loop statement for JIT compilation. */
 export declare function analyzeWhileLoop(stmt: Stmt & {
     type: "While";