@morlay/session-rdb 0.0.19 → 0.0.21-alpha.0

package/src/sqlite.ts

@@ -1,10 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { readdirSync, statSync } from "node:fs";
-import { mkdir, open } from "node:fs/promises";
+import { mkdir, open, readdir, stat } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DatabaseSync } from "node:sqlite";
-import { and, desc, eq, gte, sql } from "drizzle-orm";
+import { and, desc, eq, gte, inArray, lt, notInArray, sql } from "drizzle-orm";
 import { drizzle, type NodeSQLiteDatabase } from "drizzle-orm/node-sqlite";
 import { migrate } from "drizzle-orm/node-sqlite/migrator";
 import type { SessionId } from "@deepseek-ai/dsh-session";
@@ -16,11 +15,13 @@ import {
   type EventRow,
   type SessionRow,
 } from "./backend.ts";
-import { sessionConflictRow, sessionInsertRow, titleOfEventData } from "./log.ts";
+import { sessionConflictRow, sessionInsertRow, titleOfEventData, usageRowOf } from "./log.ts";
+import type { UsageAggregate, UsageTotals } from "./usage.ts";
 import {
   DEFAULT_BUSY_TIMEOUT_MS,
   SCHEMA_VERSION,
   SESSION_PERSISTENCE_SQLITE_APPLICATION_ID,
+  tEventUsage,
   tEvents,
   tPersistenceState,
   tSessionEvents,
@@ -37,7 +38,62 @@ import type { StorageRepository } from "./storage-takeover/types.ts";
 
 type SqliteDb = NodeSQLiteDatabase & { $client: DatabaseSync };
 
-/** drizzle-kit 生成的迁移目录（随包根 drizzle/ 发布；src/dist 形态经相对 URL 统一解析）。 */
+/** 用量聚合的原始行（列名是 SQL 别名）。 */
+interface RawUsageRow {
+  day: string;
+  provider: string | null;
+  model: string | null;
+  subagent: number;
+  events: number;
+  input_tokens: number | null;
+  output_tokens: number | null;
+  cache_read_tokens: number | null;
+  reasoning_tokens: number | null;
+  total_tokens: number | null;
+}
+
+/**
+ * 一次性回填：旧库的用量从未写过 `t_event_usage`，建表后按事件行补一次（幂等：表非空即跳过）。
+ */
+function backfillEventUsage(db: DatabaseSync): void {
+  const pending = db.prepare("SELECT count(*) AS n FROM t_event_usage").get() as { n: number };
+  if (pending.n > 0) return;
+  db.exec(`INSERT OR IGNORE INTO t_event_usage (
+      f_event_id, f_created_at, f_provider, f_model,
+      f_input_tokens, f_output_tokens, f_cache_read_tokens, f_reasoning_tokens, f_total_tokens)
+    SELECT e.f_event_id, e.f_created_at,
+           coalesce(json_extract(e.f_data, '$.data.message.source.provider'),
+                    json_extract(e.f_data, '$.message.source.provider')),
+           coalesce(json_extract(e.f_data, '$.data.message.source.model'),
+                    json_extract(e.f_data, '$.message.source.model')),
+           coalesce(json_extract(e.f_data, '$.data.usage.inputTokens'),
+                    json_extract(e.f_data, '$.usage.inputTokens'), 0),
+           coalesce(json_extract(e.f_data, '$.data.usage.outputTokens'),
+                    json_extract(e.f_data, '$.usage.outputTokens'), 0),
+           coalesce(json_extract(e.f_data, '$.data.usage.cacheReadTokens'),
+                    json_extract(e.f_data, '$.usage.cacheReadTokens'), 0),
+           coalesce(json_extract(e.f_data, '$.data.usage.reasoningTokens'),
+                    json_extract(e.f_data, '$.usage.reasoningTokens'), 0),
+           coalesce(json_extract(e.f_data, '$.data.usage.totalTokens'),
+                    json_extract(e.f_data, '$.usage.totalTokens'), 0)
+      FROM t_events e
+     WHERE e.f_type = 'assistant/message'
+       AND (json_extract(e.f_data, '$.data.usage') IS NOT NULL
+            OR json_extract(e.f_data, '$.usage') IS NOT NULL)`);
+}
+
+/** SQL 的缺失求和是 NULL：没有 usage 字段的行使该字段计 0。 */
+function totalsOf(row: RawUsageRow): UsageTotals {
+  return {
+    events: row.events,
+    inputTokens: row.input_tokens ?? 0,
+    outputTokens: row.output_tokens ?? 0,
+    cacheReadTokens: row.cache_read_tokens ?? 0,
+    reasoningTokens: row.reasoning_tokens ?? 0,
+    totalTokens: row.total_tokens ?? 0,
+  };
+}
+
 const sqliteMigrationsDir = fileURLToPath(new URL("../drizzle/sqlite/", import.meta.url));
 
 const sqliteTxQueues = new Map<string, Promise<void>>();
@@ -45,7 +101,7 @@ const sqliteTxQueues = new Map<string, Promise<void>>();
 function enqueueSqliteTx<T>(path: string, fn: () => Promise<T>): Promise<T> {
   const tail = sqliteTxQueues.get(path) ?? Promise.resolve();
   const run = tail.then(fn);
-  // 失败的事务不得毒化后续队列。
+
   sqliteTxQueues.set(
     path,
     run.then(
@@ -65,11 +121,11 @@ async function createDatabaseFile(path: string): Promise<void> {
   }
 }
 
-export function openDatabase(
+export async function openDatabase(
   path: string,
   journalMode: JournalMode,
   busyTimeout = DEFAULT_BUSY_TIMEOUT_MS,
-): DatabaseSync {
+): Promise<DatabaseSync> {
   const db = new DatabaseSync(path);
   try {
     configureDatabase(db, path, journalMode, busyTimeout);
@@ -77,13 +133,13 @@ export function openDatabase(
     const { user_version: onDisk } = db.prepare("PRAGMA user_version").get() as {
       user_version: number;
     };
-    // v2 库（旧版本建表）首次打开：建迁移表并标记 v2 baseline 已应用，
-    // 使 migrate 只执行 v3 diff（删 f_original_seq、建 t_schema_meta）。
+
     if (onDisk === 2 && !hasMigrationsTable(db)) {
-      baselineV2(db);
+      await baselineV2(db);
     }
     migrate(dbx, { migrationsFolder: sqliteMigrationsDir });
-    // store 身份单例：新库由 migrate 建表后插入；v2/v3 库已有行（no-op）。
+    backfillEventUsage(db);
+
     dbx
       .insert(tPersistenceState)
       .values({ fSingleton: 1, fStoreId: randomUUID() })
@@ -92,8 +148,7 @@ export function openDatabase(
     if (onDisk === 0 || onDisk === 2) {
       db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`);
     }
-    // journal_mode 不可绑定，经校验后的联合可直接插值；在归属校验、迁移
-    // 与身份写入全部成功之后应用（失败时保持磁盘原状）。
+
     db.exec(`PRAGMA journal_mode = ${journalMode.toUpperCase()}`);
     return db;
   } catch (error: unknown) {
@@ -110,9 +165,8 @@ function hasMigrationsTable(db: DatabaseSync): boolean {
   );
 }
 
-/** 标记 v2 baseline 已应用（迁移表 v1 结构：id/hash/created_at/name/applied_at）。 */
-function baselineV2(db: DatabaseSync): void {
-  const dir = readdirSync(sqliteMigrationsDir).find((name) => name.endsWith("_v2_initial"));
+async function baselineV2(db: DatabaseSync): Promise<void> {
+  const dir = (await readdir(sqliteMigrationsDir)).find((name) => name.endsWith("_v2_initial"));
   if (dir === undefined) throw new Error("missing v2 baseline migration in drizzle/sqlite");
   db.exec(`
     CREATE TABLE __drizzle_migrations (
@@ -134,12 +188,11 @@ function configureDatabase(
   journalMode: JournalMode,
   busyTimeout: number,
 ): void {
-  // 其余是驱动级 SQLite 操作（无 drizzle API）：连接 pragma 与 sqlite_schema 探测。
   db.exec("PRAGMA foreign_keys = ON");
-  // busy_timeout 必须先于一切锁获取（初始化事务与每次写事务）。
+
   db.exec(`PRAGMA busy_timeout = ${busyTimeout}`);
   const dbx = drizzle({ client: db });
-  // 初始化在单个 `BEGIN IMMEDIATE` 事务内完成，持写锁校验 schema 归属。
+
   dbx.transaction(
     (tx) => {
       const { user_version: onDisk } = tx.get(sql`PRAGMA user_version`) as {
@@ -185,7 +238,6 @@ export class SqliteBackend implements Backend {
   readonly kind = "sqlite" as const;
   storeIdentity!: string;
 
-  /** storages 接管表访问层；句柄在 open() 完成后解析。 */
   readonly storage: StorageRepository;
 
   private dbPath = "";
@@ -199,13 +251,12 @@ export class SqliteBackend implements Backend {
       this.resolveDb = resolve;
       this.rejectDb = reject;
     });
-    // 每个 storage 原语都会重新 await 同一 promise，失败仍逐一可见；这个
-    // 守卫只防止 open 失败早于首次使用时的 unhandled rejection。
+
     this.dbReady.catch(() => {});
     this.storage = createStorageRepository({
       db: () => this.dbReady,
-      // 同步驱动：读路径直读介质（open 之前的调用是装配错误，fail loud）。
-      dbSync: () => {
+
+      dbDirect: () => {
         if (this.db === undefined) throw new Error("sqlite session database is not open");
         return this.db;
       },
@@ -220,9 +271,7 @@ export class SqliteBackend implements Backend {
           } catch (error: unknown) {
             try {
               db.$client.exec("ROLLBACK");
-            } catch {
-              // 原始 SQLite 失败仍是可操作的根因。
-            }
+            } catch {}
             throw error;
           }
         }),
@@ -255,15 +304,12 @@ export class SqliteBackend implements Backend {
       await mkdir(dirname(actual), { recursive: true, mode: 0o700 });
       await createDatabaseFile(actual);
     }
-    // openDatabase 内的初始化事务是同步 `BEGIN IMMEDIATE`，须排进同一
-    // per-path 写队列——否则与进行中的写事务竞争会在持有锁的异步回调
-    // 让步期间忙等，冻结事件循环（死锁直到 busy_timeout）。
+
     await enqueueSqliteTx(actual, async () => {
       this.db = drizzle({
-        client: openDatabase(actual, this.options.journalMode, this.options.busyTimeout),
+        client: await openDatabase(actual, this.options.journalMode, this.options.busyTimeout),
       });
-      // drizzle-kit 迁移：v2 baseline 由旧版本建表（首次打开时标记为已应用），
-      // 本版本只执行 v3 diff（删 f_original_seq、建 t_schema_meta）。
+
       migrate(this.db, { migrationsFolder: sqliteMigrationsDir });
     });
     try {
@@ -272,7 +318,7 @@ export class SqliteBackend implements Backend {
         .from(tPersistenceState)
         .where(eq(tPersistenceState.fSingleton, 1))
         .get() as { fStoreId: string } | undefined;
-      /* v8 ignore next -- openDatabase inserts the singleton before returning. */
+
       if (row === undefined) {
         throw new Error(`session database at "${actual}" has no store identity`);
       }
@@ -280,7 +326,7 @@ export class SqliteBackend implements Backend {
         throw new Error(`session database at "${actual}" has no valid store identity`);
       }
       if (actual !== ":memory:") {
-        const identity = statSync(actual, { bigint: true });
+        const identity = await stat(actual, { bigint: true });
         this.storeIdentity = `file:${identity.dev}:${identity.ino}:${identity.birthtimeNs}:store:${row.fStoreId}`;
       } else {
         this.storeIdentity = `memory:store:${row.fStoreId}`;
@@ -292,8 +338,6 @@ export class SqliteBackend implements Backend {
   }
 
   async close(): Promise<void> {
-    // open 可能未及赋值 db 就失败（队列内初始化抛错）；close 不得在
-    // coordinator 的 dispose 之上再崩。
     if (this.db === undefined) return;
     this.db.$client.close();
   }
@@ -314,17 +358,30 @@ export class SqliteBackend implements Backend {
     return scoped.orderBy(tSessionEvents.fSequence).all() as unknown as EventRow[];
   }
 
+  async getEventTypeAt(id: SessionId, sequence: number): Promise<string | undefined> {
+    const row = this.eventRows()
+      .where(and(eq(tSessionEvents.fSessionId, id), eq(tSessionEvents.fSequence, sequence)))
+      .get() as { fType?: string } | undefined;
+    return row?.fType;
+  }
+
+  async getEventTypesBefore(
+    id: SessionId,
+    beforeSequence: number,
+    limit: number,
+  ): Promise<Array<Pick<EventRow, "fSequence" | "fType">>> {
+    return this.eventRows()
+      .where(and(eq(tSessionEvents.fSessionId, id), lt(tSessionEvents.fSequence, beforeSequence)))
+      .orderBy(desc(tSessionEvents.fSequence))
+      .limit(limit)
+      .all() as unknown as Array<Pick<EventRow, "fSequence" | "fType">>;
+  }
+
   async listSessions(): Promise<SessionRow[]> {
     return this.db.select().from(tSessions).all() as SessionRow[];
   }
 
   async transaction<T>(fn: (tx: BackendTx) => Promise<T>): Promise<T> {
-    // drizzle 的 SQLite 驱动只支持同步事务回调，而共享 BackendTx 接口因
-    // PostgreSQL 是异步的——BEGIN/COMMIT/ROLLBACK 语句因此走驱动层。
-    // 异步回调在持写锁期间让出微任务间隙：本进程内第二个连接此时同步
-    // `BEGIN IMMEDIATE` 会忙等并冻结事件循环（锁持有者无法提交，死锁直到
-    // busy_timeout）。per-path 写队列串行化消除该间隙——SQLite 本就单写者；
-    // 跨进程竞争仍经 busy_timeout 解决，不同数据库文件互不串行。
     return enqueueSqliteTx(this.dbPath, async () => {
       this.db.$client.exec("BEGIN IMMEDIATE");
       try {
@@ -332,15 +389,10 @@ export class SqliteBackend implements Backend {
         this.db.$client.exec("COMMIT");
         return result;
       } catch (error: unknown) {
-        // DELETE+INSERT 不会冲突；这里回滚 DB 级失败（磁盘满等），测试不可达。
-        /* v8 ignore start */
         try {
           this.db.$client.exec("ROLLBACK");
-        } catch {
-          // 原始 SQLite 失败仍是可操作的根因。
-        }
+        } catch {}
         throw error;
-        /* v8 ignore stop */
       }
     });
   }
@@ -357,10 +409,10 @@ export class SqliteBackend implements Backend {
     refreshTitle: (id) => this.refreshTitle(id),
     deleteBridgeTail: (id, fromSequence) => this.deleteBridgeTail(id, fromSequence),
     getPrevBridge: (id, sequence) => this.getPrevBridge(id, sequence),
+    deleteSession: (id) => this.deleteSession(id),
+    deleteSessions: (ids) => this.deleteSessions(ids),
   };
 
-  // --- row primitives (transaction-internal or standalone) ---
-
   private async upsertSession(storage: SessionStorageMetadata, incarnation: string): Promise<void> {
     this.db
       .insert(tSessions)
@@ -380,7 +432,7 @@ export class SqliteBackend implements Backend {
       .from(tSessions)
       .where(eq(tSessions.fSessionId, id))
       .get() as Pick<SessionRow, "fHeadEventId" | "fHeadSequence"> | undefined;
-    /* v8 ignore next -- appendBatch/commitRepair always materialize the row before reading the head */
+
     if (head === undefined) throw new Error(`session "${id}" has no materialized row`);
     return head;
   }
@@ -391,7 +443,7 @@ export class SqliteBackend implements Backend {
       .from(tSessions)
       .where(eq(tSessions.fSessionId, id))
       .get() as { fSeedLength: number | null } | undefined;
-    /* v8 ignore next -- rewind always materializes the row before reading the seed length */
+
     if (row === undefined) throw new Error(`session "${id}" has no materialized row`);
     return row.fSeedLength;
   }
@@ -414,6 +466,14 @@ export class SqliteBackend implements Backend {
         .values(events.slice(i, i + SqliteBackend.INSERT_BATCH_ROWS).map((event) => ({ ...event })))
         .run();
     }
+    // 用量顺带落 t_event_usage：统计不再逐行解析事件 JSON（重复事件行忽略，fork 复用不重复记）。
+    const usage = events.flatMap((event) => {
+      const row = usageRowOf(event);
+      return row === undefined ? [] : [row];
+    });
+    if (usage.length > 0) {
+      this.db.insert(tEventUsage).values(usage).onConflictDoNothing().run();
+    }
   }
 
   private async insertBridges(
@@ -453,7 +513,6 @@ export class SqliteBackend implements Backend {
       .run();
   }
 
-  /** 从事件表重算标题（最后一条 `session/title`），写回会话行的 f_title 列。 */
   private async refreshTitle(id: SessionId): Promise<void> {
     const row = this.db
       .select({ fSequence: tSessionEvents.fSequence, fData: tEvents.fData })
@@ -489,6 +548,123 @@ export class SqliteBackend implements Backend {
       .get() as { fEventId: string; fSequence: number } | undefined;
   }
 
+  private async deleteSession(id: SessionId): Promise<void> {
+    this.db.delete(tSessionEvents).where(eq(tSessionEvents.fSessionId, id)).run();
+    this.db.delete(tWorkspaceSessions).where(eq(tWorkspaceSessions.fSessionId, id)).run();
+    this.db.delete(tSessionProjcacheRows).where(eq(tSessionProjcacheRows.fSessionId, id)).run();
+    this.db.delete(tSessions).where(eq(tSessions.fSessionId, id)).run();
+  }
+
+  /** 事件行可能被多个会话共享（fork 派生），所以孤儿只能在全库范围内判定。 */
+  async collectOrphans(): Promise<number> {
+    const referenced = this.db.select({ fEventId: tSessionEvents.fEventId }).from(tSessionEvents);
+    const info = this.db.delete(tEvents).where(notInArray(tEvents.fEventId, referenced)).run();
+    // 用量行跟着事件行走：没有事件行的用量不再计入统计。
+    this.db
+      .delete(tEventUsage)
+      .where(
+        notInArray(
+          tEventUsage.fEventId,
+          this.db.select({ fEventId: tEvents.fEventId }).from(tEvents),
+        ),
+      )
+      .run();
+    return Number(info.changes);
+  }
+
+  /** 父会话被删后留下的 subagent 会话：父已不在表里，或本来就没有父。 */
+  async listOrphanSubagentSessions(): Promise<SessionId[]> {
+    const rows = this.db.$client
+      .prepare(
+        `SELECT f_session_id AS id FROM t_sessions
+         WHERE f_origin = 'subagent'
+           AND (f_parent_session IS NULL
+                OR f_parent_session NOT IN (SELECT f_session_id FROM t_sessions))`,
+      )
+      .all() as Array<{ id: string }>;
+    return rows.map((row) => row.id as SessionId);
+  }
+
+  private async deleteSessions(ids: SessionId[]): Promise<number> {
+    if (ids.length === 0) return 0;
+    this.db.delete(tSessionEvents).where(inArray(tSessionEvents.fSessionId, ids)).run();
+    this.db.delete(tWorkspaceSessions).where(inArray(tWorkspaceSessions.fSessionId, ids)).run();
+    this.db
+      .delete(tSessionProjcacheRows)
+      .where(inArray(tSessionProjcacheRows.fSessionId, ids))
+      .run();
+    const info = this.db.delete(tSessions).where(inArray(tSessions.fSessionId, ids)).run();
+    return Number(info.changes);
+  }
+
+  /** 用量聚合：只读 `t_event_usage`；可选只算 `sinceMs` 之后的事件行。 */
+  async usageReport(sinceMs?: number): Promise<UsageAggregate> {
+    const sinceClause = sinceMs === undefined ? "" : " AND u.f_created_at >= ?";
+    const sinceParams = sinceMs === undefined ? [] : [sinceMs];
+    const buckets = this.db.$client
+      .prepare(
+        `SELECT date(u.f_created_at / 1000, 'unixepoch', 'localtime') AS day,
+                u.f_provider AS provider,
+                u.f_model AS model,
+                EXISTS (SELECT 1 FROM t_session_events sb
+                          JOIN t_sessions ss ON ss.f_session_id = sb.f_session_id
+                         WHERE sb.f_event_id = u.f_event_id AND ss.f_origin = 'subagent') AS subagent,
+                count(*) AS events,
+                sum(u.f_input_tokens) AS input_tokens,
+                sum(u.f_output_tokens) AS output_tokens,
+                sum(u.f_cache_read_tokens) AS cache_read_tokens,
+                sum(u.f_reasoning_tokens) AS reasoning_tokens,
+                sum(u.f_total_tokens) AS total_tokens
+           FROM t_event_usage u
+          WHERE EXISTS (SELECT 1 FROM t_session_events rb WHERE rb.f_event_id = u.f_event_id)${sinceClause}
+          GROUP BY day, provider, model, subagent`,
+      )
+      .all(...sinceParams) as unknown as RawUsageRow[];
+    const sessions = this.db.$client
+      .prepare(
+        `SELECT b.f_session_id AS session_id,
+                s.f_title AS title,
+                (s.f_origin = 'subagent') AS subagent,
+                (s.f_archived_at IS NOT NULL) AS archived,
+                count(*) AS events,
+                sum(u.f_input_tokens) AS input_tokens,
+                sum(u.f_output_tokens) AS output_tokens,
+                sum(u.f_cache_read_tokens) AS cache_read_tokens,
+                sum(u.f_reasoning_tokens) AS reasoning_tokens,
+                sum(u.f_total_tokens) AS total_tokens
+           FROM t_session_events b
+           JOIN t_event_usage u ON u.f_event_id = b.f_event_id
+           JOIN t_sessions s ON s.f_session_id = b.f_session_id
+          WHERE 1 = 1${sinceClause}
+          GROUP BY b.f_session_id, s.f_title, s.f_origin, s.f_archived_at`,
+      )
+      .all(...sinceParams) as unknown as Array<
+      RawUsageRow & { session_id: string; title: string | null; archived: number }
+    >;
+    return {
+      buckets: buckets.map((row) => ({
+        day: row.day,
+        provider: row.provider,
+        model: row.model,
+        subagent: row.subagent === 1,
+        ...totalsOf(row),
+      })),
+      sessions: sessions.map((row) => ({
+        sessionId: row.session_id,
+        title: row.title,
+        subagent: row.subagent === 1,
+        archived: row.archived === 1,
+        ...totalsOf(row),
+      })),
+    };
+  }
+
+  async vacuum(): Promise<void> {
+    await enqueueSqliteTx(this.dbPath, async () => {
+      this.db.$client.exec("VACUUM");
+    });
+  }
+
   private eventRows() {
     return this.db
       .select({

package/src/storage-takeover/index.ts

@@ -1,16 +1,3 @@
-/**
- * storages 接管的装配入口：在 session-rdb 插件内注册
- *
- * 1. storage hub 的 `rdb` KV 后端——上游 `storage-domain` 的 `StorageBackend.kv`
- *    契约实现（名字来自上游），把 workspace 域映射到 rdb 语义专用表；
- * 2. `ctx.sessionProjectionCache` 服务——替换上游 `session-projection-cache`
- *    插件，直接读写 rdb 的投影 checkpoint 表。
- *
- * 两者都经 `ctx.inject` 挂在可选依赖上：装配里缺 `storage` 或
- * `sessionProjections`（纯 cordis 单测）时静默跳过，消费者按上游的缺服务
- * 路径降级。
- */
-
 import type { Context } from "@deepseek-ai/cordis";
 import { storageBackendServiceKey } from "@deepseek-ai/dsh-storage";
 import type { ProjectionCacheConfig } from "./projection-cache.ts";
@@ -18,24 +5,15 @@ import { SessionProjectionCacheRdb } from "./projection-cache.ts";
 import { RDB_STORAGE_BACKEND, RdbStorageBackend } from "./storage-backend.ts";
 import type { StorageRepository } from "./types.ts";
 
-/** 装配参数。 */
 export interface StorageTakeoverOptions {
-  /** storages 接管表访问层（与事件日志同介质）。 */
   repository: StorageRepository;
-  /** 投影缓存的写节流参数（上游 base 装配的部署值）。 */
+
   projectionCache: ProjectionCacheConfig;
-  /** 介质就绪信号：投影缓存直读介质前必须等到。 */
+
   ready: Promise<unknown>;
 }
 
-/**
- * Install the storages takeover on the session-rdb plugin context.
- * @param ctx - session-rdb plugin context.
- * @param options - repository and projection-cache throttle parameters.
- */
 export function installStorageTakeover(ctx: Context, options: StorageTakeoverOptions): void {
-  // workspace 域：上游 workspaceRegistry 仍持有服务与内存态，这里只提供它
-  // 依赖的 storage-domain 介质（backend 名 `rdb`，由 profile patch 路由）。
   ctx.inject(["storage"], (storageCtx) => {
     const backend = new RdbStorageBackend(options.repository);
     storageCtx.effect(() => {
@@ -48,10 +26,6 @@ export function installStorageTakeover(ctx: Context, options: StorageTakeoverOpt
     storageCtx.provide(storageBackendServiceKey(RDB_STORAGE_BACKEND), backend);
   });
 
-  // 投影 checkpoint：上游插件被禁用后由本服务提供同名 API。按 cordis
-  // class plugin 装载（而不是直接 new）：`static inject` 负责等依赖就绪，
-  // 框架负责调用 `[Service.init]` 安装写入路径——直接 new 会静默跳过 init，
-  // 导致 session/created、turn/end、计数与定时器的 checkpoint 写入全部失效。
   ctx.plugin(SessionProjectionCacheRdb, {
     ...options.projectionCache,
     repository: options.repository,