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

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

package/src/redo-stack.ts

@@ -0,0 +1,79 @@
+import type { HistoryItem } from '@aiao/rxdb';
+import { BehaviorSubject, Observable } from 'rxjs';
+
+/**
+ * Redo 栈容量上限（会话内）
+ *
+ * 超过则丢弃最旧的项（尾部），避免长会话下无界增长。
+ */
+export const MAX_REDO_STACK_SIZE = 1000;
+
+/**
+ * 会话级 Redo 栈
+ *
+ * 从 HistoryManager 抽离的 redo 栈管理子模块：
+ * - 持有内存 `BehaviorSubject<HistoryItem[]>`（不持久化）
+ * - 新项总在头部（push 后第一个）
+ * - 容量上限 `MAX_REDO_STACK_SIZE`
+ *
+ * 设计理由：
+ * - HistoryManager 原本 1120 行，redo 栈状态 + 操作占 60+ 行且与 history 查询/undo 流程正交
+ * - 独立后可单测，并避免泄漏 BehaviorSubject 引用
+ *
+ * @internal 由 HistoryManager 持有；外部通过 HistoryManager 公共 API 访问
+ */
+export class RedoStack {
+  readonly #subject = new BehaviorSubject<HistoryItem[]>([]);
+
+  /**
+   * 当前 redo 栈的可观察流（新项在前）
+   */
+  get items$(): Observable<HistoryItem[]> {
+    return this.#subject.asObservable();
+  }
+
+  /**
+   * 当前栈快照
+   */
+  get value(): HistoryItem[] {
+    return this.#subject.value;
+  }
+
+  /**
+   * 将一组历史项压入栈顶（items 在前）
+   *
+   * 超过 MAX_REDO_STACK_SIZE 时丢弃尾部最旧项。
+   */
+  push(items: HistoryItem[]): void {
+    const merged = [...items, ...this.#subject.value];
+    const capped = merged.length > MAX_REDO_STACK_SIZE ? merged.slice(0, MAX_REDO_STACK_SIZE) : merged;
+    this.#subject.next(capped);
+  }
+
+  /**
+   * 按稳定身份（`fingerprint`）移除已应用的项。
+   *
+   * @param items - 已经 redo 完成、需要出栈的项
+   * @returns 实际被移除的项（按栈中原顺序）；不在栈中的项被忽略
+   *
+   * @remarks
+   * **不能用「移除 N 项」代替身份匹配**：作用域 redo 会先按 scope 筛出本作用域的项再应用，
+   * 这些项未必位于栈顶。按数量截栈顶会删掉栈头那些**未被 redo** 的项（它们从此丢失），
+   * 而真正已 redo 的项仍留在栈里可以被重复执行。
+   */
+  remove(items: HistoryItem[]): HistoryItem[] {
+    const targets = new Set(items.map(item => item.fingerprint));
+    const current = this.#subject.value;
+    const removed = current.filter(item => targets.has(item.fingerprint));
+    if (removed.length === 0) return removed;
+    this.#subject.next(current.filter(item => !targets.has(item.fingerprint)));
+    return removed;
+  }
+
+  /**
+   * 清空栈
+   */
+  clear(): void {
+    this.#subject.next([]);
+  }
+}

package/src/remove-branch.ts

@@ -0,0 +1,100 @@
+import {
+  type LocalRxDBBranchRepository,
+  type LocalRxDBChangeRepository,
+  MAIN_BRANCH_ID,
+  RxDBBranch,
+  RxDBChange,
+  RxDBError
+} from '@aiao/rxdb';
+import { VersionManager } from './VersionManager.js';
+
+/**
+ * 移除一个分支
+ * @param version
+ * @param branchId
+ *
+ * @remarks
+ * 「查子分支 → 查 change → 删」整段必须在一个事务窗口内完成。
+ * 拆开之后，检查与删除之间新建的子分支会漏判，留下 `parentId` 指向不存在分支的孤儿，
+ * 而孤儿又会被切分支时的「父节点缺失即当作到根」静默吞掉，损坏无声。
+ *
+ * 事务体内一律用 `executor.getRepository(...)`：绑在适配器上的仓库会重新入队，
+ * 排在自己这个事务后面（队列并发度 1），永久挂起。
+ */
+export const remove_branch = async (version: VersionManager, branchId: string) => {
+  const { adapter } = await version.getLocalRepositories();
+  // 检查是否为主分支
+  if (branchId === MAIN_BRANCH_ID) {
+    throw new RxDBError(`Cannot remove main branch`);
+  }
+
+  // 校验失败**返回**而不是就地抛出：抛出会被适配器的事务包装层裹成适配器错误类型
+  // （`RxDBAdapterSqliteError` 等），调用方拿到的异常身份就跟着实现细节变了。
+  // 校验失败时本事务一行都没写，回不回滚无所谓，留到事务外抛更稳。
+  const rejection = await adapter.transaction(async executor => {
+    const branchRepository = executor.getRepository(RxDBBranch) as unknown as LocalRxDBBranchRepository;
+    const changeRepository = executor.getRepository(RxDBChange) as unknown as LocalRxDBChangeRepository;
+
+    // 检查分支是否存在
+    const branch = (
+      await branchRepository.find({
+        where: {
+          combinator: 'and',
+          rules: [{ field: 'id', operator: '=', value: branchId }]
+        },
+        limit: 1
+      })
+    )[0];
+
+    if (!branch) {
+      return `Branch '${branchId}' not found`;
+    }
+
+    // 检查分支是否为激活状态
+    if (branch.activated) {
+      return `Cannot remove active branch '${branchId}'. Switch to another branch first.`;
+    }
+
+    // 检查是否有子分支依赖于该分支
+    //
+    // 必须直接查 `parentId`：拿「父分支有哪些 change、子分支的 fromChangeId 是否落在其中」
+    // 反推拓扑有两个漏洞 —— 父分支一条 change 都没有时整段检查被跳过；子分支的 fromChangeId
+    // 指向的 change 若已被清理也会漏判。两者都留下 `parentId` 指向不存在分支的孤儿。
+    const childBranches = await branchRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [
+          { field: 'parentId', operator: '=', value: branchId },
+          { field: 'id', operator: '!=', value: branchId }
+        ]
+      },
+      limit: 1
+    });
+    if (childBranches?.length) {
+      return `Cannot remove branch '${branchId}' because it has child branches`;
+    }
+
+    const branchChanges = await changeRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [{ field: 'branchId', operator: '=', value: branchId }]
+      }
+    });
+    // 贡献方挂在这条分支名下的行清在**这一个**事务里，且排在分支行自己被删之前：
+    // 分处两个事务的话，中间失败留下的是一条「分支没了、贡献行还在」的残留，而那些行按 id
+    // 挂靠——同名重建出来的新分支会逐字命中它们，带着上一条分支的 HEAD 与未提交条目出生。
+    //
+    // 串行而非 `Promise.all`，与 `create_branch` 同理：`executor` 是一条并发度为 1 的队列，
+    // 并行发起只会让删除顺序取决于各贡献方内部 await 的排布，出问题时复现不出来。
+    for (const contribution of version.rxdb.systemContributions) {
+      await contribution.removeBranchRows({ executor, branchId });
+    }
+
+    await executor.removeMany([...branchChanges, branch]);
+    return undefined;
+  });
+
+  if (rejection) {
+    throw new RxDBError(rejection);
+  }
+};

package/src/restore-entity.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview 恢复被删除实体的纯逻辑
+ *
+ * 从 {@link VersionManager.restoreEntity} 抽出的独立实现，遵循
+ * `create_branch` / `merge_branch` 的「接收 VersionManager 实例」模式。
+ */
+
+import {
+  declareTrustedWrite,
+  EntityType,
+  getEntityMetadata,
+  RestoreEntityOptions,
+  RxDBError,
+  TrustedWriteIntent
+} from '@aiao/rxdb';
+import { get_switch_version_actions } from './switch-branch-actions.js';
+import type { VersionManager } from './VersionManager.js';
+
+/**
+ * 恢复被删除的实体。
+ *
+ * 根据 RxDBChange 记录中的 inversePatch 重新插入实体，
+ * 恢复操作本身会生成新的 RxDBChange 记录（可被 push 到远程）。
+ *
+ * @param vm - 版本管理器实例
+ * @param entity - 被删除的实体实例（需要包含 metadata 信息）
+ * @param options - 恢复选项，包含 changeId（DELETE 类型的 RxDBChange 记录 ID）
+ * @returns 恢复后的实体实例
+ */
+export async function restore_entity<T extends EntityType>(
+  vm: VersionManager,
+  entity: InstanceType<T>,
+  options: RestoreEntityOptions
+): Promise<InstanceType<T>> {
+  const { changeRepository, adapter } = await vm.getLocalRepositories();
+
+  const changes = await changeRepository.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'id', operator: '=', value: Number(options.changeId) }]
+    },
+    limit: 1
+  });
+
+  if (changes.length === 0) {
+    throw new RxDBError(`RxDBChange not found: ${options.changeId}`);
+  }
+
+  const change = changes[0];
+
+  if (change.type !== 'DELETE') {
+    throw new RxDBError(`Cannot restore from non-DELETE change (type=${change.type})`);
+  }
+
+  if (!change.inversePatch) {
+    throw new RxDBError(`RxDBChange ${options.changeId} has no inversePatch`);
+  }
+
+  const EntityType = entity.constructor as T;
+  const metadata = getEntityMetadata(EntityType);
+  const currentBranch = await vm.getCurrentBranch();
+
+  // 身份校验必须在写入之前：只校验 changeId/type/inversePatch 时，传 A 的实体配 B 的 changeId
+  // 会真的把 B 恢复出来，再用 A 的 constructor 去查 —— 返回 undefined，而返回类型声明是非空的
+  // InstanceType<T>。分支同理：别的分支的 change 不能应用到当前分支。
+  if (change.namespace !== metadata.namespace || change.entity !== metadata.name) {
+    throw new RxDBError(
+      `RxDBChange ${options.changeId} belongs to ${change.namespace}:${change.entity}, ` +
+        `not ${metadata.namespace}:${metadata.name}`
+    );
+  }
+  if (change.branchId != null && change.branchId !== currentBranch.id) {
+    throw new RxDBError(
+      `RxDBChange ${options.changeId} belongs to branch '${change.branchId}', current branch is '${currentBranch.id}'`
+    );
+  }
+
+  const actions = get_switch_version_actions([change], false);
+  // 不能走 switchBranch：各适配器的 switch_branch 第一步就是 remove_all_triggers_sql
+  // （见 sqlite-core / pglite 的 version/switch_branch.ts），恢复出来的行不会产生任何 change 行——
+  // 本函数的 TSDoc 说「恢复操作本身会生成新的 RxDBChange 记录（可被 push 到远程）」直接落空，
+  // 远端永远停在「已删除」，本地与远端静默分叉。
+  // 改走 mergeChanges(actions, undefined, false)：与 merge_branch 的 squash 出口同路，
+  // disableTriggers=false 让数据库触发器照常记账。
+  // 恢复是重算领域状态，不是一次新的用户编辑。
+  //
+  // 只有一次写，本来不需要事务。开事务是为了**拿到一个执行器当声明的作用域**：声明存在一个
+  // WeakMap 里，每个作用域只存一条（`trusted-write-scope.ts`），而工作树的
+  // `interceptMergeChanges()` 是排队拿到事务之后才取声明的（`capture-hook.ts`）。绑在适配器
+  // 实例上时，一次恢复与一次并发的压缩合并会互相覆盖：先执行的取到后声明者的意图，
+  // 后执行的取不到声明被当作未知入口拒绝（`merge-branch.ts` 的压缩出口同理，两边的并发用例在
+  // `__tests__/trusted-write-concurrency.spec.ts`）。执行器是「这一次写」独有的对象。
+  //
+  // 第二个参数（transactionLog）显式传 false，理由同 `merge-branch.ts` 的压缩出口：这一层只借
+  // 执行器当声明作用域。默认 true 会给这次写出的 change 行盖上 transactionId，
+  // `history-item-builder.ts` 于是把这条恢复显示成 `'TRANSACTION'` 而不是它自己的类型（如
+  // INSERT）——TSDoc 承诺的是一条普通的 RxDBChange 记录，不是被特殊分组的事务记录。
+  await adapter.transaction(async executor => {
+    declareTrustedWrite(executor, {
+      file: 'restore-entity.ts',
+      symbol: 'restore_entity',
+      intent: TrustedWriteIntent.restore_entity
+    });
+    await executor.mergeChanges(actions, undefined, false);
+  }, false);
+
+  const repo = adapter.getRepository(EntityType);
+  const restored = await repo.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'id', operator: '=', value: change.entityId }]
+    },
+    limit: 1
+  });
+
+  // 返回类型是非空的 InstanceType<T>，恢复不出行时必须抛错而不是让 undefined 冒充实体
+  if (!restored[0]) {
+    throw new RxDBError(
+      `Restore produced no row for ${metadata.namespace}:${metadata.name} id=${String(change.entityId)}`
+    );
+  }
+
+  return restored[0] as InstanceType<T>;
+}

package/src/scope-selection.ts

@@ -0,0 +1,133 @@
+/**
+ * 作用域历史选择（纯函数）
+ *
+ * @packageDocumentation
+ *
+ * `history(scope).undo()` 的选择口径与展示口径**不是同一件事**：
+ *
+ * - 展示（`filterHistoriesByScope`）可以把一个事务裁成「与你有关的那几条」，
+ *   用户在 User 的历史面板上看到的就该是 User 的部分；
+ * - 执行**不能**这么裁。事务是原子的，只回滚它的一半会留下一个从未存在过的中间态
+ *   （订单被撤销、订单行还在）。
+ *
+ * 因此这里把「选哪几条」和「能不能整条应用」分开：`selectScopedHistories` 只返回
+ * **完整未裁剪**的历史项，凡是触及作用域但同时改了作用域外数据的事务，一律进
+ * `crossScope` 由调用方拒绝（{@link RxDBCrossScopeTransactionError}）。
+ *
+ * 为什么是「拒绝」而不是「连带撤销作用域外的部分」：作用域的契约是**只影响这个作用域**。
+ * 悄悄扩大影响面，调用方无从知道自己刚刚还回滚了别的仓库；而静默跳过则是点了撤销
+ * 什么都没发生。报错是唯一一个既不越权、又不骗人的选项，且可恢复——调用方改用
+ * `history()`（database 作用域）就能完整撤销这个事务。
+ */
+
+import { HistoryItem, HistoryScope, RxDBChange, RxDBError } from '@aiao/rxdb';
+/** 判定作用域归属只需要这三个字段 */
+type ScopedChange = Pick<RxDBChange, 'entity' | 'entityId' | 'namespace'>;
+
+/**
+ * 单条变更是否落在作用域内
+ *
+ * @remarks
+ * entity 作用域用 `===` 比较 id，`0` / `''` 这类假值同样是合法 id——
+ * 判空必须用 `undefined` 而不是真值判断，否则 `entityId = 0` 会退化成 repository 作用域。
+ */
+export function isChangeInScope(change: ScopedChange, scope: HistoryScope): boolean {
+  if (scope.type === 'database') return true;
+  if (change.namespace !== scope.namespace || change.entity !== scope.entity) return false;
+  return scope.type === 'repository' || change.entityId === scope.entityId;
+}
+
+/** 历史项是否**至少有一条**变更落在作用域内（决定它是否出现在该作用域的历史里） */
+export function historyTouchesScope(history: HistoryItem, scope: HistoryScope): boolean {
+  return history.changes.some(change => isChangeInScope(change, scope));
+}
+
+/** 历史项是否**全部**变更都落在作用域内（决定它能否被该作用域整条应用） */
+export function isHistoryWithinScope(history: HistoryItem, scope: HistoryScope): boolean {
+  return history.changes.every(change => isChangeInScope(change, scope));
+}
+
+/** {@link selectScopedHistories} 的结果 */
+export interface ScopedHistorySelection {
+  /** 触及作用域、但同时改了作用域外数据的事务：不可部分应用 */
+  crossScope: HistoryItem[];
+  /** 完全落在作用域内、可以整条应用的历史项（未被裁剪） */
+  selected: HistoryItem[];
+}
+
+/**
+ * 在作用域内挑出接下来 `step` 条要 undo / redo 的历史项
+ *
+ * @param histories - 候选历史（已按可撤销 / 可重做过滤，最新在前）
+ * @param scope - 作用域
+ * @param step - 取几条；非正数取 0 条
+ *
+ * @remarks
+ * `step` 数的是「触及作用域的历史项」，越界事务同样占一个名额而不是被跳过——
+ * undo 必须后进先出，跳过它去撤更早的那条会把顺序弄乱。
+ */
+export function selectScopedHistories(
+  histories: HistoryItem[],
+  scope: HistoryScope,
+  step: number
+): ScopedHistorySelection {
+  const window = histories.filter(history => historyTouchesScope(history, scope)).slice(0, Math.max(0, step));
+  const crossScope: HistoryItem[] = [];
+  const selected: HistoryItem[] = [];
+
+  for (const history of window) {
+    if (isHistoryWithinScope(history, scope)) {
+      selected.push(history);
+    } else {
+      crossScope.push(history);
+    }
+  }
+
+  return { crossScope, selected };
+}
+
+const describeScope = (scope: HistoryScope): string => {
+  if (scope.type === 'database') return 'database';
+  if (scope.type === 'repository') return `${scope.namespace}:${scope.entity}`;
+  return `${scope.namespace}:${scope.entity}#${String(scope.entityId)}`;
+};
+
+const describeOutsiders = (histories: readonly HistoryItem[], scope: HistoryScope): string => {
+  const outsiders = new Set<string>();
+  for (const history of histories) {
+    for (const change of history.changes) {
+      if (isChangeInScope(change, scope)) continue;
+      outsiders.add(
+        scope.type === 'entity' ?
+          `${change.namespace}:${change.entity}#${String(change.entityId)}`
+        : `${change.namespace}:${change.entity}`
+      );
+    }
+  }
+  return [...outsiders].join(', ');
+};
+
+/**
+ * 作用域 undo / redo 撞上跨作用域事务
+ *
+ * @remarks
+ * 拿到本错误说明选中的历史项里有事务同时改了作用域内外的数据。作用域**不会**替你决定
+ * 是牺牲原子性还是越权撤销：要完整撤销这个事务，改用不带参数的
+ * `rxdb.versionManager.history()`（database 作用域）重新取一次历史再 undo。
+ * `VersionManager.historyManager` 是实现细节，不是绕开本错误的出口。
+ */
+export class RxDBCrossScopeTransactionError extends RxDBError {
+  constructor(
+    /** 发起 undo / redo 的作用域 */
+    readonly scope: HistoryScope,
+    /** 越界的历史项（完整未裁剪） */
+    readonly histories: readonly HistoryItem[]
+  ) {
+    super(
+      `Scoped history operation would split a transaction: scope ${describeScope(scope)} also changes ` +
+        `${describeOutsiders(histories, scope)}. Use the database scope to apply the whole transaction.`
+    );
+    this.name = 'RxDBCrossScopeTransactionError';
+    Object.setPrototypeOf(this, RxDBCrossScopeTransactionError.prototype);
+  }
+}