@agenr/skeln-plugin 3.3.0 → 2026.6.2

package/dist/{chunk-5LADPJ4C.js → chunk-GAERET5Q.js}

@@ -1,3 +1,11 @@
+import {
+  isCurrentlyValidMemory,
+  isStaleMemory,
+  isWithinValidityWindow,
+  normalizeClaimKey,
+  resolveKeyedDurableLifecycleStatus
+} from "./chunk-VBPYU7GO.js";
+
 // src/core/recall/cross-encoder.ts
 var DEFAULT_CROSS_ENCODER_TOP_K = 10;
 var DEFAULT_CROSS_ENCODER_ALPHA = 0.6;
@@ -125,6 +133,41 @@ function elapsedMs(startedAt) {
   return Math.max(0, Date.now() - startedAt);
 }
 
+// src/core/recall/entry-lineage.ts
+function describeDurableLineageState(entry, nowMs) {
+  if (entry.superseded_by) {
+    return "superseded";
+  }
+  if (!isCurrentlyValidMemory(entry, nowMs)) {
+    return "historical";
+  }
+  return "current";
+}
+function formatDurableClaimLifecycle(entry) {
+  const status = resolveKeyedDurableLifecycleStatus(entry);
+  return status === "no_key" ? "no-key" : status;
+}
+function summarizeClaimFamilyTransition(entries, nowMs) {
+  const current = entries.find((entry) => isCurrentlyValidMemory(entry, nowMs));
+  const prior = [...entries].reverse().find((entry) => entry.id !== current?.id && isHistoricalFamilyMember(entry, nowMs));
+  if (current && prior) {
+    return `${prior.id} -> ${current.id}`;
+  }
+  if (prior) {
+    return `${prior.id} is historical with no current sibling in the traced family`;
+  }
+  if (current) {
+    return `${current.id} is the only current sibling in the traced family`;
+  }
+  return void 0;
+}
+function isHistoricalFamilyMember(entry, nowMs) {
+  if (entry.superseded_by) {
+    return true;
+  }
+  return !isCurrentlyValidMemory(entry, nowMs);
+}
+
 // src/core/recall/fusion.ts
 var DEFAULT_RRF_RANK_CONSTANT = 60;
 var DEFAULT_RRF_SMALL_POOL_RANK_CONSTANT = 8;
@@ -268,9 +311,10 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
 ]);
 var FTS_OPERATOR_TOKENS = /* @__PURE__ */ new Set(["or", "not", "near"]);
 var LEXICAL_TOKEN_PATTERN = /[\p{L}\p{N}][\p{L}\p{N}._-]*/gu;
+var TOKEN_EDGE_PUNCTUATION_PATTERN = /^[._-]+|[._-]+$/gu;
 function tokenize(text) {
   const matches = normalizeLexicalText(text).match(LEXICAL_TOKEN_PATTERN) ?? [];
-  return matches.filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
+  return matches.map((token) => token.replace(TOKEN_EDGE_PUNCTUATION_PATTERN, "")).filter((token) => token.length >= 2 && !STOP_WORDS.has(token));
 }
 function buildLexicalPlan(text) {
   const trimmed = text.trim();
@@ -696,468 +740,6 @@ function sanitizeInteger(value, fallback) {
   return Math.floor(value);
 }
 
-// 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) {
@@ -1294,6 +876,38 @@ var inferMonthAnchor = (monthName, now) => {
   return new Date(Date.UTC(year, monthIndex, 15));
 };
 
+// src/core/recall/as-of-validity.ts
+function resolveRecallValidAsOf(params) {
+  if (params.rankingProfile === "historical_state") {
+    return null;
+  }
+  return new Date(params.asOfDate ? params.asOfDate.getTime() : params.nowMs);
+}
+function applyAsOfValidityFilter(mergeOutcome, summary, params) {
+  const asOf = resolveRecallValidAsOf(params);
+  if (asOf === null) {
+    return;
+  }
+  const asOfMs = asOf.getTime();
+  const removed = /* @__PURE__ */ new Set();
+  for (const [id, candidate] of mergeOutcome.merged) {
+    if (!isWithinValidityWindow(candidate.entry.valid_from, candidate.entry.valid_to, asOfMs)) {
+      mergeOutcome.merged.delete(id);
+      removed.add(id);
+    }
+  }
+  if (removed.size > 0) {
+    mergeOutcome.vectorRanks = mergeOutcome.vectorRanks.filter((id) => !removed.has(id));
+    mergeOutcome.ftsRanks = mergeOutcome.ftsRanks.filter((id) => !removed.has(id));
+  }
+  summary.filtering.asOfValidity = {
+    applied: true,
+    anchor: new Date(asOfMs).toISOString(),
+    source: params.asOfDate ? "explicit_as_of" : "now",
+    excludedCount: removed.size
+  };
+}
+
 // src/core/recall/trace.ts
 var NOOP_RECALL_TRACE_SINK = {
   reportSummary() {
@@ -1308,7 +922,7 @@ var HISTORICAL_NEIGHBORHOOD_FAMILIES = ["supersession_chain", "claim_key_sibling
 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_STALE_PREDECESSOR_BOOST = 0.06;
 var HISTORICAL_OLDER_STATE_BOOST = 0.08;
 var HISTORICAL_LINEAGE_GAP_MARGIN = 0.02;
 var HISTORICAL_LINEAGE_MAX_BONUS = 0.45;
@@ -1343,14 +957,20 @@ var MIN_VECTOR_WITHOUT_GROUNDED_LEXICAL_SUPPORT = 0.45;
 var GROUNDING_SORT_MAX_SCORE_GAP = 0.03;
 async function recall(query, ports, options = {}) {
   const text = query.text.trim();
+  const now = options.now ?? /* @__PURE__ */ new Date();
+  const nowMs = now.getTime();
   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 asOfDate = query.asOf ? parseAroundDate(query.asOf, now) : null;
+  const aroundDate = query.around !== void 0 ? parseAroundDate(query.around, now) : inferAroundDate(text, now);
+  const since = query.since ? parseRelativeDate(query.since, now) : null;
+  const until = query.until ? parseRelativeDate(query.until, now) : null;
+  const filters = buildDurableFilters(query.types, query.tags, since, until, {
+    asOfDate,
+    nowMs,
+    rankingProfile: query.rankingProfile
+  });
   const trace = options.trace ?? createNoopRecallTraceSink();
   const slotPolicyConfig = options.slotPolicyConfig;
   const summary = buildRecallTraceSummary({
@@ -1413,6 +1033,11 @@ async function recall(query, ports, options = {}) {
     summary.degraded.lexicalOnly = summary.degraded.active && queryEmbedding.length === 0;
     const mergeStartedAt = Date.now();
     const mergeOutcome = mergeCandidates(vectorCandidates, ftsCandidates);
+    applyAsOfValidityFilter(mergeOutcome, summary, {
+      rankingProfile: query.rankingProfile,
+      asOfDate,
+      nowMs
+    });
     const neighborhoodEnabled = options.rankingPolicy?.neighborhood !== "disabled";
     const expansionRanks = neighborhoodEnabled ? await expandEntryNeighborhood(mergeOutcome.merged, queryEmbedding, ports, {
       rankingProfile: query.rankingProfile,
@@ -1434,18 +1059,20 @@ async function recall(query, ports, options = {}) {
           asOfDate,
           aroundDate,
           aroundRadius: query.aroundRadius,
-          rankingProfile: query.rankingProfile
+          rankingProfile: query.rankingProfile,
+          now
         })
       ),
       {
         aroundDate,
-        rankingProfile: query.rankingProfile
+        rankingProfile: query.rankingProfile,
+        nowMs
       },
       summary.claimKey,
       slotPolicyConfig
     );
     const rerankedCandidates = neighborhoodEnabled ? applySeededEntryRerank(historicallyBoosted, summary.neighborhood) : historicallyBoosted;
-    const shaped = applyClaimKeyResultShaping(rerankedCandidates, summary.claimKey, slotPolicyConfig).sort((left, right) => right.score - left.score);
+    const shaped = applyClaimKeyResultShaping(rerankedCandidates, summary.claimKey, nowMs, slotPolicyConfig).sort((left, right) => right.score - left.score);
     const diversified = applyMmrDiversification(shaped, queryEmbedding, options.rankingPolicy, summary.mmr);
     const scored = await applyEntryCrossEncoderRerank(diversified, text, ports.crossEncoder, options.rankingPolicy, summary.crossEncoder);
     summary.timings.scoreCandidatesMs = elapsedMs2(scoreStartedAt);
@@ -1550,7 +1177,7 @@ function buildRecallTraceSummary(params) {
       expansionRequested: false,
       expansionAvailable: false,
       familiesRequested: [],
-      includeRetired: false,
+      includeHistorical: false,
       seedIds: [],
       expansionCandidates: 0,
       strongSeedIds: [],
@@ -1696,17 +1323,17 @@ async function expandEntryNeighborhood(mergedCandidates, queryEmbedding, ports,
     return [];
   }
   const families = HISTORICAL_NEIGHBORHOOD_FAMILIES;
-  const includeRetired = true;
+  const includeHistorical = true;
   const seedIds = Array.from(mergedCandidates.keys());
   trace.expansionRequested = true;
   trace.familiesRequested = [...families];
-  trace.includeRetired = includeRetired;
+  trace.includeHistorical = includeHistorical;
   trace.seedIds = seedIds;
   const expanded = await ports.expandNeighborhood({
     seedIds,
     budget: DEFAULT_NEIGHBORHOOD_BUDGET,
     families,
-    includeRetired
+    includeHistorical
   });
   const ranked = expanded.filter((entry) => !mergedCandidates.has(entry.id)).map((entry) => ({
     entry,
@@ -1772,7 +1399,7 @@ function resolveRecencyScore(entry, params) {
   if (params.rankingProfile === "historical_state") {
     return HISTORICAL_STATE_FLAT_RECENCY;
   }
-  return recencyScore(entry.created_at, entry.expiry);
+  return recencyScore(entry.created_at, entry.expiry, params.now);
 }
 function resolveAsOfScore(entry, asOfDate) {
   const validFrom = parseTimestamp(entry.valid_from);
@@ -1808,7 +1435,7 @@ function applyHistoricalLineageBoosts(candidates, params, claimKeyTrace, slotPol
   const entries = candidates.map((candidate) => candidate.entry);
   const scoresById = new Map(candidates.map((candidate) => [candidate.entry.id, candidate.score]));
   return candidates.map((candidate) => {
-    const decision = resolveHistoricalLineageBonus(candidate.entry, entries, scoresById, candidate.score, params.aroundDate, slotPolicyConfig);
+    const decision = resolveHistoricalLineageBonus(candidate.entry, entries, scoresById, candidate.score, params.aroundDate, params.nowMs, slotPolicyConfig);
     if (decision.tentativeLineageSuppressed) {
       claimKeyTrace.tentativeLineageSuppressed += 1;
     }
@@ -1827,7 +1454,7 @@ function applyHistoricalLineageBoosts(candidates, params, claimKeyTrace, slotPol
     };
   });
 }
-function resolveHistoricalLineageBonus(entry, entries, scoresById, candidateScore, aroundDate, slotPolicyConfig) {
+function resolveHistoricalLineageBonus(entry, entries, scoresById, candidateScore, aroundDate, nowMs, slotPolicyConfig) {
   const directSuccessor = entries.find((peer) => peer.id !== entry.id && entry.superseded_by === peer.id);
   if (directSuccessor) {
     const successorScore = scoresById.get(directSuccessor.id) ?? 0;
@@ -1846,7 +1473,7 @@ function resolveHistoricalLineageBonus(entry, entries, scoresById, candidateScor
   let bestPeerScore = 0;
   let peerMatched = false;
   for (const peer of entries) {
-    if (peer.id === entry.id || !isPotentialCurrentPeer(peer) || createdAtMs(entry.created_at) >= createdAtMs(peer.created_at)) {
+    if (peer.id === entry.id || !isPotentialCurrentPeer(peer, nowMs) || createdAtMs(entry.created_at) >= createdAtMs(peer.created_at)) {
       continue;
     }
     const relation = resolveHistoricalPeerRelation(entry, peer, entries, slotPolicyConfig);
@@ -1869,7 +1496,7 @@ function resolveHistoricalLineageBonus(entry, entries, scoresById, candidateScor
       tentativeLineageSuppressed
     };
   }
-  const base = entry.retired ? HISTORICAL_RETIRED_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST;
+  const base = isStalePredecessor(entry, nowMs) ? HISTORICAL_STALE_PREDECESSOR_BOOST : HISTORICAL_OLDER_STATE_BOOST;
   return {
     bonus: shapeHistoricalLineageBonus(base, candidateScore, bestPeerScore),
     tentativeLineageSuppressed
@@ -1880,8 +1507,11 @@ function shapeHistoricalLineageBonus(base, candidateScore, successorScore) {
   const needed = gap > 0 ? gap + HISTORICAL_LINEAGE_GAP_MARGIN : 0;
   return Math.min(HISTORICAL_LINEAGE_MAX_BONUS, Math.max(base, needed));
 }
-function isPotentialCurrentPeer(entry) {
-  return !entry.retired && entry.superseded_by === void 0;
+function isPotentialCurrentPeer(entry, nowMs) {
+  return isCurrentlyValidMemory(entry, nowMs);
+}
+function isStalePredecessor(entry, nowMs) {
+  return isStaleMemory(entry, nowMs);
 }
 function resolveHistoricalPeerRelation(left, right, entries, slotPolicyConfig) {
   if (left.claim_key && right.claim_key && left.claim_key === right.claim_key) {
@@ -2034,18 +1664,18 @@ function resolveMmrMinPoolSize(policy) {
   }
   return Math.floor(raw);
 }
-function applyClaimKeyResultShaping(candidates, claimKeyTrace, slotPolicyConfig) {
+function applyClaimKeyResultShaping(candidates, claimKeyTrace, nowMs, 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"
+      (entry) => isPotentialCurrentPeer(entry, nowMs) && 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);
+  const trustedSlotRankById = rankTrustedSlotSiblings(candidates, nowMs, slotPolicyConfig);
   return candidates.map((candidate) => {
-    const trustPenalty = shouldPenalizeTentativeCurrentSibling(candidate.entry, trustedActiveClaimKeys) ? CLAIM_KEY_TENTATIVE_CURRENT_PENALTY : 0;
+    const trustPenalty = shouldPenalizeTentativeCurrentSibling(candidate.entry, trustedActiveClaimKeys, nowMs) ? CLAIM_KEY_TENTATIVE_CURRENT_PENALTY : 0;
     const redundancyPenalty = resolveTrustedSlotRedundancyPenalty(candidate.entry.id, trustedSlotRankById);
     if (trustPenalty <= 0 && redundancyPenalty <= 0) {
       return candidate;
@@ -2067,12 +1697,12 @@ function applyClaimKeyResultShaping(candidates, claimKeyTrace, slotPolicyConfig)
     };
   });
 }
-function rankTrustedSlotSiblings(candidates, slotPolicyConfig) {
+function rankTrustedSlotSiblings(candidates, nowMs, 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") {
+    if (!claimKey || candidate.entry.claim_key_status !== "trusted" || !isPotentialCurrentPeer(candidate.entry, nowMs) || resolveClaimSlotPolicy(claimKey, slotPolicyConfig).policy !== "exclusive") {
       continue;
     }
     const siblings = trustedByClaimKey.get(claimKey) ?? [];
@@ -2092,8 +1722,8 @@ function rankTrustedSlotSiblings(candidates, slotPolicyConfig) {
 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 shouldPenalizeTentativeCurrentSibling(entry, trustedActiveClaimKeys, nowMs) {
+  return isPotentialCurrentPeer(entry, nowMs) && 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;
@@ -2199,7 +1829,7 @@ function mergeCandidates(vectorCandidates, ftsCandidates) {
     ftsRanks
   };
 }
-function buildEntryFilters(types, tags, since, until) {
+function buildDurableFilters(types, tags, since, until, options) {
   const filters = {};
   if (types && types.length > 0) {
     filters.types = types;
@@ -2213,6 +1843,16 @@ function buildEntryFilters(types, tags, since, until) {
   if (until) {
     filters.until = until;
   }
+  if (options) {
+    const validAsOf = resolveRecallValidAsOf({
+      rankingProfile: options.rankingProfile,
+      asOfDate: options.asOfDate,
+      nowMs: options.nowMs
+    });
+    if (validAsOf) {
+      filters.validAsOf = validAsOf;
+    }
+  }
   return Object.keys(filters).length > 0 ? filters : void 0;
 }
 function applyBudget(results, budget) {
@@ -2362,8 +2002,8 @@ function hasCanonicalConsecutivePhrase(haystack, needle) {
 function estimateTokens(entry) {
   return (entry.subject.length + entry.content.length) / 4;
 }
-function parseAroundDate(value) {
-  return parseRelativeDate(value) ?? inferAroundDate(value);
+function parseAroundDate(value, now) {
+  return parseRelativeDate(value, now) ?? inferAroundDate(value, now);
 }
 function normalizeLimit(value) {
   if (typeof value !== "number" || !Number.isFinite(value)) {
@@ -2399,15 +2039,6 @@ export {
   importanceScore,
   scoreCandidate,
   cosineSimilarity,
-  normalizeClaimKeySegment,
-  normalizeClaimKey,
-  compactClaimKey,
-  validateExtractedClaimKey,
-  inspectClaimKey,
-  isTrustedClaimKeyForCleanup,
-  describeClaimKeyNormalizationFailure,
-  describeExtractedClaimKeyRejection,
-  describeClaimKeySuspicion,
   tokenize,
   buildLexicalPlan,
   computeLexicalScore,
@@ -2432,5 +2063,8 @@ export {
   sharesEntryLineage,
   sharesEpisodeLineage,
   sharesProcedureLineage,
-  recall
+  recall,
+  describeDurableLineageState,
+  formatDurableClaimLifecycle,
+  summarizeClaimFamilyTransition
 };