@enbox/agent 0.6.4 → 0.6.6

package/dist/esm/sync-engine-level.js

@@ -94,6 +94,18 @@ function isEventInScope(message, scope) {
     return true;
 }
 export class SyncEngineLevel {
+    /** Validate `SyncIdentityOptions` for `registerIdentity` and `updateIdentityOptions`. */
+    static validateSyncIdentityOptions(options) {
+        if (!options || !('protocols' in options)) {
+            throw new Error('SyncEngineLevel: options.protocols is required — pass \'all\' for a full replica or a non-empty protocol list.');
+        }
+        if (options.protocols !== 'all' && !Array.isArray(options.protocols)) {
+            throw new Error('SyncEngineLevel: protocols must be \'all\' or a non-empty string array.');
+        }
+        if (Array.isArray(options.protocols) && options.protocols.length === 0) {
+            throw new Error('SyncEngineLevel: protocols must be \'all\' or a non-empty array of protocol URIs. An empty array is ambiguous.');
+        }
+    }
     constructor({ agent, dataPath, db }) {
         this._syncLock = false;
         /**
@@ -112,7 +124,7 @@ export class SyncEngineLevel {
         // ---------------------------------------------------------------------------
         // Live sync state
         // ---------------------------------------------------------------------------
-        /** Current sync mode, set by `startSync`. */
+        /** Current sync mode, set by `startSync`. Reset to `undefined` by `stopSync`/`clear`. */
         this._syncMode = 'poll';
         /**
          * Monotonic session generation counter. Incremented on every teardown.
@@ -144,6 +156,14 @@ export class SyncEngineLevel {
          * tenant. Keyed by tenantDid to prevent cross-tenant cache pollution.
          */
         this._closureContexts = new Map();
+        /**
+         * Monotonic generation counter for sync target cache invalidation.
+         * Bumped on every invalidation (register/unregister/update/clear/close/stopSync).
+         * An in-flight `getSyncTargets()` captures the generation before awaiting
+         * and only writes to the cache if it hasn't changed, preventing a
+         * concurrent mutation from being masked by stale data.
+         */
+        this._syncTargetsCacheGeneration = 0;
         /** Count of consecutive SMT sync failures (for backoff in poll mode). */
         this._consecutiveFailures = 0;
         /** Per-link degraded-poll interval timers. */
@@ -198,6 +218,15 @@ export class SyncEngineLevel {
     set agent(agent) {
         this._agent = agent;
         this._permissionsApi = new AgentPermissionsApi({ agent: agent });
+        // Cached sync targets were resolved through the previous agent's
+        // DID resolver / endpoint lookup — invalidate so the next sync
+        // tick re-resolves through the new agent.
+        this._syncTargetsCache = undefined;
+        this._syncTargetsCacheGeneration++;
+    }
+    get hasActiveSubscriptions() {
+        return this._liveSubscriptions.length > 0 ||
+            this._localSubscriptions.length > 0;
     }
     get connectivityState() {
         // Aggregate per-link connectivity: if any link is online, report online.
@@ -241,27 +270,37 @@ export class SyncEngineLevel {
     }
     clear() {
         return __awaiter(this, void 0, void 0, function* () {
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
             yield this.teardownLiveSync();
+            this._syncMode = undefined;
             yield this._permissionsApi.clear();
             yield this._db.clear();
         });
     }
     close() {
         return __awaiter(this, void 0, void 0, function* () {
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
             yield this.teardownLiveSync();
             yield this._db.close();
         });
     }
     registerIdentity(_a) {
         return __awaiter(this, arguments, void 0, function* ({ did, options }) {
+            SyncEngineLevel.validateSyncIdentityOptions(options);
             const registeredIdentities = this._db.sublevel('registeredIdentities');
             const existing = yield this.getIdentityOptions(did);
             if (existing) {
                 throw new Error(`SyncEngineLevel: Identity with DID ${did} is already registered.`);
             }
-            // if no options are provided, we default to no delegateDid and all protocols (empty array)
-            options !== null && options !== void 0 ? options : (options = { protocols: [] });
             yield registeredIdentities.put(did, JSON.stringify(options));
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
+            // If live sync is active, hot-add subscriptions for this identity.
+            if (this._syncMode === 'live') {
+                yield this.addIdentityToLiveSync(did, options);
+            }
         });
     }
     unregisterIdentity(did) {
@@ -271,7 +310,13 @@ export class SyncEngineLevel {
             if (!existing) {
                 throw new Error(`SyncEngineLevel: Identity with DID ${did} is not registered.`);
             }
+            // If live sync is active, hot-remove subscriptions for this identity.
+            if (this._syncMode === 'live') {
+                yield this.removeIdentityFromLiveSync(did);
+            }
             yield registeredIdentities.del(did);
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
         });
     }
     getIdentityOptions(did) {
@@ -297,12 +342,28 @@ export class SyncEngineLevel {
     }
     updateIdentityOptions(_a) {
         return __awaiter(this, arguments, void 0, function* ({ did, options }) {
+            SyncEngineLevel.validateSyncIdentityOptions(options);
             const registeredIdentities = this._db.sublevel('registeredIdentities');
             const existingOptions = yield this.getIdentityOptions(did);
             if (!existingOptions) {
                 throw new Error(`SyncEngineLevel: Identity with DID ${did} is not registered.`);
             }
             yield registeredIdentities.put(did, JSON.stringify(options));
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
+            // Always persist the new delegate to durable links, regardless of
+            // sync mode. If sync is stopped or polling, existing persisted links
+            // would otherwise keep the old delegateDid. When live sync starts
+            // later, initializeLinkTarget() loads the link from LevelDB without
+            // normalizing delegateDid, so repair/reconcile paths could use stale
+            // delegate data.
+            yield this.ledger.updateDelegateDid(did, options.delegateDid);
+            // If live sync is active, tear down and rebuild subscriptions with
+            // the new options.
+            if (this._syncMode === 'live' && this.hasActiveLinksForDid(did)) {
+                yield this.removeIdentityFromLiveSync(did);
+                yield this.addIdentityToLiveSync(did, options);
+            }
         });
     }
     // ---------------------------------------------------------------------------
@@ -421,7 +482,10 @@ export class SyncEngineLevel {
                 clearInterval(this._syncIntervalId);
                 this._syncIntervalId = undefined;
             }
+            this._syncTargetsCache = undefined;
+            this._syncTargetsCacheGeneration++;
             yield this.teardownLiveSync();
+            this._syncMode = undefined;
         });
     }
     // ---------------------------------------------------------------------------
@@ -492,90 +556,7 @@ export class SyncEngineLevel {
             // Step 2: Initialize replication links and open live subscriptions.
             // Each target's link initialization is independent — process concurrently.
             const syncTargets = yield this.getSyncTargets();
-            yield Promise.allSettled(syncTargets.map((target) => __awaiter(this, void 0, void 0, function* () {
-                let link;
-                try {
-                    // Get or create the link in the durable ledger.
-                    // Use protocol-scoped scope when a protocol is specified, otherwise full-tenant.
-                    const linkScope = target.protocol
-                        ? { kind: 'protocol', protocol: target.protocol }
-                        : { kind: 'full' };
-                    link = yield this.ledger.getOrCreateLink({
-                        tenantDid: target.did,
-                        remoteEndpoint: target.dwnUrl,
-                        scope: linkScope,
-                        delegateDid: target.delegateDid,
-                        protocol: target.protocol,
-                    });
-                    // Cache the link for fast access by subscription handlers.
-                    // 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 = yield this.getCursor(legacyKey);
-                        if (legacyCursor) {
-                            ReplicationLedger.resetCheckpoint(link.pull, legacyCursor);
-                            yield this.ledger.saveLink(link);
-                            yield 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.
-                    const targetWithKey = Object.assign(Object.assign({}, target), { linkKey });
-                    yield this.openLivePullSubscription(targetWithKey);
-                    try {
-                        yield this.openLocalPushSubscription(targetWithKey);
-                    }
-                    catch (pushError) {
-                        // Close the already-opened pull subscription.
-                        const pullSub = this._liveSubscriptions.find((s) => s.linkKey === linkKey);
-                        if (pullSub) {
-                            try {
-                                yield pullSub.close();
-                            }
-                            catch ( /* best effort */_a) { /* best effort */ }
-                            this._liveSubscriptions = this._liveSubscriptions.filter(s => s !== pullSub);
-                        }
-                        throw pushError;
-                    }
-                    this.emitEvent({ type: 'link:status-change', tenantDid: target.did, remoteEndpoint: target.dwnUrl, protocol: target.protocol, from: 'initializing', to: 'live' });
-                    yield 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) {
-                    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.isProgressGap && link) {
-                        console.warn(`SyncEngineLevel: ProgressGap detected for ${target.did} -> ${target.dwnUrl}, initiating repair`);
-                        this.emitEvent({ type: 'gap:detected', tenantDid: target.did, remoteEndpoint: target.dwnUrl, protocol: target.protocol, reason: 'ProgressGap' });
-                        const gapInfo = error.gapInfo;
-                        yield this.transitionToRepairing(linkKey, link, {
-                            resumeToken: gapInfo === null || gapInfo === void 0 ? void 0 : gapInfo.latestAvailable,
-                        });
-                        return;
-                    }
-                    console.error(`SyncEngineLevel: Failed to open live subscription for ${target.did} -> ${target.dwnUrl}`, error);
-                    // Clean up in-memory state for the failed link so it doesn't appear
-                    // active to later code. The durable link remains at 'initializing'.
-                    this._activeLinks.delete(linkKey);
-                    this._linkRuntimes.delete(linkKey);
-                    // Recompute connectivity — if no live subscriptions remain, reset to unknown.
-                    if (this._liveSubscriptions.length === 0) {
-                        this._connectivityState = 'unknown';
-                    }
-                }
-            })));
+            yield Promise.allSettled(syncTargets.map(t => this.initializeLinkTarget(t)));
             // Step 3: Schedule infrequent SMT integrity check.
             const integrityCheck = () => __awaiter(this, void 0, void 0, function* () {
                 if (this._syncLock) {
@@ -616,7 +597,7 @@ export class SyncEngineLevel {
         let drained = 0;
         while (true) {
             const entry = rt.inflight.get(rt.nextCommitOrdinal);
-            if (!entry || !entry.committed) {
+            if (!(entry === null || entry === void 0 ? void 0 : entry.committed)) {
                 break;
             }
             // This ordinal is committed — advance the durable checkpoint.
@@ -694,7 +675,7 @@ export class SyncEngineLevel {
             }
             // Verify link still exists and is still repairing.
             const currentLink = this._activeLinks.get(linkKey);
-            if (!currentLink || currentLink.status !== 'repairing') {
+            if ((currentLink === null || currentLink === void 0 ? void 0 : currentLink.status) !== 'repairing') {
                 return;
             }
             try {
@@ -750,6 +731,10 @@ export class SyncEngineLevel {
             // any await, the generation will have incremented and we bail before
             // mutating state — preventing the race where repair continues after teardown.
             const generation = this._engineGeneration;
+            // Identity guard helper: if the DID was hot-removed and quickly re-added,
+            // `_activeLinks` may contain a *different* link object for the same key.
+            // The old repair closure must not mutate the replacement link's state.
+            const isStaleLink = () => this._activeLinks.get(linkKey) !== link;
             const { tenantDid: did, remoteEndpoint: dwnUrl, delegateDid, protocol } = link;
             this.emitEvent({ type: 'repair:started', tenantDid: did, remoteEndpoint: dwnUrl, protocol, attempt: ((_a = this._repairAttempts.get(linkKey)) !== null && _a !== void 0 ? _a : 0) + 1 });
             const attempts = ((_b = this._repairAttempts.get(linkKey)) !== null && _b !== void 0 ? _b : 0) + 1;
@@ -757,9 +742,9 @@ export class SyncEngineLevel {
             // Step 1: Close existing subscriptions FIRST to stop old events from
             // mutating local state while repair runs.
             yield this.closeLinkSubscriptions(link);
-            if (this._engineGeneration !== generation) {
+            if (this._engineGeneration !== generation || isStaleLink()) {
                 return;
-            } // Teardown occurred.
+            }
             // Step 2: Clear runtime ordinals immediately — stale state must not
             // persist across repair attempts (successful or failed).
             const rt = this.getOrCreateRuntime(linkKey);
@@ -768,7 +753,7 @@ export class SyncEngineLevel {
             rt.nextCommitOrdinal = 0;
             try {
                 // Step 3: Run SMT reconciliation for this link.
-                const reconcileOutcome = yield this.createLinkReconciler(() => this._engineGeneration === generation).reconcile({ did, dwnUrl, delegateDid, protocol });
+                const reconcileOutcome = yield this.createLinkReconciler(() => this._engineGeneration === generation && !isStaleLink()).reconcile({ did, dwnUrl, delegateDid, protocol });
                 if (reconcileOutcome.aborted) {
                     return;
                 }
@@ -782,7 +767,7 @@ export class SyncEngineLevel {
                 const resumeToken = (_c = repairCtx === null || repairCtx === void 0 ? void 0 : repairCtx.resumeToken) !== null && _c !== void 0 ? _c : link.pull.contiguousAppliedToken;
                 ReplicationLedger.resetCheckpoint(link.pull, resumeToken);
                 yield this.ledger.saveLink(link);
-                if (this._engineGeneration !== generation) {
+                if (this._engineGeneration !== generation || isStaleLink()) {
                     return;
                 }
                 // Step 5: Reopen subscriptions.
@@ -793,7 +778,7 @@ export class SyncEngineLevel {
                 // if roots already match).
                 link.needsReconcile = true;
                 yield this.ledger.saveLink(link);
-                if (this._engineGeneration !== generation) {
+                if (this._engineGeneration !== generation || isStaleLink()) {
                     return;
                 }
                 const target = { did, dwnUrl, delegateDid, protocol, linkKey };
@@ -805,7 +790,7 @@ export class SyncEngineLevel {
                         console.warn(`SyncEngineLevel: Stale pull resume token for ${did} -> ${dwnUrl}, resetting to start fresh`);
                         ReplicationLedger.resetCheckpoint(link.pull);
                         yield this.ledger.saveLink(link);
-                        if (this._engineGeneration !== generation) {
+                        if (this._engineGeneration !== generation || isStaleLink()) {
                             return;
                         }
                         yield this.openLivePullSubscription(target);
@@ -814,7 +799,7 @@ export class SyncEngineLevel {
                         throw pullErr;
                     }
                 }
-                if (this._engineGeneration !== generation) {
+                if (this._engineGeneration !== generation || isStaleLink()) {
                     return;
                 }
                 try {
@@ -831,7 +816,7 @@ export class SyncEngineLevel {
                     }
                     throw pushError;
                 }
-                if (this._engineGeneration !== generation) {
+                if (this._engineGeneration !== generation || isStaleLink()) {
                     return;
                 }
                 // Note: post-repair reconcile to close the repair-window gap is
@@ -861,8 +846,9 @@ export class SyncEngineLevel {
                 this.emitEvent({ type: 'link:status-change', tenantDid: did, remoteEndpoint: dwnUrl, protocol, from: 'repairing', to: 'live' });
             }
             catch (error) {
-                // If teardown occurred during repair, don't retry or enter degraded_poll.
-                if (this._engineGeneration !== generation) {
+                // If teardown occurred during repair or the link was replaced by a
+                // hot-remove + re-add, don't retry or enter degraded_poll.
+                if (this._engineGeneration !== generation || isStaleLink()) {
                     return;
                 }
                 console.error(`SyncEngineLevel: Repair failed for ${did} -> ${dwnUrl} (attempt ${attempts})`, error);
@@ -927,8 +913,14 @@ export class SyncEngineLevel {
                 clearInterval(existing);
             }
             // Schedule per-link polling with jitter (15-30 seconds).
+            // Rejection sampling: mask to 14 bits ([0, 16383]), reject >= 15000.
             const baseInterval = 15000;
-            const jitter = Math.floor(Math.random() * 15000);
+            const randomBuf = new Uint32Array(1);
+            let jitter;
+            do {
+                crypto.getRandomValues(randomBuf);
+                jitter = randomBuf[0] & 0x3FFF;
+            } while (jitter >= baseInterval);
             const interval = baseInterval + jitter;
             const pollGeneration = this._engineGeneration;
             const timer = setInterval(() => __awaiter(this, void 0, void 0, function* () {
@@ -938,9 +930,12 @@ export class SyncEngineLevel {
                     this._degradedPollTimers.delete(linkKey);
                     return;
                 }
-                // If the link was transitioned out of degraded_poll externally (e.g.,
-                // by teardown or manual intervention), stop polling.
-                if (link.status !== 'degraded_poll') {
+                // Resolve the *current* link from _activeLinks on each tick, not the
+                // captured closure reference. After hot-remove + re-add, the captured
+                // `link` object is stale and must not be used for status checks or
+                // ledger writes.
+                const currentLink = this._activeLinks.get(linkKey);
+                if ((currentLink === null || currentLink === void 0 ? void 0 : currentLink.status) !== 'degraded_poll') {
                     clearInterval(timer);
                     this._degradedPollTimers.delete(linkKey);
                     return;
@@ -949,10 +944,10 @@ export class SyncEngineLevel {
                     // Attempt repair. Reset attempt counter so repairLink doesn't
                     // immediately re-enter degraded_poll on failure.
                     this._repairAttempts.set(linkKey, 0);
-                    yield this.ledger.setStatus(link, 'repairing');
+                    yield this.ledger.setStatus(currentLink, 'repairing');
                     yield this.repairLink(linkKey);
                     // If repairLink succeeded, link is now 'live' — stop polling.
-                    if (link.status === 'live') {
+                    if (currentLink.status === 'live') {
                         clearInterval(timer);
                         this._degradedPollTimers.delete(linkKey);
                     }
@@ -962,7 +957,9 @@ export class SyncEngineLevel {
                     // This is critical: repairLink sets status to 'repairing' internally,
                     // and if we don't restore degraded_poll, the next tick would see
                     // status !== 'degraded_poll' and stop the timer permanently.
-                    yield this.ledger.setStatus(link, 'degraded_poll');
+                    if (this._activeLinks.get(linkKey) === currentLink) {
+                        yield this.ledger.setStatus(currentLink, 'degraded_poll');
+                    }
                 }
             }), interval);
             this._degradedPollTimers.set(linkKey, timer);
@@ -1129,6 +1126,193 @@ export class SyncEngineLevel {
         });
     }
     // ---------------------------------------------------------------------------
+    // Per-target link initialization (shared by startLiveSync + addIdentityToLiveSync)
+    // ---------------------------------------------------------------------------
+    /**
+     * Initialize a single replication link target: create or resume the durable
+     * link, migrate legacy cursors, open pull + push subscriptions, and
+     * transition the link to `'live'`.
+     */
+    initializeLinkTarget(target) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            let link;
+            try {
+                const linkScope = target.protocol
+                    ? { kind: 'protocol', protocol: target.protocol }
+                    : { kind: 'full' };
+                link = yield this.ledger.getOrCreateLink({
+                    tenantDid: target.did,
+                    remoteEndpoint: target.dwnUrl,
+                    scope: linkScope,
+                    delegateDid: target.delegateDid,
+                    protocol: target.protocol,
+                });
+                const linkKey = this.buildLinkKey(target.did, target.dwnUrl, link.scopeId);
+                if (!link.pull.contiguousAppliedToken) {
+                    const legacyKey = buildLegacyCursorKey(target.did, target.dwnUrl, target.protocol);
+                    const legacyCursor = yield this.getCursor(legacyKey);
+                    if (legacyCursor) {
+                        ReplicationLedger.resetCheckpoint(link.pull, legacyCursor);
+                        yield this.ledger.saveLink(link);
+                        yield this.deleteLegacyCursor(legacyKey);
+                    }
+                }
+                this._activeLinks.set(linkKey, link);
+                const targetWithKey = Object.assign(Object.assign({}, target), { linkKey });
+                yield this.openLivePullSubscription(targetWithKey);
+                try {
+                    yield this.openLocalPushSubscription(targetWithKey);
+                }
+                catch (pushError) {
+                    const pullSub = this._liveSubscriptions.find((s) => s.linkKey === linkKey);
+                    if (pullSub) {
+                        try {
+                            yield pullSub.close();
+                        }
+                        catch ( /* best effort */_b) { /* best effort */ }
+                        this._liveSubscriptions = this._liveSubscriptions.filter(s => s !== pullSub);
+                    }
+                    throw pushError;
+                }
+                this.emitEvent({ type: 'link:status-change', tenantDid: target.did, remoteEndpoint: target.dwnUrl, protocol: target.protocol, from: 'initializing', to: 'live' });
+                yield this.ledger.setStatus(link, 'live');
+                if (link.needsReconcile) {
+                    this.scheduleReconcile(linkKey, 1000);
+                }
+            }
+            catch (error) {
+                const linkKey = link
+                    ? this.buildLinkKey(target.did, target.dwnUrl, link.scopeId)
+                    : buildLegacyCursorKey(target.did, target.dwnUrl, target.protocol);
+                if (error.isProgressGap && link) {
+                    console.warn(`SyncEngineLevel: ProgressGap detected for ${target.did} -> ${target.dwnUrl}, initiating repair`);
+                    this.emitEvent({ type: 'gap:detected', tenantDid: target.did, remoteEndpoint: target.dwnUrl, protocol: target.protocol, reason: 'ProgressGap' });
+                    yield this.transitionToRepairing(linkKey, link, {
+                        resumeToken: (_a = error.gapInfo) === null || _a === void 0 ? void 0 : _a.latestAvailable,
+                    });
+                    return;
+                }
+                console.error(`SyncEngineLevel: Failed to open live subscription for ${target.did} -> ${target.dwnUrl}`, error);
+                this._activeLinks.delete(linkKey);
+                this._linkRuntimes.delete(linkKey);
+                if (this._liveSubscriptions.length === 0) {
+                    this._connectivityState = 'unknown';
+                }
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // Hot-add / hot-remove: per-identity live sync management
+    // ---------------------------------------------------------------------------
+    /** Check whether a link key belongs to a given DID. */
+    isLinkKeyForDid(key, did) {
+        return key.startsWith(did + '^') || key.startsWith(did + '_');
+    }
+    /** Check whether this DID has any active links. */
+    hasActiveLinksForDid(did) {
+        for (const key of this._activeLinks.keys()) {
+            if (this.isLinkKeyForDid(key, did)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Hot-add a single identity to the active live sync session. */
+    addIdentityToLiveSync(did, options) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { protocols, delegateDid } = options;
+            const dwnEndpointUrls = yield this.agent.dwn.getDwnEndpointUrlsForTarget(did);
+            if (dwnEndpointUrls.length === 0) {
+                return;
+            }
+            const targets = [];
+            for (const dwnUrl of dwnEndpointUrls) {
+                if (protocols === 'all') {
+                    targets.push({ did, delegateDid, dwnUrl });
+                }
+                else {
+                    for (const protocol of protocols) {
+                        targets.push({ did, delegateDid, dwnUrl, protocol });
+                    }
+                }
+            }
+            yield Promise.allSettled(targets.map(t => this.initializeLinkTarget(t)));
+        });
+    }
+    /** Hot-remove a single identity from the active live sync session. */
+    removeIdentityFromLiveSync(did) {
+        return __awaiter(this, void 0, void 0, function* () {
+            for (const sub of this._liveSubscriptions.filter(s => s.did === did)) {
+                try {
+                    yield sub.close();
+                }
+                catch ( /* best effort */_a) { /* best effort */ }
+            }
+            this._liveSubscriptions = this._liveSubscriptions.filter(s => s.did !== did);
+            for (const sub of this._localSubscriptions.filter(s => s.did === did)) {
+                try {
+                    yield sub.close();
+                }
+                catch ( /* best effort */_b) { /* best effort */ }
+            }
+            this._localSubscriptions = this._localSubscriptions.filter(s => s.did !== did);
+            for (const [key, runtime] of this._pushRuntimes) {
+                if (runtime.did === did) {
+                    if (runtime.timer) {
+                        clearTimeout(runtime.timer);
+                    }
+                    this._pushRuntimes.delete(key);
+                }
+            }
+            for (const [key, timer] of this._degradedPollTimers) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    clearInterval(timer);
+                    this._degradedPollTimers.delete(key);
+                }
+            }
+            for (const key of this._repairAttempts.keys()) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    this._repairAttempts.delete(key);
+                }
+            }
+            for (const key of this._activeRepairs.keys()) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    this._activeRepairs.delete(key);
+                }
+            }
+            for (const key of this._repairContext.keys()) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    this._repairContext.delete(key);
+                }
+            }
+            for (const [key, timer] of this._repairRetryTimers) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    clearTimeout(timer);
+                    this._repairRetryTimers.delete(key);
+                }
+            }
+            for (const [key, timer] of this._reconcileTimers) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    clearTimeout(timer);
+                    this._reconcileTimers.delete(key);
+                }
+            }
+            for (const key of this._reconcileInFlight.keys()) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    this._reconcileInFlight.delete(key);
+                }
+            }
+            for (const key of this._activeLinks.keys()) {
+                if (this.isLinkKeyForDid(key, did)) {
+                    this._activeLinks.delete(key);
+                    this._linkRuntimes.delete(key);
+                }
+            }
+            this._closureContexts.delete(did);
+        });
+    }
+    // ---------------------------------------------------------------------------
     // Live pull: MessagesSubscribe to remote DWN
     // ---------------------------------------------------------------------------
     /**
@@ -1188,9 +1372,15 @@ export class SyncEngineLevel {
             // 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.
+            // Capture the link reference at subscription-open time so we can
+            // detect remove+re-add via object identity, not just key existence.
+            const capturedLink = link;
+            const isStale = () => this._engineGeneration !== handlerGeneration ||
+                !this._activeLinks.has(cursorKey) ||
+                (capturedLink !== undefined && this._activeLinks.get(cursorKey) !== capturedLink);
             const subscriptionHandler = (subMessage) => __awaiter(this, void 0, void 0, function* () {
                 var _a;
-                if (this._engineGeneration !== handlerGeneration) {
+                if (isStale()) {
                     return;
                 }
                 if (subMessage.type === 'eose') {
@@ -1203,15 +1393,16 @@ export class SyncEngineLevel {
                         }
                         if (!ReplicationLedger.validateTokenDomain(link.pull, subMessage.cursor)) {
                             console.warn(`SyncEngineLevel: Token domain mismatch on EOSE for ${did} -> ${dwnUrl}, transitioning to repairing`);
-                            yield this.transitionToRepairing(cursorKey, link);
+                            if (!isStale()) {
+                                yield this.transitionToRepairing(cursorKey, link);
+                            }
                             return;
                         }
                         ReplicationLedger.setReceivedToken(link.pull, subMessage.cursor);
-                        // Drain committed entries. Do NOT unconditionally advance to the
-                        // EOSE cursor — earlier stored events may still be in-flight
-                        // (handlers are fire-and-forget). The checkpoint advances only as
-                        // far as the contiguous drain reaches.
                         this.drainCommittedPull(cursorKey);
+                        if (isStale()) {
+                            return;
+                        }
                         yield this.ledger.saveLink(link);
                     }
                     // Transport is reachable — set connectivity to online.
@@ -1243,7 +1434,9 @@ export class SyncEngineLevel {
                     // Domain validation: reject tokens from a different stream/epoch.
                     if (link && !ReplicationLedger.validateTokenDomain(link.pull, subMessage.cursor)) {
                         console.warn(`SyncEngineLevel: Token domain mismatch for ${did} -> ${dwnUrl}, transitioning to repairing`);
-                        yield this.transitionToRepairing(cursorKey, link);
+                        if (!isStale()) {
+                            yield this.transitionToRepairing(cursorKey, link);
+                        }
                         return;
                     }
                     // Subset scope filtering: if the link has protocolPath/contextId prefixes,
@@ -1255,9 +1448,11 @@ export class SyncEngineLevel {
                     // reconnect/repair. This is safe because the event is intentionally
                     // excluded from this scope and doesn't need processing.
                     if (link && !isEventInScope(event.message, link.scope)) {
-                        ReplicationLedger.setReceivedToken(link.pull, subMessage.cursor);
-                        ReplicationLedger.commitContiguousToken(link.pull, subMessage.cursor);
-                        yield this.ledger.saveLink(link);
+                        if (!isStale()) {
+                            ReplicationLedger.setReceivedToken(link.pull, subMessage.cursor);
+                            ReplicationLedger.commitContiguousToken(link.pull, subMessage.cursor);
+                            yield this.ledger.saveLink(link);
+                        }
                         return;
                     }
                     // Assign a delivery ordinal BEFORE async processing begins.
@@ -1285,6 +1480,9 @@ export class SyncEngineLevel {
                             }
                         }
                         yield this.agent.dwn.processRawMessage(did, event.message, { dataStream });
+                        if (isStale()) {
+                            return;
+                        }
                         // Invalidate closure cache entries that may be affected by this message.
                         // Must run before closure validation so subsequent evaluations in the
                         // same session see the updated local state.
@@ -1296,7 +1494,7 @@ export class SyncEngineLevel {
                         // For protocol-scoped links, verify that all hard dependencies for
                         // this operation are locally present before considering it committed.
                         // Full-tenant scope bypasses this entirely (returns complete with 0 queries).
-                        if (link && link.scope.kind === 'protocol') {
+                        if ((link === null || link === void 0 ? void 0 : link.scope.kind) === 'protocol') {
                             const messageStore = this.agent.dwn.node.storage.messageStore;
                             let closureCtx = this._closureContexts.get(did);
                             if (!closureCtx) {
@@ -1306,6 +1504,9 @@ export class SyncEngineLevel {
                                 this._closureContexts.set(did, closureCtx);
                             }
                             const closureResult = yield evaluateClosure(event.message, messageStore, link.scope, closureCtx);
+                            if (isStale()) {
+                                return;
+                            }
                             if (!closureResult.complete) {
                                 const failureCode = closureResult.failure.code;
                                 const failureDetail = closureResult.failure.detail;
@@ -1322,7 +1523,9 @@ export class SyncEngineLevel {
                                     errorCode: failureCode,
                                     errorDetail: failureDetail,
                                 });
-                                yield this.transitionToRepairing(cursorKey, link);
+                                if (!isStale()) {
+                                    yield this.transitionToRepairing(cursorKey, link);
+                                }
                                 return;
                             }
                         }
@@ -1345,7 +1548,7 @@ export class SyncEngineLevel {
                         // Guard: if the link transitioned to repairing while this handler was
                         // in-flight (e.g., an earlier ordinal's handler failed concurrently),
                         // skip all state mutations — the repair process owns progression now.
-                        if (link && rt && link.status === 'live') {
+                        if (link && rt && link.status === 'live' && !isStale()) {
                             const entry = rt.inflight.get(ordinal);
                             if (entry) {
                                 entry.committed = true;
@@ -1396,7 +1599,7 @@ export class SyncEngineLevel {
                         // Transition to repairing immediately — do NOT advance the checkpoint
                         // past this failure or let later ordinals commit past it. SMT
                         // reconciliation will discover and fill the gap.
-                        if (link) {
+                        if (link && !isStale()) {
                             yield this.transitionToRepairing(cursorKey, link);
                         }
                     }
@@ -1503,9 +1706,14 @@ export class SyncEngineLevel {
                 permissionGrantId = grant.grant.id;
             }
             const handlerGeneration = this._engineGeneration;
+            // Capture the link for identity-based staleness detection.
+            const capturedPushLink = this._activeLinks.get(target.linkKey);
+            const isPushStale = () => this._engineGeneration !== handlerGeneration ||
+                !this._activeLinks.has(target.linkKey) ||
+                (capturedPushLink !== undefined && this._activeLinks.get(target.linkKey) !== capturedPushLink);
             // Subscribe to the local DWN's EventLog.
             const subscriptionHandler = (subMessage) => __awaiter(this, void 0, void 0, function* () {
-                if (this._engineGeneration !== handlerGeneration) {
+                if (isPushStale()) {
                     return;
                 }
                 if (subMessage.type !== 'event') {
@@ -1521,7 +1729,7 @@ export class SyncEngineLevel {
                 // Accumulate the message CID for a debounced push.
                 const targetKey = pushLinkKey;
                 const cid = yield Message.getCid(subMessage.event.message);
-                if (cid === undefined) {
+                if (cid === undefined || isPushStale()) {
                     return;
                 }
                 // Echo-loop suppression: skip CIDs that were recently pulled from this
@@ -1579,10 +1787,21 @@ export class SyncEngineLevel {
     flushPendingPushesForLink(linkKey) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
+            // Guard: bail if this link was hot-removed. Without this, a stale
+            // debounce timer or retry callback could send pushes after the DID
+            // was removed.
+            if (!this._activeLinks.has(linkKey)) {
+                return;
+            }
             const pushRuntime = this._pushRuntimes.get(linkKey);
             if (!pushRuntime) {
                 return;
             }
+            // Capture the current active link identity so we can detect
+            // remove+re-add during the await pushMessages() call.
+            const flushLink = this._activeLinks.get(linkKey);
+            const isFlushStale = () => !this._activeLinks.has(linkKey) ||
+                (flushLink !== undefined && this._activeLinks.get(linkKey) !== flushLink);
             const { did, dwnUrl, delegateDid, protocol, entries: pushEntries, retryCount } = pushRuntime;
             pushRuntime.entries = [];
             if (pushEntries.length === 0) {
@@ -1600,6 +1819,11 @@ export class SyncEngineLevel {
                     agent: this.agent,
                     permissionsApi: this._permissionsApi,
                 });
+                // If the link was replaced during pushMessages, abandon all
+                // post-push state mutations — the replacement session owns this key.
+                if (isFlushStale()) {
+                    return;
+                }
                 // Auto-clear dead letters for CIDs that succeeded — a previously
                 // failed message may have been repaired by reconciliation.
                 for (const cid of result.succeeded) {
@@ -1618,6 +1842,9 @@ export class SyncEngineLevel {
                     });
                 }
                 if (result.failed.length > 0) {
+                    if (isFlushStale()) {
+                        return;
+                    }
                     const failedSet = new Set(result.failed);
                     const failedEntries = pushEntries.filter((entry) => failedSet.has(entry.cid));
                     this.requeueOrReconcile(linkKey, {
@@ -1636,6 +1863,9 @@ export class SyncEngineLevel {
                 }
             }
             catch (error) {
+                if (isFlushStale()) {
+                    return;
+                }
                 console.error(`SyncEngineLevel: Push batch failed for ${did} -> ${dwnUrl}`, error);
                 this.requeueOrReconcile(linkKey, {
                     did, dwnUrl, delegateDid, protocol,
@@ -1735,7 +1965,16 @@ export class SyncEngineLevel {
             if (this._engineGeneration !== generation) {
                 return;
             }
-            void this.reconcileLink(linkKey);
+            // Guard: bail if this link was hot-removed since the timer was
+            // scheduled. Without this, a stale timer could restart reconcile
+            // work for a DID that is no longer active.
+            if (!this._activeLinks.has(linkKey)) {
+                return;
+            }
+            void this.reconcileLink(linkKey).catch(() => {
+                // Errors are already logged inside doReconcileLink; swallow here
+                // to prevent unhandled-rejection flakes in the test runner.
+            });
         }, delayMs);
         this._reconcileTimers.set(linkKey, timer);
     }
@@ -1776,10 +2015,14 @@ export class SyncEngineLevel {
                 return;
             }
             const generation = this._engineGeneration;
+            // Identity guard: if the DID was hot-removed and re-added, this
+            // closure's captured `link` reference may no longer be the active
+            // link object. Bail before mutating the replacement's state.
+            const isStaleLink = () => this._activeLinks.get(linkKey) !== link;
             const { tenantDid: did, remoteEndpoint: dwnUrl, delegateDid, protocol } = link;
             try {
-                const reconcileOutcome = yield this.createLinkReconciler(() => this._engineGeneration === generation).reconcile({ did, dwnUrl, delegateDid, protocol }, { verifyConvergence: true });
-                if (reconcileOutcome.aborted) {
+                const reconcileOutcome = yield this.createLinkReconciler(() => this._engineGeneration === generation && !isStaleLink()).reconcile({ did, dwnUrl, delegateDid, protocol }, { verifyConvergence: true });
+                if (reconcileOutcome.aborted || isStaleLink()) {
                     return;
                 }
                 if (reconcileOutcome.converged) {
@@ -1793,10 +2036,15 @@ export class SyncEngineLevel {
                     // 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);
+                    if (!isStaleLink()) {
+                        this.scheduleReconcile(linkKey, 5000);
+                    }
                 }
             }
             catch (error) {
+                if (isStaleLink()) {
+                    return;
+                }
                 console.error(`SyncEngineLevel: Reconciliation failed for ${did} -> ${dwnUrl}`, error);
                 // Schedule retry with longer delay.
                 this.scheduleReconcile(linkKey, 5000);
@@ -1978,9 +2226,9 @@ export class SyncEngineLevel {
             var _a;
             const si = this.stateIndex;
             if (si) {
-                const rootHash = protocol !== undefined
-                    ? yield si.getProtocolRoot(did, protocol)
-                    : yield si.getRoot(did);
+                const rootHash = protocol === undefined
+                    ? yield si.getRoot(did)
+                    : yield si.getProtocolRoot(did, protocol);
                 return hashToHex(rootHash);
             }
             // Remote mode fallback: go through processRequest → RPC.
@@ -2106,9 +2354,9 @@ export class SyncEngineLevel {
                 if (si) {
                     // Fast path: direct StateIndex access (local mode).
                     const bitPath = SyncEngineLevel.parseBitPrefix(prefix);
-                    const hash = protocol !== undefined
-                        ? yield si.getProtocolSubtreeHash(did, protocol, bitPath)
-                        : yield si.getSubtreeHash(did, bitPath);
+                    const hash = protocol === undefined
+                        ? yield si.getSubtreeHash(did, bitPath)
+                        : yield si.getProtocolSubtreeHash(did, protocol, bitPath);
                     hexHash = hashToHex(hash);
                 }
                 else {
@@ -2145,9 +2393,9 @@ export class SyncEngineLevel {
             const si = this.stateIndex;
             if (si) {
                 const bitPath = SyncEngineLevel.parseBitPrefix(prefix);
-                const hash = protocol !== undefined
-                    ? yield si.getProtocolSubtreeHash(did, protocol, bitPath)
-                    : yield si.getSubtreeHash(did, bitPath);
+                const hash = protocol === undefined
+                    ? yield si.getSubtreeHash(did, bitPath)
+                    : yield si.getProtocolSubtreeHash(did, protocol, bitPath);
                 return hashToHex(hash);
             }
             // Remote mode fallback.
@@ -2179,9 +2427,9 @@ export class SyncEngineLevel {
             const si = this.stateIndex;
             if (si) {
                 const bitPath = SyncEngineLevel.parseBitPrefix(prefix);
-                return protocol !== undefined
-                    ? yield si.getProtocolLeaves(did, protocol, bitPath)
-                    : yield si.getLeaves(did, bitPath);
+                return protocol === undefined
+                    ? yield si.getLeaves(did, bitPath)
+                    : yield si.getProtocolLeaves(did, protocol, bitPath);
             }
             // Remote mode fallback.
             const response = yield this.agent.dwn.processRequest({
@@ -2515,31 +2763,47 @@ export class SyncEngineLevel {
     // ---------------------------------------------------------------------------
     /**
      * Returns the list of sync targets: (did, dwnUrl, delegateDid?, protocol?) tuples.
+     * Results are cached for up to 30 seconds to avoid redundant DID resolution
+     * on every sync tick. The cache is invalidated when identities are registered,
+     * unregistered, or updated.
      */
     getSyncTargets() {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, e_6, _b, _c;
+            // Return cached targets if still valid.
+            if (this._syncTargetsCache
+                && (Date.now() - this._syncTargetsCache.timestamp) < SyncEngineLevel.SYNC_TARGETS_CACHE_TTL_MS) {
+                return this._syncTargetsCache.targets;
+            }
+            // Capture the generation before any async work so we can detect
+            // concurrent invalidations (register/unregister/update) that would
+            // make our result stale.
+            const generationAtStart = this._syncTargetsCacheGeneration;
             const targets = [];
+            let hasRegisteredIdentities = false;
+            let anyEndpointMissing = false;
             try {
                 for (var _d = true, _e = __asyncValues(this._db.sublevel('registeredIdentities').iterator()), _f; _f = yield _e.next(), _a = _f.done, !_a; _d = true) {
                     _c = _f.value;
                     _d = false;
                     const [did, options] = _c;
+                    hasRegisteredIdentities = true;
                     let parsed;
                     try {
                         parsed = JSON.parse(options);
                     }
                     catch (error) {
-                        console.warn(`SyncEngineLevel: Corrupt sync options for ${did}, falling back to global sync:`, error);
-                        parsed = { protocols: [] };
+                        console.warn(`SyncEngineLevel: Corrupt sync options for ${did}, skipping identity:`, error);
+                        continue;
                     }
                     const { protocols, delegateDid } = parsed;
                     const dwnEndpointUrls = yield this.agent.dwn.getDwnEndpointUrlsForTarget(did);
                     if (dwnEndpointUrls.length === 0) {
+                        anyEndpointMissing = true;
                         continue;
                     }
                     for (const dwnUrl of dwnEndpointUrls) {
-                        if (protocols.length === 0) {
+                        if (protocols === 'all') {
                             // Sync all protocols (global tree).
                             targets.push({ did, delegateDid, dwnUrl });
                         }
@@ -2558,6 +2822,17 @@ export class SyncEngineLevel {
                 }
                 finally { if (e_6) throw e_6.error; }
             }
+            // Only cache when:
+            // - The result is non-empty (empty = transient resolution failure).
+            // - All registered identities resolved successfully (partial =
+            //   one identity's endpoints failed transiently; caching would
+            //   suppress retries for that identity for the full TTL).
+            // - The generation hasn't changed (a concurrent register/unregister
+            //   invalidated the cache while we were awaiting).
+            const isComplete = hasRegisteredIdentities && !anyEndpointMissing;
+            if (targets.length > 0 && isComplete && this._syncTargetsCacheGeneration === generationAtStart) {
+                this._syncTargetsCache = { targets, timestamp: Date.now() };
+            }
             return targets;
         });
     }
@@ -2585,6 +2860,8 @@ export class SyncEngineLevel {
 SyncEngineLevel.ECHO_SUPPRESS_TTL_MS = 60000;
 /** Maximum entries in the echo-loop suppression cache. */
 SyncEngineLevel.ECHO_SUPPRESS_MAX_ENTRIES = 10000;
+/** TTL for the sync targets cache (30 seconds). */
+SyncEngineLevel.SYNC_TARGETS_CACHE_TTL_MS = 30000;
 /** Maximum consecutive failures before entering backoff. */
 SyncEngineLevel.MAX_CONSECUTIVE_FAILURES = 5;
 /** Backoff multiplier for consecutive failures (caps at 4x the configured interval). */