@morlay/session-rdb 0.0.21-alpha.7 → 0.0.21-alpha.8

package/dist/storage.d.mts

@@ -1,4 +1,4 @@
-import { A as eventKind, B as tWorkspaceState, C as EVENT_ENCODING, D as SCHEMA_VERSION, E as JournalMode, F as tSessionEvents, H as WriteGuard, I as tSessionProjcacheRows, L as tSessions, M as tEvents, N as tPersistenceState, O as SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, P as tSchemaMeta, R as tStorageUnits, S as DEFAULT_BUSY_TIMEOUT_MS, T as EventRole, U as StorageRepository, V as tWorkspaces, a as SessionListRowsPage, c as UsageAggregate, i as EventRow, j as tEventUsage, k as eventDimensions, n as BackendTx, o as SessionListRowsQuery, r as EventCountBucket, s as SessionRow, t as Backend, w as EventKind, z as tWorkspaceSessions } from "./backend-E0bmTXpz.mjs";
+import { $ as eventDimensions, A as SessionRow, D as SessionCountBucket, E as EventRow, J as EventKind, K as DEFAULT_BUSY_TIMEOUT_MS, M as UsageAggregate, O as SessionListRowsPage, Q as SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, T as BackendTx, X as JournalMode, Y as EventRole, Z as SCHEMA_VERSION, at as tSessionCounts, ct as tSessionUsage, dt as tWorkspaceSessions, et as eventKind, ft as tWorkspaceState, ht as StorageRepository, it as tSchemaMeta, j as SessionUsageBucket, k as SessionListRowsQuery, lt as tSessions, mt as WriteGuard, nt as tEvents, ot as tSessionEvents, pt as tWorkspaces, q as EVENT_ENCODING, rt as tPersistenceState, st as tSessionProjcacheRows, tt as tEventUsage, ut as tStorageUnits, w as Backend } from "./log-BbleqD1M.mjs";
 import { SessionId } from "@deepseek-ai/dsh-session";
 import { DatabaseSync } from "node:sqlite";
 //#region src/sqlite.d.ts
@@ -53,14 +53,27 @@ declare class SqliteBackend implements Backend {
    * `f_created_at`（同一时刻写入，口径一致）。
    */
   listSessionRows(query?: SessionListRowsQuery): Promise<SessionListRowsPage>;
+  /**
+   * 用量聚合：只读三张派生统计表——事件级用量行给去重口径的总量与「天 × 模型」桶，
+   * `t_session_usage` / `t_session_counts` 给按会话的行（含 fork 继承前缀）。
+   * 归属、本地日与「是否被引用」都是物化列，这里不再现算、也不回连事件表。
+   * 事件级按毫秒时间戳过滤、汇总表按本地日过滤——`sinceMs` 对齐到本地零点时两者等价。
+   */
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
-  /** 活动计数旁路累加：派生表 `t_event_counts`，不在写事务里（失败可丢，表可销毁重建）。 */
-  incrementEventCounts(id: SessionId, buckets: readonly EventCountBucket[]): Promise<void>;
-  /** 按会话重算活动计数（rewind / fork 之后）：先删该会话的行，再从事件表重算。 */
-  rebuildEventCounts(id: SessionId): Promise<void>;
-  deleteEventCounts(id: SessionId): Promise<void>;
+  /** token 用量旁路累加：派生表 `t_session_usage`，不在写事务里（失败可丢，表可销毁重建）。 */
+  incrementSessionUsage(id: SessionId, buckets: readonly SessionUsageBucket[]): Promise<void>;
+  /** 活动计数旁路累加：派生表 `t_session_counts`，同上（四项计数一次落）。 */
+  incrementSessionCounts(id: SessionId, buckets: readonly SessionCountBucket[]): Promise<void>;
+  /** 按会话重算两张汇总表（rewind / fork 之后）：先删该会话的行，再从事件表重算。 */
+  rebuildSessionStats(id: SessionId): Promise<void>;
+  /**
+   * 全量重算用量行的引用标记：rewind 截断 / fork 复用 / 会话删除都会让「引用」跨会话变化，
+   * 只按本会话判定不够。低频路径，一次全表 UPDATE（3 万行量级）。
+   */
+  refreshEventUsageFlags(): Promise<void>;
+  deleteSessionStats(id: SessionId): Promise<void>;
   vacuum(): Promise<void>;
   private eventRows;
 }
 //#endregion
-export { DEFAULT_BUSY_TIMEOUT_MS, EVENT_ENCODING, EventKind, EventRole, type EventRow, JournalMode, SCHEMA_VERSION, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, type SessionRow, SqliteBackend, SqliteBackendOptions, WriteGuard, eventDimensions, eventKind, openDatabase, tEventUsage, tEvents, tPersistenceState, tSchemaMeta, tSessionEvents, tSessionProjcacheRows, tSessions, tStorageUnits, tWorkspaceSessions, tWorkspaceState, tWorkspaces };
+export { DEFAULT_BUSY_TIMEOUT_MS, EVENT_ENCODING, EventKind, EventRole, type EventRow, JournalMode, SCHEMA_VERSION, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, type SessionRow, SqliteBackend, SqliteBackendOptions, WriteGuard, eventDimensions, eventKind, openDatabase, tEventUsage, tEvents, tPersistenceState, tSchemaMeta, tSessionCounts, tSessionEvents, tSessionProjcacheRows, tSessionUsage, tSessions, tStorageUnits, tWorkspaceSessions, tWorkspaceState, tWorkspaces };

package/dist/storage.mjs

@@ -1,2 +1,2 @@
-import { A as WriteGuard, C as tSessions, D as tWorkspaces, E as tWorkspaceState, S as tSessionProjcacheRows, T as tWorkspaceSessions, _ as tEventUsage, b as tSchemaMeta, d as DEFAULT_BUSY_TIMEOUT_MS, f as EVENT_ENCODING, g as eventKind, h as eventDimensions, m as SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, n as openDatabase, p as SCHEMA_VERSION, t as SqliteBackend, v as tEvents, w as tStorageUnits, x as tSessionEvents, y as tPersistenceState } from "./sqlite-zcXVyMxr.mjs";
-export { DEFAULT_BUSY_TIMEOUT_MS, EVENT_ENCODING, SCHEMA_VERSION, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, SqliteBackend, WriteGuard, eventDimensions, eventKind, openDatabase, tEventUsage, tEvents, tPersistenceState, tSchemaMeta, tSessionEvents, tSessionProjcacheRows, tSessions, tStorageUnits, tWorkspaceSessions, tWorkspaceState, tWorkspaces };
+import { S as tWorkspaces, T as WriteGuard, _ as tSessionUsage, a as EVENT_ENCODING, b as tWorkspaceSessions, c as eventDimensions, d as tEvents, f as tPersistenceState, g as tSessionProjcacheRows, h as tSessionEvents, i as DEFAULT_BUSY_TIMEOUT_MS, l as eventKind, m as tSessionCounts, n as openDatabase, o as SCHEMA_VERSION, p as tSchemaMeta, s as SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, t as SqliteBackend, u as tEventUsage, v as tSessions, x as tWorkspaceState, y as tStorageUnits } from "./sqlite-ChM_sHAG.mjs";
+export { DEFAULT_BUSY_TIMEOUT_MS, EVENT_ENCODING, SCHEMA_VERSION, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID, SqliteBackend, WriteGuard, eventDimensions, eventKind, openDatabase, tEventUsage, tEvents, tPersistenceState, tSchemaMeta, tSessionCounts, tSessionEvents, tSessionProjcacheRows, tSessionUsage, tSessions, tStorageUnits, tWorkspaceSessions, tWorkspaceState, tWorkspaces };

package/dist/testing.d.mts

@@ -1,4 +1,4 @@
-import { v as truncateLiveSession } from "./backend-E0bmTXpz.mjs";
+import { H as truncateLiveSession } from "./log-BbleqD1M.mjs";
 import { SessionPersistence } from "@deepseek-ai/dsh-session-persistence";
 import { Session, SessionEvent, SessionHeader, SessionId } from "@deepseek-ai/dsh-session";
 import { Context, Fiber } from "@deepseek-ai/cordis";

package/dist/testing.mjs

@@ -1,4 +1,4 @@
-import { a as truncateLiveSession } from "./branch-BjUR6wfe.mjs";
+import { a as truncateLiveSession } from "./branch-7eOh_tbO.mjs";
 import { SessionAlreadyExistsError, SessionAlreadyOwnedError, SessionFormatUnsupportedError, SessionHandleClosedError, SessionPersistenceNotFoundError, SessionReadOnlyError } from "@deepseek-ai/dsh-session-persistence";
 import SessionStore, { SESSION_FORMAT_VERSION, SessionId, SessionLogOffset, SessionSeq } from "@deepseek-ai/dsh-session";
 import { Context } from "@deepseek-ai/cordis";

package/drizzle/postgres/20260923120000_v3_usage_materialized/migration.sql

@@ -0,0 +1,48 @@
+-- 统计衍生表：纯派生数据（打开库时按事件表全量回填），迁移直接先删后建，
+-- 不做 ALTER / 数据搬迁。结构与取舍见 ADR-统计衍生表物化归属与汇总。
+DROP TABLE IF EXISTS "t_event_usage";--> statement-breakpoint
+DROP TABLE IF EXISTS "t_event_counts";--> statement-breakpoint
+DROP TABLE IF EXISTS "t_session_usage";--> statement-breakpoint
+DROP TABLE IF EXISTS "t_session_counts";--> statement-breakpoint
+CREATE TABLE "t_event_usage" (
+	"f_event_id" text PRIMARY KEY NOT NULL,
+	"f_created_at" bigint NOT NULL,
+	"f_day" text NOT NULL,
+	"f_provider" text,
+	"f_model" text,
+	"f_referenced" integer DEFAULT 0 NOT NULL,
+	"f_subagent" integer DEFAULT 0 NOT NULL,
+	"f_input_tokens" integer DEFAULT 0 NOT NULL,
+	"f_output_tokens" integer DEFAULT 0 NOT NULL,
+	"f_cache_read_tokens" integer DEFAULT 0 NOT NULL,
+	"f_reasoning_tokens" integer DEFAULT 0 NOT NULL,
+	"f_total_tokens" integer DEFAULT 0 NOT NULL,
+	CONSTRAINT "fk_t_event_usage_f_event_id_t_events_f_event_id_fk" FOREIGN KEY ("f_event_id") REFERENCES "t_events"("f_event_id") ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE INDEX "idx_event_usage_created_at" ON "t_event_usage" USING btree ("f_created_at");--> statement-breakpoint
+CREATE TABLE "t_session_usage" (
+	"f_session_id" text NOT NULL,
+	"f_day" text NOT NULL,
+	"f_provider" text DEFAULT '' NOT NULL,
+	"f_model" text DEFAULT '' NOT NULL,
+	"f_input_tokens" integer DEFAULT 0 NOT NULL,
+	"f_output_tokens" integer DEFAULT 0 NOT NULL,
+	"f_cache_read_tokens" integer DEFAULT 0 NOT NULL,
+	"f_reasoning_tokens" integer DEFAULT 0 NOT NULL,
+	"f_total_tokens" integer DEFAULT 0 NOT NULL,
+	CONSTRAINT "fk_t_session_usage_f_session_id_t_sessions_f_session_id_fk" FOREIGN KEY ("f_session_id") REFERENCES "t_sessions"("f_session_id") ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_session_usage_key" ON "t_session_usage" ("f_session_id","f_day","f_provider","f_model");--> statement-breakpoint
+CREATE TABLE "t_session_counts" (
+	"f_session_id" text NOT NULL,
+	"f_day" text NOT NULL,
+	"f_turns" integer DEFAULT 0 NOT NULL,
+	"f_steps" integer DEFAULT 0 NOT NULL,
+	"f_user_inputs" integer DEFAULT 0 NOT NULL,
+	"f_tool_calls" integer DEFAULT 0 NOT NULL,
+	CONSTRAINT "fk_t_session_counts_f_session_id_t_sessions_f_session_id_fk" FOREIGN KEY ("f_session_id") REFERENCES "t_sessions"("f_session_id") ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX "uq_session_counts_key" ON "t_session_counts" ("f_session_id","f_day");

package/drizzle/sqlite/20260923120000_v3_usage_materialized/migration.sql

@@ -0,0 +1,48 @@
+-- 统计衍生表：纯派生数据（打开库时按事件表全量回填），迁移直接先删后建，
+-- 不做 ALTER / 数据搬迁。结构与取舍见 ADR-统计衍生表物化归属与汇总。
+DROP TABLE IF EXISTS `t_event_usage`;--> statement-breakpoint
+DROP TABLE IF EXISTS `t_event_counts`;--> statement-breakpoint
+DROP TABLE IF EXISTS `t_session_usage`;--> statement-breakpoint
+DROP TABLE IF EXISTS `t_session_counts`;--> statement-breakpoint
+CREATE TABLE `t_event_usage` (
+	`f_event_id` text PRIMARY KEY NOT NULL,
+	`f_created_at` bigint NOT NULL,
+	`f_day` text NOT NULL,
+	`f_provider` text,
+	`f_model` text,
+	`f_referenced` integer DEFAULT 0 NOT NULL,
+	`f_subagent` integer DEFAULT 0 NOT NULL,
+	`f_input_tokens` integer DEFAULT 0 NOT NULL,
+	`f_output_tokens` integer DEFAULT 0 NOT NULL,
+	`f_cache_read_tokens` integer DEFAULT 0 NOT NULL,
+	`f_reasoning_tokens` integer DEFAULT 0 NOT NULL,
+	`f_total_tokens` integer DEFAULT 0 NOT NULL,
+	CONSTRAINT `fk_t_event_usage_f_event_id_t_events_f_event_id_fk` FOREIGN KEY (`f_event_id`) REFERENCES `t_events`(`f_event_id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE INDEX `idx_event_usage_created_at` ON `t_event_usage` (`f_created_at`);--> statement-breakpoint
+CREATE TABLE `t_session_usage` (
+	`f_session_id` text NOT NULL,
+	`f_day` text NOT NULL,
+	`f_provider` text DEFAULT '' NOT NULL,
+	`f_model` text DEFAULT '' NOT NULL,
+	`f_input_tokens` integer DEFAULT 0 NOT NULL,
+	`f_output_tokens` integer DEFAULT 0 NOT NULL,
+	`f_cache_read_tokens` integer DEFAULT 0 NOT NULL,
+	`f_reasoning_tokens` integer DEFAULT 0 NOT NULL,
+	`f_total_tokens` integer DEFAULT 0 NOT NULL,
+	CONSTRAINT `fk_t_session_usage_f_session_id_t_sessions_f_session_id_fk` FOREIGN KEY (`f_session_id`) REFERENCES `t_sessions`(`f_session_id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_session_usage_key` ON `t_session_usage` (`f_session_id`,`f_day`,`f_provider`,`f_model`);--> statement-breakpoint
+CREATE TABLE `t_session_counts` (
+	`f_session_id` text NOT NULL,
+	`f_day` text NOT NULL,
+	`f_turns` integer DEFAULT 0 NOT NULL,
+	`f_steps` integer DEFAULT 0 NOT NULL,
+	`f_user_inputs` integer DEFAULT 0 NOT NULL,
+	`f_tool_calls` integer DEFAULT 0 NOT NULL,
+	CONSTRAINT `fk_t_session_counts_f_session_id_t_sessions_f_session_id_fk` FOREIGN KEY (`f_session_id`) REFERENCES `t_sessions`(`f_session_id`) ON DELETE CASCADE
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uq_session_counts_key` ON `t_session_counts` (`f_session_id`,`f_day`);

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@morlay/session-rdb",
-  "version": "0.0.21-alpha.7",
+  "version": "0.0.21-alpha.8",
   "description": "RDB durable session backend for DeepSeek Harness: implements both session-persistence and session-branch (rewind / retry / fork) providers.",
   "keywords": [
     "branch",
     "dsh",
     "dsh-plugin",
-    "dsh-session-rdb",
     "rdb",
     "rewind",
+    "session-persistence",
     "session-rdb"
   ],
   "license": "MIT",
@@ -41,34 +41,34 @@
     "./locale/*.json": "./locale/*.json"
   },
   "dependencies": {
-    "@morlay/session-branch": "0.0.10-alpha.7",
+    "@morlay/session-branch": "0.0.10-alpha.8",
     "drizzle-orm": "^1.0.0-rc.5-ab785fc",
     "fflate": "^0.8.2",
     "pg": "^8.23.0"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-compaction": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-projection": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-projection-cache": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-turn-outline": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-storage": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-token-meter": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-workspace": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-compaction": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-projection-cache": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-turn-outline": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-storage": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-storage-domain": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-token-meter": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-workspace": "0.1.7-rc.1",
     "@types/pg": "^8.23.1",
     "drizzle-kit": "1.0.0-rc.5-ab785fc"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "4.0.4",
-    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-llm": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-scope": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-format": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-session-query": "0.1.7-alpha.2",
-    "@deepseek-ai/dsh-storage": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-format": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-format-catalog": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-session-query": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-storage": "0.1.7-rc.1",
     "@deepseek-ai/schemastery": "3.18.4"
   },
   "dsh": {

package/src/backend.ts

@@ -1,7 +1,8 @@
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import type { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
+import type { EventUsageRow } from "./log.ts";
 import type { StorageRepository } from "./storage-takeover/types.ts";
-import type { UsageAggregate } from "./usage.ts";
+import type { UsageActivityTotals, UsageAggregate, UsageTokenTotals } from "./usage.ts";
 
 export interface SessionRow {
   fSessionId: string;
@@ -74,7 +75,11 @@ export interface BackendTx {
 
   refreshTitle(id: SessionId): Promise<void>;
 
-  insertEvents(events: EventInsert[]): Promise<void>;
+  /**
+   * 插入事件行与它们的用量行（`usageRows` 由写路径一次折好，读侧维度已物化在行上）。
+   * 这一批事件与桥接行同事务，提交即「被引用」。
+   */
+  insertEvents(events: EventInsert[], usageRows: readonly EventUsageRow[]): Promise<void>;
 
   insertBridges(
     rows: Array<{
@@ -139,11 +144,16 @@ export interface SessionListRowsPage {
   total: number;
 }
 
-/** 活动计数的一个桶：本地日 + 事件类型 + 计数。 */
-export interface EventCountBucket {
+/** 活动计数的一个桶：本地日 + 四项计数（轮次 / 步骤 / 用户输入 / 工具调用）。 */
+export interface SessionCountBucket extends UsageActivityTotals {
+  day: string;
+}
+
+/** 用量累加的一个桶：本地日 + 模型归属 + 五个 token 列。 */
+export interface SessionUsageBucket extends UsageTokenTotals {
   day: string;
-  type: string;
-  count: number;
+  provider: string | null;
+  model: string | null;
 }
 
 export interface Backend {
@@ -178,9 +188,10 @@ export interface Backend {
   listOrphanSubagentSessions(): Promise<SessionId[]>;
 
   /**
-   * 用量统计的原始聚合：token 用量读 `t_event_usage`、活动计数读派生表 `t_event_counts`，
-   * 加按天×模型的桶与按会话的行（事件行去重、排除孤儿）。
-   * @param sinceMs - 只算该时刻（含）之后的事件行；省略即全量。
+   * 用量统计的原始聚合：读三张派生统计表（`t_event_usage` + 两张会话汇总表），
+   * 给出总量 / subagent 拆分、按天×模型的桶与按会话的行（事件行去重、排除孤儿）。
+   * @param sinceMs - 只算该时刻（含）之后的用量；省略即全量。会话汇总表按本地日过滤，
+   * 与毫秒过滤等价的前提是调用方把起点对齐到本地零点（见 `resolveUsageSince`）。
    */
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
 
@@ -188,21 +199,34 @@ export interface Backend {
   listSessionRows(query?: SessionListRowsQuery): Promise<SessionListRowsPage>;
 
   /**
-   * 活动计数**旁路累加**（派生表 `t_event_counts`，不参与写事务、失败可丢——表可销毁重建）：
-   * 每个 (会话, 本地日, 事件类型) 记一行计数。
+   * token 用量**旁路累加**（派生表 `t_session_usage`，不参与写事务、失败可丢——表可销毁重建）：
+   * 每个 (会话, 本地日, 模型) 记一行累加。
+   * @param id - 会话 id。
+   * @param buckets - 本批要累加的 (day, provider, model, tokens)。
+   */
+  incrementSessionUsage(id: SessionId, buckets: readonly SessionUsageBucket[]): Promise<void>;
+
+  /**
+   * 活动计数**旁路累加**（派生表 `t_session_counts`，同上）：每个 (会话, 本地日) 累加四项计数。
    * @param id - 会话 id。
-   * @param buckets - 本批要累加的 (day, type, count)。
+   * @param buckets - 本批要累加的 (day, turns, steps, userInputs, toolCalls)。
    */
-  incrementEventCounts(id: SessionId, buckets: readonly EventCountBucket[]): Promise<void>;
+  incrementSessionCounts(id: SessionId, buckets: readonly SessionCountBucket[]): Promise<void>;
 
   /**
-   * 按会话从事件表重算活动计数（rewind / fork 之后调用）：先删该会话的行再重算。
+   * 按会话从事件表重算两张会话汇总表（rewind / fork 之后调用）：先删该会话的行再重算。
    * @param id - 会话 id。
    */
-  rebuildEventCounts(id: SessionId): Promise<void>;
+  rebuildSessionStats(id: SessionId): Promise<void>;
+
+  /**
+   * 全量重算 `t_event_usage` 的引用标记（`f_referenced` / `f_subagent`）：rewind / fork / 会话删除之后调用。
+   * 引用可能跨会话消失（截断、删除），只按本会话判定不够，故这里是全量。
+   */
+  refreshEventUsageFlags(): Promise<void>;
 
-  /** 删掉一个会话的活动计数行（会话删除时）。 */
-  deleteEventCounts(id: SessionId): Promise<void>;
+  /** 删掉一个会话的汇总行（会话删除时；外键 CASCADE 之外再显式清一次）。 */
+  deleteSessionStats(id: SessionId): Promise<void>;
 
   /** 回收空间与统计（含 VACUUM）；不得在事务内执行。 */
   vacuum(): Promise<void>;

package/src/branch.ts

@@ -311,8 +311,8 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       internals.dropReuseEventIds(childId);
       throw error;
     }
-    // 子会话继承了前缀事件：活动计数按子会话重算（派生表，best-effort）。
-    await this.persistence.rebuildEventCounts(childId);
+    // 子会话继承了前缀事件：统计按子会话重算（派生表，best-effort）。
+    await this.persistence.rebuildSessionStats(childId);
     return childId;
   }
 
@@ -443,8 +443,8 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       });
     }
 
-    // 截断后该会话的事件集合变了：活动计数跟着重算（派生表，best-effort）。
-    await this.persistence.rebuildEventCounts(id);
+    // 截断后该会话的事件集合变了：统计跟着重算（派生表，best-effort）。
+    await this.persistence.rebuildSessionStats(id);
 
     return { header: rowToMeta(row), revision: (await internals.readStoredRevision(id))! };
   }

package/src/drizzle/postgres-v3.ts

@@ -14,3 +14,5 @@ export const tWorkspaceSessions = tables["t_workspace_sessions"]!;
 export const tWorkspaceState = tables["t_workspace_state"]!;
 export const tSessionProjcacheRows = tables["t_session_projcache_row"]!;
 export const tEventUsage = tables["t_event_usage"]!;
+export const tSessionUsage = tables["t_session_usage"]!;
+export const tSessionCounts = tables["t_session_counts"]!;

package/src/drizzle/sqlite-v3.ts

@@ -14,3 +14,5 @@ export const tWorkspaceSessions = tables["t_workspace_sessions"]!;
 export const tWorkspaceState = tables["t_workspace_state"]!;
 export const tSessionProjcacheRows = tables["t_session_projcache_row"]!;
 export const tEventUsage = tables["t_event_usage"]!;
+export const tSessionUsage = tables["t_session_usage"]!;
+export const tSessionCounts = tables["t_session_counts"]!;

package/src/entities/v3/event-usage.ts

@@ -2,7 +2,9 @@ import type { TableDef } from "../../adapters/types.ts";
 
 /**
  * 用量日志：一条 `assistant/message` 事件一行（按事件行唯一，fork 共享行不重复）。
- * 统计只读这张表，不再逐行解析事件的 JSON；事件行本身仍留在 `t_events`。
+ * 读侧维度全部物化在行上——本地日、是否被会话引用、是否被子代理会话引用——统计因此不做
+ * `EXISTS` 判定、也不回连事件表；事件行本身仍留在 `t_events`。
+ * 取舍见 ADR-统计衍生表物化归属与汇总。
  */
 export const eventUsage: TableDef = {
   name: "t_event_usage",
@@ -14,8 +16,13 @@ export const eventUsage: TableDef = {
     },
     // 毫秒时间戳：SQLite 的 integer 是 64 位，PG 的 integer 只有 int4（21 亿上限）——必须是 bigint。
     f_created_at: { type: "bigint", notNull: true },
+    // host 本地日 `YYYY-MM-DD`（与统计桶的 localtime 口径一致）。
+    f_day: { type: "text", notNull: true },
     f_provider: { type: "text" },
     f_model: { type: "text" },
+    // 被任何会话桥接行引用（孤儿 0，不计入统计）/ 被任何 subagent 会话引用（拆「人类 / 子代理」）。
+    f_referenced: { type: "integer", notNull: true, default: 0 },
+    f_subagent: { type: "integer", notNull: true, default: 0 },
     f_input_tokens: { type: "integer", notNull: true, default: 0 },
     f_output_tokens: { type: "integer", notNull: true, default: 0 },
     f_cache_read_tokens: { type: "integer", notNull: true, default: 0 },

package/src/entities/v3/index.ts

@@ -9,6 +9,8 @@ import { workspaceSessions } from "./workspace-sessions.ts";
 import { workspaceState } from "./workspace-state.ts";
 import { sessionProjcacheRows } from "./session-projcache-rows.ts";
 import { eventUsage } from "./event-usage.ts";
+import { sessionUsage } from "./session-usage.ts";
+import { sessionCounts } from "./session-counts.ts";
 
 export { persistenceState };
 export { schemaMeta };
@@ -21,6 +23,8 @@ export { workspaceSessions };
 export { workspaceState };
 export { sessionProjcacheRows };
 export { eventUsage };
+export { sessionUsage };
+export { sessionCounts };
 
 export const sqliteTableDefs = [
   persistenceState,
@@ -34,6 +38,8 @@ export const sqliteTableDefs = [
   workspaceState,
   sessionProjcacheRows,
   eventUsage,
+  sessionUsage,
+  sessionCounts,
 ] as const;
 
 export const postgresTableDefs = [
@@ -48,4 +54,6 @@ export const postgresTableDefs = [
   workspaceState,
   sessionProjcacheRows,
   eventUsage,
+  sessionUsage,
+  sessionCounts,
 ] as const;

package/src/entities/v3/session-counts.ts

@@ -0,0 +1,23 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+/**
+ * 会话 × 本地日的活动计数（派生统计表）：轮次 / 步骤 / 用户输入 / 工具调用四列直接读，
+ * 不再存事件类型、也不在读取时折。旁路累加、可按会话重建，读侧只读；
+ * 取舍见 ADR-统计衍生表物化归属与汇总。
+ */
+export const sessionCounts: TableDef = {
+  name: "t_session_counts",
+  columns: {
+    f_session_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_sessions", column: "f_session_id", onDelete: "cascade" },
+    },
+    f_day: { type: "text", notNull: true },
+    f_turns: { type: "integer", notNull: true, default: 0 },
+    f_steps: { type: "integer", notNull: true, default: 0 },
+    f_user_inputs: { type: "integer", notNull: true, default: 0 },
+    f_tool_calls: { type: "integer", notNull: true, default: 0 },
+  },
+  uniques: { uq_session_counts_key: { columns: ["f_session_id", "f_day"] } },
+};

package/src/entities/v3/session-usage.ts

@@ -0,0 +1,29 @@
+import type { TableDef } from "../../adapters/types.ts";
+
+/**
+ * 会话 × 本地日 × 模型的 token 汇总（派生统计表）：**按会话的行**读它，因此保住
+ * 「fork 子会话含继承前缀」的口径（各会话行之和 ≥ 总量）而不回连事件表。
+ * 旁路累加、可按会话重建，读侧只读；取舍见 ADR-统计衍生表物化归属与汇总。
+ */
+export const sessionUsage: TableDef = {
+  name: "t_session_usage",
+  columns: {
+    f_session_id: {
+      type: "text",
+      notNull: true,
+      references: { table: "t_sessions", column: "f_session_id", onDelete: "cascade" },
+    },
+    f_day: { type: "text", notNull: true },
+    // 模型未知时落空串（不是 NULL）：唯一键里的 NULL 在 SQLite 下互不冲突，空串才保证一行。
+    f_provider: { type: "text", notNull: true, default: "" },
+    f_model: { type: "text", notNull: true, default: "" },
+    f_input_tokens: { type: "integer", notNull: true, default: 0 },
+    f_output_tokens: { type: "integer", notNull: true, default: 0 },
+    f_cache_read_tokens: { type: "integer", notNull: true, default: 0 },
+    f_reasoning_tokens: { type: "integer", notNull: true, default: 0 },
+    f_total_tokens: { type: "integer", notNull: true, default: 0 },
+  },
+  uniques: {
+    uq_session_usage_key: { columns: ["f_session_id", "f_day", "f_provider", "f_model"] },
+  },
+};