numbl 0.3.0 → 0.4.0

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

@@ -0,0 +1,271 @@
+/**
+ * mtoc2 lowerer. Walks the numbl AST, threads a type env (with exact-
+ * value tracking), and produces typed IR. The same pass:
+ *   - resolves every function-call site through the shared
+ *     `Workspace` (which delegates to numbl's `resolveFunction`),
+ *     so MATLAB precedence rules (local > workspace > builtin, plus
+ *     class-method dispatch on `obj.method(args)` and
+ *     `ClassName.method(args)`) are inherited from numbl wholesale;
+ *   - allocates per-call function specializations (mangled by the
+ *     FNV-1a hash of the canonicalized arg-type tuple, salted by
+ *     the defining file so two files defining a subfunction with
+ *     the same name get distinct C names);
+ *   - merges types across control-flow joins;
+ *   - widens variables assigned inside loop bodies (strips exact)
+ *     before lowering the body, so the one-pass lowering doesn't
+ *     bake the entry-state value into the emitted code.
+ *
+ * Exact-value tracking threads through the type system (builtin
+ * transfer fns still compute exact results), but the only place the
+ * lowerer substitutes a literal for a computation is the `if` /
+ * `elseif` condition — when the cond's type has a `number` exact, the
+ * branch is statically taken or dropped. Arithmetic, comparisons,
+ * builtin calls, and Ident reads all emit runtime IR even when their
+ * exact value is known.
+ *
+ * MVP scope: scalar real double + arithmetic + comparisons + disp +
+ * if/while/for + user functions (0 or 1 outputs; 0-output calls return
+ * `Void` and are only valid as the expression of an `ExprStmt`) +
+ * classes (instance methods, static methods, constructors), with
+ * resolution against sibling `.m` files in the workspace via numbl's
+ * vendored resolver. Anything outside that throws
+ * `UnsupportedConstruct` with a span.
+ */
+import type { AbstractSyntaxTree, Expr, Stmt, Span } from "../parser/index.js";
+import { type Type, type NumericType } from "./types.js";
+import type { ClassRegistration } from "./classDefs.js";
+import type { Workspace } from "../workspace/workspace.js";
+import type { CallSite } from "../numbl/index.js";
+/** Hook for the `%!numbl:printtype` directive's compile-time output.
+ *  Defaults to `console.error` (so emitted lines go to stderr and
+ *  don't mix with the cross-runner's stdout comparison). Tests
+ *  replace this with a capturing function. */
+export declare let printTypeSink: (line: string) => void;
+export declare function setPrintTypeSink(sink: (line: string) => void): void;
+export declare function resetPrintTypeSink(): void;
+import { type Assign, type IRExpr, type IRStmt, type IRFunc, type IRProgram } from "./ir.js";
+export interface EnvEntry {
+    cName: string;
+    ty: Type;
+    /** True when the variable is assigned on only SOME arms of an
+     *  enclosing `if` (not all), so a read may hit a never-assigned value.
+     *  MATLAB raises "Undefined ..." at runtime on the unassigned path; the
+     *  JIT predeclares the local with a default and would silently read it,
+     *  so a read of a flagged var (or returning it as an output) declines
+     *  to the interpreter, which performs the runtime definite-assignment
+     *  check. */
+    maybeUnassigned?: boolean;
+}
+export declare class Lowerer {
+    workspace: Workspace;
+    env: Map<string, EnvEntry>;
+    specializations: Map<string, IRFunc>;
+    /** Stack of contexts for resolving the `end` keyword inside an
+     *  index slot. Pushed by the index-lowering helpers (lowerIndexLoad
+     *  / lowerIndexStore / lowerIndexSlice / lowerIndexSliceStore)
+     *  around each slot they lower; consumed by the `EndKeyword` arm of
+     *  `lowerExpr`. `axis === "linear"` flags the single-slot form
+     *  whose `end` resolves to `numel(base)`. Outside an index slot the
+     *  stack is empty and `end` raises `UnsupportedConstruct`. */
+    endStack: Array<{
+        baseCName: string;
+        baseTy: NumericType;
+        axis: number | "linear";
+    }>;
+    /** Monotonic counter for synthesizing `_mtoc2_t1`, `_mtoc2_t2`, ...
+     *  hoist-temp names. Reset per function specialization. */
+    tempCounter: number;
+    /** Monotonic counter for the synthetic suffix used when an
+     *  incompatible reassignment is split into a fresh binding
+     *  (`_mtoc2_<cName>__v<N>`). See `recordAssignment`. Per-Lowerer, so
+     *  each function specialization / script scope numbers independently. */
+    splitCounter: number;
+    /** Nesting depth inside `if` / `while` / `for` bodies. Bumped by
+     *  `withControlDepth` around each body lowering. An incompatible
+     *  reassignment can only be *split* at depth 0 (straight-line scope);
+     *  inside a branch or loop the env merge can't reconcile two storage
+     *  categories under one name, so it throws instead. */
+    controlDepth: number;
+    /** Expression-level hoist statements queued by sub-lowerings that
+     *  can't pass a `hoists` array up the IR-expression return chain.
+     *  Used today by member-rooted indexing (`obj.field(args)`) to push a
+     *  fresh `Assign(temp = MemberLoad)` so the downstream `IndexLoad` /
+     *  `IndexSlice` has a real `Var` to anchor `end`-keyword resolution
+     *  on. `lowerStmt` drains this list around every statement boundary
+     *  and prepends the hoists to whatever the inner lowering emitted. */
+    pendingExprHoists: IRStmt[];
+    /** Monotonic counter for synthesizing anonymous-function names
+     *  (`anon_0`, `anon_1`, ...). Shared across the whole program so two
+     *  textually distinct `@(...)` expressions get distinct identities. */
+    anonCounter: number;
+    /** Source file the lowerer is currently inside. Defaults to the
+     *  workspace's main file at construction; pushed/popped by
+     *  `specializeUserFunction` so a call from inside `helper.m`'s
+     *  subfunction reports the right file in its `CallSite`. */
+    currentFile: string;
+    /** Per-specialization `nargin` / `nargout` values. Pushed by
+     *  `specializeUserFunction` before lowering a function body; popped
+     *  after. Read by the matching identifier arms of `lowerIdent`. Empty
+     *  at top level — MATLAB rejects `nargin` / `nargout` outside a
+     *  function body, which we mirror by leaving the reference
+     *  unresolved (which falls through to the "undefined" error). */
+    callFrameStack: {
+        nargin: number;
+        nargout: number;
+    }[];
+    /** Spec keys whose still-empty placeholder was consumed via a cache
+     *  hit while lowering some other (or the same) spec. Tracked so
+     *  `specializeUserFunction` knows when a recursive self-call used a
+     *  stale `outputTypes` seed and a second pass is needed to refine
+     *  the recursive-call IR's `ty`. The set is populated by
+     *  `specializeUserFunction`'s cache-hit branch and consumed by the
+     *  same function after body lowering. */
+    recursiveSpecsConsumed: Set<string>;
+    /** Number of distinct specializations created so far per
+     *  `<sourceName>|<definingFile>`. Read by
+     *  `specializeUserFunction`'s cache-miss branch; when the count for
+     *  any one source-level function crosses `MAX_SPECS_PER_FUNCTION`,
+     *  translation aborts with a clear error rather than letting the
+     *  spec map (and the emitted C / JS) grow without bound. Exact-
+     *  value tracking shards the cache by arg value, so a tight call
+     *  with hundreds of distinct literal args (or value-keyed loop
+     *  bodies) is the typical trigger. */
+    specCountPerSource: Map<string, number>;
+    constructor(workspace: Workspace);
+    /** Built `CallSite` for the vendored numbl resolver. New
+     *  resolver-relevant fields added later (`className`, `methodName`,
+     *  ...) only need to be threaded here. */
+    callSite(): CallSite;
+    /** Public env lookup used by the index-lowering helpers. Returns
+     *  the env entry (cName + ty) if a binding exists in the current
+     *  scope, or undefined otherwise. */
+    envLookup(name: string): EnvEntry | undefined;
+    /** Run `fn` with `controlDepth` incremented; restored on exit. Used by
+     *  `lowerIf` / `lowerWhile` / `lowerFor` to mark "we're inside a
+     *  branch or loop body" so an incompatible reassignment throws rather
+     *  than splitting (see `recordAssignment`). */
+    withControlDepth<T>(fn: () => T): T;
+    /** Look up a registered class (workspace or local) by name.
+     *  Re-throws the saved `UnsupportedConstruct` if numbl knew the
+     *  class but mtoc2's `registerClassDef` rejected it in the JIT
+     *  bridge's `fromExistingContext` mode — surfacing the error at
+     *  the first actual use rather than at workspace finalize. */
+    classReg(name: string): ClassRegistration | undefined;
+    lowerProgram(ast: AbstractSyntaxTree): IRProgram;
+    lowerStmts(stmts: Stmt[]): IRStmt[];
+    private lowerStmt;
+    private lowerStmtInner;
+    /** Numbl directives (`%!numbl:<name> <args>`). Numbl interprets a
+     *  small set (e.g. `assert_jit`) and ignores the rest. Mtoc2 reuses
+     *  the same parsed-directive AST node to host translator-side hints
+     *  that numbl silently passes over:
+     *
+     *  - `%!numbl:opaque <var> [<var>...]` — strip `exact` from each
+     *    named variable in the current env. Used in test scripts to
+     *    force the runtime codegen path on values mtoc2 would otherwise
+     *    fold at compile time.
+     *  - `%!numbl:showtype <var> [<var>...]` — snapshot each variable's
+     *    type and emit a `/_ type ... _/` comment in the generated C
+     *    at this position. Debug aid; no runtime effect.
+     *  - `%!numbl:printtype <var> [<var>...]` — same snapshot, but
+     *    written to stderr (via `printTypeSink`) at compile time. Fires
+     *    once per function specialization. No IR node, no codegen
+     *    interaction.
+     *
+     *  Numbl ignores all three directives, so cross-runner output is
+     *  unaffected. */
+    private lowerDirective;
+    /** Look up each name in `args` in the current env, snapshotting its
+     *  `cName` and current `Type`. Throws `UnsupportedConstruct` with
+     *  the directive's span on the first unknown name. Used by the
+     *  `showtype` and `printtype` directive branches. */
+    private snapshotTypeEntries;
+    private lowerExprStmt;
+    /** Reject Void in a value-consuming context with a clear span. The
+     *  Void type tags a call to a zero-output user function; it has no
+     *  representation as a value and is only valid as the direct
+     *  expression of an `ExprStmt`. */
+    requireValueType(e: IRExpr, what: string): void;
+    /** Recursively rewrite sub-expressions of `e`, hoisting any owned-
+     *  producing non-Var sub-expression to a fresh temp Assign. The
+     *  top-level `e` itself is NOT hoisted by this function — the caller
+     *  decides what context `e` sits in (Assign RHS at an owned consume
+     *  site can keep an owned producer; everywhere else requires
+     *  `anfRequireScalarOrVar`). */
+    private anfChildren;
+    /** Walk `e` and ensure the returned expression is either non-owned or
+     *  a Var. Recursively ANFs children; if `e` itself is owned-producing
+     *  (multi-element tensor / struct / class / handle / char / string,
+     *  in non-Var form), hoist it to a fresh temp. The ANF invariant is
+     *  that owned-producing expressions appear only as direct Assign RHSs
+     *  at owned consume sites; every other position holds a Var read. */
+    anfRequireScalarOrVar(e: IRExpr, hoists: IRStmt[]): IRExpr;
+    private hoistToTemp;
+    freshTempName(): string;
+    private lowerAssign;
+    /** `s.f = rhs` or chained `s.inner.f = rhs`. Lowers to a single
+     *  `MemberStore` IR node with the root `Var` as `base` and the
+     *  field chain in `fieldPath`. v1 requires the root variable to be
+     *  already in env (no implicit struct introduction — use
+     *  `s = struct('f', v, ...)` or a class constructor). Every step
+     *  of the chain must already exist on the corresponding nested
+     *  struct/class type.
+     *
+     *  Type discipline: the rhs and the field must occupy the same
+     *  C-level slot — checked by `storageEquivalent`, which calls
+     *  `cFieldTypeStr` on both. Scalar↔tensor, different elem, or
+     *  different struct/class typedef name → rejected. Otherwise the
+     *  write is accepted and env is updated so subsequent reads of
+     *  the field report the rhs's full internal type (the C typedef
+     *  is unaffected — the typedef hash sees only the C-level type
+     *  via `cFieldTypeStr`, not the internal lattice precision). */
+    lowerAssignLValue(s: Extract<Stmt, {
+        type: "AssignLValue";
+    }>): IRStmt | IRStmt[];
+    recordAssignment(name: string, expr: IRExpr, span: Span): Assign;
+    private lowerIf;
+    private lowerElseChain;
+    private lowerWhile;
+    private lowerFor;
+    lowerExpr(e: Expr): IRExpr;
+    /** `end` keyword inside an index slot — resolves through the top of
+     *  `endStack`. Outside an index slot it raises with a span. When the
+     *  axis size is statically known, emit a `NumLit`; otherwise emit
+     *  an `EndRef` IR node and let codegen render the runtime axis-size
+     *  read. */
+    private lowerEndKeyword;
+    /** `a : b` or `a : s : b` used as a value (outside an index slot
+     *  and outside a for-loop iterable). Emits a `MakeRange` IR node
+     *  whose result is a freshly-allocated row vector. */
+    private lowerRangeAsValue;
+    /** `s.f` or chained `s.inner.f`. Lowers each nesting level into a
+     *  fresh `MemberLoad` whose `base` is the inner load. The leaf
+     *  type is the field's static type on the immediate container.
+     *
+     *  Dependent-property routing: when `base` is a class instance and
+     *  the class declares a `get.<name>` accessor, the read is replaced
+     *  by a single-output method call. The result is an owned `Call`
+     *  IRExpr; ANF in the surrounding context hoists it like any other
+     *  owned producer. */
+    private lowerMember;
+    private lowerIdent;
+    private lowerBinary;
+    private lowerUnary;
+    private requireScalarReal;
+    /** Like `requireScalarReal` but also accepts scalar complex —
+     *  used by `if` / `while` / `elseif` conds, where MATLAB's `toBool`
+     *  rule (`creal(z) != 0 || cimag(z) != 0`) gives the boolean. */
+    private requireScalarCondType;
+    private mergeBranchEnvs;
+}
+/** Map a user-source variable name to a safe C / JS identifier.
+ *  Reserved words get a `v_` prefix; other names pass through unchanged
+ *  so emitted code remains readable for the common case. The numbl
+ *  parser already rejects identifiers starting with `_`, so a user
+ *  `for` only collides with the keyword (not with `v_for` from any
+ *  other source). */
+export declare function cIdentForUserName(name: string): string;
+export { tryExtractDottedName } from "../parser/astUtils.js";
+/** Strip the surrounding `'` or `"` quotes the numbl parser stores as
+ *  part of a `Char`/`String` literal's lexeme. */
+export declare function stripQuotes(s: string): string;

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

@@ -0,0 +1,41 @@
+/**
+ * Brace-indexed cell read lowering: `c{i}`, `c{i, j}`.
+ *
+ * Routed from `lowerExpr` when the AST node is `IndexCell` AND the
+ * base resolves to an in-scope cell variable. The base must be a
+ * bare `Ident` for now — member-rooted `obj.field{i}` is rejected
+ * pending the broader member-rooted-index work.
+ *
+ * Result type depends on the cell's mode:
+ *   - Tuple mode + every index a `NumLit` matching an in-range
+ *     slot → the specific slot's `Type`.
+ *   - Tuple mode + any non-exact index → the unified slot type
+ *     (rejected with `UnsupportedConstruct` if slot types diverge).
+ *   - Uniform mode → the cell's `elem` type.
+ *
+ *  Per-axis (`c{i, j}`) reads are accepted only for tuple cells
+ *  whose shape is exact 2-D; uniform cells route through the same
+ *  column-major linear offset at runtime.
+ */
+import type { Expr, LValue, Span } from "../parser/index.js";
+import type { IRExpr, IRStmt } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerCellIndexLoad(this: Lowerer, e: Extract<Expr, {
+    type: "IndexCell";
+}>): IRExpr;
+/** Brace-write lowering: `c{i} = rhs`, `c{i, j} = rhs`. The base
+ *  must be a bare cell-typed variable. After the store, the env's
+ *  recorded type for `c` is refreshed to reflect the new slot type:
+ *
+ *  - Tuple mode + static index → update the slot's `Type` to the
+ *    rhs's type.
+ *  - Tuple mode + non-static index → require every slot type to
+ *    unify with the rhs type; demote the env entry to a uniform
+ *    cell with the unified elem.
+ *  - Uniform mode → rhs must unify with the cell's `elem`.
+ *
+ *  If neither path applies, raise `UnsupportedConstruct` (no LUB /
+ *  heterogeneous fallback per the design — see docs/cells_plan.md). */
+export declare function lowerCellIndexStore(this: Lowerer, lv: Extract<LValue, {
+    type: "IndexCell";
+}>, exprAst: Expr, span: Span): IRStmt | IRStmt[];

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

@@ -0,0 +1,19 @@
+/**
+ * Cell-literal lowering: `{a, b, c}`, `{1; 2; 3}`, `{1, 'hi'; [1 2], "x"}`.
+ *
+ * Reached from `lowerExpr` whenever the AST node is a `Cell`. The
+ * literal always produces a tuple-mode `CellType` with per-slot types
+ * (matching the lowered slot expressions). Empty `{}` produces a
+ * 0×0 tuple cell with `elements: []`.
+ *
+ * Slot expressions accept any value-typed expression — scalars,
+ * tensors, structs, classes, handles, strings, chars. The lowerer
+ * relies on the ANF pass to hoist owned-producing slot values to
+ * fresh temps before the `CellLit` becomes an Assign RHS.
+ */
+import type { Expr } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerCellLit(this: Lowerer, e: Extract<Expr, {
+    type: "Cell";
+}>): IRExpr;

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

@@ -0,0 +1,55 @@
+/**
+ * Class-constructor lowering.
+ *
+ * Three responsibilities:
+ *
+ *   - `lowerClassConstructorCall` — produces the `Call` IR node that
+ *     invokes the user-declared constructor, after settling the
+ *     class's `ClassType` and synthesizing the default-valued
+ *     receiver that the constructor body sees on entry.
+ *
+ *   - `resolveClassType` — for classes whose property types weren't
+ *     fully inferred at registration (because at least one property
+ *     declares no default), pre-scan the constructor body for the
+ *     first top-level `<receiver>.<prop> = <rhs>` write per pending
+ *     property and lower its RHS in a temp env to derive the
+ *     property's type. The first call wins; subsequent calls reuse
+ *     `reg.ty` and validate via the normal `MemberStore` storage-
+ *     equivalence check.
+ *
+ *   - `makeInitialClassReceiver` — synthesize a `StructLit` whose
+ *     ty is the just-resolved `ClassType` and whose field values are
+ *     either the registered defaults or a zero/empty placeholder for
+ *     pending properties. The constructor body's first write
+ *     overwrites the placeholder.
+ */
+import type { Expr, Span } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import { type ClassType, type Type } from "./types.js";
+import type { ClassRegistration } from "./classDefs.js";
+import type { Lowerer } from "./lower.js";
+/** Lower `ClassName(args)` to the `Call` IR node that invokes the
+ *  user-declared constructor. The constructor's first statement gets
+ *  a synthetic `obj = <default-receiver>` prepended (via
+ *  `specializeUserFunction`'s `preSeedOutput`) so the body's reads
+ *  and writes against the receiver work against an initialized
+ *  slot. */
+export declare function lowerClassConstructorCall(this: Lowerer, reg: ClassRegistration, args: Expr[], span: Span): IRExpr;
+/** Settle the class's `ClassType`. For a class with every property
+ *  declaring a default, `reg.ty` is already filled in at
+ *  registration and we just return it. For a class with pending
+ *  properties, we pre-scan the constructor body for direct
+ *  `obj.<prop> = <rhs>` writes (where `obj` is the constructor's
+ *  output receiver) and lower each first-write RHS in a temp env
+ *  bound to the call's `argTypes`. The first call wins — subsequent
+ *  specs validate against the cached type via the normal
+ *  `MemberStore` storage-equivalence check. */
+export declare function resolveClassType(this: Lowerer, reg: ClassRegistration, argTypes: Type[], span: Span): ClassType;
+/** Synthesize a `StructLit` whose ty is `classTy` and whose field
+ *  values are the property defaults from `reg.defaults` — for any
+ *  property without a default, synthesize a zero-value matching the
+ *  inferred C-level type (the constructor body's first write
+ *  overwrites it anyway; the zero is just a typed placeholder so
+ *  the C designated initializer is well-formed and any
+ *  read-before-write reads as 0 / empty). */
+export declare function makeInitialClassReceiver(this: Lowerer, reg: ClassRegistration, classTy: ClassType, span: Span): IRExpr;

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

@@ -0,0 +1,34 @@
+/**
+ * Bare-name function-call lowering: `name(args)`.
+ *
+ * Resolution priority — checked in this order:
+ *   0. The literal name `struct` (no shadowing local) → `StructLit`.
+ *   1. The literal name `bsxfun` (no shadowing local) → rewrite to
+ *      `fn(A, B)` when the first arg is `@<knownElementwiseBinary>`.
+ *   2. An in-scope `HandleType` variable → `dispatchHandleCall`.
+ *   3. An in-scope class name with no shadowing local → class
+ *      constructor.
+ *   4. An in-scope variable: multi-element numeric routes through
+ *      the index helpers; other types raise UnsupportedConstruct.
+ *   5. Zero-arity builtin paren-form (`pi()`, `Inf()`).
+ *   6. Numbl resolver verdict — builtin / user-function / class
+ *      method.
+ *   7. Fallback to mtoc2's own builtin registry for plot-drawing
+ *      builtins numbl wires through runtime dispatch.
+ */
+import type { Expr } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerFuncCall(this: Lowerer, e: Extract<Expr, {
+    type: "FuncCall";
+}>): IRExpr;
+/** Shared AST rewrite used by both `lowerFevalCall` (single-output
+ *  expression context) and the multi-assign path (`lowerMultiAssign`
+ *  calls this to rewrite the RHS before its own dispatch). Returns a
+ *  fresh `FuncCall` node naming the resolved target with `args[0]`
+ *  consumed. */
+export declare function rewriteFevalToDirectCall(e: Extract<Expr, {
+    type: "FuncCall";
+}>): Extract<Expr, {
+    type: "FuncCall";
+}>;

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

@@ -0,0 +1,57 @@
+/**
+ * Function-handle lowering:
+ *   - `@name`           → `lowerFuncHandle` (HandleLit with no captures)
+ *   - `@(p1,...) body`  → `lowerAnonFunc`   (HandleLit with captures
+ *                                            of the surrounding scope)
+ *   - `h(args)`          → `dispatchHandleCall` (specialize + Call IR)
+ *
+ * Captures are deep-copied into the handle struct at the `@(...)`
+ * site (MATLAB by-value snapshot). Owned-typed captures (tensor,
+ * struct, class instance, another handle) ship per-shape
+ * `_empty/_copy/_assign/_free` helpers so they participate in the
+ * standard scope-exit-free / early-free lifecycle.
+ */
+import type { Expr, LValue, Span } from "../parser/index.js";
+import type { IRExpr, IRStmt } from "./ir.js";
+import type { EnvEntry, Lowerer } from "./lower.js";
+/** `@name` — a named handle to a top-level user function. Builds the
+ *  handle type, captures empty, and returns a HandleLit. Builtin
+ *  targets (`@disp`, `@sin`) are rejected — mtoc2 v1 doesn't support
+ *  them. Class methods (`@SomeClass.method`) aren't reachable via
+ *  this AST (the parser emits a different shape for those). The
+ *  workspace resolver finds local + cross-file function targets. */
+export declare function lowerFuncHandle(this: Lowerer, e: Extract<Expr, {
+    type: "FuncHandle";
+}>): IRExpr;
+/** `@(p1, ..., pN) <body>` — an anonymous function. Detects every
+ *  free Ident in the body that's bound in the enclosing scope (and
+ *  not in the param list) as a capture, then synthesizes a top-level
+ *  `function out = anon_<N>(p1, ..., pN, c1, ..., cM)` whose body
+ *  assigns the source body expression to the synthesized output. The
+ *  synthesized AST is parked on `handleTy.ast` so every call site
+ *  routes through the same specialization cache used for
+ *  user-declared functions.
+ *
+ *  Captures may be scalar real numeric, tensor, struct, class
+ *  instance, or another handle — the handle's C struct ships with
+ *  per-shape `_empty/_copy/_assign/_free` helpers (just like
+ *  structs/classes), so owned-typed fields participate in the
+ *  standard scope-exit-free / early-free lifecycle. String / Void /
+ *  Unknown captures are rejected with `UnsupportedConstruct`. */
+export declare function lowerAnonFunc(this: Lowerer, e: Extract<Expr, {
+    type: "AnonFunc";
+}>): IRExpr;
+/** Dispatch `h(args)` where `h` is an in-scope handle variable.
+ *  Reads the handle's `ast` off its type, lowers the user-supplied
+ *  args, appends per-capture `HandleCaptureLoad` reads, specializes
+ *  the underlying function on the combined arg-type tuple, and emits
+ *  a direct call to the mangled name. */
+export declare function dispatchHandleCall(this: Lowerer, handleName: string, handleEntry: EnvEntry, argExprs: Expr[], span: Span): IRExpr;
+/** `[a, b, ...] = h(args)` where `h` is an in-scope handle variable.
+ *  Mirrors `dispatchHandleCall`'s user-arg + capture-load wiring, then
+ *  specializes the target at the caller's nargout. Emits a Call (when
+ *  the spec truncates to 1 output) or a MultiAssignCall (N>=2 outputs);
+ *  drop-all bare-statement use (`h(args);`) passes 0 lvalues and emits
+ *  an ExprStmt. Returns the IR statement(s) to splice into the parent
+ *  block. */
+export declare function dispatchHandleMultiAssign(this: Lowerer, handleName: string, handleEntry: EnvEntry, argExprs: Expr[], lvalues: ReadonlyArray<LValue>, span: Span): IRStmt | IRStmt[];

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

@@ -0,0 +1,16 @@
+/**
+ * Scalar index-read lowering: `v(i)` / `M(i, j)` / `T(i, j, k)` /
+ * `v(end)` / `M(end, end)` / etc.
+ *
+ * Reached from `lowerFuncCall` whenever a `FuncCall` name resolves to
+ * an in-scope multi-element numeric variable AND none of the args are
+ * a range / bare colon (that case routes to `lowerIndexSlice`). Each
+ * index slot must lower to a scalar real expression; an `end` token
+ * inside a slot resolves through the Lowerer's `endStack` to the
+ * appropriate axis size.
+ */
+import type { Expr, Span } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+/** Lower an index-read of an in-scope variable. */
+export declare function lowerIndexLoad(this: Lowerer, name: string, argExprs: ReadonlyArray<Expr>, span: Span): IRExpr;

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

@@ -0,0 +1,29 @@
+/**
+ * Range / colon / scalar-mix indexed-read lowering: `v(:)`, `v(a:b)`,
+ * `M(:, j)`, `T(:, :, i)`, … .
+ *
+ * Reached from `lowerFuncCall` whenever a `FuncCall` name resolves to
+ * an in-scope multi-element numeric variable AND at least one arg is a
+ * `Range` or bare `Colon`. Two acceptable arities: 1 slot (linear) or
+ * `base.ty.dims.length` slots (one per axis). Result-shape rules
+ * mirror numbl and mtoc:
+ *
+ *   single-slot Colon                   → column vector, length numel(base)
+ *   single-slot Range, row-vec base     → row vector, count(range)
+ *   single-slot Range, col-vec base     → col vector, count(range)
+ *   single-slot Range, matrix / N-D base → row vector, count(range)
+ *   multi-slot Colon at axis k          → base.dims[k]
+ *   multi-slot Range at axis k          → exact count when statically
+ *                                          derivable, else unknown
+ *   multi-slot Scalar at axis k         → exact 1
+ */
+import type { Expr, Span } from "../parser/index.js";
+import type { IRExpr, IndexSliceArg } from "./ir.js";
+import { type NumericType } from "./types.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerIndexSlice(this: Lowerer, name: string, argExprs: ReadonlyArray<Expr>, span: Span): IRExpr;
+/** Lower a single AST index slot into an `IndexSliceArg`. The
+ *  `endStack` is pushed around each sub-expression so an embedded
+ *  `end` token resolves against the right axis. Exported so the
+ *  store-side helper reuses the same logic. */
+export declare function lowerSliceArg(this: Lowerer, baseCName: string, baseTy: NumericType, axis: number | "linear", arg: Expr): IndexSliceArg;

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

@@ -0,0 +1,19 @@
+/**
+ * Range / colon / scalar-mix indexed-write lowering: `v(:) = w`,
+ * `v(a:b) = w`, `M(:, j) = w`, `T(:, :, i) = w`, … .
+ *
+ * Companion to `lowerIndexSlice` for slice writes. RHS shape:
+ *   - scalar real numeric → broadcast into every slot.
+ *   - named multi-element tensor (`Var`) → per-slot copy.
+ *
+ * Other RHS forms (a fresh `TensorBuild`, an `IndexSlice`, a tensor
+ * Binary, etc.) are rejected with a clear message — the user must
+ * assign the expression to a name first so the temporary lifetime is
+ * explicit.
+ */
+import type { Expr, LValue, Span } from "../parser/index.js";
+import type { IRStmt } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerIndexSliceStore(this: Lowerer, lvalue: Extract<LValue, {
+    type: "Index";
+}>, exprAst: Expr, span: Span): IRStmt | IRStmt[];

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

@@ -0,0 +1,14 @@
+/**
+ * Scalar indexed-write lowering: `v(i) = x`, `M(i, j) = x`,
+ * `T(i, j, k) = x`, `v(end) = x`.
+ *
+ * Reached from `lowerAssignLValue` whenever the lvalue is an `Index`
+ * with a simple `Ident` base AND none of the index slots are a range
+ * / colon (that case routes to `lowerIndexSliceStore`).
+ */
+import type { Expr, LValue, Span } from "../parser/index.js";
+import type { IRStmt } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerIndexStore(this: Lowerer, lvalue: Extract<LValue, {
+    type: "Index";
+}>, exprAst: Expr, span: Span): IRStmt | IRStmt[];

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

@@ -0,0 +1,45 @@
+/**
+ * Method-call lowering — every `<base>.<name>(args)` AST node:
+ *
+ *   - **Package call**: `pkg.foo(args)` and `pkg.sub.foo(args)` —
+ *     leftmost segment is not an in-scope variable. Routes to the
+ *     userFunction / classConstructor verdict from the resolver.
+ *   - **Static method call**: `ClassName.staticMethod(args)` — base
+ *     resolves to a class name. Receiver is not present in the arg
+ *     tuple.
+ *   - **Instance method call**: `obj.method(args)` — base evaluates
+ *     to a class instance. The receiver becomes the first arg when
+ *     numbl's resolver decides this is an instance dispatch
+ *     (`stripInstance === false`).
+ *   - **Member-rooted indexing**: `obj.field(args)` where `field` is
+ *     a property (not a method). The field load lands in a fresh
+ *     temp and the args run through the standard `lowerIndexLoad` /
+ *     `lowerIndexSlice` path.
+ */
+import type { Expr, Span } from "../parser/index.js";
+import type { IRExpr } from "./ir.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerMethodCall(this: Lowerer, e: Extract<Expr, {
+    type: "MethodCall";
+}>): IRExpr;
+/** Lowers `obj.depProp(args)` where `depProp` is a `Dependent`
+ *  property: call the getter to produce the value, hoist the result
+ *  to a fresh temp, then run the args through the standard
+ *  `lowerIndexLoad` / `lowerIndexSlice` path on the temp. v1
+ *  rejects the corresponding write form (`obj.depProp(args) = rhs`)
+ *  at `lowerAssignLValue` — splicing through the getter then setter
+ *  is deferred. */
+export declare function lowerDependentPropertyIndex(this: Lowerer, base: IRExpr, reg: import("./classDefs.js").ClassRegistration, propName: string, argExprs: ReadonlyArray<Expr>, span: Span): IRExpr;
+/** Lowers `obj.field(args)` where `field` is a class property (not a
+ *  method): load the field into a fresh temp, then run the args
+ *  through the standard `lowerIndexLoad` / `lowerIndexSlice` path
+ *  using the temp's name. The synthetic `Assign(temp = MemberLoad)`
+ *  is queued on `pendingExprHoists` so `lowerStmt` prepends it to
+ *  the emitted statement. */
+export declare function lowerMemberRootedIndex(this: Lowerer, base: IRExpr, field: string, argExprs: ReadonlyArray<Expr>, span: Span): IRExpr;
+/** `ClassName.staticMethod(args)` — static method called via class
+ *  name. The receiver is not present; arg types feed the resolver
+ *  directly. */
+export declare function lowerStaticMethodCall(this: Lowerer, className: string, e: Extract<Expr, {
+    type: "MethodCall";
+}>, span: Span): IRExpr;

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

@@ -0,0 +1,36 @@
+/**
+ * Multi-assign statement lowering: `[a, b] = foo(x);` (with mix of
+ * named lvalues, `~` discards, and trailing-omitted slots) and the
+ * drop-all bare-statement variant `foo(x);` where `foo` has N≥2
+ * outputs. Handles both user-function and multi-output builtin (e.g.
+ * `[v, i] = sort(...)`) targets.
+ *
+ * 1-output declarations reached through this path (because the call
+ * site has lvalues.length === 1) take the classic single-output ABI
+ * — return-by-value via a `Call` IR node and an `Assign` / `ExprStmt`
+ * wrapper. Only N≥2 outputs produce a `MultiAssignCall` IR node
+ * (which carries the sret out-pointer ABI).
+ */
+import type { Span, Stmt, LValue } from "../parser/index.js";
+import type { IRStmt } from "./ir.js";
+import { type Type } from "./types.js";
+import type { Lowerer } from "./lower.js";
+export declare function lowerMultiAssign(this: Lowerer, s: Extract<Stmt, {
+    type: "MultiAssign";
+}>): IRStmt | IRStmt[];
+/** Validate each multi-output slot type, register the lvalue
+ *  bindings in env (or mark them as discarded), and return the
+ *  `MultiAssignCall.outputs` list. Single chokepoint for the
+ *  user-function and builtin multi-output paths.
+ *
+ *  `slotLabel(i)` returns a per-slot description for the error
+ *  message when a slot's type isn't supported — e.g. `output 'a'`
+ *  for declared user-function outputs or `output slot 1` for builtin
+ *  slots that have no source-level name. */
+export declare function buildMultiOutputSlots(this: Lowerer, callName: string, slotTypes: ReadonlyArray<Type>, lvalues: ReadonlyArray<LValue>, slotLabel: (i: number) => string, span: Span): {
+    ty: Type;
+    binding: {
+        name: string;
+        cName: string;
+    } | null;
+}[];