@seanhogg/builderforce-memory 2026.10.28 → 2026.10.29

package/src/retrieval/mmr.ts

@@ -18,6 +18,7 @@
  */
 
 import { cosineSimilarity, jaccardSimilarity, tokenize } from '../similarity/index.js';
+import { compareHits, compareIds, quantizeScore, DENSE_SCORE_QUANTUM } from './order.js';
 
 export interface MmrSelectOptions<T> {
     /** Relevance of one candidate, on the same scale as {@link similarity}. */
@@ -29,19 +30,44 @@ export interface MmrSelectOptions<T> {
     /** Stop after this many picks. Default: every candidate. */
     topK?: number;
     /**
-     * Breaks an exact MMR tie in favour of the higher value. Without it the earlier
-     * candidate wins, so input order decides.
+     * Breaks an MMR tie in favour of the higher value. Ties are judged on the MMR
+     * score quantized to {@link quantum}.
      */
     tieScore?: (item: T) => number;
+    /**
+     * The candidate's id — the last tie-break, ascending. Without it the explicit
+     * id is the candidate's index in `items`, so the earlier candidate wins.
+     */
+    idOf?: (item: T) => string;
+    /** Quantum the MMR score is compared at. Default 1e-4 (cosine noise). */
+    quantum?: number;
 }
 
 /** Greedy MMR selection. Returns the picked candidates in pick order. */
 export function mmrSelect<T>(items: readonly T[], opts: MmrSelectOptions<T>): T[] {
     const lambda = opts.lambda ?? 0.7;
+    const quantum = opts.quantum ?? DENSE_SCORE_QUANTUM;
     const limit = Math.min(opts.topK ?? items.length, items.length);
     const remaining = [...items];
     const relevance = new Map<T, number>();
-    for (const item of remaining) relevance.set(item, opts.relevance(item));
+    const position = new Map<T, number>();
+    items.forEach((item, i) => {
+        relevance.set(item, opts.relevance(item));
+        if (!position.has(item)) position.set(item, i);
+    });
+    const idOf = (item: T): string | number => (opts.idOf ? opts.idOf(item) : position.get(item)!);
+    // Higher quantized MMR score, then higher tieScore, then lower id.
+    const beats = (a: T, aScore: number, b: T, bScore: number): boolean => {
+        const qa = quantizeScore(aScore, quantum);
+        const qb = quantizeScore(bScore, quantum);
+        if (qa !== qb) return qa > qb;
+        if (opts.tieScore) {
+            const ta = opts.tieScore(a);
+            const tb = opts.tieScore(b);
+            if (ta !== tb) return ta > tb;
+        }
+        return compareIds(idOf(a), idOf(b)) < 0;
+    };
 
     const selected: T[] = [];
     while (selected.length < limit && remaining.length > 0) {
@@ -55,10 +81,7 @@ export function mmrSelect<T>(items: readonly T[], opts: MmrSelectOptions<T>): T[
                 if (sim > maxSimToSelected) maxSimToSelected = sim;
             }
             const score = lambda * relevance.get(candidate)! - (1 - lambda) * maxSimToSelected;
-            const wins = score > bestScore
-                || (score === bestScore && bestIdx >= 0 && opts.tieScore !== undefined
-                    && opts.tieScore(candidate) > opts.tieScore(remaining[bestIdx]!));
-            if (wins) { bestScore = score; bestIdx = i; }
+            if (bestIdx < 0 || beats(candidate, score, remaining[bestIdx]!, bestScore)) { bestScore = score; bestIdx = i; }
         }
         if (bestIdx < 0) break;
         selected.push(remaining.splice(bestIdx, 1)[0]!);
@@ -87,6 +110,7 @@ export function maximalMarginalRelevance(
         similarity: (a, b) => cosineSimilarity(a.vector, b.vector),
         lambda,
         topK,
+        idOf: (c) => c.id,
     }).map((c) => c.id);
 }
 
@@ -101,13 +125,13 @@ export interface TextMmrItem {
 /**
  * Text MMR. Reorders every item, judging diversity by Jaccard similarity of word
  * tokens, and relevance by the item's `score` min-max normalised onto [0,1] (all
- * equal → 1). An exact tie goes to the higher raw score. `lambda` is clamped to
- * [0,1]; at 1 this is a plain score sort.
+ * equal → 1). A tie goes to the higher raw score, then the lower id. `lambda` is
+ * clamped to [0,1]; at 1 this is a plain {@link compareHits} sort.
  */
 export function textMaximalMarginalRelevance<T extends TextMmrItem>(items: readonly T[], lambda = 0.7): T[] {
     if (items.length <= 1) return [...items];
     const l = Math.max(0, Math.min(1, lambda));
-    if (l === 1) return [...items].sort((a, b) => b.score - a.score);
+    if (l === 1) return [...items].sort(compareHits);
 
     const tokens = new Map<string, Set<string>>();
     for (const item of items) tokens.set(item.id, new Set(tokenize(item.content)));
@@ -122,5 +146,6 @@ export function textMaximalMarginalRelevance<T extends TextMmrItem>(items: reado
         similarity: (a, b) => jaccardSimilarity(tokensOf(a), tokensOf(b)),
         lambda: l,
         tieScore: (item) => item.score,
+        idOf: (item) => item.id,
     });
 }

package/src/retrieval/order.ts

@@ -0,0 +1,68 @@
+/**
+ * order.ts — the ONE total order every ranker in this package returns.
+ *
+ * Score descending, then id ascending. Scores are quantized before they are
+ * compared, so float noise in the last bits (a CPU vs a WebGPU embedding, a
+ * different summation order) cannot flip a near-tie: two scores in the same
+ * quantum ARE tied, and the id decides. Without this, ties fell back to input
+ * order, and input order is not part of any index's state.
+ *
+ * Quanta: dense (cosine) scores to 1e-4, BM25 / RRF and other exact-arithmetic
+ * scores to 1e-6. Ids compare by UTF-16 code unit (`<`), never `localeCompare`,
+ * which depends on the host's ICU data.
+ *
+ * Pure and zero-dependency.
+ */
+
+/** Quantum for cosine / dot-product scores — absorbs cross-platform float noise. */
+export const DENSE_SCORE_QUANTUM = 1e-4;
+/** Quantum for BM25, RRF and other scores computed in exact-enough arithmetic. */
+export const LEXICAL_SCORE_QUANTUM = 1e-6;
+
+/** The quantized bucket of `score`. NaN sorts last; ±Infinity keep their place. */
+export function quantizeScore(score: number, quantum: number = LEXICAL_SCORE_QUANTUM): number {
+    if (Number.isNaN(score)) return -Infinity;
+    if (!Number.isFinite(score)) return score;
+    return Math.round(score / quantum);
+}
+
+/** Ascending id order by code unit. Numeric ids (a doc index) compare numerically. */
+export function compareIds(a: string | number, b: string | number): number {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * The primitive behind {@link compareHits}, for callers whose items keep score and
+ * id apart (a node index → id lookup inside a graph walk) — no object per compare.
+ */
+export function compareScoreThenId(
+    scoreA: number,
+    idA: string | number,
+    scoreB: number,
+    idB: string | number,
+    quantum: number = LEXICAL_SCORE_QUANTUM,
+): number {
+    const qa = quantizeScore(scoreA, quantum);
+    const qb = quantizeScore(scoreB, quantum);
+    if (qa !== qb) return qb > qa ? 1 : -1;
+    return compareIds(idA, idB);
+}
+
+/** A ranked item: anything with an id and a score. */
+export interface ScoredId {
+    id: string | number;
+    score: number;
+}
+
+/**
+ * Score descending (quantized), then id ascending. Usable directly as an
+ * `Array.prototype.sort` comparator (the quantum then defaults to 1e-6).
+ */
+export function compareHits(a: ScoredId, b: ScoredId, quantum: number = LEXICAL_SCORE_QUANTUM): number {
+    return compareScoreThenId(a.score, a.id, b.score, b.id, quantum);
+}
+
+/** {@link compareHits} at the dense quantum (1e-4) — for cosine-scored lists. */
+export function compareDenseHits(a: ScoredId, b: ScoredId): number {
+    return compareScoreThenId(a.score, a.id, b.score, b.id, DENSE_SCORE_QUANTUM);
+}

package/src/retrieval/weightedFusion.ts

@@ -14,6 +14,8 @@
  * Pure and zero-dependency.
  */
 
+import { compareScoreThenId, DENSE_SCORE_QUANTUM } from './order.js';
+
 /** Weight on the semantic arm when a caller states none. */
 export const DEFAULT_HYBRID_VECTOR_WEIGHT = 0.7;
 /** Weight on the lexical arm when a caller states none. */
@@ -70,7 +72,8 @@ export function bm25RankToScore(rank: number): number {
 
 /**
  * Fuse two arms keyed by a caller-supplied id and return the candidates ordered
- * best-first. `merge` builds the output row from the winning payload of each id;
+ * best-first: fused score (quantized at the dense quantum — the vector arm carries
+ * float noise) descending, then id ascending. `merge` builds the output row from the winning payload of each id;
  * later duplicates of the same id keep the first payload seen (arm order decides).
  */
 export function fuseHybridArms<TVector extends { id: string }, TText extends { id: string }, TOut>(params: {
@@ -91,11 +94,11 @@ export function fuseHybridArms<TVector extends { id: string }, TText extends { i
         if (existing) existing.scores.textScore = params.textScoreOf(row);
         else byId.set(row.id, { row, scores: { vectorScore: 0, textScore: params.textScoreOf(row) } });
     }
-    return [...byId.values()]
-        .map((entry) => {
+    return [...byId.entries()]
+        .map(([id, entry]) => {
             const score = hybridScore(entry.scores, weights);
-            return { out: params.merge(entry.row, score), score };
+            return { id, out: params.merge(entry.row, score), score };
         })
-        .sort((a, b) => b.score - a.score)
+        .sort((a, b) => compareScoreThenId(a.score, a.id, b.score, b.id, DENSE_SCORE_QUANTUM))
         .map((entry) => entry.out);
 }

package/src/vectorstore/MemoryVectorStore.ts

@@ -20,6 +20,7 @@
 
 import { bm25Search } from '../retrieval/bm25.js';
 import { HnswIndex, type HnswOptions } from '../retrieval/hnsw.js';
+import { compareScoreThenId, DENSE_SCORE_QUANTUM } from '../retrieval/order.js';
 import { cosineSimilarity } from '../similarity/index.js';
 import { combineFilters, matchesFilter } from './filter.js';
 import type {
@@ -192,7 +193,7 @@ export class MemoryVectorStore implements VectorStore {
         const exactScan = () => embedded
             .filter((r) => matchesFilter(r.metadata, filter))
             .map((r) => ({ record: r, score: cosineSimilarity(vector, r.vector as Float32Array) }))
-            .sort((a, b) => b.score - a.score);
+            .sort((a, b) => compareScoreThenId(a.score, a.record.id, b.score, b.record.id, DENSE_SCORE_QUANTUM));
 
         if (embedded.length < this._annThreshold) return exactScan();