@aiao/rxdb-plugin-sync 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,82 @@
-# Temporary Holding Version
+# @aiao/rxdb-plugin-sync
 
-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.syncManager` 才存在。
+
+核心 `@aiao/rxdb` 保留的是**原语**：`RxDBSync` 水位表、变更编解码、冲突模型（`ConflictResolution` / `RxDBConflictError`）与同步资格判定。搬进本包的是**消费者**：整库与单仓库两个粒度的 push / pull / sync、冲突落地、依赖拓扑序、过期清理与 QueryCache 出站队列。
+
+## 安装
+
+```bash
+pnpm add @aiao/rxdb @aiao/rxdb-plugin-history @aiao/rxdb-plugin-sync
+```
+
+`@aiao/rxdb-plugin-history` 不是可选的：本包声明 `inject: ['plugin:history']`。
+
+## 使用
+
+```typescript
+import { RxDB, SyncType } from '@aiao/rxdb';
+import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+import { rxDBPluginSync } from '@aiao/rxdb-plugin-sync';
+
+const rxdb = new RxDB({
+  dbName: 'notes',
+  entities: [Note],
+  sync: { type: SyncType.Full, local: { adapter: 'wa-sqlite' }, remote: { adapter: 'supabase' } }
+});
+
+// 传工厂函数本身，不要调用它；两句 use() 的先后随意——宿主按 inject 拓扑排序
+rxdb.use(rxDBPluginHistory).use(rxDBPluginSync).adapter('wa-sqlite' /* … */);
+
+await rxdb.connect('wa-sqlite');
+
+await rxdb.syncManager.sync();
+await rxdb.syncManager.pushRepository('public', 'note');
+```
+
+`use()` 必须早于 `connect()`——`connect()` 内部就会调 `init()`。
+
+`connect()` 返回之前本包的 `install()` 一定跑完，这一点比没有 `inject` 的插件更值得留意：声明了依赖的插件**不在** `init()` 里安装，它要等历史插件装好、状态转 `active`，宿主再对齐一趟才轮到它。`rxdb.init()` 之后紧接着读 `rxdb.syncManager` 会读到 `undefined`，那不是缺陷而是时序——`connect()` 是这条链的静止点。
+
+## 主要能力
+
+| 分组     | 入口                                                                                          |
+| -------- | --------------------------------------------------------------------------------------------- |
+| 推拉     | `push()` / `pull()` / `sync()` / `pushRepository()` / `pullRepository()` / `syncRepository()` |
+| 批量     | `bulkSync()` / `getRepositoryDependencyGraph()` / `getRepositorySyncOrder()`                  |
+| 仓储状态 | `getRepositorySyncStatus()` / `getAllRepositorySyncStatus()` / `checkRepositoryUpdates()`     |
+| 分支     | `syncBranches()`                                                                              |
+| 计数     | `refreshPullableCount()`                                                                      |
+| 清理     | `cleanupExpired()`                                                                            |
+
+水位线是 `RxDBSync.lastPushedChangeId`，push 与 QueryCache 出站共用同一条——两者都在把本地变更送去远端，各记一条水位会让「已推到哪」在同一张表上有两个答案。
+
+## 与历史插件的关系
+
+单向：本包 `inject: ['plugin:history']`，历史包不认识本包。耦合只走一张窄接口（`SyncHistoryBridge`）——一次往返结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人在历史侧。
+
+两件事的生命周期本就不同，所以它们各自成包：撤销重做要在第一条 `rxdb_change` 之前就位（历史插件因此**不**声明任何 `inject`），推拉同步则只在配了远端时才有意义。
+
+## 与 QueryCache 插件的关系
+
+只有 `import type { QueryCacheRemoteAdapter }`，**不产生** `inject` 运行期依赖。装了本包、没装 `@aiao/rxdb-plugin-querycache` 且没有 QueryCache 实体的工作区照常运行。
+
+## 没装插件时
+
+`rxdb.syncManager` **不存在**（读到 `undefined`），核心不给一个什么都不做的空壳。
+
+只装了本包、忘了装历史插件时，本包停在 `waiting` 永远装不上——依赖来源尘埃落定后宿主会点名一次：
+
+```
+[RxDB] Plugin 'sync' is not installed: unsatisfied dependencies [plugin:history]
+```
+
+`syncState` 面板上的待拉数由本包维护：远端适配器在实时订阅恢复后发 `syncState.requestPullableRefresh()`，本包接住它并调 `refreshPullableCount()`。没装本包，那个读数就是无人维护——这正是实情，不是零。
+
+## 连接纪元
+
+插件声明 `lifecycle: 'scoped'`，三处宿主改动全部登记在 `install(scope)` 收到的作用域上，`disconnectAll()` 时逆序释放，宿主不调用 `destroy()`：`SyncManager` 实例本身（`destroy()` 随它撤掉 `connected$` 自动回推订阅与远端事件监听）、`rxdb.syncManager` 槽位、`syncState.bindPullableRefresh()` 跳板。释放走逆拓扑序，本包先于历史插件撤销。
+
+重新 `connect()` 装的是一个全新的管理器，而不是复活上一纪元那个——后者指向的事件总线已经拆了。

package/dist/SyncManager.d.ts

@@ -0,0 +1,426 @@
+import { PullOptions, PullResult, PushOptions, PushResult, RxDB, SyncResult } from '@aiao/rxdb';
+import { PushInFlightRegistry, SyncHistoryBridge } from '@aiao/rxdb-plugin-history';
+import { BulkSyncOptions, BulkSyncResult } from './bulk-sync.js';
+import { CheckRepositoryUpdatesResult } from './check-repository-updates.js';
+import { CleanupExpiredOptions, CleanupExpiredResult } from './cleanup-expired.js';
+import { DependencyGraph, RepositoryIdentifier } from './dependency-graph.js';
+import { GetAllRepositorySyncStatusFilter } from './get-all-repository-sync-status.js';
+import { RepositorySyncStatus } from './get-repository-sync-status.js';
+import { PullRepositoryOptions, PullRepositoryResult } from './pull-repository.js';
+import { PushRepositoryOptions, PushRepositoryResult } from './push-repository.js';
+import { SyncBranchesResult } from './sync-branches.js';
+import { SyncRepositoryOptions, SyncRepositoryResult } from './sync-repository.js';
+import { SortDirection } from './topological-sort.js';
+/**
+ * 同步管理器
+ *
+ * 负责整库与单仓库两个粒度的推拉同步：
+ * - `pull` / `push` / `sync`：整库
+ * - `pullRepository` / `pushRepository` / `syncRepository` / `bulkSync`：按仓库
+ * - `getRepositorySyncStatus` / `checkRepositoryUpdates` / `cleanupExpired`：状态与清理
+ * - `getRepositoryDependencyGraph` / `getRepositorySyncOrder`：依赖图与同步顺序
+ *
+ * @remarks
+ * US-025 阶段 D 之前这些入口挂在 `@aiao/rxdb-plugin-history` 的 `VersionManager` 上。
+ * 切开的理由是两件事的生命周期本就不同：撤销重做要在第一条 `rxdb_change` 之前就位，
+ * 推拉同步则只在配了远端时才有意义。
+ *
+ * 切开之后仍有一条**单向**耦合：一次同步往返结束时 undo 边界要作废、待拉计数要结算，
+ * 而那些状态的主人是历史侧。它经 {@link SyncHistoryBridge} 这一张窄接口相遇 ——
+ * 本插件 `inject: ['plugin:history']`，历史插件则对本包一无所知。
+ */
+export declare class SyncManager {
+    #private;
+    readonly rxdb: RxDB;
+    readonly history: SyncHistoryBridge;
+    /**
+     * 「哪些变更此刻正在飞往远端」的登记处。
+     *
+     * @remarks
+     * push 与 undo 唯一的会合点，实例的主人在历史侧（`rxdb.versionManager.pushInFlight`）。
+     * 两边读的必须是同一个，见 `PushInFlightRegistry`：push 在远端往返之前认领区间，
+     * undo 把认领区间当成已推 —— 各持一份，往返窗口内的一次撤销就会造成永久分叉。
+     *
+     * @internal
+     */
+    get pushInFlight(): PushInFlightRegistry;
+    /**
+     * 本地分支激活代际：每次分支切换开始与提交各加一。
+     *
+     * @remarks
+     * 推送在规划时记下它，回执提交事务里再比一次。只比分支 id 不够：远端往返期间
+     * main→feature→main 之后 id 又对上了，但 main 的业务投影已经被切走又切回重建过。
+     * 开始与提交都加一，是为了让「规划时恰好撞上一次进行中的切换」也被识别出来。
+     *
+     * 只覆盖本实例内的切换；跨标签页的切换由提交事务里读到的持久化 active 分支兜住
+     * （A→B→A 在跨标签页时不可见，属已知限制）。
+     *
+     * @internal
+     */
+    get branchSwitchGeneration(): number;
+    /**
+     * @param rxdb - 宿主实例
+     * @param history - 历史侧借来的那一小块面，由 `rxdb.versionManager.syncBridge` 提供
+     */
+    constructor(rxdb: RxDB, history: SyncHistoryBridge);
+    /** 装上 connected$ 自动回推与远端事件计数两条链路 */
+    init(): void;
+    /** 拆掉 {@link init} 装上的全部监听与订阅 */
+    destroy(): void;
+    /** 取本地适配器上的系统表仓库 */
+    getLocalRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').LocalRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').LocalRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').LocalRxDBAdapter;
+    }>;
+    /** 取远端适配器上的系统表仓库 */
+    getRemoteRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').RemoteRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').RemoteRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').RemoteRxDBAdapter;
+    }>;
+    /**
+     * 取当前分支；没有激活分支时激活（或新建）`main`。
+     *
+     * @remarks
+     * 同步链路里每条远端事件都要调它（`sync-listeners` 的 `filterByBranch`），
+     * 热路径不开事务，见 `getCurrentBranch`。
+     */
+    getCurrentBranch(): Promise<import('@aiao/rxdb').RxDBBranch>;
+    /**
+     * 从远程同步所有分支信息到本地
+     *
+     * 远程新分支 → 在本地创建（local: false, remote: true）
+     * 本地已有的远程分支 → 更新 remote 标记为 true
+     * 纯本地分支 → 不受影响
+     *
+     * @returns 同步结果
+     *
+     * @example
+     * ```typescript
+     * const result = await rxdb.syncManager.syncBranches();
+     * console.log(`新增 ${result.created}，更新 ${result.updated}`);
+     * ```
+     */
+    syncBranches(): Promise<SyncBranchesResult>;
+    /**
+     * 从远程拉取变更并应用到本地数据库
+     *
+     * 当 autoSync=false 时，会先应用 Realtime 缓存的变更，再拉取远程变更。
+     *
+     * @param options - 可选配置
+     * @returns 拉取结果
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.pull();
+     * console.log(`Pulled ${result.pulled} changes`);
+     *
+     * // 拉取所有数据
+     * const result = await rxdb.syncManager.pull({ fetchAll: true });
+     * ```
+     */
+    pull(options?: PullOptions): Promise<PullResult>;
+    /**
+     * 将本地未同步的变更推送到远程数据库
+     *
+     * 推送时会自动：
+     * 1. 查询 lastPushedChangeId 之后的新变更
+     * 2. 过滤已撤销的变更（revertChangeId != null）
+     * 3. 压缩变更（INSERT→DELETE 丢弃，INSERT→UPDATE* 合并为 INSERT）
+     * 4. 批量推送到远程
+     * 5. 更新 lastPushedChangeId 和 lastPushedAt
+     *
+     * @param options - 可选配置
+     * @returns 推送结果
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.push();
+     * console.log(`Pushed ${result.pushed} changes`);
+     *
+     * // 自定义批量大小
+     * const result = await rxdb.syncManager.push({ batchSize: 500 });
+     * ```
+     */
+    push(options?: PushOptions): Promise<PushResult>;
+    /**
+     * 执行完整的同步操作（先 pull 再 push）
+     *
+     * 推荐在重连后使用此方法，确保：
+     * 1. 先获取远程最新变更（避免覆盖他人数据）
+     * 2. 再推送本地变更
+     *
+     * @param options - 可选配置
+     * @returns 同步结果（包含 pull 和 push 结果）
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.sync();
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     * ```
+     */
+    sync(options?: {
+        pull?: PullOptions;
+        push?: PushOptions;
+    }): Promise<SyncResult>;
+    /**
+     * 拉取指定 Repository 的远程变更
+     *
+     * 提供实体类型级别的精细同步控制，支持级联同步以自动拉取关联实体。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @param options - 拉取选项
+     * @returns 拉取结果
+     *
+     * @example
+     * ```typescript
+     * // 拉取 Todo 并级联拉取依赖
+     * const result = await rxdb.syncManager.pullRepository('public', 'Todo', {
+     *   includeRelated: true // 默认：若 Todo 有外键则自动拉取 User
+     * });
+     *
+     * // 不级联拉取
+     * const result = await rxdb.syncManager.pullRepository('public', 'Todo', {
+     *   includeRelated: false // 仅拉取 Todo，可能引发外键错误
+     * });
+     * ```
+     */
+    pullRepository(namespace: string, entity: string, options?: PullRepositoryOptions): Promise<PullRepositoryResult>;
+    /**
+     * 推送指定 Repository 的本地变更
+     *
+     * 提供实体类型级别的精细同步控制，支持级联同步以自动推送依赖实体。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "User"）
+     * @param options - 推送选项
+     * @returns 推送结果
+     *
+     * @example
+     * ```typescript
+     * // 推送 User 并级联推送依赖方
+     * const result = await rxdb.syncManager.pushRepository('public', 'User', {
+     *   includeRelated: true // 默认：若 Post 引用 User 则自动推送 Post
+     * });
+     *
+     * // 不级联推送
+     * const result = await rxdb.syncManager.pushRepository('public', 'User', {
+     *   includeRelated: false // 仅推送 User，依赖数据可能不完整
+     * });
+     * ```
+     */
+    pushRepository(namespace: string, entity: string, options?: PushRepositoryOptions): Promise<PushRepositoryResult>;
+    /**
+     * 同步指定 Repository（先 pull 再 push）
+     *
+     * 将单个 Repository 的 pull 和 push 合并为一次操作，保证正确的执行顺序。
+     * 推荐在需要确保特定实体类型数据一致性时使用。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @param options - 同步选项（分别配置 pull 和 push）
+     * @returns 同步结果（包含 pull 和 push 结果）
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.syncRepository('public', 'Todo');
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     *
+     * // 自定义 pull 和 push 选项
+     * const result = await rxdb.syncManager.syncRepository('public', 'Todo', {
+     *   pull: { limit: 500, fetchAll: true },
+     *   push: { batchSize: 100 }
+     * });
+     * ```
+     */
+    syncRepository(namespace: string, entity: string, options?: SyncRepositoryOptions): Promise<SyncRepositoryResult>;
+    /**
+     * 清理不再满足过滤条件的本地过期数据
+     *
+     * 用于 SyncType.Filter 场景，删除不满足 filter 条件的本地数据
+     * 例如：清理超过 30 天的订单数据
+     *
+     * @param namespace - 实体命名空间
+     * @param entity - 实体名称
+     * @param options - 清理选项
+     * @returns 清理结果
+     *
+     * @example
+     * ```ts
+     * const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+     * const { removed } = await rxdb.syncManager.cleanupExpired('public', 'Order', {
+     *   filter: {
+     *     combinator: 'and',
+     *     rules: [{ field: 'updatedAt', operator: '>=', value: thirtyDaysAgo }]
+     *   }
+     * });
+     * console.log(`Removed ${removed} expired records`);
+     * ```
+     */
+    cleanupExpired(namespace: string, entity: string, options?: CleanupExpiredOptions): Promise<CleanupExpiredResult>;
+    /**
+     * 检查远程是否有更新，不下载数据
+     *
+     * 仅查询远程有多少新变更，不实际拉取数据。
+     * 适用于显示「有 N 条远程更新」提示，节省带宽和时间。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @returns 更新检查结果
+     *
+     * @example
+     * ```typescript
+     * // 检查 Todo 是否有远程更新
+     * const result = await rxdb.syncManager.checkRepositoryUpdates('public', 'Todo');
+     * if (result.hasUpdates) {
+     *   console.log(`有 ${result.pendingCount} 条更新可拉取`);
+     *   // 用户点击「更新」按钮后再调用 pullRepository()
+     * }
+     * ```
+     */
+    checkRepositoryUpdates(namespace: string, entity: string): Promise<CheckRepositoryUpdatesResult>;
+    /**
+     * 获取单个 Repository 的同步状态
+     *
+     * 返回完整的同步状态信息，包括：
+     * - syncType（full/remote/local/disabled）
+     * - pushableCount（待推送的本地变更数）
+     * - pullableCount（可拉取的远程变更数）
+     * - 最近同步时间戳
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @returns Repository 同步状态
+     *
+     * @example
+     * ```typescript
+     * const status = await rxdb.syncManager.getRepositorySyncStatus('public', 'Todo');
+     * console.log(`同步类型: ${status.syncType}`);
+     * console.log(`待推送: ${status.pushableCount}，可拉取: ${status.pullableCount}`);
+     * ```
+     */
+    getRepositorySyncStatus(namespace: string, entity: string): Promise<RepositorySyncStatus>;
+    /**
+     * 获取所有 Repository 的同步状态
+     *
+     * 返回所有已注册实体的状态，支持可选过滤。
+     *
+     * @param filter - 可选过滤条件
+     * @returns Repository 同步状态数组
+     *
+     * @example
+     * ```typescript
+     * // 获取全部状态
+     * const statuses = await rxdb.syncManager.getAllRepositorySyncStatus();
+     *
+     * // 仅获取有待处理变更的 Repository
+     * const pending = await rxdb.syncManager.getAllRepositorySyncStatus({
+     *   hasPendingChanges: true
+     * });
+     *
+     * // 仅获取已启用的全量同步 Repository
+     * const fullSync = await rxdb.syncManager.getAllRepositorySyncStatus({
+     *   syncType: ['full'],
+     *   enabled: true
+     * });
+     * ```
+     */
+    getAllRepositorySyncStatus(filter?: GetAllRepositorySyncStatusFilter): Promise<RepositorySyncStatus[]>;
+    /**
+     * 按各仓库持久化的远端水位线重新计算待拉变更数
+     *
+     * @returns 当前远端待拉变更总数
+     *
+     * @remarks
+     * 远程适配器在实时订阅恢复后调用。若刷新期间又收到实时事件，保留两者中的较大值，
+     * 避免把查询快照之后到达的通知覆盖掉。
+     */
+    refreshPullableCount(): Promise<number>;
+    /**
+     * 批量同步多个 Repository
+     *
+     * 在单次操作中同步多个 Repository，支持顺序或并发执行。
+     *
+     * @param options - 批量同步选项
+     * @returns 批量同步结果（包含成功/失败计数）
+     *
+     * @example
+     * ```typescript
+     * // 顺序同步所有已启用的 Repository
+     * const result = await rxdb.syncManager.bulkSync();
+     * console.log(`成功: ${result.succeeded}，失败: ${result.failed}`);
+     *
+     * // 同步指定 Repository
+     * const result = await rxdb.syncManager.bulkSync({
+     *   repositories: [
+     *     { namespace: 'public', entity: 'Todo' },
+     *     { namespace: 'public', entity: 'User' }
+     *   ]
+     * });
+     *
+     * // 并发模式仅 pull
+     * const result = await rxdb.syncManager.bulkSync({
+     *   concurrent: true,
+     *   concurrency: 3,
+     *   push: false
+     * });
+     *
+     * // 检查每项结果
+     * for (const item of result.results) {
+     *   if (item.success) {
+     *     console.log(`${item.repository.entity}: 已拉取 ${item.result?.pullResult.pulled ?? 0} 条`);
+     *   } else {
+     *     console.error(`${item.repository.entity}: ${item.error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    bulkSync(options?: BulkSyncOptions): Promise<BulkSyncResult>;
+    /**
+     * 获取所有 Repository 的依赖图
+     *
+     * 分析实体关系（MANY_TO_ONE、ONE_TO_ONE）以构建依赖图，
+     * 展示各 Repository 之间的依赖关系。
+     *
+     * @returns 包含依赖关系的依赖图
+     *
+     * @example
+     * ```typescript
+     * const graph = rxdb.syncManager.getRepositoryDependencyGraph();
+     *
+     * // 遍历依赖关系
+     * for (const [key, dep] of graph) {
+     *   console.log(`${key} 依赖:`, dep.dependsOn);
+     *   console.log(`${key} 被依赖:`, dep.requiredBy);
+     * }
+     * ```
+     */
+    getRepositoryDependencyGraph(): DependencyGraph;
+    /**
+     * 根据依赖关系获取 Repository 的同步顺序
+     *
+     * 通过拓扑排序确定基于依赖关系的正确同步顺序。
+     *
+     * @param direction - 排序方向：'pull'（父节点优先）或 'push'（子节点优先）
+     * @returns 有序的 Repository 列表
+     *
+     * @example
+     * ```typescript
+     * // 获取 pull 顺序（父节点优先）
+     * const pullOrder = rxdb.syncManager.getRepositorySyncOrder('pull');
+     * // [User, Todo, Comment]
+     *
+     * // 获取 push 顺序（子节点优先）
+     * const pushOrder = rxdb.syncManager.getRepositorySyncOrder('push');
+     * // [Comment, Todo, User]
+     * ```
+     */
+    getRepositorySyncOrder(direction: SortDirection): RepositoryIdentifier[];
+}
+//# sourceMappingURL=SyncManager.d.ts.map

package/dist/SyncManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncManager.d.ts","sourceRoot":"","sources":["../src/SyncManager.ts"],"names":[],"mappings":"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"}

package/dist/branch-change-id.d.ts

@@ -0,0 +1,31 @@
+import { IRepository, RxDBChange } from '@aiao/rxdb';
+/** 本模块只依赖 change 仓库的 `find`，用最小接口收窄，便于在事务 executor 上复用。 */
+type ChangeFinder = Pick<IRepository<typeof RxDBChange>, 'find'>;
+/**
+ * 本地分叉点 → 远端 change id。
+ *
+ * @param repository - 本地 `RxDBChange` 仓库
+ * @param localFromChangeId - 本地分支的 `fromChangeId`
+ * @returns 远端 id；分叉点尚未推送（`remoteId` 为空）时返回 `null`
+ * @throws RxDBError 本地压根不存在这条变更 —— 这是分支表与变更表已经不一致，不能猜
+ *
+ * @remarks
+ * 返回 `null` 表示「远端此刻确实不知道这个分叉点」，而不是「分叉点在根」。调用方要据此
+ * 决定是否在实体变更推送完成后重推一次分支，见 {@link pushBranch}。
+ */
+export declare const toRemoteFromChangeId: (repository: ChangeFinder, localFromChangeId: number) => Promise<number | null>;
+/**
+ * 远端分叉点 → 本地 change id。
+ *
+ * @param repository - 本地 `RxDBChange` 仓库（事务内请传 executor 作用域的那一份）
+ * @param remoteFromChangeId - 远端分支行上的 `fromChangeId`
+ * @returns 本地 id；对应的变更尚未拉到本地时返回 `null`
+ *
+ * @remarks
+ * 返回 `null` 时**不可**退化成 `null`/`0` 写进本地分支行：`find-switch-branch-step` 会把它
+ * 当「分叉于根」处理，切换分支时应用的区间从第一条变更起算。调用方应跳过该分支，
+ * 等分叉点变更拉到本地后的下一轮再建。
+ */
+export declare const toLocalFromChangeId: (repository: ChangeFinder, remoteFromChangeId: number) => Promise<number | null>;
+export {};
+//# sourceMappingURL=branch-change-id.d.ts.map

package/dist/branch-change-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-change-id.d.ts","sourceRoot":"","sources":["../src/branch-change-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AACrE,2DAA2D;AAC3D,KAAK,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;AAcjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,YAAY,EACxB,mBAAmB,MAAM,KACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAMvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,YAAY,YAAY,EACxB,oBAAoB,MAAM,KACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAGvB,CAAC"}

package/dist/branch-materialization-source.d.ts

@@ -0,0 +1,22 @@
+import { BranchMaterializationSource } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * 造同步插件的分支物化来源。
+ *
+ * @param sm - 本纪元的同步管理器
+ * @returns 交给 `rxdb.branchMaterializationSource()` 登记的来源
+ *
+ * @remarks
+ * 各成员的调用时机由工作树插件决定，这里只守契约：
+ *
+ * - `freezeIntent` / `pages` 在任何事务之外跑，可以碰远端；
+ * - `resolveIntentDrift` / `projectPage` / `settle` 跑在切换事务里，只用传进来的执行器，
+ *   一次远端都不碰——绑在适配器上的仓库在那里会排在那笔事务自己后面，死锁。
+ *
+ * 投影**不区分**自己推上去的变更与别人的：metadata-only 分支在本地一行数据都没有，
+ * `pull` 跳过自己那份的前提（「本地已经有了」）在这里不成立。
+ *
+ * @internal
+ */
+export declare const createSyncBranchMaterializationSource: (sm: SyncManager) => BranchMaterializationSource;
+//# sourceMappingURL=branch-materialization-source.d.ts.map

package/dist/branch-materialization-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-materialization-source.d.ts","sourceRoot":"","sources":["../src/branch-materialization-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAOL,KAAK,2BAA2B,EAqBjC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAsTpD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,qCAAqC,GAAI,IAAI,WAAW,KAAG,2BA2EvE,CAAC"}

package/dist/branch-utils.d.ts

@@ -0,0 +1,40 @@
+import { EntityStaticType, RxDBBranch } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * 沿 `parentId` 向上走分支链所需的最小仓库能力。
+ *
+ * @remarks
+ * 写成结构化接口，是为了让绑在适配器上的本地仓库与事务执行器给出的仓库都接得住——
+ * 分支物化来源要在切换事务里按同一口径重算血缘，而绑在适配器上的仓库在那里会排在
+ * 那笔事务自己后面，死锁。
+ */
+export interface BranchLineageReader {
+    /**
+     * 按条件查分支
+     *
+     * @param options - 查询选项
+     * @returns 命中的分支行
+     */
+    find(options: EntityStaticType<typeof RxDBBranch, 'findOptions'>): Promise<RxDBBranch[]>;
+}
+/**
+ * 获取当前分支及其所有祖先分支的 ID 列表
+ *
+ * @returns [currentBranch, parent, grandparent, ...] 例如 ['dev', 'main']
+ */
+export declare function getAncestorBranchIds(sm: SyncManager, branchId: string): Promise<string[]>;
+/**
+ * 用给定的分支仓库算 `branchId` 及其全部祖先——{@link getAncestorBranchIds} 的本体。
+ *
+ * @param branchRepository - 见 {@link BranchLineageReader}
+ * @param branchId - 起点分支
+ * @returns [branchId, parent, grandparent, ...]
+ *
+ * @remarks
+ * 拆出来给分支物化来源用：冻结意图时在事务外算一次，屏障里再用执行器的仓库算一次比对，
+ * 两处必须与 pull 同一口径，否则「范围变没变」的判定本身就在漂。
+ *
+ * @internal
+ */
+export declare function ancestorBranchIdsFrom(branchRepository: BranchLineageReader, branchId: string): Promise<string[]>;
+//# sourceMappingURL=branch-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"branch-utils.d.ts","sourceRoot":"","sources":["../src/branch-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAkB,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,OAAO,UAAU,EAAE,aAAa,CAAC,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;CAC1F;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI/F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,gBAAgB,EAAE,mBAAmB,EACrC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,EAAE,CAAC,CAyBnB"}