numbl 0.3.0 → 0.4.0

package/dist-lib/numbl-core/jit/builtins/defs/logical/typequery.d.ts

@@ -0,0 +1,10 @@
+import type { Builtin } from "../../registry.js";
+export declare const islogical: Builtin;
+export declare const isfloat: Builtin;
+export declare const ischarBuiltin: Builtin;
+export declare const isstring: Builtin;
+export declare const isinteger: Builtin;
+export declare const ndims: Builtin;
+export declare const ismatrix: Builtin;
+export declare const isrow: Builtin;
+export declare const iscolumn: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/logical/xor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `xor(a, b)` — logical exclusive-or of two real scalars. The result is
+ * a logical scalar that is `true` iff exactly one operand is nonzero.
+ *
+ * Scalar-only: tensor or complex operands throw `UnsupportedConstruct`
+ * so the call falls back to the interpreter (which broadcasts and
+ * handles complex). Booleanization uses `(x != 0)` on the C side and
+ * `Number(x) !== 0` on the JS side so both agree element-for-element —
+ * including `NaN` (nonzero → true on both).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const xorBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/_complex_fold.d.ts

@@ -0,0 +1,34 @@
+/**
+ * JS-side scalar-complex fold functions for unary math builtins.
+ *
+ * Mirrors the cscalar.h `mtoc2_c*` helpers — both the C side and
+ * c2js's JS-runtime side must agree with these formulas. Used by
+ * `_unary_real.ts`'s factory at type-system-fold time when an input
+ * has an exact `{re, im}` carrier.
+ *
+ * Real input is projected to `{re: x, im: 0}` upstream of these
+ * helpers via `exactScalarAsComplex`; that case is rare for unary
+ * math since the same builtin's real-path fold already catches it.
+ */
+export type C = {
+    re: number;
+    im: number;
+};
+export declare function cSqrt(z: C): C;
+export declare function cExp(z: C): C;
+export declare function cLog(z: C): C;
+export declare function cLog2(z: C): C;
+export declare function cLog10(z: C): C;
+export declare function cSin(z: C): C;
+export declare function cCos(z: C): C;
+export declare function cTan(z: C): C;
+export declare function cSinh(z: C): C;
+export declare function cCosh(z: C): C;
+export declare function cTanh(z: C): C;
+export declare function cAtan(z: C): C;
+export declare function cFloor(z: C): C;
+export declare function cCeil(z: C): C;
+/** Half-away-from-zero on each component (matches C99 `round`). */
+export declare function cRound(z: C): C;
+export declare function cFix(z: C): C;
+export declare function cSign(z: C): C;

package/dist-lib/numbl-core/jit/builtins/defs/math/_unary_real.d.ts

@@ -0,0 +1,51 @@
+import { type NumericType, type Sign } from "../../../lowering/types.js";
+import type { Builtin } from "../../registry.js";
+export interface UnaryRealMathOpts {
+    /** Source-level builtin name (also the runtime helper suffix). */
+    name: string;
+    /** C `<math.h>` function name for the scalar path (e.g. `"cos"`). */
+    cFnReal: string;
+    /** JS-side scalar fn for compile-time fold (and for the interpreter's
+     *  `call` hook). */
+    jsFn: (x: number) => number;
+    /** Optional JS expression form (textual) for `emitJs`'s scalar real
+     *  path. Defaults to `Math.${name}(arg)` which works for most names
+     *  (sin/cos/tan/sqrt/exp/log/log2/log10/abs/atan/floor/ceil/sign).
+     *  Override for `fix` (`Math.trunc`) and `round`
+     *  (custom half-away-from-zero form). */
+    jsExpr?: (arg: string) => string;
+    /** Sign refinement on the result type. Called with the (validated)
+     *  real-numeric input type. */
+    signRule: (t: NumericType) => Sign;
+    /** Optional real-domain predicate. `true` means the real input stays
+     *  on the real path; `false` means it leaves the real domain (would
+     *  produce NaN / -Inf / complex). When `false` AND `complex.liftOnDomainMiss`
+     *  is set, the call lifts to the complex path (real-input,
+     *  complex-output); otherwise the factory throws `TypeError`. */
+    realDomainOk?: (t: NumericType) => boolean;
+    /** Optional complex-input support. When set, complex scalars route
+     *  through `cFnComplex` (a `mtoc2_c*` helper); complex tensors
+     *  route through `mtoc2_tensor_<name>_complex`. `jsFnComplex`
+     *  folds at the type-system layer when the input has an exact
+     *  `{re, im}` carrier. `liftOnDomainMiss` makes the factory lift
+     *  a real-typed input through the same complex path when
+     *  `realDomainOk` returns false (e.g. `sqrt(-1)`). */
+    complex?: {
+        cFnComplex: string;
+        jsFnComplex: (z: {
+            re: number;
+            im: number;
+        }) => {
+            re: number;
+            im: number;
+        };
+        liftOnDomainMiss?: boolean;
+    };
+}
+/** Sign rule for rounding-toward-zero builtins (`fix`, `round`, `ceil`,
+ *  `floor`). Captures the "may collapse to zero" pattern: if a side of
+ *  the number line can land on 0, its strict-sign input weakens to the
+ *  corresponding non-strict sign. The flags say whether the operation's
+ *  rounding direction can reach 0 from that side. */
+export declare function roundingSignRule(positiveCanLand: boolean, negativeCanLand: boolean): (t: NumericType) => Sign;
+export declare function defineUnaryRealMath(opts: UnaryRealMathOpts): Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/abs.d.ts

@@ -0,0 +1,7 @@
+import { type Builtin } from "../../registry.js";
+/** Complex-aware `abs`. Real inputs route through the existing real
+ *  builtin (preserving its sign refinement and tensor path); complex
+ *  inputs return `hypot(creal, cimag)` per-element, with a REAL result
+ *  type (different shape contract from the rest of the unary-math
+ *  family). */
+export declare const abs: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/angle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `angle(z)` — phase angle in radians. Returns `atan2(im, re)`. For
+ * real input the result is 0 when the value is non-negative, π when
+ * negative; complex input yields `carg(z)`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const angle: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/asinh.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/atan.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/atan2.d.ts

@@ -0,0 +1,3 @@
+/** Two-argument arctangent. Result is in (-π, π]; sign is generally
+ *  `unknown`. */
+export declare const atan2: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/besselh.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/ceil.d.ts

@@ -0,0 +1,4 @@
+/** `ceil(x)` rounds toward +Inf. Complex inputs round each component
+ *  independently. Only `negative` inputs may land on 0
+ *  (e.g. `ceil(-0.5) = 0`); `positive` inputs are bounded away. */
+export declare const ceil: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/conj.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `conj(z)` — complex conjugate. Accepts real or complex, scalar or
+ * tensor. For real input it's the identity; for complex input it
+ * flips the sign of the imaginary part.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const conj: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/constants.d.ts

@@ -0,0 +1,7 @@
+import { type Builtin } from "../../registry.js";
+export declare const pi: Builtin;
+export declare const eps: Builtin;
+export declare const Inf: Builtin;
+export declare const inf: Builtin;
+export declare const NaNBuiltin: Builtin;
+export declare const nan: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/cos.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/cosh.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/dot.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `dot(a, b)` — real or complex dot product.
+ *
+ * Numbl semantics
+ * (`numbl-core/interpreter/builtins/linear-algebra.ts`):
+ *   - Two same-length 1-D vectors (any combination of row / column /
+ *     scalar) → scalar `sum_i a_i * b_i` (real) or
+ *     `sum_i conj(a_i) * b_i` (complex).
+ *   - Two matrices of the **same** shape M×N → column-wise dot,
+ *     returned as a 1×N row vector.
+ *   - Length / shape mismatch → runtime error.
+ *   - Any complex operand promotes the result to complex (real
+ *     tensors flow through with `imag = 0`).
+ *
+ * Real folding: when both inputs are exact and small enough, the
+ * result is computed at type-check time and lands as `exact` on the
+ * output type, so call sites used in `if`-conds get the static fold.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const dot: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/double.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `double(x)` — numeric conversion to double.
+ *
+ * Matches numbl `type-constructors.ts`:
+ *   - Numeric scalar (double / logical / complex_or_number):
+ *     scalar real number out. For complex scalars, returns the real
+ *     part (numbl's `apply` returns `v.re`).
+ *   - Numeric tensor: same shape; logical lane → double (drop the
+ *     logical flag); complex tensors pass through as complex
+ *     (numbl preserves `isComplex` in the match shape).
+ *   - Char (single-quoted): char-code conversion. Empty → 0×0
+ *     tensor; 1 char → scalar double; N chars → 1×N row.
+ *
+ * Scope notes:
+ *   - The mtoc2 C representation already stores logical and double
+ *     scalars as `double`, and logical tensors as `mtoc2_tensor_t`
+ *     with a `double *` buffer. So a numeric → double conversion is
+ *     either identity (scalar) or a fresh struct copy (tensor); no
+ *     per-element rewrite is needed.
+ *   - Char input is supported only when the char carries `exact`
+ *     (the common case — char literals always carry exact text).
+ *     Non-exact char input (e.g. `double(sprintf(...))`) raises
+ *     `UnsupportedConstruct`. Folding at transfer time avoids
+ *     introducing a new runtime helper for the char-tensor → numeric
+ *     tensor path.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const doubleBuiltin: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/exp.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/fix.d.ts

@@ -0,0 +1,4 @@
+/** `fix(x)` truncates toward zero (C99 `trunc`). Complex inputs truncate
+ *  each component independently. Both `positive` and `negative` inputs
+ *  may collapse to 0 (e.g. `fix(±0.5) = 0`). */
+export declare const fix: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/floor.d.ts

@@ -0,0 +1,4 @@
+/** `floor(x)` rounds toward -Inf. Complex inputs round each component
+ *  independently (MATLAB convention). Only `positive` inputs may land
+ *  on 0 (e.g. `floor(0.5) = 0`); `negative` inputs are bounded away. */
+export declare const floor: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/hypot.d.ts

@@ -0,0 +1,3 @@
+/** `hypot(a, b) = sqrt(a^2 + b^2)`. Always `nonneg` (C99 `hypot`
+ *  guarantees no spurious overflow for finite inputs). */
+export declare const hypot: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/imag.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `imag(z)` — imaginary part. Accepts scalar real or complex; returns
+ * a real double. For real input the result is always 0; for complex
+ * input the result is `cimag(z)`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const imag: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/linspace.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `linspace(a, b)` / `linspace(a, b, n)` — n linearly-spaced values
+ * from `a` to `b` inclusive as a 1×n row tensor.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const linspace: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/log.d.ts

@@ -0,0 +1,4 @@
+/** Natural log. Provably non-negative real inputs stay on the real
+ *  path (`log(0) = -Inf` is still real-typed in MATLAB); anything that
+ *  could be negative lifts to the complex path. */
+export declare const log: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/log10.d.ts

@@ -0,0 +1,3 @@
+/** Base-10 log. Same non-negative real-domain rule as `log`; negative
+ *  inputs lift to the complex path. */
+export declare const log10: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/log2.d.ts

@@ -0,0 +1,5 @@
+/** Base-2 log. Same non-negative real-domain rule as `log`; negative
+ *  inputs lift to the complex path. Single-output form only; two-output
+ *  frexp form `[f,e] = log2(x)` is deferred.
+ */
+export declare const log2: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/logspace.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `logspace(a, b)` / `logspace(a, b, n)` — n logarithmically-spaced
+ * values from 10^a to 10^b as a 1×n row tensor (default n = 50).
+ * Matches numbl's interpreter, including the MATLAB special case where
+ * an upper limit of exactly `pi` makes the last point `pi` (not 10^pi).
+ */
+import type { Builtin } from "../../registry.js";
+export declare const logspace: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/mod.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/norm.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/real.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `real(z)` — real part. Accepts scalar real or complex; returns a
+ * real double. For real input it's the identity; for complex input
+ * the result is `creal(z)`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const real: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/rem.d.ts

@@ -0,0 +1,3 @@
+/** `rem(a, b)`: same as JS `%` and C `fmod` — result sign tracks `a`'s
+ *  sign. */
+export declare const rem: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/round.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/sign.d.ts

@@ -0,0 +1,5 @@
+/** `sign(x)`:
+ *   - Real input ∈ {-1, 0, 1}; the result's sign mirrors the input's.
+ *   - Complex input → `z / |z|` for nonzero, `0 + 0i` for `0 + 0i`.
+ *     The complex sign is itself complex. */
+export declare const signBuiltin: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/sin.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/sinh.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/sqrt.d.ts

@@ -0,0 +1,11 @@
+/** `sqrt(x)`: real input that's provably non-negative stays on the
+ *  real path; everything else lifts to the complex path
+ *  (`mtoc2_csqrt` for scalars, `mtoc2_tensor_sqrt_complex` for
+ *  tensors). Matches MATLAB: `sqrt(-1)` returns `0 + 1i`,
+ *  `sqrt([-1 4])` returns `[0+1i, 2]`.
+ *
+ *  Sign rule on the (real-path) input:
+ *   - `positive` → `positive` (sqrt of strictly positive is strictly positive)
+ *   - everything else (`nonneg` / `zero`) → `nonneg`.
+ */
+export declare const sqrt: import("../../registry.js").Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/math/tan.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/tanh.d.ts

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

package/dist-lib/numbl-core/jit/builtins/defs/math/uniquetol.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `uniquetol(x)` / `uniquetol(x, tol)` — first-occurrence dedup of
+ * a real-double tensor with absolute tolerance.
+ *
+ * Numbl semantics
+ * (`numbl-core/interpreter/builtins/set-operations.ts`):
+ *   - Default `tol = 1e-6` when no second arg.
+ *   - Algorithm: naive pairwise scan against the running unique
+ *     list — first-occurrence order preserved, NOT sorted.
+ *     Transitive chaining is a real consequence (e.g.
+ *     `uniquetol([0 0.6 1.2 1.8], 0.7) == [0 1.2]`).
+ *   - NaN is never within tol of anything; each NaN survives.
+ *   - Output shape: row input (1×N) → row output `[1, ?]`;
+ *     anything else (column / matrix / empty) → column output
+ *     `[?, 1]`. Empty input gives `[0, 1]`.
+ *
+ * The multi-output `[c, ia, ic] = uniquetol(...)` form, the
+ * `'ByRows'` name-value pair, and complex inputs are not yet
+ * supported and raise `UnsupportedConstruct`.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const uniquetol: Builtin;

package/dist-lib/numbl-core/jit/builtins/defs/plot/dispatch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Plot dispatch — every plotting builtin (`plot`, `surf`, `imagesc`,
+ * `bar`, `figure`, `hold`, `xlabel`, …) shares a single lowering.
+ */
+import type { Builtin } from "../../registry.js";
+export declare const plotBuiltins: ReadonlyArray<Builtin>;

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

@@ -0,0 +1,49 @@
+/**
+ * Shared scaffold for the `cumsum` / `cumprod` family — prefix-scan
+ * builtins that return a tensor of the SAME shape as the input.
+ *
+ * Mirrors numbl's `cumOp` (helpers/reduction/cumulative.ts) for both
+ * default-axis pick (first dim > 1, else dim 1) and per-fiber column-
+ * major scan. Real and complex inputs both supported; complex routes
+ * through `_complex_dim` runtime helpers that scan both lanes
+ * (cumprod uses per-step complex multiplication).
+ *
+ * Exact-fold rule: when input has an exact data carrier AND the result
+ * fits `EXACT_ARRAY_MAX_ELEMENTS`, scan at translate time and attach
+ * the result as `exact` on the returned type.
+ *
+ * Out of scope: runtime (non-exact) `dim`, and the lattice-only shape
+ * form when no dim is given (`cumsum(A)` on a tensor whose static shape
+ * is unknown raises — pass an explicit dim).
+ */
+import { type Sign } from "../../../lowering/types.js";
+import type { Builtin } from "../../registry.js";
+export interface CumulativeSpec {
+    /** Source-level builtin name (also the runtime helper suffix:
+     *  `mtoc2_tensor_<name>_dim`). */
+    name: string;
+    /** Identity seed (`0` for cumsum, `1` for cumprod). */
+    init: number;
+    /** Per-element accumulator step (real). */
+    step(acc: number, x: number): number;
+    /** Per-element accumulator step (complex). Takes `(accRe, accIm,
+     *  xRe, xIm)` and returns the next `[re, im]` pair. Required when
+     *  `supportsComplex` is not `false`. */
+    stepComplex?(accRe: number, accIm: number, xRe: number, xIm: number): [number, number];
+    /** Sign rule on the result given the input's sign. */
+    signRule(s: Sign): Sign;
+    /** Whether complex input is JIT-compiled. Defaults to `true`
+     *  (cumsum/cumprod). `cummax`/`cummin` set this `false`: numbl's
+     *  complex cummax is a quirky component-wise max that isn't worth
+     *  replicating — complex input declines to the interpreter. */
+    supportsComplex?: boolean;
+}
+export declare function defineCumulative(spec: CumulativeSpec): Builtin;
+/** cumsum: a prefix sum of like-signed values stays in the same sign
+ *  class. (Mixed signs collapse to `unknown` because partial sums can
+ *  cross zero.) */
+export declare function cumsumSign(s: Sign): Sign;
+/** cumprod: products of nonneg stay nonneg; products of positives stay
+ *  positive; everything else (including alternating-sign negative
+ *  inputs) is `unknown`. */
+export declare function cumprodSign(s: Sign): Sign;

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

@@ -0,0 +1,126 @@
+/**
+ * Shared reducer infrastructure for the `sum / prod / mean / min /
+ * max / any / all` family. Each builtin is a thin wrapper that
+ * supplies its kernel spec (init, op, finalize, sign rule, empty
+ * result) and lets this module drive transfer / codegen / arity.
+ *
+ * Numbl is the dialect oracle (see `../numbl/src/numbl-core/interpreter/
+ * builtins/reductions.ts`). The shape rules here mirror numbl's
+ * `shapeAfterReduction` against mtoc2's `DimInfo` lattice
+ * (`{exact, value}` / `unknown`) plus concrete `shape` when set.
+ *
+ * The lattice analysis is sharper than numbl's static type pass in one
+ * place worth flagging:
+ *   - A `(unknown, 1, ..., 1)` dims signature (e.g. a slice
+ *     `M(:, 2:3)` of a known-row-vector `M`) proves the output is
+ *     scalar even though the leading dim's runtime length is unknown,
+ *     because every later axis is statically `1`.
+ *
+ * Folding: when every input element is exact (scalar `t.exact: number`
+ * or tensor `t.exact: Float64Array`), the transfer computes the
+ * compile-time result. We cap the materialized result size at
+ * `EXACT_ARRAY_MAX_ELEMENTS`; beyond the cap the runtime path takes
+ * over.
+ *
+ * Out of scope: complex inputs, the `omitnan` / `includenan` flag,
+ * runtime (non-exact) integer `dim`, and multi-output
+ * `[v, i] = min(x)` — all rejected with span.
+ */
+import { type DimInfo, type NumericType, type Sign, type Type } from "../../../lowering/types.js";
+import type { Builtin } from "../../registry.js";
+/** What kind of reducer we're computing. Drives the kernel pieces
+ *  (init / accumulator / finalizer / empty fallback / sign rule /
+ *  result element type) without each builtin file rewriting the
+ *  reduce loop. */
+export interface KernelSpec {
+    /** Public source-level name (e.g. `"sum"`). */
+    name: string;
+    /** Position of the dim slot in the source-level arg list. For
+     *  `sum/prod/mean/any/all`: slot 2 (`name(A, dim)`).
+     *  For `min/max`: slot 3 (`name(A, [], dim)`). */
+    dimArgIndex: 1 | 2;
+    /** Identity / empty result. For scalar reducers (`sum`, `prod`,
+     *  `mean`), the empty-data scalar (`0`, `1`, `NaN`). For
+     *  logical reducers (`any`, `all`), 0 or 1. For NaN-seed
+     *  reducers (`min`, `max`), `NaN`. */
+    emptyValue: number;
+    /** Accumulator step. NaN-aware (the impl skips NaN where
+     *  appropriate). Receives the running accumulator and the next
+     *  element; returns the new accumulator. */
+    step(acc: number, x: number, count: number): number;
+    /** Optional finalizer (e.g. mean divides by count). */
+    finalize?(acc: number, count: number): number;
+    /** Output element kind. `"double"` for sum/prod/mean/min/max,
+     *  `"logical"` for any/all. */
+    outputElem: "double" | "logical";
+    /** Compute the sign of the result given the *input* type plus a
+     *  flag indicating whether the reduced fiber is provably
+     *  non-empty. */
+    resultSign(t: NumericType, nonEmpty: boolean): Sign;
+}
+export interface AxisAll {
+    kind: "all";
+}
+export interface AxisFixed {
+    kind: "fixed";
+    /** 1-based axis number, statically known. */
+    dim: number;
+}
+/** When no explicit dim was supplied, pick the reduction axis from
+ *  the input's lattice. This is the sharp pass: a leading `unknown`
+ *  followed only by `one` axes still proves the output is scalar
+ *  (the leading axis MUST be the non-singleton one, or the whole
+ *  tensor is `(1×1×…)`-shaped → scalar collapse anyway).
+ *
+ *  Returns `all` for the degenerate `(1, 1, ...)` case (matches
+ *  scalar input), `fixed(k)` for a clearly chosen axis, or throws
+ *  for the genuinely ambiguous case (`unknown` leading dim followed
+ *  by at least one known-non-1 or another `unknown`). */
+export declare function chooseDefaultAxis(name: string, t: NumericType): AxisAll | AxisFixed;
+/** Mirror of numbl's `shapeAfterReduction(shape, dim)` on a concrete
+ *  shape. Returns either `{ scalar: true }` (every axis is 1 after
+ *  the collapse) or `{ scalar: false, shape: [...] }`. */
+export declare function reduceConcreteShape(shape: number[], dim: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    shape: number[];
+};
+/** Same as `reduceConcreteShape` but for the lattice form. Result
+ *  is either `scalar` (every dim collapses to `one`) or a new dims
+ *  array, post-squeeze. */
+export declare function reduceLatticeDims(dims: DimInfo[], dim: number): {
+    scalar: true;
+} | {
+    scalar: false;
+    dims: DimInfo[];
+};
+/** The transfer function. Returns the result type; throws with no
+ *  span (framework's `withSpan` backfills at the call site). */
+export declare function reductionTransfer(argTypes: Type[], spec: KernelSpec): Type;
+export declare function reductionEmitJs(spec: {
+    name: string;
+    dimArgIndex: 1 | 2;
+    outputElem: "double" | "logical";
+}): Builtin["emitJs"];
+export declare function reductionCall(spec: {
+    name: string;
+    dimArgIndex: 1 | 2;
+    outputElem: "double" | "logical";
+}): Builtin["call"];
+export declare function reductionEmit(spec: {
+    name: string;
+    dimArgIndex: 1 | 2;
+    outputElem: "double" | "logical";
+}): Builtin["emitC"];
+/** Build a complete `Builtin` registration from a `KernelSpec`. */
+export declare function defineReducer(spec: KernelSpec): Builtin;
+export declare function sumSign(t: NumericType, nonEmpty: boolean): Sign;
+export declare function meanSign(t: NumericType, nonEmpty: boolean): Sign;
+export declare function prodSign(t: NumericType, nonEmpty: boolean): Sign;
+/** Sign transfer for `min` and `max` reductions on a real fiber.
+ *  min and max preserve the same sign classes: both stay in the
+ *  half-line their input occupies (positive→positive,
+ *  negative→negative, nonneg/zero→nonneg, nonpositive→nonpositive),
+ *  so the two ops share one transfer. */
+export declare function minMaxSign(t: NumericType, nonEmpty: boolean): Sign;

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

@@ -0,0 +1,17 @@
+/**
+ * `var` / `std` reductions. Two-pass (mean, then mean-square-deviation),
+ * matching numbl's `varianceOf` (interpreter/builtins/reductions.ts):
+ *
+ *   var(A)          weight 0 (÷ n-1), reduce along the first non-singleton axis
+ *   var(A, w)       w ∈ {0, 1}: 0 ÷ (n-1), 1 ÷ n
+ *   var(A, w, dim)  reduce along axis `dim`
+ *   var(A, w, 'all')reduce every element
+ *   std(...)        = sqrt(var(...))
+ *
+ * Real only. Complex input, vector weights, `omitnan`/`includenan`,
+ * the empty-weight `var(A, [], dim)` form, and runtime (non-exact) w/dim
+ * all decline to the interpreter. A scalar input yields 0 (numbl returns
+ * 0 for any scalar, regardless of value or weight).
+ */
+import type { Builtin } from "../../registry.js";
+export declare function defineVariance(name: "var" | "std"): Builtin;

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

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

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

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

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

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

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

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

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

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

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

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

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;