numbl 0.1.6 → 0.2.0

package/dist-lib/numbl-core/jit/js/jitHelpers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JIT runtime helpers assembly point.
+ *
+ * This module assembles the $h helpers object from focused sub-modules:
+ * - jitHelpersComplex.ts — complex number arithmetic
+ * - jitHelpersIndex.ts  — tensor indexing (generic, fast-path, hoisted)
+ * - jitHelpersTensor.ts — tensor binary/unary ops, concat, COW
+ *
+ * The $h object is passed to every JIT-compiled function. V8 inline
+ * caches require a stable hidden class, so buildPerRuntimeJitHelpers()
+ * creates a fresh snapshot via a single spread expression.
+ */
+export { re, im, mkc, cAdd, cSub, cMul, cDiv, cNeg, cConj, cAngle, cTruthy, } from "./jitHelpersComplex.js";
+export { bce, idx1, idx2, idxN, idx1r, idx2r, idx3r, idx1r_h, idx2r_h, idx3r_h, set1r_h, set2r_h, set3r_h, setRange1r_h, setCol2r_h, subarrayCopy1r, subarrayCopy1rRow, } from "./jitHelpersIndex.js";
+export { makeTensor, tensorBinaryOp, tensorCompareOp, tensorUnary, tensorNeg, vconcatGrow1r, unshare, shareTensor, asTensor, tDouble, tSum, tAdd, tSub, tMul, tDiv, tPow, tEq, tNeq, tLt, tLe, tGt, tGe, } from "./jitHelpersTensor.js";
+export { JitBailToInterpreter } from "./jitHelpersIndex.js";
+/**
+ * Thrown when a function handle called from JIT code returns a type
+ * different from what the JIT expected (determined by probing at compile
+ * time). The loop runner catches this and falls back to interpretation.
+ */
+export declare class JitFuncHandleBailError extends Error {
+    readonly fnName: string;
+    readonly expectedType: string;
+    readonly actualType: string;
+    constructor(fnName: string, expectedType: string, actualType: string);
+}
+export declare const jitHelpers: Record<string, unknown>;
+import type { IBuiltin } from "../../interpreter/builtins/index.js";
+/**
+ * Build a per-runtime jitHelpers snapshot. Uses a single spread expression
+ * for a fresh V8 hidden class (critical for inline-cache performance).
+ */
+export declare function buildPerRuntimeJitHelpers(jsUserFunctions: ReadonlyMap<string, IBuiltin>): Record<string, any>;

package/dist-lib/numbl-core/jit/js/jitHelpersComplex.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Complex number arithmetic helpers for JIT-compiled code.
+ * These are pure functions used by the $h helpers object.
+ */
+import type { RuntimeComplexNumber } from "../../runtime/types.js";
+export declare function re(v: unknown): number;
+export declare function im(v: unknown): number;
+export declare function mkc(r: number, i: number): number | RuntimeComplexNumber;
+export declare function cAdd(a: unknown, b: unknown): number | RuntimeComplexNumber;
+export declare function cSub(a: unknown, b: unknown): number | RuntimeComplexNumber;
+export declare function cMul(a: unknown, b: unknown): number | RuntimeComplexNumber;
+/**
+ * Complex division using Smith's method to avoid overflow/underflow.
+ * Handles division by zero consistently with MATLAB (produces Inf, not NaN).
+ */
+export declare function cDiv(a: unknown, b: unknown): number | RuntimeComplexNumber;
+export declare function cNeg(a: unknown): number | RuntimeComplexNumber;
+export declare function cConj(a: unknown): number | RuntimeComplexNumber;
+export declare function cAngle(a: unknown): number;
+/** Complex truthiness: nonzero if either real or imag part is nonzero. */
+export declare function cTruthy(v: unknown): boolean;

package/dist-lib/numbl-core/jit/js/jitHelpersIndex.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tensor indexing helpers for JIT-compiled code.
+ *
+ * Three tiers of helpers, from most general to most specialized:
+ * 1. Generic (idx1, idx2, idxN) — handle any base type, real or complex
+ * 2. Real-tensor fast path (idx1r, idx2r, idx3r) — skip type/imag checks
+ * 3. Hoisted-base (idx*r_h, set*r_h) — take pre-extracted data/len/shape
+ *
+ * All helpers use 1-based MATLAB indexing and include per-dimension bounds
+ * checks to ensure consistency with the interpreter.
+ */
+import { type FloatXArrayType, type RuntimeTensor } from "../../runtime/types.js";
+export declare class JitBailToInterpreter extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function bce(): never;
+export declare function idx1(base: unknown, i: number): unknown;
+export declare function idx2(base: unknown, ri: number, ci: number): unknown;
+export declare function idxN(base: unknown, indices: number[]): unknown;
+export declare function idx1r(base: RuntimeTensor, i: number): number;
+export declare function idx2r(base: RuntimeTensor, ri: number, ci: number): number;
+export declare function idx3r(base: RuntimeTensor, i1: number, i2: number, i3: number): number;
+export declare function idx1r_h(data: FloatXArrayType, len: number, i: number): number;
+export declare function idx2r_h(data: FloatXArrayType, len: number, rows: number, ri: number, ci: number): number;
+export declare function idx3r_h(data: FloatXArrayType, len: number, d0: number, d1: number, i1: number, i2: number, i3: number): number;
+export declare function set1r_h(data: FloatXArrayType, len: number, i: number, v: number): void;
+export declare function set2r_h(data: FloatXArrayType, len: number, rows: number, ri: number, ci: number, v: number): void;
+export declare function set3r_h(data: FloatXArrayType, len: number, d0: number, d1: number, i1: number, i2: number, i3: number, v: number): void;
+export declare function setRange1r_h(dstData: FloatXArrayType, dstLen: number, dstStart: number, dstEnd: number, srcData: FloatXArrayType, srcLen: number, srcStart: number, srcEnd: number): void;
+export declare function subarrayCopy1r(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function subarrayCopy1rRow(srcData: FloatXArrayType, srcLen: number, start: number, end: number): RuntimeTensor;
+export declare function setCol2r_h(dstData: FloatXArrayType, dstRows: number, dstLen: number, col: number, srcData: FloatXArrayType, srcLen: number): void;

package/dist-lib/numbl-core/jit/js/jitHelpersTensor.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Tensor operation helpers for JIT-compiled code.
+ * Handles element-wise binary/unary ops, comparison ops, concat, and
+ * tensor coercion for struct-array field access.
+ */
+import { type FloatXArrayType, type RuntimeTensor } from "../../runtime/types.js";
+import type { RuntimeComplexNumber } from "../../runtime/types.js";
+export declare function makeTensor(data: FloatXArrayType, imag: FloatXArrayType | undefined, shape: number[]): RuntimeTensor;
+/** Bump rc on a tensor (no-op for non-tensor values). Used for var-to-var
+ *  JIT assignments so the aliased tensor is no longer eligible for
+ *  in-place buffer reuse. */
+export declare function shareTensor(v: unknown): unknown;
+type ScalarVal = number | RuntimeComplexNumber;
+export declare function tensorBinaryOp(a: unknown, b: unknown, realOp: (x: number, y: number) => number, complexOp: (a: ScalarVal, b: ScalarVal) => ScalarVal): RuntimeTensor | ScalarVal;
+export declare function tensorCompareOp(a: unknown, b: unknown, cmp: (x: number, y: number) => boolean): RuntimeTensor;
+export declare function tensorUnary(dest: unknown, a: RuntimeTensor, fn: (x: number) => number): RuntimeTensor;
+export declare function tensorNeg(dest: unknown, a: RuntimeTensor): RuntimeTensor;
+export declare function tDouble(v: unknown): unknown;
+export declare function tSum(v: unknown): unknown;
+export declare function vconcatGrow1r(base: unknown, v: number): RuntimeTensor;
+export declare function unshare(t: unknown): RuntimeTensor;
+export declare function asTensor(v: unknown): RuntimeTensor;
+export declare const tAdd: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tSub: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tMul: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tDiv: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tPow: (_dest: unknown, a: unknown, b: unknown) => RuntimeTensor | ScalarVal;
+export declare const tEq: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tNeq: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tLt: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tLe: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tGt: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export declare const tGe: (dest: unknown, a: unknown, b: unknown) => RuntimeTensor;
+export {};

package/dist-lib/numbl-core/jit/js/jsFusedCodegen.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fused per-element loop emission for the JS-JIT.
+ *
+ * Given a FusibleChain (from fusion.ts), emits a single block-scoped
+ * JavaScript `for` loop that evaluates all the chain's tensor assigns
+ * as inline scalar expressions per element — no $h.tAdd / $h.tMul
+ * helper calls, no intermediate tensor allocations.
+ *
+ * Tensor var references become either:
+ *   - `__<name>_data[__i]`  for input params / pre-existing tensors
+ *   - `__f_<name>`           for chain-produced intermediates (scalar local)
+ *
+ * The optional trailing reduction is absorbed as an inline accumulator
+ * inside the same loop.
+ */
+import type { FusibleChain } from "../fusion.js";
+export declare function emitJsFusedChain(lines: string[], indent: string, chain: FusibleChain, allTensorVars: ReadonlySet<string>, paramTensors: ReadonlySet<string>, outputTensorNames: ReadonlySet<string>, _localTensorNames: ReadonlySet<string>, mangle: (n: string) => string, experimental?: string): void;

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

@@ -0,0 +1,58 @@
+/**
+ * Shared scalar-expression emission used by both the JS-JIT and C-JIT
+ * backends.
+ *
+ * The value-form switches for scalar Binary/Unary and the truthiness
+ * walker have identical IR traversal between the two backends — only
+ * the leaf syntax (operator spelling, coercion rules) differs. A
+ * backend supplies a `ScalarOpTarget` describing how to spell each op,
+ * and the shared functions below handle the dispatch.
+ *
+ * Complex-scalar and tensor ops are *not* covered here — those remain
+ * backend-specific (JS uses `$h.cAdd` etc.; C-JIT bails on complex).
+ */
+import { BinaryOperation, UnaryOperation } from "../parser/types.js";
+import type { JitExpr } from "./jitTypes.js";
+export interface ScalarOpTarget {
+    binAdd(l: string, r: string): string;
+    binSub(l: string, r: string): string;
+    binMul(l: string, r: string): string;
+    binDiv(l: string, r: string): string;
+    binPow(l: string, r: string): string;
+    binEq(l: string, r: string): string;
+    binNe(l: string, r: string): string;
+    binLt(l: string, r: string): string;
+    binLe(l: string, r: string): string;
+    binGt(l: string, r: string): string;
+    binGe(l: string, r: string): string;
+    binAnd(l: string, r: string): string;
+    binOr(l: string, r: string): string;
+    unaryPlus(operand: string): string;
+    unaryMinus(operand: string): string;
+    unaryNot(operand: string): string;
+    toTruthy(valueExpr: string): string;
+    condEq(l: string, r: string): string;
+    condNe(l: string, r: string): string;
+    condLt(l: string, r: string): string;
+    condLe(l: string, r: string): string;
+    condGt(l: string, r: string): string;
+    condGe(l: string, r: string): string;
+    condNot(truthyExpr: string): string;
+    condAnd(l: string, r: string): string;
+    condOr(l: string, r: string): string;
+}
+/** Dispatch a scalar Binary op to the target. Throws on unsupported ops. */
+export declare function emitScalarBinaryOp(op: BinaryOperation, left: string, right: string, target: ScalarOpTarget): string;
+/** Dispatch a scalar Unary op to the target. Transpose is scalar-identity. */
+export declare function emitScalarUnaryOp(op: UnaryOperation, operand: string, target: ScalarOpTarget): string;
+/**
+ * Emit a condition expression for `if` / `while` / `&&` / `||` operands.
+ *
+ * Recurses through nested comparison / logical operators so that the
+ * whole condition emits as a native boolean/condition expression rather
+ * than being wrapped in a trailing `!= 0` on every nested result.
+ *
+ * `emitValue` is the backend's value-form expression emitter — it is
+ * called for the leaf operands of comparisons and for the fallback path.
+ */
+export declare function emitScalarTruthiness(expr: JitExpr, emitValue: (e: JitExpr) => string, target: ScalarOpTarget): string;

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

@@ -68,7 +68,8 @@ export declare enum Token {
     Ellipsis = 66,
     Newline = 67,
     Section = 68,
-    Error = 69
+    Error = 69,
+    Directive = 70
 }
 export interface SpannedToken {
     token: Token;

package/dist-lib/numbl-core/native/lapack-bridge.d.ts

@@ -18,7 +18,7 @@
  * Expected native addon version. Bump this whenever the C++ addon API changes
  * (must match ADDON_VERSION in numbl_addon.cpp).
  */
-export declare const NATIVE_ADDON_EXPECTED_VERSION = 2;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 8;
 export interface LapackBridge {
     /** Returns the native addon's version number. */
     addonVersion?(): number;
@@ -432,6 +432,51 @@ export interface LapackBridge {
         re: Float64Array;
         im?: Float64Array;
     };
+    /** Complex-scalar * (real or complex) tensor element-wise op.
+     * op: 0=add, 1=sub, 2=mul, 3=div.
+     * Pass null for arrIm to treat the tensor as purely real. */
+    elemwiseComplexScalar?(scalarRe: number, scalarIm: number, arrRe: Float64Array, arrIm: Float64Array | null, op: number, scalarOnLeft: boolean): {
+        re: Float64Array;
+        im?: Float64Array;
+    };
+    /** Real binary elemwise: out[i] = a[i] OP b[i]. op codes per OpRealBin. */
+    tensorOpRealBinary?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    /** Real scalar-tensor binary elemwise. */
+    tensorOpRealScalarBinary?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Complex binary elemwise (split storage). aIm/bIm may be null. */
+    tensorOpComplexBinary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    /** Complex scalar-tensor binary elemwise. arrIm may be null. */
+    tensorOpComplexScalarBinary?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    /** Real unary elemwise: out[i] = OP(a[i]). op codes per OpUnary. */
+    tensorOpRealUnary?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    /** Complex unary elemwise (split storage). aIm may be null. ABS unsupported. */
+    tensorOpComplexUnary?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    /** Complex absolute value (real-valued output). aIm may be null. */
+    tensorOpComplexAbs?(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    /** Real comparison: out[i] = (a[i] OP b[i]) ? 1 : 0. */
+    tensorOpRealComparison?(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    /** Real scalar-tensor comparison. */
+    tensorOpRealScalarComparison?(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Complex comparison. EQ/NE use both parts; LT/LE/GT/GE use real parts. */
+    tensorOpComplexComparison?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    /** Complex scalar-tensor comparison. */
+    tensorOpComplexScalarComparison?(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    /** Flat real reduction (output is a 1-element Float64Array). */
+    tensorOpRealFlatReduce?(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    /** Flat complex reduction.  outIm may be null for ANY/ALL. */
+    tensorOpComplexFlatReduce?(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    /**
+     * Real Bessel tensor op: out[i] = besselX(nu, z[i]).
+     * op codes per OpBessel. scale: 0 unscaled, 1 scaled.
+     */
+    tensorOpBesselReal?(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    /**
+     * Hankel function tensor op (complex output, real input).
+     * kKind: 1 → J + i*Y; 2 → J - i*Y.
+     */
+    tensorOpBesselH?(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+    /** Dump op-code enum values as a stable string (drift detection). */
+    tensorOpDumpCodes?(): string;
 }
 export declare function setLapackBridge(bridge: LapackBridge): void;
 export declare function getLapackBridge(): LapackBridge | null;

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

@@ -0,0 +1,18 @@
+/**
+ * Pure-TS implementation of Bessel tensor ops.
+ * Mirrors native/ops/bessel.c — fallback when the native addon is unavailable.
+ *
+ * Delegates the per-element math to src/numbl-core/helpers/bessel.ts so both
+ * the scalar interpreter path and the tensor path share the same algorithm.
+ */
+/**
+ * out[i] = bessel<OP>(nu, z[i]).  scale mirrors the behavior of numbl_bessel_real.
+ */
+export declare function tsBesselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+/**
+ * Hankel function for real z:
+ *   kKind=1 → out[i] = J_nu(z[i]) + i * Y_nu(z[i])
+ *   kKind=2 → out[i] = J_nu(z[i]) - i * Y_nu(z[i])
+ * scaled=1 multiplies by exp(-i*z) (k=1) or exp(+i*z) (k=2).
+ */
+export declare function tsBesselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;

package/dist-lib/numbl-core/ops/comparison.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure-TS implementation of comparison ops.
+ * Mirrors native/ops/comparison.c.
+ *
+ * Output is 0.0 / 1.0 stored in a Float64Array (numbl's logical-tensor
+ * convention — caller wraps the result with _isLogical = true).
+ */
+export declare function tsRealComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+export declare function tsComplexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+export declare function tsComplexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-lib/numbl-core/ops/complexBinaryElemwise.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Pure-TS implementation of complex binary element-wise ops, split storage.
+ * Mirrors native/ops/complex_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ * aIm/bIm/arrIm may be null → treat as zero.
+ * outIm is always required (caller allocates even if result might be real).
+ */
+export declare function tsComplexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;

package/dist-lib/numbl-core/ops/complexUnaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of complex unary element-wise ops, split storage.
+ * Mirrors native/ops/complex_unary_elemwise.c.
+ *
+ * ABS is intentionally unsupported (use tsComplexAbs — real-valued output).
+ */
+export declare function tsComplexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+export declare function tsComplexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;

package/dist-lib/numbl-core/ops/dispatch.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tensor-ops dispatcher: chooses native bridge or pure-TS fallback.
+ *
+ * All entry points have identical signatures across native and TS impls.
+ * Caller owns input AND output memory; functions never allocate output.
+ *
+ * Selection happens once on first use per category and is cached
+ * (the bridge identity is captured at module load via getLapackBridge()).
+ */
+export declare const tensorOps: {
+    realBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexBinaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexScalarBinaryElemwise(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, outRe: Float64Array, outIm: Float64Array): void;
+    realUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexUnaryElemwise(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array): void;
+    complexAbs(n: number, aRe: Float64Array, aIm: Float64Array | null, out: Float64Array): void;
+    realComparison(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    realScalarComparison(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    complexComparison(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, bRe: Float64Array, bIm: Float64Array | null, out: Float64Array): void;
+    complexScalarComparison(op: number, n: number, sRe: number, sIm: number, arrRe: Float64Array, arrIm: Float64Array | null, scalarOnLeft: boolean, out: Float64Array): void;
+    realFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+    complexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;
+    besselReal(op: number, nu: number, n: number, z: Float64Array, scale: number, out: Float64Array): void;
+    besselH(kKind: number, nu: number, n: number, z: Float64Array, scale: number, outRe: Float64Array, outIm: Float64Array): void;
+};

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

@@ -0,0 +1,8 @@
+/**
+ * Tensor-ops layer: pointer-based, op-code dispatched, native + TS parity.
+ *
+ * Every op has identical signatures across native (C) and TS implementations.
+ * Caller owns input AND output memory; ops never allocate output.
+ */
+export { tensorOps } from "./dispatch.js";
+export { OpRealBin, OpComplexBin, OpUnary, OpCmp, OpReduce, OpBessel, } from "./opCodes.js";

package/dist-lib/numbl-core/ops/opCodes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Op-code enums for the tensor-ops layer.
+ *
+ * SINGLE SOURCE OF TRUTH on the TS side. Mirrors native/ops/numbl_ops.h.
+ * Drift detection: src/__tests__/op-codes-sync.test.ts compares this file's
+ * values against numbl_dump_op_codes() at CI time.
+ */
+/** Real binary element-wise ops. */
+export declare const OpRealBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Complex binary element-wise ops. */
+export declare const OpComplexBin: {
+    readonly ADD: 0;
+    readonly SUB: 1;
+    readonly MUL: 2;
+    readonly DIV: 3;
+};
+/** Flat reduction ops. */
+export declare const OpReduce: {
+    readonly SUM: 0;
+    readonly PROD: 1;
+    readonly MAX: 2;
+    readonly MIN: 3;
+    readonly ANY: 4;
+    readonly ALL: 5;
+    readonly MEAN: 6;
+};
+/** Comparison ops (logical output). */
+export declare const OpCmp: {
+    readonly EQ: 0;
+    readonly NE: 1;
+    readonly LT: 2;
+    readonly LE: 3;
+    readonly GT: 4;
+    readonly GE: 5;
+};
+/** Bessel function ops (real input). H-variants are in numbl_bessel_h (complex output). */
+export declare const OpBessel: {
+    readonly J: 0;
+    readonly Y: 1;
+    readonly I: 2;
+    readonly K: 3;
+};
+/** Unary element-wise ops (shared numbering for real + complex). */
+export declare const OpUnary: {
+    readonly EXP: 0;
+    readonly LOG: 1;
+    readonly LOG2: 2;
+    readonly LOG10: 3;
+    readonly SQRT: 4;
+    readonly ABS: 5;
+    readonly FLOOR: 6;
+    readonly CEIL: 7;
+    readonly ROUND: 8;
+    readonly TRUNC: 9;
+    readonly SIN: 10;
+    readonly COS: 11;
+    readonly TAN: 12;
+    readonly ASIN: 13;
+    readonly ACOS: 14;
+    readonly ATAN: 15;
+    readonly SINH: 16;
+    readonly COSH: 17;
+    readonly TANH: 18;
+    readonly SIGN: 19;
+};

package/dist-lib/numbl-core/ops/realBinaryElemwise.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pure-TS implementation of real binary element-wise ops.
+ * Mirrors native/ops/real_binary_elemwise.c.
+ *
+ * Caller-allocated input/output buffers; never copies.
+ */
+export declare function tsRealBinaryElemwise(op: number, n: number, a: Float64Array, b: Float64Array, out: Float64Array): void;
+export declare function tsRealScalarBinaryElemwise(op: number, n: number, scalar: number, arr: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;

package/dist-lib/numbl-core/ops/realUnaryElemwise.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Pure-TS implementation of real unary element-wise ops.
+ * Mirrors native/ops/real_unary_elemwise.c.
+ */
+export declare function tsRealUnaryElemwise(op: number, n: number, a: Float64Array, out: Float64Array): void;

package/dist-lib/numbl-core/ops/reduce.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pure-TS flat reductions.  Mirrors native/ops/reduce.c.
+ * Caller-allocated input and output (1-element).
+ */
+export declare function tsRealFlatReduce(op: number, n: number, a: Float64Array, out: Float64Array): void;
+export declare function tsComplexFlatReduce(op: number, n: number, aRe: Float64Array, aIm: Float64Array | null, outRe: Float64Array, outIm: Float64Array | null): void;

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

@@ -310,6 +310,12 @@ export type Stmt = {
     superClass: string | null;
     members: ClassMember[];
     span: Span;
+} | {
+    /** Magic comment directive, e.g. `%!numbl:assert_jit` or `%!numbl:assert_jit c`. */
+    type: "Directive";
+    directive: string;
+    args: string[];
+    span: Span;
 };
 export interface AbstractSyntaxTree {
     body: Stmt[];

package/dist-lib/numbl-core/runtime/alloc.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Allocate an UNINITIALIZED typed array — skips the zero-fill that
+ * `new Float64Array(n)` / `new FloatXArray(n)` perform by default.
+ *
+ * On Node, `Buffer.allocUnsafe` returns un-zeroed memory; wrapping it
+ * in a TypedArray view costs ~10× less than the zero-fill for a 16 MB
+ * buffer (~45 µs vs ~470 µs at N=2M doubles).
+ *
+ * SAFETY CONTRACT (very important):
+ *   The caller MUST write every element before reading it.  Any element
+ *   that is read before being written will contain arbitrary stale bytes
+ *   from recently-freed memory.  If you cannot guarantee full coverage,
+ *   use `new Float64Array(n)` / `new FloatXArray(n)` instead.
+ *
+ * In non-Node environments (browser, Deno without node-compat, …) where
+ * `Buffer` is unavailable, we fall back to the zero-filling constructor
+ * — still correct, just slower.
+ */
+import { FloatXArray } from "./types.js";
+type FloatXInstance = InstanceType<typeof FloatXArray>;
+export declare function uninitFloat64(n: number): Float64Array<ArrayBuffer>;
+export declare function uninitFloatX(n: number): FloatXInstance;
+export {};

package/dist-lib/numbl-core/runtime/constructors.d.ts

@@ -2,7 +2,7 @@
  * RuntimeValue constructor helpers (the MV namespace).
  */
 import { ItemType } from "../lowering/itemTypes.js";
-import { type RuntimeNumber, type RuntimeTensor, type RuntimeString, type RuntimeChar, type RuntimeLogical, type RuntimeCell, type RuntimeStruct, type RuntimeFunction, type RuntimeClassInstance, type RuntimeComplexNumber, type RuntimeDummyHandle, type RuntimeStructArray, type RuntimeSparseMatrix, type RuntimeDictionary, type RuntimeValue, type FloatXArrayType } from "./types.js";
+import { type RuntimeNumber, type RuntimeTensor, type RuntimeString, type RuntimeChar, type RuntimeLogical, type RuntimeCell, type RuntimeStruct, type RuntimeFunction, type RuntimeClassInstance, type RuntimeComplexNumber, type RuntimeDummyHandle, type RuntimeGraphicsHandle, type RuntimeStructArray, type RuntimeSparseMatrix, type RuntimeDictionary, type RuntimeValue, type FloatXArrayType } from "./types.js";
 export declare const RTV: {
     num(value: number): RuntimeNumber;
     tensor(data: FloatXArrayType | number[], shape: number[], imag?: FloatXArrayType | number[]): RuntimeTensor;
@@ -25,6 +25,7 @@ export declare const RTV: {
     classInstance(className: string, propertyNames: string[], isHandleClass?: boolean, defaults?: Map<string, RuntimeValue>): RuntimeClassInstance;
     complex(re: number, im: number): RuntimeComplexNumber;
     dummyHandle(): RuntimeDummyHandle;
+    graphicsHandle(trace: Record<string, unknown>, traceType: string): RuntimeGraphicsHandle;
     structArray(fieldNames: string[], elements: RuntimeStruct[]): RuntimeStructArray;
     sparseMatrix(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array): RuntimeSparseMatrix;
     dictionary(entries?: Map<string, {

package/dist-lib/numbl-core/runtime/error.d.ts

@@ -13,6 +13,9 @@ export type CallFrame = {
     /** Trimmed source text at callerLine (populated during error enrichment) */
     callerSourceLine?: string;
 };
+export declare class CancellationError extends Error {
+    constructor();
+}
 export declare class RuntimeError extends Error {
     /** Source span where the error occurred (carries file name + per-file offsets) */
     span: Span | null;

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

@@ -1,5 +1,5 @@
 export type { RuntimeValue, RuntimeTensor, RuntimeString, RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
-export { RuntimeError, offsetToLine, offsetToColumn } from "./error.js";
+export { RuntimeError, CancellationError, offsetToLine, offsetToColumn, } from "./error.js";
 export type { CallFrame } from "./error.js";
 export { tensorSize2D, numel, colMajorIndex, shareRuntimeValue, } from "./utils.js";
 export { toNumber, toBool, toString } from "./convert.js";

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

@@ -11,7 +11,7 @@
  * runtimeDispatch.ts, and helper types/utilities in runtimeHelpers.ts.
  */
 import { type RuntimeValue, type RuntimeLogical, type RuntimeTensor, type RuntimeStruct, type RuntimeString, type RuntimeFunction, RuntimeError, type CallFrame } from "../runtime/index.js";
-import { RuntimeChar, RuntimeCell, type RuntimeComplexNumber } from "../runtime/types.js";
+import { RuntimeChar, RuntimeCell, type RuntimeComplexNumber, type RuntimeClassInstance } from "../runtime/types.js";
 import { type ItemType } from "../lowering/itemTypes.js";
 import type { PlotInstruction } from "../../graphics/types.js";
 import type { ExecOptions } from "../executeCode.js";
@@ -25,9 +25,14 @@ export declare class Runtime {
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    private cancelFlag;
     $line: number;
     $file: string | null;
     $callStack: CallFrame[];
+    _cleanupScopes: RuntimeFunction[][];
+    pushCleanupScope(): void;
+    registerCleanup(fn: RuntimeFunction): void;
+    popAndRunCleanups(callFn: (fn: RuntimeFunction) => void): void;
     COLON: symbol;
     END: symbol;
     RTV: {
@@ -44,9 +49,10 @@ export declare class Runtime {
         cell(data: RuntimeValue[], shape: number[]): RuntimeCell;
         struct(fields: Map<string, RuntimeValue> | Record<string, RuntimeValue>): RuntimeStruct;
         func(name: string, impl: "builtin" | "user", captures?: RuntimeValue[]): RuntimeFunction;
-        classInstance(className: string, propertyNames: string[], isHandleClass?: boolean, defaults?: Map<string, RuntimeValue>): import("../runtime/types.js").RuntimeClassInstance;
+        classInstance(className: string, propertyNames: string[], isHandleClass?: boolean, defaults?: Map<string, RuntimeValue>): RuntimeClassInstance;
         complex(re: number, im: number): RuntimeComplexNumber;
         dummyHandle(): import("../runtime/types.js").RuntimeDummyHandle;
+        graphicsHandle(trace: Record<string, unknown>, traceType: string): import("../runtime/types.js").RuntimeGraphicsHandle;
         structArray(fieldNames: string[], elements: RuntimeStruct[]): import("../runtime/types.js").RuntimeStructArray;
         sparseMatrix(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array): import("../runtime/types.js").RuntimeSparseMatrix;
         dictionary(entries?: Map<string, {
@@ -104,6 +110,8 @@ export declare class Runtime {
         totalTimeMs: number;
     }>;
     constructor(options: ExecOptions, initialVariableValues?: Record<string, RuntimeValue> | undefined);
+    /** Throw CancellationError if the cancel flag has been set. */
+    checkCancel(): void;
     private initBuiltins;
     profileEnter(key: string): void;
     profileLeave(): void;
@@ -139,6 +147,7 @@ export declare class Runtime {
     /** Scalar power that returns complex for negative base with fractional exponent */
     pow(a: number, b: number): number | RuntimeComplexNumber;
     share(v: unknown): RuntimeValue;
+    get displayResults(): boolean;
     displayResult(v: unknown): void;
     displayAssign(name: string, v: unknown): void;
     getConstant(name: string): RuntimeValue;
@@ -191,6 +200,8 @@ export declare class Runtime {
     buildNameValueStruct(nvArgs: unknown[], defaults: Record<string, unknown>): RuntimeStruct;
     horzcat(elems: unknown[]): unknown;
     vertcat(rows: unknown[]): unknown;
+    /** Check if any class instance in the values has a given method. */
+    private _classHasMethod;
     switchMatch(control: unknown, caseVal: unknown): boolean;
     getFuncHandle(name: string): RuntimeFunction;
     makeUserFuncHandle(jsFn: (...args: unknown[]) => unknown, nargin?: number): RuntimeFunction;
@@ -317,6 +328,8 @@ export declare class Runtime {
     piechart_call(args: RuntimeValue[]): void;
     donutchart_call(args: RuntimeValue[]): void;
     heatmap_call(args: RuntimeValue[]): void;
+    streamline_call(args: RuntimeValue[]): RuntimeValue;
+    stream2_call(args: RuntimeValue[]): RuntimeValue;
     view_call(args: RuntimeValue[]): void;
     legend_call(args: RuntimeValue[]): void;
     drawnow(): void;

package/dist-lib/numbl-core/runtime/runtimePlot.d.ts

@@ -103,3 +103,14 @@ export declare function heatmapCall(plotInstructions: PlotInstruction[], args: R
 export declare function legendCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function drawnow(plotInstructions: PlotInstruction[], options: ExecOptions): void;
 export declare function pause(seconds: unknown): void;
+/**
+ * streamline(X,Y,U,V,startX,startY) — compute and plot 2D streamlines.
+ * streamline(verts) — plot from pre-computed cell array of vertex matrices.
+ * Returns a dummy graphics handle.
+ */
+export declare function streamlineCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): RuntimeValue;
+/**
+ * stream2(X,Y,U,V,startX,startY) — compute 2D streamline vertices.
+ * Returns a cell array of Nx2 vertex matrices.
+ */
+export declare function stream2Call(args: RuntimeValue[]): RuntimeValue;