@aiao/rxdb-plugin-sync 0.0.26 → 0.0.28

package/src/push.ts

@@ -54,6 +54,7 @@ export async function push(sm: SyncManager, options?: PushOptions): Promise<Push
     // 汇总结果
     const pushResult: PushResult = {
       pushed: 0,
+      rejected: 0,
       failed: 0,
       compacted: 0,
       originalCount: 0,
@@ -67,6 +68,7 @@ export async function push(sm: SyncManager, options?: PushOptions): Promise<Push
       const repoResult = result.result?.pushResult;
       if (repoResult) {
         pushResult.pushed += repoResult.pushed;
+        pushResult.rejected += repoResult.rejected;
         pushResult.failed += repoResult.failed;
         pushResult.compacted += repoResult.compacted;
         pushResult.originalCount += repoResult.originalCount;
@@ -75,7 +77,7 @@ export async function push(sm: SyncManager, options?: PushOptions): Promise<Push
       if (result.success) continue;
 
       // 失败**不折算成 failed += 1**：failed 的单位是变更条数，混进仓库计数会破坏
-      // `originalCount = pushed + failed + compacted`。失败结构化保留在 failures 里。
+      // `originalCount = pushed + failed + rejected + compacted`。失败结构化保留在 failures 里。
       const failure =
         result.error ??
         new RxDBError(`Repository push failed: ${result.repository.namespace}:${result.repository.entity}`);

package/src/query-cache-outbox.ts

@@ -41,6 +41,7 @@ import {
   isNetworkError,
   isRepositorySyncEnabled,
   LWWConflictResolver,
+  type QueryCacheEntity,
   type QueryCacheRemoteAdapter,
   type RxDB,
   RxDBChange,
@@ -327,7 +328,12 @@ async function runOutboxFlush(
   if (metadata) {
     await replayPhases(entries, metadata, { rxdb, entity, remoteAdapter, conflictResolver, run });
   }
-  await repairLocalCache(localAdapter, remoteAdapter, entity, run);
+  await repairLocalCache(localAdapter, remoteAdapter, entity, run, {
+    changeRepo,
+    namespace,
+    branchId: branch.id,
+    maxChangeId
+  });
 
   if (run.failures.length > 0) {
     // 整批没推完，但已经结算掉的那一段可以让水位线跟上去。不跟的话，下一轮会把这些
@@ -407,7 +413,7 @@ export async function countQueryCacheOutbox(rxdb: RxDB): Promise<number> {
     where: { combinator: 'and', rules: [{ field: 'branchId', operator: '=', value: branch.id }] }
   });
 
-  const repoRules = buildOfflineWriteRepositoryRules(rxdb.config.entities, rxdb.config.sync, repoSyncs);
+  const repoRules = buildOfflineWriteRepositoryRules(rxdb.config.entities, rxdb.entitySync, repoSyncs);
   if (repoRules.length === 0) {
     return 0;
   }
@@ -423,6 +429,9 @@ export async function countQueryCacheOutbox(rxdb: RxDB): Promise<number> {
           { field: 'branchId', operator: '=', value: branch.id },
           { field: 'revertChangeId', operator: '=', value: null },
           { field: 'remoteId', operator: '=', value: null },
+          // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+          // 必须和 remoteId = null 一起排除，否则会被当成积压计进出站队列
+          { field: 'rejectedAt', operator: '=', value: null },
           { combinator: 'or', rules: repoRules }
         ]
       }
@@ -489,7 +498,7 @@ function resolveQueryCacheSyncType(rxdb: RxDB, namespace: string, entity: string
     throw new RxDBError(`Entity not found for QueryCache outbox flush: ${namespace}/${entity}`);
   }
 
-  const syncType = getSyncType(getEntityMetadata(EntityType), rxdb.config.sync);
+  const syncType = getSyncType(getEntityMetadata(EntityType), rxdb.entitySync);
   if (syncType !== 'querycache') {
     throw new RxDBError(
       `flushQueryCacheOutbox only handles syncType 'querycache'; ${namespace}/${entity} is '${syncType}'. ` +
@@ -522,6 +531,9 @@ async function queryOutboxChanges(
     { field: 'entity', operator: '=', value: entity },
     { field: 'branchId', operator: '=', value: branchId },
     { field: 'remoteId', operator: '=', value: null },
+    // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+    // 必须和 remoteId = null 一起排除，否则会被当成待推行重放到远端
+    { field: 'rejectedAt', operator: '=', value: null },
     { field: 'revertChangeId', operator: '=', value: null }
   ];
 
@@ -836,6 +848,47 @@ function remoteWrite(
   return remoteAdapter.update ? remoteAdapter.update(entity, entry.entityId, patch) : null;
 }
 
+/** {@link repairLocalCache} 判定「这批 id 里谁被新写盖过」所需的快照上下文 */
+interface RepairSnapshot {
+  changeRepo: IRepository<typeof RxDBChange>;
+  namespace: string;
+  branchId: string;
+  /** 本轮重放开始时 `pending` 的最大变更行 id —— 判定起点,见 {@link findEntityIdsWithNewerPendingChanges} */
+  maxChangeId: number;
+}
+
+/**
+ * 查一遍这批实体里谁在本轮快照之后又产生了新的待推变更。
+ *
+ * @returns 有新变更的实体 id 集合
+ *
+ * @remarks
+ * RV-055：`repairLocalCache` 要把 KEEP_REMOTE 判负的那些行覆盖回远端取到的投影，但判负
+ * 是对着 `runOutboxFlush` 开头那份 `pending` 快照做的 —— 决定做完、`findByIds` 响应还在
+ * 网络上滞留的这段时间里，用户完全可能在同一个实体上又写了一笔离线改动。那次新写有
+ * 它自己的 `RxDBChange` 行，而触发器写入的变更 id 是自增的，必然大于本轮快照的
+ * `maxChangeId`——不用比时间戳（铁律：不用计时式修复），只用这一条单调递增的序号就能
+ * 确定「是不是本轮判过负之后才出现的」。命中的那些 id 对应的修复必须跳过：旧判决覆盖
+ * 的是「本轮快照里的状态」，而本地此刻的真实状态已经是那笔新写，拿旧判决去盖，等于让
+ * 一次已经提交的新写无声消失，且发起它的人永远不会知道。
+ *
+ * 查询条件复用 {@link queryOutboxChanges}：同分支、未推送、未回滚、`id > maxChangeId`，
+ * 与「谁还排在出站队列里」同一个口径，不开第二份判据。
+ */
+async function findEntityIdsWithNewerPendingChanges(
+  snapshot: RepairSnapshot,
+  entity: string
+): Promise<ReadonlySet<string>> {
+  const newer = await queryOutboxChanges(
+    snapshot.changeRepo,
+    snapshot.namespace,
+    entity,
+    snapshot.branchId,
+    snapshot.maxChangeId
+  );
+  return new Set(newer.map(change => String(change.entityId)));
+}
+
 /**
  * 把 LWW 判负的那些行在本地缓存里对齐远端。
  *
@@ -846,19 +899,39 @@ function remoteWrite(
  * 回去 —— 一个自我供给的循环，而且每绕一圈都以远端的那次改动被丢弃告终。
  *
  * 修复失败不改判定：远端侧已经是权威状态了，这里只是本地投影没跟上，下一次读会同步回来。
+ *
+ * **落盘前重新核对一遍「谁被新写盖过」（RV-055）**：真正的竞争窗口就是上面
+ * `findByIds` 在网络上滞留的这段时间，核对必须放在它之后、紧贴着 `upsertMany` /
+ * `deleteByIds` 之前 —— 早一步核对看到的还是旧状态，等于没核对。命中的 id 从本次要
+ * 写的集合里摘掉，留给下一轮：那时它会带着「本地此刻的真实状态」重新跟远端的最新值
+ * 比一次，而不是被这一轮的旧判决悄悄盖掉。
  */
 async function repairLocalCache(
   localAdapter: OutboxLocalAdapter,
   remoteAdapter: QueryCacheRemoteAdapter,
   entity: string,
-  run: RunState
+  run: RunState,
+  snapshot: RepairSnapshot
 ): Promise<void> {
-  if (run.restoreIds.length > 0) {
-    const rows = await firstValueFrom(remoteAdapter.findByIds(entity, run.restoreIds));
-    await firstValueFrom(localAdapter.upsertMany(entity, rows));
+  if (run.restoreIds.length === 0 && run.dropIds.length === 0) {
+    return;
   }
-  if (run.dropIds.length > 0) {
-    await firstValueFrom(localAdapter.deleteByIds(entity, run.dropIds));
+
+  const rows =
+    run.restoreIds.length > 0 ?
+      await firstValueFrom(remoteAdapter.findByIds<QueryCacheEntity>(entity, run.restoreIds))
+    : [];
+
+  const superseded = await findEntityIdsWithNewerPendingChanges(snapshot, entity);
+
+  const freshRows = rows.filter(row => !superseded.has(row.id));
+  if (freshRows.length > 0) {
+    await firstValueFrom(localAdapter.upsertMany(entity, freshRows));
+  }
+
+  const freshDropIds = run.dropIds.filter(id => !superseded.has(id));
+  if (freshDropIds.length > 0) {
+    await firstValueFrom(localAdapter.deleteByIds(entity, freshDropIds));
   }
 }
 

package/src/sync-branches.ts

@@ -1,29 +1,100 @@
-import { type IRepository, RxDBBranch, RxDBChange, RxDBError } from '@aiao/rxdb';
+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 —— 具体原因见同一个 id 在 {@link skipReasons} 里的条目。
    *
-   * 远端分支行上的 `fromChangeId` 是远端 change id，落到本地必须翻译成本地 id
-   * （见 {@link toLocalFromChangeId}）。翻译不出来时既不能写远端 id（本地会当自己的 id 消费，
-   * 分叉点变成一个无关变更），也不能写 `null`（`find-switch-branch-step` 会当「分叉于根」，
-   * 切换分支时从第一条变更起算）。唯一无损的选择是本轮跳过，等分叉点变更拉到本地后再建。
+   * 一条分支被跳过，可能是它自己的问题（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;
+  }
+}
+
 /**
  * 把远端分支按「父在前」重排。
  *
@@ -98,12 +169,12 @@ 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: [] };
+    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: [] };
+    return { created: 0, updated: 0, total: 0, skipped: [], skipReasons: {} };
   }
 
   const { adapter } = await sm.getLocalRepositories();
@@ -120,8 +191,48 @@ export async function syncBranches(sm: SyncManager): Promise<SyncBranchesResult>
     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) {
@@ -136,13 +247,16 @@ export async function syncBranches(sm: SyncManager): Promise<SyncBranchesResult>
       const fromChangeId =
         remoteFromChangeId === null ? null : await toLocalFromChangeId(changeRepository, remoteFromChangeId);
       if (remoteFromChangeId !== null && fromChangeId === null) {
-        skipped.push(remote.id);
+        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,
@@ -151,6 +265,12 @@ export async function syncBranches(sm: SyncManager): Promise<SyncBranchesResult>
       created++;
     }
 
-    return { created, updated, total: remoteBranches.length, skipped };
+    return {
+      created,
+      updated,
+      total: remoteBranches.length,
+      skipped,
+      skipReasons: Object.fromEntries(skippedThisRound)
+    };
   });
 }

package/src/sync-listeners.ts

@@ -28,8 +28,8 @@ type RemoteEntityEvent = EntityRemoteCreatedEvent | EntityRemoteUpdatedEvent | E
  * 跑一步回推动作，把失败报给面板后吞掉
  *
  * @param syncState - 失败的去处
- * @param task - 这一步
- * @returns 这一步是否成功
+ * @param task - 这一步；返回值是这一步**自己**判定的成功与否（见 {@link flushRepository}）
+ * @returns 这一步是否成功——异常通道与 `task` 自报的 `false` 都算失败
  *
  * @remarks
  * 一轮里的各个仓库互不背书：一个仓库的出站队列重放不上，不代表别的仓库那条 REST 路
@@ -39,11 +39,15 @@ type RemoteEntityEvent = EntityRemoteCreatedEvent | EntityRemoteUpdatedEvent | E
  * 多少次网络都不会再有回推。真正的重试节奏交给
  * {@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<unknown>): Promise<boolean> {
+async function runQuietly(syncState: SyncStateHub, task: () => Promise<boolean>): Promise<boolean> {
   try {
-    await task();
-    return true;
+    return await task();
   } catch (error) {
     syncState.reportError(error);
     return false;
@@ -80,7 +84,7 @@ function queryCacheRepositories(sm: SyncManager): RepositoryIdentifier[] {
 
   for (const EntityClass of consumerEntities(sm)) {
     const metadata = getEntityMetadata(EntityClass);
-    const capability = getSyncCapability(getSyncType(metadata, sm.rxdb.config.sync));
+    const capability = getSyncCapability(getSyncType(metadata, sm.rxdb.entitySync));
     if (capability.offlineWrite && !capability.push) {
       repositories.push({ namespace: metadata.namespace, entity: metadata.name });
     }
@@ -90,19 +94,35 @@ function queryCacheRepositories(sm: SyncManager): RepositoryIdentifier[] {
 }
 
 /**
- * 重放一个 QueryCache 仓库，把判负的实体报给面板
+ * 重放一个 QueryCache 仓库，把判负的实体和结构化失败都报给面板
+ *
+ * @returns 本仓库这一轮是否**真的**成功——`failures` 非空也算失败，即便没有任何异常抛出
  *
  * @remarks
- * 只有 `conflicts`（解析器判 `KEEP_REMOTE`）进面板：那是用户离线时写的东西被远端盖掉了，
- * 是唯一需要他知道的一类。逐条上报而不是只报最后一条，`lastConflict` 自然停在最新的那条。
+ * `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<void> {
+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;
 }
 
 /**

package/src/sync-repository.ts

@@ -7,7 +7,8 @@ import {
   RepositorySyncErrorEvent,
   RxDBError,
   RxDBPartialSyncError,
-  type SyncProgress
+  type SyncProgress,
+  type SyncRejection
 } from '@aiao/rxdb';
 import type { SyncManager } from './SyncManager.js';
 import {
@@ -89,6 +90,7 @@ function emptyPushResult(namespace: string, entity: string): PushRepositoryResul
   return {
     repository: { namespace, entity },
     pushed: 0,
+    rejected: 0,
     failed: 0,
     compacted: 0,
     originalCount: 0,
@@ -167,6 +169,7 @@ function rewrapPushFailure(
  * @param namespace - 实体命名空间
  * @param entity - 实体名称
  * @param options - 同步选项
+ * @param rejectionSink - 推送被拒清单收集器，语义同 {@link pushRepository} 的同名参数
  * @returns 同步结果
  *
  * @example
@@ -185,7 +188,8 @@ export async function syncRepository(
   sm: SyncManager,
   namespace: string,
   entity: string,
-  options?: SyncRepositoryOptions
+  options?: SyncRepositoryOptions,
+  rejectionSink?: SyncRejection[]
 ): Promise<SyncRepositoryResult> {
   const rxdb = sm.rxdb;
 
@@ -194,7 +198,7 @@ export async function syncRepository(
   rxdb.dispatchEvent(new RepositorySyncBeginEvent('sync', namespace, entity, includeRelated));
 
   try {
-    const result = await _syncRepositoryImpl(sm, namespace, entity, options);
+    const result = await _syncRepositoryImpl(sm, namespace, entity, options, rejectionSink);
 
     // 触发完成事件
     // 两个子结果在 SyncRepositoryResult 上都是必填：跳过的方向由 emptyPullResult /
@@ -226,7 +230,8 @@ async function _syncRepositoryImpl(
   sm: SyncManager,
   namespace: string,
   entity: string,
-  options?: SyncRepositoryOptions
+  options?: SyncRepositoryOptions,
+  rejectionSink?: SyncRejection[]
 ): Promise<SyncRepositoryResult> {
   // 验证仓库是否存在
   const EntityType = sm.rxdb.config.entities.find(e => {
@@ -241,7 +246,7 @@ async function _syncRepositoryImpl(
   const metadata = getEntityMetadata(EntityType);
 
   // 检查同步类型（支持全局配置回退）
-  const syncType = getSyncType(metadata, sm.rxdb.config.sync);
+  const syncType = getSyncType(metadata, sm.rxdb.entitySync);
   if (syncType === 'none') {
     throw new RxDBError(
       `Cannot sync repository ${namespace}:${entity}: syncType is 'none'. ` +
@@ -283,7 +288,7 @@ async function _syncRepositoryImpl(
 
   if (shouldPush) {
     try {
-      pushResult = await pushRepository(sm, namespace, entity, options?.push);
+      pushResult = await pushRepository(sm, namespace, entity, options?.push, rejectionSink);
     } catch (error) {
       // pull 已落库的进度、push 已发到远端的进度，都不能因为这次抛错就消失
       throw rewrapPushFailure(error, pullResult, namespace, entity);

package/dist/version.utils.d.ts

@@ -1,3 +0,0 @@
-import { RemoteChange, RxDBChange } from '@aiao/rxdb';
-export declare const remote_change_to_local: (remoteChange: RemoteChange[], base: Partial<RxDBChange>) => Omit<RxDBChange, "id" | "branch$">[];
-//# sourceMappingURL=version.utils.d.ts.map

package/dist/version.utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"version.utils.d.ts","sourceRoot":"","sources":["../src/version.utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAQ,MAAM,YAAY,CAAC;AAC5D,eAAO,MAAM,sBAAsB,GACjC,cAAc,YAAY,EAAE,EAC5B,MAAM,OAAO,CAAC,UAAU,CAAC,KACxB,IAAI,CAAC,UAAU,EAAE,IAAI,GAAG,SAAS,CAAC,EAUjC,CAAC"}

package/src/version.utils.ts

@@ -1,20 +0,0 @@
-/**
- * @packageDocumentation
- * 版本工具模块
- * 提供远程变更转换为本地变更等功能
- */
-import { RemoteChange, RxDBChange, UUID } from '@aiao/rxdb';
-export const remote_change_to_local = (
-  remoteChange: RemoteChange[],
-  base: Partial<RxDBChange>
-): Omit<RxDBChange, 'id' | 'branch$'>[] =>
-  remoteChange.map(rc => {
-    const { id, ...rest } = rc;
-    delete rest.clientId;
-    return {
-      ...rest,
-      ...base,
-      entityId: (base.entityId ?? rest.entityId) as UUID,
-      remoteId: id
-    };
-  });