@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,3 +1,5 @@
+import { type ZLinkRouteToActorJoinPrewarm, type ZLinkActorIngressRoute } 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';
 import type { Message } from '../../contracts/Common/Message';
@@ -19,6 +21,7 @@ export interface ZLinkActorRequestTerminal {
 /** One admitted Actor packet and the routing context that must move with it. */
 export interface ZLinkActorPacketDelivery {
     readonly origin: ApplicationJobOrigin;
+    readonly receivedAt?: Date;
     readonly actorId: string;
     readonly parts: readonly Message[];
     readonly returnResponse: boolean;
@@ -28,39 +31,15 @@ export interface ZLinkActorPacketDelivery {
     readonly messageFollowOrigin?: ZLinkMessageFollowOrigin;
     readonly sourceSessionRid?: RoutingId;
 }
-/**
- * Spec 15 §4.2 relocation temporary queue: consulted when {@code
- * resolveActor} finds nothing for an arrival that carries an exact object
- * identity. Parks the arrival if an Actor Join admission attempt is in
- * flight for {@code (actorId, objectGeneration)}, or reports not-found so
- * the caller falls through to its existing missing-actor handling
- * unchanged.
- */
-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 { ZLinkRouteToActorJoinPrewarm } from './spot-actor-ingress-admission';
 interface ZLinkSpotActorPacketDispatchOptions {
+    readonly admission?: import('../admission').ZLinkRuntimeAdmissionGate;
     readonly spot: ZLinkSpot | (() => ZLinkSpot);
     readonly spotId: () => string;
     readonly registry: ZLinkSpotActorHandlerRegistryRuntime;
-    readonly serial?: ZLinkSpotSerialTurnExecutor;
     readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
-    readonly actorLeft?: (actorId: string) => boolean;
-    readonly routeBeforeLocal?: (delivery: ZLinkActorPacketDelivery) => Promise<{
-        readonly handled: boolean;
-        readonly response?: unknown;
-    } | undefined> | {
-        readonly handled: boolean;
-        readonly response?: unknown;
-    } | undefined;
+    readonly hasDepartedActor?: (actorId: string) => boolean;
+    readonly routeBeforeLocal?: ZLinkActorIngressRoute;
     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;
@@ -69,26 +48,20 @@ interface ZLinkSpotActorPacketDispatchOptions {
     readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly routeToActorJoinPrewarm?: ZLinkRouteToActorJoinPrewarm;
 }
+export type ZLinkActorPacketExecution = {
+    readonly terminal: Promise<unknown>;
+} | {
+    readonly response: unknown;
+};
 export declare class ZLinkSpotActorPacketDispatch {
     private readonly options;
     constructor(options: ZLinkSpotActorPacketDispatchOptions);
-    dispatch(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: ZLinkActorRequestTerminal): Promise<unknown>;
-    dispatchDelivery(delivery: ZLinkActorPacketDelivery): Promise<unknown>;
-    private handleMissingActor;
-    /**
-     * Spec 15 §4.2 relocation temporary queue: parks one arrival for a
-     * missing Actor that carries an exact object identity, instead of
-     * dropping it (Send) or replying HandlerNotFound (Request). Returns
-     * {@code undefined} when no admission attempt owns this object — the
-     * caller falls through to its existing missing-actor handling unchanged.
-     * Header/payload are copied to owned buffers before parking so the
-     * arrival survives independently of the original {@link Message}
-     * lifetime.
-     */
-    private parkForActorJoinPrewarm;
+    dispatch(serial: ZLinkSpotSerialTurnExecutor | undefined, origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: ZLinkActorRequestTerminal): Promise<unknown>;
+    dispatchDelivery(serial: ZLinkSpotSerialTurnExecutor | undefined, delivery: ZLinkActorPacketDelivery): Promise<unknown>;
+    admitDelivery(serial: ZLinkSpotSerialTurnExecutor | undefined, delivery: ZLinkActorPacketDelivery, handoffRuntime?: ZLinkSpotActorHandoffRuntime): Promise<ZLinkActorPacketExecution>;
+    private dispatchUnavailableActor;
     private createPayloadDecoder;
     private dispatchActorPacket;
     private reportInvalidFrame;
     private trace;
 }
-export {};

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorPacketDispatch = void 0;
-const actor_message_follow_context_1 = require("../actors/actor-message-follow-context");
+const spot_actor_ingress_admission_1 = require("./spot-actor-ingress-admission");
 const actor_context_1 = require("../actors/actor-context");
 const session_disconnected_wire_1 = require("../actors/session-disconnected-wire");
 const routing_id_1 = require("../routing-id");
@@ -9,6 +9,7 @@ const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const diagnostics_1 = require("../diagnostics");
+const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
 const flow_context_1 = require("../diagnostics/flow-context");
 const managed_stream_1 = require("../streams/managed-stream");
 const actors_1 = require("../actors");
@@ -22,9 +23,10 @@ class ZLinkSpotActorPacketDispatch {
     constructor(options) {
         this.options = options;
     }
-    dispatch(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
-        return this.dispatchDelivery({
+    dispatch(serial, origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        return this.dispatchDelivery(serial, {
             origin,
+            receivedAt: new Date(),
             actorId,
             parts,
             returnResponse,
@@ -33,11 +35,16 @@ class ZLinkSpotActorPacketDispatch {
             requestTerminal
         });
     }
-    async dispatchDelivery(delivery) {
-        const { actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal } = delivery;
+    async dispatchDelivery(serial, delivery) {
+        const result = await this.admitDelivery(serial, delivery);
+        return 'terminal' in result ? await result.terminal : result.response;
+    }
+    async admitDelivery(serial, delivery, handoffRuntime) {
+        const { actorId, parts, returnResponse, receivedAt: deliveryReceivedAt, remoteBoundSessionTarget, fallbackActorRef, requestTerminal } = delivery;
+        const receivedAt = deliveryReceivedAt ?? new Date();
         if (parts.length < 2) {
             this.reportInvalidFrame(actorId, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend);
-            return undefined;
+            return { response: undefined };
         }
         //  Spec 26 §4.1: one level read per processing point — the same gate value
         //  drives both the decode and the flow-context install.
@@ -71,23 +78,26 @@ class ZLinkSpotActorPacketDispatch {
             const disconnectedReply = disconnected && header.kind === protocol_1.ZLinkStreamMessageKind.Request
                 ? emptyDisconnectedReply
                 : undefined;
-            if (this.options.actorLeft?.(actorId) === true && disconnected) {
-                return disconnectedReply;
-            }
-            const routed = await this.options.routeBeforeLocal?.(delivery);
-            if (routed?.handled === true) {
-                return routed.response;
-            }
-            const actor = this.options.resolveActor(actorId);
-            if (actor === undefined) {
-                return this.handleMissingActor(delivery.origin, actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
-            }
+            const admitted = (0, spot_actor_ingress_admission_1.resolveActorIngress)(delivery, messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest, {
+                handoffRuntime,
+                routeBeforeLocal: this.options.routeBeforeLocal,
+                resolveActor: this.options.resolveActor,
+                hasDepartedActor: this.options.hasDepartedActor,
+                routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
+            });
+            if ('terminal' in admitted)
+                return { terminal: admitted.terminal };
+            if (admitted.kind === 'stale')
+                return {
+                    response: await this.dispatchUnavailableActor(admitted.error, actorId, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef)
+                };
+            const actor = admitted.actor;
             if (disconnected) {
                 const identity = (0, session_disconnected_wire_1.decodeSessionDisconnected)((0, protocol_1.messageToBytes)(parts[1]));
                 if (identity === undefined) {
                     if (this.options.dispatchErrors?.captureEnabled() === true)
                         this.reportInvalidFrame(actorId, messageKind, new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'ProtocolError: malformed Session disconnect identity.'), 'warning');
-                    return disconnectedReply;
+                    return { response: disconnectedReply };
                 }
                 const current = actor.context instanceof actor_context_1.DefaultZLinkActorContext
                     ? actor.context.currentSessionBinding
@@ -96,43 +106,34 @@ class ZLinkSpotActorPacketDispatch {
                     (!(0, routing_id_1.routingIdsEqual)(current.sessionNodeRid, identity.sessionOwnerNodeRid) ||
                         current.sessionOwnerNodeGeneration !== identity.sessionOwnerNodeGeneration ||
                         current.bindingGeneration !== identity.bindingGeneration))
-                    return disconnectedReply;
+                    return { response: disconnectedReply };
                 await this.options.onDisconnectActor(actor);
-                return disconnectedReply;
+                this.trace(messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest
+                    ? ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied
+                    : ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, actorId, header, messageKind);
+                return { response: disconnectedReply };
             }
             const decodePayload = this.createPayloadDecoder(parts[1], header);
-            return this.dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, (0, serial_work_size_1.zlinkSerialWorkOptions)(parts[1].data().byteLength, (0, serial_work_size_1.zlinkMetadataByteLength)(header.metadata)));
+            return {
+                response: await this.dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, serial, (0, serial_work_size_1.zlinkSerialWorkOptions)(parts[1].data().byteLength, (0, serial_work_size_1.zlinkMetadataByteLength)(header.metadata)), receivedAt)
+            };
         });
     }
-    async handleMissingActor(origin, actorId, parts, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal) {
-        if (this.options.routeToActorJoinPrewarm !== undefined &&
-            fallbackActorRef !== undefined &&
-            parts.length >= 2 &&
-            //  A Request without a terminal has no way to complete once
-            //  migrated later — parking it would leave the caller hanging
-            //  forever with no reply route. Fall through to the existing
-            //  missing-actor handling for that shape instead.
-            (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest || requestTerminal !== undefined)) {
-            const parked = this.parkForActorJoinPrewarm(origin, actorId, parts, messageKind, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal);
-            if (parked !== undefined)
-                return parked;
-        }
+    async dispatchUnavailableActor(missingActorError, actorId, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef) {
         this.options.dispatchErrors?.report({
             surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
             messageKind,
-            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing,
+            reason: (0, dispatch_error_details_1.dispatchReasonFromError)(missingActorError),
             action,
             packetName: header.name,
             spotId: this.options.spotId(),
             actorId,
-            correlationId: header.correlationId ?? header.requestSeq?.toString()
+            correlationId: header.correlationId ?? header.requestSeq?.toString(),
+            error: missingActorError
         });
         if (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest) {
             return undefined;
         }
-        const missingActorError = (0, framework_errors_internal_1.createInternalFrameworkException)((0, actor_message_follow_context_1.actorMessageFollowContext)(fallbackActorRef) === undefined
-            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound
-            : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `SPOT actor is not registered locally: ${actorId}`);
         if (header.requestSeq !== undefined &&
             !returnResponse &&
             this.options.actorErrorSender !== undefined) {
@@ -141,77 +142,23 @@ class ZLinkSpotActorPacketDispatch {
         }
         throw missingActorError;
     }
-    /**
-     * Spec 15 §4.2 relocation temporary queue: parks one arrival for a
-     * missing Actor that carries an exact object identity, instead of
-     * dropping it (Send) or replying HandlerNotFound (Request). Returns
-     * {@code undefined} when no admission attempt owns this object — the
-     * caller falls through to its existing missing-actor handling unchanged.
-     * Header/payload are copied to owned buffers before parking so the
-     * arrival survives independently of the original {@link Message}
-     * lifetime.
-     */
-    parkForActorJoinPrewarm(origin, actorId, parts, messageKind, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
-        const isRequest = messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest;
-        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 = this.options.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;
-    }
     createPayloadDecoder(message, header) {
-        return () => (0, payload_codec_1.decodeFrameworkTypedPayloadMessage)(message, this.options.messageSerializers, undefined, (0, protocol_1.streamCodecContentType)(header.codec), header.name);
+        return (messageType) => (0, payload_codec_1.decodeFrameworkTypedPayloadMessage)(message, this.options.messageSerializers, messageType, (0, protocol_1.streamCodecContentType)(header.codec), header.name);
     }
-    async dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, workOptions) {
+    async dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, serial, workOptions, receivedAt) {
         const spot = typeof this.options.spot === 'function' ? this.options.spot() : this.options.spot;
         const dispatcher = new actors_1.ZLinkSpotActorDispatcher({
             registry: this.options.registry,
             spot,
             providerResolver: this.options.providerResolver,
-            serial: this.options.serial,
+            serial,
             serialWorkOptions: workOptions,
             messageSerializers: this.options.messageSerializers,
             onAdmitted: () => this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, actorId, header, messageKind),
             onHandlerStart: () => {
+                if (this.options.admission?.ownerAdmissionOpen() === false) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'Actor handler was rejected because Location owner admission is closed.');
+                }
                 // A transferred backlog is returned to the Actor queue as one FIFO
                 // prefix. Check the request deadline when its owner turn actually
                 // starts, not when that prefix is admitted.
@@ -220,8 +167,8 @@ class ZLinkSpotActorPacketDispatch {
                     Date.now() >= requestDeadlineUnixMs) {
                     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' expired before handler admission.`);
                 }
-                (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
                 this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, actorId, header, messageKind);
+                (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
             }
         });
         try {
@@ -229,7 +176,8 @@ class ZLinkSpotActorPacketDispatch {
                 await dispatcher.dispatchSendDecoded(actor, header.name, decodePayload, {
                     meshName: spot.context.meshName,
                     metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
-                    correlationId: header.correlationId ?? undefined
+                    correlationId: header.correlationId ?? undefined,
+                    receivedAt
                 });
                 this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend);
                 return undefined;
@@ -253,7 +201,8 @@ class ZLinkSpotActorPacketDispatch {
                 await dispatcher.dispatchRequestThenDecoded(actor, header.name, decodePayload, {
                     meshName: spot.context.meshName,
                     metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
-                    correlationId: header.correlationId ?? header.requestSeq.toString()
+                    correlationId: header.correlationId ?? header.requestSeq.toString(),
+                    receivedAt
                 }, async (response) => {
                     this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
                     await requestTerminal(response, preparedReplyReady ? preparedReply : undefined);
@@ -269,7 +218,8 @@ class ZLinkSpotActorPacketDispatch {
                 const response = await dispatcher.dispatchRequestDecoded(actor, header.name, decodePayload, {
                     meshName: spot.context.meshName,
                     metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
-                    correlationId: header.correlationId ?? header.requestSeq.toString()
+                    correlationId: header.correlationId ?? header.requestSeq.toString(),
+                    receivedAt
                 });
                 this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
                 return response;
@@ -277,7 +227,8 @@ class ZLinkSpotActorPacketDispatch {
             await dispatcher.dispatchRequestThenDecoded(actor, header.name, decodePayload, {
                 meshName: spot.context.meshName,
                 metadata: (0, contracts_1.zlinkMessageMetadata)(header.metadata),
-                correlationId: header.correlationId ?? header.requestSeq.toString()
+                correlationId: header.correlationId ?? header.requestSeq.toString(),
+                receivedAt
             }, async (response, replyOptions) => {
                 this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, actorId, header, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest);
                 await this.options.actorResponseSender?.(actor, header.name, requestSeq, response, replyOptions, fallbackBoundSessionTarget, fallbackActorRef, undefined);
@@ -288,15 +239,7 @@ class ZLinkSpotActorPacketDispatch {
             this.options.dispatchErrors?.report({
                 surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
                 messageKind,
-                reason: error instanceof contracts_1.ZLinkFrameworkException &&
-                    (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) ===
-                        framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound
-                    ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing
-                    : error instanceof contracts_1.ZLinkFrameworkException &&
-                        (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) ===
-                            framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed
-                        ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed
-                        : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                reason: (0, dispatch_error_details_1.dispatchReasonFromError)(error),
                 action,
                 packetName: header.name,
                 spotId: this.options.spotId(),

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

@@ -21,6 +21,7 @@ interface ZLinkSpotActorPacketDrainOptions {
     readonly replyActorNoBind?: (info: ZLinkBackendActorRecvInfo, parts: readonly Message[], result: RequestResult) => void;
     readonly waitIdle: () => Promise<void>;
     readonly flowEnabled?: () => boolean;
+    readonly receivedAtClock?: () => Date;
 }
 export declare class ZLinkSpotActorPacketDrain {
     private readonly options;

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

@@ -9,6 +9,7 @@ const protocol_1 = require("../streams/protocol");
 const actor_reply_1 = require("../actors/actor-reply");
 const bound_session_response_target_1 = require("../streams/bound-session-response-target");
 const ZLINK_SPOT_ACTOR_RECV_INFO_NO_BIND = 1;
+const systemReceivedAtClock = () => new Date();
 class ZLinkSpotActorPacketDrain {
     options;
     continuations = new Map();
@@ -24,6 +25,7 @@ class ZLinkSpotActorPacketDrain {
         let requestId;
         let flags;
         let packetKey;
+        let receivedAt;
         try {
             for (;;) {
                 const part = info.recvActorPart(spot_native_flags_1.ZLINK_RECV_DONT_WAIT);
@@ -31,7 +33,8 @@ class ZLinkSpotActorPacketDrain {
                     if (parts.length > 0 && packetKey !== undefined) {
                         this.continuations.set(packetKey, {
                             owner: continuationOwner(parts[0], this.flowEnabled()),
-                            parts: parts.splice(0)
+                            parts: parts.splice(0),
+                            receivedAt: receivedAt ?? (this.options.receivedAtClock ?? systemReceivedAtClock)()
                         });
                         return;
                     }
@@ -42,6 +45,8 @@ class ZLinkSpotActorPacketDrain {
                 if (packetKey === undefined) {
                     packetKey = currentPacketKey;
                     const pending = this.continuations.get(currentPacketKey);
+                    receivedAt =
+                        pending?.receivedAt ?? (this.options.receivedAtClock ?? systemReceivedAtClock)();
                     if (pending !== undefined) {
                         if (isStreamHeaderMessage(part.message, this.flowEnabled())) {
                             closeMessages(pending.parts);
@@ -79,7 +84,7 @@ class ZLinkSpotActorPacketDrain {
                 return;
             }
             if (noBindInfo !== undefined) {
-                await this.dispatchNoBindActorRequest(noBindInfo, actorId, parts, actorRef);
+                await this.dispatchNoBindActorRequest(noBindInfo, actorId, parts, actorRef, receivedAt ?? (this.options.receivedAtClock ?? systemReceivedAtClock)());
             }
             else {
                 await this.options.actorPacketHandler({
@@ -88,7 +93,8 @@ class ZLinkSpotActorPacketDrain {
                     parts,
                     returnResponse: false,
                     sourceSessionRid,
-                    fallbackActorRef: actorRef
+                    fallbackActorRef: actorRef,
+                    receivedAt
                 });
             }
         }
@@ -129,7 +135,7 @@ class ZLinkSpotActorPacketDrain {
             return false;
         }
     }
-    async dispatchNoBindActorRequest(info, actorId, parts, actorRef) {
+    async dispatchNoBindActorRequest(info, actorId, parts, actorRef, receivedAt) {
         try {
             const response = await this.options.actorPacketHandler?.({
                 origin: 'remote',
@@ -137,7 +143,8 @@ class ZLinkSpotActorPacketDrain {
                 parts,
                 returnResponse: true,
                 sourceSessionRid: info.sourceSessionRid,
-                fallbackActorRef: actorRef
+                fallbackActorRef: actorRef,
+                receivedAt
             });
             this.options.replyActorNoBind?.(info, [this.encodeActorReplyFrame(parts[0], protocol_1.ZLinkStreamMessageKind.Response, response)], runtime_values_1.RequestResult.Ok);
         }

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

@@ -10,9 +10,11 @@ import { type ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
 import { type ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
 import { type ZLinkSpotRoutedTransport } from './spot-outbound';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import { ZLinkSpotSerialExecutor } from './spot-serial-executor';
 import { type ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import type { ZLinkEntryActorRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotActorHandoffRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
 interface ZLinkEntrySpotActivationOptions {
+    readonly admission?: import('../admission').ZLinkRuntimeAdmissionGate;
     readonly entrySpotType: Type<ZLinkEntrySpot>;
     readonly timerHandlers?: readonly ZLinkEntrySpotTimerHandlerRegistration[];
     readonly packetHandlers?: readonly ZLinkEntrySpotPacketHandlerRegistration[];
@@ -44,13 +46,12 @@ interface ZLinkEntrySpotActivationOptions {
 export declare class ZLinkEntrySpotActivation {
     private readonly options;
     private readonly serial;
-    private readonly spotSerialExecutor;
+    readonly spotSerialExecutor: ZLinkSpotSerialExecutor;
     private readonly timers;
     private readonly actorHandlers;
     private readonly handlers;
     private readonly outbound;
     private readonly workerRuntime;
-    private readonly lifecycleMetrics;
     private readonly packetDispatch;
     private readonly actorPacketDispatch;
     private initialized;
@@ -72,7 +73,7 @@ export declare class ZLinkEntrySpotActivation {
         readonly channelName: string;
         readonly contentType?: string;
     }, returnResponse: boolean): Promise<unknown>;
-    dispatchPacketEncoded(packetName: string | undefined, decodePayload: () => unknown, context: {
+    dispatchPacketEncoded(packetName: string | undefined, decodePayload: (messageType?: Type) => unknown, context: {
         readonly channelName: string;
         readonly contentType?: string;
     }, returnResponse: boolean): Promise<unknown>;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkEntrySpotActivation = void 0;
+const spot_actor_admission_coordinator_1 = require("./spot-actor-admission-coordinator");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const contracts_1 = require("../../contracts");
 const abort_1 = require("../abort");
@@ -21,7 +22,6 @@ const spot_timer_1 = require("./spot-timer");
 const spot_context_1 = require("./spot-context");
 const spot_routed_spot_packet_dispatch_1 = require("./spot-routed-spot-packet-dispatch");
 const actor_handoff_1 = require("../actors/actor-handoff");
-const spot_lifecycle_metrics_1 = require("./spot-lifecycle-metrics");
 class ZLinkEntrySpotActivation {
     options;
     serial;
@@ -31,7 +31,6 @@ class ZLinkEntrySpotActivation {
     handlers;
     outbound;
     workerRuntime;
-    lifecycleMetrics;
     packetDispatch;
     actorPacketDispatch;
     initialized = false;
@@ -58,7 +57,6 @@ class ZLinkEntrySpotActivation {
             meshName: options.spotNodeName
         });
         this.timers = new spot_timer_1.ZLinkSpotTimerRegistry(options.metrics, () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
-        this.lifecycleMetrics = new spot_lifecycle_metrics_1.ZLinkSpotLifecycleMetrics(options.metrics);
         this.workerRuntime = options.workerRuntime ?? new workers_1.ZLinkWorkerRuntime();
         this.context = (0, spot_context_1.createEntrySpotContext)({
             spotId: String(options.nativeSpot.routingId),
@@ -97,11 +95,12 @@ class ZLinkEntrySpotActivation {
             dispatchErrors: options.dispatchErrors
         });
         this.actorPacketDispatch = new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
+            admission: this.options.admission,
             spot: () => this.entrySpot,
             spotId: () => String(this.options.nativeSpot.routingId),
             registry: this.actorHandlers,
             resolveActor: (targetActorId) => this.options.entryActorRuntime?.resolveActor(targetActorId),
-            routeBeforeLocal: (target) => this.options.entryActorRuntime?.routePacket(target.actorId, target.parts, target.returnResponse, target.remoteBoundSessionTarget, target.fallbackActorRef),
+            routeBeforeLocal: (delivery) => this.options.entryActorRuntime?.routePacket(delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef, delivery.origin, delivery.requestTerminal, delivery.messageFollowOrigin),
             onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
             actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(this.options.boundSessionRuntime),
             actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),
@@ -162,7 +161,7 @@ class ZLinkEntrySpotActivation {
         await this.serial.execute(() => this.entrySpot.onInitialize?.());
         this.attachActorJoinDispatch();
         this.initialized = true;
-        this.lifecycleMetrics.opened('entry');
+        this.options.metrics?.recordSpotCount(this.options.spotNodeName, 'entry', 1);
     }
     async dispose(deadline) {
         if (this.disposed)
@@ -189,7 +188,7 @@ class ZLinkEntrySpotActivation {
             await this.options.nativeSpot.dispose();
         });
         if (this.initialized) {
-            this.lifecycleMetrics.closed('entry');
+            this.options.metrics?.recordSpotCount(this.options.spotNodeName, 'entry', -1);
         }
         if (errors.length === 1)
             throw errors[0];
@@ -291,11 +290,7 @@ class ZLinkEntrySpotActivation {
         return this.serial.execute(() => this.entrySpot.onDisconnectActor?.(actor));
     }
     async dispatchActorPacket(delivery) {
-        const { actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowOrigin } = delivery;
-        const handoff = this.options.actorHandoffRuntime?.capture(delivery.origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin);
-        if (handoff !== undefined)
-            return await handoff;
-        return this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox(delivery));
+        return (0, spot_actor_admission_coordinator_1.dispatchActorPacketInMailbox)((operation) => this.spotSerialExecutor.executeActor(delivery.actorId, operation), () => this.actorPacketDispatch.admitDelivery(undefined, delivery, this.options.actorHandoffRuntime));
     }
     /** Restores source packets through the Entry Actor's existing executor. */
     admitActorPacketPrefix(actorId, records) {
@@ -325,7 +320,7 @@ class ZLinkEntrySpotActivation {
         }));
     }
     async dispatchActorPacketInsideMailbox(delivery) {
-        return this.actorPacketDispatch.dispatchDelivery(delivery);
+        return this.actorPacketDispatch.dispatchDelivery(undefined, delivery);
     }
     replyActorNoBind(info, parts, result) {
         this.options.nativeNode.replyActorNoBind(info, parts, result);

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

@@ -1,3 +1,4 @@
+import type { ZLinkHandlerMessageType } from '../../contracts/Common/HandlerMessageType';
 import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpot, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotHandlerRegistry, ZLinkSpotTimerHandler } from '../../contracts';
 import type { ZLinkEntrySpotActorRequestHandlerRegistration, ZLinkEntrySpotActorSendHandlerRegistration, ZLinkEntrySpotPacketHandlerRegistration, ZLinkEntrySpotSubscriptionHandlerRegistration, ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandlerRegistration, ZLinkSpotPacketHandlerRegistration, ZLinkSpotSubscriptionHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -5,6 +6,7 @@ import { ZLinkActorPacketKind, ZLinkSpotActorHandlerRegistryRuntime } from '../a
 export interface ZLinkSpotHandlerRegistration {
     readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'timer';
     readonly handlerType: Type;
+    readonly messageType?: ZLinkHandlerMessageType;
     readonly packetName?: string;
     readonly channelName?: string;
     readonly topic?: string;
@@ -18,11 +20,13 @@ export declare class DefaultZLinkSpotHandlerRegistry<TActor extends ZLinkActor =
     addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this;
     addActorPacket<THandler, TRegisteredActor extends ZLinkActor>(handlerType: Type<THandler>, actorType: Type<TRegisteredActor>): this;
     addPacket(handlerType: Type, packetName?: string): this;
+    addPacketRegistration(handlerType: Type, packetName: string | undefined, messageType: ZLinkHandlerMessageType | undefined): this;
     packet(packetName: string, handlerType: Type): this;
-    addActorPacketRegistration(kind: ZLinkActorPacketKind, handlerType: Type, actorType: Type<TActor>, packetName: string): this;
+    addActorPacketRegistration(kind: ZLinkActorPacketKind, handlerType: Type, actorType: Type<TActor>, packetName: string, messageType: ZLinkHandlerMessageType | undefined): this;
     actorSend(packetName: string, handlerType: Type, actorType?: Type<TActor>): this;
     actorRequest(packetName: string, handlerType: Type, actorType?: Type<TActor>): this;
     addSubscribe(handlerType: Type, channelName: string, topic: string): this;
+    addSubscriptionRegistration(handlerType: Type, channelName: string, topic: string, messageType: ZLinkHandlerMessageType | undefined): this;
     subscribe(channelName: string, topic: string, handlerType: Type): this;
     addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkSpot>>(handlerType: Type<THandler>): this;
     snapshot(): readonly ZLinkSpotHandlerRegistration[];