@morlay/session-rdb 0.0.17 → 0.0.19

package/src/index.ts

@@ -30,6 +30,7 @@ import {
   type SessionPersistenceStatOptions,
 } from "@deepseek-ai/dsh-session-persistence";
 import {
+  SESSION_FORMAT_VERSION,
   SessionLogOffset,
   type Session,
   type SessionEvent,
@@ -37,6 +38,7 @@ import {
   type SessionId,
   type SurfaceEventType,
 } from "@deepseek-ai/dsh-session";
+import { sessionFormatLogFilename } from "@deepseek-ai/dsh-session-format";
 import { type Backend, type BackendTx, type EventInsert } from "./backend.ts";
 import { WriteGuard } from "./write-guard.ts";
 import { repairReadView, rowToMeta, scanRows, toJsonlArtifact } from "./log.ts";
@@ -50,6 +52,7 @@ import { SqliteBackend } from "./sqlite.ts";
 import { PostgresBackend } from "./postgres.ts";
 import { SessionBranchRdb } from "./branch.ts";
 import { registerSessionImport } from "./import.ts";
+import { SessionQueryRdb } from "./session-query.ts";
 import { adoptLegacyRows, convertLegacyRows, isLegacyVersion } from "./legacy.ts";
 import { installStorageTakeover } from "./storage-takeover/index.ts";
 
@@ -532,6 +535,10 @@ export class SessionPersistenceRdb extends SessionPersistence {
     this.installLiveRouting(ctx);
     // 分支 provider 服务（rewind / forkFrom / timeline），随 fiber 卸载自动回滚。
     new SessionBranchRdb(this.ctx);
+    // 会话查询服务：接管官方 session-query-sqlite（同名 provide 会 fail loud，
+    // 其装配行由 better-session patch 禁用）；class-plugin 装载以复用基类的
+    // 精确读 / 过滤 / 血缘实现。
+    this.ctx.plugin(SessionQueryRdb, {});
     // 导入端点：webServer + connection 就绪后注册 `/api/session.import`。
     registerSessionImport(this.ctx, this);
     // storages 接管：storage hub 的 `rdb` 后端（workspace 域）与
@@ -706,7 +713,7 @@ export class SessionPersistenceRdb extends SessionPersistence {
 
   // --- RDB 特有能力（rewind / fork / 导出 / 测试支撑） ---
 
-  /** 导出 artifact（jsonl v2 文本），视图只读不落库。 */
+  /** 导出当前世代的 jsonl artifact，视图只读不落库。 */
   async readRaw(
     id: SessionId,
     signal?: AbortSignal,
@@ -724,7 +731,8 @@ export class SessionPersistenceRdb extends SessionPersistence {
     return {
       meta: log.meta,
       inheritedEventCount,
-      filename: "session.jsonl",
+      // 内容按当前世代编码，文件名必须声明同一世代（上游导出用 session.vN.jsonl）。
+      filename: sessionFormatLogFilename(SESSION_FORMAT_VERSION),
       content: toJsonlArtifact(log.meta, inheritedEventCount, log.events),
     };
   }

package/src/postgres.ts

@@ -60,16 +60,22 @@ export class PostgresBackend implements Backend {
     this.opened.catch(() => {});
     this.storage = createStorageRepository({
       db: () => this.opened.then(() => this.txOverride ?? this.db),
+      // storages 写事务用 serializable：workspace 域是整记录替换，多实例并发写
+      // 同一记录在 read committed 下是「最后提交者赢」的静默覆盖；提升隔离级别
+      // 后冲突以序列化失败暴露（与「并发写入 fail loud」一致），调用方重试即可。
       writeAtomically: (fn) =>
-        this.db.transaction(async (tx) => {
-          const previous = this.txOverride;
-          this.txOverride = tx;
-          try {
-            return await fn();
-          } finally {
-            this.txOverride = previous;
-          }
-        }),
+        this.db.transaction(
+          async (tx) => {
+            const previous = this.txOverride;
+            this.txOverride = tx;
+            try {
+              return await fn();
+            } finally {
+              this.txOverride = previous;
+            }
+          },
+          { isolationLevel: "serializable" },
+        ),
       tables: this.tables,
     });
   }

package/src/session-query.ts

@@ -0,0 +1,27 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { SessionQueryEngine, SessionQueryError, type Config } from "@deepseek-ai/dsh-session-query";
+
+// 会话查询服务的 rdb 实现：精确读 / 过滤 / 血缘全部复用上游基类（数据面走
+// ctx.sessions 与我们的 ctx.sessionPersistence），这里只接管服务所有权。
+// 全文检索与官方 `openAt: never` 装配保持一致——直接拒绝，不引入 FTS 索引、
+// node:sqlite 或派生库，搜索语义留待显式实现（见 ADR 0006）。
+export class SessionQueryRdb extends SessionQueryEngine {
+  constructor(ctx: Context, config: Config = {}) {
+    super(ctx, config);
+  }
+
+  override async searchSessions(): Promise<never> {
+    throw searchDisabled();
+  }
+
+  override async searchEvents(): Promise<never> {
+    throw searchDisabled();
+  }
+}
+
+function searchDisabled(): SessionQueryError {
+  return new SessionQueryError(
+    "session search is disabled: this deployment serves session queries from the rdb backend without a full-text index",
+    "SESSION_QUERY_SEARCH_DISABLED",
+  );
+}

package/src/storage-takeover/index.ts

@@ -48,13 +48,13 @@ export function installStorageTakeover(ctx: Context, options: StorageTakeoverOpt
     storageCtx.provide(storageBackendServiceKey(RDB_STORAGE_BACKEND), backend);
   });
 
-  // 投影 checkpoint：上游插件被禁用后由本服务提供同名 API。
-  ctx.inject(["sessionProjections"], (projectionCtx) => {
-    new SessionProjectionCacheRdb(
-      projectionCtx,
-      options.projectionCache,
-      options.repository,
-      options.ready,
-    );
+  // 投影 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,
+    ready: options.ready,
   });
 }

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

@@ -49,6 +49,12 @@ export interface ProjectionCacheConfig {
   writeIntervalMs: number;
 }
 
+/** class-plugin 装载参数：写节流 + storages 接管访问层 + 介质就绪信号。 */
+export interface SessionProjectionCacheRdbOptions extends ProjectionCacheConfig {
+  repository: StorageRepository;
+  ready: Promise<unknown>;
+}
+
 /** 每会话写回节流簿记（只对 live session）。 */
 interface DirtyState {
   pending: number;
@@ -67,35 +73,48 @@ export class SessionProjectionCacheRdb extends Service {
   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>;
 
   /**
-   * @param ctx - 插件上下文（须已注入 sessionProjections 与 sessions）。
-   * @param config - 写节流参数。
-   * @param repository - storages 接管表访问层。
-   * @param ready - 介质就绪信号（直读介质前必须等到）。
+   * 本类按 cordis class plugin 装载（`ctx.plugin(SessionProjectionCacheRdb, options)`）：
+   * `static inject` 等依赖就绪后构造，构造后框架调用 `[Service.init]` 安装写入
+   * 路径——直接 `new` 不会触发 init，写入路径会静默缺失。
+   * @param ctx - 插件上下文（已注入 sessionProjections 与 sessions）。
+   * @param options - 写节流 + storages 接管访问层 + 介质就绪信号。
    */
-  constructor(
-    ctx: Context,
-    private readonly config: ProjectionCacheConfig,
-    private readonly repository: StorageRepository,
-    private readonly ready: Promise<unknown>,
-  ) {
+  constructor(ctx: Context, options: SessionProjectionCacheRdbOptions) {
     super(ctx, SESSION_PROJECTION_CACHE_SERVICE);
-    this.directReads = repository.readProjcacheSync !== undefined;
+    this.config = options;
+    this.repository = options.repository;
+    this.ready = options.ready;
+    this.directReads = options.repository.readProjcacheSync !== undefined;
   }
 
   /**
-   * Wait for the medium, then install the write path. Only the async driver
-   * needs a startup mirror: the sync driver serves every read from the table.
+   * 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(
+        `session projection cache: pruned stale snapshot(s) for ${String(pruned)} session(s)`,
+      );
+    }
     if (!this.directReads) {
       for (const entry of await this.repository.loadProjcache()) {
         this.records.set(entry.sessionId as SessionId, entry);
       }
     }
-    this.installWritePath();
   }
 
   /** Read one session's stored record: straight from the medium, or from the async mirror. */
@@ -113,7 +132,10 @@ export class SessionProjectionCacheRdb extends Service {
    * @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): StoredProjcacheEntry | undefined {
+  private recordFor(
+    id: SessionId,
+    expected: CurrentCheckpointIdentity,
+  ): StoredProjcacheEntry | undefined {
     const record = this.lookup(id);
     if (record === undefined) return undefined;
     return identityMatches(record.identity, expected) ? record : undefined;
@@ -329,12 +351,15 @@ export class SessionProjectionCacheRdb extends Service {
       this.dirty.delete(session);
     });
 
-    this.ctx.effect(() => () => {
-      for (const state of this.dirty.values()) {
-        if (state.timer !== undefined) clearTimeout(state.timer);
-      }
-      this.dirty.clear();
-    }, "sessionProjectionCacheRdb.timers");
+    this.ctx.effect(
+      () => () => {
+        for (const state of this.dirty.values()) {
+          if (state.timer !== undefined) clearTimeout(state.timer);
+        }
+        this.dirty.clear();
+      },
+      "sessionProjectionCacheRdb.timers",
+    );
   }
 
   /** One fail-soft durable checkpoint. */
@@ -374,7 +399,9 @@ export class SessionProjectionCacheRdb extends Service {
 }
 
 /** Detach one checkpoint from live unit state, refusing non-lossless JSON. */
-function detachJson(rows: Record<string, ProjectionCheckpointRow>): Record<string, ProjectionCheckpointRow> {
+function detachJson(
+  rows: Record<string, ProjectionCheckpointRow>,
+): Record<string, ProjectionCheckpointRow> {
   let text: string | undefined;
   try {
     text = JSON.stringify(rows);
@@ -416,8 +443,7 @@ function identityOf(
  */
 function identityMatches(stored: CheckpointIdentity, expected: CurrentCheckpointIdentity): boolean {
   return (
-    stored.formatVersion === expected.formatVersion &&
-    lifecycleIdentityMatches(stored, expected)
+    stored.formatVersion === expected.formatVersion && lifecycleIdentityMatches(stored, expected)
   );
 }
 

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>;
 }