Skip auto-binary when sign-bit codes are degenerate

Embeddings with all-non-negative components (TF-IDF-style, ReLU final
layers) pack to identical sign-bit codes, so once a corpus crossed the
auto-binary threshold, phase-1 Hamming ranking was pure ties and
approximate search picked candidates near-randomly: recall@1 measured
1/5 on a 10k corpus, and no rerankFactor or probe setting could repair
it. Auto-binary now also requires the codes to spread (expected Hamming
distance of at least dimension/16, estimated from per-bit frequencies
over a strided sample); degenerate corpora keep the exact scan, which
is correct and no slower. Explicit binary/clusters options are honored
unchanged.

Author: platypii

src/constants.js

@@ -49,3 +49,17 @@ export const defaultClusterProbeCap = 48
 // the corpus is at least this large. Below the threshold, exact full scan
 // is fast enough that the rerank path's overhead isn't worth the column.
 export const defaultAutoBinaryThreshold = 10000
+
+// Auto-binary also requires the sign-bit codes to discriminate: when the
+// expected Hamming distance between two random vectors falls below
+// dimension * defaultBinaryMinSpread, phase-1 binary ranking is dominated
+// by ties (embeddings with all-non-negative components share one code) and
+// approximate search degenerates to a near-random candidate pick that no
+// rerankFactor can repair. Exact scan is correct and no slower in that
+// regime. 1/16 sits far below healthy embeddings (mixed-sign embeddings
+// measure ~0.3-0.5 of dimension) and far above degenerate ones (~0).
+export const defaultBinaryMinSpread = 1 / 16
+
+// Rows sampled (evenly strided) when estimating the sign-bit spread. Per-bit
+// one-frequencies converge fast, so a few thousand rows suffice at any N.
+export const binarySpreadSample = 4096

src/utils.js

@@ -1,3 +1,5 @@
+import { binarySpreadSample } from './constants.js'
+
 /**
  * @import { DistanceMetric, HypVectorMetadata } from './types.js'
  * @import { FileMetaData, KeyValue } from 'hyparquet'
@@ -114,6 +116,38 @@ export function packBinary(v, dim = v.length) {
   return bytes
 }
 
+/**
+ * Expected Hamming distance between two random rows of packed binary codes,
+ * from per-bit one-frequencies: sum over bits of 2 * p * (1 - p). Identical
+ * codes measure 0; independent fair bits measure dimension / 2. Rows are
+ * sampled with an even stride when there are more than sampleCap, which is
+ * plenty to estimate per-bit frequencies at any corpus size.
+ *
+ * @param {Uint8Array[]} codes packed binary codes (see packBinary)
+ * @param {number} dimension vector dimension
+ * @param {number} [sampleCap] max rows to sample
+ * @returns {number} expected Hamming distance in bits
+ */
+export function expectedHamming(codes, dimension, sampleCap = binarySpreadSample) {
+  if (!codes.length) return 0
+  const stride = Math.max(1, Math.ceil(codes.length / sampleCap))
+  const ones = new Uint32Array(dimension)
+  let sampled = 0
+  for (let row = 0; row < codes.length; row += stride) {
+    const code = codes[row]
+    for (let i = 0; i < dimension; i += 1) {
+      if (code[i >> 3] >> (i & 7) & 1) ones[i] += 1
+    }
+    sampled += 1
+  }
+  let expected = 0
+  for (let i = 0; i < dimension; i += 1) {
+    const p = ones[i] / sampled
+    expected += 2 * p * (1 - p)
+  }
+  return expected
+}
+
 /**
  * Unpack a Uint8Array of raw little-endian float32 bytes into a Float32Array.
  * Always returns a fresh aligned copy, since the source buffer may be

src/writeVectors.js

@@ -3,14 +3,15 @@ import { binaryKMeans, reorderClustersByHamming } from './cluster.js'
 import {
   defaultAutoBinaryThreshold,
   defaultBinaryColumn,
+  defaultBinaryMinSpread,
   defaultBinaryPageSize,
   defaultClusterIterations,
   defaultIdColumn,
   defaultRowGroupSize,
   defaultVectorColumn,
   hypVectorVersion,
 } from './constants.js'
-import { encodeBase64, l2Normalize, packBinary, packFloat32 } from './utils.js'
+import { encodeBase64, expectedHamming, l2Normalize, packBinary, packFloat32 } from './utils.js'
 
 /**
  * @import { VectorRecord, WriteVectorsOptions } from './types.js'
@@ -99,8 +100,14 @@ export async function writeVectors({
 
   // Resolve auto defaults now that we know N. Auto-clusters only fires
   // when the caller also let `binary` auto; explicit `binary: true` means
-  // "add the column, don't reshuffle rows".
-  if (autoBinary) binary = ids.length >= defaultAutoBinaryThreshold
+  // "add the column, don't reshuffle rows". Degenerate sign-bit codes
+  // (e.g. embeddings with all-non-negative components) are all ties, which
+  // would make phase-1 ranking near-random, so auto-binary also requires
+  // the codes to spread; without the column, search stays an exact scan.
+  if (autoBinary) {
+    binary = ids.length >= defaultAutoBinaryThreshold &&
+      expectedHamming(packedBin, dimension) >= dimension * defaultBinaryMinSpread
+  }
   binary = binary === true
   const clusterCount = clusters ?? (autoBinary && binary ? Math.max(1, Math.round(Math.sqrt(ids.length) / 2)) : 0)
   // Clustering operates on the binary codes, so it implies the binary column

test/utils.test.js

@@ -3,7 +3,9 @@ import {
   cosineSimilarity,
   dotProduct,
   euclideanDistance,
+  expectedHamming,
   l2Normalize,
+  packBinary,
 } from '../src/utils.js'
 
 describe('dotProduct', () => {
@@ -51,3 +53,24 @@ describe('l2Normalize', () => {
     expect(Array.from(n)).toEqual([0, 0, 0])
   })
 })
+
+describe('expectedHamming', () => {
+  it('measures 0 for identical codes and dim/2 for fair bits', () => {
+    const dimension = 16
+    const same = Array.from({ length: 100 }, () => packBinary(new Float32Array(dimension).fill(1)))
+    expect(expectedHamming(same, dimension)).toBe(0)
+    // half all-positive, half all-negative: every bit is a fair coin
+    const fair = Array.from({ length: 100 }, (_, i) =>
+      packBinary(new Float32Array(dimension).fill(i % 2 ? 1 : -1)))
+    expect(expectedHamming(fair, dimension)).toBeCloseTo(dimension / 2)
+  })
+
+  it('samples with an even stride on large inputs', () => {
+    const dimension = 8
+    // sign pattern with no period, so any sampling stride sees both signs
+    const fair = Array.from({ length: 20000 }, (_, i) =>
+      packBinary(new Float32Array(dimension).fill(Math.sin(i * 12.9898) > 0 ? 1 : -1)))
+    expect(expectedHamming(fair, dimension, 1000)).toBeCloseTo(dimension / 2, 0)
+    expect(expectedHamming([], dimension)).toBe(0)
+  })
+})

test/writeVectors.test.js

@@ -104,6 +104,29 @@ describe('writeVectors', () => {
     expect(find('hypvector.clusters')).toBe('50')
   })
 
+  it('skips auto-binary at large N when the sign-bit codes are degenerate', async () => {
+    const dimension = 32
+    const writer = fileWriter(TEST_FILE)
+    // all-non-negative components share one sign-bit code, so binary
+    // phase-1 ranking would be pure ties: keep the exact scan instead
+    const vectors = makeVectors(10000, dimension).map(({ id, vector }) => ({
+      id, vector: vector.map(Math.abs),
+    }))
+    await writeVectors({ writer, dimension, vectors })
+    const file = await asyncBufferFromFile(TEST_FILE)
+    const meta = await parquetMetadataAsync(file)
+    /**
+     * @param {string} key
+     * @returns {string | undefined}
+     */
+    function find(key) {
+      return meta.key_value_metadata?.find(e => e.key === key)?.value
+    }
+    expect(find('hypvector.binary')).toBe('false')
+    expect(find('hypvector.clusters')).toBe('0')
+    expect(meta.schema.some(e => e.name === 'vector_bin')).toBe(false)
+  })
+
   it('forces the binary column when clusters are requested below the auto-binary threshold', async () => {
     const dimension = 32 // binaryBytes must be a multiple of 4 for k-means
     const writer = fileWriter(TEST_FILE)