dsh-memento 0.2.0

package/lib/budget.mjs

@@ -0,0 +1,110 @@
+// lib/budget.mjs — 预算计算（零 DSH 依赖，纯函数）。
+//
+// 每轨每层硬字符预算：user 轨默认 2000/层，agent 轨默认 4000/层（Config
+// budgets 可覆盖；中文场景按需调大并在 PR 说明理由）。计数单位是 JS 字符串
+// 长度（UTF-16 code unit）：一个汉字计 1，与用户直觉一致且可预测。
+// 写满必须报错（BUDGET_EXCEEDED），绝不静默截断、绝不自动压缩。
+
+import { TRACKS, SCOPES } from './constants.mjs'
+
+/**
+ * (track, scope) 的当前字符用量。
+ * @param {Array<{track: string, scope: string, text: string}>} entries - 该组条目。
+ * @param {string} track - 轨道。
+ * @param {string} scope - 作用域。
+ * @returns {number} 文本长度之和。
+ */
+export function entryUsage(entries, track, scope) {
+  let used = 0
+  for (const entry of entries) {
+    if (entry.track === track && entry.scope === scope) used += entry.text.length
+  }
+  return used
+}
+
+/**
+ * 全量用量行：每个 track×scope 一行。
+ * @param {Array<{track: string, scope: string, text: string}>} entries - 全部条目。
+ * @returns {Array<{track: 'user'|'agent', scope: 'user-global'|'workspace', used: number}>} 按轨道/作用域顺序排列。
+ */
+export function usageRows(entries) {
+  const rows = []
+  for (const track of TRACKS) {
+    for (const scope of SCOPES) {
+      rows.push({ track, scope, used: entryUsage(entries, track, scope) })
+    }
+  }
+  return rows
+}
+
+/**
+ * 预算检查：当前用量 + 增量是否超限。
+ * @param {number} used - 当前用量。
+ * @param {number} limit - 硬上限。
+ * @param {number} addition - 本次新增字符数（可为负，表示 replace 后的净变化）。
+ * @returns {{ok: true} | {ok: false, used: number, limit: number, needed: number}} 纯结果。
+ */
+export function checkBudget(used, limit, addition) {
+  const needed = used + addition
+  if (needed > limit) return { ok: false, used, limit, needed }
+  return { ok: true }
+}
+
+/**
+ * 完整预算报表：每行携带上限。
+ * @param {Array<{track: string, scope: string, text: string}>} entries - 全部条目。
+ * @param {{user: {userGlobal: number, workspace: number}, agent: {userGlobal: number, workspace: number}}} budgets - 形状 {user: {userGlobal, workspace}, agent: {userGlobal, workspace}}。
+ * @returns {Array<{track: 'user'|'agent', scope: 'user-global'|'workspace', used: number, limit: number}>}。
+ */
+export function budgetReport(entries, budgets) {
+  const limits = budgetLimits(budgets)
+  return usageRows(entries).map((row) => ({ ...row, limit: limits[row.track][row.scope] }))
+}
+
+/**
+ * 把 Config.budgets 规范化为 {track: {scope: limit}} 双键表。
+ * @param {{user: {userGlobal: number, workspace: number}, agent: {userGlobal: number, workspace: number}}} budgets - Config.budgets（含 userGlobal/workspace 键）。
+ * @returns {{user: {'user-global': number, workspace: number}, agent: {'user-global': number, workspace: number}}}。
+ */
+export function budgetLimits(budgets) {
+  return {
+    user: {
+      'user-global': budgets.user.userGlobal,
+      workspace: budgets.user.workspace,
+    },
+    agent: {
+      'user-global': budgets.agent.userGlobal,
+      workspace: budgets.agent.workspace,
+    },
+  }
+}
+
+/**
+ * 校验 budgets 配置形状：所有上限必须是正整数；缺失/非法在加载期响亮失败。
+ * @param {unknown} budgets - 原始配置。
+ * @returns {{ok: true, limits: object} | {ok: false, message: string}}。
+ */
+export function validateBudgets(budgets) {
+  if (budgets === null || typeof budgets !== 'object') {
+    return { ok: false, message: 'budgets must be an object with user/agent tracks and userGlobal/workspace layers' }
+  }
+  /** @type {Record<string, object>} */
+  const limits = {}
+  for (const track of TRACKS) {
+    const trackConfig = /** @type {{userGlobal?: unknown, workspace?: unknown} | null | undefined} */ (/** @type {Record<string, unknown>} */ (budgets)[track])
+    if (trackConfig === null || typeof trackConfig !== 'object') {
+      return { ok: false, message: `budgets.${track} must be an object` }
+    }
+    const layerLimits = /** @type {Record<string, number>} */ ({})
+    for (const scope of SCOPES) {
+      const key = scope === 'user-global' ? 'userGlobal' : scope
+      const limit = /** @type {Record<string, unknown>} */ (trackConfig)[key]
+      if (typeof limit !== 'number' || !Number.isInteger(limit) || limit <= 0) {
+        return { ok: false, message: `budgets.${track}.${key} must be a positive integer` }
+      }
+      layerLimits[scope] = limit
+    }
+    limits[/** @type {string} */ (track)] = layerLimits
+  }
+  return { ok: true, limits }
+}

package/lib/constants.mjs

@@ -0,0 +1,58 @@
+// lib/constants.mjs — dsh-memento 词汇表与协议常量（零 DSH 依赖）。
+//
+// 本文件只放协议级常量（词汇、错误码、存储格式版本）。部署可调参数一律走
+// index.mjs 的 Schemastery Config，绝不在此写死 tunable。
+
+/** 记忆轨道（双轨分家）：user=用户画像，agent=环境事实/约定/教训。 */
+export const TRACKS = /** @type {readonly ['user', 'agent']} */ (['user', 'agent'])
+
+/** 分层作用域：user-global 跨工作区，workspace 按会话 cwd。 */
+export const SCOPES = /** @type {readonly ['user-global', 'workspace']} */ (['user-global', 'workspace'])
+
+/** 写策略（Config.writePolicy）：ask=用户审批，auto=放行但记录审批来源，off=拒绝。 */
+export const WRITE_POLICIES = ['ask', 'auto', 'off']
+
+/** 审批请求里标识本插件记忆写动作的工具名（审批 answerer 据此认领请求）。 */
+export const TOOL_NAME = 'memory'
+
+/** 审批 reason 前缀（含方括号）：answerer 只认领带本前缀的 memory 写请求，防止误伤同工具名的其它请求。 */
+export const REQUEST_MARKER = '[dsh-memento]'
+
+/** 记忆库 schema 版本（单调递增；旧版逐级迁移，新版响亮拒绝）。v2 = proposals 提案表；v3 = agent_key + 召回排序列。 */
+export const SCHEMA_VERSION = 3
+
+/** 数据库文件名（位于 $DSH_HOME/dsh-memento/ 下）。 */
+export const DEFAULT_DB_NAME = 'memory.db'
+
+/** 条目默认来源标注（seed 写 source: 'claude' 时除外）。 */
+export const DEFAULT_SOURCE = 'dsh-memento'
+
+/** Provider 层查询返回硬上限：显式 limit 的钳制天花板（防模型/面板拉爆上下文）。 */
+export const MAX_QUERY_LIMIT = 1000
+
+/** 面板审计路由的返回上限：只读抽屉的审计尾展示天花板（协议常量，非部署 tunable）。 */
+export const PANEL_AUDIT_CEILING = 200
+
+/** 结构化错误码：工具与面板据此分支，模型据此决定"整合后重试"还是"放弃"。 */
+export const ERROR_CODES = {
+  DISABLED: 'MEMORY_DISABLED',
+  INVALID_INPUT: 'INVALID_INPUT',
+  NO_AGENT: 'WRITE_REQUIRES_AGENT',
+  BUDGET_EXCEEDED: 'BUDGET_EXCEEDED',
+  ENTRY_NOT_FOUND: 'ENTRY_NOT_FOUND',
+  AMBIGUOUS_MATCH: 'AMBIGUOUS_MATCH',
+  WRITE_DENIED: 'WRITE_DENIED',
+  PROPOSAL_NOT_FOUND: 'PROPOSAL_NOT_FOUND',
+  STORE_CORRUPT: 'STORE_CORRUPT',
+  STORE_UNSUPPORTED_VERSION: 'STORE_UNSUPPORTED_VERSION',
+  MISSING_DSH_HOME: 'MISSING_DSH_HOME',
+}
+
+/** 会话事件名（SessionEventMap 声明合并的词汇表；运行时按已知类型自适应派发）。 */
+export const SESSION_EVENTS = {
+  added: 'memory/added',
+  updated: 'memory/updated',
+  removed: 'memory/removed',
+  recalled: 'memory/recalled',
+  snapshot: 'memory/snapshot',
+}

package/lib/errors.mjs

@@ -0,0 +1,143 @@
+// lib/errors.mjs — 结构化错误（零 DSH 依赖）。
+//
+// 所有领域失败都以 MemoryError（或其子类）抛出：携带稳定 code 与 JSON 安全
+// details，供工具层转成规范 JSON 结果（ok:false + error 对象）。基础设施失败
+// （store 损坏等）也走本家族，绝不以字符串错误静默吞掉。
+
+import { ERROR_CODES } from './constants.mjs'
+
+/**
+ * dsh-memento 领域错误基类：稳定 code + 可公开的 details。
+ * @param {string} code - ERROR_CODES 成员之一。
+ * @param {string} message - 人类可读描述（中文，面向用户与模型）。
+ * @param {object} [details] - 附加事实（usage/limit/candidates 等，必须 JSON 安全）。
+ */
+export class MemoryError extends Error {
+  constructor(/** @type {string} */ code, /** @type {string} */ message, /** @type {{[key: string]: unknown}} */ details = {}) {
+    super(message)
+    this.name = 'MemoryError'
+    this.code = code
+    this.details = details
+  }
+
+  /** @returns {{code: string, message: string} & Record<string, unknown>} 工具结果里的规范错误对象。 */
+  toPublic() {
+    return { code: this.code, message: this.message, ...this.details }
+  }
+}
+
+/** 非法输入（空文本、越界轨道/作用域、缺失必填字段）。 */
+export class InvalidInputError extends MemoryError {
+  /** @param {string} message - 描述哪一项非法。 */
+  constructor(message) {
+    super(ERROR_CODES.INVALID_INPUT, message)
+    this.name = 'InvalidInputError'
+  }
+}
+
+/**
+ * 预算超限：写入会使 (track, scope) 字符用量超过硬上限。
+ * @param {object} d - {track, scope, used, limit, needed}。
+ */
+export class BudgetExceededError extends MemoryError {
+  constructor(/** @type {{track: string, scope: string, used: number, limit: number, needed: number}} */ d) {
+    super(
+      ERROR_CODES.BUDGET_EXCEEDED,
+      `memory budget exceeded: ${d.track}/${d.scope} at ${d.used}/${d.limit} chars, this write needs ${d.needed} chars; consolidate or remove entries, then retry`,
+      d,
+    )
+    this.name = 'BudgetExceededError'
+  }
+}
+
+/** 子串未命中任何条目。 */
+export class EntryNotFoundError extends MemoryError {
+  /** @param {{track: string, scope: string, match: string}} d - {track, scope, match}。 */
+  constructor(d) {
+    super(
+      ERROR_CODES.ENTRY_NOT_FOUND,
+      `no entry in ${d.track}/${d.scope} contains ${JSON.stringify(d.match)}; nothing was changed`,
+      d,
+    )
+    this.name = 'EntryNotFoundError'
+  }
+}
+
+/** 子串命中多条：要求模型给更具体的唯一子串。 */
+export class AmbiguousMatchError extends MemoryError {
+  /**
+   * @param {{track: string, scope: string, match: string, candidates: number, sample: string[]}} d - {track, scope, match, candidates, sample}；sample 是截断后的候选文本。
+   */
+  constructor(d) {
+    super(
+      ERROR_CODES.AMBIGUOUS_MATCH,
+      `match ${JSON.stringify(d.match)} is ambiguous in ${d.track}/${d.scope}: ${d.candidates} entries contain it; use a longer, unique substring`,
+      d,
+    )
+    this.name = 'AmbiguousMatchError'
+  }
+}
+
+/** 审批未放行（rejected/cancelled/unavailable），或写策略为 off。 */
+export class WriteDeniedError extends MemoryError {
+  /**
+   * @param {string} outcome - ApprovalOutcome 之一。
+   * @param {string} [detail] - 附加原因（如审批服务抛错），拼进消息。
+   */
+  constructor(outcome, detail) {
+    super(
+      ERROR_CODES.WRITE_DENIED,
+      `memory write not approved (approval outcome: ${outcome}${detail === undefined ? '' : `; ${detail}`}); nothing was written`,
+      { outcome },
+    )
+    this.name = 'WriteDeniedError'
+  }
+}
+
+/** 插件被禁用（enabled:false）时调用写/读服务。 */
+export class DisabledError extends MemoryError {
+  constructor() {
+    super(ERROR_CODES.DISABLED, 'dsh-memento is disabled by configuration; no memory service is available')
+    this.name = 'DisabledError'
+  }
+}
+
+/** 提案不存在或已裁决（approve/dismiss 目标必须是 pending 提案）。 */
+export class ProposalNotFoundError extends MemoryError {
+  /**
+   * @param {string} id - 提案 id。
+   * @param {string} [detail] - 附加原因（如已裁决的状态）。
+   */
+  constructor(id, detail) {
+    super(
+      ERROR_CODES.PROPOSAL_NOT_FOUND,
+      `proposal ${JSON.stringify(id)} is not a pending proposal${detail === undefined ? '' : ` (${detail})`}; nothing was changed`,
+      { id },
+    )
+    this.name = 'ProposalNotFoundError'
+  }
+}
+
+/** 写路径缺少 agent（无法路由审批）：一律失败封闭，绝不静默放行。 */
+export class NoAgentError extends MemoryError {
+  constructor() {
+    super(
+      ERROR_CODES.NO_AGENT,
+      'memory write requires an owning agent session to route approval through; refuse rather than write unapproved',
+    )
+    this.name = 'NoAgentError'
+  }
+}
+
+/** 记忆库损坏/版本过新：加载期或最早可解析点响亮失败。 */
+export class StoreError extends MemoryError {
+  /**
+   * @param {string} code - STORE_CORRUPT 或 STORE_UNSUPPORTED_VERSION。
+   * @param {string} message - 具体原因。
+   * @param {{[key: string]: unknown}} [details] - {path} 等。
+   */
+  constructor(code, message, /** @type {{[key: string]: unknown}} */ details = {}) {
+    super(code, message, details)
+    this.name = 'StoreError'
+  }
+}

package/lib/extract.mjs

@@ -0,0 +1,54 @@
+// lib/extract.mjs — 会话事件文本抽取（零 DSH 依赖）。
+//
+// memory_recall 的历史片段显示用：从已知第一方事件形状里提取可读文本。
+// 只用于搜索结果片段（显示截断允许）；记忆条目的存储与审计绝不经过本函数。
+
+/**
+ * 从会话事件里提取可读文本（记忆召回的历史片段用）。
+ * @param {unknown} event - SessionEvent 形状（{type, data}）；防御性解析，形状不信任。
+ * @returns {string} 新行拼接的可读文本；不认识的事件返回空串。
+ */
+export function extractEventText(event) {
+  if (event === null || typeof event !== 'object') return ''
+  const data = /** @type {{data?: unknown}} */ (event).data
+  if (data === null || typeof data !== 'object') {
+    return typeof data === 'string' ? data : ''
+  }
+  const record = /** @type {{content?: unknown, message?: unknown, name?: unknown, arguments?: unknown, todos?: unknown, summary?: unknown, text?: unknown}} */ (data)
+  // user/message 与 assistant/message：content 文本块
+  if (Array.isArray(record.content)) {
+    return contentText(/** @type {unknown[]} */ (record.content))
+  }
+  // compaction/summary：summary 文本块
+  if (Array.isArray(record.summary)) {
+    return contentText(/** @type {unknown[]} */ (record.summary))
+  }
+  // tool/result（及携带 message 的其它事件）
+  if (record.message !== null && typeof record.message === 'object') {
+    const message = /** @type {{content?: unknown, text?: unknown}} */ (record.message)
+    if (Array.isArray(message.content)) return contentText(/** @type {unknown[]} */ (message.content))
+    if (typeof message.text === 'string') return message.text
+  }
+  // tool/call：工具名 + 原始参数
+  if (typeof record.name === 'string' && typeof record.arguments === 'string') {
+    return `${record.name} ${record.arguments}`
+  }
+  // todo/write：任务清单
+  if (Array.isArray(record.todos)) {
+    return /** @type {Array<{content: string}>} */ (record.todos).map((item) => item.content).join('\n')
+  }
+  // request/header 等：渲染文本字段
+  if (typeof record.text === 'string') return record.text
+  return ''
+}
+
+/** content 文本块拼接（跳过非文本块）。 */
+function contentText(/** @type {unknown[]} */ content) {
+  const parts = []
+  for (const part of content) {
+    if (part !== null && typeof part === 'object' && typeof /** @type {{text?: unknown}} */ (part).text === 'string' && /** @type {{text: string}} */ (part).text.length > 0) {
+      parts.push(/** @type {{text: string}} */ (part).text)
+    }
+  }
+  return parts.join('\n')
+}

package/lib/gate.mjs

@@ -0,0 +1,131 @@
+// lib/gate.mjs — 审批门策略（零 DSH 依赖，纯逻辑）。
+//
+// 写策略（Config.writePolicy，模型不可见、不可改）：
+// - ask：委托审批链上其余 answerer（Web UI 人类审批 / ACP 一次性决策），无
+//   answerer 时审批服务按失败封闭给出 unavailable → 写被拒。
+// - auto：本插件 answerer 直接放行（allowed-once）；审批来源仍随 approval/asked
+//   + approval/decided 审计对与审计表记录。
+// - off：本插件 answerer 直接拒绝（rejected），写报结构化错误。
+// 注意：会话级 ApprovalPolicy='never'（用户全局姿态）在审批服务内部、answerer
+// 之前裁决，任何 answerer（含 prepend 注册的本插件）都无法绕过——这是 DSH
+// 审批 seam 的硬不变量，本插件设计上遵从它。
+
+import { TOOL_NAME, REQUEST_MARKER, WRITE_POLICIES } from './constants.mjs'
+import { InvalidInputError } from './errors.mjs'
+
+/**
+ * 判断一条审批请求是否为本插件发出的记忆写请求。
+ * 认领条件：toolName === 'memory' 且 reason 带 [dsh-memento] 前缀——防止误伤
+ * 其它插件以同名工具身份发出的审批请求。
+ * @param {unknown} req - ApprovalRequest 形状（防御性解析）。
+ * @returns {boolean} 是否本插件的记忆写请求。
+ */
+export function isMemoryWriteRequest(req) {
+  if (req === null || typeof req !== 'object') return false
+  const candidate = /** @type {{toolName?: unknown, reason?: unknown}} */ (req)
+  return candidate.toolName === TOOL_NAME
+    && typeof candidate.reason === 'string'
+    && candidate.reason.startsWith(REQUEST_MARKER)
+}
+
+/**
+ * 构造审批 reason：第一行人类可读摘要，随后是完整载荷文本。
+ * reason 随 approval/asked 进入会话日志（已知事件类型、可持久化），
+ * S2 的"变更可自会话日志重建"由此成立。
+ * @param {{action: string, track: string, scope: string, text: string, count?: number, source?: string}} input - {action, track, scope, text, count?, source?}；count 用于 seed 批量，source 供粒度策略裁决。
+ * @returns {string} 审批 reason。
+ */
+export function buildWriteReason({ action, track, scope, text, count, source }) {
+  const batch = count === undefined ? '' : ` (${count} entries)`
+  const sourceTag = source === undefined ? '' : ` [source:${source}]`
+  return `${REQUEST_MARKER} ${action}${batch} ${track}/${scope}${sourceTag}\n${text}`
+}
+
+/**
+ * 从审批 reason 解析回结构化载荷（审计/重建用）。
+ * @param {string} reason - buildWriteReason 的产物。
+ * @returns {{action: string, track: string, scope: string, text: string, count?: number, source?: string} | null}
+ *   无法解析返回 null（调用方据此响亮报错）。
+ */
+export function parseWriteReason(reason) {
+  const match = /^\[dsh-memento\] ([a-z]+)(?: \((\d+) entries\))? ([a-z]+)\/([a-z-]+)(?: \[source:([^\]]+)\])?\n([\s\S]*)$/.exec(reason)
+  if (match === null) return null
+  return {
+    action: match[1],
+    ...(match[2] === undefined ? {} : { count: Number(match[2]) }),
+    track: match[3],
+    scope: match[4],
+    ...(match[5] === undefined ? {} : { source: match[5] }),
+    text: match[6],
+  }
+}
+
+/**
+ * 粒度写策略解析：`source:<source>` 精确键 > `track/scope` 键 > 全局 writePolicy。
+ * 未命中回退全局——旧 Config 形状（只有 writePolicy 字符串）向后兼容。
+ * @param {Record<string, string>} writePolicies - Config.writePolicies（可空）。
+ * @param {string} fallback - 全局 writePolicy。
+ * @param {string} track - 轨道。
+ * @param {string} scope - 作用域。
+ * @param {string} [source] - 来源标注。
+ * @returns {string} 生效策略。
+ */
+export function resolveWritePolicy(writePolicies, fallback, track, scope, source) {
+  if (source !== undefined) {
+    const bySource = writePolicies[`source:${source}`]
+    if (bySource !== undefined) return bySource
+  }
+  const byScope = writePolicies[`${track}/${scope}`]
+  if (byScope !== undefined) return byScope
+  return fallback
+}
+
+/**
+ * 校验粒度策略表：值必须是 ask/auto/off，键必须是 `track/scope` 或 `source:<name>`。
+ * 非法键/值在加载期响亮失败（绝不静默忽略错误配置）。
+ * @param {unknown} writePolicies - 原始配置值。
+ * @returns {Record<string, string>} 合法策略表。
+ */
+export function validateWritePolicies(writePolicies) {
+  if (writePolicies === null || typeof writePolicies !== 'object') {
+    throw new InvalidInputError('writePolicies must be an object with keys like "user/workspace" or "source:claude"')
+  }
+  const table = /** @type {Record<string, string>} */ (writePolicies)
+  for (const [key, value] of Object.entries(table)) {
+    const validKey = /^(user|agent)\/(user-global|workspace)$/.test(key) || /^source:[a-z0-9-]+$/.test(key)
+    if (!validKey) {
+      throw new InvalidInputError(`invalid writePolicies key ${JSON.stringify(key)} (expected "track/scope" or "source:<name>")`)
+    }
+    if (!WRITE_POLICIES.includes(value)) {
+      throw new InvalidInputError(`invalid writePolicies value for ${JSON.stringify(key)}: ${JSON.stringify(value)} (one of ${WRITE_POLICIES.join('|')})`)
+    }
+  }
+  return table
+}
+
+/**
+ * 对记忆写请求应用写策略（answerer 本体）。
+ * @param {string} policy - writePolicy。
+ * @param {unknown} req - ApprovalRequest（已通过 isMemoryWriteRequest 认领）。
+ * @param {() => Promise<string>} next - waterfall 续链（ask 时委托人类 answerer）。
+ * @returns {Promise<string>} ApprovalOutcome 之一。
+ */
+export async function applyWritePolicy(policy, req, next) {
+  if (!WRITE_POLICIES.includes(policy)) {
+    throw new InvalidInputError(`invalid writePolicy ${JSON.stringify(policy)} (one of ${WRITE_POLICIES.join('|')})`)
+  }
+  if (policy === 'auto') return 'allowed-once'
+  if (policy === 'off') return 'rejected'
+  return next()
+}
+
+/**
+ * 校验并归一化写策略（加载期响亮失败）。
+ * @param {unknown} policy - 原始配置值。
+ * @returns {string} 合法策略原值。 */
+export function normalizeWritePolicy(policy) {
+  if (!WRITE_POLICIES.includes(/** @type {string} */ (policy))) {
+    throw new InvalidInputError(`invalid writePolicy ${JSON.stringify(policy)} (one of ${WRITE_POLICIES.join('|')})`)
+  }
+  return /** @type {string} */ (policy)
+}

package/lib/match.mjs

@@ -0,0 +1,43 @@
+// lib/match.mjs — 唯一子串匹配（零 DSH 依赖）。
+//
+// replace/remove 的定位语义：在同 (track, scope) 的条目文本里做大小写不敏感
+// 子串匹配（ASCII 折叠；CJK 无大小写不受影响）。零命中 → not-found；多命中 →
+// ambiguous（带候选清单，要求模型给更具体的唯一子串）；恰一命中 → ok。
+// 不做 FTS/模糊匹配（小语料；FTS5 trigram 无法索引单字 CJK 字符，见 ARCHITECTURE）。
+
+/**
+ * 在候选条目里按唯一子串定位（大小写不敏感）。
+ * @param {Array<{id: string, text: string}>} entries - 已按 track+scope 过滤的候选条目。
+ * @param {string} match - 目标子串（调用方保证非空）。
+ * @returns {{kind: 'ok', entry: {id: string, text: string}}
+ *   | {kind: 'not-found'}
+ *   | {kind: 'ambiguous', candidates: Array<{id: string, text: string}>}} 纯函数结果，不抛错。
+ */
+export function findUniqueMatch(entries, match) {
+  const lower = match.toLowerCase()
+  const hits = entries.filter((entry) => entry.text.toLowerCase().includes(lower))
+  if (hits.length === 0) return { kind: 'not-found' }
+  if (hits.length > 1) return { kind: 'ambiguous', candidates: hits }
+  return { kind: 'ok', entry: hits[0] }
+}
+
+/**
+ * 把 findUniqueMatch 的结果转成领域错误（store 层使用）。
+ * @param {{kind: string, entry?: {id: string, text: string}, candidates?: Array<{id: string, text: string}>}} result - findUniqueMatch 结果。
+ * @param {object} ctx - {track, scope, match}，供错误 details 使用。
+ * @param {{EntryNotFoundError: new (ctx: object) => Error, AmbiguousMatchError: new (ctx: object) => Error}} errors - 错误类（注入以避免循环依赖）。
+ * @returns {{id: string, text: string} | undefined} 命中的条目，或抛 EntryNotFoundError / AmbiguousMatchError。
+ */
+export function requireUniqueMatch(result, ctx, errors) {
+  if (result.kind === 'ok') return result.entry
+  if (result.kind === 'ambiguous') {
+    const sample = /** @type {Array<{text: string}>} */ (result.candidates).map((candidate) =>
+      candidate.text.length > 200 ? `${candidate.text.slice(0, 200)}…` : candidate.text)
+    throw new errors.AmbiguousMatchError({
+      ...ctx,
+      candidates: /** @type {Array<{id: string, text: string}>} */ (result.candidates).length,
+      sample,
+    })
+  }
+  throw new errors.EntryNotFoundError(ctx)
+}

package/lib/snapshot.mjs

@@ -0,0 +1,115 @@
+// lib/snapshot.mjs — 冻结快照渲染（零 DSH 依赖，纯函数）。
+//
+// 会话启动时把当前记忆渲染成带用量头的冻结块，经 systemPrompt 段注入
+// （system-prompt/assemble 提供 agent，section order = Config.snapshotOrder，
+// 默认 -50：harness identity(-100) 之后、persona(0) 之前）。会话内记忆变更
+// 只落盘+落审计，不更新已注入快照（冻结语义 = 前缀缓存稳定）。
+
+import { TRACKS, SCOPES } from './constants.mjs'
+import { budgetReport } from './budget.mjs'
+import { GROUP_TITLES, SNAPSHOT_HEADER, PROPOSAL_HEADER, pick } from './strings.mjs'
+
+/**
+ * @typedef {object} SnapshotEntry - 快照渲染看到的条目面。
+ * @property {string} id
+ * @property {string} track
+ * @property {string} scope
+ * @property {string} workspaceKey
+ * @property {string} agentKey
+ * @property {string} text
+ * @property {number} createdAt
+ */
+
+/**
+ * 过滤某个会话可见的条目：agentKey 为 ''（共享层）或匹配会话 agentKey；scope
+ * user-global 全见；workspace 只匹配该会话的 workspaceKey（会话 cwd 的规范化绝对值）。
+ * @param {SnapshotEntry[]} entries - 全部条目。
+ * @param {string} workspaceKey - 会话 cwd 的规范化绝对值。
+ * @param {string} [agentKey] - 会话 agentPreset 的规范化键；'' = 共享层。
+ * @returns {SnapshotEntry[]} 可见条目。
+ */
+export function visibleEntries(entries, workspaceKey, agentKey = '') {
+  return entries.filter((entry) =>
+    (entry.agentKey === '' || entry.agentKey === agentKey)
+    && (entry.scope === 'user-global' || (entry.scope === 'workspace' && entry.workspaceKey === workspaceKey)))
+}
+
+/**
+ * 把条目按 (track, scope) 分组并组内按创建时间排序。
+ * @param {SnapshotEntry[]} entries - 可见条目。
+ * @returns {Map<string, SnapshotEntry[]>} key = 'track/scope'，值按 createdAt,id 升序。
+ */
+export function groupEntries(entries) {
+  const groups = new Map()
+  for (const entry of entries) {
+    const key = `${entry.track}/${entry.scope}`
+    const list = groups.get(key)
+    if (list === undefined) groups.set(key, [entry])
+    else list.push(entry)
+  }
+  for (const list of groups.values()) {
+    list.sort((/** @type {SnapshotEntry} */ a, /** @type {SnapshotEntry} */ b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+  }
+  return groups
+}
+
+/**
+ * @typedef {object} SnapshotProposal - 快照渲染看到的提案面。
+ * @property {string} id
+ * @property {string} track
+ * @property {string} scope
+ * @property {string} workspaceKey
+ * @property {string} agentKey
+ * @property {string} text
+ */
+
+/**
+ * 过滤某个会话可见的提案：与条目可见性同一语义（agentKey 共享/匹配 +
+ * scope 规则）。
+ * @param {SnapshotProposal[]} proposals - 全部 pending 提案。
+ * @param {string} workspaceKey - 会话 cwd 的规范化绝对值。
+ * @param {string} [agentKey] - 会话 agentPreset 的规范化键；'' = 共享层。
+ * @returns {SnapshotProposal[]} 可见提案。
+ */
+export function visibleProposals(proposals, workspaceKey, agentKey = '') {
+  return proposals.filter((proposal) =>
+    (proposal.agentKey === '' || proposal.agentKey === agentKey)
+    && (proposal.scope === 'user-global' || (proposal.scope === 'workspace' && proposal.workspaceKey === workspaceKey)))
+}
+
+/**
+ * 渲染冻结快照全文（含每分组用量头）。无任何条目时返回空串——空段不进提示词，
+ * 空记忆零 token 成本。带 pending 提案时追加提案块（模型可见 ⟺ 随快照文本
+ * 进入 request/header.system，S2 可重建）。
+ * @param {SnapshotEntry[]} entries - 会话可见条目。
+ * @param {{user: {userGlobal: number, workspace: number}, agent: {userGlobal: number, workspace: number}}} budgets - Config.budgets。
+ * @param {SnapshotProposal[]} [proposals] - 会话可见 pending 提案。
+ * @param {string} [language] - 'en' | 'zh'（默认 en）。
+ * @returns {string} 快照文本。
+ */
+export function renderSnapshot(entries, budgets, proposals = [], language = 'en') {
+  const groups = groupEntries(entries)
+  const report = budgetReport(entries, budgets)
+  const titles = /** @type {Record<string, string>} */ (pick(GROUP_TITLES, language))
+  const header = /** @type {string} */ (pick(SNAPSHOT_HEADER, language))
+  const proposalHeader = /** @type {string} */ (pick(PROPOSAL_HEADER, language))
+  const usageSuffix = language === 'zh' ? '已用字符' : 'chars used'
+  const sections = []
+  for (const track of TRACKS) {
+    for (const scope of SCOPES) {
+      const key = `${track}/${scope}`
+      const list = groups.get(key)
+      if (list === undefined || list.length === 0) continue
+      const row = report.find((candidate) => candidate.track === track && candidate.scope === scope)
+      sections.push(`## ${titles[key]} — ${row.used}/${row.limit} ${usageSuffix}\n${list.map((entry) => `- ${entry.text}`).join('\n')}`)
+    }
+  }
+  if (proposals.length > 0) {
+    sections.push([
+      `## ${proposalHeader}`,
+      proposals.map((proposal) => `- [${proposal.id}] ${proposal.track}/${proposal.scope}: ${proposal.text}`).join('\n'),
+    ].join('\n'))
+  }
+  if (sections.length === 0) return ''
+  return [header, ...sections].join('\n\n')
+}