@zlink-systems/framework 0.30.3 → 0.32.0

package/src/runtime/protocol/service_wire_codec.generated.ts

@@ -5398,7 +5398,7 @@ function writeRelocationControlData(input: RelocationControlData, writer: Writer
 export function decodeRelocationControlData(bytes: Uint8Array, context: ServiceWireDecoderContext): RelocationControlData { const reader = new Reader(bytes); const value = readRelocationControlData(reader, context, {}, 0); reader.done("relocation-control-data"); return value; }
 export function encodeRelocationControlData(value: RelocationControlData, context: ServiceWireDecoderContext): Uint8Array { const writer = new Writer(); writeRelocationControlData(value, writer, context, {}, 0); return writer.result(); }
 
-export type RequestSpecificTail = { readonly originalOperationKind: "actorLookup"; readonly terminalResult: "ok"; readonly actor: ActorRef; readonly spotId: Text8; readonly spotGeneration: NonzeroU64; readonly membershipEpoch: NonzeroU64; readonly authorityOwnerGeneration: NonzeroU64 } | { readonly originalOperationKind: "actorJoin"; readonly terminalResult: "ok"; readonly join: ActorJoinReplyTail } | { readonly originalOperationKind: "streamBind"; readonly terminalResult: "ok"; readonly bindingGeneration: NonzeroU64; readonly authorityOwnerGeneration: NonzeroU64 } | { readonly originalOperationKind: "userSpotCreate"; readonly terminalResult: "ok"; readonly createResult: UserSpotCreateResult; readonly spot: SpotRef } | { readonly originalOperationKind: "userSpotClose"; readonly terminalResult: "ok"; readonly closed: Bool8 } | { readonly originalOperationKind: "actorCreate"; readonly terminalResult: "ok"; readonly creation: ActorCreateTerminal } | { readonly originalOperationKind: MeshOperationKind; readonly terminalResult: RequestTerminalResult };
+export type RequestSpecificTail = { readonly originalOperationKind: "actorLookup"; readonly terminalResult: "ok"; readonly actor: ActorRef; readonly spotId: Text8; readonly spotGeneration: NonzeroU64; readonly membershipEpoch: NonzeroU64; readonly authorityOwnerGeneration: NonzeroU64 } | { readonly originalOperationKind: "actorJoin"; readonly terminalResult: "ok"; readonly join: ActorJoinReplyTail } | { readonly originalOperationKind: "streamBind"; readonly terminalResult: "ok"; readonly bindingGeneration: NonzeroU64; readonly authorityOwnerGeneration: NonzeroU64 } | { readonly originalOperationKind: "streamBind"; readonly terminalResult: "rejected"; readonly rejectionMessage: NonemptyText16 } | { readonly originalOperationKind: "userSpotCreate"; readonly terminalResult: "ok"; readonly createResult: UserSpotCreateResult; readonly spot: SpotRef } | { readonly originalOperationKind: "userSpotClose"; readonly terminalResult: "ok"; readonly closed: Bool8 } | { readonly originalOperationKind: "actorCreate"; readonly terminalResult: "ok"; readonly creation: ActorCreateTerminal } | { readonly originalOperationKind: MeshOperationKind; readonly terminalResult: RequestTerminalResult };
 
 function readRequestSpecificTail(reader: Reader, context: ServiceWireDecoderContext, enclosing: any, flags: number): RequestSpecificTail {
   void context; void enclosing; void flags;
@@ -5433,6 +5433,10 @@ function readRequestSpecificTail(reader: Reader, context: ServiceWireDecoderCont
     value["authorityOwnerGeneration"] = readNonzeroU64(body, context, value, flags);
 
 
+  } else if (same(value["originalOperationKind"], "streamBind") && same(value["terminalResult"], "rejected")) {
+    value["rejectionMessage"] = readNonemptyText16(body, context, value, flags);
+
+
   } else if (same(value["originalOperationKind"], "userSpotCreate") && same(value["terminalResult"], "ok")) {
     value["createResult"] = readUserSpotCreateResult(body, context, value, flags);
 
@@ -5462,7 +5466,7 @@ function writeRequestSpecificTail(input: RequestSpecificTail, writer: Writer, co
 
   const body = writer;
   if (same(value["originalOperationKind"], "actorLookup") && same(value["terminalResult"], "ok")) {
-    if (value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["actor"] === undefined) fail("actor required");
 
 
@@ -5484,13 +5488,13 @@ function writeRequestSpecificTail(input: RequestSpecificTail, writer: Writer, co
 
     writeNonzeroU64(numeric(value["authorityOwnerGeneration"]), body, context, value, flags);
   } else if (same(value["originalOperationKind"], "actorJoin") && same(value["terminalResult"], "ok")) {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["join"] === undefined) fail("join required");
 
 
     writeActorJoinReplyTail(value["join"], body, context, value, flags);
   } else if (same(value["originalOperationKind"], "streamBind") && same(value["terminalResult"], "ok")) {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["join"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["join"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["bindingGeneration"] === undefined) fail("bindingGeneration required");
 
 
@@ -5499,8 +5503,14 @@ function writeRequestSpecificTail(input: RequestSpecificTail, writer: Writer, co
 
 
     writeNonzeroU64(numeric(value["authorityOwnerGeneration"]), body, context, value, flags);
+  } else if (same(value["originalOperationKind"], "streamBind") && same(value["terminalResult"], "rejected")) {
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["rejectionMessage"] === undefined) fail("rejectionMessage required");
+
+
+    writeNonemptyText16(value["rejectionMessage"], body, context, value, flags);
   } else if (same(value["originalOperationKind"], "userSpotCreate") && same(value["terminalResult"], "ok")) {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["createResult"] === undefined) fail("createResult required");
 
 
@@ -5510,19 +5520,19 @@ function writeRequestSpecificTail(input: RequestSpecificTail, writer: Writer, co
 
     writeSpotRef(value["spot"], body, context, value, flags);
   } else if (same(value["originalOperationKind"], "userSpotClose") && same(value["terminalResult"], "ok")) {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["closed"] === undefined) fail("closed required");
 
 
     writeBool8(value["closed"], body, context, value, flags);
   } else if (same(value["originalOperationKind"], "actorCreate") && same(value["terminalResult"], "ok")) {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined) fail("request-specific-tail discriminator agreement");
     if (value["creation"] === undefined) fail("creation required");
 
 
     writeActorCreateTerminal(value["creation"], body, context, value, flags);
   } else {
-    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
+    if (value["actor"] !== undefined || value["spotId"] !== undefined || value["spotGeneration"] !== undefined || value["membershipEpoch"] !== undefined || value["authorityOwnerGeneration"] !== undefined || value["join"] !== undefined || value["bindingGeneration"] !== undefined || value["rejectionMessage"] !== undefined || value["createResult"] !== undefined || value["spot"] !== undefined || value["closed"] !== undefined || value["creation"] !== undefined) fail("request-specific-tail discriminator agreement");
 
   }
 

package/src/runtime/protocol/service_wire_pilot_codec.generated.ts

@@ -1,4 +1,4 @@
-// <auto-generated> DO NOT EDIT. schema-sha256: 9ccb179e5231ac7a42bfa09ab1b5b9ea942ee17567e0db19023a6cba30c2e044
+// <auto-generated> DO NOT EDIT. schema-sha256: 1a066261b5770782bf4027d3d08723669d4092a085699963afb214872f27d710
 export interface ServiceWireRouteFence { readonly id: string; readonly generation: bigint; readonly targetNodeRid: Uint8Array; readonly targetNodeGeneration: bigint; readonly expectedAuthorityOwnerGeneration: bigint; readonly expectedOwnerLeaseGeneration: bigint; }
 	export interface ApplicationPayloadEnvelopeV1 { readonly packetName: string; readonly contentType: string; readonly payload: Uint8Array; }
 	export interface ActorJoin28 { readonly correlation: bigint; readonly actor: ServiceWireRouteFence; readonly entry: boolean; readonly targetSpot: ServiceWireRouteFence; readonly payload?: ApplicationPayloadEnvelopeV1; }

package/src/runtime/spots/index.ts

@@ -1,3 +1,5 @@
+import { inspectRuntime } from '../internal-observation';
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import { encodeActorReply } from '../actors/actor-reply';
 import { boundSessionErrorPayload } from '../streams/bound-session-response-target';
 import { RELOCATED_REQUEST_OWNED_BY_REQUESTER } from '../actors/actor-handoff';
@@ -164,6 +166,7 @@ export {
 export { ZLinkPublicSpotManager, type ZLinkPublicSpotManagerOptions } from './spot-manager-public';
 
 export interface ZLinkSpotManagerOptions {
+  readonly defaultRequestTimeoutMs?: number;
   readonly spotFactories: readonly Type<ZLinkSpot>[];
   readonly instanceSpotFactories?: ReadonlyMap<
     string,
@@ -334,15 +337,23 @@ interface ZLinkTargetSpotCloseOperation {
 }
 
 export class DefaultZLinkSpotManager {
+  [inspectRuntime]() {
+    return Object.freeze({
+      activeActivationCount: this.activations.activeActivations().length,
+      hasCloseableActivation: (meshName: string, spotId: RoutingId) =>
+        this.activations.activationForClose(meshName, spotId) !== undefined
+    });
+  }
+
   private readonly factories: ReadonlySet<Type<ZLinkSpot>>;
-  private readonly activations: ZLinkSpotActivationRegistry;
+  readonly activations: ZLinkSpotActivationRegistry;
   private readonly workerRuntime: ZLinkWorkerRuntime;
   private readonly locationClaim: ZLinkSpotLocationClaim;
   private readonly routedSpotPackets: ZLinkRoutedSpotPacketDispatch;
   private readonly actorMembership: ZLinkSpotActorMembership;
   private readonly activationLifecycle: ZLinkSpotActivationLifecycle;
   private readonly formalRemoteTransfers = new ZLinkFormalRemoteActorTransferRegistry();
-  private readonly formalRemoteActorAdmissions = new ZLinkFormalRemoteActorAdmissionRegistry();
+  readonly formalRemoteActorAdmissions = new ZLinkFormalRemoteActorAdmissionRegistry();
   private readonly pendingInstanceMaterializations = new Map<
     string,
     Promise<ZLinkSpotActivation>
@@ -354,7 +365,7 @@ export class DefaultZLinkSpotManager {
     string,
     Map<string, Promise<ZLinkSpotActivation>>
   >();
-  private readonly closeOperations = new Map<string, ZLinkTargetSpotCloseOperation>();
+  readonly closeOperations = new Map<string, ZLinkTargetSpotCloseOperation>();
   private readonly pendingInstanceTerminals = new Map<string, number>();
   private readonly pendingInstanceTerminalGenerations = new Map<string, Map<string, number>>();
   private readonly deferredInstanceAuthorityReleases = new Map<string, Set<bigint>>();
@@ -1159,14 +1170,15 @@ export class DefaultZLinkSpotManager {
     beginAuthority: (
       onCommitted: () => void
     ) => Promise<import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority>,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    deadline?: Date
   ): Promise<boolean> {
     return await this.closeWithReason(
       meshName,
       spotId,
       signal,
       ZLinkSpotCloseReason.ExplicitClose,
-      undefined,
+      deadline,
       beginAuthority
     );
   }
@@ -1222,6 +1234,11 @@ export class DefaultZLinkSpotManager {
     >,
     contextActivation?: ZLinkSpotActivation
   ): Promise<boolean> {
+    if (reason === ZLinkSpotCloseReason.ExplicitClose) {
+      deadline ??= new Date(
+        Date.now() + (this.options.defaultRequestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS)
+      );
+    }
     requireMeshName(meshName);
     const key = `${meshName}\0${String(spotId)}`;
     let operation = this.closeOperations.get(key);
@@ -1590,7 +1607,9 @@ export class DefaultZLinkSpotManager {
     parts: readonly Message[],
     returnResponse = false,
     remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget,
-    fallbackActorRef?: ActorRef
+    fallbackActorRef?: ActorRef,
+    requestTerminal?: (response: unknown) => Promise<void> | void,
+    messageFollowOrigin?: ZLinkMessageFollowOrigin
   ): Promise<unknown> {
     const activation = this.activations.resolveUnique(spotId);
     if (activation === undefined) {
@@ -1603,7 +1622,9 @@ export class DefaultZLinkSpotManager {
       parts,
       returnResponse,
       remoteBoundSessionTarget,
-      fallbackActorRef
+      fallbackActorRef,
+      requestTerminal,
+      messageFollowOrigin
     );
   }
 
@@ -1663,6 +1684,30 @@ export class DefaultZLinkSpotManager {
     return this.admitRoutedActorPacketPrefix(owner.spotId, actorId, records);
   }
 
+  /** Runs an owner-side lifecycle decision in the Actor's existing execution gate. */
+  executeActorTurn<T>(
+    meshName: string,
+    spotId: RoutingId | undefined,
+    actorId: string,
+    operation: () => Promise<T>
+  ): Promise<T> {
+    if (spotId === undefined) {
+      if (this.options.executeEntryActor === undefined) {
+        throw new ZLinkConfigurationException(
+          `Entry Spot Actor '${actorId}' has no execution gate for MeshNode '${meshName}'.`
+        );
+      }
+      return this.options.executeEntryActor(meshName, actorId, operation);
+    }
+    const activation = this.resolveApplicationActivation(spotId, meshName);
+    if (activation === undefined) {
+      throw new ZLinkConfigurationException(
+        `Actor '${actorId}' has no active Spot execution gate for '${String(spotId)}'.`
+      );
+    }
+    return activation.executeActor(actorId, operation);
+  }
+
   async dispatchRoutedSpotSend(
     spotId: RoutingId,
     packetName: string | undefined,
@@ -1735,7 +1780,8 @@ export class DefaultZLinkSpotManager {
       this.options.messageSerializers === undefined
         ? undefined
         : { serializers: this.options.messageSerializers };
-    const decodePayload = () => decodeChannelPayload(envelope, codecs);
+    const decodePayload = (messageType?: Type) =>
+      decodeChannelPayload(envelope, codecs, messageType);
     const context = {
       channelName: envelope.header.channelName,
       contentType: envelope.header.contentType,
@@ -1857,7 +1903,8 @@ export class DefaultZLinkSpotManager {
             this.options.messageSerializers === undefined
               ? undefined
               : { serializers: this.options.messageSerializers };
-          const decodePayload = () => decodeChannelPayload(envelope, codecs);
+          const decodePayload = (messageType?: Type) =>
+            decodeChannelPayload(envelope, codecs, messageType);
           const context = {
             channelName: envelope.header.channelName,
             contentType: envelope.header.contentType,
@@ -2231,7 +2278,7 @@ export class DefaultZLinkSpotManager {
     }
   }
 
-  private async dispatchMeshActorJoinCore(
+  async dispatchMeshActorJoinCore(
     meshName: string,
     owner: ReadyRecord,
     record: ReceiveRecord,

package/src/runtime/spots/spot-activation-registry.ts

@@ -13,7 +13,6 @@ import {
   createInternalFrameworkException
 } from '../framework-errors-internal';
 import type { ZLinkSpotActivation } from './spot-activation-state';
-import { ZLinkSpotLifecycleMetrics } from './spot-lifecycle-metrics';
 import type { ZLinkLocalSpotCreateResult } from './spot-manager-internal-contracts';
 const DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE = 64;
 
@@ -44,11 +43,12 @@ export class ZLinkSpotActivationRegistry {
   private readonly closing = new Map<string, ZLinkSpotCloseOperation>();
   private readonly failedClose = new Set<string>();
   private readonly emptyWaiters = new Set<() => void>();
-  private readonly lifecycleMetrics: ZLinkSpotLifecycleMetrics;
   private activeScan: Iterator<ZLinkSpotActivation> | undefined;
 
-  constructor(metrics?: import('../diagnostics').ZLinkRuntimeMetrics) {
-    this.lifecycleMetrics = new ZLinkSpotLifecycleMetrics(metrics);
+  constructor(private readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics) {}
+
+  private recordPopulation(activation: ZLinkSpotActivation, delta: number): void {
+    this.metrics?.recordSpotCount(activation.meshName, activation.domain.kind, delta);
   }
 
   allocateSpotId(meshName: string): RoutingId {
@@ -99,7 +99,11 @@ export class ZLinkSpotActivationRegistry {
 
   finishClose(meshName: string, spotId: RoutingId): void {
     const key = spotActivationKey(meshName, spotId);
-    if (this.activations.delete(key)) this.lifecycleMetrics.closed('user');
+    const activation = this.activations.get(key);
+    if (activation !== undefined) {
+      this.activations.delete(key);
+      this.recordPopulation(activation, -1);
+    }
     this.staged.delete(key);
     this.failedClose.delete(key);
     this.resolveEmptyWaiters();
@@ -172,7 +176,7 @@ export class ZLinkSpotActivationRegistry {
     }
     if (existing === undefined) {
       this.activations.set(key, activation);
-      this.lifecycleMetrics.opened('user');
+      this.recordPopulation(activation, 1);
     }
     return this.staged.has(key) ? undefined : activation;
   }
@@ -197,7 +201,7 @@ export class ZLinkSpotActivationRegistry {
     this.activations.delete(key);
     this.staged.delete(key);
     this.failedClose.delete(key);
-    this.lifecycleMetrics.closed('user');
+    this.recordPopulation(activation, -1);
     this.resolveEmptyWaiters();
     return activation;
   }
@@ -240,7 +244,7 @@ export class ZLinkSpotActivationRegistry {
           if (completed || resourcesReleased(activation)) {
             this.activations.delete(key);
             this.staged.delete(key);
-            this.lifecycleMetrics.closed('user');
+            this.recordPopulation(activation, -1);
             this.failedClose.delete(key);
           } else {
             this.failedClose.add(key);

package/src/runtime/spots/spot-activation-state.ts

@@ -19,6 +19,7 @@ import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 import { ZLinkSpotSerialExecutor, type ZLinkActorPacketTurnDispatch } from './spot-serial-executor';
 import type { ZLinkSpotTimerRegistry } from './spot-timer';
 import type { ZLinkSpotActorJoinDispatch } from './spot-actor-join-dispatch';
+import type { ZLinkSpotActorPacketDispatch } from './spot-actor-packet-dispatch';
 import { ZLinkExecutionBarrier, type ZLinkExecutionBarrierSeal } from '../execution';
 import type { ZLinkTimerRelocationState } from './spot-timer';
 
@@ -71,6 +72,7 @@ export class ZLinkSpotActivation {
   readonly nativeSpot?: ZLinkBackendSpot;
   readonly executionBarrier: ZLinkExecutionBarrier;
   actorDispatch?: ZLinkSpotActorJoinDispatch;
+  actorPacketDispatch?: ZLinkSpotActorPacketDispatch;
 
   private readonly joinedActors = new Map<string, ZLinkActor>();
   private readonly departedActorIds = new Set<string>();

package/src/runtime/spots/spot-actor-admission-coordinator.ts

@@ -16,6 +16,7 @@ import { routingIdsEqual } from '../routing-id';
 import type { ZLinkSpotActivationLifecycleOptions } from './spot-activation';
 import { ZLinkSpotActivation } from './spot-activation-state';
 import { ZLinkSpotActorJoinDispatch } from './spot-actor-join-dispatch';
+import type { ZLinkActorPacketExecution } from './spot-actor-packet-dispatch';
 import { ZLinkSpotActorPacketDispatch } from './spot-actor-packet-dispatch';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 
@@ -51,26 +52,23 @@ export class ZLinkSpotActorAdmissionCoordinator {
     requestTerminal?: (response: unknown) => Promise<void> | void,
     messageFollowOrigin?: ZLinkMessageFollowOrigin
   ): Promise<unknown> {
-    const handoff = this.options.actorHandoffRuntime?.capture(
-      origin,
-      actorId,
-      parts,
-      returnResponse,
-      remoteBoundSessionTarget,
-      fallbackActorRef,
-      undefined,
-      messageFollowOrigin
-    );
-    if (handoff !== undefined) return await handoff;
-    return await this.dispatchActorPacketDirect(
-      origin,
-      activation,
-      actorId,
-      parts,
-      returnResponse,
-      remoteBoundSessionTarget,
-      fallbackActorRef,
-      requestTerminal
+    return dispatchActorPacketInMailbox<ZLinkSpotSerialTurnExecutor>(
+      (operation) => activation.executeActor(actorId, operation),
+      (serial) =>
+        this.actorPacketDispatch(activation).admitDelivery(
+          serial,
+          {
+            origin,
+            actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef,
+            requestTerminal,
+            messageFollowOrigin
+          },
+          this.options.actorHandoffRuntime
+        )
     );
   }
 
@@ -87,7 +85,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       ),
       serial: activation.serial,
       actors: {
-        resolveActor: (actorId) => this.resolveActor(activation, actorId),
+        resolveActor: (actorId) => this.resolveLifecycleActor(activation, actorId),
         getTarget: () => activation.spot,
         defaultAccept: false,
         transfer:
@@ -110,7 +108,9 @@ export class ZLinkSpotActorAdmissionCoordinator {
             delivery.parts,
             delivery.returnResponse,
             delivery.remoteBoundSessionTarget,
-            delivery.fallbackActorRef
+            delivery.fallbackActorRef,
+            delivery.requestTerminal,
+            delivery.messageFollowOrigin
           ),
         bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
           const node = this.options.nativeSpotNodeProvider?.(activation.meshName);
@@ -202,13 +202,30 @@ export class ZLinkSpotActorAdmissionCoordinator {
     fallbackActorRef?: ActorRef,
     requestTerminal?: (response: unknown) => Promise<void> | void
   ): Promise<unknown> {
-    return new ZLinkSpotActorPacketDispatch({
+    return this.actorPacketDispatch(activation).dispatch(
+      actorSerial,
+      origin,
+      actorId,
+      parts,
+      returnResponse,
+      remoteBoundSessionTarget,
+      fallbackActorRef,
+      requestTerminal
+    );
+  }
+
+  private actorPacketDispatch(activation: ZLinkSpotActivation): ZLinkSpotActorPacketDispatch {
+    if (activation.actorPacketDispatch !== undefined) return activation.actorPacketDispatch;
+    activation.actorPacketDispatch = new ZLinkSpotActorPacketDispatch({
+      admission: this.options.admission,
       spot: activation.spot,
       spotId: () => String(activation.spotId),
       registry: activation.actorHandlers,
-      serial: actorSerial,
-      resolveActor: (targetActorId) => this.resolveActor(activation, targetActorId),
-      actorLeft: (targetActorId) => activation.hasDepartedActor(targetActorId),
+      resolveActor: (targetActorId) =>
+        this.options.actorResolver === undefined
+          ? activation.resolveJoinedActor(targetActorId)
+          : this.options.actorResolver(targetActorId),
+      hasDepartedActor: (targetActorId) => activation.hasDepartedActor(targetActorId),
       onDisconnectActor: (actor) =>
         activation.serial.execute(() => activation.spot.onDisconnectActor?.(actor)),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
@@ -221,18 +238,15 @@ export class ZLinkSpotActorAdmissionCoordinator {
       messageSerializers: this.options.messageSerializers,
       dispatchErrors: this.options.dispatchErrors,
       routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
-    }).dispatch(
-      origin,
-      actorId,
-      parts,
-      returnResponse,
-      remoteBoundSessionTarget,
-      fallbackActorRef,
-      requestTerminal
-    );
+    });
+    return activation.actorPacketDispatch;
   }
 
-  private resolveActor(activation: ZLinkSpotActivation, actorId: string): ZLinkActor | undefined {
+  /** Resolves native lifecycle records; messages use resolveActorIngress. */
+  private resolveLifecycleActor(
+    activation: ZLinkSpotActivation,
+    actorId: string
+  ): ZLinkActor | undefined {
     if (activation.hasDepartedActor(actorId)) return undefined;
     // The manager owns relocation visibility. Membership alone cannot publish
     // a staged Actor; resolver absence supports standalone Spot runtimes.
@@ -241,7 +255,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       : this.options.actorResolver(actorId);
   }
 
-  private async commitTransferredActorTransaction(
+  async commitTransferredActorTransaction(
     activation: ZLinkSpotActivation,
     actor: ZLinkActor,
     backlog: readonly ZLinkActorHandoffPacket[],
@@ -315,3 +329,14 @@ function requireBackendValueFactory<T>(factory: (() => T) | undefined, valueName
     return factory();
   };
 }
+
+/** Releases the Actor FIFO before awaiting a transferred admission terminal. */
+export async function dispatchActorPacketInMailbox<TSerial>(
+  enqueue: (
+    operation: (serial: TSerial) => Promise<ZLinkActorPacketExecution>
+  ) => Promise<ZLinkActorPacketExecution>,
+  dispatch: (serial: TSerial) => Promise<ZLinkActorPacketExecution>
+): Promise<unknown> {
+  const result = await enqueue(dispatch);
+  return 'terminal' in result ? await result.terminal : result.response;
+}

package/src/runtime/spots/spot-actor-ingress-admission.ts

@@ -0,0 +1,157 @@
+import { actorMessageFollowContext } from '../actors/actor-message-follow-context';
+import type { ActorRef, ZLinkActor } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type {
+  ZLinkActorPacketDelivery,
+  ZLinkActorRequestTerminal
+} from './spot-actor-packet-dispatch';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
+import type { ZLinkSpotActorHandoffRuntime } from './spot-runtime-ports';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+
+/** Parks an exact Actor incarnation while its accepted Join prepares the target. */
+export type ZLinkRouteToActorJoinPrewarm = (
+  actorId: string,
+  objectGeneration: bigint,
+  arrival: {
+    readonly origin: ApplicationJobOrigin;
+    readonly header: Buffer;
+    readonly payload: Buffer;
+    readonly returnResponse: boolean;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly fallbackActorRef?: ActorRef;
+    readonly requestTerminal?: ZLinkActorRequestTerminal;
+    readonly resolve: (value: unknown) => void;
+    readonly reject: (reason: unknown) => void;
+  }
+) => 'parked' | 'not-found';
+
+export type ZLinkActorIngressRoute = (
+  delivery: ZLinkActorPacketDelivery
+) => { readonly handled: boolean; readonly response?: unknown } | undefined;
+
+export type ZLinkActorIngressAdmission =
+  | { readonly kind: 'local'; readonly actor: ZLinkActor }
+  | { readonly kind: 'follow' | 'prewarm'; readonly terminal: Promise<unknown> }
+  | { readonly kind: 'stale'; readonly error: ReturnType<typeof createInternalFrameworkException> };
+
+/** Fixes one packet owner synchronously at the Actor FIFO head. */
+export function resolveActorIngress(
+  delivery: ZLinkActorPacketDelivery,
+  request: boolean,
+  options: {
+    readonly handoffRuntime?: ZLinkSpotActorHandoffRuntime;
+    readonly routeBeforeLocal?: ZLinkActorIngressRoute;
+    readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly hasDepartedActor?: (actorId: string) => boolean;
+    readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
+  }
+): ZLinkActorIngressAdmission {
+  const handoff = options.handoffRuntime?.capture(
+    delivery.origin,
+    delivery.actorId,
+    delivery.parts,
+    delivery.returnResponse,
+    delivery.remoteBoundSessionTarget,
+    delivery.fallbackActorRef,
+    undefined,
+    delivery.messageFollowOrigin
+  );
+  if (handoff !== undefined) return { kind: 'follow', terminal: handoff };
+  const route = options.routeBeforeLocal?.(delivery);
+  if (route?.handled === true) return { kind: 'follow', terminal: Promise.resolve(route.response) };
+  const actor =
+    options.hasDepartedActor?.(delivery.actorId) === true
+      ? undefined
+      : options.resolveActor(delivery.actorId);
+  if (actor !== undefined) return { kind: 'local', actor };
+  if (
+    options.routeToActorJoinPrewarm !== undefined &&
+    delivery.fallbackActorRef !== undefined &&
+    (!request || delivery.returnResponse || delivery.requestTerminal !== undefined)
+  ) {
+    const parked = parkForActorJoinPrewarm(
+      delivery.origin,
+      options.routeToActorJoinPrewarm,
+      delivery.actorId,
+      delivery.parts,
+      request,
+      delivery.returnResponse,
+      delivery.remoteBoundSessionTarget,
+      delivery.fallbackActorRef,
+      delivery.requestTerminal
+    );
+    if (parked !== undefined) return { kind: 'prewarm', terminal: parked };
+  }
+  return {
+    kind: 'stale',
+    error: createInternalFrameworkException(
+      actorMessageFollowContext(delivery.fallbackActorRef) === undefined
+        ? ZLinkFrameworkInternalErrorKind.ActorRouteNotFound
+        : ZLinkFrameworkInternalErrorKind.ActorLocationStale,
+      `SPOT actor is not registered locally: ${delivery.actorId}`
+    )
+  };
+}
+
+function parkForActorJoinPrewarm(
+  origin: ApplicationJobOrigin,
+  routeToActorJoinPrewarm: ZLinkRouteToActorJoinPrewarm,
+  actorId: string,
+  parts: readonly Message[],
+  isRequest: boolean,
+  returnResponse: boolean,
+  remoteBoundSessionTarget: ZLinkRemoteBoundSessionTarget | undefined,
+  fallbackActorRef: ActorRef,
+  requestTerminal: ZLinkActorRequestTerminal | undefined
+): Promise<unknown> | undefined {
+  let resolve: (value: unknown) => void = () => undefined;
+  let reject: (reason: unknown) => void = () => undefined;
+  const result = new Promise<unknown>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  //  A Request's real reply must still travel through the exact mailbox
+  //  correlation the original caller captured in `requestTerminal` — not
+  //  through this method's own return value, which the caller only uses
+  //  to decide whether it still owes a reply itself. Wrapping keeps that
+  //  reply route intact across the (possibly much later) redelivery at
+  //  migration time while also releasing the original caller once the
+  //  real reply has gone out, so it never sends a premature empty one.
+  const wrappedRequestTerminal: ZLinkActorRequestTerminal | undefined =
+    requestTerminal === undefined
+      ? undefined
+      : Object.assign(
+          async (response: unknown, preparedReply?: unknown) => {
+            try {
+              await requestTerminal(response, preparedReply);
+              resolve(undefined);
+            } catch (error) {
+              reject(error);
+              throw error;
+            }
+          },
+          { prepare: requestTerminal.prepare }
+        );
+  const route = routeToActorJoinPrewarm(actorId, fallbackActorRef.objectGeneration, {
+    origin,
+    header: Buffer.from(parts[0].data()),
+    payload: Buffer.from(parts[1].data()),
+    returnResponse,
+    remoteBoundSessionTarget,
+    fallbackActorRef,
+    requestTerminal: wrappedRequestTerminal,
+    resolve,
+    reject
+  });
+  if (route !== 'parked') return undefined;
+  //  A Send has no reply to wait for: the migrated redelivery still runs
+  //  in order later, but this caller's own await is done once parking is
+  //  confirmed.
+  if (!isRequest) resolve(undefined);
+  return result;
+}