numbl 0.2.0 → 0.3.3

package/dist-lib/numbl-core/helpers/linsolve.d.ts

@@ -9,18 +9,17 @@
  * Both the native LAPACK addon and the ts-lapack TypeScript fallback are
  * supported; the native addon is preferred when available.
  */
-import { FloatXArrayType } from "../runtime/types.js";
 /**
  * Dispatch linsolve to the native addon (preferred) or ts-lapack fallback.
  * Returns null only when neither bridge exposes `linsolve` (should not happen
  * in practice since ts-lapack always has it).
  */
-export declare function linsolveLapack(A: FloatXArrayType, m: number, n: number, B: FloatXArrayType, nrhs: number): Float64Array | null;
+export declare function linsolveLapack(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array | null;
 /**
  * Dispatch complex linsolve to the native addon (preferred) or ts-lapack fallback.
  * The ts-lapack fallback throws — native addon is required for complex linsolve.
  */
-export declare function linsolveComplexLapack(ARe: FloatXArrayType, AIm: FloatXArrayType, m: number, n: number, BRe: FloatXArrayType, BIm: FloatXArrayType, nrhs: number): {
+export declare function linsolveComplexLapack(ARe: Float64Array, AIm: Float64Array, m: number, n: number, BRe: Float64Array, BIm: Float64Array, nrhs: number): {
     re: Float64Array;
     im: Float64Array;
 };

package/dist-lib/numbl-core/helpers/prng.d.ts

@@ -2,7 +2,6 @@
  * Seedable PRNG (xoshiro128**) for random number generation
  */
 import { RuntimeValue } from "../runtime/index.js";
-import { type FloatXArrayType } from "../runtime/types.js";
 export declare function setRngShuffle(): void;
 export declare function setRngSeed(seed: number): void;
 export declare function seedRng(seed: number): void;
@@ -10,7 +9,7 @@ export declare function seedRng(seed: number): void;
 export declare function rngRandom(): number;
 export declare function boxMullerRandom(): number;
 /** Fill a typed array with normal random values (bulk polar method) */
-export declare function fillRandn(data: FloatXArrayType): void;
+export declare function fillRandn(data: Float64Array): void;
 /** Return the current RNG state as a struct {Type, Seed, State} */
 export declare function getRngStateStruct(): RuntimeValue;
 /** Restore RNG state from a struct previously returned by rng() */

package/dist-lib/numbl-core/interpreter/builtins/datetime.d.ts

@@ -27,7 +27,8 @@
  * `seconds(d)` returns the numeric seconds of a duration, or wraps a
  * number as a duration.
  */
-import type { RuntimeValue, RuntimeClassInstance } from "../../runtime/types.js";
+import type { RuntimeValue } from "../../runtime/types.js";
+import { RuntimeClassInstance } from "../../runtime/types.js";
 export declare function makeDatetime(year: number, month: number, day: number, hour: number, minute: number, second: number): RuntimeClassInstance;
 export declare function makeDuration(totalSeconds: number): RuntimeClassInstance;
 /**

package/dist-lib/numbl-core/interpreter/builtins/misc.d.ts

@@ -1,4 +1,7 @@
 import type { RuntimeValue } from "../../runtime/types.js";
-/** Clear all appdata — called at the start of each executeCode to isolate runs. */
+/** Clear all appdata — called at the start of each executeCode to isolate
+ *  runs. Decrefs every stored value so the previous run's containers can
+ *  hit rc=0 cleanly; if the previous runtime is gone (test harness), we
+ *  just drop the JS references and let GC reclaim them. */
 export declare function resetAppdataStore(): void;
 export declare function convertJsonValue(val: unknown): RuntimeValue;

package/dist-lib/numbl-core/interpreter/builtins/types.d.ts

@@ -1,9 +1,9 @@
 /**
  * IBuiltin interface, registry, and shared helpers for interpreter builtins.
  */
-import type { RuntimeValue, RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
-import { FloatXArray } from "../../runtime/types.js";
-import { type JitType } from "../../jit/jitTypes.js";
+import type { RuntimeValue } from "../../runtime/types.js";
+import { RuntimeTensor, RuntimeComplexNumber } from "../../runtime/types.js";
+import { type JitType } from "../../jitTypes.js";
 export interface IBuiltinResolution {
     outputTypes: JitType[];
     apply: (args: RuntimeValue[], nargout: number) => RuntimeValue | RuntimeValue[];
@@ -19,49 +19,6 @@ export interface IBuiltin {
     resolve: (argTypes: JitType[], nargout: number) => IBuiltinResolution | null;
     /** Optional fast-path JS code emission for JIT. Return null to fall back to $h.ib_<name>. */
     jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
-    /**
-     * Optional fast-path C code emission for the C-JIT. Return null if the
-     * builtin can't be emitted as a C expression for the given arg types
-     * — the C-JIT will bail to JS-JIT for this call site. Covers the
-     * scalar-argument case only (tensor-argument emission is handled by
-     * separate tensor-op dispatch in assemble.ts / emit/fused.ts).
-     */
-    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
-    /**
-     * Optional C-JIT tensor-op dispatch metadata. When a field is present,
-     * both the C feasibility check and C codegen read it directly —
-     * adding a new tensor-unary / tensor-binary / tensor-reduction builtin
-     * is one edit here (plus the matching native-side enum or C function).
-     * Previously these were three parallel hardcoded tables (one in
-     * feasibility.ts, two in context.ts) that could silently drift
-     * from the native-side opcode enums. Centralizing on the IBuiltin
-     * registration removes that drift risk.
-     */
-    jitCapabilities?: JitCapabilities;
-}
-/** Per-builtin C-JIT tensor-op dispatch metadata. See IBuiltin.jitCapabilities. */
-export interface JitCapabilities {
-    /**
-     * libnumbl_ops opcode enum name (e.g. "NUMBL_UNARY_EXP") for
-     * element-wise unary tensor builtins routed through
-     * `numbl_realUnaryElemwise`. Set this on element-wise unary functions
-     * that have a libnumbl_ops opcode and are safe to invoke on any real
-     * input (domain-restricted ones like log/sqrt stay excluded).
-     */
-    tensorUnaryOp?: string;
-    /**
-     * C function name (e.g. "fmax", "atan2", "numbl_mod") for 2-arg
-     * element-wise tensor builtins. The C-JIT emits an inline per-element
-     * loop calling this function; it must match the interpreter's
-     * scalar-apply semantics exactly.
-     */
-    tensorBinaryFn?: string;
-    /**
-     * libnumbl_ops opcode enum name (e.g. "NUMBL_REDUCE_SUM") for
-     * tensor→scalar reductions routed through `numbl_tensor_reduce_op`.
-     * Set on reduction builtins (sum / prod / max / min / any / all / mean).
-     */
-    tensorReductionOp?: string;
 }
 export declare function getIBuiltin(name: string): IBuiltin | undefined;
 export declare function registerIBuiltin(b: IBuiltin): void;
@@ -83,7 +40,7 @@ export declare function inferJitType(value: unknown): JitType;
  *  that the runtime replaces when profiling is enabled. */
 export declare function buildIBuiltinHelpers(): Record<string, any>;
 export declare function mkc(re: number, im: number): number | RuntimeComplexNumber;
-export declare function makeTensor(data: InstanceType<typeof FloatXArray>, imag: InstanceType<typeof FloatXArray> | undefined, shape: number[]): RuntimeTensor;
+export declare function makeTensor(data: Float64Array, imag: Float64Array | undefined, shape: number[]): RuntimeTensor;
 /** Type rule requiring two scalar numbers */
 export declare function binaryNumberOnly(argTypes: JitType[]): JitType[] | null;
 export declare function applyUnaryElemwise(v: RuntimeValue, realFn: (x: number) => number, complexFn: (re: number, im: number) => {
@@ -110,8 +67,6 @@ export declare function defineBuiltin(opts: {
     help?: BuiltinHelp;
     cases: BuiltinCase[];
     jitEmit?: (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
-    jitEmitC?: (argCode: string[], argTypes: JitType[]) => string | null;
-    jitCapabilities?: JitCapabilities;
 }): void;
 type NumberJitType = Extract<JitType, {
     kind: "number";
@@ -158,46 +113,4 @@ export declare function predicateCases(scalarTest: (x: number) => boolean, compl
 export declare function unaryMathJitEmit(mathFn: string, tensorHelper: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[], getDest?: () => string) => string | null;
 /** Fast-path emitter for binary Math.* functions on two scalar numbers. */
 export declare function binaryMathJitEmit(mathFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
-/** Fast-path C emitter for unary math functions on a scalar.
- *  Emits `cFn(x)` for scalar number/boolean; returns null otherwise
- *  (tensor emission is handled separately by emit/tensor.ts).
- *  If `requireNonneg` is set, rejects values whose sign isn't known
- *  to be nonneg — matches the JS guard for domain-restricted functions. */
-export declare function unaryMathJitEmitC(cFn: string, requireNonneg?: boolean): (argCode: string[], argTypes: JitType[]) => string | null;
-/** Fast-path C emitter for binary math functions on two scalar numbers. */
-export declare function binaryMathJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar builtins that collapse to a
- * compile-time constant given the arg's kind. Common for shape/type
- * predicates where the answer is fully determined by the type
- * (e.g. `isnumeric(number) -> 1.0`, `isscalar(number) -> 1.0`,
- *       `ndims(number) -> 2.0`, `numel(number) -> 1.0`).
- *
- * `valueByKind` maps each supported JitType kind to its C constant.
- * Arg kinds not in the map return null, which bails the C-JIT to
- * JS-JIT for that call site. All values must be valid C double
- * literals (`"1.0"`, `"0.0"`, `"2.0"`, ...).
- */
-export declare function scalarConstantJitEmitC(valueByKind: Partial<Record<JitType["kind"], string>>): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar predicates backed by a runtime
- * helper whose return value is int (e.g. `numbl_is_nan`,
- * `numbl_is_inf`, `numbl_is_finite`). The int is cast to double for
- * the C-JIT's uniform boolean-as-double representation. Returns null
- * for non-scalar args.
- *
- * Note: `isnan` / `isinf` / `isfinite` from `<math.h>` can't be used
- * directly because the JIT compiles with `-ffast-math`, which implies
- * `-ffinite-math-only` and constant-folds those macros to false/true.
- * The `numbl_is_nan` / `_is_inf` / `_is_finite` helpers in
- * `jit_runtime` use bit-pattern inspection and live in a separately
- * compiled archive, so the caller's `-ffast-math` can't defeat them.
- */
-export declare function unaryPredicateJitEmitC(cFn: string): (argCode: string[], argTypes: JitType[]) => string | null;
-/**
- * Fast-path C emitter for 1-arg scalar builtins that are the identity
- * on real scalars (e.g. `double(x)`, `real(x)`, `conj(x)`). Returns
- * `(x)` for `number`/`boolean`, null otherwise.
- */
-export declare function scalarIdentityJitEmitC(): (argCode: string[], argTypes: JitType[]) => string | null;
 export {};

package/dist-lib/numbl-core/interpreter/interpreter.d.ts

@@ -48,55 +48,45 @@ export declare class Interpreter {
     fileSources: Map<string, string>;
     /** @internal Guard against infinite recursion in compileSpecialized */
     compileInProgress: Set<string>;
-    /** @internal Per-instance cache for JIT-compiled loops (avoids cross-execution collisions). */
-    loopJitCache: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-        source: string;
-    } | null>;
-    /** @internal Per-instance cache for C-JIT-compiled loops (parallel to loopJitCache). */
-    loopCJitCache: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-    } | null>;
-    /** @internal Progressive type widening for loop JIT: location -> last unified input types. */
-    loopLastInputTypes: Map<string, import("../jit/jitTypes.js").JitType[]>;
-    /** @internal Sibling stmts of the currently-executing stmt (set by execStmts). */
-    _postSiblings: import("../parser/types.js").Stmt[] | null;
-    /** @internal Index in _postSiblings of the next stmt after the current one. */
-    _postSiblingsIdx: number;
     /**
-     * Optimization level:
-     *   0 — pure AST interpreter, no JIT.
-     *   1 — JS-JIT (default): type-specialize hot functions/loops to JS via `new Function()`.
-     *   2 — C-JIT: additionally emit C for feasible scalar specializations,
-     *       compile to a native `.node` module, and invoke via N-API.
-     *       Infeasible IR transparently falls back to the JS-JIT path.
+     * Optimization mode:
+     *   "0"  — pure AST interpreter, no JIT.
+     *   "1"  — JS-JIT (default): type-specialize hot functions/loops to JS
+     *          via `new Function()`.
+     *   "e3" — C-JIT scalar-loop only (Node only). No JS-JIT suite is
+     *          registered alongside; loops either match the C-JIT
+     *          executor or fall back to the AST interpreter.
      */
-    optimization: number;
-    /**
-     * Experimental opt variant selector — e.g. `"e1"` for the prototype
-     * that keeps JS-JIT as the outer and emits on-demand C kernels for
-     * fusible tensor chains. Undefined for the standard `--opt <n>` path.
-     */
-    experimental?: string;
-    /** Emit fused per-element loops in C-JIT (--fuse flag). */
-    fuse: boolean;
-    /** Parallelize fused loops with OpenMP threads (--par flag). */
-    par: boolean;
-    /**
-     * Diagnostic mode (`--check-c-jit-parity`, only meaningful with `--opt 2`).
-     * When set, any C-JIT miss where JS-JIT would have compiled throws a
-     * `CJitParityError` instead of silently falling back — surfacing parity
-     * gaps as a punch list of features to implement in the C-JIT. Env
-     * failures (missing `cc`, compile failure) also throw, since the user
-     * explicitly asked to audit C-JIT coverage.
-     */
-    checkCJitParity: boolean;
+    optimization: import("../executors/plugins.js").OptLevel;
     /** Callback for JIT compilation logging (JS codegen). */
     onJitCompile?: (description: string, jsCode: string) => void;
-    /** Callback for C-JIT compilation logging (--dump-c). */
-    onCJitCompile?: (description: string, cSource: string) => void;
-    /** Verbose log sink (plumbed from ExecOptions.log; used by C-JIT for diagnostics). */
+    /** Callback for C-JIT compilation logging (C codegen). Invoked once
+     *  per cache miss, before the C source is compiled. */
+    onCJitCompile?: (description: string, cCode: string) => void;
+    /** Bridge for loading native shared libraries — used by the C-JIT
+     *  loop executor (`--opt e3`) to dlopen freshly-compiled `.so`
+     *  artifacts via koffi. Undefined in browser contexts; the executor
+     *  declines when undefined. */
+    nativeBridge?: import("../workspace/types.js").NativeBridge;
+    /** Compile c-jit kernels with `-ffast-math`. On by default for
+     *  libmvec-vectorized transcendentals (~30% speedup on element-wise
+     *  tensor benchmarks); opt out via the CLI's `--no-fast-math` flag
+     *  to keep reductions bitwise-deterministic. */
+    fastMath: boolean;
+    /** Telemetry: invoked after a registered executor's `run()` succeeds.
+     *  Used to track which optimizers fire in a session. The kind is the
+     *  LoweredStmt kind the executor handled ("top-level", "loop", "call",
+     *  ...). Hot path — keep the callback cheap. */
+    onExecutorFired?: (name: string, kind: string) => void;
+    /** Verbose log sink (plumbed from ExecOptions.log). */
     log?: (message: string) => void;
+    /** Executor registry. Holds the strategies (JS-JIT, C-kernel, ...)
+     *  the dispatcher selects among at runtime. The AST interpreter is
+     *  the dispatcher's hardcoded fallback (not a registered executor).
+     *  Mode-driven plugins (`--opt 1`, `--opt 2`, ...) register
+     *  executors during `executeCode` setup. See
+     *  docs/developer_reference/executors.md. */
+    readonly registry: import("../executors/registry.js").Registry;
     constructor(rt: Runtime, ctx: LoweringContext, functionIndex: FunctionIndex, mainFileName: string, initialVariableValues?: Record<string, RuntimeValue>);
     /** Clear all JIT and function resolution caches. Called after addpath/rmpath. */
     clearAllCaches(): void;

package/dist-lib/numbl-core/interpreter/interpreterSpecialBuiltins.d.ts

@@ -12,15 +12,18 @@ export interface InterpreterContext {
     evalInLocalScope: (codeArg: unknown, fileName?: string) => unknown;
     callFunction: (name: string, args: unknown[], nargout: number) => unknown;
     rt: Runtime;
-    /** Optimization level (0 = JIT disabled, 1 = JIT scalar functions). */
-    optimization: number;
+    /** Optimization mode: "0" = no JIT, "1" = JS-JIT, "e3" = C-JIT scalar loops. */
+    optimization: import("../executors/plugins.js").OptLevel;
     /** Resolve a workspace function or class name to its source file,
      *  or undefined if no workspace file provides that name.
      *  `kind` distinguishes a regular .m function from a .numbl.js
-     *  user function (treated as a MEX-equivalent) or a class file. */
+     *  user function (treated as a MEX-equivalent) or a class file.
+     *  `source` is the raw .m source for "function"/"class" kinds, or empty
+     *  for "jsfunction" (where the implementation is JS, not .m text). */
     lookupWorkspaceFile: (name: string) => {
         path: string;
         kind: "function" | "jsfunction" | "class";
+        source: string;
     } | undefined;
 }
 export declare const FALL_THROUGH: unique symbol;

package/dist-lib/numbl-core/interpreter/types.d.ts

@@ -4,7 +4,6 @@
 import type { Stmt, ArgumentsBlock } from "../parser/types.js";
 import type { Runtime } from "../runtime/runtime.js";
 import type { RuntimeValue } from "../runtime/types.js";
-import type { JitType } from "../jit/jitTypes.js";
 export declare class BreakSignal {
     readonly _tag = "break";
 }
@@ -18,8 +17,8 @@ export declare class ReturnSignal {
 }
 export type ControlSignal = BreakSignal | ContinueSignal | ReturnSignal;
 export declare class Environment {
-    private parent?;
-    private vars;
+    parent?: Environment | undefined;
+    vars: Map<string, RuntimeValue>;
     /** When true, writes to variables found in parent go to the parent (nested function semantics). */
     isNested: boolean;
     /** Nested function definitions registered during execution. Lazy-initialized. */
@@ -44,12 +43,27 @@ export declare class Environment {
     persistentFuncId: string | undefined;
     /** Back-reference to the runtime (needed for global/persistent access) */
     rt: Runtime | null;
+    /** Set when a `@nestedFn` handle has been created that captures this env
+     *  (or an ancestor). Tells the function-exit cleanup that clearing this
+     *  env would strand the handle's closure, so locals must be left alive. */
+    nestedHandleCreated: boolean;
     constructor(parent?: Environment | undefined);
     get(name: string): RuntimeValue | undefined;
-    /** Set variable — for nested scopes, writes to parent if variable exists there. */
+    /** Set variable — for nested scopes, writes to parent if variable
+     *  exists there. Maintains refcounts: increfs the new value, decrefs
+     *  the slot's prior occupant (in that order so self-rebind is safe). */
     set(name: string, value: RuntimeValue): void;
     /** Always writes to this scope (for parameter binding). */
     setLocal(name: string, value: RuntimeValue): void;
+    /** Remove a variable from this scope's local map.
+     *  Returns true if the name was present locally. Does not touch
+     *  the parent scope, globals, or persistent registrations — those
+     *  are removed via `clear global` / `clear functions` (not yet
+     *  implemented). */
+    delete(name: string): boolean;
+    /** Remove all local variables from this scope. Globals,
+     *  persistents, and nested function defs are preserved. */
+    clearLocals(): void;
     has(name: string): boolean;
     /** Check if this scope directly owns a variable (not parent). */
     hasLocal(name: string): boolean;
@@ -60,9 +74,17 @@ export declare class Environment {
         fn: FunctionDef;
         env: Environment;
     } | undefined;
+    /** Mark this env and every ancestor up to (and including) the env that
+     *  defines `name` as having had a nested-function handle created. The
+     *  handle's closure references this env, so any of those scopes' locals
+     *  must stay alive after the function exits. Returns true if `name`
+     *  was found as a nested-function definition somewhere in the chain. */
+    markChainForNestedHandle(name: string): boolean;
     localNames(): string[];
     /** Create a snapshot of this environment (copies all variables by value).
-     *  Used for anonymous functions which capture values at definition time. */
+     *  Used for anonymous functions which capture values at definition time.
+     *  Each captured value is incref'd so it survives the source env's
+     *  clearLocals when the original frame returns. */
     snapshot(): Environment;
     toRecord(): Record<string, RuntimeValue>;
 }
@@ -72,13 +94,6 @@ export interface FunctionDef {
     outputs: string[];
     body: Stmt[];
     argumentsBlocks?: ArgumentsBlock[];
-    /** JIT compilation cache: maps signature key -> compiled entry or null (failed). */
-    _jitCache?: Map<string, {
-        fn: (...args: unknown[]) => unknown;
-        source: string;
-    } | null>;
-    /** Progressive type widening: last unified arg types, keyed by nargout. */
-    _lastJitArgTypes?: Map<number, JitType[]>;
 }
 /** Create a FunctionDef from an AST Function statement. */
 export declare function funcDefFromStmt(stmt: Stmt & {

package/dist-lib/numbl-core/{jit/jitTypes.d.ts → jitTypes.d.ts}

@@ -1,7 +1,7 @@
 /**
  * JIT type system and IR node definitions.
  */
-import type { BinaryOperation, UnaryOperation } from "../parser/types.js";
+import type { BinaryOperation, UnaryOperation } from "./parser/types.js";
 export type SignCategory = "positive" | "nonneg" | "nonpositive" | "negative";
 export type JitType = {
     kind: "number";
@@ -53,6 +53,12 @@ export type JitType = {
 } | {
     kind: "cell";
     shape?: number[];
+    /** Per-index element types (1-based), tracked when literal-index
+     *  writes happen with a known type. Reads with a literal index in
+     *  the map return the tracked type instead of `unknown`, which
+     *  unblocks chunkerfunc's `[out{1:3}] = fcurve(ts); r = out{1}; …`
+     *  pattern. Sparse — missing keys mean "unknown". */
+    elements?: Record<number, JitType>;
 } | {
     kind: "dictionary";
 } | {
@@ -361,6 +367,14 @@ export type JitStmt = {
     callName: string;
     args: JitExpr[];
     outputTypes: JitType[];
+    /** Dispatch shape:
+     *  - "ibuiltin" (default) — IBuiltin called via $h.ibcall.
+     *  - "func_handle" — `callName` is a function-handle var name; the
+     *    JIT loads the handle and calls jsFn with the requested nargout.
+     *  - "user" — `callName` is a user-fn name dispatched through the
+     *    interpreter (no specialized JIT artifact for the callee yet).
+     */
+    kind?: "ibuiltin" | "func_handle" | "user";
 } | {
     /**
      * Call a synthetic specialization (installed as a forwarder on $h)

package/dist-lib/numbl-core/jsUserFunctions.d.ts

@@ -21,6 +21,14 @@ export interface LoadedJsUserFunction {
 }
 /** Returns true if the file is a numbl JS user function file (`*.numbl.js`). */
 export declare function isNumblJsFile(fileName: string): boolean;
+/** Returns true if the file is an mtoc2-only user function file (`*.mtoc2.js`).
+ *  Numbl recognizes the extension for workspace discovery + function-name
+ *  resolution, but never executes the body — mtoc2's loader does that. */
+export declare function isMtoc2JsFile(fileName: string): boolean;
+/** Derive a function name from a `.mtoc2.js` workspace file path.
+ *    "myadd.mtoc2.js"            → "myadd"
+ *    "/path/to/myadd.mtoc2.js"   → "myadd" */
+export declare function funcNameFromMtoc2JsFile(fileName: string): string;
 /**
  * Load .numbl.js user function files and return them as LoadedJsUserFunction
  * records. Each loaded record carries the function name, source file name,

package/dist-lib/numbl-core/lowering/loweringContext.d.ts

@@ -23,6 +23,13 @@ interface WorkspaceRegistry {
         fileName: string;
         builtin: IBuiltin;
     }>;
+    /** mtoc2-only user functions (.mtoc2.js): functionName → { fileName, source }.
+     *  Numbl never executes these — the source text is stored for mtoc2's loader
+     *  to consume. Numbl's interpreter rejects calls to them with a clear error. */
+    mtoc2UserFunctionsByName: Map<string, {
+        fileName: string;
+        source: string;
+    }>;
     /** Per-workspace-file lowering contexts (created on demand) */
     fileContexts: Map<string, LoweringContext>;
     /** Workspace classes: qualifiedName → ClassInfo */
@@ -68,6 +75,10 @@ export interface FunctionIndex {
     workspaceFunctions: Set<string>;
     /** JS user functions (resolved at workspace-function priority, not builtin) */
     jsUserFunctions: Set<string>;
+    /** mtoc2-only user functions (.mtoc2.js). Resolved at workspace-function
+     *  priority, like jsUserFunctions. Numbl's interpreter rejects calls to
+     *  these; mtoc2 routes them through its own loader. */
+    mtoc2UserFunctions: Set<string>;
     /** Workspace classes (classdef files) */
     workspaceClasses: Set<string>;
     /** Local subfunctions per workspace file: primaryFuncName → Set<subfuncName> */
@@ -139,6 +150,12 @@ export declare class LoweringContext {
      * Register workspace files for on-demand resolution.
      * Extracts function names from filenames (top-level only, plus +pkg namespaces).
      * Also handles @ClassName class folders.
+     *
+     * `.m` files register as workspace functions / classes / private functions
+     * (the regular MATLAB-style discovery). `.mtoc2.js` files register as
+     * mtoc2-only user functions: numbl tracks the name so resolution sees
+     * them, but the body stays unparsed — mtoc2's loader evaluates them.
+     * `.mtoc2.js` files in `@ClassName/` are not yet supported.
      */
     registerWorkspaceFiles(files: WorkspaceFile[]): void;
     isWorkspaceFunction(name: string): boolean;
@@ -149,6 +166,13 @@ export declare class LoweringContext {
      * Uses first-wins semantics so search-path priority is honored.
      */
     registerJsUserFunction(funcName: string, fileName: string, builtin: IBuiltin): void;
+    /**
+     * Register an mtoc2-only user function (.mtoc2.js) in the workspace
+     * registry. Numbl stores the source text verbatim; mtoc2's loader
+     * evaluates it. Uses first-wins semantics so search-path priority is
+     * honored — same as `.numbl.js`.
+     */
+    registerMtoc2UserFunction(funcName: string, fileName: string, source: string): void;
     /**
      * Get the effective directory for this context's file, used for
      * private function resolution. If the file is inside a private/ folder,

package/dist-lib/numbl-core/native/lapack-bridge.d.ts

@@ -26,7 +26,7 @@ export interface LapackBridge {
      * Invert an n×n real matrix stored in column-major order (MATLAB/LAPACK convention).
      * @param data  Column-major Float64Array of length n*n (not modified).
      * @param n     Matrix dimension.
-     * @returns     Inverted matrix as a new Float64Array in column-major order.
+     * @returns     Inverted matrix as a allocFloat64Array in column-major order.
      * @throws      Error if the matrix is singular.
      */
     inv(data: Float64Array, n: number): Float64Array;
@@ -138,7 +138,7 @@ export interface LapackBridge {
      * @param k  Number of columns in A and rows in B.
      * @param B  Column-major Float64Array of length k*n  (B is k×n, not modified).
      * @param n  Number of columns in B and C.
-     * @returns  C = A*B as a new Float64Array of length m*n in column-major order.
+     * @returns  C = A*B as a allocFloat64Array of length m*n in column-major order.
      */
     matmul?(A: Float64Array, m: number, k: number, B: Float64Array, n: number): Float64Array;
     /**
@@ -168,7 +168,7 @@ export interface LapackBridge {
      * @param n     Number of columns in A; also the number of rows in the result X.
      * @param B     Column-major Float64Array of length m*nrhs  (B is m×nrhs, not modified).
      * @param nrhs  Number of right-hand sides (columns of B and X).
-     * @returns     X as a new Float64Array of length n*nrhs in column-major order.
+     * @returns     X as a allocFloat64Array of length n*nrhs in column-major order.
      */
     linsolve?(A: Float64Array, m: number, n: number, B: Float64Array, nrhs: number): Float64Array;
     /**

package/dist-lib/numbl-core/parser/types.d.ts

@@ -316,6 +316,26 @@ export type Stmt = {
     directive: string;
     args: string[];
     span: Span;
+} | {
+    /** Synthetic stmt produced by an executor-registered AST
+     *  transformer (e.g. the C-JIT chain pass). Wraps a contiguous
+     *  run of original stmts so a specialized executor can claim
+     *  them as a unit; the interpreter falls back to executing
+     *  `subStmts` in order when the executor isn't registered or
+     *  declines.
+     *
+     *  Never produced by the parser. */
+    type: "Synth";
+    /** Identifies the executor that this synth node was built for
+     *  (e.g. `"c-jit-chain"`). The matching executor reads `data`. */
+    tag: string;
+    /** Original adjacent stmts, in source order. Used by the
+     *  interpreter fallback. */
+    subStmts: Stmt[];
+    /** Executor-specific pre-computed analysis. Opaque to the
+     *  interpreter. */
+    data: unknown;
+    span: Span;
 };
 export interface AbstractSyntaxTree {
     body: Stmt[];

package/dist-lib/numbl-core/runtime/constructors.d.ts

@@ -1,13 +1,13 @@
 /**
- * RuntimeValue constructor helpers (the MV namespace).
+ * RuntimeValue constructor helpers (the RTV namespace).
  */
 import { ItemType } from "../lowering/itemTypes.js";
-import { type RuntimeNumber, type RuntimeTensor, type RuntimeString, type RuntimeChar, type RuntimeLogical, type RuntimeCell, type RuntimeStruct, type RuntimeFunction, type RuntimeClassInstance, type RuntimeComplexNumber, type RuntimeDummyHandle, type RuntimeGraphicsHandle, type RuntimeStructArray, type RuntimeSparseMatrix, type RuntimeDictionary, type RuntimeValue, type FloatXArrayType } from "./types.js";
+import { type RuntimeNumber, RuntimeTensor, type RuntimeString, RuntimeChar, type RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeClassInstance, RuntimeComplexNumber, RuntimeDummyHandle, RuntimeGraphicsHandle, RuntimeStructArray, RuntimeSparseMatrix, RuntimeDictionary, type RuntimeValue } from "./types.js";
 export declare const RTV: {
     num(value: number): RuntimeNumber;
-    tensor(data: FloatXArrayType | number[], shape: number[], imag?: FloatXArrayType | number[]): RuntimeTensor;
-    /** Fast tensor constructor — data must be FloatXArray, shape already normalized (no trailing singletons). */
-    tensorRaw(data: FloatXArrayType, shape: number[]): RuntimeTensor;
+    tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
+    /** Fast tensor constructor — data must be Float64Array, shape already normalized (no trailing singletons). */
+    tensorRaw(data: Float64Array, shape: number[]): RuntimeTensor;
     /** Create a scalar tensor (1x1) */
     scalar(value: number): RuntimeNumber;
     /** Create a row vector [1 x n] */
@@ -15,7 +15,7 @@ export declare const RTV: {
     /** Create a column vector [n x 1] */
     col(data: number[], imag?: number[]): RuntimeTensor;
     /** Create a matrix from row-major data */
-    matrix(rows: number, cols: number, data: number[] | FloatXArrayType, imag?: number[] | FloatXArrayType): RuntimeTensor;
+    matrix(rows: number, cols: number, data: number[] | Float64Array, imag?: number[] | Float64Array): RuntimeTensor;
     string(value: string): RuntimeString;
     char(value: string): RuntimeChar;
     logical(value: boolean): RuntimeLogical;

package/dist-lib/numbl-core/runtime/cow.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Refcount-driven copy-on-write helpers.
+ *
+ * The lvalue write path uses these to make sure the chain from the env
+ * root to the leaf is uniquely owned before mutation: at each level, if
+ * the container is shared (`isShared`), it's cloned and the clone is
+ * rebound in the parent. After the chain is unique, in-place mutation
+ * at the leaf is observable only to the LHS variable.
+ */
+import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
+/** Return a fresh wrapper that shadows `v`'s contents but has rc=0
+ *  (modulo scope adoption from the constructor). The new wrapper holds
+ *  its own copy of the underlying buffers (for tensors) or its own
+ *  fields/data array (for containers). Refs to child values are
+ *  shared with the original — child wrappers get incref'd by the new
+ *  container's constructor. Caller is responsible for binding the
+ *  fresh wrapper into the parent slot.
+ *
+ *  Returns the original value unchanged for kinds that don't need to
+ *  be copied (handle-class instances, primitives) — the caller can
+ *  `=== v` test if the copy was a no-op. */
+export declare function cowCopy(v: RuntimeValue): RuntimeValue;
+/** If `v` is shared (rc-driven), return a fresh non-shared copy;
+ *  otherwise return `v` unchanged. The new wrapper has refcount 0
+ *  (or 1 if the active scope adopts it via the constructor); the
+ *  caller must bind it into the parent slot to keep it alive.
+ *
+ *  Returns the original `v` for handle-class instances and primitives —
+ *  callers can `result === v` test to detect a no-op. */
+export declare function cowIfShared(v: RuntimeValue): RuntimeValue;
+export { isShared } from "./refcount.js";
+export type { RefcountRuntime };

package/dist-lib/numbl-core/runtime/index.d.ts

@@ -1,7 +1,8 @@
-export type { RuntimeValue, RuntimeTensor, RuntimeString, RuntimeLogical, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
+export type { RuntimeValue, RuntimeString, RuntimeLogical } from "./types.js";
+export { RuntimeTensor, RuntimeCell, RuntimeStruct, RuntimeFunction, RuntimeDictionary, } from "./types.js";
 export { RuntimeError, CancellationError, offsetToLine, offsetToColumn, } from "./error.js";
 export type { CallFrame } from "./error.js";
-export { tensorSize2D, numel, colMajorIndex, shareRuntimeValue, } from "./utils.js";
+export { tensorSize2D, numel, colMajorIndex } from "./utils.js";
 export { toNumber, toBool, toString } from "./convert.js";
 export { valuesAreEqual } from "./compare.js";
 export { displayValue } from "./display.js";

package/dist-lib/numbl-core/runtime/indexing.d.ts

@@ -2,9 +2,14 @@
  * Indexing, struct field access, range creation, and tensor concatenation.
  */
 import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
+/** Runtime surface needed by index-store mutations. The full Runtime
+ *  class satisfies this structurally. */
+type StoreRuntime = RefcountRuntime;
 /** Sentinel marker for colon (:) indexing — means "all indices in this dimension" */
 export declare const COLON_INDEX: RuntimeValue;
 /** Index into a value: v(i1, i2, ...) */
 export declare function indexIntoRTValue(base: RuntimeValue, indices: RuntimeValue[]): RuntimeValue;
 /** Store into indexed position: base(indices) = rhs — uses copy-on-write for shared data */
-export declare function storeIntoRTValueIndex(base: RuntimeValue, indices: RuntimeValue[], rhs: RuntimeValue, parenAssign?: boolean): RuntimeValue;
+export declare function storeIntoRTValueIndex(base: RuntimeValue, indices: RuntimeValue[], rhs: RuntimeValue, parenAssign?: boolean, rt?: StoreRuntime): RuntimeValue;
+export {};