@aiao/rxdb-adapter-electron 0.0.0-stage → 0.0.28

package/src/pglite/desktop-pglite-client.ts

@@ -0,0 +1,614 @@
+/**
+ * renderer 侧的桌面 PGlite 客户端，实现 `@aiao/rxdb-adapter-pglite` 的 `IPGliteClient` 契约。
+ *
+ * @remarks
+ * 它把 query / exec / transaction 转成 `pg.*` 请求发给主进程持有的唯一 PGlite 实例，
+ * 因此 `RxDBAdapterPGlite` 里的全部 SQL、迁移、变更管线原样复用——桌面路径不是另一套
+ * 实现，只是同一份契约换了条传输通道。
+ *
+ * 事务用的是 US-208 线 G 冻结的「IPC 事务 ID 协议」：`pg.begin` 换回一个 host 签发的
+ * 事务 ID，随后的语句带着它走，最后 `pg.commit` / `pg.rollback` 结清。
+ *
+ * @module pglite/desktop-pglite-client
+ */
+
+import {
+  DEFAULT_NOTIFY_BATCH_TIMEOUT_MS,
+  PGliteNotificationBatcher,
+  type IPGliteClient,
+  type PGliteClientEvents,
+  type PGliteClientOptions,
+  type PGliteDataDirItem
+} from '@aiao/rxdb-adapter-pglite';
+import {
+  DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS,
+  RxDBAdapterDesktopError,
+  assertDesktopPgliteResponse,
+  parseDesktopPgliteBackupItem,
+  parseDesktopPgliteHandshakeResult,
+  parseDesktopPgliteNotifyMessage,
+  parseDesktopPgliteOpenResult,
+  type DesktopHostTransport,
+  type DesktopPgliteParam,
+  type DesktopPgliteRequest,
+  type DesktopPgliteResponse,
+  type RxDBAdapterDesktopErrorCode
+} from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import { EventDispatcher } from '@aiao/utils';
+import type { QueryOptions, Results, Transaction } from '@electric-sql/pglite';
+// 模板编译走 PGlite 自己的实现，而不是本地再拼一遍 `$1、$2`：`identifier` / `raw` / 嵌套
+// `sql` 这些辅助器的语义只有原实现说了算，照抄一份的分叉表征是「同一个模板在桌面下
+// 少转义了一个标识符」。`/template` 是个独立子路径（约 2 KB），不带任何 WASM 进 renderer。
+import { query as compileTemplate } from '@electric-sql/pglite/template';
+import { toDesktopPGliteResults as toResults } from './desktop-pglite-results.js';
+import { toElectronPGliteBackupError } from './electron-pglite-backup-error.js';
+
+/** {@link DesktopPGliteClient} 的构造参数。 */
+export interface DesktopPGliteClientOptions {
+  /** preload 或 worker 桥接提供的传输层。 */
+  readonly transport: DesktopHostTransport;
+  /** 应用作用域内的逻辑数据目录名；host 在自己的应用数据目录里解析它。 */
+  readonly dataDirectoryName: string;
+  /** `pg.begin` 的等待上限（毫秒）；省略时由 host 用协议默认值。 */
+  readonly beginTimeout?: number;
+  /** NOTIFY 批量窗口（毫秒）；省略时用 {@link DEFAULT_NOTIFY_BATCH_TIMEOUT_MS}。 */
+  readonly batchTimeout?: number;
+}
+
+/** `pg.open` 撞上恢复流程时的拒绝码，见 {@link DesktopPGliteClient.#assertOpened}。 */
+const RESTORE_CONFLICT_CODES: ReadonlySet<RxDBAdapterDesktopErrorCode> = new Set([
+  'restore_in_progress',
+  'restore_incomplete'
+]);
+
+/**
+ * 拒绝本代理无法转发的 `QueryOptions`。
+ *
+ * @remarks
+ * `parsers` / `serializers` / `onNotice` 都是函数，`blob` 是流——没有一个过得了结构化克隆。
+ * 静默忽略它们的后果是调用方以为自己换了解析器，而拿到的还是默认解析结果，
+ * 且**没有任何报错**。这里明确失败，比装作支持诚实。
+ */
+const assertNoQueryOptions = (options: QueryOptions | undefined): void => {
+  if (options === undefined) return;
+  throw new RxDBAdapterDesktopError(
+    'protocol_violation',
+    'the desktop PGlite protocol carries no QueryOptions; parsers, serializers, onNotice and blob ' +
+      'cannot cross the process boundary'
+  );
+};
+
+/**
+ * 拒绝由 renderer 指定的落盘位置。
+ *
+ * @remarks
+ * 存储归主进程独占（AC#5）：默默忽略 `store` / `dataDir` 会让调用方以为数据落在它指定的
+ * 位置，而实际在别处——症状是「重启后数据没了」，排查时根本不会怀疑到这两个被忽略的字段。
+ */
+const assertHostOwnedStorage = (options: PGliteClientOptions): void => {
+  if (options.store === undefined && options.dataDir === undefined) return;
+  throw new RxDBAdapterDesktopError(
+    'protocol_violation',
+    'the desktop PGlite host owns storage; store and dataDir must not be set on the renderer side'
+  );
+};
+
+const unsupportedTransactionOperation = (operation: string): RxDBAdapterDesktopError =>
+  new RxDBAdapterDesktopError(
+    'protocol_violation',
+    `${operation}() cannot be proxied to the desktop PGlite host; use query() or exec() instead`
+  );
+
+/**
+ * 把通知回调里的异常挪出传输层的调用栈。
+ *
+ * @remarks
+ * 与 `DesktopSqliteClient` 的同名手法一字不差，因为病因一字不差：NOTIFY 通道是全 renderer
+ * 共享的，`ipcRenderer.on` 又是**同步扇出**，异常一路抛回 Electron 自己的 IPC 派发循环，
+ * 排在后面的监听者（通常是另一个库的客户端）就收不到这条消息——表现为「某个库的响应式
+ * 查询不刷新」，与那条畸形消息毫无关联线索。
+ *
+ * 不吞：丢进微任务原样重抛，落成一条 uncaught error。传输层不该替调用方决定
+ * 「这个错误不重要」，它只是不该由传输层来接。
+ */
+const reportOutOfBand = (error: unknown): void => {
+  queueMicrotask(() => {
+    throw error;
+  });
+};
+
+/**
+ * 通过桌面 host 访问主进程 PGlite 实例的客户端。
+ *
+ * @remarks
+ * 两条串行化链各管一件事：
+ * - {@link DesktopPGliteClient.#tail} 是**会话内 FIFO**，保证发出顺序即执行顺序；
+ * - {@link DesktopPGliteClient.#lock} 是**本地互斥**，让事务独占整段时间。
+ *
+ * 后者不是可有可无的谨慎：主进程只有一条 PGlite 连接，一条事务开着时它被挂起的
+ * callback 攥着。没有本地互斥的话，第二条事务的 `pg.begin`（或一条自动提交语句）会排在
+ * 会话队列里等那条连接，而连接又要等第一条事务把剩下的语句发完——双方互相等，
+ * 表现为几秒后一句 `transaction_unavailable`，看上去像 host 有 bug。浏览器路径上
+ * PGlite 自己的 mutex 做的正是同一件事，这里只是把它挪到了进程边界的这一侧。
+ *
+ * @public
+ */
+export class DesktopPGliteClient extends EventDispatcher<PGliteClientEvents> implements IPGliteClient {
+  readonly #options: DesktopPGliteClientOptions;
+  readonly #batcher: PGliteNotificationBatcher;
+  #dbName = '';
+  #sessionId?: string;
+  #resolvedLocation?: string;
+  #unsubscribe?: () => void;
+  #closed = false;
+  #closePromise?: Promise<void>;
+  /** 会话内 FIFO 队尾；恒不 reject，否则一条查询出错会把整个会话废掉。 */
+  #tail: Promise<unknown> = Promise.resolve();
+  /** 本地互斥队尾；同样恒不 reject。 */
+  #lock: Promise<unknown> = Promise.resolve();
+
+  /** 本客户端在 host 上的会话 ID，用于把推送过来的 NOTIFY 对号入座。 */
+  get sessionId(): string {
+    if (!this.#sessionId) {
+      throw new RxDBAdapterDesktopError('session_closed', 'the desktop PGlite client has not been initialised yet');
+    }
+    return this.#sessionId;
+  }
+
+  /** host 解析出的逻辑位置，仅供诊断（AC#5）。 */
+  get resolvedLocation(): string {
+    if (!this.#resolvedLocation) {
+      throw new RxDBAdapterDesktopError('session_closed', 'the desktop PGlite client has not been initialised yet');
+    }
+    return this.#resolvedLocation;
+  }
+
+  /** 尚未分发的 NOTIFY 行事件数量。 */
+  get pendingNotificationCount(): number {
+    return this.#batcher.pendingCount;
+  }
+
+  constructor(options: DesktopPGliteClientOptions) {
+    super();
+    this.#options = options;
+    this.#batcher = new PGliteNotificationBatcher({
+      resolveDbName: () => this.#dbName,
+      emit: event => this.dispatchEvent(event.type, event),
+      batchTimeout: options.batchTimeout ?? DEFAULT_NOTIFY_BATCH_TIMEOUT_MS,
+      onParseError: error => console.error('Failed to parse desktop NOTIFY payload:', error)
+    });
+  }
+
+  /**
+   * 握手、打开会话并订阅变更推送。
+   *
+   * @remarks
+   * 握手排在 `pg.open` 之前是 AC#11 的全部内容：`pg.open` 会 `mkdir` 出数据目录并在里面
+   * 跑 initdb，等 renderer 从 open 应答里读出版本不匹配时，磁盘上已经多了一整棵目录树，
+   * 而调用方拿不到 client，也就没有把手去收拾它。
+   *
+   * @param dbName - RxDB 逻辑库名；只用于变更事件的 `dbName` 字段，不参与落盘位置解析
+   * @param options - PGlite 选项；**不得**含 `store` 或 `dataDir`
+   * @throws `RxDBBackupError` 数据目录正在被恢复（`restore_in_progress`）或留着未完成的恢复
+   * （`restore_incomplete`）时，见 {@link DesktopPGliteClient.#assertOpened}
+   * @throws {@link RxDBAdapterDesktopError} 指定了落盘位置、协议版本不匹配或 host 打不开数据目录时
+   */
+  async init(dbName: string, options: PGliteClientOptions): Promise<void> {
+    assertHostOwnedStorage(options);
+    if (this.#sessionId) {
+      throw new RxDBAdapterDesktopError(
+        'protocol_violation',
+        `the desktop PGlite client is already bound to session ${this.#sessionId}`
+      );
+    }
+    this.#dbName = dbName;
+
+    const handshake = assertDesktopPgliteResponse(
+      'pg.handshake',
+      await this.#options.transport.request({ kind: 'pg.handshake' })
+    );
+    parseDesktopPgliteHandshakeResult(handshake.result);
+
+    const opened = this.#assertOpened(
+      await this.#options.transport.request({
+        kind: 'pg.open',
+        storage: { engine: 'pglite', dataDirectoryName: this.#options.dataDirectoryName }
+      })
+    );
+    const result = await this.#parseOpenResultOrClose(opened.result);
+    this.#sessionId = result.sessionId;
+    this.#resolvedLocation = result.resolvedLocation;
+    this.#unsubscribe = this.#options.transport.subscribe(message => this.#onMessage(message));
+    await this.#awaitSubscription();
+  }
+
+  /**
+   * 执行一条带参数的语句（扩展查询协议）。
+   *
+   * @param query - SQL
+   * @param params - 位置参数
+   * @param options - **必须省略**，见 {@link assertNoQueryOptions}
+   * @returns 与浏览器路径同形状的结果
+   * @throws {@link RxDBAdapterDesktopError} 会话已关闭、传了 `options`，或 host 报告执行失败时
+   */
+  async query<T>(query: string, params?: unknown[], options?: QueryOptions): Promise<Results<T>> {
+    this.#assertOpen();
+    assertNoQueryOptions(options);
+    return this.#exclusive(async () => this.#queryOn(undefined, query, params));
+  }
+
+  /**
+   * 以标签模板执行一条语句，参数自动参数化。
+   *
+   * @param sqlStrings - 模板字面量片段
+   * @param params - 插值；`identifier` / `raw` / 嵌套 `sql` 辅助器按原语义处理
+   * @returns 与浏览器路径同形状的结果
+   * @throws {@link RxDBAdapterDesktopError} 会话已关闭，或 host 报告执行失败时
+   */
+  async sql<T>(sqlStrings: TemplateStringsArray, ...params: unknown[]): Promise<Results<T>> {
+    this.#assertOpen();
+    const compiled = compileTemplate(sqlStrings, ...params);
+    return this.#exclusive(async () => this.#queryOn(undefined, compiled.query, compiled.params));
+  }
+
+  /**
+   * 执行一段多语句脚本（简单查询协议）。
+   *
+   * @param query - 一条或多条以 `;` 分隔的语句
+   * @param options - **必须省略**，见 {@link assertNoQueryOptions}
+   * @returns 每条语句一个结果
+   * @throws {@link RxDBAdapterDesktopError} 会话已关闭、传了 `options`，或 host 报告执行失败时
+   */
+  async exec(query: string, options?: QueryOptions): Promise<Results[]> {
+    this.#assertOpen();
+    assertNoQueryOptions(options);
+    return this.#exclusive(async () => this.#execOn(undefined, query));
+  }
+
+  /**
+   * 在主进程那条唯一连接上开一条真事务。
+   *
+   * @remarks
+   * 回调拿到的 `tx` 是个代理：它的每条语句都带着 host 签发的事务 ID 过去，因此确实落在
+   * 同一条 PostgreSQL 事务里，而不是被包装成「看起来像事务」的独立请求（AC#2）。
+   * 回调正常返回即 `pg.commit`，抛出即 `pg.rollback`——与 PGlite 自己的语义一致。
+   *
+   * @param callback - 事务体
+   * @returns 回调的返回值
+   * @throws 回调抛出的原始异常（事务已回滚），或 {@link RxDBAdapterDesktopError}
+   */
+  async transaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T> {
+    this.#assertOpen();
+    return this.#exclusive(() => this.#runTransaction(callback));
+  }
+
+  /**
+   * 报告 host 侧 PostgreSQL 的版本串。
+   *
+   * @returns 形如 `PostgreSQL 17.x ...` 的版本串
+   */
+  async version(): Promise<string> {
+    this.#assertOpen();
+    return this.#exclusive(
+      async () =>
+        assertDesktopPgliteResponse('pg.version', await this.#send({ kind: 'pg.version', sessionId: this.sessionId }))
+          .result
+    );
+  }
+
+  /**
+   * 在 host 的一致快照上逐项读取数据目录（US-217）。
+   *
+   * @remarks
+   * host 在本会话那条唯一连接上开事务并 `CHECKPOINT`，`fn` 返回之前一直占着它：没有写入能落进
+   * 正在读的文件，快照边界前已提交的 WAL 也都已落进数据文件（AC#16）。
+   *
+   * - **独占**：整段排在本地互斥里，同一客户端的其他语句等快照结束再发。否则它们在 host 上
+   *   排在快照后面，而快照又在等 renderer 来取下一块——两边互等。
+   * - **背压**：`items` 每被取一项才发一次 `pg.backup.next`，同一时刻至多一个在途请求，
+   *   renderer 不取，host 就不读下一块（AC#21）。
+   * - **收尾**：无论 `fn` 读完、提前返回还是抛出，都发 `pg.backup.end` 交还连接（AC#19）。
+   *   `fn` 失败时收尾失败不覆盖原始错误；`fn` 成功而收尾失败则整体失败——快照没结束的
+   *   备份不能报成功。
+   *
+   * 等连接空闲的上限沿用构造参数里的 `beginTimeout`（与 `pg.begin` 同档）：契约方法不带
+   * 备份选项，`lockTimeoutMs` 传不到这里；到期由 host 以 `transaction_unavailable` 拒绝。
+   *
+   * @param fn - 消费快照的回调；`items` 只在回调返回之前有效
+   * @returns 回调的返回值
+   * @throws {@link RxDBAdapterDesktopError} 会话已关闭、host 不带备份能力（`unsupported_operation`）、
+   * 等不到连接或收尾失败时；`fn` 抛出的错误原样重抛
+   */
+  async snapshotDataDir<T>(fn: (items: AsyncIterable<PGliteDataDirItem>) => Promise<T>): Promise<T> {
+    this.#assertOpen();
+    return this.#exclusive(async () => {
+      const begun = assertDesktopPgliteResponse(
+        'pg.backup.begin',
+        await this.#send({
+          kind: 'pg.backup.begin',
+          sessionId: this.sessionId,
+          timeout: this.#options.beginTimeout ?? DESKTOP_PGLITE_DEFAULT_BEGIN_TIMEOUT_MS
+        })
+      );
+      const backupId = begun.result.backupId;
+      const end = async (): Promise<void> => {
+        assertDesktopPgliteResponse(
+          'pg.backup.end',
+          await this.#send({ kind: 'pg.backup.end', sessionId: this.sessionId, backupId })
+        );
+      };
+
+      let result: T;
+      try {
+        result = await fn(this.#backupItems(backupId));
+      } catch (error) {
+        // 收尾失败不覆盖原始错误：调用方要看的是消费方那条，而不是收摊那条。
+        await end().catch(() => undefined);
+        throw error;
+      }
+      await end();
+      return result;
+    });
+  }
+
+  /**
+   * 断开会话。
+   *
+   * @remarks
+   * 等在途请求与开着的事务跑完再关，因此调用方返回时 host 上确实已经没有本会话的
+   * 任何残留。并发调用共享同一个关闭流程。
+   */
+  async disconnect(): Promise<void> {
+    this.#closePromise ??= this.#runClose(true);
+    await this.#closePromise;
+  }
+
+  /**
+   * 不等在途请求，直接让 host 释放本会话。
+   *
+   * @remarks
+   * host 收到 `pg.close` 会把本会话仍开着的事务全部回滚，因此「不等」丢掉的只是那些
+   * 未提交的写——这正是 `forceClose` 与 {@link DesktopPGliteClient.disconnect} 的区别。
+   */
+  async forceClose(): Promise<void> {
+    this.#closePromise ??= this.#runClose(false);
+    await this.#closePromise;
+  }
+
+  /**
+   * 校验 `pg.open` 应答；目标此刻归恢复流程所有时，改报备份契约里的码。
+   *
+   * @remarks
+   * `restore_in_progress` / `restore_incomplete` 说的不是「连接坏了」，而是「这个目录正被恢复
+   * 或留着一次没做完的恢复」（AC#11、#12）：调用方要么等，要么调
+   * `cleanupIncompleteElectronPGliteRestore()` 收拾，只有按备份契约写的判断接得住。
+   * 其余打不开的原因与恢复无关，仍是桌面错误。
+   */
+  #assertOpened(response: unknown): Extract<DesktopPgliteResponse, { kind: 'pg.open' }> {
+    try {
+      return assertDesktopPgliteResponse('pg.open', response);
+    } catch (error) {
+      if (error instanceof RxDBAdapterDesktopError && RESTORE_CONFLICT_CODES.has(error.code)) {
+        throw toElectronPGliteBackupError(error, this.#options.dataDirectoryName, 'restore');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 解析 `pg.open` 结果；解析不过就先把 host 上刚开出来的会话关掉，再抛原始错误。
+   *
+   * @remarks
+   * 走到这里说明 host 已经建好数据目录、起了实例、登记了会话，而 renderer 才发现结果
+   * 形状不对。此时调用方拿不到 client，也就永远没有关掉那条会话的把手。
+   */
+  async #parseOpenResultOrClose(result: unknown): Promise<{ sessionId: string; resolvedLocation: string }> {
+    try {
+      return parseDesktopPgliteOpenResult(result);
+    } catch (error) {
+      const record = typeof result === 'object' && result !== null ? (result as Record<string, unknown>) : undefined;
+      const sessionId = record?.['sessionId'];
+      if (typeof sessionId === 'string') {
+        // 收摊失败不上报：连接已经带着准确的原因失败了，把它盖掉只会让诊断更远。
+        await this.#options.transport.request({ kind: 'pg.close', sessionId }).catch(() => undefined);
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * 等变更推送通道真正建好，失败就回滚刚打开的会话。
+   *
+   * @remarks
+   * 订阅建不起来意味着响应式查询永远不刷新。返回一个「能查、但永不刷新」的客户端是所有
+   * 故障形态里最难查的一种，所以这里让 `init()` 直接失败。
+   */
+  async #awaitSubscription(): Promise<void> {
+    try {
+      await this.#options.transport.subscriptionReady?.();
+    } catch (error) {
+      const sessionId = this.#sessionId;
+      this.#closed = true;
+      this.#unsubscribe?.();
+      await this.#send({ kind: 'pg.close', sessionId: sessionId! }).catch(() => undefined);
+      throw new RxDBAdapterDesktopError(
+        'host_unavailable',
+        `desktop PGlite session ${String(sessionId)} could not subscribe to host notifications`,
+        { cause: error }
+      );
+    }
+  }
+
+  async #runClose(drain: boolean): Promise<void> {
+    if (drain) await this.#lock.catch(() => undefined);
+    this.#closed = true;
+    if (drain) await this.#tail.catch(() => undefined);
+    const sessionId = this.#sessionId;
+    this.#unsubscribe?.();
+    this.#batcher.clear();
+    this.removeAllEventListeners();
+    if (!sessionId) return;
+    assertDesktopPgliteResponse('pg.close', await this.#options.transport.request({ kind: 'pg.close', sessionId }));
+  }
+
+  async #runTransaction<T>(callback: (tx: Transaction) => Promise<T>): Promise<T> {
+    const begun = assertDesktopPgliteResponse(
+      'pg.begin',
+      await this.#send({
+        kind: 'pg.begin',
+        sessionId: this.sessionId,
+        ...(this.#options.beginTimeout === undefined ? {} : { timeout: this.#options.beginTimeout })
+      } as DesktopPgliteRequest)
+    );
+    const transactionId = begun.result.transactionId;
+    let settled = false;
+
+    const end = async (kind: 'pg.commit' | 'pg.rollback'): Promise<void> => {
+      settled = true;
+      assertDesktopPgliteResponse(kind, await this.#send({ kind, sessionId: this.sessionId, transactionId }));
+    };
+    const assertLive = (): void => {
+      if (settled) {
+        throw new RxDBAdapterDesktopError('transaction_not_found', `transaction ${transactionId} is already closed`);
+      }
+    };
+
+    const tx: Transaction = {
+      query: async <R>(sql: string, params?: unknown[], options?: QueryOptions): Promise<Results<R>> => {
+        assertLive();
+        assertNoQueryOptions(options);
+        return this.#queryOn(transactionId, sql, params);
+      },
+      exec: async (sql: string, options?: QueryOptions): Promise<Results[]> => {
+        assertLive();
+        assertNoQueryOptions(options);
+        return this.#execOn(transactionId, sql);
+      },
+      rollback: async (): Promise<void> => {
+        assertLive();
+        await end('pg.rollback');
+      },
+      sql: async <R>(sqlStrings: TemplateStringsArray, ...values: unknown[]): Promise<Results<R>> => {
+        assertLive();
+        const compiled = compileTemplate(sqlStrings, ...values);
+        return this.#queryOn(transactionId, compiled.query, compiled.params);
+      },
+      // `listen` 代理不了：它要在**这条连接**上挂一个回调，而回调过不了进程边界。
+      // 静默降级成「订阅了但永远收不到」是最难查的一种故障，所以当场炸。
+      // 事务内的通知请改用 renderer 侧的 NOTIFY 批量器（本客户端已经在监听）。
+      listen: (): Promise<(tx?: Transaction) => Promise<void>> => {
+        throw unsupportedTransactionOperation('listen');
+      },
+      get closed(): boolean {
+        return settled;
+      }
+    };
+
+    try {
+      const result = await callback(tx);
+      if (!settled) await end('pg.commit');
+      return result;
+    } catch (error) {
+      // 回滚失败不覆盖原始错误：调用方要看的是业务那条，而不是收摊那条。
+      if (!settled) await end('pg.rollback').catch(() => undefined);
+      throw error;
+    }
+  }
+
+  async #queryOn<T>(transactionId: string | undefined, sql: string, params?: unknown[]): Promise<Results<T>> {
+    const request: DesktopPgliteRequest = {
+      kind: 'pg.query',
+      sessionId: this.sessionId,
+      sql,
+      params: (params ?? []) as readonly DesktopPgliteParam[],
+      ...(transactionId === undefined ? {} : { transactionId })
+    };
+    return toResults<T>(assertDesktopPgliteResponse('pg.query', await this.#send(request)).result);
+  }
+
+  /**
+   * 快照的逐项迭代器。
+   *
+   * @remarks
+   * 异步生成器自带排队：消费方连调两次 `next()`，第二次也要等第一次的 `pg.backup.next`
+   * 回来才发，背压因此不依赖消费方守规矩。
+   */
+  async *#backupItems(backupId: string): AsyncGenerator<PGliteDataDirItem> {
+    for (;;) {
+      const next = assertDesktopPgliteResponse(
+        'pg.backup.next',
+        await this.#send({ kind: 'pg.backup.next', sessionId: this.sessionId, backupId })
+      );
+      const item = parseDesktopPgliteBackupItem(next.result);
+      if (item.type === 'end') return;
+      yield item;
+    }
+  }
+
+  async #execOn(transactionId: string | undefined, sql: string): Promise<Results[]> {
+    const request: DesktopPgliteRequest = {
+      kind: 'pg.exec',
+      sessionId: this.sessionId,
+      sql,
+      ...(transactionId === undefined ? {} : { transactionId })
+    };
+    return assertDesktopPgliteResponse('pg.exec', await this.#send(request)).result.map(result => toResults(result));
+  }
+
+  /**
+   * 独占执行：事务整段、单条自动提交语句各算一次。
+   *
+   * @remarks
+   * 必须在任何 `await` 之前**同步**接上队尾，否则两个并发调用会抢到同一个队尾，
+   * 互斥退化成没有。
+   */
+  #exclusive<T>(run: () => Promise<T>): Promise<T> {
+    const settled = this.#lock.then(run);
+    this.#lock = settled.then(undefined, () => undefined);
+    return settled;
+  }
+
+  /**
+   * 把一个请求排进会话队列，队列空了才发上传输层。
+   *
+   * @remarks
+   * 一个会话同一时刻只允许有一个在途请求：会话在 host 侧就是同一条 PGlite 连接上的
+   * 一串调用，允许交错的话「先发的先执行」不再成立，一条 `SELECT` 可能挤到 `DELETE`
+   * 前面跑，上层看到的是刚删掉的行还在。
+   */
+  #send(payload: DesktopPgliteRequest): Promise<unknown> {
+    const settled = this.#tail.then(() => this.#options.transport.request(payload));
+    this.#tail = settled.then(undefined, () => undefined);
+    return settled;
+  }
+
+  #assertOpen(): void {
+    if (this.#closed || !this.#sessionId) {
+      throw new RxDBAdapterDesktopError(
+        'session_closed',
+        `desktop PGlite session ${String(this.#sessionId)} is not open`
+      );
+    }
+  }
+
+  /**
+   * 收下一条 host 推送。
+   *
+   * @remarks
+   * 变更通道是全 renderer 共享的：SQLite host 的 `change` 消息、别的会话的 NOTIFY 都会
+   * 从这里过。先按 `kind` 与 `sessionId` 筛掉不属于自己的，再解析——顺序反过来的话，
+   * 一条本来就不该由自己处理的消息会因为形状不符而抛错。
+   */
+  #onMessage(message: unknown): void {
+    if (this.#closed) return;
+    if (typeof message !== 'object' || message === null) return;
+    if ((message as { kind?: unknown }).kind !== 'pg.notify') return;
+    if ((message as { sessionId?: unknown }).sessionId !== this.#sessionId) return;
+    try {
+      const notification = parseDesktopPgliteNotifyMessage(message);
+      this.#batcher.accept(notification.channel, notification.payload);
+    } catch (error) {
+      reportOutOfBand(error);
+    }
+  }
+}

package/src/pglite/desktop-pglite-results.ts

@@ -0,0 +1,24 @@
+/**
+ * host 查询应答到 PGlite `Results` 的还原，普通会话与恢复校验共用。
+ *
+ * @module pglite/desktop-pglite-results
+ */
+
+import type { DesktopPgliteQueryResult } from '@aiao/rxdb-adapter-sqlite-core/desktop-host';
+import type { Results } from '@electric-sql/pglite';
+
+/**
+ * 把 host 的应答还原成 PGlite 的 `Results`。
+ *
+ * @remarks
+ * `rows` 里的值已经是 PG 的原生 JS 表示（bigint / `Uint8Array` / `Date` / 普通对象），
+ * 结构化克隆逐值搬过来，这里不做任何再解析——多一层转换就多一处能悄悄丢精度的地方。
+ *
+ * @param result - 已通过协议校验的查询结果
+ * @returns 与浏览器路径同形状的结果
+ */
+export const toDesktopPGliteResults = <T>(result: DesktopPgliteQueryResult): Results<T> => ({
+  rows: result.rows as unknown as T[],
+  fields: result.fields.map(field => ({ name: field.name, dataTypeID: field.dataTypeID })),
+  affectedRows: result.affectedRows
+});