@zlink-systems/framework 0.31.0 → 0.32.1

package/src/runtime/host/service-relocation-host-runtime.ts

@@ -4,7 +4,7 @@ import { inspectRuntime } from '../internal-observation';
 import { encodeActorReply } from '../actors/actor-reply';
 import { ZLinkStreamMessageKind } from '../streams/protocol';
 import {
-  decodeApplicationPayloadView,
+  decodeApplicationPayload,
   encodeMultipartApplicationPayload
 } from '../foundation/service-wire-m6a-codec';
 import {
@@ -80,6 +80,7 @@ import {
   flowIfEnabled,
   type ZLinkMessageFlowTracer
 } from '../diagnostics/message-flow';
+import { currentFlowContext } from '../diagnostics/flow-context';
 import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
 import { isStructuralGuardEnabled, trackDiagnosticCompletion } from '../execution/state-lane';
 import {
@@ -276,7 +277,7 @@ interface ZLinkHostRelocationOptions {
     clear?(): void | Promise<void>;
   };
   readonly trackInstanceSpot?: (input: ZLinkTrackedInstanceAuthority) => void;
-  readonly invalidateActorRoute?: (actorId: string) => void;
+  readonly observeActorAuthorityVersion?: (actorId: string, storeVersion: string) => void;
   readonly reconcileStatefulAuthorityRoutes?: (signal?: AbortSignal) => Promise<void>;
   readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
   readonly metrics?: ZLinkRuntimeMetrics;
@@ -437,13 +438,13 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     });
   }
 
-  private readonly targetStages = new Map<string, LocalStage>();
+  readonly targetStages = new Map<string, LocalStage>();
   private readonly terminalTargets = new BoundedReplayMap<string, string>(
     RELOCATION_TARGET_TOMBSTONE_LIMIT
   );
-  private readonly targetPrepareOperations = new Map<string, TargetPrepareOperation>();
+  readonly targetPrepareOperations = new Map<string, TargetPrepareOperation>();
   private readonly pendingReplyRelays = new Map<string, PendingRelocationReplyRelay>();
-  private readonly pendingSessionRelocations = new Map<string, PendingSessionRelocation>();
+  readonly pendingSessionRelocations = new Map<string, PendingSessionRelocation>();
   private readonly terminalSessionRelocations = new BoundedReplayMap<
     string,
     TerminalSessionRelocationControl
@@ -457,7 +458,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     SERVICE_CONTROL_TERMINAL_CAPACITY
   );
   private readonly sourceRelocationIds = new Set<string>();
-  private readonly targetAssemblies = new Map<string, TargetPayloadAssembly>();
+  readonly targetAssemblies = new Map<string, TargetPayloadAssembly>();
   /**
    * Terminal restore failures (assembly/checksum/factory/restore error): the
    * target already sent relocationFailed (command 53) once. An exact-identity
@@ -484,7 +485,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   private readonly terminalActorJoinSourceLeaves = new BoundedReplayMap<string, string>(
     SERVICE_CONTROL_TERMINAL_CAPACITY
   );
-  private readonly codec = new ServiceRelocationAuthorityPayloadCodec();
+  readonly codec = new ServiceRelocationAuthorityPayloadCodec();
   /**
    * Set once dispose() starts tearing assemblies down. A payload() rejection
    * observed after this point is the shutdown itself, not a chunk-assembly or
@@ -493,7 +494,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   private disposed = false;
   private readonly targetPreparationStop = new AbortController();
 
-  constructor(private readonly options: ZLinkHostRelocationOptions) {}
+  constructor(readonly options: ZLinkHostRelocationOptions) {}
 
   async relocateActorJoin(
     input: Parameters<ZLinkActorJoinRelocation['relocateActorJoin']>[0]
@@ -1129,7 +1130,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   }
 
   /** Sends the Ready reply once the async restore finished; failures replay on resend. */
-  private async deliverTargetReady(
+  async deliverTargetReady(
     meshName: string,
     operationKey: string,
     request: ServiceMaintenanceRelocationPrepare,
@@ -1681,7 +1682,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async relocateSpotAggregate(
+  async relocateSpotAggregate(
     meshName: string,
     activation: ZLinkSpotActivation,
     kind: 'user_spot' | 'instance_spot',
@@ -1962,7 +1963,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     const relocationMetric =
       spotRegistration.relocation.kind === 'disabled'
         ? undefined
-        : this.options.metrics?.startRelocation(meshName, kind, spotRegistration.relocation.kind);
+        : this.startSourceRelocationMetric(meshName, kind, spotRegistration.relocation.kind);
     try {
       const waitForRelocationBoundary = (
         activation as unknown as {
@@ -2041,7 +2042,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async relocateStandaloneActor(
+  async relocateStandaloneActor(
     meshName: string,
     state: ZLinkActorRuntimeState,
     target: ZLinkMeshNodeDescriptor | undefined,
@@ -2115,7 +2116,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     const relocationMetric =
       actorPolicy === 'disabled'
         ? undefined
-        : this.options.metrics?.startRelocation(meshName, 'actor', actorPolicy);
+        : this.startSourceRelocationMetric(meshName, 'actor', actorPolicy, state.actorId);
     try {
       if (isRelocationDebugEnabled()) {
         relocationDebug('standalone_actor.wait_budget', {
@@ -2158,7 +2159,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async relocatePerActorSpotShell(
+  async relocatePerActorSpotShell(
     meshName: string,
     activation: ZLinkSpotActivation,
     target: ZLinkMeshNodeDescriptor | undefined,
@@ -2277,11 +2278,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     const relocationMetric =
       spotRegistration.relocation.kind === 'disabled'
         ? undefined
-        : this.options.metrics?.startRelocation(
-            meshName,
-            'user_spot',
-            spotRegistration.relocation.kind
-          );
+        : this.startSourceRelocationMetric(meshName, 'user_spot', spotRegistration.relocation.kind);
     try {
       await this.waitForRelocationBudgetHeadroom(String(target.rid), signal);
       const captured = await new ServiceRelocationObjectCaptureOwner().captureUserSpotAggregate(
@@ -2473,7 +2470,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     this.sourceRelocationIds.add(id);
   }
 
-  private async runCoordinator(
+  async runCoordinator(
     meshName: string,
     target: ZLinkMeshNodeDescriptor,
     primary: ZLinkAuthoritySnapshot,
@@ -2802,6 +2799,50 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     );
   }
 
+  startSourceRelocationMetric(
+    meshName: string,
+    objectKind: 'actor' | 'user_spot' | 'instance_spot',
+    policy: 'recreate' | 'snapshot',
+    actorId?: string
+  ): ZLinkRelocationMetricOperation | undefined {
+    const flow = objectKind === 'actor' ? this.options.messageFlow?.() : undefined;
+    const flowContext = flow?.flowCreationEnabled() === true ? currentFlowContext() : undefined;
+    const traceTerminal = (outcome: string): void => {
+      if (flow === undefined || flowContext === undefined) return;
+      const result =
+        outcome === 'completed' ? 'succeeded' : outcome === 'shutdown' ? 'shutdown' : 'failed';
+      flowIfEnabled(flow, ZLinkMessageFlowOutcome.Completed, result, flowContext.flowId)?.trace({
+        outcome: ZLinkMessageFlowOutcome.Completed,
+        result,
+        surface: ZLinkDispatchErrorSurface.ActorRelocation,
+        messageKind: ZLinkDispatchMessageKind.Control,
+        meshName,
+        actorId,
+        flowId: flowContext.flowId,
+        flowOrigin: flowContext.flowOrigin,
+        errorMessage: result === 'failed' ? `source_relocation_${outcome}` : undefined
+      });
+    };
+    const metric = this.options.metrics?.startRelocation(
+      meshName,
+      objectKind,
+      policy,
+      traceTerminal
+    );
+    if (metric !== undefined) return metric;
+    if (flow === undefined || flowContext === undefined) return undefined;
+
+    let completed = false;
+    return {
+      recordBytes: (): void => {},
+      complete: (outcome: string): void => {
+        if (completed) return;
+        completed = true;
+        traceTerminal(outcome);
+      }
+    };
+  }
+
   /** Streams the payload chunks of one stage under the effective in-flight budgets. */
   private async sendRelocationStateChunks(
     meshName: string,
@@ -2864,10 +2905,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   }
 
   /** Pre-seal admission wait — a full budget delays the next unit before seal. */
-  private async waitForRelocationBudgetHeadroom(
-    targetRid: string,
-    signal?: AbortSignal
-  ): Promise<void> {
+  async waitForRelocationBudgetHeadroom(targetRid: string, signal?: AbortSignal): Promise<void> {
     await this.requireNodePayloadBudget().waitForHeadroom(signal);
     await this.requirePeerPayloadBudget(targetRid).waitForHeadroom(signal);
   }
@@ -2954,7 +2992,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   }
 
   /** Relocation flow §4.4: replay the whole batch on a different ready route. */
-  private async resendSourceCutover(window: SourceCutoverWindow): Promise<void> {
+  async resendSourceCutover(window: SourceCutoverWindow): Promise<void> {
     const frames = window.frames;
     if (frames === undefined) return;
     const route = this.requireMeshNode(window.meshName).observePeerRoute?.(window.targetNodeRid);
@@ -2986,7 +3024,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
    * A committed later owner has no Follow snapshot (Location runtime §10). An uncertain
    * Store or lease result keeps the work retained and repeats the same decision.
    */
-  private async settleSourceAuthority(
+  async settleSourceAuthority(
     envelope: ServiceRelocationEnvelope,
     primary: ZLinkAuthoritySnapshot,
     target: ServiceWireRelocationTarget,
@@ -3098,7 +3136,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return this.sourceCutoverWindows.size === 0;
   }
 
-  private async releaseParticipantAuthorities(
+  async releaseParticipantAuthorities(
     envelope: ServiceRelocationEnvelope,
     primaryKey: string,
     signal?: AbortSignal
@@ -3122,11 +3160,17 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
       if (result.kind !== 'stored') {
         throw new Error(`Participant '${participant.key}' recovery pointer release failed.`);
       }
+      if (participant.objectKind === 'actor') {
+        this.options.observeActorAuthorityVersion?.(
+          decodeAuthorityKey(key).globalId,
+          result.storeVersion.value
+        );
+      }
     }
   }
 
   /** Restores the hidden object and its saved-work prefix before Ready. */
-  private async handlePrepareControl(
+  async handlePrepareControl(
     meshName: string,
     stagingId: string,
     request: ServiceMaintenanceRelocationPrepare,
@@ -3384,7 +3428,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
    * whole (the retransmission always resends the entire batch, so the exact
    * span is the staged suffix of `boundaryRecordCount` records).
    */
-  private reconcileBoundaryRelay(
+  reconcileBoundaryRelay(
     stage: LocalStage,
     request: ServiceMaintenanceRelocationCutover,
     stagingId: string
@@ -3415,7 +3459,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     );
   }
 
-  private beginTargetFinalize(
+  beginTargetFinalize(
     meshName: string,
     stagingId: string,
     stage: LocalStage,
@@ -3432,7 +3476,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return finalize;
   }
 
-  private async finalizeTargetStage(
+  async finalizeTargetStage(
     meshName: string,
     stagingId: string,
     stage: LocalStage,
@@ -3484,15 +3528,6 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
           );
       }
       await stage.owner.normalize(stage.staging, authority, signal);
-      // The target may have visited this Actor before and still retain that
-      // tenure in its private Actor-client resolver. The target-only CAS is
-      // now authoritative, so expire the old projection before OnJoinedActor
-      // can issue an Actor request and deadlock behind source leave.
-      for (const hidden of stage.staging.hidden.values()) {
-        if (hidden.actor !== undefined) {
-          this.options.invalidateActorRoute?.(hidden.actor.context.actorId);
-        }
-      }
       await this.finalizeActorJoinProfiles(meshName, stage, signal);
       await this.publishSessionRoutes(stage.staging);
       stage.phase = 'open';
@@ -3572,7 +3607,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     );
   }
 
-  private async finalizeActorJoinProfiles(
+  async finalizeActorJoinProfiles(
     meshName: string,
     stage: LocalStage,
     signal?: AbortSignal
@@ -3605,7 +3640,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async submitActorJoinSourceLeave(
+  async submitActorJoinSourceLeave(
     meshName: string,
     sourceNodeRid: RoutingId,
     relocationId: string,
@@ -3631,7 +3666,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private acceptActorJoinSourceLeave(input: {
+  acceptActorJoinSourceLeave(input: {
     readonly transferId: string;
     readonly actorId: string;
     readonly succeeded: boolean;
@@ -3671,7 +3706,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     );
   }
 
-  private async submitControlFrame(
+  async submitControlFrame(
     meshName: string,
     targetNodeRid: RoutingId,
     frame: Buffer,
@@ -3685,7 +3720,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async clearTargetRelocationPublication(
+  async clearTargetRelocationPublication(
     stage: LocalStage,
     primary: ZLinkAuthoritySnapshot,
     signal?: AbortSignal
@@ -3714,6 +3749,12 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     if (result.kind !== 'stored') {
       throw new Error('Relocation target authority normalization CAS failed.');
     }
+    if (primary.allocation.objectKind === 'actor') {
+      this.options.observeActorAuthorityVersion?.(
+        decodeAuthorityKey(stage.staging.primaryAuthorityKey).globalId,
+        result.storeVersion.value
+      );
+    }
     return { ...result, kind: 'snapshot' };
   }
 
@@ -3793,7 +3834,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async sendReplyRelay(
+  async sendReplyRelay(
     meshName: string,
     ackTargetNodeRid: RoutingId,
     request: ServiceMaintenanceReplyRelay,
@@ -3911,7 +3952,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private targetReplyRelayCoordinator(
+  targetReplyRelayCoordinator(
     meshName: string,
     stage: LocalStage,
     authority: ZLinkAuthoritySnapshot
@@ -3937,7 +3978,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     };
   }
 
-  private async relayTerminalReply(
+  async relayTerminalReply(
     meshName: string,
     stage: LocalStage,
     coordinator: ServiceWireRelocationCoordinatorFence,
@@ -3987,9 +4028,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     );
   }
 
-  private async publishSessionRoutes(
-    staging: ServiceObjectRelocationStaging<LocalHidden>
-  ): Promise<void> {
+  async publishSessionRoutes(staging: ServiceObjectRelocationStaging<LocalHidden>): Promise<void> {
     for (const [key, hidden] of staging.hidden) {
       if (hidden.actor === undefined) continue;
       // The Session seal travels with the relocation envelope, not the Actor.
@@ -4001,7 +4040,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async sendControl(
+  async sendControl(
     meshName: string,
     targetNodeRid: RoutingId,
     request: ZLinkServiceRelocationControlRequest,
@@ -4132,7 +4171,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return authorities;
   }
 
-  private async reserveTargetForPrepare(
+  async reserveTargetForPrepare(
     meshName: string,
     prepare: ServiceMaintenanceRelocationPrepare,
     envelope: ServiceRelocationEnvelope,
@@ -4206,7 +4245,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     };
   }
 
-  private authorityPayloadForPublication(
+  authorityPayloadForPublication(
     payload: Uint8Array,
     publication: ServiceRelocationPublication,
     target?: {
@@ -4337,7 +4376,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async commitTargetReservation(
+  async commitTargetReservation(
     stage: LocalStage,
     reservation: TargetRelocationReservation,
     signal?: AbortSignal
@@ -4412,7 +4451,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     }
   }
 
-  private async readAggregateForCommitRetry(
+  async readAggregateForCommitRetry(
     prepared: ServicePreparedRelocationAggregate,
     signal?: AbortSignal
   ): Promise<
@@ -4460,7 +4499,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return source === prepared.plan.participants.length ? { kind: 'source' } : { kind: 'stale' };
   }
 
-  private async materializeTargetEnvelope(
+  async materializeTargetEnvelope(
     meshName: string,
     envelope: ServiceRelocationEnvelope,
     signal?: AbortSignal
@@ -4478,7 +4517,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
   }
 
   /** Maps schema ordinals to the authoritative Location Store inventory. */
-  private async resolveTargetParticipantInventory(
+  async resolveTargetParticipantInventory(
     meshName: string,
     request: ServiceMaintenanceRelocationPrepare,
     envelope: ServiceRelocationEnvelope,
@@ -4635,7 +4674,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return value;
   }
 
-  private async captureApplication<T>(
+  async captureApplication<T>(
     policy: { readonly kind: 'disabled' | 'recreate' | 'snapshot'; readonly adapterType?: Type },
     value: T,
     signal?: AbortSignal
@@ -4776,11 +4815,7 @@ export class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocati
     return value;
   }
 
-  private afterSpotCloseDecision<T>(
-    meshName: string,
-    spotId: RoutingId,
-    seal: () => T
-  ): T | Promise<T> {
+  afterSpotCloseDecision<T>(meshName: string, spotId: RoutingId, seal: () => T): T | Promise<T> {
     const manager = this.requireSpotManager();
     const sealAfterDecision = (): T => {
       if (manager.isSpotClosing(meshName, spotId)) {
@@ -5129,6 +5164,7 @@ class LocalTargetPort implements ServiceRelocationTargetObjectPort<LocalHidden>
         value: hidden.authorityKey
       } as ZLinkAuthorityKey);
       const actorId = hidden.actor.context.actorId;
+      this.options.observeActorAuthorityVersion?.(actorId, current.storeVersion.value);
       const node = this.options.meshNode(this.meshName);
       const restore = node?.restoreActorAuthority;
       if (node === undefined || restore === undefined) {
@@ -5836,7 +5872,7 @@ function maintenanceReplyRelay(
   const direct = packet.messageFollowOrigin?.requestSource !== undefined;
   const application =
     direct && completion.result.ok
-      ? decodeApplicationPayloadView(
+      ? decodeApplicationPayload(
           encodeMultipartApplicationPayload(
             encodeActorReply(
               Buffer.from(packet.header, 'base64'),

package/src/runtime/host/spot-address-transport.ts

@@ -263,55 +263,53 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
     return this.requests.request(timeoutMs, call.signal, async (requestOperation) => {
       const deadline = createSpotAddressDeadline(requestOperation, call.signal);
       try {
-        const resolution = await waitRequestReply(
-          this.resolveExisting(spotId, deadline.signal, call),
-          'Spot address resolve',
-          requestOperation,
-          () => deadline.close()
-        );
-        const existing =
-          resolution !== undefined && !('kind' in resolution) ? resolution : undefined;
-        if (resolution !== undefined && 'kind' in resolution)
-          call = this.reactivationCall(resolution, call);
-        deadline.requireRemaining();
-        if (existing === undefined) {
-          return await this.requestToMissingInstance(spotId, request, call, deadline, resolution);
-        }
-        this.validateExisting(existing, call);
-        try {
-          return await this.requestToExistingSpot(spotId, request, call, existing, deadline);
-        } catch (error) {
-          if (isSpotRouteRefreshError(error)) {
-            this.options.resolver()?.invalidate?.(spotId);
-          }
-          // Failover policy §4.4: SpotMoving is the owner's Ready owner-fence
-          // refusal, made before admission. With Instance intent, one authority
-          // read under the same deadline decides: Missing means Close released
-          // the incarnation, so the request activates a new one. Any other
-          // answer, and any message the owner admitted, keeps this terminal.
-          if (
-            call.instanceSpot &&
-            isOwnerFenceRefusal(error) &&
-            (await waitRequestReply(
-              this.resolveExisting(spotId, deadline.signal),
-              'Spot address resolve',
-              requestOperation,
-              () => deadline.close()
-            )) === undefined
-          ) {
-            deadline.requireRemaining();
-            return await this.requestToMissingInstance(spotId, request, call, deadline);
-          }
-          this.reportInstanceRequestError(
-            spotId,
-            request,
-            error,
-            existing.routerChannelId,
-            existing.targetNodeRid,
-            existing.stableType,
-            addressedInstanceErrorReason(error)
+        for (;;) {
+          deadline.requireRemaining();
+          const resolution = await waitRequestReply(
+            this.resolveExisting(spotId, deadline.signal, call),
+            'Spot address resolve',
+            requestOperation,
+            () => deadline.close()
           );
-          throw error;
+          const existing =
+            resolution !== undefined && !('kind' in resolution) ? resolution : undefined;
+          if (resolution !== undefined && 'kind' in resolution)
+            call = this.reactivationCall(resolution, call);
+          deadline.requireRemaining();
+          try {
+            if (existing === undefined) {
+              return await this.requestToMissingInstance(
+                spotId,
+                request,
+                call,
+                deadline,
+                resolution
+              );
+            }
+            this.validateExisting(existing, call);
+            return await this.requestToExistingSpot(spotId, request, call, existing, deadline);
+          } catch (error) {
+            if (
+              (existing !== undefined || isPreAdmissionStaleRoute(error)) &&
+              isSpotRouteRefreshError(error)
+            ) {
+              this.options.resolver()?.invalidate?.(spotId);
+            }
+            // §9 keeps admission-before-stale-route handling in this logical request.
+            if (call.instanceSpot && isPreAdmissionStaleRoute(error)) continue;
+            if (existing !== undefined) {
+              this.reportInstanceRequestError(
+                spotId,
+                request,
+                error,
+                existing.routerChannelId,
+                existing.targetNodeRid,
+                existing.stableType,
+                addressedInstanceErrorReason(error)
+              );
+            }
+            throw error;
+          }
         }
       } catch (error) {
         if (
@@ -348,9 +346,13 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
       existing.stableType,
       existing.targetNodeRid
     );
-    const reply = await waitRequestReply(
-      mapZLinkRequestReply(
-        this.options.routed.requestToSpot<TReply>(existing, request, {
+    // The address request owns the terminal entry. Observe the wire stage so
+    // a pre-admission refusal can reach the authority decision in §9.
+    const stage = new Promise<TReply>((resolve, reject) => {
+      const result = this.options.routed.requestToSpot<TReply>(
+        existing,
+        request,
+        {
           instanceSpot: call.instanceSpot,
           timeoutMs: deadline.requireRemaining(),
           deadlineMs: deadline.deadlineMs,
@@ -358,11 +360,15 @@ export class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport
           metadata: call.metadata,
           onAdmitted: call.onAdmitted,
           requestOperation: deadline.operation
-        })
-      ),
-      'Spot request',
-      deadline.operation
-    );
+        },
+        {
+          operationCompleted: (_id, value) => resolve(value as TReply),
+          operationFailed: (_id, error) => reject(error)
+        }
+      );
+      if (result.operation === undefined) void mapZLinkRequestReply(result).then(resolve, reject);
+    });
+    const reply = await waitRequestReply(stage, 'Spot request', deadline.operation);
     this.traceInstanceAddress(
       ZLinkMessageFlowOutcome.ReplyReceived,
       ZLinkDispatchMessageKind.Request,
@@ -778,19 +784,19 @@ function isSpotRouteRefreshError(error: unknown): error is ZLinkFrameworkExcepti
   if (!(error instanceof ZLinkFrameworkException)) return false;
   const kind = internalFrameworkErrorKind(error);
   return (
+    isPreAdmissionStaleRoute(error) ||
     kind === ZLinkFrameworkInternalErrorKind.SpotRouteNotFound ||
-    kind === ZLinkFrameworkInternalErrorKind.SpotGenerationStale ||
-    kind === ZLinkFrameworkInternalErrorKind.SpotMoving ||
     kind === ZLinkFrameworkInternalErrorKind.RequestTargetNotFound ||
-    kind === ZLinkFrameworkInternalErrorKind.ActorLocationStale ||
     kind === ZLinkFrameworkInternalErrorKind.RouteNotConnected
   );
 }
 
-function isOwnerFenceRefusal(error: unknown): boolean {
+function isPreAdmissionStaleRoute(error: unknown): boolean {
   return (
     error instanceof ZLinkFrameworkException &&
-    internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.SpotMoving
+    (internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.SpotMoving ||
+      internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.ActorLocationStale ||
+      internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.SpotGenerationStale)
   );
 }