@zlink-systems/framework 0.25.0 → 0.26.0

package/dist/runtime/host/service-relocation-host-runtime.js

@@ -181,10 +181,6 @@ class ZLinkHostServiceRelocationRuntime {
         this.targetReadyFailures.clear();
         this.targetReadyResponses.clear();
         for (const window of this.sourceCutoverWindows.values()) {
-            if (window.windowTimer !== undefined)
-                clearTimeout(window.windowTimer);
-            if (window.retryTimer !== undefined)
-                clearTimeout(window.retryTimer);
             if (window.followTimer !== undefined)
                 clearTimeout(window.followTimer);
         }
@@ -302,19 +298,44 @@ class ZLinkHostServiceRelocationRuntime {
             publishState: () => undefined,
             forceStop: () => undefined
         });
+        const started = [];
         for (const unit of work) {
             maintenance.enqueue({
                 id: unit.id,
                 ready: () => true,
-                relocate: unit.relocate
+                relocate: (relocationSignal) => {
+                    const run = unit.relocate(relocationSignal);
+                    started.push(run);
+                    return run;
+                }
             });
         }
         const operationSignal = signal ?? new AbortController().signal;
         const deadlineMs = signal === undefined ? 30_000 : 24 * 60 * 60 * 1000;
-        const result = await raceAbort(maintenance.start('retire', deadlineMs, stopStartingSignal, operationSignal), operationSignal);
-        if (result.state !== 'completed') {
-            throw result.terminalError ?? new Error(`Host relocation ended in '${result.state}'.`);
+        let failure;
+        try {
+            const result = await raceAbort(maintenance.start('retire', deadlineMs, stopStartingSignal, operationSignal), operationSignal);
+            if (result.state === 'completed')
+                return;
+            failure = result.terminalError ?? new Error(`Host relocation ended in '${result.state}'.`);
         }
+        catch (error) {
+            failure = error;
+        }
+        // The host result follows the settled authority of every started unit
+        // (spec 30 §13): a unit completes only after its target commit is
+        // confirmed, so a failure beside a completed unit leaves units on both
+        // sides.
+        const settled = await Promise.allSettled(started);
+        const targetSide = settled.filter((value) => value.status === 'fulfilled' || value.reason instanceof service_relocation_coordinator_1.ServiceRelocationPostCommitError).length;
+        const authorityError = settled.find((value) => value.status === 'rejected' && value.reason instanceof service_relocation_coordinator_1.ServiceRelocationAuthorityError);
+        if (authorityError !== undefined)
+            throw authorityError.reason;
+        // A unit that never started also stays on the source.
+        if (targetSide > 0 && targetSide < work.length) {
+            throw new service_relocation_coordinator_1.ServiceRelocationAuthorityError('Relocation units settled on both the source and the target.', { cause: failure });
+        }
+        throw failure;
     }
     async tryHandleControl(meshName, record, signal) {
         if (record.parts.length === 0)
@@ -827,6 +848,9 @@ class ZLinkHostServiceRelocationRuntime {
         }
     }
     async relocateSpotAggregate(meshName, activation, kind, actorStates, target, targetApplicationVersion, signal) {
+        await activation.serial.executeLifecycleOperation(() => this.relocateSpotAggregateCore(meshName, activation, kind, actorStates, target, targetApplicationVersion, signal));
+    }
+    async relocateSpotAggregateCore(meshName, activation, kind, actorStates, target, targetApplicationVersion, signal) {
         const store = this.requireLocationStore();
         const spotKey = (0, authority_key_codec_1.encodeAuthorityKey)(kind, String(activation.spotId));
         const spotAuthority = await requireAuthority(store, spotKey, signal);
@@ -866,12 +890,12 @@ class ZLinkHostServiceRelocationRuntime {
             objectGeneration: spotAuthority.objectGeneration,
             authorityOwnerGeneration: spotAuthority.authorityOwnerGeneration,
             seal: async (captureSignal) => {
-                interruptionStartedAt = performance.now();
-                spotMessageFollowSeal = this.sealSpotMessageFollow(meshName, spotAuthority, activation);
-                // captureRelocation seals synchronously before its first await. Invoke
-                // it in the same event-loop turn as the wire ingress seal so no
-                // accepted direct message can enter between the two boundaries.
-                const spotCaptureOperation = activation.captureRelocation(captureSignal);
+                const { spotCaptureOperation } = await this.afterSpotCloseDecision(meshName, activation.spotId, () => {
+                    interruptionStartedAt = performance.now();
+                    spotMessageFollowSeal = this.sealSpotMessageFollow(meshName, spotAuthority, activation);
+                    // Both seals run in the same event-loop turn after the Close decision.
+                    return { spotCaptureOperation: activation.captureRelocation(captureSignal) };
+                });
                 const preparedSessions = Promise.all(actorStates.map(async (state) => ({
                     state,
                     actor: state.actor,
@@ -986,7 +1010,9 @@ class ZLinkHostServiceRelocationRuntime {
         }
         catch (error) {
             outcome = 'failed';
-            if (readinessBoundaryConsumed && !(error instanceof service_relocation_coordinator_1.ServiceRelocationPostCommitError)) {
+            if (readinessBoundaryConsumed &&
+                !(error instanceof service_relocation_coordinator_1.ServiceRelocationPostCommitError) &&
+                !(error instanceof service_relocation_coordinator_1.ServiceRelocationAuthorityError)) {
                 await activation
                     .completeConsumedRelocationBoundary(contracts_1.ZLinkSpotRelocationReadyOutcome.Continued)
                     .catch(() => undefined);
@@ -1058,6 +1084,9 @@ class ZLinkHostServiceRelocationRuntime {
         }
     }
     async relocatePerActorSpotShell(meshName, activation, target, targetApplicationVersion, signal) {
+        await activation.serial.executeLifecycleOperation(() => this.relocatePerActorSpotShellCore(meshName, activation, target, targetApplicationVersion, signal));
+    }
+    async relocatePerActorSpotShellCore(meshName, activation, target, targetApplicationVersion, signal) {
         const spotKey = (0, authority_key_codec_1.encodeAuthorityKey)('user_spot', String(activation.spotId));
         const spotAuthority = await requireAuthority(this.requireLocationStore(), spotKey, signal);
         const spotRegistration = this.spotRegistration(meshName, 'user_spot', spotAuthority.allocation.stableType);
@@ -1080,9 +1109,12 @@ class ZLinkHostServiceRelocationRuntime {
             objectGeneration: spotAuthority.objectGeneration,
             authorityOwnerGeneration: spotAuthority.authorityOwnerGeneration,
             seal: async (captureSignal) => {
-                interruptionStartedAt = performance.now();
-                spotMessageFollowSeal = this.sealSpotMessageFollow(meshName, spotAuthority, activation);
-                spotCapture = await activation.captureRelocation(captureSignal);
+                const { spotCaptureOperation } = await this.afterSpotCloseDecision(meshName, activation.spotId, () => {
+                    interruptionStartedAt = performance.now();
+                    spotMessageFollowSeal = this.sealSpotMessageFollow(meshName, spotAuthority, activation);
+                    return { spotCaptureOperation: activation.captureRelocation(captureSignal) };
+                });
+                spotCapture = await spotCaptureOperation;
                 return {
                     boundSessionState: Buffer.alloc(0),
                     queuedMessages: [],
@@ -1191,7 +1223,10 @@ class ZLinkHostServiceRelocationRuntime {
             abortSeal: async () => {
                 if (standalone && ownSession !== undefined)
                     await ownSession.prepared.rollback();
-            }
+            },
+            discardSeal: (reason) => (standalone
+                ? ownSession
+                : sessions.find((value) => value.state === state))?.prepared.discard(reason)
         };
     }
     reserveRelocationId() {
@@ -1264,10 +1299,13 @@ class ZLinkHostServiceRelocationRuntime {
         // configured limit unchanged (spec 15 §4.2).
         const chunkLimitBytes = (0, relocation_direct_transfer_1.effectiveActorJoinChunkLimitBytes)(limits.relocationPayloadChunkLimitBytes, advertisedReceiveChunkLimitBytes);
         const plan = (0, relocation_direct_transfer_1.planRelocationChunks)(encoded, chunkLimitBytes);
-        const convergenceDeadlineAtMs = signal === undefined
-            ? performance.now() + RELOCATION_OPERATION_RETENTION_MS
-            : controlDeadlineAtMs;
+        // The Restore absolute deadline is this unit's relocation deadline: the
+        // caller's signal, or the control deadline without one. From it the
+        // source settles the authority with its Preserve fence (Location runtime
+        // §10). The target keeps no deadline of its own.
+        const restoreDeadlineReached = () => signal?.aborted === true || performance.now() >= controlDeadlineAtMs;
         let readyReceived = false;
+        let settlement;
         let sourceCommitted = false;
         try {
             const prepare = {
@@ -1343,9 +1381,9 @@ class ZLinkHostServiceRelocationRuntime {
                 boundaryRecordCount: BigInt(boundaryBatch.length),
                 boundaryChecksumCrc32c: (0, service_relocation_runtime_1.crc32c)(Buffer.concat(boundaryBatch.map((value) => value.canonicalBytes)))
             });
-            // The one-way cutover submit reaches a terminal result exactly once;
-            // success and failure both end source dispatch permanently. The batch
-            // copy stays for the retransmission window (spec 28 §4.4).
+            // The cutover submit result is not the authority result. The memory
+            // copy of the boundary batch and cutover stays until the authority
+            // settlement below (spec 28 §4.4).
             let submitFailure;
             try {
                 for (const record of boundaryBatch) {
@@ -1357,11 +1395,30 @@ class ZLinkHostServiceRelocationRuntime {
                 submitFailure = error;
                 console.warn('[zlink.runtime.relocation.cutover_submit_failed]', relayAuthorityId, error);
             }
-            this.beginSourceCutoverWindow(meshName, target.rid, relayAuthorityId, [...boundaryBatch.map((value) => value.frame), cutoverFrame], submitFailure !== undefined, limits);
-            await this.waitForTargetAuthorities(captured.envelope, targetFence, convergenceDeadlineAtMs, signal);
-            relocationDebug('coordinator.target_authorities_observed', {
-                aggregateId: captured.envelope.aggregateId
+            const window = this.beginSourceCutoverWindow(meshName, target.rid, relayAuthorityId, [...boundaryBatch.map((value) => value.frame), cutoverFrame], submitFailure !== undefined, limits);
+            try {
+                settlement = await this.settleSourceAuthority(captured.envelope, primary, targetFence, restoreDeadlineReached, window);
+            }
+            finally {
+                this.closeSourceCutoverWindow(relayAuthorityId, window);
+            }
+            relocationDebug('coordinator.authority_settled', {
+                aggregateId: captured.envelope.aggregateId,
+                settlement
             });
+            if (settlement === 'source') {
+                // Preserve won: the captured queue, timers and held records return to
+                // the source queue in their accepted order, and dispatch reopens.
+                await captured.abortSource();
+                throw new Error(`Relocation '${relayAuthorityId}' ended by the source Preserve fence; the source kept the authority.`);
+            }
+            if (settlement === 'lost') {
+                // Expired owner: dispatch and Store changes stop for good and every
+                // pending request without a terminal gets one Unavailable.
+                const unavailable = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Relocation '${relayAuthorityId}' source owner lease ended before its authority settled.`, true);
+                await captured.discardSource(unavailable);
+                throw new service_relocation_coordinator_1.ServiceRelocationAuthorityError(unavailable.message, { cause: unavailable });
+            }
             for (const session of sessions)
                 session.prepared.setReplayResults([]);
             await captured.commitSource();
@@ -1369,26 +1426,18 @@ class ZLinkHostServiceRelocationRuntime {
             await this.options.reconcileStatefulAuthorityRoutes?.(signal);
         }
         catch (error) {
-            if (!readyReceived)
+            if (settlement !== 'target')
                 throw error;
-            try {
-                await this.waitForTargetAuthorities(captured.envelope, targetFence, convergenceDeadlineAtMs);
-                if (!sourceCommitted) {
-                    for (const session of sessions)
-                        session.prepared.setReplayResults([]);
-                    await captured.commitSource();
-                    sourceCommitted = true;
-                }
-                await this.options.reconcileStatefulAuthorityRoutes?.();
-                const authority = await requireAuthority(this.requireLocationStore(), { value: primaryKey(captured.envelope) }, undefined);
-                throw new service_relocation_coordinator_1.ServiceRelocationPostCommitError(authority, { id: `${captured.envelope.aggregateId}:${captured.envelope.aggregateGeneration}` }, error);
-            }
-            catch (convergenceError) {
-                if (convergenceError instanceof service_relocation_coordinator_1.ServiceRelocationPostCommitError) {
-                    throw convergenceError;
-                }
-                throw new AggregateError([error, convergenceError], 'Relocation became irreversible after Ready and target convergence failed.');
+            // Target commit is confirmed; later source cleanup failures cannot move
+            // the authority back (spec 28 §9).
+            if (!sourceCommitted) {
+                for (const session of sessions)
+                    session.prepared.setReplayResults([]);
+                await captured.commitSource().catch(() => undefined);
             }
+            await this.options.reconcileStatefulAuthorityRoutes?.().catch(() => undefined);
+            const authority = await requireAuthority(this.requireLocationStore(), { value: primaryKey(captured.envelope) }, undefined);
+            throw new service_relocation_coordinator_1.ServiceRelocationPostCommitError(authority, { id: `${captured.envelope.aggregateId}:${captured.envelope.aggregateGeneration}` }, error);
         }
         finally {
             if (!readyReceived) {
@@ -1461,12 +1510,11 @@ class ZLinkHostServiceRelocationRuntime {
         return budget;
     }
     /**
-     * Starts the source retransmission window after the cutover submit
-     * terminal. The boundary batch and cutover copies live in framework memory
-     * (not charged to the in-flight budget) and are cleaned exactly once when
-     * the window ends. While the window is open a failed submit retries the
-     * whole batch on the (re-established) connection. S4 — the Message Follow
-     * route removal point — closes the unit for SafeToShutdown.
+     * Starts the source cutover window after the cutover submit terminal. The
+     * boundary batch and cutover copies live in framework memory (not charged
+     * to the in-flight budget) until the authority settlement closes the
+     * window. S4 — the Message Follow route removal point — closes the unit for
+     * SafeToShutdown.
      */
     beginSourceCutoverWindow(meshName, targetNodeRid, relocationKey, frames, initialSubmitFailed, limits) {
         const submittedAt = performance.now();
@@ -1474,54 +1522,134 @@ class ZLinkHostServiceRelocationRuntime {
             meshName,
             targetNodeRid,
             frames,
+            resendPending: initialSubmitFailed,
             cutoverSubmittedAtMs: submittedAt,
             windowClosed: false,
             followExpired: false
         };
         this.sourceCutoverWindows.set(relocationKey, window);
-        const settle = () => {
-            if (window.windowClosed && window.followExpired) {
-                this.sourceCutoverWindows.delete(relocationKey);
-            }
-        };
-        window.windowTimer = setTimeout(() => {
-            window.windowClosed = true;
-            window.frames = undefined;
-            if (window.retryTimer !== undefined)
-                clearTimeout(window.retryTimer);
-            settle();
-        }, limits.relocationCutoverWaitTimeoutMs);
-        window.windowTimer.unref();
         window.followTimer = setTimeout(() => {
             window.followExpired = true;
             // S1→S4 route convergence: the span the source must keep its Message
             // Follow route (spec 30 §7.1).
             this.options.metrics?.duration('zlink.relocation.route_convergence', Math.max(0, performance.now() - submittedAt) / 1000, { mesh_name: meshName });
-            settle();
+            this.releaseSourceCutoverWindow(relocationKey, window);
         }, limits.messageFollowDurationMs);
         window.followTimer.unref();
-        if (initialSubmitFailed)
-            this.scheduleCutoverRetransmit(window);
+        return window;
+    }
+    /** The authority settlement ended: the retained batch copy is released. */
+    closeSourceCutoverWindow(relocationKey, window) {
+        window.windowClosed = true;
+        window.frames = undefined;
+        this.releaseSourceCutoverWindow(relocationKey, window);
+    }
+    releaseSourceCutoverWindow(relocationKey, window) {
+        if (window.windowClosed &&
+            window.followExpired &&
+            this.sourceCutoverWindows.get(relocationKey) === window) {
+            this.sourceCutoverWindows.delete(relocationKey);
+        }
     }
-    scheduleCutoverRetransmit(window) {
-        if (window.windowClosed || window.frames === undefined)
+    /**
+     * Sends the whole boundary batch and cutover again after a failed submit
+     * or an observed loss of the target connection (spec 28 §4.4). The target
+     * replaces its partial span with the whole batch.
+     */
+    async resendSourceCutover(window) {
+        const frames = window.frames;
+        if (frames === undefined)
             return;
-        window.retryTimer = setTimeout(() => {
-            void (async () => {
-                const frames = window.frames;
-                if (window.windowClosed || frames === undefined)
-                    return;
-                try {
-                    for (const frame of frames) {
-                        await this.submitControlFrame(window.meshName, window.targetNodeRid, frame, 'cutover retransmission');
-                    }
-                }
-                catch {
-                    this.scheduleCutoverRetransmit(window);
-                }
-            })();
-        }, 250);
-        window.retryTimer.unref();
+        const peers = this.requireMeshNode(window.meshName).peers();
+        const peer = peers.find((value) => value.routingId !== null && String(value.routingId) === String(window.targetNodeRid));
+        // Backend peer state 3 is Ready.
+        if (peer !== undefined && peer.state !== 3) {
+            window.resendPending = true;
+            return;
+        }
+        if (!window.resendPending)
+            return;
+        try {
+            for (const frame of frames) {
+                await this.submitControlFrame(window.meshName, window.targetNodeRid, frame, 'cutover retransmission');
+            }
+            window.resendPending = false;
+        }
+        catch {
+            // The next settlement round retries the whole batch.
+        }
+    }
+    /**
+     * The one source authority settlement after Ready (Location runtime
+     * §6.1·§10, spec 28 §4.4). It reads the Store until the target commit or
+     * the Restore deadline. From the Restore deadline it runs the source
+     * Preserve fence: a CAS on the StoreVersion expected by target NewOwner
+     * excludes a late target commit. `target`: the
+     * target committed. `source`: Preserve fenced the target out while the
+     * source owner lease was valid. `lost`: the source owner lease ended first
+     * or another authority owns the object. An uncertain Store or lease result
+     * keeps the work retained and repeats the same decision.
+     */
+    async settleSourceAuthority(envelope, primary, target, restoreDeadlineReached, window) {
+        const owner = { ownerId: primary.ownerId, leaseGeneration: primary.ownerLeaseGeneration };
+        const store = this.requireLocationStore();
+        for (;;) {
+            if (this.disposed)
+                throw new Error('Relocation runtime stopped.');
+            await this.resendSourceCutover(window);
+            const observed = await this.readSourceSettlement(envelope, primary, target).catch(() => undefined);
+            if (observed?.kind === 'target')
+                return 'target';
+            if (observed?.kind === 'other')
+                return 'lost';
+            if (restoreDeadlineReached() && observed?.kind === 'source') {
+                // An unreadable lease is an uncertain result, not an expiry.
+                if (await this.exactSourceLeaseExpired(owner).catch(() => false))
+                    return 'lost';
+                const publication = this.codec.read(observed.current.payload);
+                const preserved = await store
+                    .compareExchangeAuthority({ value: primaryKey(envelope) }, observed.current.storeVersion, {
+                    kind: 'put',
+                    generationTransition: 'preserve',
+                    payload: publication === undefined
+                        ? observed.current.payload
+                        : this.codec.clear(observed.current.payload, publication.reference)
+                })
+                    .catch(() => undefined);
+                if (preserved?.kind === 'stored')
+                    return 'source';
+            }
+            // The caller awaits this settlement, so the retry timer keeps the loop alive.
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+    }
+    async readSourceSettlement(envelope, primary, target) {
+        const primaryAuthorityKey = primaryKey(envelope);
+        let committed = 0;
+        let primaryCurrent;
+        for (const participant of envelope.participants) {
+            const current = await this.requireLocationStore().readAuthority({
+                value: participant.key
+            });
+            if (current.kind !== 'snapshot')
+                return { kind: 'other' };
+            if (current.objectGeneration === participant.objectGeneration &&
+                current.ownerId === target.ownerId &&
+                current.ownerLeaseGeneration === target.ownerLeaseGeneration &&
+                current.authorityOwnerGeneration > participant.authorityOwnerGeneration &&
+                String(current.allocation.descriptor.rid) === target.nodeRid &&
+                current.allocation.descriptorLifecycleGeneration === target.nodeGeneration) {
+                committed += 1;
+            }
+            if (participant.key === primaryAuthorityKey)
+                primaryCurrent = current;
+        }
+        if (committed === envelope.participants.length)
+            return { kind: 'target' };
+        if (primaryCurrent !== undefined && isSourceOwner(primaryCurrent, primary)) {
+            return { kind: 'source', current: primaryCurrent };
+        }
+        return { kind: 'other' };
     }
     /**
      * True when every relocation this source started reached its Message
@@ -1611,6 +1739,7 @@ class ZLinkHostServiceRelocationRuntime {
         const envelope = (0, service_relocation_runtime_1.decodeServiceRelocationEnvelope)(payload, request.targetAttemptGeneration);
         const inventoryEnvelope = attachPrepareBoundSessions(await this.resolveTargetParticipantInventory(request, envelope, signal), request.nodeInternalBoundSessions);
         validatePrepareEnvelope(request, inventoryEnvelope);
+        const releaseActivation = (await this.options.activationAdmission?.acquire(meshName, signal)) ?? (() => undefined);
         let materialized;
         let reservation;
         try {
@@ -1620,13 +1749,12 @@ class ZLinkHostServiceRelocationRuntime {
             // rejects unrelated authority CAS until commit/abort.
             materialized = await this.materializeTargetEnvelope(meshName, inventoryEnvelope, signal);
             await materialized.owner.restoreSavedWork(materialized.staging, signal);
-            reservation = await this.reserveTargetForPrepare(meshName, request, inventoryEnvelope, materialized.target, signal);
+            reservation = await this.reserveTargetForPrepare(meshName, request, inventoryEnvelope, signal);
             const offer = {
                 prepare: request,
                 prepareFingerprint: fingerprint,
                 authenticatedSourceNodeRid: String(sourceNodeRid),
                 envelope: inventoryEnvelope,
-                restoreDeadlineAtMs: performance.now() + RELOCATION_OPERATION_RETENTION_MS,
                 reservation
             };
             const stage = {
@@ -1635,11 +1763,13 @@ class ZLinkHostServiceRelocationRuntime {
                 phase: 'ready',
                 lane: Promise.resolve(),
                 cutoverReceived: false,
-                boundaryRelay: []
+                boundaryRelay: [],
+                releaseActivation
             };
             this.targetStages.set(stagingId, stage);
         }
         catch (error) {
+            releaseActivation();
             if (reservation !== undefined) {
                 await this.abortTargetReservation(reservation, signal).catch(() => undefined);
             }
@@ -1650,12 +1780,25 @@ class ZLinkHostServiceRelocationRuntime {
         }
         return relocationReady(request);
     }
+    /**
+     * The cutover wait of a Ready stage (spec 28 §4.4) is a Warning only: it
+     * records `cutover_timeout` and never submits the target CAS or opens
+     * dispatch. From then on the target settlement reads the Location Store so
+     * a source Preserve fence or a lost target lease ends the staging; only a
+     * verified cutover lets that settlement submit the CAS.
+     */
     armTargetCutoverFallback(meshName, stagingId) {
         const stage = this.targetStages.get(stagingId);
         if (stage === undefined || stage.fallback !== undefined || stage.finalize !== undefined)
             return;
         stage.fallback = setTimeout(() => {
-            void this.beginTargetFinalize(meshName, stagingId, stage, true).catch((error) => console.error('[zlink.runtime.relocation.location_update_failed]', error));
+            if (stage.finalize !== undefined)
+                return;
+            console.warn('[zlink.runtime.relocation.cutover_timeout]', stagingId);
+            this.options.metrics?.count('zlink.relocation.cutover_timeout', 1, {
+                mesh_name: meshName
+            });
+            void this.beginTargetFinalize(meshName, stagingId, stage).catch((error) => console.error('[zlink.runtime.relocation.location_update_failed]', error));
         }, this.relocationLimits().relocationCutoverWaitTimeoutMs);
         stage.fallback.unref();
     }
@@ -1675,20 +1818,28 @@ class ZLinkHostServiceRelocationRuntime {
             throw new Error(`Relocation staging '${stagingId}' is missing.`);
         }
         validateTargetOneWayControl(stage, request, sourceNodeRid);
+        // A verified cutover closes the boundary batch. A later record or cutover
+        // is a duplicate retransmission and never changes the staged batch.
+        if (stage.cutoverReceived || (stage.phase !== 'ready' && stage.phase !== 'finalizing')) {
+            if (request.kind === 'cutover') {
+                console.warn('[zlink.runtime.relocation.late_cutover]', stagingId);
+            }
+            return;
+        }
         if (request.kind === 'data') {
             stage.lane = stage.lane.then(() => this.stageBoundaryRelay(stage, request));
             await stage.lane;
             return;
         }
-        if (stage.cutoverReceived || stage.phase !== 'ready') {
-            console.warn('[zlink.runtime.relocation.late_cutover]', stagingId);
-            return;
-        }
         this.reconcileBoundaryRelay(stage, request, stagingId);
         stage.cutoverReceived = true;
+        // A settlement started by the cutover wait Warning is still reading the
+        // Store; it submits the CAS on its next round now that cutover verified.
+        if (stage.finalize !== undefined)
+            return;
         if (stage.fallback !== undefined)
             clearTimeout(stage.fallback);
-        await this.beginTargetFinalize(meshName, stagingId, stage, false, signal);
+        await this.beginTargetFinalize(meshName, stagingId, stage, signal);
     }
     /** Validates one boundary relay record and buffers it until cutover applies it. */
     async stageBoundaryRelay(stage, request) {
@@ -1707,14 +1858,13 @@ class ZLinkHostServiceRelocationRuntime {
         }
         const expectedCount = Number(request.boundaryRecordCount);
         const staged = stage.boundaryRelay;
-        const checksumOf = (records) => (0, service_relocation_runtime_1.crc32c)(Buffer.concat(records.map((value) => value.frozenRecord.canonicalBytes)));
-        if (staged.length === expectedCount && checksumOf(staged) === request.boundaryChecksumCrc32c) {
-            return;
-        }
-        if (staged.length > expectedCount) {
-            const suffix = staged.slice(staged.length - expectedCount);
-            if (checksumOf(suffix) === request.boundaryChecksumCrc32c) {
-                console.warn('[zlink.runtime.relocation.boundary_batch_replaced]', stagingId);
+        // The batch is the last `boundaryRecordCount` records: the source sends
+        // the whole batch right before this cutover on the ordered connection,
+        // so a retransmission replaces an earlier partial span as a whole.
+        if (staged.length >= expectedCount) {
+            const batch = staged.slice(staged.length - expectedCount);
+            if ((0, service_relocation_runtime_1.crc32c)(Buffer.concat(batch.map((value) => value.frozenRecord.canonicalBytes))) ===
+                request.boundaryChecksumCrc32c) {
                 staged.splice(0, staged.length - expectedCount);
                 return;
             }
@@ -1724,18 +1874,14 @@ class ZLinkHostServiceRelocationRuntime {
         throw new Error(`Relocation cutover boundary confirmation mismatch for '${stagingId}' ` +
             `(staged=${staged.length} declared=${expectedCount}).`);
     }
-    beginTargetFinalize(meshName, stagingId, stage, fallback, signal) {
+    beginTargetFinalize(meshName, stagingId, stage, signal) {
         if (stage.finalize !== undefined)
             return stage.finalize;
-        if (fallback) {
-            console.warn('[zlink.runtime.relocation.cutover_timeout]', stagingId);
-            this.options.metrics?.count('zlink.relocation.cutover_timeout', 1, {
-                mesh_name: meshName
-            });
-        }
+        // Records staged before this point finish first. The settlement is not
+        // put on the lane, so a cutover that arrives while it waits for the
+        // authority result is still reconciled.
         const finalize = stage.lane.then(() => this.finalizeTargetStage(meshName, stagingId, stage, signal));
         stage.finalize = finalize;
-        stage.lane = finalize;
         return finalize;
     }
     async finalizeTargetStage(meshName, stagingId, stage, signal) {
@@ -1746,14 +1892,15 @@ class ZLinkHostServiceRelocationRuntime {
         let authority;
         let resumeStartedAt;
         try {
-            // The boundary relay span is applied to the temporary queue before the
-            // owner CAS so the merged order is saved work, pre-boundary relay, then
-            // post-boundary temporary records (spec 28 §4.6).
-            for (const relay of stage.boundaryRelay.splice(0)) {
-                await this.applyRelocationData(stage, relay, signal);
-            }
             authority = await this.commitTargetReservation(stage, stage.offer.reservation, signal);
+            if (authority === undefined) {
+                // Source Preserve, a definitive conflict or the target lease ended
+                // this staging before any target commit (Location runtime §10).
+                console.warn('[zlink.runtime.relocation.target_staging_discarded]', stagingId);
+                throw new Error(`Relocation '${stagingId}' target staging lost the authority settlement.`);
+            }
             authorityCommitted = true;
+            stage.releaseActivation();
             resumeStartedAt = performance.now();
             stage.phase = 'committed';
             await stage.owner.normalize(stage.staging, authority, signal);
@@ -1768,13 +1915,10 @@ class ZLinkHostServiceRelocationRuntime {
                 }
             }
             await this.finalizeActorJoinProfiles(meshName, stage, signal);
-            // Actor Join completion may advance its accepted-completion journal in
-            // the canonical authority slot. Try to clear that final publication
-            // before admission becomes externally visible so a later Join cannot
-            // reserve against the previous root. A bounded CAS conflict must not
-            // roll back already committed target ownership or strand its staged
-            // object: the next reservation recognizes the retained journal root and
-            // continues its existing cleanup/retry path.
+            // Clear the final relocation publication before admission becomes
+            // externally visible so a later Join cannot reserve against the
+            // previous root. A bounded CAS conflict must not roll back already
+            // committed target ownership or strand its staged object.
             try {
                 await this.clearTargetRelocationPublication(stage, authority, signal);
             }
@@ -1907,58 +2051,23 @@ class ZLinkHostServiceRelocationRuntime {
             throw new Error(`Relocation ${kind} was not accepted by RouteMesh.`);
         }
     }
-    async waitForTargetAuthorities(envelope, target, deadlineAtMs, signal) {
-        for (;;) {
-            signal?.throwIfAborted();
-            let exact = true;
-            for (const participant of envelope.participants) {
-                const current = await this.requireLocationStore().readAuthority({ value: participant.key }, signal);
-                if (current.kind !== 'snapshot' ||
-                    current.objectGeneration !== participant.objectGeneration ||
-                    current.ownerId !== target.ownerId ||
-                    current.ownerLeaseGeneration !== target.ownerLeaseGeneration ||
-                    current.authorityOwnerGeneration <= participant.authorityOwnerGeneration ||
-                    String(current.allocation.descriptor.rid) !== target.nodeRid ||
-                    current.allocation.descriptorLifecycleGeneration !== target.nodeGeneration) {
-                    exact = false;
-                    break;
-                }
-            }
-            if (exact)
-                return;
-            if (performance.now() >= deadlineAtMs) {
-                throw new Error('Relocation target owner was not confirmed before its original deadline.');
-            }
-            await new Promise((resolve) => setTimeout(resolve, 10));
-        }
-    }
     async clearTargetRelocationPublication(stage, primary, signal) {
         await this.releaseParticipantAuthorities(stage.staging.envelope, stage.staging.primaryAuthorityKey.value, signal);
-        //  The deferred-Join journal advances its completion cursor with its
-        //  own authority CAS while the target finalizes, so the initially
-        //  captured storeVersion can be stale by the time the relocation
-        //  wrapper is cleared. Re-read and retry on conflict instead of turning
-        //  a completed relocation into a post-commit failure (spec 28 —
-        //  retryable store conflicts converge on the same CAS and the same
-        //  relocation identity until the outcome is determined).
-        let current = primary;
-        for (let attempt = 0; attempt < 16; attempt += 1) {
-            const publication = this.codec.read(current.payload);
-            if (publication === undefined)
-                return;
-            const result = await this.requireLocationStore().compareExchangeAuthority(stage.staging.primaryAuthorityKey, current.storeVersion, {
-                kind: 'put',
-                generationTransition: 'preserve',
-                payload: this.codec.clear(current.payload, publication.reference)
-            }, signal);
-            if (result.kind === 'stored')
-                return;
-            const read = await this.requireLocationStore().readAuthority(stage.staging.primaryAuthorityKey, signal);
-            if (read.kind !== 'snapshot')
-                break;
-            current = read;
+        //  The target owner is the only writer of the committed primary
+        //  authority between its commit and this clear, so one CAS against the
+        //  committed snapshot decides. A conflict means another owner changed the
+        //  row; the caller records it and leaves the committed ownership intact.
+        const publication = this.codec.read(primary.payload);
+        if (publication === undefined)
+            return;
+        const result = await this.requireLocationStore().compareExchangeAuthority(stage.staging.primaryAuthorityKey, primary.storeVersion, {
+            kind: 'put',
+            generationTransition: 'preserve',
+            payload: this.codec.clear(primary.payload, publication.reference)
+        }, signal);
+        if (result.kind !== 'stored') {
+            throw new Error('Relocation target authority normalization CAS failed.');
         }
-        throw new Error('Relocation target authority normalization CAS failed.');
     }
     async handleReplyRelay(meshName, relay, sourceNodeRid, signal) {
         if (sourceNodeRid === null) {
@@ -2234,39 +2343,9 @@ class ZLinkHostServiceRelocationRuntime {
         }
         return authorities;
     }
-    async reserveTargetForPrepare(meshName, prepare, envelope, targetPort, signal) {
+    async reserveTargetForPrepare(meshName, prepare, envelope, signal) {
         const authorities = await this.readTargetParticipantAuthorities(envelope, signal);
         const publication = relocationPublication(prepare, envelope);
-        // Carries the exact reference + CRC of a deferred-Join publication the
-        // target reservation must keep connected through the CAS (spec 28 —
-        // clearing/replacing it here would strand the journal's own
-        // prepared->committed transition with nothing left for it to find).
-        const retainedDeferredJoinRoots = new Map();
-        for (const participant of envelope.participants) {
-            const staged = targetPort.deferredJoinRoot(participant.key);
-            if (staged !== undefined) {
-                retainedDeferredJoinRoots.set(participant.key, {
-                    reference: staged.reference.value,
-                    checksumCrc32c: staged.checksumCrc32c
-                });
-                continue;
-            }
-            const current = this.codec.read(authorities.get(participant.key).payload);
-            if (participant.objectKind === 'actor' &&
-                current?.canonical === true &&
-                (await this.options.actorTransfer.isDeferredJoinAcceptedRootPublication(current.reference, current.checksumCrc32c, {
-                    authorityKey: participant.key,
-                    objectKind: 'actor',
-                    objectGeneration: participant.objectGeneration,
-                    aggregateId: current.aggregateId,
-                    aggregateGeneration: current.aggregateGeneration
-                }, signal))) {
-                retainedDeferredJoinRoots.set(participant.key, {
-                    reference: current.reference,
-                    checksumCrc32c: current.checksumCrc32c
-                });
-            }
-        }
         const participants = envelope.participants.map((participant) => {
             const expected = authorities.get(participant.key);
             const membership = actorMembershipTarget(envelope, participant.key);
@@ -2278,19 +2357,11 @@ class ZLinkHostServiceRelocationRuntime {
                 entrySpotId === undefined) {
                 throw new Error(`Relocation target RouteMesh '${meshName}' has no Entry Spot.`);
             }
-            const retainedDeferredJoinRoot = retainedDeferredJoinRoots.get(participant.key);
-            const participantPublication = retainedDeferredJoinRoot === undefined
-                ? publication
-                : {
-                    ...publication,
-                    reference: retainedDeferredJoinRoot.reference,
-                    checksumCrc32c: retainedDeferredJoinRoot.checksumCrc32c
-                };
             return {
                 key: { value: participant.key },
                 expected,
                 ownerTransition: 'newOwner',
-                authorityPayload: this.authorityPayloadForPublication(expected.payload, participantPublication, {
+                authorityPayload: this.authorityPayloadForPublication(expected.payload, publication, {
                     owner: {
                         ownerId: prepare.target.ownerId,
                         leaseGeneration: prepare.target.ownerLeaseGeneration
@@ -2313,7 +2384,7 @@ class ZLinkHostServiceRelocationRuntime {
                             ...membership,
                             actorSpotKind: contracts_1.ZLinkSpotKind.User
                         })
-                }, retainedDeferredJoinRoot !== undefined),
+                }),
                 membershipMutation: encodeMembershipMutation(envelope.memberships, participant.key)
             };
         });
@@ -2332,19 +2403,13 @@ class ZLinkHostServiceRelocationRuntime {
             prepared: await new service_relocation_aggregate_committer_1.ServiceRelocationAggregateCommitter(this.requireLocationStore()).prepare(plan, signal)
         };
     }
-    authorityPayloadForPublication(payload, publication, target, replacesDeferredJoinRoot = false) {
+    authorityPayloadForPublication(payload, publication, target) {
         const existing = this.codec.read(payload);
         const canonicalIdentity = (0, service_relocation_runtime_1.serviceRelocationAuthoritySlotIdentity)(payload);
-        const replacesCanonicalJournal = replacesDeferredJoinRoot && existing?.canonical === true;
         if (canonicalIdentity !== undefined &&
             (existing === undefined ||
-                (existing.canonical === true &&
-                    (existing.aggregateId === publication.aggregateId || replacesCanonicalJournal)))) {
-            const published = existing === undefined
-                ? this.codec.publish(payload, publication)
-                : replacesCanonicalJournal && existing.aggregateId !== publication.aggregateId
-                    ? this.codec.publish(this.codec.clear(payload, existing.reference), publication)
-                    : payload;
+                (existing.canonical === true && existing.aggregateId === publication.aggregateId))) {
+            const published = existing === undefined ? this.codec.publish(payload, publication) : payload;
             if (target === undefined)
                 return published;
             return (0, service_relocation_runtime_1.projectServiceRelocationAuthorityTargetReady)((0, service_relocation_runtime_1.replaceServiceRelocationAuthorityApplicationPayload)(published, rewriteAuthorityApplicationRoute(published, target)), {
@@ -2394,6 +2459,7 @@ class ZLinkHostServiceRelocationRuntime {
     async abortTargetStage(stage, signal) {
         if (stage.fallback !== undefined)
             clearTimeout(stage.fallback);
+        stage.releaseActivation();
         const failures = [];
         try {
             await this.abortTargetReservation(stage.offer.reservation, signal);
@@ -2417,19 +2483,39 @@ class ZLinkHostServiceRelocationRuntime {
     async commitTargetReservation(stage, reservation, signal) {
         return await this.commitTargetAggregate(stage, reservation.prepared, signal);
     }
+    /**
+     * The one target authority settlement (Location runtime §10, spec 28
+     * §4.4-§4.5). Only a verified cutover lets the target submit its NewOwner
+     * CAS; a transient or indeterminate result resubmits the same RelocationId
+     * and expected StoreVersion while the target owner lease is valid (no
+     * separate timeout, no fixed count). Before a verified cutover the target
+     * only reads. It returns the committed authority, or undefined when a
+     * definitive Conflict excludes this commit after reconciliation, a source
+     * Preserve fence moved the source row, or the target lease ended; the
+     * caller then discards the staging.
+     */
     async commitTargetAggregate(stage, prepared, signal) {
-        let firstError;
+        const target = stage.offer.prepare.target;
         for (;;) {
             signal?.throwIfAborted();
-            let result;
-            try {
-                result = await this.requireLocationStore().commitAggregate(prepared.fence, signal);
-            }
-            catch (error) {
-                firstError ??= error;
-            }
-            if (result?.kind === 'stale' || result?.kind === 'generationExhausted') {
-                throw new Error(`location_update_failed: relocation aggregate commit returned ${result.kind}.`, { cause: firstError });
+            if (this.disposed)
+                throw new Error('Relocation runtime stopped.');
+            let conflict = false;
+            if (stage.cutoverReceived) {
+                // The boundary relay span is applied to the temporary queue before
+                // the owner CAS so the merged order is saved work, pre-boundary relay,
+                // then post-boundary temporary records (spec 28 §4.6).
+                for (const relay of stage.boundaryRelay.splice(0)) {
+                    await this.applyRelocationData(stage, relay, signal);
+                }
+                // A thrown provider call has an unknown result; the read below decides.
+                const result = await this.requireLocationStore()
+                    .commitAggregate(prepared.fence, signal)
+                    .catch(() => undefined);
+                if (result?.kind === 'generationExhausted') {
+                    throw new Error('location_update_failed: relocation aggregate commit exhausted.');
+                }
+                conflict = result?.kind === 'stale';
             }
             const observed = await this.readAggregateForCommitRetry(prepared, signal);
             if (observed.kind === 'committed') {
@@ -2439,12 +2525,13 @@ class ZLinkHostServiceRelocationRuntime {
                 }
                 return primary;
             }
-            if (observed.kind === 'stale') {
-                throw new Error('location_update_failed: relocation aggregate source authority became stale.', {
-                    cause: firstError
-                });
+            if (observed.kind === 'stale' || (conflict && observed.kind === 'source'))
+                return undefined;
+            // An unreadable lease is an uncertain result, not an expiry.
+            if (await this.exactSourceLeaseExpired({ ownerId: target.ownerId, leaseGeneration: target.ownerLeaseGeneration }, signal).catch(() => false)) {
+                return undefined;
             }
-            await waitForLocationRetry(stage.offer.restoreDeadlineAtMs, signal, firstError);
+            await waitForRelocationRetry(25, signal);
         }
     }
     async readAggregateForCommitRetry(prepared, signal) {
@@ -2708,6 +2795,17 @@ class ZLinkHostServiceRelocationRuntime {
             throw new Error('Host relocation requires the Spot manager.');
         return value;
     }
+    afterSpotCloseDecision(meshName, spotId, seal) {
+        const manager = this.requireSpotManager();
+        const sealAfterDecision = () => {
+            if (manager.isSpotClosing(meshName, spotId)) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, `Spot '${String(spotId)}' is closing.`, true);
+            }
+            return seal();
+        };
+        const decision = manager.pendingSpotCloseDecision(meshName, spotId);
+        return decision === undefined ? sealAfterDecision() : decision.then(sealAfterDecision);
+    }
     requireActorManager() {
         const value = this.options.actorManager();
         if (value === undefined)
@@ -2802,7 +2900,6 @@ class LocalTargetPort {
     options;
     meshName;
     envelope;
-    deferredJoinRoots = new Map();
     constructor(options, meshName, envelope) {
         this.options = options;
         this.meshName = meshName;
@@ -2955,10 +3052,7 @@ class LocalTargetPort {
             if (recovery.request.actorId !== hidden.actor.context.actorId) {
                 throw new Error('Canonical Actor Join recovery names a different staged Actor.');
             }
-            const deferred = await this.requireSpotManager().restoreCanonicalActorJoinRecovery(recovery, undefined, (0, service_relocation_runtime_1.inventoryDigest)(this.envelope.participants, this.envelope.memberships));
-            if (deferred !== undefined) {
-                this.deferredJoinRoots.set(hidden.authorityKey, deferred);
-            }
+            await this.requireSpotManager().restoreCanonicalActorJoinRecovery(recovery);
             return;
         }
         const packet = decodeQueuedHandoffPacket(message);
@@ -2967,9 +3061,6 @@ class LocalTargetPort {
             throw new Error('Relocated Actor state is not staged.');
         hidden.replayPackets.push(packet);
     }
-    deferredJoinRoot(authorityKey) {
-        return this.deferredJoinRoots.get(authorityKey);
-    }
     async openAdmission(hidden) {
         if (hidden.actor === undefined)
             return;
@@ -3324,8 +3415,11 @@ function sameCoordinator(left, right) {
         left.expectedAuthorityStoreVersion === right.expectedAuthorityStoreVersion);
 }
 function isExactSourceAuthority(current, expected) {
-    return (current.storeVersion.value === expected.storeVersion.value &&
-        current.objectGeneration === expected.objectGeneration &&
+    return (current.storeVersion.value === expected.storeVersion.value && isSourceOwner(current, expected));
+}
+/** The same source tenure owns the row, at any StoreVersion. */
+function isSourceOwner(current, expected) {
+    return (current.objectGeneration === expected.objectGeneration &&
         current.authorityOwnerGeneration === expected.authorityOwnerGeneration &&
         current.ownerId === expected.ownerId &&
         current.ownerLeaseGeneration === expected.ownerLeaseGeneration &&
@@ -3345,26 +3439,6 @@ function isExactCommittedTarget(current, expected, target, payload) {
         current.allocation.descriptorLifecycleGeneration === target.nodeGeneration &&
         Buffer.from(current.payload).equals(Buffer.from(payload)));
 }
-async function waitForLocationRetry(deadlineAtMs, signal, cause) {
-    signal?.throwIfAborted();
-    if (performance.now() >= deadlineAtMs) {
-        throw new Error('location_update_failed: relocation Restore validity expired before exact target owner confirmation.', { cause });
-    }
-    await new Promise((resolve, reject) => {
-        let timer;
-        const aborted = () => {
-            if (timer !== undefined)
-                clearTimeout(timer);
-            reject(signal?.reason);
-        };
-        signal?.addEventListener('abort', aborted, { once: true });
-        timer = setTimeout(() => {
-            signal?.removeEventListener('abort', aborted);
-            resolve();
-        }, Math.min(25, Math.max(1, deadlineAtMs - performance.now())));
-        timer.unref();
-    });
-}
 async function waitForRelocationRetry(delayMs, signal) {
     signal?.throwIfAborted();
     await new Promise((resolve, reject) => {
@@ -3379,7 +3453,6 @@ async function waitForRelocationRetry(delayMs, signal) {
             signal?.removeEventListener('abort', aborted);
             resolve();
         }, delayMs);
-        timer.unref();
     });
 }
 function sameRequestSource(left, right) {