numbl 0.3.3 → 0.4.1

package/dist-lib/numbl-core/jit/lowering/lowerTensorLit.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bracket-literal lowering: `[1 2 3]`, `[1; 2; 3]`, `[A B; C D]`, etc.
+ *
+ * Reached from `lowerExpr` whenever the AST node is a `Tensor`. The
+ * lowerer classifies every cell as scalar / tensor / empty, then takes
+ * one of three paths:
+ *
+ *  - **All-scalar fast path** — every cell is a scalar; collapse to a
+ *    single `TensorBuild` IR node with a column-major exact-data
+ *    carrier when the result fits the cap.
+ *  - **Singleton collapse** — `[v]` returns `v` unchanged (whether
+ *    scalar or tensor), matching MATLAB.
+ *  - **Concat path** — mixed scalar/tensor cells (or all-tensor
+ *    cells), with per-row horzcat shape and an outer vertcat. Empty
+ *    cells are dropped. Per-row width / per-cell height mismatches
+ *    are caught statically when both sides are known; runtime-only
+ *    axes trust the user (a future `mtoc2_check_concat_axis` could
+ *    validate at runtime).
+ */
+import type { Expr } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerTensorLit(this: Lowerer, e: Extract<Expr, {
+    type: "Tensor";
+}>): IRExpr;

package/dist-lib/numbl-core/jit/lowering/rangeCount.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Compile-time range-element-count formula. Single source of truth for
+ * the `n = floor((end - start) / step + 1 + 1e-10)` formula used in
+ * three places: `lowerRangeAsValue` (range-as-value `1:n`), the
+ * `exactRangeCount` helper in `lowerIndexSlice.ts`, and the C-side
+ * `mtoc2_loop_count` runtime helper. All three must agree byte-for-
+ * byte so the statically-known shape, the runtime-allocated buffer
+ * length, and the for-loop iteration count match.
+ *
+ * The `+ 1e-10` cushion absorbs the IEEE-ulp underflow on ranges like
+ * `0:0.1:0.3` (where `(0.3-0)/0.1` evaluates to 2.99999... rather
+ * than 3.0) without affecting genuinely-non-integer quotients.
+ */
+/** Compute the count of elements in a range `start : step : end`,
+ *  given that every endpoint is a finite real number and `step` is
+ *  non-zero. Returns 0 for empty ranges (e.g. `5:1:0`). The caller
+ *  is responsible for checking finiteness and `step !== 0` before
+ *  calling. */
+export declare function rangeCountFromExactEnds(start: number, step: number, end: number): number;

package/dist-lib/numbl-core/jit/lowering/specialize.d.ts

@@ -0,0 +1,93 @@
+/**
+ * User-function specialization machinery.
+ *
+ * `specializeUserFunction` is the single chokepoint that turns a
+ * parsed `function` AST into an `IRFunc` against a specific arg-type
+ * tuple, with the spec cache keyed on `(file, argTypes, nargout)`.
+ * Every expression-context user-function call (bare-name, packaged
+ * `pkg.foo`, instance / static class methods, method-via-arg-type,
+ * handle dispatch) routes through `buildUserFunctionCall`, which
+ * calls `specializeUserFunction` for the spec lookup and synthesizes
+ * the matching `Call` IR node.
+ *
+ * Lives in its own module so the new user-defined `.js` function
+ * feature has a clear integration surface: a sidecar can either
+ * register a builtin (which doesn't need this path at all) or
+ * synthesize a `decl: FuncStmt` and reuse the existing spec discipline.
+ */
+import type { Stmt } from "../parser/index.js";
+import type { Span } from "../parser/index.js";
+import type { IRExpr, IRFunc } from "./ir.js";
+import { type Type } from "./types.js";
+import type { Lowerer } from "./lower.js";
+type FuncStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+/** Build a single-output `Call` IR node against a user-function AST,
+ *  specializing the body on the arg-type tuple. Single chokepoint for
+ *  every expression-context user-function call: bare-name calls,
+ *  packaged (`pkg.foo`) calls, instance / static class methods,
+ *  method-call-via-arg-type, and handle dispatch. Each caller is
+ *  still responsible for the verdict-specific bookkeeping (resolver
+ *  routing, prepending the receiver to args for instance methods,
+ *  rejecting >=2-output methods if its dispatch path doesn't yet
+ *  support truncation, …) — but the spec lookup + output-type
+ *  derivation + IR construction is uniform here.
+ *
+ *  For 0-output declarations the resulting `Call` has `ty = VOID`,
+ *  which the caller (`lowerExprStmt`) must accept as bare-statement
+ *  use only. For >=1-output declarations the spec truncates to
+ *  nargout=1 and the result type is the (possibly Unknown if the
+ *  body didn't assign the output) first declared output.
+ *
+ *  The N≥2-output path uses a separate `MultiAssignCall` IR node
+ *  built by `lowerMultiAssign` — this helper is single-output only. */
+export declare function buildUserFunctionCall(this: Lowerer, decl: FuncStmt, callArgs: IRExpr[], callName: string, span: Span, opts?: {
+    specSource?: string;
+    definingFile?: string;
+}): IRExpr;
+/** Specialize a user function (or method, or anonymous-function
+ *  synth) on the given arg-type tuple. The C mangling salts by the
+ *  defining file so two files defining a same-named subfunction get
+ *  distinct mangled names.
+ *
+ *  Caller is responsible for passing `definingFile` — for top-level
+ *  functions resolved through the workspace, that's the resolver's
+ *  verdict file; for class methods it's the class's file; for
+ *  anonymous-function synth ASTs it's the file where `@(...)` was
+ *  written. */
+export declare function specializeUserFunction(this: Lowerer, decl: FuncStmt, argTypes: Type[], 
+/** Optional override for the specialization-key source-name half.
+ *  Class methods pass `<className>__<methodName>` so the mangled C
+ *  name disambiguates two methods of the same source-level name
+ *  on different classes. Defaults to `decl.name`. */
+specSource?: string, 
+/** File the function definition lives in. Salts the spec key so
+ *  cross-file homonyms get distinct C names. Defaults to the
+ *  function's source span's file. */
+definingFile?: string, 
+/** When set, the named output gets a synthetic first assignment to
+ *  `initExpr` (an already-lowered IR expression) prepended to the
+ *  body. The user's constructor body then sees the receiver
+ *  initialized with the class defaults. */
+preSeedOutput?: {
+    name: string;
+    ty: Type;
+    initExpr: IRExpr;
+}, 
+/** Per-call-site `nargout`: the number of outputs the caller
+ *  requested. Salts the spec key so two callers requesting
+ *  different output counts get distinct specializations. Defaults
+ *  to `decl.outputs.length` (the declared count) when the caller
+ *  can't supply a more specific value (e.g. cross-file resolver
+ *  paths that don't yet thread this through). Inside the body, the
+ *  `nargout` identifier folds to this value via the
+ *  `callFrameStack`. */
+nargout?: number, 
+/** Span of the call site, used to attribute arity / output-
+ *  assignment errors. Defaults to `decl.span` (the function
+ *  definition) when omitted — but every translation-time call site
+ *  should supply its own span so the user sees the bad call, not
+ *  the definition. */
+callSiteSpan?: Span): IRFunc;
+export {};

package/dist-lib/numbl-core/jit/lowering/types.d.ts

@@ -0,0 +1,503 @@
+/**
+ * mtoc2 type system. Built from scratch — not derived from numbl's
+ * JitType. Designed to be the long-term home for static type info,
+ * with "exact known value" tracking as a first-class feature on
+ * every scalar (and eventually small arrays).
+ *
+ * MVP scope: scalar real double only. The full Type union and the
+ * NumericType field layout already accommodate growth (complex,
+ * arrays, strings, logicals, structs, classes) but the lowerer and
+ * codegen reject anything outside scope with UnsupportedConstruct.
+ */
+import type { Span, Stmt } from "../parser/index.js";
+type FunctionStmt = Extract<Stmt, {
+    type: "Function";
+}>;
+export type Sign = "positive" | "nonneg" | "negative" | "nonpositive" | "zero" | "nonzero" | "unknown";
+export declare function signFromNumber(v: number): Sign;
+/** Derive the sign of a tensor from its exact data. Returns the
+ *  tightest lattice state that holds across every element:
+ *  - all `>0` → `positive`
+ *  - all `<0` → `negative`
+ *  - all `===0` → `zero`
+ *  - mix of `>0` and `==0` → `nonneg`
+ *  - mix of `<0` and `==0` → `nonpositive`
+ *  - mix of `>0` and `<0` (no zeros) → `nonzero`
+ *  - any NaN, or mix of all three (positives, negatives, zeros) → `unknown`.
+ *
+ *  Empty data returns `unknown` (no elements to constrain). */
+export declare function signFromExactArray(data: Float64Array): Sign;
+export declare function unifySign(a: Sign, b: Sign): Sign;
+export declare function flipSign(s: Sign): Sign;
+/** Per-axis dimension knowledge. Either the exact non-negative integer
+ *  size is known, or we have no info. There's no separate ">1" lattice
+ *  state — call sites that previously cared about "definitely > 1"
+ *  now check `d.kind === "exact" && d.value !== 1` (or `value > 1`,
+ *  depending on whether a zero-sized axis should count).
+ *  When all entries in a `dims` array are `exact`, the surrounding
+ *  `NumericType.shape` is also set; the two views never disagree. */
+export type DimInfo = {
+    kind: "exact";
+    value: number;
+} | {
+    kind: "unknown";
+};
+export declare const DIM_ONE: DimInfo;
+/** Convenience: does this `DimInfo` statically pin the axis to 1? */
+export declare function isDimOne(d: DimInfo): boolean;
+/** Product of every entry in `shape` — i.e. `numel` for a tensor with
+ *  this concrete shape. Returns 1 for an empty shape array (a 0-D
+ *  scalar in MATLAB terms; mtoc2 always pads to 2-D so this is rare
+ *  but well-defined). */
+export declare function shapeNumel(shape: ReadonlyArray<number>): number;
+/** Cap for how big an "exact array" we'll propagate through the type
+ *  system. Anything larger drops to non-exact. */
+export declare const EXACT_ARRAY_MAX_ELEMENTS = 256;
+/** Max rank for `mtoc2_tensor_t`. Mirror of `MTOC2_MAX_NDIM` in
+ *  `src/codegen/runtime/tensor.h` — kept in lockstep with the runtime
+ *  helpers that allocate per-axis stride/index buffers on the stack. */
+export declare const MTOC2_MAX_NDIM = 8;
+/** Exact-value variants.
+ *  - `number`: scalar real.
+ *  - `{re,im}`: scalar complex.
+ *  - `Float64Array`: dense real array, column-major (matches numbl's
+ *    `RuntimeTensor.data`). Shape is carried by `dims` on `NumericType`.
+ *  - `{re: Float64Array; im: Float64Array}`: dense complex array,
+ *    column-major split-buffer (mirrors the runtime layout). */
+export type NumericExact = number | {
+    re: number;
+    im: number;
+} | Float64Array | {
+    re: Float64Array;
+    im: Float64Array;
+};
+export type NumericElem = "double" | "logical" | "char";
+export interface NumericType {
+    kind: "Numeric";
+    elem: NumericElem;
+    isComplex: boolean;
+    /** Per-axis dim info: each axis is either `{exact, value}` or
+     *  `unknown`. Always present. Length 2 for scalars
+     *  (`[{exact,1},{exact,1}]`); same length as `shape` when `shape`
+     *  is set. */
+    dims: DimInfo[];
+    /** Statically-known integer shape, when available (always set when
+     *  every entry in `dims` is `exact`; mirrors those values).
+     *  `shape[i]` equals `dims[i].value` for every axis. */
+    shape?: number[];
+    sign: Sign;
+    exact?: NumericExact;
+}
+/** Scalar string handle — the double-quoted (`"foo"`) text type.
+ *  `length("foo") == 1` (numbl treats it as a single value, not a
+ *  byte array). Backed by `mtoc2_string_t` in emitted C; participates
+ *  in the standard owned-value lifecycle (empty/assign/copy/free).
+ *  `exact` carries the literal value when the source is a `"..."`
+ *  expression. */
+export interface StringType {
+    kind: "String";
+    exact?: string;
+}
+/** 1×N row-vector of bytes — the single-quoted (`'foo'`) char-array
+ *  type. `length('foo') == 3` (numbl exposes the byte count). Backed
+ *  by `mtoc2_char_tensor_t` in emitted C; same owned-value lifecycle
+ *  as `String`. Multi-row chars aren't constructable in v1, so the
+ *  type doesn't carry a shape — `exact.length` is the column count.
+ *  `exact` carries the literal value when the source is a `'...'`
+ *  expression. */
+export interface CharType {
+    kind: "Char";
+    exact?: string;
+}
+export interface UnknownType {
+    kind: "Unknown";
+}
+/** One captured variable in a `HandleType`. The `name` is both the
+ *  enclosing-scope identifier the @-site snapshot reads from AND the
+ *  synthesized function's tail-param name; the `ty` is the captured
+ *  value's type at the @-site. Captures of owned types (tensors,
+ *  structs, classes, other handles) are deep-copied into the handle's
+ *  C struct at the `@(...)` site, matching MATLAB by-value capture
+ *  semantics; the handle's per-shape `_free` helper releases each
+ *  owned field at scope exit. */
+export interface HandleCapture {
+    name: string;
+    ty: Type;
+}
+/** Function handle. mtoc2 supports only user-function targets
+ *  (named `@user_func` and anonymous `@(p1,...,pN) <body>`); `@builtin`
+ *  is rejected. Captures may be any non-Void / non-Unknown / non-String
+ *  value type — scalar real numeric, tensor, struct, class instance, or
+ *  another handle. The handle's C representation is a per-capture-shape
+ *  typedef with `_empty / _copy / _assign / _free` helpers, matching
+ *  the struct/class owned-value lifecycle. */
+export interface HandleType {
+    kind: "Handle";
+    /** Source-level identifier for the target function. For named
+     *  handles, this is the user's name (e.g. `sq`); for anonymous
+     *  handles, the synthesized name (e.g. `anon_0`). Used as the
+     *  source-name half of the specialization mangling. */
+    targetName: string;
+    /** Synthesized or pre-scanned `Function` AST handed to
+     *  `specializeUserFunction` at every call site. The params list
+     *  contains `[...userParams, ...captureNames]` (in that order); the
+     *  body's references to a captured variable resolve naturally to the
+     *  matching synthesized tail param. */
+    ast: FunctionStmt;
+    /** Variables captured from the enclosing scope at the `@(...)` site.
+     *  Empty for named handles and for capture-free anonymous functions.
+     *  Field order matches the synth function's tail params. */
+    captures: ReadonlyArray<HandleCapture>;
+}
+/** "No value" — the type of a call to a user function with zero
+ *  outputs. Valid only as the expression type of an `ExprStmt`. Every
+ *  other lowering site (Assign RHS, sub-expression of a Binary / Unary
+ *  / Call, tensor-literal element, if/while cond, for bounds) rejects
+ *  Void with `UnsupportedConstruct`. */
+export interface VoidType {
+    kind: "Void";
+}
+/** A struct value. Field order is canonical (sorted by name) so two
+ *  StructType values with the same shape are structurally identical
+ *  regardless of source-level field-write order. Construct via
+ *  `structType()` rather than the raw interface so the sort is
+ *  applied. */
+export interface StructType {
+    kind: "Struct";
+    fields: ReadonlyArray<{
+        name: string;
+        ty: Type;
+    }>;
+}
+/** A class instance value. The `className` is the source-level class
+ *  name (the `classdef Foo` identifier); `properties` is the full
+ *  flattened-and-sorted property list with each property's type
+ *  derived from its `properties` block default expression. v1
+ *  forbids inheritance, so the property list is always exactly the
+ *  one declared in the class body. */
+export interface ClassType {
+    kind: "Class";
+    className: string;
+    properties: ReadonlyArray<{
+        name: string;
+        ty: Type;
+    }>;
+}
+/** Cell array. Two modes:
+ *  - **tuple**: per-slot types, used when the cell's shape is exact
+ *    AND the total slot count fits `EXACT_ARRAY_MAX_ELEMENTS`. Cell
+ *    literals `{a, b, c}` and small `cell(n, m)` constructors land
+ *    here. `elements.length === shape product`; slot k is the
+ *    column-major-flat index. Each `elements[k]` is the *static*
+ *    type of slot k.
+ *  - **uniform**: a single `elem` type covers every slot. Used for
+ *    `cell(n, m)` with a non-exact dim or a slot count above the
+ *    cap, and for tuple cells that "demote" on a non-static-index
+ *    write whose existing slot types all unify with the rhs type.
+ *
+ *  Cells have no LUB / heterogeneous mode. When neither tuple nor
+ *  uniform applies (a non-static-index write into a tuple whose
+ *  slot types don't all unify with the rhs), the lowerer raises
+ *  `UnsupportedConstruct`. */
+export interface CellType {
+    kind: "Cell";
+    mode: "tuple" | "uniform";
+    dims: DimInfo[];
+    shape?: number[];
+    /** Tuple-mode only: per-slot types in column-major order. */
+    elements?: Type[];
+    /** Uniform-mode only: every slot has this type. */
+    elem?: Type;
+}
+export type Type = NumericType | StringType | CharType | UnknownType | VoidType | HandleType | StructType | ClassType | CellType;
+export declare const VOID: VoidType;
+export declare function scalarDouble(sign?: Sign, exact?: number): NumericType;
+/** Scalar complex double. Sign is always `unknown` for complex values
+ *  — the sign lattice describes ordering on the real line, which has
+ *  no analogue for complex numbers. When `exact` is provided, both
+ *  `re` and `im` must be finite. */
+export declare function scalarComplex(exact?: {
+    re: number;
+    im: number;
+}): NumericType;
+export declare function scalarLogical(exact?: boolean): NumericType;
+/** Real-double tensor built from a per-axis `dims` lattice. Used by
+ *  slice-read result typing when the slot pattern leaves at least one
+ *  axis with a runtime-only length (an `unknown` `DimInfo`). When every
+ *  dim turns out to be `exact`, this function also populates `shape`
+ *  so downstream code can take the concrete-shape paths uniformly.
+ *
+ *  Trailing singletons in `dims` are stripped subject to a 2-axis
+ *  minimum, matching numbl's tensor shape-normalization rule. */
+export declare function tensorDoubleFromDims(dims: DimInfo[]): NumericType;
+/** Real-double tensor with statically-known shape. `dims` is derived
+ *  from `shape` (`{kind:"exact", value: s}` per axis). When `exact` is
+ *  provided, its length must equal the shape's product; the layout is
+ *  column-major (matching numbl's `RuntimeTensor.data`).
+ *
+ *  When `exact` is provided, `sign` is derived from the actual values
+ *  via `signFromExactArray`. This is what lets `sqrt([0 1 4 9])` pass
+ *  the requireDomain check (without it the tensor would carry
+ *  `sign:"unknown"`). For tensors without exact data the caller can
+ *  set `sign` post-construction (e.g. `zeros`/`ones` know their fill
+ *  value even when the result is too large to carry exact data). */
+export declare function tensorDouble(shape: number[], exact?: Float64Array): NumericType;
+/** Complex-double tensor with statically-known shape. Mirrors
+ *  `tensorDouble` but the result type carries `isComplex: true` and
+ *  the optional `exact` is the split-buffer carrier whose `re` /
+ *  `im` Float64Arrays each match the shape product. Sign is always
+ *  `"unknown"` for complex (the lattice describes ordering on the
+ *  real line; complex numbers have no analogue). */
+export declare function tensorComplex(shape: number[], exact?: {
+    re: Float64Array;
+    im: Float64Array;
+}): NumericType;
+/** Complex-double tensor built from a per-axis `dims` lattice. Sibling
+ *  of `tensorDoubleFromDims` for slice-read result typing when at
+ *  least one axis is runtime-only. */
+export declare function tensorComplexFromDims(dims: DimInfo[]): NumericType;
+export declare const UNKNOWN: UnknownType;
+/** Constructor for a `@<user_func>` handle (named or anonymous). */
+export declare function handleType(targetName: string, ast: FunctionStmt, captures?: ReadonlyArray<HandleCapture>): HandleType;
+/** Construct a `StructType`, preserving the given field order.
+ *
+ *  Field order is OBSERVABLE in MATLAB — disp, `fieldnames`, and
+ *  `struct2cell` all report insertion order — so we must NOT sort:
+ *  sorting made the JIT display fields alphabetically while the
+ *  interpreter (and MATLAB) keep insertion order. The C typedef layout
+ *  and the JS struct object both follow this `fields` order, so keeping
+ *  insertion order aligns storage and display. The cost is that two
+ *  structs built with the same names in different orders no longer share
+ *  a typedef (they're distinct field orders, exactly as in MATLAB). */
+export declare function structType(fields: ReadonlyArray<{
+    name: string;
+    ty: Type;
+}>): StructType;
+/** Construct a `ClassType` with canonical (sorted-by-name) property
+ *  order. */
+export declare function classType(className: string, properties: ReadonlyArray<{
+    name: string;
+    ty: Type;
+}>): ClassType;
+/** Construct a tuple-mode `CellType`. The caller must provide a fully
+ *  exact shape (every entry in `dims` is `exact`) and an `elements`
+ *  array whose length equals the shape product. */
+export declare function cellTuple(shape: number[], elements: Type[]): CellType;
+/** Construct a uniform-mode `CellType`. Used when the cell's slot
+ *  count exceeds `EXACT_ARRAY_MAX_ELEMENTS`, when a dim is non-exact,
+ *  or when a tuple cell demotes after a non-static-index write. */
+export declare function cellUniform(dims: DimInfo[], elem: Type): CellType;
+/** The canonical "empty `[]` double tensor" slot type — what numbl
+ *  initialises every fresh slot in `cell(n, m)` to
+ *  (see `numbl/.../type-constructors.ts:442-469`). Shape is `[0, 0]`,
+ *  no exact data, sign unknown. Mtoc2 reuses this exact representation
+ *  so cross-runner displays of an unwritten slot match byte-for-byte. */
+export declare function emptyDoubleTensorType(): NumericType;
+export declare function isNumeric(t: Type): t is NumericType;
+export declare function isVoid(t: Type): t is VoidType;
+export declare function isHandle(t: Type): t is HandleType;
+export declare function isStruct(t: Type): t is StructType;
+export declare function isClass(t: Type): t is ClassType;
+export declare function isString(t: Type): t is StringType;
+export declare function isChar(t: Type): t is CharType;
+export declare function isCell(t: Type): t is CellType;
+/** True when `t` can be consumed by a "text-accepting" runtime helper
+ *  via `mtoc2_text_view_t` — today: a `String` handle or a `Char` array.
+ *  The shared predicate lets builtins like `disp` / future
+ *  `error` / `fprintf` accept either source kind. */
+export declare function isText(t: Type): boolean;
+/** Find a field on a struct/class by name. Returns the field's type
+ *  or undefined if the type isn't a struct/class or no such field
+ *  exists. */
+export declare function fieldType(t: Type, name: string): Type | undefined;
+export declare function isScalar(t: Type): boolean;
+export declare function isScalarRealDouble(t: Type): boolean;
+/** Scalar real numeric: double or logical. Both are stored as `double`
+ *  in emitted C, so anything operating on real values accepts either. */
+export declare function isScalarRealNumeric(t: Type): boolean;
+/** True when any axis is statically known to be ≠ 1 (or unknown).
+ *  Drives the scalar/tensor split in codegen: scalars compile to bare
+ *  `double`; multi-element values compile to `mtoc2_tensor_t`. A
+ *  zero-sized axis (`{exact, 0}`) also returns true — an empty tensor
+ *  still needs tensor storage. */
+export declare function isMultiElement(t: Type): boolean;
+/** Row-vector shape: 2-D with a singleton first axis and an exact
+ *  non-singleton second axis. Matches MATLAB's "row" classification:
+ *  1×0 (empty row) qualifies, 1×1 (scalar) does not. */
+export declare function isRowVecTy(t: NumericType): boolean;
+/** Column-vector shape: 2-D with an exact non-singleton first axis and
+ *  a singleton second axis. Matches MATLAB's "column" classification:
+ *  0×1 (empty column) qualifies, 1×1 (scalar) does not. */
+export declare function isColVecTy(t: NumericType): boolean;
+/** Statically provable to contain at least one element. True iff every
+ *  dim is `exact` with a positive value (equivalently, when `shape` is
+ *  set, every entry is > 0). Used by reductions to decide whether the
+ *  empty-input edge case (sum→0, prod→1, min/max→NaN, mean→NaN) is
+ *  reachable; tighter sign rules apply only on the provably-non-empty
+ *  branch. */
+export declare function provablyNonEmpty(t: NumericType): boolean;
+/** Owned-heap-value types — i.e. types whose C representation holds a
+ *  heap pointer the codegen must `free` at scope exit. Multi-element
+ *  tensors are the original owned kind. Structs, class instances, and
+ *  function handles all count as owned because their per-shape generated
+ *  typedef carries the same `_empty()`/`_assign()`/`_copy()`/`_free()`
+ *  lifecycle — a struct or handle with all-scalar fields would
+ *  technically be POD, but tracking ownership uniformly keeps the
+ *  codegen pipeline simple and lets struct fields and handle captures
+ *  hold tensors transparently. */
+export declare function isOwned(t: Type): boolean;
+/** Types that may appear in an N≥2-output multi-assign slot. Scalar
+ *  real numeric outputs are stored by `*_mtoc2_o<i> = <local>` struct-
+ *  copy; owned outputs (tensor, struct, class instance, function
+ *  handle, Char, String) use the kind's `_assign` helper to transfer
+ *  ownership of the buffer pointer. Only Void / Unknown stay rejected. */
+export declare function isMultiOutputSlotType(t: Type): boolean;
+export declare function signIsNonneg(s: Sign): boolean;
+export declare function signIsPositive(s: Sign): boolean;
+export declare function numericExactsEqual(a: NumericExact | undefined, b: NumericExact | undefined): boolean;
+/** Widen every entry in `env` whose name is in `names` before lowering
+ *  a loop body. Used by `lowerFor` / `lowerWhile` — see lower.ts for
+ *  rationale. Strips `exact` (the one-pass lowerer can't carry exact
+ *  values across iterations) AND widens narrowing fields like `sign`
+ *  to `"unknown"`, since a `sign: "nonneg"` set before the loop is no
+ *  longer valid if the body reassigns the variable to a negative value.
+ *  Without the sign widen, `sqrt(x)` / `log(x)` domain checks would
+ *  spuriously pass at lowering time and produce NaN at runtime. For
+ *  struct / class env entries we recurse via `withoutExact` so any
+ *  precise field/property exact values introduced by a `struct(...)`
+ *  literal or a constructor preSeed don't leak from iteration 1 into
+ *  the rest of the loop's body. */
+export declare function stripExactFromEnv(env: Map<string, {
+    cName: string;
+    ty: Type;
+}>, names: Iterable<string>): void;
+/** Drop `exact` and widen `sign` toward the rhs sign on the named
+ *  entry. Called after an indexed write (`x(i) = rhs`, `x(:) = rhs`, …)
+ *  where the rhs is general enough that we can't carry the pre-write
+ *  sign forward unchanged.
+ *
+ *  Without this, e.g. `x = zeros(1, 5); x(3) = -10; sqrt(x)` would slip
+ *  past `sqrt`'s `requireDomain` check because the env still claims
+ *  `sign = nonneg`. We use `unifySign(current, rhsSign)` so a same-sign
+ *  rhs (e.g. `x(3) = 4` after `zeros(...)`) doesn't unnecessarily
+ *  collapse the lattice — the new sign covers both the surviving
+ *  pre-write elements and the just-written one.
+ *
+ *  `rhsSign` defaults to `"unknown"` for callers that don't have a
+ *  rhs to inspect (slice writes from an opaque source, etc.). */
+export declare function widenAfterIndexedWrite(env: Map<string, {
+    cName: string;
+    ty: Type;
+}>, name: string, rhsSign?: Sign): void;
+/** Return a copy of `t` with the type at `fieldPath` replaced by
+ *  `newLeafTy`. Walks struct/class types; if the path can't be
+ *  resolved (shouldn't happen — the caller already validated), the
+ *  original type is returned unchanged. Other type kinds at a path
+ *  step are returned as-is.
+ *
+ *  Used by the env refresh after a MemberStore / member-rooted
+ *  IndexStore so subsequent reads of the touched field report the
+ *  post-write rhs type rather than the construction-site default. */
+export declare function withPathTypeUpdated(t: Type, fieldPath: ReadonlyArray<string>, newLeafTy: Type): Type;
+/** Companion to `widenAfterIndexedWrite` for member-rooted indexed
+ *  writes (`obj.field(i) = rhs`). Strips `exact` and widens the
+ *  leaf field's `sign` to `"unknown"`, then rebuilds the parent
+ *  struct/class type via `withPathTypeUpdated`. The optimisation of
+ *  refreshing the leaf's exact carrier in place (the way bare-Ident
+ *  writes do) is deferred — see `tryRefreshExactAfterIndexedWrite`. */
+export declare function widenMemberLeafAfterIndexedWrite(env: Map<string, {
+    cName: string;
+    ty: Type;
+}>, rootName: string, fieldPath: ReadonlyArray<string>, oldLeafTy: NumericType): void;
+export declare function withoutExact(t: Type): Type;
+/** Merge two types at a join point. Drops exact unless both sides agree.
+ *  Sign widens via `unifySign`. For MVP, both sides should be scalar real
+ *  double — mismatches return `UNKNOWN`. */
+export declare function unify(a: Type, b: Type): Type;
+/** Demote a tuple-mode cell to uniform mode if every slot type
+ *  unifies. Returns undefined if the cell is already uniform (no
+ *  work) or if the demotion isn't possible (heterogeneous slot
+ *  types). Used inside `unify` and at non-static-index writes. */
+export declare function cellWidenToUniform(t: CellType): CellType | undefined;
+export declare function typeToString(t: Type): string;
+/** Stable string key used for the specialization-key hash. Includes
+ *  exact when set, so each unique exact-value gets its own spec. */
+export declare function canonicalizeType(t: Type): string;
+/** True iff two types have the same canonical form. Convenience
+ *  wrapper around `canonicalizeType` for callers that don't need the
+ *  string key. */
+export declare function canonicalEq(a: Type, b: Type): boolean;
+/** Storage compatibility: do two types occupy the same C-level slot?
+ *  This is COARSER than canonical equality — every multi-element
+ *  tensor shares the same `mtoc2_tensor_t` storage regardless of
+ *  shape, every scalar real numeric maps to `double`, and every
+ *  struct/class needs its canonical typedef to match.
+ *
+ *  Used by `MemberStore` to validate that a write doesn't try to
+ *  cram a tensor into a scalar slot (or vice versa) — the typedef
+ *  hash is built from storage shapes, so changing the underlying
+ *  representation would break the C side. Shape, sign, and exact
+ *  differences are fine: the slot still holds an `mtoc2_tensor_t`. */
+export declare function storageEquivalent(a: Type, b: Type): boolean;
+/** FNV-1a 32-bit; matches the mangling scheme used in current mtoc. */
+export declare function hashType(s: string): string;
+export declare function specializationKey(argTypes: Type[]): string;
+/** Mangled C typedef name for a handle's capture shape. All no-capture
+ *  handles share `mtoc2_handle_empty_t` regardless of target identity
+ *  (the function dispatch is static — the struct is just a carrier).
+ *  Handles with captures get a per-shape `mtoc2_handle__<8hex>` typedef
+ *  whose hash covers the `(name, cFieldTypeStr)` tuple of each capture
+ *  in order. Matches the struct/class precedent: the typedef hash sees
+ *  only the C-level type of each capture, so two handle types that
+ *  differ only in lattice precision (sign, exact, tensor shape) share
+ *  one typedef and one set of owned-helpers. */
+export declare function handleTypedefName(t: HandleType): string;
+/** C-level type string for a struct/class field or function-handle
+ *  capture. This is the load-bearing identity for typedef hashing:
+ *  the typedef hash depends only on `cFieldTypeStr` per field, so
+ *  two structs whose internal field types differ only in lattice
+ *  precision (sign, exact, tensor shape) collapse to the SAME C
+ *  typedef. The internal `StructType.fields[*].ty` is free to keep
+ *  full precision — that precision drives function specialization
+ *  keys and builtin transfer functions but does NOT shard the C
+ *  typedef.
+ *
+ *  - Scalar real numeric (any sign/exact)   → "double"
+ *  - Multi-element tensor (any shape/exact) → "mtoc2_tensor_t"
+ *  - Handle                                  → handleTypedefName(t)
+ *  - Struct (recurse on fields)              → structTypedefName(t)
+ *  - Class (recurse on properties)           → classTypedefName(t)
+ *
+ *  String / Void / Unknown are not valid struct/class field types
+ *  in v1 — the lowerer rejects them at construction sites. */
+export declare function cFieldTypeStr(t: Type): string;
+/** Mangled C typedef name for a struct's shape. Keyed only on the
+ *  C-level type of each field (`cFieldTypeStr`), so two struct
+ *  values whose fields' internal types differ only in lattice
+ *  precision share one typedef. The internal `StructType.fields[*].ty`
+ *  is still carried at full precision for spec keying + transfer-fn
+ *  use — but it's separate from the typedef identity. */
+export declare function structTypedefName(t: StructType): string;
+/** Replace every non-C-identifier character (`[^A-Za-z0-9_]`) with `_`.
+ *  Used to make `<name>__<hex>` mangled names always valid C identifiers
+ *  when the source carries class/path-like characters (e.g. `pkg.foo`,
+ *  `MyClass.method`). v1 class names are typically already C-safe, so
+ *  this is a passthrough for those. */
+export declare function sanitizeCIdent(s: string): string;
+/** Mangled C typedef name for a class instance. Same C-level
+ *  contract as `structTypedefName` — the hash sees only the C-level
+ *  type of each property — but salted with `className` so two
+ *  distinct classes with the same C-level property shape still pick
+ *  distinct typedefs. */
+export declare function classTypedefName(t: ClassType): string;
+/** Mangled C typedef name for a cell shape. The hash sees the cell's
+ *  mode, dim shape (with `?` for non-exact axes), and either the
+ *  list of per-slot `cFieldTypeStr` values (tuple) or the elem
+ *  `cFieldTypeStr` (uniform). Two cell types whose internal types
+ *  differ only in lattice precision (sign, exact, tensor shape)
+ *  share one typedef. */
+export declare function cellTypedefName(t: CellType): string;
+/** Class-method specialization-name source. Becomes the input to
+ *  `mangleClassMethodName` along with arg-type canonicalization. */
+export declare function classMethodSpecSource(className: string, methodName: string): string;
+export type { Span };

package/dist-lib/numbl-core/jit/lowering/walk.d.ts

@@ -0,0 +1,17 @@
+/**
+ * IR walking helpers — read-only traversal of expression trees and
+ * the top-level expressions inside a statement. Used by the liveness
+ * analyzer (and any future IR-walking pass) to enumerate sub-
+ * expressions without each call site re-discriminating on `IRExpr`
+ * kinds.
+ */
+import type { IRExpr, IRStmt } from "./ir.js";
+/** Visit every sub-expression of `e`, including `e` itself. Walks
+ *  pre-order: the outer node is visited first, then children. Pure
+ *  read-only — `visit` should not mutate the IR. */
+export declare function forEachSubExpr(e: IRExpr, visit: (sub: IRExpr) => void): void;
+/** Visit every top-level expression in `s` (the expressions that
+ *  live directly under the statement node — NOT recursing into
+ *  nested control-flow bodies). The visitor can then call
+ *  `forEachSubExpr` to walk into each. */
+export declare function forEachTopLevelExpr(s: IRStmt, visit: (e: IRExpr) => void): void;