@maximem/synap-js-sdk 0.2.4 → 0.4.0

package/dist/chunk-NIDPTBNC.cjs

@@ -0,0 +1,800 @@
+"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
+var anticipation_default = {
+  $comment: "SOURCE OF TRUTH for anticipation-cache behavior, shared by the Python and JS/TS SDKs. Do not duplicate these values into either SDK's source. See ../README.md. Regexes are restricted to the intersection of Python 're' and ECMAScript; both SDKs have a parity test.",
+  version: 1,
+  recall_bypass: {
+    note: "WS4 of the playground query-hygiene plan. A recall-shaped question never serves from the anticipation cache. Asymmetric cost is why: a stale false-hit makes the agent answer 'I don't see that' while the store holds the fact (the BZQR6J cross-session failure), whereas bypassing costs only cold-fetch latency on a turn where the user already expects a lookup. Stem coverage cannot gate this \u2014 false hits were measured at coverage=1.00. Ties break toward INCLUDING a pattern.",
+    env_flag: "SYNAP_SDK_CACHE_RECALL_BYPASS",
+    default: false,
+    patterns: [
+      {
+        pattern: "\\bremind me\\b",
+        flags: "i",
+        note: "Original set (WS4, playground query-hygiene plan)."
+      },
+      {
+        pattern: "\\bon file\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\b(your|my|the) records\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bdo you (have|know|remember|recall|see)\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bwhat (do|did) (i|you) (say|tell|mention|have)\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bwhat('s| is) my\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bwhere (am i|do i live)\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bhow long have i\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bwhich of my\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\bwhat .{0,40}\\b(again|earlier|last time|previously|yesterday)\\b",
+        flags: "i",
+        note: "Original set (WS4). 'again' alone is deliberately NOT a marker: 'book me a ride again' is a task query, not a recall query."
+      },
+      {
+        pattern: "\\bwill you use to (contact|reach|notify)\\b",
+        flags: "i",
+        note: "Original set (WS4)."
+      },
+      {
+        pattern: "\\b(confirm|verify|double.?check)\\b.{0,40}\\bmy\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11: 'can you confirm my email address?' served a stale bundle. Also catches 'confirm my booking' \u2014 an intentional over-match, costing one cloud fetch."
+      },
+      {
+        pattern: "\\b(linked to|associated with|registered (to|on|with)) my\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11: 'what name is linked to my Uber account?' served a stale bundle."
+      },
+      {
+        pattern: "\\b(best|preferred) way to (reach|contact|update|notify) me\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11: 'best way to contact me with updates' served a stale bundle."
+      },
+      {
+        pattern: "\\bhow (do|will|can|should) you (reach|contact|notify) me\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11, sibling phrasing of the above."
+      },
+      {
+        pattern: "\\bwhich .{0,40}\\b(are|will) you (going to )?(use|using)\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11: 'which email are you going to use?' served a stale bundle."
+      },
+      {
+        pattern: "\\bon (my|the) account\\b",
+        flags: "i",
+        note: "2026-07-16 eval register issue #11."
+      }
+    ]
+  },
+  thresholds: {
+    bm25: {
+      value: 1.5,
+      note: "Nominal threshold. The value actually applied is derived per query: max(effective_floor, min(bm25, query_token_scale * len(query_tokens))). Short queries cannot reach the nominal score, so holding them to it would miss every time."
+    },
+    novel_term: {
+      value: 0.45,
+      note: "Fraction of query stems absent from the cached corpus that forces a miss."
+    },
+    min_corpus_for_novel_gate: {
+      value: 200,
+      note: "The novel-term gate is meaningless on a small corpus, where the ratio is dominated by ordinary English word forms. Measured: a fresh playground conversation reaches ~60 stems after the first push and would trip the 0.45 gate on essentially every second-turn query. 200 means the gate engages once a customer has ~3-4 typical bundles cached."
+    },
+    effective_floor: {
+      value: 0.6,
+      note: "Lower bound on the derived per-query threshold. Below this, BM25 stops discriminating."
+    },
+    query_token_scale: {
+      value: 0.3,
+      note: "Scales the threshold down for short queries: 0.3 points of score per query token."
+    }
+  },
+  bm25: {
+    k1: 1.5,
+    b: 0.75,
+    idf_floor: 0.5,
+    min_token_len: 2,
+    min_stem_len: 4,
+    suffixes: [
+      "ences",
+      "ances",
+      "ation",
+      "tion",
+      "sion",
+      "ence",
+      "ance",
+      "ness",
+      "ment",
+      "able",
+      "ible",
+      "ical",
+      "ally",
+      "ies",
+      "ive",
+      "ful",
+      "ous",
+      "ing",
+      "ary",
+      "ly",
+      "ed",
+      "es",
+      "s"
+    ],
+    stop_words: [
+      "a",
+      "about",
+      "after",
+      "an",
+      "and",
+      "are",
+      "at",
+      "be",
+      "been",
+      "before",
+      "being",
+      "but",
+      "by",
+      "can",
+      "could",
+      "did",
+      "do",
+      "does",
+      "for",
+      "from",
+      "had",
+      "has",
+      "have",
+      "how",
+      "if",
+      "in",
+      "into",
+      "is",
+      "it",
+      "its",
+      "may",
+      "might",
+      "no",
+      "nor",
+      "not",
+      "of",
+      "on",
+      "or",
+      "over",
+      "should",
+      "so",
+      "than",
+      "that",
+      "the",
+      "then",
+      "these",
+      "this",
+      "those",
+      "to",
+      "was",
+      "were",
+      "what",
+      "when",
+      "where",
+      "which",
+      "who",
+      "whom",
+      "why",
+      "will",
+      "with",
+      "would"
+    ],
+    alias_token: {
+      pattern: "\\[\\[([A-Za-z][A-Za-z0-9_]*_[a-z0-9]{12})\\]\\]",
+      note: "An alias label as it appears in text: [[PERSON_PHONE_h2n7v5cx8m0d]]. Kept whole rather than split, because 'person' and 'phone' are boilerplate shared by every label of that field type and would make two different people's memories score alike. Mirrors synap/cloud/shared/tokenizer.py \u2014 keep the two in step."
+    },
+    suffix_note: "Order matters: longest-first, because _stem returns on first match. Reordering this list silently changes every stem and therefore every BM25 score."
+  },
+  env_flags: {
+    $comment: "Read at CALL time, never at module load. Python does os.environ.get inside the function bodies; JS must do the same or late process.env mutation stops working and the flag looks broken. See gotcha G-S.",
+    SYNAP_SDK_CACHE_RECALL_BYPASS: {
+      default: false,
+      truthy: [
+        "true",
+        "1",
+        "yes"
+      ]
+    },
+    SYNAP_SDK_CACHE_HONOR_TTL_HINT: {
+      default: false,
+      truthy: [
+        "true",
+        "1",
+        "yes"
+      ],
+      note: "A bundle's server ttl_hint_seconds may only SHORTEN the global TTL, never extend it."
+    },
+    SYNAP_SDK_CACHE_INVALIDATE_ON_WRITE: {
+      default: false,
+      truthy: [
+        "true",
+        "1",
+        "yes"
+      ],
+      note: "2026-07-16 eval register issue #8: the cloud invalidates its own Redis caches on ingest, but that stops at the process boundary."
+    },
+    SYNAP_SDK_CACHE_MAX_ENTRY_AGE: {
+      default: null,
+      note: "2026-07-16 eval register issue #6: stored_at is a sliding lease renewed on hit, so under steady traffic a pre-update snapshot never expired. Defaults to 2x the sliding TTL; 0 disables."
+    },
+    SYNAP_SDK_CACHE_COVERAGE_MIN: {
+      default: null
+    }
+  },
+  coverage_gate: {
+    note: "Fraction of the query's stems present in the picked items. A bundle can clear the BM25 threshold on one shared token ('account') while lacking the asked-for fact entirely: the false HIT behind the eval's 'forgot the name' failure. ALWAYS computed and reported; ENFORCED only when SYNAP_SDK_CACHE_COVERAGE_MIN is explicitly set, so default behavior is unchanged. When it does fire it must gate BEFORE any side effect, so a rejected lookup leaves cache state untouched.",
+    env_flag: "SYNAP_SDK_CACHE_COVERAGE_MIN",
+    default: null,
+    empty_query_coverage: 1
+  },
+  telemetry: {
+    rejected_items_cap: {
+      value: 20,
+      note: "Rejected items reported per lookup, highest score first, so a large cache cannot bloat the payload."
+    },
+    content_preview_chars: 120
+  }
+};
+
+// src/behavior/contract.ts
+var CONTRACT = anticipation_default;
+var ALLOWED_FLAGS = /* @__PURE__ */ new Set(["i", "m", "s"]);
+function compile(pattern, flags) {
+  for (const ch of flags) {
+    if (!ALLOWED_FLAGS.has(ch)) {
+      throw new Error(
+        `Unsupported regex flag '${ch}' in behavior contract. Flags must be valid in both Python and ECMAScript.`
+      );
+    }
+  }
+  return new RegExp(pattern, flags);
+}
+var RECALL_PATTERNS = CONTRACT.recall_bypass.patterns.map(
+  (p) => compile(p.pattern, _nullishCoalesce(p.flags, () => ( "")))
+);
+var THRESHOLDS = {
+  bm25: CONTRACT.thresholds.bm25.value,
+  novelTerm: CONTRACT.thresholds.novel_term.value,
+  minCorpusForNovelGate: CONTRACT.thresholds.min_corpus_for_novel_gate.value,
+  /** Lower bound on the derived per-query threshold. */
+  effectiveFloor: CONTRACT.thresholds.effective_floor.value,
+  /** Points of score allowed per query token when deriving the threshold. */
+  queryTokenScale: CONTRACT.thresholds.query_token_scale.value
+};
+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;
+function isRecallQuery(searchQuery) {
+  for (const q of _nullishCoalesce(searchQuery, () => ( []))) {
+    if (!q) continue;
+    for (const pattern of RECALL_PATTERNS) {
+      if (pattern.test(q)) return true;
+    }
+  }
+  return false;
+}
+
+// src/cache/bm25.ts
+var MIN_STEM_LEN = BM25_PARAMS.min_stem_len;
+var MIN_TOKEN_LEN = BM25_PARAMS.min_token_len;
+function stem(word) {
+  for (const suffix of SUFFIXES) {
+    if (word.endsWith(suffix) && word.length - suffix.length >= MIN_STEM_LEN) {
+      return word.slice(0, word.length - suffix.length);
+    }
+  }
+  return word;
+}
+function aliasTokenRe() {
+  return new RegExp(ALIAS_TOKEN_SOURCE, "g");
+}
+var WORD_RE = /[a-z0-9]+/g;
+function tokenize(text) {
+  if (!text) return [];
+  const labels = [];
+  const remainder = text.replace(aliasTokenRe(), (_match, captured) => {
+    labels.push(captured.toLowerCase());
+    return " ";
+  });
+  const words = _nullishCoalesce(remainder.toLowerCase().match(WORD_RE), () => ( []));
+  const out = labels.slice();
+  for (const w of words) {
+    if (w.length >= MIN_TOKEN_LEN && !STOP_WORDS.has(w)) out.push(stem(w));
+  }
+  return out;
+}
+var BM25 = (_class = class _BM25 {
+  static __initStatic() {this.IDF_FLOOR = BM25_PARAMS.idf_floor}
+  
+  
+  
+  
+  
+  
+  
+  constructor(corpus, k1 = BM25_PARAMS.k1, b = BM25_PARAMS.b) {
+    this.k1 = k1;
+    this.b = b;
+    this.corpus = corpus;
+    this.docCount = corpus.length;
+    this.docLens = corpus.map((doc) => doc.length);
+    this.avgdl = this.docCount ? this.docLens.reduce((a, n) => a + n, 0) / this.docCount : 1;
+    const idf = /* @__PURE__ */ new Map();
+    const allTerms = /* @__PURE__ */ new Set();
+    for (const doc of corpus) for (const t of doc) allTerms.add(t);
+    for (const term of allTerms) {
+      let df = 0;
+      for (const doc of corpus) if (doc.includes(term)) df++;
+      const raw = Math.log((this.docCount - df + 0.5) / (df + 0.5) + 1);
+      idf.set(term, Math.max(raw, _BM25.IDF_FLOOR));
+    }
+    this.idf = idf;
+  }
+  score(queryTokens, docIdx) {
+    const doc = this.corpus[docIdx];
+    if (doc === void 0) return 0;
+    const dl = _nullishCoalesce(this.docLens[docIdx], () => ( 0));
+    const tfMap = /* @__PURE__ */ new Map();
+    for (const t of doc) tfMap.set(t, (_nullishCoalesce(tfMap.get(t), () => ( 0))) + 1);
+    let s = 0;
+    for (const term of queryTokens) {
+      const tf = tfMap.get(term);
+      if (tf === void 0) continue;
+      const idf = _nullishCoalesce(this.idf.get(term), () => ( _BM25.IDF_FLOOR));
+      const numerator = tf * (this.k1 + 1);
+      const denominator = tf + this.k1 * (1 - this.b + this.b * dl / this.avgdl);
+      s += idf * numerator / denominator;
+    }
+    return s;
+  }
+  scores(queryTokens) {
+    return this.corpus.map((_, i) => this.score(queryTokens, i));
+  }
+}, _class.__initStatic(), _class);
+
+// src/context/anticipation-cache.ts
+var EFFECTIVE_FLOOR = CONTRACT.thresholds.effective_floor.value;
+var QUERY_TOKEN_SCALE = CONTRACT.thresholds.query_token_scale.value;
+var REJECTED_CAP = CONTRACT.telemetry.rejected_items_cap.value;
+var PREVIEW_CHARS = CONTRACT.telemetry.content_preview_chars;
+var ANY_SCOPE = "_any";
+var DEFAULT_TTL_SECONDS = 1800;
+var DEFAULT_MAX_BUNDLES = 50;
+var AnticipationCache = (_class2 = class {
+  
+  
+  
+  
+  __init() {this.entries = /* @__PURE__ */ new Map()}
+  __init2() {this.items = []}
+  __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);
+    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;
+  }
+  get size() {
+    return this.entries.size;
+  }
+  get itemCount() {
+    return this.items.length;
+  }
+  store(bundle) {
+    if (!bundle.bundleId) return;
+    this.evictExpired();
+    const entityId = bundle.entityId || ANY_SCOPE;
+    if (this.entries.has(bundle.bundleId)) this.dropBundle(bundle.bundleId);
+    const now = this.now();
+    this.entries.set(bundle.bundleId, {
+      bundleId: bundle.bundleId,
+      entityId,
+      conversationId: _nullishCoalesce(bundle.conversationId, () => ( null)),
+      bundleType: _nullishCoalesce(bundle.bundleType, () => ( null)),
+      searchQueries: [..._nullishCoalesce(bundle.searchQueries, () => ( []))],
+      storedAt: now,
+      createdAt: now,
+      ttlHintSeconds: _nullishCoalesce(bundle.ttlHintSeconds, () => ( null))
+    });
+    for (const [itemType, list] of Object.entries(_nullishCoalesce(bundle.itemsByType, () => ( {})))) {
+      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 });
+        for (const t of tokens) this.corpusVocab.add(t);
+      }
+    }
+    this.bm25Dirty = true;
+    while (this.entries.size > this.maxBundles) {
+      let oldest = null;
+      for (const e of this.entries.values()) {
+        if (oldest === null || e.storedAt < oldest.storedAt) oldest = e;
+      }
+      if (oldest === null) break;
+      this.dropBundle(oldest.bundleId);
+    }
+  }
+  lookup(params) {
+    const {
+      searchQuery = null,
+      entityId = null,
+      customerId = null,
+      clientId = null,
+      conversationId = null,
+      maxItems = 10
+    } = params;
+    this.evictExpired();
+    const accepted = this.buildAcceptedScope(entityId, customerId, clientId);
+    const telemetry = {
+      searchQuery: (_nullishCoalesce(searchQuery, () => ( []))).filter((q) => Boolean(q)),
+      entityId,
+      customerId,
+      clientId,
+      conversationId,
+      scopeFilterAccepted: [...accepted].sort(),
+      novelTermRatio: null,
+      bm25Threshold: null,
+      bm25QueryTokens: [],
+      itemsPicked: [],
+      itemsRejected: [],
+      coverage: null,
+      hit: false,
+      exitReason: "empty"
+    };
+    if (this.entries.size === 0 || this.items.length === 0) {
+      return this.miss(telemetry, "empty");
+    }
+    const hasQuery = (_nullishCoalesce(searchQuery, () => ( []))).some((q) => q && q.trim() !== "");
+    if (!hasQuery) {
+      return this.freshnessLookup(entityId, 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 (queryTokens.length === 0) {
+      return this.miss(telemetry, "no_query_tokens");
+    }
+    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 : 0;
+    telemetry.novelTermRatio = round4(novelRatio);
+    if (this.corpusVocab.size >= THRESHOLDS.minCorpusForNovelGate && novelRatio >= THRESHOLDS.novelTerm) {
+      return this.miss(telemetry, "novel_term_gate");
+    }
+    if (this.bm25Dirty || this.bm25 === null) {
+      if (this.items.length === 0) return this.miss(telemetry, "empty_corpus");
+      this.bm25 = new BM25(this.items.map((i) => i.tokens));
+      this.bm25Dirty = false;
+    }
+    const scores = this.bm25.scores(queryTokens);
+    const validBundles = this.getValidBundleIds(accepted, conversationId);
+    const effectiveThreshold = Math.max(
+      EFFECTIVE_FLOOR,
+      Math.min(THRESHOLDS.bm25, QUERY_TOKEN_SCALE * queryTokens.length)
+    );
+    telemetry.bm25Threshold = round4(effectiveThreshold);
+    const picked = [];
+    const rejected = [];
+    for (let idx = 0; idx < scores.length; idx++) {
+      const item = this.items[idx];
+      const score = scores[idx];
+      const reject = (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(score),
+          reason
+        }
+      });
+      if (score < effectiveThreshold) {
+        reject("below_threshold");
+        continue;
+      }
+      if (!validBundles.has(item.bundleId)) {
+        reject("scope_filter_excluded");
+        continue;
+      }
+      picked.push({ score, 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 top = picked.slice(0, maxItems);
+    const pickedStems = /* @__PURE__ */ new Set();
+    for (const { item } of top) for (const t of item.tokens) pickedStems.add(t);
+    let overlap = 0;
+    for (const s of uniqueStems) if (pickedStems.has(s)) overlap++;
+    const coverage = uniqueStems.size ? overlap / uniqueStems.size : 1;
+    telemetry.coverage = round4(coverage);
+    const coverageMin = _chunkZKOJDUN4cjs.getEnvFloat.call(void 0, "SYNAP_SDK_CACHE_COVERAGE_MIN");
+    if (coverageMin !== null && coverage < coverageMin) {
+      return this.miss(telemetry, "coverage_gate");
+    }
+    const itemsByType = {};
+    const bundleIds = /* @__PURE__ */ new Set();
+    for (const { item } of top) {
+      (itemsByType[item.itemType] ??= []).push(item.itemDict);
+      bundleIds.add(item.bundleId);
+    }
+    const refreshOnHit = !_chunkZKOJDUN4cjs.getEnvFlag.call(void 0, "SYNAP_SDK_CACHE_HONOR_TTL_HINT");
+    if (refreshOnHit) {
+      const now = this.now();
+      for (const id of bundleIds) {
+        const entry = this.entries.get(id);
+        if (entry) entry.storedAt = now;
+      }
+    }
+    telemetry.hit = true;
+    telemetry.exitReason = "hit";
+    telemetry.itemsPicked = top.map(({ score, item }) => ({
+      bundle_id: item.bundleId,
+      item_type: item.itemType,
+      content_first_120: item.content.slice(0, PREVIEW_CHARS),
+      bm25_score: round4(score)
+    }));
+    this.fire(telemetry);
+    return {
+      itemsByType,
+      bundleIds: [...bundleIds],
+      score: top[0].score,
+      coverage
+    };
+  }
+  /**
+   * Drop this entity's bundles after a write, so the cache stops serving a
+   * pre-write view. Gated on the flag: this is the write-path hook.
+   */
+  invalidateEntity(entityId) {
+    if (!_chunkZKOJDUN4cjs.getEnvFlag.call(void 0, "SYNAP_SDK_CACHE_INVALIDATE_ON_WRITE")) return 0;
+    return this.dropEntity(entityId);
+  }
+  /**
+   * Unconditionally drop this entity's bundles. Backs `cache.clear_user` and
+   * `cache.clear_customer`, which are explicit user requests and so are not
+   * gated on the invalidate-on-write flag.
+   */
+  dropEntity(entityId) {
+    let dropped = 0;
+    for (const entry of [...this.entries.values()]) {
+      if (entry.entityId === ANY_SCOPE) continue;
+      if (entry.entityId === entityId) {
+        this.dropBundle(entry.bundleId);
+        dropped++;
+      }
+    }
+    return dropped;
+  }
+  /**
+   * A read-only diagnostic projection of the cache.
+   *
+   * Backs `client.anticipation_cache_snapshot()` and mirrors Python's shape
+   * key for key, including snake_case keys: this output gets logged, diffed
+   * and pasted into issues across both SDKs, so it is a wire format.
+   *
+   * Note the 140-character content previews. That is Python's literal, and it
+   * is deliberately NOT the 120 of `telemetry.content_preview_chars` from the
+   * contract, which caps lookup telemetry rather than this snapshot.
+   */
+  snapshot() {
+    const SNAPSHOT_PREVIEW_CHARS = 140;
+    const overallScope = /* @__PURE__ */ new Map();
+    const itemsByBundle = /* @__PURE__ */ new Map();
+    for (const record of this.items) {
+      const list = itemsByBundle.get(record.bundleId);
+      if (list === void 0) itemsByBundle.set(record.bundleId, [record]);
+      else list.push(record);
+    }
+    const bundles = [];
+    for (const [bundleId, entry] of this.entries) {
+      const perBundle = /* @__PURE__ */ new Map();
+      const itemPreviews = [];
+      for (const record of _nullishCoalesce(itemsByBundle.get(bundleId), () => ( []))) {
+        const scope = _nullishCoalesce(record.itemDict["scope"], () => ( null));
+        const key = scope === null ? "" : scope;
+        overallScope.set(key, (_nullishCoalesce(overallScope.get(key), () => ( 0))) + 1);
+        perBundle.set(key, (_nullishCoalesce(perBundle.get(key), () => ( 0))) + 1);
+        itemPreviews.push({
+          type: record.itemType,
+          scope,
+          content: record.content.slice(0, SNAPSHOT_PREVIEW_CHARS)
+        });
+      }
+      let totalItems = 0;
+      for (const n of perBundle.values()) totalItems += n;
+      bundles.push({
+        bundle_id: bundleId,
+        entity_id: entry.entityId,
+        conversation_id: entry.conversationId,
+        bundle_type: entry.bundleType,
+        search_queries: [...entry.searchQueries],
+        scope_counts: Object.fromEntries(perBundle),
+        total_items: totalItems,
+        items: itemPreviews
+      });
+    }
+    return {
+      total_entries: this.entries.size,
+      total_item_records: this.items.length,
+      scope_breakdown_overall: Object.fromEntries(overallScope),
+      corpus_vocab_size: this.corpusVocab.size,
+      corpus_vocab_sample: [...this.corpusVocab].sort().slice(0, 80),
+      item_records: this.items.slice(0, 20).map((rec) => ({
+        bundle_id: rec.bundleId,
+        item_type: rec.itemType,
+        tokens: rec.tokens.slice(0, 25),
+        content: rec.content.slice(0, SNAPSHOT_PREVIEW_CHARS)
+      })),
+      bundles
+    };
+  }
+  /**
+   * Drop every bundle belonging to one conversation.
+   *
+   * Backs the `compaction_update` signal on the Listen stream: a compaction
+   * rewrites the conversation's summary, so any bundle built from the previous
+   * state is stale and must not keep serving for the rest of its TTL.
+   *
+   * Unlike `dropEntity`, client-scope bundles are NOT spared: a bundle is only
+   * dropped here if it is bound to this specific conversation, and a shared
+   * client-scope bundle has no conversation id to match.
+   */
+  dropConversation(conversationId) {
+    if (!conversationId) return 0;
+    let dropped = 0;
+    for (const entry of [...this.entries.values()]) {
+      if (entry.conversationId === conversationId) {
+        this.dropBundle(entry.bundleId);
+        dropped++;
+      }
+    }
+    return dropped;
+  }
+  clear() {
+    this.entries.clear();
+    this.items = [];
+    this.corpusVocab.clear();
+    this.bm25 = null;
+    this.bm25Dirty = true;
+  }
+  // ── internals ───────────────────────────────────────────────────────────────
+  miss(telemetry, reason) {
+    telemetry.exitReason = reason;
+    telemetry.hit = false;
+    this.fire(telemetry);
+    return null;
+  }
+  fire(telemetry) {
+    try {
+      _optionalChain([this, 'access', _2 => _2.onLookup, 'optionalCall', _3 => _3(telemetry)]);
+    } catch (e2) {
+    }
+  }
+  freshnessLookup(entityId, maxItems, telemetry) {
+    const candidates = [...this.entries.values()].filter((e) => entityId === null || e.entityId === entityId || e.entityId === ANY_SCOPE).sort((a, b) => b.storedAt - a.storedAt);
+    if (candidates.length === 0) return this.miss(telemetry, "empty");
+    const newest = candidates[0];
+    const itemsByType = {};
+    let n = 0;
+    for (const item of this.items) {
+      if (item.bundleId !== newest.bundleId) continue;
+      if (n >= maxItems) break;
+      (itemsByType[item.itemType] ??= []).push(item.itemDict);
+      n++;
+    }
+    if (n === 0) return this.miss(telemetry, "empty");
+    telemetry.hit = true;
+    telemetry.exitReason = "hit";
+    this.fire(telemetry);
+    return { itemsByType, bundleIds: [newest.bundleId], score: 0, coverage: 1 };
+  }
+  /**
+   * The widened scope-match set for a request.
+   *
+   * A narrower-scope request also matches broader-scope bundles for the same
+   * customer or client. Falsy ids are dropped so an empty customer_id cannot
+   * accidentally match bundles keyed at "".
+   */
+  buildAcceptedScope(entityId, customerId, clientId) {
+    const accepted = /* @__PURE__ */ new Set([ANY_SCOPE]);
+    if (entityId) accepted.add(entityId);
+    if (customerId) accepted.add(customerId);
+    if (clientId) accepted.add(clientId);
+    return accepted;
+  }
+  getValidBundleIds(accepted, conversationId) {
+    const valid = /* @__PURE__ */ new Set();
+    for (const entry of this.entries.values()) {
+      if (!accepted.has(entry.entityId)) continue;
+      if (entry.conversationId && conversationId && entry.conversationId !== conversationId) continue;
+      valid.add(entry.bundleId);
+    }
+    return valid;
+  }
+  effectiveTtl(entry) {
+    if (!_chunkZKOJDUN4cjs.getEnvFlag.call(void 0, "SYNAP_SDK_CACHE_HONOR_TTL_HINT")) return this.ttlSeconds;
+    if (entry.ttlHintSeconds == null || entry.ttlHintSeconds <= 0) return this.ttlSeconds;
+    return Math.min(this.ttlSeconds, entry.ttlHintSeconds);
+  }
+  evictExpired() {
+    const now = this.now();
+    const configuredMaxAge = _chunkZKOJDUN4cjs.getEnvFloat.call(void 0, "SYNAP_SDK_CACHE_MAX_ENTRY_AGE");
+    const maxAge = _nullishCoalesce(configuredMaxAge, () => ( this.ttlSeconds * 2));
+    for (const entry of [...this.entries.values()]) {
+      const idleExpired = now - entry.storedAt > this.effectiveTtl(entry);
+      const ageExpired = maxAge > 0 && now - entry.createdAt > maxAge;
+      if (idleExpired || ageExpired) this.dropBundle(entry.bundleId);
+    }
+  }
+  dropBundle(bundleId) {
+    if (!this.entries.delete(bundleId)) return;
+    this.items = this.items.filter((i) => i.bundleId !== bundleId);
+    this.corpusVocab = new Set(this.items.flatMap((i) => i.tokens));
+    this.bm25Dirty = true;
+  }
+}, _class2);
+function monotonicNow() {
+  return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() / 1e3 : Date.now() / 1e3;
+}
+function round4(n) {
+  return Number(n.toFixed(4));
+}
+
+
+
+
+
+
+
+
+
+
+exports.CONTRACT = CONTRACT; exports.THRESHOLDS = THRESHOLDS; exports.isRecallQuery = isRecallQuery; exports.stem = stem; exports.tokenize = tokenize; exports.BM25 = BM25; exports.ANY_SCOPE = ANY_SCOPE; exports.AnticipationCache = AnticipationCache;
+//# sourceMappingURL=chunk-NIDPTBNC.cjs.map