numbl 0.1.6 → 0.2.0

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

@@ -22,6 +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;
     /** Initial hold state for plotting (persisted across REPL executions). */
     initialHoldState?: boolean;
     /** Override or add builtins for this execution only. */
@@ -34,6 +36,23 @@ export interface ExecOptions {
     onInput?: (prompt: string) => string;
     /** Optimization level for interpreter (0 = none, >=1 = JIT scalar functions). */
     optimization?: number;
+    /**
+     * Experimental opt variant selector — e.g. `"e1"` for the prototype
+     * that keeps JS-JIT as the outer and emits on-demand C kernels for
+     * fusible tensor chains. Orthogonal to `optimization`; when set,
+     * `optimization` is still the base level (typically 1).
+     */
+    experimental?: string;
+    /** 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.
@@ -41,6 +60,8 @@ export interface ExecOptions {
      * - null → opt out of the implicit-cwd behavior entirely.
      */
     implicitCwdPath?: string | null;
+    /** SharedArrayBuffer for cooperative cancellation. Int32[0] != 0 means cancelled. */
+    cancelSAB?: SharedArrayBuffer;
 }
 export interface BuiltinProfileEntry {
     totalTimeMs: number;
@@ -72,6 +93,7 @@ export interface ProfileData {
 export interface ExecResult {
     output: string[];
     generatedJS: string;
+    generatedC: string;
     plotInstructions: PlotInstruction[];
     returnValue: RuntimeValue;
     variableValues: Record<string, RuntimeValue>;

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

@@ -2,6 +2,15 @@
  * Bessel function implementations (pure numeric, no runtime dependencies).
  *
  * Provides besselj, bessely, besseli, besselk for real-valued arguments.
+ *
+ * The rational polynomial approximations for J0, J1, Y0, Y1 are derived from
+ * the Cephes Math Library Release 2.8 (June 2000) by Stephen L. Moshier.
+ * Original Cephes code: Copyright 1984-2000 by Stephen L. Moshier.
+ * Used under the BSD license with permission of the author.
+ *
+ * The underlying minimax polynomial coefficients are based on the work of
+ * W.J. Cody, "Algorithm 715: SPECFUN", ACM Trans. Math. Software 19(1),
+ * pp. 22-32, 1993.
  */
 export declare function lanczosGamma(x: number): number;
 export declare function besselj(nu: number, x: number): number;

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

@@ -46,8 +46,13 @@ export type ReductionKernel = {
     reduceAll: (v: RuntimeTensor) => RuntimeValue;
     reduceDim: (v: RuntimeTensor, dim: number) => RuntimeValue;
 };
-/** Create an accumulator-based reduction kernel (sum, mean, etc.) */
-export declare function accumKernel(reduceFn: (acc: number, val: number) => number, initial: number, finalizeFn?: (acc: number, count: number) => number): ReductionKernel;
+/** Create an accumulator-based reduction kernel (sum, mean, etc.).
+ *
+ * When `opCode` is provided (an OpReduce.* value whose semantics match
+ * `reduceFn`/`initial`), the reduceAll fast path routes Float64 real and
+ * complex tensors through tensorOps.realFlatReduce.  The closure path
+ * is still used as a fallback for non-Float64 data. */
+export declare function accumKernel(reduceFn: (acc: number, val: number) => number, initial: number, finalizeFn?: (acc: number, count: number) => number, opCode?: number): ReductionKernel;
 /** Create a slice-based reduction kernel (median, mode, etc.) */
 export declare function sliceKernel(sliceFn: (slice: ArrayLike<number>) => number): ReductionKernel;
 /** Create an accumulator kernel that skips NaN values. */

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

@@ -0,0 +1,39 @@
+/**
+ * datetime / duration builtins — scalar-only initial implementation.
+ *
+ * datetime:
+ *   datetime()                         current time
+ *   datetime('now' | 'today' | 'yesterday' | 'tomorrow')
+ *   datetime(Y, M, D)
+ *   datetime(Y, M, D, H, MI, S[, MS])
+ *   datetime(X, 'ConvertFrom', 'datenum' | 'posixtime' | 'excel' | 'excel1904')
+ *
+ * datetime values are class_instance with className="datetime" and fields
+ * Year/Month/Day/Hour/Minute/Second. They are display-formatted by
+ * display.ts as "dd-MMM-yyyy [HH:mm:ss]".
+ *
+ * duration:
+ *   Produced by datetime - datetime, or by seconds(N) / minutes(N) / ...
+ *   Represented as class_instance with className="duration" and a single
+ *   Seconds field. Display format "hh:mm:ss".
+ *
+ * Arithmetic:
+ *   datetime - datetime -> duration
+ *   datetime + duration -> datetime
+ *   datetime - duration -> datetime
+ *   duration + duration -> duration
+ *   duration - duration -> duration
+ *
+ * `seconds(d)` returns the numeric seconds of a duration, or wraps a
+ * number as a duration.
+ */
+import type { RuntimeValue, RuntimeClassInstance } from "../../runtime/types.js";
+export declare function makeDatetime(year: number, month: number, day: number, hour: number, minute: number, second: number): RuntimeClassInstance;
+export declare function makeDuration(totalSeconds: number): RuntimeClassInstance;
+/**
+ * Attempt to handle a named binary operator ("plus", "minus", "lt", ...)
+ * when at least one operand is a datetime or duration class_instance.
+ * Returns the result value on success, or undefined to let the generic
+ * numeric path run.
+ */
+export declare function tryDatetimeDurationBinop(opName: string, a: RuntimeValue, b: RuntimeValue): RuntimeValue | undefined;

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

@@ -25,6 +25,7 @@ import "./string-extras.js";
 import "./prng.js";
 import "./cell-struct.js";
 import "./time-system.js";
+import "./datetime.js";
 import "./sparse.js";
 import "./special-math.js";
 import "./misc.js";

package/dist-lib/numbl-core/interpreter/builtins/time-system.d.ts

@@ -3,3 +3,4 @@
  * ismac, ispc, isunix.
  */
 export declare function getTicTime(): number;
+export declare function setTicTime(ms: number): void;

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

@@ -3,7 +3,7 @@
  */
 import type { RuntimeValue, RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
 import { FloatXArray } from "../../runtime/types.js";
-import { type JitType } from "../jit/jitTypes.js";
+import { type JitType } from "../../jit/jitTypes.js";
 export interface IBuiltinResolution {
     outputTypes: JitType[];
     apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
@@ -18,7 +18,50 @@ export interface IBuiltin {
     /** Given input JIT types + nargout, return output types and a specialized apply, or null. */
     resolve: (argTypes: JitType[], nargout: number) => IBuiltinResolution | null;
     /** Optional fast-path JS code emission for JIT. Return null to fall back to $h.ib_<name>. */
-    jitEmit?: (argCode: string[], argTypes: JitType[]) => string | null;
+    jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
+    /**
+     * Optional fast-path C code emission for the C-JIT. Return null if the
+     * builtin can't be emitted as a C expression for the given arg types
+     * — the C-JIT will bail to JS-JIT for this call site. Covers the
+     * scalar-argument case only (tensor-argument emission is handled by
+     * separate tensor-op dispatch in assemble.ts / emit/fused.ts).
+     */
+    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
+    /**
+     * Optional C-JIT tensor-op dispatch metadata. When a field is present,
+     * both the C feasibility check and C codegen read it directly —
+     * adding a new tensor-unary / tensor-binary / tensor-reduction builtin
+     * is one edit here (plus the matching native-side enum or C function).
+     * Previously these were three parallel hardcoded tables (one in
+     * feasibility.ts, two in context.ts) that could silently drift
+     * from the native-side opcode enums. Centralizing on the IBuiltin
+     * registration removes that drift risk.
+     */
+    jitCapabilities?: JitCapabilities;
+}
+/** Per-builtin C-JIT tensor-op dispatch metadata. See IBuiltin.jitCapabilities. */
+export interface JitCapabilities {
+    /**
+     * libnumbl_ops opcode enum name (e.g. "NUMBL_UNARY_EXP") for
+     * element-wise unary tensor builtins routed through
+     * `numbl_realUnaryElemwise`. Set this on element-wise unary functions
+     * that have a libnumbl_ops opcode and are safe to invoke on any real
+     * input (domain-restricted ones like log/sqrt stay excluded).
+     */
+    tensorUnaryOp?: string;
+    /**
+     * C function name (e.g. "fmax", "atan2", "numbl_mod") for 2-arg
+     * element-wise tensor builtins. The C-JIT emits an inline per-element
+     * loop calling this function; it must match the interpreter's
+     * scalar-apply semantics exactly.
+     */
+    tensorBinaryFn?: string;
+    /**
+     * libnumbl_ops opcode enum name (e.g. "NUMBL_REDUCE_SUM") for
+     * tensor→scalar reductions routed through `numbl_tensor_reduce_op`.
+     * Set on reduction builtins (sum / prod / max / min / any / all / mean).
+     */
+    tensorReductionOp?: string;
 }
 export declare function getIBuiltin(name: string): IBuiltin | undefined;
 export declare function registerIBuiltin(b: IBuiltin): void;
@@ -66,7 +109,9 @@ export declare function defineBuiltin(opts: {
     name: string;
     help?: BuiltinHelp;
     cases: BuiltinCase[];
-    jitEmit?: (argCode: string[], argTypes: JitType[]) => string | null;
+    jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
+    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
+    jitCapabilities?: JitCapabilities;
 }): void;
 type NumberJitType = Extract<JitType, {
     kind: "number";
@@ -92,6 +137,10 @@ interface UnaryElemwiseSpec {
     };
     /** Use applyUnaryElemwiseMaybeComplex instead of applyUnaryElemwise */
     maybeComplex?: boolean;
+    /** Opcode for the native unaryElemwise dispatch (see unary_elemwise.cpp).
+     * Used by the maybeComplex path so that e.g. sqrt/log can run in native C
+     * on the common all-in-domain case, then fall back for NaN entries only. */
+    nativeOpCode?: number;
 }
 /** Generate cases for a unary element-wise builtin. Each accepted kind gets
  *  its own case that bundles the type rule with the corresponding apply. */
@@ -101,8 +150,54 @@ export declare function unaryRealResultCases(realFn: (x: number) => number, comp
 /** Build cases for numeric predicates (isnan, isinf, isfinite) that return logical. */
 export declare function predicateCases(scalarTest: (x: number) => boolean, complexTest: (re: number, im: number) => boolean, tensorTest: (x: number) => boolean, tensorComplexTest: (re: number, im: number) => boolean, name: string): BuiltinCase[];
 /** Fast-path emitter for unary Math.* functions.
- *  Emits Math.fn(x) for scalar numbers, $h.tHelper(x) for real tensors. */
-export declare function unaryMathJitEmit(mathFn: string, tensorHelper: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[]) => string | null;
+ *  Emits Math.fn(x) for scalar numbers, $h.tHelper(dest, x) for real
+ *  tensors. `getDest` is a lazy callback returning the dest local: either
+ *  a mangled LHS (top-level Assign) or a fresh scratch (inner tensor
+ *  sub-expression). It's only invoked when the tensor fast path is
+ *  actually taken, so scalar / rejected paths don't burn a scratch. */
+export declare function unaryMathJitEmit(mathFn: string, tensorHelper: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
 /** Fast-path emitter for binary Math.* functions on two scalar numbers. */
 export declare function binaryMathJitEmit(mathFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
+/** Fast-path C emitter for unary math functions on a scalar.
+ *  Emits `cFn(x)` for scalar number/boolean; returns null otherwise
+ *  (tensor emission is handled separately by emit/tensor.ts).
+ *  If `requireNonneg` is set, rejects values whose sign isn't known
+ *  to be nonneg — matches the JS guard for domain-restricted functions. */
+export declare function unaryMathJitEmitC(cFn: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[]) => string | null;
+/** Fast-path C emitter for binary math functions on two scalar numbers. */
+export declare function binaryMathJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
+/**
+ * Fast-path C emitter for 1-arg scalar builtins that collapse to a
+ * compile-time constant given the arg's kind. Common for shape/type
+ * predicates where the answer is fully determined by the type
+ * (e.g. `isnumeric(number) -> 1.0`, `isscalar(number) -> 1.0`,
+ *       `ndims(number) -> 2.0`, `numel(number) -> 1.0`).
+ *
+ * `valueByKind` maps each supported JitType kind to its C constant.
+ * Arg kinds not in the map return null, which bails the C-JIT to
+ * JS-JIT for that call site. All values must be valid C double
+ * literals (`"1.0"`, `"0.0"`, `"2.0"`, ...).
+ */
+export declare function scalarConstantJitEmitC(valueByKind: Partial<Record<JitType["kind"], string>>): (argCode: string[], argTypes: JitType[]) => string | null;
+/**
+ * Fast-path C emitter for 1-arg scalar predicates backed by a runtime
+ * helper whose return value is int (e.g. `numbl_is_nan`,
+ * `numbl_is_inf`, `numbl_is_finite`). The int is cast to double for
+ * the C-JIT's uniform boolean-as-double representation. Returns null
+ * for non-scalar args.
+ *
+ * Note: `isnan` / `isinf` / `isfinite` from `<math.h>` can't be used
+ * directly because the JIT compiles with `-ffast-math`, which implies
+ * `-ffinite-math-only` and constant-folds those macros to false/true.
+ * The `numbl_is_nan` / `_is_inf` / `_is_finite` helpers in
+ * `jit_runtime` use bit-pattern inspection and live in a separately
+ * compiled archive, so the caller's `-ffast-math` can't defeat them.
+ */
+export declare function unaryPredicateJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
+/**
+ * Fast-path C emitter for 1-arg scalar builtins that are the identity
+ * on real scalars (e.g. `double(x)`, `real(x)`, `conj(x)`). Returns
+ * `(x)` for `number`/`boolean`, null otherwise.
+ */
+export declare function scalarIdentityJitEmitC(): (argCode: string[], argTypes: JitType[]) => string | null;
 export {};

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

@@ -53,12 +53,50 @@ 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[]>;
-    /** Optimization level (0 = pure interpreter, >=1 = JIT scalar functions). */
+    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;
+    /**
+     * 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;
-    /** Callback for JIT compilation logging. */
+    /**
+     * 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?: 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). */
+    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. */
     clearAllCaches(): void;

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

@@ -12,6 +12,8 @@ export interface InterpreterContext {
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
     callFunction: (name: string, args: unknown[], nargout: number) => unknown;
     rt: Runtime;
+    /** Optimization level (0 = JIT disabled, 1 = JIT scalar functions). */
+    optimization: number;
     /** Resolve a workspace function or class name to its source file,
      *  or undefined if no workspace file provides that name.
      *  `kind` distinguishes a regular .m function from a .numbl.js

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

@@ -4,7 +4,7 @@
 import type { Stmt, ArgumentsBlock } from "../parser/types.js";
 import type { Runtime } from "../runtime/runtime.js";
 import type { RuntimeValue } from "../runtime/types.js";
-import type { JitType } from "./jit/jitTypes.js";
+import type { JitType } from "../jit/jitTypes.js";
 export declare class BreakSignal {
     readonly _tag = "break";
 }
@@ -22,15 +22,24 @@ export declare class Environment {
     private vars;
     /** When true, writes to variables found in parent go to the parent (nested function semantics). */
     isNested: boolean;
-    /** Nested function definitions registered during execution. */
-    nestedFunctions: Map<string, {
+    /** Nested function definitions registered during execution. Lazy-initialized. */
+    private _nestedFunctions;
+    get nestedFunctions(): Map<string, {
         fn: FunctionDef;
         env: Environment;
     }>;
-    /** Names declared as `global` in this scope — reads/writes go through rt.$g */
-    globalNames: Set<string>;
-    /** Names declared as `persistent` in this scope */
-    persistentNames: Set<string>;
+    set nestedFunctions(v: Map<string, {
+        fn: FunctionDef;
+        env: Environment;
+    }>);
+    /** Names declared as `global` in this scope — reads/writes go through rt.$g. Lazy-initialized. */
+    private _globalNames;
+    get globalNames(): Set<string>;
+    set globalNames(v: Set<string>);
+    /** Names declared as `persistent` in this scope. Lazy-initialized. */
+    private _persistentNames;
+    get persistentNames(): Set<string>;
+    set persistentNames(v: Set<string>);
     /** Function ID for persistent variable storage */
     persistentFuncId: string | undefined;
     /** Back-reference to the runtime (needed for global/persistent access) */

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

@@ -0,0 +1,90 @@
+/**
+ * The native ABI as an explicit slot schema — one source of truth shared
+ * between the C-signature builder (assemble.ts) and the JS wrapper
+ * marshaller (install.ts).
+ *
+ * Each `AbiSlot` carries everything either side needs: the C type for
+ * the signature, the koffi type string (with `_Out_` prefix for
+ * out-pointers), the identifier name in the emitted C, and a backref
+ * (paramIdx / outputIdx) so the JS wrapper can locate the source value
+ * or output buffer without reconstructing the param-to-slot mapping
+ * itself.
+ *
+ * Adding a new ABI shape = add a slot kind here, emit it in
+ * `buildAbiSlots`, and handle it in the JS marshaller.
+ */
+import type { ClassificationResult } from "./classify.js";
+export type AbiSlotKind = "scalar" | "complexScalarRe" | "complexScalarIm" | "tensorData"
+/** Imaginary data pointer for a complex tensor param. Paired with
+ *  `tensorData`. Marshaller passes the RuntimeTensor's `.imag` (a
+ *  Float64Array) or NULL when `.imag === undefined`; the numbl_ops
+ *  complex kernels treat NULL imag as all-zero. */
+ | "tensorDataIm" | "tensorLen" | "tensorD0" | "tensorD1" | "scalarOut" | "complexScalarReOut" | "complexScalarImOut" | "fixedOutBuf"
+/** Imaginary fixed-output buffer (complex tensor output, non-dynamic). */
+ | "fixedOutBufIm" | "fixedOutLen" | "dynOutBuf"
+/** Imaginary buffer pointer for a dynamic complex tensor output. C
+ *  mallocs, transfers ownership via `double **`; wrapper decodes+copies
+ *  into a fresh Float64Array then frees. */
+ | "dynOutBufIm" | "dynOutLen" | "dynOutD0" | "dynOutD1" | "ticState" | "errFlag"
+/** Callback for `disp(...)` — JS-registered function pointer. The C
+ *  body invokes it directly; the JS wrapper supplies a koffi-registered
+ *  pointer that routes into `rt.output`. Signature:
+ *    void __disp_cb(const char *s, double num, int kind)
+ *  kind=0 => use `s`, kind=1 => use `num`. */
+ | "dispCb";
+export interface AbiSlot {
+    kind: AbiSlotKind;
+    /** C type string for the signature, e.g. "double", "const double *",
+     *  "double **". */
+    cType: string;
+    /** Identifier as it appears in the C signature. */
+    cName: string;
+    /** koffi type string, with `_Out_` prefix where koffi must treat the
+     *  pointer as an out-param. */
+    koffiType: string;
+    /** Index into paramDescs, for "scalar" / "tensor*" kinds. */
+    paramIdx?: number;
+    /** Index into outputDescs, for output-allocated kinds. */
+    outputIdx?: number;
+}
+export interface CParamDesc {
+    name: string;
+    kind: "scalar" | "complexScalar" | "tensor";
+    /** For tensor params: max indexing arity the body uses (1, 2, or 3).
+     *  Drives the extra `_d0` / `_d1` shape args the JS wrapper must
+     *  marshal. `undefined` means the tensor is only used in whole-tensor
+     *  ops (legacy data/len ABI). */
+    ndim?: number;
+    /** True for complex tensor params. Adds an imag-data slot right after
+     *  the real-data slot; the marshaller supplies the tensor's `.imag`
+     *  Float64Array or NULL. Ignored for scalar kinds. */
+    isComplex?: boolean;
+    /** Ordered slots this param contributes to the ABI. One slot for a
+     *  scalar; two for a complex scalar (re + im); two or more
+     *  (data + [imag for complex] + len + optional d0/d1) for a tensor. */
+    slots: AbiSlot[];
+}
+/** Per-output descriptor. Tells the JS wrapper how to marshal outputs. */
+export interface COutputDesc {
+    name: string;
+    kind: "scalar" | "boolean" | "complexScalar" | "tensor";
+    /** True for tensor outputs using the dynamic-output ABI: the C code
+     *  malloc's the buffer and transfers ownership via `double **` and
+     *  extra d0/d1 out-slots. The JS wrapper decodes the pointer, copies
+     *  into a fresh Float64Array, and frees the C allocation. */
+    dynamic?: boolean;
+    /** True for complex tensor outputs. Fixed outputs add a paired imag
+     *  Float64Array buffer; dynamic outputs add a paired imag `double **`
+     *  out-pointer the caller decodes + frees after the call. */
+    isComplex?: boolean;
+    /** Ordered slots this output contributes to the ABI. One for scalars,
+     *  two for complex scalars (reOut + imOut), two for fixed real tensor
+     *  outputs (buf + lenOut), three for fixed complex (buf + bufIm +
+     *  lenOut), four for dynamic real tensor outputs, five for dynamic
+     *  complex (dynBuf + dynBufIm + dynLen + dynD0 + dynD1). */
+    slots: AbiSlot[];
+}
+/** Build the ABI schema for one generated function. Mutates paramDescs /
+ *  outputDescs in place by filling in `slots`; returns the complete
+ *  `abiSlots` array in calling order (params, then outputs, then trailers). */
+export declare function buildAbiSlots(paramDescs: CParamDesc[], outputDescs: COutputDesc[], cls: ClassificationResult, paramOutputTensors: Set<string>, unshareTensorParams: Set<string>, needsTicState: boolean, needsErrorFlag: boolean, needsDispCb: boolean): AbiSlot[];

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

@@ -0,0 +1,56 @@
+/**
+ * JIT IR → pure C code generation (koffi path).
+ *
+ * Orchestration only: this file wires the classify / ABI / emit pieces
+ * together and assembles the final C source (headers + per-callee
+ * static functions + outer function).
+ *
+ *   classify.ts     — TensorMeta / analyzeTensorUsage, the single pass
+ *                     feeding every downstream decision.
+ *   abi.ts          — AbiSlot / CParamDesc / COutputDesc, buildAbiSlots.
+ *                     The one schema walked by both signature and JS.
+ *   emit/           — per-statement / per-expression C emission, split
+ *                     by concern (scalar, complexScalar, tensor, assign,
+ *                     userCall, stmt, fused). Reads ctx.cls for every
+ *                     classification decision.
+ *   context.ts   — EmitCtx + shared name/opcode helpers.
+ *
+ * UserCall support: when a feasible user-defined function is called
+ * from the outer body, its lowered IR is already in `generatedIRBodies`
+ * (populated by `lowerUserFuncCall` in jitLower.ts). We emit each
+ * reachable callee as a `static void jit_<jitName>(...)` in the same
+ * .c file, in post-order so callees are defined before callers. The
+ * shared `__err_flag` pointer flows from outer to every callee.
+ */
+import { type JitStmt, type JitType } from "../jitTypes.js";
+import type { GeneratedFn } from "../jitLower.js";
+import { type AbiSlot, type CParamDesc, type COutputDesc } from "./abi.js";
+export type { AbiSlot, AbiSlotKind } from "./abi.js";
+export type { CParamDesc, COutputDesc } from "./abi.js";
+export { mangle, mangleIm, tensorData, tensorDataIm, tensorLen, tensorD0, tensorD1, formatNumberLiteral, C_SCALAR_TARGET, } from "./context.js";
+export interface GenerateCResult {
+    cSource: string;
+    cFnName: string;
+    paramDescs: CParamDesc[];
+    outputDescs: COutputDesc[];
+    /** The full ABI slot list in calling order:
+     *    paramDescs[0].slots ++ paramDescs[1].slots ++ ...
+     *    ++ outputDescs[0].slots ++ ... ++ trailer slots (ticState/errFlag).
+     *  The JS wrapper walks this list to marshal values. */
+    abiSlots: AbiSlot[];
+    /** True when any tensor is involved (params, locals, or outputs). */
+    usesTensors: boolean;
+    /** koffi function signature string for declaring the C function. */
+    koffiSignature: string;
+    /** True when tic/toc are used — the function has an extra `double*` param. */
+    needsTicState: boolean;
+    /** True when any Index read was emitted — the function has an extra
+     *  `double *__err_flag` trailing param. */
+    needsErrorFlag: boolean;
+    /** True when a `disp(...)` call was emitted — the function has an
+     *  extra `void (*__disp_cb)(const char *, double, int)` trailing
+     *  param. The JS wrapper registers a callback that routes back to
+     *  `rt.output`. */
+    needsDispCb: boolean;
+}
+export declare function generateC(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, argTypes: JitType[], _outputType: JitType | null, outputTypes: JitType[], fnName: string, fuse?: boolean, openmp?: boolean, generatedIRBodies?: Map<string, GeneratedFn>): GenerateCResult;

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

@@ -0,0 +1,70 @@
+/**
+ * C-JIT: unified classification pass for tensor names.
+ *
+ * Replaces the ten ad-hoc sets/maps (`tensorVars`, `paramTensorNames`,
+ * `outputTensorNames`, `localTensorNames`, `assignIndexTargets`,
+ * `unshareTensorParams`, `tensorMaxDim`, `freshAllocTensors`,
+ * `dynamicOutputs`, `paramOutputTensors`) that the codegen used to
+ * build from 7+ body walks. Everything downstream — signature builder,
+ * prelude, epilogue, emit helpers, fusion call — now reads from the
+ * `TensorMeta` table this pass produces.
+ */
+import type { JitExpr, JitStmt, JitType } from "../jitTypes.js";
+export type TensorKind = 
+/** Tensor param, never appears in the output list. */
+"param"
+/** Tensor param whose name is also in the output list. */
+ | "paramOutput"
+/** Pure tensor output (not a param). */
+ | "output"
+/** Tensor local (neither param nor output). */
+ | "local";
+export interface TensorMeta {
+    kind: TensorKind;
+    /** Max index arity on this name (1/2/3). 0 means the name is never
+     *  used as an Index or AssignIndex base. */
+    maxIndexDim: number;
+    /** True when any `Assign(name, RHS)` has RHS ∈ {TensorLiteral,
+     *  VConcatGrow, Call(zeros|ones), Var(src) where src.hasFreshAlloc,
+     *  RangeSliceRead}. Propagated to fixed point. */
+    hasFreshAlloc: boolean;
+    /** True when any AssignIndex / AssignIndexRange / AssignIndexCol
+     *  uses this name as the base. */
+    isAssignIndexTarget: boolean;
+    /** Derived: `kind === "param"` and (`isAssignIndexTarget` or
+     *  `hasFreshAlloc`). Triggers the unshare-at-entry malloc+memcpy
+     *  prelude so writes don't leak to the caller's buffer. */
+    needsUnshare: boolean;
+    /** Derived: `hasFreshAlloc` and (`kind === "output"` or
+     *  `kind === "paramOutput"`). Triggers the `double **` dynamic-output
+     *  ABI. */
+    isDynamicOutput: boolean;
+    /** True when this tensor's `JitType.isComplex === true` — either at
+     *  the boundary (param / output type) or propagated from a complex
+     *  RHS for locals. Drives paired imag-buffer plumbing: every complex
+     *  tensor gets a `v_name_data_im` companion pointer, an extra ABI
+     *  slot for boundaries, and imag malloc / free / copy parallel to
+     *  the existing real path. */
+    isComplex: boolean;
+}
+export interface ClassificationResult {
+    /** All names with a tensor role, in insertion order (params first,
+     *  then outputs, then locals in body order). */
+    tensorNames: string[];
+    /** Per-name metadata. */
+    meta: Map<string, TensorMeta>;
+    /** True iff any name has `hasFreshAlloc`. Lets callers skip the
+     *  dynamic-output marshalling when no name uses it. */
+    hasAnyDynamic: boolean;
+    /** Name → is any tensor role. `meta.has(name)`. */
+    tensorVars: Set<string>;
+    /** Names with `kind === "param"` or `"paramOutput"`. */
+    paramTensorNames: Set<string>;
+    /** Names with `kind === "output"` or `"paramOutput"`. */
+    outputTensorNames: Set<string>;
+    /** Names with `kind === "local"`. */
+    localTensorNames: Set<string>;
+}
+/** Does this Assign RHS allocate a fresh C-owned buffer? */
+export declare function isFreshTensorRhs(expr: JitExpr): boolean;
+export declare function analyzeTensorUsage(body: JitStmt[], params: string[], argTypes: JitType[], outputNames: string[], outputTypes: JitType[]): ClassificationResult;

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

@@ -0,0 +1,37 @@
+/**
+ * C-JIT compilation driver (koffi path).
+ *
+ * Takes generated C source, compiles it into a `.so` shared library,
+ * loads it via koffi, and returns the declared function.
+ *
+ * Strategy:
+ *   1. Content-addressed cache under ~/.cache/numbl/c-jit/ — the hash
+ *      includes the source bytes plus compiler/platform/numbl versions,
+ *      so any input change forces a recompile.
+ *   2. On cache miss, write `src.c` into a fresh tmpdir and shell out to
+ *      the C compiler (`$NUMBL_CC` or `cc`) with `-shared -fPIC`.
+ *   3. Load with koffi.load() and declare the function.
+ *
+ * No Node API headers are needed — functions are plain C with raw types.
+ * No NAPI_MODULE_INIT, no module registration, no exit hooks.
+ */
+export interface CompiledCFn {
+    fn: (...args: unknown[]) => unknown;
+    cachedPath: string;
+    /** The loaded koffi library handle, for declaring additional exports. */
+    lib: any;
+}
+/**
+ * Compile + load a C function via koffi. Returns null on any failure.
+ *
+ * `koffiSignature` is the koffi type-string for the C function, e.g.:
+ *   "void jit_fn(double, double *, int64_t, double *)"
+ */
+export declare function compileAndLoad(cSource: string, koffiSignature: string, _cFnName: string, log?: (m: string) => void, extraFlags?: string[]): CompiledCFn | null;
+export declare function resetCEnvForTesting(): void;
+export declare function cJitUnavailableReason(): string | undefined;
+export declare function cJitCacheSize(): number;
+export declare function readCachedBuild(cachedPath: string): Buffer;
+/** True when the C compiler supports `-fopenmp` (thread-level parallelism).
+ *  Triggers env discovery on first call so it can be used before compileAndLoad. */
+export declare function cJitOpenmpAvailable(log?: (m: string) => void): boolean;