nirs4all 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nirs4all contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# JavaScript/WASM Binding
+
+npm package name: `nirs4all`
+
+This package is the runtime surface that `nirs4all-web` should consume. The web
+application lives in `nirs4all-web`; this directory is for the reusable
+JavaScript/WASM binding and package metadata.
+
+The portable execution API delegates Kennard-Stone, SNV, Savitzky-Golay, and
+PLS component sweeps to `@nirs4all/methods-wasm`:
+
+- `runPortablePipeline(source, dataset)` parses the shared nirs4all JSON/YAML
+  syntax, executes the portable subset, and returns parity-checkable split,
+  target, variant, and selected-result fields plus a serialized selected PLS
+  model.
+- `predictPortablePipeline(result, dataset)` replays the recorded preprocessing
+  chain and predicts with that serialized model through the same methods WASM
+  backend.
+
+Savitzky-Golay defaults to `mode: "interp"` for full nirs4all parity and
+preserves explicit methods-backed modes (`mirror`, `constant`, `nearest`,
+`wrap`, `interp`) plus `cval` in the serialized preprocessing chain.

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "nirs4all",
+  "version": "0.1.0",
+  "description": "Portable nirs4all aggregate binding for JavaScript and WASM",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GBeurier/nirs4all-lite.git",
+    "directory": "bindings/wasm"
+  },
+  "keywords": [
+    "nirs",
+    "spectroscopy",
+    "chemometrics",
+    "wasm"
+  ],
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "peerDependenciesMeta": {
+    "@nirs4all/methods-wasm": {
+      "optional": true
+    },
+    "nirs4all-formats-wasm": {
+      "optional": true
+    },
+    "nirs4all-io-wasm": {
+      "optional": true
+    },
+    "@nirs4all/datasets-wasm": {
+      "optional": true
+    },
+    "dag-ml-wasm": {
+      "optional": true
+    },
+    "dag-ml-data-wasm": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/src/execution.js

@@ -0,0 +1,398 @@
+import { loadMethodsWasm, loadPipelineDefinition } from './index.js';
+
+const KENNARD_STONE = new Set([
+  'nirs4all.operators.splitters.KennardStoneSplitter',
+  'nirs4all.operators.splitters.splitters.KennardStoneSplitter',
+]);
+
+const SNV = new Set([
+  'nirs4all.operators.transforms.SNV',
+  'nirs4all.operators.transforms.StandardNormalVariate',
+  'nirs4all.operators.transforms.scalers.StandardNormalVariate',
+]);
+
+const SAVGOL = new Set([
+  'nirs4all.operators.transforms.SavitzkyGolay',
+  'nirs4all.operators.transforms.nirs.SavitzkyGolay',
+]);
+
+const PLS = new Set([
+  'sklearn.cross_decomposition.PLSRegression',
+  'sklearn.cross_decomposition._pls.PLSRegression',
+]);
+
+export async function runPortablePipeline(source, dataset, options = {}) {
+  const definition = loadPipelineDefinition(source);
+  const methods = options.methods ?? await loadMethodsWasm();
+  if (typeof methods.loadModule === 'function') {
+    await methods.loadModule();
+  }
+
+  const input = coerceDataset(dataset);
+  const plan = parseExecutionPlan(definition);
+  const split = computeSplit(methods, plan.splitter, input);
+  const train = selectRows(input.X, input.rows, input.cols, split.trainIndices);
+  const test = selectRows(input.X, input.rows, input.cols, split.testIndices);
+  const yTrain = selectRows(input.y, input.rows, 1, split.trainIndices);
+  const yTest = selectRows(input.y, input.rows, 1, split.testIndices);
+
+  let XTrain = train;
+  let XTest = test;
+  const preprocessing = [];
+
+  for (const step of plan.preprocessing) {
+    const op = methods.ppCreate(step.type, step.params);
+    try {
+      methods.ppFit(op, XTrain.data, XTrain.rows, XTrain.cols);
+      XTrain = {
+        data: methods.ppTransform(op, XTrain.data, XTrain.rows, XTrain.cols),
+        rows: XTrain.rows,
+        cols: XTrain.cols,
+      };
+      XTest = {
+        data: methods.ppTransform(op, XTest.data, XTest.rows, XTest.cols),
+        rows: XTest.rows,
+        cols: XTest.cols,
+      };
+      preprocessing.push({ type: step.type, params: step.params });
+    } finally {
+      methods.ppDestroy(op);
+    }
+  }
+
+  const candidates = plan.nComponents.map((nComponents) => {
+    const model = methods.fitPls(
+      { data: XTrain.data, rows: XTrain.rows, cols: XTrain.cols },
+      { data: yTrain.data, rows: yTrain.rows, cols: 1 },
+      nComponents,
+    );
+    const predicted = methods.predictPls(model, {
+      data: XTest.data,
+      rows: XTest.rows,
+      cols: XTest.cols,
+    });
+    const predictions = Array.from(predicted.data);
+    const targets = Array.from(yTest.data);
+    return {
+      n_components: nComponents,
+      rmse: rmse(predictions, targets),
+      predictions,
+      model: serializePlsModel(model, nComponents),
+    };
+  });
+
+  const selected = candidates.reduce((best, item) => (item.rmse < best.rmse ? item : best), candidates[0]);
+  const variants = candidates.map(stripVariantModel);
+
+  return {
+    name: definition.name,
+    rows: input.rows,
+    cols: input.cols,
+    split,
+    preprocessing,
+    variants,
+    selected: stripVariantModel(selected),
+    model: selected.model,
+    targets: Array.from(yTest.data),
+  };
+}
+
+export async function predictPortablePipeline(fitted, dataset, options = {}) {
+  if (!fitted || typeof fitted !== 'object') {
+    throw new TypeError('Portable prediction requires a fitted portable pipeline result.');
+  }
+  const methods = options.methods ?? await loadMethodsWasm();
+  if (typeof methods.loadModule === 'function') {
+    await methods.loadModule();
+  }
+
+  let X = coerceFeatures(dataset);
+  for (const step of fitted.preprocessing ?? []) {
+    const op = methods.ppCreate(step.type, step.params ?? []);
+    try {
+      methods.ppFit(op, X.data, X.rows, X.cols);
+      X = {
+        data: methods.ppTransform(op, X.data, X.rows, X.cols),
+        rows: X.rows,
+        cols: X.cols,
+      };
+    } finally {
+      methods.ppDestroy(op);
+    }
+  }
+
+  const model = hydratePlsModel(fitted.model ?? fitted.selected?.model);
+  const predicted = methods.predictPls(model, {
+    data: X.data,
+    rows: X.rows,
+    cols: X.cols,
+  });
+  return {
+    data: Array.from(predicted.data),
+    rows: predicted.rows,
+    cols: predicted.cols,
+  };
+}
+
+export function parseExecutionPlan(source) {
+  const definition = source && Array.isArray(source.pipeline) ? source : loadPipelineDefinition(source);
+  let splitter = null;
+  const preprocessing = [];
+  let modelStep = null;
+
+  for (const step of definition.pipeline) {
+    if (!step || typeof step !== 'object' || Array.isArray(step)) {
+      throw new TypeError('Portable pipeline steps must be mapping objects.');
+    }
+
+    if (typeof step.class === 'string') {
+      if (KENNARD_STONE.has(step.class)) {
+        splitter = { type: 'KennardStone', params: step.params ?? {} };
+      } else if (SNV.has(step.class)) {
+        preprocessing.push({ type: 'StandardNormalVariate', params: [] });
+      } else if (SAVGOL.has(step.class)) {
+        preprocessing.push({ type: 'SavitzkyGolay', params: savgolParams(step.params ?? {}) });
+      } else {
+        throw new Error(`Portable execution does not support step class '${step.class}'.`);
+      }
+      continue;
+    }
+
+    if (step.model && typeof step.model === 'object') {
+      if (modelStep) {
+        throw new Error('Portable execution supports exactly one model step.');
+      }
+      modelStep = step;
+      continue;
+    }
+
+    throw new Error(`Portable execution does not support pipeline step: ${JSON.stringify(step)}`);
+  }
+
+  if (!modelStep) {
+    throw new Error('Portable execution requires a PLSRegression model step.');
+  }
+  const model = modelStep.model;
+  if (!PLS.has(model.class)) {
+    throw new Error(`Portable execution does not support model class '${model.class}'.`);
+  }
+
+  return {
+    splitter,
+    preprocessing,
+    nComponents: componentValues(modelStep),
+  };
+}
+
+function coerceDataset(dataset) {
+  if (!dataset || typeof dataset !== 'object') {
+    throw new TypeError('Portable execution requires a dataset object.');
+  }
+  const rows = Number(dataset.rows ?? dataset.n_samples ?? 0);
+  const cols = Number(dataset.cols ?? dataset.n_features ?? 0);
+  const X = flattenMatrix(dataset.X, rows, cols, 'X');
+  const y = flattenMatrix(dataset.y, rows, 1, 'y');
+  return { X, y, rows, cols };
+}
+
+function coerceFeatures(dataset) {
+  if (!dataset || typeof dataset !== 'object') {
+    throw new TypeError('Portable prediction requires a feature dataset object.');
+  }
+  const rows = Number(dataset.rows ?? dataset.n_samples ?? 0);
+  const cols = Number(dataset.cols ?? dataset.n_features ?? 0);
+  const X = flattenMatrix(dataset.X, rows, cols, 'X');
+  return { data: X, rows, cols };
+}
+
+function flattenMatrix(value, rows, cols, label) {
+  if (!Number.isInteger(rows) || rows <= 0 || !Number.isInteger(cols) || cols <= 0) {
+    throw new TypeError(`Dataset ${label} shape must provide positive integer rows/cols.`);
+  }
+  if (value instanceof Float64Array) {
+    if (value.length !== rows * cols) {
+      throw new RangeError(`Dataset ${label} length ${value.length} does not match ${rows}x${cols}.`);
+    }
+    return value;
+  }
+  if (Array.isArray(value) && Array.isArray(value[0])) {
+    const out = new Float64Array(rows * cols);
+    for (let r = 0; r < rows; r += 1) {
+      for (let c = 0; c < cols; c += 1) {
+        out[r * cols + c] = Number(value[r][c]);
+      }
+    }
+    return out;
+  }
+  if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+    if (value.length !== rows * cols) {
+      throw new RangeError(`Dataset ${label} length ${value.length} does not match ${rows}x${cols}.`);
+    }
+    return Float64Array.from(value);
+  }
+  throw new TypeError(`Dataset ${label} must be a Float64Array, a flat array, or a nested row array.`);
+}
+
+function computeSplit(methods, splitter, input) {
+  if (!splitter) {
+    const indices = Array.from({ length: input.rows }, (_, i) => i);
+    return { kind: 'all', trainIndices: indices, testIndices: indices };
+  }
+  const splitOptions = { testSize: numberParam(splitter.params.test_size, 0.25) };
+  if (typeof methods.computeSplitIndices === 'function') {
+    const split = methods.computeSplitIndices(
+      'KennardStone',
+      { data: input.X, rows: input.rows, cols: input.cols },
+      null,
+      splitOptions,
+    );
+    return {
+      kind: 'KennardStone',
+      trainIndices: Array.from(split.trainIndices),
+      testIndices: Array.from(split.testIndices),
+    };
+  }
+  const mask = methods.computeSplit(
+    'KennardStone',
+    { data: input.X, rows: input.rows, cols: input.cols },
+    { data: input.y, rows: input.rows, cols: 1 },
+    splitOptions,
+  );
+  const trainIndices = [];
+  const testIndices = [];
+  for (let i = 0; i < mask.length; i += 1) {
+    if (mask[i]) testIndices.push(i);
+    else trainIndices.push(i);
+  }
+  return { kind: 'KennardStone', trainIndices, testIndices };
+}
+
+function selectRows(data, rows, cols, indices) {
+  const out = new Float64Array(indices.length * cols);
+  for (let r = 0; r < indices.length; r += 1) {
+    const source = indices[r];
+    if (source < 0 || source >= rows) {
+      throw new RangeError(`Row index ${source} is outside 0..${rows - 1}.`);
+    }
+    out.set(data.subarray(source * cols, source * cols + cols), r * cols);
+  }
+  return { data: out, rows: indices.length, cols };
+}
+
+function savgolParams(params) {
+  const delta = numberParam(params.delta, 1);
+  if (delta !== 1) {
+    throw new Error('Portable Savitzky-Golay execution currently supports delta=1 only.');
+  }
+  return [
+    numberParam(params.window_length ?? params.window, 11),
+    numberParam(params.polyorder, 3),
+    numberParam(params.deriv, 0),
+    // scipy.signal.savgol_filter, and therefore nirs4all Python, default to interp.
+    savgolMode(params.mode ?? 'interp'),
+    numberParam(params.cval, 0),
+  ];
+}
+
+const SAVGOL_MODES = new Map([
+  ['mirror', 0],
+  ['constant', 1],
+  ['nearest', 2],
+  ['wrap', 3],
+  ['interp', 4],
+]);
+
+function savgolMode(value) {
+  if (typeof value === 'string') {
+    const mode = SAVGOL_MODES.get(value.toLowerCase());
+    if (mode != null) {
+      return mode;
+    }
+    throw new Error(`Unsupported Savitzky-Golay mode: ${value}`);
+  }
+  const mode = Number(value);
+  if (Number.isInteger(mode) && mode >= 0 && mode <= 4) {
+    return mode;
+  }
+  throw new Error(`Unsupported Savitzky-Golay mode: ${value}`);
+}
+
+function componentValues(step) {
+  if (Array.isArray(step._range_)) {
+    if (step.param !== 'n_components') {
+      throw new Error("Portable execution only supports _range_ sweeps over 'n_components'.");
+    }
+    const [start, stop, stride] = step._range_.map(Number);
+    if (![start, stop, stride].every(Number.isFinite) || stride <= 0 || start > stop) {
+      throw new Error('Invalid n_components _range_; expected [start, stop, positive_step].');
+    }
+    const values = [];
+    for (let value = start; value <= stop; value += stride) {
+      values.push(Math.round(value));
+    }
+    return values;
+  }
+  const params = step.model?.params ?? {};
+  return [Math.max(1, Math.round(numberParam(params.n_components, 2)))];
+}
+
+function numberParam(value, fallback) {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function rmse(predictions, targets) {
+  if (predictions.length !== targets.length) {
+    throw new RangeError('Prediction/target length mismatch.');
+  }
+  let sum = 0;
+  for (let i = 0; i < predictions.length; i += 1) {
+    const diff = predictions[i] - targets[i];
+    sum += diff * diff;
+  }
+  return Math.sqrt(sum / predictions.length);
+}
+
+function stripVariantModel(variant) {
+  return {
+    n_components: variant.n_components,
+    rmse: variant.rmse,
+    predictions: variant.predictions,
+  };
+}
+
+function serializePlsModel(model, nComponents) {
+  if (!model || typeof model !== 'object') {
+    throw new TypeError('nirs4all-methods returned an invalid PLS model.');
+  }
+  return {
+    type: 'PLSRegression',
+    n_components: nComponents,
+    coefficients: serializeVector(model.coefficients),
+    xMean: serializeVector(model.xMean),
+    yMean: serializeVector(model.yMean),
+    intercept: model.intercept == null ? null : serializeVector(model.intercept),
+    n_features: Number(model.n_features),
+    n_targets: Number(model.n_targets),
+  };
+}
+
+function hydratePlsModel(model) {
+  if (!model || typeof model !== 'object') {
+    throw new TypeError('Portable prediction requires a serialized PLS model.');
+  }
+  return {
+    coefficients: Float64Array.from(model.coefficients ?? []),
+    xMean: Float64Array.from(model.xMean ?? model.x_mean ?? []),
+    yMean: Float64Array.from(model.yMean ?? model.y_mean ?? []),
+    intercept: model.intercept == null ? null : Float64Array.from(model.intercept),
+    n_features: Number(model.n_features),
+    n_targets: Number(model.n_targets),
+  };
+}
+
+function serializeVector(value) {
+  if (value == null) return [];
+  if (typeof value === 'number') return [value];
+  return Array.from(value);
+}

package/src/index.d.ts

@@ -0,0 +1,111 @@
+export interface Upstream {
+  key: 'dag_ml' | 'dag_ml_data' | 'formats' | 'io' | 'datasets' | 'methods';
+  candidates: readonly string[];
+  role: string;
+}
+
+export interface UpstreamProxy {
+  key: Upstream['key'];
+  import(): Promise<unknown>;
+}
+
+export interface PipelineDefinition {
+  name: string;
+  description: string;
+  random_state?: number;
+  pipeline: unknown[];
+}
+
+export interface PortableMatrixDataset {
+  X: Float64Array | number[] | readonly number[] | readonly (readonly number[])[];
+  y: Float64Array | number[] | readonly number[] | readonly (readonly number[])[];
+  rows?: number;
+  cols?: number;
+  n_samples?: number;
+  n_features?: number;
+}
+
+export interface PortableSplitResult {
+  kind: 'all' | 'KennardStone';
+  trainIndices: number[];
+  testIndices: number[];
+}
+
+export interface PortableVariantResult {
+  n_components: number;
+  rmse: number;
+  predictions: number[];
+}
+
+export interface PortablePlsModel {
+  type: 'PLSRegression';
+  n_components: number;
+  coefficients: number[];
+  xMean: number[];
+  yMean: number[];
+  intercept: number[] | null;
+  n_features: number;
+  n_targets: number;
+}
+
+export interface PortableExecutionResult {
+  name: string;
+  rows: number;
+  cols: number;
+  split: PortableSplitResult;
+  preprocessing: { type: string; params: number[] }[];
+  variants: PortableVariantResult[];
+  selected: PortableVariantResult;
+  model: PortablePlsModel;
+  targets: number[];
+}
+
+export interface PortablePredictionResult {
+  data: number[];
+  rows: number;
+  cols: number;
+}
+
+export const upstreams: readonly Upstream[];
+export const portableOperatorClasses: readonly string[];
+
+export function upstream(name: string): Upstream | null;
+export function importUpstream(name: string): Promise<unknown>;
+export function loadFormats(): Promise<unknown>;
+export function loadIo(): Promise<unknown>;
+export function loadDatasets(): Promise<unknown>;
+export function loadMethods(): Promise<unknown>;
+export function loadDagMl(): Promise<unknown>;
+export function loadDagMlData(): Promise<unknown>;
+export function loadPortableStack(keys?: readonly string[]): Promise<Record<string, unknown>>;
+export function loadMethodsWasm(): Promise<unknown>;
+export function methodsWasm(): unknown;
+export function loadDagMlWasm(): Promise<unknown>;
+export function loadDagMlDataWasm(): Promise<unknown>;
+export function loadDatasetsWasm(): Promise<unknown>;
+export function loadDataIoWasm(): Promise<{ formats: unknown; io: unknown }>;
+
+export const formats: UpstreamProxy;
+export const io: UpstreamProxy;
+export const datasets: UpstreamProxy;
+export const methods: UpstreamProxy;
+export const dagMl: UpstreamProxy;
+export const dagMlData: UpstreamProxy;
+
+export function loadPipelineDefinition(source: string | unknown[] | Record<string, unknown>): PipelineDefinition;
+export function portableClassNames(definition: PipelineDefinition | unknown[] | Record<string, unknown>): string[];
+export function parseExecutionPlan(source: string | PipelineDefinition | unknown[] | Record<string, unknown>): {
+  splitter: { type: 'KennardStone'; params: Record<string, unknown> } | null;
+  preprocessing: { type: 'StandardNormalVariate' | 'SavitzkyGolay'; params: number[] }[];
+  nComponents: number[];
+};
+export function runPortablePipeline(
+  source: string | PipelineDefinition | unknown[] | Record<string, unknown>,
+  dataset: PortableMatrixDataset,
+  options?: { methods?: unknown },
+): Promise<PortableExecutionResult>;
+export function predictPortablePipeline(
+  fitted: PortableExecutionResult | { preprocessing?: { type: string; params: number[] }[]; model?: PortablePlsModel },
+  dataset: Omit<PortableMatrixDataset, 'y'>,
+  options?: { methods?: unknown },
+): Promise<PortablePredictionResult>;

package/src/index.js

@@ -0,0 +1,280 @@
+import { parse as parseYaml } from 'yaml';
+
+export const upstreams = Object.freeze([
+  {
+    key: 'dag_ml',
+    candidates: ['dag-ml-wasm'],
+    role: 'Leakage-safe DAG/ML execution coordinator',
+  },
+  {
+    key: 'dag_ml_data',
+    candidates: ['dag-ml-data-wasm'],
+    role: 'Sample-aligned data contracts for DAG/ML runtimes',
+  },
+  {
+    key: 'formats',
+    candidates: ['nirs4all-formats-wasm'],
+    role: 'Spectroscopy/NIRS vendor file readers',
+  },
+  {
+    key: 'io',
+    candidates: ['nirs4all-io-wasm'],
+    role: 'Dataset assembly bridge',
+  },
+  {
+    key: 'datasets',
+    candidates: ['@nirs4all/datasets-wasm'],
+    role: 'DOI-pinned NIRS dataset catalog',
+  },
+  {
+    key: 'methods',
+    candidates: ['@nirs4all/methods-wasm'],
+    role: 'Portable C ABI PLS/NIRS numerical engine',
+  },
+]);
+
+export const portableOperatorClasses = Object.freeze([
+  'nirs4all.operators.splitters.KennardStoneSplitter',
+  'nirs4all.operators.splitters.splitters.KennardStoneSplitter',
+  'nirs4all.operators.transforms.SNV',
+  'nirs4all.operators.transforms.StandardNormalVariate',
+  'nirs4all.operators.transforms.scalers.StandardNormalVariate',
+  'nirs4all.operators.transforms.SavitzkyGolay',
+  'nirs4all.operators.transforms.nirs.SavitzkyGolay',
+  'sklearn.cross_decomposition.PLSRegression',
+  'sklearn.cross_decomposition._pls.PLSRegression',
+]);
+
+const portableOperatorSet = new Set(portableOperatorClasses);
+
+const upstreamByKey = new Map(upstreams.map((item) => [item.key, item]));
+
+export function upstream(name) {
+  return upstreamByKey.get(name) ?? null;
+}
+
+export async function importUpstream(name) {
+  const item = upstream(name);
+  if (!item) {
+    throw new Error(`Unknown nirs4all upstream: ${name}`);
+  }
+
+  for (const candidate of item.candidates) {
+    try {
+      return await importUpstreamCandidate(candidate);
+    } catch (error) {
+      if (isMissingModuleError(error)) {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error(
+    `nirs4all upstream '${name}' is not installed. Tried ${item.candidates.join(', ')}.`,
+  );
+}
+
+export const formats = Object.freeze({ key: 'formats', import: () => importUpstream('formats') });
+export const io = Object.freeze({ key: 'io', import: () => importUpstream('io') });
+export const datasets = Object.freeze({ key: 'datasets', import: () => importUpstream('datasets') });
+export const methods = Object.freeze({ key: 'methods', import: () => importUpstream('methods') });
+export const dagMl = Object.freeze({ key: 'dag_ml', import: () => importUpstream('dag_ml') });
+export const dagMlData = Object.freeze({
+  key: 'dag_ml_data',
+  import: () => importUpstream('dag_ml_data'),
+});
+
+export const loadFormats = () => importUpstream('formats');
+export const loadIo = () => importUpstream('io');
+export const loadDatasets = () => importUpstream('datasets');
+export const loadMethods = () => importUpstream('methods');
+export const loadDagMl = () => importUpstream('dag_ml');
+export const loadDagMlData = () => importUpstream('dag_ml_data');
+
+let methodsPromise = null;
+let methodsModule = null;
+
+export async function loadMethodsWasm() {
+  if (!methodsPromise) {
+    methodsPromise = (async () => {
+      const mod = await loadMethods();
+      if (typeof mod.loadModule === 'function') {
+        await mod.loadModule();
+      }
+      methodsModule = mod;
+      return mod;
+    })();
+  }
+  return methodsPromise;
+}
+
+export function methodsWasm() {
+  if (!methodsModule) {
+    throw new Error('nirs4all methods WASM is not loaded; call loadMethodsWasm() first.');
+  }
+  return methodsModule;
+}
+
+function initializedWasmLoader(load, init) {
+  let promise = null;
+  return async () => {
+    if (!promise) {
+      promise = (async () => {
+        const mod = await load();
+        if (typeof init === 'function') {
+          await init(mod);
+        } else if (typeof mod.default === 'function') {
+          await mod.default();
+        }
+        return mod;
+      })();
+    }
+    return promise;
+  };
+}
+
+export const loadDagMlWasm = initializedWasmLoader(loadDagMl);
+export const loadDagMlDataWasm = initializedWasmLoader(loadDagMlData);
+export const loadDatasetsWasm = initializedWasmLoader(loadDatasets);
+
+export async function loadDataIoWasm() {
+  const [formatsMod, ioMod] = await Promise.all([
+    initializedFormatsWasm(),
+    initializedIoWasm(),
+  ]);
+  return { formats: formatsMod, io: ioMod };
+}
+
+const initializedFormatsWasm = initializedWasmLoader(loadFormats);
+const initializedIoWasm = initializedWasmLoader(loadIo);
+
+export async function loadPortableStack(keys = upstreams.map((item) => item.key)) {
+  const loaded = {};
+  for (const key of keys) {
+    loaded[key] = await importUpstream(key);
+  }
+  return loaded;
+}
+
+export function loadPipelineDefinition(source) {
+  const data = typeof source === 'string' ? parsePipelineText(source) : clone(source);
+  const normalized = normalizePipelineRoot(data);
+  const pipeline = normalized.pipeline;
+  if (!Array.isArray(pipeline)) {
+    throw new Error("Pipeline definition key 'pipeline' or 'steps' must contain an array of steps.");
+  }
+
+  const definition = {
+    name: String(normalized.name || 'pipeline'),
+    description: String(normalized.description || ''),
+    pipeline: stripComments(pipeline),
+  };
+  if (Number.isInteger(normalized.random_state)) {
+    definition.random_state = normalized.random_state;
+  }
+
+  const unsupported = portableClassNames(definition).filter((name) => !portableOperatorSet.has(name));
+  if (unsupported.length > 0) {
+    throw new Error(
+      `Pipeline uses operators outside the current nirs4all-lite portable subset: ${[...new Set(unsupported)].join(', ')}`,
+    );
+  }
+
+  return definition;
+}
+
+export function portableClassNames(definition) {
+  const root = definition && Array.isArray(definition.pipeline) ? definition.pipeline : definition;
+  const classes = [];
+  collectClasses(root, classes);
+  return classes;
+}
+
+function isMissingModuleError(error) {
+  return error && (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED');
+}
+
+function importUpstreamCandidate(candidate) {
+  switch (candidate) {
+    case 'dag-ml-wasm':
+      return import('dag-ml-wasm');
+    case 'dag-ml-data-wasm':
+      return import('dag-ml-data-wasm');
+    case 'nirs4all-formats-wasm':
+      return import('nirs4all-formats-wasm');
+    case 'nirs4all-io-wasm':
+      return import('nirs4all-io-wasm');
+    case '@nirs4all/datasets-wasm':
+      return import('@nirs4all/datasets-wasm');
+    case '@nirs4all/methods-wasm':
+      return import('@nirs4all/methods-wasm');
+    default:
+      return import(candidate);
+  }
+}
+
+function parsePipelineText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return parseYaml(text);
+  }
+}
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function normalizePipelineRoot(data) {
+  if (Array.isArray(data)) {
+    return { pipeline: data };
+  }
+  if (!data || typeof data !== 'object') {
+    throw new TypeError("Pipeline definition must be an array or an object with a 'pipeline'/'steps' key.");
+  }
+  if (data.pipeline !== undefined) {
+    return data;
+  }
+  if (data.steps !== undefined) {
+    return { ...data, pipeline: data.steps };
+  }
+  throw new Error("Invalid pipeline definition format. Expected an array or an object with a 'pipeline' or 'steps' key.");
+}
+
+function stripComments(value) {
+  if (Array.isArray(value)) {
+    return value.filter((item) => !isCommentStep(item)).map(stripComments);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([key]) => key !== '_comment')
+        .map(([key, item]) => [key, stripComments(item)]),
+    );
+  }
+  return value;
+}
+
+function isCommentStep(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 1 && value._comment !== undefined;
+}
+
+function collectClasses(value, output) {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectClasses(item, output);
+    }
+    return;
+  }
+  if (value && typeof value === 'object') {
+    if (typeof value.class === 'string') {
+      output.push(value.class);
+    }
+    for (const item of Object.values(value)) {
+      collectClasses(item, output);
+    }
+  }
+}
+
+export { parseExecutionPlan, predictPortablePipeline, runPortablePipeline } from './execution.js';