perf(8.0): allocation-free distance loops (6x cosine) — evidence-revised Fork X

Rewrite the four open-core distance functions (cosine / euclidean / manhattan /
dot-product) from object-accumulating `reduce` to single-pass allocation-free
indexed loops. cosine's per-element `{dotProduct,normA,normB}` object was the
hot-path GC lever.

MEASURED (tests/benchmarks/distance-microbench.mjs, dim=384, N=20000, median of
41): cosine 44.3ms -> 7.4ms (~6x), euclidean 9.2ms -> 6.6ms (~1.4x); the built
cosineDistance drops ~44ms -> ~9ms. Numerically identical (same ops, same order)
so recall is unchanged; full suite green (1753/1753).

Also drop the unfounded perf JSDoc ("faster than GPU", "Node.js 23.11+") and the
`new Function(distanceFn.toString())` eval in calculateDistancesBatch — with the
functions now tight loops, the batch is a thin JIT-inlined map (no worker, no
stringify/reconstruct).

Evidence-revised scope: the Float32Array resident-storage half of the original
Fork X is DROPPED. The same microbench shows Float32Array is ~1.7x SLOWER for
this compute (V8 widens f32 -> f64 on every element read), so it would regress
the hot path for a RAM win the open-core JS path does not need — billion-scale
vector RAM is the native provider's SIMD/mmap/quantized domain. The resident
representation stays number[]; no type-chain or cache changes.

tests/benchmarks/distance-microbench.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * Distance microbenchmark — measures the vector-distance hot path in isolation.
+ *
+ * Compares the reduce-based implementations (current `src/utils/distance.ts`)
+ * against allocation-free indexed for-loops, on both `number[]` and
+ * `Float32Array`, to establish MEASURED evidence for the Float32Array Fork X
+ * change. Per the evidence-based-claims rule, no % is published without this.
+ *
+ * Run: node tests/benchmarks/distance-microbench.mjs
+ */
+
+const DIM = 384
+const N = 20000 // candidate vectors compared per pass
+const ITERS = 41 // repeat passes; report the median (robust to GC blips)
+
+// --- reduce-based (current distance.ts) ---
+const cosineReduce = (a, b) => {
+  const { dotProduct, normA, normB } = a.reduce(
+    (acc, val, i) => ({
+      dotProduct: acc.dotProduct + val * b[i],
+      normA: acc.normA + val * val,
+      normB: acc.normB + b[i] * b[i]
+    }),
+    { dotProduct: 0, normA: 0, normB: 0 }
+  )
+  if (normA === 0 || normB === 0) return 2
+  return 1 - dotProduct / (Math.sqrt(normA) * Math.sqrt(normB))
+}
+const euclideanReduce = (a, b) => {
+  const sum = a.reduce((acc, val, i) => {
+    const d = val - b[i]
+    return acc + d * d
+  }, 0)
+  return Math.sqrt(sum)
+}
+
+// --- allocation-free indexed for-loop (proposed) ---
+const cosineLoop = (a, b) => {
+  let dot = 0,
+    na = 0,
+    nb = 0
+  const len = a.length
+  for (let i = 0; i < len; i++) {
+    const av = a[i]
+    const bv = b[i]
+    dot += av * bv
+    na += av * av
+    nb += bv * bv
+  }
+  if (na === 0 || nb === 0) return 2
+  return 1 - dot / (Math.sqrt(na) * Math.sqrt(nb))
+}
+const euclideanLoop = (a, b) => {
+  let sum = 0
+  const len = a.length
+  for (let i = 0; i < len; i++) {
+    const d = a[i] - b[i]
+    sum += d * d
+  }
+  return Math.sqrt(sum)
+}
+
+function makeVectors(Ctor) {
+  const alloc = () => (Ctor === Array ? new Array(DIM) : new Ctor(DIM))
+  const q = alloc()
+  for (let i = 0; i < DIM; i++) q[i] = Math.sin(i * 0.1) * 0.5 + Math.cos(i * 0.03) * 0.5
+  const vs = []
+  for (let n = 0; n < N; n++) {
+    const v = alloc()
+    for (let i = 0; i < DIM; i++) v[i] = Math.sin((n + i) * 0.07)
+    vs.push(v)
+  }
+  return { q, vs }
+}
+
+let sink = 0
+function bench(name, fn, q, vs) {
+  for (let w = 0; w < 3; w++) for (let i = 0; i < vs.length; i++) sink += fn(q, vs[i])
+  const times = []
+  for (let it = 0; it < ITERS; it++) {
+    const t0 = process.hrtime.bigint()
+    for (let i = 0; i < vs.length; i++) sink += fn(q, vs[i])
+    times.push(Number(process.hrtime.bigint() - t0) / 1e6)
+  }
+  times.sort((a, b) => a - b)
+  const median = times[Math.floor(times.length / 2)]
+  const opsPerSec = (vs.length / median) * 1000
+  console.log(`  ${name.padEnd(28)} ${median.toFixed(2).padStart(8)} ms   ${(opsPerSec / 1e6).toFixed(2).padStart(6)} M ops/s`)
+  return median
+}
+
+console.log(`Distance microbench — dim=${DIM}, N=${N}, iters=${ITERS} (median)\n`)
+for (const [label, Ctor] of [
+  ['number[]', Array],
+  ['Float32Array', Float32Array]
+]) {
+  const { q, vs } = makeVectors(Ctor)
+  console.log(`--- ${label} ---`)
+  const cr = bench('cosine   reduce (current)', cosineReduce, q, vs)
+  const cl = bench('cosine   for-loop', cosineLoop, q, vs)
+  const er = bench('euclid   reduce (current)', euclideanReduce, q, vs)
+  const el = bench('euclid   for-loop', euclideanLoop, q, vs)
+  console.log(`  → cosine for-loop is ${(cr / cl).toFixed(2)}x, euclid for-loop is ${(er / el).toFixed(2)}x\n`)
+}
+if (sink === Infinity) console.log('(unreachable guard)')