@morlay/session-rdb 0.0.18 → 0.0.20

package/src/storage-takeover/repository.ts

@@ -7,8 +7,14 @@
  * 在介质事务内完成（`host.writeAtomically`），不留部分应用的中间态。
  */
 
-import { and, eq, gte, isNotNull, notInArray, sql } from "drizzle-orm";
-import { SessionId, SessionLogOffset, SessionSeq } from "@deepseek-ai/dsh-session";
+import { randomUUID } from "node:crypto";
+import { and, eq, gte, inArray, isNotNull, lt, notInArray, sql } from "drizzle-orm";
+import {
+  SESSION_FORMAT_VERSION,
+  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 {
@@ -92,9 +98,7 @@ function identityOfSession(row: SessionIdentityRow): CheckpointIdentity {
     createdAt: row.fCreatedAt,
     ...(row.fCwd === null ? {} : { cwd: row.fCwd }),
     isSeeded: row.fSeedLength !== null,
-    ...(row.fSeedLength === null
-      ? {}
-      : { inheritedEventCount: SessionLogOffset(row.fSeedLength) }),
+    ...(row.fSeedLength === null ? {} : { inheritedEventCount: SessionLogOffset(row.fSeedLength) }),
   };
 }
 
@@ -305,20 +309,38 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
                 .update(tSessions)
                 .set({ fArchivedAt: null })
                 .where(
-                  and(
-                    isNotNull(tSessions.fArchivedAt),
-                    notInArray(tSessions.fSessionId, archived),
-                  ),
+                  and(isNotNull(tSessions.fArchivedAt), notInArray(tSessions.fSessionId, archived)),
                 ),
         );
         const stamp = Date.now();
         for (const sessionId of archived) {
-          // 首次归档时间保留：重复写入同一集合不刷新标记。
+          // 归档标记落在会话行上（f_archived_at）；live 但从未物化的会话还没有
+          // 行——补一行骨架（head=-1、无 cwd/seed），否则标记无处可写，重启后
+          // 归档集由介质重算时会静默丢失。真正物化走 upsertSession，其冲突列
+          // 不含 f_archived_at，所以标记在物化后仍保留。
           await runQuery(
             db
-              .update(tSessions)
-              .set({ fArchivedAt: sql`COALESCE(${tSessions.fArchivedAt}, ${stamp})` })
-              .where(eq(tSessions.fSessionId, sessionId)),
+              .insert(tSessions)
+              .values({
+                fSessionId: sessionId,
+                fHeadEventId: "",
+                fHeadSequence: -1,
+                fVersion: SESSION_FORMAT_VERSION,
+                fCreatedAt: stamp,
+                fCwd: null,
+                fParentSession: null,
+                fSeedLength: null,
+                fOrigin: null,
+                fDelegationDepth: null,
+                fIncarnation: randomUUID(),
+                fRevision: 0,
+                fArchivedAt: stamp,
+              })
+              .onConflictDoUpdate({
+                target: tSessions.fSessionId,
+                // 首次归档时间保留：重复写入同一集合不刷新标记。
+                set: { fArchivedAt: sql`COALESCE(${tSessions.fArchivedAt}, ${stamp})` },
+              }),
           );
         }
       });
@@ -353,10 +375,7 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
       return [...entries.values()].filter((entry) => Object.keys(entry.rows).length > 0);
     },
 
-    async putProjcache(
-      sessionId: string,
-      rows: ProjectionCheckpoint,
-    ): Promise<void> {
+    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)));
@@ -371,9 +390,35 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
       });
     },
 
-    async deleteProjcache(sessionId: string): Promise<void> {
+    async pruneStaleProjcache(): Promise<number> {
       const db = await dbx();
-      await runQuery(db.delete(tProjcacheRows).where(eq(tProjcacheRows.fSessionId, sessionId)));
+      const stale = await allRows<{ fSessionId: string }>(
+        db
+          .select({ fSessionId: tProjcacheRows.fSessionId })
+          .from(tProjcacheRows)
+          .where(
+            and(
+              lt(tProjcacheRows.fSeq, 0),
+              inArray(
+                tProjcacheRows.fSessionId,
+                db
+                  .select({ fSessionId: tSessions.fSessionId })
+                  .from(tSessions)
+                  .where(gte(tSessions.fHeadSequence, 0)),
+              ),
+            ),
+          ),
+      );
+      if (stale.length === 0) return 0;
+      await runQuery(
+        db.delete(tProjcacheRows).where(
+          inArray(
+            tProjcacheRows.fSessionId,
+            stale.map((row) => row.fSessionId),
+          ),
+        ),
+      );
+      return stale.length;
     },
 
     // 同步驱动（SQLite）才有：读路径直接查介质，进程内不维护 checkpoint 镜像。
@@ -412,7 +457,8 @@ export function createStorageRepository(host: StorageRepositoryHost): StorageRep
               .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;
+            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

@@ -25,8 +25,8 @@ const WORKSPACE_TABLE = "workspaces";
 export class RdbStorageBackend implements StorageBackend {
   readonly kv: KvFacet = { open: (descriptor) => this.openUnit(descriptor) };
 
-  /** 已打开（或打开中）的 unit 名；重复 open 是调用方 bug。 */
-  private readonly open = new Set<string>();
+  /** 已打开（或打开中）的 unit；重复 open 是调用方 bug。 */
+  private readonly open = new Map<string, WorkspaceKvUnit>();
   private closed = false;
 
   /**
@@ -47,46 +47,73 @@ export class RdbStorageBackend implements StorageBackend {
           `(table '${WORKSPACE_TABLE}' plus a global slot)`,
       );
     }
+    // 本后端是 single 布局的专用表实现：per-record 布局（及其 compatibleVersions
+    // 读语义）无法表达，宁可 fail loud 也不静默按 single 读。
+    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)) {
       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}`,
-      );
+    // 名字在同步段预留：并发第二个 open 必须在任何 await 之前被拒。
+    const unit = new WorkspaceKvUnit(this.repository, descriptor);
+    this.open.set(descriptor.name, unit);
+    try {
+      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}`,
+        );
+      }
+    } catch (error) {
+      this.open.delete(descriptor.name);
+      throw error;
     }
-    this.open.add(descriptor.name);
-    return new WorkspaceKvUnit(this.repository, descriptor, () => {
+    unit.onClose(() => {
       this.open.delete(descriptor.name);
     });
+    return unit;
   }
 
   /**
-   * 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.
+   * Release the backend. New writes are rejected immediately; already-queued
+   * unit writes drain first (upstream backend contract). The medium (the
+   * session database) belongs to the owning session-rdb plugin, so closing
+   * open units here does not close it.
+   * @returns resolution after every open unit drained.
    */
   async close(): Promise<void> {
     this.closed = true;
+    const units = [...this.open.values()];
     this.open.clear();
+    await Promise.all(units.map((unit) => unit.close()));
   }
 }
 
 /** workspace 域的 KV unit：每个原语一条 SQL 语句，值形状与上游记录一致。 */
 class WorkspaceKvUnit implements KvUnit {
   private closed = false;
+  /** 在途写操作：close 先拒绝新写，再 drain 它们（不丢已受理的写）。 */
+  private readonly inflight = new Set<Promise<void>>();
+  private onClosed: (() => void) | undefined;
 
   constructor(
     private readonly repository: StorageRepository,
     private readonly descriptor: KvUnitDescriptor,
-    private readonly onClose: () => void,
   ) {}
 
+  /** Install the name-release callback after the backend registered this unit. */
+  onClose(release: () => void): void {
+    this.onClosed = release;
+  }
+
   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>;
@@ -100,24 +127,41 @@ class WorkspaceKvUnit implements KvUnit {
   async putRecord(table: string, key: string, value: unknown): Promise<void> {
     this.assertOpen();
     this.assertTable(table);
-    await this.repository.putWorkspace(key, workspaceRecordOf(value));
+    await this.track(this.repository.putWorkspace(key, workspaceRecordOf(value)));
   }
 
   async deleteRecord(table: string, key: string): Promise<void> {
     this.assertOpen();
     this.assertTable(table);
-    await this.repository.deleteWorkspace(key);
+    await this.track(this.repository.deleteWorkspace(key));
   }
 
   async setGlobal(value: unknown): Promise<void> {
     this.assertOpen();
-    await this.repository.writeWorkspaceState(workspaceStateOf(value));
+    await this.track(this.repository.writeWorkspaceState(workspaceStateOf(value)));
   }
 
   async close(): Promise<void> {
     if (this.closed) return;
     this.closed = true;
-    this.onClose();
+    while (this.inflight.size > 0) {
+      await Promise.allSettled(this.inflight);
+    }
+    this.onClosed?.();
+  }
+
+  /** Register one accepted write so close can drain it. */
+  private async track(operation: Promise<unknown>): Promise<void> {
+    const settled = operation.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.inflight.add(settled);
+    try {
+      await operation;
+    } finally {
+      this.inflight.delete(settled);
+    }
   }
 
   private assertOpen(): void {

package/src/storage-takeover/types.ts

@@ -11,7 +11,10 @@
 
 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 {
+  ProjectionCheckpoint,
+  ProjectionCheckpointRow,
+} from "@deepseek-ai/dsh-session-projection";
 import type { WorkspaceDomainState, WorkspaceRecord } from "@deepseek-ai/dsh-workspace";
 
 export type {
@@ -77,6 +80,11 @@ export interface StorageRepository {
    * @param rows - 每个投影 key 一行。
    */
   putProjcache(sessionId: string, rows: ProjectionCheckpoint): Promise<void>;
-  /** 删除一个会话的 checkpoint（缺失为 no-op）。 */
-  deleteProjcache(sessionId: string): Promise<void>;
+  /**
+   * 清理陈旧 checkpoint 行：水位为负却已有事件的会话（旧版写入路径的产物，
+   * 会把有对话的会话误判为空白）。缓存是派生数据，删除只让该会话回到
+   * 「未知即可见」并等待下一次强制点重写。
+   * @returns 删除的行数。
+   */
+  pruneStaleProjcache(): Promise<number>;
 }

package/src/testing.ts

@@ -5,3 +5,6 @@ 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";
+// rewind 落到 live 会话上的那一件事：截断内存 log 并重置派生 surface / 折叠
+// 缓存。跨包测试要构造「rewind 之后」的会话态时用它，不必拉起 RDB 装配。
+export { truncateLiveSession } from "./branch.ts";