@maximem/synap-js-sdk 0.5.8 → 0.5.9

package/dist/{chunk-T6U5PVAD.cjs → chunk-ICUFS3B5.cjs}

@@ -1,6 +1,7 @@
 "use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class; var _class2;
 
 
+
 var _chunkZKOJDUN4cjs = require('./chunk-ZKOJDUN4.cjs');
 
 // src/behavior/anticipation.json
@@ -352,6 +353,191 @@ var anticipation_default = {
         note: "sorted by key, so `customer=ab` and this cannot collapse"
       }
     ]
+  },
+  semantic_match: {
+    $comment: "Matching a fetch query to prefetched items by meaning, with the SDK's local embedding model (`model`, which history search uses too). An item's score is its best cosine to the query, over the item's own text and the questions it answers (its HQEs, sent with the bundle item; item_questions), with the query as asked and with the asker's pronouns in the third person (canonical_query). Three bands: at sure_min_cosine or above the cache answers; between min_cosine and sure_min_cosine the match is borderline and the SDK asks the server too, serving the server's answer if it arrives within race_deadline_ms and the cached one if not; below min_cosine the server answers. A hit also serves items at serve_min_cosine or above, and items from a bundle holding a hit at bundle_serve_min_cosine or above. asked_kind: a question that asks for a time of day, a duration or an amount is not answered by served items holding none (asked_details). Items not embedded yet, and every item without the model, are matched as before (BM25 with its novel-term gate). The thresholds hold for `model` only, one text per run. Measured on harnesses/anticipation_match (404 labelled queries, 4 languages, production-shaped bundles with production-prompt HQEs), held-out half, per 100 questions with the answer cached for 68: BM25 served 27 right and 13 wrong; MiniLM on the memory text alone 30 and 5.5; with all of the above (sure bar 0.74) 44-47 and 2.5-3, 21 Oct 2026.",
+    model: "onnx:Xenova/paraphrase-multilingual-MiniLM-L12-v2@2c4055b12046f11709e9df2c122e59ffbdc2f900/onnx/model_quantized.onnx",
+    mode: "semantic",
+    min_cosine: 0.66,
+    serve_min_cosine: 0.4,
+    asked_kind: true,
+    max_queries: 4,
+    item_questions: true,
+    canonical_query: "both",
+    self_pronouns: {
+      $comment: "canonical_query rewrites the asker's own pronouns into the third person memories are stored in ('my landlord' -> 'the user's landlord'). Applied in order, case-insensitive. 'canon' compares only the rewritten query, 'both' takes the better of the two (HQEs are written in the first person).",
+      en: [
+        ["\\b(i am|i'm)\\b", "the user is"],
+        ["\\b(i have|i've)\\b", "the user has"],
+        ["\\b(i was)\\b", "the user was"],
+        ["\\b(my|mine)\\b", "the user's"],
+        ["\\b(i|me|myself)\\b", "the user"]
+      ]
+    },
+    asked_details: {
+      $comment: "asked_kind: a question that asks for one of these kinds of value is not answered by served items that hold none (asked 'what time is my flight', served 'the flight is on 25 October'). Its own list, not history_search.asked_kinds, so history search's ranking is untouched. Query patterns are matched case-insensitively; value patterns are written to be language-neutral (digits, units, currency) and avoid \\\\b next to non-ASCII letters, which ECMAScript's \\\\b does not treat as word characters.",
+      time_of_day: {
+        query: "what time|at what time|which time|opening hours|open hours|what hours|when does .{0,40}(open|close|start|begin)|qu[e\xE9] hora|a qu[e\xE9] hora|que horas|a que horas|hor[a\xE1]rio|\u0915\u093F\u0938 \u0938\u092E\u092F|\u0915\u093F\u0924\u0928\u0947 \u092C\u091C\u0947|\u091F\u093E\u0907\u092E",
+        value: "\\b\\d{1,2}(:\\d{2})? ?([ap]\\.?m\\.?)(\\W|$)|\\b\\d{1,2}:\\d{2}\\b|\\b\\d{1,2}h(\\d{2})?\\b|noon|midnight|mediod[i\xED]a|meio-dia|\u092C\u091C\u0947"
+      },
+      duration: {
+        query: "how long|duration|how many (minutes|hours)|cu[a\xE1]nto dura|cu[a\xE1]nto tiempo|quanto tempo|dura[c\xE7][a\xE3]o|\u0915\u093F\u0924\u0928\u0940 \u0926\u0947\u0930|\u0915\u093F\u0924\u0928\u0947 \u0938\u092E\u092F",
+        value: "\\d+(\\.\\d+)? ?(minutes?|mins?|hours?|hrs?|days?|weeks?|months?|years?|minutos?|horas?|d[i\xED]as|semanas?|meses|a\xF1os|anos|\u092E\u093F\u0928\u091F|\u0918\u0902\u091F\u0947|\u0918\u0902\u091F\u093E|\u0926\u093F\u0928|\u0939\u092B\u094D\u0924\u0947|\u092E\u0939\u0940\u0928\u0947|\u0938\u093E\u0932)"
+      },
+      money: {
+        query: "how much|cost|price|fee|charge|budget|amount|quote|cu[a\xE1]nto cuesta|precio|costo|tarifa|quanto custa|pre[c\xE7]o|valor|custo|\u0915\u093F\u0924\u0928\u0947 \u092A\u0948\u0938\u0947|\u0915\u093F\u0924\u0928\u093E \u092A\u0948\u0938\u093E|\u0915\u0940\u092E\u0924|\u0916\u0930\u094D\u091A|\u0936\u0941\u0932\u094D\u0915|\u0915\u093F\u0924\u0928\u0947 \u0930\u0941\u092A\u092F\u0947",
+        value: "[$\u20AC\xA3\xA5\u20B9]\\s?\\d|\\d[\\d,.]* ?(usd|eur|gbp|inr|brl|mxn|dollars?|euros?|pounds?|rupees?|reais|real|pesos?|\u0930\u0941\u092A\u092F\u0947|\u0930\u0941\u092A\u090F)|\\b(usd|eur|gbp|inr|brl|rs\\.?|r\\$) ?\\d"
+      }
+    },
+    bundle_serve_min_cosine: 0.3,
+    sure_min_cosine: 0.74,
+    race_deadline_ms: 250
+  },
+  history_search: {
+    $comment: `Local search over the raw turns a compaction replaced (COMPACTION_HYBRID_PLAN.md P5). Keyword first (literal values, then BM25 with the bm25 section's tokenizer), embeddings only when installed and keywords come up short; results fused by reciprocal rank with a small recency prior, shown in conversation order. The heading reaches the LLM prompt: byte-identical in both SDKs. Each hit brings the turn before it (its last previous_turn_words words). Irregular past forms are mapped to the base form before stemming (English; history search only). A turn needs min_matched_terms query words, or one word found in at most rare_term_max_share of the turns. Passages (passages, passages_per_turn): a turn longer than max_words_per_excerpt is scored as passages (table rows with their header, a few lines of a log, a few sentences), ranks by its best passage, and shows its best passages; measured 20 Oct with multilingual MiniLM, answer text found 117 of 148 probes vs 93 by whole turns. Tool results the host agent reports are archived here too, never sent to the server, as "[tool result: <name>] <result>" cut to tool_result_max_chars: searchable like turns, not counted as server turns.`,
+    max_excerpts: 6,
+    max_words_per_excerpt: 60,
+    min_matched_terms: 2,
+    rrf_k: 60,
+    recency_weight: 0.5,
+    heading: "### From the earlier turns (verbatim excerpts matched to the latest message; later turns may have changed them)",
+    store_limits: {
+      max_conversations: 200,
+      max_turns_per_conversation: 5e3,
+      max_bytes_per_conversation: 8388608,
+      idle_ttl_seconds: 604800,
+      max_file_bytes: 209715200
+    },
+    previous_turns: 1,
+    previous_turn_words: 40,
+    rare_term_max_share: 0.02,
+    tool_result_max_chars: 16e3,
+    passages: true,
+    passages_per_turn: 2,
+    early_query: {
+      pattern: "\\b(original|originally|initial|initially|at first|at the start|used to|previous|previously|first (draft|version|proposal|quote|offer|reply|round|email|contract))\\b",
+      flags: "i",
+      note: "A question about how things started: no recency prior for it, or later turns on the same subject push the early one out (20 Oct, documents case)."
+    },
+    asked_kinds: {
+      $comment: "A question that asks for a kind of value (a number to call, an email, an address, an amount, a date, a percentage) also ranks the passages that hold one, among those sharing a query word: 'the best number to reach Renata' found her email but showed 'Best, Renata', not the line with the number (20 Oct).",
+      phone: { query: "\\b(phone|mobile|cell|telephone|call|reach|contact|direct line|best number)\\b", value: "(?:\\+\\d{1,3}[\\s.-]?)?\\(?\\d{2,4}\\)?[\\s.-]\\d{3,4}[\\s.-]\\d{3,4}\\b" },
+      email: { query: "\\b(e-?mail|email address|write to)\\b", value: "[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\\.[A-Za-z0-9-]+)+" },
+      address: { query: "\\b(address|street|located|postal|where (is|are|do|does|should))\\b", value: "\\b\\d{1,5}\\s+[A-Z][a-z]+(?:\\s[A-Z][a-z]+)*\\s(?:Street|St|Avenue|Ave|Road|Rd|Boulevard|Blvd|Lane|Ln|Drive|Dr|Way|Court|Ct|Place|Pl|Rua|Avenida)\\b" },
+      money: { query: "\\b(how much|cost|costs|price|fee|fees|charge|charges|pay|paid|budget|amount|quote|quoted|spend)\\b", value: "(?:[$\u20AC\xA3\xA5\u20B9]|\\b(?:USD|EUR|GBP|CAD|INR|AUD)\\s?)\\d" },
+      percent: { query: "(percent|percentage|%)", value: "\\d(?:\\.\\d+)?\\s?%" },
+      date: { query: "\\b(when|what date|which day|deadline|due|by what date)\\b", value: "\\b(?:\\d{4}-\\d{2}-\\d{2}|\\d{1,2}(?:st|nd|rd|th)?\\s+(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*|(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\\s+\\d{1,2})\\b" }
+    },
+    irregular_forms: {
+      sold: "sell",
+      paid: "pay",
+      sent: "send",
+      bought: "buy",
+      made: "make",
+      got: "get",
+      gotten: "get",
+      took: "take",
+      taken: "take",
+      gave: "give",
+      given: "give",
+      went: "go",
+      gone: "go",
+      told: "tell",
+      left: "leave",
+      met: "meet",
+      kept: "keep",
+      found: "find",
+      held: "hold",
+      brought: "bring",
+      thought: "think",
+      flew: "fly",
+      flown: "fly",
+      wrote: "write",
+      written: "write",
+      chose: "choose",
+      chosen: "choose",
+      spoke: "speak",
+      spoken: "speak",
+      broke: "break",
+      broken: "break",
+      began: "begin",
+      begun: "begin",
+      ran: "run",
+      came: "come",
+      saw: "see",
+      seen: "see",
+      knew: "know",
+      known: "know",
+      drove: "drive",
+      driven: "drive",
+      built: "build",
+      spent: "spend",
+      lost: "lose",
+      won: "win",
+      lent: "lend",
+      felt: "feel",
+      heard: "hear",
+      understood: "understand",
+      forgot: "forget",
+      forgotten: "forget",
+      ate: "eat",
+      eaten: "eat",
+      fell: "fall",
+      fallen: "fall",
+      grew: "grow",
+      grown: "grow",
+      hid: "hide",
+      hidden: "hide",
+      rode: "ride",
+      rang: "ring",
+      rose: "rise",
+      sang: "sing",
+      sat: "sit",
+      slept: "sleep",
+      stood: "stand",
+      stole: "steal",
+      swam: "swim",
+      taught: "teach",
+      threw: "throw",
+      thrown: "throw",
+      woke: "wake",
+      wore: "wear",
+      worn: "wear",
+      led: "lead",
+      dealt: "deal",
+      meant: "mean",
+      sought: "seek",
+      caught: "catch",
+      fought: "fight",
+      bent: "bend",
+      bit: "bite",
+      bled: "bleed",
+      blew: "blow",
+      bred: "breed",
+      drew: "draw",
+      drawn: "draw",
+      drank: "drink",
+      fed: "feed",
+      forgave: "forgive",
+      froze: "freeze",
+      hung: "hang",
+      laid: "lay",
+      lit: "light",
+      overpaid: "overpay",
+      rebuilt: "rebuild",
+      resent: "resend",
+      shook: "shake",
+      shot: "shoot",
+      shut: "shut",
+      sank: "sink",
+      slid: "slide",
+      spun: "spin",
+      struck: "strike",
+      swore: "swear",
+      swept: "sweep",
+      tore: "tear",
+      withdrew: "withdraw"
+    }
   }
 };
 
@@ -384,6 +570,8 @@ var BM25_PARAMS = CONTRACT.bm25;
 var STOP_WORDS = new Set(CONTRACT.bm25.stop_words);
 var SUFFIXES = CONTRACT.bm25.suffixes;
 var ALIAS_TOKEN_SOURCE = CONTRACT.bm25.alias_token.pattern;
+var HISTORY_SEARCH = CONTRACT.history_search;
+var SEMANTIC_MATCH = CONTRACT.semantic_match;
 function isRecallQuery(searchQuery) {
   for (const q of _nullishCoalesce(searchQuery, () => ( []))) {
     if (!q) continue;
@@ -497,6 +685,46 @@ function rungKey(scopePath) {
 function rungServes(bundleRung, requestRung) {
   return (bundleRung || null) === (requestRung || null);
 }
+function unownedElsewhere(entryEntity, entryConversation, conversationId) {
+  return entryEntity === ANY_SCOPE && entryConversation !== null && entryConversation !== conversationId;
+}
+function canonicalQuery(query) {
+  let out = query;
+  for (const [lang, rules] of Object.entries(_nullishCoalesce(SEMANTIC_MATCH.self_pronouns, () => ( {})))) {
+    if (lang.startsWith("$") || typeof rules === "string") continue;
+    for (const [pattern, repl] of rules) out = out.replace(new RegExp(pattern, "gi"), repl);
+  }
+  return out;
+}
+function askedDetailPatterns(queries) {
+  const out = [];
+  for (const [name, spec] of Object.entries(_nullishCoalesce(SEMANTIC_MATCH.asked_details, () => ( {})))) {
+    if (name.startsWith("$") || typeof spec !== "object") continue;
+    const q = new RegExp(spec.query, "i");
+    if (queries.some((x) => q.test(x))) out.push(new RegExp(spec.value, "i"));
+  }
+  return out;
+}
+function itemQuestions(item) {
+  const qs = item.questions;
+  return Array.isArray(qs) ? qs.filter((q) => typeof q === "string" && q.trim() !== "").map((q) => q.trim()) : [];
+}
+var MATCHERS = ["bm25", "semantic"];
+function matcherSetting() {
+  const raw = (_nullishCoalesce(_chunkZKOJDUN4cjs.getEnv.call(void 0, "SYNAP_SDK_CACHE_MATCHER"), () => ( ""))).trim().toLowerCase();
+  return MATCHERS.includes(raw) ? raw : SEMANTIC_MATCH.mode;
+}
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length && i < b.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  return na && nb ? dot / Math.sqrt(na * nb) : 0;
+}
 var DEFAULT_TTL_SECONDS = 1800;
 var DEFAULT_MAX_BUNDLES = 50;
 var AnticipationCache = (_class2 = class {
@@ -509,11 +737,81 @@ var AnticipationCache = (_class2 = class {
   __init3() {this.corpusVocab = /* @__PURE__ */ new Set()}
   __init4() {this.bm25 = null}
   __init5() {this.bm25Dirty = true}
-  constructor(options = {}) {;_class2.prototype.__init.call(this);_class2.prototype.__init2.call(this);_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);
+  // Semantic matching (CONTRACT.semantic_match). Python: the same fields.
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  /** Embedding runs one batch after another; `whenEmbedded` awaits the queue. */
+  __init6() {this.embedding = Promise.resolve()}
+  constructor(options = {}) {;_class2.prototype.__init.call(this);_class2.prototype.__init2.call(this);_class2.prototype.__init3.call(this);_class2.prototype.__init4.call(this);_class2.prototype.__init5.call(this);_class2.prototype.__init6.call(this);
     this.ttlSeconds = _nullishCoalesce(options.ttlSeconds, () => ( DEFAULT_TTL_SECONDS));
     this.maxBundles = _nullishCoalesce(options.maxBundles, () => ( DEFAULT_MAX_BUNDLES));
     this.now = _nullishCoalesce(options.now, () => ( monotonicNow));
     this.onLookup = options.onLookup;
+    this.encoder = _nullishCoalesce(options.encoder, () => ( null));
+    this.matcher = _nullishCoalesce(options.matcher, () => ( matcherSetting()));
+    this.minCosine = _nullishCoalesce(options.minCosine, () => ( SEMANTIC_MATCH.min_cosine));
+    this.serveMinCosine = _nullishCoalesce(options.serveMinCosine, () => ( SEMANTIC_MATCH.serve_min_cosine));
+    this.askedKind = _nullishCoalesce(options.askedKind, () => ( SEMANTIC_MATCH.asked_kind));
+    this.itemQuestions = _nullishCoalesce(options.itemQuestions, () => ( SEMANTIC_MATCH.item_questions));
+    this.canonical = _nullishCoalesce(options.canonical, () => ( SEMANTIC_MATCH.canonical_query));
+    this.bundleServeMinCosine = _nullishCoalesce(options.bundleServeMinCosine, () => ( SEMANTIC_MATCH.bundle_serve_min_cosine));
+    this.sureMinCosine = _nullishCoalesce(options.sureMinCosine, () => ( SEMANTIC_MATCH.sure_min_cosine));
+  }
+  /**
+   * Hand over the local embedding model once it has loaded. Items already
+   * cached are embedded off the lookup path.
+   */
+  setEncoder(encoder) {
+    this.encoder = encoder;
+    this.embedItems(this.items);
+  }
+  /** True when lookups match by meaning: matcher "semantic" and a model loaded. */
+  get semantic() {
+    return this.matcher === "semantic" && this.encoder !== null;
+  }
+  /** Resolves once every item stored so far has had its turn to be embedded. */
+  whenEmbedded() {
+    return this.embedding;
+  }
+  /**
+   * Give `items` their vectors, queued behind any earlier batch, so neither a
+   * bundle arriving on the stream nor a lookup waits for the model. A lookup
+   * before they are ready matches those items by BM25 alone.
+   */
+  embedItems(items) {
+    const encoder = this.encoder;
+    if (encoder === null || this.matcher !== "semantic") return;
+    const todo = items.filter((i) => i.vecModel !== encoder.model);
+    if (todo.length === 0) return;
+    this.embedding = this.embedding.then(async () => {
+      try {
+        const texts = [];
+        for (const i of todo) {
+          texts.push(i.content);
+          if (this.itemQuestions) texts.push(...i.questions);
+        }
+        const vecs = await encoder.encode(texts);
+        let k = 0;
+        for (const item of todo) {
+          const n = this.itemQuestions ? item.questions.length : 0;
+          const v = vecs[k];
+          if (v) {
+            item.vec = Array.from(v);
+            item.qvecs = vecs.slice(k + 1, k + 1 + n).map((x) => Array.from(x));
+            item.vecModel = encoder.model;
+          }
+          k += 1 + n;
+        }
+      } catch (e2) {
+      }
+    });
   }
   get size() {
     return this.entries.size;
@@ -542,11 +840,22 @@ var AnticipationCache = (_class2 = class {
       for (const item of _nullishCoalesce(list, () => ( []))) {
         const content = String(_nullishCoalesce(item.content, () => ( "")));
         const tokens = tokenize(content);
-        this.items.push({ bundleId: bundle.bundleId, itemType, content, tokens, itemDict: item });
+        this.items.push({
+          bundleId: bundle.bundleId,
+          itemType,
+          content,
+          tokens,
+          itemDict: item,
+          vec: null,
+          vecModel: "",
+          questions: itemQuestions(item),
+          qvecs: []
+        });
         for (const t of tokens) this.corpusVocab.add(t);
       }
     }
     this.bm25Dirty = true;
+    this.embedItems(this.items.filter((i) => i.bundleId === bundle.bundleId));
     while (this.entries.size > this.maxBundles) {
       let oldest = null;
       for (const e of this.entries.values()) {
@@ -556,6 +865,31 @@ var AnticipationCache = (_class2 = class {
       this.dropBundle(oldest.bundleId);
     }
   }
+  /**
+   * `lookup`, matching by meaning when a model is loaded: embeds the queries,
+   * then looks up with their vectors. A query the model cannot embed is looked
+   * up by BM25, as without a model. Python does this inside `lookup`.
+   */
+  async lookupAsync(params) {
+    const encoder = this.encoder;
+    let queries = (_nullishCoalesce(params.searchQuery, () => ( []))).filter((q) => typeof q === "string" && q.trim() !== "").map((q) => q.trim()).slice(0, SEMANTIC_MATCH.max_queries);
+    const recall = _chunkZKOJDUN4cjs.getEnvFlag.call(void 0, CONTRACT.recall_bypass.env_flag) && isRecallQuery(_nullishCoalesce(params.searchQuery, () => ( null)));
+    if (!this.semantic || encoder === null || queries.length === 0 || recall || this.items.length === 0) {
+      return this.lookup(params);
+    }
+    if (this.canonical === "canon" || this.canonical === "both") {
+      const canon = queries.map(canonicalQuery);
+      const changed = canon.filter((c, i) => c !== queries[i]);
+      queries = this.canonical === "both" ? [...queries, ...changed] : canon;
+    }
+    let queryVectors = null;
+    try {
+      queryVectors = await (_nullishCoalesce(encoder.encodeQuery, () => ( encoder.encode))).call(encoder, queries);
+    } catch (e3) {
+      queryVectors = null;
+    }
+    return this.lookup({ ...params, queryVectors });
+  }
   lookup(params) {
     const {
       searchQuery = null,
@@ -564,7 +898,8 @@ var AnticipationCache = (_class2 = class {
       clientId = null,
       conversationId = null,
       scopeRung = null,
-      maxItems = 10
+      maxItems = 10,
+      queryVectors = null
     } = params;
     this.evictExpired();
     const accepted = this.buildAcceptedScope(entityId, customerId, clientId);
@@ -590,13 +925,22 @@ var AnticipationCache = (_class2 = class {
     }
     const hasQuery = (_nullishCoalesce(searchQuery, () => ( []))).some((q) => q && q.trim() !== "");
     if (!hasQuery) {
-      return this.freshnessLookup(entityId, _nullishCoalesce(scopeRung, () => ( null)), maxItems, telemetry);
+      return this.freshnessLookup(
+        _nullishCoalesce(entityId, () => ( customerId)),
+        conversationId,
+        _nullishCoalesce(scopeRung, () => ( null)),
+        maxItems,
+        telemetry
+      );
     }
     if (_chunkZKOJDUN4cjs.getEnvFlag.call(void 0, CONTRACT.recall_bypass.env_flag) && isRecallQuery(searchQuery)) {
       return this.miss(telemetry, "recall_bypass");
     }
     const queryTokens = (_nullishCoalesce(searchQuery, () => ( []))).flatMap((q) => tokenize(q));
     telemetry.bm25QueryTokens = queryTokens;
+    if (this.semantic && queryVectors !== null && queryVectors.length > 0) {
+      return this.semanticLookup(queryTokens, queryVectors, accepted, conversationId, _nullishCoalesce(scopeRung, () => ( null)), maxItems, telemetry);
+    }
     if (queryTokens.length === 0) {
       return this.miss(telemetry, "no_query_tokens");
     }
@@ -663,6 +1007,92 @@ var AnticipationCache = (_class2 = class {
     if (coverageMin !== null && coverage < coverageMin) {
       return this.miss(telemetry, "coverage_gate");
     }
+    return this.serve(top, telemetry, coverage, "bm25_score");
+  }
+  /**
+   * Match by meaning: a lookup is a hit when an item's cosine to a query
+   * reaches `minCosine`, and the hit also serves the items at `serveMinCosine`
+   * or above. An item with no vector yet is matched by BM25 with its novel-term
+   * gate, as before. Python: `_semantic_lookup`, which explains the choices.
+   */
+  semanticLookup(queryTokens, queryVectors, accepted, conversationId, scopeRung, maxItems, telemetry) {
+    const model = _nullishCoalesce(_optionalChain([this, 'access', _2 => _2.encoder, 'optionalAccess', _3 => _3.model]), () => ( ""));
+    if (queryTokens.length > 0 && (this.bm25Dirty || this.bm25 === null) && this.items.length > 0) {
+      this.bm25 = new BM25(this.items.map((i) => i.tokens));
+      this.bm25Dirty = false;
+    }
+    const bm25Scores = queryTokens.length > 0 && this.bm25 ? this.bm25.scores(queryTokens) : [];
+    const effectiveThreshold = Math.max(
+      EFFECTIVE_FLOOR,
+      Math.min(THRESHOLDS.bm25, QUERY_TOKEN_SCALE * Math.max(queryTokens.length, 1))
+    );
+    telemetry.bm25Threshold = round4(effectiveThreshold);
+    const uniqueStems = new Set(queryTokens);
+    let novel = 0;
+    for (const s of uniqueStems) if (!this.corpusVocab.has(s)) novel++;
+    const novelRatio = uniqueStems.size ? novel / uniqueStems.size : 1;
+    telemetry.novelTermRatio = round4(novelRatio);
+    const wordRoute = queryTokens.length > 0 && !(this.corpusVocab.size >= THRESHOLDS.minCorpusForNovelGate && novelRatio >= THRESHOLDS.novelTerm);
+    const validBundles = this.getValidBundleIds(accepted, conversationId, scopeRung);
+    const picked = [];
+    const companions = [];
+    const rejected = [];
+    this.items.forEach((item, idx) => {
+      const b = _nullishCoalesce(bm25Scores[idx], () => ( 0));
+      const reject = (score, cos2, reason) => rejected.push({
+        score,
+        payload: {
+          item_index: idx,
+          bundle_id: item.bundleId,
+          item_type: item.itemType,
+          content_first_120: item.content.slice(0, PREVIEW_CHARS),
+          bm25_score: round4(b),
+          cosine: cos2 === null ? null : round4(cos2),
+          reason
+        }
+      });
+      if (!validBundles.has(item.bundleId)) return reject(b, null, "scope_filter_excluded");
+      let passes;
+      let rank;
+      let cos = null;
+      if (item.vec !== null && item.vecModel === model) {
+        const vecs = [item.vec, ...item.qvecs];
+        cos = Math.max(...queryVectors.flatMap((q) => vecs.map((v) => cosine(q, v))));
+        passes = cos >= this.minCosine;
+        rank = cos;
+      } else {
+        passes = wordRoute && b >= effectiveThreshold;
+        rank = this.minCosine;
+      }
+      if (!passes && cos !== null && cos >= Math.min(this.serveMinCosine, this.bundleServeMinCosine)) {
+        companions.push({ score: cos, item });
+        return;
+      }
+      if (!passes) return reject(rank, cos, "below_threshold");
+      picked.push({ score: rank, item });
+    });
+    rejected.sort((a, b) => b.score - a.score);
+    telemetry.itemsRejected = rejected.slice(0, REJECTED_CAP).map((r) => r.payload);
+    if (picked.length === 0) return this.miss(telemetry, "no_items_above_threshold");
+    picked.sort((a, b) => b.score - a.score);
+    const hitBundles = new Set(picked.map((p) => p.item.bundleId));
+    const served = companions.filter(
+      (c) => c.score >= this.serveMinCosine || hitBundles.has(c.item.bundleId) && c.score >= this.bundleServeMinCosine
+    );
+    served.sort((a, b) => b.score - a.score);
+    const top = [...picked, ...served].slice(0, maxItems);
+    if (this.askedKind) {
+      const patterns = askedDetailPatterns(telemetry.searchQuery);
+      if (patterns.length > 0 && !top.some(({ item }) => patterns.some((p) => p.test(item.content)))) {
+        return this.miss(telemetry, "asked_kind_missing");
+      }
+    }
+    const hit = this.serve(top, telemetry, null, "cosine");
+    hit.band = picked[0].score >= this.sureMinCosine ? "sure" : "borderline";
+    return hit;
+  }
+  /** A hit: renew the leases of the bundles used, report, merge the items. */
+  serve(top, telemetry, coverage, scoreKey) {
     const itemsByType = {};
     const bundleIds = /* @__PURE__ */ new Set();
     for (const { item } of top) {
@@ -683,14 +1113,14 @@ var AnticipationCache = (_class2 = class {
       bundle_id: item.bundleId,
       item_type: item.itemType,
       content_first_120: item.content.slice(0, PREVIEW_CHARS),
-      bm25_score: round4(score)
+      [scoreKey]: round4(score)
     }));
     this.fire(telemetry);
     return {
       itemsByType,
       bundleIds: [...bundleIds],
       score: top[0].score,
-      coverage
+      coverage: _nullishCoalesce(coverage, () => ( 1))
     };
   }
   /**
@@ -796,6 +1226,7 @@ var AnticipationCache = (_class2 = class {
       if (entry.bundleType !== "user_summary") continue;
       if (!rungServes(entry.scopeRung, scopeRung)) continue;
       if (entry.entityId !== entityId && entry.entityId !== ANY_SCOPE) continue;
+      if (unownedElsewhere(entry.entityId, entry.conversationId, null)) continue;
       if (freshest === null || entry.storedAt > freshest.storedAt) freshest = entry;
     }
     if (freshest === null) return null;
@@ -851,12 +1282,12 @@ var AnticipationCache = (_class2 = class {
   }
   fire(telemetry) {
     try {
-      _optionalChain([this, 'access', _2 => _2.onLookup, 'optionalCall', _3 => _3(telemetry)]);
-    } catch (e2) {
+      _optionalChain([this, 'access', _4 => _4.onLookup, 'optionalCall', _5 => _5(telemetry)]);
+    } catch (e4) {
     }
   }
-  freshnessLookup(entityId, scopeRung, maxItems, telemetry) {
-    const candidates = [...this.entries.values()].filter((e) => rungServes(e.scopeRung, scopeRung)).filter((e) => entityId === null || e.entityId === entityId || e.entityId === ANY_SCOPE).sort((a, b) => b.storedAt - a.storedAt);
+  freshnessLookup(owner, conversationId, scopeRung, maxItems, telemetry) {
+    const candidates = [...this.entries.values()].filter((e) => rungServes(e.scopeRung, scopeRung)).filter((e) => e.entityId === ANY_SCOPE || owner !== null && owner !== "" && e.entityId === owner).filter((e) => !unownedElsewhere(e.entityId, e.conversationId, conversationId)).sort((a, b) => b.storedAt - a.storedAt);
     if (candidates.length === 0) return this.miss(telemetry, "empty");
     const newest = candidates[0];
     const itemsByType = {};
@@ -900,6 +1331,7 @@ var AnticipationCache = (_class2 = class {
       if (!rungServes(entry.scopeRung, scopeRung)) continue;
       if (!accepted.has(entry.entityId)) continue;
       if (entry.conversationId && conversationId && entry.conversationId !== conversationId) continue;
+      if (unownedElsewhere(entry.entityId, entry.conversationId, conversationId)) continue;
       valid.add(entry.bundleId);
     }
     return valid;
@@ -944,5 +1376,10 @@ function round4(n) {
 
 
 
-exports.CONTRACT = CONTRACT; exports.THRESHOLDS = THRESHOLDS; exports.isRecallQuery = isRecallQuery; exports.stem = stem; exports.tokenize = tokenize; exports.BM25 = BM25; exports.ANY_SCOPE = ANY_SCOPE; exports.rungKey = rungKey; exports.rungServes = rungServes; exports.AnticipationCache = AnticipationCache;
-//# sourceMappingURL=chunk-T6U5PVAD.cjs.map
+
+
+
+
+
+exports.CONTRACT = CONTRACT; exports.THRESHOLDS = THRESHOLDS; exports.HISTORY_SEARCH = HISTORY_SEARCH; exports.SEMANTIC_MATCH = SEMANTIC_MATCH; exports.isRecallQuery = isRecallQuery; exports.stem = stem; exports.tokenize = tokenize; exports.BM25 = BM25; exports.ANY_SCOPE = ANY_SCOPE; exports.rungKey = rungKey; exports.rungServes = rungServes; exports.unownedElsewhere = unownedElsewhere; exports.canonicalQuery = canonicalQuery; exports.MATCHERS = MATCHERS; exports.AnticipationCache = AnticipationCache;
+//# sourceMappingURL=chunk-ICUFS3B5.cjs.map