@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,3 +1,4 @@
+import { inspectRuntime } from '../internal-observation';
 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';
@@ -9,7 +10,7 @@ export { ZLinkSpotActorAdmissionCoordinator } from './spot-actor-admission-coord
 import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from './spot-routing-internal';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import { ZLinkMessage, ZLinkFrameworkRuntimeState } from '../../contracts';
+import { ZLinkMessage, ZLinkFrameworkRuntimeState, ZLinkSpotCloseReason } from '../../contracts';
 import { type ZLinkRuntimeEventPublisher } from '../diagnostics';
 import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
 import type { ZLinkBackendSpot, ZLinkBackendSpotNode } from '../backend/contracts';
@@ -26,9 +27,11 @@ export { DefaultZLinkSpotOutbound, type ZLinkSpotAddressCallOptions, type ZLinkS
 import { type ZLinkSpotRoutedTransport } from './spot-outbound';
 export { DefaultZLinkSpotHandlerRegistry, type ZLinkSpotHandlerRegistration } from './spot-handler-registry';
 export { ZLinkRuntimeSpotPublisherTransport } from './spot-publisher-transport';
+import { ZLinkSpotActivationRegistry } from './spot-activation-registry';
 import type { ZLinkSpotActivation } from './spot-activation-state';
 import type { ZLinkSpotPreparationCompletion } from './spot-serial-executor';
 import { type ZLinkNativeSpotAuthority } from './spot-activation';
+import { ZLinkFormalRemoteActorAdmissionRegistry } from './formal-remote-actor-admission-registry';
 import type { ZLinkSpotActorHandoffRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
 import type { ZLinkRuntimeAdmissionGate, ZLinkMeshDispatchAdmission } from '../admission';
 import type { ZLinkActivationAdmission } from '../activation-admission';
@@ -40,6 +43,7 @@ export { ZLinkEntrySpotActivation } from './spot-entry-activation';
 export { createFrameworkEntrySpotId, registrationAcceptsNewActor, ZLinkSpotNodeRuntimeManager, type ZLinkSpotNodeRuntimeManagerOptions } from './spot-node-runtime-manager';
 export { ZLinkPublicSpotManager, type ZLinkPublicSpotManagerOptions } from './spot-manager-public';
 export interface ZLinkSpotManagerOptions {
+    readonly defaultRequestTimeoutMs?: number;
     readonly spotFactories: readonly Type<ZLinkSpot>[];
     readonly instanceSpotFactories?: ReadonlyMap<string, ReadonlyMap<string, Type<ZLinkInstanceSpot>>>;
     readonly instanceSpotIdleTimeoutMs?: ReadonlyMap<string, number>;
@@ -124,20 +128,33 @@ export interface ZLinkSpotManagerOptions {
     };
     readonly activationAdmission?: ZLinkActivationAdmission;
 }
+interface ZLinkTargetSpotCloseOperation {
+    readonly activation: ZLinkSpotActivation;
+    readonly reason: ZLinkSpotCloseReason;
+    readonly beginAuthority: (onCommitted: () => void) => Promise<import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority | undefined>;
+    authority?: import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority;
+    authorityDecision?: Promise<void>;
+    ready?: Promise<boolean>;
+    canExecuteApplication?(record: import('../execution/serial-execution-queue').ZLinkSerialWorkRecord<unknown>): boolean;
+}
 export declare class DefaultZLinkSpotManager {
     private readonly options;
+    [inspectRuntime](): Readonly<{
+        activeActivationCount: number;
+        hasCloseableActivation: (meshName: string, spotId: RoutingId) => boolean;
+    }>;
     private readonly factories;
-    private readonly activations;
+    readonly activations: ZLinkSpotActivationRegistry;
     private readonly workerRuntime;
     private readonly locationClaim;
     private readonly routedSpotPackets;
     private readonly actorMembership;
     private readonly activationLifecycle;
     private readonly formalRemoteTransfers;
-    private readonly formalRemoteActorAdmissions;
+    readonly formalRemoteActorAdmissions: ZLinkFormalRemoteActorAdmissionRegistry;
     private readonly pendingInstanceMaterializations;
     private readonly pendingInstanceMaterializationsByPrefix;
-    private readonly closeOperations;
+    readonly closeOperations: Map<string, ZLinkTargetSpotCloseOperation>;
     private readonly pendingInstanceTerminals;
     private readonly pendingInstanceTerminalGenerations;
     private readonly deferredInstanceAuthorityReleases;
@@ -187,7 +204,7 @@ export declare class DefaultZLinkSpotManager {
     list(meshName: string): Promise<readonly ZLinkSpotInfo[]>;
     drainForShutdown(meshName: string, signal?: AbortSignal, deadline?: Date): Promise<void>;
     close(meshName: string, spotId: RoutingId, signal?: AbortSignal): Promise<boolean>;
-    closeUserWithAuthority(meshName: string, spotId: RoutingId, beginAuthority: (onCommitted: () => void) => Promise<import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority>, signal?: AbortSignal): Promise<boolean>;
+    closeUserWithAuthority(meshName: string, spotId: RoutingId, beginAuthority: (onCommitted: () => void) => Promise<import('../locations/spot-location-claims').ZLinkInstanceClosingAuthority>, signal?: AbortSignal, deadline?: Date): Promise<boolean>;
     private closeFromContext;
     private closeWithReason;
     private runCloseOperation;
@@ -207,9 +224,11 @@ export declare class DefaultZLinkSpotManager {
     beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     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): Promise<unknown>;
+    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>;
     /** 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. */
+    executeActorTurn<T>(meshName: string, spotId: RoutingId | undefined, actorId: string, operation: () => Promise<T>): Promise<T>;
     dispatchRoutedSpotSend(spotId: RoutingId, packetName: string | undefined, message: unknown, context: {
         readonly channelName: string;
         readonly contentType?: string;
@@ -232,7 +251,9 @@ export declare class DefaultZLinkSpotManager {
     private traceInstanceMessage;
     dispatchMeshActor(origin: ApplicationJobOrigin, meshName: string, owner: ReadyRecord, record: ReceiveRecord, admit?: ZLinkMeshDispatchAdmission): Promise<void>;
     dispatchMeshActorJoin(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
-    private dispatchMeshActorJoinCore;
+    dispatchMeshActorJoinCore(meshName: string, owner: ReadyRecord, record: ReceiveRecord, replyState: {
+        targetCommitPublished: boolean;
+    }): Promise<void>;
     dispatchMeshSpotControl(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<void>;
     private dispatchMeshSpotControlCore;
     completeFormalSourceLeaveTerminal(actorId: string, transferId: string, succeeded: boolean): Promise<boolean>;

package/dist/runtime/spots/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkSpotManager = exports.ZLinkPublicSpotManager = exports.ZLinkSpotNodeRuntimeManager = exports.registrationAcceptsNewActor = exports.createFrameworkEntrySpotId = exports.ZLinkEntrySpotActivation = exports.ZLinkRuntimeSpotPublisherTransport = exports.DefaultZLinkSpotHandlerRegistry = exports.DefaultZLinkSpotOutbound = exports.ZLinkSpotTimerRegistry = exports.ZLinkManagedTimer = exports.ZLinkSpotSerialExecutor = exports.ZLinkSpotSerialTurnExecutor = exports.ZLinkSpotActorAdmissionCoordinator = exports.ZLinkSpotRoutedBoundSessionDispatch = exports.sendToSpotHandle = exports.requestToSpotHandle = exports.resolveSpotHandle = exports.createSpotHandle = void 0;
+const internal_observation_1 = require("../internal-observation");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const actor_reply_1 = require("../actors/actor-reply");
 const bound_session_response_target_1 = require("../streams/bound-session-response-target");
 const actor_handoff_1 = require("../actors/actor-handoff");
@@ -67,6 +69,12 @@ 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;
+    [internal_observation_1.inspectRuntime]() {
+        return Object.freeze({
+            activeActivationCount: this.activations.activeActivations().length,
+            hasCloseableActivation: (meshName, spotId) => this.activations.activationForClose(meshName, spotId) !== undefined
+        });
+    }
     factories;
     activations;
     workerRuntime;
@@ -629,8 +637,8 @@ class DefaultZLinkSpotManager {
     async close(meshName, spotId, signal) {
         return await this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose);
     }
-    async closeUserWithAuthority(meshName, spotId, beginAuthority, signal) {
-        return await this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose, undefined, beginAuthority);
+    async closeUserWithAuthority(meshName, spotId, beginAuthority, signal, deadline) {
+        return await this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline, beginAuthority);
     }
     closeFromContext(activation, objectGeneration, signal) {
         const { meshName, spotId } = activation;
@@ -650,6 +658,9 @@ class DefaultZLinkSpotManager {
         return this.closeWithReason(meshName, spotId, signal, contracts_1.ZLinkSpotCloseReason.ExplicitClose, undefined, beginUserAuthority, activation);
     }
     async closeWithReason(meshName, spotId, signal, reason = contracts_1.ZLinkSpotCloseReason.ExplicitClose, deadline, beginUserAuthority, contextActivation) {
+        if (reason === contracts_1.ZLinkSpotCloseReason.ExplicitClose) {
+            deadline ??= new Date(Date.now() + (this.options.defaultRequestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS));
+        }
         requireMeshName(meshName);
         const key = `${meshName}\0${String(spotId)}`;
         let operation = this.closeOperations.get(key);
@@ -902,12 +913,12 @@ class DefaultZLinkSpotManager {
     async notifyJoinedSpotActorDisconnected(spotId, actor, signal) {
         return await this.actorMembership.notifyJoinedActorDisconnected(spotId, actor, signal);
     }
-    dispatchRoutedActorPacket(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+    dispatchRoutedActorPacket(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         const activation = this.activations.resolveUnique(spotId);
         if (activation === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Spot '${spotId}' is not active.`);
         }
-        return this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+        return this.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
     /** @internal Replays a record already owned by the Actor handoff queue. */
     dispatchRoutedActorPacketDirect(origin, spotId, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
@@ -939,6 +950,20 @@ class DefaultZLinkSpotManager {
         }
         return this.admitRoutedActorPacketPrefix(owner.spotId, actorId, records);
     }
+    /** Runs an owner-side lifecycle decision in the Actor's existing execution gate. */
+    executeActorTurn(meshName, spotId, actorId, operation) {
+        if (spotId === undefined) {
+            if (this.options.executeEntryActor === undefined) {
+                throw new configuration_1.ZLinkConfigurationException(`Entry Spot Actor '${actorId}' has no execution gate for MeshNode '${meshName}'.`);
+            }
+            return this.options.executeEntryActor(meshName, actorId, operation);
+        }
+        const activation = this.resolveApplicationActivation(spotId, meshName);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' has no active Spot execution gate for '${String(spotId)}'.`);
+        }
+        return activation.executeActor(actorId, operation);
+    }
     async dispatchRoutedSpotSend(spotId, packetName, message, context) {
         await this.routedSpotPackets.send(spotId, packetName, message, context);
     }
@@ -967,7 +992,7 @@ class DefaultZLinkSpotManager {
         const codecs = this.options.messageSerializers === undefined
             ? undefined
             : { serializers: this.options.messageSerializers };
-        const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+        const decodePayload = (messageType) => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs, messageType);
         const context = {
             channelName: envelope.header.channelName,
             contentType: envelope.header.contentType,
@@ -1040,7 +1065,7 @@ class DefaultZLinkSpotManager {
                     const codecs = this.options.messageSerializers === undefined
                         ? undefined
                         : { serializers: this.options.messageSerializers };
-                    const decodePayload = () => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+                    const decodePayload = (messageType) => (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs, messageType);
                     const context = {
                         channelName: envelope.header.channelName,
                         contentType: envelope.header.contentType,

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

@@ -13,6 +13,7 @@ export interface ZLinkSpotCloseOperation {
     readonly started: boolean;
 }
 export declare class ZLinkSpotActivationRegistry {
+    private readonly metrics?;
     private nextId;
     private readonly activations;
     private readonly staged;
@@ -20,9 +21,9 @@ export declare class ZLinkSpotActivationRegistry {
     private readonly closing;
     private readonly failedClose;
     private readonly emptyWaiters;
-    private readonly lifecycleMetrics;
     private activeScan;
-    constructor(metrics?: import('../diagnostics').ZLinkRuntimeMetrics);
+    constructor(metrics?: import("../diagnostics").ZLinkRuntimeMetrics | undefined);
+    private recordPopulation;
     allocateSpotId(meshName: string): RoutingId;
     resolve(meshName: string, spotId: RoutingId): ZLinkSpotActivation | undefined;
     resolveUnique(spotId: RoutingId): ZLinkSpotActivation | undefined;

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

@@ -4,11 +4,11 @@ exports.ZLinkSpotActivationRegistry = exports.ZLinkSpotActivation = void 0;
 const contracts_1 = require("../../contracts");
 const abort_1 = require("../abort");
 const framework_errors_internal_1 = require("../framework-errors-internal");
-const spot_lifecycle_metrics_1 = require("./spot-lifecycle-metrics");
 const DEFAULT_ACTIVE_ACTIVATION_BATCH_SIZE = 64;
 var spot_activation_state_1 = require("./spot-activation-state");
 Object.defineProperty(exports, "ZLinkSpotActivation", { enumerable: true, get: function () { return spot_activation_state_1.ZLinkSpotActivation; } });
 class ZLinkSpotActivationRegistry {
+    metrics;
     nextId = 1;
     activations = new Map();
     staged = new Set();
@@ -16,10 +16,12 @@ class ZLinkSpotActivationRegistry {
     closing = new Map();
     failedClose = new Set();
     emptyWaiters = new Set();
-    lifecycleMetrics;
     activeScan;
     constructor(metrics) {
-        this.lifecycleMetrics = new spot_lifecycle_metrics_1.ZLinkSpotLifecycleMetrics(metrics);
+        this.metrics = metrics;
+    }
+    recordPopulation(activation, delta) {
+        this.metrics?.recordSpotCount(activation.meshName, activation.domain.kind, delta);
     }
     allocateSpotId(meshName) {
         let spotId;
@@ -60,8 +62,11 @@ class ZLinkSpotActivationRegistry {
     }
     finishClose(meshName, spotId) {
         const key = spotActivationKey(meshName, spotId);
-        if (this.activations.delete(key))
-            this.lifecycleMetrics.closed('user');
+        const activation = this.activations.get(key);
+        if (activation !== undefined) {
+            this.activations.delete(key);
+            this.recordPopulation(activation, -1);
+        }
         this.staged.delete(key);
         this.failedClose.delete(key);
         this.resolveEmptyWaiters();
@@ -124,7 +129,7 @@ class ZLinkSpotActivationRegistry {
         }
         if (existing === undefined) {
             this.activations.set(key, activation);
-            this.lifecycleMetrics.opened('user');
+            this.recordPopulation(activation, 1);
         }
         return this.staged.has(key) ? undefined : activation;
     }
@@ -147,7 +152,7 @@ class ZLinkSpotActivationRegistry {
         this.activations.delete(key);
         this.staged.delete(key);
         this.failedClose.delete(key);
-        this.lifecycleMetrics.closed('user');
+        this.recordPopulation(activation, -1);
         this.resolveEmptyWaiters();
         return activation;
     }
@@ -182,7 +187,7 @@ class ZLinkSpotActivationRegistry {
                 if (completed || resourcesReleased(activation)) {
                     this.activations.delete(key);
                     this.staged.delete(key);
-                    this.lifecycleMetrics.closed('user');
+                    this.recordPopulation(activation, -1);
                     this.failedClose.delete(key);
                 }
                 else {

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

@@ -8,6 +8,7 @@ import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 import { ZLinkSpotSerialExecutor } from './spot-serial-executor';
 import type { ZLinkSpotTimerRegistry } from './spot-timer';
 import type { ZLinkSpotActorJoinDispatch } from './spot-actor-join-dispatch';
+import type { ZLinkSpotActorPacketDispatch } from './spot-actor-packet-dispatch';
 import { ZLinkExecutionBarrier, type ZLinkExecutionBarrierSeal } from '../execution';
 import type { ZLinkTimerRelocationState } from './spot-timer';
 export type ZLinkSpotActivationDomain = {
@@ -54,6 +55,7 @@ export declare class ZLinkSpotActivation {
     readonly nativeSpot?: ZLinkBackendSpot;
     readonly executionBarrier: ZLinkExecutionBarrier;
     actorDispatch?: ZLinkSpotActorJoinDispatch;
+    actorPacketDispatch?: ZLinkSpotActorPacketDispatch;
     private readonly joinedActors;
     private readonly departedActorIds;
     private readonly externalActorCount;

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

@@ -21,6 +21,7 @@ class ZLinkSpotActivation {
     nativeSpot;
     executionBarrier;
     actorDispatch;
+    actorPacketDispatch;
     joinedActors = new Map();
     departedActorIds = new Set();
     externalActorCount;

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

@@ -1,12 +1,13 @@
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
-import type { ActorRef } from '../../contracts';
+import type { ActorRef, ZLinkActor } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
 import type { ZLinkBackendSpot } from '../backend/contracts';
-import { type ZLinkRemoteBoundSessionTarget } from '../actors';
+import { type ZLinkActorHandoffPacket, type ZLinkActorHandoffResult, type ZLinkRemoteBoundSessionTarget } from '../actors';
 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'>;
 export declare class ZLinkSpotActorAdmissionCoordinator {
     private readonly options;
@@ -14,8 +15,12 @@ export declare class ZLinkSpotActorAdmissionCoordinator {
     dispatchActorPacket(origin: ApplicationJobOrigin, activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     attachNativeActorJoinDispatch(activation: ZLinkSpotActivation, nativeSpot: ZLinkBackendSpot | undefined): ZLinkSpotActorJoinDispatch | undefined;
     private dispatchActorPacketInActorTurn;
-    private resolveActor;
-    private commitTransferredActorTransaction;
+    private actorPacketDispatch;
+    /** Resolves native lifecycle records; messages use resolveActorIngress. */
+    private resolveLifecycleActor;
+    commitTransferredActorTransaction(activation: ZLinkSpotActivation, actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[], sealedSession: ZLinkRemoteBoundSessionTarget | undefined): Promise<readonly ZLinkActorHandoffResult[]>;
     private replayActorBacklog;
 }
+/** Releases the Actor FIFO before awaiting a transferred admission terminal. */
+export declare function dispatchActorPacketInMailbox<TSerial>(enqueue: (operation: (serial: TSerial) => Promise<ZLinkActorPacketExecution>) => Promise<ZLinkActorPacketExecution>, dispatch: (serial: TSerial) => Promise<ZLinkActorPacketExecution>): Promise<unknown>;
 export {};

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorAdmissionCoordinator = void 0;
+exports.dispatchActorPacketInMailbox = dispatchActorPacketInMailbox;
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const actor_handoff_1 = require("../actors/actor-handoff");
 const routing_id_1 = require("../routing-id");
@@ -12,10 +13,16 @@ class ZLinkSpotActorAdmissionCoordinator {
         this.options = options;
     }
     async dispatchActorPacket(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
-        const handoff = this.options.actorHandoffRuntime?.capture(origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin);
-        if (handoff !== undefined)
-            return await handoff;
-        return await this.dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+        return dispatchActorPacketInMailbox((operation) => activation.executeActor(actorId, operation), (serial) => this.actorPacketDispatch(activation).admitDelivery(serial, {
+            origin,
+            actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef,
+            requestTerminal,
+            messageFollowOrigin
+        }, this.options.actorHandoffRuntime));
     }
     attachNativeActorJoinDispatch(activation, nativeSpot) {
         if (nativeSpot === undefined)
@@ -25,7 +32,7 @@ class ZLinkSpotActorAdmissionCoordinator {
             createTopicMessage: requireBackendValueFactory(this.options.createTopicMessage, 'TopicMessage'),
             serial: activation.serial,
             actors: {
-                resolveActor: (actorId) => this.resolveActor(activation, actorId),
+                resolveActor: (actorId) => this.resolveLifecycleActor(activation, actorId),
                 getTarget: () => activation.spot,
                 defaultAccept: false,
                 transfer: this.options.actorTransferRuntime === undefined
@@ -38,7 +45,7 @@ class ZLinkSpotActorAdmissionCoordinator {
                 commitTransferredActor: (actor, backlog, sealedSession) => this.commitTransferredActorTransaction(activation, actor, backlog, sealedSession)
             },
             packets: {
-                handle: (delivery) => this.dispatchActorPacket('remote', activation, delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef),
+                handle: (delivery) => this.dispatchActorPacket('remote', activation, delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef, delivery.requestTerminal, delivery.messageFollowOrigin),
                 bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
                     const node = this.options.nativeSpotNodeProvider?.(activation.meshName);
                     if (node === undefined || (0, routing_id_1.routingIdsEqual)(sourceNodeRid, node.routingId))
@@ -76,13 +83,20 @@ class ZLinkSpotActorAdmissionCoordinator {
         return activation.admitActorPacketPrefix(actorId, records, (actorSerial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.dispatchActorPacketInActorTurn((0, application_job_queue_scope_1.currentApplicationJobOrigin)(), activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef));
     }
     dispatchActorPacketInActorTurn(origin, activation, actorSerial, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
-        return new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
+        return this.actorPacketDispatch(activation).dispatch(actorSerial, origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+    }
+    actorPacketDispatch(activation) {
+        if (activation.actorPacketDispatch !== undefined)
+            return activation.actorPacketDispatch;
+        activation.actorPacketDispatch = new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
+            admission: this.options.admission,
             spot: activation.spot,
             spotId: () => String(activation.spotId),
             registry: activation.actorHandlers,
-            serial: actorSerial,
-            resolveActor: (targetActorId) => this.resolveActor(activation, targetActorId),
-            actorLeft: (targetActorId) => activation.hasDepartedActor(targetActorId),
+            resolveActor: (targetActorId) => this.options.actorResolver === undefined
+                ? activation.resolveJoinedActor(targetActorId)
+                : this.options.actorResolver(targetActorId),
+            hasDepartedActor: (targetActorId) => activation.hasDepartedActor(targetActorId),
             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),
@@ -90,9 +104,11 @@ class ZLinkSpotActorAdmissionCoordinator {
             messageSerializers: this.options.messageSerializers,
             dispatchErrors: this.options.dispatchErrors,
             routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
-        }).dispatch(origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+        });
+        return activation.actorPacketDispatch;
     }
-    resolveActor(activation, actorId) {
+    /** Resolves native lifecycle records; messages use resolveActorIngress. */
+    resolveLifecycleActor(activation, actorId) {
         if (activation.hasDepartedActor(actorId))
             return undefined;
         // The manager owns relocation visibility. Membership alone cannot publish
@@ -150,3 +166,8 @@ function requireBackendValueFactory(factory, valueName) {
         return factory();
     };
 }
+/** Releases the Actor FIFO before awaiting a transferred admission terminal. */
+async function dispatchActorPacketInMailbox(enqueue, dispatch) {
+    const result = await enqueue(dispatch);
+    return 'terminal' in result ? await result.terminal : result.response;
+}

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

@@ -0,0 +1,40 @@
+import type { ActorRef, ZLinkActor } from '../../contracts';
+import type { ZLinkActorPacketDelivery, ZLinkActorRequestTerminal } from './spot-actor-packet-dispatch';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
+import type { ZLinkSpotActorHandoffRuntime } from './spot-runtime-ports';
+import { createInternalFrameworkException } from '../framework-errors-internal';
+/** Parks an exact Actor incarnation while its accepted Join prepares the target. */
+export type ZLinkRouteToActorJoinPrewarm = (actorId: string, objectGeneration: bigint, arrival: {
+    readonly origin: ApplicationJobOrigin;
+    readonly header: Buffer;
+    readonly payload: Buffer;
+    readonly returnResponse: boolean;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly fallbackActorRef?: ActorRef;
+    readonly requestTerminal?: ZLinkActorRequestTerminal;
+    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 type ZLinkActorIngressAdmission = {
+    readonly kind: 'local';
+    readonly actor: ZLinkActor;
+} | {
+    readonly kind: 'follow' | 'prewarm';
+    readonly terminal: Promise<unknown>;
+} | {
+    readonly kind: 'stale';
+    readonly error: ReturnType<typeof createInternalFrameworkException>;
+};
+/** 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 resolveActor: (actorId: string) => ZLinkActor | undefined;
+    readonly hasDepartedActor?: (actorId: string) => boolean;
+    readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
+}): ZLinkActorIngressAdmission;

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

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveActorIngress = resolveActorIngress;
+const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
+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);
+    if (actor !== undefined)
+        return { kind: 'local', actor };
+    if (options.routeToActorJoinPrewarm !== undefined &&
+        delivery.fallbackActorRef !== undefined &&
+        (!request || delivery.returnResponse || delivery.requestTerminal !== undefined)) {
+        const parked = parkForActorJoinPrewarm(delivery.origin, options.routeToActorJoinPrewarm, delivery.actorId, delivery.parts, request, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef, delivery.requestTerminal);
+        if (parked !== undefined)
+            return { kind: 'prewarm', terminal: parked };
+    }
+    return {
+        kind: 'stale',
+        error: (0, framework_errors_internal_1.createInternalFrameworkException)((0, actor_message_follow_context_1.actorMessageFollowContext)(delivery.fallbackActorRef) === undefined
+            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound
+            : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `SPOT actor is not registered locally: ${delivery.actorId}`)
+    };
+}
+function parkForActorJoinPrewarm(origin, routeToActorJoinPrewarm, actorId, parts, isRequest, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+    let resolve = () => undefined;
+    let reject = () => undefined;
+    const result = new Promise((res, rej) => {
+        resolve = res;
+        reject = rej;
+    });
+    //  A Request's real reply must still travel through the exact mailbox
+    //  correlation the original caller captured in `requestTerminal` — not
+    //  through this method's own return value, which the caller only uses
+    //  to decide whether it still owes a reply itself. Wrapping keeps that
+    //  reply route intact across the (possibly much later) redelivery at
+    //  migration time while also releasing the original caller once the
+    //  real reply has gone out, so it never sends a premature empty one.
+    const wrappedRequestTerminal = requestTerminal === undefined
+        ? undefined
+        : Object.assign(async (response, preparedReply) => {
+            try {
+                await requestTerminal(response, preparedReply);
+                resolve(undefined);
+            }
+            catch (error) {
+                reject(error);
+                throw error;
+            }
+        }, { prepare: requestTerminal.prepare });
+    const route = routeToActorJoinPrewarm(actorId, fallbackActorRef.objectGeneration, {
+        origin,
+        header: Buffer.from(parts[0].data()),
+        payload: Buffer.from(parts[1].data()),
+        returnResponse,
+        remoteBoundSessionTarget,
+        fallbackActorRef,
+        requestTerminal: wrappedRequestTerminal,
+        resolve,
+        reject
+    });
+    if (route !== 'parked')
+        return undefined;
+    //  A Send has no reply to wait for: the migrated redelivery still runs
+    //  in order later, but this caller's own await is done once parking is
+    //  confirmed.
+    if (!isRequest)
+        resolve(undefined);
+    return result;
+}

package/dist/runtime/spots/spot-actor-membership.js

@@ -58,7 +58,7 @@ class ZLinkSpotActorMembership {
     async leaveActor(spotId, actor, signal, meshName) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId, meshName);
-        await this.runLifecycleOperation(activation, () => this.leaveActorCore(activation, actor, signal, meshName));
+        await this.runLifecycleOperation(activation, () => this.leaveActorCore(activation, actor, undefined, meshName), signal);
     }
     async leaveActorCore(activation, actor, signal, meshName) {
         const localEntryNodeRid = (meshName === undefined ? undefined : this.options.nodeRidProvider?.(meshName)) ??
@@ -141,8 +141,8 @@ class ZLinkSpotActorMembership {
         }
         return activation;
     }
-    async runLifecycleOperation(activation, operation) {
-        const pending = activation.serial.executeLifecycleOperation(operation);
+    async runLifecycleOperation(activation, operation, signal) {
+        const pending = (0, abort_1.awaitWithAbort)(activation.serial.executeLifecycleOperation(operation), signal);
         return activation.serial.isCurrentTurn
             ? await activation.serial.currentTurn.yieldFrameworkPromise(pending)
             : await pending;