@zlink-systems/framework 0.32.1 → 0.32.2

package/dist/runtime/host/entry-actor-runtime.d.ts

@@ -1,14 +1,11 @@
-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 { ZLinkBackendSpotNode } from '../backend';
-import type { DefaultZLinkActorManager, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { DefaultZLinkActorManager } from '../actors';
 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;
     readonly spotManager: () => DefaultZLinkSpotManager | undefined;
@@ -26,9 +23,6 @@ export declare class ZLinkEntryActorRuntimeService implements ZLinkEntryActorRun
     releaseMembers(meshName: string): Promise<void>;
     commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
     destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: ActorRef['nodeRid'], actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
-    routePacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, origin?: ApplicationJobOrigin, requestTerminal?: ZLinkActorRequestTerminal, messageFollowOrigin?: ZLinkMessageFollowOrigin): {
-        readonly handled: boolean;
-        readonly response?: unknown;
-    };
+    get actorIngressMembership(): ZLinkActorIngressMembership | undefined;
     private requireActorManager;
 }

package/dist/runtime/host/entry-actor-runtime.js

@@ -61,16 +61,8 @@ class ZLinkEntryActorRuntimeService {
     async destroyActor(node, entryNodeRid, actor, signal) {
         await this.requireActorManager().destroyActor(node, entryNodeRid, actor, signal);
     }
-    routePacket(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, origin = 'remote', requestTerminal, messageFollowOrigin) {
-        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() {
+        return this.options.spotManager()?.actorIngressMembership;
     }
     requireActorManager() {
         const manager = this.options.actorManager();

package/dist/runtime/host/spot-runtime-options-factory.js

@@ -165,7 +165,8 @@ class ZLinkSpotRuntimeOptionsFactory {
                     : (0, actors_1.toFrameworkActorRef)(state.nativeActorRef, state.meshName ?? '');
                 const localNodeRid = state?.meshName === undefined ? undefined : this.meshNodeRoutingId(state.meshName);
                 if (state?.actor === undefined ||
-                    state.remoteActorPacketTarget !== undefined ||
+                    (state.remoteActorPacketTarget !== undefined &&
+                        !(0, routing_id_1.routingIdsEqual)(state.remoteActorPacketTarget.targetNodeRid, localNodeRid)) ||
                     actorRef === undefined ||
                     localNodeRid === undefined ||
                     !(0, routing_id_1.routingIdsEqual)(actorRef.nodeRid, localNodeRid)) {

package/dist/runtime/spots/index.d.ts

@@ -1,4 +1,5 @@
 import { inspectRuntime } from '../internal-observation';
+import type { ZLinkActorDispatchOwner, ZLinkActorIngressMembership } from './spot-actor-ingress-admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, Type, ZLinkMessageSerializer, ZLinkInstanceSpot, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkSpot, ZLinkSpotActorJoinResult, ZLinkSpotInfo, ZLinkSpotPublisherClient } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -73,10 +74,7 @@ export interface ZLinkSpotManagerOptions {
     readonly releaseActorMembers?: (meshName: string, spotId: RoutingId) => Promise<void>;
     readonly userSpotExecutionMode?: (meshName: string, spotType: Type<ZLinkSpot>) => import('../../contracts').ZLinkUserSpotExecutionMode;
     readonly userSpotRelocationCoordinationMode?: (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;
@@ -139,6 +137,7 @@ interface ZLinkTargetSpotCloseOperation {
 }
 export declare class DefaultZLinkSpotManager {
     private readonly options;
+    readonly actorIngressMembership: ZLinkActorIngressMembership;
     [inspectRuntime](): Readonly<{
         activeActivationCount: number;
         hasCloseableActivation: (meshName: string, spotId: RoutingId) => boolean;
@@ -225,6 +224,7 @@ export declare class DefaultZLinkSpotManager {
     cancelActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     notifyJoinedSpotActorDisconnected(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<boolean>;
     dispatchRoutedActorPacket(origin: ApplicationJobOrigin, spotId: RoutingId, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    private dispatchActorPacketToOwner;
     /** Resolves the current Actor FIFO owner for both Entry and User membership. */
     admitSourceActorPacketPrefix(actorId: string, records: readonly ZLinkActorHandoffPrefixRecord[]): ZLinkActorHandoffPrefixAdmission;
     /** Runs an owner-side lifecycle decision in the Actor's existing execution gate. */

package/dist/runtime/spots/index.js

@@ -69,6 +69,7 @@ var spot_manager_public_1 = require("./spot-manager-public");
 Object.defineProperty(exports, "ZLinkPublicSpotManager", { enumerable: true, get: function () { return spot_manager_public_1.ZLinkPublicSpotManager; } });
 class DefaultZLinkSpotManager {
     options;
+    actorIngressMembership;
     [internal_observation_1.inspectRuntime]() {
         return Object.freeze({
             activeActivationCount: this.activations.activeActivations().length,
@@ -133,6 +134,10 @@ class DefaultZLinkSpotManager {
             spotRouteResolver: options.spotRouteResolver,
             actorTransferRuntime: options.actorTransferRuntime
         });
+        this.actorIngressMembership = {
+            resolveOwner: options.actorDispatchOwnerResolver,
+            dispatchToOwner: (spotId, delivery) => this.dispatchActorPacketToOwner(spotId, delivery)
+        };
         this.activationLifecycle = new spot_activation_1.ZLinkSpotActivationLifecycle({
             timerClock,
             spotTimerHandlers: options.spotTimerHandlers,
@@ -163,6 +168,7 @@ class DefaultZLinkSpotManager {
             createTopicMessage: options.createTopicMessage,
             nativeSpotNodeProvider: options.nativeSpotNodeProvider,
             actorResolver: options.actorResolver,
+            actorIngressMembership: this.actorIngressMembership,
             detachedTaskRunner: options.detachedTaskRunner,
             actorTransferRuntime: options.actorTransferRuntime,
             boundSessionRuntime: options.boundSessionRuntime,
@@ -920,6 +926,24 @@ class DefaultZLinkSpotManager {
         }
         return this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
+    dispatchActorPacketToOwner(spotId, delivery) {
+        const args = [
+            delivery.actorId,
+            delivery.parts,
+            delivery.returnResponse,
+            delivery.remoteBoundSessionTarget,
+            delivery.fallbackActorRef,
+            delivery.requestTerminal,
+            delivery.messageFollowOrigin
+        ];
+        if (spotId !== undefined) {
+            return this.dispatchRoutedActorPacket(delivery.origin, spotId, ...args);
+        }
+        if (this.options.dispatchEntryActorPacket === undefined) {
+            throw new configuration_1.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, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
         const activation = this.activations.resolveUnique(spotId);

package/dist/runtime/spots/spot-activation.d.ts

@@ -15,6 +15,7 @@ import { type ZLinkSpotAddressTransport, type ZLinkSpotRoutedTransport } from '.
 import { type ZLinkTimerClock, type ZLinkTimerRelocationState } from './spot-timer';
 import type { ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
 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 { ZLinkSpotActorHandoffRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
@@ -49,6 +50,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/dist/runtime/spots/spot-actor-admission-coordinator.d.ts

@@ -8,7 +8,7 @@ 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';
-type AdmissionOptions = Pick<ZLinkSpotActivationLifecycleOptions, 'actorHandoffRuntime' | 'admission' | 'actorResolver' | 'actorTransferRuntime' | 'boundSessionRuntime' | 'detachedTaskRunner' | 'dispatchErrors' | 'locationClaim' | 'messageSerializers' | 'nativeSpotNodeProvider' | 'createTopicMessage' | 'providerResolver' | 'runtimeEventPublisher' | 'routeToActorJoinPrewarm'>;
+type AdmissionOptions = Pick<ZLinkSpotActivationLifecycleOptions, 'actorHandoffRuntime' | 'admission' | 'actorResolver' | 'actorIngressMembership' | 'actorTransferRuntime' | 'boundSessionRuntime' | 'detachedTaskRunner' | 'dispatchErrors' | 'locationClaim' | 'messageSerializers' | 'nativeSpotNodeProvider' | 'createTopicMessage' | 'providerResolver' | 'runtimeEventPublisher' | 'routeToActorJoinPrewarm'>;
 export declare class ZLinkSpotActorAdmissionCoordinator {
     private readonly options;
     constructor(options: AdmissionOptions);

package/dist/runtime/spots/spot-actor-admission-coordinator.js

@@ -96,7 +96,8 @@ class ZLinkSpotActorAdmissionCoordinator {
             resolveActor: (targetActorId) => 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(this.options.boundSessionRuntime),
             actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),

package/dist/runtime/spots/spot-actor-ingress-admission.d.ts

@@ -1,4 +1,4 @@
-import type { ActorRef, ZLinkActor } from '../../contracts';
+import type { ActorRef, RoutingId, ZLinkActor } from '../../contracts';
 import type { ZLinkActorPacketDelivery, ZLinkActorRequestTerminal } from './spot-actor-packet-dispatch';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
@@ -16,10 +16,14 @@ export type ZLinkRouteToActorJoinPrewarm = (actorId: string, objectGeneration: b
     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 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;
@@ -33,8 +37,8 @@ export type ZLinkActorIngressAdmission = {
 /** Fixes one packet owner synchronously at the Actor FIFO head. */
 export declare function resolveActorIngress(delivery: ZLinkActorPacketDelivery, 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;

package/dist/runtime/spots/spot-actor-ingress-admission.js

@@ -2,18 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveActorIngress = resolveActorIngress;
 const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
+const routing_id_1 = require("../routing-id");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 /** Fixes one packet owner synchronously at the Actor FIFO head. */
 function resolveActorIngress(delivery, request, options) {
     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);
+    const membership = options.membership;
+    const owner = membership?.resolveOwner?.(delivery.actorId);
+    if (owner?.actorRef !== undefined && !(0, routing_id_1.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 = membership?.resolveOwner === undefined || owner?.actorRef !== undefined
+        ? options.resolveActor(delivery.actorId)
+        : undefined;
     if (actor !== undefined)
         return { kind: 'local', actor };
     if (options.routeToActorJoinPrewarm !== undefined &&

package/dist/runtime/spots/spot-actor-packet-dispatch.d.ts

@@ -1,4 +1,4 @@
-import { type ZLinkRouteToActorJoinPrewarm, type ZLinkActorIngressRoute } from './spot-actor-ingress-admission';
+import { type ZLinkRouteToActorJoinPrewarm, type ZLinkActorIngressMembership } from './spot-actor-ingress-admission';
 import type { ZLinkSpotActorHandoffRuntime } from './spot-runtime-ports';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, ZLinkActor, ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
@@ -38,8 +38,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, packetName: string, requestSeq: bigint, response: unknown, replyOptions: ZLinkActorResponseOptions, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, signal?: AbortSignal) => Promise<void> | void;
     readonly actorErrorSender?: (actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef) => Promise<void> | void;

package/dist/runtime/spots/spot-actor-packet-dispatch.js

@@ -80,9 +80,9 @@ class ZLinkSpotActorPacketDispatch {
                 : undefined;
             const admitted = (0, spot_actor_ingress_admission_1.resolveActorIngress)(delivery, messageKind === ZLinkDispatchOptions_1.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
             });
             if ('terminal' in admitted)

package/dist/runtime/spots/spot-entry-activation.js

@@ -100,7 +100,7 @@ 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),
             actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),

package/dist/runtime/spots/spot-runtime-ports.d.ts

@@ -7,15 +7,13 @@ import type { ZLinkActorHandoffDispatch } from '../actors/actor-handoff';
 import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
 import type { ZLinkRemoteActorJoinActor, ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
 import type { ZLinkBackendSpotNode } from '../backend/contracts';
+import type { ZLinkActorIngressMembership } from './spot-actor-ingress-admission';
 export interface ZLinkEntryActorRuntime {
+    readonly actorIngressMembership?: ZLinkActorIngressMembership;
     releaseMembers?(meshName: string): Promise<void>;
     resolveActor(actorId: string): ZLinkActor | undefined;
     commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
     destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
-    routePacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, origin?: ApplicationJobOrigin, requestTerminal?: import('./spot-actor-packet-dispatch').ZLinkActorRequestTerminal, messageFollowOrigin?: ZLinkMessageFollowOrigin): {
-        readonly handled: boolean;
-        readonly response?: unknown;
-    };
 }
 export interface ZLinkSpotActorTransferRuntime {
     prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.32.1",
+  "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.1",
+    "@zlink-systems/stream-wire": "0.32.2",
     "@zlink-systems/zlink": "1.23.0"
   }
 }

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/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