@morlay/session-rdb 0.1.0 → 0.1.2

package/src/backend.ts

@@ -75,10 +75,8 @@ export interface BackendTx {
 
   refreshTitle(id: SessionId): Promise<void>;
 
-  /**
-   * 插入事件行与它们的用量行（`usageRows` 由写路径一次折好，读侧维度已物化在行上）。
-   * 这一批事件与桥接行同事务，提交即「被引用」。
-   */
+  // 插入事件行与它们的用量行（`usageRows` 由写路径一次折好，读侧维度已物化在行上）。
+  // 这一批事件与桥接行同事务，提交即「被引用」。
   insertEvents(events: EventInsert[], usageRows: readonly EventUsageRow[]): Promise<void>;
 
   insertBridges(
@@ -92,47 +90,45 @@ export interface BackendTx {
 
   updateHead(id: SessionId, headEventId: string, headSequence: number): Promise<void>;
 
-  /** 写批次提交时递增 revision；给了 `lastEventAt` 就一并把「最后活动时间」往前推（只增不减）。 */
+  // 写批次提交时递增 revision；给了 `lastEventAt` 就一并把「最后活动时间」往前推（只增不减）。
   bumpRevision(id: SessionId, lastEventAt?: number): Promise<void>;
 
-  deleteBridgeTail(id: SessionId, fromSequence: number): Promise<void>;
+  // 删掉 fromSequence 起的桥接行，返回被删行引用的 event id（调用方据此重算这些用量行的引用标记）。
+  deleteBridgeTail(id: SessionId, fromSequence: number): Promise<readonly string[]>;
 
   getPrevBridge(
     id: SessionId,
     sequence: number,
   ): Promise<{ fEventId: string; fSequence: number } | undefined>;
 
-  deleteSession(id: SessionId): Promise<void>;
+  // 删除整条会话；返回被删桥接行引用的 event id（引用标记要跟着重算）。
+  deleteSession(id: SessionId): Promise<readonly string[]>;
 
-  /** 批量删除整条会话：桥接行、workspace 归属行、投影行与会话行。 */
-  deleteSessions(ids: SessionId[]): Promise<number>;
+  // 批量删除整条会话：桥接行、workspace 归属行、投影行与会话行；返回删除行数与被删桥接行引用的 event id。
+  deleteSessions(ids: SessionId[]): Promise<{ deleted: number; eventIds: readonly string[] }>;
 }
 
-/**
- * 「会话行」列表项：管理面自己的列表用（完整语料，含归档）+ 标题 + 最后活动时间。
- *
- * 与官方列表（`session/list` → `ctx.sessionQuery.listSessions`）的区别：那条按部署策略**默认排除归档**，
- * 这里给的是完整集合，标题也直接带出来（官方那条的标题走投影缓存）。
- */
+// 「会话行」列表项：管理面自己的列表（完整语料含归档 + 标题 + 最后活动时间）；为何与官方 `session/list`
+// 分开见 ADR-会话列表两条路。
 export interface SessionListRowRecord {
   sessionId: string;
   title: string | null;
   origin: string | null;
   cwd: string | null;
   createdAt: number;
-  /** 该会话最后一个事件的时间（没有事件时回落 `createdAt`）。 */
+  // 该会话最后一个事件的时间（没有事件时回落 `createdAt`）。
   updatedAt: number;
   archived: boolean;
   subagent: boolean;
-  /** 所属工作区标题；不属于任何工作区时为 null。 */
+  // 所属工作区标题；不属于任何工作区时为 null。
   workspace: string | null;
 }
 
-/** 会话行列表的查询条件：搜索、子代理过滤与分页都在后端做（前端分页等于每次拉全量）。 */
+// 会话行列表的查询条件：搜索、子代理过滤与分页都在后端做（前端分页等于每次拉全量）。
 export interface SessionListRowsQuery {
-  /** 匹配标题或所属工作区标题（大小写不敏感）；空串即不过滤。 */
+  // 匹配标题或所属工作区标题（大小写不敏感）；空串即不过滤。
   query?: string;
-  /** 是否连子代理派生会话一起返回（默认不含）。 */
+  // 是否连子代理派生会话一起返回（默认不含）。
   includeSubagents?: boolean;
   limit?: number;
   offset?: number;
@@ -140,16 +136,16 @@ export interface SessionListRowsQuery {
 
 export interface SessionListRowsPage {
   items: SessionListRowRecord[];
-  /** 过滤后的总数（分页前的），前端据此算页数。 */
+  // 过滤后的总数（分页前的），前端据此算页数。
   total: number;
 }
 
-/** 活动计数的一个桶：本地日 + 四项计数（轮次 / 步骤 / 用户输入 / 工具调用）。 */
+// 活动计数的一个桶：本地日 + 四项计数（轮次 / 步骤 / 用户输入 / 工具调用）。
 export interface SessionCountBucket extends UsageActivityTotals {
   day: string;
 }
 
-/** 用量累加的一个桶：本地日 + 模型归属 + 五个 token 列。 */
+// 用量累加的一个桶：本地日 + 模型归属 + 五个 token 列。
 export interface SessionUsageBucket extends UsageTokenTotals {
   day: string;
   provider: string | null;
@@ -181,54 +177,39 @@ export interface Backend {
 
   transaction<T>(fn: (tx: BackendTx) => Promise<T>): Promise<T>;
 
-  /** 删除已无桥接行引用的事件行（孤儿），返回删除行数。 */
+  // 删除已无桥接行引用的事件行（孤儿），返回删除行数。
   collectOrphans(): Promise<number>;
 
-  /** 父会话已不存在（或没有父）的 subagent 会话：父被删后它们成了孤儿。 */
+  // 父会话已不存在（或没有父）的 subagent 会话：父被删后它们成了孤儿。
   listOrphanSubagentSessions(): Promise<SessionId[]>;
 
-  /**
-   * 用量统计的原始聚合：读三张派生统计表（`t_event_usage` + 两张会话汇总表），
-   * 给出总量 / subagent 拆分、按天×模型的桶与按会话的行（事件行去重、排除孤儿）。
-   * @param sinceMs - 只算该时刻（含）之后的用量；省略即全量。会话汇总表按本地日过滤，
-   * 与毫秒过滤等价的前提是调用方把起点对齐到本地零点（见 `resolveUsageSince`）。
-   */
+  // 用量统计的原始聚合：读三张派生统计表（`t_event_usage` + 两张会话汇总表），给出总量 / subagent 拆分、
+  // 按天×模型的桶与按会话的行（事件行去重、排除孤儿）；`sinceMs` 起算（省略即全量），起点须对齐本地零点。
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
 
-  /** 管理面的会话行列表：完整语料（含归档）+ 标题 + 最后活动时间，按活动倒序分页。 */
+  // 管理面的会话行列表：完整语料（含归档）+ 标题 + 最后活动时间，按活动倒序分页。
   listSessionRows(query?: SessionListRowsQuery): Promise<SessionListRowsPage>;
 
-  /**
-   * token 用量**旁路累加**（派生表 `t_session_usage`，不参与写事务、失败可丢——表可销毁重建）：
-   * 每个 (会话, 本地日, 模型) 记一行累加。
-   * @param id - 会话 id。
-   * @param buckets - 本批要累加的 (day, provider, model, tokens)。
-   */
+  // token 用量**旁路累加**（派生表 `t_session_usage`，不参与写事务、失败可丢——表可销毁重建）：每个
+  // (会话, 本地日, 模型) 记一行；`buckets` 是本批要累加的 (day, provider, model, tokens)。
   incrementSessionUsage(id: SessionId, buckets: readonly SessionUsageBucket[]): Promise<void>;
 
-  /**
-   * 活动计数**旁路累加**（派生表 `t_session_counts`，同上）：每个 (会话, 本地日) 累加四项计数。
-   * @param id - 会话 id。
-   * @param buckets - 本批要累加的 (day, turns, steps, userInputs, toolCalls)。
-   */
+  // 活动计数**旁路累加**（派生表 `t_session_counts`，同上）：每个 (会话, 本地日) 累加四项计数，
+  // `buckets` 是本批要累加的 (day, turns, steps, userInputs, toolCalls)。
   incrementSessionCounts(id: SessionId, buckets: readonly SessionCountBucket[]): Promise<void>;
 
-  /**
-   * 按会话从事件表重算两张会话汇总表（rewind / fork 之后调用）：先删该会话的行再重算。
-   * @param id - 会话 id。
-   */
+  // 按会话从事件表重算两张汇总表（旧日志重写之后调用：迁移进来的会话没有旁路累加的历史，得补算）。
   rebuildSessionStats(id: SessionId): Promise<void>;
 
-  /**
-   * 全量重算 `t_event_usage` 的引用标记（`f_referenced` / `f_subagent`）：rewind / fork / 会话删除之后调用。
-   * 引用可能跨会话消失（截断、删除），只按本会话判定不够，故这里是全量。
-   */
-  refreshEventUsageFlags(): Promise<void>;
+  // 重算这些用量行的引用标记（`f_referenced` / `f_subagent`）：会话删除 / 日志重写之后调用，
+  // `eventIds` 是被删掉的那批桥接行引用的事件（只有它们的引用可能消失）。
+  // fork 与撤回（rewind）都**不**走这里——它们不改变已发生过的消耗（见 ADR-fork不继承统计、ADR-撤回不回退统计）。
+  refreshEventUsageFlags(eventIds: readonly string[]): Promise<void>;
 
-  /** 删掉一个会话的汇总行（会话删除时；外键 CASCADE 之外再显式清一次）。 */
+  // 删掉一个会话的汇总行（会话删除时；外键 CASCADE 之外再显式清一次）。
   deleteSessionStats(id: SessionId): Promise<void>;
 
-  /** 回收空间与统计（含 VACUUM）；不得在事务内执行。 */
+  // 回收空间与统计（含 VACUUM）；不得在事务内执行。
   vacuum(): Promise<void>;
 
   close(): 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.rebuildSessionStats(childId);
+    // fork 不动统计：继承前缀的消耗是父会话真实发生的那一次，子会话只记自己新产生的
+    // （写路径旁路累加，见 ADR-统计只记真实发生的用量）。
     return childId;
   }
 
@@ -443,9 +443,7 @@ export class SessionBranchRdbProvider implements SessionBranchProvider {
       });
     }
 
-    // 截断后该会话的事件集合变了：统计跟着重算（派生表，best-effort）。
-    await this.persistence.rebuildSessionStats(id);
-
+    // 撤回不改统计：请求已发起就已经消耗过（见 ADR-撤回不回退统计）。
     return { header: rowToMeta(row), revision: (await internals.readStoredRevision(id))! };
   }
 

package/src/deletion.ts

@@ -1,8 +1,9 @@
 import type { Context } from "@deepseek-ai/cordis";
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import { SessionDeletionError, type SessionPersistenceRdb } from "./index.ts";
+import { SESSION_DELETE_PATH } from "./routes.ts";
 
-export const SESSION_DELETE_PATH = "/api/session.delete";
+export { SESSION_DELETE_PATH };
 
 const STATUS_OF_DELETION_ERROR: Record<SessionDeletionError["code"], number> = {
   SESSION_NOT_FOUND: 404,

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

@@ -1,11 +1,8 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * 用量日志：一条 `assistant/message` 事件一行（按事件行唯一，fork 共享行不重复）。
- * 读侧维度全部物化在行上——本地日、是否被会话引用、是否被子代理会话引用——统计因此不做
- * `EXISTS` 判定、也不回连事件表；事件行本身仍留在 `t_events`。
- * 取舍见 ADR-统计衍生表物化归属与汇总。
- */
+// 用量日志：一条 `assistant/message` 事件一行（按事件行唯一，fork 共享行不重复）；读侧维度全部物化在行上
+// （本地日、是否被会话引用、是否被子代理会话引用），统计因此不做 `EXISTS` 判定、也不回连事件表。
+// 取舍见 ADR-统计衍生表物化归属与汇总。
 export const eventUsage: TableDef = {
   name: "t_event_usage",
   columns: {

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

@@ -1,10 +1,8 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * 会话 × 本地日的活动计数（派生统计表）：轮次 / 步骤 / 用户输入 / 工具调用四列直接读，
- * 不再存事件类型、也不在读取时折。旁路累加、可按会话重建，读侧只读；
- * 取舍见 ADR-统计衍生表物化归属与汇总。
- */
+// 会话 × 本地日的活动计数（派生统计表）：轮次 / 步骤 / 用户输入 / 工具调用四列直接读，
+// 不再存事件类型、也不在读取时折。旁路累加、可按会话重建，读侧只读；
+// 取舍见 ADR-统计衍生表物化归属与汇总。
 export const sessionCounts: TableDef = {
   name: "t_session_counts",
   columns: {

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

@@ -1,10 +1,8 @@
 import type { TableDef } from "../../adapters/types.ts";
 
-/**
- * 会话 × 本地日 × 模型的 token 汇总（派生统计表）：**按会话的行**读它，因此保住
- * 「fork 子会话含继承前缀」的口径（各会话行之和 ≥ 总量）而不回连事件表。
- * 旁路累加、可按会话重建，读侧只读；取舍见 ADR-统计衍生表物化归属与汇总。
- */
+// 会话 × 本地日 × 模型的 token 汇总（派生统计表）：**按会话的行**读它，因此保住
+// 「fork 子会话含继承前缀」的口径（各会话行之和 ≥ 总量）而不回连事件表。
+// 旁路累加、可按会话重建，读侧只读；取舍见 ADR-统计衍生表物化归属与汇总。
 export const sessionUsage: TableDef = {
   name: "t_session_usage",
   columns: {

package/src/export.ts

@@ -2,15 +2,16 @@ import { strToU8, zip } from "fflate";
 import type { Context } from "@deepseek-ai/cordis";
 import type { SessionId } from "@deepseek-ai/dsh-session";
 import type { SessionPersistenceRdb } from "./index.ts";
+import { SESSION_EXPORT_PATH } from "./routes.ts";
 
-export const SESSION_EXPORT_PATH = "/api/session.export";
+export { SESSION_EXPORT_PATH };
 
-/** 文件名只保留安全字符：会话 id 来自请求体，会写进 Content-Disposition。 */
+// 文件名只保留安全字符：会话 id 来自请求体，会写进 Content-Disposition。
 function safeFilename(sessionId: string): string {
   return sessionId.replace(/[^A-Za-z0-9._-]/gu, "_");
 }
 
-/** fflate 只给回调式异步 API（同步变体被 node/no-sync 禁止）。 */
+// fflate 只给回调式异步 API（同步变体被 node/no-sync 禁止）。
 function zipBytes(files: Record<string, Uint8Array>): Promise<Uint8Array> {
   return new Promise((resolve, reject) => {
     zip(files, (error, data) => {
@@ -20,7 +21,7 @@ function zipBytes(files: Record<string, Uint8Array>): Promise<Uint8Array> {
   });
 }
 
-/** 导出通道：直接把会话日志打成 zip 响应体，与导入通道读同一份 artifact。 */
+// 导出通道：直接把会话日志打成 zip 响应体，与导入通道读同一份 artifact。
 export function registerSessionExport(ctx: Context, persistence: SessionPersistenceRdb): void {
   ctx.inject(["webServer", "connection"] as const, (webCtx) => {
     const webServer = webCtx.webServer as unknown as {

package/src/gc.ts

@@ -1,14 +1,15 @@
 import type { Context } from "@deepseek-ai/cordis";
+import { SESSION_GC_PATH } from "./routes.ts";
 import type { SessionPersistenceRdb } from "./index.ts";
 
-export const SESSION_GC_PATH = "/api/session.gc";
+export { SESSION_GC_PATH };
 
 interface GcAgentLike {
   cancel?(cause: { kind: "user" }, options?: { keepInbox?: boolean }): void;
   whenIdle(): Promise<void>;
 }
 
-/** 让所有运行中的 agent 先退场：GC 要重写事件表，运行中的写路径必须停下来。 */
+// 让所有运行中的 agent 先退场：GC 要重写事件表，运行中的写路径必须停下来。
 async function stopRunningAgents(ctx: Context): Promise<number> {
   const agents = ctx.get("agents") as { list(): GcAgentLike[] } | undefined;
   const running = agents?.list() ?? [];
@@ -17,7 +18,7 @@ async function stopRunningAgents(ctx: Context): Promise<number> {
   return running.length;
 }
 
-/** GC 通道：停 agent → 回收孤儿事件行 → VACUUM，一次请求完成。 */
+// GC 通道：停 agent → 回收孤儿事件行 → VACUUM，一次请求完成。
 export function registerSessionGc(ctx: Context, persistence: SessionPersistenceRdb): void {
   ctx.inject(["webServer", "connection"] as const, (webCtx) => {
     const webServer = webCtx.webServer as unknown as {

package/src/import.ts

@@ -9,10 +9,11 @@ import { unzip } from "fflate";
 import { replaceLiveSessionLog } from "./branch.ts";
 import { restoreCatalog } from "./legacy.ts";
 import type { SessionPersistenceRdb } from "./index.ts";
+import { SESSION_IMPORT_PATH } from "./routes.ts";
 
 export const SESSION_LOG_ARTIFACT_FILENAME = "session.jsonl";
 
-export const SESSION_IMPORT_PATH = "/api/session.import";
+export { SESSION_IMPORT_PATH };
 
 const MAX_IMPORT_ZIP_BYTES = 64 * 1024 * 1024;
 
@@ -99,11 +100,9 @@ export function parseJsonlArtifact(content: string): SessionStorageMetadata & {
   };
 }
 
-/**
- * fflate 的 `unzip` 是回调式异步 API（node 侧内部走 worker_threads，浏览器侧走 Web Worker），
- * 这里桥成 Promise。它与 `unzipSync` 的差异只在同步/异步：非法 zip 走的是同一段校验代码，
- * 拒绝的错误对象与同步版一致，因此上层文案无需区分。
- */
+// fflate 的 `unzip` 是回调式异步 API（node 侧内部走 worker_threads，浏览器侧走 Web Worker），
+// 这里桥成 Promise。它与 `unzipSync` 的差异只在同步/异步：非法 zip 走的是同一段校验代码，
+// 拒绝的错误对象与同步版一致，因此上层文案无需区分。
 function unzipAsync(data: Uint8Array): Promise<Record<string, Uint8Array>> {
   return new Promise((resolve, reject) => {
     unzip(data, (error, entries) => {

package/src/index.ts

@@ -76,7 +76,7 @@ import { adoptLegacyRows, convertLegacyRows, isLegacyVersion } from "./legacy.ts
 import { needsShapeAdoption, sealOwnEvents } from "./log.ts";
 import { installStorageTakeover } from "./storage-takeover/index.ts";
 
-/** 一批事件里的最大时间：写路径据此推进会话行的「最后活动时间」。 */
+// 一批事件里的最大时间：写路径据此推进会话行的「最后活动时间」。
 function maxEventTime(events: readonly { readonly time?: number }[]): number | undefined {
   let max: number | undefined;
   for (const event of events) {
@@ -117,7 +117,7 @@ export interface SessionPersistenceRdbInternals {
   ): Promise<import("@deepseek-ai/dsh-session-persistence").SessionPersistenceRevision | undefined>;
 
   registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
-  /** fork 失败时丢弃还没被消费的映射。 */
+  // fork 失败时丢弃还没被消费的映射。
   dropReuseEventIds(childId: SessionId): void;
 }
 
@@ -142,7 +142,7 @@ export type Config =
       projectionCache?: ProjectionCacheOptions | undefined;
     };
 
-/** schema 解析之后的形状：整段 Config 是 **volatile 稳定引用**（页面可编辑），读它要过 `.get()`。 */
+// schema 解析之后的形状：整段 Config 是 **volatile 稳定引用**（页面可编辑），读它要过 `.get()`。
 export type ResolvedConfig = Volatile<Config>;
 
 export type SessionDeletionErrorCode =
@@ -488,13 +488,11 @@ class RdbSessionHandle implements SessionHandle {
   static readonly LIVE_WRITE_BATCH_MAX_DELAY_MS = 200;
 }
 
-/**
- * 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
- * （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
- */
+// 本地化说明：`description()` 的类型签名只声明 `string`，而 meta 本身接受 `Dict<string>`
+// （`vendor/schemastery/src/index.ts` 的 `mergeDesc` 就是按字典合并的），所以这里只做一次类型放行。
 const localized = (text: { zh: string; en: string }): string => text as unknown as string;
 
-/** 投影 checkpoint 的写回节流：两个分支共用。 */
+// 投影 checkpoint 的写回节流：两个分支共用。
 const projectionCacheSchema = z
   .object({
     writeEveryEvents: z
@@ -609,7 +607,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
   private readonly liveBuffers = new Map<SessionId, SessionEvent[]>();
   private readonly liveReady = new Map<SessionId, Promise<void>>();
 
-  /** 本次装配用的配置快照（整段 Config 是 volatile，重挂会给新的）。 */
+  // 本次装配用的配置快照（整段 Config 是 volatile，重挂会给新的）。
   readonly config: Config;
 
   constructor(
@@ -620,12 +618,9 @@ export class SessionPersistenceRdb extends SessionPersistence {
   ) {
     super(ctx);
 
-    // 配置就是这一行的 config（cordis.patch.yml / profile patch，或设置页改它）；上游 0.1.7 的 settings
-    // 不再提供 namespace section 覆盖，旧 `settings.yaml` 的 `session-rdb` 段由上游一次性导进同 id 的行。
-    //
-    // 整段 Config 标了 volatile（页面可编辑），而生效靠 **Loader 重挂这一行**（settings 写完经
-    // `reconcileProfilePatches` 让 Loader 重装受影响的 entry）：重挂会构造新实例、拿到新快照，所以这里取一次
-    // 就够，运行期不必反复读引用。
+    // 配置就是这一行的 config（cordis.patch.yml / profile patch，或设置页改它）；整段 Config 标了 volatile，
+    // 生效靠 **Loader 重挂这一行**（settings 写完经 `reconcileProfilePatches` 重装受影响的 entry）——重挂构造
+    // 新实例、拿到新快照，所以这里取一次就够，运行期不必反复读引用。
     this.config = config.get();
     this.backend = injectedBackend ?? createBackend(this.config);
     this.ready = this.init();
@@ -829,24 +824,23 @@ export class SessionPersistenceRdb extends SessionPersistence {
       );
     }
     await this.unarchiveBeforeDeletion(id);
-    await this.backend.transaction(async (tx) => {
-      await tx.deleteSession(id);
-    });
+    const referenced = await this.backend.transaction((tx) => tx.deleteSession(id));
     this.liveBuffers.delete(id);
     this.liveReady.delete(id);
     this.liveFailures.delete(id);
     this.liveDropWarned.delete(id);
     this.reuseEventIds.delete(id);
     await this.dropSessionStats(id);
+    await this.refreshEventUsageFlags(referenced);
   }
 
-  /** GC 通道：回收已无桥接行引用的事件行（孤儿），返回删除行数。 */
+  // GC 通道：回收已无桥接行引用的事件行（孤儿），返回删除行数。
   async collectOrphans(): Promise<number> {
     await this.ready;
     return this.backend.collectOrphans();
   }
 
-  /** GC 通道：回收父已不存在的 subagent 会话（live 的跳过），返回删除的会话数。 */
+  // GC 通道：回收父已不存在的 subagent 会话（live 的跳过），返回删除的会话数。
   async collectOrphanSessions(): Promise<number> {
     await this.ready;
     const orphans = await this.backend.listOrphanSubagentSessions();
@@ -854,7 +848,9 @@ export class SessionPersistenceRdb extends SessionPersistence {
       (id) => !this.tracker.hasPending(id) && !this.tracker.hasOpenHandle(id),
     );
     if (deletable.length === 0) return 0;
-    const deleted = await this.backend.transaction((tx) => tx.deleteSessions(deletable));
+    const { deleted, eventIds } = await this.backend.transaction((tx) =>
+      tx.deleteSessions(deletable),
+    );
     for (const id of deletable) {
       this.liveBuffers.delete(id);
       this.liveReady.delete(id);
@@ -863,16 +859,17 @@ export class SessionPersistenceRdb extends SessionPersistence {
       this.reuseEventIds.delete(id);
       await this.dropSessionStats(id);
     }
+    await this.refreshEventUsageFlags(eventIds);
     return deleted;
   }
 
-  /** 用量统计：SQL 聚合的按天 × 模型桶与按会话行（事件行去重、排除孤儿行）。 */
+  // 用量统计：SQL 聚合的按天 × 模型桶与按会话行（事件行去重、排除孤儿行）。
   async usageReport(sinceMs?: number): Promise<UsageAggregate> {
     await this.ready;
     return this.backend.usageReport(sinceMs);
   }
 
-  /** GC 通道：VACUUM；调用方需先停止运行中的写路径（见 `registerSessionGc`）。 */
+  // GC 通道：VACUUM；调用方需先停止运行中的写路径（见 `registerSessionGc`）。
   async vacuum(): Promise<void> {
     await this.ready;
     await this.backend.vacuum();
@@ -1072,11 +1069,9 @@ export class SessionPersistenceRdb extends SessionPersistence {
     };
   }
 
-  /**
-   * 统计衍生表的**旁路累加**：不在写事务里、失败只 warn——两张会话汇总表都是可销毁重建的
-   * 派生表，丢几次累加不影响可用性（需要时用 `rebuildSessionStats` 重算）。
-   * token 走写路径已折好的用量行，活动计数走本批事件类型。
-   */
+  // 统计衍生表的**旁路累加**：不在写事务里、失败只 warn——两张会话汇总表都是可销毁重建的
+  // 派生表，丢几次累加不影响可用性（需要时用 `rebuildSessionStats` 重算）。
+  // token 走写路径已折好的用量行，活动计数走本批事件类型。
   private async recordSessionStats(
     id: SessionId,
     events: readonly SessionEvent[],
@@ -1104,14 +1099,10 @@ export class SessionPersistenceRdb extends SessionPersistence {
     }
   }
 
-  /**
-   * 重算一个会话的统计（rewind / fork 之后；best-effort，同 `recordSessionStats`）：
-   * 两张汇总表按会话重算，用量行的引用标记全量重算（引用可能跨会话消失）。
-   */
+  // 重算一个会话的两张汇总表（fork 之后；best-effort，同 `recordSessionStats`）。
   async rebuildSessionStats(id: SessionId): Promise<void> {
     try {
       await this.backend.rebuildSessionStats(id);
-      await this.backend.refreshEventUsageFlags();
     } catch (error: unknown) {
       this.ctx.logger.warn(
         `session-rdb: session stats for "${id}" not rebuilt (${describeError(error)})`,
@@ -1119,11 +1110,23 @@ export class SessionPersistenceRdb extends SessionPersistence {
     }
   }
 
-  /** 会话删除时清掉它的汇总行，并重算用量行的引用标记（被删会话引用的行要立刻退出统计）。 */
+  // 重算这些用量行的引用标记（会话删除 / 日志重写之后：消失的引用要让孤儿行退出统计）。
+  private async refreshEventUsageFlags(eventIds: readonly string[]): Promise<void> {
+    const unique = [...new Set(eventIds)];
+    if (unique.length === 0) return;
+    try {
+      await this.backend.refreshEventUsageFlags(unique);
+    } catch (error: unknown) {
+      this.ctx.logger.warn(
+        `session-rdb: usage reference flags not refreshed (${describeError(error)})`,
+      );
+    }
+  }
+
+  // 会话删除时清掉它的汇总行（引用标记由调用方在拿到被删事件后一并重算）。
   private async dropSessionStats(id: SessionId): Promise<void> {
     try {
       await this.backend.deleteSessionStats(id);
-      await this.backend.refreshEventUsageFlags();
     } catch (error: unknown) {
       this.ctx.logger.warn(
         `session-rdb: session stats for "${id}" not deleted (${describeError(error)})`,
@@ -1135,15 +1138,14 @@ export class SessionPersistenceRdb extends SessionPersistence {
     id: SessionId,
     log: { meta: SessionHeader; inheritedEventCount: number; events: SessionEvent[] },
   ): Promise<void> {
+    let removed: readonly string[] = [];
     await this.backend.transaction(async (tx) => {
-      // 这段重写会删光该会话的桥接行、再按迁移视图重建——与 `appendBatch` 同一个理由，先做并发写者校验：
-      // 否则另一实例在 open 之前 / 期间提交的事件会被这段重写静默丢掉。调用方刚读过这份日志（重写只发生在
-      // write open 的读路径之后），所以 guard 里没有该会话时就把当前磁盘 head 记成本实例已确认的值；
-      // 有记录时严格比较——那能抓住"读完之后另一个实例又写了"。
+      // 重写会删光该会话的桥接行再重建，先做并发写者校验（与 `appendBatch` 同一个理由）：否则另一实例在
+      // open 前 / 期间提交的事件会被静默丢掉；调用方刚读过这份日志，guard 没有该会话时记下当前磁盘 head。
       const head = await tx.getHead(id);
       if (!this.writeGuard.has(id)) this.writeGuard.confirmHead(id, head.fHeadSequence);
       this.writeGuard.assertNoConcurrentWriter(id, head.fHeadSequence);
-      await tx.deleteBridgeTail(id, 0);
+      removed = await tx.deleteBridgeTail(id, 0);
       await tx.upsertSession(
         { meta: log.meta, inheritedEventCount: SessionLogOffset(log.inheritedEventCount) },
         randomUUID(),
@@ -1157,6 +1159,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
     });
     // 重写换了事件行：被删掉的那批成了孤儿（引用标记要落回 0），本会话汇总按新事件重算。
     await this.rebuildSessionStats(id);
+    await this.refreshEventUsageFlags(removed);
   }
 
   async listSnapshots(
@@ -1225,8 +1228,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
     signal?.throwIfAborted();
     await this.ready;
     signal?.throwIfAborted();
-    // 一条读取路径：load 的语义就是「读一次完整快照」，不再经 handle 面再读一遍
-    // （原先 open(read) 读一次 + handle.read 又读一次，等于把最贵的读付两遍）。
+    // 一条读取路径：load 的语义是「读一次完整快照」，不经 handle 面再读一遍。
     const log = await this.readLog(id, {}, signal);
     if (log === undefined) {
       // 未落库的 live 会话没有磁盘视图：与 handle.read 的 detached 口径一致，返回空日志。
@@ -1285,7 +1287,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
     this.reuseEventIds.set(childId, new Map(map));
   }
 
-  /** 丢弃一个还没被消费的复用映射（fork 失败时）：留着会让同一个 childId 之后的落写复用父会话的事件行。 */
+  // 丢弃一个还没被消费的复用映射（fork 失败时）：留着会让同一个 childId 之后的落写复用父会话的事件行。
   dropReuseEventIds(childId: SessionId): void {
     this.reuseEventIds.delete(childId);
   }
@@ -1485,7 +1487,7 @@ function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly Sessio
   );
 }
 
-/** 一批事件折成活动计数的桶：只数四种类型，按本地日聚合成四项。 */
+// 一批事件折成活动计数的桶：只数四种类型，按本地日聚合成四项。
 function sessionCountBuckets(events: readonly SessionEvent[]): SessionCountBucket[] {
   const counted = new Map<string, SessionCountBucket>();
   for (const event of events) {
@@ -1498,7 +1500,7 @@ function sessionCountBuckets(events: readonly SessionEvent[]): SessionCountBucke
   return [...counted.values()];
 }
 
-/** 一批用量行折成 token 桶：按「本地日 × 模型」聚合（模型未知落空串，与表口径一致）。 */
+// 一批用量行折成 token 桶：按「本地日 × 模型」聚合（模型未知落空串，与表口径一致）。
 function sessionUsageBuckets(usageRows: readonly EventUsageRow[]): SessionUsageBucket[] {
   const counted = new Map<string, SessionUsageBucket>();
   for (const row of usageRows) {

package/src/legacy.ts

@@ -44,11 +44,9 @@ function physicalEvent(row: EventRow): Record<string, unknown> {
   };
 }
 
-/**
- * 读旧格式用的 catalog：v3→v4 这条边要求显式子会话证据（上游 0.1.7 起），本仓库声明
- * **无子会话证据**——v3 的目录事实由父会话自己在成功路径上写成 `subagent/catalog` 事件，
- * 迁移的 child evidence 只是补偿入口；我们没有更权威的子集合来源可给（见 ADR-跟随上游session-format-v4）。
- */
+// 读旧格式用的 catalog：v3→v4 这条边要求显式子会话证据，本仓库声明**无子会话证据**——v3 的目录事实由父会话
+// 自己在成功路径上写成 `subagent/catalog` 事件，迁移的 child evidence 只是补偿入口；见
+// ADR-跟随上游session-format-v4。
 export const restoreCatalog = createSessionFormatCatalogWithChildren([]);
 
 export function convertLegacyRows(