@zlink-systems/framework 0.30.1 → 0.30.2

package/src/runtime/spots/spot-node-runtime-manager.ts

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { RuntimeDisposal } from '../disposal';
 import { randomUUID } from 'node:crypto';
@@ -34,7 +35,7 @@ import {
 import { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from '../../contracts/Locations';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkLocationOwnerToken } from '../../contracts/Locations/Writes';
-import { createAbortError } from '../abort';
+import { awaitWithAbort, createAbortError } from '../abort';
 import type { ZLinkActivationConcurrency } from '../activation-admission';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
@@ -205,6 +206,12 @@ export class ZLinkSpotNodeRuntimeManager {
     );
   }
 
+  async requestPeerReconcile(meshName: string, peerRid: string): Promise<void> {
+    await Promise.all(
+      this.autoConnectLoops.map((loop) => loop.requestPeerReconcile(meshName, peerRid))
+    );
+  }
+
   async startLocationAutoConnect(signal?: AbortSignal): Promise<void> {
     const location = this.locationAutoConnect;
     if (location === undefined || this.autoConnectLoops.length > 0) {
@@ -218,6 +225,16 @@ export class ZLinkSpotNodeRuntimeManager {
         }
         const capability = 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 ZLinkAutoConnectReconciler({
           local: capability.local,
           localRow: capability.localRow,
@@ -292,6 +309,24 @@ export 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) =>
+              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: ZLinkDispatchErrorSurface.RouteMeshChannel,
@@ -412,7 +447,7 @@ export class ZLinkSpotNodeRuntimeManager {
         this.meshNodes.delete(spotNodeName);
         completions.dispose(error);
         await pump?.dispose();
-        node.close();
+        await node.close();
         throw error;
       }
     }
@@ -447,9 +482,8 @@ export class ZLinkSpotNodeRuntimeManager {
     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) {
@@ -467,7 +501,14 @@ export class ZLinkSpotNodeRuntimeManager {
         ...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);
@@ -482,9 +523,8 @@ export 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,
@@ -517,19 +557,6 @@ export class ZLinkSpotNodeRuntimeManager {
           active: 0,
           limit: registration.activationConcurrencyLimit ?? DEFAULT_ACTIVATION_CONCURRENCY_LIMIT
         },
-        channelWeights: Object.fromEntries(
-          this.serverChannels(meshName).map(([channelName, channel]) => [
-            channelName,
-            state === ZLinkFrameworkRuntimeState.Draining
-              ? 0
-              : this.effectiveChannelWeight(
-                  meshName,
-                  channelName,
-                  channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
-                )
-          ])
-        ),
-        applicationVersion: this.options.registration.applicationVersion,
         maintenanceWave: this.options.registration.maintenanceWave,
         spotTypes: [
           ...userSpots.map(([stableType]) => stableType),
@@ -540,13 +567,14 @@ export class ZLinkSpotNodeRuntimeManager {
         state,
         securityIdentity: 'default'
       };
+      // 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,
-        ownerChanged
-          ? ZLinkLocationWriteIntent.Renew
-          : current === undefined
-            ? ZLinkLocationWriteIntent.NewClaim
-            : ZLinkLocationWriteIntent.Renew,
+        previousRevision === 0n
+          ? ZLinkLocationWriteIntent.NewClaim
+          : ZLinkLocationWriteIntent.Renew,
         signal
       );
       if (result.status !== ZLinkLocationWriteStatus.Stored) {
@@ -560,11 +588,37 @@ export class ZLinkSpotNodeRuntimeManager {
         leaseGeneration: location.runtime.currentOwnerToken!.leaseGeneration,
         updatedAt: result.updatedAt
       });
-      this.descriptorRevisionByMesh.set(meshName, descriptor.descriptorRevision);
     }
     this.publishedOwnerToken = owner;
   }
 
+  private localDescriptorFields(
+    meshName: string,
+    registration: ZLinkSpotNodeOptions,
+    state: ZLinkFrameworkRuntimeState
+  ): Pick<
+    ZLinkMeshNodeDescriptor,
+    'objectRole' | 'placementWeight' | 'channelWeights' | 'applicationVersion'
+  > {
+    return {
+      objectRole: effectiveObjectRole(registration),
+      placementWeight: this.placementWeight(meshName),
+      channelWeights: Object.fromEntries(
+        this.serverChannels(meshName).map(([channelName, channel]) => [
+          channelName,
+          state === ZLinkFrameworkRuntimeState.Draining
+            ? 0
+            : this.effectiveChannelWeight(
+                meshName,
+                channelName,
+                channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
+              )
+        ])
+      ),
+      applicationVersion: this.options.registration.applicationVersion
+    };
+  }
+
   async reconcileAndPublishMeshNodeState(
     state: ZLinkFrameworkRuntimeState,
     meshName: string,
@@ -578,13 +632,20 @@ export class ZLinkSpotNodeRuntimeManager {
     if (owner === undefined) return;
     const current = (await location.runtime.listLiveMeshNodes(meshName, signal)).find(
       (descriptor) =>
-        String(descriptor.rid) === String(status.routingId) &&
+        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)
@@ -848,12 +909,16 @@ export 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) => 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) {
@@ -870,39 +935,61 @@ export class ZLinkSpotNodeRuntimeManager {
     this.meshCompletions.clear();
   }
 
-  private async dispatchMeshRecord(
+  /**
+   * 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(
     meshName: string,
     owner: ReadyRecord,
     record: ReceiveRecord
-  ): Promise<void> {
-    const node = this.meshNodes.get(meshName);
-    const targetsEntrySpot =
-      owner.spotId === null ||
-      (node !== undefined &&
-        routingIdsEqual(owner.spotId as unknown as RoutingId, String(node.status().routingId)));
+  ): void | Promise<void> {
     if (
-      targetsEntrySpot &&
       (record.kind === ReceiveKind.ActorSend ||
         record.kind === ReceiveKind.ActorRequest ||
         record.kind === ReceiveKind.SpotSend ||
         record.kind === ReceiveKind.SpotRequest ||
-        record.kind === ReceiveKind.SpotMulticast)
+        record.kind === ReceiveKind.SpotMulticast) &&
+      this.targetsEntrySpot(meshName, owner)
     ) {
-      await this.ensureEntryActivation(meshName);
+      return this.ensureEntryActivation(meshName).then(() =>
+        this.dispatchFrameworkRecord(meshName, owner, record)
+      );
     }
+    return this.dispatchFrameworkRecord(meshName, owner, record);
+  }
+
+  private targetsEntrySpot(meshName: string, owner: ReadyRecord): boolean {
+    if (owner.spotId === null) return true;
+    const node = this.meshNodes.get(meshName);
+    return (
+      node !== undefined &&
+      routingIdsEqual(owner.spotId as unknown as RoutingId, String(node.status().routingId))
+    );
+  }
+
+  private dispatchFrameworkRecord(
+    meshName: string,
+    owner: ReadyRecord,
+    record: ReceiveRecord
+  ): void | Promise<void> {
     const dispatcher = this.options.meshRecordDispatcher;
     if (dispatcher === undefined) {
-      throw new ZLinkConfigurationException(
-        `MeshNode '${meshName}' received a record before its framework dispatcher was registered.`
+      return Promise.reject(
+        new 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: string,
     owner: ReadyRecord,
-    record: ReceiveRecord
+    record: ReceiveRecord,
+    admit?: ZLinkMeshDispatchAdmission
   ): Promise<boolean> {
     if (
       record.kind !== ReceiveKind.SpotSend &&
@@ -922,11 +1009,13 @@ export class ZLinkSpotNodeRuntimeManager {
           'MeshNode Entry Spot multicast record is missing its topic.'
         );
       }
-      await activation.dispatchSubscriptionRecord(
-        record.topic,
-        record.parts,
-        record.sourceNodeRid as unknown as RoutingId | null
-      );
+      const dispatch = () =>
+        activation.dispatchSubscriptionRecord(
+          record.topic!,
+          record.parts,
+          record.sourceNodeRid as unknown as RoutingId | null
+        );
+      await (admit === undefined ? dispatch() : admit(dispatch));
       return true;
     }
     const envelope = decodeChannelEnvelope(
@@ -940,21 +1029,30 @@ export class ZLinkSpotNodeRuntimeManager {
       channelName: envelope.header.channelName,
       contentType: envelope.header.contentType
     };
-    if (record.kind === 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(encodeChannelReplyParts(envelope.header, response, codecs))
-      );
+      const dispatch = async () => {
+        if (record.kind === ReceiveKind.SpotSend) {
+          await activation.dispatchPacketEncoded(
+            envelope.packetName,
+            decodePayload,
+            context,
+            false
+          );
+          return;
+        }
+        const response = await activation.dispatchPacketEncoded(
+          envelope.packetName,
+          decodePayload,
+          context,
+          true
+        );
+        requireEntrySpotReply(
+          record.reply(encodeChannelReplyParts(envelope.header, response, codecs))
+        );
+      };
+      await (admit === undefined ? dispatch() : admit(dispatch));
     } catch (error) {
+      if (record.kind !== ReceiveKind.SpotRequest) throw error;
       requireEntrySpotReply(record.reply(encodeChannelErrorReplyParts(envelope.header, error)));
     }
     return true;
@@ -1110,6 +1208,20 @@ export class ZLinkSpotNodeRuntimeManager {
     await activation.commitServiceActorJoin(actor, handoffBacklog);
   }
 
+  admitEntryActorPacketPrefix(
+    meshName: string,
+    actorId: string,
+    records: readonly import('../actors/actor-handoff').ZLinkActorHandoffPrefixRecord[]
+  ): import('../actors/actor-handoff').ZLinkActorHandoffPrefixAdmission {
+    const activation = this.entryActivations.get(meshName);
+    if (activation === undefined) {
+      throw new ZLinkConfigurationException(
+        `Entry Spot Actor '${actorId}' has no activation for MeshNode '${meshName}'.`
+      );
+    }
+    return activation.admitActorPacketPrefix(actorId, records);
+  }
+
   executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T> {
     const activation = this.entryActivations.get(meshName);
     if (activation === undefined) {
@@ -1345,7 +1457,8 @@ function effectiveObjectRole(registration: ZLinkSpotNodeOptions): ZLinkObjectRol
 function objectCapability(
   objectKind: 'actor' | 'user_spot' | 'instance_spot',
   stableType: string,
-  factory: DescriptorFactoryRegistration
+  factory: DescriptorFactoryRegistration,
+  entryAccepted = false
 ) {
   const policy = factory.relocation?.kind ?? 'disabled';
   return {
@@ -1353,10 +1466,27 @@ function objectCapability(
     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.
+ */
+export function registrationAcceptsNewActor(
+  registration: ZLinkSpotNodeOptions,
+  stableType: string
+): boolean {
+  return (
+    registration.entrySpotType !== undefined &&
+    registration.entrySpotActorType === stableType &&
+    effectiveActorRegistrations(registration).some(([type]) => type === stableType)
+  );
+}
+
 function aggregatePlacementCapacity(actorLimit: number, spotLimit: number): number {
   const unlimited = ZLINK_MAX_CAPACITY;
   const actors = actorLimit === 0 ? unlimited : actorLimit;

package/src/runtime/spots/spot-outbound.ts

@@ -370,7 +370,7 @@ function createAddressedSpotRequestCall(
       markSubmitted(options);
       rejectSameSpotAsyncRequest(serial, spotId, 'yield');
       const pending = begin<TReply>(signal);
-      return turn.yieldPromise(pending);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }
@@ -508,7 +508,7 @@ function wrapRequestCall(
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
       const pending = begin<TReply>(signal);
-      return turn.yieldPromise(pending);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }
@@ -626,7 +626,7 @@ function wrapRoutedSpotRequestCall(
       const turn = requireZLinkYieldTurn();
       rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
       const pending = begin<TReply>(signal);
-      return turn.yieldPromise(pending);
+      return turn.yieldFrameworkPromise(pending);
     }
   };
 }

package/src/runtime/spots/spot-remote-codec.ts

@@ -8,7 +8,7 @@ import type { Message } from '../../contracts/Common/Message';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import { decodeChannelEnvelope } from '../channels/channel-envelope';
-import { decodeRoutingId as decodeWireRoutingId } from '../routing-id';
+import { decodeRoutingId as decodeWireRoutingId, routingIdsEqual } from '../routing-id';
 import {
   REMOTE_ACTOR_JOIN_PACKET,
   type ZLinkRemoteActorJoinWirePayload
@@ -176,7 +176,14 @@ export function decodeHandoffBacklog(value: unknown): readonly ZLinkActorHandoff
           BigInt(source.ownerLeaseGeneration) <= 0n ||
           source.nodeRid.length === 0 ||
           BigInt(source.nodeGeneration) <= 0n ||
-          source.replyRouteId !== messageFollowContext.replyRouteId)) ||
+          source.replyRouteId !==
+            (packet.messageFollowOrigin !== undefined &&
+            routingIdsEqual(
+              decodeWireRoutingId(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/src/runtime/spots/spot-runtime-ports.ts

@@ -92,7 +92,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;
 }
 

package/src/runtime/spots/spot-serial-executor.ts

@@ -1,13 +1,24 @@
 import { ZLinkUserSpotExecutionMode } from '../../contracts';
 import { ZLinkActorSerialExecutor } from '../actors';
-import type { ZLinkExecutionBarrier } from '../execution';
+import type {
+  ZLinkActorHandoffDispatch,
+  ZLinkActorHandoffPrefixAdmission,
+  ZLinkActorHandoffPrefixRecord
+} from '../actors/actor-handoff';
+import type { ZLinkExecutionBarrier, ZLinkExecutionBarrierSeal } from '../execution';
 import type {
   ZLinkSerialSchedulerOptions,
-  ZLinkSerialWorkPreparation,
   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.
  *
@@ -21,6 +32,11 @@ export class ZLinkSpotSerialExecutor {
   private executionBarrier: ZLinkExecutionBarrier | undefined;
   private closing = false;
   private closePromise: Promise<void> | undefined;
+  private preparation?: {
+    readonly seal: ZLinkExecutionBarrierSeal;
+    readonly complete: (terminal?: () => Promise<void>) => void;
+    readonly execution: Promise<void>;
+  };
 
   constructor(
     private readonly spotSerial: ZLinkSpotSerialTurnExecutor,
@@ -39,6 +55,54 @@ export class ZLinkSpotSerialExecutor {
     for (const serial of this.timerSerials.values()) serial.setExecutionBarrier(barrier);
   }
 
+  get isPreparing(): boolean {
+    return this.preparation !== undefined;
+  }
+
+  beginPreparation(kind: 'activation' | 'relocation' = 'activation'): void {
+    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!: (terminal?: () => Promise<void>) => void;
+    const terminal = new Promise<(() => Promise<void>) | undefined>((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(): void {
+    if (this.preparation !== undefined) this.executionBarrier!.abort(this.preparation.seal);
+  }
+
+  async finishPreparation(terminal?: () => Promise<void>): Promise<void> {
+    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<T>(
     operation: () => Promise<T> | T,
     workOptions?: ZLinkSerialWorkOptions
@@ -55,35 +119,43 @@ export class ZLinkSpotSerialExecutor {
     return this.actorExecutor(actorId).execute(() => operation(serial), workOptions);
   }
 
-  /** @internal Restores a durable Actor FIFO prefix without starting it. */
-  admitActorDurablePrefix(
+  executeTimer<T>(
+    timerName: string,
+    operation: () => Promise<T> | T,
+    workOptions?: ZLinkSerialWorkOptions
+  ): Promise<T> {
+    return this.timerSerial(timerName).post(operation, workOptions);
+  }
+
+  /** Admits held packets through the same Actor FIFO as ordinary ingress. */
+  admitActorPacketPrefix(
     actorId: string,
-    records: readonly {
-      readonly operation: (
-        executeChild: <TChild>(
-          child: (serial: ZLinkSpotSerialTurnExecutor) => Promise<TChild> | TChild
-        ) => Promise<TChild>
-      ) => Promise<void>;
-      readonly preparation?: ZLinkSerialWorkPreparation;
-      readonly workOptions?: ZLinkSerialWorkOptions;
-    }[]
-  ): readonly Promise<void>[] {
+    records: readonly ZLinkActorHandoffPrefixRecord[],
+    dispatch: ZLinkActorPacketTurnDispatch
+  ): ZLinkActorHandoffPrefixAdmission {
     const serial = this.actorSerial(actorId);
-    return this.actorExecutor(actorId).admitDurablePrefix(
+    const terminals = this.actorExecutor(actorId).admitDurablePrefix(
       records.map((record) => ({
-        operation: (executeChild) => record.operation((child) => executeChild(() => child(serial))),
+        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<T>(
-    timerName: string,
-    operation: () => Promise<T> | T,
-    workOptions?: ZLinkSerialWorkOptions
-  ): Promise<T> {
-    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: string): boolean {