numbl 0.3.0 → 0.4.0

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

@@ -11,6 +11,7 @@
  * runtimeDispatch.ts, and helper types/utilities in runtimeHelpers.ts.
  */
 import { type RuntimeValue, type RuntimeLogical, type RuntimeTensor, type RuntimeStruct, type RuntimeString, type RuntimeFunction, RuntimeError, type CallFrame } from "../runtime/index.js";
+import { RefScope } from "./refcount.js";
 import { RuntimeChar, RuntimeCell, type RuntimeComplexNumber, type RuntimeClassInstance } from "../runtime/types.js";
 import { type ItemType } from "../lowering/itemTypes.js";
 import type { PlotInstruction } from "../../graphics/types.js";
@@ -22,9 +23,21 @@ export declare class Runtime {
     private options;
     private initialVariableValues?;
     outputLines: string[];
+    /** Stack of in-progress output-capture buffers. While non-empty,
+     *  `output()` appends to the top buffer instead of emitting, so a
+     *  speculative JIT attempt's side effects can be committed on success
+     *  or discarded on bail (preventing duplicated output when the
+     *  interpreter re-runs the same code). */
+    private outputCaptureStack;
     plotInstructions: PlotInstruction[];
     variableValues: Record<string, RuntimeValue>;
     holdState: boolean;
+    tiledLayoutState: {
+        rows: number;
+        cols: number;
+        mode: "fixed" | "flow" | "vertical" | "horizontal";
+        count: number;
+    } | null;
     private cancelFlag;
     $line: number;
     $file: string | null;
@@ -37,12 +50,12 @@ export declare class Runtime {
     END: symbol;
     RTV: {
         num(value: number): import("../runtime/types.js").RuntimeNumber;
-        tensor(data: import("../runtime/types.js").FloatXArrayType | number[], shape: number[], imag?: import("../runtime/types.js").FloatXArrayType | number[]): RuntimeTensor;
-        tensorRaw(data: import("../runtime/types.js").FloatXArrayType, shape: number[]): RuntimeTensor;
+        tensor(data: Float64Array | number[], shape: number[], imag?: Float64Array | number[]): RuntimeTensor;
+        tensorRaw(data: Float64Array, shape: number[]): RuntimeTensor;
         scalar(value: number): import("../runtime/types.js").RuntimeNumber;
         row(data: number[], imag?: number[]): RuntimeTensor;
         col(data: number[], imag?: number[]): RuntimeTensor;
-        matrix(rows: number, cols: number, data: number[] | import("../runtime/types.js").FloatXArrayType, imag?: number[] | import("../runtime/types.js").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;
@@ -60,8 +73,19 @@ export declare class Runtime {
             value: RuntimeValue;
         }>, keyType?: string, valueType?: string): import("../runtime/types.js").RuntimeDictionary;
     };
-    private persistentStore;
+    persistentStore: Map<string, Map<string, RuntimeValue>>;
     $g: Record<string, RuntimeValue>;
+    /** Active per-statement transient scope. New refcounted values are
+     *  auto-adopted into this scope (rc 0→1) on construction so they
+     *  survive long enough to be bound somewhere; on scope drain at end
+     *  of statement, anything still held only by the scope is decref'd
+     *  to 0 and destroyed. Null when no statement is in flight. */
+    currentScope: RefScope | null;
+    /** When true, `decref` on a zero count throws (loud at the
+     *  underflow site rather than silently leaking). On by default — the
+     *  refcount-driven COW system relies on accurate refcounts to make
+     *  correct mutate-vs-copy decisions. */
+    strictRefcount: boolean;
     activeAccessors: Set<string>;
     resolveClassMethod: ((className: string, methodName: string) => ((...args: any[]) => any) | null) | null;
     getClassParent: ((className: string) => string | null) | null;
@@ -86,7 +110,6 @@ export declare class Runtime {
     system?: SystemAdapter;
     builtins: Record<string, (nargout: number, args: unknown[]) => unknown>;
     customBuiltins: Record<string, (nargout: number, args: unknown[]) => unknown>;
-    jitHelpers: Record<string, any> | null;
     compileSpecialized: ((name: string, argTypes: ItemType[], callSite: CallSite) => ((...args: any[]) => any) | null) | null;
     evalLocalCallback: ((code: string, initialVars: Record<string, RuntimeValue>, onOutput: (text: string) => void, fileName?: string) => {
         returnValue: unknown;
@@ -112,6 +135,10 @@ export declare class Runtime {
     constructor(options: ExecOptions, initialVariableValues?: Record<string, RuntimeValue> | undefined);
     /** Throw CancellationError if the cancel flag has been set. */
     checkCancel(): void;
+    /** Run `fn` with a fresh `RefScope` as `this.currentScope`. On return,
+     *  every value adopted into the scope is decref'd. Used by `execStmt`
+     *  to bound the lifetime of expression transients to one statement. */
+    withScope<T>(fn: () => T): T;
     private initBuiltins;
     profileEnter(key: string): void;
     profileLeave(): void;
@@ -136,6 +163,16 @@ export declare class Runtime {
     getJitCompileTimeMs(): number;
     getDispatchUnknownCounts(): Record<string, number>;
     output(text: string): void;
+    /** Begin buffering output for a speculative execution attempt.
+     *  Pair with exactly one `commitOutputCapture()` or
+     *  `discardOutputCapture()`. */
+    beginOutputCapture(): void;
+    /** Emit the buffered output (to the parent capture frame if nested,
+     *  else to the real sink) — call when the attempt succeeded. */
+    commitOutputCapture(): void;
+    /** Drop the buffered output — call when the attempt bailed, so a
+     *  subsequent re-run is the only thing that emits. */
+    discardOutputCapture(): void;
     error(message: string): RuntimeError;
     annotateError(e: unknown): void;
     wrapError(e: unknown): RuntimeStruct;
@@ -146,7 +183,6 @@ export declare class Runtime {
     lg(v: boolean): RuntimeLogical;
     /** Scalar power that returns complex for negative base with fractional exponent */
     pow(a: number, b: number): number | RuntimeComplexNumber;
-    share(v: unknown): RuntimeValue;
     get displayResults(): boolean;
     displayResult(v: unknown): void;
     displayAssign(name: string, v: unknown): void;
@@ -270,68 +306,8 @@ export declare class Runtime {
     memberChainAssign(base: unknown, names: string[], rhs: unknown): unknown;
     narginchk(actualNargin: unknown, minArgs: unknown, maxArgs: unknown): void;
     nargoutchk(actualNargout: unknown, minArgs: unknown, maxArgs: unknown): void;
-    plot_instr(instr: {
-        type: "set_figure_handle";
-        handle: unknown;
-    } | {
-        type: "plot";
-        x: unknown;
-        y: unknown;
-    } | {
-        type: "set_hold";
-        value: unknown;
-    } | {
-        type: "close";
-    } | {
-        type: "close_all";
-    } | {
-        type: "clf";
-    } | {
-        type: "set_subplot";
-        rows: unknown;
-        cols: unknown;
-        index: unknown;
-    } | {
-        type: "set_sgtitle";
-        text: unknown;
-    } | {
-        type: "set_grid";
-        value: unknown;
-    }): void;
+    /** Read the hold state, for `ishold()` queries. */
     ishold(): RuntimeValue;
-    plot_call(args: RuntimeValue[]): void;
-    plot3_call(args: RuntimeValue[]): void;
-    surf_call(args: RuntimeValue[]): void;
-    scatter_call(args: RuntimeValue[]): void;
-    imagesc_call(args: RuntimeValue[]): void;
-    pcolor_call(args: RuntimeValue[]): void;
-    contour_call(args: RuntimeValue[], filled: boolean): void;
-    mesh_call(args: RuntimeValue[]): void;
-    bar_call(args: RuntimeValue[]): void;
-    barh_call(args: RuntimeValue[]): void;
-    bar3_call(args: RuntimeValue[]): void;
-    bar3h_call(args: RuntimeValue[]): void;
-    stairs_call(args: RuntimeValue[]): void;
-    errorbar_call(args: RuntimeValue[]): void;
-    semilogx_call(args: RuntimeValue[]): void;
-    semilogy_call(args: RuntimeValue[]): void;
-    loglog_call(args: RuntimeValue[]): void;
-    area_call(args: RuntimeValue[]): void;
-    fplot_call(args: RuntimeValue[]): void;
-    fplot3_call(args: RuntimeValue[]): void;
-    scatter3_call(args: RuntimeValue[]): void;
-    histogram_call(args: RuntimeValue[]): void;
-    histogram2_call(args: RuntimeValue[]): void;
-    boxchart_call(args: RuntimeValue[]): void;
-    swarmchart_call(args: RuntimeValue[]): void;
-    swarmchart3_call(args: RuntimeValue[]): void;
-    piechart_call(args: RuntimeValue[]): void;
-    donutchart_call(args: RuntimeValue[]): void;
-    heatmap_call(args: RuntimeValue[]): void;
-    streamline_call(args: RuntimeValue[]): RuntimeValue;
-    stream2_call(args: RuntimeValue[]): RuntimeValue;
-    view_call(args: RuntimeValue[]): void;
-    legend_call(args: RuntimeValue[]): void;
     drawnow(): void;
     pause(seconds: unknown): void;
     readInput(prompt: string): string;

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

@@ -4,12 +4,12 @@
  * Standalone functions that take the Runtime instance as the first parameter.
  * Handles function/class dispatch, arrayfun/cellfun/bsxfun, and subsref/subsasgn.
  */
-import { type RuntimeValue, type RuntimeLogical, type RuntimeFunction } from "../runtime/index.js";
+import { type RuntimeValue, type RuntimeLogical, RuntimeFunction } from "../runtime/index.js";
 import type { Runtime } from "./runtime.js";
 export declare function getFuncHandle(name: string): RuntimeFunction;
 export declare function makeUserFuncHandle(jsFn: (...args: unknown[]) => unknown, nargin?: number): RuntimeFunction;
 export declare function isa(rt: Runtime, value: unknown, classNameArg: unknown): RuntimeLogical;
-export declare function callSuperConstructor(target: unknown, superInstance: unknown): RuntimeValue;
+export declare function callSuperConstructor(target: unknown, superInstance: unknown, rt?: Runtime): RuntimeValue;
 export declare function createClassInstance(_rt: Runtime, className: string, propertyNames: string[], defaults?: Record<string, unknown>, isHandleClass?: boolean): RuntimeValue;
 export declare function dispatch(rt: Runtime, name: string, nargout: number, args: unknown[], targetClassName?: string): unknown;
 /** Direct builtin call — skips local/workspace/registry lookup. */

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

@@ -20,9 +20,9 @@ export declare function indexStore(rt: Runtime, base: unknown, indices: unknown[
 /**
  * Cell-indexed assignment (curly braces).
  */
-export declare function indexCellStore(base: unknown, indices: unknown[], rhs: unknown): unknown;
+export declare function indexCellStore(base: unknown, indices: unknown[], rhs: unknown, rt?: import("./refcount.js").RefcountRuntime): unknown;
 /**
  * Multi-output assignment to cell elements: [c{idx}] = func()
  * Distributes individual results to individual cell positions.
  */
-export declare function multiOutputCellAssign(base: unknown, indices: unknown, results: unknown[]): unknown;
+export declare function multiOutputCellAssign(base: unknown, indices: unknown, results: unknown[], rt?: import("./refcount.js").RefcountRuntime): unknown;

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

@@ -7,7 +7,7 @@ export declare function getMember(rt: Runtime, base: unknown, name: string): unk
 export declare function getMemberDynamic(base: unknown, nameExpr: unknown): RuntimeValue;
 export declare function getMemberOrEmpty(base: unknown, name: string): RuntimeValue;
 export declare function setMemberReturn(rt: Runtime, base: unknown, name: string, rhs: unknown): unknown;
-export declare function setMemberDynamicReturn(base: unknown, nameExpr: unknown, rhs: unknown): RuntimeValue;
+export declare function setMemberDynamicReturn(rt: Runtime, base: unknown, nameExpr: unknown, rhs: unknown): RuntimeValue;
 /**
  * Call a user-defined subsref method on a class instance.
  * Constructs S = struct('type', '.', 'subs', name) for each name in the chain.

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

@@ -100,6 +100,7 @@ export declare function swarmchart3Call(plotInstructions: PlotInstruction[], arg
 export declare function piechartCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function donutchartCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function heatmapCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
+export declare function quiverCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function legendCall(plotInstructions: PlotInstruction[], args: RuntimeValue[]): void;
 export declare function drawnow(plotInstructions: PlotInstruction[], options: ExecOptions): void;
 export declare function pause(seconds: unknown): void;

package/dist-lib/numbl-core/runtime/struct-access.d.ts

@@ -2,5 +2,6 @@
  * Struct and class instance field access.
  */
 import { type RuntimeValue } from "./types.js";
+import { type RefcountRuntime } from "./refcount.js";
 export declare function getRTValueField(base: RuntimeValue, field: string): RuntimeValue;
-export declare function setRTValueField(base: RuntimeValue, field: string, value: RuntimeValue): RuntimeValue;
+export declare function setRTValueField(base: RuntimeValue, field: string, value: RuntimeValue, rt?: RefcountRuntime): RuntimeValue;

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

@@ -1,6 +1,5 @@
+import { Refcounted, type RefcountRuntime } from "./refcount.js";
 export declare const USE_FLOAT32: boolean;
-export declare const FloatXArray: Float32ArrayConstructor | Float64ArrayConstructor;
-export type FloatXArrayType = Float32Array | Float64Array;
 export type RuntimeValue = number | boolean | string | RuntimeTensor | RuntimeChar | RuntimeCell | RuntimeStruct | RuntimeFunction | RuntimeClassInstance | RuntimeComplexNumber | RuntimeDummyHandle | RuntimeGraphicsHandle | RuntimeStructArray | RuntimeClassInstanceArray | RuntimeSparseMatrix | RuntimeDictionary;
 export type RuntimeNumber = number;
 export type RuntimeLogical = boolean;
@@ -22,104 +21,160 @@ export declare const isRuntimeClassInstanceArray: (value: RuntimeValue) => value
 export declare const isRuntimeSparseMatrix: (value: RuntimeValue) => value is RuntimeSparseMatrix;
 export declare const isRuntimeDictionary: (value: RuntimeValue) => value is RuntimeDictionary;
 export declare const kstr: (value: RuntimeValue) => string;
-export type RuntimeTensor = {
-    kind: "tensor";
-    data: FloatXArrayType;
-    imag?: FloatXArrayType;
+export declare class RuntimeTensor extends Refcounted {
+    readonly kind: "tensor";
+    data: Float64Array;
+    imag: Float64Array | undefined;
     shape: number[];
-    /** When true, this tensor represents a logical (boolean) array from comparisons/logical ops. */
-    _isLogical?: boolean;
-    /** Reference count for copy-on-write. When > 1, data is shared and must be copied before mutation. */
-    _rc: number;
-};
-export type RuntimeChar = {
-    kind: "char";
+    /** When true, this tensor represents a logical (boolean) array from
+     *  comparisons/logical ops. */
+    _isLogical: boolean | undefined;
+    constructor(data: Float64Array, shape: number[], imag?: Float64Array, _isLogical?: boolean);
+}
+export declare class RuntimeChar extends Refcounted {
+    readonly kind: "char";
     value: string;
-    /** Optional shape for multi-row char arrays. If absent, shape is [1, value.length].
-     *  For multi-row arrays, value contains all rows concatenated (each row is shape[1] chars). */
-    shape?: number[];
-};
-export type RuntimeCell = {
-    kind: "cell";
+    /** Optional shape for multi-row char arrays. If absent, shape is
+     *  [1, value.length]. For multi-row arrays, value contains all rows
+     *  concatenated (each row is shape[1] chars). */
+    shape: number[] | undefined;
+    constructor(value: string, shape?: number[]);
+}
+export declare class RuntimeCell extends Refcounted {
+    readonly kind: "cell";
     data: RuntimeValue[];
     shape: number[];
-    /** Reference count for copy-on-write. When > 1, data is shared and must be copied before mutation. */
-    _rc: number;
-};
-export type RuntimeStruct = {
-    kind: "struct";
+    constructor(data: RuntimeValue[], shape: number[]);
+    /** Replace element at idx, decref-old / incref-new. Caller resizes the
+     *  shape if necessary; this method does not touch shape. */
+    bindElement(rt: RefcountRuntime, idx: number, value: RuntimeValue): void;
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeStruct extends Refcounted {
+    readonly kind: "struct";
     fields: Map<string, RuntimeValue>;
-};
-export type RuntimeFunction = {
-    kind: "function";
+    constructor(fields: Map<string, RuntimeValue>);
+    /** Set/replace a field value, decref-old / incref-new. */
+    bindField(rt: RefcountRuntime, name: string, value: RuntimeValue): void;
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeFunction extends Refcounted {
+    readonly kind: "function";
     name: string;
     /** For closures: captured variables */
     captures: RuntimeValue[];
     /** The underlying callable — either a builtin or user-defined function name */
     impl: "builtin" | "user";
     /** For anonymous functions and user function handles: the underlying JS closure */
-    jsFn?: (...args: unknown[]) => unknown;
+    jsFn: ((...args: unknown[]) => unknown) | undefined;
     /** When true, jsFn expects nargout as its first argument */
-    jsFnExpectsNargout?: boolean;
+    jsFnExpectsNargout: boolean | undefined;
     /** Number of input parameters (for nargin(handle)) */
-    nargin?: number;
-};
-export type RuntimeClassInstance = {
-    kind: "class_instance";
+    nargin: number | undefined;
+    /** Cleanup hook fired by `_destroy`. Anonymous functions use this to
+     *  decref values held in their captured environment snapshot, since
+     *  those refs live in the JS closure (not in `captures`). */
+    releaseExtra: ((rt: RefcountRuntime) => void) | undefined;
+    /** For anonymous-function snapshots: the captured environment, made
+     *  visible to the alias sweep so a tensor stored both here and in
+     *  the parent env triggers copy-on-write on parent-side mutations.
+     *  (Only the structural shape `{ vars, parent }` is needed; typed
+     *  loosely to avoid a runtime↔interpreter circular import.) */
+    capturedEnv: {
+        vars: Map<string, RuntimeValue>;
+        parent?: unknown;
+    } | undefined;
+    /** The defining AST of this handle — an `AnonFunc` (`@(p) body`) or
+     *  `FuncHandle` (`@name`) parser Expr. Lets the JIT recover the
+     *  handle's source so a capture-free handle that crosses a
+     *  compile boundary (a loop input / call arg) can be inlined as an
+     *  in-scope handle constant. Typed loosely (parser Expr) to avoid a
+     *  runtime→parser layering dependency; consumers cast. Undefined for
+     *  handles created by paths that don't set it (e.g. builtins). */
+    handleAst: unknown;
+    /** Source file the handle was defined in. The inliner only reuses a
+     *  handle's AST when this matches the file being compiled, so a
+     *  named-handle target (`@foo`) resolves to the same `foo` it did at
+     *  definition (file-local functions can shadow across files). */
+    handleDefFile: string | undefined;
+    constructor(name: string, impl: "builtin" | "user", captures: RuntimeValue[], jsFn?: (...args: unknown[]) => unknown, jsFnExpectsNargout?: boolean, nargin?: number);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeClassInstance extends Refcounted {
+    readonly kind: "class_instance";
     className: string;
     fields: Map<string, RuntimeValue>;
     /** True if this class inherits from handle (reference semantics). */
     isHandleClass: boolean;
     /** For classes that inherit from built-in types (e.g. classdef Foo < double),
      *  stores the underlying built-in data. */
-    _builtinData?: RuntimeValue;
-};
+    _builtinData: RuntimeValue | undefined;
+    constructor(className: string, fields: Map<string, RuntimeValue>, isHandleClass: boolean, _builtinData?: RuntimeValue);
+    /** Set/replace a field value (handle-class in-place mutation), with
+     *  proper decref-old / incref-new bookkeeping. Used for handle-class
+     *  field assigns; value-class field assigns construct a new instance. */
+    bindField(rt: RefcountRuntime, name: string, value: RuntimeValue): void;
+    protected _destroy(rt: RefcountRuntime): void;
+}
 /** A 1-D array of class instances that all share the same class.
  *  Created by default horzcat/vertcat when the class doesn't overload them. */
-export type RuntimeClassInstanceArray = {
-    kind: "class_instance_array";
+export declare class RuntimeClassInstanceArray extends Refcounted {
+    readonly kind: "class_instance_array";
     className: string;
     elements: RuntimeClassInstance[];
-};
-export type RuntimeComplexNumber = {
-    kind: "complex_number";
+    constructor(className: string, elements: RuntimeClassInstance[]);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+export declare class RuntimeComplexNumber extends Refcounted {
+    readonly kind: "complex_number";
     re: number;
     im: number;
-};
-export type RuntimeDummyHandle = {
-    kind: "dummy_handle";
-};
+    constructor(re: number, im: number);
+}
+export declare class RuntimeDummyHandle extends Refcounted {
+    readonly kind: "dummy_handle";
+    constructor();
+}
 /** Handle to a graphics object (e.g. surface returned by pcolor) with a mutable trace reference. */
-export type RuntimeGraphicsHandle = {
-    kind: "graphics_handle";
+export declare class RuntimeGraphicsHandle extends Refcounted {
+    readonly kind: "graphics_handle";
     _trace: Record<string, unknown>;
     _traceType: string;
-};
-/** A 1-D array of structs that all share the same field names. **/
-export type RuntimeStructArray = {
-    kind: "struct_array";
+    constructor(_trace: Record<string, unknown>, _traceType: string);
+}
+/** A 1-D array of structs that all share the same field names. */
+export declare class RuntimeStructArray extends Refcounted {
+    readonly kind: "struct_array";
     fieldNames: string[];
     elements: RuntimeStruct[];
-};
-/** Sparse matrix in CSC (Compressed Sparse Column) format, matching MATLAB's internal representation. */
-export type RuntimeSparseMatrix = {
-    kind: "sparse_matrix";
+    constructor(fieldNames: string[], elements: RuntimeStruct[]);
+    protected _destroy(rt: RefcountRuntime): void;
+}
+/** Sparse matrix in CSC (Compressed Sparse Column) format, matching MATLAB's
+ *  internal representation. */
+export declare class RuntimeSparseMatrix extends Refcounted {
+    readonly kind: "sparse_matrix";
     m: number;
     n: number;
     ir: Int32Array;
     jc: Int32Array;
     pr: Float64Array;
-    pi?: Float64Array;
-    _rc: number;
-};
+    pi: Float64Array | undefined;
+    constructor(m: number, n: number, ir: Int32Array, jc: Int32Array, pr: Float64Array, pi?: Float64Array);
+}
 /** Dictionary mapping unique keys to values (MATLAB R2022b+). */
-export type RuntimeDictionary = {
-    kind: "dictionary";
+export declare class RuntimeDictionary extends Refcounted {
+    readonly kind: "dictionary";
     /** Entries keyed by a hash string of the RuntimeValue key, preserving insertion order. */
     entries: Map<string, {
         key: RuntimeValue;
         value: RuntimeValue;
     }>;
-    keyType?: string;
-    valueType?: string;
-};
+    keyType: string | undefined;
+    valueType: string | undefined;
+    constructor(entries?: Map<string, {
+        key: RuntimeValue;
+        value: RuntimeValue;
+    }>, keyType?: string, valueType?: string);
+    protected _destroy(rt: RefcountRuntime): void;
+}

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

@@ -1,7 +1,7 @@
 /**
- * Tensor shape/indexing utilities and copy-on-write helpers.
+ * Tensor shape/indexing utilities.
  */
-import { type RuntimeValue, type RuntimeTensor } from "./types.js";
+import { type RuntimeTensor } from "./types.js";
 /** Get 2D size (rows, cols) from shape, padding with 1s as needed.
  *  For N-D tensors (N>2), trailing dimensions are collapsed into cols,
  *  matching MATLAB's behavior when fewer subscripts than dimensions. */
@@ -14,9 +14,3 @@ export declare function colMajorIndex(row: number, col: number, rows: number): n
 export declare function ind2sub(shape: number[], idx: number): number[];
 /** Convert subscripts to linear index (column-major) */
 export declare function sub2ind(shape: number[], subs: number[]): number;
-/**
- * Share an RuntimeValue for assignment (COW): increments refcount on tensors/cells
- * so that mIndexStore knows to copy before mutating.
- * Returns a new wrapper object that shares the same underlying data.
- */
-export declare function shareRuntimeValue(v: RuntimeValue): RuntimeValue;

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

@@ -1,2 +1,2 @@
 /** Numbl version, used for JIT disk cache invalidation. */
-export declare const NUMBL_VERSION = "0.3.0";
+export declare const NUMBL_VERSION = "0.4.0";

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

@@ -10,7 +10,15 @@ export interface WorkspaceFile {
  * Bridge for loading native shared libraries (.so/.dll/.dylib).
  * Implemented outside numbl-core (e.g. via koffi in the CLI) since
  * native FFI is not available in browser environments.
+ *
+ * `koffi`, when present, exposes the root koffi module so the
+ * C-JIT executors can call its struct / alloc / encode / decode
+ * helpers. Browser deployments leave `koffi` undefined; the
+ * C-JIT executors decline (numbl falls back to JS-JIT).
  */
 export interface NativeBridge {
     load(libraryPath: string): unknown;
+    /** koffi root module — `require("koffi")`'s exports. Only the
+     *  C-JIT path consumes it. Optional so non-Node hosts can omit. */
+    koffi?: unknown;
 }