numbl 0.4.19 → 0.4.22

package/dist-browser/numbl-core/jit/builtins/registry.d.ts

@@ -1,8 +1,7 @@
 /**
- * Builtin registry — the contract every mtoc2 builtin (and future
- * user `.mtoc2.js` function) implements.
+ * Builtin registry — the contract every JIT builtin implements.
  *
- * Each builtin can supply up to three mirrored hooks plus the
+ * Each builtin can supply two mirrored codegen hooks plus the
  * always-required `transfer`:
  *
  *   transfer(argTypes, nargout) — required. Given input types and
@@ -32,15 +31,9 @@
  *     outputs land in these locals via the framework's destructuring
  *     wrapper. Activates JS-side runtime snippets via `useRuntime`.
  *
- *   call({args, argTypes, nargout, ctx}) — optional. Direct JS
- *     function used by the interpreter and as a JIT bailout target.
- *     Returns one runtime value per output slot. The args shape
- *     mirrors the emit hooks' shape so dispatch on `argTypes` /
- *     `nargout` stays parallel across all three.
- *
- *   elementwise? — when true, every defined emit hook (and `call`)
- *     must also produce a correct scalar output when called with
- *     scalar argTypes and scalar argsC/argsJs/args. The framework
+ *   elementwise? — when true, every defined emit hook must also
+ *     produce a correct scalar output when called with
+ *     scalar argTypes and scalar argsC/argsJs. The framework
  *     uses this for same-shape tensor fusion (and, later, broadcast
  *     / reduction-inner / mask / stencil fusion). Absence = "do not
  *     fuse me; use the regular emit on the full tensor types."
@@ -50,8 +43,6 @@
  * computes the maximum compatible backend per call site.
  */
 import type { Type } from "../lowering/types.js";
-import type { RuntimeValue } from "../runtime/value.js";
-import type { RuntimeContext } from "../runtime/context.js";
 /** Common across every hook — the type-level call descriptor. */
 interface CommonArgs {
     /** Per-arg type (after lowering / inference). */
@@ -71,7 +62,7 @@ export interface EmitCArgs extends CommonArgs {
     outArgsC?: string[];
     /** Activate a runtime C snippet on the current translation unit.
      *  See `runtime.ts` for the registry and `InlineSnippet` for the
-     *  user-supplied form. */
+     *  inline form. */
     useRuntime(spec: string | InlineSnippet): void;
 }
 export interface EmitJsArgs extends CommonArgs {
@@ -90,14 +81,6 @@ export interface EmitJsArgs extends CommonArgs {
      *  (with a `jsCode` body) defines a one-off helper from a builtin. */
     useRuntime(spec: string | InlineSnippet): void;
 }
-export interface CallArgs extends CommonArgs {
-    /** Per-arg runtime values, evaluated by the interpreter at the
-     *  call site. */
-    args: RuntimeValue[];
-    /** Host bag — `helpers.write` for stdout, future hooks for plot /
-     *  error / time. */
-    ctx: RuntimeContext;
-}
 export interface Builtin {
     /** Source-level name (registry key). */
     name: string;
@@ -109,13 +92,18 @@ export interface Builtin {
     emitC?(args: EmitCArgs): string;
     /** Optional: JS codegen. */
     emitJs?(args: EmitJsArgs): string;
-    /** Optional: direct JS function — interpreter / JIT bailout. */
-    call?(args: CallArgs): RuntimeValue[];
     /** Elementwise = result is computed pointwise. */
     elementwise?: boolean;
+    /** Optional: elementwise for these argument types only, for a builtin
+     *  whose forms differ by arity (two-argument `max(a, b)` is pointwise,
+     *  one-argument `max(a)` is a reduction). Consulted when `elementwise`
+     *  is not set. */
+    isElementwiseCall?(argTypes: Type[]): boolean;
 }
-/** Inline-defined runtime snippet supplied by a user `.mtoc2.js`
- *  builtin's `emitC` / `emitJs`. Re-exported from `runtime.ts` — kept
+/** Whether a call of `b` with these argument types is computed pointwise. */
+export declare function isElementwiseCall(b: Builtin, argTypes: Type[]): boolean;
+/** Inline-defined runtime snippet supplied by an emitter via
+ *  `useRuntime({...})`. Re-exported from `runtime.ts` — kept
  *  here for doc-locality with the `Builtin` contract. */
 export interface InlineSnippet {
     name: string;
@@ -130,9 +118,6 @@ export declare function registerBuiltin(b: Builtin): void;
 export declare function getBuiltin(name: string): Builtin | undefined;
 /** Names of every registered builtin. Drives Monaco syntax highlighting. */
 export declare function allBuiltinNames(): readonly string[];
-export type Backend = "c" | "js" | "interpreter";
-export declare function builtinSupports(b: Builtin, backend: Backend): boolean;
 export declare function requireEmitC(b: Builtin): (args: EmitCArgs) => string;
 export declare function requireEmitJs(b: Builtin): (args: EmitJsArgs) => string;
-export declare function requireCall(b: Builtin): (args: CallArgs) => RuntimeValue[];
 export {};

package/dist-browser/numbl-core/jit/builtins/runtime/system/cdiv.d.ts

@@ -2,3 +2,7 @@ export function mtoc2_cdiv(a: any, b: any): {
     re: number;
     im: number;
 };
+export function mtoc2_cdiv_mixed(a: any, b: any): {
+    re: number;
+    im: number;
+};

package/dist-browser/numbl-core/jit/builtins/runtime/system/cscalar.d.ts

@@ -16,6 +16,10 @@ export function mtoc2_cmul(a: any, b: any): {
     re: number;
     im: number;
 };
+export function mtoc2_cmul_mixed(a: any, b: any): {
+    re: number;
+    im: number;
+};
 export function mtoc2_cneg(z: any): {
     re: number;
     im: number;

package/dist-browser/numbl-core/jit/builtins/runtime/tensor_ops/tensor_elemwise_real_fn.d.ts

@@ -13,77 +13,97 @@ export function mtoc2_tensor_atan2_st(s: any, a: any): {
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_atan2_bcast_tt(a: any, b: any): {
+export function mtoc2_tensor_hypot_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_hypot_tt(a: any, b: any): {
+export function mtoc2_tensor_hypot_ts(a: any, s: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_hypot_ts(a: any, s: any): {
+export function mtoc2_tensor_power_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_hypot_bcast_tt(a: any, b: any): {
+export function mtoc2_tensor_power_ts(a: any, s: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_power_tt(a: any, b: any): {
+export function mtoc2_tensor_power_st(s: any, a: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_power_ts(a: any, s: any): {
+export function mtoc2_tensor_rem_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_power_st(s: any, a: any): {
+export function mtoc2_tensor_rem_ts(a: any, s: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_power_bcast_tt(a: any, b: any): {
+export function mtoc2_tensor_rem_st(s: any, a: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_rem_tt(a: any, b: any): {
+export function mtoc2_tensor_mod_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_rem_ts(a: any, s: any): {
+export function mtoc2_tensor_mod_ts(a: any, s: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_rem_st(s: any, a: any): {
+export function mtoc2_tensor_mod_st(s: any, a: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_rem_bcast_tt(a: any, b: any): {
+export function mtoc2_tensor_max_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_mod_tt(a: any, b: any): {
+export function mtoc2_tensor_max_ts(a: any, s: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_mod_ts(a: any, s: any): {
+export function mtoc2_tensor_min_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_tensor_mod_st(s: any, a: any): {
+export function mtoc2_tensor_min_ts(a: any, s: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_atan2_bcast_tt(a: any, b: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_hypot_bcast_tt(a: any, b: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_power_bcast_tt(a: any, b: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_rem_bcast_tt(a: any, b: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
@@ -93,3 +113,13 @@ export function mtoc2_tensor_mod_bcast_tt(a: any, b: any): {
     shape: any;
     data: any;
 };
+export function mtoc2_tensor_max_bcast_tt(a: any, b: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
+export function mtoc2_tensor_min_bcast_tt(a: any, b: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};

package/dist-browser/numbl-core/jit/builtins/runtime/tensor_ops/tensor_reduce_real.d.ts

@@ -1,28 +1,28 @@
-export function mtoc2_sum_all(t: any): any;
+export function mtoc2_sum_all(t: any): number;
 export function mtoc2_sum_dim(t: any, d: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_prod_all(t: any): any;
+export function mtoc2_prod_all(t: any): number;
 export function mtoc2_prod_dim(t: any, d: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_mean_all(t: any): any;
+export function mtoc2_mean_all(t: any): number;
 export function mtoc2_mean_dim(t: any, d: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_min_all(t: any): number;
+export function mtoc2_min_all(t: any): any;
 export function mtoc2_min_dim(t: any, d: any): {
     mtoc2Tag: string;
     shape: any;
     data: any;
 };
-export function mtoc2_max_all(t: any): number;
+export function mtoc2_max_all(t: any): any;
 export function mtoc2_max_dim(t: any, d: any): {
     mtoc2Tag: string;
     shape: any;

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

@@ -1,3 +1,4 @@
+export function mtoc2_realsqrt(x: any): number;
 export function mtoc2_tensor_cos(a: any): {
     mtoc2Tag: string;
     shape: any;
@@ -63,6 +64,11 @@ export function mtoc2_tensor_sqrt(a: any): {
     shape: any;
     data: any;
 };
+export function mtoc2_tensor_realsqrt(a: any): {
+    mtoc2Tag: string;
+    shape: any;
+    data: any;
+};
 export function mtoc2_tensor_abs(a: any): {
     mtoc2Tag: string;
     shape: any;

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

@@ -1,9 +1,9 @@
 /**
- * Single-file C codegen for mtoc2 IR. Emits:
+ * Single-file C codegen for JIT IR. Emits a shared-library module:
  *   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.
+ *   3. Function specialization bodies; the entry spec gets extern
+ *      linkage so the host can `dlsym` it.
  *
  * Scalars compile to bare `double`. Multi-element tensors compile to
  * `mtoc2_tensor_t` — no refcount, no COW. The codegen invariant
@@ -14,39 +14,18 @@
  * 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;
+    /** cName of the entry spec to expose at module scope (no `static`
+     *  qualifier so `dlsym` / koffi can resolve it after `dlopen`).
+     *  `prog.functions` must contain it and every spec it transitively
+     *  calls. */
+    exposeSpec: string;
 }
-export declare function emitProgram(prog: IRProgram, opts?: EmitOptions): 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

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

@@ -22,43 +22,25 @@
  *   <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;
+ *   return function ($h) { globalThis.$write = $h.write; ...; return <entry-spec>; };
  *   ```
  *
- * The CLI / engine evals the source via `new Function(source)(...)`
- * which returns `run`, then invokes `run(ctx.helpers)`.
+ * The host evals the source via `new Function(source)()`, then calls
+ * the returned factory with its helper hooks to get the entry spec.
  */
 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;
+    /** cName of the entry spec the module's factory returns.
+     *  `prog.functions` must contain it and every spec it transitively
+     *  calls. */
+    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(...)`. */
+     *  `return ($h) => specFn;`. 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;
+export declare function emitJsProgram(prog: IRProgram, opts: EmitJsOptions): EmitJsResult;

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

@@ -11,47 +11,23 @@ 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;
+ *  Inlined rather than goto-to-a-shared-tail, which keeps the C emit
+ *  parallel to the JS one. Inlining produces some duplication when a
+ *  function has many early returns and many owned locals, but typical
+ *  functions are small and the C compiler dedupes-by-tail-merge
+ *  anyway. */
+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
+ *  `static` (file-scope). 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;
@@ -74,3 +50,4 @@ export declare function cellLinearOffsetExpr(indices: ReadonlyArray<IRExpr>, bas
 export declare function tryStaticCellOffset(indices: ReadonlyArray<IRExpr>, baseTy: Extract<Type, {
     kind: "Cell";
 }>): number | null;
+export {};

package/dist-browser/numbl-core/jit/codegen/emitTensorFused.d.ts

@@ -23,15 +23,16 @@
  * For a single-Binary RHS this is equivalent (post-`-O3`) to the
  * existing `mtoc2_tensor_assign(&c, mtoc2_tensor_plus_tt(a, b))`
  * path — the helper's body is literally the same loop. The point of
- * doing the inlining at the IR level is that the `--inline-temps`
- * pass (phase 2) can fold a chain like `_t1 = a * b; c = _t1 + d`
- * into `c = (a * b) + d`, which the fused emitter then renders as
- * one loop with no intermediate tensor allocation.
+ * doing the inlining at the IR level is that an IR-to-IR pass
+ * (`inlinePass.ts`, run by `compileSpecC` before emit)
+ * can fold a chain like `_t1 = a * b; c = _t1 + d` into
+ * `c = (a * b) + d`, which the fused emitter then renders as one loop
+ * with no intermediate tensor allocation.
  *
- * Phase 1 (this file) only handles the *same-static-shape* case. If
- * any multi-element operand has a statically-different shape from
- * the target, the Assign falls back to the runtime-helper path
- * (`mtoc2_tensor_<op>_bcast_tt(...)`). Broadcast fusion is phase 3.
+ * Only the *same-static-shape* case is handled. If any multi-element
+ * operand has a statically-different shape from the target, the
+ * Assign falls back to the runtime-helper path
+ * (`mtoc2_tensor_<op>_bcast_tt(...)`).
  */
 import type { Assign, IRExpr } from "../lowering/ir.js";
 import { type RuntimeState } from "./runtime.js";
@@ -72,6 +73,6 @@ export declare function fusedAssignNeedsShapeGuard(s: Assign): boolean;
  *  operand must match the shape source's runtime shape, else the assign
  *  defers to `fallbackStmt` — the bcast-aware helper path, which
  *  broadcasts compatible shapes and raises "Matrix dimensions must
- *  agree" on incompatible ones. Mirrors the JS `tt_kernel` deferring to
+ *  agree" on incompatible ones. Mirrors the JS `_tt` helpers deferring to
  *  `bcast_kernel`. */
 export declare function emitTensorAssignFused(s: Assign, indent: string, state: RuntimeState, fallbackStmt?: string): string;

package/dist-browser/numbl-core/jit/codegen/inlinePass.d.ts

@@ -1,6 +1,6 @@
 /**
- * `--inline-temps` IR-to-IR rewrite: substitutes a single-use
- * producer Assign's RHS into its consumer's RHS and removes the
+ * IR-to-IR rewrite for the C backend: substitutes a single-use
+ * producer Assign's RHS into its consumer's RHS and drops the
  * producer.
  *
  * After ANF normalization every owned-producing tensor expression
@@ -13,54 +13,45 @@
  *     r2   = _t10 + 0.01
  *
  * emits four separate fused loops with three intermediate allocs.
- * After inlining (this pass), the chain collapses to
+ * After inlining, the chain collapses to
  *
  *     r2 = (rx .^ 2 + ry .^ 2 + 0.01)
  *
  * which the elementwise-fused emitter (`emitTensorFused.ts`) renders
- * as a single iter loop. No intermediate tensors, no extra passes
- * through memory.
- *
- * Gates (must all hold to inline producer P into consumer C):
- *
- *   1. P is an Assign producing a real-double multi-element tensor.
- *   2. P's RHS is pure elementwise — only NumLit / Var / Binary /
- *      Unary / Call to a builtin that has `perSlotC`. No
- *      TensorBuild / TensorConcat / IndexLoad / IndexSlice /
- *      MemberLoad / HandleLit / etc.
- *   3. P's LHS cName is used exactly once in the body. Function
- *      output cNames get a `+1` protective bump so the returned
- *      value is never elided.
- *   4. The single use is in another Assign's RHS, in a slot
- *      position (subexpression of Binary / Unary / Call args). NOT
- *      as the base of an IndexLoad / IndexSlice / MemberLoad, NOT
- *      inside a TensorBuild / TensorConcat / StructLit / HandleLit.
- *   5. C is also fusable (same predicate as `isFusableAssign`).
- *   6. P and C are at the same body level (no inlining across
- *      If / While / For — nested bodies are inlined separately).
- *   7. No statement between P and C writes to P's LHS or to any
- *      free Var in P's RHS, and no statement reads P's LHS except
- *      C. Control flow (If / While / For / Break / Continue /
- *      ReturnFromFunction) ends the safe window.
- *
- * Algorithm: per body, iterate `inlineOnePass` to fixed point.
- * Each pass scans producers in source order, finds the first
- * inlinable pair, substitutes, and returns the new body. Chained
- * inlining (`a → b → c`) needs multiple iterations because each
- * substitution can flip a previously-multi-use cName to single-use;
- * we cap at 32 iterations defensively.
- *
- * Preserves: post-inlining the IR is still well-typed (each node's
- * `.ty` is unchanged — the substitution copies the producer's RHS
- * subtree verbatim); the ANF invariant for owned producers still
- * holds because we only inline producers whose RHS is NOT itself
- * an owned producer (no TensorBuild / Call-to-direct-owned-builtin
- * / etc.); and the `isFusableAssign` predicate that gates the
- * emit-path routing still accepts the consumer after substitution
- * (shape checks compose under inlining — see the design notes in
- * `emitTensorFused.ts`).
+ * as a single loop.
+ *
+ * Gates (all must hold to inline producer P into consumer C):
+ *
+ *   1. P is a fusable Assign (`isFusableAssign`): real multi-element
+ *      tensor target, pure-elementwise RHS, operand shapes matching
+ *      the target.
+ *   2. P's LHS cName is read exactly once in the whole function
+ *      (nested bodies included). Function outputs get a +1 bump so
+ *      they are never dropped. Counting function-wide, not per body,
+ *      is what makes inlining inside loop / if bodies safe: a
+ *      body-local count misses reads after the loop.
+ *   3. C is the first statement after P in the same body that reads
+ *      P's LHS, and it is an Assign. Statements in between must not
+ *      write P's LHS or any Var P's RHS reads, and must not be
+ *      control flow. C itself may write such a Var: an Assign
+ *      evaluates its whole RHS before storing.
+ *   4. The read in C is in a slot position (Binary / Unary / Call
+ *      operand), and C is still fusable after substitution. The
+ *      latter is an ownership rule: a non-fused consumer would get a
+ *      nested owned operand that nothing frees.
+ *
+ * Use counts are stable under substitution (a single-use producer's
+ * reads move into its consumer; none is duplicated or dropped), so
+ * one forward sweep per body suffices: a consumer rewritten at index
+ * j is itself considered as a producer when the sweep reaches j,
+ * which collapses chains of any depth.
+ *
+ * The pass never mutates its input. The Lowerer's specialization
+ * cache is shared by the JS and C backends, so changed functions and
+ * statements are fresh objects; untouched ones are shared.
  */
-import type { IRProgram } from "../lowering/ir.js";
-/** Top-level entry. Mutates `prog.topLevelStmts` and each function's
- *  `body` in place when inlining fires. */
-export declare function inlinePass(prog: IRProgram): void;
+import type { IRFunc, IRProgram } from "../lowering/ir.js";
+/** Returns a new program with every function inlined. */
+export declare function inlinePass(prog: IRProgram): IRProgram;
+/** Returns `fn` itself when nothing was inlined. */
+export declare function inlineFunc(fn: IRFunc): IRFunc;

package/dist-browser/numbl-core/jit/codegen/prettyIR.d.ts

@@ -9,7 +9,7 @@
  * are visible). It IS a faithful render of what the IR actually says
  * after lowering — useful when debugging the translator.
  */
-import type { IRStmt, IRFunc, IRProgram } from "../lowering/ir.js";
+import type { IRStmt, IRFunc } from "../lowering/ir.js";
 /** One-line summary of a statement (no trailing newline). Returns null
  *  for stmts the emitter handles structurally (compound-block bodies
  *  get their own per-stmt comments inside). */
@@ -17,8 +17,3 @@ export declare function irStmtHeader(s: IRStmt): string | null;
 /** Multi-line C block comment for a function specialization, listing
  *  name, mangled C identifier, per-parameter types, and output types. */
 export declare function irFuncDocComment(fn: IRFunc): string;
-/** Render the whole lowered IR as a numbl-like script with one block
- *  per function specialization plus a trailing top-level body. Used by
- *  the IDE's Internals tab in interpreter mode, where no codegen
- *  artifact exists. */
-export declare function prettyIRProgram(prog: IRProgram): string;