@tpsdev-ai/flair-bench 0.49.0 → 0.51.0

package/dist/cosine.d.ts

@@ -11,11 +11,11 @@
 export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
 /**
  * 0-based rank of `targetIndex` within `corpusVectors` when sorted by
- * descending cosine similarity to `query`. Ties are broken by corpus
- * insertion order (stable sort — Array.prototype.sort is guaranteed stable
- * since ES2019/V8 since Node 11), the simplest documented tie-break
- * available without reverse-engineering Harper's own HNSW/BM25-RRF
- * tie-break internals. See README's "exact-vs-HNSW caveat" for what this
- * does and doesn't guarantee to reproduce.
+ * descending cosine similarity to `query`. Ties break on corpus `.index`
+ * ascending (the total-order tail — not `.id`; this ranking never has one).
+ * Input order of the scored array must not leak: the same corpus in two
+ * permutations of equal-score rows ranks identically (flair#1412).
+ * See README's "exact-vs-HNSW caveat" for what this does and doesn't
+ * guarantee to reproduce of Harper's HNSW.
  */
 export declare function rankOf(query: readonly number[], corpusVectors: readonly (readonly number[])[], targetIndex: number): number;

package/dist/cosine.js

@@ -8,6 +8,7 @@
  * (251 records), and the reason the tool can claim exact recall numbers
  * rather than approximate ones.
  */
+import { compareKey } from "./sort-comparators.js";
 export function cosineSimilarity(a, b) {
     if (a.length !== b.length) {
         throw new Error(`cosineSimilarity: dimension mismatch (${a.length} vs ${b.length})`);
@@ -28,15 +29,15 @@ export function cosineSimilarity(a, b) {
 }
 /**
  * 0-based rank of `targetIndex` within `corpusVectors` when sorted by
- * descending cosine similarity to `query`. Ties are broken by corpus
- * insertion order (stable sort — Array.prototype.sort is guaranteed stable
- * since ES2019/V8 since Node 11), the simplest documented tie-break
- * available without reverse-engineering Harper's own HNSW/BM25-RRF
- * tie-break internals. See README's "exact-vs-HNSW caveat" for what this
- * does and doesn't guarantee to reproduce.
+ * descending cosine similarity to `query`. Ties break on corpus `.index`
+ * ascending (the total-order tail — not `.id`; this ranking never has one).
+ * Input order of the scored array must not leak: the same corpus in two
+ * permutations of equal-score rows ranks identically (flair#1412).
+ * See README's "exact-vs-HNSW caveat" for what this does and doesn't
+ * guarantee to reproduce of Harper's HNSW.
  */
 export function rankOf(query, corpusVectors, targetIndex) {
     const scored = corpusVectors.map((v, index) => ({ index, score: cosineSimilarity(query, v) }));
-    scored.sort((x, y) => y.score - x.score);
+    scored.sort((x, y) => (y.score - x.score) || compareKey(x.index, y.index));
     return scored.findIndex((s) => s.index === targetIndex);
 }

package/dist/sort-comparators.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generic total-order tail (flair#1412). Same helper as
+ * `resources/sort-comparators.ts` — copied so this package stays
+ * standalone (no flair install, no Harper). Cosine ranking keys on
+ * corpus `.index`, not `.id`; force-fitting `byNumberDescThenId` here
+ * would be the over-abstraction the #1412 spec names as the failure mode.
+ *
+ * Locale-independent code-unit / numeric comparison — not localeCompare.
+ */
+export declare function compareKey<T extends string | number>(a: T, b: T): number;

package/dist/sort-comparators.js

@@ -0,0 +1,12 @@
+/**
+ * Generic total-order tail (flair#1412). Same helper as
+ * `resources/sort-comparators.ts` — copied so this package stays
+ * standalone (no flair install, no Harper). Cosine ranking keys on
+ * corpus `.index`, not `.id`; force-fitting `byNumberDescThenId` here
+ * would be the over-abstraction the #1412 spec names as the failure mode.
+ *
+ * Locale-independent code-unit / numeric comparison — not localeCompare.
+ */
+export function compareKey(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}

package/dist/version.d.ts

@@ -5,4 +5,4 @@
  * attribute edge cases in a published dist/ build. test/version-sync.test.ts
  * asserts this stays equal to package.json's "version" field.
  */
-export declare const TOOL_VERSION = "0.49.0";
+export declare const TOOL_VERSION = "0.51.0";

package/dist/version.js

@@ -5,4 +5,4 @@
  * attribute edge cases in a published dist/ build. test/version-sync.test.ts
  * asserts this stays equal to package.json's "version" field.
  */
-export const TOOL_VERSION = "0.49.0";
+export const TOOL_VERSION = "0.51.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-bench",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Standalone embedding recall benchmark for flair — run real recall numbers (p@3/MRR) against any GGUF embedding model, batch-compare, get a host-aware recommendation, and share redacted results. No flair install required.",
   "type": "module",
   "main": "dist/index.js",