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

package/README.md

@@ -80,10 +80,10 @@ web 模式经 `POST /api/session.delete`（body `{ sessionId }`）暴露，状
 
 ## 会话列表（两条路）
 
-| 用途                  | 接缝                                                                                                            | 内容                                             |
-| --------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
-| 官方 UI（上游 `ui-*`）| `session/list` → `ctx.sessionQuery.listSessions`（本包接管，**默认排除已归档**）                                 | 未归档的可见语料，标题走投影（`projections.title`） |
-| 我们自己的管理面      | `POST /api/session.rows`（本包路由）                                                                            | **完整语料（含归档）** + 标题 + 最后活动时间 + 工作区归属，**搜索 / 子代理过滤 / 分页都在后端** |
+| 用途                   | 接缝                                                                             | 内容                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| 官方 UI（上游 `ui-*`） | `session/list` → `ctx.sessionQuery.listSessions`（本包接管，**默认排除已归档**） | 未归档的可见语料，标题走投影（`projections.title`）                                             |
+| 我们自己的管理面       | `POST /api/session.rows`（本包路由）                                             | **完整语料（含归档）** + 标题 + 最后活动时间 + 工作区归属，**搜索 / 子代理过滤 / 分页都在后端** |
 
 排除归档是本部署的策略：归档是「收起来」的会话，不该混进日常列表与搜索。管理动作（取消归档 / 删除 /
 导入）需要完整集合，所以另给一条自有路由，两条路不混。决策与取舍见
@@ -118,13 +118,20 @@ subagent 会话**（`origin = 'subagent'`、父不在表里；有 open handle /
 ## 用量统计
 
 `POST /api/session.usage` 一次回报三份数据：`totals`（含 `subagent` / `human` 拆分）、按
-天 × provider/model × subagent 的桶、按会话的行。
+天 × provider/model × subagent 的桶、按会话的行（活动计数：轮次 / 步骤 / 用户输入 / 工具调用）。
 
-用量写在**专用表 `t_event_usage`**（写路径顺带记录，一条 `assistant/message` 事件行一行），统计只读它，
-不再逐行解析事件 JSON——真实库实测 **1.6s → ~140ms**。老库在首次打开时**一次性回填**（表为空才跑，
-约 2.2s / 1.99 万行），两种 `f_data` 结构都认。口径不变：只算被会话引用的事件行（fork 共享行计一次、
-孤儿行不计），GC 顺带回收不再有事件行的用量行。口径与取舍见
-[ADR-用量统计走专用用量日志表](.agents/adrs/20260918-用量统计走专用用量日志表.md)。
+统计读侧只读三张**可销毁重建的派生表**，读侧维度（会话 / 模型 / 本地日 / 是否被引用 / 是否子代理）
+全部在写入时物化，查询不做 `EXISTS`、也不回连事件表：
+
+- `t_event_usage`——一条 `assistant/message` 事件行一行（去重口径的总量与「天 × 模型」桶读它）；
+- `t_session_usage`——会话 × 本地日 × 模型的 token 汇总（按会话的行读它，含 fork 继承前缀）；
+- `t_session_counts`——会话 × 本地日的四项活动计数。
+
+写入时在事务内落用量行、事务后**旁路累加**两张汇总表；rewind / fork / 删除会话之后按会话重算并全量重算
+引用标记；表为空（首次 / 迁移后 / 手动清空）在打开库时全量回填——迁移对这三张表先删后建。真实库实测
+单次统计从 **1.6s → ~140ms → ~30ms**（口径不变，旧口径逐项交叉核对一致），升级后首次打开付一次回填
+（2.4s / 3.09 万用量行，此后不再发生）。口径与取舍见
+[ADR-统计衍生表物化归属与汇总](.agents/adrs/20260923-统计衍生表物化归属与汇总.md)。
 
 ## 查询接管（`ctx.sessionQuery`）
 

package/dist/artifact.d.mts

@@ -1,102 +1,3 @@
-import { i as EventRow, s as SessionRow } from "./backend-E0bmTXpz.mjs";
+import { C as usageRowOf, S as toJsonlArtifact, _ as sealOwnEvents, a as normalizeToCurrentShape, b as syncMeteringRanges, c as renameLegacyPtcEvents, d as repairReadView, f as repairRequestHeaders, g as scanRows, h as rowToMeta, i as needsShapeAdoption, l as repairAssistantSettlement, m as rowToEvent, n as OWN_EVENT_TYPES, o as orphanInboxSpliceSeqs, p as repairSurfaceOps, r as findSurfaceRepairs, s as recomputeReplaceProvenance, t as EventUsageRow, u as repairOrphanInboxSplices, v as sessionConflictRow, x as titleOfEventData, y as sessionInsertRow } from "./log-BbleqD1M.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
-import { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
-import { SessionEvent, SessionHeader } from "@deepseek-ai/dsh-session";
-//#region src/log.d.ts
-declare function rowToMeta(row: SessionRow): SessionHeader;
-declare function sessionInsertRow(storage: SessionStorageMetadata, incarnation: string): {
-  fSessionId: string;
-  fHeadEventId: string;
-  fHeadSequence: number;
-  fVersion: number;
-  fCreatedAt: number;
-  fCwd: string | null;
-  fParentSession: string | null;
-  fSeedLength: number | null;
-  fOrigin: string | null;
-  fDelegationDepth: number | null;
-  fAgentPreset: string | null;
-  fIncarnation: string;
-  fRevision: number;
-};
-declare function sessionConflictRow(storage: SessionStorageMetadata): {
-  fVersion: number;
-  fCreatedAt: number;
-  fCwd: string | null;
-  fParentSession: string | null;
-  fSeedLength: number | null;
-  fOrigin: string | null;
-  fDelegationDepth: number | null;
-  fAgentPreset: string | null;
-};
-declare function rowToEvent(row: EventRow): SessionEvent;
-declare function recomputeReplaceProvenance(events: SessionEvent[]): void;
-declare function findSurfaceRepairs(events: readonly SessionEvent[]): {
-  degradeToAppend: Set<number>;
-  addAppendMarker: Set<number>;
-  clearSurfaceOp: Set<number>;
-  clampEnd: Map<number, number>;
-};
-declare function repairSurfaceOps(events: SessionEvent[]): void;
-declare function repairAssistantSettlement(events: SessionEvent[]): void;
-declare function repairRequestHeaders(events: SessionEvent[]): void;
-declare function syncMeteringRanges(events: SessionEvent[]): void;
-declare function renameLegacyPtcEvents(events: SessionEvent[]): void;
-/**
- * 把**旧代（v3 及更早）的消息形状**归一到当前格式（v4）：迁移链（严格）拒绝那些形状时，读路径仍要
- * 能把它们读出来——只动字段与标记，不改坐标、不改内容。
- *
- * 三件事：
- * - `system/message` 的 source：`{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }` → `{ kind: 'system-prompt' }`
- *   （v4 起 system 消息只认这个 kind）；
- * - `tool/result` 的消息：v3 是 user 角色、结果块包在 `content[0]`；v4 是 `role: 'tool'` + 顶层
- *   `toolCallId` + `content` 就是结果块；
- * - 本仓库自己写过、上游已删除的事件类型（见 `LEGACY_OWN_EVENT_TYPES`）标 `ignorable: true`——v4 的
- *   校验对未知类型只接受可忽略信封。
- *
- * 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
- */
-declare function normalizeToCurrentShape(events: SessionEvent[]): void;
-/**
- * 本仓库写过、后来连同机制一起删除的事件类型：读的时候标 `ignorable: true` 让校验跳过它们。
- * 新增历史类型时登记到这里——**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件）。
- */
-declare const LEGACY_OWN_EVENT_TYPES: ReadonlySet<string>;
-/** 行里是否还带着旧代消息形状（`session-branch/version` 这类自造事件也算）——写路径曾把回退视图的结果
- * 以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
-declare function hasLegacyShape(events: readonly SessionEvent[]): boolean;
-declare function repairReadView(events: SessionEvent[]): void;
-declare function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<number>;
-declare function repairOrphanInboxSplices(events: SessionEvent[]): void;
-declare function scanRows(rows: readonly EventRow[], base?: number): {
-  preserved: SessionEvent[];
-  tornFrom?: number;
-};
-declare function toJsonlArtifact(meta: SessionHeader, inheritedEventCount: number, events: readonly SessionEvent[]): string;
-declare function titleOfEventData(data: string): string | undefined;
-/** 用量行的列（`t_event_usage`）。 */
-interface EventUsageRow {
-  fEventId: string;
-  fCreatedAt: number;
-  fProvider: string | null;
-  fModel: string | null;
-  fInputTokens: number;
-  fOutputTokens: number;
-  fCacheReadTokens: number;
-  fReasoningTokens: number;
-  fTotalTokens: number;
-}
-/**
- * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
- * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
- * @param event - 待写入的事件行。
- * @returns 用量行，或该事件没有用量时的 undefined。
- */
-declare function usageRowOf(event: {
-  fEventId: string;
-  fCreatedAt: number;
-  fType: string;
-  fData: string;
-}): EventUsageRow | undefined;
-//#endregion
-export { EventUsageRow, LEGACY_OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, hasLegacyShape, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };
+export { EventUsageRow, OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, needsShapeAdoption, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sealOwnEvents, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };

package/dist/artifact.mjs

@@ -1,3 +1,3 @@
-import { _ as sessionInsertRow, a as orphanInboxSpliceSeqs, b as toJsonlArtifact, c as repairAssistantSettlement, d as repairRequestHeaders, f as repairSurfaceOps, g as sessionConflictRow, h as scanRows, i as normalizeToCurrentShape, l as repairOrphanInboxSplices, m as rowToMeta, n as findSurfaceRepairs, o as recomputeReplaceProvenance, p as rowToEvent, r as hasLegacyShape, s as renameLegacyPtcEvents, t as LEGACY_OWN_EVENT_TYPES, u as repairReadView, v as syncMeteringRanges, x as usageRowOf, y as titleOfEventData } from "./log-qCNkDjh5.mjs";
+import { S as usageRowOf, _ as sessionConflictRow, a as orphanInboxSpliceSeqs, b as titleOfEventData, c as repairAssistantSettlement, d as repairRequestHeaders, f as repairSurfaceOps, g as sealOwnEvents, h as scanRows, i as normalizeToCurrentShape, l as repairOrphanInboxSplices, m as rowToMeta, n as findSurfaceRepairs, o as recomputeReplaceProvenance, p as rowToEvent, r as needsShapeAdoption, s as renameLegacyPtcEvents, t as OWN_EVENT_TYPES, u as repairReadView, v as sessionInsertRow, x as toJsonlArtifact, y as syncMeteringRanges } from "./log-DTcvsMz7.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
-export { LEGACY_OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, hasLegacyShape, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };
+export { OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, needsShapeAdoption, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sealOwnEvents, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };

package/dist/{branch-BjUR6wfe.mjs → branch-7eOh_tbO.mjs}

@@ -1,4 +1,4 @@
-import { d as repairRequestHeaders, h as scanRows, i as normalizeToCurrentShape, m as rowToMeta } from "./log-qCNkDjh5.mjs";
+import { d as repairRequestHeaders, h as scanRows, i as normalizeToCurrentShape, m as rowToMeta } from "./log-DTcvsMz7.mjs";
 import { randomUUID } from "node:crypto";
 import { SESSION_FORMAT_VERSION, SessionLogOffset } from "@deepseek-ai/dsh-session";
 import { createSessionFormatCatalogWithChildren } from "@deepseek-ai/dsh-session-format-catalog";
@@ -217,7 +217,7 @@ var SessionBranchRdbProvider = class {
 			internals.dropReuseEventIds(childId);
 			throw error;
 		}
-		await this.persistence.rebuildEventCounts(childId);
+		await this.persistence.rebuildSessionStats(childId);
 		return childId;
 	}
 	async rewind(id, toBoundary, signal) {
@@ -290,7 +290,7 @@ var SessionBranchRdbProvider = class {
 			headSeq: keepLength - 1,
 			snapshotEvents: () => []
 		});
-		await this.persistence.rebuildEventCounts(id);
+		await this.persistence.rebuildSessionStats(id);
 		return {
 			header: rowToMeta(row),
 			revision: await internals.readStoredRevision(id)

package/dist/deletion.d.mts

@@ -1,4 +1,4 @@
-import { p as SessionPersistenceRdb } from "./backend-E0bmTXpz.mjs";
+import { L as SessionPersistenceRdb } from "./log-BbleqD1M.mjs";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/deletion.d.ts
 declare const SESSION_DELETE_PATH = "/api/session.delete";

package/dist/deletion.mjs

@@ -1,2 +1,2 @@
-import { a as registerSessionDeletion, i as SESSION_DELETE_PATH } from "./src-B9X8BKyh.mjs";
+import { a as registerSessionDeletion, i as SESSION_DELETE_PATH } from "./src-BWqePRA7.mjs";
 export { SESSION_DELETE_PATH, registerSessionDeletion };

package/dist/import.d.mts

@@ -1,4 +1,4 @@
-import { p as SessionPersistenceRdb } from "./backend-E0bmTXpz.mjs";
+import { L as SessionPersistenceRdb } from "./log-BbleqD1M.mjs";
 import { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
 import { Session, SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
 import { Context } from "@deepseek-ai/cordis";

package/dist/import.mjs

@@ -1,4 +1,4 @@
-import { i as replaceLiveSessionLog, l as restoreCatalog } from "./branch-BjUR6wfe.mjs";
+import { i as replaceLiveSessionLog, l as restoreCatalog } from "./branch-7eOh_tbO.mjs";
 import { randomUUID } from "node:crypto";
 import { SESSION_FORMAT_VERSION, SessionLogOffset } from "@deepseek-ai/dsh-session";
 import { parseSessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";

package/dist/index.d.mts

@@ -1,2 +1,2 @@
-import { D as SCHEMA_VERSION, _ as locateTurnEnd, b as SessionRowsItem, d as SessionDeletionError, f as SessionDeletionErrorCode, g as SessionBranchRdbProvider, h as SessionBranchRdb, l as Config, m as SessionPersistenceRdbInternals, p as SessionPersistenceRdb, u as ProjectionCacheOptions, x as SessionRowsValue, y as SESSION_ROWS_PATH } from "./backend-E0bmTXpz.mjs";
+import { B as SessionBranchRdbProvider, F as SessionDeletionError, G as SessionRowsValue, I as SessionDeletionErrorCode, L as SessionPersistenceRdb, N as Config, P as ProjectionCacheOptions, R as SessionPersistenceRdbInternals, U as SESSION_ROWS_PATH, V as locateTurnEnd, W as SessionRowsItem, Z as SCHEMA_VERSION, z as SessionBranchRdb } from "./log-BbleqD1M.mjs";
 export { Config, ProjectionCacheOptions, SCHEMA_VERSION, SESSION_ROWS_PATH, SessionBranchRdb, SessionBranchRdbProvider, SessionDeletionError, SessionDeletionErrorCode, SessionPersistenceRdb, SessionPersistenceRdb as default, SessionPersistenceRdbInternals, type SessionRowsItem, type SessionRowsValue, locateTurnEnd };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { p as SCHEMA_VERSION } from "./sqlite-zcXVyMxr.mjs";
-import { n as SessionPersistenceRdb, r as SESSION_ROWS_PATH, t as SessionDeletionError } from "./src-B9X8BKyh.mjs";
-import { n as SessionBranchRdbProvider, r as locateTurnEnd, t as SessionBranchRdb } from "./branch-BjUR6wfe.mjs";
+import { o as SCHEMA_VERSION } from "./sqlite-ChM_sHAG.mjs";
+import { n as SessionPersistenceRdb, r as SESSION_ROWS_PATH, t as SessionDeletionError } from "./src-BWqePRA7.mjs";
+import { n as SessionBranchRdbProvider, r as locateTurnEnd, t as SessionBranchRdb } from "./branch-7eOh_tbO.mjs";
 export { SCHEMA_VERSION, SESSION_ROWS_PATH, SessionBranchRdb, SessionBranchRdbProvider, SessionDeletionError, SessionPersistenceRdb, SessionPersistenceRdb as default, locateTurnEnd };

package/dist/{backend-E0bmTXpz.d.mts → log-BbleqD1M.d.mts}

@@ -3478,6 +3478,8 @@ declare const tWorkspaceSessions: any;
 declare const tWorkspaceState: any;
 declare const tSessionProjcacheRows: any;
 declare const tEventUsage: any;
+declare const tSessionUsage: any;
+declare const tSessionCounts: any;
 type JournalMode = "wal" | "delete" | "truncate" | "persist";
 declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
 type EventKind = "message" | "thinking" | "turn" | "tool" | "request" | "config" | "audit" | "lifecycle" | "inbox" | "compaction" | "llm" | "subagent" | "team" | "workflow" | "goal" | "schedule" | "todo" | "web";
@@ -3740,14 +3742,18 @@ declare class SessionPersistenceRdb extends SessionPersistence {
     migrated: boolean;
   } | undefined>;
   /**
-   * 活动计数**旁路累加**：不在写事务里、失败只 warn——`t_event_counts` 是可销毁重建的派生表，
-   * 丢几次累加不影响可用性（需要时用 `rebuildEventCounts` 重算）。
+   * 统计衍生表的**旁路累加**：不在写事务里、失败只 warn——两张会话汇总表都是可销毁重建的
+   * 派生表，丢几次累加不影响可用性（需要时用 `rebuildSessionStats` 重算）。
+   * token 走写路径已折好的用量行，活动计数走本批事件类型。
    */
-  private recordEventCounts;
-  /** 重算一个会话的活动计数（rewind / fork 之后；best-effort，同 `recordEventCounts`）。 */
-  rebuildEventCounts(id: SessionId): Promise<void>;
-  /** 会话删除时清掉它的活动计数行（best-effort）。 */
-  private deleteEventCounts;
+  private recordSessionStats;
+  /**
+   * 重算一个会话的统计（rewind / fork 之后；best-effort，同 `recordSessionStats`）：
+   * 两张汇总表按会话重算，用量行的引用标记全量重算（引用可能跨会话消失）。
+   */
+  rebuildSessionStats(id: SessionId): Promise<void>;
+  /** 会话删除时清掉它的汇总行，并重算用量行的引用标记（被删会话引用的行要立刻退出统计）。 */
+  private dropSessionStats;
   private rewriteMigratedLog;
   listSnapshots(signal?: AbortSignal): Promise<Array<SessionPersistenceSnapshot & {
     inheritedEventCount: number;
@@ -3870,7 +3876,11 @@ interface BackendTx {
   getSeedLength(id: SessionId): Promise<number | null>;
   updateSeedLength(id: SessionId, seedLength: number): Promise<void>;
   refreshTitle(id: SessionId): Promise<void>;
-  insertEvents(events: EventInsert[]): Promise<void>;
+  /**
+   * 插入事件行与它们的用量行（`usageRows` 由写路径一次折好，读侧维度已物化在行上）。
+   * 这一批事件与桥接行同事务，提交即「被引用」。
+   */
+  insertEvents(events: EventInsert[], usageRows: readonly EventUsageRow[]): Promise<void>;
   insertBridges(rows: Array<{
     fSessionId: SessionId;
     fEventId: string;
@@ -3922,11 +3932,15 @@ interface SessionListRowsPage {
   /** 过滤后的总数（分页前的），前端据此算页数。 */
   total: number;
 }
-/** 活动计数的一个桶：本地日 + 事件类型 + 计数。 */
-interface EventCountBucket {
+/** 活动计数的一个桶：本地日 + 四项计数（轮次 / 步骤 / 用户输入 / 工具调用）。 */
+interface SessionCountBucket extends UsageActivityTotals {
   day: string;
-  type: string;
-  count: number;
+}
+/** 用量累加的一个桶：本地日 + 模型归属 + 五个 token 列。 */
+interface SessionUsageBucket extends UsageTokenTotals {
+  day: string;
+  provider: string | null;
+  model: string | null;
 }
 interface Backend {
   readonly kind: "sqlite" | "postgres";
@@ -3944,30 +3958,163 @@ interface Backend {
   /** 父会话已不存在（或没有父）的 subagent 会话：父被删后它们成了孤儿。 */
   listOrphanSubagentSessions(): Promise<SessionId[]>;
   /**
-   * 用量统计的原始聚合：token 用量读 `t_event_usage`、活动计数读派生表 `t_event_counts`，
-   * 加按天×模型的桶与按会话的行（事件行去重、排除孤儿）。
-   * @param sinceMs - 只算该时刻（含）之后的事件行；省略即全量。
+   * 用量统计的原始聚合：读三张派生统计表（`t_event_usage` + 两张会话汇总表），
+   * 给出总量 / subagent 拆分、按天×模型的桶与按会话的行（事件行去重、排除孤儿）。
+   * @param sinceMs - 只算该时刻（含）之后的用量；省略即全量。会话汇总表按本地日过滤，
+   * 与毫秒过滤等价的前提是调用方把起点对齐到本地零点（见 `resolveUsageSince`）。
    */
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
   /** 管理面的会话行列表：完整语料（含归档）+ 标题 + 最后活动时间，按活动倒序分页。 */
   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>;
-  /** 删掉一个会话的活动计数行（会话删除时）。 */
-  deleteEventCounts(id: SessionId): Promise<void>;
+  rebuildSessionStats(id: SessionId): Promise<void>;
+  /**
+   * 全量重算 `t_event_usage` 的引用标记（`f_referenced` / `f_subagent`）：rewind / fork / 会话删除之后调用。
+   * 引用可能跨会话消失（截断、删除），只按本会话判定不够，故这里是全量。
+   */
+  refreshEventUsageFlags(): Promise<void>;
+  /** 删掉一个会话的汇总行（会话删除时；外键 CASCADE 之外再显式清一次）。 */
+  deleteSessionStats(id: SessionId): Promise<void>;
   /** 回收空间与统计（含 VACUUM）；不得在事务内执行。 */
   vacuum(): Promise<void>;
   close(): Promise<void>;
 }
 //#endregion
-export { eventKind as A, tWorkspaceState as B, EVENT_ENCODING as C, SCHEMA_VERSION as D, JournalMode as E, tSessionEvents as F, WriteGuard as H, tSessionProjcacheRows as I, tSessions as L, tEvents as M, tPersistenceState as N, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID as O, tSchemaMeta as P, tStorageUnits as R, DEFAULT_BUSY_TIMEOUT_MS as S, EventRole as T, StorageRepository as U, tWorkspaces as V, locateTurnEnd as _, SessionListRowsPage as a, SessionRowsItem as b, UsageAggregate as c, SessionDeletionError as d, SessionDeletionErrorCode as f, SessionBranchRdbProvider as g, SessionBranchRdb as h, EventRow as i, tEventUsage as j, eventDimensions as k, Config$1 as l, SessionPersistenceRdbInternals as m, BackendTx as n, SessionListRowsQuery as o, SessionPersistenceRdb as p, EventCountBucket as r, SessionRow as s, Backend as t, ProjectionCacheOptions as u, truncateLiveSession as v, EventKind as w, SessionRowsValue as x, SESSION_ROWS_PATH as y, tWorkspaceSessions as z };
+//#region src/log.d.ts
+declare function rowToMeta(row: SessionRow): SessionHeader;
+declare function sessionInsertRow(storage: SessionStorageMetadata, incarnation: string): {
+  fSessionId: string;
+  fHeadEventId: string;
+  fHeadSequence: number;
+  fVersion: number;
+  fCreatedAt: number;
+  fCwd: string | null;
+  fParentSession: string | null;
+  fSeedLength: number | null;
+  fOrigin: string | null;
+  fDelegationDepth: number | null;
+  fAgentPreset: string | null;
+  fIncarnation: string;
+  fRevision: number;
+};
+declare function sessionConflictRow(storage: SessionStorageMetadata): {
+  fVersion: number;
+  fCreatedAt: number;
+  fCwd: string | null;
+  fParentSession: string | null;
+  fSeedLength: number | null;
+  fOrigin: string | null;
+  fDelegationDepth: number | null;
+  fAgentPreset: string | null;
+};
+declare function rowToEvent(row: EventRow): SessionEvent;
+declare function recomputeReplaceProvenance(events: SessionEvent[]): void;
+declare function findSurfaceRepairs(events: readonly SessionEvent[]): {
+  degradeToAppend: Set<number>;
+  addAppendMarker: Set<number>;
+  clearSurfaceOp: Set<number>;
+  clampEnd: Map<number, number>;
+};
+declare function repairSurfaceOps(events: SessionEvent[]): void;
+declare function repairAssistantSettlement(events: SessionEvent[]): void;
+declare function repairRequestHeaders(events: SessionEvent[]): void;
+declare function syncMeteringRanges(events: SessionEvent[]): void;
+declare function renameLegacyPtcEvents(events: SessionEvent[]): void;
+/**
+ * 把**旧代（v3 及更早）的消息形状**归一到当前格式（v4）：迁移链（严格）拒绝那些形状时，读路径仍要
+ * 能把它们读出来——只动字段与标记，不改坐标、不改内容。
+ *
+ * 三件事：
+ * - `system/message` 的 source：`{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }` → `{ kind: 'system-prompt' }`
+ *   （v4 起 system 消息只认这个 kind）；
+ * - `tool/result` 的消息：v3 是 user 角色、结果块包在 `content[0]`；v4 是 `role: 'tool'` + 顶层
+ *   `toolCallId` + `content` 就是结果块；
+ * - **本仓库自造、上游不认识的事件类型**（见 `OWN_EVENT_TYPES`：历史遗留的与我们当前在写的）标
+ *   `ignorable: true`——v4 的校验对未知类型只接受可忽略信封。
+ *
+ * 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
+ */
+declare function normalizeToCurrentShape(events: SessionEvent[]): void;
+/**
+ * 落库前给**本仓库自造的事件类型**补上 `ignorable: true` 信封。
+ *
+ * 上游的持久化校验（`validateStoredEvents`）只放行「已知类型」或「带可忽略信封的未知类型」，我们的类型
+ * 按构造就在已知表之外——不补的话连**写入**都会被拒（`appendBatch` 里那道校验）。上游 `Session.append`
+ * 没有承载这个信封的口子（第三个参数只服务 surface 事件），所以这一笔由持久化层补：canonical log 里的
+ * 形状不变，落库的那一份带上信封。
+ * @param events - 即将落库的批次（`materializeAppendBatch` 的 JSON 快照副本，可写）。
+ */
+declare function sealOwnEvents(events: readonly SessionEvent[]): void;
+/**
+ * 本仓库自造、上游不认识的事件类型：读的时候标 `ignorable: true`，v4 的持久化校验才肯跳过它们
+ * （`validateStoredEvents` 只放行「已知类型」或「带可忽略信封的未知类型」）。
+ *
+ * 两类都在这张表里：
+ * - **历史遗留**：写过、后来连同机制一起删除的（`session-branch/version`）；
+ * - **当前在写**：本仓库的插件自己声明的事件类型（`session-mode/selected`）——上游的
+ *   `KNOWN_SESSION_EVENT_TYPES` 由上游仓库的声明生成，外部插件的事件按构造就在它之外。
+ *
+ * 新增自造事件类型时**必须**登记到这里，否则读路径 fail loud（真回归：`session-mode/selected` 漏登记，
+ * 会话打不开）。**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件——那种必须拒读）。
+ */
+declare const OWN_EVENT_TYPES: ReadonlySet<string>;
+/** 这批事件是否需要按当前形状归一（旧代消息形状，或尚未标 `ignorable` 的自造事件类型）——写路径曾把回退
+ * 视图的结果以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
+declare function needsShapeAdoption(events: readonly SessionEvent[]): boolean;
+declare function repairReadView(events: SessionEvent[]): void;
+declare function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<number>;
+declare function repairOrphanInboxSplices(events: SessionEvent[]): void;
+declare function scanRows(rows: readonly EventRow[], base?: number): {
+  preserved: SessionEvent[];
+  tornFrom?: number;
+};
+declare function toJsonlArtifact(meta: SessionHeader, inheritedEventCount: number, events: readonly SessionEvent[]): string;
+declare function titleOfEventData(data: string): string | undefined;
+/** 用量行的列（`t_event_usage`）：读侧维度（本地日与两个归属标记）在写入时一起物化。 */
+interface EventUsageRow {
+  fEventId: string;
+  fCreatedAt: number;
+  fDay: string;
+  fProvider: string | null;
+  fModel: string | null;
+  fReferenced: number;
+  fSubagent: number;
+  fInputTokens: number;
+  fOutputTokens: number;
+  fCacheReadTokens: number;
+  fReasoningTokens: number;
+  fTotalTokens: number;
+}
+/**
+ * 一条事件行的用量（只有带 `usage` 的 `assistant/message` 才有）：写路径据此记录
+ * `t_event_usage`，统计因此不必逐行解析 JSON。两种 `f_data` 结构（带信封 / 老格式）都认。
+ * 读侧维度一起物化：本地日由事件时间算，`f_referenced` 直接 1（这一批事件行与桥接行同事务，
+ * 提交即被引用），`f_subagent` 取写入它的会话是否子代理。
+ * @param event - 待写入的事件行。
+ * @param subagent - 写入它的会话是否 `origin === 'subagent'`。
+ * @returns 用量行，或该事件没有用量时的 undefined。
+ */
+declare function usageRowOf(event: {
+  fEventId: string;
+  fCreatedAt: number;
+  fType: string;
+  fData: string;
+}, subagent: boolean): EventUsageRow | undefined;
+//#endregion
+export { eventDimensions as $, SessionRow as A, SessionBranchRdbProvider as B, usageRowOf as C, SessionCountBucket as D, EventRow as E, SessionDeletionError as F, SessionRowsValue as G, truncateLiveSession as H, SessionDeletionErrorCode as I, EventKind as J, DEFAULT_BUSY_TIMEOUT_MS as K, SessionPersistenceRdb as L, UsageAggregate as M, Config$1 as N, SessionListRowsPage as O, ProjectionCacheOptions as P, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID as Q, SessionPersistenceRdbInternals as R, toJsonlArtifact as S, BackendTx as T, SESSION_ROWS_PATH as U, locateTurnEnd as V, SessionRowsItem as W, JournalMode as X, EventRole as Y, SCHEMA_VERSION as Z, sealOwnEvents as _, normalizeToCurrentShape as a, tSessionCounts as at, syncMeteringRanges as b, renameLegacyPtcEvents as c, tSessionUsage as ct, repairReadView as d, tWorkspaceSessions as dt, eventKind as et, repairRequestHeaders as f, tWorkspaceState as ft, scanRows as g, rowToMeta as h, StorageRepository as ht, needsShapeAdoption as i, tSchemaMeta as it, SessionUsageBucket as j, SessionListRowsQuery as k, repairAssistantSettlement as l, tSessions as lt, rowToEvent as m, WriteGuard as mt, OWN_EVENT_TYPES as n, tEvents as nt, orphanInboxSpliceSeqs as o, tSessionEvents as ot, repairSurfaceOps as p, tWorkspaces as pt, EVENT_ENCODING as q, findSurfaceRepairs as r, tPersistenceState as rt, recomputeReplaceProvenance as s, tSessionProjcacheRows as st, EventUsageRow as t, tEventUsage as tt, repairOrphanInboxSplices as u, tStorageUnits as ut, sessionConflictRow as v, Backend as w, titleOfEventData as x, sessionInsertRow as y, SessionBranchRdb as z };