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

package/src/create-branch.ts

@@ -0,0 +1,178 @@
+import {
+  assertUsableBranchId,
+  type LocalRxDBBranchRepository,
+  type LocalRxDBChangeRepository,
+  resolve_current_branch,
+  RxDBBranch,
+  RxDBChange,
+  RxDBError
+} from '@aiao/rxdb';
+import { VersionManager } from './VersionManager.js';
+
+/**
+ * 创建一个新分支
+ * @param version
+ * @param branchId
+ * @param fromChangeId
+ * @returns
+ *
+ * @remarks
+ * 「查重 → 解析分叉点 → 写入」在一个事务窗口内完成。只把 `remove_branch`
+ * 包进事务是不够的：一个在删除之前就解析完父分支的 `create_branch`，仍会在删除之后
+ * 把子分支写进去，留下孤儿。两侧同处一个写队列窗口，「只能有一方成功」才成立。
+ *
+ * 远端 `branchExists` 那一趟**留在事务外**：它是网络往返，放进事务会让并发度 1 的
+ * 写队列被一次 RTT 堵住。它本来也只是尽力而为的预检，真正的互斥由本地主键约束兜底。
+ *
+ * **一条分支未必只有一行。** 贡献系统能力的插件可以在同一个事务里追写自己那几行
+ * （{@link RxDBSystemContribution.writeBranchRows}）——装了 `@aiao/rxdb-plugin-working-tree`
+ * 时是 `CommitBranchRef` 与 `WorkingTreeState` 两行。同属一个事务，正是为了不让
+ * 「建了分支却没有对应视图」这种半成品状态存在：那样一条分支与一条正常的老分支
+ * 在形状上分辨不出来，只会在下一次用到它时抛一句读不出主语的错。
+ */
+export const create_branch = async (version: VersionManager, branchId: string, fromChangeId?: number) => {
+  // 挡在所有 I/O 之前。排在查重之后的话，一条从第一个字符起就不可用的 id 会先跑完本地
+  // 查重、再跑一趟远端 RTT 才被拒——而这两趟的答案与结论无关。
+  assertUsableBranchId(branchId);
+
+  const { branchRepository: queuedBranchRepository, adapter } = await version.getLocalRepositories();
+  // 检查分支 ID 是否存在（本地）
+  //
+  // 事务里还会再查一次。这一次是快速失败：它挡在远端往返之前，
+  // 保证「本地已存在」比「远端已存在」先报，错误信息的优先级不因加事务而改变。
+  const branchEntity = await queuedBranchRepository.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'id', operator: '=', value: branchId }]
+    },
+    limit: 1
+  });
+  if (branchEntity.length) throw new RxDBError(`Branch id (${branchId}) already exists`);
+
+  // 检查分支 ID 是否存在（远程）
+  const remoteAdapterName = version.rxdb.config.sync?.remote?.adapter;
+  if (remoteAdapterName) {
+    const { adapter: remoteAdapter } = await version.getRemoteRepositories();
+    if (remoteAdapter.branchExists) {
+      const existsOnRemote = await remoteAdapter.branchExists(branchId);
+      if (existsOnRemote) throw new RxDBError(`Branch id (${branchId}) already exists on remote`);
+    }
+  }
+
+  // 校验失败返回而不是就地抛出，理由同 `remove_branch`：不让适配器的事务包装层改写异常身份。
+  const result = await adapter.transaction(async executor => {
+    const branchRepository = executor.getRepository(RxDBBranch) as unknown as LocalRxDBBranchRepository;
+    const changeRepository = executor.getRepository(RxDBChange) as unknown as LocalRxDBChangeRepository;
+
+    const existed = await branchRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [{ field: 'id', operator: '=', value: branchId }]
+      },
+      limit: 1
+    });
+    if (existed.length) return `Branch id (${branchId}) already exists`;
+
+    let fromBranch: InstanceType<typeof RxDBBranch> | undefined;
+    let fromChange: InstanceType<typeof RxDBChange> | undefined;
+
+    // 找出当前分支
+    if (fromChangeId) {
+      // 从 RxDBChange 表查找包含指定 changeId 的记录，获取其 branchId
+      const changeEntity = (
+        await changeRepository.find({
+          where: {
+            combinator: 'and',
+            rules: [{ field: 'id', operator: '=', value: fromChangeId }]
+          },
+          limit: 1
+        })
+      )[0];
+      if (!changeEntity) return `Change ID (${fromChangeId}) not found`;
+
+      // 保存找到的 change 作为 fromChange
+      fromChange = changeEntity;
+
+      // 通过 branchId 查找分支
+      fromBranch = (
+        await branchRepository.find({
+          where: {
+            combinator: 'and',
+            rules: [{ field: 'id', operator: '=', value: changeEntity.branchId! }]
+          },
+          limit: 1
+        })
+      )[0];
+    } else {
+      // 不能调 `version.getCurrentBranch()`：那一份走绑在适配器上的仓库，
+      // 会排在自己这个事务后面（队列并发度 1）而挂死。共用同一段逻辑，换成事务内的仓库。
+      fromBranch = await resolve_current_branch(branchRepository, version.rxdb);
+      fromChange = await get_current_branch_last_change(changeRepository, fromBranch.id);
+    }
+    if (!fromBranch) return 'Source branch not found';
+
+    // 创建新分支
+    //
+    // 用事务内仓库的 `create` 而非 `branch.save()`：后者经 entityManager 打到适配器上，
+    // 正是事务体内不能碰的那条队列。
+    const branch = version.rxdb.entityManager.instantiate(RxDBBranch);
+    branch.id = branchId;
+    branch.activated = false;
+    // 冗余列与 `activated` 必须同写（`system/branch.ts` 的唯一索引就架在它上面）。
+    // 漏写一处，那一行就绕过唯一约束，而 schema 那一半的保护正好在这种漏写上失效。
+    branch.activeKey = null;
+    branch.local = true;
+    branch.remote = false;
+    branch.fromChangeId = fromChange?.id ?? null;
+    branch.parentId = fromBranch.id;
+    await branchRepository.create(branch);
+
+    // 贡献方的分支级行写在**这一个**事务里，不另开一个：分支行与贡献行分处两个事务的话，
+    // 中间失败留下的是一条「分支在、贡献行不在」的记录，而这种半条分支与一条正常的老分支
+    // 在形状上分辨不出来。抛错就让整条 `create_branch` 回滚，这是对的。
+    //
+    // 串行而非 `Promise.all`：`executor` 是一条并发度为 1 的队列，并行发起只会让
+    // 写入顺序取决于各贡献方内部 await 的排布，出问题时复现不出来。
+    for (const contribution of version.rxdb.systemContributions) {
+      await contribution.writeBranchRows(version.rxdb.entityManager, { executor, branchId });
+    }
+    return branch;
+  });
+
+  if (typeof result === 'string') throw new RxDBError(result);
+  return result;
+};
+
+/**
+ * 获取分支最新一笔可作为分叉点的变更记录
+ *
+ * @param changeRepository - 变更仓库。由调用方决定它属于哪个事务 ——
+ * `create_branch` 传的是事务内的那一份，不能在这里自己去 `getLocalRepositories()`。
+ * @param currentBranchId - 分支 ID；不传则按「当前激活分支」查
+ *
+ * 独立导出而非内联，是为了被 `__tests__/version/create-branch.spec.ts` 单独测试。
+ */
+export const get_current_branch_last_change = async (
+  changeRepository: LocalRxDBChangeRepository,
+  currentBranchId?: string
+) => {
+  return (
+    await changeRepository.find({
+      where: {
+        combinator: 'and',
+        rules: [
+          currentBranchId ?
+            { field: 'branchId', operator: '=', value: currentBranchId }
+          : { field: 'branch.activated', operator: '=', value: true },
+          {
+            field: 'revertChangeId',
+            operator: '=',
+            value: null
+          }
+        ]
+      },
+      orderBy: [{ field: 'id', sort: 'desc' }],
+      limit: 1
+    })
+  )[0];
+};

package/src/detached-event-error.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview 游离事件任务的错误判据
+ *
+ * 事件监听器里发起的异步任务没有调用方接得住错误（{@link VersionManager} 的
+ * `#runDetachedEventTask`、{@link setupSyncListeners} 的远端事件处理器都是即发即忘）。
+ * 连接正在拆除时这些任务必然撞上一批「适配器已经走了」的错误，它们是拆除过程的正常噪音，
+ * 不该打进控制台当故障看。
+ *
+ * 判据留在历史插件、由同步插件经 `@aiao/rxdb-plugin-history` 引用：同步插件本就
+ * `inject: ['plugin:history']`，这条 import 不新增依赖边；放进核心则要为一个纯谓词
+ * 再撑大一圈公共表面，与 US-025「核心只留原语」的方向相反。
+ */
+
+import { isAdapterShutdownError } from '@aiao/rxdb';
+
+/**
+ * 判断游离事件任务的错误是否可忽略
+ *
+ * @param error - 任务抛出的错误
+ * @returns 属于连接拆除噪音时返回 `true`
+ *
+ * @remarks
+ * 包括：
+ * - errno 44 = ENODEV（Emscripten IDBFS 连接关闭）
+ * - name === 'AbortError'
+ * - adapter shutdown 错误（统一字符串匹配模式）
+ *
+ * @internal
+ */
+export const isIgnorableDetachedVersionEventError = (error: unknown): boolean => {
+  if (!error || typeof error !== 'object') {
+    return false;
+  }
+
+  const name = 'name' in error ? String(error.name) : '';
+  const errno = 'errno' in error ? Number((error as { errno?: unknown }).errno) : undefined;
+
+  if (errno === 44 || name === 'AbortError') {
+    return true;
+  }
+
+  return isAdapterShutdownError(error);
+};

package/src/find-switch-branch-step.ts

@@ -0,0 +1,313 @@
+import { RxDBBranch, RxDBError } from '@aiao/rxdb';
+/**
+ * 分支切换步骤
+ *
+ * @internal
+ */
+export interface SwitchBranchStep {
+  /**
+   * 分支对象
+   */
+  branch: RxDBBranch;
+  /**
+   * 开始变更 ID
+   */
+  fromChangeId: number;
+
+  /**
+   * 目标变更 ID
+   */
+  toChangeId: number;
+}
+
+/**
+ * 查找分支切换路径的参数
+ */
+export interface FindBranchPathOptions {
+  /**
+   * 所需分支列表
+   */
+  branches: RxDBBranch[];
+
+  /**
+   * 当前分支
+   */
+  currentBranch: RxDBBranch;
+
+  /**
+   * 当前分支的变更 ID
+   */
+  currentChangeId: number | null;
+
+  /**
+   * 目标分支
+   */
+  nextBranch: RxDBBranch;
+
+  /**
+   * 目标分支的变更 ID
+   */
+  nextChangeId: number | null;
+}
+
+/**
+ * 读取分支的分叉点变更 id。
+ *
+ * `fromChangeId === null` 的含义是**分叉于根**（这条分支不是从某条变更上长出来的）。
+ * 变更 id 从 1 开始递增，所以用 0 表示「根」既不会和任何真实变更撞上，又能让它
+ * 直接参与后面的区间运算。
+ *
+ * 抽成具名函数是为了让这个约定只存在一处：从前它以 `branch.fromChangeId ?? 0` 的形式
+ * 在本文件出现十余次，读的人无法判断哪一处是「表达根」、哪一处只是随手兜底。
+ *
+ * @param branch - 分支行
+ * @returns 分叉点变更 id，分叉于根时为 0
+ */
+const forkPointOf = (branch: RxDBBranch): number => branch.fromChangeId ?? 0;
+
+/**
+ * 沿 `parentId` 从一条分支走到它所在树的根，返回途经的全部分支（含自己，根在最后）。
+ *
+ * 断链（`parentId` 指不到分支）与成环都是**持久化完整性错误**：调用方传进来的分支集合
+ * 是全量无过滤查询的结果，不存在「父分支被过滤掉了」这种正常情况。
+ * 曾经这两种情况都是 `break` —— 相当于把坏数据当成「已经到根」，继续算出一条通往
+ * 并不存在的根的完整 action 序列，调用方照单全收地写库，半条路径被应用而没有任何报错。
+ * 切分支失败远好过静默切错，因此这里必须终止且不产生任何 action。
+ *
+ * 从 {@link find_switch_branch_step} 的闭包里提出来成为模块级导出，是因为
+ * 「父链自不自洽」这一问的答案必须**全局只有一个**：`enable-migration.ts` 的
+ * 「分支可否完整物化」判定用的就是它（research.md R11）。留在闭包里够不着，
+ * 调用方只能另写一套遍历，于是迁移期与运行期会对同一个库给出两种答案。
+ *
+ * 它**够不到** {@link find_switch_branch_step} 的两处提前返回：变更 id 相同（含两边
+ * 都没有变更、都落在根上）时那个函数直接返回空步骤，根本走不到这里。所以要检查父链
+ * 完整性的调用方必须**自己**调它一次，不能指望 `find_switch_branch_step` 顺带检查。
+ *
+ * @param branch - 起点分支
+ * @param branchMap - 分支 id → 分支；必须是全量集合
+ * @returns 从 `branch` 到根的路径，`branch` 在第 0 位
+ * @throws {@link RxDBError} 父链成环或指向不存在的分支时
+ *
+ * @internal
+ */
+export const find_branch_path_to_root = (
+  branch: RxDBBranch,
+  branchMap: ReadonlyMap<string, RxDBBranch>
+): RxDBBranch[] => {
+  const path: RxDBBranch[] = [branch];
+  const visited = new Set<string>([branch.id]);
+  let current = branch;
+  while (current.parentId) {
+    if (visited.has(current.parentId)) {
+      throw new RxDBError(
+        `Branch history is corrupt: cycle detected at branch '${current.id}' (parentId '${current.parentId}' already visited)`
+      );
+    }
+    const parent = branchMap.get(current.parentId);
+    if (!parent) {
+      throw new RxDBError(
+        `Branch history is corrupt: branch '${current.id}' references missing parent '${current.parentId}'`
+      );
+    }
+    visited.add(parent.id);
+    path.push(parent);
+    current = parent;
+  }
+  return path;
+};
+
+/**
+ * 算出树上两个节点之间的切换路径
+ *
+ * @param options - 起点分支、目标分支、两侧当前变更 id，以及**全量**分支集合
+ * @returns 按执行顺序排好的步骤；两侧停在同一个变更 id 时为空数组
+ * @throws {@link RxDBError} 父链成环或指向不存在的分支时（经 {@link find_branch_path_to_root}）
+ *
+ * @remarks
+ * 规则四条：
+ *
+ * 1. 两个节点有共同祖先时，路径是「当前节点 → 共同祖先 → 目标节点」
+ * 2. 没有共同祖先时，路径是「当前节点 → 根 → 目标节点」
+ * 3. 路径里每个节点都要算出自己那一段的变更区间，即 `fromChangeId → toChangeId`
+ * 4. `changeId` 在每条分支上都递增，所以**逆向还原**的那些步骤 `fromChangeId > toChangeId`，
+ *    正向应用的则相反——方向由这两个数的大小关系表达，步骤上没有第二个方向字段
+ *
+ * 有两处**提前返回**会跳过父链遍历——变更 id 相同时返回空步骤，同分支不同变更 id 时返回
+ * 单步——因此本函数不是父链完整性的检查点，理由见 {@link find_branch_path_to_root}。
+ *
+ * @internal
+ */
+export const find_switch_branch_step = (options: FindBranchPathOptions): SwitchBranchStep[] => {
+  const { branches, currentBranch, nextBranch } = options;
+
+  // 如果分支没有自己的变更记录，使用 fromChangeId 作为当前状态
+  // 否则使用该分支的最大 changeId
+  const currentChangeId = options.currentChangeId ?? forkPointOf(currentBranch);
+  const nextChangeId = options.nextChangeId ?? forkPointOf(nextBranch);
+
+  // 任意分支只要变更 id 相同，都无需切换数据
+  if (currentChangeId === nextChangeId) {
+    return [];
+  }
+
+  // 如果是同一个分支但变更 id 不同，直接在当前分支上移动
+  if (currentBranch.id === nextBranch.id) {
+    return [
+      {
+        branch: currentBranch,
+        fromChangeId: currentChangeId,
+        toChangeId: nextChangeId
+      }
+    ];
+  }
+
+  // 构建分支映射表
+  const branchMap = new Map<string, RxDBBranch>();
+  for (const branch of branches) {
+    branchMap.set(branch.id, branch);
+  }
+
+  // 获取当前分支和目标分支到根的路径
+  const currentPath = find_branch_path_to_root(currentBranch, branchMap);
+  const nextPath = find_branch_path_to_root(nextBranch, branchMap);
+
+  // 找到最近的共同祖先
+  let commonAncestor: RxDBBranch | null = null;
+  let commonAncestorIndex = -1;
+
+  for (let i = 0; i < currentPath.length; i++) {
+    const idx = nextPath.findIndex(b => b.id === currentPath[i].id);
+    if (idx !== -1) {
+      commonAncestor = currentPath[i];
+      commonAncestorIndex = i;
+      break;
+    }
+  }
+
+  const steps: SwitchBranchStep[] = [];
+
+  if (commonAncestor) {
+    // 从当前分支回退到共同祖先
+    for (let i = 0; i < commonAncestorIndex; i++) {
+      const branch = currentPath[i];
+      const fromId = i === 0 ? currentChangeId : forkPointOf(currentPath[i - 1]);
+      const toId = forkPointOf(branch);
+
+      // 只有当需要实际变更时才添加步骤
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+
+    // 在共同祖先上可能也需要移动
+    const ancestorIndexInNext = nextPath.findIndex(b => b.id === commonAncestor!.id);
+
+    if (ancestorIndexInNext === 0) {
+      // 共同祖先就是目标分支，需要移动到目标 changeId
+      const ancestorFromId =
+        commonAncestorIndex === 0 ? currentChangeId : forkPointOf(currentPath[commonAncestorIndex - 1]);
+      const ancestorToId = nextChangeId;
+
+      if (ancestorFromId !== ancestorToId) {
+        steps.push({
+          branch: commonAncestor,
+          fromChangeId: ancestorFromId,
+          toChangeId: ancestorToId
+        });
+      }
+    } else if (ancestorIndexInNext > 0) {
+      // 需要从当前位置移动到目标分支的 fromChangeId
+      const ancestorFromId =
+        commonAncestorIndex === 0 ? currentChangeId : forkPointOf(currentPath[commonAncestorIndex - 1]);
+      const ancestorToId = forkPointOf(nextPath[ancestorIndexInNext - 1]);
+
+      if (ancestorFromId !== ancestorToId) {
+        steps.push({
+          branch: commonAncestor,
+          fromChangeId: ancestorFromId,
+          toChangeId: ancestorToId
+        });
+      }
+    }
+
+    // 从共同祖先前进到目标分支
+    const forwardPath = nextPath.slice(0, ancestorIndexInNext).reverse();
+
+    for (let i = 0; i < forwardPath.length; i++) {
+      const branch = forwardPath[i];
+      const fromId = forkPointOf(branch);
+      const toId = i === forwardPath.length - 1 ? nextChangeId : forkPointOf(forwardPath[i + 1]);
+
+      // 只有当需要实际变更时才添加步骤
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+  } else {
+    // 没有共同祖先，回退到当前分支的根，然后前进到目标分支
+    // 1. 回退当前分支的所有节点到根
+    for (let i = 0; i < currentPath.length; i++) {
+      const branch = currentPath[i];
+      const fromId = i === 0 ? currentChangeId : forkPointOf(currentPath[i - 1]);
+      const toId = forkPointOf(branch);
+
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+
+    // 2. 将当前树的根节点回退到 0
+    const currentRoot = currentPath[currentPath.length - 1];
+    const currentRootFromId = forkPointOf(currentRoot);
+
+    if (currentRootFromId !== 0) {
+      steps.push({
+        branch: currentRoot,
+        fromChangeId: currentRootFromId,
+        toChangeId: 0
+      });
+    }
+
+    // 3. 从目标树的根节点开始前进到目标分支
+    const nextRoot = nextPath[nextPath.length - 1];
+    const nextRootTargetId = nextPath.length > 1 ? forkPointOf(nextPath[nextPath.length - 2]) : nextChangeId;
+
+    if (nextRootTargetId !== 0) {
+      steps.push({
+        branch: nextRoot,
+        fromChangeId: 0,
+        toChangeId: nextRootTargetId
+      });
+    }
+
+    // 4. 前进目标树的所有子节点
+    const forwardPath = nextPath.slice(0, nextPath.length - 1).reverse();
+    for (let i = 0; i < forwardPath.length; i++) {
+      const branch = forwardPath[i];
+      const fromId = forkPointOf(branch);
+      const toId = i === forwardPath.length - 1 ? nextChangeId : forkPointOf(forwardPath[i + 1]);
+
+      if (fromId !== toId) {
+        steps.push({
+          branch,
+          fromChangeId: fromId,
+          toChangeId: toId
+        });
+      }
+    }
+  }
+
+  return steps;
+};

package/src/history-filters.ts

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview 历史记录过滤与作用域键的纯函数集合
+ *
+ * 这些函数不持有任何状态，供 {@link HistoryManager} 与单元测试共用：
+ * - {@link filterHistoriesByScope}：按作用域裁切历史
+ * - {@link buildLastPushedMap}：合成每个仓库的「视同已推」水位线
+ * - {@link filterUndoableHistories}：过滤可撤销的历史
+ * - {@link getScopeKey}：生成作用域缓存键
+ *
+ * @module rxdb/version/history-filters
+ */
+
+import { getRxDBEntityIdentityKey, type HistoryItem, type HistoryScope } from '@aiao/rxdb';
+import { generateHistoryDescription } from './history-item-builder.js';
+/**
+ * 生成 repository 的缓存键（纯函数）
+ *
+ * @param repository - 带 namespace / entity 的仓储标识
+ * @returns 'namespace:entity' 形式的缓存键
+ *
+ * @internal 供 HistoryManager 与同文件的过滤函数使用
+ */
+export const getRepositoryKey = (repository: { namespace: string; entity: string }): string =>
+  `${repository.namespace}:${repository.entity}`;
+
+/**
+ * 合成「每个仓库推到哪了」的水位线映射：已提交的 `RxDBSync` 水位线与正在飞的认领取较大者。
+ *
+ * @param repoSyncs - 当前分支下的 `RxDBSync` 行
+ * @param inFlight - `PushInFlightRegistry.snapshot()`，`namespace:entity` -> 正在飞的最大 change id
+ * @returns `namespace:entity` -> 该仓库「视同已推」的最大 change id
+ *
+ * @remarks
+ * `undoHistories$` 与 `fetchLatestHistories` 两条路径都要这份映射，此前各写一份循环。
+ * 两份必须逐字一致：一边认在飞、另一边不认，反应式的「可撤销」列表就会和真正执行撤销时
+ * 的判定分家 —— UI 上还亮着的那一项点下去什么也不会发生，或者更糟，真的撤销了一条
+ * 已经在飞的变更。
+ *
+ * 取最大值而不是「有在飞就用在飞」：上一轮推到 30、这一轮只在飞到 20 时，
+ * 水位线不许倒退。
+ *
+ * 在飞认领先进 map，因此**没有** `RxDBSync` 行的仓库也报得出来：`RxDBSync` 行由
+ * `planRepositoryPush` 现建，行还没落到本次查询的结果集里时，认领仍然必须生效。
+ */
+export function buildLastPushedMap(
+  repoSyncs: readonly { namespace: string; entity: string; lastPushedChangeId: number | null }[],
+  inFlight: ReadonlyMap<string, number>
+): Map<string, number> {
+  const lastPushedMap = new Map(inFlight);
+
+  for (const repoSync of repoSyncs) {
+    if (repoSync.lastPushedChangeId === null) continue;
+    const key = getRepositoryKey(repoSync);
+    const claimed = lastPushedMap.get(key);
+    if (claimed !== undefined && claimed >= repoSync.lastPushedChangeId) continue;
+    lastPushedMap.set(key, repoSync.lastPushedChangeId);
+  }
+
+  return lastPushedMap;
+}
+
+/**
+ * 按作用域过滤历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param scope - 作用域配置
+ * @returns 过滤后的历史记录数组
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function filterHistoriesByScope(histories: HistoryItem[], scope: HistoryScope): HistoryItem[] {
+  if (scope.type === 'database') {
+    return histories;
+  }
+
+  return histories
+    .map(history => {
+      const filtered_changes = history.changes.filter(change => {
+        if (scope.type === 'repository') {
+          return change.namespace === scope.namespace && change.entity === scope.entity;
+        }
+        // 实体作用域
+        return (
+          change.namespace === scope.namespace && change.entity === scope.entity && change.entityId === scope.entityId
+        );
+      });
+
+      if (filtered_changes.length === 0) return null;
+
+      return {
+        ...history,
+        changes: filtered_changes,
+        count: filtered_changes.length,
+        description: generateHistoryDescription(filtered_changes)
+      };
+    })
+    .filter((h): h is HistoryItem => h !== null);
+}
+
+/**
+ * 过滤出可撤销的历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param lastPushedMap - namespace:entity -> lastPushedChangeId 的 repository 级水位线映射
+ * @param undoBoundaryChangeId - 同步清空后的永久撤销边界
+ * @param undoBoundaryCreatedAfter - 无数字 change id 时使用的严格时间边界
+ * @returns 可撤销的历史记录数组
+ *
+ * @remarks
+ * undoHistories$（UI 展示）与 undo()（实际执行）共用同一套规则，
+ * 保证 UI 上看不到的历史不会被 undo() 撤销：
+ * 1. history.reverted == false（按 updatedAt 水位合并持久态与本地态，未被撤销）
+ * 2. remoteId == null（只有本地创建的变更才能撤销）
+ * 3. id > 该 repository 的 lastPushedChangeId（未推送到远程；按 repository 独立判断）
+ * 4. id > undoBoundaryChangeId（同步清空前的历史永久不可撤销）
+ * 5. createdAt > undoBoundaryCreatedAfter（无数字 id 时保守隔离旧 session）
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function filterUndoableHistories(
+  histories: HistoryItem[],
+  lastPushedMap: Map<string, number>,
+  undoBoundaryChangeId = 0,
+  undoBoundaryCreatedAfter: Date | null = null
+): HistoryItem[] {
+  return histories.filter(history => {
+    if (history.reverted) return false;
+
+    return history.changes.every(change => {
+      const isLocal = change.remoteId == null;
+      const lastPushedId = lastPushedMap.get(getRepositoryKey(change));
+      const notPushed = lastPushedId == null || change.id > lastPushedId;
+      const afterUndoBoundary = change.id > undoBoundaryChangeId;
+      const afterUndoTimeBoundary =
+        undoBoundaryCreatedAfter === null || change.createdAt.getTime() > undoBoundaryCreatedAfter.getTime();
+      return isLocal && notPushed && afterUndoBoundary && afterUndoTimeBoundary;
+    });
+  });
+}
+
+/**
+ * 生成作用域缓存键（纯函数）
+ *
+ * @param scope - 作用域配置
+ * @returns 缓存键字符串：'database' | 'namespace:entity' | 'namespace:entity:id'
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export function getScopeKey(scope: HistoryScope): string {
+  if (scope.type === 'database') {
+    return 'database';
+  }
+  if (scope.type === 'repository') {
+    return `${scope.namespace}:${scope.entity}`;
+  }
+  return `${scope.namespace}:${scope.entity}:${getRxDBEntityIdentityKey(scope.entityId)}`;
+}