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

package/src/storage-takeover/projection-cache.ts

@@ -1,15 +1,3 @@
-/**
- * 投影 checkpoint 服务（`ctx.sessionProjectionCache`）的 rdb 实现：替换上游
- * `@deepseek-ai/dsh-session-projection-cache` 插件，公开面与语义逐一对齐
- * （cachedSnapshot / cachedPredecessorTitle / hydratePrepared / write /
- * coldSnapshot，以及三个强制写点与计数/定时节流），持久层换成 session-rdb
- * 的语义专用表 `t_session_projcache` / `t_session_projcache_row`。
- *
- * 读方法是同步签名（session 列表在请求路径上直接调用），所以服务持有启动时
- * 从表中加载的内存 checkpoint 表；写先落库、后更新内存，保证读到的内存值
- * 磁盘上一定存在。
- */
-
 import { Context, Service } from "@deepseek-ai/cordis";
 import { SessionLogOffset } from "@deepseek-ai/dsh-session";
 import type {
@@ -31,79 +19,55 @@ import type {
   ProjectionCheckpointRow,
 } from "./types.ts";
 
-/** 服务注册名（与上游插件一致，消费者经 `ctx.get` 解析）。 */
 export const SESSION_PROJECTION_CACHE_SERVICE = "sessionProjectionCache";
 
-/** 完整身份：当前世代写入的字段都必需。 */
 type CurrentCheckpointIdentity = CheckpointIdentity & {
   formatVersion: number;
   isSeeded: boolean;
   inheritedEventCount: number;
 };
 
-/** 缓存写节流参数（上游 Config 的部署值）。 */
 export interface ProjectionCacheConfig {
-  /** 两次强制点之间，累积多少个已提交事件强制落一次盘。 */
   writeEveryEvents: number;
-  /** 脏 checkpoint 在强制点之间允许滞留的最长毫秒数。 */
+
   writeIntervalMs: number;
 }
 
-/** class-plugin 装载参数：写节流 + storages 接管访问层 + 介质就绪信号。 */
 export interface SessionProjectionCacheRdbOptions extends ProjectionCacheConfig {
   repository: StorageRepository;
   ready: Promise<unknown>;
 }
 
-/** 每会话写回节流簿记（只对 live session）。 */
 interface DirtyState {
   pending: number;
   timer: ReturnType<typeof setTimeout> | undefined;
 }
 
-/** 只认 title 的前代提示（与上游一致）。 */
 const PREDECESSOR_TITLE_KEY = "title" as Extract<keyof SessionProjectionMap, string>;
 
-/** rdb 持久化的投影 checkpoint 服务：同步驱动直读介质，异步驱动用写穿镜像支撑同步签名。 */
 export class SessionProjectionCacheRdb extends Service {
   static inject = ["sessionProjections", "sessions"];
 
-  /** 异步驱动（PostgreSQL）的同步读镜像：同步驱动（SQLite）直读介质，这里恒为空。 */
   private readonly records = new Map<SessionId, StoredProjcacheEntry>();
   private readonly dirty = new Map<Session, DirtyState>();
-  /** 读路径是否直读介质（`readProjcacheSync` 存在即同步驱动）。 */
+
   private readonly directReads: boolean;
   private readonly config: ProjectionCacheConfig;
   private readonly repository: StorageRepository;
   private readonly ready: Promise<unknown>;
 
-  /**
-   * 本类按 cordis class plugin 装载（`ctx.plugin(SessionProjectionCacheRdb, options)`）：
-   * `static inject` 等依赖就绪后构造，构造后框架调用 `[Service.init]` 安装写入
-   * 路径——直接 `new` 不会触发 init，写入路径会静默缺失。
-   * @param ctx - 插件上下文（已注入 sessionProjections 与 sessions）。
-   * @param options - 写节流 + storages 接管访问层 + 介质就绪信号。
-   */
   constructor(ctx: Context, options: SessionProjectionCacheRdbOptions) {
     super(ctx, SESSION_PROJECTION_CACHE_SERVICE);
     this.config = options;
     this.repository = options.repository;
     this.ready = options.ready;
-    this.directReads = options.repository.readProjcacheSync !== undefined;
+    this.directReads = options.repository.readProjcacheDirect !== undefined;
   }
 
-  /**
-   * Install the write path before the async medium wait: listeners must exist
-   * from plugin activation on, or sessions created while the medium settles
-   * lose their mandatory checkpoints. Only the async driver needs the startup
-   * mirror; the sync driver serves every read from the table.
-   */
   protected async [Service.init](): Promise<void> {
     this.installWritePath();
     await this.ready;
-    // 一次性清理旧版写入路径留下的陈旧行（水位为负却已有事件）：这些行会把
-    // 有对话的会话在 cold 列表里误判为空白。缓存是派生数据，删除让会话回到
-    // 「未知即可见」，等待下一次强制点重写。
+
     const pruned = await this.repository.pruneStaleProjcache();
     if (pruned > 0) {
       this.ctx.logger.info(
@@ -117,21 +81,11 @@ export class SessionProjectionCacheRdb extends Service {
     }
   }
 
-  /** Read one session's stored record: straight from the medium, or from the async mirror. */
   private lookup(id: SessionId): StoredProjcacheEntry | undefined {
-    if (this.directReads) return this.repository.readProjcacheSync?.(id);
+    if (this.directReads) return this.repository.readProjcacheDirect?.(id);
     return this.records.get(id);
   }
 
-  /**
-   * The stored record for one session, accepted only when its bound log
-   * identity matches `expected`. A session id names a slot, not a lifecycle:
-   * a recreated id or a persistence store swapped under a surviving cache
-   * must not let an old record seed state folded from an unrelated log.
-   * @param id - the session whose record is read.
-   * @param expected - the log identity the caller holds (live or stored header).
-   * @returns the identity-matching record, or `undefined` (absent or unrelated).
-   */
   private recordFor(
     id: SessionId,
     expected: CurrentCheckpointIdentity,
@@ -141,14 +95,6 @@ export class SessionProjectionCacheRdb extends Service {
     return identityMatches(record.identity, expected) ? record : undefined;
   }
 
-  /**
-   * The cached projection cut for one stored (cold) or live header.
-   * @param meta - authoritative Session header.
-   * @param inheritedEventCount - exact inherited cut completing the lifecycle identity.
-   * @param keys - optional projection keys required by the caller's audience.
-   * @returns the cut (`asOfSeq` = lowest served-row watermark), or `undefined`
-   *   when no usable row exists for this lifecycle.
-   */
   cachedSnapshot(
     meta: SessionHeader,
     inheritedEventCount: SessionLogOffset,
@@ -159,10 +105,6 @@ export class SessionProjectionCacheRdb extends Service {
     return this.withDirectTitle(meta.id, keys, snapshot);
   }
 
-  /**
-   * 标题是会话数据本身（`t_sessions.f_title`，由 rdb 写路径与 rewind 维护）：
-   * checkpoint 行里没有 title 时直接取该列，列表消费不依赖缓存行是否存在。
-   */
   private withDirectTitle(
     id: SessionId,
     keys: readonly Extract<keyof SessionProjectionMap, string>[] | undefined,
@@ -172,23 +114,15 @@ export class SessionProjectionCacheRdb extends Service {
       return snapshot;
     }
     if (snapshot?.values[PREDECESSOR_TITLE_KEY] !== undefined) return snapshot;
-    const direct = this.repository.readSessionTitleSync?.(id);
+    const direct = this.repository.readSessionTitleDirect?.(id);
     if (direct === undefined) return snapshot;
     const values = { ...snapshot?.values, [PREDECESSOR_TITLE_KEY]: direct.title };
-    // 水位取最低（under-claim 安全）：已有块的水位与直取行取小。
+
     const asOfSeq =
       snapshot === undefined ? direct.seq : Math.min(snapshot.asOfSeq as number, direct.seq);
     return { asOfSeq: asOfSeq as SessionSeqCursor, values };
   }
 
-  /**
-   * Read only a predecessor checkpoint's title as a zero-I/O listing hint.
-   * @param meta - authoritative listed Session header.
-   * @param inheritedEventCount - exact inherited cut completing the lifecycle identity.
-   * @returns a title-only checkpoint view with `asOfSeq: -1`, or `undefined`
-   *   when the record is current, newer, unrelated, missing, or incompatible
-   *   with the title unit.
-   */
   cachedPredecessorTitle(
     meta: SessionHeader,
     inheritedEventCount: SessionLogOffset,
@@ -202,7 +136,6 @@ export class SessionProjectionCacheRdb extends Service {
     return title === undefined ? undefined : { ...title, asOfSeq: -1 };
   }
 
-  /** View selected wire rows and bind them to their lowest served watermark. */
   private viewRecord(
     record: StoredProjcacheEntry,
     keys?: readonly Extract<keyof SessionProjectionMap, string>[],
@@ -213,9 +146,7 @@ export class SessionProjectionCacheRdb extends Service {
     );
     const servedKeys = Object.keys(values);
     if (servedKeys.length === 0) return undefined;
-    // The block carries ONE cut: the lowest served watermark is the seq every
-    // value is at least current as of (under-claiming is safe under
-    // higher-seq-wins; over-claiming would let a stale value outrank pushes).
+
     const firstKey = servedKeys[0] as string;
     let asOfSeq = (record.rows[firstKey] as ProjectionCheckpointRow).seq as SessionSeqCursor;
     for (const key of servedKeys.slice(1)) {
@@ -225,15 +156,6 @@ export class SessionProjectionCacheRdb extends Service {
     return { asOfSeq, values };
   }
 
-  /**
-   * Hydrate projection cells for an already-prepared Session without another
-   * persistence read. The cache seeds matching rows; the supplied exact log
-   * advances every unit to the observation cut. No checkpoint is written
-   * because the logical observation may contain recovery events not yet durable.
-   * @param session - exact unpublished Session retained by persistence.
-   * @param events - exact logical event prefix represented by the observation.
-   * @returns all projection values at the event cut.
-   */
   hydratePrepared(session: Session, events: readonly SessionEvent[]): ProjectionSnapshot {
     const record = this.recordFor(
       session.id,
@@ -250,26 +172,14 @@ export class SessionProjectionCacheRdb extends Service {
         SessionLogOffset(0),
       );
     } catch {
-      // Cached rows are disposable derived data. Retry from the exact log so a
-      // stale schema cannot make a valid Session unreadable.
       return this.ctx.sessionProjections.hydrate(session, {}, events, SessionLogOffset(0));
     }
   }
 
-  /**
-   * Durably checkpoint one live session NOW (all mandatory points call this).
-   * NOT fail-soft — callers on the fail-soft paths contain it.
-   * @param session - the live session to checkpoint.
-   * @returns resolution after durability.
-   */
   async write(session: Session): Promise<void> {
     const rows = this.ctx.sessionProjections.checkpoint(session);
     this.markClean(session);
-    // Durability barrier: the checkpoint cut was taken above, so flushing
-    // AFTER it guarantees every event inside the cut is durably logged
-    // before the cache row lands — a crash can leave the cache behind the
-    // log (longer tail replay) but never ahead of it (phantom values folded
-    // from events no stored log contains).
+
     if (this.ctx.sessions.get(session.id) === session) await this.ctx.sessions.flush(session);
     await this.put(
       session.id,
@@ -278,15 +188,24 @@ export class SessionProjectionCacheRdb extends Service {
     );
   }
 
-  /**
-   * Cold-read one session's projections from its complete log. Each unit is
-   * seeded from the identity-checked cached rows and the refreshed checkpoint
-   * is written back (fail-soft, fire-and-forget).
-   * @param meta - the stored session header (identity witness).
-   * @param inheritedEventCount - exact inherited prefix length for projection initialization and identity.
-   * @param events - the session's complete log, in seq order.
-   * @returns the projection cut at the log end.
-   */
+  // rewind 后 head 回退：把水位超出新 head 的投影单元丢弃，保留仍在截断前缀内的行。
+  // 这是零 I/O 读的更新（不 fold 日志）：下次零 I/O 读拿到的是截断后的水位，而不是旧值。
+  async truncateTo(
+    meta: SessionHeader,
+    inheritedEventCount: SessionLogOffset,
+    headSeq: number,
+  ): Promise<void> {
+    const identity = identityOf(meta, inheritedEventCount);
+    const record = this.recordFor(meta.id, identity);
+    if (record === undefined) return;
+    const rows = Object.fromEntries(
+      Object.entries(record.rows).filter(
+        ([, row]) => ((row as ProjectionCheckpointRow).seq as number) <= headSeq,
+      ),
+    );
+    await this.put(meta.id, identity, rows as unknown as Record<string, ProjectionCheckpointRow>);
+  }
+
   coldSnapshot(
     meta: SessionHeader,
     inheritedEventCount: SessionLogOffset,
@@ -300,8 +219,7 @@ export class SessionProjectionCacheRdb extends Service {
       meta,
       inheritedEventCount,
     );
-    // Refresh the row so the next cold read seeds from it; fail-soft and
-    // fire-and-forget — a failed write-back only costs a longer tail replay.
+
     void this.put(
       meta.id,
       identity,
@@ -314,12 +232,7 @@ export class SessionProjectionCacheRdb extends Service {
     return restored.snapshot;
   }
 
-  // --- write-behind (throttle + mandatory points) ---
-
   private installWritePath(): void {
-    // Every committed event advances the dirty counter; turn/end is a
-    // mandatory point (the durable value most reads want is the turn-final
-    // one), count/interval throttle the in-turn stream.
     this.ctx.on("session/event", (session: Session, event: SessionEvent) => {
       if (event.type === "turn/end") {
         void this.flushSoft(session, "turn/end");
@@ -337,14 +250,10 @@ export class SessionProjectionCacheRdb extends Service {
       }, this.config.writeIntervalMs);
     });
 
-    // Creation is the FIRST mandatory point: a session that never talks (a
-    // forked child seeded with its ancestor's title, say) would otherwise
-    // get its first row only at detach.
     this.ctx.on("session/created", (session: Session) => {
       void this.flushSoft(session, "create");
     });
 
-    // Detach (the live-to-cold moment): the final mandatory point.
     this.ctx.on("session/disposed", (session: Session) => {
       void this.flushSoft(session, "detach");
       this.markClean(session);
@@ -362,7 +271,6 @@ export class SessionProjectionCacheRdb extends Service {
     );
   }
 
-  /** One fail-soft durable checkpoint. */
   private async flushSoft(session: Session, trigger: string): Promise<void> {
     try {
       await this.write(session);
@@ -373,7 +281,6 @@ export class SessionProjectionCacheRdb extends Service {
     }
   }
 
-  /** Reset one session's dirty bookkeeping (its checkpoint is being written). */
   private markClean(session: Session): void {
     const state = this.dirty.get(session);
     if (state === undefined) return;
@@ -384,21 +291,19 @@ export class SessionProjectionCacheRdb extends Service {
     }
   }
 
-  /** Replace one session's stored record with its log identity and a detached snapshot of `rows`. */
   private async put(
     id: SessionId,
     identity: CheckpointIdentity,
     rows: Record<string, ProjectionCheckpointRow>,
   ): Promise<void> {
     const detached = detachJson(rows);
-    // 介质只存行：checkpoint 的 identity 由会话行承载（直读时现取）。
+
     await this.repository.putProjcache(id, detached);
-    // 异步驱动的镜像要 identity 才能做校验，随写入一起带上。
+
     if (!this.directReads) this.records.set(id, { sessionId: id, identity, rows: detached });
   }
 }
 
-/** Detach one checkpoint from live unit state, refusing non-lossless JSON. */
 function detachJson(
   rows: Record<string, ProjectionCheckpointRow>,
 ): Record<string, ProjectionCheckpointRow> {
@@ -417,7 +322,6 @@ function detachJson(
   return JSON.parse(text) as Record<string, ProjectionCheckpointRow>;
 }
 
-/** Project a header onto the identity fields a record is bound to. */
 function identityOf(
   header: SessionHeader,
   inheritedEventCount: SessionLogOffset,
@@ -435,19 +339,12 @@ function identityOf(
   };
 }
 
-/**
- * Whether a stored record's bound identity names the caller's lifecycle.
- * An absent format generation cannot prove the fold semantics and never
- * matches. Once the format matches, absent lineage fields (records admitted
- * via compatible versions predate them) read as the unseeded lineage.
- */
 function identityMatches(stored: CheckpointIdentity, expected: CurrentCheckpointIdentity): boolean {
   return (
     stored.formatVersion === expected.formatVersion && lifecycleIdentityMatches(stored, expected)
   );
 }
 
-/** Match one predecessor cache record to the authoritative listed lifecycle. */
 function predecessorIdentityMatches(
   stored: CheckpointIdentity,
   expected: CurrentCheckpointIdentity,
@@ -457,7 +354,6 @@ function predecessorIdentityMatches(
   return predecessor && lifecycleIdentityMatches(stored, expected);
 }
 
-/** Match the format-independent fields that distinguish one Session lifecycle. */
 function lifecycleIdentityMatches(
   stored: CheckpointIdentity,
   expected: CurrentCheckpointIdentity,

package/src/storage-takeover/repository.ts

@@ -1,12 +1,3 @@
-/**
- * storages 接管表的方言无关实现：SQLite 与 PostgreSQL 的 drizzle 查询构建器
- * 共享同一套调用形状（SQLite 走同步 `.all()`/`.get()`/`.run()`，PostgreSQL
- * 走 thenable），差别由本模块的执行 helper 吸收。
- *
- * workspace 域是权威数据：记录、归属、显示顺序与归档集都拆成语义表，每次写入
- * 在介质事务内完成（`host.writeAtomically`），不留部分应用的中间态。
- */
-
 import { randomUUID } from "node:crypto";
 import { and, eq, gte, inArray, isNotNull, lt, notInArray, sql } from "drizzle-orm";
 import {
@@ -27,36 +18,23 @@ import type {
   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` 产出的方言表对象。 */
+
+  /** 不经 await、直接拿到的数据库句柄；未开放时只走异步的 `db`。 */
+  dbDirect?: () => unknown;
+
   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();
@@ -64,7 +42,6 @@ async function oneRow<T>(query: unknown): Promise<T | undefined> {
   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") {
@@ -74,7 +51,6 @@ async function runQuery(query: unknown): Promise<void> {
   await query;
 }
 
-/** `t_sessions` 上承载 checkpoint identity 的列（与投影行 1:1，不另存一份）。 */
 interface SessionIdentityRow {
   fVersion: number;
   fCreatedAt: number;
@@ -82,7 +58,6 @@ interface SessionIdentityRow {
   fSeedLength: number | null;
 }
 
-/** `t_session_projcache_row` 的行形状（存储层视角）。 */
 interface ProjcacheRowRecord {
   fSessionId: string;
   fKey: string;
@@ -91,7 +66,6 @@ interface ProjcacheRowRecord {
   fVal: string;
 }
 
-/** 一行会话元数据 → 上游 `CheckpointIdentity`。 */
 function identityOfSession(row: SessionIdentityRow): CheckpointIdentity {
   return {
     formatVersion: row.fVersion,
@@ -102,12 +76,10 @@ function identityOfSession(row: SessionIdentityRow): CheckpointIdentity {
   };
 }
 
-/** 存储的整数水位 → 上游 seq cursor（-1 是空日志哨兵）。 */
 function seqCursor(seq: number): SessionSeqCursor {
   return seq === -1 ? -1 : SessionSeq(seq);
 }
 
-/** 两写标记的两列 → 上游 `pendingMutation`（未知操作按缺失处理）。 */
 function pendingMutationOf(row: {
   fPendingOperation: string | null;
   fPendingWorkspaceId: string | null;
@@ -117,13 +89,7 @@ function pendingMutationOf(row: {
   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"]!;
@@ -131,7 +97,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
   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,
@@ -139,9 +105,8 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
     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
+  const dbx = async (): Promise<any> => (await host.db()) as any;
 
   return {
     async readUnitVersion(name: string): Promise<number | undefined> {
@@ -209,7 +174,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
             .values(values)
             .onConflictDoUpdate({ target: tWorkspaces.fWorkspaceId, set: values }),
         );
-        // 归属整体替换：DELETE + 有序 INSERT 在同一事务内，读不到中间态。
+
         await runQuery(
           db.delete(tWorkspaceSessions).where(eq(tWorkspaceSessions.fWorkspaceId, id)),
         );
@@ -287,7 +252,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
             .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(
@@ -297,7 +262,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
               .where(eq(tWorkspaces.fWorkspaceId, workspaceId)),
           );
         }
-        // 归档集整体替换：标记落在会话行（f_archived_at），未列出的会话清空标记。
+
         const archived = state.archivedSessionIds;
         await runQuery(
           archived.length === 0
@@ -314,10 +279,6 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
         );
         const stamp = Date.now();
         for (const sessionId of archived) {
-          // 归档标记落在会话行上（f_archived_at）；live 但从未物化的会话还没有
-          // 行——补一行骨架（head=-1、无 cwd/seed），否则标记无处可写，重启后
-          // 归档集由介质重算时会静默丢失。真正物化走 upsertSession，其冲突列
-          // 不含 f_archived_at，所以标记在物化后仍保留。
           await runQuery(
             db
               .insert(tSessions)
@@ -338,7 +299,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
               })
               .onConflictDoUpdate({
                 target: tSessions.fSessionId,
-                // 首次归档时间保留：重复写入同一集合不刷新标记。
+
                 set: { fArchivedAt: sql`COALESCE(${tSessions.fArchivedAt}, ${stamp})` },
               }),
           );
@@ -362,7 +323,6 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
         });
       }
       for (const row of rows) {
-        // 没有会话行的行读作缺失：checkpoint 的 identity 由会话行承载。
         const entry = entries.get(row.fSessionId);
         if (entry === undefined) continue;
         entry.rows[row.fKey] = {
@@ -371,7 +331,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
           val: JSON.parse(row.fVal),
         } satisfies ProjectionCheckpointRow;
       }
-      // 没有投影行的会话没有 checkpoint（避免把空记录装进异步镜像）。
+
       return [...entries.values()].filter((entry) => Object.keys(entry.rows).length > 0);
     },
 
@@ -421,12 +381,11 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
       return stale.length;
     },
 
-    // 同步驱动（SQLite）才有：读路径直接查介质，进程内不维护 checkpoint 镜像。
-    ...(host.dbSync === undefined
+    ...(host.dbDirect === undefined
       ? {}
       : {
-          readProjcacheSync: (sessionId: string): StoredProjcacheEntry | undefined => {
-            const db = host.dbSync!() as any; // eslint-disable-line @typescript-eslint/no-explicit-any
+          readProjcacheDirect: (sessionId: string): StoredProjcacheEntry | undefined => {
+            const db = host.dbDirect!() as any;
             const stored = db
               .select()
               .from(tProjcacheRows)
@@ -438,7 +397,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
               .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) {
@@ -450,8 +409,10 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
             }
             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
+          readSessionTitleDirect: (
+            sessionId: string,
+          ): { title: string; seq: number } | undefined => {
+            const db = host.dbDirect!() as any;
             const row = db
               .select({ fTitle: tSessions.fTitle, fTitleSeq: tSessions.fTitleSeq })
               .from(tSessions)