持久化与数据库设计

结论：持久化是一组数据所有权合同，而不是一个笼统的“数据库”

这种分离是本章最重要的结论。JSONL 与 SQLite 是同一 Session 合同的替代物理 provider，但通用 JSON/SQLite backend 并不是 Session 数据库。同样，Workspace 的归组记录不等于对 transcript 的外键所有权，attachment reference 也不等于对象本身。

1. 所有权地图阻止意外级联

2. SessionPersistence 是行为 seam，不是 CRUD repository

create(header)              // 预留 identity；可以只存在于内存
append(id, contiguousBatch) // 只在耐久后 resolve
inspect(id)                 // 平衡的逻辑视图；不做物理修复
load(id)                    // Cold 时提交修复，再返回平衡视图
prepare(id)                 // 为 Resume 独占预留 exact unpublished Session
readFrom(id, seq)           // 分离、非突变的 stored suffix
list / listSnapshots        // 只列已 materialize 的日志

这个 seam 把崩溃语义写进了接口。完整且有效、但中断的最后一个 Turn 会被保留，并以确定性 closers 闭合；provider 返回连续前缀，以及它判定为不可恢复后缀的不透明 marker。这个抽象比字面上的“部分物理记录”更宽；第 6、8 节会审计具体分类。已 create、从未 append 的 Session 可以完全不留下 artifact。因此不能用普通增删改查替代 SQLite 实现——provider 必须实现 append 连续性、identity、repair 与静止关闭。

3. Coordinator 才是真正的可移植层

PersistenceCoordinator 拥有延迟 identity 冲突检查、write-behind controller、按 ID 串行化、prepared-session cache、live adoption、crash-repair sequencing、revision retry 与 disposal。Provider 只贡献介质 primitive，无需重写这套状态机。

4. Write-behind 把热路径接纳与耐久静止点分开

session/event → structuredClone → pending queue
                 首个 item 启动固定 deadline
deadline → stable batch → backend append
failure  → batch 恢复到队首；暂停自动重试
flush    → 取消 timer → 加入 active write → 重试并排空

后续 event 不会延长当前 batching deadline。一次写入期间接纳的 event 会形成 follow-up batch。后台失败会被报告，同时 exact batch 仍被保留；显式 flush 是重试与 quiescence barrier。Backend disposal 会先排空 controller，再关闭介质。

5. JSONL 是一种逻辑事件流，对应两种物理编码

配置 root 必填，并在 constructor 中只 resolve 一次，因此后续 process.cwd() 变化不会拆散同一 backend。Session ID 在成为路径 segment 前会做 injective escape。Repair 或 append 前会检查 Header identity 以及由 cwd/id 推导的路径；混用 compression suffix 的 root 或已退役 flat layout 会被拒绝，而不是猜测。

6. JSONL 的耐久性很强，但 Repair 刻意分成两个阶段

Raw mode 只容忍不完整的最后一条 record，或严格位于最后一个 committed turn/end 之后的缺陷。Zstandard mode 会拒绝损坏的完整 frame，但可以从结构不完整的 final frame 中抢救已经输出的完整 JSONL records。它从该 frame 起点截断，只重写 recovered records 与 closers，不会改写更早的 committed prefix。

7. Session SQLite 把同一日志合同映射为 STRICT rows

数据库同时携带 application_id 与 user_version。Pristine database 会初始化并 stamp；非空未版本化 database、外来 application identity，或 SCHEMA_VERSION = 15 之外的任何版本都会拒绝。尽管字段名叫“version”，这个 pre-release 实现没有 migration path。

8. SQLite Append 与 Repair 获得事务原子性和真正的 Suffix Read

首次 materialization 与其 batch 中的每个 event 在一个 transaction 内提交。后续 append batch 同样如此，并只让 Session revision 增加一次。Load 在同一事务快照中扫描完整 row set，找出第一个 invalid tail seq，再用一个 transaction 删除 seq >= tornMarker、插入确定性 closers，并递增 revision。

9. 文档中的 WAL 默认值存在 Direct-constructor 陷阱

通用 SQLite storage backend 也出现相同形状：Schemastery 承诺 WAL 默认值，但 public constructor 强制转换一个缺失的 optional value，随后 open path 解引用它。经 Loader/schema normalization 的 plugin 构造是安全的；没有传 journalMode 的直接程序化构造则不是。

10. 通用 Storage 刻意比 SessionPersistence 知道得更少

Storage hub
  ├─ backend registry: name → 一个介质与可选 facets
  └─ mounted forms: 当前为 domain

KV backend contract
  open(unit descriptor) → loadAll / putRecord / deleteRecord / setGlobal / close

Domain form
  spec + zod schemas + route → authoritative memory + 单写入 chain + change events

对 backend 而言，KV value 是不透明 JSON。Unit 保证每次单独调用原子且耐久，但明确不串行化并发调用。Domain 层补上这一顺序，在 open 时校验数据，先完成 backend durability，再修改内存 Map，只有两者一致后才发出 domain/changed。

通用 SQLite provider 在 units 中为每个 unit 保存一行，在 unit_globals 中保存可选 global row，并为每个声明表创建一个 STRICT u_<unit>_<table> table。它的物理 user_version 为 1；其他 stamped layout 会拒绝，而不是 migration。每次 KV mutation 是一条 prepared statement，因此 provider 提供单次调用原子性，Domain 仍负责写序。PERSIST-STORAGE-SQLITE-SCHEMAPERSIST-STORAGE-SQLITE-UNIT

11. JSON KV 发布认真处理了耐久性，但相对 Root 仍是动态的

每次 JSON KV mutation 都会重新发布整份 human-readable unit file。Writer 创建同目录、owner-only 的临时文件，写入并 fsync，以 atomic rename 覆盖 target，然后在 POSIX 下 fsync 父目录。Windows 通过 libuv 获得 atomic replacement，但没有显式 write-through flag。实现也没有跨进程 writer lock。

12. Domain Close 存在一种单向失败状态

Happy path 是可靠的：close() 立刻拒绝新写入，排空已经 settle 的 write-chain tail，关闭 backend unit，把读取标记为 closed，最后释放 facility 的 name reservation。重复 close 会共享同一个 Promise。

13. Attachment 使用 Commit-before-reference 与内容寻址 Ownership

Deduplication 是安全的，因为接受既有对象前会重新读取并 hash。Read 会重新 hash bytes，把存储 metadata 与日志 reference 对比，并保留 cancellation。由于 resumed/forked Session 可能共享对象，所有对象会无限期保留；删除 Session 或 Workspace 都不会隐式 garbage-collect 它们。PERSIST-ATTACH-LIMITS

14. Attachment 的 Read-time Decode 文档不正确

实现仍然验证 integrity 与 reference metadata；漂移涉及的是计算工作和 malformed-payload revalidation，而不是跳过 digest verification。文档应改成“admission 时完整 decode；read 时先验证 digest，再 probe Header”。

15. Workspace 是 Domain State 之上的可恢复两次写 Registry

workspace domain（version 2）为每个 Workspace 保存一条 record——canonical path、title、有序 candidate Session IDs 与 timestamps——并以 global state 保存 initialized、Workspace order、archive IDs 与可选 pending create/delete marker。首次启动只列 Session Header，规范化有效 cwd 目录，对其分组，并把 initialized marker 放到最后写。PERSIST-WORKSPACE-INITPERSIST-WORKSPACE-BOOTSTRAP

Create/delete 无法成为一个通用 cross-record transaction，因此 Registry 会在 record/order pair 可能分叉前先写 pending marker。启动时只完成被 marker 点名的 mutation；无法解释的 order/table、duplicate path 或 duplicate-session ownership 仍会 fail loud。删除 Workspace 只删除注册与 account，绝不删除目录、文件、live Session、persisted log 或 attachment。PERSIST-WORKSPACE-MUTATIONPERSIST-WORKSPACE-OWNERSHIP

16. Workspace 的 Title、Schema 与 Refresh 合同存在可见缺口

17. 一个有用的 Codex 对照：介质相似，权威性拓扑不同

对 Codex 用户来说，文件名很容易造成误解。在 Codex 官方公开仓库提交 66919805ea080053d1933b6b43afeb0d8bf70c91 上，rollout module 明确说 JSONL Session rollout 会被持久化，以便 replay 或后续 inspection；recorder 会把 canonical rollout items 写入 JSONL。公开 config 把 sqlite_home 定义为 SQLite state DB 的目录；App Server 的 thread/list 合同说明默认路径可以扫描 JSONL rollout 来修复 metadata，而 useStateDbOnly 会关闭该行为。

18. 审计结论：合同扎实，并有七个具体后续项

• 在 Constructor 边界 Normalize SQLite Defaults。修复两个 direct-constructor journalMode 路径，或要求 normalized config type。
• 准确命名 Torn-tail Policy。明确两种 provider 都可能丢弃最后一个闭合 Turn 后、物理完整但异常的 records；在无法确认物理撕裂时，考虑保留诊断信息或要求显式 repair。
• 解决 JSON KV 发布后失败。目录 sync 在 rename 后失败时，让 Domain、unit memory 与已发布 target 进入定义清楚的状态。
• 冻结 JSON KV Root Identity。像 Session JSONL 一样，只 resolve 一次显式 relative root。
• 定义失败的 Domain Closure。明确 retry 与 name-release 语义，避免 close error 留下 readable-but-unwritable handle。
• 修正 Attachment 文档。明确 admission 时完整 decode，read 时执行 digest + Header verification。
• 收紧或明确 Workspace 边界。删除已无 caller 的 create-time title 分支，按意图校验用户可见 title/timestamp/ID，并提供 runtime full refresh，或停止承诺它。

系统的中心设计仍然连贯：耐久事实有明确 owner，provider 共享同一份 Session 合同。Recovery 对最后一个闭合 Turn 以内的历史保持保守，而最终 open tail 遵循更宽的策略，应该被准确命名。静态缺口集中在 repair classification、发布后失败、configuration、lifecycle、documentation 与 cache refresh 边界，并不是对 event-log 所有权认识混乱。