@zlink-systems/framework 0.32.0 → 0.32.2

package/dist/runtime/actors/actor-context.js

@@ -59,7 +59,7 @@ class DefaultZLinkActorContext {
         return this.state.boundSession;
     }
     get objectGeneration() {
-        return this.state.nativeActorRef?.generation ?? 1n;
+        return this.state.currentActorRef().generation;
     }
     get spotId() {
         return this.state.spotId;

package/dist/runtime/actors/actor-creation.js

@@ -116,7 +116,7 @@ class ZLinkActorCreationCoordinator {
                 }
             }
             else if (nodeRid !== undefined && updateLocation) {
-                await this.options.locationLifecycle?.setActorRef(actorType, actorId, { actorId, objectGeneration: 1n, meshName, nodeRid }, 0n);
+                await this.options.locationLifecycle?.setActorRef(actorType, actorId, (0, actor_runtime_state_1.toFrameworkActorRef)(state.currentActorRef(), meshName), 0n);
             }
             return { status: 'created', actor, reply: response.reply };
         }

package/dist/runtime/actors/actor-runtime-state.d.ts

@@ -76,6 +76,7 @@ export declare class ZLinkActorRuntimeState {
     private spotGenerationValue;
     private spotMembershipEpochValue;
     private nativeActorRefValue;
+    private nativeActorDestroyed;
     private entryNodeRidValue;
     boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
     private remoteActorPacketTargetValue;
@@ -96,6 +97,7 @@ export declare class ZLinkActorRuntimeState {
     get spotMembershipEpoch(): bigint;
     get spotGeneration(): bigint | undefined;
     get nativeActorRef(): ZLinkBackendActorRef | undefined;
+    currentActorRef(): ZLinkBackendActorRef;
     get boundSessionBindingGeneration(): bigint;
     get entryNodeRid(): RoutingId | undefined;
     /** The one current Session binding of this Actor (Session–Actor binding §6). */
@@ -124,7 +126,6 @@ export declare class ZLinkActorRuntimeState {
     setOwnerLeaseGeneration(generation: bigint): void;
     getOrStartDestroy(entryNodeRid: RoutingId, destroy: (actorRef: ZLinkBackendActorRef | undefined) => Promise<void>): Promise<void>;
     markNativeActorDestroyed(actorRef: ZLinkBackendActorRef): void;
-    clearFailedDestroy(task: Promise<void>): void;
     ensureContext(createContext: () => ZLinkActorContext): ZLinkActorContext;
     getOrStartCreation(actorType: string, failIfExists: boolean, createActor: () => Promise<ZLinkActorCreationAttemptResult>): ZLinkActorCreationOperation;
     clearFailedCreation(task: Promise<ZLinkActorCreationAttemptResult>): boolean;

package/dist/runtime/actors/actor-runtime-state.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorRuntimeState = void 0;
 exports.toFrameworkRoutingId = toFrameworkRoutingId;
 exports.toFrameworkActorRef = toFrameworkActorRef;
+const configuration_1 = require("../configuration");
 const state_lane_1 = require("../execution/state-lane");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const routing_id_1 = require("../routing-id");
@@ -57,7 +58,9 @@ class ZLinkActorRuntimeState {
     spotIdValue;
     spotGenerationValue;
     spotMembershipEpochValue = 0n;
+    // Preserve the exact incarnation until teardown finalization, even after native removal.
     nativeActorRefValue;
+    nativeActorDestroyed = false;
     entryNodeRidValue;
     boundSessionValue;
     remoteActorPacketTargetValue;
@@ -103,6 +106,12 @@ class ZLinkActorRuntimeState {
     get nativeActorRef() {
         return this.nativeActorRefValue;
     }
+    currentActorRef() {
+        if (this.nativeActorRefValue === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${this.actorId}' lifecycle identity is not initialized.`);
+        }
+        return this.nativeActorRefValue;
+    }
     get boundSessionBindingGeneration() {
         return this.boundSessionValue?.bindingGeneration ?? 0n;
     }
@@ -194,20 +203,23 @@ class ZLinkActorRuntimeState {
             !(0, routing_id_1.routingIdsEqual)(toFrameworkRoutingId(actorRef.nodeRid), entryNodeRid)) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${this.actorId}' is not owned by this Entry Spot.`);
         }
-        const task = Promise.resolve().then(() => destroy(actorRef));
+        const task = Promise.resolve()
+            .then(() => destroy(this.nativeActorDestroyed ? undefined : actorRef))
+            .catch((error) => {
+            // 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) {
         if (this.nativeActorRefValue === actorRef) {
-            this.nativeActorRefValue = undefined;
-        }
-    }
-    clearFailedDestroy(task) {
-        if (this.destroyTask === task) {
-            this.destroyTask = undefined;
+            this.nativeActorDestroyed = true;
         }
-        this.movingValue = false;
     }
     ensureContext(createContext) {
         this.context ??= createContext();
@@ -243,6 +255,7 @@ class ZLinkActorRuntimeState {
             this.createRequestPayloadValue = undefined;
             this.configured = false;
             this.nativeActorRefValue = undefined;
+            this.nativeActorDestroyed = false;
             this.entryNodeRidValue = undefined;
             return true;
         }
@@ -278,6 +291,7 @@ class ZLinkActorRuntimeState {
     }
     setNativeActorRef(actorRef) {
         this.nativeActorRefValue = actorRef;
+        this.nativeActorDestroyed = false;
         this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
     }
     /** @internal Installs one authority-confirmed binding inside its Actor owner turn. */
@@ -344,6 +358,7 @@ class ZLinkActorRuntimeState {
         this.spotGenerationValue = undefined;
         this.spotMembershipEpochValue = 0n;
         this.nativeActorRefValue = undefined;
+        this.nativeActorDestroyed = false;
         this.entryNodeRidValue = undefined;
         this.boundSessionValue = undefined;
         this.remoteActorPacketTargetValue = undefined;
@@ -366,6 +381,7 @@ 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/dist/runtime/actors/index.d.ts

@@ -64,7 +64,7 @@ export declare class DefaultZLinkActorManager implements ZLinkActorManager {
     private awaitActorDestroy;
     getOrCreateActor(actorId: string, actorType: string, signal?: AbortSignal): Promise<ZLinkActor>;
     getOrCreateWithNativeRef(actorId: string, actorType: string, actorRef: ZLinkBackendActorRef, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActor>;
-    getOrCreateActorResult(actorId: string, actorType: string, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActorLocalCreateResult>;
+    getOrCreateActorResult(actorId: string, actorType: string, createRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>>;
     createReservedActorResult(actorId: string, actorType: string, createRequest: unknown, signal?: AbortSignal, nativeActorRef?: ZLinkBackendActorRef): Promise<ZLinkActorLocalCreateResult>;
     adoptCreatedAuthority(actorId: string, authorityOwnerGeneration: bigint, ownerLeaseGeneration: bigint): void;
     getState(actorId: string): ZLinkActorRuntimeState | undefined;
@@ -77,10 +77,10 @@ export declare class DefaultZLinkActorManager implements ZLinkActorManager {
     private getOrCreateState;
     private actorRefForState;
 }
-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;
 } | {
     readonly status: 'rejected';

package/dist/runtime/actors/index.js

@@ -17,7 +17,6 @@ const actor_creation_1 = require("./actor-creation");
 const actor_runtime_state_1 = require("./actor-runtime-state");
 const transferred_actor_rollback_1 = require("./transferred-actor-rollback");
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
-const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 var actor_client_1 = require("./actor-client");
 Object.defineProperty(exports, "DefaultZLinkActorClient", { enumerable: true, get: function () { return actor_client_1.DefaultZLinkActorClient; } });
 var actor_context_1 = require("./actor-context");
@@ -100,7 +99,7 @@ class DefaultZLinkActorManager {
         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);
@@ -111,7 +110,9 @@ class DefaultZLinkActorManager {
     async findSpot(actorId, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const state = this.states.get(actorId);
-        if (state?.actor === undefined || state.spotId === undefined)
+        if (state?.actor === undefined ||
+            state.spotId === undefined ||
+            state.nativeActorRef === undefined)
             return undefined;
         const spotId = state.spotId;
         const actorRef = this.actorRefForState(state);
@@ -162,13 +163,7 @@ class DefaultZLinkActorManager {
             }
             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;
     }
     async materializeTransferredActor(actorId, actorType, adapterKey, transferState, signal) {
@@ -235,9 +230,10 @@ class DefaultZLinkActorManager {
         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 };
     }
     ensureActorTypeBelongsToMesh(meshName, actorType) {
         const registeredMesh = this.options.actorMeshNameProvider?.(actorType);
@@ -442,7 +438,13 @@ class DefaultZLinkActorManager {
     }
     async createReservedActorResult(actorId, actorType, createRequest, signal, nativeActorRef) {
         this.rememberActorMeshFromType(actorId, actorType);
-        return await this.createOrGet(actorId, actorType, false, createRequest, signal, false, Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef);
+        const result = await this.createOrGet(actorId, actorType, false, createRequest, signal, false, Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef);
+        if (result.status === 'failed' || result.status === 'rejected')
+            return result;
+        return {
+            ...result,
+            actorRef: this.actorRefForState(this.states.get(actorId))
+        };
     }
     adoptCreatedAuthority(actorId, authorityOwnerGeneration, ownerLeaseGeneration) {
         const state = this.states.get(actorId);
@@ -473,7 +475,7 @@ class DefaultZLinkActorManager {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.context.actorId}' must leave its current SPOT before destroy.`);
         }
         const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) => this.terminateActor(state, async () => {
-            const destroyedActorRef = actorRef === undefined ? undefined : (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, state.meshName ?? '');
+            const destroyedActorRef = state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
             if (actorRef !== undefined) {
                 await node.destroyActor(actorRef, 0, destroySignal);
                 state.markNativeActorDestroyed(actorRef);
@@ -483,13 +485,7 @@ class DefaultZLinkActorManager {
             }
             await this.finalizeDestroyedActor(actor.context.actorId, state);
         }));
-        try {
-            await this.awaitActorDestroy(state, destroyTask);
-        }
-        catch (error) {
-            state.clearFailedDestroy(destroyTask);
-            throw error;
-        }
+        await this.awaitActorDestroy(state, destroyTask);
     }
     async createOrGet(actorId, actorType, failIfExists, request, signal, claimLocation = true, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef) {
         const deadline = performance.now() + timeoutMs;
@@ -533,7 +529,7 @@ class DefaultZLinkActorManager {
             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,
@@ -602,16 +598,7 @@ class DefaultZLinkActorManager {
         return state;
     }
     actorRefForState(state) {
-        const nativeActorRef = state.nativeActorRef;
-        if (nativeActorRef !== undefined) {
-            return (0, actor_runtime_state_1.toFrameworkActorRef)(nativeActorRef, state.meshName ?? '');
-        }
-        return {
-            actorId: state.actorId,
-            objectGeneration: 1n,
-            meshName: state.meshName ?? '',
-            nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
-        };
+        return (0, actor_runtime_state_1.toFrameworkActorRef)(state.currentActorRef(), state.meshName ?? '');
     }
 }
 exports.DefaultZLinkActorManager = DefaultZLinkActorManager;

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/locations/actor-location-claims.js

@@ -311,24 +311,23 @@ 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 Errors_1.ZLinkFrameworkException(result.kind === 'conflict'
+            ? classifyMembershipAuthorityFailure(result.current, actorRef)
+            : Errors_1.ZLinkFrameworkErrorKind.InternalFailure, `Actor '${actorId}' authority release was rejected with status ${result.kind}.`);
     }
 }
 exports.ZLinkActorLocationClaims = ZLinkActorLocationClaims;

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;