@aiao/rxdb-plugin-history 0.0.26 → 0.0.28

package/dist/merge-branch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"merge-branch.d.ts","sourceRoot":"","sources":["../src/merge-branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,kBAAkB,EAAE,iBAAiB,EAAmC,MAAM,YAAY,CAAC;AACtH,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,iBAAiB,MAAM,EACvB,UAAU,kBAAkB,KAC3B,OAAO,CAAC,iBAAiB,CA4H3B,CAAC"}
+{"version":3,"file":"merge-branch.d.ts","sourceRoot":"","sources":["../src/merge-branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,kBAAkB,EAClB,iBAAiB,EAIlB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAIrD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,cAAc,EACvB,gBAAgB,MAAM,EACtB,iBAAiB,MAAM,EACvB,UAAU,kBAAkB,KAC3B,OAAO,CAAC,iBAAiB,CA2J3B,CAAC"}

package/dist/remove-branch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remove-branch.d.ts","sourceRoot":"","sources":["../src/remove-branch.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,cAAc,EAAE,UAAU,MAAM,kBAkE5E,CAAC"}
+{"version":3,"file":"remove-branch.d.ts","sourceRoot":"","sources":["../src/remove-branch.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,cAAc,EAAE,UAAU,MAAM,kBA4E5E,CAAC"}

package/dist/restore-entity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"restore-entity.d.ts","sourceRoot":"","sources":["../src/restore-entity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAqB,oBAAoB,EAAa,MAAM,YAAY,CAAC;AAE5F,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,UAAU,EACvD,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAsE1B"}
+{"version":3,"file":"restore-entity.d.ts","sourceRoot":"","sources":["../src/restore-entity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAEL,UAAU,EAEV,oBAAoB,EAGrB,MAAM,YAAY,CAAC;AAEpB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,UAAU,EACvD,EAAE,EAAE,cAAc,EAClB,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CA0F1B"}

package/dist/scope-selection.d.ts

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

package/dist/scope-selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-selection.d.ts","sourceRoot":"","sources":["../src/scope-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,sBAAsB;AACtB,KAAK,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAIlF;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEtF;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEvF;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,WAAW,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GACX,sBAAsB,CAcxB;AAuBD;;;;;;;GAOG;AACH,qBAAa,8BAA+B,SAAQ,SAAS;IAEzD,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE;;IAH1C,0BAA0B;IACjB,KAAK,EAAE,YAAY;IAC5B,oBAAoB;IACX,SAAS,EAAE,SAAS,WAAW,EAAE;CAS7C"}
+{"version":3,"file":"scope-selection.d.ts","sourceRoot":"","sources":["../src/scope-selection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC9E,sBAAsB;AACtB,KAAK,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAIlF;AAED,+CAA+C;AAC/C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEtF;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAEvF;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,gCAAgC;IAChC,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,WAAW,EAAE,EACxB,KAAK,EAAE,YAAY,EACnB,IAAI,EAAE,MAAM,GACX,sBAAsB,CAcxB;AAuBD;;;;;;;;GAQG;AACH,qBAAa,8BAA+B,SAAQ,SAAS;IAEzD,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,oBAAoB;IACpB,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE;;IAH1C,0BAA0B;IACjB,KAAK,EAAE,YAAY;IAC5B,oBAAoB;IACX,SAAS,EAAE,SAAS,WAAW,EAAE;CAS7C"}

package/dist/switch-branch-actions.d.ts

@@ -1,4 +1,4 @@
-import { RxDBChange, SwitchVersionActions } from '@aiao/rxdb';
+import { EntityStaticType, RxDBBranch, RxDBChange, SwitchVersionActions } from '@aiao/rxdb';
 import { VersionManager } from './VersionManager.js';
 /**
  * 计算切换分支所需的操作
@@ -7,10 +7,81 @@ import { VersionManager } from './VersionManager.js';
  * @returns 返回切换分支所需的操作序列
  */
 export declare const switch_branch_actions: (version: VersionManager, branchId: string) => Promise<SwitchVersionActions<import('@aiao/rxdb').EntityType>>;
+/**
+ * 算切换分支所需操作要用到的最小仓库能力。
+ *
+ * @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 declare const compute_switch_branch_actions: (readers: SwitchBranchActionReaders, branchId: string) => Promise<SwitchVersionActions>;
 /**
  * 计算切换版本所需的操作
  * @param changes 需要计算的 changes
  * @param options
  */
 export declare const get_switch_version_actions: (changes: RxDBChange[], isPatch: boolean, actions?: SwitchVersionActions) => SwitchVersionActions;
+/**
+ * 读一条分支 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 declare const get_branch_max_change: (changeRepository: BranchChangeReader, branchId: string) => Promise<RxDBChange | undefined>;
 //# sourceMappingURL=switch-branch-actions.d.ts.map

package/dist/switch-branch-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"switch-branch-actions.d.ts","sourceRoot":"","sources":["../src/switch-branch-actions.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,UAAU,EAEV,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAU,SAAS,cAAc,EAAE,UAAU,MAAM,mEAmFpF,CAAC;AAkBF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,UAAU,EAAE,EACrB,SAAS,OAAO,EAChB,UAAS,oBAIR,KACA,oBA4FF,CAAC"}
+{"version":3,"file":"switch-branch-actions.d.ts","sourceRoot":"","sources":["../src/switch-branch-actions.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAEhB,UAAU,EACV,UAAU,EAEV,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAU,SAAS,cAAc,EAAE,UAAU,MAAM,mEACN,CAAC;AAEhF;;;;;;GAMG;AACH,MAAM,WAAW,yBAAyB;IACxC,WAAW;IACX,QAAQ,CAAC,gBAAgB,EAAE;QACzB;;;;;WAKG;QACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,UAAU,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;KAC1F,CAAC;IAEF,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,kBAAkB,CAAC;CAC/C;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,6BAA6B,GACxC,SAAS,yBAAyB,EAClC,UAAU,MAAM,KACf,OAAO,CAAC,oBAAoB,CAmF9B,CAAC;AAkBF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,GACrC,SAAS,UAAU,EAAE,EACrB,SAAS,OAAO,EAChB,UAAS,oBAIR,KACA,oBA4FF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,UAAU,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CAC1F;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,kBAAkB,EACpC,UAAU,MAAM,KACf,OAAO,CAAC,UAAU,GAAG,SAAS,CAahC,CAAC"}

package/dist/undo-redo-apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"undo-redo-apply.d.ts","sourceRoot":"","sources":["../src/undo-redo-apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,KAAK,IAAI,EACT,KAAK,oBAAoB,EAEzB,UAAU,EAEV,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAkB,OAAO,EAAE,MAAM,MAAM,CAAC;AAGhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEvF,KAAK,uBAAuB,GAAG,WAAW,CAAC,OAAO,QAAQ,CAAC,GAAG;IAC5D,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,QAAQ,EAAE,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC3G,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,SAAS,oBAAoB,KAAG,uBACA,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,qBAAqB,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,mBAAmB,IAAI,IAAI,CAAC;IAC5B,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC1D,2BAA2B,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACzD,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1F,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC5C,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAAC;CAC1D;AAED,sCAAsC;AACtC,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAoD3E;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,SAAS,EAAE,WAAW,EAAE,EACxB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAiEf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsEhF"}
+{"version":3,"file":"undo-redo-apply.d.ts","sourceRoot":"","sources":["../src/undo-redo-apply.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,WAAW,EAEhB,KAAK,IAAI,EACT,KAAK,oBAAoB,EAEzB,UAAU,EAEV,QAAQ,EACR,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,EAGvB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,eAAe,EAAkB,OAAO,EAAE,MAAM,MAAM,CAAC;AAGhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEvF,KAAK,uBAAuB,GAAG,WAAW,CAAC,OAAO,QAAQ,CAAC,GAAG;IAC5D,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,QAAQ,EAAE,iBAAiB,EAAE,oBAAoB,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CAC3G,CAAC;AAEF,eAAO,MAAM,0BAA0B,GAAI,SAAS,oBAAoB,KAAG,uBACA,CAAC;AAE5E;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,qBAAqB,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;IACxD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACjC,mBAAmB,IAAI,IAAI,CAAC;IAC5B,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC1D,2BAA2B,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;IACzD,wBAAwB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IAC1F,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAC5C,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAAC;CAC1D;AAED,sCAAsC;AACtC,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,iBAAiB,EACvB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC;IAAE,SAAS,EAAE,WAAW,EAAE,CAAC;IAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC,CAoD3E;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,SAAS,EAAE,WAAW,EAAE,EACxB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAwEf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsEhF"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@aiao/rxdb-plugin-history",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "History, undo/redo and branch management for Aiao RxDB.",
-  "homepage": "https://rxdb.netlify.app/docs/plugins",
+  "homepage": "https://rxdb.aiao.io/docs/plugins",
   "bugs": {
     "url": "https://github.com/aiao-io/rxdb/issues"
   },
@@ -54,7 +54,9 @@
   },
   "dependencies": {
     "rxjs": "^7.8.2",
-    "@aiao/rxdb": "0.0.26",
-    "@aiao/utils": "0.0.26"
+    "@aiao/utils": "^0.0.28"
+  },
+  "peerDependencies": {
+    "@aiao/rxdb": "^0.0.28"
   }
 }

package/src/HistoryManager.ts

@@ -1,4 +1,5 @@
 import {
+  declareTrustedWrite,
   EntityType,
   HistoryItem,
   HistoryScope,
@@ -7,7 +8,9 @@ import {
   REPOSITORY_SYNC_COMPLETE_EVENT,
   RxDB,
   RxDBBranch,
-  RxDBChange
+  RxDBChange,
+  SKIP_BRANCH_SWITCH_PREPARE,
+  TrustedWriteIntent
 } from '@aiao/rxdb';
 import {
   BehaviorSubject,
@@ -17,6 +20,7 @@ import {
   filter,
   firstValueFrom,
   map,
+  NEVER,
   Observable,
   ReplaySubject,
   shareReplay,
@@ -166,12 +170,21 @@ export class HistoryManager {
 
     const branchRepository = rxdb.entityManager.getRepository(RxDBBranch);
     const changeRepository = rxdb.entityManager.getRepository(RxDBChange);
-    const current_branch$ = branchRepository.findOne({
-      where: {
-        combinator: 'and',
-        rules: [{ field: 'activated', operator: '=', value: true }]
-      }
-    });
+    // 连上之后才查：仓库活查询会经适配器的就绪门把实例连起来，构造期直接订阅等于 `init()` 之后插件
+    // 自己把库连上了，「连接前先恢复」之类必须对着未连接实例做的操作就永远拿不到空目标。
+    // 断开时交 NEVER：丢掉挂在已断适配器上的查询，undo session 停在最后一个分支上，重连再查。
+    const current_branch$ = this.rxdb.connected$.pipe(
+      switchMap(connected =>
+        connected ?
+          branchRepository.findOne({
+            where: {
+              combinator: 'and',
+              rules: [{ field: 'activated', operator: '=', value: true }]
+            }
+          })
+        : NEVER
+      )
+    );
 
     this.#subscriptions.push(
       current_branch$.pipe(takeUntil(this.#destroy$)).subscribe({
@@ -297,7 +310,11 @@ export class HistoryManager {
           const baseRules = [
             { field: 'branchId' as const, operator: '=' as const, value: branch!.id },
             { field: 'revertChangeId' as const, operator: '=' as const, value: null },
-            { field: 'remoteId' as const, operator: '=' as const, value: null }
+            { field: 'remoteId' as const, operator: '=' as const, value: null },
+            // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被
+            // 推送，必须和 remoteId = null 一起排除，否则无关的被拒变更一有风吹草动
+            // 就会白触发一次 pushableCount 重算
+            { field: 'rejectedAt' as const, operator: '=' as const, value: null }
           ];
           return changeRepository
             .count({
@@ -497,13 +514,18 @@ export class HistoryManager {
   /**
    * 使 redo 栈失效。全部 trigger id ≤ {@link #redoInvalidationFloor} 视为迟到通知，跳过。
    *
+   * @remarks
+   * 这里**不查** `isUndoRedoInProgress` / `isInvalidatingRedo`：undo、redo 与本方法三个入口
+   * 全部排进 {@link HistoryManager.#runSerialized}，两个标志又只在同一个序列化任务内部置起
+   * 再复位，因此轮到本任务时它们必然已复位——查了也是一条走不到的分支。下面那句
+   * `isInvalidatingRedo = true` 留着是给 {@link HistoryManager.isExecutingUndoRedo} 读的，
+   * 真正生效的守卫在调用方 `VersionManager` 的 `if (!historyManager.isExecutingUndoRedo())`，
+   * 它连 `syncDepth` 一起看，覆盖比这里严。
+   *
    * @internal
    */
   async invalidateRedoStack(triggerChangeIds?: readonly number[]): Promise<void> {
     return this.#runSerialized(async () => {
-      if (this.isUndoRedoInProgress || this.isInvalidatingRedo) {
-        return;
-      }
       if (triggerChangeIds?.length && triggerChangeIds.every(id => id <= this.#redoInvalidationFloor)) {
         return;
       }
@@ -530,10 +552,18 @@ export class HistoryManager {
           });
         });
 
+        // 作废 redo 栈同样只重写投影（行 4）。这里与下面 undo-redo-apply 调的是同一个原语，
+        // 两者的结论相反，区别只在这条声明里。
+        declareTrustedWrite(adapter, {
+          file: 'HistoryManager.ts',
+          symbol: 'invalidateRedoStack',
+          intent: TrustedWriteIntent.redo_invalidation
+        });
         // 不传 branchId：这里只想把 actions 套用在**当前**分支上。自己先查再传会留下一个
         // 采样窗口——本方法是 detached 任务（变更通知还会被批处理 / 跨进程延迟），窗口内的一次
         // 真实 switchBranch 会让这条调用把 activated 与全部触发器倒回旧分支。
-        await adapter.switchBranch({ actions });
+        // 同上：分支不换，没有前置条件可校验。
+        await adapter.switchBranch({ actions, prepare: SKIP_BRANCH_SWITCH_PREPARE });
 
         this.clearRedoStack();
       } catch (error) {

package/src/VersionManager.ts

@@ -1,4 +1,5 @@
 import {
+  declareTrustedWrite,
   ENTITY_LOCAL_CREATE_EVENT,
   EntityLocalCreatedEvent,
   EntityType,
@@ -18,9 +19,14 @@ import {
   SwitchBranchBeginEvent,
   SwitchBranchCommitEvent,
   SwitchBranchRollbackEvent,
+  takeDeclaredWrite,
   TRANSACTION_BEGIN,
   TRANSACTION_COMMIT,
-  TRANSACTION_ROLLBACK
+  TRANSACTION_ROLLBACK,
+  TrustedWriteIntent,
+  type RxDBAdapterLocalBase,
+  type RxDBBranchSwitchPreconditions,
+  type TransactionExecutor
 } from '@aiao/rxdb';
 import { create_branch } from './create-branch.js';
 import { isIgnorableDetachedVersionEventError } from './detached-event-error.js';
@@ -127,8 +133,9 @@ export class VersionManager {
    * `HistoryManager` 已经拆掉了订阅，这里重建一个而不是复用 —— 复用等于把新纪元的
    * 变更喂给一条已 complete 的流。
    *
-   * 不发任何适配器读写，因此可以（也必须）早于引导链跑：`HistoryManager` 的分支流
-   * 要赶在第一条 `rxdb_change` 事件之前订阅上，装晚了那一批变更就不进历史。
+   * 不发任何适配器读写，也不会把实例连起来（分支流等 `connected$` 为真才查），因此可以
+   * （也必须）早于引导链跑：`HistoryManager` 的分支流要赶在第一条 `rxdb_change` 事件之前
+   * 订阅上，装晚了那一批变更就不进历史。
    */
   init() {
     if (this.#historyManagerDestroyed) {
@@ -256,43 +263,92 @@ export class VersionManager {
    * 切换到指定分支
    *
    * @param branchId - 目标分支 ID
+   * @param preconditions - 【可选】切换前要成立的条件；不传时行为与以往逐字节一致
    *
    * @remarks
    * 切换分支后会自动清空 redo 栈，因为 redo 历史在新分支中不再有效。
    * 如果目标分支与当前分支相同，则直接返回，避免不必要的操作。
+   *
+   * 第二形参是**纯扩展**：既有调用点一个都不用改，不传即不表态。做成默认开启的话，
+   * `switchBranch(id)` 会在任何有未提交改动的库上开始抛错——而历史子系统自己就在调它
+   * （undo/redo 回放、redo 失效），那些路径上工作树恒非空，默认开启等于让 undo 在有改动时不可用。
+   *
+   * 条件由**能力插件**校验，本方法一个字段都不读：判据是
+   * `@aiao/rxdb-plugin-working-tree` 贡献的那几张表，这里既不认识也不该认识它们。
+   * 反方向（本包 import 那个插件）是条依赖环，nx 的图插件会把 `run-many` 当场拒掉。
    */
-  async switchBranch(branchId: string): Promise<void> {
+  async switchBranch(branchId: string, preconditions?: RxDBBranchSwitchPreconditions): Promise<void> {
     const currentBranch = await this.getCurrentBranch();
     // 若切换到相同分支则直接返回，避免不必要操作
     if (currentBranch?.id === branchId) {
       return;
     }
     let switchCommitted = false;
+    // 声明挂在**适配器实例**上、取用即清除；下面的 catch 要靠它原路清掉。
+    let declaredAdapter: RxDBAdapterLocalBase | undefined;
+    // 适配器是否真的调了 prepare。见下方「没调用就抛」那一段。
+    let prepared = false;
     try {
       this.rxdb.dispatchEvent(new SwitchBranchBeginEvent(branchId));
+      // 问一句这次切换要不要整个交给某个能力贡献方（见 RxDBSystemContribution.takeOverBranchSwitch）。
+      // 排在 `getLocalRepositories()` **之前**：接管方自己解析适配器、自己开事务，这里先取一个
+      // 出来只是让它在接管路径上白白闲置一个纪元引用。
+      if (await this.#take_over_branch_switch(currentBranch?.id ?? null, branchId, preconditions)) {
+        // 接管方已经把 active 切过去了（它自己的事务已提交），此后与普通路径同一个状态。
+        switchCommitted = true;
+        this.#settle_switched(branchId);
+        return;
+      }
       const { adapter } = await this.getLocalRepositories();
       const actions = await switch_branch_actions(this, branchId);
+      // 切分支重写的是实体表的**投影**，不是用户的编辑：矩阵行 4 要求它不产生工作树单元。
+      // 不声明的话挂载点只看见「有人在调 switchBranch」，与 undo/redo（行 6，必须产生单元）
+      // 完全同形，切一次分支就会把整批物化写记成一批未提交变更。
+      declareTrustedWrite(adapter, {
+        file: 'VersionManager.ts',
+        symbol: 'switchBranch',
+        intent: TrustedWriteIntent.branch_materialization
+      });
+      declaredAdapter = adapter;
       const result = await adapter.switchBranch({
         branchId: branchId,
-        actions
+        actions,
+        // 前置校验跑在切换事务**内部**（见 #prepare_branch_switch）。`targetBranchId` 用
+        // 适配器解析出来的那一个而不是这里的 `branchId`：省略分支的调用点上只有它是对的。
+        prepare: async ({ executor, targetBranchId }) => {
+          prepared = true;
+          await this.#prepare_branch_switch(executor, currentBranch?.id ?? null, targetBranchId, preconditions);
+        }
       });
       // 适配器的 switchBranch 内部包了事务（见各适配器 version/switch_branch.ts），
       // 走到这里说明已提交。此后任何失败都不该再发 Rollback —— 分支确实切过去了。
       switchCommitted = true;
 
-      // 切换分支后清理状态：
-      // 1. 清空 redo 栈，因为 redo 历史在新分支中不再有效
-      // 2. 更新当前分支ID和历史起始时间为切换时刻
-      this.historyManager.clearRedoStack();
-      // undo session 是按分支存的，这里同步切视图。否则要等 current_branch$
-      // 这条响应式查询补发，切换后紧接着的 undo() 会撞上中途换 session 的竞态。
-      this.historyManager.setUndoBranch(branchId);
-
-      this.rxdb.dispatchEvent(new SwitchBranchCommitEvent(branchId));
+      this.#settle_switched(branchId);
+      // 适配器吞掉 `prepare` 不会以任何别的方式显形：分支照切、actions 照套、事件照发，
+      // 只是这一次切换没验过目标分支的提交图、没判过调用方提的条件、也没推进激活代际。
+      // 上面那几步记账照做完 —— 分支确实切过去了，把内存视图留在旧分支只是再坏一件事；
+      // 抛出只为一件事：不让这条契约违背被当成一次正常切换吞掉。
+      if (!prepared) {
+        throw new RxDBError(
+          `适配器 ${adapter.constructor.name} 的 switchBranch 没有调用 options.prepare：` +
+            `分支已经切到 ${branchId}，但这次切换一条前置条件都没校验过。` +
+            '适配器必须在解析出目标分支之后、动第一行之前 await 它（见 rxdb-adapter.ts › SwitchBranchOptions.prepare）。'
+        );
+      }
       return result;
     } catch (error) {
+      // 前置校验现在在事务内判，被拒是一条**日常**路径（工作树不干净就该拒），而那条路径上
+      // 一个写原语都没跑过——声明还原封不动挂在适配器上。留着的话，这个适配器的下一次
+      // mergeChanges 会把它取走，那次合并于是按 projection_rewrite 判定：一个工作树单元都不产生，
+      // 拉回来的远端改动凭空消失。
+      if (declaredAdapter) takeDeclaredWrite(declaredAdapter);
       if (!switchCommitted) {
         this.rxdb.dispatchEvent(new SwitchBranchRollbackEvent(branchId));
+        // 诊断落盘排在**回滚之后**、重新抛出之前：判定失败发生在那次注定回滚的事务里，
+        // 写在里面的标记会跟着一起消失（见 RxDBSystemContribution.settleBranchSwitchFailure）。
+        // 只在没提交的那条路径上跑——切换已经成立之后的失败不是「没切成」。
+        await this.#settle_branch_switch_failure(currentBranch?.id ?? null, branchId, error);
       }
       throw error;
     }
@@ -440,6 +496,116 @@ export class VersionManager {
     return getCurrentBranch(this.rxdb);
   }
 
+  /**
+   * 逐个问贡献方：这次切换能不能发生；能的话，把该在同一个事务里做掉的事做掉。
+   *
+   * @param executor - **切换事务本身**的执行器，由适配器经 `SwitchBranchOptions.prepare` 交过来
+   * @param currentBranchId - 当前分支 id；一条 active 分支都没有时为 `null`
+   * @param targetBranchId - 适配器解析之后的目标分支 id
+   * @param preconditions - 调用方提出的条件；没提出时是 `undefined`
+   *
+   * @remarks
+   * **跑在切换事务内部。** 它以前自己开一个只读事务、在 `adapter.switchBranch()` **之前**跑完：
+   * 那个事务提交到切换事务开始之间是一段没有任何东西守着的窗口，窗口里的一次写能让刚判过的
+   * 「工作树干净」重新变脏，而切换照样完成。搬进来之后，「校验通过」与「切换完成」不再是
+   * 两件可以分开发生的事——同一个事务，要么一起成立，要么一起没发生。
+   *
+   * 代价是顺序反了过来：`switch_branch_actions()` 现在排在校验**之前**（它算出来的重放指令
+   * 得先交给适配器才谈得上开事务），目标分支的链已知损坏时会白算一遍。那一遍只读不写，
+   * 被拒时一行都还没动——拿一次白算换掉上面那段窗口。
+   *
+   * **每一次真正发生的切换上都跑，与调用方提没提条件无关。** 目标分支的提交图可达损坏
+   * 与有没有 `preconditions` 无关（SC-013：三条入口各自返回 `commit_graph_corrupted`）；
+   * 只在带选项时跑的话，日常那条不带选项的切换会一路切进一份重放不出来的历史。
+   *
+   * 「真正发生」是字面意思：A→A 的调用在 {@link VersionManager.switchBranch} 里就早返回了
+   * （同文件上方的 `currentBranch?.id === branchId`），根本走不到这里。那条路径上没有要防的
+   * 东西——分支没换，目标分支的历史也没有被重放，工作树连一行都不会动。把早返回去掉好让
+   * 守卫「真的无条件」是反向的：切到当前分支会因为它自己的历史损坏而失败，而这次切换
+   * 本来什么都不做。
+   *
+   * 串行而非 `Promise.all`：`executor` 是并发度为 1 的队列，并行发起只会让读取顺序取决于
+   * 各贡献方内部 await 的排布。一个贡献方都没有时这里是一次空循环——没装能力插件的库上，
+   * 这条扩展不多开事务、也不多发一条查询。
+   */
+  /**
+   * 切换成立之后那几步与库无关的记账。
+   *
+   * @param branchId - 已经切过去的分支 id
+   *
+   * @remarks
+   * 抽出来只为一件事：**接管路径与普通路径必须记同一笔账**。两处各抄一遍的那天，
+   * 接管路径上漏掉的 `setUndoBranch()` 不会以任何形式报错——它只是让切换后紧接着的
+   * 一次 `undo()` 撤到上一条分支的 session 上去。
+   *
+   * 三步的顺序是：redo 栈先清（它在新分支上不再有效），undo 视图再切（按分支存，
+   * 等 `current_branch$` 补发会让紧接着的 `undo()` 撞上中途换 session 的竞态），
+   * 事件最后发（订阅者醒来时这两样都该已经是新分支的）。
+   */
+  #settle_switched(branchId: string): void {
+    this.historyManager.clearRedoStack();
+    this.historyManager.setUndoBranch(branchId);
+    this.rxdb.dispatchEvent(new SwitchBranchCommitEvent(branchId));
+  }
+
+  /**
+   * 问各贡献方要不要接管这次切换，第一个答应的就停。
+   *
+   * @param currentBranchId - 当前分支 id
+   * @param targetBranchId - 目标分支 id
+   * @param preconditions - 调用方提出的前置条件
+   * @returns 有人接管了就是 `true`，此时 active 已经切过去了
+   *
+   * @remarks
+   * 问到第一个 `'switched'` 为止：两个贡献方都接管等于 active 被切两次，而第二次看到的
+   * 现场已经是第一次的结果。串行的理由与 {@link VersionManager.#prepare_branch_switch} 同源。
+   */
+  async #take_over_branch_switch(
+    currentBranchId: string | null,
+    targetBranchId: string,
+    preconditions: RxDBBranchSwitchPreconditions | undefined
+  ): Promise<boolean> {
+    for (const contribution of this.rxdb.systemContributions) {
+      const verdict = await contribution.takeOverBranchSwitch({ currentBranchId, targetBranchId, preconditions });
+      if (verdict === 'switched') return true;
+    }
+    return false;
+  }
+
+  /**
+   * 切换事务回滚之后，让各贡献方落下自己的失败诊断。
+   *
+   * @param currentBranchId - 仍然 active 的那条分支
+   * @param targetBranchId - 没切成的目标分支
+   * @param error - 让这次切换失败的那个错误
+   *
+   * @remarks
+   * 调用点在 `catch` 里，紧接着就要把 `error` 重新抛出去——所以贡献方那一侧带着一条
+   * 「不得抛出」的硬契约（见 {@link RxDBSystemContribution.settleBranchSwitchFailure}）。
+   * 这里**不**加 try/catch 替它兜：兜住就等于宣布这个契约可以不遵守，而真正被兜掉的那个
+   * 异常从此没有任何一处会显形。
+   */
+  async #settle_branch_switch_failure(
+    currentBranchId: string | null,
+    targetBranchId: string,
+    error: unknown
+  ): Promise<void> {
+    for (const contribution of this.rxdb.systemContributions) {
+      await contribution.settleBranchSwitchFailure({ currentBranchId, targetBranchId, error });
+    }
+  }
+
+  async #prepare_branch_switch(
+    executor: TransactionExecutor,
+    currentBranchId: string | null,
+    targetBranchId: string,
+    preconditions: RxDBBranchSwitchPreconditions | undefined
+  ): Promise<void> {
+    for (const contribution of this.rxdb.systemContributions) {
+      await contribution.prepareBranchSwitch({ executor, currentBranchId, targetBranchId, preconditions });
+    }
+  }
+
   #runDetachedEventTask(task: Promise<void>, label: string) {
     void task.catch(error => {
       if (isIgnorableDetachedVersionEventError(error)) {

package/src/create-branch.ts

@@ -1,4 +1,5 @@
 import {
+  assertUsableBranchId,
   type LocalRxDBBranchRepository,
   type LocalRxDBChangeRepository,
   resolve_current_branch,
@@ -22,8 +23,18 @@ import { VersionManager } from './VersionManager.js';
  *
  * 远端 `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 是否存在（本地）
   //
@@ -107,11 +118,24 @@ export const create_branch = async (version: VersionManager, branchId: string, f
     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;
   });