From 9bf8e0bb21b9867760eb86ff5a94c702830f1b81 Mon Sep 17 00:00:00 2001 From: Reuven Cohen Date: Wed, 11 Nov 2026 17:40:44 +0000 Subject: [PATCH 01/19] feat: add shared e-means clustering and ecosystem integrations --- Cargo.lock | 14 + Cargo.toml | 2 + crates/ruvector-core/Cargo.toml | 2 + crates/ruvector-core/src/quantization.rs | 93 +- .../tests/e_means_quantization.rs | 129 ++ crates/ruvector-e-means/Cargo.toml | 29 + crates/ruvector-e-means/LICENSE | 21 + crates/ruvector-e-means/README.md | 32 + crates/ruvector-e-means/examples/benchmark.rs | 177 ++ crates/ruvector-e-means/src/config.rs | 115 ++ crates/ruvector-e-means/src/distance.rs | 189 ++ crates/ruvector-e-means/src/ivf.rs | 155 ++ crates/ruvector-e-means/src/lib.rs | 81 + crates/ruvector-e-means/src/quantization.rs | 181 ++ crates/ruvector-e-means/src/trainer.rs | 242 +++ crates/ruvector-e-means/src/wasm.rs | 92 + crates/ruvector-e-means/tests/clustering.rs | 234 +++ crates/ruvector-e-means/tests/ivf.rs | 103 ++ crates/ruvector-e-means/tests/quantization.rs | 113 ++ crates/ruvector-pq-search/Cargo.toml | 1 + crates/ruvector-pq-search/src/codebook.rs | 53 +- crates/ruvector-pq-search/src/ivf_pq.rs | 60 +- crates/ruvector-pq-search/tests/e_means.rs | 73 + crates/ruvector-rairs/Cargo.toml | 1 + crates/ruvector-rairs/src/ivf.rs | 64 + crates/ruvector-rairs/src/rairs.rs | 20 + crates/ruvector-rairs/src/seil.rs | 20 + crates/ruvector-rairs/tests/e_means.rs | 114 ++ crates/ruvector-wasm/clustering.d.mts | 2 + crates/ruvector-wasm/clustering.mjs | 2 + .../ruvector-wasm/clustering/cloudflare.d.mts | 1 + .../ruvector-wasm/clustering/cloudflare.mjs | 1 + crates/ruvector-wasm/clustering/ivf.d.mts | 1 + crates/ruvector-wasm/clustering/ivf.mjs | 1 + .../clustering/metaharness.d.mts | 1 + .../ruvector-wasm/clustering/metaharness.mjs | 1 + .../clustering/quantization.d.mts | 1 + .../ruvector-wasm/clustering/quantization.mjs | 1 + crates/ruvector-wasm/package.json | 28 +- docs/adr/ADR-359-e-means-shared-clustering.md | 226 +++ .../ADR-360-e-means-ecosystem-integrations.md | 184 ++ docs/adr/INDEX.md | 17 +- .../e-means/integrations-qualification.json | 70 + .../e-means/performance-2026-11-11.json | 406 +++++ npm/package-lock.json | 1539 ++++++++++++++++- npm/package.json | 4 + npm/packages/all/clustering.d.mts | 2 + npm/packages/all/clustering.mjs | 2 + npm/packages/all/clustering/cloudflare.d.mts | 1 + npm/packages/all/clustering/cloudflare.mjs | 1 + npm/packages/all/clustering/ivf.d.mts | 1 + npm/packages/all/clustering/ivf.mjs | 1 + npm/packages/all/clustering/metaharness.d.mts | 1 + npm/packages/all/clustering/metaharness.mjs | 1 + .../all/clustering/quantization.d.mts | 1 + npm/packages/all/clustering/quantization.mjs | 1 + npm/packages/all/package.json | 6 +- npm/packages/core/clustering.d.mts | 2 + npm/packages/core/clustering.mjs | 2 + npm/packages/core/clustering/cloudflare.d.mts | 1 + npm/packages/core/clustering/cloudflare.mjs | 1 + npm/packages/core/clustering/ivf.d.mts | 1 + npm/packages/core/clustering/ivf.mjs | 1 + .../core/clustering/metaharness.d.mts | 1 + npm/packages/core/clustering/metaharness.mjs | 1 + .../core/clustering/quantization.d.mts | 1 + npm/packages/core/clustering/quantization.mjs | 1 + npm/packages/core/package.json | 6 +- npm/packages/e-means/.gitignore | 2 + npm/packages/e-means/LICENSE | 21 + npm/packages/e-means/README.md | 98 ++ npm/packages/e-means/e-means.d.ts | 33 + npm/packages/e-means/e-means.mjs | 29 + .../e-means/examples/cloudflare/build.d.ts | 5 + .../e-means/examples/cloudflare/build.mjs | 23 + .../e-means/examples/cloudflare/worker.mjs | 9 + .../examples/cloudflare/wrangler.jsonc | 9 + npm/packages/e-means/examples/metaharness.mjs | 16 + .../e-means/integrations/cloudflare.d.ts | 58 + .../e-means/integrations/cloudflare.mjs | 72 + .../e-means/integrations/cloudflare/http.mjs | 59 + .../integrations/cloudflare/storage.mjs | 78 + .../integrations/cloudflare/validation.mjs | 107 ++ .../integrations/clustering-validation.mjs | 111 ++ npm/packages/e-means/integrations/ivf.d.ts | 16 + npm/packages/e-means/integrations/ivf.mjs | 63 + .../e-means/integrations/metaharness.d.ts | 115 ++ .../e-means/integrations/metaharness.mjs | 151 ++ .../e-means/integrations/quantization.d.ts | 29 + .../e-means/integrations/quantization.mjs | 144 ++ npm/packages/e-means/package-lock.json | 1534 ++++++++++++++++ npm/packages/e-means/package.json | 108 ++ npm/packages/e-means/runtime.d.ts | 4 + npm/packages/e-means/runtime.mjs | 96 + npm/packages/e-means/scripts/build.mjs | 23 + .../e-means/scripts/check-artifact.mjs | 11 + npm/packages/e-means/test/benchmark.mjs | 111 ++ .../e-means/test/browser-consumer.mjs | 90 + .../e-means/test/cloudflare-storage.test.mjs | 108 ++ .../e-means/test/cloudflare-tsconfig.json | 12 + npm/packages/e-means/test/cloudflare-types.ts | 25 + .../e-means/test/cloudflare-workerd.test.mjs | 83 + npm/packages/e-means/test/cloudflare.test.mjs | 96 + npm/packages/e-means/test/e-means.test.mjs | 135 ++ .../e-means/test/ecosystem-consumers.mjs | 99 ++ npm/packages/e-means/test/ivf.test.mjs | 60 + .../e-means/test/metaharness.test.mjs | 128 ++ npm/packages/e-means/test/packed-consumer.mjs | 88 + .../e-means/test/quantization-types.mts | 19 + .../e-means/test/quantization.test.mjs | 114 ++ npm/packages/e-means/test/runtime.test.mjs | 40 + npm/packages/e-means/test/tsconfig.json | 12 + .../e-means/test/typed-bridge.test.mjs | 70 + npm/packages/e-means/test/types.ts | 32 + npm/packages/e-means/wasm-module.d.ts | 3 + .../e-means/wasm/ruvector_e_means.d.ts | 83 + npm/packages/e-means/wasm/ruvector_e_means.js | 456 +++++ .../e-means/wasm/ruvector_e_means_bg.wasm | Bin 0 -> 142782 bytes .../wasm/ruvector_e_means_bg.wasm.d.ts | 19 + npm/packages/ruvector/clustering.d.mts | 2 + npm/packages/ruvector/clustering.mjs | 2 + .../ruvector/clustering/cloudflare.d.mts | 1 + .../ruvector/clustering/cloudflare.mjs | 1 + npm/packages/ruvector/clustering/ivf.d.mts | 1 + npm/packages/ruvector/clustering/ivf.mjs | 1 + .../ruvector/clustering/metaharness.d.mts | 1 + .../ruvector/clustering/metaharness.mjs | 1 + .../ruvector/clustering/quantization.d.mts | 1 + .../ruvector/clustering/quantization.mjs | 1 + npm/packages/ruvector/package.json | 11 +- npm/packages/ruvector/test/e-means.mjs | 10 + 131 files changed, 9851 insertions(+), 21 deletions(-) create mode 100644 crates/ruvector-core/tests/e_means_quantization.rs create mode 100644 crates/ruvector-e-means/Cargo.toml create mode 100644 crates/ruvector-e-means/LICENSE create mode 100644 crates/ruvector-e-means/README.md create mode 100644 crates/ruvector-e-means/examples/benchmark.rs create mode 100644 crates/ruvector-e-means/src/config.rs create mode 100644 crates/ruvector-e-means/src/distance.rs create mode 100644 crates/ruvector-e-means/src/ivf.rs create mode 100644 crates/ruvector-e-means/src/lib.rs create mode 100644 crates/ruvector-e-means/src/quantization.rs create mode 100644 crates/ruvector-e-means/src/trainer.rs create mode 100644 crates/ruvector-e-means/src/wasm.rs create mode 100644 crates/ruvector-e-means/tests/clustering.rs create mode 100644 crates/ruvector-e-means/tests/ivf.rs create mode 100644 crates/ruvector-e-means/tests/quantization.rs create mode 100644 crates/ruvector-pq-search/tests/e_means.rs create mode 100644 crates/ruvector-rairs/tests/e_means.rs create mode 100644 crates/ruvector-wasm/clustering.d.mts create mode 100644 crates/ruvector-wasm/clustering.mjs create mode 100644 crates/ruvector-wasm/clustering/cloudflare.d.mts create mode 100644 crates/ruvector-wasm/clustering/cloudflare.mjs create mode 100644 crates/ruvector-wasm/clustering/ivf.d.mts create mode 100644 crates/ruvector-wasm/clustering/ivf.mjs create mode 100644 crates/ruvector-wasm/clustering/metaharness.d.mts create mode 100644 crates/ruvector-wasm/clustering/metaharness.mjs create mode 100644 crates/ruvector-wasm/clustering/quantization.d.mts create mode 100644 crates/ruvector-wasm/clustering/quantization.mjs create mode 100644 docs/adr/ADR-359-e-means-shared-clustering.md create mode 100644 docs/adr/ADR-360-e-means-ecosystem-integrations.md create mode 100644 docs/research/e-means/integrations-qualification.json create mode 100644 docs/research/e-means/performance-2026-11-11.json create mode 100644 npm/packages/all/clustering.d.mts create mode 100644 npm/packages/all/clustering.mjs create mode 100644 npm/packages/all/clustering/cloudflare.d.mts create mode 100644 npm/packages/all/clustering/cloudflare.mjs create mode 100644 npm/packages/all/clustering/ivf.d.mts create mode 100644 npm/packages/all/clustering/ivf.mjs create mode 100644 npm/packages/all/clustering/metaharness.d.mts create mode 100644 npm/packages/all/clustering/metaharness.mjs create mode 100644 npm/packages/all/clustering/quantization.d.mts create mode 100644 npm/packages/all/clustering/quantization.mjs create mode 100644 npm/packages/core/clustering.d.mts create mode 100644 npm/packages/core/clustering.mjs create mode 100644 npm/packages/core/clustering/cloudflare.d.mts create mode 100644 npm/packages/core/clustering/cloudflare.mjs create mode 100644 npm/packages/core/clustering/ivf.d.mts create mode 100644 npm/packages/core/clustering/ivf.mjs create mode 100644 npm/packages/core/clustering/metaharness.d.mts create mode 100644 npm/packages/core/clustering/metaharness.mjs create mode 100644 npm/packages/core/clustering/quantization.d.mts create mode 100644 npm/packages/core/clustering/quantization.mjs create mode 100644 npm/packages/e-means/.gitignore create mode 100644 npm/packages/e-means/LICENSE create mode 100644 npm/packages/e-means/README.md create mode 100644 npm/packages/e-means/e-means.d.ts create mode 100644 npm/packages/e-means/e-means.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/build.d.ts create mode 100644 npm/packages/e-means/examples/cloudflare/build.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/worker.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/wrangler.jsonc create mode 100644 npm/packages/e-means/examples/metaharness.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare.d.ts create mode 100644 npm/packages/e-means/integrations/cloudflare.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/http.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/storage.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/validation.mjs create mode 100644 npm/packages/e-means/integrations/clustering-validation.mjs create mode 100644 npm/packages/e-means/integrations/ivf.d.ts create mode 100644 npm/packages/e-means/integrations/ivf.mjs create mode 100644 npm/packages/e-means/integrations/metaharness.d.ts create mode 100644 npm/packages/e-means/integrations/metaharness.mjs create mode 100644 npm/packages/e-means/integrations/quantization.d.ts create mode 100644 npm/packages/e-means/integrations/quantization.mjs create mode 100644 npm/packages/e-means/package-lock.json create mode 100644 npm/packages/e-means/package.json create mode 100644 npm/packages/e-means/runtime.d.ts create mode 100644 npm/packages/e-means/runtime.mjs create mode 100644 npm/packages/e-means/scripts/build.mjs create mode 100644 npm/packages/e-means/scripts/check-artifact.mjs create mode 100644 npm/packages/e-means/test/benchmark.mjs create mode 100644 npm/packages/e-means/test/browser-consumer.mjs create mode 100644 npm/packages/e-means/test/cloudflare-storage.test.mjs create mode 100644 npm/packages/e-means/test/cloudflare-tsconfig.json create mode 100644 npm/packages/e-means/test/cloudflare-types.ts create mode 100644 npm/packages/e-means/test/cloudflare-workerd.test.mjs create mode 100644 npm/packages/e-means/test/cloudflare.test.mjs create mode 100644 npm/packages/e-means/test/e-means.test.mjs create mode 100644 npm/packages/e-means/test/ecosystem-consumers.mjs create mode 100644 npm/packages/e-means/test/ivf.test.mjs create mode 100644 npm/packages/e-means/test/metaharness.test.mjs create mode 100644 npm/packages/e-means/test/packed-consumer.mjs create mode 100644 npm/packages/e-means/test/quantization-types.mts create mode 100644 npm/packages/e-means/test/quantization.test.mjs create mode 100644 npm/packages/e-means/test/runtime.test.mjs create mode 100644 npm/packages/e-means/test/tsconfig.json create mode 100644 npm/packages/e-means/test/typed-bridge.test.mjs create mode 100644 npm/packages/e-means/test/types.ts create mode 100644 npm/packages/e-means/wasm-module.d.ts create mode 100644 npm/packages/e-means/wasm/ruvector_e_means.d.ts create mode 100644 npm/packages/e-means/wasm/ruvector_e_means.js create mode 100644 npm/packages/e-means/wasm/ruvector_e_means_bg.wasm create mode 100644 npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts create mode 100644 npm/packages/ruvector/clustering.d.mts create mode 100644 npm/packages/ruvector/clustering.mjs create mode 100644 npm/packages/ruvector/clustering/cloudflare.d.mts create mode 100644 npm/packages/ruvector/clustering/cloudflare.mjs create mode 100644 npm/packages/ruvector/clustering/ivf.d.mts create mode 100644 npm/packages/ruvector/clustering/ivf.mjs create mode 100644 npm/packages/ruvector/clustering/metaharness.d.mts create mode 100644 npm/packages/ruvector/clustering/metaharness.mjs create mode 100644 npm/packages/ruvector/clustering/quantization.d.mts create mode 100644 npm/packages/ruvector/clustering/quantization.mjs create mode 100644 npm/packages/ruvector/test/e-means.mjs diff --git a/Cargo.lock b/Cargo.lock index 9067191dff..d8bc30ebb8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -9276,6 +9276,7 @@ dependencies = [ "rkyv", "rustc_version", "ruvector-core 2.5.1", + "ruvector-e-means", "ruvector-turboquant", "serde", "serde_json", @@ -9538,6 +9539,17 @@ dependencies = [ "wasm-bindgen-test", ] +[[package]] +name = "ruvector-e-means" +version = "0.1.0" +dependencies = [ + "rand_chacha 0.3.1", + "rand_core 0.6.4", + "serde", + "serde_json", + "wasm-bindgen", +] + [[package]] name = "ruvector-economy-wasm" version = "0.1.0" @@ -10409,6 +10421,7 @@ name = "ruvector-pq-search" version = "2.3.0" dependencies = [ "rand 0.8.6", + "ruvector-e-means", "serde", "serde_json", "thiserror 2.0.18", @@ -10513,6 +10526,7 @@ version = "0.1.0" dependencies = [ "criterion 0.5.1", "rand 0.8.6", + "ruvector-e-means", "serde", ] diff --git a/Cargo.toml b/Cargo.toml index e57eb682cc..adea40f9c4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -51,6 +51,8 @@ exclude = ["crates/prime-radiant", "patches/candle-core-0.8.4", "patches/candle- # unify with this workspace. The pure cores it wraps are members below. "edge", "edge/*"] members = [ + # Shared EMA clustering core and portable npm WASM engine (ADR-359). + "crates/ruvector-e-means", # ruvector Python SDK (ADR-352): PyO3 + maturin bindings. Salvaged from # the stale feature/python-sdk-m1 branch (M1 RaBitQ scope) and extended. "crates/ruvector-py", diff --git a/crates/ruvector-core/Cargo.toml b/crates/ruvector-core/Cargo.toml index 92d49a9c73..74724ff1fb 100644 --- a/crates/ruvector-core/Cargo.toml +++ b/crates/ruvector-core/Cargo.toml @@ -17,6 +17,8 @@ hnsw_rs = { workspace = true, optional = true } # Turbo4 codec + unified encoding plane (ADR-296/297). Dependency-free and # WASM-safe, so it is unconditional: the codec plane exists on every build. ruvector-turboquant = { version = "2.3.0", path = "../ruvector-turboquant" } +# Shared CPU/WASM e-means optimizer, used by the explicit PQ training API. +ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } simsimd = { workspace = true, optional = true } rayon = { workspace = true, optional = true } crossbeam = { workspace = true, optional = true } diff --git a/crates/ruvector-core/src/quantization.rs b/crates/ruvector-core/src/quantization.rs index 8d3ffed16b..d5714d7030 100644 --- a/crates/ruvector-core/src/quantization.rs +++ b/crates/ruvector-core/src/quantization.rs @@ -109,6 +109,83 @@ pub struct ProductQuantized { } impl ProductQuantized { + /// Train product-quantization codebooks with the shared e-means optimizer. + /// + /// `config.clusters` selects the number of entries in each codebook (1–256). + /// Every vector must have the same nonzero dimension, evenly divisible by + /// `num_subspaces`, and contain only finite values. The returned codebooks + /// use the same representation as [`Self::train`] and work with + /// [`Self::encode`]. No input vector is encoded until the caller requests it. + /// + /// This API is explicit because e-means' automatic hyperparameters were + /// fitted on large embedding datasets; callers training small PQ subspaces + /// can set `batch_size` and `peak_step` in the configuration. + pub fn train_e_means( + vectors: &[Vec], + num_subspaces: usize, + config: &ruvector_e_means::Config, + ) -> Result { + use crate::error::RuvectorError; + + let dimensions = vectors.first().map_or(0, Vec::len); + if vectors.is_empty() || dimensions == 0 { + return Err(RuvectorError::InvalidInput( + "e-means PQ training requires nonempty vectors".into(), + )); + } + if num_subspaces == 0 || dimensions % num_subspaces != 0 { + return Err(RuvectorError::InvalidParameter( + "Subspace count must be nonzero and divide vector dimensions".into(), + )); + } + if config.clusters == 0 || config.clusters > 256 || config.clusters > vectors.len() { + return Err(RuvectorError::InvalidParameter( + "Codebook size must be in 1..=256 and no greater than the vector count".into(), + )); + } + for vector in vectors { + if vector.len() != dimensions { + return Err(RuvectorError::DimensionMismatch { + expected: dimensions, + actual: vector.len(), + }); + } + if vector.iter().any(|value| !value.is_finite()) { + return Err(RuvectorError::InvalidInput( + "e-means PQ training vectors must contain only finite values".into(), + )); + } + } + + let subspace_dim = dimensions / num_subspaces; + let capacity = vectors.len().checked_mul(subspace_dim).ok_or_else(|| { + RuvectorError::InvalidInput("e-means PQ training shape overflows usize".into()) + })?; + let mut codebooks = Vec::with_capacity(num_subspaces); + let mut subspace_vectors = Vec::with_capacity(capacity); + for subspace_idx in 0..num_subspaces { + subspace_vectors.clear(); + let start = subspace_idx * subspace_dim; + for vector in vectors { + subspace_vectors.extend_from_slice(&vector[start..start + subspace_dim]); + } + let model = ruvector_e_means::fit(&subspace_vectors, subspace_dim, config) + .map_err(|error| RuvectorError::InvalidParameter(error.to_string()))?; + codebooks.push( + model + .centroids + .chunks_exact(subspace_dim) + .map(<[f32]>::to_vec) + .collect(), + ); + } + + Ok(Self { + codes: Vec::new(), + codebooks, + }) + } + /// Train product quantization on a set of vectors pub fn train( vectors: &[Vec], @@ -168,16 +245,22 @@ impl ProductQuantized { let start = subspace_idx * subspace_dim; let end = start + subspace_dim; let subvector = &vector[start..end]; + // Finite f32 embeddings can have squared distances above f32::MAX. + // Compare in f64 so those candidates retain their nearest ordering. + let squared_distance = |centroid: &[f32]| -> f64 { + subvector + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum() + }; // Find nearest centroid let code = codebook .iter() .enumerate() - .min_by(|(_, a), (_, b)| { - let dist_a = euclidean_squared(subvector, a); - let dist_b = euclidean_squared(subvector, b); - dist_a.partial_cmp(&dist_b).unwrap() - }) + .map(|(idx, centroid)| (idx, squared_distance(centroid))) + .min_by(|(_, a), (_, b)| a.total_cmp(b)) .map(|(idx, _)| idx as u8) .unwrap_or(0); diff --git a/crates/ruvector-core/tests/e_means_quantization.rs b/crates/ruvector-core/tests/e_means_quantization.rs new file mode 100644 index 0000000000..2fad64398e --- /dev/null +++ b/crates/ruvector-core/tests/e_means_quantization.rs @@ -0,0 +1,129 @@ +//! Integration evidence for the shared e-means PQ training path. + +use ruvector_core::error::RuvectorError; +use ruvector_core::ProductQuantized; +use ruvector_e_means::Config; + +fn config(clusters: usize) -> Config { + Config { + clusters, + epochs: 3, + seed: 17, + ..Config::default() + } +} + +#[test] +fn subspace_codebooks_recover_column_means_and_keep_the_existing_format() { + let vectors = vec![ + vec![1.0, 2.0, 10.0, 20.0], + vec![3.0, 4.0, 30.0, 40.0], + vec![5.0, 6.0, 50.0, 60.0], + ]; + let trained = ProductQuantized::train_e_means(&vectors, 2, &config(1)).unwrap(); + assert!(trained.codes.is_empty()); + assert_eq!( + trained.codebooks, + vec![vec![vec![3.0, 4.0]], vec![vec![30.0, 40.0]]] + ); + assert_eq!(trained.encode(&vectors[0]), vec![0, 0]); + + // Existing persisted PQ consumers use the same serde representation and + // reconstruct a vector by looking up each subspace's encoded centroid. + let json = serde_json::to_vec(&trained).unwrap(); + let restored: ProductQuantized = serde_json::from_slice(&json).unwrap(); + let codes = restored.encode(&vectors[2]); + let reconstructed: Vec = codes + .iter() + .enumerate() + .flat_map(|(subspace, &code)| restored.codebooks[subspace][code as usize].clone()) + .collect(); + assert_eq!(reconstructed, vec![3.0, 4.0, 30.0, 40.0]); +} + +#[test] +fn identical_seed_and_options_produce_identical_codebooks() { + let vectors: Vec> = (0..80) + .map(|i| vec![i as f32 / 10.0, (i % 7) as f32, -(i as f32), 2.0]) + .collect(); + let mut options = config(4); + options.batch_size = Some(7); // Exercise the final short batch. + let first = ProductQuantized::train_e_means(&vectors, 2, &options).unwrap(); + let second = ProductQuantized::train_e_means(&vectors, 2, &options).unwrap(); + assert_eq!(first.codebooks, second.codebooks); + assert_eq!(first.codebooks.len(), 2); + assert!(first.codebooks.iter().all(|book| book.len() == 4)); + assert!(first + .codebooks + .iter() + .flatten() + .all(|centroid| centroid.len() == 2 && centroid.iter().all(|v| v.is_finite()))); +} + +#[test] +fn maximum_u8_codebook_size_is_usable() { + let vectors: Vec> = (0..256).map(|i| vec![i as f32]).collect(); + let mut options = config(256); + options.epochs = 1; + options.batch_size = Some(256); + let trained = ProductQuantized::train_e_means(&vectors, 1, &options).unwrap(); + assert_eq!(trained.codebooks[0].len(), 256); + let codes: std::collections::BTreeSet = + vectors.iter().map(|v| trained.encode(v)[0]).collect(); + assert_eq!(codes.len(), 256); +} + +#[test] +fn large_finite_inputs_keep_the_nearest_centroid_when_squared_f32_distances_overflow() { + let magnitude = f32::MAX / 4.0; + let vectors = vec![vec![-magnitude], vec![magnitude]]; + let mut options = config(2); + options.epochs = 1; + options.batch_size = Some(2); + let trained = ProductQuantized::train_e_means(&vectors, 1, &options).unwrap(); + // Pick a query past the second centroid. Both candidate squared distances + // overflow f32, but the second remains strictly nearer in f64. + let query = trained.codebooks[0][1][0] * 2.0; + assert!(query.is_finite()); + for centroid in &trained.codebooks[0] { + assert!((query - centroid[0]).powi(2).is_infinite()); + } + assert_eq!(trained.encode(&[query]), vec![1]); +} + +#[test] +fn malformed_training_inputs_return_errors() { + let valid = vec![vec![1.0, 2.0, 3.0, 4.0], vec![2.0, 3.0, 4.0, 5.0]]; + for (vectors, subspaces) in [ + (Vec::new(), 1), + (vec![Vec::new()], 1), + (valid.clone(), 0), + (valid.clone(), 3), + (valid.clone(), 8), + (vec![valid[0].clone(), vec![1.0]], 2), + (vec![vec![f32::NAN, 0.0]], 1), + (vec![vec![f32::INFINITY, 0.0]], 1), + ] { + assert!(ProductQuantized::train_e_means(&vectors, subspaces, &config(1)).is_err()); + } + let error = + ProductQuantized::train_e_means(&[vec![1.0, 2.0], vec![1.0]], 1, &config(1)).unwrap_err(); + assert!(matches!(error, RuvectorError::DimensionMismatch { .. })); +} + +#[test] +fn invalid_optimizer_settings_return_errors() { + let vectors = vec![vec![1.0, 2.0], vec![3.0, 4.0]]; + for clusters in [0, 3, 257] { + assert!(ProductQuantized::train_e_means(&vectors, 1, &config(clusters)).is_err()); + } + let mut options = config(1); + options.epochs = 0; + assert!(ProductQuantized::train_e_means(&vectors, 1, &options).is_err()); + options = config(1); + options.batch_size = Some(0); + assert!(ProductQuantized::train_e_means(&vectors, 1, &options).is_err()); + options = config(1); + options.peak_step = Some(f64::NAN); + assert!(ProductQuantized::train_e_means(&vectors, 1, &options).is_err()); +} diff --git a/crates/ruvector-e-means/Cargo.toml b/crates/ruvector-e-means/Cargo.toml new file mode 100644 index 0000000000..a4905c1bff --- /dev/null +++ b/crates/ruvector-e-means/Cargo.toml @@ -0,0 +1,29 @@ +[package] +name = "ruvector-e-means" +version = "0.1.0" +edition = "2021" +rust-version = "1.81" +license = "MIT" +description = "Deterministic CPU and WebAssembly e-means clustering with EMA centroid updates" +repository = "https://github.com/ruvnet/ruvector" +keywords = ["clustering", "k-means", "ema", "quantization", "machine-learning"] +categories = ["algorithms", "science"] +include = ["src/**", "tests/**", "examples/**", "Cargo.toml", "LICENSE", "README.md"] + +[lib] +crate-type = ["rlib", "cdylib"] + +[features] +default = [] +serde = ["dep:serde"] +wasm = ["serde", "dep:serde_json", "dep:wasm-bindgen"] + +[dependencies] +rand_chacha = "0.3.1" +rand_core = "0.6.4" +serde = { version = "1.0", features = ["derive"], optional = true } +serde_json = { version = "1.0", optional = true } +wasm-bindgen = { version = "=0.2.125", optional = true } + +[dev-dependencies] +serde_json = "1.0" diff --git a/crates/ruvector-e-means/LICENSE b/crates/ruvector-e-means/LICENSE new file mode 100644 index 0000000000..2dd524ac38 --- /dev/null +++ b/crates/ruvector-e-means/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rUv + +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. diff --git a/crates/ruvector-e-means/README.md b/crates/ruvector-e-means/README.md new file mode 100644 index 0000000000..1f32a76191 --- /dev/null +++ b/crates/ruvector-e-means/README.md @@ -0,0 +1,32 @@ +# ruvector-e-means + +CPU reference implementation of [e-means (Bessa et al., 2026)](https://arxiv.org/abs/2611.09501), shared by RuVector and ruv-FANN. MIT-licensed original Rust implementation; no upstream implementation code is copied. + +```rust +use ruvector_e_means::{fit, Config}; +let data = [1.0f32, 2.0, 3.0, 4.0]; // two 2-dimensional rows +let config = Config { clusters: 1, ..Config::default() }; +let model = fit(&data, 2, &config)?; +assert_eq!(model.centroids, [2.0, 3.0]); +# Ok::<(), ruvector_e_means::Error>(()) +``` + +The implementation includes seeded random initialization, EMA counts/sums initialized at 1e-10, cosine scheduling, automatic batch/step scaling, weighted donor splitting every five updates, and final-epoch mean or main EMA finalization. Prediction and returned MSE use exact squared-L2 distances in original input order. All rows, including a partial final batch, are visited each epoch. Scratch memory is O(n + kd). Accumulation and distance arithmetic use f64; codebooks use f32. Extreme revival perturbations saturate to finite f32. Dead slots outnumbering available live donors wait for the next revival pass. + +Assignment prunes candidates once their partial squared distance cannot beat the current best, checking every eight coordinates above 16 dimensions. Small vectors retain the scalar path. A zero-distance winner stops the search. Ordered f64 addition and lowest-index ties are preserved. Training reuses revival scratch and omits last-epoch buffers in `Ema` mode. The npm bridge returns owned typed arrays and frees its temporary Rust model after materialization. + +Scaling laws were fitted on large, high-dimensional embeddings; override `batch_size` and `peak_step` for other distributions. Last-epoch means average assignments observed during the last epoch, when centroids were moving; this is not a separate Lloyd pass. Empty final clusters retain their EMA centroid. A final exact pass recomputes assignments and MSE against the returned codebook. `mse` is the mean squared L2 distance per row, not per coordinate. + +This version does not implement GPU/low-precision kernels, distributed or approximate IVF assignment, or slow-EMA finalization. It makes no claim to reproduce the paper's GPU speedups or universally outperform Lloyd. Existing consumer training defaults remain available. + +Native Rust has no default features. `serde` adds config/model serialization; `wasm` adds the wasm-bindgen bridge used by `@ruvector/e-means`. Native core MSRV is Rust 1.81; WASM builds use the toolchain required by the pinned wasm-bindgen dependency. See [ADR-359](../../docs/adr/ADR-359-e-means-shared-clustering.md) for integration, validation, and staged release instructions. + +Run the deterministic native benchmark with `cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both`. Dataset generation and warmup are excluded from median fit/predict times. The [local measurements](../../docs/research/e-means/performance-2026-11-11.json) include baseline comparisons, allocation counts and unchanged-output checks; gains depend on shape and distribution. + +Reusable `quantization::ProductQuantizer` and `ivf::IvfPartition` modules add +checked byte-code encode/decode, subspace-major codebooks, and stable inverted +postings. Their private shape fields and serde restoration reject malformed +persisted state. `ruvector-pq-search` and the IVF/RAIRS/SEIL family expose explicit +e-means training using this dependency. See [ADR-360](../../docs/adr/ADR-360-e-means-ecosystem-integrations.md) +for the native/npm integration matrix, MetaHarness evaluation, and Cloudflare +static-WASM entrypoints. These additions preserve existing training defaults. diff --git a/crates/ruvector-e-means/examples/benchmark.rs b/crates/ruvector-e-means/examples/benchmark.rs new file mode 100644 index 0000000000..5112f8032d --- /dev/null +++ b/crates/ruvector-e-means/examples/benchmark.rs @@ -0,0 +1,177 @@ +//! Portable native fit/predict benchmark. No extra dependencies or CPU flags. +//! +//! cargo run -p ruvector-e-means --release --example benchmark -- +//! --case all --repeats 5 --seed 42 --finalization both +//! +//! Dataset creation and warmup are excluded from reported median timings. + +use ruvector_e_means::{fit, Config, Finalization}; +use std::{hint::black_box, time::Instant}; + +#[derive(Clone, Copy)] +pub struct Case { + pub name: &'static str, + pub samples: usize, + pub clusters: usize, + pub dimensions: usize, +} + +pub const CASES: [Case; 4] = [ + Case { + name: "embedding128", + samples: 4096, + clusters: 64, + dimensions: 128, + }, + Case { + name: "embedding768", + samples: 2048, + clusters: 32, + dimensions: 768, + }, + Case { + name: "pq8", + samples: 8192, + clusters: 256, + dimensions: 8, + }, + Case { + name: "revival", + samples: 2048, + clusters: 64, + dimensions: 32, + }, +]; + +/// Deterministic synthetic inputs, not a reproduction of the paper's datasets. +/// Cases cover clustered and diffuse normalized embeddings, diffuse low-D +/// codebook training, and duplicate/zero rows that exercise cluster revival. +pub fn generate(case: Case, seed: u64) -> Vec { + let mut state = seed; + let mut random = || { + state = state.wrapping_add(0x9e3779b97f4a7c15); + let mut value = state; + value = (value ^ (value >> 30)).wrapping_mul(0xbf58476d1ce4e5b9); + value = (value ^ (value >> 27)).wrapping_mul(0x94d049bb133111eb); + value ^= value >> 31; + ((value >> 40) as f32 / 16_777_216.0) * 2.0 - 1.0 + }; + let centers: Vec = (0..case.clusters * case.dimensions) + .map(|_| random()) + .collect(); + let mut data = Vec::with_capacity(case.samples * case.dimensions); + for i in 0..case.samples { + for d in 0..case.dimensions { + let value = match case.name { + "embedding128" => { + centers[(i % case.clusters) * case.dimensions + d] + random() * 0.1 + } + "revival" if i % 5 == 0 => 0.0, + "revival" => ((i % 4) as f32 - 1.5) * if d % 2 == 0 { 1.0 } else { -1.0 }, + _ => random(), + }; + data.push(value); + } + if case.name.starts_with("embedding") { + let row = &mut data[i * case.dimensions..(i + 1) * case.dimensions]; + let norm = row + .iter() + .map(|&v| f64::from(v).powi(2)) + .sum::() + .sqrt(); + for value in row { + *value = (f64::from(*value) / norm) as f32; + } + } + } + data +} + +pub fn digest(centroids: &[f32], assignments: &[usize]) -> u64 { + let mut hash = 0xcbf29ce484222325u64; + for bits in centroids + .iter() + .map(|v| u64::from(v.to_bits())) + .chain(assignments.iter().map(|&v| v as u64)) + { + for byte in bits.to_le_bytes() { + hash = (hash ^ u64::from(byte)).wrapping_mul(0x100000001b3); + } + } + hash +} + +pub fn median_ms(samples: &mut [f64]) -> f64 { + samples.sort_by(f64::total_cmp); + let middle = samples.len() / 2; + if samples.len() % 2 == 0 { + (samples[middle - 1] + samples[middle]) / 2.0 + } else { + samples[middle] + } +} + +fn main() -> Result<(), Box> { + let mut case_name = String::from("all"); + let mut repeats = 5usize; + let mut seed = 42u64; + let mut finalization = String::from("both"); + let mut args = std::env::args().skip(1); + while let Some(flag) = args.next() { + if flag == "--help" { + println!("benchmark [--case all|embedding128|embedding768|pq8|revival] [--repeats 1..99] [--seed u64] [--finalization both|lastEpochMean|ema]"); + return Ok(()); + } + let value = args.next().ok_or("every option requires a value")?; + match flag.as_str() { + "--case" => case_name = value, + "--repeats" => repeats = value.parse()?, + "--seed" => seed = value.parse()?, + "--finalization" => finalization = value, + _ => return Err(format!("unknown option: {flag}").into()), + } + } + if !(1..=99).contains(&repeats) + || !["both", "lastEpochMean", "ema"].contains(&finalization.as_str()) + { + return Err("invalid repeats or finalization".into()); + } + let cases: Vec = CASES + .into_iter() + .filter(|case| case_name == "all" || case.name == case_name) + .collect(); + if cases.is_empty() { + return Err("unknown benchmark case".into()); + } + for case in cases { + let data = generate(case, seed); + for (label, mode) in [ + ("lastEpochMean", Finalization::LastEpochMean), + ("ema", Finalization::Ema), + ] { + if finalization != "both" && finalization != label { + continue; + } + let config = Config { + clusters: case.clusters, + seed, + finalization: mode, + ..Config::default() + }; + let model = fit(black_box(&data), case.dimensions, &config)?; + black_box(model.predict(black_box(&data))?); + let mut fit_ms = Vec::with_capacity(repeats); + let mut predict_ms = Vec::with_capacity(repeats); + for _ in 0..repeats { + let start = Instant::now(); + black_box(fit(black_box(&data), case.dimensions, black_box(&config))?); + fit_ms.push(start.elapsed().as_secs_f64() * 1000.0); + let start = Instant::now(); + black_box(model.predict(black_box(&data))?); + predict_ms.push(start.elapsed().as_secs_f64() * 1000.0); + } + println!("{{\"case\":\"{}\",\"samples\":{},\"clusters\":{},\"dimensions\":{},\"seed\":{},\"epochs\":{},\"repeats\":{},\"finalization\":\"{}\",\"fitMedianMs\":{:.6},\"predictMedianMs\":{:.6},\"mse\":{:.12},\"revivedClusters\":{},\"digest\":\"{:016x}\"}}", case.name, case.samples, case.clusters, case.dimensions, seed, config.epochs, repeats, label, median_ms(&mut fit_ms), median_ms(&mut predict_ms), model.mse, model.revived_clusters, digest(&model.centroids, &model.assignments)); + } + } + Ok(()) +} diff --git a/crates/ruvector-e-means/src/config.rs b/crates/ruvector-e-means/src/config.rs new file mode 100644 index 0000000000..9e63d6a575 --- /dev/null +++ b/crates/ruvector-e-means/src/config.rs @@ -0,0 +1,115 @@ +use crate::Error; + +/// Final centroid estimator. Slow-EMA finalization is reserved for a future API. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub enum Finalization { + #[default] + LastEpochMean, + Ema, +} + +/// Fit options. Overrides are useful for tiny or low-dimensional datasets where +/// the paper's empirically fitted scaling laws are outside their training range. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr( + feature = "serde", + serde(rename_all = "camelCase", deny_unknown_fields) +)] +pub struct Config { + pub clusters: usize, + #[cfg_attr(feature = "serde", serde(default = "default_epochs"))] + pub epochs: usize, + #[cfg_attr(feature = "serde", serde(default))] + pub batch_size: Option, + #[cfg_attr(feature = "serde", serde(default))] + pub peak_step: Option, + #[cfg_attr(feature = "serde", serde(default = "default_seed"))] + pub seed: u64, + #[cfg_attr(feature = "serde", serde(default))] + pub finalization: Finalization, +} + +fn default_epochs() -> usize { + 3 +} + +fn default_seed() -> u64 { + 42 +} + +impl Default for Config { + fn default() -> Self { + Self { + clusters: 8, + epochs: default_epochs(), + batch_size: None, + peak_step: None, + seed: default_seed(), + finalization: Finalization::LastEpochMean, + } + } +} + +/// Resolved scaling-law parameters, inspectable before allocating a model. +#[derive(Debug, Clone, Copy)] +pub struct Parameters { + pub batch_size: usize, + pub peak_step: f64, + pub updates: usize, +} + +impl Config { + /// Table 2 and equations (6)-(7) of arXiv:2611.09501v1. Batch law uses + /// coefficient 0.035, divided by 8 above two million samples, rounded to + /// the nearest power of two and capped at n. Tail batches are included. + pub fn parameters(&self, samples: usize) -> Result { + if samples == 0 || self.clusters == 0 || self.clusters > samples { + return Err(Error("clusters must be in 1..=number of samples")); + } + if self.epochs == 0 { + return Err(Error("epochs must be positive")); + } + let n = samples as f64; + let k = self.clusters as f64; + let t = self.epochs as f64; + let batch_size = match self.batch_size { + Some(0) => return Err(Error("batch size must be positive")), + Some(b) => b.min(samples), + None => { + let coefficient = if samples > 2_000_000 { + 0.035 / 8.0 + } else { + 0.035 + }; + let law = coefficient * k.powf(0.13) * n.powf(0.88) * t.powf(0.81); + 2.0_f64.powf(law.max(1.0).log2().round()).min(n) as usize + } + }; + let peak_step = self.peak_step.unwrap_or_else(|| { + (0.824 * k.powf(-0.46) * (batch_size as f64).powf(0.90) * n.powf(-0.45) * t.powf(-0.11)) + .min(1.0) + }); + if !peak_step.is_finite() || peak_step <= 0.0 || peak_step > 1.0 { + return Err(Error("peak step must be finite and in (0, 1]")); + } + let batches = samples / batch_size + usize::from(samples % batch_size != 0); + let updates = batches + .checked_mul(self.epochs) + .ok_or(Error("update count overflow"))?; + Ok(Parameters { + batch_size, + peak_step, + updates, + }) + } +} + +/// Equation (5), zero-based batch index t and total M updates. Its denominator +/// is M as printed in the paper: the last update approaches the 0.1 floor. +pub fn cosine_step(peak_step: f64, update: usize, total_updates: usize) -> f64 { + let fraction = (update as f64) / (total_updates.max(1) as f64); + peak_step * (0.1 + 0.9 * 0.5 * (1.0 + (std::f64::consts::PI * fraction).cos())) +} diff --git a/crates/ruvector-e-means/src/distance.rs b/crates/ruvector-e-means/src/distance.rs new file mode 100644 index 0000000000..03b9753679 --- /dev/null +++ b/crates/ruvector-e-means/src/distance.rs @@ -0,0 +1,189 @@ +//! Exact squared-L2 assignment with bounded work on losing candidates. + +/// Inputs have already passed the public API's shape and finiteness checks. +/// All squared terms are nonnegative: once a partial distance reaches the +/// best distance, that later centroid cannot win, including in a tie. +pub(crate) fn nearest(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + // End-to-end diffuse PQ benchmarks favor the original scalar path at small + // dimensions: pruning checks cost more than the arithmetic they can skip. + if dimensions <= 16 { + exhaustive(row, centroids, dimensions) + } else { + pruned::<8>(row, centroids, dimensions) + } +} + +fn exhaustive(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let distance: f64 = row + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum(); + if distance < best.1 { + best = (j, distance); + if distance == 0.0 { + break; + } + } + } + best +} + +fn pruned(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let mut distance = 0.0; + for (xs, ys) in row.chunks(BLOCK).zip(centroid.chunks(BLOCK)) { + // Retain left-to-right f64 addition. Reassociating these terms, or + // expanding norms and dot products, can change near-tie winners. + for (&x, &y) in xs.iter().zip(ys) { + let difference = f64::from(x) - f64::from(y); + distance += difference * difference; + } + if distance >= best.1 { + break; + } + } + if distance < best.1 { + best = (j, distance); + if distance == 0.0 { + break; + } + } + } + best +} + +#[cfg(test)] +mod tests { + use super::nearest; + + /// The pre-optimization exhaustive implementation is an independent oracle. + fn oracle(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let distance: f64 = row + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum(); + if distance < best.1 { + best = (j, distance); + } + } + best + } + + fn compare(row: &[f32], centroids: &[f32]) { + let expected = oracle(row, centroids, row.len()); + let actual = nearest(row, centroids, row.len()); + assert_eq!(actual.0, expected.0, "{} dimensions", row.len()); + assert_eq!(actual.1.to_bits(), expected.1.to_bits()); + } + + fn random(state: &mut u64) -> f32 { + *state = state.wrapping_mul(6364136223846793005).wrapping_add(1); + ((*state >> 40) as f32 / 16777216.0) * 2.0 - 1.0 + } + + #[test] + fn assignment_matches_exhaustive_on_diffuse_and_separated_data() { + let mut state = 42; + for dimensions in [ + 1, 3, 4, 7, 8, 9, 15, 16, 17, 31, 32, 33, 127, 128, 129, 384, 385, 768, 769, + ] { + for clusters in [1, 2, 7, 32] { + for separated in [false, true] { + let centroids = (0..clusters * dimensions) + .map(|i| { + random(&mut state) + + if separated { + (i / dimensions) as f32 * 4.0 + } else { + 0.0 + } + }) + .collect::>(); + for i in 0..13 { + let row = (0..dimensions) + .map(|d| { + if separated { + centroids[(i % clusters) * dimensions + d] + + random(&mut state) * 0.01 + } else { + random(&mut state) + } + }) + .collect::>(); + compare(&row, ¢roids); + } + } + } + } + } + + #[test] + fn ties_and_zero_distances_keep_the_lowest_index() { + for dimensions in [1, 3, 8, 16, 32, 128, 384, 768] { + let row = vec![0.0; dimensions]; + let mut centroids = vec![1.0; dimensions]; + centroids.extend(vec![-1.0; dimensions]); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 0); + centroids.extend(vec![-0.0; dimensions]); + centroids.extend(vec![0.0; dimensions]); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 2); + } + } + + #[test] + fn extreme_finite_coordinates_and_subnormals_preserve_exact_distance() { + let values = [ + f32::MAX, + -f32::MAX, + f32::MIN_POSITIVE, + f32::from_bits(1), + -f32::from_bits(1), + 0.0, + -0.0, + 1.0, + ]; + for dimensions in [1, 3, 8, 16, 32, 128, 384, 768] { + for offset in 0..values.len() { + let row = (0..dimensions) + .map(|d| values[(d + offset) % values.len()]) + .collect::>(); + let centroids = (0..7 * dimensions) + .map(|d| values[(d * 3 + offset + 1) % values.len()]) + .collect::>(); + compare(&row, ¢roids); + } + } + } + + #[test] + fn near_ties_and_awkward_tail_dimensions_preserve_ordered_addition() { + for dimensions in [3, 7, 8, 9, 15, 16, 17, 31, 32, 33, 127, 129, 385, 769] { + let row = vec![0.0; dimensions]; + let mut first = vec![1.0; dimensions]; + let mut second = first.clone(); + first[dimensions - 1] = f32::from_bits(1.0_f32.to_bits() + 1); + let mut centroids = first.clone(); + centroids.extend_from_slice(&second); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 1); + + // Tiny trailing contributions disappear when added after a huge + // leading square; summation reassociation must not break this tie. + first[0] = 1e20; + second[0] = 1e20; + let mut centroids = first; + centroids.extend(second); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 0); + } + } +} diff --git a/crates/ruvector-e-means/src/ivf.rs b/crates/ruvector-e-means/src/ivf.rs new file mode 100644 index 0000000000..136f78d200 --- /dev/null +++ b/crates/ruvector-e-means/src/ivf.rs @@ -0,0 +1,155 @@ +//! Stable inverted-file postings over a trained e-means centroid model. + +use crate::{fit, validate_rows, Config, Error, Model}; + +/// A centroid model plus compact, deterministic inverted lists of input row IDs. +/// Posting `j` occupies `indices[offsets[j]..offsets[j + 1]]`. Row IDs within +/// every list are ascending and every training row occurs exactly once. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct IvfPartition { + model: Model, + offsets: Vec, + indices: Vec, +} + +impl IvfPartition { + /// Train centroids and build postings from the final nearest assignments. + pub fn fit(data: &[f32], dimensions: usize, config: &Config) -> Result { + Self::from_model(fit(data, dimensions, config)?) + } + + /// Build postings for an existing, validated fitted model. + pub fn from_model(model: Model) -> Result { + let clusters = validate_model(&model)?; + let mut offsets = vec![0usize; clusters + 1]; + for &assignment in &model.assignments { + offsets[assignment + 1] += 1; + } + for i in 1..offsets.len() { + offsets[i] += offsets[i - 1]; + } + let mut cursors = offsets[..clusters].to_vec(); + let mut indices = vec![0usize; model.assignments.len()]; + for (row, &assignment) in model.assignments.iter().enumerate() { + indices[cursors[assignment]] = row; + cursors[assignment] += 1; + } + Ok(Self { + model, + offsets, + indices, + }) + } + + /// Restore a persisted partition, checking offsets, labels, and row IDs. + /// Repeated, omitted, reordered, or incorrectly assigned row IDs reject. + pub fn from_parts( + model: Model, + offsets: Vec, + indices: Vec, + ) -> Result { + let clusters = validate_model(&model)?; + let samples = model.assignments.len(); + if offsets.len() != clusters + 1 + || offsets.first() != Some(&0) + || offsets.last() != Some(&samples) + || indices.len() != samples + { + return Err(Error( + "IVF offsets and indices must cover every training row", + )); + } + if offsets + .windows(2) + .any(|pair| pair[0] > pair[1] || pair[1] > samples) + { + return Err(Error( + "IVF offsets must be monotonic and within the row count", + )); + } + for cluster in 0..clusters { + let posting = &indices[offsets[cluster]..offsets[cluster + 1]]; + if posting.windows(2).any(|pair| pair[0] >= pair[1]) { + return Err(Error("IVF posting row IDs must be strictly ascending")); + } + for &row in posting { + if row >= samples || model.assignments[row] != cluster { + return Err(Error("IVF row ID is out of range or in the wrong posting")); + } + } + } + Ok(Self { + model, + offsets, + indices, + }) + } + + /// Trained centroids, final labels, and training metrics. + pub fn model(&self) -> &Model { + &self.model + } + + /// Exclusive posting boundaries, of length `clusters + 1`. + pub fn offsets(&self) -> &[usize] { + &self.offsets + } + + /// Input row IDs grouped by cluster, stable within each cluster. + pub fn indices(&self) -> &[usize] { + &self.indices + } + + /// Borrow one inverted list, returning an error for an invalid cluster. + pub fn posting(&self, cluster: usize) -> Result<&[usize], Error> { + if cluster >= self.offsets.len() - 1 { + return Err(Error("IVF cluster index is out of range")); + } + Ok(&self.indices[self.offsets[cluster]..self.offsets[cluster + 1]]) + } + + /// Consume this partition without copying its trained centroid model. + pub fn into_model(self) -> Model { + self.model + } +} + +fn validate_model(model: &Model) -> Result { + validate_rows(&model.centroids, model.dimensions)?; + let clusters = model.centroids.len() / model.dimensions; + let samples = model.assignments.len(); + if clusters == 0 || samples < clusters || model.assignments.iter().any(|&j| j >= clusters) { + return Err(Error( + "IVF model must have valid nonempty centroids and assignments", + )); + } + if !model.mse.is_finite() + || model.mse < 0.0 + || !model.peak_step.is_finite() + || model.peak_step <= 0.0 + || model.peak_step > 1.0 + || model.batch_size == 0 + || model.batch_size > samples + || model.updates == 0 + { + return Err(Error("IVF model has invalid fitted training metrics")); + } + Ok(clusters) +} + +#[cfg(feature = "serde")] +impl<'de> serde::Deserialize<'de> for IvfPartition { + fn deserialize>(deserializer: D) -> Result { + #[derive(serde::Deserialize)] + #[serde(rename_all = "camelCase", deny_unknown_fields)] + struct Wire { + model: Model, + offsets: Vec, + indices: Vec, + } + let wire = ::deserialize(deserializer)?; + Self::from_parts(wire.model, wire.offsets, wire.indices).map_err(serde::de::Error::custom) + } +} diff --git a/crates/ruvector-e-means/src/lib.rs b/crates/ruvector-e-means/src/lib.rs new file mode 100644 index 0000000000..959539093d --- /dev/null +++ b/crates/ruvector-e-means/src/lib.rs @@ -0,0 +1,81 @@ +//! e-means CPU reference implementation of Bessa et al., arXiv:2611.09501v1. +//! +//! Uses exact squared-L2 assignment, f64 sufficient statistics and seeded +//! ChaCha8 shuffles. This does not implement the paper's GPU or approximate IVF +//! kernels. See [`fit`] and [`Config`]. + +mod config; +mod distance; +pub mod ivf; +pub mod quantization; +mod trainer; +#[cfg(feature = "wasm")] +mod wasm; + +pub use config::{cosine_step, Config, Finalization, Parameters}; +pub(crate) use distance::nearest; +pub use ivf::IvfPartition; +pub use quantization::ProductQuantizer; +pub use trainer::fit; + +/// Validation failure; invalid input is rejected before training starts. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Error(pub(crate) &'static str); + +impl std::fmt::Display for Error { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.0) + } +} + +impl std::error::Error for Error {} + +/// A trained flat, row-major codebook and freshly recomputed training metrics. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct Model { + pub centroids: Vec, + pub dimensions: usize, + /// Nearest-centroid assignments in original input order, after finalization. + pub assignments: Vec, + /// Mean squared L2 distance per vector, not divided by dimensionality. + pub mse: f64, + pub batch_size: usize, + pub peak_step: f64, + pub updates: usize, + pub revived_clusters: usize, +} + +impl Model { + /// Assign new vectors to this codebook. Empty queries return no assignments. + /// Public/deserialized model fields are validated on every call. + pub fn predict(&self, data: &[f32]) -> Result, Error> { + predict(data, self.dimensions, &self.centroids) + } +} + +/// Exact squared-L2 prediction with deterministic lowest-index tie breaking. +pub fn predict(data: &[f32], dimensions: usize, centroids: &[f32]) -> Result, Error> { + validate_rows(data, dimensions)?; + validate_rows(centroids, dimensions)?; + if centroids.is_empty() { + return Err(Error("centroids must not be empty")); + } + Ok(data + .chunks_exact(dimensions) + .map(|row| nearest(row, centroids, dimensions).0) + .collect()) +} + +pub(crate) fn validate_rows(data: &[f32], dimensions: usize) -> Result<(), Error> { + if dimensions == 0 || data.len() % dimensions != 0 { + return Err(Error( + "dimensions must be positive and divide the data length", + )); + } + if data.iter().any(|v| !v.is_finite()) { + return Err(Error("vectors must contain only finite values")); + } + Ok(()) +} diff --git a/crates/ruvector-e-means/src/quantization.rs b/crates/ruvector-e-means/src/quantization.rs new file mode 100644 index 0000000000..1fb7f7989a --- /dev/null +++ b/crates/ruvector-e-means/src/quantization.rs @@ -0,0 +1,181 @@ +//! Checked product-quantization codebooks trained by the shared e-means kernel. + +use crate::{fit, nearest, validate_rows, Config, Error}; + +/// A reusable PQ codebook with private, validated layout metadata. +/// +/// Centroids are subspace-major: `[subspace][cluster][subspace_dimension]`. +/// Codes are row-major: one u8 per subspace per input vector. Each subspace +/// uses the supplied configuration unchanged, including its deterministic seed. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct ProductQuantizer { + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, +} + +impl ProductQuantizer { + /// Train one e-means codebook per equally sized subspace. + pub fn fit( + data: &[f32], + dimensions: usize, + subspaces: usize, + config: &Config, + ) -> Result { + validate_rows(data, dimensions)?; + config.parameters(data.len() / dimensions)?; + Self::validate_shape(dimensions, subspaces, config.clusters)?; + let sub_dim = dimensions / subspaces; + let mut centroids = Vec::with_capacity(dimensions * config.clusters); + let mut sub_data = Vec::with_capacity(data.len() / subspaces); + for subspace in 0..subspaces { + sub_data.clear(); + let start = subspace * sub_dim; + for row in data.chunks_exact(dimensions) { + sub_data.extend_from_slice(&row[start..start + sub_dim]); + } + centroids.extend(fit(&sub_data, sub_dim, config)?.centroids); + } + Self::from_centroids(dimensions, subspaces, config.clusters, centroids) + } + + /// Restore a codebook, rejecting inconsistent shapes or nonfinite values. + pub fn from_centroids( + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, + ) -> Result { + Self::validate_parts(dimensions, subspaces, clusters, ¢roids)?; + Ok(Self { + dimensions, + subspaces, + clusters, + centroids, + }) + } + + /// Validate a borrowed codebook layout without allocating a copy. + pub fn validate_parts( + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: &[f32], + ) -> Result<(), Error> { + Self::validate_shape(dimensions, subspaces, clusters)?; + if centroids.len() != dimensions * clusters { + return Err(Error( + "PQ centroid length must equal dimensions times clusters", + )); + } + validate_rows(centroids, dimensions / subspaces) + } + + fn validate_shape(dimensions: usize, subspaces: usize, clusters: usize) -> Result<(), Error> { + if dimensions == 0 || subspaces == 0 || dimensions % subspaces != 0 { + return Err(Error( + "PQ subspaces must be positive and divide positive dimensions", + )); + } + if !(1..=256).contains(&clusters) { + return Err(Error("PQ clusters must be in 1..=256 for u8 codes")); + } + dimensions + .checked_mul(clusters) + .ok_or(Error("PQ centroid shape overflows usize"))?; + Ok(()) + } + + /// Original vector dimensionality. + pub fn dimensions(&self) -> usize { + self.dimensions + } + + /// Number of equally sized subspaces, and bytes in each encoded vector. + pub fn subspaces(&self) -> usize { + self.subspaces + } + + /// Number of centroids in each subspace. + pub fn clusters(&self) -> usize { + self.clusters + } + + /// Dimensionality of each subvector. + pub fn subspace_dimensions(&self) -> usize { + self.dimensions / self.subspaces + } + + /// Borrow the flat subspace-major codebook. + pub fn centroids(&self) -> &[f32] { + &self.centroids + } + + /// Consume the quantizer and return its existing flat codebook allocation. + pub fn into_centroids(self) -> Vec { + self.centroids + } + + /// Encode finite row-major vectors with exact f64 nearest-centroid assignment. + /// Empty input produces an empty code array; ties choose the lowest code. + pub fn encode(&self, data: &[f32]) -> Result, Error> { + validate_rows(data, self.dimensions)?; + let sub_dim = self.subspace_dimensions(); + let mut codes = Vec::with_capacity(data.len() / sub_dim); + for row in data.chunks_exact(self.dimensions) { + for (subspace, subvector) in row.chunks_exact(sub_dim).enumerate() { + let start = subspace * self.clusters * sub_dim; + let book = &self.centroids[start..start + self.clusters * sub_dim]; + codes.push(nearest(subvector, book, sub_dim).0 as u8); + } + } + Ok(codes) + } + + /// Decode row-major PQ codes, rejecting incomplete rows and invalid codes. + pub fn decode(&self, codes: &[u8]) -> Result, Error> { + if codes.len() % self.subspaces != 0 { + return Err(Error("PQ code length must be divisible by subspaces")); + } + if codes.iter().any(|&code| usize::from(code) >= self.clusters) { + return Err(Error("PQ code is outside the trained codebook")); + } + let capacity = (codes.len() / self.subspaces) + .checked_mul(self.dimensions) + .ok_or(Error("decoded PQ shape overflows usize"))?; + let sub_dim = self.subspace_dimensions(); + let mut data = Vec::with_capacity(capacity); + for row in codes.chunks_exact(self.subspaces) { + for (subspace, &code) in row.iter().enumerate() { + let start = (subspace * self.clusters + usize::from(code)) * sub_dim; + data.extend_from_slice(&self.centroids[start..start + sub_dim]); + } + } + Ok(data) + } +} + +#[cfg(feature = "serde")] +impl<'de> serde::Deserialize<'de> for ProductQuantizer { + fn deserialize>(deserializer: D) -> Result { + #[derive(serde::Deserialize)] + #[serde(rename_all = "camelCase", deny_unknown_fields)] + struct Wire { + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, + } + let wire = ::deserialize(deserializer)?; + Self::from_centroids( + wire.dimensions, + wire.subspaces, + wire.clusters, + wire.centroids, + ) + .map_err(serde::de::Error::custom) + } +} diff --git a/crates/ruvector-e-means/src/trainer.rs b/crates/ruvector-e-means/src/trainer.rs new file mode 100644 index 0000000000..5ded7db45b --- /dev/null +++ b/crates/ruvector-e-means/src/trainer.rs @@ -0,0 +1,242 @@ +use crate::{cosine_step, nearest, validate_rows, Config, Error, Finalization, Model}; +use rand_chacha::ChaCha8Rng; +use rand_core::{RngCore, SeedableRng}; + +const INITIAL_COUNT: f64 = 1e-10; +const MIN_COUNT: f64 = 1e-300; +const REVIVAL_THRESHOLD: f64 = 0.1; +// BF16 epsilon, as used by Appendix H, even though this implementation is f32. +const SPLIT_DELTA: f64 = 1.0 / 128.0; + +/// Train on finite flat row-major f32 vectors. The algorithm follows equations +/// (2)-(8) of arXiv:2611.09501v1, using exact CPU assignment. Shuffled partial +/// batches are included, so every row participates in every epoch. Scratch +/// memory is O(n + kd); no n-by-k distance matrix is allocated. +pub fn fit(data: &[f32], dimensions: usize, config: &Config) -> Result { + validate_rows(data, dimensions)?; + let samples = data.len() / dimensions; + let params = config.parameters(samples)?; + let k = config.clusters; + let mut rng = ChaCha8Rng::seed_from_u64(config.seed); + let mut order: Vec = (0..samples).collect(); + shuffle(&mut order, &mut rng); + let mut centroids = Vec::with_capacity(k * dimensions); + for &i in &order[..k] { + centroids.extend_from_slice(&data[i * dimensions..(i + 1) * dimensions]); + } + let mut counts = vec![INITIAL_COUNT; k]; + let mut sums: Vec = centroids + .iter() + .map(|&v| f64::from(v) * INITIAL_COUNT) + .collect(); + let mut batch_counts = vec![0.0; k]; + let mut batch_sums = vec![0.0; sums.len()]; + let use_last_mean = config.finalization == Finalization::LastEpochMean; + let mut last_counts = if use_last_mean { + vec![0usize; k] + } else { + Vec::new() + }; + let mut last_sums = if use_last_mean { + vec![0.0; sums.len()] + } else { + Vec::new() + }; + let mut revival_scratch = RevivalScratch::default(); + let mut updates = 0; + let mut revived_clusters = 0; + for epoch in 0..config.epochs { + let record_last = use_last_mean && epoch + 1 == config.epochs; + shuffle(&mut order, &mut rng); + for batch in order.chunks(params.batch_size) { + batch_counts.fill(0.0); + batch_sums.fill(0.0); + for &i in batch { + let row = &data[i * dimensions..(i + 1) * dimensions]; + let (j, _) = nearest(row, ¢roids, dimensions); + batch_counts[j] += 1.0; + let batch_sum = &mut batch_sums[j * dimensions..(j + 1) * dimensions]; + for (sum, &x) in batch_sum.iter_mut().zip(row) { + *sum += f64::from(x); + } + if record_last { + last_counts[j] += 1; + let last_sum = &mut last_sums[j * dimensions..(j + 1) * dimensions]; + for (sum, &x) in last_sum.iter_mut().zip(row) { + *sum += f64::from(x); + } + } + } + let step = cosine_step(params.peak_step, updates, params.updates); + for j in 0..k { + let count = (1.0 - step) * counts[j] + step * batch_counts[j]; + let denominator = count.max(MIN_COUNT); + counts[j] = denominator; + let range = j * dimensions..(j + 1) * dimensions; + let sum_row = &mut sums[range.clone()]; + let centroid_row = &mut centroids[range.clone()]; + if count < MIN_COUNT { + // A peak step of 1 can erase empty-cluster statistics. + // Preserve that centroid with a negligible pseudo-count. + for (sum, centroid) in sum_row.iter_mut().zip(centroid_row) { + *sum = denominator * f64::from(*centroid); + *centroid = bounded_f32(*sum / denominator); + } + } else { + for ((sum, &batch_sum), centroid) in + sum_row.iter_mut().zip(&batch_sums[range]).zip(centroid_row) + { + *sum = (1.0 - step) * *sum + step * batch_sum; + *centroid = bounded_f32(*sum / denominator); + } + } + } + updates += 1; + if updates % 5 == 0 { + revived_clusters += revive( + &mut counts, + &mut sums, + &mut centroids, + dimensions, + &mut rng, + &mut revival_scratch, + ); + } + } + } + if use_last_mean { + for (j, &count) in last_counts.iter().enumerate() { + if count > 0 { + for d in 0..dimensions { + centroids[j * dimensions + d] = + bounded_f32(last_sums[j * dimensions + d] / count as f64); + } + } + } + } + let mut assignments = Vec::with_capacity(samples); + let mut loss = 0.0; + for row in data.chunks_exact(dimensions) { + let (j, distance) = nearest(row, ¢roids, dimensions); + assignments.push(j); + loss += distance; + } + Ok(Model { + centroids, + dimensions, + assignments, + mse: loss / samples as f64, + batch_size: params.batch_size, + peak_step: params.peak_step, + updates, + revived_clusters, + }) +} + +fn bounded_f32(value: f64) -> f32 { + value.clamp(-f64::from(f32::MAX), f64::from(f32::MAX)) as f32 +} + +fn shuffle(order: &mut [usize], rng: &mut ChaCha8Rng) { + for i in (1..order.len()).rev() { + let limit = (i + 1) as u64; + // Rejection sampling avoids modulo bias, including on wasm32. + let threshold = limit.wrapping_neg() % limit; + let value = loop { + let value = rng.next_u64(); + if value >= threshold { + break value; + } + }; + order.swap(i, (value % limit) as usize); + } +} + +#[derive(Default)] +struct RevivalScratch { + dead: Vec, + available: Vec, +} + +fn revive( + counts: &mut [f64], + sums: &mut [f64], + centroids: &mut [f32], + dimensions: usize, + rng: &mut ChaCha8Rng, + scratch: &mut RevivalScratch, +) -> usize { + let threshold = REVIVAL_THRESHOLD * counts.iter().sum::() / counts.len() as f64; + scratch.dead.clear(); + scratch + .dead + .extend((0..counts.len()).filter(|&j| counts[j] < threshold)); + if scratch.dead.is_empty() { + return 0; + } + // Select live donors proportional to their EMA count, without replacement. + // Newly revived slots cannot donate again in the same revival pass. + let available = &mut scratch.available; + available.clear(); + available.extend((0..counts.len()).filter(|&j| counts[j] >= threshold)); + let mut revived = 0; + for &j in &scratch.dead { + let mass: f64 = available.iter().map(|&i| counts[i]).sum(); + if mass <= 0.0 { + break; + } + let unit = (rng.next_u64() >> 11) as f64 / ((1u64 << 53) as f64); + let mut pick = unit * mass; + let mut donor_pos = available.len() - 1; + for (pos, &i) in available.iter().enumerate() { + pick -= counts[i]; + if pick <= 0.0 { + donor_pos = pos; + break; + } + } + let donor = available.remove(donor_pos); + counts[donor] *= 0.5; + counts[j] = counts[donor]; + for d in 0..dimensions { + let shift = if d % 2 == 0 { + SPLIT_DELTA + } else { + -SPLIT_DELTA + }; + let value = f64::from(centroids[donor * dimensions + d]); + centroids[j * dimensions + d] = bounded_f32(value * (1.0 + shift)); + centroids[donor * dimensions + d] = bounded_f32(value * (1.0 - shift)); + sums[j * dimensions + d] = f64::from(centroids[j * dimensions + d]) * counts[j]; + sums[donor * dimensions + d] = + f64::from(centroids[donor * dimensions + d]) * counts[donor]; + } + revived += 1; + } + revived +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn donor_split_preserves_mass_and_weighted_sum() { + let mut counts = vec![10.0, 0.0]; + let mut sums = vec![40.0, 80.0, 0.0, 0.0]; + let mut centroids = vec![4.0, 8.0, 0.0, 0.0]; + let n = revive( + &mut counts, + &mut sums, + &mut centroids, + 2, + &mut ChaCha8Rng::seed_from_u64(2), + &mut RevivalScratch::default(), + ); + assert_eq!(n, 1); + assert_eq!(counts, [5.0, 5.0]); + assert_eq!(sums[0] + sums[2], 40.0); + assert_eq!(sums[1] + sums[3], 80.0); + assert_ne!(¢roids[..2], ¢roids[2..]); + } +} diff --git a/crates/ruvector-e-means/src/wasm.rs b/crates/ruvector-e-means/src/wasm.rs new file mode 100644 index 0000000000..6888112de3 --- /dev/null +++ b/crates/ruvector-e-means/src/wasm.rs @@ -0,0 +1,92 @@ +use crate::{fit, predict, Config, Model}; +use wasm_bindgen::prelude::*; + +/// Compatibility transport and an independent parity oracle for typed output. +#[wasm_bindgen(js_name = fitJson)] +pub fn fit_json(data: &[f32], dimensions: usize, config_json: &str) -> Result { + let config: Config = + serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?; + let model = fit(data, dimensions, &config).map_err(|e| JsError::new(&e.to_string()))?; + serde_json::to_string(&model).map_err(|e| JsError::new(&e.to_string())) +} + +/// A temporary owner for one fit result. JavaScript takes independent output +/// arrays and then frees this handle, releasing any vectors not taken. +#[wasm_bindgen] +pub struct FittedModel { + model: Model, +} + +#[wasm_bindgen] +impl FittedModel { + /// wasm-bindgen copies the returned vector into a caller-owned Float32Array + /// before freeing its Rust allocation. No view into WASM memory escapes. + #[wasm_bindgen(js_name = takeCentroids)] + pub fn take_centroids(&mut self) -> Vec { + std::mem::take(&mut self.model.centroids) + } + + /// Cluster indices fit u32 because wasm32 arrays and sample counts do. + #[wasm_bindgen(js_name = takeAssignments)] + pub fn take_assignments(&mut self) -> Vec { + std::mem::take(&mut self.model.assignments) + .into_iter() + .map(|index| index as u32) + .collect() + } + + #[wasm_bindgen(getter)] + pub fn dimensions(&self) -> usize { + self.model.dimensions + } + + #[wasm_bindgen(getter)] + pub fn mse(&self) -> f64 { + self.model.mse + } + + #[wasm_bindgen(getter, js_name = batchSize)] + pub fn batch_size(&self) -> usize { + self.model.batch_size + } + + #[wasm_bindgen(getter, js_name = peakStep)] + pub fn peak_step(&self) -> f64 { + self.model.peak_step + } + + #[wasm_bindgen(getter)] + pub fn updates(&self) -> usize { + self.model.updates + } + + #[wasm_bindgen(getter, js_name = revivedClusters)] + pub fn revived_clusters(&self) -> usize { + self.model.revived_clusters + } +} + +/// Only the small configuration crosses JSON; result vectors stay numeric. +#[wasm_bindgen(js_name = fitTyped)] +pub fn fit_typed( + data: &[f32], + dimensions: usize, + config_json: &str, +) -> Result { + let config: Config = + serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?; + fit(data, dimensions, &config) + .map(|model| FittedModel { model }) + .map_err(|e| JsError::new(&e.to_string())) +} + +#[wasm_bindgen(js_name = predictFlat)] +pub fn predict_flat( + data: &[f32], + dimensions: usize, + centroids: &[f32], +) -> Result, JsError> { + predict(data, dimensions, centroids) + .map(|v| v.into_iter().map(|j| j as u32).collect()) + .map_err(|e| JsError::new(&e.to_string())) +} diff --git a/crates/ruvector-e-means/tests/clustering.rs b/crates/ruvector-e-means/tests/clustering.rs new file mode 100644 index 0000000000..3f340f2b76 --- /dev/null +++ b/crates/ruvector-e-means/tests/clustering.rs @@ -0,0 +1,234 @@ +use ruvector_e_means::{cosine_step, fit, predict, Config, Finalization}; + +#[test] +fn ema_uses_decayed_sums_and_counts_including_short_batches() { + let model = fit( + &[0.0, 1.0, 9.0], + 1, + &Config { + clusters: 1, + epochs: 1, + batch_size: Some(2), + peak_step: Some(1.0), + finalization: Finalization::Ema, + ..Config::default() + }, + ) + .unwrap(); + // First step=1, second step=.55. For any shuffled tail x, the + // correct ratio is (.45*(10-x)+.55*x)/(.45*2+.55*1). + // Averaging batch centroids directly gives a different answer. + let possible: Vec = [0.0, 1.0, 9.0] + .into_iter() + .map(|tail| (0.45 * (10.0 - tail) + 0.55 * tail) / 1.45) + .collect(); + assert!(possible + .iter() + .any(|x| (*x - f64::from(model.centroids[0])).abs() < 1e-6)); + assert_eq!(model.updates, 2); + let center = f64::from(model.centroids[0]); + let expected_mse = (center.powi(2) + (1.0 - center).powi(2) + (9.0 - center).powi(2)) / 3.0; + assert!((model.mse - expected_mse).abs() < 1e-12); +} + +#[test] +fn last_epoch_mean_matches_independent_mean_and_mse_with_tail_batch() { + let data = [1., 2., 3., 4., 5., 6., 7., 8., 9., 10.]; + let config = Config { + clusters: 1, + epochs: 2, + batch_size: Some(2), + ..Config::default() + }; + let model = fit(&data, 2, &config).unwrap(); + assert_eq!(model.centroids, [5., 6.]); + assert_eq!(model.assignments, [0; 5]); + assert_eq!(model.mse, 16.0); + assert_eq!(model.updates, 6); // ceil(5/2) * 2, no dropped rows. + assert_eq!(model.predict(&data).unwrap(), model.assignments); +} + +#[test] +fn scaling_laws_match_table_two_and_large_dataset_rule() { + let params = Config { + clusters: 1024, + epochs: 4, + ..Config::default() + } + .parameters(1_000_000) + .unwrap(); + assert_eq!(params.batch_size, 65536); + assert_eq!(params.peak_step, 1.0); + let params = Config { + clusters: 1024, + epochs: 4, + batch_size: Some(256), + ..Config::default() + } + .parameters(1_000_000) + .unwrap(); + assert!((params.peak_step - 0.008558124524629177).abs() < 1e-14); + let params = Config { + clusters: 1000, + ..Config::default() + } + .parameters(3_000_000) + .unwrap(); + assert_eq!(params.batch_size, 16384); + assert!((params.peak_step - 0.2299943961117698).abs() < 1e-14); +} + +#[test] +fn schedule_matches_equation_five() { + assert_eq!(cosine_step(0.5, 0, 20), 0.5); + assert!((cosine_step(0.5, 10, 20) - 0.275).abs() < 1e-15); + assert_eq!(cosine_step(0.5, 20, 20), 0.05); + let steps: Vec = (0..20).map(|i| cosine_step(0.5, i, 20)).collect(); + assert!(steps.windows(2).all(|s| s[1] < s[0])); + assert!(steps[19] > 0.05); +} + +#[test] +fn separates_three_clouds_and_reproduces_seed() { + let mut data = Vec::new(); + for j in 0..3 { + for i in 0..48 { + for d in 0..8 { + data.push(j as f32 * 40.0 + ((i * 13 + d * 7) % 19) as f32 * 0.01); + } + } + } + let config = Config { + clusters: 3, + epochs: 5, + batch_size: Some(12), + ..Config::default() + }; + let a = fit(&data, 8, &config).unwrap(); + let b = fit(&data, 8, &config).unwrap(); + assert_eq!(a.centroids, b.centroids); + assert_eq!(a.assignments, b.assignments); + assert!(a.mse < 0.1, "mse {}", a.mse); + let leaders: Vec<_> = [0, 48, 96].into_iter().map(|i| a.assignments[i]).collect(); + assert_ne!(leaders[0], leaders[1]); + assert_ne!(leaders[0], leaders[2]); + assert_ne!(leaders[1], leaders[2]); + for cloud in a.assignments.chunks_exact(48) { + assert!(cloud.iter().all(|j| *j == cloud[0])); + } +} + +#[test] +fn duplicate_and_zero_vectors_remain_finite_with_revival_and_step_one() { + for value in [0., 12., f32::MAX, -f32::MAX] { + for finalization in [Finalization::LastEpochMean, Finalization::Ema] { + let model = fit( + &[value; 96], + 3, + &Config { + clusters: 8, + epochs: 4, + batch_size: Some(2), + peak_step: Some(1.0), + finalization, + ..Config::default() + }, + ) + .unwrap(); + assert!(model.centroids.iter().all(|x| x.is_finite())); + assert!(model.mse.is_finite()); + assert!(model.revived_clusters > 0); + assert!(model.assignments.iter().all(|j| *j < 8)); + } + } +} + +#[test] +fn handles_full_batch_k_equals_n_and_large_coordinates() { + let data = [f32::MAX, -f32::MAX, -f32::MAX, f32::MAX]; + let model = fit( + &data, + 2, + &Config { + clusters: 2, + batch_size: Some(100), + ..Config::default() + }, + ) + .unwrap(); + assert_eq!(model.batch_size, 2); + assert_eq!(model.mse, 0.0); + assert_ne!(model.assignments[0], model.assignments[1]); +} + +#[test] +fn validates_before_training_and_checks_mutated_models_on_predict() { + let good = Config { + clusters: 1, + ..Config::default() + }; + for (data, dim) in [ + (vec![], 2), + (vec![1.], 0), + (vec![1.], 2), + (vec![f32::NAN], 1), + (vec![f32::INFINITY], 1), + ] { + assert!(fit(&data, dim, &good).is_err()); + } + for config in [ + Config { + clusters: 0, + ..good.clone() + }, + Config { + clusters: 3, + ..good.clone() + }, + Config { + epochs: 0, + ..good.clone() + }, + Config { + batch_size: Some(0), + ..good.clone() + }, + Config { + peak_step: Some(0.), + ..good.clone() + }, + Config { + peak_step: Some(-0.1), + ..good.clone() + }, + Config { + peak_step: Some(1.1), + ..good.clone() + }, + Config { + peak_step: Some(f64::NAN), + ..good.clone() + }, + Config { + epochs: usize::MAX, + batch_size: Some(1), + ..good.clone() + }, + ] { + assert!(fit(&[1., 2.], 1, &config).is_err()); + } + let mut model = fit(&[1., 2.], 1, &good).unwrap(); + assert!(model.predict(&[]).unwrap().is_empty()); + model.dimensions = 0; + assert!(model.predict(&[1.]).is_err()); + assert!(predict(&[1., 2.], 2, &[1.]).is_err()); + assert!(predict(&[1.], 1, &[]).is_err()); +} + +#[cfg(feature = "serde")] +#[test] +fn serializable_public_api_is_available() { + fn serializable serde::Deserialize<'de>>() {} + serializable::(); + serializable::(); +} diff --git a/crates/ruvector-e-means/tests/ivf.rs b/crates/ruvector-e-means/tests/ivf.rs new file mode 100644 index 0000000000..067c016487 --- /dev/null +++ b/crates/ruvector-e-means/tests/ivf.rs @@ -0,0 +1,103 @@ +use ruvector_e_means::{Config, IvfPartition, Model}; + +fn model() -> Model { + Model { + centroids: vec![0.0, 10.0], + dimensions: 1, + assignments: vec![1, 0, 1, 0], + mse: 0.0, + batch_size: 4, + peak_step: 0.2, + updates: 1, + revived_clusters: 0, + } +} + +#[test] +fn stable_postings_group_every_input_row_exactly_once() { + let partition = IvfPartition::from_model(model()).unwrap(); + assert_eq!(partition.offsets(), [0, 2, 4]); + assert_eq!(partition.indices(), [1, 3, 0, 2]); + assert_eq!(partition.posting(0).unwrap(), [1, 3]); + assert_eq!(partition.posting(1).unwrap(), [0, 2]); + assert!(partition.posting(2).is_err()); + let restored = IvfPartition::from_parts( + model(), + partition.offsets().to_vec(), + partition.indices().to_vec(), + ) + .unwrap(); + assert_eq!(restored.indices(), partition.indices()); +} + +#[test] +fn fit_partitions_final_predictions_in_original_row_order() { + let data = [10.0, -10.0, 11.0, -11.0, 12.0, -12.0]; + let partition = IvfPartition::fit( + &data, + 1, + &Config { + clusters: 2, + epochs: 5, + ..Config::default() + }, + ) + .unwrap(); + let model = partition.model(); + assert_eq!(model.predict(&data).unwrap(), model.assignments); + let mut ids = partition.indices().to_vec(); + ids.sort_unstable(); + assert_eq!(ids, (0..data.len()).collect::>()); + for cluster in 0..2 { + let posting = partition.posting(cluster).unwrap(); + assert!(posting.windows(2).all(|p| p[0] < p[1])); + assert!(posting.iter().all(|&id| model.assignments[id] == cluster)); + } +} + +#[test] +fn malformed_offsets_labels_and_row_permutations_reject() { + for (offsets, indices) in [ + (vec![1, 2, 4], vec![1, 3, 0, 2]), + (vec![0, 3, 4], vec![1, 3, 0, 2]), + (vec![0, 5, 4], vec![1, 3, 0, 2]), + (vec![0, 2], vec![1, 3, 0, 2]), + (vec![0, 2, 4], vec![1, 1, 0, 2]), + (vec![0, 2, 4], vec![3, 1, 0, 2]), + (vec![0, 2, 4], vec![1, 3, 0, 9]), + (vec![0, 2, 4], vec![1, 3, 0]), + ] { + assert!(IvfPartition::from_parts(model(), offsets, indices).is_err()); + } + let mut invalid = model(); + invalid.assignments[0] = 2; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.centroids[0] = f32::INFINITY; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.dimensions = 0; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.batch_size = 0; + assert!(IvfPartition::from_model(invalid).is_err()); +} + +#[cfg(feature = "serde")] +#[test] +fn serde_roundtrip_rejects_corrupted_postings_and_models() { + let partition = IvfPartition::from_model(model()).unwrap(); + let value = serde_json::to_value(&partition).unwrap(); + let restored: IvfPartition = serde_json::from_value(value.clone()).unwrap(); + assert_eq!(restored.offsets(), partition.offsets()); + assert_eq!(restored.indices(), partition.indices()); + let mut invalid = value.clone(); + invalid["indices"] = serde_json::json!([1, 1, 0, 2]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value.clone(); + invalid["model"]["assignments"] = serde_json::json!([2, 0, 1, 0]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value; + invalid["offsets"] = serde_json::json!([0, 4, 2]); + assert!(serde_json::from_value::(invalid).is_err()); +} diff --git a/crates/ruvector-e-means/tests/quantization.rs b/crates/ruvector-e-means/tests/quantization.rs new file mode 100644 index 0000000000..7f88a70061 --- /dev/null +++ b/crates/ruvector-e-means/tests/quantization.rs @@ -0,0 +1,113 @@ +use ruvector_e_means::{Config, ProductQuantizer}; + +#[test] +fn subspace_layout_codes_and_reconstruction_have_an_independent_oracle() { + let pq = ProductQuantizer::from_centroids( + 4, + 2, + 2, + vec![0.0, 0.0, 10.0, 10.0, 100.0, 100.0, 200.0, 200.0], + ) + .unwrap(); + let data = [0.0, 0.0, 200.0, 200.0, 10.0, 10.0, 100.0, 100.0]; + assert_eq!(pq.encode(&data).unwrap(), [0, 1, 1, 0]); + assert_eq!(pq.decode(&[0, 1, 1, 0]).unwrap(), data); + assert_eq!(pq.encode(&[5.0, 5.0, 150.0, 150.0]).unwrap(), [0, 0]); + assert!(pq.encode(&[]).unwrap().is_empty()); + assert!(pq.decode(&[]).unwrap().is_empty()); +} + +#[test] +fn fitted_single_codebooks_recover_column_means() { + let pq = ProductQuantizer::fit( + &[1.0, 10.0, 3.0, 30.0, 5.0, 50.0], + 2, + 2, + &Config { + clusters: 1, + batch_size: Some(2), + ..Config::default() + }, + ) + .unwrap(); + assert_eq!( + ( + pq.dimensions(), + pq.subspaces(), + pq.clusters(), + pq.subspace_dimensions() + ), + (2, 2, 1, 1) + ); + assert_eq!(pq.centroids(), [3.0, 30.0]); + assert_eq!( + pq.decode(&pq.encode(&[2.0, 20.0, 9.0, 90.0]).unwrap()) + .unwrap(), + [3.0, 30.0, 3.0, 30.0] + ); +} + +#[test] +fn checked_pq_boundaries_reject_malformed_and_nonfinite_data() { + for (dimensions, subspaces, clusters, centroids) in [ + (0, 1, 1, vec![]), + (2, 0, 1, vec![0.0; 2]), + (3, 2, 1, vec![0.0; 3]), + (2, 1, 0, vec![]), + (1, 1, 257, vec![0.0; 257]), + (2, 1, 1, vec![0.0]), + (1, 1, 1, vec![f32::NAN]), + (usize::MAX, 1, 256, vec![]), + ] { + assert!( + ProductQuantizer::from_centroids(dimensions, subspaces, clusters, centroids).is_err() + ); + } + let pq = ProductQuantizer::from_centroids(2, 2, 1, vec![0.0; 2]).unwrap(); + assert!(pq.encode(&[1.0]).is_err()); + assert!(pq.encode(&[f32::INFINITY, 0.0]).is_err()); + assert!(pq.decode(&[0]).is_err()); + assert!(pq.decode(&[0, 1]).is_err()); + assert!(ProductQuantizer::fit(&[], 2, 2, &Config::default()).is_err()); + assert!(ProductQuantizer::fit( + &[0.0; 8], + 2, + 2, + &Config { + clusters: 5, + ..Config::default() + } + ) + .is_err()); +} + +#[test] +fn all_u8_codes_and_large_finite_distances_remain_valid() { + let pq = + ProductQuantizer::from_centroids(1, 1, 256, (0..256).map(|v| v as f32).collect()).unwrap(); + assert_eq!(pq.encode(&[255.0]).unwrap(), [255]); + assert_eq!(pq.decode(&[255]).unwrap(), [255.0]); + let magnitude = f32::MAX / 4.0; + let pq = ProductQuantizer::from_centroids(1, 1, 2, vec![-magnitude, magnitude]).unwrap(); + assert_eq!(pq.encode(&[magnitude * 2.0]).unwrap(), [1]); +} + +#[cfg(feature = "serde")] +#[test] +fn serde_roundtrip_validates_the_codebook_before_it_becomes_usable() { + let pq = ProductQuantizer::from_centroids(2, 2, 2, vec![0.0, 1.0, 10.0, 20.0]).unwrap(); + let value = serde_json::to_value(&pq).unwrap(); + let restored: ProductQuantizer = serde_json::from_value(value.clone()).unwrap(); + assert_eq!(restored.encode(&[1.0, 20.0]).unwrap(), [1, 1]); + for field in ["dimensions", "subspaces", "clusters"] { + let mut invalid = value.clone(); + invalid[field] = 0.into(); + assert!(serde_json::from_value::(invalid).is_err()); + } + let mut invalid = value.clone(); + invalid["centroids"] = serde_json::json!([0.0]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value; + invalid["extra"] = true.into(); + assert!(serde_json::from_value::(invalid).is_err()); +} diff --git a/crates/ruvector-pq-search/Cargo.toml b/crates/ruvector-pq-search/Cargo.toml index 7dab2653a3..f570f85dd8 100644 --- a/crates/ruvector-pq-search/Cargo.toml +++ b/crates/ruvector-pq-search/Cargo.toml @@ -16,6 +16,7 @@ name = "pq-benchmark" path = "src/main.rs" [dependencies] +ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } rand = { workspace = true } thiserror = { workspace = true } serde = { workspace = true } diff --git a/crates/ruvector-pq-search/src/codebook.rs b/crates/ruvector-pq-search/src/codebook.rs index 638c9c8d70..1193099169 100644 --- a/crates/ruvector-pq-search/src/codebook.rs +++ b/crates/ruvector-pq-search/src/codebook.rs @@ -1,9 +1,20 @@ -//! PQ codebook: M sub-spaces, K centroids each, trained with Lloyd's k-means. +//! PQ codebook: M sub-spaces, K centroids, with Lloyd and explicit e-means training. use crate::l2_sq; use rand::rngs::StdRng; use rand::{Rng, SeedableRng}; +/// Validation or shared-optimizer failure in the checked e-means PQ APIs. +#[derive(Debug, thiserror::Error)] +pub enum EmeansPqError { + /// Malformed codebook, vector, or probe configuration. + #[error("invalid e-means PQ input: {0}")] + InvalidInput(&'static str), + /// Validation failure from the shared clustering implementation. + #[error(transparent)] + Clustering(#[from] ruvector_e_means::Error), +} + /// Configuration for product quantization. #[derive(Debug, Clone)] pub struct PqConfig { @@ -11,7 +22,7 @@ pub struct PqConfig { pub m: usize, /// Number of centroids per sub-space (must be ≤ 256 for u8 codes). pub k: usize, - /// Number of Lloyd's iterations. + /// Training budget: Lloyd iterations, or epochs for explicit e-means training. pub iterations: usize, /// RNG seed (deterministic builds). pub seed: u64, @@ -54,6 +65,44 @@ pub struct PqCodebook { } impl PqCodebook { + /// Train checked e-means subspace codebooks in the existing flat PQ layout. + /// `options.clusters` is the number of u8 centroids per subspace. The same + /// configuration is used for every subspace; Lloyd defaults are unchanged. + pub fn train_e_means( + subspaces: usize, + vectors: &[f32], + dim: usize, + options: &ruvector_e_means::Config, + ) -> Result { + let quantizer = ruvector_e_means::ProductQuantizer::fit(vectors, dim, subspaces, options)?; + Ok(Self { + config: PqConfig { + m: subspaces, + k: options.clusters, + iterations: options.epochs, + seed: options.seed, + }, + sub_dim: quantizer.subspace_dimensions(), + dim, + centroids: quantizer.into_centroids(), + }) + } + + pub(crate) fn validate_e_means_layout(&self) -> Result<(), EmeansPqError> { + ruvector_e_means::ProductQuantizer::validate_parts( + self.dim, + self.config.m, + self.config.k, + &self.centroids, + )?; + if self.sub_dim != self.dim / self.config.m { + return Err(EmeansPqError::InvalidInput( + "codebook sub_dim disagrees with its shape", + )); + } + Ok(()) + } + /// Train a PQ codebook from a slice of flat row-major vectors. /// `vectors`: n × dim flat layout. pub fn train(config: PqConfig, vectors: &[f32], dim: usize) -> Self { diff --git a/crates/ruvector-pq-search/src/ivf_pq.rs b/crates/ruvector-pq-search/src/ivf_pq.rs index 123ed2f902..c0f67eca5c 100644 --- a/crates/ruvector-pq-search/src/ivf_pq.rs +++ b/crates/ruvector-pq-search/src/ivf_pq.rs @@ -4,7 +4,11 @@ //! k-means on raw vectors. At query time, probe the `n_probe` nearest cells //! and run ADC only within those lists. Reduces scan from O(n) to O(n/n_lists × n_probe). -use crate::{codebook::PqCodebook, encoder::encode_vector, l2_sq, PqSearch, SearchResult}; +use crate::{ + codebook::{EmeansPqError, PqCodebook}, + encoder::encode_vector, + l2_sq, PqSearch, SearchResult, +}; use rand::rngs::StdRng; use rand::{Rng, SeedableRng}; @@ -21,6 +25,60 @@ pub struct IvfPqIndex { } impl IvfPqIndex { + /// Train coarse e-means centroids while retaining the existing IVF+PQ + /// posting, code, and ADC search representation. `options.clusters` sets + /// the number of lists; the supplied codebook may also be e-means-trained. + pub fn new_e_means( + codebook: PqCodebook, + n_probe: usize, + training_vecs: &[f32], + options: &ruvector_e_means::Config, + ) -> Result { + codebook.validate_e_means_layout()?; + if n_probe == 0 || n_probe > options.clusters { + return Err(EmeansPqError::InvalidInput( + "n_probe must be in 1..=coarse clusters", + )); + } + let dim = codebook.dim; + let coarse = ruvector_e_means::fit(training_vecs, dim, options)?; + Ok(Self { + codebook, + coarse_centroids: coarse.centroids, + lists: vec![Vec::new(); options.clusters], + n_lists: options.clusters, + n_probe, + dim, + next_id: 0, + }) + } + + /// Insert one finite, correctly shaped vector without a partial mutation + /// on validation failure. Existing `PqSearch::insert` remains available. + pub fn try_insert(&mut self, vector: &[f32]) -> Result<(), EmeansPqError> { + self.validate_vector(vector)?; + if self.next_id == usize::MAX { + return Err(EmeansPqError::InvalidInput("vector ID overflow")); + } + ::insert(self, vector); + Ok(()) + } + + /// Search with explicit query validation before accessing legacy ADC code. + pub fn try_search(&self, query: &[f32], k: usize) -> Result, EmeansPqError> { + self.validate_vector(query)?; + Ok(::search(self, query, k)) + } + + fn validate_vector(&self, vector: &[f32]) -> Result<(), EmeansPqError> { + if vector.len() != self.dim || vector.iter().any(|value| !value.is_finite()) { + return Err(EmeansPqError::InvalidInput( + "vector must match dimensions and contain only finite values", + )); + } + Ok(()) + } + /// Build an IVF+PQ index. /// `n_lists`: number of Voronoi partitions. /// `n_probe`: cells to probe at query time. diff --git a/crates/ruvector-pq-search/tests/e_means.rs b/crates/ruvector-pq-search/tests/e_means.rs new file mode 100644 index 0000000000..4e1ff254fe --- /dev/null +++ b/crates/ruvector-pq-search/tests/e_means.rs @@ -0,0 +1,73 @@ +use ruvector_e_means::Config; +use ruvector_pq_search::{decode_vector, encode_vector, IvfPqIndex, PqCodebook}; + +fn data() -> Vec { + (0..8).flat_map(|i| [i as f32; 4]).collect() +} + +fn options(clusters: usize) -> Config { + Config { + clusters, + epochs: 1, + batch_size: Some(8), + seed: 7, + ..Config::default() + } +} + +#[test] +fn e_means_codebooks_roundtrip_existing_codes_and_adc_search() { + let data = data(); + let codebook = PqCodebook::train_e_means(2, &data, 4, &options(8)).unwrap(); + assert_eq!(codebook.centroids.len(), 8 * 4); + for row in data.as_chunks::<4>().0 { + let codes = encode_vector(&codebook, row); + assert_eq!(codes.len(), 2); + assert_eq!(decode_vector(&codebook, &codes), row.as_slice()); + let table = codebook.build_adc_table(row); + assert_eq!(codebook.adc_distance(&table, &codes), 0.0); + } + let mut index = IvfPqIndex::new_e_means(codebook, 2, &data, &options(2)).unwrap(); + assert!(index.try_insert(&[1.0]).is_err()); + assert!(index.try_insert(&[f32::NAN; 4]).is_err()); + for row in data.as_chunks::<4>().0 { + index.try_insert(row).unwrap(); + } + let results = index.try_search(&[3.0; 4], 3).unwrap(); + assert_eq!(results[0].id, 3); + assert_eq!( + results.iter().map(|r| r.distance).collect::>(), + [0.0, 4.0, 4.0] + ); + let mut ids: Vec = results.iter().map(|r| r.id).collect(); + ids.sort_unstable(); + assert_eq!(ids, [2, 3, 4]); + assert!(index.try_search(&[0.0], 1).is_err()); + assert!(index.try_search(&[f32::INFINITY; 4], 1).is_err()); + assert!(index.try_search(&[0.0; 4], 0).unwrap().is_empty()); +} + +#[test] +fn checked_constructors_reject_invalid_training_and_public_codebook_fields() { + let data = data(); + assert!(PqCodebook::train_e_means(0, &data, 4, &options(2)).is_err()); + assert!(PqCodebook::train_e_means(3, &data, 4, &options(2)).is_err()); + assert!(PqCodebook::train_e_means(2, &[0.0; 3], 4, &options(2)).is_err()); + assert!(PqCodebook::train_e_means(2, &[f32::NAN; 32], 4, &options(2)).is_err()); + assert!(PqCodebook::train_e_means(2, &data, 4, &options(9)).is_err()); + let codebook = PqCodebook::train_e_means(2, &data, 4, &options(8)).unwrap(); + for probes in [0, 3] { + assert!(IvfPqIndex::new_e_means(codebook.clone(), probes, &data, &options(2)).is_err()); + } + let mut corrupt = codebook.clone(); + corrupt.sub_dim = 0; + assert!(IvfPqIndex::new_e_means(corrupt, 1, &data, &options(2)).is_err()); + let mut corrupt = codebook.clone(); + corrupt.config.m = 0; + assert!(IvfPqIndex::new_e_means(corrupt, 1, &data, &options(2)).is_err()); + let mut corrupt = codebook.clone(); + corrupt.centroids[0] = f32::NAN; + assert!(IvfPqIndex::new_e_means(corrupt, 1, &data, &options(2)).is_err()); + assert!(IvfPqIndex::new_e_means(codebook.clone(), 1, &[], &options(2)).is_err()); + assert!(IvfPqIndex::new_e_means(codebook, 1, &[0.0; 3], &options(2)).is_err()); +} diff --git a/crates/ruvector-rairs/Cargo.toml b/crates/ruvector-rairs/Cargo.toml index bd069d489a..e731e27152 100644 --- a/crates/ruvector-rairs/Cargo.toml +++ b/crates/ruvector-rairs/Cargo.toml @@ -14,6 +14,7 @@ name = "rairs-demo" path = "src/main.rs" [dependencies] +ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } rand = "0.8" serde = { version = "1", features = ["derive"] } diff --git a/crates/ruvector-rairs/src/ivf.rs b/crates/ruvector-rairs/src/ivf.rs index 160c1bcb08..14fb0cf5b7 100644 --- a/crates/ruvector-rairs/src/ivf.rs +++ b/crates/ruvector-rairs/src/ivf.rs @@ -22,6 +22,22 @@ pub struct IvfFlat { } impl IvfFlat { + /// Train with the shared e-means optimizer instead of Lloyd's algorithm. + /// `options.clusters` must match this index's configured cluster count; + /// epochs and seed come from `options`. Successful retraining clears all + /// inserted vectors and restarts IDs; validation failure preserves state. + pub fn train_e_means( + &mut self, + corpus: &[Vec], + options: &ruvector_e_means::Config, + ) -> Result<(), RairsError> { + let centroids = train_e_means_centroids(corpus, self.dim, self.nclusters, options)?; + self.lists = vec![Vec::new(); centroids.len()]; + self.centroids = centroids; + self.total = 0; + Ok(()) + } + /// Create a new untrained IvfFlat index. /// /// * `dim` — vector dimensionality @@ -59,6 +75,54 @@ impl IvfFlat { } } +/// Shared validated centroid training for the IVF, RAIRS, and SEIL layouts. +pub(crate) fn train_e_means_centroids( + corpus: &[Vec], + dimensions: usize, + clusters: usize, + options: &ruvector_e_means::Config, +) -> Result>, RairsError> { + if corpus.is_empty() { + return Err(RairsError::EmptyCorpus); + } + if dimensions == 0 || options.clusters != clusters { + return Err(RairsError::InvalidParam( + "e-means requires positive dimensions and a matching cluster count".into(), + )); + } + options + .parameters(corpus.len()) + .map_err(|error| RairsError::InvalidParam(error.to_string()))?; + let capacity = corpus + .len() + .checked_mul(dimensions) + .ok_or_else(|| RairsError::InvalidParam("training shape overflows usize".into()))?; + for row in corpus { + if row.len() != dimensions { + return Err(RairsError::DimMismatch { + expected: dimensions, + got: row.len(), + }); + } + if row.iter().any(|value| !value.is_finite()) { + return Err(RairsError::InvalidParam( + "e-means training vectors must contain only finite values".into(), + )); + } + } + let mut data = Vec::with_capacity(capacity); + for row in corpus { + data.extend_from_slice(row); + } + let model = ruvector_e_means::fit(&data, dimensions, options) + .map_err(|error| RairsError::InvalidParam(error.to_string()))?; + Ok(model + .centroids + .chunks_exact(dimensions) + .map(<[f32]>::to_vec) + .collect()) +} + impl AnnIndex for IvfFlat { fn add(&mut self, vectors: &[Vec]) -> Result<(), RairsError> { if self.centroids.is_empty() { diff --git a/crates/ruvector-rairs/src/rairs.rs b/crates/ruvector-rairs/src/rairs.rs index da9c342c2f..b87f99f7cd 100644 --- a/crates/ruvector-rairs/src/rairs.rs +++ b/crates/ruvector-rairs/src/rairs.rs @@ -34,6 +34,26 @@ pub struct RairsStrict { } impl RairsStrict { + /// Train explicit e-means centroids, preserving this variant's redundant + /// assignment and search layout. Cluster count must match the constructor; + /// the supplied options control epochs and seed. A failed fit preserves + /// current state; successful retraining clears vectors and resets IDs. + pub fn train_e_means( + &mut self, + corpus: &[Vec], + options: &ruvector_e_means::Config, + ) -> Result<(), RairsError> { + if !self.lambda.is_finite() { + return Err(RairsError::InvalidParam("lambda must be finite".into())); + } + let centroids = + crate::ivf::train_e_means_centroids(corpus, self.dim, self.nclusters, options)?; + self.lists = vec![Vec::new(); centroids.len()]; + self.centroids = centroids; + self.total = 0; + Ok(()) + } + /// Create a new untrained RairsStrict index. /// /// `lambda` is the RAIR amplification factor (paper default = 1.0). diff --git a/crates/ruvector-rairs/src/seil.rs b/crates/ruvector-rairs/src/seil.rs index 19d7d6a1c5..124c5aebf0 100644 --- a/crates/ruvector-rairs/src/seil.rs +++ b/crates/ruvector-rairs/src/seil.rs @@ -48,6 +48,26 @@ pub struct RairsSeil { } impl RairsSeil { + /// Train explicit e-means centroids while retaining SEIL block storage and + /// redundant assignment. Cluster count must match the constructor; options + /// provide epochs and seed. Failure preserves state; success clears stored + /// vectors and restarts their IDs at zero. + pub fn train_e_means( + &mut self, + corpus: &[Vec], + options: &ruvector_e_means::Config, + ) -> Result<(), RairsError> { + if !self.lambda.is_finite() { + return Err(RairsError::InvalidParam("lambda must be finite".into())); + } + let centroids = + crate::ivf::train_e_means_centroids(corpus, self.dim, self.nclusters, options)?; + self.lists = vec![Vec::new(); centroids.len()]; + self.centroids = centroids; + self.total = 0; + Ok(()) + } + /// Create a new untrained RairsSeil index. pub fn new(dim: usize, nclusters: usize, max_iter: usize, seed: u64, lambda: f32) -> Self { Self { diff --git a/crates/ruvector-rairs/tests/e_means.rs b/crates/ruvector-rairs/tests/e_means.rs new file mode 100644 index 0000000000..388ac60f5f --- /dev/null +++ b/crates/ruvector-rairs/tests/e_means.rs @@ -0,0 +1,114 @@ +use ruvector_e_means::Config; +use ruvector_rairs::{AnnIndex, IvfFlat, RairsSeil, RairsStrict}; + +fn corpus() -> Vec> { + (0..40) + .map(|i| vec![i as f32, i as f32 * 0.1, (i % 3) as f32, -(i as f32)]) + .collect() +} + +fn options() -> Config { + Config { + clusters: 4, + epochs: 3, + batch_size: Some(7), + seed: 17, + ..Config::default() + } +} + +fn assert_full_probe_ground_truth(index: &dyn AnnIndex, vectors: &[Vec]) { + let query = [17.37, 1.65, 2.13, -17.91]; + let mut truth: Vec<(usize, f64)> = vectors + .iter() + .enumerate() + .map(|(id, row)| { + ( + id, + row.iter() + .zip(query) + .map(|(&x, y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum::() + .sqrt(), + ) + }) + .collect(); + truth.sort_by(|a, b| a.1.total_cmp(&b.1)); + let results = index.search(&query, 5, index.num_lists()).unwrap(); + assert_eq!(results.len(), 5); + for (actual, expected) in results.iter().zip(truth) { + assert_eq!(actual.id, expected.0); + assert!((f64::from(actual.distance) - expected.1).abs() < 0.001); + } +} + +#[test] +fn all_rairs_layouts_use_e_means_and_preserve_search_and_training_atomicity() { + let vectors = corpus(); + let config = options(); + macro_rules! check { + ($index:expr) => {{ + let mut index = $index; + index.train_e_means(&vectors, &config).unwrap(); + index.add(&vectors).unwrap(); + assert_eq!(index.len(), vectors.len()); + assert_full_probe_ground_truth(&index, &vectors); + let before = index.search(&vectors[17], 5, 4).unwrap(); + let mut invalid = vectors.clone(); + invalid[3].pop(); + assert!(index.train_e_means(&invalid, &config).is_err()); + invalid = vectors.clone(); + invalid[3][0] = f32::NAN; + assert!(index.train_e_means(&invalid, &config).is_err()); + assert!(index.train_e_means(&[], &config).is_err()); + let mut bad_options = config.clone(); + bad_options.clusters = 5; + assert!(index.train_e_means(&vectors, &bad_options).is_err()); + bad_options = config.clone(); + bad_options.epochs = 0; + assert!(index.train_e_means(&vectors, &bad_options).is_err()); + assert_eq!(index.len(), vectors.len()); + assert_eq!(index.search(&vectors[17], 5, 4).unwrap(), before); + index.train_e_means(&vectors, &config).unwrap(); + assert!(index.is_empty()); + index.add(&vectors[10..12]).unwrap(); + assert_eq!(index.len(), 2); + assert_eq!(index.search(&vectors[10], 1, 4).unwrap()[0].id, 0); + }}; + } + check!(IvfFlat::new(4, 4, 25, 42)); + check!(RairsStrict::new(4, 4, 25, 42, 1.0)); + check!(RairsSeil::new(4, 4, 25, 42, 1.0)); +} + +#[test] +fn invalid_constructor_settings_reject_without_a_training_panic() { + let vectors = corpus(); + assert!(IvfFlat::new(0, 4, 25, 42) + .train_e_means(&vectors, &options()) + .is_err()); + assert!(IvfFlat::new(4, 0, 25, 42) + .train_e_means( + &vectors, + &Config { + clusters: 0, + ..options() + } + ) + .is_err()); + assert!(IvfFlat::new(4, 41, 25, 42) + .train_e_means( + &vectors, + &Config { + clusters: 41, + ..options() + } + ) + .is_err()); + assert!(RairsStrict::new(4, 4, 25, 42, f32::NAN) + .train_e_means(&vectors, &options()) + .is_err()); + assert!(RairsSeil::new(4, 4, 25, 42, f32::INFINITY) + .train_e_means(&vectors, &options()) + .is_err()); +} diff --git a/crates/ruvector-wasm/clustering.d.mts b/crates/ruvector-wasm/clustering.d.mts new file mode 100644 index 0000000000..2ca0a76f10 --- /dev/null +++ b/crates/ruvector-wasm/clustering.d.mts @@ -0,0 +1,2 @@ +export { init, fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; diff --git a/crates/ruvector-wasm/clustering.mjs b/crates/ruvector-wasm/clustering.mjs new file mode 100644 index 0000000000..f1f8835355 --- /dev/null +++ b/crates/ruvector-wasm/clustering.mjs @@ -0,0 +1,2 @@ +/** Shared Rust/WASM clustering; initialize explicitly before numerical calls. */ +export { init, fit, predict } from '@ruvector/e-means'; diff --git a/crates/ruvector-wasm/clustering/cloudflare.d.mts b/crates/ruvector-wasm/clustering/cloudflare.d.mts new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/crates/ruvector-wasm/clustering/cloudflare.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/crates/ruvector-wasm/clustering/cloudflare.mjs b/crates/ruvector-wasm/clustering/cloudflare.mjs new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/crates/ruvector-wasm/clustering/cloudflare.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/crates/ruvector-wasm/clustering/ivf.d.mts b/crates/ruvector-wasm/clustering/ivf.d.mts new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/crates/ruvector-wasm/clustering/ivf.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/crates/ruvector-wasm/clustering/ivf.mjs b/crates/ruvector-wasm/clustering/ivf.mjs new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/crates/ruvector-wasm/clustering/ivf.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/crates/ruvector-wasm/clustering/metaharness.d.mts b/crates/ruvector-wasm/clustering/metaharness.d.mts new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/crates/ruvector-wasm/clustering/metaharness.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/crates/ruvector-wasm/clustering/metaharness.mjs b/crates/ruvector-wasm/clustering/metaharness.mjs new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/crates/ruvector-wasm/clustering/metaharness.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/crates/ruvector-wasm/clustering/quantization.d.mts b/crates/ruvector-wasm/clustering/quantization.d.mts new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/crates/ruvector-wasm/clustering/quantization.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/crates/ruvector-wasm/clustering/quantization.mjs b/crates/ruvector-wasm/clustering/quantization.mjs new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/crates/ruvector-wasm/clustering/quantization.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/crates/ruvector-wasm/package.json b/crates/ruvector-wasm/package.json index bd16bae8d1..0fb4030afd 100644 --- a/crates/ruvector-wasm/package.json +++ b/crates/ruvector-wasm/package.json @@ -13,6 +13,26 @@ "./adapter": { "types": "./src/adapter.d.ts", "default": "./src/adapter.js" + }, + "./clustering": { + "types": "./clustering.d.mts", + "import": "./clustering.mjs" + }, + "./clustering/quantization": { + "types": "./clustering/quantization.d.mts", + "import": "./clustering/quantization.mjs" + }, + "./clustering/ivf": { + "types": "./clustering/ivf.d.mts", + "import": "./clustering/ivf.mjs" + }, + "./clustering/metaharness": { + "types": "./clustering/metaharness.d.mts", + "import": "./clustering/metaharness.mjs" + }, + "./clustering/cloudflare": { + "types": "./clustering/cloudflare.d.mts", + "import": "./clustering/cloudflare.mjs" } }, "files": [ @@ -21,7 +41,10 @@ "src/adapter.d.ts", "src/worker.js", "src/worker-pool.js", - "src/indexeddb.js" + "src/indexeddb.js", + "clustering.mjs", + "clustering.d.mts", + "clustering/" ], "scripts": { "build": "npm run build:web && npm run build:simd && npm run build:bundler", @@ -59,6 +82,9 @@ "bugs": { "url": "https://github.com/ruvnet/ruvector/issues" }, + "dependencies": { + "@ruvector/e-means": "0.1.0" + }, "devDependencies": { "wasm-pack": "^0.12.1" } diff --git a/docs/adr/ADR-359-e-means-shared-clustering.md b/docs/adr/ADR-359-e-means-shared-clustering.md new file mode 100644 index 0000000000..d4decba3c6 --- /dev/null +++ b/docs/adr/ADR-359-e-means-shared-clustering.md @@ -0,0 +1,226 @@ +# ADR-359: Shared e-means clustering for RuVector and ruv-FANN + +- **Status**: Accepted; local implementation, registry publication pending +- **Date**: 2026-11-11 +- **Source**: Bessa et al., [e-means: outperforming k-means (in one-tenth the epochs)](https://arxiv.org/abs/2611.09501), [version 1](https://arxiv.org/html/2611.09501v1), 2026-11-06 +- **Related**: [ruv-FANN ADR-013](https://github.com/ruvnet/ruv-FANN/blob/main/docs/adr/ADR-013-e-means-clustering.md) + +## Context and scope + +RuVector trains product-quantization codebooks with Lloyd k-means. ruv-FANN +consumers also need unsupervised clustering of input embeddings without changing +their supervised labels or neural optimizers. Maintaining independent clustering +implementations for Rust and JavaScript would make numerical fixes and paper +conformance diverge. + +The paper proposes mini-batch EMA sufficient statistics plus a particular +initialization, schedule, cluster revival, and finalization recipe. Its reported +GPU results motivate implementation, but do not establish performance of this CPU +implementation. Its fitted hyperparameters are less reliable for tiny and +low-dimensional data, including many PQ subspaces. This release therefore adds +explicit e-means APIs while preserving existing training defaults and persisted +codebook formats. + +## Decision and contracts + +Create `ruvector-e-means` 0.1.0 as a separately publishable, MIT-licensed crate in +`crates/ruvector-e-means`, registered in the workspace. The native core requires +Rust 1.81, has no default features, and has no dependency on either consumer. +`serde` adds config/model serialization. `wasm` adds a thin wasm-bindgen bridge. +Pin wasm-bindgen and its build CLI to the existing workspace version 0.2.125 so +this feature does not upgrade other packages' WASM dependency stack. + +The public core API is `fit(flat_f32_rows, dimensions, &Config) -> Result` +and exact `predict`. `Config` exposes clusters, epochs (default 3), optional batch +and peak-step overrides, seed (default 42), and finalization. `Model` returns flat +centroids, assignments, dimensions, squared-L2 MSE per vector, resolved batch and +step, update count, and number of revived clusters. Assignments are recomputed +against the returned centroids in original row order. Public/deserialized +codebooks are validated when passed to prediction. + +Implement the paper's primary recipe: + +1. Seeded ChaCha8 sampling without replacement for initial centroids; initialize + counts to `1e-10` and sums to count times centroid (equation 4). +2. Resolve `B = 0.035 k^0.13 n^0.88 T^0.81`, divided by eight when + `n > 2,000,000`, rounded to the nearest power of two and capped at `n`. + Resolve `alpha0 = min(0.824 k^-0.46 B^0.90 n^-0.45 T^-0.11, 1)` using + the effective batch size (equations 6–7, table 2). +3. Shuffle each epoch. Assign rows by exact squared L2 and accumulate per-cluster + batch counts/sums. Update every cluster's statistics with equation 2 and + the cosine step from equation 5, including its 0.1 floor and `t/M` denominator. +4. Every five batches revive counts below 0.1 times the mean count. Draw live + donors proportional to count, without replacement. Split count in half and + perturb child coordinates by alternating `1 +/- 1/128` (Appendix H). +5. Finalize using the mean of assignments recorded during the last epoch, or + return the main EMA centroids. Recompute nearest assignments and MSE in a + final exact pass. + +Use f64 sums, counts, and distances, and f32 codebooks. Retain a negligible +pseudo-count for a temporarily empty cluster when a step of one would otherwise +erase its state. Clamp extreme split coordinates to finite f32. Final clusters +without recorded rows retain their EMA centroid. If dead slots outnumber live +donors, remaining slots wait until a later revival pass. + +Two deliberate execution differences from the printed algorithm are explicit: +include short tail batches rather than dropping rows, with +`M = T * ceil(n/B)`; and recompute final nearest assignments/MSE rather than +reporting the loss of stale last-epoch assignments. Last-epoch mean is an average +of assignments made while centroids moved, not a separate Lloyd iteration, so we +do not promise monotonic improvement over the final EMA model. + +`@ruvector/e-means` 0.1.0 in `npm/packages/e-means` ships that same Rust core as +portable WebAssembly, typed ESM APIs, and the matching generated loader. +`await init()` loads bundled bytes in Node and fetches them in a browser; +`fit(Float32Array, dimensions, options)` and `predict` run synchronously after +initialization. No JavaScript numerical fallback or Rust installation is needed +by an installed consumer. Training calls are bounded by caller-selected sizes +and epochs and can block the caller; applications should use workers for long +runs. The Rust crate itself does not spawn threads or fetch datasets. + +## Consumer integration and release order + +- RuVector core directly depends on the new crate and exposes + `ProductQuantized::train_e_means(vectors, num_subspaces, &Config)`. It trains + each subspace with the shared implementation and retains u8 codes and the + current codebook serialization. f64 encode comparisons preserve nearest + ordering for large finite f32 coordinates. +- The main `ruvector` npm package depends on exact `@ruvector/e-means` 0.1.0 and + ships `ruvector/clustering.mjs` with matching ESM declarations. This explicit + subpath avoids eagerly initializing WASM or restricting legacy package + subpaths with a new exports map. +- ruv-FANN has an optional `clustering` Cargo feature with a version-only + dependency on `ruvector-e-means` 0.1.0, re-exported types/functions, and + `TrainingData::cluster_inputs`. It clusters inputs without mutating inputs + or outputs. Its npm facade depends on exact `@ruvector/e-means` 0.1.0 and + exposes `ruv-fann/clustering` without changing the root neural API. + +Publish the new crate and npm package before releasing dependent consumer +versions. Before registry publication, qualify ruv-FANN with an explicit local +Cargo patch and install the packed npm dependency in isolated consumer tests: + +```sh +cd ../ruv-FANN +cargo test --features clustering --test clustering_tests \ + --config 'patch.crates-io.ruvector-e-means.path="../ruvector/crates/ruvector-e-means"' +``` + +No sibling checkout path is committed in ruv-FANN's published dependency +contract. Its version-only dependency cannot resolve from a fresh registry +checkout until the new crate is published, even with the feature disabled. +Local lockfile qualification with a patch does not prove registry availability. +Do not claim publication based on a successful local build or archive check. + +## Alternatives and consequences + +- Copying the algorithm into both projects and npm would multiply maintenance + and correctness risk. A single Rust implementation compiled to WASM keeps + numerical behavior shared. +- Replacing all Lloyd defaults immediately risks quality regressions for small + PQ subspaces outside the scaling laws' fitted domain. Explicit APIs allow + evaluation with real embeddings and consumer-specific recall/latency gates. +- A GPU/PyTorch/Faiss runtime dependency would add substantial deployment cost. + This CPU reference and portable WASM establish the contract first. GPU, + low-precision, distributed/IVF assignment, slow-EMA finalization, arbitrary + streaming updates, and wholesale replacement of all clustering call sites are + outside this release. + +The algorithm stores O(n + kd) scratch state and performs O(Tnkd) exact-distance +work plus a final O(nkd) scoring pass. Training is synchronous. Seeded shuffles +are stable across native/WASM; platform transcendental routines can introduce +small floating-point differences, so cross-target numerical checks use an +appropriate tolerance rather than a universal bit-identity claim. + +## Acceptance and validation + +| Requirement | Executable evidence | +|---|---| +| Paper coefficients, cosine schedule, weighted mass-preserving revival | `cargo test -p ruvector-e-means` | +| Mean/MSE oracle, all tail rows visited, reproducibility, separated clouds | crate `tests/clustering.rs` | +| Empty/ragged/nonfinite shapes, invalid configs, overflow, duplicate/zero/extreme inputs | crate and consumer Rust tests; npm WASM tests | +| PQ representation, serialization, all 256 u8 codes, extreme nearest comparison | `cargo test -p ruvector-core --no-default-features --test e_means_quantization` | +| ruv-FANN adapter and unchanged supervised state | patched `clustering_tests` plus existing library tests | +| Same Rust core used through typed npm facade | `npm test` and `npm run typecheck` in the new package; consumer facade tests | +| Complete installable npm artifact without repository paths | `npm run test:consumer` in the new package | +| Browser default fetch/initialization | new package's headless browser consumer test | + +Build WASM with `npm run build` in the new package, using the pinned CLI. Its +prepack check executes the shipped artifact. Review and run the targeted checks +before release; this ADR does not certify the entire monorepo, GPU speedups, or +universal quality superiority. Rollback means use the retained Lloyd/neural APIs +or stop importing the clustering subpaths; existing persisted codebooks need no +migration. + +### Local qualification on 2026-11-11 + +- The shared crate passed 10 native tests with all features and strict Clippy. + `cargo package --allow-dirty` built and verified the archive. Its native core + also passed `cargo +1.81.0 check --locked` against the packaged manifest. +- Actual RuVector core passed 6 new integration tests and 36 existing + quantization tests. ruv-FANN passed 3 adapter tests and 207 existing library + tests with the local dependency patch. +- The final wasm-bindgen 0.2.125 artifact passed 9 Node numerical/API tests, + offline installed-archive qualification, strict TypeScript, and both consumer + facade checks. Packed ruv-FANN was also installed with the packed dependency + and exercised through its public subpath. +- Browser execution remains unverified here: the browser consumer timed out, + and independent Chromium `about:blank` startup also timed out, including a + single-process baseline. The checked-in browser test fails on that timeout; + no skip or simulated success is counted as a pass. Re-run it in a working + Chromium environment before claiming browser qualification. + +These are focused local checks. Neither registry publication nor full-monorepo +qualification was performed. + +## Optimization qualification + +Exact partial-distance pruning checks candidates every eight coordinates for +dimensions above 16, while small codebooks retain scalar distance evaluation. +Zero distance ends the search. These changes retain the scalar addition order +and lowest-index ties. Independent exhaustive-oracle tests cover diffuse and +separated inputs, extreme/subnormal coordinates, near ties, and dimensions with +incomplete final blocks. The optimization does not add approximate assignment +or change seeded shuffles, sufficient statistics, or finalizers. + +Training uses sliced centroid rows, reuses dead/donor scratch capacity, skips +donor-list construction when no cluster is dead, and omits last-epoch statistics +for EMA finalization. PQ encoding computes each candidate distance once. The +WASM wrapper keeps JSON for the small config and returns vectors as owned typed +arrays, releasing its temporary Rust handle in `finally`. Tests check repeated +fits, error-path cleanup, and output survival after WASM memory growth. + +On the local AMD EPYC 9V74 environment, five interleaved native repetitions +showed these median fit times for last-epoch-mean finalization: + +| Synthetic input (n × d, clusters) | Before | After | Speedup | +|---|---:|---:|---:| +| Clustered embeddings (4096 × 128, 64) | 130.05 ms | 70.57 ms | 1.84× | +| Diffuse embeddings (2048 × 768, 32) | 203.61 ms | 177.48 ms | 1.15× | +| Duplicate/zero rows (2048 × 32, 64) | 13.35 ms | 2.53 ms | 5.29× | + +All model fields and predictions matched the baseline bit for bit in eight +native scenarios. A 21-repeat 8D PQ follow-up measured 51.25→52.68 ms with +last-epoch mean and 50.28→50.83 ms with EMA; no PQ speedup is claimed. EMA mode +on the 768D fixture reduced peak additional requested heap from 721,664 to +525,312 bytes. Last-epoch-mean mode may retain a little more scratch capacity; +allocation-event reduction is distinct from peak-memory reduction. + +Node 24 WASM median-of-seven fit times were 36.19→15.00 ms (2.41×) for an +8192 × 64, 16-cluster fixture and 84.09→61.57 ms (1.37×) for one million +scalar rows with one cluster. Both match baseline centroids, assignments and +MSE. Comparing JSON and typed output using the same optimized kernel measured +75.97→58.41 ms on the million-row fixture; this includes the whole fit and +materialization, not just conversion time. + +The [measurement artifact](../research/e-means/performance-2026-11-11.json) +records shapes, options, raw native samples, environment, allocation definitions, +and source/artifact checksums. The native benchmark example and npm `benchmark` +command reproduce current measurements. These synthetic CPU/WASM results do not +establish speedups on arbitrary datasets or the paper's GPU benchmarks. Browser +qualification and registry publication remain pending. + +Post-optimization validation passed 14 shared-crate tests, 6 PQ integration +tests, 20 existing core quantization tests, 207 ruv-FANN library tests and its +3 adapter tests. The npm runtime passed 13 numerical/ownership tests, installed +archive checks, both consumer facades and strict TypeScript. Strict Clippy, +crate archive verification, and the packaged native Rust 1.81 check also passed. diff --git a/docs/adr/ADR-360-e-means-ecosystem-integrations.md b/docs/adr/ADR-360-e-means-ecosystem-integrations.md new file mode 100644 index 0000000000..beca468bbf --- /dev/null +++ b/docs/adr/ADR-360-e-means-ecosystem-integrations.md @@ -0,0 +1,184 @@ +# ADR-360: e-means ecosystem submodules, MetaHarness, and Cloudflare Workers + +- **Status**: Accepted; local integration implemented, publication and deployment pending +- **Date**: 2026-11-11 +- **Related**: [ADR-359](./ADR-359-e-means-shared-clustering.md) + +## Outcome and acceptance contract + +Make the shared e-means implementation usable for existing PQ/IVF indexes, +neural-input workflows, measured MetaHarness tuning, and Cloudflare Workers. +Integrations must invoke the real Rust/WASM kernel, preserve current training +defaults, expose explicit typed entrypoints, and run from installed npm archives. +Here, submodules mean Rust modules and npm export subpaths; no Git submodule +checkout is required. + +Success requires numerical encode/decode and posting-list oracles; checked +restoration of persisted records; actual Darwin evolution with held-out scoring; +authenticated, resource-bounded Worker execution with statically imported WASM; +and real local workerd/R2 qualification. Hosted deployment, registry publication, +and live Vectorize mutation are outside this implementation request. + +## Module boundaries + +| Surface | Interface and responsibility | +|---|---| +| Rust `quantization` | `ProductQuantizer::fit`, checked `from_centroids`, byte `encode`/`decode`, private shape fields, validated serde restoration | +| Rust `ivf` | `IvfPartition::fit`, checked `from_model`/`from_parts`, stable offsets/indices, checked `posting` access | +| npm `/quantization` | `trainProductQuantizer`, `encodeProductQuantizer`, `decodeProductQuantizer`, validated owned JSON conversions | +| npm `/ivf` | `partition` and `postingList`, with owned typed arrays and stable input-row IDs | +| npm `/runtime` | Node-free `init(source)`, `fit`, `predict`; requires explicit bytes or a precompiled module | +| npm `/metaharness` | `createClusteringEvaluator` and bounded Node-only `tuneClustering`, using the actual Darwin numeric API | +| npm `/cloudflare` | Stateless Worker factory and explicit R2/Vectorize binding helpers | +| npm `/cloudflare/build` | Node-only local static-WASM builder, using esbuild; never deploys | +| npm `/wasm` | Raw artifact export for Wrangler's static WebAssembly import | + +PQ decomposition and posting construction wrap the shared fitter and nearest +assignment. There is no second JavaScript clustering optimizer. All PQ codes are +row-major, one u8 per subspace; centroids are subspace-major. Rust and JavaScript +use the same numeric layout, but JS JSON has an explicit schema envelope. Remove +that envelope before native serde deserialization, or construct the native +quantizer with its checked `from_centroids` API. Do not assume arbitrary JSON +records from the two APIs are interchangeable. + +## Actual consumers + +- `ruvector-core::ProductQuantized::train_e_means` remains available from ADR-359. +- `ruvector-pq-search` adds `PqCodebook::train_e_means`, + `IvfPqIndex::new_e_means`, and checked insertion/query wrappers. Existing PQ + layouts and ADC search behavior remain in place. +- `ruvector-rairs` adds explicit training to `IvfFlat`, `RairsStrict`, and + `RairsSeil`. Invalid training leaves state intact. Successful explicit + retraining resets inserted vectors and IDs, as documented by these methods. +- `@ruvector/core`, `ruvector`, and `@ruvector/all` ship `clustering.mjs` and + `clustering/{quantization,ivf,metaharness,cloudflare}.mjs`, with `.d.mts` + declarations. Their existing package subpaths remain accessible. +- The current `@ruvector/wasm` source at `crates/ruvector-wasm` exposes + `/clustering` and `/clustering/{quantization,ivf,metaharness,cloudflare}`. + Historical same-name manifest copies are not release sources for this change. +- `ruv-fann` and `@ruv-fann/integrations` expose corresponding clustering + subpaths. Existing WSP Cloudflare and neural MetaHarness entrypoints retain + their own meanings. + +Each npm consumer depends on exact `@ruvector/e-means` 0.1.0. It is an optional +dependency for `@ruvector/core`, whose legacy entrypoint supports Node 18; +clustering entrypoints require the shared package's Node 20 runtime. When optional +dependencies are omitted, install the shared package explicitly. The new modules +do not eagerly initialize WASM or import Darwin during ordinary SDK imports. + +Shared modules use f64 assignment arithmetic. Existing downstream ADC/scanning +APIs retain their existing f32 precision and legacy validation behavior; this +integration does not certify those algorithms for extreme f32 magnitudes or +silently replace their defaults. + +## MetaHarness control flow and evidence + +The evaluator synchronously copies training/holdout arrays and snapshots the +baseline, domain, and budgets before its first await. Holdout rows must be +nonempty and nonoverlapping with training rows. Each dispatch validates the +genome, reserves its work allowance, executes real WASM training, and separately +predicts and scores the holdout. Higher-is-better `primary = 1/(1+holdoutMse)` +matches Darwin's score contract. Records include actual training/holdout MSE, +fit/prediction timings, selected configuration, and resource estimates. + +Only one evaluation runs at a time, with at most 32 admitted dispatches, +64 MiB of input snapshots, and a caller-selected allowance capped at 1e9 +coordinate-scale work units. Admission includes centroid updates, tail batches, +and quadratic donor selection. Units are conservative estimates, not measured +instructions or a process-memory limit. Deadlines are cooperative; synchronous +fits and arbitrary host operations cannot be preempted. + +`tuneClustering` dynamically loads exact `@metaharness/darwin` 0.13.0, validates +the installed identity/API, and calls its real `evolveNumeric` at concurrency 1. +It checks worst-case search cost before execution and matches returned archive +records to observed evaluations. Regressed/unmeasured winners cannot replace +the baseline recommendation. A temporary archive is removed in `finally`. +Receipts and returned scores are independent copies; `sourceApplied` is always +false. The holdout guides selection and is not an independent generalization +test. SDK version checking is metadata validation, not binary attestation. + +The SDK is an optional peer, loaded only when tuning is invoked. Package tests +exercise both an installation without that peer and actual evolution with the +pinned peer installed. + +## Cloudflare execution and authority boundaries + +Wrangler imports `.wasm` as `WebAssembly.Module`; the Worker passes that static +module to the Node-free runtime. No Node filesystem loader, downloaded model, +runtime source compilation, or `instantiateStreaming` path is needed. + +The Worker exposes public `/health` and authenticated POST `/fit` and `/predict`. +Operations fail closed when no token is configured, except an explicit trusted +local `allowUnauthenticated` opt-in. The example reads `E_MEANS_BEARER_TOKEN` +from the caller's binding configuration; credentials are not packaged. + +Before entering WASM, the handler reads bounded UTF-8 JSON with a stream deadline +and validates exact fields, finite float32 values, shapes, options, and work. +Absolute caps include 1 MiB request bodies, 262,144 elements, 16,384 rows, +1,536 dimensions, 256 clusters, 32 epochs, and 1e8 estimated work units; defaults +are smaller. The work estimate includes updates and donor revival. These are +per-call bounds, not a guarantee against aggregate isolate exhaustion or a hard +CPU-time cap. Request vectors/models are not kept in global mutable state, and +HTTP responses expose no unexpected stack traces. + +Storage operations are explicit helper calls on caller-owned bindings. HTTP +fitting does not automatically store or export anything: + +- R2 stores only bounded centroid codebooks, not source vectors or assignments. + Writes require an acknowledgement; reads validate streamed bytes and schema + before constructing owned numeric arrays. PQ schema records are rejected + because their subspace-major layout is not a single centroid set. +- Vectorize V2 exports validate the entire snapshot and identifier/namespace + byte lengths before the first upsert. Batches are limited to 1,000 vectors + and dimensions to 1,536. Every acknowledgement must carry a mutation ID. + An acknowledgement does not prove immediate query visibility. +- Export failures report prior acknowledged rows/mutation IDs. The failed batch + may also have applied; no transaction, rollback, retry, or deletion is implied. + Use a versioned prefix/namespace for revised codebooks, since upserts do not + remove stale IDs from an older, larger codebook. + +Official Cloudflare references: [WASM bundling](https://developers.cloudflare.com/workers/wrangler/bundling/), +[Vectorize limits](https://developers.cloudflare.com/vectorize/platform/limits/), +[asynchronous mutations](https://developers.cloudflare.com/vectorize/get-started/intro/). +The connected Cloudflare documentation tool was used to verify these contracts. + +## Packaging, validation, and rollback + +Use the isolated package lock in `npm/packages/e-means` for integration tooling. +Miniflare 4.20260730.0 and esbuild 0.28.2 are development-only. Scoped overrides +select patched sharp 0.35.5 and undici 7.30.1; re-run workerd tests and the +lockfile-aware audit when updating them. The workspace lock records this tool +graph beneath the e-means workspace without upgrading unrelated dependency +versions. Whole-workspace installation remains separately constrained by the +repository's existing platform-specific workspace packages. + +| Requirement | Check | +|---|---| +| Native layout, persisted-state validation, real index consumers | `cargo test -p ruvector-e-means --features serde -p ruvector-pq-search -p ruvector-rairs` | +| Existing shared core and optional WASM bridge | `cargo test -p ruvector-e-means --all-features` | +| JS numerical, ownership, holdout, budget and HTTP boundaries | `npm test` in the shared package | +| Installed package without/with actual optional Darwin SDK | `npm run test:consumer` | +| New entrypoints from actual consumer archives | `npm run test:ecosystem` | +| Real static WASM and R2 in local workerd | `npm run test:cloudflare` | +| Public declarations | `npm run typecheck` and installed consumer checks | +| Newly selected tool dependency graph | `npm audit --package-lock-only --workspaces=false` | + +Consumer archive tests qualify the new clustering subpaths. Their unrelated +legacy root/prepack release builds are not qualified by this task. Vectorize +has binding-contract tests, not a claimed hosted index write. No Cloudflare +deployment or registry publication is inferred from passing local checks. + +Release the shared crate/package first, bump affected consumer release versions, +and verify registry installs before publishing consumers. Local ruv-FANN Rust +checks use the explicit Cargo patch from ADR-359. Rollback means stop using the +new feature methods or subpaths; existing codebooks, neural APIs, and search +defaults require no migration. Storage helpers never delete external resources. + +Local qualification passed 50 targeted Rust tests, 44 shared npm tests, 8 FANN +facade tests, and 3 Rust FANN adapter tests, plus strict declarations, Clippy, +archive verification and the packaged Rust 1.81 check. Installed consumers +exercised the optional-SDK absence path, actual Darwin evolution, all four +RuVector facade packages, and static-WASM/R2 execution in real local workerd. +The isolated integration-tool lockfile audit reported zero known advisories +after the scoped overrides. [Qualification evidence](../research/e-means/integrations-qualification.json) +records versions, scope limits, and current lock/artifact digests. diff --git a/docs/adr/INDEX.md b/docs/adr/INDEX.md index 798d610c43..bbd221b0e4 100644 --- a/docs/adr/INDEX.md +++ b/docs/adr/INDEX.md @@ -1,6 +1,6 @@ # ADR Index -**Next available ADR number: 350** +**Next available ADR number: 361** > Generated by `node scripts/adr-index.mjs` — do not edit by hand. > This file is the canonical allocation counter for new ADR numbers @@ -8,8 +8,8 @@ > historical artifacts and are cited as `ADR-NNN (slug)`. > CI gate: `node scripts/adr-index.mjs --check`. -- ADR files indexed: **376** (329 on the canonical counter, 47 in namespaced families) -- Highest allocated number: **ADR-349** +- ADR files indexed: **388** (341 on the canonical counter, 47 in namespaced families) +- Highest allocated number: **ADR-360** - Frozen duplicate numbers: **27** (spanning 61 files) | Number | Title | File | Last commit | Status | Duplicate | @@ -345,7 +345,16 @@ | ADR-345 | ADR-345: Mincut-Gated Forgetting — Structural Eviction Signal and Eviction Witnesses for Agent Memory | [`ADR-345-mincut-gated-forgetting.md`](./ADR-345-mincut-gated-forgetting.md) | 2026-09-05 | Rejected (for production use as designed). Experimental crate addition | | | ADR-346 | ADR-346: Deterministic, Non-Degenerate Witness Partitions in `ruvector-mincut` | [`ADR-346-deterministic-mincut-witness-partition.md`](./ADR-346-deterministic-mincut-witness-partition.md) | 2026-09-26 | Accepted. Non-breaking bug fix, merged into `ruvector-mincut` directly (no | | | ADR-347 | ADR-347: Ed25519 `WitnessSigner` for the TARL Ledger's Witness Chain | [`ADR-347-witness-signer-tarl-ledger.md`](./ADR-347-witness-signer-tarl-ledger.md) | 2026-09-16 | Accepted. New, opt-in, non-default module | | -| ADR-349 | ADR-349: pi.ruv.io — Three Independent 504 Mechanisms, a UTF-8 Crash, and the Unauthenticated Write Path | [`ADR-349-ruvbrain-504-mechanisms-and-write-path-auth.md`](./ADR-349-ruvbrain-504-mechanisms-and-write-path-auth.md) | 2026-09-26 | Accepted (code landed) | | +| ADR-349 | ADR-349: pi.ruv.io — Three Independent 504 Mechanisms, a UTF-8 Crash, and the Unauthenticated Write Path | [`ADR-349-ruvbrain-504-mechanisms-and-write-path-auth.md`](./ADR-349-ruvbrain-504-mechanisms-and-write-path-auth.md) | 2026-09-26 | Accepted (code landed; item 6 fixed by P5 in a follow-up). Three items are delib | | +| ADR-351 | ADR-351: ruvector edge — Multi-Tenant Rust/wasm Services on Cloudflare Workers + Durable Objects, Behind an Edge Authorization Server Federated to cognitum-one OAuth | [`ADR-351-ruvector-edge-multitenant-services.md`](./ADR-351-ruvector-edge-multitenant-services.md) | 2026-11-10 | **Proposed.** 2026-09-28; reconciled 2026-09-29 with the edge-authorization-serv | | +| ADR-352 | ADR-352: ruvector Python SDK, CLI, and MCP Server (PyO3 core, SOTA scope) | [`ADR-352-ruvector-python-sdk-cli-mcp.md`](./ADR-352-ruvector-python-sdk-cli-mcp.md) | 2026-11-10 | **Proposed, with M1 implemented and verified.** 2026-10-01. Supersedes the scope | | +| ADR-353 | ADR-353: RVF Stream Descriptor (RVSD) — verified streaming delivery (project Ofer) | [`ADR-353-rvf-stream-descriptor.md`](./ADR-353-rvf-stream-descriptor.md) | 2026-11-10 | Proposed (implemented on `feat/ofer-core`; section 10 records where the code ref | | +| ADR-354 | ADR-354: RVF dialect convergence and an effective Strict policy (project Ofer prerequisites) | [`ADR-354-rvf-dialect-convergence-and-strict-policy.md`](./ADR-354-rvf-dialect-convergence-and-strict-policy.md) | 2026-11-10 | Proposed | | +| ADR-355 | ADR-355: ruvector-weaver, a self-improving harness for the ruvnet package fabric | [`ADR-355-ruvector-weaver-ecosystem-fabric.md`](./ADR-355-ruvector-weaver-ecosystem-fabric.md) | 2026-11-10 | Accepted | | +| ADR-356 | ADR-356: Portfolio distribution and SEO standard for the ruvnet npm packages | [`ADR-356-portfolio-distribution-seo.md`](./ADR-356-portfolio-distribution-seo.md) | 2026-11-10 | Accepted | | +| ADR-358 | ADR-358: @ruvector/weight-space, a versioned ruv-fann weight registry indexed by RuVector | [`ADR-358-weight-space-ruv-fann-registry.md`](./ADR-358-weight-space-ruv-fann-registry.md) | 2026-11-10 | Accepted | | +| ADR-359 | ADR-359: Shared e-means clustering for RuVector and ruv-FANN | [`ADR-359-e-means-shared-clustering.md`](./ADR-359-e-means-shared-clustering.md) | | Accepted; local implementation, registry publication pending | | +| ADR-360 | ADR-360: e-means ecosystem submodules, MetaHarness, and Cloudflare Workers | [`ADR-360-e-means-ecosystem-integrations.md`](./ADR-360-e-means-ecosystem-integrations.md) | | Accepted; local integration implemented, publication and deployment pending | | | ADR-CE-001 | ADR-CE-001: Sheaf Laplacian Defines Coherence Witness | [`coherence-engine/ADR-CE-001-sheaf-laplacian-coherence.md`](./coherence-engine/ADR-CE-001-sheaf-laplacian-coherence.md) | 2026-08-20 | Accepted | | | ADR-CE-002 | ADR-CE-002: Incremental Coherence Computation | [`coherence-engine/ADR-CE-002-incremental-computation.md`](./coherence-engine/ADR-CE-002-incremental-computation.md) | 2026-08-20 | Accepted | | | ADR-CE-003 | ADR-CE-003: PostgreSQL + Ruvector Unified Substrate | [`coherence-engine/ADR-CE-003-hybrid-storage.md`](./coherence-engine/ADR-CE-003-hybrid-storage.md) | 2026-08-20 | Accepted | | diff --git a/docs/research/e-means/integrations-qualification.json b/docs/research/e-means/integrations-qualification.json new file mode 100644 index 0000000000..4cfee7cddd --- /dev/null +++ b/docs/research/e-means/integrations-qualification.json @@ -0,0 +1,70 @@ +{ + "observedAt": "2026-11-11T17:36:16.810277+00:00", + "scope": "New e-means modules and explicit ecosystem entrypoints; no registry publication, Cloudflare deployment, or hosted Vectorize mutation.", + "rust": { + "targetedTestsPassed": 50, + "packages": [ + "ruvector-e-means (all features)", + "ruvector-pq-search", + "ruvector-rairs" + ], + "strictClippyAllTargets": "passed", + "crateArchiveVerification": "passed", + "packagedNativeRust181Check": "passed" + }, + "npm": { + "sharedTestsPassed": 44, + "sharedFailures": 0, + "sharedSkips": 0, + "strictTypes": "passed", + "optionalSdkAbsentInstalledConsumer": "passed", + "realDarwinInstalledConsumer": "passed", + "newRuVectorArchiveEntryPoints": [ + "@ruvector/core/clustering.mjs", + "ruvector/clustering.mjs", + "@ruvector/all/clustering.mjs", + "@ruvector/wasm/clustering" + ], + "newRuVectorArchiveEntryPointsStatus": "passed; unrelated legacy root/prepack release builds excluded", + "fannSourceFacadeTestsPassed": 8, + "fannRustAdapterTestsPassed": 3 + }, + "cloudflare": { + "localWorkerd": "passed with static Rust WASM and no nodejs_compat", + "localR2BindingRoundtrip": "passed", + "installedArchiveWorker": "passed", + "vectorize": "binding-contract fixtures only; no hosted mutation", + "schemaIteratorAuthBodyDeadlineAndWorkBoundRegressions": "passed" + }, + "metaharness": { + "package": "@metaharness/darwin", + "version": "0.13.0", + "algorithm": "actual evolveNumeric", + "holdout": "Separate nonoverlapping caller-supplied snapshot; used for selection, not independent generalization evidence", + "sourceApplied": false, + "temporaryArchiveCleanup": "passed" + }, + "dependencyAudit": { + "scope": "Isolated canonical integration-tool package lock", + "counts": { + "info": 0, + "low": 0, + "moderate": 0, + "high": 0, + "critical": 0, + "total": 0 + }, + "miniflare": "4.20260730.0", + "scopedOverrides": { + "sharp": "0.35.5", + "undici": "7.30.1" + }, + "workspaceInstallLimitation": "Existing Darwin-only workspace package prevents a whole-workspace Linux npm install; isolated lock qualification is used." + }, + "sha256": { + "npm/packages/e-means/package-lock.json": "d4b066d2503c58c92927fac0872180e3f1cc5d9f3e2e9665ddd5d2fdf717d25b", + "npm/package-lock.json": "4d80b3ccec4d52dbbfc5191062cc57397b8f6aa0ff24e7211c45cdb06c3fa1b0", + "Cargo.lock": "45f6253a219ae8446ff24b4adc27061e18ea43b9e627f8c55756f8983f81fcf4", + "npm/packages/e-means/wasm/ruvector_e_means_bg.wasm": "2c8f8a21e89f7e809a02d967bb77935284f35115855ed8024fae1a9453f27b5b" + } +} diff --git a/docs/research/e-means/performance-2026-11-11.json b/docs/research/e-means/performance-2026-11-11.json new file mode 100644 index 0000000000..921bcd5632 --- /dev/null +++ b/docs/research/e-means/performance-2026-11-11.json @@ -0,0 +1,406 @@ +{ + "date": "2026-11-11", + "scope": "Local synthetic CPU/WASM measurements against the pre-optimization implementation from this task; not paper GPU results or a production-data guarantee.", + "nativeEnvironment": { + "rustc": "rustc 1.99.1 (58cf8f9c3 2026-10-13)", + "system": "Linux-6.18.57-x86_64-with-glibc2.41", + "cpu": "AMD EPYC 9V74 80-Core Processor,virtualized", + "cpuQuota": "400000 100000", + "memoryLimitBytes": "17179869184", + "rustflags": "", + "profile": { + "optLevel": 3, + "lto": "fat", + "codegenUnits": 1 + }, + "repeats": 5, + "warmup": "one fit and predict per implementation,per scenario", + "ordering": "alternate baseline-first and current-first on each timing repetition", + "heapMeasurement": "allocation/reallocation events and peak additional live requested heap bytes during one fit; excludes preexisting dataset and models; notRSS", + "equivalence": "exact centroid f32 bits,assignments,dimension,mse f64 bits,peakstep f64 bits,batchsize,updates,revivedclusters,predictions", + "timingInstrumentation": "Same global tracking System allocator active in both implementations; timings include its atomic allocation/reallocation accounting.", + "pqFollowup": "pq21.jsonl uses same compiled binary,seed42,21interleavedrepetitions;pairedratios reported separately." + }, + "nativeResults": [ + { + "case": "embedding128", + "samples": 4096, + "clusters": 64, + "dimensions": 128, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 130.051781, + "currentFitMedianMs": 70.574425, + "fitSpeedup": 1.84276, + "baselinePredictMedianMs": 32.324955, + "currentPredictMedianMs": 15.459149, + "predictSpeedup": 2.09099, + "baselineFitSamplesMs": [131.467435, 127.331156, 130.242989, 130.051781, 122.74313], + "currentFitSamplesMs": [70.574425, 79.942167, 70.979476, 66.06521, 65.197374], + "baselinePredictSamplesMs": [37.515317, 33.257138, 32.324955, 32.27568, 31.45154], + "currentPredictSamplesMs": [27.529438, 15.707944, 15.284636, 14.883934, 15.459149], + "baselineAllocations": 65, + "currentAllocations": 18, + "baselinePeakBytes": 296448, + "currentPeakBytes": 297216, + "mse": 0.114103430514, + "revivedClusters": 35, + "digest": "d4c3e4ebdca756ec", + "bitwiseEqual": true + }, + { + "case": "embedding128", + "samples": 4096, + "clusters": 64, + "dimensions": 128, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 127.289993, + "currentFitMedianMs": 68.394125, + "fitSpeedup": 1.86112, + "baselinePredictMedianMs": 32.655452, + "currentPredictMedianMs": 16.103738, + "predictSpeedup": 2.02782, + "baselineFitSamplesMs": [123.94487, 127.289993, 140.52791, 129.614864, 123.52662], + "currentFitSamplesMs": [68.394125, 68.124209, 68.149968, 98.981614, 69.446419], + "baselinePredictSamplesMs": [32.222961, 33.500103, 31.648978, 32.655452, 33.376668], + "currentPredictSamplesMs": [15.650256, 16.10431, 16.103738, 16.809221, 15.972451], + "baselineAllocations": 65, + "currentAllocations": 16, + "baselinePeakBytes": 296448, + "currentPeakBytes": 231168, + "mse": 0.117060715656, + "revivedClusters": 35, + "digest": "8fe5489fdb461bac", + "bitwiseEqual": true + }, + { + "case": "embedding768", + "samples": 2048, + "clusters": 32, + "dimensions": 768, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 203.612263, + "currentFitMedianMs": 177.482473, + "fitSpeedup": 1.14722, + "baselinePredictMedianMs": 52.71644, + "currentPredictMedianMs": 43.645892, + "predictSpeedup": 1.20782, + "baselineFitSamplesMs": [204.457404, 198.054146, 219.330426, 203.612263, 183.144237], + "currentFitSamplesMs": [177.8861, 177.482473, 182.109762, 173.68051, 169.356138], + "baselinePredictSamplesMs": [53.80124, 47.364421, 49.976874, 52.71644, 53.603404], + "currentPredictSamplesMs": [43.804434, 43.151491, 43.949389, 43.645892, 43.350748], + "baselineAllocations": 62, + "currentAllocations": 17, + "baselinePeakBytes": 721664, + "currentPeakBytes": 722176, + "mse": 0.973645490345, + "revivedClusters": 65, + "digest": "37a4d73d3bf84abb", + "bitwiseEqual": true + }, + { + "case": "embedding768", + "samples": 2048, + "clusters": 32, + "dimensions": 768, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 192.918342, + "currentFitMedianMs": 184.687942, + "fitSpeedup": 1.04456, + "baselinePredictMedianMs": 51.914446, + "currentPredictMedianMs": 47.421477, + "predictSpeedup": 1.09475, + "baselineFitSamplesMs": [187.38364, 216.452527, 213.979302, 178.705455, 192.918342], + "currentFitSamplesMs": [177.536174, 184.687942, 184.713402, 191.928362, 180.864216], + "baselinePredictSamplesMs": [71.861448, 57.920893, 51.914446, 51.732527, 47.172022], + "currentPredictSamplesMs": [48.789807, 47.421477, 47.508818, 43.513473, 46.182311], + "baselineAllocations": 62, + "currentAllocations": 15, + "baselinePeakBytes": 721664, + "currentPeakBytes": 525312, + "mse": 0.97650976645, + "revivedClusters": 65, + "digest": "348b350dd42e4f2f", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 49.976593, + "currentFitMedianMs": 51.816974, + "fitSpeedup": 0.96448, + "baselinePredictMedianMs": 14.465709, + "currentPredictMedianMs": 12.975626, + "predictSpeedup": 1.11484, + "baselineFitSamplesMs": [47.05165, 51.369871, 48.388843, 55.925801, 49.976593], + "currentFitSamplesMs": [51.816974, 47.203168, 48.491608, 51.961502, 56.463701], + "baselinePredictSamplesMs": [15.078182, 11.836701, 12.312207, 14.465709, 16.043384], + "currentPredictSamplesMs": [12.975626, 13.535009, 19.086345, 12.357025, 12.182241], + "baselineAllocations": 72, + "currentAllocations": 9, + "baselinePeakBytes": 194560, + "currentPeakBytes": 194560, + "mse": 0.611907061092, + "revivedClusters": 0, + "digest": "d397aea176dfd1db", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 49.940565, + "currentFitMedianMs": 53.106126, + "fitSpeedup": 0.94039, + "baselinePredictMedianMs": 12.497583, + "currentPredictMedianMs": 12.372008, + "predictSpeedup": 1.01015, + "baselineFitSamplesMs": [51.534639, 49.823182, 55.087438, 49.940565, 47.923417], + "currentFitSamplesMs": [53.106126, 63.783741, 48.189242, 54.477886, 52.573087], + "baselinePredictSamplesMs": [12.996287, 11.327925, 11.742278, 12.497583, 12.582941], + "currentPredictSamplesMs": [12.17396, 12.372008, 12.316084, 12.405534, 13.082613], + "baselineAllocations": 72, + "currentAllocations": 7, + "baselinePeakBytes": 194560, + "currentPeakBytes": 176128, + "mse": 0.614058884679, + "revivedClusters": 0, + "digest": "598a7d0a59609a23", + "bitwiseEqual": true + }, + { + "case": "revival", + "samples": 2048, + "clusters": 64, + "dimensions": 32, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 13.349986, + "currentFitMedianMs": 2.525902, + "fitSpeedup": 5.28524, + "baselinePredictMedianMs": 3.117462, + "currentPredictMedianMs": 0.248884, + "predictSpeedup": 12.52576, + "baselineFitSamplesMs": [12.900549, 15.271623, 12.593227, 17.385549, 13.349986], + "currentFitSamplesMs": [2.532672, 2.410038, 2.525902, 2.512823, 3.187197], + "baselinePredictSamplesMs": [3.40796, 3.115189, 2.963251, 4.092791, 3.117462], + "currentPredictSamplesMs": [0.321274, 0.246832, 0.337598, 0.248884, 0.248334], + "baselineAllocations": 80, + "currentAllocations": 19, + "baselinePeakBytes": 91648, + "currentPeakBytes": 92672, + "mse": 0.0, + "revivedClusters": 167, + "digest": "e510f1a7dd7e5fe7", + "bitwiseEqual": true + }, + { + "case": "revival", + "samples": 2048, + "clusters": 64, + "dimensions": 32, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 12.905517, + "currentFitMedianMs": 3.145295, + "fitSpeedup": 4.10312, + "baselinePredictMedianMs": 3.489793, + "currentPredictMedianMs": 0.781276, + "predictSpeedup": 4.46679, + "baselineFitSamplesMs": [15.14003, 12.905517, 13.234311, 12.580436, 12.535741], + "currentFitSamplesMs": [3.350463, 3.380248, 3.126326, 3.145295, 2.962339], + "baselinePredictSamplesMs": [4.709018, 3.083932, 3.489793, 3.906741, 2.897862], + "currentPredictSamplesMs": [0.772182, 0.765983, 0.833865, 0.7971, 0.781276], + "baselineAllocations": 80, + "currentAllocations": 17, + "baselinePeakBytes": 91648, + "currentPeakBytes": 75776, + "mse": 1.8328e-08, + "revivedClusters": 167, + "digest": "60ad9268e8f72725", + "bitwiseEqual": true + } + ], + "nativePqFollowup": [ + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 21, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 51.24788, + "currentFitMedianMs": 52.682849, + "fitSpeedup": 0.97276, + "baselinePredictMedianMs": 13.382461, + "currentPredictMedianMs": 13.632527, + "predictSpeedup": 0.98166, + "baselineFitSamplesMs": [49.448291, 49.816586, 49.312958, 48.863471, 51.08877, 48.398356, 52.749219, 51.153607, 51.147177, 52.587776, 58.093673, 51.758298, 52.255166, 51.439568, 51.496994, 52.095585, 49.410925, 51.24788, 53.677175, 51.450254, 50.59035], + "currentFitSamplesMs": [50.906396, 53.363303, 49.171624, 48.485522, 51.836616, 54.628707, 52.223908, 53.907743, 51.938108, 53.92603, 59.165586, 53.207258, 54.037302, 52.044438, 52.682849, 54.567615, 52.528166, 51.875483, 54.145655, 50.834828, 54.102114], + "baselinePredictSamplesMs": [13.083401, 12.904091, 13.440829, 12.854857, 13.701972, 14.183566, 13.736564, 13.026355, 13.022549, 13.786629, 12.42468, 13.382461, 13.45503, 13.917757, 13.202941, 14.74445, 12.927286, 13.384143, 12.49818, 12.775959, 16.755818], + "currentPredictSamplesMs": [14.81667, 13.117412, 13.440328, 12.302315, 13.213417, 14.582297, 13.978999, 15.233878, 13.649152, 13.632527, 13.236692, 14.473603, 12.616579, 13.798918, 13.571535, 14.082564, 13.86665, 13.012905, 11.896034, 13.598897, 14.586924], + "baselineAllocations": 72, + "currentAllocations": 9, + "baselinePeakBytes": 194560, + "currentPeakBytes": 194560, + "mse": 0.611907061092, + "revivedClusters": 0, + "digest": "d397aea176dfd1db", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 21, + "finalization": "ema", + "baselineFitMedianMs": 50.276679, + "currentFitMedianMs": 50.832466, + "fitSpeedup": 0.98907, + "baselinePredictMedianMs": 12.737901, + "currentPredictMedianMs": 13.050141, + "predictSpeedup": 0.97607, + "baselineFitSamplesMs": [47.921643, 48.137958, 48.476228, 50.120504, 49.945341, 48.566244, 49.538017, 48.266904, 46.495408, 64.897544, 73.224287, 56.418893, 50.48981, 52.052792, 50.767058, 51.888285, 50.276679, 54.769221, 59.892563, 49.93207, 94.624515], + "currentFitSamplesMs": [49.980713, 48.920456, 50.832466, 48.000654, 48.827698, 49.990659, 46.3299, 52.639305, 50.077289, 61.600693, 57.869147, 65.716427, 51.168893, 50.068806, 50.157379, 50.630702, 51.047169, 53.231833, 55.708239, 51.757348, 109.263924], + "baselinePredictSamplesMs": [12.159581, 12.584019, 12.620094, 12.799063, 12.296727, 11.405556, 12.620986, 13.689182, 12.929981, 16.264949, 14.558451, 12.833325, 13.327659, 12.405751, 12.988378, 13.218344, 12.535867, 12.737901, 11.942053, 30.120994, 12.542518], + "currentPredictSamplesMs": [12.864371, 13.261529, 13.898338, 13.794552, 11.400368, 13.422412, 12.868548, 13.469041, 13.050141, 16.407775, 16.744091, 12.667987, 12.244189, 12.784041, 12.993115, 13.011372, 11.954952, 13.802284, 13.442983, 17.258065, 11.744716], + "baselineAllocations": 72, + "currentAllocations": 7, + "baselinePeakBytes": 194560, + "currentPeakBytes": 176128, + "mse": 0.614058884679, + "revivedClusters": 0, + "digest": "598a7d0a59609a23", + "bitwiseEqual": true + } + ], + "npm": { + "runtime": { + "node": "v24.22.1", + "platform": "linux", + "arch": "x64", + "cpu": "AMD EPYC 9V74 80-Core Processor", + "logicalCpus": 5 + }, + "repeats": 7, + "warmupsPerVariant": 2, + "measurement": "median wall-clock milliseconds, fully materialized results; explicit GC outside timing", + "sameKernelTransportMeasurement": "full fit plus output materialization using one optimized WASM kernel; difference includes JSON serialization/parsing and array conversion, not a conversion-only timer", + "checksum": 42347816.01348107, + "cases": [ + { + "name": "large-assignment-result", + "samples": 1000000, + "dimensions": 1, + "clusters": 1, + "epochs": 1, + "batchSize": 4096, + "fit": { + "optimizedMs": 61.56721399999992, + "baselineMs": 84.090687, + "speedup": 1.3658355078402624 + }, + "predict": { + "optimizedMs": 10.453125, + "baselineMs": 15.906072000000222, + "speedup": 1.5216571121076445 + }, + "sameKernelTransport": { + "jsonMs": 75.97168599999986, + "typedMs": 58.40519399999994, + "speedup": 1.3007693459591958 + }, + "baselineParity": { + "labelDifferences": 0, + "centroidMaxAbsDifference": 0, + "mseAbsoluteDifference": 0 + } + }, + { + "name": "embedding-codebook", + "samples": 8192, + "dimensions": 64, + "clusters": 16, + "epochs": 3, + "batchSize": 256, + "fit": { + "optimizedMs": 15.001260999999886, + "baselineMs": 36.18889299999955, + "speedup": 2.4123900650751846 + }, + "predict": { + "optimizedMs": 5.059164999999666, + "baselineMs": 13.240130000000136, + "speedup": 2.6170583485616716 + }, + "sameKernelTransport": { + "jsonMs": 12.692776000000777, + "typedMs": 12.346003999999994, + "speedup": 1.0280877926170107 + }, + "baselineParity": { + "labelDifferences": 0, + "centroidMaxAbsDifference": 0, + "mseAbsoluteDifference": 0 + } + } + ] + }, + "sourceAndArtifactSha256": { + "baselineRustSource": { + "config.rs": "b9ad83acdf082778bc9841b18833122b0f353586b6a2cae5e2047f87d4dff6d6", + "lib.rs": "627e108c9d0b2644f4cc75f5f09805c1f92bde683f56b50a6f474074a2ccb517", + "trainer.rs": "f67fc903d4995678716dbc450cba820f4f4e4d73c50686c7267c2de01d22b967", + "wasm.rs": "270d30ca46b32602a7549d4c37b5d0740275800babdc24f62b8df358008f6568" + }, + "optimizedRustSource": { + "config.rs": "b9ad83acdf082778bc9841b18833122b0f353586b6a2cae5e2047f87d4dff6d6", + "distance.rs": "b2bb4252b7c10a99d55d07a33c46f196743d8fbe071694340db4be76c5f22e05", + "lib.rs": "084ce5655335019fc6a11b0226f0ccfed6b48a55cde674686453dc8231d59562", + "trainer.rs": "1bfa1299152cc9dd188975e6e068752aac83d5cdd3bd199672472ad68d5b1af2", + "wasm.rs": "7d4fbe5c800e083446ecf5f767bbe9eb6ed603b0330ab9be7086d009d930ad00" + }, + "baselineWasm": "dd68d9bf52a7422f14f56819f6b49c55118fc40438a0282ab64cde6e066c348b", + "optimizedWasm": "2c8f8a21e89f7e809a02d967bb77935284f35115855ed8024fae1a9453f27b5b" + }, + "verification": { + "native": "All model fields and predictions match baseline bit for bit in all eight measured cases.", + "npm": "Baseline centroid/label/MSE differences are zero in both measured cases; typed and JSON transports of the optimized kernel compare equal.", + "memory": "Native peaks are additional live requested heap bytes, excluding the dataset and preexisting models; not process RSS. LastEpochMean peaks can rise slightly due to retained scratch capacity; EMA skips last-epoch buffers.", + "pq8": "21-repeat follow-up fit median ratios baseline/current are 0.97276 (lastEpochMean) and 0.98907 (ema). No PQ speedup is claimed.", + "browser": "Chromium startup failed even for about:blank in the earlier baseline; browser qualification remains pending." + }, + "reproduceCurrentNative": "cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both", + "reproduceNpm": "npm run benchmark -- --repeats 7 (in npm/packages/e-means); --baseline compares a supplied prior artifact." +} diff --git a/npm/package-lock.json b/npm/package-lock.json index 87b5cd8571..d70995b342 100644 --- a/npm/package-lock.json +++ b/npm/package-lock.json @@ -3581,6 +3581,10 @@ "node": ">= 18" } }, + "node_modules/@ruvector/e-means": { + "resolved": "packages/e-means", + "link": true + }, "node_modules/@ruvector/economy-wasm": { "version": "0.1.29", "resolved": "https://registry.npmjs.org/@ruvector/economy-wasm/-/economy-wasm-0.1.29.tgz", @@ -19007,7 +19011,8 @@ "@ruvector/sona": "^0.1.9", "@ruvector/tiny-dancer": "^0.1.23", "ruvector": "^0.3.7", - "rvlite": "^0.2.7" + "rvlite": "^0.2.7", + "@ruvector/e-means": "0.1.0" }, "engines": { "node": ">=20.0.0" @@ -19465,7 +19470,8 @@ "ruvector-core-darwin-x64": "0.1.34", "ruvector-core-linux-arm64-gnu": "0.1.34", "ruvector-core-linux-x64-gnu": "0.1.34", - "ruvector-core-win32-x64-msvc": "0.1.34" + "ruvector-core-win32-x64-msvc": "0.1.34", + "@ruvector/e-means": "0.1.0" } }, "packages/diskann": { @@ -19486,6 +19492,28 @@ "@ruvector/diskann-win32-x64-msvc": "0.1.3" } }, + "packages/e-means": { + "name": "@ruvector/e-means", + "version": "0.1.0", + "license": "MIT", + "devDependencies": { + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + } + }, "packages/emergent-time": { "name": "@ruvector/emergent-time", "version": "0.1.3", @@ -21176,7 +21204,8 @@ "@ruvector/sona": "^0.1.11", "chalk": "^4.1.2", "commander": "^11.1.0", - "ora": "^5.4.1" + "ora": "^5.4.1", + "@ruvector/e-means": "0.1.0" }, "bin": { "ruvector": "bin/cli.js" @@ -22410,6 +22439,1510 @@ "engines": { "node": ">=18.0.0" } + }, + "packages/e-means/node_modules/@babel/helper-string-parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.13.tgz", + "integrity": "sha512-fWegr+WsEsiMVW4KUNdIIzzMTZSzNiqhy0//6+2MRi2d5NFNsL/AYwBQW8eBnRbTBVRnDVzjaJEUqKaCWjMMdQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@babel/helper-validator-identifier": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@babel/parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.13.tgz", + "integrity": "sha512-fJM50YYjlTiBhgdkGmC1tBpv+FMAyo4annf2X6Aks+0yRlaiVkYW/3f07xAfVVkYIoZ9fFZp+mEThUFnuybhkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.11" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "packages/e-means/node_modules/@babel/types": { + "version": "7.29.11", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.11.tgz", + "integrity": "sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.29.11", + "@babel/helper-validator-identifier": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-darwin-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260730.1.tgz", + "integrity": "sha512-+MBHmPaiTe2KajryW0T24rZvWFxb41hD3d8anNzQqHzft6vSEb18+sp0znSwxgij7ApPhSM1+vhkNg4f3YMguA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-darwin-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260730.1.tgz", + "integrity": "sha512-SBHKntPkKvNPgaCrTe99xC1CAl8ygJDzlYfK0LbuJ1muKadIw35WnhO0wu894fKBtllsVQdNzDLee+cm0ppLSQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-linux-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260730.1.tgz", + "integrity": "sha512-ouyPOSMbiKPeSwUJUvxtMcxGAXs2J4aPE4T5ABIYX5ClcQx5j5bbHTmnqOQEY8sAuLTPjH7dY+iB6UI5ISlwwA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-linux-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260730.1.tgz", + "integrity": "sha512-YQ+Mi78U3TPdgBPtwq+Sm6rJU+Ihl2y0pjYtuuKkdmUbYzL7oLR6Xqq9wljhasnuCFICssDJaqhMep5WizYoEQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-windows-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260730.1.tgz", + "integrity": "sha512-27fAN+vUECW1oYVc1KOcHYpkL8COM2Uxtxql7TL595kxbjoqS5yckw7NLz7bTf2pALFCZWjqXDjZGJ/xbG4ZKQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "packages/e-means/node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "packages/e-means/node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@img/colour": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", + "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@img/sharp-darwin-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz", + "integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-darwin-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz", + "integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-freebsd-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz", + "integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==", + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-darwin-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz", + "integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-darwin-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz", + "integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-arm": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz", + "integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz", + "integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-ppc64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz", + "integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-riscv64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz", + "integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-s390x": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz", + "integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz", + "integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linuxmusl-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz", + "integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linuxmusl-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz", + "integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-arm": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz", + "integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz", + "integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-ppc64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz", + "integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-ppc64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-riscv64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz", + "integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-riscv64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-s390x": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz", + "integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-s390x": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz", + "integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linuxmusl-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz", + "integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linuxmusl-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz", + "integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz", + "integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==", + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.11.3" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-webcontainers-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz", + "integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz", + "integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-ia32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz", + "integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz", + "integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "packages/e-means/node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "packages/e-means/node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "packages/e-means/node_modules/@metaharness/darwin": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/@metaharness/darwin/-/darwin-0.13.0.tgz", + "integrity": "sha512-L3SrQii70erHVDmo1qx0875IRpVujk86zAO7sxtSVChWCgAjabEmmYRYt72D1VekfUCbSWCgZKIktqUxVAKCFA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.29.13" + }, + "bin": { + "metaharness-darwin": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "packages/e-means/node_modules/@poppinss/colors": { + "version": "4.1.6", + "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz", + "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==", + "dev": true, + "license": "MIT", + "dependencies": { + "kleur": "^4.1.5" + } + }, + "packages/e-means/node_modules/@poppinss/dumper": { + "version": "0.6.5", + "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz", + "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@sindresorhus/is": "^7.0.2", + "supports-color": "^10.0.0" + } + }, + "packages/e-means/node_modules/@poppinss/exception": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz", + "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==", + "dev": true, + "license": "MIT" + }, + "packages/e-means/node_modules/@sindresorhus/is": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz", + "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "packages/e-means/node_modules/@speed-highlight/core": { + "version": "1.2.24", + "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.24.tgz", + "integrity": "sha512-qeW2e1l78afw8VhRPfPQ1Gjj+KU5XFQ/OFV5ti6eTa9bruO7mJyZtA4vw0ofqmA3tKCkROE9xLk3VZoeRc98nw==", + "dev": true, + "license": "CC0-1.0" + }, + "packages/e-means/node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "packages/e-means/node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "packages/e-means/node_modules/error-stack-parser-es": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz", + "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "packages/e-means/node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "packages/e-means/node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "packages/e-means/node_modules/miniflare": { + "version": "4.20260730.0", + "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260730.0.tgz", + "integrity": "sha512-1Z9SB9r/o//80UA02Re3QhtcecSHAyAjf5EcKBfQVlQrCg7Miy79hl2PvtkwFLIaJ5rcrOPdDcRr577okwZPsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "0.8.1", + "sharp": "0.35.2", + "undici": "7.28.0", + "workerd": "1.20260730.1", + "ws": "8.21.0", + "youch": "4.1.0-beta.10" + }, + "bin": { + "miniflare": "bootstrap.js" + }, + "engines": { + "node": ">=22.0.0" + } + }, + "packages/e-means/node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "packages/e-means/node_modules/sharp": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz", + "integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@img/colour": "^1.1.0", + "detect-libc": "^2.1.2", + "semver": "^7.8.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-darwin-arm64": "0.35.5", + "@img/sharp-darwin-x64": "0.35.5", + "@img/sharp-freebsd-wasm32": "0.35.5", + "@img/sharp-libvips-darwin-arm64": "1.3.4", + "@img/sharp-libvips-darwin-x64": "1.3.4", + "@img/sharp-libvips-linux-arm": "1.3.4", + "@img/sharp-libvips-linux-arm64": "1.3.4", + "@img/sharp-libvips-linux-ppc64": "1.3.4", + "@img/sharp-libvips-linux-riscv64": "1.3.4", + "@img/sharp-libvips-linux-s390x": "1.3.4", + "@img/sharp-libvips-linux-x64": "1.3.4", + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4", + "@img/sharp-libvips-linuxmusl-x64": "1.3.4", + "@img/sharp-linux-arm": "0.35.5", + "@img/sharp-linux-arm64": "0.35.5", + "@img/sharp-linux-ppc64": "0.35.5", + "@img/sharp-linux-riscv64": "0.35.5", + "@img/sharp-linux-s390x": "0.35.5", + "@img/sharp-linux-x64": "0.35.5", + "@img/sharp-linuxmusl-arm64": "0.35.5", + "@img/sharp-linuxmusl-x64": "0.35.5", + "@img/sharp-webcontainers-wasm32": "0.35.5", + "@img/sharp-win32-arm64": "0.35.5", + "@img/sharp-win32-ia32": "0.35.5", + "@img/sharp-win32-x64": "0.35.5" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "packages/e-means/node_modules/supports-color": { + "version": "10.2.2", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz", + "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "packages/e-means/node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "packages/e-means/node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "packages/e-means/node_modules/undici": { + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.18.1" + } + }, + "packages/e-means/node_modules/workerd": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260730.1.tgz", + "integrity": "sha512-zmfNIjwYSWFY5chGBOjWtH3xAE7p97FTC6vR4Ep98290ho6AeAR/NVcBD274YCLEUYzqm8yxdtZlxMybU8a3jA==", + "dev": true, + "hasInstallScript": true, + "license": "Apache-2.0", + "bin": { + "workerd": "bin/workerd" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "@cloudflare/workerd-darwin-64": "1.20260730.1", + "@cloudflare/workerd-darwin-arm64": "1.20260730.1", + "@cloudflare/workerd-linux-64": "1.20260730.1", + "@cloudflare/workerd-linux-arm64": "1.20260730.1", + "@cloudflare/workerd-windows-64": "1.20260730.1" + } + }, + "packages/e-means/node_modules/ws": { + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "packages/e-means/node_modules/youch": { + "version": "4.1.0-beta.10", + "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz", + "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@poppinss/dumper": "^0.6.4", + "@speed-highlight/core": "^1.2.7", + "cookie": "^1.0.2", + "youch-core": "^0.3.3" + } + }, + "packages/e-means/node_modules/youch-core": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz", + "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/exception": "^1.2.2", + "error-stack-parser-es": "^1.0.5" + } } } } diff --git a/npm/package.json b/npm/package.json index 2e1505e593..274ecf56c5 100644 --- a/npm/package.json +++ b/npm/package.json @@ -30,6 +30,10 @@ "npm": ">=9.0.0" }, "overrides": { + "miniflare": { + "sharp": "0.35.5", + "undici": "7.30.1" + }, "node-forge": ">=1.4.0", "flatted": ">=3.3.3", "picomatch": ">=4.0.3", diff --git a/npm/packages/all/clustering.d.mts b/npm/packages/all/clustering.d.mts new file mode 100644 index 0000000000..2ca0a76f10 --- /dev/null +++ b/npm/packages/all/clustering.d.mts @@ -0,0 +1,2 @@ +export { init, fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; diff --git a/npm/packages/all/clustering.mjs b/npm/packages/all/clustering.mjs new file mode 100644 index 0000000000..f1f8835355 --- /dev/null +++ b/npm/packages/all/clustering.mjs @@ -0,0 +1,2 @@ +/** Shared Rust/WASM clustering; initialize explicitly before numerical calls. */ +export { init, fit, predict } from '@ruvector/e-means'; diff --git a/npm/packages/all/clustering/cloudflare.d.mts b/npm/packages/all/clustering/cloudflare.d.mts new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/all/clustering/cloudflare.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/all/clustering/cloudflare.mjs b/npm/packages/all/clustering/cloudflare.mjs new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/all/clustering/cloudflare.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/all/clustering/ivf.d.mts b/npm/packages/all/clustering/ivf.d.mts new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/all/clustering/ivf.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/all/clustering/ivf.mjs b/npm/packages/all/clustering/ivf.mjs new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/all/clustering/ivf.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/all/clustering/metaharness.d.mts b/npm/packages/all/clustering/metaharness.d.mts new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/all/clustering/metaharness.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/all/clustering/metaharness.mjs b/npm/packages/all/clustering/metaharness.mjs new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/all/clustering/metaharness.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/all/clustering/quantization.d.mts b/npm/packages/all/clustering/quantization.d.mts new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/all/clustering/quantization.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/all/clustering/quantization.mjs b/npm/packages/all/clustering/quantization.mjs new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/all/clustering/quantization.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/all/package.json b/npm/packages/all/package.json index 895268d823..95f7ea786c 100644 --- a/npm/packages/all/package.json +++ b/npm/packages/all/package.json @@ -21,12 +21,16 @@ "files": [ "index.js", "index.d.ts", - "README.md" + "README.md", + "clustering.mjs", + "clustering.d.mts", + "clustering/" ], "scripts": { "test": "node --test test/all.test.js" }, "dependencies": { + "@ruvector/e-means": "0.1.0", "ruvector": "^0.3.7", "@ruvector/rvf": "^0.4.1", "@ruvector/sona": "^0.1.9", diff --git a/npm/packages/core/clustering.d.mts b/npm/packages/core/clustering.d.mts new file mode 100644 index 0000000000..2ca0a76f10 --- /dev/null +++ b/npm/packages/core/clustering.d.mts @@ -0,0 +1,2 @@ +export { init, fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; diff --git a/npm/packages/core/clustering.mjs b/npm/packages/core/clustering.mjs new file mode 100644 index 0000000000..f1f8835355 --- /dev/null +++ b/npm/packages/core/clustering.mjs @@ -0,0 +1,2 @@ +/** Shared Rust/WASM clustering; initialize explicitly before numerical calls. */ +export { init, fit, predict } from '@ruvector/e-means'; diff --git a/npm/packages/core/clustering/cloudflare.d.mts b/npm/packages/core/clustering/cloudflare.d.mts new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/core/clustering/cloudflare.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/core/clustering/cloudflare.mjs b/npm/packages/core/clustering/cloudflare.mjs new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/core/clustering/cloudflare.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/core/clustering/ivf.d.mts b/npm/packages/core/clustering/ivf.d.mts new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/core/clustering/ivf.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/core/clustering/ivf.mjs b/npm/packages/core/clustering/ivf.mjs new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/core/clustering/ivf.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/core/clustering/metaharness.d.mts b/npm/packages/core/clustering/metaharness.d.mts new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/core/clustering/metaharness.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/core/clustering/metaharness.mjs b/npm/packages/core/clustering/metaharness.mjs new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/core/clustering/metaharness.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/core/clustering/quantization.d.mts b/npm/packages/core/clustering/quantization.d.mts new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/core/clustering/quantization.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/core/clustering/quantization.mjs b/npm/packages/core/clustering/quantization.mjs new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/core/clustering/quantization.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/core/package.json b/npm/packages/core/package.json index e42719839b..0b7a6699e9 100644 --- a/npm/packages/core/package.json +++ b/npm/packages/core/package.json @@ -21,7 +21,10 @@ "files": [ "index.js", "index.d.ts", - "README.md" + "README.md", + "clustering.mjs", + "clustering.d.mts", + "clustering/" ], "scripts": { "build:napi": "napi build --platform --release --cargo-cwd ../../../crates/ruvector-node", @@ -32,6 +35,7 @@ "@napi-rs/cli": "^2.18.0" }, "optionalDependencies": { + "@ruvector/e-means": "0.1.0", "ruvector-core-linux-x64-gnu": "0.1.35", "ruvector-core-linux-arm64-gnu": "0.1.35", "ruvector-core-darwin-x64": "0.1.35", diff --git a/npm/packages/e-means/.gitignore b/npm/packages/e-means/.gitignore new file mode 100644 index 0000000000..7f84121734 --- /dev/null +++ b/npm/packages/e-means/.gitignore @@ -0,0 +1,2 @@ +# Keep the isolated integration-test dependency graph reproducible. +!package-lock.json diff --git a/npm/packages/e-means/LICENSE b/npm/packages/e-means/LICENSE new file mode 100644 index 0000000000..2dd524ac38 --- /dev/null +++ b/npm/packages/e-means/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rUv + +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. diff --git a/npm/packages/e-means/README.md b/npm/packages/e-means/README.md new file mode 100644 index 0000000000..592b5c07bc --- /dev/null +++ b/npm/packages/e-means/README.md @@ -0,0 +1,98 @@ +# @ruvector/e-means + +Portable WebAssembly bindings for the shared `ruvector-e-means` Rust crate, based on [e-means (arXiv:2611.09501v1)](https://arxiv.org/abs/2611.09501v1). Uses EMA counts and sums, cosine annealing, dead-cluster splitting and last-epoch mean finalization. + +```js +import { init, fit, predict } from '@ruvector/e-means'; + +await init(); +const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); +const model = fit(data, 2, { clusters: 2, epochs: 3, seed: 42 }); +const labels = predict(data, 2, model.centroids); +``` + +Pass flat row-major `Float32Array` data and finite values. `fit` and `predict` are synchronous after `init`; input arrays are unchanged. Cluster labels break distance ties at the lowest centroid index. `mse` is mean squared Euclidean distance per vector. Output assignments are recomputed against the final codebook. + +The runtime transfers result vectors directly as typed arrays. Returned arrays belong to the caller and remain valid across later fits and WebAssembly memory growth. The temporary Rust result handle is released before `fit` returns; the small options object alone uses JSON transport. + +`batchSize` and `peakStep` can override the paper's automatic settings. `finalization: 'ema'` returns the training EMA instead of the default `'lastEpochMean'`. The empirical scaling laws target large embedding datasets; evaluate overrides on tiny or low-dimensional data. CPU/WASM throughput is not the paper's measured GPU throughput. GPU kernels, approximate assignment and the optional slow-EMA finalizer are outside this initial implementation. + +Node reads the bundled WASM from disk. In browsers, serve the `.wasm` artifact beside its generated JavaScript module, or call `init(bytes)` / `init(compiledModule)` to supply it explicitly. No native compilation, network request, or model download occurs during installation or Node initialization. Browser initialization fetches the bundled `.wasm` URL by default. + +From a source checkout: install the `wasm32-unknown-unknown` Rust target and `wasm-bindgen-cli` version `0.2.125`, then run `npm run build`, `npm test` and `npm run test:consumer` in this package. `npm pack` verifies the built runtime before creating an archive. The archive contains the runtime and needs neither Rust nor the source repository. + +`npm run typecheck` validates the declarations. `npm run test:browser` runs the same numerical oracle in headless Chromium against the default browser loader; set `E_MEANS_CHROMIUM` when Chromium is not on `PATH`. + +`npm run benchmark -- --baseline /path/to/previous/package --repeats 7` measures median fit and prediction time on one million scalar rows and an embedding codebook workload. It also compares JSON and typed output on the same current Rust kernel. The baseline argument is optional; retain the previous package's module and WASM together. Run benchmarks without other compute workloads; results describe the current machine and these fixtures. + +RuVector exposes the same API through `ruvector/clustering.mjs`; ruv-FANN exposes `ruv-fann/clustering`. Both depend on this package. + +The package also ships explicit integration subpaths: + +| Import | Use | +|---|---| +| `@ruvector/e-means/quantization` | Train PQ subspace codebooks, encode byte codes, decode vectors, and validate JSON codebooks | +| `@ruvector/e-means/ivf` | Train coarse clusters and construct stable posting lists | +| `@ruvector/e-means/metaharness` | Measure held-out clustering quality and run bounded numeric evolution with actual Darwin 0.13.0 | +| `@ruvector/e-means/cloudflare` | Create an authenticated Worker and explicitly persist/export centroid codebooks through R2/Vectorize bindings | +| `@ruvector/e-means/runtime` | Initialize from explicit bytes or a precompiled WASM module without importing Node loaders | +| `@ruvector/e-means/cloudflare/build` | Build the shipped Worker example locally; requires development tooling, and never deploys | +| `@ruvector/e-means/wasm` | Static WASM module import for Wrangler | + +```js +import { init } from '@ruvector/e-means'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer } + from '@ruvector/e-means/quantization'; +import { partition, postingList } from '@ruvector/e-means/ivf'; + +await init(); +const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); +const options = { clusters: 2, epochs: 3, seed: 42 }; +const book = trainProductQuantizer(data, 2, 2, options); +const codes = encodeProductQuantizer(book, data); +const reconstructed = decodeProductQuantizer(book, codes); +const inverted = partition(data, 2, options); +const firstPosting = postingList(inverted, 0); +``` + +MetaHarness tuning requires the optional peer `@metaharness/darwin@0.13.0`. +`createClusteringEvaluator` uses snapshotted, nonoverlapping training/holdout +arrays and explicit evaluation/work/deadline budgets. `tuneClustering` calls the +real numeric SDK, verifies observed records, and returns a recommendation with +`sourceApplied: false`. Selection uses the holdout; another test split is needed +for generalization claims. See the shipped `examples/metaharness.mjs`. + +For a Worker, statically import the module and supply the deployment's secret: + +```js +import wasmModule from '@ruvector/e-means/wasm'; +import { createClusteringWorker } from '@ruvector/e-means/cloudflare'; + +export default { + fetch(request, env) { + return createClusteringWorker({ + wasmModule, bearerToken: env.E_MEANS_BEARER_TOKEN, + }).fetch(request); + }, +}; +``` + +`/fit` and `/predict` require authentication by default and enforce body, shape, +stream-read and work bounds. R2 helpers persist only centroid codebooks. +Vectorize exports use explicit caller-owned bindings; acknowledgements are +asynchronous and failures can leave earlier batches applied. Use versioned +prefixes/namespaces because upserts do not delete stale IDs. PQ records have a +different layout and are rejected by these single-codebook helpers. + +The shipped `examples/cloudflare` contains a static-WASM builder and Wrangler +configuration. `npm run build:cloudflare` only writes local artifacts. Qualify +with `npm ci --ignore-scripts --workspaces=false`, `npm test`, +`npm run typecheck`, `npm run test:consumer`, and `npm run test:ecosystem`. +Local workerd/R2 tests use development dependencies; Vectorize is covered by +binding fixtures. No hosted deployment is implied. + +These integrations are also exposed by `@ruvector/core`, `@ruvector/all`, the +current `@ruvector/wasm` source, `ruvector`, `ruv-fann`, and +`@ruv-fann/integrations` through their clustering subpaths. See +[ADR-360](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-360-e-means-ecosystem-integrations.md) +for the exact paths, release order, and validation scope. diff --git a/npm/packages/e-means/e-means.d.ts b/npm/packages/e-means/e-means.d.ts new file mode 100644 index 0000000000..6230ed769a --- /dev/null +++ b/npm/packages/e-means/e-means.d.ts @@ -0,0 +1,33 @@ +export interface EMeansOptions { + clusters: number; + /** Positive integer, default 3. */ + epochs?: number; + /** Positive integer; defaults to the paper's batch scaling law, capped at the row count. */ + batchSize?: number; + /** Peak EMA step in (0, 1]; defaults to the paper's step scaling law. */ + peakStep?: number; + /** Non-negative safe integer; default 42. */ + seed?: number; + finalization?: 'lastEpochMean' | 'ema'; +} + +export interface EMeansModel { + /** Flat row-major clusters × dimensions codebook. */ + centroids: Float32Array; + /** Nearest final centroid for every input row. */ + assignments: Uint32Array; + dimensions: number; + /** Mean squared Euclidean distance per vector, not per coordinate. */ + mse: number; + batchSize: number; + peakStep: number; + updates: number; + revivedClusters: number; +} + +/** Load the bundled WebAssembly runtime. In browsers the default .wasm URL must be served. */ +export function init(input?: BufferSource | WebAssembly.Module): Promise; +/** Requires init(). Inputs are not modified. */ +export function fit(data: Float32Array, dimensions: number, options: EMeansOptions): EMeansModel; +/** Requires init(). An empty input returns an empty assignment array. */ +export function predict(data: Float32Array, dimensions: number, centroids: Float32Array): Uint32Array; diff --git a/npm/packages/e-means/e-means.mjs b/npm/packages/e-means/e-means.mjs new file mode 100644 index 0000000000..9d74da55ff --- /dev/null +++ b/npm/packages/e-means/e-means.mjs @@ -0,0 +1,29 @@ +import { init as initRuntime } from './runtime.mjs'; +export { fit, predict } from './runtime.mjs'; + +let initialization; + +/** Load the bundled Rust runtime once; pass bytes or a compiled module to override it. */ +export async function init(input) { + if (!initialization) { + initialization = (async () => { + let source = input; + if (source === undefined) { + const url = new URL('./wasm/ruvector_e_means_bg.wasm', import.meta.url); + if (url.protocol === 'file:' && typeof process !== 'undefined' && process.versions?.node) { + const { readFile } = await import('node:fs/promises'); + source = await readFile(url); + } else { + source = url; + } + } + await initRuntime(source); + })().catch((error) => { + initialization = undefined; + const message = typeof error?.message === 'string' ? error.message : String(error); + if (message.startsWith('Could not initialize @ruvector/e-means:')) throw error; + throw new Error(`Could not initialize @ruvector/e-means: ${message}`, { cause: error }); + }); + } + await initialization; +} diff --git a/npm/packages/e-means/examples/cloudflare/build.d.ts b/npm/packages/e-means/examples/cloudflare/build.d.ts new file mode 100644 index 0000000000..eac7465c9d --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/build.d.ts @@ -0,0 +1,5 @@ +/** Node-only build tooling; requires caller-installed esbuild. Never deploys. */ +export function buildWorker(outDirectory: string, entryPoint?: string): Promise<{ + script: string; + wasm: string; +}>; diff --git a/npm/packages/e-means/examples/cloudflare/build.mjs b/npm/packages/e-means/examples/cloudflare/build.mjs new file mode 100644 index 0000000000..987052ff2b --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/build.mjs @@ -0,0 +1,23 @@ +import { build } from 'esbuild'; +import { mkdir, copyFile } from 'node:fs/promises'; +import { join, resolve } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; + +/** Build a static-WASM Worker locally; this function never deploys anything. */ +export async function buildWorker(outDirectory, entryPoint = fileURLToPath(new URL('./worker.mjs', import.meta.url))) { + if (typeof outDirectory !== 'string' || outDirectory.length === 0) throw new TypeError('outDirectory is required'); + const output = resolve(outDirectory), wasm = join(output, 'e-means.wasm'); + await mkdir(output, { recursive: true }); + await copyFile(fileURLToPath(import.meta.resolve('@ruvector/e-means/wasm')), wasm); + const script = join(output, 'worker.mjs'); + await build({ entryPoints: [entryPoint], outfile: script, bundle: true, format: 'esm', platform: 'browser', + target: 'es2022', legalComments: 'none', plugins: [{ name: 'e-means-static-wasm', setup(builder) { + builder.onResolve({ filter: /^@ruvector\/e-means\/wasm$/ }, () => ({ path: './e-means.wasm', external: true })); + } }] }); + return { script, wasm }; +} + +if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { + const artifact = await buildWorker(process.argv[2] ?? fileURLToPath(new URL('./dist/', import.meta.url))); + console.log(JSON.stringify(artifact)); +} diff --git a/npm/packages/e-means/examples/cloudflare/worker.mjs b/npm/packages/e-means/examples/cloudflare/worker.mjs new file mode 100644 index 0000000000..be36fb9ebd --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/worker.mjs @@ -0,0 +1,9 @@ +import wasmModule from '@ruvector/e-means/wasm'; +import { createClusteringWorker } from '@ruvector/e-means/cloudflare'; + +export default { + fetch(request, env) { + // The secret is supplied by the deployment's binding configuration. + return createClusteringWorker({ wasmModule, bearerToken: env.E_MEANS_BEARER_TOKEN }).fetch(request); + }, +}; diff --git a/npm/packages/e-means/examples/cloudflare/wrangler.jsonc b/npm/packages/e-means/examples/cloudflare/wrangler.jsonc new file mode 100644 index 0000000000..19ed83de99 --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/wrangler.jsonc @@ -0,0 +1,9 @@ +{ + "name": "ruvector-e-means", + "main": "dist/worker.mjs", + "compatibility_date": "2026-07-30", + "no_bundle": true, + "find_additional_modules": true, + "rules": [{ "type": "CompiledWasm", "globs": ["**/*.wasm"], "fallthrough": true }], + "observability": { "enabled": true } +} diff --git a/npm/packages/e-means/examples/metaharness.mjs b/npm/packages/e-means/examples/metaharness.mjs new file mode 100644 index 0000000000..a2114ea7e5 --- /dev/null +++ b/npm/packages/e-means/examples/metaharness.mjs @@ -0,0 +1,16 @@ +import { tuneClustering } from '@ruvector/e-means/metaharness'; + +const result = await tuneClustering({ + training: new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]), + holdout: new Float32Array([0, 1, 10, 11]), + dimensions: 2, + baseline: { clusters: 2, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { peakStep: { min: 0.1, max: 1, type: 'float', scale: 'log' } }, + budget: { maxEvaluations: 3, maxDistanceCoordinates: 100_000, timeoutMs: 30_000 }, + generations: 1, + childrenPerGeneration: 2, + mutationSeed: 7, +}); +console.log(JSON.stringify({ baselineHoldoutMse: result.baseline.score.raw.holdoutMse, + winnerHoldoutMse: result.winner.score.raw.holdoutMse, recommendation: result.recommendation, + sourceApplied: result.sourceApplied }, null, 2)); diff --git a/npm/packages/e-means/integrations/cloudflare.d.ts b/npm/packages/e-means/integrations/cloudflare.d.ts new file mode 100644 index 0000000000..499c546dbb --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare.d.ts @@ -0,0 +1,58 @@ +export interface WorkerOptions { + /** Statically import @ruvector/e-means/wasm in a Worker. */ + wasmModule: WebAssembly.Module; + bearerToken?: string; + /** Explicit local/trusted opt-in; false by default. */ + allowUnauthenticated?: boolean; + maxRequestBytes?: number; + maxWork?: number; + bodyTimeoutMs?: number; +} +/** One row-major set of full-dimensional centroids, not subspace-major PQ books. */ +export interface CodebookInput { + dimensions: number; + centroids: Float32Array; + schema?: 'ruvector.e-means-codebook/1'; +} +export interface StoredCodebook extends CodebookInput { + schema: 'ruvector.e-means-codebook/1'; + clusters: number; +} +export interface R2Binding { + put(key: string, body: string, options?: { httpMetadata?: { contentType?: string } }): Promise; + get(key: string): Promise<{ size: number; body: ReadableStream } | null>; +} +export interface VectorizeVector { + id: string; + values: number[]; + metadata: { cluster: number }; + namespace?: string; +} +export interface VectorizeBinding { + upsert(vectors: VectorizeVector[]): Promise<{ mutationId: string }>; +} +export interface ExportOptions { + /** Use a versioned prefix for a new codebook; old centroid IDs are not deleted. */ + prefix: string; + namespace?: string; + batchSize?: number; +} +export interface ExportReceipt { submitted: number; mutationIds: string[] } +/** Does not persist request data. Operations fail closed unless authentication is configured. */ +export function createClusteringWorker(options: WorkerOptions): { fetch(request: Request): Promise }; +export function persistCodebook(bucket: Pick, key: string, model: CodebookInput): Promise<{ + key: string; dimensions: number; clusters: number; bytes: number; +}>; +export function loadCodebook(bucket: Pick, key: string): Promise; +/** Batches upserts; acknowledgement does not establish query visibility or atomicity. */ +export function exportCentroids(index: VectorizeBinding, model: CodebookInput, options: ExportOptions): Promise; +export class CentroidExportError extends Error { + constructor(submitted: number, mutationIds: readonly string[], cause: unknown); + /** Rows in previously acknowledged batches; the failing batch may also have applied. */ + submitted: number; + mutationIds: string[]; +} +export const WORKER_LIMITS: Readonly<{ + maxRequestBytes: number; maxWork: number; maxRows: number; maxDimensions: number; + maxClusters: number; maxEpochs: number; maxElements: number; maxCodebookBytes: number; +}>; diff --git a/npm/packages/e-means/integrations/cloudflare.mjs b/npm/packages/e-means/integrations/cloudflare.mjs new file mode 100644 index 0000000000..f8ed7db1e0 --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare.mjs @@ -0,0 +1,72 @@ +import { init, fit, predict } from '../runtime.mjs'; +import { workEstimate } from './clustering-validation.mjs'; +import { HTTPError, integer, LIMITS, plain, floats, fitOptions } from './cloudflare/validation.mjs'; +import { readJSON, response, tokenMatches } from './cloudflare/http.mjs'; + +export { persistCodebook, loadCodebook, exportCentroids, CentroidExportError } from './cloudflare/storage.mjs'; +export { LIMITS as WORKER_LIMITS } from './cloudflare/validation.mjs'; + +/** Private, stateless Worker handler. Pass a statically imported WASM module. */ +export function createClusteringWorker(options) { + const config = plain(options, ['wasmModule', 'bearerToken', 'allowUnauthenticated', + 'maxRequestBytes', 'maxWork', 'bodyTimeoutMs'], ['wasmModule'], 'Worker options'); + if (!(config.wasmModule instanceof WebAssembly.Module)) throw new TypeError('wasmModule must be a precompiled WebAssembly.Module'); + if (config.bearerToken !== undefined && (typeof config.bearerToken !== 'string' || + config.bearerToken.length < 24 || config.bearerToken.length > 1024 || !/^[\x21-\x7e]+$/.test(config.bearerToken))) { + throw new TypeError('bearerToken must be 24..1024 printable non-space ASCII characters'); + } + if (config.allowUnauthenticated !== undefined && typeof config.allowUnauthenticated !== 'boolean') { + throw new TypeError('allowUnauthenticated must be boolean'); + } + const maxBytes = integer(config.maxRequestBytes ?? 512 * 1024, 1, LIMITS.maxRequestBytes, 'maxRequestBytes'); + const maxWork = integer(config.maxWork ?? 10_000_000, 1, LIMITS.maxWork, 'maxWork'); + const timeoutMs = integer(config.bodyTimeoutMs ?? 5000, 1, 30_000, 'bodyTimeoutMs'); + const token = config.bearerToken; + return Object.freeze({ async fetch(request) { + try { + if (!(request instanceof Request)) throw new TypeError('request must be a Request'); + const url = new URL(request.url); + if (url.search) throw new HTTPError(400, 'invalid_query', 'Query parameters are unsupported'); + if (url.pathname === '/health') { + if (request.method !== 'GET') return response({ error: 'method_not_allowed' }, 405, { Allow: 'GET' }); + return response({ schema: 'ruvector.e-means-worker/1', stateless: true, + authenticatedOperations: Boolean(token), maxRequestBytes: maxBytes, maxWork }); + } + if (!['/fit', '/predict'].includes(url.pathname)) return response({ error: 'not_found' }, 404); + if (request.method !== 'POST') return response({ error: 'method_not_allowed' }, 405, { Allow: 'POST' }); + if (!token && config.allowUnauthenticated !== true) { + throw new HTTPError(503, 'authentication_unconfigured', 'Configure E_MEANS_BEARER_TOKEN before using operations'); + } + if (token && !tokenMatches(request.headers.get('authorization'), `Bearer ${token}`)) { + throw new HTTPError(401, 'unauthorized', 'A valid bearer token is required'); + } + const isFit = url.pathname === '/fit'; + const fields = isFit ? ['data', 'dimensions', 'options'] : ['data', 'dimensions', 'centroids']; + const body = plain(await readJSON(request, maxBytes, timeoutMs), fields, fields, 'request'); + const dimensions = integer(body.dimensions, 1, LIMITS.maxDimensions, 'dimensions'); + const data = floats(body.data, dimensions, 'data', !isFit); + if (isFit) { + const options = fitOptions(body.options, data.length / dimensions); + // Shared coordinate-scale admission estimate, including centroid + // statistics and O(k²) donor revival; not a hard CPU-clock limit. + const epochs = options.epochs ?? 3; + const work = workEstimate({ ...options, epochs }, data.length / dimensions, 0, dimensions); + if (work > maxWork) throw new HTTPError(413, 'work_budget_exceeded', 'Fit exceeds configured work budget'); + await init(config.wasmModule); + const model = fit(data, dimensions, options); + return response({ ...model, centroids: Array.from(model.centroids), assignments: Array.from(model.assignments) }); + } + const centroids = floats(body.centroids, dimensions, 'centroids'); + const clusters = integer(centroids.length / dimensions, 1, LIMITS.maxClusters, 'clusters'); + if (data.length + centroids.length > LIMITS.maxElements || data.length * clusters > maxWork) { + throw new HTTPError(413, 'work_budget_exceeded', 'Prediction exceeds configured work or element budget'); + } + await init(config.wasmModule); + return response({ assignments: Array.from(predict(data, dimensions, centroids)) }); + } catch (error) { + if (error instanceof HTTPError) return response({ error: error.code, message: error.message }, error.status); + if (error instanceof TypeError || error instanceof RangeError) return response({ error: 'invalid_input', message: error.message }, 422); + return response({ error: 'execution_failed', message: 'Clustering execution failed' }, 500); + } + } }); +} diff --git a/npm/packages/e-means/integrations/cloudflare/http.mjs b/npm/packages/e-means/integrations/cloudflare/http.mjs new file mode 100644 index 0000000000..3b7f58550e --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/http.mjs @@ -0,0 +1,59 @@ +import { HTTPError } from './validation.mjs'; + +export function response(value, status = 200, headers = {}) { + return new Response(JSON.stringify(value), { status, headers: { + 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', + 'X-Content-Type-Options': 'nosniff', ...headers, + } }); +} + +export function tokenMatches(value, token) { + if (typeof value !== 'string' || value.length !== token.length) return false; + let different = 0; + for (let index = 0; index < token.length; index++) different |= value.charCodeAt(index) ^ token.charCodeAt(index); + return different === 0; +} + +export async function readBytes(stream, limit, timeoutMs) { + if (!stream || typeof stream.getReader !== 'function') throw new HTTPError(400, 'invalid_body', 'A body is required'); + const reader = stream.getReader(); + let timer; + const cancel = () => { void reader.cancel('body rejected').catch(() => {}); }; + const read = async () => { + let bytes = new Uint8Array(Math.min(limit, 8192)), size = 0; + for (;;) { + const { value, done } = await reader.read(); + if (done) return bytes.subarray(0, size); + if (!(value instanceof Uint8Array)) throw new HTTPError(400, 'invalid_body', 'Body must contain bytes'); + if (value.byteLength > limit - size) { + cancel(); + throw new HTTPError(413, 'body_too_large', 'Body exceeds byte limit'); + } + const next = size + value.byteLength; + if (next > bytes.length) { + const grown = new Uint8Array(Math.min(limit, Math.max(next, bytes.length * 2))); + grown.set(bytes); bytes = grown; + } + bytes.set(value, size); size = next; + } + }; + const deadline = new Promise((_, reject) => { + timer = setTimeout(() => { cancel(); reject(new HTTPError(408, 'body_timeout', 'Body read timed out')); }, timeoutMs); + }); + try { return await Promise.race([read(), deadline]); } + finally { clearTimeout(timer); reader.releaseLock(); } +} + +export async function readJSON(request, limit, timeoutMs) { + const type = request.headers.get('content-type'); + if (!type || !/^application\/json(?:\s*;\s*charset\s*=\s*(?:utf-8|"utf-8"))?\s*$/i.test(type)) { + throw new HTTPError(415, 'unsupported_media_type', 'Content-Type must be UTF-8 application/json'); + } + const length = request.headers.get('content-length'); + if (length !== null && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > limit)) { + throw new HTTPError(413, 'body_too_large', 'Body exceeds byte limit'); + } + const bytes = await readBytes(request.body, limit, timeoutMs); + try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } + catch { throw new HTTPError(400, 'invalid_json', 'Body must be valid UTF-8 JSON'); } +} diff --git a/npm/packages/e-means/integrations/cloudflare/storage.mjs b/npm/packages/e-means/integrations/cloudflare/storage.mjs new file mode 100644 index 0000000000..71ecee2799 --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/storage.mjs @@ -0,0 +1,78 @@ +import { checkedCodebook, integer, LIMITS, plain, safeText } from './validation.mjs'; +import { readBytes } from './http.mjs'; + +/** Persist centroids only, never input vectors or assignments. Binding is caller-owned. */ +export async function persistCodebook(bucket, key, model) { + if (typeof bucket?.put !== 'function') throw new TypeError('an R2 put binding is required'); + safeText(key, 'key', 1024); + const checked = checkedCodebook(model); + const body = JSON.stringify({ ...checked, centroids: Array.from(checked.centroids) }); + const bytes = new TextEncoder().encode(body).byteLength; + if (bytes > LIMITS.maxCodebookBytes) throw new RangeError('codebook exceeds storage byte limit'); + const result = await bucket.put(key, body, { httpMetadata: { contentType: 'application/json' } }); + if (!result || typeof result !== 'object') throw new Error('R2 did not acknowledge the codebook write'); + return { key, dimensions: checked.dimensions, clusters: checked.clusters, bytes }; +} + +export async function loadCodebook(bucket, key) { + if (typeof bucket?.get !== 'function') throw new TypeError('an R2 get binding is required'); + safeText(key, 'key', 1024); + const stored = await bucket.get(key); + if (stored === null) return null; + if (!stored || !Number.isSafeInteger(stored.size) || stored.size < 0 || stored.size > LIMITS.maxCodebookBytes) { + throw new RangeError('stored codebook exceeds storage byte limit'); + } + const bytes = await readBytes(stored.body, LIMITS.maxCodebookBytes, 5000); + let parsed; + try { parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } + catch { throw new TypeError('stored codebook must be valid UTF-8 JSON'); } + const record = plain(parsed, ['schema', 'dimensions', 'clusters', 'centroids'], + ['schema', 'dimensions', 'clusters', 'centroids'], 'stored codebook'); + if (record.schema !== 'ruvector.e-means-codebook/1' || !Array.isArray(record.centroids) || + record.centroids.length > LIMITS.maxElements) throw new TypeError('unsupported stored codebook'); + for (const value of record.centroids) { + if (!Number.isFinite(value) || Math.abs(value) > 3.4028234663852886e38) throw new RangeError('stored centroids must be finite float32 values'); + } + const checked = checkedCodebook({ dimensions: record.dimensions, centroids: new Float32Array(record.centroids) }); + if (record.clusters !== checked.clusters) throw new TypeError('stored cluster count does not match centroid shape'); + return checked; +} + +export class CentroidExportError extends Error { + constructor(submitted, mutationIds, cause) { + super('Vectorize export failed after a partially submitted batch sequence', { cause }); + this.name = 'CentroidExportError'; this.submitted = submitted; this.mutationIds = [...mutationIds]; + } +} + +/** Submit centroids to Vectorize. Acknowledged mutations may not be query-visible yet. */ +export async function exportCentroids(index, model, options) { + if (typeof index?.upsert !== 'function') throw new TypeError('a Vectorize upsert binding is required'); + const config = plain(options, ['prefix', 'namespace', 'batchSize'], ['prefix'], 'Vectorize options'); + safeText(config.prefix, 'prefix', 64); + if (config.namespace !== undefined) safeText(config.namespace, 'namespace', 64); + const batchSize = integer(config.batchSize ?? 1000, 1, 1000, 'batchSize'); + const checked = checkedCodebook(model); + integer(checked.dimensions, 1, 1536, 'Vectorize dimensions'); + // Every ID uses the same prefix and a decimal ordinal; the last is longest. + safeText(`${config.prefix}:${checked.clusters - 1}`, 'vector id', 64); + let submitted = 0; + const mutationIds = []; + while (submitted < checked.clusters) { + const end = Math.min(checked.clusters, submitted + batchSize), vectors = []; + for (let ordinal = submitted; ordinal < end; ordinal++) { + const row = checked.centroids.subarray(ordinal * checked.dimensions, (ordinal + 1) * checked.dimensions); + vectors.push({ id: `${config.prefix}:${ordinal}`, values: Array.from(row), metadata: { cluster: ordinal }, + ...(config.namespace === undefined ? {} : { namespace: config.namespace }) }); + } + let result; + try { + result = await index.upsert(vectors); + safeText(result?.mutationId, 'Vectorize mutation id', 256); + } + catch (cause) { throw new CentroidExportError(submitted, mutationIds, cause); } + submitted = end; + mutationIds.push(result.mutationId); + } + return { submitted, mutationIds }; +} diff --git a/npm/packages/e-means/integrations/cloudflare/validation.mjs b/npm/packages/e-means/integrations/cloudflare/validation.mjs new file mode 100644 index 0000000000..bf054d7b7e --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/validation.mjs @@ -0,0 +1,107 @@ +export const LIMITS = Object.freeze({ + maxRequestBytes: 1024 * 1024, + maxWork: 100_000_000, + maxRows: 16_384, + maxDimensions: 1536, + maxClusters: 256, + maxEpochs: 32, + maxElements: 262_144, + maxCodebookBytes: 8 * 1024 * 1024, +}); + +export class HTTPError extends Error { + constructor(status, code, message) { super(message); this.status = status; this.code = code; } +} + +export function plain(value, allowed, required, name) { + if (!value || typeof value !== 'object' || Array.isArray(value) || + ![Object.prototype, null].includes(Object.getPrototypeOf(value))) { + throw new TypeError(`${name} must be a plain object`); + } + const output = Object.create(null); + for (const key of Reflect.ownKeys(value)) { + const descriptor = Object.getOwnPropertyDescriptor(value, key); + if (typeof key !== 'string' || !allowed.includes(key) || !Object.hasOwn(descriptor, 'value')) { + throw new TypeError(`unknown or accessor ${name} field`); + } + output[key] = descriptor.value; + } + if (required.some(key => !Object.hasOwn(output, key))) throw new TypeError(`missing ${name} field`); + return output; +} + +export function integer(value, min, max, name) { + if (!Number.isSafeInteger(value) || value < min || value > max) { + throw new RangeError(`${name} must be an integer in ${min}..${max}`); + } + return value; +} + +export function safeText(value, name, maxBytes) { + if (typeof value !== 'string' || value.length === 0 || /[\u0000-\u001f\u007f]/.test(value)) { + throw new TypeError(`${name} must be nonempty text without control characters`); + } + for (const character of value) { + const code = character.codePointAt(0); + if (code >= 0xd800 && code <= 0xdfff) throw new TypeError(`${name} must contain valid Unicode`); + } + if (new TextEncoder().encode(value).byteLength > maxBytes) throw new RangeError(`${name} exceeds ${maxBytes} UTF-8 bytes`); + return value; +} + +export function floats(values, dimensions, name, allowEmpty = false) { + if (!Array.isArray(values) || (!allowEmpty && values.length === 0) || + values.length > LIMITS.maxElements || values.length % dimensions !== 0) { + throw new RangeError(`${name} must be a bounded array of complete vectors`); + } + integer(values.length / dimensions, allowEmpty ? 0 : 1, LIMITS.maxRows, `${name} rows`); + for (const value of values) { + if (!Number.isFinite(value) || Math.abs(value) > 3.4028234663852886e38) { + throw new RangeError(`${name} must contain finite float32 values`); + } + } + return new Float32Array(values); +} + +export function fitOptions(value, rows) { + const options = plain(value, ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization'], ['clusters'], 'fit options'); + integer(options.clusters, 1, Math.min(rows, LIMITS.maxClusters), 'clusters'); + if (options.epochs !== undefined) integer(options.epochs, 1, LIMITS.maxEpochs, 'epochs'); + if (options.batchSize !== undefined) integer(options.batchSize, 1, LIMITS.maxRows, 'batchSize'); + if (options.peakStep !== undefined && (!Number.isFinite(options.peakStep) || options.peakStep <= 0 || options.peakStep > 1)) { + throw new RangeError('peakStep must be in (0, 1]'); + } + if (options.seed !== undefined) integer(options.seed, 0, Number.MAX_SAFE_INTEGER, 'seed'); + if (options.finalization !== undefined && !['lastEpochMean', 'ema'].includes(options.finalization)) { + throw new TypeError('unsupported finalization'); + } + return options; +} + +export function checkedCodebook(value) { + if (!value || typeof value !== 'object') throw new TypeError('codebook is required'); + const schemaDescriptor = Object.getOwnPropertyDescriptor(value, 'schema'); + if (schemaDescriptor && (!Object.hasOwn(schemaDescriptor, 'value') || schemaDescriptor.value !== 'ruvector.e-means-codebook/1')) { + throw new TypeError('expected a single row-major codebook, not another model schema'); + } + const dimensionsDescriptor = Object.getOwnPropertyDescriptor(value, 'dimensions'); + const centroidsDescriptor = Object.getOwnPropertyDescriptor(value, 'centroids'); + if (!dimensionsDescriptor || !centroidsDescriptor || + !Object.hasOwn(dimensionsDescriptor, 'value') || !Object.hasOwn(centroidsDescriptor, 'value')) { + throw new TypeError('codebook dimensions and centroids must be own data properties'); + } + const dimensions = integer(dimensionsDescriptor.value, 1, LIMITS.maxElements, 'dimensions'); + const centroids = centroidsDescriptor.value; + if (!(centroids instanceof Float32Array) || centroids.length === 0 || + centroids.length > LIMITS.maxElements || centroids.length % dimensions !== 0) { + throw new RangeError('codebook must contain complete finite centroid rows'); + } + // Validate the owned snapshot, including when the caller supplies shared + // storage or overrides its typed-array iterator. + const owned = new Float32Array(centroids); + for (let index = 0; index < owned.length; index++) { + if (!Number.isFinite(owned[index])) throw new RangeError('centroids must be finite'); + } + return { schema: 'ruvector.e-means-codebook/1', dimensions, + clusters: owned.length / dimensions, centroids: owned }; +} diff --git a/npm/packages/e-means/integrations/clustering-validation.mjs b/npm/packages/e-means/integrations/clustering-validation.mjs new file mode 100644 index 0000000000..e7e058f72e --- /dev/null +++ b/npm/packages/e-means/integrations/clustering-validation.mjs @@ -0,0 +1,111 @@ +const PARAMS = ['clusters', 'epochs', 'batchSize', 'peakStep']; +const FIT_KEYS = [...PARAMS, 'seed', 'finalization']; +const MAX_U32 = 0xffff_ffff; +export const MAX_INPUT_BYTES = 64 * 1024 * 1024; +export const MAX_WORK = 1_000_000_000; + +export function object(value, allowed, name) { + if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`); + for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`Unsupported ${name} field: ${key}`); + return value; +} + +export function integer(value, min, max, name) { + if (!Number.isSafeInteger(value) || value < min || value > max) throw new RangeError(`${name} must be an integer in ${min}..${max}`); + return value; +} + +function finite(value, min, max, name) { + if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) throw new RangeError(`${name} must be finite in ${min}..${max}`); + return value; +} + +function rows(data, dimensions, name) { + if (!(data instanceof Float32Array)) throw new TypeError(`${name} must be a Float32Array`); + if (!data.length || data.length % dimensions) throw new RangeError(`${name} must contain nonempty complete vectors`); + for (let i = 0; i < data.length; i++) if (!Number.isFinite(data[i])) throw new RangeError(`${name} must contain only finite values`); + return data.length / dimensions; +} + +function config(value, samples) { + object(value, FIT_KEYS, 'baseline'); + const out = { clusters: value.clusters, epochs: value.epochs === undefined ? 3 : value.epochs, + seed: value.seed === undefined ? 42 : value.seed, finalization: value.finalization === undefined ? 'lastEpochMean' : value.finalization }; + integer(out.clusters, 1, samples, 'clusters'); + integer(out.epochs, 1, MAX_U32, 'epochs'); + integer(out.seed, 0, Number.MAX_SAFE_INTEGER, 'seed'); + if (!['lastEpochMean', 'ema'].includes(out.finalization)) throw new RangeError('Unsupported finalization'); + if (value.batchSize !== undefined) out.batchSize = integer(value.batchSize, 1, MAX_U32, 'batchSize'); + if (value.peakStep !== undefined) out.peakStep = finite(value.peakStep, Number.MIN_VALUE, 1, 'peakStep'); + return out; +} + +function domain(value, baseline, samples) { + object(value, PARAMS, 'domain'); + if (!Object.keys(value).length) throw new RangeError('domain must contain at least one tunable parameter'); + const result = {}; + for (const [name, supplied] of Object.entries(value)) { + object(supplied, ['min', 'max', 'type', 'scale', 'default'], `${name} domain`); + const min = finite(supplied.min, Number.MIN_VALUE, name === 'peakStep' ? 1 : MAX_U32, `${name}.min`); + const max = finite(supplied.max, min, name === 'peakStep' ? 1 : MAX_U32, `${name}.max`); + const type = name === 'peakStep' ? 'float' : 'int'; + if (supplied.type !== type || !['linear', 'log'].includes(supplied.scale)) throw new TypeError(`Invalid type or scale for ${name}`); + if (type === 'int') { integer(min, 1, MAX_U32, `${name}.min`); integer(max, min, MAX_U32, `${name}.max`); } + if (name === 'clusters' && max > samples) throw new RangeError('Cluster domain exceeds training rows'); + if (baseline[name] === undefined || baseline[name] < min || baseline[name] > max) throw new RangeError(`baseline ${name} must be explicitly inside its domain`); + if (supplied.default !== undefined && supplied.default !== baseline[name]) throw new RangeError(`${name}.default must match the baseline`); + result[name] = Object.freeze({ min, max, type, scale: supplied.scale, default: baseline[name] }); + } + return Object.freeze(result); +} + +// Coordinate-scale upper estimate, including short-batch statistics and O(k²) +// donor selection. It is an admission budget, not a measured instruction count. +export function workEstimate(config, n, holdout, d) { + const k = config.clusters, epochs = config.epochs; + // When automatic batch size is requested, B>=1 is a safe lower bound. + const batch = Math.min(config.batchSize ?? 1, n); + const updates = epochs * Math.ceil(n / batch); + const work = n * k * d * epochs + (n + holdout) * k * d + holdout * d + + n * d * (epochs + 1) + n * (epochs + 1) + + updates * k * (8 * d + 6) + Math.floor(updates / 5) * (3 * k * k + 6 * k * d + 3 * k); + if (!Number.isSafeInteger(work) || !Number.isSafeInteger(updates)) throw new RangeError('Clustering work estimate exceeds safe integer range'); + return work; +} + +export function checkOptions(value) { + object(value, ['training', 'holdout', 'dimensions', 'baseline', 'domain', 'budget', 'qualityTolerance'], 'evaluator options'); + const dimensions = integer(value.dimensions, 1, MAX_U32, 'dimensions'); + if (!(value.training instanceof Float32Array) || !(value.holdout instanceof Float32Array)) throw new TypeError('training and holdout must be Float32Array values'); + const bytes = value.training.byteLength + value.holdout.byteLength; + if (bytes > MAX_INPUT_BYTES) throw new RangeError('Input snapshots exceed 64 MiB'); + const n = rows(value.training, dimensions, 'training'), h = rows(value.holdout, dimensions, 'holdout'); + if (value.training.buffer === value.holdout.buffer && value.training.byteOffset < value.holdout.byteOffset + value.holdout.byteLength && + value.holdout.byteOffset < value.training.byteOffset + value.training.byteLength) throw new RangeError('training and holdout must use separate, nonoverlapping rows'); + const baseline = Object.freeze(config(value.baseline, n)); + const space = domain(value.domain, baseline, n); + object(value.budget, ['maxEvaluations', 'maxDistanceCoordinates', 'timeoutMs'], 'budget'); + const budget = Object.freeze({ maxEvaluations: integer(value.budget.maxEvaluations, 1, 32, 'maxEvaluations'), + maxDistanceCoordinates: integer(value.budget.maxDistanceCoordinates, 1, MAX_WORK, 'maxDistanceCoordinates'), + timeoutMs: integer(value.budget.timeoutMs === undefined ? 30_000 : value.budget.timeoutMs, 1, 120_000, 'timeoutMs') }); + const worst = { ...baseline }; + for (const [name, spec] of Object.entries(space)) worst[name] = name === 'batchSize' ? spec.min : spec.max; + const worstCaseWorkPerTrial = workEstimate(worst, n, h, dimensions); + if (worstCaseWorkPerTrial > budget.maxDistanceCoordinates) throw new RangeError(`Domain permits work ${worstCaseWorkPerTrial} above maxDistanceCoordinates`); + const qualityTolerance = finite(value.qualityTolerance === undefined ? 0 : value.qualityTolerance, 0, 1, 'qualityTolerance'); + return { training: new Float32Array(value.training), holdout: new Float32Array(value.holdout), dimensions, n, h, baseline, + domain: space, budget, qualityTolerance, numericSnapshotBytes: bytes, worstCaseWorkPerTrial }; +} + +export function checkGenome(value, space) { + const keys = Object.keys(space); + object(value, keys, 'genome'); + if (Object.keys(value).length !== keys.length) throw new RangeError('Genome must include every domain parameter'); + const out = {}; + for (const [name, spec] of Object.entries(space)) { + out[name] = spec.type === 'int' ? integer(value[name], spec.min, spec.max, name) : finite(value[name], spec.min, spec.max, name); + } + return out; +} + +export const clone = value => structuredClone(value); diff --git a/npm/packages/e-means/integrations/ivf.d.ts b/npm/packages/e-means/integrations/ivf.d.ts new file mode 100644 index 0000000000..c1345fb8ee --- /dev/null +++ b/npm/packages/e-means/integrations/ivf.d.ts @@ -0,0 +1,16 @@ +import type { EMeansModel, EMeansOptions } from '../e-means.js'; + +/** Caller-owned structured-clone-compatible records; postingList validates on every operation. */ +export interface IVFPartition { + schema: 'ruvector-e-means-ivf-v1'; + model: EMeansModel; + /** Length clusters+1. Cluster j occupies indices[offsets[j]..offsets[j+1]). */ + offsets: Uint32Array; + /** Original input indices, in ascending order within every cluster. */ + indices: Uint32Array; +} + +/** Requires init() from the root package. Trains centroids and returns owned posting arrays. */ +export function partition(data: Float32Array, dimensions: number, options: EMeansOptions): IVFPartition; +/** Validates shape, assignment consistency and stable unique indices; returns an owned list. */ +export function postingList(value: IVFPartition, cluster: number): Uint32Array; diff --git a/npm/packages/e-means/integrations/ivf.mjs b/npm/packages/e-means/integrations/ivf.mjs new file mode 100644 index 0000000000..f3fbec8217 --- /dev/null +++ b/npm/packages/e-means/integrations/ivf.mjs @@ -0,0 +1,63 @@ +import { fit } from '../e-means.mjs'; + +const schema = 'ruvector-e-means-ivf-v1'; + +/** Train coarse centroids and construct stable posting lists from exact Rust/WASM assignments. */ +export function partition(data, dimensions, options) { + const model = fit(data, dimensions, options); + const clusters = model.centroids.length / dimensions; + const offsets = new Uint32Array(clusters + 1); + for (const cluster of model.assignments) offsets[cluster + 1]++; + for (let cluster = 0; cluster < clusters; cluster++) offsets[cluster + 1] += offsets[cluster]; + const cursors = offsets.slice(0, clusters); + const indices = new Uint32Array(model.assignments.length); + for (let row = 0; row < model.assignments.length; row++) { + indices[cursors[model.assignments[row]]++] = row; + } + return { schema, model, offsets, indices }; +} + +function validated(value) { + if (value === null || typeof value !== 'object' || value.schema !== schema) { + throw new TypeError(`partition must use schema ${schema}`); + } + const { model, offsets, indices } = value; + if (model === null || typeof model !== 'object') throw new TypeError('partition must contain a model'); + const { dimensions, centroids, assignments, mse, batchSize, peakStep, updates, revivedClusters } = model; + if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 0xffff_ffff) throw new RangeError('model dimensions must be positive'); + if (!(centroids instanceof Float32Array) || centroids.length === 0 || centroids.length % dimensions !== 0) { + throw new RangeError('model centroids must be complete Float32Array vectors'); + } + for (const coordinate of centroids) if (!Number.isFinite(coordinate)) throw new RangeError('model centroids must be finite'); + if (!Number.isFinite(mse) || mse < 0 || !Number.isFinite(peakStep) || peakStep <= 0 || peakStep > 1 || + !Number.isSafeInteger(batchSize) || batchSize < 1 || !Number.isSafeInteger(updates) || updates < 1 || + !Number.isSafeInteger(revivedClusters) || revivedClusters < 0) throw new RangeError('model metrics are invalid'); + if (!(assignments instanceof Uint32Array) || !(offsets instanceof Uint32Array) || !(indices instanceof Uint32Array)) { + throw new TypeError('assignments, offsets and indices must be Uint32Array values'); + } + const clusters = centroids.length / dimensions; + if (offsets.length !== clusters + 1 || offsets[0] !== 0 || offsets[clusters] !== indices.length || indices.length !== assignments.length) { + throw new RangeError('posting offsets must cover every model assignment exactly once'); + } + for (let cluster = 0; cluster < clusters; cluster++) { + const start = offsets[cluster]; + const end = offsets[cluster + 1]; + if (end < start || end > indices.length) throw new RangeError('posting offsets must be monotonic'); + let previous = -1; + for (let cursor = start; cursor < end; cursor++) { + const row = indices[cursor]; + if (row <= previous || row >= assignments.length || assignments[row] !== cluster) { + throw new RangeError('posting indices must be unique, stable and consistent with model assignments'); + } + previous = row; + } + } + return { clusters, offsets, indices }; +} + +/** Return an owned copy of one posting list after validating the caller-owned partition. */ +export function postingList(value, cluster) { + const { clusters, offsets, indices } = validated(value); + if (!Number.isInteger(cluster) || cluster < 0 || cluster >= clusters) throw new RangeError('cluster is outside the partition'); + return indices.slice(offsets[cluster], offsets[cluster + 1]); +} diff --git a/npm/packages/e-means/integrations/metaharness.d.ts b/npm/packages/e-means/integrations/metaharness.d.ts new file mode 100644 index 0000000000..cf7168b873 --- /dev/null +++ b/npm/packages/e-means/integrations/metaharness.d.ts @@ -0,0 +1,115 @@ +import type { EMeansOptions } from '@ruvector/e-means'; + +export interface ClusteringParameter { + min: number; + max: number; + type: 'int' | 'float'; + scale: 'linear' | 'log'; + /** If supplied, must equal the baseline's value for this parameter. */ + default?: number; +} + +export interface ClusteringBudget { + /** Includes the baseline and every admitted dispatch. Integer 1..32. */ + maxEvaluations: number; + /** Conservative scalar-work allowance, including short-batch centroid updates and revival; at most 1e9. */ + maxDistanceCoordinates: number; + /** Cooperative deadline in milliseconds, 1..120000; default 30000. A synchronous fit cannot be preempted. */ + timeoutMs?: number; +} + +export interface ClusteringEvaluationOptions { + training: Float32Array; + /** Nonempty, nonoverlapping validation rows. Selection uses this split; supply another test split for generalization claims. */ + holdout: Float32Array; + dimensions: number; + baseline: EMeansOptions; + /** Searched parameters need explicit baseline values; peakStep uses float, all other fields use int. */ + domain: Partial>; + budget: ClusteringBudget; + /** Relative holdout-MSE degradation allowance in [0,1], default 0. */ + qualityTolerance?: number; +} + +export interface ClusteringScoreCard { + variantId: string; + /** Higher is better: 1/(1+holdoutMse). */ + primary: number; + regressed: boolean; + noopRate: 0; + costPerWin: 0; + raw: { + fitConfig: EMeansOptions; + trainMse: number; + holdoutMse: number; + baselineHoldoutMse: number; + fitMs: number; + holdoutMs: number; + estimatedWork: number; + updates: number; + revivedClusters: number; + trainingRows: number; + holdoutRows: number; + dimensions: number; + }; +} + +export interface ClusteringTrial { + variantId: string; + genome: Record; + score: ClusteringScoreCard; +} + +export interface ClusteringEvaluationReceipt { + schema: 'e-means.clustering-evaluation/1'; + baseline?: ClusteringTrial; + trials: ClusteringTrial[]; + baselineGenome: Record; + baselineConfig: EMeansOptions; + domain: Record; + dimensions: number; + trainingRows: number; + holdoutRows: number; + qualityTolerance: number; + budget: Required; + dispatchCount: number; + consumedWork: number; + worstCaseWorkPerTrial: number; + numericSnapshotBytes: number; + sourceApplied: false; + scope: string; + timingScope: string; + limits: { maxInputBytes: number; maxDistanceCoordinates: number; cooperativeDeadline: true; workUnit: string }; +} + +/** Structurally compatible with @metaharness/darwin's NumericEvaluator. */ +export interface ClusteringEvaluator { + readonly baselineGenome: Readonly>; + readonly domain: Readonly>>; + evaluate(genome: Readonly>, variantId: string): Promise; + /** Returns an independent snapshot. Changes never affect evaluator state. */ + receipt(): ClusteringEvaluationReceipt; +} + +export interface ClusteringTuningOptions extends ClusteringEvaluationOptions { + generations: number; + childrenPerGeneration: number; + mutationSeed?: number; +} + +export interface ClusteringTuningReceipt extends Omit { + schema: 'e-means.clustering-tuning/1'; + engine: { package: '@metaharness/darwin'; version: '0.13.0'; algorithm: 'evolveNumeric' }; + baseline: ClusteringTrial; + winner: ClusteringTrial; + recommendation: EMeansOptions; + winnerRejected: boolean; + improvedOnObservedHoldout: boolean; + search: { generations: number; childrenPerGeneration: number; mutationSeed: number; worstCaseDispatches: number; concurrency: 1 }; + temporaryArchiveRemoved: true; +} + +/** Copies inputs/configuration synchronously. First evaluate() must use baselineGenome. No SDK import occurs here. */ +export function createClusteringEvaluator(options: ClusteringEvaluationOptions): ClusteringEvaluator; +/** Node-only bounded search using the actual optional @metaharness/darwin0.13.0 peer. Never applies a model. */ +export function tuneClustering(options: ClusteringTuningOptions): Promise; diff --git a/npm/packages/e-means/integrations/metaharness.mjs b/npm/packages/e-means/integrations/metaharness.mjs new file mode 100644 index 0000000000..5bcd2ab736 --- /dev/null +++ b/npm/packages/e-means/integrations/metaharness.mjs @@ -0,0 +1,151 @@ +import { init, fit, predict } from '../e-means.mjs'; +import { checkOptions, checkGenome, clone, integer, object, workEstimate, MAX_INPUT_BYTES, MAX_WORK } from './clustering-validation.mjs'; + +function holdoutMse(data, dimensions, centroids) { + const assignments = predict(data, dimensions, centroids); + let loss = 0; + for (let row = 0; row < assignments.length; row++) { + const centroid = assignments[row] * dimensions; + for (let d = 0; d < dimensions; d++) { + const delta = data[row * dimensions + d] - centroids[centroid + d]; + loss += delta * delta; + } + } + return loss / assignments.length; +} + +/** NumericEvaluator compatible with published Darwin0.13.0. Snapshots happen + * synchronously before any await. The first dispatch must be the baseline. + */ +export function createClusteringEvaluator(options) { + const config = checkOptions(options); + const baselineGenome = Object.freeze(Object.fromEntries(Object.keys(config.domain).map(key => [key, config.baseline[key]]))); + const trials = [], ids = new Set(); + let active = false, calls = 0, consumedWork = 0, baseline; + const started = performance.now(); + const check = () => { + if (performance.now() - started > config.budget.timeoutMs) throw new Error('Clustering cooperative deadline exceeded'); + }; + const receipt = () => clone({ schema: 'e-means.clustering-evaluation/1', baseline, trials, + baselineGenome, baselineConfig: config.baseline, domain: config.domain, + dimensions: config.dimensions, trainingRows: config.n, holdoutRows: config.h, + qualityTolerance: config.qualityTolerance, budget: config.budget, + dispatchCount: calls, consumedWork, worstCaseWorkPerTrial: config.worstCaseWorkPerTrial, + numericSnapshotBytes: config.numericSnapshotBytes, sourceApplied: false, + scope: 'Caller-supplied training and holdout snapshots. Holdout guides selection and is not an independent generalization test.', + timingScope: 'One synchronous Rust/WASM fit and one separate holdout prediction/MSE calculation per dispatch; initialization excluded.', + limits: { maxInputBytes: MAX_INPUT_BYTES, maxDistanceCoordinates: MAX_WORK, cooperativeDeadline: true, + workUnit: 'Conservative coordinate-scale work estimate including centroid updates and donor selection; not measured instructions.' } }); + + const evaluator = { + baselineGenome, + domain: config.domain, + async evaluate(genome, variantId) { + check(); + if (active) throw new Error('Concurrent clustering evaluations are not supported'); + if (calls >= config.budget.maxEvaluations) throw new RangeError('Clustering evaluation budget exhausted'); + calls++; + if (typeof variantId !== 'string' || !variantId || variantId.length > 128 || ids.has(variantId)) throw new TypeError('variantId must be a unique nonempty label of at most 128 characters'); + const selected = checkGenome(genome, config.domain); + if (!baseline && JSON.stringify(selected) !== JSON.stringify(baselineGenome)) throw new Error('First evaluation must use baselineGenome'); + const fitConfig = { ...config.baseline, ...selected }; + const work = workEstimate(fitConfig, config.n, config.h, config.dimensions); + if (work > config.budget.maxDistanceCoordinates - consumedWork) throw new RangeError('Clustering coordinate work budget exhausted'); + ids.add(variantId); consumedWork += work; active = true; + try { + await init(); + check(); + const fitStart = performance.now(); + const model = fit(config.training, config.dimensions, fitConfig); + const fitMs = performance.now() - fitStart; + check(); + const scoreStart = performance.now(); + const mse = holdoutMse(config.holdout, config.dimensions, model.centroids); + const holdoutMs = performance.now() - scoreStart; + check(); + if (!Number.isFinite(mse) || mse < 0) throw new Error('Nonfinite clustering evaluation'); + const baselineMse = baseline?.score.raw.holdoutMse ?? mse; + const score = { variantId, primary: 1 / (1 + mse), regressed: mse > baselineMse * (1 + config.qualityTolerance), + noopRate: 0, costPerWin: 0, raw: { fitConfig, trainMse: model.mse, holdoutMse: mse, baselineHoldoutMse: baselineMse, + fitMs, holdoutMs, estimatedWork: work, updates: model.updates, revivedClusters: model.revivedClusters, + trainingRows: config.n, holdoutRows: config.h, dimensions: config.dimensions } }; + const trial = clone({ variantId, genome: selected, score }); + trials.push(trial); + if (!baseline) baseline = trial; + return clone(score); + } finally { active = false; } + }, + receipt, + }; + return Object.freeze(evaluator); +} + +async function loadDarwin() { + const { readFile } = await import('node:fs/promises'); + let entry; + try { entry = import.meta.resolve('@metaharness/darwin'); } + catch (cause) { throw new Error('tuneClustering requires optional peer @metaharness/darwin@0.13.0', { cause }); } + const manifest = JSON.parse(await readFile(new URL('../package.json', entry), 'utf8')); + if (manifest.name !== '@metaharness/darwin' || manifest.version !== '0.13.0') throw new Error('Expected @metaharness/darwin 0.13.0'); + const { evolveNumeric } = await import('@metaharness/darwin'); + if (typeof evolveNumeric !== 'function') throw new Error('Darwin numeric API is unavailable'); + return evolveNumeric; +} + +/** Run bounded, local numeric evolution. Never mutates source or applies a model. */ +export async function tuneClustering(options) { + const started = performance.now(); + object(options, ['training', 'holdout', 'dimensions', 'baseline', 'domain', 'budget', 'qualityTolerance', 'generations', 'childrenPerGeneration', 'mutationSeed'], 'tuning options'); + const { generations, childrenPerGeneration, mutationSeed = 0, ...evaluation } = options; + integer(generations, 1, 8, 'generations'); + integer(childrenPerGeneration, 1, 8, 'childrenPerGeneration'); + integer(mutationSeed, 0, 0xffff_ffff, 'mutationSeed'); + const evaluator = createClusteringEvaluator(evaluation); + const initial = evaluator.receipt(); + const check = () => { + if (performance.now() - started > initial.budget.timeoutMs) throw new Error('Clustering cooperative deadline exceeded'); + }; + const worstCaseDispatches = 1 + childrenPerGeneration + 2 * childrenPerGeneration * (generations - 1); + if (worstCaseDispatches > initial.budget.maxEvaluations) throw new RangeError('Darwin worst-case dispatches exceed maxEvaluations'); + if (worstCaseDispatches * initial.worstCaseWorkPerTrial > initial.budget.maxDistanceCoordinates) throw new RangeError('Darwin worst-case work exceeds maxDistanceCoordinates'); + const evolveNumeric = await loadDarwin(); + check(); + const { mkdtemp, rm } = await import('node:fs/promises'); + const { tmpdir } = await import('node:os'); + const { join } = await import('node:path'); + let archive, failure, answer; + try { + archive = await mkdtemp(join(tmpdir(), 'e-means-darwin-')); + check(); + const result = await evolveNumeric({ genomeSpec: evaluator.domain, baselineGenome: evaluator.baselineGenome, + evaluator: { evaluate: async (...args) => { + try { return await evaluator.evaluate(...args); } + catch (error) { failure = error; throw error; } + } }, generations, childrenPerGeneration, seed: mutationSeed, concurrency: 1, + mutationSigma: 0.2, crossover: false, workRoot: archive }); + if (failure) throw failure; + check(); + const measured = evaluator.receipt(); + if (!Array.isArray(result?.records) || result.records.length !== measured.trials.length || measured.dispatchCount !== measured.trials.length) throw new Error('Darwin archive differs from observed evaluations'); + const observed = new Map(measured.trials.map(trial => [trial.variantId, trial])); + const verified = record => { + const trial = observed.get(record?.variant?.id); + if (!trial || JSON.stringify(trial.genome) !== JSON.stringify(record.variant.genome) || JSON.stringify(trial.score) !== JSON.stringify(record.score)) throw new Error('Darwin returned an unobserved result'); + return trial; + }; + for (const record of result.records) verified(record); + const baseline = verified(result.baseline); + if (JSON.stringify(baseline.genome) !== JSON.stringify(evaluator.baselineGenome)) throw new Error('Darwin changed the requested baseline'); + let winner = result.winner ? verified(result.winner) : baseline; + const winnerRejected = winner.score.regressed || winner.score.primary < baseline.score.primary; + if (winnerRejected) winner = baseline; + answer = { engine: { package: '@metaharness/darwin', version: '0.13.0', algorithm: 'evolveNumeric' }, + ...measured, schema: 'e-means.clustering-tuning/1', baseline, winner, + recommendation: clone(winner.score.raw.fitConfig), winnerRejected, + improvedOnObservedHoldout: winner.score.primary > baseline.score.primary, + search: { generations, childrenPerGeneration, mutationSeed, worstCaseDispatches, concurrency: 1 }, + sourceApplied: false, temporaryArchiveRemoved: true }; + } finally { if (archive) await rm(archive, { recursive: true, force: true }); } + check(); + return answer; +} diff --git a/npm/packages/e-means/integrations/quantization.d.ts b/npm/packages/e-means/integrations/quantization.d.ts new file mode 100644 index 0000000000..b1aa5ad55e --- /dev/null +++ b/npm/packages/e-means/integrations/quantization.d.ts @@ -0,0 +1,29 @@ +import type { EMeansOptions } from '../e-means.js'; + +/** Caller-owned mutable records. Every codec operation validates their shape and finite coordinates. */ +export interface ProductQuantizer { + schema: 'ruvector-e-means-pq-v1'; + dimensions: number; + subspaces: number; + /** 1..256, shared by every subspace. */ + clusters: number; + /** Flat subspace-major codebooks: subspaces × clusters × (dimensions/subspaces). */ + centroids: Float32Array; +} + +export interface ProductQuantizerJSON { + schema: 'ruvector-e-means-pq-v1'; + dimensions: number; + subspaces: number; + clusters: number; + centroids: number[]; +} + +/** Requires init() from the root package. Input data is borrowed; returned centroids are owned. */ +export function trainProductQuantizer(data: Float32Array, dimensions: number, subspaces: number, options: EMeansOptions): ProductQuantizer; +/** Requires init(). Codes are row-major, rows × subspaces bytes. Empty input is supported. */ +export function encodeProductQuantizer(model: ProductQuantizer, data: Float32Array): Uint8Array; +/** No runtime initialization required. Returns an owned reconstruction; empty codes are supported. */ +export function decodeProductQuantizer(model: ProductQuantizer, codes: Uint8Array): Float32Array; +export function productQuantizerToJSON(model: ProductQuantizer): ProductQuantizerJSON; +export function productQuantizerFromJSON(value: unknown): ProductQuantizer; diff --git a/npm/packages/e-means/integrations/quantization.mjs b/npm/packages/e-means/integrations/quantization.mjs new file mode 100644 index 0000000000..85537def17 --- /dev/null +++ b/npm/packages/e-means/integrations/quantization.mjs @@ -0,0 +1,144 @@ +import { fit, predict } from '../e-means.mjs'; + +const schema = 'ruvector-e-means-pq-v1'; +const maxU32 = 0xffff_ffff; + +function positiveInteger(value, name, maximum = maxU32) { + if (!Number.isInteger(value) || value < 1 || value > maximum) { + throw new RangeError(`${name} must be an integer in 1..${maximum}`); + } +} + +function shape(dimensions, subspaces, clusters) { + positiveInteger(dimensions, 'dimensions'); + positiveInteger(subspaces, 'subspaces', dimensions); + positiveInteger(clusters, 'clusters', 256); + if (dimensions % subspaces !== 0) throw new RangeError('dimensions must be divisible by subspaces'); + return dimensions / subspaces; +} + +function vectors(data, dimensions, allowEmpty = false) { + if (!(data instanceof Float32Array)) throw new TypeError('data must be a Float32Array'); + if ((!allowEmpty && data.length === 0) || data.length % dimensions !== 0) { + throw new RangeError('data must contain complete vectors'); + } + for (const value of data) if (!Number.isFinite(value)) throw new RangeError('data must be finite'); +} + +function validated(model) { + if (model === null || typeof model !== 'object' || model.schema !== schema) { + throw new TypeError(`model must use schema ${schema}`); + } + const { dimensions, subspaces, clusters, centroids } = model; + const subDimensions = shape(dimensions, subspaces, clusters); + if (!(centroids instanceof Float32Array)) throw new TypeError('centroids must be a Float32Array'); + if (centroids.length !== dimensions * clusters) throw new RangeError('centroid count does not match the codebook shape'); + for (const value of centroids) if (!Number.isFinite(value)) throw new RangeError('centroids must be finite'); + return { dimensions, subspaces, clusters, centroids, subDimensions }; +} + +function gather(data, dimensions, subDimensions, subspace, target) { + for (let row = 0; row < data.length / dimensions; row++) { + const start = row * dimensions + subspace * subDimensions; + target.set(data.subarray(start, start + subDimensions), row * subDimensions); + } +} + +function snapshotOptions(options) { + if (options === null || typeof options !== 'object' || Array.isArray(options)) { + throw new TypeError('options must contain clusters'); + } + // Read caller properties once so all subspaces use one stable configuration. + const config = { ...options }; + const supported = ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization']; + for (const key of Object.keys(config)) if (!supported.includes(key)) throw new TypeError(`Unknown option: ${key}`); + if (config.epochs !== undefined) positiveInteger(config.epochs, 'epochs'); + if (config.batchSize !== undefined) positiveInteger(config.batchSize, 'batchSize'); + if (config.peakStep !== undefined && + (typeof config.peakStep !== 'number' || !Number.isFinite(config.peakStep) || config.peakStep <= 0 || config.peakStep > 1)) { + throw new RangeError('peakStep must be finite and in (0, 1]'); + } + if (config.seed !== undefined && (!Number.isSafeInteger(config.seed) || config.seed < 0)) throw new RangeError('seed must be a non-negative safe integer'); + if (config.finalization !== undefined && !['lastEpochMean', 'ema'].includes(config.finalization)) throw new RangeError('unsupported finalization'); + return config; +} + +/** Train independent subspace codebooks using the shared Rust/WASM fitter. Requires init(). */ +export function trainProductQuantizer(data, dimensions, subspaces, options) { + const config = snapshotOptions(options); + const clusters = config.clusters; + const subDimensions = shape(dimensions, subspaces, clusters); + vectors(data, dimensions); + const rows = data.length / dimensions; + if (clusters > rows) throw new RangeError('clusters cannot exceed the number of vectors'); + const centroids = new Float32Array(clusters * dimensions); + const subvector = new Float32Array(rows * subDimensions); + for (let subspace = 0; subspace < subspaces; subspace++) { + gather(data, dimensions, subDimensions, subspace, subvector); + const model = fit(subvector, subDimensions, config); + centroids.set(model.centroids, subspace * clusters * subDimensions); + } + return { schema, dimensions, subspaces, clusters, centroids }; +} + +/** Encode to row-major, one-byte-per-subspace codes using exact Rust/WASM assignment. */ +export function encodeProductQuantizer(model, data) { + const { dimensions, subspaces, clusters, centroids, subDimensions } = validated(model); + vectors(data, dimensions, true); + const rows = data.length / dimensions; + const codes = new Uint8Array(rows * subspaces); + const subvector = new Float32Array(rows * subDimensions); + for (let subspace = 0; subspace < subspaces; subspace++) { + gather(data, dimensions, subDimensions, subspace, subvector); + const start = subspace * clusters * subDimensions; + const assignments = predict(subvector, subDimensions, centroids.subarray(start, start + clusters * subDimensions)); + for (let row = 0; row < rows; row++) codes[row * subspaces + subspace] = assignments[row]; + } + return codes; +} + +/** Reconstruct row-major vectors from a validated codebook and byte codes. Does not require init(). */ +export function decodeProductQuantizer(model, codes) { + const { dimensions, subspaces, clusters, centroids, subDimensions } = validated(model); + if (!(codes instanceof Uint8Array)) throw new TypeError('codes must be a Uint8Array'); + if (codes.length % subspaces !== 0) throw new RangeError('codes must contain complete subspace groups'); + for (const code of codes) if (code >= clusters) throw new RangeError('code exceeds the codebook cluster count'); + const rows = codes.length / subspaces; + if (rows * dimensions > maxU32) throw new RangeError('decoded output exceeds the supported element count'); + const data = new Float32Array(rows * dimensions); + for (let row = 0; row < rows; row++) { + for (let subspace = 0; subspace < subspaces; subspace++) { + const code = codes[row * subspaces + subspace]; + const start = (subspace * clusters + code) * subDimensions; + data.set(centroids.subarray(start, start + subDimensions), row * dimensions + subspace * subDimensions); + } + } + return data; +} + +/** Return owned JSON-compatible codebook data. */ +export function productQuantizerToJSON(model) { + const { dimensions, subspaces, clusters, centroids } = validated(model); + return { schema, dimensions, subspaces, clusters, centroids: Array.from(centroids) }; +} + +/** Restore a validated, owned typed codebook from parsed JSON. */ +export function productQuantizerFromJSON(value) { + if (value === null || typeof value !== 'object' || value.schema !== schema) { + throw new TypeError(`model must use schema ${schema}`); + } + const { dimensions, subspaces, clusters, centroids } = value; + shape(dimensions, subspaces, clusters); + if (!Array.isArray(centroids) || centroids.length !== dimensions * clusters) { + throw new RangeError('JSON centroids must be an array matching the codebook shape'); + } + const owned = new Float32Array(centroids.length); + for (let index = 0; index < centroids.length; index++) { + const coordinate = centroids[index]; + if (typeof coordinate !== 'number' || !Number.isFinite(coordinate)) throw new RangeError('JSON centroids must be finite numbers'); + owned[index] = coordinate; + } + const model = { schema, dimensions, subspaces, clusters, centroids: owned }; + validated(model); + return model; +} diff --git a/npm/packages/e-means/package-lock.json b/npm/packages/e-means/package-lock.json new file mode 100644 index 0000000000..955f21d604 --- /dev/null +++ b/npm/packages/e-means/package-lock.json @@ -0,0 +1,1534 @@ +{ + "name": "@ruvector/e-means", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@ruvector/e-means", + "version": "0.1.0", + "license": "MIT", + "devDependencies": { + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.13.tgz", + "integrity": "sha512-fWegr+WsEsiMVW4KUNdIIzzMTZSzNiqhy0//6+2MRi2d5NFNsL/AYwBQW8eBnRbTBVRnDVzjaJEUqKaCWjMMdQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.13.tgz", + "integrity": "sha512-fJM50YYjlTiBhgdkGmC1tBpv+FMAyo4annf2X6Aks+0yRlaiVkYW/3f07xAfVVkYIoZ9fFZp+mEThUFnuybhkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.11" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/types": { + "version": "7.29.11", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.11.tgz", + "integrity": "sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.29.11", + "@babel/helper-validator-identifier": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@cloudflare/workerd-darwin-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260730.1.tgz", + "integrity": "sha512-+MBHmPaiTe2KajryW0T24rZvWFxb41hD3d8anNzQqHzft6vSEb18+sp0znSwxgij7ApPhSM1+vhkNg4f3YMguA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-darwin-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260730.1.tgz", + "integrity": "sha512-SBHKntPkKvNPgaCrTe99xC1CAl8ygJDzlYfK0LbuJ1muKadIw35WnhO0wu894fKBtllsVQdNzDLee+cm0ppLSQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-linux-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260730.1.tgz", + "integrity": "sha512-ouyPOSMbiKPeSwUJUvxtMcxGAXs2J4aPE4T5ABIYX5ClcQx5j5bbHTmnqOQEY8sAuLTPjH7dY+iB6UI5ISlwwA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-linux-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260730.1.tgz", + "integrity": "sha512-YQ+Mi78U3TPdgBPtwq+Sm6rJU+Ihl2y0pjYtuuKkdmUbYzL7oLR6Xqq9wljhasnuCFICssDJaqhMep5WizYoEQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-windows-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260730.1.tgz", + "integrity": "sha512-27fAN+vUECW1oYVc1KOcHYpkL8COM2Uxtxql7TL595kxbjoqS5yckw7NLz7bTf2pALFCZWjqXDjZGJ/xbG4ZKQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@img/colour": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", + "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/@img/sharp-darwin-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz", + "integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-darwin-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz", + "integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-freebsd-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz", + "integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==", + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-darwin-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz", + "integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-darwin-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz", + "integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz", + "integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz", + "integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-ppc64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz", + "integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-riscv64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz", + "integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-s390x": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz", + "integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz", + "integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz", + "integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz", + "integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-linux-arm": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz", + "integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz", + "integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-ppc64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz", + "integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-ppc64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-riscv64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz", + "integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-riscv64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-s390x": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz", + "integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-s390x": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz", + "integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-linuxmusl-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz", + "integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-linuxmusl-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz", + "integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz", + "integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==", + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.11.3" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-webcontainers-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz", + "integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz", + "integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-ia32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz", + "integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz", + "integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "node_modules/@metaharness/darwin": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/@metaharness/darwin/-/darwin-0.13.0.tgz", + "integrity": "sha512-L3SrQii70erHVDmo1qx0875IRpVujk86zAO7sxtSVChWCgAjabEmmYRYt72D1VekfUCbSWCgZKIktqUxVAKCFA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.29.13" + }, + "bin": { + "metaharness-darwin": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@poppinss/colors": { + "version": "4.1.6", + "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz", + "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==", + "dev": true, + "license": "MIT", + "dependencies": { + "kleur": "^4.1.5" + } + }, + "node_modules/@poppinss/dumper": { + "version": "0.6.5", + "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz", + "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@sindresorhus/is": "^7.0.2", + "supports-color": "^10.0.0" + } + }, + "node_modules/@poppinss/exception": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz", + "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@sindresorhus/is": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz", + "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "node_modules/@speed-highlight/core": { + "version": "1.2.24", + "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.24.tgz", + "integrity": "sha512-qeW2e1l78afw8VhRPfPQ1Gjj+KU5XFQ/OFV5ti6eTa9bruO7mJyZtA4vw0ofqmA3tKCkROE9xLk3VZoeRc98nw==", + "dev": true, + "license": "CC0-1.0" + }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "node_modules/error-stack-parser-es": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz", + "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/miniflare": { + "version": "4.20260730.0", + "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260730.0.tgz", + "integrity": "sha512-1Z9SB9r/o//80UA02Re3QhtcecSHAyAjf5EcKBfQVlQrCg7Miy79hl2PvtkwFLIaJ5rcrOPdDcRr577okwZPsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "0.8.1", + "sharp": "0.35.2", + "undici": "7.28.0", + "workerd": "1.20260730.1", + "ws": "8.21.0", + "youch": "4.1.0-beta.10" + }, + "bin": { + "miniflare": "bootstrap.js" + }, + "engines": { + "node": ">=22.0.0" + } + }, + "node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/sharp": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz", + "integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@img/colour": "^1.1.0", + "detect-libc": "^2.1.2", + "semver": "^7.8.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-darwin-arm64": "0.35.5", + "@img/sharp-darwin-x64": "0.35.5", + "@img/sharp-freebsd-wasm32": "0.35.5", + "@img/sharp-libvips-darwin-arm64": "1.3.4", + "@img/sharp-libvips-darwin-x64": "1.3.4", + "@img/sharp-libvips-linux-arm": "1.3.4", + "@img/sharp-libvips-linux-arm64": "1.3.4", + "@img/sharp-libvips-linux-ppc64": "1.3.4", + "@img/sharp-libvips-linux-riscv64": "1.3.4", + "@img/sharp-libvips-linux-s390x": "1.3.4", + "@img/sharp-libvips-linux-x64": "1.3.4", + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4", + "@img/sharp-libvips-linuxmusl-x64": "1.3.4", + "@img/sharp-linux-arm": "0.35.5", + "@img/sharp-linux-arm64": "0.35.5", + "@img/sharp-linux-ppc64": "0.35.5", + "@img/sharp-linux-riscv64": "0.35.5", + "@img/sharp-linux-s390x": "0.35.5", + "@img/sharp-linux-x64": "0.35.5", + "@img/sharp-linuxmusl-arm64": "0.35.5", + "@img/sharp-linuxmusl-x64": "0.35.5", + "@img/sharp-webcontainers-wasm32": "0.35.5", + "@img/sharp-win32-arm64": "0.35.5", + "@img/sharp-win32-ia32": "0.35.5", + "@img/sharp-win32-x64": "0.35.5" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/supports-color": { + "version": "10.2.2", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz", + "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici": { + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.18.1" + } + }, + "node_modules/workerd": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260730.1.tgz", + "integrity": "sha512-zmfNIjwYSWFY5chGBOjWtH3xAE7p97FTC6vR4Ep98290ho6AeAR/NVcBD274YCLEUYzqm8yxdtZlxMybU8a3jA==", + "dev": true, + "hasInstallScript": true, + "license": "Apache-2.0", + "bin": { + "workerd": "bin/workerd" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "@cloudflare/workerd-darwin-64": "1.20260730.1", + "@cloudflare/workerd-darwin-arm64": "1.20260730.1", + "@cloudflare/workerd-linux-64": "1.20260730.1", + "@cloudflare/workerd-linux-arm64": "1.20260730.1", + "@cloudflare/workerd-windows-64": "1.20260730.1" + } + }, + "node_modules/ws": { + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/youch": { + "version": "4.1.0-beta.10", + "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz", + "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@poppinss/dumper": "^0.6.4", + "@speed-highlight/core": "^1.2.7", + "cookie": "^1.0.2", + "youch-core": "^0.3.3" + } + }, + "node_modules/youch-core": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz", + "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/exception": "^1.2.2", + "error-stack-parser-es": "^1.0.5" + } + } + } +} diff --git a/npm/packages/e-means/package.json b/npm/packages/e-means/package.json new file mode 100644 index 0000000000..2e1ec03d63 --- /dev/null +++ b/npm/packages/e-means/package.json @@ -0,0 +1,108 @@ +{ + "name": "@ruvector/e-means", + "version": "0.1.0", + "description": "Deterministic e-means clustering from the shared Rust core, compiled to portable WebAssembly", + "type": "module", + "main": "./e-means.mjs", + "types": "./e-means.d.ts", + "exports": { + ".": { + "types": "./e-means.d.ts", + "import": "./e-means.mjs" + }, + "./runtime": { + "types": "./runtime.d.ts", + "import": "./runtime.mjs" + }, + "./quantization": { + "types": "./integrations/quantization.d.ts", + "import": "./integrations/quantization.mjs" + }, + "./ivf": { + "types": "./integrations/ivf.d.ts", + "import": "./integrations/ivf.mjs" + }, + "./metaharness": { + "types": "./integrations/metaharness.d.ts", + "import": "./integrations/metaharness.mjs" + }, + "./cloudflare": { + "types": "./integrations/cloudflare.d.ts", + "import": "./integrations/cloudflare.mjs" + }, + "./cloudflare/build": { + "types": "./examples/cloudflare/build.d.ts", + "import": "./examples/cloudflare/build.mjs" + }, + "./wasm": { + "types": "./wasm-module.d.ts", + "default": "./wasm/ruvector_e_means_bg.wasm" + } + }, + "files": [ + "e-means.mjs", + "e-means.d.ts", + "runtime.mjs", + "runtime.d.ts", + "wasm-module.d.ts", + "integrations/", + "examples/cloudflare/", + "examples/metaharness.mjs", + "wasm/", + "scripts/check-artifact.mjs", + "README.md", + "LICENSE" + ], + "scripts": { + "build": "node scripts/build.mjs", + "test": "node --test test/*.test.mjs", + "test:consumer": "node test/packed-consumer.mjs", + "test:ecosystem": "node test/ecosystem-consumers.mjs", + "test:cloudflare": "node --test test/cloudflare*.test.mjs", + "build:cloudflare": "node examples/cloudflare/build.mjs", + "prepack": "node scripts/check-artifact.mjs", + "typecheck": "tsc --noEmit -p test/tsconfig.json", + "test:browser": "node test/browser-consumer.mjs", + "benchmark": "node --expose-gc test/benchmark.mjs" + }, + "engines": { + "node": ">=20.0.0" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/ruvnet/ruvector.git", + "directory": "npm/packages/e-means" + }, + "publishConfig": { + "access": "public" + }, + "keywords": [ + "clustering", + "e-means", + "ema", + "k-means", + "webassembly", + "rust" + ], + "devDependencies": { + "typescript": "5.9.3", + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + }, + "overrides": { + "miniflare": { + "sharp": "0.35.5", + "undici": "7.30.1" + } + } +} diff --git a/npm/packages/e-means/runtime.d.ts b/npm/packages/e-means/runtime.d.ts new file mode 100644 index 0000000000..ab711476c2 --- /dev/null +++ b/npm/packages/e-means/runtime.d.ts @@ -0,0 +1,4 @@ +export { fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; +/** No filesystem/default URL loader. Supply bytes or a precompiled module. */ +export function init(source: BufferSource | WebAssembly.Module): Promise; diff --git a/npm/packages/e-means/runtime.mjs b/npm/packages/e-means/runtime.mjs new file mode 100644 index 0000000000..d79984c862 --- /dev/null +++ b/npm/packages/e-means/runtime.mjs @@ -0,0 +1,96 @@ +import initWasm, { fitTyped, predictFlat } from './wasm/ruvector_e_means.js'; + +let initialized = false; +let initialization; +const maxU32 = 0xffff_ffff; + +/** Initialize from caller-supplied bytes or a precompiled module; no Node loader is reachable. */ +export async function init(source) { + if (initialized) return; + if (!initialization) { + initialization = (async () => { + if (source === undefined) throw new TypeError('runtime init requires WASM bytes or a precompiled module'); + await initWasm({ module_or_path: source }); + initialized = true; + })().catch((error) => { + initialization = undefined; + const message = typeof error?.message === 'string' ? error.message : String(error); + throw new Error(`Could not initialize @ruvector/e-means: ${message}`, { cause: error }); + }); + } + await initialization; +} + +function ready() { + if (!initialized) throw new Error('Call and await init() before using @ruvector/e-means'); +} + +function positiveInteger(value, name) { + if (!Number.isInteger(value) || value <= 0 || value > maxU32) { + throw new RangeError(`${name} must be an integer between 1 and ${maxU32}`); + } +} + +function vectors(data, dimensions, name, allowEmpty = false) { + if (!(data instanceof Float32Array)) throw new TypeError(`${name} must be a Float32Array`); + positiveInteger(dimensions, 'dimensions'); + if ((!allowEmpty && data.length === 0) || data.length % dimensions !== 0) { + throw new RangeError(`${name} must contain complete ${dimensions}-dimensional vectors`); + } + for (let index = 0; index < data.length; index++) { + if (!Number.isFinite(data[index])) throw new RangeError(`${name} must contain only finite values`); + } +} + +/** Cluster flat row-major f32 vectors using the e-means Rust implementation. */ +export function fit(data, dimensions, options) { + ready(); + vectors(data, dimensions, 'data'); + if (options === null || typeof options !== 'object' || Array.isArray(options)) { + throw new TypeError('options must be an object with clusters'); + } + const allowed = ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization']; + for (const key of Object.keys(options)) { + if (!allowed.includes(key)) throw new TypeError(`Unknown option: ${key}`); + } + positiveInteger(options.clusters, 'clusters'); + if (options.clusters > data.length / dimensions) throw new RangeError('clusters cannot exceed the number of vectors'); + if (options.epochs !== undefined) positiveInteger(options.epochs, 'epochs'); + if (options.batchSize !== undefined) positiveInteger(options.batchSize, 'batchSize'); + if (options.peakStep !== undefined && + (typeof options.peakStep !== 'number' || !Number.isFinite(options.peakStep) || options.peakStep <= 0 || options.peakStep > 1)) { + throw new RangeError('peakStep must be a finite number in (0, 1]'); + } + if (options.seed !== undefined && (!Number.isSafeInteger(options.seed) || options.seed < 0)) { + throw new RangeError('seed must be a non-negative safe integer'); + } + if (options.finalization !== undefined && !['lastEpochMean', 'ema'].includes(options.finalization)) { + throw new RangeError('finalization must be lastEpochMean or ema'); + } + // Copy supported options explicitly: inherited properties and toJSON do not become Rust configuration. + const config = { clusters: options.clusters }; + for (const key of allowed.slice(1)) if (options[key] !== undefined) config[key] = options[key]; + const model = fitTyped(data, dimensions, JSON.stringify(config)); + try { + return { + centroids: model.takeCentroids(), + assignments: model.takeAssignments(), + dimensions: model.dimensions, + mse: model.mse, + batchSize: model.batchSize, + peakStep: model.peakStep, + updates: model.updates, + revivedClusters: model.revivedClusters, + }; + } finally { + model.free(); + } +} + +/** Assign vectors to their nearest centroid using squared Euclidean distance. */ +export function predict(data, dimensions, centroids) { + ready(); + vectors(data, dimensions, 'data', true); + vectors(centroids, dimensions, 'centroids'); + return predictFlat(data, dimensions, centroids); +} diff --git a/npm/packages/e-means/scripts/build.mjs b/npm/packages/e-means/scripts/build.mjs new file mode 100644 index 0000000000..4f907425eb --- /dev/null +++ b/npm/packages/e-means/scripts/build.mjs @@ -0,0 +1,23 @@ +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import { mkdir } from 'node:fs/promises'; + +const root = fileURLToPath(new URL('../../../../', import.meta.url)); +const manifest = fileURLToPath(new URL('../../../../crates/ruvector-e-means/Cargo.toml', import.meta.url)); +const target = fileURLToPath(new URL('../../../../target/e-means-wasm/', import.meta.url)); +const output = fileURLToPath(new URL('../wasm/', import.meta.url)); + +function run(command, args) { + const result = spawnSync(command, args, { cwd: root, stdio: 'inherit' }); + if (result.error) throw result.error; + if (result.status !== 0) throw new Error(`${command} exited ${result.status}`); +} + +const version = spawnSync('wasm-bindgen', ['--version'], { encoding: 'utf8' }); +if (version.error || version.status !== 0 || version.stdout.trim() !== 'wasm-bindgen 0.2.125') { + throw new Error('Install wasm-bindgen-cli@0.2.125 and the wasm32-unknown-unknown Rust target before building'); +} +await mkdir(output, { recursive: true }); +run('cargo', ['build', '--locked', '--manifest-path', manifest, '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', target]); +run('wasm-bindgen', [`${target}/wasm32-unknown-unknown/release/ruvector_e_means.wasm`, '--target', 'web', '--out-dir', output, '--out-name', 'ruvector_e_means']); +run(process.execPath, [fileURLToPath(new URL('./check-artifact.mjs', import.meta.url))]); diff --git a/npm/packages/e-means/scripts/check-artifact.mjs b/npm/packages/e-means/scripts/check-artifact.mjs new file mode 100644 index 0000000000..d87a846a50 --- /dev/null +++ b/npm/packages/e-means/scripts/check-artifact.mjs @@ -0,0 +1,11 @@ +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { init, fit } from '../e-means.mjs'; + +const bytes = await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url)); +assert.deepEqual([...bytes.subarray(0, 4)], [0, 97, 115, 109], 'missing or invalid WebAssembly artifact'); +await init(bytes); +const model = fit(new Float32Array([0, 2]), 1, { clusters: 1, epochs: 1 }); +assert.equal(model.centroids[0], 1, 'bundled WASM must run the Rust mean finalizer'); +assert.equal(model.mse, 1); +console.error('Bundled e-means WASM verified'); diff --git a/npm/packages/e-means/test/benchmark.mjs b/npm/packages/e-means/test/benchmark.mjs new file mode 100644 index 0000000000..3a572d30ba --- /dev/null +++ b/npm/packages/e-means/test/benchmark.mjs @@ -0,0 +1,111 @@ +import assert from 'node:assert/strict'; +import { cpus } from 'node:os'; +import { resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { init, fit, predict } from '../e-means.mjs'; +import { fitJson, fitTyped } from '../wasm/ruvector_e_means.js'; + +let baselinePath, repeats = 7; +for (let i = 2; i < process.argv.length; i++) { + const argument = process.argv[i]; + if (argument === '--baseline') baselinePath = process.argv[++i]; + else if (argument === '--repeats') repeats = Number(process.argv[++i]); + else throw new Error(`Unknown benchmark argument: ${argument}`); +} +assert.ok(Number.isInteger(repeats) && repeats >= 3 && repeats <= 31, '--repeats must be in 3..31'); +await init(); +let baseline; +if (baselinePath) { + baseline = await import(pathToFileURL(resolve(baselinePath, 'e-means.mjs')).href); + await baseline.init(); +} + +function materialize(handle) { + try { + return { + centroids: handle.takeCentroids(), assignments: handle.takeAssignments(), + dimensions: handle.dimensions, mse: handle.mse, batchSize: handle.batchSize, + peakStep: handle.peakStep, updates: handle.updates, revivedClusters: handle.revivedClusters, + }; + } finally { + handle.free(); + } +} + +function median(values) { + return [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]; +} + +// Interleave variants and rotate their order to reduce ordering/thermal bias. +// GC is outside the timed region; each result is fully materialized and consumed. +let checksum = 0; +function measure(variants) { + const entries = Object.entries(variants), timings = new Map(entries.map(([name]) => [name, []])); + for (const [, operation] of entries) for (let i = 0; i < 2; i++) operation(); + for (let round = 0; round < repeats; round++) { + for (let i = 0; i < entries.length; i++) { + const [name, operation] = entries[(i + round) % entries.length]; + globalThis.gc?.(); + const start = performance.now(); + const result = operation(); + timings.get(name).push(performance.now() - start); + checksum += result instanceof Uint32Array ? result.length + (result[0] || 0) : result.mse + result.assignments.length; + } + } + return Object.fromEntries([...timings].map(([name, samples]) => [name, median(samples)])); +} + +function compareResults(a, b) { + assert.equal(a.assignments.length, b.assignments.length); + assert.equal(a.centroids.length, b.centroids.length); + let labelDifferences = 0, centroidMaxAbsDifference = 0; + for (let i = 0; i < a.assignments.length; i++) labelDifferences += Number(a.assignments[i] !== b.assignments[i]); + for (let i = 0; i < a.centroids.length; i++) centroidMaxAbsDifference = Math.max(centroidMaxAbsDifference, Math.abs(a.centroids[i] - b.centroids[i])); + return { labelDifferences, centroidMaxAbsDifference, mseAbsoluteDifference: Math.abs(a.mse - b.mse) }; +} + +const cases = [ + { name: 'large-assignment-result', samples: 1_000_000, dimensions: 1, clusters: 1, epochs: 1, batchSize: 4096 }, + { name: 'embedding-codebook', samples: 8192, dimensions: 64, clusters: 16, epochs: 3, batchSize: 256 }, +]; +const results = []; +for (const scenario of cases) { + const { samples, dimensions, clusters, epochs, batchSize } = scenario; + const data = new Float32Array(samples * dimensions); + for (let row = 0; row < samples; row++) { + for (let column = 0; column < dimensions; column++) { + data[row * dimensions + column] = (row % clusters) * 4 + (column % 7) * 0.1 + ((row * 17 + column * 31) % 97) / 9700; + } + } + const options = { clusters, epochs, batchSize, seed: 42 }, config = JSON.stringify(options); + const optimizedModel = fit(data, dimensions, options); + const jsonResult = JSON.parse(fitJson(data, dimensions, config)); + const jsonModel = { ...jsonResult, centroids: Float32Array.from(jsonResult.centroids), assignments: Uint32Array.from(jsonResult.assignments) }; + assert.deepEqual(optimizedModel, jsonModel, 'same optimized kernel must have identical JSON/typed results'); + const baselineModel = baseline?.fit(data, dimensions, options); + if (baselineModel) assert.deepEqual(optimizedModel, baselineModel, 'optimized fit must preserve baseline outputs on the measured fixture'); + const fitVariants = { optimizedMs: () => fit(data, dimensions, options) }; + if (baseline) fitVariants.baselineMs = () => baseline.fit(data, dimensions, options); + const fitTimes = measure(fitVariants); + if (baseline) fitTimes.speedup = fitTimes.baselineMs / fitTimes.optimizedMs; + + const transport = measure({ + jsonMs: () => { + const model = JSON.parse(fitJson(data, dimensions, config)); + return { ...model, centroids: Float32Array.from(model.centroids), assignments: Uint32Array.from(model.assignments) }; + }, + typedMs: () => materialize(fitTyped(data, dimensions, config)), + }); + transport.speedup = transport.jsonMs / transport.typedMs; + const predictVariants = { optimizedMs: () => predict(data, dimensions, optimizedModel.centroids) }; + if (baseline) predictVariants.baselineMs = () => baseline.predict(data, dimensions, baselineModel.centroids); + const predictTimes = measure(predictVariants); + if (baseline) predictTimes.speedup = predictTimes.baselineMs / predictTimes.optimizedMs; + results.push({ ...scenario, fit: fitTimes, predict: predictTimes, sameKernelTransport: transport, + baselineParity: baselineModel ? compareResults(optimizedModel, baselineModel) : undefined }); +} +console.log(JSON.stringify({ runtime: { node: process.version, platform: process.platform, arch: process.arch, + cpu: cpus()[0]?.model, logicalCpus: cpus().length }, repeats, warmupsPerVariant: 2, + measurement: 'median wall-clock milliseconds, fully materialized results; explicit GC outside timing', + sameKernelTransportMeasurement: 'full fit plus output materialization using one optimized WASM kernel; difference includes JSON serialization/parsing and array conversion, not a conversion-only timer', + baselinePath: baselinePath ? resolve(baselinePath) : undefined, checksum, cases: results }, null, 2)); diff --git a/npm/packages/e-means/test/browser-consumer.mjs b/npm/packages/e-means/test/browser-consumer.mjs new file mode 100644 index 0000000000..a38a304477 --- /dev/null +++ b/npm/packages/e-means/test/browser-consumer.mjs @@ -0,0 +1,90 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { createServer } from 'node:http'; +import { mkdtemp, readFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +const page = ``; + +const routes = new Map([ + ['/e-means.mjs', ['../e-means.mjs', 'application/javascript']], + ['/wasm/ruvector_e_means.js', ['../wasm/ruvector_e_means.js', 'application/javascript']], + ['/wasm/ruvector_e_means_bg.wasm', ['../wasm/ruvector_e_means_bg.wasm', 'application/wasm']], +]); +let fetchedWasm = false; +const server = createServer(async (request, response) => { + try { + if (request.url === '/') { + response.writeHead(200, { 'content-type': 'text/html' }); + response.end(page); + return; + } + const route = routes.get(request.url); + if (!route) { + response.writeHead(404); + response.end(); + return; + } + if (request.url.endsWith('.wasm')) fetchedWasm = true; + const bytes = await readFile(new URL(route[0], import.meta.url)); + response.writeHead(200, { 'content-type': route[1] }); + response.end(bytes); + } catch (error) { + response.writeHead(500); + response.end(error.message); + } +}); + +const profile = await mkdtemp(join(tmpdir(), 'e-means-chromium-')); +let browser; +function stopBrowser() { + if (!browser?.pid) return; + try { process.kill(-browser.pid, 'SIGKILL'); } catch (error) { + if (error.code !== 'ESRCH') throw error; + } +} +try { + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + const chromium = process.env.E_MEANS_CHROMIUM || 'chromium'; + const url = `http://127.0.0.1:${server.address().port}/`; + const result = await new Promise((resolve, reject) => { + const child = browser = spawn(chromium, ['--headless', '--no-sandbox', '--disable-dev-shm-usage', + '--disable-gpu', '--disable-background-networking', '--no-first-run', + `--user-data-dir=${profile}`, '--dump-dom', '--virtual-time-budget=10000', url], + { stdio: ['ignore', 'pipe', 'pipe'], detached: true }); + let stdout = '', stderr = ''; + child.stdout.on('data', (chunk) => { stdout += chunk; }); + child.stderr.on('data', (chunk) => { stderr += chunk; }); + const timer = setTimeout(() => { + stopBrowser(); + reject(new Error(`Chromium browser consumer exceeded 25 seconds\n${stdout}\n${stderr.slice(-2000)}`)); + }, 25_000); + child.once('error', (error) => { clearTimeout(timer); reject(error); }); + child.once('close', (status) => { clearTimeout(timer); resolve({ status, stdout, stderr }); }); + }); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /data-result="pass"/, result.stdout + '\n' + result.stderr.slice(-1500)); + assert.ok(fetchedWasm, 'browser must fetch the bundled .wasm through default init()'); + console.log('Chromium browser consumer passed: default WASM fetch, fit, predict and numerical oracle'); +} finally { + stopBrowser(); + await new Promise((resolve) => server.close(resolve)); + await rm(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); +} diff --git a/npm/packages/e-means/test/cloudflare-storage.test.mjs b/npm/packages/e-means/test/cloudflare-storage.test.mjs new file mode 100644 index 0000000000..90b01c8acb --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-storage.test.mjs @@ -0,0 +1,108 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { persistCodebook, loadCodebook, exportCentroids, CentroidExportError } from '../integrations/cloudflare.mjs'; + +const model = { dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]), assignments: new Uint32Array([0, 1]), mse: 1 }; +function stored(body) { return { size: new TextEncoder().encode(body).length, body: new Response(body).body }; } + +test('R2 binding helpers persist only centroid codebooks and restore independent typed output', async () => { + let written; + const bucket = { async put(key, body, options) { written = { key, body, options }; return {}; }, async get() { return stored(written.body); } }; + const receipt = await persistCodebook(bucket, 'private/codebook.json', model); + assert.equal(receipt.clusters, 2); + const record = JSON.parse(written.body); + assert.deepEqual(Object.keys(record).sort(), ['centroids', 'clusters', 'dimensions', 'schema']); + assert.equal(written.options.httpMetadata.contentType, 'application/json'); + const loaded = await loadCodebook(bucket, 'private/codebook.json'); + assert.deepEqual(loaded.centroids, model.centroids); + loaded.centroids[0] = 99; + assert.equal(model.centroids[0], 1); + assert.equal(await loadCodebook({ get: async () => null }, 'missing'), null); +}); + +test('R2 writes snapshot caller-owned centroid data before the first asynchronous boundary', async () => { + const input = { dimensions: 1, centroids: new Float32Array([3, 7]) }; + let payload; + const promise = persistCodebook({ async put(key, body) { payload = body; await Promise.resolve(); return {}; } }, 'snapshot', input); + input.centroids.fill(100); + await promise; + assert.deepEqual(JSON.parse(payload).centroids, [3, 7]); +}); + +test('centroid validation inspects copied numeric storage even with an overridden iterator', async () => { + const centroids = new Float32Array([1, NaN]); + centroids[Symbol.iterator] = function* () { yield 0; }; + const input = { dimensions: 1, centroids }; + let writes = 0; + await assert.rejects(persistCodebook({ put: async () => { writes++; return {}; } }, 'bad', input), /finite/); + await assert.rejects(exportCentroids({ upsert: async () => { writes++; return { mutationId: 'bad' }; } }, input, { prefix: 'bad' }), /finite/); + assert.equal(writes, 0); +}); + +test('PQ envelopes and accessor schemas cannot be mistaken for full-dimensional codebooks', async () => { + let writes = 0, reads = 0; + const bucket = { put: async () => { writes++; return {}; } }; + const index = { upsert: async () => { writes++; return { mutationId: 'unexpected' }; } }; + const pq = { schema: 'ruvector-e-means-pq-v1', dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]) }; + const accessor = { dimensions: 2, centroids: new Float32Array([1, 2]) }; + Object.defineProperty(accessor, 'schema', { get() { reads++; return 'ruvector.e-means-codebook/1'; } }); + for (const input of [pq, accessor]) { + await assert.rejects(persistCodebook(bucket, 'book', input), /single row-major codebook/); + await assert.rejects(exportCentroids(index, input, { prefix: 'book' }), /single row-major codebook/); + } + assert.equal(writes, 0); + assert.equal(reads, 0); +}); + +test('corrupt, oversized, nonfinite and malformed stored codebooks reject', async () => { + for (const record of [ + { schema: 'other', dimensions: 1, clusters: 1, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 2, clusters: 1, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 2, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 1, centroids: ['1'] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 1, centroids: [1e40] }, + ]) await assert.rejects(loadCodebook({ get: async () => stored(JSON.stringify(record)) }, 'bad')); + await assert.rejects(loadCodebook({ get: async () => ({ size: 10_000_000, body: new Response('x').body }) }, 'large')); + await assert.rejects(persistCodebook({ put: async () => null }, 'failed', model), /acknowledge/); + await assert.rejects(persistCodebook({ put: async () => undefined }, 'failed', model), /acknowledge/); + let writes = 0; + await assert.rejects(persistCodebook({ put: async () => { writes++; } }, 'invalid', { dimensions: 1, centroids: new Float32Array([Infinity]) })); + assert.equal(writes, 0); +}); + +test('Vectorize binding export batches static centroid records and propagates explicit namespace', async () => { + const batches = []; + const index = { async upsert(vectors) { batches.push(structuredClone(vectors)); return { mutationId: `m${batches.length}` }; } }; + const receipt = await exportCentroids(index, { dimensions: 1, centroids: Float32Array.from({ length: 2001 }, (_, i) => i) }, + { prefix: 'codebook', namespace: 'owned-namespace' }); + assert.deepEqual(batches.map(batch => batch.length), [1000, 1000, 1]); + assert.deepEqual(receipt, { submitted: 2001, mutationIds: ['m1', 'm2', 'm3'] }); + assert.deepEqual(batches[2][0], { id: 'codebook:2000', values: [2000], metadata: { cluster: 2000 }, namespace: 'owned-namespace' }); + assert.equal(new Set(batches.flat().map(v => v.id)).size, 2001); +}); + +test('Vectorize validates every record before writes and reports acknowledged batches on failure', async () => { + let calls = 0; + const index = { async upsert() { if (++calls === 2) throw new Error('binding failure'); return { mutationId: 'first' }; } }; + for (const [input, options] of [ + [model, { prefix: '😀'.repeat(16) }], [model, { prefix: 'x', namespace: '😀'.repeat(17) }], + [model, { prefix: 'x', batchSize: 1001 }], + [{ dimensions: 1537, centroids: new Float32Array(1537) }, { prefix: 'x' }], + [{ dimensions: 1, centroids: new Float32Array([NaN]) }, { prefix: 'x' }], + ]) await assert.rejects(exportCentroids(index, input, options)); + assert.equal(calls, 0); + await assert.rejects(exportCentroids(index, { dimensions: 1, centroids: new Float32Array(1001) }, { prefix: 'x' }), error => { + assert.ok(error instanceof CentroidExportError); + assert.equal(error.submitted, 1000); + assert.deepEqual(error.mutationIds, ['first']); + return true; + }); + for (const acknowledgement of [undefined, {}, { mutationId: '' }, { mutationId: 'x'.repeat(257) }]) { + await assert.rejects(exportCentroids({ upsert: async () => acknowledgement }, model, { prefix: 'x' }), error => { + assert.ok(error instanceof CentroidExportError); + assert.equal(error.submitted, 0); + assert.deepEqual(error.mutationIds, []); + return true; + }); + } +}); diff --git a/npm/packages/e-means/test/cloudflare-tsconfig.json b/npm/packages/e-means/test/cloudflare-tsconfig.json new file mode 100644 index 0000000000..6fa7091d6d --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-tsconfig.json @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noEmit": true, + "lib": ["ES2022", "DOM"], + "types": [] + }, + "include": ["cloudflare-types.ts"] +} diff --git a/npm/packages/e-means/test/cloudflare-types.ts b/npm/packages/e-means/test/cloudflare-types.ts new file mode 100644 index 0000000000..e9b6eabcc5 --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-types.ts @@ -0,0 +1,25 @@ +import type { EMeansModel } from '@ruvector/e-means'; +import { + createClusteringWorker, persistCodebook, loadCodebook, exportCentroids, + type CodebookInput, type R2Binding, type VectorizeBinding, +} from '@ruvector/e-means/cloudflare'; + +declare const wasm: WebAssembly.Module; +declare const model: EMeansModel; +declare const request: Request; +const worker = createClusteringWorker({ wasmModule: wasm, maxWork: 1_000_000, bodyTimeoutMs: 1000 }); +const response: Promise = worker.fetch(request); +const bucket: R2Binding = { put: async () => ({}), get: async () => null }; +const index: VectorizeBinding = { upsert: async () => ({ mutationId: 'acknowledgement' }) }; +const input: CodebookInput = model; +void response; +void persistCodebook(bucket, 'model', input); +void loadCodebook(bucket, 'model'); +void exportCentroids(index, model, { prefix: 'model', namespace: 'owned' }); +// @ts-expect-error Worker configuration numbers cannot be strings. +createClusteringWorker({ wasmModule: wasm, maxWork: 'unbounded' }); +// @ts-expect-error Codebook storage requires owned float32 centroid arrays. +persistCodebook(bucket, 'model', { dimensions: 1, centroids: [0, 1] }); +// @ts-expect-error Vectorize returns an acknowledgement identity. +const invalidIndex: VectorizeBinding = { upsert: async () => ({}) }; +void invalidIndex; diff --git a/npm/packages/e-means/test/cloudflare-workerd.test.mjs b/npm/packages/e-means/test/cloudflare-workerd.test.mjs new file mode 100644 index 0000000000..eaf0df63f8 --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-workerd.test.mjs @@ -0,0 +1,83 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { mkdtemp, readFile, rm, writeFile, mkdir, symlink } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { tmpdir } from 'node:os'; +import { dirname, join } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { Miniflare } from 'miniflare'; +import { buildWorker } from '../examples/cloudflare/build.mjs'; + +const token = 'e-means-workerd-test-not-for-production'; +const config = { compatibilityDate: '2026-07-30', modules: true, + modulesRules: [{ type: 'CompiledWasm', include: ['**/*.wasm'], fallthrough: true }] }; + +test('packed npm static Rust WASM executes in real workerd without Node compatibility', { timeout: 60_000 }, async t => { + const temporary = await mkdtemp(join(tmpdir(), 'e-means-workerd-')); + const packageDir = fileURLToPath(new URL('../', import.meta.url)); + const run = (args, cwd) => { + const result = spawnSync('npm', args, { cwd, encoding: 'utf8', env: { ...process.env, npm_config_workspaces: 'false' } }); + assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`); + return result.stdout; + }; + const archive = JSON.parse(run(['pack', '--json', '--workspaces=false', '--pack-destination', temporary], packageDir))[0]; + const consumer = join(temporary, 'consumer'); + await mkdir(consumer); + await writeFile(join(consumer, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + run(['install', '--ignore-scripts', '--no-audit', '--no-fund', '--offline', join(temporary, archive.filename)], consumer); + // esbuild is caller-supplied build tooling, not an installed runtime dependency. + await symlink(dirname(dirname(fileURLToPath(import.meta.resolve('esbuild')))), join(consumer, 'node_modules/esbuild'), 'dir'); + const installed = join(consumer, 'node_modules/@ruvector/e-means'); + const builder = await import(pathToFileURL(join(installed, 'examples/cloudflare/build.mjs')).href); + const output = join(temporary, 'output'); + const artifact = await builder.buildWorker(output); + const source = await readFile(artifact.script, 'utf8'); + assert.match(source, /\.\/e-means\.wasm/); + assert.doesNotMatch(source, /node:fs|node:crypto|node:os/); + const worker = new Miniflare({ ...config, modulesRoot: output, scriptPath: artifact.script, + bindings: { E_MEANS_BEARER_TOKEN: token } }); + t.after(async () => { await worker.dispose(); await rm(temporary, { recursive: true, force: true }); }); + const invoke = (path, value, authorization = `Bearer ${token}`) => worker.dispatchFetch(`https://worker.test${path}`, { + method: 'POST', headers: { 'content-type': 'application/json', authorization }, body: JSON.stringify(value), + }); + const health = await worker.dispatchFetch('https://worker.test/health'); + assert.equal(health.status, 200); + assert.equal((await health.json()).stateless, true); + const fitted = await invoke('/fit', { data: [1, 2, 3, 4, 5, 6], dimensions: 2, options: { clusters: 1 } }); + assert.equal(fitted.status, 200, await fitted.clone().text()); + const model = await fitted.json(); + assert.deepEqual(model.centroids, [3, 4]); + assert.deepEqual(model.assignments, [0, 0, 0]); + assert.equal(model.mse, 16 / 3); + const predicted = await invoke('/predict', { data: [1, 1, 9, 9], dimensions: 2, centroids: [0, 0, 10, 10] }); + assert.deepEqual(await predicted.json(), { assignments: [0, 1] }); + assert.equal((await invoke('/fit', {}, 'Bearer incorrect')).status, 401); + assert.equal((await invoke('/fit', { data: [1, 2], dimensions: 0, options: { clusters: 1 } })).status, 422); +}); + +test('R2 codebook helpers use the real local binding and Vectorize contract remains explicit', { timeout: 60_000 }, async t => { + const temporary = await mkdtemp(join(tmpdir(), 'e-means-r2-workerd-')); + const entry = join(temporary, 'entry.mjs'); + const adapter = fileURLToPath(new URL('../integrations/cloudflare.mjs', import.meta.url)); + await writeFile(entry, ` +import { persistCodebook, loadCodebook } from ${JSON.stringify(adapter)}; +export default { async fetch(request, env) { + const original = { dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]) }; + const receipt = await persistCodebook(env.CODEBOOKS, 'test/codebook', original); + const restored = await loadCodebook(env.CODEBOOKS, 'test/codebook'); + return Response.json({ receipt, centroids: Array.from(restored.centroids), clusters: restored.clusters }); +} }; +`); + const artifact = await buildWorker(join(temporary, 'out'), entry); + const worker = new Miniflare({ ...config, modulesRoot: join(temporary, 'out'), scriptPath: artifact.script, r2Buckets: ['CODEBOOKS'] }); + t.after(async () => { await worker.dispose(); await rm(temporary, { recursive: true, force: true }); }); + const response = await worker.dispatchFetch('https://worker.test/storage'); + assert.equal(response.status, 200, await response.clone().text()); + const result = await response.json(); + assert.deepEqual(result.centroids, [1, 2, 3, 4]); + assert.equal(result.clusters, 2); + const bucket = await worker.getR2Bucket('CODEBOOKS'); + const stored = JSON.parse(await (await bucket.get('test/codebook')).text()); + assert.equal(stored.schema, 'ruvector.e-means-codebook/1'); + assert.equal(Object.hasOwn(stored, 'assignments'), false); +}); diff --git a/npm/packages/e-means/test/cloudflare.test.mjs b/npm/packages/e-means/test/cloudflare.test.mjs new file mode 100644 index 0000000000..7c081e83fb --- /dev/null +++ b/npm/packages/e-means/test/cloudflare.test.mjs @@ -0,0 +1,96 @@ +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { test } from 'node:test'; +import { createClusteringWorker, WORKER_LIMITS } from '../integrations/cloudflare.mjs'; + +const wasmModule = new WebAssembly.Module(await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url))); +const token = 'e-means-test-token-not-for-production'; +const valid = { data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dimensions: 2, + options: { clusters: 1, epochs: 2, batchSize: 2, seed: 42 } }; +const handler = createClusteringWorker({ wasmModule, bearerToken: token }); +function request(path, body, authorization = `Bearer ${token}`, headers = {}) { + return new Request(`https://worker.test${path}`, { method: 'POST', + headers: { 'content-type': 'application/json', authorization, ...headers }, body: JSON.stringify(body) }); +} + +test('Worker fits and predicts with the real precompiled Rust WASM module', async () => { + const response = await handler.fetch(request('/fit', valid)); + assert.equal(response.status, 200); + const fitted = await response.json(); + assert.deepEqual(fitted.centroids, [5, 6]); + assert.deepEqual(fitted.assignments, [0, 0, 0, 0, 0]); + assert.equal(fitted.mse, 16); + assert.equal(fitted.updates, 6); + const predicted = await handler.fetch(request('/predict', { data: [2, 2, 8, 8], dimensions: 2, centroids: [1, 1, 9, 9] })); + assert.deepEqual(await predicted.json(), { assignments: [0, 1] }); + const empty = await handler.fetch(request('/predict', { data: [], dimensions: 2, centroids: [1, 1] })); + assert.deepEqual(await empty.json(), { assignments: [] }); + assert.equal(response.headers.get('cache-control'), 'no-store'); + assert.equal(response.headers.get('x-content-type-options'), 'nosniff'); +}); + +test('authentication fails closed and request fields cannot bypass it', async () => { + const unavailable = createClusteringWorker({ wasmModule }); + assert.equal((await unavailable.fetch(request('/fit', valid))).status, 503); + assert.equal((await handler.fetch(request('/fit', valid, 'Bearer incorrect'))).status, 401); + const health = await unavailable.fetch(new Request('https://worker.test/health')); + assert.equal(health.status, 200); + assert.equal((await health.json()).authenticatedOperations, false); + assert.equal((await handler.fetch(request('/fit', { ...valid, allowUnauthenticated: true }))).status, 422); + const local = createClusteringWorker({ wasmModule, allowUnauthenticated: true }); + assert.equal((await local.fetch(request('/fit', valid, ''))).status, 200); +}); + +test('shape, numeric, option, method and conservative work limits reject requests', async () => { + for (const body of [ + { ...valid, data: [] }, { ...valid, data: [1, 2, 3] }, + { ...valid, data: ['1', 2] }, { ...valid, data: [1e40, 2] }, + { ...valid, dimensions: 0 }, { ...valid, dimensions: WORKER_LIMITS.maxDimensions + 1 }, + { ...valid, options: { clusters: 0 } }, { ...valid, options: { clusters: 6 } }, + { ...valid, options: { clusters: 1, epochs: 0 } }, + { ...valid, options: { clusters: 1, batchSize: 0 } }, + { ...valid, options: { clusters: 1, peakStep: 0 } }, + { ...valid, options: { clusters: 1, seed: -1 } }, + { ...valid, options: { clusters: 1, finalization: 'slow' } }, + { ...valid, options: { clusters: 1, unknown: 1 } }, + ]) assert.equal((await handler.fetch(request('/fit', body))).status, 422, JSON.stringify(body)); + const limited = createClusteringWorker({ wasmModule, bearerToken: token, maxWork: 1 }); + assert.equal((await limited.fetch(request('/fit', valid))).status, 413); + assert.equal((await limited.fetch(request('/predict', { data: [1, 2], dimensions: 1, centroids: [0, 1] }))).status, 413); + // Assignment-only accounting would allow this ~4M-unit request; donor + // revival at every fifth batch makes the actual upper bound much larger. + assert.equal((await handler.fetch(request('/fit', { data: Array(256).fill(0), dimensions: 1, + options: { clusters: 256, epochs: 32, batchSize: 1 } }))).status, 413); + assert.equal((await handler.fetch(new Request('https://worker.test/fit'))).status, 405); + assert.equal((await handler.fetch(request('/fit?namespace=another-user', valid))).status, 400); + assert.equal((await handler.fetch(request('/persist', valid))).status, 404); + assert.equal((await handler.fetch(request('/fit', valid, `Bearer ${token}`, { 'content-type': 'text/plain' }))).status, 415); +}); + +test('streamed bodies have actual byte limits, strict UTF-8 parsing and read deadlines', async () => { + const small = createClusteringWorker({ wasmModule, bearerToken: token, maxRequestBytes: 32 }); + let cancelled = false; + const oversized = new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array(33)); }, cancel() { cancelled = true; } }); + const response = await small.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: oversized, duplex: 'half' })); + assert.equal(response.status, 413); + assert.equal(cancelled, true); + const malformed = await handler.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: new Uint8Array([0xff]) })); + assert.equal(malformed.status, 400); + const quick = createClusteringWorker({ wasmModule, bearerToken: token, bodyTimeoutMs: 20 }); + const stalled = new ReadableStream({ start() {}, cancel() {} }); + const timeout = await quick.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: stalled, duplex: 'half' })); + assert.equal(timeout.status, 408); + const contentLength = await handler.fetch(request('/fit', valid, `Bearer ${token}`, { 'content-length': '999999999' })); + assert.equal(contentLength.status, 413); +}); + +test('Worker configuration is explicit and bounded', () => { + for (const options of [ + {}, { wasmModule: new Uint8Array() }, { wasmModule, bearerToken: 'short' }, + { wasmModule, maxWork: Infinity }, { wasmModule, maxRequestBytes: WORKER_LIMITS.maxRequestBytes + 1 }, + { wasmModule, allowUnauthenticated: 'true' }, { wasmModule, bodyTimeoutMs: 0 }, + ]) assert.throws(() => createClusteringWorker(options)); +}); diff --git a/npm/packages/e-means/test/e-means.test.mjs b/npm/packages/e-means/test/e-means.test.mjs new file mode 100644 index 0000000000..36b4a25f64 --- /dev/null +++ b/npm/packages/e-means/test/e-means.test.mjs @@ -0,0 +1,135 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { test } from 'node:test'; +import { init, fit, predict } from '../e-means.mjs'; + +test('numerical operations require completed initialization', () => { + const moduleUrl = new URL('../e-means.mjs', import.meta.url).href; + const child = spawnSync(process.execPath, ['--input-type=module', '-e', ` + import assert from 'node:assert/strict'; + import { fit, predict } from ${JSON.stringify(moduleUrl)}; + assert.throws(() => fit(new Float32Array([0]), 1, { clusters: 1 }), /await init/); + assert.throws(() => predict(new Float32Array([0]), 1, new Float32Array([0])), /await init/); + `], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); +}); + +test('initialization failure is retryable and concurrent calls share the runtime', async () => { + const moduleUrl = new URL('../e-means.mjs', import.meta.url).href; + const child = spawnSync(process.execPath, ['--input-type=module', '-e', ` + import assert from 'node:assert/strict'; + import { init, fit } from ${JSON.stringify(moduleUrl)}; + await assert.rejects(init(new Uint8Array([0, 1, 2])), /Could not initialize/); + await Promise.all([init(), init()]); + assert.equal(fit(new Float32Array([1, 3]), 1, { clusters: 1 }).centroids[0], 2); + `], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); +}); + +await init(); + +test('last-epoch mean uses every row, including a partial final batch', () => { + const data = new Float32Array([1, 2, 3, 4]); + const original = data.slice(); + const model = fit(data, 1, { clusters: 1, epochs: 1, batchSize: 3, peakStep: 1 }); + assert.deepEqual(data, original); + assert.deepEqual(model.centroids, new Float32Array([2.5])); + assert.deepEqual(model.assignments, new Uint32Array([0, 0, 0, 0])); + assert.equal(model.mse, 1.25); + assert.equal(model.updates, 2); + assert.equal(model.batchSize, 3); + assert.equal(model.dimensions, 1); +}); + +test('shared native/WASM golden case agrees on the exact codebook and diagnostics', () => { + const model = fit(new Float32Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), 2, + { clusters: 1, epochs: 2, batchSize: 2, seed: 42 }); + assert.deepEqual([...model.centroids], [5, 6]); + assert.deepEqual([...model.assignments], [0, 0, 0, 0, 0]); + assert.equal(model.mse, 16); + assert.equal(model.updates, 6); + assert.equal(model.batchSize, 2); +}); + +test('EMA maintains decayed sums and counts across unequal batch sizes', () => { + const model = fit(new Float32Array([0, 1, 9]), 1, + { clusters: 1, epochs: 1, batchSize: 2, peakStep: 1, finalization: 'ema', seed: 42 }); + // At t=1 of M=2, alpha=.55. Denominator is .45*2+.55*1=1.45. + // Enumerate the three possible final rows so the oracle is independent of shuffle order. + const possible = [3.103448275862069, 3.1724137931034484, 3.724137931034483]; + const center = model.centroids[0]; + assert.ok(possible.some((expected) => Math.abs(expected - center) < 1e-6), `center ${center}`); + assert.ok(Math.abs(model.mse - ([0, 1, 9].reduce((sum, x) => sum + (x - center) ** 2, 0) / 3)) < 1e-10); +}); + +test('separated clusters reconstruct accurately and output labels match the final codebook', () => { + const data = new Float32Array(256 * 2); + for (let i = 0; i < 256; ++i) { + const center = i < 128 ? -10 : 10; + data[i * 2] = center + (i % 5) * 0.01; + data[i * 2 + 1] = center - (i % 7) * 0.01; + } + const options = { clusters: 2, epochs: 4, batchSize: 32, seed: 7 }; + const model = fit(data, 2, options); + assert.ok(model.mse < 0.01, `MSE ${model.mse}`); + assert.deepEqual(model.assignments, predict(data, 2, model.centroids)); + assert.notEqual(model.assignments[0], model.assignments[128]); + assert.deepEqual(fit(data, 2, options), model, 'same seed reproduces the same fit'); + assert.equal(model.centroids.length, 4); + for (const v of model.centroids) assert.ok(Number.isFinite(v)); +}); + +test('nearest centroid handles ties, empty queries and f32 extreme values', () => { + const centroids = new Float32Array([-1, 1]); + assert.deepEqual(predict(new Float32Array([-2, 0, 2]), 1, centroids), new Uint32Array([0, 0, 1])); + assert.deepEqual(predict(new Float32Array(), 1, centroids), new Uint32Array()); + const large = new Float32Array([-3e38, 3e38]); + const model = fit(large, 1, { clusters: 1, epochs: 1 }); + assert.equal(model.centroids[0], 0); + assert.ok(Number.isFinite(model.mse)); +}); + +test('duplicate and zero vectors never create nonfinite centroids', () => { + for (const finalization of ['lastEpochMean', 'ema']) { + const data = new Float32Array(96); + const model = fit(data, 3, { clusters: 8, epochs: 3, batchSize: 2, peakStep: 1, finalization }); + assert.equal(model.centroids.length, 24); + assert.equal(model.mse, 0); + for (const v of model.centroids) assert.ok(Number.isFinite(v)); + } +}); + +test('invalid shapes, nonfinite input and malformed config reject before WASM coercion', () => { + const data = new Float32Array([0, 1]); + const config = { clusters: 1 }; + for (const bad of [0, -1, 1.5, NaN, Infinity, 2 ** 32, '1']) { + assert.throws(() => fit(data, bad, config), /dimensions/); + } + for (const bad of [[], [0, 1], new Float64Array([0, 1]), null]) { + assert.throws(() => fit(bad, 1, config), /Float32Array/); + } + assert.throws(() => fit(new Float32Array(), 1, config), /complete/); + assert.throws(() => fit(new Float32Array([1, 2, 3]), 2, config), /complete/); + for (const bad of [NaN, Infinity, -Infinity]) { + assert.throws(() => fit(new Float32Array([0, bad]), 1, config), /finite/); + assert.throws(() => predict(data, 1, new Float32Array([bad])), /finite/); + } + for (const key of ['clusters', 'epochs', 'batchSize']) { + for (const bad of [0, -1, 0.5, NaN, Infinity, 2 ** 32, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, [key]: bad }), new RegExp(key)); + } + } + assert.throws(() => fit(data, 1, { clusters: 3 }), /number of vectors/); + for (const bad of [0, -1, 2, NaN, Infinity, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, peakStep: bad }), /peakStep/); + } + for (const bad of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1, NaN, Infinity, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, seed: bad }), /seed/); + } + for (const bad of [undefined, null, [], 1, 'config']) { + assert.throws(() => fit(data, 1, bad), /options/); + } + assert.throws(() => fit(data, 1, { ...config, finalization: 'slowEma' }), /finalization/); + assert.throws(() => fit(data, 1, { ...config, epohs: 3 }), /Unknown option/); + assert.throws(() => predict(data, 1, new Float32Array()), /complete/); +}); diff --git a/npm/packages/e-means/test/ecosystem-consumers.mjs b/npm/packages/e-means/test/ecosystem-consumers.mjs new file mode 100644 index 0000000000..3136e26e6d --- /dev/null +++ b/npm/packages/e-means/test/ecosystem-consumers.mjs @@ -0,0 +1,99 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const repository = fileURLToPath(new URL('../../../../', import.meta.url)); +const packageRoot = fileURLToPath(new URL('../', import.meta.url)); +const temporary = await mkdtemp(join(tmpdir(), 'e-means-ecosystem-')); +function run(command, args, cwd = temporary) { + const result = spawnSync(command, args, { + cwd, encoding: 'utf8', timeout: 180_000, + env: { ...process.env, npm_config_workspaces: 'false' }, + }); + assert.equal(result.status, 0, `${command} ${args.join(' ')}\n${result.stdout}\n${result.stderr}`); + return result.stdout; +} +try { + await writeFile(join(temporary, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + const packages = [ + { path: packageRoot, check: true }, + { path: join(repository, 'npm/packages/core') }, + { path: join(repository, 'npm/packages/ruvector') }, + { path: join(repository, 'npm/packages/all') }, + { path: join(repository, 'crates/ruvector-wasm') }, + ]; + const archives = []; + for (const item of packages) { + const args = ['pack', '--json', '--workspaces=false', '--pack-destination', temporary]; + // The shared artifact's normal prepack executes its actual WASM. Consumer + // prepack lanes build unrelated database SDKs; this test qualifies only the + // newly shipped clustering subpaths, not those packages' legacy root builds. + if (!item.check) args.push('--ignore-scripts'); + const [packed] = JSON.parse(run('npm', args, item.path)); + const paths = packed.files.map(file => file.path); + if (item.check) { + for (const name of ['runtime.mjs', 'wasm/ruvector_e_means_bg.wasm', 'integrations/metaharness.mjs', 'integrations/cloudflare.mjs']) { + assert.ok(paths.includes(name), `missing shared artifact ${name}`); + } + } else { + for (const name of ['clustering.mjs', 'clustering.d.mts', 'clustering/quantization.mjs', 'clustering/ivf.mjs', 'clustering/metaharness.mjs', 'clustering/cloudflare.mjs']) { + assert.ok(paths.includes(name), `missing consumer artifact ${name}`); + } + } + archives.push(join(temporary, packed.filename)); + } + run('npm', ['install', '--ignore-scripts', '--omit=optional', '--no-audit', '--no-fund', ...archives]); + await writeFile(join(temporary, 'consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { readFile } from 'node:fs/promises'; + const cases = [ + ['@ruvector/core/clustering.mjs', '@ruvector/core/clustering/'], + ['ruvector/clustering.mjs', 'ruvector/clustering/'], + ['@ruvector/all/clustering.mjs', '@ruvector/all/clustering/'], + ['@ruvector/wasm/clustering', '@ruvector/wasm/clustering/'], + ]; + for (const [root, prefix] of cases) { + const extension = root.endsWith('.mjs') ? '.mjs' : ''; + const core = await import(root); + await core.init(); + const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); + const quantization = await import(prefix + 'quantization' + extension); + const book = quantization.trainProductQuantizer(data, 2, 2, { clusters: 1, epochs: 1 }); + const codes = quantization.encodeProductQuantizer(book, data); + assert.ok(codes instanceof Uint8Array); + assert.deepEqual([...quantization.decodeProductQuantizer(book, codes)], [5,6,5,6,5,6,5,6]); + const ivf = await import(prefix + 'ivf' + extension); + const partitions = ivf.partition(data, 2, { clusters: 1 }); + assert.deepEqual([...ivf.postingList(partitions, 0)], [0,1,2,3]); + const meta = await import(prefix + 'metaharness' + extension); + const evaluator = meta.createClusteringEvaluator({ training: data, + holdout: new Float32Array([5,6]), dimensions: 2, + baseline: { clusters: 1, epochs: 1, batchSize: 4 }, + domain: { batchSize: { min: 1, max: 4, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 1, maxDistanceCoordinates: 100000, timeoutMs: 30000 } }); + const score = await evaluator.evaluate(evaluator.baselineGenome, 'installed-baseline'); + assert.equal(score.raw.holdoutMse, 0); + const edge = await import(prefix + 'cloudflare' + extension); + const bytes = await readFile(new URL(import.meta.resolve('@ruvector/e-means/wasm'))); + const wasmModule = await WebAssembly.compile(bytes); + const token = 'local-installed-consumer-test-token'; + const worker = edge.createClusteringWorker({ wasmModule, bearerToken: token }); + const response = await worker.fetch(new Request('https://local.test/fit', { + method: 'POST', headers: { authorization: 'Bearer ' + token, 'content-type': 'application/json' }, + body: JSON.stringify({ data: [1,2,3,4], dimensions: 2, options: { clusters: 1 } }), + })); + assert.equal(response.status, 200); + assert.deepEqual((await response.json()).centroids, [2,3]); + console.log(root + ': PQ, IVF, heldout evaluator and Worker facades passed'); + } + `); + process.stdout.write(run(process.execPath, ['consumer.mjs'])); + const installed = JSON.parse(await readFile(join(temporary, 'node_modules/@ruvector/e-means/package.json'))); + assert.equal(installed.version, '0.1.0'); + console.log('Installed ecosystem subpaths passed; consumer root/prepack release lanes were not qualified'); +} finally { + await rm(temporary, { recursive: true, force: true }); +} diff --git a/npm/packages/e-means/test/ivf.test.mjs b/npm/packages/e-means/test/ivf.test.mjs new file mode 100644 index 0000000000..9e8d09acdd --- /dev/null +++ b/npm/packages/e-means/test/ivf.test.mjs @@ -0,0 +1,60 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { init, fit, predict } from '@ruvector/e-means'; +import { partition, postingList } from '@ruvector/e-means/ivf'; + +await init(); + +const data = new Float32Array([-10, -9, 10, 9, -9, -10, 9, 10, -11, -9, 11, 9]); +const options = { clusters: 2, epochs: 6, batchSize: 3, seed: 42 }; + +test('IVF partitions use shared fit results and stable exact assignment posting lists', () => { + const before = data.slice(); + const result = partition(data, 2, options); + const shared = fit(data, 2, options); + assert.equal(result.schema, 'ruvector-e-means-ivf-v1'); + assert.deepEqual(result.model.centroids, shared.centroids); + assert.deepEqual(result.model.assignments, predict(data, 2, shared.centroids)); + assert.equal(result.offsets.length, 3); + assert.equal(result.offsets[0], 0); + assert.equal(result.offsets[2], 6); + assert.deepEqual(Array.from(result.indices).sort((a, b) => a - b), [0, 1, 2, 3, 4, 5]); + for (let cluster = 0; cluster < 2; cluster++) { + const expected = Array.from({ length: 6 }, (_, row) => row).filter(row => shared.assignments[row] === cluster); + assert.deepEqual(Array.from(postingList(result, cluster)), expected); + } + assert.deepEqual(data, before); +}); + +test('IVF handles empty clusters and returns independent posting-list storage', () => { + const result = partition(new Float32Array(16).fill(1), 2, { clusters: 4, epochs: 1, batchSize: 8 }); + assert.deepEqual(Array.from(postingList(result, 0)), [0, 1, 2, 3, 4, 5, 6, 7]); + for (let cluster = 1; cluster < 4; cluster++) assert.deepEqual(postingList(result, cluster), new Uint32Array()); + const list = postingList(result, 0); + list.fill(99); + assert.equal(result.indices[0], 0); + assert.deepEqual(postingList(structuredClone(result), 0), postingList(result, 0)); +}); + +test('IVF rejects malformed training data and mutated partition records', () => { + assert.throws(() => partition(new Float32Array([1, NaN]), 2, { clusters: 1 })); + assert.throws(() => partition(new Float32Array([1]), 2, { clusters: 1 })); + assert.throws(() => partition(data, 2, { clusters: 0 })); + const result = partition(data, 2, options); + for (const cluster of [-1, 2, 0.5, NaN]) assert.throws(() => postingList(result, cluster)); + for (const mutation of [ + value => { value.schema = 'unknown'; }, + value => { value.offsets = value.offsets.slice(1); }, + value => { value.offsets[0] = 1; }, + value => { value.offsets[1] = 99; }, + value => { value.indices[0] = 99; }, + value => { value.indices[1] = value.indices[0]; }, + value => { value.model.assignments[value.indices[0]] = 99; }, + value => { value.model.centroids[0] = NaN; }, + value => { value.model.mse = NaN; }, + ]) { + const bad = structuredClone(result); + mutation(bad); + assert.throws(() => postingList(bad, 0)); + } +}); diff --git a/npm/packages/e-means/test/metaharness.test.mjs b/npm/packages/e-means/test/metaharness.test.mjs new file mode 100644 index 0000000000..51a3756bd3 --- /dev/null +++ b/npm/packages/e-means/test/metaharness.test.mjs @@ -0,0 +1,128 @@ +import assert from 'node:assert/strict'; +import { mkdtemp, readdir, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { test } from 'node:test'; +import { createClusteringEvaluator, tuneClustering } from '../integrations/metaharness.mjs'; +import { evolveNumeric } from '@metaharness/darwin'; + +function options(extra = {}) { + return { + training: new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]), + holdout: new Float32Array([0, 1, 10, 11]), dimensions: 2, + baseline: { clusters: 2, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { clusters: { min: 1, max: 2, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 3, maxDistanceCoordinates: 100_000, timeoutMs: 30_000 }, + ...extra, + }; +} + +test('real WASM measures a separate holdout and flags quality regressions', async () => { + const evaluator = createClusteringEvaluator(options()); + const baseline = await evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + assert.equal(baseline.raw.trainMse, 1); + assert.equal(baseline.raw.holdoutMse, 0); + assert.equal(baseline.primary, 1); + assert.equal(baseline.regressed, false); + const candidate = await evaluator.evaluate({ clusters: 1 }, 'candidate'); + assert.equal(candidate.raw.holdoutMse, 50); + assert.equal(candidate.raw.baselineHoldoutMse, 0); + assert.equal(candidate.primary, 1 / 51); + assert.equal(candidate.regressed, true); + assert.ok(Number.isFinite(candidate.raw.fitMs) && candidate.raw.fitMs >= 0); + assert.ok(Number.isFinite(candidate.raw.holdoutMs) && candidate.raw.holdoutMs >= 0); + assert.equal(evaluator.receipt().sourceApplied, false); +}); + +test('inputs/configuration snapshot before awaits and receipts cannot mutate evidence', async () => { + const supplied = options(); + supplied.training.slice = () => supplied.training; + supplied.holdout.slice = () => supplied.holdout; + const evaluator = createClusteringEvaluator(supplied); + const pending = evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + supplied.training.fill(999); supplied.holdout.fill(999); + supplied.baseline.clusters = 1; supplied.domain.clusters.min = 2; + supplied.budget.maxEvaluations = 0; + const score = await pending; + assert.equal(score.raw.holdoutMse, 0); + score.raw.holdoutMse = 999; + const receipt = evaluator.receipt(); + receipt.trials[0].score.raw.holdoutMse = 999; + receipt.domain.clusters.min = 2; + receipt.baselineConfig.clusters = 99; + assert.equal(evaluator.receipt().baseline.score.raw.holdoutMse, 0); + assert.equal(evaluator.receipt().domain.clusters.min, 1); + assert.equal(evaluator.receipt().baselineConfig.clusters, 2); + assert.equal((await evaluator.evaluate({ clusters: 1 }, 'candidate')).raw.holdoutMse, 50); +}); + +test('admission rejects invalid splits, unbounded domains and oversized work before training', () => { + const badCases = [ + options({ holdout: new Float32Array() }), + options({ holdout: new Float32Array([NaN, 1]) }), + options({ dimensions: 0 }), + options({ domain: {} }), + options({ domain: { clusters: { min: 1, max: Infinity, type: 'int', scale: 'linear' } } }), + options({ domain: { clusters: { min: 1, max: 5, type: 'int', scale: 'linear' } } }), + options({ domain: { batchSize: { min: 1, max: 4, type: 'float', scale: 'linear' } } }), + options({ domain: { peakStep: { min: 0.1, max: 1, type: 'float', scale: 'log', default: 0.1 } } }), + options({ baseline: { clusters: 2, epochs: 2, batchSize: 0 } }), + options({ baseline: { clusters: 2, epochs: null } }), + options({ baseline: { clusters: 2, seed: null } }), + options({ budget: { maxEvaluations: 0, maxDistanceCoordinates: 10_000 } }), + options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 1 } }), + options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 1e10 } }), + options({ baseline: { clusters: 2, epochs: 0xffff_ffff, batchSize: 1 } }), + options({ qualityTolerance: -1 }), + options({ qualityTolerance: null }), + ]; + for (const value of badCases) assert.throws(() => createClusteringEvaluator(value)); + const overlapping = options(); overlapping.holdout = overlapping.training.subarray(0, 4); + assert.throws(() => createClusteringEvaluator(overlapping), /nonoverlapping/); + assert.throws(() => createClusteringEvaluator(options({ training: new Float32Array(16_777_217) })), /64 MiB/); +}); + +test('evaluation dispatch, domain, concurrency and cooperative deadline limits are enforced', async () => { + const evaluator = createClusteringEvaluator(options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 100_000 } })); + const pending = evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + await assert.rejects(evaluator.evaluate(evaluator.baselineGenome, 'parallel'), /Concurrent/); + await pending; + await assert.rejects(evaluator.evaluate({ clusters: 1 }, 'second'), /budget exhausted/); + const firstCandidate = createClusteringEvaluator(options()); + await assert.rejects(firstCandidate.evaluate({ clusters: 1 }, 'wrong-first'), /baselineGenome/); + await assert.rejects(firstCandidate.evaluate({ clusters: 99 }, 'outside'), /clusters/); + const expired = createClusteringEvaluator(options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 100_000, timeoutMs: 1 } })); + await new Promise(resolve => setTimeout(resolve, 10)); + await assert.rejects(expired.evaluate(expired.baselineGenome, 'expired'), /deadline/); +}); + +test('published Darwin evolveNumeric accepts the real clustering evaluator', async () => { + const evaluator = createClusteringEvaluator(options()); + const archive = await mkdtemp(join(tmpdir(), 'e-means-sdk-test-')); + try { + const result = await evolveNumeric({ genomeSpec: evaluator.domain, baselineGenome: evaluator.baselineGenome, + evaluator, generations: 1, childrenPerGeneration: 2, seed: 7, concurrency: 1, workRoot: archive }); + assert.equal(result.records.length, 3); + assert.equal(result.baseline.score.raw.holdoutMse, 0); + assert.equal(evaluator.receipt().dispatchCount, 3); + assert.ok(result.records.every(record => Number.isFinite(record.score.primary))); + } finally { await rm(archive, { recursive: true, force: true }); } +}); + +test('bounded tuneClustering uses Darwin0.13.0, validates evidence and removes its archive', async () => { + const before = new Set((await readdir(tmpdir())).filter(name => name.startsWith('e-means-darwin-'))); + const supplied = options({ generations: 1, childrenPerGeneration: 2, mutationSeed: 7 }); + const result = await tuneClustering(supplied); + assert.deepEqual(result.engine, { package: '@metaharness/darwin', version: '0.13.0', algorithm: 'evolveNumeric' }); + assert.equal(result.schema, 'e-means.clustering-tuning/1'); + assert.equal(result.trials.length, 3); + assert.equal(result.dispatchCount, 3); + assert.equal(result.baseline.score.raw.holdoutMse, 0); + assert.equal(result.sourceApplied, false); + assert.equal(result.temporaryArchiveRemoved, true); + assert.ok(result.consumedWork <= result.budget.maxDistanceCoordinates); + assert.ok(result.winner.score.primary >= result.baseline.score.primary); + assert.deepEqual(supplied.training, options().training); + assert.equal((await readdir(tmpdir())).filter(name => name.startsWith('e-means-darwin-') && !before.has(name)).length, 0); + await assert.rejects(tuneClustering(options({ generations: 8, childrenPerGeneration: 8 })), /worst-case dispatches/); +}); diff --git a/npm/packages/e-means/test/packed-consumer.mjs b/npm/packages/e-means/test/packed-consumer.mjs new file mode 100644 index 0000000000..5bc838f64e --- /dev/null +++ b/npm/packages/e-means/test/packed-consumer.mjs @@ -0,0 +1,88 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const packageDir = fileURLToPath(new URL('../', import.meta.url)); +const temp = await mkdtemp(join(tmpdir(), 'e-means-consumer-')); +function run(command, args, cwd = temp) { + const result = spawnSync(command, args, { cwd, encoding: 'utf8', env: { ...process.env, npm_config_workspaces: 'false' } }); + assert.equal(result.status, 0, `${command} ${args.join(' ')}\n${result.stdout}\n${result.stderr}`); + return result.stdout; +} +try { + const pack = JSON.parse(run('npm', ['pack', '--json', '--pack-destination', temp, '--workspaces=false'], packageDir)); + const files = pack[0].files.map((entry) => entry.path); + assert.ok(files.includes('wasm/ruvector_e_means_bg.wasm')); + assert.ok(files.includes('wasm/ruvector_e_means.js')); + assert.ok(files.includes('e-means.d.ts')); + for (const path of ['runtime.mjs', 'runtime.d.ts', 'integrations/metaharness.mjs', 'integrations/metaharness.d.ts', 'integrations/clustering-validation.mjs']) { + assert.ok(files.includes(path), `archive missing ${path}`); + } + assert.ok(!files.some((path) => path.endsWith('.rs') || path.includes('node_modules'))); + await writeFile(join(temp, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + run('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--offline', join(temp, pack[0].filename)]); + await writeFile(join(temp, 'consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { init, fit, predict } from '@ruvector/e-means'; + import { createClusteringEvaluator, tuneClustering } from '@ruvector/e-means/metaharness'; + import { fit as runtimeFit } from '@ruvector/e-means/runtime'; + await init(); + const data = new Float32Array([1, 1, 3, 3]); + const result = fit(data, 2, { clusters: 1 }); + assert.deepEqual([...result.centroids], [2, 2]); + assert.equal(result.mse, 2); + assert.deepEqual([...predict(data, 2, result.centroids)], [0, 0]); + assert.equal(runtimeFit(data, 2, { clusters: 1 }).mse, 2); + const evaluation = { training: new Float32Array([0,0,0,2,10,10,10,12]), holdout: new Float32Array([0,1,10,11]), dimensions:2, + baseline:{clusters:2,epochs:2,batchSize:2,peakStep:0.5}, domain:{clusters:{min:1,max:2,type:'int',scale:'linear'}}, + budget:{maxEvaluations:3,maxDistanceCoordinates:100000} }; + const evaluator = createClusteringEvaluator(evaluation); + assert.equal((await evaluator.evaluate(evaluator.baselineGenome, 'baseline')).raw.holdoutMse, 0); + await assert.rejects(tuneClustering({...evaluation,generations:1,childrenPerGeneration:2}), /optional peer/); + console.log('Installed archive runtime/evaluator passed without the optional SDK'); + `); + process.stdout.write(run(process.execPath, ['consumer.mjs'])); + const installed = JSON.parse(await readFile(join(temp, 'node_modules/@ruvector/e-means/package.json'))); + assert.equal(installed.version, '0.1.0'); + // Cached pinned registry packages only: installation and qualification do not + // execute dependency lifecycle scripts or contact the registry. + run('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '@metaharness/darwin@0.13.0', 'typescript@5.9.3']); + await writeFile(join(temp, 'meta-consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { tuneClustering } from '@ruvector/e-means/metaharness'; + import { evolveNumeric } from '@metaharness/darwin'; + assert.equal(typeof evolveNumeric, 'function'); + const result = await tuneClustering({ + training:new Float32Array([0,0,0,2,10,10,10,12]), holdout:new Float32Array([0,1,10,11]), dimensions:2, + baseline:{clusters:2,epochs:2,batchSize:2,peakStep:0.5}, domain:{clusters:{min:1,max:2,type:'int',scale:'linear'}}, + budget:{maxEvaluations:3,maxDistanceCoordinates:100000}, generations:1,childrenPerGeneration:2 }); + assert.equal(result.engine.version,'0.13.0'); + assert.equal(result.trials.length,3); + assert.equal(result.baseline.score.raw.holdoutMse,0); + assert.equal(result.sourceApplied,false); + assert.equal(result.temporaryArchiveRemoved,true); + console.log('Offline installed MetaHarness/WASM consumer passed'); + `); + process.stdout.write(run(process.execPath, ['meta-consumer.mjs'])); + await writeFile(join(temp, 'types.mts'), ` + import {createClusteringEvaluator,tuneClustering,type ClusteringEvaluationOptions} from '@ruvector/e-means/metaharness'; + import {init,fit} from '@ruvector/e-means/runtime'; + const config:ClusteringEvaluationOptions={training:new Float32Array([0,1]),holdout:new Float32Array([2]),dimensions:1, + baseline:{clusters:1,epochs:1},domain:{epochs:{min:1,max:2,type:'int',scale:'linear'}},budget:{maxEvaluations:2,maxDistanceCoordinates:1000}}; + const evaluator=createClusteringEvaluator(config); + const result=await tuneClustering({...config,generations:1,childrenPerGeneration:1}); + const notApplied:false=result.sourceApplied; + await init(new WebAssembly.Module(new Uint8Array())); + const assignments:Uint32Array=fit(config.training,1,config.baseline).assignments; + void [evaluator,notApplied,assignments]; + // @ts-expect-error explicit source required by Node-free runtime + await init(); + `); + run(process.execPath, ['node_modules/typescript/bin/tsc', '--noEmit', '--strict', '--target', 'es2022', '--module', 'nodenext', '--moduleResolution', 'nodenext', '--lib', 'es2022,dom', 'types.mts']); + console.log('Offline installed integration declarations passed'); +} finally { + await rm(temp, { recursive: true, force: true }); +} diff --git a/npm/packages/e-means/test/quantization-types.mts b/npm/packages/e-means/test/quantization-types.mts new file mode 100644 index 0000000000..67fa682ea2 --- /dev/null +++ b/npm/packages/e-means/test/quantization-types.mts @@ -0,0 +1,19 @@ +import { type EMeansOptions } from '@ruvector/e-means'; +import { + trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, + productQuantizerToJSON, productQuantizerFromJSON, type ProductQuantizer, +} from '@ruvector/e-means/quantization'; +import { partition, postingList, type IVFPartition } from '@ruvector/e-means/ivf'; + +const data = new Float32Array([1, 2, 3, 4]); +const options: EMeansOptions = { clusters: 1 }; +const pq: ProductQuantizer = trainProductQuantizer(data, 2, 2, options); +const codes: Uint8Array = encodeProductQuantizer(pq, data); +const restored: Float32Array = decodeProductQuantizer(productQuantizerFromJSON(productQuantizerToJSON(pq)), codes); +const ivf: IVFPartition = partition(restored, 2, options); +const posting: Uint32Array = postingList(ivf, 0); +void posting; +// @ts-expect-error byte codes are required +decodeProductQuantizer(pq, new Uint32Array()); +// @ts-expect-error float32 input vectors are required +trainProductQuantizer([1, 2], 2, 1, options); diff --git a/npm/packages/e-means/test/quantization.test.mjs b/npm/packages/e-means/test/quantization.test.mjs new file mode 100644 index 0000000000..65b1f5da53 --- /dev/null +++ b/npm/packages/e-means/test/quantization.test.mjs @@ -0,0 +1,114 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { init, fit, predict } from '@ruvector/e-means'; +import { + trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, + productQuantizerToJSON, productQuantizerFromJSON, +} from '@ruvector/e-means/quantization'; + +await init(); + +const data = new Float32Array([1, 2, 10, 11, 1, 2, 20, 21, 3, 4, 10, 11, 3, 4, 20, 21]); +const options = { clusters: 2, epochs: 8, batchSize: 4, peakStep: 0.5, seed: 42 }; + +test('product quantization trains exact shared codebooks and reconstructs representable vectors', () => { + const before = data.slice(); + const model = trainProductQuantizer(data, 4, 2, options); + assert.equal(model.schema, 'ruvector-e-means-pq-v1'); + assert.equal(model.centroids.length, 8); + const codes = encodeProductQuantizer(model, data); + assert.ok(codes instanceof Uint8Array); + assert.equal(codes.length, 8); + assert.deepEqual(decodeProductQuantizer(model, codes), data); + assert.deepEqual(data, before); + assert.deepEqual(trainProductQuantizer(data, 4, 2, options).centroids, model.centroids); + for (let subspace = 0; subspace < 2; subspace++) { + const subvectors = Float32Array.from({ length: 8 }, (_, index) => data[Math.floor(index / 2) * 4 + subspace * 2 + index % 2]); + const shared = fit(subvectors, 2, options); + const start = subspace * 4; + assert.deepEqual(model.centroids.slice(start, start + 4), shared.centroids); + const assignments = predict(subvectors, 2, shared.centroids); + for (let row = 0; row < 4; row++) assert.equal(codes[row * 2 + subspace], assignments[row]); + } +}); + +test('one-cluster subspaces have arithmetic-mean codebooks and support empty codecs', () => { + const model = trainProductQuantizer(data, 4, 2, { clusters: 1, batchSize: 3 }); + assert.deepEqual(Array.from(model.centroids), [2, 3, 15, 16]); + assert.deepEqual(encodeProductQuantizer(model, new Float32Array()), new Uint8Array()); + assert.deepEqual(decodeProductQuantizer(model, new Uint8Array()), new Float32Array()); + assert.deepEqual(Array.from(decodeProductQuantizer(model, new Uint8Array([0, 0]))), [2, 3, 15, 16]); +}); + +test('all subspaces use one snapshot of caller configuration', () => { + let reads = 0; + const model = trainProductQuantizer(data, 4, 2, { + get clusters() { reads++; return reads === 1 ? 1 : 2; }, + batchSize: 3, + }); + assert.equal(reads, 1); + assert.equal(model.clusters, 1); + assert.deepEqual(Array.from(model.centroids), [2, 3, 15, 16]); +}); + +test('codebooks survive JSON and structured clone with independent ownership', () => { + const model = trainProductQuantizer(data, 4, 2, options); + const json = productQuantizerToJSON(model); + const restored = productQuantizerFromJSON(JSON.parse(JSON.stringify(json))); + assert.deepEqual(restored.centroids, model.centroids); + assert.notEqual(restored.centroids, model.centroids); + const clone = structuredClone(model); + assert.deepEqual(encodeProductQuantizer(clone, data), encodeProductQuantizer(model, data)); + restored.centroids.fill(0); + json.centroids.fill(0); + assert.ok(model.centroids.some(value => value !== 0)); +}); + +test('256-centroid codebooks preserve the full byte range', () => { + const model = { + schema: 'ruvector-e-means-pq-v1', dimensions: 1, subspaces: 1, clusters: 256, + centroids: Float32Array.from({ length: 256 }, (_, index) => index), + }; + const input = new Float32Array([0, 255, 254]); + const codes = encodeProductQuantizer(model, input); + assert.deepEqual(Array.from(codes), [0, 255, 254]); + assert.deepEqual(decodeProductQuantizer(model, codes), input); +}); + +test('product quantization rejects invalid shapes, values, configuration and byte codes', () => { + for (const [dimensions, subspaces, clusters] of [[0, 1, 1], [4, 0, 1], [4, 3, 1], [4, 5, 1], [4, 2, 0], [4, 2, 257], [4, 2, 5]]) { + assert.throws(() => trainProductQuantizer(data, dimensions, subspaces, { clusters })); + } + assert.throws(() => trainProductQuantizer(data, 4, 2, { clusters: 2, epochs: 0 })); + assert.throws(() => trainProductQuantizer(data, 4, 2, { ...options, unknown: true })); + assert.throws(() => trainProductQuantizer([1, 2, 3, 4], 4, 2, { clusters: 1 })); + assert.throws(() => trainProductQuantizer(new Float32Array([1, NaN, 3, 4]), 4, 2, { clusters: 1 })); + const model = trainProductQuantizer(data, 4, 2, options); + assert.throws(() => encodeProductQuantizer(model, new Float32Array([1]))); + assert.throws(() => encodeProductQuantizer(model, new Float32Array([1, 2, 3, Infinity]))); + assert.throws(() => decodeProductQuantizer(model, new Uint32Array([0, 0]))); + assert.throws(() => decodeProductQuantizer(model, new Uint8Array([0]))); + assert.throws(() => decodeProductQuantizer(model, new Uint8Array([0, 2]))); +}); + +test('every operation revalidates caller-owned codebooks and JSON values', () => { + const model = trainProductQuantizer(data, 4, 2, options); + for (const mutation of [ + value => { value.schema = 'unknown'; }, + value => { value.subspaces = 3; }, + value => { value.clusters = 257; }, + value => { value.centroids = value.centroids.slice(1); }, + value => { value.centroids[0] = NaN; }, + ]) { + const bad = structuredClone(model); + mutation(bad); + assert.throws(() => encodeProductQuantizer(bad, data)); + assert.throws(() => decodeProductQuantizer(bad, new Uint8Array([0, 0]))); + assert.throws(() => productQuantizerToJSON(bad)); + } + for (const coordinate of ['1', NaN, Infinity, 1e100, undefined]) { + const json = productQuantizerToJSON(model); + json.centroids[0] = coordinate; + assert.throws(() => productQuantizerFromJSON(json)); + } +}); diff --git a/npm/packages/e-means/test/runtime.test.mjs b/npm/packages/e-means/test/runtime.test.mjs new file mode 100644 index 0000000000..70e7a96d5e --- /dev/null +++ b/npm/packages/e-means/test/runtime.test.mjs @@ -0,0 +1,40 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { test } from 'node:test'; + +test('compiled-module runtime and plain imports load no Node builtins or Darwin SDK', async () => { + const temp = await mkdtemp(join(tmpdir(), 'e-means-runtime-')); + try { + const bytes = await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url)); + const loader = 'data:text/javascript,' + encodeURIComponent(` + export async function resolve(specifier, context, next) { + if (specifier.startsWith('node:') || specifier.includes('@metaharness/darwin')) { + throw new Error('Unexpected Node/SDK import: ' + specifier); + } + return next(specifier, context); + } + `); + const file = join(temp, 'consumer.mjs'); + await writeFile(file, ` + const runtime = await import(${JSON.stringify(new URL('../runtime.mjs', import.meta.url).href)}); + let rejected = false; + try { await runtime.init(); } catch (error) { rejected = /requires WASM bytes/.test(error.message); } + if (!rejected) throw new Error('Runtime must reject an omitted source before initialization'); + const bytes = Uint8Array.from(atob(${JSON.stringify(bytes.toString('base64'))}), character => character.charCodeAt(0)); + const module = new WebAssembly.Module(bytes); + await Promise.all([runtime.init(module), runtime.init(module)]); + const result = runtime.fit(new Float32Array([0, 2]), 1, { clusters: 1 }); + if (result.centroids[0] !== 1 || result.mse !== 1) throw new Error('Compiled module fit differs'); + await import(${JSON.stringify(new URL('../e-means.mjs', import.meta.url).href)}); + const integration = await import(${JSON.stringify(new URL('../integrations/metaharness.mjs', import.meta.url).href)}); + if (typeof integration.createClusteringEvaluator !== 'function') throw new Error('Evaluator export missing'); + console.log('Node-free runtime and lazy SDK imports passed'); + `); + const child = spawnSync(process.execPath, ['--experimental-loader', loader, file], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); + assert.match(child.stdout, /Node-free runtime/); + } finally { await rm(temp, { recursive: true, force: true }); } +}); diff --git a/npm/packages/e-means/test/tsconfig.json b/npm/packages/e-means/test/tsconfig.json new file mode 100644 index 0000000000..29ec5a0a8c --- /dev/null +++ b/npm/packages/e-means/test/tsconfig.json @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noEmit": true, + "lib": ["ES2022", "DOM"], + "types": [] + }, + "include": ["*.ts", "*.mts"] +} diff --git a/npm/packages/e-means/test/typed-bridge.test.mjs b/npm/packages/e-means/test/typed-bridge.test.mjs new file mode 100644 index 0000000000..11e14a2d4c --- /dev/null +++ b/npm/packages/e-means/test/typed-bridge.test.mjs @@ -0,0 +1,70 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { init, fit } from '../e-means.mjs'; +import initWasm, { fitJson, fitTyped, FittedModel } from '../wasm/ruvector_e_means.js'; + +await init(); +const runtime = await initWasm(); +const samples = new Float32Array([0, 1, 0, 2, 10, 12, 10, 13, -9, -10, -9, -11]); + +test('typed result transport matches JSON transport for both finalizers', () => { + for (const finalization of ['lastEpochMean', 'ema']) { + const options = { clusters: 3, epochs: 3, batchSize: 2, seed: 7, finalization }; + const json = JSON.parse(fitJson(samples, 2, JSON.stringify(options))); + assert.deepEqual(fit(samples, 2, options), { + ...json, + centroids: Float32Array.from(json.centroids), + assignments: Uint32Array.from(json.assignments), + }); + } +}); + +test('consumed outputs are caller-owned and survive handle release and WASM memory growth', () => { + const handle = fitTyped(samples, 2, JSON.stringify({ clusters: 3, epochs: 2 })); + let centroids, assignments; + try { + centroids = handle.takeCentroids(); + assignments = handle.takeAssignments(); + assert.deepEqual(handle.takeCentroids(), new Float32Array()); + assert.deepEqual(handle.takeAssignments(), new Uint32Array()); + assert.notEqual(centroids.buffer, runtime.memory.buffer); + assert.notEqual(assignments.buffer, runtime.memory.buffer); + } finally { + handle.free(); + } + const expectedCentroids = centroids.slice(), expectedAssignments = assignments.slice(); + runtime.memory.grow(1); + fit(samples, 2, { clusters: 2 }); + assert.deepEqual(centroids, expectedCentroids); + assert.deepEqual(assignments, expectedAssignments); +}); + +test('the wrapper frees its model handle after success and output-copy failure', () => { + const originalTake = FittedModel.prototype.takeAssignments; + const originalFree = FittedModel.prototype.free; + let frees = 0; + FittedModel.prototype.free = function () { frees++; return originalFree.call(this); }; + try { + assert.equal(fit(samples, 2, { clusters: 2 }).assignments.length, 6); + assert.equal(frees, 1); + FittedModel.prototype.takeAssignments = function () { throw new Error('injected output-copy failure'); }; + assert.throws(() => fit(samples, 2, { clusters: 2 }), /injected output-copy failure/); + assert.equal(frees, 2); + } finally { + FittedModel.prototype.takeAssignments = originalTake; + FittedModel.prototype.free = originalFree; + } + assert.equal(fit(samples, 2, { clusters: 2 }).assignments.length, 6); +}); + +test('repeated fits release WASM model allocations instead of accumulating them', () => { + const data = Float32Array.from({ length: 4096 }, (_, i) => (i % 17) / 17); + const config = { clusters: 1, epochs: 1, batchSize: 128 }; + for (let i = 0; i < 8; i++) fit(data, 1, config); + const afterWarmup = runtime.memory.buffer.byteLength; + for (let i = 0; i < 128; i++) { + const model = fit(data, 1, config); + assert.equal(model.assignments.length, data.length); + } + assert.equal(runtime.memory.buffer.byteLength, afterWarmup, 'WASM allocation high-water mark must plateau'); +}); diff --git a/npm/packages/e-means/test/types.ts b/npm/packages/e-means/test/types.ts new file mode 100644 index 0000000000..e463a2c7d4 --- /dev/null +++ b/npm/packages/e-means/test/types.ts @@ -0,0 +1,32 @@ +import { init, fit, predict, type EMeansModel, type EMeansOptions } from '@ruvector/e-means'; +import { init as initRuntime } from '@ruvector/e-means/runtime'; +import { createClusteringEvaluator, tuneClustering, type ClusteringEvaluationOptions } from '@ruvector/e-means/metaharness'; + +const options: EMeansOptions = { clusters: 2, epochs: 3, finalization: 'lastEpochMean' }; +await init(); +const model: EMeansModel = fit(new Float32Array([0, 0, 1, 1]), 2, options); +const assignments: Uint32Array = predict(new Float32Array([2, 2]), 2, model.centroids); +void assignments; +// @ts-expect-error missing required cluster count +fit(new Float32Array(), 1, { epochs: 3 }); +// @ts-expect-error row storage must be Float32Array +fit([0, 1], 1, options); +// @ts-expect-error unsupported finalization policy +fit(new Float32Array(), 1, { clusters: 1, finalization: 'slowEma' }); + +await initRuntime(new WebAssembly.Module(new Uint8Array())); +// @ts-expect-error Node-free runtime requires an explicit source +await initRuntime(); +const evaluation: ClusteringEvaluationOptions = { + training: new Float32Array([0, 1]), holdout: new Float32Array([2]), dimensions: 1, + baseline: { clusters: 1, epochs: 1 }, + domain: { epochs: { min: 1, max: 2, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 2, maxDistanceCoordinates: 1000 }, +}; +const evaluator = createClusteringEvaluator(evaluation); +await evaluator.evaluate(evaluator.baselineGenome, 'baseline'); +const tuned = await tuneClustering({ ...evaluation, generations: 1, childrenPerGeneration: 1 }); +const neverApplied: false = tuned.sourceApplied; +void neverApplied; +// @ts-expect-error tuning requires a finite explicit evaluation budget +createClusteringEvaluator({ training: new Float32Array(), holdout: new Float32Array(), dimensions: 1, baseline: options, domain: {} }); diff --git a/npm/packages/e-means/wasm-module.d.ts b/npm/packages/e-means/wasm-module.d.ts new file mode 100644 index 0000000000..b439be05df --- /dev/null +++ b/npm/packages/e-means/wasm-module.d.ts @@ -0,0 +1,3 @@ +/** Statically compiled module supplied by a Worker-aware bundler such as Wrangler. */ +declare const module: WebAssembly.Module; +export default module; diff --git a/npm/packages/e-means/wasm/ruvector_e_means.d.ts b/npm/packages/e-means/wasm/ruvector_e_means.d.ts new file mode 100644 index 0000000000..c63fbfba3d --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means.d.ts @@ -0,0 +1,83 @@ +/* tslint:disable */ +/* eslint-disable */ + +/** + * A temporary owner for one fit result. JavaScript takes independent output + * arrays and then frees this handle, releasing any vectors not taken. + */ +export class FittedModel { + private constructor(); + free(): void; + [Symbol.dispose](): void; + /** + * Cluster indices fit u32 because wasm32 arrays and sample counts do. + */ + takeAssignments(): Uint32Array; + /** + * wasm-bindgen copies the returned vector into a caller-owned Float32Array + * before freeing its Rust allocation. No view into WASM memory escapes. + */ + takeCentroids(): Float32Array; + readonly batchSize: number; + readonly dimensions: number; + readonly mse: number; + readonly peakStep: number; + readonly revivedClusters: number; + readonly updates: number; +} + +/** + * Compatibility transport and an independent parity oracle for typed output. + */ +export function fitJson(data: Float32Array, dimensions: number, config_json: string): string; + +/** + * Only the small configuration crosses JSON; result vectors stay numeric. + */ +export function fitTyped(data: Float32Array, dimensions: number, config_json: string): FittedModel; + +export function predictFlat(data: Float32Array, dimensions: number, centroids: Float32Array): Uint32Array; + +export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module; + +export interface InitOutput { + readonly memory: WebAssembly.Memory; + readonly __wbg_fittedmodel_free: (a: number, b: number) => void; + readonly fitJson: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly fitTyped: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly fittedmodel_batchSize: (a: number) => number; + readonly fittedmodel_dimensions: (a: number) => number; + readonly fittedmodel_mse: (a: number) => number; + readonly fittedmodel_peakStep: (a: number) => number; + readonly fittedmodel_revivedClusters: (a: number) => number; + readonly fittedmodel_takeAssignments: (a: number, b: number) => void; + readonly fittedmodel_takeCentroids: (a: number, b: number) => void; + readonly fittedmodel_updates: (a: number) => number; + readonly predictFlat: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly __wbindgen_add_to_stack_pointer: (a: number) => number; + readonly __wbindgen_export: (a: number, b: number) => number; + readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number; + readonly __wbindgen_export3: (a: number, b: number, c: number) => void; +} + +export type SyncInitInput = BufferSource | WebAssembly.Module; + +/** + * Instantiates the given `module`, which can either be bytes or + * a precompiled `WebAssembly.Module`. + * + * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated. + * + * @returns {InitOutput} + */ +export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput; + +/** + * If `module_or_path` is {RequestInfo} or {URL}, makes a request and + * for everything else, calls `WebAssembly.instantiate` directly. + * + * @param {{ module_or_path: InitInput | Promise }} module_or_path - Passing `InitInput` directly is deprecated. + * + * @returns {Promise} + */ +export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise } | InitInput | Promise): Promise; diff --git a/npm/packages/e-means/wasm/ruvector_e_means.js b/npm/packages/e-means/wasm/ruvector_e_means.js new file mode 100644 index 0000000000..ba3256a488 --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means.js @@ -0,0 +1,456 @@ +/* @ts-self-types="./ruvector_e_means.d.ts" */ + +/** + * A temporary owner for one fit result. JavaScript takes independent output + * arrays and then frees this handle, releasing any vectors not taken. + */ +export class FittedModel { + static __wrap(ptr) { + const obj = Object.create(FittedModel.prototype); + obj.__wbg_ptr = ptr; + FittedModelFinalization.register(obj, obj.__wbg_ptr, obj); + return obj; + } + __destroy_into_raw() { + const ptr = this.__wbg_ptr; + this.__wbg_ptr = 0; + FittedModelFinalization.unregister(this); + return ptr; + } + free() { + const ptr = this.__destroy_into_raw(); + wasm.__wbg_fittedmodel_free(ptr, 0); + } + /** + * @returns {number} + */ + get batchSize() { + const ret = wasm.fittedmodel_batchSize(this.__wbg_ptr); + return ret >>> 0; + } + /** + * @returns {number} + */ + get dimensions() { + const ret = wasm.fittedmodel_dimensions(this.__wbg_ptr); + return ret >>> 0; + } + /** + * @returns {number} + */ + get mse() { + const ret = wasm.fittedmodel_mse(this.__wbg_ptr); + return ret; + } + /** + * @returns {number} + */ + get peakStep() { + const ret = wasm.fittedmodel_peakStep(this.__wbg_ptr); + return ret; + } + /** + * @returns {number} + */ + get revivedClusters() { + const ret = wasm.fittedmodel_revivedClusters(this.__wbg_ptr); + return ret >>> 0; + } + /** + * Cluster indices fit u32 because wasm32 arrays and sample counts do. + * @returns {Uint32Array} + */ + takeAssignments() { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + wasm.fittedmodel_takeAssignments(retptr, this.__wbg_ptr); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var v1 = getArrayU32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v1; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } + } + /** + * wasm-bindgen copies the returned vector into a caller-owned Float32Array + * before freeing its Rust allocation. No view into WASM memory escapes. + * @returns {Float32Array} + */ + takeCentroids() { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + wasm.fittedmodel_takeCentroids(retptr, this.__wbg_ptr); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var v1 = getArrayF32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v1; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } + } + /** + * @returns {number} + */ + get updates() { + const ret = wasm.fittedmodel_updates(this.__wbg_ptr); + return ret >>> 0; + } +} +if (Symbol.dispose) FittedModel.prototype[Symbol.dispose] = FittedModel.prototype.free; + +/** + * Compatibility transport and an independent parity oracle for typed output. + * @param {Float32Array} data + * @param {number} dimensions + * @param {string} config_json + * @returns {string} + */ +export function fitJson(data, dimensions, config_json) { + let deferred4_0; + let deferred4_1; + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_export, wasm.__wbindgen_export2); + const len1 = WASM_VECTOR_LEN; + wasm.fitJson(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true); + var ptr3 = r0; + var len3 = r1; + if (r3) { + ptr3 = 0; len3 = 0; + throw takeObject(r2); + } + deferred4_0 = ptr3; + deferred4_1 = len3; + return getStringFromWasm0(ptr3, len3); + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + wasm.__wbindgen_export3(deferred4_0, deferred4_1, 1); + } +} + +/** + * Only the small configuration crosses JSON; result vectors stay numeric. + * @param {Float32Array} data + * @param {number} dimensions + * @param {string} config_json + * @returns {FittedModel} + */ +export function fitTyped(data, dimensions, config_json) { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_export, wasm.__wbindgen_export2); + const len1 = WASM_VECTOR_LEN; + wasm.fitTyped(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + if (r2) { + throw takeObject(r1); + } + return FittedModel.__wrap(r0); + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } +} + +/** + * @param {Float32Array} data + * @param {number} dimensions + * @param {Float32Array} centroids + * @returns {Uint32Array} + */ +export function predictFlat(data, dimensions, centroids) { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passArrayF32ToWasm0(centroids, wasm.__wbindgen_export); + const len1 = WASM_VECTOR_LEN; + wasm.predictFlat(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true); + if (r3) { + throw takeObject(r2); + } + var v3 = getArrayU32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v3; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } +} +function __wbg_get_imports() { + const import0 = { + __proto__: null, + __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) { + const ret = Error(getStringFromWasm0(arg0, arg1)); + return addHeapObject(ret); + }, + __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) { + throw new Error(getStringFromWasm0(arg0, arg1)); + }, + }; + return { + __proto__: null, + "./ruvector_e_means_bg.js": import0, + }; +} + +const FittedModelFinalization = (typeof FinalizationRegistry === 'undefined') + ? { register: () => {}, unregister: () => {} } + : new FinalizationRegistry(ptr => wasm.__wbg_fittedmodel_free(ptr, 1)); + +function addHeapObject(obj) { + if (heap_next === heap.length) heap.push(heap.length + 1); + const idx = heap_next; + heap_next = heap[idx]; + + heap[idx] = obj; + return idx; +} + +function dropObject(idx) { + if (idx < 1028) return; + heap[idx] = heap_next; + heap_next = idx; +} + +function getArrayF32FromWasm0(ptr, len) { + ptr = ptr >>> 0; + return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len); +} + +function getArrayU32FromWasm0(ptr, len) { + ptr = ptr >>> 0; + return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len); +} + +let cachedDataViewMemory0 = null; +function getDataViewMemory0() { + if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) { + cachedDataViewMemory0 = new DataView(wasm.memory.buffer); + } + return cachedDataViewMemory0; +} + +let cachedFloat32ArrayMemory0 = null; +function getFloat32ArrayMemory0() { + if (cachedFloat32ArrayMemory0 === null || cachedFloat32ArrayMemory0.byteLength === 0) { + cachedFloat32ArrayMemory0 = new Float32Array(wasm.memory.buffer); + } + return cachedFloat32ArrayMemory0; +} + +function getStringFromWasm0(ptr, len) { + return decodeText(ptr >>> 0, len); +} + +let cachedUint32ArrayMemory0 = null; +function getUint32ArrayMemory0() { + if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) { + cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer); + } + return cachedUint32ArrayMemory0; +} + +let cachedUint8ArrayMemory0 = null; +function getUint8ArrayMemory0() { + if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) { + cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer); + } + return cachedUint8ArrayMemory0; +} + +function getObject(idx) { return heap[idx]; } + +let heap = new Array(1024).fill(undefined); +heap.push(undefined, null, true, false); + +let heap_next = heap.length; + +function passArrayF32ToWasm0(arg, malloc) { + const ptr = malloc(arg.length * 4, 4) >>> 0; + getFloat32ArrayMemory0().set(arg, ptr / 4); + WASM_VECTOR_LEN = arg.length; + return ptr; +} + +function passStringToWasm0(arg, malloc, realloc) { + if (realloc === undefined) { + const buf = cachedTextEncoder.encode(arg); + const ptr = malloc(buf.length, 1) >>> 0; + getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf); + WASM_VECTOR_LEN = buf.length; + return ptr; + } + + let len = arg.length; + let ptr = malloc(len, 1) >>> 0; + + const mem = getUint8ArrayMemory0(); + + let offset = 0; + + for (; offset < len; offset++) { + const code = arg.charCodeAt(offset); + if (code > 0x7F) break; + mem[ptr + offset] = code; + } + if (offset !== len) { + if (offset !== 0) { + arg = arg.slice(offset); + } + ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0; + const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len); + const ret = cachedTextEncoder.encodeInto(arg, view); + + offset += ret.written; + ptr = realloc(ptr, len, offset, 1) >>> 0; + } + + WASM_VECTOR_LEN = offset; + return ptr; +} + +function takeObject(idx) { + const ret = getObject(idx); + dropObject(idx); + return ret; +} + +let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }); +cachedTextDecoder.decode(); +const MAX_SAFARI_DECODE_BYTES = 2146435072; +let numBytesDecoded = 0; +function decodeText(ptr, len) { + numBytesDecoded += len; + if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) { + cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }); + cachedTextDecoder.decode(); + numBytesDecoded = len; + } + return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len)); +} + +const cachedTextEncoder = new TextEncoder(); + +if (!('encodeInto' in cachedTextEncoder)) { + cachedTextEncoder.encodeInto = function (arg, view) { + const buf = cachedTextEncoder.encode(arg); + view.set(buf); + return { + read: arg.length, + written: buf.length + }; + }; +} + +let WASM_VECTOR_LEN = 0; + +let wasmModule, wasmInstance, wasm; +function __wbg_finalize_init(instance, module) { + wasmInstance = instance; + wasm = instance.exports; + wasmModule = module; + cachedDataViewMemory0 = null; + cachedFloat32ArrayMemory0 = null; + cachedUint32ArrayMemory0 = null; + cachedUint8ArrayMemory0 = null; + return wasm; +} + +async function __wbg_load(module, imports) { + if (typeof Response === 'function' && module instanceof Response) { + if (typeof WebAssembly.instantiateStreaming === 'function') { + try { + return await WebAssembly.instantiateStreaming(module, imports); + } catch (e) { + const validResponse = module.ok && expectedResponseType(module.type); + + if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') { + console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e); + + } else { throw e; } + } + } + + const bytes = await module.arrayBuffer(); + return await WebAssembly.instantiate(bytes, imports); + } else { + const instance = await WebAssembly.instantiate(module, imports); + + if (instance instanceof WebAssembly.Instance) { + return { instance, module }; + } else { + return instance; + } + } + + function expectedResponseType(type) { + switch (type) { + case 'basic': case 'cors': case 'default': return true; + } + return false; + } +} + +function initSync(module) { + if (wasm !== undefined) return wasm; + + + if (module !== undefined) { + if (Object.getPrototypeOf(module) === Object.prototype) { + ({module} = module) + } else { + console.warn('using deprecated parameters for `initSync()`; pass a single object instead') + } + } + + const imports = __wbg_get_imports(); + if (!(module instanceof WebAssembly.Module)) { + module = new WebAssembly.Module(module); + } + const instance = new WebAssembly.Instance(module, imports); + return __wbg_finalize_init(instance, module); +} + +async function __wbg_init(module_or_path) { + if (wasm !== undefined) return wasm; + + + if (module_or_path !== undefined) { + if (Object.getPrototypeOf(module_or_path) === Object.prototype) { + ({module_or_path} = module_or_path) + } else { + console.warn('using deprecated parameters for the initialization function; pass a single object instead') + } + } + + if (module_or_path === undefined) { + module_or_path = new URL('ruvector_e_means_bg.wasm', import.meta.url); + } + const imports = __wbg_get_imports(); + + if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) { + module_or_path = fetch(module_or_path); + } + + const { instance, module } = await __wbg_load(await module_or_path, imports); + + return __wbg_finalize_init(instance, module); +} + +export { initSync, __wbg_init as default }; diff --git a/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm new file mode 100644 index 0000000000000000000000000000000000000000..b7189ea79886279d6e846cbac12b89ffc94efcc0 GIT binary patch literal 142782 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≠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�_5ZB|klv#J=!xq=+sP&L#H^+F@i+}~{eYcc+x`v0%R^550f@At=`LzM=`y^ewXPZ)v(|6nkqh%`n( zu?O$X|G^%-PA84+Q0$SusMH_+*#IMBC58u#$ioo6c7CK0Suh9&UN`)U<6wNv-W|N2 z`WIH@QPqECLmKIz3_b|hYS{kuTWWLc*y^7To&4(%X^`c&pTC7BWJ`I+>*ViX=j%kF z%^@$!z}MyreA4S|ii1FJHwPau@JISX8qr3^5dC~SNn^>IgV^H71LeRbjqK!&B*43Q zFazM93Ttyb*~2OH_pqBCxilzok-Csl*srUbDUlv9*fR8Uk@R8mw{R8dq_R8v$}l2ejb zQczMQd3e_mQ$8jR!~+{R#H}0R#8?}R#R42kyDXZQBYA-QBqM>QBhG< zQBzS@l~a`muh|tK}M98#xYf=oev_JZpU{D;s$*bIgK{r@lczx@kD@qatWe-++;G@Act;D6=jKN`*d ze*^#TP(c43^6($6LH`{J=>O&6zueUSN9)pmH1Pi>CmB2f{4ciyLrwQrYl1hz81J#> zfBCYlhDPNlp{M*x<;0<6yNsG(-ehzjea!hMoFeYCcfVii-{xb`*ZVPSiMPtYL);&` zC-|{@jD7diMTIH6{*ueb{ry3PA}jEh7VVN}=YHzu3!QywF&&D!y1>Z%FeK1a-{X~m zg;KJvVNO|jh{qXLd<@+y58c@ei~DB%7Hu9mUBYRdZOk4jQ`4nqr|RSHKaf(_=J|@c zdONG^)q(=sz|U~110S!)oE^Dq)>W-N*!BI*Q=#K&B2|`OTsQL57V?t!AANne!Oyclq0(Tde!^1$`#a9JHpH$8l?||OWt&(jZM283Y|QVu^R&1st@6aB zvRZ;|t9G!DPy|!%ZO-mTF9i3g)iRoQN?tq^Rd5OZvCG}osL*VC3ohB`%r(n&+>*UO_zKcQ(}5`!_=+kRI|Bp zwA$;p*vo5&K9%stKXr#(y1R+*^Im>9HlJe9`|E+I+vPEu zFN(vd$J<|hQ0RGPW83eDPfX7<=35bc7F9T+c|0x(XP#Fu^X<4#^ZTc-jc*t8?V4=f zRW7@jRDF0gmDjdc^o_{;n=H-w!`*dOp)6XbEvf5YQ4<~qO`j6E!^zos)w{!yZclR1 zA=j&3SBHmAcG9e!?6H!~DnrrI(6S%0THhOCrLU~H^x{MDxM<3u<;yp{xQyY);g9l| zuJ~3@G_-Nk6z1#J_>7QNrrvUznk^#(z#ol;m3S-96dJW*|Cs+K`*~&Mk*IuBJU?gO_Ylz zn#IIy57}rlA?}wqp3)kh5_c3)ws`QXNaeZp4OSz@tlax5AI=AJC&b46$j#woy{qjV zdnDX^RD4`CpgD5*@aLX0{9cY%uW{!nzd^0o6~lwy_~5;Y0qGNtQ1~~H0Ru^=JygyqIGk*9Jn{4Li_-WD@@Q24hSiO)#C><-sm)4P*J4mHQQrrhr3>v# zJ6!t0*F;(!-uw01HWd-d-bKfF@%=nQ4c4arXyJEu0VfemNHU zEQvqUQ%ok^<;QykqZ5N3(RF5Tuf67JgcdG5xbUnezMx3FuZyAROZ42yn`_N6rR~pd z;i6fd3E6pCaT98a`j$`GPzxN6_6T+0l5d+SZq2XO#0IFyee7JdB?gzLFSh2N#W5SK zzP+z`x01cTc7D-7dKbI-O6JVtg(PV#GiRu{H=>ir`q1V z%$gd7ma&eJ3rlKR%vwp9;TI`7O)>ARebsg*vD4l#e7UQ}q(US+C>ghP=1t1rVVaA> zBCo16pK=!Uye$2d@M=67KX85TcoT058vo))*ikM@%%5 zF<5gb=Jnz*PD_{B5yU=~Z+v+@K>@Qr^+;ahvlm=q2E&inB(&o`%+KnGKTP}}cmB}N zh{e=TM`k3S-wpYmykj^kuiJ8~+^>Lpr$4_^kV|FLcnII**HSTc|5%u;-BgpCIR7wD zth4o#!O(bp2|J_h_w2jPzpOQwDkR=rXMW4laI5L_T-}ddFWCbu7++;@I=}xaSmmg6 zY&SRa`KR0Nbzku~r!;jR8l+?KHX#By*u^R?@> zbVHw7Mj5$&rd9YgPR4zn+j*|Q|LwVv#oHE)ZcZ+O(?=Q-P5K(Pd>fH6Yu)kC%~j6d z+%Lxez=h-$R*ffH^mO@pCigp<2orBE=TI+Q&U`)|bKU-=h-c+n^#{iFMn4VT`;}OA zXSeP-6H}k6kldK$ae(>zsfgOk6^>2{+OlQdxU1%VS1;Pdzap-$GlZMr+v5Tg4B<7_ zcoiF)38?@a@w4efw(e?92}ZSESdDp?R6)tL)q|Q*&mUv1OU1Jv{rPCuCjx8S?CBMu z&u{(r<>Y;TV?%H0Tyd@O>quX(?T&}HpVu?ZXlHkoisn*bmr~^U+s3mddhTtQ`bOOLV^V-ML?*3(H-zt=Hb3Ia(j2 z;c@(}R}Rle;87!q>|ai7H1Ue2XYLDIvd&+)eeXxqktCPqV#ygP8O!OD1?~Z}ob@_t zyWVCE@f@z*U({0ib$HCgh>N9>b1@gmk4 zGAz790c_p)hUks*(yBXm8ZAUvGjmVTf3khh&$3ncqnqdSg&!Lqn9}kuJg%7ip7PLP zk#AW$rQ>$YT3xn>f6c9kn&Mw+a>RnMCdUY)-r;v|t$Kglj;I`C_;H_J>grjKG7Y`3 zxn~}iGH=T;*Be*0nLX{x@q8F>5NsRP?|A8TeQ7w=gC{4xBpF9|Vr}db{B~D44)E+` zmbSY1r0s`BSuHpXF z2hY3rn5d`pTwFQj*!=3l3EB7->#;=N*3)5EPtNTJcBti{`S_jit0C$GO?3g0hNZ5K2HxAdE98vyp+iTJx!w3 z?7a7p6Za;p-awU8=bm>r4Y7RaQbPKXads>(lRI9ot8TKa<HSZOrgM^!AxBhZx3&dMt|T3;GuL{%|LbA2M?o;# z`0|Z;VGr6&p-Z&PK#5IH5ew*EMMv7ja_gp_0EB&b>D(_IBP94NPzqh*tL?nI(WgBYzIKjlVU z6nbN7(Bf*B+g)|+%gWUj-HLRV{%@^!we@oSMwhQ|rSWLAeSCrIrOVSR3D1TYZ9B0O z4Ru6;rw{KXOhAWN)pqO@b`hC&)x1?cAq-2fBZL={un# z(HLn1p)EOL+;4}RQh#|G%8&i>U}t>rYmWNth9$RS=jBxH$8Y*(RHTzCwPl3}kw$)_ z!5InVvA?PY81K1v@xEp_HrbdpX?m|KexkPJ3d_!koa+#68cqw#E;yx5SpX%7^8iGCQ< zoOcmFo3C5+`OoSYc%{WT@5rvo%MlB5C_P_lTolR*eI7pYFtWxhg5{p66}{z_W?S={ zC*EChd|QJRzF-#kT{)nti+DdAs>NH~Q*2A^Nq)7s71`SWU_8 zkC={+xtm1PpUi7W{)jo27k2h;s@|=t%v9TjV4k*lovqU@w_flaQN5)$XMRmpCd1|n z{65iH_VGI-Pmi|IrbbP9yCn7kg65t|Vc}qI&$6>8)o*Z7)8nl#OjVc*Ju#aedNL?z zoSv*q{G1&ac>ECCBv0ZYnK!|@uS_EQGX33hMMTOc?)LUSryU!*Qd9< zb6H%~-y?Oq`_w?UZ$ehjWVHM$oApl{y{jpxePy9B+X{DR<|%*w+1DYbU%+ZP=1oK2 z0mXc~ld!gGmbk_HQb*FR$dQct=K+^bDw+2bICGj8;+&z(y8s}bz_zD2OrP8 zxRH?k6C?CJhBzFfVX7Hu@Qm$#o}O~3U$%SZBeAoY=b=2Whv!anGHPM#18byyHbz5F z=hYmBS(4gB%x1#h1eg@?UO-!SeC1gE@nVvTIn$APyeam3Q!&rI#l-7&=j%=y^G%H_ zc=mprke8&g;>}E*$voF{Mc-aVVMAkgZIOyXd2mBZ!pr5m>-TAnec1Qte%ARZ_R@N}NGI*a*PFWr)Y-4QrTx6$KTYgj|MZr7U*b^)1OGc0 zuGgyQ+W4N4lRN(_5$`I$+HDuh9Nbkwh-g%iq;FYk(hD2!&wB7`FSi>eC|!YY$IbI5 zmZ%!fSo5%Dcb;~!aO_U*ot2ME%y|72hoXBJC7rg8T5{GuFD=@y!)n+1Li7EBlndT0 zF%zQl)RjC(9q|L#dh1HKey#S0fKb$|B+2v|B*!& z|AC{kbN+z^n(qGti+jxc123V@|H(S_`i*}w)Ag5M{^aeSV>ABX=tY4~cmCi4`7)c2 ze=z33Q|{D1__0jW)tbLp2RzZyzWa;6oWTe`Ir|seS3dq4QuUjo!#L|j2VVc?^h$4q zkobh(TzeR=&EZ=1n+vDAy184BWdWqEAeK$X?%$QMS-2L!AhpRWk3pbjMe+wCeGt zO%|BLe%!0VvQ_o*CX0KvagVfGypR2{$qG-7Gka=e)3WA~SSL#BHapeR@NOWpiEK<) z_6WS)b&sosI7i}_@qCMk^mj~hgR&8hHeh3w|7tQ?q|MfZaDn+C=i0V$uG9ltzamUs z(PMRAwWqh?`D`Y_;~j-ZtFUOSSX)IsK%L73l}Erd@+wsU+J3`#sOy&qg2`aMc$d(k zsNt*g`V80qMyCeZ>u*c-;(| znXNm=PyvM*hGFO@Q(dDcDvH$l`lDaJ$}vnY^3$C=@zvSkTAazw_$bLY#XApr?l0ES zqAL*@bg`*RPtSFt8tpOJ)6?tKqx z=-nl^no9q?seTXjHQ8sfGuy_CP|Fg?6y#-X&lWbZGY6%iXl>n!)#fE{HWU(!^@ z)Mx5m1>QA~WJxt!8@+8{)n4Yf_r+(9y6h9BO>b?DHFziQGmfP{lV3NQFhA2YoLE$J zgO&G=?tNm8Lq&xLTg9_|d6tf&&!wj$wX(C@rp^}l+SW&=T-7?%GtSGmT3XeftmgEt zx^s_&zRmS*nk<9MH{;jYhwoorV6A7E-CglyRhsRA^jTH?5Kjd+W$)~zaP>i%yOo$j z*;G-jExT8KzDY<6`#gY~2!CoFpg6Sl=1XmErG65#JQDh*%|$fSRNJDkrlX-q?Z}pl2H5wo zXio)=_1dRr@jljfL{WREL+ohVj#^ho*J6*!Tb?>_=#_eE@O2I!hYKrlu`F znEhzJXia!O{ZZAW&P77jb1~Oa@K}6Oz|3i=ZzPnMaH9Ff#JtN5=JIRNxFfHpCQ^L4 z9B1G+=d-#5cKI-Txn&ujzOJO3I6M@^mV%{`e>YR2wBz)_a`u;3j?5YDA!biLfB0;4 z{3X{@D&NX2mpv~l2TUk(~#22hZl^Uh}$oX-pMy71wR7#_!(SEf*` z$I0685Snj!MZ!d@WS3?Ihi;R7Ukxve7^!48*6aM*Sb?t#ICBznUbkwNjhobMgz0sc zYFka+@2)+|%0GVXeey)~)18gyRN)#GPeq?L&N<-^_XbNFVs)(yc0#lbyi=Zo+nHW` z8qWw|KhjKJoXI-&glkeiUG}YOm1<6VLhzR1(894pwJXf6IfnNeC9hW?G3J&@6FE8o` z`UW*d?)JNZIe(_qj3?B1H_qMd-CKq?hRYS1t`3}+-X>tsuQD@D27bM&)6=qw?JF~E zd3^C$X8f`ETV;lgnZjpj73xoaQ*r%P!pAn?8eHj_y5T5%(*QO5Ty&65|NH=z0zZGy zw7Z>hOas-I-Na7@QJ;%nls>+TDk`S2&-WDIuqjNZW>s}XKVwV|YfUJ9tKxWc+(SrE zDEiC=sW*pq?`~PEeuwiY+g{*FtY<2}`1TvYD!cu$nR5G+%JHnM)0sZWi}y6@OZAqQ zIQbjZg@Zc>Lhi)+mAU1wc$=|dg0^qa4~%Z>VU2BVGR&6&&Sw(3lBJ&HT*u2pdMfs*f_Q{lgE5wDU0)K^3LaXSthI+%3+IVs$nxM z4P8RD6&V`0@ej>M>?_MTKSfCva@5h-?vwY(2|t{5>Ag+R?);Cm4Fzj)kw>RbwtQWg zsM1ZP@{hgGnr6wybNf@6Mo-Z>q4ydH!&`|ys$RRD8x%}eG@r(;+E+*>L)5t_vU5toje$%+F zYC;vMTlJ?Ox+@RK1oQJ{cl*=k_w|K@l_ zm0dObVD?gp zCkSZe?THWhF?y&{B}%I&txUYLdANk5mfQVs>=oM9g%{t}=K2rv6kav(a?<~NB;-;3 zjI?ANnqUenBUr({I7i_g9oU%u{D+V0Ac#&pSoD>Seuttr94 z?Ii5IWNt8JJCK=jyRz(j>(HsEs_y1u>M1{cM>yHS7tKcR#o3>4&~L~yN=}{X3JLH! zf9_sm@gZkj%bT~vpbO92!_?f}dM6$nlzDquzIhcJo{JmR75c`xu$qYG|3&;b#cy!5 zuY6`$R;!{_G^mQ_i&+1Byt#Y7Che<$>KCttM^Bu!2ne)y!aj-Hy+78)LOS7x=W~{O z_uJG;-r70AmA}MmpTrHgdH=#aH*LHR52z@9$iFR$GCWpv+Fyy&&Ir{!6>D3q$Kki{ zS~_gCG=Q2DyB>1<#l>!cu0`G2pDE}m`R;7Rc0H8D#tGBHz!MmkNZlO*M7P4wEAcO4 zC)(^G#^?K7r5@2(K5?b~bS)&j+0@YPw5l?l%+l$z@4GDWd`mhbYV-=9G+oT7qtywr zElym2Yjy6-Qbmh$5kv2}Up?;Yrpmv*{GR9`-(Bv@rHqnNTmO}vJ*uqedA~P)~6=-pUXbg`nZv8de)~rZ_w9+cshKAcIbiD=SrZI z&9tx0)8Xhc!;4v3!PooC;X@-ocWQ+kpZFM9!j^CXe@ba;xzZ{7_Q&I9&j(BC_Z8}v zsBejiDBw{lHDr2WQb5DPyz3p`zOf8}Gm?`r3K*jb{Iu~oTdO)(kGioU?Kn=0eWkp= z?k;}R!;SHFr#fG%uw~h%vJlce5p$z2daJFTM}*|SLpe^pF_EKGh5Wx*;*b5=zuhjP9lV@iVsP#raeBS6!t( z8=CQGRBZd*#&5;*S1miwP7U1o{ng1HS=n;@vdvUDxyVjaQuzTIx)A7vpg)O{7 zipfpd?AW4A;V=DT#){V`wQp81O2-sya@1hc7<5X$CG6{z_$8d)ag6uLEf%JOvl9Y4 z0)9v-5pRu!yyrNy%|oPYUj|pcPTg#3MN;aapDlG~dbtEzd#_daW#6cgxZ^KU8C&>e z;Zd>$qt+X~fUD`!1LIFmY+2#VKI4>_ndlT2Q7jvo@^0zU%Gb#9`pNYi?(}=Z@)jX+ z%f)>CPS6dK>gnZj9b*NIn#$s??$L-Nwc&03y+b>& zZTdBDPH_+U6mtE-W3y7@>$8T%)HNNN;114sYF+OOtgqun(AfL^r<*R77(d@l+_JyqwL!e}o~x2^ z2QL}sPhA##&hYBe4lU;ZK1w;~P@{wc_lMhe&s@THMzv!m$|M#w?FR+KD-E6zuPhrn98#R`Xk?U77&xy}wKJ46 zqOAGV{g-7&qT;P~b#+ywPVe?jp4rVN$6p$7bmM`=H`n9IvhK&Xu8Q_C%WwEh$;9~A zTeS?PSy{$ZL~cAbTa$0!_FbWOAwZ_c+&ZehG-5}i&n@joax5CpzAD>{_i=ZN$Muwi zS?@83zJ2OgkHhomQ0LZzTUD&h3;697TAQ#R26U8)ue9EAZ!cM1Uy$56m}2rUEkVg4 zZu#Kd^|>E82Wt9W-+c*LpUZ!tc*P>`!Eu@(~{BJkd1!cAcNf=ol( z&d9!J905sv8M@%53$NnPUf!Ljcn-?!tTUbXRW+u~Ix?P9=rF$Y`eU(h@Zd1x7R$5^ z18doQm(*QBlO>ZhjEDWTUny(Gz_;G8jvsXD>XSOqvj>eIJN53lrFC&+6xFW`J4U^D z8Rn$ZKbOUB-o&i@P(Rlv7S>g@9pEz0BW@-HLr~an}kAcoHAA2vI`r-%7otTGYM4tdP}z)iG?TRvS#Wvy#1E*SMuEZ+7 zXe#D@^yKZr>^>p?$tTw#YR`0`J9k-TJw8k_j;r@T_yi>nA=iPxk6qs+WMfb1IKPBq z*b6_I@kIM9YK#~5M$tU{cyza|tFUcS%^B;CNALI4`;R}SUy40UP1It1b~r| zLsTL*#g~AXi!Y)VK@u22l(EPQHGrl~pg$=np!>18R!6|mDPU7=5onD#xC#W5)QFHp zBghhzK%g=suKwqEa`zDO1Qef50WRa z0t$>$1%&=i1vrKW+9f7n&jSo{o)mzgoF_!9L|5ey9LrheQQd3rTPJW)Dh*zX?+Iaz;B}XJL5Tpj`%`Omr23R}90QMx!8Ps1J zIP~u~WRV-#Hvj&6XMeZ(uenEZ{%^MbiPgXH@xOT(g~L$6Fw6!+uqa9atSeHb=EmS? zAy^CL#Gr|iM=`=YC>W;23Sp;VYEW7nFmR8?plHBv3^j~F!C2H*;17q{v_rw*AMk+% zj7Gy$7#OBv#-m{x7!4zS5%+lT8;yb)F(^7JD)5^UE@Fp-i>3k*fZr^56pRCbV1Q#7 z%nb(tqUkVL?Dg%Q{Vi(tfH5ttFC z-`0jWKtUj6qzo}A319?&6Ci_p~JxF?IJ zL~~=gMb$8DC&pf>P=HE(z-8Y&$DF$^7z3Yr(ijpd@k&{3J}R#l`|q>`b=<3!QC z)Tmy55GoplV!~0=2+B}z=in0MVdJFP4^n4sPHIiXblbFI2oB4Wl)?n0a`!sVyG5&qcAo)HoC(!TNBLT zok*L4v^e0ip~#h}3$83`u;+m>NWB6z2h?p8#E69%A$}aLp9*FM*Cc2|usZ}{UuiU` zqZky#&#Zxkq3y3EF>o_K%t4JBp#uIvO@kk!m?ZXM5H|*U2`w0y8yrRcr~Z^PeEWApTvna_mg76BW4nP%uUq=Hos_t3g8pZ^4k-T&yHolVQcew=;6XEpLLp7nW{b@St`S;?6fG%Kr0GZ6XM}lB>ZJ17jD;881qulS4pYP6^IcSQ)b=onhL&nKXrz!$ zl>uo?v9z!V4eX2oMGj8)Rul%!1iosG0*x9YXow&T54a@xP&z1>3RHAjP?3T!I?;oMN5#^MD~CZK@_8G^Tho4^GW7YjWsO1+g9G$v>{P(UD&;AWr? z${t*DAZN1R=7O{fSdjDWpo-2Q1qW`f5EBy#vdT7<=jgC$qjK^(fEA>W5H zqLs&l!zzptAg_3|JP4NxCZI*IF!c`5j4OdV6g9Z#*`QJ2CWV48!DwoBQt57<2?o$= z=)<6pkP3mufXp$V%&Cz~aw28Dc^uT1uOP*sAw+Q_w!ks?fGQ{@C*&`cnDrXLr6_Rq(-SBn9mma7pi-k{Q~f~4Uq-wNc{wab%6O7&+mxdzYNgE z6PFMGy#S?uc3~gr{FnVcT}vCY-8*dzcJJJM$V^%itX>Ce*yZG8{ulnd>_R{s&@u2_ zeHf%82|QdP{ee^9xz-%)k^alS?qB$TCu2W>9RhOy9D%pbruZZ9+Xl1(O~F1EJaZzC zo&W6E(G3Ws`wM6ZD1rX@|JjDfSAy;W(#ar+8~8f;k#u>%ihm$&>E`4JL=n6}_Ysi* z05a8}bNP=){G9?^eSn%}AP})eB-!mj$v6cB`}leMdFYQo>_9$&FeVZq`KXhloui|l zlRu)@i}YS8ggCJa0^$XK2I>feH0}L-JU}AA!9$_xI$HxRBD z@N#l=3-odZ>YZdePahv3?&$|Iu^HN5q6y+oGA=R#{-It#hQR}L<9vK2fR-^BH=vXh z5{iH;P;&MBEnng0?F%$3fFOsR7wEo&uR(xe3ebT<6lw#2IxvuF2n-1JLsV`N-C1v+ z-|6xP9Y80b`Rf6saFO0U_=S`o(8TowqZ&Q|cE2?oNU;X^_y~9c0e&ZN0(=7f9Gt-S zEc`>ALV)f=z;Az~V~(Iekb-pZ^YQnWb_9~cz%eODqz*h*q?pUmzlz3ep|u>r1LA|Ex}dgh&2lh8GZA2Imsg z1)zL^RH5G~0Ks~b@(hvzN>UbhKnj#3g}Qkel70qyBVyAoK7L@3#&Og3w^rvV+@|&{ zMZ5Fn-?;j390VQ-#KHASagQ(ya{Yp_o;_gy30%yG_NN07?go+BZjL``Xasr(``P)5 zO8_YpZ%`?1_k+P8+f8{`0zr@fdf*POPX6FB|8Jq9Aw$;2MFyY9(#!Utq)My{%0>?u zePI5%%@ahLZlHxqx;Vv=@gqw6i%dR4p2q&!5AbqK&I&ZR_F{5kzuh;G-BbMEC36TG zXq8|EAO{6ko!ZfJsVOniBoKgJBE~9I}E;sp2VJ`IkLvH%$sl48?hnG%Fow^Lo>0TZD zp<7|OYtdy_?v~H_% zd80sO4Hi^|@ph^r^nz*?429~lTLd*0_yqUpC>5IV*?l-P=Wb_yz~_Vcr6xNIsK@TG z)APc^&>KNZXr%DSjZwj4Q)3^F_kOXn5`bo`=in%t10W4NI9teuxd5u=9D!&B1Yk$` z0vN=HDrhQ1`9CiNE@sdWlMDu8vcVw2(j%Pu62Yv+VY-ouKQLDt-K^LWgYg9l_3&S)MF8r!}i=BvvJ_ z1MOVpAu(lL=BHH=5>wVmLTgeaUL>zuq8Or`5maNn*;nsoAvv5>wVO;nyQbOj%d7 zZ9SI6X5@7~+Uvbq!1Fk4RieUT46z(M4h$dEURw#!C{vAkV|!y)i^$2J*akhmA23enWdj*mMYhd($7oWE51!@7 z^MLtCqp(09nmjL8jiitSI+EmhvS#GbVamK!FVg5N7$YUmBTa;~NTE~abzX%GNKBb$ zNrd*2m@@D2HFSu?lzE8XNN*h=h%zsb9(E+zPm<^9iNT&EHYU%T(}Tf)E!g77^Vp8V z5hSL}D+`8WNlcmNl?f-4m@@CG63!y=ZSp**CvZNADf5y(z(pjc%oAFLD@lBuJa2~s zRZC*ZJQ{ga6NxGFTK1wIk(e^i#2M8^;`iivAE!_+NlclCaS=5{V#>UTI@B16Df1M1 zQBx#lGT59q@D;U4V#<4b9D0?+l=tcapznwrkRZS3)yx04VHX!j}@cTyZ2iad4F?&h; z&-X${8SrElfOJ0kQB0(74S)|Z{+s(I*{zm!fJq#z7d5H{jfi|0@(fQdpSsxn|Gi;l7T<`Bemteuo1dCP?AfgZ`!i_)SkfmlS6B z8zcEa%9>&y09fP?4h4+7x1-p{14f>IDeMXu=_gZoKVYFhm>KY&;WPb>Lx9^q?L+^@ zVSnS3e`BPjK+>jaLF$vKwr;=bRN!Pg10>@002 z?>v0Hje8hhpYQiRaZ9w?xvfe>g`M~43q37{LmLjw{^nhrvrA6j#GA~2J{gK0n)Y7o zo*lCJX@>n>2j)Szq9Bcwx;6ec?k2O0j9kcH12npN`UZwZ&UT)l_wN_z1pKp;`#5p5 zo8eJ76)+dDH+6E>cLFc3DIImnmo7FO!I+T~_>K%PV5ALVVrF4tVr8LcV5g&HXJ=$! z6;<2H2}aPFI2jn|*{Hc0m^j#JIp}FwS!h}9?3kbvz?=pq3z#BcYJqtI%pfqIfLR2F z#-0g$?-A&o0;3F!F)&AfaRDX_m;zv412Yc{wF48x1`IDSV!)^Zvmcn_z_EU(6Brc8&lX^|0V4;DJ}~CM*a8Ep%J1QV$`AhMRh32CKeK3B0|6THKBJK z7a+zQEW|833*nC@L0K>V9f56OY6uIR{)oJ$hIkj;$gi&{-?jKf3J0;n_4eq0UE7OwM+fHLs_#lI|J-bK&is|}e)(1cxH6*VHhWbPFss#(1|;1*40 zXt)XDtyH_4PT`MQA@Em!wn7R|H`(?E(S+BKSx11N_)rd>en_z|&{B!tuy^kxbGj%| zbAOM@!YG+XP{c2-8L#}DTvX4i`q(JUNQiv4H}}joGB*nn zd-d+}?NuRjuLR*vhp-XXPBJs?Bs3kn!nt^u%(g;=n;8Zd2VKehNP&3%n*3l#D48K) zVuRD!!6#?Q9KD?gS%wt#UZmJhHwj0x}n=5zlOx?Yno2%*T}p$L6n{&Ui%T22sM}hCN#YUQzr{ zHKhuF-0JX!%)Oih)B;tC^)i`tI0*a3t-_t@Cdudbd()4G)afujGLO&@#AJ-8F3OSl z^>%_4-YEL19+~I3h!?l*xP>++vn?%w)qe4;u?v|K)d(fG?=t)weaGBM=P13L9J*pEsc$S3Xf@B>pPlz6hH|vrAJ0p8dy=^qPcX4w`4$vK=ID1?w|0wtOU@*7Glq!970Oj# zC$ld-(b*@jex!lS>GXt+hkMfby2xCBBKQ<8w7R_~a|l1Nfp_3o%QuQW6LI2}uAMk; zYBN7N%)}AXxZ#Ui$vi?!m~mVl(-38QH*6|&$lS|7WM5kj*?EY}&gz8D-orBU zE@WonBGx@jJX0FJ$4>s%u<)Txz~K072(Pi7sMaE8N6 zhOv{(0&`j{kF3mT-;>#PK})mZ*fI76GNgwNN$vl)q!xm$;De1=0)QIpKBbc9;%q|Y)YWR{~L zx_Y^Ys5_Av8gDY#`()){7@2=j5k>2t1&5}Q*>|DoOM21On?+>q9oHJ`h=^ajOJ*(( z0=;Xh^sXK5XlfzvPRmp8+ z2G>`h-|()d8f1pbwL}cPj|G{Kd2X?3%^)#U!I{j_9a?Jl^Q+dv$=tN8by`aV^*V#h zwlAAf(=VTTSVCqxS|W3Qrb;7`%p=WBStrsYTV8B(^gAZvjPQ1k!3nax{tWV50XE9> z0tDS}I=ak7OJ<$hO=!iHG6DygIa!FOQJQS7f)x8kEzjuS9eGk@&Y9KfxW_E>Qk7!= zr0GnQ_ZN13GRwWzayj(F&t^ZFwYi8#E2 zVJAqJ`boYFCv(9>Q}4yVErtnX*7>B>PUZZAm`Uakh#0fb*0JL8$6N;e0chn+LTxcKJzWc9B^COL%RiF0A>Q%)QG^3(sFDOnoGC zB{!kC?7hwPSu%gY5a;^VZ#u7#S&p8#M|eP7j%t3hewfT_9XrO-`#;*d`=2K6I1b=f z1gt<%D3qXBjsgYB%Gz47=zW2zU^NWEfZ5!n$U|M`5XwZ*tWXUqI%J@r=%x}-9)=Sn zV=2<_grSi+MdmP89;Ee=M`svMMTfhspZ*ie?x%a*eeZtw2E z-^T&#*yw@i^ES)}hYwL|>j{_IU@-kY8Wz-DIlC5Y7^0-2%_qyEE#pTiRneu+@@-(D z4I1oF#a&c_r3;YL7B!{K1o!x(3$0~`dvd|uHu&W6LaFH(xWEG|x3Bt;cN+ZK3Dx|X zKKgMLSiS^3J;Itj(*O?HfaA7X=NnqV&wS825C5|FJHezKZff~dbfgEYc}j`Ge@J*~ z0Jn`$(noK(G2`H32Aa7m&2Kk>bC%(+k0%wZv7Ip2vs8dMwK*$)at71$SJ{BNWTPio z5{SH6`zi+l!L#n@<&Lb~`=#JcckJhK@Qr5#SZIZ;s+%@<#e(H5+}OoY9ZCSx-#@nc zNovF{aJLg$Y*;RF%mKd=q0r@fvOR}z&fb}fAXwY-&+<9;#6Mf_OoAOva z_)9Kc-P_xprv*#+$h0&&B=;s*vjjh~dRBetKA3(U_PM5bo*D#`le&9Bp>+*o;Bp_# zEx?=Zo4`Ug_We<0H*fo=xqiW7Y=7z1xY)&P&0q%BK8$*s;RWaATwFO^yG9!XF89Ss zx0EI(1@7h`zqzN%q>W&rU$^+e3B}E=V7(Bx6g;jJrGPuRDCE1L=w&K;dt}% zEM{Y=-X`rzA=qGtJ3>{86&0tL^ny6)U2s$kOgW?*; z*FWzDSGeI;iE~u-W3Z5i?nHYGW{iQW<+w2SvUS89xSztU6+1h)%t>>-w7#e;XvWKq z4W|ExA|n_1z3~PovM^Z}^Jq#0F84;GE%{+{VPIm8azDBwkr{2dep<)4U$d6{#A18Q zCYF!OJ_Bol3J%CsD?L5K*dy}9x*I9!0O8%`LFrC`zlW&Zx~HNOfR!@&$~+KBop zShElr1A-s)UbmQq#qDldS(n8G>Kpj$OjAEN<2`h$UVlI^3O0CPE5W(FO(rnuj@m^L zc{1jdxjt=7%vav4>}7+AIo(KX*pS*6%-n=}qt9&(lz{a-y!7()J}dj9HUF*qjx z6Ec0l&xE~xffqdup!;(FZ~uu3Fo<`H31We=;WwZ#wAbsZeAm(XpJJsk;?) zPh7DlT|wt>l6NWoUG*h3lb{yS`H_^YWO{{Oh6BAz2WaS=lOSoIm2EcNvCR6yRv07> W4w5*~i}a=m;8qLiV?iSE%D(~61vr!d literal 0 HcmV?d00001 diff --git a/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts new file mode 100644 index 0000000000..1d8bb910ab --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts @@ -0,0 +1,19 @@ +/* tslint:disable */ +/* eslint-disable */ +export const memory: WebAssembly.Memory; +export const __wbg_fittedmodel_free: (a: number, b: number) => void; +export const fitJson: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const fitTyped: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const fittedmodel_batchSize: (a: number) => number; +export const fittedmodel_dimensions: (a: number) => number; +export const fittedmodel_mse: (a: number) => number; +export const fittedmodel_peakStep: (a: number) => number; +export const fittedmodel_revivedClusters: (a: number) => number; +export const fittedmodel_takeAssignments: (a: number, b: number) => void; +export const fittedmodel_takeCentroids: (a: number, b: number) => void; +export const fittedmodel_updates: (a: number) => number; +export const predictFlat: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const __wbindgen_add_to_stack_pointer: (a: number) => number; +export const __wbindgen_export: (a: number, b: number) => number; +export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number; +export const __wbindgen_export3: (a: number, b: number, c: number) => void; diff --git a/npm/packages/ruvector/clustering.d.mts b/npm/packages/ruvector/clustering.d.mts new file mode 100644 index 0000000000..2ca0a76f10 --- /dev/null +++ b/npm/packages/ruvector/clustering.d.mts @@ -0,0 +1,2 @@ +export { init, fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; diff --git a/npm/packages/ruvector/clustering.mjs b/npm/packages/ruvector/clustering.mjs new file mode 100644 index 0000000000..b229b6a5a9 --- /dev/null +++ b/npm/packages/ruvector/clustering.mjs @@ -0,0 +1,2 @@ +/** Shared Rust/WASM e-means clustering, loaded explicitly by the caller. */ +export { init, fit, predict } from '@ruvector/e-means'; diff --git a/npm/packages/ruvector/clustering/cloudflare.d.mts b/npm/packages/ruvector/clustering/cloudflare.d.mts new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/ruvector/clustering/cloudflare.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/ruvector/clustering/cloudflare.mjs b/npm/packages/ruvector/clustering/cloudflare.mjs new file mode 100644 index 0000000000..c3a6e7b5f3 --- /dev/null +++ b/npm/packages/ruvector/clustering/cloudflare.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/cloudflare'; diff --git a/npm/packages/ruvector/clustering/ivf.d.mts b/npm/packages/ruvector/clustering/ivf.d.mts new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/ruvector/clustering/ivf.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/ruvector/clustering/ivf.mjs b/npm/packages/ruvector/clustering/ivf.mjs new file mode 100644 index 0000000000..8fcf4814d7 --- /dev/null +++ b/npm/packages/ruvector/clustering/ivf.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/ivf'; diff --git a/npm/packages/ruvector/clustering/metaharness.d.mts b/npm/packages/ruvector/clustering/metaharness.d.mts new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/ruvector/clustering/metaharness.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/ruvector/clustering/metaharness.mjs b/npm/packages/ruvector/clustering/metaharness.mjs new file mode 100644 index 0000000000..79c64e223c --- /dev/null +++ b/npm/packages/ruvector/clustering/metaharness.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/metaharness'; diff --git a/npm/packages/ruvector/clustering/quantization.d.mts b/npm/packages/ruvector/clustering/quantization.d.mts new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/ruvector/clustering/quantization.d.mts @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/ruvector/clustering/quantization.mjs b/npm/packages/ruvector/clustering/quantization.mjs new file mode 100644 index 0000000000..d1e262eeb5 --- /dev/null +++ b/npm/packages/ruvector/clustering/quantization.mjs @@ -0,0 +1 @@ +export * from '@ruvector/e-means/quantization'; diff --git a/npm/packages/ruvector/package.json b/npm/packages/ruvector/package.json index 99a9171646..14355d1efc 100644 --- a/npm/packages/ruvector/package.json +++ b/npm/packages/ruvector/package.json @@ -12,7 +12,8 @@ "verify-dist": "node scripts/verify-dist.js", "prepack": "npm run build && npm run verify-dist", "prepublishOnly": "npm run build && npm run verify-dist", - "test": "node test/integration.js && node test/graph-modularity.js && node test/backend-fallback.js && node test/mincut-wasm.js && node test/graph-cli-e2e.js && node test/metaharness-sdk.js && node test/metaharness-optional-deps.js && node test/cli-commands.js && node test/metaharness-cli.js && node test/db-workflow.js && node test/fast-agentdb-native.js && node test/mcp-stdio.js && node test/metaharness-mcp.js && node test/sigterm-cleanup.js && node test/mcp-policy.js && node test/mcp-command-security.js && node test/mcp-exploit-regression.js && node test/mcp-handshake.js && node test/mcp-intel-durability.js && node test/add-extras.js && node test/rabitq-optional.js && node test/rabitq-recall.js && node test/diskann-cli.js && node test/skills-install.js && node test/manifest-ranges.js && node test/attention-panic.js && node test/mcp-extras.js && node test/rvf-e2e.js && node test/startup-budget.js && node test/rag-context-rerank.js && node test/neural-q.js && node test/learning-import-types.js && node test/weight-space-optional.js && node test/weight-space-cli.js" + "test": "node test/integration.js && node test/graph-modularity.js && node test/backend-fallback.js && node test/mincut-wasm.js && node test/graph-cli-e2e.js && node test/metaharness-sdk.js && node test/metaharness-optional-deps.js && node test/cli-commands.js && node test/metaharness-cli.js && node test/db-workflow.js && node test/fast-agentdb-native.js && node test/mcp-stdio.js && node test/metaharness-mcp.js && node test/sigterm-cleanup.js && node test/mcp-policy.js && node test/mcp-command-security.js && node test/mcp-exploit-regression.js && node test/mcp-handshake.js && node test/mcp-intel-durability.js && node test/add-extras.js && node test/rabitq-optional.js && node test/rabitq-recall.js && node test/diskann-cli.js && node test/skills-install.js && node test/manifest-ranges.js && node test/attention-panic.js && node test/mcp-extras.js && node test/rvf-e2e.js && node test/startup-budget.js && node test/rag-context-rerank.js && node test/neural-q.js && node test/learning-import-types.js && node test/weight-space-optional.js && node test/weight-space-cli.js && node test/e-means.mjs", + "test:e-means": "node test/e-means.mjs" }, "keywords": [ "vector-database", @@ -51,7 +52,8 @@ "@ruvector/sona": "^0.1.11", "chalk": "^4.1.2", "commander": "^11.1.0", - "ora": "^5.4.1" + "ora": "^5.4.1", + "@ruvector/e-means": "0.1.0" }, "optionalDependencies": { "@metaharness/darwin": "^0.13.0", @@ -84,7 +86,10 @@ "wasm/", "skills/", "README.md", - "LICENSE" + "LICENSE", + "clustering.mjs", + "clustering.d.mts", + "clustering/" ], "peerDependencies": { "@metaharness/darwin": "^0.13.0", diff --git a/npm/packages/ruvector/test/e-means.mjs b/npm/packages/ruvector/test/e-means.mjs new file mode 100644 index 0000000000..b1add78cdf --- /dev/null +++ b/npm/packages/ruvector/test/e-means.mjs @@ -0,0 +1,10 @@ +import assert from 'node:assert/strict'; +import { init, fit, predict } from '../clustering.mjs'; + +await init(); +const values = new Float32Array([0, 0, 2, 2]); +const result = fit(values, 2, { clusters: 1, epochs: 1 }); +assert.deepEqual([...result.centroids], [1, 1]); +assert.equal(result.mse, 2); +assert.deepEqual([...predict(values, 2, result.centroids)], [0, 0]); +console.log('RuVector shared e-means dependency passed'); From e45eaf8e9d7308f0cf0a493230a978764ab2ac3c Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 12:54:52 -0500 Subject: [PATCH 02/19] fix(e-means): validate typed array storage without custom iterators --- npm/packages/e-means/integrations/ivf.mjs | 4 +++- .../e-means/integrations/quantization.mjs | 14 ++++++++---- npm/packages/e-means/test/ivf.test.mjs | 7 ++++++ .../e-means/test/quantization.test.mjs | 22 +++++++++++++++++++ 4 files changed, 42 insertions(+), 5 deletions(-) diff --git a/npm/packages/e-means/integrations/ivf.mjs b/npm/packages/e-means/integrations/ivf.mjs index f3fbec8217..d9efa910a9 100644 --- a/npm/packages/e-means/integrations/ivf.mjs +++ b/npm/packages/e-means/integrations/ivf.mjs @@ -28,7 +28,9 @@ function validated(value) { if (!(centroids instanceof Float32Array) || centroids.length === 0 || centroids.length % dimensions !== 0) { throw new RangeError('model centroids must be complete Float32Array vectors'); } - for (const coordinate of centroids) if (!Number.isFinite(coordinate)) throw new RangeError('model centroids must be finite'); + for (let index = 0; index < centroids.length; index++) { + if (!Number.isFinite(centroids[index])) throw new RangeError('model centroids must be finite'); + } if (!Number.isFinite(mse) || mse < 0 || !Number.isFinite(peakStep) || peakStep <= 0 || peakStep > 1 || !Number.isSafeInteger(batchSize) || batchSize < 1 || !Number.isSafeInteger(updates) || updates < 1 || !Number.isSafeInteger(revivedClusters) || revivedClusters < 0) throw new RangeError('model metrics are invalid'); diff --git a/npm/packages/e-means/integrations/quantization.mjs b/npm/packages/e-means/integrations/quantization.mjs index 85537def17..903a4a315f 100644 --- a/npm/packages/e-means/integrations/quantization.mjs +++ b/npm/packages/e-means/integrations/quantization.mjs @@ -22,7 +22,9 @@ function vectors(data, dimensions, allowEmpty = false) { if ((!allowEmpty && data.length === 0) || data.length % dimensions !== 0) { throw new RangeError('data must contain complete vectors'); } - for (const value of data) if (!Number.isFinite(value)) throw new RangeError('data must be finite'); + for (let index = 0; index < data.length; index++) { + if (!Number.isFinite(data[index])) throw new RangeError('data must be finite'); + } } function validated(model) { @@ -33,7 +35,9 @@ function validated(model) { const subDimensions = shape(dimensions, subspaces, clusters); if (!(centroids instanceof Float32Array)) throw new TypeError('centroids must be a Float32Array'); if (centroids.length !== dimensions * clusters) throw new RangeError('centroid count does not match the codebook shape'); - for (const value of centroids) if (!Number.isFinite(value)) throw new RangeError('centroids must be finite'); + for (let index = 0; index < centroids.length; index++) { + if (!Number.isFinite(centroids[index])) throw new RangeError('centroids must be finite'); + } return { dimensions, subspaces, clusters, centroids, subDimensions }; } @@ -102,7 +106,9 @@ export function decodeProductQuantizer(model, codes) { const { dimensions, subspaces, clusters, centroids, subDimensions } = validated(model); if (!(codes instanceof Uint8Array)) throw new TypeError('codes must be a Uint8Array'); if (codes.length % subspaces !== 0) throw new RangeError('codes must contain complete subspace groups'); - for (const code of codes) if (code >= clusters) throw new RangeError('code exceeds the codebook cluster count'); + for (let index = 0; index < codes.length; index++) { + if (codes[index] >= clusters) throw new RangeError('code exceeds the codebook cluster count'); + } const rows = codes.length / subspaces; if (rows * dimensions > maxU32) throw new RangeError('decoded output exceeds the supported element count'); const data = new Float32Array(rows * dimensions); @@ -119,7 +125,7 @@ export function decodeProductQuantizer(model, codes) { /** Return owned JSON-compatible codebook data. */ export function productQuantizerToJSON(model) { const { dimensions, subspaces, clusters, centroids } = validated(model); - return { schema, dimensions, subspaces, clusters, centroids: Array.from(centroids) }; + return { schema, dimensions, subspaces, clusters, centroids: Array.from({ length: centroids.length }, (_, index) => centroids[index]) }; } /** Restore a validated, owned typed codebook from parsed JSON. */ diff --git a/npm/packages/e-means/test/ivf.test.mjs b/npm/packages/e-means/test/ivf.test.mjs index 9e8d09acdd..fcc5b5a4f0 100644 --- a/npm/packages/e-means/test/ivf.test.mjs +++ b/npm/packages/e-means/test/ivf.test.mjs @@ -58,3 +58,10 @@ test('IVF rejects malformed training data and mutated partition records', () => assert.throws(() => postingList(bad, 0)); } }); + +test('posting validation reads actual centroid storage despite an overridden iterator', () => { + const result = partition(data, 2, options); + result.model.centroids[0] = NaN; + result.model.centroids[Symbol.iterator] = function* () { yield 0; }; + assert.throws(() => postingList(result, 0), /centroids must be finite/); +}); diff --git a/npm/packages/e-means/test/quantization.test.mjs b/npm/packages/e-means/test/quantization.test.mjs index 65b1f5da53..0825fd68fa 100644 --- a/npm/packages/e-means/test/quantization.test.mjs +++ b/npm/packages/e-means/test/quantization.test.mjs @@ -112,3 +112,25 @@ test('every operation revalidates caller-owned codebooks and JSON values', () => assert.throws(() => productQuantizerFromJSON(json)); } }); + +test('codecs validate indexed typed-array storage despite overridden iterators', () => { + const model = { schema: 'ruvector-e-means-pq-v1', dimensions: 1, subspaces: 1, + clusters: 1, centroids: new Float32Array([3]) }; + const hiddenNonfinite = new Float32Array([NaN]); + hiddenNonfinite[Symbol.iterator] = function* () { yield 0; }; + const corrupt = { ...model, centroids: hiddenNonfinite }; + assert.throws(() => decodeProductQuantizer(corrupt, new Uint8Array([0])), /centroids must be finite/); + assert.throws(() => productQuantizerToJSON(corrupt), /centroids must be finite/); + const hiddenInvalidCode = new Uint8Array([255]); + hiddenInvalidCode[Symbol.iterator] = function* () { yield 0; }; + assert.throws(() => decodeProductQuantizer(model, hiddenInvalidCode), /code exceeds/); +}); + +test('codebook JSON serialization reads stored coordinates rather than a custom iterator', () => { + const centroids = new Float32Array([3, 7]); + centroids[Symbol.iterator] = function* () { yield 0; }; + const model = { schema: 'ruvector-e-means-pq-v1', dimensions: 2, subspaces: 1, + clusters: 1, centroids }; + assert.deepEqual(productQuantizerToJSON(model).centroids, [3, 7]); + assert.deepEqual(Array.from(decodeProductQuantizer(model, new Uint8Array([0]))), [3, 7]); +}); From 9864a652719b2e922336118542a7a012477a0f22 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:00:42 -0500 Subject: [PATCH 03/19] review: keep legacy PQ codes, pin new edges, fix Darwin 0.13.1 path, add release metadata - ruvector-core ProductQuantized::encode keeps the existing f32 ordering for finite distances; f64 is used only when an f32 squared distance overflows. Adds a regression test with a pair that ties in f32 but not in f64. - Pin new 0.x edges exactly: rand_chacha =0.3.1, rand_core =0.6.4 and ruvector-e-means =0.1.0 in core, pq-search and rairs. - @ruvector/core: e-means moves from optionalDependencies to dependencies, since clustering.mjs re-exports it statically and has no fallback. - e-means MetaHarness accepts Darwin 0.13.0 and 0.13.1 (both run). ruvector resolves ^0.13.0 to 0.13.1, which made tuneClustering throw through ruvector/clustering. The receipt reports the version actually loaded. - cloudflare/build imports esbuild lazily and explains a missing install. - ADR-356 metadata for ruvector-e-means and @ruvector/e-means (homepage, bugs, keywords, description, animated SVG). READMEs no longer state unreleased ruv-FANN or consumer facades as available; crate README links are absolute. - ADR-359 labels the author's speedups as measured against an earlier build that is not in the tree, and adds an independent reproduction of the pruning change with matching output digests. Co-Authored-By: claude-flow --- crates/ruvector-core/Cargo.toml | 2 +- crates/ruvector-core/src/quantization.rs | 20 +++--- .../tests/e_means_quantization.rs | 15 +++++ crates/ruvector-e-means/Cargo.toml | 6 +- crates/ruvector-e-means/README.md | 10 +-- crates/ruvector-pq-search/Cargo.toml | 2 +- crates/ruvector-rairs/Cargo.toml | 2 +- docs/adr/ADR-359-e-means-shared-clustering.md | 31 +++++++++- npm/package-lock.json | 8 ++- npm/packages/core/package.json | 4 +- npm/packages/e-means/README.md | 17 ++--- npm/packages/e-means/assets/e-means-flow.svg | 62 +++++++++++++++++++ .../e-means/examples/cloudflare/build.mjs | 4 +- .../e-means/integrations/metaharness.d.ts | 4 +- .../e-means/integrations/metaharness.mjs | 15 +++-- npm/packages/e-means/package-lock.json | 2 +- npm/packages/e-means/package.json | 20 ++++-- 17 files changed, 180 insertions(+), 44 deletions(-) create mode 100644 npm/packages/e-means/assets/e-means-flow.svg diff --git a/crates/ruvector-core/Cargo.toml b/crates/ruvector-core/Cargo.toml index 74724ff1fb..e1ec5f1267 100644 --- a/crates/ruvector-core/Cargo.toml +++ b/crates/ruvector-core/Cargo.toml @@ -18,7 +18,7 @@ hnsw_rs = { workspace = true, optional = true } # WASM-safe, so it is unconditional: the codec plane exists on every build. ruvector-turboquant = { version = "2.3.0", path = "../ruvector-turboquant" } # Shared CPU/WASM e-means optimizer, used by the explicit PQ training API. -ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } +ruvector-e-means = { version = "=0.1.0", path = "../ruvector-e-means" } simsimd = { workspace = true, optional = true } rayon = { workspace = true, optional = true } crossbeam = { workspace = true, optional = true } diff --git a/crates/ruvector-core/src/quantization.rs b/crates/ruvector-core/src/quantization.rs index d5714d7030..e03c454965 100644 --- a/crates/ruvector-core/src/quantization.rs +++ b/crates/ruvector-core/src/quantization.rs @@ -245,14 +245,20 @@ impl ProductQuantized { let start = subspace_idx * subspace_dim; let end = start + subspace_dim; let subvector = &vector[start..end]; - // Finite f32 embeddings can have squared distances above f32::MAX. - // Compare in f64 so those candidates retain their nearest ordering. + // Keep the existing f32 distance, so codes for finite distances are + // unchanged. Only a candidate whose f32 squared distance overflows + // is re-measured in f64, keeping its nearest ordering. let squared_distance = |centroid: &[f32]| -> f64 { - subvector - .iter() - .zip(centroid) - .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) - .sum() + let fast = euclidean_squared(subvector, centroid); + if fast.is_finite() { + f64::from(fast) + } else { + subvector + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum() + } }; // Find nearest centroid diff --git a/crates/ruvector-core/tests/e_means_quantization.rs b/crates/ruvector-core/tests/e_means_quantization.rs index 2fad64398e..83a0ce75e0 100644 --- a/crates/ruvector-core/tests/e_means_quantization.rs +++ b/crates/ruvector-core/tests/e_means_quantization.rs @@ -127,3 +127,18 @@ fn invalid_optimizer_settings_return_errors() { options.peak_step = Some(f64::NAN); assert!(ProductQuantized::train_e_means(&vectors, 1, &options).is_err()); } + +#[test] +fn finite_distance_codes_keep_the_existing_f32_ordering() { + // These rows tie in f32 but not in f64. Existing encode picks the first + // f32 minimum, and codes for already-trained indexes must not change. + let bits = |v: [u32; 4]| v.map(f32::from_bits).to_vec(); + let query = bits([1059241166, 3208695764, 3205419074, 1055842996]); + let first = bits([1063676912, 3210863684, 1060297430, 3212197722]); + let second = bits([1052646232, 3210863675, 1060297430, 3212197722]); + let quantized = ProductQuantized { + codes: Vec::new(), + codebooks: vec![vec![first, second]], + }; + assert_eq!(quantized.encode(&query), vec![0]); +} diff --git a/crates/ruvector-e-means/Cargo.toml b/crates/ruvector-e-means/Cargo.toml index a4905c1bff..9b457c4e2a 100644 --- a/crates/ruvector-e-means/Cargo.toml +++ b/crates/ruvector-e-means/Cargo.toml @@ -6,6 +6,8 @@ rust-version = "1.81" license = "MIT" description = "Deterministic CPU and WebAssembly e-means clustering with EMA centroid updates" repository = "https://github.com/ruvnet/ruvector" +homepage = "https://ruv.io" +documentation = "https://docs.rs/ruvector-e-means" keywords = ["clustering", "k-means", "ema", "quantization", "machine-learning"] categories = ["algorithms", "science"] include = ["src/**", "tests/**", "examples/**", "Cargo.toml", "LICENSE", "README.md"] @@ -19,8 +21,8 @@ serde = ["dep:serde"] wasm = ["serde", "dep:serde_json", "dep:wasm-bindgen"] [dependencies] -rand_chacha = "0.3.1" -rand_core = "0.6.4" +rand_chacha = "=0.3.1" +rand_core = "=0.6.4" serde = { version = "1.0", features = ["derive"], optional = true } serde_json = { version = "1.0", optional = true } wasm-bindgen = { version = "=0.2.125", optional = true } diff --git a/crates/ruvector-e-means/README.md b/crates/ruvector-e-means/README.md index 1f32a76191..092c9b8f3f 100644 --- a/crates/ruvector-e-means/README.md +++ b/crates/ruvector-e-means/README.md @@ -1,6 +1,8 @@ # ruvector-e-means -CPU reference implementation of [e-means (Bessa et al., 2026)](https://arxiv.org/abs/2611.09501), shared by RuVector and ruv-FANN. MIT-licensed original Rust implementation; no upstream implementation code is copied. +![e-means training loop: rows are assigned in mini-batches, EMA counts and sums move the centroids with a cosine-decaying step, a dead centroid is revived by splitting a busy donor, and the last epoch mean gives the codebook](https://raw.githubusercontent.com/ruvnet/ruvector/main/npm/packages/e-means/assets/e-means-flow.svg) + +CPU reference implementation of [e-means (Bessa et al., 2026)](https://arxiv.org/abs/2611.09501), used by RuVector's PQ and IVF crates. MIT-licensed original Rust implementation; no upstream implementation code is copied. ```rust use ruvector_e_means::{fit, Config}; @@ -19,14 +21,14 @@ Scaling laws were fitted on large, high-dimensional embeddings; override `batch_ This version does not implement GPU/low-precision kernels, distributed or approximate IVF assignment, or slow-EMA finalization. It makes no claim to reproduce the paper's GPU speedups or universally outperform Lloyd. Existing consumer training defaults remain available. -Native Rust has no default features. `serde` adds config/model serialization; `wasm` adds the wasm-bindgen bridge used by `@ruvector/e-means`. Native core MSRV is Rust 1.81; WASM builds use the toolchain required by the pinned wasm-bindgen dependency. See [ADR-359](../../docs/adr/ADR-359-e-means-shared-clustering.md) for integration, validation, and staged release instructions. +Native Rust has no default features. `serde` adds config/model serialization; `wasm` adds the wasm-bindgen bridge used by `@ruvector/e-means`. Native core MSRV is Rust 1.81; WASM builds use the toolchain required by the pinned wasm-bindgen dependency. See [ADR-359](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-359-e-means-shared-clustering.md) for integration, validation, and staged release instructions. -Run the deterministic native benchmark with `cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both`. Dataset generation and warmup are excluded from median fit/predict times. The [local measurements](../../docs/research/e-means/performance-2026-11-11.json) include baseline comparisons, allocation counts and unchanged-output checks; gains depend on shape and distribution. +Run the deterministic native benchmark with `cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both`. Dataset generation and warmup are excluded from median fit/predict times. The [local measurements](https://github.com/ruvnet/ruvector/blob/main/docs/research/e-means/performance-2026-11-11.json) include baseline comparisons, allocation counts and unchanged-output checks; gains depend on shape and distribution. Reusable `quantization::ProductQuantizer` and `ivf::IvfPartition` modules add checked byte-code encode/decode, subspace-major codebooks, and stable inverted postings. Their private shape fields and serde restoration reject malformed persisted state. `ruvector-pq-search` and the IVF/RAIRS/SEIL family expose explicit -e-means training using this dependency. See [ADR-360](../../docs/adr/ADR-360-e-means-ecosystem-integrations.md) +e-means training using this dependency. See [ADR-360](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-360-e-means-ecosystem-integrations.md) for the native/npm integration matrix, MetaHarness evaluation, and Cloudflare static-WASM entrypoints. These additions preserve existing training defaults. diff --git a/crates/ruvector-pq-search/Cargo.toml b/crates/ruvector-pq-search/Cargo.toml index f570f85dd8..362e2f5341 100644 --- a/crates/ruvector-pq-search/Cargo.toml +++ b/crates/ruvector-pq-search/Cargo.toml @@ -16,7 +16,7 @@ name = "pq-benchmark" path = "src/main.rs" [dependencies] -ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } +ruvector-e-means = { version = "=0.1.0", path = "../ruvector-e-means" } rand = { workspace = true } thiserror = { workspace = true } serde = { workspace = true } diff --git a/crates/ruvector-rairs/Cargo.toml b/crates/ruvector-rairs/Cargo.toml index e731e27152..c36b5ffd60 100644 --- a/crates/ruvector-rairs/Cargo.toml +++ b/crates/ruvector-rairs/Cargo.toml @@ -14,7 +14,7 @@ name = "rairs-demo" path = "src/main.rs" [dependencies] -ruvector-e-means = { version = "0.1.0", path = "../ruvector-e-means" } +ruvector-e-means = { version = "=0.1.0", path = "../ruvector-e-means" } rand = "0.8" serde = { version = "1", features = ["derive"] } diff --git a/docs/adr/ADR-359-e-means-shared-clustering.md b/docs/adr/ADR-359-e-means-shared-clustering.md index d4decba3c6..cff693fa71 100644 --- a/docs/adr/ADR-359-e-means-shared-clustering.md +++ b/docs/adr/ADR-359-e-means-shared-clustering.md @@ -189,8 +189,10 @@ WASM wrapper keeps JSON for the small config and returns vectors as owned typed arrays, releasing its temporary Rust handle in `finally`. Tests check repeated fits, error-path cleanup, and output survival after WASM memory growth. -On the local AMD EPYC 9V74 environment, five interleaved native repetitions -showed these median fit times for last-epoch-mean finalization: +The author's run on an AMD EPYC 9V74 environment, with five interleaved native +repetitions, recorded these median fit times for last-epoch-mean finalization. +The "Before" build is a pre-optimization version of this crate that is not in +the repository, so these ratios cannot be re-run from the tree: | Synthetic input (n × d, clusters) | Before | After | Speedup | |---|---:|---:|---:| @@ -205,13 +207,36 @@ on the 768D fixture reduced peak additional requested heap from 721,664 to 525,312 bytes. Last-epoch-mean mode may retain a little more scratch capacity; allocation-event reduction is distinct from peak-memory reduction. -Node 24 WASM median-of-seven fit times were 36.19→15.00 ms (2.41×) for an +In the same author run, Node 24 WASM median-of-seven fit times were 36.19→15.00 ms (2.41×) for an 8192 × 64, 16-cluster fixture and 84.09→61.57 ms (1.37×) for one million scalar rows with one cluster. Both match baseline centroids, assignments and MSE. Comparing JSON and typed output using the same optimized kernel measured 75.97→58.41 ms on the million-row fixture; this includes the whole fit and materialization, not just conversion time. +Independent review reproduction (2026-11-11, ruvultra, Rust 1.99.1 with the +workspace release profile for both sides, one pinned core, five interleaved +rounds of five repetitions). The baseline is this tree with partial-distance +pruning disabled (`nearest` always takes the scalar path), so it isolates the +pruning change only. It does not include the other optimizations above: + +| Synthetic input (n × d, clusters) | Pruning off | Pruning on | Speedup | +|---|---:|---:|---:| +| Clustered embeddings (4096 × 128, 64) | 57.55 ms | 36.40 ms | 1.58× | +| Diffuse embeddings (2048 × 768, 32) | 97.95 ms | 98.30 ms | 1.00× | +| 8D PQ (8192 × 8, 256) | 28.83 ms | 28.80 ms | 1.00× | +| Duplicate/zero rows (2048 × 32, 64) | 3.65 ms | 1.44 ms | 2.54× | + +The npm `benchmark` 8192 × 64, 16-cluster fixture measured 17.0→7.5 ms +(2.26×) against a pruning-off WASM build. All eight native digests +(centroid bits and assignments) equal both the pruning-off build and the +digests recorded in the measurement artifact, and the WASM fixtures matched +with zero label or centroid differences. The shipped `.wasm` rebuilds +byte-for-byte from this source with Rust 1.99.1 and wasm-bindgen 0.2.125 +(`--remap-path-prefix` set to the author's home directory). Treat the author +ratios above as that environment's results against an earlier build, and the +reproduction as the checked effect of pruning. + The [measurement artifact](../research/e-means/performance-2026-11-11.json) records shapes, options, raw native samples, environment, allocation definitions, and source/artifact checksums. The native benchmark example and npm `benchmark` diff --git a/npm/package-lock.json b/npm/package-lock.json index d70995b342..9ca843f88d 100644 --- a/npm/package-lock.json +++ b/npm/package-lock.json @@ -19465,13 +19465,15 @@ "engines": { "node": ">=18.0.0" }, + "dependencies": { + "@ruvector/e-means": "0.1.0" + }, "optionalDependencies": { "ruvector-core-darwin-arm64": "0.1.34", "ruvector-core-darwin-x64": "0.1.34", "ruvector-core-linux-arm64-gnu": "0.1.34", "ruvector-core-linux-x64-gnu": "0.1.34", - "ruvector-core-win32-x64-msvc": "0.1.34", - "@ruvector/e-means": "0.1.0" + "ruvector-core-win32-x64-msvc": "0.1.34" } }, "packages/diskann": { @@ -19506,7 +19508,7 @@ "node": ">=20.0.0" }, "peerDependencies": { - "@metaharness/darwin": "0.13.0" + "@metaharness/darwin": "0.13.0 || 0.13.1" }, "peerDependenciesMeta": { "@metaharness/darwin": { diff --git a/npm/packages/core/package.json b/npm/packages/core/package.json index 0b7a6699e9..197ce9642b 100644 --- a/npm/packages/core/package.json +++ b/npm/packages/core/package.json @@ -34,8 +34,10 @@ "devDependencies": { "@napi-rs/cli": "^2.18.0" }, + "dependencies": { + "@ruvector/e-means": "0.1.0" + }, "optionalDependencies": { - "@ruvector/e-means": "0.1.0", "ruvector-core-linux-x64-gnu": "0.1.35", "ruvector-core-linux-arm64-gnu": "0.1.35", "ruvector-core-darwin-x64": "0.1.35", diff --git a/npm/packages/e-means/README.md b/npm/packages/e-means/README.md index 592b5c07bc..121ff27951 100644 --- a/npm/packages/e-means/README.md +++ b/npm/packages/e-means/README.md @@ -1,5 +1,7 @@ # @ruvector/e-means +![e-means training loop: rows are assigned in mini-batches, EMA counts and sums move the centroids with a cosine-decaying step, a dead centroid is revived by splitting a busy donor, and the last epoch mean gives the codebook](https://raw.githubusercontent.com/ruvnet/ruvector/main/npm/packages/e-means/assets/e-means-flow.svg) + Portable WebAssembly bindings for the shared `ruvector-e-means` Rust crate, based on [e-means (arXiv:2611.09501v1)](https://arxiv.org/abs/2611.09501v1). Uses EMA counts and sums, cosine annealing, dead-cluster splitting and last-epoch mean finalization. ```js @@ -25,7 +27,7 @@ From a source checkout: install the `wasm32-unknown-unknown` Rust target and `wa `npm run benchmark -- --baseline /path/to/previous/package --repeats 7` measures median fit and prediction time on one million scalar rows and an embedding codebook workload. It also compares JSON and typed output on the same current Rust kernel. The baseline argument is optional; retain the previous package's module and WASM together. Run benchmarks without other compute workloads; results describe the current machine and these fixtures. -RuVector exposes the same API through `ruvector/clustering.mjs`; ruv-FANN exposes `ruv-fann/clustering`. Both depend on this package. +RuVector exposes the same API through `ruvector/clustering.mjs` once a `ruvector` release that depends on this package is published. A ruv-FANN facade is proposed separately and is not released. The package also ships explicit integration subpaths: @@ -33,7 +35,7 @@ The package also ships explicit integration subpaths: |---|---| | `@ruvector/e-means/quantization` | Train PQ subspace codebooks, encode byte codes, decode vectors, and validate JSON codebooks | | `@ruvector/e-means/ivf` | Train coarse clusters and construct stable posting lists | -| `@ruvector/e-means/metaharness` | Measure held-out clustering quality and run bounded numeric evolution with actual Darwin 0.13.0 | +| `@ruvector/e-means/metaharness` | Measure held-out clustering quality and run bounded numeric evolution with Darwin 0.13.0 or 0.13.1 | | `@ruvector/e-means/cloudflare` | Create an authenticated Worker and explicitly persist/export centroid codebooks through R2/Vectorize bindings | | `@ruvector/e-means/runtime` | Initialize from explicit bytes or a precompiled WASM module without importing Node loaders | | `@ruvector/e-means/cloudflare/build` | Build the shipped Worker example locally; requires development tooling, and never deploys | @@ -55,7 +57,7 @@ const inverted = partition(data, 2, options); const firstPosting = postingList(inverted, 0); ``` -MetaHarness tuning requires the optional peer `@metaharness/darwin@0.13.0`. +MetaHarness tuning requires the optional peer `@metaharness/darwin` at 0.13.0 or 0.13.1. `createClusteringEvaluator` uses snapshotted, nonoverlapping training/holdout arrays and explicit evaluation/work/deadline budgets. `tuneClustering` calls the real numeric SDK, verifies observed records, and returns a recommendation with @@ -85,14 +87,15 @@ prefixes/namespaces because upserts do not delete stale IDs. PQ records have a different layout and are rejected by these single-codebook helpers. The shipped `examples/cloudflare` contains a static-WASM builder and Wrangler -configuration. `npm run build:cloudflare` only writes local artifacts. Qualify +configuration. `npm run build:cloudflare` only writes local artifacts. `buildWorker` needs `esbuild` +installed by the caller and reports a clear error without it. Qualify with `npm ci --ignore-scripts --workspaces=false`, `npm test`, `npm run typecheck`, `npm run test:consumer`, and `npm run test:ecosystem`. Local workerd/R2 tests use development dependencies; Vectorize is covered by binding fixtures. No hosted deployment is implied. -These integrations are also exposed by `@ruvector/core`, `@ruvector/all`, the -current `@ruvector/wasm` source, `ruvector`, `ruv-fann`, and -`@ruv-fann/integrations` through their clustering subpaths. See +The `@ruvector/core`, `@ruvector/all`, `@ruvector/wasm` and `ruvector` sources +add clustering subpaths over these integrations; they reach users only with +those packages' next releases. See [ADR-360](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-360-e-means-ecosystem-integrations.md) for the exact paths, release order, and validation scope. diff --git a/npm/packages/e-means/assets/e-means-flow.svg b/npm/packages/e-means/assets/e-means-flow.svg new file mode 100644 index 0000000000..670e13813f --- /dev/null +++ b/npm/packages/e-means/assets/e-means-flow.svg @@ -0,0 +1,62 @@ + + e-means training loop + Three groups of points. Centroids start on random rows and move toward each group as mini-batches update exponential moving averages of counts and sums with a cosine-decaying step. A dead centroid is revived by splitting a busy donor, and the last epoch's mean gives the final codebook. + + + + + + + + + + + + + + + + + + + + + + + + e-means: mini-batch k-means with EMA statistics + + + + 1. assign batch rows, EMA-update counts and sums + + + + 2. step size follows a cosine schedule + + + + 3. every 5 updates, split a busy donor into a dead slot + + + + 4. finalize with the last epoch's mean (or the EMA) + Same Rust kernel natively and in WebAssembly; seeded and deterministic. + diff --git a/npm/packages/e-means/examples/cloudflare/build.mjs b/npm/packages/e-means/examples/cloudflare/build.mjs index 987052ff2b..e253422332 100644 --- a/npm/packages/e-means/examples/cloudflare/build.mjs +++ b/npm/packages/e-means/examples/cloudflare/build.mjs @@ -1,4 +1,3 @@ -import { build } from 'esbuild'; import { mkdir, copyFile } from 'node:fs/promises'; import { join, resolve } from 'node:path'; import { fileURLToPath, pathToFileURL } from 'node:url'; @@ -6,6 +5,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url'; /** Build a static-WASM Worker locally; this function never deploys anything. */ export async function buildWorker(outDirectory, entryPoint = fileURLToPath(new URL('./worker.mjs', import.meta.url))) { if (typeof outDirectory !== 'string' || outDirectory.length === 0) throw new TypeError('outDirectory is required'); + let build; + try { ({ build } = await import('esbuild')); } + catch (cause) { throw new Error('buildWorker requires esbuild; install it as a development dependency', { cause }); } const output = resolve(outDirectory), wasm = join(output, 'e-means.wasm'); await mkdir(output, { recursive: true }); await copyFile(fileURLToPath(import.meta.resolve('@ruvector/e-means/wasm')), wasm); diff --git a/npm/packages/e-means/integrations/metaharness.d.ts b/npm/packages/e-means/integrations/metaharness.d.ts index cf7168b873..58db50b900 100644 --- a/npm/packages/e-means/integrations/metaharness.d.ts +++ b/npm/packages/e-means/integrations/metaharness.d.ts @@ -99,7 +99,7 @@ export interface ClusteringTuningOptions extends ClusteringEvaluationOptions { export interface ClusteringTuningReceipt extends Omit { schema: 'e-means.clustering-tuning/1'; - engine: { package: '@metaharness/darwin'; version: '0.13.0'; algorithm: 'evolveNumeric' }; + engine: { package: '@metaharness/darwin'; version: '0.13.0' | '0.13.1'; algorithm: 'evolveNumeric' }; baseline: ClusteringTrial; winner: ClusteringTrial; recommendation: EMeansOptions; @@ -111,5 +111,5 @@ export interface ClusteringTuningReceipt extends Omit; diff --git a/npm/packages/e-means/integrations/metaharness.mjs b/npm/packages/e-means/integrations/metaharness.mjs index 5bcd2ab736..5a14ba0ad5 100644 --- a/npm/packages/e-means/integrations/metaharness.mjs +++ b/npm/packages/e-means/integrations/metaharness.mjs @@ -14,7 +14,7 @@ function holdoutMse(data, dimensions, centroids) { return loss / assignments.length; } -/** NumericEvaluator compatible with published Darwin0.13.0. Snapshots happen +/** NumericEvaluator compatible with published Darwin 0.13.0 and 0.13.1. Snapshots happen * synchronously before any await. The first dispatch must be the baseline. */ export function createClusteringEvaluator(options) { @@ -80,16 +80,19 @@ export function createClusteringEvaluator(options) { return Object.freeze(evaluator); } +// Exact versions whose numeric API this integration was run against. +const DARWIN_VERSIONS = ['0.13.0', '0.13.1']; + async function loadDarwin() { const { readFile } = await import('node:fs/promises'); let entry; try { entry = import.meta.resolve('@metaharness/darwin'); } - catch (cause) { throw new Error('tuneClustering requires optional peer @metaharness/darwin@0.13.0', { cause }); } + catch (cause) { throw new Error(`tuneClustering requires optional peer @metaharness/darwin (${DARWIN_VERSIONS.join(' or ')})`, { cause }); } const manifest = JSON.parse(await readFile(new URL('../package.json', entry), 'utf8')); - if (manifest.name !== '@metaharness/darwin' || manifest.version !== '0.13.0') throw new Error('Expected @metaharness/darwin 0.13.0'); + if (manifest.name !== '@metaharness/darwin' || !DARWIN_VERSIONS.includes(manifest.version)) throw new Error(`Expected @metaharness/darwin ${DARWIN_VERSIONS.join(' or ')}`); const { evolveNumeric } = await import('@metaharness/darwin'); if (typeof evolveNumeric !== 'function') throw new Error('Darwin numeric API is unavailable'); - return evolveNumeric; + return { evolveNumeric, version: manifest.version }; } /** Run bounded, local numeric evolution. Never mutates source or applies a model. */ @@ -108,7 +111,7 @@ export async function tuneClustering(options) { const worstCaseDispatches = 1 + childrenPerGeneration + 2 * childrenPerGeneration * (generations - 1); if (worstCaseDispatches > initial.budget.maxEvaluations) throw new RangeError('Darwin worst-case dispatches exceed maxEvaluations'); if (worstCaseDispatches * initial.worstCaseWorkPerTrial > initial.budget.maxDistanceCoordinates) throw new RangeError('Darwin worst-case work exceeds maxDistanceCoordinates'); - const evolveNumeric = await loadDarwin(); + const { evolveNumeric, version: darwinVersion } = await loadDarwin(); check(); const { mkdtemp, rm } = await import('node:fs/promises'); const { tmpdir } = await import('node:os'); @@ -139,7 +142,7 @@ export async function tuneClustering(options) { let winner = result.winner ? verified(result.winner) : baseline; const winnerRejected = winner.score.regressed || winner.score.primary < baseline.score.primary; if (winnerRejected) winner = baseline; - answer = { engine: { package: '@metaharness/darwin', version: '0.13.0', algorithm: 'evolveNumeric' }, + answer = { engine: { package: '@metaharness/darwin', version: darwinVersion, algorithm: 'evolveNumeric' }, ...measured, schema: 'e-means.clustering-tuning/1', baseline, winner, recommendation: clone(winner.score.raw.fitConfig), winnerRejected, improvedOnObservedHoldout: winner.score.primary > baseline.score.primary, diff --git a/npm/packages/e-means/package-lock.json b/npm/packages/e-means/package-lock.json index 955f21d604..f5b191bec2 100644 --- a/npm/packages/e-means/package-lock.json +++ b/npm/packages/e-means/package-lock.json @@ -18,7 +18,7 @@ "node": ">=20.0.0" }, "peerDependencies": { - "@metaharness/darwin": "0.13.0" + "@metaharness/darwin": "0.13.0 || 0.13.1" }, "peerDependenciesMeta": { "@metaharness/darwin": { diff --git a/npm/packages/e-means/package.json b/npm/packages/e-means/package.json index 2e1ec03d63..8dcf9ca38f 100644 --- a/npm/packages/e-means/package.json +++ b/npm/packages/e-means/package.json @@ -1,7 +1,7 @@ { "name": "@ruvector/e-means", "version": "0.1.0", - "description": "Deterministic e-means clustering from the shared Rust core, compiled to portable WebAssembly", + "description": "Deterministic e-means (EMA k-means) clustering for vectors: Rust core compiled to WebAssembly, with PQ codebook, IVF, MetaHarness tuning and Cloudflare Worker helpers", "type": "module", "main": "./e-means.mjs", "types": "./e-means.d.ts", @@ -69,6 +69,10 @@ "node": ">=20.0.0" }, "license": "MIT", + "homepage": "https://ruv.io", + "bugs": { + "url": "https://github.com/ruvnet/ruvector/issues" + }, "repository": { "type": "git", "url": "https://github.com/ruvnet/ruvector.git", @@ -80,10 +84,18 @@ "keywords": [ "clustering", "e-means", - "ema", "k-means", + "ema", "webassembly", - "rust" + "wasm", + "rust", + "product-quantization", + "ivf", + "vector-search", + "codebook", + "embeddings", + "cloudflare-workers", + "ruvector" ], "devDependencies": { "typescript": "5.9.3", @@ -92,7 +104,7 @@ "miniflare": "4.20260730.0" }, "peerDependencies": { - "@metaharness/darwin": "0.13.0" + "@metaharness/darwin": "0.13.0 || 0.13.1" }, "peerDependenciesMeta": { "@metaharness/darwin": { From 77f6cd5198b155a3f6c9afa129b21e9569c648f1 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:02:58 -0500 Subject: [PATCH 04/19] Qualify and protect exact e-means crate and npm publication --- .github/workflows/e-means-preflight.yml | 64 +++ .../workflows/e-means-protected-release.yml | 71 ++++ .../e-means/test/browser-consumer.mjs | 1 + scripts/e-means/public-consumer.rs | 24 ++ scripts/e-means/registry.py | 94 +++++ scripts/e-means/release.py | 377 ++++++++++++++++++ scripts/e-means/test_release.py | 74 ++++ 7 files changed, 705 insertions(+) create mode 100644 .github/workflows/e-means-preflight.yml create mode 100644 .github/workflows/e-means-protected-release.yml create mode 100644 scripts/e-means/public-consumer.rs create mode 100644 scripts/e-means/registry.py create mode 100644 scripts/e-means/release.py create mode 100644 scripts/e-means/test_release.py diff --git a/.github/workflows/e-means-preflight.yml b/.github/workflows/e-means-preflight.yml new file mode 100644 index 0000000000..ee8662af49 --- /dev/null +++ b/.github/workflows/e-means-preflight.yml @@ -0,0 +1,64 @@ +name: e-means-preflight +on: + push: + branches: ['release/**'] + workflow_dispatch: {} +permissions: + contents: read +concurrency: + group: e-means-preflight-${{ github.ref }} + cancel-in-progress: true +jobs: + qualify: + runs-on: ubuntu-24.04 + timeout-minutes: 60 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '24' + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec + with: + toolchain: '1.98.1' + targets: wasm32-unknown-unknown + components: clippy + - name: Install pinned MSRV and WASM binding tools + run: | + rustup toolchain install 1.81.0 --profile minimal + cargo install wasm-bindgen-cli --version '=0.2.125' --locked --root "$RUNNER_TEMP/e-means-tools" + cargo install cargo-audit --version '=0.22.2' --locked --root "$RUNNER_TEMP/e-means-tools" + echo "$RUNNER_TEMP/e-means-tools/bin" >> "$GITHUB_PATH" + - name: Install pinned real Chromium + run: | + npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 + "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium + node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + - name: Exercise release guards + run: python3 -m unittest discover -s scripts/e-means -p 'test_*.py' -v + - name: Build exact archives and execute native, installed, Worker and browser consumers + run: python3 scripts/e-means/release.py seal --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-seal" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: e-means-candidate-${{ github.sha }} + path: ${{ runner.temp }}/e-means-seal + if-no-files-found: error + retention-days: 90 + node20: + needs: qualify + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '20.0.0' + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 + with: + name: e-means-candidate-${{ github.sha }} + path: ${{ runner.temp }}/e-means-node20 + - name: Exercise sealed portable runtime and PQ/IVF on the advertised Node minimum + run: python3 scripts/e-means/release.py node20 --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-node20" diff --git a/.github/workflows/e-means-protected-release.yml b/.github/workflows/e-means-protected-release.yml new file mode 100644 index 0000000000..89d98f5ed7 --- /dev/null +++ b/.github/workflows/e-means-protected-release.yml @@ -0,0 +1,71 @@ +name: e-means-protected-release +on: + workflow_dispatch: + inputs: + expected_sha: + description: Exact main SHA qualified by the release-branch e-means preflight + required: true + type: string +permissions: + contents: read + issues: read + actions: read +concurrency: + group: protected-e-means-release + cancel-in-progress: false +jobs: + publish: + runs-on: ubuntu-24.04 + timeout-minutes: 45 + environment: npm-production + permissions: + contents: read + issues: read + actions: read + id-token: write + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '24' + registry-url: https://registry.npmjs.org + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec + with: + toolchain: '1.98.1' + - name: Verify exact source and select sealed pre-main artifacts + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + run: python3 scripts/e-means/release.py download --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - name: Publish only the verified crate and npm archive + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_API_KEY }} + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: python3 scripts/e-means/release.py publish --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - name: Install real Chromium for the public archive consumer + run: | + npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 + "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium + node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + - name: Test fresh public registry consumers without publication credentials + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + run: python3 scripts/e-means/release.py verify-public --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + if: always() + with: + name: e-means-publication-${{ github.sha }} + if-no-files-found: error + path: | + ${{ runner.temp }}/e-means-publication/ci.json + ${{ runner.temp }}/e-means-publication/candidate/candidate.json + ${{ runner.temp }}/e-means-publication/candidate/FILES.json + ${{ runner.temp }}/e-means-publication/public/* + ${{ runner.temp }}/e-means-publication/publication.json + ${{ runner.temp }}/e-means-publication/public-consumers.json + ${{ runner.temp }}/e-means-publication/fresh/command-*.log diff --git a/npm/packages/e-means/test/browser-consumer.mjs b/npm/packages/e-means/test/browser-consumer.mjs index a38a304477..0d77e9f57e 100644 --- a/npm/packages/e-means/test/browser-consumer.mjs +++ b/npm/packages/e-means/test/browser-consumer.mjs @@ -25,6 +25,7 @@ try { const routes = new Map([ ['/e-means.mjs', ['../e-means.mjs', 'application/javascript']], + ['/runtime.mjs', ['../runtime.mjs', 'application/javascript']], ['/wasm/ruvector_e_means.js', ['../wasm/ruvector_e_means.js', 'application/javascript']], ['/wasm/ruvector_e_means_bg.wasm', ['../wasm/ruvector_e_means_bg.wasm', 'application/wasm']], ]); diff --git a/scripts/e-means/public-consumer.rs b/scripts/e-means/public-consumer.rs new file mode 100644 index 0000000000..1e0675d091 --- /dev/null +++ b/scripts/e-means/public-consumer.rs @@ -0,0 +1,24 @@ +use ruvector_e_means::{fit, Config, IvfPartition, ProductQuantizer}; + +fn main() { + let mut checks = 0; + let mut check = |ok: bool| { assert!(ok); checks += 1; }; + let data = [0.0f32, 2.0, 4.0, 6.0, 8.0, 10.0]; + let config = Config { clusters: 1, epochs: 2, batch_size: Some(2), ..Config::default() }; + let model = fit(&data, 2, &config).unwrap(); + check(model.centroids == [4.0, 6.0]); + check(model.assignments == [0, 0, 0]); + check(model.predict(&data).unwrap() == [0, 0, 0]); + check(model.mse.is_finite() && model.mse >= 0.0); + check(model.updates == 4); + check(fit(&data, 2, &config).unwrap().centroids == model.centroids); + check(fit(&[f32::NAN], 1, &config).is_err()); + let pq = ProductQuantizer::fit(&data, 2, 2, &config).unwrap(); + check(pq.encode(&data).unwrap() == [0, 0, 0, 0, 0, 0]); + check(pq.decode(&[0, 0]).unwrap() == [4.0, 6.0]); + check(pq.decode(&[255, 0]).is_err()); + let ivf = IvfPartition::fit(&data, 2, &config).unwrap(); + check(ivf.posting(0).unwrap() == [0, 1, 2]); + check(ivf.posting(1).is_err()); + println!("E_MEANS_PUBLIC_CHECKS={checks}"); +} diff --git a/scripts/e-means/registry.py b/scripts/e-means/registry.py new file mode 100644 index 0000000000..bcb853fbd0 --- /dev/null +++ b/scripts/e-means/registry.py @@ -0,0 +1,94 @@ +# Registry transport adapted from ruvnet/ruv-FANN scripts/publish-candidates.py. +# MIT; exact-archive upload protocol: https://doc.rust-lang.org/cargo/reference/registry-web-api.html#publish +import hashlib, json, tarfile, time, tomllib, urllib.error, urllib.request +USER_AGENT = "ruvector-e-means-release (https://github.com/ruvnet/RuVector)" +VISIBILITY_TIMEOUT = 600 +VISIBILITY_DELAYS = (5, 10, 20, 30, 60) + +def sha(data): + return hashlib.sha256(data).hexdigest() + + +def metadata(archive): + with tarfile.open(archive) as tar: + names = tar.getnames() + manifests = [n for n in names if n.count('/') == 1 and n.endswith('/Cargo.toml')] + if len(manifests) != 1: + raise ValueError('Expected exactly one normalized manifest') + prefix = manifests[0].rsplit('/', 1)[0] + document = tomllib.loads(tar.extractfile(manifests[0]).read().decode()) + package = document['package'] + if prefix != package['name'] + '-' + package['version']: + raise ValueError('Archive identity mismatch') + result = {'name': package['name'], 'vers': package['version'], + 'deps': [], 'features': document.get('features', {}), + 'authors': package.get('authors', []), 'keywords': package.get('keywords', []), + 'categories': package.get('categories', []), 'badges': document.get('badges', {})} + for key in ['description', 'documentation', 'homepage', 'license', 'repository', 'links']: + result[key] = package.get(key) + result['license_file'] = package.get('license-file') + result['rust_version'] = package.get('rust-version') + readme = package.get('readme') + result['readme_file'] = readme if isinstance(readme, str) else None + result['readme'] = tar.extractfile(prefix + '/' + readme).read().decode() if isinstance(readme, str) else None + for target, table in [(None, document), *document.get('target', {}).items()]: + for section, kind in [('dependencies', 'normal'), ('dev-dependencies', 'dev'), ('build-dependencies', 'build')]: + for name, dep in table.get(section, {}).items(): + dep = {'version': dep} if isinstance(dep, str) else dep + if 'version' not in dep or 'path' in dep or 'git' in dep: + raise ValueError('Unpublishable dependency: ' + name) + result['deps'].append({'name': dep.get('package', name), 'version_req': dep['version'], + 'features': dep.get('features', []), 'optional': dep.get('optional', False), + 'default_features': dep.get('default-features', True), 'target': target, 'kind': kind, + 'registry': dep.get('registry-index'), 'explicit_name_in_toml': name if 'package' in dep else None}) + return result + + +def downloaded(name, version): + url = f'https://static.crates.io/crates/{name}/{name}-{version}.crate' + try: + with urllib.request.urlopen(urllib.request.Request(url, headers={'User-Agent': USER_AGENT}), timeout=60) as response: + return response.read() + except urllib.error.HTTPError as error: + if error.code in (403, 404): + return None + raise + + +def wait_public(name, version, timeout=VISIBILITY_TIMEOUT, sleep=time.sleep, clock=time.monotonic): + """Return the public crate bytes, or None if static.crates.io still lacks them past the deadline.""" + deadline = clock() + timeout + attempt = 0 + while True: + public = downloaded(name, version) + if public is not None: + return public + remaining = deadline - clock() + if remaining <= 0: + return None + sleep(min(VISIBILITY_DELAYS[min(attempt, len(VISIBILITY_DELAYS) - 1)], remaining)) + attempt += 1 + + +def confirm_version_absent(name, version): + """Static S3 403/404 alone is not authority to treat an immutable version as new.""" + key = name.lower() + if len(key) <= 2: + relative = f'{len(key)}/{key}' + elif len(key) == 3: + relative = f'3/{key[0]}/{key}' + else: + relative = f'{key[:2]}/{key[2:4]}/{key}' + request = urllib.request.Request('https://index.crates.io/' + relative, headers={'User-Agent': USER_AGENT}) + try: + with urllib.request.urlopen(request, timeout=60) as response: + records = [json.loads(line) for line in response.read().decode().splitlines() if line.strip()] + except urllib.error.HTTPError as error: + if error.code == 404: + return + raise + if not records or any(not isinstance(row.get('vers'), str) or row.get('name', '').lower() != key for row in records): + raise ValueError('Invalid or empty sparse registry index: ' + name) + if any(row['vers'] == version for row in records): + raise ValueError(f'Published version {name} {version} exists in the index but its public archive is unavailable; nothing may be uploaded') + diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py new file mode 100644 index 0000000000..c0edb415ff --- /dev/null +++ b/scripts/e-means/release.py @@ -0,0 +1,377 @@ +#!/usr/bin/env python3 +"""Seal, publish and independently exercise the two shared e-means archives.""" +import argparse +import base64 +import hashlib +import json +import os +from pathlib import Path +import re +import shutil +import struct +import subprocess +import sys +import tarfile +import time +import urllib.error +import urllib.request +import zipfile + +import registry + +ROOT = Path(__file__).resolve().parents[2] +REPO = 'ruvnet/RuVector' +PREFLIGHT = '.github/workflows/e-means-preflight.yml' +PUBLISHER = 'e-means-protected-release' +VERSION = '0.1.0' +NPM_NAME = '@ruvector/e-means' +CRATE = 'ruvector-e-means' + + +def sha(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def gh(endpoint): + return json.loads(subprocess.check_output(['gh', 'api', endpoint], text=True)) + + +def pages(endpoint, field): + result = [] + for page in range(1, 101): + rows = gh(endpoint + ('&' if '?' in endpoint else '?') + f'per_page=100&page={page}')[field] + result.extend(rows) + if len(rows) < 100: + return result + raise ValueError('Pagination exceeded explicit bound') + + +def identity(source): + if not re.fullmatch('[a-f0-9]{40}', source): + raise ValueError('Expected full immutable SHA') + if subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=ROOT, text=True).strip() != source: + raise ValueError('Checkout source mismatch') + if subprocess.check_output(['git', 'status', '--porcelain'], cwd=ROOT): + raise ValueError('Source checkout must be clean') + + +def protected(source): + identity(source) + expected = ('true', PUBLISHER, 'refs/heads/main', source) + actual = tuple(os.environ.get(k) for k in ('GITHUB_ACTIONS', 'GITHUB_WORKFLOW', 'GITHUB_REF', 'GITHUB_SHA')) + if actual != expected: + raise ValueError('Publication requires the protected main workflow') + if gh(f'repos/{REPO}/git/ref/heads/main')['object']['sha'] != source: + raise ValueError('Main moved since qualification') + if gh(f'repos/{REPO}/issues?state=open&labels=release-blocker&per_page=1'): + raise ValueError('Open release blockers') + + +def execute(args, cwd, base, commands, kind=None, env=None): + log = base / f'command-{len(commands)}.log' + with log.open('w') as stream: + result = subprocess.run(args, cwd=cwd, stdout=stream, stderr=subprocess.STDOUT, + env={**os.environ, **(env or {})}) + output = log.read_text(errors='replace') + record = {'args': [str(x) for x in args], 'exitCode': result.returncode, + 'log': log.name, 'logSha256': sha(log)} + commands.append(record) + if result.returncode: + print(output[-12000:], file=sys.stderr) + raise RuntimeError(f'Command failed: {args}') + if kind == 'rust': + summaries = re.findall(r'test result: ok\. (\d+) passed; (\d+) failed; (\d+) ignored;', output) + if not summaries or not sum(int(x[0]) for x in summaries) or any(int(x[1]) or int(x[2]) for x in summaries): + raise ValueError('Rust qualification needs executed tests with no failures or ignored tests') + record['testsPassed'] = sum(int(x[0]) for x in summaries) + if kind == 'node': + passed = re.search(r'^# pass (\d+)$', output, re.M) + if not passed or int(passed[1]) == 0 or any(not re.search(rf'^# {key} 0$', output, re.M) for key in ('fail', 'cancelled', 'skipped', 'todo')): + raise ValueError('Node qualification needs nonzero tests and zero failures/skips/todos') + record['testsPassed'] = int(passed[1]) + if kind == 'browser': + if 'Chromium browser consumer passed:' not in output: + raise ValueError('Actual browser numerical qualification missing') + record['browserPassed'] = True + print(json.dumps(record), flush=True) + return output + + +def extract(archive, destination): + with tarfile.open(archive) as handle: + for member in handle.getmembers(): + path = Path(member.name) + if path.is_absolute() or '..' in path.parts or not (member.isfile() or member.isdir()): + raise ValueError('Unsafe archive member') + handle.extractall(destination, filter='data') + + +def seal(source, base): + identity(source) + base.mkdir(parents=True, exist_ok=False) + commands = [] + env = {'RUSTFLAGS': '', 'CARGO_BUILD_JOBS': '2', 'CARGO_INCREMENTAL': '0', 'CARGO_PROFILE_DEV_DEBUG': '0'} + for args in ( + ['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests'], + ['cargo', 'test', '--locked', '-p', 'ruvector-core', '--no-default-features', '--test', 'e_means_quantization'], + ['cargo', 'test', '--locked', '-p', 'ruvector-pq-search', '--test', 'e_means'], + ['cargo', 'test', '--locked', '-p', 'ruvector-rairs', '--test', 'e_means'], + ): + execute(args, ROOT, base, commands, 'rust', env) + execute(['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], ROOT, base, commands, env=env) + target = base / 'package-build' + execute(['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', str(target)], ROOT, base, commands, env=env) + crate = base / f'{CRATE}-{VERSION}.crate' + shutil.copyfile(target / 'package' / crate.name, crate) + extract(crate, base / 'extracted') + rust = base / 'extracted' / f'{CRATE}-{VERSION}' + execute(['cargo', 'audit', '--file', str(rust / 'Cargo.lock'), '--deny', 'warnings'], ROOT, base, commands, env=env) + execute(['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--no-default-features', '--target-dir', str(base / 'msrv-target')], ROOT, base, commands, env=env) + execute(['cargo', 'test', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--all-features', '--lib', '--tests', '--target-dir', str(base / 'packed-target')], ROOT, base, commands, 'rust', env) + npm = base / 'npm-source' + shutil.copytree(ROOT / 'npm/packages/e-means', npm, ignore=shutil.ignore_patterns('node_modules', '*.tgz')) + execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=env) + version = subprocess.check_output(['wasm-bindgen', '--version'], text=True).strip() + if version != 'wasm-bindgen 0.2.125': + raise ValueError('Wrong wasm-bindgen CLI') + execute(['wasm-bindgen', str(base / 'wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm'), '--target', 'web', '--out-dir', str(npm / 'wasm'), '--out-name', 'ruvector_e_means'], ROOT, base, commands) + execute(['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], npm, base, commands) + execute(['npm', 'audit', '--audit-level=low', '--workspaces=false'], npm, base, commands) + execute(['npm', 'test', '--workspaces=false'], npm, base, commands, 'node') + execute(['npm', 'run', 'typecheck', '--workspaces=false'], npm, base, commands) + execute(['npm', 'run', 'test:consumer', '--workspaces=false'], npm, base, commands) + execute(['npm', 'run', 'test:browser', '--workspaces=false'], npm, base, commands, 'browser') + execute(['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', str(base)], npm, base, commands) + archive = base / f'ruvector-e-means-{VERSION}.tgz' + if not archive.is_file(): + raise ValueError('Missing packed npm archive') + identity(source) + receipt = {'schema': 'ruvector.e-means-candidate/1', 'sourceSha': source, + 'commands': commands, 'artifacts': {crate.name: sha(crate), archive.name: sha(archive)}, + 'wasmSha256': sha(npm / 'wasm/ruvector_e_means_bg.wasm'), 'wasmBindgen': version} + (base / 'candidate.json').write_text(json.dumps(receipt, indent=2) + '\n') + # Transfer only immutable archives, actual logs and the test harness; no + # build trees or source checkout become publication authority. + harness = base / 'harness' + shutil.copytree(npm / 'test', harness / 'test') + shutil.copyfile(npm / 'package.json', harness / 'package.json') + shutil.copyfile(npm / 'package-lock.json', harness / 'package-lock.json') + for path in base.iterdir(): + if path.is_dir() and path != harness: + shutil.rmtree(path) + files = {str(p.relative_to(base)): sha(p) for p in base.rglob('*') if p.is_file()} + (base / 'FILES.json').write_text(json.dumps(files, indent=2) + '\n') + + +def validate_candidate(base, source): + files = json.loads((base / 'FILES.json').read_text()) + for relative, digest in files.items(): + path = (base / relative).resolve() + if not path.is_relative_to(base.resolve()) or sha(path) != digest: + raise ValueError('Candidate payload changed: ' + relative) + receipt = json.loads((base / 'candidate.json').read_text()) + if receipt.get('schema') != 'ruvector.e-means-candidate/1' or receipt.get('sourceSha') != source: + raise ValueError('Candidate identity mismatch') + commands = receipt.get('commands', []) + if len(commands) < 15 or any(c['exitCode'] != 0 or sha(base / c['log']) != c['logSha256'] for c in commands): + raise ValueError('Missing or failed real qualification commands') + if not any(c.get('browserPassed') for c in commands) or sum(c.get('testsPassed', 0) for c in commands) <= 0: + raise ValueError('Missing executed numerical/browser tests') + expected = {f'{CRATE}-{VERSION}.crate', f'ruvector-e-means-{VERSION}.tgz'} + if set(receipt['artifacts']) != expected or any(sha(base / name) != digest for name, digest in receipt['artifacts'].items()): + raise ValueError('Archive seal mismatch') + data = registry.metadata(base / f'{CRATE}-{VERSION}.crate') + if (data['name'], data['vers']) != (CRATE, VERSION): + raise ValueError('Rust archive identity mismatch') + with tarfile.open(base / f'ruvector-e-means-{VERSION}.tgz') as tar: + manifest = json.load(tar.extractfile('package/package.json')) + if (manifest['name'], manifest['version']) != (NPM_NAME, VERSION): + raise ValueError('npm archive identity mismatch') + if hashlib.sha256(tar.extractfile('package/wasm/ruvector_e_means_bg.wasm').read()).hexdigest() != receipt['wasmSha256']: + raise ValueError('Bundled WASM differs from actual source build') + return receipt + + +def node20(source, base): + identity(source) + validate_candidate(base, source) + consumer = base.parent / 'node20-consumer' + consumer.mkdir() + (consumer / 'package.json').write_text('{"private":true,"type":"module"}') + commands = [] + execute(['npm', 'install', '--ignore-scripts', '--offline', '--no-audit', '--no-fund', str(base / f'ruvector-e-means-{VERSION}.tgz')], consumer, consumer, commands) + installed = consumer / 'node_modules/@ruvector/e-means' + shutil.copytree(base / 'harness/test', installed / 'test') + selected = ['e-means', 'runtime', 'typed-bridge', 'quantization', 'ivf'] + execute(['node', '--test', *[str(installed / f'test/{name}.test.mjs') for name in selected]], consumer, consumer, commands, 'node') + + +def select_and_download(source, base): + protected(source) + runs = pages(f'repos/{REPO}/actions/workflows/e-means-preflight.yml/runs?head_sha={source}&event=push', 'workflow_runs') + runs = [r for r in runs if r['head_branch'].startswith('release/') and r['path'] == PREFLIGHT and r['status'] == 'completed' and r['conclusion'] == 'success'] + if not runs: + raise ValueError('No successful exact-source pre-main candidate') + run = max(runs, key=lambda r: r['id']) + jobs = pages(f'repos/{REPO}/actions/runs/{run["id"]}/jobs?filter=latest', 'jobs') + if not jobs or any(j['status'] != 'completed' or j['conclusion'] != 'success' for j in jobs): + raise ValueError('Incomplete or failed preflight jobs') + artifacts = pages(f'repos/{REPO}/actions/runs/{run["id"]}/artifacts', 'artifacts') + matches = [a for a in artifacts if a['name'] == f'e-means-candidate-{source}' and not a['expired']] + if len(matches) != 1 or not re.fullmatch('sha256:[a-f0-9]{64}', matches[0].get('digest', '')): + raise ValueError('Missing unique sealed candidate') + item = matches[0] + base.mkdir(parents=True, exist_ok=False) + archive = base / 'candidate.zip' + with archive.open('xb') as out: + subprocess.run(['gh', 'api', f'repos/{REPO}/actions/artifacts/{item["id"]}/zip'], stdout=out, check=True) + if 'sha256:' + sha(archive) != item['digest']: + raise ValueError('GitHub artifact digest mismatch') + with zipfile.ZipFile(archive) as handle: + for name in handle.namelist(): + path = Path(name) + if path.is_absolute() or '..' in path.parts: + raise ValueError('Unsafe candidate ZIP') + handle.extractall(base / 'candidate') + (base / 'ci.json').write_text(json.dumps({'sourceSha': source, 'runId': run['id'], 'jobs': jobs, 'artifact': item}, indent=2)) + validate_candidate(base / 'candidate', source) + + +def npm_public(): + url = f'https://registry.npmjs.org/@ruvector%2fe-means/{VERSION}' + try: + with urllib.request.urlopen(url, timeout=60) as response: + metadata = json.load(response) + except urllib.error.HTTPError as error: + if error.code == 404: + return None + raise + if (metadata.get('name'), metadata.get('version')) != (NPM_NAME, VERSION): + raise ValueError('Registry npm identity mismatch') + with urllib.request.urlopen(metadata['dist']['tarball'], timeout=60) as response: + data = response.read() + integrity = 'sha512-' + base64.b64encode(hashlib.sha512(data).digest()).decode() + if integrity != metadata['dist']['integrity']: + raise ValueError('npm public integrity mismatch') + return data + + +def publish(source, base): + protected(source) + candidate = base / 'candidate' + receipt = validate_candidate(candidate, source) + crate = candidate / f'{CRATE}-{VERSION}.crate' + npm = candidate / f'ruvector-e-means-{VERSION}.tgz' + # Check both immutable registries before either upload. + rust_bytes = registry.downloaded(CRATE, VERSION) + npm_bytes = npm_public() + for path, data in ((crate, rust_bytes), (npm, npm_bytes)): + if data is not None and hashlib.sha256(data).hexdigest() != sha(path): + raise ValueError('Public version already exists with different bytes: ' + path.name) + if rust_bytes is None: + registry.confirm_version_absent(CRATE, VERSION) + token = os.environ.get('CARGO_REGISTRY_TOKEN') + if not token: + raise ValueError('Missing crate publication credential') + meta = json.dumps(registry.metadata(crate)).encode() + payload = crate.read_bytes() + body = struct.pack(' Date: Wed, 11 Nov 2026 13:07:56 -0500 Subject: [PATCH 05/19] Require official registry source and exact lock checksum in public consumer --- scripts/e-means/release.py | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py index c0edb415ff..90253d58e8 100644 --- a/scripts/e-means/release.py +++ b/scripts/e-means/release.py @@ -326,8 +326,14 @@ def verify_public(source, base): checks = re.search(r'E_MEANS_PUBLIC_CHECKS=(\d+)', output) if not checks or int(checks[1]) < 10: raise ValueError('Public Rust numerical checks missing') - lock = (cargo / 'Cargo.lock').read_text() - if receipt['artifacts'][f'{CRATE}-{VERSION}.crate'] not in lock: + metadata = json.loads(execute(['cargo', 'metadata', '--locked', '--format-version', '1', '--manifest-path', str(cargo / 'Cargo.toml')], cargo, fresh, commands, env=env)) + resolved = [p for p in metadata['packages'] if p['name'] == CRATE and p['version'] == VERSION] + if len(resolved) != 1 or resolved[0].get('source') != 'registry+https://github.com/rust-lang/crates.io-index': + raise ValueError('Fresh Cargo consumer did not resolve the official registry package') + import tomllib + lock = tomllib.loads((cargo / 'Cargo.lock').read_text()) + locked = [p for p in lock['package'] if p['name'] == CRATE and p['version'] == VERSION] + if len(locked) != 1 or locked[0].get('checksum') != receipt['artifacts'][f'{CRATE}-{VERSION}.crate']: raise ValueError('Fresh Cargo consumer did not resolve sealed public checksum') npm = fresh / 'npm' npm.mkdir() From 97b36c2806d40dbba8b933b6b7619aa04a06fc00 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:11:12 -0500 Subject: [PATCH 06/19] Preserve workspace WASM optimization profile in archived-source builds --- scripts/e-means/release.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py index 90253d58e8..6d10ef22aa 100644 --- a/scripts/e-means/release.py +++ b/scripts/e-means/release.py @@ -75,6 +75,9 @@ def execute(args, cwd, base, commands, kind=None, env=None): output = log.read_text(errors='replace') record = {'args': [str(x) for x in args], 'exitCode': result.returncode, 'log': log.name, 'logSha256': sha(log)} + if env: + # Only this explicit, non-secret build override map is recorded. + record['environment'] = env commands.append(record) if result.returncode: print(output[-12000:], file=sys.stderr) @@ -130,7 +133,10 @@ def seal(source, base): execute(['cargo', 'test', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--all-features', '--lib', '--tests', '--target-dir', str(base / 'packed-target')], ROOT, base, commands, 'rust', env) npm = base / 'npm-source' shutil.copytree(ROOT / 'npm/packages/e-means', npm, ignore=shutil.ignore_patterns('node_modules', '*.tgz')) - execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=env) + wasm_env = {**env, 'CARGO_PROFILE_RELEASE_OPT_LEVEL': '3', 'CARGO_PROFILE_RELEASE_LTO': 'fat', + 'CARGO_PROFILE_RELEASE_CODEGEN_UNITS': '1', 'CARGO_PROFILE_RELEASE_STRIP': 'true', + 'CARGO_PROFILE_RELEASE_PANIC': 'unwind'} + execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=wasm_env) version = subprocess.check_output(['wasm-bindgen', '--version'], text=True).strip() if version != 'wasm-bindgen 0.2.125': raise ValueError('Wrong wasm-bindgen CLI') @@ -148,7 +154,10 @@ def seal(source, base): identity(source) receipt = {'schema': 'ruvector.e-means-candidate/1', 'sourceSha': source, 'commands': commands, 'artifacts': {crate.name: sha(crate), archive.name: sha(archive)}, - 'wasmSha256': sha(npm / 'wasm/ruvector_e_means_bg.wasm'), 'wasmBindgen': version} + 'wasmSha256': sha(npm / 'wasm/ruvector_e_means_bg.wasm'), 'wasmBindgen': version, + 'rustcVersion': subprocess.check_output(['rustc', '--version'], text=True).strip(), + 'cargoVersion': subprocess.check_output(['cargo', '--version'], text=True).strip(), + 'nodeVersion': subprocess.check_output(['node', '--version'], text=True).strip()} (base / 'candidate.json').write_text(json.dumps(receipt, indent=2) + '\n') # Transfer only immutable archives, actual logs and the test harness; no # build trees or source checkout become publication authority. From 342cfdc59d22bbb5705f3e31e3371b4028054acd Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:12:22 -0500 Subject: [PATCH 07/19] Require exact e-means qualification commands and reparse owned logs --- scripts/e-means/release.py | 190 ++++++++++++++++++++------ scripts/e-means/test_release.py | 235 ++++++++++++++++++++++++++++++++ 2 files changed, 380 insertions(+), 45 deletions(-) diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py index 6d10ef22aa..360ca0df48 100644 --- a/scripts/e-means/release.py +++ b/scripts/e-means/release.py @@ -67,14 +67,87 @@ def protected(source): raise ValueError('Open release blockers') -def execute(args, cwd, base, commands, kind=None, env=None): +# These are the required publication gates, not caller-provided receipt claims. +# Portable paths keep the owned command proof valid after the sealed artifact is +# transferred from the preflight runner to the protected publication runner. +SOURCE = '${SOURCE}' +CANDIDATE = '${CANDIDATE}' +RUST = f'{CANDIDATE}/extracted/{CRATE}-{VERSION}' +QUALIFICATION = { + 'rust-source': (['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests'], SOURCE, 'rust', 4), + 'core-adapter': (['cargo', 'test', '--locked', '-p', 'ruvector-core', '--no-default-features', '--test', 'e_means_quantization'], SOURCE, 'rust', 1), + 'pq-adapter': (['cargo', 'test', '--locked', '-p', 'ruvector-pq-search', '--test', 'e_means'], SOURCE, 'rust', 1), + 'rairs-adapter': (['cargo', 'test', '--locked', '-p', 'ruvector-rairs', '--test', 'e_means'], SOURCE, 'rust', 1), + 'clippy': (['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], SOURCE, None, None), + 'rust-package': (['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', f'{CANDIDATE}/package-build'], SOURCE, None, None), + 'rust-audit': (['cargo', 'audit', '--file', f'{RUST}/Cargo.lock', '--deny', 'warnings'], SOURCE, None, None), + 'rust-msrv': (['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--no-default-features', '--target-dir', f'{CANDIDATE}/msrv-target'], SOURCE, None, None), + 'rust-packed': (['cargo', 'test', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--all-features', '--lib', '--tests', '--target-dir', f'{CANDIDATE}/packed-target'], SOURCE, 'rust', 4), + 'wasm-build': (['cargo', 'build', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', f'{CANDIDATE}/wasm-target'], SOURCE, None, None), + 'wasm-bindgen': (['wasm-bindgen', f'{CANDIDATE}/wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm', '--target', 'web', '--out-dir', f'{CANDIDATE}/npm-source/wasm', '--out-name', 'ruvector_e_means'], SOURCE, None, None), + 'npm-install': (['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], f'{CANDIDATE}/npm-source', None, None), + 'npm-audit': (['npm', 'audit', '--audit-level=low', '--workspaces=false'], f'{CANDIDATE}/npm-source', None, None), + 'npm-tests': (['npm', 'test', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'node', None), + 'npm-types': (['npm', 'run', 'typecheck', '--workspaces=false'], f'{CANDIDATE}/npm-source', None, None), + 'npm-consumer': (['npm', 'run', 'test:consumer', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'consumer', None), + 'npm-browser': (['npm', 'run', 'test:browser', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'browser', None), + 'npm-package': (['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', CANDIDATE], f'{CANDIDATE}/npm-source', None, None), +} +BROWSER_MARKER = 'Chromium browser consumer passed: default WASM fetch, fit, predict and numerical oracle' +CONSUMER_MARKERS = ( + 'Installed archive runtime/evaluator passed without the optional SDK', + 'Offline installed MetaHarness/WASM consumer passed', + 'Offline installed integration declarations passed', +) + + +def evidence(output, kind, summaries=None): + """Derive evidence from actual command output, including when validating it.""" + if kind == 'rust': + lines = re.findall(r'^test result: (.+)$', output, re.M) + parsed = [re.fullmatch(r'ok\. (\d+) passed; (\d+) failed; (\d+) ignored; (\d+) measured; (\d+) filtered out; finished in .+', line) for line in lines] + if (not parsed or (summaries is not None and len(parsed) != summaries) + or any(not row or int(row[1]) == 0 or any(int(row[n]) for n in range(2, 6)) for row in parsed)): + raise ValueError('Rust qualification needs nonzero test suites with no failures, ignored tests, measured or filtered tests') + return {'testsPassed': sum(int(row[1]) for row in parsed)} + if kind == 'node': + values = {key: re.findall(rf'^# {key} (\d+)$', output, re.M) for key in ('pass', 'fail', 'cancelled', 'skipped', 'todo')} + if any(len(rows) != 1 for rows in values.values()) or int(values['pass'][0]) == 0 or any(int(values[key][0]) for key in ('fail', 'cancelled', 'skipped', 'todo')): + raise ValueError('Node qualification needs nonzero tests and zero failures/skips/todos') + return {'testsPassed': int(values['pass'][0])} + if kind == 'browser': + if output.splitlines().count(BROWSER_MARKER) != 1: + raise ValueError('Actual browser numerical qualification missing') + return {'browserPassed': True} + if kind == 'consumer': + if any(output.splitlines().count(marker) != 1 for marker in CONSUMER_MARKERS): + raise ValueError('Installed archive consumer numerical/type qualification missing') + return {} + + +def portable(value, base): + value = str(value) + for directory, placeholder in ((base, CANDIDATE), (ROOT, SOURCE)): + prefix = str(directory) + if value == prefix or value.startswith(prefix + '/'): + return placeholder + value[len(prefix):] + return value + + +def execute(args, cwd, base, commands, kind=None, env=None, role=None): + record = {'args': [str(x) for x in args]} + summaries = None + if role is not None: + expected_args, expected_cwd, expected_kind, summaries = QUALIFICATION[role] + record.update(role=role, args=[portable(x, base) for x in args], cwd=portable(cwd, base)) + if (record['args'], record['cwd'], kind) != (expected_args, expected_cwd, expected_kind): + raise ValueError('Owned qualification command differs from required role: ' + role) log = base / f'command-{len(commands)}.log' with log.open('w') as stream: result = subprocess.run(args, cwd=cwd, stdout=stream, stderr=subprocess.STDOUT, env={**os.environ, **(env or {})}) output = log.read_text(errors='replace') - record = {'args': [str(x) for x in args], 'exitCode': result.returncode, - 'log': log.name, 'logSha256': sha(log)} + record.update(exitCode=result.returncode, log=log.name, logSha256=sha(log)) if env: # Only this explicit, non-secret build override map is recorded. record['environment'] = env @@ -82,20 +155,7 @@ def execute(args, cwd, base, commands, kind=None, env=None): if result.returncode: print(output[-12000:], file=sys.stderr) raise RuntimeError(f'Command failed: {args}') - if kind == 'rust': - summaries = re.findall(r'test result: ok\. (\d+) passed; (\d+) failed; (\d+) ignored;', output) - if not summaries or not sum(int(x[0]) for x in summaries) or any(int(x[1]) or int(x[2]) for x in summaries): - raise ValueError('Rust qualification needs executed tests with no failures or ignored tests') - record['testsPassed'] = sum(int(x[0]) for x in summaries) - if kind == 'node': - passed = re.search(r'^# pass (\d+)$', output, re.M) - if not passed or int(passed[1]) == 0 or any(not re.search(rf'^# {key} 0$', output, re.M) for key in ('fail', 'cancelled', 'skipped', 'todo')): - raise ValueError('Node qualification needs nonzero tests and zero failures/skips/todos') - record['testsPassed'] = int(passed[1]) - if kind == 'browser': - if 'Chromium browser consumer passed:' not in output: - raise ValueError('Actual browser numerical qualification missing') - record['browserPassed'] = True + record.update(evidence(output, kind, summaries)) print(json.dumps(record), flush=True) return output @@ -114,40 +174,40 @@ def seal(source, base): base.mkdir(parents=True, exist_ok=False) commands = [] env = {'RUSTFLAGS': '', 'CARGO_BUILD_JOBS': '2', 'CARGO_INCREMENTAL': '0', 'CARGO_PROFILE_DEV_DEBUG': '0'} - for args in ( - ['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests'], - ['cargo', 'test', '--locked', '-p', 'ruvector-core', '--no-default-features', '--test', 'e_means_quantization'], - ['cargo', 'test', '--locked', '-p', 'ruvector-pq-search', '--test', 'e_means'], - ['cargo', 'test', '--locked', '-p', 'ruvector-rairs', '--test', 'e_means'], + for role, args in ( + ('rust-source', ['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests']), + ('core-adapter', ['cargo', 'test', '--locked', '-p', 'ruvector-core', '--no-default-features', '--test', 'e_means_quantization']), + ('pq-adapter', ['cargo', 'test', '--locked', '-p', 'ruvector-pq-search', '--test', 'e_means']), + ('rairs-adapter', ['cargo', 'test', '--locked', '-p', 'ruvector-rairs', '--test', 'e_means']), ): - execute(args, ROOT, base, commands, 'rust', env) - execute(['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], ROOT, base, commands, env=env) + execute(args, ROOT, base, commands, 'rust', env, role=role) + execute(['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], ROOT, base, commands, env=env, role='clippy') target = base / 'package-build' - execute(['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', str(target)], ROOT, base, commands, env=env) + execute(['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', str(target)], ROOT, base, commands, env=env, role='rust-package') crate = base / f'{CRATE}-{VERSION}.crate' shutil.copyfile(target / 'package' / crate.name, crate) extract(crate, base / 'extracted') rust = base / 'extracted' / f'{CRATE}-{VERSION}' - execute(['cargo', 'audit', '--file', str(rust / 'Cargo.lock'), '--deny', 'warnings'], ROOT, base, commands, env=env) - execute(['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--no-default-features', '--target-dir', str(base / 'msrv-target')], ROOT, base, commands, env=env) - execute(['cargo', 'test', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--all-features', '--lib', '--tests', '--target-dir', str(base / 'packed-target')], ROOT, base, commands, 'rust', env) + execute(['cargo', 'audit', '--file', str(rust / 'Cargo.lock'), '--deny', 'warnings'], ROOT, base, commands, env=env, role='rust-audit') + execute(['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--no-default-features', '--target-dir', str(base / 'msrv-target')], ROOT, base, commands, env=env, role='rust-msrv') + execute(['cargo', 'test', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--all-features', '--lib', '--tests', '--target-dir', str(base / 'packed-target')], ROOT, base, commands, 'rust', env, role='rust-packed') npm = base / 'npm-source' shutil.copytree(ROOT / 'npm/packages/e-means', npm, ignore=shutil.ignore_patterns('node_modules', '*.tgz')) wasm_env = {**env, 'CARGO_PROFILE_RELEASE_OPT_LEVEL': '3', 'CARGO_PROFILE_RELEASE_LTO': 'fat', 'CARGO_PROFILE_RELEASE_CODEGEN_UNITS': '1', 'CARGO_PROFILE_RELEASE_STRIP': 'true', 'CARGO_PROFILE_RELEASE_PANIC': 'unwind'} - execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=wasm_env) + execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=wasm_env, role='wasm-build') version = subprocess.check_output(['wasm-bindgen', '--version'], text=True).strip() if version != 'wasm-bindgen 0.2.125': raise ValueError('Wrong wasm-bindgen CLI') - execute(['wasm-bindgen', str(base / 'wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm'), '--target', 'web', '--out-dir', str(npm / 'wasm'), '--out-name', 'ruvector_e_means'], ROOT, base, commands) - execute(['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], npm, base, commands) - execute(['npm', 'audit', '--audit-level=low', '--workspaces=false'], npm, base, commands) - execute(['npm', 'test', '--workspaces=false'], npm, base, commands, 'node') - execute(['npm', 'run', 'typecheck', '--workspaces=false'], npm, base, commands) - execute(['npm', 'run', 'test:consumer', '--workspaces=false'], npm, base, commands) - execute(['npm', 'run', 'test:browser', '--workspaces=false'], npm, base, commands, 'browser') - execute(['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', str(base)], npm, base, commands) + execute(['wasm-bindgen', str(base / 'wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm'), '--target', 'web', '--out-dir', str(npm / 'wasm'), '--out-name', 'ruvector_e_means'], ROOT, base, commands, role='wasm-bindgen') + execute(['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], npm, base, commands, role='npm-install') + execute(['npm', 'audit', '--audit-level=low', '--workspaces=false'], npm, base, commands, role='npm-audit') + execute(['npm', 'test', '--workspaces=false'], npm, base, commands, 'node', role='npm-tests') + execute(['npm', 'run', 'typecheck', '--workspaces=false'], npm, base, commands, role='npm-types') + execute(['npm', 'run', 'test:consumer', '--workspaces=false'], npm, base, commands, 'consumer', role='npm-consumer') + execute(['npm', 'run', 'test:browser', '--workspaces=false'], npm, base, commands, 'browser', role='npm-browser') + execute(['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', str(base)], npm, base, commands, role='npm-package') archive = base / f'ruvector-e-means-{VERSION}.tgz' if not archive.is_file(): raise ValueError('Missing packed npm archive') @@ -172,20 +232,59 @@ def seal(source, base): (base / 'FILES.json').write_text(json.dumps(files, indent=2) + '\n') -def validate_candidate(base, source): +def validate_payload(base): files = json.loads((base / 'FILES.json').read_text()) + if not isinstance(files, dict) or not files: + raise ValueError('Missing complete candidate FILES manifest') + paths = list(base.rglob('*')) + if any(path.is_symlink() for path in paths): + raise ValueError('Candidate payload may not contain symlinks') + actual = {path.relative_to(base).as_posix() for path in paths if path.is_file() and path != base / 'FILES.json'} + if set(files) != actual: + raise ValueError('Candidate FILES manifest must cover the complete payload') for relative, digest in files.items(): path = (base / relative).resolve() - if not path.is_relative_to(base.resolve()) or sha(path) != digest: + if (not isinstance(relative, str) or Path(relative).as_posix() != relative + or '\\' in relative or not path.is_relative_to(base.resolve()) + or not re.fullmatch('[a-f0-9]{64}', str(digest)) or sha(path) != digest): raise ValueError('Candidate payload changed: ' + relative) + # The transferred harness is reviewed source at this exact checkout, not a + # second authority supplied by the artifact producer. + npm = ROOT / 'npm/packages/e-means' + expected_harness = {'harness/' + name: sha(npm / name) for name in ('package.json', 'package-lock.json')} + expected_harness.update({'harness/test/' + path.relative_to(npm / 'test').as_posix(): sha(path) + for path in (npm / 'test').rglob('*') if path.is_file()}) + if {name: digest for name, digest in files.items() if name.startswith('harness/')} != expected_harness: + raise ValueError('Candidate harness differs from exact-source checkout') + return files + + +def validate_qualification(base, receipt, files): + commands = receipt.get('commands', []) + if not isinstance(commands, list) or [c.get('role') for c in commands] != list(QUALIFICATION): + raise ValueError('Missing, duplicated or reordered required qualification roles') + for index, command in enumerate(commands): + role = command['role'] + args, cwd, kind, summaries = QUALIFICATION[role] + log = f'command-{index}.log' + if (command.get('args') != args or command.get('cwd') != cwd or type(command.get('exitCode')) is not int or command['exitCode'] != 0 + or command.get('log') != log or files.get(log) != command.get('logSha256')): + raise ValueError('Qualification command/log differs from required role: ' + role) + derived = evidence((base / log).read_text(errors='replace'), kind, summaries) + claims = {key: command[key] for key in ('testsPassed', 'browserPassed') if key in command} + if claims != derived or any(type(claims[key]) is not type(value) for key, value in derived.items()): + raise ValueError('Qualification claims differ from actual owned log: ' + role) + + +def validate_candidate(base, source): + files = validate_payload(base) receipt = json.loads((base / 'candidate.json').read_text()) - if receipt.get('schema') != 'ruvector.e-means-candidate/1' or receipt.get('sourceSha') != source: + if (not re.fullmatch('[a-f0-9]{40}', source) + or receipt.get('schema') != 'ruvector.e-means-candidate/1' or receipt.get('sourceSha') != source): raise ValueError('Candidate identity mismatch') - commands = receipt.get('commands', []) - if len(commands) < 15 or any(c['exitCode'] != 0 or sha(base / c['log']) != c['logSha256'] for c in commands): - raise ValueError('Missing or failed real qualification commands') - if not any(c.get('browserPassed') for c in commands) or sum(c.get('testsPassed', 0) for c in commands) <= 0: - raise ValueError('Missing executed numerical/browser tests') + if receipt.get('wasmBindgen') != 'wasm-bindgen 0.2.125': + raise ValueError('Candidate WASM binding tool differs from pinned version') + validate_qualification(base, receipt, files) expected = {f'{CRATE}-{VERSION}.crate', f'ruvector-e-means-{VERSION}.tgz'} if set(receipt['artifacts']) != expected or any(sha(base / name) != digest for name, digest in receipt['artifacts'].items()): raise ValueError('Archive seal mismatch') @@ -385,6 +484,7 @@ def main(): elif args.mode == 'node20': node20(args.expected_sha, base) else: + identity(args.expected_sha) validate_candidate(base, args.expected_sha) diff --git a/scripts/e-means/test_release.py b/scripts/e-means/test_release.py index f5c315296b..63eddf388c 100644 --- a/scripts/e-means/test_release.py +++ b/scripts/e-means/test_release.py @@ -1,4 +1,10 @@ +import base64 import contextlib +import copy +import hashlib +import json +import shutil +import tarfile import importlib.util import io import os @@ -6,6 +12,7 @@ import sys import tempfile import unittest +from types import SimpleNamespace from unittest.mock import patch sys.path.insert(0, str(Path(__file__).parent)) @@ -70,5 +77,233 @@ def test_immutable_sha_validation_rejects_branches(self): release.identity('main') +RUST_RESULT = 'test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.01s\n' +NODE_RESULT = '# pass 7\n# fail 0\n# cancelled 0\n# skipped 0\n# todo 0\n' + + +class CandidateProof(unittest.TestCase): + """Synthetic archives/logs are validator mutation fixtures, never receipts.""" + + def setUp(self): + self.temporary = tempfile.TemporaryDirectory() + self.addCleanup(self.temporary.cleanup) + self.base = Path(self.temporary.name) + npm = release.ROOT / 'npm/packages/e-means' + shutil.copytree(npm / 'test', self.base / 'harness/test') + for name in ('package.json', 'package-lock.json'): + shutil.copyfile(npm / name, self.base / 'harness' / name) + self.commands = [] + for role, (args, cwd, kind, suites) in release.QUALIFICATION.items(): + log = f'command-{len(self.commands)}.log' + text = (RUST_RESULT * suites if kind == 'rust' else NODE_RESULT if kind == 'node' + else release.BROWSER_MARKER + '\n' if kind == 'browser' + else '\n'.join(release.CONSUMER_MARKERS) if kind == 'consumer' else 'command completed\n') + (self.base / log).write_text(text) + command = {'role': role, 'args': list(args), 'cwd': cwd, 'exitCode': 0, + 'log': log, 'logSha256': release.sha(self.base / log)} + if kind in ('rust', 'node'): + command['testsPassed'] = 3 * suites if kind == 'rust' else 7 + if kind == 'browser': + command['browserPassed'] = True + self.commands.append(command) + crate = f'{release.CRATE}-{release.VERSION}.crate' + npm_archive = f'ruvector-e-means-{release.VERSION}.tgz' + wasm = b'validator-fixture-not-an-executable-wasm' + self.archive(crate, {f'{release.CRATE}-{release.VERSION}/Cargo.toml': + f'[package]\nname="{release.CRATE}"\nversion="{release.VERSION}"\n'.encode()}) + self.archive(npm_archive, {'package/package.json': json.dumps({'name': release.NPM_NAME, 'version': release.VERSION}).encode(), + 'package/wasm/ruvector_e_means_bg.wasm': wasm}) + self.receipt = {'schema': 'ruvector.e-means-candidate/1', 'sourceSha': 'a' * 40, + 'commands': self.commands, 'wasmBindgen': 'wasm-bindgen 0.2.125', + 'wasmSha256': hashlib.sha256(wasm).hexdigest(), + 'artifacts': {name: release.sha(self.base / name) for name in (crate, npm_archive)}} + self.write_receipt() + + def archive(self, filename, members): + with tarfile.open(self.base / filename, 'w:gz') as tar: + for name, data in members.items(): + member = tarfile.TarInfo(name) + member.size = len(data) + tar.addfile(member, io.BytesIO(data)) + + def manifest(self): + files = {path.relative_to(self.base).as_posix(): release.sha(path) + for path in self.base.rglob('*') if path.is_file() and path.name != 'FILES.json'} + (self.base / 'FILES.json').write_text(json.dumps(files)) + return files + + def write_receipt(self): + (self.base / 'candidate.json').write_text(json.dumps(self.receipt)) + self.manifest() + + def validate(self): + return release.validate_candidate(self.base, 'a' * 40) + + def test_valid_complete_candidate_survives_transfer_to_new_directory(self): + self.assertEqual(self.validate()['sourceSha'], 'a' * 40) + with tempfile.TemporaryDirectory() as moved: + destination = Path(moved) / 'transferred' + shutil.copytree(self.base, destination) + self.assertEqual(release.validate_candidate(destination, 'a' * 40)['commands'], self.commands) + + def test_real_seal_command_wiring_matches_required_roles_before_transfer(self): + # Exercise the producer orchestration and its argument/cwd checks without + # building code or writing to a registry. Only subprocess effects are fake. + generated = self.base / 'generated' + original_logs = {role: (self.base / command['log']).read_text() + for role, command in zip(release.QUALIFICATION, self.commands)} + wasm = b'validator-fixture-not-an-executable-wasm' + + def subprocess_fixture(args, cwd, stdout, stderr, env): + index = int(Path(stdout.name).stem.split('-')[1]) + role = list(release.QUALIFICATION)[index] + stdout.write(original_logs[role]) + if role == 'rust-package': + destination = generated / 'package-build/package' + destination.mkdir(parents=True) + shutil.copyfile(self.base / f'{release.CRATE}-{release.VERSION}.crate', destination / f'{release.CRATE}-{release.VERSION}.crate') + if role == 'wasm-bindgen': + destination = generated / 'npm-source/wasm/ruvector_e_means_bg.wasm' + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_bytes(wasm) + if role == 'npm-package': + shutil.copyfile(self.base / f'ruvector-e-means-{release.VERSION}.tgz', generated / f'ruvector-e-means-{release.VERSION}.tgz') + return SimpleNamespace(returncode=0) + + with patch.object(release, 'identity'), patch.object(release.subprocess, 'run', side_effect=subprocess_fixture), \ + patch.object(release.subprocess, 'check_output', return_value='wasm-bindgen 0.2.125'), \ + contextlib.redirect_stdout(io.StringIO()): + release.seal('a' * 40, generated) + validated = release.validate_candidate(generated, 'a' * 40) + self.assertEqual([row['role'] for row in validated['commands']], list(release.QUALIFICATION)) + with tempfile.TemporaryDirectory() as moved: + destination = Path(moved) / 'candidate' + shutil.copytree(generated, destination) + self.assertEqual(release.validate_candidate(destination, 'a' * 40), validated) + + def test_missing_duplicate_reordered_or_unknown_roles_fail(self): + valid = copy.deepcopy(self.commands) + for mutation in ('missing', 'duplicate', 'reordered', 'unknown'): + with self.subTest(mutation=mutation): + self.commands[:] = copy.deepcopy(valid) + if mutation == 'missing': self.commands.pop(8) + elif mutation == 'duplicate': self.commands[8] = copy.deepcopy(self.commands[7]) + elif mutation == 'reordered': self.commands[7], self.commands[8] = self.commands[8], self.commands[7] + else: self.commands[8]['role'] = 'not-required' + self.write_receipt() + with self.assertRaisesRegex(ValueError, 'required qualification roles'): + self.validate() + + def test_wrong_args_cwd_failed_exit_unowned_or_reused_logs_fail(self): + valid = copy.deepcopy(self.commands) + for key, value in [('args', ['cargo', '--version']), ('cwd', '/tmp/other-source'), + ('exitCode', 1), ('exitCode', False), ('log', '../command-0.log'), ('log', 'command-0.log'), + ('logSha256', 'b' * 64)]: + with self.subTest(key=key, value=value): + self.commands[:] = copy.deepcopy(valid) + self.commands[8][key] = value + self.write_receipt() + with self.assertRaisesRegex(ValueError, 'command/log differs'): + self.validate() + + def test_forged_evidence_claims_fail_even_when_outer_manifest_is_resealed(self): + valid = copy.deepcopy(self.commands) + for index, key, value in [(8, 'testsPassed', 9000), (16, 'browserPassed', False), (16, 'browserPassed', 1), (4, 'testsPassed', 1), (0, 'browserPassed', True)]: + with self.subTest(index=index, key=key): + self.commands[:] = copy.deepcopy(valid) + self.commands[index][key] = value + self.write_receipt() + with self.assertRaisesRegex(ValueError, 'claims differ'): + self.validate() + + def replace_log(self, index, text): + log = self.base / self.commands[index]['log'] + log.write_text(text) + self.commands[index]['logSha256'] = release.sha(log) + self.write_receipt() + + def test_zero_missing_failed_ignored_measured_and_filtered_rust_suites_fail(self): + for text in ('no tests executed\n', RUST_RESULT, RUST_RESULT.replace('3 passed', '0 passed') * 4, + RUST_RESULT.replace('0 failed', '1 failed') * 4, + RUST_RESULT.replace('0 ignored', '1 ignored') * 4, + RUST_RESULT.replace('0 measured', '1 measured') * 4, + RUST_RESULT.replace('0 filtered out', '1 filtered out') * 4): + with self.subTest(text=text): + self.replace_log(8, text) + with self.assertRaisesRegex(ValueError, 'Rust qualification'): + self.validate() + + def test_zero_failed_cancelled_skipped_todo_and_duplicate_node_summaries_fail(self): + variants = [NODE_RESULT.replace('# pass 7', '# pass 0'), NODE_RESULT * 2] + variants.extend(NODE_RESULT.replace(f'# {key} 0', f'# {key} 1') for key in ('fail', 'cancelled', 'skipped', 'todo')) + for text in variants: + with self.subTest(text=text): + self.replace_log(13, text) + with self.assertRaisesRegex(ValueError, 'Node qualification'): + self.validate() + + def test_successful_browser_and_installed_consumer_without_oracles_fail(self): + for index, text, message in [(16, 'browser started', 'Actual browser'), + (15, release.CONSUMER_MARKERS[0], 'Installed archive consumer')]: + with self.subTest(index=index): + self.replace_log(index, text) + with self.assertRaisesRegex(ValueError, message): + self.validate() + # Restore this role before testing the next one. + original = release.BROWSER_MARKER if index == 16 else '\n'.join(release.CONSUMER_MARKERS) + self.replace_log(index, original) + + def test_files_manifest_cannot_omit_logs_or_accept_unlisted_payload(self): + files = self.manifest() + files.pop('command-0.log') + (self.base / 'FILES.json').write_text(json.dumps(files)) + with self.assertRaisesRegex(ValueError, 'complete payload'): + self.validate() + self.manifest() + (self.base / 'unlisted.txt').write_text('not covered') + with self.assertRaisesRegex(ValueError, 'complete payload'): + self.validate() + + def test_harness_changes_cannot_be_hidden_by_resealing_manifest(self): + (self.base / 'harness/test/browser-consumer.mjs').write_text('console.log("passed")') + self.manifest() + with self.assertRaisesRegex(ValueError, 'exact-source checkout'): + self.validate() + + def test_manifest_traversal_and_symlinks_fail(self): + files = self.manifest() + files['../outside.txt'] = 'a' * 64 + (self.base / 'FILES.json').write_text(json.dumps(files)) + with self.assertRaisesRegex(ValueError, 'complete payload'): + self.validate() + self.manifest() + (self.base / 'alias').symlink_to(self.base / 'command-0.log') + with self.assertRaisesRegex(ValueError, 'symlinks'): + self.validate() + + def test_source_and_pinned_binding_tool_are_required(self): + for key, value, message in [('sourceSha', 'b' * 40, 'identity'), ('wasmBindgen', 'wasm-bindgen 0.2.124', 'pinned version')]: + with self.subTest(key=key): + original = self.receipt[key] + self.receipt[key] = value + self.write_receipt() + with self.assertRaisesRegex(ValueError, message): + self.validate() + self.receipt[key] = original + + +class RegistryIntegrity(unittest.TestCase): + def test_npm_public_bytes_must_match_registry_sha512_integrity(self): + payload = b'canonical public archive fixture' + integrity = 'sha512-' + base64.b64encode(hashlib.sha512(payload).digest()).decode() + metadata = {'name': release.NPM_NAME, 'version': release.VERSION, + 'dist': {'tarball': 'https://registry.npmjs.org/archive.tgz', 'integrity': integrity}} + with patch.object(release.urllib.request, 'urlopen', side_effect=[io.BytesIO(json.dumps(metadata).encode()), io.BytesIO(payload)]): + self.assertEqual(release.npm_public(), payload) + with patch.object(release.urllib.request, 'urlopen', side_effect=[io.BytesIO(json.dumps(metadata).encode()), io.BytesIO(payload + b'changed')]): + with self.assertRaisesRegex(ValueError, 'integrity mismatch'): + release.npm_public() + + if __name__ == '__main__': unittest.main() From 4005c4c1ff51f5e8152f6d79538a845a9d74ef2a Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:32:50 -0500 Subject: [PATCH 08/19] Release shared e-means crate and portable npm runtime before consumers --- .github/workflows/e-means-preflight.yml | 64 + .../workflows/e-means-protected-release.yml | 79 + Cargo.lock | 11 + Cargo.toml | 2 + crates/ruvector-e-means/Cargo.toml | 31 + crates/ruvector-e-means/LICENSE | 21 + crates/ruvector-e-means/README.md | 34 + crates/ruvector-e-means/examples/benchmark.rs | 177 ++ crates/ruvector-e-means/src/config.rs | 115 ++ crates/ruvector-e-means/src/distance.rs | 189 ++ crates/ruvector-e-means/src/ivf.rs | 155 ++ crates/ruvector-e-means/src/lib.rs | 81 + crates/ruvector-e-means/src/quantization.rs | 181 ++ crates/ruvector-e-means/src/trainer.rs | 242 +++ crates/ruvector-e-means/src/wasm.rs | 92 + crates/ruvector-e-means/tests/clustering.rs | 234 +++ crates/ruvector-e-means/tests/ivf.rs | 103 ++ crates/ruvector-e-means/tests/quantization.rs | 113 ++ docs/adr/ADR-359-e-means-shared-clustering.md | 263 +++ .../ADR-360-e-means-ecosystem-integrations.md | 186 ++ docs/e-means-release.md | 50 + .../e-means/integrations-qualification.json | 70 + .../e-means/performance-2026-11-11.json | 406 +++++ npm/package-lock.json | 1530 ++++++++++++++++ npm/package.json | 4 + npm/packages/e-means/.gitignore | 2 + npm/packages/e-means/LICENSE | 21 + npm/packages/e-means/README.md | 101 ++ npm/packages/e-means/assets/e-means-flow.svg | 62 + npm/packages/e-means/e-means.d.ts | 33 + npm/packages/e-means/e-means.mjs | 29 + .../e-means/examples/cloudflare/build.d.ts | 5 + .../e-means/examples/cloudflare/build.mjs | 25 + .../e-means/examples/cloudflare/worker.mjs | 9 + .../examples/cloudflare/wrangler.jsonc | 9 + npm/packages/e-means/examples/metaharness.mjs | 16 + .../e-means/integrations/cloudflare.d.ts | 58 + .../e-means/integrations/cloudflare.mjs | 72 + .../e-means/integrations/cloudflare/http.mjs | 59 + .../integrations/cloudflare/storage.mjs | 78 + .../integrations/cloudflare/validation.mjs | 107 ++ .../integrations/clustering-validation.mjs | 111 ++ npm/packages/e-means/integrations/ivf.d.ts | 16 + npm/packages/e-means/integrations/ivf.mjs | 65 + .../e-means/integrations/metaharness.d.ts | 115 ++ .../e-means/integrations/metaharness.mjs | 154 ++ .../e-means/integrations/quantization.d.ts | 29 + .../e-means/integrations/quantization.mjs | 150 ++ npm/packages/e-means/package-lock.json | 1534 +++++++++++++++++ npm/packages/e-means/package.json | 120 ++ npm/packages/e-means/runtime.d.ts | 4 + npm/packages/e-means/runtime.mjs | 96 ++ npm/packages/e-means/scripts/build.mjs | 23 + .../e-means/scripts/check-artifact.mjs | 11 + npm/packages/e-means/test/benchmark.mjs | 111 ++ .../e-means/test/browser-consumer.mjs | 91 + .../e-means/test/cloudflare-storage.test.mjs | 108 ++ .../e-means/test/cloudflare-tsconfig.json | 12 + npm/packages/e-means/test/cloudflare-types.ts | 25 + .../e-means/test/cloudflare-workerd.test.mjs | 83 + npm/packages/e-means/test/cloudflare.test.mjs | 96 ++ npm/packages/e-means/test/e-means.test.mjs | 135 ++ .../e-means/test/ecosystem-consumers.mjs | 99 ++ npm/packages/e-means/test/ivf.test.mjs | 67 + .../e-means/test/metaharness.test.mjs | 128 ++ npm/packages/e-means/test/packed-consumer.mjs | 88 + .../e-means/test/quantization-types.mts | 19 + .../e-means/test/quantization.test.mjs | 136 ++ npm/packages/e-means/test/runtime.test.mjs | 40 + npm/packages/e-means/test/tsconfig.json | 12 + .../e-means/test/typed-bridge.test.mjs | 70 + npm/packages/e-means/test/types.ts | 32 + npm/packages/e-means/wasm-module.d.ts | 3 + .../e-means/wasm/ruvector_e_means.d.ts | 83 + npm/packages/e-means/wasm/ruvector_e_means.js | 456 +++++ .../e-means/wasm/ruvector_e_means_bg.wasm | Bin 0 -> 142782 bytes .../wasm/ruvector_e_means_bg.wasm.d.ts | 19 + scripts/e-means/github_release.py | 294 ++++ scripts/e-means/public-consumer.rs | 24 + scripts/e-means/registry.py | 94 + scripts/e-means/release.py | 486 ++++++ scripts/e-means/test_github_release.py | 327 ++++ scripts/e-means/test_release.py | 313 ++++ 83 files changed, 10998 insertions(+) create mode 100644 .github/workflows/e-means-preflight.yml create mode 100644 .github/workflows/e-means-protected-release.yml create mode 100644 crates/ruvector-e-means/Cargo.toml create mode 100644 crates/ruvector-e-means/LICENSE create mode 100644 crates/ruvector-e-means/README.md create mode 100644 crates/ruvector-e-means/examples/benchmark.rs create mode 100644 crates/ruvector-e-means/src/config.rs create mode 100644 crates/ruvector-e-means/src/distance.rs create mode 100644 crates/ruvector-e-means/src/ivf.rs create mode 100644 crates/ruvector-e-means/src/lib.rs create mode 100644 crates/ruvector-e-means/src/quantization.rs create mode 100644 crates/ruvector-e-means/src/trainer.rs create mode 100644 crates/ruvector-e-means/src/wasm.rs create mode 100644 crates/ruvector-e-means/tests/clustering.rs create mode 100644 crates/ruvector-e-means/tests/ivf.rs create mode 100644 crates/ruvector-e-means/tests/quantization.rs create mode 100644 docs/adr/ADR-359-e-means-shared-clustering.md create mode 100644 docs/adr/ADR-360-e-means-ecosystem-integrations.md create mode 100644 docs/e-means-release.md create mode 100644 docs/research/e-means/integrations-qualification.json create mode 100644 docs/research/e-means/performance-2026-11-11.json create mode 100644 npm/packages/e-means/.gitignore create mode 100644 npm/packages/e-means/LICENSE create mode 100644 npm/packages/e-means/README.md create mode 100644 npm/packages/e-means/assets/e-means-flow.svg create mode 100644 npm/packages/e-means/e-means.d.ts create mode 100644 npm/packages/e-means/e-means.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/build.d.ts create mode 100644 npm/packages/e-means/examples/cloudflare/build.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/worker.mjs create mode 100644 npm/packages/e-means/examples/cloudflare/wrangler.jsonc create mode 100644 npm/packages/e-means/examples/metaharness.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare.d.ts create mode 100644 npm/packages/e-means/integrations/cloudflare.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/http.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/storage.mjs create mode 100644 npm/packages/e-means/integrations/cloudflare/validation.mjs create mode 100644 npm/packages/e-means/integrations/clustering-validation.mjs create mode 100644 npm/packages/e-means/integrations/ivf.d.ts create mode 100644 npm/packages/e-means/integrations/ivf.mjs create mode 100644 npm/packages/e-means/integrations/metaharness.d.ts create mode 100644 npm/packages/e-means/integrations/metaharness.mjs create mode 100644 npm/packages/e-means/integrations/quantization.d.ts create mode 100644 npm/packages/e-means/integrations/quantization.mjs create mode 100644 npm/packages/e-means/package-lock.json create mode 100644 npm/packages/e-means/package.json create mode 100644 npm/packages/e-means/runtime.d.ts create mode 100644 npm/packages/e-means/runtime.mjs create mode 100644 npm/packages/e-means/scripts/build.mjs create mode 100644 npm/packages/e-means/scripts/check-artifact.mjs create mode 100644 npm/packages/e-means/test/benchmark.mjs create mode 100644 npm/packages/e-means/test/browser-consumer.mjs create mode 100644 npm/packages/e-means/test/cloudflare-storage.test.mjs create mode 100644 npm/packages/e-means/test/cloudflare-tsconfig.json create mode 100644 npm/packages/e-means/test/cloudflare-types.ts create mode 100644 npm/packages/e-means/test/cloudflare-workerd.test.mjs create mode 100644 npm/packages/e-means/test/cloudflare.test.mjs create mode 100644 npm/packages/e-means/test/e-means.test.mjs create mode 100644 npm/packages/e-means/test/ecosystem-consumers.mjs create mode 100644 npm/packages/e-means/test/ivf.test.mjs create mode 100644 npm/packages/e-means/test/metaharness.test.mjs create mode 100644 npm/packages/e-means/test/packed-consumer.mjs create mode 100644 npm/packages/e-means/test/quantization-types.mts create mode 100644 npm/packages/e-means/test/quantization.test.mjs create mode 100644 npm/packages/e-means/test/runtime.test.mjs create mode 100644 npm/packages/e-means/test/tsconfig.json create mode 100644 npm/packages/e-means/test/typed-bridge.test.mjs create mode 100644 npm/packages/e-means/test/types.ts create mode 100644 npm/packages/e-means/wasm-module.d.ts create mode 100644 npm/packages/e-means/wasm/ruvector_e_means.d.ts create mode 100644 npm/packages/e-means/wasm/ruvector_e_means.js create mode 100644 npm/packages/e-means/wasm/ruvector_e_means_bg.wasm create mode 100644 npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts create mode 100644 scripts/e-means/github_release.py create mode 100644 scripts/e-means/public-consumer.rs create mode 100644 scripts/e-means/registry.py create mode 100644 scripts/e-means/release.py create mode 100644 scripts/e-means/test_github_release.py create mode 100644 scripts/e-means/test_release.py diff --git a/.github/workflows/e-means-preflight.yml b/.github/workflows/e-means-preflight.yml new file mode 100644 index 0000000000..ee8662af49 --- /dev/null +++ b/.github/workflows/e-means-preflight.yml @@ -0,0 +1,64 @@ +name: e-means-preflight +on: + push: + branches: ['release/**'] + workflow_dispatch: {} +permissions: + contents: read +concurrency: + group: e-means-preflight-${{ github.ref }} + cancel-in-progress: true +jobs: + qualify: + runs-on: ubuntu-24.04 + timeout-minutes: 60 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '24' + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec + with: + toolchain: '1.98.1' + targets: wasm32-unknown-unknown + components: clippy + - name: Install pinned MSRV and WASM binding tools + run: | + rustup toolchain install 1.81.0 --profile minimal + cargo install wasm-bindgen-cli --version '=0.2.125' --locked --root "$RUNNER_TEMP/e-means-tools" + cargo install cargo-audit --version '=0.22.2' --locked --root "$RUNNER_TEMP/e-means-tools" + echo "$RUNNER_TEMP/e-means-tools/bin" >> "$GITHUB_PATH" + - name: Install pinned real Chromium + run: | + npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 + "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium + node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + - name: Exercise release guards + run: python3 -m unittest discover -s scripts/e-means -p 'test_*.py' -v + - name: Build exact archives and execute native, installed, Worker and browser consumers + run: python3 scripts/e-means/release.py seal --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-seal" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: e-means-candidate-${{ github.sha }} + path: ${{ runner.temp }}/e-means-seal + if-no-files-found: error + retention-days: 90 + node20: + needs: qualify + runs-on: ubuntu-24.04 + timeout-minutes: 10 + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '20.0.0' + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 + with: + name: e-means-candidate-${{ github.sha }} + path: ${{ runner.temp }}/e-means-node20 + - name: Exercise sealed portable runtime and PQ/IVF on the advertised Node minimum + run: python3 scripts/e-means/release.py node20 --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-node20" diff --git a/.github/workflows/e-means-protected-release.yml b/.github/workflows/e-means-protected-release.yml new file mode 100644 index 0000000000..0046153339 --- /dev/null +++ b/.github/workflows/e-means-protected-release.yml @@ -0,0 +1,79 @@ +name: e-means-protected-release +on: + workflow_dispatch: + inputs: + expected_sha: + description: Exact main SHA qualified by the release-branch e-means preflight + required: true + type: string +permissions: + contents: read + issues: read + actions: read +concurrency: + group: protected-e-means-release + cancel-in-progress: false +jobs: + publish: + runs-on: ubuntu-24.04 + timeout-minutes: 45 + environment: npm-production + permissions: + contents: write + issues: read + actions: read + id-token: write + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 + with: + persist-credentials: false + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 + with: + node-version: '24' + registry-url: https://registry.npmjs.org + - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec + with: + toolchain: '1.98.1' + - name: Verify exact source and select sealed pre-main artifacts + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + run: python3 scripts/e-means/release.py download --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - name: Publish only the verified crate and npm archive + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + CARGO_REGISTRY_TOKEN: ${{ secrets.CRATES_API_KEY }} + NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + run: python3 scripts/e-means/release.py publish --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - name: Install real Chromium for the public archive consumer + run: | + npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 + "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium + node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + - name: Test fresh public registry consumers without publication credentials + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + run: python3 scripts/e-means/release.py verify-public --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - name: Publish exact-source GitHub release and redownload every asset + env: + GH_TOKEN: ${{ github.token }} + EXPECTED_SHA: ${{ inputs.expected_sha }} + E_MEANS_RELEASE_ENVIRONMENT: npm-production + run: python3 scripts/e-means/github_release.py --expected-sha "$EXPECTED_SHA" --directory "$RUNNER_TEMP/e-means-publication" + - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + if: always() + with: + name: e-means-publication-${{ github.sha }} + if-no-files-found: error + path: | + ${{ runner.temp }}/e-means-publication/ci.json + ${{ runner.temp }}/e-means-publication/candidate/candidate.json + ${{ runner.temp }}/e-means-publication/candidate/FILES.json + ${{ runner.temp }}/e-means-publication/public/* + ${{ runner.temp }}/e-means-publication/publication.json + ${{ runner.temp }}/e-means-publication/public-consumers.json + ${{ runner.temp }}/e-means-publication/fresh/command-*.log + ${{ runner.temp }}/e-means-publication/github-release.json + ${{ runner.temp }}/e-means-publication/github-release-assets/* diff --git a/Cargo.lock b/Cargo.lock index 9067191dff..05bb18cb73 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -9538,6 +9538,17 @@ dependencies = [ "wasm-bindgen-test", ] +[[package]] +name = "ruvector-e-means" +version = "0.1.0" +dependencies = [ + "rand_chacha 0.3.1", + "rand_core 0.6.4", + "serde", + "serde_json", + "wasm-bindgen", +] + [[package]] name = "ruvector-economy-wasm" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index e57eb682cc..adea40f9c4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -51,6 +51,8 @@ exclude = ["crates/prime-radiant", "patches/candle-core-0.8.4", "patches/candle- # unify with this workspace. The pure cores it wraps are members below. "edge", "edge/*"] members = [ + # Shared EMA clustering core and portable npm WASM engine (ADR-359). + "crates/ruvector-e-means", # ruvector Python SDK (ADR-352): PyO3 + maturin bindings. Salvaged from # the stale feature/python-sdk-m1 branch (M1 RaBitQ scope) and extended. "crates/ruvector-py", diff --git a/crates/ruvector-e-means/Cargo.toml b/crates/ruvector-e-means/Cargo.toml new file mode 100644 index 0000000000..9b457c4e2a --- /dev/null +++ b/crates/ruvector-e-means/Cargo.toml @@ -0,0 +1,31 @@ +[package] +name = "ruvector-e-means" +version = "0.1.0" +edition = "2021" +rust-version = "1.81" +license = "MIT" +description = "Deterministic CPU and WebAssembly e-means clustering with EMA centroid updates" +repository = "https://github.com/ruvnet/ruvector" +homepage = "https://ruv.io" +documentation = "https://docs.rs/ruvector-e-means" +keywords = ["clustering", "k-means", "ema", "quantization", "machine-learning"] +categories = ["algorithms", "science"] +include = ["src/**", "tests/**", "examples/**", "Cargo.toml", "LICENSE", "README.md"] + +[lib] +crate-type = ["rlib", "cdylib"] + +[features] +default = [] +serde = ["dep:serde"] +wasm = ["serde", "dep:serde_json", "dep:wasm-bindgen"] + +[dependencies] +rand_chacha = "=0.3.1" +rand_core = "=0.6.4" +serde = { version = "1.0", features = ["derive"], optional = true } +serde_json = { version = "1.0", optional = true } +wasm-bindgen = { version = "=0.2.125", optional = true } + +[dev-dependencies] +serde_json = "1.0" diff --git a/crates/ruvector-e-means/LICENSE b/crates/ruvector-e-means/LICENSE new file mode 100644 index 0000000000..2dd524ac38 --- /dev/null +++ b/crates/ruvector-e-means/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rUv + +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. diff --git a/crates/ruvector-e-means/README.md b/crates/ruvector-e-means/README.md new file mode 100644 index 0000000000..092c9b8f3f --- /dev/null +++ b/crates/ruvector-e-means/README.md @@ -0,0 +1,34 @@ +# ruvector-e-means + +![e-means training loop: rows are assigned in mini-batches, EMA counts and sums move the centroids with a cosine-decaying step, a dead centroid is revived by splitting a busy donor, and the last epoch mean gives the codebook](https://raw.githubusercontent.com/ruvnet/ruvector/main/npm/packages/e-means/assets/e-means-flow.svg) + +CPU reference implementation of [e-means (Bessa et al., 2026)](https://arxiv.org/abs/2611.09501), used by RuVector's PQ and IVF crates. MIT-licensed original Rust implementation; no upstream implementation code is copied. + +```rust +use ruvector_e_means::{fit, Config}; +let data = [1.0f32, 2.0, 3.0, 4.0]; // two 2-dimensional rows +let config = Config { clusters: 1, ..Config::default() }; +let model = fit(&data, 2, &config)?; +assert_eq!(model.centroids, [2.0, 3.0]); +# Ok::<(), ruvector_e_means::Error>(()) +``` + +The implementation includes seeded random initialization, EMA counts/sums initialized at 1e-10, cosine scheduling, automatic batch/step scaling, weighted donor splitting every five updates, and final-epoch mean or main EMA finalization. Prediction and returned MSE use exact squared-L2 distances in original input order. All rows, including a partial final batch, are visited each epoch. Scratch memory is O(n + kd). Accumulation and distance arithmetic use f64; codebooks use f32. Extreme revival perturbations saturate to finite f32. Dead slots outnumbering available live donors wait for the next revival pass. + +Assignment prunes candidates once their partial squared distance cannot beat the current best, checking every eight coordinates above 16 dimensions. Small vectors retain the scalar path. A zero-distance winner stops the search. Ordered f64 addition and lowest-index ties are preserved. Training reuses revival scratch and omits last-epoch buffers in `Ema` mode. The npm bridge returns owned typed arrays and frees its temporary Rust model after materialization. + +Scaling laws were fitted on large, high-dimensional embeddings; override `batch_size` and `peak_step` for other distributions. Last-epoch means average assignments observed during the last epoch, when centroids were moving; this is not a separate Lloyd pass. Empty final clusters retain their EMA centroid. A final exact pass recomputes assignments and MSE against the returned codebook. `mse` is the mean squared L2 distance per row, not per coordinate. + +This version does not implement GPU/low-precision kernels, distributed or approximate IVF assignment, or slow-EMA finalization. It makes no claim to reproduce the paper's GPU speedups or universally outperform Lloyd. Existing consumer training defaults remain available. + +Native Rust has no default features. `serde` adds config/model serialization; `wasm` adds the wasm-bindgen bridge used by `@ruvector/e-means`. Native core MSRV is Rust 1.81; WASM builds use the toolchain required by the pinned wasm-bindgen dependency. See [ADR-359](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-359-e-means-shared-clustering.md) for integration, validation, and staged release instructions. + +Run the deterministic native benchmark with `cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both`. Dataset generation and warmup are excluded from median fit/predict times. The [local measurements](https://github.com/ruvnet/ruvector/blob/main/docs/research/e-means/performance-2026-11-11.json) include baseline comparisons, allocation counts and unchanged-output checks; gains depend on shape and distribution. + +Reusable `quantization::ProductQuantizer` and `ivf::IvfPartition` modules add +checked byte-code encode/decode, subspace-major codebooks, and stable inverted +postings. Their private shape fields and serde restoration reject malformed +persisted state. `ruvector-pq-search` and the IVF/RAIRS/SEIL family expose explicit +e-means training using this dependency. See [ADR-360](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-360-e-means-ecosystem-integrations.md) +for the native/npm integration matrix, MetaHarness evaluation, and Cloudflare +static-WASM entrypoints. These additions preserve existing training defaults. diff --git a/crates/ruvector-e-means/examples/benchmark.rs b/crates/ruvector-e-means/examples/benchmark.rs new file mode 100644 index 0000000000..5112f8032d --- /dev/null +++ b/crates/ruvector-e-means/examples/benchmark.rs @@ -0,0 +1,177 @@ +//! Portable native fit/predict benchmark. No extra dependencies or CPU flags. +//! +//! cargo run -p ruvector-e-means --release --example benchmark -- +//! --case all --repeats 5 --seed 42 --finalization both +//! +//! Dataset creation and warmup are excluded from reported median timings. + +use ruvector_e_means::{fit, Config, Finalization}; +use std::{hint::black_box, time::Instant}; + +#[derive(Clone, Copy)] +pub struct Case { + pub name: &'static str, + pub samples: usize, + pub clusters: usize, + pub dimensions: usize, +} + +pub const CASES: [Case; 4] = [ + Case { + name: "embedding128", + samples: 4096, + clusters: 64, + dimensions: 128, + }, + Case { + name: "embedding768", + samples: 2048, + clusters: 32, + dimensions: 768, + }, + Case { + name: "pq8", + samples: 8192, + clusters: 256, + dimensions: 8, + }, + Case { + name: "revival", + samples: 2048, + clusters: 64, + dimensions: 32, + }, +]; + +/// Deterministic synthetic inputs, not a reproduction of the paper's datasets. +/// Cases cover clustered and diffuse normalized embeddings, diffuse low-D +/// codebook training, and duplicate/zero rows that exercise cluster revival. +pub fn generate(case: Case, seed: u64) -> Vec { + let mut state = seed; + let mut random = || { + state = state.wrapping_add(0x9e3779b97f4a7c15); + let mut value = state; + value = (value ^ (value >> 30)).wrapping_mul(0xbf58476d1ce4e5b9); + value = (value ^ (value >> 27)).wrapping_mul(0x94d049bb133111eb); + value ^= value >> 31; + ((value >> 40) as f32 / 16_777_216.0) * 2.0 - 1.0 + }; + let centers: Vec = (0..case.clusters * case.dimensions) + .map(|_| random()) + .collect(); + let mut data = Vec::with_capacity(case.samples * case.dimensions); + for i in 0..case.samples { + for d in 0..case.dimensions { + let value = match case.name { + "embedding128" => { + centers[(i % case.clusters) * case.dimensions + d] + random() * 0.1 + } + "revival" if i % 5 == 0 => 0.0, + "revival" => ((i % 4) as f32 - 1.5) * if d % 2 == 0 { 1.0 } else { -1.0 }, + _ => random(), + }; + data.push(value); + } + if case.name.starts_with("embedding") { + let row = &mut data[i * case.dimensions..(i + 1) * case.dimensions]; + let norm = row + .iter() + .map(|&v| f64::from(v).powi(2)) + .sum::() + .sqrt(); + for value in row { + *value = (f64::from(*value) / norm) as f32; + } + } + } + data +} + +pub fn digest(centroids: &[f32], assignments: &[usize]) -> u64 { + let mut hash = 0xcbf29ce484222325u64; + for bits in centroids + .iter() + .map(|v| u64::from(v.to_bits())) + .chain(assignments.iter().map(|&v| v as u64)) + { + for byte in bits.to_le_bytes() { + hash = (hash ^ u64::from(byte)).wrapping_mul(0x100000001b3); + } + } + hash +} + +pub fn median_ms(samples: &mut [f64]) -> f64 { + samples.sort_by(f64::total_cmp); + let middle = samples.len() / 2; + if samples.len() % 2 == 0 { + (samples[middle - 1] + samples[middle]) / 2.0 + } else { + samples[middle] + } +} + +fn main() -> Result<(), Box> { + let mut case_name = String::from("all"); + let mut repeats = 5usize; + let mut seed = 42u64; + let mut finalization = String::from("both"); + let mut args = std::env::args().skip(1); + while let Some(flag) = args.next() { + if flag == "--help" { + println!("benchmark [--case all|embedding128|embedding768|pq8|revival] [--repeats 1..99] [--seed u64] [--finalization both|lastEpochMean|ema]"); + return Ok(()); + } + let value = args.next().ok_or("every option requires a value")?; + match flag.as_str() { + "--case" => case_name = value, + "--repeats" => repeats = value.parse()?, + "--seed" => seed = value.parse()?, + "--finalization" => finalization = value, + _ => return Err(format!("unknown option: {flag}").into()), + } + } + if !(1..=99).contains(&repeats) + || !["both", "lastEpochMean", "ema"].contains(&finalization.as_str()) + { + return Err("invalid repeats or finalization".into()); + } + let cases: Vec = CASES + .into_iter() + .filter(|case| case_name == "all" || case.name == case_name) + .collect(); + if cases.is_empty() { + return Err("unknown benchmark case".into()); + } + for case in cases { + let data = generate(case, seed); + for (label, mode) in [ + ("lastEpochMean", Finalization::LastEpochMean), + ("ema", Finalization::Ema), + ] { + if finalization != "both" && finalization != label { + continue; + } + let config = Config { + clusters: case.clusters, + seed, + finalization: mode, + ..Config::default() + }; + let model = fit(black_box(&data), case.dimensions, &config)?; + black_box(model.predict(black_box(&data))?); + let mut fit_ms = Vec::with_capacity(repeats); + let mut predict_ms = Vec::with_capacity(repeats); + for _ in 0..repeats { + let start = Instant::now(); + black_box(fit(black_box(&data), case.dimensions, black_box(&config))?); + fit_ms.push(start.elapsed().as_secs_f64() * 1000.0); + let start = Instant::now(); + black_box(model.predict(black_box(&data))?); + predict_ms.push(start.elapsed().as_secs_f64() * 1000.0); + } + println!("{{\"case\":\"{}\",\"samples\":{},\"clusters\":{},\"dimensions\":{},\"seed\":{},\"epochs\":{},\"repeats\":{},\"finalization\":\"{}\",\"fitMedianMs\":{:.6},\"predictMedianMs\":{:.6},\"mse\":{:.12},\"revivedClusters\":{},\"digest\":\"{:016x}\"}}", case.name, case.samples, case.clusters, case.dimensions, seed, config.epochs, repeats, label, median_ms(&mut fit_ms), median_ms(&mut predict_ms), model.mse, model.revived_clusters, digest(&model.centroids, &model.assignments)); + } + } + Ok(()) +} diff --git a/crates/ruvector-e-means/src/config.rs b/crates/ruvector-e-means/src/config.rs new file mode 100644 index 0000000000..9e63d6a575 --- /dev/null +++ b/crates/ruvector-e-means/src/config.rs @@ -0,0 +1,115 @@ +use crate::Error; + +/// Final centroid estimator. Slow-EMA finalization is reserved for a future API. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub enum Finalization { + #[default] + LastEpochMean, + Ema, +} + +/// Fit options. Overrides are useful for tiny or low-dimensional datasets where +/// the paper's empirically fitted scaling laws are outside their training range. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr( + feature = "serde", + serde(rename_all = "camelCase", deny_unknown_fields) +)] +pub struct Config { + pub clusters: usize, + #[cfg_attr(feature = "serde", serde(default = "default_epochs"))] + pub epochs: usize, + #[cfg_attr(feature = "serde", serde(default))] + pub batch_size: Option, + #[cfg_attr(feature = "serde", serde(default))] + pub peak_step: Option, + #[cfg_attr(feature = "serde", serde(default = "default_seed"))] + pub seed: u64, + #[cfg_attr(feature = "serde", serde(default))] + pub finalization: Finalization, +} + +fn default_epochs() -> usize { + 3 +} + +fn default_seed() -> u64 { + 42 +} + +impl Default for Config { + fn default() -> Self { + Self { + clusters: 8, + epochs: default_epochs(), + batch_size: None, + peak_step: None, + seed: default_seed(), + finalization: Finalization::LastEpochMean, + } + } +} + +/// Resolved scaling-law parameters, inspectable before allocating a model. +#[derive(Debug, Clone, Copy)] +pub struct Parameters { + pub batch_size: usize, + pub peak_step: f64, + pub updates: usize, +} + +impl Config { + /// Table 2 and equations (6)-(7) of arXiv:2611.09501v1. Batch law uses + /// coefficient 0.035, divided by 8 above two million samples, rounded to + /// the nearest power of two and capped at n. Tail batches are included. + pub fn parameters(&self, samples: usize) -> Result { + if samples == 0 || self.clusters == 0 || self.clusters > samples { + return Err(Error("clusters must be in 1..=number of samples")); + } + if self.epochs == 0 { + return Err(Error("epochs must be positive")); + } + let n = samples as f64; + let k = self.clusters as f64; + let t = self.epochs as f64; + let batch_size = match self.batch_size { + Some(0) => return Err(Error("batch size must be positive")), + Some(b) => b.min(samples), + None => { + let coefficient = if samples > 2_000_000 { + 0.035 / 8.0 + } else { + 0.035 + }; + let law = coefficient * k.powf(0.13) * n.powf(0.88) * t.powf(0.81); + 2.0_f64.powf(law.max(1.0).log2().round()).min(n) as usize + } + }; + let peak_step = self.peak_step.unwrap_or_else(|| { + (0.824 * k.powf(-0.46) * (batch_size as f64).powf(0.90) * n.powf(-0.45) * t.powf(-0.11)) + .min(1.0) + }); + if !peak_step.is_finite() || peak_step <= 0.0 || peak_step > 1.0 { + return Err(Error("peak step must be finite and in (0, 1]")); + } + let batches = samples / batch_size + usize::from(samples % batch_size != 0); + let updates = batches + .checked_mul(self.epochs) + .ok_or(Error("update count overflow"))?; + Ok(Parameters { + batch_size, + peak_step, + updates, + }) + } +} + +/// Equation (5), zero-based batch index t and total M updates. Its denominator +/// is M as printed in the paper: the last update approaches the 0.1 floor. +pub fn cosine_step(peak_step: f64, update: usize, total_updates: usize) -> f64 { + let fraction = (update as f64) / (total_updates.max(1) as f64); + peak_step * (0.1 + 0.9 * 0.5 * (1.0 + (std::f64::consts::PI * fraction).cos())) +} diff --git a/crates/ruvector-e-means/src/distance.rs b/crates/ruvector-e-means/src/distance.rs new file mode 100644 index 0000000000..03b9753679 --- /dev/null +++ b/crates/ruvector-e-means/src/distance.rs @@ -0,0 +1,189 @@ +//! Exact squared-L2 assignment with bounded work on losing candidates. + +/// Inputs have already passed the public API's shape and finiteness checks. +/// All squared terms are nonnegative: once a partial distance reaches the +/// best distance, that later centroid cannot win, including in a tie. +pub(crate) fn nearest(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + // End-to-end diffuse PQ benchmarks favor the original scalar path at small + // dimensions: pruning checks cost more than the arithmetic they can skip. + if dimensions <= 16 { + exhaustive(row, centroids, dimensions) + } else { + pruned::<8>(row, centroids, dimensions) + } +} + +fn exhaustive(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let distance: f64 = row + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum(); + if distance < best.1 { + best = (j, distance); + if distance == 0.0 { + break; + } + } + } + best +} + +fn pruned(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let mut distance = 0.0; + for (xs, ys) in row.chunks(BLOCK).zip(centroid.chunks(BLOCK)) { + // Retain left-to-right f64 addition. Reassociating these terms, or + // expanding norms and dot products, can change near-tie winners. + for (&x, &y) in xs.iter().zip(ys) { + let difference = f64::from(x) - f64::from(y); + distance += difference * difference; + } + if distance >= best.1 { + break; + } + } + if distance < best.1 { + best = (j, distance); + if distance == 0.0 { + break; + } + } + } + best +} + +#[cfg(test)] +mod tests { + use super::nearest; + + /// The pre-optimization exhaustive implementation is an independent oracle. + fn oracle(row: &[f32], centroids: &[f32], dimensions: usize) -> (usize, f64) { + let mut best = (0, f64::INFINITY); + for (j, centroid) in centroids.chunks_exact(dimensions).enumerate() { + let distance: f64 = row + .iter() + .zip(centroid) + .map(|(&x, &y)| (f64::from(x) - f64::from(y)).powi(2)) + .sum(); + if distance < best.1 { + best = (j, distance); + } + } + best + } + + fn compare(row: &[f32], centroids: &[f32]) { + let expected = oracle(row, centroids, row.len()); + let actual = nearest(row, centroids, row.len()); + assert_eq!(actual.0, expected.0, "{} dimensions", row.len()); + assert_eq!(actual.1.to_bits(), expected.1.to_bits()); + } + + fn random(state: &mut u64) -> f32 { + *state = state.wrapping_mul(6364136223846793005).wrapping_add(1); + ((*state >> 40) as f32 / 16777216.0) * 2.0 - 1.0 + } + + #[test] + fn assignment_matches_exhaustive_on_diffuse_and_separated_data() { + let mut state = 42; + for dimensions in [ + 1, 3, 4, 7, 8, 9, 15, 16, 17, 31, 32, 33, 127, 128, 129, 384, 385, 768, 769, + ] { + for clusters in [1, 2, 7, 32] { + for separated in [false, true] { + let centroids = (0..clusters * dimensions) + .map(|i| { + random(&mut state) + + if separated { + (i / dimensions) as f32 * 4.0 + } else { + 0.0 + } + }) + .collect::>(); + for i in 0..13 { + let row = (0..dimensions) + .map(|d| { + if separated { + centroids[(i % clusters) * dimensions + d] + + random(&mut state) * 0.01 + } else { + random(&mut state) + } + }) + .collect::>(); + compare(&row, ¢roids); + } + } + } + } + } + + #[test] + fn ties_and_zero_distances_keep_the_lowest_index() { + for dimensions in [1, 3, 8, 16, 32, 128, 384, 768] { + let row = vec![0.0; dimensions]; + let mut centroids = vec![1.0; dimensions]; + centroids.extend(vec![-1.0; dimensions]); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 0); + centroids.extend(vec![-0.0; dimensions]); + centroids.extend(vec![0.0; dimensions]); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 2); + } + } + + #[test] + fn extreme_finite_coordinates_and_subnormals_preserve_exact_distance() { + let values = [ + f32::MAX, + -f32::MAX, + f32::MIN_POSITIVE, + f32::from_bits(1), + -f32::from_bits(1), + 0.0, + -0.0, + 1.0, + ]; + for dimensions in [1, 3, 8, 16, 32, 128, 384, 768] { + for offset in 0..values.len() { + let row = (0..dimensions) + .map(|d| values[(d + offset) % values.len()]) + .collect::>(); + let centroids = (0..7 * dimensions) + .map(|d| values[(d * 3 + offset + 1) % values.len()]) + .collect::>(); + compare(&row, ¢roids); + } + } + } + + #[test] + fn near_ties_and_awkward_tail_dimensions_preserve_ordered_addition() { + for dimensions in [3, 7, 8, 9, 15, 16, 17, 31, 32, 33, 127, 129, 385, 769] { + let row = vec![0.0; dimensions]; + let mut first = vec![1.0; dimensions]; + let mut second = first.clone(); + first[dimensions - 1] = f32::from_bits(1.0_f32.to_bits() + 1); + let mut centroids = first.clone(); + centroids.extend_from_slice(&second); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 1); + + // Tiny trailing contributions disappear when added after a huge + // leading square; summation reassociation must not break this tie. + first[0] = 1e20; + second[0] = 1e20; + let mut centroids = first; + centroids.extend(second); + compare(&row, ¢roids); + assert_eq!(nearest(&row, ¢roids, dimensions).0, 0); + } + } +} diff --git a/crates/ruvector-e-means/src/ivf.rs b/crates/ruvector-e-means/src/ivf.rs new file mode 100644 index 0000000000..136f78d200 --- /dev/null +++ b/crates/ruvector-e-means/src/ivf.rs @@ -0,0 +1,155 @@ +//! Stable inverted-file postings over a trained e-means centroid model. + +use crate::{fit, validate_rows, Config, Error, Model}; + +/// A centroid model plus compact, deterministic inverted lists of input row IDs. +/// Posting `j` occupies `indices[offsets[j]..offsets[j + 1]]`. Row IDs within +/// every list are ascending and every training row occurs exactly once. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct IvfPartition { + model: Model, + offsets: Vec, + indices: Vec, +} + +impl IvfPartition { + /// Train centroids and build postings from the final nearest assignments. + pub fn fit(data: &[f32], dimensions: usize, config: &Config) -> Result { + Self::from_model(fit(data, dimensions, config)?) + } + + /// Build postings for an existing, validated fitted model. + pub fn from_model(model: Model) -> Result { + let clusters = validate_model(&model)?; + let mut offsets = vec![0usize; clusters + 1]; + for &assignment in &model.assignments { + offsets[assignment + 1] += 1; + } + for i in 1..offsets.len() { + offsets[i] += offsets[i - 1]; + } + let mut cursors = offsets[..clusters].to_vec(); + let mut indices = vec![0usize; model.assignments.len()]; + for (row, &assignment) in model.assignments.iter().enumerate() { + indices[cursors[assignment]] = row; + cursors[assignment] += 1; + } + Ok(Self { + model, + offsets, + indices, + }) + } + + /// Restore a persisted partition, checking offsets, labels, and row IDs. + /// Repeated, omitted, reordered, or incorrectly assigned row IDs reject. + pub fn from_parts( + model: Model, + offsets: Vec, + indices: Vec, + ) -> Result { + let clusters = validate_model(&model)?; + let samples = model.assignments.len(); + if offsets.len() != clusters + 1 + || offsets.first() != Some(&0) + || offsets.last() != Some(&samples) + || indices.len() != samples + { + return Err(Error( + "IVF offsets and indices must cover every training row", + )); + } + if offsets + .windows(2) + .any(|pair| pair[0] > pair[1] || pair[1] > samples) + { + return Err(Error( + "IVF offsets must be monotonic and within the row count", + )); + } + for cluster in 0..clusters { + let posting = &indices[offsets[cluster]..offsets[cluster + 1]]; + if posting.windows(2).any(|pair| pair[0] >= pair[1]) { + return Err(Error("IVF posting row IDs must be strictly ascending")); + } + for &row in posting { + if row >= samples || model.assignments[row] != cluster { + return Err(Error("IVF row ID is out of range or in the wrong posting")); + } + } + } + Ok(Self { + model, + offsets, + indices, + }) + } + + /// Trained centroids, final labels, and training metrics. + pub fn model(&self) -> &Model { + &self.model + } + + /// Exclusive posting boundaries, of length `clusters + 1`. + pub fn offsets(&self) -> &[usize] { + &self.offsets + } + + /// Input row IDs grouped by cluster, stable within each cluster. + pub fn indices(&self) -> &[usize] { + &self.indices + } + + /// Borrow one inverted list, returning an error for an invalid cluster. + pub fn posting(&self, cluster: usize) -> Result<&[usize], Error> { + if cluster >= self.offsets.len() - 1 { + return Err(Error("IVF cluster index is out of range")); + } + Ok(&self.indices[self.offsets[cluster]..self.offsets[cluster + 1]]) + } + + /// Consume this partition without copying its trained centroid model. + pub fn into_model(self) -> Model { + self.model + } +} + +fn validate_model(model: &Model) -> Result { + validate_rows(&model.centroids, model.dimensions)?; + let clusters = model.centroids.len() / model.dimensions; + let samples = model.assignments.len(); + if clusters == 0 || samples < clusters || model.assignments.iter().any(|&j| j >= clusters) { + return Err(Error( + "IVF model must have valid nonempty centroids and assignments", + )); + } + if !model.mse.is_finite() + || model.mse < 0.0 + || !model.peak_step.is_finite() + || model.peak_step <= 0.0 + || model.peak_step > 1.0 + || model.batch_size == 0 + || model.batch_size > samples + || model.updates == 0 + { + return Err(Error("IVF model has invalid fitted training metrics")); + } + Ok(clusters) +} + +#[cfg(feature = "serde")] +impl<'de> serde::Deserialize<'de> for IvfPartition { + fn deserialize>(deserializer: D) -> Result { + #[derive(serde::Deserialize)] + #[serde(rename_all = "camelCase", deny_unknown_fields)] + struct Wire { + model: Model, + offsets: Vec, + indices: Vec, + } + let wire = ::deserialize(deserializer)?; + Self::from_parts(wire.model, wire.offsets, wire.indices).map_err(serde::de::Error::custom) + } +} diff --git a/crates/ruvector-e-means/src/lib.rs b/crates/ruvector-e-means/src/lib.rs new file mode 100644 index 0000000000..959539093d --- /dev/null +++ b/crates/ruvector-e-means/src/lib.rs @@ -0,0 +1,81 @@ +//! e-means CPU reference implementation of Bessa et al., arXiv:2611.09501v1. +//! +//! Uses exact squared-L2 assignment, f64 sufficient statistics and seeded +//! ChaCha8 shuffles. This does not implement the paper's GPU or approximate IVF +//! kernels. See [`fit`] and [`Config`]. + +mod config; +mod distance; +pub mod ivf; +pub mod quantization; +mod trainer; +#[cfg(feature = "wasm")] +mod wasm; + +pub use config::{cosine_step, Config, Finalization, Parameters}; +pub(crate) use distance::nearest; +pub use ivf::IvfPartition; +pub use quantization::ProductQuantizer; +pub use trainer::fit; + +/// Validation failure; invalid input is rejected before training starts. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Error(pub(crate) &'static str); + +impl std::fmt::Display for Error { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.write_str(self.0) + } +} + +impl std::error::Error for Error {} + +/// A trained flat, row-major codebook and freshly recomputed training metrics. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct Model { + pub centroids: Vec, + pub dimensions: usize, + /// Nearest-centroid assignments in original input order, after finalization. + pub assignments: Vec, + /// Mean squared L2 distance per vector, not divided by dimensionality. + pub mse: f64, + pub batch_size: usize, + pub peak_step: f64, + pub updates: usize, + pub revived_clusters: usize, +} + +impl Model { + /// Assign new vectors to this codebook. Empty queries return no assignments. + /// Public/deserialized model fields are validated on every call. + pub fn predict(&self, data: &[f32]) -> Result, Error> { + predict(data, self.dimensions, &self.centroids) + } +} + +/// Exact squared-L2 prediction with deterministic lowest-index tie breaking. +pub fn predict(data: &[f32], dimensions: usize, centroids: &[f32]) -> Result, Error> { + validate_rows(data, dimensions)?; + validate_rows(centroids, dimensions)?; + if centroids.is_empty() { + return Err(Error("centroids must not be empty")); + } + Ok(data + .chunks_exact(dimensions) + .map(|row| nearest(row, centroids, dimensions).0) + .collect()) +} + +pub(crate) fn validate_rows(data: &[f32], dimensions: usize) -> Result<(), Error> { + if dimensions == 0 || data.len() % dimensions != 0 { + return Err(Error( + "dimensions must be positive and divide the data length", + )); + } + if data.iter().any(|v| !v.is_finite()) { + return Err(Error("vectors must contain only finite values")); + } + Ok(()) +} diff --git a/crates/ruvector-e-means/src/quantization.rs b/crates/ruvector-e-means/src/quantization.rs new file mode 100644 index 0000000000..1fb7f7989a --- /dev/null +++ b/crates/ruvector-e-means/src/quantization.rs @@ -0,0 +1,181 @@ +//! Checked product-quantization codebooks trained by the shared e-means kernel. + +use crate::{fit, nearest, validate_rows, Config, Error}; + +/// A reusable PQ codebook with private, validated layout metadata. +/// +/// Centroids are subspace-major: `[subspace][cluster][subspace_dimension]`. +/// Codes are row-major: one u8 per subspace per input vector. Each subspace +/// uses the supplied configuration unchanged, including its deterministic seed. +#[derive(Debug, Clone)] +#[cfg_attr(feature = "serde", derive(serde::Serialize))] +#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))] +pub struct ProductQuantizer { + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, +} + +impl ProductQuantizer { + /// Train one e-means codebook per equally sized subspace. + pub fn fit( + data: &[f32], + dimensions: usize, + subspaces: usize, + config: &Config, + ) -> Result { + validate_rows(data, dimensions)?; + config.parameters(data.len() / dimensions)?; + Self::validate_shape(dimensions, subspaces, config.clusters)?; + let sub_dim = dimensions / subspaces; + let mut centroids = Vec::with_capacity(dimensions * config.clusters); + let mut sub_data = Vec::with_capacity(data.len() / subspaces); + for subspace in 0..subspaces { + sub_data.clear(); + let start = subspace * sub_dim; + for row in data.chunks_exact(dimensions) { + sub_data.extend_from_slice(&row[start..start + sub_dim]); + } + centroids.extend(fit(&sub_data, sub_dim, config)?.centroids); + } + Self::from_centroids(dimensions, subspaces, config.clusters, centroids) + } + + /// Restore a codebook, rejecting inconsistent shapes or nonfinite values. + pub fn from_centroids( + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, + ) -> Result { + Self::validate_parts(dimensions, subspaces, clusters, ¢roids)?; + Ok(Self { + dimensions, + subspaces, + clusters, + centroids, + }) + } + + /// Validate a borrowed codebook layout without allocating a copy. + pub fn validate_parts( + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: &[f32], + ) -> Result<(), Error> { + Self::validate_shape(dimensions, subspaces, clusters)?; + if centroids.len() != dimensions * clusters { + return Err(Error( + "PQ centroid length must equal dimensions times clusters", + )); + } + validate_rows(centroids, dimensions / subspaces) + } + + fn validate_shape(dimensions: usize, subspaces: usize, clusters: usize) -> Result<(), Error> { + if dimensions == 0 || subspaces == 0 || dimensions % subspaces != 0 { + return Err(Error( + "PQ subspaces must be positive and divide positive dimensions", + )); + } + if !(1..=256).contains(&clusters) { + return Err(Error("PQ clusters must be in 1..=256 for u8 codes")); + } + dimensions + .checked_mul(clusters) + .ok_or(Error("PQ centroid shape overflows usize"))?; + Ok(()) + } + + /// Original vector dimensionality. + pub fn dimensions(&self) -> usize { + self.dimensions + } + + /// Number of equally sized subspaces, and bytes in each encoded vector. + pub fn subspaces(&self) -> usize { + self.subspaces + } + + /// Number of centroids in each subspace. + pub fn clusters(&self) -> usize { + self.clusters + } + + /// Dimensionality of each subvector. + pub fn subspace_dimensions(&self) -> usize { + self.dimensions / self.subspaces + } + + /// Borrow the flat subspace-major codebook. + pub fn centroids(&self) -> &[f32] { + &self.centroids + } + + /// Consume the quantizer and return its existing flat codebook allocation. + pub fn into_centroids(self) -> Vec { + self.centroids + } + + /// Encode finite row-major vectors with exact f64 nearest-centroid assignment. + /// Empty input produces an empty code array; ties choose the lowest code. + pub fn encode(&self, data: &[f32]) -> Result, Error> { + validate_rows(data, self.dimensions)?; + let sub_dim = self.subspace_dimensions(); + let mut codes = Vec::with_capacity(data.len() / sub_dim); + for row in data.chunks_exact(self.dimensions) { + for (subspace, subvector) in row.chunks_exact(sub_dim).enumerate() { + let start = subspace * self.clusters * sub_dim; + let book = &self.centroids[start..start + self.clusters * sub_dim]; + codes.push(nearest(subvector, book, sub_dim).0 as u8); + } + } + Ok(codes) + } + + /// Decode row-major PQ codes, rejecting incomplete rows and invalid codes. + pub fn decode(&self, codes: &[u8]) -> Result, Error> { + if codes.len() % self.subspaces != 0 { + return Err(Error("PQ code length must be divisible by subspaces")); + } + if codes.iter().any(|&code| usize::from(code) >= self.clusters) { + return Err(Error("PQ code is outside the trained codebook")); + } + let capacity = (codes.len() / self.subspaces) + .checked_mul(self.dimensions) + .ok_or(Error("decoded PQ shape overflows usize"))?; + let sub_dim = self.subspace_dimensions(); + let mut data = Vec::with_capacity(capacity); + for row in codes.chunks_exact(self.subspaces) { + for (subspace, &code) in row.iter().enumerate() { + let start = (subspace * self.clusters + usize::from(code)) * sub_dim; + data.extend_from_slice(&self.centroids[start..start + sub_dim]); + } + } + Ok(data) + } +} + +#[cfg(feature = "serde")] +impl<'de> serde::Deserialize<'de> for ProductQuantizer { + fn deserialize>(deserializer: D) -> Result { + #[derive(serde::Deserialize)] + #[serde(rename_all = "camelCase", deny_unknown_fields)] + struct Wire { + dimensions: usize, + subspaces: usize, + clusters: usize, + centroids: Vec, + } + let wire = ::deserialize(deserializer)?; + Self::from_centroids( + wire.dimensions, + wire.subspaces, + wire.clusters, + wire.centroids, + ) + .map_err(serde::de::Error::custom) + } +} diff --git a/crates/ruvector-e-means/src/trainer.rs b/crates/ruvector-e-means/src/trainer.rs new file mode 100644 index 0000000000..5ded7db45b --- /dev/null +++ b/crates/ruvector-e-means/src/trainer.rs @@ -0,0 +1,242 @@ +use crate::{cosine_step, nearest, validate_rows, Config, Error, Finalization, Model}; +use rand_chacha::ChaCha8Rng; +use rand_core::{RngCore, SeedableRng}; + +const INITIAL_COUNT: f64 = 1e-10; +const MIN_COUNT: f64 = 1e-300; +const REVIVAL_THRESHOLD: f64 = 0.1; +// BF16 epsilon, as used by Appendix H, even though this implementation is f32. +const SPLIT_DELTA: f64 = 1.0 / 128.0; + +/// Train on finite flat row-major f32 vectors. The algorithm follows equations +/// (2)-(8) of arXiv:2611.09501v1, using exact CPU assignment. Shuffled partial +/// batches are included, so every row participates in every epoch. Scratch +/// memory is O(n + kd); no n-by-k distance matrix is allocated. +pub fn fit(data: &[f32], dimensions: usize, config: &Config) -> Result { + validate_rows(data, dimensions)?; + let samples = data.len() / dimensions; + let params = config.parameters(samples)?; + let k = config.clusters; + let mut rng = ChaCha8Rng::seed_from_u64(config.seed); + let mut order: Vec = (0..samples).collect(); + shuffle(&mut order, &mut rng); + let mut centroids = Vec::with_capacity(k * dimensions); + for &i in &order[..k] { + centroids.extend_from_slice(&data[i * dimensions..(i + 1) * dimensions]); + } + let mut counts = vec![INITIAL_COUNT; k]; + let mut sums: Vec = centroids + .iter() + .map(|&v| f64::from(v) * INITIAL_COUNT) + .collect(); + let mut batch_counts = vec![0.0; k]; + let mut batch_sums = vec![0.0; sums.len()]; + let use_last_mean = config.finalization == Finalization::LastEpochMean; + let mut last_counts = if use_last_mean { + vec![0usize; k] + } else { + Vec::new() + }; + let mut last_sums = if use_last_mean { + vec![0.0; sums.len()] + } else { + Vec::new() + }; + let mut revival_scratch = RevivalScratch::default(); + let mut updates = 0; + let mut revived_clusters = 0; + for epoch in 0..config.epochs { + let record_last = use_last_mean && epoch + 1 == config.epochs; + shuffle(&mut order, &mut rng); + for batch in order.chunks(params.batch_size) { + batch_counts.fill(0.0); + batch_sums.fill(0.0); + for &i in batch { + let row = &data[i * dimensions..(i + 1) * dimensions]; + let (j, _) = nearest(row, ¢roids, dimensions); + batch_counts[j] += 1.0; + let batch_sum = &mut batch_sums[j * dimensions..(j + 1) * dimensions]; + for (sum, &x) in batch_sum.iter_mut().zip(row) { + *sum += f64::from(x); + } + if record_last { + last_counts[j] += 1; + let last_sum = &mut last_sums[j * dimensions..(j + 1) * dimensions]; + for (sum, &x) in last_sum.iter_mut().zip(row) { + *sum += f64::from(x); + } + } + } + let step = cosine_step(params.peak_step, updates, params.updates); + for j in 0..k { + let count = (1.0 - step) * counts[j] + step * batch_counts[j]; + let denominator = count.max(MIN_COUNT); + counts[j] = denominator; + let range = j * dimensions..(j + 1) * dimensions; + let sum_row = &mut sums[range.clone()]; + let centroid_row = &mut centroids[range.clone()]; + if count < MIN_COUNT { + // A peak step of 1 can erase empty-cluster statistics. + // Preserve that centroid with a negligible pseudo-count. + for (sum, centroid) in sum_row.iter_mut().zip(centroid_row) { + *sum = denominator * f64::from(*centroid); + *centroid = bounded_f32(*sum / denominator); + } + } else { + for ((sum, &batch_sum), centroid) in + sum_row.iter_mut().zip(&batch_sums[range]).zip(centroid_row) + { + *sum = (1.0 - step) * *sum + step * batch_sum; + *centroid = bounded_f32(*sum / denominator); + } + } + } + updates += 1; + if updates % 5 == 0 { + revived_clusters += revive( + &mut counts, + &mut sums, + &mut centroids, + dimensions, + &mut rng, + &mut revival_scratch, + ); + } + } + } + if use_last_mean { + for (j, &count) in last_counts.iter().enumerate() { + if count > 0 { + for d in 0..dimensions { + centroids[j * dimensions + d] = + bounded_f32(last_sums[j * dimensions + d] / count as f64); + } + } + } + } + let mut assignments = Vec::with_capacity(samples); + let mut loss = 0.0; + for row in data.chunks_exact(dimensions) { + let (j, distance) = nearest(row, ¢roids, dimensions); + assignments.push(j); + loss += distance; + } + Ok(Model { + centroids, + dimensions, + assignments, + mse: loss / samples as f64, + batch_size: params.batch_size, + peak_step: params.peak_step, + updates, + revived_clusters, + }) +} + +fn bounded_f32(value: f64) -> f32 { + value.clamp(-f64::from(f32::MAX), f64::from(f32::MAX)) as f32 +} + +fn shuffle(order: &mut [usize], rng: &mut ChaCha8Rng) { + for i in (1..order.len()).rev() { + let limit = (i + 1) as u64; + // Rejection sampling avoids modulo bias, including on wasm32. + let threshold = limit.wrapping_neg() % limit; + let value = loop { + let value = rng.next_u64(); + if value >= threshold { + break value; + } + }; + order.swap(i, (value % limit) as usize); + } +} + +#[derive(Default)] +struct RevivalScratch { + dead: Vec, + available: Vec, +} + +fn revive( + counts: &mut [f64], + sums: &mut [f64], + centroids: &mut [f32], + dimensions: usize, + rng: &mut ChaCha8Rng, + scratch: &mut RevivalScratch, +) -> usize { + let threshold = REVIVAL_THRESHOLD * counts.iter().sum::() / counts.len() as f64; + scratch.dead.clear(); + scratch + .dead + .extend((0..counts.len()).filter(|&j| counts[j] < threshold)); + if scratch.dead.is_empty() { + return 0; + } + // Select live donors proportional to their EMA count, without replacement. + // Newly revived slots cannot donate again in the same revival pass. + let available = &mut scratch.available; + available.clear(); + available.extend((0..counts.len()).filter(|&j| counts[j] >= threshold)); + let mut revived = 0; + for &j in &scratch.dead { + let mass: f64 = available.iter().map(|&i| counts[i]).sum(); + if mass <= 0.0 { + break; + } + let unit = (rng.next_u64() >> 11) as f64 / ((1u64 << 53) as f64); + let mut pick = unit * mass; + let mut donor_pos = available.len() - 1; + for (pos, &i) in available.iter().enumerate() { + pick -= counts[i]; + if pick <= 0.0 { + donor_pos = pos; + break; + } + } + let donor = available.remove(donor_pos); + counts[donor] *= 0.5; + counts[j] = counts[donor]; + for d in 0..dimensions { + let shift = if d % 2 == 0 { + SPLIT_DELTA + } else { + -SPLIT_DELTA + }; + let value = f64::from(centroids[donor * dimensions + d]); + centroids[j * dimensions + d] = bounded_f32(value * (1.0 + shift)); + centroids[donor * dimensions + d] = bounded_f32(value * (1.0 - shift)); + sums[j * dimensions + d] = f64::from(centroids[j * dimensions + d]) * counts[j]; + sums[donor * dimensions + d] = + f64::from(centroids[donor * dimensions + d]) * counts[donor]; + } + revived += 1; + } + revived +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn donor_split_preserves_mass_and_weighted_sum() { + let mut counts = vec![10.0, 0.0]; + let mut sums = vec![40.0, 80.0, 0.0, 0.0]; + let mut centroids = vec![4.0, 8.0, 0.0, 0.0]; + let n = revive( + &mut counts, + &mut sums, + &mut centroids, + 2, + &mut ChaCha8Rng::seed_from_u64(2), + &mut RevivalScratch::default(), + ); + assert_eq!(n, 1); + assert_eq!(counts, [5.0, 5.0]); + assert_eq!(sums[0] + sums[2], 40.0); + assert_eq!(sums[1] + sums[3], 80.0); + assert_ne!(¢roids[..2], ¢roids[2..]); + } +} diff --git a/crates/ruvector-e-means/src/wasm.rs b/crates/ruvector-e-means/src/wasm.rs new file mode 100644 index 0000000000..6888112de3 --- /dev/null +++ b/crates/ruvector-e-means/src/wasm.rs @@ -0,0 +1,92 @@ +use crate::{fit, predict, Config, Model}; +use wasm_bindgen::prelude::*; + +/// Compatibility transport and an independent parity oracle for typed output. +#[wasm_bindgen(js_name = fitJson)] +pub fn fit_json(data: &[f32], dimensions: usize, config_json: &str) -> Result { + let config: Config = + serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?; + let model = fit(data, dimensions, &config).map_err(|e| JsError::new(&e.to_string()))?; + serde_json::to_string(&model).map_err(|e| JsError::new(&e.to_string())) +} + +/// A temporary owner for one fit result. JavaScript takes independent output +/// arrays and then frees this handle, releasing any vectors not taken. +#[wasm_bindgen] +pub struct FittedModel { + model: Model, +} + +#[wasm_bindgen] +impl FittedModel { + /// wasm-bindgen copies the returned vector into a caller-owned Float32Array + /// before freeing its Rust allocation. No view into WASM memory escapes. + #[wasm_bindgen(js_name = takeCentroids)] + pub fn take_centroids(&mut self) -> Vec { + std::mem::take(&mut self.model.centroids) + } + + /// Cluster indices fit u32 because wasm32 arrays and sample counts do. + #[wasm_bindgen(js_name = takeAssignments)] + pub fn take_assignments(&mut self) -> Vec { + std::mem::take(&mut self.model.assignments) + .into_iter() + .map(|index| index as u32) + .collect() + } + + #[wasm_bindgen(getter)] + pub fn dimensions(&self) -> usize { + self.model.dimensions + } + + #[wasm_bindgen(getter)] + pub fn mse(&self) -> f64 { + self.model.mse + } + + #[wasm_bindgen(getter, js_name = batchSize)] + pub fn batch_size(&self) -> usize { + self.model.batch_size + } + + #[wasm_bindgen(getter, js_name = peakStep)] + pub fn peak_step(&self) -> f64 { + self.model.peak_step + } + + #[wasm_bindgen(getter)] + pub fn updates(&self) -> usize { + self.model.updates + } + + #[wasm_bindgen(getter, js_name = revivedClusters)] + pub fn revived_clusters(&self) -> usize { + self.model.revived_clusters + } +} + +/// Only the small configuration crosses JSON; result vectors stay numeric. +#[wasm_bindgen(js_name = fitTyped)] +pub fn fit_typed( + data: &[f32], + dimensions: usize, + config_json: &str, +) -> Result { + let config: Config = + serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?; + fit(data, dimensions, &config) + .map(|model| FittedModel { model }) + .map_err(|e| JsError::new(&e.to_string())) +} + +#[wasm_bindgen(js_name = predictFlat)] +pub fn predict_flat( + data: &[f32], + dimensions: usize, + centroids: &[f32], +) -> Result, JsError> { + predict(data, dimensions, centroids) + .map(|v| v.into_iter().map(|j| j as u32).collect()) + .map_err(|e| JsError::new(&e.to_string())) +} diff --git a/crates/ruvector-e-means/tests/clustering.rs b/crates/ruvector-e-means/tests/clustering.rs new file mode 100644 index 0000000000..3f340f2b76 --- /dev/null +++ b/crates/ruvector-e-means/tests/clustering.rs @@ -0,0 +1,234 @@ +use ruvector_e_means::{cosine_step, fit, predict, Config, Finalization}; + +#[test] +fn ema_uses_decayed_sums_and_counts_including_short_batches() { + let model = fit( + &[0.0, 1.0, 9.0], + 1, + &Config { + clusters: 1, + epochs: 1, + batch_size: Some(2), + peak_step: Some(1.0), + finalization: Finalization::Ema, + ..Config::default() + }, + ) + .unwrap(); + // First step=1, second step=.55. For any shuffled tail x, the + // correct ratio is (.45*(10-x)+.55*x)/(.45*2+.55*1). + // Averaging batch centroids directly gives a different answer. + let possible: Vec = [0.0, 1.0, 9.0] + .into_iter() + .map(|tail| (0.45 * (10.0 - tail) + 0.55 * tail) / 1.45) + .collect(); + assert!(possible + .iter() + .any(|x| (*x - f64::from(model.centroids[0])).abs() < 1e-6)); + assert_eq!(model.updates, 2); + let center = f64::from(model.centroids[0]); + let expected_mse = (center.powi(2) + (1.0 - center).powi(2) + (9.0 - center).powi(2)) / 3.0; + assert!((model.mse - expected_mse).abs() < 1e-12); +} + +#[test] +fn last_epoch_mean_matches_independent_mean_and_mse_with_tail_batch() { + let data = [1., 2., 3., 4., 5., 6., 7., 8., 9., 10.]; + let config = Config { + clusters: 1, + epochs: 2, + batch_size: Some(2), + ..Config::default() + }; + let model = fit(&data, 2, &config).unwrap(); + assert_eq!(model.centroids, [5., 6.]); + assert_eq!(model.assignments, [0; 5]); + assert_eq!(model.mse, 16.0); + assert_eq!(model.updates, 6); // ceil(5/2) * 2, no dropped rows. + assert_eq!(model.predict(&data).unwrap(), model.assignments); +} + +#[test] +fn scaling_laws_match_table_two_and_large_dataset_rule() { + let params = Config { + clusters: 1024, + epochs: 4, + ..Config::default() + } + .parameters(1_000_000) + .unwrap(); + assert_eq!(params.batch_size, 65536); + assert_eq!(params.peak_step, 1.0); + let params = Config { + clusters: 1024, + epochs: 4, + batch_size: Some(256), + ..Config::default() + } + .parameters(1_000_000) + .unwrap(); + assert!((params.peak_step - 0.008558124524629177).abs() < 1e-14); + let params = Config { + clusters: 1000, + ..Config::default() + } + .parameters(3_000_000) + .unwrap(); + assert_eq!(params.batch_size, 16384); + assert!((params.peak_step - 0.2299943961117698).abs() < 1e-14); +} + +#[test] +fn schedule_matches_equation_five() { + assert_eq!(cosine_step(0.5, 0, 20), 0.5); + assert!((cosine_step(0.5, 10, 20) - 0.275).abs() < 1e-15); + assert_eq!(cosine_step(0.5, 20, 20), 0.05); + let steps: Vec = (0..20).map(|i| cosine_step(0.5, i, 20)).collect(); + assert!(steps.windows(2).all(|s| s[1] < s[0])); + assert!(steps[19] > 0.05); +} + +#[test] +fn separates_three_clouds_and_reproduces_seed() { + let mut data = Vec::new(); + for j in 0..3 { + for i in 0..48 { + for d in 0..8 { + data.push(j as f32 * 40.0 + ((i * 13 + d * 7) % 19) as f32 * 0.01); + } + } + } + let config = Config { + clusters: 3, + epochs: 5, + batch_size: Some(12), + ..Config::default() + }; + let a = fit(&data, 8, &config).unwrap(); + let b = fit(&data, 8, &config).unwrap(); + assert_eq!(a.centroids, b.centroids); + assert_eq!(a.assignments, b.assignments); + assert!(a.mse < 0.1, "mse {}", a.mse); + let leaders: Vec<_> = [0, 48, 96].into_iter().map(|i| a.assignments[i]).collect(); + assert_ne!(leaders[0], leaders[1]); + assert_ne!(leaders[0], leaders[2]); + assert_ne!(leaders[1], leaders[2]); + for cloud in a.assignments.chunks_exact(48) { + assert!(cloud.iter().all(|j| *j == cloud[0])); + } +} + +#[test] +fn duplicate_and_zero_vectors_remain_finite_with_revival_and_step_one() { + for value in [0., 12., f32::MAX, -f32::MAX] { + for finalization in [Finalization::LastEpochMean, Finalization::Ema] { + let model = fit( + &[value; 96], + 3, + &Config { + clusters: 8, + epochs: 4, + batch_size: Some(2), + peak_step: Some(1.0), + finalization, + ..Config::default() + }, + ) + .unwrap(); + assert!(model.centroids.iter().all(|x| x.is_finite())); + assert!(model.mse.is_finite()); + assert!(model.revived_clusters > 0); + assert!(model.assignments.iter().all(|j| *j < 8)); + } + } +} + +#[test] +fn handles_full_batch_k_equals_n_and_large_coordinates() { + let data = [f32::MAX, -f32::MAX, -f32::MAX, f32::MAX]; + let model = fit( + &data, + 2, + &Config { + clusters: 2, + batch_size: Some(100), + ..Config::default() + }, + ) + .unwrap(); + assert_eq!(model.batch_size, 2); + assert_eq!(model.mse, 0.0); + assert_ne!(model.assignments[0], model.assignments[1]); +} + +#[test] +fn validates_before_training_and_checks_mutated_models_on_predict() { + let good = Config { + clusters: 1, + ..Config::default() + }; + for (data, dim) in [ + (vec![], 2), + (vec![1.], 0), + (vec![1.], 2), + (vec![f32::NAN], 1), + (vec![f32::INFINITY], 1), + ] { + assert!(fit(&data, dim, &good).is_err()); + } + for config in [ + Config { + clusters: 0, + ..good.clone() + }, + Config { + clusters: 3, + ..good.clone() + }, + Config { + epochs: 0, + ..good.clone() + }, + Config { + batch_size: Some(0), + ..good.clone() + }, + Config { + peak_step: Some(0.), + ..good.clone() + }, + Config { + peak_step: Some(-0.1), + ..good.clone() + }, + Config { + peak_step: Some(1.1), + ..good.clone() + }, + Config { + peak_step: Some(f64::NAN), + ..good.clone() + }, + Config { + epochs: usize::MAX, + batch_size: Some(1), + ..good.clone() + }, + ] { + assert!(fit(&[1., 2.], 1, &config).is_err()); + } + let mut model = fit(&[1., 2.], 1, &good).unwrap(); + assert!(model.predict(&[]).unwrap().is_empty()); + model.dimensions = 0; + assert!(model.predict(&[1.]).is_err()); + assert!(predict(&[1., 2.], 2, &[1.]).is_err()); + assert!(predict(&[1.], 1, &[]).is_err()); +} + +#[cfg(feature = "serde")] +#[test] +fn serializable_public_api_is_available() { + fn serializable serde::Deserialize<'de>>() {} + serializable::(); + serializable::(); +} diff --git a/crates/ruvector-e-means/tests/ivf.rs b/crates/ruvector-e-means/tests/ivf.rs new file mode 100644 index 0000000000..067c016487 --- /dev/null +++ b/crates/ruvector-e-means/tests/ivf.rs @@ -0,0 +1,103 @@ +use ruvector_e_means::{Config, IvfPartition, Model}; + +fn model() -> Model { + Model { + centroids: vec![0.0, 10.0], + dimensions: 1, + assignments: vec![1, 0, 1, 0], + mse: 0.0, + batch_size: 4, + peak_step: 0.2, + updates: 1, + revived_clusters: 0, + } +} + +#[test] +fn stable_postings_group_every_input_row_exactly_once() { + let partition = IvfPartition::from_model(model()).unwrap(); + assert_eq!(partition.offsets(), [0, 2, 4]); + assert_eq!(partition.indices(), [1, 3, 0, 2]); + assert_eq!(partition.posting(0).unwrap(), [1, 3]); + assert_eq!(partition.posting(1).unwrap(), [0, 2]); + assert!(partition.posting(2).is_err()); + let restored = IvfPartition::from_parts( + model(), + partition.offsets().to_vec(), + partition.indices().to_vec(), + ) + .unwrap(); + assert_eq!(restored.indices(), partition.indices()); +} + +#[test] +fn fit_partitions_final_predictions_in_original_row_order() { + let data = [10.0, -10.0, 11.0, -11.0, 12.0, -12.0]; + let partition = IvfPartition::fit( + &data, + 1, + &Config { + clusters: 2, + epochs: 5, + ..Config::default() + }, + ) + .unwrap(); + let model = partition.model(); + assert_eq!(model.predict(&data).unwrap(), model.assignments); + let mut ids = partition.indices().to_vec(); + ids.sort_unstable(); + assert_eq!(ids, (0..data.len()).collect::>()); + for cluster in 0..2 { + let posting = partition.posting(cluster).unwrap(); + assert!(posting.windows(2).all(|p| p[0] < p[1])); + assert!(posting.iter().all(|&id| model.assignments[id] == cluster)); + } +} + +#[test] +fn malformed_offsets_labels_and_row_permutations_reject() { + for (offsets, indices) in [ + (vec![1, 2, 4], vec![1, 3, 0, 2]), + (vec![0, 3, 4], vec![1, 3, 0, 2]), + (vec![0, 5, 4], vec![1, 3, 0, 2]), + (vec![0, 2], vec![1, 3, 0, 2]), + (vec![0, 2, 4], vec![1, 1, 0, 2]), + (vec![0, 2, 4], vec![3, 1, 0, 2]), + (vec![0, 2, 4], vec![1, 3, 0, 9]), + (vec![0, 2, 4], vec![1, 3, 0]), + ] { + assert!(IvfPartition::from_parts(model(), offsets, indices).is_err()); + } + let mut invalid = model(); + invalid.assignments[0] = 2; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.centroids[0] = f32::INFINITY; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.dimensions = 0; + assert!(IvfPartition::from_model(invalid).is_err()); + let mut invalid = model(); + invalid.batch_size = 0; + assert!(IvfPartition::from_model(invalid).is_err()); +} + +#[cfg(feature = "serde")] +#[test] +fn serde_roundtrip_rejects_corrupted_postings_and_models() { + let partition = IvfPartition::from_model(model()).unwrap(); + let value = serde_json::to_value(&partition).unwrap(); + let restored: IvfPartition = serde_json::from_value(value.clone()).unwrap(); + assert_eq!(restored.offsets(), partition.offsets()); + assert_eq!(restored.indices(), partition.indices()); + let mut invalid = value.clone(); + invalid["indices"] = serde_json::json!([1, 1, 0, 2]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value.clone(); + invalid["model"]["assignments"] = serde_json::json!([2, 0, 1, 0]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value; + invalid["offsets"] = serde_json::json!([0, 4, 2]); + assert!(serde_json::from_value::(invalid).is_err()); +} diff --git a/crates/ruvector-e-means/tests/quantization.rs b/crates/ruvector-e-means/tests/quantization.rs new file mode 100644 index 0000000000..7f88a70061 --- /dev/null +++ b/crates/ruvector-e-means/tests/quantization.rs @@ -0,0 +1,113 @@ +use ruvector_e_means::{Config, ProductQuantizer}; + +#[test] +fn subspace_layout_codes_and_reconstruction_have_an_independent_oracle() { + let pq = ProductQuantizer::from_centroids( + 4, + 2, + 2, + vec![0.0, 0.0, 10.0, 10.0, 100.0, 100.0, 200.0, 200.0], + ) + .unwrap(); + let data = [0.0, 0.0, 200.0, 200.0, 10.0, 10.0, 100.0, 100.0]; + assert_eq!(pq.encode(&data).unwrap(), [0, 1, 1, 0]); + assert_eq!(pq.decode(&[0, 1, 1, 0]).unwrap(), data); + assert_eq!(pq.encode(&[5.0, 5.0, 150.0, 150.0]).unwrap(), [0, 0]); + assert!(pq.encode(&[]).unwrap().is_empty()); + assert!(pq.decode(&[]).unwrap().is_empty()); +} + +#[test] +fn fitted_single_codebooks_recover_column_means() { + let pq = ProductQuantizer::fit( + &[1.0, 10.0, 3.0, 30.0, 5.0, 50.0], + 2, + 2, + &Config { + clusters: 1, + batch_size: Some(2), + ..Config::default() + }, + ) + .unwrap(); + assert_eq!( + ( + pq.dimensions(), + pq.subspaces(), + pq.clusters(), + pq.subspace_dimensions() + ), + (2, 2, 1, 1) + ); + assert_eq!(pq.centroids(), [3.0, 30.0]); + assert_eq!( + pq.decode(&pq.encode(&[2.0, 20.0, 9.0, 90.0]).unwrap()) + .unwrap(), + [3.0, 30.0, 3.0, 30.0] + ); +} + +#[test] +fn checked_pq_boundaries_reject_malformed_and_nonfinite_data() { + for (dimensions, subspaces, clusters, centroids) in [ + (0, 1, 1, vec![]), + (2, 0, 1, vec![0.0; 2]), + (3, 2, 1, vec![0.0; 3]), + (2, 1, 0, vec![]), + (1, 1, 257, vec![0.0; 257]), + (2, 1, 1, vec![0.0]), + (1, 1, 1, vec![f32::NAN]), + (usize::MAX, 1, 256, vec![]), + ] { + assert!( + ProductQuantizer::from_centroids(dimensions, subspaces, clusters, centroids).is_err() + ); + } + let pq = ProductQuantizer::from_centroids(2, 2, 1, vec![0.0; 2]).unwrap(); + assert!(pq.encode(&[1.0]).is_err()); + assert!(pq.encode(&[f32::INFINITY, 0.0]).is_err()); + assert!(pq.decode(&[0]).is_err()); + assert!(pq.decode(&[0, 1]).is_err()); + assert!(ProductQuantizer::fit(&[], 2, 2, &Config::default()).is_err()); + assert!(ProductQuantizer::fit( + &[0.0; 8], + 2, + 2, + &Config { + clusters: 5, + ..Config::default() + } + ) + .is_err()); +} + +#[test] +fn all_u8_codes_and_large_finite_distances_remain_valid() { + let pq = + ProductQuantizer::from_centroids(1, 1, 256, (0..256).map(|v| v as f32).collect()).unwrap(); + assert_eq!(pq.encode(&[255.0]).unwrap(), [255]); + assert_eq!(pq.decode(&[255]).unwrap(), [255.0]); + let magnitude = f32::MAX / 4.0; + let pq = ProductQuantizer::from_centroids(1, 1, 2, vec![-magnitude, magnitude]).unwrap(); + assert_eq!(pq.encode(&[magnitude * 2.0]).unwrap(), [1]); +} + +#[cfg(feature = "serde")] +#[test] +fn serde_roundtrip_validates_the_codebook_before_it_becomes_usable() { + let pq = ProductQuantizer::from_centroids(2, 2, 2, vec![0.0, 1.0, 10.0, 20.0]).unwrap(); + let value = serde_json::to_value(&pq).unwrap(); + let restored: ProductQuantizer = serde_json::from_value(value.clone()).unwrap(); + assert_eq!(restored.encode(&[1.0, 20.0]).unwrap(), [1, 1]); + for field in ["dimensions", "subspaces", "clusters"] { + let mut invalid = value.clone(); + invalid[field] = 0.into(); + assert!(serde_json::from_value::(invalid).is_err()); + } + let mut invalid = value.clone(); + invalid["centroids"] = serde_json::json!([0.0]); + assert!(serde_json::from_value::(invalid).is_err()); + let mut invalid = value; + invalid["extra"] = true.into(); + assert!(serde_json::from_value::(invalid).is_err()); +} diff --git a/docs/adr/ADR-359-e-means-shared-clustering.md b/docs/adr/ADR-359-e-means-shared-clustering.md new file mode 100644 index 0000000000..da1289c54e --- /dev/null +++ b/docs/adr/ADR-359-e-means-shared-clustering.md @@ -0,0 +1,263 @@ +# ADR-359: Shared e-means clustering for RuVector and ruv-FANN + +- **Status**: Accepted; local implementation, registry publication pending +- **Date**: 2026-11-11 +- **Updated**: 2026-11-11 (split shared release qualification) +- **Source**: Bessa et al., [e-means: outperforming k-means (in one-tenth the epochs)](https://arxiv.org/abs/2611.09501), [version 1](https://arxiv.org/html/2611.09501v1), 2026-11-06 +- **Related**: [ruv-FANN ADR-013](https://github.com/ruvnet/ruv-FANN/blob/main/docs/adr/ADR-013-e-means-clustering.md) + +## Release qualification + +The shared package is promoted separately from dependent integrations; see +[the protected leaf release protocol](../e-means-release.md). The browser route +was corrected and its missing-route mutation fails. PQ/IVF validators inspect +typed-array storage without caller-defined iterators. Local qualification of +the archived-source WASM build passed native/MSRV, npm, installed-consumer, +workerd and real Chromium checks; registry publication remains subject to the +exact-source protected workflow and fresh public consumers. + +## Context and scope + +RuVector trains product-quantization codebooks with Lloyd k-means. ruv-FANN +consumers also need unsupervised clustering of input embeddings without changing +their supervised labels or neural optimizers. Maintaining independent clustering +implementations for Rust and JavaScript would make numerical fixes and paper +conformance diverge. + +The paper proposes mini-batch EMA sufficient statistics plus a particular +initialization, schedule, cluster revival, and finalization recipe. Its reported +GPU results motivate implementation, but do not establish performance of this CPU +implementation. Its fitted hyperparameters are less reliable for tiny and +low-dimensional data, including many PQ subspaces. This release therefore adds +explicit e-means APIs while preserving existing training defaults and persisted +codebook formats. + +## Decision and contracts + +Create `ruvector-e-means` 0.1.0 as a separately publishable, MIT-licensed crate in +`crates/ruvector-e-means`, registered in the workspace. The native core requires +Rust 1.81, has no default features, and has no dependency on either consumer. +`serde` adds config/model serialization. `wasm` adds a thin wasm-bindgen bridge. +Pin wasm-bindgen and its build CLI to the existing workspace version 0.2.125 so +this feature does not upgrade other packages' WASM dependency stack. + +The public core API is `fit(flat_f32_rows, dimensions, &Config) -> Result` +and exact `predict`. `Config` exposes clusters, epochs (default 3), optional batch +and peak-step overrides, seed (default 42), and finalization. `Model` returns flat +centroids, assignments, dimensions, squared-L2 MSE per vector, resolved batch and +step, update count, and number of revived clusters. Assignments are recomputed +against the returned centroids in original row order. Public/deserialized +codebooks are validated when passed to prediction. + +Implement the paper's primary recipe: + +1. Seeded ChaCha8 sampling without replacement for initial centroids; initialize + counts to `1e-10` and sums to count times centroid (equation 4). +2. Resolve `B = 0.035 k^0.13 n^0.88 T^0.81`, divided by eight when + `n > 2,000,000`, rounded to the nearest power of two and capped at `n`. + Resolve `alpha0 = min(0.824 k^-0.46 B^0.90 n^-0.45 T^-0.11, 1)` using + the effective batch size (equations 6–7, table 2). +3. Shuffle each epoch. Assign rows by exact squared L2 and accumulate per-cluster + batch counts/sums. Update every cluster's statistics with equation 2 and + the cosine step from equation 5, including its 0.1 floor and `t/M` denominator. +4. Every five batches revive counts below 0.1 times the mean count. Draw live + donors proportional to count, without replacement. Split count in half and + perturb child coordinates by alternating `1 +/- 1/128` (Appendix H). +5. Finalize using the mean of assignments recorded during the last epoch, or + return the main EMA centroids. Recompute nearest assignments and MSE in a + final exact pass. + +Use f64 sums, counts, and distances, and f32 codebooks. Retain a negligible +pseudo-count for a temporarily empty cluster when a step of one would otherwise +erase its state. Clamp extreme split coordinates to finite f32. Final clusters +without recorded rows retain their EMA centroid. If dead slots outnumber live +donors, remaining slots wait until a later revival pass. + +Two deliberate execution differences from the printed algorithm are explicit: +include short tail batches rather than dropping rows, with +`M = T * ceil(n/B)`; and recompute final nearest assignments/MSE rather than +reporting the loss of stale last-epoch assignments. Last-epoch mean is an average +of assignments made while centroids moved, not a separate Lloyd iteration, so we +do not promise monotonic improvement over the final EMA model. + +`@ruvector/e-means` 0.1.0 in `npm/packages/e-means` ships that same Rust core as +portable WebAssembly, typed ESM APIs, and the matching generated loader. +`await init()` loads bundled bytes in Node and fetches them in a browser; +`fit(Float32Array, dimensions, options)` and `predict` run synchronously after +initialization. No JavaScript numerical fallback or Rust installation is needed +by an installed consumer. Training calls are bounded by caller-selected sizes +and epochs and can block the caller; applications should use workers for long +runs. The Rust crate itself does not spawn threads or fetch datasets. + +## Consumer integration and release order + +- RuVector core directly depends on the new crate and exposes + `ProductQuantized::train_e_means(vectors, num_subspaces, &Config)`. It trains + each subspace with the shared implementation and retains u8 codes and the + current codebook serialization. f64 encode comparisons preserve nearest + ordering for large finite f32 coordinates. +- The main `ruvector` npm package depends on exact `@ruvector/e-means` 0.1.0 and + ships `ruvector/clustering.mjs` with matching ESM declarations. This explicit + subpath avoids eagerly initializing WASM or restricting legacy package + subpaths with a new exports map. +- ruv-FANN has an optional `clustering` Cargo feature with a version-only + dependency on `ruvector-e-means` 0.1.0, re-exported types/functions, and + `TrainingData::cluster_inputs`. It clusters inputs without mutating inputs + or outputs. Its npm facade depends on exact `@ruvector/e-means` 0.1.0 and + exposes `ruv-fann/clustering` without changing the root neural API. + +Publish the new crate and npm package before releasing dependent consumer +versions. Before registry publication, qualify ruv-FANN with an explicit local +Cargo patch and install the packed npm dependency in isolated consumer tests: + +```sh +cd ../ruv-FANN +cargo test --features clustering --test clustering_tests \ + --config 'patch.crates-io.ruvector-e-means.path="../ruvector/crates/ruvector-e-means"' +``` + +No sibling checkout path is committed in ruv-FANN's published dependency +contract. Its version-only dependency cannot resolve from a fresh registry +checkout until the new crate is published, even with the feature disabled. +Local lockfile qualification with a patch does not prove registry availability. +Do not claim publication based on a successful local build or archive check. + +## Alternatives and consequences + +- Copying the algorithm into both projects and npm would multiply maintenance + and correctness risk. A single Rust implementation compiled to WASM keeps + numerical behavior shared. +- Replacing all Lloyd defaults immediately risks quality regressions for small + PQ subspaces outside the scaling laws' fitted domain. Explicit APIs allow + evaluation with real embeddings and consumer-specific recall/latency gates. +- A GPU/PyTorch/Faiss runtime dependency would add substantial deployment cost. + This CPU reference and portable WASM establish the contract first. GPU, + low-precision, distributed/IVF assignment, slow-EMA finalization, arbitrary + streaming updates, and wholesale replacement of all clustering call sites are + outside this release. + +The algorithm stores O(n + kd) scratch state and performs O(Tnkd) exact-distance +work plus a final O(nkd) scoring pass. Training is synchronous. Seeded shuffles +are stable across native/WASM; platform transcendental routines can introduce +small floating-point differences, so cross-target numerical checks use an +appropriate tolerance rather than a universal bit-identity claim. + +## Acceptance and validation + +| Requirement | Executable evidence | +|---|---| +| Paper coefficients, cosine schedule, weighted mass-preserving revival | `cargo test -p ruvector-e-means` | +| Mean/MSE oracle, all tail rows visited, reproducibility, separated clouds | crate `tests/clustering.rs` | +| Empty/ragged/nonfinite shapes, invalid configs, overflow, duplicate/zero/extreme inputs | crate and consumer Rust tests; npm WASM tests | +| PQ representation, serialization, all 256 u8 codes, extreme nearest comparison | `cargo test -p ruvector-core --no-default-features --test e_means_quantization` | +| ruv-FANN adapter and unchanged supervised state | patched `clustering_tests` plus existing library tests | +| Same Rust core used through typed npm facade | `npm test` and `npm run typecheck` in the new package; consumer facade tests | +| Complete installable npm artifact without repository paths | `npm run test:consumer` in the new package | +| Browser default fetch/initialization | new package's headless browser consumer test | + +Build WASM with `npm run build` in the new package, using the pinned CLI. Its +prepack check executes the shipped artifact. Review and run the targeted checks +before release; this ADR does not certify the entire monorepo, GPU speedups, or +universal quality superiority. Rollback means use the retained Lloyd/neural APIs +or stop importing the clustering subpaths; existing persisted codebooks need no +migration. + +### Initial local qualification on 2026-11-11 (historical) + +- The shared crate passed 10 native tests with all features and strict Clippy. + `cargo package --allow-dirty` built and verified the archive. Its native core + also passed `cargo +1.81.0 check --locked` against the packaged manifest. +- Actual RuVector core passed 6 new integration tests and 36 existing + quantization tests. ruv-FANN passed 3 adapter tests and 207 existing library + tests with the local dependency patch. +- The final wasm-bindgen 0.2.125 artifact passed 9 Node numerical/API tests, + offline installed-archive qualification, strict TypeScript, and both consumer + facade checks. Packed ruv-FANN was also installed with the packed dependency + and exercised through its public subpath. +- Browser execution remains unverified here: the browser consumer timed out, + and independent Chromium `about:blank` startup also timed out, including a + single-process baseline. The checked-in browser test fails on that timeout; + no skip or simulated success is counted as a pass. Re-run it in a working + Chromium environment before claiming browser qualification. + +These are focused local checks. Neither registry publication nor full-monorepo +qualification was performed. + +## Optimization qualification + +Exact partial-distance pruning checks candidates every eight coordinates for +dimensions above 16, while small codebooks retain scalar distance evaluation. +Zero distance ends the search. These changes retain the scalar addition order +and lowest-index ties. Independent exhaustive-oracle tests cover diffuse and +separated inputs, extreme/subnormal coordinates, near ties, and dimensions with +incomplete final blocks. The optimization does not add approximate assignment +or change seeded shuffles, sufficient statistics, or finalizers. + +Training uses sliced centroid rows, reuses dead/donor scratch capacity, skips +donor-list construction when no cluster is dead, and omits last-epoch statistics +for EMA finalization. PQ encoding computes each candidate distance once. The +WASM wrapper keeps JSON for the small config and returns vectors as owned typed +arrays, releasing its temporary Rust handle in `finally`. Tests check repeated +fits, error-path cleanup, and output survival after WASM memory growth. + +The author's run on an AMD EPYC 9V74 environment, with five interleaved native +repetitions, recorded these median fit times for last-epoch-mean finalization. +The "Before" build is a pre-optimization version of this crate that is not in +the repository, so these ratios cannot be re-run from the tree: + +| Synthetic input (n × d, clusters) | Before | After | Speedup | +|---|---:|---:|---:| +| Clustered embeddings (4096 × 128, 64) | 130.05 ms | 70.57 ms | 1.84× | +| Diffuse embeddings (2048 × 768, 32) | 203.61 ms | 177.48 ms | 1.15× | +| Duplicate/zero rows (2048 × 32, 64) | 13.35 ms | 2.53 ms | 5.29× | + +All model fields and predictions matched the baseline bit for bit in eight +native scenarios. A 21-repeat 8D PQ follow-up measured 51.25→52.68 ms with +last-epoch mean and 50.28→50.83 ms with EMA; no PQ speedup is claimed. EMA mode +on the 768D fixture reduced peak additional requested heap from 721,664 to +525,312 bytes. Last-epoch-mean mode may retain a little more scratch capacity; +allocation-event reduction is distinct from peak-memory reduction. + +In the same author run, Node 24 WASM median-of-seven fit times were 36.19→15.00 ms (2.41×) for an +8192 × 64, 16-cluster fixture and 84.09→61.57 ms (1.37×) for one million +scalar rows with one cluster. Both match baseline centroids, assignments and +MSE. Comparing JSON and typed output using the same optimized kernel measured +75.97→58.41 ms on the million-row fixture; this includes the whole fit and +materialization, not just conversion time. + +Independent review reproduction (2026-11-11, ruvultra, Rust 1.99.1 with the +workspace release profile for both sides, one pinned core, five interleaved +rounds of five repetitions). The baseline is this tree with partial-distance +pruning disabled (`nearest` always takes the scalar path), so it isolates the +pruning change only. It does not include the other optimizations above: + +| Synthetic input (n × d, clusters) | Pruning off | Pruning on | Speedup | +|---|---:|---:|---:| +| Clustered embeddings (4096 × 128, 64) | 57.55 ms | 36.40 ms | 1.58× | +| Diffuse embeddings (2048 × 768, 32) | 97.95 ms | 98.30 ms | 1.00× | +| 8D PQ (8192 × 8, 256) | 28.83 ms | 28.80 ms | 1.00× | +| Duplicate/zero rows (2048 × 32, 64) | 3.65 ms | 1.44 ms | 2.54× | + +The npm `benchmark` 8192 × 64, 16-cluster fixture measured 17.0→7.5 ms +(2.26×) against a pruning-off WASM build. All eight native digests +(centroid bits and assignments) equal both the pruning-off build and the +digests recorded in the measurement artifact, and the WASM fixtures matched +with zero label or centroid differences. The shipped `.wasm` rebuilds +byte-for-byte from this source with Rust 1.99.1 and wasm-bindgen 0.2.125 +(`--remap-path-prefix` set to the author's home directory). Treat the author +ratios above as that environment's results against an earlier build, and the +reproduction as the checked effect of pruning. + +The [measurement artifact](../research/e-means/performance-2026-11-11.json) +records shapes, options, raw native samples, environment, allocation definitions, +and source/artifact checksums. The native benchmark example and npm `benchmark` +command reproduce current measurements. These synthetic CPU/WASM results do not +establish speedups on arbitrary datasets or the paper's GPU benchmarks. At that initial checkpoint browser +qualification and registry publication remained pending. The release qualification +section above records later browser execution; publication still requires the protected workflow. + +Initial post-optimization validation passed 14 shared-crate tests, 6 PQ integration +tests, 20 existing core quantization tests, 207 ruv-FANN library tests and its +3 adapter tests. The npm runtime passed 13 numerical/ownership tests, installed +archive checks, both consumer facades and strict TypeScript. Strict Clippy, +crate archive verification, and the packaged native Rust 1.81 check also passed. diff --git a/docs/adr/ADR-360-e-means-ecosystem-integrations.md b/docs/adr/ADR-360-e-means-ecosystem-integrations.md new file mode 100644 index 0000000000..eb0a80c91b --- /dev/null +++ b/docs/adr/ADR-360-e-means-ecosystem-integrations.md @@ -0,0 +1,186 @@ +# ADR-360: e-means ecosystem submodules, MetaHarness, and Cloudflare Workers + +- **Status**: Accepted; local integration implemented, publication and deployment pending +- **Date**: 2026-11-11 +- **Updated**: 2026-11-11 (leaf publication and dependency contract review) +- **Related**: [ADR-359](./ADR-359-e-means-shared-clustering.md) + +## Outcome and acceptance contract + +Make the shared e-means implementation usable for existing PQ/IVF indexes, +neural-input workflows, measured MetaHarness tuning, and Cloudflare Workers. +Integrations must invoke the real Rust/WASM kernel, preserve current training +defaults, expose explicit typed entrypoints, and run from installed npm archives. +Here, submodules mean Rust modules and npm export subpaths; no Git submodule +checkout is required. + +Success requires numerical encode/decode and posting-list oracles; checked +restoration of persisted records; actual Darwin evolution with held-out scoring; +authenticated, resource-bounded Worker execution with statically imported WASM; +and real local workerd/R2 qualification. Hosted deployment, registry publication, +and live Vectorize mutation are outside this implementation request. + +## Module boundaries + +| Surface | Interface and responsibility | +|---|---| +| Rust `quantization` | `ProductQuantizer::fit`, checked `from_centroids`, byte `encode`/`decode`, private shape fields, validated serde restoration | +| Rust `ivf` | `IvfPartition::fit`, checked `from_model`/`from_parts`, stable offsets/indices, checked `posting` access | +| npm `/quantization` | `trainProductQuantizer`, `encodeProductQuantizer`, `decodeProductQuantizer`, validated owned JSON conversions | +| npm `/ivf` | `partition` and `postingList`, with owned typed arrays and stable input-row IDs | +| npm `/runtime` | Node-free `init(source)`, `fit`, `predict`; requires explicit bytes or a precompiled module | +| npm `/metaharness` | `createClusteringEvaluator` and bounded Node-only `tuneClustering`, using the actual Darwin numeric API | +| npm `/cloudflare` | Stateless Worker factory and explicit R2/Vectorize binding helpers | +| npm `/cloudflare/build` | Node-only local static-WASM builder, using esbuild; never deploys | +| npm `/wasm` | Raw artifact export for Wrangler's static WebAssembly import | + +PQ decomposition and posting construction wrap the shared fitter and nearest +assignment. There is no second JavaScript clustering optimizer. All PQ codes are +row-major, one u8 per subspace; centroids are subspace-major. Rust and JavaScript +use the same numeric layout, but JS JSON has an explicit schema envelope. Remove +that envelope before native serde deserialization, or construct the native +quantizer with its checked `from_centroids` API. Do not assume arbitrary JSON +records from the two APIs are interchangeable. + +## Dependent integrations (separate promotion) + +- `ruvector-core::ProductQuantized::train_e_means` remains available from ADR-359. +- `ruvector-pq-search` adds `PqCodebook::train_e_means`, + `IvfPqIndex::new_e_means`, and checked insertion/query wrappers. Existing PQ + layouts and ADC search behavior remain in place. +- `ruvector-rairs` adds explicit training to `IvfFlat`, `RairsStrict`, and + `RairsSeil`. Invalid training leaves state intact. Successful explicit + retraining resets inserted vectors and IDs, as documented by these methods. +- `@ruvector/core`, `ruvector`, and `@ruvector/all` ship `clustering.mjs` and + `clustering/{quantization,ivf,metaharness,cloudflare}.mjs`, with `.d.mts` + declarations. Their existing package subpaths remain accessible. +- The current `@ruvector/wasm` source at `crates/ruvector-wasm` exposes + `/clustering` and `/clustering/{quantization,ivf,metaharness,cloudflare}`. + Historical same-name manifest copies are not release sources for this change. +- `ruv-fann` and `@ruv-fann/integrations` expose corresponding clustering + subpaths. Existing WSP Cloudflare and neural MetaHarness entrypoints retain + their own meanings. + +Each npm consumer depends on exact `@ruvector/e-means` 0.1.0. Static +clustering re-exports require it as a normal dependency, including in +`@ruvector/core`; the package's Node 20 runtime requirement applies to these +entrypoints. The new modules do not eagerly initialize WASM or import Darwin +during ordinary SDK imports. These consumer changes are outside the leaf +publication commit and are promoted after the shared registries are verified. + +Shared modules use f64 assignment arithmetic. Existing downstream ADC/scanning +APIs retain their existing f32 precision and legacy validation behavior; this +integration does not certify those algorithms for extreme f32 magnitudes or +silently replace their defaults. + +## MetaHarness control flow and evidence + +The evaluator synchronously copies training/holdout arrays and snapshots the +baseline, domain, and budgets before its first await. Holdout rows must be +nonempty and nonoverlapping with training rows. Each dispatch validates the +genome, reserves its work allowance, executes real WASM training, and separately +predicts and scores the holdout. Higher-is-better `primary = 1/(1+holdoutMse)` +matches Darwin's score contract. Records include actual training/holdout MSE, +fit/prediction timings, selected configuration, and resource estimates. + +Only one evaluation runs at a time, with at most 32 admitted dispatches, +64 MiB of input snapshots, and a caller-selected allowance capped at 1e9 +coordinate-scale work units. Admission includes centroid updates, tail batches, +and quadratic donor selection. Units are conservative estimates, not measured +instructions or a process-memory limit. Deadlines are cooperative; synchronous +fits and arbitrary host operations cannot be preempted. + +`tuneClustering` dynamically loads `@metaharness/darwin` 0.13.0 or 0.13.1, validates +the installed identity/API, and calls its real `evolveNumeric` at concurrency 1. +It checks worst-case search cost before execution and matches returned archive +records to observed evaluations. Regressed/unmeasured winners cannot replace +the baseline recommendation. A temporary archive is removed in `finally`. +Receipts and returned scores are independent copies; `sourceApplied` is always +false. The holdout guides selection and is not an independent generalization +test. SDK version checking is metadata validation, not binary attestation. + +The SDK is an optional peer, loaded only when tuning is invoked. Package tests +exercise both an installation without that peer and actual evolution with the +pinned peer installed. + +## Cloudflare execution and authority boundaries + +Wrangler imports `.wasm` as `WebAssembly.Module`; the Worker passes that static +module to the Node-free runtime. No Node filesystem loader, downloaded model, +runtime source compilation, or `instantiateStreaming` path is needed. + +The Worker exposes public `/health` and authenticated POST `/fit` and `/predict`. +Operations fail closed when no token is configured, except an explicit trusted +local `allowUnauthenticated` opt-in. The example reads `E_MEANS_BEARER_TOKEN` +from the caller's binding configuration; credentials are not packaged. + +Before entering WASM, the handler reads bounded UTF-8 JSON with a stream deadline +and validates exact fields, finite float32 values, shapes, options, and work. +Absolute caps include 1 MiB request bodies, 262,144 elements, 16,384 rows, +1,536 dimensions, 256 clusters, 32 epochs, and 1e8 estimated work units; defaults +are smaller. The work estimate includes updates and donor revival. These are +per-call bounds, not a guarantee against aggregate isolate exhaustion or a hard +CPU-time cap. Request vectors/models are not kept in global mutable state, and +HTTP responses expose no unexpected stack traces. + +Storage operations are explicit helper calls on caller-owned bindings. HTTP +fitting does not automatically store or export anything: + +- R2 stores only bounded centroid codebooks, not source vectors or assignments. + Writes require an acknowledgement; reads validate streamed bytes and schema + before constructing owned numeric arrays. PQ schema records are rejected + because their subspace-major layout is not a single centroid set. +- Vectorize V2 exports validate the entire snapshot and identifier/namespace + byte lengths before the first upsert. Batches are limited to 1,000 vectors + and dimensions to 1,536. Every acknowledgement must carry a mutation ID. + An acknowledgement does not prove immediate query visibility. +- Export failures report prior acknowledged rows/mutation IDs. The failed batch + may also have applied; no transaction, rollback, retry, or deletion is implied. + Use a versioned prefix/namespace for revised codebooks, since upserts do not + remove stale IDs from an older, larger codebook. + +Official Cloudflare references: [WASM bundling](https://developers.cloudflare.com/workers/wrangler/bundling/), +[Vectorize limits](https://developers.cloudflare.com/vectorize/platform/limits/), +[asynchronous mutations](https://developers.cloudflare.com/vectorize/get-started/intro/). +The connected Cloudflare documentation tool was used to verify these contracts. + +## Packaging, validation, and rollback + +Use the isolated package lock in `npm/packages/e-means` for integration tooling. +Miniflare 4.20260730.0 and esbuild 0.28.2 are development-only. Scoped overrides +select patched sharp 0.35.5 and undici 7.30.1; re-run workerd tests and the +lockfile-aware audit when updating them. The workspace lock records this tool +graph beneath the e-means workspace without upgrading unrelated dependency +versions. Whole-workspace installation remains separately constrained by the +repository's existing platform-specific workspace packages. + +| Requirement | Check | +|---|---| +| Native layout, persisted-state validation, real index consumers | `cargo test -p ruvector-e-means --features serde -p ruvector-pq-search -p ruvector-rairs` | +| Existing shared core and optional WASM bridge | `cargo test -p ruvector-e-means --all-features` | +| JS numerical, ownership, holdout, budget and HTTP boundaries | `npm test` in the shared package | +| Installed package without/with actual optional Darwin SDK | `npm run test:consumer` | +| New entrypoints from actual consumer archives | `npm run test:ecosystem` | +| Real static WASM and R2 in local workerd | `npm run test:cloudflare` | +| Public declarations | `npm run typecheck` and installed consumer checks | +| Newly selected tool dependency graph | `npm audit --package-lock-only --workspaces=false` | + +Consumer archive tests qualify the new clustering subpaths. Their unrelated +legacy root/prepack release builds are not qualified by this task. Vectorize +has binding-contract tests, not a claimed hosted index write. No Cloudflare +deployment or registry publication is inferred from passing local checks. + +Release the shared crate/package first, bump affected consumer release versions, +and verify registry installs before publishing consumers. Local ruv-FANN Rust +checks use the explicit Cargo patch from ADR-359. Rollback means stop using the +new feature methods or subpaths; existing codebooks, neural APIs, and search +defaults require no migration. Storage helpers never delete external resources. + +Initial integration qualification passed 50 targeted Rust tests, 44 shared npm tests, 8 FANN +facade tests, and 3 Rust FANN adapter tests, plus strict declarations, Clippy, +archive verification and the packaged Rust 1.81 check. Installed consumers +exercised the optional-SDK absence path, actual Darwin evolution, all four +RuVector facade packages, and static-WASM/R2 execution in real local workerd. +The isolated integration-tool lockfile audit reported zero known advisories +after the scoped overrides. [Qualification evidence](../research/e-means/integrations-qualification.json) +records versions, scope limits, and current lock/artifact digests. diff --git a/docs/e-means-release.md b/docs/e-means-release.md new file mode 100644 index 0000000000..4aef5cdc9d --- /dev/null +++ b/docs/e-means-release.md @@ -0,0 +1,50 @@ +# Shared e-means release + +The shared `ruvector-e-means` crate and `@ruvector/e-means` package are released +before their dependent consumer integrations. This leaf change contains no new +consumer dependency on an unpublished registry package. RuVector PR #1489 and +ruv-FANN PR #227 integrate the public dependencies afterward. + +The release branch runs `e-means-preflight.yml` at an immutable source commit. +Its 15 mandatory commands execute the shared native tests and strict Clippy, +verify a Cargo archive, audit that archive's dependency lock, check Rust 1.81, +execute the packaged Rust tests, and build WASM from the extracted archive. +The WASM build explicitly retains the workspace release optimization settings. +The copied npm package then runs its dependency audit, real WASM/Worker tests, +strict declarations, installed consumers with and without the optional SDK, +and real Chromium numerical checks before packing. A second job installs the +sealed archive offline and exercises the portable APIs on Node 20.0.0. + +The source-bound candidate records actual command exit codes, owned logs and +digests. The verifier requires the complete ordered command set and derives +test counts again from the logs. Zero tests, ignored/filtered Rust tests, +skipped/todo Node tests, missing browser or installed-consumer checks, altered +payloads and missing harness files reject the candidate. + +After that unchanged commit reaches main, `e-means-protected-release.yml` +selects the successful release-branch run itself. It requires current main, +zero labeled release blockers, both successful jobs, a unique source-bound +artifact and its GitHub ZIP digest. Both public registries are checked for +conflicting immutable bytes before either upload. The controller uploads only +the sealed crate and npm archives, then compares public downloads. Publication +credentials are limited to that upload step. + +The final consumer step uses a virgin Cargo home with an exact registry pin, +checks the official Cargo registry source and checksum, and executes numerical +fit/predict/PQ/IVF assertions. It installs the public npm package separately, +compares installed files with the public archive, then runs the transferred +test harness, strict declarations and actual Chromium. Partial publication is +not a completed release; retained receipts and command logs identify the state. + +After public consumers pass, the protected job creates immutable tag +`e-means-v0.1.0` and a draft GitHub release. It attaches the canonical archives, +original candidate ZIP, checksums, source-bound receipts and actual command logs. +Every asset is downloaded and compared before the draft becomes public and +again afterward. A conflicting tag or asset rejects promotion; an identical +partial draft may resume without overwriting bytes. + +This is scoped package qualification. The existing broad-monorepo advisory +failure is tracked separately in RuVector #1487. A successful leaf audit does +not claim that unrelated workspace dependencies or hosted deployments passed. +Historical benchmark results retain their original provenance; this release +does not relabel them as measurements of the sealed public artifacts. diff --git a/docs/research/e-means/integrations-qualification.json b/docs/research/e-means/integrations-qualification.json new file mode 100644 index 0000000000..4cfee7cddd --- /dev/null +++ b/docs/research/e-means/integrations-qualification.json @@ -0,0 +1,70 @@ +{ + "observedAt": "2026-11-11T17:36:16.810277+00:00", + "scope": "New e-means modules and explicit ecosystem entrypoints; no registry publication, Cloudflare deployment, or hosted Vectorize mutation.", + "rust": { + "targetedTestsPassed": 50, + "packages": [ + "ruvector-e-means (all features)", + "ruvector-pq-search", + "ruvector-rairs" + ], + "strictClippyAllTargets": "passed", + "crateArchiveVerification": "passed", + "packagedNativeRust181Check": "passed" + }, + "npm": { + "sharedTestsPassed": 44, + "sharedFailures": 0, + "sharedSkips": 0, + "strictTypes": "passed", + "optionalSdkAbsentInstalledConsumer": "passed", + "realDarwinInstalledConsumer": "passed", + "newRuVectorArchiveEntryPoints": [ + "@ruvector/core/clustering.mjs", + "ruvector/clustering.mjs", + "@ruvector/all/clustering.mjs", + "@ruvector/wasm/clustering" + ], + "newRuVectorArchiveEntryPointsStatus": "passed; unrelated legacy root/prepack release builds excluded", + "fannSourceFacadeTestsPassed": 8, + "fannRustAdapterTestsPassed": 3 + }, + "cloudflare": { + "localWorkerd": "passed with static Rust WASM and no nodejs_compat", + "localR2BindingRoundtrip": "passed", + "installedArchiveWorker": "passed", + "vectorize": "binding-contract fixtures only; no hosted mutation", + "schemaIteratorAuthBodyDeadlineAndWorkBoundRegressions": "passed" + }, + "metaharness": { + "package": "@metaharness/darwin", + "version": "0.13.0", + "algorithm": "actual evolveNumeric", + "holdout": "Separate nonoverlapping caller-supplied snapshot; used for selection, not independent generalization evidence", + "sourceApplied": false, + "temporaryArchiveCleanup": "passed" + }, + "dependencyAudit": { + "scope": "Isolated canonical integration-tool package lock", + "counts": { + "info": 0, + "low": 0, + "moderate": 0, + "high": 0, + "critical": 0, + "total": 0 + }, + "miniflare": "4.20260730.0", + "scopedOverrides": { + "sharp": "0.35.5", + "undici": "7.30.1" + }, + "workspaceInstallLimitation": "Existing Darwin-only workspace package prevents a whole-workspace Linux npm install; isolated lock qualification is used." + }, + "sha256": { + "npm/packages/e-means/package-lock.json": "d4b066d2503c58c92927fac0872180e3f1cc5d9f3e2e9665ddd5d2fdf717d25b", + "npm/package-lock.json": "4d80b3ccec4d52dbbfc5191062cc57397b8f6aa0ff24e7211c45cdb06c3fa1b0", + "Cargo.lock": "45f6253a219ae8446ff24b4adc27061e18ea43b9e627f8c55756f8983f81fcf4", + "npm/packages/e-means/wasm/ruvector_e_means_bg.wasm": "2c8f8a21e89f7e809a02d967bb77935284f35115855ed8024fae1a9453f27b5b" + } +} diff --git a/docs/research/e-means/performance-2026-11-11.json b/docs/research/e-means/performance-2026-11-11.json new file mode 100644 index 0000000000..921bcd5632 --- /dev/null +++ b/docs/research/e-means/performance-2026-11-11.json @@ -0,0 +1,406 @@ +{ + "date": "2026-11-11", + "scope": "Local synthetic CPU/WASM measurements against the pre-optimization implementation from this task; not paper GPU results or a production-data guarantee.", + "nativeEnvironment": { + "rustc": "rustc 1.99.1 (58cf8f9c3 2026-10-13)", + "system": "Linux-6.18.57-x86_64-with-glibc2.41", + "cpu": "AMD EPYC 9V74 80-Core Processor,virtualized", + "cpuQuota": "400000 100000", + "memoryLimitBytes": "17179869184", + "rustflags": "", + "profile": { + "optLevel": 3, + "lto": "fat", + "codegenUnits": 1 + }, + "repeats": 5, + "warmup": "one fit and predict per implementation,per scenario", + "ordering": "alternate baseline-first and current-first on each timing repetition", + "heapMeasurement": "allocation/reallocation events and peak additional live requested heap bytes during one fit; excludes preexisting dataset and models; notRSS", + "equivalence": "exact centroid f32 bits,assignments,dimension,mse f64 bits,peakstep f64 bits,batchsize,updates,revivedclusters,predictions", + "timingInstrumentation": "Same global tracking System allocator active in both implementations; timings include its atomic allocation/reallocation accounting.", + "pqFollowup": "pq21.jsonl uses same compiled binary,seed42,21interleavedrepetitions;pairedratios reported separately." + }, + "nativeResults": [ + { + "case": "embedding128", + "samples": 4096, + "clusters": 64, + "dimensions": 128, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 130.051781, + "currentFitMedianMs": 70.574425, + "fitSpeedup": 1.84276, + "baselinePredictMedianMs": 32.324955, + "currentPredictMedianMs": 15.459149, + "predictSpeedup": 2.09099, + "baselineFitSamplesMs": [131.467435, 127.331156, 130.242989, 130.051781, 122.74313], + "currentFitSamplesMs": [70.574425, 79.942167, 70.979476, 66.06521, 65.197374], + "baselinePredictSamplesMs": [37.515317, 33.257138, 32.324955, 32.27568, 31.45154], + "currentPredictSamplesMs": [27.529438, 15.707944, 15.284636, 14.883934, 15.459149], + "baselineAllocations": 65, + "currentAllocations": 18, + "baselinePeakBytes": 296448, + "currentPeakBytes": 297216, + "mse": 0.114103430514, + "revivedClusters": 35, + "digest": "d4c3e4ebdca756ec", + "bitwiseEqual": true + }, + { + "case": "embedding128", + "samples": 4096, + "clusters": 64, + "dimensions": 128, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 127.289993, + "currentFitMedianMs": 68.394125, + "fitSpeedup": 1.86112, + "baselinePredictMedianMs": 32.655452, + "currentPredictMedianMs": 16.103738, + "predictSpeedup": 2.02782, + "baselineFitSamplesMs": [123.94487, 127.289993, 140.52791, 129.614864, 123.52662], + "currentFitSamplesMs": [68.394125, 68.124209, 68.149968, 98.981614, 69.446419], + "baselinePredictSamplesMs": [32.222961, 33.500103, 31.648978, 32.655452, 33.376668], + "currentPredictSamplesMs": [15.650256, 16.10431, 16.103738, 16.809221, 15.972451], + "baselineAllocations": 65, + "currentAllocations": 16, + "baselinePeakBytes": 296448, + "currentPeakBytes": 231168, + "mse": 0.117060715656, + "revivedClusters": 35, + "digest": "8fe5489fdb461bac", + "bitwiseEqual": true + }, + { + "case": "embedding768", + "samples": 2048, + "clusters": 32, + "dimensions": 768, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 203.612263, + "currentFitMedianMs": 177.482473, + "fitSpeedup": 1.14722, + "baselinePredictMedianMs": 52.71644, + "currentPredictMedianMs": 43.645892, + "predictSpeedup": 1.20782, + "baselineFitSamplesMs": [204.457404, 198.054146, 219.330426, 203.612263, 183.144237], + "currentFitSamplesMs": [177.8861, 177.482473, 182.109762, 173.68051, 169.356138], + "baselinePredictSamplesMs": [53.80124, 47.364421, 49.976874, 52.71644, 53.603404], + "currentPredictSamplesMs": [43.804434, 43.151491, 43.949389, 43.645892, 43.350748], + "baselineAllocations": 62, + "currentAllocations": 17, + "baselinePeakBytes": 721664, + "currentPeakBytes": 722176, + "mse": 0.973645490345, + "revivedClusters": 65, + "digest": "37a4d73d3bf84abb", + "bitwiseEqual": true + }, + { + "case": "embedding768", + "samples": 2048, + "clusters": 32, + "dimensions": 768, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 192.918342, + "currentFitMedianMs": 184.687942, + "fitSpeedup": 1.04456, + "baselinePredictMedianMs": 51.914446, + "currentPredictMedianMs": 47.421477, + "predictSpeedup": 1.09475, + "baselineFitSamplesMs": [187.38364, 216.452527, 213.979302, 178.705455, 192.918342], + "currentFitSamplesMs": [177.536174, 184.687942, 184.713402, 191.928362, 180.864216], + "baselinePredictSamplesMs": [71.861448, 57.920893, 51.914446, 51.732527, 47.172022], + "currentPredictSamplesMs": [48.789807, 47.421477, 47.508818, 43.513473, 46.182311], + "baselineAllocations": 62, + "currentAllocations": 15, + "baselinePeakBytes": 721664, + "currentPeakBytes": 525312, + "mse": 0.97650976645, + "revivedClusters": 65, + "digest": "348b350dd42e4f2f", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 49.976593, + "currentFitMedianMs": 51.816974, + "fitSpeedup": 0.96448, + "baselinePredictMedianMs": 14.465709, + "currentPredictMedianMs": 12.975626, + "predictSpeedup": 1.11484, + "baselineFitSamplesMs": [47.05165, 51.369871, 48.388843, 55.925801, 49.976593], + "currentFitSamplesMs": [51.816974, 47.203168, 48.491608, 51.961502, 56.463701], + "baselinePredictSamplesMs": [15.078182, 11.836701, 12.312207, 14.465709, 16.043384], + "currentPredictSamplesMs": [12.975626, 13.535009, 19.086345, 12.357025, 12.182241], + "baselineAllocations": 72, + "currentAllocations": 9, + "baselinePeakBytes": 194560, + "currentPeakBytes": 194560, + "mse": 0.611907061092, + "revivedClusters": 0, + "digest": "d397aea176dfd1db", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 49.940565, + "currentFitMedianMs": 53.106126, + "fitSpeedup": 0.94039, + "baselinePredictMedianMs": 12.497583, + "currentPredictMedianMs": 12.372008, + "predictSpeedup": 1.01015, + "baselineFitSamplesMs": [51.534639, 49.823182, 55.087438, 49.940565, 47.923417], + "currentFitSamplesMs": [53.106126, 63.783741, 48.189242, 54.477886, 52.573087], + "baselinePredictSamplesMs": [12.996287, 11.327925, 11.742278, 12.497583, 12.582941], + "currentPredictSamplesMs": [12.17396, 12.372008, 12.316084, 12.405534, 13.082613], + "baselineAllocations": 72, + "currentAllocations": 7, + "baselinePeakBytes": 194560, + "currentPeakBytes": 176128, + "mse": 0.614058884679, + "revivedClusters": 0, + "digest": "598a7d0a59609a23", + "bitwiseEqual": true + }, + { + "case": "revival", + "samples": 2048, + "clusters": 64, + "dimensions": 32, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 13.349986, + "currentFitMedianMs": 2.525902, + "fitSpeedup": 5.28524, + "baselinePredictMedianMs": 3.117462, + "currentPredictMedianMs": 0.248884, + "predictSpeedup": 12.52576, + "baselineFitSamplesMs": [12.900549, 15.271623, 12.593227, 17.385549, 13.349986], + "currentFitSamplesMs": [2.532672, 2.410038, 2.525902, 2.512823, 3.187197], + "baselinePredictSamplesMs": [3.40796, 3.115189, 2.963251, 4.092791, 3.117462], + "currentPredictSamplesMs": [0.321274, 0.246832, 0.337598, 0.248884, 0.248334], + "baselineAllocations": 80, + "currentAllocations": 19, + "baselinePeakBytes": 91648, + "currentPeakBytes": 92672, + "mse": 0.0, + "revivedClusters": 167, + "digest": "e510f1a7dd7e5fe7", + "bitwiseEqual": true + }, + { + "case": "revival", + "samples": 2048, + "clusters": 64, + "dimensions": 32, + "seed": 42, + "epochs": 3, + "repeats": 5, + "finalization": "ema", + "baselineFitMedianMs": 12.905517, + "currentFitMedianMs": 3.145295, + "fitSpeedup": 4.10312, + "baselinePredictMedianMs": 3.489793, + "currentPredictMedianMs": 0.781276, + "predictSpeedup": 4.46679, + "baselineFitSamplesMs": [15.14003, 12.905517, 13.234311, 12.580436, 12.535741], + "currentFitSamplesMs": [3.350463, 3.380248, 3.126326, 3.145295, 2.962339], + "baselinePredictSamplesMs": [4.709018, 3.083932, 3.489793, 3.906741, 2.897862], + "currentPredictSamplesMs": [0.772182, 0.765983, 0.833865, 0.7971, 0.781276], + "baselineAllocations": 80, + "currentAllocations": 17, + "baselinePeakBytes": 91648, + "currentPeakBytes": 75776, + "mse": 1.8328e-08, + "revivedClusters": 167, + "digest": "60ad9268e8f72725", + "bitwiseEqual": true + } + ], + "nativePqFollowup": [ + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 21, + "finalization": "lastEpochMean", + "baselineFitMedianMs": 51.24788, + "currentFitMedianMs": 52.682849, + "fitSpeedup": 0.97276, + "baselinePredictMedianMs": 13.382461, + "currentPredictMedianMs": 13.632527, + "predictSpeedup": 0.98166, + "baselineFitSamplesMs": [49.448291, 49.816586, 49.312958, 48.863471, 51.08877, 48.398356, 52.749219, 51.153607, 51.147177, 52.587776, 58.093673, 51.758298, 52.255166, 51.439568, 51.496994, 52.095585, 49.410925, 51.24788, 53.677175, 51.450254, 50.59035], + "currentFitSamplesMs": [50.906396, 53.363303, 49.171624, 48.485522, 51.836616, 54.628707, 52.223908, 53.907743, 51.938108, 53.92603, 59.165586, 53.207258, 54.037302, 52.044438, 52.682849, 54.567615, 52.528166, 51.875483, 54.145655, 50.834828, 54.102114], + "baselinePredictSamplesMs": [13.083401, 12.904091, 13.440829, 12.854857, 13.701972, 14.183566, 13.736564, 13.026355, 13.022549, 13.786629, 12.42468, 13.382461, 13.45503, 13.917757, 13.202941, 14.74445, 12.927286, 13.384143, 12.49818, 12.775959, 16.755818], + "currentPredictSamplesMs": [14.81667, 13.117412, 13.440328, 12.302315, 13.213417, 14.582297, 13.978999, 15.233878, 13.649152, 13.632527, 13.236692, 14.473603, 12.616579, 13.798918, 13.571535, 14.082564, 13.86665, 13.012905, 11.896034, 13.598897, 14.586924], + "baselineAllocations": 72, + "currentAllocations": 9, + "baselinePeakBytes": 194560, + "currentPeakBytes": 194560, + "mse": 0.611907061092, + "revivedClusters": 0, + "digest": "d397aea176dfd1db", + "bitwiseEqual": true + }, + { + "case": "pq8", + "samples": 8192, + "clusters": 256, + "dimensions": 8, + "seed": 42, + "epochs": 3, + "repeats": 21, + "finalization": "ema", + "baselineFitMedianMs": 50.276679, + "currentFitMedianMs": 50.832466, + "fitSpeedup": 0.98907, + "baselinePredictMedianMs": 12.737901, + "currentPredictMedianMs": 13.050141, + "predictSpeedup": 0.97607, + "baselineFitSamplesMs": [47.921643, 48.137958, 48.476228, 50.120504, 49.945341, 48.566244, 49.538017, 48.266904, 46.495408, 64.897544, 73.224287, 56.418893, 50.48981, 52.052792, 50.767058, 51.888285, 50.276679, 54.769221, 59.892563, 49.93207, 94.624515], + "currentFitSamplesMs": [49.980713, 48.920456, 50.832466, 48.000654, 48.827698, 49.990659, 46.3299, 52.639305, 50.077289, 61.600693, 57.869147, 65.716427, 51.168893, 50.068806, 50.157379, 50.630702, 51.047169, 53.231833, 55.708239, 51.757348, 109.263924], + "baselinePredictSamplesMs": [12.159581, 12.584019, 12.620094, 12.799063, 12.296727, 11.405556, 12.620986, 13.689182, 12.929981, 16.264949, 14.558451, 12.833325, 13.327659, 12.405751, 12.988378, 13.218344, 12.535867, 12.737901, 11.942053, 30.120994, 12.542518], + "currentPredictSamplesMs": [12.864371, 13.261529, 13.898338, 13.794552, 11.400368, 13.422412, 12.868548, 13.469041, 13.050141, 16.407775, 16.744091, 12.667987, 12.244189, 12.784041, 12.993115, 13.011372, 11.954952, 13.802284, 13.442983, 17.258065, 11.744716], + "baselineAllocations": 72, + "currentAllocations": 7, + "baselinePeakBytes": 194560, + "currentPeakBytes": 176128, + "mse": 0.614058884679, + "revivedClusters": 0, + "digest": "598a7d0a59609a23", + "bitwiseEqual": true + } + ], + "npm": { + "runtime": { + "node": "v24.22.1", + "platform": "linux", + "arch": "x64", + "cpu": "AMD EPYC 9V74 80-Core Processor", + "logicalCpus": 5 + }, + "repeats": 7, + "warmupsPerVariant": 2, + "measurement": "median wall-clock milliseconds, fully materialized results; explicit GC outside timing", + "sameKernelTransportMeasurement": "full fit plus output materialization using one optimized WASM kernel; difference includes JSON serialization/parsing and array conversion, not a conversion-only timer", + "checksum": 42347816.01348107, + "cases": [ + { + "name": "large-assignment-result", + "samples": 1000000, + "dimensions": 1, + "clusters": 1, + "epochs": 1, + "batchSize": 4096, + "fit": { + "optimizedMs": 61.56721399999992, + "baselineMs": 84.090687, + "speedup": 1.3658355078402624 + }, + "predict": { + "optimizedMs": 10.453125, + "baselineMs": 15.906072000000222, + "speedup": 1.5216571121076445 + }, + "sameKernelTransport": { + "jsonMs": 75.97168599999986, + "typedMs": 58.40519399999994, + "speedup": 1.3007693459591958 + }, + "baselineParity": { + "labelDifferences": 0, + "centroidMaxAbsDifference": 0, + "mseAbsoluteDifference": 0 + } + }, + { + "name": "embedding-codebook", + "samples": 8192, + "dimensions": 64, + "clusters": 16, + "epochs": 3, + "batchSize": 256, + "fit": { + "optimizedMs": 15.001260999999886, + "baselineMs": 36.18889299999955, + "speedup": 2.4123900650751846 + }, + "predict": { + "optimizedMs": 5.059164999999666, + "baselineMs": 13.240130000000136, + "speedup": 2.6170583485616716 + }, + "sameKernelTransport": { + "jsonMs": 12.692776000000777, + "typedMs": 12.346003999999994, + "speedup": 1.0280877926170107 + }, + "baselineParity": { + "labelDifferences": 0, + "centroidMaxAbsDifference": 0, + "mseAbsoluteDifference": 0 + } + } + ] + }, + "sourceAndArtifactSha256": { + "baselineRustSource": { + "config.rs": "b9ad83acdf082778bc9841b18833122b0f353586b6a2cae5e2047f87d4dff6d6", + "lib.rs": "627e108c9d0b2644f4cc75f5f09805c1f92bde683f56b50a6f474074a2ccb517", + "trainer.rs": "f67fc903d4995678716dbc450cba820f4f4e4d73c50686c7267c2de01d22b967", + "wasm.rs": "270d30ca46b32602a7549d4c37b5d0740275800babdc24f62b8df358008f6568" + }, + "optimizedRustSource": { + "config.rs": "b9ad83acdf082778bc9841b18833122b0f353586b6a2cae5e2047f87d4dff6d6", + "distance.rs": "b2bb4252b7c10a99d55d07a33c46f196743d8fbe071694340db4be76c5f22e05", + "lib.rs": "084ce5655335019fc6a11b0226f0ccfed6b48a55cde674686453dc8231d59562", + "trainer.rs": "1bfa1299152cc9dd188975e6e068752aac83d5cdd3bd199672472ad68d5b1af2", + "wasm.rs": "7d4fbe5c800e083446ecf5f767bbe9eb6ed603b0330ab9be7086d009d930ad00" + }, + "baselineWasm": "dd68d9bf52a7422f14f56819f6b49c55118fc40438a0282ab64cde6e066c348b", + "optimizedWasm": "2c8f8a21e89f7e809a02d967bb77935284f35115855ed8024fae1a9453f27b5b" + }, + "verification": { + "native": "All model fields and predictions match baseline bit for bit in all eight measured cases.", + "npm": "Baseline centroid/label/MSE differences are zero in both measured cases; typed and JSON transports of the optimized kernel compare equal.", + "memory": "Native peaks are additional live requested heap bytes, excluding the dataset and preexisting models; not process RSS. LastEpochMean peaks can rise slightly due to retained scratch capacity; EMA skips last-epoch buffers.", + "pq8": "21-repeat follow-up fit median ratios baseline/current are 0.97276 (lastEpochMean) and 0.98907 (ema). No PQ speedup is claimed.", + "browser": "Chromium startup failed even for about:blank in the earlier baseline; browser qualification remains pending." + }, + "reproduceCurrentNative": "cargo run -p ruvector-e-means --release --example benchmark -- --case all --repeats 5 --seed 42 --finalization both", + "reproduceNpm": "npm run benchmark -- --repeats 7 (in npm/packages/e-means); --baseline compares a supplied prior artifact." +} diff --git a/npm/package-lock.json b/npm/package-lock.json index 87b5cd8571..f2d501d38b 100644 --- a/npm/package-lock.json +++ b/npm/package-lock.json @@ -3581,6 +3581,10 @@ "node": ">= 18" } }, + "node_modules/@ruvector/e-means": { + "resolved": "packages/e-means", + "link": true + }, "node_modules/@ruvector/economy-wasm": { "version": "0.1.29", "resolved": "https://registry.npmjs.org/@ruvector/economy-wasm/-/economy-wasm-0.1.29.tgz", @@ -19486,6 +19490,1532 @@ "@ruvector/diskann-win32-x64-msvc": "0.1.3" } }, + "packages/e-means": { + "name": "@ruvector/e-means", + "version": "0.1.0", + "license": "MIT", + "devDependencies": { + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0 || 0.13.1" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + } + }, + "packages/e-means/node_modules/@babel/helper-string-parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.13.tgz", + "integrity": "sha512-fWegr+WsEsiMVW4KUNdIIzzMTZSzNiqhy0//6+2MRi2d5NFNsL/AYwBQW8eBnRbTBVRnDVzjaJEUqKaCWjMMdQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@babel/helper-validator-identifier": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@babel/parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.13.tgz", + "integrity": "sha512-fJM50YYjlTiBhgdkGmC1tBpv+FMAyo4annf2X6Aks+0yRlaiVkYW/3f07xAfVVkYIoZ9fFZp+mEThUFnuybhkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.11" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "packages/e-means/node_modules/@babel/types": { + "version": "7.29.11", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.11.tgz", + "integrity": "sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.29.11", + "@babel/helper-validator-identifier": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-darwin-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260730.1.tgz", + "integrity": "sha512-+MBHmPaiTe2KajryW0T24rZvWFxb41hD3d8anNzQqHzft6vSEb18+sp0znSwxgij7ApPhSM1+vhkNg4f3YMguA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-darwin-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260730.1.tgz", + "integrity": "sha512-SBHKntPkKvNPgaCrTe99xC1CAl8ygJDzlYfK0LbuJ1muKadIw35WnhO0wu894fKBtllsVQdNzDLee+cm0ppLSQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-linux-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260730.1.tgz", + "integrity": "sha512-ouyPOSMbiKPeSwUJUvxtMcxGAXs2J4aPE4T5ABIYX5ClcQx5j5bbHTmnqOQEY8sAuLTPjH7dY+iB6UI5ISlwwA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-linux-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260730.1.tgz", + "integrity": "sha512-YQ+Mi78U3TPdgBPtwq+Sm6rJU+Ihl2y0pjYtuuKkdmUbYzL7oLR6Xqq9wljhasnuCFICssDJaqhMep5WizYoEQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cloudflare/workerd-windows-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260730.1.tgz", + "integrity": "sha512-27fAN+vUECW1oYVc1KOcHYpkL8COM2Uxtxql7TL595kxbjoqS5yckw7NLz7bTf2pALFCZWjqXDjZGJ/xbG4ZKQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + }, + "packages/e-means/node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "packages/e-means/node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "packages/e-means/node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@img/colour": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", + "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "packages/e-means/node_modules/@img/sharp-darwin-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz", + "integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-darwin-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz", + "integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-freebsd-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz", + "integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==", + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-darwin-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz", + "integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-darwin-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz", + "integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-arm": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz", + "integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz", + "integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-ppc64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz", + "integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-riscv64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz", + "integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-s390x": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz", + "integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linux-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz", + "integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linuxmusl-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz", + "integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-libvips-linuxmusl-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz", + "integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-arm": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz", + "integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz", + "integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-ppc64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz", + "integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-ppc64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-riscv64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz", + "integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-riscv64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-s390x": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz", + "integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-s390x": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linux-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz", + "integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linuxmusl-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz", + "integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-linuxmusl-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz", + "integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-x64": "1.3.4" + } + }, + "packages/e-means/node_modules/@img/sharp-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz", + "integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==", + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.11.3" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-webcontainers-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz", + "integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz", + "integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-ia32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz", + "integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@img/sharp-win32-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz", + "integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "packages/e-means/node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "packages/e-means/node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "packages/e-means/node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "packages/e-means/node_modules/@metaharness/darwin": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/@metaharness/darwin/-/darwin-0.13.0.tgz", + "integrity": "sha512-L3SrQii70erHVDmo1qx0875IRpVujk86zAO7sxtSVChWCgAjabEmmYRYt72D1VekfUCbSWCgZKIktqUxVAKCFA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.29.13" + }, + "bin": { + "metaharness-darwin": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "packages/e-means/node_modules/@poppinss/colors": { + "version": "4.1.6", + "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz", + "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==", + "dev": true, + "license": "MIT", + "dependencies": { + "kleur": "^4.1.5" + } + }, + "packages/e-means/node_modules/@poppinss/dumper": { + "version": "0.6.5", + "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz", + "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@sindresorhus/is": "^7.0.2", + "supports-color": "^10.0.0" + } + }, + "packages/e-means/node_modules/@poppinss/exception": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz", + "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==", + "dev": true, + "license": "MIT" + }, + "packages/e-means/node_modules/@sindresorhus/is": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz", + "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "packages/e-means/node_modules/@speed-highlight/core": { + "version": "1.2.24", + "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.24.tgz", + "integrity": "sha512-qeW2e1l78afw8VhRPfPQ1Gjj+KU5XFQ/OFV5ti6eTa9bruO7mJyZtA4vw0ofqmA3tKCkROE9xLk3VZoeRc98nw==", + "dev": true, + "license": "CC0-1.0" + }, + "packages/e-means/node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "packages/e-means/node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "packages/e-means/node_modules/error-stack-parser-es": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz", + "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "packages/e-means/node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "packages/e-means/node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "packages/e-means/node_modules/miniflare": { + "version": "4.20260730.0", + "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260730.0.tgz", + "integrity": "sha512-1Z9SB9r/o//80UA02Re3QhtcecSHAyAjf5EcKBfQVlQrCg7Miy79hl2PvtkwFLIaJ5rcrOPdDcRr577okwZPsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "0.8.1", + "sharp": "0.35.2", + "undici": "7.28.0", + "workerd": "1.20260730.1", + "ws": "8.21.0", + "youch": "4.1.0-beta.10" + }, + "bin": { + "miniflare": "bootstrap.js" + }, + "engines": { + "node": ">=22.0.0" + } + }, + "packages/e-means/node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "packages/e-means/node_modules/sharp": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz", + "integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@img/colour": "^1.1.0", + "detect-libc": "^2.1.2", + "semver": "^7.8.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-darwin-arm64": "0.35.5", + "@img/sharp-darwin-x64": "0.35.5", + "@img/sharp-freebsd-wasm32": "0.35.5", + "@img/sharp-libvips-darwin-arm64": "1.3.4", + "@img/sharp-libvips-darwin-x64": "1.3.4", + "@img/sharp-libvips-linux-arm": "1.3.4", + "@img/sharp-libvips-linux-arm64": "1.3.4", + "@img/sharp-libvips-linux-ppc64": "1.3.4", + "@img/sharp-libvips-linux-riscv64": "1.3.4", + "@img/sharp-libvips-linux-s390x": "1.3.4", + "@img/sharp-libvips-linux-x64": "1.3.4", + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4", + "@img/sharp-libvips-linuxmusl-x64": "1.3.4", + "@img/sharp-linux-arm": "0.35.5", + "@img/sharp-linux-arm64": "0.35.5", + "@img/sharp-linux-ppc64": "0.35.5", + "@img/sharp-linux-riscv64": "0.35.5", + "@img/sharp-linux-s390x": "0.35.5", + "@img/sharp-linux-x64": "0.35.5", + "@img/sharp-linuxmusl-arm64": "0.35.5", + "@img/sharp-linuxmusl-x64": "0.35.5", + "@img/sharp-webcontainers-wasm32": "0.35.5", + "@img/sharp-win32-arm64": "0.35.5", + "@img/sharp-win32-ia32": "0.35.5", + "@img/sharp-win32-x64": "0.35.5" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "packages/e-means/node_modules/supports-color": { + "version": "10.2.2", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz", + "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "packages/e-means/node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "packages/e-means/node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "packages/e-means/node_modules/undici": { + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.18.1" + } + }, + "packages/e-means/node_modules/workerd": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260730.1.tgz", + "integrity": "sha512-zmfNIjwYSWFY5chGBOjWtH3xAE7p97FTC6vR4Ep98290ho6AeAR/NVcBD274YCLEUYzqm8yxdtZlxMybU8a3jA==", + "dev": true, + "hasInstallScript": true, + "license": "Apache-2.0", + "bin": { + "workerd": "bin/workerd" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "@cloudflare/workerd-darwin-64": "1.20260730.1", + "@cloudflare/workerd-darwin-arm64": "1.20260730.1", + "@cloudflare/workerd-linux-64": "1.20260730.1", + "@cloudflare/workerd-linux-arm64": "1.20260730.1", + "@cloudflare/workerd-windows-64": "1.20260730.1" + } + }, + "packages/e-means/node_modules/ws": { + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "packages/e-means/node_modules/youch": { + "version": "4.1.0-beta.10", + "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz", + "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@poppinss/dumper": "^0.6.4", + "@speed-highlight/core": "^1.2.7", + "cookie": "^1.0.2", + "youch-core": "^0.3.3" + } + }, + "packages/e-means/node_modules/youch-core": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz", + "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/exception": "^1.2.2", + "error-stack-parser-es": "^1.0.5" + } + }, "packages/emergent-time": { "name": "@ruvector/emergent-time", "version": "0.1.3", diff --git a/npm/package.json b/npm/package.json index 2e1505e593..274ecf56c5 100644 --- a/npm/package.json +++ b/npm/package.json @@ -30,6 +30,10 @@ "npm": ">=9.0.0" }, "overrides": { + "miniflare": { + "sharp": "0.35.5", + "undici": "7.30.1" + }, "node-forge": ">=1.4.0", "flatted": ">=3.3.3", "picomatch": ">=4.0.3", diff --git a/npm/packages/e-means/.gitignore b/npm/packages/e-means/.gitignore new file mode 100644 index 0000000000..7f84121734 --- /dev/null +++ b/npm/packages/e-means/.gitignore @@ -0,0 +1,2 @@ +# Keep the isolated integration-test dependency graph reproducible. +!package-lock.json diff --git a/npm/packages/e-means/LICENSE b/npm/packages/e-means/LICENSE new file mode 100644 index 0000000000..2dd524ac38 --- /dev/null +++ b/npm/packages/e-means/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 rUv + +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. diff --git a/npm/packages/e-means/README.md b/npm/packages/e-means/README.md new file mode 100644 index 0000000000..121ff27951 --- /dev/null +++ b/npm/packages/e-means/README.md @@ -0,0 +1,101 @@ +# @ruvector/e-means + +![e-means training loop: rows are assigned in mini-batches, EMA counts and sums move the centroids with a cosine-decaying step, a dead centroid is revived by splitting a busy donor, and the last epoch mean gives the codebook](https://raw.githubusercontent.com/ruvnet/ruvector/main/npm/packages/e-means/assets/e-means-flow.svg) + +Portable WebAssembly bindings for the shared `ruvector-e-means` Rust crate, based on [e-means (arXiv:2611.09501v1)](https://arxiv.org/abs/2611.09501v1). Uses EMA counts and sums, cosine annealing, dead-cluster splitting and last-epoch mean finalization. + +```js +import { init, fit, predict } from '@ruvector/e-means'; + +await init(); +const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); +const model = fit(data, 2, { clusters: 2, epochs: 3, seed: 42 }); +const labels = predict(data, 2, model.centroids); +``` + +Pass flat row-major `Float32Array` data and finite values. `fit` and `predict` are synchronous after `init`; input arrays are unchanged. Cluster labels break distance ties at the lowest centroid index. `mse` is mean squared Euclidean distance per vector. Output assignments are recomputed against the final codebook. + +The runtime transfers result vectors directly as typed arrays. Returned arrays belong to the caller and remain valid across later fits and WebAssembly memory growth. The temporary Rust result handle is released before `fit` returns; the small options object alone uses JSON transport. + +`batchSize` and `peakStep` can override the paper's automatic settings. `finalization: 'ema'` returns the training EMA instead of the default `'lastEpochMean'`. The empirical scaling laws target large embedding datasets; evaluate overrides on tiny or low-dimensional data. CPU/WASM throughput is not the paper's measured GPU throughput. GPU kernels, approximate assignment and the optional slow-EMA finalizer are outside this initial implementation. + +Node reads the bundled WASM from disk. In browsers, serve the `.wasm` artifact beside its generated JavaScript module, or call `init(bytes)` / `init(compiledModule)` to supply it explicitly. No native compilation, network request, or model download occurs during installation or Node initialization. Browser initialization fetches the bundled `.wasm` URL by default. + +From a source checkout: install the `wasm32-unknown-unknown` Rust target and `wasm-bindgen-cli` version `0.2.125`, then run `npm run build`, `npm test` and `npm run test:consumer` in this package. `npm pack` verifies the built runtime before creating an archive. The archive contains the runtime and needs neither Rust nor the source repository. + +`npm run typecheck` validates the declarations. `npm run test:browser` runs the same numerical oracle in headless Chromium against the default browser loader; set `E_MEANS_CHROMIUM` when Chromium is not on `PATH`. + +`npm run benchmark -- --baseline /path/to/previous/package --repeats 7` measures median fit and prediction time on one million scalar rows and an embedding codebook workload. It also compares JSON and typed output on the same current Rust kernel. The baseline argument is optional; retain the previous package's module and WASM together. Run benchmarks without other compute workloads; results describe the current machine and these fixtures. + +RuVector exposes the same API through `ruvector/clustering.mjs` once a `ruvector` release that depends on this package is published. A ruv-FANN facade is proposed separately and is not released. + +The package also ships explicit integration subpaths: + +| Import | Use | +|---|---| +| `@ruvector/e-means/quantization` | Train PQ subspace codebooks, encode byte codes, decode vectors, and validate JSON codebooks | +| `@ruvector/e-means/ivf` | Train coarse clusters and construct stable posting lists | +| `@ruvector/e-means/metaharness` | Measure held-out clustering quality and run bounded numeric evolution with Darwin 0.13.0 or 0.13.1 | +| `@ruvector/e-means/cloudflare` | Create an authenticated Worker and explicitly persist/export centroid codebooks through R2/Vectorize bindings | +| `@ruvector/e-means/runtime` | Initialize from explicit bytes or a precompiled WASM module without importing Node loaders | +| `@ruvector/e-means/cloudflare/build` | Build the shipped Worker example locally; requires development tooling, and never deploys | +| `@ruvector/e-means/wasm` | Static WASM module import for Wrangler | + +```js +import { init } from '@ruvector/e-means'; +import { trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer } + from '@ruvector/e-means/quantization'; +import { partition, postingList } from '@ruvector/e-means/ivf'; + +await init(); +const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); +const options = { clusters: 2, epochs: 3, seed: 42 }; +const book = trainProductQuantizer(data, 2, 2, options); +const codes = encodeProductQuantizer(book, data); +const reconstructed = decodeProductQuantizer(book, codes); +const inverted = partition(data, 2, options); +const firstPosting = postingList(inverted, 0); +``` + +MetaHarness tuning requires the optional peer `@metaharness/darwin` at 0.13.0 or 0.13.1. +`createClusteringEvaluator` uses snapshotted, nonoverlapping training/holdout +arrays and explicit evaluation/work/deadline budgets. `tuneClustering` calls the +real numeric SDK, verifies observed records, and returns a recommendation with +`sourceApplied: false`. Selection uses the holdout; another test split is needed +for generalization claims. See the shipped `examples/metaharness.mjs`. + +For a Worker, statically import the module and supply the deployment's secret: + +```js +import wasmModule from '@ruvector/e-means/wasm'; +import { createClusteringWorker } from '@ruvector/e-means/cloudflare'; + +export default { + fetch(request, env) { + return createClusteringWorker({ + wasmModule, bearerToken: env.E_MEANS_BEARER_TOKEN, + }).fetch(request); + }, +}; +``` + +`/fit` and `/predict` require authentication by default and enforce body, shape, +stream-read and work bounds. R2 helpers persist only centroid codebooks. +Vectorize exports use explicit caller-owned bindings; acknowledgements are +asynchronous and failures can leave earlier batches applied. Use versioned +prefixes/namespaces because upserts do not delete stale IDs. PQ records have a +different layout and are rejected by these single-codebook helpers. + +The shipped `examples/cloudflare` contains a static-WASM builder and Wrangler +configuration. `npm run build:cloudflare` only writes local artifacts. `buildWorker` needs `esbuild` +installed by the caller and reports a clear error without it. Qualify +with `npm ci --ignore-scripts --workspaces=false`, `npm test`, +`npm run typecheck`, `npm run test:consumer`, and `npm run test:ecosystem`. +Local workerd/R2 tests use development dependencies; Vectorize is covered by +binding fixtures. No hosted deployment is implied. + +The `@ruvector/core`, `@ruvector/all`, `@ruvector/wasm` and `ruvector` sources +add clustering subpaths over these integrations; they reach users only with +those packages' next releases. See +[ADR-360](https://github.com/ruvnet/ruvector/blob/main/docs/adr/ADR-360-e-means-ecosystem-integrations.md) +for the exact paths, release order, and validation scope. diff --git a/npm/packages/e-means/assets/e-means-flow.svg b/npm/packages/e-means/assets/e-means-flow.svg new file mode 100644 index 0000000000..670e13813f --- /dev/null +++ b/npm/packages/e-means/assets/e-means-flow.svg @@ -0,0 +1,62 @@ + + e-means training loop + Three groups of points. Centroids start on random rows and move toward each group as mini-batches update exponential moving averages of counts and sums with a cosine-decaying step. A dead centroid is revived by splitting a busy donor, and the last epoch's mean gives the final codebook. + + + + + + + + + + + + + + + + + + + + + + + + e-means: mini-batch k-means with EMA statistics + + + + 1. assign batch rows, EMA-update counts and sums + + + + 2. step size follows a cosine schedule + + + + 3. every 5 updates, split a busy donor into a dead slot + + + + 4. finalize with the last epoch's mean (or the EMA) + Same Rust kernel natively and in WebAssembly; seeded and deterministic. + diff --git a/npm/packages/e-means/e-means.d.ts b/npm/packages/e-means/e-means.d.ts new file mode 100644 index 0000000000..6230ed769a --- /dev/null +++ b/npm/packages/e-means/e-means.d.ts @@ -0,0 +1,33 @@ +export interface EMeansOptions { + clusters: number; + /** Positive integer, default 3. */ + epochs?: number; + /** Positive integer; defaults to the paper's batch scaling law, capped at the row count. */ + batchSize?: number; + /** Peak EMA step in (0, 1]; defaults to the paper's step scaling law. */ + peakStep?: number; + /** Non-negative safe integer; default 42. */ + seed?: number; + finalization?: 'lastEpochMean' | 'ema'; +} + +export interface EMeansModel { + /** Flat row-major clusters × dimensions codebook. */ + centroids: Float32Array; + /** Nearest final centroid for every input row. */ + assignments: Uint32Array; + dimensions: number; + /** Mean squared Euclidean distance per vector, not per coordinate. */ + mse: number; + batchSize: number; + peakStep: number; + updates: number; + revivedClusters: number; +} + +/** Load the bundled WebAssembly runtime. In browsers the default .wasm URL must be served. */ +export function init(input?: BufferSource | WebAssembly.Module): Promise; +/** Requires init(). Inputs are not modified. */ +export function fit(data: Float32Array, dimensions: number, options: EMeansOptions): EMeansModel; +/** Requires init(). An empty input returns an empty assignment array. */ +export function predict(data: Float32Array, dimensions: number, centroids: Float32Array): Uint32Array; diff --git a/npm/packages/e-means/e-means.mjs b/npm/packages/e-means/e-means.mjs new file mode 100644 index 0000000000..9d74da55ff --- /dev/null +++ b/npm/packages/e-means/e-means.mjs @@ -0,0 +1,29 @@ +import { init as initRuntime } from './runtime.mjs'; +export { fit, predict } from './runtime.mjs'; + +let initialization; + +/** Load the bundled Rust runtime once; pass bytes or a compiled module to override it. */ +export async function init(input) { + if (!initialization) { + initialization = (async () => { + let source = input; + if (source === undefined) { + const url = new URL('./wasm/ruvector_e_means_bg.wasm', import.meta.url); + if (url.protocol === 'file:' && typeof process !== 'undefined' && process.versions?.node) { + const { readFile } = await import('node:fs/promises'); + source = await readFile(url); + } else { + source = url; + } + } + await initRuntime(source); + })().catch((error) => { + initialization = undefined; + const message = typeof error?.message === 'string' ? error.message : String(error); + if (message.startsWith('Could not initialize @ruvector/e-means:')) throw error; + throw new Error(`Could not initialize @ruvector/e-means: ${message}`, { cause: error }); + }); + } + await initialization; +} diff --git a/npm/packages/e-means/examples/cloudflare/build.d.ts b/npm/packages/e-means/examples/cloudflare/build.d.ts new file mode 100644 index 0000000000..eac7465c9d --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/build.d.ts @@ -0,0 +1,5 @@ +/** Node-only build tooling; requires caller-installed esbuild. Never deploys. */ +export function buildWorker(outDirectory: string, entryPoint?: string): Promise<{ + script: string; + wasm: string; +}>; diff --git a/npm/packages/e-means/examples/cloudflare/build.mjs b/npm/packages/e-means/examples/cloudflare/build.mjs new file mode 100644 index 0000000000..e253422332 --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/build.mjs @@ -0,0 +1,25 @@ +import { mkdir, copyFile } from 'node:fs/promises'; +import { join, resolve } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; + +/** Build a static-WASM Worker locally; this function never deploys anything. */ +export async function buildWorker(outDirectory, entryPoint = fileURLToPath(new URL('./worker.mjs', import.meta.url))) { + if (typeof outDirectory !== 'string' || outDirectory.length === 0) throw new TypeError('outDirectory is required'); + let build; + try { ({ build } = await import('esbuild')); } + catch (cause) { throw new Error('buildWorker requires esbuild; install it as a development dependency', { cause }); } + const output = resolve(outDirectory), wasm = join(output, 'e-means.wasm'); + await mkdir(output, { recursive: true }); + await copyFile(fileURLToPath(import.meta.resolve('@ruvector/e-means/wasm')), wasm); + const script = join(output, 'worker.mjs'); + await build({ entryPoints: [entryPoint], outfile: script, bundle: true, format: 'esm', platform: 'browser', + target: 'es2022', legalComments: 'none', plugins: [{ name: 'e-means-static-wasm', setup(builder) { + builder.onResolve({ filter: /^@ruvector\/e-means\/wasm$/ }, () => ({ path: './e-means.wasm', external: true })); + } }] }); + return { script, wasm }; +} + +if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) { + const artifact = await buildWorker(process.argv[2] ?? fileURLToPath(new URL('./dist/', import.meta.url))); + console.log(JSON.stringify(artifact)); +} diff --git a/npm/packages/e-means/examples/cloudflare/worker.mjs b/npm/packages/e-means/examples/cloudflare/worker.mjs new file mode 100644 index 0000000000..be36fb9ebd --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/worker.mjs @@ -0,0 +1,9 @@ +import wasmModule from '@ruvector/e-means/wasm'; +import { createClusteringWorker } from '@ruvector/e-means/cloudflare'; + +export default { + fetch(request, env) { + // The secret is supplied by the deployment's binding configuration. + return createClusteringWorker({ wasmModule, bearerToken: env.E_MEANS_BEARER_TOKEN }).fetch(request); + }, +}; diff --git a/npm/packages/e-means/examples/cloudflare/wrangler.jsonc b/npm/packages/e-means/examples/cloudflare/wrangler.jsonc new file mode 100644 index 0000000000..19ed83de99 --- /dev/null +++ b/npm/packages/e-means/examples/cloudflare/wrangler.jsonc @@ -0,0 +1,9 @@ +{ + "name": "ruvector-e-means", + "main": "dist/worker.mjs", + "compatibility_date": "2026-07-30", + "no_bundle": true, + "find_additional_modules": true, + "rules": [{ "type": "CompiledWasm", "globs": ["**/*.wasm"], "fallthrough": true }], + "observability": { "enabled": true } +} diff --git a/npm/packages/e-means/examples/metaharness.mjs b/npm/packages/e-means/examples/metaharness.mjs new file mode 100644 index 0000000000..a2114ea7e5 --- /dev/null +++ b/npm/packages/e-means/examples/metaharness.mjs @@ -0,0 +1,16 @@ +import { tuneClustering } from '@ruvector/e-means/metaharness'; + +const result = await tuneClustering({ + training: new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]), + holdout: new Float32Array([0, 1, 10, 11]), + dimensions: 2, + baseline: { clusters: 2, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { peakStep: { min: 0.1, max: 1, type: 'float', scale: 'log' } }, + budget: { maxEvaluations: 3, maxDistanceCoordinates: 100_000, timeoutMs: 30_000 }, + generations: 1, + childrenPerGeneration: 2, + mutationSeed: 7, +}); +console.log(JSON.stringify({ baselineHoldoutMse: result.baseline.score.raw.holdoutMse, + winnerHoldoutMse: result.winner.score.raw.holdoutMse, recommendation: result.recommendation, + sourceApplied: result.sourceApplied }, null, 2)); diff --git a/npm/packages/e-means/integrations/cloudflare.d.ts b/npm/packages/e-means/integrations/cloudflare.d.ts new file mode 100644 index 0000000000..499c546dbb --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare.d.ts @@ -0,0 +1,58 @@ +export interface WorkerOptions { + /** Statically import @ruvector/e-means/wasm in a Worker. */ + wasmModule: WebAssembly.Module; + bearerToken?: string; + /** Explicit local/trusted opt-in; false by default. */ + allowUnauthenticated?: boolean; + maxRequestBytes?: number; + maxWork?: number; + bodyTimeoutMs?: number; +} +/** One row-major set of full-dimensional centroids, not subspace-major PQ books. */ +export interface CodebookInput { + dimensions: number; + centroids: Float32Array; + schema?: 'ruvector.e-means-codebook/1'; +} +export interface StoredCodebook extends CodebookInput { + schema: 'ruvector.e-means-codebook/1'; + clusters: number; +} +export interface R2Binding { + put(key: string, body: string, options?: { httpMetadata?: { contentType?: string } }): Promise; + get(key: string): Promise<{ size: number; body: ReadableStream } | null>; +} +export interface VectorizeVector { + id: string; + values: number[]; + metadata: { cluster: number }; + namespace?: string; +} +export interface VectorizeBinding { + upsert(vectors: VectorizeVector[]): Promise<{ mutationId: string }>; +} +export interface ExportOptions { + /** Use a versioned prefix for a new codebook; old centroid IDs are not deleted. */ + prefix: string; + namespace?: string; + batchSize?: number; +} +export interface ExportReceipt { submitted: number; mutationIds: string[] } +/** Does not persist request data. Operations fail closed unless authentication is configured. */ +export function createClusteringWorker(options: WorkerOptions): { fetch(request: Request): Promise }; +export function persistCodebook(bucket: Pick, key: string, model: CodebookInput): Promise<{ + key: string; dimensions: number; clusters: number; bytes: number; +}>; +export function loadCodebook(bucket: Pick, key: string): Promise; +/** Batches upserts; acknowledgement does not establish query visibility or atomicity. */ +export function exportCentroids(index: VectorizeBinding, model: CodebookInput, options: ExportOptions): Promise; +export class CentroidExportError extends Error { + constructor(submitted: number, mutationIds: readonly string[], cause: unknown); + /** Rows in previously acknowledged batches; the failing batch may also have applied. */ + submitted: number; + mutationIds: string[]; +} +export const WORKER_LIMITS: Readonly<{ + maxRequestBytes: number; maxWork: number; maxRows: number; maxDimensions: number; + maxClusters: number; maxEpochs: number; maxElements: number; maxCodebookBytes: number; +}>; diff --git a/npm/packages/e-means/integrations/cloudflare.mjs b/npm/packages/e-means/integrations/cloudflare.mjs new file mode 100644 index 0000000000..f8ed7db1e0 --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare.mjs @@ -0,0 +1,72 @@ +import { init, fit, predict } from '../runtime.mjs'; +import { workEstimate } from './clustering-validation.mjs'; +import { HTTPError, integer, LIMITS, plain, floats, fitOptions } from './cloudflare/validation.mjs'; +import { readJSON, response, tokenMatches } from './cloudflare/http.mjs'; + +export { persistCodebook, loadCodebook, exportCentroids, CentroidExportError } from './cloudflare/storage.mjs'; +export { LIMITS as WORKER_LIMITS } from './cloudflare/validation.mjs'; + +/** Private, stateless Worker handler. Pass a statically imported WASM module. */ +export function createClusteringWorker(options) { + const config = plain(options, ['wasmModule', 'bearerToken', 'allowUnauthenticated', + 'maxRequestBytes', 'maxWork', 'bodyTimeoutMs'], ['wasmModule'], 'Worker options'); + if (!(config.wasmModule instanceof WebAssembly.Module)) throw new TypeError('wasmModule must be a precompiled WebAssembly.Module'); + if (config.bearerToken !== undefined && (typeof config.bearerToken !== 'string' || + config.bearerToken.length < 24 || config.bearerToken.length > 1024 || !/^[\x21-\x7e]+$/.test(config.bearerToken))) { + throw new TypeError('bearerToken must be 24..1024 printable non-space ASCII characters'); + } + if (config.allowUnauthenticated !== undefined && typeof config.allowUnauthenticated !== 'boolean') { + throw new TypeError('allowUnauthenticated must be boolean'); + } + const maxBytes = integer(config.maxRequestBytes ?? 512 * 1024, 1, LIMITS.maxRequestBytes, 'maxRequestBytes'); + const maxWork = integer(config.maxWork ?? 10_000_000, 1, LIMITS.maxWork, 'maxWork'); + const timeoutMs = integer(config.bodyTimeoutMs ?? 5000, 1, 30_000, 'bodyTimeoutMs'); + const token = config.bearerToken; + return Object.freeze({ async fetch(request) { + try { + if (!(request instanceof Request)) throw new TypeError('request must be a Request'); + const url = new URL(request.url); + if (url.search) throw new HTTPError(400, 'invalid_query', 'Query parameters are unsupported'); + if (url.pathname === '/health') { + if (request.method !== 'GET') return response({ error: 'method_not_allowed' }, 405, { Allow: 'GET' }); + return response({ schema: 'ruvector.e-means-worker/1', stateless: true, + authenticatedOperations: Boolean(token), maxRequestBytes: maxBytes, maxWork }); + } + if (!['/fit', '/predict'].includes(url.pathname)) return response({ error: 'not_found' }, 404); + if (request.method !== 'POST') return response({ error: 'method_not_allowed' }, 405, { Allow: 'POST' }); + if (!token && config.allowUnauthenticated !== true) { + throw new HTTPError(503, 'authentication_unconfigured', 'Configure E_MEANS_BEARER_TOKEN before using operations'); + } + if (token && !tokenMatches(request.headers.get('authorization'), `Bearer ${token}`)) { + throw new HTTPError(401, 'unauthorized', 'A valid bearer token is required'); + } + const isFit = url.pathname === '/fit'; + const fields = isFit ? ['data', 'dimensions', 'options'] : ['data', 'dimensions', 'centroids']; + const body = plain(await readJSON(request, maxBytes, timeoutMs), fields, fields, 'request'); + const dimensions = integer(body.dimensions, 1, LIMITS.maxDimensions, 'dimensions'); + const data = floats(body.data, dimensions, 'data', !isFit); + if (isFit) { + const options = fitOptions(body.options, data.length / dimensions); + // Shared coordinate-scale admission estimate, including centroid + // statistics and O(k²) donor revival; not a hard CPU-clock limit. + const epochs = options.epochs ?? 3; + const work = workEstimate({ ...options, epochs }, data.length / dimensions, 0, dimensions); + if (work > maxWork) throw new HTTPError(413, 'work_budget_exceeded', 'Fit exceeds configured work budget'); + await init(config.wasmModule); + const model = fit(data, dimensions, options); + return response({ ...model, centroids: Array.from(model.centroids), assignments: Array.from(model.assignments) }); + } + const centroids = floats(body.centroids, dimensions, 'centroids'); + const clusters = integer(centroids.length / dimensions, 1, LIMITS.maxClusters, 'clusters'); + if (data.length + centroids.length > LIMITS.maxElements || data.length * clusters > maxWork) { + throw new HTTPError(413, 'work_budget_exceeded', 'Prediction exceeds configured work or element budget'); + } + await init(config.wasmModule); + return response({ assignments: Array.from(predict(data, dimensions, centroids)) }); + } catch (error) { + if (error instanceof HTTPError) return response({ error: error.code, message: error.message }, error.status); + if (error instanceof TypeError || error instanceof RangeError) return response({ error: 'invalid_input', message: error.message }, 422); + return response({ error: 'execution_failed', message: 'Clustering execution failed' }, 500); + } + } }); +} diff --git a/npm/packages/e-means/integrations/cloudflare/http.mjs b/npm/packages/e-means/integrations/cloudflare/http.mjs new file mode 100644 index 0000000000..3b7f58550e --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/http.mjs @@ -0,0 +1,59 @@ +import { HTTPError } from './validation.mjs'; + +export function response(value, status = 200, headers = {}) { + return new Response(JSON.stringify(value), { status, headers: { + 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store', + 'X-Content-Type-Options': 'nosniff', ...headers, + } }); +} + +export function tokenMatches(value, token) { + if (typeof value !== 'string' || value.length !== token.length) return false; + let different = 0; + for (let index = 0; index < token.length; index++) different |= value.charCodeAt(index) ^ token.charCodeAt(index); + return different === 0; +} + +export async function readBytes(stream, limit, timeoutMs) { + if (!stream || typeof stream.getReader !== 'function') throw new HTTPError(400, 'invalid_body', 'A body is required'); + const reader = stream.getReader(); + let timer; + const cancel = () => { void reader.cancel('body rejected').catch(() => {}); }; + const read = async () => { + let bytes = new Uint8Array(Math.min(limit, 8192)), size = 0; + for (;;) { + const { value, done } = await reader.read(); + if (done) return bytes.subarray(0, size); + if (!(value instanceof Uint8Array)) throw new HTTPError(400, 'invalid_body', 'Body must contain bytes'); + if (value.byteLength > limit - size) { + cancel(); + throw new HTTPError(413, 'body_too_large', 'Body exceeds byte limit'); + } + const next = size + value.byteLength; + if (next > bytes.length) { + const grown = new Uint8Array(Math.min(limit, Math.max(next, bytes.length * 2))); + grown.set(bytes); bytes = grown; + } + bytes.set(value, size); size = next; + } + }; + const deadline = new Promise((_, reject) => { + timer = setTimeout(() => { cancel(); reject(new HTTPError(408, 'body_timeout', 'Body read timed out')); }, timeoutMs); + }); + try { return await Promise.race([read(), deadline]); } + finally { clearTimeout(timer); reader.releaseLock(); } +} + +export async function readJSON(request, limit, timeoutMs) { + const type = request.headers.get('content-type'); + if (!type || !/^application\/json(?:\s*;\s*charset\s*=\s*(?:utf-8|"utf-8"))?\s*$/i.test(type)) { + throw new HTTPError(415, 'unsupported_media_type', 'Content-Type must be UTF-8 application/json'); + } + const length = request.headers.get('content-length'); + if (length !== null && (!/^(0|[1-9][0-9]*)$/.test(length) || Number(length) > limit)) { + throw new HTTPError(413, 'body_too_large', 'Body exceeds byte limit'); + } + const bytes = await readBytes(request.body, limit, timeoutMs); + try { return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } + catch { throw new HTTPError(400, 'invalid_json', 'Body must be valid UTF-8 JSON'); } +} diff --git a/npm/packages/e-means/integrations/cloudflare/storage.mjs b/npm/packages/e-means/integrations/cloudflare/storage.mjs new file mode 100644 index 0000000000..71ecee2799 --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/storage.mjs @@ -0,0 +1,78 @@ +import { checkedCodebook, integer, LIMITS, plain, safeText } from './validation.mjs'; +import { readBytes } from './http.mjs'; + +/** Persist centroids only, never input vectors or assignments. Binding is caller-owned. */ +export async function persistCodebook(bucket, key, model) { + if (typeof bucket?.put !== 'function') throw new TypeError('an R2 put binding is required'); + safeText(key, 'key', 1024); + const checked = checkedCodebook(model); + const body = JSON.stringify({ ...checked, centroids: Array.from(checked.centroids) }); + const bytes = new TextEncoder().encode(body).byteLength; + if (bytes > LIMITS.maxCodebookBytes) throw new RangeError('codebook exceeds storage byte limit'); + const result = await bucket.put(key, body, { httpMetadata: { contentType: 'application/json' } }); + if (!result || typeof result !== 'object') throw new Error('R2 did not acknowledge the codebook write'); + return { key, dimensions: checked.dimensions, clusters: checked.clusters, bytes }; +} + +export async function loadCodebook(bucket, key) { + if (typeof bucket?.get !== 'function') throw new TypeError('an R2 get binding is required'); + safeText(key, 'key', 1024); + const stored = await bucket.get(key); + if (stored === null) return null; + if (!stored || !Number.isSafeInteger(stored.size) || stored.size < 0 || stored.size > LIMITS.maxCodebookBytes) { + throw new RangeError('stored codebook exceeds storage byte limit'); + } + const bytes = await readBytes(stored.body, LIMITS.maxCodebookBytes, 5000); + let parsed; + try { parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes)); } + catch { throw new TypeError('stored codebook must be valid UTF-8 JSON'); } + const record = plain(parsed, ['schema', 'dimensions', 'clusters', 'centroids'], + ['schema', 'dimensions', 'clusters', 'centroids'], 'stored codebook'); + if (record.schema !== 'ruvector.e-means-codebook/1' || !Array.isArray(record.centroids) || + record.centroids.length > LIMITS.maxElements) throw new TypeError('unsupported stored codebook'); + for (const value of record.centroids) { + if (!Number.isFinite(value) || Math.abs(value) > 3.4028234663852886e38) throw new RangeError('stored centroids must be finite float32 values'); + } + const checked = checkedCodebook({ dimensions: record.dimensions, centroids: new Float32Array(record.centroids) }); + if (record.clusters !== checked.clusters) throw new TypeError('stored cluster count does not match centroid shape'); + return checked; +} + +export class CentroidExportError extends Error { + constructor(submitted, mutationIds, cause) { + super('Vectorize export failed after a partially submitted batch sequence', { cause }); + this.name = 'CentroidExportError'; this.submitted = submitted; this.mutationIds = [...mutationIds]; + } +} + +/** Submit centroids to Vectorize. Acknowledged mutations may not be query-visible yet. */ +export async function exportCentroids(index, model, options) { + if (typeof index?.upsert !== 'function') throw new TypeError('a Vectorize upsert binding is required'); + const config = plain(options, ['prefix', 'namespace', 'batchSize'], ['prefix'], 'Vectorize options'); + safeText(config.prefix, 'prefix', 64); + if (config.namespace !== undefined) safeText(config.namespace, 'namespace', 64); + const batchSize = integer(config.batchSize ?? 1000, 1, 1000, 'batchSize'); + const checked = checkedCodebook(model); + integer(checked.dimensions, 1, 1536, 'Vectorize dimensions'); + // Every ID uses the same prefix and a decimal ordinal; the last is longest. + safeText(`${config.prefix}:${checked.clusters - 1}`, 'vector id', 64); + let submitted = 0; + const mutationIds = []; + while (submitted < checked.clusters) { + const end = Math.min(checked.clusters, submitted + batchSize), vectors = []; + for (let ordinal = submitted; ordinal < end; ordinal++) { + const row = checked.centroids.subarray(ordinal * checked.dimensions, (ordinal + 1) * checked.dimensions); + vectors.push({ id: `${config.prefix}:${ordinal}`, values: Array.from(row), metadata: { cluster: ordinal }, + ...(config.namespace === undefined ? {} : { namespace: config.namespace }) }); + } + let result; + try { + result = await index.upsert(vectors); + safeText(result?.mutationId, 'Vectorize mutation id', 256); + } + catch (cause) { throw new CentroidExportError(submitted, mutationIds, cause); } + submitted = end; + mutationIds.push(result.mutationId); + } + return { submitted, mutationIds }; +} diff --git a/npm/packages/e-means/integrations/cloudflare/validation.mjs b/npm/packages/e-means/integrations/cloudflare/validation.mjs new file mode 100644 index 0000000000..bf054d7b7e --- /dev/null +++ b/npm/packages/e-means/integrations/cloudflare/validation.mjs @@ -0,0 +1,107 @@ +export const LIMITS = Object.freeze({ + maxRequestBytes: 1024 * 1024, + maxWork: 100_000_000, + maxRows: 16_384, + maxDimensions: 1536, + maxClusters: 256, + maxEpochs: 32, + maxElements: 262_144, + maxCodebookBytes: 8 * 1024 * 1024, +}); + +export class HTTPError extends Error { + constructor(status, code, message) { super(message); this.status = status; this.code = code; } +} + +export function plain(value, allowed, required, name) { + if (!value || typeof value !== 'object' || Array.isArray(value) || + ![Object.prototype, null].includes(Object.getPrototypeOf(value))) { + throw new TypeError(`${name} must be a plain object`); + } + const output = Object.create(null); + for (const key of Reflect.ownKeys(value)) { + const descriptor = Object.getOwnPropertyDescriptor(value, key); + if (typeof key !== 'string' || !allowed.includes(key) || !Object.hasOwn(descriptor, 'value')) { + throw new TypeError(`unknown or accessor ${name} field`); + } + output[key] = descriptor.value; + } + if (required.some(key => !Object.hasOwn(output, key))) throw new TypeError(`missing ${name} field`); + return output; +} + +export function integer(value, min, max, name) { + if (!Number.isSafeInteger(value) || value < min || value > max) { + throw new RangeError(`${name} must be an integer in ${min}..${max}`); + } + return value; +} + +export function safeText(value, name, maxBytes) { + if (typeof value !== 'string' || value.length === 0 || /[\u0000-\u001f\u007f]/.test(value)) { + throw new TypeError(`${name} must be nonempty text without control characters`); + } + for (const character of value) { + const code = character.codePointAt(0); + if (code >= 0xd800 && code <= 0xdfff) throw new TypeError(`${name} must contain valid Unicode`); + } + if (new TextEncoder().encode(value).byteLength > maxBytes) throw new RangeError(`${name} exceeds ${maxBytes} UTF-8 bytes`); + return value; +} + +export function floats(values, dimensions, name, allowEmpty = false) { + if (!Array.isArray(values) || (!allowEmpty && values.length === 0) || + values.length > LIMITS.maxElements || values.length % dimensions !== 0) { + throw new RangeError(`${name} must be a bounded array of complete vectors`); + } + integer(values.length / dimensions, allowEmpty ? 0 : 1, LIMITS.maxRows, `${name} rows`); + for (const value of values) { + if (!Number.isFinite(value) || Math.abs(value) > 3.4028234663852886e38) { + throw new RangeError(`${name} must contain finite float32 values`); + } + } + return new Float32Array(values); +} + +export function fitOptions(value, rows) { + const options = plain(value, ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization'], ['clusters'], 'fit options'); + integer(options.clusters, 1, Math.min(rows, LIMITS.maxClusters), 'clusters'); + if (options.epochs !== undefined) integer(options.epochs, 1, LIMITS.maxEpochs, 'epochs'); + if (options.batchSize !== undefined) integer(options.batchSize, 1, LIMITS.maxRows, 'batchSize'); + if (options.peakStep !== undefined && (!Number.isFinite(options.peakStep) || options.peakStep <= 0 || options.peakStep > 1)) { + throw new RangeError('peakStep must be in (0, 1]'); + } + if (options.seed !== undefined) integer(options.seed, 0, Number.MAX_SAFE_INTEGER, 'seed'); + if (options.finalization !== undefined && !['lastEpochMean', 'ema'].includes(options.finalization)) { + throw new TypeError('unsupported finalization'); + } + return options; +} + +export function checkedCodebook(value) { + if (!value || typeof value !== 'object') throw new TypeError('codebook is required'); + const schemaDescriptor = Object.getOwnPropertyDescriptor(value, 'schema'); + if (schemaDescriptor && (!Object.hasOwn(schemaDescriptor, 'value') || schemaDescriptor.value !== 'ruvector.e-means-codebook/1')) { + throw new TypeError('expected a single row-major codebook, not another model schema'); + } + const dimensionsDescriptor = Object.getOwnPropertyDescriptor(value, 'dimensions'); + const centroidsDescriptor = Object.getOwnPropertyDescriptor(value, 'centroids'); + if (!dimensionsDescriptor || !centroidsDescriptor || + !Object.hasOwn(dimensionsDescriptor, 'value') || !Object.hasOwn(centroidsDescriptor, 'value')) { + throw new TypeError('codebook dimensions and centroids must be own data properties'); + } + const dimensions = integer(dimensionsDescriptor.value, 1, LIMITS.maxElements, 'dimensions'); + const centroids = centroidsDescriptor.value; + if (!(centroids instanceof Float32Array) || centroids.length === 0 || + centroids.length > LIMITS.maxElements || centroids.length % dimensions !== 0) { + throw new RangeError('codebook must contain complete finite centroid rows'); + } + // Validate the owned snapshot, including when the caller supplies shared + // storage or overrides its typed-array iterator. + const owned = new Float32Array(centroids); + for (let index = 0; index < owned.length; index++) { + if (!Number.isFinite(owned[index])) throw new RangeError('centroids must be finite'); + } + return { schema: 'ruvector.e-means-codebook/1', dimensions, + clusters: owned.length / dimensions, centroids: owned }; +} diff --git a/npm/packages/e-means/integrations/clustering-validation.mjs b/npm/packages/e-means/integrations/clustering-validation.mjs new file mode 100644 index 0000000000..e7e058f72e --- /dev/null +++ b/npm/packages/e-means/integrations/clustering-validation.mjs @@ -0,0 +1,111 @@ +const PARAMS = ['clusters', 'epochs', 'batchSize', 'peakStep']; +const FIT_KEYS = [...PARAMS, 'seed', 'finalization']; +const MAX_U32 = 0xffff_ffff; +export const MAX_INPUT_BYTES = 64 * 1024 * 1024; +export const MAX_WORK = 1_000_000_000; + +export function object(value, allowed, name) { + if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${name} must be an object`); + for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new TypeError(`Unsupported ${name} field: ${key}`); + return value; +} + +export function integer(value, min, max, name) { + if (!Number.isSafeInteger(value) || value < min || value > max) throw new RangeError(`${name} must be an integer in ${min}..${max}`); + return value; +} + +function finite(value, min, max, name) { + if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) throw new RangeError(`${name} must be finite in ${min}..${max}`); + return value; +} + +function rows(data, dimensions, name) { + if (!(data instanceof Float32Array)) throw new TypeError(`${name} must be a Float32Array`); + if (!data.length || data.length % dimensions) throw new RangeError(`${name} must contain nonempty complete vectors`); + for (let i = 0; i < data.length; i++) if (!Number.isFinite(data[i])) throw new RangeError(`${name} must contain only finite values`); + return data.length / dimensions; +} + +function config(value, samples) { + object(value, FIT_KEYS, 'baseline'); + const out = { clusters: value.clusters, epochs: value.epochs === undefined ? 3 : value.epochs, + seed: value.seed === undefined ? 42 : value.seed, finalization: value.finalization === undefined ? 'lastEpochMean' : value.finalization }; + integer(out.clusters, 1, samples, 'clusters'); + integer(out.epochs, 1, MAX_U32, 'epochs'); + integer(out.seed, 0, Number.MAX_SAFE_INTEGER, 'seed'); + if (!['lastEpochMean', 'ema'].includes(out.finalization)) throw new RangeError('Unsupported finalization'); + if (value.batchSize !== undefined) out.batchSize = integer(value.batchSize, 1, MAX_U32, 'batchSize'); + if (value.peakStep !== undefined) out.peakStep = finite(value.peakStep, Number.MIN_VALUE, 1, 'peakStep'); + return out; +} + +function domain(value, baseline, samples) { + object(value, PARAMS, 'domain'); + if (!Object.keys(value).length) throw new RangeError('domain must contain at least one tunable parameter'); + const result = {}; + for (const [name, supplied] of Object.entries(value)) { + object(supplied, ['min', 'max', 'type', 'scale', 'default'], `${name} domain`); + const min = finite(supplied.min, Number.MIN_VALUE, name === 'peakStep' ? 1 : MAX_U32, `${name}.min`); + const max = finite(supplied.max, min, name === 'peakStep' ? 1 : MAX_U32, `${name}.max`); + const type = name === 'peakStep' ? 'float' : 'int'; + if (supplied.type !== type || !['linear', 'log'].includes(supplied.scale)) throw new TypeError(`Invalid type or scale for ${name}`); + if (type === 'int') { integer(min, 1, MAX_U32, `${name}.min`); integer(max, min, MAX_U32, `${name}.max`); } + if (name === 'clusters' && max > samples) throw new RangeError('Cluster domain exceeds training rows'); + if (baseline[name] === undefined || baseline[name] < min || baseline[name] > max) throw new RangeError(`baseline ${name} must be explicitly inside its domain`); + if (supplied.default !== undefined && supplied.default !== baseline[name]) throw new RangeError(`${name}.default must match the baseline`); + result[name] = Object.freeze({ min, max, type, scale: supplied.scale, default: baseline[name] }); + } + return Object.freeze(result); +} + +// Coordinate-scale upper estimate, including short-batch statistics and O(k²) +// donor selection. It is an admission budget, not a measured instruction count. +export function workEstimate(config, n, holdout, d) { + const k = config.clusters, epochs = config.epochs; + // When automatic batch size is requested, B>=1 is a safe lower bound. + const batch = Math.min(config.batchSize ?? 1, n); + const updates = epochs * Math.ceil(n / batch); + const work = n * k * d * epochs + (n + holdout) * k * d + holdout * d + + n * d * (epochs + 1) + n * (epochs + 1) + + updates * k * (8 * d + 6) + Math.floor(updates / 5) * (3 * k * k + 6 * k * d + 3 * k); + if (!Number.isSafeInteger(work) || !Number.isSafeInteger(updates)) throw new RangeError('Clustering work estimate exceeds safe integer range'); + return work; +} + +export function checkOptions(value) { + object(value, ['training', 'holdout', 'dimensions', 'baseline', 'domain', 'budget', 'qualityTolerance'], 'evaluator options'); + const dimensions = integer(value.dimensions, 1, MAX_U32, 'dimensions'); + if (!(value.training instanceof Float32Array) || !(value.holdout instanceof Float32Array)) throw new TypeError('training and holdout must be Float32Array values'); + const bytes = value.training.byteLength + value.holdout.byteLength; + if (bytes > MAX_INPUT_BYTES) throw new RangeError('Input snapshots exceed 64 MiB'); + const n = rows(value.training, dimensions, 'training'), h = rows(value.holdout, dimensions, 'holdout'); + if (value.training.buffer === value.holdout.buffer && value.training.byteOffset < value.holdout.byteOffset + value.holdout.byteLength && + value.holdout.byteOffset < value.training.byteOffset + value.training.byteLength) throw new RangeError('training and holdout must use separate, nonoverlapping rows'); + const baseline = Object.freeze(config(value.baseline, n)); + const space = domain(value.domain, baseline, n); + object(value.budget, ['maxEvaluations', 'maxDistanceCoordinates', 'timeoutMs'], 'budget'); + const budget = Object.freeze({ maxEvaluations: integer(value.budget.maxEvaluations, 1, 32, 'maxEvaluations'), + maxDistanceCoordinates: integer(value.budget.maxDistanceCoordinates, 1, MAX_WORK, 'maxDistanceCoordinates'), + timeoutMs: integer(value.budget.timeoutMs === undefined ? 30_000 : value.budget.timeoutMs, 1, 120_000, 'timeoutMs') }); + const worst = { ...baseline }; + for (const [name, spec] of Object.entries(space)) worst[name] = name === 'batchSize' ? spec.min : spec.max; + const worstCaseWorkPerTrial = workEstimate(worst, n, h, dimensions); + if (worstCaseWorkPerTrial > budget.maxDistanceCoordinates) throw new RangeError(`Domain permits work ${worstCaseWorkPerTrial} above maxDistanceCoordinates`); + const qualityTolerance = finite(value.qualityTolerance === undefined ? 0 : value.qualityTolerance, 0, 1, 'qualityTolerance'); + return { training: new Float32Array(value.training), holdout: new Float32Array(value.holdout), dimensions, n, h, baseline, + domain: space, budget, qualityTolerance, numericSnapshotBytes: bytes, worstCaseWorkPerTrial }; +} + +export function checkGenome(value, space) { + const keys = Object.keys(space); + object(value, keys, 'genome'); + if (Object.keys(value).length !== keys.length) throw new RangeError('Genome must include every domain parameter'); + const out = {}; + for (const [name, spec] of Object.entries(space)) { + out[name] = spec.type === 'int' ? integer(value[name], spec.min, spec.max, name) : finite(value[name], spec.min, spec.max, name); + } + return out; +} + +export const clone = value => structuredClone(value); diff --git a/npm/packages/e-means/integrations/ivf.d.ts b/npm/packages/e-means/integrations/ivf.d.ts new file mode 100644 index 0000000000..c1345fb8ee --- /dev/null +++ b/npm/packages/e-means/integrations/ivf.d.ts @@ -0,0 +1,16 @@ +import type { EMeansModel, EMeansOptions } from '../e-means.js'; + +/** Caller-owned structured-clone-compatible records; postingList validates on every operation. */ +export interface IVFPartition { + schema: 'ruvector-e-means-ivf-v1'; + model: EMeansModel; + /** Length clusters+1. Cluster j occupies indices[offsets[j]..offsets[j+1]). */ + offsets: Uint32Array; + /** Original input indices, in ascending order within every cluster. */ + indices: Uint32Array; +} + +/** Requires init() from the root package. Trains centroids and returns owned posting arrays. */ +export function partition(data: Float32Array, dimensions: number, options: EMeansOptions): IVFPartition; +/** Validates shape, assignment consistency and stable unique indices; returns an owned list. */ +export function postingList(value: IVFPartition, cluster: number): Uint32Array; diff --git a/npm/packages/e-means/integrations/ivf.mjs b/npm/packages/e-means/integrations/ivf.mjs new file mode 100644 index 0000000000..d9efa910a9 --- /dev/null +++ b/npm/packages/e-means/integrations/ivf.mjs @@ -0,0 +1,65 @@ +import { fit } from '../e-means.mjs'; + +const schema = 'ruvector-e-means-ivf-v1'; + +/** Train coarse centroids and construct stable posting lists from exact Rust/WASM assignments. */ +export function partition(data, dimensions, options) { + const model = fit(data, dimensions, options); + const clusters = model.centroids.length / dimensions; + const offsets = new Uint32Array(clusters + 1); + for (const cluster of model.assignments) offsets[cluster + 1]++; + for (let cluster = 0; cluster < clusters; cluster++) offsets[cluster + 1] += offsets[cluster]; + const cursors = offsets.slice(0, clusters); + const indices = new Uint32Array(model.assignments.length); + for (let row = 0; row < model.assignments.length; row++) { + indices[cursors[model.assignments[row]]++] = row; + } + return { schema, model, offsets, indices }; +} + +function validated(value) { + if (value === null || typeof value !== 'object' || value.schema !== schema) { + throw new TypeError(`partition must use schema ${schema}`); + } + const { model, offsets, indices } = value; + if (model === null || typeof model !== 'object') throw new TypeError('partition must contain a model'); + const { dimensions, centroids, assignments, mse, batchSize, peakStep, updates, revivedClusters } = model; + if (!Number.isInteger(dimensions) || dimensions < 1 || dimensions > 0xffff_ffff) throw new RangeError('model dimensions must be positive'); + if (!(centroids instanceof Float32Array) || centroids.length === 0 || centroids.length % dimensions !== 0) { + throw new RangeError('model centroids must be complete Float32Array vectors'); + } + for (let index = 0; index < centroids.length; index++) { + if (!Number.isFinite(centroids[index])) throw new RangeError('model centroids must be finite'); + } + if (!Number.isFinite(mse) || mse < 0 || !Number.isFinite(peakStep) || peakStep <= 0 || peakStep > 1 || + !Number.isSafeInteger(batchSize) || batchSize < 1 || !Number.isSafeInteger(updates) || updates < 1 || + !Number.isSafeInteger(revivedClusters) || revivedClusters < 0) throw new RangeError('model metrics are invalid'); + if (!(assignments instanceof Uint32Array) || !(offsets instanceof Uint32Array) || !(indices instanceof Uint32Array)) { + throw new TypeError('assignments, offsets and indices must be Uint32Array values'); + } + const clusters = centroids.length / dimensions; + if (offsets.length !== clusters + 1 || offsets[0] !== 0 || offsets[clusters] !== indices.length || indices.length !== assignments.length) { + throw new RangeError('posting offsets must cover every model assignment exactly once'); + } + for (let cluster = 0; cluster < clusters; cluster++) { + const start = offsets[cluster]; + const end = offsets[cluster + 1]; + if (end < start || end > indices.length) throw new RangeError('posting offsets must be monotonic'); + let previous = -1; + for (let cursor = start; cursor < end; cursor++) { + const row = indices[cursor]; + if (row <= previous || row >= assignments.length || assignments[row] !== cluster) { + throw new RangeError('posting indices must be unique, stable and consistent with model assignments'); + } + previous = row; + } + } + return { clusters, offsets, indices }; +} + +/** Return an owned copy of one posting list after validating the caller-owned partition. */ +export function postingList(value, cluster) { + const { clusters, offsets, indices } = validated(value); + if (!Number.isInteger(cluster) || cluster < 0 || cluster >= clusters) throw new RangeError('cluster is outside the partition'); + return indices.slice(offsets[cluster], offsets[cluster + 1]); +} diff --git a/npm/packages/e-means/integrations/metaharness.d.ts b/npm/packages/e-means/integrations/metaharness.d.ts new file mode 100644 index 0000000000..58db50b900 --- /dev/null +++ b/npm/packages/e-means/integrations/metaharness.d.ts @@ -0,0 +1,115 @@ +import type { EMeansOptions } from '@ruvector/e-means'; + +export interface ClusteringParameter { + min: number; + max: number; + type: 'int' | 'float'; + scale: 'linear' | 'log'; + /** If supplied, must equal the baseline's value for this parameter. */ + default?: number; +} + +export interface ClusteringBudget { + /** Includes the baseline and every admitted dispatch. Integer 1..32. */ + maxEvaluations: number; + /** Conservative scalar-work allowance, including short-batch centroid updates and revival; at most 1e9. */ + maxDistanceCoordinates: number; + /** Cooperative deadline in milliseconds, 1..120000; default 30000. A synchronous fit cannot be preempted. */ + timeoutMs?: number; +} + +export interface ClusteringEvaluationOptions { + training: Float32Array; + /** Nonempty, nonoverlapping validation rows. Selection uses this split; supply another test split for generalization claims. */ + holdout: Float32Array; + dimensions: number; + baseline: EMeansOptions; + /** Searched parameters need explicit baseline values; peakStep uses float, all other fields use int. */ + domain: Partial>; + budget: ClusteringBudget; + /** Relative holdout-MSE degradation allowance in [0,1], default 0. */ + qualityTolerance?: number; +} + +export interface ClusteringScoreCard { + variantId: string; + /** Higher is better: 1/(1+holdoutMse). */ + primary: number; + regressed: boolean; + noopRate: 0; + costPerWin: 0; + raw: { + fitConfig: EMeansOptions; + trainMse: number; + holdoutMse: number; + baselineHoldoutMse: number; + fitMs: number; + holdoutMs: number; + estimatedWork: number; + updates: number; + revivedClusters: number; + trainingRows: number; + holdoutRows: number; + dimensions: number; + }; +} + +export interface ClusteringTrial { + variantId: string; + genome: Record; + score: ClusteringScoreCard; +} + +export interface ClusteringEvaluationReceipt { + schema: 'e-means.clustering-evaluation/1'; + baseline?: ClusteringTrial; + trials: ClusteringTrial[]; + baselineGenome: Record; + baselineConfig: EMeansOptions; + domain: Record; + dimensions: number; + trainingRows: number; + holdoutRows: number; + qualityTolerance: number; + budget: Required; + dispatchCount: number; + consumedWork: number; + worstCaseWorkPerTrial: number; + numericSnapshotBytes: number; + sourceApplied: false; + scope: string; + timingScope: string; + limits: { maxInputBytes: number; maxDistanceCoordinates: number; cooperativeDeadline: true; workUnit: string }; +} + +/** Structurally compatible with @metaharness/darwin's NumericEvaluator. */ +export interface ClusteringEvaluator { + readonly baselineGenome: Readonly>; + readonly domain: Readonly>>; + evaluate(genome: Readonly>, variantId: string): Promise; + /** Returns an independent snapshot. Changes never affect evaluator state. */ + receipt(): ClusteringEvaluationReceipt; +} + +export interface ClusteringTuningOptions extends ClusteringEvaluationOptions { + generations: number; + childrenPerGeneration: number; + mutationSeed?: number; +} + +export interface ClusteringTuningReceipt extends Omit { + schema: 'e-means.clustering-tuning/1'; + engine: { package: '@metaharness/darwin'; version: '0.13.0' | '0.13.1'; algorithm: 'evolveNumeric' }; + baseline: ClusteringTrial; + winner: ClusteringTrial; + recommendation: EMeansOptions; + winnerRejected: boolean; + improvedOnObservedHoldout: boolean; + search: { generations: number; childrenPerGeneration: number; mutationSeed: number; worstCaseDispatches: number; concurrency: 1 }; + temporaryArchiveRemoved: true; +} + +/** Copies inputs/configuration synchronously. First evaluate() must use baselineGenome. No SDK import occurs here. */ +export function createClusteringEvaluator(options: ClusteringEvaluationOptions): ClusteringEvaluator; +/** Node-only bounded search using the actual optional @metaharness/darwin 0.13.0 or 0.13.1 peer. Never applies a model. */ +export function tuneClustering(options: ClusteringTuningOptions): Promise; diff --git a/npm/packages/e-means/integrations/metaharness.mjs b/npm/packages/e-means/integrations/metaharness.mjs new file mode 100644 index 0000000000..5a14ba0ad5 --- /dev/null +++ b/npm/packages/e-means/integrations/metaharness.mjs @@ -0,0 +1,154 @@ +import { init, fit, predict } from '../e-means.mjs'; +import { checkOptions, checkGenome, clone, integer, object, workEstimate, MAX_INPUT_BYTES, MAX_WORK } from './clustering-validation.mjs'; + +function holdoutMse(data, dimensions, centroids) { + const assignments = predict(data, dimensions, centroids); + let loss = 0; + for (let row = 0; row < assignments.length; row++) { + const centroid = assignments[row] * dimensions; + for (let d = 0; d < dimensions; d++) { + const delta = data[row * dimensions + d] - centroids[centroid + d]; + loss += delta * delta; + } + } + return loss / assignments.length; +} + +/** NumericEvaluator compatible with published Darwin 0.13.0 and 0.13.1. Snapshots happen + * synchronously before any await. The first dispatch must be the baseline. + */ +export function createClusteringEvaluator(options) { + const config = checkOptions(options); + const baselineGenome = Object.freeze(Object.fromEntries(Object.keys(config.domain).map(key => [key, config.baseline[key]]))); + const trials = [], ids = new Set(); + let active = false, calls = 0, consumedWork = 0, baseline; + const started = performance.now(); + const check = () => { + if (performance.now() - started > config.budget.timeoutMs) throw new Error('Clustering cooperative deadline exceeded'); + }; + const receipt = () => clone({ schema: 'e-means.clustering-evaluation/1', baseline, trials, + baselineGenome, baselineConfig: config.baseline, domain: config.domain, + dimensions: config.dimensions, trainingRows: config.n, holdoutRows: config.h, + qualityTolerance: config.qualityTolerance, budget: config.budget, + dispatchCount: calls, consumedWork, worstCaseWorkPerTrial: config.worstCaseWorkPerTrial, + numericSnapshotBytes: config.numericSnapshotBytes, sourceApplied: false, + scope: 'Caller-supplied training and holdout snapshots. Holdout guides selection and is not an independent generalization test.', + timingScope: 'One synchronous Rust/WASM fit and one separate holdout prediction/MSE calculation per dispatch; initialization excluded.', + limits: { maxInputBytes: MAX_INPUT_BYTES, maxDistanceCoordinates: MAX_WORK, cooperativeDeadline: true, + workUnit: 'Conservative coordinate-scale work estimate including centroid updates and donor selection; not measured instructions.' } }); + + const evaluator = { + baselineGenome, + domain: config.domain, + async evaluate(genome, variantId) { + check(); + if (active) throw new Error('Concurrent clustering evaluations are not supported'); + if (calls >= config.budget.maxEvaluations) throw new RangeError('Clustering evaluation budget exhausted'); + calls++; + if (typeof variantId !== 'string' || !variantId || variantId.length > 128 || ids.has(variantId)) throw new TypeError('variantId must be a unique nonempty label of at most 128 characters'); + const selected = checkGenome(genome, config.domain); + if (!baseline && JSON.stringify(selected) !== JSON.stringify(baselineGenome)) throw new Error('First evaluation must use baselineGenome'); + const fitConfig = { ...config.baseline, ...selected }; + const work = workEstimate(fitConfig, config.n, config.h, config.dimensions); + if (work > config.budget.maxDistanceCoordinates - consumedWork) throw new RangeError('Clustering coordinate work budget exhausted'); + ids.add(variantId); consumedWork += work; active = true; + try { + await init(); + check(); + const fitStart = performance.now(); + const model = fit(config.training, config.dimensions, fitConfig); + const fitMs = performance.now() - fitStart; + check(); + const scoreStart = performance.now(); + const mse = holdoutMse(config.holdout, config.dimensions, model.centroids); + const holdoutMs = performance.now() - scoreStart; + check(); + if (!Number.isFinite(mse) || mse < 0) throw new Error('Nonfinite clustering evaluation'); + const baselineMse = baseline?.score.raw.holdoutMse ?? mse; + const score = { variantId, primary: 1 / (1 + mse), regressed: mse > baselineMse * (1 + config.qualityTolerance), + noopRate: 0, costPerWin: 0, raw: { fitConfig, trainMse: model.mse, holdoutMse: mse, baselineHoldoutMse: baselineMse, + fitMs, holdoutMs, estimatedWork: work, updates: model.updates, revivedClusters: model.revivedClusters, + trainingRows: config.n, holdoutRows: config.h, dimensions: config.dimensions } }; + const trial = clone({ variantId, genome: selected, score }); + trials.push(trial); + if (!baseline) baseline = trial; + return clone(score); + } finally { active = false; } + }, + receipt, + }; + return Object.freeze(evaluator); +} + +// Exact versions whose numeric API this integration was run against. +const DARWIN_VERSIONS = ['0.13.0', '0.13.1']; + +async function loadDarwin() { + const { readFile } = await import('node:fs/promises'); + let entry; + try { entry = import.meta.resolve('@metaharness/darwin'); } + catch (cause) { throw new Error(`tuneClustering requires optional peer @metaharness/darwin (${DARWIN_VERSIONS.join(' or ')})`, { cause }); } + const manifest = JSON.parse(await readFile(new URL('../package.json', entry), 'utf8')); + if (manifest.name !== '@metaharness/darwin' || !DARWIN_VERSIONS.includes(manifest.version)) throw new Error(`Expected @metaharness/darwin ${DARWIN_VERSIONS.join(' or ')}`); + const { evolveNumeric } = await import('@metaharness/darwin'); + if (typeof evolveNumeric !== 'function') throw new Error('Darwin numeric API is unavailable'); + return { evolveNumeric, version: manifest.version }; +} + +/** Run bounded, local numeric evolution. Never mutates source or applies a model. */ +export async function tuneClustering(options) { + const started = performance.now(); + object(options, ['training', 'holdout', 'dimensions', 'baseline', 'domain', 'budget', 'qualityTolerance', 'generations', 'childrenPerGeneration', 'mutationSeed'], 'tuning options'); + const { generations, childrenPerGeneration, mutationSeed = 0, ...evaluation } = options; + integer(generations, 1, 8, 'generations'); + integer(childrenPerGeneration, 1, 8, 'childrenPerGeneration'); + integer(mutationSeed, 0, 0xffff_ffff, 'mutationSeed'); + const evaluator = createClusteringEvaluator(evaluation); + const initial = evaluator.receipt(); + const check = () => { + if (performance.now() - started > initial.budget.timeoutMs) throw new Error('Clustering cooperative deadline exceeded'); + }; + const worstCaseDispatches = 1 + childrenPerGeneration + 2 * childrenPerGeneration * (generations - 1); + if (worstCaseDispatches > initial.budget.maxEvaluations) throw new RangeError('Darwin worst-case dispatches exceed maxEvaluations'); + if (worstCaseDispatches * initial.worstCaseWorkPerTrial > initial.budget.maxDistanceCoordinates) throw new RangeError('Darwin worst-case work exceeds maxDistanceCoordinates'); + const { evolveNumeric, version: darwinVersion } = await loadDarwin(); + check(); + const { mkdtemp, rm } = await import('node:fs/promises'); + const { tmpdir } = await import('node:os'); + const { join } = await import('node:path'); + let archive, failure, answer; + try { + archive = await mkdtemp(join(tmpdir(), 'e-means-darwin-')); + check(); + const result = await evolveNumeric({ genomeSpec: evaluator.domain, baselineGenome: evaluator.baselineGenome, + evaluator: { evaluate: async (...args) => { + try { return await evaluator.evaluate(...args); } + catch (error) { failure = error; throw error; } + } }, generations, childrenPerGeneration, seed: mutationSeed, concurrency: 1, + mutationSigma: 0.2, crossover: false, workRoot: archive }); + if (failure) throw failure; + check(); + const measured = evaluator.receipt(); + if (!Array.isArray(result?.records) || result.records.length !== measured.trials.length || measured.dispatchCount !== measured.trials.length) throw new Error('Darwin archive differs from observed evaluations'); + const observed = new Map(measured.trials.map(trial => [trial.variantId, trial])); + const verified = record => { + const trial = observed.get(record?.variant?.id); + if (!trial || JSON.stringify(trial.genome) !== JSON.stringify(record.variant.genome) || JSON.stringify(trial.score) !== JSON.stringify(record.score)) throw new Error('Darwin returned an unobserved result'); + return trial; + }; + for (const record of result.records) verified(record); + const baseline = verified(result.baseline); + if (JSON.stringify(baseline.genome) !== JSON.stringify(evaluator.baselineGenome)) throw new Error('Darwin changed the requested baseline'); + let winner = result.winner ? verified(result.winner) : baseline; + const winnerRejected = winner.score.regressed || winner.score.primary < baseline.score.primary; + if (winnerRejected) winner = baseline; + answer = { engine: { package: '@metaharness/darwin', version: darwinVersion, algorithm: 'evolveNumeric' }, + ...measured, schema: 'e-means.clustering-tuning/1', baseline, winner, + recommendation: clone(winner.score.raw.fitConfig), winnerRejected, + improvedOnObservedHoldout: winner.score.primary > baseline.score.primary, + search: { generations, childrenPerGeneration, mutationSeed, worstCaseDispatches, concurrency: 1 }, + sourceApplied: false, temporaryArchiveRemoved: true }; + } finally { if (archive) await rm(archive, { recursive: true, force: true }); } + check(); + return answer; +} diff --git a/npm/packages/e-means/integrations/quantization.d.ts b/npm/packages/e-means/integrations/quantization.d.ts new file mode 100644 index 0000000000..b1aa5ad55e --- /dev/null +++ b/npm/packages/e-means/integrations/quantization.d.ts @@ -0,0 +1,29 @@ +import type { EMeansOptions } from '../e-means.js'; + +/** Caller-owned mutable records. Every codec operation validates their shape and finite coordinates. */ +export interface ProductQuantizer { + schema: 'ruvector-e-means-pq-v1'; + dimensions: number; + subspaces: number; + /** 1..256, shared by every subspace. */ + clusters: number; + /** Flat subspace-major codebooks: subspaces × clusters × (dimensions/subspaces). */ + centroids: Float32Array; +} + +export interface ProductQuantizerJSON { + schema: 'ruvector-e-means-pq-v1'; + dimensions: number; + subspaces: number; + clusters: number; + centroids: number[]; +} + +/** Requires init() from the root package. Input data is borrowed; returned centroids are owned. */ +export function trainProductQuantizer(data: Float32Array, dimensions: number, subspaces: number, options: EMeansOptions): ProductQuantizer; +/** Requires init(). Codes are row-major, rows × subspaces bytes. Empty input is supported. */ +export function encodeProductQuantizer(model: ProductQuantizer, data: Float32Array): Uint8Array; +/** No runtime initialization required. Returns an owned reconstruction; empty codes are supported. */ +export function decodeProductQuantizer(model: ProductQuantizer, codes: Uint8Array): Float32Array; +export function productQuantizerToJSON(model: ProductQuantizer): ProductQuantizerJSON; +export function productQuantizerFromJSON(value: unknown): ProductQuantizer; diff --git a/npm/packages/e-means/integrations/quantization.mjs b/npm/packages/e-means/integrations/quantization.mjs new file mode 100644 index 0000000000..903a4a315f --- /dev/null +++ b/npm/packages/e-means/integrations/quantization.mjs @@ -0,0 +1,150 @@ +import { fit, predict } from '../e-means.mjs'; + +const schema = 'ruvector-e-means-pq-v1'; +const maxU32 = 0xffff_ffff; + +function positiveInteger(value, name, maximum = maxU32) { + if (!Number.isInteger(value) || value < 1 || value > maximum) { + throw new RangeError(`${name} must be an integer in 1..${maximum}`); + } +} + +function shape(dimensions, subspaces, clusters) { + positiveInteger(dimensions, 'dimensions'); + positiveInteger(subspaces, 'subspaces', dimensions); + positiveInteger(clusters, 'clusters', 256); + if (dimensions % subspaces !== 0) throw new RangeError('dimensions must be divisible by subspaces'); + return dimensions / subspaces; +} + +function vectors(data, dimensions, allowEmpty = false) { + if (!(data instanceof Float32Array)) throw new TypeError('data must be a Float32Array'); + if ((!allowEmpty && data.length === 0) || data.length % dimensions !== 0) { + throw new RangeError('data must contain complete vectors'); + } + for (let index = 0; index < data.length; index++) { + if (!Number.isFinite(data[index])) throw new RangeError('data must be finite'); + } +} + +function validated(model) { + if (model === null || typeof model !== 'object' || model.schema !== schema) { + throw new TypeError(`model must use schema ${schema}`); + } + const { dimensions, subspaces, clusters, centroids } = model; + const subDimensions = shape(dimensions, subspaces, clusters); + if (!(centroids instanceof Float32Array)) throw new TypeError('centroids must be a Float32Array'); + if (centroids.length !== dimensions * clusters) throw new RangeError('centroid count does not match the codebook shape'); + for (let index = 0; index < centroids.length; index++) { + if (!Number.isFinite(centroids[index])) throw new RangeError('centroids must be finite'); + } + return { dimensions, subspaces, clusters, centroids, subDimensions }; +} + +function gather(data, dimensions, subDimensions, subspace, target) { + for (let row = 0; row < data.length / dimensions; row++) { + const start = row * dimensions + subspace * subDimensions; + target.set(data.subarray(start, start + subDimensions), row * subDimensions); + } +} + +function snapshotOptions(options) { + if (options === null || typeof options !== 'object' || Array.isArray(options)) { + throw new TypeError('options must contain clusters'); + } + // Read caller properties once so all subspaces use one stable configuration. + const config = { ...options }; + const supported = ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization']; + for (const key of Object.keys(config)) if (!supported.includes(key)) throw new TypeError(`Unknown option: ${key}`); + if (config.epochs !== undefined) positiveInteger(config.epochs, 'epochs'); + if (config.batchSize !== undefined) positiveInteger(config.batchSize, 'batchSize'); + if (config.peakStep !== undefined && + (typeof config.peakStep !== 'number' || !Number.isFinite(config.peakStep) || config.peakStep <= 0 || config.peakStep > 1)) { + throw new RangeError('peakStep must be finite and in (0, 1]'); + } + if (config.seed !== undefined && (!Number.isSafeInteger(config.seed) || config.seed < 0)) throw new RangeError('seed must be a non-negative safe integer'); + if (config.finalization !== undefined && !['lastEpochMean', 'ema'].includes(config.finalization)) throw new RangeError('unsupported finalization'); + return config; +} + +/** Train independent subspace codebooks using the shared Rust/WASM fitter. Requires init(). */ +export function trainProductQuantizer(data, dimensions, subspaces, options) { + const config = snapshotOptions(options); + const clusters = config.clusters; + const subDimensions = shape(dimensions, subspaces, clusters); + vectors(data, dimensions); + const rows = data.length / dimensions; + if (clusters > rows) throw new RangeError('clusters cannot exceed the number of vectors'); + const centroids = new Float32Array(clusters * dimensions); + const subvector = new Float32Array(rows * subDimensions); + for (let subspace = 0; subspace < subspaces; subspace++) { + gather(data, dimensions, subDimensions, subspace, subvector); + const model = fit(subvector, subDimensions, config); + centroids.set(model.centroids, subspace * clusters * subDimensions); + } + return { schema, dimensions, subspaces, clusters, centroids }; +} + +/** Encode to row-major, one-byte-per-subspace codes using exact Rust/WASM assignment. */ +export function encodeProductQuantizer(model, data) { + const { dimensions, subspaces, clusters, centroids, subDimensions } = validated(model); + vectors(data, dimensions, true); + const rows = data.length / dimensions; + const codes = new Uint8Array(rows * subspaces); + const subvector = new Float32Array(rows * subDimensions); + for (let subspace = 0; subspace < subspaces; subspace++) { + gather(data, dimensions, subDimensions, subspace, subvector); + const start = subspace * clusters * subDimensions; + const assignments = predict(subvector, subDimensions, centroids.subarray(start, start + clusters * subDimensions)); + for (let row = 0; row < rows; row++) codes[row * subspaces + subspace] = assignments[row]; + } + return codes; +} + +/** Reconstruct row-major vectors from a validated codebook and byte codes. Does not require init(). */ +export function decodeProductQuantizer(model, codes) { + const { dimensions, subspaces, clusters, centroids, subDimensions } = validated(model); + if (!(codes instanceof Uint8Array)) throw new TypeError('codes must be a Uint8Array'); + if (codes.length % subspaces !== 0) throw new RangeError('codes must contain complete subspace groups'); + for (let index = 0; index < codes.length; index++) { + if (codes[index] >= clusters) throw new RangeError('code exceeds the codebook cluster count'); + } + const rows = codes.length / subspaces; + if (rows * dimensions > maxU32) throw new RangeError('decoded output exceeds the supported element count'); + const data = new Float32Array(rows * dimensions); + for (let row = 0; row < rows; row++) { + for (let subspace = 0; subspace < subspaces; subspace++) { + const code = codes[row * subspaces + subspace]; + const start = (subspace * clusters + code) * subDimensions; + data.set(centroids.subarray(start, start + subDimensions), row * dimensions + subspace * subDimensions); + } + } + return data; +} + +/** Return owned JSON-compatible codebook data. */ +export function productQuantizerToJSON(model) { + const { dimensions, subspaces, clusters, centroids } = validated(model); + return { schema, dimensions, subspaces, clusters, centroids: Array.from({ length: centroids.length }, (_, index) => centroids[index]) }; +} + +/** Restore a validated, owned typed codebook from parsed JSON. */ +export function productQuantizerFromJSON(value) { + if (value === null || typeof value !== 'object' || value.schema !== schema) { + throw new TypeError(`model must use schema ${schema}`); + } + const { dimensions, subspaces, clusters, centroids } = value; + shape(dimensions, subspaces, clusters); + if (!Array.isArray(centroids) || centroids.length !== dimensions * clusters) { + throw new RangeError('JSON centroids must be an array matching the codebook shape'); + } + const owned = new Float32Array(centroids.length); + for (let index = 0; index < centroids.length; index++) { + const coordinate = centroids[index]; + if (typeof coordinate !== 'number' || !Number.isFinite(coordinate)) throw new RangeError('JSON centroids must be finite numbers'); + owned[index] = coordinate; + } + const model = { schema, dimensions, subspaces, clusters, centroids: owned }; + validated(model); + return model; +} diff --git a/npm/packages/e-means/package-lock.json b/npm/packages/e-means/package-lock.json new file mode 100644 index 0000000000..f5b191bec2 --- /dev/null +++ b/npm/packages/e-means/package-lock.json @@ -0,0 +1,1534 @@ +{ + "name": "@ruvector/e-means", + "version": "0.1.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "@ruvector/e-means", + "version": "0.1.0", + "license": "MIT", + "devDependencies": { + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0", + "typescript": "5.9.3" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0 || 0.13.1" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.29.13.tgz", + "integrity": "sha512-fWegr+WsEsiMVW4KUNdIIzzMTZSzNiqhy0//6+2MRi2d5NFNsL/AYwBQW8eBnRbTBVRnDVzjaJEUqKaCWjMMdQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.29.7", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.29.7.tgz", + "integrity": "sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.29.13", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.29.13.tgz", + "integrity": "sha512-fJM50YYjlTiBhgdkGmC1tBpv+FMAyo4annf2X6Aks+0yRlaiVkYW/3f07xAfVVkYIoZ9fFZp+mEThUFnuybhkQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.29.11" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/types": { + "version": "7.29.11", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.29.11.tgz", + "integrity": "sha512-WCsemW40Cpc6gouC1SrY6PBaZ+oLRlEVY9XBvZBI7il/HyUrb2nJ505wE1MHEFyDZNnrWDEuy4jL50WVHfTTSQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.29.11", + "@babel/helper-validator-identifier": "^7.29.7" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@cloudflare/workerd-darwin-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-64/-/workerd-darwin-64-1.20260730.1.tgz", + "integrity": "sha512-+MBHmPaiTe2KajryW0T24rZvWFxb41hD3d8anNzQqHzft6vSEb18+sp0znSwxgij7ApPhSM1+vhkNg4f3YMguA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-darwin-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-darwin-arm64/-/workerd-darwin-arm64-1.20260730.1.tgz", + "integrity": "sha512-SBHKntPkKvNPgaCrTe99xC1CAl8ygJDzlYfK0LbuJ1muKadIw35WnhO0wu894fKBtllsVQdNzDLee+cm0ppLSQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-linux-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-64/-/workerd-linux-64-1.20260730.1.tgz", + "integrity": "sha512-ouyPOSMbiKPeSwUJUvxtMcxGAXs2J4aPE4T5ABIYX5ClcQx5j5bbHTmnqOQEY8sAuLTPjH7dY+iB6UI5ISlwwA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-linux-arm64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-linux-arm64/-/workerd-linux-arm64-1.20260730.1.tgz", + "integrity": "sha512-YQ+Mi78U3TPdgBPtwq+Sm6rJU+Ihl2y0pjYtuuKkdmUbYzL7oLR6Xqq9wljhasnuCFICssDJaqhMep5WizYoEQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cloudflare/workerd-windows-64": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/@cloudflare/workerd-windows-64/-/workerd-windows-64-1.20260730.1.tgz", + "integrity": "sha512-27fAN+vUECW1oYVc1KOcHYpkL8COM2Uxtxql7TL595kxbjoqS5yckw7NLz7bTf2pALFCZWjqXDjZGJ/xbG4ZKQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16" + } + }, + "node_modules/@cspotcode/source-map-support": { + "version": "0.8.1", + "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz", + "integrity": "sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/trace-mapping": "0.3.9" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/@emnapi/runtime": { + "version": "1.11.3", + "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz", + "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "tslib": "^2.4.0" + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.2.tgz", + "integrity": "sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.2.tgz", + "integrity": "sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.2.tgz", + "integrity": "sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.2.tgz", + "integrity": "sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.2.tgz", + "integrity": "sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.2.tgz", + "integrity": "sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.2.tgz", + "integrity": "sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.2.tgz", + "integrity": "sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.2.tgz", + "integrity": "sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.2.tgz", + "integrity": "sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.2.tgz", + "integrity": "sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.2.tgz", + "integrity": "sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.2.tgz", + "integrity": "sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.2.tgz", + "integrity": "sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.2.tgz", + "integrity": "sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.2.tgz", + "integrity": "sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.2.tgz", + "integrity": "sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.2.tgz", + "integrity": "sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.2.tgz", + "integrity": "sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.2.tgz", + "integrity": "sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.2.tgz", + "integrity": "sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/openharmony-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.2.tgz", + "integrity": "sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openharmony" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.2.tgz", + "integrity": "sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.2.tgz", + "integrity": "sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.2.tgz", + "integrity": "sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.2.tgz", + "integrity": "sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=18" + } + }, + "node_modules/@img/colour": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz", + "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + } + }, + "node_modules/@img/sharp-darwin-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.35.5.tgz", + "integrity": "sha512-QRUlFQ0WxvdWyqqG/WtI3iupfD5rBzmCHXSdPsY91sAtVtTo7Q4cb6zOccZ3gqEqkr0f1As1ehLqmEpDsRf+lg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-darwin-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.35.5.tgz", + "integrity": "sha512-+BR255RhDlpygUpOc/Jdt1nT6DQ3XG/ERo5wbcdOf5Q320dKtPCKPLR1LJs9VGXRaMa8l1uUa0tkCNOXiAxZUw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-darwin-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-freebsd-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-freebsd-wasm32/-/sharp-freebsd-wasm32-0.35.5.tgz", + "integrity": "sha512-Y/z91nEZ4uIBX5X3nfTovjU9lHNKFYbL2lpHCLVNmXQK03VIZvXBBt0KxbPGp2SdGSF+2mQU4e+hQaWOt86iAw==", + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-darwin-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.3.4.tgz", + "integrity": "sha512-5R89nBYiRdUlSWJxPhO+GVtaXzXSxKnRu/xqMn3KTA3L9EB9Oy/P+Nn2f2vlhPuUdy/Zusb2DarbyTpGCfEDuw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-darwin-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.3.4.tgz", + "integrity": "sha512-iR2OKH80yi0U+dUplyh3/xdpFvps6YkCwsXenIJxqxR1v9o+xtKTGbS9H7cps+2Vxjc8B1j96p75NmTGjIhtpQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "darwin" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.3.4.tgz", + "integrity": "sha512-LmRtTsOHuvM2+wlO2Db37dx5MiZhB0FvSunciw48YjdOkZz9KAiRbm8ujeMOA1INqmei5NapFxYEK1D1ZSidmw==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.3.4.tgz", + "integrity": "sha512-Y3dgX/6lE2QhQb+Gxy0WZxfg9MEm/JBjamZpS2IklP7xIQoKN4hzAm7KcMVGtaVDt3neE9OKBC7vAfonA/Lr1A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-ppc64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-ppc64/-/sharp-libvips-linux-ppc64-1.3.4.tgz", + "integrity": "sha512-Le6boB8Tai0Nis+gIxIpKx68UDVVIqdR8Tin5Yf1z2LJJQLDJvCDRqRu+jC2qCoD+eIomonmOwB4smBRxfVpYQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-riscv64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-riscv64/-/sharp-libvips-linux-riscv64-1.3.4.tgz", + "integrity": "sha512-aHkkIEHPRdQEegJN20MLmGtxYD9R2wQr3Cwpddnu5+YKMt6Uzax7S9h5gpZTo8wyrGuZSlfQ63OevL5mTyOC7Q==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-s390x": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-s390x/-/sharp-libvips-linux-s390x-1.3.4.tgz", + "integrity": "sha512-ra/mB6MikESDUO7Yg+Mi95bFBb9GsObURuhnOv3OqknjGe9sZrG8tCe9q0xSIGrtLgvgw0gKnFWcK4blSgQOuQ==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linux-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.3.4.tgz", + "integrity": "sha512-GJ//SSXbnwSDes02umB3nDJLFcQzw8a18V8fyhqr6tV515tOEMdImjjxj1AoafMRz56F3PHgftnj1QEKSU1zkw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-arm64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.3.4.tgz", + "integrity": "sha512-hvulFwtjUcagsis6BBxHwGFwWoNZjgYmULGVrZcyfNbjA8hKILbRxGg15/7w5HDyXHXUos/j6baAWqnCyQ2DWA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-libvips-linuxmusl-x64": { + "version": "1.3.4", + "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.3.4.tgz", + "integrity": "sha512-6zXKeE/p39I1AmA3cJG35eyBGNqNddLnUXjhwBnsGjFPWqf5VKkDBEqaEkPDoTEtkxwi2vv8Tcr2mDyP4So7Fg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "LGPL-3.0-or-later", + "optional": true, + "os": [ + "linux" + ], + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-linux-arm": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.35.5.tgz", + "integrity": "sha512-LEaXK2WdXVK5ykcw0buWyPMsmLLL2vpHLD6yrNSW+JGEL3BZPA4tpKN6iaMc4AxTTAoaX/sU1rOL51lcIz48ZQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.35.5.tgz", + "integrity": "sha512-LYVx5JTsOM2CBzmxreh+nl64/3H6Xb09iSLknqH47z2T2DFFxDeFLP5y4dJwe6H7uGQlHPyEEtIqyo3DYsRwdQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-ppc64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-ppc64/-/sharp-linux-ppc64-0.35.5.tgz", + "integrity": "sha512-QVxAAq8evVRI9ia2vqgwrmWucn5Dfv+JdWzj75pD8omHLPSP7f8p20O8jxzjCcuCEQEOtYOZUmX1hkiZ0kdevA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-ppc64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-riscv64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-riscv64/-/sharp-linux-riscv64-0.35.5.tgz", + "integrity": "sha512-LtdreXguaavKODPIfzJ4kffx7UNt1omwtK0rch4EBbbSTXPnxWmYSayXdLJw0fJzQ97kHt1gL/yh4tvU+nCyRQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-riscv64": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-s390x": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-s390x/-/sharp-linux-s390x-0.35.5.tgz", + "integrity": "sha512-UZasTOFiYzotTsGOCu42BfUzP6Tu6Do/947iRm1RsLKvlllxwGcn4RN27LibGWceix4Y+Pmw3jsnTcCQIgWjqA==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-s390x": "1.3.4" + } + }, + "node_modules/@img/sharp-linux-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.35.5.tgz", + "integrity": "sha512-SxFtLTeJInhAA9Q836kux2vZNeOBQEx658qvbboZScr0wIARym3IcGmW7KpVD5sbVg0Ojy+udFQdayYIZyoNog==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linux-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-linuxmusl-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.35.5.tgz", + "integrity": "sha512-9HbMclmI1zlNkFRs3z9/eBtDjfD0sGlrX1z6b1qwmiFY5ElDLh4BC0LPBdVp7z1DXFiKlIcznf+ZlsuZzLxQqg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4" + } + }, + "node_modules/@img/sharp-linuxmusl-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.35.5.tgz", + "integrity": "sha512-4KOphqB035HrVdqLZfCgMzzERrQkkzOwRhl4OAkRO1YCldbaFjySXMaK534Mo0V+LndnlJk+sbUyLeU0ULyD1A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-libvips-linuxmusl-x64": "1.3.4" + } + }, + "node_modules/@img/sharp-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-wasm32/-/sharp-wasm32-0.35.5.tgz", + "integrity": "sha512-Ptsga1su4tQx+LLF1ECS9U6nz5kmrXKo6XVbtR48Ke3ZRxxgaWBu7IDtEe1quo8hiupwm6WFqxVlXaSf7IINGQ==", + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later AND MIT", + "optional": true, + "dependencies": { + "@emnapi/runtime": "^1.11.3" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-webcontainers-wasm32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-webcontainers-wasm32/-/sharp-webcontainers-wasm32-0.35.5.tgz", + "integrity": "sha512-hfhF/FmoQyTUkA0bIKFOtw536BQSeBMe6BF6QyWlrPxT754+TFLaZ7sKKTfvvM0yJgKgaYTwnFCIZ/GuDw5SUA==", + "cpu": [ + "wasm32" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "dependencies": { + "@img/sharp-wasm32": "0.35.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-arm64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.35.5.tgz", + "integrity": "sha512-X4t7g+7ZA5DKblCBEXGjUqqemj4vczING/5viFwAL8h4N3qYeyjwdCvRLHi4EdOUI+2Z7UFlp1VM+p/AuEtm6Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-ia32": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-ia32/-/sharp-win32-ia32-0.35.5.tgz", + "integrity": "sha512-5Zm82LoBc43nhwNybZlG7Y1KO//Zhsn306fQl29ZOuStHLGTo3BWL83q3cznX0poxSAMuYL1On/BHBxkBeKr6A==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": "^20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@img/sharp-win32-x64": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.35.5.tgz", + "integrity": "sha512-x76eH0vEiHlcMQu8Y8IenntaACtddpT6W0wmXtWrnKcnKI7ME5DdgqhAD6SEWOEl1v2zDvkZDhFA9KnURwpfqg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0 AND LGPL-3.0-or-later", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.6.0", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.6.0.tgz", + "integrity": "sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.9", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.9.tgz", + "integrity": "sha512-3Belt6tdc8bPgAtbcmdtNJlirVoTmEb5e2gC94PnkwEW9jI6CAHUeoG85tjWP5WquqfavoMtMwiG4P926ZKKuQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.0.3", + "@jridgewell/sourcemap-codec": "^1.4.10" + } + }, + "node_modules/@metaharness/darwin": { + "version": "0.13.0", + "resolved": "https://registry.npmjs.org/@metaharness/darwin/-/darwin-0.13.0.tgz", + "integrity": "sha512-L3SrQii70erHVDmo1qx0875IRpVujk86zAO7sxtSVChWCgAjabEmmYRYt72D1VekfUCbSWCgZKIktqUxVAKCFA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.29.13" + }, + "bin": { + "metaharness-darwin": "dist/cli.js" + }, + "engines": { + "node": ">=20.0.0" + } + }, + "node_modules/@poppinss/colors": { + "version": "4.1.6", + "resolved": "https://registry.npmjs.org/@poppinss/colors/-/colors-4.1.6.tgz", + "integrity": "sha512-H9xkIdFswbS8n1d6vmRd8+c10t2Qe+rZITbbDHHkQixH5+2x1FDGmi/0K+WgWiqQFKPSlIYB7jlH6Kpfn6Fleg==", + "dev": true, + "license": "MIT", + "dependencies": { + "kleur": "^4.1.5" + } + }, + "node_modules/@poppinss/dumper": { + "version": "0.6.5", + "resolved": "https://registry.npmjs.org/@poppinss/dumper/-/dumper-0.6.5.tgz", + "integrity": "sha512-NBdYIb90J7LfOI32dOewKI1r7wnkiH6m920puQ3qHUeZkxNkQiFnXVWoE6YtFSv6QOiPPf7ys6i+HWWecDz7sw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@sindresorhus/is": "^7.0.2", + "supports-color": "^10.0.0" + } + }, + "node_modules/@poppinss/exception": { + "version": "1.2.3", + "resolved": "https://registry.npmjs.org/@poppinss/exception/-/exception-1.2.3.tgz", + "integrity": "sha512-dCED+QRChTVatE9ibtoaxc+WkdzOSjYTKi/+uacHWIsfodVfpsueo3+DKpgU5Px8qXjgmXkSvhXvSCz3fnP9lw==", + "dev": true, + "license": "MIT" + }, + "node_modules/@sindresorhus/is": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz", + "integrity": "sha512-P1Cz1dWaFfR4IR+U13mqqiGsLFf1KbayybWwdd2vfctdV6hDpUkgCY0nKOLLTMSoRd/jJNjtbqzf13K8DCCXQw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sindresorhus/is?sponsor=1" + } + }, + "node_modules/@speed-highlight/core": { + "version": "1.2.24", + "resolved": "https://registry.npmjs.org/@speed-highlight/core/-/core-1.2.24.tgz", + "integrity": "sha512-qeW2e1l78afw8VhRPfPQ1Gjj+KU5XFQ/OFV5ti6eTa9bruO7mJyZtA4vw0ofqmA3tKCkROE9xLk3VZoeRc98nw==", + "dev": true, + "license": "CC0-1.0" + }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/detect-libc": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz", + "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==", + "dev": true, + "license": "Apache-2.0", + "engines": { + "node": ">=8" + } + }, + "node_modules/error-stack-parser-es": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/error-stack-parser-es/-/error-stack-parser-es-1.0.5.tgz", + "integrity": "sha512-5qucVt2XcuGMcEGgWI7i+yZpmpByQ8J1lHhcL7PwqCwu9FPP3VUXzT4ltHe5i2z9dePwEHcDVOAfSnHsOlCXRA==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/esbuild": { + "version": "0.28.2", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.2.tgz", + "integrity": "sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.28.2", + "@esbuild/android-arm": "0.28.2", + "@esbuild/android-arm64": "0.28.2", + "@esbuild/android-x64": "0.28.2", + "@esbuild/darwin-arm64": "0.28.2", + "@esbuild/darwin-x64": "0.28.2", + "@esbuild/freebsd-arm64": "0.28.2", + "@esbuild/freebsd-x64": "0.28.2", + "@esbuild/linux-arm": "0.28.2", + "@esbuild/linux-arm64": "0.28.2", + "@esbuild/linux-ia32": "0.28.2", + "@esbuild/linux-loong64": "0.28.2", + "@esbuild/linux-mips64el": "0.28.2", + "@esbuild/linux-ppc64": "0.28.2", + "@esbuild/linux-riscv64": "0.28.2", + "@esbuild/linux-s390x": "0.28.2", + "@esbuild/linux-x64": "0.28.2", + "@esbuild/netbsd-arm64": "0.28.2", + "@esbuild/netbsd-x64": "0.28.2", + "@esbuild/openbsd-arm64": "0.28.2", + "@esbuild/openbsd-x64": "0.28.2", + "@esbuild/openharmony-arm64": "0.28.2", + "@esbuild/sunos-x64": "0.28.2", + "@esbuild/win32-arm64": "0.28.2", + "@esbuild/win32-ia32": "0.28.2", + "@esbuild/win32-x64": "0.28.2" + } + }, + "node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/miniflare": { + "version": "4.20260730.0", + "resolved": "https://registry.npmjs.org/miniflare/-/miniflare-4.20260730.0.tgz", + "integrity": "sha512-1Z9SB9r/o//80UA02Re3QhtcecSHAyAjf5EcKBfQVlQrCg7Miy79hl2PvtkwFLIaJ5rcrOPdDcRr577okwZPsg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@cspotcode/source-map-support": "0.8.1", + "sharp": "0.35.2", + "undici": "7.28.0", + "workerd": "1.20260730.1", + "ws": "8.21.0", + "youch": "4.1.0-beta.10" + }, + "bin": { + "miniflare": "bootstrap.js" + }, + "engines": { + "node": ">=22.0.0" + } + }, + "node_modules/semver": { + "version": "7.8.6", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.8.6.tgz", + "integrity": "sha512-9lpSSU4Mly3mrtruwLs1eLK6+gzbzqeBFwRNjIjE+9LuDpWdYctrQlQ3ej1Ilgi7gknpsTRnPoLP8DpCHqHIJw==", + "dev": true, + "license": "ISC", + "bin": { + "semver": "bin/semver.js" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/sharp": { + "version": "0.35.5", + "resolved": "https://registry.npmjs.org/sharp/-/sharp-0.35.5.tgz", + "integrity": "sha512-Ywn4OnzGukp7CDMrp08RQ50YKmuwG47brZgIVPTvBaaAfQlRlygrRqSrxdCiL9M+LlzLBiJ68IR1QqvzHyjC7g==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@img/colour": "^1.1.0", + "detect-libc": "^2.1.2", + "semver": "^7.8.5" + }, + "engines": { + "node": ">=20.9.0" + }, + "funding": { + "url": "https://opencollective.com/libvips" + }, + "optionalDependencies": { + "@img/sharp-darwin-arm64": "0.35.5", + "@img/sharp-darwin-x64": "0.35.5", + "@img/sharp-freebsd-wasm32": "0.35.5", + "@img/sharp-libvips-darwin-arm64": "1.3.4", + "@img/sharp-libvips-darwin-x64": "1.3.4", + "@img/sharp-libvips-linux-arm": "1.3.4", + "@img/sharp-libvips-linux-arm64": "1.3.4", + "@img/sharp-libvips-linux-ppc64": "1.3.4", + "@img/sharp-libvips-linux-riscv64": "1.3.4", + "@img/sharp-libvips-linux-s390x": "1.3.4", + "@img/sharp-libvips-linux-x64": "1.3.4", + "@img/sharp-libvips-linuxmusl-arm64": "1.3.4", + "@img/sharp-libvips-linuxmusl-x64": "1.3.4", + "@img/sharp-linux-arm": "0.35.5", + "@img/sharp-linux-arm64": "0.35.5", + "@img/sharp-linux-ppc64": "0.35.5", + "@img/sharp-linux-riscv64": "0.35.5", + "@img/sharp-linux-s390x": "0.35.5", + "@img/sharp-linux-x64": "0.35.5", + "@img/sharp-linuxmusl-arm64": "0.35.5", + "@img/sharp-linuxmusl-x64": "0.35.5", + "@img/sharp-webcontainers-wasm32": "0.35.5", + "@img/sharp-win32-arm64": "0.35.5", + "@img/sharp-win32-ia32": "0.35.5", + "@img/sharp-win32-x64": "0.35.5" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + } + } + }, + "node_modules/supports-color": { + "version": "10.2.2", + "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-10.2.2.tgz", + "integrity": "sha512-SS+jx45GF1QjgEXQx4NJZV9ImqmO2NPz5FNsIHrsDjh2YsHnawpan7SNQ1o8NuhrbHZy9AZhIoCUiCeaW/C80g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/chalk/supports-color?sponsor=1" + } + }, + "node_modules/tslib": { + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.9.1.tgz", + "integrity": "sha512-a4Ux9VKuIMHsOS7ENbEq6hK2ZGYIT27Rtl0E4eD9KqwxhKiQeMZE/9xb3IdYwWaSOyIBQLExhQgXDTYoiCxnWA==", + "dev": true, + "license": "0BSD", + "optional": true + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici": { + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=20.18.1" + } + }, + "node_modules/workerd": { + "version": "1.20260730.1", + "resolved": "https://registry.npmjs.org/workerd/-/workerd-1.20260730.1.tgz", + "integrity": "sha512-zmfNIjwYSWFY5chGBOjWtH3xAE7p97FTC6vR4Ep98290ho6AeAR/NVcBD274YCLEUYzqm8yxdtZlxMybU8a3jA==", + "dev": true, + "hasInstallScript": true, + "license": "Apache-2.0", + "bin": { + "workerd": "bin/workerd" + }, + "engines": { + "node": ">=16" + }, + "optionalDependencies": { + "@cloudflare/workerd-darwin-64": "1.20260730.1", + "@cloudflare/workerd-darwin-arm64": "1.20260730.1", + "@cloudflare/workerd-linux-64": "1.20260730.1", + "@cloudflare/workerd-linux-arm64": "1.20260730.1", + "@cloudflare/workerd-windows-64": "1.20260730.1" + } + }, + "node_modules/ws": { + "version": "8.21.0", + "resolved": "https://registry.npmjs.org/ws/-/ws-8.21.0.tgz", + "integrity": "sha512-Vsp28b7DRcimFQvrqu2Wek3z1iYxDCWqHYB8Qsnk/S4RfaCQzPGPyBNuVjJV3cd6UiKtUtp6sNM77gWvzcCH+g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10.0.0" + }, + "peerDependencies": { + "bufferutil": "^4.0.1", + "utf-8-validate": ">=5.0.2" + }, + "peerDependenciesMeta": { + "bufferutil": { + "optional": true + }, + "utf-8-validate": { + "optional": true + } + } + }, + "node_modules/youch": { + "version": "4.1.0-beta.10", + "resolved": "https://registry.npmjs.org/youch/-/youch-4.1.0-beta.10.tgz", + "integrity": "sha512-rLfVLB4FgQneDr0dv1oddCVZmKjcJ6yX6mS4pU82Mq/Dt9a3cLZQ62pDBL4AUO+uVrCvtWz3ZFUL2HFAFJ/BXQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/colors": "^4.1.5", + "@poppinss/dumper": "^0.6.4", + "@speed-highlight/core": "^1.2.7", + "cookie": "^1.0.2", + "youch-core": "^0.3.3" + } + }, + "node_modules/youch-core": { + "version": "0.3.3", + "resolved": "https://registry.npmjs.org/youch-core/-/youch-core-0.3.3.tgz", + "integrity": "sha512-ho7XuGjLaJ2hWHoK8yFnsUGy2Y5uDpqSTq1FkHLK4/oqKtyUU1AFbOOxY4IpC9f0fTLjwYbslUz0Po5BpD1wrA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@poppinss/exception": "^1.2.2", + "error-stack-parser-es": "^1.0.5" + } + } + } +} diff --git a/npm/packages/e-means/package.json b/npm/packages/e-means/package.json new file mode 100644 index 0000000000..8dcf9ca38f --- /dev/null +++ b/npm/packages/e-means/package.json @@ -0,0 +1,120 @@ +{ + "name": "@ruvector/e-means", + "version": "0.1.0", + "description": "Deterministic e-means (EMA k-means) clustering for vectors: Rust core compiled to WebAssembly, with PQ codebook, IVF, MetaHarness tuning and Cloudflare Worker helpers", + "type": "module", + "main": "./e-means.mjs", + "types": "./e-means.d.ts", + "exports": { + ".": { + "types": "./e-means.d.ts", + "import": "./e-means.mjs" + }, + "./runtime": { + "types": "./runtime.d.ts", + "import": "./runtime.mjs" + }, + "./quantization": { + "types": "./integrations/quantization.d.ts", + "import": "./integrations/quantization.mjs" + }, + "./ivf": { + "types": "./integrations/ivf.d.ts", + "import": "./integrations/ivf.mjs" + }, + "./metaharness": { + "types": "./integrations/metaharness.d.ts", + "import": "./integrations/metaharness.mjs" + }, + "./cloudflare": { + "types": "./integrations/cloudflare.d.ts", + "import": "./integrations/cloudflare.mjs" + }, + "./cloudflare/build": { + "types": "./examples/cloudflare/build.d.ts", + "import": "./examples/cloudflare/build.mjs" + }, + "./wasm": { + "types": "./wasm-module.d.ts", + "default": "./wasm/ruvector_e_means_bg.wasm" + } + }, + "files": [ + "e-means.mjs", + "e-means.d.ts", + "runtime.mjs", + "runtime.d.ts", + "wasm-module.d.ts", + "integrations/", + "examples/cloudflare/", + "examples/metaharness.mjs", + "wasm/", + "scripts/check-artifact.mjs", + "README.md", + "LICENSE" + ], + "scripts": { + "build": "node scripts/build.mjs", + "test": "node --test test/*.test.mjs", + "test:consumer": "node test/packed-consumer.mjs", + "test:ecosystem": "node test/ecosystem-consumers.mjs", + "test:cloudflare": "node --test test/cloudflare*.test.mjs", + "build:cloudflare": "node examples/cloudflare/build.mjs", + "prepack": "node scripts/check-artifact.mjs", + "typecheck": "tsc --noEmit -p test/tsconfig.json", + "test:browser": "node test/browser-consumer.mjs", + "benchmark": "node --expose-gc test/benchmark.mjs" + }, + "engines": { + "node": ">=20.0.0" + }, + "license": "MIT", + "homepage": "https://ruv.io", + "bugs": { + "url": "https://github.com/ruvnet/ruvector/issues" + }, + "repository": { + "type": "git", + "url": "https://github.com/ruvnet/ruvector.git", + "directory": "npm/packages/e-means" + }, + "publishConfig": { + "access": "public" + }, + "keywords": [ + "clustering", + "e-means", + "k-means", + "ema", + "webassembly", + "wasm", + "rust", + "product-quantization", + "ivf", + "vector-search", + "codebook", + "embeddings", + "cloudflare-workers", + "ruvector" + ], + "devDependencies": { + "typescript": "5.9.3", + "@metaharness/darwin": "0.13.0", + "esbuild": "0.28.2", + "miniflare": "4.20260730.0" + }, + "peerDependencies": { + "@metaharness/darwin": "0.13.0 || 0.13.1" + }, + "peerDependenciesMeta": { + "@metaharness/darwin": { + "optional": true + } + }, + "overrides": { + "miniflare": { + "sharp": "0.35.5", + "undici": "7.30.1" + } + } +} diff --git a/npm/packages/e-means/runtime.d.ts b/npm/packages/e-means/runtime.d.ts new file mode 100644 index 0000000000..ab711476c2 --- /dev/null +++ b/npm/packages/e-means/runtime.d.ts @@ -0,0 +1,4 @@ +export { fit, predict } from '@ruvector/e-means'; +export type { EMeansOptions, EMeansModel } from '@ruvector/e-means'; +/** No filesystem/default URL loader. Supply bytes or a precompiled module. */ +export function init(source: BufferSource | WebAssembly.Module): Promise; diff --git a/npm/packages/e-means/runtime.mjs b/npm/packages/e-means/runtime.mjs new file mode 100644 index 0000000000..d79984c862 --- /dev/null +++ b/npm/packages/e-means/runtime.mjs @@ -0,0 +1,96 @@ +import initWasm, { fitTyped, predictFlat } from './wasm/ruvector_e_means.js'; + +let initialized = false; +let initialization; +const maxU32 = 0xffff_ffff; + +/** Initialize from caller-supplied bytes or a precompiled module; no Node loader is reachable. */ +export async function init(source) { + if (initialized) return; + if (!initialization) { + initialization = (async () => { + if (source === undefined) throw new TypeError('runtime init requires WASM bytes or a precompiled module'); + await initWasm({ module_or_path: source }); + initialized = true; + })().catch((error) => { + initialization = undefined; + const message = typeof error?.message === 'string' ? error.message : String(error); + throw new Error(`Could not initialize @ruvector/e-means: ${message}`, { cause: error }); + }); + } + await initialization; +} + +function ready() { + if (!initialized) throw new Error('Call and await init() before using @ruvector/e-means'); +} + +function positiveInteger(value, name) { + if (!Number.isInteger(value) || value <= 0 || value > maxU32) { + throw new RangeError(`${name} must be an integer between 1 and ${maxU32}`); + } +} + +function vectors(data, dimensions, name, allowEmpty = false) { + if (!(data instanceof Float32Array)) throw new TypeError(`${name} must be a Float32Array`); + positiveInteger(dimensions, 'dimensions'); + if ((!allowEmpty && data.length === 0) || data.length % dimensions !== 0) { + throw new RangeError(`${name} must contain complete ${dimensions}-dimensional vectors`); + } + for (let index = 0; index < data.length; index++) { + if (!Number.isFinite(data[index])) throw new RangeError(`${name} must contain only finite values`); + } +} + +/** Cluster flat row-major f32 vectors using the e-means Rust implementation. */ +export function fit(data, dimensions, options) { + ready(); + vectors(data, dimensions, 'data'); + if (options === null || typeof options !== 'object' || Array.isArray(options)) { + throw new TypeError('options must be an object with clusters'); + } + const allowed = ['clusters', 'epochs', 'batchSize', 'peakStep', 'seed', 'finalization']; + for (const key of Object.keys(options)) { + if (!allowed.includes(key)) throw new TypeError(`Unknown option: ${key}`); + } + positiveInteger(options.clusters, 'clusters'); + if (options.clusters > data.length / dimensions) throw new RangeError('clusters cannot exceed the number of vectors'); + if (options.epochs !== undefined) positiveInteger(options.epochs, 'epochs'); + if (options.batchSize !== undefined) positiveInteger(options.batchSize, 'batchSize'); + if (options.peakStep !== undefined && + (typeof options.peakStep !== 'number' || !Number.isFinite(options.peakStep) || options.peakStep <= 0 || options.peakStep > 1)) { + throw new RangeError('peakStep must be a finite number in (0, 1]'); + } + if (options.seed !== undefined && (!Number.isSafeInteger(options.seed) || options.seed < 0)) { + throw new RangeError('seed must be a non-negative safe integer'); + } + if (options.finalization !== undefined && !['lastEpochMean', 'ema'].includes(options.finalization)) { + throw new RangeError('finalization must be lastEpochMean or ema'); + } + // Copy supported options explicitly: inherited properties and toJSON do not become Rust configuration. + const config = { clusters: options.clusters }; + for (const key of allowed.slice(1)) if (options[key] !== undefined) config[key] = options[key]; + const model = fitTyped(data, dimensions, JSON.stringify(config)); + try { + return { + centroids: model.takeCentroids(), + assignments: model.takeAssignments(), + dimensions: model.dimensions, + mse: model.mse, + batchSize: model.batchSize, + peakStep: model.peakStep, + updates: model.updates, + revivedClusters: model.revivedClusters, + }; + } finally { + model.free(); + } +} + +/** Assign vectors to their nearest centroid using squared Euclidean distance. */ +export function predict(data, dimensions, centroids) { + ready(); + vectors(data, dimensions, 'data', true); + vectors(centroids, dimensions, 'centroids'); + return predictFlat(data, dimensions, centroids); +} diff --git a/npm/packages/e-means/scripts/build.mjs b/npm/packages/e-means/scripts/build.mjs new file mode 100644 index 0000000000..4f907425eb --- /dev/null +++ b/npm/packages/e-means/scripts/build.mjs @@ -0,0 +1,23 @@ +import { spawnSync } from 'node:child_process'; +import { fileURLToPath } from 'node:url'; +import { mkdir } from 'node:fs/promises'; + +const root = fileURLToPath(new URL('../../../../', import.meta.url)); +const manifest = fileURLToPath(new URL('../../../../crates/ruvector-e-means/Cargo.toml', import.meta.url)); +const target = fileURLToPath(new URL('../../../../target/e-means-wasm/', import.meta.url)); +const output = fileURLToPath(new URL('../wasm/', import.meta.url)); + +function run(command, args) { + const result = spawnSync(command, args, { cwd: root, stdio: 'inherit' }); + if (result.error) throw result.error; + if (result.status !== 0) throw new Error(`${command} exited ${result.status}`); +} + +const version = spawnSync('wasm-bindgen', ['--version'], { encoding: 'utf8' }); +if (version.error || version.status !== 0 || version.stdout.trim() !== 'wasm-bindgen 0.2.125') { + throw new Error('Install wasm-bindgen-cli@0.2.125 and the wasm32-unknown-unknown Rust target before building'); +} +await mkdir(output, { recursive: true }); +run('cargo', ['build', '--locked', '--manifest-path', manifest, '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', target]); +run('wasm-bindgen', [`${target}/wasm32-unknown-unknown/release/ruvector_e_means.wasm`, '--target', 'web', '--out-dir', output, '--out-name', 'ruvector_e_means']); +run(process.execPath, [fileURLToPath(new URL('./check-artifact.mjs', import.meta.url))]); diff --git a/npm/packages/e-means/scripts/check-artifact.mjs b/npm/packages/e-means/scripts/check-artifact.mjs new file mode 100644 index 0000000000..d87a846a50 --- /dev/null +++ b/npm/packages/e-means/scripts/check-artifact.mjs @@ -0,0 +1,11 @@ +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { init, fit } from '../e-means.mjs'; + +const bytes = await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url)); +assert.deepEqual([...bytes.subarray(0, 4)], [0, 97, 115, 109], 'missing or invalid WebAssembly artifact'); +await init(bytes); +const model = fit(new Float32Array([0, 2]), 1, { clusters: 1, epochs: 1 }); +assert.equal(model.centroids[0], 1, 'bundled WASM must run the Rust mean finalizer'); +assert.equal(model.mse, 1); +console.error('Bundled e-means WASM verified'); diff --git a/npm/packages/e-means/test/benchmark.mjs b/npm/packages/e-means/test/benchmark.mjs new file mode 100644 index 0000000000..3a572d30ba --- /dev/null +++ b/npm/packages/e-means/test/benchmark.mjs @@ -0,0 +1,111 @@ +import assert from 'node:assert/strict'; +import { cpus } from 'node:os'; +import { resolve } from 'node:path'; +import { pathToFileURL } from 'node:url'; +import { init, fit, predict } from '../e-means.mjs'; +import { fitJson, fitTyped } from '../wasm/ruvector_e_means.js'; + +let baselinePath, repeats = 7; +for (let i = 2; i < process.argv.length; i++) { + const argument = process.argv[i]; + if (argument === '--baseline') baselinePath = process.argv[++i]; + else if (argument === '--repeats') repeats = Number(process.argv[++i]); + else throw new Error(`Unknown benchmark argument: ${argument}`); +} +assert.ok(Number.isInteger(repeats) && repeats >= 3 && repeats <= 31, '--repeats must be in 3..31'); +await init(); +let baseline; +if (baselinePath) { + baseline = await import(pathToFileURL(resolve(baselinePath, 'e-means.mjs')).href); + await baseline.init(); +} + +function materialize(handle) { + try { + return { + centroids: handle.takeCentroids(), assignments: handle.takeAssignments(), + dimensions: handle.dimensions, mse: handle.mse, batchSize: handle.batchSize, + peakStep: handle.peakStep, updates: handle.updates, revivedClusters: handle.revivedClusters, + }; + } finally { + handle.free(); + } +} + +function median(values) { + return [...values].sort((a, b) => a - b)[Math.floor(values.length / 2)]; +} + +// Interleave variants and rotate their order to reduce ordering/thermal bias. +// GC is outside the timed region; each result is fully materialized and consumed. +let checksum = 0; +function measure(variants) { + const entries = Object.entries(variants), timings = new Map(entries.map(([name]) => [name, []])); + for (const [, operation] of entries) for (let i = 0; i < 2; i++) operation(); + for (let round = 0; round < repeats; round++) { + for (let i = 0; i < entries.length; i++) { + const [name, operation] = entries[(i + round) % entries.length]; + globalThis.gc?.(); + const start = performance.now(); + const result = operation(); + timings.get(name).push(performance.now() - start); + checksum += result instanceof Uint32Array ? result.length + (result[0] || 0) : result.mse + result.assignments.length; + } + } + return Object.fromEntries([...timings].map(([name, samples]) => [name, median(samples)])); +} + +function compareResults(a, b) { + assert.equal(a.assignments.length, b.assignments.length); + assert.equal(a.centroids.length, b.centroids.length); + let labelDifferences = 0, centroidMaxAbsDifference = 0; + for (let i = 0; i < a.assignments.length; i++) labelDifferences += Number(a.assignments[i] !== b.assignments[i]); + for (let i = 0; i < a.centroids.length; i++) centroidMaxAbsDifference = Math.max(centroidMaxAbsDifference, Math.abs(a.centroids[i] - b.centroids[i])); + return { labelDifferences, centroidMaxAbsDifference, mseAbsoluteDifference: Math.abs(a.mse - b.mse) }; +} + +const cases = [ + { name: 'large-assignment-result', samples: 1_000_000, dimensions: 1, clusters: 1, epochs: 1, batchSize: 4096 }, + { name: 'embedding-codebook', samples: 8192, dimensions: 64, clusters: 16, epochs: 3, batchSize: 256 }, +]; +const results = []; +for (const scenario of cases) { + const { samples, dimensions, clusters, epochs, batchSize } = scenario; + const data = new Float32Array(samples * dimensions); + for (let row = 0; row < samples; row++) { + for (let column = 0; column < dimensions; column++) { + data[row * dimensions + column] = (row % clusters) * 4 + (column % 7) * 0.1 + ((row * 17 + column * 31) % 97) / 9700; + } + } + const options = { clusters, epochs, batchSize, seed: 42 }, config = JSON.stringify(options); + const optimizedModel = fit(data, dimensions, options); + const jsonResult = JSON.parse(fitJson(data, dimensions, config)); + const jsonModel = { ...jsonResult, centroids: Float32Array.from(jsonResult.centroids), assignments: Uint32Array.from(jsonResult.assignments) }; + assert.deepEqual(optimizedModel, jsonModel, 'same optimized kernel must have identical JSON/typed results'); + const baselineModel = baseline?.fit(data, dimensions, options); + if (baselineModel) assert.deepEqual(optimizedModel, baselineModel, 'optimized fit must preserve baseline outputs on the measured fixture'); + const fitVariants = { optimizedMs: () => fit(data, dimensions, options) }; + if (baseline) fitVariants.baselineMs = () => baseline.fit(data, dimensions, options); + const fitTimes = measure(fitVariants); + if (baseline) fitTimes.speedup = fitTimes.baselineMs / fitTimes.optimizedMs; + + const transport = measure({ + jsonMs: () => { + const model = JSON.parse(fitJson(data, dimensions, config)); + return { ...model, centroids: Float32Array.from(model.centroids), assignments: Uint32Array.from(model.assignments) }; + }, + typedMs: () => materialize(fitTyped(data, dimensions, config)), + }); + transport.speedup = transport.jsonMs / transport.typedMs; + const predictVariants = { optimizedMs: () => predict(data, dimensions, optimizedModel.centroids) }; + if (baseline) predictVariants.baselineMs = () => baseline.predict(data, dimensions, baselineModel.centroids); + const predictTimes = measure(predictVariants); + if (baseline) predictTimes.speedup = predictTimes.baselineMs / predictTimes.optimizedMs; + results.push({ ...scenario, fit: fitTimes, predict: predictTimes, sameKernelTransport: transport, + baselineParity: baselineModel ? compareResults(optimizedModel, baselineModel) : undefined }); +} +console.log(JSON.stringify({ runtime: { node: process.version, platform: process.platform, arch: process.arch, + cpu: cpus()[0]?.model, logicalCpus: cpus().length }, repeats, warmupsPerVariant: 2, + measurement: 'median wall-clock milliseconds, fully materialized results; explicit GC outside timing', + sameKernelTransportMeasurement: 'full fit plus output materialization using one optimized WASM kernel; difference includes JSON serialization/parsing and array conversion, not a conversion-only timer', + baselinePath: baselinePath ? resolve(baselinePath) : undefined, checksum, cases: results }, null, 2)); diff --git a/npm/packages/e-means/test/browser-consumer.mjs b/npm/packages/e-means/test/browser-consumer.mjs new file mode 100644 index 0000000000..0d77e9f57e --- /dev/null +++ b/npm/packages/e-means/test/browser-consumer.mjs @@ -0,0 +1,91 @@ +import assert from 'node:assert/strict'; +import { spawn } from 'node:child_process'; +import { createServer } from 'node:http'; +import { mkdtemp, readFile, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; + +const page = ``; + +const routes = new Map([ + ['/e-means.mjs', ['../e-means.mjs', 'application/javascript']], + ['/runtime.mjs', ['../runtime.mjs', 'application/javascript']], + ['/wasm/ruvector_e_means.js', ['../wasm/ruvector_e_means.js', 'application/javascript']], + ['/wasm/ruvector_e_means_bg.wasm', ['../wasm/ruvector_e_means_bg.wasm', 'application/wasm']], +]); +let fetchedWasm = false; +const server = createServer(async (request, response) => { + try { + if (request.url === '/') { + response.writeHead(200, { 'content-type': 'text/html' }); + response.end(page); + return; + } + const route = routes.get(request.url); + if (!route) { + response.writeHead(404); + response.end(); + return; + } + if (request.url.endsWith('.wasm')) fetchedWasm = true; + const bytes = await readFile(new URL(route[0], import.meta.url)); + response.writeHead(200, { 'content-type': route[1] }); + response.end(bytes); + } catch (error) { + response.writeHead(500); + response.end(error.message); + } +}); + +const profile = await mkdtemp(join(tmpdir(), 'e-means-chromium-')); +let browser; +function stopBrowser() { + if (!browser?.pid) return; + try { process.kill(-browser.pid, 'SIGKILL'); } catch (error) { + if (error.code !== 'ESRCH') throw error; + } +} +try { + await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve)); + const chromium = process.env.E_MEANS_CHROMIUM || 'chromium'; + const url = `http://127.0.0.1:${server.address().port}/`; + const result = await new Promise((resolve, reject) => { + const child = browser = spawn(chromium, ['--headless', '--no-sandbox', '--disable-dev-shm-usage', + '--disable-gpu', '--disable-background-networking', '--no-first-run', + `--user-data-dir=${profile}`, '--dump-dom', '--virtual-time-budget=10000', url], + { stdio: ['ignore', 'pipe', 'pipe'], detached: true }); + let stdout = '', stderr = ''; + child.stdout.on('data', (chunk) => { stdout += chunk; }); + child.stderr.on('data', (chunk) => { stderr += chunk; }); + const timer = setTimeout(() => { + stopBrowser(); + reject(new Error(`Chromium browser consumer exceeded 25 seconds\n${stdout}\n${stderr.slice(-2000)}`)); + }, 25_000); + child.once('error', (error) => { clearTimeout(timer); reject(error); }); + child.once('close', (status) => { clearTimeout(timer); resolve({ status, stdout, stderr }); }); + }); + assert.equal(result.status, 0, result.stderr); + assert.match(result.stdout, /data-result="pass"/, result.stdout + '\n' + result.stderr.slice(-1500)); + assert.ok(fetchedWasm, 'browser must fetch the bundled .wasm through default init()'); + console.log('Chromium browser consumer passed: default WASM fetch, fit, predict and numerical oracle'); +} finally { + stopBrowser(); + await new Promise((resolve) => server.close(resolve)); + await rm(profile, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 }); +} diff --git a/npm/packages/e-means/test/cloudflare-storage.test.mjs b/npm/packages/e-means/test/cloudflare-storage.test.mjs new file mode 100644 index 0000000000..90b01c8acb --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-storage.test.mjs @@ -0,0 +1,108 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { persistCodebook, loadCodebook, exportCentroids, CentroidExportError } from '../integrations/cloudflare.mjs'; + +const model = { dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]), assignments: new Uint32Array([0, 1]), mse: 1 }; +function stored(body) { return { size: new TextEncoder().encode(body).length, body: new Response(body).body }; } + +test('R2 binding helpers persist only centroid codebooks and restore independent typed output', async () => { + let written; + const bucket = { async put(key, body, options) { written = { key, body, options }; return {}; }, async get() { return stored(written.body); } }; + const receipt = await persistCodebook(bucket, 'private/codebook.json', model); + assert.equal(receipt.clusters, 2); + const record = JSON.parse(written.body); + assert.deepEqual(Object.keys(record).sort(), ['centroids', 'clusters', 'dimensions', 'schema']); + assert.equal(written.options.httpMetadata.contentType, 'application/json'); + const loaded = await loadCodebook(bucket, 'private/codebook.json'); + assert.deepEqual(loaded.centroids, model.centroids); + loaded.centroids[0] = 99; + assert.equal(model.centroids[0], 1); + assert.equal(await loadCodebook({ get: async () => null }, 'missing'), null); +}); + +test('R2 writes snapshot caller-owned centroid data before the first asynchronous boundary', async () => { + const input = { dimensions: 1, centroids: new Float32Array([3, 7]) }; + let payload; + const promise = persistCodebook({ async put(key, body) { payload = body; await Promise.resolve(); return {}; } }, 'snapshot', input); + input.centroids.fill(100); + await promise; + assert.deepEqual(JSON.parse(payload).centroids, [3, 7]); +}); + +test('centroid validation inspects copied numeric storage even with an overridden iterator', async () => { + const centroids = new Float32Array([1, NaN]); + centroids[Symbol.iterator] = function* () { yield 0; }; + const input = { dimensions: 1, centroids }; + let writes = 0; + await assert.rejects(persistCodebook({ put: async () => { writes++; return {}; } }, 'bad', input), /finite/); + await assert.rejects(exportCentroids({ upsert: async () => { writes++; return { mutationId: 'bad' }; } }, input, { prefix: 'bad' }), /finite/); + assert.equal(writes, 0); +}); + +test('PQ envelopes and accessor schemas cannot be mistaken for full-dimensional codebooks', async () => { + let writes = 0, reads = 0; + const bucket = { put: async () => { writes++; return {}; } }; + const index = { upsert: async () => { writes++; return { mutationId: 'unexpected' }; } }; + const pq = { schema: 'ruvector-e-means-pq-v1', dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]) }; + const accessor = { dimensions: 2, centroids: new Float32Array([1, 2]) }; + Object.defineProperty(accessor, 'schema', { get() { reads++; return 'ruvector.e-means-codebook/1'; } }); + for (const input of [pq, accessor]) { + await assert.rejects(persistCodebook(bucket, 'book', input), /single row-major codebook/); + await assert.rejects(exportCentroids(index, input, { prefix: 'book' }), /single row-major codebook/); + } + assert.equal(writes, 0); + assert.equal(reads, 0); +}); + +test('corrupt, oversized, nonfinite and malformed stored codebooks reject', async () => { + for (const record of [ + { schema: 'other', dimensions: 1, clusters: 1, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 2, clusters: 1, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 2, centroids: [0] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 1, centroids: ['1'] }, + { schema: 'ruvector.e-means-codebook/1', dimensions: 1, clusters: 1, centroids: [1e40] }, + ]) await assert.rejects(loadCodebook({ get: async () => stored(JSON.stringify(record)) }, 'bad')); + await assert.rejects(loadCodebook({ get: async () => ({ size: 10_000_000, body: new Response('x').body }) }, 'large')); + await assert.rejects(persistCodebook({ put: async () => null }, 'failed', model), /acknowledge/); + await assert.rejects(persistCodebook({ put: async () => undefined }, 'failed', model), /acknowledge/); + let writes = 0; + await assert.rejects(persistCodebook({ put: async () => { writes++; } }, 'invalid', { dimensions: 1, centroids: new Float32Array([Infinity]) })); + assert.equal(writes, 0); +}); + +test('Vectorize binding export batches static centroid records and propagates explicit namespace', async () => { + const batches = []; + const index = { async upsert(vectors) { batches.push(structuredClone(vectors)); return { mutationId: `m${batches.length}` }; } }; + const receipt = await exportCentroids(index, { dimensions: 1, centroids: Float32Array.from({ length: 2001 }, (_, i) => i) }, + { prefix: 'codebook', namespace: 'owned-namespace' }); + assert.deepEqual(batches.map(batch => batch.length), [1000, 1000, 1]); + assert.deepEqual(receipt, { submitted: 2001, mutationIds: ['m1', 'm2', 'm3'] }); + assert.deepEqual(batches[2][0], { id: 'codebook:2000', values: [2000], metadata: { cluster: 2000 }, namespace: 'owned-namespace' }); + assert.equal(new Set(batches.flat().map(v => v.id)).size, 2001); +}); + +test('Vectorize validates every record before writes and reports acknowledged batches on failure', async () => { + let calls = 0; + const index = { async upsert() { if (++calls === 2) throw new Error('binding failure'); return { mutationId: 'first' }; } }; + for (const [input, options] of [ + [model, { prefix: '😀'.repeat(16) }], [model, { prefix: 'x', namespace: '😀'.repeat(17) }], + [model, { prefix: 'x', batchSize: 1001 }], + [{ dimensions: 1537, centroids: new Float32Array(1537) }, { prefix: 'x' }], + [{ dimensions: 1, centroids: new Float32Array([NaN]) }, { prefix: 'x' }], + ]) await assert.rejects(exportCentroids(index, input, options)); + assert.equal(calls, 0); + await assert.rejects(exportCentroids(index, { dimensions: 1, centroids: new Float32Array(1001) }, { prefix: 'x' }), error => { + assert.ok(error instanceof CentroidExportError); + assert.equal(error.submitted, 1000); + assert.deepEqual(error.mutationIds, ['first']); + return true; + }); + for (const acknowledgement of [undefined, {}, { mutationId: '' }, { mutationId: 'x'.repeat(257) }]) { + await assert.rejects(exportCentroids({ upsert: async () => acknowledgement }, model, { prefix: 'x' }), error => { + assert.ok(error instanceof CentroidExportError); + assert.equal(error.submitted, 0); + assert.deepEqual(error.mutationIds, []); + return true; + }); + } +}); diff --git a/npm/packages/e-means/test/cloudflare-tsconfig.json b/npm/packages/e-means/test/cloudflare-tsconfig.json new file mode 100644 index 0000000000..6fa7091d6d --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-tsconfig.json @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noEmit": true, + "lib": ["ES2022", "DOM"], + "types": [] + }, + "include": ["cloudflare-types.ts"] +} diff --git a/npm/packages/e-means/test/cloudflare-types.ts b/npm/packages/e-means/test/cloudflare-types.ts new file mode 100644 index 0000000000..e9b6eabcc5 --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-types.ts @@ -0,0 +1,25 @@ +import type { EMeansModel } from '@ruvector/e-means'; +import { + createClusteringWorker, persistCodebook, loadCodebook, exportCentroids, + type CodebookInput, type R2Binding, type VectorizeBinding, +} from '@ruvector/e-means/cloudflare'; + +declare const wasm: WebAssembly.Module; +declare const model: EMeansModel; +declare const request: Request; +const worker = createClusteringWorker({ wasmModule: wasm, maxWork: 1_000_000, bodyTimeoutMs: 1000 }); +const response: Promise = worker.fetch(request); +const bucket: R2Binding = { put: async () => ({}), get: async () => null }; +const index: VectorizeBinding = { upsert: async () => ({ mutationId: 'acknowledgement' }) }; +const input: CodebookInput = model; +void response; +void persistCodebook(bucket, 'model', input); +void loadCodebook(bucket, 'model'); +void exportCentroids(index, model, { prefix: 'model', namespace: 'owned' }); +// @ts-expect-error Worker configuration numbers cannot be strings. +createClusteringWorker({ wasmModule: wasm, maxWork: 'unbounded' }); +// @ts-expect-error Codebook storage requires owned float32 centroid arrays. +persistCodebook(bucket, 'model', { dimensions: 1, centroids: [0, 1] }); +// @ts-expect-error Vectorize returns an acknowledgement identity. +const invalidIndex: VectorizeBinding = { upsert: async () => ({}) }; +void invalidIndex; diff --git a/npm/packages/e-means/test/cloudflare-workerd.test.mjs b/npm/packages/e-means/test/cloudflare-workerd.test.mjs new file mode 100644 index 0000000000..eaf0df63f8 --- /dev/null +++ b/npm/packages/e-means/test/cloudflare-workerd.test.mjs @@ -0,0 +1,83 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { mkdtemp, readFile, rm, writeFile, mkdir, symlink } from 'node:fs/promises'; +import { spawnSync } from 'node:child_process'; +import { tmpdir } from 'node:os'; +import { dirname, join } from 'node:path'; +import { fileURLToPath, pathToFileURL } from 'node:url'; +import { Miniflare } from 'miniflare'; +import { buildWorker } from '../examples/cloudflare/build.mjs'; + +const token = 'e-means-workerd-test-not-for-production'; +const config = { compatibilityDate: '2026-07-30', modules: true, + modulesRules: [{ type: 'CompiledWasm', include: ['**/*.wasm'], fallthrough: true }] }; + +test('packed npm static Rust WASM executes in real workerd without Node compatibility', { timeout: 60_000 }, async t => { + const temporary = await mkdtemp(join(tmpdir(), 'e-means-workerd-')); + const packageDir = fileURLToPath(new URL('../', import.meta.url)); + const run = (args, cwd) => { + const result = spawnSync('npm', args, { cwd, encoding: 'utf8', env: { ...process.env, npm_config_workspaces: 'false' } }); + assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`); + return result.stdout; + }; + const archive = JSON.parse(run(['pack', '--json', '--workspaces=false', '--pack-destination', temporary], packageDir))[0]; + const consumer = join(temporary, 'consumer'); + await mkdir(consumer); + await writeFile(join(consumer, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + run(['install', '--ignore-scripts', '--no-audit', '--no-fund', '--offline', join(temporary, archive.filename)], consumer); + // esbuild is caller-supplied build tooling, not an installed runtime dependency. + await symlink(dirname(dirname(fileURLToPath(import.meta.resolve('esbuild')))), join(consumer, 'node_modules/esbuild'), 'dir'); + const installed = join(consumer, 'node_modules/@ruvector/e-means'); + const builder = await import(pathToFileURL(join(installed, 'examples/cloudflare/build.mjs')).href); + const output = join(temporary, 'output'); + const artifact = await builder.buildWorker(output); + const source = await readFile(artifact.script, 'utf8'); + assert.match(source, /\.\/e-means\.wasm/); + assert.doesNotMatch(source, /node:fs|node:crypto|node:os/); + const worker = new Miniflare({ ...config, modulesRoot: output, scriptPath: artifact.script, + bindings: { E_MEANS_BEARER_TOKEN: token } }); + t.after(async () => { await worker.dispose(); await rm(temporary, { recursive: true, force: true }); }); + const invoke = (path, value, authorization = `Bearer ${token}`) => worker.dispatchFetch(`https://worker.test${path}`, { + method: 'POST', headers: { 'content-type': 'application/json', authorization }, body: JSON.stringify(value), + }); + const health = await worker.dispatchFetch('https://worker.test/health'); + assert.equal(health.status, 200); + assert.equal((await health.json()).stateless, true); + const fitted = await invoke('/fit', { data: [1, 2, 3, 4, 5, 6], dimensions: 2, options: { clusters: 1 } }); + assert.equal(fitted.status, 200, await fitted.clone().text()); + const model = await fitted.json(); + assert.deepEqual(model.centroids, [3, 4]); + assert.deepEqual(model.assignments, [0, 0, 0]); + assert.equal(model.mse, 16 / 3); + const predicted = await invoke('/predict', { data: [1, 1, 9, 9], dimensions: 2, centroids: [0, 0, 10, 10] }); + assert.deepEqual(await predicted.json(), { assignments: [0, 1] }); + assert.equal((await invoke('/fit', {}, 'Bearer incorrect')).status, 401); + assert.equal((await invoke('/fit', { data: [1, 2], dimensions: 0, options: { clusters: 1 } })).status, 422); +}); + +test('R2 codebook helpers use the real local binding and Vectorize contract remains explicit', { timeout: 60_000 }, async t => { + const temporary = await mkdtemp(join(tmpdir(), 'e-means-r2-workerd-')); + const entry = join(temporary, 'entry.mjs'); + const adapter = fileURLToPath(new URL('../integrations/cloudflare.mjs', import.meta.url)); + await writeFile(entry, ` +import { persistCodebook, loadCodebook } from ${JSON.stringify(adapter)}; +export default { async fetch(request, env) { + const original = { dimensions: 2, centroids: new Float32Array([1, 2, 3, 4]) }; + const receipt = await persistCodebook(env.CODEBOOKS, 'test/codebook', original); + const restored = await loadCodebook(env.CODEBOOKS, 'test/codebook'); + return Response.json({ receipt, centroids: Array.from(restored.centroids), clusters: restored.clusters }); +} }; +`); + const artifact = await buildWorker(join(temporary, 'out'), entry); + const worker = new Miniflare({ ...config, modulesRoot: join(temporary, 'out'), scriptPath: artifact.script, r2Buckets: ['CODEBOOKS'] }); + t.after(async () => { await worker.dispose(); await rm(temporary, { recursive: true, force: true }); }); + const response = await worker.dispatchFetch('https://worker.test/storage'); + assert.equal(response.status, 200, await response.clone().text()); + const result = await response.json(); + assert.deepEqual(result.centroids, [1, 2, 3, 4]); + assert.equal(result.clusters, 2); + const bucket = await worker.getR2Bucket('CODEBOOKS'); + const stored = JSON.parse(await (await bucket.get('test/codebook')).text()); + assert.equal(stored.schema, 'ruvector.e-means-codebook/1'); + assert.equal(Object.hasOwn(stored, 'assignments'), false); +}); diff --git a/npm/packages/e-means/test/cloudflare.test.mjs b/npm/packages/e-means/test/cloudflare.test.mjs new file mode 100644 index 0000000000..7c081e83fb --- /dev/null +++ b/npm/packages/e-means/test/cloudflare.test.mjs @@ -0,0 +1,96 @@ +import assert from 'node:assert/strict'; +import { readFile } from 'node:fs/promises'; +import { test } from 'node:test'; +import { createClusteringWorker, WORKER_LIMITS } from '../integrations/cloudflare.mjs'; + +const wasmModule = new WebAssembly.Module(await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url))); +const token = 'e-means-test-token-not-for-production'; +const valid = { data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10], dimensions: 2, + options: { clusters: 1, epochs: 2, batchSize: 2, seed: 42 } }; +const handler = createClusteringWorker({ wasmModule, bearerToken: token }); +function request(path, body, authorization = `Bearer ${token}`, headers = {}) { + return new Request(`https://worker.test${path}`, { method: 'POST', + headers: { 'content-type': 'application/json', authorization, ...headers }, body: JSON.stringify(body) }); +} + +test('Worker fits and predicts with the real precompiled Rust WASM module', async () => { + const response = await handler.fetch(request('/fit', valid)); + assert.equal(response.status, 200); + const fitted = await response.json(); + assert.deepEqual(fitted.centroids, [5, 6]); + assert.deepEqual(fitted.assignments, [0, 0, 0, 0, 0]); + assert.equal(fitted.mse, 16); + assert.equal(fitted.updates, 6); + const predicted = await handler.fetch(request('/predict', { data: [2, 2, 8, 8], dimensions: 2, centroids: [1, 1, 9, 9] })); + assert.deepEqual(await predicted.json(), { assignments: [0, 1] }); + const empty = await handler.fetch(request('/predict', { data: [], dimensions: 2, centroids: [1, 1] })); + assert.deepEqual(await empty.json(), { assignments: [] }); + assert.equal(response.headers.get('cache-control'), 'no-store'); + assert.equal(response.headers.get('x-content-type-options'), 'nosniff'); +}); + +test('authentication fails closed and request fields cannot bypass it', async () => { + const unavailable = createClusteringWorker({ wasmModule }); + assert.equal((await unavailable.fetch(request('/fit', valid))).status, 503); + assert.equal((await handler.fetch(request('/fit', valid, 'Bearer incorrect'))).status, 401); + const health = await unavailable.fetch(new Request('https://worker.test/health')); + assert.equal(health.status, 200); + assert.equal((await health.json()).authenticatedOperations, false); + assert.equal((await handler.fetch(request('/fit', { ...valid, allowUnauthenticated: true }))).status, 422); + const local = createClusteringWorker({ wasmModule, allowUnauthenticated: true }); + assert.equal((await local.fetch(request('/fit', valid, ''))).status, 200); +}); + +test('shape, numeric, option, method and conservative work limits reject requests', async () => { + for (const body of [ + { ...valid, data: [] }, { ...valid, data: [1, 2, 3] }, + { ...valid, data: ['1', 2] }, { ...valid, data: [1e40, 2] }, + { ...valid, dimensions: 0 }, { ...valid, dimensions: WORKER_LIMITS.maxDimensions + 1 }, + { ...valid, options: { clusters: 0 } }, { ...valid, options: { clusters: 6 } }, + { ...valid, options: { clusters: 1, epochs: 0 } }, + { ...valid, options: { clusters: 1, batchSize: 0 } }, + { ...valid, options: { clusters: 1, peakStep: 0 } }, + { ...valid, options: { clusters: 1, seed: -1 } }, + { ...valid, options: { clusters: 1, finalization: 'slow' } }, + { ...valid, options: { clusters: 1, unknown: 1 } }, + ]) assert.equal((await handler.fetch(request('/fit', body))).status, 422, JSON.stringify(body)); + const limited = createClusteringWorker({ wasmModule, bearerToken: token, maxWork: 1 }); + assert.equal((await limited.fetch(request('/fit', valid))).status, 413); + assert.equal((await limited.fetch(request('/predict', { data: [1, 2], dimensions: 1, centroids: [0, 1] }))).status, 413); + // Assignment-only accounting would allow this ~4M-unit request; donor + // revival at every fifth batch makes the actual upper bound much larger. + assert.equal((await handler.fetch(request('/fit', { data: Array(256).fill(0), dimensions: 1, + options: { clusters: 256, epochs: 32, batchSize: 1 } }))).status, 413); + assert.equal((await handler.fetch(new Request('https://worker.test/fit'))).status, 405); + assert.equal((await handler.fetch(request('/fit?namespace=another-user', valid))).status, 400); + assert.equal((await handler.fetch(request('/persist', valid))).status, 404); + assert.equal((await handler.fetch(request('/fit', valid, `Bearer ${token}`, { 'content-type': 'text/plain' }))).status, 415); +}); + +test('streamed bodies have actual byte limits, strict UTF-8 parsing and read deadlines', async () => { + const small = createClusteringWorker({ wasmModule, bearerToken: token, maxRequestBytes: 32 }); + let cancelled = false; + const oversized = new ReadableStream({ start(controller) { controller.enqueue(new Uint8Array(33)); }, cancel() { cancelled = true; } }); + const response = await small.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: oversized, duplex: 'half' })); + assert.equal(response.status, 413); + assert.equal(cancelled, true); + const malformed = await handler.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: new Uint8Array([0xff]) })); + assert.equal(malformed.status, 400); + const quick = createClusteringWorker({ wasmModule, bearerToken: token, bodyTimeoutMs: 20 }); + const stalled = new ReadableStream({ start() {}, cancel() {} }); + const timeout = await quick.fetch(new Request('https://worker.test/fit', { method: 'POST', + headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: stalled, duplex: 'half' })); + assert.equal(timeout.status, 408); + const contentLength = await handler.fetch(request('/fit', valid, `Bearer ${token}`, { 'content-length': '999999999' })); + assert.equal(contentLength.status, 413); +}); + +test('Worker configuration is explicit and bounded', () => { + for (const options of [ + {}, { wasmModule: new Uint8Array() }, { wasmModule, bearerToken: 'short' }, + { wasmModule, maxWork: Infinity }, { wasmModule, maxRequestBytes: WORKER_LIMITS.maxRequestBytes + 1 }, + { wasmModule, allowUnauthenticated: 'true' }, { wasmModule, bodyTimeoutMs: 0 }, + ]) assert.throws(() => createClusteringWorker(options)); +}); diff --git a/npm/packages/e-means/test/e-means.test.mjs b/npm/packages/e-means/test/e-means.test.mjs new file mode 100644 index 0000000000..36b4a25f64 --- /dev/null +++ b/npm/packages/e-means/test/e-means.test.mjs @@ -0,0 +1,135 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { test } from 'node:test'; +import { init, fit, predict } from '../e-means.mjs'; + +test('numerical operations require completed initialization', () => { + const moduleUrl = new URL('../e-means.mjs', import.meta.url).href; + const child = spawnSync(process.execPath, ['--input-type=module', '-e', ` + import assert from 'node:assert/strict'; + import { fit, predict } from ${JSON.stringify(moduleUrl)}; + assert.throws(() => fit(new Float32Array([0]), 1, { clusters: 1 }), /await init/); + assert.throws(() => predict(new Float32Array([0]), 1, new Float32Array([0])), /await init/); + `], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); +}); + +test('initialization failure is retryable and concurrent calls share the runtime', async () => { + const moduleUrl = new URL('../e-means.mjs', import.meta.url).href; + const child = spawnSync(process.execPath, ['--input-type=module', '-e', ` + import assert from 'node:assert/strict'; + import { init, fit } from ${JSON.stringify(moduleUrl)}; + await assert.rejects(init(new Uint8Array([0, 1, 2])), /Could not initialize/); + await Promise.all([init(), init()]); + assert.equal(fit(new Float32Array([1, 3]), 1, { clusters: 1 }).centroids[0], 2); + `], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); +}); + +await init(); + +test('last-epoch mean uses every row, including a partial final batch', () => { + const data = new Float32Array([1, 2, 3, 4]); + const original = data.slice(); + const model = fit(data, 1, { clusters: 1, epochs: 1, batchSize: 3, peakStep: 1 }); + assert.deepEqual(data, original); + assert.deepEqual(model.centroids, new Float32Array([2.5])); + assert.deepEqual(model.assignments, new Uint32Array([0, 0, 0, 0])); + assert.equal(model.mse, 1.25); + assert.equal(model.updates, 2); + assert.equal(model.batchSize, 3); + assert.equal(model.dimensions, 1); +}); + +test('shared native/WASM golden case agrees on the exact codebook and diagnostics', () => { + const model = fit(new Float32Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), 2, + { clusters: 1, epochs: 2, batchSize: 2, seed: 42 }); + assert.deepEqual([...model.centroids], [5, 6]); + assert.deepEqual([...model.assignments], [0, 0, 0, 0, 0]); + assert.equal(model.mse, 16); + assert.equal(model.updates, 6); + assert.equal(model.batchSize, 2); +}); + +test('EMA maintains decayed sums and counts across unequal batch sizes', () => { + const model = fit(new Float32Array([0, 1, 9]), 1, + { clusters: 1, epochs: 1, batchSize: 2, peakStep: 1, finalization: 'ema', seed: 42 }); + // At t=1 of M=2, alpha=.55. Denominator is .45*2+.55*1=1.45. + // Enumerate the three possible final rows so the oracle is independent of shuffle order. + const possible = [3.103448275862069, 3.1724137931034484, 3.724137931034483]; + const center = model.centroids[0]; + assert.ok(possible.some((expected) => Math.abs(expected - center) < 1e-6), `center ${center}`); + assert.ok(Math.abs(model.mse - ([0, 1, 9].reduce((sum, x) => sum + (x - center) ** 2, 0) / 3)) < 1e-10); +}); + +test('separated clusters reconstruct accurately and output labels match the final codebook', () => { + const data = new Float32Array(256 * 2); + for (let i = 0; i < 256; ++i) { + const center = i < 128 ? -10 : 10; + data[i * 2] = center + (i % 5) * 0.01; + data[i * 2 + 1] = center - (i % 7) * 0.01; + } + const options = { clusters: 2, epochs: 4, batchSize: 32, seed: 7 }; + const model = fit(data, 2, options); + assert.ok(model.mse < 0.01, `MSE ${model.mse}`); + assert.deepEqual(model.assignments, predict(data, 2, model.centroids)); + assert.notEqual(model.assignments[0], model.assignments[128]); + assert.deepEqual(fit(data, 2, options), model, 'same seed reproduces the same fit'); + assert.equal(model.centroids.length, 4); + for (const v of model.centroids) assert.ok(Number.isFinite(v)); +}); + +test('nearest centroid handles ties, empty queries and f32 extreme values', () => { + const centroids = new Float32Array([-1, 1]); + assert.deepEqual(predict(new Float32Array([-2, 0, 2]), 1, centroids), new Uint32Array([0, 0, 1])); + assert.deepEqual(predict(new Float32Array(), 1, centroids), new Uint32Array()); + const large = new Float32Array([-3e38, 3e38]); + const model = fit(large, 1, { clusters: 1, epochs: 1 }); + assert.equal(model.centroids[0], 0); + assert.ok(Number.isFinite(model.mse)); +}); + +test('duplicate and zero vectors never create nonfinite centroids', () => { + for (const finalization of ['lastEpochMean', 'ema']) { + const data = new Float32Array(96); + const model = fit(data, 3, { clusters: 8, epochs: 3, batchSize: 2, peakStep: 1, finalization }); + assert.equal(model.centroids.length, 24); + assert.equal(model.mse, 0); + for (const v of model.centroids) assert.ok(Number.isFinite(v)); + } +}); + +test('invalid shapes, nonfinite input and malformed config reject before WASM coercion', () => { + const data = new Float32Array([0, 1]); + const config = { clusters: 1 }; + for (const bad of [0, -1, 1.5, NaN, Infinity, 2 ** 32, '1']) { + assert.throws(() => fit(data, bad, config), /dimensions/); + } + for (const bad of [[], [0, 1], new Float64Array([0, 1]), null]) { + assert.throws(() => fit(bad, 1, config), /Float32Array/); + } + assert.throws(() => fit(new Float32Array(), 1, config), /complete/); + assert.throws(() => fit(new Float32Array([1, 2, 3]), 2, config), /complete/); + for (const bad of [NaN, Infinity, -Infinity]) { + assert.throws(() => fit(new Float32Array([0, bad]), 1, config), /finite/); + assert.throws(() => predict(data, 1, new Float32Array([bad])), /finite/); + } + for (const key of ['clusters', 'epochs', 'batchSize']) { + for (const bad of [0, -1, 0.5, NaN, Infinity, 2 ** 32, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, [key]: bad }), new RegExp(key)); + } + } + assert.throws(() => fit(data, 1, { clusters: 3 }), /number of vectors/); + for (const bad of [0, -1, 2, NaN, Infinity, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, peakStep: bad }), /peakStep/); + } + for (const bad of [-1, 1.5, Number.MAX_SAFE_INTEGER + 1, NaN, Infinity, '1', null]) { + assert.throws(() => fit(data, 1, { ...config, seed: bad }), /seed/); + } + for (const bad of [undefined, null, [], 1, 'config']) { + assert.throws(() => fit(data, 1, bad), /options/); + } + assert.throws(() => fit(data, 1, { ...config, finalization: 'slowEma' }), /finalization/); + assert.throws(() => fit(data, 1, { ...config, epohs: 3 }), /Unknown option/); + assert.throws(() => predict(data, 1, new Float32Array()), /complete/); +}); diff --git a/npm/packages/e-means/test/ecosystem-consumers.mjs b/npm/packages/e-means/test/ecosystem-consumers.mjs new file mode 100644 index 0000000000..3136e26e6d --- /dev/null +++ b/npm/packages/e-means/test/ecosystem-consumers.mjs @@ -0,0 +1,99 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const repository = fileURLToPath(new URL('../../../../', import.meta.url)); +const packageRoot = fileURLToPath(new URL('../', import.meta.url)); +const temporary = await mkdtemp(join(tmpdir(), 'e-means-ecosystem-')); +function run(command, args, cwd = temporary) { + const result = spawnSync(command, args, { + cwd, encoding: 'utf8', timeout: 180_000, + env: { ...process.env, npm_config_workspaces: 'false' }, + }); + assert.equal(result.status, 0, `${command} ${args.join(' ')}\n${result.stdout}\n${result.stderr}`); + return result.stdout; +} +try { + await writeFile(join(temporary, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + const packages = [ + { path: packageRoot, check: true }, + { path: join(repository, 'npm/packages/core') }, + { path: join(repository, 'npm/packages/ruvector') }, + { path: join(repository, 'npm/packages/all') }, + { path: join(repository, 'crates/ruvector-wasm') }, + ]; + const archives = []; + for (const item of packages) { + const args = ['pack', '--json', '--workspaces=false', '--pack-destination', temporary]; + // The shared artifact's normal prepack executes its actual WASM. Consumer + // prepack lanes build unrelated database SDKs; this test qualifies only the + // newly shipped clustering subpaths, not those packages' legacy root builds. + if (!item.check) args.push('--ignore-scripts'); + const [packed] = JSON.parse(run('npm', args, item.path)); + const paths = packed.files.map(file => file.path); + if (item.check) { + for (const name of ['runtime.mjs', 'wasm/ruvector_e_means_bg.wasm', 'integrations/metaharness.mjs', 'integrations/cloudflare.mjs']) { + assert.ok(paths.includes(name), `missing shared artifact ${name}`); + } + } else { + for (const name of ['clustering.mjs', 'clustering.d.mts', 'clustering/quantization.mjs', 'clustering/ivf.mjs', 'clustering/metaharness.mjs', 'clustering/cloudflare.mjs']) { + assert.ok(paths.includes(name), `missing consumer artifact ${name}`); + } + } + archives.push(join(temporary, packed.filename)); + } + run('npm', ['install', '--ignore-scripts', '--omit=optional', '--no-audit', '--no-fund', ...archives]); + await writeFile(join(temporary, 'consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { readFile } from 'node:fs/promises'; + const cases = [ + ['@ruvector/core/clustering.mjs', '@ruvector/core/clustering/'], + ['ruvector/clustering.mjs', 'ruvector/clustering/'], + ['@ruvector/all/clustering.mjs', '@ruvector/all/clustering/'], + ['@ruvector/wasm/clustering', '@ruvector/wasm/clustering/'], + ]; + for (const [root, prefix] of cases) { + const extension = root.endsWith('.mjs') ? '.mjs' : ''; + const core = await import(root); + await core.init(); + const data = new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]); + const quantization = await import(prefix + 'quantization' + extension); + const book = quantization.trainProductQuantizer(data, 2, 2, { clusters: 1, epochs: 1 }); + const codes = quantization.encodeProductQuantizer(book, data); + assert.ok(codes instanceof Uint8Array); + assert.deepEqual([...quantization.decodeProductQuantizer(book, codes)], [5,6,5,6,5,6,5,6]); + const ivf = await import(prefix + 'ivf' + extension); + const partitions = ivf.partition(data, 2, { clusters: 1 }); + assert.deepEqual([...ivf.postingList(partitions, 0)], [0,1,2,3]); + const meta = await import(prefix + 'metaharness' + extension); + const evaluator = meta.createClusteringEvaluator({ training: data, + holdout: new Float32Array([5,6]), dimensions: 2, + baseline: { clusters: 1, epochs: 1, batchSize: 4 }, + domain: { batchSize: { min: 1, max: 4, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 1, maxDistanceCoordinates: 100000, timeoutMs: 30000 } }); + const score = await evaluator.evaluate(evaluator.baselineGenome, 'installed-baseline'); + assert.equal(score.raw.holdoutMse, 0); + const edge = await import(prefix + 'cloudflare' + extension); + const bytes = await readFile(new URL(import.meta.resolve('@ruvector/e-means/wasm'))); + const wasmModule = await WebAssembly.compile(bytes); + const token = 'local-installed-consumer-test-token'; + const worker = edge.createClusteringWorker({ wasmModule, bearerToken: token }); + const response = await worker.fetch(new Request('https://local.test/fit', { + method: 'POST', headers: { authorization: 'Bearer ' + token, 'content-type': 'application/json' }, + body: JSON.stringify({ data: [1,2,3,4], dimensions: 2, options: { clusters: 1 } }), + })); + assert.equal(response.status, 200); + assert.deepEqual((await response.json()).centroids, [2,3]); + console.log(root + ': PQ, IVF, heldout evaluator and Worker facades passed'); + } + `); + process.stdout.write(run(process.execPath, ['consumer.mjs'])); + const installed = JSON.parse(await readFile(join(temporary, 'node_modules/@ruvector/e-means/package.json'))); + assert.equal(installed.version, '0.1.0'); + console.log('Installed ecosystem subpaths passed; consumer root/prepack release lanes were not qualified'); +} finally { + await rm(temporary, { recursive: true, force: true }); +} diff --git a/npm/packages/e-means/test/ivf.test.mjs b/npm/packages/e-means/test/ivf.test.mjs new file mode 100644 index 0000000000..fcc5b5a4f0 --- /dev/null +++ b/npm/packages/e-means/test/ivf.test.mjs @@ -0,0 +1,67 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { init, fit, predict } from '@ruvector/e-means'; +import { partition, postingList } from '@ruvector/e-means/ivf'; + +await init(); + +const data = new Float32Array([-10, -9, 10, 9, -9, -10, 9, 10, -11, -9, 11, 9]); +const options = { clusters: 2, epochs: 6, batchSize: 3, seed: 42 }; + +test('IVF partitions use shared fit results and stable exact assignment posting lists', () => { + const before = data.slice(); + const result = partition(data, 2, options); + const shared = fit(data, 2, options); + assert.equal(result.schema, 'ruvector-e-means-ivf-v1'); + assert.deepEqual(result.model.centroids, shared.centroids); + assert.deepEqual(result.model.assignments, predict(data, 2, shared.centroids)); + assert.equal(result.offsets.length, 3); + assert.equal(result.offsets[0], 0); + assert.equal(result.offsets[2], 6); + assert.deepEqual(Array.from(result.indices).sort((a, b) => a - b), [0, 1, 2, 3, 4, 5]); + for (let cluster = 0; cluster < 2; cluster++) { + const expected = Array.from({ length: 6 }, (_, row) => row).filter(row => shared.assignments[row] === cluster); + assert.deepEqual(Array.from(postingList(result, cluster)), expected); + } + assert.deepEqual(data, before); +}); + +test('IVF handles empty clusters and returns independent posting-list storage', () => { + const result = partition(new Float32Array(16).fill(1), 2, { clusters: 4, epochs: 1, batchSize: 8 }); + assert.deepEqual(Array.from(postingList(result, 0)), [0, 1, 2, 3, 4, 5, 6, 7]); + for (let cluster = 1; cluster < 4; cluster++) assert.deepEqual(postingList(result, cluster), new Uint32Array()); + const list = postingList(result, 0); + list.fill(99); + assert.equal(result.indices[0], 0); + assert.deepEqual(postingList(structuredClone(result), 0), postingList(result, 0)); +}); + +test('IVF rejects malformed training data and mutated partition records', () => { + assert.throws(() => partition(new Float32Array([1, NaN]), 2, { clusters: 1 })); + assert.throws(() => partition(new Float32Array([1]), 2, { clusters: 1 })); + assert.throws(() => partition(data, 2, { clusters: 0 })); + const result = partition(data, 2, options); + for (const cluster of [-1, 2, 0.5, NaN]) assert.throws(() => postingList(result, cluster)); + for (const mutation of [ + value => { value.schema = 'unknown'; }, + value => { value.offsets = value.offsets.slice(1); }, + value => { value.offsets[0] = 1; }, + value => { value.offsets[1] = 99; }, + value => { value.indices[0] = 99; }, + value => { value.indices[1] = value.indices[0]; }, + value => { value.model.assignments[value.indices[0]] = 99; }, + value => { value.model.centroids[0] = NaN; }, + value => { value.model.mse = NaN; }, + ]) { + const bad = structuredClone(result); + mutation(bad); + assert.throws(() => postingList(bad, 0)); + } +}); + +test('posting validation reads actual centroid storage despite an overridden iterator', () => { + const result = partition(data, 2, options); + result.model.centroids[0] = NaN; + result.model.centroids[Symbol.iterator] = function* () { yield 0; }; + assert.throws(() => postingList(result, 0), /centroids must be finite/); +}); diff --git a/npm/packages/e-means/test/metaharness.test.mjs b/npm/packages/e-means/test/metaharness.test.mjs new file mode 100644 index 0000000000..51a3756bd3 --- /dev/null +++ b/npm/packages/e-means/test/metaharness.test.mjs @@ -0,0 +1,128 @@ +import assert from 'node:assert/strict'; +import { mkdtemp, readdir, rm } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { test } from 'node:test'; +import { createClusteringEvaluator, tuneClustering } from '../integrations/metaharness.mjs'; +import { evolveNumeric } from '@metaharness/darwin'; + +function options(extra = {}) { + return { + training: new Float32Array([0, 0, 0, 2, 10, 10, 10, 12]), + holdout: new Float32Array([0, 1, 10, 11]), dimensions: 2, + baseline: { clusters: 2, epochs: 2, batchSize: 2, peakStep: 0.5, seed: 42 }, + domain: { clusters: { min: 1, max: 2, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 3, maxDistanceCoordinates: 100_000, timeoutMs: 30_000 }, + ...extra, + }; +} + +test('real WASM measures a separate holdout and flags quality regressions', async () => { + const evaluator = createClusteringEvaluator(options()); + const baseline = await evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + assert.equal(baseline.raw.trainMse, 1); + assert.equal(baseline.raw.holdoutMse, 0); + assert.equal(baseline.primary, 1); + assert.equal(baseline.regressed, false); + const candidate = await evaluator.evaluate({ clusters: 1 }, 'candidate'); + assert.equal(candidate.raw.holdoutMse, 50); + assert.equal(candidate.raw.baselineHoldoutMse, 0); + assert.equal(candidate.primary, 1 / 51); + assert.equal(candidate.regressed, true); + assert.ok(Number.isFinite(candidate.raw.fitMs) && candidate.raw.fitMs >= 0); + assert.ok(Number.isFinite(candidate.raw.holdoutMs) && candidate.raw.holdoutMs >= 0); + assert.equal(evaluator.receipt().sourceApplied, false); +}); + +test('inputs/configuration snapshot before awaits and receipts cannot mutate evidence', async () => { + const supplied = options(); + supplied.training.slice = () => supplied.training; + supplied.holdout.slice = () => supplied.holdout; + const evaluator = createClusteringEvaluator(supplied); + const pending = evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + supplied.training.fill(999); supplied.holdout.fill(999); + supplied.baseline.clusters = 1; supplied.domain.clusters.min = 2; + supplied.budget.maxEvaluations = 0; + const score = await pending; + assert.equal(score.raw.holdoutMse, 0); + score.raw.holdoutMse = 999; + const receipt = evaluator.receipt(); + receipt.trials[0].score.raw.holdoutMse = 999; + receipt.domain.clusters.min = 2; + receipt.baselineConfig.clusters = 99; + assert.equal(evaluator.receipt().baseline.score.raw.holdoutMse, 0); + assert.equal(evaluator.receipt().domain.clusters.min, 1); + assert.equal(evaluator.receipt().baselineConfig.clusters, 2); + assert.equal((await evaluator.evaluate({ clusters: 1 }, 'candidate')).raw.holdoutMse, 50); +}); + +test('admission rejects invalid splits, unbounded domains and oversized work before training', () => { + const badCases = [ + options({ holdout: new Float32Array() }), + options({ holdout: new Float32Array([NaN, 1]) }), + options({ dimensions: 0 }), + options({ domain: {} }), + options({ domain: { clusters: { min: 1, max: Infinity, type: 'int', scale: 'linear' } } }), + options({ domain: { clusters: { min: 1, max: 5, type: 'int', scale: 'linear' } } }), + options({ domain: { batchSize: { min: 1, max: 4, type: 'float', scale: 'linear' } } }), + options({ domain: { peakStep: { min: 0.1, max: 1, type: 'float', scale: 'log', default: 0.1 } } }), + options({ baseline: { clusters: 2, epochs: 2, batchSize: 0 } }), + options({ baseline: { clusters: 2, epochs: null } }), + options({ baseline: { clusters: 2, seed: null } }), + options({ budget: { maxEvaluations: 0, maxDistanceCoordinates: 10_000 } }), + options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 1 } }), + options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 1e10 } }), + options({ baseline: { clusters: 2, epochs: 0xffff_ffff, batchSize: 1 } }), + options({ qualityTolerance: -1 }), + options({ qualityTolerance: null }), + ]; + for (const value of badCases) assert.throws(() => createClusteringEvaluator(value)); + const overlapping = options(); overlapping.holdout = overlapping.training.subarray(0, 4); + assert.throws(() => createClusteringEvaluator(overlapping), /nonoverlapping/); + assert.throws(() => createClusteringEvaluator(options({ training: new Float32Array(16_777_217) })), /64 MiB/); +}); + +test('evaluation dispatch, domain, concurrency and cooperative deadline limits are enforced', async () => { + const evaluator = createClusteringEvaluator(options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 100_000 } })); + const pending = evaluator.evaluate(evaluator.baselineGenome, 'baseline'); + await assert.rejects(evaluator.evaluate(evaluator.baselineGenome, 'parallel'), /Concurrent/); + await pending; + await assert.rejects(evaluator.evaluate({ clusters: 1 }, 'second'), /budget exhausted/); + const firstCandidate = createClusteringEvaluator(options()); + await assert.rejects(firstCandidate.evaluate({ clusters: 1 }, 'wrong-first'), /baselineGenome/); + await assert.rejects(firstCandidate.evaluate({ clusters: 99 }, 'outside'), /clusters/); + const expired = createClusteringEvaluator(options({ budget: { maxEvaluations: 1, maxDistanceCoordinates: 100_000, timeoutMs: 1 } })); + await new Promise(resolve => setTimeout(resolve, 10)); + await assert.rejects(expired.evaluate(expired.baselineGenome, 'expired'), /deadline/); +}); + +test('published Darwin evolveNumeric accepts the real clustering evaluator', async () => { + const evaluator = createClusteringEvaluator(options()); + const archive = await mkdtemp(join(tmpdir(), 'e-means-sdk-test-')); + try { + const result = await evolveNumeric({ genomeSpec: evaluator.domain, baselineGenome: evaluator.baselineGenome, + evaluator, generations: 1, childrenPerGeneration: 2, seed: 7, concurrency: 1, workRoot: archive }); + assert.equal(result.records.length, 3); + assert.equal(result.baseline.score.raw.holdoutMse, 0); + assert.equal(evaluator.receipt().dispatchCount, 3); + assert.ok(result.records.every(record => Number.isFinite(record.score.primary))); + } finally { await rm(archive, { recursive: true, force: true }); } +}); + +test('bounded tuneClustering uses Darwin0.13.0, validates evidence and removes its archive', async () => { + const before = new Set((await readdir(tmpdir())).filter(name => name.startsWith('e-means-darwin-'))); + const supplied = options({ generations: 1, childrenPerGeneration: 2, mutationSeed: 7 }); + const result = await tuneClustering(supplied); + assert.deepEqual(result.engine, { package: '@metaharness/darwin', version: '0.13.0', algorithm: 'evolveNumeric' }); + assert.equal(result.schema, 'e-means.clustering-tuning/1'); + assert.equal(result.trials.length, 3); + assert.equal(result.dispatchCount, 3); + assert.equal(result.baseline.score.raw.holdoutMse, 0); + assert.equal(result.sourceApplied, false); + assert.equal(result.temporaryArchiveRemoved, true); + assert.ok(result.consumedWork <= result.budget.maxDistanceCoordinates); + assert.ok(result.winner.score.primary >= result.baseline.score.primary); + assert.deepEqual(supplied.training, options().training); + assert.equal((await readdir(tmpdir())).filter(name => name.startsWith('e-means-darwin-') && !before.has(name)).length, 0); + await assert.rejects(tuneClustering(options({ generations: 8, childrenPerGeneration: 8 })), /worst-case dispatches/); +}); diff --git a/npm/packages/e-means/test/packed-consumer.mjs b/npm/packages/e-means/test/packed-consumer.mjs new file mode 100644 index 0000000000..5bc838f64e --- /dev/null +++ b/npm/packages/e-means/test/packed-consumer.mjs @@ -0,0 +1,88 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const packageDir = fileURLToPath(new URL('../', import.meta.url)); +const temp = await mkdtemp(join(tmpdir(), 'e-means-consumer-')); +function run(command, args, cwd = temp) { + const result = spawnSync(command, args, { cwd, encoding: 'utf8', env: { ...process.env, npm_config_workspaces: 'false' } }); + assert.equal(result.status, 0, `${command} ${args.join(' ')}\n${result.stdout}\n${result.stderr}`); + return result.stdout; +} +try { + const pack = JSON.parse(run('npm', ['pack', '--json', '--pack-destination', temp, '--workspaces=false'], packageDir)); + const files = pack[0].files.map((entry) => entry.path); + assert.ok(files.includes('wasm/ruvector_e_means_bg.wasm')); + assert.ok(files.includes('wasm/ruvector_e_means.js')); + assert.ok(files.includes('e-means.d.ts')); + for (const path of ['runtime.mjs', 'runtime.d.ts', 'integrations/metaharness.mjs', 'integrations/metaharness.d.ts', 'integrations/clustering-validation.mjs']) { + assert.ok(files.includes(path), `archive missing ${path}`); + } + assert.ok(!files.some((path) => path.endsWith('.rs') || path.includes('node_modules'))); + await writeFile(join(temp, 'package.json'), JSON.stringify({ private: true, type: 'module' })); + run('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--offline', join(temp, pack[0].filename)]); + await writeFile(join(temp, 'consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { init, fit, predict } from '@ruvector/e-means'; + import { createClusteringEvaluator, tuneClustering } from '@ruvector/e-means/metaharness'; + import { fit as runtimeFit } from '@ruvector/e-means/runtime'; + await init(); + const data = new Float32Array([1, 1, 3, 3]); + const result = fit(data, 2, { clusters: 1 }); + assert.deepEqual([...result.centroids], [2, 2]); + assert.equal(result.mse, 2); + assert.deepEqual([...predict(data, 2, result.centroids)], [0, 0]); + assert.equal(runtimeFit(data, 2, { clusters: 1 }).mse, 2); + const evaluation = { training: new Float32Array([0,0,0,2,10,10,10,12]), holdout: new Float32Array([0,1,10,11]), dimensions:2, + baseline:{clusters:2,epochs:2,batchSize:2,peakStep:0.5}, domain:{clusters:{min:1,max:2,type:'int',scale:'linear'}}, + budget:{maxEvaluations:3,maxDistanceCoordinates:100000} }; + const evaluator = createClusteringEvaluator(evaluation); + assert.equal((await evaluator.evaluate(evaluator.baselineGenome, 'baseline')).raw.holdoutMse, 0); + await assert.rejects(tuneClustering({...evaluation,generations:1,childrenPerGeneration:2}), /optional peer/); + console.log('Installed archive runtime/evaluator passed without the optional SDK'); + `); + process.stdout.write(run(process.execPath, ['consumer.mjs'])); + const installed = JSON.parse(await readFile(join(temp, 'node_modules/@ruvector/e-means/package.json'))); + assert.equal(installed.version, '0.1.0'); + // Cached pinned registry packages only: installation and qualification do not + // execute dependency lifecycle scripts or contact the registry. + run('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '@metaharness/darwin@0.13.0', 'typescript@5.9.3']); + await writeFile(join(temp, 'meta-consumer.mjs'), ` + import assert from 'node:assert/strict'; + import { tuneClustering } from '@ruvector/e-means/metaharness'; + import { evolveNumeric } from '@metaharness/darwin'; + assert.equal(typeof evolveNumeric, 'function'); + const result = await tuneClustering({ + training:new Float32Array([0,0,0,2,10,10,10,12]), holdout:new Float32Array([0,1,10,11]), dimensions:2, + baseline:{clusters:2,epochs:2,batchSize:2,peakStep:0.5}, domain:{clusters:{min:1,max:2,type:'int',scale:'linear'}}, + budget:{maxEvaluations:3,maxDistanceCoordinates:100000}, generations:1,childrenPerGeneration:2 }); + assert.equal(result.engine.version,'0.13.0'); + assert.equal(result.trials.length,3); + assert.equal(result.baseline.score.raw.holdoutMse,0); + assert.equal(result.sourceApplied,false); + assert.equal(result.temporaryArchiveRemoved,true); + console.log('Offline installed MetaHarness/WASM consumer passed'); + `); + process.stdout.write(run(process.execPath, ['meta-consumer.mjs'])); + await writeFile(join(temp, 'types.mts'), ` + import {createClusteringEvaluator,tuneClustering,type ClusteringEvaluationOptions} from '@ruvector/e-means/metaharness'; + import {init,fit} from '@ruvector/e-means/runtime'; + const config:ClusteringEvaluationOptions={training:new Float32Array([0,1]),holdout:new Float32Array([2]),dimensions:1, + baseline:{clusters:1,epochs:1},domain:{epochs:{min:1,max:2,type:'int',scale:'linear'}},budget:{maxEvaluations:2,maxDistanceCoordinates:1000}}; + const evaluator=createClusteringEvaluator(config); + const result=await tuneClustering({...config,generations:1,childrenPerGeneration:1}); + const notApplied:false=result.sourceApplied; + await init(new WebAssembly.Module(new Uint8Array())); + const assignments:Uint32Array=fit(config.training,1,config.baseline).assignments; + void [evaluator,notApplied,assignments]; + // @ts-expect-error explicit source required by Node-free runtime + await init(); + `); + run(process.execPath, ['node_modules/typescript/bin/tsc', '--noEmit', '--strict', '--target', 'es2022', '--module', 'nodenext', '--moduleResolution', 'nodenext', '--lib', 'es2022,dom', 'types.mts']); + console.log('Offline installed integration declarations passed'); +} finally { + await rm(temp, { recursive: true, force: true }); +} diff --git a/npm/packages/e-means/test/quantization-types.mts b/npm/packages/e-means/test/quantization-types.mts new file mode 100644 index 0000000000..67fa682ea2 --- /dev/null +++ b/npm/packages/e-means/test/quantization-types.mts @@ -0,0 +1,19 @@ +import { type EMeansOptions } from '@ruvector/e-means'; +import { + trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, + productQuantizerToJSON, productQuantizerFromJSON, type ProductQuantizer, +} from '@ruvector/e-means/quantization'; +import { partition, postingList, type IVFPartition } from '@ruvector/e-means/ivf'; + +const data = new Float32Array([1, 2, 3, 4]); +const options: EMeansOptions = { clusters: 1 }; +const pq: ProductQuantizer = trainProductQuantizer(data, 2, 2, options); +const codes: Uint8Array = encodeProductQuantizer(pq, data); +const restored: Float32Array = decodeProductQuantizer(productQuantizerFromJSON(productQuantizerToJSON(pq)), codes); +const ivf: IVFPartition = partition(restored, 2, options); +const posting: Uint32Array = postingList(ivf, 0); +void posting; +// @ts-expect-error byte codes are required +decodeProductQuantizer(pq, new Uint32Array()); +// @ts-expect-error float32 input vectors are required +trainProductQuantizer([1, 2], 2, 1, options); diff --git a/npm/packages/e-means/test/quantization.test.mjs b/npm/packages/e-means/test/quantization.test.mjs new file mode 100644 index 0000000000..0825fd68fa --- /dev/null +++ b/npm/packages/e-means/test/quantization.test.mjs @@ -0,0 +1,136 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { init, fit, predict } from '@ruvector/e-means'; +import { + trainProductQuantizer, encodeProductQuantizer, decodeProductQuantizer, + productQuantizerToJSON, productQuantizerFromJSON, +} from '@ruvector/e-means/quantization'; + +await init(); + +const data = new Float32Array([1, 2, 10, 11, 1, 2, 20, 21, 3, 4, 10, 11, 3, 4, 20, 21]); +const options = { clusters: 2, epochs: 8, batchSize: 4, peakStep: 0.5, seed: 42 }; + +test('product quantization trains exact shared codebooks and reconstructs representable vectors', () => { + const before = data.slice(); + const model = trainProductQuantizer(data, 4, 2, options); + assert.equal(model.schema, 'ruvector-e-means-pq-v1'); + assert.equal(model.centroids.length, 8); + const codes = encodeProductQuantizer(model, data); + assert.ok(codes instanceof Uint8Array); + assert.equal(codes.length, 8); + assert.deepEqual(decodeProductQuantizer(model, codes), data); + assert.deepEqual(data, before); + assert.deepEqual(trainProductQuantizer(data, 4, 2, options).centroids, model.centroids); + for (let subspace = 0; subspace < 2; subspace++) { + const subvectors = Float32Array.from({ length: 8 }, (_, index) => data[Math.floor(index / 2) * 4 + subspace * 2 + index % 2]); + const shared = fit(subvectors, 2, options); + const start = subspace * 4; + assert.deepEqual(model.centroids.slice(start, start + 4), shared.centroids); + const assignments = predict(subvectors, 2, shared.centroids); + for (let row = 0; row < 4; row++) assert.equal(codes[row * 2 + subspace], assignments[row]); + } +}); + +test('one-cluster subspaces have arithmetic-mean codebooks and support empty codecs', () => { + const model = trainProductQuantizer(data, 4, 2, { clusters: 1, batchSize: 3 }); + assert.deepEqual(Array.from(model.centroids), [2, 3, 15, 16]); + assert.deepEqual(encodeProductQuantizer(model, new Float32Array()), new Uint8Array()); + assert.deepEqual(decodeProductQuantizer(model, new Uint8Array()), new Float32Array()); + assert.deepEqual(Array.from(decodeProductQuantizer(model, new Uint8Array([0, 0]))), [2, 3, 15, 16]); +}); + +test('all subspaces use one snapshot of caller configuration', () => { + let reads = 0; + const model = trainProductQuantizer(data, 4, 2, { + get clusters() { reads++; return reads === 1 ? 1 : 2; }, + batchSize: 3, + }); + assert.equal(reads, 1); + assert.equal(model.clusters, 1); + assert.deepEqual(Array.from(model.centroids), [2, 3, 15, 16]); +}); + +test('codebooks survive JSON and structured clone with independent ownership', () => { + const model = trainProductQuantizer(data, 4, 2, options); + const json = productQuantizerToJSON(model); + const restored = productQuantizerFromJSON(JSON.parse(JSON.stringify(json))); + assert.deepEqual(restored.centroids, model.centroids); + assert.notEqual(restored.centroids, model.centroids); + const clone = structuredClone(model); + assert.deepEqual(encodeProductQuantizer(clone, data), encodeProductQuantizer(model, data)); + restored.centroids.fill(0); + json.centroids.fill(0); + assert.ok(model.centroids.some(value => value !== 0)); +}); + +test('256-centroid codebooks preserve the full byte range', () => { + const model = { + schema: 'ruvector-e-means-pq-v1', dimensions: 1, subspaces: 1, clusters: 256, + centroids: Float32Array.from({ length: 256 }, (_, index) => index), + }; + const input = new Float32Array([0, 255, 254]); + const codes = encodeProductQuantizer(model, input); + assert.deepEqual(Array.from(codes), [0, 255, 254]); + assert.deepEqual(decodeProductQuantizer(model, codes), input); +}); + +test('product quantization rejects invalid shapes, values, configuration and byte codes', () => { + for (const [dimensions, subspaces, clusters] of [[0, 1, 1], [4, 0, 1], [4, 3, 1], [4, 5, 1], [4, 2, 0], [4, 2, 257], [4, 2, 5]]) { + assert.throws(() => trainProductQuantizer(data, dimensions, subspaces, { clusters })); + } + assert.throws(() => trainProductQuantizer(data, 4, 2, { clusters: 2, epochs: 0 })); + assert.throws(() => trainProductQuantizer(data, 4, 2, { ...options, unknown: true })); + assert.throws(() => trainProductQuantizer([1, 2, 3, 4], 4, 2, { clusters: 1 })); + assert.throws(() => trainProductQuantizer(new Float32Array([1, NaN, 3, 4]), 4, 2, { clusters: 1 })); + const model = trainProductQuantizer(data, 4, 2, options); + assert.throws(() => encodeProductQuantizer(model, new Float32Array([1]))); + assert.throws(() => encodeProductQuantizer(model, new Float32Array([1, 2, 3, Infinity]))); + assert.throws(() => decodeProductQuantizer(model, new Uint32Array([0, 0]))); + assert.throws(() => decodeProductQuantizer(model, new Uint8Array([0]))); + assert.throws(() => decodeProductQuantizer(model, new Uint8Array([0, 2]))); +}); + +test('every operation revalidates caller-owned codebooks and JSON values', () => { + const model = trainProductQuantizer(data, 4, 2, options); + for (const mutation of [ + value => { value.schema = 'unknown'; }, + value => { value.subspaces = 3; }, + value => { value.clusters = 257; }, + value => { value.centroids = value.centroids.slice(1); }, + value => { value.centroids[0] = NaN; }, + ]) { + const bad = structuredClone(model); + mutation(bad); + assert.throws(() => encodeProductQuantizer(bad, data)); + assert.throws(() => decodeProductQuantizer(bad, new Uint8Array([0, 0]))); + assert.throws(() => productQuantizerToJSON(bad)); + } + for (const coordinate of ['1', NaN, Infinity, 1e100, undefined]) { + const json = productQuantizerToJSON(model); + json.centroids[0] = coordinate; + assert.throws(() => productQuantizerFromJSON(json)); + } +}); + +test('codecs validate indexed typed-array storage despite overridden iterators', () => { + const model = { schema: 'ruvector-e-means-pq-v1', dimensions: 1, subspaces: 1, + clusters: 1, centroids: new Float32Array([3]) }; + const hiddenNonfinite = new Float32Array([NaN]); + hiddenNonfinite[Symbol.iterator] = function* () { yield 0; }; + const corrupt = { ...model, centroids: hiddenNonfinite }; + assert.throws(() => decodeProductQuantizer(corrupt, new Uint8Array([0])), /centroids must be finite/); + assert.throws(() => productQuantizerToJSON(corrupt), /centroids must be finite/); + const hiddenInvalidCode = new Uint8Array([255]); + hiddenInvalidCode[Symbol.iterator] = function* () { yield 0; }; + assert.throws(() => decodeProductQuantizer(model, hiddenInvalidCode), /code exceeds/); +}); + +test('codebook JSON serialization reads stored coordinates rather than a custom iterator', () => { + const centroids = new Float32Array([3, 7]); + centroids[Symbol.iterator] = function* () { yield 0; }; + const model = { schema: 'ruvector-e-means-pq-v1', dimensions: 2, subspaces: 1, + clusters: 1, centroids }; + assert.deepEqual(productQuantizerToJSON(model).centroids, [3, 7]); + assert.deepEqual(Array.from(decodeProductQuantizer(model, new Uint8Array([0]))), [3, 7]); +}); diff --git a/npm/packages/e-means/test/runtime.test.mjs b/npm/packages/e-means/test/runtime.test.mjs new file mode 100644 index 0000000000..70e7a96d5e --- /dev/null +++ b/npm/packages/e-means/test/runtime.test.mjs @@ -0,0 +1,40 @@ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { test } from 'node:test'; + +test('compiled-module runtime and plain imports load no Node builtins or Darwin SDK', async () => { + const temp = await mkdtemp(join(tmpdir(), 'e-means-runtime-')); + try { + const bytes = await readFile(new URL('../wasm/ruvector_e_means_bg.wasm', import.meta.url)); + const loader = 'data:text/javascript,' + encodeURIComponent(` + export async function resolve(specifier, context, next) { + if (specifier.startsWith('node:') || specifier.includes('@metaharness/darwin')) { + throw new Error('Unexpected Node/SDK import: ' + specifier); + } + return next(specifier, context); + } + `); + const file = join(temp, 'consumer.mjs'); + await writeFile(file, ` + const runtime = await import(${JSON.stringify(new URL('../runtime.mjs', import.meta.url).href)}); + let rejected = false; + try { await runtime.init(); } catch (error) { rejected = /requires WASM bytes/.test(error.message); } + if (!rejected) throw new Error('Runtime must reject an omitted source before initialization'); + const bytes = Uint8Array.from(atob(${JSON.stringify(bytes.toString('base64'))}), character => character.charCodeAt(0)); + const module = new WebAssembly.Module(bytes); + await Promise.all([runtime.init(module), runtime.init(module)]); + const result = runtime.fit(new Float32Array([0, 2]), 1, { clusters: 1 }); + if (result.centroids[0] !== 1 || result.mse !== 1) throw new Error('Compiled module fit differs'); + await import(${JSON.stringify(new URL('../e-means.mjs', import.meta.url).href)}); + const integration = await import(${JSON.stringify(new URL('../integrations/metaharness.mjs', import.meta.url).href)}); + if (typeof integration.createClusteringEvaluator !== 'function') throw new Error('Evaluator export missing'); + console.log('Node-free runtime and lazy SDK imports passed'); + `); + const child = spawnSync(process.execPath, ['--experimental-loader', loader, file], { encoding: 'utf8' }); + assert.equal(child.status, 0, child.stderr); + assert.match(child.stdout, /Node-free runtime/); + } finally { await rm(temp, { recursive: true, force: true }); } +}); diff --git a/npm/packages/e-means/test/tsconfig.json b/npm/packages/e-means/test/tsconfig.json new file mode 100644 index 0000000000..29ec5a0a8c --- /dev/null +++ b/npm/packages/e-means/test/tsconfig.json @@ -0,0 +1,12 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "NodeNext", + "moduleResolution": "NodeNext", + "strict": true, + "noEmit": true, + "lib": ["ES2022", "DOM"], + "types": [] + }, + "include": ["*.ts", "*.mts"] +} diff --git a/npm/packages/e-means/test/typed-bridge.test.mjs b/npm/packages/e-means/test/typed-bridge.test.mjs new file mode 100644 index 0000000000..11e14a2d4c --- /dev/null +++ b/npm/packages/e-means/test/typed-bridge.test.mjs @@ -0,0 +1,70 @@ +import assert from 'node:assert/strict'; +import { test } from 'node:test'; +import { init, fit } from '../e-means.mjs'; +import initWasm, { fitJson, fitTyped, FittedModel } from '../wasm/ruvector_e_means.js'; + +await init(); +const runtime = await initWasm(); +const samples = new Float32Array([0, 1, 0, 2, 10, 12, 10, 13, -9, -10, -9, -11]); + +test('typed result transport matches JSON transport for both finalizers', () => { + for (const finalization of ['lastEpochMean', 'ema']) { + const options = { clusters: 3, epochs: 3, batchSize: 2, seed: 7, finalization }; + const json = JSON.parse(fitJson(samples, 2, JSON.stringify(options))); + assert.deepEqual(fit(samples, 2, options), { + ...json, + centroids: Float32Array.from(json.centroids), + assignments: Uint32Array.from(json.assignments), + }); + } +}); + +test('consumed outputs are caller-owned and survive handle release and WASM memory growth', () => { + const handle = fitTyped(samples, 2, JSON.stringify({ clusters: 3, epochs: 2 })); + let centroids, assignments; + try { + centroids = handle.takeCentroids(); + assignments = handle.takeAssignments(); + assert.deepEqual(handle.takeCentroids(), new Float32Array()); + assert.deepEqual(handle.takeAssignments(), new Uint32Array()); + assert.notEqual(centroids.buffer, runtime.memory.buffer); + assert.notEqual(assignments.buffer, runtime.memory.buffer); + } finally { + handle.free(); + } + const expectedCentroids = centroids.slice(), expectedAssignments = assignments.slice(); + runtime.memory.grow(1); + fit(samples, 2, { clusters: 2 }); + assert.deepEqual(centroids, expectedCentroids); + assert.deepEqual(assignments, expectedAssignments); +}); + +test('the wrapper frees its model handle after success and output-copy failure', () => { + const originalTake = FittedModel.prototype.takeAssignments; + const originalFree = FittedModel.prototype.free; + let frees = 0; + FittedModel.prototype.free = function () { frees++; return originalFree.call(this); }; + try { + assert.equal(fit(samples, 2, { clusters: 2 }).assignments.length, 6); + assert.equal(frees, 1); + FittedModel.prototype.takeAssignments = function () { throw new Error('injected output-copy failure'); }; + assert.throws(() => fit(samples, 2, { clusters: 2 }), /injected output-copy failure/); + assert.equal(frees, 2); + } finally { + FittedModel.prototype.takeAssignments = originalTake; + FittedModel.prototype.free = originalFree; + } + assert.equal(fit(samples, 2, { clusters: 2 }).assignments.length, 6); +}); + +test('repeated fits release WASM model allocations instead of accumulating them', () => { + const data = Float32Array.from({ length: 4096 }, (_, i) => (i % 17) / 17); + const config = { clusters: 1, epochs: 1, batchSize: 128 }; + for (let i = 0; i < 8; i++) fit(data, 1, config); + const afterWarmup = runtime.memory.buffer.byteLength; + for (let i = 0; i < 128; i++) { + const model = fit(data, 1, config); + assert.equal(model.assignments.length, data.length); + } + assert.equal(runtime.memory.buffer.byteLength, afterWarmup, 'WASM allocation high-water mark must plateau'); +}); diff --git a/npm/packages/e-means/test/types.ts b/npm/packages/e-means/test/types.ts new file mode 100644 index 0000000000..e463a2c7d4 --- /dev/null +++ b/npm/packages/e-means/test/types.ts @@ -0,0 +1,32 @@ +import { init, fit, predict, type EMeansModel, type EMeansOptions } from '@ruvector/e-means'; +import { init as initRuntime } from '@ruvector/e-means/runtime'; +import { createClusteringEvaluator, tuneClustering, type ClusteringEvaluationOptions } from '@ruvector/e-means/metaharness'; + +const options: EMeansOptions = { clusters: 2, epochs: 3, finalization: 'lastEpochMean' }; +await init(); +const model: EMeansModel = fit(new Float32Array([0, 0, 1, 1]), 2, options); +const assignments: Uint32Array = predict(new Float32Array([2, 2]), 2, model.centroids); +void assignments; +// @ts-expect-error missing required cluster count +fit(new Float32Array(), 1, { epochs: 3 }); +// @ts-expect-error row storage must be Float32Array +fit([0, 1], 1, options); +// @ts-expect-error unsupported finalization policy +fit(new Float32Array(), 1, { clusters: 1, finalization: 'slowEma' }); + +await initRuntime(new WebAssembly.Module(new Uint8Array())); +// @ts-expect-error Node-free runtime requires an explicit source +await initRuntime(); +const evaluation: ClusteringEvaluationOptions = { + training: new Float32Array([0, 1]), holdout: new Float32Array([2]), dimensions: 1, + baseline: { clusters: 1, epochs: 1 }, + domain: { epochs: { min: 1, max: 2, type: 'int', scale: 'linear' } }, + budget: { maxEvaluations: 2, maxDistanceCoordinates: 1000 }, +}; +const evaluator = createClusteringEvaluator(evaluation); +await evaluator.evaluate(evaluator.baselineGenome, 'baseline'); +const tuned = await tuneClustering({ ...evaluation, generations: 1, childrenPerGeneration: 1 }); +const neverApplied: false = tuned.sourceApplied; +void neverApplied; +// @ts-expect-error tuning requires a finite explicit evaluation budget +createClusteringEvaluator({ training: new Float32Array(), holdout: new Float32Array(), dimensions: 1, baseline: options, domain: {} }); diff --git a/npm/packages/e-means/wasm-module.d.ts b/npm/packages/e-means/wasm-module.d.ts new file mode 100644 index 0000000000..b439be05df --- /dev/null +++ b/npm/packages/e-means/wasm-module.d.ts @@ -0,0 +1,3 @@ +/** Statically compiled module supplied by a Worker-aware bundler such as Wrangler. */ +declare const module: WebAssembly.Module; +export default module; diff --git a/npm/packages/e-means/wasm/ruvector_e_means.d.ts b/npm/packages/e-means/wasm/ruvector_e_means.d.ts new file mode 100644 index 0000000000..c63fbfba3d --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means.d.ts @@ -0,0 +1,83 @@ +/* tslint:disable */ +/* eslint-disable */ + +/** + * A temporary owner for one fit result. JavaScript takes independent output + * arrays and then frees this handle, releasing any vectors not taken. + */ +export class FittedModel { + private constructor(); + free(): void; + [Symbol.dispose](): void; + /** + * Cluster indices fit u32 because wasm32 arrays and sample counts do. + */ + takeAssignments(): Uint32Array; + /** + * wasm-bindgen copies the returned vector into a caller-owned Float32Array + * before freeing its Rust allocation. No view into WASM memory escapes. + */ + takeCentroids(): Float32Array; + readonly batchSize: number; + readonly dimensions: number; + readonly mse: number; + readonly peakStep: number; + readonly revivedClusters: number; + readonly updates: number; +} + +/** + * Compatibility transport and an independent parity oracle for typed output. + */ +export function fitJson(data: Float32Array, dimensions: number, config_json: string): string; + +/** + * Only the small configuration crosses JSON; result vectors stay numeric. + */ +export function fitTyped(data: Float32Array, dimensions: number, config_json: string): FittedModel; + +export function predictFlat(data: Float32Array, dimensions: number, centroids: Float32Array): Uint32Array; + +export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module; + +export interface InitOutput { + readonly memory: WebAssembly.Memory; + readonly __wbg_fittedmodel_free: (a: number, b: number) => void; + readonly fitJson: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly fitTyped: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly fittedmodel_batchSize: (a: number) => number; + readonly fittedmodel_dimensions: (a: number) => number; + readonly fittedmodel_mse: (a: number) => number; + readonly fittedmodel_peakStep: (a: number) => number; + readonly fittedmodel_revivedClusters: (a: number) => number; + readonly fittedmodel_takeAssignments: (a: number, b: number) => void; + readonly fittedmodel_takeCentroids: (a: number, b: number) => void; + readonly fittedmodel_updates: (a: number) => number; + readonly predictFlat: (a: number, b: number, c: number, d: number, e: number, f: number) => void; + readonly __wbindgen_add_to_stack_pointer: (a: number) => number; + readonly __wbindgen_export: (a: number, b: number) => number; + readonly __wbindgen_export2: (a: number, b: number, c: number, d: number) => number; + readonly __wbindgen_export3: (a: number, b: number, c: number) => void; +} + +export type SyncInitInput = BufferSource | WebAssembly.Module; + +/** + * Instantiates the given `module`, which can either be bytes or + * a precompiled `WebAssembly.Module`. + * + * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated. + * + * @returns {InitOutput} + */ +export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput; + +/** + * If `module_or_path` is {RequestInfo} or {URL}, makes a request and + * for everything else, calls `WebAssembly.instantiate` directly. + * + * @param {{ module_or_path: InitInput | Promise }} module_or_path - Passing `InitInput` directly is deprecated. + * + * @returns {Promise} + */ +export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise } | InitInput | Promise): Promise; diff --git a/npm/packages/e-means/wasm/ruvector_e_means.js b/npm/packages/e-means/wasm/ruvector_e_means.js new file mode 100644 index 0000000000..ba3256a488 --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means.js @@ -0,0 +1,456 @@ +/* @ts-self-types="./ruvector_e_means.d.ts" */ + +/** + * A temporary owner for one fit result. JavaScript takes independent output + * arrays and then frees this handle, releasing any vectors not taken. + */ +export class FittedModel { + static __wrap(ptr) { + const obj = Object.create(FittedModel.prototype); + obj.__wbg_ptr = ptr; + FittedModelFinalization.register(obj, obj.__wbg_ptr, obj); + return obj; + } + __destroy_into_raw() { + const ptr = this.__wbg_ptr; + this.__wbg_ptr = 0; + FittedModelFinalization.unregister(this); + return ptr; + } + free() { + const ptr = this.__destroy_into_raw(); + wasm.__wbg_fittedmodel_free(ptr, 0); + } + /** + * @returns {number} + */ + get batchSize() { + const ret = wasm.fittedmodel_batchSize(this.__wbg_ptr); + return ret >>> 0; + } + /** + * @returns {number} + */ + get dimensions() { + const ret = wasm.fittedmodel_dimensions(this.__wbg_ptr); + return ret >>> 0; + } + /** + * @returns {number} + */ + get mse() { + const ret = wasm.fittedmodel_mse(this.__wbg_ptr); + return ret; + } + /** + * @returns {number} + */ + get peakStep() { + const ret = wasm.fittedmodel_peakStep(this.__wbg_ptr); + return ret; + } + /** + * @returns {number} + */ + get revivedClusters() { + const ret = wasm.fittedmodel_revivedClusters(this.__wbg_ptr); + return ret >>> 0; + } + /** + * Cluster indices fit u32 because wasm32 arrays and sample counts do. + * @returns {Uint32Array} + */ + takeAssignments() { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + wasm.fittedmodel_takeAssignments(retptr, this.__wbg_ptr); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var v1 = getArrayU32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v1; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } + } + /** + * wasm-bindgen copies the returned vector into a caller-owned Float32Array + * before freeing its Rust allocation. No view into WASM memory escapes. + * @returns {Float32Array} + */ + takeCentroids() { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + wasm.fittedmodel_takeCentroids(retptr, this.__wbg_ptr); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var v1 = getArrayF32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v1; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } + } + /** + * @returns {number} + */ + get updates() { + const ret = wasm.fittedmodel_updates(this.__wbg_ptr); + return ret >>> 0; + } +} +if (Symbol.dispose) FittedModel.prototype[Symbol.dispose] = FittedModel.prototype.free; + +/** + * Compatibility transport and an independent parity oracle for typed output. + * @param {Float32Array} data + * @param {number} dimensions + * @param {string} config_json + * @returns {string} + */ +export function fitJson(data, dimensions, config_json) { + let deferred4_0; + let deferred4_1; + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_export, wasm.__wbindgen_export2); + const len1 = WASM_VECTOR_LEN; + wasm.fitJson(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true); + var ptr3 = r0; + var len3 = r1; + if (r3) { + ptr3 = 0; len3 = 0; + throw takeObject(r2); + } + deferred4_0 = ptr3; + deferred4_1 = len3; + return getStringFromWasm0(ptr3, len3); + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + wasm.__wbindgen_export3(deferred4_0, deferred4_1, 1); + } +} + +/** + * Only the small configuration crosses JSON; result vectors stay numeric. + * @param {Float32Array} data + * @param {number} dimensions + * @param {string} config_json + * @returns {FittedModel} + */ +export function fitTyped(data, dimensions, config_json) { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passStringToWasm0(config_json, wasm.__wbindgen_export, wasm.__wbindgen_export2); + const len1 = WASM_VECTOR_LEN; + wasm.fitTyped(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + if (r2) { + throw takeObject(r1); + } + return FittedModel.__wrap(r0); + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } +} + +/** + * @param {Float32Array} data + * @param {number} dimensions + * @param {Float32Array} centroids + * @returns {Uint32Array} + */ +export function predictFlat(data, dimensions, centroids) { + try { + const retptr = wasm.__wbindgen_add_to_stack_pointer(-16); + const ptr0 = passArrayF32ToWasm0(data, wasm.__wbindgen_export); + const len0 = WASM_VECTOR_LEN; + const ptr1 = passArrayF32ToWasm0(centroids, wasm.__wbindgen_export); + const len1 = WASM_VECTOR_LEN; + wasm.predictFlat(retptr, ptr0, len0, dimensions, ptr1, len1); + var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true); + var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true); + var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true); + var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true); + if (r3) { + throw takeObject(r2); + } + var v3 = getArrayU32FromWasm0(r0, r1).slice(); + wasm.__wbindgen_export3(r0, r1 * 4, 4); + return v3; + } finally { + wasm.__wbindgen_add_to_stack_pointer(16); + } +} +function __wbg_get_imports() { + const import0 = { + __proto__: null, + __wbg_Error_fdd633d4bb5dd76a: function(arg0, arg1) { + const ret = Error(getStringFromWasm0(arg0, arg1)); + return addHeapObject(ret); + }, + __wbg___wbindgen_throw_ea4887a5f8f9a9db: function(arg0, arg1) { + throw new Error(getStringFromWasm0(arg0, arg1)); + }, + }; + return { + __proto__: null, + "./ruvector_e_means_bg.js": import0, + }; +} + +const FittedModelFinalization = (typeof FinalizationRegistry === 'undefined') + ? { register: () => {}, unregister: () => {} } + : new FinalizationRegistry(ptr => wasm.__wbg_fittedmodel_free(ptr, 1)); + +function addHeapObject(obj) { + if (heap_next === heap.length) heap.push(heap.length + 1); + const idx = heap_next; + heap_next = heap[idx]; + + heap[idx] = obj; + return idx; +} + +function dropObject(idx) { + if (idx < 1028) return; + heap[idx] = heap_next; + heap_next = idx; +} + +function getArrayF32FromWasm0(ptr, len) { + ptr = ptr >>> 0; + return getFloat32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len); +} + +function getArrayU32FromWasm0(ptr, len) { + ptr = ptr >>> 0; + return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len); +} + +let cachedDataViewMemory0 = null; +function getDataViewMemory0() { + if (cachedDataViewMemory0 === null || cachedDataViewMemory0.buffer.detached === true || (cachedDataViewMemory0.buffer.detached === undefined && cachedDataViewMemory0.buffer !== wasm.memory.buffer)) { + cachedDataViewMemory0 = new DataView(wasm.memory.buffer); + } + return cachedDataViewMemory0; +} + +let cachedFloat32ArrayMemory0 = null; +function getFloat32ArrayMemory0() { + if (cachedFloat32ArrayMemory0 === null || cachedFloat32ArrayMemory0.byteLength === 0) { + cachedFloat32ArrayMemory0 = new Float32Array(wasm.memory.buffer); + } + return cachedFloat32ArrayMemory0; +} + +function getStringFromWasm0(ptr, len) { + return decodeText(ptr >>> 0, len); +} + +let cachedUint32ArrayMemory0 = null; +function getUint32ArrayMemory0() { + if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) { + cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer); + } + return cachedUint32ArrayMemory0; +} + +let cachedUint8ArrayMemory0 = null; +function getUint8ArrayMemory0() { + if (cachedUint8ArrayMemory0 === null || cachedUint8ArrayMemory0.byteLength === 0) { + cachedUint8ArrayMemory0 = new Uint8Array(wasm.memory.buffer); + } + return cachedUint8ArrayMemory0; +} + +function getObject(idx) { return heap[idx]; } + +let heap = new Array(1024).fill(undefined); +heap.push(undefined, null, true, false); + +let heap_next = heap.length; + +function passArrayF32ToWasm0(arg, malloc) { + const ptr = malloc(arg.length * 4, 4) >>> 0; + getFloat32ArrayMemory0().set(arg, ptr / 4); + WASM_VECTOR_LEN = arg.length; + return ptr; +} + +function passStringToWasm0(arg, malloc, realloc) { + if (realloc === undefined) { + const buf = cachedTextEncoder.encode(arg); + const ptr = malloc(buf.length, 1) >>> 0; + getUint8ArrayMemory0().subarray(ptr, ptr + buf.length).set(buf); + WASM_VECTOR_LEN = buf.length; + return ptr; + } + + let len = arg.length; + let ptr = malloc(len, 1) >>> 0; + + const mem = getUint8ArrayMemory0(); + + let offset = 0; + + for (; offset < len; offset++) { + const code = arg.charCodeAt(offset); + if (code > 0x7F) break; + mem[ptr + offset] = code; + } + if (offset !== len) { + if (offset !== 0) { + arg = arg.slice(offset); + } + ptr = realloc(ptr, len, len = offset + arg.length * 3, 1) >>> 0; + const view = getUint8ArrayMemory0().subarray(ptr + offset, ptr + len); + const ret = cachedTextEncoder.encodeInto(arg, view); + + offset += ret.written; + ptr = realloc(ptr, len, offset, 1) >>> 0; + } + + WASM_VECTOR_LEN = offset; + return ptr; +} + +function takeObject(idx) { + const ret = getObject(idx); + dropObject(idx); + return ret; +} + +let cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }); +cachedTextDecoder.decode(); +const MAX_SAFARI_DECODE_BYTES = 2146435072; +let numBytesDecoded = 0; +function decodeText(ptr, len) { + numBytesDecoded += len; + if (numBytesDecoded >= MAX_SAFARI_DECODE_BYTES) { + cachedTextDecoder = new TextDecoder('utf-8', { ignoreBOM: true, fatal: true }); + cachedTextDecoder.decode(); + numBytesDecoded = len; + } + return cachedTextDecoder.decode(getUint8ArrayMemory0().subarray(ptr, ptr + len)); +} + +const cachedTextEncoder = new TextEncoder(); + +if (!('encodeInto' in cachedTextEncoder)) { + cachedTextEncoder.encodeInto = function (arg, view) { + const buf = cachedTextEncoder.encode(arg); + view.set(buf); + return { + read: arg.length, + written: buf.length + }; + }; +} + +let WASM_VECTOR_LEN = 0; + +let wasmModule, wasmInstance, wasm; +function __wbg_finalize_init(instance, module) { + wasmInstance = instance; + wasm = instance.exports; + wasmModule = module; + cachedDataViewMemory0 = null; + cachedFloat32ArrayMemory0 = null; + cachedUint32ArrayMemory0 = null; + cachedUint8ArrayMemory0 = null; + return wasm; +} + +async function __wbg_load(module, imports) { + if (typeof Response === 'function' && module instanceof Response) { + if (typeof WebAssembly.instantiateStreaming === 'function') { + try { + return await WebAssembly.instantiateStreaming(module, imports); + } catch (e) { + const validResponse = module.ok && expectedResponseType(module.type); + + if (validResponse && module.headers.get('Content-Type') !== 'application/wasm') { + console.warn("`WebAssembly.instantiateStreaming` failed because your server does not serve Wasm with `application/wasm` MIME type. Falling back to `WebAssembly.instantiate` which is slower. Original error:\n", e); + + } else { throw e; } + } + } + + const bytes = await module.arrayBuffer(); + return await WebAssembly.instantiate(bytes, imports); + } else { + const instance = await WebAssembly.instantiate(module, imports); + + if (instance instanceof WebAssembly.Instance) { + return { instance, module }; + } else { + return instance; + } + } + + function expectedResponseType(type) { + switch (type) { + case 'basic': case 'cors': case 'default': return true; + } + return false; + } +} + +function initSync(module) { + if (wasm !== undefined) return wasm; + + + if (module !== undefined) { + if (Object.getPrototypeOf(module) === Object.prototype) { + ({module} = module) + } else { + console.warn('using deprecated parameters for `initSync()`; pass a single object instead') + } + } + + const imports = __wbg_get_imports(); + if (!(module instanceof WebAssembly.Module)) { + module = new WebAssembly.Module(module); + } + const instance = new WebAssembly.Instance(module, imports); + return __wbg_finalize_init(instance, module); +} + +async function __wbg_init(module_or_path) { + if (wasm !== undefined) return wasm; + + + if (module_or_path !== undefined) { + if (Object.getPrototypeOf(module_or_path) === Object.prototype) { + ({module_or_path} = module_or_path) + } else { + console.warn('using deprecated parameters for the initialization function; pass a single object instead') + } + } + + if (module_or_path === undefined) { + module_or_path = new URL('ruvector_e_means_bg.wasm', import.meta.url); + } + const imports = __wbg_get_imports(); + + if (typeof module_or_path === 'string' || (typeof Request === 'function' && module_or_path instanceof Request) || (typeof URL === 'function' && module_or_path instanceof URL)) { + module_or_path = fetch(module_or_path); + } + + const { instance, module } = await __wbg_load(await module_or_path, imports); + + return __wbg_finalize_init(instance, module); +} + +export { initSync, __wbg_init as default }; diff --git a/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm new file mode 100644 index 0000000000000000000000000000000000000000..b7189ea79886279d6e846cbac12b89ffc94efcc0 GIT binary patch literal 142782 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≠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�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 W4w5*~i}a=m;8qLiV?iSE%D(~61vr!d literal 0 HcmV?d00001 diff --git a/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts new file mode 100644 index 0000000000..1d8bb910ab --- /dev/null +++ b/npm/packages/e-means/wasm/ruvector_e_means_bg.wasm.d.ts @@ -0,0 +1,19 @@ +/* tslint:disable */ +/* eslint-disable */ +export const memory: WebAssembly.Memory; +export const __wbg_fittedmodel_free: (a: number, b: number) => void; +export const fitJson: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const fitTyped: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const fittedmodel_batchSize: (a: number) => number; +export const fittedmodel_dimensions: (a: number) => number; +export const fittedmodel_mse: (a: number) => number; +export const fittedmodel_peakStep: (a: number) => number; +export const fittedmodel_revivedClusters: (a: number) => number; +export const fittedmodel_takeAssignments: (a: number, b: number) => void; +export const fittedmodel_takeCentroids: (a: number, b: number) => void; +export const fittedmodel_updates: (a: number) => number; +export const predictFlat: (a: number, b: number, c: number, d: number, e: number, f: number) => void; +export const __wbindgen_add_to_stack_pointer: (a: number) => number; +export const __wbindgen_export: (a: number, b: number) => number; +export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number; +export const __wbindgen_export3: (a: number, b: number, c: number) => void; diff --git a/scripts/e-means/github_release.py b/scripts/e-means/github_release.py new file mode 100644 index 0000000000..76508c1100 --- /dev/null +++ b/scripts/e-means/github_release.py @@ -0,0 +1,294 @@ +#!/usr/bin/env python3 +"""Publish the exact-source shared e-means release and verify every asset byte. + +Only the protected main job may mutate GitHub. Existing tags and asset bytes +are immutable; retries may complete an otherwise identical partial draft. +""" +import argparse +import hashlib +import json +import os +from pathlib import Path +import re +import shutil +import subprocess +import tempfile +import tomllib +import zipfile + +import release + +TAG = 'e-means-v0.1.0' +TITLE = 'Shared e-means 0.1.0 (Rust and WebAssembly)' + + +def gh(*args): + return subprocess.check_output(['gh', *args], text=True).strip() + + +def api_optional(endpoint): + result = subprocess.run(['gh', 'api', endpoint], capture_output=True, text=True) + if result.returncode: + if re.search(r'\(HTTP 404\)', result.stderr): + return None + raise ValueError('Cannot establish GitHub identity or absence: ' + endpoint) + return json.loads(result.stdout) + + +def inventory(endpoint): + rows = [] + for page in range(1, 101): + batch = json.loads(gh('api', endpoint + f'?per_page=100&page={page}')) + if not isinstance(batch, list): + raise ValueError('Invalid authenticated GitHub inventory') + rows.extend(batch) + if len(batch) < 100: + return rows + raise ValueError('GitHub inventory exceeded explicit pagination bound') + + +def guard(source): + release.protected(source) + if os.environ.get('E_MEANS_RELEASE_ENVIRONMENT') != 'npm-production': + raise ValueError('GitHub release requires the protected npm-production environment') + + +def tag_source(): + ref = api_optional(f'repos/{release.REPO}/git/ref/tags/{TAG}') + if ref is None: + return None + obj = ref['object'] + for _ in range(5): + if obj['type'] == 'commit' and re.fullmatch('[a-f0-9]{40}', obj['sha']): + return obj['sha'] + if obj['type'] != 'tag': + break + obj = json.loads(gh('api', f'repos/{release.REPO}/git/tags/{obj["sha"]}'))['object'] + raise ValueError('Release tag does not identify a commit') + + +def ensure_tag(source): + current = tag_source() + if current is None: + guard(source) + gh('api', '--method', 'POST', f'repos/{release.REPO}/git/refs', + '-f', f'ref=refs/tags/{TAG}', '-f', f'sha={source}') + current = tag_source() + if current != source: + raise ValueError('Conflicting immutable release tag; never move or overwrite it') + + +def assert_tag(source): + if tag_source() != source: + raise ValueError('Immutable release tag is missing or changed') + + +def existing_release(): + # Authenticated listing includes drafts, unlike relying on the public tag URL. + matches = [row for row in inventory(f'repos/{release.REPO}/releases') if row.get('tag_name') == TAG] + if len(matches) > 1: + raise ValueError('Multiple releases identify the same tag') + return matches[0] if matches else None + + +def validate_ci(base, source): + ci = json.loads((base / 'ci.json').read_text()) + item = ci.get('artifact', {}) + if (ci.get('sourceSha') != source or not ci.get('jobs') + or any(j.get('status') != 'completed' or j.get('conclusion') != 'success' for j in ci['jobs']) + or item.get('name') != f'e-means-candidate-{source}' or item.get('expired') is not False + or not re.fullmatch('sha256:[a-f0-9]{64}', item.get('digest', ''))): + raise ValueError('Missing successful exact-source preflight evidence') + run = release.gh(f'repos/{release.REPO}/actions/runs/{ci["runId"]}') + if (run.get('head_sha') != source or run.get('event') != 'push' + or not run.get('head_branch', '').startswith('release/') or run.get('path') != release.PREFLIGHT + or run.get('status') != 'completed' or run.get('conclusion') != 'success'): + raise ValueError('Preflight run does not identify the accepted source') + jobs = release.pages(f'repos/{release.REPO}/actions/runs/{ci["runId"]}/jobs?filter=latest', 'jobs') + def job_identity(job): + return (job.get('id'), job.get('name'), job.get('status'), job.get('conclusion')) + if (not {'qualify', 'node20'}.issubset({job.get('name') for job in jobs}) + or any(job.get('status') != 'completed' or job.get('conclusion') != 'success' for job in jobs) + or sorted(map(job_identity, jobs)) != sorted(map(job_identity, ci['jobs']))): + raise ValueError('Preflight job evidence differs from GitHub authority') + official = release.gh(f'repos/{release.REPO}/actions/artifacts/{item["id"]}') + if (any(official.get(key) != item.get(key) for key in ('id', 'name', 'digest', 'expired')) + or official.get('workflow_run', {}).get('id') != ci['runId'] + or official.get('workflow_run', {}).get('head_sha') != source): + raise ValueError('Candidate artifact differs from GitHub authority') + if 'sha256:' + release.sha(base / 'candidate.zip') != item['digest']: + raise ValueError('Candidate artifact ZIP digest mismatch') + with zipfile.ZipFile(base / 'candidate.zip') as archive: + entries = [row for row in archive.infolist() if not row.is_dir()] + names = [row.filename for row in entries] + actual = {p.relative_to(base / 'candidate').as_posix() for p in (base / 'candidate').rglob('*') if p.is_file()} + if len(set(names)) != len(names) or set(names) != actual: + raise ValueError('Extracted candidate differs from accepted artifact inventory') + for row in entries: + if archive.read(row) != (base / 'candidate' / row.filename).read_bytes(): + raise ValueError('Extracted candidate differs from accepted artifact bytes') + return ci + + +def validate_public(base, source, candidate): + publication = json.loads((base / 'publication.json').read_text()) + consumers = json.loads((base / 'public-consumers.json').read_text()) + for row, schema in ((publication, 'ruvector.e-means-publication/1'), (consumers, 'ruvector.e-means-public-consumers/1')): + if row.get('schema') != schema or row.get('sourceSha') != source or row.get('artifacts') != candidate['artifacts']: + raise ValueError('Public evidence identity or archive mismatch') + for name, digest in candidate['artifacts'].items(): + if release.sha(base / 'public' / name) != digest: + raise ValueError('Canonical public archive changed') + fresh = base / 'fresh' + if release.sha(fresh / 'cargo/src/main.rs') != release.sha(release.ROOT / 'scripts/e-means/public-consumer.rs'): + raise ValueError('Public Rust consumer differs from exact-source fixture') + installed = fresh / 'npm/node_modules/@ruvector/e-means' + manifest = str(fresh / 'cargo/Cargo.toml') + expected = [ + (['cargo', 'run', '--manifest-path', manifest], None), + (['cargo', 'metadata', '--quiet', '--locked', '--format-version', '1', '--manifest-path', manifest], None), + (['npm', 'install', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], None), + (['node', '--test', *[str(installed / 'test' / p.name) for p in sorted((base / 'candidate/harness/test').glob('*.test.mjs'))]], 'node'), + (['node', str(fresh / 'npm/node_modules/typescript/bin/tsc'), '--noEmit', '-p', str(installed / 'test/tsconfig.json')], None), + (['node', str(installed / 'test/browser-consumer.mjs')], 'browser'), + ] + commands = consumers.get('commands', []) + if len(commands) != len(expected): + raise ValueError('Missing required fresh public consumer commands') + logs = [] + for index, (command, (args, kind)) in enumerate(zip(commands, expected)): + path = fresh / f'command-{index}.log' + if (command.get('args') != args or type(command.get('exitCode')) is not int or command['exitCode'] != 0 + or command.get('log') != path.name or release.sha(path) != command.get('logSha256')): + raise ValueError('Public consumer command or owned log changed') + output = path.read_text(errors='replace') + derived = release.evidence(output, kind) + claims = {key: command[key] for key in ('testsPassed', 'browserPassed') if key in command} + if claims != derived or any(type(claims[key]) is not type(value) for key, value in derived.items()): + raise ValueError('Public consumer claims differ from actual logs') + logs.append(output) + checks = re.findall(r'^E_MEANS_PUBLIC_CHECKS=(\d+)$', logs[0], re.M) + if len(checks) != 1 or int(checks[0]) < 10 or type(consumers.get('rustChecks')) is not int or consumers['rustChecks'] != int(checks[0]): + raise ValueError('Missing actual public Rust numerical checks') + metadata = json.loads(logs[1]) + resolved = [p for p in metadata['packages'] if (p.get('name'), p.get('version')) == (release.CRATE, release.VERSION)] + lock = tomllib.loads((fresh / 'cargo/Cargo.lock').read_text()) + locked = [p for p in lock['package'] if (p.get('name'), p.get('version')) == (release.CRATE, release.VERSION)] + registry = 'registry+https://github.com/rust-lang/crates.io-index' + if (len(resolved) != 1 or resolved[0].get('source') != registry or len(locked) != 1 + or locked[0].get('source') != registry or locked[0].get('checksum') != candidate['artifacts'][f'{release.CRATE}-{release.VERSION}.crate']): + raise ValueError('Fresh public Rust consumer did not resolve sealed canonical registry bytes') + # Recheck canonical registries immediately before exposing the release. + for name, public in ((f'{release.CRATE}-{release.VERSION}.crate', release.registry.downloaded(release.CRATE, release.VERSION)), + (f'ruvector-e-means-{release.VERSION}.tgz', release.npm_public())): + if public is None or hashlib.sha256(public).hexdigest() != candidate['artifacts'][name]: + raise ValueError('Canonical registry archive unavailable or differs from candidate') + return consumers + + +def assets(base, source): + candidate = release.validate_candidate(base / 'candidate', source) + validate_ci(base, source) + consumers = validate_public(base, source, candidate) + folder = base / 'github-release-assets' + if folder.exists(): + shutil.rmtree(folder) + folder.mkdir() + inputs = {name: base / 'public' / name for name in candidate['artifacts']} + inputs.update({'candidate.json': base / 'candidate/candidate.json', 'FILES.json': base / 'candidate/FILES.json', + 'ci.json': base / 'ci.json', 'publication.json': base / 'publication.json', + 'public-consumers.json': base / 'public-consumers.json', 'candidate-artifact.zip': base / 'candidate.zip', + 'public-Cargo.lock': base / 'fresh/cargo/Cargo.lock'}) + inputs.update({'candidate-' + row['log']: base / 'candidate' / row['log'] for row in candidate['commands']}) + inputs.update({'public-' + row['log']: base / 'fresh' / row['log'] for row in consumers['commands']}) + for name, path in inputs.items(): + if path.is_symlink() or not path.is_file(): + raise ValueError('Missing regular release evidence asset: ' + name) + shutil.copyfile(path, folder / name) + manifest = {name: release.sha(folder / name) for name in inputs} + (folder / 'release-assets.json').write_text(json.dumps({'schema': 'ruvector.e-means-github-assets/1', + 'sourceSha': source, 'tag': TAG, 'assets': manifest}, indent=2, sort_keys=True) + '\n') + manifest['release-assets.json'] = release.sha(folder / 'release-assets.json') + (folder / 'SHA256SUMS').write_text(''.join(f'{digest} {name}\n' for name, digest in sorted(manifest.items()))) + manifest['SHA256SUMS'] = release.sha(folder / 'SHA256SUMS') + return folder, manifest + + +def verify_assets(row, folder, manifest, complete=True): + remote = inventory(f'repos/{release.REPO}/releases/{row["id"]}/assets') + names = [asset.get('name') for asset in remote] + if len(names) != len(set(names)) or not set(names).issubset(manifest) or (complete and set(names) != set(manifest)): + raise ValueError('Conflicting or incomplete GitHub release asset inventory') + with tempfile.TemporaryDirectory(prefix='e-means-release-download-') as temporary: + for asset in remote: + name = asset['name'] + if asset.get('state') != 'uploaded' or asset.get('size') != (folder / name).stat().st_size: + raise ValueError('GitHub asset upload is incomplete') + path = Path(temporary) / name + with path.open('xb') as stream: + subprocess.run(['gh', 'api', f'repos/{release.REPO}/releases/assets/{asset["id"]}', + '-H', 'Accept: application/octet-stream'], stdout=stream, check=True) + if release.sha(path) != manifest[name] or (asset.get('digest') and asset['digest'] != 'sha256:' + manifest[name]): + raise ValueError('Conflicting GitHub release asset bytes; never overwrite') + return set(names) + + +def publish(source, base): + guard(source) + folder, manifest = assets(base, source) + row = existing_release() + current = tag_source() + if current is not None and current != source: + raise ValueError('Conflicting immutable release tag; never overwrite') + if row is not None and (type(row.get('draft')) is not bool or current is None or row.get('target_commitish') != source or row.get('name') != TITLE): + raise ValueError('Existing release does not identify the accepted immutable source') + if row is None: + ensure_tag(source) + notes = base / 'github-release-notes.md' + notes.write_text(f'Shared e-means 0.1.0 from `{source}`.\n\n' + 'Canonical public Rust and npm archives, actual source-bound qualification logs, ' + 'fresh public Cargo/Node/Worker/Chromium consumer evidence and the original sealed candidate are attached.\n') + guard(source) + gh('release', 'create', TAG, '--repo', release.REPO, '--target', source, '--verify-tag', '--draft', + '--latest=false', '--title', TITLE, '--notes-file', str(notes)) + row = existing_release() + if row is None or row.get('draft') is not True or row.get('target_commitish') != source: + raise ValueError('Created draft identity mismatch') + existing = verify_assets(row, folder, manifest, complete=row.get('draft') is not True) + if row.get('draft') is True: + for name in sorted(set(manifest) - existing): + guard(source) + assert_tag(source) + gh('release', 'upload', TAG, str(folder / name), '--repo', release.REPO) + verify_assets(row, folder, manifest) + assert_tag(source) + guard(source) + gh('release', 'edit', TAG, '--repo', release.REPO, '--draft=false') + published = existing_release() + if published is None or published.get('id') != row['id'] or published.get('draft') is not False: + raise ValueError('GitHub release did not become public') + row = published + status = 'published-and-byte-verified' + else: + status = 'already-published-and-byte-verified' + assert_tag(source) + verify_assets(row, folder, manifest) + final_source = tag_source() + if final_source != source: + raise ValueError('Release tag changed during final asset verification') + report = {'schema': 'ruvector.e-means-github-publication/1', 'sourceSha': source, + 'tag': TAG, 'tagSourceSha': final_source, 'status': status, + 'url': f'https://github.com/{release.REPO}/releases/tag/{TAG}', 'assets': manifest} + (base / 'github-release.json').write_text(json.dumps(report, indent=2) + '\n') + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('--expected-sha', required=True) + parser.add_argument('--directory', required=True, type=Path) + args = parser.parse_args() + publish(args.expected_sha, args.directory.resolve()) + + +if __name__ == '__main__': + main() diff --git a/scripts/e-means/public-consumer.rs b/scripts/e-means/public-consumer.rs new file mode 100644 index 0000000000..1e0675d091 --- /dev/null +++ b/scripts/e-means/public-consumer.rs @@ -0,0 +1,24 @@ +use ruvector_e_means::{fit, Config, IvfPartition, ProductQuantizer}; + +fn main() { + let mut checks = 0; + let mut check = |ok: bool| { assert!(ok); checks += 1; }; + let data = [0.0f32, 2.0, 4.0, 6.0, 8.0, 10.0]; + let config = Config { clusters: 1, epochs: 2, batch_size: Some(2), ..Config::default() }; + let model = fit(&data, 2, &config).unwrap(); + check(model.centroids == [4.0, 6.0]); + check(model.assignments == [0, 0, 0]); + check(model.predict(&data).unwrap() == [0, 0, 0]); + check(model.mse.is_finite() && model.mse >= 0.0); + check(model.updates == 4); + check(fit(&data, 2, &config).unwrap().centroids == model.centroids); + check(fit(&[f32::NAN], 1, &config).is_err()); + let pq = ProductQuantizer::fit(&data, 2, 2, &config).unwrap(); + check(pq.encode(&data).unwrap() == [0, 0, 0, 0, 0, 0]); + check(pq.decode(&[0, 0]).unwrap() == [4.0, 6.0]); + check(pq.decode(&[255, 0]).is_err()); + let ivf = IvfPartition::fit(&data, 2, &config).unwrap(); + check(ivf.posting(0).unwrap() == [0, 1, 2]); + check(ivf.posting(1).is_err()); + println!("E_MEANS_PUBLIC_CHECKS={checks}"); +} diff --git a/scripts/e-means/registry.py b/scripts/e-means/registry.py new file mode 100644 index 0000000000..bcb853fbd0 --- /dev/null +++ b/scripts/e-means/registry.py @@ -0,0 +1,94 @@ +# Registry transport adapted from ruvnet/ruv-FANN scripts/publish-candidates.py. +# MIT; exact-archive upload protocol: https://doc.rust-lang.org/cargo/reference/registry-web-api.html#publish +import hashlib, json, tarfile, time, tomllib, urllib.error, urllib.request +USER_AGENT = "ruvector-e-means-release (https://github.com/ruvnet/RuVector)" +VISIBILITY_TIMEOUT = 600 +VISIBILITY_DELAYS = (5, 10, 20, 30, 60) + +def sha(data): + return hashlib.sha256(data).hexdigest() + + +def metadata(archive): + with tarfile.open(archive) as tar: + names = tar.getnames() + manifests = [n for n in names if n.count('/') == 1 and n.endswith('/Cargo.toml')] + if len(manifests) != 1: + raise ValueError('Expected exactly one normalized manifest') + prefix = manifests[0].rsplit('/', 1)[0] + document = tomllib.loads(tar.extractfile(manifests[0]).read().decode()) + package = document['package'] + if prefix != package['name'] + '-' + package['version']: + raise ValueError('Archive identity mismatch') + result = {'name': package['name'], 'vers': package['version'], + 'deps': [], 'features': document.get('features', {}), + 'authors': package.get('authors', []), 'keywords': package.get('keywords', []), + 'categories': package.get('categories', []), 'badges': document.get('badges', {})} + for key in ['description', 'documentation', 'homepage', 'license', 'repository', 'links']: + result[key] = package.get(key) + result['license_file'] = package.get('license-file') + result['rust_version'] = package.get('rust-version') + readme = package.get('readme') + result['readme_file'] = readme if isinstance(readme, str) else None + result['readme'] = tar.extractfile(prefix + '/' + readme).read().decode() if isinstance(readme, str) else None + for target, table in [(None, document), *document.get('target', {}).items()]: + for section, kind in [('dependencies', 'normal'), ('dev-dependencies', 'dev'), ('build-dependencies', 'build')]: + for name, dep in table.get(section, {}).items(): + dep = {'version': dep} if isinstance(dep, str) else dep + if 'version' not in dep or 'path' in dep or 'git' in dep: + raise ValueError('Unpublishable dependency: ' + name) + result['deps'].append({'name': dep.get('package', name), 'version_req': dep['version'], + 'features': dep.get('features', []), 'optional': dep.get('optional', False), + 'default_features': dep.get('default-features', True), 'target': target, 'kind': kind, + 'registry': dep.get('registry-index'), 'explicit_name_in_toml': name if 'package' in dep else None}) + return result + + +def downloaded(name, version): + url = f'https://static.crates.io/crates/{name}/{name}-{version}.crate' + try: + with urllib.request.urlopen(urllib.request.Request(url, headers={'User-Agent': USER_AGENT}), timeout=60) as response: + return response.read() + except urllib.error.HTTPError as error: + if error.code in (403, 404): + return None + raise + + +def wait_public(name, version, timeout=VISIBILITY_TIMEOUT, sleep=time.sleep, clock=time.monotonic): + """Return the public crate bytes, or None if static.crates.io still lacks them past the deadline.""" + deadline = clock() + timeout + attempt = 0 + while True: + public = downloaded(name, version) + if public is not None: + return public + remaining = deadline - clock() + if remaining <= 0: + return None + sleep(min(VISIBILITY_DELAYS[min(attempt, len(VISIBILITY_DELAYS) - 1)], remaining)) + attempt += 1 + + +def confirm_version_absent(name, version): + """Static S3 403/404 alone is not authority to treat an immutable version as new.""" + key = name.lower() + if len(key) <= 2: + relative = f'{len(key)}/{key}' + elif len(key) == 3: + relative = f'3/{key[0]}/{key}' + else: + relative = f'{key[:2]}/{key[2:4]}/{key}' + request = urllib.request.Request('https://index.crates.io/' + relative, headers={'User-Agent': USER_AGENT}) + try: + with urllib.request.urlopen(request, timeout=60) as response: + records = [json.loads(line) for line in response.read().decode().splitlines() if line.strip()] + except urllib.error.HTTPError as error: + if error.code == 404: + return + raise + if not records or any(not isinstance(row.get('vers'), str) or row.get('name', '').lower() != key for row in records): + raise ValueError('Invalid or empty sparse registry index: ' + name) + if any(row['vers'] == version for row in records): + raise ValueError(f'Published version {name} {version} exists in the index but its public archive is unavailable; nothing may be uploaded') + diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py new file mode 100644 index 0000000000..9d3107916e --- /dev/null +++ b/scripts/e-means/release.py @@ -0,0 +1,486 @@ +#!/usr/bin/env python3 +"""Seal, publish and independently exercise the two shared e-means archives.""" +import argparse +import base64 +import hashlib +import json +import os +from pathlib import Path +import re +import shutil +import struct +import subprocess +import sys +import tarfile +import time +import urllib.error +import urllib.request +import zipfile + +import registry + +ROOT = Path(__file__).resolve().parents[2] +REPO = 'ruvnet/RuVector' +PREFLIGHT = '.github/workflows/e-means-preflight.yml' +PUBLISHER = 'e-means-protected-release' +VERSION = '0.1.0' +NPM_NAME = '@ruvector/e-means' +CRATE = 'ruvector-e-means' + + +def sha(path): + return hashlib.sha256(Path(path).read_bytes()).hexdigest() + + +def gh(endpoint): + return json.loads(subprocess.check_output(['gh', 'api', endpoint], text=True)) + + +def pages(endpoint, field): + result = [] + for page in range(1, 101): + rows = gh(endpoint + ('&' if '?' in endpoint else '?') + f'per_page=100&page={page}')[field] + result.extend(rows) + if len(rows) < 100: + return result + raise ValueError('Pagination exceeded explicit bound') + + +def identity(source): + if not re.fullmatch('[a-f0-9]{40}', source): + raise ValueError('Expected full immutable SHA') + if subprocess.check_output(['git', 'rev-parse', 'HEAD'], cwd=ROOT, text=True).strip() != source: + raise ValueError('Checkout source mismatch') + if subprocess.check_output(['git', 'status', '--porcelain'], cwd=ROOT): + raise ValueError('Source checkout must be clean') + + +def protected(source): + identity(source) + expected = ('true', PUBLISHER, 'refs/heads/main', source) + actual = tuple(os.environ.get(k) for k in ('GITHUB_ACTIONS', 'GITHUB_WORKFLOW', 'GITHUB_REF', 'GITHUB_SHA')) + if actual != expected: + raise ValueError('Publication requires the protected main workflow') + if gh(f'repos/{REPO}/git/ref/heads/main')['object']['sha'] != source: + raise ValueError('Main moved since qualification') + if gh(f'repos/{REPO}/issues?state=open&labels=release-blocker&per_page=1'): + raise ValueError('Open release blockers') + + +# These are the required publication gates, not caller-provided receipt claims. +# Portable paths keep the owned command proof valid after the sealed artifact is +# transferred from the preflight runner to the protected publication runner. +SOURCE = '${SOURCE}' +CANDIDATE = '${CANDIDATE}' +RUST = f'{CANDIDATE}/extracted/{CRATE}-{VERSION}' +QUALIFICATION = { + 'rust-source': (['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests'], SOURCE, 'rust', 4), + 'clippy': (['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], SOURCE, None, None), + 'rust-package': (['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', f'{CANDIDATE}/package-build'], SOURCE, None, None), + 'rust-audit': (['cargo', 'audit', '--file', f'{RUST}/Cargo.lock', '--deny', 'warnings'], SOURCE, None, None), + 'rust-msrv': (['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--no-default-features', '--target-dir', f'{CANDIDATE}/msrv-target'], SOURCE, None, None), + 'rust-packed': (['cargo', 'test', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--all-features', '--lib', '--tests', '--target-dir', f'{CANDIDATE}/packed-target'], SOURCE, 'rust', 4), + 'wasm-build': (['cargo', 'build', '--locked', '--manifest-path', f'{RUST}/Cargo.toml', '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', f'{CANDIDATE}/wasm-target'], SOURCE, None, None), + 'wasm-bindgen': (['wasm-bindgen', f'{CANDIDATE}/wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm', '--target', 'web', '--out-dir', f'{CANDIDATE}/npm-source/wasm', '--out-name', 'ruvector_e_means'], SOURCE, None, None), + 'npm-install': (['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], f'{CANDIDATE}/npm-source', None, None), + 'npm-audit': (['npm', 'audit', '--audit-level=low', '--workspaces=false'], f'{CANDIDATE}/npm-source', None, None), + 'npm-tests': (['npm', 'test', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'node', None), + 'npm-types': (['npm', 'run', 'typecheck', '--workspaces=false'], f'{CANDIDATE}/npm-source', None, None), + 'npm-consumer': (['npm', 'run', 'test:consumer', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'consumer', None), + 'npm-browser': (['npm', 'run', 'test:browser', '--workspaces=false'], f'{CANDIDATE}/npm-source', 'browser', None), + 'npm-package': (['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', CANDIDATE], f'{CANDIDATE}/npm-source', None, None), +} +BROWSER_MARKER = 'Chromium browser consumer passed: default WASM fetch, fit, predict and numerical oracle' +CONSUMER_MARKERS = ( + 'Installed archive runtime/evaluator passed without the optional SDK', + 'Offline installed MetaHarness/WASM consumer passed', + 'Offline installed integration declarations passed', +) + + +def evidence(output, kind, summaries=None): + """Derive evidence from actual command output, including when validating it.""" + if kind == 'rust': + lines = re.findall(r'^test result: (.+)$', output, re.M) + parsed = [re.fullmatch(r'ok\. (\d+) passed; (\d+) failed; (\d+) ignored; (\d+) measured; (\d+) filtered out; finished in .+', line) for line in lines] + if (not parsed or (summaries is not None and len(parsed) != summaries) + or any(not row or int(row[1]) == 0 or any(int(row[n]) for n in range(2, 6)) for row in parsed)): + raise ValueError('Rust qualification needs nonzero test suites with no failures, ignored tests, measured or filtered tests') + return {'testsPassed': sum(int(row[1]) for row in parsed)} + if kind == 'node': + values = {key: re.findall(rf'^# {key} (\d+)$', output, re.M) for key in ('pass', 'fail', 'cancelled', 'skipped', 'todo')} + if any(len(rows) != 1 for rows in values.values()) or int(values['pass'][0]) == 0 or any(int(values[key][0]) for key in ('fail', 'cancelled', 'skipped', 'todo')): + raise ValueError('Node qualification needs nonzero tests and zero failures/skips/todos') + return {'testsPassed': int(values['pass'][0])} + if kind == 'browser': + if output.splitlines().count(BROWSER_MARKER) != 1: + raise ValueError('Actual browser numerical qualification missing') + return {'browserPassed': True} + if kind == 'consumer': + if any(output.splitlines().count(marker) != 1 for marker in CONSUMER_MARKERS): + raise ValueError('Installed archive consumer numerical/type qualification missing') + return {} + + +def portable(value, base): + value = str(value) + for directory, placeholder in ((base, CANDIDATE), (ROOT, SOURCE)): + prefix = str(directory) + if value == prefix or value.startswith(prefix + '/'): + return placeholder + value[len(prefix):] + return value + + +def execute(args, cwd, base, commands, kind=None, env=None, role=None): + record = {'args': [str(x) for x in args]} + summaries = None + if role is not None: + expected_args, expected_cwd, expected_kind, summaries = QUALIFICATION[role] + record.update(role=role, args=[portable(x, base) for x in args], cwd=portable(cwd, base)) + if (record['args'], record['cwd'], kind) != (expected_args, expected_cwd, expected_kind): + raise ValueError('Owned qualification command differs from required role: ' + role) + log = base / f'command-{len(commands)}.log' + with log.open('w') as stream: + result = subprocess.run(args, cwd=cwd, stdout=stream, stderr=subprocess.STDOUT, + env={**os.environ, **(env or {})}) + output = log.read_text(errors='replace') + record.update(exitCode=result.returncode, log=log.name, logSha256=sha(log)) + if env: + # Only this explicit, non-secret build override map is recorded. + record['environment'] = env + commands.append(record) + if result.returncode: + print(output[-12000:], file=sys.stderr) + raise RuntimeError(f'Command failed: {args}') + record.update(evidence(output, kind, summaries)) + print(json.dumps(record), flush=True) + return output + + +def extract(archive, destination): + with tarfile.open(archive) as handle: + for member in handle.getmembers(): + path = Path(member.name) + if path.is_absolute() or '..' in path.parts or not (member.isfile() or member.isdir()): + raise ValueError('Unsafe archive member') + handle.extractall(destination, filter='data') + + +def seal(source, base): + identity(source) + base.mkdir(parents=True, exist_ok=False) + commands = [] + env = {'RUSTFLAGS': '', 'CARGO_BUILD_JOBS': '2', 'CARGO_INCREMENTAL': '0', 'CARGO_PROFILE_DEV_DEBUG': '0'} + for role, args in ( + ('rust-source', ['cargo', 'test', '--locked', '-p', CRATE, '--all-features', '--lib', '--tests']), + ): + execute(args, ROOT, base, commands, 'rust', env, role=role) + execute(['cargo', 'clippy', '--locked', '-p', CRATE, '--all-features', '--all-targets', '--', '-D', 'warnings'], ROOT, base, commands, env=env, role='clippy') + target = base / 'package-build' + execute(['cargo', 'package', '--locked', '-p', CRATE, '--target-dir', str(target)], ROOT, base, commands, env=env, role='rust-package') + crate = base / f'{CRATE}-{VERSION}.crate' + shutil.copyfile(target / 'package' / crate.name, crate) + extract(crate, base / 'extracted') + rust = base / 'extracted' / f'{CRATE}-{VERSION}' + execute(['cargo', 'audit', '--file', str(rust / 'Cargo.lock'), '--deny', 'warnings'], ROOT, base, commands, env=env, role='rust-audit') + execute(['cargo', '+1.81.0', 'check', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--no-default-features', '--target-dir', str(base / 'msrv-target')], ROOT, base, commands, env=env, role='rust-msrv') + execute(['cargo', 'test', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--all-features', '--lib', '--tests', '--target-dir', str(base / 'packed-target')], ROOT, base, commands, 'rust', env, role='rust-packed') + npm = base / 'npm-source' + shutil.copytree(ROOT / 'npm/packages/e-means', npm, ignore=shutil.ignore_patterns('node_modules', '*.tgz')) + wasm_env = {**env, 'CARGO_PROFILE_RELEASE_OPT_LEVEL': '3', 'CARGO_PROFILE_RELEASE_LTO': 'fat', + 'CARGO_PROFILE_RELEASE_CODEGEN_UNITS': '1', 'CARGO_PROFILE_RELEASE_STRIP': 'true', + 'CARGO_PROFILE_RELEASE_PANIC': 'unwind'} + execute(['cargo', 'build', '--locked', '--manifest-path', str(rust / 'Cargo.toml'), '--release', '--target', 'wasm32-unknown-unknown', '--features', 'wasm', '--target-dir', str(base / 'wasm-target')], ROOT, base, commands, env=wasm_env, role='wasm-build') + version = subprocess.check_output(['wasm-bindgen', '--version'], text=True).strip() + if version != 'wasm-bindgen 0.2.125': + raise ValueError('Wrong wasm-bindgen CLI') + execute(['wasm-bindgen', str(base / 'wasm-target/wasm32-unknown-unknown/release/ruvector_e_means.wasm'), '--target', 'web', '--out-dir', str(npm / 'wasm'), '--out-name', 'ruvector_e_means'], ROOT, base, commands, role='wasm-bindgen') + execute(['npm', 'ci', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], npm, base, commands, role='npm-install') + execute(['npm', 'audit', '--audit-level=low', '--workspaces=false'], npm, base, commands, role='npm-audit') + execute(['npm', 'test', '--workspaces=false'], npm, base, commands, 'node', role='npm-tests') + execute(['npm', 'run', 'typecheck', '--workspaces=false'], npm, base, commands, role='npm-types') + execute(['npm', 'run', 'test:consumer', '--workspaces=false'], npm, base, commands, 'consumer', role='npm-consumer') + execute(['npm', 'run', 'test:browser', '--workspaces=false'], npm, base, commands, 'browser', role='npm-browser') + execute(['npm', 'pack', '--json', '--workspaces=false', '--pack-destination', str(base)], npm, base, commands, role='npm-package') + archive = base / f'ruvector-e-means-{VERSION}.tgz' + if not archive.is_file(): + raise ValueError('Missing packed npm archive') + identity(source) + receipt = {'schema': 'ruvector.e-means-candidate/1', 'sourceSha': source, + 'commands': commands, 'artifacts': {crate.name: sha(crate), archive.name: sha(archive)}, + 'wasmSha256': sha(npm / 'wasm/ruvector_e_means_bg.wasm'), 'wasmBindgen': version, + 'rustcVersion': subprocess.check_output(['rustc', '--version'], text=True).strip(), + 'cargoVersion': subprocess.check_output(['cargo', '--version'], text=True).strip(), + 'nodeVersion': subprocess.check_output(['node', '--version'], text=True).strip()} + (base / 'candidate.json').write_text(json.dumps(receipt, indent=2) + '\n') + # Transfer only immutable archives, actual logs and the test harness; no + # build trees or source checkout become publication authority. + harness = base / 'harness' + shutil.copytree(npm / 'test', harness / 'test') + shutil.copyfile(npm / 'package.json', harness / 'package.json') + shutil.copyfile(npm / 'package-lock.json', harness / 'package-lock.json') + for path in base.iterdir(): + if path.is_dir() and path != harness: + shutil.rmtree(path) + files = {str(p.relative_to(base)): sha(p) for p in base.rglob('*') if p.is_file()} + (base / 'FILES.json').write_text(json.dumps(files, indent=2) + '\n') + + +def validate_payload(base): + files = json.loads((base / 'FILES.json').read_text()) + if not isinstance(files, dict) or not files: + raise ValueError('Missing complete candidate FILES manifest') + paths = list(base.rglob('*')) + if any(path.is_symlink() for path in paths): + raise ValueError('Candidate payload may not contain symlinks') + actual = {path.relative_to(base).as_posix() for path in paths if path.is_file() and path != base / 'FILES.json'} + if set(files) != actual: + raise ValueError('Candidate FILES manifest must cover the complete payload') + for relative, digest in files.items(): + path = (base / relative).resolve() + if (not isinstance(relative, str) or Path(relative).as_posix() != relative + or '\\' in relative or not path.is_relative_to(base.resolve()) + or not re.fullmatch('[a-f0-9]{64}', str(digest)) or sha(path) != digest): + raise ValueError('Candidate payload changed: ' + relative) + # The transferred harness is reviewed source at this exact checkout, not a + # second authority supplied by the artifact producer. + npm = ROOT / 'npm/packages/e-means' + expected_harness = {'harness/' + name: sha(npm / name) for name in ('package.json', 'package-lock.json')} + expected_harness.update({'harness/test/' + path.relative_to(npm / 'test').as_posix(): sha(path) + for path in (npm / 'test').rglob('*') if path.is_file()}) + if {name: digest for name, digest in files.items() if name.startswith('harness/')} != expected_harness: + raise ValueError('Candidate harness differs from exact-source checkout') + return files + + +def validate_qualification(base, receipt, files): + commands = receipt.get('commands', []) + if not isinstance(commands, list) or [c.get('role') for c in commands] != list(QUALIFICATION): + raise ValueError('Missing, duplicated or reordered required qualification roles') + for index, command in enumerate(commands): + role = command['role'] + args, cwd, kind, summaries = QUALIFICATION[role] + log = f'command-{index}.log' + if (command.get('args') != args or command.get('cwd') != cwd or type(command.get('exitCode')) is not int or command['exitCode'] != 0 + or command.get('log') != log or files.get(log) != command.get('logSha256')): + raise ValueError('Qualification command/log differs from required role: ' + role) + derived = evidence((base / log).read_text(errors='replace'), kind, summaries) + claims = {key: command[key] for key in ('testsPassed', 'browserPassed') if key in command} + if claims != derived or any(type(claims[key]) is not type(value) for key, value in derived.items()): + raise ValueError('Qualification claims differ from actual owned log: ' + role) + + +def validate_candidate(base, source): + files = validate_payload(base) + receipt = json.loads((base / 'candidate.json').read_text()) + if (not re.fullmatch('[a-f0-9]{40}', source) + or receipt.get('schema') != 'ruvector.e-means-candidate/1' or receipt.get('sourceSha') != source): + raise ValueError('Candidate identity mismatch') + if receipt.get('wasmBindgen') != 'wasm-bindgen 0.2.125': + raise ValueError('Candidate WASM binding tool differs from pinned version') + validate_qualification(base, receipt, files) + expected = {f'{CRATE}-{VERSION}.crate', f'ruvector-e-means-{VERSION}.tgz'} + if set(receipt['artifacts']) != expected or any(sha(base / name) != digest for name, digest in receipt['artifacts'].items()): + raise ValueError('Archive seal mismatch') + data = registry.metadata(base / f'{CRATE}-{VERSION}.crate') + if (data['name'], data['vers']) != (CRATE, VERSION): + raise ValueError('Rust archive identity mismatch') + with tarfile.open(base / f'ruvector-e-means-{VERSION}.tgz') as tar: + manifest = json.load(tar.extractfile('package/package.json')) + if (manifest['name'], manifest['version']) != (NPM_NAME, VERSION): + raise ValueError('npm archive identity mismatch') + if hashlib.sha256(tar.extractfile('package/wasm/ruvector_e_means_bg.wasm').read()).hexdigest() != receipt['wasmSha256']: + raise ValueError('Bundled WASM differs from actual source build') + return receipt + + +def node20(source, base): + identity(source) + validate_candidate(base, source) + consumer = base.parent / 'node20-consumer' + consumer.mkdir() + (consumer / 'package.json').write_text('{"private":true,"type":"module"}') + commands = [] + execute(['npm', 'install', '--ignore-scripts', '--offline', '--no-audit', '--no-fund', str(base / f'ruvector-e-means-{VERSION}.tgz')], consumer, consumer, commands) + installed = consumer / 'node_modules/@ruvector/e-means' + shutil.copytree(base / 'harness/test', installed / 'test') + selected = ['e-means', 'runtime', 'typed-bridge', 'quantization', 'ivf'] + execute(['node', '--test', *[str(installed / f'test/{name}.test.mjs') for name in selected]], consumer, consumer, commands, 'node') + + +def select_and_download(source, base): + protected(source) + runs = pages(f'repos/{REPO}/actions/workflows/e-means-preflight.yml/runs?head_sha={source}&event=push', 'workflow_runs') + runs = [r for r in runs if r['head_branch'].startswith('release/') and r['path'] == PREFLIGHT and r['status'] == 'completed' and r['conclusion'] == 'success'] + if not runs: + raise ValueError('No successful exact-source pre-main candidate') + run = max(runs, key=lambda r: r['id']) + jobs = pages(f'repos/{REPO}/actions/runs/{run["id"]}/jobs?filter=latest', 'jobs') + if not jobs or any(j['status'] != 'completed' or j['conclusion'] != 'success' for j in jobs): + raise ValueError('Incomplete or failed preflight jobs') + artifacts = pages(f'repos/{REPO}/actions/runs/{run["id"]}/artifacts', 'artifacts') + matches = [a for a in artifacts if a['name'] == f'e-means-candidate-{source}' and not a['expired']] + if len(matches) != 1 or not re.fullmatch('sha256:[a-f0-9]{64}', matches[0].get('digest', '')): + raise ValueError('Missing unique sealed candidate') + item = matches[0] + base.mkdir(parents=True, exist_ok=False) + archive = base / 'candidate.zip' + with archive.open('xb') as out: + subprocess.run(['gh', 'api', f'repos/{REPO}/actions/artifacts/{item["id"]}/zip'], stdout=out, check=True) + if 'sha256:' + sha(archive) != item['digest']: + raise ValueError('GitHub artifact digest mismatch') + with zipfile.ZipFile(archive) as handle: + for name in handle.namelist(): + path = Path(name) + if path.is_absolute() or '..' in path.parts: + raise ValueError('Unsafe candidate ZIP') + handle.extractall(base / 'candidate') + (base / 'ci.json').write_text(json.dumps({'sourceSha': source, 'runId': run['id'], 'jobs': jobs, 'artifact': item}, indent=2)) + validate_candidate(base / 'candidate', source) + + +def npm_public(): + url = f'https://registry.npmjs.org/@ruvector%2fe-means/{VERSION}' + try: + with urllib.request.urlopen(url, timeout=60) as response: + metadata = json.load(response) + except urllib.error.HTTPError as error: + if error.code == 404: + return None + raise + if (metadata.get('name'), metadata.get('version')) != (NPM_NAME, VERSION): + raise ValueError('Registry npm identity mismatch') + with urllib.request.urlopen(metadata['dist']['tarball'], timeout=60) as response: + data = response.read() + integrity = 'sha512-' + base64.b64encode(hashlib.sha512(data).digest()).decode() + if integrity != metadata['dist']['integrity']: + raise ValueError('npm public integrity mismatch') + return data + + +def publish(source, base): + protected(source) + candidate = base / 'candidate' + receipt = validate_candidate(candidate, source) + crate = candidate / f'{CRATE}-{VERSION}.crate' + npm = candidate / f'ruvector-e-means-{VERSION}.tgz' + # Check both immutable registries before either upload. + rust_bytes = registry.downloaded(CRATE, VERSION) + npm_bytes = npm_public() + for path, data in ((crate, rust_bytes), (npm, npm_bytes)): + if data is not None and hashlib.sha256(data).hexdigest() != sha(path): + raise ValueError('Public version already exists with different bytes: ' + path.name) + if rust_bytes is None: + registry.confirm_version_absent(CRATE, VERSION) + token = os.environ.get('CARGO_REGISTRY_TOKEN') + if not token: + raise ValueError('Missing crate publication credential') + meta = json.dumps(registry.metadata(crate)).encode() + payload = crate.read_bytes() + body = struct.pack(' Date: Wed, 11 Nov 2026 13:33:02 -0500 Subject: [PATCH 09/19] Normalize registry transport file ending --- scripts/e-means/registry.py | 1 - 1 file changed, 1 deletion(-) diff --git a/scripts/e-means/registry.py b/scripts/e-means/registry.py index bcb853fbd0..2f4cfc28fd 100644 --- a/scripts/e-means/registry.py +++ b/scripts/e-means/registry.py @@ -91,4 +91,3 @@ def confirm_version_absent(name, version): raise ValueError('Invalid or empty sparse registry index: ' + name) if any(row['vers'] == version for row in records): raise ValueError(f'Published version {name} {version} exists in the index but its public archive is unavailable; nothing may be uploaded') - From 7060e27ee0407873311b3d6cf09c69cc76514b7e Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:34:31 -0500 Subject: [PATCH 10/19] Require both exact-source release-branch qualification jobs --- docs/e-means-release.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/e-means-release.md b/docs/e-means-release.md index 4aef5cdc9d..9b48686d4b 100644 --- a/docs/e-means-release.md +++ b/docs/e-means-release.md @@ -14,6 +14,9 @@ The copied npm package then runs its dependency audit, real WASM/Worker tests, strict declarations, installed consumers with and without the optional SDK, and real Chromium numerical checks before packing. A second job installs the sealed archive offline and exercises the portable APIs on Node 20.0.0. +Both `qualify` and `node20` must succeed on the same release-branch push; +a successful local seal or a pull-request merge commit cannot substitute for +that immutable pre-main qualification. The source-bound candidate records actual command exit codes, owned logs and digests. The verifier requires the complete ordered command set and derives From 03c1751cb6890b3c2a2a63f16a25c4863fc00e9e Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:44:42 -0500 Subject: [PATCH 11/19] Pin TAP reporters for exact e-means Node qualification --- .github/workflows/e-means-preflight.yml | 16 +++++ npm/packages/e-means/package.json | 2 +- scripts/e-means/github_release.py | 2 +- scripts/e-means/release.py | 10 ++- scripts/e-means/test_github_release.py | 2 +- scripts/e-means/test_node_reporter.py | 81 +++++++++++++++++++++++++ 6 files changed, 107 insertions(+), 6 deletions(-) create mode 100644 scripts/e-means/test_node_reporter.py diff --git a/.github/workflows/e-means-preflight.yml b/.github/workflows/e-means-preflight.yml index ee8662af49..e945dcc9c4 100644 --- a/.github/workflows/e-means-preflight.yml +++ b/.github/workflows/e-means-preflight.yml @@ -45,6 +45,14 @@ jobs: path: ${{ runner.temp }}/e-means-seal if-no-files-found: error retention-days: 90 + - name: Preserve owned command logs when qualification fails + if: failure() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: e-means-failure-logs-${{ github.sha }} + path: ${{ runner.temp }}/e-means-seal/command-*.log + if-no-files-found: ignore + retention-days: 14 node20: needs: qualify runs-on: ubuntu-24.04 @@ -62,3 +70,11 @@ jobs: path: ${{ runner.temp }}/e-means-node20 - name: Exercise sealed portable runtime and PQ/IVF on the advertised Node minimum run: python3 scripts/e-means/release.py node20 --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-node20" + - name: Preserve Node minimum command logs when qualification fails + if: failure() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 + with: + name: e-means-failure-logs-${{ github.sha }} + path: ${{ runner.temp }}/node20-consumer/command-*.log + if-no-files-found: ignore + retention-days: 14 diff --git a/npm/packages/e-means/package.json b/npm/packages/e-means/package.json index 8dcf9ca38f..c6c700e3fe 100644 --- a/npm/packages/e-means/package.json +++ b/npm/packages/e-means/package.json @@ -55,7 +55,7 @@ ], "scripts": { "build": "node scripts/build.mjs", - "test": "node --test test/*.test.mjs", + "test": "node --test --test-reporter=tap test/*.test.mjs", "test:consumer": "node test/packed-consumer.mjs", "test:ecosystem": "node test/ecosystem-consumers.mjs", "test:cloudflare": "node --test test/cloudflare*.test.mjs", diff --git a/scripts/e-means/github_release.py b/scripts/e-means/github_release.py index 76508c1100..d57836fc65 100644 --- a/scripts/e-means/github_release.py +++ b/scripts/e-means/github_release.py @@ -148,7 +148,7 @@ def validate_public(base, source, candidate): (['cargo', 'run', '--manifest-path', manifest], None), (['cargo', 'metadata', '--quiet', '--locked', '--format-version', '1', '--manifest-path', manifest], None), (['npm', 'install', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], None), - (['node', '--test', *[str(installed / 'test' / p.name) for p in sorted((base / 'candidate/harness/test').glob('*.test.mjs'))]], 'node'), + (['node', '--test', '--test-reporter=tap', *[str(installed / 'test' / p.name) for p in sorted((base / 'candidate/harness/test').glob('*.test.mjs'))]], 'node'), (['node', str(fresh / 'npm/node_modules/typescript/bin/tsc'), '--noEmit', '-p', str(installed / 'test/tsconfig.json')], None), (['node', str(installed / 'test/browser-consumer.mjs')], 'browser'), ] diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py index 9d3107916e..88921cc0a1 100644 --- a/scripts/e-means/release.py +++ b/scripts/e-means/release.py @@ -152,7 +152,11 @@ def execute(args, cwd, base, commands, kind=None, env=None, role=None): if result.returncode: print(output[-12000:], file=sys.stderr) raise RuntimeError(f'Command failed: {args}') - record.update(evidence(output, kind, summaries)) + try: + record.update(evidence(output, kind, summaries)) + except ValueError: + print(output[-12000:], file=sys.stderr) + raise print(json.dumps(record), flush=True) return output @@ -305,7 +309,7 @@ def node20(source, base): installed = consumer / 'node_modules/@ruvector/e-means' shutil.copytree(base / 'harness/test', installed / 'test') selected = ['e-means', 'runtime', 'typed-bridge', 'quantization', 'ivf'] - execute(['node', '--test', *[str(installed / f'test/{name}.test.mjs') for name in selected]], consumer, consumer, commands, 'node') + execute(['node', '--test', '--test-reporter=tap', *[str(installed / f'test/{name}.test.mjs') for name in selected]], consumer, consumer, commands, 'node') def select_and_download(source, base): @@ -452,7 +456,7 @@ def verify_public(source, base): if (installed / relative).read_bytes() != tar.extractfile(member).read(): raise ValueError('Installed npm payload differs from sealed public archive') shutil.copytree(candidate / 'harness/test', installed / 'test') - execute(['node', '--test', *[str(p) for p in sorted((installed / 'test').glob('*.test.mjs'))]], npm, fresh, commands, 'node') + execute(['node', '--test', '--test-reporter=tap', *[str(p) for p in sorted((installed / 'test').glob('*.test.mjs'))]], npm, fresh, commands, 'node') execute(['node', str(npm / 'node_modules/typescript/bin/tsc'), '--noEmit', '-p', str(installed / 'test/tsconfig.json')], npm, fresh, commands) execute(['node', str(installed / 'test/browser-consumer.mjs')], npm, fresh, commands, 'browser') report = {'schema': 'ruvector.e-means-public-consumers/1', 'sourceSha': source, diff --git a/scripts/e-means/test_github_release.py b/scripts/e-means/test_github_release.py index b0b978136b..ca0a77222c 100644 --- a/scripts/e-means/test_github_release.py +++ b/scripts/e-means/test_github_release.py @@ -196,7 +196,7 @@ def setUp(self): args = [(['cargo', 'run', '--manifest-path', manifest], 'E_MEANS_PUBLIC_CHECKS=12\n'), (['cargo', 'metadata', '--quiet', '--locked', '--format-version', '1', '--manifest-path', manifest], json.dumps(self.metadata)), (['npm', 'install', '--ignore-scripts', '--workspaces=false', '--no-audit', '--no-fund'], 'installed'), - (['node', '--test', str(self.installed / 'test/one.test.mjs')], NODE), + (['node', '--test', '--test-reporter=tap', str(self.installed / 'test/one.test.mjs')], NODE), (['node', str(self.fresh / 'npm/node_modules/typescript/bin/tsc'), '--noEmit', '-p', str(self.installed / 'test/tsconfig.json')], ''), (['node', str(self.installed / 'test/browser-consumer.mjs')], release.BROWSER_MARKER + '\n')] self.commands = [] diff --git a/scripts/e-means/test_node_reporter.py b/scripts/e-means/test_node_reporter.py new file mode 100644 index 0000000000..1a01143766 --- /dev/null +++ b/scripts/e-means/test_node_reporter.py @@ -0,0 +1,81 @@ +"""Exercise the actual Node reporter contract; synthetic probes are not receipts.""" +import ast +import contextlib +import io +import json +from pathlib import Path +import shutil +import subprocess +import sys +import tempfile +import unittest + +sys.path.insert(0, str(Path(__file__).parent)) +import release + + +class NodeReporter(unittest.TestCase): + def test_actual_default_reporter_and_explicit_tap(self): + node = shutil.which('node') + self.assertIsNotNone(node, 'The release guard requires the actual Node runtime') + major = int(subprocess.check_output([node, '--version'], text=True).strip().lstrip('v').split('.')[0]) + with tempfile.TemporaryDirectory() as temporary: + fixture = Path(temporary) / 'reporter.test.mjs' + fixture.write_text("import test from 'node:test'; test('actual reporter regression probe', () => {});\n") + baseline = subprocess.run([node, '--test', str(fixture)], capture_output=True, text=True, check=True) + if major >= 23: + # Node 23 changed non-TTY default output from TAP to spec. + with self.assertRaisesRegex(ValueError, 'Node qualification'): + release.evidence(baseline.stdout, 'node') + else: + self.assertEqual(release.evidence(baseline.stdout, 'node'), {'testsPassed': 1}) + tap = subprocess.run([node, '--test', '--test-reporter=tap', str(fixture)], capture_output=True, text=True, check=True) + self.assertEqual(release.evidence(tap.stdout, 'node'), {'testsPassed': 1}) + fixture.write_text("import test from 'node:test'; test('must not qualify', { skip: true }, () => {});\n") + skipped = subprocess.run([node, '--test', '--test-reporter=tap', str(fixture)], capture_output=True, text=True, check=True) + with self.assertRaisesRegex(ValueError, 'Node qualification'): + release.evidence(skipped.stdout, 'node') + + def test_parser_failure_prints_the_actual_owned_command_log(self): + with tempfile.TemporaryDirectory() as temporary, contextlib.redirect_stderr(io.StringIO()) as diagnostic: + commands = [] + with self.assertRaisesRegex(ValueError, 'Node qualification'): + release.execute([sys.executable, '-c', 'print("actual reporter output without TAP")'], + Path(temporary), Path(temporary), commands, 'node') + self.assertIn('actual reporter output without TAP', diagnostic.getvalue()) + self.assertEqual(commands[0]['exitCode'], 0) + self.assertNotIn('testsPassed', commands[0]) + + def test_package_and_all_direct_release_tests_pin_tap(self): + manifest = json.loads((release.ROOT / 'npm/packages/e-means/package.json').read_text()) + self.assertEqual(manifest['scripts']['test'], 'node --test --test-reporter=tap test/*.test.mjs') + for filename, count in (('release.py', 2), ('github_release.py', 1)): + with self.subTest(filename=filename): + tree = ast.parse((Path(__file__).parent / filename).read_text()) + arguments = [node for node in ast.walk(tree) if isinstance(node, ast.List) + and len(node.elts) >= 2 and all(isinstance(value, ast.Constant) for value in node.elts[:2]) + and [value.value for value in node.elts[:2]] == ['node', '--test']] + self.assertEqual(len(arguments), count) + for argv in arguments: + self.assertIsInstance(argv.elts[2], ast.Constant) + self.assertEqual(argv.elts[2].value, '--test-reporter=tap') + + def test_failure_upload_is_conditional_and_contains_only_owned_logs(self): + workflow = (release.ROOT / '.github/workflows/e-means-preflight.yml').read_text() + start = workflow.index(' - name: Preserve owned command logs when qualification fails') + step = workflow[start:workflow.index(' node20:', start)] + self.assertIn(' if: failure()', step) + self.assertIn('name: e-means-failure-logs-${{ github.sha }}', step) + paths = [line.strip() for line in step.splitlines() if line.strip().startswith('path:')] + self.assertEqual(paths, ['path: ${{ runner.temp }}/e-means-seal/command-*.log']) + self.assertIn('if-no-files-found: ignore', step) + start = workflow.index(' - name: Preserve Node minimum command logs when qualification fails') + step = workflow[start:] + self.assertIn(' if: failure()', step) + self.assertIn('name: e-means-failure-logs-${{ github.sha }}', step) + paths = [line.strip() for line in step.splitlines() if line.strip().startswith('path:')] + self.assertEqual(paths, ['path: ${{ runner.temp }}/node20-consumer/command-*.log']) + + +if __name__ == '__main__': + unittest.main() From e0a1b3478647ee091ece2ca780a91cbb746e90e7 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:49:54 -0500 Subject: [PATCH 12/19] Align e-means consumer package engines with Node 20 runtime --- crates/ruvector-wasm/README.md | 2 +- crates/ruvector-wasm/package.json | 3 +++ docs/e-means-consumers.md | 26 ++++++++++++++++++++++++++ npm/package-lock.json | 2 +- npm/packages/core/README.md | 4 ++-- npm/packages/core/package.json | 2 +- 6 files changed, 34 insertions(+), 5 deletions(-) create mode 100644 docs/e-means-consumers.md diff --git a/crates/ruvector-wasm/README.md b/crates/ruvector-wasm/README.md index efd2ba6779..bf1e8330ba 100644 --- a/crates/ruvector-wasm/README.md +++ b/crates/ruvector-wasm/README.md @@ -605,7 +605,7 @@ button.addEventListener('click', async () => { - **Rust**: 1.77 or higher - **wasm-pack**: Latest version -- **Node.js**: 18.0 or higher +- **Node.js**: 20.0 or higher ```bash # Install wasm-pack diff --git a/crates/ruvector-wasm/package.json b/crates/ruvector-wasm/package.json index 0fb4030afd..687b654a88 100644 --- a/crates/ruvector-wasm/package.json +++ b/crates/ruvector-wasm/package.json @@ -1,6 +1,9 @@ { "name": "@ruvector/wasm", "version": "0.2.2", + "engines": { + "node": ">=20.0.0" + }, "description": "High-performance Rust vector database for browsers via WASM", "homepage": "https://ruv.io", "main": "pkg/ruvector_wasm.js", diff --git a/docs/e-means-consumers.md b/docs/e-means-consumers.md new file mode 100644 index 0000000000..97278f07a8 --- /dev/null +++ b/docs/e-means-consumers.md @@ -0,0 +1,26 @@ +# e-means consumer packages + +The reviewed consumer integration adds explicit clustering subpaths to +`@ruvector/core@0.1.38`, `ruvector`, `@ruvector/all`, and +`@ruvector/wasm@0.2.2`. These facades use the shared +`@ruvector/e-means@0.1.0` runtime. Their existing root APIs remain separate +from the clustering subpaths. + +The core and WASM npm packages require Node.js 20 or newer because the shared +runtime is a mandatory dependency with that minimum Node version. Their +package metadata must declare the same minimum so engine-strict installs do +not advertise unsupported Node.js 18 compatibility. The WASM package also +supports browser consumers; its Node engine declaration describes npm/Node +usage, not a browser version requirement. + +Publish and verify the shared Cargo and npm archives before qualifying or +publishing these consumer packages against the registry. The shared release +uses the [protected leaf release protocol](./e-means-release.md). A local +workspace link or packed archive can support diagnostic checks but does not +prove that an ordinary registry install works. + +The Rust consumer adapters in `ruvector-core`, `ruvector-pq-search`, and +`ruvector-rairs` retain explicit e-means training entrypoints. They consume +the unchanged shared crate; this integration does not republish or modify +the sealed shared runtime. Consumer publication and registry installation +results require their own exact-source evidence after shared publication. diff --git a/npm/package-lock.json b/npm/package-lock.json index 390814eb08..a2a2182d55 100644 --- a/npm/package-lock.json +++ b/npm/package-lock.json @@ -19463,7 +19463,7 @@ "@napi-rs/cli": "^2.18.0" }, "engines": { - "node": ">=18.0.0" + "node": ">=20.0.0" }, "dependencies": { "@ruvector/e-means": "0.1.0" diff --git a/npm/packages/core/README.md b/npm/packages/core/README.md index f69c8172f2..3927a3ab88 100644 --- a/npm/packages/core/README.md +++ b/npm/packages/core/README.md @@ -146,7 +146,7 @@ Automatically installs the correct native module for: - **macOS**: x64 (Intel), ARM64 (Apple Silicon) - **Windows**: x64 (MSVC) -Node.js 18+ required. +Node.js 20+ required. ## Advanced Configuration @@ -201,7 +201,7 @@ npm run build:napi Requires: - Rust 1.77+ -- Node.js 18+ +- Node.js 20+ - Cargo ## Use Cases diff --git a/npm/packages/core/package.json b/npm/packages/core/package.json index 197ce9642b..a3a3a7e780 100644 --- a/npm/packages/core/package.json +++ b/npm/packages/core/package.json @@ -16,7 +16,7 @@ }, "license": "MIT", "engines": { - "node": ">=18.0.0" + "node": ">=20.0.0" }, "files": [ "index.js", From b54139abbdb0d7f84f8c9d370e1cb0bf4e6ed124 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 13:59:15 -0500 Subject: [PATCH 13/19] Use lock-bound tooling closure for offline e-means consumers --- .../e-means/test/offline-tooling-lock.mjs | 48 ++++++++++++++++++ .../test/offline-tooling-lock.test.mjs | 50 +++++++++++++++++++ npm/packages/e-means/test/packed-consumer.mjs | 14 ++++-- 3 files changed, 109 insertions(+), 3 deletions(-) create mode 100644 npm/packages/e-means/test/offline-tooling-lock.mjs create mode 100644 npm/packages/e-means/test/offline-tooling-lock.test.mjs diff --git a/npm/packages/e-means/test/offline-tooling-lock.mjs b/npm/packages/e-means/test/offline-tooling-lock.mjs new file mode 100644 index 0000000000..dffada9b65 --- /dev/null +++ b/npm/packages/e-means/test/offline-tooling-lock.mjs @@ -0,0 +1,48 @@ +import assert from 'node:assert/strict'; + +const tooling = { '@metaharness/darwin': '0.13.0', typescript: '5.9.3' }; + +/** Reuse exact registry records; never resolve package names or repack tooling. */ +export function offlineToolingLock(source, consumer, manifest) { + assert.equal(source.lockfileVersion, 3, 'source tooling requires a v3 lock'); + assert.equal(consumer.lockfileVersion, 3, 'consumer requires a v3 lock'); + assert.deepEqual(Object.keys(manifest.dependencies ?? {}), ['@ruvector/e-means']); + assert.deepEqual(consumer.packages[''].dependencies, manifest.dependencies); + const own = consumer.packages['node_modules/@ruvector/e-means']; + assert.equal(own?.version, '0.1.0', 'retain the actually installed shared archive'); + assert.ok(own.resolved?.startsWith('file:') && own.integrity?.startsWith('sha512-')); + const packages = { '': { ...consumer.packages[''], devDependencies: tooling }, + 'node_modules/@ruvector/e-means': own }; + + function resolve(from, name) { + for (let prefix = from; ; ) { + const key = `${prefix ? `${prefix}/` : ''}node_modules/${name}`; + if (Object.hasOwn(source.packages, key)) return key; + if (!prefix) throw new Error(`Source lock lacks dependency ${name} from ${from}`); + const parent = prefix.lastIndexOf('/node_modules/'); + prefix = parent < 0 ? '' : prefix.slice(0, parent); + } + } + function include(key) { + if (Object.hasOwn(packages, key)) return; + const record = source.packages[key]; + assert.ok(record && !record.link && record.version, `Missing locked tooling ${key}`); + const url = new URL(record.resolved); + assert.equal(url.protocol, 'https:'); + assert.equal(url.hostname, 'registry.npmjs.org'); + assert.ok(record.integrity?.startsWith('sha512-'), `Missing integrity for ${key}`); + // Current pinned tools have no optional or peer closure. Reject a changed + // graph explicitly instead of silently resolving missing registry metadata. + assert.equal(Object.keys(record.optionalDependencies ?? {}).length, 0, `Unsupported optional tooling dependency ${key}`); + assert.equal(Object.keys(record.peerDependencies ?? {}).length, 0, `Unsupported peer tooling dependency ${key}`); + packages[key] = structuredClone(record); + for (const name of Object.keys(record.dependencies ?? {})) include(resolve(key, name)); + } + for (const [name, version] of Object.entries(tooling)) { + const key = `node_modules/${name}`; + assert.equal(source.packages[key]?.version, version, `Source lock must pin ${name}@${version}`); + include(key); + } + return { manifest: { ...manifest, devDependencies: tooling }, + lock: { ...consumer, packages } }; +} diff --git a/npm/packages/e-means/test/offline-tooling-lock.test.mjs b/npm/packages/e-means/test/offline-tooling-lock.test.mjs new file mode 100644 index 0000000000..39dd4bf31f --- /dev/null +++ b/npm/packages/e-means/test/offline-tooling-lock.test.mjs @@ -0,0 +1,50 @@ +import assert from 'node:assert/strict'; +import test from 'node:test'; +import { offlineToolingLock } from './offline-tooling-lock.mjs'; + +function fixture() { + const record = (name, version, dependencies = {}) => ({ version, dev: true, dependencies, + resolved: `https://registry.npmjs.org/${name}/-/${name.split('/').at(-1)}-${version}.tgz`, integrity: 'sha512-fixture' }); + const source = { lockfileVersion: 3, packages: { + 'node_modules/@metaharness/darwin': record('@metaharness/darwin', '0.13.0', { '@babel/parser': '^7.29.13' }), + 'node_modules/@babel/parser': record('@babel/parser', '7.29.13', { '@babel/types': '^7.29.11' }), + 'node_modules/@babel/types': record('@babel/types', '7.29.11', { '@babel/helper-string-parser': '^7.29.11', '@babel/helper-validator-identifier': '^7.29.7' }), + 'node_modules/@babel/helper-string-parser': record('@babel/helper-string-parser', '7.29.13'), + 'node_modules/@babel/helper-validator-identifier': record('@babel/helper-validator-identifier', '7.29.7'), + 'node_modules/typescript': record('typescript', '5.9.3'), + 'node_modules/unrelated-build-tool': record('unrelated-build-tool', '1.0.0'), + } }; + const manifest = { private: true, type: 'module', dependencies: { '@ruvector/e-means': 'file:actual-shared.tgz' } }; + const own = { version: '0.1.0', resolved: 'file:actual-shared.tgz', integrity: 'sha512-actual-shared-fixture', + peerDependencies: { '@metaharness/darwin': '0.13.0 || 0.13.1' }, peerDependenciesMeta: { '@metaharness/darwin': { optional: true } } }; + const consumer = { lockfileVersion: 3, packages: { '': { dependencies: manifest.dependencies }, 'node_modules/@ruvector/e-means': own } }; + return { source, consumer, manifest }; +} + +test('minimal tooling graph preserves every source record and the actual packed shared record', () => { + const { source, consumer, manifest } = fixture(); + const original = structuredClone({ source, consumer, manifest }); + const result = offlineToolingLock(source, consumer, manifest); + assert.equal(Object.keys(result.lock.packages).length, 8); // root + own + six registry records + assert.ok(!Object.hasOwn(result.lock.packages, 'node_modules/unrelated-build-tool')); + assert.deepEqual(result.lock.packages['node_modules/@ruvector/e-means'], consumer.packages['node_modules/@ruvector/e-means']); + for (const [key, value] of Object.entries(result.lock.packages)) { + if (key && key !== 'node_modules/@ruvector/e-means') assert.deepEqual(value, source.packages[key]); + } + assert.deepEqual(result.manifest.devDependencies, { '@metaharness/darwin': '0.13.0', typescript: '5.9.3' }); + assert.deepEqual(result.lock.packages[''].devDependencies, result.manifest.devDependencies); + assert.deepEqual({ source, consumer, manifest }, original); +}); + +test('missing transitive records, changed tools, missing integrity and non-registry bytes fail closed', () => { + for (const mutation of ['transitive', 'version', 'integrity', 'registry', 'peer', 'shared']) { + const { source, consumer, manifest } = fixture(); + if (mutation === 'transitive') delete source.packages['node_modules/@babel/types']; + if (mutation === 'version') source.packages['node_modules/typescript'].version = '5.9.2'; + if (mutation === 'integrity') delete source.packages['node_modules/@babel/parser'].integrity; + if (mutation === 'registry') source.packages['node_modules/@babel/parser'].resolved = 'https://example.com/parser.tgz'; + if (mutation === 'peer') source.packages['node_modules/@babel/parser'].peerDependencies = { missing: '*' }; + if (mutation === 'shared') consumer.packages['node_modules/@ruvector/e-means'].resolved = 'https://registry.npmjs.org/shared.tgz'; + assert.throws(() => offlineToolingLock(source, consumer, manifest), undefined, mutation); + } +}); diff --git a/npm/packages/e-means/test/packed-consumer.mjs b/npm/packages/e-means/test/packed-consumer.mjs index 5bc838f64e..6953df6c19 100644 --- a/npm/packages/e-means/test/packed-consumer.mjs +++ b/npm/packages/e-means/test/packed-consumer.mjs @@ -4,6 +4,7 @@ import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'; import { tmpdir } from 'node:os'; import { join } from 'node:path'; import { fileURLToPath } from 'node:url'; +import { offlineToolingLock } from './offline-tooling-lock.mjs'; const packageDir = fileURLToPath(new URL('../', import.meta.url)); const temp = await mkdtemp(join(tmpdir(), 'e-means-consumer-')); @@ -47,9 +48,16 @@ try { process.stdout.write(run(process.execPath, ['consumer.mjs'])); const installed = JSON.parse(await readFile(join(temp, 'node_modules/@ruvector/e-means/package.json'))); assert.equal(installed.version, '0.1.0'); - // Cached pinned registry packages only: installation and qualification do not - // execute dependency lifecycle scripts or contact the registry. - run('npm', ['install', '--offline', '--ignore-scripts', '--no-audit', '--no-fund', '@metaharness/darwin@0.13.0', 'typescript@5.9.3']); + // npm ci cached the source lock's tarballs, not necessarily registry package + // metadata. Transfer only the exact SDK/tool closure and the actual phase-one + // shared archive record, then install without any name/version resolution. + const sourceLock = JSON.parse(await readFile(join(packageDir, 'package-lock.json'))); + const consumerLock = JSON.parse(await readFile(join(temp, 'package-lock.json'))); + const consumerManifest = JSON.parse(await readFile(join(temp, 'package.json'))); + const offline = offlineToolingLock(sourceLock, consumerLock, consumerManifest); + await writeFile(join(temp, 'package.json'), JSON.stringify(offline.manifest)); + await writeFile(join(temp, 'package-lock.json'), JSON.stringify(offline.lock)); + run('npm', ['ci', '--offline', '--ignore-scripts', '--no-audit', '--no-fund']); await writeFile(join(temp, 'meta-consumer.mjs'), ` import assert from 'node:assert/strict'; import { tuneClustering } from '@ruvector/e-means/metaharness'; From efdfdad2a4c414264ab66354f85d75bd2955b208 Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 14:07:11 -0500 Subject: [PATCH 14/19] Qualify real Darwin tuning on the Node 20 minimum --- .github/workflows/e-means-preflight.yml | 2 +- .../e-means/integrations/metaharness.mjs | 22 ++++++-- .../e-means/test/offline-tooling-lock.mjs | 52 +++++++++++++++---- .../test/offline-tooling-lock.test.mjs | 17 +++++- scripts/e-means/release.py | 5 ++ scripts/e-means/test_release.py | 37 +++++++++++++ 6 files changed, 118 insertions(+), 17 deletions(-) diff --git a/.github/workflows/e-means-preflight.yml b/.github/workflows/e-means-preflight.yml index e945dcc9c4..6e44942011 100644 --- a/.github/workflows/e-means-preflight.yml +++ b/.github/workflows/e-means-preflight.yml @@ -68,7 +68,7 @@ jobs: with: name: e-means-candidate-${{ github.sha }} path: ${{ runner.temp }}/e-means-node20 - - name: Exercise sealed portable runtime and PQ/IVF on the advertised Node minimum + - name: Exercise sealed portable runtime, PQ/IVF and actual Darwin tuning on the advertised Node minimum run: python3 scripts/e-means/release.py node20 --expected-sha "$GITHUB_SHA" --directory "$RUNNER_TEMP/e-means-node20" - name: Preserve Node minimum command logs when qualification fails if: failure() diff --git a/npm/packages/e-means/integrations/metaharness.mjs b/npm/packages/e-means/integrations/metaharness.mjs index 5a14ba0ad5..4aef515413 100644 --- a/npm/packages/e-means/integrations/metaharness.mjs +++ b/npm/packages/e-means/integrations/metaharness.mjs @@ -85,10 +85,24 @@ const DARWIN_VERSIONS = ['0.13.0', '0.13.1']; async function loadDarwin() { const { readFile } = await import('node:fs/promises'); - let entry; - try { entry = import.meta.resolve('@metaharness/darwin'); } - catch (cause) { throw new Error(`tuneClustering requires optional peer @metaharness/darwin (${DARWIN_VERSIONS.join(' or ')})`, { cause }); } - const manifest = JSON.parse(await readFile(new URL('../package.json', entry), 'utf8')); + const missingPeer = cause => new Error(`tuneClustering requires optional peer @metaharness/darwin (${DARWIN_VERSIONS.join(' or ')})`, { cause }); + let manifest; + if (typeof import.meta.resolve === 'function') { + let entry; + try { entry = import.meta.resolve('@metaharness/darwin'); } + catch (cause) { throw missingPeer(cause); } + manifest = JSON.parse(await readFile(new URL('../package.json', entry), 'utf8')); + } else { + // Node 20.0 predates unflagged import.meta.resolve. Search standard package + // directories without requiring Darwin's import-only exported entrypoint. + const { createRequire } = await import('node:module'); + const { join } = await import('node:path'); + for (const directory of createRequire(import.meta.url).resolve.paths('@metaharness/darwin') ?? []) { + try { manifest = JSON.parse(await readFile(join(directory, '@metaharness/darwin/package.json'), 'utf8')); break; } + catch (cause) { if (cause.code !== 'ENOENT') throw cause; } + } + if (!manifest) throw missingPeer(); + } if (manifest.name !== '@metaharness/darwin' || !DARWIN_VERSIONS.includes(manifest.version)) throw new Error(`Expected @metaharness/darwin ${DARWIN_VERSIONS.join(' or ')}`); const { evolveNumeric } = await import('@metaharness/darwin'); if (typeof evolveNumeric !== 'function') throw new Error('Darwin numeric API is unavailable'); diff --git a/npm/packages/e-means/test/offline-tooling-lock.mjs b/npm/packages/e-means/test/offline-tooling-lock.mjs index dffada9b65..784f17dee3 100644 --- a/npm/packages/e-means/test/offline-tooling-lock.mjs +++ b/npm/packages/e-means/test/offline-tooling-lock.mjs @@ -1,19 +1,13 @@ import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import { readFile } from 'node:fs/promises'; +import { pathToFileURL } from 'node:url'; const tooling = { '@metaharness/darwin': '0.13.0', typescript: '5.9.3' }; -/** Reuse exact registry records; never resolve package names or repack tooling. */ -export function offlineToolingLock(source, consumer, manifest) { +function toolingPackages(source) { assert.equal(source.lockfileVersion, 3, 'source tooling requires a v3 lock'); - assert.equal(consumer.lockfileVersion, 3, 'consumer requires a v3 lock'); - assert.deepEqual(Object.keys(manifest.dependencies ?? {}), ['@ruvector/e-means']); - assert.deepEqual(consumer.packages[''].dependencies, manifest.dependencies); - const own = consumer.packages['node_modules/@ruvector/e-means']; - assert.equal(own?.version, '0.1.0', 'retain the actually installed shared archive'); - assert.ok(own.resolved?.startsWith('file:') && own.integrity?.startsWith('sha512-')); - const packages = { '': { ...consumer.packages[''], devDependencies: tooling }, - 'node_modules/@ruvector/e-means': own }; - + const packages = {}; function resolve(from, name) { for (let prefix = from; ; ) { const key = `${prefix ? `${prefix}/` : ''}node_modules/${name}`; @@ -30,6 +24,7 @@ export function offlineToolingLock(source, consumer, manifest) { const url = new URL(record.resolved); assert.equal(url.protocol, 'https:'); assert.equal(url.hostname, 'registry.npmjs.org'); + assert.ok(!url.username && !url.password && !url.search && !url.hash && url.pathname.includes('/-/') && url.pathname.endsWith('.tgz'), 'Expected a canonical registry tarball URL'); assert.ok(record.integrity?.startsWith('sha512-'), `Missing integrity for ${key}`); // Current pinned tools have no optional or peer closure. Reject a changed // graph explicitly instead of silently resolving missing registry metadata. @@ -43,6 +38,41 @@ export function offlineToolingLock(source, consumer, manifest) { assert.equal(source.packages[key]?.version, version, `Source lock must pin ${name}@${version}`); include(key); } + return packages; +} + +/** Only the six exact SDK/compiler closure tarballs; never package metadata. */ +export function toolingTarballURLs(source) { + const urls = Object.values(toolingPackages(source)).map(record => record.resolved); + assert.equal(urls.length, 6, 'Expected six minimal tooling tarballs'); + assert.equal(new Set(urls).size, 6, 'Tooling tarballs must be unique'); + return urls; +} + +/** Reuse exact registry records; never resolve package names or repack tooling. */ +export function offlineToolingLock(source, consumer, manifest) { + assert.equal(consumer.lockfileVersion, 3, 'consumer requires a v3 lock'); + assert.deepEqual(Object.keys(manifest.dependencies ?? {}), ['@ruvector/e-means']); + assert.deepEqual(consumer.packages[''].dependencies, manifest.dependencies); + const own = consumer.packages['node_modules/@ruvector/e-means']; + assert.equal(own?.version, '0.1.0', 'retain the actually installed shared archive'); + assert.ok(own.resolved?.startsWith('file:') && own.integrity?.startsWith('sha512-')); + const packages = { '': { ...consumer.packages[''], devDependencies: tooling }, + 'node_modules/@ruvector/e-means': own, ...toolingPackages(source) }; + return { manifest: { ...manifest, devDependencies: tooling }, lock: { ...consumer, packages } }; } + +// This is an explicit prefetch step. All subsequent consumer installs stay +// offline and enforce the original source lock's integrity hashes via npm ci. +if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) { + assert.equal(process.argv[2], 'warm'); + assert.equal(process.argv.length, 4); + const source = JSON.parse(await readFile(process.argv[3], 'utf8')); + for (const url of toolingTarballURLs(source)) { + const result = spawnSync('npm', ['cache', 'add', url, '--ignore-scripts', '--workspaces=false'], { stdio: 'inherit' }); + assert.equal(result.status, 0, `Failed to warm locked tooling tarball: ${url}`); + } + console.log('Warmed six lock-bound tooling tarballs without package metadata'); +} diff --git a/npm/packages/e-means/test/offline-tooling-lock.test.mjs b/npm/packages/e-means/test/offline-tooling-lock.test.mjs index 39dd4bf31f..6a3b86857a 100644 --- a/npm/packages/e-means/test/offline-tooling-lock.test.mjs +++ b/npm/packages/e-means/test/offline-tooling-lock.test.mjs @@ -1,6 +1,6 @@ import assert from 'node:assert/strict'; import test from 'node:test'; -import { offlineToolingLock } from './offline-tooling-lock.mjs'; +import { offlineToolingLock, toolingTarballURLs } from './offline-tooling-lock.mjs'; function fixture() { const record = (name, version, dependencies = {}) => ({ version, dev: true, dependencies, @@ -48,3 +48,18 @@ test('missing transitive records, changed tools, missing integrity and non-regis assert.throws(() => offlineToolingLock(source, consumer, manifest), undefined, mutation); } }); + +test('cache warming selects only six locked tarball URLs and rejects metadata endpoints', () => { + const { source } = fixture(); + const urls = toolingTarballURLs(source); + assert.equal(urls.length, 6); + assert.deepEqual(urls, Object.values(source.packages).slice(0, 6).map(row => row.resolved)); + for (const url of ['https://registry.npmjs.org/@babel/parser', 'https://registry.npmjs.org/parser/-/parser.tgz?metadata=true']) { + const modified = structuredClone(source); + modified.packages['node_modules/@babel/parser'].resolved = url; + assert.throws(() => toolingTarballURLs(modified), /tarball URL/); + } + source.packages['node_modules/@babel/parser'].dependencies.unexpected = '*'; + source.packages['node_modules/unexpected'] = { ...source.packages['node_modules/typescript'], resolved: 'https://registry.npmjs.org/unexpected/-/unexpected-1.0.0.tgz' }; + assert.throws(() => toolingTarballURLs(source), /six minimal/); +}); diff --git a/scripts/e-means/release.py b/scripts/e-means/release.py index 88921cc0a1..b900eee272 100644 --- a/scripts/e-means/release.py +++ b/scripts/e-means/release.py @@ -308,8 +308,13 @@ def node20(source, base): execute(['npm', 'install', '--ignore-scripts', '--offline', '--no-audit', '--no-fund', str(base / f'ruvector-e-means-{VERSION}.tgz')], consumer, consumer, commands) installed = consumer / 'node_modules/@ruvector/e-means' shutil.copytree(base / 'harness/test', installed / 'test') + shutil.copyfile(base / 'harness/package-lock.json', installed / 'package-lock.json') selected = ['e-means', 'runtime', 'typed-bridge', 'quantization', 'ivf'] execute(['node', '--test', '--test-reporter=tap', *[str(installed / f'test/{name}.test.mjs') for name in selected]], consumer, consumer, commands, 'node') + # The portable runtime first proves optional-SDK absence. Warm only the six + # source-lock tarballs, then require real offline Darwin tuning and types. + execute(['node', str(installed / 'test/offline-tooling-lock.mjs'), 'warm', str(installed / 'package-lock.json')], consumer, consumer, commands) + execute(['node', str(installed / 'test/packed-consumer.mjs')], consumer, consumer, commands, 'consumer') def select_and_download(source, base): diff --git a/scripts/e-means/test_release.py b/scripts/e-means/test_release.py index c6167dc5aa..36aff474ef 100644 --- a/scripts/e-means/test_release.py +++ b/scripts/e-means/test_release.py @@ -311,3 +311,40 @@ def test_npm_public_bytes_must_match_registry_sha512_integrity(self): if __name__ == '__main__': unittest.main() + + +class Node20Consumer(unittest.TestCase): + def test_minimum_runtime_requires_portable_tests_then_lock_bound_full_consumer(self): + with tempfile.TemporaryDirectory() as temp: + base = Path(temp) / 'candidate' + harness = base / 'harness' + (harness / 'test').mkdir(parents=True) + (harness / 'test/packed-consumer.mjs').write_text('owned packed consumer') + (harness / 'package-lock.json').write_text('exact sealed tooling lock') + calls = [] + + def execute(args, cwd, evidence, commands, kind=None): + calls.append((args, cwd, kind)) + if len(calls) == 1: + (cwd / 'node_modules/@ruvector/e-means').mkdir(parents=True) + if kind == 'consumer': + self.assertEqual((cwd / 'node_modules/@ruvector/e-means/package-lock.json').read_text(), 'exact sealed tooling lock') + self.assertEqual((cwd / 'node_modules/@ruvector/e-means/test/packed-consumer.mjs').read_text(), 'owned packed consumer') + return '' + + with patch.object(release, 'identity'), patch.object(release, 'validate_candidate'), patch.object(release, 'execute', side_effect=execute): + release.node20('a' * 40, base) + consumer = base.parent / 'node20-consumer' + installed = consumer / 'node_modules/@ruvector/e-means' + self.assertEqual(len(calls), 4) + self.assertIn('--offline', calls[0][0]) + self.assertEqual(calls[1][0][:3], ['node', '--test', '--test-reporter=tap']) + self.assertEqual(calls[1][2], 'node') + self.assertEqual(calls[2], (['node', str(installed / 'test/offline-tooling-lock.mjs'), 'warm', str(installed / 'package-lock.json')], consumer, None)) + self.assertEqual(calls[3], (['node', str(installed / 'test/packed-consumer.mjs')], consumer, 'consumer')) + + def test_partial_full_consumer_markers_do_not_qualify(self): + with tempfile.TemporaryDirectory() as temp: + output = '\n'.join(release.CONSUMER_MARKERS[:1]) + with self.assertRaisesRegex(ValueError, 'Installed archive consumer'): + release.execute([sys.executable, '-c', f'print({output!r})'], Path(temp), Path(temp), [], 'consumer') From 1532ee8d7dcab8db54cdf9704547f553a35fe16a Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 14:07:56 -0500 Subject: [PATCH 15/19] Document real minimum-runtime and lock-bound offline qualification --- docs/adr/ADR-359-e-means-shared-clustering.md | 5 ++++- docs/e-means-release.md | 6 +++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/adr/ADR-359-e-means-shared-clustering.md b/docs/adr/ADR-359-e-means-shared-clustering.md index da1289c54e..c5e7696458 100644 --- a/docs/adr/ADR-359-e-means-shared-clustering.md +++ b/docs/adr/ADR-359-e-means-shared-clustering.md @@ -14,7 +14,10 @@ was corrected and its missing-route mutation fails. PQ/IVF validators inspect typed-array storage without caller-defined iterators. Local qualification of the archived-source WASM build passed native/MSRV, npm, installed-consumer, workerd and real Chromium checks; registry publication remains subject to the -exact-source protected workflow and fresh public consumers. +exact-source protected workflow and fresh public consumers. The minimum Node +20.0 job now exercises actual Darwin tuning as well as the portable APIs; +explicit TAP reporting and lock-bound offline tooling avoid reporter and npm +metadata-cache assumptions. ## Context and scope diff --git a/docs/e-means-release.md b/docs/e-means-release.md index 9b48686d4b..d9dd5f8692 100644 --- a/docs/e-means-release.md +++ b/docs/e-means-release.md @@ -13,7 +13,11 @@ The WASM build explicitly retains the workspace release optimization settings. The copied npm package then runs its dependency audit, real WASM/Worker tests, strict declarations, installed consumers with and without the optional SDK, and real Chromium numerical checks before packing. A second job installs the -sealed archive offline and exercises the portable APIs on Node 20.0.0. +sealed archive offline and exercises the portable APIs on Node 20.0.0. It then +warm-caches only six exact tooling tarball URLs from the sealed lock, requires +real offline Darwin tuning and strict installed declarations, and never relies +on cached registry package metadata. The Node 20.0 tuning path uses lazy +package-manifest lookup when unflagged `import.meta.resolve` is unavailable. Both `qualify` and `node20` must succeed on the same release-branch push; a successful local seal or a pull-request merge commit cannot substitute for that immutable pre-main qualification. From 7600dcd46daa3ee7421c86a09684b8e7f346860b Mon Sep 17 00:00:00 2001 From: ruvnet Date: Wed, 11 Nov 2026 14:18:40 -0500 Subject: [PATCH 16/19] Qualify actual e-means browser results through pinned Playwright --- .github/workflows/e-means-preflight.yml | 1 + .../workflows/e-means-protected-release.yml | 1 + docs/e-means-release.md | 4 +- npm/packages/e-means/README.md | 10 ++- .../e-means/test/browser-consumer.mjs | 89 +++++++++++-------- scripts/e-means/test_browser_consumer.py | 72 +++++++++++++++ 6 files changed, 138 insertions(+), 39 deletions(-) create mode 100644 scripts/e-means/test_browser_consumer.py diff --git a/.github/workflows/e-means-preflight.yml b/.github/workflows/e-means-preflight.yml index 6e44942011..83a0982c74 100644 --- a/.github/workflows/e-means-preflight.yml +++ b/.github/workflows/e-means-preflight.yml @@ -35,6 +35,7 @@ jobs: npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + echo "E_MEANS_PLAYWRIGHT_ROOT=$RUNNER_TEMP/browser-tools" >> "$GITHUB_ENV" - name: Exercise release guards run: python3 -m unittest discover -s scripts/e-means -p 'test_*.py' -v - name: Build exact archives and execute native, installed, Worker and browser consumers diff --git a/.github/workflows/e-means-protected-release.yml b/.github/workflows/e-means-protected-release.yml index 0046153339..35f60fd25b 100644 --- a/.github/workflows/e-means-protected-release.yml +++ b/.github/workflows/e-means-protected-release.yml @@ -51,6 +51,7 @@ jobs: npm install --prefix "$RUNNER_TEMP/browser-tools" --ignore-scripts --no-save playwright@1.62.1 "$RUNNER_TEMP/browser-tools/node_modules/.bin/playwright" install chromium node -e 'const p=require(process.env.RUNNER_TEMP+"/browser-tools/node_modules/playwright"); console.log("E_MEANS_CHROMIUM="+p.chromium.executablePath())' >> "$GITHUB_ENV" + echo "E_MEANS_PLAYWRIGHT_ROOT=$RUNNER_TEMP/browser-tools" >> "$GITHUB_ENV" - name: Test fresh public registry consumers without publication credentials env: GH_TOKEN: ${{ github.token }} diff --git a/docs/e-means-release.md b/docs/e-means-release.md index d9dd5f8692..8df375f37d 100644 --- a/docs/e-means-release.md +++ b/docs/e-means-release.md @@ -12,7 +12,9 @@ execute the packaged Rust tests, and build WASM from the extracted archive. The WASM build explicitly retains the workspace release optimization settings. The copied npm package then runs its dependency audit, real WASM/Worker tests, strict declarations, installed consumers with and without the optional SDK, -and real Chromium numerical checks before packing. A second job installs the +and real Chromium numerical checks before packing. The externally installed +Playwright 1.62.1 driver waits for the actual page result and verifies successful +module, runtime and default WASM responses; it does not depend on CLI DOM dumping. A second job installs the sealed archive offline and exercises the portable APIs on Node 20.0.0. It then warm-caches only six exact tooling tarball URLs from the sealed lock, requires real offline Darwin tuning and strict installed declarations, and never relies diff --git a/npm/packages/e-means/README.md b/npm/packages/e-means/README.md index 121ff27951..64e69577ea 100644 --- a/npm/packages/e-means/README.md +++ b/npm/packages/e-means/README.md @@ -23,7 +23,15 @@ Node reads the bundled WASM from disk. In browsers, serve the `.wasm` artifact b From a source checkout: install the `wasm32-unknown-unknown` Rust target and `wasm-bindgen-cli` version `0.2.125`, then run `npm run build`, `npm test` and `npm run test:consumer` in this package. `npm pack` verifies the built runtime before creating an archive. The archive contains the runtime and needs neither Rust nor the source repository. -`npm run typecheck` validates the declarations. `npm run test:browser` runs the same numerical oracle in headless Chromium against the default browser loader; set `E_MEANS_CHROMIUM` when Chromium is not on `PATH`. +`npm run typecheck` validates the declarations. `npm run test:browser` uses external Playwright 1.62.1 tooling to run the numerical oracle in real headless Chromium against the default browser loader. Bootstrap the development-only driver outside this package: + +```sh +npm install --prefix /tmp/e-means-browser-tools --ignore-scripts --no-save playwright@1.62.1 +/tmp/e-means-browser-tools/node_modules/.bin/playwright install chromium +E_MEANS_PLAYWRIGHT_ROOT=/tmp/e-means-browser-tools npm run test:browser +``` + +`E_MEANS_CHROMIUM` can select an existing Chromium executable. Qualification requires successful module/runtime/WASM responses and the typed numerical result; browser errors or missing routes fail. `npm run benchmark -- --baseline /path/to/previous/package --repeats 7` measures median fit and prediction time on one million scalar rows and an embedding codebook workload. It also compares JSON and typed output on the same current Rust kernel. The baseline argument is optional; retain the previous package's module and WASM together. Run benchmarks without other compute workloads; results describe the current machine and these fixtures. diff --git a/npm/packages/e-means/test/browser-consumer.mjs b/npm/packages/e-means/test/browser-consumer.mjs index 0d77e9f57e..e86f83ae75 100644 --- a/npm/packages/e-means/test/browser-consumer.mjs +++ b/npm/packages/e-means/test/browser-consumer.mjs @@ -1,11 +1,11 @@ import assert from 'node:assert/strict'; -import { spawn } from 'node:child_process'; +import { constants } from 'node:fs'; +import { createRequire } from 'node:module'; import { createServer } from 'node:http'; -import { mkdtemp, readFile, rm } from 'node:fs/promises'; -import { tmpdir } from 'node:os'; -import { join } from 'node:path'; +import { access, readFile } from 'node:fs/promises'; +import { resolve } from 'node:path'; -const page = `