@zlink-systems/framework 0.32.0 → 0.32.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.32.0",
+  "version": "0.32.2",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.32.0",
+    "@zlink-systems/stream-wire": "0.32.2",
     "@zlink-systems/zlink": "1.23.0"
   }
 }

package/src/runtime/actors/actor-context.ts

@@ -97,7 +97,7 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
   }
 
   get objectGeneration(): bigint {
-    return this.state.nativeActorRef?.generation ?? 1n;
+    return this.state.currentActorRef().generation;
   }
 
   get spotId(): SpotId | undefined {

package/src/runtime/actors/actor-creation.ts

@@ -211,7 +211,7 @@ export class ZLinkActorCreationCoordinator {
         await this.options.locationLifecycle?.setActorRef(
           actorType,
           actorId,
-          { actorId, objectGeneration: 1n, meshName, nodeRid },
+          toFrameworkActorRef(state.currentActorRef(), meshName),
           0n
         );
       }

package/src/runtime/actors/actor-runtime-state.ts

@@ -9,6 +9,7 @@ import {
 
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
+import { ZLinkConfigurationException } from '../configuration';
 import { isStructuralGuardEnabled } from '../execution/state-lane';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -172,7 +173,9 @@ export class ZLinkActorRuntimeState {
   private spotIdValue: RoutingId | undefined;
   private spotGenerationValue: bigint | undefined;
   private spotMembershipEpochValue = 0n;
+  // Preserve the exact incarnation until teardown finalization, even after native removal.
   private nativeActorRefValue: ZLinkBackendActorRef | undefined;
+  private nativeActorDestroyed = false;
   private entryNodeRidValue: RoutingId | undefined;
   boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
   private remoteActorPacketTargetValue: ZLinkRemoteActorPacketTarget | undefined;
@@ -228,6 +231,15 @@ export class ZLinkActorRuntimeState {
     return this.nativeActorRefValue;
   }
 
+  currentActorRef(): ZLinkBackendActorRef {
+    if (this.nativeActorRefValue === undefined) {
+      throw new ZLinkConfigurationException(
+        `Actor '${this.actorId}' lifecycle identity is not initialized.`
+      );
+    }
+    return this.nativeActorRefValue;
+  }
+
   get boundSessionBindingGeneration(): bigint {
     return this.boundSessionValue?.bindingGeneration ?? 0n;
   }
@@ -355,24 +367,26 @@ export class ZLinkActorRuntimeState {
       );
     }
 
-    const task = Promise.resolve().then(() => destroy(actorRef));
+    const task = Promise.resolve()
+      .then(() => destroy(this.nativeActorDestroyed ? undefined : actorRef))
+      .catch((error: unknown) => {
+        // A caller may start another attempt only after this attempt has failed.
+        if (this.destroyTask === task) {
+          this.destroyTask = undefined;
+          this.movingValue = false;
+        }
+        throw error;
+      });
     this.destroyTask = task;
     return task;
   }
 
   markNativeActorDestroyed(actorRef: ZLinkBackendActorRef): void {
     if (this.nativeActorRefValue === actorRef) {
-      this.nativeActorRefValue = undefined;
+      this.nativeActorDestroyed = true;
     }
   }
 
-  clearFailedDestroy(task: Promise<void>): void {
-    if (this.destroyTask === task) {
-      this.destroyTask = undefined;
-    }
-    this.movingValue = false;
-  }
-
   ensureContext(createContext: () => ZLinkActorContext): ZLinkActorContext {
     this.context ??= createContext();
     return this.context;
@@ -425,6 +439,7 @@ export class ZLinkActorRuntimeState {
       this.createRequestPayloadValue = undefined;
       this.configured = false;
       this.nativeActorRefValue = undefined;
+      this.nativeActorDestroyed = false;
       this.entryNodeRidValue = undefined;
       return true;
     }
@@ -474,6 +489,7 @@ export class ZLinkActorRuntimeState {
 
   setNativeActorRef(actorRef: ZLinkBackendActorRef): void {
     this.nativeActorRefValue = actorRef;
+    this.nativeActorDestroyed = false;
     this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
   }
 
@@ -556,6 +572,7 @@ export class ZLinkActorRuntimeState {
     this.spotGenerationValue = undefined;
     this.spotMembershipEpochValue = 0n;
     this.nativeActorRefValue = undefined;
+    this.nativeActorDestroyed = false;
     this.entryNodeRidValue = undefined;
     this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;
@@ -578,6 +595,7 @@ export class ZLinkActorRuntimeState {
     this.spotValue = undefined;
     this.spotIdValue = undefined;
     this.nativeActorRefValue = undefined;
+    this.nativeActorDestroyed = false;
     // The arriving relocation installs the binding it carries.
     this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;

package/src/runtime/actors/index.ts

@@ -40,7 +40,6 @@ import {
 } from './actor-runtime-state';
 import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-rollback';
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
-const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 
 export { DefaultZLinkActorClient, type ZLinkActorClientOptions } from './actor-client';
 export { DefaultZLinkActorContext, ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME } from './actor-context';
@@ -167,7 +166,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     throwIfAborted(signal);
     if (this.relocationStaged.has(actorId)) return undefined;
     const state = this.states.get(actorId);
-    if (state?.actor !== undefined) {
+    if (state?.actor !== undefined && state.nativeActorRef !== undefined) {
       return this.actorRefForState(state);
     }
     return await this.options.actorRefResolver?.resolveActorRef(actorId, signal);
@@ -182,7 +181,12 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   async findSpot(actorId: string, signal?: AbortSignal): Promise<SpotRef | undefined> {
     throwIfAborted(signal);
     const state = this.states.get(actorId);
-    if (state?.actor === undefined || state.spotId === undefined) return undefined;
+    if (
+      state?.actor === undefined ||
+      state.spotId === undefined ||
+      state.nativeActorRef === undefined
+    )
+      return undefined;
     const spotId = state.spotId;
     const actorRef = this.actorRefForState(state);
     return {
@@ -249,12 +253,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         await this.finalizeDestroyedActor(actor.actorId, state);
       })
     );
-    try {
-      await this.awaitActorDestroy(state, destroyTask);
-    } catch (error) {
-      state.clearFailedDestroy(destroyTask);
-      throw error;
-    }
+    await this.awaitActorDestroy(state, destroyTask);
     return true;
   }
 
@@ -362,9 +361,10 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     if (result.status === 'failed') {
       throw actorApplicationFailure(actorId, result.error);
     }
+    const actorRef = result.actorRef ?? this.actorRefForState(this.states.get(actorId)!);
     return result.reply === undefined
-      ? { status: result.status, actor: result.actorRef }
-      : { status: result.status, actor: result.actorRef, reply: result.reply };
+      ? { status: result.status, actor: actorRef }
+      : { status: result.status, actor: actorRef, reply: result.reply };
   }
 
   private ensureActorTypeBelongsToMesh(meshName: string, actorType: string): void {
@@ -638,7 +638,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     actorType: string,
     createRequest?: unknown,
     signal?: AbortSignal
-  ): Promise<ZLinkActorLocalCreateResult> {
+  ): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>> {
     this.rememberActorMeshFromType(actorId, actorType);
     return await this.createOrGet(actorId, actorType, false, createRequest, signal);
   }
@@ -651,7 +651,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     nativeActorRef?: ZLinkBackendActorRef
   ): Promise<ZLinkActorLocalCreateResult> {
     this.rememberActorMeshFromType(actorId, actorType);
-    return await this.createOrGet(
+    const result = await this.createOrGet(
       actorId,
       actorType,
       false,
@@ -661,6 +661,11 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       DEFAULT_REQUEST_TIMEOUT_MS,
       nativeActorRef
     );
+    if (result.status === 'failed' || result.status === 'rejected') return result;
+    return {
+      ...result,
+      actorRef: this.actorRefForState(this.states.get(actorId)!)
+    };
   }
 
   adoptCreatedAuthority(
@@ -712,7 +717,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) =>
       this.terminateActor(state, async () => {
         const destroyedActorRef =
-          actorRef === undefined ? undefined : toFrameworkActorRef(actorRef, state.meshName ?? '');
+          state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
         if (actorRef !== undefined) {
           await node.destroyActor(actorRef, 0, destroySignal);
           state.markNativeActorDestroyed(actorRef);
@@ -728,12 +733,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       })
     );
 
-    try {
-      await this.awaitActorDestroy(state, destroyTask);
-    } catch (error) {
-      state.clearFailedDestroy(destroyTask);
-      throw error;
-    }
+    await this.awaitActorDestroy(state, destroyTask);
   }
 
   private async createOrGet(
@@ -745,7 +745,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     claimLocation = true,
     timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     nativeActorRef?: ZLinkBackendActorRef
-  ): Promise<ZLinkActorLocalCreateResult> {
+  ): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>> {
     const deadline = performance.now() + timeoutMs;
     const requestedMeshName = this.actorMeshNames.get(actorId);
     for (;;) {
@@ -801,7 +801,8 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       try {
         const result = await operation.task;
         if (result.status === 'created') {
-          const actorRef = this.actorRefForState(state);
+          const actorRef =
+            state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
           return {
             status: operation.created ? 'created' : 'existing',
             actor: result.actor,
@@ -886,16 +887,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   }
 
   private actorRefForState(state: ZLinkActorRuntimeState): ActorRef {
-    const nativeActorRef = state.nativeActorRef;
-    if (nativeActorRef !== undefined) {
-      return toFrameworkActorRef(nativeActorRef, state.meshName ?? '');
-    }
-    return {
-      actorId: state.actorId,
-      objectGeneration: 1n,
-      meshName: state.meshName ?? '',
-      nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
-    };
+    return toFrameworkActorRef(state.currentActorRef(), state.meshName ?? '');
   }
 }
 
@@ -994,11 +986,11 @@ class ZLinkActorGetOrCreateCallRuntime
   extends ZLinkActorCreateCallRuntime
   implements ZLinkActorGetOrCreateCall {}
 
-export type ZLinkActorLocalCreateResult =
+export type ZLinkActorLocalCreateResult<TActorRef extends ActorRef | undefined = ActorRef> =
   | {
       readonly status: 'existing' | 'created';
       readonly actor: ZLinkActor;
-      readonly actorRef: ActorRef;
+      readonly actorRef: TActorRef;
       readonly reply?: unknown;
     }
   | {
@@ -1010,7 +1002,10 @@ export type ZLinkActorLocalCreateResult =
       readonly error: unknown;
     };
 
-function requireCreatedActor(result: ZLinkActorLocalCreateResult, actorId: string): ZLinkActor {
+function requireCreatedActor(
+  result: ZLinkActorLocalCreateResult<ActorRef | undefined>,
+  actorId: string
+): ZLinkActor {
   if (result.status === 'existing' || result.status === 'created') return result.actor;
   if (result.status === 'failed') {
     throw actorApplicationFailure(actorId, result.error);

package/src/runtime/host/entry-actor-runtime.ts

@@ -1,15 +1,12 @@
-import type { ApplicationJobOrigin } from '../application-jobs/contracts';
-import type { ZLinkActorRequestTerminal } from '../spots/spot-actor-packet-dispatch';
-import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
 import type { ActorRef, ZLinkActor } from '../../contracts';
-import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendSpotNode } from '../backend';
-import type { DefaultZLinkActorManager, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { DefaultZLinkActorManager } from '../actors';
 import { ZLinkPostCommitActorBinder } from '../actors/post-commit-actor-binder';
 import type { DefaultZLinkSpotManager, ZLinkSpotNodeRuntimeManager } from '../spots';
 import type { ZLinkEntryActorRuntime } from '../spots/spot-runtime-ports';
 import type { ZLinkStreamActorLifecyclePort } from '../streams/stream-binding-runtime-ports';
 import type { ZLinkBoundSessionRelay } from './bound-session-relay';
+import type { ZLinkActorIngressMembership } from '../spots/spot-actor-ingress-admission';
 
 export interface ZLinkEntryActorRuntimeOptions {
   readonly actorManager: () => DefaultZLinkActorManager | undefined;
@@ -87,35 +84,8 @@ export class ZLinkEntryActorRuntimeService implements ZLinkEntryActorRuntime {
     await this.requireActorManager().destroyActor(node, entryNodeRid, actor, signal);
   }
 
-  routePacket(
-    actorId: string,
-    parts: readonly Message[],
-    returnResponse?: boolean,
-    remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget,
-    fallbackActorRef?: ActorRef,
-    origin: ApplicationJobOrigin = 'remote',
-    requestTerminal?: ZLinkActorRequestTerminal,
-    messageFollowOrigin?: ZLinkMessageFollowOrigin
-  ): { readonly handled: boolean; readonly response?: unknown } {
-    const spotManager = this.options.spotManager();
-    const spotId = this.options.actorManager()?.getState(actorId)?.spotId;
-    if (spotId === undefined || spotManager === undefined) {
-      return { handled: false };
-    }
-    return {
-      handled: true,
-      response: spotManager.dispatchRoutedActorPacket(
-        origin,
-        spotId,
-        actorId,
-        parts,
-        returnResponse,
-        remoteBoundSessionTarget,
-        fallbackActorRef,
-        requestTerminal,
-        messageFollowOrigin
-      )
-    };
+  get actorIngressMembership(): ZLinkActorIngressMembership | undefined {
+    return this.options.spotManager()?.actorIngressMembership;
   }
 
   private requireActorManager(): DefaultZLinkActorManager {

package/src/runtime/host/spot-runtime-options-factory.ts

@@ -315,7 +315,8 @@ export class ZLinkSpotRuntimeOptionsFactory {
           state?.meshName === undefined ? undefined : this.meshNodeRoutingId(state.meshName);
         if (
           state?.actor === undefined ||
-          state.remoteActorPacketTarget !== undefined ||
+          (state.remoteActorPacketTarget !== undefined &&
+            !routingIdsEqual(state.remoteActorPacketTarget.targetNodeRid, localNodeRid)) ||
           actorRef === undefined ||
           localNodeRid === undefined ||
           !routingIdsEqual(actorRef.nodeRid, localNodeRid)

package/src/runtime/locations/actor-location-claims.ts

@@ -426,30 +426,30 @@ export class ZLinkActorLocationClaims {
     const current = await store.readAuthority(key);
     if (!matchesActorAuthority(current, actorRef, ownerToken)) return;
 
-    const result = await store.compareExchangeAuthority(key, current.storeVersion, {
+    let result = await store.compareExchangeAuthority(key, current.storeVersion, {
       kind: 'delete'
     });
-    if (
-      result.kind === 'deleted' ||
-      (result.kind === 'conflict' && result.current.kind === 'missing')
-    ) {
-      return;
-    }
     if (
       result.kind === 'conflict' &&
       result.current.kind === 'snapshot' &&
       matchesActorAuthority(result.current, actorRef, ownerToken)
     ) {
-      const retry = await store.compareExchangeAuthority(key, result.current.storeVersion, {
+      result = await store.compareExchangeAuthority(key, result.current.storeVersion, {
         kind: 'delete'
       });
-      if (
-        retry.kind === 'deleted' ||
-        (retry.kind === 'conflict' && retry.current.kind === 'missing')
-      ) {
-        return;
-      }
     }
+    if (
+      result.kind === 'deleted' ||
+      (result.kind === 'conflict' && result.current.kind === 'missing')
+    ) {
+      return;
+    }
+    throw new ZLinkFrameworkException(
+      result.kind === 'conflict'
+        ? classifyMembershipAuthorityFailure(result.current, actorRef)
+        : ZLinkFrameworkErrorKind.InternalFailure,
+      `Actor '${actorId}' authority release was rejected with status ${result.kind}.`
+    );
   }
 }
 

package/src/runtime/spots/index.ts

@@ -4,6 +4,11 @@ import { encodeActorReply } from '../actors/actor-reply';
 import { boundSessionErrorPayload } from '../streams/bound-session-response-target';
 import { RELOCATED_REQUEST_OWNED_BY_REQUESTER } from '../actors/actor-handoff';
 import { routingIdsEqual } from '../routing-id';
+import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
+import type {
+  ZLinkActorDispatchOwner,
+  ZLinkActorIngressMembership
+} from './spot-actor-ingress-admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { dispatchReasonFromError } from '../diagnostics/dispatch-error-details';
 import type {
@@ -231,10 +236,7 @@ export interface ZLinkSpotManagerOptions {
     meshName: string,
     spotType: Type<ZLinkSpot>
   ) => import('../../contracts').ZLinkSpotRelocationCoordinationMode;
-  readonly actorDispatchOwnerResolver?: (actorId: string) => {
-    readonly actorRef?: ActorRef;
-    readonly spotId?: RoutingId;
-  };
+  readonly actorDispatchOwnerResolver?: (actorId: string) => ZLinkActorDispatchOwner;
   readonly channelClient?: ZLinkChannelClient;
   readonly fanoutClient?: ZLinkFanoutClient;
   readonly spotPublisherClient?: ZLinkSpotPublisherClient;
@@ -337,6 +339,7 @@ interface ZLinkTargetSpotCloseOperation {
 }
 
 export class DefaultZLinkSpotManager {
+  readonly actorIngressMembership: ZLinkActorIngressMembership;
   [inspectRuntime]() {
     return Object.freeze({
       activeActivationCount: this.activations.activeActivations().length,
@@ -414,6 +417,10 @@ export class DefaultZLinkSpotManager {
       spotRouteResolver: options.spotRouteResolver,
       actorTransferRuntime: options.actorTransferRuntime
     });
+    this.actorIngressMembership = {
+      resolveOwner: options.actorDispatchOwnerResolver,
+      dispatchToOwner: (spotId, delivery) => this.dispatchActorPacketToOwner(spotId, delivery)
+    };
     this.activationLifecycle = new ZLinkSpotActivationLifecycle({
       timerClock,
       spotTimerHandlers: options.spotTimerHandlers,
@@ -444,6 +451,7 @@ export class DefaultZLinkSpotManager {
       createTopicMessage: options.createTopicMessage,
       nativeSpotNodeProvider: options.nativeSpotNodeProvider,
       actorResolver: options.actorResolver,
+      actorIngressMembership: this.actorIngressMembership,
       detachedTaskRunner: options.detachedTaskRunner,
       actorTransferRuntime: options.actorTransferRuntime,
       boundSessionRuntime: options.boundSessionRuntime,
@@ -1628,6 +1636,28 @@ export class DefaultZLinkSpotManager {
     );
   }
 
+  private dispatchActorPacketToOwner(
+    spotId: RoutingId | undefined,
+    delivery: ZLinkActorPacketDelivery
+  ): Promise<unknown> {
+    const args = [
+      delivery.actorId,
+      delivery.parts,
+      delivery.returnResponse,
+      delivery.remoteBoundSessionTarget,
+      delivery.fallbackActorRef,
+      delivery.requestTerminal,
+      delivery.messageFollowOrigin
+    ] as const;
+    if (spotId !== undefined) {
+      return this.dispatchRoutedActorPacket(delivery.origin, spotId, ...args);
+    }
+    if (this.options.dispatchEntryActorPacket === undefined) {
+      throw new ZLinkConfigurationException('Actor ingress requires an Entry FIFO port.');
+    }
+    return this.options.dispatchEntryActorPacket(delivery.origin, ...args);
+  }
+
   /** @internal Replays a record already owned by the Actor handoff queue. */
   dispatchRoutedActorPacketDirect(
     origin: ApplicationJobOrigin,

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

@@ -82,6 +82,7 @@ import type {
 } from './spot-actor-join-dispatch';
 import { ZLinkSpotActorAdmissionCoordinator } from './spot-actor-admission-coordinator';
 import type { ZLinkRouteToActorJoinPrewarm } from './spot-actor-packet-dispatch';
+import type { ZLinkActorIngressMembership } from './spot-actor-ingress-admission';
 import { ZLinkSpotActivation } from './spot-activation-state';
 import type { ZLinkSpotLocationClaim } from './spot-location-claim';
 import type {
@@ -132,6 +133,7 @@ export interface ZLinkSpotActivationLifecycleOptions {
   readonly createTopicMessage?: () => ZLinkBackendTopicMessage;
   readonly nativeSpotNodeProvider?: (meshName: string) => ZLinkBackendSpotNode | undefined;
   readonly actorResolver?: (actorId: string) => ZLinkActor | undefined;
+  readonly actorIngressMembership?: ZLinkActorIngressMembership;
   readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
   readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
   readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;

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

@@ -25,6 +25,7 @@ type AdmissionOptions = Pick<
   | 'actorHandoffRuntime'
   | 'admission'
   | 'actorResolver'
+  | 'actorIngressMembership'
   | 'actorTransferRuntime'
   | 'boundSessionRuntime'
   | 'detachedTaskRunner'
@@ -225,7 +226,8 @@ export class ZLinkSpotActorAdmissionCoordinator {
         this.options.actorResolver === undefined
           ? activation.resolveJoinedActor(targetActorId)
           : this.options.actorResolver(targetActorId),
-      hasDepartedActor: (targetActorId) => activation.hasDepartedActor(targetActorId),
+      membershipSpotId: activation.spotId,
+      membership: this.options.actorIngressMembership,
       onDisconnectActor: (actor) =>
         activation.serial.execute(() => activation.spot.onDisconnectActor?.(actor)),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(

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

@@ -1,5 +1,6 @@
 import { actorMessageFollowContext } from '../actors/actor-message-follow-context';
-import type { ActorRef, ZLinkActor } from '../../contracts';
+import type { ActorRef, RoutingId, ZLinkActor } from '../../contracts';
+import { routingIdsEqual } from '../routing-id';
 import type { Message } from '../../contracts/Common/Message';
 import type {
   ZLinkActorPacketDelivery,
@@ -30,9 +31,18 @@ export type ZLinkRouteToActorJoinPrewarm = (
   }
 ) => 'parked' | 'not-found';
 
-export type ZLinkActorIngressRoute = (
-  delivery: ZLinkActorPacketDelivery
-) => { readonly handled: boolean; readonly response?: unknown } | undefined;
+export interface ZLinkActorDispatchOwner {
+  readonly actorRef?: ActorRef;
+  readonly spotId?: RoutingId;
+}
+
+export interface ZLinkActorIngressMembership {
+  readonly resolveOwner?: (actorId: string) => ZLinkActorDispatchOwner;
+  readonly dispatchToOwner?: (
+    spotId: RoutingId | undefined,
+    delivery: ZLinkActorPacketDelivery
+  ) => Promise<unknown>;
+}
 
 export type ZLinkActorIngressAdmission =
   | { readonly kind: 'local'; readonly actor: ZLinkActor }
@@ -45,9 +55,9 @@ export function resolveActorIngress(
   request: boolean,
   options: {
     readonly handoffRuntime?: ZLinkSpotActorHandoffRuntime;
-    readonly routeBeforeLocal?: ZLinkActorIngressRoute;
+    readonly spotId?: RoutingId;
+    readonly membership?: ZLinkActorIngressMembership;
     readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
-    readonly hasDepartedActor?: (actorId: string) => boolean;
     readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
   }
 ): ZLinkActorIngressAdmission {
@@ -62,12 +72,20 @@ export function resolveActorIngress(
     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 membership = options.membership;
+  const owner = membership?.resolveOwner?.(delivery.actorId);
+  if (owner?.actorRef !== undefined && !routingIdsEqual(owner.spotId, options.spotId)) {
+    if (membership?.dispatchToOwner === undefined) {
+      throw new Error('Actor ingress requires the current membership dispatch port.');
+    }
+    // Transfer the accepted delivery before releasing the source FIFO claim.
+    // Its terminal is awaited outside that claim by dispatchActorPacketInMailbox.
+    return { kind: 'follow', terminal: membership.dispatchToOwner(owner.spotId, delivery) };
+  }
   const actor =
-    options.hasDepartedActor?.(delivery.actorId) === true
-      ? undefined
-      : options.resolveActor(delivery.actorId);
+    membership?.resolveOwner === undefined || owner?.actorRef !== undefined
+      ? options.resolveActor(delivery.actorId)
+      : undefined;
   if (actor !== undefined) return { kind: 'local', actor };
   if (
     options.routeToActorJoinPrewarm !== undefined &&

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

@@ -1,7 +1,7 @@
 import {
   resolveActorIngress,
   type ZLinkRouteToActorJoinPrewarm,
-  type ZLinkActorIngressRoute
+  type ZLinkActorIngressMembership
 } from './spot-actor-ingress-admission';
 import type { ZLinkSpotActorHandoffRuntime } from './spot-runtime-ports';
 import { DefaultZLinkActorContext } from '../actors/actor-context';
@@ -97,8 +97,8 @@ interface ZLinkSpotActorPacketDispatchOptions {
   readonly spotId: () => string;
   readonly registry: ZLinkSpotActorHandlerRegistryRuntime;
   readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
-  readonly hasDepartedActor?: (actorId: string) => boolean;
-  readonly routeBeforeLocal?: ZLinkActorIngressRoute;
+  readonly membershipSpotId?: RoutingId;
+  readonly membership?: ZLinkActorIngressMembership;
   readonly onDisconnectActor: (actor: ZLinkActor) => Promise<void>;
   readonly actorResponseSender?: (
     actor: ZLinkActor,
@@ -226,9 +226,9 @@ export class ZLinkSpotActorPacketDispatch {
           messageKind === ZLinkDispatchMessageKind.ActorRequest,
           {
             handoffRuntime,
-            routeBeforeLocal: this.options.routeBeforeLocal,
+            spotId: this.options.membershipSpotId,
+            membership: this.options.membership,
             resolveActor: this.options.resolveActor,
-            hasDepartedActor: this.options.hasDepartedActor,
             routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
           }
         );

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

@@ -196,17 +196,7 @@ export class ZLinkEntrySpotActivation {
       spotId: () => String(this.options.nativeSpot.routingId),
       registry: this.actorHandlers,
       resolveActor: (targetActorId) => this.options.entryActorRuntime?.resolveActor(targetActorId),
-      routeBeforeLocal: (delivery) =>
-        this.options.entryActorRuntime?.routePacket(
-          delivery.actorId,
-          delivery.parts,
-          delivery.returnResponse,
-          delivery.remoteBoundSessionTarget,
-          delivery.fallbackActorRef,
-          delivery.origin,
-          delivery.requestTerminal,
-          delivery.messageFollowOrigin
-        ),
+      membership: this.options.entryActorRuntime?.actorIngressMembership,
       onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
         this.options.boundSessionRuntime