@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/storage/sessions-aggregate.test.ts

@@ -0,0 +1,435 @@
+/**
+ * sessions 聚合表测试
+ *
+ * 背景：querySessions 旧实现对 events 表做 GROUP BY + 子查询提取 first_prompt，
+ * 复杂度 O(sessions × events)。现在在 writeEvent 里 upsert 到 sessions 聚合表，
+ * querySessions 直接读聚合表 → O(sessions)。
+ *
+ * 覆盖：
+ *   1. writeEvent 首次命中 session_id 时插入聚合行
+ *   2. 同一 session 多次事件 → event_count 递增、end_time 更新
+ *   3. 首条 UserPromptSubmit 写入 first_prompt；后续事件不覆盖
+ *   4. querySessions 从聚合表读取，不触及 events 相关子查询
+ *   5. 旧库启动时的 backfill 迁移：空 sessions + 有 events → 自动对齐
+ *   6. upsertSession 失败不应阻塞原 events 写入（硬性约束）
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { ForgeEvent } from '../../../src/core/types.js';
+
+describe('SQLiteStorage: sessions aggregate table', () => {
+  let tmp: string;
+  let dbPath: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-sess-agg-'));
+    dbPath = join(tmp, 'data.db');
+    storage = new SQLiteStorage(dbPath);
+  });
+
+  afterEach(() => {
+    try {
+      storage.getDatabase().close();
+    } catch {
+      // already closed
+    }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function makeEvent(overrides: Partial<ForgeEvent>): ForgeEvent {
+    return {
+      session_id: 's1',
+      project_path: '/tmp/proj',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      ...overrides,
+    };
+  }
+
+  it('首次写入事件应在 sessions 表创建一行', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 's-new',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '你好',
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT * FROM sessions WHERE session_id = ?')
+      .get('s-new') as Record<string, unknown>;
+
+    expect(row).toBeDefined();
+    expect(row.session_id).toBe('s-new');
+    expect(row.project_path).toBe('/tmp/proj');
+    expect(row.first_prompt).toBe('你好');
+    expect(row.start_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.end_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.event_count).toBe(1);
+  });
+
+  it('同一 session 多次事件应累加 event_count 并推进 end_time', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'first',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:05:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 's-multi',
+      timestamp: '2026-05-10T10:10:00.000Z',
+      hook_type: 'PostToolUse',
+      tool_name: 'Read',
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT event_count, start_time, end_time, last_event_time FROM sessions WHERE session_id = ?')
+      .get('s-multi') as Record<string, unknown>;
+
+    expect(row.event_count).toBe(3);
+    expect(row.start_time).toBe('2026-05-10T10:00:00.000Z');
+    expect(row.end_time).toBe('2026-05-10T10:10:00.000Z');
+    expect(row.last_event_time).toBe('2026-05-10T10:10:00.000Z');
+  });
+
+  it('first_prompt 仅在首次 UserPromptSubmit 时落库，后续事件不覆盖', () => {
+    // 第一条：非 UserPromptSubmit → first_prompt 应为 null
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:00:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+
+    let row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBeNull();
+
+    // 第二条：UserPromptSubmit → first_prompt 应被填充
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:01:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '真正的第一条 prompt',
+    }));
+
+    row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('真正的第一条 prompt');
+
+    // 第三条：又一条 UserPromptSubmit → 不应覆盖第二条
+    storage.writeEvent(makeEvent({
+      session_id: 's-fp',
+      timestamp: '2026-05-10T10:02:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: '后续的 prompt 不应覆盖',
+    }));
+
+    row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-fp') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('真正的第一条 prompt');
+  });
+
+  it('user_prompt 超长时 first_prompt 截断到 200 字', () => {
+    const longPrompt = 'x'.repeat(500);
+    storage.writeEvent(makeEvent({
+      session_id: 's-long',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: longPrompt,
+    }));
+
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('s-long') as Record<string, unknown>;
+    expect((row.first_prompt as string).length).toBe(200);
+  });
+
+  it('querySessions 直接读聚合表，不执行 events 相关子查询', () => {
+    // 构造 3 个 session，每个 3 条事件
+    const sessionIds = ['sq-a', 'sq-b', 'sq-c'];
+    for (const sid of sessionIds) {
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:00.000Z`,
+        hook_type: 'UserPromptSubmit',
+        user_prompt: `prompt of ${sid}`,
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:30.000Z`,
+        hook_type: 'PreToolUse',
+        tool_name: 'Read',
+      }));
+      storage.writeEvent(makeEvent({
+        session_id: sid,
+        timestamp: `2026-05-10T10:0${sessionIds.indexOf(sid)}:40.000Z`,
+        hook_type: 'PostToolUse',
+        tool_name: 'Read',
+      }));
+    }
+
+    // 用 EXPLAIN QUERY PLAN 验证只扫聚合表
+    const plan = storage
+      .getDatabase()
+      .prepare(`EXPLAIN QUERY PLAN
+        SELECT session_id, first_prompt, event_count, start_time,
+               COALESCE(end_time, last_event_time, start_time) AS end_time
+        FROM sessions
+        ORDER BY start_time DESC
+        LIMIT 10`)
+      .all() as Array<{ detail: string }>;
+    const planText = plan.map(p => p.detail).join(' | ');
+    expect(planText).toMatch(/sessions/i);
+    expect(planText).not.toMatch(/events/i);
+
+    const results = storage.querySessions({ limit: 10 });
+    expect(results).toHaveLength(3);
+    expect(results.map(r => r.session_id).sort()).toEqual(['sq-a', 'sq-b', 'sq-c']);
+    // start_time DESC → sq-c, sq-b, sq-a
+    expect(results[0].session_id).toBe('sq-c');
+    for (const r of results) {
+      expect(r.event_count).toBe(3);
+      expect(r.first_prompt).toBe(`prompt of ${r.session_id}`);
+    }
+  });
+
+  it('querySessions 支持 project_path 过滤', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 'proj-a-1',
+      project_path: '/proj/a',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'a-1',
+      timestamp: '2026-05-10T10:00:00.000Z',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'proj-b-1',
+      project_path: '/proj/b',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'b-1',
+      timestamp: '2026-05-10T10:01:00.000Z',
+    }));
+
+    const results = storage.querySessions({ project_path: '/proj/a', limit: 10 });
+    expect(results).toHaveLength(1);
+    expect(results[0].session_id).toBe('proj-a-1');
+  });
+
+  it('backfill 迁移：旧库只有 events、sessions 为空时启动应自动对齐', () => {
+    // 先用当前 storage 写几条事件，随后清空 sessions 模拟旧库
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-1',
+      timestamp: '2026-05-10T09:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'backfill-prompt-1',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-1',
+      timestamp: '2026-05-10T09:05:00.000Z',
+      hook_type: 'PreToolUse',
+      tool_name: 'Read',
+    }));
+    storage.writeEvent(makeEvent({
+      session_id: 'bf-2',
+      timestamp: '2026-05-10T09:10:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'backfill-prompt-2',
+    }));
+
+    // 清空 sessions，模拟"旧库已有 events，但无聚合"
+    storage.getDatabase().exec('DELETE FROM sessions');
+    expect(
+      (storage.getDatabase().prepare('SELECT COUNT(*) AS c FROM sessions').get() as { c: number }).c
+    ).toBe(0);
+
+    // 关闭当前 storage，重新打开 → 触发 runMigrations → backfillSessionsIfNeeded
+    storage.getDatabase().close();
+    storage = new SQLiteStorage(dbPath);
+
+    const rows = storage
+      .getDatabase()
+      .prepare('SELECT session_id, first_prompt, event_count FROM sessions ORDER BY session_id')
+      .all() as Array<Record<string, unknown>>;
+    expect(rows).toHaveLength(2);
+    expect(rows[0].session_id).toBe('bf-1');
+    expect(rows[0].first_prompt).toBe('backfill-prompt-1');
+    expect(rows[0].event_count).toBe(2);
+    expect(rows[1].session_id).toBe('bf-2');
+    expect(rows[1].first_prompt).toBe('backfill-prompt-2');
+    expect(rows[1].event_count).toBe(1);
+  });
+
+  it('backfill 幂等：sessions 已有 first_prompt 时再次打开不会重复回填/覆盖', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 'idem-1',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'original',
+      timestamp: '2026-05-10T08:00:00.000Z',
+    }));
+
+    // 手工把 event_count 改成一个明显异常值，重新打开后如果被 backfill 覆盖就会恢复为 1
+    storage.getDatabase().prepare('UPDATE sessions SET event_count = 999 WHERE session_id = ?').run('idem-1');
+    storage.getDatabase().close();
+
+    storage = new SQLiteStorage(dbPath);
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT event_count, first_prompt FROM sessions WHERE session_id = ?')
+      .get('idem-1') as Record<string, unknown>;
+    expect(row.event_count).toBe(999); // 未被回填覆盖
+    expect(row.first_prompt).toBe('original');
+  });
+
+  it('upsertSession 失败不应阻塞 writeEvent 的事件写入', () => {
+    // 注入一个会让 upsert 抛错的场景：伪造一个 hook_type 约束内合法但 session 列有
+    // 致命冲突的情况较复杂，这里改用直接 monkey-patch upsertSession 来模拟失败路径，
+    // 断言 events 表仍然写入成功。
+    const originalUpsert = storage.upsertSession.bind(storage);
+    let upsertCalls = 0;
+    storage.upsertSession = (evt: ForgeEvent): void => {
+      upsertCalls += 1;
+      throw new Error('simulated upsert failure');
+    };
+
+    const evt = makeEvent({
+      session_id: 'fail-session',
+      timestamp: '2026-05-10T11:00:00.000Z',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'still written',
+    });
+    expect(() => storage.writeEvent(evt)).not.toThrow();
+    expect(upsertCalls).toBe(1);
+
+    // events 表中应该有这条事件
+    const eventRow = storage
+      .getDatabase()
+      .prepare('SELECT session_id, user_prompt FROM events WHERE session_id = ?')
+      .get('fail-session') as Record<string, unknown>;
+    expect(eventRow).toBeDefined();
+    expect(eventRow.user_prompt).toBe('still written');
+
+    // 恢复，避免污染其它用例
+    storage.upsertSession = originalUpsert;
+  });
+
+  it('runMigrations 对已有 first_prompt 列的库应幂等（重复打开不报错）', () => {
+    storage.writeEvent(makeEvent({
+      session_id: 're-open',
+      hook_type: 'UserPromptSubmit',
+      user_prompt: 'hi',
+    }));
+    storage.getDatabase().close();
+
+    // 再打开两次，不应抛异常
+    expect(() => {
+      const s2 = new SQLiteStorage(dbPath);
+      s2.getDatabase().close();
+      const s3 = new SQLiteStorage(dbPath);
+      s3.getDatabase().close();
+    }).not.toThrow();
+
+    storage = new SQLiteStorage(dbPath);
+    const row = storage
+      .getDatabase()
+      .prepare('SELECT first_prompt FROM sessions WHERE session_id = ?')
+      .get('re-open') as Record<string, unknown>;
+    expect(row.first_prompt).toBe('hi');
+  });
+});
+
+describe('SQLiteStorage: legacy DB without first_prompt column', () => {
+  let tmp: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-sess-legacy-'));
+    dbPath = join(tmp, 'legacy.db');
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('旧 sessions 表无 first_prompt 列时 runMigrations 应自动 ALTER + backfill', () => {
+    // 手工建一个老版本的库：events 表 + 老 sessions 表（无 first_prompt 列）
+    const raw = new Database(dbPath);
+    raw.exec(`
+      CREATE TABLE events (
+        event_id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        project_path TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        hook_type TEXT NOT NULL,
+        tool_name TEXT,
+        tool_input TEXT,
+        tool_output TEXT,
+        user_prompt TEXT,
+        ai_response TEXT,
+        distilled INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now'))
+      );
+      CREATE TABLE sessions (
+        session_id TEXT PRIMARY KEY,
+        project_path TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'active',
+        start_time TEXT NOT NULL,
+        end_time TEXT,
+        last_event_time TEXT,
+        event_count INTEGER DEFAULT 0,
+        created_at TEXT DEFAULT (datetime('now')),
+        updated_at TEXT DEFAULT (datetime('now'))
+      );
+    `);
+    // 插入 events（模拟旧库残留的未聚合数据）
+    raw.prepare(`
+      INSERT INTO events (event_id, session_id, project_path, timestamp, hook_type, user_prompt)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run('e1', 'legacy-1', '/proj', '2026-05-10T07:00:00.000Z', 'UserPromptSubmit', 'legacy prompt');
+    raw.prepare(`
+      INSERT INTO events (event_id, session_id, project_path, timestamp, hook_type, tool_name)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run('e2', 'legacy-1', '/proj', '2026-05-10T07:05:00.000Z', 'PreToolUse', 'Read');
+    raw.close();
+
+    // 用 SQLiteStorage 打开 → 期待：ALTER 加 first_prompt 列 + backfill
+    const storage = new SQLiteStorage(dbPath);
+    try {
+      // 列存在
+      const cols = storage
+        .getDatabase()
+        .prepare('PRAGMA table_info(sessions)')
+        .all() as Array<{ name: string }>;
+      expect(cols.some(c => c.name === 'first_prompt')).toBe(true);
+
+      // backfill 填充
+      const row = storage
+        .getDatabase()
+        .prepare('SELECT first_prompt, event_count FROM sessions WHERE session_id = ?')
+        .get('legacy-1') as Record<string, unknown>;
+      expect(row).toBeDefined();
+      expect(row.first_prompt).toBe('legacy prompt');
+      expect(row.event_count).toBe(2);
+    } finally {
+      storage.getDatabase().close();
+    }
+  });
+});

package/tests/unit/storage/skill-operations-counts.test.ts

@@ -0,0 +1,106 @@
+/**
+ * H2: SkillOperations 新增 count / query 方法测试
+ *
+ * 覆盖 4 个方法：
+ *   countAllSkillInvocations
+ *   countSkillInvocationsBySession
+ *   countDistinctSkillsSince
+ *   queryDistinctSkillIdsBySession
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+import type { SkillInvocationRow } from '../../../src/core/storage/rows.js';
+
+describe('SkillOperations H2 counts', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h2-skills-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  function makeInv(overrides: Partial<SkillInvocationRow>): Omit<SkillInvocationRow, 'created_at'> {
+    return {
+      id: `inv-${Math.random().toString(36).slice(2, 10)}`,
+      route_request_id: null,
+      session_id: 's1',
+      agent_id: null,
+      skill_id: 'skill-a',
+      invocation_type: 'manual',
+      reason: null,
+      workflow: null,
+      phase: null,
+      feature_slug: null,
+      artifact_path: null,
+      depth: 0,
+      success: 1,
+      error: null,
+      timestamp: Date.now(),
+      ...overrides,
+    };
+  }
+
+  describe('countAllSkillInvocations', () => {
+    it('空表返回 0', () => {
+      expect(storage.countAllSkillInvocations()).toBe(0);
+    });
+    it('多条返回总数', () => {
+      storage.writeSkillInvocation(makeInv({ id: 'a' }));
+      storage.writeSkillInvocation(makeInv({ id: 'b' }));
+      storage.writeSkillInvocation(makeInv({ id: 'c' }));
+      expect(storage.countAllSkillInvocations()).toBe(3);
+    });
+  });
+
+  describe('countSkillInvocationsBySession', () => {
+    it('未匹配 session 返回 0', () => {
+      expect(storage.countSkillInvocationsBySession('nope')).toBe(0);
+    });
+    it('按 session_id 计数', () => {
+      storage.writeSkillInvocation(makeInv({ id: 'a', session_id: 's1' }));
+      storage.writeSkillInvocation(makeInv({ id: 'b', session_id: 's1' }));
+      storage.writeSkillInvocation(makeInv({ id: 'c', session_id: 's2' }));
+      expect(storage.countSkillInvocationsBySession('s1')).toBe(2);
+      expect(storage.countSkillInvocationsBySession('s2')).toBe(1);
+    });
+  });
+
+  describe('countDistinctSkillsSince', () => {
+    it('空表返回 0', () => {
+      expect(storage.countDistinctSkillsSince(0)).toBe(0);
+    });
+    it('distinct skill_id 计数，since 过滤', () => {
+      const now = Date.now();
+      storage.writeSkillInvocation(makeInv({ id: 'a', skill_id: 'x', timestamp: now }));
+      storage.writeSkillInvocation(makeInv({ id: 'b', skill_id: 'x', timestamp: now }));
+      storage.writeSkillInvocation(makeInv({ id: 'c', skill_id: 'y', timestamp: now }));
+      storage.writeSkillInvocation(makeInv({ id: 'd', skill_id: 'z', timestamp: now - 1_000_000 }));
+      expect(storage.countDistinctSkillsSince(now)).toBe(2);  // x, y
+      expect(storage.countDistinctSkillsSince(0)).toBe(3);    // x, y, z
+    });
+  });
+
+  describe('queryDistinctSkillIdsBySession', () => {
+    it('未匹配返回空', () => {
+      expect(storage.queryDistinctSkillIdsBySession('nope')).toEqual([]);
+    });
+    it('按 session 返回 distinct skill_id', () => {
+      storage.writeSkillInvocation(makeInv({ id: 'a', session_id: 's1', skill_id: 'x' }));
+      storage.writeSkillInvocation(makeInv({ id: 'b', session_id: 's1', skill_id: 'x' }));
+      storage.writeSkillInvocation(makeInv({ id: 'c', session_id: 's1', skill_id: 'y' }));
+      storage.writeSkillInvocation(makeInv({ id: 'd', session_id: 's2', skill_id: 'z' }));
+      const r = storage.queryDistinctSkillIdsBySession('s1');
+      expect(r.sort()).toEqual(['x', 'y']);
+    });
+  });
+});

package/tests/unit/storage/skills-aggregates.test.ts

@@ -0,0 +1,104 @@
+/**
+ * H1 storage aggregates: skill_invocations
+ *
+ * 覆盖：
+ *   - 空表返回 []
+ *   - success=1/0 分别计数
+ *   - 按 total 降序
+ *   - since 过滤边界
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SQLiteStorage } from '../../../src/core/storage/sqlite.js';
+
+const SESSION = 'sess-s';
+
+function makeInv(overrides: {
+  id: string;
+  skill_id: string;
+  success: 0 | 1;
+  timestamp: number;
+  error?: string | null;
+}) {
+  return {
+    id: overrides.id,
+    route_request_id: null,
+    session_id: SESSION,
+    agent_id: null,
+    skill_id: overrides.skill_id,
+    invocation_type: 'dynamic' as const,
+    reason: null,
+    workflow: null,
+    phase: null,
+    feature_slug: null,
+    artifact_path: null,
+    depth: 0,
+    success: overrides.success,
+    error: overrides.error ?? null,
+    timestamp: overrides.timestamp,
+  };
+}
+
+describe('storage.aggregateSkillInvocationsBySkill', () => {
+  let tmp: string;
+  let storage: SQLiteStorage;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'forge-h1-skills-'));
+    storage = new SQLiteStorage(join(tmp, 'data.db'));
+  });
+
+  afterEach(() => {
+    try { storage.close(); } catch { /* ignore */ }
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('空表返回 []', () => {
+    expect(storage.aggregateSkillInvocationsBySkill({ since: 0 })).toEqual([]);
+  });
+
+  it('success=1/0 分别计数；按 total 降序', () => {
+    const now = Date.now();
+    // tdd: 2 success + 1 failed = 3
+    storage.writeSkillInvocation(makeInv({ id: 'i1', skill_id: 'tdd', success: 1, timestamp: now }));
+    storage.writeSkillInvocation(makeInv({ id: 'i2', skill_id: 'tdd', success: 1, timestamp: now }));
+    storage.writeSkillInvocation(makeInv({ id: 'i3', skill_id: 'tdd', success: 0, timestamp: now, error: 'boom' }));
+    // debug: 1 success
+    storage.writeSkillInvocation(makeInv({ id: 'i4', skill_id: 'debug', success: 1, timestamp: now }));
+
+    const r = storage.aggregateSkillInvocationsBySkill({ since: 0 });
+    expect(r).toHaveLength(2);
+    // 排序：tdd 3 > debug 1
+    expect(r[0]).toEqual({ skill_id: 'tdd', total: 3, success: 2, failed: 1 });
+    expect(r[1]).toEqual({ skill_id: 'debug', total: 1, success: 1, failed: 0 });
+  });
+
+  it('since 过滤（旧 invocation 被排除）', () => {
+    const old = Date.now() - 10 * 24 * 3600 * 1000;
+    const fresh = Date.now();
+    storage.writeSkillInvocation(makeInv({ id: 'old', skill_id: 'tdd', success: 1, timestamp: old }));
+    storage.writeSkillInvocation(makeInv({ id: 'new', skill_id: 'tdd', success: 1, timestamp: fresh }));
+
+    const sevenDaysAgo = Date.now() - 7 * 24 * 3600 * 1000;
+    const r = storage.aggregateSkillInvocationsBySkill({ since: sevenDaysAgo });
+    expect(r).toHaveLength(1);
+    expect(r[0]).toEqual({ skill_id: 'tdd', total: 1, success: 1, failed: 0 });
+  });
+
+  it('since 边界：>= 通过', () => {
+    storage.writeSkillInvocation(makeInv({ id: 'b1', skill_id: 'tdd', success: 1, timestamp: 1000 }));
+    storage.writeSkillInvocation(makeInv({ id: 'b2', skill_id: 'tdd', success: 1, timestamp: 2000 }));
+
+    const r1 = storage.aggregateSkillInvocationsBySkill({ since: 2000 });
+    expect(r1[0].total).toBe(1);
+
+    const r2 = storage.aggregateSkillInvocationsBySkill({ since: 1000 });
+    expect(r2[0].total).toBe(2);
+
+    const r3 = storage.aggregateSkillInvocationsBySkill({ since: 2001 });
+    expect(r3).toEqual([]);
+  });
+});