@nirs4all/methods 1.0.6

package/README.md

@@ -0,0 +1,135 @@
+# @nirs4all/methods — WebAssembly binding
+
+Browser + Node.js binding for **libn4m** (the `nirs4all-methods` portable
+PLS/NIRS engine), compiled via Emscripten. It is a **non-idiomatic function
+library**: raw typed arrays in, typed arrays out. Estimator ergonomics and the
+multi-component aggregation live in the separate `nirs4all-core` repo — not
+here. See [`INPUT_CONTRACT.md`](INPUT_CONTRACT.md) and
+[`examples/consume.mjs`](examples/consume.mjs).
+
+The package ships:
+
+- `n4m.wasm` — the libn4m C ABI compiled to WebAssembly (full engine).
+- `n4m.js` — Emscripten MODULARIZE/EXPORT_ES6 loader.
+- `dist/` — TypeScript wrappers (`Context`, `Config`, `Model`, `MethodResult`)
+  emitted from `src/`.
+
+## Build
+
+```bash
+# 1. Activate the Emscripten SDK.
+source /path/to/emsdk/emsdk_env.sh
+# 2. Configure + build the WASM preset (zero deps beyond Emscripten).
+cmake --preset emscripten
+cmake --build --preset emscripten --target n4m_wasm
+# Artifacts land in build/emscripten/bindings/js/{n4m.js,n4m.wasm}.
+
+# 3. Build the TypeScript wrapper for distribution:
+cd bindings/js && npm run build && npm run stage:wasm
+```
+
+## Smoke test (Node)
+
+```bash
+cd bindings/js
+npm test                 # PLS parity + API/generic/AOM/new-pack smokes
+node examples/consume.mjs # the downstream-consumption example
+```
+
+The smoke suite fits a SIMPLS PLS regression through the raw-pointer entrypoint,
+checks the public API and generic method path, exercises POP/AOM helpers, and
+gates the broad-model-pack additions (`ECR`, `O2PLS`, AOM Ridge/Stack,
+DataTwinning, SystematicCircular). The PLS smoke compares coefficients +
+predictions to a frozen native fixture (`test/parity_fixture.json`) at a 1e-9
+isolated band (achieved ~1e-16).
+
+## API surface
+
+```typescript
+import * as n4m from "@nirs4all/methods";
+
+await n4m.loadModule();
+console.log(n4m.version());     // "1.0.3+abi.2.0.0"
+console.log(n4m.abiVersion());  // [2, 0, 0]
+
+const rows = 40, cols = 6;
+const X = new Float64Array(rows * cols);   // row-major
+const y = new Float64Array(rows);
+// ... fill X, y ...
+
+const model = n4m.fitPls({ data: X, rows, cols },
+                         { data: y, rows, cols: 1 }, 3);
+const preds = n4m.predictPls(model, { data: X, rows, cols });
+
+const split = n4m.computeSplitIndices("KennardStone", { data: X, rows, cols }, null);
+// `computeSplit()` remains available when a compact train/test mask is enough.
+```
+
+`Context` / `Config` / `MethodResult` are also exported for the lower-level
+path. There is no idiomatic (sklearn-style) layer — that is intentional.
+
+## Build options
+
+The CMake `emscripten` preset sets:
+
+- `WASM_BIGINT=1` — int64 ABI params are exchanged as `BigInt`.
+- `MODULARIZE=1`, `EXPORT_ES6=1` — the module factory is the default export.
+- `ALLOW_MEMORY_GROWTH=1`, `INITIAL_MEMORY=64MB`, `MAXIMUM_MEMORY=2GB`.
+- `EXPORTED_FUNCTIONS` — driven by `cpp/abi/expected_symbols_linux.txt`; every
+  `n4m_*` symbol that ships in `libn4m` is exported here as `_n4m_*` (the full
+  engine surface), plus `_malloc`/`_free` and the raw-pointer PLS shims.
+
+## Generic method path (enabled)
+
+Two ways to reach the engine, both bit-exact vs native:
+
+- **Raw-pointer shims** — `fitPls` / `predictPls` and the other shims in
+  `src/wasm_entry.c` (e.g. `n4m_wasm_pls_fit_legacy`): typed arrays in, typed
+  arrays out, no handle bookkeeping.
+- **Generic `MethodResult.run`** — call **any** of the ~188 `method_result`
+  producers by symbol, passing `n4m_matrix_view_t*` arguments built from JS.
+
+The generic path **works** and is regression-tested (`test/run_generic_method.mjs`
+fits `n4m_estimators_sparse_simpls_fit` and the generic `n4m_model_fit` and matches the raw
+`n4m_estimators_pls_fit` oracle byte-for-byte). The previous "Emscripten miscompiles
+matrix-view parameters" diagnosis was **wrong**: the bug was the TS `ccall` layer
+passing a JS `number` for the `int64_t` `rows`/`cols` fields. Marshalling those
+dims as `BigInt` under `WASM_BIGINT` (`ffi.ts` / `makeMatrixView`) made the deep
+view-pointer path byte-correct — see the note at the top of `src/wasm_entry.c`.
+
+```js
+import { loadModule, Context, Config, MethodResult } from "@nirs4all/methods";
+await loadModule();
+const ctx = new Context(), cfg = new Config();
+const X = makeMatrixView(rows, cols, dataF64);   // row-major Float64Array
+const res = MethodResult.run("n4m_estimators_sparse_simpls_fit", ctx, cfg, [X /* , Y */]);
+const coef = res.matrix("coefficients");          // typed array + shape
+res.destroy(); cfg.destroy(); ctx.destroy();
+```
+
+## Layout
+
+```
+bindings/js/
+├── CMakeLists.txt        # Emscripten target wired into the project preset
+├── package.json          # @nirs4all/methods
+├── tsconfig.json
+├── INPUT_CONTRACT.md      # the raw-array input contract (copied by nirs4all-lite)
+├── src/
+│   ├── wasm_entry.c      # ABI header pull-in + raw-pointer PLS shims
+│   ├── ffi.ts            # Module loader + matrix-view helpers
+│   ├── types.ts          # Mirrored C enums + error class
+│   ├── context.ts        # Context wrapper
+│   ├── config.ts         # Config wrapper
+│   ├── model.ts          # Model fit / predict (raw-pointer path)
+│   ├── methodResult.ts   # Universal n4m_method_result_t wrapper
+│   └── index.ts          # Public barrel
+├── examples/
+│   └── consume.mjs       # downstream-consumption example
+└── test/
+    ├── run_smoke.mjs     # Node PLS smoke + parity vs native Python
+    ├── run_api.mjs
+    ├── run_generic_method.mjs
+    ├── run_pop_aom.mjs
+    └── run_new_pack.mjs  # broad-model-pack smoke
+```

package/dist/config.d.ts

@@ -0,0 +1,16 @@
+import { Algorithm, Deflation, Solver } from "./types.js";
+/** RAII wrapper around n4m_config_t. */
+export declare class Config {
+    private _ptr;
+    private constructor();
+    static create(): Config;
+    get handle(): number;
+    destroy(): void;
+    setNComponents(k: number): void;
+    setAlgorithm(a: Algorithm): void;
+    setSolver(solver: Solver): void;
+    setDeflation(d: Deflation): void;
+    setCenterX(on: boolean): void;
+    setCenterY(on: boolean): void;
+    setStoreScores(on: boolean): void;
+}

package/dist/config.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: CECILL-2.1
+import { checkStatus, getModule } from "./ffi.js";
+/** RAII wrapper around n4m_config_t. */
+export class Config {
+    _ptr;
+    constructor(ptr) {
+        this._ptr = ptr;
+    }
+    static create() {
+        const m = getModule();
+        const out = m._malloc(4);
+        try {
+            const status = m.ccall("n4m_config_create", "number", ["number"], [out]);
+            checkStatus(status);
+            return new Config(m.getValue(out, "i32"));
+        }
+        finally {
+            m._free(out);
+        }
+    }
+    get handle() {
+        return this._ptr;
+    }
+    destroy() {
+        if (this._ptr === 0)
+            return;
+        getModule().ccall("n4m_config_destroy", null, ["number"], [this._ptr]);
+        this._ptr = 0;
+    }
+    setNComponents(k) {
+        const s = getModule().ccall("n4m_config_set_n_components", "number", ["number", "number"], [this._ptr, k]);
+        checkStatus(s);
+    }
+    setAlgorithm(a) {
+        const s = getModule().ccall("n4m_config_set_algorithm", "number", ["number", "number"], [this._ptr, a]);
+        checkStatus(s);
+    }
+    setSolver(solver) {
+        const s = getModule().ccall("n4m_config_set_solver", "number", ["number", "number"], [this._ptr, solver]);
+        checkStatus(s);
+    }
+    setDeflation(d) {
+        const s = getModule().ccall("n4m_config_set_deflation", "number", ["number", "number"], [this._ptr, d]);
+        checkStatus(s);
+    }
+    setCenterX(on) {
+        const s = getModule().ccall("n4m_config_set_center_x", "number", ["number", "number"], [this._ptr, on ? 1 : 0]);
+        checkStatus(s);
+    }
+    setCenterY(on) {
+        const s = getModule().ccall("n4m_config_set_center_y", "number", ["number", "number"], [this._ptr, on ? 1 : 0]);
+        checkStatus(s);
+    }
+    setStoreScores(on) {
+        const s = getModule().ccall("n4m_config_set_store_scores", "number", ["number", "number"], [this._ptr, on ? 1 : 0]);
+        checkStatus(s);
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,18 @@
+/** RAII wrapper around n4m_context_t. */
+export declare class Context {
+    private _ptr;
+    private constructor();
+    /** Create a new context. Throws N4mError on failure. */
+    static create(): Context;
+    /** Returns the raw `n4m_context_t*` pointer (handle). */
+    get handle(): number;
+    /** Free the context. Safe to call multiple times. */
+    destroy(): void;
+    /** Set the RNG seed used by stochastic algorithms.
+     *
+     *  n4m_context_set_seed takes a uint64_t. Under WASM_BIGINT=1 the i64 slot
+     *  must be marshalled as 'i64' with a BigInt — passing a JS number loses
+     *  precision above 2^53 and throws "Cannot convert N to a BigInt" on emsdk
+     *  >= 5.0.7 (same class of bug as the matrix-view dims; see ffi.ts). */
+    setSeed(seed: bigint | number): void;
+}

package/dist/context.js

@@ -0,0 +1,44 @@
+// SPDX-License-Identifier: CECILL-2.1
+import { checkStatus, getModule } from "./ffi.js";
+/** RAII wrapper around n4m_context_t. */
+export class Context {
+    _ptr;
+    constructor(ptr) {
+        this._ptr = ptr;
+    }
+    /** Create a new context. Throws N4mError on failure. */
+    static create() {
+        const m = getModule();
+        const out = m._malloc(4);
+        try {
+            const status = m.ccall("n4m_context_create", "number", ["number"], [out]);
+            checkStatus(status);
+            const ptr = m.getValue(out, "i32");
+            return new Context(ptr);
+        }
+        finally {
+            m._free(out);
+        }
+    }
+    /** Returns the raw `n4m_context_t*` pointer (handle). */
+    get handle() {
+        return this._ptr;
+    }
+    /** Free the context. Safe to call multiple times. */
+    destroy() {
+        if (this._ptr === 0)
+            return;
+        getModule().ccall("n4m_context_destroy", null, ["number"], [this._ptr]);
+        this._ptr = 0;
+    }
+    /** Set the RNG seed used by stochastic algorithms.
+     *
+     *  n4m_context_set_seed takes a uint64_t. Under WASM_BIGINT=1 the i64 slot
+     *  must be marshalled as 'i64' with a BigInt — passing a JS number loses
+     *  precision above 2^53 and throws "Cannot convert N to a BigInt" on emsdk
+     *  >= 5.0.7 (same class of bug as the matrix-view dims; see ffi.ts). */
+    setSeed(seed) {
+        const status = getModule().ccall("n4m_context_set_seed", "number", ["number", "i64"], [this._ptr, BigInt(seed)]);
+        checkStatus(status, this._ptr);
+    }
+}

package/dist/ffi.d.ts

@@ -0,0 +1,45 @@
+/** Loose typing of the Emscripten module factory's runtime instance. */
+export interface EmModule {
+    HEAPU8: Uint8Array;
+    HEAP32: Int32Array;
+    HEAPF64: Float64Array;
+    _malloc(size: number): number;
+    _free(ptr: number): void;
+    ccall<T>(name: string, returnType: string | null, argTypes: string[], args: unknown[]): T;
+    cwrap<T extends Function>(name: string, returnType: string | null, argTypes: string[]): T;
+    UTF8ToString(ptr: number): string;
+    stringToUTF8(s: string, ptr: number, max: number): void;
+    lengthBytesUTF8(s: string): number;
+    getValue(ptr: number, type: string): number;
+    setValue(ptr: number, value: number, type: string): void;
+}
+/** Load and cache the Emscripten module. Call once at app startup. */
+export declare function loadModule(): Promise<EmModule>;
+export declare function getModule(): EmModule;
+export declare function checkStatus(status: number, ctxPtr?: number): void;
+export declare const MATRIX_VIEW_SIZE = 48;
+/** Allocate a matrix-view struct and copy `data` into the WASM heap.
+ *  Returns the view pointer; caller must `free()` it.
+ *
+ *  NOTE: n4m_matrix_view_init_rowmajor takes `int64_t rows, int64_t cols`.
+ *  The WASM module is built with `-s WASM_BIGINT=1`, so ccall marshals i64
+ *  args as BigInt — passing a plain JS number for these slots silently
+ *  corrupts the struct fields (rows/cols/strides become garbage, producing
+ *  ~1e32 numerics downstream) and on emsdk >= 5.0.7 throws
+ *  "TypeError: Cannot convert N to a BigInt". We therefore declare the two
+ *  dimension args as 'i64' and pass BigInt(...). The data/out/dtype slots
+ *  stay 32-bit. dtype defaults to N4M_DTYPE_F64 (= 1; see types.ts Dtype). */
+export declare function makeMatrixView(data: Float64Array, rows: number, cols: number, dtype?: number): {
+    viewPtr: number;
+    dataPtr: number;
+    free: () => void;
+};
+/** Read a core-owned `n4m_array_t*` (e.g. from n4m_model_get_array) into a
+ *  JS-owned Float64Array. Does NOT free the array — the caller must call
+ *  `n4m_array_free` afterwards. i64 view fields (rows @8, cols @16) are read
+ *  as BigInt under WASM_BIGINT and narrowed with Number(). */
+export declare function readArrayView(arrPtr: number): {
+    data: Float64Array;
+    rows: number;
+    cols: number;
+};

package/dist/ffi.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: CECILL-2.1
+//
+// Thin ccall/cwrap wrappers around the Emscripten module.
+import { Status, N4mError } from "./types.js";
+let _module = null;
+/** Load and cache the Emscripten module. Call once at app startup. */
+export async function loadModule() {
+    if (_module !== null)
+        return _module;
+    // n4m.js (the Emscripten loader) is staged into dist/ next to this module,
+    // so the package is self-contained (files: ["dist/"]). See package.json
+    // `stage:wasm`. The import path must stay relative to dist/ so the shipped
+    // package resolves the loader it bundles.
+    const factory = (await import("./n4m.js")).default;
+    _module = await factory({});
+    return _module;
+}
+export function getModule() {
+    if (_module === null) {
+        throw new Error("@nirs4all/methods not loaded — call await loadModule() first.");
+    }
+    return _module;
+}
+export function checkStatus(status, ctxPtr = 0) {
+    if (status === Status.OK)
+        return;
+    let msg = "";
+    if (ctxPtr !== 0) {
+        const m = getModule();
+        const cstr = m.ccall("n4m_context_last_error", "number", ["number"], [ctxPtr]);
+        if (cstr !== 0)
+            msg = m.UTF8ToString(cstr);
+    }
+    if (msg === "") {
+        const m = getModule();
+        const cstr = m.ccall("n4m_status_to_string", "number", ["number"], [status]);
+        if (cstr !== 0)
+            msg = m.UTF8ToString(cstr);
+    }
+    throw new N4mError(status, msg);
+}
+// ---- n4m_matrix_view_t layout (mirrors cpp/include/n4m/n4m.h) -----------
+//
+// struct {
+//     void*    data;       // 4 bytes (WASM is 32-bit; offset 0)
+//     int64_t  rows;       // 8 bytes (offset 8, aligned to 8)
+//     int64_t  cols;       // 8 bytes (offset 16)
+//     int64_t  row_stride; // 8 bytes (offset 24)
+//     int64_t  col_stride; // 8 bytes (offset 32)
+//     int32_t  dtype;      // 4 bytes (offset 40)
+//     int32_t  reserved0;  // 4 bytes (offset 44)
+// }; total = 48 bytes on WASM32 with the 8-byte alignment of int64_t.
+export const MATRIX_VIEW_SIZE = 48;
+/** Allocate a matrix-view struct and copy `data` into the WASM heap.
+ *  Returns the view pointer; caller must `free()` it.
+ *
+ *  NOTE: n4m_matrix_view_init_rowmajor takes `int64_t rows, int64_t cols`.
+ *  The WASM module is built with `-s WASM_BIGINT=1`, so ccall marshals i64
+ *  args as BigInt — passing a plain JS number for these slots silently
+ *  corrupts the struct fields (rows/cols/strides become garbage, producing
+ *  ~1e32 numerics downstream) and on emsdk >= 5.0.7 throws
+ *  "TypeError: Cannot convert N to a BigInt". We therefore declare the two
+ *  dimension args as 'i64' and pass BigInt(...). The data/out/dtype slots
+ *  stay 32-bit. dtype defaults to N4M_DTYPE_F64 (= 1; see types.ts Dtype). */
+export function makeMatrixView(data, rows, cols, dtype = 1 /* N4M_DTYPE_F64 */) {
+    const m = getModule();
+    const expected = rows * cols;
+    if (data.length !== expected) {
+        throw new Error(`matrix data length ${data.length} != rows*cols (${expected})`);
+    }
+    const bytes = Math.max(1, data.length) * 8;
+    const dataPtr = m._malloc(bytes);
+    if (data.length > 0) {
+        m.HEAPF64.set(data, dataPtr / 8);
+    }
+    const viewPtr = m._malloc(MATRIX_VIEW_SIZE);
+    const status = m.ccall("n4m_matrix_view_init_rowmajor", "number", ["number", "number", "i64", "i64", "number"], [viewPtr, dataPtr, BigInt(rows), BigInt(cols), dtype]);
+    if (status !== Status.OK) {
+        m._free(dataPtr);
+        m._free(viewPtr);
+        checkStatus(status);
+    }
+    return {
+        viewPtr,
+        dataPtr,
+        free: () => {
+            m._free(viewPtr);
+            m._free(dataPtr);
+        },
+    };
+}
+/** Read a core-owned `n4m_array_t*` (e.g. from n4m_model_get_array) into a
+ *  JS-owned Float64Array. Does NOT free the array — the caller must call
+ *  `n4m_array_free` afterwards. i64 view fields (rows @8, cols @16) are read
+ *  as BigInt under WASM_BIGINT and narrowed with Number(). */
+export function readArrayView(arrPtr) {
+    const m = getModule();
+    const vp = m._malloc(MATRIX_VIEW_SIZE);
+    try {
+        const st = m.ccall("n4m_array_view", "number", ["number", "number"], [arrPtr, vp]);
+        checkStatus(st);
+        const dataPtr = m.getValue(vp, "i32");
+        const rows = Number(m.getValue(vp + 8, "i64"));
+        const cols = Number(m.getValue(vp + 16, "i64"));
+        const n = rows * cols;
+        const data = new Float64Array(n);
+        if (n > 0) {
+            data.set(m.HEAPF64.subarray(dataPtr / 8, dataPtr / 8 + n));
+        }
+        return { data, rows, cols };
+    }
+    finally {
+        m._free(vp);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { loadModule, getModule, makeMatrixView, readArrayView } from "./ffi.js";
+export { Context } from "./context.js";
+export { Config } from "./config.js";
+export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices, type PlsModel, type FittedModel, type AomModel, type PopModel, type AomRidgeOptions, type AomStackOptions, type SplitKind, type SplitOptions, type SplitIndices } from "./model.js";
+export { ppCreate, ppFit, ppTransform, ppGetState, ppSetState, ppDestroy, type PpOperator, } from "./preprocessing.js";
+export { MethodResult } from "./methodResult.js";
+export { Status, Dtype, Algorithm, Solver, Deflation, N4mError, type Matrix, } from "./types.js";
+/** ABI / project version reported by the loaded WASM module. */
+export declare function version(): string;
+/** ABI MAJOR.MINOR.PATCH triple. */
+export declare function abiVersion(): readonly [number, number, number];

package/dist/index.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: CECILL-2.1
+//
+// Public TypeScript API for the @nirs4all/methods binding — a
+// non-idiomatic function library over libn4m (raw typed arrays in/out). See
+// INPUT_CONTRACT.md and examples/consume.mjs.
+//
+// Example:
+//   import * as n4m from "@nirs4all/methods";
+//   await n4m.loadModule();
+//   const model = n4m.fitPls({ data: X, rows, cols }, { data: y, rows, cols: 1 }, 3);
+//   const preds = n4m.predictPls(model, { data: X, rows, cols });
+import { getModule } from "./ffi.js";
+export { loadModule, getModule, makeMatrixView, readArrayView } from "./ffi.js";
+export { Context } from "./context.js";
+export { Config } from "./config.js";
+export { Model, fitPls, predictPls, fitModel, predictModel, fitAom, fitPop, fitAomRidge, fitAomStack, computeSplit, computeSplitIndices } from "./model.js";
+export { ppCreate, ppFit, ppTransform, ppGetState, ppSetState, ppDestroy, } from "./preprocessing.js";
+export { MethodResult } from "./methodResult.js";
+export { Status, Dtype, Algorithm, Solver, Deflation, N4mError, } from "./types.js";
+/** ABI / project version reported by the loaded WASM module. */
+export function version() {
+    const m = getModule();
+    const ptr = m.ccall("n4m_get_version_string", "number", [], []);
+    return ptr === 0 ? "" : m.UTF8ToString(ptr);
+}
+/** ABI MAJOR.MINOR.PATCH triple. */
+export function abiVersion() {
+    const m = getModule();
+    return [
+        m.ccall("n4m_get_abi_version_major", "number", [], []),
+        m.ccall("n4m_get_abi_version_minor", "number", [], []),
+        m.ccall("n4m_get_abi_version_patch", "number", [], []),
+    ];
+}

package/dist/methodResult.d.ts

@@ -0,0 +1,28 @@
+import { Matrix } from "./types.js";
+export declare class MethodResult {
+    private _ptr;
+    constructor(ptr: number);
+    /** Generic runner for the `(ctx, cfg, X[, Y, ...views], ...scalar-extras)
+     *  -> n4m_method_result_t**` family — the bulk of the ~150 method_result
+     *  producers. Matrix views are built BigInt-safe via makeMatrixView, so
+     *  the deep entrypoints get correct dimensions under WASM_BIGINT=1.
+     *  Returns an owning MethodResult; read outputs with matrix()/vector().
+     *
+     *  `extra` are the positional scalar args after the views, matching the C
+     *  signature: "int" -> int32_t, "double" -> double, "int64" -> int64_t.
+     *  (Methods taking raw caller buffers — e.g. weighted_pls sample_weights —
+     *  need a thin per-method wrapper that mallocs the buffer; not handled
+     *  here.) */
+    static run(symbol: string, ctxHandle: number, cfgHandle: number, views: Matrix[], extra?: ReadonlyArray<{
+        kind: "int" | "double" | "int64";
+        value: number;
+    }>): MethodResult;
+    get handle(): number;
+    /** Read a named double matrix by name. Returns a copy in JS-owned memory. */
+    matrix(name: string): Matrix;
+    /** Read a named int32 vector. */
+    vectorInt(name: string): Int32Array;
+    /** Read a named scalar (returns NaN if not present). */
+    scalar(name: string): number;
+    destroy(): void;
+}

package/dist/methodResult.js

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: CECILL-2.1
+//
+// Owning wrapper around n4m_method_result_t — the universal output
+// container used by every method shipped in Batches 1-12 of the C ABI.
+import { checkStatus, getModule, makeMatrixView } from "./ffi.js";
+export class MethodResult {
+    _ptr;
+    constructor(ptr) {
+        this._ptr = ptr;
+    }
+    /** Generic runner for the `(ctx, cfg, X[, Y, ...views], ...scalar-extras)
+     *  -> n4m_method_result_t**` family — the bulk of the ~150 method_result
+     *  producers. Matrix views are built BigInt-safe via makeMatrixView, so
+     *  the deep entrypoints get correct dimensions under WASM_BIGINT=1.
+     *  Returns an owning MethodResult; read outputs with matrix()/vector().
+     *
+     *  `extra` are the positional scalar args after the views, matching the C
+     *  signature: "int" -> int32_t, "double" -> double, "int64" -> int64_t.
+     *  (Methods taking raw caller buffers — e.g. weighted_pls sample_weights —
+     *  need a thin per-method wrapper that mallocs the buffer; not handled
+     *  here.) */
+    static run(symbol, ctxHandle, cfgHandle, views, extra = []) {
+        const m = getModule();
+        const built = views.map((v) => makeMatrixView(v.data, v.rows, v.cols));
+        const resPP = m._malloc(4);
+        m.setValue(resPP, 0, "i32");
+        try {
+            const argTypes = ["number", "number"];
+            const args = [ctxHandle, cfgHandle];
+            for (const b of built) {
+                argTypes.push("number");
+                args.push(b.viewPtr);
+            }
+            for (const e of extra) {
+                if (e.kind === "double") {
+                    argTypes.push("number");
+                    args.push(e.value);
+                }
+                else if (e.kind === "int64") {
+                    argTypes.push("i64");
+                    args.push(BigInt(e.value));
+                }
+                else {
+                    argTypes.push("number");
+                    args.push(e.value | 0);
+                }
+            }
+            argTypes.push("number");
+            args.push(resPP); // n4m_method_result_t** out
+            const status = m.ccall(symbol, "number", argTypes, args);
+            checkStatus(status, ctxHandle);
+            const ptr = m.getValue(resPP, "i32");
+            return new MethodResult(ptr);
+        }
+        finally {
+            for (const b of built)
+                b.free();
+            m._free(resPP);
+        }
+    }
+    get handle() {
+        return this._ptr;
+    }
+    /** Read a named double matrix by name. Returns a copy in JS-owned memory. */
+    matrix(name) {
+        const m = getModule();
+        const nameBytes = m.lengthBytesUTF8(name);
+        const namePtr = m._malloc(nameBytes + 1);
+        const dataPtrPtr = m._malloc(4);
+        const rowsPtr = m._malloc(8);
+        const colsPtr = m._malloc(8);
+        try {
+            m.stringToUTF8(name, namePtr, nameBytes + 1);
+            const status = m.ccall("n4m_method_result_get_double_matrix", "number", ["number", "number", "number", "number", "number"], [this._ptr, namePtr, dataPtrPtr, rowsPtr, colsPtr]);
+            checkStatus(status);
+            const dataPtr = m.getValue(dataPtrPtr, "i32");
+            // i64 lo/hi pair — WASM_BIGINT=1 returns BigInt; use HEAP32 instead.
+            const rows = m.getValue(rowsPtr, "i64");
+            const cols = m.getValue(colsPtr, "i64");
+            const n = Number(rows) * Number(cols);
+            const data = new Float64Array(n);
+            if (n > 0) {
+                data.set(m.HEAPF64.subarray(dataPtr / 8, dataPtr / 8 + n));
+            }
+            return { data, rows: Number(rows), cols: Number(cols) };
+        }
+        finally {
+            m._free(namePtr);
+            m._free(dataPtrPtr);
+            m._free(rowsPtr);
+            m._free(colsPtr);
+        }
+    }
+    /** Read a named int32 vector. */
+    vectorInt(name) {
+        const m = getModule();
+        const nameBytes = m.lengthBytesUTF8(name);
+        const namePtr = m._malloc(nameBytes + 1);
+        const dataPtrPtr = m._malloc(4);
+        const sizePtr = m._malloc(4);
+        try {
+            m.stringToUTF8(name, namePtr, nameBytes + 1);
+            const status = m.ccall("n4m_method_result_get_int_vector", "number", ["number", "number", "number", "number"], [this._ptr, namePtr, dataPtrPtr, sizePtr]);
+            checkStatus(status);
+            const dataPtr = m.getValue(dataPtrPtr, "i32");
+            const size = m.getValue(sizePtr, "i32");
+            const out = new Int32Array(size);
+            if (size > 0) {
+                out.set(m.HEAP32.subarray(dataPtr / 4, dataPtr / 4 + size));
+            }
+            return out;
+        }
+        finally {
+            m._free(namePtr);
+            m._free(dataPtrPtr);
+            m._free(sizePtr);
+        }
+    }
+    /** Read a named scalar (returns NaN if not present). */
+    scalar(name) {
+        const m = getModule();
+        const nameBytes = m.lengthBytesUTF8(name);
+        const namePtr = m._malloc(nameBytes + 1);
+        const outPtr = m._malloc(8);
+        try {
+            m.stringToUTF8(name, namePtr, nameBytes + 1);
+            const status = m.ccall("n4m_method_result_get_scalar", "number", ["number", "number", "number"], [this._ptr, namePtr, outPtr]);
+            if (status !== 0)
+                return NaN;
+            return m.getValue(outPtr, "double");
+        }
+        finally {
+            m._free(namePtr);
+            m._free(outPtr);
+        }
+    }
+    destroy() {
+        if (this._ptr === 0)
+            return;
+        getModule().ccall("n4m_method_result_destroy", null, ["number"], [this._ptr]);
+        this._ptr = 0;
+    }
+}