@zlink-systems/framework 0.30.1 → 0.30.2

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.js

@@ -162,7 +162,7 @@ function createAddressedSpotRequestCall(serial, transport, spotId, request, sour
             markSubmitted(options);
             rejectSameSpotAsyncRequest(serial, spotId, 'yield');
             const pending = begin(signal);
-            return turn.yieldPromise(pending);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }
@@ -277,7 +277,7 @@ function wrapRequestCall(serial, inner) {
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
             const pending = begin(signal);
-            return turn.yieldPromise(pending);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }
@@ -366,7 +366,7 @@ function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterC
             const turn = (0, execution_1.requireZLinkYieldTurn)();
             rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
             const pending = begin(signal);
-            return turn.yieldPromise(pending);
+            return turn.yieldFrameworkPromise(pending);
         }
     };
 }

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-runtime-ports.d.ts

@@ -33,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>;

package/dist/runtime/spots/spot-serial-executor.js

@@ -21,6 +21,7 @@ class ZLinkSpotSerialExecutor {
     executionBarrier;
     closing = false;
     closePromise;
+    preparation;
     constructor(spotSerial, executionMode, sourceSpotId, actorOptions) {
         this.spotSerial = spotSerial;
         this.executionMode = executionMode;
@@ -38,6 +39,49 @@ class ZLinkSpotSerialExecutor {
         for (const serial of this.timerSerials.values())
             serial.setExecutionBarrier(barrier);
     }
+    get isPreparing() {
+        return this.preparation !== undefined;
+    }
+    beginPreparation(kind = 'activation') {
+        if (this.preparation !== undefined || this.executionBarrier === undefined)
+            throw new Error('Activation preparation requires one unowned execution barrier.');
+        const barrier = this.executionBarrier;
+        const seal = barrier.seal(kind);
+        let complete;
+        const terminal = new Promise((resolve) => {
+            complete = resolve;
+        });
+        // The staging seal itself owns target preparation. No normal preparation
+        // item is admitted in addition to this lifecycle owner.
+        const execution = this.spotSerial.executeControlLifecycleOperation(async () => {
+            const finish = await terminal;
+            await finish?.();
+        }, {
+            canExecuteApplication: (record) => record.context === undefined || !barrier.isCurrent(seal)
+        });
+        this.preparation = { seal, complete, execution };
+    }
+    openPreparationAdmission() {
+        if (this.preparation !== undefined)
+            this.executionBarrier.abort(this.preparation.seal);
+    }
+    async finishPreparation(terminal) {
+        const preparation = this.preparation;
+        if (preparation === undefined) {
+            await terminal?.();
+            return;
+        }
+        preparation.complete(terminal);
+        try {
+            await preparation.execution;
+        }
+        finally {
+            if (this.preparation === preparation) {
+                this.executionBarrier.abort(preparation.seal);
+                this.preparation = undefined;
+            }
+        }
+    }
     executeSpot(operation, workOptions) {
         return this.spotSerial.execute(operation, workOptions);
     }
@@ -45,17 +89,26 @@ class ZLinkSpotSerialExecutor {
         const serial = this.actorSerial(actorId);
         return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
     }
-    /** @internal Restores a durable Actor FIFO prefix without starting it. */
-    admitActorDurablePrefix(actorId, records) {
+    executeTimer(timerName, operation, workOptions) {
+        return this.timerSerial(timerName).post(operation, workOptions);
+    }
+    /** Admits held packets through the same Actor FIFO as ordinary ingress. */
+    admitActorPacketPrefix(actorId, records, dispatch) {
         const serial = this.actorSerial(actorId);
-        return this.actorExecutor(actorId).admitDurablePrefix(records.map((record) => ({
-            operation: (executeChild) => record.operation((child) => executeChild(() => child(serial))),
+        const terminals = this.actorExecutor(actorId).admitDurablePrefix(records.map((record) => ({
+            operation: (executeChild) => record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => executeChild(() => dispatch(serial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef))),
             preparation: record.preparation,
-            workOptions: record.workOptions
+            workOptions: { payloadBytes: record.payloadBytes, onWithdrawable: record.onWithdrawable }
         })));
-    }
-    executeTimer(timerName, operation, workOptions) {
-        return this.timerSerial(timerName).execute(operation, workOptions);
+        const terminal = Promise.allSettled(terminals).then((outcomes) => {
+            const errors = outcomes.flatMap((outcome) => outcome.status === 'rejected' ? [outcome.reason] : []);
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1) {
+                throw new AggregateError(errors, `Actor '${actorId}' durable prefix replay failed.`);
+            }
+        });
+        return { terminal };
     }
     isTimerExecuting(timerName) {
         if (this.executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide) {

package/dist/runtime/spots/spot-serial-turn-executor.js

@@ -94,7 +94,7 @@ class ZLinkSpotSerialTurnExecutor {
      * this so they never run inline inside another callback's turn.
      */
     post(operation, workOptions) {
-        return this.enqueueApplicationTurn(operation, workOptions);
+        return this.enqueueApplicationTurn(operation, workOptions, undefined, true);
     }
     /**
      * Queues a one-way turn in serial order. Handler completion is reported
@@ -181,11 +181,22 @@ class ZLinkSpotSerialTurnExecutor {
     visitPendingApplication(visitor) {
         this.scheduler.visitPendingApplication(visitor);
     }
-    async enqueueApplicationTurn(operation, workOptions = {}, replay) {
+    async enqueueApplicationTurn(operation, workOptions = {}, replay, retainWhilePreparing = false) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
             const entry = this.executionBarrier?.enter();
+            if (entry instanceof Promise &&
+                retainWhilePreparing &&
+                this.scheduler.retainsApplicationForLifecycle) {
+                try {
+                    return await this.submitQueuedTurn(operation, workOptions, entry);
+                }
+                catch (error) {
+                    (await entry).release();
+                    throw error;
+                }
+            }
             barrierClaim = entry instanceof Promise ? await entry : entry;
             const refusal = this.applicationAdmissionRefusal(replay !== undefined);
             if (refusal !== undefined)
@@ -224,6 +235,12 @@ class ZLinkSpotSerialTurnExecutor {
             : this.scheduler.submit(boundOperation, options, barrierClaim);
     }
     runQueuedRecord(record) {
+        if (record.context instanceof Promise) {
+            return record.context.then((claim) => {
+                Object.assign(record, { context: claim });
+                return this.runQueuedRecord(record);
+            });
+        }
         const context = record.context;
         if (context?.replay !== undefined && record.operation === context.replay) {
             context.release();

package/dist/runtime/spots/spot-subscription-dispatch.js

@@ -130,7 +130,7 @@ class ZLinkSpotSubscriptionDispatch {
         const subSource = message.routingId === null ? undefined : String(message.routingId);
         const inboundFlow = (0, flow_context_1.createInboundFlow)(envelope.header.flowId, envelope.header.flowOrigin, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, undefined);
         try {
-            await this.options.serial.execute(() => (0, flow_context_1.runWithFlow)(inboundFlow, async () => {
+            await this.options.serial.post(() => (0, flow_context_1.runWithFlow)(inboundFlow, async () => {
                 // Payload deserialization belongs to the Spot serial turn. Queue
                 // admission and execution authority therefore precede this work.
                 const event = (0, channel_envelope_1.decodeChannelPayload)(envelope, this.channelCodecs());