@enbox/agent 0.5.13 → 0.5.15

package/src/sync-engine-level.ts

@@ -21,7 +21,9 @@ import { createClosureContext, invalidateClosureCache } from './sync-closure-typ
 import { AgentPermissionsApi } from './permissions-api.js';
 import { DwnInterface } from './types/dwn.js';
 import { isRecordsWrite } from './utils.js';
+import { SyncLinkReconciler } from './sync-link-reconciler.js';
 import { topologicalSort } from './sync-topological-sort.js';
+import { buildLegacyCursorKey, buildLinkId } from './sync-link-id.js';
 import { fetchRemoteMessages, pullMessages, pushMessages } from './sync-messages.js';
 
 export type SyncEngineLevelParams = {
@@ -46,20 +48,16 @@ const MAX_DIFF_DEPTH = 16;
 const BATCHED_DIFF_DEPTH = 8;
 
 /**
-/**
- * Key for the subscription cursor sublevel. Cursors are keyed by
- * `{did}^{dwnUrl}[^{protocol}]` and store an opaque EventLog cursor string.
- */
-const CURSOR_SEPARATOR = '^';
-
-/**
- * Debounce window for push-on-write. When the local EventLog emits events,
- * we batch them and push after this delay to avoid a push per individual write.
+ * Debounce window for batching writes that arrive while a push is in flight.
+ * The first write in a quiet window triggers an immediate push; subsequent
+ * writes arriving during the push are batched and flushed after this delay
+ * once the in-flight push completes.
  */
-const PUSH_DEBOUNCE_MS = 250;
+const PUSH_DEBOUNCE_MS = 100;
 
 /** Tracks a live subscription to a remote DWN for one sync target. */
 type LiveSubscription = {
+  linkKey: string;
   did: string;
   dwnUrl: string;
   delegateDid?: string;
@@ -69,6 +67,7 @@ type LiveSubscription = {
 
 /** Tracks a local EventLog subscription for push-on-write. */
 type LocalSubscription = {
+  linkKey: string;
   did: string;
   dwnUrl: string;
   delegateDid?: string;
@@ -150,6 +149,18 @@ type LinkRuntimeState = {
   inflight: Map<number, InFlightCommit>;
 };
 
+type PushRuntimeState = {
+  did: string;
+  dwnUrl: string;
+  delegateDid?: string;
+  protocol?: string;
+  entries: { cid: string }[];
+  retryCount: number;
+  timer?: ReturnType<typeof setTimeout>;
+  /** True while a push HTTP request is in flight for this link. */
+  flushing?: boolean;
+};
+
 export class SyncEngineLevel implements SyncEngine {
   /**
    * Holds the instance of a `EnboxPlatformAgent` that represents the current execution context for
@@ -170,8 +181,7 @@ export class SyncEngineLevel implements SyncEngine {
 
   /**
    * Durable replication ledger — persists per-link checkpoint state.
-   * Used by live sync to track pull/push progression independently per link.
-   * Poll-mode sync still uses the legacy `getCursor`/`setCursor` path.
+   * Used by live sync to track pull progression per link.
    * Lazily initialized on first use to avoid sublevel() calls on mock dbs.
    */
   private _ledger?: ReplicationLedger;
@@ -211,7 +221,7 @@ export class SyncEngineLevel implements SyncEngine {
    * and bail if it has changed — this prevents stale work from mutating
    * state after teardown or mode switch.
    */
-  private _syncGeneration = 0;
+  private _engineGeneration = 0;
 
   /** Active live pull subscriptions (remote -> local via MessagesSubscribe). */
   private _liveSubscriptions: LiveSubscription[] = [];
@@ -222,17 +232,11 @@ export class SyncEngineLevel implements SyncEngine {
   /** Connectivity state derived from subscription health. */
   private _connectivityState: SyncConnectivityState = 'unknown';
 
-  /** Debounce timer for batched push-on-write. */
-  private _pushDebounceTimer?: ReturnType<typeof setTimeout>;
-
   /** Registered event listeners for observability. */
   private _eventListeners: Set<SyncEventListener> = new Set();
 
-  /** Entry in the pending push queue — a message CID with its local EventLog token. */
-  private _pendingPushCids: Map<string, {
-    did: string; dwnUrl: string; delegateDid?: string; protocol?: string;
-    entries: { cid: string; localToken?: ProgressToken }[];
-  }> = new Map();
+  /** Per-link push runtime: queue, debounce timer, retry state. */
+  private _pushRuntimes: Map<string, PushRuntimeState> = new Map();
 
   /**
    * CIDs recently received via pull subscription, keyed by `cid|dwnUrl` to
@@ -334,11 +338,13 @@ export class SyncEngineLevel implements SyncEngine {
   }
 
   public async clear(): Promise<void> {
+    await this.teardownLiveSync();
     await this._permissionsApi.clear();
     await this._db.clear();
   }
 
   public async close(): Promise<void> {
+    await this.teardownLiveSync();
     await this._db.close();
   }
 
@@ -405,98 +411,61 @@ export class SyncEngineLevel implements SyncEngine {
 
     this._syncLock = true;
     try {
-      // Iterate over all registered identities and their DWN endpoints.
+      // Group targets by remote endpoint so each URL group can be reconciled
+      // concurrently. Within a group, targets are processed sequentially so
+      // that a single network failure skips the rest of that group.
       const syncTargets = await this.getSyncTargets();
-      const errored = new Set<string>();
-      let hadFailure = false;
-
+      const byUrl = new Map<string, typeof syncTargets>();
       for (const target of syncTargets) {
-        const { did, delegateDid, dwnUrl, protocol } = target;
-
-        if (errored.has(dwnUrl)) {
-          continue;
+        let group = byUrl.get(target.dwnUrl);
+        if (!group) {
+          group = [];
+          byUrl.set(target.dwnUrl, group);
         }
+        group.push(target);
+      }
 
-        try {
-          // Phase 1: Compare SMT roots between local and remote.
-          const localRoot = await this.getLocalRoot(did, delegateDid, protocol);
-          const remoteRoot = await this.getRemoteRoot(did, dwnUrl, delegateDid, protocol);
-
-          if (localRoot === remoteRoot) {
-            // Trees are identical — nothing to sync for this target.
-            continue;
-          }
-
-          // Phase 2: Compute the diff in a single round-trip using the
-          // batched 'diff' action.  This replaces the per-node tree walk
-          // that previously required dozens of HTTP requests.
-          const diff = await this.diffWithRemote({
-            did, dwnUrl, delegateDid, protocol,
-          });
+      let groupsSucceeded = 0;
+      let groupsFailed = 0;
 
-          // Phase 3: Pull missing messages (remote has, local doesn't).
-          // The diff response may include inline message data — use it
-          // directly instead of re-fetching via individual MessagesRead calls.
-          if (!direction || direction === 'pull') {
-            if (diff.onlyRemote.length > 0) {
-              // Separate entries into three categories:
-              // 1. Fully prefetched: have message + inline data (or no data needed)
-              // 2. Need data fetch: have message but missing data for RecordsWrite
-              // 3. Need full fetch: no message at all
-              const prefetched: (MessagesSyncDiffEntry & { message: GenericMessage })[] = [];
-              const needsFetchCids: string[] = [];
-
-              for (const entry of diff.onlyRemote) {
-                if (!entry.message) {
-                  // No message at all — need full fetch.
-                  needsFetchCids.push(entry.messageCid);
-                } else if (
-                  entry.message.descriptor.interface === 'Records' &&
-                  entry.message.descriptor.method === 'Write' &&
-                  (entry.message.descriptor as any).dataCid &&
-                  !entry.encodedData
-                ) {
-                  // RecordsWrite with data but data wasn't inlined (too large).
-                  // Need to fetch individually to get the data stream.
-                  needsFetchCids.push(entry.messageCid);
-                } else {
-                  // Fully prefetched (message + data or no data needed).
-                  prefetched.push(entry as MessagesSyncDiffEntry & { message: GenericMessage });
-                }
-              }
-              await this.pullMessages({
-                did, dwnUrl, delegateDid, protocol,
-                messageCids: needsFetchCids,
-                prefetched,
-              });
-            }
+      const results = await Promise.allSettled([...byUrl.entries()].map(async ([dwnUrl, targets]) => {
+        for (const target of targets) {
+          const { did, delegateDid, protocol } = target;
+          try {
+            await this.createLinkReconciler().reconcile({
+              did, dwnUrl, delegateDid, protocol,
+            }, { direction });
+          } catch (error: any) {
+            // Skip remaining targets for this DWN endpoint.
+            groupsFailed++;
+            console.error(`SyncEngineLevel: Error syncing ${did} with ${dwnUrl}`, error);
+            return;
           }
+        }
+        groupsSucceeded++;
+      }));
 
-          // Phase 4: Push missing messages (local has, remote doesn't).
-          if (!direction || direction === 'push') {
-            if (diff.onlyLocal.length > 0) {
-              await this.pushMessages({ did, dwnUrl, delegateDid, protocol, messageCids: diff.onlyLocal });
-            }
-          }
-        } catch (error: any) {
-          // Skip this DWN endpoint for remaining targets and log the real cause.
-          errored.add(dwnUrl);
-          hadFailure = true;
-          console.error(`SyncEngineLevel: Error syncing ${did} with ${dwnUrl}`, error);
+      // Check for unexpected rejections (should not happen given inner try/catch).
+      for (const result of results) {
+        if (result.status === 'rejected') {
+          groupsFailed++;
         }
       }
 
-      // Track consecutive failures for backoff in poll mode.
-      if (hadFailure) {
+      // Track connectivity based on per-group outcomes. If at least one
+      // group succeeded, stay online — partial reachability is still online.
+      if (groupsSucceeded > 0) {
+        this._consecutiveFailures = 0;
+        this._connectivityState = 'online';
+      } else if (groupsFailed > 0) {
         this._consecutiveFailures++;
         if (this._connectivityState === 'online') {
           this._connectivityState = 'offline';
         }
-      } else {
+      } else if (syncTargets.length > 0) {
+        // All targets had matching roots (no reconciliation needed).
         this._consecutiveFailures = 0;
-        if (syncTargets.length > 0) {
-          this._connectivityState = 'online';
-        }
+        this._connectivityState = 'online';
       }
     } finally {
       this._syncLock = false;
@@ -535,6 +504,7 @@ export class SyncEngineLevel implements SyncEngine {
    * and tearing down any live subscriptions.
    */
   public async stopSync(timeout: number = 2000): Promise<void> {
+    this._engineGeneration++;
     let elapsedTimeout = 0;
 
     while (this._syncLock) {
@@ -559,7 +529,9 @@ export class SyncEngineLevel implements SyncEngine {
   // ---------------------------------------------------------------------------
 
   private async startPollSync(intervalMilliseconds: number): Promise<void> {
+    const generation = this._engineGeneration;
     const intervalSync = async (): Promise<void> => {
+      if (this._engineGeneration !== generation) { return; }
       if (this._syncLock) {
         return;
       }
@@ -582,6 +554,7 @@ export class SyncEngineLevel implements SyncEngine {
         ? intervalMilliseconds * backoffMultiplier
         : intervalMilliseconds;
 
+      if (this._engineGeneration !== generation) { return; }
       if (!this._syncIntervalId) {
         this._syncIntervalId = setInterval(intervalSync, effectiveInterval);
       }
@@ -619,8 +592,9 @@ export class SyncEngineLevel implements SyncEngine {
     }
 
     // Step 2: Initialize replication links and open live subscriptions.
+    // Each target's link initialization is independent — process concurrently.
     const syncTargets = await this.getSyncTargets();
-    for (const target of syncTargets) {
+    await Promise.allSettled(syncTargets.map(async (target) => {
       let link: ReplicationLinkState | undefined;
       try {
         // Get or create the link in the durable ledger.
@@ -637,20 +611,34 @@ export class SyncEngineLevel implements SyncEngine {
         });
 
         // Cache the link for fast access by subscription handlers.
-        const linkKey = this.buildCursorKey(target.did, target.dwnUrl, target.protocol);
+        // Use scopeId from the link for consistent runtime identity.
+        const linkKey = this.buildLinkKey(target.did, target.dwnUrl, link.scopeId);
+
+        // One-time migration: if the link has no pull checkpoint, check for
+        // a legacy cursor in the old syncCursors sublevel. The legacy key
+        // used protocol, not scopeId, so we must build it the old way.
+        if (!link.pull.contiguousAppliedToken) {
+          const legacyKey = buildLegacyCursorKey(target.did, target.dwnUrl, target.protocol);
+          const legacyCursor = await this.getCursor(legacyKey);
+          if (legacyCursor) {
+            ReplicationLedger.resetCheckpoint(link.pull, legacyCursor);
+            await this.ledger.saveLink(link);
+            await this.deleteLegacyCursor(legacyKey);
+          }
+        }
+
         this._activeLinks.set(linkKey, link);
 
         // Open subscriptions — only transition to live if both succeed.
         // If pull succeeds but push fails, close the pull subscription to
         // avoid a resource leak with inconsistent state.
-        await this.openLivePullSubscription(target);
+        const targetWithKey = { ...target, linkKey };
+        await this.openLivePullSubscription(targetWithKey);
         try {
-          await this.openLocalPushSubscription(target);
+          await this.openLocalPushSubscription(targetWithKey);
         } catch (pushError) {
           // Close the already-opened pull subscription.
-          const pullSub = this._liveSubscriptions.find(
-            s => s.did === target.did && s.dwnUrl === target.dwnUrl && s.protocol === target.protocol
-          );
+          const pullSub = this._liveSubscriptions.find((s) => s.linkKey === linkKey);
           if (pullSub) {
             try { await pullSub.close(); } catch { /* best effort */ }
             this._liveSubscriptions = this._liveSubscriptions.filter(s => s !== pullSub);
@@ -660,8 +648,16 @@ export class SyncEngineLevel implements SyncEngine {
 
         this.emitEvent({ type: 'link:status-change', tenantDid: target.did, remoteEndpoint: target.dwnUrl, protocol: target.protocol, from: 'initializing', to: 'live' });
         await this.ledger.setStatus(link!, 'live');
+
+        // If the link was marked dirty in a previous session, schedule
+        // immediate reconciliation now that subscriptions are open.
+        if (link!.needsReconcile) {
+          this.scheduleReconcile(linkKey, 1000);
+        }
       } catch (error: any) {
-        const linkKey = this.buildCursorKey(target.did, target.dwnUrl, target.protocol);
+        const linkKey = link
+          ? this.buildLinkKey(target.did, target.dwnUrl, link.scopeId)
+          : buildLegacyCursorKey(target.did, target.dwnUrl, target.protocol);
 
         // Detect ProgressGap (410) — the cursor is stale, link needs SMT repair.
         if ((error as any).isProgressGap && link) {
@@ -671,7 +667,7 @@ export class SyncEngineLevel implements SyncEngine {
           await this.transitionToRepairing(linkKey, link, {
             resumeToken: gapInfo?.latestAvailable,
           });
-          continue;
+          return;
         }
 
         console.error(`SyncEngineLevel: Failed to open live subscription for ${target.did} -> ${target.dwnUrl}`, error);
@@ -686,7 +682,7 @@ export class SyncEngineLevel implements SyncEngine {
           this._connectivityState = 'unknown';
         }
       }
-    }
+    }));
 
     // Step 3: Schedule infrequent SMT integrity check.
     const integrityCheck = async (): Promise<void> => {
@@ -833,12 +829,12 @@ export class SyncEngineLevel implements SyncEngine {
     const backoff = SyncEngineLevel.REPAIR_BACKOFF_MS;
     const delayMs = backoff[Math.min(attempts - 1, backoff.length - 1)];
 
-    const timerGeneration = this._syncGeneration;
+    const timerGeneration = this._engineGeneration;
     const timer = setTimeout(async (): Promise<void> => {
       this._repairRetryTimers.delete(linkKey);
 
       // Bail if teardown occurred since this timer was scheduled.
-      if (this._syncGeneration !== timerGeneration) { return; }
+      if (this._engineGeneration !== timerGeneration) { return; }
 
       // Verify link still exists and is still repairing.
       const currentLink = this._activeLinks.get(linkKey);
@@ -868,6 +864,15 @@ export class SyncEngineLevel implements SyncEngine {
 
     const promise = this.doRepairLink(linkKey).finally(() => {
       this._activeRepairs.delete(linkKey);
+
+      // Post-repair reconcile: if doRepairLink() marked needsReconcile
+      // (to close the gap between diff snapshot and new push subscription),
+      // schedule reconciliation NOW — after _activeRepairs is cleared so
+      // scheduleReconcile() won't skip it.
+      const link = this._activeLinks.get(linkKey);
+      if (link?.needsReconcile && link.status === 'live') {
+        this.scheduleReconcile(linkKey, 500);
+      }
     });
     this._activeRepairs.set(linkKey, promise);
     return promise;
@@ -886,7 +891,7 @@ export class SyncEngineLevel implements SyncEngine {
     // Capture the sync generation at repair start. If teardown occurs during
     // any await, the generation will have incremented and we bail before
     // mutating state — preventing the race where repair continues after teardown.
-    const generation = this._syncGeneration;
+    const generation = this._engineGeneration;
 
     const { tenantDid: did, remoteEndpoint: dwnUrl, delegateDid, protocol } = link;
 
@@ -897,7 +902,7 @@ export class SyncEngineLevel implements SyncEngine {
     // Step 1: Close existing subscriptions FIRST to stop old events from
     // mutating local state while repair runs.
     await this.closeLinkSubscriptions(link);
-    if (this._syncGeneration !== generation) { return; } // Teardown occurred.
+    if (this._engineGeneration !== generation) { return; } // Teardown occurred.
 
     // Step 2: Clear runtime ordinals immediately — stale state must not
     // persist across repair attempts (successful or failed).
@@ -908,72 +913,64 @@ export class SyncEngineLevel implements SyncEngine {
 
     try {
       // Step 3: Run SMT reconciliation for this link.
-      const localRoot = await this.getLocalRoot(did, delegateDid, protocol);
-      if (this._syncGeneration !== generation) { return; }
-      const remoteRoot = await this.getRemoteRoot(did, dwnUrl, delegateDid, protocol);
-      if (this._syncGeneration !== generation) { return; }
-
-      if (localRoot !== remoteRoot) {
-        const diff = await this.diffWithRemote({ did, dwnUrl, delegateDid, protocol });
-        if (this._syncGeneration !== generation) { return; }
-
-        if (diff.onlyRemote.length > 0) {
-          const prefetched: (MessagesSyncDiffEntry & { message: GenericMessage })[] = [];
-          const needsFetchCids: string[] = [];
-          for (const entry of diff.onlyRemote) {
-            if (!entry.message || (entry.message.descriptor.interface === 'Records' &&
-                entry.message.descriptor.method === 'Write' &&
-                (entry.message.descriptor as any).dataCid && !entry.encodedData)) {
-              needsFetchCids.push(entry.messageCid);
-            } else {
-              prefetched.push(entry as MessagesSyncDiffEntry & { message: GenericMessage });
-            }
-          }
-          await this.pullMessages({ did, dwnUrl, delegateDid, protocol, messageCids: needsFetchCids, prefetched });
-          if (this._syncGeneration !== generation) { return; }
-        }
-
-        if (diff.onlyLocal.length > 0) {
-          await this.pushMessages({ did, dwnUrl, delegateDid, protocol, messageCids: diff.onlyLocal });
-          if (this._syncGeneration !== generation) { return; }
-        }
-      }
+      const reconcileOutcome = await this.createLinkReconciler(
+        () => this._engineGeneration === generation
+      ).reconcile({ did, dwnUrl, delegateDid, protocol });
+      if (reconcileOutcome.aborted) { return; }
 
-      // Step 4: Determine the post-repair resume token.
+      // Step 4: Determine the post-repair pull resume token.
       // - If repair was triggered by ProgressGap, use the stored resumeToken
       //   (from gapInfo.latestAvailable) so the reopened subscription replays
       //   from a valid boundary, closing the race window between SMT and resubscribe.
       // - Otherwise, use the existing contiguousAppliedToken if still valid.
-      // - Push checkpoint is NOT reset during repair: push frontier tracks what
-      //   the local EventLog has delivered to the remote. SMT repair handles
-      //   pull-side convergence; push-side convergence is handled by the diff's
-      //   onlyLocal push. The push checkpoint remains the local authority.
+      // Push is opportunistic — no push checkpoint to reset.
       const repairCtx = this._repairContext.get(linkKey);
       const resumeToken = repairCtx?.resumeToken ?? link.pull.contiguousAppliedToken;
       ReplicationLedger.resetCheckpoint(link.pull, resumeToken);
       await this.ledger.saveLink(link);
-      if (this._syncGeneration !== generation) { return; }
+      if (this._engineGeneration !== generation) { return; }
+
+      // Step 5: Reopen subscriptions.
+      // Mark needsReconcile BEFORE reopening — local push starts from "now",
+      // so any writes between the diff snapshot (step 3) and the new push
+      // subscription are invisible to both mechanisms. A short post-reopen
+      // reconcile will close this gap (cheap: SMT root comparison short-circuits
+      // if roots already match).
+      link.needsReconcile = true;
+      await this.ledger.saveLink(link);
+      if (this._engineGeneration !== generation) { return; }
 
-      // Step 5: Reopen subscriptions with the repaired checkpoints.
-      const target = { did, dwnUrl, delegateDid, protocol };
-      await this.openLivePullSubscription(target);
-      if (this._syncGeneration !== generation) { return; }
+      const target = { did, dwnUrl, delegateDid, protocol, linkKey };
       try {
-        await this.openLocalPushSubscription({
-          ...target,
-          pushCursor: link.push.contiguousAppliedToken,
-        });
+        await this.openLivePullSubscription(target);
+      } catch (pullErr: any) {
+        if (pullErr.isProgressGap) {
+          console.warn(`SyncEngineLevel: Stale pull resume token for ${did} -> ${dwnUrl}, resetting to start fresh`);
+          ReplicationLedger.resetCheckpoint(link.pull);
+          await this.ledger.saveLink(link);
+          if (this._engineGeneration !== generation) { return; }
+          await this.openLivePullSubscription(target);
+        } else {
+          throw pullErr;
+        }
+      }
+      if (this._engineGeneration !== generation) { return; }
+      try {
+        await this.openLocalPushSubscription(target);
       } catch (pushError) {
-        const pullSub = this._liveSubscriptions.find(
-          s => s.did === did && s.dwnUrl === dwnUrl && s.protocol === protocol
-        );
+        const pullSub = this._liveSubscriptions.find((s) => s.linkKey === linkKey);
         if (pullSub) {
           try { await pullSub.close(); } catch { /* best effort */ }
           this._liveSubscriptions = this._liveSubscriptions.filter(s => s !== pullSub);
         }
         throw pushError;
       }
-      if (this._syncGeneration !== generation) { return; }
+      if (this._engineGeneration !== generation) { return; }
+
+      // Note: post-repair reconcile to close the repair-window gap is
+      // scheduled by repairLink() AFTER _activeRepairs is cleared — not
+      // here, because scheduleReconcile() would skip it while _activeRepairs
+      // still contains this link.
 
       // Step 6: Clean up repair context and transition to live.
       this._repairContext.delete(linkKey);
@@ -991,7 +988,7 @@ export class SyncEngineLevel implements SyncEngine {
 
     } catch (error: any) {
       // If teardown occurred during repair, don't retry or enter degraded_poll.
-      if (this._syncGeneration !== generation) { return; }
+      if (this._engineGeneration !== generation) { return; }
 
       console.error(`SyncEngineLevel: Repair failed for ${did} -> ${dwnUrl} (attempt ${attempts})`, error);
       this.emitEvent({ type: 'repair:failed', tenantDid: did, remoteEndpoint: dwnUrl, protocol, attempt: attempts, error: String(error.message ?? error) });
@@ -1011,21 +1008,18 @@ export class SyncEngineLevel implements SyncEngine {
    * Close pull and push subscriptions for a specific link.
    */
   private async closeLinkSubscriptions(link: ReplicationLinkState): Promise<void> {
-    const { tenantDid: did, remoteEndpoint: dwnUrl, protocol } = link;
+    const { tenantDid: did, remoteEndpoint: dwnUrl } = link;
+    const linkKey = this.buildLinkKey(did, dwnUrl, link.scopeId);
 
     // Close pull subscription.
-    const pullSub = this._liveSubscriptions.find(
-      s => s.did === did && s.dwnUrl === dwnUrl && s.protocol === protocol
-    );
+    const pullSub = this._liveSubscriptions.find((s) => s.linkKey === linkKey);
     if (pullSub) {
       try { await pullSub.close(); } catch { /* best effort */ }
       this._liveSubscriptions = this._liveSubscriptions.filter(s => s !== pullSub);
     }
 
     // Close local push subscription.
-    const pushSub = this._localSubscriptions.find(
-      s => s.did === did && s.dwnUrl === dwnUrl && s.protocol === protocol
-    );
+    const pushSub = this._localSubscriptions.find((s) => s.linkKey === linkKey);
     if (pushSub) {
       try { await pushSub.close(); } catch { /* best effort */ }
       this._localSubscriptions = this._localSubscriptions.filter(s => s !== pushSub);
@@ -1057,10 +1051,10 @@ export class SyncEngineLevel implements SyncEngine {
     const jitter = Math.floor(Math.random() * 15_000);
     const interval = baseInterval + jitter;
 
-    const pollGeneration = this._syncGeneration;
+    const pollGeneration = this._engineGeneration;
     const timer = setInterval(async (): Promise<void> => {
       // Bail if teardown occurred since this timer was created.
-      if (this._syncGeneration !== pollGeneration) {
+      if (this._engineGeneration !== pollGeneration) {
         clearInterval(timer);
         this._degradedPollTimers.delete(linkKey);
         return;
@@ -1105,16 +1099,15 @@ export class SyncEngineLevel implements SyncEngine {
     // Increment generation to invalidate all in-flight async operations
     // (repairs, retry timers, degraded-poll ticks). Any async work that
     // captured the previous generation will bail on its next checkpoint.
-    this._syncGeneration++;
+    this._engineGeneration++;
 
-    // Clear the push debounce timer.
-    if (this._pushDebounceTimer) {
-      clearTimeout(this._pushDebounceTimer);
-      this._pushDebounceTimer = undefined;
+    // Clear per-link push runtime state.
+    for (const pushRuntime of this._pushRuntimes.values()) {
+      if (pushRuntime.timer) {
+        clearTimeout(pushRuntime.timer);
+      }
     }
-
-    // Flush any pending push CIDs.
-    this._pendingPushCids.clear();
+    this._pushRuntimes.clear();
 
     // Close all live pull subscriptions.
     for (const sub of this._liveSubscriptions) {
@@ -1149,8 +1142,16 @@ export class SyncEngineLevel implements SyncEngine {
     this._repairRetryTimers.clear();
     this._repairContext.clear();
 
+    // Clear reconcile timers and in-flight operations.
+    for (const timer of this._reconcileTimers.values()) {
+      clearTimeout(timer);
+    }
+    this._reconcileTimers.clear();
+    this._reconcileInFlight.clear();
+
     // Clear closure evaluation contexts.
     this._closureContexts.clear();
+    this._recentlyPulledCids.clear();
 
     // Clear the in-memory link and runtime state.
     this._activeLinks.clear();
@@ -1167,13 +1168,15 @@ export class SyncEngineLevel implements SyncEngine {
    */
   private async openLivePullSubscription(target: {
     did: string; dwnUrl: string; delegateDid?: string; protocol?: string;
+    linkKey: string;
   }): Promise<void> {
     const { did, delegateDid, dwnUrl, protocol } = target;
 
-    // Resolve the cursor from the link's pull checkpoint (preferred) or legacy storage.
-    const cursorKey = this.buildCursorKey(did, dwnUrl, protocol);
+    // Resolve the cursor from the link's durable pull checkpoint.
+    // Legacy syncCursors migration happens at link load time in startLiveSync().
+    const cursorKey = target.linkKey;
     const link = this._activeLinks.get(cursorKey);
-    let cursor = link?.pull.contiguousAppliedToken ?? await this.getCursor(cursorKey);
+    let cursor = link?.pull.contiguousAppliedToken;
 
     // Guard against corrupted tokens with empty fields — these would fail
     // MessagesSubscribe JSON schema validation (minLength: 1). Discard and
@@ -1217,11 +1220,17 @@ export class SyncEngineLevel implements SyncEngine {
       permissionGrantId = grant.grant.id;
     }
 
+    const handlerGeneration = this._engineGeneration;
+
     // Define the subscription handler that processes incoming events.
     // NOTE: The WebSocket client fires handlers without awaiting (fire-and-forget),
     // so multiple handlers can be in-flight concurrently. The ordinal tracker
     // ensures the checkpoint advances only when all earlier deliveries are committed.
     const subscriptionHandler = async (subMessage: SubscriptionMessage): Promise<void> => {
+      if (this._engineGeneration !== handlerGeneration) {
+        return;
+      }
+
       if (subMessage.type === 'eose') {
         // End-of-stored-events — catch-up complete.
         if (link) {
@@ -1243,8 +1252,6 @@ export class SyncEngineLevel implements SyncEngine {
           // far as the contiguous drain reaches.
           this.drainCommittedPull(cursorKey);
           await this.ledger.saveLink(link);
-        } else {
-          await this.setCursor(cursorKey, subMessage.cursor);
         }
         // Transport is reachable — set connectivity to online.
         if (link) {
@@ -1253,6 +1260,10 @@ export class SyncEngineLevel implements SyncEngine {
           if (prevEoseConnectivity !== 'online') {
             this.emitEvent({ type: 'link:connectivity-change', tenantDid: did, remoteEndpoint: dwnUrl, protocol, from: prevEoseConnectivity, to: 'online' });
           }
+          // If the link was marked dirty, schedule reconciliation now that it's healthy.
+          if (link.needsReconcile) {
+            this.scheduleReconcile(cursorKey, 500);
+          }
         } else {
           this._connectivityState = 'online';
         }
@@ -1399,9 +1410,6 @@ export class SyncEngineLevel implements SyncEngine {
               console.warn(`SyncEngineLevel: Pull in-flight overflow for ${did} -> ${dwnUrl}, transitioning to repairing`);
               await this.transitionToRepairing(cursorKey, link);
             }
-          } else if (!link) {
-            // Legacy path: no link available, use simple cursor persistence.
-            await this.setCursor(cursorKey, subMessage.cursor);
           }
         } catch (error: any) {
           console.error(`SyncEngineLevel: Error processing live-pull event for ${did}`, error);
@@ -1480,15 +1488,16 @@ export class SyncEngineLevel implements SyncEngine {
     }
 
     this._liveSubscriptions.push({
+      linkKey : cursorKey,
       did,
       dwnUrl,
       delegateDid,
       protocol,
-      close: async (): Promise<void> => { await reply.subscription!.close(); },
+      close   : async (): Promise<void> => { await reply.subscription!.close(); },
     });
 
     // Set per-link connectivity to online after successful subscription setup.
-    const pullLink = this._activeLinks.get(this.buildCursorKey(did, dwnUrl, protocol));
+    const pullLink = this._activeLinks.get(cursorKey);
     if (pullLink) {
       const prevPullConnectivity = pullLink.connectivity;
       pullLink.connectivity = 'online';
@@ -1508,23 +1517,10 @@ export class SyncEngineLevel implements SyncEngine {
    */
   private async openLocalPushSubscription(target: {
     did: string; dwnUrl: string; delegateDid?: string; protocol?: string;
-    pushCursor?: ProgressToken;
+    linkKey: string;
   }): Promise<void> {
     const { did, delegateDid, dwnUrl, protocol } = target;
 
-    // Guard against corrupted push cursors — same validation as the pull side.
-    let pushCursor = target.pushCursor;
-    if (pushCursor && (!pushCursor.streamId || !pushCursor.messageCid || !pushCursor.epoch || !pushCursor.position)) {
-      console.warn(`SyncEngineLevel: Discarding stored push cursor with empty field(s) for ${did} -> ${dwnUrl}`);
-      pushCursor = undefined;
-      const cursorKey = this.buildCursorKey(did, dwnUrl, protocol);
-      const link = this._activeLinks.get(cursorKey);
-      if (link) {
-        ReplicationLedger.resetCheckpoint(link.push);
-        await this.ledger.saveLink(link);
-      }
-    }
-
     // Build filters scoped to the protocol (if any).
     const filters = protocol ? [{ protocol }] : [];
 
@@ -1541,41 +1537,28 @@ export class SyncEngineLevel implements SyncEngine {
       permissionGrantId = grant.grant.id;
     }
 
+    const handlerGeneration = this._engineGeneration;
+
     // Subscribe to the local DWN's EventLog.
     const subscriptionHandler = async (subMessage: SubscriptionMessage): Promise<void> => {
+      if (this._engineGeneration !== handlerGeneration) {
+        return;
+      }
+
       if (subMessage.type !== 'event') {
         return;
       }
 
-      // Subset scope filtering for push: only push events that match the
-      // link's scope prefixes. Events outside the scope are not our responsibility.
-      // Skipped events MUST advance the push checkpoint to prevent infinite
-      // replay after repair/reconnect (same reason as the pull side).
-      const pushLink = this._activeLinks.get(this.buildCursorKey(did, dwnUrl, protocol));
+      // Subset scope filtering: only push events that match the link's
+      // scope prefixes. Events outside the scope are not our responsibility.
+      const pushLinkKey = target.linkKey;
+      const pushLink = this._activeLinks.get(pushLinkKey);
       if (pushLink && !isEventInScope(subMessage.event.message, pushLink.scope)) {
-        // Guard: only mutate durable state when the link is live/initializing.
-        // During repair/degraded_poll, orchestration owns checkpoint progression.
-        if (pushLink.status !== 'live' && pushLink.status !== 'initializing') {
-          return;
-        }
-
-        // Validate token domain before committing — a stream/epoch mismatch
-        // on the local EventLog should trigger repair, not silently overwrite.
-        if (!ReplicationLedger.validateTokenDomain(pushLink.push, subMessage.cursor)) {
-          await this.transitionToRepairing(
-            this.buildCursorKey(did, dwnUrl, protocol), pushLink
-          );
-          return;
-        }
-
-        ReplicationLedger.setReceivedToken(pushLink.push, subMessage.cursor);
-        ReplicationLedger.commitContiguousToken(pushLink.push, subMessage.cursor);
-        await this.ledger.saveLink(pushLink);
         return;
       }
 
       // Accumulate the message CID for a debounced push.
-      const targetKey = this.buildCursorKey(did, dwnUrl, protocol);
+      const targetKey = pushLinkKey;
       const cid = await Message.getCid(subMessage.event.message);
       if (cid === undefined) {
         return;
@@ -1588,32 +1571,28 @@ export class SyncEngineLevel implements SyncEngine {
         return;
       }
 
-      let pending = this._pendingPushCids.get(targetKey);
-      if (!pending) {
-        pending = { did, dwnUrl, delegateDid, protocol, entries: [] };
-        this._pendingPushCids.set(targetKey, pending);
-      }
-      pending.entries.push({ cid, localToken: subMessage.cursor });
+      const pushRuntime = this.getOrCreatePushRuntime(targetKey, {
+        did, dwnUrl, delegateDid, protocol,
+      });
+      pushRuntime.entries.push({ cid });
 
-      // Debounce the push.
-      if (this._pushDebounceTimer) {
-        clearTimeout(this._pushDebounceTimer);
+      // Immediate-first: if no push is in flight and no batch timer is
+      // pending, push immediately. Otherwise, the pending batch timer
+      // or the post-flush drain will pick up the new entry.
+      if (!pushRuntime.flushing && !pushRuntime.timer) {
+        void this.flushPendingPushesForLink(targetKey);
       }
-      this._pushDebounceTimer = setTimeout((): void => {
-        void this.flushPendingPushes();
-      }, PUSH_DEBOUNCE_MS);
     };
 
-    // Process the local subscription request.
-    // When a push cursor is provided (e.g., after repair), the local subscription
-    // replays events from that position, closing the race window where local
-    // writes during repair would otherwise be missed by push-on-write.
+    // Subscribe to the local DWN EventLog from "now" — opportunistic push
+    // does not replay from a stored cursor. Any writes missed during outages
+    // are recovered by the post-repair reconciliation path.
     const response = await this.agent.dwn.processRequest({
       author              : did,
       target              : did,
       messageType         : DwnInterface.MessagesSubscribe,
       granteeDid          : delegateDid,
-      messageParams       : { filters, permissionGrantId, cursor: pushCursor },
+      messageParams       : { filters, permissionGrantId },
       subscriptionHandler : subscriptionHandler as any,
     });
 
@@ -1623,11 +1602,12 @@ export class SyncEngineLevel implements SyncEngine {
     }
 
     this._localSubscriptions.push({
+      linkKey : target.linkKey ?? buildLegacyCursorKey(did, dwnUrl, protocol),
       did,
       dwnUrl,
       delegateDid,
       protocol,
-      close: async (): Promise<void> => { await reply.subscription!.close(); },
+      close   : async (): Promise<void> => { await reply.subscription!.close(); },
     });
   }
 
@@ -1635,112 +1615,261 @@ export class SyncEngineLevel implements SyncEngine {
    * Flushes accumulated push CIDs to remote DWNs.
    */
   private async flushPendingPushes(): Promise<void> {
-    this._pushDebounceTimer = undefined;
+    await Promise.all([...this._pushRuntimes.keys()].map(async (linkKey) => {
+      await this.flushPendingPushesForLink(linkKey);
+    }));
+  }
+
+  private async flushPendingPushesForLink(linkKey: string): Promise<void> {
+    const pushRuntime = this._pushRuntimes.get(linkKey);
+    if (!pushRuntime) {
+      return;
+    }
 
-    const batches = [...this._pendingPushCids.entries()];
-    this._pendingPushCids.clear();
+    const { did, dwnUrl, delegateDid, protocol, entries: pushEntries, retryCount } = pushRuntime;
+    pushRuntime.entries = [];
 
-    // Push to all endpoints in parallel — each target is independent.
-    await Promise.all(batches.map(async ([targetKey, pending]) => {
-      const { did, dwnUrl, delegateDid, protocol, entries: pushEntries } = pending;
-      if (pushEntries.length === 0) {
-        return;
+    if (pushEntries.length === 0) {
+      if (!pushRuntime.timer && !pushRuntime.flushing && retryCount === 0) {
+        this._pushRuntimes.delete(linkKey);
       }
+      return;
+    }
 
-      const cids = pushEntries.map(e => e.cid);
+    const cids = pushEntries.map((entry) => entry.cid);
+    pushRuntime.flushing = true;
 
-      try {
-        const result = await pushMessages({
+    try {
+      const result = await pushMessages({
+        did, dwnUrl, delegateDid, protocol,
+        messageCids    : cids,
+        agent          : this.agent,
+        permissionsApi : this._permissionsApi,
+      });
+
+      if (result.failed.length > 0) {
+        const failedSet = new Set(result.failed);
+        const failedEntries = pushEntries.filter((entry) => failedSet.has(entry.cid));
+        this.requeueOrReconcile(linkKey, {
           did, dwnUrl, delegateDid, protocol,
-          messageCids    : cids,
-          agent          : this.agent,
-          permissionsApi : this._permissionsApi,
+          entries    : failedEntries,
+          retryCount : retryCount + 1,
         });
-
-        // Advance the push checkpoint for successfully pushed entries.
-        // Push is sequential (single batch, in-order processing) so we can
-        // commit directly without ordinal tracking — there's no concurrent
-        // completion to reorder.
-        const link = this._activeLinks.get(targetKey);
-        if (link) {
-          const succeededSet = new Set(result.succeeded);
-          // Track highest contiguous success: if a CID fails, we stop advancing.
-          let hitFailure = false;
-          for (const entry of pushEntries) {
-            if (hitFailure) { break; }
-            if (succeededSet.has(entry.cid) && entry.localToken) {
-              if (!ReplicationLedger.validateTokenDomain(link.push, entry.localToken)) {
-                console.warn(`SyncEngineLevel: Push checkpoint domain mismatch for ${did} -> ${dwnUrl}, transitioning to repairing`);
-                await this.transitionToRepairing(targetKey, link);
-                break;
-              }
-              ReplicationLedger.setReceivedToken(link.push, entry.localToken);
-              ReplicationLedger.commitContiguousToken(link.push, entry.localToken);
-            } else {
-              // This CID failed or had no token — stop advancing.
-              hitFailure = true;
-            }
-          }
-          await this.ledger.saveLink(link);
+      } else {
+        // Successful push — reset retry count so subsequent unrelated
+        // batches on this link start with a fresh budget.
+        pushRuntime.retryCount = 0;
+        if (!pushRuntime.timer && pushRuntime.entries.length === 0) {
+          this._pushRuntimes.delete(linkKey);
         }
+      }
+    } catch (error: any) {
+      console.error(`SyncEngineLevel: Push batch failed for ${did} -> ${dwnUrl}`, error);
+      this.requeueOrReconcile(linkKey, {
+        did, dwnUrl, delegateDid, protocol,
+        entries    : pushEntries,
+        retryCount : retryCount + 1,
+      });
+    } finally {
+      pushRuntime.flushing = false;
+
+      // If new entries accumulated while this push was in flight, schedule
+      // a short drain to flush them. This gives a brief batching window
+      // for burst writes while keeping single-write latency low.
+      const rt = this._pushRuntimes.get(linkKey);
+      if (rt && rt.entries.length > 0 && !rt.timer) {
+        rt.timer = setTimeout((): void => {
+          rt.timer = undefined;
+          void this.flushPendingPushesForLink(linkKey);
+        }, PUSH_DEBOUNCE_MS);
+      }
+    }
+  }
 
-        // Re-queue only TRANSIENT failures for retry. Permanent failures (400/401/403)
-        // are dropped — they will never succeed regardless of retry.
-        if (result.failed.length > 0) {
-          console.error(
-            `SyncEngineLevel: Push-on-write failed for ${did} -> ${dwnUrl}: ` +
-            `${result.failed.length} transient failures of ${cids.length} messages`
-          );
-          const failedSet = new Set(result.failed);
-          const failedEntries = pushEntries.filter(e => failedSet.has(e.cid));
-          let requeued = this._pendingPushCids.get(targetKey);
-          if (!requeued) {
-            requeued = { did, dwnUrl, delegateDid, protocol, entries: [] };
-            this._pendingPushCids.set(targetKey, requeued);
-          }
-          requeued.entries.push(...failedEntries);
+  /** Push retry backoff schedule: immediate, 250ms, 1s, 2s, then give up. */
+  private static readonly PUSH_RETRY_BACKOFF_MS = [0, 250, 1000, 2000];
 
-          // Schedule a retry after a short delay.
-          if (!this._pushDebounceTimer) {
-            this._pushDebounceTimer = setTimeout((): void => {
-              void this.flushPendingPushes();
-            }, PUSH_DEBOUNCE_MS * 4);
-          }
-        }
-        // Permanent failures are logged by pushMessages but NOT re-queued.
-        // They will be rediscovered by the next SMT integrity check if the
-        // local/remote state has changed, but won't spin in a retry loop.
-      } catch (error: any) {
-        // Truly unexpected error (not per-message failure). Re-queue entire
-        // batch so entries aren't silently dropped from the debounce queue.
-        console.error(`SyncEngineLevel: Push-on-write failed for ${did} -> ${dwnUrl}`, error);
-        let requeued = this._pendingPushCids.get(targetKey);
-        if (!requeued) {
-          requeued = { did, dwnUrl, delegateDid, protocol, entries: [] };
-          this._pendingPushCids.set(targetKey, requeued);
-        }
-        requeued.entries.push(...pushEntries);
+  /**
+   * Re-queues a failed push batch for retry, or marks the link
+   * `needsReconcile` if retries are exhausted. Bounded to prevent
+   * infinite retry loops.
+   */
+  private requeueOrReconcile(targetKey: string, pending: {
+    did: string; dwnUrl: string; delegateDid?: string; protocol?: string;
+    entries: { cid: string }[];
+    retryCount: number;
+  }): void {
+    const maxRetries = SyncEngineLevel.PUSH_RETRY_BACKOFF_MS.length;
+    const pushRuntime = this.getOrCreatePushRuntime(targetKey, pending);
+
+    if (pending.retryCount >= maxRetries) {
+      // Retry budget exhausted — mark link dirty for reconciliation.
+      if (pushRuntime.timer) {
+        clearTimeout(pushRuntime.timer);
+      }
+      this._pushRuntimes.delete(targetKey);
+      const link = this._activeLinks.get(targetKey);
+      if (link && !link.needsReconcile) {
+        link.needsReconcile = true;
+        void this.ledger.saveLink(link).then(() => {
+          this.emitEvent({ type: 'reconcile:needed', tenantDid: pending.did, remoteEndpoint: pending.dwnUrl, protocol: pending.protocol, reason: 'push-retry-exhausted' });
+          this.scheduleReconcile(targetKey);
+        });
+      }
+      return;
+    }
 
-        if (!this._pushDebounceTimer) {
-          this._pushDebounceTimer = setTimeout((): void => {
-            void this.flushPendingPushes();
-          }, PUSH_DEBOUNCE_MS * 4);
-        }
+    pushRuntime.entries.push(...pending.entries);
+    pushRuntime.retryCount = pending.retryCount;
+    const delayMs = SyncEngineLevel.PUSH_RETRY_BACKOFF_MS[pending.retryCount] ?? 2000;
+    if (pushRuntime.timer) {
+      clearTimeout(pushRuntime.timer);
+    }
+    pushRuntime.timer = setTimeout((): void => {
+      pushRuntime.timer = undefined;
+      void this.flushPendingPushesForLink(targetKey);
+    }, delayMs);
+  }
+
+  private createLinkReconciler(shouldContinue?: () => boolean): SyncLinkReconciler {
+    return new SyncLinkReconciler({
+      getLocalRoot   : async (did, delegateDid, protocol) => this.getLocalRoot(did, delegateDid, protocol),
+      getRemoteRoot  : async (did, dwnUrl, delegateDid, protocol) => this.getRemoteRoot(did, dwnUrl, delegateDid, protocol),
+      diffWithRemote : async (target) => this.diffWithRemote(target),
+      pullMessages   : async (params) => this.pullMessages(params),
+      pushMessages   : async (params) => this.pushMessages(params),
+      shouldContinue,
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Per-link reconciliation
+  // ---------------------------------------------------------------------------
+
+  /** Active reconcile timers, keyed by link key. */
+  private _reconcileTimers: Map<string, ReturnType<typeof setTimeout>> = new Map();
+
+  /** Active reconcile operations, keyed by link key (dedup). */
+  private _reconcileInFlight: Map<string, Promise<void>> = new Map();
+
+  /**
+   * Schedule a per-link reconciliation after a short debounce. Coalesces
+   * repeated requests for the same link.
+   */
+  private scheduleReconcile(linkKey: string, delayMs: number = 1500): void {
+    if (this._reconcileTimers.has(linkKey)) { return; }
+    if (this._reconcileInFlight.has(linkKey)) { return; }
+    if (this._activeRepairs.has(linkKey)) { return; }
+
+    const generation = this._engineGeneration;
+    const timer = setTimeout((): void => {
+      this._reconcileTimers.delete(linkKey);
+      if (this._engineGeneration !== generation) { return; }
+      void this.reconcileLink(linkKey);
+    }, delayMs);
+    this._reconcileTimers.set(linkKey, timer);
+  }
+
+  /**
+   * Run SMT reconciliation for a single link. Deduplicates concurrent calls.
+   * On success, clears `needsReconcile`. On failure, schedules retry.
+   */
+  private async reconcileLink(linkKey: string): Promise<void> {
+    const existing = this._reconcileInFlight.get(linkKey);
+    if (existing) { return existing; }
+
+    const promise = this.doReconcileLink(linkKey).finally(() => {
+      this._reconcileInFlight.delete(linkKey);
+    });
+    this._reconcileInFlight.set(linkKey, promise);
+    return promise;
+  }
+
+  /**
+   * Internal reconciliation implementation for a single link. Runs the
+   * same SMT diff + pull/push that `sync()` does, but scoped to one link.
+   */
+  private async doReconcileLink(linkKey: string): Promise<void> {
+    const link = this._activeLinks.get(linkKey);
+    if (!link) { return; }
+
+    // Only reconcile live links — repairing/degraded links have their own
+    // recovery path. Reconciling during repair would race with SMT diff.
+    if (link.status !== 'live') {
+      return;
+    }
+
+    // Skip if a repair is in progress for this link.
+    if (this._activeRepairs.has(linkKey)) {
+      return;
+    }
+
+    const generation = this._engineGeneration;
+    const { tenantDid: did, remoteEndpoint: dwnUrl, delegateDid, protocol } = link;
+
+    try {
+      const reconcileOutcome = await this.createLinkReconciler(
+        () => this._engineGeneration === generation
+      ).reconcile({ did, dwnUrl, delegateDid, protocol }, { verifyConvergence: true });
+      if (reconcileOutcome.aborted) { return; }
+
+      if (reconcileOutcome.converged) {
+        await this.ledger.clearNeedsReconcile(link);
+        this.emitEvent({ type: 'reconcile:completed', tenantDid: did, remoteEndpoint: dwnUrl, protocol });
+      } else {
+        // Roots still differ — retry after a delay. This can happen when
+        // pushMessages() had permanent failures, pullMessages() partially
+        // failed, or new writes arrived during reconciliation.
+        this.scheduleReconcile(linkKey, 5000);
       }
-    }));
+    } catch (error: any) {
+      console.error(`SyncEngineLevel: Reconciliation failed for ${did} -> ${dwnUrl}`, error);
+      // Schedule retry with longer delay.
+      this.scheduleReconcile(linkKey, 5000);
+    }
+  }
+
+  private getOrCreatePushRuntime(linkKey: string, params: {
+    did: string;
+    dwnUrl: string;
+    delegateDid?: string;
+    protocol?: string;
+  }): PushRuntimeState {
+    let pushRuntime = this._pushRuntimes.get(linkKey);
+    if (!pushRuntime) {
+      pushRuntime = {
+        ...params,
+        entries    : [],
+        retryCount : 0,
+      };
+      this._pushRuntimes.set(linkKey, pushRuntime);
+    }
+
+    return pushRuntime;
   }
 
   // ---------------------------------------------------------------------------
   // Cursor persistence
   // ---------------------------------------------------------------------------
 
-  private buildCursorKey(did: string, dwnUrl: string, protocol?: string): string {
-    const base = `${did}${CURSOR_SEPARATOR}${dwnUrl}`;
-    return protocol ? `${base}${CURSOR_SEPARATOR}${protocol}` : base;
+  /**
+   * Build the runtime key for a replication link.
+   *
+   * Live-mode subscription methods (`openLivePullSubscription`,
+   * `openLocalPushSubscription`) receive `linkKey` directly and never
+   * call this. The remaining callers are poll-mode `sync()` and the
+   * live-mode startup/error paths that already have `link.scopeId`.
+   *
+   * The `undefined` fallback (which produces a legacy cursor key) exists
+   * only for the no-protocol full-tenant targets in poll mode.
+   */
+  private buildLinkKey(did: string, dwnUrl: string, scopeIdOrProtocol?: string): string {
+    return scopeIdOrProtocol ? buildLinkId(did, dwnUrl, scopeIdOrProtocol) : buildLegacyCursorKey(did, dwnUrl);
   }
 
   /**
-   * Retrieves a stored progress token. Handles migration from old string cursors:
+   * @deprecated Used by poll-mode sync and one-time migration only. Live mode
+   * uses ReplicationLedger checkpoints. Handles migration from old string cursors:
    * if the stored value is a bare string (pre-ProgressToken format), it is treated
    * as absent — the sync engine will do a full SMT reconciliation on first startup
    * after upgrade, which is correct and safe.
@@ -1759,8 +1888,11 @@ export class SyncEngineLevel implements SyncEngine {
           return parsed as ProgressToken;
         }
       } catch {
-        // Not valid JSON (old string cursor) — treat as absent.
+        // Not valid JSON (old string cursor) — fall through to delete.
       }
+      // Entry exists but is unparseable or has invalid/empty fields. Delete it
+      // so subsequent startups don't re-check it on every launch.
+      await this.deleteLegacyCursor(key);
       return undefined;
     } catch (error) {
       const e = error as { code: string };
@@ -1771,9 +1903,20 @@ export class SyncEngineLevel implements SyncEngine {
     }
   }
 
-  private async setCursor(key: string, cursor: ProgressToken): Promise<void> {
+
+  /**
+   * Delete a legacy cursor from the old syncCursors sublevel.
+   * Called as part of one-time migration to ReplicationLedger.
+   */
+  private async deleteLegacyCursor(key: string): Promise<void> {
     const cursors = this._db.sublevel('syncCursors');
-    await cursors.put(key, JSON.stringify(cursor));
+    try {
+      await cursors.del(key);
+    } catch {
+      // Best-effort — ignore LEVEL_NOT_FOUND and transient I/O errors alike.
+      // A failed delete leaves the bad entry for one more re-check on the
+      // next startup, which is harmless.
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -1791,8 +1934,11 @@ export class SyncEngineLevel implements SyncEngine {
     }
 
     // Check for inline base64url-encoded data (small records from EventLog).
+    // Delete the transport-level field so the DWN schema validator does not
+    // reject the message for having unevaluated properties.
     const encodedData = (event.message as any).encodedData as string | undefined;
     if (encodedData) {
+      delete (event.message as any).encodedData;
       const bytes = Encoder.base64UrlToBytes(encodedData);
       return new ReadableStream<Uint8Array>({
         start(controller): void {