@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,3 +1,5 @@
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import type { ZLinkBackendActorRef } from '../backend/contracts';
 import { decodeActorMessageFollowContext, type ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { RoutingId, ZLinkActor } from '../../contracts';
@@ -146,7 +148,7 @@ export function decodeRemoteActorJoinPayload(
     requestContentType:
       typeof payload.requestContentType === 'string'
         ? payload.requestContentType
-        : 'application/json'
+        : ZlinkStreamContentType.Json
   };
 }
 
@@ -302,8 +304,10 @@ function decodeBoundSessionServiceWireRelocation(
 
 function requireSpotId(value: string): string {
   const bytes = Buffer.byteLength(value, 'utf8');
-  if (bytes < 1 || bytes > 255) {
-    throw new Error('Remote bound session SpotId must contain 1..255 UTF-8 bytes.');
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES) {
+    throw new Error(
+      `Remote bound session SpotId must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`
+    );
   }
   return value;
 }

package/src/runtime/spots/spot-route-packet-dispatch.ts

@@ -1,21 +1,31 @@
-import type {
-  Type,
-  ZLinkMessageSerializer,
-  ZLinkSpot,
-  ZLinkSpotPacketHandler,
-  ZLinkSpotRequestHandler
+import {
+  type Type,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  type ZLinkSpotPacketHandler,
+  type ZLinkSpotRequestHandler,
+  ZLinkFrameworkException,
+  zlinkMessageMetadata
 } from '../../contracts';
+
+import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkFrameworkException, zlinkMessageMetadata } from '../../contracts';
 import {
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import {
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET
+} from '../actors';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
-import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import {
   decodeChannelEnvelope,
@@ -27,25 +37,18 @@ import {
   ZLinkChannelMessageKind,
   type ZLinkChannelEnvelopeCodecRegistry
 } from '../channels/channel-envelope';
+import { SPOT_DIRECT_ENVELOPE } from '../channels/spot-direct-envelope';
+import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
+import { zlinkMetadataByteLength, zlinkSerialWorkOptions } from '../execution/serial-work-size';
 import {
-  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET
-} from '../actors';
+  internalFrameworkErrorKind,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
 import { resolveLifecycleHandler } from '../handlers/handler-instance-scope';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
-import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkApplicationWorkClaim } from '../admission';
-import { zlinkMetadataByteLength, zlinkSerialWorkOptions } from '../execution/serial-work-size';
 import { REMOTE_ACTOR_JOIN_PACKET } from './spot-remote-codec';
 import { appendRouteReplyParts, hasReplyToken, submitRouteReply } from './spot-route-replies';
-import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
-import {
-  ZLinkFrameworkInternalErrorKind,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
-import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 
 interface ZLinkSpotRoutePacketDispatchOptions {
   readonly packetHandlers: ReadonlyMap<string, readonly ZLinkSpotHandlerRegistration[]>;
@@ -58,8 +61,6 @@ interface ZLinkSpotRoutePacketDispatchOptions {
   readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
 }
 
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
-
 /** D5: reply metadata attached only to framework-self-generated errors. */
 const FRAMEWORK_ORIGIN_REPLY_METADATA: Readonly<Record<string, string>> = Object.freeze({
   [ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY]: ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE

package/src/runtime/spots/spot-route-replies.ts

@@ -1,6 +1,7 @@
+import { constants as osConstants } from 'node:os';
 import type {
-  ZLinkBackendMessageLike as MessageLike,
-  ZLinkBackendReceived as BackendReceived
+  ZLinkBackendReceived as BackendReceived,
+  ZLinkBackendMessageLike as MessageLike
 } from '../backend/runtime-values';
 import {
   decodeChannelEnvelope,
@@ -8,8 +9,9 @@ import {
   encodeChannelReplyParts
 } from '../channels/channel-envelope';
 import { ZLinkConfigurationException } from '../configuration';
-import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 import type { ZLinkDecodedRemoteActorJoinRequest } from './spot-remote-codec';
+import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
+const nativeErrnoValues = osConstants.errno;
 
 export interface ZLinkRouteReplySubmitOperation {
   message(message: MessageLike): ZLinkRouteReplySubmitOperation;
@@ -120,6 +122,6 @@ function isNativeBadAddress(error: unknown): boolean {
   return (
     typeof error === 'object' &&
     error !== null &&
-    Number((error as { nativeErrno?: unknown }).nativeErrno) === 14
+    Number((error as { nativeErrno?: unknown }).nativeErrno) === nativeErrnoValues.EFAULT
   );
 }

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

@@ -5,6 +5,8 @@ import type {
   ZLinkSpotActorJoinResult
 } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import {
@@ -23,12 +25,12 @@ import {
   hasRemoteActorJoinIdentity,
   isRemoteActorJoinPayload,
   type ZLinkDecodedRemoteActorJoinRequest,
-  type ZLinkRoutedActorTransferProvider,
-  type ZLinkRemoteActorJoinWirePayload
+  type ZLinkRemoteActorJoinWirePayload,
+  type ZLinkRoutedActorTransferProvider
 } from './spot-remote-codec';
 import { submitRoutedActorJoinError, submitRoutedActorJoinReply } from './spot-route-replies';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+const DEFAULT_PENDING_ADMISSION_TIMEOUT_MS = 30_000;
 
 interface ZLinkRoutedActorAdmissionTarget {
   onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
@@ -41,7 +43,8 @@ interface ZLinkSpotRoutedActorAdmissionOptions {
   readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
   readonly commitTransferredActor?: (
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ) => Promise<readonly ZLinkActorHandoffResult[]>;
   readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
   readonly pendingAdmissionTimeoutMs?: number;
@@ -220,7 +223,11 @@ export class ZLinkSpotRoutedActorAdmission {
         decoded.remoteBoundSessionTarget
       );
       const handoffResults =
-        (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog)) ?? [];
+        (await this.options.commitTransferredActor?.(
+          actor,
+          decoded.handoffBacklog,
+          decoded.remoteBoundSessionTarget
+        )) ?? [];
       const commitReply = {
         accepted: true,
         actorNodeRid: String(actorRef.nodeRid),
@@ -278,7 +285,7 @@ export class ZLinkSpotRoutedActorAdmission {
     if (pending.deadline !== undefined) clearTimeout(pending.deadline);
     pending.deadline = setTimeout(() => {
       if (this.pending.get(transferId) === pending) this.pending.delete(transferId);
-    }, this.options.pendingAdmissionTimeoutMs ?? 30_000);
+    }, this.options.pendingAdmissionTimeoutMs ?? DEFAULT_PENDING_ADMISSION_TIMEOUT_MS);
     pending.deadline.unref();
   }
 

package/src/runtime/spots/spot-routed-frame-dispatch.ts

@@ -9,11 +9,10 @@ import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProvider
 import type { RoutingId } from '../../contracts';
 import type { ActorRef } from '../../contracts/Common/ActorRef';
 import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
-import type { ZLinkBackendReceived, ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkBackendReceived } from '../backend/contracts';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkChannelEnvelopeCodecRegistry } from '../channels/channel-envelope';
 import { decodeRemoteActorPacketRelay } from './spot-remote-route-codec';
-import { ZLINK_RECV_DONT_WAIT } from './spot-native-flags';
 import { ZLinkSpotActorPacketRelayDispatch } from './spot-actor-packet-relay-dispatch';
 import type {
   ZLinkActorPacketDelivery,
@@ -33,8 +32,6 @@ interface ZLinkRoutedFrameAdmissionTarget {
 }
 
 interface ZLinkSpotRoutedFrameDispatchOptions {
-  readonly nativeSpot: ZLinkBackendSpot;
-  readonly createReceived: () => ZLinkBackendReceived;
   readonly nativeSpotId: string;
   readonly serial: ZLinkSpotSerialTurnExecutor;
   readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
@@ -43,7 +40,8 @@ interface ZLinkSpotRoutedFrameDispatchOptions {
   readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
   readonly commitTransferredActor?: (
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ) => Promise<readonly ZLinkActorHandoffResult[]>;
   readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
   readonly routedBoundSessionReceiver?: (
@@ -86,11 +84,9 @@ interface ZLinkSpotRoutedFrameDispatchOptions {
   readonly providerResolver?: ZLinkProviderResolver;
   readonly dispatchErrors?: ZLinkDispatchErrorReporter;
   readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
-  readonly waitIdle: () => Promise<void>;
 }
 
 export class ZLinkSpotRoutedFrameDispatch {
-  private routeDraining = false;
   private readonly packetHandlers = new Map<string, ZLinkSpotHandlerRegistration[]>();
   private readonly routedBoundSessionDispatch: ZLinkSpotRoutedBoundSessionDispatch;
   private readonly actorPacketRelayDispatch: ZLinkSpotActorPacketRelayDispatch;
@@ -144,61 +140,6 @@ export class ZLinkSpotRoutedFrameDispatch {
     }
   }
 
-  async drain(
-    received: ZLinkBackendReceived | undefined = undefined,
-    retryDeadlineMs = performance.now()
-  ): Promise<void> {
-    if (this.routeDraining) {
-      if (received !== undefined) {
-        try {
-          await this.dispatch(received);
-        } finally {
-          received.close();
-        }
-      }
-      return;
-    }
-    this.routeDraining = true;
-    try {
-      if (received !== undefined) {
-        try {
-          await this.dispatch(received);
-        } finally {
-          received.close();
-        }
-        received = undefined;
-      }
-      for (;;) {
-        received ??= this.options.createReceived();
-        try {
-          if (!this.options.nativeSpot.recvRoute(received, ZLINK_RECV_DONT_WAIT)) {
-            received.close();
-            await this.options.waitIdle();
-            return;
-          }
-        } catch (error) {
-          if (isRouteRecvRetryable(error)) {
-            closeReceivedQuietly(received);
-            if (performance.now() < retryDeadlineMs) {
-              setTimeout(() => void this.drain(undefined, retryDeadlineMs), 10);
-            }
-            return;
-          }
-          received.close();
-          throw error;
-        }
-        try {
-          await this.dispatch(received);
-        } finally {
-          received.close();
-        }
-        received = this.options.createReceived();
-      }
-    } finally {
-      this.routeDraining = false;
-    }
-  }
-
   async dispatchFromEvent(received: ZLinkBackendReceived): Promise<void> {
     try {
       await this.dispatch(received);
@@ -234,20 +175,8 @@ export class ZLinkSpotRoutedFrameDispatch {
     if (await this.routePacketDispatch.dispatch(received)) {
       return;
     }
-    await this.routedActorAdmission.admit(received);
+    await this.options.serial.executeLifecycleOperation(() =>
+      this.routedActorAdmission.admit(received)
+    );
   }
 }
-
-function isRouteRecvRetryable(error: unknown): boolean {
-  return (
-    typeof error === 'object' &&
-    error !== null &&
-    [201, 202, 204].includes(Number((error as { result?: unknown }).result))
-  );
-}
-
-function closeReceivedQuietly(received: ZLinkBackendReceived): void {
-  try {
-    received.close();
-  } catch {}
-}

package/src/runtime/spots/spot-routed-spot-packet-dispatch.ts

@@ -1,3 +1,4 @@
+import { dispatchReasonFromError } from '../diagnostics/dispatch-error-details';
 import type {
   RoutingId,
   Type,
@@ -7,7 +8,7 @@ import type {
 } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkApplicationWorkClaim } from '../admission';
-import { ZLinkFrameworkException, zlinkMessageMetadata } from '../../contracts';
+import { zlinkMessageMetadata } from '../../contracts';
 import {
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
@@ -18,8 +19,7 @@ import type { ZLinkDispatchErrorReporter } from '../channels';
 import { ZLinkConfigurationException } from '../configuration';
 import {
   ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
+  createInternalFrameworkException
 } from '../framework-errors-internal';
 import { resolveLifecycleHandler } from '../handlers/handler-instance-scope';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
@@ -31,6 +31,7 @@ import {
 } from '../application-jobs/application-job-queue-scope';
 
 interface ZLinkRoutedSpotPacketActivation {
+  readonly objectGeneration?: bigint;
   readonly meshName?: string;
   readonly spotId: RoutingId;
   readonly spot: ZLinkSpot;
@@ -55,6 +56,9 @@ interface ZLinkRoutedSpotPacketContext {
   readonly signal?: AbortSignal;
   /** Wait until a recovered activation has actually entered its first handler. */
   readonly awaitFirstHandlerTurn?: boolean;
+  readonly onOneWayError?: (error: unknown) => void;
+  /** Retains the caller's Instance address intent through an incarnation boundary. */
+  readonly activationRecord?: import('../foundation/service-runtime-contracts').ReceiveRecord;
 }
 
 export class ZLinkRoutedSpotPacketDispatch {
@@ -143,14 +147,52 @@ export class ZLinkRoutedSpotPacketDispatch {
       activation.meshName === undefined
         ? undefined
         : this.options.claimApplicationWork?.(activation.meshName);
-    const runHandler = async () => {
+    const originalRecord = context.activationRecord?.activationRecord;
+    const instanceIntent =
+      originalRecord?.activation === 'missing' ||
+      (originalRecord?.activation === 'ready' && originalRecord.instanceIntent);
+    const runHandler = async (failure?: unknown) => {
       try {
+        if (failure !== undefined) throw failure;
+        const current = this.options.resolveActivation(spotId);
+        if (
+          current === undefined ||
+          (!instanceIntent &&
+            (current !== activation ||
+              (originalRecord?.activation === 'ready' &&
+                originalRecord.route.objectGeneration !== current.objectGeneration)))
+        ) {
+          throw createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+            `Spot '${String(spotId)}' is not active.`
+          );
+        }
+        if (
+          context.activationRecord?.deadlineUnixMs !== undefined &&
+          context.activationRecord.deadlineUnixMs < BigInt(Date.now())
+        ) {
+          throw createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+            `Spot '${String(spotId)}' request deadline has expired.`
+          );
+        }
+        const currentRegistrations =
+          current === activation
+            ? registrations
+            : current.handlers
+                .snapshot()
+                .filter(
+                  (registration) =>
+                    registration.kind === 'packet' &&
+                    (registration.packetName ?? registration.handlerType.name) ===
+                      (packetName ?? '')
+                );
         // Decode only after the Spot has acquired both application admission
         // and its execution authority.
         const payload = decodePayload();
-        for (const registration of registrations) {
+        for (const registration of currentRegistrations) {
           const handler = await resolveLifecycleHandler(
-            activation.spot,
+            current.spot,
             registration.handlerType as Type<
               | ZLinkSpotPacketHandler<ZLinkSpot, unknown>
               | ZLinkSpotRequestHandler<ZLinkSpot, unknown, unknown>
@@ -159,8 +201,9 @@ export class ZLinkRoutedSpotPacketDispatch {
           );
           resolveFirstHandlerTurn?.();
           resolveFirstHandlerTurn = undefined;
+          context.activationRecord?.onHandlerTurnStarted?.();
           releaseApplicationJobPermitBeforeHandler();
-          response = await handler.handle(activation.spot, payload, {
+          response = await handler.handle(current.spot, payload, {
             channelName: context.channelName,
             contentType: context.contentType,
             packetName: packetName!,
@@ -186,17 +229,33 @@ export class ZLinkRoutedSpotPacketDispatch {
                 applicationClaim?.close();
               }
             },
-            (error) => this.reportFailure(spotId, packetName, context, false, error),
+            (error) => {
+              if (context.onOneWayError === undefined) {
+                this.reportFailure(spotId, packetName, context, false, error);
+              } else if (resolveFirstHandlerTurn === undefined) {
+                context.onOneWayError(error);
+              }
+            },
             context.workOptions,
-            { signal: context.signal }
+            { signal: context.signal },
+            instanceIntent
+              ? async (failure?: unknown) => {
+                  try {
+                    await runHandler(failure);
+                  } finally {
+                    detachedApplicationPermit?.releaseAfterInternalProcessing();
+                    applicationClaim?.close();
+                  }
+                }
+              : undefined
           );
-          await firstHandlerTurn;
         } catch (error) {
           detached = false;
           detachedApplicationPermit?.releaseAfterInternalProcessing();
           rejectFirstHandlerTurn?.(error);
           throw error;
         }
+        await firstHandlerTurn;
       } else {
         if (activation.serial.isCurrentTurn) {
           throw createInternalFrameworkException(
@@ -204,10 +263,15 @@ export class ZLinkRoutedSpotPacketDispatch {
             `Spot '${spotId}' cannot await a request to its current serial turn.`
           );
         }
-        await activation.serial.execute(runHandler, context.workOptions);
+        await activation.serial.execute(
+          runHandler,
+          context.workOptions,
+          instanceIntent ? runHandler : undefined
+        );
       }
     } catch (error) {
-      this.reportFailure(spotId, packetName, context, returnResponse, error);
+      if (context.activationRecord?.activationRecord === undefined)
+        this.reportFailure(spotId, packetName, context, returnResponse, error);
       throw error;
     } finally {
       if (!detached) applicationClaim?.close();
@@ -222,18 +286,17 @@ export class ZLinkRoutedSpotPacketDispatch {
     returnResponse: boolean,
     error: unknown
   ): void {
-    const frameworkErrorKind =
-      error instanceof ZLinkFrameworkException ? internalFrameworkErrorKind(error) : undefined;
-    this.options.dispatchErrors?.report({
-      surface: ZLinkDispatchErrorSurface.SpotRoute,
+    const reporter = this.options.dispatchErrors;
+    if (reporter?.captureEnabled() !== true) return;
+    reporter.report({
+      surface:
+        context.activationRecord?.activationRecord?.kind === 'instanceSpot'
+          ? ZLinkDispatchErrorSurface.InstanceSpot
+          : ZLinkDispatchErrorSurface.SpotRoute,
       messageKind: returnResponse
         ? ZLinkDispatchMessageKind.Request
         : ZLinkDispatchMessageKind.Send,
-      reason:
-        frameworkErrorKind === ZLinkFrameworkInternalErrorKind.WorkerQueueFull ||
-        frameworkErrorKind === ZLinkFrameworkInternalErrorKind.DeadlineExceeded
-          ? ZLinkDispatchErrorReason.Backpressure
-          : ZLinkDispatchErrorReason.HandlerException,
+      reason: dispatchReasonFromError(error),
       action: returnResponse ? ZLinkDispatchErrorAction.FailCaller : ZLinkDispatchErrorAction.Drop,
       packetName,
       channelName: context.channelName,
@@ -245,9 +308,19 @@ export class ZLinkRoutedSpotPacketDispatch {
   private reportMissing(
     spotId: RoutingId,
     packetName: string | undefined,
-    context: { readonly channelName: string },
+    context: ZLinkRoutedSpotPacketContext,
     returnResponse: boolean
   ): void {
+    if (context.activationRecord?.activationRecord !== undefined) {
+      if (!returnResponse && context.onOneWayError !== undefined)
+        context.onOneWayError(
+          createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.HandlerNotFound,
+            `SPOT route handler not found: ${packetName}`
+          )
+        );
+      return;
+    }
     this.options.dispatchErrors?.report({
       surface: ZLinkDispatchErrorSurface.SpotRoute,
       messageKind: returnResponse

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

@@ -10,7 +10,7 @@ import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-con
 import type {
   ZLinkRemoteActorPacketTarget,
   ZLinkRemoteBoundSessionTarget,
-  ZLinkDeferredJoinAcceptedRoot
+  ZLinkDeferredJoinCompletion
 } from '../actors';
 import type { ZLinkActorHandoffDispatch } from '../actors/actor-handoff';
 import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
@@ -44,26 +44,15 @@ export interface ZLinkSpotActorTransferRuntime {
     operationId: ZLinkActorJoinOperationId,
     actorRef: ActorRef,
     rawReply: Uint8Array,
-    replyContentType?: string,
-    signal?: AbortSignal,
-    canonicalInventoryDigest?: string
-  ): Promise<ZLinkDeferredJoinAcceptedRoot>;
-  discardDeferredJoinAccepted(
-    root: ZLinkDeferredJoinAcceptedRoot,
-    signal?: AbortSignal
-  ): Promise<void>;
-  markDeferredJoinAcceptedCommitted(
-    root: ZLinkDeferredJoinAcceptedRoot,
-    actorRef: ActorRef,
-    signal?: AbortSignal
-  ): Promise<ZLinkDeferredJoinAcceptedRoot>;
-  commitAndDeliverDeferredJoinAccepted(
-    root: ZLinkDeferredJoinAcceptedRoot,
+    replyContentType?: string
+  ): ZLinkDeferredJoinCompletion;
+  deliverDeferredJoinCompletion(
+    completion: ZLinkDeferredJoinCompletion,
     actor: ZLinkActor,
     actorRef: ActorRef,
     submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>,
     signal?: AbortSignal
-  ): Promise<ZLinkDeferredJoinAcceptedRoot>;
+  ): Promise<void>;
   getOrCreateRoutedActor(
     actorId: string,
     actorType: string,
@@ -83,15 +72,6 @@ export interface ZLinkSpotActorTransferRuntime {
     deadlineAtMs: number,
     signal?: AbortSignal
   ): Promise<import('../locations/internal-location-contracts').ZLinkAuthoritySnapshot>;
-  rememberRoutedActorTransferTarget(
-    actorId: string,
-    target: ZLinkRemoteBoundSessionTarget | undefined
-  ): void;
-  claimNativeActorLocation(
-    actor: ZLinkActor,
-    spotId: RoutingId,
-    spotMeshName: string
-  ): Promise<ZLinkNativeActorJoinSnapshot>;
   claimRoutedActorLocation(
     actor: ZLinkActor,
     spotId: RoutingId,
@@ -101,28 +81,19 @@ export interface ZLinkSpotActorTransferRuntime {
       readonly membershipEpoch: bigint;
     }
   ): Promise<void>;
-  publishRoutedActorOwnership(actor: ZLinkActor): Promise<void>;
+  publishRoutedActorOwnership(
+    actor: ZLinkActor,
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
+  ): Promise<void>;
   openRoutedActorSession(actor: ZLinkActor): Promise<void>;
   bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
   commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
   clearRoutedActor(actor: ZLinkActor): void;
-  rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
   rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
   notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
   actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
 }
 
-export interface ZLinkNativeActorJoinSnapshot {
-  readonly spotId?: RoutingId;
-  readonly spot?: ZLinkSpot;
-  readonly locationSpotId?: RoutingId;
-  readonly spotMeshName?: string;
-  readonly actorRef?: ActorRef;
-  readonly spotGeneration?: bigint;
-  readonly membershipEpoch?: bigint;
-  readonly ownerNodeGeneration?: bigint;
-}
-
 export interface ZLinkSpotBoundSessionRuntime {
   receiveRoutedBoundSession(
     actorId: string,
@@ -151,10 +122,6 @@ export interface ZLinkSpotBoundSessionRuntime {
     actorPacketTarget?: unknown,
     signal?: AbortSignal
   ): Promise<void>;
-  rememberRemoteBoundSessionTarget(
-    actorId: string,
-    target: ZLinkRemoteBoundSessionTarget | undefined
-  ): void;
   resolveRemoteBoundSessionTarget(
     sourceNodeRid: RoutingId,
     sourceSessionRid: RoutingId

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

@@ -107,6 +107,15 @@ export class ZLinkSpotSerialExecutor {
    * ownership turn. Already accepted work remains drainable.
    */
   close(): Promise<void> {
+    const children = this.closeChildren();
+    return Promise.all([children, this.spotSerial.whenIdle()]).then(() => undefined);
+  }
+
+  /**
+   * Closes the Actor and timer queues. The Spot queue stays open for the Spot
+   * Close lifecycle item that owns it; that Close closes it when it finishes.
+   */
+  closeChildren(): Promise<void> {
     if (this.closePromise !== undefined) return this.closePromise;
     this.closing = true;
     const childSerials = [...this.actorSerials.values(), ...this.timerSerials.values()];
@@ -115,8 +124,7 @@ export class ZLinkSpotSerialExecutor {
     this.timerSerials.clear();
     this.actorExecutors.clear();
     this.closePromise = Promise.all([
-      this.spotSerial.close(),
-      ...childSerials.map((serial) => serial.close()),
+      ...childSerials.map((serial) => serial.whenIdle()),
       ...actorExecutors.map((executor) => executor.close())
     ]).then(() => undefined);
     return this.closePromise;