perf(tui): project source filters without rescanning

[makoMakoGo]

Summary

• separate the immutable TUI scan universe from session-local source selection
• project Sources and Group By changes from the installed generation without rescanning or blocking the content area
• persist source-aware canonical projection state in schema 41, with SHA-256 validation and explicit legacy/corrupt cache misses
• keep Sessions and other views aligned with source selection, while retaining universe-wide scanner health
• preserve prior data after warm refresh failures and document the architecture in ADR 0028

Validation

• cargo test -p tokscale-cli — 885 passed, 1 ignored
• cargo test -p tokscale-core — 1496 passed, 4 ignored
• cargo clippy -p tokscale-core -p tokscale-cli --all-targets -- -D warnings
• cargo fmt --all -- --check
• cargo build -p tokscale-cli --release

Performance

Five-run medians against the installed tokscale 4.8.0 binary:

Scenario	Installed	This branch
TUI warm-cache display	19.0 ms / 14,400 KiB	28.8 ms / 14,736 KiB
Source selection change	1.004 s / 22,884 KiB	25.5 ms / 18,044 KiB
Codex CLI scan	2.91 s / 24,336 KiB	2.25 s / 23,448 KiB
All-client CLI scan	7.68 s / 60,640 KiB	7.37 s / 61,660 KiB

The schema-41 TUI bundle grows from 3,309,696 to 5,044,486 bytes for the canonical source-aware projection state.

Summary by CodeRabbit

• 新功能

  • TUI 支持在已加载的数据范围内临时筛选来源，并即时更新 Usage、Sessions 和分组视图。
  • 切换来源或分组时无需重新扫描数据，支持按需生成本地投影。
  • 新增更可靠的缓存校验，检测到缓存损坏或不匹配时会自动视为未命中并重建。

• 错误修复

  • 筛选失败时自动回滚至之前的选择，并显示状态提示。
  • 防止选择未加载来源，并改善加载期间的交互反馈。
  • 优化来源筛选后会话明细与空状态显示的一致性。

• 文档

  • 补充来源全集、临时筛选、缓存与刷新行为说明。

[coderabbitai]

Warning

Review limit reached

@makoMakoGo, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 5 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7536a08f-b9c6-477a-85b2-45549dcb508c

📥 Commits

Reviewing files that changed from the base of the PR and between d17a693 and 899243b.

📒 Files selected for processing (23)

• AGENTS.md
• crates/tokscale-cli/src/tui/app.rs
• crates/tokscale-cli/src/tui/cache.rs
• crates/tokscale-cli/src/tui/interaction.rs
• crates/tokscale-cli/src/tui/mod.rs
• crates/tokscale-cli/src/tui/session_data.rs
• crates/tokscale-cli/src/tui/ui/agents.rs
• crates/tokscale-cli/src/tui/ui/dialog/group_by_picker.rs
• crates/tokscale-cli/src/tui/ui/dialog/mod.rs
• crates/tokscale-cli/src/tui/ui/dialog/source_picker.rs
• crates/tokscale-cli/src/tui/ui/dialog/stack.rs
• crates/tokscale-cli/src/tui/ui/mod.rs
• crates/tokscale-cli/src/tui/view_state.rs
• crates/tokscale-core/benches/aggregation.rs
• crates/tokscale-core/src/aggregate/keys.rs
• crates/tokscale-core/src/aggregate/tui.rs
• crates/tokscale-core/src/lib.rs
• crates/tokscale-core/src/usage_views.rs
• docs/adr/0008-single-copy-memory-pipeline.md
• docs/adr/0026-group-by-view-scope-contract.md
• docs/adr/0028-tui-source-universe-and-view-selection.md
• docs/cli.md
• docs/configuration.md

Walkthrough

PR 将 TUI 的启动来源全集与会话选择分离，支持按客户端子集本地重投影，并升级 schema-41 缓存以持久化和校验 canonical 聚合状态。对话框变更改为关闭后应用，失败时回滚。

Changes

TUI 来源选择与投影

Layer / File(s)	Summary
聚合器子集投影与序列化 crates/tokscale-core/src/aggregate/*, crates/tokscale-core/src/lib.rs, crates/tokscale-core/src/usage_views.rs	TuiAcc 按来源保存可序列化聚合数据，并新增按 selected clients 生成投影的 API。
Schema 41 canonical 缓存 crates/tokscale-cli/src/tui/cache.rs	缓存保存 canonical JSON 和 SHA-256 摘要，加载时校验结构、摘要、source universe、source space 与 session 来源。
App 与后台投影流程 crates/tokscale-cli/src/tui/app.rs, crates/tokscale-cli/src/tui/mod.rs	App 区分 source_universe、selected_clients 和 data_clients；后台加载和本地投影均传递 selected clients，失败时回滚并统一报告状态。
选择器与会话视图 crates/tokscale-cli/src/tui/ui/dialog/*, crates/tokscale-cli/src/tui/view_state.rs, crates/tokscale-cli/src/tui/ui/agents.rs	移除 NeedsReload 对话结果，选择器限制在已加载全集内，Sessions 和空状态按当前选择过滤。
架构与 CLI 文档 docs/adr/*.md, docs/cli.md	记录 source universe、selected clients、schema 41 canonical 缓存及不触发扫描的本地投影语义。

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant SourcePicker
  participant App
  participant ProjectionStore
  participant TuiAcc
  User->>SourcePicker: 修改来源选择
  SourcePicker->>App: 标记 dialog_source_changed
  User->>App: 关闭对话框
  App->>ProjectionStore: project(group_by, selected_clients)
  ProjectionStore->>TuiAcc: 按 selected clients 投影
  TuiAcc-->>App: 返回 UsageData

Loading

Possibly related PRs

• makoMakoGo/tokscale#135：直接关联 ProjectionBackend 和 ProjectionStore 的 selected clients 子集投影接口。
• makoMakoGo/tokscale#167：关联 App 中 Group By 对话框与内存重投影触发逻辑。
• makoMakoGo/tokscale#173：关联 TUI 缓存 bundle 和同一代投影安装流程。

Poem

小兔挥爪选来源，
聚合桶里数据流。
Canonical 摘要闪闪亮，
投影失败就回望。
关闭对话框，报表轻轻换。

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.99% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	标题准确概括了本次 PR 的核心：TUI 源过滤改为投影而非重新扫描。
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/tui-local-source-projection

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[makoMakoGo]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: c4bea52af0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codspeed-hq]

Merging this PR will degrade performance by 14.19%

❌ 1 regressed benchmark
✅ 40 untouched benchmarks
🆕 2 new benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	tui_accumulator_project[production_shaped_initial_model]	18.8 ms	22 ms	-14.19%
🆕	tui_accumulator_project_for_clients[production_shaped_multi_source_model_100k]	N/A	16.2 ms	N/A
🆕	tui_accumulator_project_for_clients[production_shaped_single_source_model_100k]	N/A	9.1 ms	N/A

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing codex/tui-local-source-projection (899243b) with personal/local-clients (3ea8cb5)}