@zlink-systems/framework 0.10.0

package/dist/runtime/spots/index.js

@@ -0,0 +1,2090 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkSpotManager = exports.ZLinkPublicSpotManager = exports.ZLinkSpotNodeRuntimeManager = exports.createFrameworkEntrySpotId = exports.ZLinkEntrySpotActivation = exports.ZLinkRuntimeSpotPublisherTransport = exports.DefaultZLinkSpotHandlerRegistry = exports.DefaultZLinkSpotOutbound = exports.ZLinkSpotTimerRegistry = exports.ZLinkManagedTimer = exports.ZLinkSpotSerialExecutor = exports.ZLinkSpotSerialTurnExecutor = exports.ZLinkSpotActorAdmissionCoordinator = exports.ZLinkSpotRoutedBoundSessionDispatch = exports.sendToSpotHandle = exports.requestToSpotHandle = exports.resolveSpotHandle = exports.createSpotHandle = void 0;
+var spot_handle_1 = require("./spot-handle");
+Object.defineProperty(exports, "createSpotHandle", { enumerable: true, get: function () { return spot_handle_1.createSpotHandle; } });
+Object.defineProperty(exports, "resolveSpotHandle", { enumerable: true, get: function () { return spot_handle_1.resolveSpotHandle; } });
+var spot_outbound_1 = require("./spot-outbound");
+Object.defineProperty(exports, "requestToSpotHandle", { enumerable: true, get: function () { return spot_outbound_1.requestToSpotHandle; } });
+Object.defineProperty(exports, "sendToSpotHandle", { enumerable: true, get: function () { return spot_outbound_1.sendToSpotHandle; } });
+var spot_routed_bound_session_dispatch_1 = require("./spot-routed-bound-session-dispatch");
+Object.defineProperty(exports, "ZLinkSpotRoutedBoundSessionDispatch", { enumerable: true, get: function () { return spot_routed_bound_session_dispatch_1.ZLinkSpotRoutedBoundSessionDispatch; } });
+var spot_actor_admission_coordinator_1 = require("./spot-actor-admission-coordinator");
+Object.defineProperty(exports, "ZLinkSpotActorAdmissionCoordinator", { enumerable: true, get: function () { return spot_actor_admission_coordinator_1.ZLinkSpotActorAdmissionCoordinator; } });
+const abort_1 = require("../abort");
+const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const diagnostics_1 = require("../diagnostics");
+const runtime_message_1 = require("../backend/runtime-message");
+const runtime_values_1 = require("../backend/runtime-values");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const serial_work_size_1 = require("../execution/serial-work-size");
+const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const workers_1 = require("../workers");
+const payload_codec_1 = require("../messaging/payload-codec");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const protocol_1 = require("../streams/protocol");
+const actor_remote_wire_1 = require("../actors/actor-remote-wire");
+const actor_handoff_1 = require("../actors/actor-handoff");
+const spot_remote_codec_1 = require("./spot-remote-codec");
+const routing_id_1 = require("../routing-id");
+const service_wire_constants_generated_1 = require("../foundation/service-wire-constants.generated");
+var spot_serial_turn_executor_1 = require("./spot-serial-turn-executor");
+Object.defineProperty(exports, "ZLinkSpotSerialTurnExecutor", { enumerable: true, get: function () { return spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor; } });
+var spot_serial_executor_1 = require("./spot-serial-executor");
+Object.defineProperty(exports, "ZLinkSpotSerialExecutor", { enumerable: true, get: function () { return spot_serial_executor_1.ZLinkSpotSerialExecutor; } });
+var spot_timer_1 = require("./spot-timer");
+Object.defineProperty(exports, "ZLinkManagedTimer", { enumerable: true, get: function () { return spot_timer_1.ZLinkManagedTimer; } });
+Object.defineProperty(exports, "ZLinkSpotTimerRegistry", { enumerable: true, get: function () { return spot_timer_1.ZLinkSpotTimerRegistry; } });
+var spot_outbound_2 = require("./spot-outbound");
+Object.defineProperty(exports, "DefaultZLinkSpotOutbound", { enumerable: true, get: function () { return spot_outbound_2.DefaultZLinkSpotOutbound; } });
+var spot_handler_registry_1 = require("./spot-handler-registry");
+Object.defineProperty(exports, "DefaultZLinkSpotHandlerRegistry", { enumerable: true, get: function () { return spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry; } });
+var spot_publisher_transport_1 = require("./spot-publisher-transport");
+Object.defineProperty(exports, "ZLinkRuntimeSpotPublisherTransport", { enumerable: true, get: function () { return spot_publisher_transport_1.ZLinkRuntimeSpotPublisherTransport; } });
+const spot_activation_registry_1 = require("./spot-activation-registry");
+const spot_activation_state_1 = require("./spot-activation-state");
+const spot_activation_1 = require("./spot-activation");
+const spot_actor_membership_1 = require("./spot-actor-membership");
+const formal_remote_actor_transfer_registry_1 = require("./formal-remote-actor-transfer-registry");
+const formal_remote_actor_admission_registry_1 = require("./formal-remote-actor-admission-registry");
+const spot_location_claim_1 = require("./spot-location-claim");
+const spot_routed_spot_packet_dispatch_1 = require("./spot-routed-spot-packet-dispatch");
+var spot_entry_activation_1 = require("./spot-entry-activation");
+Object.defineProperty(exports, "ZLinkEntrySpotActivation", { enumerable: true, get: function () { return spot_entry_activation_1.ZLinkEntrySpotActivation; } });
+var spot_node_runtime_manager_1 = require("./spot-node-runtime-manager");
+Object.defineProperty(exports, "createFrameworkEntrySpotId", { enumerable: true, get: function () { return spot_node_runtime_manager_1.createFrameworkEntrySpotId; } });
+Object.defineProperty(exports, "ZLinkSpotNodeRuntimeManager", { enumerable: true, get: function () { return spot_node_runtime_manager_1.ZLinkSpotNodeRuntimeManager; } });
+var spot_manager_public_1 = require("./spot-manager-public");
+Object.defineProperty(exports, "ZLinkPublicSpotManager", { enumerable: true, get: function () { return spot_manager_public_1.ZLinkPublicSpotManager; } });
+class DefaultZLinkSpotManager {
+    options;
+    factories;
+    activations;
+    workerRuntime;
+    locationClaim;
+    routedSpotPackets;
+    actorMembership;
+    activationLifecycle;
+    formalRemoteTransfers = new formal_remote_actor_transfer_registry_1.ZLinkFormalRemoteActorTransferRegistry();
+    formalRemoteActorAdmissions = new formal_remote_actor_admission_registry_1.ZLinkFormalRemoteActorAdmissionRegistry();
+    pendingInstanceMaterializations = new Map();
+    //  Parallel index keyed by `${meshName}\0${spotId}` so per-activation
+    //  callbacks (isInstanceMaterializing, sibling-generation lookups) resolve
+    //  in O(1) instead of scanning every pending key.
+    pendingInstanceMaterializationsByPrefix = new Map();
+    instanceActivationGates = new Map();
+    pendingInstanceCloses = new Map();
+    pendingInstanceTerminals = new Map();
+    pendingInstanceTerminalGenerations = new Map();
+    deferredInstanceAuthorityReleases = new Map();
+    idleSweepTimer;
+    idleSweepRunning = false;
+    constructor(options, timerClock) {
+        this.options = options;
+        this.activations = new spot_activation_registry_1.ZLinkSpotActivationRegistry(options.metrics);
+        this.factories = new Set(options.spotFactories);
+        this.workerRuntime = options.workerRuntime ?? new workers_1.ZLinkWorkerRuntime();
+        this.locationClaim = new spot_location_claim_1.ZLinkSpotLocationClaim({
+            lifecycle: options.locationLifecycle,
+            nodeRid: options.nodeRid,
+            nodeRidProvider: options.nodeRidProvider,
+            nodeGenerationProvider: options.nodeGenerationProvider
+        });
+        this.routedSpotPackets = new spot_routed_spot_packet_dispatch_1.ZLinkRoutedSpotPacketDispatch({
+            resolveActivation: (spotId) => this.activations.resolveUnique(spotId),
+            claimApplicationWork: options.admission === undefined
+                ? undefined
+                : (meshName) => options.admission.claim(meshName, 'Spot route dispatch'),
+            providerResolver: options.providerResolver,
+            dispatchErrors: options.dispatchErrors
+        });
+        this.actorMembership = new spot_actor_membership_1.ZLinkSpotActorMembership({
+            resolveActivation: (spotId, meshName) => meshName === undefined
+                ? this.activations.resolveUnique(spotId)
+                : this.activations.resolve(meshName, spotId),
+            providerResolver: options.providerResolver,
+            messageSerializers: options.messageSerializers,
+            dispatchErrors: options.dispatchErrors,
+            entrySpotCallbacks: options.entrySpotCallbacks,
+            nodeRid: options.nodeRid,
+            nodeRidProvider: options.nodeRidProvider,
+            entryNodeRid: options.entryNodeRid,
+            entryNodeRidProvider: options.entryNodeRidProvider,
+            entrySpotIdProvider: options.entrySpotIdProvider,
+            spotRouteResolver: options.spotRouteResolver,
+            actorTransferRuntime: options.actorTransferRuntime
+        });
+        this.activationLifecycle = new spot_activation_1.ZLinkSpotActivationLifecycle({
+            timerClock,
+            spotTimerHandlers: options.spotTimerHandlers,
+            spotPacketHandlers: options.spotPacketHandlers,
+            spotSubscriptionHandlers: options.spotSubscriptionHandlers,
+            spotActorSendHandlers: options.spotActorSendHandlers,
+            spotActorRequestHandlers: options.spotActorRequestHandlers,
+            nodeRid: options.nodeRid,
+            nodeRidProvider: options.nodeRidProvider,
+            actorCountProvider: options.actorCountProvider,
+            userSpotExecutionMode: options.userSpotExecutionMode,
+            userSpotRelocationCoordinationMode: options.userSpotRelocationCoordinationMode,
+            channelClient: options.channelClient,
+            fanoutClient: options.fanoutClient,
+            spotPublisherClient: options.spotPublisherClient,
+            routedTransport: options.routedTransport,
+            addressTransport: options.addressTransport,
+            spotRouterChannelIdForMesh: options.spotRouterChannelIdForMesh,
+            providerResolver: options.providerResolver,
+            dispatchErrors: options.dispatchErrors,
+            runtimeEventPublisher: options.runtimeEventPublisher,
+            workerRuntime: this.workerRuntime,
+            messageSerializers: options.messageSerializers,
+            locationClaim: this.locationClaim,
+            createNativeSpot: options.createNativeSpot,
+            createReceived: options.createReceived,
+            createTopicMessage: options.createTopicMessage,
+            nativeSpotNodeProvider: options.nativeSpotNodeProvider,
+            actorResolver: options.actorResolver,
+            detachedTaskRunner: options.detachedTaskRunner,
+            actorTransferRuntime: options.actorTransferRuntime,
+            boundSessionRuntime: options.boundSessionRuntime,
+            actorHandoffRuntime: options.actorHandoffRuntime,
+            admission: options.admission,
+            statefulExecutionAllowed: options.statefulExecutionAllowed,
+            leaveActor: (spotId, actor, signal, meshName) => this.actorMembership.leaveActor(spotId, actor, signal, meshName),
+            closeSpot: (meshName, spotId, signal, reason) => this.closeWithReason(meshName, spotId, signal, reason),
+            registerActivation: (activation) => {
+                this.activations.register(activation);
+                this.scheduleIdleSweep();
+            },
+            //  Spec 15 §4.2 relocation temporary queue: production ingress
+            //  consults the same admission attempts registered on Accepted
+            //  (`formalRemoteActorAdmissions.begin`, in dispatchMeshActorJoin)
+            //  instead of dropping an arrival for an Actor that has not yet
+            //  cut over locally.
+            routeToActorJoinPrewarm: (actorId, objectGeneration, arrival) => this.formalRemoteActorAdmissions.routeIngress(actorId, objectGeneration, arrival),
+            releaseLocation: (activation, meshName, spotId) => {
+                if (activation.domain.kind === 'user') {
+                    return this.locationClaim.release(meshName, spotId);
+                }
+                const currentApplication = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+                if (currentApplication !== undefined
+                    && currentApplication.objectGeneration !== activation.domain.objectGeneration) {
+                    // A superseded local application must not release the authority row
+                    // that now belongs to the newer object generation.
+                    return Promise.resolve();
+                }
+                const key = `${meshName}\0${String(spotId)}`;
+                const objectGeneration = activation.domain.objectGeneration;
+                if (this.pendingInstanceTerminals.has(key)) {
+                    this.deferInstanceAuthorityRelease(key, objectGeneration);
+                    return Promise.resolve();
+                }
+                this.removeDeferredInstanceAuthorityRelease(key, objectGeneration);
+                return this.releaseInstanceAuthority(meshName, spotId, objectGeneration);
+            },
+            metrics: options.metrics
+        });
+        this.scheduleIdleSweep();
+    }
+    entrySpotIdForMesh(meshName) {
+        return this.options.entrySpotIdProvider?.(meshName);
+    }
+    relocationActivations(meshName) {
+        return this.activations.activeActivations().filter(activation => activation.meshName === meshName
+            && this.activations.resolve(meshName, activation.spotId) === activation);
+    }
+    activeSpotCount(meshName) {
+        return this.activations.list(meshName).length;
+    }
+    instanceActivationConcurrency(meshName) {
+        const limit = this.options.activationConcurrencyLimitProvider?.(meshName) ?? 128;
+        return { active: this.instanceActivationGates.get(meshName)?.active ?? 0, limit };
+    }
+    resolveRelocationActivation(meshName, spotId) {
+        return this.activations.resolve(meshName, spotId);
+    }
+    async prepareRelocationSpot(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, signal) {
+        this.activations.stage(meshName, spotId);
+        try {
+            return await this.activationLifecycle.materializeRelocation(meshName, objectKind, stableType, implementation, spotId, objectGeneration, authorityOwnerGeneration, signal);
+        }
+        catch (error) {
+            this.activations.abandonStage(meshName, spotId);
+            throw error;
+        }
+    }
+    async publishRelocationSpot(activation, beforeAdmission) {
+        await activation.serial.execute(() => activation.spot.onInitialize?.());
+        await beforeAdmission?.();
+        this.activations.publish(activation.meshName, activation.spotId);
+    }
+    async abortRelocationSpot(activation) {
+        this.activations.detachRelocated(activation.meshName, activation.spotId);
+        await activation.timers.dispose();
+        await activation.nativeSpot?.dispose();
+    }
+    async completeRelocationSource(activation) {
+        this.activations.detachRelocated(activation.meshName, activation.spotId);
+        await activation.nativeSpot?.dispose();
+    }
+    async materializeInstance(meshName, instanceType, spotId, objectGeneration, signal) {
+        const existing = this.pendingInstanceMaterializations.get(instanceMaterializationKey(meshName, spotId, objectGeneration));
+        if (existing !== undefined) {
+            await (0, abort_1.awaitWithAbort)(existing, signal);
+            return;
+        }
+        const release = await this.acquireInstanceActivation(meshName, signal);
+        try {
+            await this.materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, signal);
+        }
+        finally {
+            release();
+        }
+    }
+    async materializeInstanceCore(meshName, instanceType, spotId, objectGeneration, signal) {
+        const factory = this.requireInstanceFactory(meshName, instanceType);
+        const key = `${meshName}\0${String(spotId)}`;
+        const materializationKey = instanceMaterializationKey(meshName, spotId, objectGeneration);
+        const materializationPrefix = instanceMaterializationPrefix(meshName, spotId);
+        for (;;) {
+            // A close seals admission before cleanup removes the activation. An
+            // explicit Instance intent arriving at that boundary must wait for the
+            // old resources to be released before materializing the replacement.
+            // This is lifecycle convergence; it does not resubmit application work.
+            const pendingClose = this.pendingInstanceCloses.get(key);
+            if (pendingClose !== undefined) {
+                await (0, abort_1.awaitWithAbort)(pendingClose, signal);
+                continue;
+            }
+            const closing = this.activations.closingOperation(meshName, spotId);
+            if (closing !== undefined) {
+                await (0, abort_1.awaitWithAbort)(closing.ready, signal);
+                continue;
+            }
+            const current = this.activations.resolve(meshName, spotId);
+            if (current !== undefined) {
+                if (current.spotType !== factory) {
+                    throw new configuration_1.ZLinkConfigurationException(`Instance Spot '${String(spotId)}' is assigned to another type.`);
+                }
+                if (current.objectGeneration === objectGeneration)
+                    return;
+                if (current.objectGeneration === undefined
+                    || current.objectGeneration > objectGeneration) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `Instance Spot '${String(spotId)}' has a newer application generation.`);
+                }
+                // A newer authority route may become visible while the previous
+                // application factory is still completing. Dispose that older
+                // activation before publishing the requested generation. The
+                // generation-aware release callback prevents this cleanup from
+                // releasing the newer authority row.
+                await this.discardInstance(meshName, spotId);
+                continue;
+            }
+            const lifecycleActivation = this.activations.activeActivations().find((activation) => activation.meshName === meshName && String(activation.spotId) === String(spotId));
+            if (lifecycleActivation?.isIdleEvicting === true) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `Instance Spot '${String(spotId)}' is entering idle eviction.`);
+            }
+            let pending = this.pendingInstanceMaterializations.get(materializationKey);
+            if (pending === undefined) {
+                const siblings = this.pendingInstanceMaterializationsByPrefix.get(materializationPrefix);
+                const otherPending = siblings === undefined
+                    ? undefined
+                    : siblings.values().next().value;
+                if (otherPending !== undefined) {
+                    await (0, abort_1.awaitWithAbort)(otherPending, signal);
+                    continue;
+                }
+            }
+            if (pending === undefined) {
+                const metric = this.options.metrics?.startInstanceSpotActivation(meshName, instanceType);
+                pending = this.activationLifecycle.materializeInstance(meshName, instanceType, factory, spotId, objectGeneration, signal).then(activation => {
+                    metric?.complete('ready');
+                    return activation;
+                }, error => {
+                    metric?.complete(instanceActivationOutcome(error));
+                    throw error;
+                });
+                this.pendingInstanceMaterializations.set(materializationKey, pending);
+                let siblings = this.pendingInstanceMaterializationsByPrefix.get(materializationPrefix);
+                if (siblings === undefined) {
+                    siblings = new Map();
+                    this.pendingInstanceMaterializationsByPrefix.set(materializationPrefix, siblings);
+                }
+                siblings.set(materializationKey, pending);
+                void pending.finally(() => {
+                    if (this.pendingInstanceMaterializations.get(materializationKey) === pending) {
+                        this.pendingInstanceMaterializations.delete(materializationKey);
+                    }
+                    const bucket = this.pendingInstanceMaterializationsByPrefix.get(materializationPrefix);
+                    if (bucket !== undefined && bucket.get(materializationKey) === pending) {
+                        bucket.delete(materializationKey);
+                        if (bucket.size === 0) {
+                            this.pendingInstanceMaterializationsByPrefix.delete(materializationPrefix);
+                        }
+                    }
+                }).catch(() => undefined);
+            }
+            await pending;
+            return;
+        }
+    }
+    async acquireInstanceActivation(meshName, signal) {
+        let gate = this.instanceActivationGates.get(meshName);
+        if (gate === undefined) {
+            gate = {
+                meshName,
+                limit: this.options.activationConcurrencyLimitProvider?.(meshName) ?? 128,
+                active: 0,
+                waiters: [],
+                waiterHead: 0
+            };
+            this.instanceActivationGates.set(meshName, gate);
+        }
+        if (signal?.aborted === true)
+            throw signal.reason;
+        if (gate.active < gate.limit) {
+            gate.active += 1;
+            this.options.onInstanceActivationConcurrencyChanged?.(meshName);
+            return () => this.releaseInstanceActivation(gate);
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = { resolve, reject, signal, abort: undefined };
+            const slot = gate.waiters.length;
+            waiter.abort = () => {
+                if (gate.waiters[slot] === waiter)
+                    gate.waiters[slot] = undefined;
+                reject(signal?.reason);
+            };
+            signal?.addEventListener('abort', waiter.abort, { once: true });
+            gate.waiters.push(waiter);
+        });
+    }
+    releaseInstanceActivation(gate) {
+        while (gate.waiterHead < gate.waiters.length) {
+            const waiter = gate.waiters[gate.waiterHead];
+            gate.waiters[gate.waiterHead] = undefined;
+            gate.waiterHead += 1;
+            if (gate.waiterHead >= gate.waiters.length) {
+                gate.waiters.length = 0;
+                gate.waiterHead = 0;
+            }
+            if (waiter === undefined)
+                continue;
+            if (waiter.abort !== undefined)
+                waiter.signal?.removeEventListener('abort', waiter.abort);
+            waiter.resolve(() => this.releaseInstanceActivation(gate));
+            return;
+        }
+        gate.waiters.length = 0;
+        gate.waiterHead = 0;
+        gate.active -= 1;
+        this.options.onInstanceActivationConcurrencyChanged?.(gate.meshName);
+    }
+    isInstanceMaterialized(meshName, instanceType, spotId) {
+        const activation = this.activations.resolve(meshName, spotId);
+        return activation !== undefined
+            && activation.spotType === this.requireInstanceFactory(meshName, instanceType);
+    }
+    isInstanceMaterializing(meshName, spotId) {
+        const prefix = instanceMaterializationPrefix(meshName, spotId);
+        return (this.pendingInstanceMaterializationsByPrefix.get(prefix)?.size ?? 0) > 0;
+    }
+    isInstanceClosing(meshName, spotId) {
+        const key = `${meshName}\0${String(spotId)}`;
+        return this.pendingInstanceCloses.has(key)
+            || this.activations.closingOperation(meshName, spotId) !== undefined;
+    }
+    async discardInstance(meshName, spotId) {
+        const activation = this.activations.resolve(meshName, spotId);
+        if (activation === undefined)
+            return;
+        activation.requestClose();
+        const operation = this.activations.startClose(meshName, spotId, (current) => this.activationLifecycle.discardInstance(current), () => true);
+        await operation?.ready;
+    }
+    isInstanceSpotIdleEvicting(meshName, spotId) {
+        const activation = this.activations.activeActivations().find((candidate) => candidate.meshName === meshName && String(candidate.spotId) === String(spotId));
+        return activation !== undefined
+            && activation.domain.kind === 'instance'
+            && activation.isIdleEvicting;
+    }
+    beginInstanceSpotIdleEviction(meshName, spotId) {
+        const activation = this.activations.activeActivations().find((candidate) => candidate.meshName === meshName && String(candidate.spotId) === String(spotId));
+        if (activation === undefined
+            || activation.domain.kind !== 'instance'
+            || !activation.isIdleFor(performance.now(), this.options.instanceSpotIdleTimeoutMs?.get(meshName) ?? 0)) {
+            return false;
+        }
+        return activation.beginIdleEviction();
+    }
+    async completeInstanceTerminal(meshName, spotId, objectGeneration) {
+        const key = `${meshName}\0${String(spotId)}`;
+        const pending = this.pendingInstanceTerminals.get(key);
+        if (pending === undefined)
+            return false;
+        this.removePendingInstanceTerminalGeneration(key, objectGeneration);
+        if (pending > 1) {
+            this.pendingInstanceTerminals.set(key, pending - 1);
+            return false;
+        }
+        this.pendingInstanceTerminals.delete(key);
+        this.pendingInstanceTerminalGenerations.delete(key);
+        const pendingClose = this.pendingInstanceCloses.get(key);
+        if (pendingClose !== undefined) {
+            this.deferInstanceAuthorityRelease(key, objectGeneration);
+            await pendingClose;
+            return true;
+        }
+        const deferredRelease = this.deferredInstanceAuthorityReleases.get(key)?.has(objectGeneration) === true;
+        if (!deferredRelease
+            && this.activations.closingOperation(meshName, spotId) === undefined) {
+            return false;
+        }
+        const currentApplication = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+        if (currentApplication !== undefined
+            && currentApplication.objectGeneration !== objectGeneration) {
+            this.removeDeferredInstanceAuthorityRelease(key, objectGeneration);
+            return false;
+        }
+        this.removeDeferredInstanceAuthorityRelease(key, objectGeneration);
+        await this.releaseInstanceAuthority(meshName, spotId, objectGeneration);
+        return true;
+    }
+    beginInstanceTerminal(meshName, spotId, objectGeneration) {
+        const key = `${meshName}\0${String(spotId)}`;
+        this.pendingInstanceTerminals.set(key, (this.pendingInstanceTerminals.get(key) ?? 0) + 1);
+        const generations = this.pendingInstanceTerminalGenerations.get(key) ?? new Map();
+        const generationKey = objectGeneration.toString();
+        generations.set(generationKey, (generations.get(generationKey) ?? 0) + 1);
+        this.pendingInstanceTerminalGenerations.set(key, generations);
+    }
+    deferInstanceAuthorityRelease(key, objectGeneration) {
+        const generations = this.deferredInstanceAuthorityReleases.get(key) ?? new Set();
+        generations.add(objectGeneration);
+        this.deferredInstanceAuthorityReleases.set(key, generations);
+    }
+    removeDeferredInstanceAuthorityRelease(key, objectGeneration) {
+        const generations = this.deferredInstanceAuthorityReleases.get(key);
+        if (generations === undefined)
+            return;
+        generations.delete(objectGeneration);
+        if (generations.size === 0)
+            this.deferredInstanceAuthorityReleases.delete(key);
+    }
+    removePendingInstanceTerminalGeneration(key, objectGeneration) {
+        const generations = this.pendingInstanceTerminalGenerations.get(key);
+        if (generations === undefined)
+            return;
+        const generationKey = objectGeneration.toString();
+        const pending = generations.get(generationKey);
+        if (pending === undefined || pending <= 1)
+            generations.delete(generationKey);
+        else
+            generations.set(generationKey, pending - 1);
+    }
+    releaseInstanceAuthority(meshName, spotId, objectGeneration) {
+        return this.options.releaseInstanceAuthority?.(meshName, spotId, objectGeneration)
+            ?? Promise.resolve();
+    }
+    requireInstanceFactory(meshName, instanceType) {
+        const factory = this.options.instanceSpotFactories?.get(meshName)?.get(instanceType);
+        if (factory === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Instance Spot factory '${instanceType}' is not registered on RouteMesh '${meshName}'.`);
+        }
+        return factory;
+    }
+    scheduleIdleSweep() {
+        if (this.idleSweepTimer !== undefined)
+            return;
+        if (!this.hasIdleSweepTarget())
+            return;
+        const delays = [...(this.options.instanceSpotIdleTimeoutMs?.values() ?? [])]
+            .filter((value) => value > 0);
+        if (delays.length === 0)
+            return;
+        const delay = Math.max(1, Math.min(...delays));
+        const timer = setTimeout(() => {
+            this.idleSweepTimer = undefined;
+            void this.runIdleSweep();
+        }, delay);
+        timer.unref();
+        this.idleSweepTimer = timer;
+    }
+    hasIdleSweepTarget() {
+        return this.activations.hasActiveActivations();
+    }
+    async runIdleSweep() {
+        if (this.idleSweepRunning)
+            return;
+        this.idleSweepRunning = true;
+        try {
+            const now = performance.now();
+            for (const activation of this.activations.nextActiveActivationBatch()) {
+                const timeoutMs = this.options.instanceSpotIdleTimeoutMs?.get(activation.meshName) ?? 0;
+                if (timeoutMs <= 0
+                    || activation.domain.kind !== 'instance'
+                    || !activation.isIdleFor(now, timeoutMs)
+                    || !activation.beginIdleEviction()) {
+                    continue;
+                }
+                let durableClosing;
+                try {
+                    durableClosing = await (this.options.beginInstanceIdleClosingAuthority?.(activation.meshName, activation.spotId) ?? Promise.resolve({ restoreReady: async () => undefined }));
+                }
+                catch (error) {
+                    activation.abortIdleEviction();
+                    throw error;
+                }
+                if (durableClosing === undefined) {
+                    activation.abortIdleEviction();
+                    continue;
+                }
+                const close = this.closeWithReason(activation.meshName, activation.spotId, undefined, contracts_1.ZLinkSpotCloseReason.IdleEvicted);
+                const run = async () => {
+                    try {
+                        const closed = await close;
+                        if (!closed) {
+                            await durableClosing.restoreReady();
+                            activation.abortIdleEviction();
+                        }
+                    }
+                    catch (error) {
+                        if (error instanceof spot_activation_state_1.ZLinkSpotCloseOccupiedError) {
+                            await durableClosing.restoreReady();
+                        }
+                        activation.abortIdleEviction();
+                        throw error;
+                    }
+                };
+                this.options.detachedTaskRunner?.runDetached(`instance idle eviction ${String(activation.spotId)}`, run);
+                if (this.options.detachedTaskRunner === undefined) {
+                    void run().catch(() => undefined);
+                }
+            }
+        }
+        finally {
+            this.idleSweepRunning = false;
+            this.scheduleIdleSweep();
+        }
+    }
+    async create(meshName, spotType, requestOrSignal, signal) {
+        requireMeshName(meshName);
+        const args = normalizeSpotCreateArgs(requestOrSignal, signal);
+        this.options.admission?.requireRequest('SPOT create', meshName);
+        const spotId = this.activations.allocateSpotId(meshName);
+        const ownedRequest = args.request === undefined
+            ? runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0))
+            : (0, payload_codec_1.encodeFrameworkPayloadMessage)(args.request, this.options.messageSerializers);
+        try {
+            return await this.createActivation(meshName, spotType, spotId, ownedRequest, args.signal);
+        }
+        finally {
+            ownedRequest.close();
+        }
+    }
+    async getOrCreate(meshName, spotType, spotId, requestOrSignal, signal) {
+        return await this.getOrCreateWithAuthority(meshName, spotType, spotId, requestOrSignal, undefined, signal);
+    }
+    async getOrCreateWithAuthority(meshName, spotType, spotId, requestOrSignal, authority, signal) {
+        requireMeshName(meshName);
+        const args = normalizeSpotCreateArgs(requestOrSignal, signal);
+        (0, abort_1.throwIfAborted)(args.signal);
+        const operation = this.activations.getOrBegin(meshName, spotType, spotId, async () => {
+            this.options.admission?.requireRequest('SPOT create', meshName);
+            const ownedRequest = args.request === undefined
+                ? runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0))
+                : (0, payload_codec_1.encodeFrameworkPayloadMessage)(args.request, this.options.messageSerializers);
+            try {
+                return await this.createActivation(meshName, spotType, spotId, ownedRequest, undefined, authority);
+            }
+            finally {
+                ownedRequest.close();
+            }
+        });
+        return await (0, abort_1.awaitWithAbort)(operation.ready, args.signal);
+    }
+    async find(meshName, spotId) {
+        requireMeshName(meshName);
+        return this.activations.has(meshName, spotId) ? { spotId } : null;
+    }
+    async list(meshName) {
+        requireMeshName(meshName);
+        return this.activations.list(meshName);
+    }
+    async drainForShutdown(meshName, signal, deadline) {
+        const results = await Promise.allSettled(this.activations.activeActivations()
+            .filter(activation => activation.meshName === meshName)
+            .map(activation => this.closeWithReason(meshName, activation.spotId, signal, contracts_1.ZLinkSpotCloseReason.HostShutdown, deadline)));
+        const errors = results
+            .filter((result) => result.status === 'rejected')
+            .map(result => result.reason);
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, 'Spot shutdown cleanup failed.');
+    }
+    async close(meshName, spotId, signal) {
+        return await this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose);
+    }
+    async closeWithReason(meshName, spotId, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline) {
+        requireMeshName(meshName);
+        const key = `${meshName}\0${String(spotId)}`;
+        const closing = this.activations.closingOperation(meshName, spotId);
+        if (closing !== undefined) {
+            return await closing.ready;
+        }
+        const pendingClose = this.pendingInstanceCloses.get(key);
+        if (pendingClose !== undefined) {
+            const pendingActivation = this.activations.resolve(meshName, spotId);
+            if (pendingActivation?.serial.isCurrentTurn === true)
+                return true;
+            return await pendingClose;
+        }
+        const activation = this.activations.resolve(meshName, spotId);
+        if (activation === undefined) {
+            return false;
+        }
+        const currentTurn = activation.serial.isCurrentTurn;
+        const isInstance = activation.domain.kind === 'instance';
+        const beginClose = () => {
+            const seal = activation.sealExecution();
+            const operation = this.activations.startClose(meshName, spotId, (target) => this.activationLifecycle.closeAfterSeal(target, seal, signal, reason, deadline), (target) => this.activationLifecycle.resourcesReleased(target), reason);
+            if (operation === undefined) {
+                activation.abortExecutionSeal(seal);
+            }
+            return operation;
+        };
+        if (isInstance) {
+            const beginAuthorityClose = reason === contracts_1.ZLinkSpotCloseReason.ExplicitClose
+                ? this.options.beginInstanceClosingAuthority
+                : undefined;
+            // Register the close gate before waiting for the current application
+            // and activation-authority terminal completions. A close requested from
+            // a handler cannot publish Closing until that handler's durable inbox
+            // completion has removed the recovery fence.
+            const trackedClosePromise = (async () => {
+                const waitForApplication = this.options.instanceSpotApplicationQuiescenceProvider?.(meshName, spotId, signal);
+                if (waitForApplication !== undefined) {
+                    await waitForApplication;
+                }
+                const closingAuthority = beginAuthorityClose === undefined
+                    ? undefined
+                    : await beginAuthorityClose(meshName, spotId);
+                if (beginAuthorityClose !== undefined && closingAuthority === undefined) {
+                    return false;
+                }
+                const operation = beginClose();
+                if (operation === undefined) {
+                    await closingAuthority?.restoreReady();
+                    return false;
+                }
+                const closed = await operation.ready;
+                if (!closed)
+                    await closingAuthority?.restoreReady();
+                return closed;
+            })().finally(() => {
+                if (this.pendingInstanceCloses.get(key) === trackedClosePromise) {
+                    this.pendingInstanceCloses.delete(key);
+                }
+            });
+            this.pendingInstanceCloses.set(key, trackedClosePromise);
+            if (currentTurn) {
+                // The current turn must return before its terminal completion can
+                // release the activation recovery fence and allow the durable close
+                // CAS. The registered close gate prevents a second admission while
+                // that detached close finishes.
+                this.options.detachedTaskRunner?.runDetached(`instance spot close ${String(spotId)}`, async () => { await trackedClosePromise; });
+                if (this.options.detachedTaskRunner === undefined) {
+                    void trackedClosePromise.catch(() => undefined);
+                }
+                return true;
+            }
+            return await trackedClosePromise;
+        }
+        const operation = beginClose();
+        if (operation === undefined) {
+            return false;
+        }
+        if (currentTurn) {
+            if (operation.started) {
+                this.options.detachedTaskRunner?.runDetached(`spot close ${String(spotId)}`, async () => { await operation.ready; });
+                if (this.options.detachedTaskRunner === undefined) {
+                    void operation.ready.catch(() => undefined);
+                }
+            }
+            return true;
+        }
+        return await operation.ready;
+    }
+    async executeOnSpot(spotType, spotId, operation, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const activation = this.activations.resolveUnique(spotId);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        if (activation.spotType !== spotType) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' has a different spot type.`);
+        }
+        if (activation.serial.isCurrentTurn) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Spot '${String(spotId)}' cannot start a public operation from its current serial turn.`);
+        }
+        return activation.serial.execute(() => operation(activation.spot));
+    }
+    hasActiveSpot(spotId) {
+        return this.activations.resolveUnique(spotId) !== undefined;
+    }
+    canCloseUserSpot(meshName, spotId) {
+        return this.activations.canClose(meshName, spotId);
+    }
+    beginUserSpotPublication(meshName, spotId) {
+        this.activations.stage(meshName, spotId);
+    }
+    publishUserSpot(meshName, spotId) {
+        this.activations.publish(meshName, spotId);
+    }
+    abortUserSpotPublication(meshName, spotId) {
+        this.activations.abandonStage(meshName, spotId);
+    }
+    resolveLocalSpotRoute(spotId) {
+        const activation = this.activations.resolveUnique(spotId);
+        const generation = activation?.nativeSpot?.lifecycleGeneration;
+        if (activation === undefined || generation === undefined || generation <= 0n) {
+            return undefined;
+        }
+        const nodeRid = this.options.nodeRidProvider?.(activation.meshName) ?? this.options.nodeRid;
+        if (nodeRid === undefined) {
+            return undefined;
+        }
+        return {
+            routerChannelId: this.options.spotRouterChannelIdForMesh?.(activation.meshName) ?? activation.meshName,
+            targetNodeRid: nodeRid,
+            spotId: activation.spotId,
+            spotKind: contracts_1.ZLinkSpotKind.User,
+            targetSpotGeneration: generation
+        };
+    }
+    async admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType = 'application/json') {
+        const meshName = this.activations.resolveUnique(spotId)?.meshName;
+        this.options.admission?.requireRequest('Actor join admission', meshName);
+        return await this.actorMembership.admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType);
+    }
+    async leaveActor(spotId, actor, signal) {
+        const meshName = this.activations.resolveUnique(spotId)?.meshName;
+        await this.actorMembership.leaveActor(spotId, actor, signal, meshName);
+    }
+    async leaveActorInMesh(meshName, spotId, actor, signal) {
+        requireMeshName(meshName);
+        await this.actorMembership.leaveActor(spotId, actor, signal, meshName);
+    }
+    async notifyActorLeftAfterTransfer(spotId, actor, signal) {
+        await this.actorMembership.notifyActorLeftAfterTransfer(spotId, actor, signal);
+    }
+    async prepareActorLeaveForTransfer(spotId, actor, signal) {
+        await this.actorMembership.prepareActorLeaveForTransfer(spotId, actor, signal);
+    }
+    async commitActorLeaveAfterTransfer(spotId, actorId) {
+        await this.actorMembership.commitActorLeaveAfterTransfer(spotId, actorId);
+    }
+    async restoreActorAfterFailedTransfer(spotId, actor, signal) {
+        await this.actorMembership.restoreActorAfterFailedTransfer(spotId, actor, signal);
+    }
+    async beginActorTransfer(spotId, actorId) {
+        await this.actorMembership.beginActorTransfer(spotId, actorId);
+    }
+    async cancelActorTransfer(spotId, actorId) {
+        await this.actorMembership.cancelActorTransfer(spotId, actorId);
+    }
+    async notifyJoinedSpotActorDisconnected(spotId, actor, signal) {
+        return await this.actorMembership.notifyJoinedActorDisconnected(spotId, actor, signal);
+    }
+    dispatchRoutedActorPacket(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+        const activation = this.activations.resolveUnique(spotId);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        return this.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+    }
+    /** @internal Replays a record already owned by the Actor handoff queue. */
+    dispatchRoutedActorPacketDirect(spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+        const activation = this.activations.resolveUnique(spotId);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        return this.activationLifecycle.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+    }
+    /** @internal Atomically restores one durable packet prefix to an Actor FIFO. */
+    admitRoutedActorPacketPrefix(spotId, actorId, records) {
+        const activation = this.activations.resolveUnique(spotId);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
+        }
+        return this.activationLifecycle.admitActorPacketPrefix(activation, actorId, records);
+    }
+    async dispatchRoutedSpotSend(spotId, packetName, message, context) {
+        await this.routedSpotPackets.send(spotId, packetName, message, context);
+    }
+    async dispatchRoutedSpotRequest(spotId, packetName, request, context) {
+        return await this.routedSpotPackets.request(spotId, packetName, request, context);
+    }
+    async dispatchMeshSpot(meshName, owner, record) {
+        const spotId = owner.spotId;
+        if (spotId === null) {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Spot record is missing the owner Spot RID.');
+        }
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast) {
+            const activation = this.activations.resolve(meshName, spotId);
+            if (activation?.actorDispatch === undefined) {
+                throw new configuration_1.ZLinkConfigurationException(`MeshNode Spot multicast target '${String(spotId)}' is not active.`);
+            }
+            if (record.topic === null || record.topic.length === 0) {
+                throw new configuration_1.ZLinkConfigurationException('MeshNode Spot multicast record is missing its topic.');
+            }
+            await activation.actorDispatch.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            return;
+        }
+        const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(record.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        const packetName = envelope.packetName;
+        const codecs = this.options.messageSerializers === undefined
+            ? undefined
+            : { serializers: this.options.messageSerializers };
+        const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+        const context = {
+            channelName: envelope.header.channelName,
+            contentType: envelope.header.contentType,
+            workOptions: (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, record.applicationMetadata?.byteLength ?? (0, serial_work_size_1.zlinkMetadataByteLength)(envelope.header.metadata))
+        };
+        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
+            await this.ensureInstanceApplicationActivation(meshName, spotId);
+            await this.routedSpotPackets.sendEncoded(spotId, packetName, decodePayload, context);
+            return;
+        }
+        if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest) {
+            throw new configuration_1.ZLinkConfigurationException(`Unsupported MeshNode Spot record kind '${record.kind}'.`);
+        }
+        try {
+            await this.ensureInstanceApplicationActivation(meshName, spotId);
+            const response = await this.routedSpotPackets.requestEncoded(spotId, packetName, decodePayload, context);
+            requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+        }
+        catch (error) {
+            requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error instanceof Error ? error.message : String(error))));
+        }
+    }
+    async ensureInstanceApplicationActivation(meshName, spotId) {
+        let target = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+        if (target === undefined)
+            return;
+        for (;;) {
+            const current = this.activations.resolve(meshName, spotId);
+            if (current !== undefined
+                && current.objectGeneration === target.objectGeneration
+                && current.spotType === this.requireInstanceFactory(meshName, target.stableType))
+                return;
+            await this.materializeInstance(meshName, target.stableType, spotId, target.objectGeneration);
+            const latest = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+            if (latest === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, `Instance Spot target '${String(spotId)}' no longer has a Ready application target.`);
+            }
+            if (latest.objectGeneration === target.objectGeneration)
+                return;
+            target = latest;
+        }
+    }
+    async dispatchMeshInstance(meshName, owner, record) {
+        const spotId = owner.spotId;
+        if (spotId === null) {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Instance Spot record is missing the owner Spot RID.');
+        }
+        const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(record.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        const inboundFlow = (0, diagnostics_1.createInboundFlow)(envelope.header.flowId, envelope.header.flowOrigin, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        await (0, diagnostics_1.runWithFlow)(inboundFlow, async () => {
+            const request = record.operationKind === service_runtime_contracts_1.OperationKind.InstanceSpotRequest;
+            this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, meshName, spotId, record, envelope, 'activating');
+            try {
+                await this.ensureInstanceApplicationActivation(meshName, spotId);
+                const activation = this.activations.resolve(meshName, spotId);
+                if (activation === undefined || activation.domain.kind !== 'instance') {
+                    throw new configuration_1.ZLinkConfigurationException(`MeshNode Instance Spot target '${String(spotId)}' is not active.`);
+                }
+                const target = this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId);
+                if (target !== undefined
+                    && activation.domain.objectGeneration !== target.objectGeneration) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `Instance Spot target '${String(spotId)}' application generation is stale.`);
+                }
+                const codecs = this.options.messageSerializers === undefined
+                    ? undefined
+                    : { serializers: this.options.messageSerializers };
+                const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+                const context = {
+                    channelName: envelope.header.channelName,
+                    contentType: envelope.header.contentType,
+                    awaitFirstHandlerTurn: record.kind === service_runtime_contracts_1.ReceiveKind.InstanceSpotActivation,
+                    workOptions: (0, serial_work_size_1.zlinkSerialWorkOptions)(envelope.payload.byteLength, record.applicationMetadata?.byteLength ?? (0, serial_work_size_1.zlinkMetadataByteLength)(envelope.header.metadata))
+                };
+                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                if (!request) {
+                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                    await this.routedSpotPackets.sendEncoded(spotId, envelope.packetName, decodePayload, context);
+                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                    return;
+                }
+                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, meshName, spotId, record, envelope, 'ready', target?.stableType);
+                const response = await this.routedSpotPackets.requestEncoded(spotId, envelope.packetName, decodePayload, context);
+                requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+                this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, meshName, spotId, record, envelope, 'ready', target?.stableType);
+            }
+            catch (error) {
+                const reason = instanceDispatchErrorReason(error);
+                if (!request) {
+                    this.traceInstanceMessage(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, meshName, spotId, record, envelope, 'closing', undefined, reason);
+                    return;
+                }
+                this.options.dispatchErrors?.report({
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot,
+                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
+                    packetName: envelope.packetName,
+                    channelName: envelope.header.channelName,
+                    meshName,
+                    correlationId: envelope.header.correlationId ?? undefined,
+                    sourceRid: record.sourceNodeRid === null ? undefined : String(record.sourceNodeRid),
+                    spotId: String(spotId),
+                    instanceSpotType: this.options.instanceSpotApplicationTargetProvider?.(meshName, spotId)?.stableType,
+                    activationState: 'closing',
+                    flowId: envelope.header.flowId,
+                    flowOrigin: envelope.header.flowOrigin,
+                    reason,
+                    action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError,
+                    error
+                });
+                requireMeshSpotReply(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error instanceof Error ? error.message : String(error))));
+            }
+        });
+    }
+    traceInstanceMessage(outcome, meshName, spotId, record, envelope, activationState, instanceSpotType, errorReason) {
+        const flow = (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, outcome, undefined, envelope.header.flowId);
+        if (flow === undefined)
+            return;
+        flow.trace({
+            outcome,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot,
+            messageKind: record.operationKind === service_runtime_contracts_1.OperationKind.InstanceSpotRequest
+                ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request
+                : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            packetName: envelope.packetName,
+            channelName: envelope.header.channelName,
+            meshName,
+            correlationId: envelope.header.correlationId ?? undefined,
+            sourceRid: record.sourceNodeRid === null ? undefined : String(record.sourceNodeRid),
+            spotId: String(spotId),
+            instanceSpotType,
+            activationState,
+            flowId: envelope.header.flowId,
+            flowOrigin: envelope.header.flowOrigin,
+            errorReason
+        });
+    }
+    async dispatchMeshActor(meshName, owner, record) {
+        const spotId = owner.spotId;
+        const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
+        const targetsEntrySpot = spotId === null
+            || (entrySpotId !== undefined && spotId === entrySpotId);
+        const actor = owner.actor;
+        if (actor === null) {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Actor record is missing its Actor owner.');
+        }
+        const request = record.kind === service_runtime_contracts_1.ReceiveKind.ActorRequest;
+        if (record.sourceBindingGeneration > 0n) {
+            this.options.actorBindingGenerationObserver?.(actor.actorId, record.sourceBindingGeneration);
+        }
+        const resolvedOwner = this.options.actorDispatchOwnerResolver?.(actor.actorId);
+        const resolvedActorRef = resolvedOwner?.actorRef ?? {
+            actorId: actor.actorId,
+            objectGeneration: actor.generation,
+            meshName,
+            nodeRid: String(actor.nodeRid)
+        };
+        const responseActorRef = record.sourceBindingGeneration > 0n
+            ? {
+                ...resolvedActorRef,
+                bindingGeneration: record.sourceBindingGeneration
+            }
+            : resolvedActorRef;
+        const ownerActorRef = responseActorRef;
+        const requestTerminalState = { prepared: false, submitted: false };
+        const requestTerminal = request
+            ? Object.assign((response, preparedReply) => {
+                const encoded = preparedReply === undefined
+                    ? this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)
+                    : preparedReply;
+                requireMeshSpotReply(record.reply(encoded));
+                requestTerminalState.submitted = true;
+            }, {
+                prepare: (response) => {
+                    const encoded = this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Response, response);
+                    requestTerminalState.prepared = true;
+                    return encoded;
+                }
+            })
+            : undefined;
+        try {
+            if (this.formalRemoteTransfers.has(actor.actorId)) {
+                throw new Error(`Actor '${actor.actorId}' target transfer reconciliation is not complete.`);
+            }
+            const response = targetsEntrySpot
+                ? await this.options.dispatchEntryActorPacket?.(actor.actorId, record.parts, request, undefined, ownerActorRef, requestTerminal, record.messageFollowOrigin)
+                : await this.dispatchMeshActorPacket(meshName, spotId, actor.actorId, record.parts, request, ownerActorRef, requestTerminal, record.messageFollowOrigin);
+            if (targetsEntrySpot && this.options.dispatchEntryActorPacket === undefined) {
+                throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot Actor dispatch is not configured.');
+            }
+            if (request && !requestTerminalState.submitted) {
+                requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)));
+            }
+        }
+        catch (error) {
+            if (!request) {
+                throw error;
+            }
+            if (requestTerminalState.prepared || requestTerminalState.submitted) {
+                throw error;
+            }
+            requireMeshSpotReply(record.reply(this.encodeMeshActorReply(record.parts[0], protocol_1.ZLinkStreamMessageKind.Error, {
+                message: error instanceof Error ? error.message : String(error),
+                kind: error instanceof contracts_1.ZLinkFrameworkException
+                    ? error.kind
+                    : contracts_1.ZLinkFrameworkErrorKind.InternalFailure
+            })));
+        }
+    }
+    async dispatchMeshActorJoin(meshName, owner, record) {
+        const spotId = owner.spotId;
+        const control = record.kindData;
+        if (control?.kind !== 'actorControl') {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Actor join record is missing lifecycle identity data.');
+        }
+        const actorId = control.currentActor?.actorId;
+        if (spotId === null || actorId === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Actor join record is missing its Spot or Actor owner.');
+        }
+        const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
+        let requestContentType = record.contentType ?? 'application/json';
+        const targetsEntrySpot = entrySpotId !== undefined
+            && String(spotId) === String(entrySpotId);
+        const activation = this.activations.resolve(meshName, spotId);
+        const transferRequest = record.parts.length === 0
+            ? undefined
+            : decodeFormalRemoteTransferRequest(record.parts[0]);
+        const remoteJoinPhase = transferRequest?.phase;
+        const isRemoteAdmission = remoteJoinPhase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ADMISSION;
+        const isRemoteCommit = remoteJoinPhase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_COMMIT;
+        const isRemoteAbort = remoteJoinPhase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ABORT;
+        let admissionRecord = transferRequest !== undefined
+            ? this.formalRemoteActorAdmissions.get(transferRequest.transferId)
+            : undefined;
+        let canonicalAdmissionCreated = false;
+        let pendingAdmission = isRemoteCommit ? admissionRecord : undefined;
+        let commitAdmissionMissing = isRemoteCommit && admissionRecord === undefined;
+        const applicationClaim = transferRequest === undefined
+            ? this.options.admission?.claim(meshName, 'Actor join dispatch')
+            : undefined;
+        let canonicalActorType;
+        if (control.canonicalActorJoin !== undefined) {
+            const resolver = this.options.canonicalActorJoinResolver;
+            if (resolver === undefined) {
+                throw new configuration_1.ZLinkConfigurationException('Canonical Actor Join dispatch requires the Location Store admission resolver.');
+            }
+            const rawActorRef = control.previousActor ?? control.currentActor;
+            const rawRequest = record.parts[0];
+            if (rawActorRef === null) {
+                throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' canonical admission is missing its ActorRef or request.`);
+            }
+            const actorRef = toFrameworkRemoteAdmissionActorRef(rawActorRef, meshName);
+            const provisional = this.formalRemoteActorAdmissions.beginProvisional({
+                actorId,
+                actorRef,
+                spotId,
+                targetSpotGeneration: control.currentSpotGeneration,
+                expectedMembershipEpoch: control.currentMembershipEpoch,
+                requestFingerprint: rawRequest.data().toString('base64'),
+                transferId: control.canonicalActorJoin.handoffId,
+                sourceActorNodeRid: control.canonicalActorJoin.actorNodeRid
+            });
+            admissionRecord = provisional.record;
+            canonicalAdmissionCreated = provisional.created;
+            try {
+                canonicalActorType = (await resolver({ actorId, ...control.canonicalActorJoin })).actorType;
+            }
+            catch (error) {
+                this.formalRemoteActorAdmissions.fail(control.canonicalActorJoin.handoffId, error);
+                if (error instanceof contracts_1.ZLinkFrameworkException && record.replyFailure !== undefined) {
+                    const terminal = (0, framework_errors_internal_1.internalFrameworkWireReply)(error);
+                    requireMeshSpotReply(record.replyFailure(terminal.terminalResult, terminal.failureCode));
+                    return;
+                }
+                throw error;
+            }
+        }
+        const resolvedActor = this.options.actorResolver?.(actorId);
+        const lifecycleActor = targetsEntrySpot
+            ? this.options.actorLifecycleResolver?.(actorId)
+            : undefined;
+        let actor = resolvedActor;
+        if (actor === undefined && targetsEntrySpot) {
+            // An actor returning from a User Spot can still be marked as moving
+            // while the source-side relocation fence is being completed. Entry Spot
+            // admission must resolve that lifecycle object so the accepted Core
+            // reply can commit the return transaction.
+            actor = lifecycleActor;
+        }
+        if (actor === undefined && admissionRecord?.actor !== undefined) {
+            actor = admissionRecord.actor;
+        }
+        let callbackRequest = record.parts.length === 0
+            ? undefined
+            : record.parts[0];
+        let ownedCallbackRequest;
+        let materialized = false;
+        let reply;
+        let deferredJoinRoot;
+        let preparedTransferState;
+        let admissionOutcome;
+        let accepted = false;
+        let committedAdmissionReplay = isRemoteCommit
+            && admissionRecord?.state === 'committed';
+        let targetCommitPublished;
+        const actorJoinIsCurrent = () => ((record.deadlineUnixMs === undefined || record.deadlineUnixMs > BigInt(Date.now()))
+            && (record.isPending?.() ?? true));
+        const abandonStaleAdmission = () => {
+            if (isRemoteAdmission && transferRequest !== undefined) {
+                this.formalRemoteActorAdmissions.abort(transferRequest.transferId);
+            }
+        };
+        try {
+            if (!isRemoteAbort && !actorJoinIsCurrent()) {
+                abandonStaleAdmission();
+                return;
+            }
+            if (isRemoteAbort) {
+                if (transferRequest !== undefined) {
+                    this.formalRemoteActorAdmissions.abort(transferRequest.transferId);
+                }
+                requireMeshSpotReply(record.replyActorJoin(1, []));
+                return;
+            }
+            if (transferRequest !== undefined) {
+                ownedCallbackRequest = runtime_message_1.ZLinkBufferMessage.from(Buffer.from(transferRequest.request, 'base64'));
+                callbackRequest = ownedCallbackRequest;
+            }
+            else if (callbackRequest !== undefined) {
+                ownedCallbackRequest = runtime_message_1.ZLinkBufferMessage.from(callbackRequest.data());
+                callbackRequest = ownedCallbackRequest;
+            }
+            if (control.canonicalActorJoin !== undefined) {
+                if (callbackRequest === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' canonical admission could not resolve its request.`);
+                }
+                const actorType = canonicalActorType;
+                if (actorType === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' canonical admission has no Store-resolved Actor type.`);
+                }
+                const actorRef = toFrameworkRemoteAdmissionActorRef(control.previousActor ?? control.currentActor, meshName);
+                admissionRecord = this.formalRemoteActorAdmissions.finalizeProvisional(control.canonicalActorJoin.handoffId, {
+                    actorId,
+                    actorType,
+                    actorRef,
+                    spotId,
+                    targetSpotGeneration: control.currentSpotGeneration,
+                    expectedMembershipEpoch: control.currentMembershipEpoch,
+                    requestFingerprint: callbackRequest.data().toString('base64'),
+                    transferId: control.canonicalActorJoin.handoffId,
+                    sourceActorNodeRid: control.canonicalActorJoin.actorNodeRid
+                });
+                if (canonicalAdmissionCreated) {
+                    if (targetsEntrySpot) {
+                        admissionOutcome = {
+                            accepted: this.options.dispatchEntryActorJoin !== undefined,
+                            actorRef
+                        };
+                    }
+                    else if (activation === undefined) {
+                        admissionOutcome = { accepted: false, actorRef };
+                    }
+                    else {
+                        const response = await activation.serial.execute(async () => activation.spot.onActorJoin(actorRef.actorId, (0, payload_codec_1.wrapFrameworkPayloadMessage)(callbackRequest, this.options.messageSerializers, requestContentType)));
+                        let encodedReply;
+                        try {
+                            encodedReply = response.reply === undefined
+                                ? undefined
+                                : (0, payload_codec_1.encodeFrameworkPayloadMessage)(response.reply, this.options.messageSerializers);
+                            admissionOutcome = {
+                                accepted: response.accepted,
+                                actorRef,
+                                ...(encodedReply === undefined
+                                    ? {}
+                                    : {
+                                        reply: Buffer.from(encodedReply.data()),
+                                        replyContentType: (0, payload_codec_1.frameworkPayloadContentType)(encodedReply)
+                                    })
+                            };
+                        }
+                        finally {
+                            encodedReply?.close();
+                        }
+                    }
+                    this.formalRemoteActorAdmissions.complete(control.canonicalActorJoin.handoffId, admissionOutcome);
+                }
+                admissionOutcome = admissionRecord.result ?? await admissionRecord.resultTask;
+                if ('error' in admissionOutcome)
+                    throw admissionOutcome.error;
+                accepted = admissionOutcome.accepted;
+                reply = admissionOutcome.reply === undefined
+                    ? undefined
+                    : runtime_message_1.ZLinkBufferMessage.from(admissionOutcome.reply);
+            }
+            if (transferRequest !== undefined
+                && !targetsEntrySpot
+                && remoteJoinPhase === undefined) {
+                // User Spot transfers must carry the private admission/commit phases.
+                // A legacy one-phase request would otherwise read relocation state
+                // before the target application has accepted the Actor.
+                requireMeshSpotReply(record.replyActorJoin(1, []));
+                return;
+            }
+            if (isRemoteAdmission && transferRequest !== undefined) {
+                const rawActorRef = transferRequest.actorRef ?? control.currentActor ?? undefined;
+                if (rawActorRef === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' join record has no ActorRef.`);
+                }
+                const actorRef = toFrameworkRemoteAdmissionActorRef(rawActorRef, meshName);
+                const admission = this.formalRemoteActorAdmissions.begin({
+                    actorId,
+                    actorType: transferRequest.actorType,
+                    actorRef,
+                    spotId,
+                    targetSpotGeneration: control.currentSpotGeneration,
+                    expectedMembershipEpoch: transferRequest.expectedMembershipEpoch,
+                    requestFingerprint: transferRequest.request,
+                    transferId: transferRequest.transferId,
+                    completionOperationId: transferRequest.completionOperationId,
+                    sourceSpotId: transferRequest.sourceSpotId
+                });
+                admissionRecord = admission.record;
+                if (admission.created) {
+                    try {
+                        if (targetsEntrySpot) {
+                            if (this.options.dispatchEntryActorJoin !== undefined
+                                && transferRequest.completionOperationId !== undefined
+                                && this.options.actorTransferRuntime !== undefined) {
+                                deferredJoinRoot = await this.options.actorTransferRuntime
+                                    .prepareDeferredJoinAccepted(actorId, transferRequest.completionOperationId, actorRef, Buffer.alloc(0));
+                            }
+                            admissionOutcome = {
+                                accepted: this.options.dispatchEntryActorJoin !== undefined,
+                                actorRef,
+                                ...(deferredJoinRoot === undefined ? {} : { deferredJoinRoot })
+                            };
+                        }
+                        else if (activation === undefined) {
+                            admissionOutcome = { accepted: false, actorRef };
+                        }
+                        else {
+                            if (!actorJoinIsCurrent()) {
+                                abandonStaleAdmission();
+                                return;
+                            }
+                            const response = await activation.serial.execute(async () => activation.spot.onActorJoin(actorRef.actorId, (0, payload_codec_1.wrapFrameworkPayloadMessage)(ownedCallbackRequest, this.options.messageSerializers, transferRequest.requestContentType)));
+                            let encodedReply;
+                            try {
+                                encodedReply = response.reply === undefined
+                                    ? undefined
+                                    : (0, payload_codec_1.encodeFrameworkPayloadMessage)(response.reply, this.options.messageSerializers);
+                                if (response.accepted
+                                    && transferRequest.completionOperationId !== undefined
+                                    && this.options.actorTransferRuntime !== undefined) {
+                                    deferredJoinRoot = await this.options.actorTransferRuntime
+                                        .prepareDeferredJoinAccepted(actorId, transferRequest.completionOperationId, actorRef, encodedReply?.data() ?? Buffer.alloc(0), encodedReply === undefined
+                                        ? undefined
+                                        : (0, payload_codec_1.frameworkPayloadContentType)(encodedReply));
+                                    this.options.runtimeEventPublisher?.publish({
+                                        sourceName: 'zlink.framework.actor-handoff',
+                                        timestamp: new Date(),
+                                        marker: 'deferred_completion_staged',
+                                        actorId
+                                    });
+                                }
+                                admissionOutcome = {
+                                    accepted: response.accepted,
+                                    actorRef,
+                                    ...(deferredJoinRoot === undefined ? {} : { deferredJoinRoot }),
+                                    ...(encodedReply === undefined
+                                        ? {}
+                                        : {
+                                            reply: Buffer.from(encodedReply.data()),
+                                            replyContentType: (0, payload_codec_1.frameworkPayloadContentType)(encodedReply)
+                                        })
+                                };
+                            }
+                            finally {
+                                encodedReply?.close();
+                            }
+                            if (!actorJoinIsCurrent()) {
+                                abandonStaleAdmission();
+                                return;
+                            }
+                        }
+                        this.formalRemoteActorAdmissions.complete(transferRequest.transferId, admissionOutcome);
+                    }
+                    catch (error) {
+                        this.formalRemoteActorAdmissions.fail(transferRequest.transferId, error);
+                        throw error;
+                    }
+                }
+                admissionOutcome = await admissionRecord.resultTask;
+                if ('error' in admissionOutcome) {
+                    throw admissionOutcome.error;
+                }
+                accepted = admissionOutcome.accepted;
+                reply = admissionOutcome.reply === undefined
+                    ? undefined
+                    : runtime_message_1.ZLinkBufferMessage.from(admissionOutcome.reply);
+            }
+            if (isRemoteCommit && admissionRecord !== undefined) {
+                admissionOutcome = await admissionRecord.resultTask;
+                if ('error' in admissionOutcome) {
+                    throw admissionOutcome.error;
+                }
+                deferredJoinRoot = admissionOutcome.deferredJoinRoot;
+            }
+            if (actor === undefined
+                && transferRequest !== undefined
+                && this.options.actorTransferRuntime !== undefined
+                && !isRemoteAdmission
+                && !commitAdmissionMissing
+                && admissionRecord?.state !== 'committed'
+                && (targetsEntrySpot || activation !== undefined)) {
+                // Relocation state travels inline with the join request. The store
+                // reference handoff was removed with the direct-transfer contract
+                // (spec 28 §2 — Relocation Store keeps no relocation state payloads).
+                if (transferRequest.transferState === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' transfer commit carries no inline relocation state.`);
+                }
+                preparedTransferState = runtime_message_1.ZLinkBufferMessage.from(Buffer.from(transferRequest.transferState, 'base64'));
+            }
+            if (isRemoteAdmission && targetsEntrySpot) {
+                accepted = admissionOutcome !== undefined
+                    && !('error' in admissionOutcome)
+                    && admissionOutcome.accepted;
+            }
+            else if (isRemoteCommit && pendingAdmission !== undefined) {
+                validateRemoteAdmissionCommit(pendingAdmission, transferRequest, actorId, control);
+                accepted = pendingAdmission.state === 'admitted'
+                    || pendingAdmission.state === 'committed';
+            }
+            else if (commitAdmissionMissing) {
+                accepted = false;
+            }
+            else if (targetsEntrySpot) {
+                // Entry Spot return joins have no application admission callback. The
+                // actor-manager transaction is committed after the Core reply below.
+                // A formal transfer payload materializes the existing actor state at
+                // the Entry owner before that transaction is committed.
+                accepted = actor !== undefined
+                    || (transferRequest !== undefined && this.options.actorTransferRuntime !== undefined);
+            }
+            else if (!isRemoteAdmission
+                && control.canonicalActorJoin === undefined
+                &&
+                    activation !== undefined
+                && callbackRequest !== undefined
+                && (actor !== undefined || transferRequest !== undefined)) {
+                if (!actorJoinIsCurrent())
+                    return;
+                const request = callbackRequest;
+                const rawActorRef = transferRequest?.actorRef ?? control.currentActor ?? undefined;
+                if (rawActorRef === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' join record has no ActorRef.`);
+                }
+                const actorRef = {
+                    actorId: rawActorRef.actorId,
+                    objectGeneration: 'objectGeneration' in rawActorRef
+                        ? rawActorRef.objectGeneration
+                        : rawActorRef.generation,
+                    meshName,
+                    nodeRid: rawActorRef.nodeRid
+                };
+                const response = await activation.serial.execute(async () => activation.spot.onActorJoin(actorRef.actorId, (0, payload_codec_1.wrapFrameworkPayloadMessage)(request, this.options.messageSerializers, transferRequest?.requestContentType ?? requestContentType)));
+                if (!actorJoinIsCurrent())
+                    return;
+                accepted = response.accepted;
+                reply = response.reply === undefined
+                    ? undefined
+                    : (0, payload_codec_1.encodeFrameworkPayloadMessage)(response.reply, this.options.messageSerializers);
+                if (accepted
+                    && transferRequest?.completionOperationId !== undefined
+                    && this.options.actorTransferRuntime !== undefined) {
+                    deferredJoinRoot = await this.options.actorTransferRuntime
+                        .prepareDeferredJoinAccepted(actorId, transferRequest.completionOperationId, actorRef, reply?.data() ?? Buffer.alloc(0), reply === undefined ? undefined : (0, payload_codec_1.frameworkPayloadContentType)(reply));
+                    this.options.runtimeEventPublisher?.publish({
+                        sourceName: 'zlink.framework.actor-handoff',
+                        timestamp: new Date(),
+                        marker: 'deferred_completion_staged',
+                        actorId
+                    });
+                }
+            }
+            if (accepted
+                && !isRemoteAdmission
+                && actor === undefined
+                && transferRequest !== undefined
+                && this.options.actorTransferRuntime !== undefined) {
+                if (!actorJoinIsCurrent())
+                    return;
+                const transferState = preparedTransferState;
+                preparedTransferState = undefined;
+                if (transferState === undefined) {
+                    throw new Error('Remote actor transfer state was not prepared before admission.');
+                }
+                try {
+                    const result = await this.options.actorTransferRuntime.materializeRoutedActor(actorId, transferRequest.actorType, transferRequest.transferAdapterKey, transferState, transferRequest.actorEntryNodeRid, transferRequest.remoteBoundSessionTarget);
+                    actor = result.actor;
+                    materialized = true;
+                    await this.options.actorTransferRuntime.commitRoutedActorAuthority(actor, toFrameworkRemoteAdmissionActorRef(transferRequest.actorRef ?? control.currentActor, meshName), transferRequest.transferId, spotId, control.currentSpotGeneration, control.currentMembershipEpoch, record.deadlineUnixMs === undefined
+                        ? Date.now() + 5_000
+                        : Number(record.deadlineUnixMs), undefined);
+                }
+                finally {
+                    transferState.close();
+                }
+                if (!actorJoinIsCurrent()) {
+                    await this.options.actorTransferRuntime.rollbackRoutedActor(actor);
+                    materialized = false;
+                    return;
+                }
+            }
+            if (accepted
+                && transferRequest !== undefined
+                && this.options.actorTransferRuntime !== undefined
+                && !isRemoteAdmission) {
+                // A lightweight Core actor-join notification can create the Actor
+                // before the formal transfer request reaches this branch. Preserve
+                // the full relocation fence in that race so a later Session bind
+                // refresh cannot erase the seal or accepted journal.
+                this.options.actorTransferRuntime.rememberRoutedActorTransferTarget(actorId, transferRequest.remoteBoundSessionTarget);
+            }
+            if (accepted
+                && actor !== undefined
+                && transferRequest !== undefined
+                && !isRemoteAdmission
+                && !committedAdmissionReplay) {
+                this.formalRemoteTransfers.begin({
+                    actor,
+                    spotId,
+                    transferId: transferRequest.transferId,
+                    handoffBacklog: transferRequest.handoffBacklog,
+                    deferredJoinRoot
+                });
+                if (isRemoteCommit && admissionRecord !== undefined) {
+                    this.formalRemoteActorAdmissions.markCommitted(transferRequest.transferId, actor);
+                }
+            }
+            const replyActorJoin = () => {
+                if (!actorJoinIsCurrent())
+                    return false;
+                const joinReplyResult = record.replyActorJoin(accepted ? 0 : 1, reply === undefined ? [] : [reply.data()], undefined, admissionOutcome === undefined || 'error' in admissionOutcome
+                    ? undefined
+                    : admissionOutcome.replyContentType);
+                if (accepted && !isRemoteAdmission && joinReplyResult === runtime_values_1.SubmitResult.Ok) {
+                    // Core commits the target membership while it accepts this reply.
+                    // From this call onward a later callback/transport failure is
+                    // post-commit and must not roll the materialized Actor back.
+                    targetCommitPublished = true;
+                }
+                requireMeshSpotReply(joinReplyResult);
+                return true;
+            };
+            if (control.canonicalActorJoin !== undefined) {
+                replyActorJoin();
+                return;
+            }
+            if (accepted && targetsEntrySpot && actor !== undefined) {
+                const entryActor = actor;
+                const pendingTransfer = transferRequest === undefined
+                    ? undefined
+                    : this.formalRemoteTransfers.get(actorId);
+                if (committedAdmissionReplay) {
+                    if (!replyActorJoin())
+                        return;
+                }
+                else if (pendingTransfer === undefined) {
+                    if (!actorJoinIsCurrent())
+                        return;
+                    // The Core reply commits target membership. Entry lifecycle must
+                    // therefore run after that commit, as it does on the native path.
+                    if (!replyActorJoin())
+                        return;
+                    await this.options.dispatchEntryActorJoin?.(meshName, entryActor);
+                }
+                else {
+                    if (!replyActorJoin())
+                        return;
+                    const commitEntryTransfer = async () => {
+                        try {
+                            await this.options.dispatchEntryActorJoin?.(meshName, entryActor, []);
+                        }
+                        finally {
+                            this.formalRemoteTransfers.completeTargetLifecycle(entryActor.context.actorId, pendingTransfer.transferId);
+                        }
+                        const sourceLeaveSubmitted = await pendingTransfer.sourceLeaveSubmitted;
+                        if (!sourceLeaveSubmitted) {
+                            throw new Error(`Actor '${entryActor.context.actorId}' source authority commit failed before leave submission.`);
+                        }
+                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, async (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => {
+                            if (this.options.dispatchEntryActorPacket === undefined) {
+                                throw new Error('Entry Spot saved handoff replay requires its Actor packet runtime.');
+                            }
+                            return await this.options.dispatchEntryActorPacket(entryActor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+                        }, index => this.options.runtimeEventPublisher?.publish({
+                            sourceName: 'zlink.framework.actor-handoff',
+                            timestamp: new Date(),
+                            marker: 'backlog_enqueued',
+                            actorId: entryActor.context.actorId,
+                            index
+                        }));
+                        const failedHandoff = handoffResults.find(result => !result.ok);
+                        if (failedHandoff !== undefined) {
+                            throw new Error(`Actor '${entryActor.context.actorId}' saved Entry handoff packet `
+                                + `${failedHandoff.index} failed: ${failedHandoff.error ?? 'unknown error'}.`);
+                        }
+                        this.formalRemoteTransfers.delete(entryActor.context.actorId);
+                    };
+                    this.options.detachedTaskRunner?.runDetached(`actor Entry Spot transfer ${entryActor.context.actorId}`, commitEntryTransfer);
+                    if (this.options.detachedTaskRunner === undefined) {
+                        void commitEntryTransfer().catch(() => undefined);
+                    }
+                }
+            }
+            else {
+                if (!replyActorJoin())
+                    return;
+            }
+        }
+        catch (error) {
+            if (control.canonicalActorJoin !== undefined) {
+                this.formalRemoteActorAdmissions.fail(control.canonicalActorJoin.handoffId, error);
+            }
+            if (deferredJoinRoot !== undefined && targetCommitPublished !== true) {
+                await this.options.actorTransferRuntime?.discardDeferredJoinAccepted(deferredJoinRoot);
+            }
+            if (targetCommitPublished !== true) {
+                this.formalRemoteTransfers.delete(actorId);
+            }
+            if (materialized && targetCommitPublished !== true) {
+                await this.options.actorTransferRuntime?.rollbackRoutedActor(actor);
+            }
+            throw error;
+        }
+        finally {
+            preparedTransferState?.close();
+            ownedCallbackRequest?.close();
+            reply?.close();
+            applicationClaim?.close();
+        }
+    }
+    async dispatchMeshSpotControl(meshName, owner, record) {
+        const spotId = owner.spotId;
+        const control = record.kindData;
+        if (control?.kind !== 'actorControl') {
+            throw new configuration_1.ZLinkConfigurationException('MeshNode Spot control record is missing actor lifecycle data.');
+        }
+        const actorRef = control.lifecycleKind === service_runtime_contracts_1.ActorLifecycleKind.Left
+            ? control.previousActor
+            : control.currentActor;
+        const actorId = actorRef?.actorId;
+        const pendingTransfer = actorId === undefined
+            ? undefined
+            : this.formalRemoteTransfers.get(actorId);
+        const sourceActivation = actorId === undefined || spotId === null
+            ? undefined
+            : this.activations.resolve(meshName, spotId);
+        const sourceJoinedActor = actorId === undefined
+            ? undefined
+            : sourceActivation?.resolveJoinedActor(actorId);
+        const actor = actorId === undefined
+            ? undefined
+            : pendingTransfer?.actor
+                ?? sourceJoinedActor
+                ?? this.options.actorLifecycleResolver?.(actorId)
+                ?? this.options.actorResolver?.(actorId);
+        const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
+        if (actor === undefined) {
+            return;
+        }
+        if (control.lifecycleKind === service_runtime_contracts_1.ActorLifecycleKind.Left
+            && (spotId === null || (entrySpotId !== undefined && String(spotId) === String(entrySpotId)))) {
+            const callback = async () => {
+                await this.options.entrySpotCallbacks?.onLeaveActor(actor, undefined, actorRef, control.previousMembershipEpoch);
+            };
+            if (this.options.actorTransferRuntime === undefined) {
+                await callback();
+            }
+            else {
+                await this.options.actorTransferRuntime.notifyCoreSourceLeave(actor, callback);
+            }
+            return;
+        }
+        if (spotId === null) {
+            return;
+        }
+        const activation = this.activations.resolve(meshName, spotId);
+        if (activation === undefined) {
+            return;
+        }
+        await activation.serial.execute(async () => {
+            if (control.lifecycleKind === service_runtime_contracts_1.ActorLifecycleKind.Joined) {
+                if (control.currentActor !== null) {
+                    this.options.actorTransferRuntime?.bindRoutedActorRef(actor, control.currentActor);
+                }
+                this.options.actorTransferRuntime?.commitRoutedActor(actor, spotId, activation.spot);
+                const completeTargetLifecycle = async () => {
+                    await this.options.actorTransferRuntime?.claimRoutedActorLocation(actor, spotId, meshName, {
+                        spotGeneration: control.currentSpotGeneration,
+                        membershipEpoch: control.currentMembershipEpoch
+                    });
+                    // Make the Actor resolvable for lifecycle and saved-work dispatch,
+                    // while formalRemoteTransfers continues to fence new ingress until
+                    // the saved backlog has completed.
+                    activation.commitActorJoin(actor);
+                    await activation.spot.onJoinedActor(actor);
+                };
+                const completePublicJoin = async () => {
+                    const deferredJoinRoot = pendingTransfer?.deferredJoinRoot;
+                    if (deferredJoinRoot !== undefined) {
+                        const currentRef = this.options.actorTransferRuntime === undefined
+                            ? null
+                            : control.currentActor;
+                        if (currentRef === null) {
+                            throw new Error(`Actor '${actor.context.actorId}' has no target ref for deferred Join completion.`);
+                        }
+                        await this.options.actorTransferRuntime?.commitAndDeliverDeferredJoinAccepted(deferredJoinRoot, actor, currentRef, operation => activation.executeActor(actor.context.actorId, async () => await operation()));
+                    }
+                };
+                const completeTargetReady = async () => {
+                    if (pendingTransfer !== undefined) {
+                        const handoffResults = await (0, actor_handoff_1.replayActorHandoffBacklog)(pendingTransfer.handoffBacklog, (parts, returnResponse, remoteBoundSessionTarget, _fallbackActorRef) => this.dispatchActorPacket(activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, undefined), (index) => this.options.runtimeEventPublisher?.publish({
+                            sourceName: 'zlink.framework.actor-handoff',
+                            timestamp: new Date(),
+                            marker: 'backlog_enqueued',
+                            actorId: actor.context.actorId,
+                            index
+                        }));
+                        const failedHandoff = handoffResults.find(result => !result.ok);
+                        if (failedHandoff !== undefined) {
+                            throw new Error(`Actor '${actor.context.actorId}' saved handoff packet `
+                                + `${failedHandoff.index} failed: ${failedHandoff.error ?? 'unknown error'}.`);
+                        }
+                        // Spec 15 §4.2 relocation temporary queue: arrivals parked at
+                        // this target directly (not relayed through the source's
+                        // ingress hold) migrate into the real Actor queue next, in the
+                        // order they parked — after the relayed backlog above, before
+                        // regular ingress opens.
+                        await this.migrateActorJoinPrewarm(activation, actor, pendingTransfer.transferId);
+                        // This registry owns target lifecycle and saved backlog
+                        // reconciliation only. Session route readiness is enforced by
+                        // the Session binding aggregate after this boundary.
+                        this.formalRemoteTransfers.delete(actor.context.actorId);
+                    }
+                    const updateBoundSessionRoute = async () => {
+                        await this.options.actorTransferRuntime?.publishRoutedActorOwnership(actor);
+                        await this.options.actorTransferRuntime?.openRoutedActorSession(actor);
+                    };
+                    // Session routing is an independent post-Ready branch. Callback
+                    // sends are retained by the Session owner seal until this converges.
+                    if (pendingTransfer !== undefined && this.options.detachedTaskRunner !== undefined) {
+                        this.options.detachedTaskRunner.runDetached(`actor transfer Session route ${actor.context.actorId}`, updateBoundSessionRoute);
+                    }
+                    else {
+                        await updateBoundSessionRoute();
+                    }
+                };
+                if (pendingTransfer !== undefined) {
+                    const resume = async () => {
+                        try {
+                            await activation.serial.post(completeTargetLifecycle);
+                        }
+                        finally {
+                            this.formalRemoteTransfers.completeTargetLifecycle(actor.context.actorId, pendingTransfer.transferId);
+                        }
+                        const sourceLeaveSubmitted = await pendingTransfer.sourceLeaveSubmitted;
+                        if (!sourceLeaveSubmitted) {
+                            throw new Error(`Actor '${actor.context.actorId}' source authority commit failed before leave submission.`);
+                        }
+                        await completePublicJoin();
+                        // Saved handlers enter the Spot owner on their own turns. Run
+                        // them only after the lifecycle turn above has been released.
+                        await completeTargetReady();
+                    };
+                    this.options.detachedTaskRunner?.runDetached(`actor transfer target commit ${actor.context.actorId}`, resume);
+                    if (this.options.detachedTaskRunner === undefined) {
+                        void resume().catch(() => undefined);
+                    }
+                    return;
+                }
+                await completeTargetLifecycle();
+                await completePublicJoin();
+                await completeTargetReady();
+                return;
+            }
+            if (control.lifecycleKind === service_runtime_contracts_1.ActorLifecycleKind.Left) {
+                if (this.options.actorTransferRuntime === undefined) {
+                    await activation.spot.onLeaveActor(actor);
+                }
+                else {
+                    // Spot.Context.leaveActor can run the source callback before the
+                    // native Entry join is submitted. In that path the membership is
+                    // already committed away, so a later Core LEFT control must not
+                    // execute the same callback twice.
+                    if (sourceJoinedActor === undefined && pendingTransfer === undefined) {
+                        return;
+                    }
+                    await this.options.actorTransferRuntime.notifyCoreSourceLeave(actor, () => activation.spot.onLeaveActor(actor));
+                }
+                activation.commitActorDeparture(actor.context.actorId);
+                return;
+            }
+            if (control.lifecycleKind === service_runtime_contracts_1.ActorLifecycleKind.Disconnected) {
+                await activation.spot.onDisconnectActor?.(actor);
+            }
+        });
+    }
+    async completeFormalSourceLeaveTerminal(actorId, transferId, succeeded) {
+        return await this.formalRemoteTransfers.completeSourceLeaveTerminal(actorId, transferId, succeeded);
+    }
+    async finalizeActorJoinRelocation(meshName, relocationId, actor, actorRef, submitSourceLeave, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const admission = this.formalRemoteActorAdmissions.get(relocationId);
+        if (admission === undefined)
+            return false;
+        if (admission.admission.actorId !== actor.context.actorId) {
+            throw new Error(`Actor Join relocation '${relocationId}' changed its admitted Actor.`);
+        }
+        const outcome = admission.result ?? await admission.resultTask;
+        if ('error' in outcome)
+            throw outcome.error;
+        if (!outcome.accepted || admission.state !== 'admitted') {
+            throw new Error(`Actor Join relocation '${relocationId}' has no accepted admission.`);
+        }
+        const entrySpotId = this.options.entryNodeRidProvider?.() ?? this.options.entryNodeRid;
+        const targetsEntry = entrySpotId !== undefined
+            && String(admission.admission.spotId) === String(entrySpotId);
+        if (targetsEntry) {
+            await this.options.dispatchEntryActorJoin?.(meshName, actor, []);
+        }
+        else {
+            const activation = this.activations.resolve(meshName, admission.admission.spotId);
+            if (activation === undefined) {
+                throw new Error(`Actor Join relocation '${relocationId}' target Spot is not active.`);
+            }
+            await activation.serial.execute(() => activation.spot.onJoinedActor(actor));
+        }
+        await submitSourceLeave(admission.admission.actorRef.nodeRid);
+        if (outcome.deferredJoinRoot !== undefined && this.options.actorTransferRuntime !== undefined) {
+            const submitMailbox = targetsEntry
+                ? (operation) => operation()
+                : (operation) => {
+                    const activation = this.activations.resolve(meshName, admission.admission.spotId);
+                    if (activation === undefined) {
+                        throw new Error(`Actor Join relocation '${relocationId}' target mailbox is missing.`);
+                    }
+                    return activation.executeActor(actor.context.actorId, operation);
+                };
+            await this.options.actorTransferRuntime.commitAndDeliverDeferredJoinAccepted(outcome.deferredJoinRoot, actor, actorRef, submitMailbox, signal);
+        }
+        this.formalRemoteActorAdmissions.markCommitted(relocationId, actor);
+        return true;
+    }
+    async restoreCanonicalActorJoinRecovery(recovery, signal, canonicalInventoryDigest) {
+        (0, abort_1.throwIfAborted)(signal);
+        const admission = this.formalRemoteActorAdmissions.get(recovery.request.handoffId);
+        if (admission === undefined) {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' has no canonical command-28 admission.`);
+        }
+        const outcome = admission.result ?? await admission.resultTask;
+        if ('error' in outcome || !outcome.accepted || admission.state !== 'admitted') {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' has no accepted admission.`);
+        }
+        const admitted = admission.admission;
+        if (admitted.sourceActorNodeRid === undefined) {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' lost its command-28 source route.`);
+        }
+        const admittedNodeBytes = Buffer.from((0, routing_id_1.encodeRoutingIdStorageHex)(admitted.sourceActorNodeRid), 'hex');
+        if (admitted.actorId !== recovery.request.actorId
+            || admitted.actorType !== recovery.request.actorType
+            || admitted.requestFingerprint !== recovery.request.request.toString('base64')
+            || String(admitted.spotId) !== recovery.targetSpotId
+            || admitted.targetSpotGeneration !== recovery.targetSpotGeneration
+            || admitted.actorRef.objectGeneration !== recovery.request.actorGeneration
+            || !admittedNodeBytes.equals(recovery.request.sourceNodeRid)) {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' changed its command-28 identity.`);
+        }
+        const admittedReply = outcome.reply ?? Buffer.alloc(0);
+        if (!admittedReply.equals(recovery.reply)) {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' changed its admission reply.`);
+        }
+        if (recovery.operationId === undefined) {
+            if (recovery.replyContentType !== undefined || recovery.reply.byteLength !== 0) {
+                throw new Error(`Actor Join recovery '${recovery.request.handoffId}' has a reply without an OperationId.`);
+            }
+            return;
+        }
+        const outerReplyContentType = admittedReply.byteLength === 0
+            ? recovery.replyContentType
+            : service_wire_constants_generated_1.SERVICE_FRAMEWORK_MULTIPART_CONTENT_TYPE;
+        if (recovery.replyContentType !== outerReplyContentType) {
+            throw new Error(`Actor Join recovery '${recovery.request.handoffId}' changed its reply content type.`);
+        }
+        // Command 28 carries a present reply in one outer framework-multipart
+        // part. The accepted target admission still owns the inner typed content
+        // type, which the durable completion must retain for application decode.
+        const admittedContentType = admittedReply.byteLength === 0
+            ? recovery.replyContentType
+            : outcome.replyContentType;
+        const transfer = this.options.actorTransferRuntime;
+        if (transfer === undefined) {
+            throw new Error('Canonical Actor Join recovery requires the Actor transfer runtime.');
+        }
+        const deferred = await transfer.prepareDeferredJoinAccepted(recovery.request.actorId, recovery.operationId, admitted.actorRef, recovery.reply, admittedContentType, signal, canonicalInventoryDigest);
+        this.formalRemoteActorAdmissions.attachDeferredJoinRoot(recovery.request.handoffId, deferred);
+        return deferred;
+    }
+    encodeMeshActorReply(requestHeaderPart, kind, payload) {
+        // Spec 27 §4/§7: the decode gate strips the observation-only flow pair at
+        // Off (and skips its validation); when tracing is on the reply preserves
+        // the request's flow pair alongside its correlation.
+        const requestHeader = (0, protocol_1.decodeStreamHeader)(requestHeaderPart.data(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+        const encoded = (0, payload_codec_1.encodeFrameworkPayload)(payload, this.options.messageSerializers);
+        try {
+            //  encodeStreamHeader returns a fresh, unaliased array; view it without
+            //  re-copying. The payload copy stays: encoded.message closes below.
+            const replyHeader = (0, protocol_1.encodeStreamHeader)({
+                kind,
+                codec: (0, protocol_1.streamCodecForContentType)(encoded.contentType),
+                flags: protocol_1.ZLinkStreamHeaderFlags.None,
+                requestSeq: requestHeader.requestSeq,
+                name: '',
+                metadata: new Map(),
+                correlationId: requestHeader.correlationId,
+                flowId: requestHeader.flowId,
+                flowOrigin: requestHeader.flowOrigin
+            });
+            return [
+                Buffer.from(replyHeader.buffer, replyHeader.byteOffset, replyHeader.byteLength),
+                Buffer.from(encoded.message.data())
+            ];
+        }
+        finally {
+            encoded.message.close();
+        }
+    }
+    async createActivation(meshName, spotType, spotId, request, signal, authority) {
+        this.requireRegisteredFactory(spotType);
+        return await this.activationLifecycle.create(meshName, spotType, spotId, request, signal, authority);
+    }
+    requireRegisteredFactory(spotType) {
+        if (!this.factories.has(spotType)) {
+            throw new configuration_1.ZLinkConfigurationException('Spot type is not registered as a spot factory.');
+        }
+    }
+    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        return await this.activationLifecycle.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    }
+    /**
+     * Spec 15 §4.2 relocation temporary queue: drains every arrival parked
+     * for this exact Actor Join admission attempt since Accepted, in order,
+     * dispatching each one for real now that the Actor has cut over locally.
+     * {@link ZLinkFormalRemoteActorAdmissionRegistry#completeMigration}
+     * synchronously snapshots the parked queue and flips the attempt to
+     * `migrated` before this method dispatches anything, so a racing arrival
+     * either lands in the snapshot or resolves the Actor directly through
+     * ordinary ingress — never both, never neither.
+     */
+    async migrateActorJoinPrewarm(activation, actor, transferId) {
+        const drained = this.formalRemoteActorAdmissions.completeMigration(transferId);
+        for (const arrival of drained) {
+            try {
+                const response = await this.dispatchActorPacket(activation, actor.context.actorId, [
+                    runtime_message_1.ZLinkBufferMessage.from(arrival.header),
+                    runtime_message_1.ZLinkBufferMessage.from(arrival.payload)
+                ], arrival.returnResponse, arrival.remoteBoundSessionTarget, arrival.fallbackActorRef, arrival.requestTerminal);
+                arrival.resolve(response);
+            }
+            catch (error) {
+                arrival.reject(error);
+            }
+        }
+    }
+    async dispatchMeshActorPacket(meshName, spotId, actorId, parts, returnResponse, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        const activation = this.activations.resolve(meshName, spotId);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Spot '${String(spotId)}' is not active in mesh '${meshName}'.`);
+        }
+        return await this.dispatchActorPacket(activation, actorId, parts, returnResponse, undefined, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    }
+}
+exports.DefaultZLinkSpotManager = DefaultZLinkSpotManager;
+function instanceDispatchErrorReason(error) {
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
+        const kind = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
+        if (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound) {
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget;
+        }
+    }
+    return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+}
+function decodeFormalRemoteTransferRequest(message) {
+    return decodeFormalRemoteTransferRequestBytes(message.data());
+}
+function decodeFormalRemoteTransferRequestBytes(bytes) {
+    let payload;
+    try {
+        payload = JSON.parse(Buffer.from(bytes).toString());
+    }
+    catch {
+        return undefined;
+    }
+    if (payload.packetName !== actor_remote_wire_1.REMOTE_ACTOR_JOIN_PACKET
+        || typeof payload.actorType !== 'string'
+        || typeof payload.transferId !== 'string'
+        || !(payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ADMISSION
+            || payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ABORT
+            || payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_COMMIT
+            || payload.phase === undefined)
+        || !(payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ADMISSION
+            || payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ABORT
+            || (typeof payload.transferState === 'string'))
+        || typeof payload.request !== 'string') {
+        return undefined;
+    }
+    return {
+        actorType: payload.actorType,
+        actorId: typeof payload.actorId === 'string' ? payload.actorId : undefined,
+        phase: payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ADMISSION
+            || payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_COMMIT
+            || payload.phase === actor_remote_wire_1.REMOTE_ACTOR_JOIN_ABORT
+            ? payload.phase
+            : undefined,
+        transferId: payload.transferId,
+        transferAdapterKey: typeof payload.transferAdapterKey === 'string'
+            ? payload.transferAdapterKey
+            : undefined,
+        transferState: typeof payload.transferState === 'string'
+            ? payload.transferState
+            : undefined,
+        request: payload.request,
+        requestContentType: typeof payload.requestContentType === 'string'
+            ? payload.requestContentType
+            : 'application/json',
+        actorEntryNodeRid: typeof payload.actorEntryNodeRid === 'string'
+            ? (0, routing_id_1.decodeRoutingId)(payload.actorEntryNodeRid, payload.actorEntryNodeRidHex)
+            : undefined,
+        sourceSpotId: typeof payload.sourceSpotId === 'string'
+            ? payload.sourceSpotId
+            : undefined,
+        actorRef: decodeFormalRemoteActorRef(payload),
+        remoteBoundSessionTarget: (0, spot_remote_codec_1.decodeRemoteBoundSessionTarget)(payload.boundSessionRouterChannelId, payload.boundSessionTargetNodeRid, payload.boundSessionTargetNodeRidHex, payload.boundSessionSpotId, payload.boundSessionNodeRid, payload.boundSessionNodeRidHex, payload.boundSessionRid, payload.boundSessionRidHex, payload.boundSessionBindingGeneration, payload.boundSessionPreviousAuthorityOwnerGeneration, payload.boundSessionPreviousOwnerLeaseGeneration, payload.boundSessionRelocationSealId, payload.boundSessionServiceWireRelocation),
+        expectedMembershipEpoch: typeof payload.expectedMembershipEpoch === 'string'
+            ? BigInt(payload.expectedMembershipEpoch)
+            : 0n,
+        handoffBacklog: (0, spot_remote_codec_1.decodeHandoffBacklog)(payload.handoffBacklog),
+        completionOperationId: typeof payload.completionOperationHigh === 'string'
+            && typeof payload.completionOperationLow === 'string'
+            ? {
+                high: BigInt(payload.completionOperationHigh),
+                low: BigInt(payload.completionOperationLow)
+            }
+            : undefined
+    };
+}
+function decodeFormalRemoteActorRef(payload) {
+    const backend = (0, spot_remote_codec_1.decodeRemoteActorRef)(payload.actorNodeRid, payload.actorNodeRidHex, typeof payload.actorId === 'string' ? payload.actorId : '', payload.actorGeneration);
+    if (backend === undefined || typeof payload.routerChannelId !== 'string') {
+        return undefined;
+    }
+    return {
+        actorId: backend.actorId,
+        objectGeneration: backend.generation,
+        meshName: payload.routerChannelId,
+        nodeRid: backend.nodeRid
+    };
+}
+function requireMeshSpotReply(result) {
+    if (result !== runtime_values_1.SubmitResult.Ok) {
+        throw new configuration_1.ZLinkConfigurationException(`MeshNode reply was not accepted (submit result ${result}).`);
+    }
+}
+function toFrameworkRemoteAdmissionActorRef(rawActorRef, meshName) {
+    const objectGeneration = rawActorRef.objectGeneration ?? rawActorRef.generation;
+    if (objectGeneration === undefined) {
+        throw new configuration_1.ZLinkConfigurationException(`Actor '${rawActorRef.actorId}' join record has no ObjectGeneration.`);
+    }
+    return {
+        actorId: rawActorRef.actorId,
+        objectGeneration,
+        meshName,
+        nodeRid: rawActorRef.nodeRid
+    };
+}
+function validateRemoteAdmissionCommit(admission, request, actorId, control) {
+    const expected = admission.admission;
+    const actorRef = request.actorRef;
+    if (expected.actorId !== actorId
+        || expected.actorType !== request.actorType
+        || expected.expectedMembershipEpoch !== request.expectedMembershipEpoch
+        || expected.requestFingerprint !== request.request
+        || expected.targetSpotGeneration !== (control.currentSpotGeneration ?? 0n)
+        || actorRef === undefined
+        || actorRef.actorId !== expected.actorRef.actorId
+        || String(actorRef.nodeRid) !== String(expected.actorRef.nodeRid)
+        || actorRef.objectGeneration !== expected.actorRef.objectGeneration) {
+        throw new configuration_1.ZLinkConfigurationException(`Remote Actor '${actorId}' commit does not match its target admission.`);
+    }
+}
+function normalizeSpotCreateArgs(requestOrSignal, signal) {
+    if (isAbortSignal(requestOrSignal)) {
+        return { request: undefined, signal: requestOrSignal };
+    }
+    return { request: requestOrSignal, signal };
+}
+function requireMeshName(meshName) {
+    if (meshName.length === 0) {
+        throw new configuration_1.ZLinkConfigurationException('Spot operations require a mesh name.');
+    }
+}
+function instanceMaterializationPrefix(meshName, spotId) {
+    return `${meshName}\0${String(spotId)}`;
+}
+function instanceMaterializationKey(meshName, spotId, objectGeneration) {
+    return `${instanceMaterializationPrefix(meshName, spotId)}\0${objectGeneration}`;
+}
+function isAbortSignal(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.aborted === 'boolean'
+        && typeof value.addEventListener === 'function';
+}
+function instanceActivationOutcome(error) {
+    if ((0, abort_1.isAbortError)(error))
+        return 'shutdown';
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
+        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.DeadlineExceeded)
+            return 'timed_out';
+        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.AlreadyExists)
+            return 'conflict';
+        if (error.kind === contracts_1.ZLinkFrameworkErrorKind.InvalidOperation
+            || error.kind === contracts_1.ZLinkFrameworkErrorKind.Unavailable)
+            return 'fenced';
+    }
+    return 'failed';
+}