numbl 0.4.7 → 0.4.9

package/dist-browser/numbl-core/executors/registry.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Executor registry and dispatch.
+ *
+ * Three entry points, three concerns:
+ *   - `dispatch(siblings, i, ctx)` — per-stmt dispatch. Each executor
+ *     handles exactly one stmt (no consumed-N).
+ *   - `dispatchCall(fn, args, nargout, interp)` — user-function call.
+ *   - `tryRunWholeScope(siblings, interp)` — whole-script attempt,
+ *     called once before the per-stmt loop runs. Top-level executors
+ *     register here separately from per-stmt ones.
+ *
+ * Plugins register executors at startup; the dispatcher selects among
+ * them at runtime based on cost estimates. The AST interpreter is the
+ * always-matching last-resort fallback for per-stmt dispatch and isn't
+ * a registered executor.
+ */
+import type { Stmt } from "../parser/types.js";
+import type { ControlSignal, FunctionDef } from "../interpreter/types.js";
+import type { Executor } from "./types.js";
+import { DispatchContext } from "./context.js";
+/** AST stmt-list transformer. Receives a stmt list and returns a
+ *  list of the same semantics, possibly with `Synth` stmts inserted
+ *  where the transformer can collapse a contiguous run of stmts into
+ *  a unit handled by a specialized executor. The transform is
+ *  shallow — recursive descent into For/While/If bodies happens
+ *  lazily on the next call to `transformStmts`, cached separately. */
+export type StmtTransformer = (stmts: readonly Stmt[]) => Stmt[];
+export interface DispatchResult {
+    /** Control signal from interpreter execution (break/continue/return),
+     *  if any. */
+    signal: ControlSignal | null;
+}
+/** Result from `dispatchCall`. `null` means no executor handled the
+ *  call — the caller should fall through to its own
+ *  interpreter-execution path. */
+export type CallDispatchResult = {
+    result: unknown;
+} | null;
+/** Result from `tryRunWholeScope`. `null` means no whole-scope
+ *  executor matched (or all bailed) — the caller should fall through
+ *  to the per-stmt dispatch loop. */
+export type WholeScopeResult = {
+    signal: ControlSignal | null;
+} | null;
+export declare class Registry {
+    /** Per-stmt executors (loop, call, fuse). */
+    private readonly executors;
+    /** Whole-scope executors (top-level). Iterated only by
+     *  `tryRunWholeScope`, separate from per-stmt dispatch. */
+    private readonly wholeScopeExecutors;
+    /** AST stmt-list transformers. Run lazily on each stmt list before
+     *  the per-stmt loop walks it; result cached per input list. */
+    private readonly transformers;
+    /** Memoize transformed lists by input list identity. WeakMap so
+     *  entries vanish when the AST is dropped. The transformed list
+     *  is also stored mapped to itself so a second call with the
+     *  result hits the cache (idempotency). */
+    private transformCache;
+    private cache;
+    private loweringCache;
+    /** Pre-allocated context reused for `dispatchCall`. Avoids the
+     *  per-call Map+Set allocation cost that previously motivated
+     *  bypassing ctx entirely on call-heavy workloads. Safe to reuse
+     *  because dispatchCall isn't reentrant within itself: each call's
+     *  propose/compile/run touches the context synchronously, and any
+     *  nested call dispatch goes through `Interpreter.callUserFunction`
+     *  which re-enters dispatchCall and re-resets the context. */
+    private callCtx;
+    register(executor: Executor): void;
+    /** Register an executor that handles a whole stmt list as a unit
+     *  (e.g. JS-JIT top-level). Iterated only by `tryRunWholeScope`
+     *  and never seen by per-stmt dispatch. */
+    registerWholeScope(executor: Executor): void;
+    /** Register an AST stmt-list transformer. Transformers run on every
+     *  stmt list the interpreter is about to walk (script body, function
+     *  body, loop body, if branch, ...) before the per-stmt loop kicks
+     *  in. They typically wrap contiguous runs of stmts in `Synth`
+     *  nodes that a matching executor will recognize. Adding new
+     *  transformers is additive — they compose in registration order. */
+    registerStmtTransformer(fn: StmtTransformer): void;
+    /** Transform a stmt list, applying all registered transformers in
+     *  registration order. Cached per input-list identity (WeakMap).
+     *  When no transformers are registered, returns the input unchanged
+     *  without populating the cache (saves a Map lookup per dispatch). */
+    transformStmts(stmts: readonly Stmt[]): Stmt[];
+    /** Number of registered per-stmt executors. Mainly for tests. */
+    get size(): number;
+    /** Drop all cached compiled artifacts. Called from
+     *  `Interpreter.clearAllCaches()` after addpath/rmpath etc. */
+    clearCache(): void;
+    /**
+     * Dispatch one statement at `siblings[i]`. Each executor handles
+     * exactly one stmt — the dispatcher always advances by one on
+     * success.
+     *
+     * Hot path. Two optimizations matter for the chunkie-helmholtz-
+     * scale workloads:
+     *
+     *   1. The AST interpreter is the always-applicable last-resort
+     *      fallback. It is *not* a registered executor — the dispatcher
+     *      hardcodes a direct call to `ctx.interp.execStmt(stmt)` when
+     *      no specialized executor matches or all of them bail. This
+     *      avoids per-dispatch match/Candidate/cache/result allocations
+     *      for the most common path (where only the interpreter would
+     *      fit anyway).
+     *
+     *   2. The reentrancy guard (`pushActive`/`popActive` /
+     *      `isActive`) is short-circuited when the active set is
+     *      empty — no sub-dispatch in flight means the bookkeeping is
+     *      pure overhead.
+     */
+    dispatch(siblings: readonly Stmt[], i: number, ctx: DispatchContext): DispatchResult;
+    private runStmtCandidate;
+    /** Cache lookup + compile-on-miss + run + bail handling. Returns
+     *  the executor's success RunResult, or null when the candidate
+     *  bailed (cache may have been marked BAILED). When `guardKey` is
+     *  non-null, the reentrancy guard pushes/pops around `run()` —
+     *  passed by the stmt path; the call path passes null because
+     *  `dispatchCall` isn't reentrant within itself. */
+    private executeCandidate;
+    /**
+     * Dispatch a user-function call. Iterates the same `executors`
+     * array as stmt dispatch — call-shape executors filter on
+     * `lowered.kind === "call"`. Returns `{ result }` when one of them
+     * handles the call, or `null` so the caller (callUserFunction)
+     * falls through to the AST interpreter.
+     *
+     * Reuses a pre-allocated DispatchContext (`callCtx`) to avoid the
+     * per-call Map+Set allocation that previously motivated bypassing
+     * ctx for call dispatch entirely.
+     */
+    dispatchCall(fn: FunctionDef, args: unknown[], nargout: number, interp: import("../interpreter/interpreter.js").Interpreter): CallDispatchResult;
+    private runCallCandidate;
+    private getCallCtx;
+    /**
+     * Whole-scope dispatch: try to handle the entire stmt list as a
+     * single unit (e.g. JS-JIT top-level). Called by the Interpreter
+     * once before the per-stmt loop runs. Returns:
+     *   - `{ signal }` when a whole-scope executor handled the body.
+     *     The caller should skip the per-stmt loop entirely.
+     *   - `null` when no whole-scope executor matched (or all bailed).
+     *     The caller falls through to per-stmt dispatch.
+     */
+    tryRunWholeScope(siblings: readonly Stmt[], interp: import("../interpreter/interpreter.js").Interpreter): WholeScopeResult;
+    private finishWholeScope;
+}
+/** Build a fresh dispatch context. */
+export declare function makeRootContext(interp: import("../interpreter/interpreter.js").Interpreter, registry: Registry): DispatchContext;

package/dist-browser/numbl-core/executors/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Executor registry — core types.
+ *
+ * See docs/developer_reference/executors.md for the design overview.
+ *
+ * The interpreter delegates each statement (or run of statements) — and
+ * each user-function call — to a registry of Executors. Each executor
+ * implements one strategy (interpreter, JS-JIT, C-kernel, ...). On each
+ * dispatch, every executor may submit a Proposal; the dispatcher picks
+ * the lowest-cost. Stmt-shape and call-shape work share the same
+ * Executor interface — they're discriminated via the lowered statement
+ * passed to propose().
+ */
+import type { DispatchContext } from "./context.js";
+import type { LoweredStmt } from "./lowering.js";
+/** Estimated cost of using this executor for the proposed work.
+ *  Numbers can be very rough at first; the dispatcher's policy is
+ *  refined separately from executors. */
+export interface CostEstimate {
+    /** One-time compile cost on cache miss. */
+    compileMs: number;
+    /** Per-call dispatch overhead (marshaling, frame setup, ...). */
+    perCallNs: number;
+    /** Estimated work done by the compiled artifact for the proposed
+     *  input sizes. */
+    runNs: number;
+}
+/** Reason a `run` invocation could not complete. The dispatcher
+ *  invalidates the cache entry and tries the next-best candidate. */
+export interface BailReason {
+    message: string;
+    cause?: unknown;
+}
+export type RunResult = 
+/** Stmt-shape success — handled the head stmt. Registered executors
+ *  don't produce control signals (break/continue/return); only the
+ *  hardcoded interpreter fallback in `Registry.dispatch` does.
+ *  The dispatcher always advances by exactly one stmt on success. */
+{
+    ok: true;
+}
+/** Call-shape success — used by executors that handle a
+ *  CallLoweredStmt. The dispatcher's call entry point
+ *  (`dispatchCall`) returns this `result` to the caller. */
+ | {
+    result: unknown;
+} | {
+    bail: BailReason;
+    /** When true, the bail is not cached: future dispatches re-enter
+     *  the executor as if cache had never been touched. Use for
+     *  shim/wrapper executors whose internal classify logic must
+     *  re-run on every call (e.g., because the wrapped layer caches
+     *  on its own keying scheme). Default false. */
+    transient?: boolean;
+};
+/** An executor's bid to handle the current dispatch. The dispatcher
+ *  picks the lowest-cost proposal; the executor's own `data` flows
+ *  through to compile() and run() unchanged. */
+export interface Proposal<D> {
+    /** Opaque per-executor data; passed to compile() and run(). */
+    data: D;
+    cost: CostEstimate;
+    /** Whether this specific proposal's compiled artifact may fail an
+     *  invariant mid-execution (and thus need re-running by a fallback).
+     *  The dispatcher filters bail-risk proposals out of contexts marked
+     *  `requireNoBail`. Per-proposal because a single executor may
+     *  produce both bail-risky and bail-safe proposals depending on the
+     *  inputs it sees. */
+    bailRisk: boolean;
+}
+export interface Executor<D = unknown, C = unknown> {
+    /** Stable identifier for logging, cache keys, and test selection. */
+    readonly name: string;
+    /** Submit a bid to handle this stmt. Runs on every dispatch — must
+     *  be cheap.
+     *
+     *  Receives the lowered statement produced by the dispatcher's
+     *  pre-propose lowering pass. The `kind` field discriminates: a
+     *  specialized shape (e.g. `"top-level"`) carries a lowered IR
+     *  plus pre-computed feasibility flags; the fallback `"stmt"` kind
+     *  carries the raw AST stmt for executors that classify from the
+     *  AST directly.
+     *
+     *  Codegen-feasibility decisions (display mode, IO+bail-risk, etc.)
+     *  belong here — the lowering pipeline produces an IR; the
+     *  executor decides whether to commit. For lookahead across
+     *  multiple stmts, use `ctx.peekSibling(offset)` or `ctx.siblings`.
+     *
+     *  Returns null to decline. */
+    propose(lowered: LoweredStmt, ctx: DispatchContext): Proposal<D> | null;
+    /** Stable cache key projected from the proposal data. Drops
+     *  volatile bits (e.g., exact scalar values; tensor shape if
+     *  codegen is shape-agnostic) so unrelated runs of the same code
+     *  reuse compiled artifacts. */
+    cacheKey(data: D): string;
+    /** Compile to a runnable artifact. Called only on cache miss.
+     *  Cached under (executor, headStmt, cacheKey). */
+    compile(data: D, ctx: DispatchContext): C;
+    /** Execute. Returns the number of consumed sibling stmts on success,
+     *  or a Bail signalling the cache entry should be invalidated and
+     *  the next-best candidate tried. */
+    run(compiled: C, data: D, ctx: DispatchContext): RunResult;
+}

package/dist-browser/numbl-core/externalAccessDirective.d.ts

@@ -0,0 +1,6 @@
+export interface ExternalAccessDirectives {
+    /** Variable names declared at file/script scope (outside any function) */
+    fileScope: Set<string>;
+    /** Function name -> variable names declared within that function */
+    functionScope: Map<string, Set<string>>;
+}

package/dist-browser/numbl-core/fileIOAdapter.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Platform-agnostic file I/O adapter interface.
+ *
+ * numbl-core defines this interface but never imports Node.js fs.
+ * Concrete implementations (e.g. NodeFileIOAdapter) are injected
+ * from the CLI or other host environments via ExecOptions.fileIO.
+ */
+/** Options extracted from a weboptions struct for websave/webread. */
+export interface WebOptions {
+    timeout?: number;
+    requestMethod?: string;
+    headerFields?: [string, string][];
+    username?: string;
+    password?: string;
+    keyName?: string;
+    keyValue?: string;
+}
+/** Subset of MATLAB's fileattrib attribute struct. `Name` is the resolved
+ *  absolute path. */
+export interface FileAttribInfo {
+    Name: string;
+    directory: boolean;
+    UserRead: boolean;
+    UserWrite: boolean;
+    UserExecute: boolean;
+}
+export interface FileIOAdapter {
+    /** Open a file, returns an integer file identifier (fid). */
+    fopen(filename: string, permission: string): number;
+    /** Close a file (or 'all'). Returns 0 on success, -1 on error. */
+    fclose(fid: number | "all"): number;
+    /** Read one line, stripping the newline. Returns -1 at EOF. */
+    fgetl(fid: number): string | number;
+    /** Read one line, keeping the newline. Returns -1 at EOF. */
+    fgets(fid: number): string | number;
+    /** Read an entire file as a string. */
+    fileread(filename: string): string;
+    /** Returns 1 if at EOF, 0 otherwise. */
+    feof(fid: number): number;
+    /** Returns the error message string for the last operation on fid. */
+    ferror(fid: number): string;
+    /** Write a string to a file descriptor (used by fprintf). */
+    fwrite(fid: number, text: string): void;
+    /** Read raw bytes from a file. Returns the bytes actually read (may be fewer than count at EOF). Optional. */
+    freadBytes?(fid: number, count: number): Uint8Array;
+    /** Write raw bytes to a file. Returns number of bytes written. Optional. */
+    fwriteBytes?(fid: number, data: Uint8Array): number;
+    /** Seek to a position in a file. origin: -1=bof, 0=cof, 1=eof. Returns 0 on success, -1 on error. Optional. */
+    fseek?(fid: number, offset: number, origin: number): number;
+    /** Return current file position. Optional. */
+    ftell?(fid: number): number;
+    /** Scan a directory for workspace files (.m, .js, .wasm). Optional. */
+    scanDirectory?(dirPath: string): import("../numbl-core/workspace/index.js").WorkspaceFile[];
+    /** Resolve a path to absolute. Optional. */
+    resolvePath?(dirPath: string): string;
+    /** Check whether a path exists and whether it is a file or directory. Optional. */
+    existsPath?(path: string): "file" | "dir" | null;
+    /** Create a directory (and parents). Returns true on success. Optional. */
+    mkdir?(dirPath: string): boolean;
+    /** Download a URL to a file. Optional. */
+    websave?(url: string, filename: string, options?: WebOptions): void;
+    /** Fetch content from a URL and return as a string. Optional. */
+    webread?(url: string, options?: WebOptions): string;
+    /** Delete files matching a pattern (supports globs). Optional. */
+    deleteFile?(pattern: string): void;
+    /** Remove a directory. If recursive is true, remove contents first. Returns true on success. Optional. */
+    rmdir?(dirPath: string, recursive: boolean): boolean;
+    /** Move or rename a file or folder. If force is true, overwrites read-only files. Returns true on success. Optional. */
+    movefile?(source: string, destination: string, force: boolean): boolean;
+    /** Copy a file or folder. If force is true, overwrites read-only files. Returns true on success. Optional. */
+    copyfile?(source: string, destination: string, force: boolean): boolean;
+    /** Resolve a file/dir to its absolute path and attributes, or null if it does not exist. Optional. */
+    fileattrib?(path: string): FileAttribInfo | null;
+    /** Extract a ZIP file to an output folder. Returns list of extracted file paths. Optional. */
+    unzip?(zipfilename: string, outputfolder: string): string[];
+    /** Return the temporary directory path. Optional. */
+    tempdir?(): string;
+    /** Return the numbl user/config directory path. Optional. */
+    userpath?(): string;
+    /** List directory entries. Returns array of {name, folder, bytes, isdir, mtimeMs}. Optional. */
+    listDir?(dirPath: string): {
+        name: string;
+        folder: string;
+        bytes: number;
+        isdir: boolean;
+        mtimeMs: number;
+    }[];
+}

package/dist-browser/numbl-core/functionResolve.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Unified function resolution.
+ *
+ * Single source of truth for resolving a function name + arg types + call site
+ * to a definitive target. Used by both codegen (compile-time) and JIT (runtime).
+ */
+import type { FunctionIndex } from "./lowering/loweringContext.js";
+import type { CallSite } from "./runtime/runtimeHelpers.js";
+import type { ItemType } from "./lowering/itemTypes.js";
+export type ResolvedTarget = {
+    kind: "classMethod";
+    className: string;
+    methodName: string;
+    compileArgTypes: ItemType[];
+    stripInstance: boolean;
+} | {
+    kind: "localFunction";
+    name: string;
+    argTypes: ItemType[];
+    source: {
+        from: "main";
+    } | {
+        from: "classFile";
+        className: string;
+        methodScope?: string;
+    } | {
+        from: "workspaceFile";
+        wsName: string;
+    } | {
+        from: "privateFile";
+        callerFile: string;
+    };
+} | {
+    kind: "privateFunction";
+    name: string;
+    argTypes: ItemType[];
+    callerFile: string;
+} | {
+    kind: "workspaceFunction";
+    name: string;
+    argTypes: ItemType[];
+} | {
+    kind: "jsUserFunction";
+    name: string;
+    argTypes: ItemType[];
+} | {
+    /** mtoc2-only user function (.mtoc2.js). Numbl's interpreter
+     *  rejects calls to this kind; mtoc2's loader picks up the source
+     *  from the workspace registry and evaluates it. */
+    kind: "mtoc2UserFunction";
+    name: string;
+    argTypes: ItemType[];
+} | {
+    kind: "workspaceClassConstructor";
+    className: string;
+    argTypes: ItemType[];
+} | {
+    kind: "builtin";
+    name: string;
+};
+/**
+ * Definitively resolve a function name to a single target using the FunctionIndex.
+ * Returns null only if the function is truly not found.
+ *
+ * @param name - Function name to resolve
+ * @param argTypes - Argument types (may include undefined for unknown)
+ * @param callSite - Where the call originates
+ * @param index - The upfront function index
+ */
+export declare function resolveFunction(name: string, argTypes: ItemType[], callSite: CallSite, index: FunctionIndex): ResolvedTarget | null;

package/dist-browser/numbl-core/helpers/arithmetic.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Arithmetic, comparison, and related internal helpers.
+ */
+import { type RuntimeValue } from "../runtime/types.js";
+/** Add two RuntimeValues */
+export declare function mAdd(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Subtract two RuntimeValues */
+export declare function mSub(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Multiply two RuntimeValues (matrix multiply for 2D tensors, scalar otherwise) */
+export declare function mMul(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise multiply */
+export declare function mElemMul(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Divide */
+export declare function mDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise divide */
+export declare function mElemDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Left division (mldivide): a \ b — for scalars b/a, for matrices solve a*x = b */
+export declare function mLeftDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise left division (ldivide): a .\ b = b ./ a */
+export declare function mElemLeftDiv(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Power */
+export declare function mPow(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Element-wise power */
+export declare function mElemPow(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/** Negation */
+export declare function mNeg(v: RuntimeValue): RuntimeValue;
+/** Transpose (non-conjugate for complex scalars and tensors) */
+export declare function mTranspose(v: RuntimeValue): RuntimeValue;
+/** Conjugate transpose (Hermitian transpose) - transposes and conjugates */
+export declare function mConjugateTranspose(v: RuntimeValue): RuntimeValue;
+export declare function mEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mNotEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mLess(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mLessEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mGreater(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+export declare function mGreaterEqual(a: RuntimeValue, b: RuntimeValue): RuntimeValue;
+/**
+ * Check if two shapes are compatible for broadcasting and compute the output shape.
+ * Broadcasting: dimensions must be equal or one of them must be 1.
+ * Returns null if shapes are incompatible, otherwise returns the broadcast shape.
+ */
+export declare function getBroadcastShape(shapeA: number[], shapeB: number[]): number[] | null;
+/**
+ * Iterate over all elements of a broadcast result in column-major order,
+ * calling `visit(aIdx, bIdx, outIdx)` for each output element.
+ */
+export declare function broadcastIterate(aShape: number[], bShape: number[], outShape: number[], visit: (aIdx: number, bIdx: number, outIdx: number) => void): void;

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

@@ -0,0 +1,49 @@
+/**
+ * Bessel function implementations (pure numeric, no runtime dependencies).
+ *
+ * Provides besselj, bessely, besseli, besselk for real-valued arguments.
+ *
+ * The rational polynomial approximations for J0, J1, Y0, Y1 are derived from
+ * the Cephes Math Library Release 2.8 (June 2000) by Stephen L. Moshier.
+ * Original Cephes code: Copyright 1984-2000 by Stephen L. Moshier.
+ * Used under the BSD license with permission of the author.
+ *
+ * The underlying minimax polynomial coefficients are based on the work of
+ * W.J. Cody, "Algorithm 715: SPECFUN", ACM Trans. Math. Software 19(1),
+ * pp. 22-32, 1993.
+ */
+export declare function lanczosGamma(x: number): number;
+export declare function besselj(nu: number, x: number): number;
+export declare function bessely(nu: number, x: number): number;
+export declare function besseli(nu: number, x: number): number;
+export declare function besselk(nu: number, x: number): number;
+/**
+ * Airy function of the first kind, Ai(x).
+ */
+export declare function airyAi(x: number): number;
+/**
+ * Derivative of Airy function of the first kind, Ai'(x).
+ */
+export declare function airyAiPrime(x: number): number;
+/**
+ * Airy function of the second kind, Bi(x).
+ */
+export declare function airyBi(x: number): number;
+/**
+ * Derivative of Airy function of the second kind, Bi'(x).
+ */
+export declare function airyBiPrime(x: number): number;
+interface CR {
+    re: number;
+    im: number;
+}
+/**
+ * Compute all four complex Airy functions at once: Ai(z), Ai'(z), Bi(z), Bi'(z).
+ */
+export declare function airyAllComplex(zr: number, zi: number): {
+    ai: CR;
+    aip: CR;
+    bi: CR;
+    bip: CR;
+};
+export {};

package/dist-browser/numbl-core/helpers/check-helpers.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Helpers for writing builtin check functions.
+ * These make check implementations shorter and easier to read.
+ */
+import { RTV, RuntimeValue } from "../runtime/index.js";
+/** Ensure data is Float64Array (needed by LAPACK bridges). */
+export declare function toF64(data: Float64Array): Float64Array;
+/**
+ * Extract and normalize a string argument at runtime.
+ * Strips surrounding quotes and lowercases the result.
+ * Works with both raw string args and RuntimeChar/RuntimeString values.
+ */
+export declare function parseStringArgLower(arg: unknown): string;
+/**
+ * Parse runtime economy-mode argument (0 or 'econ') used by qr, svd, etc.
+ * Returns true for economy mode, false otherwise.
+ */
+export declare function parseEconArgRuntime(arg: RuntimeValue | undefined): boolean;
+/**
+ * Build a (possibly complex) eigenvector matrix from LAPACK's packed real format.
+ *
+ * For complex conjugate eigenvalue pairs, LAPACK stores eigenvectors as:
+ *   Column j:   real part
+ *   Column j+1: imaginary part
+ * Eigenvector for eigenvalue j   is V(:,j) + i*V(:,j+1)
+ * Eigenvector for eigenvalue j+1 is V(:,j) - i*V(:,j+1)
+ */
+export declare function buildEigenvectorMatrix(packedV: Float64Array, wi: Float64Array, n: number, hasComplex: boolean): import("../runtime/types.js").RuntimeTensor;
+/**
+ * Build a tensor, attaching the imaginary part only when it contains non-zero values.
+ * Replaces the repeated `hasComplex ? RTV.tensor(re, shape, im) : RTV.tensor(re, shape)` pattern.
+ */
+export declare function maybeComplexTensor(re: Float64Array | Float64Array, shape: number[], im: Float64Array | Float64Array | undefined): ReturnType<typeof RTV.tensor>;
+/**
+ * Build a diagonal matrix from a vector of values (column-major).
+ * For square matrices pass just n; for rectangular pass [rows, cols].
+ * Optionally includes an imaginary diagonal.
+ */
+export declare function buildDiagMatrix(realVals: Float64Array | Float64Array, imagVals: Float64Array | Float64Array | undefined, size: number | [number, number]): ReturnType<typeof RTV.tensor>;
+/**
+ * In-place Gauss-Jordan elimination with partial pivoting on a column-major
+ * augmented matrix [A | B] of size `rows × totalCols`.
+ */
+export declare function gaussJordanEliminate(aug: Float64Array, rows: number, totalCols: number): void;
+/**
+ * Call a registered builtin from within another builtin's apply().
+ * Convenience wrapper that includes the caller name in error messages.
+ */
+export declare function applyBuiltin(caller: string, name: string, args: RuntimeValue[], nargout: number): RuntimeValue;

package/dist-browser/numbl-core/helpers/constants.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in constant values
+ */
+import { RuntimeValue } from "../runtime/index.js";
+export declare function getConstant(name: string): RuntimeValue | undefined;
+export declare function getAllConstantNames(): string[];

package/dist-browser/numbl-core/helpers/dummy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Dummy no-op built-in function names.
+ * Used as placeholders for unsupported functionality.
+ */
+export declare function getDummyBuiltinNames(): string[];

package/dist-browser/numbl-core/helpers/effectively-real.d.ts

@@ -0,0 +1,25 @@
+/**
+ * "Effectively real" helpers.
+ *
+ * numbl's JIT cannot always prove at compile time that the result of an
+ * operation is real (e.g. `sqrt(1 - x.^2/2)` — the argument's sign is not
+ * statically provable, so `sqrt` lifts to the complex path). The result is
+ * a complex-typed tensor whose imaginary lane is entirely zero — an
+ * artifact of static typing, not a value the user asked to be complex.
+ *
+ * Value-sensitive builtins (`isreal`, `min`, `max`, `sort`, …) must treat
+ * such a tensor exactly as they would a real one: otherwise `min`/`max`
+ * silently switch to magnitude ordering and `isreal` reports `false`,
+ * diverging from the interpreter (`--opt 0`, which never creates the
+ * artifact) and from MATLAB on real data. These helpers detect the
+ * all-zero imaginary lane and drop it so the real code path runs.
+ */
+import type { RuntimeValue } from "../runtime/index.js";
+import { type RuntimeTensor } from "../runtime/types.js";
+/** True when `imag` is absent or every element is exactly zero. */
+export declare function imagAllZero(imag: ArrayLike<number> | undefined): boolean;
+/** If `t` carries an all-zero imaginary lane, return a real view sharing
+ *  its data; otherwise return `t` unchanged. */
+export declare function stripZeroImagTensor(t: RuntimeTensor): RuntimeTensor;
+/** Tensor-aware variant for the generic `RuntimeValue` channel. */
+export declare function stripZeroImagValue(v: RuntimeValue): RuntimeValue;

package/dist-browser/numbl-core/helpers/eigs-select.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Selection + ordering logic for `eigs` (a subset of eigenvalues).
+ *
+ * `eigs` in numbl piggybacks on the dense `eig`: the runtime computes every
+ * eigenvalue, then this module picks the requested `k` of them according to
+ * `sigma` and returns their original indices in the order `eigs` reports
+ * them. It is pure (operates on plain number arrays) so it can be unit
+ * tested without the runtime.
+ */
+export type SigmaKind = "largestabs" | "smallestabs" | "largestreal" | "smallestreal" | "bothendsreal" | "largestimag" | "smallestimag" | "bothendsimag";
+export type SigmaSpec = {
+    kind: SigmaKind;
+} | {
+    kind: "scalar";
+    re: number;
+    im: number;
+};
+/** Map a text sigma value to a canonical kind, or `null` if unrecognized. */
+export declare function normalizeSigmaString(s: string): SigmaKind | null;
+/**
+ * Pick `k` eigenvalues (by original index) and return them in the order
+ * `eigs` reports for the given `sigma`. `re`/`im` are the real/imaginary
+ * parts of all `n` eigenvalues.
+ */
+export declare function selectEigsIndices(re: number[], im: number[], k: number, sigma: SigmaSpec): number[];

package/dist-browser/numbl-core/helpers/erf.d.ts

@@ -0,0 +1,5 @@
+export declare const erfScalar: (x: number) => number;
+export declare const erfcScalar: (x: number) => number;
+export declare const erfinvScalar: (x: number) => number;
+export declare const erfcinvScalar: (x: number) => number;
+export declare const erfcxScalar: (x: number) => number;