Session Projection zh

会话投影

上游日志派生状态投影系统在 Edge 中的适配。

上游参考：会话投影文档

上游提供了什么

会话投影是一项能力接缝，让领域插件向客户端提供从已提交事件日志计算的派生状态值。包含两个服务：

• SessionProjectionRegistry（ctx.sessionProjections）— 驱动计算：订阅 session/event，对每个已提交事件调用各注册单元的同步 apply()。提供 snapshot() 一致性读取、checkpoint() 持久化、restore() 冷日志重放。
• SessionProjectionCache（ctx.sessionProjectionCache）— 持久化层：节流 write-behind 检查点、通过 cachedSnapshot() 零 I/O 列表读取、通过 coldSnapshot() 冷 session 尾读 + 重放。在 session/disposed 时清理。

领域插件注册投影单元（如 GoalService 注册 'goal'，SessionTitleService 注册 'title'）。每个单元的 apply() 必须同步、返回纯 JSON、且在事件不影响其状态时保持引用相等。

Edge 改了什么

直接复用 两个服务

SessionProjectionRegistry 和 SessionProjectionCache 全部原封安装。注册表驱动计算，缓存通过 storageDomain（由 DurableObjectStorageBackend 支撑）处理持久化。所有投影单元注册（goal、title、sessionListMetadata）来自上游插件。

传输桥 WebSocket 投影推送

上游客户端从进程内内存读取投影。Edge 通过 sessionProjections.onChanged() 捕获变更，以 session/projection WebSocket 帧推送。桥在事件发生时同步缓冲条目，在 publishSessionEvent() 中按 seq 匹配 drain——确保投影在其对应事件持久化后才到达。

sessionListMetadata 是唯一例外：它在 publishSessionEvent() 中使用独立推送和自己的 fold 逻辑，因为其计算依赖注册表未管理的 Edge 特定会话列表元数据。

传输桥 初始 baseline

session.history 和 session.list 在响应中包含投影值。热 session 读 projectionSnapshot()，冷 session 降级到 projectionCachedSnapshot()（从缓存服务同步领域读取）。

Edge 没有改什么

• 投影单元契约（同步 apply、纯 JSON 状态、引用相等）
• 注册表驱动机制（session/event 订阅）
• 缓存写入时机（节流 write-behind）、生命周期清理、冷快照恢复
• Snapshot/checkpoint/restore API 语义

性能特征

逐事件驱动代价

drive() 遍历所有注册单元（当前：goal、title、sessionListMetadata），调用各自的 apply()。每个 apply 是常量时间的 last-wins fold。onChanged 回调仅在值的引用变化时触发（引用相等检查），不影响的事件产生零下游工作。

推送时序

投影帧在事件发生时同步捕获（正确的值 + 正确的 seq），在事件 flush 完成后 drain（持久化交付保证）。缓冲区按 entry.seq <= event.seq 过滤，防止后续 seq 的投影在其事件之前到达。

冷 session 读取

| 路径 | 代价 | 使用者 |

|---|---|---|

| projectionSnapshot() | O(1) — 内存读取 | 热 session |

| projectionCachedSnapshot() | O(1) — 同步领域读取 | 冷 session 列表 + 历史 |

| coldSnapshot() | O(尾部事件数) — 尾读 + 重放 | 缓存未命中时的历史 |

架构总结

| 组件 | 分类 | Edge 代码 |

|---|---|---|

| SessionProjectionRegistry | 复用 | 一行 ctx.plugin() 调用 |

| SessionProjectionCache | 复用 | 一行 ctx.plugin() 调用 |

| WebSocket 投影推送 | 桥接 | onChanged → 缓冲 → seq 匹配 drain |

| 初始 baseline 合并 | 桥接 | summaryProjections() 合并缓存值 |

关键观察：投影系统是上游业务插件和 Edge 传输层之间的连接组织。上游插件注册单元并计算值；Edge 只添加网络传输通道。计算引擎和持久化缓存完全由上游提供。