docs(usage): design revision-consistent screen reads

[Sun-GLiang]

Summary

Settings Usage should install its statistics, breakdowns, pricing/coverage, and first activity page from one Storage read transaction and one opaque revision. Further activity pages carry that revision and receive rows only while it still matches. A mismatch returns revision_changed; Host retains no per-reader Usage dataset and Desktop never combines different revisions.

This is a design-only draft for #4058, following the maintainer's P1 review and Storage/protocol rules. It does not introduce or evaluate new performance budgets, bounded-admission thresholds, arbitrary-history availability, or incremental aggregate projections.

The latest inspected main baseline is 1ae4d5b89. Its renderer paginates the already-loaded activity array, but Desktop still constructs one Usage screen from independent summary, LLM-log, tool-log, and pricing reads. The consistency defect therefore remains.

Design: Revision-consistent Usage screen reads.

Review focus

The document now gives an author proposal, an alternative, and a specific confirmation request for every remaining Storage decision:

• Query boundary — likun: propose screen/page reads on the existing Usage facade with one internal synchronous transaction module; direct facade implementation remains an alternative.
• Repair boundary — likun: propose explicit Host-requested repair through the existing writer, followed by the screen read; an explicitly writable Storage wrapper remains an alternative.
• Revision — likun: propose a root-scoped durable Usage counter combined with existing pricing revision and Host fencing; narrowly scoped triggers or an equivalent mutation-sensitive revision remain alternatives.
• Cursor — likun: propose (timestamp, source, stableStorageIdentity); an equivalent globally unique Storage ordering key remains an alternative.
• Restore fencing — likun: propose database-incarnation identity plus Host generation; an equivalent lifecycle identity remains an alternative.
• Host and Desktop behavior: fence old Host generations, atomically install complete screens, append only matching-revision pages, and retain a visible stale screen on revision_changed until Refresh.
• Existing semantics: preserve accounting composition, unpriced versus zero, Session-independent Usage history, and range-wide activity search/status filtering.

Agreement with this document is design agreement, not implementation approval.

Explicit non-goals

• New scan, sort, latency, memory, or availability targets.
• Bounded-admission limits or a new limit_exceeded product state.
• Exact-query guarantees for arbitrary history sizes.
• Incremental aggregate/completeness projections.
• Additional breakdown/pricing pagination or a general query framework.
• Retention changes, retroactive repricing, exports, or coverage UI redesign.

Existing protocol item and encoded-byte limits remain wire safety constraints.

Implementation outline

• Define the cross-package consistency contract and concrete Storage review choices.
• Select the Storage transaction API, revision mechanism, writer coverage, and cursor schema.
• Implement the Storage initial-screen and revision-checked continuation operations.
• Add Runtime Host protocol and Desktop IPC/preload support; raise the compatibility epoch above main.
• Replace Desktop's independent reads and activity drain with atomic screen installation and on-demand continuation.
• Add real-SQLite race, revision, accounting, cursor, protocol, Host-replacement, and Desktop stale-screen tests.
• Run affected tests, typecheck, lint/format, ASF checks, and the epoch guard before ready-for-review.

Verification

• Static source baseline: 1ae4d5b89 on 2026-09-15.
• Documentation whitespace check: passed.
• ASF header check: passed for 3,602 covered files.
• No runtime code changed; runtime tests and performance benchmarks were not run.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Codex inspected the latest main Usage path and rewrote the design to isolate #4058's consistency contract and make its remaining Storage choices reviewable. Sun-GLiang is the contributor of record. Documentation commits carry Generated-by: Codex.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

These implementation checks remain pending; this draft changes documentation only.

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

The current diff has no runtime behavior change. Update this selection when implementation lands.

[likun666661]

从问题定义和奥卡姆剃刀角度看，我认可核心方向：单个 Storage 事务返回首屏、SQL 聚合、明细按需游标分页、后续页校验 revision，且不保留 Host 侧的整批数据快照。这比用容量、租约、释放协议维护全量副本更直接。

建议把问题定义收敛为：

Usage 应展示口径一致的统计和明细；显示一页不应要求把全量历史物化到应用内存，单次请求的工作量应有明确边界。

这里需要区分三个独立目标：数据一致性、资源有界、产品可用性。前两个成立，不自动意味着第三个成立。文档已经列出相关取舍，但建议在继续细化实现前，先明确两个产品决策：

1. 数据量超过预算时，是否允许 Usage 不可用？ 当前 bounded-admission 候选通过拒绝查询来限制工作量，不是保证任意历史规模下都能返回准确统计。尤其 completeness 是 root/session scoped，超过 source/checkpoint 上限后，Today 和 7d 也可能失败，缩小时间范围并不一定有用。请明确支持规模及超限用户行为。如果长期积累后仍必须可查准确统计，就需要评估增量聚合等架构；这时额外复杂度是需求所必需，不能仅靠提高阈值或增加重试解决。

2. 持续写入时，是否接受翻页被打断并回到首屏？ revision 校验能防止混搭，但不保留旧快照意味着版本变化后不能继续浏览原结果。root-wide counter 还可能因范围外写入而失效。请用持续调用场景验证 continuation 成功率和刷新频率，并明确可接受的交互；限制自动重试次数只能避免无限重试，不能保证可浏览性。

最小实现方向仍建议保留上述核心，以及现有计费、完整性、搜索语义。不要为简化而把未计价当成零费用，或把范围搜索缩成当前页搜索。细粒度 revision、额外列表分页、通用查询抽象则应按实际约束和证据决定，不必预先全部引入；暂不分页的集合仍需明确上限及超限行为。

另外，SQL 聚合减少的是应用侧物化、JSON 解码和传输，不自动消除随历史规模增长的扫描/分组工作；现有单源 SQLite probe 的结论边界应继续保留。

结论：支持核心方向，但先把“数据大了能否拒绝展示”和“写入活跃时能否打断翻页”定清楚，再选择具体 Storage 机制和预算。这是设计意见，不是实现批准。

---

AI-assisted：本评论由 Codex 根据本任务中的讨论整理并经用户授权发布。基于设计文档 ddae525b、#4058 和前序设计评审；未运行实现测试或端到端性能验证。