@aiao/rxdb-plugin-history 0.0.26 → 0.0.28

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

@@ -1,6 +1,8 @@
 import { RxDBBranch, RxDBError } from '@aiao/rxdb';
 /**
  * 分支切换步骤
+ *
+ * @internal
  */
 export interface SwitchBranchStep {
   /**
@@ -48,14 +50,6 @@ export interface FindBranchPathOptions {
   nextChangeId: number | null;
 }
 
-/**
- * 计算出树的两个节点之间的切换路径
- * 规则如下:
- *  1, 如果两个树节点有共同的祖先节点,则路径为从当前节点到共同祖先节点,再到目标节点
- *  2, 如果没有共同祖先节点,则路径为从当前节点到根节点,再到目标节点
- *  3, 需要计算出路径内每个节点需要变更过程，也就是 fromChangeId -> toChangeId
- *  4, 由于 changeId 在不同分支的变化都是是递增的, 所以如果逆向还原数据那么 fromChangeId 会大于 toChangeId, 正向应用数据则相反
- */
 /**
  * 读取分支的分叉点变更 id。
  *
@@ -71,6 +65,78 @@ export interface FindBranchPathOptions {
  */
 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;
 
@@ -101,39 +167,9 @@ export const find_switch_branch_step = (options: FindBranchPathOptions): SwitchB
     branchMap.set(branch.id, branch);
   }
 
-  // 获取从某个分支到根的路径
-  //
-  // 断链（parentId 指不到分支）与成环都是**持久化完整性错误**：调用方传进来的 `branches`
-  // 是全量无过滤查询的结果，不存在「父分支被过滤掉了」这种正常情况。
-  // 曾经这两种情况都是 `break` —— 相当于把坏数据当成「已经到根」，继续算出一条通往
-  // 并不存在的根的完整 action 序列，调用方照单全收地写库，半条路径被应用而没有任何报错。
-  // 切分支失败远好过静默切错，因此这里必须终止且不产生任何 action。
-  const getPathToRoot = (branch: 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;
-  };
-
   // 获取当前分支和目标分支到根的路径
-  const currentPath = getPathToRoot(currentBranch);
-  const nextPath = getPathToRoot(nextBranch);
+  const currentPath = find_branch_path_to_root(currentBranch, branchMap);
+  const nextPath = find_branch_path_to_root(nextBranch, branchMap);
 
   // 找到最近的共同祖先
   let commonAncestor: RxDBBranch | null = null;

package/src/index.ts

@@ -44,3 +44,18 @@ export { isIgnorableDetachedVersionEventError } from './detached-event-error.js'
 export { PushInFlightRegistry } from './push-inflight.js';
 export type { PushInFlightSession } from './push-inflight.js';
 export type { SyncHistoryBridge } from './sync-history-bridge.js';
+
+// ---------------------------------------------------------------------------
+// 以下六项只为 `@aiao/rxdb-plugin-working-tree` 而导出，全部标了 `@internal`：
+// 工作树插件的 commit 迁移（`commit/enable-migration.ts`）要在放行一条分支之前，
+// 先按 `switchBranch` 的同一口径问两件事——「父链自不自洽」与「这条分支现在停在哪」；
+// 它的物化屏障（`working-tree/materialize-branch.ts`）要在切换事务里按同一口径撤掉
+// 来源分支的投影，手上只有事务执行器的仓库。另写一条同义查询，迟早会在「回滚标记算不算」
+// 或「排序列是哪一个」上与切换路径分叉，表现为迁移放行了一条 `switchBranch` 走不通的分支
+// （research.md R11），或物化后留下一截来源分支的数据。
+// 两包之间只有 `dist` 一条路，没有深路径可走，所以从桶里出。应用代码不该引用它们。
+// ---------------------------------------------------------------------------
+export { find_branch_path_to_root, find_switch_branch_step } from './find-switch-branch-step.js';
+export type { SwitchBranchStep } from './find-switch-branch-step.js';
+export { compute_switch_branch_actions, get_branch_max_change } from './switch-branch-actions.js';
+export type { SwitchBranchActionReaders } from './switch-branch-actions.js';

package/src/merge-branch.ts

@@ -1,4 +1,12 @@
-import { getRxDBChangeKey, MergeBranchOptions, MergeBranchResult, RxDBError, SwitchVersionActions } from '@aiao/rxdb';
+import {
+  declareTrustedWrite,
+  getRxDBChangeKey,
+  MergeBranchOptions,
+  MergeBranchResult,
+  RxDBError,
+  SwitchVersionActions,
+  TrustedWriteIntent
+} 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';
@@ -122,6 +130,12 @@ export const merge_branch = async (
         } else if (change.type === 'DELETE') {
           singleActions.deletes.set(key, { patch: null, inversePatch: change.inversePatch! });
         }
+        // 声明写在循环体内：声明是取用即清除的，提到循环外只有第一条变更带得上身份。
+        declareTrustedWrite(executor, {
+          file: 'merge-branch.ts',
+          symbol: 'merge_branch',
+          intent: TrustedWriteIntent.merge_per_change
+        });
         await executor.mergeChanges(singleActions, undefined, false);
       }
     });
@@ -146,7 +160,32 @@ export const merge_branch = async (
 
     // 应用变更到当前分支的实体表
     // disableTriggers=false：让数据库触发器自动生成目标分支的 RxDBChange 记录
-    await adapter.mergeChanges(actions, undefined, false);
+    //
+    // 压缩只有一次写，本来不需要事务。开事务是为了**拿到一个执行器当声明的作用域**：
+    // 声明存在一个 WeakMap 里，每个作用域只存一条（`trusted-write-scope.ts`），而工作树的
+    // `interceptMergeChanges()` 是排队拿到事务之后才取声明的（`capture-hook.ts`）。绑在
+    // 适配器实例上时，两个并发的适配器级写会互相覆盖：先执行的取到后声明者的意图，
+    // 后执行的取不到声明被当作未知入口拒绝（`__tests__/trusted-write-concurrency.spec.ts`）。
+    // 执行器是「这一次写」独有的对象，于是并发与否都不会串台。
+    //
+    // 与逐条出口同一个符号、不同意图：登记表把它们分成两行，因为压缩与逐条的判定不同，
+    // 合成一行会让其中一条策略失去登记。
+    //
+    // 第二个参数（transactionLog）显式传 false：这一层只借执行器当声明作用域，不该把合并记成
+    // 一次事务化的历史条目。默认 true 会为本次事务启用一个 transactionId（SQLite 系后端按分支
+    // 重建全部触发器，PGlite 设一个事务局部变量），写出的每条 change 行都盖上它，
+    // `history-item-builder.ts` 的 `type = transactionId ? 'TRANSACTION' : first_change.type`
+    // 随即把 squash 产生的多条 change 折叠成一条 `'TRANSACTION'`——undo 粒度从「按实体」
+    // 变成「整次合并一起撤销」。传 false，历史记账与不包这层事务时一致（调用契约锁在
+    // `__tests__/merge-branch.spec.ts`，分组结果锁在 pglite 的 `version/merge_branch.spec.ts`）。
+    await adapter.transaction(async executor => {
+      declareTrustedWrite(executor, {
+        file: 'merge-branch.ts',
+        symbol: 'merge_branch',
+        intent: TrustedWriteIntent.merge_squash
+      });
+      await executor.mergeChanges(actions, undefined, false);
+    }, false);
   }
 
   return toResult(merged, await doDeleteSource());

package/src/remove-branch.ts

@@ -1,6 +1,7 @@
 import {
   type LocalRxDBBranchRepository,
   type LocalRxDBChangeRepository,
+  MAIN_BRANCH_ID,
   RxDBBranch,
   RxDBChange,
   RxDBError
@@ -23,7 +24,7 @@ import { VersionManager } from './VersionManager.js';
 export const remove_branch = async (version: VersionManager, branchId: string) => {
   const { adapter } = await version.getLocalRepositories();
   // 检查是否为主分支
-  if (branchId === 'main') {
+  if (branchId === MAIN_BRANCH_ID) {
     throw new RxDBError(`Cannot remove main branch`);
   }
 
@@ -79,6 +80,16 @@ export const remove_branch = async (version: VersionManager, branchId: string) =
         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;
   });

package/src/restore-entity.ts

@@ -5,7 +5,14 @@
  * `create_branch` / `merge_branch` 的「接收 VersionManager 实例」模式。
  */
 
-import { EntityType, getEntityMetadata, RestoreEntityOptions, RxDBError } from '@aiao/rxdb';
+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';
 
@@ -75,7 +82,27 @@ export async function restore_entity<T extends EntityType>(
   // 远端永远停在「已删除」，本地与远端静默分叉。
   // 改走 mergeChanges(actions, undefined, false)：与 merge_branch 的 squash 出口同路，
   // disableTriggers=false 让数据库触发器照常记账。
-  await adapter.mergeChanges(actions, undefined, 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({

package/src/scope-selection.ts

@@ -112,8 +112,9 @@ const describeOutsiders = (histories: readonly HistoryItem[], scope: HistoryScop
  *
  * @remarks
  * 拿到本错误说明选中的历史项里有事务同时改了作用域内外的数据。作用域**不会**替你决定
- * 是牺牲原子性还是越权撤销，改用不带参数的 `rxdb.versionManager.history()`
- * （database 作用域）可以完整撤销这个事务。`historyManager` 是私有字段，够不到。
+ * 是牺牲原子性还是越权撤销：要完整撤销这个事务，改用不带参数的
+ * `rxdb.versionManager.history()`（database 作用域）重新取一次历史再 undo。
+ * `VersionManager.historyManager` 是实现细节，不是绕开本错误的出口。
  */
 export class RxDBCrossScopeTransactionError extends RxDBError {
   constructor(

package/src/switch-branch-actions.ts

@@ -1,7 +1,7 @@
 import {
   EntityStaticType,
   getRxDBChangeKey,
-  LocalRxDBChangeRepository,
+  RxDBBranch,
   RxDBChange,
   RxDBError,
   SwitchVersionActions
@@ -14,8 +14,53 @@ import { VersionManager } from './VersionManager.js';
  * @param branchId 要切换到的分支ID
  * @returns 返回切换分支所需的操作序列
  */
-export const switch_branch_actions = async (version: VersionManager, branchId: string) => {
-  const { branchRepository, changeRepository } = await version.getLocalRepositories();
+export const switch_branch_actions = async (version: VersionManager, branchId: string) =>
+  compute_switch_branch_actions(await version.getLocalRepositories(), branchId);
+
+/**
+ * 算切换分支所需操作要用到的最小仓库能力。
+ *
+ * @remarks
+ * 与 {@link BranchChangeReader} 同一个理由写成结构化接口：本地仓库与事务执行器给出的
+ * `IRepository` 都接得住，两边的 `find` 入参本就是同一个类型。
+ */
+export interface SwitchBranchActionReaders {
+  /** 读分支行 */
+  readonly branchRepository: {
+    /**
+     * 按条件查分支
+     *
+     * @param options - 查询选项
+     * @returns 命中的分支行
+     */
+    find(options: EntityStaticType<typeof RxDBBranch, 'findOptions'>): Promise<RxDBBranch[]>;
+  };
+
+  /** 读变更行；见 {@link BranchChangeReader} */
+  readonly changeRepository: BranchChangeReader;
+}
+
+/**
+ * 用给定的仓库算「从当前 active 分支切到 `branchId`」要落的增删改——
+ * {@link switch_branch_actions} 的本体。
+ *
+ * @param readers - 见 {@link SwitchBranchActionReaders}
+ * @param branchId - 要切换到的分支 id
+ * @returns 切换分支所需的操作序列
+ *
+ * @remarks
+ * 拆出来是给 `@aiao/rxdb-plugin-working-tree` 的物化屏障用的：屏障要先把来源分支的投影撤掉，
+ * 再铺目标分支的快照，而它跑在 `switchBranch` 的 `prepare` 里，手上只有事务执行器的仓库——
+ * 绑在适配器上的本地仓库会在同一条连接上等屏障自己那笔事务，死锁。另写一份同义计算，
+ * 迟早会在「回滚标记算不算」上与普通切换分叉。
+ *
+ * @internal
+ */
+export const compute_switch_branch_actions = async (
+  readers: SwitchBranchActionReaders,
+  branchId: string
+): Promise<SwitchVersionActions> => {
+  const { branchRepository, changeRepository } = readers;
   const current_branch = (
     await branchRepository.find({
       where: {
@@ -222,7 +267,43 @@ export const get_switch_version_actions = (
   return actions;
 };
 
-const get_branch_max_change = async (changeRepository: LocalRxDBChangeRepository, branchId: string) => {
+/**
+ * 读一条分支 tip 所需要的最小仓库能力。
+ *
+ * @remarks
+ * 写成结构化的最小接口而不是直接用本地仓库类型，是为了让 {@link get_branch_max_change}
+ * 同时接得住事务执行器给出的 `IRepository<typeof RxDBChange>`——`enable-migration.ts`
+ * 跑在事务里，拿不到本地仓库。两边的 `find` 入参本就是同一个类型
+ * （`RxDBChangeStaticTypes['findOptions']`），所以这不是放宽，只是把已有的共同点写出来。
+ */
+export interface BranchChangeReader {
+  /**
+   * 按条件查变更
+   *
+   * @param options - 查询选项
+   * @returns 命中的变更行
+   */
+  find(options: EntityStaticType<typeof RxDBChange, 'findOptions'>): Promise<RxDBChange[]>;
+}
+
+/**
+ * 读一条分支当前的 tip：它自己那些未被回滚的变更里 id 最大的那条。
+ *
+ * @param changeRepository - 见 {@link BranchChangeReader}
+ * @param branchId - 分支 id
+ * @returns tip 变更行；该分支一条自有变更都没有时为 `undefined`（调用方据此退回分叉点）
+ *
+ * @remarks
+ * 导出是给 `enable-migration.ts` 复用的：「一条分支现在停在哪」这一问必须全局只有一个
+ * 答案（research.md R11）。迁移期另写一条同义查询，迟早会在「回滚标记算不算」
+ * 或「排序列是哪一个」上与切换路径分叉，表现为迁移放行了一条 `switchBranch` 走不通的分支。
+ *
+ * @internal
+ */
+export const get_branch_max_change = async (
+  changeRepository: BranchChangeReader,
+  branchId: string
+): Promise<RxDBChange | undefined> => {
   const changes = await changeRepository.find({
     where: {
       combinator: 'and',

package/src/undo-redo-apply.ts

@@ -1,5 +1,6 @@
 import {
   buildPushableRepositoryRules,
+  declareTrustedWrite,
   type FindOptions,
   type HistoryItem,
   type IRepository,
@@ -11,7 +12,9 @@ import {
   type RxDBChangeRuleGroup,
   RxDBSync,
   type RxDBSyncOrderByField,
-  type RxDBSyncRuleGroup
+  type RxDBSyncRuleGroup,
+  SKIP_BRANCH_SWITCH_PREPARE,
+  TrustedWriteIntent
 } from '@aiao/rxdb';
 import { BehaviorSubject, firstValueFrom, Subject } from 'rxjs';
 import { buildLastPushedMap } from './history-filters.js';
@@ -165,9 +168,16 @@ export async function applyUndoRedoHistories(
     if (operation === 'undo') {
       if (undoSession === undefined || !host.isUndoSessionCurrent(undoSession)) return;
     }
+    // undo/redo 是用户可感知的编辑，矩阵行 6 要求它**产生**单元（origin='undo_redo'）。
+    declareTrustedWrite(adapter, {
+      file: 'undo-redo-apply.ts',
+      symbol: 'applyUndoRedoHistories',
+      intent: TrustedWriteIntent.undo_redo
+    });
     // 不传 branchId：回放只作用于当前分支。在事务外采样分支 id 会让这次写入在并发切换时
     // 把 activated 与全部触发器倒回旧分支（见 SwitchBranchOptions.branchId）。
-    await adapter.switchBranch({ actions });
+    // 分支一动不动，所以没有前置条件可校验——这里的豁免是一句「我确实不需要」，不是漏传。
+    await adapter.switchBranch({ actions, prepare: SKIP_BRANCH_SWITCH_PREPARE });
 
     host.pushableCountTrigger$.next(Date.now());
     host.setRevertStateWatermarks(changes, operation === 'undo', stateUpdatedAt);
@@ -226,7 +236,7 @@ export async function updatePushableCount(host: UndoRedoApplyHost): Promise<void
       }
     });
 
-    const repoRules = buildPushableRepositoryRules(host.rxdb.config.entities, host.rxdb.config.sync, repoSyncs);
+    const repoRules = buildPushableRepositoryRules(host.rxdb.config.entities, host.rxdb.entitySync, repoSyncs);
     if (repoRules.length === 0) {
       publish(0);
       return;