numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/executors/jsJit/lower/blockAnalysis.d.ts

@@ -1,37 +0,0 @@
-/**
- * Static AST analysis to determine input/output variables for loop JIT.
- *
- * Walks the loop body (and condition for while) to collect:
- * - assigned: variables written inside the loop
- * - referenced: variables read inside the loop
- * - hasReturn: whether the loop body contains a return statement
- */
-import type { Stmt } from "../../../parser/types.js";
-export interface BlockVarInfo {
-    /** Variables referenced in the loop that must come from enclosing scope */
-    inputs: string[];
-    /** Variables assigned in the loop body (written back after JIT execution) */
-    outputs: string[];
-    /** Whether the loop body contains a return statement (skip JIT if true) */
-    hasReturn: boolean;
-}
-/** Analyze a for loop statement for JIT compilation. */
-export declare function analyzeForLoop(stmt: Stmt & {
-    type: "For";
-}): BlockVarInfo;
-/**
- * Collect the names of all variables read in a sibling-tail starting at
- * `startIdx` of the given stmt list. Used by the loop JIT to filter the
- * loop's output set so that loop-internal temporaries don't get written
- * back when no later code reads them.
- */
-export declare function collectReadsFromSiblings(stmts: Stmt[], startIdx: number, out: Set<string>): void;
-/**
- * Analyze a top-level script body (list of statements) for JIT compilation.
- * Used by `tryJitTopLevel` to wrap the whole main script as a synthetic fn.
- */
-export declare function analyzeTopLevel(stmts: Stmt[]): BlockVarInfo;
-/** Analyze a while loop statement for JIT compilation. */
-export declare function analyzeWhileLoop(stmt: Stmt & {
-    type: "While";
-}): BlockVarInfo;

package/dist-lib/numbl-core/executors/jsJit/lower/jitBailSafety.d.ts

@@ -1,41 +0,0 @@
-/**
- * Bail-safety gate for JIT bodies that contain I/O side effects.
- *
- * Mid-execution bails (JitBailToInterpreter / JitFuncHandleBailError)
- * cause the interpreter to re-run the body from the top. If the body
- * already emitted I/O before the bail, that output gets duplicated —
- * which the user would notice.
- *
- * Rule: a body with any I/O statement may only be JIT-compiled if we
- * can prove no bail can happen during execution. If there's no I/O,
- * the body can be JIT'd normally (a bail just restarts silently).
- *
- * Walkers are IR-level — they see the actual lowered constructs that
- * map 1:1 to runtime bail sites. The walkers recurse into the bodies
- * of `UserCall`-ed functions (via `generatedIRBodies`), since a bail
- * inside a callee still forces the caller to re-run.
- */
-import type { JitStmt } from "../../../jitTypes.js";
-import type { GeneratedFn } from "./jitLower.js";
-/**
- * Names of I/O-emitting builtins that the JIT is willing to lower as
- * ExprStmt calls. Any `Call` to one of these in the lowered IR marks
- * the body as having observable I/O.
- */
-export declare const JIT_IO_BUILTINS: Set<string>;
-/**
- * Walk a body + its transitively called function bodies and return
- * whether the combined execution graph contains an I/O call.
- */
-export declare function irHasIO(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;
-/**
- * Walk a body + its transitively called function bodies and return
- * whether any construct exists that can throw `JitBailToInterpreter`
- * or `JitFuncHandleBailError` at runtime.
- *
- * Bail-risky constructs:
- *   - AssignIndex / AssignIndexCol: may bail on out-of-bounds grow.
- *   - FuncHandleCall / UserDispatchCall: return-type check may bail.
- *   - UserCall: recurse into callee body.
- */
-export declare function irHasBailRisk(body: JitStmt[], generatedIRBodies: Map<string, GeneratedFn>): boolean;

package/dist-lib/numbl-core/executors/jsJit/lower/jitLower.d.ts

@@ -1,136 +0,0 @@
-/**
- * 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;
-    /** The nargin this specialization was requested with. Set whenever the
-     *  function is varargin (the call shape pins down nargin per spec).
-     *  Reads of bare `nargin` get inlined to this constant; `nargin > K`
-     *  guards then constant-fold so dead branches don't have to lower. */
-    nargin?: number;
-    /** Number of variadic args bound for this specialization (0 for
-     *  non-varargin callees). Used by `varargin{i}` lowering to redirect to
-     *  the synthetic `$va_*` param holding the i-th variadic arg. The
-     *  varargin lowering only needs the count — the synthetic name is
-     *  derived from the literal index alone. */
-    nVarargin?: 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>, varargs?: {
-    effectiveParams: string[];
-    nVarargin: number;
-}): LoweringResult | null;

package/dist-lib/numbl-core/executors/jsJit/lower/jitLowerExpr.d.ts

@@ -1,36 +0,0 @@
-/**
- * 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 { Interpreter } from "../../../interpreter/interpreter.js";
-import { type JitType, 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;
-/**
- * Multi-output variant of probeFuncHandleReturnType. Calls the handle
- * with the requested nargout and returns one JitType per output. Bails
- * (returns null) on the same conditions as the single-output probe
- * (handle without jsFn, args we can't synthesize, output containing
- * unknown), or when the result isn't an array of the expected length.
- */
-export declare function probeFuncHandleMultiReturnTypes(interp: Interpreter, fnName: string, loweredArgs: JitExpr[], nargout: number): JitType[] | null;

package/dist-lib/numbl-core/executors/jsJit/lower/jitLowerStmt.d.ts

@@ -1,9 +0,0 @@
-/**
- * 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/executors/jsJit/lower/jitLowerTypes.d.ts

@@ -1,29 +0,0 @@
-/**
- * Type-level helpers for the JIT lowering pass.
- *
- * Pure functions for:
- * - Sign algebra (how signs combine through arithmetic)
- * - Binary/unary operation result type inference
- * - Type environment management (clone, merge, equality)
- * - Known MATLAB constants
- *
- * These have no dependency on LowerCtx or the lowering state.
- */
-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;
-/** Merge two type environments at a join point. Returns null if any type becomes unknown. */
-export declare function mergeEnvs(a: TypeEnv, b: TypeEnv): TypeEnv | null;
-/** Check if two type environments are identical (by JSON comparison). */
-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, 
-/** 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/executors/jsJit/lower/scalarEmit.d.ts

@@ -1,58 +0,0 @@
-/**
- * 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/executors/jsJit/shared.d.ts

@@ -1,120 +0,0 @@
-/**
- * Shared helpers for the JS-JIT shape modules.
- *
- * The three shape modules (`jitTopLevel.ts`, `jitLoop.ts`,
- * `jitCall.ts`) all do the same handful of things — type inference
- * with `exact` pruning, progressive type widening, JS body assembly,
- * `new Function` instantiation, env writeback. Those bits live here
- * so the shape modules can stay focused on what's actually different
- * between them (synthetic-fn shape, cacheKey scheme, run-time entry).
- */
-import type { Interpreter } from "../../interpreter/interpreter.js";
-import type { Runtime } from "../../runtime/runtime.js";
-import type { JitType } from "../../jitTypes.js";
-import { type LoweringResult } from "./lower/jitLower.js";
-import type { Stmt } from "../../parser/types.js";
-/** Names that look like variables but never resolve to env values
- *  inside the JIT (constants, literals, the special `end` slot, the
- *  imaginary unit). Skipped when collecting env inputs. */
-export declare const KNOWN_CONSTANTS: ReadonlySet<string>;
-/**
- * Drop `exact` from a numeric scalar `JitType`. Numeric `exact` only
- * survives unification when two consecutive specializations see the
- * *same* literal — almost never the case for variables — so stripping
- * up front means the first specialization's cacheKey already matches
- * later calls.
- */
-export declare function pruneArgType(t: JitType): JitType;
-/**
- * Progressive type widening: in-place unify each entry of `types`
- * with the corresponding entry of `prev`. No-op when shapes don't
- * match (different arity → different specialization, no widening).
- *
- * Widening that would collapse a known type to `unknown` is rejected
- * — keep this call's concrete type so a fresh, specific spec gets
- * built. Without this, a 1st call with (number, …) followed by a 2nd
- * call with (tensor, …) would unify the first arg to `unknown` and
- * poison every subsequent specialization with the same arg shape
- * (chunkie hits this with `fcurve(ta)` (scalar discovery) followed
- * by `fcurve(ts)` (tensor)).
- */
-export declare function widenAgainst(types: JitType[], prev: readonly JitType[] | undefined): void;
-/**
- * Gather env inputs for the synthetic FunctionDef of a top-level or
- * loop block. For each candidate name: skip known constants, skip
- * names not in env (likely fn names), infer the JIT type, prune
- * `exact`. Returns null if any candidate has an unknown type — that's
- * a structural blocker for lowering.
- */
-export declare function gatherTypedEnvInputs(interp: Interpreter, candidates: readonly string[]): {
-    inputs: string[];
-    inputTypes: JitType[];
-} | null;
-/**
- * Build a `// File: …` + indented source-slice comment block for the
- * code being JIT-compiled. Used by `--dump-js` so each emitted JS
- * section is annotated with the .m source it came from. Falls back
- * gracefully when the source isn't in `interp.fileSources`.
- *
- * `start` is rewound to the beginning of its line so the first line
- * keeps its original indentation (Stmt spans start at the first
- * non-whitespace char, which would otherwise leave the first line
- * dedented relative to the rest).
- */
-export declare function buildJitSourceComment(interp: Interpreter, file: string, start: number, end: number): string;
-/**
- * Read the live env values for `inputs` in order. Used at run time
- * to bind the compiled fn's parameters before invocation.
- */
-export declare function gatherEnvValues(interp: Interpreter, inputs: readonly string[]): unknown[];
-/**
- * Build the JS body for a synthetic FunctionDef: prepend each
- * generated callee body (indented 2 spaces to nest inside the
- * outer function), then append the main body.
- */
-export declare function assembleJsBody(result: LoweringResult, mainBody: string): string;
-/**
- * Wrap a JS body string in a `new Function(...)` and bind it to the
- * runtime's helpers and `$rt`. Returns null when the body fails to
- * parse (defensive — should not happen for IR that lowering accepted).
- */
-export declare function instantiateJsFn(rt: Runtime, paramNames: readonly string[], jsBody: string): ((...args: unknown[]) => unknown) | null;
-/**
- * Write a compiled fn's return value back into the interpreter env.
- * The compiled fn returns either a single value (for one-output fns)
- * or an array of values (for multi-output) — matching the JS-JIT
- * convention used in the wrapper layer.
- */
-export declare function writeBackOutputs(interp: Interpreter, outputs: readonly string[], result: unknown): void;
-/**
- * Build a synthetic `FunctionDef` from (name, inputs, outputs, body)
- * and lower it through `lowerFunction`. Returns null when lowering
- * declines (constructs the JS-JIT IR doesn't model).
- */
-export declare function lowerSyntheticFn(interp: Interpreter, name: string, inputs: readonly string[], inputTypes: readonly JitType[], outputs: readonly string[], body: Stmt[]): LoweringResult | null;
-/**
- * Generate JS for a synthetic-fn lowered IR and instantiate it.
- * Returns null when `new Function` throws (defensive — should not
- * happen for IR that lowering accepted). Both top-level and loop
- * codegen use this; the shape module then wraps the returned fn in
- * its `*Compiled` shape and emits its own source/diagnostics.
- */
-export declare function generateSyntheticFnJS(interp: Interpreter, result: LoweringResult, inputs: readonly string[], outputCount: number): {
-    fn: (...args: unknown[]) => unknown;
-    jsBody: string;
-} | null;
-/** Outcome of `runSyntheticFnAgainstEnv`. `transient` distinguishes
- *  the recoverable JitBailToInterpreter case (cache preserved) from
- *  the hard JitFuncHandleBailError case (cache invalidated). */
-export type SyntheticFnRunResult = {
-    ok: true;
-} | {
-    ok: false;
-    transient: boolean;
-};
-/**
- * Gather input values from env, invoke the compiled fn, write back
- * outputs. Translates JIT bails to a SyntheticFnRunResult. Used by
- * both top-level and loop run phases.
- */
-export declare function runSyntheticFnAgainstEnv(interp: Interpreter, fn: (...args: unknown[]) => unknown, inputs: readonly string[], outputs: readonly string[]): SyntheticFnRunResult;

package/dist-lib/numbl-core/executors/jsJit/topLevelExecutor.d.ts

@@ -1,17 +0,0 @@
-/**
- * js-jit-top-level — JS codegen executor for the top-level shape.
- *
- *   - `propose()` filters on `lowered.kind === "top-level"`, applies
- *     JIT-feasibility checks (hasReturn, display mode + unsuppressed
- *     assigns, IO+bail-risk).
- *
- *   - `compile()` calls `generateTopLevelJS`. Cached by the registry
- *     under the classification's cacheKey.
- *
- *   - `run()` calls `runTopLevelCompiled`. JitBailToInterpreter →
- *     transient bail; JitFuncHandleBailError → permanent bail.
- *     `consumed` claims the entire script body.
- */
-import type { Executor } from "../types.js";
-import { type TopLevelLowered, type TopLevelCompiled } from "./jitTopLevel.js";
-export declare const jsJitTopLevelExecutor: Executor<TopLevelLowered, TopLevelCompiled | null>;