Trim unused SessionQuery convenience methods
精简未使用的 SessionQuery 便利方法
[`SessionQueryEngine`](../../../../packages/session-query/session-query/src/index.ts) maintains `readSession`, `readTitle`, `readTitleSnapshot`, and `listEvents` without executing first-party product callers. Exact-name and call-site searches find internal delegation, tests, and generated discovery metadata. Current consumers use retained observations, batch titles, surface reads, and traces. The generated catalog ex
English
Problem
SessionQueryEngine maintains readSession, readTitle, readTitleSnapshot, and listEvents without executing first-party product callers. Exact-name and call-site searches find internal delegation, tests, and generated discovery metadata. Current consumers use retained observations, batch titles, surface reads, and traces. The generated catalog exposes these methods to plugin authors but does not execute the advertised operations.
These entry points add replay-validation and result-copying paths, wrappers, public types, and endpoint-specific tests. Their removal can reduce maintained API obligations without replacing the shared query implementation.
Proposal
Remove the four methods, the unreferenced SessionLogSnapshot result type, and eventRecords. Remove their imports and current documentation, including the SessionLogSnapshot type-equivalence block and explanatory paragraph in both subsystem pages. Remove its hand-maintained entry in the type-equivalence manifest and its LINK_MAP entry in the catalog generator, then regenerate discovery metadata. The selected definitions occupy approximately eighty source lines before import and metadata cleanup; no replacement service is needed.
Retain filterEvents and _filterEvents, together with their semantic extraction and filtering helpers. Retain observeSession, readTitleSnapshots, readSurface, readEvent, listing, search, and tracing. Preserve shared corpus resolution and its existing ownership and failure behavior.
The historical unified-query decision explains the retained single-service topology. This proposal removes selected convenience operations, not that topology. No active note is fully superseded; keep archived records frozen and link this narrower decision from affected current documentation.
Alternatives considered
Retain all documented methods for external callers. This avoids migration for installed plugins, but keeps four APIs without a current product caller. The pre-stable API policy permits a deliberate removal with explicit migration costs.
Remove filterEvents too. Rejected because its provider-independent literal substring scan differs from FTS token matching. The SQLite query documentation explicitly recommends this operation; removing it would withdraw a distinct query capability.
Acceptance criteria
- Remove the four methods and orphan definitions from source, package READMEs, subsystem declarations, and generated catalogs; retain literal substring queries.
- Preserve live-source precedence, corruption refusal, cancellation, detached results, cold reads, and batch-title behavior through retained endpoints. Move relevant assertions from removed-method tests instead of deleting their shared guarantees; account for
readSession's additional replay validation. - Run focused query, SQLite-query, tool-query, and affected context-reference tests, relevant keyless query recordings, catalog generation, typecheck, lint, and doc-sync. Released Session generations remain unchanged.
Risks
Repository searches cannot enumerate installed or dynamically authored plugins. Such callers lose complete-log and lightweight-record convenience operations and must adopt retained APIs with their actual ownership and error semantics. A demonstrated consumer requiring a removed operation would justify reconsidering that operation separately.
中文
问题
SessionQueryEngine 维护了 readSession、readTitle、readTitleSnapshot 和 listEvents，但没有执行这些方法的第一方产品调用方。精确名称和调用点搜索只找到内部委托、测试和生成的发现元数据。当前消费方使用可保留的观测、批量标题、模型可见事件读取和追踪。生成的目录向插件作者展示这些方法，但不执行其中列出的操作。
这些入口增加了回放验证和结果复制路径、包装层、公开类型及入口专属测试。删除它们可以减少需要维护的 API 义务，无须替换共享查询实现。
提案
删除这四个方法、不再被引用的 SessionLogSnapshot 结果类型和 eventRecords。删除相关导入及当前文档，包括两个子系统页面中的 SessionLogSnapshot 类型等价代码块和说明段落。删除类型等价 manifest 中手工维护的条目，以及目录生成器 中的 LINK_MAP 条目，然后重新生成发现元数据。选定定义在清理导入和元数据之前约占八十行源代码；无须新增替代服务。
保留 filterEvents 和 _filterEvents，以及语义提取和过滤辅助函数。保留 observeSession、readTitleSnapshots、readSurface、readEvent、列举、搜索和追踪。保留共享会话集合解析及其现有所有权和失败行为。
历史上的统一查询决策 解释了保留的单服务结构。本提案删除选定的便利操作，不改变该结构。没有活动记录被完全取代；保持归档记录冻结，并从受影响的当前文档链接到这一较窄的决策。
考虑过的替代方案
为外部调用方保留所有已记录的方法。 这样可以避免已安装插件迁移，但会保留四个没有当前产品调用方的 API。尚未稳定的 API 策略允许在明确迁移代价后有意删除它们。
同时删除 filterEvents。 不采用，因为其提供方无关的字面子串扫描不同于 FTS 的 token 匹配。SQLite 查询文档 明确推荐该操作；删除它会撤销一项独立的查询能力。
验收标准
- 从源代码、包 README、子系统声明和生成目录中删除这四个方法及失去引用的定义；保留字面子串查询。
- 通过保留的入口维持实时来源优先、损坏拒绝、取消、结果独立复制、冷读取和批量标题行为。将被删方法测试中的相关断言迁移出去，不删除其共享保证；明确处理
readSession额外执行的回放验证。 - 运行针对查询、SQLite 查询、查询工具及受影响的会话引用的测试，相关无密钥查询录制回放、目录生成、类型检查、lint 和 doc-sync（文档同步门禁）。已发布的 Session 代际文件保持不变。
风险
仓库搜索无法枚举已安装或动态编写的插件。这些调用方将失去完整日志和轻量事件记录的便利操作，必须按照保留 API 实际的所有权和错误语义迁移。若出现确实需要某个被删操作的消费方，可以单独重新考虑该操作。