ZiyaZhang
8ea5cdd894
146 篇 RFC 译文按 v4 基线（#348）重出：v4 模板+术语表、金标 few-shot、三段协议、切换行后处理；全量机械核对零异常（一处 task id 术语违规已修）。三篇超长 RFC（code-mode 已入，web-seam/ agent-scope/sandbox/cds-core 仍在长文档通道产出）随后补。
5.2 KiB
RFC：源端拥有的会话不可变性与开发模式不变式
Status: implemented
English | 中文
问题
会话日志需要两种不同的保护：对每条已存储事实的不可变所有权，以及对跨时间和服务 seam 的事实之间关系的检查。如果将二者混为一个可选的开发插件，生产环境的历史记录将失去保护；如果试图通过 TypeScript readonly 类型同时表达两者，既无法建立运行时边界，也无法描述关系规则。
会话日志是回放、请求重建、持久化与用户可见历史的持久真源。会话包（package）外部的代码必须能检视历史，但不能保留一个可在之后改写历史的引用；从调用方接受的输入也不能继续连接到调用方拥有的可变对象。
单个值的不可变性只是契约的一半。一份日志可以包含完全不可变的记录，但其序列、轮次/步骤嵌套、工具调用配对、作用域分发或重建的模型请求是错误的。这些规则涉及多条记录或多个服务，无法通过冻结单个对象来建立。
TypeScript readonly 类型不是充分的运行时边界。它们在程序运行时消失，类型转换可以绕过它们，而递归的 DeepReadonly<T> 会扩散到每个日志和消息消费方，尽管某些下游请求处理 API 有意使用可变值。
决策
职责在始终启用的存储边界与可选的开发断言之间分离。
Session 拥有不可变历史
Session 仅在一次递归遍历完成无损 JSON 快照的物化之后才接受事件。该遍历拒绝不支持的值，并产出进入日志的确切分离记录，因此验证与存储不会从有状态的 getter 观察到不同的值，也不会保留调用方拥有的嵌套引用。
被接受的事件及其所有后代在发布前被深度冻结。append() 返回该拥有的冻结事件，session/event 观察者接收同一记录，session.events 返回冻结的数组快照。先前返回的数组不会因后续 append 而增长。种子记录在构造成功前经过相同的验证、快照与冻结边界。
此保证属于 Session 而非可选监听器，因为每种组合都依赖可信的历史。无论是否注册了开发支持插件，生产部署、聚焦测试或自定义嵌入都获得相同的存储语义。
派生请求保持分离
deriveMessages() 将已记录的表面事件投影为分离的、深度冻结的 Message 对象，并返回一份新的数组快照。因此请求组装可以将派生历史与其他输入组合，而不会暴露一条回到日志的路径。缓存复用安全的不可变投影，而非为每次模型调用重新克隆完整历史。
不变式插件检查关系
dsh-invariants 是一个纯监听器的开发插件。它不冻结记录，没有配置；dispose（资源释放）仅移除其断言。它检查需要跟踪状态或观察另一个 seam 的规则，包括单调递增的序列号、轮次与步骤嵌套、工具调用/结果配对、合法的 agent（智能体）状态转换、主体正确的作用域分发，以及循环构建的请求与从其会话日志前缀重建的请求之间的等价性。
当插件附加到已有或已播种的会话时，它回放不可变日志以重建跟踪状态。这使得在轮次中途热重载是安全的，同时不赋予插件对会话存储的所有权。
曾考虑的替代方案
全面的 deep-readonly 类型
被否决的不可变公共表面提案会在公共日志和消息表面上应用递归 readonly 类型。这能提供编辑器反馈，但无法提供运行时保证：TypeScript 类型在运行时被擦除，插件代码可以通过类型转换绕过。它还会将 readonly 类型推入有意进行修改的消费方。在 Session 边界处的运行时所有权保护所有调用方，无需这种类型传播。
仅在开发模式冻结
仅当不变式插件安装时才冻结历史，会使核心保证依赖于组合方式。代码可能通过开发测试，却在生产环境或省略了该插件的聚焦组合中破坏历史。因此存储不可变性始终启用，而开销更大的关系检查则保持为可选的开发支持。
仅在派生消息时克隆
分离 deriveMessages() 能保护最常见的请求路径，但 session.events 的其他读取者、append 返回值和会话事件观察者仍能修改持久历史。日志必须保护自身的边界；派生投影是额外的隔离边界，而非替代品。
后果
- 每个被接受的实时或种子会话事件在任何观察者接收之前，都已从调用方拥有的输入中分离并深度不可变。
session.events暴露稳定的不可变快照，而非私有的增长数组。- 请求侧的修改无法通过派生消息触及已存储的历史。
- 开发构建可以启用关系断言而不改变存储行为；dispose 或省略该插件不会削弱日志不可变性。
dsh-invariants没有Config表面，因为它没有可调节的行为。- 运行时边界对每个被接受的事件产生一次递归快照与冻结的开销；后续读取者和缓存投影复用已拥有的不可变记录。