@remnic/core 9.3.734 → 9.3.736

package/dist/first-start-migration-W4U6XDKI.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/maintenance/first-start-migration.ts"],"sourcesContent":["/**\n * First-start lifecycle migration (issue #686 retention-completion).\n *\n * When `lifecyclePolicyEnabled` is true but the memoryDir has never been\n * touched by the lifecycle policy (i.e. the state marker\n * `.lifecycle-init-done` does not exist), run a one-time, rate-limited\n * demotion sweep so the hot tier isn't flooded on the first real cron pass.\n *\n * Design constraints:\n *   - Capped at `FIRST_START_DEMOTION_CAP` (default 50) demotions per run\n *     so a large pre-existing corpus doesn't stall startup.\n *   - Resumable: subsequent invocations see the marker and skip.\n *   - The marker is written AFTER all mutations succeed so a crash during\n *     migration doesn't leave a false \"done\" marker (CLAUDE.md rule #12).\n *   - Dry-run mode reports candidates without mutating anything or writing\n *     the marker (safe to call from tests).\n */\n\nimport path from \"node:path\";\nimport { access, mkdir, readFile, unlink, writeFile } from \"node:fs/promises\";\nimport {\n  resolveMemoryLifecycleCapabilities,\n  resolveQmdCapabilities,\n} from \"../capabilities.js\";\nimport type { StorageManager } from \"../storage.js\";\nimport type { PluginConfig } from \"../types.js\";\nimport {\n  decideTierTransition,\n  type TierRoutingPolicy,\n} from \"../tier-routing.js\";\nimport { TierMigrationExecutor } from \"../tier-migration.js\";\nimport type { SearchBackend } from \"../search/port.js\";\nimport {\n  applyUtilityPromotionRuntimePolicy,\n  loadUtilityRuntimeValues,\n} from \"../utility-runtime.js\";\n\nexport const FIRST_START_DEMOTION_CAP = 50;\nexport const LIFECYCLE_INIT_DONE_MARKER = \".lifecycle-init-done\";\nconst LIFECYCLE_QMD_REFRESH_PENDING_MARKER = \".lifecycle-qmd-refresh-pending\";\n\ntype QmdRefreshPendingMarker = {\n  createdAt: string;\n  collection: string;\n};\n\nexport interface FirstStartMigrationOptions {\n  storage: StorageManager;\n  config: PluginConfig;\n  /** Override the per-run demotion cap (default: FIRST_START_DEMOTION_CAP). */\n  demotionCap?: number;\n  /** When true, report candidates but do not mutate or write the marker. */\n  dryRun?: boolean;\n  /** Optional QMD backend used to journal demotions and refresh tier collections. */\n  qmd?: SearchBackend;\n  /** Hot-tier QMD collection name. Defaults to config.qmdCollection. */\n  hotCollection?: string;\n  /** Cold-tier QMD collection name. Defaults to config.qmdColdCollection. */\n  coldCollection?: string;\n  /** Optional shutdown signal. When aborted, the migration stops without writing the done marker. */\n  signal?: AbortSignal;\n  /** Override clock for tests. */\n  now?: () => Date;\n}\n\nexport interface FirstStartMigrationResult {\n  skipped: boolean;\n  skipReason?: string;\n  dryRun: boolean;\n  candidateCount: number;\n  demotedCount: number;\n  /** Number of individual demotion failures. When > 0, the init-done marker is\n   *  NOT written so the next start can retry the failed demotions. */\n  failureCount: number;\n  cappedAt: number;\n}\n\nfunction markerPath(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", LIFECYCLE_INIT_DONE_MARKER);\n}\n\nfunction qmdRefreshPendingPath(memoryDir: string): string {\n  return path.join(memoryDir, \"state\", LIFECYCLE_QMD_REFRESH_PENDING_MARKER);\n}\n\nasync function markerExists(memoryDir: string): Promise<boolean> {\n  try {\n    await access(markerPath(memoryDir));\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function writeMarker(memoryDir: string, now: Date): Promise<void> {\n  const p = markerPath(memoryDir);\n  await mkdir(path.dirname(p), { recursive: true });\n  await writeFile(p, JSON.stringify({ createdAt: now.toISOString() }), \"utf-8\");\n}\n\nasync function readQmdRefreshPending(memoryDir: string): Promise<QmdRefreshPendingMarker | null> {\n  try {\n    const raw = await readFile(qmdRefreshPendingPath(memoryDir), \"utf-8\");\n    const parsed = JSON.parse(raw) as unknown;\n    if (\n      parsed &&\n      typeof parsed === \"object\" &&\n      typeof (parsed as { createdAt?: unknown }).createdAt === \"string\" &&\n      typeof (parsed as { collection?: unknown }).collection === \"string\" &&\n      (parsed as { collection: string }).collection.length > 0\n    ) {\n      return parsed as QmdRefreshPendingMarker;\n    }\n    return null;\n  } catch {\n    return null;\n  }\n}\n\nasync function pathExists(p: string): Promise<boolean> {\n  try {\n    await access(p);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nasync function writeQmdRefreshPending(memoryDir: string, now: Date, collection: string): Promise<void> {\n  const p = qmdRefreshPendingPath(memoryDir);\n  await mkdir(path.dirname(p), { recursive: true });\n  await writeFile(p, JSON.stringify({ createdAt: now.toISOString(), collection }), \"utf-8\");\n}\n\nasync function clearQmdRefreshPending(memoryDir: string): Promise<void> {\n  await unlink(qmdRefreshPendingPath(memoryDir)).catch(() => {});\n}\n\nasync function buildTierRoutingPolicy(config: PluginConfig): Promise<TierRoutingPolicy> {\n  const basePolicy: TierRoutingPolicy = {\n    enabled: resolveQmdCapabilities(config).qmdTierMigration,\n    demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,\n    demotionValueThreshold: config.qmdTierDemotionValueThreshold,\n    promotionValueThreshold: config.qmdTierPromotionValueThreshold,\n  };\n  const runtime = await loadUtilityRuntimeValues({\n    memoryDir: config.memoryDir,\n    memoryUtilityLearningEnabled: config.memoryUtilityLearningEnabled,\n    promotionByOutcomeEnabled: config.promotionByOutcomeEnabled,\n  });\n  return applyUtilityPromotionRuntimePolicy(basePolicy, runtime);\n}\n\nasync function refreshQmdCollection(\n  qmd: SearchBackend,\n  collection: string,\n  signal?: AbortSignal,\n): Promise<void> {\n  if (typeof qmd.updateCollectionStrict === \"function\") {\n    await qmd.updateCollectionStrict(collection, { signal });\n    return;\n  }\n  await qmd.updateCollection(collection, { signal });\n}\n\n/**\n * Run the first-start migration sweep.  No-ops when:\n *   - `lifecyclePolicyEnabled` is false, or\n *   - `qmdTierMigrationEnabled` is false (no tier migration configured), or\n *   - the state marker already exists (already ran).\n *\n * Returns a structured result describing what happened.\n */\nexport async function runFirstStartMigration(\n  options: FirstStartMigrationOptions,\n): Promise<FirstStartMigrationResult> {\n  const {\n    storage,\n    config,\n    demotionCap = FIRST_START_DEMOTION_CAP,\n    dryRun = false,\n    qmd,\n    signal,\n  } = options;\n  const now = (options.now ?? (() => new Date()))();\n  const lifecycleCaps = resolveMemoryLifecycleCapabilities(config);\n  const abortedResult = (candidateCount = 0, demotedCount = 0, failureCount = 0): FirstStartMigrationResult => ({\n    skipped: candidateCount === 0 && demotedCount === 0 && failureCount === 0,\n    skipReason: candidateCount === 0 && demotedCount === 0 && failureCount === 0 ? \"aborted\" : undefined,\n    dryRun,\n    candidateCount,\n    demotedCount,\n    failureCount,\n    cappedAt: demotionCap,\n  });\n\n  if (signal?.aborted) {\n    return abortedResult();\n  }\n\n  if (!lifecycleCaps.lifecyclePolicy) {\n    return {\n      skipped: true,\n      skipReason: \"lifecyclePolicyEnabled is false\",\n      dryRun,\n      candidateCount: 0,\n      demotedCount: 0,\n      failureCount: 0,\n      cappedAt: demotionCap,\n    };\n  }\n\n  if (!resolveQmdCapabilities(config).qmdTierMigration) {\n    return {\n      skipped: true,\n      skipReason: \"qmdTierMigrationEnabled is false\",\n      dryRun,\n      candidateCount: 0,\n      demotedCount: 0,\n      failureCount: 0,\n      cappedAt: demotionCap,\n    };\n  }\n\n  if (await markerExists(config.memoryDir)) {\n    return {\n      skipped: true,\n      skipReason: \"lifecycle-init-done marker already present\",\n      dryRun,\n      candidateCount: 0,\n      demotedCount: 0,\n      failureCount: 0,\n      cappedAt: demotionCap,\n    };\n  }\n\n  if (signal?.aborted) {\n    return abortedResult();\n  }\n\n  const policy = await buildTierRoutingPolicy(config);\n  if (signal?.aborted) {\n    return abortedResult();\n  }\n\n  const hotMemories = await storage.readAllMemories();\n  if (signal?.aborted) {\n    return abortedResult();\n  }\n\n  // Find hot memories that should be demoted to cold\n  const demotionCandidates = hotMemories.filter((m) => {\n    const decision = decideTierTransition(m, \"hot\", policy, now);\n    return decision.changed && decision.nextTier === \"cold\";\n  });\n\n  const candidateCount = demotionCandidates.length;\n  // Apply cap\n  const batch = demotionCandidates.slice(0, demotionCap);\n\n  if (dryRun) {\n    return {\n      skipped: false,\n      dryRun: true,\n      candidateCount,\n      demotedCount: 0,\n      failureCount: 0,\n      cappedAt: demotionCap,\n    };\n  }\n\n  let demotedCount = 0;\n  let failureCount = 0;\n  let qmdRefreshPendingForRun = false;\n  const executor = qmd\n    ? new TierMigrationExecutor({\n        storage,\n        qmd,\n        hotCollection: options.hotCollection ?? config.qmdCollection ?? \"openclaw-engram\",\n        coldCollection: options.coldCollection ?? config.qmdColdCollection ?? \"openclaw-engram-cold\",\n    })\n    : null;\n  const coldCollection = options.coldCollection ?? config.qmdColdCollection ?? \"openclaw-engram-cold\";\n\n  for (const memory of batch) {\n    if (signal?.aborted) {\n      return abortedResult(candidateCount, demotedCount, failureCount);\n    }\n    try {\n      if (executor) {\n        await executor.migrateMemory({\n          memory,\n          fromTier: \"hot\",\n          toTier: \"cold\",\n          reason: \"first-start-lifecycle-migration\",\n        });\n      } else {\n        await storage.migrateMemoryToTier(memory, \"cold\");\n      }\n      demotedCount += 1;\n    } catch {\n      const targetPath = storage.buildTierMemoryPath(memory, \"cold\");\n      const [targetExists, sourceExists] = await Promise.all([\n        pathExists(targetPath),\n        pathExists(memory.path),\n      ]);\n      const movedToCold = targetExists && !sourceExists;\n      if (movedToCold) {\n        if (!qmd) {\n          demotedCount += 1;\n          continue;\n        }\n        try {\n          await refreshQmdCollection(qmd, coldCollection, signal);\n          demotedCount += 1;\n          continue;\n        } catch {\n          qmdRefreshPendingForRun = true;\n          try {\n            await writeQmdRefreshPending(config.memoryDir, now, coldCollection);\n          } catch {\n            // The end-of-run retry below still gets a chance to repair the QMD\n            // state before we decide whether the init marker is safe to write.\n          }\n          demotedCount += 1;\n          continue;\n        }\n      }\n      // Non-fatal — individual migration failures are counted but do not abort\n      // the sweep. We track them so the marker is only written when ALL\n      // attempted demotions succeeded (CLAUDE.md rule #12: don't write a\n      // success marker after a partial failure).\n      failureCount += 1;\n    }\n  }\n\n  // Write marker AFTER all mutations succeed (CLAUDE.md rule #12).\n  // If any demotion failed, skip the marker so the next start retries.\n  if (signal?.aborted) {\n    return abortedResult(candidateCount, demotedCount, failureCount);\n  }\n  const persistedQmdRefreshPending = qmd ? await readQmdRefreshPending(config.memoryDir) : null;\n  const hasPersistedQmdRefreshPending = persistedQmdRefreshPending?.collection === coldCollection;\n  if (qmd && persistedQmdRefreshPending && persistedQmdRefreshPending.collection !== coldCollection) {\n    failureCount += 1;\n  }\n  if (qmd && (qmdRefreshPendingForRun || hasPersistedQmdRefreshPending)) {\n    try {\n      await refreshQmdCollection(qmd, coldCollection, signal);\n      await clearQmdRefreshPending(config.memoryDir);\n    } catch {\n      failureCount += 1;\n    }\n  }\n  if (failureCount === 0) {\n    await writeMarker(config.memoryDir, now);\n  }\n\n  return {\n    skipped: false,\n    dryRun: false,\n    candidateCount,\n    demotedCount,\n    failureCount,\n    cappedAt: demotionCap,\n  };\n}\n"],"mappings":"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","names":["candidateCount","demotedCount","failureCount"]}

package/dist/tier-stats-LSM35HZY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/maintenance/tier-stats.ts"],"sourcesContent":["/**\n * Operator-facing tier visibility (issue #686 PR 5/6).\n *\n * Two read-only surfaces:\n *\n *   - `summarizeTiers(storage)` — count memories by tier (hot vs cold)\n *     plus per-status breakdown so operators can see at a glance\n *     whether the lifecycle policy has actually demoted anything.\n *   - `explainTierForMemory(storage, id)` — show the value-score\n *     components and tier-transition decision for a single memory\n *     so an operator can reason about why a memory ended up where\n *     it did.\n *\n * Pure inspection — neither surface mutates anything.  The CLI wires\n * them as `remnic tier list` and `remnic tier explain <id>`.\n */\n\nimport type { StorageManager } from \"../storage.js\";\nimport type { MemoryFile, PluginConfig } from \"../types.js\";\nimport { computeLifecycleValueInputs } from \"../lifecycle.js\";\nimport {\n  computeTierValueScore,\n  decideTierTransition,\n  type MemoryTier,\n  type TierRoutingPolicy,\n  type TierTransitionDecision,\n} from \"../tier-routing.js\";\nimport { resolveQmdCapabilities } from \"../capabilities.js\";\nimport {\n  applyUtilityPromotionRuntimePolicy,\n  loadUtilityRuntimeValues,\n} from \"../utility-runtime.js\";\n\nexport interface TierSummary {\n  /** Total memories scanned (all tiers, all statuses). */\n  total: number;\n  byTier: Record<MemoryTier, number>;\n  byStatus: Record<string, number>;\n  /** Memories with `status === \"forgotten\"` (issue #686 PR 4/6). */\n  forgottenCount: number;\n  /** Top contributors to the forgotten / archived buckets, by category. */\n  byCategory: Record<string, number>;\n}\n\nexport interface TierExplainResult {\n  id: string;\n  path: string;\n  currentTier: MemoryTier;\n  status: string;\n  category: string;\n  valueScore: number;\n  decision: TierTransitionDecision;\n  signals: {\n    confidence: number;\n    accessCount: number;\n    lastAccessed: string | null;\n    created: string;\n    updated: string;\n    importance: number;\n    feedback: number;\n  };\n}\n\ninterface TierVisibleMemory {\n  memory: MemoryFile;\n  tier: MemoryTier;\n}\n\nasync function readTierVisibleMemories(\n  storage: StorageManager,\n): Promise<TierVisibleMemory[]> {\n  const [hotMemories, coldMemories] = await Promise.all([\n    storage.readAllMemories(),\n    storage.readAllColdMemories(),\n  ]);\n  return [\n    ...hotMemories.map((memory) => ({ memory, tier: \"hot\" as const })),\n    ...coldMemories.map((memory) => ({ memory, tier: \"cold\" as const })),\n  ];\n}\n\nasync function tierRoutingPolicyFromConfig(\n  config: PluginConfig,\n): Promise<TierRoutingPolicy> {\n  const basePolicy: TierRoutingPolicy = {\n    enabled: resolveQmdCapabilities(config).qmdTierMigration,\n    demotionMinAgeDays: config.qmdTierDemotionMinAgeDays,\n    demotionValueThreshold: config.qmdTierDemotionValueThreshold,\n    promotionValueThreshold: config.qmdTierPromotionValueThreshold,\n  };\n  const runtime = await loadUtilityRuntimeValues({\n    memoryDir: config.memoryDir,\n    memoryUtilityLearningEnabled: config.memoryUtilityLearningEnabled,\n    promotionByOutcomeEnabled: config.promotionByOutcomeEnabled,\n  });\n  return applyUtilityPromotionRuntimePolicy(basePolicy, runtime);\n}\n\nexport async function summarizeTiers(\n  storage: StorageManager,\n): Promise<TierSummary> {\n  const all = await readTierVisibleMemories(storage);\n  const summary: TierSummary = {\n    total: all.length,\n    byTier: { hot: 0, cold: 0 },\n    byStatus: {},\n    forgottenCount: 0,\n    byCategory: {},\n  };\n  for (const { memory: m, tier } of all) {\n    summary.byTier[tier] += 1;\n    const status: string = m.frontmatter.status ?? \"active\";\n    summary.byStatus[status] = (summary.byStatus[status] ?? 0) + 1;\n    // Compare via the widened `string` type so this module compiles\n    // both before and after PR 4/6 lands `\"forgotten\"` in MemoryStatus.\n    if (status === \"forgotten\") summary.forgottenCount += 1;\n    const cat = m.frontmatter.category ?? \"(uncategorized)\";\n    summary.byCategory[cat] = (summary.byCategory[cat] ?? 0) + 1;\n  }\n  return summary;\n}\n\nexport async function explainTierForMemory(\n  storage: StorageManager,\n  id: string,\n  config: PluginConfig,\n): Promise<TierExplainResult> {\n  const trimmed = typeof id === \"string\" ? id.trim() : \"\";\n  if (trimmed.length === 0) {\n    throw new Error(\"tier explain: memory id is required and must be non-empty\");\n  }\n  const all = await readTierVisibleMemories(storage);\n  const entry = all.find(({ memory: m }) => m.frontmatter.id === trimmed);\n  if (!entry) {\n    throw new Error(`tier explain: memory not found: ${trimmed}`);\n  }\n  const { memory, tier: currentTier } = entry;\n  const now = new Date();\n  const valueInputs = computeLifecycleValueInputs(memory, now);\n  const valueScore = computeTierValueScore(memory, now);\n  const policy = await tierRoutingPolicyFromConfig(config);\n  const decision = decideTierTransition(memory, currentTier, policy, now);\n  const fm = memory.frontmatter as unknown as Record<string, unknown>;\n  return {\n    id: trimmed,\n    path: memory.path,\n    currentTier,\n    status: typeof fm.status === \"string\" ? (fm.status as string) : \"active\",\n    category: typeof fm.category === \"string\" ? (fm.category as string) : \"\",\n    valueScore,\n    decision,\n    signals: {\n      confidence: valueInputs.confidence,\n      accessCount:\n        typeof fm.accessCount === \"number\" ? (fm.accessCount as number) : 0,\n      lastAccessed:\n        typeof fm.lastAccessed === \"string\" ? (fm.lastAccessed as string) : null,\n      created: typeof fm.created === \"string\" ? (fm.created as string) : \"\",\n      updated: typeof fm.updated === \"string\" ? (fm.updated as string) : \"\",\n      importance: valueInputs.importance,\n      feedback: valueInputs.feedback,\n    },\n  };\n}\n\n/**\n * Render a TierSummary as plain text for `remnic tier list` text mode.\n * Pure formatter — exposed so future surfaces (HTTP, MCP) can reuse.\n */\nexport function formatTierSummaryText(summary: TierSummary): string {\n  const lines: string[] = [];\n  lines.push(\"=== Memory Tier Distribution ===\");\n  lines.push(`Total memories: ${summary.total}`);\n  lines.push(\"\");\n  lines.push(\"Tier:\");\n  lines.push(`  hot:  ${summary.byTier.hot}`);\n  lines.push(`  cold: ${summary.byTier.cold}`);\n  lines.push(\"\");\n  lines.push(\"Status:\");\n  const statusEntries = Object.entries(summary.byStatus).sort(\n    (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),\n  );\n  for (const [status, count] of statusEntries) {\n    lines.push(`  ${status}: ${count}`);\n  }\n  lines.push(\"\");\n  lines.push(\"Top categories:\");\n  const categoryEntries = Object.entries(summary.byCategory)\n    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))\n    .slice(0, 8);\n  for (const [cat, count] of categoryEntries) {\n    lines.push(`  ${cat}: ${count}`);\n  }\n  return lines.join(\"\\n\");\n}\n\n/**\n * Render a TierExplainResult as plain text for `remnic tier explain`.\n */\nexport function formatTierExplainText(explain: TierExplainResult): string {\n  const lines: string[] = [];\n  lines.push(`=== Tier Explain: ${explain.id} ===`);\n  lines.push(`path:          ${explain.path}`);\n  lines.push(`current tier:  ${explain.currentTier}`);\n  lines.push(`status:        ${explain.status}`);\n  lines.push(`category:      ${explain.category}`);\n  lines.push(`value score:   ${explain.valueScore.toFixed(3)}`);\n  lines.push(\"\");\n  lines.push(\"Tier-transition decision:\");\n  lines.push(`  next tier: ${explain.decision.nextTier}`);\n  lines.push(`  changed:   ${explain.decision.changed}`);\n  lines.push(`  reason:    ${explain.decision.reason}`);\n  lines.push(\"\");\n  lines.push(\"Signals:\");\n  lines.push(`  confidence:   ${explain.signals.confidence}`);\n  lines.push(`  accessCount:  ${explain.signals.accessCount}`);\n  lines.push(`  lastAccessed: ${explain.signals.lastAccessed ?? \"(never)\"}`);\n  lines.push(`  created:      ${explain.signals.created}`);\n  lines.push(`  updated:      ${explain.signals.updated}`);\n  lines.push(`  importance:   ${explain.signals.importance}`);\n  lines.push(`  feedback:     ${explain.signals.feedback}`);\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}