numbl 0.4.21 → 0.4.22

package/dist-lib/node.js

@@ -67,6 +67,24 @@ function scanMFiles(dirPath, excludeFile) {
   return files;
 }
 
+// src/numbl-core/helpers/glob.ts
+var PATH_TOKENS = {
+  "**/": "(?:.*/)?",
+  "**": ".*",
+  "*": "[^/]*",
+  "?": "[^/]"
+};
+function globToRegExp(pattern, opts = {}) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  let body;
+  if (!opts.paths) {
+    body = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
+  } else {
+    body = escaped.replace(/\*\*\/|\*\*|\*|\?/g, (m) => PATH_TOKENS[m]);
+  }
+  return new RegExp("^" + body + "$");
+}
+
 // src/cli-fileio.ts
 function expandTilde(filepath) {
   if (filepath.startsWith("~/")) {
@@ -458,9 +476,7 @@ var NodeFileIOAdapter = class {
       const lastSep = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
       const dir = lastSep >= 0 ? p.slice(0, lastSep) : ".";
       const globPat = lastSep >= 0 ? p.slice(lastSep + 1) : p;
-      const re = new RegExp(
-        "^" + globPat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
-      );
+      const re = globToRegExp(globPat);
       let entries;
       try {
         entries = readdirSync2(dir);
@@ -547,9 +563,7 @@ var NodeFileIOAdapter = class {
       const last = basename(p);
       if (last.includes("*") || last.includes("?")) {
         const dir = dirname(abs);
-        const re = new RegExp(
-          "^" + last.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
-        );
+        const re = globToRegExp(last);
         let dirEntries;
         try {
           dirEntries = readdirSync2(dir);
@@ -642,9 +656,7 @@ var NodeFileIOAdapter = class {
     );
     const dir = lastSep >= 0 ? pattern.slice(0, lastSep) : ".";
     const globPat = lastSep >= 0 ? pattern.slice(lastSep + 1) : pattern;
-    const re = new RegExp(
-      "^" + globPat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$"
-    );
+    const re = globToRegExp(globPat);
     const absDir = resolve(dir);
     const results = [];
     let entries;
@@ -685,11 +697,7 @@ var NodeFileIOAdapter = class {
       return [];
     }
     const suffix = norm.slice(idx);
-    const DIRS = "\0";
-    const ANY = "
";
-    const re = new RegExp(
-      "^" + suffix.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, DIRS).replace(/\*\*/g, ANY).replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(new RegExp(DIRS, "g"), "(?:.*/)?").replace(new RegExp(ANY, "g"), ".*") + "$"
-    );
+    const re = globToRegExp(suffix, { paths: true });
     const results = [];
     const pushIfMatch = (rel, name, folder, bytes, isdir, mtimeMs) => {
       if (re.test(rel)) results.push({ name, folder, bytes, isdir, mtimeMs });

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

@@ -0,0 +1,39 @@
+/**
+ * REPL-style session over `executeCode`. Each call builds a fresh runtime, so
+ * the state a session carries from one call to the next is threaded through
+ * here: workspace variables, plot hold state, figure handles, search paths and
+ * workspace files (as changed by addpath/rmpath), the implicit cwd, and the
+ * uihtml session left by the latest run. Used by the CLI REPL and the
+ * browser workers.
+ */
+import { type ExecOptions, type ExecResult, type FigureHandles, type UihtmlSession } from "./executeCode.js";
+import type { RuntimeValue } from "./runtime/index.js";
+import type { NativeBridge, WorkspaceFile } from "./workspace/types.js";
+export declare class ExecSession {
+    variableValues: Record<string, RuntimeValue>;
+    holdState: boolean;
+    figureHandles: FigureHandles;
+    workspaceFiles: WorkspaceFile[];
+    searchPaths: string[] | undefined;
+    implicitCwdPath: string | null | undefined;
+    /** Live uihtml callbacks from the latest run, if any (see UihtmlSession). */
+    uihtmlSession: UihtmlSession | null;
+    /** Appended to the search paths of every `execute` unless already present
+     *  (e.g. the mip core directory). */
+    extraSearchPaths: string[];
+    nativeBridge: NativeBridge | undefined;
+    constructor(init?: {
+        workspaceFiles?: WorkspaceFile[];
+        searchPaths?: string[];
+        nativeBridge?: NativeBridge;
+    });
+    /** Run `code` against the carried state and adopt the result's state. A
+     *  new run supersedes the previous uihtml session; on error the rest of
+     *  the state is left unchanged. */
+    execute(code: string, options?: ExecOptions, mainFileName?: string): ExecResult;
+    /** Carry a successful run's state forward. */
+    adopt(result: ExecResult): void;
+    /** Forget variables, hold state and figures (paths and cwd are kept). */
+    clearWorkspace(): void;
+    disposeUihtmlSession(): void;
+}

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

@@ -5,7 +5,7 @@
  * creates an Interpreter, and runs the AST.
  */
 import type { RuntimeValue } from "./runtime/index.js";
-import type { PlotInstruction } from "../graphics/types.js";
+import type { PlotInstruction } from "./plotting/types.js";
 import type { FileIOAdapter } from "./fileIOAdapter.js";
 import type { SystemAdapter } from "./systemAdapter.js";
 import type { WorkspaceFile } from "../numbl-core/workspace/index.js";
@@ -31,6 +31,9 @@ export interface ExecOptions {
     onJitBail?: (message: string) => void;
     /** Initial hold state for plotting (persisted across REPL executions). */
     initialHoldState?: boolean;
+    /** Current and largest figure handle so far (persisted across REPL
+     *  executions, so a bare `figure` keeps allocating new figures). */
+    initialFigureHandles?: FigureHandles;
     /** 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). */
@@ -92,6 +95,7 @@ export interface ExecResult {
     returnValue: RuntimeValue;
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    figureHandles: FigureHandles;
     profileData?: ProfileData;
     dispatchUnknownCounts?: Record<string, number>;
     /** Updated search paths (set when addpath/rmpath was called). */
@@ -105,4 +109,9 @@ export interface ExecResult {
      *  interpreter (see UihtmlSession). Absent for normal runs (no overhead). */
     uihtmlSession?: UihtmlSession;
 }
+/** Figure-handle state of a run (see Runtime.currentFigureHandle). */
+export interface FigureHandles {
+    current: number;
+    max: number;
+}
 export declare function executeCode(source: string, options?: ExecOptions, workspaceFiles?: WorkspaceFile[], mainFileName?: string, searchPaths?: string[], nativeBridge?: NativeBridge): ExecResult;

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

@@ -105,17 +105,9 @@ export interface CallClassification {
     readonly fn: FunctionDef;
     readonly nargout: number;
     readonly argTypes: readonly JitType[];
+    /** Compile-cache key within the FunctionDef owner: arg types + nargout
+     *  (the spec is specialized on both). */
     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;
 }

package/dist-lib/numbl-core/executors/jit/backend.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The JIT backend strategy.
+ *
+ * The three shape executors (top-level, loop, call) are written once
+ * against `JitBackend`; `jsBackend` (`compileSpec` + `new Function`) and
+ * `cBackend` (`compileSpecC` + `cc` + koffi) supply what differs: type
+ * feasibility, compile, and how a compiled spec is called.
+ */
+import type { Interpreter } from "../../interpreter/interpreter.js";
+import type { JitType } from "../../jitTypes.js";
+import type { Stmt } from "../../parser/index.js";
+import type { RuntimeValue } from "../../runtime/types.js";
+import { type Type as CompilerType } from "../../jit/index.js";
+import type { RunResult } from "../types.js";
+export type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+export interface CompileRequest {
+    /** Executor name, for diagnostics. */
+    readonly where: string;
+    readonly funcDecl: FuncStmt;
+    readonly argTypes: CompilerType[];
+    readonly nargout: number;
+    /** True when `funcDecl` wraps a script body or loop rather than a
+     *  user function (relaxes the C entry-output check). */
+    readonly synthetic: boolean;
+    /** Suffix for the `onJitCompile` label, e.g. `(number) -> nargout=1`. */
+    readonly describe: string;
+}
+export interface JitBackend<A = unknown> {
+    readonly lang: "js" | "c";
+    /** Executor-name prefix: `jit` or `cjit`. */
+    readonly prefix: string;
+    /** Whether the backend can run in this interpreter at all. */
+    available(interp: Interpreter): boolean;
+    /** Translate a numbl input type to a compiler type; null declines. */
+    mapType(jt: JitType): CompilerType | null;
+    /** Compile a spec. May throw `UnsupportedConstruct` / `JitTypeError`
+     *  (see `compileUnit`); returns null for any other decline. */
+    compile(req: CompileRequest, interp: Interpreter): A | null;
+    /** Call a compiled spec. Returns its outputs (`undefined` for one the
+     *  spec left unassigned), or null to bail to the interpreter. */
+    invoke(art: A, args: readonly (RuntimeValue | undefined)[], interp: Interpreter, where: string): (RuntimeValue | undefined)[] | null;
+}
+/** `backend.compile`, turning a compiler rejection into a recorded
+ *  decline (null). Only the compiler's own decline errors are caught. */
+export declare function compileUnit<A>(backend: JitBackend<A>, req: CompileRequest, interp: Interpreter): A | null;
+/** Map every input type through the backend; null if any declines. */
+export declare function mapTypes(backend: JitBackend, types: readonly JitType[]): CompilerType[] | null;
+/** `%!numbl:assert_jit c` requires C-JIT at --opt 2, so the JS backend
+ *  declines such units there: they either C-JIT or fall through to the
+ *  interpreter, which raises on the directive. Plain `assert_jit` only
+ *  requires JS-JIT at --opt 1 and does not gate here. */
+export declare function declinedByAssertC(backend: JitBackend, interp: Interpreter, assertsCJit: boolean): boolean;
+/** The loop-depth gate shared by the loop and call shapes: decline while
+ *  an enclosing loop is running, since compiling that loop captures this
+ *  unit. Lifts when every enclosing loop was itself declined
+ *  (`Interpreter.jitDeclinedLoopDepth`). */
+export declare function insideCompiledLoop(interp: Interpreter): boolean;
+/** A synthetic `FuncStmt` wrapping a script body or loop: params are the
+ *  env inputs, outputs the env outputs. */
+export declare function synthesizeFuncStmt(name: string, inputs: readonly string[], outputs: readonly string[], body: Stmt[], fileName: string): FuncStmt;
+/** Run a compiled script-body or loop spec against the interpreter env:
+ *  read `inputs` from it, write back the `outputs` the spec assigned. */
+export declare function runInEnv<A>(backend: JitBackend<A>, art: A, inputs: readonly string[], outputs: readonly string[], interp: Interpreter, where: string): RunResult;

package/dist-lib/numbl-core/executors/jit/cBackend.d.ts

@@ -0,0 +1,22 @@
+/**
+ * C backend: `compileSpecC` → `cc -shared` → koffi `dlopen`.
+ *
+ * Node only. Imported solely by `compileC.node.ts`, which registers it at
+ * bootstrap, so the browser bundle never pulls in the C compile graph.
+ * See `valueAdapterC.ts` for the marshaling protocol.
+ */
+import { type CompileSpecCResult, type SpecCSignature, type Type } from "../../jit/index.js";
+import { type CompiledC } from "./compileC.js";
+import { bindGrowBail, makeCMarshalCtx, type HostWriteBinding } from "./valueAdapterC.js";
+import type { JitBackend } from "./backend.js";
+interface CArtifact {
+    readonly compiled: CompiledC;
+    readonly signature: SpecCSignature;
+    readonly assignedFlags: CompileSpecCResult["assignedFlags"];
+    readonly paramTypes: Type[];
+    readonly ctx: ReturnType<typeof makeCMarshalCtx>;
+    readonly hostWrite: HostWriteBinding;
+    readonly growBail: ReturnType<typeof bindGrowBail>;
+}
+export declare const cBackend: JitBackend<CArtifact>;
+export {};

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

@@ -1,51 +1,20 @@
 /**
- * jit-call — executor that compiles user-function calls via mtoc2's
- * `compileSpec` JIT entry point and runs the emitted JS in-process.
+ * `<prefix>-call` — compiles a user-function call specialized on its
+ * argument types and nargout.
  *
- * 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. The gate lifts when
- *   every enclosing loop was itself declined: nothing above will be
- *   compiled then, and an expensive callee would otherwise run
- *   interpreted all the way down (`Interpreter.jitDeclinedLoopDepth`).
+ * Declines `nargout === 0` (bare `f();`): the interpreter still binds the
+ * first declared output to `ans`, but a nargout=0 spec returns nothing.
+ * Declines inside a loop that is itself being compiled (see
+ * `insideCompiledLoop`): the call then runs inside that compiled loop.
  */
 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[];
+import type { CallClassification } from "../classification.js";
+import type { Type as CompilerType } from "../../jit/index.js";
+import { type JitBackend } from "./backend.js";
+interface CallData {
+    readonly c: CallClassification;
+    readonly argTypes: CompilerType[];
     readonly args: readonly unknown[];
 }
-interface CompiledArtifact {
-    readonly specFn: (...args: unknown[]) => unknown;
-    /** The spec's declared output types — needed to convert a returned
-     *  struct back (an untagged JS object otherwise). */
-    readonly outputTypes: ReadonlyArray<CompilerType>;
-}
-export declare const jitCallExecutor: Executor<JitCallData, CompiledArtifact | null>;
+export declare function makeCallExecutor<A>(backend: JitBackend<A>): Executor<"call", CallData, A | null>;
 export {};

package/dist-lib/numbl-core/executors/jit/hostHelpers.d.ts

@@ -13,6 +13,11 @@
  *    so `colorbar('off')` / `pcolor(...)` / etc. produce the same
  *    plot-instruction stream as the interpreter would.
  *
+ *  - `elemwise` — the interpreter's element-wise tensor kernels (native
+ *    addon when loaded). The JS runtime snippets use them for large
+ *    tensors, so --opt 0 and --opt 1 compute the same bits and large
+ *    element-wise work runs as SIMD C rather than a scalar JS loop.
+ *
  * The unknown-name fallthrough (when `dispatchPlotBuiltin` returns
  * false) is a programmer error: every name mtoc2's plot builtin
  * registration covers is in `PLOT_ALL_NAMES`, which is sourced from
@@ -20,6 +25,16 @@
  * mismatch is loud rather than silently dropping a side effect.
  */
 import type { Runtime } from "../../runtime/runtime.js";
+/** Element-wise kernels exposed to the JS runtime snippets as
+ *  `$elemwise` (see `runtime-globals.d.ts`). `out` has `a`'s length. */
+export interface JitElemwiseHost {
+    binary(op: string, a: Float64Array, b: Float64Array, out: Float64Array): void;
+    scalarBinary(op: string, s: number, a: Float64Array, scalarOnLeft: boolean, out: Float64Array): void;
+    /** False when `op` has no host kernel (the caller runs its own loop). */
+    unary(op: string, a: Float64Array, out: Float64Array): boolean;
+    /** NaN-skipping `min` / `max` over all of `a` (non-empty). */
+    minmax(op: "min" | "max", a: Float64Array): number;
+}
 export interface JitHostHelpers {
     write: (s: string) => void;
     plotDispatch: (name: string, args: unknown[]) => void;
@@ -27,5 +42,14 @@ export interface JitHostHelpers {
      *  (the same `rngRandom` the interpreter uses), so JIT'd and interpreted
      *  `rand` draw from one shared, `rng(seed)`-controllable stream. */
     rand: () => number;
+    elemwise: JitElemwiseHost;
 }
 export declare function buildHostHelpers(rt: Runtime): JitHostHelpers;
+/** The output sink for a compiled C call: passes program output to
+ *  `rt.output` and turns plot records into plot instructions. A record may
+ *  arrive in several chunks; it ends at a newline. Call `flush` after the C
+ *  call returns. */
+export declare function cOutputSink(rt: Runtime): {
+    write: (s: string) => void;
+    flush: () => void;
+};

package/dist-lib/numbl-core/executors/jit/jsBackend.d.ts

@@ -0,0 +1,15 @@
+/**
+ * JS backend: `compileSpec` emits a JS factory, materialized with
+ * `new Function` and run in-process.
+ */
+import { type Type as CompilerType } from "../../jit/index.js";
+import type { JitBackend } from "./backend.js";
+interface JsArtifact {
+    readonly specFn: (...args: unknown[]) => unknown;
+    readonly argTypes: readonly CompilerType[];
+    /** Needed to rebuild a returned struct (an untagged JS object). */
+    readonly outputTypes: readonly CompilerType[];
+    readonly nargout: number;
+}
+export declare const jsBackend: JitBackend<JsArtifact>;
+export {};

package/dist-lib/numbl-core/executors/jit/loopExecutor.d.ts

@@ -1,46 +1,19 @@
 /**
- * jit-loop — compiles a single For/While stmt via mtoc2's
- * `compileSpec` with the loop wrapped as a synthetic user function
- * whose params are the variables the loop reads (env inputs) and
- * whose outputs are the variables it assigns that are live after the
- * loop (filtered in classification).
+ * `<prefix>-loop` — compiles a single For/While stmt, wrapped as a
+ * synthetic function whose params are the variables the loop reads from
+ * the env and whose outputs are the variables it assigns that are live
+ * after the loop (filtered in classification).
  *
- * Mirrors `topLevelExecutor.ts` — the only structural difference is
- * that the synthetic body is a single-element `[loopStmt]` instead of
- * a whole script body.
- *
- * Loop-depth gate: fires when `interp.loopDepth === 0`, or when every
- * enclosing loop has been declined by the JIT. A loop dispatched while the
- * interpreter iterates an enclosing loop-body would pay per-iter
- * propose/cache overhead with no speedup, because the *outer* loop is the
- * natural JIT entry point (it captures the inner loop's body and runs it
- * natively in mtoc2-emitted code) — but that only holds when the outer loop
- * actually compiles. If it declined, the interpreter is walking its body and
- * this loop is the outermost thing still compilable, so the gate lifts
- * (`Interpreter.jitDeclinedLoopDepth`).
+ * Fires for outermost loops only, unless every enclosing loop was itself
+ * declined (see `insideCompiledLoop`).
  */
 import type { Executor } from "../types.js";
-import { type JitType } from "../../jitTypes.js";
-import type { Stmt } from "../../parser/index.js";
-import { type Type as CompilerType } from "../../jit/index.js";
-import type { ConstHandle } from "../classification.js";
-interface JitLoopData {
-    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 specFn: (...args: unknown[]) => unknown;
-    /** The synthetic spec's output types, so a struct written back into the
-     *  env is rebuilt as a struct (the emitted value is an untagged object). */
-    readonly outputTypes: ReadonlyArray<CompilerType>;
+import type { LoopClassification } from "../classification.js";
+import type { Type as CompilerType } from "../../jit/index.js";
+import { type JitBackend } from "./backend.js";
+interface LoopData {
+    readonly c: LoopClassification;
+    readonly argTypes: CompilerType[];
 }
-export declare const jitLoopExecutor: Executor<JitLoopData, CompiledArtifact | null>;
+export declare function makeLoopExecutor<A>(backend: JitBackend<A>): Executor<"loop", LoopData, A | null>;
 export {};

package/dist-lib/numbl-core/executors/jit/session.d.ts

@@ -1,6 +1,6 @@
 /**
  * Per-LoweringContext mtoc2 session state shared between
- * `jitCallExecutor` and `jitTopLevelExecutor`. One `Workspace`
+ * the JIT executors (both backends). One `Workspace`
  * (built from numbl's existing `LoweringContext`) and one `Lowerer`
  * per execution session, so the `Lowerer.specializations` cache
  * persists across whole-scope + per-call dispatches.

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

@@ -1,39 +1,19 @@
 /**
- * jit-top-level — compiles a script body via mtoc2's `compileSpec`
- * with the body wrapped as a synthetic user function whose params are
- * the variables the body reads (env inputs) and whose outputs are the
- * variables it assigns (env outputs).
+ * `<prefix>-top-level` — compiles a whole script body, wrapped as a
+ * synthetic function whose params are the variables the body reads from
+ * the env and whose outputs are the variables it assigns.
  *
- * The interpreter calls `Registry.tryRunWholeScope` once at script
- * start; we register this via `registerWholeScope`. On compile
- * success the entire script runs in mtoc2-emitted JS; on
- * `UnsupportedConstruct` / `TypeError` we decline and the dispatcher
- * falls through to per-stmt dispatch (where jit-call still handles
- * individual user-function calls).
- *
- * Top-level loops *inside* the script execute as part of the
- * compiled artifact, so `loopDepth` only gates dispatch-level calls,
- * not this whole-scope attempt.
+ * The interpreter calls `Registry.tryRunWholeScope` once at script start.
+ * On a decline the per-stmt loop runs instead, where the loop and call
+ * executors still get their chance.
  */
 import type { Executor } from "../types.js";
-import { type JitType } from "../../jitTypes.js";
-import type { Stmt } from "../../parser/index.js";
-import { type Type as CompilerType } from "../../jit/index.js";
-interface JitTopLevelData {
-    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 specFn: (...args: unknown[]) => unknown;
-    readonly nargout: number;
-    /** The synthetic spec's output types, so a struct written back into the
-     *  env is rebuilt as a struct (the emitted value is an untagged object). */
-    readonly outputTypes: ReadonlyArray<CompilerType>;
+import type { TopLevelClassification } from "../classification.js";
+import type { Type as CompilerType } from "../../jit/index.js";
+import { type JitBackend } from "./backend.js";
+interface TopLevelData {
+    readonly c: TopLevelClassification;
+    readonly argTypes: CompilerType[];
 }
-export declare const jitTopLevelExecutor: Executor<JitTopLevelData, CompiledArtifact | null>;
+export declare function makeTopLevelExecutor<A>(backend: JitBackend<A>): Executor<"top-level", TopLevelData, A | null>;
 export {};

package/dist-lib/numbl-core/executors/jit/valueAdapterC.d.ts

@@ -5,22 +5,14 @@
  * `RuntimeValue` to / from the C ABI mtoc2 expects across the koffi
  * FFI boundary.
  *
- * **Copy budget** (see CLAUDE memo `feedback-no-silent-bails.md`
- * and the user's "no extra copies" guideline):
+ * **Copy budget**:
  *   - Scalars: zero copies; passed by value in koffi's args array.
- *   - Tensors: one copy in, one copy out. mtoc2's call convention
- *     requires the callee own its tensor params (it frees them at
- *     scope exit), so the input data must be copied into a
- *     `koffi.alloc`'d malloc-backed buffer that mtoc2 can free.
- *     Reused / shared buffer would either (a) get freed under
- *     numbl's still-live Float64Array, or (b) require extending
- *     mtoc2 with borrowed-param semantics — deferred.
- *
- *   - Output tensors arrive as `mtoc2_tensor_t` with mtoc2_alloc'd
- *     `real`/`imag` pointers. Caller (this adapter) copies the data
- *     into a fresh `Float64Array`, then calls `free()` on the
- *     pointers (`koffi`-bound `free` from libc) to release mtoc2's
- *     buffers.
+ *   - Tensors: one copy in, one copy out. The callee owns (and frees at
+ *     scope exit) its tensor params, so input data is copied into
+ *     buffers from the `.so`'s own `mtoc2_jit_malloc`. Output tensors
+ *     arrive with callee-allocated `real`/`imag`; they are copied into
+ *     fresh `Float64Array`s and released with `mtoc2_jit_free`. Both
+ *     copies are bulk `koffi.encode` / `koffi.decode` calls.
  */
 import { RuntimeTensor, type RuntimeValue } from "../../runtime/types.js";
 import type { Type, NumericType } from "../../jit/index.js";
@@ -28,31 +20,31 @@ import type { KoffiLib } from "./compileC.js";
 /** Loose koffi typing — same shape as in typeAdapterC.ts. */
 type KoffiAny = any;
 interface Koffi {
-    alloc(type: string, count: number): any;
-    decode(ptr: unknown, type: string, count: number): any;
-    encode(buf: any, type: string, value: any): void;
-    address(buf: any): any;
+    encode(ptr: unknown, type: string, value: Float64Array, len: number): void;
+    decode(ptr: unknown, type: string, len: number): Float64Array;
 }
 /** A function that frees the `mtoc2_alloc`'d buffer at the given
  *  pointer. Resolved via koffi against libc's `free`. The .so we
  *  dlopen pulls in libc anyway, so binding through the same lib is
  *  zero-cost. */
 type FreeFn = (ptr: unknown) => void;
+type MallocFn = (bytes: number) => unknown;
 interface MarshalCtx {
     readonly koffi: Koffi;
+    readonly malloc: MallocFn;
     readonly free: FreeFn;
 }
+export interface HostWriteBinding {
+    /** Run `fn` (the C call) with the `.so`'s output routed to `write`. */
+    run<T>(write: (s: string) => void, fn: () => T): T;
+}
 /** Bind numbl's output sink into an emitted C `.so` so program output
- *  (disp / fprintf / …) routes through `write` instead of libc stdout
- *  — see `runtime/io/host_output.h`. Returns a `dispose()` the caller
- *  MUST invoke after the C call returns (success or throw) to unbind
- *  and free the koffi callback.
+ *  (disp / fprintf / …) routes through the host instead of libc stdout
+ *  (see `runtime/io/host_output.h`). Done once per loaded `.so`.
  *
  *  When the spec emitted no output, `mtoc2_set_host_write` is absent
  *  from the `.so`; binding then no-ops (the C code never writes). */
-export declare function bindHostWrite(koffi: KoffiAny, lib: KoffiLib, write: (s: string) => void): {
-    dispose(): void;
-};
+export declare function bindHostWrite(koffi: KoffiAny, lib: KoffiLib): HostWriteBinding;
 /** Bind the emitted `.so`'s grow-bail flag accessors. A runtime
  *  indexed-store grow (`v(k) = x`, k past the runtime extent) sets a
  *  flag in the `.so` and `longjmp`s back to the host-entry function's
@@ -68,35 +60,27 @@ export declare function bindGrowBail(lib: KoffiLib): {
     reset(): void;
     bailed(): boolean;
 };
-/** Build a marshaling context from a koffi lib handle. The host
- *  passes the lib it got from `compileAndLoadC`; we resolve `free`
- *  against that same lib (libc symbols are reachable through any
- *  dlopen'd .so). */
+/** Build a marshaling context from a koffi lib handle. `mtoc2_jit_malloc`
+ *  / `mtoc2_jit_free` are exported by every JIT `.so` (see
+ *  `jit/codegen/emit.ts`), so host-side buffers use the same allocator
+ *  the emitted code frees with. */
 export declare function makeCMarshalCtx(koffi: Koffi, lib: KoffiLib): MarshalCtx;
-/** Marshaled-input bookkeeping returned by `marshalInputs`. The
- *  caller is responsible for invoking `release()` once the C call
- *  has returned (success or throw). `release` does nothing for
- *  scalar inputs (no allocation); for tensor inputs it's also a
- *  no-op: mtoc2's spec body frees the buffers at its scope exit.
- *  Kept as an explicit handle so a future change to lifetime
- *  semantics has a single place to update. */
+/** Marshaled-input bookkeeping returned by `marshalInputs`. The callee
+ *  takes ownership of tensor buffers once it is called; `release()`
+ *  frees them for a call that never happened (marshaling or koffi
+ *  argument-conversion failure). */
 export interface MarshaledInputs {
     /** The values to splat into the koffi call, in order. */
     readonly args: unknown[];
     release(): void;
 }
-/** Convert a numbl `RuntimeValue` to the matching koffi-callable
- *  arg for a parameter of mtoc2 `Type`. */
+/** Convert numbl `RuntimeValue`s to koffi-callable args for parameters of
+ *  the given compiler `Type`s, or null if a value doesn't fit its type. */
 export declare function marshalInputs(ctx: MarshalCtx, paramTypes: ReadonlyArray<Type>, values: ReadonlyArray<RuntimeValue | undefined>): MarshaledInputs | null;
-/** Convert a returned C tensor struct (decoded by koffi into a JS
- *  object with `{real, imag, ndim, dims}`) to a numbl RuntimeTensor.
- *  Reads `n = product(dims[0..ndim])` doubles from each lane, then
- *  frees mtoc2's buffers.
- *
- *  For `Numeric` outputs that aren't multi-element (scalars), the
- *  caller passes the bare value through `unmarshalScalarOutput`
- *  instead — koffi unboxes them automatically.
- */
+/** Convert a returned C tensor struct (decoded by koffi into a JS object
+ *  with `{real, imag, ndim, dims}`) to a numbl RuntimeTensor, then free
+ *  the callee's buffers. Scalar outputs go through
+ *  `unmarshalScalarOutput` instead. */
 export declare function unmarshalTensorOutput(ctx: MarshalCtx, ret: KoffiAny, ty: NumericType): RuntimeTensor;
 /** Convert a bare scalar return value to a numbl RuntimeValue.
  *