numbl 0.1.0 → 0.1.2

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

@@ -0,0 +1,4 @@
+/**
+ * Array construction builtins: zeros, ones, nan/NaN, eye, linspace, logspace.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Array extras: colon, tril, triu, toeplitz, magic,
+ * bitwise ops, and coordinate transforms.
+ */
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * Array manipulation builtins for the interpreter system:
+ * reshape, diag, cat, horzcat, vertcat, flip, fliplr, flipud, rot90,
+ * repmat, repelem, squeeze, circshift, permute, ipermute,
+ * ndgrid, meshgrid, sub2ind, ind2sub.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Cell/struct operation builtins: cell2mat, cell2struct, mat2cell, num2cell,
+ * struct2cell, namedargs2cell, rmfield.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Complex number builtins: real, imag, conj, angle.
+ */
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Dictionary builtins: dictionary, configureDictionary, keys, values,
+ * numEntries, isConfigured, isKey, entries, insert, lookup, remove, types.
+ */
+import { type RuntimeValue, type RuntimeDictionary } from "../../runtime/types.js";
+/** Produce a unique string key from a RuntimeValue for Map lookup. */
+export declare function hashKey(v: RuntimeValue): string;
+/** Insert a single key-value pair without expanding arrays. */
+export declare function dictInsertSingle(d: RuntimeDictionary, key: RuntimeValue, value: RuntimeValue): RuntimeDictionary;
+/** Insert key-value pairs into a dictionary, returning a new dictionary. */
+export declare function dictInsert(d: RuntimeDictionary, keysArg: RuntimeValue, valuesArg: RuntimeValue): RuntimeDictionary;
+/** Remove keys from a dictionary, returning a new dictionary. */
+export declare function dictRemove(d: RuntimeDictionary, keysArg: RuntimeValue): RuntimeDictionary;
+/** Lookup values by keys. Returns single value or tensor/cell array. */
+export declare function dictLookup(d: RuntimeDictionary, keysArg: RuntimeValue): RuntimeValue;

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

@@ -0,0 +1,7 @@
+/**
+ * Interpreter IBuiltins for FFT functions:
+ * fft, ifft, fftshift, ifftshift.
+ *
+ * Reuses the same algorithmic implementations as the legacy builtins.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Help text for builtins. Registered via registerBuiltinHelp so existing
+ * builtin definitions don't need to be modified.
+ */
+export {};

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

@@ -0,0 +1,34 @@
+/**
+ * Interpreter builtins: register all and re-export.
+ *
+ * Import order matters — each module registers its builtins on import.
+ */
+import "./math.js";
+import "./arithmetic.js";
+import "./complex.js";
+import "./predicates.js";
+import "./utility.js";
+import "./introspection.js";
+import "./array-construction.js";
+import "./reductions.js";
+import "./strings.js";
+import "./set-operations.js";
+import "./linear-algebra.js";
+import "./fft.js";
+import "./array-manipulation.js";
+import "./array-extras.js";
+import "./validation.js";
+import "./numerical.js";
+import "./type-constructors.js";
+import "./string-extras.js";
+import "./prng.js";
+import "./cell-struct.js";
+import "./time-system.js";
+import "./sparse.js";
+import "./special-math.js";
+import "./misc.js";
+import "./dictionary.js";
+import "./help-text.js";
+export { getIBuiltin, getIBuiltinHelp, getIBuiltinNargin, getAllIBuiltinNames, buildIBuiltinHelpers, setDynamicRegisterHook, registerBuiltinHelp, inferJitType, } from "./types.js";
+export type { IBuiltin, IBuiltinResolution, BuiltinHelp } from "./types.js";
+export { resetAppdataStore, convertJsonValue } from "./misc.js";

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

@@ -0,0 +1,6 @@
+/**
+ * Introspection builtins: size, length, numel, ndims, isempty, isscalar,
+ * isvector, isrow, iscolumn, ismatrix, islogical, isnumeric, isfloat,
+ * isinteger, ischar, isstring, iscell, isstruct, issparse, class.
+ */
+export {};

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

@@ -0,0 +1,9 @@
+/**
+ * Interpreter IBuiltins for linear algebra functions:
+ * norm, vecnorm, dot, det, trace, cross, inv, svd, qr, lu, eig, chol,
+ * linsolve, cond, rank, pinv, kron, blkdiag, pagemtimes, pagetranspose.
+ *
+ * These delegate to the same runtime implementations as the legacy builtins
+ * but provide JitType-level resolve() for the interpreter/JIT pipeline.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Unary math builtins: trig, hyperbolic, exp/log, rounding, abs, sqrt, sign.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+import type { RuntimeValue } from "../../runtime/types.js";
+/** Clear all appdata — called at the start of each executeCode to isolate runs. */
+export declare function resetAppdataStore(): void;
+export declare function convertJsonValue(val: unknown): RuntimeValue;

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

@@ -0,0 +1,10 @@
+/**
+ * Numerical builtins for the interpreter system:
+ * conv, deconv, polyval, polyfit, trapz, cumtrapz, gradient,
+ * interp1, roots, poly, cov, corrcoef, accumarray.
+ *
+ * These are thin wrappers that delegate to the legacy implementations
+ * (which are already well-tested) while registering as IBuiltins for
+ * proper JIT type inference.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Predicate builtins: isnan, isinf, isfinite, isreal.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * PRNG builtins: rand, randn, randi, randperm, rng.
+ */
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Interpreter IBuiltins for reduction operations:
+ * sum, prod, mean, std, var, median, mode, any, all,
+ * cumsum, cumprod, cummax, cummin, diff.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Set and search builtins for the interpreter: find, sort, setdiff, ismember.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Sparse matrix builtins: sparse, speye, spdiags, spconvert.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Special math builtins: airy, ellipj, legendre, besselj, bessely, besseli, besselk.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * String builtins that return cell arrays or have complex output modes:
+ * strsplit, strjoin, regexp, regexpi, regexprep, symvar.
+ */
+export {};

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

@@ -0,0 +1,7 @@
+/**
+ * Interpreter IBuiltins for string/char operations.
+ *
+ * Functions that involve cell arrays (strsplit, strjoin, symvar, regexp/regexpi)
+ * or the parser (symvar) are left to legacy builtins since JitType has no cell kind.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Time and system builtins: tic, toc, clock, etime, warning, computer, version,
+ * ismac, ispc, isunix.
+ */
+export {};

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

@@ -0,0 +1,5 @@
+/**
+ * Type constructor builtins: double, logical, complex, cell, struct, full,
+ * isfield, deal, func2str.
+ */
+export {};

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

@@ -0,0 +1,109 @@
+/**
+ * IBuiltin interface, registry, and shared helpers for interpreter builtins.
+ */
+import type { RuntimeValue, RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
+import { FloatXArray } from "../../runtime/types.js";
+import { type JitType } from "../jit/jitTypes.js";
+export interface IBuiltinResolution {
+    outputTypes: JitType[];
+    apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
+}
+export interface BuiltinHelp {
+    signatures: string[];
+    description: string;
+}
+export interface IBuiltin {
+    name: string;
+    help?: BuiltinHelp;
+    /** 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;
+}
+export declare function getIBuiltin(name: string): IBuiltin | undefined;
+export declare function registerIBuiltin(b: IBuiltin): void;
+/** Set a callback for dynamic IBuiltin registration (called by jitHelpers setup). */
+export declare function setDynamicRegisterHook(hook: ((b: IBuiltin) => void) | null): void;
+/** Register a dynamic IBuiltin (e.g. .js user functions), replacing any
+ *  existing entry with the same name without error. */
+export declare function registerDynamicIBuiltin(b: IBuiltin): void;
+export declare function unregisterIBuiltin(name: string): void;
+export declare function getAllIBuiltinNames(): string[];
+export declare function getIBuiltinHelp(name: string): BuiltinHelp | undefined;
+export declare function registerBuiltinHelp(name: string, help: BuiltinHelp): void;
+/** Probe an IBuiltin to determine its nargin (number of input args).
+ *  Tries resolve with 1, 2, 3 number-type args to find the accepted count. */
+export declare function getIBuiltinNargin(name: string): number | undefined;
+export declare function inferJitType(value: unknown): JitType;
+/** Build the ib_* entries for the jitHelpers object.
+ *  The returned object also has _profileEnter/_profileLeave hooks (no-ops by default)
+ *  that the runtime replaces when profiling is enabled. */
+export declare function buildIBuiltinHelpers(): Record<string, any>;
+export declare function mkc(re: number, im: number): number | RuntimeComplexNumber;
+export declare function makeTensor(data: InstanceType<typeof FloatXArray>, imag: InstanceType<typeof FloatXArray> | undefined, shape: number[]): RuntimeTensor;
+/** Type rule requiring two scalar numbers */
+export declare function binaryNumberOnly(argTypes: JitType[]): JitType[] | null;
+/** Apply a unary element-wise function with complex support */
+export declare function applyUnaryElemwise(v: RuntimeValue, realFn: (x: number) => number, complexFn: (re: number, im: number) => {
+    re: number;
+    im: number;
+}, name: string): RuntimeValue;
+/** Apply a binary scalar function */
+export declare function applyBinaryScalar(args: RuntimeValue[], fn: (a: number, b: number) => number, name: string): RuntimeValue;
+/** Apply a binary element-wise function supporting scalars, tensors, and broadcast. */
+export declare function applyBinaryElemwise(args: RuntimeValue[], fn: (a: number, b: number) => number, name: string): RuntimeValue;
+/** Match a binary function accepting number/boolean/tensor args (no complex). */
+export declare function binaryElemwiseMatch(argTypes: JitType[]): JitType[] | null;
+/** A single case in a builtin's dispatch table. Bundles type-level matching
+ *  with runtime implementation so the two paths cannot diverge. */
+export interface BuiltinCase {
+    /** Return output types if this case handles the given arg types, or null. */
+    match: (argTypes: JitType[], nargout: number) => JitType[] | null;
+    /** Runtime implementation — only called when match succeeded. */
+    apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
+}
+/** Register an IBuiltin from a list of cases. The first matching case wins. */
+export declare function defineBuiltin(opts: {
+    name: string;
+    help?: BuiltinHelp;
+    cases: BuiltinCase[];
+    jitEmit?: (argCode: string[], argTypes: JitType[]) => string | null;
+}): void;
+type NumberJitType = Extract<JitType, {
+    kind: "number";
+}>;
+type BooleanJitType = Extract<JitType, {
+    kind: "boolean";
+}>;
+type ComplexJitType = Extract<JitType, {
+    kind: "complex_or_number";
+}>;
+type TensorJitType = Extract<JitType, {
+    kind: "tensor";
+}>;
+interface UnaryElemwiseSpec {
+    numberType?: (a: NumberJitType) => JitType | null;
+    booleanType?: (a: BooleanJitType) => JitType | null;
+    complexType?: (a: ComplexJitType) => JitType | null;
+    tensorType?: (a: TensorJitType) => JitType | null;
+    realFn: (x: number) => number;
+    complexFn: (re: number, im: number) => {
+        re: number;
+        im: number;
+    };
+    /** Use applyUnaryElemwiseMaybeComplex instead of applyUnaryElemwise */
+    maybeComplex?: boolean;
+}
+/** Generate cases for a unary element-wise builtin. Each accepted kind gets
+ *  its own case that bundles the type rule with the corresponding apply. */
+export declare function unaryElemwiseCases(spec: UnaryElemwiseSpec, name: string): BuiltinCase[];
+/** Shorthand: build cases where all kinds return always-real output. */
+export declare function unaryRealResultCases(realFn: (x: number) => number, complexFn: (re: number, im: number) => number, name: string): BuiltinCase[];
+/** 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;
+/** Fast-path emitter for binary Math.* functions on two scalar numbers. */
+export declare function binaryMathJitEmit(mathFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Utility builtins for JIT: isequal, assert, error, abs.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * Validation builtins: mustBe* family.
+ */
+export {};

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

@@ -0,0 +1,146 @@
+/**
+ * AST-walking interpreter for MATLAB code.
+ *
+ * Walks the parsed AST directly without lowering or codegen.
+ * All dispatch decisions are made at runtime using actual values.
+ *
+ * Reuses LoweringContext and FunctionIndex from the lowering pipeline
+ * for workspace registration, class extraction, and function resolution.
+ *
+ * The Interpreter class is defined here with all fields.
+ * Methods are split across:
+ *   - interpreterExec.ts   (statement + expression evaluation)
+ *   - interpreterFunctions.ts (function call, resolution, class methods)
+ */
+import type { AbstractSyntaxTree } from "../parser/types.js";
+import type { Runtime } from "../runtime/runtime.js";
+import type { RuntimeValue } from "../runtime/types.js";
+import type { LoweringContext, FunctionIndex } from "../lowering/loweringContext.js";
+import { type ResolvedTarget } from "../functionResolve.js";
+import { Environment, type FunctionDef, type ControlSignal } from "./types.js";
+import type { Stmt, Expr, LValue } from "../parser/types.js";
+import type { ClassInfo } from "../lowering/classInfo.js";
+export declare class Interpreter {
+    /** @internal */ env: Environment;
+    ans: RuntimeValue | undefined;
+    /** @internal */ ctx: LoweringContext;
+    /** @internal */ functionIndex: FunctionIndex;
+    /** @internal */ rt: Runtime;
+    /** @internal */ currentFile: string;
+    /** @internal */ currentClassName: string | undefined;
+    /** @internal */ currentMethodName: string | undefined;
+    /** @internal */ mainLocalFunctions: Map<string, FunctionDef>;
+    /** @internal The main script (workspace) environment — for evalin/assignin('workspace', ...) */
+    workspaceEnv: Environment | undefined;
+    /** @internal The caller's environment — for evalin/assignin('caller', ...) */
+    callerEnv: Environment | undefined;
+    /** @internal Stack of [base, dimIndex, numIndices] for resolving `end` keyword in indexing. */
+    endContextStack: Array<{
+        base: unknown;
+        dimIndex: number;
+        numIndices: number;
+    }>;
+    /** @internal */
+    functionDefCache: Map<string, FunctionDef>;
+    /** @internal Pre-built line break tables for offset→line lookup per file. */
+    lineTableCache: Map<string, number[]>;
+    /** @internal file→source mapping for line number computation */
+    fileSources: Map<string, string>;
+    /** @internal Guard against infinite recursion in compileSpecialized */
+    compileInProgress: Set<string>;
+    /** @internal Per-instance cache for JIT-compiled loops (avoids cross-execution collisions). */
+    loopJitCache: Map<string, {
+        fn: (...args: unknown[]) => unknown;
+        source: string;
+    } | 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). */
+    optimization: number;
+    /** Callback for JIT compilation logging. */
+    onJitCompile?: (description: string, jsCode: 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;
+    /** Wire up runtime callbacks so dispatch() routes through the interpreter. */
+    installRuntimeCallbacks(): void;
+    /** Run a complete AST (main script). */
+    run(ast: AbstractSyntaxTree): void;
+    /** Get variable values for ExecResult. */
+    getVariableValues(): Record<string, RuntimeValue>;
+    execStmt: (stmt: Stmt) => ControlSignal | null;
+    execStmts: (stmts: Stmt[]) => ControlSignal | null;
+    evalExpr: (expr: Expr) => unknown;
+    evalExprNargout: (expr: Expr, nargout: number) => unknown;
+    evalBinary: (expr: Extract<Expr, {
+        type: "Binary";
+    }>) => unknown;
+    evalUnary: (expr: Extract<Expr, {
+        type: "Unary";
+    }>) => unknown;
+    evalRange: (expr: Extract<Expr, {
+        type: "Range";
+    }>) => unknown;
+    evalFuncCall: (expr: Extract<Expr, {
+        type: "FuncCall";
+    }>, nargout: number) => unknown;
+    evalIndex: (expr: Extract<Expr, {
+        type: "Index";
+    }>) => unknown;
+    evalIndexCell: (expr: Extract<Expr, {
+        type: "IndexCell";
+    }>) => unknown;
+    evalIndicesWithEnd: (base: unknown, indexExprs: Expr[]) => unknown[];
+    evalArgs: (argExprs: Expr[]) => unknown[];
+    evalMember: (expr: Extract<Expr, {
+        type: "Member";
+    }>, nargout: number) => unknown;
+    tryExtractDottedName: (expr: Expr) => string | null;
+    evalAnonFunc: (expr: Extract<Expr, {
+        type: "AnonFunc";
+    }>) => RuntimeValue;
+    makeFuncHandle: (name: string) => RuntimeValue;
+    evalTensorLiteral: (expr: Extract<Expr, {
+        type: "Tensor";
+    }>) => unknown;
+    evalCellLiteral: (expr: Extract<Expr, {
+        type: "Cell";
+    }>) => unknown;
+    assignLValue: (lv: LValue, value: RuntimeValue) => void;
+    writeLValueBase: (base: Expr, value: RuntimeValue) => void;
+    evalLValueBase: (base: Expr, defaultVal: RuntimeValue) => unknown;
+    switchMatch: (switchVal: unknown, caseVal: unknown) => boolean;
+    isOutputExpr: (expr: Expr) => boolean;
+    callFunction: (name: string, args: unknown[], nargout: number) => unknown;
+    interpretTarget: (target: ResolvedTarget, args: unknown[], nargout: number) => unknown;
+    interpretLocalFunction: (target: Extract<ResolvedTarget, {
+        kind: "localFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretWorkspaceFunction: (target: Extract<ResolvedTarget, {
+        kind: "workspaceFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretClassMethod: (target: Extract<ResolvedTarget, {
+        kind: "classMethod";
+    }>, args: unknown[], nargout: number) => unknown;
+    interpretPrivateFunction: (target: Extract<ResolvedTarget, {
+        kind: "privateFunction";
+    }>, args: unknown[], nargout: number) => unknown;
+    instantiateClass: (className: string, args: unknown[], nargout: number) => unknown;
+    interpretConstructor: (classInfo: ClassInfo, args: unknown[], nargout: number) => unknown;
+    callUserFunction: (fn: FunctionDef, args: unknown[], nargout: number, narginOverride?: number) => unknown;
+    callNestedFunction: (fn: FunctionDef, parentEnv: Environment, args: unknown[], nargout: number) => unknown;
+    withFileContext: <T>(file: string, className: string | undefined, methodName: string | undefined, fn: () => T) => T;
+    getWorkspaceFileName: (funcName: string) => string;
+    getClassFileName: (className: string) => string;
+    findFunctionInWorkspaceFile: (wsName: string, funcName: string) => FunctionDef | null;
+    findFunctionInClassFile: (className: string, funcName: string, methodScope?: string) => FunctionDef | null;
+    findMethodInClass: (classInfo: ClassInfo, methodName: string) => FunctionDef | null;
+    findExternalMethod: (classInfo: ClassInfo, methodName: string) => FunctionDef | null;
+    collectClassProperties: (classInfo: ClassInfo) => {
+        propertyNames: string[];
+        propertyDefaults: Map<string, Expr>;
+    };
+    isHandleClass: (classInfo: ClassInfo) => boolean;
+    evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
+    processArgumentsBlocks: (fn: FunctionDef, args: unknown[]) => unknown[];
+}

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

@@ -0,0 +1,51 @@
+/**
+ * Interpreter statement execution and expression evaluation methods.
+ * Augments the Interpreter class via prototype assignment.
+ */
+import type { Stmt, Expr, LValue } from "../parser/types.js";
+import type { RuntimeValue } from "../runtime/types.js";
+import { type ControlSignal } from "./types.js";
+import type { Interpreter } from "./interpreter.js";
+export declare function execStmt(this: Interpreter, stmt: Stmt): ControlSignal | null;
+export declare function execStmts(this: Interpreter, stmts: Stmt[]): ControlSignal | null;
+export declare function evalExpr(this: Interpreter, expr: Expr): unknown;
+export declare function evalExprNargout(this: Interpreter, expr: Expr, nargout: number): unknown;
+export declare function evalArgs(this: Interpreter, argExprs: Expr[]): unknown[];
+export declare function evalBinary(this: Interpreter, expr: Extract<Expr, {
+    type: "Binary";
+}>): unknown;
+export declare function evalUnary(this: Interpreter, expr: Extract<Expr, {
+    type: "Unary";
+}>): unknown;
+export declare function evalRange(this: Interpreter, expr: Extract<Expr, {
+    type: "Range";
+}>): unknown;
+export declare function evalFuncCall(this: Interpreter, expr: Extract<Expr, {
+    type: "FuncCall";
+}>, nargout: number): unknown;
+export declare function evalMember(this: Interpreter, expr: Extract<Expr, {
+    type: "Member";
+}>, nargout: number): unknown;
+export declare function tryExtractDottedName(this: Interpreter, expr: Expr): string | null;
+export declare function evalIndex(this: Interpreter, expr: Extract<Expr, {
+    type: "Index";
+}>): unknown;
+export declare function evalIndexCell(this: Interpreter, expr: Extract<Expr, {
+    type: "IndexCell";
+}>): unknown;
+export declare function evalIndicesWithEnd(this: Interpreter, base: unknown, indexExprs: Expr[]): unknown[];
+export declare function evalAnonFunc(this: Interpreter, expr: Extract<Expr, {
+    type: "AnonFunc";
+}>): RuntimeValue;
+export declare function makeFuncHandle(this: Interpreter, name: string): RuntimeValue;
+export declare function evalTensorLiteral(this: Interpreter, expr: Extract<Expr, {
+    type: "Tensor";
+}>): unknown;
+export declare function evalCellLiteral(this: Interpreter, expr: Extract<Expr, {
+    type: "Cell";
+}>): unknown;
+export declare function assignLValue(this: Interpreter, lv: LValue, value: RuntimeValue): void;
+export declare function writeLValueBase(this: Interpreter, base: Expr, value: RuntimeValue): void;
+export declare function evalLValueBase(this: Interpreter, base: Expr, defaultVal: RuntimeValue): unknown;
+export declare function switchMatch(this: Interpreter, switchVal: unknown, caseVal: unknown): boolean;
+export declare function isOutputExpr(this: Interpreter, expr: Expr): boolean;

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

@@ -0,0 +1,41 @@
+/**
+ * Interpreter function call, resolution, and class method methods.
+ * Augments the Interpreter class via prototype assignment.
+ */
+import type { Expr } from "../parser/types.js";
+import { type ResolvedTarget } from "../functionResolve.js";
+import type { ClassInfo } from "../lowering/classInfo.js";
+import { Environment, type FunctionDef } from "./types.js";
+import type { Interpreter } from "./interpreter.js";
+export declare function callFunction(this: Interpreter, name: string, args: unknown[], nargout: number): unknown;
+export declare function interpretTarget(this: Interpreter, target: ResolvedTarget, args: unknown[], nargout: number): unknown;
+export declare function interpretLocalFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "localFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretWorkspaceFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "workspaceFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretClassMethod(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "classMethod";
+}>, args: unknown[], nargout: number): unknown;
+export declare function interpretPrivateFunction(this: Interpreter, target: Extract<ResolvedTarget, {
+    kind: "privateFunction";
+}>, args: unknown[], nargout: number): unknown;
+export declare function instantiateClass(this: Interpreter, className: string, args: unknown[], nargout: number): unknown;
+export declare function interpretConstructor(this: Interpreter, classInfo: ClassInfo, args: unknown[], nargout: number): unknown;
+export declare function callUserFunction(this: Interpreter, fn: FunctionDef, args: unknown[], nargout: number, narginOverride?: number): unknown;
+export declare function callNestedFunction(this: Interpreter, fn: FunctionDef, parentEnv: Environment, args: unknown[], nargout: number): unknown;
+export declare function withFileContext<T>(this: Interpreter, file: string, className: string | undefined, methodName: string | undefined, fn: () => T): T;
+export declare function getWorkspaceFileName(this: Interpreter, funcName: string): string;
+export declare function getClassFileName(this: Interpreter, className: string): string;
+export declare function findFunctionInWorkspaceFile(this: Interpreter, wsName: string, funcName: string): FunctionDef | null;
+export declare function findFunctionInClassFile(this: Interpreter, className: string, funcName: string, methodScope?: string): FunctionDef | null;
+export declare function findMethodInClass(this: Interpreter, classInfo: ClassInfo, methodName: string): FunctionDef | null;
+export declare function findExternalMethod(this: Interpreter, classInfo: ClassInfo, methodName: string): FunctionDef | null;
+export declare function collectClassProperties(this: Interpreter, classInfo: ClassInfo): {
+    propertyNames: string[];
+    propertyDefaults: Map<string, Expr>;
+};
+export declare function isHandleClass(this: Interpreter, classInfo: ClassInfo): boolean;
+export declare function evalInLocalScope(this: Interpreter, codeArg: unknown, fileName?: string): unknown;
+export declare function processArgumentsBlocks(this: Interpreter, fn: FunctionDef, args: unknown[]): unknown[];

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

@@ -0,0 +1,18 @@
+/**
+ * Interpreter special builtins: functions that need access to interpreter
+ * context (env, callerEnv, etc.) and run before normal function resolution.
+ */
+import type { Environment } from "./types.js";
+import type { Runtime } from "../runtime/runtime.js";
+export interface InterpreterContext {
+    env: Environment;
+    setEnv: (env: Environment) => void;
+    callerEnv: Environment | undefined;
+    workspaceEnv: Environment | undefined;
+    evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
+    callFunction: (name: string, args: unknown[], nargout: number) => unknown;
+    rt: Runtime;
+}
+export declare const FALL_THROUGH: unique symbol;
+export type InterpreterSpecialBuiltinHandler = (ctx: InterpreterContext, args: unknown[], nargout: number) => unknown | typeof FALL_THROUGH;
+export declare function getInterpreterSpecialBuiltin(name: string): InterpreterSpecialBuiltinHandler | undefined;

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

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

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

@@ -0,0 +1,5 @@
+/**
+ * JIT IR -> JavaScript code generation.
+ */
+import { type JitStmt } from "./jitTypes.js";
+export declare function generateJS(body: JitStmt[], params: string[], outputs: string[], nargout: number, localVars: Set<string>, fileName?: string): string;

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

@@ -0,0 +1,5 @@
+/**
+ * Runtime helpers for JIT-compiled tensor and complex operations.
+ * Passed as `$h` to generated functions.
+ */
+export declare const jitHelpers: Record<string, unknown>;

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

@@ -0,0 +1,25 @@
+/**
+ * JIT compilation for inline for/while loops.
+ *
+ * When the interpreter encounters a for or while loop, these functions
+ * attempt to JIT-compile the loop as a synthetic function: inputs are
+ * variables from the enclosing scope, outputs are variables assigned
+ * inside the loop body. On success the compiled code runs and output
+ * values are written back to the interpreter environment.
+ */
+import type { Interpreter } from "../interpreter.js";
+import type { Stmt } from "../../parser/types.js";
+/**
+ * Attempt to JIT-compile and execute a for-loop statement.
+ * Returns true if JIT succeeded, false to fall back to interpretation.
+ */
+export declare function tryJitFor(interp: Interpreter, stmt: Stmt & {
+    type: "For";
+}): boolean;
+/**
+ * Attempt to JIT-compile and execute a while-loop statement.
+ * Returns true if JIT succeeded, false to fall back to interpretation.
+ */
+export declare function tryJitWhile(interp: Interpreter, stmt: Stmt & {
+    type: "While";
+}): boolean;