numbl 0.3.0 → 0.4.0

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

@@ -0,0 +1,95 @@
+export function mtoc2_tensor_cos(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_sin(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_tan(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_atan(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_sinh(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_cosh(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_tanh(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_asinh(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_exp(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_log(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_log2(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_log10(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_sqrt(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_abs(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_floor(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_ceil(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_fix(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_round(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_sign(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

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

@@ -0,0 +1,5 @@
+export function mtoc2_uniquetol_real(a: any, tol: any, rowOut: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

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

@@ -0,0 +1,12 @@
+export function mtoc2_var_all(t: any, w: any): any;
+export function mtoc2_var_dim(t: any, dim: any, w: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_std_all(t: any, w: any): any;
+export function mtoc2_std_dim(t: any, dim: any, w: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

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

@@ -0,0 +1,5 @@
+export function mtoc2_tensor_zeros_nd(ndim: any, dims: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

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

@@ -0,0 +1,5 @@
+export function mtoc2_tensor_zeros_square(n: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

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

@@ -0,0 +1,2 @@
+export function mtoc2_strcmp(a: any, b: any): 1 | 0;
+export function mtoc2_strcmpi(a: any, b: any): 1 | 0;

package/dist-lib/numbl-core/jit/codegen/cFormat.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure C-source formatting utilities used by the codegen modules. No
+ * runtime-state threading, no IR dependencies — string in, string out.
+ * Lives separately so the emit-* modules can import them without
+ * cycling through emit.ts.
+ */
+import type { Type } from "../lowering/types.js";
+/** Encode `s` as a C string literal `"..."` whose bytes are the UTF-8
+ *  encoding of `s`. Returns `{ lit, byteLen }` where `byteLen` is the
+ *  encoded byte count (excluding the trailing NUL). Non-printable bytes
+ *  use `\xHH`; backslash/quote/standard whitespace use the C escapes.
+ *
+ *  Why hex over `\uHHHH`: narrow C string literals don't accept
+ *  universal-character names; we need byte-level escapes to keep the
+ *  emitted code portable. */
+export declare function cStringLiteral(s: string): {
+    lit: string;
+    byteLen: number;
+};
+/** Format a Span as a quoted "<file>:<offset>" string literal for
+ *  passing to a runtime helper. The file path is JSON-escaped (the
+ *  emitter already requires a single C-string-safe form), and the
+ *  offset is the byte offset of the violating expression — matches
+ *  the format used by translate-time `UnsupportedConstruct` errors,
+ *  so the user sees a familiar location for runtime OOB too. */
+export declare function locStringOf(span: {
+    file: string;
+    start: number;
+}): string;
+/** Build the C expression for `numel(<cName>)` as the product of its
+ *  per-axis `.dims[i]` slots. Returns `"0L"` for an empty / non-numeric
+ *  type so the emitted C still parses on degenerate inputs. */
+export declare function dimsProductExpr(cName: string, ty: Type): string;
+/** Compute the column-major linear offset for an N-D access given
+ *  per-axis source terms and a stride source. */
+export declare function formatNdOffset(terms: ReadonlyArray<string>, stride: (axisIndex: number) => string): string;

package/dist-lib/numbl-core/jit/codegen/cHelpers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared C-type and owned-helper renderers used by both `emit.ts` and
+ * `emitNamedTypedef.ts`. Lives in its own module so the two emitters
+ * don't have to import each other (the previous arrangement had
+ * `emitNamedTypedef.ts` duplicating these helpers to avoid a circular
+ * import).
+ */
+import { type Type } from "../lowering/types.js";
+/** C type for any mtoc2 IR-typed value: tensor / string / char →
+ *  per-kind runtime struct; struct / class / handle → per-shape
+ *  generated typedef; everything else (scalar real numeric) → `double`. */
+export declare function cTypeFor(t: Type): string;
+/** Per-owned-kind helper-name family. Tensors / strings / chars use
+ *  the global `mtoc2_*` runtime snippet names; structs, classes, and
+ *  handles use their program-emitted `<typedef>_*` family. */
+export interface OwnedHelpers {
+    empty: string;
+    assign: string;
+    copy: string;
+    free: string;
+    /** When true, `empty`/`assign`/`copy`/`free` are loaded from the
+     *  runtime snippet registry. When false, they're emitted directly
+     *  into the generated C by `emitNamedTypedef` and need no
+     *  `useRuntimeByName` activation. */
+    isRuntime: boolean;
+}
+/** Owned-helper family for any type. Returns `null` for non-owned
+ *  (POD) types — those get plain assignment / no copy / no free. */
+export declare function ownedHelpersFor(t: Type): OwnedHelpers | null;
+/** Asserting form: returns helpers for a type known to be owned, and
+ *  throws if it isn't. Use this at sites where the caller has already
+ *  proven the type is owned (e.g. via `isOwned(t)`) and the null check
+ *  would be a redundant nuisance. */
+export declare function requireOwnedHelpers(t: Type): OwnedHelpers;
+/** C expression that disps one value of type `t`, including the
+ *  trailing newline that matches numbl's `disp` contract. Activates
+ *  any runtime snippets the chosen helper needs via `useRuntime`.
+ *  Returns `null` when no disp helper exists for the type (Class /
+ *  Handle / Void / Unknown — call sites decide whether to skip or
+ *  raise). Single dispatch shared by the `disp` builtin's `emitC`
+ *  and the per-field disp inside struct typedefs, so the two can't
+ *  drift apart when a new value kind becomes a valid struct field. */
+export declare function emitDispCallC(t: Type, valueC: string, useRuntime: (name: string) => void): string | null;
+/** Format a JS number as a C double literal that round-trips. Single
+ *  source of truth — both the per-expression emit path and the fused
+ *  per-element template emitter route through here so NaN / ±Infinity
+ *  format consistently as `NAN` / `INFINITY` / `(-INFINITY)`. */
+export declare function formatDouble(v: number): string;

package/dist-lib/numbl-core/jit/codegen/emit.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Single-file C codegen for mtoc2 IR. Emits:
+ *   1. Standard headers + activated runtime snippets (in dep order).
+ *   2. Forward declarations for user-function specializations.
+ *   3. Function specialization bodies.
+ *   4. `main()` containing top-level statements.
+ *
+ * Scalars compile to bare `double`. Multi-element tensors compile to
+ * `mtoc2_tensor_t` — no refcount, no COW. The codegen invariant
+ * (matching mtoc's): every tensor RHS is freshly owned, every
+ * ownership-transferring use of a Var read wraps in
+ * `mtoc2_tensor_copy(name)`. Pre-declaration of every owned local
+ * via `mtoc2_tensor_empty()` at function top makes the first-vs-
+ * later distinction uniform (the assign helper releases the prior
+ * buffer, which is NULL on first call). Scope-exit emits a
+ * `mtoc2_tensor_free` for every owned local.
+ *
+ * `includeRuntime` (default true): when false, the activated runtime
+ * helpers are omitted from the output (a placeholder comment is shown
+ * instead) so the IDE's "runtime helpers" toggle can show user-level
+ * code in isolation. The emitted C is not compilable in that mode —
+ * it's a viewing aid.
+ */
+import type { IRProgram } from "../lowering/ir.js";
+import { type Type } from "../lowering/types.js";
+import { type RuntimeState } from "./runtime.js";
+export interface EmitOptions {
+    /** Include the activated runtime helper bodies in the output.
+     *  Default true. When false, headers + a placeholder stub replace
+     *  them so the user sees only their generated code. */
+    includeRuntime?: boolean;
+    /** Max-threads OpenMP setting. See `TranslateOptions.threads`. */
+    threads?: number | "auto";
+    /** Workspace context. Threaded through `RuntimeState` so emit-time
+     *  builtin lookups consult `.mtoc2.js` user builtins via
+     *  `getUserBuiltin`. Optional — vitest unit tests that don't drive
+     *  through a workspace can omit it. */
+    workspace?: import("./runtime.js").WorkspaceLike;
+    /** JIT-mode emit. When set, the cName of a single user-function spec
+     *  to expose at module scope (no `static` qualifier so `dlsym` /
+     *  koffi can resolve it after `dlopen`). Disables the `int main()`
+     *  emission — the module becomes a `.so` consumers load and call
+     *  into directly. Requires `prog.topLevelStmts` to be empty and
+     *  `prog.functions` to contain the named spec; every spec
+     *  transitively called by the entry must also be in
+     *  `prog.functions` so internal calls resolve. */
+    exposeSpec?: string;
+}
+export declare function emitProgram(prog: IRProgram, opts?: EmitOptions): string;
+export declare function activateOwnedRuntime(t: Type, state: RuntimeState): void;
+/** Activate the runtime snippets needed for an owned type AND return
+ *  its OwnedHelpers descriptor. Shorthand for the
+ *  `activateOwnedRuntime(t, state); requireOwnedHelpers(t)` pair that
+ *  appears at every owned-codegen site. */
+export declare function activatedOwnedHelpers(t: Type, state: RuntimeState): import("./cHelpers.js").OwnedHelpers;

package/dist-lib/numbl-core/jit/codegen/emitCellTypedef.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-shape cell-array typedef + owned-helper emission. Sibling of
+ * `emitNamedTypedef` (which covers struct / class / handle). Cells
+ * differ enough that they get their own emitter:
+ *
+ *  - **tuple-mode** cells have one C field per slot
+ *    (`slot_0`, `slot_1`, …, `slot_{n-1}`) — direct analogue of a
+ *    struct with positional fields. Helpers walk each slot once.
+ *  - **uniform-mode** cells have a small descriptor (`ndim`, `dims[]`,
+ *    `slots[]`) and a heap-allocated slot buffer. Helpers loop over
+ *    the slot count, calling the elem type's owned helpers on each.
+ *
+ *  Both modes ship the same five-helper family used elsewhere
+ *  (`_empty / _assign / _copy / _free / _disp`).
+ *
+ *  Output format for `disp(c)` matches numbl's `formatCell`
+ *  (`runtime/display.ts:244-251`): single line `{e1, e2, ...}` with
+ *  chars in `'...'`, strings in `"..."`, other values via the
+ *  scalar / tensor / struct disp helper. Empty cell renders as `{}`.
+ */
+import { type CellType } from "../lowering/types.js";
+import { type RuntimeState } from "./runtime.js";
+export declare function emitCellTypedef(t: CellType, state: RuntimeState): string;

package/dist-lib/numbl-core/jit/codegen/emitExpr.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `emitExpr` and the per-IRExpr-kind helpers that don't belong in
+ * their own module. The big switch dispatches on `IRExpr.kind` and
+ * returns the C expression string. Owned-aware sites (Var copy,
+ * StructLit owned fields, …) route through `emitOwnedRhs`, which is
+ * also defined here so the regular-expression and consume-site emit
+ * paths share a single source of truth.
+ */
+import type { IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+/** Owned-typed RHS for an Assign or MemberStore (or a Call arg that
+ *  binds to an owned callee param). Every owned C value produced
+ *  here is freshly-owned; the consumer's `_assign` helper releases
+ *  the prior slot and consumes the rhs.
+ *
+ *  - `Var`               → `<type>_copy(name)` (deep copy)
+ *  - `MemberLoad`        → `<type>_copy(<base>.<field>)` (the load
+ *                          itself is a struct-by-value read; we wrap
+ *                          it in copy so the consumer gets a freshly-
+ *                          owned buffer)
+ *  - `HandleCaptureLoad` → `<type>_copy(<base>.cap_<name>)` (same
+ *                          rationale — the handle's capture slot is
+ *                          read by value and we copy it for the
+ *                          consumer)
+ *  - anything else       → `emitExpr` (TensorBuild / StructLit /
+ *                          HandleLit / Binary / Call etc. already
+ *                          emit fresh-allocating helpers) */
+export declare function emitOwnedRhs(e: IRExpr, state: RuntimeState): string;
+/** Lower a scalar cond expression to a C bool expression. Complex
+ *  scalars use the numbl/MATLAB `creal(z) != 0 || cimag(z) != 0` rule
+ *  via the `mtoc2_cnonzero` helper; real scalars compare against `0.0`. */
+export declare function emitCondToBoolExpr(e: IRExpr, state: RuntimeState): string;
+export declare function emitExpr(e: IRExpr, state: RuntimeState): string;

package/dist-lib/numbl-core/jit/codegen/emitIndex.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Index-related codegen — scalar offsets, slice slot setup, range and
+ * logical-mask setup, slice producer (`IndexSlice`), and slice store
+ * (`IndexSliceStore`). Shared by `emit.ts`'s `emitStmt` / `emitExpr`
+ * arms for IndexLoad / IndexStore / IndexSlice / IndexSliceStore.
+ *
+ * Everything here ultimately emits column-major offset arithmetic
+ * against an `mtoc2_tensor_t`'s `.real` / `.imag` flat buffers, with
+ * bounds checks via the `mtoc2_idx_*` / `mtoc2_check_*` runtime
+ * helpers (per-axis, per-linear-index, or full per-range).
+ */
+import type { IRExpr, IRStmt, IndexSliceArg } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+/** Compute the column-major linear buffer offset for a scalar
+ *  IndexLoad / IndexStore: 1-arg linear, 2-arg row/col, or N-arg N-D.
+ *  Each axis index is wrapped in a runtime bounds-check call
+ *  (`mtoc2_idx_axis` for per-axis; `mtoc2_idx_lin` for 1-arg linear)
+ *  so an OOB access aborts with a numbl-style "Index exceeds array
+ *  bounds" message instead of silently reading/writing past the
+ *  buffer. Mirrors mtoc's `emitNdScalarOffset` — one source of truth
+ *  for the offset formula.
+ *
+ *  `grow` selects the indexed-STORE variant: the `*_grow` bounds
+ *  checks bail (longjmp to the host-entry guard → host re-runs on the
+ *  interpreter) instead of aborting when the index exceeds the extent,
+ *  because a store past the end GROWS the array in MATLAB — which the
+ *  JIT can't model. Reads pass `grow = false` (OOB is a genuine
+ *  error). See `grow_bail.h`. */
+export declare function emitNdScalarOffset(state: RuntimeState, indices: ReadonlyArray<IRExpr>, baseCName: string, grow?: boolean): string;
+/** Emit per-slot setup for a multi-slot slice (read or write): pushes
+ *  `_mtoc2_n_<i>` (per-slot iteration count) and any Range / Scalar
+ *  locals into `lines`. Returns the per-slot source-index expression
+ *  (in terms of `_mtoc2_k_<i>` for Colon/Range, or the precomputed
+ *  `_mtoc2_src_<i>` local for Scalar slots).
+ *
+ *  `cleanups`, when provided, is populated with lines that must run
+ *  after the iter loop (currently used for LogicalMask slots to free
+ *  the precomputed source-index buffer). The caller is expected to
+ *  emit these lines immediately after closing the slot iteration
+ *  loops and before the GCC statement-expression's yield expression. */
+export declare function emitSliceSlotSetup(state: RuntimeState, lines: string[], indent: string, slotsTyped: ReadonlyArray<IndexSliceArg>, baseCName: string, cleanups?: string[]): string[];
+/** Emit an `IndexSlice` as a C statement-expression-style block that
+ *  allocates the result tensor, fills it, and evaluates to the result
+ *  via a comma expression. The result is consumed at an owned consume
+ *  site (`mtoc2_tensor_assign(&v, <here>)`); ANF guarantees IndexSlice
+ *  appears only as the direct RHS of an Assign. */
+export declare function emitIndexSliceProducer(e: Extract<IRExpr, {
+    kind: "IndexSlice";
+}>, state: RuntimeState): string;
+/** Emit an `IndexSliceStore` statement: mutate `base` in place.
+ *  Member-rooted stores target a field slot `<rootCName>.<fieldPath>`
+ *  with the field's NumericType replacing the (struct/class) base
+ *  type for offset / complex-lane decisions. */
+export declare function emitIndexSliceStore(s: Extract<IRStmt, {
+    kind: "IndexSliceStore";
+}>, indent: string, state: RuntimeState): string;

package/dist-lib/numbl-core/jit/codegen/emitJs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Single-file JS codegen for mtoc2 IR. Mirrors `emit.ts` (the C path)
+ * intentionally — same control flow, same variable layout, same call
+ * shape — differing only in language and the I/O primitive (`$write(s)`
+ * vs `printf(...)`).
+ *
+ * Pass-by-value protocol: owned-typed RHSes (Var / MemberLoad /
+ * HandleCaptureLoad) at Assign, user-function Call args, and
+ * MultiAssignCall args route through `emitOwnedRhsJs`, which wraps
+ * the expression in `mtoc2_deep_clone(...)`. JS GC handles lifetime,
+ * but value-semantics still need an explicit copy — otherwise
+ * `b = a; b.f = rhs` would mutate `a`. Owned-producing expressions
+ * (TensorBuild, StructLit, HandleLit, fresh-allocating helpers) are
+ * left alone — they already yield a fresh value.
+ *
+ * Builtin dispatch routes through `builtin.emitJs`. If a needed
+ * builtin has no `emitJs` hook yet, `requireEmitJs` throws a clear
+ * "no emitJs hook" error.
+ *
+ * The emitted module has the shape:
+ *   ```js
+ *   <inlined runtime snippet bodies>
+ *   function <user-fn-spec-1>(...) { ... }
+ *   function <user-fn-spec-2>(...) { ... }
+ *   function run($h) {
+ *     globalThis.$write = $h.write;
+ *     let v1, v2, ...;          // pre-declared locals
+ *     ... top-level stmts ...
+ *   }
+ *   return run;
+ *   ```
+ *
+ * The CLI / engine evals the source via `new Function(source)(...)`
+ * which returns `run`, then invokes `run(ctx.helpers)`.
+ */
+import type { IRProgram } from "../lowering/ir.js";
+import { type WorkspaceLike } from "./runtime.js";
+export interface EmitJsOptions {
+    /** Workspace context. Threaded through `RuntimeState` so emit-time
+     *  builtin lookups consult `.mtoc2.js` user builtins. Optional. */
+    workspace?: WorkspaceLike;
+    /** Include the activated runtime helper bodies inline at the top of
+     *  the emitted module. Default true. When false the placeholder
+     *  comment lands instead — useful for the IDE preview. */
+    includeRuntime?: boolean;
+    /** JIT-mode emit. When set, the cName of a single user-function spec
+     *  to expose: the outer module returns a `($h) => specFn` factory
+     *  instead of the script-style `function run($h)` wrapper. Requires
+     *  `prog.topLevelStmts` to be empty and `prog.functions` to contain
+     *  the named spec (which must be reachable along with any specs it
+     *  transitively calls). Used by the numbl JIT bridge. */
+    exposeSpec?: string;
+}
+export interface EmitJsResult {
+    /** Full module source — runtime snippets, user-function defs, and
+     *  either `function run($h)` + `return run;` (script mode) or
+     *  `return ($h) => specFn;` (when `opts.exposeSpec` is set). Ready
+     *  for `new Function(...)`. */
+    source: string;
+    /** Names of every runtime snippet activated during emit (debug aid;
+     *  also useful to gate dependency wiring in tests). */
+    activatedSnippets: ReadonlyArray<string>;
+}
+export declare function emitJsProgram(prog: IRProgram, opts?: EmitJsOptions): EmitJsResult;

package/dist-lib/numbl-core/jit/codegen/emitNamedTypedef.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Per-shape struct/class typedef + owned-helper emission.
+ *
+ * Structs and class instances live as generated C `typedef struct
+ * <name> { ... } <name>;` definitions, one per distinct canonical
+ * shape. Each typedef ships with the four owned-kind helpers —
+ * `_empty()`, `_assign()`, `_copy()`, `_free()` — so the existing
+ * codegen pipeline (predeclare at function top, scope-exit free,
+ * early-free, ANF) treats struct/class locals uniformly with tensors.
+ *
+ * Structs additionally get a `_disp()` helper used by `disp(s)`; v1
+ * doesn't emit `_disp` for class instances.
+ *
+ * The renderer walks each field once and emits the right helper
+ * pattern for that field:
+ *   - scalar (Numeric / Handle / Unknown): plain C assignment / no
+ *     free / no recursive copy.
+ *   - owned (multi-element Numeric / nested Struct / nested Class):
+ *     route through the field's own owned-kind helper family.
+ *
+ * Tensor fields call `mtoc2_tensor_*` directly; nested struct/class
+ * fields call the corresponding `<inner-typedef>_*` helper, so a
+ * topological order over the typedef-dependency graph guarantees each
+ * helper is defined before the one that uses it.
+ */
+import { type ClassType, type HandleType, type StructType, type Type } from "../lowering/types.js";
+import { type RuntimeState } from "./runtime.js";
+export interface NamedTypedefSpec {
+    /** Typedef name. The C output uses this as both the struct tag and
+     *  the typedef alias. */
+    name: string;
+    /** Field list — canonical order (sorted by name). */
+    fields: ReadonlyArray<{
+        name: string;
+        ty: Type;
+    }>;
+    /** Emit a `_disp(value)` helper (true for structs, false for
+     *  classes in v1). */
+    emitDisp: boolean;
+    /** Source description for the function-leading comment (e.g.
+     *  `struct{x:double,y:double}` or `class Foo`). */
+    pretty: string;
+}
+/** Emit the typedef and its four (or five) owned-kind helpers as
+ *  one block of C source. Activates any runtime snippets the helpers
+ *  call into (e.g. `mtoc2_tensor_copy`). */
+export declare function emitNamedTypedef(spec: NamedTypedefSpec, state: RuntimeState): string;
+/** Helper for emit.ts: build a `NamedTypedefSpec` for a `StructType`. */
+export declare function specForStruct(t: StructType): NamedTypedefSpec;
+/** Helper for emit.ts: build a `NamedTypedefSpec` for a `ClassType`. */
+export declare function specForClass(t: ClassType): NamedTypedefSpec;
+/** Helper for emit.ts: build a `NamedTypedefSpec` for a `HandleType`.
+ *  Captures map to fields named `cap_<captureName>` — matching the
+ *  layout that `HandleCaptureLoad` codegen reads. The no-capture
+ *  shape emits as a placeholder-bearing struct (handled by the empty-
+ *  fields branch in `emitNamedTypedef`). Handles never emit `_disp` —
+ *  `disp(handle)` is rejected at lowering. */
+export declare function specForHandle(t: HandleType): NamedTypedefSpec;

package/dist-lib/numbl-core/jit/codegen/emitStmt.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Function-shape + statement-level codegen — `emitFunction`,
+ * `emitBody`, `emitStmt`, and the locals-collection / param-list
+ * helpers they share. Statement emit is mutually recursive with body
+ * emit (If/While/For wrap nested bodies), so they live together.
+ *
+ * Expression-side emit lives in `emitExpr.ts`; index slice store /
+ * scalar offset and named-typedef helpers are in their own modules.
+ */
+import type { IRExpr, IRFunc, IRStmt } from "../lowering/ir.js";
+import { type Type } from "../lowering/types.js";
+import { type RuntimeState } from "./runtime.js";
+import { type FutureTouchMap } from "./liveness.js";
+/** Default initializer for a freshly-declared non-owned local. Owned
+ *  types (tensors, structs, classes, handles) route through their
+ *  `_empty()` helper instead and never hit this path; everything
+ *  reaching here is scalar real numeric, so `0.0` always fits. */
+export declare function defaultInitFor(): string;
+export declare function fnRetType(fn: IRFunc): string;
+export declare function fnParamList(fn: IRFunc): string;
+/** Walk `stmts` once and split the result into owned vs non-owned
+ *  locals. Every local is pre-declared at function top — owned with
+ *  the per-type `_empty()` helper, scalars with the default init
+ *  (`0.0` / `0`). The non-owned half also picks up For loop vars and
+ *  multi-assign slot bindings so that a later read of a variable
+ *  first written inside an If / While / For body (reachable via
+ *  `mergeBranchEnvs` keeping partial-branch keys) doesn't reference
+ *  an out-of-scope C local. */
+export declare function collectLocals(stmts: IRStmt[]): {
+    owned: {
+        cName: string;
+        ty: Type;
+    }[];
+    scalars: {
+        cName: string;
+        ty: Type;
+    }[];
+};
+/** Emits the function/scope's exit cleanup + return statements at a
+ *  given indent. Called from two places: at every `ReturnFromFunction`
+ *  site (inline cleanup — no goto), and at the fall-through bottom of
+ *  the function. Single source of truth so the two callers can't
+ *  drift on which locals get freed in what order.
+ *
+ *  Why inline rather than goto-to-a-shared-tail: c2js can't translate
+ *  C `goto`, and we want a single C emit that works for both targets.
+ *  Inlining produces some duplication when a function has many early
+ *  returns and many owned locals, but typical mtoc2 functions are
+ *  small and the C compiler dedupes-by-tail-merge anyway. */
+export type EmitReturnTail = (indent: string) => string;
+export declare function emitFunction(fn: IRFunc, state: RuntimeState, 
+/** Storage-class qualifier on the function definition. Default is
+ *  `static` (file-scope, the C-AOT whole-program convention). Pass
+ *  `""` to omit the qualifier — the function then gets external
+ *  linkage so a JIT host can resolve it via `dlsym` / koffi after
+ *  `dlopen`'ing the compiled `.so`. */
+storageClass?: "static" | ""): string;
+/** Emit a sequence of statements with their per-stmt early-frees.
+ *  After each stmt, owned C-names that aren't in the stmt's
+ *  futureTouchOut (i.e. their last use was at this stmt) get a
+ *  `<owned-kind>_free(&v);` call dispatched on the variable's
+ *  recorded owned type. Scope-exit frees still emit unconditionally
+ *  — they're no-ops for buffers already nulled by the early-free. */
+export declare function emitBody(stmts: IRStmt[], indent: string, state: RuntimeState, futureTouches: FutureTouchMap, ownedTypes: ReadonlyMap<string, Type>, emitReturnTail: EmitReturnTail): string;
+/** Compute a column-major linear offset expression from cell-brace
+ *  indices. The base's shape supplies the row count for the 2-D
+ *  formula. Indices are 1-based in source; we subtract 1 to land
+ *  in C's 0-based slot/buffer array. */
+export declare function cellLinearOffsetExpr(indices: ReadonlyArray<IRExpr>, baseTy: Extract<Type, {
+    kind: "Cell";
+}>, baseCName: string, state: RuntimeState): string;
+/** Try to compute a static slot offset from a tuple cell's indices.
+ *  Returns `null` if any index isn't a NumLit. */
+export declare function tryStaticCellOffset(indices: ReadonlyArray<IRExpr>, baseTy: Extract<Type, {
+    kind: "Cell";
+}>): number | null;

package/dist-lib/numbl-core/jit/codegen/emitTensorConcat.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `TensorConcat` codegen — the bracket-concatenation IR node produced
+ * by `lowerTensorLit`'s mixed-cell path (`[a, b; c, d]` where at least
+ * one cell is a tensor). Two paths: a fully-static one that bakes per-
+ * cell row/col offsets into literals, and a dynamic one that walks
+ * runtime `.dims[k]` reads.
+ *
+ * Both emit a GCC statement-expression that allocs a destination
+ * tensor, writes every cell's rectangle, and evaluates to the
+ * destination. ANF guarantees every tensor cell is already a Var, so
+ * cell reads carry no allocation cost.
+ *
+ * Mirrors numbl's `catAlongDim` (runtime/tensor-construction.ts) for
+ * the output layout — column-major destination, per-cell rectangle.
+ */
+import type { IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+/** Top-level entry: dispatch to the static or dynamic codegen path
+ *  based on whether every per-cell dim and the output shape are
+ *  compile-time known. */
+export declare function emitTensorConcat(e: Extract<IRExpr, {
+    kind: "TensorConcat";
+}>, state: RuntimeState): string;

package/dist-lib/numbl-core/jit/codegen/emitTensorConcatJs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * JS sibling of `emitTensorConcat.ts`. Same two-path structure
+ * (fully-static vs. runtime-dim), same per-cell rectangle-copy
+ * shape — only the language and field names differ:
+ *   `.real` (C)  → `.data` (JS)
+ *   `.dims[k]` (C) → `.shape[k]` (JS)
+ *
+ * GCC statement-expressions don't exist in JS; the destination
+ * tensor and per-cell writes are wrapped in an IIFE that returns
+ * the result.
+ */
+import type { IRExpr } from "../lowering/ir.js";
+import { type RuntimeState } from "./runtime.js";
+export declare function emitTensorConcatJs(e: Extract<IRExpr, {
+    kind: "TensorConcat";
+}>, state: RuntimeState, emit: (e: IRExpr, state: RuntimeState) => string): string;