numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/jit/codegen/emitStmt.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Function-shape + statement-level codegen — `emitFunction`,
+ * `emitBody`, `emitStmt`, and the locals-collection / param-list
+ * helpers they share. Statement emit is mutually recursive with body
+ * emit (If/While/For wrap nested bodies), so they live together.
+ *
+ * Expression-side emit lives in `emitExpr.ts`; index slice store /
+ * scalar offset and named-typedef helpers are in their own modules.
+ */
+import type { IRExpr, IRFunc, IRStmt } from "../lowering/ir.js";
+import { type Type } from "../lowering/types.js";
+import { type RuntimeState } from "./runtime.js";
+import { type FutureTouchMap } from "./liveness.js";
+/** Default initializer for a freshly-declared non-owned local. Owned
+ *  types (tensors, structs, classes, handles) route through their
+ *  `_empty()` helper instead and never hit this path; everything
+ *  reaching here is scalar real numeric, so `0.0` always fits. */
+export declare function defaultInitFor(): string;
+export declare function fnRetType(fn: IRFunc): string;
+export declare function fnParamList(fn: IRFunc): string;
+/** Walk `stmts` once and split the result into owned vs non-owned
+ *  locals. Every local is pre-declared at function top — owned with
+ *  the per-type `_empty()` helper, scalars with the default init
+ *  (`0.0` / `0`). The non-owned half also picks up For loop vars and
+ *  multi-assign slot bindings so that a later read of a variable
+ *  first written inside an If / While / For body (reachable via
+ *  `mergeBranchEnvs` keeping partial-branch keys) doesn't reference
+ *  an out-of-scope C local. */
+export declare function collectLocals(stmts: IRStmt[]): {
+    owned: {
+        cName: string;
+        ty: Type;
+    }[];
+    scalars: {
+        cName: string;
+        ty: Type;
+    }[];
+};
+/** Emits the function/scope's exit cleanup + return statements at a
+ *  given indent. Called from two places: at every `ReturnFromFunction`
+ *  site (inline cleanup — no goto), and at the fall-through bottom of
+ *  the function. Single source of truth so the two callers can't
+ *  drift on which locals get freed in what order.
+ *
+ *  Why inline rather than goto-to-a-shared-tail: c2js can't translate
+ *  C `goto`, and we want a single C emit that works for both targets.
+ *  Inlining produces some duplication when a function has many early
+ *  returns and many owned locals, but typical mtoc2 functions are
+ *  small and the C compiler dedupes-by-tail-merge anyway. */
+export type EmitReturnTail = (indent: string) => string;
+export declare function emitFunction(fn: IRFunc, state: RuntimeState, 
+/** Storage-class qualifier on the function definition. Default is
+ *  `static` (file-scope, the C-AOT whole-program convention). Pass
+ *  `""` to omit the qualifier — the function then gets external
+ *  linkage so a JIT host can resolve it via `dlsym` / koffi after
+ *  `dlopen`'ing the compiled `.so`. */
+storageClass?: "static" | ""): string;
+/** Emit a sequence of statements with their per-stmt early-frees.
+ *  After each stmt, owned C-names that aren't in the stmt's
+ *  futureTouchOut (i.e. their last use was at this stmt) get a
+ *  `<owned-kind>_free(&v);` call dispatched on the variable's
+ *  recorded owned type. Scope-exit frees still emit unconditionally
+ *  — they're no-ops for buffers already nulled by the early-free. */
+export declare function emitBody(stmts: IRStmt[], indent: string, state: RuntimeState, futureTouches: FutureTouchMap, ownedTypes: ReadonlyMap<string, Type>, emitReturnTail: EmitReturnTail): string;
+/** Compute a column-major linear offset expression from cell-brace
+ *  indices. The base's shape supplies the row count for the 2-D
+ *  formula. Indices are 1-based in source; we subtract 1 to land
+ *  in C's 0-based slot/buffer array. */
+export declare function cellLinearOffsetExpr(indices: ReadonlyArray<IRExpr>, baseTy: Extract<Type, {
+    kind: "Cell";
+}>, baseCName: string, state: RuntimeState): string;
+/** Try to compute a static slot offset from a tuple cell's indices.
+ *  Returns `null` if any index isn't a NumLit. */
+export declare function tryStaticCellOffset(indices: ReadonlyArray<IRExpr>, baseTy: Extract<Type, {
+    kind: "Cell";
+}>): number | null;

package/dist-lib/numbl-core/jit/codegen/emitTensorConcat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `TensorConcat` codegen — the bracket-concatenation IR node produced
+ * by `lowerTensorLit`'s mixed-cell path (`[a, b; c, d]` where at least
+ * one cell is a tensor). Two paths: a fully-static one that bakes per-
+ * cell row/col offsets into literals, and a dynamic one that walks
+ * runtime `.dims[k]` reads.
+ *
+ * Both emit a GCC statement-expression that allocs a destination
+ * tensor, writes every cell's rectangle, and evaluates to the
+ * destination. ANF guarantees every tensor cell is already a Var, so
+ * cell reads carry no allocation cost.
+ *
+ * Mirrors numbl's `catAlongDim` (runtime/tensor-construction.ts) for
+ * the output layout — column-major destination, per-cell rectangle.
+ */
+import type { IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+/** Top-level entry: dispatch to the static or dynamic codegen path
+ *  based on whether every per-cell dim and the output shape are
+ *  compile-time known. */
+export declare function emitTensorConcat(e: Extract<IRExpr, {
+    kind: "TensorConcat";
+}>, state: RuntimeState): string;

package/dist-lib/numbl-core/jit/codegen/emitTensorConcatJs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JS sibling of `emitTensorConcat.ts`. Same two-path structure
+ * (fully-static vs. runtime-dim), same per-cell rectangle-copy
+ * shape — only the language and field names differ:
+ *   `.real` (C)  → `.data` (JS)
+ *   `.dims[k]` (C) → `.shape[k]` (JS)
+ *
+ * GCC statement-expressions don't exist in JS; the destination
+ * tensor and per-cell writes are wrapped in an IIFE that returns
+ * the result.
+ */
+import type { IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+export declare function emitTensorConcatJs(e: Extract<IRExpr, {
+    kind: "TensorConcat";
+}>, state: RuntimeState, emit: (e: IRExpr, state: RuntimeState) => string): string;

package/dist-lib/numbl-core/jit/codegen/emitTensorFused.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Elementwise-fused tensor Assign emission.
+ *
+ * For an Assign whose RHS is a pure elementwise expression and whose
+ * multi-element operands all share the target's static shape, emit a
+ * single inline iter loop instead of nested runtime-helper calls:
+ *
+ *     // c = a + b;     emits:
+ *     {
+ *       mtoc2_tensor_t _r = mtoc2_tensor_alloc_nd(a.ndim, a.dims);
+ *       long _mtoc2_n = 1; for (int _mtoc2_i = 0; _mtoc2_i < _r.ndim; _mtoc2_i++) _mtoc2_n *= _r.dims[_mtoc2_i];
+ *       MTOC2_OMP_PARFOR_N
+ *       for (long _mtoc2_i = 0; _mtoc2_i < _mtoc2_n; _mtoc2_i++) _r.real[_mtoc2_i] = (a.real[_mtoc2_i] + b.real[_mtoc2_i]);
+ *       mtoc2_tensor_assign(&c, _r);
+ *     }
+ *
+ * The local element-count + iter variables use the `_mtoc2_` reserved
+ * prefix so they can't collide with user-scope identifiers (`n`, `i`
+ * are common single-letter names in MATLAB and would shadow the
+ * function param / local on the enclosing block if we declared them
+ * with their natural names).
+ *
+ * For a single-Binary RHS this is equivalent (post-`-O3`) to the
+ * existing `mtoc2_tensor_assign(&c, mtoc2_tensor_plus_tt(a, b))`
+ * path — the helper's body is literally the same loop. The point of
+ * doing the inlining at the IR level is that the `--inline-temps`
+ * pass (phase 2) can fold a chain like `_t1 = a * b; c = _t1 + d`
+ * into `c = (a * b) + d`, which the fused emitter then renders as
+ * one loop with no intermediate tensor allocation.
+ *
+ * Phase 1 (this file) only handles the *same-static-shape* case. If
+ * any multi-element operand has a statically-different shape from
+ * the target, the Assign falls back to the runtime-helper path
+ * (`mtoc2_tensor_<op>_bcast_tt(...)`). Broadcast fusion is phase 3.
+ */
+import type { Assign, IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+/** True iff `e` is a pure-elementwise expression — only NumLit / Var /
+ *  Binary / Unary / Call to a builtin that has a `perSlotC` hook. No
+ *  owned producers (TensorBuild, TensorConcat, IndexSlice), no
+ *  non-elementwise calls (mtimes, reshape, sum, …), no user-fn calls,
+ *  no HandleLit, no IndexLoad/HandleCaptureLoad/MemberLoad, etc.
+ *
+ *  These are exactly the node kinds the per-slot renderer below
+ *  knows how to walk. */
+export declare function isPureElementwiseExpr(e: IRExpr): boolean;
+/** True iff the fused emitter can handle this Assign. Requires:
+ *    - target is a real-double multi-element tensor
+ *    - RHS is pure elementwise (see `isPureElementwiseExpr`)
+ *    - every multi-element Var in the RHS shares the target's static
+ *      shape (no broadcasting in this phase)
+ *    - no complex tensor anywhere in the RHS — the per-slot renderer
+ *      addresses tensors as `<cName>.real[i]` and drops the imag lane.
+ *      Complex sites take the runtime-helper path. */
+export declare function isFusableAssign(s: Assign): boolean;
+/** A fusable Assign needs a runtime shape guard iff it reads two or more
+ *  DISTINCT multi-element operands AND at least one carries a dynamic
+ *  (non-exact) dim. In that case `isFusableAssign` matched the operands
+ *  on a shared static dim PATTERN, but their runtime extents aren't
+ *  proven equal (`ones(1,n) + ones(1,m)`), so the fused loop — which
+ *  reads every operand over the shape source's linear extent — could
+ *  read out of bounds. With all-exact dims the pattern match already
+ *  proves equality, and a single distinct operand is its own shape
+ *  source; neither needs the guard. */
+export declare function fusedAssignNeedsShapeGuard(s: Assign): boolean;
+/** Emit the fused inline iter loop. Pre-condition:
+ *  `isFusableAssign(s)` returned true.
+ *
+ *  When `fallbackStmt` is supplied (the caller passes it iff
+ *  `fusedAssignNeedsShapeGuard(s)` is true), the fast loop is wrapped in
+ *  a runtime shape-equality guard: every other distinct multi-element
+ *  operand must match the shape source's runtime shape, else the assign
+ *  defers to `fallbackStmt` — the bcast-aware helper path, which
+ *  broadcasts compatible shapes and raises "Matrix dimensions must
+ *  agree" on incompatible ones. Mirrors the JS `tt_kernel` deferring to
+ *  `bcast_kernel`. */
+export declare function emitTensorAssignFused(s: Assign, indent: string, state: RuntimeState, fallbackStmt?: string): string;

package/dist-lib/numbl-core/jit/codegen/inlinePass.d.ts

@@ -0,0 +1,66 @@
+/**
+ * `--inline-temps` IR-to-IR rewrite: substitutes a single-use
+ * producer Assign's RHS into its consumer's RHS and removes the
+ * producer.
+ *
+ * After ANF normalization every owned-producing tensor expression
+ * lives in its own `_mtoc2_t<N>` temp. Without inlining, a chain
+ * like
+ *
+ *     _t8  = rx .^ 2
+ *     _t9  = ry .^ 2
+ *     _t10 = _t8 + _t9
+ *     r2   = _t10 + 0.01
+ *
+ * emits four separate fused loops with three intermediate allocs.
+ * After inlining (this pass), the chain collapses to
+ *
+ *     r2 = (rx .^ 2 + ry .^ 2 + 0.01)
+ *
+ * which the elementwise-fused emitter (`emitTensorFused.ts`) renders
+ * as a single iter loop. No intermediate tensors, no extra passes
+ * through memory.
+ *
+ * Gates (must all hold to inline producer P into consumer C):
+ *
+ *   1. P is an Assign producing a real-double multi-element tensor.
+ *   2. P's RHS is pure elementwise — only NumLit / Var / Binary /
+ *      Unary / Call to a builtin that has `perSlotC`. No
+ *      TensorBuild / TensorConcat / IndexLoad / IndexSlice /
+ *      MemberLoad / HandleLit / etc.
+ *   3. P's LHS cName is used exactly once in the body. Function
+ *      output cNames get a `+1` protective bump so the returned
+ *      value is never elided.
+ *   4. The single use is in another Assign's RHS, in a slot
+ *      position (subexpression of Binary / Unary / Call args). NOT
+ *      as the base of an IndexLoad / IndexSlice / MemberLoad, NOT
+ *      inside a TensorBuild / TensorConcat / StructLit / HandleLit.
+ *   5. C is also fusable (same predicate as `isFusableAssign`).
+ *   6. P and C are at the same body level (no inlining across
+ *      If / While / For — nested bodies are inlined separately).
+ *   7. No statement between P and C writes to P's LHS or to any
+ *      free Var in P's RHS, and no statement reads P's LHS except
+ *      C. Control flow (If / While / For / Break / Continue /
+ *      ReturnFromFunction) ends the safe window.
+ *
+ * Algorithm: per body, iterate `inlineOnePass` to fixed point.
+ * Each pass scans producers in source order, finds the first
+ * inlinable pair, substitutes, and returns the new body. Chained
+ * inlining (`a → b → c`) needs multiple iterations because each
+ * substitution can flip a previously-multi-use cName to single-use;
+ * we cap at 32 iterations defensively.
+ *
+ * Preserves: post-inlining the IR is still well-typed (each node's
+ * `.ty` is unchanged — the substitution copies the producer's RHS
+ * subtree verbatim); the ANF invariant for owned producers still
+ * holds because we only inline producers whose RHS is NOT itself
+ * an owned producer (no TensorBuild / Call-to-direct-owned-builtin
+ * / etc.); and the `isFusableAssign` predicate that gates the
+ * emit-path routing still accepts the consumer after substitution
+ * (shape checks compose under inlining — see the design notes in
+ * `emitTensorFused.ts`).
+ */
+import type { IRProgram } from "../lowering/ir.js";
+/** Top-level entry. Mutates `prog.topLevelStmts` and each function's
+ *  `body` in place when inlining fires. */
+export declare function inlinePass(prog: IRProgram): void;

package/dist-lib/numbl-core/jit/codegen/liveness.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Backward dataflow over the lowered IR computing per-statement
+ * "future-touch" sets for owned-heap-value variables — currently
+ * just multi-element tensors (`isOwned` in types.ts). An owned `v`'s
+ * future-touch set at statement `s` is the union of vars touched
+ * (read OR written) by any successor of `s` in the structured CFG.
+ *
+ * Drives the "early free" emission in emit.ts: an owned `v` whose
+ * last touch is statement `s` (i.e. `v` is in
+ * `(uses ∪ defs)(s)` but NOT in `futureTouchOut(s)`) gets a
+ * `mtoc2_tensor_free(&v)` immediately after `s`'s C output, rather
+ * than waiting for scope exit.
+ *
+ * Why "touch" (uses ∪ defs) rather than standard liveness (uses with
+ * kill on def)? Reassignment goes through `mtoc2_tensor_assign(&v,
+ * ...)`, which already releases the prior buffer. If `v`'s next
+ * interaction is a reassignment, an early-free at the previous use
+ * would be redundant — better to let the assign helper handle it.
+ * The future-touch set captures exactly that: a redef counts as a
+ * future touch and suppresses the early-free emission.
+ *
+ * Only owned variables are tracked; scalar `double` locals live in
+ * C automatic storage and have no heap to release.
+ *
+ * Loops resolve by fixpoint over the body's "after-body-last" set.
+ * Break / Continue / ReturnFromFunction consult the enclosing
+ * context for their target's future touches.
+ *
+ * Direct port of mtoc's `src/codegen/liveness.ts`, adapted for
+ * mtoc2's simpler IR (no Disp/Error/Assert/Fprintf/MultiAssignCall/
+ * IndexStore/etc. yet).
+ */
+import type { IRStmt } from "../lowering/ir.js";
+import { type Type } from "../lowering/types.js";
+/** Per-statement future-touch sets, keyed by the IRStmt object
+ *  reference. Each entry holds the set of owned C-names that may be
+ *  touched (read or written) at any successor of the statement. */
+export type FutureTouchMap = ReadonlyMap<IRStmt, ReadonlySet<string>>;
+/** Compute per-statement future-touch sets for a body of statements.
+ *  For function bodies whose output slots include owned values, pass
+ *  one `{ cName, ty }` per owned output. The analyzer seeds the body-
+ *  end future-touch with each owned-output C-name — otherwise the
+ *  implicit return / sret writes would see the final defs as "last
+ *  touches" and emit stray early-frees of the values we're about to
+ *  transfer to the caller. Pass an empty array for main, scalar-
+ *  returning functions, or functions with no owned outputs. */
+export declare function computeFutureTouches(stmts: ReadonlyArray<IRStmt>, ownedOutputs?: ReadonlyArray<{
+    cName: string;
+    ty: Type;
+}>): FutureTouchMap;
+/** After emitting `s`, return the set of owned C-names that should
+ *  be freed immediately (no future touch). Helper for emit.ts.
+ *
+ *  The scope-exit free walk emits frees for every owned local
+ *  unconditionally — early-frees null out the buffer and every owned
+ *  `_free` helper is NULL-safe, so a scope-exit free of an already-
+ *  freed local is redundant but safe. */
+export declare function earlyFreeCandidates(s: IRStmt, futureTouches: FutureTouchMap): Set<string>;

package/dist-lib/numbl-core/jit/codegen/prettyIR.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Numbl-like pretty-printer for the IR. Used by the C emitter to
+ * annotate the generated source with readable comments — function
+ * signatures with detailed type info, and a per-statement summary
+ * of the lowered expression above each emitted block.
+ *
+ * The output is NOT a faithful reproduction of the user's source
+ * (synthetic names like `_mtoc2_t1`, ANF temps, and folded branches
+ * are visible). It IS a faithful render of what the IR actually says
+ * after lowering — useful when debugging the translator.
+ */
+import type { IRStmt, IRFunc, IRProgram } from "../lowering/ir.js";
+/** One-line summary of a statement (no trailing newline). Returns null
+ *  for stmts the emitter handles structurally (compound-block bodies
+ *  get their own per-stmt comments inside). */
+export declare function irStmtHeader(s: IRStmt): string | null;
+/** Multi-line C block comment for a function specialization, listing
+ *  name, mangled C identifier, per-parameter types, and output types. */
+export declare function irFuncDocComment(fn: IRFunc): string;
+/** Render the whole lowered IR as a numbl-like script with one block
+ *  per function specialization plus a trailing top-level body. Used by
+ *  the IDE's Internals tab in interpreter mode, where no codegen
+ *  artifact exists. */
+export declare function prettyIRProgram(prog: IRProgram): string;

package/dist-lib/numbl-core/jit/codegen/runtime.d.ts

@@ -0,0 +1,150 @@
+/**
+ * mtoc2 runtime helpers — small C snippets inlined into the generated
+ * source on demand.
+ *
+ * Each helper lives in its own .h file under `runtime/` so it can be
+ * edited with normal C tooling (clangd, syntax highlighting). The .h
+ * sources are inlined into `runtime/snippets.gen.ts` by
+ * `scripts/build_runtime_snippets.ts`; this module reads them from
+ * there (rather than the filesystem at load time) so the translator
+ * bundles in the browser.
+ *
+ * Each helper is referenced by a stable name (e.g. "mtoc2_disp_double").
+ * Snippets can declare other snippets they depend on; the activator
+ * pulls dependencies in first.
+ */
+import type { Builtin } from "../builtins/registry.js";
+/** Minimal Workspace shape consulted at emit time. Importing the
+ *  concrete Workspace class would create a cycle (workspace ↔ codegen);
+ *  the structural type below captures exactly what codegen needs. */
+export interface WorkspaceLike {
+    getUserBuiltin(name: string): Builtin | undefined;
+}
+export interface RuntimeSnippet {
+    /** Standard-library headers parsed out of the source file. */
+    headers: ReadonlyArray<string>;
+    /** Body of the snippet (definitions only — `#include`s removed). */
+    code: string;
+    /** Paired JS body, when a `<basename>.js` sibling exists in the
+     *  runtime directory. Populated by `loadSnippet` from
+     *  `JS_SNIPPETS[<basename>.js]`. `emitJs` activates and inlines
+     *  this; if absent, the snippet is C-only (the builtin that owns
+     *  it has no JS path yet). */
+    jsCode?: string;
+    /** Other helpers (by name) this snippet depends on. The activator
+     *  pulls these in first so their definitions come before this
+     *  snippet's. Cycles are not supported — keep the graph acyclic. */
+    deps: ReadonlyArray<string>;
+    /** `.h` filename this snippet was loaded from (e.g.
+     *  `tensor_alloc_nd.h`). Used to build the JS-import dep map at
+     *  activation time. Optional because user-supplied inline snippets
+     *  have no on-disk file. */
+    srcFilename?: string;
+}
+/**
+ * Parse a raw snippet source string into its `headers` and `code` parts.
+ *
+ * The strict `#include` pattern accepted is:
+ *   optional-whitespace `#` optional-whitespace `include`
+ *   whitespace `<header>` or `"header"` optional-trailing-whitespace
+ *
+ * Any line whose trimmed form starts with `#include` but does NOT match
+ * that pattern is rejected.
+ */
+export declare function parseSnippetSource(raw: string): {
+    headers: string[];
+    code: string;
+};
+/** Public re-export for callers that don't have a `RuntimeState` (the
+ *  build-snippets script). Resolves against the global registry only. */
+export declare function getRuntimeSnippet(name: string): RuntimeSnippet;
+/** Inline snippet definition supplied by a user `.mtoc2.js` builtin's
+ *  `emitC` / `emitJs` via `useRuntime({...})`. Once registered on a
+ *  `RuntimeState`, subsequent activations of the same `name` are
+ *  deduplicated.
+ *
+ *  `code` is the C body (required for `emitC` consumers); `jsCode`
+ *  is the optional JS body (required for `emitJs` consumers but
+ *  ignored on the C path). A builtin that supports both backends
+ *  supplies both; one that only supports C may omit `jsCode`. */
+export interface InlineSnippet {
+    name: string;
+    code: string;
+    jsCode?: string;
+    headers?: ReadonlyArray<string>;
+    deps?: ReadonlyArray<string>;
+}
+export interface RuntimeState {
+    /** Insertion-ordered set of activated snippet names. */
+    active: Set<string>;
+    /** Counter for `MultiAssignCall` discard-temp suffixes so adjacent
+     *  multi-output call sites don't collide on `_mtoc2_discard_<N>_<i>`
+     *  names. Incremented each time a multi-output call is emitted. */
+    multiAssignCallCounter: number;
+    /** Workspace-scoped snippets registered via the user `useRuntime`
+     *  callback. Looked up by name alongside the global registry. */
+    extraSnippets: Map<string, RuntimeSnippet>;
+    /** Workspace reference for resolving names to `.mtoc2.js` user
+     *  builtins during emit. Undefined for non-workspace-driven codegen
+     *  (the snippet-build script, vitest unit tests that bypass the
+     *  workspace). */
+    workspace?: WorkspaceLike;
+    /** JS-side helper: cName list of the currently-emitting user
+     *  function's outputs. Set by `emitFunction` before walking the
+     *  body and cleared after so `ReturnFromFunction` can emit a
+     *  return matching the function's shape (bare value / array /
+     *  nothing). Undefined at top level. */
+    currentFnOutputs?: ReadonlyArray<string>;
+    /** Set when the program contains a scalar indexed STORE, which
+     *  emits the grow-aware `mtoc2_idx_*_grow` bounds checks. The
+     *  host-entry function (storage class `""`) then arms a `setjmp`
+     *  guard so a runtime grow (`v(k) = x`, k past the runtime extent)
+     *  `longjmp`s back and returns cleanly for a host-side bail to the
+     *  interpreter, instead of `exit(1)`. Computed by a pre-pass in
+     *  `emit.ts` so it's set regardless of function emission order. */
+    usedGrowBail?: boolean;
+}
+export declare function newRuntimeState(workspace?: WorkspaceLike): RuntimeState;
+/** Look up a `Builtin` for an emit-time call. Consults the workspace's
+ *  `.mtoc2.js` user builtins first (so a `foo.mtoc2.js` overrides any
+ *  identically-named built-in for callers in this workspace), then
+ *  falls back to the global registry. */
+export declare function lookupBuiltin(state: RuntimeState, name: string): Builtin | undefined;
+/** Activate a snippet by its registered name. Pulls its `deps` in first
+ *  so they appear before it in the final emission order. Also pulls in
+ *  JS-import deps inferred from the snippet's paired `.js` sibling
+ *  (built by `scripts/build_runtime_snippets.ts` into `JS_IMPORTS`),
+ *  so cross-snippet JS calls resolve at runtime even when the C deps
+ *  field doesn't enumerate them. Idempotent. */
+export declare function useRuntimeByName(state: RuntimeState, name: string): void;
+/** Register-and-activate an inline snippet supplied by a user builtin.
+ *  First call registers the snippet on the state; subsequent calls
+ *  (with the same name) are no-ops at the registration step and just
+ *  re-activate through the global pathway. */
+export declare function useRuntimeInline(state: RuntimeState, snippet: InlineSnippet): void;
+/** Build the `useRuntime` callback passed into a `Builtin.emit` call.
+ *  Accepts either a name (resolved against the global mtoc2 runtime
+ *  registry) or an `InlineSnippet` (registered on the current state).
+ *  Centralized here so every emit call site activates snippets
+ *  uniformly. */
+export declare function makeEmitUseRuntime(state: RuntimeState): (spec: string | InlineSnippet) => void;
+/** All headers required by the activated snippets, in insertion order. */
+export declare function collectRuntimeHeaders(state: RuntimeState): string[];
+/** Concatenated bodies (definitions) of activated snippets, in
+ *  activation (dep-respecting) order. */
+export declare function renderRuntimeBodies(state: RuntimeState): string;
+/** JS counterpart of `renderRuntimeBodies` — concatenates the `jsCode`
+ *  fields of activated snippets, in dependency order, skipping
+ *  snippets that have no JS body. The result is plain JS source
+ *  ready to inline at the top of the emitted module so subsequent
+ *  call-site code can reference helpers by bare name.
+ *
+ *  Symmetric with the C side: the same `state.active` set drives
+ *  both renderers — a builtin activates `mtoc2_disp_double` once,
+ *  the C path emits `disp_double.h`'s body, the JS path emits
+ *  `disp_double.js`'s body. */
+export declare function renderJsRuntimeBodies(state: RuntimeState): string;
+/** Stable always-emitted header set — every translation includes these
+ *  so the user-level code can rely on stdio/math without each builtin
+ *  re-declaring them. Kept tiny on purpose. */
+export declare const BASE_HEADERS: ReadonlyArray<string>;

package/dist-lib/numbl-core/jit/compileSpec.d.ts

@@ -0,0 +1,84 @@
+/**
+ * JIT entry point for sibling consumers (e.g. numbl's executor
+ * registry) that want to compile a single user-function
+ * specialization on demand instead of running mtoc2 as a whole-program
+ * AOT translator.
+ *
+ * Bypasses the script-level driver (`translate.ts` / `lowerProject`)
+ * and produces an emitted JS module that returns a factory
+ * `($h) => specFn`. The caller evaluates the source with
+ * `new Function(source)()`, invokes the factory once per spec to bind
+ * its I/O hooks, then calls `specFn(...args)` per dispatch. Per-call
+ * dispatch has no I/O setup cost.
+ *
+ * The `lowerer` argument is the JIT spec cache: passing the same
+ * `Lowerer` instance across calls means `Lowerer.specializations`
+ * accumulates compiled IR across the session, so repeated calls to the
+ * same `(funcDecl, argTypes, nargout)` triple skip the lowering cost.
+ *
+ * Caller responsibilities:
+ *
+ * - **Strip `exact` before calling.** Runtime-observed scalars should
+ *   arrive as opaque-sign types (`scalarDouble("unknown")`,
+ *   `tensorDouble(shape)` without exact data) so that `f(1); f(2);
+ *   f(3)` doesn't shard the spec cache by value. `compileSpec` runs
+ *   `withoutExact` as a defensive second pass.
+ * - **Treat lowering errors as JIT bailouts.** `UnsupportedConstruct`
+ *   and `TypeError` from the lowerer propagate to the caller as the
+ *   "decline this JIT proposal" signal — the caller falls back to its
+ *   interpreter for that dispatch.
+ *
+ * The emitted module includes every spec currently in
+ * `lowerer.specializations` (not just the entry spec), because the
+ * entry spec's body references its transitively-called specs by their
+ * mangled cNames. Dead specs from prior compileSpec calls are bounded
+ * by `MTOC2_MAX_SPECS_PER_FUNCTION` and don't affect correctness; if
+ * profiling shows the re-emit cost dominates, a future change can do
+ * a reachability walk over the entry's IR body.
+ */
+import type { Stmt } from "./parser/index.js";
+import type { Lowerer } from "./lowering/lower.js";
+import type { Workspace } from "./workspace/workspace.js";
+import { type Type } from "./lowering/types.js";
+type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+export interface CompileSpecArgs {
+    /** Workspace whose files are pre-registered. Safe to share across
+     *  many `compileSpec` calls — `Workspace.finalize()` is idempotent
+     *  and nothing in the workspace mutates during lowering. */
+    workspace: Workspace;
+    /** Lowerer whose `.specializations` map persists across calls. Pass
+     *  the same instance throughout the JIT session so cached lowerings
+     *  are reused. */
+    lowerer: Lowerer;
+    /** The function AST to specialize. Caller fetches via
+     *  `workspace.ctx.fileASTCache` or `workspace.resolve(...)`. */
+    funcDecl: FuncStmt;
+    /** Argument types for this specialization. Caller should already
+     *  have stripped `exact`; `compileSpec` runs `withoutExact` again
+     *  defensively. */
+    argTypes: Type[];
+    /** Number of outputs the call site requests. Salts the spec key. */
+    nargout: number;
+}
+export interface CompileSpecResult {
+    /** Mangled spec name (the IRFunc cName). Useful for caller-side
+     *  cache keys and tracing. */
+    cName: string;
+    /** Full module source. Use:
+     *
+     *  ```ts
+     *  const factory = new Function(source)();
+     *  const specFn = factory({ write: (s) => ... });
+     *  const out = specFn(...args);
+     *  ```
+     *
+     *  `$h.write` must be a synchronous string sink that consumes
+     *  `disp` / `fprintf` output. */
+    source: string;
+    /** Names of runtime snippets activated by emit. Diagnostic only. */
+    activatedSnippets: ReadonlyArray<string>;
+}
+export declare function compileSpec(args: CompileSpecArgs): CompileSpecResult;
+export {};