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

package/src/get-all-repository-sync-status.ts

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview 获取所有仓库的同步状态
+ *
+ * 提供查询所有仓库同步状态的功能，支持按 syncType、启用状态和待处理变更进行过滤。
+ */
+
+import { getEntityMetadata, type RxDB } from '@aiao/rxdb';
+import {
+  getRepositorySyncStatus,
+  type RepositorySyncStatus,
+  type SyncTypeValue
+} from './get-repository-sync-status.js';
+
+/**
+ * getAllRepositorySyncStatus 的过滤选项
+ */
+export interface GetAllRepositorySyncStatusFilter {
+  /**
+   * 按同步类型过滤
+   * 如果提供，则仅返回这些同步类型的仓库
+   */
+  syncType?: SyncTypeValue[];
+
+  /**
+   * 按启用状态过滤
+   * 如果为 true，则仅返回启用的仓库
+   * 如果为 false，则仅返回禁用的仓库
+   * 如果为 undefined，则返回全部
+   */
+  enabled?: boolean;
+
+  /**
+   * 按待处理变更过滤
+   * 如果为 true，则仅返回 pushableCount > 0 或 pullableCount > 0 的仓库
+   * 如果为 false，则仅返回没有待处理变更的仓库
+   * 如果为 undefined，则返回全部
+   */
+  hasPendingChanges?: boolean;
+}
+
+/**
+ * 获取所有仓库的同步状态
+ *
+ * 遍历所有注册实体并查询它们的同步状态，支持按 syncType、启用状态和待处理变更进行过滤。
+ *
+ * @param rxdb - RxDB 实例
+ * @param filter - 可选的过滤条件
+ * @returns 仓库同步状态数组
+ *
+ * @example
+ * ```typescript
+ * // 获取所有仓库状态
+ * const statuses = await getAllRepositorySyncStatus(rxdb);
+ *
+ * // 仅获取启用的仓库
+ * const statuses = await getAllRepositorySyncStatus(rxdb, {
+ *   enabled: true
+ * });
+ *
+ * // 仅获取有待处理变更的仓库
+ * const statuses = await getAllRepositorySyncStatus(rxdb, {
+ *   hasPendingChanges: true
+ * });
+ *
+ * // 仅获取 full/remote 同步类型的仓库
+ * const statuses = await getAllRepositorySyncStatus(rxdb, {
+ *   syncType: ['full', 'remote']
+ * });
+ * ```
+ */
+export async function getAllRepositorySyncStatus(
+  rxdb: RxDB,
+  filter?: GetAllRepositorySyncStatusFilter
+): Promise<RepositorySyncStatus[]> {
+  // 1. 从配置中获取所有实体
+  const entities = rxdb.config.entities;
+  const allStatuses: RepositorySyncStatus[] = [];
+
+  // 2. 查询每个实体的状态
+  for (const EntityClass of entities) {
+    const metadata = getEntityMetadata(EntityClass);
+    const namespace = metadata.namespace;
+    const entity = metadata.name;
+
+    // 获取该实体的状态
+    const status = await getRepositorySyncStatus(rxdb, namespace, entity);
+    allStatuses.push(status);
+  }
+
+  // 3. 应用过滤条件
+  let filteredStatuses = allStatuses;
+
+  // 按 syncType 过滤
+  if (filter?.syncType && filter.syncType.length > 0) {
+    filteredStatuses = filteredStatuses.filter(status => filter.syncType!.includes(status.syncType));
+  }
+
+  // 按 enabled 状态过滤
+  if (filter?.enabled !== undefined) {
+    filteredStatuses = filteredStatuses.filter(status => status.enabled === filter.enabled);
+  }
+
+  // 按 hasPendingChanges 过滤
+  if (filter?.hasPendingChanges !== undefined) {
+    if (filter.hasPendingChanges) {
+      // 仅返回有待处理变更的仓库
+      filteredStatuses = filteredStatuses.filter(status => status.pushableCount > 0 || status.pullableCount > 0);
+    } else {
+      // 仅返回没有待处理变更的仓库
+      filteredStatuses = filteredStatuses.filter(status => status.pushableCount === 0 && status.pullableCount === 0);
+    }
+  }
+
+  return filteredStatuses;
+}

package/src/get-repository-sync-status.ts

@@ -0,0 +1,237 @@
+/**
+ * @fileoverview 获取仓库同步状态
+ *
+ * 提供查询单个仓库同步状态的功能，包含 syncType、pushableCount、pullableCount 以及最后同步时间戳等信息。
+ */
+
+import {
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  isRepositorySyncEnabled,
+  type RepositoryIdentifier,
+  type RxDB,
+  RxDBChange,
+  type RxDBChangeRuleGroup,
+  RxDBSync,
+  type RxDBSyncRuleGroup
+} from '@aiao/rxdb';
+import { checkRepositoryUpdates } from './check-repository-updates.js';
+import type { SyncManager } from './SyncManager.js';
+// 唯一定义收敛到 `VersionManager.interface.ts`。
+export type { RepositoryIdentifier };
+
+/**
+ * 同步类型的取值
+ */
+export type SyncTypeValue = 'full' | 'filter' | 'querycache' | 'remote' | 'local' | 'none';
+
+/**
+ * 仓库同步状态
+ */
+export interface RepositorySyncStatus {
+  /**
+   * 仓库标识
+   */
+  repository: RepositoryIdentifier;
+
+  /**
+   * 分支 ID
+   */
+  branchId: string;
+
+  /**
+   * 同步类型
+   */
+  syncType: SyncTypeValue;
+
+  /**
+   * 是否启用同步
+   */
+  enabled: boolean;
+
+  /**
+   * 最后一次推送的 changeId
+   */
+  lastPushedChangeId: number | null;
+
+  /**
+   * 最后一次推送时间戳
+   */
+  lastPushedAt: Date | null;
+
+  /**
+   * 最后一次拉取时间戳
+   */
+  lastPulledAt: Date | null;
+
+  /**
+   * 最后一次拉取到的远端 changeId
+   */
+  lastPullRemoteChangeId: number | null;
+
+  /**
+   * 待推送的变更数量
+   */
+  pushableCount: number;
+
+  /**
+   * 可供拉取的变更数量
+   */
+  pullableCount: number;
+}
+
+/**
+ * 计算仓库的待推送变更数量
+ *
+ * 逻辑：
+ * - 统计 RxDBChange 记录，满足以下条件：
+ *   1. 属于该实体（entity 字段匹配）
+ *   2. 属于当前分支
+ *   3. 不是远端产生的（remoteId 为 null）
+ *   4. 未被撤销（revertChangeId 为 null）
+ *   5. 比 lastPushedChangeId 新（如果存在）
+ *
+ * @param sm - 调用方持有的同步管理器实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @param branchId - 当前分支 ID
+ * @param lastPushedChangeId - 最后一次推送的 changeId（若未推送则为 null）
+ * @returns 待推送的变更数量
+ */
+async function calculatePushableCount(
+  sm: SyncManager,
+  namespace: string,
+  entity: string,
+  branchId: string,
+  lastPushedChangeId: number | null
+): Promise<number> {
+  const { adapter: localAdapter } = await sm.getLocalRepositories();
+  const changeRepo = localAdapter.getRepository(RxDBChange);
+
+  // 构建查询规则
+  const rules: RxDBChangeRuleGroup['rules'] = [
+    { field: 'namespace', operator: '=', value: namespace },
+    { field: 'entity', operator: '=', value: entity },
+    { field: 'branchId', operator: '=', value: branchId },
+    { field: 'remoteId', operator: '=', value: null },
+    // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+    // 必须和 remoteId = null 一起排除，否则会被当成待推变更计进 pushableCount
+    { field: 'rejectedAt', operator: '=', value: null },
+    { field: 'revertChangeId', operator: '=', value: null }
+  ];
+
+  // 如果存在 lastPushedChangeId，则添加过滤条件
+  if (lastPushedChangeId !== null) {
+    rules.push({ field: 'id', operator: '>', value: lastPushedChangeId });
+  }
+
+  const result = await changeRepo.find({
+    where: {
+      combinator: 'and',
+      rules
+    }
+  });
+
+  return result.length;
+}
+
+/**
+ * 计算仓库可拉取变更的数量
+ *
+ * 使用 checkRepositoryUpdates() 查询远端变更计数，避免下载实际数据。
+ *
+ * @param rxdb - RxDB 实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @returns 可拉取的变更数量
+ */
+async function calculatePullableCount(rxdb: RxDB, namespace: string, entity: string): Promise<number> {
+  const result = await checkRepositoryUpdates(rxdb, namespace, entity);
+  return result.pendingCount;
+}
+
+/**
+ * 获取单个仓库的同步状态
+ *
+ * @param rxdb - RxDB 实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @returns 仓库同步状态
+ *
+ * @example
+ * ```typescript
+ * const status = await getRepositorySyncStatus(rxdb, 'public', 'Todo');
+ * console.log(`Sync type: ${status.syncType}`);
+ * console.log(`Pushable: ${status.pushableCount}, Pullable: ${status.pullableCount}`);
+ * ```
+ */
+export async function getRepositorySyncStatus(
+  rxdb: RxDB,
+  namespace: string,
+  entity: string
+): Promise<RepositorySyncStatus> {
+  // 1. 查找实体类并获取元数据
+  const EntityClass = rxdb.config.entities.find(e => {
+    const meta = getEntityMetadata(e);
+    return meta.namespace === namespace && meta.name === entity;
+  });
+
+  if (!EntityClass) {
+    throw new Error(`Entity not found: ${namespace}.${entity}`);
+  }
+
+  const metadata = getEntityMetadata(EntityClass);
+  const syncType = getSyncType(metadata, rxdb.entitySync);
+  const syncCapability = getSyncCapability(syncType);
+
+  // 2. 获取当前分支
+  // 槽位只解析这一次：`rxdb.syncManager` 由插件作用域挂着，断连即被删除，
+  // 一次查询里反复重解析等于给自己留三个 `undefined` 的窗口。
+  const sm = rxdb.syncManager;
+  const branch = await sm.getCurrentBranch();
+  const branchId = branch.id;
+
+  // 3. 查询 RxDBSync 记录
+  const { adapter: localAdapter } = await sm.getLocalRepositories();
+  const repoSyncRepo = localAdapter.getRepository(RxDBSync);
+  const repoSyncId = `${namespace}:${entity}:${branchId}`;
+
+  const repoSyncWhere: RxDBSyncRuleGroup = {
+    combinator: 'and',
+    rules: [{ field: 'id', operator: '=', value: repoSyncId }]
+  };
+
+  const repoSyncResults = await repoSyncRepo.find({ where: repoSyncWhere, limit: 1 });
+
+  const repoSync = repoSyncResults.length > 0 ? repoSyncResults[0] : null;
+
+  // 4. 计算 pushableCount 和 pullableCount
+  let pushableCount = 0;
+  let pullableCount = 0;
+
+  // 推拉能力取开头那一次解析的结果：中间隔着几个 await，重新解析可能与返回的 syncType 不一致
+  if (syncCapability.push) {
+    pushableCount = await calculatePushableCount(sm, namespace, entity, branchId, repoSync?.lastPushedChangeId ?? null);
+  }
+
+  if (syncCapability.pull) {
+    pullableCount = await calculatePullableCount(rxdb, namespace, entity);
+  }
+
+  // 5. 构建并返回状态
+  return {
+    repository: { namespace, entity },
+    branchId,
+    syncType,
+    // 口径与调度侧同源 —— 两个方向都不可同步的（`none` / `local`）恒为
+    // 关闭；有能力时才由 `RxDBSync.enabled` 说了算（记录还没懒创建 ⇒ 启用）
+    enabled: syncCapability.pull || syncCapability.push ? isRepositorySyncEnabled(repoSync) : false,
+    lastPushedChangeId: repoSync?.lastPushedChangeId ?? null,
+    lastPushedAt: repoSync?.lastPushedAt ?? null,
+    lastPulledAt: repoSync?.lastPulledAt ?? null,
+    lastPullRemoteChangeId: repoSync?.lastPullRemoteChangeId ?? null,
+    pushableCount,
+    pullableCount
+  };
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @packageDocumentation
+ * `@aiao/rxdb-plugin-sync` —— 推拉同步、冲突处理与仓库依赖序。
+ *
+ * @remarks
+ * 核心 `@aiao/rxdb` 只保留**原语**：`RxDBSync` 水位表、变更编解码、冲突模型
+ * （`ConflictResolution` / `RxDBConflictError`）与同步资格判定。搬进本包的是**消费者**：
+ * 整库与单仓库两个粒度的 push / pull / sync、冲突落地、依赖拓扑序、过期清理与出站队列。
+ *
+ * US-025 阶段 D 之前这些入口挂在 `@aiao/rxdb-plugin-history` 的 `VersionManager` 上。
+ * 两件事的生命周期本就不同：撤销重做要在第一条 `rxdb_change` 之前就位，推拉同步则只在
+ * 配了远端时才有意义，所以它们各自成包。
+ *
+ * 本包 `inject: ['plugin:history']`，反向没有依赖——历史包不认识本包。这条单向耦合只走
+ * 一张窄接口：一次往返结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人在历史侧。
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ * import { rxDBPluginSync } from '@aiao/rxdb-plugin-sync';
+ *
+ * rxdb.use(rxDBPluginHistory);
+ * rxdb.use(rxDBPluginSync);
+ * await rxdb.connect();
+ *
+ * await rxdb.syncManager.sync();
+ * ```
+ */
+export * from './plugin.js';
+// `SyncManager.bulkSync()` 的形参与返回值。
+export type { BulkSyncOptions, BulkSyncResult } from './bulk-sync.js';
+// `SyncManager.checkRepositoryUpdates()` 的返回值。函数本身是内部实现。
+export type { CheckRepositoryUpdatesResult } from './check-repository-updates.js';
+// `SyncManager.cleanupExpired()` 的形参与返回值。同名的自由函数是该方法的实现，
+// 全仓只有 `SyncManager.ts:427` 与本包测试相对 import 它——转出去等于多一个能绕开
+// `SyncManager` 自身前置校验的入口。
+export type { CleanupExpiredOptions, CleanupExpiredResult } from './cleanup-expired.js';
+// `SyncManager.getRepositoryDependencyGraph()` 的返回值。图的构建函数是内部实现。
+export type { DependencyGraph } from './dependency-graph.js';
+// `SyncManager.getAllRepositorySyncStatus()` 的可选过滤器。
+export type { GetAllRepositorySyncStatusFilter } from './get-all-repository-sync-status.js';
+// `getRepositorySyncStatus()` 的返回值。
+export type { RepositorySyncStatus } from './get-repository-sync-status.js';
+// QueryCache 出站队列的三个入口（US-025 阶段 D 从核心搬来）。前两个供应用与 DevTools
+// 手动驱动一轮重放 / 读队列长度；`pendingQueryCacheWriteIds` 还兼作核心
+// `QueryCacheOutboxProvider` 的实现，由本包的插件在 `install()` 里登记进宿主。
+export {
+  countQueryCacheOutbox,
+  flushQueryCacheOutbox,
+  pendingQueryCacheWriteIds,
+  type QueryCacheOutboxFailure,
+  type QueryCacheOutboxResult
+} from './query-cache-outbox.js';
+// 同 `cleanup-expired`：只转 `SyncManager.syncBranches()` 的返回值（连同 `skipReasons` 的
+// 元素类型），自由函数收回。
+export type { SyncBranchSkipReason, SyncBranchesResult } from './sync-branches.js';
+// 实例由插件装配，用户不自己 new，因此只转类型不转类。
+export type { SyncManager } from './SyncManager.js';

package/src/plugin.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview RxDB 推拉同步插件
+ * 把 {@link SyncManager} 装进宿主的连接纪元，并接住核心同步状态枢纽的「重算待拉数」请求。
+ *
+ * @module rxdb-plugin-sync
+ */
+
+import { IRxDBPlugin, Plugin, RxDB, RxDBPluginBase } from '@aiao/rxdb';
+import type { LifecycleScope } from '@aiao/utils';
+import { createSyncBranchMaterializationSource } from './branch-materialization-source.js';
+import { pendingQueryCacheWriteIds } from './query-cache-outbox.js';
+import { SyncManager } from './SyncManager.js';
+
+/** 本插件当前不接受任何选项 */
+export type RxDBPluginSyncOptions = object;
+
+/**
+ * 推拉同步 / 冲突 / 仓库依赖序插件。
+ *
+ * @remarks
+ * **声明 `inject: ['plugin:history']`**，且只声明这一条：
+ *
+ * - 要历史插件，是因为一次往返结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人
+ *   在历史侧。{@link SyncManager} 拿的是 `rxdb.versionManager.syncBridge` 这张窄接口，
+ *   没有它连构造都无从谈起。依赖缺失时宿主不装本插件、只告警一次，`rxdb.syncManager`
+ *   这个槽位于是不存在——没有历史就没有同步，这正是实情。
+ * - **不要 `adapter:remote`**：同步入口本身是按调用发起的，装配阶段一条适配器读写都不发；
+ *   而 {@link SyncManager.init} 挂的 `connected$` 自动回推订阅必须在第一次连接就位之前
+ *   就已经订阅上，声明适配器依赖会把安装推到引导链之后，第一次连接的那一跳回推就丢了。
+ *
+ * 六处宿主改动都登记在 `scope` 上，断开连接时由宿主逆序释放：
+ *
+ * 1. `rxdb.syncManager` 这个实例槽位 —— 释放时连同 `destroy()` 一起撤掉，不给下一个纪元
+ *    留一个指向已拆事件总线的管理器；
+ * 2. {@link RxDB.syncState} 上的「重算待拉数」跳板 —— 远端适配器在实时订阅恢复后按
+ *    `syncState.requestPullableRefresh()` 发信号，它不认识 {@link SyncManager}，接住这一跳
+ *    是本插件的活（US-025 阶段 D 之前这条绑定在历史插件上，随 `refreshPullableCount` 一起
+ *    搬过来）。没装插件时那个请求发进空里，正是「待拉数无人维护」的实情。
+ * 3. {@link RxDB.queryCacheOutbox} 这个出站队列槽 —— QueryCache 实体的读引擎要靠它把
+ *    「远端没返回」和「本地离线写过」区分开。这一条**没有**缺席形态：槽空着时核心在
+ *    `connect()` 就抛 `RxDBMissingPluginError`，因为「当空集」等于把每条离线写都当孤儿删掉。
+ * 4. 宿主的 `online` / `offline` 监听 —— `ReachabilityMonitor` 只在有人 `watch()` 时才往
+ *    `globalThis` 上挂，而这两个事件唯一的消费者是本包的同步监听器（`wakeup$` 驱动回推
+ *    重试）。不同步的库不该因为 `new RxDB()` 就永久多一对活过实例的监听器（US-025 D2）。
+ * 5. {@link RxDB.branchMaterializationSource} 这个分支物化来源槽 —— `syncBranches()` 拉下来的
+ *    分支只有元数据，工作树插件第一次切过去之前要按来源交出的分页快照物化。远端是本插件的，
+ *    来源于是也只能由本插件交；槽空着时那次切换稳定抛 `branch_not_materialized`，
+ *    不存在「没装同步也能物化」的形态。槽位至多一个来源，本插件登记即占住。
+ */
+export class RxDBPluginSync extends RxDBPluginBase implements IRxDBPlugin {
+  readonly lifecycle = 'scoped' as const;
+  readonly inject = ['plugin:history'] as const;
+  name: Uncapitalize<string> = 'sync';
+
+  install(scope: LifecycleScope) {
+    // `inject` 已经保证历史插件先装完，`versionManager` 槽位此刻一定在。
+    // 借的是 `syncBridge` 而不是管理器本身：面越窄，两个包越不会在演进中互相拽住。
+    const syncManager = new SyncManager(this.rxdb, this.rxdb.versionManager.syncBridge);
+    scope.acquire(() => () => syncManager.destroy(), 'sync:syncManager');
+
+    scope.acquire(() => {
+      Object.defineProperty(this.rxdb, 'syncManager', {
+        value: syncManager,
+        configurable: true,
+        enumerable: true
+      });
+      return () => void Reflect.deleteProperty(this.rxdb, 'syncManager');
+    }, 'sync:slot');
+
+    // 只登记 `pendingWriteIds` 这一个问题。`flushQueryCacheOutbox` / `countQueryCacheOutbox`
+    // 的调用者（同步监听器、DevTools 面板）都在本包里，核心不必认识它们。
+    // 传 scope：断开连接时这条注册跟着一起撤销，不留一个指向已拆纪元的队列。
+    this.rxdb.queryCacheOutbox(
+      { pendingWriteIds: (namespace, entity) => pendingQueryCacheWriteIds(this.rxdb, namespace, entity) },
+      scope
+    );
+
+    // 传 scope：断开连接时撤销，下一个纪元登记的是指向新 syncManager 的那一个，不撞「至多一个」。
+    this.rxdb.branchMaterializationSource(createSyncBranchMaterializationSource(syncManager), scope);
+
+    // 可达性监听：`watch()` 自己返回撤销函数，正好是 `acquire` 要的 setup 形状。
+    // 引用计数在监视器一侧，所以同一个宿主上多装几个消费者也不会互相摘掉对方的监听。
+    scope.acquire(() => this.rxdb.reachability.watch(), 'sync:reachability');
+
+    syncManager.init();
+
+    // 跳板约定「回调不得抛出」：这里即发即忘，没有调用方接得住错误，也没有位置重试。
+    // 重算失败只说明这一次的读数没刷新，下一次实时恢复还会再请求一次，不该炸掉
+    // 适配器的订阅恢复路径。
+    scope.acquire(
+      () =>
+        this.rxdb.syncState.bindPullableRefresh(() => {
+          void syncManager.refreshPullableCount().catch((error: unknown) => {
+            const message = error instanceof Error ? error.message : String(error);
+            console.warn(`[RxDB Sync] 重算待拉数失败：${message}。`);
+          });
+        }),
+      'sync:pullableRefresh'
+    );
+  }
+}
+
+declare module '@aiao/rxdb' {
+  interface RxDB {
+    /**
+     * 推拉同步子系统。
+     *
+     * @remarks
+     * 由 `@aiao/rxdb-plugin-sync` 在连接纪元内装配。**没装插件（或没装它依赖的
+     * `@aiao/rxdb-plugin-history`）时这个槽位不存在**：读它拿到 `undefined`，
+     * 而不是一个什么都不做的空壳——核心不做 fallback 兜底。
+     */
+    syncManager: SyncManager;
+  }
+}
+
+/**
+ * 同步插件工厂。
+ *
+ * @param db - 宿主实例
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ * import { rxDBPluginSync } from '@aiao/rxdb-plugin-sync';
+ *
+ * // 顺序随意：宿主按 `inject` 拓扑排序，历史插件一定先装完。
+ * rxdb.use(rxDBPluginSync);
+ * rxdb.use(rxDBPluginHistory);
+ * ```
+ */
+export const rxDBPluginSync: Plugin<RxDBPluginSyncOptions> = (db: RxDB) => new RxDBPluginSync(db);

package/src/pull-ancestor-changes.ts

@@ -0,0 +1,61 @@
+import { type RemoteChange, type RuleGroup, type RxDBAdapterRemoteBase } from '@aiao/rxdb';
+/**
+ * 一个仓库跨祖先分支拉取变更所需的全部参数。
+ */
+export interface AncestorPullRequest {
+  /** 仓库命名空间 */
+  namespace: string;
+
+  /** 实体名 */
+  entity: string;
+
+  /** 水位线：只拉 id 大于它的变更 */
+  sinceId: number;
+
+  /** 本轮最多消费多少条 */
+  limit: number;
+
+  /** 行级过滤条件，`SyncType.Filter` 用；批量路径不支持，故为可选 */
+  filter?: RuleGroup;
+}
+
+/**
+ * 跨祖先分支拉取**单个仓库**的远端变更，合并成一条按 id 递增、长度不超过 `limit` 的序列。
+ *
+ * @param remoteAdapter - 远端适配器
+ * @param request - 仓库标识、水位线、批量大小与可选行级过滤
+ * @param branchIds - 当前分支及其全部祖先，见 `getAncestorBranchIds`
+ * @returns 合并、排序、截断后的变更序列
+ *
+ * @remarks
+ * **为什么必须逐祖先分支拉。** 分支是 patch 模型，不是快照模型：建分支时只写
+ * `parentId` + `fromChangeId`，一条变更都不复制。所以 feature 分支上可见的数据 =
+ * 父分支在分叉点之前的变更 + feature 自己的变更，而父分支那些记录**物理上仍然
+ * 归属 `branchId='main'`**。`pullChanges` 的 `branchId` 是精确匹配（见其接口契约），
+ * 只传当前分支就永远收不到别人推到 main 的更新 —— 且不会自愈：切回 main 时水位线
+ * 换成了 `${ns}:${entity}:main` 这条**另一个**记录，那段区间从此跳过。
+ *
+ * **为什么合并后必须全局排序再截断。** 每个分支各自取满 `limit` 条，直接拼接会让
+ * 某个分支的高 id 把共享水位线推过另一个分支尚未消费的低 id；那些变更此后都不再满足
+ * `id > lastPullRemoteChangeId`，被永久跳过。排序后只消费前 `limit` 条，其余留给下一轮 ——
+ * 调用方据 `length >= limit` 置 `hasMore` 继续循环。
+ *
+ * 单分支（在 main 上）时只发一次请求，与逐祖先的写法结果一致，不额外分支判断。
+ */
+export async function pullAncestorBranchChanges(
+  remoteAdapter: RxDBAdapterRemoteBase,
+  request: AncestorPullRequest,
+  branchIds: readonly string[]
+): Promise<RemoteChange[]> {
+  const { namespace, entity, sinceId, limit, filter } = request;
+  const repositoryFilter = [`${namespace}:${entity}`];
+
+  const perBranch = await Promise.all(
+    branchIds.map(branchId => remoteAdapter.pullChanges(sinceId, limit, repositoryFilter, filter, branchId))
+  );
+
+  return perBranch
+    .flat()
+    .sort((left, right) => left.id - right.id)
+    .slice(0, limit);
+}