@aiao/rxdb-plugin-history 0.0.0-stage → 0.0.26

package/src/history-scope-api.ts

@@ -0,0 +1,189 @@
+import {
+  EntityType,
+  getEntityMetadata,
+  type HistoryItem,
+  type HistoryScope,
+  type HistoryScopeAPI,
+  RxDBEntityId
+} from '@aiao/rxdb';
+import { firstValueFrom, map, Observable, shareReplay } from 'rxjs';
+import { filterHistoriesByScope, filterUndoableHistories, getScopeKey } from './history-filters.js';
+import type { ActiveUndoSession, UndoBoundary, UndoSession } from './history-undo-session.types.js';
+/**
+ * `history()` 工厂所需的可变状态与委托。
+ *
+ * `history_cache` / `history_ref_counts` 是类持有的同一份 Map，sibling 的 set/delete 必须写回。
+ */
+export interface HistoryScopeApiHost {
+  readonly history_cache: Map<string, HistoryScopeAPI>;
+  readonly history_ref_counts: Map<string, number>;
+  readonly histories$: Observable<HistoryItem[]>;
+  readonly undoHistories$: Observable<HistoryItem[]>;
+  readonly redoHistories$: Observable<HistoryItem[]>;
+  readonly undoSession$: { readonly value: UndoSession };
+  runSerialized<T>(task: () => Promise<T>): Promise<T>;
+  fetchLatestHistories(boundary: UndoBoundary): Promise<{
+    histories: HistoryItem[];
+    lastPushedMap: Map<string, number>;
+  }>;
+  isUndoSessionCurrent(session: ActiveUndoSession): boolean;
+  selectWholeTransactions(histories: HistoryItem[], scope: HistoryScope, step: number): HistoryItem[];
+  applyUndoRedoHistories(
+    operation: 'undo' | 'redo',
+    histories: HistoryItem[],
+    undoSession?: ActiveUndoSession
+  ): Promise<void>;
+}
+
+/**
+ * 解析 `history()` 入参：无参 → database；显式 HistoryScope；否则 EntityType / 实例。
+ */
+export function resolveHistoryScope<T extends EntityType>(options?: T | InstanceType<T> | HistoryScope): HistoryScope {
+  if (!options) return { type: 'database' };
+  if (Object.getPrototypeOf(options) === Object.prototype && 'type' in options) {
+    return options as HistoryScope;
+  }
+
+  const metadata = getEntityMetadata(options as T | InstanceType<T>);
+  const id = 'id' in options ? (options as { id: unknown }).id : undefined;
+  const entityId: RxDBEntityId | undefined =
+    typeof id === 'string' || typeof id === 'number' || typeof id === 'bigint' ? id : undefined;
+  if (entityId !== undefined) {
+    return {
+      type: 'entity',
+      namespace: metadata.namespace,
+      entity: metadata.name,
+      entityId
+    };
+  }
+  return {
+    type: 'repository',
+    namespace: metadata.namespace,
+    entity: metadata.name
+  };
+}
+
+/**
+ * 创建（或从缓存取出）特定作用域的历史 API。
+ *
+ * @remarks
+ * 引用计数由 wrapObservable 对称管理（addRef / cleanup 成对出现），不再挂 finalize。
+ * 缓存条目的生死跟着引用计数走：第一个订阅者出现时入表，最后一个退订时摘掉。
+ * 因此「只调方法不订阅」的用法不产生任何常驻状态 —— 它拿到的是个短命对象，
+ * 用完即由 GC 回收。
+ */
+export function createHistoryScopeApi<T extends EntityType>(
+  host: HistoryScopeApiHost,
+  options?: T | InstanceType<T> | HistoryScope
+): HistoryScopeAPI {
+  const scope = resolveHistoryScope(options);
+  const cacheKey = getScopeKey(scope);
+
+  const cached = host.history_cache.get(cacheKey);
+  if (cached) return cached;
+
+  const cleanup = () => {
+    const count = (host.history_ref_counts.get(cacheKey) || 0) - 1;
+    if (count <= 0) {
+      host.history_cache.delete(cacheKey);
+      host.history_ref_counts.delete(cacheKey);
+    } else {
+      host.history_ref_counts.set(cacheKey, count);
+    }
+  };
+
+  const addRef = () => {
+    const count = (host.history_ref_counts.get(cacheKey) || 0) + 1;
+    host.history_ref_counts.set(cacheKey, count);
+    // 入表推迟到第一个订阅者出现，与 `cleanup` 的摘除严格对称。
+    // 此前在函数末尾无条件入表：只调方法不订阅（`history(record).undo()`）的调用方
+    // 引用计数永远是 0，`cleanup` 永远不跑，条目就永久留下 —— 而 cacheKey 是按
+    // 记录 id 分的，每 undo 一条不同记录就多漏一条，没有上界。
+    host.history_cache.set(cacheKey, api);
+  };
+
+  const wrapObservable = <U>(source: Observable<U>): Observable<U> =>
+    new Observable(subscriber => {
+      addRef();
+      const sub = source.subscribe(subscriber);
+      return () => {
+        sub.unsubscribe();
+        cleanup();
+      };
+    });
+
+  const base_histories$ = host.histories$.pipe(
+    map(histories => filterHistoriesByScope(histories, scope)),
+    shareReplay({ bufferSize: 1, refCount: true })
+  );
+  const scoped_histories$ = wrapObservable(base_histories$);
+  const scoped_undo_histories$ = wrapObservable(
+    host.undoHistories$.pipe(
+      map(histories => filterHistoriesByScope(histories, scope)),
+      shareReplay({ bufferSize: 1, refCount: true })
+    )
+  );
+  const scoped_redo_histories$ = wrapObservable(
+    host.redoHistories$.pipe(
+      map(histories => filterHistoriesByScope(histories, scope)),
+      shareReplay({ bufferSize: 1, refCount: true })
+    )
+  );
+  const scoped_count$ = wrapObservable(
+    base_histories$.pipe(
+      map(h => h.length),
+      shareReplay({ bufferSize: 1, refCount: true })
+    )
+  );
+  const scoped_undo_count$ = wrapObservable(
+    scoped_undo_histories$.pipe(
+      map(h => h.length),
+      shareReplay({ bufferSize: 1, refCount: true })
+    )
+  );
+  const scoped_redo_count$ = wrapObservable(
+    scoped_redo_histories$.pipe(
+      map(h => h.length),
+      shareReplay({ bufferSize: 1, refCount: true })
+    )
+  );
+
+  const api: HistoryScopeAPI = {
+    type: scope.type,
+    histories$: scoped_histories$,
+    undoHistories$: scoped_undo_histories$,
+    redoHistories$: scoped_redo_histories$,
+    count$: scoped_count$,
+    undoCount$: scoped_undo_count$,
+    redoCount$: scoped_redo_count$,
+
+    undo: (step = 1) =>
+      host.runSerialized(async () => {
+        const undoSession = host.undoSession$.value;
+        if (undoSession.state === 'cleared') return;
+
+        const { histories, lastPushedMap } = await host.fetchLatestHistories(undoSession.boundary);
+        if (!host.isUndoSessionCurrent(undoSession)) return;
+
+        const undoable = filterUndoableHistories(
+          histories,
+          lastPushedMap,
+          undoSession.boundary.changeId,
+          undoSession.boundary.createdAfter
+        );
+        const toUndo = host.selectWholeTransactions(undoable, scope, step);
+        if (toUndo.length === 0) return;
+        await host.applyUndoRedoHistories('undo', toUndo, undoSession);
+      }),
+
+    redo: (step = 1) =>
+      host.runSerialized(async () => {
+        const histories = await firstValueFrom(host.redoHistories$);
+        const toRedo = host.selectWholeTransactions(histories, scope, step);
+        if (toRedo.length === 0) return;
+        await host.applyUndoRedoHistories('redo', toRedo);
+      })
+  };
+
+  return api;
+}

package/src/history-undo-session.types.ts

@@ -0,0 +1,37 @@
+/**
+ * undo session 类型：按分支隔离的撤销边界。
+ *
+ * @internal 供 {@link HistoryManager} 与 undo/redo sibling 共用
+ */
+
+/** 同步清空后的永久撤销边界 */
+export type UndoBoundary = Readonly<{
+  changeId: number;
+  createdAfter: Date | null;
+}>;
+
+/** 当前可撤销的 session */
+export type ActiveUndoSession = Readonly<{
+  generation: number;
+  state: 'active';
+  boundary: UndoBoundary;
+}>;
+
+/** 同步后已清空、等待本地新写入再恢复的 session */
+export type ClearedUndoSession = Readonly<{
+  generation: number;
+  state: 'cleared';
+  boundary: UndoBoundary;
+  clearedAt: Date;
+}>;
+
+export type UndoSession = ActiveUndoSession | ClearedUndoSession;
+
+/** 本地写入事件携带的 session 归属信息 */
+export type UndoSessionEvent = Readonly<{
+  generation: number | null;
+  recordAt: Date | null;
+}>;
+
+/** 未发生过清空时的默认边界 */
+export const INITIAL_UNDO_BOUNDARY: UndoBoundary = { changeId: 0, createdAfter: null };

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @packageDocumentation
+ * `@aiao/rxdb-plugin-history` —— 历史、撤销重做与分支。
+ *
+ * @remarks
+ * 核心 `@aiao/rxdb` 只保留**原语**：三张系统表（{@link RxDBBranch} / `RxDBChange` /
+ * `RxDBSync`）、变更编解码、冲突模型与同步资格判定。原因是这些东西并不属于历史子系统 ——
+ * 变更日志触发器直接写 `branchId`，`RxDBChange.branch` 会生成真实的
+ * `REFERENCES rxdb$rxdb_branch(id)` 外键，整条响应式增量链路都跑在 `rxdb_change` 上。
+ *
+ * 搬进本包的是**消费者**：读历史、撤销重做、建/切/合/删分支。
+ *
+ * 推拉同步的调度**不在这里**。US-025 阶段 D 之后它住在 `@aiao/rxdb-plugin-sync`：
+ * `rxdb.syncManager.push()` / `.pull()` / `.sync()`。那个插件 `inject: ['plugin:history']`，
+ * 反向则没有依赖——本包不认识同步包。
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ *
+ * rxdb.use(rxDBPluginHistory);
+ * await rxdb.connect();
+ *
+ * // 撤销重做走作用域 API：无参 = 整库，传实体类 = 该仓储，传实例 = 该行
+ * await rxdb.versionManager.history().undo();
+ * ```
+ */
+export * from './plugin.js';
+// 作用域 undo/redo 撞上跨作用域事务时抛给调用方的结构化错误。
+// 选择谓词（isChangeInScope 等）是 HistoryManager 的内部实现，不进公开 API。
+export { RxDBCrossScopeTransactionError } from './scope-selection.js';
+// 实例由插件装配，用户不自己 new，因此只转类型不转类。
+export type { VersionManager } from './VersionManager.js';
+
+// ---------------------------------------------------------------------------
+// 以下四项只为 `@aiao/rxdb-plugin-sync` 而导出，全部标了 `@internal`：
+// 同步插件是本包唯一的下游插件（它 `inject: ['plugin:history']`），一次 pull / push
+// 结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人在本包。接口窄且单向，
+// 见 `sync-history-bridge.ts` 的文件头。应用代码不该引用它们。
+// ---------------------------------------------------------------------------
+export { isIgnorableDetachedVersionEventError } from './detached-event-error.js';
+// 登记处是**类**导出而非类型导出：同步插件的 push 用例要 `new` 一个真的出来
+// （替身会把要验的东西验掉），而两包之间只有 `dist` 一条路，没有深路径可走。
+export { PushInFlightRegistry } from './push-inflight.js';
+export type { PushInFlightSession } from './push-inflight.js';
+export type { SyncHistoryBridge } from './sync-history-bridge.js';

package/src/merge-branch.ts

@@ -0,0 +1,153 @@
+import { getRxDBChangeKey, MergeBranchOptions, MergeBranchResult, RxDBError, SwitchVersionActions } from '@aiao/rxdb';
+import { VersionManager } from './VersionManager.js';
+import { remove_branch } from './remove-branch.js';
+import { get_switch_version_actions } from './switch-branch-actions.js';
+
+/**
+ * 合并分支
+ *
+ * 将源分支的变更合并到当前激活分支（目标分支）。
+ *
+ * 支持两种策略：
+ * - `squash`（默认）：将源分支所有变更压缩为最小操作集后应用，过滤幽灵操作（源分支内
+ *   INSERT 后又 DELETE 的实体不会影响目标分支）
+ * - `normal`：逐条应用源分支变更，每条变更在目标分支产生独立的变更记录，不过滤幽灵操作
+ *
+ * 合并后可选删除源分支。
+ *
+ * @param version - VersionManager 实例
+ * @param sourceBranchId - 源分支 ID
+ * @param currentBranchId - 当前激活分支 ID（由调用方提供，避免重复查询）
+ * @param options - 合并选项
+ * @returns 合并结果
+ */
+export const merge_branch = async (
+  version: VersionManager,
+  sourceBranchId: string,
+  currentBranchId: string,
+  options?: MergeBranchOptions
+): Promise<MergeBranchResult> => {
+  const strategy = options?.strategy ?? 'squash';
+  const deleteSource = options?.deleteSource ?? false;
+
+  const { branchRepository, changeRepository, adapter } = await version.getLocalRepositories();
+
+  // 验证：源分支不能是目标分支
+  if (sourceBranchId === currentBranchId) {
+    throw new RxDBError(`Cannot merge branch '${sourceBranchId}' into itself`);
+  }
+
+  // 验证：源分支必须存在
+  const sourceBranch = (
+    await branchRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [{ field: 'id', operator: '=', value: sourceBranchId }]
+      },
+      limit: 1
+    })
+  )[0];
+
+  if (!sourceBranch) {
+    throw new RxDBError(`Branch '${sourceBranchId}' not found`);
+  }
+
+  // 查询源分支从 fromChangeId 之后的所有有效变更
+  const sourceChanges = await changeRepository.find({
+    where: {
+      combinator: 'and',
+      rules: [
+        { field: 'branchId', operator: '=', value: sourceBranchId },
+        { field: 'revertChangeId', operator: '=', value: null },
+        ...(sourceBranch.fromChangeId != null ?
+          [{ field: 'id' as const, operator: '>' as const, value: sourceBranch.fromChangeId }]
+        : [])
+      ]
+    },
+    orderBy: [{ field: 'id', sort: 'asc' }]
+  });
+
+  /**
+   * 删源分支：合并落库之后的收尾动作。
+   *
+   * 失败不上抛 —— 合并已经落库且触发器已生成目标分支的变更记录，把它判成整体失败会让
+   * 调用方重试，normal 策略下就是二次合并。这里只如实返回「没删成」与原因。
+   */
+  const doDeleteSource = async (): Promise<{ deleted: boolean; error?: Error }> => {
+    if (!deleteSource) return { deleted: false };
+    try {
+      await remove_branch(version, sourceBranchId);
+      return { deleted: true };
+    } catch (error) {
+      return { deleted: false, error: error instanceof Error ? error : new Error(String(error)) };
+    }
+  };
+
+  const toResult = (mergedCount: number, deleteResult: { deleted: boolean; error?: Error }): MergeBranchResult => ({
+    merged: mergedCount,
+    strategy,
+    sourceDeleted: deleteResult.deleted,
+    ...(deleteResult.error ? { sourceDeleteError: deleteResult.error } : {})
+  });
+
+  // 空分支：无变更需要合并
+  if (sourceChanges.length === 0) {
+    return toResult(0, await doDeleteSource());
+  }
+
+  let merged: number;
+
+  if (strategy === 'normal') {
+    // normal 策略：逐条应用源分支变更，每条变更在目标分支产生独立的变更记录。
+    //
+    // 整个循环必须在**一个**事务里：单次 mergeChanges 在适配器内部虽已是事务，
+    // 但 N 次就是 N 个独立事务 —— 第 k 条失败时前 k-1 条已落库、触发器也已在目标分支
+    // 生成对应 RxDBChange，留下「合了一半」的状态。
+    //
+    // 循环内必须调 `executor.mergeChanges` 而非 `adapter.mergeChanges`：持有 executor 才算
+    // 在本事务内。旧写法靠适配器的环境态推断「已在事务中就复用」，那正是 C2 要拆掉的东西 ——
+    // 翻转后它会从「复用当前事务」变成「重新排队」，排在自己身后直接自锁。
+    await adapter.transaction(async executor => {
+      for (const change of sourceChanges) {
+        const singleActions: SwitchVersionActions = {
+          deletes: new Map(),
+          updates: new Map(),
+          inserts: new Map()
+        };
+        const key = getRxDBChangeKey(change);
+        if (change.type === 'INSERT') {
+          singleActions.inserts.set(key, { patch: change.patch!, inversePatch: null });
+        } else if (change.type === 'UPDATE') {
+          singleActions.updates.set(key, { patch: change.patch!, inversePatch: change.inversePatch! });
+        } else if (change.type === 'DELETE') {
+          singleActions.deletes.set(key, { patch: null, inversePatch: change.inversePatch! });
+        }
+        await executor.mergeChanges(singleActions, undefined, false);
+      }
+    });
+    merged = sourceChanges.length;
+  } else {
+    // squash 策略：压缩为目标分支最终状态的最小操作集
+    const actions = get_switch_version_actions(sourceChanges, true);
+
+    // 过滤幽灵删除：在源分支内创建后又删除的实体，对目标分支无净贡献
+    const createdInSource = new Set(sourceChanges.filter(c => c.type === 'INSERT').map(c => getRxDBChangeKey(c)));
+    for (const key of createdInSource) {
+      if (actions.deletes.has(key)) {
+        actions.deletes.delete(key);
+      }
+    }
+
+    merged = actions.inserts.size + actions.updates.size + actions.deletes.size;
+
+    if (merged === 0) {
+      return toResult(0, await doDeleteSource());
+    }
+
+    // 应用变更到当前分支的实体表
+    // disableTriggers=false：让数据库触发器自动生成目标分支的 RxDBChange 记录
+    await adapter.mergeChanges(actions, undefined, false);
+  }
+
+  return toResult(merged, await doDeleteSource());
+};

package/src/plugin.ts

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview RxDB 历史 / 撤销重做 / 分支插件
+ * 把 {@link VersionManager} 装进宿主的连接纪元，并把「可推送变更数」接回核心的同步状态枢纽。
+ *
+ * @module rxdb-plugin-history
+ */
+
+import { IRxDBPlugin, Plugin, RxDB, RxDBPluginBase } from '@aiao/rxdb';
+import type { LifecycleScope } from '@aiao/utils';
+import { VersionManager } from './VersionManager.js';
+
+/** 本插件当前不接受任何选项 */
+export type RxDBPluginHistoryOptions = object;
+
+/**
+ * 历史 / 撤销重做 / 分支插件。
+ *
+ * @remarks
+ * **不声明 `inject`**：`VersionManager.init()` 只挂事件监听与订阅，一条适配器读写都不发。
+ * 声明 `adapter:local` 会把安装推到引导链之后，而 `HistoryManager` 的分支流必须在第一条
+ * `rxdb_change` 事件到达之前就已经订阅上——装晚了，那一批变更不进历史。这也正是搬进插件
+ * 之前的时序：核心在构造器里 `new VersionManager()`、在 `init()` 里调 `init()`，
+ * 两者都早于 `schemaManager.init()`。
+ *
+ * 两处宿主改动都登记在 `scope` 上，断开连接时由宿主逆序释放：
+ *
+ * 1. `rxdb.versionManager` 这个实例槽位 —— 释放时连同 `destroy()` 一起撤掉，不给下一个
+ *    纪元留一个指向已拆事件总线的管理器。槽位排在最先获取，因而最后撤，`destroy()`
+ *    才跑得在槽位仍可读的窗口里；
+ * 2. {@link RxDB.syncState} 上的可推送计数订阅 —— 枢纽活得和实例一样长，计数却只在连接
+ *    期间有意义，因此走 `bindPushableCount()` 拿一个解绑函数，而不是在构造枢纽时传进去。
+ *
+ * 同一枢纽上的「重算待拉数」跳板**不在这里**：`refreshPullableCount()` 随 US-025 阶段 D
+ * 去了 `@aiao/rxdb-plugin-sync`，接住 `requestPullableRefresh()` 于是也是那个插件的活。
+ * 只装历史不装同步时那个请求发进空里，正是「没有同步就没有待拉数」的实情。
+ */
+export class RxDBPluginHistory extends RxDBPluginBase implements IRxDBPlugin {
+  readonly lifecycle = 'scoped' as const;
+  name: Uncapitalize<string> = 'history';
+
+  install(scope: LifecycleScope) {
+    const versionManager = new VersionManager(this.rxdb);
+
+    // 槽位**先**获取，于是最后一个撤：撤销序是获取序的逆序，`destroy()` 因此跑在
+    // 「`rxdb.versionManager` 还读得到」的窗口里。反过来登记的话，正卡在 await 中途的
+    // 历史流（如 `HistoryManager` 的可撤销列表管线）恢复执行时读到 `undefined`，
+    // 一次正常断开就伪装成 TypeError 落进 `errors$`。
+    scope.acquire(() => {
+      Object.defineProperty(this.rxdb, 'versionManager', {
+        value: versionManager,
+        configurable: true,
+        enumerable: true
+      });
+      return () => void Reflect.deleteProperty(this.rxdb, 'versionManager');
+    }, 'history:slot');
+
+    // 构造器里就订阅了活跃分支流（`HistoryManager`），所以「造出来」本身已经是一次资源获取：
+    // 先把撤销登记上，再让它开始工作。`init()` 因此不需要自己一条 `acquire()` ——
+    // 它登记的事件监听与订阅全都由同一个 `destroy()` 收，中途抛错也够得着。
+    scope.acquire(() => () => versionManager.destroy(), 'history:versionManager');
+
+    versionManager.init();
+
+    scope.acquire(() => this.rxdb.syncState.bindPushableCount(versionManager.pushableCount$), 'history:pushableCount');
+  }
+}
+
+declare module '@aiao/rxdb' {
+  interface RxDB {
+    /**
+     * 历史 / 撤销重做 / 分支子系统。
+     *
+     * @remarks
+     * 由 `@aiao/rxdb-plugin-history` 在连接纪元内装配。**没装插件时这个槽位不存在**：
+     * 读它拿到 `undefined`，而不是一个什么都不做的空壳——核心不做 fallback 兜底。
+     */
+    versionManager: VersionManager;
+  }
+}
+
+/**
+ * 历史插件工厂。
+ *
+ * @param db - 宿主实例
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ *
+ * rxdb.use(rxDBPluginHistory);
+ * ```
+ */
+export const rxDBPluginHistory: Plugin<RxDBPluginHistoryOptions> = (db: RxDB) => new RxDBPluginHistory(db);

package/src/pullable-count.ts

@@ -0,0 +1,67 @@
+/**
+ * @packageDocumentation
+ * pullable 计数的结算规则
+ *
+ * `pullableCount$` 是「远端还有多少条没拉下来」。它由远端事件累加，由一次 pull 结算。
+ * 结算的难点全在「这次 pull 到底覆盖了多少」：
+ *
+ * - `repositoryFilter` 只拉了指定仓库，其余仓库的待拉量原封不动；
+ * - `hasMore` 说明这一页拉完了还有下一页；
+ * - `failures` 里的仓库一条都没拉成。
+ *
+ * 这三种情况下把全局计数归零，界面就会显示「已经同步干净了」，而远端明明还有东西。
+ * 本模块把判据和结算算式拆成纯函数，让 {@link VersionManager.pull} 和
+ * {@link VersionManager.sync} 两条路径共用同一份口径 —— 此前后者根本不结算。
+ */
+
+import type { PullOptions, PullResult } from '@aiao/rxdb';
+
+/**
+ * 结算一次 pull 所需的全部输入
+ */
+export interface PullableSettlement {
+  /** 本次 pull 是否覆盖了当前分支的完整仓库集合，且没有遗留分页或失败 */
+  complete: boolean;
+
+  /** 结算令牌签发之后是否又有远端事件到达 */
+  concurrent: boolean;
+
+  /** 本次 pull 实际取回的变更数 */
+  pulled: number;
+}
+
+/**
+ * 判断一次 pull 是否算「完整同步」
+ *
+ * @param options - 发起 pull 时的选项
+ * @param result - pull 的结果
+ * @returns 覆盖了全部仓库、没有下一页、也没有失败仓库时返回 `true`
+ *
+ * @remarks
+ * `repositoryFilter` 传了空数组等价于不过滤：判成不完整会让绝大多数正常 pull 永远清不掉计数。
+ */
+export function isCompletePull(options: PullOptions | undefined, result: PullResult): boolean {
+  if (options?.repositoryFilter !== undefined && options.repositoryFilter.length > 0) {
+    return false;
+  }
+  return !result.hasMore && result.failures.length === 0;
+}
+
+/**
+ * 计算结算后的 pullable 计数
+ *
+ * @param current - 结算前的计数
+ * @param settlement - 结算输入
+ * @returns 结算后的计数（不会为负）
+ *
+ * @remarks
+ * 只有「完整同步」且「期间没有新的远端事件」才归零。`concurrent` 这一关是必须的：
+ * pull 期间到达的事件描述的是快照之后的新变更，本次 pull 没有覆盖它们，
+ * 归零等于把它们吞掉，界面从此再也不会提示这批数据。
+ */
+export function settledPullableCount(current: number, settlement: PullableSettlement): number {
+  if (settlement.complete && !settlement.concurrent) {
+    return 0;
+  }
+  return Math.max(0, current - settlement.pulled);
+}

package/src/push-inflight.ts

@@ -0,0 +1,91 @@
+/**
+ * 推送在飞登记：push 把「正在往远端送」的变更区间挂出来，undo 认这个区间。
+ *
+ * @module rxdb/version/push-inflight
+ */
+
+/**
+ * 一次 push 调用期间持有的认领句柄。
+ *
+ * 一次 `pushRepository` 可能同时推多个仓库（级联），因此 `claim` 可以调多次，
+ * 而 {@link release} 一次把这一轮的全部认领撤干净 —— 谁开的谁关，中途从哪条路径
+ * 提前返回都不会漏。
+ */
+export interface PushInFlightSession {
+  /**
+   * 声明本轮正在把某仓库 id ≤ `maxChangeId` 的变更送往远端。
+   *
+   * @param repositoryKey - `namespace:entity`
+   * @param maxChangeId - 本轮送出的最大 change id
+   *
+   * @remarks
+   * 同一仓库重复认领取**较大**者：级联路径分相位推同一份计划，后一相位不该把
+   * 前一相位已经罩住的区间缩回去。
+   */
+  claim(repositoryKey: string, maxChangeId: number): void;
+
+  /** 撤销本 session 的全部认领。重复调用是空操作。 */
+  release(): void;
+}
+
+/**
+ * 「哪些变更此刻正在飞往远端」的进程内登记处。
+ *
+ * @remarks
+ * 存在的理由是一个时序缺口：撤销的判据是「还没推上去」，而这件事的数据源
+ * `RxDBSync.lastPushedChangeId` 只在 push **提交**时才写。push 的远端往返在事务之外，
+ * 于是「已经发出去了、水位线还没推进」这段窗口里，`undo()` 会放行一条其实已经到达
+ * 远端的变更。
+ *
+ * 撤销**不产生新的变更行**（`undo-redo-apply.ts` 只给原行打 `revertChangeId` 标记），
+ * 而出站查询过滤 `revertChangeId = null` —— 那条变更从此远端有、本地无，且没有任何
+ * 一次 push 会把这个差异送出去。本登记处把那段窗口填上：在飞即视同已推。
+ *
+ * **只覆盖本进程。** 多 tab / Tauri 多进程共享同一份本地库时，另一个进程的 push
+ * 在这里是看不见的。跨进程要的是数据库里的一条租约行，而 push 路径目前整体就没有
+ * 跨进程互斥（两个进程会各自推同一批变更），那是另一个问题，不在这里假装解决。
+ */
+export class PushInFlightRegistry {
+  /** sessionId -> (repositoryKey -> 该 session 认领的最大 change id) */
+  readonly #sessions = new Map<number, Map<string, number>>();
+  #nextSessionId = 0;
+
+  /**
+   * 开一轮认领。
+   *
+   * @returns 本轮的认领句柄；调用方必须在 `finally` 里 {@link PushInFlightSession.release}
+   */
+  session(): PushInFlightSession {
+    const sessionId = ++this.#nextSessionId;
+    const claims = new Map<string, number>();
+    this.#sessions.set(sessionId, claims);
+
+    return {
+      claim: (repositoryKey: string, maxChangeId: number): void => {
+        const existing = claims.get(repositoryKey);
+        if (existing !== undefined && existing >= maxChangeId) return;
+        claims.set(repositoryKey, maxChangeId);
+      },
+      release: (): void => {
+        this.#sessions.delete(sessionId);
+      }
+    };
+  }
+
+  /**
+   * 当前全部在飞认领，按仓库取最大值。
+   *
+   * @returns `namespace:entity` -> 正在飞的最大 change id；没有任何认领时是空 Map
+   */
+  snapshot(): ReadonlyMap<string, number> {
+    const merged = new Map<string, number>();
+    for (const claims of this.#sessions.values()) {
+      for (const [repositoryKey, maxChangeId] of claims) {
+        const existing = merged.get(repositoryKey);
+        if (existing !== undefined && existing >= maxChangeId) continue;
+        merged.set(repositoryKey, maxChangeId);
+      }
+    }
+    return merged;
+  }
+}