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

package/src/storage-takeover/storage-backend.ts

@@ -1,19 +1,12 @@
 import { StorageError } from "@deepseek-ai/dsh-storage";
-import type { SessionId } from "@deepseek-ai/dsh-session";
-import type { ScheduleTask } from "@deepseek-ai/dsh-schedule";
-import type { WorkspaceId } from "@deepseek-ai/dsh-workspace";
 import type { KvFacet, KvUnit, KvUnitDescriptor, StorageBackend } from "@deepseek-ai/dsh-storage";
-import type { StorageRepository, WorkspaceRecord, WorkspaceDomainState } from "./types.ts";
+import type { StorageRepository } from "./types.ts";
 
 export const RDB_STORAGE_BACKEND = "rdb";
 
-// 本后端服务哪些域：一个域一个显式映射（表结构显式维护，未知域名 fail loud——见
-// `.agents/adrs/20260917-接管storages到rdb语义表.md`）。官方那几行谁读哪个域是上游的事，
-// 这里只回答"这个域的数据落在哪张表"。
-const WORKSPACE_UNIT = "workspace";
-const WORKSPACE_TABLE = "workspaces";
-const SCHEDULE_UNIT = "schedule";
-const SCHEDULE_TABLE = "tasks";
+// 本后端服务**所有** storage 域：`(域, 表, 键)` 一行落 `t_storage_records`，global 单例用空表名与空键。
+// 上游 `KvUnit` 的契约只有「按表名读写记录 + 一个 global」这几种操作，行存储直接承载它，所以再加一个域
+// （不论它自带几张表、还是只有 global）都不需要新表或新映射——域名就是行的一部分。
 
 // 本后端对 unit 的内部约定：关闭时把域名让回后端（上游 `KvUnit` 没有这个入口，它归"谁能再开一次"这件事）。
 interface ReleasableKvUnit extends KvUnit {
@@ -24,29 +17,31 @@ export class RdbStorageBackend implements StorageBackend {
   readonly kv: KvFacet = { open: (descriptor) => this.openUnit(descriptor) };
 
   private readonly open = new Map<string, ReleasableKvUnit>();
+  // 正在打开的名字：`open()` 要先等介质，占位必须在 await 之前，否则并发 open 会双双通过检查。
+  private readonly opening = new Set<string>();
   private closed = false;
 
-  constructor(private readonly repository: StorageRepository) {}
+  constructor(private readonly repository: () => Promise<StorageRepository>) {}
 
   private async openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
     if (this.closed) throw new StorageError("closed", "rdb storage backend is closed");
-    if (descriptor.layout !== undefined && descriptor.layout !== "single") {
-      throw new Error(
-        `rdb storage backend serves only the 'single' layout (domain '${descriptor.name}' ` +
-          `declares '${descriptor.layout}')`,
-      );
-    }
-    if (this.open.has(descriptor.name)) {
+    if (this.open.has(descriptor.name) || this.opening.has(descriptor.name)) {
       throw new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`);
     }
+    this.opening.add(descriptor.name);
 
-    const unit = this.unitFor(descriptor);
+    const repository = await this.repository();
+    const unit = new RdbKvUnit(repository, descriptor);
     this.open.set(descriptor.name, unit);
+    this.opening.delete(descriptor.name);
     try {
-      const stored = await this.repository.readUnitVersion(descriptor.name);
+      const stored = await repository.readUnitVersion(descriptor.name);
+      const accepted =
+        stored === descriptor.version ||
+        (descriptor.compatibleVersions ?? []).includes(stored ?? -1);
       if (stored === undefined) {
-        await this.repository.insertUnitVersion(descriptor.name, descriptor.version);
-      } else if (stored !== descriptor.version) {
+        await repository.insertUnitVersion(descriptor.name, descriptor.version);
+      } else if (!accepted) {
         throw new StorageError(
           "version-mismatch",
           `kv unit '${descriptor.name}' is stamped version ${stored} on the medium, ` +
@@ -55,6 +50,7 @@ export class RdbStorageBackend implements StorageBackend {
       }
     } catch (error) {
       this.open.delete(descriptor.name);
+      this.opening.delete(descriptor.name);
       throw error;
     }
     unit.onClose(() => {
@@ -63,31 +59,6 @@ export class RdbStorageBackend implements StorageBackend {
     return unit;
   }
 
-  private unitFor(descriptor: KvUnitDescriptor): ReleasableKvUnit {
-    if (descriptor.name === WORKSPACE_UNIT) {
-      if (!descriptor.tables.includes(WORKSPACE_TABLE) || descriptor.hasGlobal !== true) {
-        throw new Error(
-          `rdb storage backend expects the '${WORKSPACE_UNIT}' domain shape ` +
-            `(table '${WORKSPACE_TABLE}' plus a global slot)`,
-        );
-      }
-      return new WorkspaceKvUnit(this.repository, descriptor);
-    }
-    if (descriptor.name === SCHEDULE_UNIT) {
-      if (!descriptor.tables.includes(SCHEDULE_TABLE) || descriptor.hasGlobal !== false) {
-        throw new Error(
-          `rdb storage backend expects the '${SCHEDULE_UNIT}' domain shape ` +
-            `(table '${SCHEDULE_TABLE}' without a global slot)`,
-        );
-      }
-      return new ScheduleKvUnit(this.repository, descriptor);
-    }
-    throw new Error(
-      `rdb storage backend serves only the '${WORKSPACE_UNIT}' and '${SCHEDULE_UNIT}' domains ` +
-        `(requested '${descriptor.name}')`,
-    );
-  }
-
   async close(): Promise<void> {
     this.closed = true;
     const units = [...this.open.values()];
@@ -96,8 +67,7 @@ export class RdbStorageBackend implements StorageBackend {
   }
 }
 
-// 一个 KV unit 的公共形态：关闭后拒写、关闭前把已接受的写排干、关闭回调把名字让回给后端。
-// 域自己的读写在子类里（`unitFor` 的返回类型就地校验它们合得上 `KvUnit`）。
+// 一个 unit 的公共形态：关闭后拒写、关闭前把已接受的写排干、关闭回调把名字让回给后端。
 abstract class TrackedKvUnit {
   private closed = false;
 
@@ -110,9 +80,6 @@ abstract class TrackedKvUnit {
     protected readonly descriptor: KvUnitDescriptor,
   ) {}
 
-  // 这个 unit 认的表名（由各自的域决定）。
-  protected abstract readonly tables: readonly string[];
-
   onClose(release: () => void): void {
     this.onClosed = release;
   }
@@ -146,139 +113,57 @@ abstract class TrackedKvUnit {
   }
 
   protected assertTable(table: string): void {
-    if (!this.tables.includes(table)) {
+    if (!this.descriptor.tables.includes(table)) {
       throw new Error(`unit '${this.descriptor.name}' does not declare table '${table}'`);
     }
   }
 }
 
-class WorkspaceKvUnit extends TrackedKvUnit {
-  protected readonly tables = [WORKSPACE_TABLE];
-
+// 行存储：记录按 `(域, 表, 键)` 一行，global 单例是空表名的那一行。`single` 与 `per-record` 两种布局
+// 在这里同构（一行一条记录），所以布局不再拒绝——版本仍按域戳。
+class RdbKvUnit extends TrackedKvUnit {
   async loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }> {
     this.assertOpen();
-    const records: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-    for (const { id, record } of await this.repository.listWorkspaces()) {
-      records[id] = record;
+    const tables: Record<string, Record<string, unknown>> = Object.create(null) as Record<
+      string,
+      Record<string, unknown>
+    >;
+    for (const record of await this.repository.listDomainRecords(this.descriptor.name)) {
+      (tables[record.table] ??= {})[record.key] = record.value;
     }
-    const state = await this.repository.readWorkspaceState();
-    return { tables: { [WORKSPACE_TABLE]: records }, global: state };
+    // 声明了但从未写过的表也要出现在快照里（域层按 spec.tables 逐表读）。
+    for (const table of this.descriptor.tables) tables[table] ??= {};
+    return {
+      tables,
+      global: this.descriptor.hasGlobal
+        ? await this.repository.readDomainGlobal(this.descriptor.name)
+        : null,
+    };
   }
 
   async putRecord(table: string, key: string, value: unknown): Promise<void> {
     this.assertOpen();
     this.assertTable(table);
-    await this.track(this.repository.putWorkspace(key, workspaceRecordOf(value)));
+    await this.track(this.repository.putDomainRecord(this.descriptor.name, table, key, value));
   }
 
   async deleteRecord(table: string, key: string): Promise<void> {
     this.assertOpen();
     this.assertTable(table);
-    await this.track(this.repository.deleteWorkspace(key));
+    await this.track(this.repository.deleteDomainRecord(this.descriptor.name, table, key));
   }
 
-  // 上游 `KvUnit.deleteRecords`：行存储一次批量做完（不让调用方逐条重试）。
   async deleteRecords(table: string, keys: readonly string[]): Promise<void> {
     this.assertOpen();
     this.assertTable(table);
-    await this.track(this.repository.deleteWorkspaces([...new Set(keys)]));
+    await this.track(this.repository.deleteDomainRecords(this.descriptor.name, table, keys));
   }
 
   async setGlobal(value: unknown): Promise<void> {
     this.assertOpen();
-    await this.track(this.repository.writeWorkspaceState(workspaceStateOf(value)));
-  }
-}
-
-class ScheduleKvUnit extends TrackedKvUnit {
-  protected readonly tables = [SCHEDULE_TABLE];
-
-  async loadAll(): Promise<{ tables: Record<string, Record<string, unknown>>; global: unknown }> {
-    this.assertOpen();
-    const records: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
-    for (const { id, task } of await this.repository.listScheduleTasks()) {
-      records[id] = task;
+    if (!this.descriptor.hasGlobal) {
+      throw new Error(`unit '${this.descriptor.name}' declares no global slot`);
     }
-    // 这个域没有 global 槽（`scheduleDomain` 不声明）：`null` = "从未写过"，域层不会读它。
-    return { tables: { [SCHEDULE_TABLE]: records }, global: null };
-  }
-
-  async putRecord(table: string, key: string, value: unknown): Promise<void> {
-    this.assertOpen();
-    this.assertTable(table);
-    await this.track(this.repository.putScheduleTask(key, scheduleTaskOf(value)));
-  }
-
-  async deleteRecord(table: string, key: string): Promise<void> {
-    this.assertOpen();
-    this.assertTable(table);
-    await this.track(this.repository.deleteScheduleTask(key));
-  }
-
-  async deleteRecords(table: string, keys: readonly string[]): Promise<void> {
-    this.assertOpen();
-    this.assertTable(table);
-    await this.track(this.repository.deleteScheduleTasks([...new Set(keys)]));
-  }
-
-  setGlobal(_value: unknown): Promise<void> {
-    throw new Error(`unit '${this.descriptor.name}' declares no global slot`);
-  }
-}
-
-function workspaceRecordOf(value: unknown): WorkspaceRecord {
-  const record = value as Partial<WorkspaceRecord> | null;
-  if (
-    typeof record !== "object" ||
-    record === null ||
-    typeof record.path !== "string" ||
-    typeof record.title !== "string" ||
-    !Array.isArray(record.sessionIds) ||
-    typeof record.createdAt !== "string" ||
-    typeof record.updatedAt !== "string"
-  ) {
-    throw new TypeError("workspace record does not match the stored shape");
-  }
-  return {
-    path: record.path,
-    title: record.title,
-    sessionIds: record.sessionIds.map((id) => id as SessionId),
-    createdAt: record.createdAt,
-    updatedAt: record.updatedAt,
-  };
-}
-
-function workspaceStateOf(value: unknown): WorkspaceDomainState {
-  const state = value as Partial<WorkspaceDomainState> | null;
-  if (
-    typeof state !== "object" ||
-    state === null ||
-    typeof state.initialized !== "boolean" ||
-    !Array.isArray(state.workspaceIds) ||
-    !Array.isArray(state.archivedSessionIds) ||
-    !Array.isArray(state.pinnedSessionIds)
-  ) {
-    throw new TypeError("workspace registry state does not match the stored shape");
-  }
-  return {
-    initialized: state.initialized,
-    workspaceIds: state.workspaceIds.map((id) => id as WorkspaceId),
-    archivedSessionIds: state.archivedSessionIds.map((id) => id as SessionId),
-    pinnedSessionIds: state.pinnedSessionIds.map((id) => id as SessionId),
-    ...(state.pendingMutation === undefined ? {} : { pendingMutation: state.pendingMutation }),
-  };
-}
-
-function scheduleTaskOf(value: unknown): ScheduleTask {
-  const task = value as Partial<ScheduleTask> | null;
-  if (
-    typeof task !== "object" ||
-    task === null ||
-    typeof task.sessionId !== "string" ||
-    typeof task.record !== "object" ||
-    task.record === null
-  ) {
-    throw new TypeError("schedule task does not match the stored shape");
+    await this.track(this.repository.writeDomainGlobal(this.descriptor.name, value));
   }
-  return task as ScheduleTask;
 }

package/src/storage-takeover/types.ts

@@ -6,6 +6,7 @@ import type {
   ProjectionCheckpointRow,
 } from "@deepseek-ai/dsh-session-projection";
 import type { WorkspaceDomainState, WorkspaceRecord } from "@deepseek-ai/dsh-workspace";
+import type { Database } from "@morlay/rdbkit";
 
 export type {
   CheckpointIdentity,
@@ -16,10 +17,32 @@ export type {
   WorkspaceRecord,
 };
 
+export interface DomainRecord {
+  table: string;
+  key: string;
+  value: unknown;
+}
+
+export interface WorkspaceIndexEntry {
+  id: string;
+  title: string;
+  sessionIds: string[];
+}
+
+export interface StorageRepositoryHost {
+  /** 统一的查询面（结构、迁移与域读写都走它）。 */
+  database: Database;
+
+  /** 把一组写做成一次事务（宿主管连接与隔离级别）。 */
+  writeAtomically: <T>(fn: (database: Database) => Promise<T>) => Promise<T>;
+}
+
 export interface StoredProjcacheEntry {
   sessionId: SessionId;
   identity: CheckpointIdentity;
   rows: ProjectionCheckpoint;
+  /** 会话标题（随快照一起加载 / 写路径刷新；`cachedSnapshot` 缺标题时用它补，不回库直读）。 */
+  title?: { title: string; seq: number };
 }
 
 export interface StorageRepository {
@@ -27,36 +50,39 @@ export interface StorageRepository {
 
   insertUnitVersion(name: string, version: number): Promise<void>;
 
-  listWorkspaces(): Promise<Array<{ id: string; record: WorkspaceRecord }>>;
+  // 所有 storage 域共用：`(domain, table, key)` 一行，值是整份记录文档。global 单例用
+  // `table = ''`、`key = ''`；读不到返回 `null`（域层据此改用 spec 的 initial，与上游
+  // `KvUnit.loadAll` 的哨兵语义一致）。
+  listDomainRecords(domain: string): Promise<DomainRecord[]>;
 
-  putWorkspace(id: string, record: WorkspaceRecord): Promise<void>;
+  readDomainGlobal(domain: string): Promise<unknown>;
 
-  deleteWorkspace(id: string): Promise<void>;
+  putDomainRecord(domain: string, table: string, key: string, value: unknown): Promise<void>;
 
-  // 一次批量（上游 `KvUnit.deleteRecords` 的契约：行存储要么一次做完、要么不做）。
-  deleteWorkspaces(ids: readonly string[]): Promise<void>;
-
-  readWorkspaceState(): Promise<WorkspaceDomainState | null>;
-
-  writeWorkspaceState(state: WorkspaceDomainState): Promise<void>;
-
-  // 官方 `schedule` 域的 `tasks` 表：一个提醒一行（key 是 `ScheduleId`）。
-  listScheduleTasks(): Promise<Array<{ id: string; task: ScheduleTask }>>;
+  deleteDomainRecord(domain: string, table: string, key: string): Promise<void>;
 
-  putScheduleTask(id: string, task: ScheduleTask): Promise<void>;
+  // 一次批量（上游 `KvUnit.deleteRecords` 的契约：行存储要么一次做完、要么不做）。
+  deleteDomainRecords(domain: string, table: string, keys: readonly string[]): Promise<void>;
 
-  deleteScheduleTask(id: string): Promise<void>;
+  writeDomainGlobal(domain: string, value: unknown): Promise<void>;
 
-  deleteScheduleTasks(ids: readonly string[]): Promise<void>;
+  // 会话面读 workspace 文档：列表的标题与搜索、删除会话时清理归属。数据只有 `t_storage_records`
+  // 一份，所以这两条走文档（workspace 数量级小，整份读没问题）。
+  listWorkspaceIndex(): Promise<WorkspaceIndexEntry[]>;
 
   loadProjcache(): Promise<StoredProjcacheEntry[]>;
 
-  // 不经 await、直接读的路径（供同步的 `cachedSnapshot` 消费）；宿主提供不了则缺省。
-  readProjcacheDirect?(sessionId: string): StoredProjcacheEntry | undefined;
-
-  readSessionTitleDirect?(sessionId: string): { title: string; seq: number } | undefined;
+  /** 会话标题（投影缓存的镜像刷新与 `cachedSnapshot` 补标题用）。 */
+  readSessionTitle(sessionId: string): Promise<{ title: string; seq: number } | undefined>;
 
   putProjcache(sessionId: string, rows: ProjectionCheckpoint): Promise<void>;
 
+  /** 增量写回：只 upsert `changed` 里的行、删掉 `removedKeys`，其余行原样不动。 */
+  patchProjcache(
+    sessionId: string,
+    changed: ProjectionCheckpoint,
+    removedKeys: readonly string[],
+  ): Promise<void>;
+
   pruneStaleProjcache(): Promise<number>;
 }

package/src/storage-takeover/workspace-documents.ts

@@ -0,0 +1,65 @@
+import { E, type Database } from "@morlay/rdbkit";
+import { storageRecords } from "../entities/index.ts";
+import type { WorkspaceDomainState, WorkspaceRecord } from "./types.ts";
+
+const WORKSPACE_DOMAIN = "workspace";
+const WORKSPACE_TABLE = "workspaces";
+const GLOBAL_TABLE = "";
+
+/**
+ * 删除会话后清掉 workspace 文档里的归属与归档 / 钉住集合。
+ *
+ * 域存储只有 `t_storage_records` 一份，没有再 join 的归属表，所以删除路径得读改文档。调用方保证在
+ * 写事务内：SQLite 用同一连接上的 `Database`，PG 用当前事务的 scoped `Database`。
+ * @param database - 当前执行面（事务内就是 scoped 实例）。
+ * @param ids - 刚删除的会话 id。
+ */
+export async function pruneWorkspaceDocuments(
+  database: Database,
+  ids: readonly string[],
+): Promise<void> {
+  if (ids.length === 0) return;
+  const records = database.table(storageRecords);
+  const scope = E.and(E.eq(records.f_domain, WORKSPACE_DOMAIN), E.eq(records.f_table, WORKSPACE_TABLE));
+  const drop = new Set<string>(ids);
+
+  for await (const row of records
+    .select({ key: records.f_key, value: records.f_value })
+    .where(scope)) {
+    const record = JSON.parse(row.value) as WorkspaceRecord;
+    const kept = record.sessionIds.filter((sessionId) => !drop.has(sessionId));
+    if (kept.length === record.sessionIds.length) continue;
+    await records.update(
+      { f_value: JSON.stringify({ ...record, sessionIds: kept }) },
+      E.and(
+        E.eq(records.f_domain, WORKSPACE_DOMAIN),
+        E.eq(records.f_table, WORKSPACE_TABLE),
+        E.eq(records.f_key, row.key),
+      ),
+    );
+  }
+
+  let globalValue: string | undefined;
+  for await (const row of records
+    .select({ value: records.f_value })
+    .where(E.and(E.eq(records.f_domain, WORKSPACE_DOMAIN), E.eq(records.f_table, GLOBAL_TABLE)))) {
+    globalValue = row.value;
+  }
+  if (globalValue === undefined) return;
+  const state = JSON.parse(globalValue) as WorkspaceDomainState;
+  const archivedSessionIds = state.archivedSessionIds.filter((sessionId) => !drop.has(sessionId));
+  const pinnedSessionIds = (state.pinnedSessionIds ?? []).filter(
+    (sessionId) => !drop.has(sessionId),
+  );
+  if (
+    archivedSessionIds.length === state.archivedSessionIds.length &&
+    pinnedSessionIds.length === (state.pinnedSessionIds ?? []).length
+  ) {
+    return;
+  }
+  const next: WorkspaceDomainState = { ...state, archivedSessionIds, pinnedSessionIds };
+  await records.update(
+    { f_value: JSON.stringify(next) },
+    E.and(E.eq(records.f_domain, WORKSPACE_DOMAIN), E.eq(records.f_table, GLOBAL_TABLE)),
+  );
+}

package/src/storage.ts

@@ -1,3 +1,5 @@
-export * from "./schema.ts";
-export * from "./sqlite.ts";
+export * from "./version.ts";
+export * from "./event-shape.ts";
+export * from "./backend-rdb.ts";
 export * from "./write-guard.ts";
+export type { EventRow, SessionRow } from "./backend.ts";

package/src/testing.ts

@@ -1,6 +1,26 @@
+import type { DatabaseSync } from "node:sqlite";
+import { openSqliteHandle } from "@morlay/rdbkit/testing";
+import { openRdbBackend } from "./db/open.ts";
+import { DEFAULT_BUSY_TIMEOUT_MS, type JournalMode } from "./version.ts";
+
 export type { ContractBackend } from "./testing/contract.ts";
 export { appendLog, meta, oneTurnLog, runPersistenceContract } from "./testing/contract.ts";
 export type { CoordinatorFixture } from "./testing/coordinator-contract.ts";
 export { runCoordinatorContract } from "./testing/coordinator-contract.ts";
 
-export { truncateLiveSession } from "./branch.ts";
+export { truncateLiveSession } from "./branch/index.ts";
+
+/**
+ * 测试辅助：先把库初始化（建表 / 迁移 / 身份），再给一个同步句柄——造损坏数据、读 `PRAGMA` 用。
+ *
+ * 同步口只在测试里存在：生产路径拿到的永远是 `Database`。
+ */
+export async function openInitializedSqlite(
+  path: string,
+  journalMode: JournalMode = "wal",
+  busyTimeout = DEFAULT_BUSY_TIMEOUT_MS,
+): Promise<DatabaseSync> {
+  const backend = await openRdbBackend({ type: "sqlite", path, journalMode, busyTimeout });
+  await backend.close();
+  return openSqliteHandle(path, { journalMode, busyTimeout });
+}

package/src/usage.ts

@@ -1,6 +1,7 @@
 import type { Context } from "@deepseek-ai/cordis";
 import { SESSION_USAGE_PATH } from "./routes.ts";
-import type { SessionPersistenceRdb } from "./index.ts";
+import { mountJsonRoute } from "./http/route.ts";
+import type { SessionPersistenceRdb } from "./session-store.ts";
 
 export { SESSION_USAGE_PATH };
 
@@ -179,69 +180,14 @@ export function addTotals(target: UsageTotals, row: UsageTotals): UsageTotals {
 // 用量统计通道：一次请求回报总览（含 subagent 拆分）、按天 × 模型的桶与按会话的行。
 // 聚合只算被会话引用的事件行——fork 共享行因此只计一次，已删会话留下的孤儿行不计。
 export function registerSessionUsage(ctx: Context, persistence: SessionPersistenceRdb): void {
-  ctx.inject(["webServer", "connection"] as const, (webCtx) => {
-    const webServer = webCtx.webServer as unknown as {
-      register(route: {
-        kind: "exact";
-        path: string;
-        handler: (
-          req: import("node:http").IncomingMessage,
-          res: import("node:http").ServerResponse,
-        ) => void | Promise<void>;
-      }): () => void;
-    };
-    const connection = webCtx.get("connection") as unknown as {
-      requestRejection(request: {
-        headers: import("node:http").IncomingHttpHeaders;
-      }): number | undefined;
-    };
-    return webCtx.effect(
-      () =>
-        webServer.register({
-          kind: "exact",
-          path: SESSION_USAGE_PATH,
-          handler: async (req, res) => {
-            const rejection = connection.requestRejection(req);
-            if (rejection !== undefined) {
-              res.writeHead(rejection);
-              res.end(rejection === 401 ? "unauthorized" : "forbidden");
-              return;
-            }
-            if (req.method !== "POST") {
-              res.writeHead(405, { "content-type": "application/json" });
-              res.end(JSON.stringify({ error: "method not allowed" }));
-              return;
-            }
-            const chunks: Buffer[] = [];
-            for await (const chunk of req) chunks.push(chunk as Buffer);
-            const raw = Buffer.concat(chunks).toString("utf8");
-            let envelope: { range?: unknown } = {};
-            if (raw !== "") {
-              try {
-                envelope = JSON.parse(raw) as { range?: unknown };
-              } catch {
-                res.writeHead(400, { "content-type": "application/json" });
-                res.end(JSON.stringify({ error: "request body is not JSON" }));
-                return;
-              }
-            }
-            try {
-              const report = await persistence.usageReport(
-                resolveUsageSince(parseUsageRange(envelope.range), Date.now()),
-              );
-              res.writeHead(200, { "content-type": "application/json" });
-              res.end(JSON.stringify(report));
-            } catch (error: unknown) {
-              res.writeHead(500, { "content-type": "application/json" });
-              res.end(
-                JSON.stringify({
-                  error: error instanceof Error ? error.message : "usage report failed",
-                }),
-              );
-            }
-          },
-        }),
-      `session-rdb: ${SESSION_USAGE_PATH} route`,
-    );
+  mountJsonRoute(ctx, {
+    path: SESSION_USAGE_PATH,
+    handle: async (body) => {
+      const { range } = body as { range?: unknown };
+      const report = await persistence.usageReport(
+        resolveUsageSince(parseUsageRange(range), Date.now()),
+      );
+      return { body: report };
+    },
   });
 }

package/src/version.ts

@@ -0,0 +1,13 @@
+/** 库结构版本（写入 SQLite 的 `user_version`，不匹配即拒绝打开）。 */
+export const SCHEMA_VERSION = 3;
+
+/** SQLite 文件头的 application id（`0x44534850` = "DSHP"），防止误开别的库。 */
+export const SESSION_PERSISTENCE_SQLITE_APPLICATION_ID = 0x44534850;
+
+/** 事件 `f_data` 的编码（目前只有 JSON）。 */
+export const EVENT_ENCODING = "json";
+
+export type JournalMode = "wal" | "delete" | "truncate" | "persist";
+
+/** SQLite 的默认 busy timeout（毫秒）。 */
+export const DEFAULT_BUSY_TIMEOUT_MS = 5000;