@agenr/agenr-plugin 1.7.0 → 1.7.2

package/dist/chunk-7WL5EAQZ.js

@@ -0,0 +1,758 @@
+// src/core/recall/scoring.ts
+var DAY_IN_MILLISECONDS = 1e3 * 60 * 60 * 24;
+var IMPORTANCE_FLOOR = 0.4;
+var RELEVANCE_WEIGHT = 0.5;
+var RECENCY_WEIGHT = 0.25;
+var IMPORTANCE_WEIGHT = 0.25;
+function recencyScore(createdAt, expiry, now = /* @__PURE__ */ new Date()) {
+  if (expiry === "core") {
+    return 1;
+  }
+  const createdDate = asValidDate(createdAt);
+  const nowDate = asValidDate(now);
+  if (!createdDate || !nowDate) {
+    return 0;
+  }
+  const halfLifeDays = expiry === "permanent" ? 365 : 30;
+  const daysOld = Math.max(0, (nowDate.getTime() - createdDate.getTime()) / DAY_IN_MILLISECONDS);
+  return clampUnit(Math.pow(0.5, daysOld / halfLifeDays));
+}
+function gaussianRecency(createdAt, aroundDate, radiusDays) {
+  const createdDate = asValidDate(createdAt);
+  const anchorDate = asValidDate(aroundDate);
+  const normalizedRadius = sanitizeNonNegative(radiusDays);
+  if (!createdDate || !anchorDate) {
+    return 0;
+  }
+  if (normalizedRadius <= 0) {
+    return createdDate.getTime() === anchorDate.getTime() ? 1 : 0;
+  }
+  const daysDelta = Math.abs(createdDate.getTime() - anchorDate.getTime()) / DAY_IN_MILLISECONDS;
+  return clampUnit(Math.exp(-0.5 * (daysDelta / normalizedRadius) ** 2));
+}
+function importanceScore(importance) {
+  const clampedImportance = clampRange(sanitizeNonNegative(importance), 1, 10);
+  return clampUnit(IMPORTANCE_FLOOR + (clampedImportance - 1) / 9 * (1 - IMPORTANCE_FLOOR));
+}
+function combinedRelevance(vectorSim, lexical) {
+  const normalizedVector = clampUnit(sanitizeNonNegative(vectorSim));
+  const normalizedLexical = clampUnit(sanitizeNonNegative(lexical));
+  if (normalizedVector > 0 && normalizedLexical > 0) {
+    return clampUnit(normalizedVector * 0.6 + normalizedLexical * 0.4);
+  }
+  return Math.max(normalizedVector, normalizedLexical);
+}
+function scoreCandidate(params) {
+  const vector = clampUnit(sanitizeNonNegative(params.vectorSim));
+  const lexical = clampUnit(sanitizeNonNegative(params.lexical));
+  const recency = clampUnit(sanitizeNonNegative(params.recency));
+  const importance = clampUnit(sanitizeNonNegative(params.importance));
+  const relevance = combinedRelevance(vector, lexical);
+  const score = clampUnit(relevance * RELEVANCE_WEIGHT + recency * RECENCY_WEIGHT + importance * IMPORTANCE_WEIGHT);
+  return {
+    score,
+    scores: {
+      relevance,
+      vector,
+      lexical,
+      recency,
+      importance
+    }
+  };
+}
+function cosineSimilarity(left, right) {
+  const size = Math.min(left.length, right.length);
+  if (size === 0) {
+    return 0;
+  }
+  let dot = 0;
+  let leftNorm = 0;
+  let rightNorm = 0;
+  for (let index = 0; index < size; index += 1) {
+    const leftValue = sanitizeFinite(left[index]);
+    const rightValue = sanitizeFinite(right[index]);
+    dot += leftValue * rightValue;
+    leftNorm += leftValue * leftValue;
+    rightNorm += rightValue * rightValue;
+  }
+  if (leftNorm <= 0 || rightNorm <= 0) {
+    return 0;
+  }
+  return clampUnit(dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm)));
+}
+var asValidDate = (value) => {
+  const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+var clampUnit = (value) => clampRange(sanitizeNonNegative(value), 0, 1);
+var clampRange = (value, min, max) => Math.min(max, Math.max(min, value));
+var sanitizeFinite = (value) => typeof value === "number" && Number.isFinite(value) ? value : 0;
+var sanitizeNonNegative = (value) => Math.max(0, sanitizeFinite(value));
+
+// src/core/recall/temporal.ts
+var DAY_IN_MILLISECONDS2 = 1e3 * 60 * 60 * 24;
+var MONTH_INDEX = /* @__PURE__ */ new Map([
+  ["january", 0],
+  ["february", 1],
+  ["march", 2],
+  ["april", 3],
+  ["may", 4],
+  ["june", 5],
+  ["july", 6],
+  ["august", 7],
+  ["september", 8],
+  ["october", 9],
+  ["november", 10],
+  ["december", 11]
+]);
+function inferAroundDate(text, now = /* @__PURE__ */ new Date()) {
+  const normalized = text.trim().toLowerCase();
+  const referenceNow = asValidDate2(now);
+  if (normalized.length === 0 || !referenceNow) {
+    return null;
+  }
+  let inferred = null;
+  if (/\byesterday\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 1);
+  } else if (/\blast week\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 7);
+  } else if (/\blast month\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 30);
+  } else if (/\blast year\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 365);
+  } else if (/\bthis week\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 3);
+  } else if (/\bthis month\b/.test(normalized)) {
+    inferred = offsetDays(referenceNow, 15);
+  } else {
+    const relativeMatch = normalized.match(/\b(\d+)\s+(day|days|week|weeks|month|months)\s+ago\b/);
+    if (relativeMatch) {
+      const amount = Number(relativeMatch[1]);
+      const unit = relativeMatch[2];
+      const multiplier = unit?.startsWith("week") ? 7 : unit?.startsWith("month") ? 30 : 1;
+      inferred = Number.isFinite(amount) ? offsetDays(referenceNow, amount * multiplier) : null;
+    } else {
+      const monthMatch = normalized.match(/\bin\s+(january|february|march|april|may|june|july|august|september|october|november|december)\b/);
+      if (monthMatch?.[1]) {
+        inferred = inferMonthAnchor(monthMatch[1], referenceNow);
+      }
+    }
+  }
+  if (!inferred) {
+    return null;
+  }
+  return inferred.getTime() > referenceNow.getTime() ? new Date(referenceNow.getTime()) : inferred;
+}
+function parseRelativeDate(input, now = /* @__PURE__ */ new Date()) {
+  const trimmed = input.trim();
+  const referenceNow = asValidDate2(now);
+  if (trimmed.length === 0 || !referenceNow) {
+    return null;
+  }
+  const durationMatch = trimmed.match(/^(\d+)d$/i);
+  if (durationMatch?.[1]) {
+    const days = Number(durationMatch[1]);
+    return Number.isFinite(days) ? offsetDays(referenceNow, days) : null;
+  }
+  const parsed = new Date(trimmed);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+var asValidDate2 = (value) => {
+  const date = new Date(value.getTime());
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+var offsetDays = (date, days) => new Date(date.getTime() - days * DAY_IN_MILLISECONDS2);
+var inferMonthAnchor = (monthName, now) => {
+  const monthIndex = MONTH_INDEX.get(monthName);
+  if (monthIndex === void 0) {
+    return null;
+  }
+  const year = monthIndex <= now.getUTCMonth() ? now.getUTCFullYear() : now.getUTCFullYear() - 1;
+  return new Date(Date.UTC(year, monthIndex, 15));
+};
+
+// src/core/recall/lexical.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "shall",
+  "can",
+  "need",
+  "must",
+  "i",
+  "me",
+  "my",
+  "we",
+  "our",
+  "you",
+  "your",
+  "he",
+  "him",
+  "his",
+  "she",
+  "her",
+  "it",
+  "its",
+  "they",
+  "them",
+  "their",
+  "this",
+  "that",
+  "these",
+  "those",
+  "what",
+  "which",
+  "who",
+  "whom",
+  "in",
+  "on",
+  "at",
+  "to",
+  "for",
+  "of",
+  "with",
+  "by",
+  "from",
+  "up",
+  "about",
+  "into",
+  "through",
+  "during",
+  "before",
+  "after",
+  "above",
+  "below",
+  "and",
+  "or",
+  "but",
+  "not",
+  "no",
+  "nor",
+  "so",
+  "if",
+  "then",
+  "else",
+  "when",
+  "where",
+  "how",
+  "all",
+  "each",
+  "every",
+  "both",
+  "few",
+  "more",
+  "some",
+  "any",
+  "other",
+  "than"
+]);
+var FTS_OPERATOR_TOKENS = /* @__PURE__ */ new Set(["or", "not", "near"]);
+function tokenize(text) {
+  const matches = text.toLowerCase().match(/[a-z0-9][a-z0-9._-]*/g) ?? [];
+  return matches.filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+}
+function buildLexicalPlan(text) {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return [];
+  }
+  const tokens = tokenize(trimmed).filter((token) => !FTS_OPERATOR_TOKENS.has(token));
+  if (tokens.length === 0) {
+    return [
+      {
+        tier: "exact",
+        text: trimmed
+      }
+    ];
+  }
+  if (tokens.length === 1) {
+    return [
+      {
+        tier: "exact",
+        text: trimmed
+      },
+      {
+        tier: "all_tokens",
+        tokens
+      }
+    ];
+  }
+  return [
+    {
+      tier: "exact",
+      text: trimmed
+    },
+    {
+      tier: "all_tokens",
+      tokens
+    },
+    {
+      tier: "any_tokens",
+      tokens
+    }
+  ];
+}
+function computeLexicalScore(query, subject, content) {
+  const queryTokens = tokenize(query);
+  const subjectTokens = tokenize(subject);
+  const contentTokens = tokenize(content);
+  const subjectTokenSet = new Set(subjectTokens);
+  const contentTokenSet = new Set(contentTokens);
+  const tokenOverlap = queryTokens.length === 0 ? 0 : queryTokens.filter((token) => subjectTokenSet.has(token) || contentTokenSet.has(token)).length / queryTokens.length;
+  const phraseMatches = countPhraseMatches(queryTokens, subjectTokens, contentTokens);
+  const phraseBonus = Math.min(0.4, phraseMatches * 0.2);
+  const subjectBonus = normalizeText(query) === normalizeText(subject) && normalizeText(query).length > 0 ? 0.3 : 0;
+  return Math.min(1, tokenOverlap + phraseBonus + subjectBonus);
+}
+var normalizeText = (text) => text.trim().toLowerCase();
+var countPhraseMatches = (queryTokens, subjectTokens, contentTokens) => {
+  if (queryTokens.length < 2) {
+    return 0;
+  }
+  const matchedPhrases = /* @__PURE__ */ new Set();
+  for (let size = 2; size <= queryTokens.length; size += 1) {
+    for (let index = 0; index + size <= queryTokens.length; index += 1) {
+      const phraseTokens = queryTokens.slice(index, index + size);
+      if (hasConsecutivePhrase(subjectTokens, phraseTokens) || hasConsecutivePhrase(contentTokens, phraseTokens)) {
+        matchedPhrases.add(phraseTokens.join(" "));
+      }
+    }
+  }
+  return matchedPhrases.size;
+};
+var hasConsecutivePhrase = (haystack, needle) => {
+  if (needle.length === 0 || haystack.length < needle.length) {
+    return false;
+  }
+  for (let index = 0; index + needle.length <= haystack.length; index += 1) {
+    let matches = true;
+    for (let offset = 0; offset < needle.length; offset += 1) {
+      if (haystack[index + offset] !== needle[offset]) {
+        matches = false;
+        break;
+      }
+    }
+    if (matches) {
+      return true;
+    }
+  }
+  return false;
+};
+
+// src/core/recall/trace.ts
+var NOOP_RECALL_TRACE_SINK = {
+  reportSummary() {
+  }
+};
+function createNoopRecallTraceSink() {
+  return NOOP_RECALL_TRACE_SINK;
+}
+
+// src/core/recall/search.ts
+var MIN_VECTOR_ONLY_EVIDENCE = 0.3;
+var HISTORICAL_STATE_FLAT_RECENCY = 0.5;
+var HISTORICAL_PREDECESSOR_BOOST = 0.08;
+var HISTORICAL_RETIRED_PREDECESSOR_BOOST = 0.06;
+var HISTORICAL_OLDER_STATE_BOOST = 0.08;
+var HISTORICAL_TOPIC_SHARED_PREFIX_MIN = 2;
+var HISTORICAL_TOPIC_PREFIX_OF_CANDIDATE_MIN = 0.6;
+async function recall(query, ports, options = {}) {
+  const text = query.text.trim();
+  const limit = normalizeLimit(query.limit);
+  const threshold = normalizeThreshold(query.threshold);
+  const budget = normalizeBudget(query.budget);
+  const aroundDate = query.around !== void 0 ? parseAroundDate(query.around) : inferAroundDate(text);
+  const since = query.since ? parseRelativeDate(query.since) : null;
+  const until = query.until ? parseRelativeDate(query.until) : null;
+  const filters = buildEntryFilters(query.types, query.tags, since, until);
+  const trace = options.trace ?? createNoopRecallTraceSink();
+  const summary = buildRecallTraceSummary({
+    filters,
+    limit,
+    threshold,
+    budget,
+    aroundDate,
+    aroundSource: query.around !== void 0 ? "explicit" : "inferred",
+    aroundRadius: aroundDate ? normalizeAroundRadius(query.aroundRadius) : void 0
+  });
+  let traceReported = false;
+  const reportTrace = (noResultReason) => {
+    if (traceReported) {
+      return;
+    }
+    traceReported = true;
+    finishRecallTrace(summary, trace, noResultReason);
+  };
+  if (text.length === 0) {
+    reportTrace("empty_query");
+    return [];
+  }
+  if (limit === 0) {
+    reportTrace("limit_zero");
+    return [];
+  }
+  try {
+    const queryEmbedding = await ports.embed(text);
+    const [vectorCandidates, ftsCandidates] = await Promise.all([
+      ports.vectorSearch({
+        embedding: queryEmbedding,
+        limit: limit * 4,
+        filters
+      }),
+      ports.ftsSearch({
+        text,
+        limit: limit * 2,
+        filters
+      })
+    ]);
+    const mergeStartedAt = Date.now();
+    const mergedCandidates = mergeCandidates(vectorCandidates, ftsCandidates);
+    await expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, {
+      activeEntryIds: Array.from(mergedCandidates.keys()),
+      rankingProfile: query.rankingProfile
+    });
+    summary.candidateCounts.merged = mergedCandidates.size;
+    summary.timings.mergeCandidatesMs = elapsedMs(mergeStartedAt);
+    const scoreStartedAt = Date.now();
+    const scored = applyHistoricalLineageBoosts(
+      Array.from(mergedCandidates.values()).map(
+        (candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, {
+          aroundDate,
+          aroundRadius: query.aroundRadius,
+          rankingProfile: query.rankingProfile
+        })
+      ),
+      {
+        aroundDate,
+        rankingProfile: query.rankingProfile
+      }
+    ).sort((left, right) => right.score - left.score);
+    summary.timings.scoreCandidatesMs = elapsedMs(scoreStartedAt);
+    const thresholdStartedAt = Date.now();
+    const thresholded = scored.filter((result) => hasSufficientReturnEvidence(result) && result.score >= threshold);
+    summary.candidateCounts.thresholdQualified = thresholded.length;
+    summary.timings.thresholdMs = elapsedMs(thresholdStartedAt);
+    if (thresholded.length === 0) {
+      reportTrace(scored.length === 0 ? "no_candidates" : "below_threshold");
+      return [];
+    }
+    const budgetStartedAt = Date.now();
+    const budgeted = budget === null ? thresholded : applyBudget(thresholded, budget);
+    summary.candidateCounts.budgetAccepted = budgeted.length;
+    summary.timings.budgetMs = budget === null ? 0 : elapsedMs(budgetStartedAt);
+    const ranked = budgeted.slice(0, limit);
+    summary.candidateCounts.finalRanked = ranked.length;
+    if (ranked.length === 0) {
+      reportTrace("limit_zero");
+      return [];
+    }
+    const hydratedEntries = await ports.hydrateEntries(ranked.map((result) => result.entry.id));
+    const shapeStartedAt = Date.now();
+    const hydratedById = new Map(hydratedEntries.map((entry) => [entry.id, entry]));
+    const results = ranked.flatMap((result) => {
+      const entry = hydratedById.get(result.entry.id);
+      if (!entry) {
+        return [];
+      }
+      return [
+        {
+          entry,
+          score: result.score,
+          scores: result.scores
+        }
+      ];
+    });
+    summary.candidateCounts.returned = results.length;
+    summary.timings.shapeResultsMs = elapsedMs(shapeStartedAt);
+    if (results.length === 0) {
+      reportTrace("hydrate_missing");
+      return [];
+    }
+    if (results.length > 0) {
+      await ports.recordRecallEvents({
+        entryIds: results.map((result) => result.entry.id),
+        query: text,
+        sessionKey: query.sessionKey
+      }).catch(() => void 0);
+    }
+    reportTrace();
+    return results;
+  } catch (error) {
+    reportTrace();
+    throw error;
+  }
+}
+function buildRecallTraceSummary(params) {
+  return {
+    filtering: {
+      types: params.filters?.types ?? [],
+      tags: params.filters?.tags ?? [],
+      since: params.filters?.since?.toISOString(),
+      until: params.filters?.until?.toISOString(),
+      around: params.aroundDate ? {
+        source: params.aroundSource,
+        anchor: params.aroundDate.toISOString(),
+        radiusDays: params.aroundRadius ?? 14
+      } : void 0
+    },
+    ranking: {
+      limit: params.limit,
+      threshold: params.threshold,
+      budget: params.budget
+    },
+    candidateCounts: {
+      merged: 0,
+      thresholdQualified: 0,
+      budgetAccepted: 0,
+      finalRanked: 0,
+      returned: 0
+    },
+    timings: {
+      mergeCandidatesMs: 0,
+      scoreCandidatesMs: 0,
+      thresholdMs: 0,
+      budgetMs: 0,
+      shapeResultsMs: 0
+    }
+  };
+}
+function finishRecallTrace(summary, trace, noResultReason) {
+  if (noResultReason) {
+    summary.ranking.noResultReason = noResultReason;
+  }
+  trace.reportSummary(summary);
+}
+function scoreMergedCandidate(candidate, queryText, queryEmbedding, params) {
+  const vector = candidate.vectorSim ?? cosineSimilarity(candidate.entry.embedding ?? [], queryEmbedding);
+  const lexical = computeLexicalScore(queryText, candidate.entry.subject, candidate.entry.content);
+  const recency = resolveRecencyScore(candidate.entry, params);
+  const importance = importanceScore(candidate.entry.importance);
+  const scored = scoreCandidate({
+    vectorSim: vector,
+    lexical,
+    recency,
+    importance
+  });
+  return {
+    entry: candidate.entry,
+    score: scored.score,
+    scores: scored.scores
+  };
+}
+async function expandHistoricalCandidates(mergedCandidates, queryEmbedding, ports, params) {
+  if (params.rankingProfile !== "historical_state" || mergedCandidates.size === 0 || !ports.fetchPredecessors) {
+    return;
+  }
+  const predecessors = await ports.fetchPredecessors({
+    activeEntryIds: params.activeEntryIds
+  });
+  for (const entry of predecessors) {
+    if (mergedCandidates.has(entry.id)) {
+      continue;
+    }
+    mergedCandidates.set(entry.id, {
+      entry,
+      vectorSim: cosineSimilarity(entry.embedding ?? [], queryEmbedding)
+    });
+  }
+}
+function resolveRecencyScore(entry, params) {
+  if (params.aroundDate) {
+    return gaussianRecency(entry.created_at, params.aroundDate, normalizeAroundRadius(params.aroundRadius));
+  }
+  if (params.rankingProfile === "historical_state") {
+    return HISTORICAL_STATE_FLAT_RECENCY;
+  }
+  return recencyScore(entry.created_at, entry.expiry);
+}
+function applyHistoricalLineageBoosts(candidates, params) {
+  if (params.rankingProfile !== "historical_state") {
+    return candidates;
+  }
+  const entries = candidates.map((candidate) => candidate.entry);
+  return candidates.map((candidate) => {
+    const bonus = resolveHistoricalLineageBonus(candidate.entry, entries, params.aroundDate);
+    if (bonus <= 0) {
+      return candidate;
+    }
+    return {
+      ...candidate,
+      score: Math.min(1, candidate.score + bonus)
+    };
+  });
+}
+function resolveHistoricalLineageBonus(entry, entries, aroundDate) {
+  if (entries.some((peer) => peer.id !== entry.id && entry.superseded_by === peer.id)) {
+    return HISTORICAL_PREDECESSOR_BOOST;
+  }
+  if (aroundDate) {
+    return 0;
+  }
+  const activePeers = entries.filter((peer) => peer.id !== entry.id && isPotentialCurrentPeer(peer) && isOlderHistoricalPeer(entry, peer));
+  if (activePeers.length === 0) {
+    return 0;
+  }
+  return entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST;
+}
+function isPotentialCurrentPeer(entry) {
+  return !entry.retired && entry.superseded_by === void 0;
+}
+function isOlderHistoricalPeer(left, right) {
+  return createdAtMs(left.created_at) < createdAtMs(right.created_at) && sharesHistoricalLineage(left, right);
+}
+function sharesHistoricalLineage(left, right) {
+  if (left.claim_key && right.claim_key && left.claim_key === right.claim_key) {
+    return true;
+  }
+  return sharesHistoricalTopic(left, right);
+}
+function sharesHistoricalTopic(left, right) {
+  const leftTokens = tokenize(left.subject);
+  const rightTokens = tokenize(right.subject);
+  if (leftTokens.length === 0 || rightTokens.length === 0) {
+    return false;
+  }
+  const sharedPrefixCount = countSharedPrefixTokens(leftTokens, rightTokens);
+  return sharedPrefixCount >= HISTORICAL_TOPIC_SHARED_PREFIX_MIN && sharedPrefixCount / leftTokens.length >= HISTORICAL_TOPIC_PREFIX_OF_CANDIDATE_MIN;
+}
+function createdAtMs(value) {
+  const timestamp = new Date(value).getTime();
+  return Number.isFinite(timestamp) ? timestamp : 0;
+}
+function countSharedPrefixTokens(leftTokens, rightTokens) {
+  const length = Math.min(leftTokens.length, rightTokens.length);
+  let sharedPrefixCount = 0;
+  for (let index = 0; index < length; index += 1) {
+    if (leftTokens[index] !== rightTokens[index]) {
+      break;
+    }
+    sharedPrefixCount += 1;
+  }
+  return sharedPrefixCount;
+}
+function hasSufficientReturnEvidence(candidate) {
+  if (candidate.scores.lexical > 0) {
+    return true;
+  }
+  return candidate.scores.vector >= MIN_VECTOR_ONLY_EVIDENCE;
+}
+function mergeCandidates(vectorCandidates, ftsCandidates) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const candidate of vectorCandidates) {
+    merged.set(candidate.entry.id, {
+      entry: candidate.entry,
+      vectorSim: candidate.vectorSim
+    });
+  }
+  for (const candidate of ftsCandidates) {
+    const existing = merged.get(candidate.entry.id);
+    if (existing) {
+      existing.entry = existing.entry.embedding ? existing.entry : candidate.entry;
+      continue;
+    }
+    merged.set(candidate.entry.id, {
+      entry: candidate.entry
+    });
+  }
+  return merged;
+}
+function buildEntryFilters(types, tags, since, until) {
+  const filters = {};
+  if (types && types.length > 0) {
+    filters.types = types;
+  }
+  if (tags && tags.length > 0) {
+    filters.tags = tags;
+  }
+  if (since) {
+    filters.since = since;
+  }
+  if (until) {
+    filters.until = until;
+  }
+  return Object.keys(filters).length > 0 ? filters : void 0;
+}
+function applyBudget(results, budget) {
+  if (results.length === 0) {
+    return [];
+  }
+  const accepted = [results[0]];
+  let consumed = estimateTokens(results[0].entry);
+  for (const result of results.slice(1)) {
+    const estimate = estimateTokens(result.entry);
+    if (consumed + estimate > budget) {
+      continue;
+    }
+    accepted.push(result);
+    consumed += estimate;
+  }
+  return accepted;
+}
+function estimateTokens(entry) {
+  return (entry.subject.length + entry.content.length) / 4;
+}
+function parseAroundDate(value) {
+  return parseRelativeDate(value) ?? inferAroundDate(value);
+}
+function normalizeLimit(value) {
+  if (!Number.isFinite(value)) {
+    return 10;
+  }
+  return Math.max(0, Math.floor(value ?? 10));
+}
+function normalizeThreshold(value) {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(1, Math.max(0, value ?? 0));
+}
+function normalizeBudget(value) {
+  if (!Number.isFinite(value)) {
+    return null;
+  }
+  return Math.max(0, value ?? 0);
+}
+function normalizeAroundRadius(value) {
+  if (!Number.isFinite(value) || (value ?? 0) <= 0) {
+    return 14;
+  }
+  return value;
+}
+function elapsedMs(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+export {
+  recencyScore,
+  gaussianRecency,
+  importanceScore,
+  combinedRelevance,
+  scoreCandidate,
+  cosineSimilarity,
+  inferAroundDate,
+  parseRelativeDate,
+  tokenize,
+  buildLexicalPlan,
+  computeLexicalScore,
+  recall
+};