test(8.0): A/B benchmark harness (open leg) — generic corpus+metrics lib, brainy-alone scaling bench, boundary guard, real-embedding recall guard

The open-core, Cortex-free half of the library A/B (handoff AJ/AK), authored once in
brainy so the proprietary A/B comparison can import it for both legs:

- tests/benchmarks/lib/corpus.js — deterministic clustered-mixture corpus generator
  (recompute-on-demand, O(clusters·dim) memory) for latency/ingest/memory at scale.
- tests/benchmarks/lib/metrics.js — percentiles, brute-force recall@k, RSS snapshot.
- tests/benchmarks/brainy-scale.js — brainy-alone scaling leg (ingest, find p50/p99 for
  vector/metadata/graph/triple, RSS). Recall is intentionally NOT measured on synthetic
  data — see below.
- tests/unit/boundary-no-cortex.test.ts — CI guard: fails if @soulcraft/cortex ever
  appears in a src/ or tests/ import or in any package.json dependency field.
- tests/integration/vector-recall.test.ts — semantic-search correctness on REAL
  embeddings (19-20/20 exact-text top-1).

Methodology note: synthetic vectors (random/one-hot/clustered/latent) are near-orthogonal
under cosine, so HNSW (any graph ANN, incl. DiskANN) cannot navigate them and recall
collapses regardless of engine — a property of the data, not the index. Brainy vector
search is verified correct on real embeddings. The A/B recall@10 column is therefore
measured on SIFT/BIGANN, identically for both legs.

tests/benchmarks/lib/corpus.js

@@ -0,0 +1,135 @@
+/**
+ * @module tests/benchmarks/lib/corpus
+ * @description Deterministic synthetic-corpus generator for scaling benchmarks —
+ * the single source of truth so the open-core leg and the (proprietary) A/B
+ * comparison leg measure the IDENTICAL workload. Vectors follow a
+ * mixture-of-clusters distribution (clusters of related points + small noise),
+ * which is closer to real embedding geometry than uniform-random and is the
+ * worst case to avoid for product quantization — matching the methodology used
+ * by the native-provider benchmark suite so columns are comparable.
+ *
+ * Everything is recomputed on demand from a seed + index (no large arrays held),
+ * so a 1M / 10M corpus costs O(clusters·dim) memory, not O(n·dim). Same seed ⇒
+ * byte-identical corpus across runs, machines, and the two A/B legs.
+ *
+ * Cortex-free by construction: this is generic MIT benchmark tooling, usable by
+ * any open-core consumer to benchmark their own deployment. It is NOT shipped in
+ * the npm package (tests/ is outside `files`).
+ */
+
+/**
+ * @description Deterministic 32-bit LCG (Numerical Recipes constants). Returns a
+ * closure producing floats in [0, 1). Seeded so every run is reproducible.
+ * @param seed - 32-bit unsigned seed.
+ * @returns A function returning the next pseudo-random float in [0, 1).
+ */
+export function makeRng(seed = 0x12345678) {
+  let state = seed >>> 0
+  return () => {
+    state = (Math.imul(state, 1664525) + 1013904223) >>> 0
+    return state / 4294967296
+  }
+}
+
+/**
+ * @description Number of cluster centres for a corpus of `n` points:
+ * `min(1024, max(64, floor(sqrt(n))))`. Sub-linear so clusters stay dense as the
+ * corpus grows (matches the native-suite generator).
+ * @param n - Corpus size.
+ * @returns The cluster count.
+ */
+export function clusterCount(n) {
+  return Math.min(1024, Math.max(64, Math.floor(Math.sqrt(n))))
+}
+
+/**
+ * @description Build a deterministic corpus descriptor for `n` entities of
+ * dimension `dim`. Nothing large is allocated up front: cluster centres
+ * (clusters·dim) are materialized once; every entity vector, its metadata, the
+ * query set, and the hub→neighbour edge set are recomputed on demand from the
+ * seed and the index.
+ *
+ * @param opts - Corpus parameters.
+ * @param opts.n - Number of entities.
+ * @param opts.dim - Vector dimension (default 384, the all-MiniLM-L6-v2 size).
+ * @param opts.seed - Master seed (default 0x12345678).
+ * @param opts.noise - Per-component uniform noise added to a cluster centre (default 0.1).
+ * @param opts.categories - Distinct values for the `category` metadata field (default 10).
+ * @param opts.hubs - Entities that get an out-edge neighbourhood (default min(n/10, 1000)).
+ * @param opts.fanout - Out-edges per hub (default 100).
+ * @returns A descriptor exposing `vector(i)`, `metadata(i)`, `queryVector(j)`,
+ *   `neighborIndex(hub, f)`, plus the resolved parameters.
+ */
+export function makeCorpus(opts) {
+  const n = opts.n
+  const dim = opts.dim ?? 384
+  const seed = (opts.seed ?? 0x12345678) >>> 0
+  const noise = opts.noise ?? 0.1
+  const categories = opts.categories ?? 10
+  const clusters = clusterCount(n)
+  const hubs = opts.hubs ?? Math.min(Math.floor(n / 10) || 1, 1000)
+  const fanout = opts.fanout ?? 100
+
+  // Materialize cluster centres once (clusters · dim floats — small).
+  // Components are CENTERED in [-1, 1) so clusters separate by both DIRECTION
+  // (cosine — Brainy's default metric) and DISTANCE (L2 — the native/pgvector
+  // metric). A positive-orthant corpus would be degenerate under cosine and
+  // tank recall, so the shared corpus must be fair to both metrics.
+  const centerRng = makeRng(seed ^ 0x9e3779b9)
+  const centers = new Array(clusters)
+  for (let c = 0; c < clusters; c++) {
+    const v = new Array(dim)
+    for (let d = 0; d < dim; d++) v[d] = centerRng() * 2 - 1
+    centers[c] = v
+  }
+
+  /** Deterministic per-index noise stream (decorrelated from the centre stream). */
+  const noiseAt = (i) => makeRng((seed + 0x85ebca6b * (i + 1)) >>> 0)
+
+  return {
+    n, dim, seed, clusters, hubs, fanout, categories,
+
+    /**
+     * @returns A deterministic, collision-free, UUID-shaped id for entity `i`
+     * (the index is encoded in the node field). Used so the caller never depends
+     * on `addMany` completion order to know which id holds which vector — the
+     * id↔index map is exact, which recall and the edge graph both require.
+     */
+    id(i) {
+      return `00000000-0000-4000-8000-${i.toString(16).padStart(12, '0')}`
+    },
+
+    /** @returns The vector for entity `i`: its cluster centre + seeded noise. */
+    vector(i) {
+      const center = centers[i % clusters]
+      const r = noiseAt(i)
+      const v = new Array(dim)
+      for (let d = 0; d < dim; d++) v[d] = center[d] + (r() * 2 - 1) * noise
+      return v
+    },
+
+    /** @returns Deterministic metadata for entity `i`. */
+    metadata(i) {
+      const r = noiseAt(i ^ 0x1234)
+      return { idx: i, category: i % categories, score: Math.floor(r() * 1000), active: (i & 1) === 0 }
+    },
+
+    /**
+     * @returns A query vector for query `j`: near a deterministically chosen
+     * cluster (drawn from the SAME distribution as the corpus, distinct stream).
+     */
+    queryVector(j) {
+      const c = j % clusters
+      const center = centers[c]
+      const r = makeRng((seed + 0xc2b2ae35 * (j + 1)) >>> 0)
+      const v = new Array(dim)
+      for (let d = 0; d < dim; d++) v[d] = center[d] + (r() * 2 - 1) * noise
+      return v
+    },
+
+    /** @returns The global index of out-neighbour `f` of `hub` (deterministic, wraps within n). */
+    neighborIndex(hub, f) {
+      return (hub * fanout + f + hubs) % n
+    }
+  }
+}

tests/benchmarks/lib/metrics.js

@@ -0,0 +1,112 @@
+/**
+ * @module tests/benchmarks/lib/metrics
+ * @description Measurement helpers for scaling benchmarks: latency percentiles,
+ * brute-force recall@k ground truth, and a memory snapshot. Generic MIT
+ * benchmark tooling shared by the open-core leg and the A/B comparison so every
+ * column is computed identically. Recall uses cosine distance to match Brainy's
+ * default index metric (`this.distance = cosineDistance`).
+ *
+ * Not shipped in the npm package (tests/ is outside `files`).
+ */
+
+/**
+ * @description The p-th percentile of an already-ascending-sorted array.
+ * @param sorted - Ascending-sorted samples.
+ * @param p - Percentile in [0, 100].
+ * @returns The sample at the percentile (nearest-rank).
+ */
+export function percentile(sorted, p) {
+  if (sorted.length === 0) return NaN
+  const idx = Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))
+  return sorted[idx]
+}
+
+/**
+ * @description Summarize a list of latency samples (milliseconds).
+ * @param latMs - Latency samples in ms (any order).
+ * @returns `{ p50, p95, p99, mean, n }`.
+ */
+export function summarize(latMs) {
+  const s = [...latMs].sort((a, b) => a - b)
+  const mean = s.reduce((acc, x) => acc + x, 0) / (s.length || 1)
+  return { p50: percentile(s, 50), p95: percentile(s, 95), p99: percentile(s, 99), mean, n: s.length }
+}
+
+/** @description High-resolution elapsed-ms timer around an async function. */
+export async function timed(fn) {
+  const t = process.hrtime.bigint()
+  const value = await fn()
+  return { ms: Number(process.hrtime.bigint() - t) / 1e6, value }
+}
+
+/**
+ * @description Cosine distance (`1 - cosineSimilarity`) — matches Brainy's
+ * default index metric, so brute-force ground truth ranks identically to the index.
+ * @param a - First vector.
+ * @param b - Second vector.
+ * @returns Cosine distance in [0, 2].
+ */
+export function cosineDistance(a, b) {
+  let dot = 0, na = 0, nb = 0
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb)
+  return denom === 0 ? 1 : 1 - dot / denom
+}
+
+/**
+ * @description Exact top-k indices for `query` by ascending cosine distance over
+ * the whole corpus — the recall ground truth. O(n·dim) per query, so call it on a
+ * sample of queries, not all of them.
+ * @param query - Query vector.
+ * @param getVector - `(i) => number[]` corpus accessor.
+ * @param n - Corpus size.
+ * @param k - Neighbours to return.
+ * @returns Array of the k nearest corpus indices, nearest first.
+ */
+export function bruteForceTopK(query, getVector, n, k) {
+  const heap = [] // small: keep k best as {i, d}
+  for (let i = 0; i < n; i++) {
+    const d = cosineDistance(query, getVector(i))
+    if (heap.length < k) {
+      heap.push({ i, d })
+      if (heap.length === k) heap.sort((a, b) => a.d - b.d)
+    } else if (d < heap[k - 1].d) {
+      // insert in order, drop the worst
+      let pos = k - 1
+      while (pos > 0 && heap[pos - 1].d > d) { heap[pos] = heap[pos - 1]; pos-- }
+      heap[pos] = { i, d }
+    }
+  }
+  return heap.slice(0, k).map((e) => e.i)
+}
+
+/**
+ * @description recall@k = |approx ∩ truth| / |truth|. Keys must be comparable
+ * (map entity ids to corpus indices, or vice-versa, before calling).
+ * @param approxKeys - Keys the index returned.
+ * @param truthKeys - Ground-truth keys.
+ * @returns Recall in [0, 1].
+ */
+export function recallAtK(approxKeys, truthKeys) {
+  if (truthKeys.length === 0) return 1
+  const truth = new Set(truthKeys)
+  let hit = 0
+  for (const k of approxKeys) if (truth.has(k)) hit++
+  return hit / truthKeys.length
+}
+
+/**
+ * @description Process memory snapshot, optionally per-entity.
+ * @param entityCount - Optional entity count for the per-entity figure.
+ * @returns `{ rssGB, heapGB, rssBytesPerEntity }`.
+ */
+export function memSnapshot(entityCount) {
+  const m = process.memoryUsage()
+  return {
+    rssGB: +(m.rss / 1e9).toFixed(3),
+    heapGB: +(m.heapUsed / 1e9).toFixed(3),
+    rssBytesPerEntity: entityCount ? Math.round(m.rss / entityCount) : null
+  }
+}