会话即日志：
SessionEvent 与事件溯源。

事件溯源心智：日志就是状态

在 dsh 里，一个 Session 不是「带历史的消息对象」，而是一份仅追加（append-only）的、 类型化的 SessionEvent 日志——它是这次 agent 交互的唯一真源。 模型看到的消息历史从不单独存储，而是每次从日志派生；回放，就是用同一组事件重新派生一遍。 这是 packages/core/session（dsh-session）的核心决策，记录在 Agent Note 2026-06-11-event-sourced-sessions 里。

这个设计有一个被明确否决的对照组：「可变消息数组 + 事件仅作通知」。那条路实现更简单， 但内存状态与日志可能悄悄分叉。事件溯源让日志本身就是状态——分歧在结构上不可能发生。 这就是它被称为全仓库中心的原因：改日志 = 改产品的记忆，下游一切（重放、分支、审计、统计）随之改变。

日志有几条不容妥协的硬约定，读代码前先把它们刻进脑子：

• seq 单调且连续：seq === log.length，不能跳号、不能过滤——连原始的流式 chunk 都占一个序号。
• 事件不可变：进入日志时被深冻结；append 是同步操作，热路径从不阻塞 I/O。
• 无损 JSON：所有 event.data 必须可无损序列化为 JSON，Session.append 在源头校验并直接拒绝坏事件。
• 先提交后广播：追加提交后通过 session/event 同步通知；持久化插件异步缓冲，在 session/flush 检查点排空。

一份持久化日志（JSONL 后端的逻辑视图）长这样——第一行是 header，之后每行一条事件：

deriveMessages()：从日志投影模型历史

日志里的大多数事件并不直接变成消息。只有三种 surface 事件——user/message、 assistant/message、tool/result——携带 surfaceOp 标记， 声明自己如何进入有序的 surface。deriveMessages() 沿 surface 节点逐条折叠纯函数 deriveEventMessage()，投影出模型看到的 Message[]。它是缓存的 （每个节点只在首次出现时投影一次，surface 被 replace 重写时重建）且冻结的 （调用方拿到共享的深冻结消息，改历史这件事在类型上就写不出来）。

投影规则一共四条，其余事件一律是结构信息：

• user/message → 一条 user 消息，content 原样呈现。注入的上下文（agent.inject() 的产物：文件变更通知、skill 内容、cron 提醒……）也是它，靠 source 字段区分来源。
• assistant/message → 一条 assistant 消息。内容为空的会被跳过（比如 max-tokens 截断且无输出的步骤），但事件仍留在日志里保存 usage、提供方与模型。
• tool/result → 一条携带 tool-result 块的 user 消息。
• turn/*、step/*、request/*、assistant/chunk 等其余事件 → 不产生任何消息。

那 assistant/chunk 为什么存在？因为它保的是另外两样东西：token 级 replay 保真和 UI 流式渲染保真。原始分片原样落日志，派生历史时却被跳过——组装后的 assistant/message 才是权威，并用 sourceEventSeqs 回指生成它的那些 chunk 的 seq。 token 记账走同一条路：读每步的 usage 分片，没有时回退到 assistant/message.usage。

压缩（compaction）是这套投影的另一半：surfaceOp: {op:'replace',start,end} 会遮蔽一段 surface 节点，让派生历史变短，而日志原文一字不动。派生成本随日志长度增长，压缩是预期的缓解手段， 不是改写日志——日志永远只增。

同一条流的派生物

因为一切皆日志的投影，下面这些看似无关的能力，共享同一条事件流：

• fork — ctx.sessions.fork(source, boundary?) 取到指定 seq 为止的前缀做种子，开出一个活跃的子会话；header 里记下 parentSession 与 seedLength。以开放轮次结尾的前缀会被拒绝，而不是静默截断。
• resume — 重启后 ctx.agents.resume({ resumeSessionId }) 用整段持久日志做构造种子；session/end-seed 事件标记「种子历史」与「本次生命周期的实时写入」之间的边界。
• transcript — 面向人类的文本记录是另一个投影，读的是追加来源的事件——surface 会有意遮蔽被 replace 概括掉的范围。
• telemetry — 订阅 session/event 的消费方；接手一份已有日志的会话时从 firstLiveSeq 开始，不重复计算种子历史。
• 持久化 — 持久化插件订阅 session/event 异步缓冲落盘，session/flush 排空。JSONL 后端（每会话一个 session.v3.jsonl.zstd）遵守同一份约定：每个事件包括 chunk 都无损保存，seq 保持连续。（SQLite 如今只以 session-query-sqlite 的身份作为查询索引层存在，不承担持久化。）

版本闸门：SESSION_FORMAT_VERSION 与 ignorable

日志是要落盘的，落盘就有格式问题。dsh-session 的 SESSION_FORMAT_VERSION 现在是 3，且这个格式已随产品正式发布——「哪个版本已发布」的单一真源是权威文档 docs/session-format-status.md。header 里的 version 在创建时盖戳， 兼容则靠相邻迁移：迁移包族 session-format-v0-to-v1、v1-to-v2、 v2-to-v3 一环扣一环，打开旧日志时沿这条链升级为当前代——写打开还会把迁移结果 发布成一个新的 generation 文件。历史 generation 一旦落盘就不可变：不移动、不覆盖、 不删除已提交的 generation，源文件逐字节保留，于是一个会话目录里可能同时躺着 session.jsonl（v0）与 session.v1/v2/v3.jsonl，运行时永远选择数值最高的那一代。 SessionFormatUnsupportedError 只拒绝没有迁移路径可走的版本——比如比当前构建更新的日志 （错误消息提示先升级 harness）——绝不猜着读。

另一条闸门在事件信封上：ignorable: true。读取器遇到不认识的事件类型时默认必须拒绝重建—— 因为一条不认识的必需事件可能改变日志其余部分的解读方式；只有丢失也不影响重建的纯信息记录， 写入方才允许标 ignorable: true 让它可跳过。默认必需意味着忘标记的后果只是「过度拒绝」 （一种不便），而不是静默恢复出一个被掏空的会话（一次事故）。这条规则由 KNOWN_SESSION_EVENT_TYPES 清单（gen-persistence-catalog 生成）在加载边界执行。

铁律：model-visible ⟺ logged

这条双向约束是整套设计的承重墙：抵达模型请求的一切，都必须能从日志重建；反过来，模型历史也只从日志渲染。 连请求信封都不例外——request/header 事件把调用配置、渲染后的系统提示词、组装好的工具 schema 一并写进日志，因此每个对话请求都是日志的纯函数。一项运行时不变量持续断言这个关系， 而不是靠 Code Review 时的人肉记忆。

它直接规定了你扩展时的动作顺序。想让模型看到一种新输入（比如一种新的环境通知），正确路径是： 先扩展 SessionEventMap 声明一个 session 事件、把它 append 进日志，再由投影把它渲染进请求。 内建的 agent.inject() 就是这个模式的实例：注入的上下文落到下一次获准的请求里， 成为一条带 source 标记的 user/message——于是 fork、resume、transcript、 遥测全都自动看见了它。

动手试：解剖一份真实日志

默认配置下，会话持久化在 ~/.dsh/sessions 下（root 来自 base 组合包里的 !!js dshHomePath('sessions')），文件是 Zstandard 压缩的 session.v3.jsonl.zstd， 不能直接按行阅读。为了看清每一条事件，我们用 L2 学过的 patch 技能做一个实验 overlay： 换成未压缩格式，并写入一个独立的 root（一个 root 只属于一种编码，混用会被拒绝）—— 新会话由当前构建写出，落盘为 session.v3.jsonl。