dsh-memory-gate 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.5.0 - 2026-08-15
+
+- Authority: weak lexical matches demote from `use` to `verify` (relevance
+  0.12–0.5, non-capsule). The gate no longer confidently injects a memory
+  that only weakly overlaps the query — it labels it as an unverified hint.
+- Fix capsule composition: a trusted global preference/constraint that also
+  matches lexically now keeps its capsule identity (unconditional use) instead
+  of being downgraded to a weak trigger match.
+- Backtest: the three partial-overlap hard cases now resolve as `verify`
+  (weak matches); one synonym-coverage gap (改表 vs 修改 schema) is recorded
+  for follow-up. 30/30 clear scenarios pass, F1 = 1.000.
+
+## 0.4.0 - 2026-08-15
+
+- Ship the evaluation data foundation (repo + npm tarball):
+  - Decision-layer backtest: 30 synthetic scenarios (all five claim kinds,
+    verify branches, quarantine, pollution, cross-scope, paraphrases) with a
+    four-leg comparison (gate / top-3 / random / shadow) and a clear-vs-hard
+    split; a hard case records the known partial-overlap over-trigger.
+  - Result-layer measurement: adoption / token-cost / effect scoring.
+  - Trajectory observer: parse DSH session logs (jsonl/zstd) and measure
+    per-turn injection adoption and effect.
+  - Release gate: `prepublishOnly` runs `check + test + backtest` before any
+    publish and aborts on clear-case regressions.
+- No runtime behavior change to the plugin itself.
+
 ## 0.3.2 - 2026-08-14
 
 - Docs-only release: reposition from storage ("SQLite + FTS5 memory") to

package/README.md

@@ -141,10 +141,17 @@ dsh plugin --profile web remove dsh-memory-gate
 
 ```bash
 npm install
-npm run check
+npm run check          # 类型检查 + 构建
+npm test               # 21 个单元/集成测试
+npm run backtest       # 决策层回测：30 场景四腿对照（gate/top-3/random/shadow）
+npm run result         # 结果层：注入采纳度 / 成本 / 效果分
+npm run observe <log>  # 轨迹观测：对真实 session 日志量采纳度
 npm pack --dry-run
 ```
 
+发布门：`prepublishOnly` 会在任何 `npm publish` 前自动跑 `check + test +
+backtest`，回测清晰场景不过关即中止发布。
+
 发布前的三轮基准中位数（Node.js 22.22.1，1001 条合成记忆，每轮 300
 次查询）：WSL 磁盘上的触发检索 p95 `5.343ms`，包含 CBDC 决策和 SQLite
 审计的完整召回 p95 `11.151ms`，三轮最大观测 p95 `11.663ms`。基准不会

package/backtest/capture.mjs

@@ -0,0 +1,62 @@
+/**
+ * 真实决策轨迹捕获 —— 把审计库（cbdc.sqlite）里已发生的「召回→决策→注入」
+ * 导出成样本（schema v0），供结果层回测（P1）与人工抽查使用。
+ *
+ * 注意：出于隐私设计，retrieval_runs 只存 query_hash 与词项，不存查询原文，
+ * 因此捕获样本的 query 是词项列表而非原文。
+ *
+ * 用法：node backtest/capture.mjs [path-to.sqlite] [outfile]
+ */
+import { readFileSync } from 'node:fs'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { DatabaseSync } from 'node:sqlite'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const dbPath = process.argv[2] ?? '/home/ubuntu/.dsh/memory/cbdc.sqlite'
+const outFile = process.argv[3] ?? join(ROOT, 'fixtures', 'captured', 'captured-latest.json')
+
+const db = new DatabaseSync(dbPath, { readOnly: true })
+try {
+  const runs = db
+    .prepare('SELECT id, query_terms_json, created_at FROM retrieval_runs ORDER BY created_at DESC LIMIT 50')
+    .all()
+
+  const samples = runs.map((run) => {
+    const decisions = db
+      .prepare(
+        `SELECT d.claim_id, d.action, d.belief_score, d.relevance_score, d.freshness_score, d.risk_score, d.reason_codes_json
+         FROM authority_decisions d WHERE d.run_id = ?`,
+      )
+      .all(run.id)
+    const injection = db
+      .prepare('SELECT claim_ids_json, mode, created_at FROM injections WHERE run_id = ? LIMIT 1')
+      .get(run.id)
+    const json = (s) => JSON.parse(s)
+    return {
+      schema: '1.0',
+      source: 'captured',
+      scenario_id: String(run.id),
+      created_at: String(run.created_at),
+      query_terms: json(run.query_terms_json),
+      decisions: decisions.map((d) => ({
+        claim_id: String(d.claim_id),
+        action: String(d.action),
+        belief: Number(d.belief_score),
+        relevance: Number(d.relevance_score),
+        freshness: Number(d.freshness_score),
+        risk: Number(d.risk_score),
+        reasons: json(d.reason_codes_json),
+      })),
+      injection: injection ? { claim_ids: json(injection.claim_ids_json), mode: String(injection.mode) } : null,
+    }
+  })
+
+  mkdirSync(dirname(outFile), { recursive: true })
+  writeFileSync(outFile, JSON.stringify(samples, null, 1) + '\n')
+  console.log(`captured ${samples.length} runs → ${outFile}`)
+  if (samples.length > 0) console.log(`sample keys: ${Object.keys(samples[0]).join(', ')}`)
+} finally {
+  db.close()
+}

package/backtest/measure.mjs

@@ -0,0 +1,43 @@
+/**
+ * 结果层测量（纯函数）—— 从「注入的 memory」与「assistant 的最终回答」算采纳度 / 成本 / 效果分。
+ *
+ * 这是 P1 轨迹观测仪的核心度量，先做成可单测的纯函数，离线、零模型调用。
+ * 局限（诚实的）：采纳度基于词项重叠，对 fact/procedure（回答会复述内容）有效；
+ * 对 preference/constraint（模型"照做"但不会复述"简洁"这个词）是弱信号，留待后续。
+ */
+import { extractTerms } from '../lib/index.js'
+
+/** 粗略双语 token 估算：CJK ~1 token/字，其余 ~1 token/4 字符。 */
+export function estimateTokens(text) {
+  const cjk = (text.match(/[\p{Script=Han}]/gu) ?? []).length
+  const other = text.replace(/[\p{Script=Han}\s]/gu, '')
+  return cjk + Math.ceil(other.length / 4)
+}
+
+/** 注入 claim 的「特有词项」：claim 词项中不在 query 词项里的那部分。 */
+export function distinctiveTerms(claimTerms, queryTerms) {
+  const query = new Set(queryTerms)
+  return claimTerms.filter((term) => !query.has(term))
+}
+
+/** 采纳度：特有词项出现在 assistant 最终回答里的比例（0~1）。 */
+export function adoptionScore(distinctive, assistantText) {
+  if (!distinctive.length) return 0
+  const tokens = new Set(extractTerms(assistantText, 500))
+  const hits = distinctive.filter((term) => tokens.has(term)).length
+  return hits / distinctive.length
+}
+
+/** 效果分：采纳 + 结果质量 − 成本惩罚，输出 [-1, +1]。 */
+export function effectScore({ adoption, quality, tokenCost, costWeight = 0.002, adoptionWeight = 0.6, qualityWeight = 0.4 }) {
+  const costPenalty = Math.min(1, tokenCost * costWeight)
+  const score = adoptionWeight * adoption + qualityWeight * quality - costPenalty
+  return Math.max(-1, Math.min(1, score))
+}
+
+/** 质量信号 0~1：有正反馈为 1、无信号 0.5、有负反馈 0（先验，待真实数据校准）。 */
+export function qualitySignal(feedback) {
+  if (feedback === 'helped') return 1
+  if (feedback === 'harmful' || feedback === 'stale' || feedback === 'conflict') return 0
+  return 0.5
+}

package/backtest/measure.test.mjs

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+
+import { adoptionScore, distinctiveTerms, effectScore, estimateTokens, qualitySignal } from '../backtest/measure.mjs'
+
+test('estimateTokens: CJK ~1/字，latin ~1/4 字符', () => {
+  assert.equal(estimateTokens('中文'), 2)
+  assert.ok(estimateTokens('abcd') >= 1)
+  assert.ok(estimateTokens('中文 abcd') >= 3)
+})
+
+test('distinctiveTerms 排除 query 词项', () => {
+  const distinctive = distinctiveTerms(['简洁', '中文', '目录'], ['简洁'])
+  assert.deepEqual(distinctive, ['中文', '目录'])
+})
+
+test('adoptionScore 度量特有词项命中比例', () => {
+  const distinctive = ['目录']
+  assert.equal(adoptionScore(distinctive, '项目代码在 /home/ubuntu/dsh 目录'), 1)
+  assert.equal(adoptionScore(distinctive, '这个我不清楚'), 0)
+  // 同义折叠在「别名令牌」层生效：claim 词项含 recall_alias_deploy，
+  // 回答里说「上线」也会折叠到同一令牌，从而命中。
+  assert.equal(adoptionScore(['recall_alias_deploy'], '上线流程是这样的'), 1)
+})
+
+test('adoptionScore 空特有词返回 0（无信号不算采纳）', () => {
+  assert.equal(adoptionScore([], '随便'), 0)
+})
+
+test('effectScore 正采纳加分、成本减分、有界', () => {
+  const good = effectScore({ adoption: 1, quality: 1, tokenCost: 0 })
+  assert.ok(good > 0.9)
+  const costly = effectScore({ adoption: 1, quality: 1, tokenCost: 2000, costWeight: 0.002 })
+  assert.ok(costly < good, '成本应拉低效果分')
+  assert.equal(effectScore({ adoption: 0, quality: 0, tokenCost: 1e9 }), -1, '有下界 -1')
+  assert.equal(effectScore({ adoption: 1, quality: 1, tokenCost: 1e9 }), 0, '满分减满成本惩罚为 0')
+})
+
+test('qualitySignal 映射反馈到质量', () => {
+  assert.equal(qualitySignal('helped'), 1)
+  assert.equal(qualitySignal('harmful'), 0)
+  assert.equal(qualitySignal(undefined), 0.5)
+})

package/backtest/observe.mjs

@@ -0,0 +1,56 @@
+/**
+ * 轨迹观测 —— 把结果层度量接到真实/合成 session 轨迹上。
+ *
+ * 对每个含注入的回合：query 词项 → 注入块特有词项 → 在 assistant 最终回答里量采纳度
+ * → 合成效果分。支持 .jsonl 与 .jsonl.zstd（经 zstd CLI 解压）。
+ *
+ * 用法：node backtest/observe.mjs <session.jsonl|session.jsonl.zstd>
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+import { extractTerms } from '../lib/index.js'
+import { adoptionScore, distinctiveTerms, effectScore, estimateTokens, qualitySignal } from './measure.mjs'
+import { observeSession, parseEvents } from './trajectory.mjs'
+
+const file = process.argv[2]
+if (!file) {
+  console.error('用法: node backtest/observe.mjs <session.jsonl|session.jsonl.zstd>')
+  process.exit(2)
+}
+
+const path = resolve(file)
+let text
+if (path.endsWith('.zstd')) {
+  text = execFileSync('zstd', ['-dc', path], { maxBuffer: 256 * 1024 * 1024 }).toString('utf8')
+} else {
+  text = readFileSync(path, 'utf8')
+}
+
+const turns = observeSession(parseEvents(text))
+const rows = []
+for (const turn of turns) {
+  if (!turn.injections.length) continue
+  const queryTerms = extractTerms(turn.query)
+  const memoryText = turn.injections.flatMap((i) => i.contents ?? [i.text]).join('\n')
+  const memoryTerms = extractTerms(memoryText, 500)
+  const distinctive = distinctiveTerms(memoryTerms, queryTerms)
+  const adoption = adoptionScore(distinctive, turn.assistantText)
+  const tokenCost = estimateTokens(memoryText)
+  const effect = effectScore({ adoption, quality: qualitySignal(undefined), tokenCost })
+  rows.push({ turn: turn.turn, claims: turn.injections.flatMap((i) => i.claimIds).length, adoption, tokenCost, effect })
+}
+
+if (!rows.length) {
+  console.log('（该轨迹中未检测到记忆注入——等 dogfood 存了记忆、有了真实注入后这里才有数据）')
+} else {
+  console.log('| 回合 | 注入条数 | 采纳度 | token 成本 | 效果分 |')
+  console.log('|---|---|---|---|---|')
+  for (const r of rows) {
+    console.log(`| #${r.turn} | ${r.claims} | ${r.adoption.toFixed(2)} | ${r.tokenCost} | ${r.effect.toFixed(2)} |`)
+  }
+  const avgAdoption = rows.reduce((s, r) => s + r.adoption, 0) / rows.length
+  const avgEffect = rows.reduce((s, r) => s + r.effect, 0) / rows.length
+  console.log(`\n注入 ${rows.length} 次；平均采纳度 ${avgAdoption.toFixed(2)}；平均效果分 ${avgEffect.toFixed(2)}`)
+}

package/backtest/result.mjs

@@ -0,0 +1,97 @@
+/**
+ * 结果层回测演示 —— 决策层只回答"该不该注入"；这里回答"注入后被用上了吗、值不值"。
+ *
+ * 对每个带 golden.assistant_answer 的场景：跑 gate → 对注入的 claim 算
+ * 特有词项 → 在 assistant 最终回答里量采纳度 → 合成为效果分。
+ * 纯离线、零模型调用（assistant_answer 是场景里写好的金标回答）。
+ *
+ * 用法：npm run result
+ */
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { MemoryRepository, MemoryService, extractTerms } from '../lib/index.js'
+import { adoptionScore, distinctiveTerms, effectScore, estimateTokens, qualitySignal } from './measure.mjs'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const FIXTURES = join(ROOT, 'fixtures', 'synthetic')
+
+const CONFIG = {
+  mode: 'assist',
+  automaticExtraction: false,
+  candidateLimit: 16,
+  capsuleLimit: 2,
+  injectionLimit: 3,
+  maxInjectionChars: 1200,
+  auditRetentionRuns: 5000,
+  minUseBelief: 0.7,
+  maxUseRisk: 0.45,
+  harmfulQuarantineThreshold: 2,
+  freshnessHalfLifeDays: 180,
+}
+
+function buildStore(scenario) {
+  const repo = new MemoryRepository(':memory:')
+  const svc = new MemoryService(repo, CONFIG)
+  const idByIndex = new Map()
+  scenario.claim_store.forEach((claim, index) => {
+    const scope = claim.scope ?? 'global'
+    const scopeKey = claim.scope_key ?? scope
+    const { claim: created } = repo.remember({
+      scope,
+      scopeKey,
+      kind: claim.kind,
+      content: claim.content,
+      origin: claim.origin ?? 'explicit',
+      ...(claim.valid_until === undefined ? {} : { validUntil: claim.valid_until }),
+    })
+    idByIndex.set(index, created.id)
+  })
+  return { repo, svc, idByIndex }
+}
+
+const scenarios = readdirSync(FIXTURES)
+  .filter((name) => name.endsWith('.json'))
+  .sort()
+  .map((name) => JSON.parse(readFileSync(join(FIXTURES, name), 'utf8')))
+  .filter((s) => s.golden?.assistant_answer && s.claim_store.length > 0)
+
+const rows = []
+for (const scenario of scenarios) {
+  const { repo, svc, idByIndex } = buildStore(scenario)
+  const retrieval = svc.retrieve({ query: scenario.query, sessionId: 'backtest', sessionScopeKey: 'backtest' })
+  const injectedIndices = retrieval.decisions.filter((d) => d.action !== 'ignore').map((d) => {
+    for (const [index, id] of idByIndex) if (id === d.claimId) return index
+    return -1
+  }).filter((i) => i >= 0)
+
+  const queryTerms = extractTerms(scenario.query)
+  const distinctive = new Set()
+  let tokenCost = 0
+  for (const index of injectedIndices) {
+    const claim = repo.getClaim(idByIndex.get(index))
+    if (!claim) continue
+    for (const term of distinctiveTerms(claim.terms, queryTerms)) distinctive.add(term)
+    tokenCost += estimateTokens(claim.content)
+  }
+
+  const adoption = adoptionScore([...distinctive], scenario.golden.assistant_answer)
+  const quality = qualitySignal(scenario.golden.feedback)
+  const effect = effectScore({ adoption, quality, tokenCost })
+  rows.push({ scenario: scenario.scenario_id, injected: injectedIndices.length, adoption, quality, tokenCost, effect })
+  repo.close()
+}
+
+console.log('| 场景 | 注入条数 | 采纳度 | 质量 | token 成本 | 效果分 |')
+console.log('|---|---|---|---|---|---|')
+for (const r of rows) {
+  console.log(`| ${r.scenario} | ${r.injected} | ${r.adoption.toFixed(2)} | ${r.quality.toFixed(1)} | ${r.tokenCost} | ${r.effect.toFixed(2)} |`)
+}
+if (rows.length) {
+  const avgAdoption = rows.reduce((s, r) => s + r.adoption, 0) / rows.length
+  const avgEffect = rows.reduce((s, r) => s + r.effect, 0) / rows.length
+  console.log(`\n平均采纳度 ${avgAdoption.toFixed(2)}，平均效果分 ${avgEffect.toFixed(2)}`)
+} else {
+  console.log('\n（没有带 assistant_answer 的场景，结果层为空）')
+}

package/backtest/run.mjs

@@ -0,0 +1,212 @@
+/**
+ * 决策层回测引擎 —— gate 的「因子回测」。
+ *
+ * 四条腿对照同一批合成场景：
+ *   gate   真实 retrieve → CBDC 决策（use|verify 记为注入，ignore 记为不注入）
+ *   top-3  无门控基线：词法检索 top-3 全注入（capsule 不参与）
+ *   random 随机注入（固定种子，可复现）
+ *   shadow 零注入基线
+ *
+ * 两层评分：
+ *   - 注入集合 vs 金标（claim 级精确率/召回率/F1，四腿对照）
+ *   - gate 的动作（use/verify/ignore）vs 金标 expected_action（仅 gate 腿）
+ *
+ * 硬案例（hard=true）与清晰案例分开计分：硬案例记录已知短板、不阻塞发版；
+ * CI 门只要求清晰场景全对（clear F1 == 1.0）。
+ *
+ * 用法：npm run backtest
+ */
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { MemoryRepository, MemoryService } from '../lib/index.js'
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const FIXTURES = join(ROOT, 'fixtures', 'synthetic')
+const REPORTS = join(ROOT, 'reports')
+const INJECTION_LIMIT = 3
+
+const CONFIG = {
+  mode: 'assist',
+  automaticExtraction: false,
+  candidateLimit: 16,
+  capsuleLimit: 2,
+  injectionLimit: INJECTION_LIMIT,
+  maxInjectionChars: 1200,
+  auditRetentionRuns: 5000,
+  minUseBelief: 0.7,
+  maxUseRisk: 0.45,
+  harmfulQuarantineThreshold: 2,
+  freshnessHalfLifeDays: 180,
+}
+
+const loadScenarios = () =>
+  readdirSync(FIXTURES)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => JSON.parse(readFileSync(join(FIXTURES, name), 'utf8')))
+
+const seededRandom = (seed) => {
+  let state = seed >>> 0
+  return () => {
+    state = (state * 1664525 + 1013904223) >>> 0
+    return state / 0x100000000
+  }
+}
+
+function buildStore(scenario) {
+  const repo = new MemoryRepository(':memory:')
+  const svc = new MemoryService(repo, CONFIG)
+  const idToIndex = new Map()
+  scenario.claim_store.forEach((claim, index) => {
+    const scope = claim.scope ?? 'global'
+    const scopeKey = claim.scope_key ?? scope
+    const { claim: created } = repo.remember({
+      scope,
+      scopeKey,
+      kind: claim.kind,
+      content: claim.content,
+      origin: claim.origin ?? 'explicit',
+      ...(claim.valid_until === undefined ? {} : { validUntil: claim.valid_until }),
+    })
+    idToIndex.set(created.id, index)
+    for (let i = 0; i < (claim.harmful_bootstrap ?? 0); i += 1) {
+      repo.recordConsumption(created.id, 'harmful', 'backtest-bootstrap')
+    }
+  })
+  return { repo, svc, idToIndex }
+}
+
+function runScenario(scenario) {
+  const { repo, svc, idToIndex } = buildStore(scenario)
+  const goldenSet = new Set(scenario.golden.inject ?? [])
+  const expectedAction = (index) => (goldenSet.has(index) ? scenario.golden.expected_action : 'ignore')
+
+  const retrieval = svc.retrieve({ query: scenario.query, sessionId: 'backtest', sessionScopeKey: 'backtest' })
+  const gateDecisions = retrieval.decisions.map((d) => ({ index: idToIndex.get(d.claimId), action: d.action }))
+  const gateInject = new Set(gateDecisions.filter((d) => d.action !== 'ignore').map((d) => d.index))
+
+  const topCandidates = repo.search(scenario.query, ['global'], INJECTION_LIMIT)
+  const topInject = new Set(topCandidates.map((c) => idToIndex.get(c.claim.id)).filter((i) => i !== undefined))
+
+  const rand = seededRandom(0x5eed + scenario.claim_store.length)
+  const pool = scenario.claim_store.map((_, i) => i)
+  const randomInject = new Set()
+  for (let i = 0; i < Math.min(INJECTION_LIMIT, pool.length); i += 1) {
+    const pick = Math.floor(rand() * pool.length)
+    randomInject.add(pool[pick])
+    pool.splice(pick, 1)
+  }
+
+  const shadowInject = new Set()
+
+  const actionCorrect = scenario.claim_store.every((_, index) => {
+    const actual = gateDecisions.find((d) => d.index === index)?.action ?? 'ignore'
+    return actual === expectedAction(index)
+  })
+
+  repo.close()
+  return { scenario, goldenSet, gateInject, topInject, randomInject, shadowInject, actionCorrect }
+}
+
+const setsEqual = (a, b) => {
+  if (a.size !== b.size) return false
+  for (const item of a) if (!b.has(item)) return false
+  return true
+}
+const fmt = (set) => (set.size === 0 ? '∅' : [...set].sort((a, b) => a - b).join(','))
+
+function aggregate(results) {
+  const acc = { gate: { tp: 0, fp: 0, fn: 0 }, 'top-3': { tp: 0, fp: 0, fn: 0 }, random: { tp: 0, fp: 0, fn: 0 }, shadow: { tp: 0, fp: 0, fn: 0 } }
+  const injectOf = (r, name) => (name === 'gate' ? r.gateInject : name === 'top-3' ? r.topInject : name === 'random' ? r.randomInject : r.shadowInject)
+  for (const r of results) {
+    for (const name of Object.keys(acc)) {
+      const inject = injectOf(r, name)
+      r.scenario.claim_store.forEach((_, index) => {
+        const label = r.goldenSet.has(index)
+        const predict = inject.has(index)
+        if (predict && label) acc[name].tp += 1
+        else if (predict && !label) acc[name].fp += 1
+        else if (!predict && label) acc[name].fn += 1
+      })
+    }
+  }
+  return acc
+}
+
+function prf(acc, name) {
+  const { tp, fp, fn } = acc[name]
+  const precision = tp + fp === 0 ? 0 : tp / (tp + fp)
+  const recall = tp + fn === 0 ? 0 : tp / (tp + fn)
+  const f1 = precision + recall === 0 ? 0 : (2 * precision * recall) / (precision + recall)
+  return { precision, recall, f1, tp, fp, fn }
+}
+
+const scenarios = loadScenarios()
+const results = scenarios.map(runScenario)
+const clear = results.filter((r) => r.scenario.golden.hard !== true)
+const hard = results.filter((r) => r.scenario.golden.hard === true)
+
+const clearAgg = aggregate(clear)
+const hardAgg = aggregate(hard)
+
+const lines = []
+lines.push('# gate 决策层回测报告（合成场景）')
+lines.push('')
+lines.push(`场景总数 ${scenarios.length}（清晰 ${clear.length} / 硬案例 ${hard.length}）`)
+lines.push('')
+lines.push('| 场景 | 金标 | gate | top-3 | random | shadow | 结果 |')
+lines.push('|---|---|---|---|---|---|---|')
+
+for (const r of results) {
+  const isHard = r.scenario.golden.hard === true
+  const ok = setsEqual(r.gateInject, r.goldenSet) && r.actionCorrect
+  const mark = isHard ? '⚠️' : ok ? '✓' : '✗'
+  lines.push(
+    `| ${r.scenario.scenario_id}${isHard ? ' (hard)' : ''} | ${fmt(r.goldenSet)} | ${fmt(r.gateInject)} | ${fmt(r.topInject)} | ${fmt(r.randomInject)} | ${fmt(r.shadowInject)} | ${mark} |`,
+  )
+}
+
+const metricTable = (title, agg, results) => {
+  lines.push('')
+  lines.push(`## ${title}`)
+  lines.push('')
+  lines.push('| 腿 | 精确率 | 召回率 | F1 | TP/FP/FN |')
+  lines.push('|---|---|---|---|---|')
+  for (const name of ['gate', 'top-3', 'random', 'shadow']) {
+    const m = prf(agg, name)
+    lines.push(`| ${name} | ${m.precision.toFixed(2)} | ${m.recall.toFixed(2)} | ${m.f1.toFixed(2)} | ${m.tp}/${m.fp}/${m.fn} |`)
+  }
+  const actionOk = results.filter((r) => r.actionCorrect).length
+  lines.push('')
+  lines.push(`gate 动作全对：${actionOk}/${results.length}`)
+}
+
+metricTable('清晰场景（CI 门依据）', clearAgg, clear)
+metricTable('硬案例（已知短板，不阻塞）', hardAgg, hard)
+
+const clearPass = clear.filter((r) => setsEqual(r.gateInject, r.goldenSet) && r.actionCorrect).length
+const clearF1 = prf(clearAgg, 'gate').f1
+const hardFails = hard.filter((r) => !(setsEqual(r.gateInject, r.goldenSet) && r.actionCorrect)).map((r) => r.scenario.scenario_id)
+
+lines.push('')
+lines.push('## 结论')
+lines.push(`- 清晰场景通过：${clearPass}/${clear.length}`)
+if (hardFails.length) lines.push(`- 已知硬案例（待攻）：${hardFails.join(', ')}`)
+else lines.push('- 硬案例全部通过（无已知短板）')
+
+const report = lines.join('\n')
+console.log(report)
+
+mkdirSync(REPORTS, { recursive: true })
+const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+writeFileSync(join(REPORTS, `backtest-${ts}.md`), report + '\n')
+
+// CI 门：清晰场景 gate 必须全对（即 clear F1 == 1.0，动作全对）。
+const pass = clearPass === clear.length && clearF1 >= 0.999
+if (!pass) {
+  console.error(`\n[CI gate] FAILED: clear ${clearPass}/${clear.length}, clear F1=${clearF1.toFixed(3)}`)
+  process.exit(1)
+}
+console.log(`\n[CI gate] PASSED: clear ${clearPass}/${clear.length}, clear F1=${clearF1.toFixed(3)}`)

package/backtest/schema-v0.json

@@ -0,0 +1,34 @@
+{
+  "$comment": "dsh-memory-gate 回测样本 schema v0 —— 一条样本 = 一次「召回→决策→注入→结果」的闭环。决策层回测只填到 injection；outcome 由结果层回测（P1）再填。",
+  "schema": "1.0",
+  "source": "synthetic | captured",
+  "scenario_id": "pref-zh-concise",
+  "query": "请用简短的中文答复我",
+  "scopes": ["global"],
+  "claim_store": [
+    { "kind": "preference", "scope": "global", "content": "用户偏好简洁中文回答", "harmful_bootstrap": 0, "valid_until": null }
+  ],
+  "recall": {
+    "candidate_indices": [0],
+    "lexical_scores": [0.82]
+  },
+  "decisions": [
+    { "claim_index": 0, "action": "use", "belief": 0.86, "relevance": 0.82, "risk": 0.16, "reasons": ["authority_thresholds_passed"] }
+  ],
+  "injection": {
+    "claim_indices": [0],
+    "token_cost": 420,
+    "char_budget": 300
+  },
+  "outcome": {
+    "adoption": null,
+    "quality": null,
+    "feedback": null,
+    "effect_score": null
+  },
+  "golden": {
+    "inject": [0],
+    "expected_action": "use",
+    "hard": false
+  }
+}

package/backtest/trajectory.mjs

@@ -0,0 +1,74 @@
+/**
+ * 轨迹解析器 —— 把 DSH 的 session 事件流解析成「回合」视图。
+ *
+ * 每回合产出：{ query（人类提问文本）, assistantText（模型最终回答文本）, injections[] }
+ * 注入检测：消息文本含 <long_term_memory> 标记，且能从中抽出 claim id。
+ *
+ * 纯函数、可单测；zstd 解压由调用方（observe.mjs）负责。
+ */
+
+export function parseEvents(text) {
+  const events = []
+  for (const line of text.split('\n')) {
+    if (!line.trim()) continue
+    try {
+      events.push(JSON.parse(line))
+    } catch {
+      // 忽略无法解析的行（损坏/半行）
+    }
+  }
+  return events
+}
+
+function messageText(data) {
+  return (data?.content ?? []).map((part) => part?.text ?? '').join('\n')
+}
+
+function claimIdsOf(memoryText) {
+  const ids = [...memoryText.matchAll(/mem_[0-9a-f-]+/g)].map((m) => m[0])
+  return [...new Set(ids)]
+}
+
+/** 从记忆块里抽出每条 claim 的正文（去掉 `- [USE #1 mem_x kind]` 前缀与 boilerplate）。 */
+function claimContentsOf(memoryText) {
+  return memoryText
+    .split('\n')
+    .filter((line) => line.trimStart().startsWith('- ['))
+    .map((line) => line.replace(/^- \[[^\]]*\]\s*/, '').trim())
+    .filter(Boolean)
+}
+
+/**
+ * @param {Array} events 已解析的事件数组
+ * @returns {Array<{turn:number, query:string, assistantText:string, injections:Array<{claimIds:string[], text:string}>}>}
+ */
+export function observeSession(events) {
+  let currentTurn = 0
+  const turns = new Map()
+  const ensure = (turn) => {
+    if (!turns.has(turn)) turns.set(turn, { turn, query: '', assistantText: '', injections: [] })
+    return turns.get(turn)
+  }
+
+  for (const event of events) {
+    const type = event?.type
+    const data = event?.data ?? {}
+    if (type === 'turn/start') {
+      currentTurn = data.turn ?? currentTurn
+      ensure(currentTurn)
+    } else if (type === 'user/message') {
+      const text = messageText(data)
+      if (text.includes('<long_term_memory>')) {
+        ensure(currentTurn).injections.push({ claimIds: claimIdsOf(text), text, contents: claimContentsOf(text) })
+      } else if (text.trim()) {
+        const turn = ensure(currentTurn)
+        turn.query = turn.query ? `${turn.query}\n${text}` : text
+      }
+    } else if (type === 'assistant/message') {
+      const turn = data.turn ?? currentTurn
+      const texts = (data.message?.content ?? []).filter((part) => part.type === 'text').map((part) => part.text)
+      ensure(turn).assistantText += texts.join('\n')
+    }
+  }
+  return [...turns.values()]
+}