Session historical data compatibility
Session 历史数据兼容
Users care whether old conversations still open after an upgrade, not about internal class names. The abstraction refactor must not incidentally change disk bytes or require manual session moves. The current `0.1.5-rc.1` checkout writes Session format V3 and includes the released-format migration chain through V3.
English
Problem
Users care whether old conversations still open after an upgrade, not about internal class names. The abstraction refactor must not incidentally change disk bytes or require manual session moves. The current 0.1.5-rc.1 checkout writes Session format V3 and includes the released-format migration chain through V3.
Proposal
Start with 0.1.5-rc.1 / V3
V3 is the current durable Session format, not a projection-cache version. SESSION_FORMAT_VERSION is the writer authority; the format catalog owns the released v0→v1→v2→v3 path, including the dedicated V2-to-V3 stage and its delivery guards. Native V3 validation and incoming historical migration remain separate responsibilities.
Do not overwrite old generations or auto-downgrade. Migration writes a new current generation and retains old committed generations for inspection and recovery. A current runtime can open released older formats through the catalog; an older runtime is not promised to read V3.
Effect on ordinary users
Stages 1–3 only rearrange code ownership. They do not change V3 Session JSONL bytes, SESSION_FORMAT_VERSION, or the user startup flow. Ordinary users need no extra manual migration or configuration change for this refactor. On first open of a supported old format, the existing migration pipeline prepares and publishes a current V3 generation. Large logs use streaming stages to avoid whole-artifact memory peaks.
Users should still keep normal backups of DSH_HOME before upgrades. If open fails, preserve the full session generation and error text instead of deleting old files. Future providers must distinguish unsupported future versions, corruption, ownership conflicts, and migration failures. The system rebuilds query indexes and other derived data; users do not migrate them manually.
Invariants after provider replacement
Replacing the in-memory implementation, JSONL provider, or search index does not change logical SessionId, header, event order, fork lineage, or surface. A storage provider reads released formats. Search/statistics caches are derived data that can rebuild from canonical Session content and cannot become recovery authority.
Alternatives considered
Re-specify V3 inside the refactor. Rejected because released-data compatibility is independent of the abstraction stack. This work must preserve the existing format authority and migration evidence, not create a parallel definition.
Treat every component version named V3 as Session V3. Rejected because Session logs and derived formats such as projection caches have different durability and recovery rules.
Acceptance criteria
- The existing V3 catalog, V2-to-V3 stage, native validation, and released-format fixtures remain green.
- Stages 1–5 and provider extraction do not change V3 disk format. A future format change has a separate version, migration, restart, and rollback evidence.
- Users do not edit logs manually. Failures preserve recoverable data and report a precise category.
Risks
The main risk is accidentally coupling the new abstraction to V3's current JSONL provider, or treating a rebuildable projection cache as canonical Session data. Provider replacement must preserve the released-format contract while keeping physical layout outside ordinary feature code.
中文
Problem
用户关心升级后旧对话是否仍能打开，而不是内部类名。抽象重构不能顺带改变磁盘字节或要求手工搬移会话。当前 0.1.5-rc.1 checkout 写入 Session format V3，并已包含贯穿 V3 的 released-format migration chain。
Proposal
从 0.1.5-rc.1 / V3 开始
V3 是当前 durable Session format，不是 projection-cache version。SESSION_FORMAT_VERSION 是 writer authority；format catalog 拥有 released v0→v1→v2→v3 路径，其中包括独立 V2-to-V3 stage 及其 delivery guards。原生 V3 校验与历史格式进入迁移是两项独立责任。
不得覆盖旧 generation 或自动降级。迁移写入新的 current generation，旧 committed generation 留给检查与恢复；当前 runtime 可通过 catalog 打开已发布旧格式，但不承诺旧 runtime 能读取 V3。
对普通用户的影响
阶段 1–3 只重排代码所有权，不改变 V3 Session JSONL bytes、SESSION_FORMAT_VERSION 或用户启动方式。普通用户无需因本次 refactor 额外手工迁移或更改配置。首次打开受支持的旧格式时，现有 migration pipeline 会准备并发布 current V3 generation；大日志使用流式 stage，避免 whole-artifact 内存峰值。
升级前仍应保留 DSH_HOME 的常规备份。若打开失败，应保留完整 session generation 与错误信息，不要删除旧文件；未来 provider 也必须把 unsupported future version、corruption、ownership conflict 和 migration failure 区分报告。查询索引与其他派生数据由系统重建，用户不需要手工迁移。
Provider 替换后的不变量
更换内存实现、JSONL provider 或搜索索引不改变逻辑 SessionId、header、事件顺序、fork lineage 和 surface。Storage provider 负责已发布格式读取；search/statistics cache 是派生数据，可从规范 Session 内容重建，不能反向成为恢复权威。
Alternatives considered
在 refactor 内重新定义 V3。 拒绝；已发布数据兼容独立于抽象 stack。本工作必须保留既有 format authority 与 migration evidence，而不是另建平行定义。
把每个名为 V3 的组件版本都当作 Session V3。 拒绝；Session log 与 projection-cache 等派生格式有不同 durability 和恢复规则。
Acceptance criteria
- 既有 V3 catalog、V2-to-V3 stage、native validation 与 released-format fixtures 保持通过。
- 阶段 1–5 与 provider 抽取不改变 V3 磁盘格式；未来格式变化另有版本、迁移、重启和回滚证据。
- 用户不需手工编辑日志；错误保留可恢复数据并给出明确类别。
Risks
主要风险是把新抽象耦合到 V3 当前 JSONL provider，或把可重建 projection cache 当作规范 Session 数据。替换 provider 必须保持 released-format contract，同时让普通功能代码看不到物理布局。