@zlink-systems/framework 0.31.0 → 0.32.0

package/dist/runtime/host/service-relocation-host-runtime.d.ts

@@ -1,23 +1,30 @@
 import type { RequestRuntime } from '../foundation/request-runtime';
 import { inspectRuntime } from '../internal-observation';
-import { type RoutingId, type ZLinkMeshNodeDescriptor } from '../../contracts';
+import { type RoutingId, type Type, type ZLinkActor, type ZLinkMeshNodeDescriptor, ZLinkSpotKind } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkActivationAdmission } from '../activation-admission';
 import type { DefaultZLinkActorManager } from '../actors';
-import { type ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import { type ZLinkActorHandoffPacket, type ZLinkActorHandoffResult } from '../actors/actor-handoff';
 import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
+import { type ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
 import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
 import type { ZLinkFrameworkRegistration } from '../configuration';
-import { type ZLinkRuntimeEventPublisher, type ZLinkRuntimeMetrics } from '../diagnostics';
+import { type ZLinkRuntimeEventPublisher, type ZLinkRelocationMetricOperation, type ZLinkRuntimeMetrics } from '../diagnostics';
 import { type ZLinkMessageFlowTracer } from '../diagnostics/message-flow';
-import { type ServiceRelocationQueuedMessage } from '../foundation/service-relocation-runtime';
+import { type ServicePreparedRelocationAggregate } from '../foundation/service-relocation-aggregate-committer';
+import { ServiceRelocationObjectRestoreOwner, type ServiceCapturedObjectRelocation, type ServiceObjectRelocationStaging, type ServiceRelocationHiddenObject, type ServiceRelocationTargetObjectPort } from '../foundation/service-relocation-object-owner';
+import { ServiceRelocationAuthorityPayloadCodec, type ServiceRelocationEnvelope, type ServiceRelocationMembership, type ServiceRelocationParticipant, type ServiceRelocationPublication, type ServiceRelocationQueuedMessage } from '../foundation/service-relocation-runtime';
 import { type ReceiveRecord } from '../foundation/service-runtime-contracts';
-import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed } from '../foundation/service-stateful-wire-codec';
+import { type ServiceMaintenanceRelocationCutover, type ServiceMaintenanceRelocationData, type ServiceMaintenanceRelocationPrepare, type ServiceMaintenanceRelocationReady, type ServiceMaintenanceReplyRelay, type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed, type ServiceWireRelocationCoordinatorFence, type ServiceWireRelocationTarget, type ServiceWireRequestSourceFence } from '../foundation/service-stateful-wire-codec';
 import type { ZLinkDomainLocationStore as ZLinkLocationStore } from '../locations/domain-store-contract';
-import type { ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
 import type { ZLinkTrackedInstanceAuthority } from '../locations/spot-location-claims';
 import type { DefaultZLinkSpotManager } from '../spots';
+import type { ZLinkSpotActivation } from '../spots/spot-activation-state';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import { type ZLinkActorTransferRuntime } from './actor-transfer-runtime';
+import { ZLinkRelocationPayloadAssembly } from './relocation-direct-transfer';
+import { decodeServiceRelocationControlResponse, type ZLinkServiceRelocationControlRequest } from './service-relocation-control';
 export declare class ZLinkRelocationStateIncompatibleError extends Error {
     constructor(message: string);
 }
@@ -45,15 +52,92 @@ 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;
     readonly activationAdmission?: ZLinkActivationAdmission;
 }
+interface LocalHidden extends ServiceRelocationHiddenObject {
+    readonly participant: ServiceRelocationParticipant;
+    readonly actor?: ZLinkActor;
+    readonly activation?: ZLinkSpotActivation;
+    initialized: boolean;
+    replayStart?: Promise<void>;
+    onReplayResult?: (packet: ZLinkActorHandoffPacket, result: ZLinkActorHandoffResult) => Promise<void>;
+    readonly replayPackets: ZLinkActorHandoffPacket[];
+    targetAuthorityOwnerGeneration?: bigint;
+}
+interface LocalStage {
+    readonly offer: TargetRelocationOffer;
+    readonly owner: ServiceRelocationObjectRestoreOwner<LocalHidden>;
+    readonly staging: ServiceObjectRelocationStaging<LocalHidden>;
+    phase: 'ready' | 'finalizing' | 'committed' | 'open' | 'failed';
+    lane: Promise<void>;
+    cutoverReceived: boolean;
+    /** Boundary relay records buffered until cutover (or fallback) applies them. */
+    readonly boundaryRelay: ServiceMaintenanceRelocationData[];
+    fallback?: ReturnType<typeof setTimeout>;
+    finalize?: Promise<void>;
+    /** The Restore's activation admission (MeshNode §5.1); held until target commit or abort. */
+    readonly releaseActivation: () => void;
+    readonly releaseJoinAdmission: () => void;
+}
+interface TargetPayloadAssembly {
+    readonly prepare: ServiceMaintenanceRelocationPrepare;
+    readonly fingerprint: string;
+    readonly authenticatedSourceNodeRid: string;
+    readonly assembly: ZLinkRelocationPayloadAssembly;
+}
+/** One authority read decides commit and the snapshots eligible for Follow. */
+type SourceAuthorityCommit = {
+    readonly kind: 'target';
+    readonly followAuthorities: ReadonlyMap<string, ZLinkAuthoritySnapshot>;
+};
+interface SourceCutoverWindow {
+    readonly meshName: string;
+    readonly targetNodeRid: RoutingId;
+    /** Boundary batch frames plus the cutover frame, retained until authority settlement. */
+    frames?: readonly Buffer[];
+    /** The ready route used to submit the retained batch. */
+    submittedRouteGeneration?: bigint;
+    readonly cutoverSubmittedAtMs: number;
+    followTimer?: ReturnType<typeof setTimeout>;
+    windowClosed: boolean;
+    followExpired: boolean;
+}
+interface TargetRelocationReservation {
+    readonly prepared: ServicePreparedRelocationAggregate;
+}
+interface TargetRelocationOffer {
+    readonly prepare: ServiceMaintenanceRelocationPrepare;
+    readonly prepareFingerprint: string;
+    readonly authenticatedSourceNodeRid: string;
+    readonly envelope: ServiceRelocationEnvelope;
+    readonly reservation: TargetRelocationReservation;
+}
+interface TargetPrepareOperation {
+    readonly fingerprint: string;
+    readonly promise: Promise<ServiceMaintenanceRelocationReady>;
+}
+interface SourceActorSession {
+    readonly state: ZLinkActorRuntimeState;
+    readonly actor: ZLinkActor;
+    readonly prepared: Awaited<ReturnType<ZLinkActorTransferRuntime['prepareMaintenanceSession']>>;
+}
+interface PendingSessionRelocation {
+    readonly targetNodeRid: string;
+    readonly request: ServiceSessionRelocationSeal;
+    readonly requestFingerprint: string;
+    readonly promise: Promise<ServiceSessionRelocationSealed>;
+    readonly resolve: (response: ServiceSessionRelocationSealed) => void;
+    readonly reject: (error: unknown) => void;
+    retryTimer?: ReturnType<typeof setTimeout>;
+    deadlineTimer?: ReturnType<typeof setTimeout>;
+}
 /** Production host bridge from Retire inventory to remote RouteMesh owners. */
 export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoinRelocation {
-    private readonly options;
+    readonly options: ZLinkHostRelocationOptions;
     [inspectRuntime](): Readonly<{
         targetStages: number;
         targetAssemblies: number;
@@ -64,11 +148,11 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
         }> | undefined;
         terminalTargets: number;
     }>;
-    private readonly targetStages;
+    readonly targetStages: Map<string, LocalStage>;
     private readonly terminalTargets;
-    private readonly targetPrepareOperations;
+    readonly targetPrepareOperations: Map<string, TargetPrepareOperation>;
     private readonly pendingReplyRelays;
-    private readonly pendingSessionRelocations;
+    readonly pendingSessionRelocations: Map<string, PendingSessionRelocation>;
     private readonly terminalSessionRelocations;
     /**
      * A command 44 submit has no response path. Keep a bounded record of a
@@ -77,7 +161,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      */
     private readonly failedSessionRouteSubmits;
     private readonly sourceRelocationIds;
-    private readonly targetAssemblies;
+    readonly targetAssemblies: Map<string, TargetPayloadAssembly>;
     /**
      * Terminal restore failures (assembly/checksum/factory/restore error): the
      * target already sent relocationFailed (command 53) once. An exact-identity
@@ -96,7 +180,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private nodePayloadBudget?;
     private readonly sourceActorJoinProfiles;
     private readonly terminalActorJoinSourceLeaves;
-    private readonly codec;
+    readonly codec: ServiceRelocationAuthorityPayloadCodec;
     /**
      * Set once dispose() starts tearing assemblies down. A payload() rejection
      * observed after this point is the shutdown itself, not a chunk-assembly or
@@ -122,7 +206,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     tryHandleControl(meshName: string, record: ReceiveRecord, signal?: AbortSignal): boolean | Promise<boolean>;
     private handleControl;
     /** Sends the Ready reply once the async restore finished; failures replay on resend. */
-    private deliverTargetReady;
+    deliverTargetReady(meshName: string, operationKey: string, request: ServiceMaintenanceRelocationPrepare, ingress: ReceiveRecord, operation: Promise<ServiceMaintenanceRelocationReady>): Promise<void>;
     /** Cleans up a Ready reply that never delivered within the Restore validity window. */
     private expireTargetReadyResponse;
     /**
@@ -145,16 +229,24 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private handleSessionRelocationRoute;
     private validateSessionOwnerFence;
     private sendSessionRelocationResponse;
-    private relocateSpotAggregate;
+    relocateSpotAggregate(meshName: string, activation: ZLinkSpotActivation, kind: 'user_spot' | 'instance_spot', actorStates: readonly ZLinkActorRuntimeState[], target: ZLinkMeshNodeDescriptor | undefined, targetApplicationVersion: bigint | undefined, signal?: AbortSignal): Promise<void>;
     private relocateSpotAggregateCore;
-    private relocateStandaloneActor;
-    private relocatePerActorSpotShell;
+    relocateStandaloneActor(meshName: string, state: ZLinkActorRuntimeState, target: ZLinkMeshNodeDescriptor | undefined, targetApplicationVersion: bigint | undefined, signal?: AbortSignal, targetMembership?: ZLinkSpotRouteTarget & {
+        readonly spotKind: ZLinkSpotKind.Entry | ZLinkSpotKind.User;
+        readonly spotObjectGeneration: bigint;
+    }, aggregateIdOverride?: string, retainSourceForActorJoin?: boolean, 
+    /** Target's advertised relocation state chunk cap (Actor Join only; spec 15 §4.2). */
+    advertisedReceiveChunkLimitBytes?: number, deadlineAtMs?: number): Promise<void>;
+    relocatePerActorSpotShell(meshName: string, activation: ZLinkSpotActivation, target: ZLinkMeshNodeDescriptor | undefined, targetApplicationVersion: bigint | undefined, signal?: AbortSignal): Promise<void>;
     private relocatePerActorSpotShellCore;
     private actorCaptureUnit;
     private reserveRelocationId;
     private reserveExactRelocationId;
-    private runCoordinator;
+    runCoordinator(meshName: string, target: ZLinkMeshNodeDescriptor, primary: ZLinkAuthoritySnapshot, captured: ServiceCapturedObjectRelocation, _authorities: ReadonlyMap<string, ZLinkAuthoritySnapshot>, signal?: AbortSignal, sessions?: readonly SourceActorSession[], 
+    /** Target's advertised relocation state chunk cap (Actor Join only; spec 15 §4.2). */
+    advertisedReceiveChunkLimitBytes?: number, controlDeadlineAtMs?: number, relocationMetric?: ZLinkRelocationMetricOperation): Promise<void>;
     private completeSourceRelocationMetric;
+    startSourceRelocationMetric(meshName: string, objectKind: 'actor' | 'user_spot' | 'instance_spot', policy: 'recreate' | 'snapshot', actorId?: string): ZLinkRelocationMetricOperation | undefined;
     /** Streams the payload chunks of one stage under the effective in-flight budgets. */
     private sendRelocationStateChunks;
     /**
@@ -163,7 +255,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      */
     private acquireRelocationBudget;
     /** Pre-seal admission wait — a full budget delays the next unit before seal. */
-    private waitForRelocationBudgetHeadroom;
+    waitForRelocationBudgetHeadroom(targetRid: string, signal?: AbortSignal): Promise<void>;
     private requireNodePayloadBudget;
     private requirePeerPayloadBudget;
     /**
@@ -178,7 +270,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
     private closeSourceCutoverWindow;
     private releaseSourceCutoverWindow;
     /** Relocation flow §4.4: replay the whole batch on a different ready route. */
-    private resendSourceCutover;
+    resendSourceCutover(window: SourceCutoverWindow): Promise<void>;
     /**
      * The one source authority settlement after request creation (Location runtime
      * §6.1·§10, spec 28 §4.4). It reads the Store until the target commit or
@@ -191,7 +283,7 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      * 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 settleSourceAuthority;
+    settleSourceAuthority(envelope: ServiceRelocationEnvelope, primary: ZLinkAuthoritySnapshot, target: ServiceWireRelocationTarget, restoreDeadlineReached: () => boolean, window: SourceCutoverWindow | undefined, relocationMetric?: ZLinkRelocationMetricOperation): Promise<SourceAuthorityCommit | 'source' | 'lost'>;
     private readSourceSettlement;
     /**
      * True when every relocation this source started reached its Message
@@ -199,9 +291,9 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      * ended — both source-local events (spec 30 §11).
      */
     isSafeToShutdown(): boolean;
-    private releaseParticipantAuthorities;
+    releaseParticipantAuthorities(envelope: ServiceRelocationEnvelope, primaryKey: string, signal?: AbortSignal): Promise<void>;
     /** Restores the hidden object and its saved-work prefix before Ready. */
-    private handlePrepareControl;
+    handlePrepareControl(meshName: string, stagingId: string, request: ServiceMaintenanceRelocationPrepare, sourceNodeRid: RoutingId, signal?: AbortSignal): Promise<ServiceMaintenanceRelocationReady>;
     /**
      * 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
@@ -219,34 +311,49 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      * whole (the retransmission always resends the entire batch, so the exact
      * span is the staged suffix of `boundaryRecordCount` records).
      */
-    private reconcileBoundaryRelay;
-    private beginTargetFinalize;
-    private finalizeTargetStage;
+    reconcileBoundaryRelay(stage: LocalStage, request: ServiceMaintenanceRelocationCutover, stagingId: string): void;
+    beginTargetFinalize(meshName: string, stagingId: string, stage: LocalStage, signal?: AbortSignal): Promise<void>;
+    finalizeTargetStage(meshName: string, stagingId: string, stage: LocalStage, signal?: AbortSignal): Promise<void>;
     private validateRelocationData;
     private applyRelocationData;
-    private finalizeActorJoinProfiles;
-    private submitActorJoinSourceLeave;
-    private acceptActorJoinSourceLeave;
+    finalizeActorJoinProfiles(meshName: string, stage: LocalStage, signal?: AbortSignal): Promise<void>;
+    submitActorJoinSourceLeave(meshName: string, sourceNodeRid: RoutingId, relocationId: string, actorId: string): Promise<void>;
+    acceptActorJoinSourceLeave(input: {
+        readonly transferId: string;
+        readonly actorId: string;
+        readonly succeeded: boolean;
+    }): boolean;
     private sendControlOneWay;
-    private submitControlFrame;
-    private clearTargetRelocationPublication;
+    submitControlFrame(meshName: string, targetNodeRid: RoutingId, frame: Buffer, kind: string): Promise<void>;
+    clearTargetRelocationPublication(stage: LocalStage, primary: ZLinkAuthoritySnapshot, signal?: AbortSignal): Promise<ZLinkAuthoritySnapshot>;
     private handleReplyRelay;
-    private sendReplyRelay;
+    sendReplyRelay(meshName: string, ackTargetNodeRid: RoutingId, request: ServiceMaintenanceReplyRelay, expectedRequestSource: ServiceWireRequestSourceFence, signal?: AbortSignal): Promise<RelocationTerminalDelivery>;
     private acceptReplyRelayAck;
     private requireAdmittedPeer;
-    private targetReplyRelayCoordinator;
-    private relayTerminalReply;
+    targetReplyRelayCoordinator(meshName: string, stage: LocalStage, authority: ZLinkAuthoritySnapshot): ServiceWireRelocationCoordinatorFence;
+    relayTerminalReply(meshName: string, stage: LocalStage, coordinator: ServiceWireRelocationCoordinatorFence, participantId: bigint, packet: ZLinkActorHandoffPacket, result: ZLinkActorHandoffResult, signal?: AbortSignal): Promise<void>;
     private exactSourceLeaseExpired;
-    private publishSessionRoutes;
-    private sendControl;
+    publishSessionRoutes(staging: ServiceObjectRelocationStaging<LocalHidden>): Promise<void>;
+    sendControl(meshName: string, targetNodeRid: RoutingId, request: ZLinkServiceRelocationControlRequest, signal?: AbortSignal, deadlineAtMs?: number, onSubmitted?: (signal: AbortSignal) => Promise<void>): Promise<ReturnType<typeof decodeServiceRelocationControlResponse>>;
     private selectTarget;
     private readTargetParticipantAuthorities;
-    private reserveTargetForPrepare;
-    private authorityPayloadForPublication;
+    reserveTargetForPrepare(meshName: string, prepare: ServiceMaintenanceRelocationPrepare, envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<TargetRelocationReservation>;
+    authorityPayloadForPublication(payload: Uint8Array, publication: ServiceRelocationPublication, target?: {
+        readonly owner: ZLinkLocationOwnerToken;
+        readonly meshName: string;
+        readonly nodeRid: string;
+        readonly nodeGeneration: bigint;
+        readonly objectGeneration: bigint;
+        readonly targetAttemptGeneration: bigint;
+        readonly coordinatorExpectedStoreVersion: string;
+        readonly actorSpotId?: string;
+        readonly actorSpotGeneration?: bigint;
+        readonly actorSpotKind?: ZLinkSpotKind.Entry | ZLinkSpotKind.User;
+    }): Uint8Array;
     private abortTargetReservation;
     private abortTargetStage;
     private discardTargetStage;
-    private commitTargetReservation;
+    commitTargetReservation(stage: LocalStage, reservation: TargetRelocationReservation, signal?: AbortSignal): Promise<ZLinkAuthoritySnapshot | undefined>;
     /**
      * The one target authority settlement (Location runtime §10, spec 28
      * §4.4-§4.5). Only a verified cutover lets the target submit its NewOwner
@@ -259,27 +366,57 @@ export declare class ZLinkHostServiceRelocationRuntime implements ZLinkActorJoin
      * caller then discards the staging.
      */
     private commitTargetAggregate;
-    private readAggregateForCommitRetry;
-    private materializeTargetEnvelope;
+    readAggregateForCommitRetry(prepared: ServicePreparedRelocationAggregate, signal?: AbortSignal): Promise<{
+        readonly kind: 'committed';
+        readonly authorities: ReadonlyMap<string, ZLinkAuthoritySnapshot>;
+    } | {
+        readonly kind: 'source' | 'unknown' | 'stale';
+    }>;
+    materializeTargetEnvelope(meshName: string, envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<Pick<LocalStage, 'owner' | 'staging'> & {
+        readonly target: LocalTargetPort;
+    }>;
     /** Maps schema ordinals to the authoritative Location Store inventory. */
-    private resolveTargetParticipantInventory;
+    resolveTargetParticipantInventory(meshName: string, request: ServiceMaintenanceRelocationPrepare, envelope: ServiceRelocationEnvelope, signal?: AbortSignal): Promise<ServiceRelocationEnvelope>;
     private spotKind;
     private spotRegistration;
     private actorRegistration;
-    private captureApplication;
+    captureApplication<T>(policy: {
+        readonly kind: 'disabled' | 'recreate' | 'snapshot';
+        readonly adapterType?: Type;
+    }, value: T, signal?: AbortSignal): Promise<Uint8Array>;
     private createRelocationAdapter;
     private recordRelocationInterruption;
     private sealSpotMessageFollow;
     private commitSpotMessageFollow;
     private requireLocationStore;
     private requireSpotManager;
-    private afterSpotCloseDecision;
+    afterSpotCloseDecision<T>(meshName: string, spotId: RoutingId, seal: () => T): T | Promise<T>;
     private requireActorManager;
     private relocationLimits;
     private requireMeshNode;
     private sendInfrastructureControl;
     private requestInfrastructureControl;
 }
+declare class LocalTargetPort implements ServiceRelocationTargetObjectPort<LocalHidden> {
+    private readonly options;
+    private readonly meshName;
+    private readonly envelope;
+    constructor(options: ZLinkHostRelocationOptions, meshName: string, envelope: ServiceRelocationEnvelope);
+    createHidden(participant: ServiceRelocationParticipant, signal?: AbortSignal): Promise<LocalHidden>;
+    restoreApplicationState(hidden: LocalHidden, payload: Uint8Array, signal?: AbortSignal): Promise<void>;
+    restoreMemberships(hidden: ReadonlyMap<string, LocalHidden>, memberships: readonly ServiceRelocationMembership[]): Promise<void>;
+    publish(hidden: LocalHidden, authority: ZLinkAuthoritySnapshot): Promise<void>;
+    restoreBoundSession(hidden: LocalHidden, payload: Uint8Array): Promise<void>;
+    replayQueuedMessage(hidden: LocalHidden, message: ServiceRelocationQueuedMessage): Promise<void>;
+    openAdmission(hidden: LocalHidden): Promise<void>;
+    normalize(hidden: LocalHidden): Promise<void>;
+    abort(hidden: LocalHidden): Promise<void>;
+    private registration;
+    private requireLocationStore;
+    private requireSpotManager;
+    private requireActorManager;
+}
+type RelocationTerminalDelivery = 'terminalReceived' | 'alreadyTerminal' | 'sourceLeaseExpired';
 export declare function decodeQueuedHandoffPacket(message: ServiceRelocationQueuedMessage): ZLinkActorHandoffPacket;
 export declare function createServiceRelocationId(isInUse: (candidate: string) => boolean, entropy?: (size: number) => Uint8Array): string;
 /**

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

@@ -25,6 +25,7 @@ const runtime_values_1 = require("../backend/runtime-values");
 const diagnostics_1 = require("../diagnostics");
 const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 const message_flow_1 = require("../diagnostics/message-flow");
+const flow_context_1 = require("../diagnostics/flow-context");
 const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
 const state_lane_1 = require("../execution/state-lane");
 const actor_join_recovery_codec_1 = require("../foundation/actor-join-recovery-codec");
@@ -1212,7 +1213,7 @@ class ZLinkHostServiceRelocationRuntime {
         }));
         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.waitForRelocationBoundary;
             readinessBoundaryConsumed =
@@ -1288,7 +1289,7 @@ class ZLinkHostServiceRelocationRuntime {
         };
         const relocationMetric = actorPolicy === 'disabled'
             ? undefined
-            : this.options.metrics?.startRelocation(meshName, 'actor', actorPolicy);
+            : this.startSourceRelocationMetric(meshName, 'actor', actorPolicy, state.actorId);
         try {
             if ((0, diagnostics_1.isRelocationDebugEnabled)()) {
                 (0, diagnostics_1.relocationDebug)('standalone_actor.wait_budget', {
@@ -1390,7 +1391,7 @@ class ZLinkHostServiceRelocationRuntime {
         const aggregateId = this.reserveRelocationId();
         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 service_relocation_object_owner_1.ServiceRelocationObjectCaptureOwner().captureUserSpotAggregate(aggregateId, 1n, spotUnit, [], [], signal);
@@ -1765,6 +1766,41 @@ class ZLinkHostServiceRelocationRuntime {
                         ? 'shutdown'
                         : 'failed');
     }
+    startSourceRelocationMetric(meshName, objectKind, policy, actorId) {
+        const flow = objectKind === 'actor' ? this.options.messageFlow?.() : undefined;
+        const flowContext = flow?.flowCreationEnabled() === true ? (0, flow_context_1.currentFlowContext)() : undefined;
+        const traceTerminal = (outcome) => {
+            if (flow === undefined || flowContext === undefined)
+                return;
+            const result = outcome === 'completed' ? 'succeeded' : outcome === 'shutdown' ? 'shutdown' : 'failed';
+            (0, message_flow_1.flowIfEnabled)(flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, result, flowContext.flowId)?.trace({
+                outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed,
+                result,
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ActorRelocation,
+                messageKind: ZLinkDispatchOptions_1.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: () => { },
+            complete: (outcome) => {
+                if (completed)
+                    return;
+                completed = true;
+                traceTerminal(outcome);
+            }
+        };
+    }
     /** Streams the payload chunks of one stage under the effective in-flight budgets. */
     async sendRelocationStateChunks(meshName, target, identity, encoded, plan, signal) {
         for (let ordinal = 0; ordinal < plan.chunkCount; ordinal += 1) {
@@ -2009,6 +2045,9 @@ class ZLinkHostServiceRelocationRuntime {
             if (result.kind !== 'stored') {
                 throw new Error(`Participant '${participant.key}' recovery pointer release failed.`);
             }
+            if (participant.objectKind === 'actor') {
+                this.options.observeActorAuthorityVersion?.((0, authority_key_codec_1.decodeAuthorityKey)(key).globalId, result.storeVersion.value);
+            }
         }
     }
     /** Restores the hidden object and its saved-work prefix before Ready. */
@@ -2304,15 +2343,6 @@ class ZLinkHostServiceRelocationRuntime {
                 hidden.onReplayResult = (packet, result) => this.relayTerminalReply(meshName, stage, coordinator, BigInt(index + 1), packet, result, signal);
             }
             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';
@@ -2449,6 +2479,9 @@ class ZLinkHostServiceRelocationRuntime {
         if (result.kind !== 'stored') {
             throw new Error('Relocation target authority normalization CAS failed.');
         }
+        if (primary.allocation.objectKind === 'actor') {
+            this.options.observeActorAuthorityVersion?.((0, authority_key_codec_1.decodeAuthorityKey)(stage.staging.primaryAuthorityKey).globalId, result.storeVersion.value);
+        }
         return { ...result, kind: 'snapshot' };
     }
     async handleReplyRelay(meshName, relay, sourceNodeRid, signal) {
@@ -3406,6 +3439,7 @@ class LocalTargetPort {
                 value: hidden.authorityKey
             });
             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) {
@@ -3897,7 +3931,7 @@ function maintenanceReplyRelay(stage, coordinator, participantId, completion, pa
     const value = completion.result.ok ? completion.result.response : undefined;
     const direct = packet.messageFollowOrigin?.requestSource !== undefined;
     const application = direct && completion.result.ok
-        ? (0, service_wire_m6a_codec_1.decodeApplicationPayloadView)((0, service_wire_m6a_codec_1.encodeMultipartApplicationPayload)((0, actor_reply_1.encodeActorReply)(Buffer.from(packet.header, 'base64'), protocol_1.ZLinkStreamMessageKind.Response, value, serializers, flowEnabled), service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME, service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE))
+        ? (0, service_wire_m6a_codec_1.decodeApplicationPayload)((0, service_wire_m6a_codec_1.encodeMultipartApplicationPayload)((0, actor_reply_1.encodeActorReply)(Buffer.from(packet.header, 'base64'), protocol_1.ZLinkStreamMessageKind.Response, value, serializers, flowEnabled), service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_PACKET_NAME, service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE))
         : undefined;
     return {
         relocation: relocationWireId(stage.staging.envelope.aggregateId),

package/dist/runtime/host/spot-address-transport.js

@@ -100,35 +100,33 @@ class ZLinkHostSpotAddressTransport {
         return this.requests.request(timeoutMs, call.signal, async (requestOperation) => {
             const deadline = createSpotAddressDeadline(requestOperation, call.signal);
             try {
-                const resolution = await (0, request_deadline_1.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);
+                for (;;) {
+                    deadline.requireRemaining();
+                    const resolution = await (0, request_deadline_1.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();
+                    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);
                     }
-                    // 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 (0, request_deadline_1.waitRequestReply)(this.resolveExisting(spotId, deadline.signal), 'Spot address resolve', requestOperation, () => deadline.close())) === undefined) {
-                        deadline.requireRemaining();
-                        return await this.requestToMissingInstance(spotId, request, call, 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;
                     }
-                    this.reportInstanceRequestError(spotId, request, error, existing.routerChannelId, existing.targetNodeRid, existing.stableType, addressedInstanceErrorReason(error));
-                    throw error;
                 }
             }
             catch (error) {
@@ -145,15 +143,25 @@ class ZLinkHostSpotAddressTransport {
     }
     async requestToExistingSpot(spotId, request, call, existing, deadline) {
         this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, existing.routerChannelId, existing.stableType, existing.targetNodeRid);
-        const reply = await (0, request_deadline_1.waitRequestReply)((0, request_result_1.mapZLinkRequestReply)(this.options.routed.requestToSpot(existing, request, {
-            instanceSpot: call.instanceSpot,
-            timeoutMs: deadline.requireRemaining(),
-            deadlineMs: deadline.deadlineMs,
-            signal: deadline.signal,
-            metadata: call.metadata,
-            onAdmitted: call.onAdmitted,
-            requestOperation: deadline.operation
-        })), 'Spot request', deadline.operation);
+        // 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((resolve, reject) => {
+            const result = this.options.routed.requestToSpot(existing, request, {
+                instanceSpot: call.instanceSpot,
+                timeoutMs: deadline.requireRemaining(),
+                deadlineMs: deadline.deadlineMs,
+                signal: deadline.signal,
+                metadata: call.metadata,
+                onAdmitted: call.onAdmitted,
+                requestOperation: deadline.operation
+            }, {
+                operationCompleted: (_id, value) => resolve(value),
+                operationFailed: (_id, error) => reject(error)
+            });
+            if (result.operation === undefined)
+                void (0, request_result_1.mapZLinkRequestReply)(result).then(resolve, reject);
+        });
+        const reply = await (0, request_deadline_1.waitRequestReply)(stage, 'Spot request', deadline.operation);
         this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, existing.routerChannelId, existing.stableType, existing.targetNodeRid);
         return reply;
     }
@@ -367,16 +375,16 @@ function isSpotRouteRefreshError(error) {
     if (!(error instanceof contracts_1.ZLinkFrameworkException))
         return false;
     const kind = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
-    return (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound ||
-        kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale ||
-        kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving ||
+    return (isPreAdmissionStaleRoute(error) ||
+        kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound ||
         kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound ||
-        kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale ||
         kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected);
 }
-function isOwnerFenceRefusal(error) {
+function isPreAdmissionStaleRoute(error) {
     return (error instanceof contracts_1.ZLinkFrameworkException &&
-        (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving);
+        ((0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving ||
+            (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale ||
+            (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale));
 }
 function submitResultReason(status) {
     switch (status) {

package/dist/runtime/locations/auto-connect-loop.d.ts

@@ -13,7 +13,6 @@ export interface ZLinkAutoConnectLoopOptions {
     readonly clearTimer?: (handle: unknown) => void;
 }
 export declare class ZLinkAutoConnectLoop {
-    private readonly lane;
     private readonly reconciler;
     private readonly options;
     private readonly meshName;