@remnic/core 1.1.30 → 9.3.515

package/dist/{chunk-OIGNEXKZ.js.map → chunk-K5O2QY6T.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/temporal-supersession.ts"],"sourcesContent":["/**\n * Temporal Supersession (issue #375)\n *\n * When a new fact lands with `structuredAttributes` keyed on a known\n * `entityRef`, any prior fact whose supersession key collides with the new\n * fact's key is marked `status: \"superseded\"` and linked via\n * `supersededBy` / `supersededAt`.  Recall filters those superseded memories\n * by default so agents see only the \"current\" value per entity attribute.\n *\n * The algorithm is intentionally O(N) over the memory corpus per write, but\n * skips cheaply when the new fact has no structuredAttributes.  It reuses the\n * cached `readAllMemories()` path so cost is amortized with the rest of the\n * write pipeline.\n */\nimport type { MemoryFile, MemoryFrontmatter } from \"./types.js\";\nimport type { StorageManager } from \"./storage.js\";\nimport { log } from \"./logger.js\";\nimport { effectiveValidAt } from \"./temporal-validity.js\";\n\n/**\n * Shared normalization for supersession key components.\n *\n * Trims surrounding whitespace, lowercases, then collapses any run of\n * whitespace OR hyphens to a single hyphen, and strips any leading/trailing\n * hyphens that result.  Both `computeSupersessionKey` and\n * `lookupAttributeByNormalizedKey` must use this so that keys produced at\n * write time and keys used at lookup time are identical regardless of how\n * the LLM encoded whitespace, hyphens, or casing (Finding B fix).\n *\n * Symmetry guarantee: `\"foo bar\"`, `\"foo-bar\"`, `\"foo - bar\"`, and\n * `\"foo  bar\"` all canonicalize to `\"foo-bar\"`.\n *\n * Exported so external tests can verify the canonical form.\n */\nexport function normalizeSupersessionKey(raw: string): string {\n  return raw\n    .trim()\n    .toLowerCase()\n    .replace(/[\\s\\-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n}\n\n/**\n * Stable supersession key for an (entityRef, attributeName) pair.\n *\n * The algorithm is:\n *  - normalize the entityRef (trim, lower-case, collapse whitespace)\n *  - normalize the attributeName the same way\n *  - join with `::`\n *\n * Exported so tests and tools can recompute it without depending on storage.\n */\nexport function computeSupersessionKey(\n  entityRef: string | undefined,\n  attributeName: string,\n): string | null {\n  if (!entityRef || typeof entityRef !== \"string\") return null;\n  if (!attributeName || typeof attributeName !== \"string\") return null;\n  const entity = normalizeSupersessionKey(entityRef);\n  const attr = normalizeSupersessionKey(attributeName);\n  if (entity.length === 0 || attr.length === 0) return null;\n  return `${entity}::${attr}`;\n}\n\n/**\n * Compute the full set of supersession keys for a fact with structured\n * attributes.  Returns an empty array if no keys can be derived.\n */\nexport function supersessionKeysForFact(spec: {\n  entityRef?: string;\n  structuredAttributes?: Record<string, string>;\n}): string[] {\n  if (!spec.entityRef) return [];\n  if (!spec.structuredAttributes) return [];\n  const keys: string[] = [];\n  for (const attrName of Object.keys(spec.structuredAttributes)) {\n    const key = computeSupersessionKey(spec.entityRef, attrName);\n    if (key) keys.push(key);\n  }\n  return keys;\n}\n\n/**\n * Look up a structured-attribute value by a raw key, normalizing both sides\n * with `normalizeSupersessionKey` before comparing.  This ensures that keys\n * written by the LLM with mixed case, surrounding whitespace, or internal\n * whitespace (e.g. `\"City\"`, `\" city \"`, `\"job   title\"`, `\"job-title\"`)\n * are all matched against normalized keys produced by `computeSupersessionKey`\n * (Finding B fix — uses the same helper so both sides are identical).\n *\n * The storage format is NOT changed — we only normalize at lookup time.\n */\nexport function lookupAttributeByNormalizedKey(\n  attributes: Record<string, unknown>,\n  rawKey: string,\n): unknown {\n  const normalizedTarget = normalizeSupersessionKey(rawKey);\n  for (const [k, v] of Object.entries(attributes)) {\n    if (normalizeSupersessionKey(k) === normalizedTarget) return v;\n  }\n  return undefined;\n}\n\n/**\n * Decide whether an existing memory should be superseded by a newly-written\n * memory that carries the supplied supersession key set.\n *\n * Only memories that:\n *  - are currently `active`\n *  - share an `entityRef` with the new fact\n *  - share at least one supersession key with the new fact\n *  - are older than the new fact\n *  - have a conflicting value (different string) for the overlapping key\n * are eligible.  This keeps supersession local to the attribute that actually\n * changed — if fact A sets `{city: Austin, tool: vim}` and fact B sets\n * `{city: NYC}`, only the city attribute is superseded, not the tool.\n */\nexport function shouldSupersedeExisting(args: {\n  candidate: MemoryFrontmatter;\n  newEntityRef: string;\n  newAttributes: Record<string, string>;\n  newCreatedAt: string;\n  newMemoryId: string;\n}): { matchedKeys: string[] } | null {\n  const { candidate, newEntityRef, newAttributes, newCreatedAt, newMemoryId } = args;\n\n  if (candidate.id === newMemoryId) return null;\n  if (candidate.status && candidate.status !== \"active\") return null;\n  if (!candidate.entityRef) return null;\n  if (!candidate.structuredAttributes) return null;\n\n  // Reuse the shared `normalizeSupersessionKey` helper so this comparison\n  // cannot drift from the canonical form used to build supersession keys\n  // elsewhere in this file.\n  const candidateEntityNorm = normalizeSupersessionKey(candidate.entityRef);\n  const newEntityNorm = normalizeSupersessionKey(newEntityRef);\n  if (candidateEntityNorm !== newEntityNorm) return null;\n\n  // Must be older than the new fact's effective validity start — equal\n  // timestamps are ignored to avoid races within the same millisecond. When\n  // replay/import supplies source time, valid_at must drive ordering instead\n  // of wall-clock persistence time.\n  const candidateCreated = Date.parse(effectiveValidAt(candidate));\n  const newCreated = Date.parse(newCreatedAt);\n  if (!Number.isFinite(candidateCreated) || !Number.isFinite(newCreated)) return null;\n  if (candidateCreated >= newCreated) return null;\n\n  const matchedKeys: string[] = [];\n  for (const [attrName, newValue] of Object.entries(newAttributes)) {\n    // Use normalized key lookup so mixed-case or whitespace-padded keys\n    // stored by the LLM are matched correctly (Finding 2 fix).\n    const candidateValue = lookupAttributeByNormalizedKey(\n      candidate.structuredAttributes,\n      attrName,\n    );\n    if (candidateValue === undefined) continue;\n    // Only supersede on conflicting values — identical values are a no-op.\n    if (normalizeValue(String(candidateValue)) === normalizeValue(newValue)) continue;\n    const key = computeSupersessionKey(newEntityRef, attrName);\n    if (key) matchedKeys.push(key);\n  }\n\n  return matchedKeys.length > 0 ? { matchedKeys } : null;\n}\n\nfunction normalizeValue(v: string): string {\n  return v.trim().toLowerCase();\n}\n\nasync function expireChildChunksForSupersededParent(args: {\n  storage: StorageManager;\n  allCandidates: MemoryFile[];\n  parentId: string;\n  newMemoryId: string;\n  supersededAt: string;\n  invalidAt?: string;\n}): Promise<void> {\n  const processedChunkIds = new Set<string>();\n  const chunks = args.allCandidates.filter(\n    (candidate) => candidate.frontmatter.parentId === args.parentId,\n  );\n\n  for (const chunk of chunks) {\n    const chunkKey = chunk.frontmatter.id ?? chunk.path;\n    if (processedChunkIds.has(chunkKey)) continue;\n\n    try {\n      const freshChunk = await args.storage.readMemoryByPath(chunk.path);\n      if (!freshChunk) continue;\n      processedChunkIds.add(chunkKey);\n      const freshStatus = freshChunk.frontmatter.status ?? \"active\";\n      if (freshStatus !== \"active\" || freshChunk.frontmatter.supersededBy) continue;\n\n      await args.storage.writeMemoryFrontmatter(\n        freshChunk,\n        {\n          status: \"superseded\",\n          supersededBy: args.newMemoryId,\n          supersededAt: args.supersededAt,\n          updated: args.supersededAt,\n          ...(args.invalidAt && !freshChunk.frontmatter.invalid_at\n            ? { invalid_at: args.invalidAt }\n            : {}),\n        },\n        {\n          actor: \"temporal-supersession\",\n          reasonCode: \"structured-attribute-update-child-chunk\",\n          relatedMemoryIds: [args.newMemoryId, args.parentId],\n        },\n      );\n    } catch (err) {\n      log.warn(\n        `temporal-supersession: failed to expire child chunk ${chunk.frontmatter.id} for parent ${args.parentId}: ${err}`,\n      );\n    }\n  }\n}\n\nexport interface TemporalSupersessionResult {\n  supersededIds: string[];\n  matchedKeys: string[];\n}\n\n/**\n * Scan existing memories and mark any that are superseded by the\n * just-written memory.  Fails open on I/O errors — the new memory is already\n * on disk, and supersession is a best-effort hygiene step.\n */\nexport async function applyTemporalSupersession(args: {\n  storage: StorageManager;\n  newMemoryId: string;\n  entityRef?: string;\n  structuredAttributes?: Record<string, string>;\n  createdAt: string;\n  enabled: boolean;\n  /**\n   * When true, skip the persisted `frontmatter.created` lookup and use\n   * `args.createdAt` directly as the ordering anchor.  Set this on the\n   * hash-dedup short-circuit path where `newMemoryId` points to an existing\n   * OLD fact (no new file is written) and its persisted timestamp would be\n   * stale relative to the incoming promotion event (PR #402 Finding Uyui).\n   */\n  useCallerTimestamp?: boolean;\n}): Promise<TemporalSupersessionResult> {\n  const empty: TemporalSupersessionResult = { supersededIds: [], matchedKeys: [] };\n  if (!args.enabled) return empty;\n  if (!args.entityRef) return empty;\n  if (!args.structuredAttributes) return empty;\n  if (Object.keys(args.structuredAttributes).length === 0) return empty;\n\n  const newKeys = supersessionKeysForFact({\n    entityRef: args.entityRef,\n    structuredAttributes: args.structuredAttributes,\n  });\n  if (newKeys.length === 0) return empty;\n\n  let hotMemories: MemoryFile[];\n  try {\n    hotMemories = await args.storage.readAllMemories();\n  } catch (err) {\n    log.warn(`temporal-supersession: readAllMemories failed: ${err}`);\n    return empty;\n  }\n\n  // Finding 1 fix: use the on-disk effective validity start of the\n  // newly-written memory rather than a wall-clock timestamp sampled after\n  // `writeMemory` returns.  In concurrent writers the two can differ by enough\n  // to cause wrong-direction supersession.  If source replay/import provided\n  // valid_at, it must drive ordering; otherwise created remains the legacy\n  // fallback.  If the memory is not yet visible in the cache (edge case during\n  // fast concurrent writes) fall back to args.createdAt.\n  //\n  // PR #402 round-12 (Finding Uyui): on the hash-dedup early-return path the\n  // caller supplies the OLD matching fact's id as `newMemoryId` (no new file is\n  // written).  That makes `newMemoryFile.frontmatter.created` an arbitrarily\n  // old timestamp.  When `args.useCallerTimestamp` is set the caller explicitly\n  // opts out of the persisted-timestamp lookup so `args.createdAt` (the\n  // incoming event time: source valid_at when present, otherwise wall-clock) is\n  // used directly, keeping ordering correct regardless of how old the matching\n  // fact is.\n  const newMemoryFile = hotMemories.find((m) => m.frontmatter.id === args.newMemoryId);\n  const persistedCreatedAt = args.useCallerTimestamp\n    ? args.createdAt\n    : (newMemoryFile ? effectiveValidAt(newMemoryFile.frontmatter) : args.createdAt);\n\n  const supersededIds: string[] = [];\n  const matchedKeys = new Set<string>();\n\n  // Process hot then cold.  Hot-then-cold ordering is safer because hot\n  // writes are more frequent and the CAS re-read guards against double-writes.\n  // A Set<string> of already-processed ids ensures that a memory visible in\n  // both tiers (same logical memory with different filesystem paths during a\n  // migration race) is processed at most once.  Keying on `frontmatter.id`\n  // is correct because the same logical memory has the same id regardless of\n  // which tier's directory it currently lives in (PR #402 Finding 1 fix).\n  // Fall back to path-based keying when id is absent (defensive).\n  const processedIds = new Set<string>();\n\n  // Finding UOGi fix (round-6): readAllColdMemories() performs a full uncached\n  // recursive directory scan of cold/.  After Finding UTsP broadened the scan\n  // to cover the entire cold root (not just facts/+corrections/), the per-call\n  // cost grows with the cold tree size.\n  //\n  // The fix is a TTL-based in-memory cache inside StorageManager\n  // (readAllColdMemories caches its result for COLD_SCAN_CACHE_TTL_MS) that is\n  // shared across consecutive supersession calls within the same write burst.\n  // The cache is invalidated automatically on any hot→cold demotion (which\n  // calls invalidateAllMemoriesCache, which also clears the cold cache) and\n  // expires after the TTL as a safety net.\n  //\n  // This means back-to-back structured-attribute writes in the same burst\n  // (e.g. batch extraction) pay the cold I/O cost at most once, not N times.\n  // Correctness is preserved because the cache TTL ensures eventual consistency\n  // and the invalidation hook covers the hot→cold path.\n\n  let coldMemories: MemoryFile[];\n  try {\n    coldMemories = await args.storage.readAllColdMemories();\n  } catch (err) {\n    log.warn(`temporal-supersession: readAllColdMemories failed: ${err}`);\n    coldMemories = [];\n  }\n\n  // Combine hot and cold memories into a single scan.  New memory itself is\n  // excluded inline.  We do NOT skip cold scan when hot produced zero\n  // supersessions — the P1 finding is precisely that stale cold facts leak\n  // when hot has no hits.\n  const allCandidates: MemoryFile[] = [...hotMemories, ...coldMemories];\n\n  for (const memory of allCandidates) {\n    if (memory.frontmatter.id === args.newMemoryId) continue;\n    const dedupeKey = memory.frontmatter.id ?? memory.path;\n    if (processedIds.has(dedupeKey)) continue;\n    // NOTE: do NOT call processedIds.add(dedupeKey) here.  We defer marking\n    // the id as processed until AFTER the CAS re-read succeeds.  If we mark\n    // it here and the re-read fails (e.g. the hot entry has already been\n    // migrated to cold storage), the same logical id that appears later in\n    // the cold tier scan would be silently skipped, leaving a stale cold\n    // fact unsuperseded.  Deferring ensures that a failed primary-tier read\n    // grants the alternate tier a chance to process the same id (PR #402\n    // round-6 Finding 1 fix).\n\n    const decision = shouldSupersedeExisting({\n      candidate: memory.frontmatter,\n      newEntityRef: args.entityRef,\n      newAttributes: args.structuredAttributes,\n      newCreatedAt: persistedCreatedAt,\n      newMemoryId: args.newMemoryId,\n    });\n    if (!decision) {\n      // No supersession decision — safe to mark as processed now so the\n      // alternate tier doesn't re-evaluate an identical non-matching entry.\n      processedIds.add(dedupeKey);\n      continue;\n    }\n\n    try {\n      // CAS-style re-read immediately before the write.  `readAllMemories()`\n      // is a snapshot — with concurrent writers, another run may have already\n      // superseded this candidate since we loaded it.  If we blindly trust the\n      // snapshot we can clobber a newer `supersededBy` link with a stale one.\n      //\n      // File storage offers no true locking, so the best we can do is:\n      //   1. re-read the exact file we're about to mutate\n      //   2. verify status is still \"active\" and no `supersededBy` is set\n      //   3. only then issue the write\n      // If the re-read shows a newer concurrent writer beat us to it, skip.\n      // This CAS pattern applies equally to hot and cold tier candidates.\n      // Mark as processed AFTER confirming the candidate is readable so that\n      // a migration-race read failure on the hot entry does not silently\n      // prevent the cold entry from being evaluated (Finding 1, round 6).\n      const fresh = await args.storage.readMemoryByPath(memory.path);\n      if (!fresh) {\n        log.debug(\n          `[engram] temporal supersession skipped candidate ${memory.frontmatter.id}: no longer readable at ${memory.path} — leaving id available for alternate tier`,\n        );\n        // Do NOT add to processedIds — allow the cold-tier copy to be\n        // evaluated in the next iteration of the same scan.\n        continue;\n      }\n      // Candidate is readable — mark the id as processed now to prevent the\n      // alternate tier from double-writing.\n      processedIds.add(dedupeKey);\n      const freshStatus = fresh.frontmatter.status ?? \"active\";\n      if (freshStatus !== \"active\" || fresh.frontmatter.supersededBy) {\n        log.debug(\n          `[engram] temporal supersession skipped candidate ${memory.frontmatter.id}: already superseded by concurrent writer`,\n        );\n        continue;\n      }\n\n      // Finding 2 fix: the `supersededAt` / `updated` timestamps written to the\n      // old fact must never run backwards relative to its own persisted\n      // `created` timestamp.  If the caller-supplied `args.createdAt` (which\n      // represents \"when the new replacing fact was authored\") is earlier than\n      // either the new fact's persisted `created` (T_new) or the old fact's\n      // persisted `created` (T_old), we'd be writing a nonsensical\n      // `supersededAt` that precedes the old memory's own creation.  Clamp to\n      // the monotonic maximum so time only moves forward.\n      // This monotonic clamp is applied for both hot and cold tier writes.\n      const oldCreatedMs = new Date(fresh.frontmatter.created).getTime();\n      const newCreatedMs = new Date(persistedCreatedAt).getTime();\n      const argCreatedMs = new Date(args.createdAt).getTime();\n      const maxMs = Math.max(\n        Number.isFinite(oldCreatedMs) ? oldCreatedMs : 0,\n        Number.isFinite(newCreatedMs) ? newCreatedMs : 0,\n        Number.isFinite(argCreatedMs) ? argCreatedMs : 0,\n      );\n      const supersededAt = new Date(maxMs).toISOString();\n\n      // Issue #680 — explicit fact lifecycle.  When the new fact\n      // supersedes this one, set the predecessor's `invalid_at` to the\n      // successor's effective valid_at.  Skip when the predecessor\n      // already carries an `invalid_at` so manual / earlier values\n      // are preserved (idempotent).\n      //\n      // Codex P1 on PR #713: in the hash-dedup early-return path\n      // (`useCallerTimestamp: true`), `newMemoryFile` is actually the\n      // OLD matching fact — no new file was written — so its\n      // `valid_at` is the predecessor's own old timestamp, not the\n      // successor's effective time. Use `persistedCreatedAt`\n      // directly in that path so the predecessor's invalid_at lines\n      // up with the caller's wall-clock, not the matching fact's old\n      // valid_at. The non-dedup path keeps the previous behavior\n      // (prefer the new file's explicit valid_at, fall back to its\n      // persisted created).\n      let invalidAtPatch: string | undefined;\n      if (!fresh.frontmatter.invalid_at) {\n        if (args.useCallerTimestamp) {\n          invalidAtPatch = persistedCreatedAt;\n        } else {\n          const newValidAt = newMemoryFile?.frontmatter.valid_at?.trim();\n          invalidAtPatch =\n            newValidAt && newValidAt.length > 0 ? newValidAt : persistedCreatedAt;\n        }\n      }\n      const wrote = await args.storage.writeMemoryFrontmatter(\n        fresh,\n        {\n          status: \"superseded\",\n          supersededBy: args.newMemoryId,\n          supersededAt,\n          updated: supersededAt,\n          ...(invalidAtPatch ? { invalid_at: invalidAtPatch } : {}),\n        },\n        {\n          actor: \"temporal-supersession\",\n          reasonCode: \"structured-attribute-update\",\n          relatedMemoryIds: [args.newMemoryId],\n        },\n      );\n      if (wrote) {\n        supersededIds.push(memory.frontmatter.id);\n        for (const key of decision.matchedKeys) matchedKeys.add(key);\n        await expireChildChunksForSupersededParent({\n          storage: args.storage,\n          allCandidates,\n          parentId: fresh.frontmatter.id,\n          newMemoryId: args.newMemoryId,\n          supersededAt,\n          invalidAt: invalidAtPatch ?? fresh.frontmatter.invalid_at,\n        });\n      }\n    } catch (err) {\n      log.warn(\n        `temporal-supersession: failed to mark ${memory.frontmatter.id} superseded: ${err}`,\n      );\n    }\n  }\n\n  if (supersededIds.length > 0) {\n    log.debug(\n      `temporal-supersession: marked ${supersededIds.length} memories superseded by ${args.newMemoryId} (keys=${Array.from(matchedKeys).join(\",\")})`,\n    );\n  }\n\n  return { supersededIds, matchedKeys: Array.from(matchedKeys) };\n}\n\n/**\n * Recall-side filter: returns true when the candidate should be excluded\n * from recall because it has been temporally superseded.  When\n * `includeInRecall` is true, this always returns false (the fact is kept),\n * matching the audit/history opt-in described in the config.\n */\nexport function shouldFilterSupersededFromRecall(\n  frontmatter: MemoryFrontmatter,\n  options: { enabled: boolean; includeInRecall: boolean },\n): boolean {\n  if (!options.enabled) return false;\n  if (options.includeInRecall) return false;\n  return frontmatter.status === \"superseded\";\n}\n"],"mappings":";;;;;;;;AAkCO,SAAS,yBAAyB,KAAqB;AAC5D,SAAO,IACJ,KAAK,EACL,YAAY,EACZ,QAAQ,YAAY,GAAG,EACvB,QAAQ,YAAY,EAAE;AAC3B;AAYO,SAAS,uBACd,WACA,eACe;AACf,MAAI,CAAC,aAAa,OAAO,cAAc,SAAU,QAAO;AACxD,MAAI,CAAC,iBAAiB,OAAO,kBAAkB,SAAU,QAAO;AAChE,QAAM,SAAS,yBAAyB,SAAS;AACjD,QAAM,OAAO,yBAAyB,aAAa;AACnD,MAAI,OAAO,WAAW,KAAK,KAAK,WAAW,EAAG,QAAO;AACrD,SAAO,GAAG,MAAM,KAAK,IAAI;AAC3B;AAMO,SAAS,wBAAwB,MAG3B;AACX,MAAI,CAAC,KAAK,UAAW,QAAO,CAAC;AAC7B,MAAI,CAAC,KAAK,qBAAsB,QAAO,CAAC;AACxC,QAAM,OAAiB,CAAC;AACxB,aAAW,YAAY,OAAO,KAAK,KAAK,oBAAoB,GAAG;AAC7D,UAAM,MAAM,uBAAuB,KAAK,WAAW,QAAQ;AAC3D,QAAI,IAAK,MAAK,KAAK,GAAG;AAAA,EACxB;AACA,SAAO;AACT;AAYO,SAAS,+BACd,YACA,QACS;AACT,QAAM,mBAAmB,yBAAyB,MAAM;AACxD,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,UAAU,GAAG;AAC/C,QAAI,yBAAyB,CAAC,MAAM,iBAAkB,QAAO;AAAA,EAC/D;AACA,SAAO;AACT;AAgBO,SAAS,wBAAwB,MAMH;AACnC,QAAM,EAAE,WAAW,cAAc,eAAe,cAAc,YAAY,IAAI;AAE9E,MAAI,UAAU,OAAO,YAAa,QAAO;AACzC,MAAI,UAAU,UAAU,UAAU,WAAW,SAAU,QAAO;AAC9D,MAAI,CAAC,UAAU,UAAW,QAAO;AACjC,MAAI,CAAC,UAAU,qBAAsB,QAAO;AAK5C,QAAM,sBAAsB,yBAAyB,UAAU,SAAS;AACxE,QAAM,gBAAgB,yBAAyB,YAAY;AAC3D,MAAI,wBAAwB,cAAe,QAAO;AAMlD,QAAM,mBAAmB,KAAK,MAAM,iBAAiB,SAAS,CAAC;AAC/D,QAAM,aAAa,KAAK,MAAM,YAAY;AAC1C,MAAI,CAAC,OAAO,SAAS,gBAAgB,KAAK,CAAC,OAAO,SAAS,UAAU,EAAG,QAAO;AAC/E,MAAI,oBAAoB,WAAY,QAAO;AAE3C,QAAM,cAAwB,CAAC;AAC/B,aAAW,CAAC,UAAU,QAAQ,KAAK,OAAO,QAAQ,aAAa,GAAG;AAGhE,UAAM,iBAAiB;AAAA,MACrB,UAAU;AAAA,MACV;AAAA,IACF;AACA,QAAI,mBAAmB,OAAW;AAElC,QAAI,eAAe,OAAO,cAAc,CAAC,MAAM,eAAe,QAAQ,EAAG;AACzE,UAAM,MAAM,uBAAuB,cAAc,QAAQ;AACzD,QAAI,IAAK,aAAY,KAAK,GAAG;AAAA,EAC/B;AAEA,SAAO,YAAY,SAAS,IAAI,EAAE,YAAY,IAAI;AACpD;AAEA,SAAS,eAAe,GAAmB;AACzC,SAAO,EAAE,KAAK,EAAE,YAAY;AAC9B;AAEA,eAAe,qCAAqC,MAOlC;AAChB,QAAM,oBAAoB,oBAAI,IAAY;AAC1C,QAAM,SAAS,KAAK,cAAc;AAAA,IAChC,CAAC,cAAc,UAAU,YAAY,aAAa,KAAK;AAAA,EACzD;AAEA,aAAW,SAAS,QAAQ;AAC1B,UAAM,WAAW,MAAM,YAAY,MAAM,MAAM;AAC/C,QAAI,kBAAkB,IAAI,QAAQ,EAAG;AAErC,QAAI;AACF,YAAM,aAAa,MAAM,KAAK,QAAQ,iBAAiB,MAAM,IAAI;AACjE,UAAI,CAAC,WAAY;AACjB,wBAAkB,IAAI,QAAQ;AAC9B,YAAM,cAAc,WAAW,YAAY,UAAU;AACrD,UAAI,gBAAgB,YAAY,WAAW,YAAY,aAAc;AAErE,YAAM,KAAK,QAAQ;AAAA,QACjB;AAAA,QACA;AAAA,UACE,QAAQ;AAAA,UACR,cAAc,KAAK;AAAA,UACnB,cAAc,KAAK;AAAA,UACnB,SAAS,KAAK;AAAA,UACd,GAAI,KAAK,aAAa,CAAC,WAAW,YAAY,aAC1C,EAAE,YAAY,KAAK,UAAU,IAC7B,CAAC;AAAA,QACP;AAAA,QACA;AAAA,UACE,OAAO;AAAA,UACP,YAAY;AAAA,UACZ,kBAAkB,CAAC,KAAK,aAAa,KAAK,QAAQ;AAAA,QACpD;AAAA,MACF;AAAA,IACF,SAAS,KAAK;AACZ,UAAI;AAAA,QACF,uDAAuD,MAAM,YAAY,EAAE,eAAe,KAAK,QAAQ,KAAK,GAAG;AAAA,MACjH;AAAA,IACF;AAAA,EACF;AACF;AAYA,eAAsB,0BAA0B,MAeR;AACtC,QAAM,QAAoC,EAAE,eAAe,CAAC,GAAG,aAAa,CAAC,EAAE;AAC/E,MAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,MAAI,CAAC,KAAK,UAAW,QAAO;AAC5B,MAAI,CAAC,KAAK,qBAAsB,QAAO;AACvC,MAAI,OAAO,KAAK,KAAK,oBAAoB,EAAE,WAAW,EAAG,QAAO;AAEhE,QAAM,UAAU,wBAAwB;AAAA,IACtC,WAAW,KAAK;AAAA,IAChB,sBAAsB,KAAK;AAAA,EAC7B,CAAC;AACD,MAAI,QAAQ,WAAW,EAAG,QAAO;AAEjC,MAAI;AACJ,MAAI;AACF,kBAAc,MAAM,KAAK,QAAQ,gBAAgB;AAAA,EACnD,SAAS,KAAK;AACZ,QAAI,KAAK,kDAAkD,GAAG,EAAE;AAChE,WAAO;AAAA,EACT;AAkBA,QAAM,gBAAgB,YAAY,KAAK,CAAC,MAAM,EAAE,YAAY,OAAO,KAAK,WAAW;AACnF,QAAM,qBAAqB,KAAK,qBAC5B,KAAK,YACJ,gBAAgB,iBAAiB,cAAc,WAAW,IAAI,KAAK;AAExE,QAAM,gBAA0B,CAAC;AACjC,QAAM,cAAc,oBAAI,IAAY;AAUpC,QAAM,eAAe,oBAAI,IAAY;AAmBrC,MAAI;AACJ,MAAI;AACF,mBAAe,MAAM,KAAK,QAAQ,oBAAoB;AAAA,EACxD,SAAS,KAAK;AACZ,QAAI,KAAK,sDAAsD,GAAG,EAAE;AACpE,mBAAe,CAAC;AAAA,EAClB;AAMA,QAAM,gBAA8B,CAAC,GAAG,aAAa,GAAG,YAAY;AAEpE,aAAW,UAAU,eAAe;AAClC,QAAI,OAAO,YAAY,OAAO,KAAK,YAAa;AAChD,UAAM,YAAY,OAAO,YAAY,MAAM,OAAO;AAClD,QAAI,aAAa,IAAI,SAAS,EAAG;AAUjC,UAAM,WAAW,wBAAwB;AAAA,MACvC,WAAW,OAAO;AAAA,MAClB,cAAc,KAAK;AAAA,MACnB,eAAe,KAAK;AAAA,MACpB,cAAc;AAAA,MACd,aAAa,KAAK;AAAA,IACpB,CAAC;AACD,QAAI,CAAC,UAAU;AAGb,mBAAa,IAAI,SAAS;AAC1B;AAAA,IACF;AAEA,QAAI;AAeF,YAAM,QAAQ,MAAM,KAAK,QAAQ,iBAAiB,OAAO,IAAI;AAC7D,UAAI,CAAC,OAAO;AACV,YAAI;AAAA,UACF,oDAAoD,OAAO,YAAY,EAAE,2BAA2B,OAAO,IAAI;AAAA,QACjH;AAGA;AAAA,MACF;AAGA,mBAAa,IAAI,SAAS;AAC1B,YAAM,cAAc,MAAM,YAAY,UAAU;AAChD,UAAI,gBAAgB,YAAY,MAAM,YAAY,cAAc;AAC9D,YAAI;AAAA,UACF,oDAAoD,OAAO,YAAY,EAAE;AAAA,QAC3E;AACA;AAAA,MACF;AAWA,YAAM,eAAe,IAAI,KAAK,MAAM,YAAY,OAAO,EAAE,QAAQ;AACjE,YAAM,eAAe,IAAI,KAAK,kBAAkB,EAAE,QAAQ;AAC1D,YAAM,eAAe,IAAI,KAAK,KAAK,SAAS,EAAE,QAAQ;AACtD,YAAM,QAAQ,KAAK;AAAA,QACjB,OAAO,SAAS,YAAY,IAAI,eAAe;AAAA,QAC/C,OAAO,SAAS,YAAY,IAAI,eAAe;AAAA,QAC/C,OAAO,SAAS,YAAY,IAAI,eAAe;AAAA,MACjD;AACA,YAAM,eAAe,IAAI,KAAK,KAAK,EAAE,YAAY;AAkBjD,UAAI;AACJ,UAAI,CAAC,MAAM,YAAY,YAAY;AACjC,YAAI,KAAK,oBAAoB;AAC3B,2BAAiB;AAAA,QACnB,OAAO;AACL,gBAAM,aAAa,eAAe,YAAY,UAAU,KAAK;AAC7D,2BACE,cAAc,WAAW,SAAS,IAAI,aAAa;AAAA,QACvD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,KAAK,QAAQ;AAAA,QAC/B;AAAA,QACA;AAAA,UACE,QAAQ;AAAA,UACR,cAAc,KAAK;AAAA,UACnB;AAAA,UACA,SAAS;AAAA,UACT,GAAI,iBAAiB,EAAE,YAAY,eAAe,IAAI,CAAC;AAAA,QACzD;AAAA,QACA;AAAA,UACE,OAAO;AAAA,UACP,YAAY;AAAA,UACZ,kBAAkB,CAAC,KAAK,WAAW;AAAA,QACrC;AAAA,MACF;AACA,UAAI,OAAO;AACT,sBAAc,KAAK,OAAO,YAAY,EAAE;AACxC,mBAAW,OAAO,SAAS,YAAa,aAAY,IAAI,GAAG;AAC3D,cAAM,qCAAqC;AAAA,UACzC,SAAS,KAAK;AAAA,UACd;AAAA,UACA,UAAU,MAAM,YAAY;AAAA,UAC5B,aAAa,KAAK;AAAA,UAClB;AAAA,UACA,WAAW,kBAAkB,MAAM,YAAY;AAAA,QACjD,CAAC;AAAA,MACH;AAAA,IACF,SAAS,KAAK;AACZ,UAAI;AAAA,QACF,yCAAyC,OAAO,YAAY,EAAE,gBAAgB,GAAG;AAAA,MACnF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,cAAc,SAAS,GAAG;AAC5B,QAAI;AAAA,MACF,iCAAiC,cAAc,MAAM,2BAA2B,KAAK,WAAW,UAAU,MAAM,KAAK,WAAW,EAAE,KAAK,GAAG,CAAC;AAAA,IAC7I;AAAA,EACF;AAEA,SAAO,EAAE,eAAe,aAAa,MAAM,KAAK,WAAW,EAAE;AAC/D;AAQO,SAAS,iCACd,aACA,SACS;AACT,MAAI,CAAC,QAAQ,QAAS,QAAO;AAC7B,MAAI,QAAQ,gBAAiB,QAAO;AACpC,SAAO,YAAY,WAAW;AAChC;","names":[]}
+{"version":3,"sources":["../src/temporal-supersession.ts"],"sourcesContent":["/**\n * Temporal Supersession (issue #375)\n *\n * When a new fact lands with `structuredAttributes` keyed on a known\n * `entityRef`, any prior fact whose supersession key collides with the new\n * fact's key is marked `status: \"superseded\"` and linked via\n * `supersededBy` / `supersededAt`.  Recall filters those superseded memories\n * by default so agents see only the \"current\" value per entity attribute.\n *\n * The algorithm is intentionally O(N) over the memory corpus per write, but\n * skips cheaply when the new fact has no structuredAttributes.  It reuses the\n * cached `readAllMemories()` path so cost is amortized with the rest of the\n * write pipeline.\n */\nimport type { MemoryFile, MemoryFrontmatter } from \"./types.js\";\nimport type { StorageManager } from \"./storage.js\";\nimport { log } from \"./logger.js\";\nimport { effectiveValidAt } from \"./temporal-validity.js\";\n\n/**\n * Shared normalization for supersession key components.\n *\n * Trims surrounding whitespace, lowercases, then collapses any run of\n * whitespace OR hyphens to a single hyphen, and strips any leading/trailing\n * hyphens that result.  Both `computeSupersessionKey` and\n * `lookupAttributeByNormalizedKey` must use this so that keys produced at\n * write time and keys used at lookup time are identical regardless of how\n * the LLM encoded whitespace, hyphens, or casing (Finding B fix).\n *\n * Symmetry guarantee: `\"foo bar\"`, `\"foo-bar\"`, `\"foo - bar\"`, and\n * `\"foo  bar\"` all canonicalize to `\"foo-bar\"`.\n *\n * Exported so external tests can verify the canonical form.\n */\nexport function normalizeSupersessionKey(raw: string): string {\n  return raw\n    .trim()\n    .toLowerCase()\n    .replace(/[\\s\\-]+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n}\n\n/**\n * Stable supersession key for an (entityRef, attributeName) pair.\n *\n * The algorithm is:\n *  - normalize the entityRef (trim, lower-case, collapse whitespace)\n *  - normalize the attributeName the same way\n *  - join with `::`\n *\n * Exported so tests and tools can recompute it without depending on storage.\n */\nexport function computeSupersessionKey(\n  entityRef: string | undefined,\n  attributeName: string,\n): string | null {\n  if (!entityRef || typeof entityRef !== \"string\") return null;\n  if (!attributeName || typeof attributeName !== \"string\") return null;\n  const entity = normalizeSupersessionKey(entityRef);\n  const attr = normalizeSupersessionKey(attributeName);\n  if (entity.length === 0 || attr.length === 0) return null;\n  return `${entity}::${attr}`;\n}\n\n/**\n * Compute the full set of supersession keys for a fact with structured\n * attributes.  Returns an empty array if no keys can be derived.\n */\nexport function supersessionKeysForFact(spec: {\n  entityRef?: string;\n  structuredAttributes?: Record<string, string>;\n}): string[] {\n  if (!spec.entityRef) return [];\n  if (!spec.structuredAttributes) return [];\n  const keys: string[] = [];\n  for (const attrName of Object.keys(spec.structuredAttributes)) {\n    const key = computeSupersessionKey(spec.entityRef, attrName);\n    if (key) keys.push(key);\n  }\n  return keys;\n}\n\n/**\n * Look up a structured-attribute value by a raw key, normalizing both sides\n * with `normalizeSupersessionKey` before comparing.  This ensures that keys\n * written by the LLM with mixed case, surrounding whitespace, or internal\n * whitespace (e.g. `\"City\"`, `\" city \"`, `\"job   title\"`, `\"job-title\"`)\n * are all matched against normalized keys produced by `computeSupersessionKey`\n * (Finding B fix — uses the same helper so both sides are identical).\n *\n * The storage format is NOT changed — we only normalize at lookup time.\n */\nexport function lookupAttributeByNormalizedKey(\n  attributes: Record<string, unknown>,\n  rawKey: string,\n): unknown {\n  const normalizedTarget = normalizeSupersessionKey(rawKey);\n  for (const [k, v] of Object.entries(attributes)) {\n    if (normalizeSupersessionKey(k) === normalizedTarget) return v;\n  }\n  return undefined;\n}\n\n/**\n * Decide whether an existing memory should be superseded by a newly-written\n * memory that carries the supplied supersession key set.\n *\n * Only memories that:\n *  - are currently `active`\n *  - share an `entityRef` with the new fact\n *  - share at least one supersession key with the new fact\n *  - are older than the new fact\n *  - have a conflicting value (different string) for the overlapping key\n * are eligible.  This keeps supersession local to the attribute that actually\n * changed — if fact A sets `{city: Austin, tool: vim}` and fact B sets\n * `{city: NYC}`, only the city attribute is superseded, not the tool.\n */\nexport function shouldSupersedeExisting(args: {\n  candidate: MemoryFrontmatter;\n  newEntityRef: string;\n  newAttributes: Record<string, string>;\n  newCreatedAt: string;\n  newMemoryId: string;\n}): { matchedKeys: string[] } | null {\n  const { candidate, newEntityRef, newAttributes, newCreatedAt, newMemoryId } = args;\n\n  if (candidate.id === newMemoryId) return null;\n  if (candidate.status && candidate.status !== \"active\") return null;\n  if (!candidate.entityRef) return null;\n  if (!candidate.structuredAttributes) return null;\n\n  // Reuse the shared `normalizeSupersessionKey` helper so this comparison\n  // cannot drift from the canonical form used to build supersession keys\n  // elsewhere in this file.\n  const candidateEntityNorm = normalizeSupersessionKey(candidate.entityRef);\n  const newEntityNorm = normalizeSupersessionKey(newEntityRef);\n  if (candidateEntityNorm !== newEntityNorm) return null;\n\n  // Must be older than the new fact's effective validity start — equal\n  // timestamps are ignored to avoid races within the same millisecond. When\n  // replay/import supplies source time, valid_at must drive ordering instead\n  // of wall-clock persistence time.\n  const candidateCreated = Date.parse(effectiveValidAt(candidate));\n  const newCreated = Date.parse(newCreatedAt);\n  if (!Number.isFinite(candidateCreated) || !Number.isFinite(newCreated)) return null;\n  if (candidateCreated >= newCreated) return null;\n\n  const matchedKeys: string[] = [];\n  for (const [attrName, newValue] of Object.entries(newAttributes)) {\n    // Use normalized key lookup so mixed-case or whitespace-padded keys\n    // stored by the LLM are matched correctly (Finding 2 fix).\n    const candidateValue = lookupAttributeByNormalizedKey(\n      candidate.structuredAttributes,\n      attrName,\n    );\n    if (candidateValue === undefined) continue;\n    // Only supersede on conflicting values — identical values are a no-op.\n    if (normalizeValue(String(candidateValue)) === normalizeValue(newValue)) continue;\n    const key = computeSupersessionKey(newEntityRef, attrName);\n    if (key) matchedKeys.push(key);\n  }\n\n  return matchedKeys.length > 0 ? { matchedKeys } : null;\n}\n\nfunction normalizeValue(v: string): string {\n  return v.trim().toLowerCase();\n}\n\nasync function expireChildChunksForSupersededParent(args: {\n  storage: StorageManager;\n  allCandidates: MemoryFile[];\n  parentId: string;\n  newMemoryId: string;\n  supersededAt: string;\n  invalidAt?: string;\n}): Promise<void> {\n  const processedChunkIds = new Set<string>();\n  const chunks = args.allCandidates.filter(\n    (candidate) => candidate.frontmatter.parentId === args.parentId,\n  );\n\n  for (const chunk of chunks) {\n    const chunkKey = chunk.frontmatter.id ?? chunk.path;\n    if (processedChunkIds.has(chunkKey)) continue;\n\n    try {\n      const freshChunk = await args.storage.readMemoryByPath(chunk.path);\n      if (!freshChunk) continue;\n      processedChunkIds.add(chunkKey);\n      const freshStatus = freshChunk.frontmatter.status ?? \"active\";\n      if (freshStatus !== \"active\" || freshChunk.frontmatter.supersededBy) continue;\n\n      await args.storage.writeMemoryFrontmatter(\n        freshChunk,\n        {\n          status: \"superseded\",\n          supersededBy: args.newMemoryId,\n          supersededAt: args.supersededAt,\n          updated: args.supersededAt,\n          ...(args.invalidAt && !freshChunk.frontmatter.invalid_at\n            ? { invalid_at: args.invalidAt }\n            : {}),\n        },\n        {\n          actor: \"temporal-supersession\",\n          reasonCode: \"structured-attribute-update-child-chunk\",\n          relatedMemoryIds: [args.newMemoryId, args.parentId],\n        },\n      );\n    } catch (err) {\n      log.warn(\n        `temporal-supersession: failed to expire child chunk ${chunk.frontmatter.id} for parent ${args.parentId}: ${err}`,\n      );\n    }\n  }\n}\n\nexport interface TemporalSupersessionResult {\n  supersededIds: string[];\n  matchedKeys: string[];\n}\n\n/**\n * Scan existing memories and mark any that are superseded by the\n * just-written memory.  Fails open on I/O errors — the new memory is already\n * on disk, and supersession is a best-effort hygiene step.\n */\nexport async function applyTemporalSupersession(args: {\n  storage: StorageManager;\n  newMemoryId: string;\n  entityRef?: string;\n  structuredAttributes?: Record<string, string>;\n  createdAt: string;\n  enabled: boolean;\n  /**\n   * When true, skip the persisted `frontmatter.created` lookup and use\n   * `args.createdAt` directly as the ordering anchor.  Set this on the\n   * hash-dedup short-circuit path where `newMemoryId` points to an existing\n   * OLD fact (no new file is written) and its persisted timestamp would be\n   * stale relative to the incoming promotion event (PR #402 Finding Uyui).\n   */\n  useCallerTimestamp?: boolean;\n}): Promise<TemporalSupersessionResult> {\n  const empty: TemporalSupersessionResult = { supersededIds: [], matchedKeys: [] };\n  if (!args.enabled) return empty;\n  if (!args.entityRef) return empty;\n  if (!args.structuredAttributes) return empty;\n  if (Object.keys(args.structuredAttributes).length === 0) return empty;\n\n  const newKeys = supersessionKeysForFact({\n    entityRef: args.entityRef,\n    structuredAttributes: args.structuredAttributes,\n  });\n  if (newKeys.length === 0) return empty;\n\n  let hotMemories: MemoryFile[];\n  try {\n    hotMemories = await args.storage.readAllMemories();\n  } catch (err) {\n    log.warn(`temporal-supersession: readAllMemories failed: ${err}`);\n    return empty;\n  }\n\n  // Finding 1 fix: use the on-disk effective validity start of the\n  // newly-written memory rather than a wall-clock timestamp sampled after\n  // `writeMemory` returns.  In concurrent writers the two can differ by enough\n  // to cause wrong-direction supersession.  If source replay/import provided\n  // valid_at, it must drive ordering; otherwise created remains the legacy\n  // fallback.  If the memory is not yet visible in the cache (edge case during\n  // fast concurrent writes) fall back to args.createdAt.\n  //\n  // PR #402 round-12 (Finding Uyui): on the hash-dedup early-return path the\n  // caller supplies the OLD matching fact's id as `newMemoryId` (no new file is\n  // written).  That makes `newMemoryFile.frontmatter.created` an arbitrarily\n  // old timestamp.  When `args.useCallerTimestamp` is set the caller explicitly\n  // opts out of the persisted-timestamp lookup so `args.createdAt` (the\n  // incoming event time: source valid_at when present, otherwise wall-clock) is\n  // used directly, keeping ordering correct regardless of how old the matching\n  // fact is.\n  const newMemoryFile = hotMemories.find((m) => m.frontmatter.id === args.newMemoryId);\n  const persistedCreatedAt = args.useCallerTimestamp\n    ? args.createdAt\n    : (newMemoryFile ? effectiveValidAt(newMemoryFile.frontmatter) : args.createdAt);\n\n  const supersededIds: string[] = [];\n  const matchedKeys = new Set<string>();\n\n  // Process hot then cold.  Hot-then-cold ordering is safer because hot\n  // writes are more frequent and the CAS re-read guards against double-writes.\n  // A Set<string> of already-processed ids ensures that a memory visible in\n  // both tiers (same logical memory with different filesystem paths during a\n  // migration race) is processed at most once.  Keying on `frontmatter.id`\n  // is correct because the same logical memory has the same id regardless of\n  // which tier's directory it currently lives in (PR #402 Finding 1 fix).\n  // Fall back to path-based keying when id is absent (defensive).\n  const processedIds = new Set<string>();\n\n  // Finding UOGi fix (round-6): readAllColdMemories() performs a full uncached\n  // recursive directory scan of cold/.  After Finding UTsP broadened the scan\n  // to cover the entire cold root (not just facts/+corrections/), the per-call\n  // cost grows with the cold tree size.\n  //\n  // The fix is a TTL-based in-memory cache inside StorageManager\n  // (readAllColdMemories caches its result for COLD_SCAN_CACHE_TTL_MS) that is\n  // shared across consecutive supersession calls within the same write burst.\n  // The cache is invalidated automatically on any hot→cold demotion (which\n  // calls invalidateAllMemoriesCache, which also clears the cold cache) and\n  // expires after the TTL as a safety net.\n  //\n  // This means back-to-back structured-attribute writes in the same burst\n  // (e.g. batch extraction) pay the cold I/O cost at most once, not N times.\n  // Correctness is preserved because the cache TTL ensures eventual consistency\n  // and the invalidation hook covers the hot→cold path.\n\n  let coldMemories: MemoryFile[];\n  try {\n    coldMemories = await args.storage.readAllColdMemories();\n  } catch (err) {\n    log.warn(`temporal-supersession: readAllColdMemories failed: ${err}`);\n    coldMemories = [];\n  }\n\n  // Combine hot and cold memories into a single scan.  New memory itself is\n  // excluded inline.  We do NOT skip cold scan when hot produced zero\n  // supersessions — the P1 finding is precisely that stale cold facts leak\n  // when hot has no hits.\n  const allCandidates: MemoryFile[] = [...hotMemories, ...coldMemories];\n\n  for (const memory of allCandidates) {\n    if (memory.frontmatter.id === args.newMemoryId) continue;\n    const dedupeKey = memory.frontmatter.id ?? memory.path;\n    if (processedIds.has(dedupeKey)) continue;\n    const snapshotStatus = memory.frontmatter.status ?? \"active\";\n    if (snapshotStatus !== \"active\") {\n      // A stale non-active snapshot entry must not suppress an active copy of\n      // the same logical memory that appears later in another tier.  This can\n      // happen during hot/cold migration races where the hot snapshot is already\n      // superseded but the cold copy is still active and should be evaluated.\n      continue;\n    }\n    // NOTE: do NOT call processedIds.add(dedupeKey) here.  We defer marking\n    // the id as processed until AFTER the CAS re-read succeeds.  If we mark\n    // it here and the re-read fails (e.g. the hot entry has already been\n    // migrated to cold storage), the same logical id that appears later in\n    // the cold tier scan would be silently skipped, leaving a stale cold\n    // fact unsuperseded.  Deferring ensures that a failed primary-tier read\n    // grants the alternate tier a chance to process the same id (PR #402\n    // round-6 Finding 1 fix).\n\n    const decision = shouldSupersedeExisting({\n      candidate: memory.frontmatter,\n      newEntityRef: args.entityRef,\n      newAttributes: args.structuredAttributes,\n      newCreatedAt: persistedCreatedAt,\n      newMemoryId: args.newMemoryId,\n    });\n    if (!decision) {\n      // No supersession decision — safe to mark as processed now so the\n      // alternate tier doesn't re-evaluate an identical non-matching entry.\n      processedIds.add(dedupeKey);\n      continue;\n    }\n\n    try {\n      // CAS-style re-read immediately before the write.  `readAllMemories()`\n      // is a snapshot — with concurrent writers, another run may have already\n      // superseded this candidate since we loaded it.  If we blindly trust the\n      // snapshot we can clobber a newer `supersededBy` link with a stale one.\n      //\n      // File storage offers no true locking, so the best we can do is:\n      //   1. re-read the exact file we're about to mutate\n      //   2. verify status is still \"active\" and no `supersededBy` is set\n      //   3. only then issue the write\n      // If the re-read shows a newer concurrent writer beat us to it, skip.\n      // This CAS pattern applies equally to hot and cold tier candidates.\n      // Mark as processed AFTER confirming the candidate is readable so that\n      // a migration-race read failure on the hot entry does not silently\n      // prevent the cold entry from being evaluated (Finding 1, round 6).\n      const fresh = await args.storage.readMemoryByPath(memory.path);\n      if (!fresh) {\n        log.debug(\n          `[engram] temporal supersession skipped candidate ${memory.frontmatter.id}: no longer readable at ${memory.path} — leaving id available for alternate tier`,\n        );\n        // Do NOT add to processedIds — allow the cold-tier copy to be\n        // evaluated in the next iteration of the same scan.\n        continue;\n      }\n      // Candidate is readable — mark the id as processed now to prevent the\n      // alternate tier from double-writing.\n      processedIds.add(dedupeKey);\n      const freshStatus = fresh.frontmatter.status ?? \"active\";\n      if (freshStatus !== \"active\" || fresh.frontmatter.supersededBy) {\n        log.debug(\n          `[engram] temporal supersession skipped candidate ${memory.frontmatter.id}: already superseded by concurrent writer`,\n        );\n        continue;\n      }\n\n      // Finding 2 fix: the `supersededAt` / `updated` timestamps written to the\n      // old fact must never run backwards relative to its own persisted\n      // `created` timestamp.  If the caller-supplied `args.createdAt` (which\n      // represents \"when the new replacing fact was authored\") is earlier than\n      // either the new fact's persisted `created` (T_new) or the old fact's\n      // persisted `created` (T_old), we'd be writing a nonsensical\n      // `supersededAt` that precedes the old memory's own creation.  Clamp to\n      // the monotonic maximum so time only moves forward.\n      // This monotonic clamp is applied for both hot and cold tier writes.\n      const oldCreatedMs = new Date(fresh.frontmatter.created).getTime();\n      const newCreatedMs = new Date(persistedCreatedAt).getTime();\n      const argCreatedMs = new Date(args.createdAt).getTime();\n      const maxMs = Math.max(\n        Number.isFinite(oldCreatedMs) ? oldCreatedMs : 0,\n        Number.isFinite(newCreatedMs) ? newCreatedMs : 0,\n        Number.isFinite(argCreatedMs) ? argCreatedMs : 0,\n      );\n      const supersededAt = new Date(maxMs).toISOString();\n\n      // Issue #680 — explicit fact lifecycle.  When the new fact\n      // supersedes this one, set the predecessor's `invalid_at` to the\n      // successor's effective valid_at.  Skip when the predecessor\n      // already carries an `invalid_at` so manual / earlier values\n      // are preserved (idempotent).\n      //\n      // Codex P1 on PR #713: in the hash-dedup early-return path\n      // (`useCallerTimestamp: true`), `newMemoryFile` is actually the\n      // OLD matching fact — no new file was written — so its\n      // `valid_at` is the predecessor's own old timestamp, not the\n      // successor's effective time. Use `persistedCreatedAt`\n      // directly in that path so the predecessor's invalid_at lines\n      // up with the caller's wall-clock, not the matching fact's old\n      // valid_at. The non-dedup path keeps the previous behavior\n      // (prefer the new file's explicit valid_at, fall back to its\n      // persisted created).\n      let invalidAtPatch: string | undefined;\n      if (!fresh.frontmatter.invalid_at) {\n        if (args.useCallerTimestamp) {\n          invalidAtPatch = persistedCreatedAt;\n        } else {\n          const newValidAt = newMemoryFile?.frontmatter.valid_at?.trim();\n          invalidAtPatch =\n            newValidAt && newValidAt.length > 0 ? newValidAt : persistedCreatedAt;\n        }\n      }\n      const wrote = await args.storage.writeMemoryFrontmatter(\n        fresh,\n        {\n          status: \"superseded\",\n          supersededBy: args.newMemoryId,\n          supersededAt,\n          updated: supersededAt,\n          ...(invalidAtPatch ? { invalid_at: invalidAtPatch } : {}),\n        },\n        {\n          actor: \"temporal-supersession\",\n          reasonCode: \"structured-attribute-update\",\n          relatedMemoryIds: [args.newMemoryId],\n        },\n      );\n      if (wrote) {\n        supersededIds.push(memory.frontmatter.id);\n        for (const key of decision.matchedKeys) matchedKeys.add(key);\n        await expireChildChunksForSupersededParent({\n          storage: args.storage,\n          allCandidates,\n          parentId: fresh.frontmatter.id,\n          newMemoryId: args.newMemoryId,\n          supersededAt,\n          invalidAt: invalidAtPatch ?? fresh.frontmatter.invalid_at,\n        });\n      }\n    } catch (err) {\n      log.warn(\n        `temporal-supersession: failed to mark ${memory.frontmatter.id} superseded: ${err}`,\n      );\n    }\n  }\n\n  if (supersededIds.length > 0) {\n    log.debug(\n      `temporal-supersession: marked ${supersededIds.length} memories superseded by ${args.newMemoryId} (keys=${Array.from(matchedKeys).join(\",\")})`,\n    );\n  }\n\n  return { supersededIds, matchedKeys: Array.from(matchedKeys) };\n}\n\n/**\n * Recall-side filter: returns true when the candidate should be excluded\n * from recall because it has been temporally superseded.  When\n * `includeInRecall` is true, this always returns false (the fact is kept),\n * matching the audit/history opt-in described in the config.\n */\nexport function shouldFilterSupersededFromRecall(\n  frontmatter: MemoryFrontmatter,\n  options: { enabled: boolean; includeInRecall: boolean },\n): boolean {\n  if (!options.enabled) return false;\n  if (options.includeInRecall) return false;\n  return frontmatter.status === \"superseded\";\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-ZTFCYYEZ.js → chunk-KCYE2MZM.js}

@@ -36,7 +36,7 @@ ${sections.join("\n\n")}`;
 }
 function selectBestCoverage(allNodes, fromTurn, toTurn) {
   const candidates = allNodes.filter(
-    (n) => n.msg_start <= toTurn && n.msg_end >= fromTurn
+    (n) => n.msg_start >= fromTurn && n.msg_end <= toTurn
   );
   if (candidates.length === 0) return [];
   candidates.sort((a, b) => {
@@ -48,7 +48,7 @@ function selectBestCoverage(allNodes, fromTurn, toTurn) {
   for (const node of candidates) {
     if (node.msg_start > coveredUpTo) {
       selected.push(node);
-      coveredUpTo = Math.min(node.msg_end, toTurn);
+      coveredUpTo = node.msg_end;
       if (coveredUpTo >= toTurn) break;
     }
   }
@@ -66,4 +66,4 @@ function formatRangeLabel(node, maxTurn) {
 export {
   assembleCompressedHistory
 };
-//# sourceMappingURL=chunk-ZTFCYYEZ.js.map
+//# sourceMappingURL=chunk-KCYE2MZM.js.map

package/dist/chunk-KCYE2MZM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lcm/recall.ts"],"sourcesContent":["import type { LcmDag, SummaryNode } from \"./dag.js\";\nimport type { LcmArchive } from \"./archive.js\";\nimport { log } from \"../logger.js\";\n\nexport interface LcmRecallConfig {\n  freshTailTurns: number;\n  budgetChars: number;\n}\n\n/**\n * Assemble a compressed session history section from the summary DAG.\n *\n * Strategy:\n * 1. For the \"fresh tail\" (most recent N turns), use leaf-level summaries for maximum detail.\n * 2. For older portions, use the deepest available summary nodes (most compressed).\n * 3. Fill within budget, prioritizing recent content.\n */\nexport function assembleCompressedHistory(\n  dag: LcmDag,\n  archive: LcmArchive,\n  sessionId: string,\n  config: LcmRecallConfig,\n): string {\n  const maxTurn = archive.getMaxTurnIndex(sessionId);\n  if (maxTurn < 0) return \"\";\n\n  const allNodes = dag.getAllNodes(sessionId);\n  if (allNodes.length === 0) return \"\";\n\n  const freshTailStart = Math.max(0, maxTurn - config.freshTailTurns + 1);\n  const sections: string[] = [];\n  let usedChars = 0;\n\n  // Collect nodes covering the \"old\" portion (before fresh tail)\n  if (freshTailStart > 0) {\n    const oldNodes = selectBestCoverage(allNodes, 0, freshTailStart - 1);\n    for (const node of oldNodes) {\n      const label = formatRangeLabel(node, maxTurn);\n      const entry = `**${label}** (depth ${node.depth}):\\n${node.summary_text}`;\n      if (usedChars + entry.length > config.budgetChars) break;\n      sections.push(entry);\n      usedChars += entry.length;\n    }\n  }\n\n  // Collect leaf nodes that overlap with the fresh tail region.\n  // The old section uses deep nodes (depth > 0), so leaf nodes included here\n  // won't duplicate old-section content. Use msg_end >= freshTailStart to\n  // include straddling leaf nodes that partially cover the fresh region.\n  const freshNodes = allNodes\n    .filter(\n      (n) => n.depth === 0 && n.msg_end >= freshTailStart && n.msg_end <= maxTurn,\n    )\n    .sort((a, b) => a.msg_start - b.msg_start);\n\n  for (const node of freshNodes) {\n    const label = `Recent (turns ${node.msg_start}-${node.msg_end})`;\n    const entry = `**${label}**:\\n${node.summary_text}`;\n    if (usedChars + entry.length > config.budgetChars) break;\n    sections.push(entry);\n    usedChars += entry.length;\n  }\n\n  if (sections.length === 0) return \"\";\n\n  return `## Session History (Compressed)\\n\\n${sections.join(\"\\n\\n\")}`;\n}\n\n/**\n * Select the best coverage for a turn range.\n * Prefers deeper (more compressed) nodes. Avoids overlapping coverage.\n */\nfunction selectBestCoverage(\n  allNodes: SummaryNode[],\n  fromTurn: number,\n  toTurn: number,\n): SummaryNode[] {\n  // Filter to nodes fully contained in the requested range. Straddling nodes\n  // would duplicate protected fresh-tail turns while still emitting their full\n  // summary text and range label.\n  const candidates = allNodes.filter(\n    (n) => n.msg_start >= fromTurn && n.msg_end <= toTurn,\n  );\n\n  if (candidates.length === 0) return [];\n\n  // Sort by msg_start ascending, then depth descending (prefer deeper at same position)\n  candidates.sort((a, b) => {\n    if (a.msg_start !== b.msg_start) return a.msg_start - b.msg_start;\n    return b.depth - a.depth;\n  });\n\n  // Greedily select non-overlapping nodes, preferring deeper coverage.\n  const selected: SummaryNode[] = [];\n  let coveredUpTo = fromTurn - 1;\n\n  for (const node of candidates) {\n    if (node.msg_start > coveredUpTo) {\n      selected.push(node);\n      coveredUpTo = node.msg_end;\n      if (coveredUpTo >= toTurn) break;\n    }\n  }\n\n  // Re-sort selected by msg_start for chronological output\n  selected.sort((a, b) => a.msg_start - b.msg_start);\n  return selected;\n}\n\nfunction formatRangeLabel(node: SummaryNode, maxTurn: number): string {\n  const startPct = Math.round((node.msg_start / Math.max(1, maxTurn)) * 100);\n  const endPct = Math.round((node.msg_end / Math.max(1, maxTurn)) * 100);\n\n  if (startPct < 33) return `Early session (turns ${node.msg_start}-${node.msg_end})`;\n  if (endPct < 66) return `Mid session (turns ${node.msg_start}-${node.msg_end})`;\n  return `Later session (turns ${node.msg_start}-${node.msg_end})`;\n}\n"],"mappings":";AAiBO,SAAS,0BACd,KACA,SACA,WACA,QACQ;AACR,QAAM,UAAU,QAAQ,gBAAgB,SAAS;AACjD,MAAI,UAAU,EAAG,QAAO;AAExB,QAAM,WAAW,IAAI,YAAY,SAAS;AAC1C,MAAI,SAAS,WAAW,EAAG,QAAO;AAElC,QAAM,iBAAiB,KAAK,IAAI,GAAG,UAAU,OAAO,iBAAiB,CAAC;AACtE,QAAM,WAAqB,CAAC;AAC5B,MAAI,YAAY;AAGhB,MAAI,iBAAiB,GAAG;AACtB,UAAM,WAAW,mBAAmB,UAAU,GAAG,iBAAiB,CAAC;AACnE,eAAW,QAAQ,UAAU;AAC3B,YAAM,QAAQ,iBAAiB,MAAM,OAAO;AAC5C,YAAM,QAAQ,KAAK,KAAK,aAAa,KAAK,KAAK;AAAA,EAAO,KAAK,YAAY;AACvE,UAAI,YAAY,MAAM,SAAS,OAAO,YAAa;AACnD,eAAS,KAAK,KAAK;AACnB,mBAAa,MAAM;AAAA,IACrB;AAAA,EACF;AAMA,QAAM,aAAa,SAChB;AAAA,IACC,CAAC,MAAM,EAAE,UAAU,KAAK,EAAE,WAAW,kBAAkB,EAAE,WAAW;AAAA,EACtE,EACC,KAAK,CAAC,GAAG,MAAM,EAAE,YAAY,EAAE,SAAS;AAE3C,aAAW,QAAQ,YAAY;AAC7B,UAAM,QAAQ,iBAAiB,KAAK,SAAS,IAAI,KAAK,OAAO;AAC7D,UAAM,QAAQ,KAAK,KAAK;AAAA,EAAQ,KAAK,YAAY;AACjD,QAAI,YAAY,MAAM,SAAS,OAAO,YAAa;AACnD,aAAS,KAAK,KAAK;AACnB,iBAAa,MAAM;AAAA,EACrB;AAEA,MAAI,SAAS,WAAW,EAAG,QAAO;AAElC,SAAO;AAAA;AAAA,EAAsC,SAAS,KAAK,MAAM,CAAC;AACpE;AAMA,SAAS,mBACP,UACA,UACA,QACe;AAIf,QAAM,aAAa,SAAS;AAAA,IAC1B,CAAC,MAAM,EAAE,aAAa,YAAY,EAAE,WAAW;AAAA,EACjD;AAEA,MAAI,WAAW,WAAW,EAAG,QAAO,CAAC;AAGrC,aAAW,KAAK,CAAC,GAAG,MAAM;AACxB,QAAI,EAAE,cAAc,EAAE,UAAW,QAAO,EAAE,YAAY,EAAE;AACxD,WAAO,EAAE,QAAQ,EAAE;AAAA,EACrB,CAAC;AAGD,QAAM,WAA0B,CAAC;AACjC,MAAI,cAAc,WAAW;AAE7B,aAAW,QAAQ,YAAY;AAC7B,QAAI,KAAK,YAAY,aAAa;AAChC,eAAS,KAAK,IAAI;AAClB,oBAAc,KAAK;AACnB,UAAI,eAAe,OAAQ;AAAA,IAC7B;AAAA,EACF;AAGA,WAAS,KAAK,CAAC,GAAG,MAAM,EAAE,YAAY,EAAE,SAAS;AACjD,SAAO;AACT;AAEA,SAAS,iBAAiB,MAAmB,SAAyB;AACpE,QAAM,WAAW,KAAK,MAAO,KAAK,YAAY,KAAK,IAAI,GAAG,OAAO,IAAK,GAAG;AACzE,QAAM,SAAS,KAAK,MAAO,KAAK,UAAU,KAAK,IAAI,GAAG,OAAO,IAAK,GAAG;AAErE,MAAI,WAAW,GAAI,QAAO,wBAAwB,KAAK,SAAS,IAAI,KAAK,OAAO;AAChF,MAAI,SAAS,GAAI,QAAO,sBAAsB,KAAK,SAAS,IAAI,KAAK,OAAO;AAC5E,SAAO,wBAAwB,KAAK,SAAS,IAAI,KAAK,OAAO;AAC/D;","names":[]}

package/dist/{chunk-JWPLJLDU.js → chunk-KD3QD3A5.js}

@@ -47,7 +47,7 @@ function dedupeBehaviorSignalsByMemoryAndHash(signals) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const signal of signals) {
-    const key = `${signal.memoryId}:${signal.signalHash}`;
+    const key = `${signal.namespace}:${signal.memoryId}:${signal.signalHash}`;
     if (seen.has(key)) continue;
     seen.add(key);
     out.push(signal);
@@ -60,4 +60,4 @@ export {
   buildBehaviorSignalsForMemory,
   dedupeBehaviorSignalsByMemoryAndHash
 };
-//# sourceMappingURL=chunk-JWPLJLDU.js.map
+//# sourceMappingURL=chunk-KD3QD3A5.js.map

package/dist/{chunk-JWPLJLDU.js.map → chunk-KD3QD3A5.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/behavior-signals.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { BehaviorSignalEvent, MemoryCategory } from \"./types.js\";\n\nfunction normalizeSignalText(input: string): string {\n  return input.replace(/\\s+/g, \" \").trim().toLowerCase();\n}\n\nexport function buildBehaviorSignalHash(category: MemoryCategory, content: string): string {\n  const normalized = `${category}:${normalizeSignalText(content)}`;\n  return createHash(\"sha256\").update(normalized).digest(\"hex\").slice(0, 16);\n}\n\nexport function buildBehaviorSignalsForMemory(input: {\n  memoryId: string;\n  category: MemoryCategory;\n  content: string;\n  namespace: string;\n  confidence: number;\n  timestamp?: string;\n  source?: \"extraction\" | \"correction\";\n}): BehaviorSignalEvent[] {\n  const timestamp = input.timestamp ?? new Date().toISOString();\n  const signalHash = buildBehaviorSignalHash(input.category, input.content);\n  const source = input.source ?? \"extraction\";\n\n  if (input.category === \"correction\") {\n    return [\n      {\n        timestamp,\n        namespace: input.namespace,\n        memoryId: input.memoryId,\n        category: \"correction\",\n        signalType: \"correction_override\",\n        direction: \"negative\",\n        confidence: input.confidence,\n        signalHash,\n        source,\n      },\n    ];\n  }\n\n  if (input.category === \"preference\") {\n    return [\n      {\n        timestamp,\n        namespace: input.namespace,\n        memoryId: input.memoryId,\n        category: \"preference\",\n        signalType: \"preference_affinity\",\n        direction: \"positive\",\n        confidence: input.confidence,\n        signalHash,\n        source,\n      },\n    ];\n  }\n\n  return [];\n}\n\nexport function dedupeBehaviorSignalsByMemoryAndHash(\n  signals: BehaviorSignalEvent[],\n): BehaviorSignalEvent[] {\n  const seen = new Set<string>();\n  const out: BehaviorSignalEvent[] = [];\n  for (const signal of signals) {\n    const key = `${signal.memoryId}:${signal.signalHash}`;\n    if (seen.has(key)) continue;\n    seen.add(key);\n    out.push(signal);\n  }\n  return out;\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAG3B,SAAS,oBAAoB,OAAuB;AAClD,SAAO,MAAM,QAAQ,QAAQ,GAAG,EAAE,KAAK,EAAE,YAAY;AACvD;AAEO,SAAS,wBAAwB,UAA0B,SAAyB;AACzF,QAAM,aAAa,GAAG,QAAQ,IAAI,oBAAoB,OAAO,CAAC;AAC9D,SAAO,WAAW,QAAQ,EAAE,OAAO,UAAU,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AAC1E;AAEO,SAAS,8BAA8B,OAQpB;AACxB,QAAM,YAAY,MAAM,cAAa,oBAAI,KAAK,GAAE,YAAY;AAC5D,QAAM,aAAa,wBAAwB,MAAM,UAAU,MAAM,OAAO;AACxE,QAAM,SAAS,MAAM,UAAU;AAE/B,MAAI,MAAM,aAAa,cAAc;AACnC,WAAO;AAAA,MACL;AAAA,QACE;AAAA,QACA,WAAW,MAAM;AAAA,QACjB,UAAU,MAAM;AAAA,QAChB,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,WAAW;AAAA,QACX,YAAY,MAAM;AAAA,QAClB;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,MAAM,aAAa,cAAc;AACnC,WAAO;AAAA,MACL;AAAA,QACE;AAAA,QACA,WAAW,MAAM;AAAA,QACjB,UAAU,MAAM;AAAA,QAChB,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,WAAW;AAAA,QACX,YAAY,MAAM;AAAA,QAClB;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,CAAC;AACV;AAEO,SAAS,qCACd,SACuB;AACvB,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,MAA6B,CAAC;AACpC,aAAW,UAAU,SAAS;AAC5B,UAAM,MAAM,GAAG,OAAO,QAAQ,IAAI,OAAO,UAAU;AACnD,QAAI,KAAK,IAAI,GAAG,EAAG;AACnB,SAAK,IAAI,GAAG;AACZ,QAAI,KAAK,MAAM;AAAA,EACjB;AACA,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/behavior-signals.ts"],"sourcesContent":["import { createHash } from \"node:crypto\";\nimport type { BehaviorSignalEvent, MemoryCategory } from \"./types.js\";\n\nfunction normalizeSignalText(input: string): string {\n  return input.replace(/\\s+/g, \" \").trim().toLowerCase();\n}\n\nexport function buildBehaviorSignalHash(category: MemoryCategory, content: string): string {\n  const normalized = `${category}:${normalizeSignalText(content)}`;\n  return createHash(\"sha256\").update(normalized).digest(\"hex\").slice(0, 16);\n}\n\nexport function buildBehaviorSignalsForMemory(input: {\n  memoryId: string;\n  category: MemoryCategory;\n  content: string;\n  namespace: string;\n  confidence: number;\n  timestamp?: string;\n  source?: \"extraction\" | \"correction\";\n}): BehaviorSignalEvent[] {\n  const timestamp = input.timestamp ?? new Date().toISOString();\n  const signalHash = buildBehaviorSignalHash(input.category, input.content);\n  const source = input.source ?? \"extraction\";\n\n  if (input.category === \"correction\") {\n    return [\n      {\n        timestamp,\n        namespace: input.namespace,\n        memoryId: input.memoryId,\n        category: \"correction\",\n        signalType: \"correction_override\",\n        direction: \"negative\",\n        confidence: input.confidence,\n        signalHash,\n        source,\n      },\n    ];\n  }\n\n  if (input.category === \"preference\") {\n    return [\n      {\n        timestamp,\n        namespace: input.namespace,\n        memoryId: input.memoryId,\n        category: \"preference\",\n        signalType: \"preference_affinity\",\n        direction: \"positive\",\n        confidence: input.confidence,\n        signalHash,\n        source,\n      },\n    ];\n  }\n\n  return [];\n}\n\nexport function dedupeBehaviorSignalsByMemoryAndHash(\n  signals: BehaviorSignalEvent[],\n): BehaviorSignalEvent[] {\n  const seen = new Set<string>();\n  const out: BehaviorSignalEvent[] = [];\n  for (const signal of signals) {\n    const key = `${signal.namespace}:${signal.memoryId}:${signal.signalHash}`;\n    if (seen.has(key)) continue;\n    seen.add(key);\n    out.push(signal);\n  }\n  return out;\n}\n"],"mappings":";AAAA,SAAS,kBAAkB;AAG3B,SAAS,oBAAoB,OAAuB;AAClD,SAAO,MAAM,QAAQ,QAAQ,GAAG,EAAE,KAAK,EAAE,YAAY;AACvD;AAEO,SAAS,wBAAwB,UAA0B,SAAyB;AACzF,QAAM,aAAa,GAAG,QAAQ,IAAI,oBAAoB,OAAO,CAAC;AAC9D,SAAO,WAAW,QAAQ,EAAE,OAAO,UAAU,EAAE,OAAO,KAAK,EAAE,MAAM,GAAG,EAAE;AAC1E;AAEO,SAAS,8BAA8B,OAQpB;AACxB,QAAM,YAAY,MAAM,cAAa,oBAAI,KAAK,GAAE,YAAY;AAC5D,QAAM,aAAa,wBAAwB,MAAM,UAAU,MAAM,OAAO;AACxE,QAAM,SAAS,MAAM,UAAU;AAE/B,MAAI,MAAM,aAAa,cAAc;AACnC,WAAO;AAAA,MACL;AAAA,QACE;AAAA,QACA,WAAW,MAAM;AAAA,QACjB,UAAU,MAAM;AAAA,QAChB,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,WAAW;AAAA,QACX,YAAY,MAAM;AAAA,QAClB;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,MAAI,MAAM,aAAa,cAAc;AACnC,WAAO;AAAA,MACL;AAAA,QACE;AAAA,QACA,WAAW,MAAM;AAAA,QACjB,UAAU,MAAM;AAAA,QAChB,UAAU;AAAA,QACV,YAAY;AAAA,QACZ,WAAW;AAAA,QACX,YAAY,MAAM;AAAA,QAClB;AAAA,QACA;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,SAAO,CAAC;AACV;AAEO,SAAS,qCACd,SACuB;AACvB,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,MAA6B,CAAC;AACpC,aAAW,UAAU,SAAS;AAC5B,UAAM,MAAM,GAAG,OAAO,SAAS,IAAI,OAAO,QAAQ,IAAI,OAAO,UAAU;AACvE,QAAI,KAAK,IAAI,GAAG,EAAG;AACnB,SAAK,IAAI,GAAG;AACZ,QAAI,KAAK,MAAM;AAAA,EACjB;AACA,SAAO;AACT;","names":[]}

package/dist/{chunk-YRMVARQP.js → chunk-KFY3SGN7.js}

@@ -1,6 +1,6 @@
 // src/session-integrity.ts
 import path from "path";
-import { readFile, readdir, unlink, writeFile } from "fs/promises";
+import { lstat, readFile, readdir, realpath, unlink, writeFile } from "fs/promises";
 function isObjectRecord(input) {
   return Boolean(input) && typeof input === "object";
 }
@@ -325,6 +325,7 @@ function planSessionRepair(options) {
   return {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
     dryRun: options.dryRun,
+    memoryDir: options.report.memoryDir,
     allowSessionFileRepair: options.allowSessionFileRepair === true,
     actions
   };
@@ -367,11 +368,13 @@ async function applySessionRepair(options) {
   for (const action of plan.actions) {
     try {
       if (action.kind === "rewrite_transcript") {
+        await assertRepairTargetAllowed(plan.memoryDir, action);
         await rewriteTranscriptFile(action.targetPath);
         actionsApplied += 1;
         continue;
       }
       if (action.kind === "remove_checkpoint") {
+        await assertRepairTargetAllowed(plan.memoryDir, action);
         try {
           await unlink(action.targetPath);
         } catch (err) {
@@ -397,10 +400,54 @@ async function applySessionRepair(options) {
     errors
   };
 }
+async function assertRepairTargetAllowed(memoryDir, action) {
+  const root = path.resolve(memoryDir);
+  const target = path.resolve(action.targetPath);
+  if (action.kind === "rewrite_transcript") {
+    const transcriptsRoot = path.join(root, "transcripts");
+    if (!target.endsWith(".jsonl")) {
+      throw new Error("transcript repair target must end in .jsonl");
+    }
+    await assertNoSymlinkPath(transcriptsRoot, target);
+    return;
+  }
+  if (action.kind === "remove_checkpoint") {
+    const checkpointPath = path.join(root, "state", "checkpoint.json");
+    if (target !== checkpointPath) {
+      throw new Error("checkpoint repair target must be the configured checkpoint.json");
+    }
+    await assertNoSymlinkPath(root, target);
+  }
+}
+async function assertNoSymlinkPath(root, target) {
+  const rootReal = await realpath(root);
+  const targetDir = path.dirname(target);
+  const targetDirReal = await realpath(targetDir);
+  const relative = path.relative(rootReal, targetDirReal);
+  if (relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative)) {
+    const normalizedTarget = path.join(targetDirReal, path.basename(target));
+    let current = rootReal;
+    for (const segment of path.relative(rootReal, normalizedTarget).split(path.sep)) {
+      if (!segment) continue;
+      current = path.join(current, segment);
+      try {
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink()) {
+          throw new Error(`repair target crosses symlink: ${current}`);
+        }
+      } catch (err) {
+        const code = typeof err === "object" && err && "code" in err ? String(err.code ?? "") : "";
+        if (code !== "ENOENT") throw err;
+      }
+    }
+    return;
+  }
+  throw new Error("repair target escapes configured memoryDir");
+}
 
 export {
   analyzeSessionIntegrity,
   planSessionRepair,
   applySessionRepair
 };
-//# sourceMappingURL=chunk-YRMVARQP.js.map
+//# sourceMappingURL=chunk-KFY3SGN7.js.map

package/dist/chunk-KFY3SGN7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/session-integrity.ts"],"sourcesContent":["import path from \"node:path\";\nimport { lstat, readFile, readdir, realpath, unlink, writeFile } from \"node:fs/promises\";\nimport type { Checkpoint, TranscriptEntry } from \"./types.js\";\n\nexport type SessionIntegrityIssueCode =\n  | \"transcript_malformed_line\"\n  | \"transcript_invalid_entry\"\n  | \"transcript_duplicate_turn_id\"\n  | \"transcript_broken_chain\"\n  | \"transcript_incomplete_turn\"\n  | \"checkpoint_missing\"\n  | \"checkpoint_invalid_json\"\n  | \"checkpoint_invalid_metadata\"\n  | \"checkpoint_expired\";\n\nexport interface SessionIntegrityIssue {\n  code: SessionIntegrityIssueCode;\n  severity: \"info\" | \"warn\" | \"error\";\n  message: string;\n  filePath?: string;\n  line?: number;\n  sessionKey?: string;\n}\n\nexport interface SessionTranscriptStats {\n  sessionKey: string;\n  entries: number;\n  malformedLines: number;\n  invalidEntries: number;\n  duplicateTurnIds: number;\n  brokenChains: number;\n  incompleteTurns: number;\n}\n\nexport interface SessionIntegrityReport {\n  generatedAt: string;\n  memoryDir: string;\n  healthy: boolean;\n  sessions: SessionTranscriptStats[];\n  checkpoint: {\n    present: boolean;\n    healthy: boolean;\n    path: string;\n    sessionKey?: string;\n    expiresAt?: string;\n  };\n  issues: SessionIntegrityIssue[];\n}\n\ntype SessionEntryRef = {\n  filePath: string;\n  lineNumber: number;\n  entry: TranscriptEntry;\n};\n\ntype FileSessionParse = {\n  bySession: Map<string, SessionEntryRef[]>;\n  malformed: SessionIntegrityIssue[];\n  invalid: SessionIntegrityIssue[];\n  invalidBySession: Map<string, number>;\n};\n\nexport interface SessionRepairAction {\n  kind: \"rewrite_transcript\" | \"remove_checkpoint\" | \"repair_session_files\";\n  description: string;\n  targetPath: string;\n  details?: string;\n}\n\nexport interface SessionRepairPlan {\n  generatedAt: string;\n  dryRun: boolean;\n  memoryDir: string;\n  allowSessionFileRepair: boolean;\n  actions: SessionRepairAction[];\n}\n\nexport interface SessionRepairApplyResult {\n  applied: boolean;\n  actionsAttempted: number;\n  actionsApplied: number;\n  errors: string[];\n}\n\nexport interface AnalyzeSessionIntegrityOptions {\n  memoryDir: string;\n}\n\nexport interface PlanSessionRepairOptions {\n  report: SessionIntegrityReport;\n  dryRun: boolean;\n  allowSessionFileRepair?: boolean;\n  sessionFilesDir?: string;\n}\n\nexport interface ApplySessionRepairOptions {\n  plan: SessionRepairPlan;\n}\n\nfunction isObjectRecord(input: unknown): input is Record<string, unknown> {\n  return Boolean(input) && typeof input === \"object\";\n}\n\nfunction isTranscriptEntry(raw: unknown): raw is TranscriptEntry {\n  if (!isObjectRecord(raw)) return false;\n  if (raw.role !== \"user\" && raw.role !== \"assistant\") return false;\n  return (\n    typeof raw.timestamp === \"string\" &&\n    raw.timestamp.length > 0 &&\n    typeof raw.content === \"string\" &&\n    typeof raw.sessionKey === \"string\" &&\n    raw.sessionKey.length > 0 &&\n    typeof raw.turnId === \"string\" &&\n    raw.turnId.length > 0\n  );\n}\n\nasync function listTranscriptFiles(memoryDir: string): Promise<string[]> {\n  const transcriptsDir = path.join(memoryDir, \"transcripts\");\n  const out: string[] = [];\n  const stack = [transcriptsDir];\n  while (stack.length > 0) {\n    const dir = stack.pop();\n    if (!dir) continue;\n    let entries: Array<{ name: string; isDirectory(): boolean; isFile(): boolean }>;\n    try {\n      entries = await readdir(dir, { withFileTypes: true });\n    } catch {\n      continue;\n    }\n    for (const entry of entries) {\n      const fullPath = path.join(dir, entry.name);\n      if (entry.isDirectory()) {\n        stack.push(fullPath);\n      } else if (entry.isFile() && entry.name.endsWith(\".jsonl\")) {\n        out.push(fullPath);\n      }\n    }\n  }\n  return out.sort((a, b) => a.localeCompare(b));\n}\n\nasync function parseTranscriptFile(filePath: string): Promise<FileSessionParse> {\n  const bySession = new Map<string, SessionEntryRef[]>();\n  const malformed: SessionIntegrityIssue[] = [];\n  const invalid: SessionIntegrityIssue[] = [];\n  const invalidBySession = new Map<string, number>();\n\n  let raw = \"\";\n  try {\n    raw = await readFile(filePath, \"utf-8\");\n  } catch {\n    return { bySession, malformed, invalid, invalidBySession };\n  }\n\n  const lines = raw.split(\"\\n\");\n  for (let index = 0; index < lines.length; index += 1) {\n    const line = lines[index]?.trim() ?? \"\";\n    if (!line) continue;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(line);\n    } catch {\n      malformed.push({\n        code: \"transcript_malformed_line\",\n        severity: \"warn\",\n        message: \"Transcript line is not valid JSON.\",\n        filePath,\n        line: index + 1,\n      });\n      continue;\n    }\n    if (!isTranscriptEntry(parsed)) {\n      const sessionKey =\n        isObjectRecord(parsed) &&\n        typeof parsed.sessionKey === \"string\" &&\n        parsed.sessionKey.length > 0\n          ? parsed.sessionKey\n          : undefined;\n      invalid.push({\n        code: \"transcript_invalid_entry\",\n        severity: \"warn\",\n        message: \"Transcript entry is missing required fields.\",\n        filePath,\n        line: index + 1,\n        sessionKey,\n      });\n      if (sessionKey) {\n        invalidBySession.set(sessionKey, (invalidBySession.get(sessionKey) ?? 0) + 1);\n      }\n      continue;\n    }\n\n    const list = bySession.get(parsed.sessionKey) ?? [];\n    list.push({ filePath, lineNumber: index + 1, entry: parsed });\n    bySession.set(parsed.sessionKey, list);\n  }\n  return { bySession, malformed, invalid, invalidBySession };\n}\n\nfunction analyzeSessionEntries(\n  sessionKey: string,\n  refs: SessionEntryRef[],\n): { stats: SessionTranscriptStats; issues: SessionIntegrityIssue[] } {\n  function parseTimestampForSort(timestamp: string): number {\n    const parsed = Date.parse(timestamp);\n    if (Number.isFinite(parsed)) return parsed;\n    return Number.MAX_SAFE_INTEGER;\n  }\n\n  const issues: SessionIntegrityIssue[] = [];\n  const sorted = [...refs].sort((a, b) => {\n    const tsA = parseTimestampForSort(a.entry.timestamp);\n    const tsB = parseTimestampForSort(b.entry.timestamp);\n    if (tsA !== tsB) return tsA - tsB;\n    const rawTimestampCmp = a.entry.timestamp.localeCompare(b.entry.timestamp);\n    if (rawTimestampCmp !== 0) return rawTimestampCmp;\n    return a.entry.turnId.localeCompare(b.entry.turnId);\n  });\n  const turnIdSeen = new Set<string>();\n  let duplicateTurnIds = 0;\n  let brokenChains = 0;\n\n  for (let i = 0; i < sorted.length; i += 1) {\n    const current = sorted[i];\n    if (turnIdSeen.has(current.entry.turnId)) {\n      duplicateTurnIds += 1;\n      issues.push({\n        code: \"transcript_duplicate_turn_id\",\n        severity: \"warn\",\n        message: `Duplicate turnId detected: ${current.entry.turnId}`,\n        sessionKey,\n        filePath: current.filePath,\n        line: current.lineNumber,\n      });\n    } else {\n      turnIdSeen.add(current.entry.turnId);\n    }\n\n    if (i > 0) {\n      const previous = sorted[i - 1];\n      if (previous && previous.entry.role === current.entry.role) {\n        brokenChains += 1;\n        issues.push({\n          code: \"transcript_broken_chain\",\n          severity: \"warn\",\n          message: `Adjacent turns have the same role (${current.entry.role}).`,\n          sessionKey,\n          filePath: current.filePath,\n          line: current.lineNumber,\n        });\n      }\n    }\n  }\n\n  let incompleteTurns = 0;\n  if (sorted.length > 0 && sorted[sorted.length - 1]?.entry.role === \"user\") {\n    incompleteTurns = 1;\n    const last = sorted[sorted.length - 1];\n    issues.push({\n      code: \"transcript_incomplete_turn\",\n      severity: \"warn\",\n      message: \"Session ends on a user turn without assistant response.\",\n      sessionKey,\n      filePath: last?.filePath,\n      line: last?.lineNumber,\n    });\n  }\n\n  return {\n    stats: {\n      sessionKey,\n      entries: sorted.length,\n      malformedLines: 0,\n      invalidEntries: 0,\n      duplicateTurnIds,\n      brokenChains,\n      incompleteTurns,\n    },\n    issues,\n  };\n}\n\nfunction validateCheckpointRaw(checkpoint: unknown): checkpoint is Checkpoint {\n  if (!isObjectRecord(checkpoint)) return false;\n  return (\n    typeof checkpoint.sessionKey === \"string\" &&\n    checkpoint.sessionKey.length > 0 &&\n    typeof checkpoint.capturedAt === \"string\" &&\n    typeof checkpoint.ttl === \"string\" &&\n    Array.isArray(checkpoint.turns)\n  );\n}\n\nasync function analyzeCheckpoint(memoryDir: string): Promise<{\n  checkpoint: SessionIntegrityReport[\"checkpoint\"];\n  issues: SessionIntegrityIssue[];\n}> {\n  const checkpointPath = path.join(memoryDir, \"state\", \"checkpoint.json\");\n  const issues: SessionIntegrityIssue[] = [];\n  const checkpoint: SessionIntegrityReport[\"checkpoint\"] = {\n    present: false,\n    healthy: true,\n    path: checkpointPath,\n  };\n\n  let raw = \"\";\n  try {\n    raw = await readFile(checkpointPath, \"utf-8\");\n  } catch {\n    issues.push({\n      code: \"checkpoint_missing\",\n      severity: \"info\",\n      message: \"No checkpoint file present.\",\n      filePath: checkpointPath,\n    });\n    return { checkpoint, issues };\n  }\n\n  checkpoint.present = true;\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    checkpoint.healthy = false;\n    issues.push({\n      code: \"checkpoint_invalid_json\",\n      severity: \"error\",\n      message: \"Checkpoint file is invalid JSON.\",\n      filePath: checkpointPath,\n    });\n    return { checkpoint, issues };\n  }\n\n  if (!validateCheckpointRaw(parsed)) {\n    checkpoint.healthy = false;\n    issues.push({\n      code: \"checkpoint_invalid_metadata\",\n      severity: \"error\",\n      message: \"Checkpoint file is missing required metadata fields.\",\n      filePath: checkpointPath,\n    });\n    return { checkpoint, issues };\n  }\n\n  checkpoint.sessionKey = parsed.sessionKey;\n  checkpoint.expiresAt = parsed.ttl;\n\n  const ttlMs = Date.parse(parsed.ttl);\n  const capturedAtMs = Date.parse(parsed.capturedAt);\n  if (!Number.isFinite(ttlMs) || !Number.isFinite(capturedAtMs) || ttlMs <= capturedAtMs) {\n    checkpoint.healthy = false;\n    issues.push({\n      code: \"checkpoint_invalid_metadata\",\n      severity: \"error\",\n      message: \"Checkpoint timestamps are invalid or inconsistent.\",\n      filePath: checkpointPath,\n      sessionKey: parsed.sessionKey,\n    });\n    return { checkpoint, issues };\n  }\n\n  if (ttlMs < Date.now()) {\n    checkpoint.healthy = false;\n    issues.push({\n      code: \"checkpoint_expired\",\n      severity: \"warn\",\n      message: \"Checkpoint TTL has expired.\",\n      filePath: checkpointPath,\n      sessionKey: parsed.sessionKey,\n    });\n  }\n\n  for (const turn of parsed.turns) {\n    if (!isTranscriptEntry(turn)) {\n      checkpoint.healthy = false;\n      issues.push({\n        code: \"checkpoint_invalid_metadata\",\n        severity: \"error\",\n        message: \"Checkpoint contains invalid turn entries.\",\n        filePath: checkpointPath,\n        sessionKey: parsed.sessionKey,\n      });\n      break;\n    }\n  }\n\n  return { checkpoint, issues };\n}\n\nexport async function analyzeSessionIntegrity(\n  options: AnalyzeSessionIntegrityOptions,\n): Promise<SessionIntegrityReport> {\n  const memoryDir = options.memoryDir;\n  const reportIssues: SessionIntegrityIssue[] = [];\n  const allSessionRefs = new Map<string, SessionEntryRef[]>();\n  const invalidBySession = new Map<string, number>();\n  const sessions = new Map<string, SessionTranscriptStats>();\n\n  const files = await listTranscriptFiles(memoryDir);\n  for (const filePath of files) {\n    const parsed = await parseTranscriptFile(filePath);\n    reportIssues.push(...parsed.malformed, ...parsed.invalid);\n    for (const [sessionKey, count] of parsed.invalidBySession.entries()) {\n      invalidBySession.set(sessionKey, (invalidBySession.get(sessionKey) ?? 0) + count);\n    }\n\n    for (const [sessionKey, refs] of parsed.bySession.entries()) {\n      const existing = allSessionRefs.get(sessionKey) ?? [];\n      existing.push(...refs);\n      allSessionRefs.set(sessionKey, existing);\n    }\n  }\n\n  for (const [sessionKey, refs] of allSessionRefs.entries()) {\n    const analyzed = analyzeSessionEntries(sessionKey, refs);\n    reportIssues.push(...analyzed.issues);\n    sessions.set(sessionKey, {\n      ...analyzed.stats,\n      malformedLines: 0,\n      invalidEntries: invalidBySession.get(sessionKey) ?? 0,\n    });\n  }\n\n  const checkpoint = await analyzeCheckpoint(memoryDir);\n  reportIssues.push(...checkpoint.issues);\n\n  const severeIssueCount = reportIssues.filter((issue) => issue.severity !== \"info\").length;\n\n  return {\n    generatedAt: new Date().toISOString(),\n    memoryDir,\n    healthy: severeIssueCount === 0,\n    sessions: [...sessions.values()].sort((a, b) => a.sessionKey.localeCompare(b.sessionKey)),\n    checkpoint: checkpoint.checkpoint,\n    issues: reportIssues,\n  };\n}\n\nfunction collectTranscriptRewriteTargets(report: SessionIntegrityReport): string[] {\n  const set = new Set<string>();\n  for (const issue of report.issues) {\n    if (!issue.filePath) continue;\n    if (\n      issue.code === \"transcript_malformed_line\" ||\n      issue.code === \"transcript_invalid_entry\"\n    ) {\n      set.add(issue.filePath);\n    }\n  }\n  return [...set].sort((a, b) => a.localeCompare(b));\n}\n\nexport function planSessionRepair(options: PlanSessionRepairOptions): SessionRepairPlan {\n  const actions: SessionRepairAction[] = [];\n  const transcriptTargets = collectTranscriptRewriteTargets(options.report);\n  for (const targetPath of transcriptTargets) {\n    actions.push({\n      kind: \"rewrite_transcript\",\n      targetPath,\n      description: \"Rewrite transcript file with only valid JSON transcript entries.\",\n    });\n  }\n\n  const checkpointNeedsRepair = options.report.issues.some((issue) =>\n    issue.code === \"checkpoint_invalid_json\" ||\n    issue.code === \"checkpoint_invalid_metadata\" ||\n    issue.code === \"checkpoint_expired\"\n  );\n  if (checkpointNeedsRepair && options.report.checkpoint.present) {\n    actions.push({\n      kind: \"remove_checkpoint\",\n      targetPath: options.report.checkpoint.path,\n      description: \"Remove invalid or expired checkpoint file.\",\n    });\n  }\n\n  if (options.sessionFilesDir && options.allowSessionFileRepair === true) {\n    actions.push({\n      kind: \"repair_session_files\",\n      targetPath: options.sessionFilesDir,\n      description: \"Session file repair was requested; no automatic rewiring is performed.\",\n      details: \"No-op by design. OpenClaw session files require explicit manual review.\",\n    });\n  }\n\n  return {\n    generatedAt: new Date().toISOString(),\n    dryRun: options.dryRun,\n    memoryDir: options.report.memoryDir,\n    allowSessionFileRepair: options.allowSessionFileRepair === true,\n    actions,\n  };\n}\n\nasync function rewriteTranscriptFile(targetPath: string): Promise<void> {\n  let raw = \"\";\n  try {\n    raw = await readFile(targetPath, \"utf-8\");\n  } catch {\n    return;\n  }\n  const lines = raw.split(\"\\n\");\n  const validLines: string[] = [];\n  for (const line of lines) {\n    const trimmed = line.trim();\n    if (!trimmed) continue;\n    try {\n      const parsed = JSON.parse(trimmed);\n      if (!isTranscriptEntry(parsed)) continue;\n      validLines.push(JSON.stringify(parsed));\n    } catch {\n      // drop malformed lines\n    }\n  }\n  const body = validLines.length > 0 ? `${validLines.join(\"\\n\")}\\n` : \"\";\n  await writeFile(targetPath, body, \"utf-8\");\n}\n\nexport async function applySessionRepair(\n  options: ApplySessionRepairOptions,\n): Promise<SessionRepairApplyResult> {\n  const { plan } = options;\n  if (plan.dryRun) {\n    return {\n      applied: false,\n      actionsAttempted: plan.actions.length,\n      actionsApplied: 0,\n      errors: [],\n    };\n  }\n\n  let actionsApplied = 0;\n  const errors: string[] = [];\n\n  for (const action of plan.actions) {\n    try {\n      if (action.kind === \"rewrite_transcript\") {\n        await assertRepairTargetAllowed(plan.memoryDir, action);\n        await rewriteTranscriptFile(action.targetPath);\n        actionsApplied += 1;\n        continue;\n      }\n      if (action.kind === \"remove_checkpoint\") {\n        await assertRepairTargetAllowed(plan.memoryDir, action);\n        try {\n          await unlink(action.targetPath);\n        } catch (err) {\n          const code = typeof err === \"object\" && err && \"code\" in err ? String((err as { code?: unknown }).code ?? \"\") : \"\";\n          if (code !== \"ENOENT\") {\n            throw err;\n          }\n        }\n        actionsApplied += 1;\n        continue;\n      }\n      if (action.kind === \"repair_session_files\") {\n        // intentionally no-op; pointer/session rewiring is explicitly forbidden here.\n        actionsApplied += 1;\n      }\n    } catch (err) {\n      errors.push(`Failed ${action.kind} ${action.targetPath}: ${err instanceof Error ? err.message : String(err)}`);\n    }\n  }\n\n  return {\n    applied: true,\n    actionsAttempted: plan.actions.length,\n    actionsApplied,\n    errors,\n  };\n}\n\nasync function assertRepairTargetAllowed(memoryDir: string, action: SessionRepairAction): Promise<void> {\n  const root = path.resolve(memoryDir);\n  const target = path.resolve(action.targetPath);\n  if (action.kind === \"rewrite_transcript\") {\n    const transcriptsRoot = path.join(root, \"transcripts\");\n    if (!target.endsWith(\".jsonl\")) {\n      throw new Error(\"transcript repair target must end in .jsonl\");\n    }\n    await assertNoSymlinkPath(transcriptsRoot, target);\n    return;\n  }\n  if (action.kind === \"remove_checkpoint\") {\n    const checkpointPath = path.join(root, \"state\", \"checkpoint.json\");\n    if (target !== checkpointPath) {\n      throw new Error(\"checkpoint repair target must be the configured checkpoint.json\");\n    }\n    await assertNoSymlinkPath(root, target);\n  }\n}\n\nasync function assertNoSymlinkPath(root: string, target: string): Promise<void> {\n  const rootReal = await realpath(root);\n  const targetDir = path.dirname(target);\n  const targetDirReal = await realpath(targetDir);\n  const relative = path.relative(rootReal, targetDirReal);\n  if (relative === \"\" || (!relative.startsWith(\"..\") && !path.isAbsolute(relative))) {\n    const normalizedTarget = path.join(targetDirReal, path.basename(target));\n    let current = rootReal;\n    for (const segment of path.relative(rootReal, normalizedTarget).split(path.sep)) {\n      if (!segment) continue;\n      current = path.join(current, segment);\n      try {\n        const stat = await lstat(current);\n        if (stat.isSymbolicLink()) {\n          throw new Error(`repair target crosses symlink: ${current}`);\n        }\n      } catch (err) {\n        const code = typeof err === \"object\" && err && \"code\" in err ? String((err as { code?: unknown }).code ?? \"\") : \"\";\n        if (code !== \"ENOENT\") throw err;\n      }\n    }\n    return;\n  }\n  throw new Error(\"repair target escapes configured memoryDir\");\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-CYFQJMUV.js → chunk-KIB7SDIJ.js}

@@ -1,14 +1,14 @@
-import {
-  searchConversationIndex,
-  searchConversationIndexFaissFailOpen
-} from "./chunk-7DTASS5T.js";
 import {
   failOpenFaissHealth
-} from "./chunk-FJ43PRLT.js";
+} from "./chunk-ORFGK3XI.js";
 import {
   rebuildConversationChunksFailOpen,
   upsertConversationChunksFailOpen
-} from "./chunk-LLQ2LLWF.js";
+} from "./chunk-HENLZHIT.js";
+import {
+  searchConversationIndex,
+  searchConversationIndexFaissFailOpen
+} from "./chunk-7DTASS5T.js";
 
 // src/conversation-index/backend.ts
 function createConversationIndexBackend(options) {
@@ -153,13 +153,18 @@ function createFaissBackend(getFaiss) {
     async search(query, maxResults) {
       return searchConversationIndexFaissFailOpen(getFaiss(), query, maxResults);
     },
-    async update(chunks, _options) {
-      await upsertConversationChunksFailOpen(getFaiss(), chunks);
+    async update(chunks, options) {
+      await upsertConversationChunksFailOpen(getFaiss(), chunks, {
+        retentionCutoffMs: options.retentionCutoffMs
+      });
       return { embedded: false };
     },
     async rebuild(chunks, _options) {
       const result = await rebuildConversationChunksFailOpen(getFaiss(), chunks);
-      return { embedded: false, rebuilt: result.skipped !== true };
+      return {
+        embedded: false,
+        rebuilt: result.skipped !== true && result.rebuilt === chunks.length
+      };
     },
     async health() {
       const faiss = await failOpenFaissHealth(getFaiss());
@@ -230,4 +235,4 @@ function createFaissBackend(getFaiss) {
 export {
   createConversationIndexBackend
 };
-//# sourceMappingURL=chunk-CYFQJMUV.js.map
+//# sourceMappingURL=chunk-KIB7SDIJ.js.map

package/dist/chunk-KIB7SDIJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/conversation-index/backend.ts"],"sourcesContent":["import type { SearchBackend, SearchExecutionOptions } from \"../search/port.js\";\nimport type { ConversationChunk } from \"./chunker.js\";\nimport { failOpenFaissHealth, type FaissConversationIndexAdapter } from \"./faiss-adapter.js\";\nimport {\n  rebuildConversationChunksFailOpen,\n  upsertConversationChunksFailOpen,\n} from \"./indexer.js\";\nimport { searchConversationIndex, searchConversationIndexFaissFailOpen, type ConversationSearchResult } from \"./search.js\";\n\ntype CollectionState = \"missing\" | \"unknown\" | \"present\" | \"skipped\";\n\nexport interface ConversationQmdRuntime extends SearchBackend {\n  isAvailable(): boolean;\n  probe(): Promise<boolean>;\n  ensureCollection(baseDir: string): Promise<CollectionState>;\n  update(execution?: SearchExecutionOptions): Promise<void>;\n  updateCollection(collection: string, execution?: SearchExecutionOptions): Promise<void>;\n  embed(): Promise<void>;\n  debugStatus(): string;\n}\n\nexport interface ConversationIndexBackendHealth {\n  backend: \"qmd\" | \"faiss\";\n  status: \"ok\" | \"degraded\" | \"disabled\";\n  message?: string;\n  qmdAvailable?: boolean;\n  faiss?: {\n    ok: boolean;\n    status: \"ok\" | \"degraded\" | \"error\";\n    indexPath: string;\n    message?: string;\n    manifest?: {\n      version: number;\n      modelId: string;\n      normalizedModelId: string;\n      dimension: number;\n      chunkCount: number;\n      updatedAt: string;\n      lastSuccessfulRebuildAt: string;\n    };\n  };\n}\n\nexport interface ConversationIndexBackendInspection {\n  backend: \"qmd\" | \"faiss\";\n  status: \"ok\" | \"degraded\" | \"disabled\";\n  available: boolean;\n  indexPath: string;\n  supportsIncrementalUpdate: boolean;\n  message?: string;\n  metadata: {\n    chunkCount: number | null;\n    qmdAvailable?: boolean;\n    debugStatus?: string;\n    hasIndex?: boolean;\n    hasMetadata?: boolean;\n    hasManifest?: boolean;\n    manifest?: {\n      version: number;\n      modelId: string;\n      normalizedModelId: string;\n      dimension: number;\n      chunkCount: number;\n      updatedAt: string;\n      lastSuccessfulRebuildAt: string;\n    };\n  };\n}\n\nexport interface ConversationIndexBackendInitResult {\n  enabled: boolean;\n  logLevel: \"info\" | \"warn\" | \"debug\";\n  message: string;\n}\n\nexport interface ConversationIndexBackend {\n  readonly kind: \"qmd\" | \"faiss\";\n  initialize(): Promise<ConversationIndexBackendInitResult>;\n  search(query: string, maxResults: number): Promise<ConversationSearchResult[]>;\n  update(\n    chunks: ConversationChunk[],\n    options: { embed: boolean; retentionCutoffMs?: number },\n  ): Promise<{ embedded: boolean }>;\n  rebuild(chunks: ConversationChunk[], options: { embed: boolean }): Promise<{ embedded: boolean; rebuilt: boolean }>;\n  health(): Promise<ConversationIndexBackendHealth>;\n  inspect(): Promise<ConversationIndexBackendInspection>;\n}\n\nexport function createConversationIndexBackend(options: {\n  enabled: boolean;\n  backend: \"qmd\" | \"faiss\";\n  getQmd?: () => ConversationQmdRuntime | undefined;\n  getFaiss?: () => FaissConversationIndexAdapter | undefined;\n  qmd?: ConversationQmdRuntime;\n  faiss?: FaissConversationIndexAdapter;\n  collectionDir: string;\n}): ConversationIndexBackend | undefined {\n  if (!options.enabled) return undefined;\n  const getQmd = options.getQmd ?? (() => options.qmd);\n  const getFaiss = options.getFaiss ?? (() => options.faiss);\n  if (options.backend === \"faiss\") {\n    return createFaissBackend(getFaiss);\n  }\n  return createQmdBackend(getQmd, options.collectionDir);\n}\n\nfunction createQmdBackend(\n  getQmd: () => ConversationQmdRuntime | undefined,\n  collectionDir: string,\n): ConversationIndexBackend {\n  return {\n    kind: \"qmd\",\n    async initialize() {\n      const qmd = getQmd();\n      if (!qmd) {\n        return {\n          enabled: true,\n          logLevel: \"warn\",\n          message: \"Conversation index QMD: not available search backend disabled or unsupported\",\n        };\n      }\n\n      const available = await qmd.probe();\n      if (!available) {\n        return {\n          enabled: true,\n          logLevel: \"warn\",\n          message: `Conversation index QMD: not available ${qmd.debugStatus()}`,\n        };\n      }\n\n      const collectionState = await qmd.ensureCollection(collectionDir);\n      if (collectionState === \"missing\") {\n        return {\n          enabled: false,\n          logLevel: \"warn\",\n          message: \"Conversation index collection missing; disabling conversation semantic recall for this runtime\",\n        };\n      }\n      if (collectionState === \"unknown\") {\n        return {\n          enabled: true,\n          logLevel: \"warn\",\n          message: \"Conversation index collection check unavailable; keeping conversation semantic recall enabled for fail-open behavior\",\n        };\n      }\n      if (collectionState === \"skipped\") {\n        return {\n          enabled: true,\n          logLevel: \"debug\",\n          message: \"Conversation index collection check skipped in daemon-only mode\",\n        };\n      }\n\n      return {\n        enabled: true,\n        logLevel: \"info\",\n        message: `Conversation index QMD: available ${qmd.debugStatus()}`,\n      };\n    },\n    async search(query: string, maxResults: number) {\n      const qmd = getQmd();\n      if (!qmd || !qmd.isAvailable()) return [];\n      return searchConversationIndex(qmd, query, maxResults);\n    },\n    async update(_chunks: ConversationChunk[], options: { embed: boolean; retentionCutoffMs?: number }) {\n      const qmd = getQmd();\n      if (!qmd || !qmd.isAvailable()) return { embedded: false };\n      await qmd.update();\n      if (options.embed) {\n        await qmd.embed();\n        return { embedded: true };\n      }\n      return { embedded: false };\n    },\n    async rebuild(_chunks: ConversationChunk[], options: { embed: boolean }) {\n      const qmd = getQmd();\n      if (!qmd || !qmd.isAvailable()) return { embedded: false, rebuilt: false };\n      await qmd.update();\n      if (options.embed) {\n        await qmd.embed();\n        return { embedded: true, rebuilt: true };\n      }\n      return { embedded: false, rebuilt: true };\n    },\n    async health() {\n      const qmd = getQmd();\n      let qmdAvailable = !!qmd?.isAvailable();\n      if (!qmdAvailable && qmd) {\n        try {\n          qmdAvailable = await qmd.probe();\n        } catch {\n          qmdAvailable = false;\n        }\n      }\n\n      return {\n        backend: \"qmd\",\n        status: qmdAvailable ? \"ok\" : \"degraded\",\n        qmdAvailable,\n      };\n    },\n    async inspect() {\n      const qmd = getQmd();\n      let qmdAvailable = !!qmd?.isAvailable();\n      if (!qmdAvailable && qmd) {\n        try {\n          qmdAvailable = await qmd.probe();\n        } catch {\n          qmdAvailable = false;\n        }\n      }\n\n      return {\n        backend: \"qmd\",\n        status: qmdAvailable ? \"ok\" : \"degraded\",\n        available: qmdAvailable,\n        indexPath: collectionDir,\n        supportsIncrementalUpdate: true,\n        message: qmd ? undefined : \"Conversation index QMD runtime unavailable\",\n        metadata: {\n          chunkCount: null,\n          qmdAvailable,\n          debugStatus: qmd?.debugStatus(),\n        },\n      };\n    },\n  };\n}\n\nfunction createFaissBackend(\n  getFaiss: () => FaissConversationIndexAdapter | undefined,\n): ConversationIndexBackend {\n  return {\n    kind: \"faiss\",\n    async initialize() {\n      const health = await failOpenFaissHealth(getFaiss());\n      return health.status === \"ok\"\n        ? {\n            enabled: true,\n            logLevel: \"info\",\n            message: `Conversation index FAISS: available (status=${health.status})`,\n          }\n        : {\n            enabled: true,\n            logLevel: \"warn\",\n            message: `Conversation index FAISS: degraded (${health.message ?? health.status})`,\n          };\n    },\n    async search(query: string, maxResults: number) {\n      return searchConversationIndexFaissFailOpen(getFaiss(), query, maxResults);\n    },\n    async update(chunks: ConversationChunk[], options: { embed: boolean; retentionCutoffMs?: number }) {\n      await upsertConversationChunksFailOpen(getFaiss(), chunks, {\n        retentionCutoffMs: options.retentionCutoffMs,\n      });\n      return { embedded: false };\n    },\n    async rebuild(chunks: ConversationChunk[], _options: { embed: boolean }) {\n      const result = await rebuildConversationChunksFailOpen(getFaiss(), chunks);\n      return {\n        embedded: false,\n        rebuilt: result.skipped !== true && result.rebuilt === chunks.length,\n      };\n    },\n    async health() {\n      const faiss = await failOpenFaissHealth(getFaiss());\n      return {\n        backend: \"faiss\",\n        status: faiss.status === \"ok\" ? \"ok\" : \"degraded\",\n        message: faiss.message,\n        faiss,\n      };\n    },\n    async inspect() {\n      const adapter = getFaiss();\n      if (!adapter) {\n        return {\n          backend: \"faiss\",\n          status: \"degraded\",\n          available: false,\n          indexPath: \"\",\n          supportsIncrementalUpdate: true,\n          message: \"Conversation index FAISS runtime unavailable\",\n          metadata: {\n            chunkCount: 0,\n            hasIndex: false,\n            hasMetadata: false,\n            hasManifest: false,\n          },\n        };\n      }\n\n      try {\n        const inspection = await adapter.inspect();\n        return {\n          backend: \"faiss\",\n          status: inspection.status === \"ok\" ? \"ok\" : \"degraded\",\n          available: inspection.status === \"ok\",\n          indexPath: inspection.indexPath,\n          supportsIncrementalUpdate: true,\n          message: inspection.message,\n          metadata: {\n            chunkCount: inspection.metadata.chunkCount,\n            hasIndex: inspection.metadata.hasIndex,\n            hasMetadata: inspection.metadata.hasMetadata,\n            hasManifest: inspection.metadata.hasManifest,\n            manifest: inspection.manifest,\n          },\n        };\n      } catch (err) {\n        const fallback = await failOpenFaissHealth(adapter);\n        return {\n          backend: \"faiss\",\n          status: \"degraded\",\n          available: false,\n          indexPath: fallback.indexPath,\n          supportsIncrementalUpdate: true,\n          message: fallback.message ?? String(err),\n          metadata: {\n            chunkCount: fallback.manifest?.chunkCount ?? 0,\n            hasIndex: false,\n            hasMetadata: false,\n            hasManifest: !!fallback.manifest,\n            manifest: fallback.manifest,\n          },\n        };\n      }\n    },\n  };\n}\n"],"mappings":"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","names":[]}