numbl 0.1.7 → 0.2.0

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

@@ -0,0 +1,122 @@
+/**
+ * AST -> JIT IR lowering with type propagation. Orchestrator that owns
+ * the shared context types (LowerCtx, SliceAlias), the public result
+ * types (GeneratedFn, LoweringResult), and the `lowerFunction` entry
+ * point. Actual statement and expression lowering lives in
+ * jitLowerStmt.ts and jitLowerExpr.ts; type-level helpers are in
+ * jitLowerTypes.ts.
+ *
+ * Returns null if any unsupported construct is encountered, causing the
+ * entire function to fall back to interpretation.
+ */
+import type { FunctionDef } from "../interpreter/types.js";
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { JitType, JitExpr, JitStmt } from "./jitTypes.js";
+import { type TypeEnv } from "./jitLowerTypes.js";
+/**
+ * Lowered IR for a user function reached during a top-level lowering.
+ *
+ * JS-JIT caches the callee as generated JS source in `generatedFns` and
+ * is done. C-JIT needs to re-analyze the callee's IR (for recursive
+ * feasibility + emitting a static C function per callee), so we also
+ * cache the raw IR here. One entry per unique `jitName`; matches the
+ * JS-JIT specialization key.
+ */
+export interface GeneratedFn {
+    fn: FunctionDef;
+    argTypes: JitType[];
+    outputNames: string[];
+    outputTypes: JitType[];
+    body: JitStmt[];
+    localVars: Set<string>;
+    nargout: number;
+}
+export interface LoweringResult {
+    body: JitStmt[];
+    outputNames: string[];
+    localVars: Set<string>;
+    hasTensorOps: boolean;
+    /** Generated JS code for called user functions: jitName → code */
+    generatedFns: Map<string, string>;
+    /** Lowered IR for called user functions: jitName → IR + metadata.
+     *  Populated alongside `generatedFns` by `lowerUserFuncCall`; the
+     *  C-JIT uses it for recursive feasibility and per-callee C emission. */
+    generatedIRBodies: Map<string, GeneratedFn>;
+    /** Type of the first output variable after lowering */
+    outputType: JitType | null;
+    /** Types of all output variables in outputNames order. Mirrors the
+     *  shape of JS-JIT's `return [out0, out1, ...]`. */
+    outputTypes: JitType[];
+    /** Final typed environment after lowering the body. The hybrid
+     *  loop-extraction pass uses this to look up live-in/live-out var
+     *  types without re-running type inference. */
+    endEnv: TypeEnv;
+}
+/**
+ * A "slice alias" records that a MATLAB local was bound to a colon-slice of
+ * a real tensor (e.g. `pt = pts(:, i)`). Rather than materializing the slice
+ * as a RuntimeTensor per iteration, we remember the base tensor and a
+ * per-dim "template" of indices — scalar expressions captured at bind time
+ * for the non-colon dims, and `"colon"` placeholders for the colon dims.
+ * Subsequent reads like `pt(k)` substitute `k` into the colon positions and
+ * emit a direct scalar read on the base tensor, which compiles cleanly
+ * through the existing hoisted `idx{1,2,3}r_h` fast path.
+ */
+export interface SliceAlias {
+    baseName: string;
+    baseType: JitType;
+    /**
+     * One entry per index of the original bind expression, in source order.
+     * A `"colon"` slot expects to be filled by the read-site's colon indices.
+     * An `"expr"` slot carries a JitExpr that will be substituted as-is.
+     */
+    template: ({
+        kind: "colon";
+    } | {
+        kind: "expr";
+        expr: JitExpr;
+    })[];
+    /** Sizes of the slice's colon dimensions, in source order. */
+    sliceShape: number[];
+    /** Indices into `template` where colon slots live, in source order. */
+    colonPositions: number[];
+}
+export interface LowerCtx {
+    env: TypeEnv;
+    localVars: Set<string>;
+    params: Set<string>;
+    /** First bail reason encountered during lowering; lets callers surface
+     *  a hint for why JS-JIT declined a function (purely diagnostic, only
+     *  consulted by the `NUMBL_LOG_CJIT_MISSES` tally). Writes should use
+     *  `setBailReason()` which is idempotent — only the first reason sticks. */
+    bailReason?: string;
+    bailLine?: number;
+    /** Type of the deepest expr whose lowering was attempted — used as a
+     *  last-resort bail reason hint when no more specific reason was set. */
+    lastExprType?: string;
+    lastExprLine?: number;
+    /** Variables that are actually assigned in the function body. */
+    assignedVars: Set<string>;
+    /**
+     * Map from a MATLAB local name to its slice alias, if any. A name is
+     * present here iff the most recent assignment to it was a whole-tensor
+     * colon slice. Reads of the name as a plain Ident bail; reads of
+     * `name(...)` substitute through the template and emit a direct scalar
+     * read of the base tensor. See `tryLowerAsSliceBind`.
+     */
+    sliceAliases: Map<string, SliceAlias>;
+    _hasTensorOps?: boolean;
+    interp?: Interpreter;
+    /** The nargout this specialization was requested with — inlined wherever
+     *  the body reads the `nargout` identifier, since the JIT specializes per
+     *  nargout already. */
+    nargout?: number;
+    generatedFns: Map<string, string>;
+    generatedIRBodies: Map<string, GeneratedFn>;
+    loweringInProgress: Set<string>;
+    /** Pre-built line break table for offset→line lookup. */
+    lineTable?: number[];
+}
+/** Idempotent bail-reason setter. Only the first reason per function sticks. */
+export declare function setBailReason(ctx: LowerCtx, reason: string, line?: number): void;
+export declare function lowerFunction(fn: FunctionDef, argTypes: JitType[], nargout: number, interp?: Interpreter, generatedFns?: Map<string, string>, loweringInProgress?: Set<string>, generatedIRBodies?: Map<string, GeneratedFn>): LoweringResult | null;

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

@@ -0,0 +1,27 @@
+/**
+ * Expression lowering for the JIT. Paired with jitLowerStmt.ts; the two
+ * sides are mutually recursive (stmt bodies contain exprs; function-call
+ * exprs may trigger nested lowering of a callee's body). jitLower.ts is
+ * the orchestrator that ties them together via LowerCtx + lowerFunction.
+ */
+import type { Expr } from "../parser/types.js";
+import { type JitExpr } from "./jitTypes.js";
+import type { LowerCtx } from "./jitLower.js";
+export declare function lowerExpr(ctx: LowerCtx, expr: Expr): JitExpr | null;
+/**
+ * Stage 21: lower `src(a:b)` on a real-tensor base into a
+ * `RangeSliceRead` IR node producing a fresh column-vector tensor.
+ *
+ * Accepts `Range` with no step (default step 1). `start` and `end`
+ * must lower to numeric/boolean scalar exprs. The result is a real
+ * tensor with shape `[?, 1]` — the exact length is runtime-dependent.
+ *
+ * Caller responsibility: match the parent expression shape
+ * `Index(Ident(src), [Range])` or `FuncCall(src, [Range])` before
+ * calling. Returns null if the source isn't a real tensor or the
+ * range isn't the expected shape.
+ */
+export declare function tryLowerRangeSliceRead(ctx: LowerCtx, baseName: string, rangeExpr: Expr): JitExpr | null;
+export declare function lowerIBuiltinCall(ctx: LowerCtx, expr: Expr & {
+    type: "FuncCall";
+}): JitExpr | null;

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

@@ -0,0 +1,9 @@
+/**
+ * Statement lowering for the JIT. Paired with jitLowerExpr.ts; the two
+ * sides are mutually recursive. jitLower.ts is the orchestrator that ties
+ * them together via LowerCtx + lowerFunction.
+ */
+import type { Stmt } from "../parser/types.js";
+import { type JitStmt } from "./jitTypes.js";
+import type { LowerCtx } from "./jitLower.js";
+export declare function lowerStmts(ctx: LowerCtx, stmts: Stmt[]): JitStmt[] | null;

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

@@ -9,8 +9,8 @@
  *
  * These have no dependency on LowerCtx or the lowering state.
  */
-import { BinaryOperation, UnaryOperation } from "../../parser/types.js";
-import { type JitType, type SignCategory } from "./jitTypes.js";
+import { BinaryOperation, UnaryOperation } from "../parser/types.js";
+import { type JitExpr, type JitType, type SignCategory } from "./jitTypes.js";
 export declare const KNOWN_CONSTANTS: Record<string, number>;
 export type TypeEnv = Map<string, JitType>;
 export declare function cloneEnv(env: TypeEnv): TypeEnv;
@@ -21,5 +21,9 @@ export declare function envsEqual(a: TypeEnv, b: TypeEnv): boolean;
 export declare function addSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
 export declare function mulSigns(a: SignCategory, b: SignCategory): SignCategory | undefined;
 export declare function combineSigns(a: SignCategory | undefined, b: SignCategory | undefined, op: BinaryOperation): SignCategory | undefined;
-export declare function binaryResultType(op: BinaryOperation, left: JitType, right: JitType): JitType | null;
+export declare function binaryResultType(op: BinaryOperation, left: JitType, right: JitType, 
+/** Lowered operand exprs. Optional because tests / older callers pass
+ *  only types. When provided, enables structural nonneg detection for
+ *  patterns like `x .* x` that the type-only path can't see. */
+leftExpr?: JitExpr, rightExpr?: JitExpr): JitType | null;
 export declare function unaryResultType(op: UnaryOperation, operand: JitType): JitType | null;

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

@@ -0,0 +1,22 @@
+/**
+ * JIT compilation for the top-level script body (the main workspace).
+ *
+ * Wraps the list of non-function, non-classdef statements of a script as
+ * a synthetic `FunctionDef` whose parameters are the live-in env vars
+ * and whose outputs are every variable assigned in the script. On
+ * success the compiled code runs once and all output values are written
+ * back to the interpreter's workspace env.
+ *
+ * Mirrors `tryJitLoop` in jitLoop.ts — same lowering, same JS/C backend
+ * pipeline, same progressive type widening. The differences:
+ *   - the synthetic body is the list of stmts directly, not a single For/While
+ *   - every assigned variable is live-out (the whole workspace is live)
+ *   - cache key is per-Interpreter (a single script AST per interp run)
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
+/**
+ * Attempt to JIT-compile and execute the top-level script body.
+ * Returns true if JIT succeeded, false to fall back to interpretation.
+ */
+export declare function tryJitTopLevel(interp: Interpreter, stmts: Stmt[]): boolean;

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

@@ -1,7 +1,7 @@
 /**
  * JIT type system and IR node definitions.
  */
-import type { BinaryOperation, UnaryOperation } from "../../parser/types.js";
+import type { BinaryOperation, UnaryOperation } from "../parser/types.js";
 export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
 export type JitType = {
     kind: "number";
@@ -55,6 +55,8 @@ export type JitType = {
     shape?: number[];
 } | {
     kind: "dictionary";
+} | {
+    kind: "function_handle";
 } | {
     kind: "unknown";
 };
@@ -125,6 +127,29 @@ export type JitExpr = {
     base: JitExpr;
     indices: JitExpr[];
     jitType: JitType;
+} | {
+    /**
+     * Range slice read on a real tensor: `src(a:b)` producing a fresh
+     * column-vector tensor of length `b - a + 1`. Stage 21 — unblocks
+     * chunkie's chunk_nearparam Newton loop which splits a Legendre
+     * expansion vector via `r0 = all0(1:dim)`.
+     *
+     * Codegen emits `$h.subarrayCopy1r(srcData, srcLen, start, end)`
+     * using the hoisted data/length aliases. Per-iter allocation is
+     * unavoidable without a range-alias extension to stage 5; small
+     * slices are cheap in V8 young-gen.
+     */
+    tag: "RangeSliceRead";
+    baseName: string;
+    start: JitExpr;
+    /** `null` when the range endpoint is the `end` keyword — codegen
+     *  substitutes the hoisted `.data.length` alias. */
+    end: JitExpr | null;
+    /** True when the source is a statically-known row vector
+     *  (shape `[1, n]`); the slice then preserves row orientation.
+     *  Otherwise the slice is a column vector (MATLAB semantics). */
+    isRow: boolean;
+    jitType: JitType;
 } | {
     tag: "TensorLiteral";
     rows: JitExpr[][];
@@ -181,6 +206,40 @@ export type JitExpr = {
     indexExpr: JitExpr;
     leafFieldName: string;
     jitType: JitType;
+} | {
+    /**
+     * Indirect call through a function handle variable: `f(a, b)` where
+     * `f` has JitType `function_handle`. The codegen emits
+     * `$h.callFuncHandle($rt, f, arg1, arg2, ...)` which invokes the
+     * handle via its `jsFn` closure (or falls back to `rt.dispatch`).
+     * The `returnType` is determined at lowering time by probing the
+     * function handle's runtime value.
+     */
+    tag: "FuncHandleCall";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
+} | {
+    /**
+     * User function call that bailed recursive lowering (stage 24 —
+     * soft-bail). Instead of bailing the containing loop, emit a
+     * runtime dispatch through the interpreter. Return type is
+     * determined at JIT compile time by probing (actually calling
+     * the function once with representative args). The helper
+     * `callUserFunc` verifies the actual return type on every call
+     * and throws `JitFuncHandleBailError` on mismatch so the loop
+     * runner can invalidate the cache entry and fall back to
+     * interpretation.
+     *
+     * Use case: `oneintp(...)` / `lege.exev(...)` in chunkie's adap
+     * inner loop — the callee body has tensor arithmetic the JIT
+     * can't inline, but the outer loop (scalar stack + col-slice
+     * writes + scalar compares) is a perfect JIT fit.
+     */
+    tag: "UserDispatchCall";
+    name: string;
+    args: JitExpr[];
+    jitType: JitType;
 };
 export type JitStmt = {
     tag: "Assign";
@@ -217,6 +276,56 @@ export type JitStmt = {
     srcType: JitType;
     srcStart: JitExpr | null;
     srcEnd: JitExpr | null;
+} | {
+    /**
+     * Multi-dim column slice write `dst(:, j) = src` where both `dst`
+     * and `src` are real tensors. LHS must be `Index(Ident(dst),
+     * [Colon, scalar_j])` with `dst` having statically 2-D shape.
+     * RHS must be a plain Ident referencing a real-tensor var whose
+     * total element count matches `dst.shape[0]` at runtime.
+     *
+     * Used by the loop JIT for chunkie's adapgausskerneval column
+     * stack write: `vals(:, jj+1) = v2`. Also covers
+     * chunkerinterior's `rss(:, jj) = rval(:, k)` after a slice
+     * alias binds the RHS.
+     */
+    tag: "AssignIndexCol";
+    baseName: string;
+    baseType: JitType;
+    colIndex: JitExpr;
+    srcBaseName: string;
+    srcType: JitType;
+} | {
+    /**
+     * Page-slice write `dst(:, :, k) = rhs` where `dst` is a 3-D tensor
+     * and `rhs` is a 2-D tensor. Real-base + complex-rhs upgrades the
+     * base to complex in place.  Drives chunkie helm2d.green's
+     * `grad(:,:,k) = ...` / `hess(:,:,k) = ...` assignments.
+     */
+    tag: "AssignIndexPage3d";
+    baseName: string;
+    /** Base tensor type AFTER the write (may be complex even if the
+     *  initializer was real — the lowerer promotes in ctx.env). */
+    baseType: JitType;
+    /** Page index (1-based). */
+    pageIndex: JitExpr;
+    /** 2-D tensor RHS. */
+    value: JitExpr;
+} | {
+    /**
+     * Struct field assign lvalue `s.f = v`. When `needsPromote` is
+     * true, the base is (re)initialized as a fresh empty struct
+     * before the field is set — mirrors MATLAB's
+     * `s = []; s.f = v` idiom that promotes the empty matrix to a
+     * struct on first field write. `valueType` is the JIT type of
+     * `value` so stage 12 can hoist subsequent reads through a
+     * typed alias.
+     */
+    tag: "AssignMember";
+    baseName: string;
+    fieldName: string;
+    value: JitExpr;
+    needsPromote: boolean;
 } | {
     tag: "If";
     cond: JitExpr;
@@ -252,9 +361,32 @@ export type JitStmt = {
     callName: string;
     args: JitExpr[];
     outputTypes: JitType[];
+} | {
+    /**
+     * Call a synthetic specialization (installed as a forwarder on $h)
+     * and write back multiple outputs into outer-scope vars. Only
+     * produced by the hybrid-loop pass in hybrid.ts, which
+     * replaces a For/While JitStmt with this call form when the
+     * extracted loop specialization compiled to native C.
+     *
+     * Semantics (0 / 1 / N outputs):
+     *   nargout==0 → emit `$h.callUser(...)` as a stmt (no writeback)
+     *   nargout==1 → emit `out = $h.callUser(...)`
+     *   nargout>=2 → emit `var $r = $h.callUser(...); out0=$r[0]; ...`
+     */
+    tag: "UserCallWriteback";
+    outputs: string[];
+    jitName: string;
+    name: string;
+    args: JitExpr[];
+    outputTypes: JitType[];
 } | {
     tag: "SetLoc";
     line: number;
+} | {
+    /** C-JIT assertion: if this JitStmt survives to JS codegen at --opt 2,
+     *  emit a runtime throw. The C-JIT codegen elides it. */
+    tag: "AssertCJit";
 };
 export interface JitCacheEntry {
     fn: (...args: unknown[]) => unknown;

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

@@ -3,5 +3,5 @@
  *
  * IR walkers for hoist-pass data collection are in jitCodegenHoist.ts.
  */
-import { type JitStmt } from "./jitTypes.js";
-export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string): string;
+import { type JitStmt } from "../jitTypes.js";
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string, fuse?: boolean, experimental?: string): string;

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

@@ -5,7 +5,7 @@
  * for hoisting tensor aliases, struct field reads, and struct array
  * element reads to the top of the generated function.
  */
-import type { JitStmt } from "./jitTypes.js";
+import type { JitStmt } from "../jitTypes.js";
 /**
  * Hoisted aliases for a tensor variable read/written in the loop body.
  * Maps the original variable name to local JS identifiers for its
@@ -33,6 +33,24 @@ export interface TensorUsage {
  * maximum indexing arity and whether all uses are on a real tensor.
  */
 export declare function collectTensorUsage(body: JitStmt[]): Map<string, TensorUsage>;
+/**
+ * Walk the JIT IR collecting every base name that is the target of an
+ * `AssignMember` stmt (stage 22 struct field write). Used by the
+ * codegen to emit a one-time `$h.structUnshare_h(s)` at function entry
+ * for any such name that is also a function parameter — this preserves
+ * MATLAB value semantics when structs are passed by value and the
+ * callee mutates a field.
+ */
+export declare function collectStructMemberWrites(body: JitStmt[]): Set<string>;
+/**
+ * Walk the JIT IR collecting every name that is the target of any
+ * plain `Assign` stmt. Used by the stage-12 struct-field-read hoist to
+ * decide whether a struct-typed param is safe to hoist: if the body
+ * ever reassigns the name (e.g. `s = [];` promoted to struct, or `s =
+ * struct()` inside the loop), the pre-loop hoisted field aliases would
+ * be stale and must be disabled.
+ */
+export declare function collectPlainAssignTargets(body: JitStmt[]): Set<string>;
 /**
  * Walk the JIT IR collecting all unique (baseName, fieldName) pairs
  * referenced by MemberRead nodes. The codegen hoists each pair as a

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

@@ -11,10 +11,22 @@
  * 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, } from "./jitHelpersIndex.js";
-export { makeTensor, tensorBinaryOp, tensorCompareOp, tensorUnary, tensorNeg, vconcatGrow1r, unshare, asTensor, tAdd, tSub, tMul, tDiv, tPow, tEq, tNeq, tLt, tLe, tGt, tGe, } from "./jitHelpersTensor.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 "../builtins/index.js";
+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).

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

@@ -10,6 +10,10 @@
  * 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;
@@ -24,3 +28,6 @@ export declare function set1r_h(data: FloatXArrayType, len: number, i: number, v
 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 = 3;
+export declare const NATIVE_ADDON_EXPECTED_VERSION = 8;
 export interface LapackBridge {
     /** Returns the native addon's version number. */
     addonVersion?(): number;
@@ -439,6 +439,44 @@ export interface LapackBridge {
         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;