@morlay/session-rdb 0.1.10-alpha.0 → 0.1.10-alpha.2

package/src/db/open.ts

@@ -0,0 +1,180 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, open as openFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { ensureSchema, openDatabase as openRdbkitDatabase, runMigrations, type Database } from "@morlay/rdbkit";
+import type { Backend } from "../backend.ts";
+import { catalog, persistenceState } from "../entities/index.ts";
+import { sessionMigrations } from "../migrations.ts";
+import { createReadModel } from "../storage-takeover/read-model.ts";
+import { createStorageRepository } from "../storage-takeover/repository.ts";
+import {
+  DEFAULT_BUSY_TIMEOUT_MS,
+  SCHEMA_VERSION,
+  SESSION_PERSISTENCE_SQLITE_APPLICATION_ID,
+  type JournalMode,
+} from "../version.ts";
+import { backfillUsageTables } from "./stats.ts";
+import { RdbBackend } from "../backend-rdb.ts";
+
+export type BackendConfig =
+  | { type: "sqlite"; path: string; journalMode?: JournalMode; busyTimeout?: number }
+  | { type: "postgres"; connectionString: string; schema?: string };
+
+
+/**
+ * 写事务按介质串行：SQLite 的 `BEGIN IMMEDIATE` 并发会直接 busy，PG 的 `serializable` 并发会冲突；
+ * 同一个库（进程内多个实例）共用一条队列。
+ */
+const writeQueues = new Map<string, Promise<void>>();
+
+function enqueueWrite<T>(key: string, fn: () => Promise<T>): Promise<T> {
+  const tail = writeQueues.get(key) ?? Promise.resolve();
+  const run = tail.then(fn);
+  writeQueues.set(
+    key,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return run;
+}
+
+/** 打开数据库、对齐结构、跑迁移、落 identity（连接、库身份、回填都在这一步）。 */
+export async function openRdbBackend(config: BackendConfig): Promise<Backend> {
+  const schema = config.type === "postgres" ? (config.schema ?? "public") : "";
+  const actualPath =
+    config.type === "sqlite" && config.path !== ":memory:" ? resolve(config.path) : undefined;
+  if (actualPath !== undefined) {
+    // 库文件与目录的权限：目录 0700（不改变已有目录的 mode），文件 0600（WAL / SHM 继承）。
+    await mkdir(dirname(actualPath), { recursive: true, mode: 0o700 });
+    try {
+      // 独占创建：新建的文件固定 0600；已存在的文件保留它自己的 mode。
+      const handle = await openFile(actualPath, "wx", 0o600);
+      await handle.close();
+      await chmod(actualPath, 0o600);
+    } catch (error) {
+      if ((error as { code?: string }).code !== "EEXIST") throw error;
+    }
+  }
+  const database = await openRdbkitDatabase(
+    config.type === "sqlite"
+      ? {
+          dialect: "sqlite",
+          path: actualPath ?? config.path,
+          ...(config.journalMode === undefined ? {} : { journalMode: config.journalMode }),
+          // journal_mode 等校验通过后再切（拒绝旧库时不能改动它）。
+          applyJournalMode: false,
+          busyTimeout: config.busyTimeout ?? DEFAULT_BUSY_TIMEOUT_MS,
+          cacheSizeKb: 65536,
+          mmapSize: 268435456,
+        }
+      : {
+          dialect: "postgres",
+          connectionString: config.connectionString,
+          ...(config.schema === undefined ? {} : { schema: config.schema }),
+          isolationLevel: "serializable",
+        },
+  );
+
+  try {
+    let onDisk = 0;
+    if (config.type === "sqlite") {
+      onDisk = Number((await database.sqlitePragma("user_version")) ?? 0);
+      const applicationId = Number((await database.sqlitePragma("application_id")) ?? 0);
+      if (onDisk !== 0 && onDisk !== SCHEMA_VERSION) {
+        throw new Error(
+          `session database at "${config.path}" has schema version ${onDisk}, incompatible with this build (${SCHEMA_VERSION})`,
+        );
+      }
+      if (onDisk >= 1 && applicationId !== SESSION_PERSISTENCE_SQLITE_APPLICATION_ID) {
+        throw new Error(
+          `session database at "${config.path}" has application id ${applicationId}, expected ${SESSION_PERSISTENCE_SQLITE_APPLICATION_ID}`,
+        );
+      }
+      if (onDisk === 0) {
+        // 有表但没版本标记：旧库或别的程序的库，拒绝并要求显式迁移（空文件才允许初始化）。
+        const objects = await database.objectNames();
+        const foreignApplication =
+          applicationId !== 0 && applicationId !== SESSION_PERSISTENCE_SQLITE_APPLICATION_ID;
+        if (foreignApplication || objects.length > 0) {
+          throw new Error(
+            `session database at "${config.path}" has an unversioned schema or application identity`,
+          );
+        }
+      }
+    }
+
+    const writeKey =
+      config.type === "sqlite"
+        ? `sqlite:${config.path}`
+        : `postgres:${config.connectionString}:${schema}`;
+    const inWrite = <T>(fn: (scoped: Database) => Promise<T>): Promise<T> =>
+      enqueueWrite(writeKey, () => database.transaction(fn));
+
+    if (actualPath !== undefined) {
+      // SQLite 自己创建 WAL / SHM / 回滚日志时用默认 mode（受 umask 影响），统一收成 0600。
+      for (const suffix of ["-wal", "-shm", "-journal"]) {
+        try {
+          await chmod(`${actualPath}${suffix}`, 0o600);
+        } catch {
+          // 文件还没创建（未进入 WAL / 没有回滚日志）就跳过。
+        }
+      }
+    }
+
+    // 打标记、建表、迁移、回填、identity 是**一个事务**：任一步失败都不在库里留痕
+    //（旧版本 / 别人的库被拒时，连表与版本戳都不该出现）。
+    let storeId: string | undefined;
+    await inWrite(async (scoped) => {
+      if (config.type === "sqlite" && onDisk === 0) {
+        await scoped.setSqlitePragma("application_id", SESSION_PERSISTENCE_SQLITE_APPLICATION_ID);
+        await scoped.setSqlitePragma("user_version", SCHEMA_VERSION);
+      }
+      await ensureSchema(scoped, catalog);
+      await runMigrations(scoped, {
+        catalog,
+        migrations: sessionMigrations(),
+      });
+      await backfillUsageTables(scoped);
+
+      const state = persistenceState.table(scoped);
+      await state.insertIgnore({ f_singleton: 1, f_store_id: randomUUID() }, ["f_singleton"]);
+      for await (const row of state.select({ storeId: state.f_store_id })) storeId = row.storeId;
+    });
+    if (storeId === undefined || storeId.length === 0) {
+      throw new Error("session database has no valid store identity");
+    }
+    if (config.type === "sqlite") {
+      // 结构对齐成功后才切 journal_mode：被拒的库不能被改动。
+      await database.setSqlitePragma("journal_mode", (config.journalMode ?? "wal").toLowerCase());
+    }
+
+    const storage = createStorageRepository({
+      database,
+      writeAtomically: (fn) => inWrite((scoped) => fn(scoped)),
+    });
+    const storeIdentity =
+      config.type === "sqlite"
+        ? actualPath === undefined
+          ? `memory:store:${storeId}`
+          : await fileIdentity(actualPath, storeId)
+        : `${config.type}:${config.connectionString}:${schema}:store:${storeId}`;
+    return new RdbBackend({
+      kind: config.type,
+      database,
+      storage,
+      readModel: createReadModel(database),
+      storeIdentity,
+    });
+  } catch (error) {
+    await database.close();
+    throw error;
+  }
+}
+
+/** 库文件身份：`file:dev:ino:birthtimeNs:store:<storeId>`（符号链接指向同一 inode 时身份相同）。 */
+async function fileIdentity(path: string, storeId: string): Promise<string> {
+  const identity = await stat(path, { bigint: true });
+  return `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${storeId}`;
+}

package/src/db/stats.ts

@@ -0,0 +1,449 @@
+import {
+  E,
+  count,
+  sum,
+  type Database,
+  type OperandInput,
+  type Table,
+  type TableDef,
+} from "@morlay/rdbkit";
+import type {
+  SessionCountBucket,
+  SessionListRowsPage,
+  SessionListRowsQuery,
+  SessionUsageBucket,
+} from "../backend.ts";
+import {
+  eventUsage,
+  events,
+  sessionCounts,
+  sessionEvents,
+  sessions,
+  sessionUsage,
+} from "../entities/index.ts";
+import type { StorageRepository } from "../storage-takeover/types.ts";
+import {
+  deleteSessionStats as deleteSessionStatsRows,
+  incrementSessionCounts as incrementSessionCountsRows,
+  incrementSessionUsage as incrementSessionUsageRows,
+  listSessionRows as listSessionRowsQuery,
+  rebuildSessionStats as rebuildSessionStatsRows,
+  refreshEventUsageFlags as refreshEventUsageFlagsRows,
+  usageActivityScope,
+  usageBuckets,
+  usageSessionCounts,
+  usageSessionTokens,
+  usageTokenScope,
+} from "../session-ops.ts";
+import type { UsageAggregate } from "../usage.ts";
+import { COUNTED_EVENT_TYPES } from "../usage.ts";
+
+function asText(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+export async function usageReport(database: Database, sinceMs?: number): Promise<UsageAggregate> {
+  const buckets = await usageBuckets(database, sinceMs);
+  const tokenScope = await usageTokenScope(database, sinceMs);
+  const activityScope = await usageActivityScope(database, sinceMs);
+  const tokenSessions = await usageSessionTokens(database, sinceMs);
+  const activitySessions = await usageSessionCounts(database, sinceMs);
+
+    const toToken = (row: Record<string, unknown>) => ({
+      inputTokens: Number(row["input_tokens"] ?? 0),
+      outputTokens: Number(row["output_tokens"] ?? 0),
+      cacheReadTokens: Number(row["cache_read_tokens"] ?? 0),
+      reasoningTokens: Number(row["reasoning_tokens"] ?? 0),
+      totalTokens: Number(row["total_tokens"] ?? 0),
+    });
+    const toActivity = (row: Record<string, unknown>) => ({
+      turns: Number(row["turns"] ?? 0),
+      steps: Number(row["steps"] ?? 0),
+      userInputs: Number(row["user_inputs"] ?? 0),
+      toolCalls: Number(row["tool_calls"] ?? 0),
+    });
+    const emptyToken = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, reasoningTokens: 0, totalTokens: 0 };
+    const emptyActivity = { turns: 0, steps: 0, userInputs: 0, toolCalls: 0 };
+    const addToken = (target: ReturnType<typeof toToken>, row: Record<string, unknown>) => {
+      const token = toToken(row);
+      target.inputTokens += token.inputTokens;
+      target.outputTokens += token.outputTokens;
+      target.cacheReadTokens += token.cacheReadTokens;
+      target.reasoningTokens += token.reasoningTokens;
+      target.totalTokens += token.totalTokens;
+    };
+    const addActivity = (target: ReturnType<typeof toActivity>, row: Record<string, unknown>) => {
+      const activity = toActivity(row);
+      target.turns += activity.turns;
+      target.steps += activity.steps;
+      target.userInputs += activity.userInputs;
+      target.toolCalls += activity.toolCalls;
+    };
+    const sum = (left: typeof emptyToken & typeof emptyActivity, right: typeof emptyToken & typeof emptyActivity) => ({
+      inputTokens: left.inputTokens + right.inputTokens,
+      outputTokens: left.outputTokens + right.outputTokens,
+      cacheReadTokens: left.cacheReadTokens + right.cacheReadTokens,
+      reasoningTokens: left.reasoningTokens + right.reasoningTokens,
+      totalTokens: left.totalTokens + right.totalTokens,
+      turns: left.turns + right.turns,
+      steps: left.steps + right.steps,
+      userInputs: left.userInputs + right.userInputs,
+      toolCalls: left.toolCalls + right.toolCalls,
+    });
+
+    const human = { ...emptyToken, ...emptyActivity };
+    const subagent = { ...emptyToken, ...emptyActivity };
+    for (const row of tokenScope) {
+      addToken(Number(row.subagent) === 1 ? subagent : human, row);
+    }
+    for (const row of activityScope) {
+      addActivity(Number(row["subagent"]) === 1 ? subagent : human, row);
+    }
+    const activityBySession = new Map<string, ReturnType<typeof toActivity>>();
+    for (const row of activitySessions) {
+      activityBySession.set(String(row["session_id"]), toActivity(row));
+    }
+    return {
+      totals: sum(sum({ ...emptyToken, ...emptyActivity }, human), subagent),
+      subagent,
+      human,
+      buckets: buckets.map((row) => ({
+        day: String(row.day),
+        provider: row.provider,
+        model: row.model,
+        subagent: Number(row.subagent) === 1,
+        ...toToken(row as unknown as Record<string, unknown>),
+      })),
+      sessions: tokenSessions.map((row) => ({
+        sessionId: String(row["session_id"]),
+        title: asText(row["title"]),
+        subagent: Number(row["subagent"]) === 1 || row["subagent"] === true,
+        archived: Number(row["archived"]) === 1 || row["archived"] === true,
+        ...toToken(row),
+        ...(activityBySession.get(String(row["session_id"])) ?? emptyActivity),
+      })),
+    };
+  }
+
+export async function listSessionRows(
+  database: Database,
+  storage: StorageRepository,
+  query?: SessionListRowsQuery,
+): Promise<SessionListRowsPage> {
+    const needle = query?.query?.trim().toLowerCase() ?? "";
+    const index = await storage.listWorkspaceIndex();
+    const titleMatches =
+      needle === ""
+        ? []
+        : [
+            ...new Set(
+              index
+                .filter((entry) => entry.title.toLowerCase().includes(needle))
+                .flatMap((entry) => entry.sessionIds),
+            ),
+          ];
+    const { items, total } = await listSessionRowsQuery(database, {
+      needle,
+      titleMatches,
+      includeSubagents: query?.includeSubagents === true,
+      limit: query?.limit ?? 20,
+      offset: query?.offset ?? 0,
+    });
+    const workspaceOf = new Map<string, string>();
+    for (const entry of index) {
+      for (const sessionId of entry.sessionIds) {
+        if (!workspaceOf.has(sessionId)) workspaceOf.set(sessionId, entry.title);
+      }
+    }
+    return {
+      items: items.map((row) => ({
+        sessionId: String(row["session_id"]),
+        title: asText(row["title"]),
+        origin: asText(row["origin"]),
+        cwd: asText(row["cwd"]),
+        createdAt: Number(row["created_at"]),
+        updatedAt: Number(row["updated_at"]),
+        archived: Number(row["archived"]) === 1 || row["archived"] === true,
+        subagent: row["origin"] === "subagent",
+        workspace: workspaceOf.get(String(row["session_id"])) ?? null,
+      })),
+      total,
+    };
+  }
+
+export async function incrementSessionUsage(
+  database: Database,
+  id: string,
+  buckets: readonly SessionUsageBucket[],
+): Promise<void> {
+    await incrementSessionUsageRows(database, id, buckets);
+  }
+
+export async function incrementSessionCounts(
+  database: Database,
+  id: string,
+  buckets: readonly SessionCountBucket[],
+): Promise<void> {
+    await incrementSessionCountsRows(database, id, buckets);
+  }
+
+export async function deleteSessionStats(database: Database, id: string): Promise<void> {
+    await deleteSessionStatsRows(database, id);
+  }
+
+export async function rebuildSessionStats(database: Database, id: string): Promise<void> {
+    const links = sessionEvents.table(database);
+    const eventsTable = events.table(database);
+    const usageTable = eventUsage.table(database);
+
+    // 用量：本会话桥接行 × 用量行，按 (本地日, provider, model) 聚合。
+    const usage = links
+      .select({
+        f_session_id: links.f_session_id,
+        f_day: usageTable.f_day,
+        f_provider: E.coalesce(usageTable.f_provider, ""),
+        f_model: E.coalesce(usageTable.f_model, ""),
+        f_input_tokens: sum("f_input_tokens", "t_event_usage"),
+        f_output_tokens: sum("f_output_tokens", "t_event_usage"),
+        f_cache_read_tokens: sum("f_cache_read_tokens", "t_event_usage"),
+        f_reasoning_tokens: sum("f_reasoning_tokens", "t_event_usage"),
+        f_total_tokens: sum("f_total_tokens", "t_event_usage"),
+      })
+      .join(eventUsage, E.eq(usageTable.f_event_id, links.f_event_id))
+      .where(E.eq(links.f_session_id, id))
+      // 按列分组而不是按 `COALESCE` 表达式：PostgreSQL 的 GROUP BY 匹配按语法树，参数化的表达式
+      // 在 SELECT 与 GROUP BY 里是两个不同的 Param 节点，会被判成「不在 GROUP BY 里」。
+      .groupBy(links.f_session_id, usageTable.f_day, usageTable.f_provider, usageTable.f_model)
+      .toFragment();
+
+    // 活动计数：本会话桥接行 × 事件行，按本地日聚合四项。
+    const counts = links
+      .select({
+        f_session_id: links.f_session_id,
+        f_day: E.localDay(eventsTable.f_created_at),
+        f_turns: E.countIf(E.eq(eventsTable.f_type, "turn/start")),
+        f_steps: E.countIf(E.eq(eventsTable.f_type, "step/start")),
+        f_user_inputs: E.countIf(E.eq(eventsTable.f_type, "user/message")),
+        f_tool_calls: E.countIf(E.eq(eventsTable.f_type, "tool/call")),
+      })
+      .join(events, E.eq(eventsTable.f_event_id, links.f_event_id))
+      .where(
+        E.and(
+          E.eq(links.f_session_id, id),
+          E.inList(eventsTable.f_type, [...COUNTED_EVENT_TYPES]),
+        ),
+      )
+      .groupBy(links.f_session_id, E.localDay(eventsTable.f_created_at))
+      .toFragment();
+
+    await rebuildSessionStatsRows(database, id, { usage, counts });
+  }
+
+export async function refreshEventUsageFlags(
+  database: Database,
+  eventIds: readonly string[],
+): Promise<void> {
+    const links = sessionEvents.table(database);
+    const sessionsTable = sessions.table(database);
+    // 相关子查询：外层是被更新的用量行的 `f_event_id`（`UPDATE` 的目标表没有别名，用表名限定）。
+    const refersTo = (eventId: OperandInput) => E.eq(links.f_event_id, eventId);
+    await refreshEventUsageFlagsRows(
+      database,
+      eventIds,
+      {
+        referenced: E.toInt(
+          E.exists(
+            links
+              .select({ one: links.f_event_id })
+              .where(refersTo(E.column("f_event_id", "t_event_usage")))
+              .toFragment(),
+          ),
+        ),
+        subagent: E.toInt(
+          E.exists(
+            links
+              .select({ one: links.f_event_id })
+              .join(sessions, E.eq(sessionsTable.f_session_id, links.f_session_id))
+              .where(
+                E.and(
+                  refersTo(E.column("f_event_id", "t_event_usage")),
+                  E.eq(sessionsTable.f_origin, "subagent"),
+                ),
+              )
+              .toFragment(),
+          ),
+        ),
+      },
+      400,
+    );
+  }
+
+/** 统计表为空时按事件表全量回填（幂等；迁移删表重建、手动清空后自愈）。 */
+export async function backfillUsageTables(database: Database): Promise<void> {
+  const links = sessionEvents.table(database);
+  const eventsTable = events.table(database);
+  const sessionsTable = sessions.table(database);
+  const usageTable = eventUsage.table(database);
+
+  if (await isEmpty(database, eventUsage)) {
+    const hasUsage = (path: string) => E.isNotNull(E.jsonText(eventsTable.f_data, path));
+    const text = (path: string) => E.jsonText(eventsTable.f_data, path);
+    const int = (path: string) => E.coalesce(E.jsonInt(eventsTable.f_data, path), 0);
+    const usagePaths = (field: string) => [
+      `$.data.usage.${field}`,
+      `$.usage.${field}`,
+    ] as const;
+    const input = usagePaths("inputTokens");
+    const output = usagePaths("outputTokens");
+    const cacheRead = usagePaths("cacheReadTokens");
+    const reasoning = usagePaths("reasoningTokens");
+    const total = usagePaths("totalTokens");
+    const referenced = (eventId: OperandInput) =>
+      E.toInt(
+        E.exists(
+          links
+            .select({ one: links.f_event_id })
+            .where(E.eq(links.f_event_id, eventId))
+            .toFragment(),
+        ),
+      );
+    const subagent = (eventId: OperandInput) =>
+      E.toInt(
+        E.exists(
+          links
+            .select({ one: links.f_event_id })
+            .join(sessions, E.eq(sessionsTable.f_session_id, links.f_session_id))
+            .where(E.and(E.eq(links.f_event_id, eventId), E.eq(sessionsTable.f_origin, "subagent")))
+            .toFragment(),
+        ),
+      );
+
+    const source = eventsTable
+      .select({
+        f_event_id: eventsTable.f_event_id,
+        f_created_at: eventsTable.f_created_at,
+        f_day: E.localDay(eventsTable.f_created_at),
+        f_provider: E.coalesce(
+          text("$.data.message.source.provider"),
+          text("$.message.source.provider"),
+        ),
+        f_model: E.coalesce(text("$.data.message.source.model"), text("$.message.source.model")),
+        f_referenced: referenced(E.column("f_event_id", "t_events")),
+        f_subagent: subagent(E.column("f_event_id", "t_events")),
+        f_input_tokens: E.coalesce(int(input[0]), int(input[1]), 0),
+        f_output_tokens: E.coalesce(int(output[0]), int(output[1]), 0),
+        f_cache_read_tokens: E.coalesce(int(cacheRead[0]), int(cacheRead[1]), 0),
+        f_reasoning_tokens: E.coalesce(int(reasoning[0]), int(reasoning[1]), 0),
+        f_total_tokens: E.coalesce(int(total[0]), int(total[1]), 0),
+      })
+      .where(
+        E.and(
+          E.eq(eventsTable.f_type, "assistant/message"),
+          E.or(hasUsage("$.data.usage"), hasUsage("$.usage")),
+        ),
+      )
+      .toFragment();
+
+    await usageTable.insertFromSelect(
+      [
+        "f_event_id",
+        "f_created_at",
+        "f_day",
+        "f_provider",
+        "f_model",
+        "f_referenced",
+        "f_subagent",
+        "f_input_tokens",
+        "f_output_tokens",
+        "f_cache_read_tokens",
+        "f_reasoning_tokens",
+        "f_total_tokens",
+      ],
+      source,
+      { conflict: ["f_event_id"] },
+    );
+  }
+
+  if (await isEmpty(database, sessionUsage)) {
+    const source = links
+      .select({
+        f_session_id: links.f_session_id,
+        f_day: usageTable.f_day,
+        f_provider: E.coalesce(usageTable.f_provider, ""),
+        f_model: E.coalesce(usageTable.f_model, ""),
+        f_input_tokens: sum("f_input_tokens", "t_event_usage"),
+        f_output_tokens: sum("f_output_tokens", "t_event_usage"),
+        f_cache_read_tokens: sum("f_cache_read_tokens", "t_event_usage"),
+        f_reasoning_tokens: sum("f_reasoning_tokens", "t_event_usage"),
+        f_total_tokens: sum("f_total_tokens", "t_event_usage"),
+      })
+      .join(eventUsage, E.eq(usageTable.f_event_id, links.f_event_id))
+      // 同上：分组用列，`COALESCE` 只留在投影里。
+      .groupBy(links.f_session_id, usageTable.f_day, usageTable.f_provider, usageTable.f_model)
+      .toFragment();
+    await sessionUsage.table(database).insertFromSelect(
+      [
+        "f_session_id",
+        "f_day",
+        "f_provider",
+        "f_model",
+        "f_input_tokens",
+        "f_output_tokens",
+        "f_cache_read_tokens",
+        "f_reasoning_tokens",
+        "f_total_tokens",
+      ],
+      source,
+      { conflict: ["f_session_id", "f_day", "f_provider", "f_model"] },
+    );
+  }
+
+  if (await isEmpty(database, sessionCounts)) {
+    const source = links
+      .select({
+        f_session_id: links.f_session_id,
+        f_day: E.localDay(eventsTable.f_created_at),
+        f_turns: E.countIf(E.eq(eventsTable.f_type, "turn/start")),
+        f_steps: E.countIf(E.eq(eventsTable.f_type, "step/start")),
+        f_user_inputs: E.countIf(E.eq(eventsTable.f_type, "user/message")),
+        f_tool_calls: E.countIf(E.eq(eventsTable.f_type, "tool/call")),
+      })
+      .join(events, E.eq(eventsTable.f_event_id, links.f_event_id))
+      .where(E.inList(eventsTable.f_type, [...COUNTED_EVENT_TYPES]))
+      .groupBy(links.f_session_id, E.localDay(eventsTable.f_created_at))
+      .toFragment();
+    await sessionCounts.table(database).insertFromSelect(
+      ["f_session_id", "f_day", "f_turns", "f_steps", "f_user_inputs", "f_tool_calls"],
+      source,
+      { conflict: ["f_session_id", "f_day"] },
+    );
+  }
+}
+
+async function isEmpty<T extends TableDef>(database: Database, definition: Table<T>): Promise<boolean> {
+  for await (const row of definition.table(database).select({ n: count() })) {
+    // PostgreSQL 的 COUNT 返回 int8 → BigInt，`0n === 0` 是 false，必须显式转。
+    return Number(row.n) === 0;
+  }
+  return true;
+}
+
+/**
+ * 整理数据的一步：三张派生统计表**清空后全量重算**。
+ *
+ * 这三张表本来就是可销毁重建的派生数据（见 ADR-统计衍生表物化归属与汇总），所以重算走「删了再回填」
+ * 这条与打开时自愈相同的路径，不逐会话补差。
+ * @param database - 执行面。
+ * @returns 重建涉及的会话数。
+ */
+export async function rebuildAllStats(database: Database): Promise<number> {
+  await sessionUsage.table(database).delete();
+  await sessionCounts.table(database).delete();
+  await eventUsage.table(database).delete();
+  await backfillUsageTables(database);
+  let total = 0;
+  for await (const row of sessions.table(database).select({ n: count() })) {
+    total = Number(row.n);
+  }
+  return total;
+}

package/src/deletion-error.ts

@@ -0,0 +1,17 @@
+/**
+ * 会话删除的失败语义（叶子模块）。
+ *
+ * 放成叶子是为了断开 `session-store ↔ deletion` 的运行时环：HTTP 路由只依赖这个错误类型，不再值引入整个服务。
+现在 `deletion.ts` 对它只剩 `import type`，运行时环为 0。
+ */
+export type SessionDeletionErrorCode = "SESSION_NOT_FOUND" | "SESSION_NOT_ARCHIVED" | "SESSION_LIVE";
+
+export class SessionDeletionError extends Error {
+  constructor(
+    message: string,
+    readonly code: SessionDeletionErrorCode,
+  ) {
+    super(message);
+    this.name = "SessionDeletionError";
+  }
+}