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

package/src/sync-branches.ts

@@ -0,0 +1,276 @@
+import {
+  assertUsableBranchId,
+  InvalidBranchIdError,
+  RxDBBranch,
+  RxDBChange,
+  RxDBError,
+  type IRepository
+} from '@aiao/rxdb';
+import { toLocalFromChangeId } from './branch-change-id.js';
+import type { SyncManager } from './SyncManager.js';
+
+/**
+ * {@link SyncManager.syncBranches} 一轮的结果。
+ *
+ * @remarks
+ * `created + updated + skipped.length` 不一定等于 `total`：本地已有、且早已标了 `remote` 的
+ * 分支既不计 `updated`，也不进 `skipped`。
+ */
+export interface SyncBranchesResult {
+  /** 本轮在本地新建的远端分支数。 */
+  created: number;
+  /** 本地已有、本轮补上 `remote: true` 标记的分支数。 */
+  updated: number;
+  /** 远端本轮交回的分支总数，含被跳过的。 */
+  total: number;
+
+  /**
+   * 本轮**未创建**的远端分支 id —— 具体原因见同一个 id 在 {@link skipReasons} 里的条目。
+   *
+   * 一条分支被跳过，可能是它自己的问题（id 不可用、或分叉点变更还没拉到本地翻译不出本地
+   * id），也可能单纯因为它的父本轮被跳过——后一种情形下这条分支自身完全合格，但父本轮
+   * 不会落库，若仍然照常创建，它的 `parentId` 就是一条指向「本轮不存在的父」的悬空外键
+   * （`rxdb_branch.parentId` 是 `PRAGMA defer_foreign_keys` 延迟到 COMMIT 才检查的外键，
+   * 届时会回滚整个事务，连同本轮所有本该成功的分支）。三种成因统一走同一条 `skipped`
+   * 通道，因为对调用方而言处理方式是一样的：这个 id 本轮没有对应的本地分支，仅此而已。
+   *
+   * **跳过不留持久标记**：每轮都全量重拉远端分支、从头再判一遍，`skipped` 与
+   * {@link skipReasons} 只报这一轮。`unresolved-from-change-id` 在分叉点变更拉到本地后自愈，
+   * 挂在它下面的 `ancestor-skipped` 随之自愈；`invalid-id` 则远端不改就每轮重拉、重跳，
+   * 一直占位——调用方要区分这两类，看 {@link skipReasons}。要不要记一个持久的「已知坏行」
+   * 标记，登记在 `requirements/roadmap.md`「epic-006 评审顺延的架构项」。
+   */
+  skipped: string[];
+
+  /**
+   * `skipped` 里每一个 id 对应的具体跳过原因；key 覆盖 `skipped` 的每一项，一一对应。
+   *
+   * 单开一个字段而不是把原因塞进 `skipped` 数组本身：`skipped: string[]` 这个形状已经被
+   * 外部当「id 列表」消费，改成对象数组是破坏性变更；`Record<id, reason>` 是纯增量，
+   * 只读 `skipped` 的既有调用方不受影响。
+   */
+  skipReasons: Record<string, SyncBranchSkipReason>;
+}
+
+/**
+ * 一条远端分支本轮被跳过的具体原因。
+ *
+ * @remarks
+ * 三种成因互斥——处理顺序保证每条被跳过的分支只会落进其中一种：
+ * - `invalid-id`：分支自己的 id 落不进本地 `rxdb_branch.id`（见 {@link isUsableBranchId}）。
+ * - `unresolved-from-change-id`：分叉点变更还没拉到本地，`fromChangeId` 翻译不出本地 id。
+ * - `ancestor-skipped`：分支自身没有问题，但它的**直接父**本轮已经被跳过（不管父是因为
+ *   哪一种成因被跳的）。`ancestorId` 记的是那个直接父的 id，不是链路最顶端的根因——
+ *   要追根因，沿 `skipReasons[ancestorId]` 递归上溯，直到查到的原因不再是
+ *   `ancestor-skipped` 为止。
+ */
+export type SyncBranchSkipReason =
+  | { readonly cause: 'invalid-id' }
+  | { readonly cause: 'unresolved-from-change-id' }
+  | { readonly cause: 'ancestor-skipped'; readonly ancestorId: string };
+
+/** `pullBranches()` 交回来的形状里，本函数只依赖这三个字段。 */
+interface RemoteBranchRow {
+  id: string;
+  parentId?: string | null;
+}
+
+/**
+ * 远端分支 id 能否落进本地 `rxdb_branch.id`。
+ *
+ * @remarks
+ * 判定口径**只有**核心 {@link assertUsableBranchId} 一份——这里把它的抛错翻成布尔，
+ * 不是第二份规则。各写一遍的话，核心哪天多禁一个字符，同步这条导入路径会静默放行。
+ *
+ * 只吞 {@link InvalidBranchIdError}：别的异常说明校验自身坏了，那不是「这条远端行不合格」，
+ * 不该被记成一次 `skipped`。
+ */
+function isUsableBranchId(branchId: string): boolean {
+  try {
+    assertUsableBranchId(branchId);
+    return true;
+  } catch (error) {
+    if (error instanceof InvalidBranchIdError) return false;
+    throw error;
+  }
+}
+
+/**
+ * 把远端分支按「父在前」重排。
+ *
+ * `rxdb_branch.parentId` 是指向自己的外键，逐条落库时父必须先在库里。而 `pullBranches()`
+ * 返回的数组**没有顺序保证** —— 远端按 `updatedAt`、按主键、按它高兴的任何顺序返回都合法，
+ * 分页更是会把父子切到不同批次。所以顺序必须由本地重建，不能指望远端。
+ *
+ * 判定一个分支「可落库」的依据是它的父是否已经就绪：要么父本来就在本地，要么父在本批里
+ * 且已排到它前面。反复扫描直到某一轮一条都排不出去 —— 剩下的就是父确实找不到
+ * （远端删了父 / 父被分页切走）或互相成环，两者都无法安全落库。
+ *
+ * @param remoteBranches - 远端原样交回的分支数组，顺序不可信
+ * @param localIds - 已在本地的分支 id，它们可以充当父
+ * @returns 父一定排在子前面的新数组
+ * @throws RxDBError 存在父分支缺失或互相成环的记录时。整批放弃优于留下孤儿：
+ * 孤儿会被切分支时的「父节点缺失即当作到根」静默吞掉，损坏无声。
+ */
+function sortBranchesParentFirst<T extends RemoteBranchRow>(remoteBranches: T[], localIds: Set<string>): T[] {
+  const resolved = new Set(localIds);
+  // 本批自己带来的 id：用来把「父确实缺失」和「父只是还排在后面」区分开，好让报错说人话。
+  const incoming = new Set(remoteBranches.map(branch => branch.id));
+  const sorted: T[] = [];
+  let pending = remoteBranches;
+
+  while (pending.length > 0) {
+    const ready = pending.filter(branch => {
+      const parentId = branch.parentId ?? null;
+      return parentId === null || resolved.has(parentId);
+    });
+    if (ready.length === 0) break;
+    for (const branch of ready) {
+      sorted.push(branch);
+      resolved.add(branch.id);
+    }
+    pending = pending.filter(branch => !resolved.has(branch.id));
+  }
+
+  if (pending.length > 0) {
+    const detail = pending
+      .map(branch => {
+        const parentId = branch.parentId ?? null;
+        // 父在本批里却始终排不出去 = 成环；否则就是父压根不存在。
+        const reason = parentId !== null && incoming.has(parentId) ? 'cycle' : 'missing parent';
+        return `'${branch.id}' -> '${String(parentId)}' (${reason})`;
+      })
+      .join(', ');
+    throw new RxDBError(`syncBranches: 远端分支拓扑无法解析，整批放弃：${detail}`);
+  }
+
+  return sorted;
+}
+
+/**
+ * 从远程拉取所有分支信息并同步到本地
+ *
+ * 规则：
+ * 1. 远程新分支 → 在本地创建（local: false, remote: true）
+ * 2. 本地已有的远程分支 → 更新 remote 标记为 true
+ * 3. 纯本地分支（remote=false）→ 不受影响
+ *
+ * @remarks
+ * 读本地、排序、落库全部在**同一个事务窗口**内完成：
+ *
+ * - 无事务时中途失败会留下半批已提交的分支，下次重试撞主键，同步就此永久卡死；
+ * - 读若在事务外做，快照与写之间存在窗口，并发建分支会让「本地已有」的判断过时，
+ *   重复 create 同样撞主键。
+ *
+ * 事务体内只能用 `executor` 作用域的仓库。绑在适配器上的那一份走并发度 1 的写队列，
+ * 在事务体内调用会排到自己这个事务后面 —— 直接死锁。
+ */
+export async function syncBranches(sm: SyncManager): Promise<SyncBranchesResult> {
+  const { adapter: remoteAdapter } = await sm.getRemoteRepositories();
+
+  if (!remoteAdapter.pullBranches) {
+    return { created: 0, updated: 0, total: 0, skipped: [], skipReasons: {} };
+  }
+
+  const remoteBranches = await remoteAdapter.pullBranches();
+  if (remoteBranches.length === 0) {
+    return { created: 0, updated: 0, total: 0, skipped: [], skipReasons: {} };
+  }
+
+  const { adapter } = await sm.getLocalRepositories();
+
+  return adapter.transaction(async executor => {
+    const branchRepository = executor.getRepository(RxDBBranch) as unknown as IRepository<typeof RxDBBranch>;
+    const changeRepository = executor.getRepository(RxDBChange) as unknown as IRepository<typeof RxDBChange>;
+
+    const localBranches = await branchRepository.find({
+      where: { combinator: 'and', rules: [] }
+    });
+    const localMap = new Map(localBranches.map(b => [b.id, b]));
+
+    let created = 0;
+    let updated = 0;
+    const skipped: string[] = [];
+    // 本轮已跳过的分支 id → 跳过原因。级联判断（下面对 `remoteParentId` 的检查）只能靠它，
+    // 不能靠 `localMap`——`localMap` 是本轮开始前的快照，而分支已经按父优先的拓扑序处理
+    // （`sortBranchesParentFirst`），父的跳过决定必然先于子被记录进这个集合。
+    //
+    // 用 Map 记、返回时才经 `Object.fromEntries` 转成对象：键是远端给的分支 id，`__proto__`
+    // 过得了 id 校验。对象字面量逐键赋值会命中 `Object.prototype.__proto__` 的 setter，
+    // 改写返回对象的原型而不是添一个键；`Object.fromEntries` 建的是自有数据属性，不走 setter。
+    const skippedThisRound = new Map<string, SyncBranchSkipReason>();
+
+    /**
+     * 记一次跳过：本函数三处跳过点（id 不可用 / 分叉点翻译不出 / 祖先已跳过）共用同一套
+     * 记账。不分渠道是有意为之——不管一条分支这一轮为什么建不出来，它的后代都同样不能
+     * 创建，记账收敛成一个函数，下面对 `skippedThisRound` 的级联检查才能对三种成因
+     * 一次性生效，不用每加一种跳过原因就多写一遍级联判断。
+     */
+    const recordSkip = (branchId: string, reason: SyncBranchSkipReason): void => {
+      skipped.push(branchId);
+      skippedThisRound.set(branchId, reason);
+    };
+
+    for (const remote of sortBranchesParentFirst(remoteBranches, new Set(localMap.keys()))) {
+      // 子分支连带跳过必须最先判断：父本轮不会落库，子无论自身是否「合格」都不能创建——
+      // 创建了就是一条指向「本轮不存在的父」的悬空外键，真实落库会在 COMMIT 时被
+      // `PRAGMA defer_foreign_keys` 卡住，回滚整个事务（连同本轮所有本该成功的分支）。
+      // 父是因为 id 不可用被跳的、还是分叉点翻译不出被跳的、还是它自己的父被跳的，
+      // 这里都不关心——`skippedThisRound` 不区分渠道，只认「本轮是否已经决定跳过」。
+      const remoteParentId = remote.parentId ?? null;
+      if (remoteParentId !== null && skippedThisRound.has(remoteParentId)) {
+        recordSkip(remote.id, { cause: 'ancestor-skipped', ancestorId: remoteParentId });
+        continue;
+      }
+
+      // 远端分支行是外来数据，它的 id 没走过本地那条创建路径。不校验就直接落库，
+      // 一条叫 `*active*` 的远端分支会与 active 哨兵同形（`system/active-branch-guard.ts`）。
+      //
+      // 跳过而不是整批放弃：`skipped` 这条通道本来就是为「这一行本轮落不了库，别的行照常」
+      // 准备的。整批抛错会让一条坏的远端行把整个同步卡死，而本地这边一点办法都没有。
+      if (!isUsableBranchId(remote.id)) {
+        recordSkip(remote.id, { cause: 'invalid-id' });
+        continue;
+      }
+
+      const local = localMap.get(remote.id);
+      if (local) {
+        if (!local.remote) {
+          await branchRepository.update(local, { remote: true, updatedAt: new Date() });
+          updated++;
+        }
+        continue;
+      }
+
+      // 远端 change id 必须翻译成本地 id 才能写进本地分支行
+      const remoteFromChangeId = remote.fromChangeId ?? null;
+      const fromChangeId =
+        remoteFromChangeId === null ? null : await toLocalFromChangeId(changeRepository, remoteFromChangeId);
+      if (remoteFromChangeId !== null && fromChangeId === null) {
+        recordSkip(remote.id, { cause: 'unresolved-from-change-id' });
+        continue;
+      }
+
+      await branchRepository.create({
+        id: remote.id,
+        activated: false,
+        // 显式写 NULL 而不是留空：两列必须同进同出（`system/branch.ts`）。
+        // 留空在两个后端上**眼下**也落成 NULL，但那是默认值的巧合，不是这一行的意图。
+        activeKey: null,
+        local: false,
+        remote: true,
+        fromChangeId,
+        parentId: remote.parentId ?? null
+      } as InstanceType<typeof RxDBBranch>);
+      created++;
+    }
+
+    return {
+      created,
+      updated,
+      total: remoteBranches.length,
+      skipped,
+      skipReasons: Object.fromEntries(skippedThisRound)
+    };
+  });
+}

package/src/sync-listeners.ts

@@ -0,0 +1,309 @@
+import {
+  ENTITY_REMOTE_CREATE_EVENT,
+  ENTITY_REMOTE_REMOVE_EVENT,
+  ENTITY_REMOTE_UPDATE_EVENT,
+  EntityRemoteCreatedEvent,
+  EntityRemoteRemovedEvent,
+  EntityRemoteUpdatedEvent,
+  type EntityType,
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  isSystemEntity,
+  type RepositoryIdentifier,
+  type SyncStateHub
+} from '@aiao/rxdb';
+import { isIgnorableDetachedVersionEventError } from '@aiao/rxdb-plugin-history';
+import { combineLatest, merge, type Observable, Subscription } from 'rxjs';
+import { distinctUntilChanged, exhaustMap, filter, map, withLatestFrom } from 'rxjs/operators';
+import { countQueryCacheOutbox, flushQueryCacheOutbox } from './query-cache-outbox.js';
+import type { SyncManager } from './SyncManager.js';
+
+/**
+ * 远程实体事件类型集合（CREATE/UPDATE/REMOVE）
+ */
+type RemoteEntityEvent = EntityRemoteCreatedEvent | EntityRemoteUpdatedEvent | EntityRemoteRemovedEvent;
+
+/**
+ * 跑一步回推动作，把失败报给面板后吞掉
+ *
+ * @param syncState - 失败的去处
+ * @param task - 这一步；返回值是这一步**自己**判定的成功与否（见 {@link flushRepository}）
+ * @returns 这一步是否成功——异常通道与 `task` 自报的 `false` 都算失败
+ *
+ * @remarks
+ * 一轮里的各个仓库互不背书：一个仓库的出站队列重放不上，不代表别的仓库那条 REST 路
+ * 也走不通。任何一步的失败都只影响它自己，剩下的照跑。
+ *
+ * 吞错也是为了不掐断订阅 —— rxjs 里一个逃逸到流上的异常会终结整条链，此后再恢复
+ * 多少次网络都不会再有回推。真正的重试节奏交给
+ * {@link ReachabilityMonitor.wakeup$} 的退避。吞掉不等于藏起来：错误进
+ * {@link SyncStateHub.reportError}，用户在面板上看得见。
+ *
+ * **只兜异常通道**：`flushQueryCacheOutbox` 对结构化失败（REST 403、网络错误）从不
+ * `reject`，失败躺在返回值的 `failures` 数组里（RV-052）。这里只负责「`task` 真的
+ * 抛了」这一种失败；`task` 自己上报 `syncState.reportError` 并返回 `false` 的那种
+ * 失败，原样作为返回值传上去，不重复上报。
+ */
+async function runQuietly(syncState: SyncStateHub, task: () => Promise<boolean>): Promise<boolean> {
+  try {
+    return await task();
+  } catch (error) {
+    syncState.reportError(error);
+    return false;
+  }
+}
+
+/**
+ * 接入方声明的实体，即摘掉系统表之后的 `config.entities`
+ *
+ * @remarks
+ * 分派问的是「**用户的**数据该往哪走」，而 `config.entities` 里还混着
+ * {@link SchemaManager.init} 补进来的四张系统表。它们不带自己的 `sync`，于是跟随库级配置 ——
+ * 库级两端俱全时 {@link getSyncType} 会把它们判成 `full`，四张本地簿记表就这么被卷进
+ * 用户数据的分派里。系统表自己的同步由 {@link SyncManager} 直接安排，从不经过这里。
+ */
+function consumerEntities(sm: SyncManager): EntityType[] {
+  return sm.rxdb.config.entities.filter(EntityClass => !isSystemEntity(EntityClass));
+}
+
+/**
+ * 枚举需要走 REST 重放的仓库
+ *
+ * @remarks
+ * 判据是 `offlineWrite && !push`，也就是「能在离线时接受本地写，但没有 changelog 端点」——
+ * 现阶段只有 `querycache`。带 `push` 能力的仓库不在这里：它们由用户显式调
+ * {@link SyncManager.push}，那条路自己按能力矩阵筛。
+ *
+ * 不在这里查 `RxDBSync.enabled`：那要为每个仓库读一次库，而
+ * {@link flushQueryCacheOutbox} 入口本来就会判并返回 `skipped`。判两遍等于把同一个口径
+ * 抄成两份。
+ */
+function queryCacheRepositories(sm: SyncManager): RepositoryIdentifier[] {
+  const repositories: RepositoryIdentifier[] = [];
+
+  for (const EntityClass of consumerEntities(sm)) {
+    const metadata = getEntityMetadata(EntityClass);
+    const capability = getSyncCapability(getSyncType(metadata, sm.rxdb.entitySync));
+    if (capability.offlineWrite && !capability.push) {
+      repositories.push({ namespace: metadata.namespace, entity: metadata.name });
+    }
+  }
+
+  return repositories;
+}
+
+/**
+ * 重放一个 QueryCache 仓库，把判负的实体和结构化失败都报给面板
+ *
+ * @returns 本仓库这一轮是否**真的**成功——`failures` 非空也算失败，即便没有任何异常抛出
+ *
+ * @remarks
+ * `conflicts`（解析器判 `KEEP_REMOTE`）进面板是用户离线时写的东西被远端盖掉了，
+ * 是需要他知道的一类；逐条上报而不是只报最后一条，`lastConflict` 自然停在最新的那条。
+ *
+ * **`failures` 同样必须上报（RV-052）**：`flushQueryCacheOutbox` 对 REST 403、网络错误
+ * 等结构化失败从不 `reject`——Promise 照常 resolve，失败躺在返回值的 `failures` 数组里
+ * （见 `query-cache-outbox.ts` 的 `replayEntry`/`runOutboxFlush`）。调用方如果只认「有没有
+ * 抛异常」，这类失败会被判成「没出错」，面板上 `lastError` 被清空、`reportSuccess()`
+ * 被调用，而出站队列其实原地没动。这里逐条把失败的原因上报给 `syncState`——
+ * 和 `conflicts` 同样的理由，`lastError` 自然停在本轮最新的那条——并把「有没有
+ * 失败」原样交还给调用方，参与整轮 {@link flushRepositories} 的成功聚合。
+ */
+async function flushRepository(sm: SyncManager, namespace: string, entity: string): Promise<boolean> {
+  const { syncState } = sm.rxdb;
+  const result = await flushQueryCacheOutbox(sm.rxdb, namespace, entity);
+
+  for (const entityId of result.conflicts) {
+    syncState.reportConflict({ namespace, entity, entityId, winner: 'remote' });
+  }
+
+  for (const failure of result.failures) {
+    syncState.reportError(failure.error);
+  }
+
+  return result.failures.length === 0;
+}
+
+/**
+ * 重放本轮所有 QueryCache 仓库
+ *
+ * @param sm - 当前 SyncManager
+ * @param repositories - 本轮的仓库名单，由 {@link queryCacheRepositories} 枚举
+ * @returns 是否每个仓库都成功
+ */
+async function flushRepositories(sm: SyncManager, repositories: RepositoryIdentifier[]): Promise<boolean> {
+  const { syncState } = sm.rxdb;
+  let allSucceeded = true;
+
+  for (const { namespace, entity } of repositories) {
+    const succeeded = await runQuietly(syncState, () => flushRepository(sm, namespace, entity));
+    allSucceeded = succeeded && allSucceeded;
+  }
+
+  return allSucceeded;
+}
+
+/**
+ * 重新数一遍 QueryCache 的出站积压，刷新面板
+ *
+ * @remarks
+ * 失败**不**走 {@link runQuietly}：这是一次读，读不到只意味着面板停在上一个数字，
+ * 而 `lastError` 说的是「你的数据没推上去」。把一次 COUNT 失败写进去会让用户
+ * 以为刚推成功的一轮出了问题。
+ *
+ * 每轮都数而不是只在推过之后数：水位线推进不写 `rxdb_change`，实时查询看不见这个数
+ * （见 {@link SyncStateHub.reportOutboxCount}），一轮一次重算是它唯一的纠偏时机。
+ */
+async function refreshOutboxCount(sm: SyncManager): Promise<void> {
+  try {
+    sm.rxdb.syncState.reportOutboxCount(await countQueryCacheOutbox(sm.rxdb));
+  } catch {
+    // 面板保留上一个数字
+  }
+}
+
+/**
+ * 恢复联网后的一轮回推：逐个重放 QueryCache 仓库的出站队列
+ *
+ * @remarks
+ * 这一轮**只**管 QueryCache 那条 REST 路（[US-020 D5-R](../../../../requirements/stories/core/US-020-querycache-repository.md)）。
+ * changelog 那半边 —— {@link SyncManager.syncBranches} 与 {@link SyncManager.push} ——
+ * 不在这里自动跑：`push` 问的是「把我这条分支上攒的提交送到远端去」，和 git 的 `push`
+ * 一样是用户的决定。自动替他按下去，`pushableCount` 与界面上的 Push 按钮就成了摆设，
+ * 「写在本地、还没推」这个状态从此不存在。QueryCache 没有这层分支语义，它的出站队列
+ * 就是「这次写本该直接进远端，只是当时网断了」，联网补上才是它的正确行为。
+ *
+ * 各仓库串行而非并行 —— 它们打的是同一个远端，恢复瞬间并发只会把刚恢复的连接再压垮一次。
+ *
+ * 一个 QueryCache 仓库都没有时整轮不进：既省掉必然为空的一次 COUNT，也不让面板的
+ * `syncing` 为了一轮什么都不做的回推闪一下。
+ *
+ * `endRound` 放 `finally`：每一步都被 {@link runQuietly} 兜住了，但重算积压那步之外
+ * 若将来再加一步没兜住的，`syncing` 会永久卡在真上，面板从此显示「正在同步」。
+ */
+async function resumeSync(sm: SyncManager): Promise<void> {
+  const repositories = queryCacheRepositories(sm);
+  if (repositories.length === 0) {
+    return;
+  }
+
+  const { syncState } = sm.rxdb;
+  syncState.beginRound();
+
+  try {
+    // 清账放在重算积压之前：先宣布本轮没出错，再把「还剩多少」更新上去
+    if (await flushRepositories(sm, repositories)) {
+      syncState.reportSuccess();
+    }
+    await refreshOutboxCount(sm);
+  } finally {
+    syncState.endRound();
+  }
+}
+
+/**
+ * 构造回推触发流
+ *
+ * @remarks
+ * 两个触发源，语义不同：
+ *
+ * - **可回推了**：`connected$`（适配器生命周期）与 `online$`（网络可达）**同时**为真。
+ *   两者缺一不可，也不能互相替代 —— HTTP 适配器的 `connect()` 不发任何网络请求，
+ *   断网时它照样报 connected；反过来网通了但适配器没连上，回推没有可用的本地仓储。
+ * - **再试一次**：离线期间的退避节拍。它只按 `connected$` 过滤，**不**按 `online$` ——
+ *   节拍存在的意义正是在判定为离线时驱动重试，用离线状态把它挡掉会让重试链彻底断掉。
+ */
+function createResumeTrigger(sm: SyncManager): Observable<unknown> {
+  const connected$ = sm.rxdb.connected$;
+  const ready$ = combineLatest([connected$, sm.rxdb.reachability.online$]).pipe(
+    map(([connected, online]) => connected && online),
+    distinctUntilChanged()
+  );
+
+  return merge(
+    ready$.pipe(filter(ready => ready)),
+    sm.rxdb.reachability.wakeup$.pipe(
+      withLatestFrom(connected$),
+      filter(([, connected]) => connected)
+    )
+  );
+}
+
+/**
+ * 设置 SyncManager 的同步监听器
+ *
+ * 包含两条 reactive 链路：
+ * 1. 「已连接且网络可达」→ 自动重放 QueryCache 出站队列，离线期间由退避节拍驱动重试，
+ *    每个仓库失败仅吞错。changelog 的 `push` 不在其中，见 {@link resumeSync}
+ * 2. Remote 实体事件 → 累计 `pullableCount`（仅统计当前激活分支）
+ *
+ * 调用方负责管理返回的 subscriptions / removers 生命周期（destroy 时清理）。
+ *
+ * @param sm - 当前同步管理器
+ * @returns 已注册的 rxjs subscriptions 和事件解绑闭包
+ */
+export function setupSyncListeners(sm: SyncManager): {
+  subscriptions: Subscription[];
+  removers: Array<() => void>;
+} {
+  const subscriptions: Subscription[] = [];
+  const removers: Array<() => void> = [];
+
+  // 1. 有远程适配器时，恢复联网后自动回推
+  const remoteAdapterName = sm.rxdb.config.sync?.remote?.adapter;
+  if (remoteAdapterName) {
+    // `exhaustMap` 而不是 `mergeMap`：恢复瞬间往往连着来好几个信号（`online` 事件、
+    // 退避节拍、用户手动重试），并发起两轮回推会把同一批变更重放两次 ——
+    // 第二轮读到的还是第一轮尚未推进的水位线。
+    const sub = createResumeTrigger(sm)
+      .pipe(
+        exhaustMap(() =>
+          // 一轮回推失败只终结这一轮。`resumeSync` 里 `runQuietly` 兜住的只有逐仓库 flush，
+          // 枚举仓库与面板上报都在兜底之外；它们抛错顺着 `exhaustMap` 冒到订阅上就会终结整条
+          // 触发流 —— 此后 online 事件、退避节拍、重新连接一律无效，自动回推永久停摆，
+          // 而离线恢复本就是最容易出错的场景。吞掉不等于藏起来：错误进面板，用户看得见。
+          resumeSync(sm).catch((error: unknown) => {
+            sm.rxdb.syncState.reportError(error);
+          })
+        )
+      )
+      .subscribe();
+    subscriptions.push(sub);
+  }
+
+  // 2. 只累计当前激活分支的远程变更数量
+  const filterByBranch = async (entities: { branchId?: string }[]): Promise<number> => {
+    const branch = await sm.getCurrentBranch();
+    return entities.filter(e => !e.branchId || e.branchId === branch.id).length;
+  };
+
+  const makeRemoteHandler = (label: string) => {
+    return (event: RemoteEntityEvent) => {
+      void (async () => {
+        try {
+          const count = await filterByBranch(event.entities);
+          if (count > 0) sm.history.incrementPullableCount(count);
+        } catch (error) {
+          if (!isIgnorableDetachedVersionEventError(error)) {
+            console.error(`[SyncManager] ${label} failed:`, error);
+          }
+        }
+      })();
+    };
+  };
+
+  const remoteHandlers = [
+    { type: ENTITY_REMOTE_CREATE_EVENT, handler: makeRemoteHandler('onRemoteCreate') },
+    { type: ENTITY_REMOTE_UPDATE_EVENT, handler: makeRemoteHandler('onRemoteUpdate') },
+    { type: ENTITY_REMOTE_REMOVE_EVENT, handler: makeRemoteHandler('onRemoteRemove') }
+  ] as const;
+
+  for (const { type, handler } of remoteHandlers) {
+    sm.rxdb.addEventListener(type, handler);
+    // 在注册点闭包捕获已静态对齐的 type/handler，解绑时无需类型断言
+    removers.push(() => sm.rxdb.removeEventListener(type, handler));
+  }
+
+  return { subscriptions, removers };
+}

package/src/sync-manager.utils.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview 同步管理器的纯函数工具集
+ *
+ * 从 {@link SyncManager} 抽出的无状态辅助函数。US-025 阶段 D 之前它们住在
+ * `@aiao/rxdb-plugin-history` 的 `version-manager.utils.ts`，随 `bulkSync` 一起搬过来 ——
+ * 两个函数的形参都是 {@link SyncRepositoryResult}，这是同步侧的类型。
+ */
+
+import { RxDBPartialSyncError } from '@aiao/rxdb';
+import type { SyncRepositoryResult } from './sync-repository.js';
+
+/**
+ * 「这次同步已经改写了本地数据」的共同判据形状。
+ *
+ * @remarks
+ * 四个粒度的结果都满足它，所以判据只需要写一份：整库 / 单仓库的 `PullResult` 只有
+ * `historyInvalidated`，`SyncRepositoryResult` 还多一段 `pushResult`。两项都取可选，
+ * 缺哪一段就当那一段没有进度。
+ */
+interface SyncedProgress {
+  readonly historyInvalidated?: boolean;
+  readonly pushResult?: { readonly pushed: number };
+}
+
+/** 一次仓库同步是否改写了本地实体数据（undo 历史边界因此失效） */
+export const hasSyncedData = (result: SyncedProgress | undefined): boolean =>
+  result?.historyInvalidated === true || (result?.pushResult?.pushed ?? 0) > 0;
+
+/**
+ * 中断的同步里是否带着「已经落库 / 已经上行」的进度。
+ *
+ * @remarks
+ * 部分成功以 {@link RxDBPartialSyncError} 的形式抛出，进度只挂在它的 `result` 上。
+ * `pull` / `pullRepository` / `sync` / `syncRepository` 四个入口共用这一条判据 ——
+ * 各写各的 `instanceof` + 强转，迟早会有一个入口漏掉 `pushResult` 那一半。
+ */
+export const partialSyncInvalidatesHistory = (error: unknown): boolean =>
+  error instanceof RxDBPartialSyncError && hasSyncedData(error.result as SyncedProgress);
+
+/**
+ * 取出失败项里携带的部分进度。
+ *
+ * @remarks
+ * 仓库在失败前可能已经提交了部分结果，它只存在于 {@link RxDBPartialSyncError.result}。
+ * 忽略它会让「远端数据已落库但 undo 边界没推进」的状态逃过检查。
+ */
+export const partialResultOf = (error: Error | undefined): SyncRepositoryResult | undefined =>
+  error instanceof RxDBPartialSyncError ? (error.result as SyncRepositoryResult) : undefined;