numbl 0.3.0 → 0.4.0

package/dist-lib/numbl-core/jit/builtins/defs/reduction/numel.d.ts

@@ -0,0 +1,2 @@
+import type { Builtin } from "../../registry.js";
+export declare const numel: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/reduction/prod.d.ts

@@ -0,0 +1 @@
+export declare const prod: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/reduction/std.d.ts

@@ -0,0 +1 @@
+export declare const stdBuiltin: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/reduction/sum.d.ts

@@ -0,0 +1 @@
+export declare const sum: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/reduction/var.d.ts

@@ -0,0 +1 @@
+export declare const varBuiltin: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/_construct.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Shared infrastructure for the rank-N constructor builtins
+ * (`zeros`, `ones`). Each call site supplies 1..MTOC2_MAX_NDIM scalar
+ * real shape arguments. Each dim arg is either statically-known
+ * (`exact` set on its NumericType) or dynamic (a runtime scalar
+ * `double`); both are accepted. MATLAB's `zeros(n)` / `ones(n)`
+ * one-arg form means an n×n square — codegen routes the dynamic
+ * variant through `mtoc2_tensor_<kind>_square` so the dim expression
+ * is evaluated exactly once.
+ *
+ * When every dim is exact the transfer can compute the shape (and
+ * sometimes the fill data); when any dim is dynamic the result type
+ * is built via `tensorDoubleFromDims` so the unknown axes propagate
+ * through the type lattice unchanged.
+ *
+ * Codegen always emits a runtime call:
+ *   - all-exact dims: `mtoc2_tensor_<kind>_nd(<N>, (long[]){<lit>,…})`
+ *   - dynamic single-arg square form:
+ *     `mtoc2_tensor_<kind>_square((long)(<arg>))`
+ *   - dynamic multi-arg form:
+ *     `mtoc2_tensor_<kind>_nd(<N>, (long[]){<lit-or-cast>,…})`
+ *
+ * The element cap (8 = MTOC2_MAX_NDIM) is enforced at the source side
+ * too; the runtime helper aborts beyond that, but raising at lowering
+ * time gives a proper span.
+ */
+import type { Builtin, InlineSnippet } from "../../registry.js";
+/** Runtime dim validation for the interpreter-shim `call` path —
+ *  mirrors the emitted `mtoc2_check_dim` and the interpreter's
+ *  `validateDim`: reject non-finite / non-integer, clamp negative to 0. */
+export declare function checkDimRuntime(x: number): number;
+/** Runtime dim validator shared by both backends. Mirrors the
+ *  interpreter's `validateDim` (interpreter/builtins/array-construction.ts):
+ *  a non-finite or non-integer size is an error, a negative size clamps
+ *  to 0 (empty axis). A dynamic dim previously truncated silently
+ *  (`(long)` / `Math.trunc`), so `zeros(1, 3.7)` built a 1×3 instead of
+ *  raising. */
+export declare const CHECK_DIM_SNIPPET: InlineSnippet;
+/** Options for `defineShapeConstructor`. When `cFillValue` is set, the
+ *  factory builds a "parameterized fill" constructor: the runtime
+ *  helpers are invoked with `cFillValue` as their first arg
+ *  (`mtoc2_tensor_fill_nd(v, ndim, dims)` style) and the scalar-
+ *  collapse emit uses `cFillValue` verbatim. This is the path used by
+ *  the non-finite constants (`nan`/`NaN`/`Inf`/`inf`), where the JS
+ *  number's `toString` ("NaN" / "Infinity") doesn't round-trip to
+ *  valid C. When `cFillValue` is undefined, the factory keeps the
+ *  original zeros/ones contract: helpers take `(ndim, dims)` only
+ *  and scalar collapse emits a JS-derived literal. */
+interface ShapeConstructorOpts {
+    /** Inclusive lower bound on argument count. Defaults to 1 (zeros /
+     *  ones don't accept the 0-arg form). Set to 0 by callers that
+     *  combine a scalar-constant 0-arg branch with the shape
+     *  constructor (the constants in `math/constants.ts`); the
+     *  combined builtin's transfer/codegen pre-dispatches 0 args
+     *  before delegating to this factory's transfer/codegen. */
+    minArgs?: number;
+    /** When set, prepend this C expression as the first arg of every
+     *  helper call and emit it directly for the scalar-collapse case.
+     *  Required when `fillValue` is non-finite (NaN/Infinity). */
+    cFillValue?: string;
+}
+/** Build a `zeros` / `ones` / fill-style shape-constructor builtin.
+ *  `fillValue` is the constant the output is filled with at the
+ *  type level (Float64Array). See `ShapeConstructorOpts.cFillValue`
+ *  for the per-helper invocation contract. */
+export declare function defineShapeConstructor(name: string, fillValue: number, ndHelper: string, squareHelper: string, opts?: ShapeConstructorOpts): Builtin;
+export {};

package/dist-lib/numbl-core/jit/builtins/defs/shape/_triangular.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared logic for `triu` / `tril` — the two builtins differ only by
+ * the keep-predicate (column - row vs. row - column) and the runtime
+ * helper they dispatch to. This module centralizes:
+ *
+ *   - argument validation (1..2 args, real-double tensor, k literal int)
+ *   - `transfer` (exact-fold when input data fits)
+ *   - hooks builders (emitC / emitJs / call) parameterized by the
+ *     family-specific predicate + runtime helper.
+ *
+ * Mirrors `triPart` in numbl's
+ * `interpreter/builtins/array-extras.ts`. Real and complex inputs
+ * both supported; sparse inputs and rank > 2 are deferred / rejected.
+ */
+import type { Builtin } from "../../registry.js";
+import type { RuntimeTensor } from "../../../runtime/value.js";
+import { mtoc2_tensor_triu as jsTriu, mtoc2_tensor_tril as jsTril, mtoc2_tensor_triu_complex as jsTriuComplex, mtoc2_tensor_tril_complex as jsTrilComplex } from "../../runtime/snippets.gen.js";
+interface TriangularSpec {
+    /** Source-level name (registry key). */
+    name: string;
+    /** C runtime helper name for real-input (e.g. `"mtoc2_tensor_triu"`). */
+    cHelper: string;
+    /** C runtime helper name for complex-input
+     *  (e.g. `"mtoc2_tensor_triu_complex"`). */
+    cHelperComplex: string;
+    /** Keep predicate matching numbl's `triPart` (column-major i,j). */
+    keep(i: number, j: number, k: number): boolean;
+    /** JS-side helper for real input. */
+    jsHelper: (a: RuntimeTensor, k: number) => unknown;
+    /** JS-side helper for complex input. */
+    jsHelperComplex: (a: RuntimeTensor, k: number) => unknown;
+}
+export declare function defineTriangular(spec: TriangularSpec): Builtin;
+export { jsTriu, jsTril, jsTriuComplex, jsTrilComplex };

package/dist-lib/numbl-core/jit/builtins/defs/shape/cat.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `cat` builtin — concatenate N tensors along a given dimension.
+ *
+ * Surface: `cat(dim, A, B, ...)` where `dim >= 1` is a statically-known
+ * positive integer literal (dynamic dims are deferred). Mirrors numbl's
+ * `cat` (and the underlying `catAlongDim` in
+ * `numbl/runtime/tensor-construction.ts`):
+ *
+ *   - dim==1 → vertical concat (along rows). Equivalent to `[A; B]`.
+ *   - dim==2 → horizontal concat (along cols). Equivalent to `[A B]`.
+ *   - dim>=3 → grow a new outer axis; result is N-D.
+ *
+ * Discipline:
+ *   - Every non-dim arg must be numeric (double or logical), real
+ *     or complex. Any complex input contaminates the result to
+ *     complex (real inputs flow through with `imag = 0` lanes).
+ *   - Scalar args are treated as 1×1 tensors (matching numbl).
+ *   - Empty inputs along the cat axis are dropped at runtime. A zero-
+ *     element input also drops when its non-cat dims don't match the
+ *     reference shape (the asymmetric MATLAB rule).
+ *   - All inputs must agree on every non-cat axis; the result extent
+ *     along the cat axis is the sum of input extents.
+ *
+ * Exact-folding: when every input has statically-known shape and exact
+ * data, and the result fits `EXACT_ARRAY_MAX_ELEMENTS`, the result is
+ * computed at transfer time.
+ *
+ * Codegen dispatches to `mtoc2_tensor_cat(dim, nin, xs)` (a single
+ * runtime helper that accepts a tagged-arg array — see
+ * `tensor_cat.h`).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const cat: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/diag.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `diag` builtin — matrix-diagonal extract / vector-to-diagonal
+ * construct.
+ *
+ *   diag(v)     — vector (1×N or N×1) ⇒ N×N matrix with v on the
+ *                 main diagonal, zeros elsewhere.
+ *   diag(A)     — 2-D matrix (neither dim ≡ 1) ⇒ min(M,N)×1 column
+ *                 vector of the main diagonal.
+ *   diag(v, k)  — k-th super-/sub-diagonal. `k` must be a
+ *                 statically-known integer literal. `k > 0` is
+ *                 super-, `k < 0` is sub-diagonal.
+ *   diag(scalar)        — pass-through (matches numbl's 1+|k| sizing
+ *                         with k=0).
+ *   diag(scalar, k≠0)   — (|k|+1)×(|k|+1) matrix with the scalar at
+ *                         the k-th diagonal position.
+ *
+ * Mirrors numbl's `diag` tensor-branch in
+ * `interpreter/builtins/array-manipulation.ts`. Real and complex
+ * inputs both supported (complex routes through `*_diag_*_complex`
+ * runtime helpers); the sparse-matrix branch is N/A (mtoc2 has no
+ * sparse type).
+ *
+ * Input shape must be statically known (matches numbl's eager
+ * dispatch on rows/cols), and `k` must be statically known so the
+ * result shape is decidable at lowering time. Both restrictions can
+ * be relaxed later.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const diag: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/eye.d.ts

@@ -0,0 +1,5 @@
+/**
+ * `eye(n)` and `eye(m, n)` — 2-D identity matrices.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const eye: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/flip.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `flipud`, `fliplr`, `flip` — axis-flip builtins.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const flipud: Builtin;
+export declare const fliplr: Builtin;
+export declare const flip: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/meshgrid.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `meshgrid` — 2-D coordinate grid builder.
+ *
+ * Forms supported:
+ *   - `[X, Y] = meshgrid(x, y)` — `x` length M, `y` length N.
+ *                                  Returns X (N×M, each row = x) and
+ *                                  Y (N×M, each column = y).
+ *   - `[X, Y] = meshgrid(x)`    — shorthand for `meshgrid(x, x)`.
+ *   - `Z = meshgrid(x, y)` / `Z = meshgrid(x)` — returns just X.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const meshgrid: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/ones.d.ts

@@ -0,0 +1 @@
+export declare const ones: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/repmat.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `repmat` builtin. Surface forms (mirrors numbl's
+ * array-manipulation `repmat`):
+ *
+ *   repmat(A, n)            — `n×n` tile (single scalar rep → square)
+ *   repmat(A, m, n, ...)    — Form A: variadic scalar reps per axis
+ *   repmat(A, [m n p ...])  — Form B: dim-vector reps (must be static)
+ *
+ * Discipline:
+ *   - A may be a scalar or a tensor of double / logical / complex
+ *     elements. Complex inputs route through `mtoc2_tensor_repmat_complex`
+ *     (or `_fill_nd_complex` for scalar A).
+ *   - Each rep arg is a scalar real double; statically-known finite
+ *     integers pin the corresponding output axis, dynamic scalars leave
+ *     that axis as `unknown` in the result lattice.
+ *   - Form B requires the dim vector to be a statically-known constant
+ *     (no runtime-vector reps in v1).
+ *   - Negative reps clamp to 0 (matching numbl/MATLAB), which yields an
+ *     empty axis at runtime. Statically-known negatives propagate
+ *     through the type system as 0 too.
+ *   - Output shape is `padShape[i] * padReps[i]` where the input's
+ *     shape and the reps vector are both right-padded with 1s to a
+ *     common rank. There's one numbl quirk we replicate: scalar input
+ *     with a single-element Form B vector (`repmat(5, [3])`) produces
+ *     an `n×n` square instead of a 1-D vector.
+ *
+ * Codegen:
+ *   - Scalar input: emit `mtoc2_tensor_fill_nd(<val>, ndim, dims)`
+ *     directly — no need to build a 1×1 tensor first.
+ *   - Tensor input: emit `mtoc2_tensor_repmat(<in>, ndim, dims)`.
+ *
+ * Exact-data folding: when the input is exact and the reps are exact,
+ * the transfer computes the tiled data and pins it on the result type
+ * (subject to the EXACT_ARRAY_MAX_ELEMENTS cap).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const repmat: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/reshape.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `reshape` builtin. Two surface forms:
+ *
+ *   Form A — variadic scalar dims:  reshape(A, d1, d2, …, dN)
+ *   Form B — vector of dims:        reshape(A, [d1, d2, …, dN])
+ *
+ * Discipline (mirrors numbl's array-manipulation `reshape`):
+ *   - 1 ≤ N ≤ MTOC2_MAX_NDIM (8). Trailing-singletons are stripped
+ *     down to a 2-axis minimum (numbl:
+ *     `while (s.length>2 && s.last===1) s.pop()`), then padded back
+ *     up to 2 axes if N=1 was given (mtoc2 represents every tensor
+ *     as min-2D).
+ *   - Form A — each `di` is a scalar real double; statically-known
+ *     finite non-negative integers pin the corresponding axis, and
+ *     dynamic scalars (no `exact`) leave the axis as `unknown` in
+ *     the result lattice.
+ *   - Form B — the dim vector must be a statically-known
+ *     `Float64Array` of dims (runtime vectors are not yet supported).
+ *   - Form A allows at most one `[]` auto-infer slot. The translator
+ *     fills it from `numel(A)` / `prod(other dims)` when both are
+ *     known statically, else codegen passes `-1L` to
+ *     `mtoc2_reshape_nd` which computes the slot at runtime. Form B
+ *     still rejects the placeholder (the dim vector itself must be a
+ *     static constant; a single `[]` inside the bracket is ambiguous).
+ *   - Input `A` must be a real numeric (scalar or tensor); complex /
+ *     handle / struct / class / void / string rejected with TypeError.
+ *   - Element-count check at transfer time when the input shape and
+ *     every new dim are statically known; deferred to the runtime
+ *     helper otherwise.
+ *
+ * Codegen routes through the per-op runtime helper `mtoc2_reshape_nd`
+ * (declared in `src/codegen/runtime/tensor_reshape_nd.h`), which
+ * already accepts a runtime `(int ndim, const long *dims)` pair plus
+ * an optional `-1L` auto-infer sentinel. The result is freshly owned,
+ * so the standard ANF / scope-exit-free pipeline carries it without
+ * changes.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const reshape: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/size.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `size` builtin.
+ *
+ * Three forms supported in mtoc2 v1:
+ *
+ *   - `size(A)`         → 1×ndim row tensor of dim sizes.
+ *   - `size(A, k)`      → scalar (k-th dim, 1-based).
+ *   - `[d1, d2, ...]    → one scalar per requested output. Each output
+ *     = size(A)`          slot i (0-based) returns `A.dims[i]` when
+ *                         i < ndim and 1 otherwise — matches numbl,
+ *                         which does NOT collapse trailing dims into
+ *                         the last output (unlike MATLAB).
+ *
+ * Multi-output combined with the `dim` arg is rejected — numbl
+ * silently drops the extra outputs in that combo (leaves them
+ * unset), and matching that behavior would leak undefined values
+ * into mtoc2's typed env.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const size: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/sort.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `sort` — stable sort with optional 'ascend' / 'descend' mode arg.
+ *
+ * Supported forms in v1:
+ *   - `b = sort(a)`                       — ascending
+ *   - `b = sort(a, 'ascend' | 'descend')` — explicit mode
+ *   - `[v, i] = sort(...)`                — values + 1-based positions
+ *
+ * Real and complex inputs both supported. Complex sort orders by
+ * magnitude (then phase as tiebreak), matching numbl / MATLAB.
+ *
+ * `dim` arg and `sort(a, dim, mode)` form are out of scope for v1 —
+ * the runtime helper walks the flat column-major buffer and the
+ * type system restricts inputs to 1×N / N×1 vectors. The descending
+ * comparator preserves the stable tie-break (ascending original
+ * index) in both directions, matching numbl.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const sort: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/transpose.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `transpose` builtin — backs the `.'` operator. Conjugate `'` on a
+ * complex input lowers to `transpose(conj(z))`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const transpose: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/tril.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `tril(A [, k])` — lower triangular part of a matrix around the k-th
+ * diagonal. Keeps entries where `i - j >= -k` (equivalently
+ * `j - i <= k`), zeros the rest.
+ *
+ *   tril(A)     ≡ tril(A, 0): zero everything strictly above the main
+ *                 diagonal.
+ *   tril(A, k)  with `k > 0` widens the kept block upward by `k`
+ *                 super-diagonals; `k < 0` narrows it (kept band
+ *                 starts `|k|` below the main diagonal).
+ *
+ * `k` must be a statically-known integer literal. Real and complex
+ * inputs both supported; rank > 2 is deferred with `UnsupportedConstruct`.
+ * Mirrors numbl's `tril` in `interpreter/builtins/array-extras.ts`.
+ */
+export declare const tril: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/triu.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `triu(A [, k])` — upper triangular part of a matrix around the k-th
+ * diagonal. Keeps entries where `j - i >= k`, zeros the rest.
+ *
+ *   triu(A)     ≡ triu(A, 0): zero everything strictly below the main
+ *                 diagonal.
+ *   triu(A, k)  with `k > 0` shifts the kept band upward (kept block
+ *                 starts at the k-th super-diagonal); `k < 0` shifts
+ *                 downward (kept block extends into the |k| sub-
+ *                 diagonals).
+ *
+ * `k` must be a statically-known integer literal. Real and complex
+ * inputs both supported; rank > 2 is deferred with `UnsupportedConstruct`.
+ * Mirrors numbl's `triu` in `interpreter/builtins/array-extras.ts`.
+ */
+export declare const triu: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/shape/zeros.d.ts

@@ -0,0 +1 @@
+export declare const zeros: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/system/deal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `deal` — multi-output passthrough.
+ *
+ *   [a, b, c] = deal(x, y, z)   → a=x, b=y, c=z       (N-arg form)
+ *   [a, b, c] = deal(x)         → a=x, b=x, c=x       (broadcast form)
+ *   a        = deal(x)          → x
+ *
+ * Numbl's rule (the dialect oracle): single-input broadcasts to any
+ * `nargout >= 1`; otherwise `args.length` must equal `nargout` or
+ * it's a runtime error. mtoc2 lifts the equality check into
+ * `transfer` so the mismatch is a type-time error.
+ *
+ * The result types are the input types as-is. The c-aot backend
+ * still has to emit `_copy(...)` for owned types to satisfy the
+ * "freshly-owned at every consume site" invariant; the js-aot
+ * backend uses `mtoc2_deep_clone` for the same reason; the
+ * interpreter follows numbl and deep-clones owned values too.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const deal: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/system/feval.d.ts

@@ -0,0 +1,36 @@
+/**
+ * feval(handle_or_name, args...) — invoke a function handle (or a
+ * function named by a char) with the given args.
+ *
+ * Implementation strategy:
+ *
+ *   The c-aot / js-aot backends cannot route through a builtin
+ *   emitC / emitJs hook because invoking a user function requires
+ *   specialization (the target's mangled C name is created at
+ *   lowering time, with the actual arg types) — information a
+ *   builtin emit hook doesn't have access to. So the lowerer
+ *   intercepts `feval(...)` in `lowerFuncCall` and
+ *   `lowerMultiAssign` and rewrites it to a direct call on the
+ *   underlying handle / function name (see `tryLowerFevalCall` in
+ *   `src/lowering/lowerFuncCall.ts`). Once the rewrite fires, the
+ *   builtin's emit hooks are never reached.
+ *
+ *   The interpreter parallels this with a special-case in
+ *   `callByName` (next to the existing `struct` / `cell`
+ *   special-cases) — it consumes args[0] as a handle or char,
+ *   dispatches via `callHandle` or recursively via `callByName`,
+ *   and threads `nargout` through. Once that fires, this builtin's
+ *   `call` hook is unreachable.
+ *
+ *   This file therefore exists primarily to:
+ *     - keep `feval` in `allBuiltinNames()` for syntax highlighting
+ *       and the `@feval` rejection path,
+ *     - validate arity / argument shape via `transfer` as a safety
+ *       net if a future codepath bypasses the lowerer / interpreter
+ *       interception.
+ *
+ *   All four hooks raise `UnsupportedConstruct` with a message
+ *   pointing the reader at where the real implementation lives.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const feval: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/system/pathBuiltins.d.ts

@@ -0,0 +1,4 @@
+import type { Builtin } from "../../registry.js";
+export declare const addpath: Builtin;
+export declare const rmpath: Builtin;
+export declare const savepath: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/system/tic.d.ts

@@ -0,0 +1,8 @@
+/**
+ * tic — start the wall-clock stopwatch.
+ *
+ * Returns the start time in seconds (matches numbl: `performance.now()
+ * / 1000`).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const tic: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/system/toc.d.ts

@@ -0,0 +1,5 @@
+/**
+ * toc — read the elapsed wall-clock seconds since `tic`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const toc: Builtin;

package/dist-lib/numbl-core/jit/builtins/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Builtins package. Each builtin lives in its own file and is registered
+ * here via `registerBuiltin`. Public API:
+ *
+ *  - `getBuiltin(name)` / `allBuiltinNames()` for runtime lookup.
+ *  - `binaryOpBuiltin(op)` / `unaryOpBuiltin(op)` to map AST operator
+ *    enums to builtin names.
+ *
+ *  See `registry.ts` for the `Builtin` interface and the registry itself.
+ */
+import type { Span } from "../parser/index.js";
+import { BinaryOperation, UnaryOperation } from "../parser/index.js";
+export type { Builtin } from "./registry.js";
+export { registerBuiltin, getBuiltin, allBuiltinNames } from "./registry.js";
+export declare function binaryOpBuiltin(op: BinaryOperation, span: Span): string;
+export declare function unaryOpBuiltin(op: UnaryOperation, span: Span): string;

package/dist-lib/numbl-core/jit/builtins/registry.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Builtin registry — the contract every mtoc2 builtin (and future
+ * user `.mtoc2.js` function) implements.
+ *
+ * Each builtin can supply up to three mirrored hooks plus the
+ * always-required `transfer`:
+ *
+ *   transfer(argTypes, nargout) — required. Given input types and
+ *     the number of outputs the call site wants, return one Type
+ *     per output. When every input is exact, set `exact` on the
+ *     returned type(s) so the lowerer can key specialization on the
+ *     value (and fold `if` conditions). Throws plain `Error` /
+ *     `TypeError` / `UnsupportedConstruct` on bad input — no source
+ *     span; the framework attaches the call-site span via `withSpan`.
+ *
+ *   emitC({argsC, argTypes, nargout, outArgsC?, useRuntime}) —
+ *     optional. C codegen. Returns the full string ready to splice
+ *     into the surrounding context:
+ *       - nargout=1: a C expression (`(a + b)`,
+ *         `mtoc2_tensor_plus_tt(a, b)`)
+ *       - nargout≥2: a full call including out-pointer args
+ *         (`mtoc2_sort_real_2(a, &v, &i)`). `outArgsC` holds those
+ *         pre-built `&v`, `&i` strings in the order the call site
+ *         requested.
+ *     Activate any runtime snippets this emit-output references by
+ *     calling `useRuntime(name)`.
+ *
+ *   emitJs({argsJs, argTypes, nargout, outTargetsJs?, useRuntime}) —
+ *     optional. JS codegen. Returns a JS expression (or call
+ *     sequence) ready to splice. Multi-output calls receive
+ *     `outTargetsJs` pre-built as `o1`, `o2`, … the secondary
+ *     outputs land in these locals via the framework's destructuring
+ *     wrapper. Activates JS-side runtime snippets via `useRuntime`.
+ *
+ *   call({args, argTypes, nargout, ctx}) — optional. Direct JS
+ *     function used by the interpreter and as a JIT bailout target.
+ *     Returns one runtime value per output slot. The args shape
+ *     mirrors the emit hooks' shape so dispatch on `argTypes` /
+ *     `nargout` stays parallel across all three.
+ *
+ *   elementwise? — when true, every defined emit hook (and `call`)
+ *     must also produce a correct scalar output when called with
+ *     scalar argTypes and scalar argsC/argsJs/args. The framework
+ *     uses this for same-shape tensor fusion (and, later, broadcast
+ *     / reduction-inner / mask / stencil fusion). Absence = "do not
+ *     fuse me; use the regular emit on the full tensor types."
+ *
+ * Each backend selector requires the matching hook to be defined on
+ * every builtin in the call's transitive reach; the framework
+ * computes the maximum compatible backend per call site.
+ */
+import type { Type } from "../lowering/types.js";
+import type { RuntimeValue } from "../runtime/value.js";
+import type { RuntimeContext } from "../runtime/context.js";
+/** Common across every hook — the type-level call descriptor. */
+interface CommonArgs {
+    /** Per-arg type (after lowering / inference). */
+    argTypes: Type[];
+    /** Number of outputs requested at the call site. */
+    nargout: number;
+}
+export interface EmitCArgs extends CommonArgs {
+    /** Per-arg C expression. In fused contexts this is scalar form
+     *  (e.g. `<var>.real[i]`); in the regular path it's whatever the
+     *  framework's `emitExpr` produced. */
+    argsC: string[];
+    /** Out-pointer C expressions for multi-output calls (length =
+     *  nargout when nargout≥2; otherwise undefined). The framework
+     *  pre-builds these as `&v`, `&i`, … so `emit` just splices them
+     *  in. */
+    outArgsC?: string[];
+    /** Activate a runtime C snippet on the current translation unit.
+     *  See `runtime.ts` for the registry and `InlineSnippet` for the
+     *  user-supplied form. */
+    useRuntime(spec: string | InlineSnippet): void;
+}
+export interface EmitJsArgs extends CommonArgs {
+    /** Per-arg JS expression. */
+    argsJs: string[];
+    /** Out-target JS expressions for multi-output calls. The
+     *  framework pre-builds these as `o1`, `o2`, … and destructures
+     *  the call's return into them. Length equals `nargout-1` when
+     *  `nargout≥2` (the primary output is the expression's value).
+     *  Undefined for `nargout≤1`. */
+    outTargetsJs?: string[];
+    /** Activate a JS-side runtime snippet. Snippets are inlined once
+     *  per build at the top of the emitted module, so the call site
+     *  invokes them by bare name. Mirrors the C-side `useRuntime` —
+     *  same registry, paired `.h`/`.js` source files. An `InlineSnippet`
+     *  (with a `jsCode` body) defines a one-off helper from a builtin. */
+    useRuntime(spec: string | InlineSnippet): void;
+}
+export interface CallArgs extends CommonArgs {
+    /** Per-arg runtime values, evaluated by the interpreter at the
+     *  call site. */
+    args: RuntimeValue[];
+    /** Host bag — `helpers.write` for stdout, future hooks for plot /
+     *  error / time. */
+    ctx: RuntimeContext;
+}
+export interface Builtin {
+    /** Source-level name (registry key). */
+    name: string;
+    /** Required: output Type per output slot. Pure — safe to invoke
+     *  as a probe (the framework calls this for bare-identifier 0-arg
+     *  detection). */
+    transfer(argTypes: Type[], nargout: number): Type[];
+    /** Optional: C codegen. */
+    emitC?(args: EmitCArgs): string;
+    /** Optional: JS codegen. */
+    emitJs?(args: EmitJsArgs): string;
+    /** Optional: direct JS function — interpreter / JIT bailout. */
+    call?(args: CallArgs): RuntimeValue[];
+    /** Elementwise = result is computed pointwise. */
+    elementwise?: boolean;
+}
+/** Inline-defined runtime snippet supplied by a user `.mtoc2.js`
+ *  builtin's `emitC` / `emitJs`. Re-exported from `runtime.ts` — kept
+ *  here for doc-locality with the `Builtin` contract. */
+export interface InlineSnippet {
+    name: string;
+    /** C body (required for `emitC` consumers; ignored on the JS path). */
+    code: string;
+    /** Optional JS body (required for `emitJs` consumers). */
+    jsCode?: string;
+    headers?: ReadonlyArray<string>;
+    deps?: ReadonlyArray<string>;
+}
+export declare function registerBuiltin(b: Builtin): void;
+export declare function getBuiltin(name: string): Builtin | undefined;
+/** Names of every registered builtin. Drives Monaco syntax highlighting. */
+export declare function allBuiltinNames(): readonly string[];
+export type Backend = "c" | "js" | "interpreter";
+export declare function builtinSupports(b: Builtin, backend: Backend): boolean;
+export declare function requireEmitC(b: Builtin): (args: EmitCArgs) => string;
+export declare function requireEmitJs(b: Builtin): (args: EmitJsArgs) => string;
+export declare function requireCall(b: Builtin): (args: CallArgs) => RuntimeValue[];
+export {};

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

@@ -0,0 +1,24 @@
+/** Construct a cell from a flat slot list (column-major) and a shape.
+ *  Caller has already produced fresh slot values (deep_clone'd where
+ *  the slot was an owned alias), so we simply build the wrapper. */
+export function mtoc2_cell_make(slots: any, shape: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+/** `cell(n)` / `cell(n, m)` / `cell(n, m, k, ...)`. The 1-arg square
+ *  form has already been expanded to two dim args at lowering time so
+ *  this helper is dim-symmetric.
+ *
+ *  Each axis is coerced to a non-negative integer (matching numbl —
+ *  `Math.floor` then clamp at 0). The slot count is the dim product;
+ *  each slot is the empty-double sentinel. */
+export function mtoc2_cell_empty(dims: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any[];
+};
+/** Format a cell value to match numbl's `formatCell` byte-for-byte:
+ *  `{e1, e2, ...}` with chars in `'...'`, strings in `"..."`, other
+ *  values via `formatValue`. Empty cell renders as `{}`. */
+export function mtoc2_format_cell(c: any): string;

package/dist-lib/numbl-core/jit/builtins/runtime/indexing/loop_count.d.ts

@@ -0,0 +1 @@
+export function mtoc2_loop_count(start: any, end: any, step: any): number;