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

package/src/history-item-builder.ts

@@ -0,0 +1,101 @@
+import { getRxDBEntityIdentityKey, HistoryItem, RxDBChange, UUID } from '@aiao/rxdb';
+import { isNil } from '@aiao/utils';
+/**
+ * 生成历史项的描述文本
+ *
+ * 规则：
+ * - 单条 INSERT/UPDATE/DELETE → 「创建 Foo」「更新 Foo」「删除 Foo」
+ * - 事务（多条变更）→ 「事务: 创建2条, 更新3条」
+ */
+export function generateHistoryDescription(changes: RxDBChange[]): string {
+  if (changes.length === 1) {
+    const change = changes[0];
+    const action =
+      change.type === 'INSERT' ? '创建'
+      : change.type === 'UPDATE' ? '更新'
+      : '删除';
+    return `${action} ${change.entity}`;
+  }
+
+  const operations: Record<string, number> = {};
+  for (const change of changes) {
+    const key = change.type.toLowerCase();
+    operations[key] = (operations[key] ?? 0) + 1;
+  }
+
+  const parts: string[] = [];
+  if (operations['insert']) parts.push(`创建${operations['insert']}条`);
+  if (operations['update']) parts.push(`更新${operations['update']}条`);
+  if (operations['delete']) parts.push(`删除${operations['delete']}条`);
+
+  return `事务: ${parts.join(', ')}`;
+}
+
+/**
+ * 从一组同事务的变更构造单个 HistoryItem
+ *
+ * @param changes - 属于同一事务的变更记录（至少一条）
+ * @returns 结构化的历史项，包含描述、类型、状态等信息
+ */
+export function createHistoryItem(changes: RxDBChange[]): HistoryItem {
+  const first_change = changes[0]!;
+  const count = changes.length;
+  const transactionId = first_change.transactionId ?? null;
+  const createdAt = first_change.createdAt!;
+  const namespace = first_change.namespace;
+  const entity = first_change.entity;
+  const type = transactionId ? 'TRANSACTION' : first_change.type;
+  const fingerprint = [type, getRxDBEntityIdentityKey(first_change.entityId), createdAt.getTime()].join(':');
+  const reverted = changes.some(c => isNil(c.revertChangeId) === false);
+  const redoInvalidated = changes.some(c => isNil(c.redoInvalidatedAt) === false);
+
+  return {
+    transactionId,
+    changeId: changes.reduce((max, c) => (c.id > max ? c.id : max), changes[0].id),
+    fingerprint,
+    changes,
+    type,
+    count,
+    createdAt,
+    description: generateHistoryDescription(changes),
+    namespace,
+    entity,
+    reverted,
+    redoInvalidated
+  };
+}
+
+/**
+ * 把按 id 降序排列的变更列表，转换为按事务分组的 HistoryItem 数组
+ *
+ * 转换逻辑：
+ * - 相同 transactionId 的连续变更合并为一个 HistoryItem
+ * - 无 transactionId 的变更单独成为一个 HistoryItem
+ */
+export function convertChangesToHistories(changes: RxDBChange[]): HistoryItem[] {
+  const histories: HistoryItem[] = [];
+  const next_transaction: RxDBChange[] = [];
+  let _transaction_id: UUID | undefined | null = undefined;
+
+  changes.forEach(d => {
+    if (d.transactionId && d.transactionId === _transaction_id) {
+      next_transaction.push(d);
+    } else {
+      _transaction_id = d.transactionId;
+      if (next_transaction.length) {
+        histories.push(createHistoryItem([...next_transaction]));
+        next_transaction.length = 0;
+      }
+      if (d.transactionId) {
+        next_transaction.push(d);
+      } else {
+        histories.push(createHistoryItem([d]));
+      }
+    }
+  });
+  if (next_transaction.length) {
+    histories.push(createHistoryItem([...next_transaction]));
+  }
+
+  return histories;
+}

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,61 @@
+/**
+ * @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';
+
+// ---------------------------------------------------------------------------
+// 以下六项只为 `@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

@@ -0,0 +1,192 @@
+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';
+
+/**
+ * 合并分支
+ *
+ * 将源分支的变更合并到当前激活分支（目标分支）。
+ *
+ * 支持两种策略：
+ * - `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! });
+        }
+        // 声明写在循环体内：声明是取用即清除的，提到循环外只有第一条变更带得上身份。
+        declareTrustedWrite(executor, {
+          file: 'merge-branch.ts',
+          symbol: 'merge_branch',
+          intent: TrustedWriteIntent.merge_per_change
+        });
+        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 记录
+    //
+    // 压缩只有一次写，本来不需要事务。开事务是为了**拿到一个执行器当声明的作用域**：
+    // 声明存在一个 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/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);