@agenr/agenr-plugin 1.7.3 → 1.8.0

package/dist/chunk-GUDCFFRV.js

@@ -0,0 +1,1517 @@
+// 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"]);
+var LEXICAL_TOKEN_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}._-]*/gu;
+function tokenize(text) {
+  const matches = normalizeLexicalText(text).match(LEXICAL_TOKEN_PATTERN) ?? [];
+  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) => normalizeLexicalText(text).trim();
+var normalizeLexicalText = (text) => text.normalize("NFKC").toLocaleLowerCase();
+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/claim-key.ts
+var UNKNOWN_SEGMENT = "unknown";
+var SELF_REFERENTIAL_ENTITIES = /* @__PURE__ */ new Set(["i", "me", "myself", "the_user", "user", "we", "our_team", "the_project", "this_project"]);
+var GENERIC_ENTITIES = /* @__PURE__ */ new Set([
+  "app",
+  "company",
+  "config",
+  "data",
+  "device",
+  "entity",
+  "environment",
+  "item",
+  "organization",
+  "person",
+  "place",
+  "project",
+  "service",
+  "setting",
+  "system",
+  "team",
+  "thing",
+  "user",
+  "workspace"
+]);
+var GENERIC_ATTRIBUTES = /* @__PURE__ */ new Set(["info", "details", "config", "stuff", "thing", "data"]);
+var COMPACTION_RELATION_TOKENS = /* @__PURE__ */ new Set([
+  "after",
+  "before",
+  "depend",
+  "depends",
+  "follows",
+  "follow",
+  "keep",
+  "keeps",
+  "maintain",
+  "maintains",
+  "need",
+  "needs",
+  "precede",
+  "precedes",
+  "preserve",
+  "preserves",
+  "require",
+  "required",
+  "requires",
+  "retain",
+  "retains"
+]);
+var COMPACTION_BREAK_TOKENS = /* @__PURE__ */ new Set(["about", "across", "and", "between", "during", "for", "from", "into", "onto", "or", "to", "with"]);
+var COMPACTION_WEAK_LEADING_TOKENS = /* @__PURE__ */ new Set(["actual", "authoritative", "canonical", "concrete", "current", "durable", "existing", "real"]);
+var ACTION_CONDITION_TOKENS = /* @__PURE__ */ new Set(["activate", "activation", "apply", "fire", "launch", "run", "start", "trigger"]);
+var TRAILING_OBJECT_COMPACTION_PREPOSITIONS = /* @__PURE__ */ new Set(["about", "for", "from", "into", "onto", "to", "with"]);
+var TRAILING_OBJECT_TRANSFER_HEADS = /* @__PURE__ */ new Set([
+  "access",
+  "boundary",
+  "condition",
+  "contract",
+  "guide",
+  "path",
+  "policy",
+  "preference",
+  "process",
+  "rule",
+  "schedule",
+  "support",
+  "surface",
+  "window",
+  "workflow"
+]);
+var STABLE_ATTRIBUTE_HEADS = /* @__PURE__ */ new Set([
+  "access",
+  "boundary",
+  "condition",
+  "contract",
+  "default",
+  "dependency",
+  "guide",
+  "mode",
+  "order",
+  "path",
+  "policy",
+  "preference",
+  "preservation",
+  "process",
+  "requirement",
+  "rule",
+  "schedule",
+  "setting",
+  "status",
+  "strategy",
+  "support",
+  "surface",
+  "timezone",
+  "truth",
+  "version",
+  "window",
+  "workflow"
+]);
+function normalizeClaimKeySegment(value) {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+}
+function normalizeClaimKey(value) {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: "empty" };
+  }
+  const slashCount = Array.from(trimmed).filter((character) => character === "/").length;
+  if (slashCount === 0) {
+    return { ok: false, reason: "missing_separator" };
+  }
+  if (slashCount !== 1) {
+    return { ok: false, reason: "too_many_segments" };
+  }
+  const [rawEntity = "", rawAttribute = ""] = trimmed.split("/");
+  const entity = normalizeClaimKeySegment(rawEntity);
+  if (entity.length === 0) {
+    return { ok: false, reason: "empty_entity" };
+  }
+  const attribute = normalizeClaimKeySegment(rawAttribute);
+  if (attribute.length === 0) {
+    return { ok: false, reason: "empty_attribute" };
+  }
+  if (entity === UNKNOWN_SEGMENT && attribute === UNKNOWN_SEGMENT) {
+    return { ok: false, reason: "unknown_pair" };
+  }
+  return {
+    ok: true,
+    value: {
+      claimKey: `${entity}/${attribute}`,
+      entity,
+      attribute
+    }
+  };
+}
+function compactClaimKey(claimKey) {
+  const normalized = normalizeClaimKey(claimKey);
+  if (!normalized.ok) {
+    return null;
+  }
+  let attributeTokens = normalized.value.attribute.split("_").filter((token) => token.length > 0);
+  const entityTokens = normalized.value.entity.split("_").filter((token) => token.length > 0);
+  const reasons = [];
+  if (entityTokens.length > 0 && startsWithTokens(attributeTokens, entityTokens) && attributeTokens.length > entityTokens.length) {
+    attributeTokens = attributeTokens.slice(entityTokens.length);
+    reasons.push("removed duplicated entity prefix from attribute");
+  }
+  if (entityTokens.length > 0 && attributeTokens.length > entityTokens.length + 1 && endsWithTokens(attributeTokens, entityTokens) && TRAILING_OBJECT_COMPACTION_PREPOSITIONS.has(attributeTokens[attributeTokens.length - entityTokens.length - 1] ?? "")) {
+    attributeTokens = attributeTokens.slice(0, attributeTokens.length - entityTokens.length - 1);
+    reasons.push("removed duplicated entity suffix from attribute");
+  }
+  const sourceOfTruthCompaction = compactSourceOfTruthAttribute(attributeTokens);
+  if (sourceOfTruthCompaction) {
+    attributeTokens = sourceOfTruthCompaction.attributeTokens;
+    reasons.push(sourceOfTruthCompaction.reason);
+  } else {
+    const relationCompaction = compactRelationAttribute(attributeTokens);
+    if (relationCompaction) {
+      attributeTokens = relationCompaction.attributeTokens;
+      reasons.push(relationCompaction.reason);
+    } else {
+      const trailingObjectCompaction = compactTrailingObjectAttribute(attributeTokens);
+      if (trailingObjectCompaction) {
+        attributeTokens = trailingObjectCompaction.attributeTokens;
+        reasons.push(trailingObjectCompaction.reason);
+      }
+    }
+  }
+  const attribute = attributeTokens.join("_");
+  if (attribute.length === 0) {
+    return {
+      claimKey: normalized.value.claimKey,
+      entity: normalized.value.entity,
+      attribute: normalized.value.attribute,
+      compactedFrom: null,
+      reason: null
+    };
+  }
+  const compactedClaimKey = `${normalized.value.entity}/${attribute}`;
+  return {
+    claimKey: compactedClaimKey,
+    entity: normalized.value.entity,
+    attribute,
+    compactedFrom: compactedClaimKey !== normalized.value.claimKey ? normalized.value.claimKey : null,
+    reason: reasons.length > 0 ? joinCompactionReasons(reasons) : null
+  };
+}
+function validateExtractedClaimKey(claimKey) {
+  if (SELF_REFERENTIAL_ENTITIES.has(claimKey.entity)) {
+    return {
+      ok: false,
+      reason: "self_referential_entity",
+      value: claimKey
+    };
+  }
+  if (GENERIC_ATTRIBUTES.has(claimKey.attribute)) {
+    return {
+      ok: false,
+      reason: "generic_attribute",
+      value: claimKey
+    };
+  }
+  if (isValueShapedAttribute(claimKey.attribute)) {
+    return {
+      ok: false,
+      reason: "value_shaped_attribute",
+      value: claimKey
+    };
+  }
+  return {
+    ok: true,
+    value: claimKey
+  };
+}
+function inspectClaimKey(value) {
+  const rawClaimKey = value.trim();
+  const normalized = normalizeClaimKey(rawClaimKey);
+  if (!normalized.ok) {
+    return {
+      rawClaimKey,
+      canonical: false,
+      normalizationFailure: normalized.reason,
+      suspectReasons: []
+    };
+  }
+  const suspectReasons = /* @__PURE__ */ new Set();
+  const validation = validateExtractedClaimKey(normalized.value);
+  if (!validation.ok) {
+    suspectReasons.add(validation.reason);
+  }
+  if (GENERIC_ENTITIES.has(normalized.value.entity)) {
+    suspectReasons.add("generic_entity");
+  }
+  return {
+    rawClaimKey,
+    canonical: normalized.value.claimKey === rawClaimKey,
+    normalized: normalized.value,
+    suspectReasons: [...suspectReasons]
+  };
+}
+function isTrustedClaimKeyForCleanup(value) {
+  const inspection = inspectClaimKey(value);
+  return Boolean(inspection.canonical && inspection.normalized && inspection.suspectReasons.length === 0);
+}
+function describeClaimKeyNormalizationFailure(reason) {
+  switch (reason) {
+    case "empty":
+      return "claim key was empty";
+    case "missing_separator":
+      return "claim key must contain exactly one '/'";
+    case "too_many_segments":
+      return "claim key must contain exactly one '/'";
+    case "empty_entity":
+      return "claim key entity was empty after normalization";
+    case "empty_attribute":
+      return "claim key attribute was empty after normalization";
+    case "unknown_pair":
+      return 'claim key "unknown/unknown" is not allowed';
+  }
+}
+function describeExtractedClaimKeyRejection(reason, claimKey) {
+  switch (reason) {
+    case "self_referential_entity":
+      return `entity "${claimKey.entity}" is self-referential`;
+    case "generic_attribute":
+      return `attribute "${claimKey.attribute}" is too generic`;
+    case "value_shaped_attribute":
+      return `attribute "${claimKey.attribute}" looks value-shaped`;
+  }
+}
+function describeClaimKeySuspicion(reason, claimKey) {
+  switch (reason) {
+    case "generic_entity":
+      return `entity "${claimKey.entity}" is too generic`;
+    case "self_referential_entity":
+    case "generic_attribute":
+    case "value_shaped_attribute":
+      return describeExtractedClaimKeyRejection(reason, claimKey);
+  }
+}
+function isValueShapedAttribute(attribute) {
+  return /^\d+(?:_\d+)*$/u.test(attribute) || /^v\d+(?:_\d+)*$/u.test(attribute);
+}
+function compactSourceOfTruthAttribute(attributeTokens) {
+  const sourceOfTruthIndex = findSourceOfTruthPhraseIndex(attributeTokens);
+  if (sourceOfTruthIndex === -1) {
+    return null;
+  }
+  const normalizedPhrase = ["source", "of", "truth"];
+  if (attributeTokens.length === normalizedPhrase.length && startsWithTokens(attributeTokens, normalizedPhrase)) {
+    return null;
+  }
+  const before = attributeTokens.slice(0, sourceOfTruthIndex);
+  const after = attributeTokens.slice(sourceOfTruthIndex + normalizedPhrase.length);
+  const leadingAllowed = before.every((token) => COMPACTION_WEAK_LEADING_TOKENS.has(token));
+  const hasMixedStableFamily = before.some((token) => STABLE_ATTRIBUTE_HEADS.has(token)) || after.some((token) => STABLE_ATTRIBUTE_HEADS.has(token));
+  const hasConjunctionNoise = before.includes("and") || before.includes("or") || after.includes("and") || after.includes("or");
+  if (!leadingAllowed || hasMixedStableFamily || hasConjunctionNoise) {
+    return null;
+  }
+  return {
+    attributeTokens: normalizedPhrase,
+    reason: "collapsed source-of-truth phrasing into the stable canonical slot"
+  };
+}
+function compactRelationAttribute(attributeTokens) {
+  const relationIndex = attributeTokens.findIndex((token) => COMPACTION_RELATION_TOKENS.has(token));
+  if (relationIndex === -1) {
+    return null;
+  }
+  const relation = attributeTokens[relationIndex] ?? "";
+  const left = attributeTokens.slice(0, relationIndex);
+  const right = attributeTokens.slice(relationIndex + 1);
+  if (left.length === 0 && right.length === 0) {
+    return null;
+  }
+  if (isRequirementRelation(relation)) {
+    const conditionAction = extractConditionAction(right);
+    if (conditionAction) {
+      return {
+        attributeTokens: [conditionAction, "condition"],
+        reason: `collapsed a sentence-like ${conditionAction} requirement into a stable condition slot`
+      };
+    }
+    const requirementFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!requirementFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...requirementFocus, "requirement"],
+      reason: "collapsed a sentence-like requirement phrase into a stable requirement slot"
+    };
+  }
+  if (isOrderingRelation(relation)) {
+    const orderingFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!orderingFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...orderingFocus, "order"],
+      reason: "collapsed a sentence-like ordering phrase into a stable order slot"
+    };
+  }
+  if (isPreservationRelation(relation)) {
+    const preservationFocus = extractCompactionFocus(right, 2) ?? extractCompactionFocus(left, 2);
+    if (!preservationFocus) {
+      return null;
+    }
+    return {
+      attributeTokens: [...preservationFocus, "preservation"],
+      reason: "collapsed a sentence-like preservation phrase into a stable preservation slot"
+    };
+  }
+  return null;
+}
+function compactTrailingObjectAttribute(attributeTokens) {
+  const prepositionIndex = attributeTokens.findIndex((token) => TRAILING_OBJECT_COMPACTION_PREPOSITIONS.has(token));
+  if (prepositionIndex <= 0 || prepositionIndex >= attributeTokens.length - 1) {
+    return null;
+  }
+  const left = trimWeakLeadingTokens(attributeTokens.slice(0, prepositionIndex));
+  const right = attributeTokens.slice(prepositionIndex + 1);
+  if (left.length === 0 || left.length > 3 || left.includes("and") || left.includes("or") || left.some((token) => COMPACTION_RELATION_TOKENS.has(token))) {
+    return null;
+  }
+  const head = left[left.length - 1];
+  if (!head || !TRAILING_OBJECT_TRANSFER_HEADS.has(head)) {
+    return null;
+  }
+  const objectFocus = extractCompactionFocus(right, 2);
+  if (!objectFocus) {
+    return null;
+  }
+  const headCore = extractStableHeadCore(left, 2);
+  if (!headCore) {
+    return null;
+  }
+  return {
+    attributeTokens: [...objectFocus, ...headCore],
+    reason: "collapsed a trailing object phrase into a compact stable slot name"
+  };
+}
+function findSourceOfTruthPhraseIndex(tokens) {
+  for (let index = 0; index <= tokens.length - 3; index += 1) {
+    if (tokens[index] === "source" && tokens[index + 1] === "of" && tokens[index + 2] === "truth") {
+      return index;
+    }
+  }
+  return -1;
+}
+function extractConditionAction(tokens) {
+  for (let index = tokens.length - 1; index >= 0; index -= 1) {
+    const token = tokens[index];
+    if (token && ACTION_CONDITION_TOKENS.has(token)) {
+      return token;
+    }
+  }
+  return null;
+}
+function extractCompactionFocus(tokens, limit) {
+  const compactable = trimWeakLeadingTokens(tokens).filter((token) => token.length > 0);
+  const segments = splitTokensOnBreaks(compactable).filter((segment) => segment.length > 0);
+  const preferredSegment = segments[0];
+  if (!preferredSegment || preferredSegment.length === 0) {
+    return null;
+  }
+  return preferredSegment.slice(0, limit);
+}
+function extractStableHeadCore(tokens, limit) {
+  const compactable = trimWeakLeadingTokens(tokens).filter((token) => token.length > 0);
+  const head = compactable[compactable.length - 1];
+  if (!head || !STABLE_ATTRIBUTE_HEADS.has(head)) {
+    return null;
+  }
+  return compactable.slice(Math.max(0, compactable.length - limit));
+}
+function splitTokensOnBreaks(tokens) {
+  const segments = [];
+  let current = [];
+  for (const token of tokens) {
+    if (COMPACTION_BREAK_TOKENS.has(token)) {
+      if (current.length > 0) {
+        segments.push(current);
+        current = [];
+      }
+      continue;
+    }
+    current.push(token);
+  }
+  if (current.length > 0) {
+    segments.push(current);
+  }
+  return segments;
+}
+function trimWeakLeadingTokens(tokens) {
+  let start = 0;
+  while (start < tokens.length && COMPACTION_WEAK_LEADING_TOKENS.has(tokens[start] ?? "")) {
+    start += 1;
+  }
+  return tokens.slice(start);
+}
+function joinCompactionReasons(reasons) {
+  if (reasons.length <= 1) {
+    return reasons[0] ?? "";
+  }
+  return `${reasons.slice(0, -1).join(", ")} and ${reasons[reasons.length - 1]}`;
+}
+function isRequirementRelation(token) {
+  return token === "depend" || token === "depends" || token === "need" || token === "needs" || token === "required" || token === "require" || token === "requires";
+}
+function isOrderingRelation(token) {
+  return token === "after" || token === "before" || token === "follow" || token === "follows" || token === "precede" || token === "precedes";
+}
+function isPreservationRelation(token) {
+  return token === "keep" || token === "keeps" || token === "maintain" || token === "maintains" || token === "preserve" || token === "preserves" || token === "retain" || token === "retains";
+}
+function startsWithTokens(tokens, prefix) {
+  return prefix.every((token, index) => tokens[index] === token);
+}
+function endsWithTokens(tokens, suffix) {
+  return suffix.every((token, index) => tokens[tokens.length - suffix.length + index] === token);
+}
+
+// src/core/claim-slot-policy.ts
+var MULTIVALUED_ATTRIBUTE_HEADS = /* @__PURE__ */ new Set(["access", "dependency", "guide", "integration", "preference", "requirement", "support"]);
+function resolveClaimSlotPolicy(claimKey, config) {
+  const normalized = normalizeClaimKey(claimKey ?? "");
+  if (!normalized.ok) {
+    return {
+      policy: "exclusive",
+      reason: "No canonical claim key was available, so the slot policy defaulted to exclusive."
+    };
+  }
+  const { claimKey: canonicalClaimKey, entity, attribute } = normalized.value;
+  const attributeHead = attribute.split("_")[0] ?? attribute;
+  const configuredPolicy = resolveConfiguredAttributeHeadPolicy(attributeHead, config);
+  if (configuredPolicy) {
+    return {
+      claimKey: canonicalClaimKey,
+      entity,
+      attribute,
+      attributeHead,
+      policy: configuredPolicy,
+      reason: `Attribute head "${attributeHead}" is configured as ${configuredPolicy} by runtime policy.`
+    };
+  }
+  if (MULTIVALUED_ATTRIBUTE_HEADS.has(attributeHead)) {
+    return {
+      claimKey: canonicalClaimKey,
+      entity,
+      attribute,
+      attributeHead,
+      policy: "multivalued",
+      reason: `Attribute head "${attributeHead}" is registered as multivalued.`
+    };
+  }
+  return {
+    claimKey: canonicalClaimKey,
+    entity,
+    attribute,
+    attributeHead,
+    policy: "exclusive",
+    reason: `Attribute head "${attributeHead}" defaults to exclusive current-state shaping.`
+  };
+}
+function resolveConfiguredAttributeHeadPolicy(attributeHead, config) {
+  const configuredPolicy = config?.attributeHeads?.[attributeHead];
+  if (configuredPolicy) {
+    return configuredPolicy;
+  }
+  const loweredAttributeHead = attributeHead.toLowerCase();
+  if (loweredAttributeHead === attributeHead) {
+    return void 0;
+  }
+  return config?.attributeHeads?.[loweredAttributeHead];
+}
+
+// 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;
+var CLAIM_KEY_TENTATIVE_CURRENT_PENALTY = 0.08;
+var CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_PENALTY = 0.05;
+var CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_MAX_PENALTY = 0.15;
+var QUERY_EMBEDDING_FAILURE_NOTICE = "Embeddings failed during recall, so Agenr fell back to lexical-only entry ranking.";
+var VECTOR_SEARCH_FAILURE_NOTICE = "Vector search failed during recall, so Agenr continued with lexical entry candidates only.";
+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 asOfDate = query.asOf ? parseAroundDate(query.asOf) : null;
+  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 slotPolicyConfig = options.slotPolicyConfig;
+  const summary = buildRecallTraceSummary({
+    filters,
+    limit,
+    threshold,
+    budget,
+    asOfDate,
+    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 {
+    let queryEmbedding = [];
+    try {
+      queryEmbedding = await ports.embed(text);
+    } catch {
+      markRecallDegraded(summary, "query_embedding_failed", QUERY_EMBEDDING_FAILURE_NOTICE);
+    }
+    const vectorSearchLimit = limit * 4;
+    const lexicalSearchLimit = limit * 2;
+    const [vectorCandidates, ftsCandidates] = queryEmbedding.length > 0 ? await Promise.all([
+      ports.vectorSearch({
+        embedding: queryEmbedding,
+        limit: vectorSearchLimit,
+        filters
+      }).catch(() => {
+        markRecallDegraded(summary, "vector_search_failed", VECTOR_SEARCH_FAILURE_NOTICE);
+        return [];
+      }),
+      ports.ftsSearch({
+        text,
+        limit: lexicalSearchLimit,
+        filters
+      })
+    ]) : [
+      [],
+      await ports.ftsSearch({
+        text,
+        limit: lexicalSearchLimit,
+        filters
+      })
+    ];
+    summary.degraded.lexicalOnly = summary.degraded.active && queryEmbedding.length === 0;
+    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 = applyClaimKeyResultShaping(
+      applyHistoricalLineageBoosts(
+        Array.from(mergedCandidates.values()).map(
+          (candidate) => scoreMergedCandidate(candidate, text, queryEmbedding, {
+            asOfDate,
+            aroundDate,
+            aroundRadius: query.aroundRadius,
+            rankingProfile: query.rankingProfile
+          })
+        ),
+        {
+          aroundDate,
+          rankingProfile: query.rankingProfile
+        },
+        summary.claimKey,
+        slotPolicyConfig
+      ),
+      summary.claimKey,
+      slotPolicyConfig
+    ).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(resolveNoResultReason(summary, 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(resolveNoResultReason(summary, "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,
+      ...params.asOfDate ? {
+        asOf: {
+          anchor: params.asOfDate.toISOString()
+        }
+      } : {}
+    },
+    ranking: {
+      limit: params.limit,
+      threshold: params.threshold,
+      budget: params.budget
+    },
+    candidateCounts: {
+      merged: 0,
+      thresholdQualified: 0,
+      budgetAccepted: 0,
+      finalRanked: 0,
+      returned: 0
+    },
+    claimKey: {
+      historicalBoosted: 0,
+      tentativeLineageSuppressed: 0,
+      trustPenalized: 0,
+      redundancyPenalized: 0
+    },
+    timings: {
+      mergeCandidatesMs: 0,
+      scoreCandidatesMs: 0,
+      thresholdMs: 0,
+      budgetMs: 0,
+      shapeResultsMs: 0
+    },
+    degraded: {
+      active: false,
+      reasons: [],
+      lexicalOnly: false,
+      notices: []
+    }
+  };
+}
+function finishRecallTrace(summary, trace, noResultReason) {
+  if (noResultReason) {
+    summary.ranking.noResultReason = noResultReason;
+  }
+  trace.reportSummary(summary);
+}
+function markRecallDegraded(summary, reason, notice) {
+  summary.degraded.active = true;
+  if (!summary.degraded.reasons.includes(reason)) {
+    summary.degraded.reasons.push(reason);
+  }
+  if (!summary.degraded.notices.includes(notice)) {
+    summary.degraded.notices.push(notice);
+  }
+}
+function resolveNoResultReason(summary, reason) {
+  if (!summary.degraded.active) {
+    return reason;
+  }
+  if (reason === "no_candidates") {
+    return "degraded_no_candidates";
+  }
+  if (reason === "below_threshold") {
+    return "degraded_below_threshold";
+  }
+  return reason;
+}
+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,
+      historicalLineage: 0,
+      claimKeyTrustPenalty: 0,
+      claimKeyRedundancyPenalty: 0
+    }
+  };
+}
+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.asOfDate) {
+    return resolveAsOfScore(entry, params.asOfDate);
+  }
+  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 resolveAsOfScore(entry, asOfDate) {
+  const validFrom = parseTimestamp(entry.valid_from);
+  const validTo = parseTimestamp(entry.valid_to);
+  if (validFrom || validTo) {
+    const startMs = validFrom?.getTime() ?? Number.NEGATIVE_INFINITY;
+    const endMs = validTo?.getTime() ?? Number.POSITIVE_INFINITY;
+    const asOfMs = asOfDate.getTime();
+    if (asOfMs >= startMs && asOfMs <= endMs) {
+      return 1;
+    }
+    const nearestBoundaryMs = asOfMs < startMs ? startMs : endMs;
+    return Math.max(0.1, gaussianRecency(new Date(nearestBoundaryMs).toISOString(), asOfDate, 21) * 0.65);
+  }
+  const observedAt = parseTimestamp(entry.claim_support_observed_at);
+  if (observedAt) {
+    const observedBeforeAsOf = observedAt.getTime() <= asOfDate.getTime();
+    const proximity = gaussianRecency(observedAt.toISOString(), asOfDate, 30);
+    return observedBeforeAsOf ? Math.max(0.45, proximity * 0.8) : Math.max(0.05, proximity * 0.2);
+  }
+  const createdAt = parseTimestamp(entry.created_at);
+  if (createdAt) {
+    const createdBeforeAsOf = createdAt.getTime() <= asOfDate.getTime();
+    const proximity = gaussianRecency(createdAt.toISOString(), asOfDate, 45);
+    return createdBeforeAsOf ? Math.max(0.35, proximity * 0.7) : Math.max(0.05, proximity * 0.15);
+  }
+  return HISTORICAL_STATE_FLAT_RECENCY;
+}
+function applyHistoricalLineageBoosts(candidates, params, claimKeyTrace, slotPolicyConfig) {
+  if (params.rankingProfile !== "historical_state") {
+    return candidates;
+  }
+  const entries = candidates.map((candidate) => candidate.entry);
+  return candidates.map((candidate) => {
+    const decision = resolveHistoricalLineageBonus(candidate.entry, entries, params.aroundDate, slotPolicyConfig);
+    if (decision.tentativeLineageSuppressed) {
+      claimKeyTrace.tentativeLineageSuppressed += 1;
+    }
+    const bonus = decision.bonus;
+    if (bonus <= 0) {
+      return candidate;
+    }
+    claimKeyTrace.historicalBoosted += 1;
+    return {
+      ...candidate,
+      score: clampRecallScore(candidate.score + bonus),
+      scores: {
+        ...candidate.scores,
+        historicalLineage: candidate.scores.historicalLineage + bonus
+      }
+    };
+  });
+}
+function resolveHistoricalLineageBonus(entry, entries, aroundDate, slotPolicyConfig) {
+  if (entries.some((peer) => peer.id !== entry.id && entry.superseded_by === peer.id)) {
+    return {
+      bonus: HISTORICAL_PREDECESSOR_BOOST,
+      tentativeLineageSuppressed: false
+    };
+  }
+  if (aroundDate) {
+    return {
+      bonus: 0,
+      tentativeLineageSuppressed: false
+    };
+  }
+  let tentativeLineageSuppressed = false;
+  for (const peer of entries) {
+    if (peer.id === entry.id || !isPotentialCurrentPeer(peer) || createdAtMs(entry.created_at) >= createdAtMs(peer.created_at)) {
+      continue;
+    }
+    const relation = resolveHistoricalPeerRelation(entry, peer, entries, slotPolicyConfig);
+    if (relation === "tentative_claim_key_suppressed") {
+      tentativeLineageSuppressed = true;
+      continue;
+    }
+    if (relation === null) {
+      continue;
+    }
+    return {
+      bonus: entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST,
+      tentativeLineageSuppressed
+    };
+  }
+  return {
+    bonus: 0,
+    tentativeLineageSuppressed
+  };
+}
+function isPotentialCurrentPeer(entry) {
+  return !entry.retired && entry.superseded_by === void 0;
+}
+function resolveHistoricalPeerRelation(left, right, entries, slotPolicyConfig) {
+  if (left.claim_key && right.claim_key && left.claim_key === right.claim_key) {
+    if (resolveClaimSlotPolicy(left.claim_key, slotPolicyConfig).policy === "multivalued") {
+      return null;
+    }
+    return canUseClaimKeyLineage(left, entries, slotPolicyConfig) ? "claim_key" : "tentative_claim_key_suppressed";
+  }
+  return sharesHistoricalTopic(left, right) ? "topic" : null;
+}
+function canUseClaimKeyLineage(entry, entries, slotPolicyConfig) {
+  if (!entry.claim_key) {
+    return false;
+  }
+  if (resolveClaimSlotPolicy(entry.claim_key, slotPolicyConfig).policy === "multivalued") {
+    return false;
+  }
+  if (!hasTrustedClaimKeyEvidence(entries, entry.claim_key)) {
+    return true;
+  }
+  return entry.claim_key_status === "trusted";
+}
+function hasTrustedClaimKeyEvidence(entries, claimKey) {
+  return entries.some((entry) => entry.claim_key === claimKey && entry.claim_key_status === "trusted");
+}
+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) {
+  return parseTimestamp(value)?.getTime() ?? 0;
+}
+function parseTimestamp(value) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return null;
+  }
+  const timestamp = new Date(normalized);
+  return Number.isFinite(timestamp.getTime()) ? timestamp : null;
+}
+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 applyClaimKeyResultShaping(candidates, claimKeyTrace, slotPolicyConfig) {
+  if (candidates.length === 0) {
+    return candidates;
+  }
+  const trustedActiveClaimKeys = new Set(
+    candidates.map((candidate) => candidate.entry).filter(
+      (entry) => isPotentialCurrentPeer(entry) && entry.claim_key && entry.claim_key_status === "trusted" && resolveClaimSlotPolicy(entry.claim_key, slotPolicyConfig).policy === "exclusive"
+    ).map((entry) => entry.claim_key)
+  );
+  const trustedSlotRankById = rankTrustedSlotSiblings(candidates, slotPolicyConfig);
+  return candidates.map((candidate) => {
+    const trustPenalty = shouldPenalizeTentativeCurrentSibling(candidate.entry, trustedActiveClaimKeys) ? CLAIM_KEY_TENTATIVE_CURRENT_PENALTY : 0;
+    const redundancyPenalty = resolveTrustedSlotRedundancyPenalty(candidate.entry.id, trustedSlotRankById);
+    if (trustPenalty <= 0 && redundancyPenalty <= 0) {
+      return candidate;
+    }
+    if (trustPenalty > 0) {
+      claimKeyTrace.trustPenalized += 1;
+    }
+    if (redundancyPenalty > 0) {
+      claimKeyTrace.redundancyPenalized += 1;
+    }
+    return {
+      ...candidate,
+      score: clampRecallScore(candidate.score - trustPenalty - redundancyPenalty),
+      scores: {
+        ...candidate.scores,
+        claimKeyTrustPenalty: trustPenalty,
+        claimKeyRedundancyPenalty: redundancyPenalty
+      }
+    };
+  });
+}
+function rankTrustedSlotSiblings(candidates, slotPolicyConfig) {
+  const candidatesById = new Map(candidates.map((candidate) => [candidate.entry.id, candidate]));
+  const trustedByClaimKey = /* @__PURE__ */ new Map();
+  for (const candidate of candidates) {
+    const claimKey = candidate.entry.claim_key;
+    if (!claimKey || candidate.entry.claim_key_status !== "trusted" || !isPotentialCurrentPeer(candidate.entry) || resolveClaimSlotPolicy(claimKey, slotPolicyConfig).policy !== "exclusive") {
+      continue;
+    }
+    const siblings = trustedByClaimKey.get(claimKey) ?? [];
+    siblings.push(candidate);
+    trustedByClaimKey.set(claimKey, siblings);
+  }
+  const ranks = /* @__PURE__ */ new Map();
+  for (const siblings of trustedByClaimKey.values()) {
+    siblings.slice().sort(compareCandidatesForTrustedSlotRank).forEach((candidate, index) => {
+      if (candidatesById.has(candidate.entry.id)) {
+        ranks.set(candidate.entry.id, index);
+      }
+    });
+  }
+  return ranks;
+}
+function compareCandidatesForTrustedSlotRank(left, right) {
+  return right.score - left.score || createdAtMs(right.entry.created_at) - createdAtMs(left.entry.created_at) || left.entry.id.localeCompare(right.entry.id);
+}
+function shouldPenalizeTentativeCurrentSibling(entry, trustedActiveClaimKeys) {
+  return isPotentialCurrentPeer(entry) && entry.claim_key !== void 0 && entry.claim_key_status !== "trusted" && trustedActiveClaimKeys.has(entry.claim_key);
+}
+function resolveTrustedSlotRedundancyPenalty(entryId, trustedSlotRankById) {
+  const rank = trustedSlotRankById.get(entryId) ?? 0;
+  if (rank <= 0) {
+    return 0;
+  }
+  return Math.min(CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_MAX_PENALTY, rank * CLAIM_KEY_REDUNDANT_TRUSTED_SLOT_PENALTY);
+}
+function clampRecallScore(value) {
+  return Math.max(0, Math.min(1, value));
+}
+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 (typeof value !== "number" || !Number.isFinite(value)) {
+    return 10;
+  }
+  return Math.max(0, Math.floor(value));
+}
+function normalizeThreshold(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  return Math.min(1, Math.max(0, value));
+}
+function normalizeBudget(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null;
+  }
+  return Math.max(0, value);
+}
+function normalizeAroundRadius(value) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return 14;
+  }
+  return value;
+}
+function elapsedMs(startedAt) {
+  return Math.max(0, Date.now() - startedAt);
+}
+
+export {
+  recencyScore,
+  gaussianRecency,
+  importanceScore,
+  combinedRelevance,
+  scoreCandidate,
+  cosineSimilarity,
+  normalizeClaimKeySegment,
+  normalizeClaimKey,
+  compactClaimKey,
+  validateExtractedClaimKey,
+  inspectClaimKey,
+  isTrustedClaimKeyForCleanup,
+  describeClaimKeyNormalizationFailure,
+  describeExtractedClaimKeyRejection,
+  describeClaimKeySuspicion,
+  inferAroundDate,
+  parseRelativeDate,
+  tokenize,
+  buildLexicalPlan,
+  computeLexicalScore,
+  resolveClaimSlotPolicy,
+  recall
+};