dsh-experience 1.0.5 → 1.0.14

package/lib/capture.js

@@ -39,6 +39,7 @@ export const DEFAULT_CONFIG = {
   stepsJaccard: 0.7,
   allowAutoVerified: false,
   minEffectiveSteps: 2,
+  recallThreshold: 0.15,
 }
 
 export function redact(text) {
@@ -197,7 +198,58 @@ export function effectiveSteps(calls) {
   return count
 }
 
-const ACTION_VERBS = /^(新增|写|跑通|修改|修复|重构|实现|添加|删除|更新|重命名|移动|替换|补|加|改为)/
+const ACTION_VERBS = /^(新增|写|跑通|跑|执行|修改|修复|重构|实现|添加|删除|更新|重命名|移动|替换|补|加|改为)/
+
+/**
+ * Executions worth repeating. A run recipe is "how to invoke this thing", so a
+ * bare mkdir / dir listing / file read never counts: those describe discovery,
+ * not the recipe.
+ */
+export function runSteps(calls) {
+  const kept = []
+  for (const call of calls || []) {
+    if (!call || !call.ok) continue
+    if (classify(call).kind !== 'run') continue
+    if (stepPriority(call) < 2) continue
+    if (isNoiseStep(stepLabel(call))) continue
+    kept.push(call)
+  }
+  return kept
+}
+
+/** The program a run call actually launched: "& \"C:\\...\\node.exe\" x.mjs" -> node. */
+export function commandHeads(calls) {
+  const heads = []
+  for (const call of calls || []) {
+    if (!call || !call.ok) continue
+    if (classify(call).kind !== 'run') continue
+    if (isNoiseStep(stepLabel(call))) continue
+    const raw = firstString(call && (call.hint || call.argsHint || call.args)) || ''
+    const lead = raw.trim().replace(/^&\s*/, '')
+    const quoted = lead.match(/^("[^"]+"|'[^']+'|\S+)/)
+    const program = quoted ? quoted[0].replace(/^["']|["']$/g, '') : ''
+    const base = program.split(/[\\/]+/).filter(Boolean).pop() || ''
+    const head = base.replace(/\.exe$/i, '').toLowerCase()
+    if (head && /^[a-z][a-z0-9_.-]*$/.test(head) && !/^[a-z]:$/.test(head)) heads.push(head)
+  }
+  return [...new Set(heads)].sort()
+}
+
+/** The script a run recipe executes, as a bare name: "run build.mjs" -> build. */
+export function runArtifactName(calls) {
+  for (const call of calls || []) {
+    if (!call || !call.ok) continue
+    if (classify(call).kind !== 'run') continue
+    const raw = firstString(call && (call.hint || call.argsHint || call.args)) || ''
+    const hit = raw.match(/[A-Za-z0-9_][A-Za-z0-9_.-]*\.(?:mjs|cjs|js|py|go|rs|sh|ps1|java)\b/i)
+    if (!hit) continue
+    const base = hit[0].split(/[\\/]/).pop()
+    return base.replace(/\.[^.]+$/, '')
+  }
+  return ''
+}
+
+
 
 /** The object of a title must name a concrete artifact, not only <placeholders>. */
 export function actionableTitle(title) {
@@ -219,15 +271,19 @@ export function actionableTitle(title) {
  * G7 — refuses captures whose steps or title are not a reusable recipe.
  * Runs after the G1..G6 chain; the caller writes trace.skipReason = reason.
  */
-export function gateStepQuality(trace, record, config) {
+export function gateStepQuality(trace, record, config, intent) {
   const cfg = { ...DEFAULT_CONFIG, ...(config || {}) }
   const calls = (trace && trace.calls) || []
-  const effective = effectiveSteps(calls)
+  // Two scales: a change is judged by its write/test steps, an invocation
+  // recipe by its repeatable executions. mkdir/read never enter either count.
+  const effective = intent === 'run' ? runSteps(calls).length : effectiveSteps(calls)
   if (effective < cfg.minEffectiveSteps) {
+    const what = intent === 'run' ? '可复用执行（建目录/读文件不计）' : '（只有写操作与测试执行算核心步骤）'
     return {
       ok: false,
-      reason: `G7: 有效步骤 ${effective} < ${cfg.minEffectiveSteps}（只有写操作与测试执行算核心步骤）`,
+      reason: `G7: 有效步骤 ${effective} < ${cfg.minEffectiveSteps}${intent === 'run' ? ' 次' : ''}${what}`,
       effective,
+      runOnly: intent === 'run',
     }
   }
   const title = String((record && record.title) || '')
@@ -261,6 +317,46 @@ export function summarizeCalls(calls) {
  * A second run that only re-reads and re-runs the tests has the same fingerprint
  * as the first run that scaffolded everything — that is the real "same task".
  */
+const EXT_KIND = {
+  code: ['js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'py', 'go', 'rs', 'java', 'cs', 'rb', 'php', 'sh', 'ps1', 'cmd', 'bat'],
+  image: ['png', 'jpg', 'jpeg', 'webp', 'gif', 'bmp', 'svg', 'tif', 'tiff', 'ico', 'heic'],
+  doc: ['md', 'txt', 'pdf', 'docx', 'doc', 'pptx', 'xlsx', 'csv', 'html', 'css', 'json', 'yml', 'yaml'],
+  binary: ['zip', 'gz', 'tgz', 'exe', 'dll', 'whl', 'jar'],
+}
+
+const KIND_BY_EXT = (() => {
+  const map = new Map()
+  for (const [kind, exts] of Object.entries(EXT_KIND)) for (const ext of exts) map.set(ext, kind)
+  return map
+})()
+
+export function artifactKindOf(target) {
+  const name = String(target || '').toLowerCase()
+  const match = name.match(/\.([a-z0-9]+)$/)
+  if (!match) return ''
+  return KIND_BY_EXT.get(match[1]) || ''
+}
+
+export function artifactKindsOf(targets) {
+  const kinds = new Set()
+  for (const target of targets || []) {
+    const kind = artifactKindOf(target)
+    if (kind) kinds.add(kind)
+  }
+  return [...kinds].sort()
+}
+
+/**
+ * Do these two runs write fundamentally different kinds of artifact?
+ * Only says "conflict" when both sides have evidence and the sets are disjoint.
+ */
+export function artifactTypesConflict(left, right) {
+  const a = (left && left.fingerprint && left.fingerprint.kinds) || []
+  const b = (right && right.fingerprint && right.fingerprint.kinds) || []
+  if (!a.length || !b.length) return false
+  return !a.some((kind) => b.includes(kind))
+}
+
 export function outcomeFingerprint(calls) {
   const list = calls || []
   const artifactOf = (call) => {
@@ -276,9 +372,12 @@ export function outcomeFingerprint(calls) {
   // A run that failed and then went green still ends green; the failure itself is
   // captured as a reverse example, not as a reason to refuse the merge.
   const green = testCalls.length > 0 && testCalls[testCalls.length - 1].ok === true
-  const artifacts = (writes.length ? writes : reads).filter(isCode)
+  const allArtifacts = writes.length ? writes : reads
+  const artifacts = allArtifacts.filter(isCode)
   return {
     targets: [...new Set(artifacts)].sort(),
+    commands: commandHeads(list),
+    kinds: artifactKindsOf(allArtifacts),
     tests: [...new Set(tests)].sort(),
     green,
     verificationOnly: writes.length === 0,
@@ -290,6 +389,8 @@ export function fingerprintsMatch(left, right) {
   const a = left && left.fingerprint
   const b = right && right.fingerprint
   if (!a || !b || !a.green || !b.green) return false
+  // Same name, different artifact type is not the same outcome.
+  if (artifactTypesConflict(left, right)) return false
   const have = new Set(a.targets || [])
   const want = new Set(b.targets || [])
   if (!have.size || !want.size) return false
@@ -375,7 +476,7 @@ export function inferTaskType(calls, cwd) {
   return 'workspace/general'
 }
 
-export function shouldCapture(trace, counts, config) {
+export function shouldCapture(trace, counts, config, intent) {
   const cfg = { ...DEFAULT_CONFIG, ...(config || {}) }
   const calls = (trace && trace.calls) || []
   const successes = calls.filter((call) => call && call.ok)
@@ -394,7 +495,11 @@ export function shouldCapture(trace, counts, config) {
   const tests = successes.filter((call) => isTestCall(call))
   const testFailures = calls.filter((call) => call && !call.ok && isTestCall(call))
   const verifiedGreen = tests.length > 0 && testFailures.length === 0
-  if (!writes.length && !recoveries.length && !verifiedGreen) {
+  // A run recipe is legitimate evidence on its own: nobody wrote anything, but
+  // the execution was repeated and is worth replaying.
+  const executions = intent === 'run' ? runSteps(calls) : []
+  const runOnly = intent === 'run' && !writes.length && !recoveries.length && !verifiedGreen
+  if (!writes.length && !recoveries.length && !verifiedGreen && !(runOnly && executions.length >= 2)) {
     return { ok: false, reason: 'G3: 无成功写操作、无失败后成功，且不是全绿验证轨迹' }
   }
 
@@ -404,7 +509,14 @@ export function shouldCapture(trace, counts, config) {
   if ((counts && counts.autoTotal) >= cfg.libraryLimit) {
     return { ok: false, reason: `G5: 自动经验库已达上限 ${cfg.libraryLimit}` }
   }
-  return { ok: true, writes, recoveries, verificationOnly: !writes.length && !recoveries.length }
+  return {
+    ok: true,
+    writes,
+    recoveries,
+    runOnly,
+    executions: executions.length,
+    verificationOnly: !writes.length && !recoveries.length,
+  }
 }
 
 function verbsOf(taskType) {
@@ -423,7 +535,12 @@ export function workspaceName(cwd) {
 
 const GENERIC_DIRS = new Set([
   'users', 'home', 'desktop', 'documents', 'downloads', 'src', 'test', 'tests',
-  'lib', 'node_modules', 'bin', 'tmp', 'temp', 'app', 'apps', 'workspace', 'workspaces',
+  'lib', 'node_modules', 'bin', 'tmp', 'temp', 'app', 'apps', 'workspace',
+  'workspaces',
+  // Tool-chain directories: every recipe on this machine touches them, so they
+  // say nothing about *which project* a record belongs to.
+  'node', 'python', 'python3', 'npm', 'pnpm', 'npx', 'yarn', 'git', 'pwsh',
+  'deno', 'bun', 'runtime', 'runtimes', 'dependencies', 'dsh', 'windows',
 ])
 
 /**
@@ -481,9 +598,14 @@ export function scopeOf(record) {
 }
 
 /** Two records describe different targets when both name a project dir and the names disagree. */
+/** Scope tokens that actually name a project, not the tool-chain around it. */
+export function projectScope(record) {
+  return scopeOf(record).filter((item) => item.length >= 2 && !GENERIC_DIRS.has(item))
+}
+
 export function scopeConflicts(existing, draft) {
-  const left = scopeOf(existing)
-  const right = scopeOf(draft)
+  const left = projectScope(existing)
+  const right = projectScope(draft)
   if (!left.length || !right.length) return false
   return !left.some((item) => right.includes(item))
 }
@@ -505,14 +627,29 @@ export function buildCandidate(trace, info, config) {
   const writes = calls.filter((call) => call && call.ok && classify(call).kind === 'write')
   const runs = calls.filter((call) => call && call.ok && classify(call).kind === 'run')
 
+  const runOnly = Boolean(info && info.runOnly) || (!writes.length && runs.length > 0)
   const primary = writes.length ? classify(writes[0]).target : runs.length ? classify(runs[0]).target : ''
+  const scriptName = runOnly ? runArtifactName(calls) : ''
   const verb = writes.length ? '写' : '跑通'
   // Prefer a concrete artifact name (raw basename, before path normalization):
   // "<path>/<name>.js" cannot name what was produced, "slugify.js" can.
   const named = writes
     .map((call) => artifactName(call))
     .find((name) => /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/.test(name) && /[A-Za-z0-9]{2,}/.test(name))
-  const title = clip(named ? `新增 ${named}` : primary ? `${verb} ${primary}` : verbsOf(taskType), 110)
+  const title = clip(
+    runOnly
+      ? scriptName
+        ? `跑 ${scriptName}`
+        : primary
+          ? `跑 ${primary}`
+          : verbsOf(taskType)
+      : named
+        ? `新增 ${named}`
+        : primary
+          ? `${verb} ${primary}`
+          : verbsOf(taskType),
+    110,
+  )
   const place = workspaceName(info && info.cwd)
   const when = clip(place ? `在 ${place} 里 ${verbsOf(taskType)}` : `当需要${verbsOf(taskType)}时`, 160)
   const keywords = [...new Set([taskType, ...steps.map((step) => step.split(' ')[1] || '').filter(Boolean)])]

package/lib/decay.js

@@ -127,7 +127,7 @@ export function selectEvictions(records, now = Date.now(), config = {}) {
     return { ...base, triggered: false, evictions: [], reason: `未达容量阈值 ${threshold}（当前 ${list.length}）` }
   }
   const eligible = list
-    .filter((record) => record && record.status !== 'verified' && !isPinned(record))
+    .filter((record) => record && record.status !== 'verified' && record.status !== 'rejected' && !isPinned(record))
     .map((record) => ({ record, info: stateOf(record, now, config) }))
     .filter((entry) => entry.info.dormant)
     .sort((left, right) => left.info.rank - right.info.rank)
@@ -178,9 +178,13 @@ export function decayLine(record, now = Date.now(), config = {}) {
 
 export function renderDecayReport(store, now = Date.now(), config = {}) {
   const records = Array.isArray(store && store.experiences) ? store.experiences : []
-  const proposal = selectEvictions(records, now, config)
+  // Rejected records are kept as an audit trail: they cannot be recalled, merged
+  // or evicted, so counting them would only distort the capacity numbers.
+  const hiddenRejected = records.filter((record) => record && record.status === 'rejected').length
+  const live = records.filter((record) => record && record.status !== 'rejected')
+  const proposal = selectEvictions(live, now, config)
   const counts = { active: 0, dormant: 0, pinned: 0 }
-  const sorted = records
+  const sorted = live
     .map((record) => ({ record, info: stateOf(record, now, config) }))
     .sort((left, right) => {
       if (left.info.pinned !== right.info.pinned) return left.info.pinned ? 1 : -1
@@ -193,7 +197,8 @@ export function renderDecayReport(store, now = Date.now(), config = {}) {
   const eligible = new Set(proposal.evictions.map((item) => item.id))
   const top = sorted.filter((entry) => !entry.info.pinned).slice(0, 5)
   const lines = [
-    `[M3.3 衰减报告] 库 ${records.length} 条 · active ${counts.active} / dormant ${counts.dormant} / pinned ${counts.pinned}`,
+    `[M3.3 衰减报告] 库 ${live.length} 条 · active ${counts.active} / dormant ${counts.dormant} / pinned ${counts.pinned}`,
+    ...(hiddenRejected ? [`已排除 ${hiddenRejected} 条 rejected（审计留档，不参与排序与容量；\/memory list --all 查看）`] : []),
     `容量: ${proposal.count}/${proposal.libraryLimit}（阈值 ${proposal.threshold} · 比例 ${num(config.capacityRatio, DECAY_DEFAULTS.capacityRatio)}）· ${proposal.triggered ? '已达阈值' : '未达阈值'}`,
     proposal.triggered
       ? `建议归档 ${proposal.evictions.length} 条（最多 ${num(config.evictBatch, DECAY_DEFAULTS.evictBatch)} 条/次，按 rank 升序）:`

package/lib/recall.js

@@ -0,0 +1,220 @@
+// Retrieval scoring: lexical tokens + a small hand-written feature layer.
+//
+// Why this exists: a task description and a stored recipe often share *meaning*
+// while sharing almost no words ("跑一个会踩坑的 .mjs 脚本，node 报错" vs
+// "pwsh / node.exe / load_workspace_dependencies"). Pure lexical coverage then
+// scores near zero and the recipe is never recalled.
+//
+// Two mechanisms, both synchronous and dependency-free:
+//   1. stop words — colloquial fillers ("随便", "故意", "测试场景") must not dilute coverage
+//   2. features   — canonical buckets ("#node", "#error", "#shell") that merge synonyms
+//
+// Features are derived from the raw text *before* stop-word removal, so a task
+// that explicitly says "测试" still produces "#test" even though "测试" is dropped
+// as a token.
+
+export const STOP_WORDS = new Set([
+  // function words
+  '的', '了', '和', '与', '在', '是', '把', '并', '就', '还', '也', '有', '用', '要', '中',
+  '这个', '那个', '一个', '一下', '我们', '你们', '可以', '需要', '请', '帮', '让我', '给我',
+  '然后', '现在', '已经', '还是', '就是', '不要', '不用', '没有', '什么', '怎么', '这样',
+  '那样', '但是', '因为', '所以', '如果', '或者', '以及', '并且', '而且', '之后', '之前',
+  // colloquial fillers that carry no retrieval signal
+  '随便', '随便写', '故意', '特意', '场景', '测试场景', '试试', '尝试', '看看', '跑一个',
+  '随便跑', '简单', '复杂', '大概', '可能', '应该', '一会', '等下',
+  // english
+  'the', 'a', 'an', 'and', 'or', 'to', 'of', 'in', 'on', 'for', 'with', 'is', 'are', 'be',
+  'it', 'this', 'that', 'then', 'use', 'run', 'can', 'will', 'should', 'just', 'some',
+])
+
+// Canonical bucket -> patterns that should activate it. Keep this list small and
+// conservative: a bucket that fires on everything destroys ranking signal.
+export const FEATURES = {
+  node: [/node(?:\.exe)?/, /\bmjs\b/, /\.mjs\b/, /\besm\b/, /内置\s*node/, /nodejs/],
+  shell: [/pwsh/, /powershell/, /\bshell\b/, /命令行/, /终端/, /cmd\b/],
+  error: [/报错/, /错误/, /\berror\b/, /exception/, /抛错/, /失败/, /\bfail/, /stack/],
+  module: [/模块/, /\bmodule\b/, /import\s/, /require\(/, /导出/, /export\s/],
+  test: [/测试/, /\btest\b/, /用例/, /\bspec\b/, /断言/, /assert/],
+  file: [/文件/, /脚本/, /\bfile\b/, /\.js\b/, /\.mjs\b/, /\.json\b/],
+  path: [/路径/, /目录/, /\bpath\b/, /folder/, /文件夹/],
+  python: [/python/, /\.py\b/, /pip\b/],
+  git: [/\bgit\b/, /提交/, /分支/, /仓库/, /commit/],
+  // Intent buckets: "run this script" and "add a function" are different tasks
+  // even when they mention the same files. Without these, a noisy description
+  // matches whichever record happens to share more generic nouns.
+  run: [/跑/, /运行/, /执行/, /\brun\b/, /execute/, /启动/],
+  write: [/新增/, /添加/, /创建/, /写入/, /\bwrite\b/, /\bcreate\b/, /实现/, /修改/, /重构/, /补/],
+  debug: [/排查/, /踩坑/, /修复/, /定位/, /\bdebug\b/, /为什么/, /失败原因/],
+}
+
+const FEATURE_PREFIX = '#'
+
+export function features(text) {
+  const source = String(text || '').toLowerCase()
+  const out = new Set()
+  for (const [name, patterns] of Object.entries(FEATURES)) {
+    if (patterns.some((re) => re.test(source))) out.add(FEATURE_PREFIX + name)
+  }
+  return out
+}
+
+export function tokenize(text) {
+  const out = new Set()
+  const source = String(text || '').toLowerCase()
+  for (const match of source.matchAll(/[a-z0-9_][a-z0-9_.\-/]*/g)) {
+    const token = match[0]
+    if (token.length >= 2 && !STOP_WORDS.has(token)) {
+      out.add(token)
+      // Index the basename too, so "truncate.test.mjs" matches "test/truncate.test.mjs".
+      const slash = token.lastIndexOf('/')
+      if (slash > 0 && token.length - slash > 2) out.add(token.slice(slash + 1))
+    }
+  }
+  const cjk = source.replace(/[^\u4e00-\u9fff]+/g, ' ')
+  for (const chunk of cjk.split(' ')) {
+    for (let i = 0; i + 1 < chunk.length; i++) {
+      const bigram = chunk.slice(i, i + 2)
+      if (!STOP_WORDS.has(bigram)) out.add(bigram)
+    }
+  }
+  return out
+}
+
+/** Tokens + feature buckets for one text (a query or a stored profile). */
+export function expand(text) {
+  const out = tokenize(text)
+  for (const feature of features(text)) out.add(feature)
+  return out
+}
+
+/** The searchable profile of a stored experience. */
+export function profileText(experience) {
+  if (!experience) return ''
+  // Pitfalls and counter-examples are usually the only place a record names the
+  // concrete failure ("MODULE_NOT_FOUND", "CommandNotFoundException"). Scoring
+  // without them ranks "add a file" chores above the actual troubleshooting note.
+  return [
+    experience.title,
+    experience.taskType,
+    experience.when,
+    (experience.keywords || []).join(' '),
+    (experience.pitfalls || []).join(' '),
+    (experience.reverse_examples || []).join(' '),
+  ].filter(Boolean).join(' ')
+}
+
+const round = (value) => Math.round(value * 1000) / 1000
+
+/**
+ * Document frequencies across the whole library. Rare tokens ("node.exe",
+ * "MODULE_NOT_FOUND") discriminate; common ones ("报错", "模块") must not.
+ * Without this, a noisy task description lifts every record at once.
+ */
+/**
+ * Which kind of task is this: running something, or writing something?
+ * Empty means "cannot tell" and never vetoes anything.
+ */
+export function intentOf(experienceOrText) {
+  const text =
+    typeof experienceOrText === 'string' ? experienceOrText : profileText(experienceOrText)
+  const found = features(text)
+  const run = found.has('#run')
+  const write = found.has('#write')
+  if (run && !write) return 'run'
+  if (write && !run) return 'write'
+  return ''
+}
+
+/**
+ * "run the image pipeline" and "add a helper function" are different tasks even
+ * when they share every noun; only verdicts with evidence on both sides count.
+ */
+export function intentConflict(left, right) {
+  const a = intentOf(left)
+  const b = intentOf(right)
+  return Boolean(a && b && a !== b)
+}
+
+export function corpus(experiences) {
+  const df = new Map()
+  let n = 0
+  for (const experience of experiences || []) {
+    n += 1
+    for (const token of expand(profileText(experience))) df.set(token, (df.get(token) || 0) + 1)
+  }
+  return { n, df }
+}
+
+function idf(token, c) {
+  if (!c || !c.n) return 1
+  const d = c.df.get(token) || 0
+  return Math.log(1 + (c.n - d + 0.5) / (d + 0.5))
+}
+
+/** Feature buckets are hand-made and rare by construction: worth a little more than a plain token. */
+const FEATURE_WEIGHTS = {
+  '#error': 3,
+  '#node': 2.6,
+  '#module': 2.2,
+  '#shell': 2,
+  '#debug': 2,
+  '#run': 1.8,
+  '#write': 1.8,
+  '#test': 1.4,
+  '#file': 1.2,
+  '#path': 1.2,
+  '#python': 1.4,
+  '#git': 1.4,
+}
+
+const featureWeight = (token) =>
+  token.startsWith(FEATURE_PREFIX) ? FEATURE_WEIGHTS[token] || 1.4 : 1
+
+// A shared failure signal is worth more than any amount of shared nouns: the
+// user is asking for help with the same class of breakage.
+const CRITICAL_FEATURES = ['#error', '#node', '#module']
+
+/** CJK bigrams are noisy: 脚本 / 模块 / 报错 collide across unrelated tasks. */
+const scriptWeight = (token) => (/^[\u4e00-\u9fff]+$/.test(token) ? 0.45 : 1)
+
+/**
+ * Score a stored profile against an expanded query set.
+ * 0.75 * idf-weighted share of the query the profile covers
+ * 0.25 * unweighted share of the profile the query covers
+ * Both terms are bounded, so the result is always within [0, 1].
+ */
+export function score(profile, queryTokens, c) {
+  const expTokens = expand(profile)
+  if (!queryTokens || !queryTokens.size || !expTokens.size) return 0
+  let weightSum = 0
+  let weightHit = 0
+  for (const token of queryTokens) {
+    const weight = idf(token, c) * featureWeight(token) * scriptWeight(token)
+    weightSum += weight
+    if (expTokens.has(token)) weightHit += weight
+  }
+  const queryCoverage = weightSum ? weightHit / weightSum : 0
+  let expHits = 0
+  for (const token of expTokens) if (queryTokens.has(token)) expHits++
+  const expCoverage = expHits / expTokens.size
+  let critical = 0
+  for (const feature of CRITICAL_FEATURES) {
+    if (queryTokens.has(feature) && expTokens.has(feature)) critical += 1
+  }
+  const criticalBonus = critical ? 0.08 * critical : 0
+  return round(Math.min(1, 0.75 * queryCoverage + 0.25 * expCoverage + criticalBonus))
+}
+
+/** Human-readable breakdown for `/memory why` and `experience_debug`. */
+export function explain(profile, queryText) {
+  const queryTokens = expand(queryText)
+  const expTokens = expand(profile)
+  const shared = [...queryTokens].filter((t) => expTokens.has(t))
+  return {
+    score: score(profile, queryTokens),
+    queryTokens: [...queryTokens].slice(0, 40),
+    expTokens: [...expTokens].slice(0, 40),
+    shared: shared.slice(0, 20),
+    features: shared.filter((t) => t.startsWith(FEATURE_PREFIX)),
+  }
+}

package/lib/store.js

@@ -0,0 +1,66 @@
+// Durable store I/O, split out of index.js so the reload path is testable.
+//
+// The bug this exists to prevent: `loadStore()` used to rebuild only
+// {version,nextId,nextInjectionId,experiences,injections,turns}, so every
+// reload dropped `archive` and `evictions` — and the next persist() rewrote
+// them out of the file, silently losing archived records.
+
+import fs from 'node:fs'
+
+export function emptyStore() {
+  return {
+    version: 1,
+    nextId: 1,
+    nextInjectionId: 1,
+    experiences: [],
+    injections: [],
+    turns: [],
+    archive: [],
+    evictions: [],
+  }
+}
+
+const array = (value) => (Array.isArray(value) ? value : [])
+
+/**
+ * Rebuild a store from parsed JSON without dropping fields.
+ * Unknown extra fields are preserved verbatim on purpose: a plugin upgrade that
+ * adds a table must not lose it when an older build reloads the file.
+ */
+export function normalizeStore(parsed) {
+  if (!parsed || typeof parsed !== 'object') throw new Error('not an object')
+  const known = {
+    version: Math.max(2, Number(parsed.version || 1)),
+    nextId: Number(parsed.nextId) || 1,
+    nextInjectionId: Number(parsed.nextInjectionId) || 1,
+    experiences: array(parsed.experiences),
+    injections: array(parsed.injections),
+    turns: array(parsed.turns),
+    archive: array(parsed.archive),
+    evictions: array(parsed.evictions),
+  }
+  return { ...parsed, ...known }
+}
+
+/**
+ * Read a store file.
+ * @returns {{ store: object, error?: Error, missing?: boolean }}
+ */
+export function readStore(file) {
+  try {
+    const raw = fs.readFileSync(file, 'utf8')
+    return { store: normalizeStore(JSON.parse(raw)) }
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { store: emptyStore(), missing: true }
+    return { store: emptyStore(), error }
+  }
+}
+
+/** Atomic-ish write: temp file + rename, UTF-8, no BOM. */
+export function writeStore(file, store) {
+  const dir = file.slice(0, Math.max(file.lastIndexOf('/'), file.lastIndexOf('\\')))
+  if (dir) fs.mkdirSync(dir, { recursive: true })
+  const tmp = `${file}.tmp`
+  fs.writeFileSync(tmp, JSON.stringify(store, null, 2), 'utf8')
+  fs.renameSync(tmp, file)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-experience",
-  "version": "1.0.5",
+  "version": "1.0.14",
   "private": false,
   "publishConfig": {
     "access": "public"