@@ -2,9 +2,9 @@
[English ](README.md ) | 中文
抽象的持久会话持久化 seam（ `ctx.sessionPersistence` ）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 功 能 seam 模板一致（见[功 能 seam../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md )）：本包提供抽象服务，同级包提供具体实现，消费方注入接口。
这是用于持久保存会话的 抽象 seam（ `ctx.sessionPersistence` ）。它定义持久化后端做什么：持久存储、重新加载和列出会话，而不规定如何实现。它与 `dsh-bash` 能力 seam 模板一致（见[能力 seam ](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md )）：本包提供抽象服务，同级包提供具体实现，消费方注入接口。
持久化单元就是现有 `SessionEvent` （事件溯源模型：日志是唯一真源），因此不存在并行的「持久消息」类型。不可回放的 对话状态元数据（ ） `SessionHeader` 单独传输，该类型归 `dsh-session` 所有，并在此重新导出。
持久化单元就是现有 `SessionEvent` （事件溯源模型：日志是唯一真源），因此不存在另一套 并行的「持久消息」类型。不属于 可回放对话状态的 元数据（ ） `SessionHeader` 单独传输，该类型归 `dsh-session` 所有，并在此重新导出。
## 服务 API（ ）
@@ -12,51 +12,51 @@
|---|---|
| `locate(meta): SessionLocation \| undefined` | 在不执行 I/O 或实体化的情况下解析绝对的每会话产物目标。没有独立本地产物的后端返回 `undefined` 。 |
| `create(meta): Promise<void>` | 注册新会话元数据。可以将物理写入延迟到第一次 `append` （延迟实体化）。 |
| `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq； 命名违规 类型。 |
| `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq； 指出导致问题的 类型。 |
| `load(id): Promise<{ meta; events }>` | 返回已存储 header 和平衡、连续的日志，其中事件已脱离并验证，带标识的消息已深度冻结。协调器会在返回快照中，将消息标识机制引入前的四种消息事件形状升级为当前包装层；其余过时或格式错误的形状仍会被拒绝。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result` /`step/end?` /`turn/end {interrupted}` 事件关闭它。只丢弃撕裂尾部碎片；已提交损坏和未知 `version` 会被拒绝。 |
| `inspect(id, signal?): Promise<{ meta; events }>` | 返回脱离的有效已存储前缀，其中带标识的消息已经升级、验证并深度冻结；不截断撕裂尾部、合成恢复 closer 或发布协调器状态。它与同 id 写入串行化；可选信号会迅速拒绝已排队调用方，阻止该后端读取启动，并取消活动 后端读取工作。用于绝不应恢复日志的读模型和其他观察者。 |
| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | read-from-seq 原语：返回 header 和 `seq >= fromSeq` 的有效已存储事件，与 `inspect` 同样脱离且非变更（不截断、不合成 closer、不发布协调器状态） `fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（ ） ； （ ） ， 者 （例如持久投影缓存）。 |
| `inspect(id, signal?): Promise<{ meta; events }>` | 返回脱离的有效已存储前缀，其中带标识的消息已经升级、验证并深度冻结；不截断撕裂尾部、合成恢复 closer 或发布协调器状态。它与同 id 写入串行化；可选信号会迅速拒绝已排队调用方，阻止该后端读取启动，并取消正在进行的 后端读取工作。用于绝不应恢复日志的读模型和其他观察者。 |
| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | read-from-seq 原语：返回 header 和 `seq >= fromSeq` 的有效已存储事件，与 `inspect` 同样脱离且非变更（不截断、不合成 closer、不发布协调器状态） `fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（ ） ； （ ） ， 方 （例如持久投影缓存）。 |
| `list(signal?): Promise<SessionHeader[]>` | 从元数据轻量列出，不解析完整日志。可选信号取消后端列表工作。零事件延迟实体化会话不在 `list` 中。 |
| `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和不透明品牌化每日志 修订， ， ； 在拒绝前结算已启动列表工作，使已等待调用 完全停稳。 |
| `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和每份日志一个不透明、带品牌类型的 修订值 ， ， ； 会先等待所有已启动的列出工作结束，再予以拒绝，因此调用返回拒绝时，相关工作已 完全停稳。 |
## 每个后端必须遵守的不变量
- **仅追加；崩溃轮次会被关闭，而非截断。** 已 flush 事件绝不重写。崩溃可留下未关闭最终轮次，其事件真实且可能很大；`load` 保留它们，并持久追加合成 closer（ `tool/result` ，再添加 `step/end?` +`turn/end {interrupted}` ），以平衡日志，并确保重新载入的历史仍是有效的提供方 transcript。只丢弃从未完整写入的撕裂尾部碎片。
- **仅追加；崩溃轮次会被关闭，而非截断。** 已 flush 事件绝不重写。崩溃可留下未关闭最终轮次，其事件真实且可能很大；`load` 保留它们，并持久追加合成 closer（ `tool/result` ，再添加 `step/end?` +`turn/end {interrupted}` ），以平衡日志，并确保重新载入的历史仍是有效的提供方 transcript（文本记录） 。只丢弃从未完整写入的撕裂尾部碎片。
- **连续 seq。**`load` 拒绝日志中间的 `seq` 缺口/解析错误；`append` 的第一个 `seq` 必须等于已存储 next-seq。
- **JSON 可序列化数据。**`append` 通过共享单遍无损 JSON 边界实体化每个直接/回放批次。实时 `Session` 事件已深度冻结，但写入协调器仍将每个事件复制到持久化自有缓冲区。
- **持久性。**`append` 只在批次持久后返回。
## 写入协调器
`PersistenceCoordinator` 负责每 id 状态和串行化、每个实时会话的一个急切 写入 controller、延迟实体化、崩溃尾部修复、会话接管和完全停稳 dispose。第一方后端组合一个协调器， `PersistenceBackend` 存储钩子接口，并委托其有状态方法。因此 JSONL 和 SQLite 共享生命周期正确性，同时保留不同存储原语；见[协调器 Agent Note ](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md ) 和 [flush controller 简化 ](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md )。
`PersistenceCoordinator` 负责每 id 状态和串行化、每个活动会话各自的主动 写入 controller、延迟实体化、崩溃尾部修复、会话接管和完全停稳的 dispose（资源释放） 。第一方后端组合一个协调器，实现小型 `PersistenceBackend` 存储钩子接口，并委托其有状态方法。因此 JSONL 和 SQLite 共享生命周期正确性，同时保留不同存储原语；见[协调器 Agent Note ](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md ) 和 [flush controller 简化 ](../../../.agents/notes/implemented/simplification/2026-07-23-collapse-persistence-flush-state.md )。
每个 `session/event` 将事件复制到会话 controller， 急切 drain。并发通知共享当前 drain； ， `session/flush` 是观察屏障，会等待 controller 无当前或 pending 批次。急切 失败会记录日志并保留批次；下一次显式 flush 或后端拆卸重试，并向调用方公开失败 。
每个 `session/event` 将事件复制到会话 controller， 立即 启动 drain。并发通知共享当前 drain； ， `session/flush` 是观察屏障，会等待 controller 无当前或 pending 批次。即时写入 失败会记录日志并保留批次；下一次显式 flush 或后端拆卸会 重试该批次，并将失败返回给调用方 。
崩溃修复只适用于冷状态。对于实时 id， `load(id)` 为权威内存日志制作快照，等待该快照持久，并只在平衡时将其与协调器已存储 header 一起返回；开放实时轮次会被拒绝，而不会收到合成中断 closer。冷 load 在后端读取和修复写入期间保留 id， `Session` 的并发发布会拒绝并回滚。HMR 接管通过 `loadStored` 读取，应用协调器 cwd 检查，并绝不关闭活动轮次。
后端读取会在当前形状验证前，规范化消息标识机制引入前的 `user/message` 、`assistant/message` 、`tool/result` 以及 steering（ ） `steering/message` 载荷。每条导入消息都会获得确定性的 id `legacy-message:<session-id>:<event-seq>` ；工具结果的内容替换会继承其目标导入后的 id。协调器对 `load` 、`inspect` 、无 owner 状态的认领和 HMR 前缀接管使用同一份规范化视图，因此恢复后的会话可以追加当前事件，不会被误判为发生前缀冲突。存储仍然仅追加：读取不会重写旧记录，此后追加的每个事件都使用当前形状。这是[消息标识机制引入前的消息恢复决策 ](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md )所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
后端读取会在当前形状验证前，规范化消息标识机制引入前的 `user/message` 、`assistant/message` 、`tool/result` 和 `steering/message` 载荷。每条导入消息都会获得确定性的 id `legacy-message:<session-id>:<event-seq>` ；工具结果的内容替换会继承其目标导入后的 id。协调器对 `load` 、`inspect` 、无所有者 状态的认领和 HMR 前缀接管使用同一份规范化视图，因此恢复后的会话可以追加当前事件，不会被误判为发生前缀冲突。存储仍然仅追加：读取不会重写旧记录，此后追加的每个事件都使用当前形状。这是[消息标识机制引入前的消息恢复决策 ](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md )所规定的范围受限的导入例外，并不构成通用的 v0 迁移承诺。
实时会话发出 `session/disposed` 时，协调器等待其 controller， ， `Session` 对象拥有的状态。失败退役会将 controller 保留在实时会话 map 中， ， ，
无副作用 `locate` 和轻量 `listSnapshots` 查询仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方的精确 信号传入 后端发现，使观察者可在不脱离该工作的情况下取消。
无副作用 `locate` 和轻量 `listSnapshots` 查询仍由后端负责，因为它们描述存储拓扑和修订身份，而非写入编排。`listSnapshots(signal?)` 将调用方传入的同一个 信号传给 后端发现流程 ，使观察者可在不脱离该工作的情况下取消。
`PersistenceBackend<TornMarker>` 钩子（协调器与存储之间的唯一 seam） ：
| 钩子 | 职责 |
|---|---|
| `name` | dispose 失败 `AggregateError` 的后端标签。 |
| `loadStored(id, signal?)` | 在全部存储范围中按 id 读取已存储前缀。用于 resume/load、非变更 inspect、实时接管和 create 冲突探测。可选信号属于仅观察读取。返回元数据标识 `id` ；当且仅当必须截断撕裂尾部时才存在不透明 `tornMarker` 。 |
| `loadStored(id, signal?)` | 在全部存储范围中按 id 读取已存储前缀。用于恢复／加载、非修改式 inspect、实时接管和 create 冲突探测。可选信号属于仅观察读取。返回元数据标识 `id` ；当且仅当必须截断撕裂尾部时才存在不透明 `tornMarker` 。 |
| `loadStoredFrom?(id, fromSeq, signal?)` | 服务 `readFrom` 背后的可选可寻址后缀读取：返回 header 和 `seq >= fromSeq` 的已存储事件， `WHERE seq >= ?` ）；不实现的后端使用协调器回退——`loadStored` 加向前跳过。 |
| `appendBatch(meta, events, isMaterialized)` | 持久追加连续批次；尚未实体化时以原子方式延迟实体化。 |
| `commitRepair(meta, tornMarker, closers)` | 使崩溃修复持久：截断撕裂尾部（当且仅当 `tornMarker !== undefined` ；标记可为 falsy， `0` ），并追加 `closers` 。不要求原子性。由 load（ ） （ ）
| `list(signal?)` | 列出全部已存储元数据，观察 可选取消。 |
| `list(signal?)` | 列出全部已存储元数据，并遵循 可选的 取消信号 。 |
| `close?()` | 可选生命周期拆卸（例如关闭 db 句柄），在 dispose drain 后等待。 |
协调器断言已存储 id， `inspect()` 路径验证并克隆前缀，不调用 `commitRepair` 或发布写入状态。`tornMarker` 完全不透明：协调器只测试 `!== undefined` ，并将其原样往返给 `commitRepair` ， （ ， ） ， 写入协调器 Agent Note ](../../../.agents/notes/implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md )。
## 测试后端
导入 `runPersistenceContract` （公开 API， `tests/contract.ts` ；再导入 `runCoordinatorContract` （ ： ） ， `tests/coordinator-contract.ts` ，并使用后端 fixture 调用两者。每个后端都遵守相同仅追加/连续 seq/延迟实体化/可序列化语义和相同编排，因此后端自身 spec 只需在其上测试存储机制（ ；
导入 `runPersistenceContract` （公开 API， `tests/contract.ts` ；再导入 `runCoordinatorContract` （ ： ） ， `tests/coordinator-contract.ts` ，并使用后端 fixture（测试前置数据） 调用两者。每个后端都遵守相同仅追加/连续 seq/延迟实体化/可序列化语义和相同编排，因此后端自身 spec 只需在其上测试存储机制（ ；
三个后端运行这些套件：内存参考（位于 `tests/` ）、`dsh-session-persistence-jsonl` （仅追加文件日志）和 `dsh-session-persistence-sqlite` （ `node:sqlite` ，每个 `SessionEvent` 是一行 `(session_id, seq, type, time, data, source_event_seqs, surface_op)` ）。它们全部通过同一契约 + 协调器套件，证明 seam 真正与后端无关：
@@ -70,18 +70,18 @@
#### 模型所见
该 seam 不添加提示词或 schema。Resume 将已存储接口事件恢复 为消息历史；已存储请求 header 重建较早调用，新 loop 则为下一次请求组合当前系统提示词、工具和会话前缀。崩溃修复将没有持久调用的 assistant 请求标记为 `TOOL_NOT_STARTED` ；有持久调用但无结果时变为 `TOOL_OUTCOME_UNKNOWN` ，其文本允许模型重试只读或幂等工作，但要求验证副作用或请求 用户，而不是盲目重试。
该 seam 不添加提示词或 schema。恢复会将已存储的表层事件还原 为消息历史；已存储请求 header 重建较早调用，新 loop 则为下一次请求组合当前系统提示词、工具和会话前缀。崩溃修复将没有持久调用的 assistant 请求标记为 `TOOL_NOT_STARTED` ；有持久调用但无结果时变为 `TOOL_OUTCOME_UNKNOWN` ，其文本允许模型重试只读或幂等工作，但要求验证副作用或询问 用户，而不是盲目重试。
#### Token 影响
普通持久化期间为零 token。Resume 恢复已保留历史成本，并正常支付当前请求 envelope； 保留错误文本。
普通持久化期间为零 token。恢复后会重新计入保留历史的 token 用量，并照常计入当前请求 envelope 的 token 用量；每个已修复调用都会增加一段以引用形式 保留的 错误文本。
#### KV 缓存 影响
#### KV Cache 影响
持久化不修改实时请求前缀。只有当重建历史、当前 envelope 和模型路由匹配时，恢复 loop 才能重用提供方缓存；崩溃修复结果仅追加，不重写较早历史。
## 已知限制与待完成工作
## 已知限制与暂缓事项
- **无删除或保留接口**：剪枝已存储会话是带外后端维护。
- **`list()` 无分页且无过滤**：它返回每个已存储会话的 header； ，
- **修复时合成 closer 是唯一崩溃方案**：后端必须在 load 时合成 `tool/result` /`step/end` /`turn/end` closer； resume 。
- **修复时合成 closer 是唯一崩溃方案**：后端必须在 load 时合成 `tool/result` /`step/end` /`turn/end` closer； 恢复 。
xjt