numbl 0.3.3 → 0.4.1

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

@@ -0,0 +1,16 @@
+/**
+ * `diff(A)` / `diff(A, 1)` / `diff(A, 1, dim)` — first-order forward
+ * difference along the operating axis, matching numbl's `diffOnce`
+ * (helpers/reduction/cumulative.ts).
+ *
+ * Scope (v1): first-order (n == 1) real diff of a non-scalar tensor with
+ * a statically-known shape. Declines to the interpreter for:
+ *   - n != 1 (the n-fold loop recomputes the default axis each pass and
+ *     can flip orientation — numbl's own type/value disagree there);
+ *   - the `diff(A, [], dim)` empty-weight form (numbl returns A
+ *     unchanged via a NaN loop count — a quirk not worth matching);
+ *   - complex input, scalar input, non-exact n/dim, out-of-range dim,
+ *     and lattice-only (non-concrete) shapes.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const diff: Builtin;

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

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

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

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

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

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

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

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

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;