@zlink-systems/framework 0.26.0 → 0.27.0

package/src/runtime/spots/spot-actor-join-dispatch.ts

@@ -6,34 +6,35 @@ import type {
   ZLinkSpot,
   ZLinkSpotActorJoinResult
 } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkBackendSpotDispatchEvent } from '../backend/contracts';
-import type {
-  ZLinkBackendActorRef,
-  ZLinkBackendActorRecvInfo,
-  ZLinkBackendSpot,
-  ZLinkBackendTopicMessage
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import {
+  type ZLinkBackendActorRecvInfo,
+  type ZLinkBackendActorRef,
+  type ZLinkBackendSpot,
+  type ZLinkBackendTopicMessage,
+  ZLinkBackendSpotDispatchEvent
 } from '../backend/contracts';
-import type { Message } from '../../contracts/Common/Message';
+
 import type { RequestResult } from '../backend/runtime-values';
-type RuntimeMessage = Message;
-import type { ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import { ZLinkSpotActorLifecycleDrain } from './spot-actor-lifecycle-drain';
+import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
 import { ZLinkSpotActorPacketDrain, type ZLinkActorDispatchPart } from './spot-actor-packet-drain';
-import { ZLINK_RECV_DONT_WAIT } from './spot-native-flags';
-import { ZLinkSpotNativeActorJoinAdmission } from './spot-native-actor-join-admission';
-import { ZLinkSpotRoutedFrameDispatch } from './spot-routed-frame-dispatch';
-import { ZLinkSpotSubscriptionDispatch } from './spot-subscription-dispatch';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
-import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkApplicationWorkClaim } from '../admission';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
-import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+import { ZLinkSpotRoutedFrameDispatch } from './spot-routed-frame-dispatch';
 import type {
   ZLinkSpotActorTransferRuntime,
   ZLinkSpotBoundSessionRuntime
 } from './spot-runtime-ports';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import { ZLinkSpotSubscriptionDispatch } from './spot-subscription-dispatch';
+const ACTOR_JOIN_POLL_INTERVAL_MS = 5;
+
+type RuntimeMessage = Message;
 
 const ZLINK_SPOT_DISPATCH_SUBJECT_SPOT = 1;
 const ZLINK_SPOT_DISPATCH_SUBJECT_CHANNEL_DEALER = 3;
@@ -62,11 +63,11 @@ interface ZLinkSpotActorAdmissionRuntime {
         readonly kind: 'enabled';
         readonly runtime: ZLinkSpotActorTransferRuntime;
       };
-  readonly commitNativeActor?: (actor: ZLinkActor) => Promise<void>;
   readonly commitActorDeparture?: (actorId: string) => void;
   readonly commitTransferredActor?: (
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ) => Promise<readonly ZLinkActorHandoffResult[]>;
 }
 
@@ -75,8 +76,7 @@ interface ZLinkSpotActorPacketRuntime {
   readonly bindRemoteSession?: (
     actor: ZLinkBackendActorRef,
     sourceNodeRid: RoutingId,
-    sourceSessionRid: RoutingId,
-    declaredTarget?: ZLinkRemoteBoundSessionTarget
+    sourceSessionRid: RoutingId
   ) => void;
   readonly replyNoBind?: (
     info: ZLinkBackendActorRecvInfo,
@@ -93,7 +93,6 @@ interface ZLinkSpotActorJoinDispatchOptions {
   readonly nativeSpot: ZLinkBackendSpot;
   readonly createTopicMessage: () => ZLinkBackendTopicMessage;
   readonly serial: ZLinkSpotSerialTurnExecutor;
-  readonly isSpotClosing?: () => boolean;
   readonly actors: ZLinkSpotActorAdmissionRuntime;
   readonly packets?: ZLinkSpotActorPacketRuntime;
   readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
@@ -105,13 +104,10 @@ interface ZLinkSpotActorJoinDispatchOptions {
 }
 
 export class ZLinkSpotActorJoinDispatch {
-  private draining = false;
-  private redrainRequested = false;
   private readonly nativeSpotId: string;
   private readonly subscriptions: ZLinkSpotSubscriptionDispatch;
   private readonly actorLifecycleDrain: ZLinkSpotActorLifecycleDrain;
   private readonly actorPacketDrain: ZLinkSpotActorPacketDrain;
-  private readonly nativeActorJoinAdmission: ZLinkSpotNativeActorJoinAdmission;
   private readonly routedFrames: ZLinkSpotRoutedFrameDispatch;
   private readonly nativeSpot: ZLinkBackendSpot;
 
@@ -136,20 +132,9 @@ export class ZLinkSpotActorJoinDispatch {
       waitIdle: waitSpotDispatchIdle,
       flowEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
     });
-    this.nativeActorJoinAdmission = new ZLinkSpotNativeActorJoinAdmission({
-      nativeSpot: options.nativeSpot,
-      serial: options.serial,
-      resolveActor: actors.resolveActor,
-      getTarget: actors.getTarget,
-      defaultAccept: actors.defaultAccept,
-      commitAcceptedActor: actors.commitNativeActor,
-      messageSerializers: options.messageSerializers,
-      dispatchErrors: options.dispatchErrors
-    });
     this.routedFrames = new ZLinkSpotRoutedFrameDispatch({
       nativeSpotId: this.nativeSpotId,
       serial: options.serial,
-      isSpotClosing: options.isSpotClosing,
       resolveActor: actors.resolveActor,
       getTarget: () => actors.getTarget() as ZLinkActorJoinAdmissionTarget & ZLinkSpot,
       defaultAccept: actors.defaultAccept,
@@ -159,7 +144,7 @@ export class ZLinkSpotActorJoinDispatch {
       bindRemoteSession:
         options.packets?.bindRemoteSession === undefined
           ? undefined
-          : (actor, sourceNodeRid, sourceSessionRid, declaredTarget) =>
+          : (actor, sourceNodeRid, sourceSessionRid) =>
               options.packets!.bindRemoteSession!(
                 {
                   actorId: actor.actorId,
@@ -167,8 +152,7 @@ export class ZLinkSpotActorJoinDispatch {
                   nodeRid: actor.nodeRid
                 },
                 sourceNodeRid,
-                sourceSessionRid,
-                declaredTarget
+                sourceSessionRid
               ),
       routedBoundSessionReceiver: options.boundSessionRuntime?.receiveRoutedBoundSession.bind(
         options.boundSessionRuntime
@@ -223,10 +207,6 @@ export class ZLinkSpotActorJoinDispatch {
       return;
     }
     this.nativeSpot.setDispatchHandler((info) => {
-      if (info.event === ZLinkBackendSpotDispatchEvent.ActorJoinReadable) {
-        this.runDetached('spot actor join drain', () => this.drain());
-        return;
-      }
       if (info.event === ZLinkBackendSpotDispatchEvent.SubscribeReadable) {
         this.runDetached('spot subscription drain', () => this.subscriptions.drain());
         return;
@@ -278,41 +258,8 @@ export class ZLinkSpotActorJoinDispatch {
     }
     void callback().catch(() => undefined);
   }
-
-  private async drain(): Promise<void> {
-    if (this.draining) {
-      this.redrainRequested = true;
-      return;
-    }
-    this.draining = true;
-    try {
-      do {
-        this.redrainRequested = false;
-        await this.drainAvailableActorJoins();
-      } while (this.redrainWasRequested());
-    } finally {
-      this.draining = false;
-    }
-  }
-
-  private redrainWasRequested(): boolean {
-    return this.redrainRequested;
-  }
-
-  private async drainAvailableActorJoins(): Promise<void> {
-    for (;;) {
-      const request = this.nativeSpot.recvActorJoin(ZLINK_RECV_DONT_WAIT);
-      if (request === null) {
-        await waitSpotDispatchIdle();
-        return;
-      }
-      await this.options.serial.executeLifecycleOperation(() =>
-        this.nativeActorJoinAdmission.admit(request, this.options.isSpotClosing?.() === true)
-      );
-    }
-  }
 }
 
 function waitSpotDispatchIdle(): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, 5));
+  return new Promise((resolve) => setTimeout(resolve, ACTOR_JOIN_POLL_INTERVAL_MS));
 }

package/src/runtime/spots/spot-actor-membership.ts

@@ -1,27 +1,31 @@
-import type {
-  RoutingId,
-  ZLinkActor,
-  ZLinkMessageSerializer,
-  ZLinkSpot,
-  ZLinkSpotActorJoinResult
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
+import {
+  type RoutingId,
+  type ZLinkActor,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  type ZLinkSpotActorJoinResult,
+  ZLinkEncodedPayload,
+  ZLinkMessage
 } from '../../contracts';
+
+import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkEncodedPayload, ZLinkMessage } from '../../contracts';
+import {
+  ZLinkDispatchErrorSurface,
+  ZLinkDispatchMessageKind,
+  ZLinkRuntimeDispatchErrorAction,
+  ZLinkRuntimeDispatchErrorReason
+} from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import { throwIfAborted } from '../abort';
-import type { Message } from '../../contracts/Common/Message';
+import { ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME, ZLinkSpotActorDispatcher } from '../actors';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import { ZLinkConfigurationException } from '../configuration';
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
 import { ZLinkDispatchErrorReporter } from '../channels';
-import { ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME, ZLinkSpotActorDispatcher } from '../actors';
+import { ZLinkConfigurationException } from '../configuration';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
-import { routingIdsEqual } from '../routing-id';
 import type { ZLinkSpotActivation } from './spot-activation-state';
-import type { ZLinkSpotActorTransferRuntime } from './spot-runtime-ports';
 import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
+import type { ZLinkSpotActorTransferRuntime } from './spot-runtime-ports';
 
 export interface ZLinkSpotActorMembershipOptions {
   readonly resolveActivation: (
@@ -41,11 +45,8 @@ export interface ZLinkSpotActorMembershipOptions {
   readonly entrySpotIdProvider?: (meshName: string) => string | undefined;
   readonly spotRouteResolver?: ZLinkSpotRouteResolver;
   readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
-  readonly isSpotClosing?: (activation: ZLinkSpotActivation) => boolean;
 }
 
-export type ZLinkActorJoinRollback = () => Promise<void> | void;
-
 export class ZLinkSpotActorMembership {
   constructor(private readonly options: ZLinkSpotActorMembershipOptions) {}
 
@@ -53,22 +54,14 @@ export class ZLinkSpotActorMembership {
     spotId: RoutingId,
     actor: ZLinkActor,
     request: Message,
-    commit: (
-      spot: ZLinkSpot
-    ) => Promise<ZLinkActorJoinRollback | void> | ZLinkActorJoinRollback | void,
+    commit: (spot: ZLinkSpot) => Promise<void> | void,
     signal?: AbortSignal,
     leaveSource?: () => Promise<void>,
-    contentType = 'application/json'
+    contentType: string = ZlinkStreamContentType.Json
   ): Promise<ZLinkSpotActorJoinResult> {
     throwIfAborted(signal);
     const activation = this.requireActivation(spotId);
     return await this.runLifecycleOperation(activation, async () => {
-      if (this.options.isSpotClosing?.(activation) === true) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestRejected,
-          `User Spot '${String(spotId)}' is closing.`
-        );
-      }
       return await this.admitActorJoinCore(
         activation,
         actor,
@@ -85,41 +78,34 @@ export class ZLinkSpotActorMembership {
     activation: ZLinkSpotActivation,
     actor: ZLinkActor,
     request: Message,
-    commit: (
-      spot: ZLinkSpot
-    ) => Promise<ZLinkActorJoinRollback | void> | ZLinkActorJoinRollback | void,
+    commit: (spot: ZLinkSpot) => Promise<void> | void,
     signal: AbortSignal | undefined,
     leaveSource: (() => Promise<void>) | undefined,
     contentType: string
   ): Promise<ZLinkSpotActorJoinResult> {
     const dispatcher = this.createActorDispatcher(activation);
-    const transaction: {
-      rollbackExternal?: ZLinkActorJoinRollback;
-      rollbackMembership?: () => void;
-      committed: boolean;
-    } = { committed: false };
-    let response: ZLinkSpotActorJoinResult;
-    try {
-      response = await dispatcher.evaluateActorJoin(actor, request, contentType);
-      if (response.accepted) {
+    const response = await dispatcher.evaluateActorJoin(actor, request, contentType);
+    if (response.accepted) {
+      await commit(activation.spot);
+      activation.commitActorJoin(actor);
+      try {
+        await dispatcher.notifyJoinActor(actor);
+      } finally {
         if (leaveSource === undefined) {
-          await this.options.entrySpotCallbacks?.onLeaveActor(actor, signal);
+          void this.options.entrySpotCallbacks?.onLeaveActor(actor, signal).catch((error) => {
+            this.options.dispatchErrors?.report({
+              surface: ZLinkDispatchErrorSurface.SpotActor,
+              messageKind: ZLinkDispatchMessageKind.ActorSend,
+              reason: ZLinkRuntimeDispatchErrorReason.HandlerException,
+              action: ZLinkRuntimeDispatchErrorAction.Drop,
+              actorId: actor.context.actorId,
+              error
+            });
+          });
         } else {
           await leaveSource();
         }
-        await dispatcher.commitActorJoin(actor, async () => {
-          const rollback = await commit(activation.spot);
-          if (rollback !== undefined) transaction.rollbackExternal = rollback;
-          transaction.rollbackMembership = activation.commitActorJoin(actor);
-          transaction.committed = true;
-        });
       }
-    } catch (error) {
-      if (transaction.committed) {
-        transaction.rollbackMembership?.();
-        await transaction.rollbackExternal?.();
-      }
-      throw error;
     }
     return {
       accepted: response.accepted,
@@ -169,24 +155,6 @@ export class ZLinkSpotActorMembership {
         'Spot actor leave requires an Entry Spot node routing id.'
       );
     }
-    const remoteEntry =
-      localEntryNodeRid !== undefined && !routingIdsEqual(entryNodeRid, localEntryNodeRid);
-    if (!remoteEntry) {
-      const leaveSource = async () => {
-        activation.beginActorTransfer(actor.context.actorId);
-        await activation.spot.onLeaveActor(actor);
-        activation.commitActorDeparture(actor.context.actorId);
-        this.options.actorTransferRuntime?.clearRoutedActor(actor);
-      };
-      // A Spot actor handler already owns this activation's serial turn.
-      // Complete its lifecycle transition inside that turn instead of trying
-      // to acquire a second turn for the same owner.
-      if (activation.serial.isCurrentTurn) {
-        await leaveSource();
-      } else {
-        await activation.serial.execute(leaveSource);
-      }
-    }
     const request = RuntimeMessage.from(Buffer.alloc(0));
     try {
       const context = actor.context as typeof actor.context & {

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

@@ -24,7 +24,6 @@ import { createInboundFlow, currentFlowContext, runWithFlow } from '../diagnosti
 import { streamSessionIdFromRoutingId } from '../streams/managed-stream';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors';
 import {
-  actorMessageFollowContext,
   ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
   ZLinkSpotActorDispatcher,
   ZLinkSpotActorHandlerRegistryRuntime
@@ -104,10 +103,6 @@ interface ZLinkSpotActorPacketDispatchOptions {
     | Promise<{ readonly handled: boolean; readonly response?: unknown } | undefined>
     | { readonly handled: boolean; readonly response?: unknown }
     | undefined;
-  readonly onRemoteBoundSessionTarget?: (
-    actorId: string,
-    target: ZLinkRemoteBoundSessionTarget | undefined
-  ) => void;
   readonly onDisconnectActor: (actor: ZLinkActor) => Promise<void>;
   readonly actorResponseSender?: (
     actor: ZLinkActor,
@@ -210,16 +205,6 @@ export class ZLinkSpotActorPacketDispatch {
         ) {
           return undefined;
         }
-        if (
-          remoteBoundSessionTarget !== undefined &&
-          actorMessageFollowContext(fallbackActorRef) === undefined
-        ) {
-          // A replayed handoff/Message Follow packet keeps its captured Session
-          // route solely for that packet's response. It cannot republish the
-          // predecessor route over a binding already confirmed by a later Actor
-          // owner turn.
-          this.options.onRemoteBoundSessionTarget?.(actorId, remoteBoundSessionTarget);
-        }
         const routed = await this.options.routeBeforeLocal?.(delivery);
         if (routed?.handled === true) {
           return routed.response;
@@ -239,7 +224,6 @@ export class ZLinkSpotActorPacketDispatch {
           );
         }
         if (header.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
-          this.options.onRemoteBoundSessionTarget?.(actorId, undefined);
           await this.options.onDisconnectActor(actor);
           return undefined;
         }

package/src/runtime/spots/spot-actor-packet-relay-dispatch.ts

@@ -5,7 +5,7 @@ import {
 import { ZLinkFrameworkException, type ActorRef, type RoutingId } from '../../contracts';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
-import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkRemoteActorPacketTarget } from '../actors';
 import { decodeStreamHeader, messageToBytes, ZLinkStreamMessageKind } from '../streams/protocol';
 import {
   decodeRemoteActorSessionBinding,
@@ -25,8 +25,7 @@ interface ZLinkSpotActorPacketRelayDispatchOptions {
   readonly bindRemoteSession?: (
     actor: ActorRef,
     sourceNodeRid: RoutingId,
-    sourceSessionRid: RoutingId,
-    declaredTarget?: ZLinkRemoteBoundSessionTarget
+    sourceSessionRid: RoutingId
   ) => void;
   readonly flowEnabled?: () => boolean;
 }
@@ -81,18 +80,7 @@ export class ZLinkSpotActorPacketRelayDispatch {
             'Remote actor session binding source did not match the declared session node.'
           );
         }
-        this.options.bindRemoteSession(
-          actorRef,
-          declaredSourceNodeRid,
-          binding.sessionRid,
-          remoteBoundSessionTarget === undefined
-            ? undefined
-            : {
-                ...remoteBoundSessionTarget,
-                sessionNodeRid: declaredSourceNodeRid,
-                sessionRid: binding.sessionRid
-              }
-        );
+        this.options.bindRemoteSession(actorRef, declaredSourceNodeRid, binding.sessionRid);
         if (hasReplyToken(received.replyToken)) {
           submitSpotRouteBridgeReply(received, actorPacketRelay.envelope, {
             ok: true,

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

@@ -26,7 +26,7 @@ import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 
 interface ZLinkEntrySpotContextOptions {
   readonly spotId: SpotId;
-  readonly objectGeneration: number;
+  readonly objectGeneration: bigint;
   readonly nodeRid: RoutingId;
   readonly handlers: ZLinkSpotHandlerRegistry;
   readonly outbound: ZLinkSpotOutbound;
@@ -47,7 +47,7 @@ interface ZLinkEntrySpotContextOptions {
 interface ZLinkSpotContextOptions {
   readonly meshName: string;
   readonly spotId: SpotId;
-  readonly objectGeneration: number;
+  readonly objectGeneration: bigint;
   readonly handlers: ZLinkSpotHandlerRegistry;
   readonly outbound: ZLinkSpotOutbound;
   readonly timers: ZLinkSpotTimerRegistry;
@@ -263,7 +263,7 @@ function withImmutableSpotIdentity<
   T extends {
     readonly meshName: string;
     readonly spotId: SpotId;
-    readonly objectGeneration: number;
+    readonly objectGeneration: bigint;
     readonly nodeRid: RoutingId;
   }
 >(context: T): T {

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

@@ -88,7 +88,6 @@ interface ZLinkEntrySpotActivationOptions {
   readonly spotPublisherClient?: ZLinkSpotPublisherClient;
   readonly routedTransport?: ZLinkSpotRoutedTransport;
   readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
-  readonly channelMeshNameForChannel?: (channelName: string) => string | undefined;
   readonly providerResolver?: ZLinkProviderResolver;
   readonly dispatchErrors?: ZLinkDispatchErrorReporter;
   readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
@@ -99,7 +98,7 @@ interface ZLinkEntrySpotActivationOptions {
   readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
   readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
   readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-  readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+  readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
 }
 
 export class ZLinkEntrySpotActivation {
@@ -121,6 +120,11 @@ export class ZLinkEntrySpotActivation {
   readonly context: ZLinkEntrySpotContext;
 
   constructor(private readonly options: ZLinkEntrySpotActivationOptions) {
+    if ((options.detachedTaskRunner as unknown) === undefined) {
+      throw new ZLinkConfigurationException(
+        'Entry Spot activation requires a detached task runner.'
+      );
+    }
     this.serial = new ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
     this.spotSerialExecutor = new ZLinkSpotSerialExecutor(
       this.serial,
@@ -145,7 +149,7 @@ export class ZLinkEntrySpotActivation {
     this.workerRuntime = options.workerRuntime ?? new ZLinkWorkerRuntime();
     this.context = createEntrySpotContext({
       spotId: String(options.nativeSpot.routingId),
-      objectGeneration: toContextGeneration(entrySpotGeneration(options.nativeSpot)),
+      objectGeneration: entrySpotGeneration(options.nativeSpot),
       nodeRid: options.nodeRid,
       handlers: this.handlers,
       outbound: this.outbound,
@@ -195,8 +199,6 @@ export class ZLinkEntrySpotActivation {
           target.remoteBoundSessionTarget,
           target.fallbackActorRef
         ),
-      onRemoteBoundSessionTarget: (targetActorId, target) =>
-        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
       onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
         this.options.boundSessionRuntime
@@ -325,7 +327,7 @@ export class ZLinkEntrySpotActivation {
     await cleanup(() => this.actorDispatch?.dispose());
     await cleanup(() => this.timers.dispose());
     await cleanup(() => this.spotSerialExecutor.close());
-    await cleanup(() => disposeLifecycleHandlers(this.entrySpot));
+    await cleanup(() => disposeLifecycleHandlers(this.entrySpot, this.options.detachedTaskRunner));
     await cleanup(() => this.options.nativeSpot.dispose());
     if (this.initialized) {
       this.lifecycleMetrics.closed('entry');
@@ -372,6 +374,10 @@ export class ZLinkEntrySpotActivation {
     }
   }
 
+  executeActor<T>(actorId: string, operation: () => Promise<T>): Promise<T> {
+    return this.spotSerialExecutor.executeActor(actorId, operation);
+  }
+
   /**
    * Entry Spot membership does not have an application admission callback.
    * The shared core round-trip therefore accepts a valid returning Actor and
@@ -393,7 +399,6 @@ export class ZLinkEntrySpotActivation {
                 kind: 'enabled',
                 runtime: this.options.actorTransferRuntime
               },
-        commitNativeActor: (actor) => this.commitEntryActorTransaction(actor),
         commitTransferredActor: async (actor, backlog) => {
           await this.commitEntryActorTransaction(actor);
           return await this.replayActorBacklog(actor, backlog);
@@ -401,23 +406,10 @@ export class ZLinkEntrySpotActivation {
       },
       packets: {
         handle: (delivery) => this.dispatchActorPacket(delivery),
-        bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => {
+        bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
           if (routingIdsEqual(sourceNodeRid, this.options.nativeNode.routingId)) {
             return;
           }
-          const target =
-            declaredTarget ??
-            this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(
-              sourceNodeRid,
-              sourceSessionRid
-            );
-          if (target !== undefined) {
-            this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(actor.actorId, {
-              ...target,
-              sessionNodeRid: sourceNodeRid,
-              sessionRid: sourceSessionRid
-            });
-          }
           this.options.nativeNode.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
         },
         replyNoBind: (info, parts, result) => this.replyActorNoBind(info, parts, result)
@@ -549,15 +541,6 @@ function notifyEntryActorJoined(entrySpot: ZLinkEntrySpot, actor: ZLinkActor): P
   return callback === undefined ? Promise.resolve() : callback.call(entrySpot, actor);
 }
 
-function toContextGeneration(generation: bigint): number {
-  if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
-    throw new ZLinkConfigurationException(
-      `Entry Spot object generation '${generation}' cannot be represented by the Node.js public context.`
-    );
-  }
-  return Number(generation);
-}
-
 function entrySpotGeneration(spot: ZLinkBackendSpot): bigint {
   return (
     spot.lifecycleGeneration ??

package/src/runtime/spots/spot-lifecycle-metrics.ts

@@ -1,3 +1,4 @@
+import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
 import type { ZLinkRuntimeMetrics } from '../diagnostics';
 
 export type ZLinkSpotMetricKind = 'entry' | 'user';
@@ -6,10 +7,10 @@ export class ZLinkSpotLifecycleMetrics {
   constructor(private readonly metrics?: ZLinkRuntimeMetrics) {}
 
   opened(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change('zlink.spot.count', 1, { kind });
+    this.metrics?.change(METRIC_NAMES.SpotCount, 1, { kind });
   }
 
   closed(kind: ZLinkSpotMetricKind): void {
-    this.metrics?.change('zlink.spot.count', -1, { kind });
+    this.metrics?.change(METRIC_NAMES.SpotCount, -1, { kind });
   }
 }

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

@@ -1,12 +1,8 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind,
-  wireReplyFailureException
-} from '../framework-errors-internal';
 import { randomUUID } from 'node:crypto';
 import {
+  type ZLinkMessageSerializer,
   ZLinkFrameworkException,
+  ZLinkSpotKind,
   type RoutingId,
   type SpotId,
   type SpotRef,
@@ -15,20 +11,26 @@ import {
   type ZLinkSpotCreateCall,
   type ZLinkSpotCreateResult,
   type ZLinkSpotGetOrCreateCall,
-  type ZLinkSpotManager,
-  ZLinkSpotKind
+  type ZLinkSpotManager
 } from '../../contracts';
-import type { ZLinkMessageSerializer } from '../../contracts';
+
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
 import type { ZLinkObjectFactoryRegistration } from '../../contracts/Configuration/RegistrationTypes';
 import { ZLinkConfigurationException } from '../configuration';
-import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
-import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
-import type { DefaultZLinkSpotManager } from './index';
-import { encodeFrameworkCreationPayload } from '../messaging/creation-payload-codec';
-import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
+import { captureZLinkSpotSerialTurn, requireZLinkYieldTurn } from '../execution';
 import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  wireReplyFailureException
+} from '../framework-errors-internal';
+import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
 import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
-import { captureZLinkSpotSerialTurn, requireZLinkYieldTurn } from '../execution';
+import { encodeFrameworkCreationPayload } from '../messaging/creation-payload-codec';
+import type { DefaultZLinkSpotManager } from './index';
+import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
 
 export interface ZLinkPublicSpotManagerOptions {
   readonly local: DefaultZLinkSpotManager;
@@ -331,8 +333,10 @@ function selectFactory(
 
 function requireText(value: string, label: string): string {
   const bytes = Buffer.byteLength(value);
-  if (bytes < 1 || bytes > 255 || value.includes('\0')) {
-    throw invalidConfiguration(`${label} must contain 1..255 UTF-8 bytes and no NUL.`);
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES || value.includes('\0')) {
+    throw invalidConfiguration(
+      `${label} must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes and no NUL.`
+    );
   }
   return value;
 }