@nirs4all/methods 1.0.18 → 1.1.0

package/dist/nativeAugmentation.d.ts

@@ -0,0 +1,29 @@
+import type { Matrix } from "./types.js";
+declare const KINDS: {
+    readonly GaussianNoise: readonly [0, 1];
+    readonly MultiplicativeNoise: readonly [1, 1];
+    readonly SpikeNoise: readonly [2, 4];
+    readonly HeteroNoise: readonly [3, 2];
+    readonly LinearDrift: readonly [4, 4];
+    readonly PathLength: readonly [5, 2];
+    readonly BandPerturb: readonly [6, 7];
+    readonly BandMask: readonly [7, 5];
+    readonly ChannelDropout: readonly [8, 2];
+    readonly GaussJitter: readonly [9, 3];
+    readonly UnsharpMask: readonly [10, 4];
+    readonly LocalClip: readonly [11, 3];
+    readonly RotateTranslate: readonly [12, 2];
+    readonly RandomXOp: readonly [13, 3];
+    readonly ScatterSimMSC: readonly [14, 4];
+    readonly DeadBand: readonly [15, 6];
+    readonly BatchEffect: readonly [16, 4];
+    readonly SplineSmoothing: readonly [17, 0];
+    readonly SplineXPerturb: readonly [18, 4];
+    readonly SplineYPerturb: readonly [19, 2];
+    readonly SplineXSimplify: readonly [20, 2];
+    readonly SplineCurveSimplify: readonly [21, 2];
+};
+export type NativeAugmentationKind = keyof typeof KINDS;
+/** Apply one seeded native augmenter to training X; no Y or fitted state. */
+export declare function augmentNative(kind: NativeAugmentationKind, X: Matrix, params: readonly number[], seed?: number | bigint): Matrix;
+export {};

package/dist/nativeAugmentation.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: CECILL-2.1
+// Train-only X->X augmentation facade. All numerical work remains in C++.
+import { checkStatus, getModule } from "./ffi.js";
+const KINDS = {
+    GaussianNoise: [0, 1], MultiplicativeNoise: [1, 1],
+    SpikeNoise: [2, 4], HeteroNoise: [3, 2], LinearDrift: [4, 4],
+    PathLength: [5, 2], BandPerturb: [6, 7], BandMask: [7, 5],
+    ChannelDropout: [8, 2], GaussJitter: [9, 3], UnsharpMask: [10, 4],
+    LocalClip: [11, 3], RotateTranslate: [12, 2], RandomXOp: [13, 3],
+    ScatterSimMSC: [14, 4], DeadBand: [15, 6], BatchEffect: [16, 4],
+    SplineSmoothing: [17, 0], SplineXPerturb: [18, 4],
+    SplineYPerturb: [19, 2], SplineXSimplify: [20, 2],
+    SplineCurveSimplify: [21, 2],
+};
+/** Apply one seeded native augmenter to training X; no Y or fitted state. */
+export function augmentNative(kind, X, params, seed = 0) {
+    if (!Object.prototype.hasOwnProperty.call(KINDS, kind))
+        throw new Error(`unknown native augmentation ${kind}`);
+    const [code, count] = KINDS[kind];
+    if (!Number.isSafeInteger(X.rows) || !Number.isSafeInteger(X.cols) ||
+        X.rows < 1 || X.cols < 1 || X.rows * X.cols > 2147483647 ||
+        X.data.length !== X.rows * X.cols || !X.data.every(Number.isFinite))
+        throw new Error("X must be a nonempty finite row-major matrix");
+    if (params.length !== count || !params.every(Number.isFinite))
+        throw new Error("invalid native augmentation parameter vector");
+    if (typeof seed === "number" && !Number.isSafeInteger(seed))
+        throw new Error("seed must be an exact unsigned integer");
+    const seed64 = BigInt(seed);
+    if (seed64 < 0n || seed64 > (1n << 64n) - 1n)
+        throw new Error("seed must fit unsigned int64");
+    const m = getModule();
+    const xp = m._malloc(X.data.byteLength);
+    const pp = count === 0 ? 0 : m._malloc(count * 8);
+    const op = m._malloc(X.data.byteLength);
+    try {
+        m.HEAPF64.set(X.data, xp / 8);
+        if (count > 0)
+            m.HEAPF64.set(params, pp / 8);
+        checkStatus(m.ccall("n4m_wasm_augmentation_apply", "number", Array(9).fill("number"), [code, pp, count, Number(seed64 & 0xffffffffn),
+            Number(seed64 >> 32n), xp, X.rows, X.cols, op]));
+        return { rows: X.rows, cols: X.cols,
+            data: Float64Array.from(m.HEAPF64.subarray(op / 8, op / 8 + X.data.length)) };
+    }
+    finally {
+        for (const ptr of [xp, pp, op])
+            if (ptr !== 0)
+                m._free(ptr);
+    }
+}

package/dist/nativeModel.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from "./context.js";
+import type { MethodResult } from "./methodResult.js";
+import type { Matrix } from "./types.js";
+export declare class NativeModel {
+    private _ptr;
+    private readonly _ctx;
+    private constructor();
+    /** Copy an affine MethodResult into a standalone native model. */
+    static fromMethodResult(ctx: Context, result: MethodResult): NativeModel;
+    /** Import a complete native N4MM model payload. */
+    static fromN4mm(ctx: Context, payload: Uint8Array): NativeModel;
+    /** Predict through libn4m; no coefficients are evaluated in JS. */
+    predict(X: Matrix): Matrix;
+    /** Export the complete native model as N4MM bytes. */
+    toN4mm(): Uint8Array;
+    destroy(): void;
+}

package/dist/nativeModel.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: CECILL-2.1
+// Native predict-only model promoted from an affine MethodResult.
+import { checkStatus, getModule, makeMatrixView } from "./ffi.js";
+export class NativeModel {
+    _ptr;
+    _ctx;
+    constructor(ctx, ptr) {
+        this._ctx = ctx;
+        this._ptr = ptr;
+    }
+    /** Copy an affine MethodResult into a standalone native model. */
+    static fromMethodResult(ctx, result) {
+        const m = getModule();
+        const out = m._malloc(4);
+        try {
+            m.setValue(out, 0, "i32");
+            const status = m.ccall("n4m_model_from_method_result", "number", ["number", "number", "number"], [ctx.handle, result.handle, out]);
+            checkStatus(status, ctx.handle);
+            return new NativeModel(ctx, m.getValue(out, "i32"));
+        }
+        finally {
+            m._free(out);
+        }
+    }
+    /** Import a complete native N4MM model payload. */
+    static fromN4mm(ctx, payload) {
+        const m = getModule();
+        const data = m._malloc(Math.max(1, payload.byteLength));
+        const out = m._malloc(4);
+        try {
+            m.HEAPU8.set(payload, data);
+            m.setValue(out, 0, "i32");
+            const status = m.ccall("n4m_model_import_from_buffer", "number", ["number", "number", "number", "number"], [ctx.handle, data, payload.byteLength, out]);
+            checkStatus(status, ctx.handle);
+            return new NativeModel(ctx, m.getValue(out, "i32"));
+        }
+        finally {
+            m._free(data);
+            m._free(out);
+        }
+    }
+    /** Predict through libn4m; no coefficients are evaluated in JS. */
+    predict(X) {
+        const m = getModule();
+        const targetsPtr = m._malloc(4);
+        try {
+            checkStatus(m.ccall("n4m_model_get_n_targets", "number", ["number", "number"], [this._ptr, targetsPtr]));
+            const targets = m.getValue(targetsPtr, "i32");
+            const input = makeMatrixView(X.data, X.rows, X.cols);
+            try {
+                const output = makeMatrixView(new Float64Array(X.rows * targets), X.rows, targets);
+                try {
+                    checkStatus(m.ccall("n4m_model_predict", "number", ["number", "number", "number", "number"], [this._ctx.handle, this._ptr, input.viewPtr, output.viewPtr]), this._ctx.handle);
+                    return {
+                        data: new Float64Array(m.HEAPF64.subarray(output.dataPtr / 8, output.dataPtr / 8 + X.rows * targets)),
+                        rows: X.rows,
+                        cols: targets,
+                    };
+                }
+                finally {
+                    output.free();
+                }
+            }
+            finally {
+                input.free();
+            }
+        }
+        finally {
+            m._free(targetsPtr);
+        }
+    }
+    /** Export the complete native model as N4MM bytes. */
+    toN4mm() {
+        const m = getModule();
+        const sizePtr = m._malloc(4); // size_t on WASM32
+        const writtenPtr = m._malloc(4);
+        try {
+            checkStatus(m.ccall("n4m_model_export_size", "number", ["number", "number"], [this._ptr, sizePtr]));
+            const size = m.getValue(sizePtr, "i32");
+            const data = m._malloc(Math.max(1, size));
+            try {
+                checkStatus(m.ccall("n4m_model_export_to_buffer", "number", ["number", "number", "number", "number"], [this._ptr, data, size, writtenPtr]));
+                return new Uint8Array(m.HEAPU8.subarray(data, data + m.getValue(writtenPtr, "i32")));
+            }
+            finally {
+                m._free(data);
+            }
+        }
+        finally {
+            m._free(sizePtr);
+            m._free(writtenPtr);
+        }
+    }
+    destroy() {
+        if (this._ptr === 0)
+            return;
+        getModule().ccall("n4m_model_destroy", null, ["number"], [this._ptr]);
+        this._ptr = 0;
+    }
+}

package/dist/nativePreprocessingPipeline.d.ts

@@ -0,0 +1,42 @@
+import type { Context } from "./context.js";
+import type { Matrix } from "./types.js";
+/** The 15 pipeline kinds currently implemented by the native core. */
+export declare enum PipelineOperatorKind {
+    IDENTITY = 0,
+    CENTER = 1,
+    AUTOSCALE = 2,
+    PARETO_SCALE = 3,
+    SNV = 4,
+    MSC = 5,
+    EMSC = 6,
+    DETREND_POLY = 7,
+    SAVGOL_SMOOTH = 8,
+    SAVGOL_DERIVATIVE = 9,
+    NORRIS_WILLIAMS = 10,
+    ASLS_BASELINE = 11,
+    OSC = 12,
+    EPO = 13,
+    WAVELET_DENOISE = 14
+}
+export interface PipelineStep {
+    readonly kind: PipelineOperatorKind;
+    /** Original positional native parameters; defaults remain an empty vector. */
+    readonly params: readonly number[];
+}
+/** Owning JS façade for an ordered, fitted C ABI preprocessing pipeline. */
+export declare class NativePreprocessingPipeline {
+    private _ptr;
+    private readonly _ctx;
+    readonly nFeatures: number;
+    readonly steps: readonly PipelineStep[];
+    private constructor();
+    /** Fit an ordered recipe. OSC and EPO require Y; others may omit it. */
+    static fit(ctx: Context, steps: readonly PipelineStep[], X: Matrix, Y?: Matrix): NativePreprocessingPipeline;
+    /** Import fitted N4MP bytes; optionally attest against an external recipe. */
+    static fromBytes(ctx: Context, bytes: Uint8Array, expectedSteps?: readonly PipelineStep[]): NativePreprocessingPipeline;
+    /** Transform new rows using only native fitted state. */
+    transform(X: Matrix): Matrix;
+    /** Export the native fitted state and ordered recipe in N4MP format. */
+    toBytes(): Uint8Array;
+    destroy(): void;
+}

package/dist/nativePreprocessingPipeline.js

@@ -0,0 +1,246 @@
+// SPDX-License-Identifier: CECILL-2.1
+// Fitted preprocessing and N4MP portability; all numerics remain in libn4m.
+import { checkStatus, getModule, makeMatrixView } from "./ffi.js";
+/** The 15 pipeline kinds currently implemented by the native core. */
+export var PipelineOperatorKind;
+(function (PipelineOperatorKind) {
+    PipelineOperatorKind[PipelineOperatorKind["IDENTITY"] = 0] = "IDENTITY";
+    PipelineOperatorKind[PipelineOperatorKind["CENTER"] = 1] = "CENTER";
+    PipelineOperatorKind[PipelineOperatorKind["AUTOSCALE"] = 2] = "AUTOSCALE";
+    PipelineOperatorKind[PipelineOperatorKind["PARETO_SCALE"] = 3] = "PARETO_SCALE";
+    PipelineOperatorKind[PipelineOperatorKind["SNV"] = 4] = "SNV";
+    PipelineOperatorKind[PipelineOperatorKind["MSC"] = 5] = "MSC";
+    PipelineOperatorKind[PipelineOperatorKind["EMSC"] = 6] = "EMSC";
+    PipelineOperatorKind[PipelineOperatorKind["DETREND_POLY"] = 7] = "DETREND_POLY";
+    PipelineOperatorKind[PipelineOperatorKind["SAVGOL_SMOOTH"] = 8] = "SAVGOL_SMOOTH";
+    PipelineOperatorKind[PipelineOperatorKind["SAVGOL_DERIVATIVE"] = 9] = "SAVGOL_DERIVATIVE";
+    PipelineOperatorKind[PipelineOperatorKind["NORRIS_WILLIAMS"] = 10] = "NORRIS_WILLIAMS";
+    PipelineOperatorKind[PipelineOperatorKind["ASLS_BASELINE"] = 11] = "ASLS_BASELINE";
+    PipelineOperatorKind[PipelineOperatorKind["OSC"] = 12] = "OSC";
+    PipelineOperatorKind[PipelineOperatorKind["EPO"] = 13] = "EPO";
+    PipelineOperatorKind[PipelineOperatorKind["WAVELET_DENOISE"] = 14] = "WAVELET_DENOISE";
+})(PipelineOperatorKind || (PipelineOperatorKind = {}));
+function validateMatrix(X, label) {
+    if (!Number.isSafeInteger(X.rows) || !Number.isSafeInteger(X.cols) ||
+        X.rows < 1 || X.cols < 1 || X.data.length !== X.rows * X.cols ||
+        !X.data.every(Number.isFinite)) {
+        throw new Error(`${label} must be a nonempty finite row-major matrix`);
+    }
+}
+function validateSteps(steps) {
+    if (steps.length < 1 || steps.length > 256) {
+        throw new Error("native pipeline requires 1–256 ordered steps");
+    }
+    for (const step of steps) {
+        if (!Number.isInteger(step.kind) || step.kind < 0 || step.kind > 14 ||
+            !Array.isArray(step.params) || step.params.length > 256 ||
+            !step.params.every(Number.isFinite)) {
+            throw new Error("invalid or unsupported native pipeline step");
+        }
+    }
+}
+function readPlan(ptr) {
+    const m = getModule();
+    const info = m._malloc(12); // int64_t feature width, int32_t operator count
+    try {
+        checkStatus(m.ccall("n4m_pipeline_get_info", "number", ["number", "number", "number"], [ptr, info, info + 8]));
+        const features = Number(m.getValue(info, "i64"));
+        const count = m.getValue(info + 8, "i32");
+        if (!Number.isSafeInteger(features) || features < 1 || count < 1 || count > 256) {
+            throw new Error("invalid native pipeline metadata");
+        }
+        const kindPtr = m._malloc(4);
+        const countPtr = m._malloc(4);
+        try {
+            const steps = [];
+            for (let index = 0; index < count; ++index) {
+                checkStatus(m.ccall("n4m_pipeline_get_operator", "number", ["number", "number", "number", "number", "number", "number"], [ptr, index, kindPtr, 0, 0, countPtr]));
+                const kind = m.getValue(kindPtr, "i32");
+                const nParams = m.getValue(countPtr, "i32");
+                if (kind < 0 || kind > 14 || nParams < 0 || nParams > 256) {
+                    throw new Error("invalid native pipeline operator metadata");
+                }
+                const paramsPtr = m._malloc(Math.max(1, nParams) * 8);
+                try {
+                    if (nParams > 0) {
+                        checkStatus(m.ccall("n4m_pipeline_get_operator", "number", ["number", "number", "number", "number", "number", "number"], [ptr, index, kindPtr, paramsPtr, nParams, countPtr]));
+                    }
+                    steps.push({ kind, params: Array.from(m.HEAPF64.subarray(paramsPtr / 8, paramsPtr / 8 + nParams)) });
+                }
+                finally {
+                    m._free(paramsPtr);
+                }
+            }
+            return { features, steps };
+        }
+        finally {
+            m._free(kindPtr);
+            m._free(countPtr);
+        }
+    }
+    finally {
+        m._free(info);
+    }
+}
+function samePlan(a, b) {
+    return a.length === b.length && a.every((step, index) => {
+        const other = b[index];
+        return other !== undefined && step.kind === other.kind &&
+            step.params.length === other.params.length &&
+            step.params.every((value, i) => Object.is(value, other.params[i]));
+    });
+}
+/** Owning JS façade for an ordered, fitted C ABI preprocessing pipeline. */
+export class NativePreprocessingPipeline {
+    _ptr;
+    _ctx;
+    nFeatures;
+    steps;
+    constructor(ctx, ptr, features, steps) {
+        this._ctx = ctx;
+        this._ptr = ptr;
+        this.nFeatures = features;
+        this.steps = steps.map(step => Object.freeze({
+            kind: step.kind, params: Object.freeze([...step.params]),
+        }));
+        Object.freeze(this.steps);
+    }
+    /** Fit an ordered recipe. OSC and EPO require Y; others may omit it. */
+    static fit(ctx, steps, X, Y) {
+        validateSteps(steps);
+        validateMatrix(X, "X");
+        if (Y !== undefined) {
+            validateMatrix(Y, "Y");
+            if (Y.rows !== X.rows)
+                throw new Error("Y rows must match X rows");
+        }
+        const m = getModule();
+        const outPtr = m._malloc(4);
+        let ptr = 0;
+        try {
+            m.setValue(outPtr, 0, "i32");
+            checkStatus(m.ccall("n4m_pipeline_create", "number", ["number"], [outPtr]));
+            ptr = m.getValue(outPtr, "i32");
+            for (const step of steps) {
+                const params = m._malloc(Math.max(1, step.params.length) * 8);
+                try {
+                    m.HEAPF64.set(step.params, params / 8);
+                    checkStatus(m.ccall("n4m_pipeline_add_operator", "number", ["number", "number", "number", "number"], [ptr, step.kind, step.params.length ? params : 0,
+                        step.params.length]));
+                }
+                finally {
+                    m._free(params);
+                }
+            }
+            const xView = makeMatrixView(X.data, X.rows, X.cols);
+            let yView;
+            try {
+                yView = Y === undefined ? undefined :
+                    makeMatrixView(Y.data, Y.rows, Y.cols);
+                checkStatus(m.ccall("n4m_pipeline_fit", "number", ["number", "number", "number", "number"], [ctx.handle, ptr, xView.viewPtr, yView?.viewPtr ?? 0]), ctx.handle);
+            }
+            finally {
+                yView?.free();
+                xView.free();
+            }
+            const plan = readPlan(ptr);
+            if (!samePlan(plan.steps, steps)) {
+                throw new Error("native fitted plan differs from requested recipe");
+            }
+            const result = new NativePreprocessingPipeline(ctx, ptr, plan.features, plan.steps);
+            ptr = 0;
+            return result;
+        }
+        finally {
+            if (ptr !== 0)
+                m.ccall("n4m_pipeline_destroy", null, ["number"], [ptr]);
+            m._free(outPtr);
+        }
+    }
+    /** Import fitted N4MP bytes; optionally attest against an external recipe. */
+    static fromBytes(ctx, bytes, expectedSteps) {
+        if (!(bytes instanceof Uint8Array) || bytes.length === 0 ||
+            bytes.length > 64 * 1024 * 1024) {
+            throw new Error("N4MP payload must be a Uint8Array of at most 64 MiB");
+        }
+        if (expectedSteps !== undefined)
+            validateSteps(expectedSteps);
+        const m = getModule();
+        const data = m._malloc(bytes.length);
+        const outPtr = m._malloc(4);
+        let ptr = 0;
+        try {
+            m.HEAPU8.set(bytes, data);
+            m.setValue(outPtr, 0, "i32");
+            checkStatus(m.ccall("n4m_pipeline_import_from_buffer", "number", ["number", "number", "number", "number"], [ctx.handle, data, bytes.length, outPtr]), ctx.handle);
+            ptr = m.getValue(outPtr, "i32");
+            const plan = readPlan(ptr);
+            if (expectedSteps !== undefined && !samePlan(plan.steps, expectedSteps)) {
+                throw new Error("N4MP ordered plan does not match expected recipe");
+            }
+            const result = new NativePreprocessingPipeline(ctx, ptr, plan.features, plan.steps);
+            ptr = 0;
+            return result;
+        }
+        finally {
+            if (ptr !== 0)
+                m.ccall("n4m_pipeline_destroy", null, ["number"], [ptr]);
+            m._free(data);
+            m._free(outPtr);
+        }
+    }
+    /** Transform new rows using only native fitted state. */
+    transform(X) {
+        if (this._ptr === 0)
+            throw new Error("native pipeline has been destroyed");
+        validateMatrix(X, "X");
+        if (X.cols !== this.nFeatures)
+            throw new Error("X feature width must match fit");
+        const m = getModule();
+        const input = makeMatrixView(X.data, X.rows, X.cols);
+        try {
+            const output = makeMatrixView(new Float64Array(X.data.length), X.rows, X.cols);
+            try {
+                checkStatus(m.ccall("n4m_pipeline_transform", "number", ["number", "number", "number", "number"], [this._ctx.handle, this._ptr, input.viewPtr, output.viewPtr]), this._ctx.handle);
+                return { data: Float64Array.from(m.HEAPF64.subarray(output.dataPtr / 8, output.dataPtr / 8 + X.data.length)),
+                    rows: X.rows, cols: X.cols };
+            }
+            finally {
+                output.free();
+            }
+        }
+        finally {
+            input.free();
+        }
+    }
+    /** Export the native fitted state and ordered recipe in N4MP format. */
+    toBytes() {
+        if (this._ptr === 0)
+            throw new Error("native pipeline has been destroyed");
+        const m = getModule();
+        const sizePtr = m._malloc(4); // WASM32 size_t
+        const writtenPtr = m._malloc(4);
+        try {
+            checkStatus(m.ccall("n4m_pipeline_export_size", "number", ["number", "number"], [this._ptr, sizePtr]));
+            const size = m.getValue(sizePtr, "i32");
+            const data = m._malloc(Math.max(1, size));
+            try {
+                checkStatus(m.ccall("n4m_pipeline_export_to_buffer", "number", ["number", "number", "number", "number"], [this._ptr, data, size, writtenPtr]));
+                return Uint8Array.from(m.HEAPU8.subarray(data, data + m.getValue(writtenPtr, "i32")));
+            }
+            finally {
+                m._free(data);
+            }
+        }
+        finally {
+            m._free(sizePtr);
+            m._free(writtenPtr);
+        }
+    }
+    destroy() {
+        if (this._ptr === 0)
+            return;
+        getModule().ccall("n4m_pipeline_destroy", null, ["number"], [this._ptr]);
+        this._ptr = 0;
+    }
+}

package/dist/nativeSplitter.d.ts

@@ -0,0 +1,23 @@
+import type { Matrix } from "./types.js";
+export type NativeSplitterKind = "KennardStone" | "SPXY" | "SPXYFold" | "SPXYGroupFold" | "KMeans" | "KBinsStratified" | "BinnedStratGroupFold" | "SystematicCircular" | "DataTwinning";
+export interface NativeSplitterOptions {
+    testSize?: number;
+    nSplits?: number;
+    yMetric?: 0 | 1 | 2;
+    aggregation?: 0 | 1;
+    nBins?: number;
+    strategy?: 0 | 1;
+    shuffle?: boolean;
+    maxIter?: number;
+    seed?: number | bigint;
+    /** Signed int64 group IDs, one per sample. Required by group-fold kinds. */
+    groups?: readonly (number | bigint)[];
+    /** Zero-based fold index for the three fold kinds; zero otherwise. */
+    foldIndex?: number;
+}
+export interface NativeSplitIndices {
+    trainIndices: Int32Array;
+    testIndices: Int32Array;
+}
+/** Return the native ordered row indices without sorting or host-side splitting. */
+export declare function splitNative(kind: NativeSplitterKind, X: Matrix | null, Y?: Matrix | null, options?: NativeSplitterOptions): NativeSplitIndices;

package/dist/nativeSplitter.js

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: CECILL-2.1
+// One typed marshalling path to the nine native sample splitters.
+import { checkStatus, getModule } from "./ffi.js";
+const KINDS = {
+    KennardStone: 0, SPXY: 1, SPXYFold: 2, SPXYGroupFold: 3,
+    KMeans: 4, KBinsStratified: 5, BinnedStratGroupFold: 6,
+    SystematicCircular: 7, DataTwinning: 8,
+};
+function validMatrix(value, name) {
+    if (!Number.isSafeInteger(value.rows) || !Number.isSafeInteger(value.cols) ||
+        value.rows < 1 || value.cols < 1 ||
+        value.data.length !== value.rows * value.cols ||
+        !value.data.every(Number.isFinite)) {
+        throw new Error(`${name} must be a nonempty finite row-major matrix`);
+    }
+}
+/** Return the native ordered row indices without sorting or host-side splitting. */
+export function splitNative(kind, X, Y = null, options = {}) {
+    if (!Object.prototype.hasOwnProperty.call(KINDS, kind)) {
+        throw new Error(`unknown native splitter ${kind}`);
+    }
+    const code = KINDS[kind];
+    const needsX = [0, 1, 2, 3, 4, 8].includes(code);
+    const needsY = [1, 2, 3, 5, 6, 7].includes(code);
+    const grouped = code === 3 || code === 6;
+    const folded = code === 2 || code === 3 || code === 6;
+    if ((X !== null) !== needsX || (Y !== null) !== needsY ||
+        (options.groups !== undefined) !== grouped) {
+        throw new Error("X/Y/groups must match the native splitter kind");
+    }
+    if (X !== null)
+        validMatrix(X, "X");
+    if (Y !== null)
+        validMatrix(Y, "Y");
+    const n = X?.rows ?? Y.rows;
+    if (!Number.isSafeInteger(n) || n > 2147483647 ||
+        (X !== null && Y !== null && X.rows !== Y.rows)) {
+        throw new Error("native splitter requires aligned, int32-sized rows");
+    }
+    const ns = options.nSplits ?? 3;
+    const fold = options.foldIndex ?? 0;
+    if (!Number.isInteger(fold) || (folded ? fold < 0 || fold >= ns : fold !== 0) ||
+        !Number.isInteger(ns) || ns < 2) {
+        throw new Error("invalid native splitter fold configuration");
+    }
+    const rawGroups = options.groups ?? [];
+    if (grouped && rawGroups.length !== n)
+        throw new Error("groups length must match rows");
+    const groupIds = rawGroups.map(value => {
+        if (typeof value === "number" && (!Number.isSafeInteger(value))) {
+            throw new Error("group IDs must be exact signed int64 integers");
+        }
+        const id = BigInt(value);
+        if (id < -(1n << 63n) || id > (1n << 63n) - 1n) {
+            throw new Error("group IDs must fit signed int64");
+        }
+        return id;
+    });
+    const seedRaw = options.seed ?? 0;
+    if (typeof seedRaw === "number" && !Number.isSafeInteger(seedRaw)) {
+        throw new Error("seed must be an exact unsigned integer");
+    }
+    const seed = BigInt(seedRaw);
+    if (seed < 0n || seed > (1n << 64n) - 1n) {
+        throw new Error("seed must fit unsigned int64");
+    }
+    const integers = [options.yMetric ?? 1, options.aggregation ?? 0,
+        options.nBins ?? 5, options.strategy ?? 0,
+        options.maxIter ?? 100];
+    if (integers.some(value => !Number.isInteger(value) ||
+        value < 0 || value > 2147483647)) {
+        throw new Error("native splitter parameters must be nonnegative int32 values");
+    }
+    const testSize = options.testSize ?? 0.25;
+    if (!Number.isFinite(testSize) || testSize <= 0 || testSize >= 1) {
+        throw new Error("testSize must be between zero and one");
+    }
+    const m = getModule();
+    const spec = m._malloc(48); // C n4m_splitter_spec_t, WASM32 8-byte alignment
+    const xp = X === null ? 0 : m._malloc(X.data.byteLength);
+    const yp = Y === null ? 0 : m._malloc(Y.data.byteLength);
+    const gp = grouped ? m._malloc(n * 8) : 0;
+    const train = m._malloc(n * 4);
+    const test = m._malloc(n * 4);
+    const nTrain = m._malloc(4);
+    const nTest = m._malloc(4);
+    try {
+        if (X !== null)
+            m.HEAPF64.set(X.data, xp / 8);
+        if (Y !== null)
+            m.HEAPF64.set(Y.data, yp / 8);
+        const data = new DataView(m.HEAPU8.buffer);
+        groupIds.forEach((id, i) => data.setBigInt64(gp + i * 8, id, true));
+        [code, ns, integers[0], integers[1], integers[2], integers[3],
+            options.shuffle === false ? 0 : 1, integers[4]].forEach((value, i) => data.setInt32(spec + i * 4, value, true));
+        data.setFloat64(spec + 32, testSize, true);
+        data.setBigUint64(spec + 40, seed, true);
+        checkStatus(m.ccall("n4m_wasm_splitter_indices", "number", Array(12).fill("number"), [spec, xp, yp, n, X?.cols ?? 0, Y?.cols ?? 0, gp, fold,
+            train, nTrain, test, nTest]));
+        const trainCount = m.getValue(nTrain, "i32");
+        const testCount = m.getValue(nTest, "i32");
+        if (trainCount < 0 || testCount < 0 || trainCount + testCount !== n) {
+            throw new Error("invalid native splitter result sizes");
+        }
+        return {
+            trainIndices: Int32Array.from(m.HEAP32.subarray(train / 4, train / 4 + trainCount)),
+            testIndices: Int32Array.from(m.HEAP32.subarray(test / 4, test / 4 + testCount)),
+        };
+    }
+    finally {
+        for (const ptr of [spec, xp, yp, gp, train, test, nTrain, nTest]) {
+            if (ptr !== 0)
+                m._free(ptr);
+        }
+    }
+}

package/dist/selection.d.ts

@@ -0,0 +1,6 @@
+import { Matrix } from "./types.js";
+export declare const selectorMethods: readonly string[];
+/** Run one of the 25 native selectors, preserving its ranked int64 indices. */
+export declare function selectVariables(method: string, X: Matrix, Y: Matrix, nComponents?: number, methodParams?: Record<string, unknown>): BigInt64Array;
+/** Compatibility convenience wrapper for the native SPA selector. */
+export declare function selectSpa(X: Matrix, Y: Matrix, topK: number, nComponents?: number): BigInt64Array;