numbl 0.4.8 → 0.4.9

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

@@ -0,0 +1,108 @@
+/**
+ * Entry point for code execution.
+ *
+ * Parses source, sets up the LoweringContext and Runtime,
+ * creates an Interpreter, and runs the AST.
+ */
+import type { RuntimeValue } from "./runtime/index.js";
+import type { PlotInstruction } from "../graphics/types.js";
+import type { FileIOAdapter } from "./fileIOAdapter.js";
+import type { SystemAdapter } from "./systemAdapter.js";
+import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
+import type { NativeBridge } from "./workspace/index.js";
+import { type UihtmlSession } from "./runtime/uihtmlSession.js";
+export type { UihtmlSession } from "./runtime/uihtmlSession.js";
+export interface ExecOptions {
+    onOutput?: (text: string) => void;
+    onDrawnow?: (plotInstructions: PlotInstruction[]) => void;
+    displayResults?: boolean;
+    maxIterations?: number;
+    initialVariableValues?: Record<string, RuntimeValue>;
+    /** Optional callback for verbose compilation logging. */
+    log?: (message: string) => void;
+    /** Enable profiling of builtin function calls. */
+    profile?: boolean;
+    /** Called each time a JIT function is compiled, with a description, the
+     *  generated source, and the backend language (`"js"` or `"c"`). */
+    onJitCompile?: (description: string, code: string, lang: "js" | "c") => void;
+    /** Called when a JIT-compiled unit bails to the interpreter at runtime
+     *  (e.g. an indexed-store array growth the JIT can't model). Surfaced
+     *  as a warning; the CLI routes it to stderr. */
+    onJitBail?: (message: string) => void;
+    /** Initial hold state for plotting (persisted across REPL executions). */
+    initialHoldState?: boolean;
+    /** Override or add builtins for this execution only. */
+    customBuiltins?: Record<string, (nargout: number, args: any[]) => any>;
+    /** Platform-specific file I/O adapter (e.g. Node.js fs). */
+    fileIO?: FileIOAdapter;
+    /** Platform-specific system adapter (env vars, cwd, platform info). */
+    system?: SystemAdapter;
+    /** Synchronous callback for the `input()` builtin. Displays prompt, returns user's line. */
+    onInput?: (prompt: string) => string;
+    /** Optimization mode: `"0"` interpreter, `"1"` JS-JIT, `"2"` C-JIT. */
+    optimization?: import("./executors/plugins.js").OptLevel;
+    /**
+     * Initial implicit cwd path for the MATLAB-style "cwd is the first search path" feature.
+     * - undefined → auto-detect from `system.cwd()` and scan its files.
+     * - a string → use this absolute path as the implicit cwd (REPL persistence).
+     * - null → opt out of the implicit-cwd behavior entirely.
+     */
+    implicitCwdPath?: string | null;
+    /** SharedArrayBuffer for cooperative cancellation. Int32[0] != 0 means cancelled. */
+    cancelSAB?: SharedArrayBuffer;
+    /** Hook for `sendEventToHTMLSource(src,name,data)` — pushes an event from a
+     *  uihtml callback back to the component's page (MATLAB → JS). `dataJson` is
+     *  the data already `jsonencode`d. The host forwards it to the iframe. */
+    onHtmlSourceEvent?: (compId: string, name: string, dataJson: string) => void;
+}
+export interface BuiltinProfileEntry {
+    totalTimeMs: number;
+    callCount: number;
+}
+export interface BuiltinProfileBreakdown {
+    /** Calls from the registry fallback (rt.builtins). */
+    fallback: BuiltinProfileEntry;
+    /** Calls from the interpreter (IBuiltin.resolve → apply). */
+    interp: BuiltinProfileEntry;
+    /** Calls from JIT-compiled code (ib_* helpers). */
+    jit: BuiltinProfileEntry;
+}
+export interface HotLoopEntry {
+    file: string;
+    line: number;
+    kind: "for" | "while";
+    iterations: number;
+    callCount: number;
+    totalTimeMs: number;
+}
+export interface ProfileData {
+    executionTimeMs: number;
+    jitCompileTimeMs: number;
+    builtins: Record<string, BuiltinProfileBreakdown>;
+    dispatches: Record<string, BuiltinProfileEntry>;
+    hotLoops: HotLoopEntry[];
+}
+export interface ExecResult {
+    output: string[];
+    generatedJS: string;
+    /** C source emitted by the C-JIT backend (`--opt 2`). Empty placeholder
+     *  when no C was generated (e.g. `--opt 0`/`1`). */
+    generatedC: string;
+    plotInstructions: PlotInstruction[];
+    returnValue: RuntimeValue;
+    variableValues: Record<string, RuntimeValue>;
+    holdState: boolean;
+    profileData?: ProfileData;
+    dispatchUnknownCounts?: Record<string, number>;
+    /** Updated search paths (set when addpath/rmpath was called). */
+    searchPaths?: string[];
+    /** Updated workspace files (set when addpath/rmpath was called). */
+    workspaceFiles?: WorkspaceFile[];
+    /** Final implicit cwd path (for REPL persistence across commands). */
+    implicitCwdPath?: string | null;
+    /** Present when the run left `uihtml` reverse-channel callbacks registered.
+     *  The host retains this to dispatch later iframe events into the still-live
+     *  interpreter (see UihtmlSession). Absent for normal runs (no overhead). */
+    uihtmlSession?: UihtmlSession;
+}
+export declare function executeCode(source: string, options?: ExecOptions, workspaceFiles?: WorkspaceFile[], mainFileName?: string, searchPaths?: string[], nativeBridge?: NativeBridge): ExecResult;

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

@@ -0,0 +1,26 @@
+/**
+ * Per-executor compilation cache.
+ *
+ * Keyed by (executor, owner, cacheKey). The `owner` is the object the
+ * cache entry's lifetime is tied to:
+ *   - For stmt dispatch: the head Stmt at `siblings[i]`.
+ *   - For function-call dispatch: the FunctionDef.
+ *
+ * WeakMap scoping ensures entries are reclaimed when the owner is
+ * garbage-collected (e.g., when an AST is dropped after addpath).
+ *
+ * Each registered executor gets its own slot in the cache; a single
+ * owner can host entries from multiple executors with different
+ * specializations.
+ */
+declare const BAILED: unique symbol;
+type Bailed = typeof BAILED;
+export declare class ExecutorCache {
+    /** owner → executorName → cacheKey → compiled artifact (or BAILED) */
+    private readonly slots;
+    get(executorName: string, owner: object, key: string): unknown | undefined;
+    set(executorName: string, owner: object, key: string, compiled: unknown): void;
+    markBailed(executorName: string, owner: object, key: string): void;
+    isBailed(value: unknown): value is Bailed;
+}
+export {};

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

@@ -0,0 +1,134 @@
+/**
+ * Classification (JS-JIT-independent).
+ *
+ * Two classification phases — top-level (whole-script) and call
+ * (user-function-call) — produce the analysis records that codegen
+ * executors consume to decide whether they can lower a stmt list /
+ * call and to key their caches.
+ *
+ * The analysis is purely AST + type inference and is consumed by the
+ * JIT executors (`executors/jit/`) — no backend-specific IR involved.
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { FunctionDef } from "../interpreter/types.js";
+import type { Stmt, Expr } from "../parser/types.js";
+import { type JitType } from "../jitTypes.js";
+/** A capture-free function handle the JIT inlines into the spec body as
+ *  an in-scope `@...` constant instead of taking it as a runtime input.
+ *  `identity` keys the spec cache (distinct handles → distinct specs). */
+export interface ConstHandle {
+    readonly name: string;
+    readonly expr: Expr;
+    readonly identity: string;
+}
+/** Names that look like variables but never resolve to env values
+ *  (constants, 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.
+ */
+export declare function widenAgainst(types: JitType[], prev: readonly JitType[] | undefined): void;
+/**
+ * Gather env inputs for the synthetic FunctionDef of a top-level
+ * 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;
+export interface TopLevelClassification {
+    readonly stmts: readonly Stmt[];
+    readonly inputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly outputs: readonly string[];
+    readonly currentFile: string;
+    readonly hasReturn: boolean;
+    /** Body contains a `%!numbl:assert_jit c` directive (the C-JIT
+     *  variant) — see `containsAssertJitC`. Makes the JS-JIT executors
+     *  decline at `--opt 2` so the unit must C-JIT (or fall to the
+     *  interpreter, which raises). */
+    readonly assertsCJit: boolean;
+    readonly cacheKey: string;
+}
+export declare function classifyTopLevel(interp: Interpreter, stmts: readonly Stmt[], prevInputTypes: readonly JitType[] | undefined): TopLevelClassification | null;
+export interface LoopClassification {
+    /** The single For/While stmt this classification describes. */
+    readonly stmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly inputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    /** Loop-local writes that are read by code AFTER the loop in the
+     *  same sibling list. Loop-internal-only temporaries are filtered
+     *  out so a JIT artifact doesn't need to write them back to env. */
+    readonly outputs: readonly string[];
+    readonly currentFile: string;
+    readonly hasReturn: boolean;
+    /** Loop body contains a `%!numbl:assert_jit c` directive (C-JIT variant). */
+    readonly assertsCJit: boolean;
+    /** Capture-free handle inputs to inline as in-scope `@...` constants
+     *  in the synthesized spec body (instead of runtime inputs). */
+    readonly constHandles: readonly ConstHandle[];
+    readonly cacheKey: string;
+}
+/**
+ * Classify a single For/While loop at `siblings[siblingIndex]`. The
+ * post-loop tail of the sibling list is scanned to filter the
+ * loop's assigned-set down to names that are actually live-out
+ * (read after the loop) — purely loop-internal scratch never makes
+ * it into the synthetic function's outputs.
+ */
+export declare function classifyLoop(interp: Interpreter, stmt: Stmt & {
+    type: "For" | "While";
+}, siblings: readonly Stmt[], siblingIndex: number, prevInputTypes: readonly JitType[] | undefined): LoopClassification | null;
+export interface CallClassification {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly cacheKey: string;
+    /**
+     * Effective parameter names for this specialization. Mirrors
+     * `fn.params` for non-varargin functions. For varargin functions,
+     * the trailing `varargin` is replaced with one synthetic name per
+     * variadic arg (`$va_0`, `$va_1`, …). argTypes is one-to-one with
+     * effectiveParams.
+     */
+    readonly effectiveParams: readonly string[];
+    /** Number of variadic args (0 when fn has no varargin). */
+    readonly nVarargin: number;
+    /** Function body contains a `%!numbl:assert_jit c` directive (C-JIT variant). */
+    readonly assertsCJit: boolean;
+}
+export declare function classifyCall(fn: FunctionDef, args: unknown[], nargout: number, prevArgTypes: readonly JitType[] | undefined): CallClassification | null;
+/** True if any statement in `stmts` is a `%!numbl:assert_jit c` directive
+ *  (the C-JIT variant), recursing into control-flow bodies (if / for /
+ *  while / switch / try) but NOT into nested function definitions — a
+ *  directive inside a nested function belongs to that function's own unit.
+ *
+ *  Only the `c` variant matters here: it requires C-JIT at `--opt 2`, so
+ *  the JS-JIT executors decline such a unit at `--opt 2` to force either
+ *  C-JIT or an interpreter fallthrough (which then raises). The plain
+ *  `%!numbl:assert_jit` (require JS-JIT at `--opt 1` only) needs no
+ *  executor change — the interpreter's `Directive` handler raises if it
+ *  reaches the directive at `--opt 1`. */
+export declare function containsAssertJitC(stmts: readonly Stmt[]): boolean;

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

@@ -0,0 +1,76 @@
+/**
+ * Dispatch context — passed to every executor call.
+ *
+ * Provides env access, type-info queries, sub-dispatch into the
+ * registry, and runtime callbacks. Memoizes type-info lookups for the
+ * lifetime of a single dispatch so repeated `typeOf(name)` calls from
+ * different executors don't re-infer.
+ */
+import type { Interpreter } from "../interpreter/interpreter.js";
+import type { Stmt } from "../parser/types.js";
+import type { ControlSignal } from "../interpreter/types.js";
+import type { Registry } from "./registry.js";
+import { type JitType } from "../jitTypes.js";
+export declare class DispatchContext {
+    readonly interp: Interpreter;
+    readonly registry: Registry;
+    /** When true, only no-bail executors are eligible. Set when the
+     *  caller's compiled artifact has emitted observable side effects
+     *  that mustn't repeat. */
+    readonly requireNoBail: boolean;
+    /** Per-dispatch memoization of typeOf(name) lookups. */
+    private readonly typeCache;
+    /** Re-entrancy guard: which executors are currently running on
+     *  which head stmts. Prevents an executor sub-dispatching back into
+     *  itself on the same stmt. */
+    private readonly active;
+    /** Sibling list and head index for the current dispatch. Set by
+     *  Registry.dispatch before calling executors; read by peekSibling.
+     *  Most executors don't read these directly. */
+    private _siblings;
+    private _i;
+    constructor(interp: Interpreter, registry: Registry, requireNoBail: boolean, active?: Set<string>);
+    /** Look up a name's JitType from the interpreter env, memoized. */
+    typeOf(name: string): JitType;
+    /** Read a value from env (no inference). Returns undefined if unbound. */
+    envValue(name: string): unknown;
+    /** Peek at a sibling stmt at `offset` from the current head.
+     *  offset=0 is the current stmt; positive values look ahead.
+     *  Returns null if the offset is past the end of the scope. Used by
+     *  chain-style executors that may consume multiple consecutive
+     *  stmts. */
+    peekSibling(offset: number): Stmt | null;
+    /** Sibling list of the current scope. The head stmt is at
+     *  `siblings[headIndex]`. Most executors don't need this directly —
+     *  use `peekSibling(offset)` for lookahead. The rare cases that
+     *  forward the raw list to a legacy adapter (the chain executor) or
+     *  claim the whole scope (the top-level executor) read these. */
+    get siblings(): readonly Stmt[];
+    get headIndex(): number;
+    /** @internal Set the position state for an upcoming dispatch. Only
+     *  the registry calls this. */
+    _setPosition(siblings: readonly Stmt[], i: number): void;
+    /** Reset per-dispatch state so this context can be reused for the
+     *  next stmt in a sibling loop. The reentrancy guard is expected to
+     *  already be empty (every pushActive is paired with a popActive in
+     *  Registry.runCandidate's finally). */
+    resetForNextDispatch(): void;
+    /** Construct a child context for sub-dispatch. `requireNoBail` is
+     *  the OR of the parent flag and the parent executor's
+     *  `requireNoBailInChildren` declaration. */
+    childContext(requireNoBail: boolean): DispatchContext;
+    /** @internal Whether the reentrancy guard has any entries. The
+     *  registry uses this to skip the guard check on the hot path —
+     *  when nothing is active there's nothing to detect. */
+    get hasActive(): boolean;
+    /** @internal Used by the registry's reentrancy guard. Pre-checked
+     *  with hasActive on the hot path, so the actual `has` only fires
+     *  during sub-dispatch. */
+    isActive(executorName: string, stmt: Stmt): boolean;
+    /** @internal */
+    pushActive(executorName: string, stmt: Stmt): void;
+    /** @internal */
+    popActive(executorName: string, stmt: Stmt): void;
+}
+/** Re-export for the runner's signal type. */
+export type { ControlSignal };

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

@@ -0,0 +1,58 @@
+/**
+ * Function-handle inlining for the JIT.
+ *
+ * A function handle that crosses a compile boundary — a loop input
+ * (`f = @...; for ...; f(x); end`) or a call argument
+ * (`applyfn(@sq, x)`) — arrives at the executor as an opaque
+ * `function_handle` value the JIT can't type. But a *capture-free*
+ * handle is fully described by its source AST, so instead of marshaling
+ * it across the boundary we inline its `@...` definition as an in-scope
+ * handle constant inside the synthesized spec. That reduces the boundary
+ * case to the already-supported in-scope case (`lowerAnonFunc` /
+ * `lowerFuncHandle` + `dispatchHandleCall`), which lowers identically on
+ * the JS and C backends — no value-adapter or ABI work.
+ *
+ * "Capture-free" is the key constraint: a handle that closes over an
+ * outer variable can't be inlined, because the inlined copy would
+ * re-resolve that name in the spec's scope (a different value, or
+ * unresolved) rather than the by-value snapshot the handle took. We
+ * detect captures against the handle's own recorded definition
+ * environment, so the test reflects what the handle actually closed
+ * over, not a syntactic guess.
+ *
+ * A second constraint applies at the relocation site. A body name that
+ * is NOT a variable in the def env resolves at definition time to a
+ * function (or is undefined). After relocation into the loop's synthetic
+ * scope, that same name may be bound as a variable (a loop input or
+ * assigned local). Re-lowering would then capture the loop variable
+ * instead of resolving the function/undefined the handle saw — silently
+ * turning `@(t) sq(t)` from a function call into an array index, or
+ * masking an undefined-variable error. So the caller passes the set of
+ * names that will be in scope at the relocation site, and we decline
+ * when a free body name collides with it. A name that is purely a
+ * function (never an env variable) is not in that set, so the common
+ * `@(t) sq(t)` case still inlines; only the genuine shadowing case
+ * declines (and falls back to the interpreter).
+ */
+import type { Expr } from "../parser/index.js";
+/**
+ * If `val` is a function handle the JIT can inline as a compile-time
+ * constant in a spec compiled for `compileFile`, return its `@...`
+ * defining Expr; otherwise return null.
+ *
+ * Inlinable iff:
+ *  - it's a `RuntimeFunction` carrying a recorded `handleAst`, AND
+ *  - it was defined in `compileFile` (so a `@name` target resolves to
+ *    the same function it did at definition — file-local functions can
+ *    shadow across files), AND
+ *  - for an anonymous handle, it is capture-free: no name its body
+ *    references (other than its own params) exists as a variable in the
+ *    handle's recorded definition environment, AND no free body name
+ *    collides with `relocScopeNames` (the names that will be in scope
+ *    where the handle is inlined).
+ *
+ * Named (`@name`) handles are always capture-free. Anything the lowerer
+ * ultimately can't compile (e.g. a builtin target) simply makes the
+ * enclosing unit decline to the interpreter — still correct.
+ */
+export declare function inlinableHandleExpr(val: unknown, compileFile: string, relocScopeNames?: ReadonlySet<string>): Expr | null;

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

@@ -0,0 +1,14 @@
+/**
+ * Executor registry — public surface.
+ *
+ * See docs/developer_reference/executors.md for the design.
+ */
+export type { Executor, CostEstimate, BailReason, RunResult, Proposal, } from "./types.js";
+export { Registry, makeRootContext } from "./registry.js";
+export type { DispatchResult, CallDispatchResult, WholeScopeResult, } from "./registry.js";
+export { DispatchContext } from "./context.js";
+export { ExecutorCache } from "./cache.js";
+export type { JitType, SignCategory } from "../jitTypes.js";
+export { jitTypeKey, unifyJitTypes, isScalarType, isTensorType, isComplexType, isKnownInteger, } from "../jitTypes.js";
+export { inferJitType } from "../interpreter/builtins/types.js";
+export { registerExecutorsForOpt } from "./plugins.js";

package/dist-browser/numbl-core/executors/jit/cJitCallExecutor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * cjit-call — C-backed JIT executor for user-function calls.
+ *
+ * Mirrors `callExecutor.ts` (the JS-emit sibling) but routes the
+ * specialization's emitted code through `compileSpecC` →
+ * `cc -shared -fPIC -O3` → `dlopen` via koffi instead of
+ * `new Function(source)`. The dispatch, gating, and caching
+ * conventions are otherwise identical, so a sibling executor can
+ * register alongside the JS path at the same opt level without any
+ * arbitration in the dispatcher beyond cost-based selection.
+ *
+ * Declines when:
+ *   - `nativeBridge` / `koffi` are not available (browser).
+ *   - Any param or output type fails the C-FFI feasibility check
+ *     (`compilerTypeToCDecl` returns null).
+ *   - mtoc2 throws `UnsupportedConstruct` / `JitTypeError` at lowering.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitCallData {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly compilerArgTypes: readonly CompilerType[];
+    readonly args: readonly unknown[];
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitCallExecutor: Executor<CJitCallData, CompiledArtifact | null>;
+export {};

package/dist-browser/numbl-core/executors/jit/cJitLoopExecutor.d.ts

@@ -0,0 +1,31 @@
+/**
+ * cjit-loop — C-backed JIT executor for outermost For/While
+ * loops. Mirrors `loopExecutor.ts` (JS-emit sibling) but routes
+ * through `compileSpecC` → `cc -shared` → `koffi`. See
+ * `cJitCallExecutor.ts` for the marshaling protocol; this file just
+ * adapts the loop-shape `data` to the same C-side pipeline.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import type { ConstHandle } from "../classification.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitLoopData {
+    readonly loopStmt: Stmt & {
+        type: "For" | "While";
+    };
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly constHandles: readonly ConstHandle[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitLoopExecutor: Executor<CJitLoopData, CompiledArtifact | null>;
+export {};

package/dist-browser/numbl-core/executors/jit/cJitTopLevelExecutor.d.ts

@@ -0,0 +1,29 @@
+/**
+ * cjit-top-level — C-backed JIT executor for whole-script bodies.
+ *
+ * Mirrors `topLevelExecutor.ts` (JS-emit sibling) but routes through
+ * `compileSpecC` → `cc -shared` → `koffi`. See `cJitCallExecutor.ts`
+ * for the marshaling protocol. Same `isAllSuppressed` gate as the JS
+ * sibling so `displayAssign`/`displayResult` semantics stay on the
+ * interpreter path.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import { type Type as CompilerType, type SpecCSignature } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+interface CJitTopLevelData {
+    readonly stmts: readonly Stmt[];
+    readonly inputs: readonly string[];
+    readonly outputs: readonly string[];
+    readonly inputTypes: readonly JitType[];
+    readonly compilerInputTypes: readonly CompilerType[];
+    readonly currentFile: string;
+    readonly cacheKey: string;
+}
+interface CompiledArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+}
+export declare const cJitTopLevelExecutor: Executor<CJitTopLevelData, CompiledArtifact | null>;
+export {};

package/dist-browser/numbl-core/executors/jit/callExecutor.d.ts

@@ -0,0 +1,45 @@
+/**
+ * jit-call — executor that compiles user-function calls via mtoc2's
+ * `compileSpec` JIT entry point and runs the emitted JS in-process.
+ *
+ * Replaces the JS-JIT call executor at `--opt 1`. The shape of the
+ * fallback path is the same: on rejection (mtoc2's
+ * `UnsupportedConstruct` / `TypeError` during lowering, or a JitType
+ * the type adapter can't translate), `propose()` declines and the
+ * dispatcher falls through to the next executor / interpreter.
+ *
+ * Key differences from JS-JIT:
+ *
+ * - **No mid-run bailouts.** mtoc2 either lowers cleanly or rejects
+ *   statically. When `compile()` returns, the artifact will run to
+ *   completion. `bailRisk` is `false`.
+ * - **Shared `Lowerer.specializations` is the cache.** One Workspace
+ *   + Lowerer pair per LoweringContext (i.e. per execution session);
+ *   accumulating specs persist across calls so a function called
+ *   repeatedly with the same arg signature reuses the prior compile.
+ * - **Output-count support.** `nargout >= 1` (single-output and
+ *   multi-output `[a, b, ...] = f(x)`). `nargout === 0` (bare-stmt
+ *   `f();`) is declined because mtoc2's nargout=0 spec emits a no-
+ *   return body, but numbl's interpreter still uses the first
+ *   declared output for `ans` binding — let the interpreter handle.
+ * - **Loop-depth gate.** Declines when `interp.loopDepth > 0` so a
+ *   hot loop iterating function calls doesn't pay per-call JIT
+ *   propose / spec-cache overhead. Once an outer call is JIT'd, its
+ *   loops run inside mtoc2's compiled code anyway.
+ */
+import type { Executor } from "../types.js";
+import { type JitType } from "../../jitTypes.js";
+import type { FunctionDef } from "../../interpreter/types.js";
+import { type Type as CompilerType } from "../../jit/index.js";
+interface JitCallData {
+    readonly fn: FunctionDef;
+    readonly nargout: number;
+    readonly argTypes: readonly JitType[];
+    readonly compilerArgTypes: readonly CompilerType[];
+    readonly args: readonly unknown[];
+}
+interface CompiledArtifact {
+    readonly specFn: (...args: unknown[]) => unknown;
+}
+export declare const jitCallExecutor: Executor<JitCallData, CompiledArtifact | null>;
+export {};

package/dist-browser/numbl-core/executors/jit/compileC.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Browser-safe surface for the koffi C-JIT pipeline.
+ *
+ * The real implementation (`compileAndLoadCImpl`) lives in
+ * `compileC.node.ts` because it imports Node-only modules (`node:fs`,
+ * `node:child_process`, `node:os`, `node:crypto`) that vite/rollup
+ * cannot bundle for the browser. The CLI's bootstrap registers the
+ * Node implementation here at startup via `setCompileAndLoadCImpl()`;
+ * any browser bundle leaves it unregistered, so the koffi-backed
+ * executors decline (their proposals already gate on
+ * `bridge.koffi !== undefined`).
+ *
+ * Types stay in this file so the koffi executors can import them
+ * without dragging Node-only deps into the static dep graph.
+ */
+import type { NativeBridge } from "../../workspace/types.js";
+/** The koffi function reference returned by `lib.func(decl)`. The
+ *  actual call signature is controlled by the caller's declaration —
+ *  type as variadic and let the caller cast. */
+export type CFn = (...args: unknown[]) => unknown;
+export interface CompiledC {
+    readonly fn: CFn;
+    /** koffi `Lib` instance — useful for binding auxiliary symbols
+     *  (`free` from libc, allocator helpers, etc.) without re-opening
+     *  the .so. */
+    readonly lib: KoffiLib;
+    /** Path to the .so on disk — diagnostics only. */
+    readonly libPath: string;
+    /** Cache hit (true) vs. fresh cc invocation (false). */
+    readonly cacheHit: boolean;
+}
+/** koffi's runtime-shaped lib object. Loosely typed because koffi
+ *  doesn't ship TS types for its declaration-string API. */
+export interface KoffiLib {
+    func(declaration: string): CFn;
+}
+/** Signature of the real compile-and-load. The CLI registers an
+ *  implementation that shells out to `cc` and `dlopen`s the result
+ *  via koffi. */
+export type CompileAndLoadCImpl = (source: string, declaration: string, bridge: NativeBridge) => CompiledC;
+/** Install the Node-side C-JIT implementation. Called by `cli.ts`
+ *  during CLI bootstrap; browser bundles never call this, so `impl`
+ *  stays null and the koffi executors decline. */
+export declare function setCompileAndLoadCImpl(fn: CompileAndLoadCImpl): void;
+/** Compile (or look up cached) and load. Delegates to whatever was
+ *  registered via `setCompileAndLoadCImpl()`; throws if no
+ *  implementation is available (= running in a browser host that
+ *  somehow got past the koffi executor's `bridge.koffi` gate). */
+export declare function compileAndLoadC(source: string, declaration: string, bridge: NativeBridge): CompiledC;
+export declare function setReadCachedCSourceImpl(fn: (hash: string) => string | null): void;
+export declare function readCachedCSource(hash: string): string | null;

package/dist-browser/numbl-core/executors/jit/compileC.node.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Node-only implementation of the koffi C-JIT pipeline.
+ *
+ * Cache layout: `~/.cache/numbl/mtoc2-c-jit/<sha>.so` (one per unique
+ * `(declaration, source, flags)` triple). On hit, `dlopen` and reuse —
+ * no `cc` invocation. On miss, write `<sha>.c`, exec `cc`, then
+ * `dlopen`.
+ *
+ * This file is split out of `compileC.ts` so the browser bundle stays
+ * free of `node:fs` / `node:child_process` imports — vite/rollup
+ * cannot resolve them for the browser target. Browser bundles import
+ * only `compileC.ts` (types + a runtime-injected stub); the CLI
+ * imports this file at bootstrap and calls `setCompileAndLoadCImpl()`.
+ */
+import type { NativeBridge } from "../../workspace/types.js";
+import { type CompiledC } from "./compileC.js";
+/** Compile (or look up cached) and load. The cache key is the SHA of
+ *  `(flags, declaration, source)` so two different signatures or
+ *  compile-flag sets against the same source get distinct artifacts. */
+export declare function compileAndLoadC(source: string, declaration: string, bridge: NativeBridge): CompiledC;
+/** Read a previously-compiled C source from disk. Diagnostic helper. */
+export declare function readCachedCSource(hash: string): string | null;
+/** Register both implementations with the browser-safe surface. The
+ *  CLI imports this module at bootstrap to wire them in. */
+export declare function registerNodeCompileC(): void;