@morlay/session-rdb 0.0.16 → 0.0.18

package/src/storage-takeover/repository.ts

@@ -0,0 +1,420 @@
+/**
+ * storages 接管表的方言无关实现：SQLite 与 PostgreSQL 的 drizzle 查询构建器
+ * 共享同一套调用形状（SQLite 走同步 `.all()`/`.get()`/`.run()`，PostgreSQL
+ * 走 thenable），差别由本模块的执行 helper 吸收。
+ *
+ * workspace 域是权威数据：记录、归属、显示顺序与归档集都拆成语义表，每次写入
+ * 在介质事务内完成（`host.writeAtomically`），不留部分应用的中间态。
+ */
+
+import { and, eq, gte, isNotNull, notInArray, sql } from "drizzle-orm";
+import { SessionId, SessionLogOffset, SessionSeq } from "@deepseek-ai/dsh-session";
+import type { SessionSeqCursor } from "@deepseek-ai/dsh-session";
+import type { WorkspaceId } from "@deepseek-ai/dsh-workspace";
+import type {
+  CheckpointIdentity,
+  ProjectionCheckpoint,
+  ProjectionCheckpointRow,
+  StorageRepository,
+  StoredProjcacheEntry,
+  WorkspaceDomainState,
+  WorkspaceRecord,
+} from "./types.ts";
+
+/** 注入口：介质句柄 + 方言表对象 + 事务。 */
+export interface StorageRepositoryHost {
+  /** 解析 drizzle 句柄；介质未就绪时调用方等待其 open 完成。 */
+  db: () => Promise<unknown>;
+  /**
+   * 同步驱动的 drizzle 句柄（SQLite）。缺席时 {@link StorageRepository.readProjcacheSync}
+   * 不提供：异步驱动（PostgreSQL）没有同步读，调用方只能维护写穿镜像。
+   * @returns the open drizzle handle.
+   */
+  dbSync?: () => unknown;
+  /** `toSqliteSchema` / `toPostgresSchema` 产出的方言表对象。 */
+  tables: Record<string, unknown>;
+  /**
+   * Run `fn` inside one medium transaction: every statement issued through
+   * {@link StorageRepositoryHost.db} while it runs joins that transaction, and
+   * a failure rolls the whole write back.
+   * @param fn - statements to run atomically.
+   * @returns the callback's result.
+   */
+  writeAtomically: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+
+/** 多行查询：SQLite 同步 `.all()`，PostgreSQL await。 */
+async function allRows<T>(query: unknown): Promise<T[]> {
+  const q = query as { all?: () => T[] };
+  if (typeof q.all === "function") return q.all();
+  return (await query) as T[];
+}
+
+/** 单行查询：SQLite 同步 `.get()`，PostgreSQL await 后取首行。 */
+async function oneRow<T>(query: unknown): Promise<T | undefined> {
+  const q = query as { get?: () => T | undefined };
+  if (typeof q.get === "function") return q.get();
+  const rows = (await query) as T[];
+  return rows[0];
+}
+
+/** 写入语句：SQLite 同步 `.run()`，PostgreSQL await。 */
+async function runQuery(query: unknown): Promise<void> {
+  const q = query as { run?: () => unknown };
+  if (typeof q.run === "function") {
+    q.run();
+    return;
+  }
+  await query;
+}
+
+/** `t_sessions` 上承载 checkpoint identity 的列（与投影行 1:1，不另存一份）。 */
+interface SessionIdentityRow {
+  fVersion: number;
+  fCreatedAt: number;
+  fCwd: string | null;
+  fSeedLength: number | null;
+}
+
+/** `t_session_projcache_row` 的行形状（存储层视角）。 */
+interface ProjcacheRowRecord {
+  fSessionId: string;
+  fKey: string;
+  fVer: number;
+  fSeq: number;
+  fVal: string;
+}
+
+/** 一行会话元数据 → 上游 `CheckpointIdentity`。 */
+function identityOfSession(row: SessionIdentityRow): CheckpointIdentity {
+  return {
+    formatVersion: row.fVersion,
+    createdAt: row.fCreatedAt,
+    ...(row.fCwd === null ? {} : { cwd: row.fCwd }),
+    isSeeded: row.fSeedLength !== null,
+    ...(row.fSeedLength === null
+      ? {}
+      : { inheritedEventCount: SessionLogOffset(row.fSeedLength) }),
+  };
+}
+
+/** 存储的整数水位 → 上游 seq cursor（-1 是空日志哨兵）。 */
+function seqCursor(seq: number): SessionSeqCursor {
+  return seq === -1 ? -1 : SessionSeq(seq);
+}
+
+/** 两写标记的两列 → 上游 `pendingMutation`（未知操作按缺失处理）。 */
+function pendingMutationOf(row: {
+  fPendingOperation: string | null;
+  fPendingWorkspaceId: string | null;
+}): WorkspaceDomainState["pendingMutation"] {
+  const operation = row.fPendingOperation;
+  if (operation !== "create" && operation !== "delete") return undefined;
+  return { operation, workspaceId: (row.fPendingWorkspaceId ?? "") as WorkspaceId };
+}
+
+/**
+ * 构建一个介质的 storages 接管访问层。
+ * @param host - 介质句柄、方言表对象与事务执行器。
+ * @returns 方言无关的访问层。
+ */
+export function createStorageRepository(host: StorageRepositoryHost): StorageRepository {
+  /* eslint-disable @typescript-eslint/no-explicit-any -- drizzle 双方言表对象只在运行期共享查询形状 */
+  const tables = host.tables as Record<string, any>;
+  const tUnits = tables["t_storage_units"]!;
+  const tSessions = tables["t_sessions"]!;
+  const tWorkspaces = tables["t_workspaces"]!;
+  const tWorkspaceSessions = tables["t_workspace_sessions"]!;
+  const tWorkspaceState = tables["t_workspace_state"]!;
+  const tProjcacheRows = tables["t_session_projcache_row"]!;
+  /** checkpoint identity 的列投影：直接复用会话行，不再单存记录头。 */
+  const sessionIdentity = {
+    fSessionId: tSessions.fSessionId,
+    fVersion: tSessions.fVersion,
+    fCreatedAt: tSessions.fCreatedAt,
+    fCwd: tSessions.fCwd,
+    fSeedLength: tSessions.fSeedLength,
+  };
+  /* eslint-enable @typescript-eslint/no-explicit-any */
+
+  const dbx = async (): Promise<any> => (await host.db()) as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  return {
+    async readUnitVersion(name: string): Promise<number | undefined> {
+      const db = await dbx();
+      const row = await oneRow<{ fVersion: number }>(
+        db.select().from(tUnits).where(eq(tUnits.fName, name)),
+      );
+      return row?.fVersion;
+    },
+
+    async insertUnitVersion(name: string, version: number): Promise<void> {
+      const db = await dbx();
+      await runQuery(
+        db.insert(tUnits).values({ fName: name, fVersion: version }).onConflictDoNothing(),
+      );
+    },
+
+    async listWorkspaces(): Promise<Array<{ id: string; record: WorkspaceRecord }>> {
+      const db = await dbx();
+      const rows = await allRows<{
+        fWorkspaceId: string;
+        fPath: string;
+        fTitle: string;
+        fCreatedAt: string;
+        fUpdatedAt: string;
+      }>(db.select().from(tWorkspaces));
+      const links = await allRows<{
+        fWorkspaceId: string;
+        fSessionId: string;
+        fPosition: number;
+      }>(db.select().from(tWorkspaceSessions));
+      const sessions = new Map<string, Array<{ id: string; position: number }>>();
+      for (const link of links) {
+        const owned = sessions.get(link.fWorkspaceId) ?? [];
+        owned.push({ id: link.fSessionId, position: link.fPosition });
+        sessions.set(link.fWorkspaceId, owned);
+      }
+      return rows.map((row) => ({
+        id: row.fWorkspaceId,
+        record: {
+          path: row.fPath,
+          title: row.fTitle,
+          sessionIds: (sessions.get(row.fWorkspaceId) ?? [])
+            .sort((left, right) => left.position - right.position)
+            .map((entry) => SessionId(entry.id)),
+          createdAt: row.fCreatedAt,
+          updatedAt: row.fUpdatedAt,
+        },
+      }));
+    },
+
+    async putWorkspace(id: string, record: WorkspaceRecord): Promise<void> {
+      await host.writeAtomically(async () => {
+        const db = await dbx();
+        const values = {
+          fWorkspaceId: id,
+          fPath: record.path,
+          fTitle: record.title,
+          fCreatedAt: record.createdAt,
+          fUpdatedAt: record.updatedAt,
+        };
+        await runQuery(
+          db
+            .insert(tWorkspaces)
+            .values(values)
+            .onConflictDoUpdate({ target: tWorkspaces.fWorkspaceId, set: values }),
+        );
+        // 归属整体替换：DELETE + 有序 INSERT 在同一事务内，读不到中间态。
+        await runQuery(
+          db.delete(tWorkspaceSessions).where(eq(tWorkspaceSessions.fWorkspaceId, id)),
+        );
+        const links = record.sessionIds.map((sessionId, position) => ({
+          fWorkspaceId: id,
+          fSessionId: sessionId,
+          fPosition: position,
+        }));
+        if (links.length > 0) await runQuery(db.insert(tWorkspaceSessions).values(links));
+      });
+    },
+
+    async deleteWorkspace(id: string): Promise<void> {
+      await host.writeAtomically(async () => {
+        const db = await dbx();
+        await runQuery(
+          db.delete(tWorkspaceSessions).where(eq(tWorkspaceSessions.fWorkspaceId, id)),
+        );
+        await runQuery(db.delete(tWorkspaces).where(eq(tWorkspaces.fWorkspaceId, id)));
+      });
+    },
+
+    async readWorkspaceState(): Promise<WorkspaceDomainState | null> {
+      const db = await dbx();
+      const row = await oneRow<{
+        fInitialized: number;
+        fPendingOperation: string | null;
+        fPendingWorkspaceId: string | null;
+      }>(db.select().from(tWorkspaceState).where(eq(tWorkspaceState.fSingleton, 1)));
+      if (row === undefined) return null;
+      const ordered = await allRows<{ fWorkspaceId: string }>(
+        db
+          .select()
+          .from(tWorkspaces)
+          .where(gte(tWorkspaces.fPosition, 0))
+          .orderBy(tWorkspaces.fPosition),
+      );
+      const archives = await allRows<{ fSessionId: string }>(
+        db
+          .select({ fSessionId: tSessions.fSessionId })
+          .from(tSessions)
+          .where(isNotNull(tSessions.fArchivedAt))
+          .orderBy(tSessions.fArchivedAt),
+      );
+      const pendingMutation = pendingMutationOf(row);
+      return {
+        initialized: row.fInitialized !== 0,
+        workspaceIds: ordered.map((entry) => entry.fWorkspaceId as WorkspaceId),
+        archivedSessionIds: archives.map((entry) => entry.fSessionId as SessionId),
+        ...(pendingMutation === undefined ? {} : { pendingMutation }),
+      };
+    },
+
+    async writeWorkspaceState(state: WorkspaceDomainState): Promise<void> {
+      await host.writeAtomically(async () => {
+        const db = await dbx();
+        const pending = state.pendingMutation as
+          | { operation?: unknown; workspaceId?: unknown }
+          | undefined;
+        const values = {
+          fSingleton: 1,
+          fInitialized: state.initialized ? 1 : 0,
+          fPendingOperation:
+            pending === undefined || typeof pending.operation !== "string"
+              ? null
+              : pending.operation,
+          fPendingWorkspaceId:
+            pending === undefined || typeof pending.workspaceId !== "string"
+              ? null
+              : pending.workspaceId,
+        };
+        await runQuery(
+          db
+            .insert(tWorkspaceState)
+            .values(values)
+            .onConflictDoUpdate({ target: tWorkspaceState.fSingleton, set: values }),
+        );
+        // 显示顺序整体替换：先清位，再按数组顺序定位（不在集合里的记录保持 -1）。
+        await runQuery(db.update(tWorkspaces).set({ fPosition: -1 }));
+        for (const [position, workspaceId] of state.workspaceIds.entries()) {
+          await runQuery(
+            db
+              .update(tWorkspaces)
+              .set({ fPosition: position })
+              .where(eq(tWorkspaces.fWorkspaceId, workspaceId)),
+          );
+        }
+        // 归档集整体替换：标记落在会话行（f_archived_at），未列出的会话清空标记。
+        const archived = state.archivedSessionIds;
+        await runQuery(
+          archived.length === 0
+            ? db
+                .update(tSessions)
+                .set({ fArchivedAt: null })
+                .where(isNotNull(tSessions.fArchivedAt))
+            : db
+                .update(tSessions)
+                .set({ fArchivedAt: null })
+                .where(
+                  and(
+                    isNotNull(tSessions.fArchivedAt),
+                    notInArray(tSessions.fSessionId, archived),
+                  ),
+                ),
+        );
+        const stamp = Date.now();
+        for (const sessionId of archived) {
+          // 首次归档时间保留：重复写入同一集合不刷新标记。
+          await runQuery(
+            db
+              .update(tSessions)
+              .set({ fArchivedAt: sql`COALESCE(${tSessions.fArchivedAt}, ${stamp})` })
+              .where(eq(tSessions.fSessionId, sessionId)),
+          );
+        }
+      });
+    },
+
+    async loadProjcache(): Promise<StoredProjcacheEntry[]> {
+      const db = await dbx();
+      const rows = await allRows<ProjcacheRowRecord>(db.select().from(tProjcacheRows));
+      if (rows.length === 0) return [];
+      const sessions = await allRows<SessionIdentityRow & { fSessionId: string }>(
+        db.select(sessionIdentity).from(tSessions),
+      );
+      const entries = new Map<string, StoredProjcacheEntry>();
+      for (const session of sessions) {
+        entries.set(session.fSessionId, {
+          sessionId: SessionId(session.fSessionId),
+          identity: identityOfSession(session),
+          rows: {},
+        });
+      }
+      for (const row of rows) {
+        // 没有会话行的行读作缺失：checkpoint 的 identity 由会话行承载。
+        const entry = entries.get(row.fSessionId);
+        if (entry === undefined) continue;
+        entry.rows[row.fKey] = {
+          ver: row.fVer,
+          seq: seqCursor(row.fSeq),
+          val: JSON.parse(row.fVal),
+        } satisfies ProjectionCheckpointRow;
+      }
+      // 没有投影行的会话没有 checkpoint（避免把空记录装进异步镜像）。
+      return [...entries.values()].filter((entry) => Object.keys(entry.rows).length > 0);
+    },
+
+    async putProjcache(
+      sessionId: string,
+      rows: ProjectionCheckpoint,
+    ): Promise<void> {
+      await host.writeAtomically(async () => {
+        const db = await dbx();
+        await runQuery(db.delete(tProjcacheRows).where(eq(tProjcacheRows.fSessionId, sessionId)));
+        const values = Object.entries(rows).map(([key, row]) => ({
+          fSessionId: sessionId,
+          fKey: key,
+          fVer: row.ver,
+          fSeq: row.seq,
+          fVal: JSON.stringify(row.val),
+        }));
+        if (values.length > 0) await runQuery(db.insert(tProjcacheRows).values(values));
+      });
+    },
+
+    async deleteProjcache(sessionId: string): Promise<void> {
+      const db = await dbx();
+      await runQuery(db.delete(tProjcacheRows).where(eq(tProjcacheRows.fSessionId, sessionId)));
+    },
+
+    // 同步驱动（SQLite）才有：读路径直接查介质，进程内不维护 checkpoint 镜像。
+    ...(host.dbSync === undefined
+      ? {}
+      : {
+          readProjcacheSync: (sessionId: string): StoredProjcacheEntry | undefined => {
+            const db = host.dbSync!() as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+            const stored = db
+              .select()
+              .from(tProjcacheRows)
+              .where(eq(tProjcacheRows.fSessionId, sessionId))
+              .all() as ProjcacheRowRecord[];
+            if (stored.length === 0) return undefined;
+            const session = db
+              .select(sessionIdentity)
+              .from(tSessions)
+              .where(eq(tSessions.fSessionId, sessionId))
+              .get() as (SessionIdentityRow & { fSessionId: string }) | undefined;
+            // 没有会话行（未物化或已删）就没有可校验的 identity → 读作缺失。
+            if (session === undefined) return undefined;
+            const rows: ProjectionCheckpoint = {};
+            for (const row of stored) {
+              rows[row.fKey] = {
+                ver: row.fVer,
+                seq: seqCursor(row.fSeq),
+                val: JSON.parse(row.fVal),
+              };
+            }
+            return { sessionId: SessionId(sessionId), identity: identityOfSession(session), rows };
+          },
+          readSessionTitleSync: (sessionId: string): { title: string; seq: number } | undefined => {
+            const db = host.dbSync!() as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+            const row = db
+              .select({ fTitle: tSessions.fTitle, fTitleSeq: tSessions.fTitleSeq })
+              .from(tSessions)
+              .where(eq(tSessions.fSessionId, sessionId))
+              .get() as { fTitle: string | null; fTitleSeq: number | null } | undefined;
+            if (row === undefined || row.fTitle === null || row.fTitleSeq === null) return undefined;
+            return { title: row.fTitle, seq: row.fTitleSeq };
+          },
+        }),
+  };
+}

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

@@ -0,0 +1,177 @@
+/**
+ * storages 接管：注册在 storage hub 上的 `rdb` KV 后端。它把 workspace 域
+ * （上游 single 布局：一张 `workspaces` 表 + global 单例）映射到 session-rdb
+ * 的语义专用表，与事件日志同库同连接；域层（`ctx.storageDomain`）通过
+ * `routes` 把 `workspace` 域路由到本后端。
+ *
+ * 本后端只服务已知域的专用表：未知 unit 名 fail loud，而不是静默落到通用
+ * 存储——表结构是显式维护的（见 docs/schema.md）。
+ */
+
+import { StorageError } from "@deepseek-ai/dsh-storage";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+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";
+
+/** 注册到 storage hub 的后端名（storage-domain 的 routes 引用它）。 */
+export const RDB_STORAGE_BACKEND = "rdb";
+
+/** 本后端唯一服务的域：上游 `workspaceDomainSpec`（v2，single 布局）。 */
+const WORKSPACE_UNIT = "workspace";
+const WORKSPACE_TABLE = "workspaces";
+
+/** 只服务 workspace 域的 KV 后端。 */
+export class RdbStorageBackend implements StorageBackend {
+  readonly kv: KvFacet = { open: (descriptor) => this.openUnit(descriptor) };
+
+  /** 已打开（或打开中）的 unit 名；重复 open 是调用方 bug。 */
+  private readonly open = new Set<string>();
+  private closed = false;
+
+  /**
+   * @param repository - storages 接管表访问层（与事件日志同介质）。
+   */
+  constructor(private readonly repository: StorageRepository) {}
+
+  private async openUnit(descriptor: KvUnitDescriptor): Promise<KvUnit> {
+    if (this.closed) throw new StorageError("closed", "rdb storage backend is closed");
+    if (descriptor.name !== WORKSPACE_UNIT) {
+      throw new Error(
+        `rdb storage backend serves only the '${WORKSPACE_UNIT}' domain (requested '${descriptor.name}')`,
+      );
+    }
+    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)`,
+      );
+    }
+    if (this.open.has(descriptor.name)) {
+      throw new Error(`kv unit '${descriptor.name}' is already open (double-open is a caller bug)`);
+    }
+    const stored = await this.repository.readUnitVersion(descriptor.name);
+    if (stored === undefined) {
+      await this.repository.insertUnitVersion(descriptor.name, descriptor.version);
+    } else if (stored !== descriptor.version) {
+      throw new StorageError(
+        "version-mismatch",
+        `kv unit '${descriptor.name}' is stamped version ${stored} on the medium, ` +
+          `incompatible with descriptor version ${descriptor.version}`,
+      );
+    }
+    this.open.add(descriptor.name);
+    return new WorkspaceKvUnit(this.repository, descriptor, () => {
+      this.open.delete(descriptor.name);
+    });
+  }
+
+  /**
+   * Release the backend. The medium (the session database) belongs to the
+   * owning session-rdb plugin, so closing open units here does not close it.
+   * @returns resolution after the name table is cleared.
+   */
+  async close(): Promise<void> {
+    this.closed = true;
+    this.open.clear();
+  }
+}
+
+/** workspace 域的 KV unit：每个原语一条 SQL 语句，值形状与上游记录一致。 */
+class WorkspaceKvUnit implements KvUnit {
+  private closed = false;
+
+  constructor(
+    private readonly repository: StorageRepository,
+    private readonly descriptor: KvUnitDescriptor,
+    private readonly onClose: () => void,
+  ) {}
+
+  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 state = await this.repository.readWorkspaceState();
+    return { tables: { [WORKSPACE_TABLE]: records }, global: state };
+  }
+
+  async putRecord(table: string, key: string, value: unknown): Promise<void> {
+    this.assertOpen();
+    this.assertTable(table);
+    await this.repository.putWorkspace(key, workspaceRecordOf(value));
+  }
+
+  async deleteRecord(table: string, key: string): Promise<void> {
+    this.assertOpen();
+    this.assertTable(table);
+    await this.repository.deleteWorkspace(key);
+  }
+
+  async setGlobal(value: unknown): Promise<void> {
+    this.assertOpen();
+    await this.repository.writeWorkspaceState(workspaceStateOf(value));
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    this.onClose();
+  }
+
+  private assertOpen(): void {
+    if (this.closed) {
+      throw new StorageError("closed", `kv unit '${this.descriptor.name}' is closed`);
+    }
+  }
+
+  private assertTable(table: string): void {
+    if (table !== WORKSPACE_TABLE) {
+      throw new Error(`unit '${this.descriptor.name}' does not declare table '${table}'`);
+    }
+  }
+}
+
+/** Narrow one opaque KV record to the workspace record the domain shipped. */
+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,
+  };
+}
+
+/** Narrow one opaque KV global to the workspace registry state the domain shipped. */
+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)
+  ) {
+    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),
+    ...(state.pendingMutation === undefined ? {} : { pendingMutation: state.pendingMutation }),
+  };
+}

package/src/storage-takeover/types.ts

@@ -0,0 +1,82 @@
+/**
+ * storages 接管的类型：**能复用上游契约的一律复用**——记录形状来自上游
+ * domain/projection 的 `z.infer` 产物（`WorkspaceRecord` / `WorkspaceDomainState`
+ * / `CheckpointIdentity` / `ProjectionCheckpoint`），本文件只声明存储层的访问
+ * 接口与"上游类型 + 会话键"的组合。上游 spec 变化时这里直接编译报错，不会
+ * 静默偏移。
+ *
+ * 这些 import 全是类型导入（无运行时依赖）：rdb 是通用插件，不能硬依赖
+ * web 层的 workspace 包或已被替换的 projcache 包。
+ */
+
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { CheckpointIdentity } from "@deepseek-ai/dsh-session-projection-cache";
+import type { ProjectionCheckpoint, ProjectionCheckpointRow } from "@deepseek-ai/dsh-session-projection";
+import type { WorkspaceDomainState, WorkspaceRecord } from "@deepseek-ai/dsh-workspace";
+
+export type {
+  CheckpointIdentity,
+  ProjectionCheckpoint,
+  ProjectionCheckpointRow,
+  WorkspaceDomainState,
+  WorkspaceRecord,
+};
+
+/**
+ * 一个会话的完整 checkpoint：上游 `CheckpointIdentity`（日志身份，唯一权威定义
+ * 在被替换的 projcache spec 里）+ 上游 `ProjectionCheckpoint`（逐 key 行）+ 会话键。
+ */
+export interface StoredProjcacheEntry {
+  sessionId: SessionId;
+  identity: CheckpointIdentity;
+  rows: ProjectionCheckpoint;
+}
+
+/**
+ * storages 接管表的方言无关访问层：SQLite 与 PostgreSQL 两个 Backend 各提供
+ * 同一实现，调用方（KV 后端与投影缓存服务）不感知介质差异。读方法返回持久
+ * 值的语义视图，workspace 的写入在介质事务内整体替换。
+ */
+export interface StorageRepository {
+  /** 读一个域的版本戳；域从未打开时 undefined。 */
+  readUnitVersion(name: string): Promise<number | undefined>;
+  /** 写入域的首次版本戳；已存在时保持原值。 */
+  insertUnitVersion(name: string, version: number): Promise<void>;
+  /** 读全部 workspace 记录（按 workspace id）。 */
+  listWorkspaces(): Promise<Array<{ id: string; record: WorkspaceRecord }>>;
+  /** 覆盖写一条 workspace 记录（含归属行）。 */
+  putWorkspace(id: string, record: WorkspaceRecord): Promise<void>;
+  /** 删除一条 workspace 记录（缺失为 no-op）。 */
+  deleteWorkspace(id: string): Promise<void>;
+  /** 读 workspace 单例；从未写入时 null。 */
+  readWorkspaceState(): Promise<WorkspaceDomainState | null>;
+  /** 覆盖写 workspace 单例（显示顺序与归档集一并整体替换）。 */
+  writeWorkspaceState(state: WorkspaceDomainState): Promise<void>;
+  /** 读全部投影 checkpoint（含逐 key 行）。 */
+  loadProjcache(): Promise<StoredProjcacheEntry[]>;
+  /**
+   * 同步读一个会话的 checkpoint：只有同步驱动（SQLite）提供，读路径直接落到
+   * 介质；异步驱动（PostgreSQL）缺席，调用方退化为写穿镜像。上游的
+   * `cachedSnapshot` 系列是同步签名，这里的存在性就是"能否直读库"的开关。
+   * @param sessionId - 会话 id。
+   * @returns 该会话的 checkpoint，缺失时 `undefined`。
+   */
+  readProjcacheSync?(sessionId: string): StoredProjcacheEntry | undefined;
+  /**
+   * 同步读一个会话的标题列（`t_sessions.f_title` / `f_title_seq`，rdb 写路径与
+   * rewind 维护）：只有同步驱动提供，列表消费直接取会话数据，不依赖 checkpoint
+   * 行是否存在。
+   * @param sessionId - 会话 id。
+   * @returns 标题与其事件 seq，未写过标题时 `undefined`。
+   */
+  readSessionTitleSync?(sessionId: string): { title: string; seq: number } | undefined;
+  /**
+   * 覆盖写一个会话的 checkpoint 行（先清旧行再写新行，同一事务）。记录头
+   * 不在这里：它与 `t_sessions` 行 1:1，identity 直接复用该行的列。
+   * @param sessionId - 会话 id。
+   * @param rows - 每个投影 key 一行。
+   */
+  putProjcache(sessionId: string, rows: ProjectionCheckpoint): Promise<void>;
+  /** 删除一个会话的 checkpoint（缺失为 no-op）。 */
+  deleteProjcache(sessionId: string): Promise<void>;
+}