@aiao/rxdb-plugin-sync 0.0.26 → 0.0.28

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

@@ -9,8 +9,6 @@ import {
   getSyncCapability,
   getSyncType,
   isRepositorySyncEnabled,
-  needsPull,
-  needsPush,
   type RepositoryIdentifier,
   type RxDB,
   RxDBChange,
@@ -117,6 +115,9 @@ async function calculatePushableCount(
     { 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 }
   ];
 
@@ -181,7 +182,7 @@ export async function getRepositorySyncStatus(
   }
 
   const metadata = getEntityMetadata(EntityClass);
-  const syncType = getSyncType(metadata, rxdb.config.sync);
+  const syncType = getSyncType(metadata, rxdb.entitySync);
   const syncCapability = getSyncCapability(syncType);
 
   // 2. 获取当前分支
@@ -209,13 +210,12 @@ export async function getRepositorySyncStatus(
   let pushableCount = 0;
   let pullableCount = 0;
 
-  // 如果该实体需要推送，则计算 pushableCount（与 syncType 一致地传入全局 sync 回退）
-  if (needsPush(metadata, rxdb.config.sync)) {
+  // 推拉能力取开头那一次解析的结果：中间隔着几个 await，重新解析可能与返回的 syncType 不一致
+  if (syncCapability.push) {
     pushableCount = await calculatePushableCount(sm, namespace, entity, branchId, repoSync?.lastPushedChangeId ?? null);
   }
 
-  // 如果该实体需要拉取，则计算 pullableCount（与 syncType 一致地传入全局 sync 回退）
-  if (needsPull(metadata, rxdb.config.sync)) {
+  if (syncCapability.pull) {
     pullableCount = await calculatePullableCount(rxdb, namespace, entity);
   }
 

package/src/index.ts

@@ -31,7 +31,10 @@ export * from './plugin.js';
 export type { BulkSyncOptions, BulkSyncResult } from './bulk-sync.js';
 // `SyncManager.checkRepositoryUpdates()` 的返回值。函数本身是内部实现。
 export type { CheckRepositoryUpdatesResult } from './check-repository-updates.js';
-export * from './cleanup-expired.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()` 的可选过滤器。
@@ -48,6 +51,8 @@ export {
   type QueryCacheOutboxFailure,
   type QueryCacheOutboxResult
 } from './query-cache-outbox.js';
-export * from './sync-branches.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

@@ -7,6 +7,7 @@
 
 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';
 
@@ -27,7 +28,7 @@ export type RxDBPluginSyncOptions = object;
  *   而 {@link SyncManager.init} 挂的 `connected$` 自动回推订阅必须在第一次连接就位之前
  *   就已经订阅上，声明适配器依赖会把安装推到引导链之后，第一次连接的那一跳回推就丢了。
  *
- * 五处宿主改动都登记在 `scope` 上，断开连接时由宿主逆序释放：
+ * 六处宿主改动都登记在 `scope` 上，断开连接时由宿主逆序释放：
  *
  * 1. `rxdb.syncManager` 这个实例槽位 —— 释放时连同 `destroy()` 一起撤掉，不给下一个纪元
  *    留一个指向已拆事件总线的管理器；
@@ -41,6 +42,10 @@ export type RxDBPluginSyncOptions = object;
  * 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;
@@ -70,6 +75,9 @@ export class RxDBPluginSync extends RxDBPluginBase implements IRxDBPlugin {
       scope
     );
 
+    // 传 scope：断开连接时撤销，下一个纪元登记的是指向新 syncManager 的那一个，不撞「至多一个」。
+    this.rxdb.branchMaterializationSource(createSyncBranchMaterializationSource(syncManager), scope);
+
     // 可达性监听：`watch()` 自己返回撤销函数，正好是 `acquire` 要的 setup 形状。
     // 引用计数在监视器一侧，所以同一个宿主上多装几个消费者也不会互相摘掉对方的监听。
     scope.acquire(() => this.rxdb.reachability.watch(), 'sync:reachability');

package/src/pull-batch.ts

@@ -13,6 +13,7 @@
 import {
   compactChanges,
   type ConflictResolver,
+  declareTrustedWrite,
   getEntityMetadata,
   getOrCreateSyncRecord,
   getSyncCapability,
@@ -26,7 +27,8 @@ import {
   RxDBError,
   type RxDBEvent,
   RxDBPartialSyncError,
-  RxDBSync
+  RxDBSync,
+  TrustedWriteIntent
 } from '@aiao/rxdb';
 import type { SyncManager } from './SyncManager.js';
 import { getAncestorBranchIds } from './branch-utils.js';
@@ -39,6 +41,7 @@ import {
   queryPendingLocalChanges,
   resolveConflictsAndBuildActions
 } from './pull-conflict-utils.js';
+import { backfillOwnChangeRemoteIds, splitRemoteChangesByOrigin } from './pull-round.js';
 import { topologicalSortForPull } from './topological-sort.js';
 
 interface RepoSyncInfo {
@@ -170,7 +173,7 @@ async function pullBatchOnce(
 
   for (const EntityClass of rxdb.config.entities) {
     const metadata = getEntityMetadata(EntityClass);
-    const syncType = getSyncType(metadata, rxdb.config.sync);
+    const syncType = getSyncType(metadata, rxdb.entitySync);
 
     // 跳过口径从内联的 `none | local` 换成能力矩阵，与单仓/级联路径同源
     if (!getSyncCapability(syncType).pull) continue;
@@ -302,44 +305,10 @@ async function pullBatchOnce(
 
       totalPulled += filteredChanges.length;
 
-      // 分离自己推送的变更和他人的变更
-      // 只按 clientId 识别：远端记录缺少 localId（如 push 走 actions-only 路径）时，
-      // 自己的变更也不能进入他人变更的 apply/conflict 链路
-      const ownChanges: RemoteChange[] = [];
-      const otherChanges: RemoteChange[] = [];
-
-      for (const rc of filteredChanges) {
-        if (rc.clientId != null && rc.clientId === clientId) {
-          ownChanges.push(rc);
-        } else {
-          otherChanges.push(rc);
-        }
-      }
-
-      // 批量更新自己推送变更的 remoteId（只有带 localId 的记录才能回填映射）
-      const mappableChanges = ownChanges.filter(c => c.localId != null);
-      if (mappableChanges.length > 0) {
-        const localIds = mappableChanges.map(c => c.localId!);
-        const locals = await changeRepo.find({
-          where: {
-            combinator: 'and',
-            rules: [
-              { field: 'id', operator: 'in', value: localIds },
-              { field: 'remoteId', operator: '=', value: null }
-            ]
-          }
-        });
-
-        if (locals.length > 0) {
-          const ownChangeMap = new Map(mappableChanges.map(c => [c.localId!, c.id]));
-          for (const local of locals) {
-            const remoteId = ownChangeMap.get(local.id);
-            if (remoteId != null) {
-              await changeRepo.update(local, { remoteId });
-            }
-          }
-        }
-      }
+      // 分离自己推送的变更和他人的变更，再把自推变更的 remoteId 回填到本地行上。
+      // 两步与 pull-repository.ts 共用同一份实现（见 pull-round.ts 的 @packageDocumentation）。
+      const { ownChanges, otherChanges } = splitRemoteChangesByOrigin(filteredChanges, clientId);
+      await backfillOwnChangeRemoteIds(changeRepo, ownChanges);
 
       // 压缩并应用他人的变更
       if (otherChanges.length > 0) {
@@ -375,6 +344,13 @@ async function pullBatchOnce(
         const applyCount = countActions(applyActions);
         if (applyCount > 0) {
           // disableTriggers=true 确保不生成本地 RxDBChange 记录
+          // disableTriggers=true 压掉的是变更日志行，不是工作树单元：FR-046 要求拉取
+          // 照样落一个 origin='remote_sync' 的单元，所以挂载点 2 从 actions 派生，不看日志。
+          declareTrustedWrite(executor, {
+            file: 'pull-batch.ts',
+            symbol: 'pullBatchOnce',
+            intent: TrustedWriteIntent.remote_sync
+          });
           await executor.mergeChanges(applyActions, undefined, true);
           totalApplied += applyCount;
         }

package/src/pull-conflict-utils.ts

@@ -113,6 +113,10 @@ export async function queryPendingLocalChanges(
     { field: 'entity', operator: '=', value: entity },
     { field: 'branchId', operator: '=', value: branchId },
     { field: 'remoteId', operator: '=', value: null },
+    // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+    // 必须和 remoteId = null 一起排除，否则会被当成待推的本地变更，和远端变更
+    // 撞上同一个 entityId 时误判出一次本不存在的冲突
+    { field: 'rejectedAt', operator: '=', value: null },
     { field: 'revertChangeId', operator: '=', value: null },
     { field: 'entityId', operator: 'in', value: getRxDBChangeEntityIdQueryValues(entityIds) }
   ];

package/src/pull-repository.ts

@@ -7,10 +7,11 @@
 
 import {
   compactChanges,
-  type EntityMetadata,
+  declareTrustedWrite,
   type EntityType,
   getEntityMetadata,
   getOrCreateSyncRecord,
+  getSyncConfig,
   getSyncType,
   LWWConflictResolver,
   type PullRepositoryOptions,
@@ -30,7 +31,9 @@ import {
   type RxDBEvent,
   RxDBPartialSyncError,
   RxDBSync,
-  type SyncFailure
+  type SyncFailure,
+  type SyncOptions,
+  TrustedWriteIntent
 } from '@aiao/rxdb';
 import type { SyncManager } from './SyncManager.js';
 import { getAncestorBranchIds } from './branch-utils.js';
@@ -45,6 +48,7 @@ import {
   queryPendingLocalChanges,
   resolveConflictsAndBuildActions
 } from './pull-conflict-utils.js';
+import { backfillOwnChangeRemoteIds, splitRemoteChangesByOrigin } from './pull-round.js';
 import { topologicalSortForPull } from './topological-sort.js';
 
 /**
@@ -190,7 +194,7 @@ async function _pullRepositoryImpl(
   // 避免两条路径各写一份而漂移。
   // 同一处叠加 `RxDBSync.enabled` —— 显式点名单个仓库时抛错而非静默跳过，
   // 与 syncType 不合格时的行为一致；批量枚举路径（pullBatch）才是跳过。
-  const syncType = getSyncType(metadata, sm.rxdb.config.sync);
+  const syncType = getSyncType(metadata, sm.rxdb.entitySync);
   const ineligible = await resolvePullIneligibility(sm.rxdb, namespace, entity, syncType);
 
   if (ineligible) {
@@ -200,7 +204,11 @@ async function _pullRepositoryImpl(
   // 对于 Filter 同步类型，从配置中提取 filter 函数并执行
   let effectiveFilter = opts.filter;
   if (syncType === 'filter' && !effectiveFilter) {
-    const syncConfig = metadata.sync as { type: string; remote?: { filter?: () => RuleGroup } };
+    // 取生效配置而不是装饰器原值：实例覆盖可能换掉了 filter
+    const syncConfig = getSyncConfig(metadata, sm.rxdb.entitySync) as {
+      type: string;
+      remote?: { filter?: () => RuleGroup };
+    };
     if (syncConfig?.remote?.filter) {
       // T022: filter 函数执行错误处理
       try {
@@ -378,7 +386,7 @@ async function pullCascadeNode(
   }
 
   const repoMetadata = getEntityMetadata(EntityType);
-  const repoSyncType = getSyncType(repoMetadata, sm.rxdb.config.sync);
+  const repoSyncType = getSyncType(repoMetadata, sm.rxdb.entitySync);
 
   // 级联节点必须走和单仓路径同一份资格校验，否则 `local` / `none`
   // 的依赖仓会被拿去问远端要数据，绕过它自己声明的同步策略
@@ -392,7 +400,12 @@ async function pullCascadeNode(
     const result = await pullSingleRepository(sm, repo.namespace, repo.entity, {
       ...options,
       // T039: 为每个实体独立提取 filter
-      filter: resolveCascadeFilter(repoKey, repoMetadata, repoSyncType, options.filter),
+      filter: resolveCascadeFilter(
+        repoKey,
+        getSyncConfig(repoMetadata, sm.rxdb.entitySync),
+        repoSyncType,
+        options.filter
+      ),
       includeRelated: false // 防止递归级联
     });
     result.success = true;
@@ -416,7 +429,8 @@ async function pullCascadeNode(
  * 解析级联节点自己的 filter
  *
  * @param repoKey - 仓库键（`namespace:entity`），用于错误消息
- * @param repoMetadata - 该仓库的实体元数据
+ * @param repoSync - 该仓库的**生效**同步配置（`getSyncConfig(metadata, rxdb.entitySync)`）；
+ *   不能传装饰器原值 `metadata.sync`：实例覆盖可能换掉了 filter，也可能把 Full 覆盖成 Filter
  * @param repoSyncType - 该仓库的有效同步类型
  * @param inheritedFilter - 调用方显式传入的 filter
  * @returns 该仓库实际生效的 filter
@@ -429,9 +443,9 @@ async function pullCascadeNode(
  *
  * @internal
  */
-function resolveCascadeFilter(
+export function resolveCascadeFilter(
   repoKey: string,
-  repoMetadata: EntityMetadata,
+  repoSync: SyncOptions | undefined,
   repoSyncType: RepositorySyncType,
   inheritedFilter: RuleGroup | undefined
 ): RuleGroup | undefined {
@@ -439,8 +453,7 @@ function resolveCascadeFilter(
   if (repoSyncType === 'full') return undefined;
   if (repoSyncType !== 'filter') return inheritedFilter;
 
-  const syncConfig = repoMetadata.sync as { type: string; remote?: { filter?: () => RuleGroup } };
-  const filterFn = syncConfig?.remote?.filter;
+  const filterFn = (repoSync as { remote?: { filter?: () => RuleGroup } } | undefined)?.remote?.filter;
   if (!filterFn) return inheritedFilter;
 
   let extractedFilter: RuleGroup;
@@ -497,7 +510,7 @@ async function pullSingleRepository(
     return meta.namespace === namespace && meta.name === entity;
   });
   const metadata = getEntityMetadata(EntityType!);
-  const syncType = getSyncType(metadata, sm.rxdb.config.sync);
+  const syncType = getSyncType(metadata, sm.rxdb.entitySync);
 
   let repoSync = await getOrCreateSyncRecord(
     repoSyncRepo,
@@ -558,20 +571,8 @@ async function pullSingleRepository(
       lastRemoteChange = remoteChanges[remoteChanges.length - 1];
       sinceId = lastRemoteChange.id;
 
-      // 分离自己 push 上去的变更和他人的变更
-      const clientId = rxdb.context.clientId;
-      const ownChanges: RemoteChange[] = [];
-      const otherChanges: RemoteChange[] = [];
-
-      // 只按 clientId 识别：远端记录缺少 localId（如 push 走 actions-only 路径）时，
-      // 自己的变更也不能进入他人变更的 apply/conflict 链路
-      for (const rc of remoteChanges) {
-        if (rc.clientId != null && rc.clientId === clientId) {
-          ownChanges.push(rc);
-        } else {
-          otherChanges.push(rc);
-        }
-      }
+      // 分离自己 push 上去的变更和他人的变更（与 pull-batch.ts 共用同一份实现）
+      const { ownChanges, otherChanges } = splitRemoteChangesByOrigin(remoteChanges, rxdb.context.clientId);
 
       // remoteId 回填、实体应用、supersession 标记与水位线推进必须在**一个**事务里。
       //
@@ -586,24 +587,9 @@ async function pullSingleRepository(
         // 绑定在适配器上，其读写会重新排队并排在自己这个事务后面（队列并发度 1）。
         const txChangeRepo = executor.getRepository(RxDBChange);
         const txRepoSyncRepo = executor.getRepository(RxDBSync);
-        // 为自己 push 的变更更新本地 remoteId（只有带 localId 的记录才能回填映射）
-        const mappableChanges = ownChanges.filter(c => c.localId != null);
-        if (mappableChanges.length > 0) {
-          const localIds = mappableChanges.map(c => c.localId!);
-          const locals = await txChangeRepo.find({
-            where: {
-              combinator: 'and',
-              rules: [{ field: 'id', operator: 'in', value: localIds }]
-            }
-          });
-          const localMap = new Map(locals.map(l => [l.id, l]));
-          for (const ownChange of mappableChanges) {
-            const local = localMap.get(ownChange.localId!);
-            if (local && local.remoteId == null) {
-              await txChangeRepo.update(local, { remoteId: ownChange.id });
-            }
-          }
-        }
+        // 为自己 push 的变更更新本地 remoteId。此前这里把「只写没映射过的行」写成 JS 守卫，
+        // 而 pull-batch 写在 SQL 里——判据相同、写法不同，改一处漏一处不会红。现已共用。
+        await backfillOwnChangeRemoteIds(txChangeRepo, ownChanges);
 
         // 只对他人的变更执行压缩和应用
         if (otherChanges.length > 0) {
@@ -630,6 +616,13 @@ async function pullSingleRepository(
               conflictResolver,
               dispatchEvent: (event: RxDBEvent) => rxdb.dispatchEvent(event),
               repoLabel: `${namespace}:${entity}`,
+              // 推迟 supersession 标记，改由下面 `mergeChanges` 之后自己写。pull-batch 不传这一项、
+              // 走的是解冲突时就地标记——两条路径由此分叉，但分叉是**有意的**：本文件的写全在
+              // 一个事务里，把「这条本地变更已被远端取代」写在实体合并之后，失败回滚时二者同进同退。
+              //
+              // 这个位置不会漏标：`localChangeSupersessions` 只在 KEEP_REMOTE 分支 push，而那一支
+              // 必定同时 `setAction`，于是非空的 supersession 蕴含 `applyCount > 0`，
+              // 下面那道 `if` 永远不会把它挡在外面。
               deferLocalChangeSupersession: true,
               localClientId: rxdb.context.clientId
             }
@@ -640,6 +633,12 @@ async function pullSingleRepository(
           if (applyCount > 0) {
             // 先将实体变更应用到本地数据库（在更新 RxDBSync 之前）
             // disableTriggers=true 确保不生成本地 RxDBChange 记录
+            // 同 pull-batch：远端来的行进工作树，但不回流成一次可 push 的本地变更。
+            declareTrustedWrite(executor, {
+              file: 'pull-repository.ts',
+              symbol: 'pullSingleRepository',
+              intent: TrustedWriteIntent.remote_sync
+            });
             await executor.mergeChanges(applyActions, undefined, true);
             for (const supersession of localChangeSupersessions) {
               await markLocalChangesSuperseded(txChangeRepo, supersession.localChanges, supersession.remoteId);

package/src/pull-round.ts

@@ -0,0 +1,103 @@
+/**
+ * @packageDocumentation
+ * 一轮拉取里与「谁推的、映射回哪一行」有关的两步。
+ *
+ * @remarks
+ * `pullBatchOnce`（`pull-batch.ts`）与 `pullSingleRepository`（`pull-repository.ts`）走的是
+ * 同一段流程：**拆分自推与他人的变更 → 回填自推变更的 `remoteId` → 压缩他人变更 → 解冲突 →
+ * 合并进实体表 → 推水位线**。两边曾各抄一份，而抄件会分叉——next-11 评审复核时实测到的分叉
+ * 正在这里：一侧把「只回填还没映射过的行」写进 SQL（`remoteId = null` → `IS NULL`），
+ * 一侧写成 JS 守卫（`local.remoteId == null`）。两种写法当时判据相同，但**没有任何东西保证
+ * 下一次改动仍然相同**，而一侧漏改不会让任何用例变红。
+ *
+ * 本模块收的是那段流程里**不碰受信写原语**的前半截。后半截（`executor.mergeChanges` 与随之
+ * 而来的 supersession 标记）留在各自文件里，不是嫌麻烦：那一次写要按 `file`·`symbol`·`intent`
+ * 在 `TRUSTED_CALLSITE_REGISTRY` 里对号入座（`declareTrustedWrite`），搬进本模块等于把两个
+ * 登记入口合并成一个——那是核心包的适配器契约变更，不是同步插件自己能定的事。
+ */
+
+import { type IRepository, type RemoteChange, type RxDBChange } from '@aiao/rxdb';
+
+/** {@link splitRemoteChangesByOrigin} 的结果 */
+export interface RemoteChangeOrigins {
+  /** 本客户端自己 push 上去、这轮又拉回来的变更 */
+  ownChanges: RemoteChange[];
+  /** 其他客户端产生的变更，只有这一批进 apply / conflict 链路 */
+  otherChanges: RemoteChange[];
+}
+
+/**
+ * 按 `clientId` 把一批远端变更拆成「自己推的」与「他人的」
+ *
+ * @param changes - 本轮拉到的远端变更
+ * @param clientId - 本客户端 id
+ * @returns 两个互斥的子集，顺序与入参一致
+ *
+ * @remarks
+ * **只认 `clientId`，不拿 `localId` 当替补**：push 走 actions-only 路径时远端记录不带 `localId`，
+ * 若用「有 localId 就是自己的」去判，这类记录会被判成他人的而重复应用一遍；反过来，若把
+ * 「没有 clientId」也算成自己的，那这批数据拉下来了却永远不进 apply 链路——静默丢数据。
+ * 所以缺 `clientId` 一律算他人的：多走一遍幂等的 apply，好过整批不落库。
+ */
+export const splitRemoteChangesByOrigin = (
+  changes: RemoteChange[],
+  clientId: string | undefined
+): RemoteChangeOrigins => {
+  const ownChanges: RemoteChange[] = [];
+  const otherChanges: RemoteChange[] = [];
+
+  for (const change of changes) {
+    if (change.clientId != null && change.clientId === clientId) {
+      ownChanges.push(change);
+    } else {
+      otherChanges.push(change);
+    }
+  }
+
+  return { ownChanges, otherChanges };
+};
+
+/**
+ * 把自推变更拿到的远端 id 回填到对应的本地 `RxDBChange` 行上
+ *
+ * @param changeRepo - 变更表仓库；在事务里调用时必须是经 executor 取到的那一个
+ * @param ownChanges - {@link splitRemoteChangesByOrigin} 分出的自推变更
+ *
+ * @remarks
+ * 只回填 `remoteId` 还空着的行，判据写在 SQL 里（`= null` 由适配器编译成 `IS NULL`）而不是
+ * 取回来再用 JS 挑：少取一批行是次要的，主要是让「只写没映射过的」成为查询本身的一部分，
+ * 而不是一条可以被下一次改动顺手删掉的 `if`。
+ *
+ * 覆盖已有映射不是小事：`cleanupExpired` 按 `remoteId` 判「这条已经同步出去了」，
+ * 把旧映射改写成本轮的 id 会让保留窗口整段错位——旧变更被当成刚同步的留下来，
+ * 而真正该留的那批反而先到期。
+ *
+ * 没有 `localId` 的自推变更直接跳过：对不上本地行，硬回填只能靠猜。
+ */
+export const backfillOwnChangeRemoteIds = async (
+  changeRepo: IRepository<typeof RxDBChange>,
+  ownChanges: RemoteChange[]
+): Promise<void> => {
+  const mappableChanges = ownChanges.filter(change => change.localId != null);
+  if (mappableChanges.length === 0) return;
+
+  const locals = await changeRepo.find({
+    where: {
+      combinator: 'and',
+      rules: [
+        { field: 'id', operator: 'in', value: mappableChanges.map(change => change.localId!) },
+        { field: 'remoteId', operator: '=', value: null },
+        // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+        // 不该被本轮回填覆盖掉——覆盖了反而让 cleanupExpired 的保留窗口误判
+        { field: 'rejectedAt', operator: '=', value: null }
+      ]
+    }
+  });
+  if (locals.length === 0) return;
+
+  const remoteIdByLocalId = new Map(mappableChanges.map(change => [change.localId!, change.id]));
+  for (const local of locals) {
+    const remoteId = remoteIdByLocalId.get(local.id);
+    if (remoteId != null) await changeRepo.update(local, { remoteId });
+  }
+};

package/src/pull.ts

@@ -89,7 +89,7 @@ async function pullFilterRepositories(sm: SyncManager, options: PullOptions | un
 
   for (const EntityClass of rxdb.config.entities) {
     const metadata = getEntityMetadata(EntityClass);
-    const syncType = getSyncType(metadata, rxdb.config.sync);
+    const syncType = getSyncType(metadata, rxdb.entitySync);
     if (syncType !== 'filter' || !getSyncCapability(syncType).pull) continue;
 
     const repoSync = await findCurrentSyncRecord(sm.rxdb, metadata.namespace, metadata.name);

package/src/push-branch.ts

@@ -1,3 +1,4 @@
+import { MAIN_BRANCH_ID } from '@aiao/rxdb';
 import { toRemoteFromChangeId } from './branch-change-id.js';
 import type { SyncManager } from './SyncManager.js';
 
@@ -17,14 +18,14 @@ export interface PushBranchResult {
  * 将当前激活分支推送到远程
  *
  * 规则:
- * 1. 不推送 id='main' 的分支
+ * 1. 不推送根分支（{@link MAIN_BRANCH_ID}）
  * 2. 不修改远程分支的 activated 属性（由 SQL 函数保证）
  * 3. `fromChangeId` 翻译成远端 id 后再上行（见 {@link toRemoteFromChangeId}）
  */
 export async function pushBranch(sm: SyncManager): Promise<PushBranchResult> {
   const branch = await sm.getCurrentBranch();
-  if (!branch || branch.id === 'main') {
-    return { synced: 0, skipped: branch ? ['main'] : [], forkPointPending: false };
+  if (!branch || branch.id === MAIN_BRANCH_ID) {
+    return { synced: 0, skipped: branch ? [MAIN_BRANCH_ID] : [], forkPointPending: false };
   }
 
   const { adapter: remoteAdapter } = await sm.getRemoteRepositories();