Session Storage

Session storage 是 profile-local。SQLite 是权威来源；raw logs 和 blob files 是 recovery、retention 和 large-payload storage helpers。

SQLite Repositories

Repository structs 位于 internal/state。聚合的 state.Repositories 会传给需要 storage 的 gateway/runtime services。

不要从 UI 或 channel code 绕过 repositories。需要新 query path 时，添加 repository methods 和 tests。

SessionRecord 存储 session ID、title、scope columns、provider/model snapshot、timestamps、 archive status 和 metadata。

Role 作为 profile-local persona metadata 存储，并通过 legacy scope columns 保持兼容。Role 不是 profile 或 permission boundary。

Turn records 跟踪 active 和 completed user turns。Gateway 在调用 loop 前创建 running turn，并在 completion、cancellation、approval stop 或 error 后更新 status。

Messages 存储 conversation parts。Attachment parts、tool-call parts、tool-result parts 和 externalized raw references 都用结构化 records 表示。

Search 和 context windows 应使用 repository queries，而不是直接扫描 raw files。

Tool calls 和 results 与 messages 分开存储，以便 audit、approval、debug 和 result references 可以直接寻址它们。

Large result content 可以 externalize 到 raw/blob storage，而 visible result 保留 bounded preview。

Raw logs 位于 raw/YYYY/MM/DD/<session>.jsonl。Blob storage 保存由 hash 引用的大型或二进制 payloads。

Maintenance code 拥有 compaction、checkpointing、retention、raw reconciliation 和 lifecycle migration。执行破坏性 state maintenance 前先创建 backup。