@ultimat3/cache 28.0.0 → 29.0.0

package/README.md

@@ -430,6 +430,13 @@ is a driver seam for that reason; a Postgres/pgvector-backed implementation does
 yet here (`@ultimat3/ai`'s `postgresVectorStore()` is a separate store, for RAG retrieval, not this
 cache).
 
+A similarity that is not a number is not a match. A pair with no defined cosine — one side
+carrying a `NaN` component, or a dot product and norms that overflow together — makes
+`cosineSimilarity` answer `NaN`: honestly, rather than a `0` that would rank a directionless
+vector above every opposed one. The lookup SKIPS such a record: it misses, rather than answering
+one question with another's entry. Every comparison against `NaN` is false, so a record that
+reached the floor unchecked would have passed it, at any floor — `0` included.
+
 ## Errors
 
 | Code | Cause |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "28.0.0",
+  "version": "29.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -25,13 +25,13 @@
     "LICENSE"
   ],
   "engines": {
-    "bun": ">=1.4.3"
+    "bun": ">=1.4.4"
   },
   "scripts": {
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "28.0.0"
+    "@ultimat3/core": "29.0.0"
   }
 }

package/src/semantic.ts

@@ -54,6 +54,17 @@ export interface SemanticCacheOptions {
   readonly clock?: Clock;
 }
 
+/**
+ * Cosine similarity — and the honest answer for a pair that has none: a `NaN` component, or a
+ * dot product and norms that overflow together (`1e200` on both sides), leaves the cosine
+ * UNDEFINED, and this answers `NaN` rather than a `0` that would rank a vector with no direction
+ * above every opposed one (the rule `@ultimat3/ai`'s `cosine` keeps on purpose).
+ *
+ * `NaN` is not a verdict — the CALLER decides what a nonfinite similarity means. `lookup` skips
+ * a record whose similarity is not finite: it is not a candidate, so the entry cannot answer a
+ * question it was never asked. A finite similarity is the floor's business, as any other is — a
+ * finite dot over an overflowing norm is the `0`, and the floor decides it.
+ */
 export function cosineSimilarity(a: Embedding, b: Embedding): number {
   if (a.length !== b.length || a.length === 0) return 0;
   let dot = 0;
@@ -114,6 +125,11 @@ export function memorySemanticCache(options: SemanticCacheOptions = {}): Semanti
       let best: SemanticHit<T> | undefined;
       for (const record of live()) {
         const similarity = cosineSimilarity(embedding, record.embedding);
+        // A similarity that is not a number is not a match. Every comparison against `NaN` is
+        // false, so a broken vector SKIPPED the floor below, became `best`, and the cache
+        // answered a question it was never asked — a worse failure than a miss, because nothing
+        // said so. The floor did not fail to hold; the comparison against it never happened.
+        if (!Number.isFinite(similarity)) continue;
         if (similarity < floor) continue;
         if (best === undefined || similarity > best.similarity) {
           best = { value: record.value as T, similarity, key: record.key };