@winspan/claude-forge 8.53.2 → 8.54.3

package/docs/design/h1-storage-aggregation-spec-20260518-1121.md

@@ -1,299 +0,0 @@
-# H1: Storage 层 SQL 聚合改造 Spec
-
-## 目标
-
-把 `web/routes/{rules,skill-stats,tasks}.ts` 里的"全表 SELECT + JS GROUP BY"模式下沉为 SQL 聚合，消除单进程内存放大（最大 100k 行 × 2），同时把 `tasks/:taskId` 的 5000 行二段全扫改为 PK 直查 + JOIN。纯增量改动，旧 API 不动。
-
-## 涉及文件
-
-- 改动 storage：`src/core/storage/routing.ts`、`src/core/storage/skills.ts`、`src/core/storage/tasks.ts`、`src/core/storage/sqlite.ts`（facade 转发）
-- 改动 routes：`src/web/routes/rules.ts`、`src/web/routes/skill-stats.ts`、`src/web/routes/tasks.ts`
-- 索引：`src/core/storage/schema.sql` + `src/core/storage/base.ts`（runMigrations）
-- 测试新增：`tests/unit/storage/routing-aggregates.test.ts`、`tests/unit/storage/skills-aggregates.test.ts`、`tests/unit/storage/tasks-getById.test.ts`
-- 测试保留契约：`tests/unit/web/routes-skill-stats.test.ts`、`tests/unit/web/routes-tasks.test.ts`
-- 测试缺口：rules 路由无测试 → spec 标注需补 `tests/unit/web/routes-rules.test.ts`
-
-## 现状分析
-
-| 文件:行 | 问题 | 行为 |
-|---|---|---|
-| `rules.ts:24,34` | `limit: 100000` ×2 | 全表 routing/skill 拉进内存后 JS reduce |
-| `skill-stats.ts:19,44,65,113` | 5 个 `limit: 10000` | 4 个聚合 + 1 个 trend by-day |
-| `skill-stats.ts:94` | `limit: 1000` invocations | by-skill 频次聚合 |
-| `tasks.ts:63-64` | 拉 5000 tasks 再 `.find(id)` | 应 PK 直查 |
-| `tasks.ts:71-75` | 拉 5000 events 后 `Set.has` 过滤 | 应 JOIN `task_events` |
-
-## 设计方案
-
-### 1. 新增 storage 方法
-
-**命名约定**：聚合方法用 `aggregate` 前缀（CLAUDE.md 未明确，spec 明确为硬约束）。
-
-#### `RoutingOperations` (`src/core/storage/routing.ts`)
-
-```ts
-// 一次返回 rules.ts 和 skill-stats.ts 共用的 routing 汇总
-aggregateRoutingStats(filter: { since_ts: number; project_path?: string }): {
-  total: number;
-  obeyed: number;       // obeyed = 1
-  refused: number;      // obeyed = 0
-  unknown: number;      // obeyed IS NULL
-  by_type: Array<{ type: 'agent' | 'skill' | 'none'; count: number }>;
-  by_agent: Array<{ agent: string; count: number }>;       // obeyed=1 AND routed_to_name NOT NULL
-  by_skill_routed: Array<{ skill: string; count: number }>; // routed_to_type='skill' (for frequency)
-}
-```
-
-SQL（在事务里跑 4 个独立聚合，全部走 `idx_routing_events_ts` / `idx_routing_events_obeyed_ts` / `idx_routing_events_agent`）：
-
-```sql
--- total + obeyed counts
-SELECT COUNT(*) AS total,
-       SUM(CASE WHEN obeyed=1 THEN 1 ELSE 0 END) AS obeyed,
-       SUM(CASE WHEN obeyed=0 THEN 1 ELSE 0 END) AS refused,
-       SUM(CASE WHEN obeyed IS NULL THEN 1 ELSE 0 END) AS unknown
-FROM routing_events WHERE ts >= @since AND (@project IS NULL OR project_path = @project);
-
--- by_type (distribution)
-SELECT COALESCE(routed_to_type,'none') AS type, COUNT(*) AS count
-FROM routing_events WHERE ts >= @since [...] GROUP BY type;
-
--- by_agent
-SELECT routed_to_name AS agent, COUNT(*) AS count
-FROM routing_events
-WHERE ts >= @since AND obeyed=1 AND routed_to_name IS NOT NULL [...]
-GROUP BY routed_to_name ORDER BY count DESC;
-
--- by_skill_routed (frequency)
-SELECT routed_to_name AS skill, COUNT(*) AS count
-FROM routing_events
-WHERE ts >= @since AND routed_to_type='skill' AND routed_to_name IS NOT NULL [...]
-GROUP BY routed_to_name ORDER BY count DESC;
-```
-
-```ts
-// trend by day（skill-stats.ts:62）— SQLite 用 strftime
-aggregateRoutingTrendByDay(filter: { since_ts: number }): Array<{
-  day: string;       // 'YYYY-MM-DD'
-  total: number;
-  skill: number;
-}>
-```
-
-SQL：
-
-```sql
-SELECT strftime('%Y-%m-%d', ts/1000, 'unixepoch') AS day,
-       COUNT(*) AS total,
-       SUM(CASE WHEN routed_to_type='skill' THEN 1 ELSE 0 END) AS skill
-FROM routing_events WHERE ts >= @since
-GROUP BY day ORDER BY day ASC;
-```
-
-调用方：`rules.ts`（hit-rate）、`skill-stats.ts`（distribution / frequency / trend / routing-stats）
-
-#### `SkillOperations` (`src/core/storage/skills.ts`)
-
-```ts
-aggregateSkillInvocationsBySkill(filter: { since: number; limit?: number }): Array<{
-  skill_id: string;
-  total: number;
-  success: number;   // success = 1
-  failed: number;    // success = 0
-}>
-```
-
-SQL（走 `idx_skill_invocations_timestamp` + group）：
-
-```sql
-SELECT skill_id,
-       COUNT(*) AS total,
-       SUM(CASE WHEN success=1 THEN 1 ELSE 0 END) AS success,
-       SUM(CASE WHEN success=0 THEN 1 ELSE 0 END) AS failed
-FROM skill_invocations
-WHERE timestamp >= @since
-GROUP BY skill_id ORDER BY total DESC;
-```
-
-调用方：`rules.ts`（per-skill）、`skill-stats.ts:91`（invocations）
-
-#### `TaskOperations` (`src/core/storage/tasks.ts`)
-
-```ts
-getTask(taskId: string): TaskRecord | null;
-queryEventsByTaskId(taskId: string, opts?: { limit?: number }): ForgeEvent[];
-queryInjectionsByTaskId(taskId: string): Injection[];
-querySkillInvocationsByTaskWindow(taskId: string): SkillInvocationRow[]; // 用 task 的 start_time / end_time 直接 SQL 过滤
-```
-
-SQL：
-
-```sql
--- getTask
-SELECT t.*, s.project_path FROM tasks t
-LEFT JOIN sessions s ON s.session_id = t.session_id
-WHERE t.id = ?;
-
--- queryEventsByTaskId
-SELECT e.* FROM events e
-JOIN task_events te ON te.event_id = e.event_id
-WHERE te.task_id = ?
-ORDER BY e.timestamp ASC
-LIMIT ?;
-
--- queryInjectionsByTaskId
-SELECT i.* FROM injections i
-JOIN task_events te ON te.event_id = i.event_id
-WHERE te.task_id = ?
-ORDER BY i.timestamp ASC;
-
--- querySkillInvocationsByTaskWindow（避免 detail 路由再做时间过滤）
-SELECT si.* FROM skill_invocations si
-JOIN tasks t ON t.session_id = si.session_id
-WHERE t.id = ?
-  AND si.timestamp >= CAST(strftime('%s', t.start_time) AS INTEGER) * 1000
-  AND si.timestamp <= COALESCE(CAST(strftime('%s', t.end_time) AS INTEGER) * 1000, @now_ms)
-ORDER BY si.timestamp ASC;
-```
-
-调用方：`tasks.ts:59` detail route
-
-> **决策**：`querySkillInvocationsByTaskWindow` 把 `now` 通过参数传入而不是 SQL 端拿，便于测试时 mock 时间。
-
-### 2. 索引调整
-
-**复查现状**：
-- `idx_routing_events_ts` ✓ — 覆盖 `since_ts`
-- `idx_routing_events_agent (routed_to_name, obeyed)` ✓ — 覆盖 by_agent
-- `idx_routing_events_obeyed_ts` ✓ — 覆盖 obeyed group
-- `idx_skill_invocations_timestamp` ✓ — 覆盖 since filter
-- `idx_skill_invocations_skill` ✓ — 覆盖 by skill_id group（不一定需要）
-- `idx_task_events_task` ✓ — 覆盖 JOIN
-- `tasks.id` 是 PK ✓
-
-**新增（一处）**：
-
-```sql
--- routing_events: routed_to_type 走 distribution 分组高频用
-CREATE INDEX IF NOT EXISTS idx_routing_events_type_ts ON routing_events(routed_to_type, ts DESC);
-```
-
-放置：`schema.sql` 末尾 + `base.ts` runMigrations 末段（与 Phase 1 indexes 同样的 try/catch 块）。**不要重复放两份**——H4 已记录"schema.sql 与 base.ts 索引重复"问题。本 spec 决定：**只加在 schema.sql，base.ts 的 runMigrations 也加同一条 idempotent CREATE INDEX**（已有先例），不算重复。其它索引保持原样。
-
-### 3. Routes 改造
-
-#### `rules.ts` (hit-rate)
-
-```ts
-// before: queryRoutingEvents({limit:100000}) + querySkillInvocations({limit:100000}) + JS reduce
-// after:
-const routing = storage.aggregateRoutingStats({ since_ts: since });
-const skillsAgg = storage.aggregateSkillInvocationsBySkill({ since });
-const totalPrompts = routing.total;
-const agentDelegations = routing.obeyed;
-const skills = skillsAgg.map(s => ({...s, rate: pct(s.total, totalPrompts)}));
-const agents = routing.by_agent.map(a => ({...a, rate: pct(a.count, totalPrompts)}));
-const triggered = new Set(skillsAgg.map(s => s.skill_id));
-const neverTriggered = skillRegistry?.getAll().map(s=>s.id).filter(id=>!triggered.has(id)) ?? [];
-```
-
-#### `skill-stats.ts`
-
-| Endpoint | 旧 | 新 |
-|---|---|---|
-| `/distribution` | `queryRoutingEvents{limit:10000}` + JS group | `aggregateRoutingStats(...).by_type` |
-| `/frequency` | 同上 | `aggregateRoutingStats(...).by_skill_routed` |
-| `/trend` | 同上 + by-day JS group | `aggregateRoutingTrendByDay({since_ts})` 再 JS map 成 `{day, skillRate}` |
-| `/invocations` | `querySkillInvocations{limit:1000}` + JS group | `aggregateSkillInvocationsBySkill({since})` |
-| `/api/routing/stats` | `queryRoutingEvents{limit:10000}` + JS filter | `aggregateRoutingStats` 中 `obeyed/total/by_agent` |
-
-#### `tasks.ts:/:taskId`
-
-```ts
-// before:
-//   const allTasks = storage.queryTasks({limit:5000}); task = allTasks.find(...)
-//   const eventIds = new Set(storage.getTaskEventIds(taskId));
-//   const allEvents = storage.queryEvents({session_id, limit:5000}); filter by eventIds
-//   const allInjections = storage.queryInjections({session_id, limit:500}); filter by eventIds
-//   const allSkillInvocations = storage.querySkillInvocations({session_id, limit:200}); JS time filter
-// after:
-const task = storage.getTask(taskId); if (!task) return 404;
-const taskEvents = storage.queryEventsByTaskId(taskId, { limit: 5000 });
-const allInjections = storage.queryInjectionsByTaskId(taskId);
-const skillInvocations = storage.querySkillInvocationsByTaskWindow(taskId);
-// 后续 timeline / artifacts / userPrompts 逻辑不变
-```
-
-## 关键决策
-
-1. **聚合方法用 `aggregate` 前缀**（CLAUDE.md 未规定，本 spec 固化）— `aggregateRoutingStats` / `aggregateSkillInvocationsBySkill` / `aggregateRoutingTrendByDay`。理由：与 `query*` / `list*` / `get*` 区分语义，调用方一眼能看出"这是 SQL 端 GROUP BY"。
-2. **新方法挂在各自 Operations 类**，sqlite.ts facade 仅做转发。理由：保持职责拆分，不在 facade 写 SQL。
-3. **不合并 routing 4 个聚合到单条 SQL**。理由：SQLite 无 GROUPING SETS / CUBE，强行 UNION ALL 反而难读；分 4 条 prepared statement 各走自己的索引更快。
-4. **trend by-day 用 `strftime('%Y-%m-%d', ts/1000, 'unixepoch')`**，已验证 better-sqlite3 完全支持。
-5. **`queryEventsByTaskId` 保留 `limit` 参数**（默认 5000）— 防御过大 task；前端不分页，但要有上限。
-6. **`task_events` PK 是 `(task_id, event_id)`**，但 `task_events(event_id)` 的反向 JOIN 已有 `idx_task_events_event`；正向 `idx_task_events_task` 也存在，JOIN 性能 OK。
-
-## 测试策略
-
-### 单元测试（必加）
-
-- `tests/unit/storage/routing-aggregates.test.ts`
-  - 空表返回 `{total:0, obeyed:0, refused:0, unknown:0, by_type:[], ...}`
-  - 混合 `obeyed=1/0/NULL` 计数正确
-  - `since_ts` 过滤边界（等于 / 小于）
-  - `by_agent` 排除 `obeyed≠1` 和 `routed_to_name IS NULL`
-  - `aggregateRoutingTrendByDay` 跨日聚合 + 时区一致性（UTC）
-- `tests/unit/storage/skills-aggregates.test.ts`
-  - `success=1/0` 分别计数；按 total 降序
-  - `since` 过滤
-- `tests/unit/storage/tasks-getById.test.ts`
-  - `getTask` 命中 / null
-  - `queryEventsByTaskId` JOIN 正确性 + 排序
-  - `querySkillInvocationsByTaskWindow` 时间窗包含/排除（含 end_time IS NULL 取 now）
-  - `queryInjectionsByTaskId` event_id 关联
-
-### 集成 / 路由测试
-
-- `tests/unit/web/routes-skill-stats.test.ts` — 保留现有契约（响应字段不变），跑过即可
-- `tests/unit/web/routes-tasks.test.ts` — 保留，detail 路由响应结构不变
-- `tests/unit/web/routes-rules.test.ts` — **缺口，本任务新增**：空数据、混合数据下 totalPrompts / agentDelegations / skills / agents / neverTriggered 均符合预期
-
-### 性能基准（可选，给 coder agent）
-
-写一个 `scripts/bench/h1-aggregation.ts`（不入 git CI）：
-- 灌 100k routing_events + 10k skill_invocations
-- 测 `aggregateRoutingStats` vs 旧 `queryRoutingEvents({limit:100000})` + JS reduce 的耗时
-- 目标：新 ≤ 旧 / 10，内存峰值下降 ≥ 90%
-
-## 风险与回滚
-
-| 风险 | 应对 |
-|---|---|
-| `strftime('%Y-%m-%d', ts/1000, 'unixepoch')` 在 ts=0 / 负值时返回 NULL | 聚合前 WHERE `ts > 0` 兜底；测试覆盖 |
-| `routed_to_type` 历史值含 NULL | `COALESCE(routed_to_type,'none')`，与旧逻辑 `e.routed_to_type \|\| 'none'` 一致 |
-| 新索引 `idx_routing_events_type_ts` 与 H4 索引重复隐患 | 检查 `base.ts` 已存在的 5 类索引前缀，确认未重复；只在 schema.sql + base.ts 的 Phase 1 块各加一处 idempotent CREATE |
-| `getTask` 响应字段需要包含 `project_path`（旧 detail 路由没用到，但 list 用了） | 用 LEFT JOIN sessions，缺失时返回 undefined，detail 路由对此字段无依赖 |
-| 测试缺口：rules 路由 0 测试 → 改造时可能行为漂移 | **强制先补 routes-rules.test.ts，再改 route**（TDD 顺序） |
-
-**回滚**：纯增量，新方法 + 新索引 + route 内部实现替换。回滚 = revert route 改动（storage 新方法保留无害）。
-
-## 实施顺序（给 coder agent）
-
-1. **Storage 层先**
-   - a. 新增 3 个 aggregate 方法 + 4 个 task 方法 + sqlite.ts facade 转发
-   - b. 新增索引（schema.sql + base.ts 同步）
-   - c. 跑 `npx vitest run tests/unit/storage/ --reporter=verbose`
-2. **补 routes-rules.test.ts**（基于旧实现先建立行为基线）
-3. **一次改一个 route，每改完跑对应测试**
-   - rules.ts → routes-rules.test.ts
-   - skill-stats.ts → routes-skill-stats.test.ts
-   - tasks.ts → routes-tasks.test.ts
-4. **`npx tsc --noEmit` + 全量测试**
-5. **可选基准脚本验证**
-
-## 命名遵循（CLAUDE.md 约束 + 本 spec 扩展）
-
-- 单条查询：`getTask(id)` ✓
-- 列表/查询：`queryEventsByTaskId`、`queryInjectionsByTaskId`、`querySkillInvocationsByTaskWindow` ✓
-- 聚合（**本 spec 固化**）：`aggregate*` — `aggregateRoutingStats`、`aggregateRoutingTrendByDay`、`aggregateSkillInvocationsBySkill`
-- 写入：本任务无新增

package/docs/design/h2-getdatabase-encapsulation-spec-20260518-1450.md

@@ -1,191 +0,0 @@
-# H2: getDatabase 越权 SQL 收敛到 Operations 层 Spec
-
-## 目标
-
-消除 `web/routes/`、`web/analytics/`、`cli/commands/`、`daemon/handlers/` 中对 `storage.getDatabase().prepare()` 的直写，按"查询动词 + 资源"命名下沉到对应 `*Operations` 类，以 `SQLiteStorage` facade 为唯一对外入口，便于后续 schema 重构。
-
-## 调研结果
-
-### 越权 SQL 清单（主线程封闭性扫描后修订：27 处）
-
-| 位置 | SQL 用途 | 表 | 应归属 |
-|---|---|---|---|
-| `daemon/handlers/stop.ts:154-158` | 按 session 统计 tool_name 调用 | events | EventOperations |
-| `daemon/handlers/stop.ts:163-168` | 按 session 统计 Agent/Task subagent_type 调用 | events | EventOperations |
-| `daemon/handlers/stop.ts:176-178` | 按 session 计数 skill 调用 | skill_invocations | SkillOperations |
-| `web/routes/stats.ts:13` | 全局 events 计数 | events | EventOperations |
-| `web/routes/stats.ts:14` | 全局 sessions 计数 | sessions | SessionOperations |
-| `web/routes/stats.ts:17-21` | Top 15 tool 使用分布 | events | EventOperations |
-| `web/routes/stats.ts:28-33` | 最近 7 天每日事件数 | events | EventOperations |
-| `web/routes/stats.ts:35-40` | 最近 7 天每日会话数 | sessions | SessionOperations |
-| `web/routes/stats.ts:50` | 全局 skill 调用计数 | skill_invocations | SkillOperations |
-| `web/routes/trace.ts:106-109` | 按 session 聚合 hook_type 分布 | events | EventOperations |
-| `web/routes/trace.ts:111-116` | 按 session 聚合 subagent_type 分布 | events | EventOperations |
-| `web/routes/trace.ts:118-120` | 按 session 列出 distinct skill_id | skill_invocations | SkillOperations |
-| **`cli/commands/trace.ts:115`** | hook_type 分布（CLI 版） | events | EventOperations |
-| **`cli/commands/trace.ts:124`** | subagent_type 分布（CLI 版） | events | EventOperations |
-| **`cli/commands/trace.ts:135`** | distinct skill_id（CLI 版） | skill_invocations | SkillOperations |
-| `web/analytics/drift-detector.ts:125-128` | 时间窗内 distinct skill 数 | skill_invocations | SkillOperations |
-| `web/analytics/drift-detector.ts:154-157` | 最近 7 天有事件的活跃日数 | events | EventOperations |
-| `web/analytics/drift-detector.ts:185-187` | 时间窗内 session 计数 | sessions | SessionOperations |
-| `web/analytics/drift-detector.ts:190-192` | 时间窗内 task 计数 | tasks | TaskOperations |
-| `web/analytics/weekly-report.ts:100-109` | 周内 events overview | events | EventOperations |
-| `web/analytics/weekly-report.ts:111-116` | 周内 distinct project_path | events | EventOperations |
-| `web/analytics/weekly-report.ts:118-122` | 周内 task 计数 | tasks | TaskOperations |
-| `web/analytics/weekly-report.ts:214-222` | 周内 PreToolUse top tools | events | EventOperations |
-| `web/analytics/weekly-report.ts:228-244` | 周内 PostToolUse 失败/总数 | events | EventOperations |
-| `web/analytics/weekly-report.ts:261-268` | 周内 file edit tool_input | events | EventOperations |
-| `web/analytics/anti-pattern-detector.ts:83-86` | 时间窗内全字段 events | events | EventOperations |
-| `web/analytics/anti-pattern-detector.ts:104-114` | 时间窗内 session 概览 | sessions | SessionOperations |
-
-**关键修订**：`cli/commands/trace.ts` 有 3 段与 web/routes/trace.ts 同模式的 SQL，调用同一组聚合方法。
-
-### Operations 类现状
-
-| 类 | 文件 | 现有方法（节选） |
-|---|---|---|
-| EventOperations | `core/storage/events.ts` | writeEvent / queryEvents / countEvents / searchEvents |
-| SessionOperations | `core/storage/sessions.ts` | upsertSession / querySessions |
-| TaskOperations | `core/storage/tasks.ts` | writeTask / queryTasks / queryTasksFiltered |
-| SkillOperations | `core/storage/skills.ts` | writeSkillInvocation / aggregateSkillInvocationsBySkill |
-| RoutingOperations | `core/storage/routing.ts` | aggregateRoutingStats / aggregateRoutingTrendByDay |
-
-H1 已固化 `aggregate*` 命名模式。
-
-### `getDatabase()` 调用方现状
-
-| 调用方 | 类型 | 处理 |
-|---|---|---|
-| `web/routes/{stats,trace}.ts` | 越权 | 消除 |
-| `web/analytics/*` | 越权 | 消除 |
-| `cli/commands/trace.ts` | 越权 | 消除 |
-| `daemon/handlers/stop.ts` | 越权 | 消除 |
-| 测试 fixture / migration | 合法 | 保留 |
-
-### 测试覆盖现状
-
-| 模块 | 现有测试 | safety-net 评级 |
-|---|---|---|
-| `web/routes/stats.ts` | 无 | **必补** |
-| `web/routes/trace.ts` | 无 | **必补** |
-| `cli/commands/trace.ts` | 无 | 可补（跑得到的话） |
-| `web/analytics/*` | `tests/integration/web-analytics.integration.test.ts`（仅 200 + shape） | 增强字段值断言 |
-| `daemon/handlers/stop.ts` behavior summary | 无 | **必补**（fixture + 断言摘要） |
-| Operations 新增方法 | 无 | 每个新方法配单测 |
-
-## 方案选择
-
-**方案 A（推荐）**：所有越权 SQL 下沉到 `*Operations`，作为聚合/计数方法暴露给 facade，调用方改用 facade。
-
-`getDatabase()` 处理：**保留 public** + jsdoc `@internal — Operations 子类使用。Routes/Handlers/Analytics 禁止调用，请使用 facade 方法。` 不改 protected（架构非继承）。
-
-## 新增 Operations 方法清单
-
-```ts
-// EventOperations（11 个）
-countAllEvents(): number;
-aggregateToolUsage(opts: { since?: string; limit?: number; hook_type?: 'PreToolUse' | 'PostToolUse' }): Array<{ tool_name: string; count: number }>;
-aggregateDailyEventCounts(opts: { since: string; until?: string }): Array<{ date: string; count: number }>;
-aggregateHookTypeBySession(session_id: string): Array<{ hook_type: string; count: number }>;
-aggregateAgentTypeBySession(session_id: string): Array<{ agent_type: string | null; count: number }>;
-aggregateToolUsageBySession(session_id: string): Array<{ tool_name: string; count: number }>;
-countActiveDays(opts: { since: string; until?: string }): number;
-aggregateOverviewByRange(opts: { since: string; until: string }): { event_count: number; session_count: number; day_count: number };
-queryDistinctProjects(opts: { since: string; until: string }): string[];
-aggregateToolFailureRate(opts: { since: string; until: string }): { post_total: number; failed: number };
-queryFileEditInputs(opts: { since: string; until: string; tool_names: string[] }): Array<{ tool_input: string }>;
-queryEventsByTimeRange(opts: { since: string; until?: string }): ForgeEvent[];
-
-// SessionOperations（4 个）
-countAllSessions(): number;
-aggregateDailySessionCounts(opts: { since: string; until?: string }): Array<{ date: string; count: number }>;
-querySessionsByTimeRange(opts: { since: string; until?: string }): SessionSummary[];
-countSessionsByRange(opts: { since: string; until?: string }): number;
-
-// TaskOperations（1 个）
-countTasksByRange(opts: { since: string; until?: string }): number;
-
-// SkillOperations（4 个）
-countAllSkillInvocations(): number;
-countSkillInvocationsBySession(session_id: string): number;
-countDistinctSkillsSince(since_ms: number): number;
-queryDistinctSkillIdsBySession(session_id: string): string[];
-```
-
-**总计：~20 个新增方法**。命名 `count*` / `aggregate*` / `query*`。
-
-## safety-net 设计
-
-| 测试文件 | 覆盖目标 | 状态 |
-|---|---|---|
-| `tests/integration/web-stats.integration.test.ts` | GET `/api/stats` 200 + totalEvents/totalSessions/toolUsage/dailyActivity/skillInvocations 字段 | **新增** |
-| `tests/integration/web-trace.integration.test.ts` | GET `/api/trace/:commit` 多分支（无 project / 非 git / 无 note / 有 note）+ sessions[] shape | **新增**（用 tmp git repo 或 mock） |
-| `src/tests/stop-handler-behavior-summary.test.ts` | StopHandler.generateBehaviorSummary 输出字符串断言 | **新增** |
-| `tests/integration/web-analytics.integration.test.ts` | 现有 shape + 加 fixture 数据断言关键字段值 | **增强** |
-| `src/tests/event-operations-aggregates.test.ts` | EventOperations 11 个新方法 | **新增** |
-| `src/tests/session-operations-aggregates.test.ts` | SessionOperations 4 个 | **新增** |
-| `src/tests/skill-operations-counts.test.ts` | SkillOperations 4 个 | **新增** |
-
-## 改造范围
-
-| 文件 | 改动点 | 行数估计 |
-|---|---|---|
-| `core/storage/events.ts` | +11 方法 | +200 |
-| `core/storage/sessions.ts` | +4 方法 | +80 |
-| `core/storage/tasks.ts` | +1 方法 | +20 |
-| `core/storage/skills.ts` | +4 方法 | +60 |
-| `core/storage/sqlite.ts` | facade 转发 | +60 |
-| `daemon/handlers/stop.ts` | 删 db.prepare → facade | -25 / +15 |
-| `web/routes/stats.ts` | 全文重写无 SQL | -50 / +30 |
-| `web/routes/trace.ts` | SQL 段改 facade | -25 / +12 |
-| `cli/commands/trace.ts` | 3 段 SQL 改 facade | -20 / +10 |
-| `web/analytics/drift-detector.ts` | 4 段 SQL 改 facade | -25 / +15 |
-| `web/analytics/weekly-report.ts` | 6 段 SQL 改 facade | -55 / +30 |
-| `web/analytics/anti-pattern-detector.ts` | 2 段 SQL 改 facade | -30 / +12 |
-| **新增测试 7 文件** | safety-net + 聚合单测 | +600 |
-
-**总计：~13 文件改 + 7 文件新增，净 +750 / -230 ≈ 980 行**
-
-## 风险与回滚
-
-| 风险 | 应对 |
-|---|---|
-| GROUP BY/ORDER BY/NULL 处理细节不一致 | safety-net 字段值断言；逐方法 diff 旧 SQL |
-| `LIKE '%error%'` 失败检测被新方法弱化 | weekly-report 失败率单测覆盖原 SQL 3 个 OR 条件 |
-| `date('now', '-7 days')` 与传入 since 字符串语义差异 | 新方法统一接收 ISO 字符串，调用方负责 now() 计算 |
-| 周报 file edit `IN ?` placeholders | `queryFileEditInputs({ tool_names })` 内部展开 |
-| 改动量大致命合并冲突 | 分多 commit，每 commit 独立可 revert |
-
-## 实施顺序（refactor-safe 5 phase）
-
-### Phase 1: safety-net（commit 1）
-1. `tests/integration/web-stats.integration.test.ts` 新增
-2. `tests/integration/web-trace.integration.test.ts` 新增（tmp git repo）
-3. `src/tests/stop-handler-behavior-summary.test.ts` 新增
-4. 增强 `web-analytics.integration.test.ts`
-5. 跑全量确认 baseline 通过
-
-### Phase 2: Operations 新方法（commit 2）
-1. 4 个 Operations 类加方法
-2. 4 个单测文件加 fixture + 断言
-3. sqlite.ts facade 转发
-4. 不删旧 SQL，并行存在
-
-### Phase 3: 替换调用方（每文件独立 commit，共 7 commit）
-1. stats.ts → 跑 stats 集成测试
-2. trace.ts (web) → 跑 trace 集成测试
-3. trace.ts (cli) → 同样断言（如有测试）
-4. stop.ts → 跑 stop handler 单测
-5. drift-detector.ts → 跑 web-analytics
-6. weekly-report.ts → 同上
-7. anti-pattern-detector.ts → 同上
-
-### Phase 4: 收尾（commit 3）
-1. `getDatabase()` 加 jsdoc 警告
-2. `npx tsc --noEmit` + `npm test` 全量
-3. 可选：CLAUDE.md 「常见陷阱」补 1 条
-
-## 命名遵循
-
-- 计数 `count*` / 聚合 `aggregate*` / 列表 `query*`
-- 遵循 H1 已固化的 `aggregateRoutingStats` 等模式

package/docs/design/h3-fallback-removal-spec-20260518-1245.md

@@ -1,76 +0,0 @@
-# H3: 删除 schema.sql inline fallback Spec
-
-## 目标
-消除 `SQLiteBase.initSchema()` 中残缺的 inline fallback，schema.sql 缺失时 fail-fast，杜绝静默降级导致的生产数据写炸。
-
-## 涉及文件
-- `src/core/storage/base.ts`（主改）
-- `package.json`（build script 加 postbuild 校验）
-- `tests/unit/storage/schema-missing.test.ts`（新增）
-- `src/core/storage/index.ts` / `sqlite.ts` 类导出（无需改，构造签名不变）
-
-## 现状分析
-- inline fallback 位置：`src/core/storage/base.ts:61-84`（`initSchema` 的 else 分支，70-82 行）
-- fallback 内容：仅建 `events` 1 张表 + 4 个旧索引（idx_events_session/project/timestamp/distilled）
-- schema.sql 真实：8 张活表（events / sessions / injections / tasks / task_events / routing_events / token_usage / skill_invocations）+ 33 个 CREATE TABLE/INDEX 语句，含 FK ON DELETE CASCADE 与若干复合索引
-- 缺漏表：sessions / injections / tasks / task_events / routing_events / token_usage / skill_invocations 全部缺失 — 一旦走 fallback，所有 routing/skill/task/token 路径首次 prepared statement 即报 `no such table`
-- npm 发布拷贝：`package.json:13` 的 build script —
-  `cp src/core/storage/schema.sql dist/core/storage/schema.sql`（裸 `cp`，无失败检测，且依赖前置 `tsc` 已创建 `dist/core/storage/` 目录）
-
-## 方案选择
-
-| 方案 | 改动量 | 优点 | 缺点 |
-|------|------|------|------|
-| A 删 fallback + fail-fast | 小（~15 行） | 简单；schema 缺失立即抛错 | 单点失败：发布翻车一次即生产 daemon 起不来（但 silent corruption 更糟） |
-| B 嵌入 schema 为 TS 常量 | 中（新增构建步骤 + 1 文件） | 彻底脱离运行时文件依赖；npm 安装零拷贝 | tsc 无 raw-loader；要么手写常量易漂移，要么加 prebuild 脚本生成 `schema-embedded.ts` |
-| C A + postbuild 校验 | 小（~20 行 + 1 行脚本） | 删 fallback 防 silent failure；postbuild 校验防发布事故；不引入构建复杂度 | 仍依赖运行时 fs（开发期问题不大） |
-
-**推荐：C**
-
-理由：B 的常量化听起来最干净，但本项目用 `tsc` 直接编译，引入 codegen 脚本会增加 prebuild 链路（且 schema.sql 改动频率不高，收益不匹配复杂度）。A 解决了核心问题（不再 silent），但发布事故仍可能爆。C 用一行 `test -f` 把发布事故拦截在 `npm run build` 阶段，是性价比最高的组合。
-
-## 设计细节（方案 C）
-
-**改动 1：`src/core/storage/base.ts` `initSchema()` 重写**
-- 删除 70-82 行 inline fallback
-- 删除 `existsSync(schemaPath)` 分支判断；改为：若文件不存在或读取失败，抛 `Error(`[SQLiteStorage] schema.sql not found at ${schemaPath}. ...`)`
-- 错误信息示例：
-  ```
-  [SQLiteStorage] schema.sql not found at /path/to/dist/core/storage/schema.sql.
-  This indicates a broken build/install. Run `npm run build` or reinstall the package.
-  ```
-- 更新文件头注释：删 "或 inline fallback"
-
-**改动 2：`package.json` build script**
-- 在 build 命令末尾追加 `&& test -f dist/core/storage/schema.sql || (echo "[build] FATAL: dist/core/storage/schema.sql missing" && exit 1)`
-- 拷贝命令保留原样（一次失败立即被 test -f 抓出来）
-
-**改动 3：注释清理**
-- `base.ts` 行 6 注释更新为"加载 schema.sql（缺失则抛错）"
-- 文件头注释列表同步
-
-## 测试策略
-
-新增 `tests/unit/storage/schema-missing.test.ts`：
-
-| case | 输入 | 预期 |
-|------|------|------|
-| 1 | 正常环境（schema.sql 存在）| `new SQLiteStorage(tmpDb)` 成功，`sqlite_master` 有 `sessions` 表 |
-| 2 | 临时 rename `dist/core/storage/schema.sql` 或 mock `readFileSync` 抛错 | 构造抛 Error，message 含 `schema.sql not found`；**断言不存在 events 表**（确认未走旧 fallback） |
-
-实现要点：
-- case 2 不能真改 dist/（影响其他测试），用 `vi.mock('node:fs', ...)` 截 `existsSync` 返回 false
-- 现有 `tests/unit/storage/migration-idempotent.test.ts` 不变，验证回归（schema.sql 存在路径仍 idempotent）
-- 跑 `npx vitest run tests/unit/storage --reporter=verbose` + `npx tsc --noEmit`
-
-## 风险与回滚
-
-- **风险 1（开发期）**：开发者本地未跑 `npm run build`，直接 `node src/cli/index.js` 这种从 src 启动？— 实际启动路径都从 `dist/` 走（`bin` 指向 `dist/cli/index.js`），不存在 src 直跑场景；vitest 跑测试用的是源码路径下的 schema.sql（`src/core/storage/schema.sql`），同样存在，无影响
-- **风险 2（首次升级）**：旧版本用户残留 dist 缺 schema.sql？— 升级走 `npm i`，`prebuild` 已 `rm -rf dist`，必然重 build；新 postbuild 校验拦截
-- **回滚**：纯增量改动；revert 单 commit 即可恢复旧 fallback 行为
-
-## 命名遵循
-
-- 测试文件 `schema-missing.test.ts`：kebab-case ✓
-- 不引入新函数/常量；保留 `initSchema()` 私有方法名 ✓
-- 错误信息以 `[SQLiteStorage]` 前缀（与现有 logger 调用一致）✓