@zlink-systems/framework 0.29.1 → 0.30.1

package/dist/runtime/host/index.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkUserSpotCreationCoordinator = exports.ZLinkHostSpotAddressTransport = exports.ZLinkRelocationStateIncompatibleError = exports.ZLinkRouteMeshRuntimeCoordinator = exports.ZLinkRetiringRollbackError = exports.ZLinkDrainingStatePublishError = exports.transferIdString = exports.ZLinkActorTransferAuthorityRuntime = exports.ZLinkFrameworkRuntimeHost = void 0;
 exports.hasUnsupportedManualTopology = hasUnsupportedManualTopology;
 exports.hasExactPeerReadiness = hasExactPeerReadiness;
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const location_store_pages_1 = require("../locations/location-store-pages");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
+const node_util_1 = require("node:util");
 const contracts_1 = require("../../contracts");
 const ConfigurationException_1 = require("../../contracts/Configuration/ConfigurationException");
 const DiagnosticsValidation_1 = require("../../contracts/Configuration/DiagnosticsValidation");
@@ -21,7 +23,7 @@ const actor_message_follow_context_1 = require("../actors/actor-message-follow-c
 const actor_transport_delivery_gate_1 = require("../actors/actor-transport-delivery-gate");
 const admission_1 = require("../admission");
 const application_job_queue_handler_start_gate_1 = require("../application-jobs/application-job-queue-handler-start-gate");
-const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const application_job_queue_scope_2 = require("../application-jobs/application-job-queue-scope");
 const backend_1 = require("../backend");
 const runtime_message_1 = require("../backend/runtime-message");
 const runtime_values_1 = require("../backend/runtime-values");
@@ -76,7 +78,7 @@ class ZLinkFrameworkRuntimeHost {
     lifecycleSink;
     executionState;
     runtimeState = contracts_1.ZLinkFrameworkRuntimeState.Preparing;
-    runtimeSequence = 0n;
+    runtimeStatus;
     runtimeObservationSource = Symbol('zlink.framework-runtime');
     runtimeDeadline;
     shutdownDeadline;
@@ -152,16 +154,8 @@ class ZLinkFrameworkRuntimeHost {
         this.runtimeEventPublisher =
             options.runtimeEventPublisher ?? new diagnostics_1.DefaultZLinkRuntimeEventPublisher();
         this.metrics = new diagnostics_1.ZLinkRuntimeMetrics(options.registration.metrics?.meterProvider);
-        this.applicationJobQueue = new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)(options.registration.applicationJobQueue, () => (0, application_job_queue_1.nodeEffectiveProcessorCount)(options.registration.worker?.maxThreads)), undefined, () => {
-            try {
-                return (this.options.providerResolver
-                    ?.get?.(application_job_queue_handler_start_gate_1.ZLINK_INTERNAL_APPLICATION_JOB_QUEUE_HANDLER_START_GATE)
-                    ?.shouldHoldPermitBeforeHandler() === true);
-            }
-            catch {
-                return false;
-            }
-        });
+        const handlerStartGate = options.providerResolver?.get?.(application_job_queue_handler_start_gate_1.ZLINK_INTERNAL_APPLICATION_JOB_QUEUE_HANDLER_START_GATE);
+        this.applicationJobQueue = new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)(options.registration.applicationJobQueue, () => (0, application_job_queue_1.nodeEffectiveProcessorCount)(options.registration.worker?.maxThreads)), undefined, handlerStartGate?.shouldHoldPermitBeforeHandler.bind(handlerStartGate), (error) => (this.errorSink ?? this.preStartErrorSink).reportRuntimeTaskException('logger-provider', error));
         this.capacityStatus = new host_capacity_status_1.HostCapacityStatusProjection(options.registration.coreHwm, this.applicationJobQueue);
         this.clientServerRuntime = new topology_runtime_projections_1.ZLinkClientServerRuntimeProjection(() => this.channelRuntime, () => this.runtimeState);
         this.fanoutRuntime = new topology_runtime_projections_1.ZLinkFanoutRuntimeProjection(() => this.channelRuntime, () => this.runtimeState);
@@ -452,12 +446,12 @@ class ZLinkFrameworkRuntimeHost {
             },
             sessionRelocationWire: () => this.serviceRelocation,
             clearRemoteActorPacketTarget: (actorId) => this.boundSessionRelay.clearRemoteActorPacketTarget(actorId),
-            prepareApplicationJob: async (preparationSignal) => {
+            prepareApplicationJob: async (preparationSignal, origin) => {
                 const runtimeSignal = this.executionState?.abortController.signal;
                 const signal = runtimeSignal === undefined
                     ? preparationSignal
                     : AbortSignal.any([runtimeSignal, preparationSignal]);
-                const permit = await this.applicationJobQueue.acquire(signal);
+                const permit = await this.applicationJobQueue.acquire(signal, origin);
                 let state = 'ready';
                 let closedReason;
                 let abort;
@@ -491,7 +485,7 @@ class ZLinkFrameworkRuntimeHost {
                         state = 'running';
                         signal.removeEventListener('abort', abort);
                         try {
-                            return await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(permit, operation);
+                            return await (0, application_job_queue_scope_2.runWithApplicationJobPermit)(permit, operation);
                         }
                         finally {
                             state = 'closed';
@@ -508,6 +502,7 @@ class ZLinkFrameworkRuntimeHost {
         this.serviceRelocation = new service_relocation_host_runtime_1.ZLinkHostServiceRelocationRuntime({
             registration: options.registration,
             targetAdmissionSealed: () => this.shutdownOperationStartedAt !== undefined,
+            sourceQuiescenceChanged: () => this.publishCurrentRuntimeStatus(),
             providerResolver: options.providerResolver,
             locationStore: () => this.locationOwner.currentStores?.locationStore,
             currentOwner: () => this.locationOwner.currentRuntime?.currentOwnerToken,
@@ -581,6 +576,9 @@ class ZLinkFrameworkRuntimeHost {
         return this.executionState !== undefined && !this.executionState.abortController.signal.aborted;
     }
     get status() {
+        return this.publishCurrentRuntimeStatus();
+    }
+    buildRuntimeStatus() {
         return {
             state: this.runtimeState,
             isReady: (0, runtime_state_projections_1.runtimeStateIsReady)(this.runtimeState),
@@ -590,8 +588,8 @@ class ZLinkFrameworkRuntimeHost {
             deadline: this.runtimeDeadline,
             relocationResult: this.runtimeRelocationResult,
             terminationResult: this.runtimeTerminationResult,
-            sequence: this.runtimeSequence,
-            observedAt: new Date()
+            sequence: this.runtimeStatus?.sequence ?? 0n,
+            observedAt: this.runtimeStatus?.observedAt ?? new Date()
         };
     }
     // Bound listener records of the current runtime generation.
@@ -604,10 +602,11 @@ class ZLinkFrameworkRuntimeHost {
         return { kind, name, endpoint, observedAt: new Date() };
     }
     observe(signal) {
+        const status = this.status;
         const queue = new runtime_observation_queue_1.RuntimeEventQueue(undefined, signal);
         this.runtimeObservers.add(queue);
         queue.onClose(() => this.runtimeObservers.delete(queue));
-        this.publishRuntimeStatus(queue, this.status);
+        this.publishRuntimeStatus(queue, status);
         return queue;
     }
     resetCapacityMetrics() {
@@ -770,6 +769,9 @@ class ZLinkFrameworkRuntimeHost {
                 const shutdown = this.routeMeshCoordinator.shutdownHost(this.runtimeDeadline, this.shutdownDeadline.signal);
                 const drain = await shutdown;
                 await unscopedStreamDrain;
+                if (drain.kind === 'forceStopped' && drain.error !== undefined) {
+                    this.runtimeOrPreStartErrorSink.reportRuntimeTaskException('host shutdown', drain.error);
+                }
                 await this.stop();
                 if (drain.kind === 'forceStopped') {
                     return this.completeTermination({
@@ -891,12 +893,24 @@ class ZLinkFrameworkRuntimeHost {
         if (this.runtimeState === state)
             return;
         this.runtimeState = state;
-        this.runtimeSequence += 1n;
         this.notifyTopologyHostStateChanged();
-        const status = this.status;
+        this.publishCurrentRuntimeStatus();
+    }
+    publishCurrentRuntimeStatus() {
+        const current = this.buildRuntimeStatus();
+        if (this.runtimeStatus !== undefined && (0, node_util_1.isDeepStrictEqual)(this.runtimeStatus, current)) {
+            return this.runtimeStatus;
+        }
+        const status = {
+            ...current,
+            sequence: (this.runtimeStatus?.sequence ?? 0n) + 1n,
+            observedAt: new Date()
+        };
+        this.runtimeStatus = status;
         for (const observer of this.runtimeObservers) {
             this.publishRuntimeStatus(observer, status);
         }
+        return status;
     }
     publishRuntimeStatus(observer, status) {
         if ((0, runtime_state_projections_1.runtimeObservationIsTerminal)(status.state)) {
@@ -1245,6 +1259,7 @@ class ZLinkFrameworkRuntimeHost {
             }
             activationNode.registerAsyncInstanceActivationAuthority?.(new instance_activation_authority_1.ZLinkInstanceActivationAuthority({
                 store: locationStore,
+                relocationPolicy: (stableType) => this.options.registration.spotNodes.get(meshName)?.instanceSpotFactoryRegistrations?.[stableType]?.relocation.kind,
                 relocationStore: this.options.registration.locations.relocationStoreInstance,
                 meshName,
                 owner: () => this.locationOwner.currentRuntime?.currentOwnerToken,
@@ -1579,6 +1594,8 @@ class ZLinkFrameworkRuntimeHost {
         });
         const coordinator = (this.userSpotCoordinator = new user_spot_creation_coordinator_1.ZLinkUserSpotCreationCoordinator({
             store: locationStore,
+            relocationPolicy: (meshName, stableType) => this.options.registration.spotNodes.get(meshName)?.spotFactoryRegistrations?.[stableType]
+                ?.relocation.kind,
             publishReadyRoute: (meshName, route) => {
                 this.cachedLocationSpotRouteResolver?.invalidate?.(route.spot.spotId);
                 this.spotNodeRuntime?.meshNode(meshName)?.rememberSpotRoute?.(route);
@@ -1961,96 +1978,49 @@ class ZLinkFrameworkRuntimeHost {
                     ownerLeaseGeneration: record.source.ownerLeaseGeneration
                 });
             },
-            meshRecordDispatcher: (meshName, owner, record) => this.dispatchMeshRecord(meshName, owner, record, this.executionState?.abortController.signal),
+            meshRecordDispatcher: (meshName, owner, record) => this.dispatchMeshRecord(application_job_queue_scope_1.currentApplicationJobOrigin, meshName, owner, record, this.executionState?.abortController.signal),
             activationConcurrency: (meshName) => this.activationAdmission.current(meshName)
         };
     }
-    async dispatchMeshRecord(meshName, owner, record, signal) {
+    dispatchMeshNodeRecord(meshName, record, signal) {
+        const control = this.serviceRelocation.tryHandleControl(meshName, record, signal);
+        if (control instanceof Promise)
+            return control.then((handled) => handled ? undefined : this.dispatchMeshNodePayload(meshName, record, signal));
+        if (!control)
+            return this.dispatchMeshNodePayload(meshName, record, signal);
+    }
+    dispatchMeshNodePayload(meshName, record, signal) {
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.NodeRequest && record.parts.length === 1) {
+            const terminal = (0, actors_1.decodeRemoteActorSourceLeaveTerminal)(record.parts[0].data());
+            if (terminal !== undefined) {
+                return this.completeFormalSourceLeave(record, terminal);
+            }
+        }
+        const channelRuntime = this.channelRuntime;
+        if (channelRuntime === undefined) {
+            throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode node-direct dispatch requires the channel runtime.');
+        }
+        return channelRuntime.dispatchMeshRoute(meshName, record, signal);
+    }
+    async completeFormalSourceLeave(record, terminal) {
+        const completed = await this.spotManager?.completeFormalSourceLeaveTerminal(terminal.actorId, terminal.transferId, terminal.succeeded);
+        if (completed !== true) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Actor '${terminal.actorId}' has no matching formal transfer terminal gate.`);
+        }
+        if (record.reply(Buffer.alloc(0)) !== runtime_values_1.SubmitResult.Ok) {
+            throw new ConfigurationException_1.ZLinkConfigurationException(`Actor '${terminal.actorId}' formal transfer terminal acknowledgement failed.`);
+        }
+        return;
+    }
+    dispatchMeshRecord(applicationJobOrigin, meshName, owner, record, signal) {
         if (record.operationKind === service_runtime_contracts_1.OperationKind.ActorJoin) {
             if (this.spotManager === undefined) {
                 throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode Actor join dispatch requires the Spot manager.');
             }
             return this.spotManager.dispatchMeshActorJoin(meshName, owner, record);
         }
-        if (record.kind === service_runtime_contracts_1.ReceiveKind.ActorBinding) {
-            if (record.kindData?.kind !== 'actorBinding') {
-                throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode Actor binding record has no binding generation.');
-            }
-            const binding = record.kindData;
-            const replyBindingFailure = (kind) => {
-                const terminal = (0, framework_errors_internal_1.internalFrameworkWireReply)(kind);
-                if (record.replyFailure?.(terminal.terminalResult, terminal.failureCode) !== runtime_values_1.SubmitResult.Ok) {
-                    throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' failure acknowledgement failed.`);
-                }
-            };
-            const replyBindingSuccess = () => {
-                if (record.reply(Buffer.alloc(0)) !== runtime_values_1.SubmitResult.Ok) {
-                    throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' acknowledgement failed.`);
-                }
-            };
-            const state = this.actorManager?.getState(binding.actor.actorId);
-            const nativeActorRef = state?.nativeActorRef;
-            if (state === undefined ||
-                nativeActorRef === undefined ||
-                nativeActorRef.actorId !== binding.actor.actorId ||
-                !(0, routing_id_1.routingIdsEqual)(nativeActorRef.nodeRid, binding.actor.nodeRid)) {
-                replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
-                return;
-            }
-            if (nativeActorRef.generation !== binding.actor.generation) {
-                replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale);
-                return;
-            }
-            const node = state.meshName === meshName ? this.spotNodeRuntime?.meshNode(meshName) : undefined;
-            const localStatus = node?.status();
-            // ownsLocation tracks local cleanup responsibility, not Actor authority.
-            // A relocation target can exact-read committed authority without owning that cleanup.
-            if (localStatus === undefined ||
-                !(0, routing_id_1.routingIdsEqual)(localStatus.routingId, binding.actor.nodeRid) ||
-                localStatus.lifecycleGeneration !== binding.actorNodeGeneration ||
-                state.locationGeneration !== binding.authorityOwnerGeneration ||
-                state.isMoving) {
-                replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
-                return;
-            }
-            const sessionOwnerIsLocal = (0, routing_id_1.routingIdsEqual)(localStatus.routingId, binding.sessionNodeRid) &&
-                localStatus.lifecycleGeneration === binding.sessionOwnerNodeGeneration;
-            if (binding.transition === 'tombstone') {
-                const actorRef = {
-                    actorId: binding.actor.actorId,
-                    objectGeneration: binding.actor.generation,
-                    meshName,
-                    nodeRid: binding.actor.nodeRid
-                };
-                if (sessionOwnerIsLocal) {
-                    (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
-                    await this.streamBindingRuntime.retireRemoteBinding(actorRef, binding.sessionRid, binding.bindingGeneration, signal);
-                }
-                state.retireBoundSessionBinding(binding);
-                replyBindingSuccess();
-                return;
-            }
-            const target = this.boundSessionRelay.boundSessions.resolveRemoteBoundSessionTarget(binding.sessionNodeRid, binding.sessionRid);
-            if (target === undefined) {
-                replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
-                return;
-            }
-            const installed = state.installBoundSessionBinding({
-                ...target,
-                sessionNodeRid: binding.sessionNodeRid,
-                sessionRid: binding.sessionRid,
-                sessionOwnerNodeGeneration: binding.sessionOwnerNodeGeneration,
-                sessionOwnerId: binding.sessionOwnerId,
-                sessionOwnerLeaseGeneration: binding.sessionOwnerLeaseGeneration,
-                bindingGeneration: binding.bindingGeneration
-            });
-            if (!installed) {
-                replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
-                return;
-            }
-            replyBindingSuccess();
-            return Promise.resolve();
-        }
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.ActorBinding)
+            return this.dispatchMeshActorBinding(meshName, record, signal);
         switch (record.kind) {
             case service_runtime_contracts_1.ReceiveKind.TransferControl:
                 if (record.kindData?.kind !== 'transferControl') {
@@ -2067,28 +2037,7 @@ class ZLinkFrameworkRuntimeHost {
             }
             case service_runtime_contracts_1.ReceiveKind.NodeSend:
             case service_runtime_contracts_1.ReceiveKind.NodeRequest: {
-                return this.admission.run(meshName, 'RouteMesh node dispatch', async () => {
-                    if (await this.serviceRelocation.tryHandleControl(meshName, record, signal)) {
-                        return;
-                    }
-                    if (record.kind === service_runtime_contracts_1.ReceiveKind.NodeRequest && record.parts.length === 1) {
-                        const terminal = (0, actors_1.decodeRemoteActorSourceLeaveTerminal)(record.parts[0].data());
-                        if (terminal !== undefined) {
-                            if ((await this.spotManager?.completeFormalSourceLeaveTerminal(terminal.actorId, terminal.transferId, terminal.succeeded)) !== true) {
-                                throw new ConfigurationException_1.ZLinkConfigurationException(`Actor '${terminal.actorId}' has no matching formal transfer terminal gate.`);
-                            }
-                            if (record.reply(Buffer.alloc(0)) !== runtime_values_1.SubmitResult.Ok) {
-                                throw new ConfigurationException_1.ZLinkConfigurationException(`Actor '${terminal.actorId}' formal transfer terminal acknowledgement failed.`);
-                            }
-                            return;
-                        }
-                    }
-                    const channelRuntime = this.channelRuntime;
-                    if (channelRuntime === undefined) {
-                        throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode node-direct dispatch requires the channel runtime.');
-                    }
-                    return await channelRuntime.dispatchMeshRoute(meshName, record, signal);
-                });
+                return this.admission.run(meshName, 'RouteMesh node dispatch', () => this.dispatchMeshNodeRecord(meshName, record, signal));
             }
             case service_runtime_contracts_1.ReceiveKind.SpotSend:
             case service_runtime_contracts_1.ReceiveKind.SpotRequest:
@@ -2109,13 +2058,92 @@ class ZLinkFrameworkRuntimeHost {
                 if (this.spotManager === undefined) {
                     throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode Actor dispatch requires the Spot manager.');
                 }
-                return this.admission.run(meshName, 'RouteMesh Actor dispatch', () => this.spotManager.dispatchMeshActor(meshName, owner, record));
+                return this.admission.run(meshName, 'RouteMesh Actor dispatch', () => this.spotManager.dispatchMeshActor(applicationJobOrigin(), meshName, owner, record));
             case service_runtime_contracts_1.ReceiveKind.SendReady:
                 return Promise.resolve();
             default:
                 throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode record kind '${record.kind}' does not yet have a registered framework consumer.`);
         }
     }
+    async dispatchMeshActorBinding(meshName, record, signal) {
+        if (record.kindData?.kind !== 'actorBinding') {
+            throw new ConfigurationException_1.ZLinkConfigurationException('MeshNode Actor binding record has no binding generation.');
+        }
+        const binding = record.kindData;
+        const replyBindingFailure = (kind) => {
+            const terminal = (0, framework_errors_internal_1.internalFrameworkWireReply)(kind);
+            if (record.replyFailure?.(terminal.terminalResult, terminal.failureCode) !== runtime_values_1.SubmitResult.Ok) {
+                throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' failure acknowledgement failed.`);
+            }
+        };
+        const replyBindingSuccess = () => {
+            if (record.reply(Buffer.alloc(0)) !== runtime_values_1.SubmitResult.Ok) {
+                throw new ConfigurationException_1.ZLinkConfigurationException(`MeshNode Actor binding target '${binding.actor.actorId}' acknowledgement failed.`);
+            }
+        };
+        const state = this.actorManager?.getState(binding.actor.actorId);
+        const nativeActorRef = state?.nativeActorRef;
+        if (state === undefined ||
+            nativeActorRef === undefined ||
+            nativeActorRef.actorId !== binding.actor.actorId ||
+            !(0, routing_id_1.routingIdsEqual)(nativeActorRef.nodeRid, binding.actor.nodeRid)) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
+            return;
+        }
+        if (nativeActorRef.generation !== binding.actor.generation) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale);
+            return;
+        }
+        const node = state.meshName === meshName ? this.spotNodeRuntime?.meshNode(meshName) : undefined;
+        const localStatus = node?.status();
+        // ownsLocation tracks local cleanup responsibility, not Actor authority.
+        // A relocation target can exact-read committed authority without owning that cleanup.
+        if (localStatus === undefined ||
+            !(0, routing_id_1.routingIdsEqual)(localStatus.routingId, binding.actor.nodeRid) ||
+            localStatus.lifecycleGeneration !== binding.actorNodeGeneration ||
+            state.locationGeneration !== binding.authorityOwnerGeneration ||
+            state.isMoving) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
+            return;
+        }
+        const sessionOwnerIsLocal = (0, routing_id_1.routingIdsEqual)(localStatus.routingId, binding.sessionNodeRid) &&
+            localStatus.lifecycleGeneration === binding.sessionOwnerNodeGeneration;
+        if (binding.transition === 'tombstone') {
+            const actorRef = {
+                actorId: binding.actor.actorId,
+                objectGeneration: binding.actor.generation,
+                meshName,
+                nodeRid: binding.actor.nodeRid
+            };
+            if (sessionOwnerIsLocal) {
+                (0, application_job_queue_scope_2.releaseApplicationJobPermitBeforeHandler)();
+                await this.streamBindingRuntime.retireRemoteBinding(actorRef, binding.sessionRid, binding.bindingGeneration, signal);
+            }
+            state.retireBoundSessionBinding(binding);
+            replyBindingSuccess();
+            return;
+        }
+        const target = this.boundSessionRelay.boundSessions.resolveRemoteBoundSessionTarget(binding.sessionNodeRid, binding.sessionRid);
+        if (target === undefined) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
+            return;
+        }
+        const installed = state.installBoundSessionBinding({
+            ...target,
+            sessionNodeRid: binding.sessionNodeRid,
+            sessionRid: binding.sessionRid,
+            sessionOwnerNodeGeneration: binding.sessionOwnerNodeGeneration,
+            sessionOwnerId: binding.sessionOwnerId,
+            sessionOwnerLeaseGeneration: binding.sessionOwnerLeaseGeneration,
+            bindingGeneration: binding.bindingGeneration
+        });
+        if (!installed) {
+            replyBindingFailure(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale);
+            return;
+        }
+        replyBindingSuccess();
+        return Promise.resolve();
+    }
     submitLocalMeshRoute(meshName, sourceNodeRid, parts) {
         const state = this.executionState;
         const channelRuntime = this.channelRuntime;
@@ -2143,9 +2171,9 @@ class ZLinkFrameworkRuntimeHost {
         try {
             state.taskRunner.runDetached('mesh-node-local-route-dispatch', async () => {
                 try {
-                    const permit = await this.applicationJobQueue.acquire(state.abortController.signal);
+                    const permit = await this.applicationJobQueue.acquire(state.abortController.signal, 'local');
                     permit.markApplicationQueued();
-                    await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(permit, () => channelRuntime.dispatchLocalMeshRoute(meshName, sourceNodeRid, ownedParts));
+                    await (0, application_job_queue_scope_2.runWithApplicationJobPermit)(permit, () => channelRuntime.dispatchLocalMeshRoute(meshName, sourceNodeRid, ownedParts));
                 }
                 finally {
                     for (const part of ownedParts)

package/dist/runtime/host/instance-activation-authority.d.ts

@@ -5,6 +5,7 @@ import type { ServiceSpotState } from '../foundation/service-stateful-registry';
 import type { ServiceInstanceActivationTarget, ServiceInstanceRouteFence } from '../foundation/service-stateful-wire-codec';
 import { type ServiceInstanceActivationRecoveryEnvelope } from '../foundation/service-instance-activation-recovery-codec';
 export interface ZLinkInstanceActivationAuthorityOptions {
+    readonly relocationPolicy?: (stableType: string) => import('../locations/internal-location-contracts').ZLinkObjectReserveRequest['actorRelocationPolicy'];
     readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
     readonly relocationStore?: ZLinkRelocationStore;
     readonly meshName: string;
@@ -16,7 +17,7 @@ export declare class ZLinkInstanceActivationAuthority implements ServiceAsyncIns
     private readonly options;
     private readonly pending;
     constructor(options: ZLinkInstanceActivationAuthorityOptions);
-    read(target: ServiceInstanceActivationTarget): Promise<ServiceInstanceAuthorityRead>;
+    read(target: ServiceInstanceActivationTarget, instanceIntent?: true, activation?: ServiceInstanceActivationRecoveryEnvelope, acceptsLocal?: (route: ServiceInstanceRouteFence) => boolean): Promise<ServiceInstanceAuthorityRead>;
     reserve(activation: Omit<ServiceInstanceActivationRecoveryEnvelope, 'targetMeshName'>, signal?: AbortSignal): Promise<ServiceInstanceAuthorityReserve>;
     resume(target: ServiceInstanceActivationTarget, pending: ServicePendingInstanceActivation): Promise<ServiceInstanceActivationReservation>;
     commit(target: ServiceInstanceActivationTarget, reservation: ServiceInstanceActivationReservation, spot: ServiceSpotState, deadlineUnixMs?: bigint): Promise<{

package/dist/runtime/host/instance-activation-authority.js

@@ -17,9 +17,71 @@ class ZLinkInstanceActivationAuthority {
     constructor(options) {
         this.options = options;
     }
-    async read(target) {
-        const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
-        return current.kind === 'snapshot' ? readyRead(current, target) : { kind: 'missing' };
+    async read(target, instanceIntent, activation, acceptsLocal) {
+        const key = authorityKey(target.targetSpotId);
+        const current = await this.options.store.readAuthority(key);
+        if (current.kind !== 'snapshot')
+            return { kind: 'missing' };
+        const ready = (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(current.payload);
+        const resolved = readyRead(current, target, ready);
+        if (ready?.state === 'ready' &&
+            resolved.kind === 'ready' &&
+            acceptsLocal?.(resolved.route) === true) {
+            return resolved;
+        }
+        if (activation !== undefined &&
+            current.allocation.objectKind === 'instance_spot' &&
+            (0, routing_id_1.routingIdsEqual)(current.allocation.descriptor.rid, target.targetNodeRid) &&
+            current.allocation.descriptorLifecycleGeneration === target.targetNodeGeneration) {
+            const reference = current.pendingCreation?.requestContentReference ?? ready?.activationRecovery?.reference;
+            if (reference !== undefined) {
+                const root = await this.options.relocationStore?.read((0, relocation_blob_1.relocationBlobReference)(reference));
+                if (root?.kind !== 'found') {
+                    throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.DataLost, 'Stored Instance activation is missing.');
+                }
+                let stored;
+                try {
+                    stored = (0, service_instance_activation_recovery_codec_1.decodeInstanceActivationRecoveryEnvelope)(root.bytes);
+                }
+                catch (error) {
+                    if (!(error instanceof TypeError || error instanceof RangeError))
+                        throw error;
+                    throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'Stored Instance activation is invalid.');
+                }
+                if (stored.operation.high === activation.operation.high &&
+                    stored.operation.low === activation.operation.low &&
+                    (stored.targetMeshName !== activation.targetMeshName ||
+                        stored.target.stableType !== target.stableType ||
+                        stored.target.descriptorVersion !== target.descriptorVersion ||
+                        stored.deadlineUnixMs !== activation.deadlineUnixMs ||
+                        (stored.metadataFrame === undefined) !== (activation.metadataFrame === undefined) ||
+                        (stored.metadataFrame !== undefined &&
+                            activation.metadataFrame !== undefined &&
+                            Buffer.compare(stored.metadataFrame, activation.metadataFrame) !== 0))) {
+                    throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'Instance route does not match the stored activation.');
+                }
+            }
+        }
+        if (instanceIntent === true &&
+            current.allocation.state === 'active' &&
+            ready?.state === 'ready') {
+            if (current.allocation.objectKind !== 'instance_spot' ||
+                current.allocation.stableType !== target.stableType) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch, 'Instance activation type does not match the current authority.');
+            }
+            const released = await this.options.store.releaseEndedReservation?.(key, current.storeVersion.value, undefined, {
+                key: { kind: 'instance_spot', globalId: target.targetSpotId },
+                intent: { stableType: target.stableType },
+                actorRelocationPolicy: this.options.relocationPolicy?.(target.stableType)
+            });
+            if (released === true)
+                return { kind: 'missing' };
+            const refreshed = await this.options.store.readAuthority(key);
+            return refreshed.kind === 'snapshot'
+                ? readyRead(refreshed, target, (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(refreshed.payload))
+                : { kind: 'missing' };
+        }
+        return resolved;
     }
     async reserve(activation, signal) {
         const target = activation.target;
@@ -49,6 +111,7 @@ class ZLinkInstanceActivationAuthority {
         try {
             reserved = await this.options.store.reserve({
                 key: { kind: 'instance_spot', globalId: target.targetSpotId },
+                actorRelocationPolicy: this.options.relocationPolicy?.(target.stableType),
                 intent: {
                     stableType: target.stableType,
                     requestContentReference: stored.reference.value,
@@ -207,7 +270,7 @@ class ZLinkInstanceActivationAuthority {
         }
         const current = await this.options.store.readAuthority(authorityKey(target.targetSpotId));
         if (current.kind === 'snapshot') {
-            const ready = readyRead(current, target);
+            const ready = readyRead(current, target, (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(current.payload));
             if (ready.kind === 'ready') {
                 this.pending.delete(reservation.token);
                 return { kind: 'lost', route: ready.route };
@@ -236,7 +299,7 @@ class ZLinkInstanceActivationAuthority {
         }
         const recovery = decoded.activationRecovery;
         if (recovery === undefined)
-            return routeFromSnapshot(current);
+            return routeFromSnapshot(current, decoded.spotId);
         let completed = current;
         if (recovery.replayCursor < recovery.inboxSequence) {
             const cursorStored = await this.options.store.compareExchangeAuthority(key, current.storeVersion, {
@@ -338,19 +401,16 @@ class ZLinkInstanceActivationAuthority {
     }
 }
 exports.ZLinkInstanceActivationAuthority = ZLinkInstanceActivationAuthority;
-function readyRead(snapshot, target) {
-    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload) ??
-        (0, service_authority_payload_codec_1.decodeServiceClosingSpotAuthority)(snapshot.payload);
-    const creating = (0, service_authority_payload_codec_1.decodeServiceInstanceAuthorityPayload)(snapshot.payload);
-    if (creating?.state === 'coldActivating' &&
+function readyRead(snapshot, target, decoded) {
+    if (decoded?.state === 'coldActivating' &&
         snapshot.allocation.objectKind === 'instance_spot' &&
-        creating.stableType === target.stableType &&
-        creating.spotId === target.targetSpotId &&
-        creating.ownerId === snapshot.ownerId &&
-        creating.ownerLeaseGeneration === snapshot.ownerLeaseGeneration &&
-        creating.ownerMeshName === snapshot.allocation.descriptor.meshName &&
-        creating.ownerNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration &&
-        (0, routing_id_1.routingIdsEqual)(creating.ownerNodeRid, snapshot.allocation.descriptor.rid) &&
+        decoded.stableType === target.stableType &&
+        decoded.spotId === target.targetSpotId &&
+        decoded.ownerId === snapshot.ownerId &&
+        decoded.ownerLeaseGeneration === snapshot.ownerLeaseGeneration &&
+        decoded.ownerMeshName === snapshot.allocation.descriptor.meshName &&
+        decoded.ownerNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration &&
+        (0, routing_id_1.routingIdsEqual)(decoded.ownerNodeRid, snapshot.allocation.descriptor.rid) &&
         (0, routing_id_1.routingIdsEqual)(target.targetNodeRid, snapshot.allocation.descriptor.rid) &&
         target.targetNodeGeneration === snapshot.allocation.descriptorLifecycleGeneration) {
         return {
@@ -360,7 +420,8 @@ function readyRead(snapshot, target) {
             authority: snapshot
         };
     }
-    if (decoded?.kind !== 'instance_spot' ||
+    if (decoded === undefined ||
+        decoded.state === 'coldActivating' ||
         decoded.stableType !== target.stableType ||
         decoded.spotId !== target.targetSpotId ||
         snapshot.allocation.objectKind !== 'instance_spot' ||
@@ -374,7 +435,7 @@ function readyRead(snapshot, target) {
         target.targetNodeGeneration !== snapshot.allocation.descriptorLifecycleGeneration) {
         return { kind: 'missing' };
     }
-    return { kind: 'ready', route: routeFromSnapshot(snapshot), authority: snapshot };
+    return { kind: 'ready', route: routeFromSnapshot(snapshot, decoded.spotId), authority: snapshot };
 }
 function requireCommitIdentity(target, reservation, creating, spot, meshName) {
     if (creating.allocation.state !== 'reserved' ||
@@ -392,16 +453,19 @@ function requireCommitIdentity(target, reservation, creating, spot, meshName) {
         throw new Error('Instance activation Ready identity does not match its exact reservation.');
     }
 }
-function routeFromSnapshot(snapshot) {
-    const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload) ??
-        (0, service_authority_payload_codec_1.decodeServiceClosingSpotAuthority)(snapshot.payload);
-    if (decoded?.kind !== 'instance_spot') {
-        throw new Error('Instance authority is not Ready.');
+function routeFromSnapshot(snapshot, spotId) {
+    if (spotId === undefined) {
+        const decoded = (0, service_authority_payload_codec_1.decodeServiceReadySpotAuthority)(snapshot.payload) ??
+            (0, service_authority_payload_codec_1.decodeServiceClosingSpotAuthority)(snapshot.payload);
+        if (decoded?.kind !== 'instance_spot') {
+            throw new Error('Instance authority is not Ready.');
+        }
+        spotId = decoded.spotId;
     }
     return {
         targetNodeRid: String(snapshot.allocation.descriptor.rid),
         targetNodeGeneration: snapshot.allocation.descriptorLifecycleGeneration,
-        targetSpotId: decoded.spotId,
+        targetSpotId: spotId,
         objectGeneration: snapshot.objectGeneration,
         ownerId: snapshot.ownerId,
         authorityOwnerGeneration: snapshot.authorityOwnerGeneration,