@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/spots/spot-node-runtime-manager.d.ts

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { type ActorRef, type RoutingId, type ZLinkActor, type ZLinkChannelClient, type ZLinkFanoutClient, type ZLinkMeshNodeDescriptor, type ZLinkMessage, type ZLinkMessageSerializer, type ZLinkSpotPublisherClient, ZLinkFrameworkRuntimeState } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
@@ -9,7 +10,7 @@ import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import type { ZLinkBackendAdapterFactory, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
 import { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
 import type { ZLinkDispatchErrorReporter } from '../channels';
-import { type ZLinkFrameworkRegistration } from '../configuration';
+import { type ZLinkFrameworkRegistration, type ZLinkSpotNodeOptions } from '../configuration';
 import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
 import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import { type ZLinkMessageFollowOrigin, type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
@@ -75,6 +76,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     constructor(options: ZLinkSpotNodeRuntimeManagerOptions);
     createTopicMessage(): import("../backend/runtime-values").ZLinkBackendTopicMessage;
     configureLocationAutoConnect(runtime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, events?: ZLinkLocationEventSink): void;
+    requestPeerReconcile(meshName: string, peerRid: string): Promise<void>;
     startLocationAutoConnect(signal?: AbortSignal): Promise<void>;
     /**
      * Fences transport connections that were created under an owner token which
@@ -85,6 +87,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     start(): Promise<void>;
     publishMeshNodeState(state: ZLinkFrameworkRuntimeState, signal?: AbortSignal, selectedMeshName?: string): Promise<void>;
     private publishMeshNodeStateCore;
+    private localDescriptorFields;
     reconcileAndPublishMeshNodeState(state: ZLinkFrameworkRuntimeState, meshName: string, signal?: AbortSignal): Promise<void>;
     private entrySpotId;
     get meshNodesByName(): ReadonlyMap<string, ZLinkBackendMeshNode>;
@@ -112,13 +115,21 @@ export declare class ZLinkSpotNodeRuntimeManager {
     serverChannels(meshName: string): [string, import("../configuration").ZLinkMeshChannelOptions][];
     dispose(signal?: AbortSignal, deadline?: Date): Promise<void>;
     private disposeCore;
+    /**
+     * Node and Channel records go straight to the framework dispatcher in the
+     * pump's turn. Only Spot and Actor records addressed to the Entry Spot wait
+     * for its activation first.
+     */
     private dispatchMeshRecord;
-    dispatchEntrySpotRecord(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<boolean>;
+    private targetsEntrySpot;
+    private dispatchFrameworkRecord;
+    dispatchEntrySpotRecord(meshName: string, owner: ReadyRecord, record: ReceiveRecord, admit?: ZLinkMeshDispatchAdmission): Promise<boolean>;
     private ensureEntryActivation;
     private initializeEntrySpot;
     private primaryEntryActivation;
     dispatchEntryActorPacket(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     dispatchEntryActorJoin(meshName: string, actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[]): Promise<void>;
+    admitEntryActorPacketPrefix(meshName: string, actorId: string, records: readonly import('../actors/actor-handoff').ZLinkActorHandoffPrefixRecord[]): import('../actors/actor-handoff').ZLinkActorHandoffPrefixAdmission;
     executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T>;
     publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private executePublish;
@@ -126,3 +137,9 @@ export declare class ZLinkSpotNodeRuntimeManager {
     private publishWithFlags;
 }
 export declare function createFrameworkEntrySpotId(prefix: string): string;
+/**
+ * The one decision for creating a new Actor on this node (Actor model §6.3): the node registered
+ * an Entry Spot type that accepts the Actor type and an Actor factory for it. Publication and the
+ * target refusal both read it.
+ */
+export declare function registrationAcceptsNewActor(registration: ZLinkSpotNodeOptions, stableType: string): boolean;

package/dist/runtime/spots/spot-node-runtime-manager.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotNodeRuntimeManager = void 0;
 exports.createFrameworkEntrySpotId = createFrameworkEntrySpotId;
+exports.registrationAcceptsNewActor = registrationAcceptsNewActor;
 const disposal_1 = require("../disposal");
 const node_crypto_1 = require("node:crypto");
 const contracts_1 = require("../../contracts");
@@ -68,6 +69,9 @@ class ZLinkSpotNodeRuntimeManager {
     configureLocationAutoConnect(runtime, stores, options, events) {
         this.locationAutoConnect = (0, spot_node_autoconnect_1.createSpotNodeLocationAutoConnectContext)(runtime, stores, options, events);
     }
+    async requestPeerReconcile(meshName, peerRid) {
+        await Promise.all(this.autoConnectLoops.map((loop) => loop.requestPeerReconcile(meshName, peerRid)));
+    }
     async startLocationAutoConnect(signal) {
         const location = this.locationAutoConnect;
         if (location === undefined || this.autoConnectLoops.length > 0) {
@@ -82,6 +86,7 @@ class ZLinkSpotNodeRuntimeManager {
                 const capability = (0, spot_node_autoconnect_1.spotNodeAutoConnectCapability)(spotNodeName, spotNode, node);
                 if (capability === undefined)
                     continue;
+                node.setRequestSourceAcceptance?.((nodeRid, nodeGeneration, nodeRidStorageHex, sourceSignal) => location.requestSources.accept(capability.local.meshName, nodeRid, nodeGeneration, nodeRidStorageHex, sourceSignal));
                 const reconciler = new locations_1.ZLinkAutoConnectReconciler({
                     local: capability.local,
                     localRow: capability.localRow,
@@ -152,6 +157,22 @@ class ZLinkSpotNodeRuntimeManager {
             if (this.options.dispatchErrors !== undefined) {
                 node.setDispatchErrorReporter?.(this.options.dispatchErrors, spotNodeName);
             }
+            // Session-Actor binding §4: the Session owner identity comes from the
+            // host's own descriptor or from a peer descriptor that passed the
+            // Location runtime §4.1 owner lease check.
+            node.setSessionOwnerDescriptors?.({
+                local: () => this.locationAutoConnect?.runtime.currentOwnerToken,
+                peer: async (peerRid, peerGeneration) => {
+                    const location = this.locationAutoConnect;
+                    if (location === undefined)
+                        return undefined;
+                    const descriptor = (await location.runtime.listLiveMeshNodes(spotNodeName)).find((candidate) => (0, routing_id_1.routingIdsEqual)(candidate.rid, peerRid) &&
+                        candidate.lifecycleGeneration === peerGeneration);
+                    return descriptor === undefined
+                        ? undefined
+                        : { ownerId: descriptor.ownerId, leaseGeneration: descriptor.leaseGeneration };
+                }
+            });
             node.setMailboxRecordDroppedHandler?.((record) => this.options.dispatchErrors?.report({
                 surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel,
                 messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
@@ -257,7 +278,7 @@ class ZLinkSpotNodeRuntimeManager {
                 this.meshNodes.delete(spotNodeName);
                 completions.dispose(error);
                 await pump?.dispose();
-                node.close();
+                await node.close();
                 throw error;
             }
         }
@@ -283,9 +304,8 @@ class ZLinkSpotNodeRuntimeManager {
             return;
         const ownerChanged = this.publishedOwnerToken !== undefined && !sameOwnerToken(this.publishedOwnerToken, owner);
         if (ownerChanged) {
-            // A new owner token can refer to an empty or replaced Store. The cached
-            // descriptor was written under the previous lease and must not force a
-            // Renew against a row that no longer exists.
+            // A descriptor confirmed under the previous lease must not supply
+            // cached population data for a new owner token.
             this.publishedMeshNodeDescriptors.clear();
         }
         for (const [meshName, registration] of this.options.registration.spotNodes) {
@@ -301,7 +321,7 @@ class ZLinkSpotNodeRuntimeManager {
             const capabilities = [
                 ...userSpots.map(([stableType, factory]) => objectCapability('user_spot', stableType, factory)),
                 ...instanceSpots.map(([stableType, factory]) => objectCapability('instance_spot', stableType, factory)),
-                ...actors.map(([stableType, factory]) => objectCapability('actor', stableType, factory))
+                ...actors.map(([stableType, factory]) => objectCapability('actor', stableType, factory, registrationAcceptsNewActor(registration, stableType)))
             ].sort((left, right) => {
                 const kindOrder = left.objectKind.localeCompare(right.objectKind);
                 return kindOrder !== 0 ? kindOrder : left.stableType.localeCompare(right.stableType);
@@ -316,9 +336,8 @@ class ZLinkSpotNodeRuntimeManager {
                 // The raw MeshNode resolves port zero and applies AdvertiseHost once.
                 // Discovery and RouteMesh hello must publish that same public identity.
                 endpoint: status.localEndpoint,
-                objectRole: effectiveObjectRole(registration),
+                ...this.localDescriptorFields(meshName, registration, state),
                 entrySpotId: this.entrySpotId(meshName, registration),
-                placementWeight: this.placementWeight(meshName),
                 populationCapacity: {
                     actors: {
                         active: current?.populationCapacity.actors.active ?? 0,
@@ -348,13 +367,6 @@ class ZLinkSpotNodeRuntimeManager {
                     active: 0,
                     limit: registration.activationConcurrencyLimit ?? InternalDefaults_1.DEFAULT_ACTIVATION_CONCURRENCY_LIMIT
                 },
-                channelWeights: Object.fromEntries(this.serverChannels(meshName).map(([channelName, channel]) => [
-                    channelName,
-                    state === contracts_1.ZLinkFrameworkRuntimeState.Draining
-                        ? 0
-                        : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT)
-                ])),
-                applicationVersion: this.options.registration.applicationVersion,
                 maintenanceWave: this.options.registration.maintenanceWave,
                 spotTypes: [
                     ...userSpots.map(([stableType]) => stableType),
@@ -365,11 +377,12 @@ class ZLinkSpotNodeRuntimeManager {
                 state,
                 securityIdentity: 'default'
             };
-            const result = await location.runtime.writeMeshNode(descriptor, ownerChanged
-                ? Locations_1.ZLinkLocationWriteIntent.Renew
-                : current === undefined
-                    ? Locations_1.ZLinkLocationWriteIntent.NewClaim
-                    : Locations_1.ZLinkLocationWriteIntent.Renew, signal);
+            // Revision is issued before submission: an unconfirmed Store write may
+            // already have applied, so the next publication must not reuse it.
+            this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
+            const result = await location.runtime.writeMeshNode(descriptor, previousRevision === 0n
+                ? Locations_1.ZLinkLocationWriteIntent.NewClaim
+                : Locations_1.ZLinkLocationWriteIntent.Renew, signal);
             if (result.status !== Locations_1.ZLinkLocationWriteStatus.Stored) {
                 throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' descriptor publication failed: ${result.status}.`);
             }
@@ -379,10 +392,22 @@ class ZLinkSpotNodeRuntimeManager {
                 leaseGeneration: location.runtime.currentOwnerToken.leaseGeneration,
                 updatedAt: result.updatedAt
             });
-            this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
         }
         this.publishedOwnerToken = owner;
     }
+    localDescriptorFields(meshName, registration, state) {
+        return {
+            objectRole: effectiveObjectRole(registration),
+            placementWeight: this.placementWeight(meshName),
+            channelWeights: Object.fromEntries(this.serverChannels(meshName).map(([channelName, channel]) => [
+                channelName,
+                state === contracts_1.ZLinkFrameworkRuntimeState.Draining
+                    ? 0
+                    : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT)
+            ])),
+            applicationVersion: this.options.registration.applicationVersion
+        };
+    }
     async reconcileAndPublishMeshNodeState(state, meshName, signal) {
         const location = this.locationAutoConnect;
         const node = this.meshNodes.get(meshName);
@@ -392,12 +417,15 @@ class ZLinkSpotNodeRuntimeManager {
         const owner = location.runtime.currentOwnerToken;
         if (owner === undefined)
             return;
-        const current = (await location.runtime.listLiveMeshNodes(meshName, signal)).find((descriptor) => String(descriptor.rid) === String(status.routingId) &&
+        const current = (await location.runtime.listLiveMeshNodes(meshName, signal)).find((descriptor) => (0, routing_id_1.routingIdsEqual)(descriptor.rid, status.routingId) &&
             descriptor.lifecycleGeneration === status.lifecycleGeneration &&
             descriptor.ownerId === owner.ownerId &&
             descriptor.leaseGeneration === owner.leaseGeneration);
         if (current !== undefined) {
-            this.publishedMeshNodeDescriptors.set(meshName, current);
+            this.publishedMeshNodeDescriptors.set(meshName, {
+                ...current,
+                ...this.localDescriptorFields(meshName, this.options.registration.spotNodes.get(meshName), state)
+            });
             this.descriptorRevisionByMesh.set(meshName, maxBigInt(this.descriptorRevisionByMesh.get(meshName) ?? 0n, current.descriptorRevision));
             this.publishedOwnerToken = owner;
         }
@@ -583,11 +611,13 @@ class ZLinkSpotNodeRuntimeManager {
         };
         await settle(publishers.map(async (publisher) => publisher.close()));
         await settle(autoConnectLoops.map((loop) => loop.prepareTransportShutdown()));
-        await settle(entryActivations.reverse().map((activation) => activation.dispose(deadline)));
-        await settle(meshPumps.reverse().map((pump) => pump.dispose()));
+        await settle(entryActivations
+            .reverse()
+            .map((activation) => (0, abort_1.awaitWithAbort)(activation.dispose(deadline), signal)));
+        await settle(meshPumps.reverse().map((pump) => pump.dispose(signal)));
         await settle(meshNodes.reverse().map(async (node) => {
-            node.shutdown(DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS);
-            node.close();
+            await node.shutdown(DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS);
+            await node.close();
         }));
         for (const completions of meshCompletions) {
             completions.dispose();
@@ -604,26 +634,37 @@ class ZLinkSpotNodeRuntimeManager {
         this.meshNodes.clear();
         this.meshCompletions.clear();
     }
-    async dispatchMeshRecord(meshName, owner, record) {
+    /**
+     * Node and Channel records go straight to the framework dispatcher in the
+     * pump's turn. Only Spot and Actor records addressed to the Entry Spot wait
+     * for its activation first.
+     */
+    dispatchMeshRecord(meshName, owner, record) {
+        if ((record.kind === service_runtime_contracts_1.ReceiveKind.ActorSend ||
+            record.kind === service_runtime_contracts_1.ReceiveKind.ActorRequest ||
+            record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend ||
+            record.kind === service_runtime_contracts_1.ReceiveKind.SpotRequest ||
+            record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast) &&
+            this.targetsEntrySpot(meshName, owner)) {
+            return this.ensureEntryActivation(meshName).then(() => this.dispatchFrameworkRecord(meshName, owner, record));
+        }
+        return this.dispatchFrameworkRecord(meshName, owner, record);
+    }
+    targetsEntrySpot(meshName, owner) {
+        if (owner.spotId === null)
+            return true;
         const node = this.meshNodes.get(meshName);
-        const targetsEntrySpot = owner.spotId === null ||
-            (node !== undefined &&
-                (0, routing_id_1.routingIdsEqual)(owner.spotId, String(node.status().routingId)));
-        if (targetsEntrySpot &&
-            (record.kind === service_runtime_contracts_1.ReceiveKind.ActorSend ||
-                record.kind === service_runtime_contracts_1.ReceiveKind.ActorRequest ||
-                record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend ||
-                record.kind === service_runtime_contracts_1.ReceiveKind.SpotRequest ||
-                record.kind === service_runtime_contracts_1.ReceiveKind.SpotMulticast)) {
-            await this.ensureEntryActivation(meshName);
-        }
+        return (node !== undefined &&
+            (0, routing_id_1.routingIdsEqual)(owner.spotId, String(node.status().routingId)));
+    }
+    dispatchFrameworkRecord(meshName, owner, record) {
         const dispatcher = this.options.meshRecordDispatcher;
         if (dispatcher === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' received a record before its framework dispatcher was registered.`);
+            return Promise.reject(new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' received a record before its framework dispatcher was registered.`));
         }
-        await dispatcher(meshName, owner, record);
+        return dispatcher(meshName, owner, record);
     }
-    async dispatchEntrySpotRecord(meshName, owner, record) {
+    async dispatchEntrySpotRecord(meshName, owner, record, admit) {
         if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotSend &&
             record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest &&
             record.kind !== service_runtime_contracts_1.ReceiveKind.SpotMulticast) {
@@ -638,7 +679,8 @@ class ZLinkSpotNodeRuntimeManager {
             if (record.topic === null || record.topic.length === 0) {
                 throw new configuration_1.ZLinkConfigurationException('MeshNode Entry Spot multicast record is missing its topic.');
             }
-            await activation.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            const dispatch = () => activation.dispatchSubscriptionRecord(record.topic, record.parts, record.sourceNodeRid);
+            await (admit === undefined ? dispatch() : admit(dispatch));
             return true;
         }
         const envelope = (0, channel_envelope_1.decodeChannelEnvelope)(record.parts, undefined, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
@@ -648,15 +690,20 @@ class ZLinkSpotNodeRuntimeManager {
             channelName: envelope.header.channelName,
             contentType: envelope.header.contentType
         };
-        if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
-            await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, false);
-            return true;
-        }
         try {
-            const response = await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, true);
-            requireEntrySpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+            const dispatch = async () => {
+                if (record.kind === service_runtime_contracts_1.ReceiveKind.SpotSend) {
+                    await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, false);
+                    return;
+                }
+                const response = await activation.dispatchPacketEncoded(envelope.packetName, decodePayload, context, true);
+                requireEntrySpotReply(record.reply((0, channel_envelope_1.encodeChannelReplyParts)(envelope.header, response, codecs)));
+            };
+            await (admit === undefined ? dispatch() : admit(dispatch));
         }
         catch (error) {
+            if (record.kind !== service_runtime_contracts_1.ReceiveKind.SpotRequest)
+                throw error;
             requireEntrySpotReply(record.reply((0, channel_envelope_1.encodeChannelErrorReplyParts)(envelope.header, error)));
         }
         return true;
@@ -784,6 +831,13 @@ class ZLinkSpotNodeRuntimeManager {
         }
         await activation.commitServiceActorJoin(actor, handoffBacklog);
     }
+    admitEntryActorPacketPrefix(meshName, actorId, records) {
+        const activation = this.entryActivations.get(meshName);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Entry Spot Actor '${actorId}' has no activation for MeshNode '${meshName}'.`);
+        }
+        return activation.admitActorPacketPrefix(actorId, records);
+    }
     executeEntryActor(meshName, actorId, operation) {
         const activation = this.entryActivations.get(meshName);
         if (activation === undefined) {
@@ -910,16 +964,27 @@ function effectiveObjectRole(registration) {
         ? contracts_1.ZLinkObjectRole.Server
         : contracts_1.ZLinkObjectRole.None;
 }
-function objectCapability(objectKind, stableType, factory) {
+function objectCapability(objectKind, stableType, factory, entryAccepted = false) {
     const policy = factory.relocation?.kind ?? 'disabled';
     return {
         objectKind,
         stableType,
         policy,
         hasSnapshotAdapter: policy === 'snapshot',
-        limit: objectKind === 'actor' ? 0 : (factory.options?.stableTypeLimit ?? 0)
+        limit: objectKind === 'actor' ? 0 : (factory.options?.stableTypeLimit ?? 0),
+        entryAccepted
     };
 }
+/**
+ * The one decision for creating a new Actor on this node (Actor model §6.3): the node registered
+ * an Entry Spot type that accepts the Actor type and an Actor factory for it. Publication and the
+ * target refusal both read it.
+ */
+function registrationAcceptsNewActor(registration, stableType) {
+    return (registration.entrySpotType !== undefined &&
+        registration.entrySpotActorType === stableType &&
+        effectiveActorRegistrations(registration).some(([type]) => type === stableType));
+}
 function aggregatePlacementCapacity(actorLimit, spotLimit) {
     const unlimited = RegistrationBuilderPolicy_1.ZLINK_MAX_CAPACITY;
     const actors = actorLimit === 0 ? unlimited : actorLimit;

package/dist/runtime/spots/spot-outbound.d.ts

@@ -35,6 +35,7 @@ export declare class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
     private requireAddressTransport;
 }
 export interface ZLinkSpotAddressCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly instanceSpot: boolean;
     readonly instanceSpotType?: string;
@@ -63,10 +64,12 @@ export interface ZLinkSpotRoutedSendOptions {
     readonly metadata?: ReadonlyMap<string, string>;
 }
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+    readonly onAdmitted?: () => void;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
 export interface ZLinkSpotHandleCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;

package/dist/runtime/spots/spot-outbound.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkSpotOutbound = void 0;
 exports.sendToSpotHandle = sendToSpotHandle;
 exports.requestToSpotHandle = requestToSpotHandle;
+const request_result_1 = require("../messaging/request-result");
 const contracts_1 = require("../../contracts");
 const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const configuration_1 = require("../configuration");
@@ -115,14 +116,13 @@ function createAddressedSpotSendCall(serial, transport, spotId, message, sourceS
 }
 function createAddressedSpotRequestCall(serial, transport, spotId, request, sourceSpotProvider) {
     const options = newAddressCallOptions();
-    const begin = (waitPolicy, signal) => {
-        markSubmitted(options);
-        rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
+    const begin = (signal, onAdmitted) => {
         return startRequestOnSerial(serial, () => ({
             pending: transport.requestToSpotAddress(spotId, request, {
                 ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
                 timeoutMs: options.timeoutMs,
-                signal
+                signal,
+                onAdmitted
             })
         }));
     };
@@ -153,13 +153,16 @@ function createAddressedSpotRequestCall(serial, transport, spotId, request, sour
             return this;
         },
         submit(signal) {
-            const pending = begin('async', signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            markSubmitted(options);
+            rejectSameSpotAsyncRequest(serial, spotId, 'async');
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
-            const pending = begin('yield', signal);
-            return turn.yieldPromise(pending);
+            markSubmitted(options);
+            rejectSameSpotAsyncRequest(serial, spotId, 'yield');
+            const pending = begin(signal);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }
@@ -250,7 +253,12 @@ function wrapPublishCall(serial, inner) {
     };
 }
 function wrapRequestCall(serial, inner) {
-    const begin = (signal) => startRequestOnSerial(serial, () => ({ pending: inner.submit(signal) }));
+    const begin = (signal, onAdmitted) => startRequestOnSerial(serial, () => {
+        const pending = inner.submit(signal);
+        if (onAdmitted !== undefined)
+            void pending.admitted.then(onAdmitted, () => undefined);
+        return { pending };
+    });
     return {
         metadata(key, value) {
             if (typeof key === 'string')
@@ -264,13 +272,12 @@ function wrapRequestCall(serial, inner) {
             return this;
         },
         submit(signal) {
-            const pending = begin(signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
             const pending = begin(signal);
-            return turn.yieldPromise(pending);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }
@@ -320,15 +327,15 @@ function wrapRoutedSpotSendCall(serial, transport, spot, message, spotRouterChan
 function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterChannelIdForMesh, sourceSpotProvider) {
     let selectedTimeoutMs;
     const metadata = new Map();
-    const begin = (waitPolicy, signal) => {
+    const begin = (signal, onAdmitted) => {
         // A request to the current Spot would wait behind the handler that owns
         // the same Spot claim. Reject it before resolving a route or submitting
         // transport work; one-way self-send remains a valid FIFO admission.
-        rejectSameSpotAsyncRequest(serial, spot.spotId, waitPolicy);
         return startRequestOnSerial(serial, () => ({
             pending: requestToSpotHandle(transport, spot, request, {
                 timeoutMs: selectedTimeoutMs,
                 signal,
+                onAdmitted,
                 metadata,
                 spotRouterChannelIdForMesh,
                 sourceSpot: sourceSpotProvider?.()
@@ -352,13 +359,14 @@ function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterC
             return this;
         },
         submit(signal) {
-            const pending = begin('async', signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            rejectSameSpotAsyncRequest(serial, spot.spotId, 'async');
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
-            const pending = begin('yield', signal);
-            return turn.yieldPromise(pending);
+            rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
+            const pending = begin(signal);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }
@@ -395,6 +403,7 @@ async function requestToSpotHandle(transport, spot, request, options = {}) {
             packetName,
             timeoutMs: options.timeoutMs,
             signal: options.signal,
+            onAdmitted: options.onAdmitted,
             metadata: options.metadata
         };
         if (options.sourceSpot !== undefined && transport.requestFromSpotToSpot !== undefined) {

package/dist/runtime/spots/spot-remote-codec.js

@@ -85,7 +85,11 @@ function decodeHandoffBacklog(value) {
                     BigInt(source.ownerLeaseGeneration) <= 0n ||
                     source.nodeRid.length === 0 ||
                     BigInt(source.nodeGeneration) <= 0n ||
-                    source.replyRouteId !== messageFollowContext.replyRouteId)) ||
+                    source.replyRouteId !==
+                        (packet.messageFollowOrigin !== undefined &&
+                            (0, routing_id_1.routingIdsEqual)((0, routing_id_1.decodeRoutingId)(source.nodeRid, source.nodeRidHex), packet.messageFollowOrigin.sourceNodeRid)
+                            ? packet.messageFollowOrigin.originalReplyRouteId.toString()
+                            : messageFollowContext.replyRouteId))) ||
             (!packet.returnResponse && source !== undefined)) {
             throw new Error('Remote actor handoff request source fence is invalid.');
         }

package/dist/runtime/spots/spot-routed-spot-packet-dispatch.d.ts

@@ -23,6 +23,7 @@ interface ZLinkRoutedSpotPacketDispatchOptions {
 }
 interface ZLinkRoutedSpotPacketContext {
     readonly channelName: string;
+    readonly onAdmitted?: () => void;
     readonly contentType?: string;
     readonly workOptions?: ZLinkSerialWorkOptions;
     readonly admissionTimeoutMs?: number;

package/dist/runtime/spots/spot-routed-spot-packet-dispatch.js

@@ -151,7 +151,7 @@ class ZLinkRoutedSpotPacketDispatch {
                 if (activation.serial.isCurrentTurn) {
                     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Spot '${spotId}' cannot await a request to its current serial turn.`);
                 }
-                await activation.serial.execute(runHandler, context.workOptions, instanceIntent ? runHandler : undefined);
+                await activation.serial.execute(runHandler, { ...context.workOptions, onAdmitted: context.onAdmitted }, instanceIntent ? runHandler : undefined);
             }
         }
         catch (error) {

package/dist/runtime/spots/spot-runtime-ports.d.ts

@@ -8,6 +8,7 @@ import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
 import type { ZLinkRemoteActorJoinActor, ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
 import type { ZLinkBackendSpotNode } from '../backend/contracts';
 export interface ZLinkEntryActorRuntime {
+    releaseMembers?(meshName: string): Promise<void>;
     resolveActor(actorId: string): ZLinkActor | undefined;
     commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
     destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
@@ -32,7 +33,6 @@ export interface ZLinkSpotActorTransferRuntime {
     commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
     clearRoutedActor(actor: ZLinkActor): void;
     rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
-    notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
     actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
 }
 export interface ZLinkSpotBoundSessionRuntime {

package/dist/runtime/spots/spot-serial-executor.d.ts

@@ -1,7 +1,10 @@
 import { ZLinkUserSpotExecutionMode } from '../../contracts';
+import type { ZLinkActorHandoffDispatch, ZLinkActorHandoffPrefixAdmission, ZLinkActorHandoffPrefixRecord } from '../actors/actor-handoff';
 import type { ZLinkExecutionBarrier } from '../execution';
 import type { ZLinkSerialSchedulerOptions, ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+export type ZLinkSpotPreparationCompletion = 'publication' | 'first-terminal';
+export type ZLinkActorPacketTurnDispatch = (serial: ZLinkSpotSerialTurnExecutor, ...args: Parameters<ZLinkActorHandoffDispatch>) => ReturnType<ZLinkActorHandoffDispatch>;
 /**
  * Owns every application serial unit that belongs to one Spot activation.
  *
@@ -19,11 +22,18 @@ export declare class ZLinkSpotSerialExecutor {
     private executionBarrier;
     private closing;
     private closePromise;
+    private preparation?;
     constructor(spotSerial: ZLinkSpotSerialTurnExecutor, executionMode: ZLinkUserSpotExecutionMode, sourceSpotId: unknown, actorOptions?: ZLinkSerialSchedulerOptions | undefined);
     setExecutionBarrier(barrier: ZLinkExecutionBarrier): void;
+    get isPreparing(): boolean;
+    beginPreparation(kind?: 'activation' | 'relocation'): void;
+    openPreparationAdmission(): void;
+    finishPreparation(terminal?: () => Promise<void>): Promise<void>;
     executeSpot<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
     executeActor<T>(actorId: string, operation: (serial: ZLinkSpotSerialTurnExecutor) => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
     executeTimer<T>(timerName: string, operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    /** Admits held packets through the same Actor FIFO as ordinary ingress. */
+    admitActorPacketPrefix(actorId: string, records: readonly ZLinkActorHandoffPrefixRecord[], dispatch: ZLinkActorPacketTurnDispatch): ZLinkActorHandoffPrefixAdmission;
     isTimerExecuting(timerName: string): boolean;
     executeLifecycle<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
     terminateActor(actorId: string, terminal: () => Promise<void>): Promise<void>;