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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aiao Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @aiao/rxdb-plugin-history
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Implements: [US-025 核心插件化外移](https://github.com/aiao-io/rxdb/blob/main/requirements/stories/core/US-025-core-plugin-extraction.md)
+
+历史、撤销重做与分支。装上它，`rxdb.versionManager` 才存在。
+
+核心 `@aiao/rxdb` 保留的是**原语**：三张系统表（`RxDBBranch` / `RxDBChange` / `RxDBSync`）、变更编解码、冲突模型、同步资格判定，以及 `getCurrentBranch()`。这些东西并不专属历史子系统——变更日志触发器直接写 `branchId`，`RxDBChange.branch` 会生成真实的 `REFERENCES rxdb$rxdb_branch(id)` 外键，整条响应式增量链路都跑在 `rxdb_change` 上。搬进本包的是**消费者**：读历史、撤销重做、建/切/合/删分支。
+
+推拉同步的调度**不在这里**，它住在 [`@aiao/rxdb-plugin-sync`](../rxdb-plugin-sync/README.md)：`rxdb.syncManager.push()` / `.pull()` / `.sync()`。那个插件 `inject: ['plugin:history']`，反向没有依赖——本包不认识同步包。
+
+## 安装
+
+```bash
+pnpm add @aiao/rxdb @aiao/rxdb-plugin-history
+```
+
+## 使用
+
+```typescript
+import { RxDB, SyncType } from '@aiao/rxdb';
+import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+
+const rxdb = new RxDB({
+  dbName: 'notes',
+  entities: [Note],
+  sync: { type: SyncType.Full, local: { adapter: 'wa-sqlite' }, remote: { adapter: 'supabase' } }
+});
+
+// 传工厂函数本身，不要调用它；必须早于 connect()——connect() 内部就会调 init()
+rxdb.use(rxDBPluginHistory).adapter('wa-sqlite' /* … */);
+
+await rxdb.connect('wa-sqlite');
+
+// 撤销重做
+await rxdb.versionManager.history().undo();
+await rxdb.versionManager.history(Note).redo(2);
+
+// 分支
+await rxdb.versionManager.createBranch('feature-a');
+await rxdb.versionManager.switchBranch('feature-a');
+await rxdb.versionManager.mergeBranch('feature-a');
+```
+
+`use()` 的时机是有意义的：`use()` 在 `init()` 之前调用则插件在 `init()` 时装上，之后调用则立即装上，而 `connect()` 内部会调 `init()`。写在 `connect()` 后面，第一批变更已经错过了历史订阅。
+
+## 主要能力
+
+| 分组 | 入口                                                                                                    |
+| ---- | ------------------------------------------------------------------------------------------------------- |
+| 历史 | `history(scope?)` → `histories$` / `undoHistories$` / `redoHistories$` / `count$` / `undo()` / `redo()` |
+| 分支 | `createBranch()` / `switchBranch()` / `mergeBranch()` / `removeBranch()`                                |
+| 计数 | `pushableCount$` / `pullableCount$`                                                                     |
+| 恢复 | `restoreEntity()`                                                                                       |
+
+`history()` 的作用域按入参解析：无参 = 整库，传实体类 = 该仓储，传实例 = 该行。撤销一个跨作用域事务时抛 `RxDBCrossScopeTransactionError`，而不是只撤一半——半个事务比失败难查得多。
+
+## 没装插件时
+
+`rxdb.versionManager` **不存在**（读到 `undefined`），核心不给一个什么都不做的空壳。这对下游是可见的契约而非退化路径：
+
+- **DevTools**：`DevToolsRxDB.versionManager` 是可选成员，连接器据实报「分支能力不可用」，不会把它谎报成「一个分支都没有」。
+- **同步状态枢纽**：`SyncStateHub` 留在核心，但可推送计数由本插件经 `bindPushableCount()` 接上。没装插件，那个读数就是无人维护——这正是实情。待拉数归 `@aiao/rxdb-plugin-sync`：它接住远端适配器发出的 `requestPullableRefresh()`。
+- **类型**：`versionManager` 由本包的 `declare module '@aiao/rxdb'` 声明。只消费、不负责安装的模块（框架组件、共享 UI）应写 `import type {} from '@aiao/rxdb-plugin-history';`——它把类型声明拉进编译单元，同时在 emit 时整句擦除，不产生运行时依赖。
+
+## 连接纪元
+
+插件声明 `lifecycle: 'scoped'`，三处宿主改动全部登记在 `install(scope)` 收到的作用域上，`disconnectAll()` 时逆序释放，宿主不调用 `destroy()`：`VersionManager` 实例本身（连同 `destroy()`）、`rxdb.versionManager` 槽位、`syncState.bindPushableCount()` 订阅。重新 `connect()` 装的是一个全新的管理器，而不是复活上一纪元那个——后者指向的事件总线已经拆了。
+
+本包**不声明 `inject`**，所以它在 `init()` 里就装完；`@aiao/rxdb-plugin-sync` 声明了 `inject: ['plugin:history']`，要等本包装好才轮到它，那个槽位得 `await connect()` 之后才在。
+
+插件**不声明 `inject`**：`VersionManager.init()` 只挂监听与订阅，一条适配器读写都不发。声明 `adapter:local` 会把安装推到引导链之后，而分支流必须在第一条 `rxdb_change` 事件到达之前就订阅上。

package/dist/HistoryManager.d.ts

@@ -0,0 +1,87 @@
+import { EntityType, HistoryItem, HistoryScope, HistoryScopeAPI, RxDB } from '@aiao/rxdb';
+import { Observable, Subject } from 'rxjs';
+import { UndoSessionEvent } from './history-undo-session.types.js';
+export { filterHistoriesByScope, filterUndoableHistories, getScopeKey } from './history-filters.js';
+export { generateHistoryDescription } from './history-item-builder.js';
+/**
+ * 历史记录管理器：变更历史、内存 redo 栈、多作用域 undo/redo API。
+ *
+ * 数据流：`RxDBChange[] → #all_changes$ → histories$ → undoHistories$ / redoHistories$`
+ */
+export declare class HistoryManager {
+    #private;
+    private rxdb;
+    private isUndoRedoInProgress;
+    private isInvalidatingRedo;
+    /** 进行中的 pull/push 深度（可重入，避免并发同步提前清标志） */
+    private syncDepth;
+    private readonly redoStack;
+    private history_cache;
+    private history_ref_counts;
+    histories$: Observable<HistoryItem[]>;
+    undoHistories$: Observable<HistoryItem[]>;
+    redoHistories$: Observable<HistoryItem[]>;
+    undoCount$: Observable<number>;
+    redoCount$: Observable<number>;
+    /** 内部错误流：派生流降级的同时把错误推给订阅者 */
+    readonly errors$: Subject<Error>;
+    pushableCount$: Observable<number>;
+    pullableCount$: Observable<number>;
+    count$: Observable<number>;
+    /**
+     * 当前撤销 session generation。
+     *
+     * @internal 供 VersionManager 在事务开始时捕获事件所属 session
+     */
+    get undoSessionGeneration(): number;
+    constructor(rxdb: RxDB);
+    destroy(): void;
+    /** 增加远程待 pull 计数 */
+    incrementPullableCount(count: number): void;
+    /** session 重置时清零 pullable；pull 结束结算走 {@link settlePullableCount} */
+    resetPullableCount(): void;
+    /** pull 开始前签发结算令牌，必须在真正发起 pull 之前取 */
+    beginPullableSettlement(): number;
+    /** 用远端水位线校准待拉计数 */
+    reconcilePullableCount(token: number, count: number): void;
+    /** 按一次 pull 的实际覆盖范围结算待拉计数 */
+    settlePullableCount(token: number, settlement: {
+        complete: boolean;
+        pulled: number;
+    }): void;
+    /** 推入 redo 栈（新项在前，超容量丢尾） */
+    pushToRedoStack(items: HistoryItem[]): void;
+    /** 按身份从 redo 栈移除已应用项（作用域 redo 未必在栈顶） */
+    removeFromRedoStack(items: HistoryItem[]): HistoryItem[];
+    /** 清空 redo 栈 */
+    clearRedoStack(): void;
+    /** switchBranch 提交后同步切 undo session，避免 await 中间引用比对失配 */
+    setUndoBranch(branchId: string): void;
+    /** 清空当前分支 undo/redo；连接级重置用 {@link clearAllUndoHistory} */
+    clearUndoHistory(): void;
+    /** 清空所有分支 undo/redo，并推进 {@link #undoSessionFloor} */
+    clearAllUndoHistory(): void;
+    /** 用属于当前 clear session 的本地写入事件恢复 undo */
+    resetSyncCleared(changeIds?: readonly number[], event?: UndoSessionEvent): void;
+    /** 正在执行 undo/redo 或同步 */
+    isExecutingUndoRedo(): boolean;
+    /** 在可重入同步上下文中执行：期间变更不影响 undo/redo 栈 */
+    syncing<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * 使 redo 栈失效。全部 trigger id ≤ {@link #redoInvalidationFloor} 视为迟到通知，跳过。
+     *
+     * @remarks
+     * 这里**不查** `isUndoRedoInProgress` / `isInvalidatingRedo`：undo、redo 与本方法三个入口
+     * 全部排进 {@link HistoryManager.#runSerialized}，两个标志又只在同一个序列化任务内部置起
+     * 再复位，因此轮到本任务时它们必然已复位——查了也是一条走不到的分支。下面那句
+     * `isInvalidatingRedo = true` 留着是给 {@link HistoryManager.isExecutingUndoRedo} 读的，
+     * 真正生效的守卫在调用方 `VersionManager` 的 `if (!historyManager.isExecutingUndoRedo())`，
+     * 它连 `syncDepth` 一起看，覆盖比这里严。
+     *
+     * @internal
+     */
+    invalidateRedoStack(triggerChangeIds?: readonly number[]): Promise<void>;
+    /** 创建（或取出缓存的）作用域历史 API */
+    history<T extends EntityType>(options?: T | InstanceType<T> | HistoryScope): HistoryScopeAPI;
+}
+//# sourceMappingURL=HistoryManager.d.ts.map

package/dist/HistoryManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HistoryManager.d.ts","sourceRoot":"","sources":["../src/HistoryManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EAGf,IAAI,EAKL,MAAM,YAAY,CAAC;AACpB,OAAO,EASL,UAAU,EAGV,OAAO,EAIR,MAAM,MAAM,CAAC;AAId,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AAazC,OAAO,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACpG,OAAO,EAAE,0BAA0B,EAAE,MAAM,2BAA2B,CAAC;AAgBvE;;;;GAIG;AACH,qBAAa,cAAc;;IA0Fb,OAAO,CAAC,IAAI;IA7BxB,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,kBAAkB,CAAS;IACnC,yCAAyC;IACzC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmB;IAC7C,OAAO,CAAC,aAAa,CAAsC;IAC3D,OAAO,CAAC,kBAAkB,CAA6B;IACvD,UAAU,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACtC,cAAc,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1C,cAAc,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IAC1C,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAC/B,UAAU,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE/B,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,iBAAwB;IACxC,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,cAAc,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAEnC,MAAM,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE3B;;;;OAIG;IACH,IAAI,qBAAqB,IAAI,MAAM,CAElC;gBAEmB,IAAI,EAAE,IAAI;IAqL9B,OAAO,IAAI,IAAI;IAaf,oBAAoB;IACpB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM3C,oEAAoE;IACpE,kBAAkB,IAAI,IAAI;IAK1B,sCAAsC;IACtC,uBAAuB,IAAI,MAAM;IAIjC,mBAAmB;IACnB,sBAAsB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAK1D,6BAA6B;IAC7B,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAU3F,4BAA4B;IAC5B,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,IAAI;IAI3C,wCAAwC;IACxC,mBAAmB,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE;IAIxD,gBAAgB;IAChB,cAAc,IAAI,IAAI;IAItB,yDAAyD;IACzD,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAIrC,0DAA0D;IAC1D,gBAAgB,IAAI,IAAI;IAUxB,qDAAqD;IACrD,mBAAmB,IAAI,IAAI;IAqB3B,yCAAyC;IACzC,gBAAgB,CAAC,SAAS,GAAE,SAAS,MAAM,EAAO,EAAE,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI;IAkDnF,yBAAyB;IACzB,mBAAmB,IAAI,OAAO;IAI9B,uCAAuC;IACjC,OAAO,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IASlD;;;;;;;;;;;;OAYG;IACG,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmD9E,0BAA0B;IAC1B,OAAO,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,eAAe;CA6N7F"}

package/dist/VersionManager.d.ts

@@ -0,0 +1,243 @@
+import { EntityType, HistoryScopeAPI, MergeBranchOptions, MergeBranchResult, RestoreEntityOptions, RxDB, RxDBBranch, RxDBBranchSwitchPreconditions } from '@aiao/rxdb';
+import { PushInFlightRegistry } from './push-inflight.js';
+import { SyncHistoryBridge } from './sync-history-bridge.js';
+/**
+ * 版本管理器
+ *
+ * 负责管理数据库的分支、撤销/重做与版本历史：
+ * - 分支管理（创建、删除、切换、合并）
+ * - 撤销/重做操作（数据库级别）
+ * - Redo 栈的自动失效（当有新操作时）
+ *
+ * @remarks
+ * 推拉同步**不在**这里。US-025 阶段 D 之后它住在 `@aiao/rxdb-plugin-sync` 的
+ * `SyncManager` 上，两边只经 {@link VersionManager.syncBridge} 这一张窄接口相遇。
+ */
+export declare class VersionManager {
+    #private;
+    readonly rxdb: RxDB;
+    /**
+     * 撤销/重做辅助类
+     * 管理历史记录和内存 redo 栈
+     */
+    private historyManager;
+    /**
+     * 「哪些变更此刻正在飞往远端」的登记处。
+     *
+     * @remarks
+     * push 与 undo 唯一的会合点。push 在远端往返之前认领区间，undo 把认领区间当成已推 ——
+     * 没有它，往返窗口内的一次撤销会造成本地与远端永久分叉，见 {@link PushInFlightRegistry}。
+     *
+     * 挂在 `VersionManager` 上是因为两边都只经它相遇：`pushRepository(vm, …)` 直接拿到它，
+     * `HistoryManager` 经 `rxdb.versionManager` 拿到它。生命周期跟随实例，不跨实例共享。
+     *
+     * @internal
+     */
+    readonly pushInFlight: PushInFlightRegistry;
+    /**
+     * 交给同步插件的那一小块历史能力。
+     *
+     * @remarks
+     * 传闭包而不是 `this.historyManager`：`init()` 会在断连重连后重建管理器，
+     * 桥必须每次现取，见 {@link createSyncHistoryBridge}。
+     *
+     * @internal
+     */
+    readonly syncBridge: SyncHistoryBridge;
+    /**
+     * 可 push 的变更数量流
+     *
+     * 实时追踪本地未推送的有效变更数量：
+     * - 排除已撤销的变更（revertChangeId != null）
+     * - 排除从远程 pull 来的变更（remoteId != null）
+     */
+    get pushableCount$(): import('rxjs').Observable<number>;
+    /**
+     * 远程待 pull 的变更数量流
+     *
+     * 通过监听远程事件（INSERT/UPDATE/DELETE）累计：
+     * - 收到远程变更事件时计数+1
+     * - pull 完成后计数重置为 0
+     *
+     * 用于 UI 显示"有 N 条远程更新可拉取"
+     */
+    get pullableCount$(): import('rxjs').Observable<number>;
+    /**
+     * @param rxdb - 宿主实例
+     *
+     * @remarks
+     * 构造即建 {@link HistoryManager}，而它在自己的构造器里就订阅了活跃分支流 ——
+     * 所以「造出来」本身已经是一次资源获取，调用方必须把 {@link VersionManager.destroy}
+     * 登记在作用域上，哪怕后面的 {@link VersionManager.init} 还没跑。
+     */
+    constructor(rxdb: RxDB);
+    /**
+     * 挂上事务与本地写入的事件监听，开始记历史。
+     *
+     * @remarks
+     * 与 {@link VersionManager.destroy} 成对，可重入：上一轮 `destroy()` 过的
+     * `HistoryManager` 已经拆掉了订阅，这里重建一个而不是复用 —— 复用等于把新纪元的
+     * 变更喂给一条已 complete 的流。
+     *
+     * 不发任何适配器读写，也不会把实例连起来（分支流等 `connected$` 为真才查），因此可以
+     * （也必须）早于引导链跑：`HistoryManager` 的分支流要赶在第一条 `rxdb_change` 事件之前
+     * 订阅上，装晚了那一批变更就不进历史。
+     */
+    init(): void;
+    /**
+     * 摘掉全部事件监听与订阅，并销毁 {@link HistoryManager}。
+     *
+     * @remarks
+     * 幂等。事务深度与代次一并清零：拆卸可能发生在事务中途，留着计数会让下一个纪元
+     * 以为自己开局就在一笔未结的事务里。
+     */
+    destroy(): void;
+    /**
+     * 作废本连接积累的历史上下文：清空全部分支的 undo 会话与待拉计数。
+     *
+     * @remarks
+     * 供切库 / 重连这类「本地数据整体换了一份」的场景调用。清的是**全部**分支而不只是
+     * 当前分支 —— 换掉的是整个数据源，其它分支上那些 undo 条目指向的行同样已经不在了。
+     */
+    resetSessionState(): void;
+    /**
+     * 创建新分支
+     * @param branchId 分支 id
+     * @param fromChangeId 从哪个 changeId 创建新分支
+     */
+    createBranch(branchId: string, fromChangeId?: number): Promise<InstanceType<typeof RxDBBranch>>;
+    /**
+     * 删除分支
+     * @param branchId 分支 id
+     */
+    removeBranch(branchId: string): Promise<void>;
+    /**
+     * 切换到指定分支
+     *
+     * @param branchId - 目标分支 ID
+     * @param preconditions - 【可选】切换前要成立的条件；不传时行为与以往逐字节一致
+     *
+     * @remarks
+     * 切换分支后会自动清空 redo 栈，因为 redo 历史在新分支中不再有效。
+     * 如果目标分支与当前分支相同，则直接返回，避免不必要的操作。
+     *
+     * 第二形参是**纯扩展**：既有调用点一个都不用改，不传即不表态。做成默认开启的话，
+     * `switchBranch(id)` 会在任何有未提交改动的库上开始抛错——而历史子系统自己就在调它
+     * （undo/redo 回放、redo 失效），那些路径上工作树恒非空，默认开启等于让 undo 在有改动时不可用。
+     *
+     * 条件由**能力插件**校验，本方法一个字段都不读：判据是
+     * `@aiao/rxdb-plugin-working-tree` 贡献的那几张表，这里既不认识也不该认识它们。
+     * 反方向（本包 import 那个插件）是条依赖环，nx 的图插件会把 `run-many` 当场拒掉。
+     */
+    switchBranch(branchId: string, preconditions?: RxDBBranchSwitchPreconditions): Promise<void>;
+    /**
+     * 合并分支
+     *
+     * 将源分支的变更合并到当前激活分支（目标分支）。
+     *
+     * @param sourceBranchId - 源分支 ID
+     * @param options - 合并选项
+     * @returns 合并结果
+     *
+     * @remarks
+     * 支持两种策略：
+     * - `squash`（默认）：将源分支所有变更压缩为最小操作集后一次性应用，目标分支只产生一组变更记录
+     * - `normal`：逐条应用源分支变更，每条变更在目标分支产生独立的变更记录（保留历史细节）
+     *
+     * 合并后会清空 undo/redo 历史，因为合并操作不可逆。
+     * 可选通过 `deleteSource: true` 在合并后删除源分支。
+     *
+     * @example
+     * ```typescript
+     * // 压缩合并（默认）
+     * const result = await rxdb.versionManager.mergeBranch('feature-x');
+     * console.log(`Merged ${result.merged} changes`);
+     *
+     * // 普通合并
+     * const result = await rxdb.versionManager.mergeBranch('feature-x', {
+     *   strategy: 'normal'
+     * });
+     *
+     * // 合并后删除源分支
+     * const result = await rxdb.versionManager.mergeBranch('feature-x', {
+     *   deleteSource: true
+     * });
+     * ```
+     */
+    mergeBranch(sourceBranchId: string, options?: MergeBranchOptions): Promise<MergeBranchResult>;
+    /**
+     * 获取特定作用域的历史记录 API
+     *
+     * @param options - 作用域选项：
+     *   - 不传参数 → database 作用域（整个数据库）
+     *   - EntityType 类 → repository 作用域（该实体的所有记录）
+     *   - 实体实例 → entity 作用域（该实例的历史）
+     * @returns 统一的历史记录 API 接口
+     *
+     * @example
+     * ```ts
+     * // 数据库级别
+     * const dbHistory = versionManager.history();
+     *
+     * // 仓库级别（所有 User 记录）
+     * const userHistory = versionManager.history(User);
+     *
+     * // 实体级别（单个用户）
+     * const entityHistory = versionManager.history(userInstance);
+     * ```
+     */
+    history<T extends EntityType>(options?: T | InstanceType<T>): HistoryScopeAPI;
+    /**
+     * 恢复被删除的实体
+     *
+     * 根据 RxDBChange 记录中的 inversePatch 重新插入实体，
+     * 恢复操作本身会生成新的 RxDBChange 记录（可被 push 到远程）。
+     *
+     * @param entity - 被删除的实体实例（需要包含 metadata 信息）
+     * @param options - 恢复选项，包含 changeId（DELETE 类型的 RxDBChange 记录 ID）
+     * @returns 恢复后的实体实例
+     */
+    restoreEntity<T extends EntityType>(entity: InstanceType<T>, options: RestoreEntityOptions): Promise<InstanceType<T>>;
+    /**
+     * 取本地适配器上的系统表仓库。
+     *
+     * @returns `branchRepository` / `changeRepository` 与它们所属的本地适配器
+     *
+     * @remarks
+     * 每次都经 `localAdapter$` 重新解析，不缓存：适配器随连接纪元换，缓下来的那一份
+     * 会在重连之后指向已拆的旧实例。
+     */
+    getLocalRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').LocalRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').LocalRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').LocalRxDBAdapter;
+    }>;
+    /**
+     * 取远端适配器上的系统表仓库。
+     *
+     * @returns `branchRepository` / `changeRepository` 与它们所属的远端适配器
+     *
+     * @remarks
+     * 未配置远端时 `remoteAdapter$` 不发值，调用会一直挂着 —— 这是有意的：同步路径
+     * 本来就只在配了远端时才走，返回一个空壳只会把「没配远端」推迟到更深的地方才报。
+     */
+    getRemoteRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').RemoteRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').RemoteRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').RemoteRxDBAdapter;
+    }>;
+    /**
+     * 取当前分支；没有激活分支时激活（或新建）`main`。
+     *
+     * @remarks
+     * 分两段是有意的：
+     *
+     * - **热路径**（已有激活分支）不开事务。同步插件的远端事件链路里每条事件都要调它
+     *   （`sync-listeners` 的 `filterByBranch`），把整段包进事务能修好并发，
+     *   但会让每次读都去抢并发度 1 的写队列槽位。
+     * - **冷路径**（查不到激活分支）才开事务，并在事务内**重做一遍检查**（双重检查）。
+     * 否则两个并发调用会双双走到 `create`，第二个撞主键报错。
+     */
+    getCurrentBranch(): Promise<RxDBBranch>;
+}
+//# sourceMappingURL=VersionManager.d.ts.map

package/dist/VersionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VersionManager.d.ts","sourceRoot":"","sources":["../src/VersionManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,UAAU,EAIV,eAAe,EAIf,kBAAkB,EAClB,iBAAiB,EACjB,oBAAoB,EACpB,IAAI,EACJ,UAAU,EAWV,KAAK,6BAA6B,EAEnC,MAAM,YAAY,CAAC;AAKpB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAI1D,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE3F;;;;;;;;;;;GAWG;AAEH,qBAAa,cAAc;;aAsEG,IAAI,EAAE,IAAI;IA/DtC;;;OAGG;IACH,OAAO,CAAC,cAAc,CAAiB;IAEvC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,uBAA8B;IAEnD;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAyE;IAE/G;;;;;;OAMG;IACH,IAAI,cAAc,sCAEjB;IAED;;;;;;;;OAQG;IACH,IAAI,cAAc,sCAEjB;IAED;;;;;;;OAOG;gBACyB,IAAI,EAAE,IAAI;IAItC;;;;;;;;;;;OAWG;IACH,IAAI;IAwEJ;;;;;;OAMG;IACH,OAAO;IAaP;;;;;;OAMG;IACH,iBAAiB;IAMjB;;;;OAIG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,OAAO,UAAU,CAAC,CAAC;IAIrG;;;OAGG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;;;;;;;;;;;;;;;;OAiBG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IA6ElG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBnG;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,eAAe;IAI7E;;;;;;;;;OASG;IACG,aAAa,CAAC,CAAC,SAAS,UAAU,EACtC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAI3B;;;;;;;;OAQG;IACG,oBAAoB;;;;;IAI1B;;;;;;;;OAQG;IACG,qBAAqB;;;;;IAI3B;;;;;;;;;;;OAWG;IACG,gBAAgB;CA0HvB"}

package/dist/create-branch.d.ts

@@ -0,0 +1,35 @@
+import { LocalRxDBChangeRepository, RxDBBranch, RxDBChange } 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 declare const create_branch: (version: VersionManager, branchId: string, fromChangeId?: number) => Promise<RxDBBranch>;
+/**
+ * 获取分支最新一笔可作为分叉点的变更记录
+ *
+ * @param changeRepository - 变更仓库。由调用方决定它属于哪个事务 ——
+ * `create_branch` 传的是事务内的那一份，不能在这里自己去 `getLocalRepositories()`。
+ * @param currentBranchId - 分支 ID；不传则按「当前激活分支」查
+ *
+ * 独立导出而非内联，是为了被 `__tests__/version/create-branch.spec.ts` 单独测试。
+ */
+export declare const get_current_branch_last_change: (changeRepository: LocalRxDBChangeRepository, currentBranchId?: string) => Promise<RxDBChange>;
+//# sourceMappingURL=create-branch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-branch.d.ts","sourceRoot":"","sources":["../src/create-branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,yBAAyB,EAE9B,UAAU,EACV,UAAU,EAEX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,GAAU,SAAS,cAAc,EAAE,UAAU,MAAM,EAAE,eAAe,MAAM,wBA+GnG,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,GACzC,kBAAkB,yBAAyB,EAC3C,kBAAkB,MAAM,wBAqBzB,CAAC"}

package/dist/detached-event-error.d.ts

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

package/dist/detached-event-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detached-event-error.d.ts","sourceRoot":"","sources":["../src/detached-event-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oCAAoC,GAAI,OAAO,OAAO,KAAG,OAarE,CAAC"}

package/dist/find-switch-branch-step.d.ts

@@ -0,0 +1,94 @@
+import { RxDBBranch } 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;
+}
+/**
+ * 沿 `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 declare const find_branch_path_to_root: (branch: RxDBBranch, branchMap: ReadonlyMap<string, RxDBBranch>) => RxDBBranch[];
+/**
+ * 算出树上两个节点之间的切换路径
+ *
+ * @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 declare const find_switch_branch_step: (options: FindBranchPathOptions) => SwitchBranchStep[];
+//# sourceMappingURL=find-switch-branch-step.d.ts.map

package/dist/find-switch-branch-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-switch-branch-step.d.ts","sourceRoot":"","sources":["../src/find-switch-branch-step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AACnD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;OAEG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;IAEvB;;OAEG;IACH,aAAa,EAAE,UAAU,CAAC;IAE1B;;OAEG;IACH,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,UAAU,EAAE,UAAU,CAAC;IAEvB;;OAEG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,UAAU,EAClB,WAAW,WAAW,CAAC,MAAM,EAAE,UAAU,CAAC,KACzC,UAAU,EAqBZ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,qBAAqB,KAAG,gBAAgB,EA6KxF,CAAC"}