@a9i5k4/dsh-auto-memory 0.1.28 → 0.1.30

package/lib/context-sink-python.js

@@ -0,0 +1,90 @@
+/**
+ * M7-0/M7-1 PythonContextSinkPre(docs/PYTHON-SIDECAR-CONTRACT.md §5.2,§8.2,§13.1)。
+ * 实现 M5 ContextSinkPre 接口:消费现有 ContextPushEnvelopePre 原样字段(零 schema 改动),
+ * 在 deadlineAt 预算内返回兼容 ContextAckPre;worker 主动推送的 activation_request 帧经
+ * onActivation 上抛(交给现有 M6 validator/inbox 路径,本模块不构建 Packet)。
+ * 失败映射为结构化 ContextAckPre(accepted:false + reason 枚举);异常绝不冒泡到基础对话。
+ * 本模块不 spawn:进程生命周期完全属于共享的 SidecarClient。UTF-8 无 BOM。
+ */
+import { validateContextAckPre } from './context-bridge.js'
+import { ackMatchesObservationPre } from './m7-wire.js'
+
+export const PYTHON_CONTEXT_SINK_KIND_PRE = 'python'
+
+const ACK_REASON_FOR_CODE_PRE = Object.freeze({
+  timeout: 'busy',
+  aborted: 'busy',
+  circuitOpen: 'unsupported',
+  'circuit-open': 'unsupported',
+  unavailable: 'unsupported',
+  crashed: 'unsupported',
+  disposed: 'unsupported',
+  backpressure: 'busy',
+  protocol: 'unsupported',
+  'line-oversize': 'unsupported',
+  'worker-error': 'unsupported',
+  'unsupported-frame': 'unsupported',
+})
+
+export function createPythonContextSinkPre(opts = {}) {
+  const client = opts.client
+  if (!client || typeof client.request !== 'function') throw new Error('context-sink-python: client required')
+  const stats = { pushed: 0, accepted: 0, rejected: 0, staleDeadline: 0, invalidAck: 0, errors: 0 }
+  const requestTimeoutMs = Number(opts.requestTimeoutMs) || 5000
+  // 2026-08-30 canary 实证修复:传入的 onActivation 从未注册(只暴露注册方法,无人调用),
+  // worker activation_request 帧到达客户端后静默蒸发(activationsReceived++ 但 offers=0)。
+  // 自动注册,修通 Python emit → M6 的最后一厘米。
+  if (typeof opts.onActivation === 'function') client.onActivation(opts.onActivation)
+
+  /** 注册 worker 主动激活的下游处理器(M6 路径);返回解绑函数。 */
+  function onActivation(handler) { return client.onActivation(handler) }
+
+  async function push(frame, signal) {
+    stats.pushed++
+    const observationId = frame && typeof frame.observationId === 'string' ? frame.observationId : ''
+    try {
+      if (!frame || !observationId) { stats.rejected++; stats.errors++; return { observationId, accepted: false, reason: 'unsupported' } }
+      const now = Date.now()
+      const deadline = Number(frame.deadlineAt)
+      let timeoutMs = requestTimeoutMs
+      if (Number.isFinite(deadline)) {
+        const remaining = deadline - now
+        if (remaining <= 0) { stats.rejected++; stats.staleDeadline++; return { observationId, accepted: false, reason: 'stale' } }
+        timeoutMs = Math.min(timeoutMs, remaining)
+      }
+      // §8.2:payload 即完整 ContextPushEnvelopePre,原样透传(零字段增删)
+      const res = await client.request('context_push', frame, { timeoutMs, signal })
+      if (res.ok) {
+        const ack = res.frame && res.frame.payload
+        const v = validateContextAckPre(ack)
+        if (!v.ok || !ackMatchesObservationPre(ack, observationId)) {
+          stats.rejected++; stats.invalidAck++
+          return { observationId, accepted: false, reason: 'unsupported' }
+        }
+        if (ack.accepted) stats.accepted++; else stats.rejected++
+        return ack
+      }
+      stats.rejected++
+      const reason = ACK_REASON_FOR_CODE_PRE[res.code] || 'unsupported'
+      return { observationId, accepted: false, reason }
+    } catch (_) {
+      stats.errors++; stats.rejected++
+      return { observationId, accepted: false, reason: 'unsupported' }
+    }
+  }
+
+  async function closeSession(sessionId) {
+    try { client.notify('close_session', { sessionId: String(sessionId || '') }) } catch (_) {}
+  }
+
+  async function dispose(reason) {
+    void reason
+    // 客户端为 engine 级共享;sink 只解除自身注册(进程销毁由客户端 disposer 负责)
+  }
+
+  function debugView() {
+    return { kind: PYTHON_CONTEXT_SINK_KIND_PRE, stats: { ...stats }, client: client.debugView() }
+  }
+
+  return { kind: PYTHON_CONTEXT_SINK_KIND_PRE, push, closeSession, dispose, onActivation, debugView, _statsForTest: stats }
+}

package/lib/episodic-store.js

@@ -0,0 +1,316 @@
+/**
+ * M8-1 Episodic Store 纯核心(docs/proactive-associative-memory-system-map.html M-02 Episodic)。
+ * 纯内存状态机,零 IO、零依赖(node:crypto 仅作确定性身份);持久化通过可注入 IO 接口,
+ * Host 接线时才接真实文件(本模块自身不读写磁盘,测试用内存 IO)。
+ *
+ * 设计目标(M-02 元代码逐行落地):
+ *   - Episode 六元组: {intent, actions, entities, unresolved, outcome, provenance}
+ *   - 轻量事件先落 sidecar;会话结束或空闲期再摘要和巩固。
+ *   - 失败经验默认是 candidate,不直接是事实(防错误自我解释污染长期层)。
+ *
+ * 生命周期:
+ *   append(segment)  → episode 累积(intent/actions/entities/unresolved 从对话段提取)
+ *   consolidate()    → 会话结束/空闲期调用:把 episode 摘要并固化,产出 episodic_candidate
+ *                      供 M-03 Semantic(fact candidate)/M-04 Procedural(procedure candidate)消费。
+ *
+ * 与 M5 evidence 的衔接:每段都有 eventSeq/contextVersion 溯源;consolidate 后 evidence
+ * 挂钩供 Procedure 晋升复用(复用 fact-store 的 evidenceFor 语义,本模块自带轻量聚合)。
+ *
+ * 与 M7 judgement-shadow 的衔接:episodic_candidate 是 judgement-shadow 8 类之一,
+ * 本模块是它的 JS 侧真实来源(Python 侧仅建议,JS 侧才固化)。
+ *
+ * 全部同输入确定; UTF-8 无 BOM。
+ */
+import { createHash } from 'node:crypto'
+
+// ========== 冻结常量 ==========
+
+export const EPISODIC_POLICY_VERSION = 'episodic_store_v1'
+export const EPISODE_ID_PREFIX = 'epi_'
+export const EPISODE_ID_RE = /^epi_[0-9a-f]{32}$/
+
+/** episode 累积上限(防无限增长;超过后最旧段被丢弃)。 */
+export const EPISODE_SEGMENT_CAP_V1 = 64
+
+/** 巩固后保留的最多 episode 数(超出按时间淘汰,保留最近)。 */
+export const EPISODE_RETENTION_V1 = 256
+
+/** 巩固阈值:至少多少段才算一个可巩固 episode(少于=丢弃,噪声太多)。 */
+export const EPISODE_MIN_SEGMENTS_V1 = 2
+
+/** outcome 枚举。 */
+export const EPISODE_OUTCOMES_V1 = Object.freeze(['unknown', 'success', 'failure', 'partial'])
+
+/**
+ * EpisodeSegment 校验(append 输入)。
+ * 最小字段: kind/userText 至少一个非空; eventSeq 非负; contextVersion 非负。
+ */
+export function validateEpisodeSegmentPre(seg) {
+  const p = []
+  if (!seg || typeof seg !== 'object' || Array.isArray(seg)) return { ok: false, reason: 'not-object' }
+  const hasText = typeof seg.userText === 'string' && seg.userText.trim() ||
+    typeof seg.assistantText === 'string' && seg.assistantText.trim()
+  if (!hasText) p.push('no-text')
+  if (seg.kind !== undefined && !['user', 'assistant', 'reasoning', 'tool'].includes(seg.kind)) p.push('kind')
+  if (seg.eventSeq !== undefined && (!Number.isInteger(seg.eventSeq) || seg.eventSeq < 0)) p.push('eventSeq')
+  if (seg.contextVersion !== undefined && (!Number.isInteger(seg.contextVersion) || seg.contextVersion < 0)) p.push('contextVersion')
+  if (p.length) return { ok: false, reason: 'invalid:' + p.join(',') }
+  return { ok: true, segment: seg }
+}
+
+/** Episode 校验(consolidate 产出 / 持久化读回)。 */
+export function validateEpisodePre(ep) {
+  const p = []
+  if (!ep || typeof ep !== 'object' || Array.isArray(ep)) return { ok: false, reason: 'not-object' }
+  if (typeof ep.episodeId !== 'string' || !EPISODE_ID_RE.test(ep.episodeId)) p.push('episodeId')
+  if (typeof ep.sessionRef !== 'string' || !ep.sessionRef) p.push('sessionRef')
+  if (typeof ep.intent !== 'string') p.push('intent')
+  if (!Array.isArray(ep.actions)) p.push('actions')
+  if (!Array.isArray(ep.entities)) p.push('entities')
+  if (!Array.isArray(ep.unresolved)) p.push('unresolved')
+  if (!EPISODE_OUTCOMES_V1.includes(ep.outcome)) p.push('outcome')
+  if (!Array.isArray(ep.provenance)) p.push('provenance')
+  if (typeof ep.startedAt !== 'number' || !Number.isFinite(ep.startedAt)) p.push('startedAt')
+  if (ep.consolidatedAt !== undefined && (typeof ep.consolidatedAt !== 'number' || !Number.isFinite(ep.consolidatedAt))) p.push('consolidatedAt')
+  if (ep.success !== undefined && typeof ep.success !== 'boolean') p.push('success')
+  if (p.length) return { ok: false, reason: 'invalid:' + p.join(',') }
+  return { ok: true, episode: ep }
+}
+
+/**
+ * Episodic Store 工厂。
+ * @param {object} opts
+ * @param {object} opts.io      可选持久化 { save(snapshot), load() → snapshot, clear() }
+ * @param {function} opts.now   可选时钟
+ * @param {object} opts.config  { minSegments?, retention?, segmentCap? } — 可调参数(默认走冻结常量)
+ */
+export function createEpisodicStorePre(opts = {}) {
+  const io = opts.io || { save() {}, load() { return null }, clear() {} }
+  const nowFn = typeof opts.now === 'function' ? opts.now : () => Date.now()
+  const cfg = Object.assign({
+    segmentCap: EPISODE_SEGMENT_CAP_V1,
+    retention: EPISODE_RETENTION_V1,
+    minSegments: EPISODE_MIN_SEGMENTS_V1,
+  }, opts.config || {})
+
+  let episodes = []        // 已巩固 episode(含 candidate 状态)
+  let current = null       // 当前会话累积中(未巩固)
+  let disposed = false
+  const stats = { segmentsAppended: 0, consolidated: 0, droppedTooShort: 0, retained: 0 }
+
+  function defaultEpisodeId(sessionRef, startedAt) {
+    const h = createHash('sha256').update(['episode-pre-v1', String(sessionRef), String(startedAt)].join('\u0000')).digest('hex')
+    return EPISODE_ID_PREFIX + h.slice(0, 32)
+  }
+
+  // ---- 段追加(会话进行中实时累积) ----
+  function append(seg) {
+    if (disposed) return { ok: false, reason: 'disposed' }
+    const v = validateEpisodeSegmentPre(seg)
+    if (!v.ok) return { ok: false, reason: v.reason }
+    const s = v.segment
+    if (!current) {
+      current = {
+        sessionRef: String(s.sessionRef || 'unknown'),
+        startedAt: nowFn(),
+        segments: [],
+        userTexts: [], assistantTexts: [],
+      }
+    }
+    // 累积文本(只保留文本特征,不保留原文全文 —— 隐私最小化)
+    const ut = typeof s.userText === 'string' ? s.userText : ''
+    const at = typeof s.assistantText === 'string' ? s.assistantText : ''
+    if (ut.trim()) current.userTexts.push(ut.trim().slice(0, 200))
+    if (at.trim()) current.assistantTexts.push(at.trim().slice(0, 200))
+    current.segments.push({
+      kind: s.kind || 'unknown',
+      eventSeq: s.eventSeq || 0,
+      contextVersion: s.contextVersion || 0,
+      userText: ut.slice(0, 200),
+      assistantText: at.slice(0, 200),
+      ts: nowFn(),
+    })
+    // 超 cap:丢最旧段(保留最近上下文)
+    while (current.segments.length > cfg.segmentCap) {
+      current.segments.shift()
+      if (current.userTexts.length) current.userTexts.shift()
+      if (current.assistantTexts.length) current.assistantTexts.shift()
+    }
+    stats.segmentsAppended++
+    return { ok: true, segments: current.segments.length }
+  }
+
+  /** 从累积文本提取 intent(2026-08-28 提纯):跳过本插件注入快照污染的段
+   *  (「Current runtime context. This snapshot…」/auto-memory 标记),取第一条
+   *  真实用户文本;全被污染则取最后一条(退化)。 */
+  function extractIntent(ep) {
+    const INJECTED_RE = /^current runtime context\.|^this snapshot supersedes|auto-memory|\[自动沉淀\]/i
+    const texts = (ep.userTexts || []).map((t) => String(t || '').trim()).filter((t) => t)
+    const clean = texts.filter((t) => !INJECTED_RE.test(t))
+    const pick = clean.length ? clean[0] : (texts.length ? texts[texts.length - 1] : '')
+    return pick ? pick.slice(0, 60) : '(未提取)'
+  }
+
+  /** 从累积文本提取 entities(简单启发式:用户文本中的 CJK 2-4 字符 token,高频优先)。 */
+  function extractEntities(userTexts) {
+    const joined = userTexts.join(' ')
+    const grams = new Map()
+    const tokens = String(joined).match(/[A-Za-z0-9_\u4e00-\u9fff]+/g) || []
+    for (const tok of tokens) {
+      if (tok.length < 2 || tok.length > 20) continue
+      if (/^[\u4e00-\u9fff]+$/.test(tok) && tok.length > 4) {
+        // 中文长 token 按 2-3 字滑窗
+        for (let i = 0; i + 2 <= tok.length && i < tok.length - 2 + 1 && i < 12; i++) {
+          const g = tok.slice(i, i + 2)
+          if (/[\u4e00-\u9fff]/.test(g)) grams.set(g, (grams.get(g) || 0) + 1)
+        }
+      } else {
+        grams.set(tok, (grams.get(tok) || 0) + 1)
+      }
+    }
+    return [...grams.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8).map(([g]) => g)
+  }
+
+  /** 推断 outcome(启发式:助手文本含失败信号→failure, 成功信号→success)。 */
+  function inferOutcome(ep) {
+    const at = ep.assistantTexts.join(' ').toLowerCase()
+    const failSig = ['失败', '错误', '报错', '无法', 'error', 'failed', 'exception']
+    const succSig = ['成功', '完成', '已修复', '搞定', 'ok', 'done', 'success']
+    if (failSig.some((s) => at.includes(s))) return 'failure'
+    if (succSig.some((s) => at.includes(s))) return 'success'
+    return 'unknown'
+  }
+
+  /** 提取未决事项(启发式:用户文本含问句/待办)。 */
+  function extractUnresolved(ep) {
+    const ut = ep.userTexts.join(' ')
+    const out = []
+    const q = ut.match(/[^。！？\n]*[？?][^。！？\n]*/g) || []
+    for (const s of q) if (s.trim() && out.length < 5) out.push(s.trim().slice(0, 80))
+    return out
+  }
+
+  /**
+   * 巩固: 会话结束/空闲期调用,把当前累积固化成 episode。
+   * 产出 outcome=intent/entities/unresolved 等特征,并挂上 success 标志(供 Procedure 用)。
+   * 少于 minSegments 的丢弃(噪声)。
+   */
+  function consolidate() {
+    if (disposed) return { ok: false, reason: 'disposed' }
+    if (!current) return { ok: false, reason: 'nothing-to-consolidate' }
+    if (current.segments.length < cfg.minSegments) {
+      stats.droppedTooShort++
+      const segs = current.segments.length
+      current = null
+      return { ok: false, reason: 'too-short', segments: segs }
+    }
+    const outcome = inferOutcome(current)
+    const ep = {
+      episodeId: defaultEpisodeId(current.sessionRef, current.startedAt),
+      sessionRef: current.sessionRef,
+      intent: extractIntent(current),
+      actions: current.segments.map((s) => s.kind).filter(Boolean),
+      entities: extractEntities(current.userTexts),
+      unresolved: extractUnresolved(current),
+      outcome,
+      success: outcome === 'success',
+      provenance: current.segments.map((s) => 'seg:' + String(s.eventSeq)),
+      startedAt: current.startedAt,
+      consolidatedAt: nowFn(),
+    }
+    const v = validateEpisodePre(ep)
+    if (!v.ok) { current = null; return { ok: false, reason: 'invalid:' + v.reason } }
+    episodes.push(v.episode)
+    // 保留策略: 超 retention 淘汰最旧
+    if (episodes.length > cfg.retention) {
+      episodes = episodes.slice(-cfg.retention)
+      stats.retained++
+    }
+    current = null
+    stats.consolidated++
+    void persist()
+    return { ok: true, episode: v.episode }
+  }
+
+  /** 会话中途强制巩固(跨天续接/会话切换时调用)。 */
+  function flush() {
+    if (current) return consolidate()
+    return { ok: false, reason: 'nothing-to-consolidate' }
+  }
+
+  // ---- 查询 ----
+  function query(q = {}) {
+    if (disposed) return []
+    return episodes
+      .filter((e) =>
+        (q.sessionRef === undefined || e.sessionRef === q.sessionRef) &&
+        (q.outcome === undefined || e.outcome === q.outcome) &&
+        (q.success === undefined || e.success === q.success))
+      .map((e) => ({ ...e }))
+  }
+  function recent(n = 10) {
+    return episodes.slice(-n).map((e) => ({ ...e }))
+  }
+  function get(episodeId) {
+    const e = episodes.find((x) => x.episodeId === episodeId)
+    return e ? { ...e } : null
+  }
+
+  // ---- M-04 挂钩: 供 Procedure 晋升用的事故/成功统计 ----
+  function statsFor(sessionRef) {
+    const all = episodes.filter((e) => e.sessionRef === sessionRef)
+    return {
+      total: all.length,
+      success: all.filter((e) => e.success).length,
+      failure: all.filter((e) => e.outcome === 'failure').length,
+      distinctSessions: new Set(episodes.map((e) => e.sessionRef)).size,
+    }
+  }
+
+  // ---- 持久化 ----
+  function snapshot() {
+    return {
+      schemaVersion: 1, namespace: 'dsh-auto-memory', policyVersion: EPISODIC_POLICY_VERSION,
+      savedAt: nowFn(),
+      episodes: episodes.map((e) => ({ ...e })),
+      current: current ? {
+        sessionRef: current.sessionRef, startedAt: current.startedAt,
+        segments: current.segments, userTexts: current.userTexts, assistantTexts: current.assistantTexts,
+      } : null,
+    }
+  }
+  function restore(data) {
+    if (!data || data.schemaVersion !== 1) return { ok: false, reason: 'bad-schema' }
+    if (!Array.isArray(data.episodes)) return { ok: false, reason: 'bad-episodes' }
+    episodes = []
+    for (const e of data.episodes) {
+      const v = validateEpisodePre(e)
+      if (!v.ok) continue
+      episodes.push(v.episode)
+    }
+    current = data.current || null
+    return { ok: true, restored: episodes.length }
+  }
+  function clear() {
+    episodes = []; current = null
+    try { io.clear() } catch (_) {}
+    return { ok: true }
+  }
+  function dispose(reason) {
+    if (disposed) return
+    disposed = true
+    try { io.save(snapshot()) } catch (_) {}
+  }
+
+  function persist() {
+    try { io.save(snapshot()) } catch (_) {}
+  }
+
+  return {
+    append, consolidate, flush, query, recent, get, statsFor,
+    snapshot, restore, clear, dispose,
+    getStats: () => ({ ...stats }),
+    get size() { return episodes.length },
+    get hasCurrent() { return !!current },
+  }
+}

package/lib/evidence-store.js

@@ -0,0 +1,272 @@
+/**
+ * M5-2 Evidence Store + Aggregate(docs/M5-CONTRACT.md §8-§11)。
+ * append-only events(JSONL 按日分片)+隐私投影(sessionRef/workspaceRef 哈希;无原文/无绝对路径/
+ * 无裸 sessionId/workspaceKey/excerpt)+retention(30 天/32MiB)+aggregate rebuild(fresh/stale/unknown)。
+ * events 为唯一权威;aggregate 是可重建派生物。默认不构造不落盘;测试用临时 DSH_HOME 注入 root。
+ * 零第三方依赖(node:fs/path/crypto);UTF-8 无 BOM。
+ */
+import { mkdirSync, appendFileSync, readdirSync, readFileSync, statSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { createHash } from 'node:crypto'
+import {
+  validateAccessEvidencePre, validateEvidenceAggregatePre, EVIDENCE_POLICY_VERSION, NAMESPACE, BoundedIdSet,
+} from './context-bridge.js'
+
+const sha256Str = (s) => createHash('sha256').update(Buffer.from(String(s), 'utf8')).digest('hex')
+const first32 = (h) => h.slice(0, 32)
+
+/** §10 持久化策略(冻结)。 */
+export const EVIDENCE_STORE_POLICY_V1 = Object.freeze({
+  schemaVersion: 1,
+  storePolicyVersion: 'evidence_store_v1',
+  keepDays: 30,
+  maxTotalBytes: 32 * 1024 * 1024,
+  eventMaxBytes: 16 * 1024,
+  appendedIdCache: 4096,
+})
+
+/** 稳定 workspaceKey 规范化(与 m4-corpus canonical 同规则:resolve+正斜杠+小写)。 */
+export function canonicalWorkspaceKey(key) {
+  return path.resolve(String(key == null ? '' : key)).replace(/\\/g, '/').toLowerCase()
+}
+
+/** §10 隐私投影:sessionId → plugin-local sessionRef(不可逆哈希;跨文件稳定)。 */
+export function sessionRefOf(sessionId) {
+  return 'sesr_' + first32(sha256Str('evidence-sesref-pre-v1\u0000' + String(sessionId || '')))
+}
+
+/** §10 隐私投影:workspace 绝对键 → 稳定 workspaceRef(不落盘任何绝对路径)。 */
+export function workspaceRefOf(workspaceKey) {
+  return 'wsr_' + first32(sha256Str('evidence-wsref-pre-v1\u0000' + canonicalWorkspaceKey(workspaceKey)))
+}
+
+/**
+ * §10 durable projection:evidence → 落盘形态。删除裸 sessionId/workspaceKey;
+ * sourceRef 已由 validator 限定为相对引用(user:/workspace:/workspace-log:+文件名)。
+ * 返回 {ok, projected} 或 {ok:false, reason}(invalid-evidence/oversize)。
+ */
+export function projectEvidenceForDurable(ev, opts = {}) {
+  const v = validateAccessEvidencePre(ev)
+  if (!v.ok) return { ok: false, reason: 'invalid-evidence:' + v.reason }
+  const maxBytes = Number(opts.eventMaxBytes) || EVIDENCE_STORE_POLICY_V1.eventMaxBytes
+  const projected = {
+    schemaVersion: 1,
+    namespace: NAMESPACE,
+    storePolicyVersion: EVIDENCE_STORE_POLICY_V1.storePolicyVersion,
+    evidenceId: ev.evidenceId,
+    kind: ev.kind,
+    memoryId: ev.memoryId,
+    anchorId: ev.anchorId,
+    scope: ev.scope,
+    workspaceRef: workspaceRefOf(ev.workspaceKey),
+    event: {
+      sessionRef: sessionRefOf(ev.event.sessionId),
+      eventSeq: ev.event.eventSeq,
+      nativeSeq: ev.event.nativeSeq === undefined ? undefined : ev.event.nativeSeq,
+      contextVersion: ev.event.contextVersion,
+      callId: ev.event.callId === undefined ? undefined : ev.event.callId,
+      ts: ev.event.ts,
+    },
+    source: {
+      sourceRef: ev.source.sourceRef,
+      sourceEpoch: ev.source.sourceEpoch,
+      sourceVersion: ev.source.sourceVersion,
+      fileDigest: ev.source.fileDigest,
+      recordDigest: ev.source.recordDigest,
+    },
+    policyVersion: ev.policyVersion,
+    recordedAt: Number.isFinite(opts.now) ? opts.now : Date.now(),
+  }
+  if (ev.coverage !== undefined) projected.coverage = ev.coverage
+  if (ev.episodeId !== undefined && ev.episodeId !== null) projected.episodeId = ev.episodeId
+  const json = JSON.stringify(projected)
+  if (Buffer.byteLength(json, 'utf8') > maxBytes) return { ok: false, reason: 'event-oversize' }
+  return { ok: true, projected, line: json }
+}
+
+/** 从投影行还原成 rebuild 输入(无原始 sessionId;distinctSessions 以 sessionRef 计数)。 */
+export function parseDurableEventLine(line) {
+  try {
+    const j = JSON.parse(line)
+    if (!j || typeof j !== 'object' || !j.evidenceId || !j.kind || !j.memoryId) return { ok: false }
+    return { ok: true, event: j }
+  } catch (_) { return { ok: false } }
+}
+
+// ========== Store(appen-only JSONL,engine 级串行链) ==========
+
+export class EvidenceEventStore {
+  constructor(opts = {}) {
+    this.root = opts.root || null
+    this.eventsDir = opts.eventsDir || (this.root ? path.join(this.root, 'events') : null)
+    this._chain = Promise.resolve()
+    this._appended = new BoundedIdSet(EVIDENCE_STORE_POLICY_V1.appendedIdCache)
+    this._swept = false
+    this.stats = { appended: 0, duplicates: 0, oversize: 0, invalid: 0, writeFailed: 0, sweptFiles: 0, lastWriteError: null }
+  }
+
+  /** §9 幂等:同 evidenceId 进程内只落盘一次(seed replay 与 live 双喂安全网;磁盘侧靠 rebuild 去重兜底)。 */
+  async append(evidence, opts = {}) {
+    if (!this.eventsDir) return { ok: false, reason: 'store-not-configured' }
+    const id = evidence && evidence.evidenceId
+    if (id && this._appended.has(id)) { this.stats.duplicates++; return { ok: false, reason: 'duplicate-evidence', evidenceId: id } }
+    const proj = projectEvidenceForDurable(evidence, { now: opts.now })
+    if (!proj.ok) {
+      if (proj.reason === 'event-oversize') this.stats.oversize++
+      else this.stats.invalid++
+      return proj
+    }
+    if (id) this._appended.add(id)
+    this._chain = this._chain.then(() => this._writeLine(proj.line))
+    return this._chain.then((written) => ({ ok: written, reason: written ? 'ok' : 'write-failed', evidenceId: id, projected: proj.projected }))
+  }
+
+  async _writeLine(line) {
+    try {
+      mkdirSync(this.eventsDir, { recursive: true })
+      const d = new Date()
+      const fname = d.getFullYear() + '-' + String(d.getMonth() + 1).padStart(2, '0') + '-' + String(d.getDate()).padStart(2, '0') + '.jsonl'
+      appendFileSync(path.join(this.eventsDir, fname), line + '\n', 'utf8')
+      this.stats.appended++
+      this.sweepRetention()
+      return true
+    } catch (e) {
+      this.stats.writeFailed++
+      this.stats.lastWriteError = String(e && e.message ? e.message : e)
+      try { console.error('[evidence-store] write-failed: ' + this.stats.lastWriteError) } catch (_) {}
+      return false
+    }
+  }
+
+  /** §10 retention:保留 keepDays 天且总量 ≤maxTotalBytes;只清 events 分片。每进程至多全扫一次。 */
+  sweepRetention(force = false) {
+    if (this._swept && !force) return
+    this._swept = true
+    try {
+      const now = Date.now()
+      let total = 0
+      const files = []
+      for (const f of readdirSync(this.eventsDir)) {
+        if (!f.endsWith('.jsonl')) continue
+        const fp = path.join(this.eventsDir, f)
+        const st = statSync(fp)
+        total += st.size
+        files.push({ fp, mtimeMs: st.mtimeMs, size: st.size })
+      }
+      files.sort((a, b) => a.mtimeMs - b.mtimeMs)
+      for (const f of files) {
+        const ageDays = (now - f.mtimeMs) / 86400000
+        if (ageDays > EVIDENCE_STORE_POLICY_V1.keepDays || total > EVIDENCE_STORE_POLICY_V1.maxTotalBytes) {
+          try { rmSync(f.fp, { force: true }); this.stats.sweptFiles++; total -= f.size } catch (_) {}
+        } else break
+      }
+    } catch (_) {}
+  }
+
+  /** 读回全部事件(旧→新按文件名排序;坏行跳过计数)。 */
+  loadEvents() {
+    const out = []
+    let badLines = 0
+    try {
+      const files = readdirSync(this.eventsDir).filter((f) => f.endsWith('.jsonl')).sort()
+      for (const f of files) {
+        const text = readFileSync(path.join(this.eventsDir, f), 'utf8')
+        for (const line of text.split('\n')) {
+          if (!line.trim()) continue
+          const p = parseDurableEventLine(line)
+          if (p.ok) out.push(p.event)
+          else badLines++
+        }
+      }
+    } catch (_) {}
+    return { events: out, badLines }
+  }
+
+  dispose(reason) {
+    void reason
+    this._appended.clear()
+  }
+}
+
+// ========== §11 Aggregate rebuild(events 为唯一权威) ==========
+
+/**
+ * aggregate rebuild:从 durable events 重建 per-memoryId 聚合。
+ *  - Session scope 不进 durable aggregate(§11 scope 仅 Workspace|User;privacy)。
+ *  - evidenceId 去重(首见保留;重复计账)——seed replay/live 双写安全网。
+ *  - freshness:提供 corpusRecords 时,digest+sourceVersion 与当前记录一致=fresh;
+ *    memoryId 存在但不匹配=stale;语料缺失=unknown。不提供 corpusRecords → 全部 unknown。
+ */
+export function rebuildAggregates(durableEvents, corpusRecords) {
+  const list = Array.isArray(durableEvents)
+    ? durableEvents
+    : (durableEvents && Array.isArray(durableEvents.events) ? durableEvents.events : [])
+  const byKey = new Map() // memoryId → state
+  const seenIds = new Set()
+  let duplicates = 0
+  let sessionScoped = 0
+  for (const ev of list) {
+    if (seenIds.has(ev.evidenceId)) { duplicates++; continue }
+    seenIds.add(ev.evidenceId)
+    if (ev.scope === 'Session') { sessionScoped++; continue }
+    if (ev.scope !== 'Workspace' && ev.scope !== 'User') continue
+    const wsRef = ev.workspaceRef || 'unknown'
+    const key = ev.memoryId + '|' + ev.scope + '|' + wsRef
+    let st = byKey.get(key)
+    if (!st) {
+      st = { memoryId: ev.memoryId, scope: ev.scope, workspaceRef: wsRef, sessions: new Set(), counts: { seen: 0, read: 0, cite: 0, reuse: 0, success: 0, correction: 0 }, lastEvidenceAt: 0, latest: null }
+      byKey.set(key, st)
+    }
+    if (st.counts[ev.kind] === undefined) continue // 未知 kind 不计入(policy 升级兼容)
+    st.counts[ev.kind]++
+    st.sessions.add(ev.event && ev.event.sessionRef ? ev.event.sessionRef : 'unknown')
+    const ts = Number(ev.event && ev.event.ts) || 0
+    if (ts >= st.lastEvidenceAt) { st.lastEvidenceAt = ts; st.latest = ev }
+  }
+  const recsByMemory = new Map()
+  for (const r of Array.isArray(corpusRecords) ? corpusRecords : []) {
+    if (!recsByMemory.has(r.memoryId)) recsByMemory.set(r.memoryId, [])
+    recsByMemory.get(r.memoryId).push(r)
+  }
+  const aggregates = []
+  const byWorkspaceRef = new Map() // workspaceRef → aggregates(§9 跨工作区零泄漏的推送侧过滤依据)
+  for (const st of byKey.values()) {
+    let freshness = 'unknown'
+    const recs = recsByMemory.get(st.memoryId)
+    if (recs && recs.length && st.latest) {
+      const match = recs.some((r) => r.recordDigest === st.latest.source.recordDigest && r.sourceVersion === st.latest.source.sourceVersion)
+      freshness = match ? 'fresh' : 'stale'
+    }
+    const agg = {
+      memoryId: st.memoryId,
+      scope: st.scope,
+      freshness,
+      distinctSessions: st.sessions.size,
+      seen: st.counts.seen,
+      read: st.counts.read,
+      cite: st.counts.cite,
+      reuse: st.counts.reuse,
+      success: st.counts.success,
+      correction: st.counts.correction,
+      lastEvidenceAt: st.lastEvidenceAt,
+      policyVersion: EVIDENCE_POLICY_VERSION,
+    }
+    const v = validateEvidenceAggregatePre(agg)
+    if (v.ok) {
+      aggregates.push(v.aggregate)
+      if (!byWorkspaceRef.has(st.workspaceRef)) byWorkspaceRef.set(st.workspaceRef, [])
+      byWorkspaceRef.get(st.workspaceRef).push(v.aggregate)
+    }
+  }
+  aggregates.sort((a, b) => (a.memoryId < b.memoryId ? -1 : a.memoryId > b.memoryId ? 1 : a.scope < b.scope ? -1 : 1))
+  return { aggregates, byWorkspaceRef, duplicates, sessionScoped }
+}
+
+/** aggregate 快照持久化(evidence/aggregates/index.json;可重建派生物,仅调试/导出用)。 */
+export function persistAggregatesSnapshot(root, aggregates) {
+  const dir = path.join(root, 'aggregates')
+  mkdirSync(dir, { recursive: true })
+  const payload = { schemaVersion: 1, namespace: NAMESPACE, storePolicyVersion: EVIDENCE_STORE_POLICY_V1.storePolicyVersion, rebuiltAt: Date.now(), aggregates }
+  writeFileSync(path.join(dir, 'index.json'), JSON.stringify(payload, null, 2) + '\n', 'utf8')
+  return path.join(dir, 'index.json')
+}