@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/spots/spot-remote-codec.js

@@ -7,6 +7,8 @@ exports.decodeRemoteActorJoinPayload = decodeRemoteActorJoinPayload;
 exports.decodeHandoffBacklog = decodeHandoffBacklog;
 exports.decodeRemoteActorRef = decodeRemoteActorRef;
 exports.decodeRemoteBoundSessionTarget = decodeRemoteBoundSessionTarget;
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const actors_1 = require("../actors");
 const runtime_message_1 = require("../backend/runtime-message");
 const routing_id_1 = require("../routing-id");
@@ -58,7 +60,7 @@ function decodeRemoteActorJoinPayload(payload, request, received, raw, envelope)
         request,
         requestContentType: typeof payload.requestContentType === 'string'
             ? payload.requestContentType
-            : 'application/json'
+            : stream_wire_1.ZlinkStreamContentType.Json
     };
 }
 function decodeHandoffBacklog(value) {
@@ -179,8 +181,8 @@ function decodeBoundSessionServiceWireRelocation(value) {
 }
 function requireSpotId(value) {
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 255) {
-        throw new Error('Remote bound session SpotId must contain 1..255 UTF-8 bytes.');
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES) {
+        throw new Error(`Remote bound session SpotId must contain 1..${CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
     }
     return value;
 }

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

@@ -1,10 +1,10 @@
-import type { ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
+import { type ZLinkMessageSerializer, type ZLinkSpot } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkApplicationWorkClaim } from '../admission';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkApplicationWorkClaim } from '../admission';
 interface ZLinkSpotRoutePacketDispatchOptions {
     readonly packetHandlers: ReadonlyMap<string, readonly ZLinkSpotHandlerRegistration[]>;
     readonly nativeSpotId: string;

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

@@ -3,17 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotRoutePacketDispatch = void 0;
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const actors_1 = require("../actors");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const runtime_message_1 = require("../backend/runtime-message");
 const channel_envelope_1 = require("../channels/channel-envelope");
-const actors_1 = require("../actors");
-const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const spot_direct_envelope_1 = require("../channels/spot-direct-envelope");
+const flow_context_1 = require("../diagnostics/flow-context");
 const serial_work_size_1 = require("../execution/serial-work-size");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
 const spot_remote_codec_1 = require("./spot-remote-codec");
 const spot_route_replies_1 = require("./spot-route-replies");
-const flow_context_1 = require("../diagnostics/flow-context");
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
 /** D5: reply metadata attached only to framework-self-generated errors. */
 const FRAMEWORK_ORIGIN_REPLY_METADATA = Object.freeze({
     [channel_envelope_1.ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY]: channel_envelope_1.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE
@@ -206,7 +206,7 @@ function decodeSpotDirectEnvelope(parts) {
     }
     try {
         const decoded = JSON.parse(parts[0].data().toString());
-        if (decoded.marker !== SPOT_DIRECT_ENVELOPE ||
+        if (decoded.marker !== spot_direct_envelope_1.SPOT_DIRECT_ENVELOPE ||
             (decoded.kind !== 1 /* ZLinkChannelMessageKind.Request */ &&
                 decoded.kind !== 3 /* ZLinkChannelMessageKind.Command */) ||
             typeof decoded.channelName !== 'string') {
@@ -232,7 +232,7 @@ function decodeSpotDirectEnvelope(parts) {
 }
 function encodeSpotDirectReply(ok, response, error) {
     return runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(JSON.stringify({
-        marker: SPOT_DIRECT_ENVELOPE,
+        marker: spot_direct_envelope_1.SPOT_DIRECT_ENVELOPE,
         ok,
         response,
         error

package/dist/runtime/spots/spot-route-replies.d.ts

@@ -1,7 +1,7 @@
-import type { ZLinkBackendMessageLike as MessageLike, ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import type { ZLinkBackendReceived as BackendReceived, ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import { decodeChannelEnvelope } from '../channels/channel-envelope';
-import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 import type { ZLinkDecodedRemoteActorJoinRequest } from './spot-remote-codec';
+import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 export interface ZLinkRouteReplySubmitOperation {
     message(message: MessageLike): ZLinkRouteReplySubmitOperation;
     submit(): void;

package/dist/runtime/spots/spot-route-replies.js

@@ -7,9 +7,11 @@ exports.submitRoutedActorJoinReply = submitRoutedActorJoinReply;
 exports.submitRoutedActorJoinError = submitRoutedActorJoinError;
 exports.appendRouteReplyParts = appendRouteReplyParts;
 exports.hasReplyToken = hasReplyToken;
+const node_os_1 = require("node:os");
 const channel_envelope_1 = require("../channels/channel-envelope");
 const configuration_1 = require("../configuration");
 const spot_route_reply_wire_1 = require("./spot-route-reply-wire");
+const nativeErrnoValues = node_os_1.constants.errno;
 function submitRouteReply(operation) {
     try {
         operation.submit();
@@ -70,5 +72,5 @@ function requireRoutedActorJoinEnvelope(decoded) {
 function isNativeBadAddress(error) {
     return (typeof error === 'object' &&
         error !== null &&
-        Number(error.nativeErrno) === 14);
+        Number(error.nativeErrno) === nativeErrnoValues.EFAULT);
 }

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

@@ -1,8 +1,9 @@
 import type { ZLinkActor, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import { type ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
 interface ZLinkRoutedActorAdmissionTarget {
     onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
 }
@@ -11,7 +12,7 @@ interface ZLinkSpotRoutedActorAdmissionOptions {
     readonly getTarget: () => ZLinkRoutedActorAdmissionTarget;
     readonly defaultAccept: boolean;
     readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
-    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[], sealedSession: ZLinkRemoteBoundSessionTarget | undefined) => Promise<readonly ZLinkActorHandoffResult[]>;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
     readonly pendingAdmissionTimeoutMs?: number;
     /** Spec 27 §4: with tracing Off, inbound flow fields are neither validated nor carried forward. */

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

@@ -7,6 +7,7 @@ const payload_codec_1 = require("../messaging/payload-codec");
 const routing_id_1 = require("../routing-id");
 const spot_remote_codec_1 = require("./spot-remote-codec");
 const spot_route_replies_1 = require("./spot-route-replies");
+const DEFAULT_PENDING_ADMISSION_TIMEOUT_MS = 30_000;
 class ZLinkSpotRoutedActorAdmission {
     options;
     pending = new Map();
@@ -139,7 +140,7 @@ class ZLinkSpotRoutedActorAdmission {
                 throw new Error('Remote actor transfer commit cannot materialize the target actor.');
             }
             const { actor, actorRef } = await this.options.routedActorTransferProvider(decoded.actorId, decoded.actorType, decoded.transferAdapterKey, decoded.transferState, decoded.actorEntryNodeRid, decoded.remoteBoundSessionTarget);
-            const handoffResults = (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog)) ?? [];
+            const handoffResults = (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog, decoded.remoteBoundSessionTarget)) ?? [];
             const commitReply = {
                 accepted: true,
                 actorNodeRid: String(actorRef.nodeRid),
@@ -183,7 +184,7 @@ class ZLinkSpotRoutedActorAdmission {
         pending.deadline = setTimeout(() => {
             if (this.pending.get(transferId) === pending)
                 this.pending.delete(transferId);
-        }, this.options.pendingAdmissionTimeoutMs ?? 30_000);
+        }, this.options.pendingAdmissionTimeoutMs ?? DEFAULT_PENDING_ADMISSION_TIMEOUT_MS);
         pending.deadline.unref();
     }
     closeDecoded(decoded) {

package/dist/runtime/spots/spot-routed-frame-dispatch.d.ts

@@ -3,7 +3,7 @@ import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProvider
 import type { RoutingId } from '../../contracts';
 import type { ActorRef } from '../../contracts/Common/ActorRef';
 import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
-import type { ZLinkBackendReceived, ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkBackendReceived } from '../backend/contracts';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkActorPacketDelivery, ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
@@ -15,15 +15,13 @@ interface ZLinkRoutedFrameAdmissionTarget {
     onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
 }
 interface ZLinkSpotRoutedFrameDispatchOptions {
-    readonly nativeSpot: ZLinkBackendSpot;
-    readonly createReceived: () => ZLinkBackendReceived;
     readonly nativeSpotId: string;
     readonly serial: ZLinkSpotSerialTurnExecutor;
     readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
     readonly getTarget: () => ZLinkRoutedFrameAdmissionTarget & ZLinkSpot;
     readonly defaultAccept: boolean;
     readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
-    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[], sealedSession: ZLinkRemoteBoundSessionTarget | undefined) => Promise<readonly ZLinkActorHandoffResult[]>;
     readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
     readonly routedBoundSessionReceiver?: (actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, actorRef?: ActorRef, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
     readonly routedBoundSessionResponseReceiver?: (actorId: string, packetName: string, requestSeq: bigint, message: unknown, replyOptions: ZLinkActorResponseOptions, actorPacketTarget?: unknown, signal?: AbortSignal) => Promise<void>;
@@ -34,11 +32,9 @@ interface ZLinkSpotRoutedFrameDispatchOptions {
     readonly providerResolver?: ZLinkProviderResolver;
     readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
-    readonly waitIdle: () => Promise<void>;
 }
 export declare class ZLinkSpotRoutedFrameDispatch {
     private readonly options;
-    private routeDraining;
     private readonly packetHandlers;
     private readonly routedBoundSessionDispatch;
     private readonly actorPacketRelayDispatch;
@@ -46,7 +42,6 @@ export declare class ZLinkSpotRoutedFrameDispatch {
     private readonly routedActorAdmission;
     constructor(options: ZLinkSpotRoutedFrameDispatchOptions);
     configurePacketHandlers(registrations: readonly ZLinkSpotHandlerRegistration[]): void;
-    drain(received?: ZLinkBackendReceived | undefined, retryDeadlineMs?: number): Promise<void>;
     dispatchFromEvent(received: ZLinkBackendReceived): Promise<void>;
     private channelCodecs;
     private dispatch;

package/dist/runtime/spots/spot-routed-frame-dispatch.js

@@ -2,14 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotRoutedFrameDispatch = void 0;
 const spot_remote_route_codec_1 = require("./spot-remote-route-codec");
-const spot_native_flags_1 = require("./spot-native-flags");
 const spot_actor_packet_relay_dispatch_1 = require("./spot-actor-packet-relay-dispatch");
 const spot_route_packet_dispatch_1 = require("./spot-route-packet-dispatch");
 const spot_routed_actor_admission_1 = require("./spot-routed-actor-admission");
 const spot_routed_bound_session_dispatch_1 = require("./spot-routed-bound-session-dispatch");
 class ZLinkSpotRoutedFrameDispatch {
     options;
-    routeDraining = false;
     packetHandlers = new Map();
     routedBoundSessionDispatch;
     actorPacketRelayDispatch;
@@ -61,62 +59,6 @@ class ZLinkSpotRoutedFrameDispatch {
             this.packetHandlers.set(packetName, existing);
         }
     }
-    async drain(received = undefined, retryDeadlineMs = performance.now()) {
-        if (this.routeDraining) {
-            if (received !== undefined) {
-                try {
-                    await this.dispatch(received);
-                }
-                finally {
-                    received.close();
-                }
-            }
-            return;
-        }
-        this.routeDraining = true;
-        try {
-            if (received !== undefined) {
-                try {
-                    await this.dispatch(received);
-                }
-                finally {
-                    received.close();
-                }
-                received = undefined;
-            }
-            for (;;) {
-                received ??= this.options.createReceived();
-                try {
-                    if (!this.options.nativeSpot.recvRoute(received, spot_native_flags_1.ZLINK_RECV_DONT_WAIT)) {
-                        received.close();
-                        await this.options.waitIdle();
-                        return;
-                    }
-                }
-                catch (error) {
-                    if (isRouteRecvRetryable(error)) {
-                        closeReceivedQuietly(received);
-                        if (performance.now() < retryDeadlineMs) {
-                            setTimeout(() => void this.drain(undefined, retryDeadlineMs), 10);
-                        }
-                        return;
-                    }
-                    received.close();
-                    throw error;
-                }
-                try {
-                    await this.dispatch(received);
-                }
-                finally {
-                    received.close();
-                }
-                received = this.options.createReceived();
-            }
-        }
-        finally {
-            this.routeDraining = false;
-        }
-    }
     async dispatchFromEvent(received) {
         try {
             await this.dispatch(received);
@@ -145,18 +87,7 @@ class ZLinkSpotRoutedFrameDispatch {
         if (await this.routePacketDispatch.dispatch(received)) {
             return;
         }
-        await this.routedActorAdmission.admit(received);
+        await this.options.serial.executeLifecycleOperation(() => this.routedActorAdmission.admit(received));
     }
 }
 exports.ZLinkSpotRoutedFrameDispatch = ZLinkSpotRoutedFrameDispatch;
-function isRouteRecvRetryable(error) {
-    return (typeof error === 'object' &&
-        error !== null &&
-        [201, 202, 204].includes(Number(error.result)));
-}
-function closeReceivedQuietly(received) {
-    try {
-        received.close();
-    }
-    catch { }
-}

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

@@ -6,6 +6,7 @@ import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 import type { ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
 interface ZLinkRoutedSpotPacketActivation {
+    readonly objectGeneration?: bigint;
     readonly meshName?: string;
     readonly spotId: RoutingId;
     readonly spot: ZLinkSpot;
@@ -28,6 +29,9 @@ interface ZLinkRoutedSpotPacketContext {
     readonly signal?: AbortSignal;
     /** Wait until a recovered activation has actually entered its first handler. */
     readonly awaitFirstHandlerTurn?: boolean;
+    readonly onOneWayError?: (error: unknown) => void;
+    /** Retains the caller's Instance address intent through an incarnation boundary. */
+    readonly activationRecord?: import('../foundation/service-runtime-contracts').ReceiveRecord;
 }
 export declare class ZLinkRoutedSpotPacketDispatch {
     private readonly options;

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkRoutedSpotPacketDispatch = void 0;
+const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const configuration_1 = require("../configuration");
@@ -58,17 +59,42 @@ class ZLinkRoutedSpotPacketDispatch {
         const applicationClaim = activation.meshName === undefined
             ? undefined
             : this.options.claimApplicationWork?.(activation.meshName);
-        const runHandler = async () => {
+        const originalRecord = context.activationRecord?.activationRecord;
+        const instanceIntent = originalRecord?.activation === 'missing' ||
+            (originalRecord?.activation === 'ready' && originalRecord.instanceIntent);
+        const runHandler = async (failure) => {
             try {
+                if (failure !== undefined)
+                    throw failure;
+                const current = this.options.resolveActivation(spotId);
+                if (current === undefined ||
+                    (!instanceIntent &&
+                        (current !== activation ||
+                            (originalRecord?.activation === 'ready' &&
+                                originalRecord.route.objectGeneration !== current.objectGeneration)))) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `Spot '${String(spotId)}' is not active.`);
+                }
+                if (context.activationRecord?.deadlineUnixMs !== undefined &&
+                    context.activationRecord.deadlineUnixMs < BigInt(Date.now())) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Spot '${String(spotId)}' request deadline has expired.`);
+                }
+                const currentRegistrations = current === activation
+                    ? registrations
+                    : current.handlers
+                        .snapshot()
+                        .filter((registration) => registration.kind === 'packet' &&
+                        (registration.packetName ?? registration.handlerType.name) ===
+                            (packetName ?? ''));
                 // Decode only after the Spot has acquired both application admission
                 // and its execution authority.
                 const payload = decodePayload();
-                for (const registration of registrations) {
-                    const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(activation.spot, registration.handlerType, this.options.providerResolver);
+                for (const registration of currentRegistrations) {
+                    const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(current.spot, registration.handlerType, this.options.providerResolver);
                     resolveFirstHandlerTurn?.();
                     resolveFirstHandlerTurn = undefined;
+                    context.activationRecord?.onHandlerTurnStarted?.();
                     (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
-                    response = await handler.handle(activation.spot, payload, {
+                    response = await handler.handle(current.spot, payload, {
                         channelName: context.channelName,
                         contentType: context.contentType,
                         packetName: packetName,
@@ -94,8 +120,24 @@ class ZLinkRoutedSpotPacketDispatch {
                             detachedApplicationPermit?.releaseAfterInternalProcessing();
                             applicationClaim?.close();
                         }
-                    }, (error) => this.reportFailure(spotId, packetName, context, false, error), context.workOptions, { signal: context.signal });
-                    await firstHandlerTurn;
+                    }, (error) => {
+                        if (context.onOneWayError === undefined) {
+                            this.reportFailure(spotId, packetName, context, false, error);
+                        }
+                        else if (resolveFirstHandlerTurn === undefined) {
+                            context.onOneWayError(error);
+                        }
+                    }, context.workOptions, { signal: context.signal }, instanceIntent
+                        ? async (failure) => {
+                            try {
+                                await runHandler(failure);
+                            }
+                            finally {
+                                detachedApplicationPermit?.releaseAfterInternalProcessing();
+                                applicationClaim?.close();
+                            }
+                        }
+                        : undefined);
                 }
                 catch (error) {
                     detached = false;
@@ -103,16 +145,18 @@ class ZLinkRoutedSpotPacketDispatch {
                     rejectFirstHandlerTurn?.(error);
                     throw error;
                 }
+                await firstHandlerTurn;
             }
             else {
                 if (activation.serial.isCurrentTurn) {
                     throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Spot '${spotId}' cannot await a request to its current serial turn.`);
                 }
-                await activation.serial.execute(runHandler, context.workOptions);
+                await activation.serial.execute(runHandler, context.workOptions, instanceIntent ? runHandler : undefined);
             }
         }
         catch (error) {
-            this.reportFailure(spotId, packetName, context, returnResponse, error);
+            if (context.activationRecord?.activationRecord === undefined)
+                this.reportFailure(spotId, packetName, context, returnResponse, error);
             throw error;
         }
         finally {
@@ -122,16 +166,17 @@ class ZLinkRoutedSpotPacketDispatch {
         return returnResponse ? response : undefined;
     }
     reportFailure(spotId, packetName, context, returnResponse, error) {
-        const frameworkErrorKind = error instanceof contracts_1.ZLinkFrameworkException ? (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) : undefined;
-        this.options.dispatchErrors?.report({
-            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute,
+        const reporter = this.options.dispatchErrors;
+        if (reporter?.captureEnabled() !== true)
+            return;
+        reporter.report({
+            surface: context.activationRecord?.activationRecord?.kind === 'instanceSpot'
+                ? ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot
+                : ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute,
             messageKind: returnResponse
                 ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request
                 : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
-            reason: frameworkErrorKind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerQueueFull ||
-                frameworkErrorKind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded
-                ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure
-                : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+            reason: (0, dispatch_error_details_1.dispatchReasonFromError)(error),
             action: returnResponse ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.FailCaller : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
             packetName,
             channelName: context.channelName,
@@ -140,6 +185,11 @@ class ZLinkRoutedSpotPacketDispatch {
         });
     }
     reportMissing(spotId, packetName, context, returnResponse) {
+        if (context.activationRecord?.activationRecord !== undefined) {
+            if (!returnResponse && context.onOneWayError !== undefined)
+                context.onOneWayError((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.HandlerNotFound, `SPOT route handler not found: ${packetName}`));
+            return;
+        }
         this.options.dispatchErrors?.report({
             surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotRoute,
             messageKind: returnResponse

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

@@ -1,7 +1,7 @@
 import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkSpot } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget, ZLinkDeferredJoinAcceptedRoot } from '../actors';
+import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget, ZLinkDeferredJoinCompletion } from '../actors';
 import type { ZLinkActorHandoffDispatch } from '../actors/actor-handoff';
 import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
 import type { ZLinkRemoteActorJoinActor, ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
@@ -16,44 +16,28 @@ export interface ZLinkEntryActorRuntime {
     }>;
 }
 export interface ZLinkSpotActorTransferRuntime {
-    prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string, signal?: AbortSignal, canonicalInventoryDigest?: string): Promise<ZLinkDeferredJoinAcceptedRoot>;
-    discardDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, signal?: AbortSignal): Promise<void>;
-    markDeferredJoinAcceptedCommitted(root: ZLinkDeferredJoinAcceptedRoot, actorRef: ActorRef, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
-    commitAndDeliverDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
+    prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;
+    deliverDeferredJoinCompletion(completion: ZLinkDeferredJoinCompletion, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<void>;
     getOrCreateRoutedActor(actorId: string, actorType: string, actorRef?: ActorRef, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, actorCreateRequest?: Message, signal?: AbortSignal): Promise<ZLinkRemoteActorJoinActor>;
     materializeRoutedActor: ZLinkRoutedActorTransferProvider;
     commitRoutedActorAuthority(actor: ZLinkActor, sourceActorRef: ActorRef, transferId: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, deadlineAtMs: number, signal?: AbortSignal): Promise<import('../locations/internal-location-contracts').ZLinkAuthoritySnapshot>;
-    rememberRoutedActorTransferTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
-    claimNativeActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string): Promise<ZLinkNativeActorJoinSnapshot>;
     claimRoutedActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string, joinedLocation?: {
         readonly spotGeneration: bigint;
         readonly membershipEpoch: bigint;
     }): Promise<void>;
-    publishRoutedActorOwnership(actor: ZLinkActor): Promise<void>;
+    publishRoutedActorOwnership(actor: ZLinkActor, sealedSession: ZLinkRemoteBoundSessionTarget | undefined): Promise<void>;
     openRoutedActorSession(actor: ZLinkActor): Promise<void>;
     bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
     commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
     clearRoutedActor(actor: ZLinkActor): void;
-    rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
     rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
     actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
 }
-export interface ZLinkNativeActorJoinSnapshot {
-    readonly spotId?: RoutingId;
-    readonly spot?: ZLinkSpot;
-    readonly locationSpotId?: RoutingId;
-    readonly spotMeshName?: string;
-    readonly actorRef?: ActorRef;
-    readonly spotGeneration?: bigint;
-    readonly membershipEpoch?: bigint;
-    readonly ownerNodeGeneration?: bigint;
-}
 export interface ZLinkSpotBoundSessionRuntime {
     receiveRoutedBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, actorRef?: ActorRef, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
     receiveRoutedBoundSessionResponse(actorId: string, packetName: string, requestSeq: bigint, message: unknown, replyOptions: ZLinkActorResponseOptions, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
     receiveRoutedBoundSessionError(actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, actorPacketTarget?: unknown, signal?: AbortSignal): Promise<void>;
-    rememberRemoteBoundSessionTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
     resolveRemoteBoundSessionTarget(sourceNodeRid: RoutingId, sourceSessionRid: RoutingId): ZLinkRemoteBoundSessionTarget | undefined;
     actorPacketTargetForState(actorId: string): ZLinkRemoteActorPacketTarget | undefined;
     sendActorResponse(actor: ZLinkActor, packetName: string, requestSeq: bigint, response: unknown, replyOptions: ZLinkActorResponseOptions, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, signal?: AbortSignal): Promise<void>;

package/dist/runtime/spots/spot-serial-executor.d.ts

@@ -31,6 +31,11 @@ export declare class ZLinkSpotSerialExecutor {
      * ownership turn. Already accepted work remains drainable.
      */
     close(): Promise<void>;
+    /**
+     * Closes the Actor and timer queues. The Spot queue stays open for the Spot
+     * Close lifecycle item that owns it; that Close closes it when it finishes.
+     */
+    closeChildren(): Promise<void>;
     private actorExecutor;
     private actorSerial;
     private timerSerial;

package/dist/runtime/spots/spot-serial-executor.js

@@ -70,6 +70,14 @@ class ZLinkSpotSerialExecutor {
      * ownership turn. Already accepted work remains drainable.
      */
     close() {
+        const children = this.closeChildren();
+        return Promise.all([children, this.spotSerial.whenIdle()]).then(() => undefined);
+    }
+    /**
+     * Closes the Actor and timer queues. The Spot queue stays open for the Spot
+     * Close lifecycle item that owns it; that Close closes it when it finishes.
+     */
+    closeChildren() {
         if (this.closePromise !== undefined)
             return this.closePromise;
         this.closing = true;
@@ -79,8 +87,7 @@ class ZLinkSpotSerialExecutor {
         this.timerSerials.clear();
         this.actorExecutors.clear();
         this.closePromise = Promise.all([
-            this.spotSerial.close(),
-            ...childSerials.map((serial) => serial.close()),
+            ...childSerials.map((serial) => serial.whenIdle()),
             ...actorExecutors.map((executor) => executor.close())
         ]).then(() => undefined);
         return this.closePromise;

package/dist/runtime/spots/spot-serial-turn-executor.d.ts

@@ -1,6 +1,11 @@
-import { ZLinkExecutionBarrier, ZLinkSpotSerialTurn } from '../execution';
+import { ZLinkExecutionBarrier, type ZLinkExecutionBarrierClaim, ZLinkSpotSerialTurn } from '../execution';
 import type { SpotId } from '../../contracts';
-import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+import type { ZLinkFrameworkException } from '../../contracts/Errors/ZLinkFrameworkException';
+import { type ZLinkSerialSchedulerOptions, type ZLinkSerialWorkOptions, type ZLinkSerialWorkRecord } from '../execution/serial-execution-queue';
+import type { ZLinkSerialLifecycleContext } from '../execution/serial-execution-queue';
+export type ZLinkSpotApplicationTurnContext = ZLinkExecutionBarrierClaim & {
+    readonly replay?: (failure?: unknown) => Promise<unknown> | unknown;
+};
 export declare class ZLinkSpotSerialTurnExecutor {
     private readonly yieldAllowed;
     readonly sourceSpotId?: SpotId | undefined;
@@ -10,6 +15,7 @@ export declare class ZLinkSpotSerialTurnExecutor {
     private executionBarrier;
     private resumedOwnerTurn;
     private lastActivityAtMs;
+    private lifecycleAdmissionClosed;
     activeTurnId: number;
     constructor(yieldAllowed?: boolean, sourceSpotId?: SpotId | undefined, schedulerOptions?: ZLinkSerialSchedulerOptions);
     get isExecuting(): boolean;
@@ -17,13 +23,25 @@ export declare class ZLinkSpotSerialTurnExecutor {
     get hasPendingWork(): boolean;
     get lastActivityAt(): number;
     get currentTurn(): ZLinkSpotSerialTurn | undefined;
-    /** Stops new turns while allowing turns accepted before close to complete. */
-    close(): Promise<void>;
+    /** Waits for turns admitted through the execution barrier to complete. */
+    whenIdle(): Promise<void>;
+    closeAdmission(): void;
+    /**
+     * Spot messaging §7 step 3: after Close ends this queue's admission, an Instance
+     * intent message is refused before admission as a released owner fence, and any
+     * other message finds no incarnation. Undefined while admission is open.
+     */
+    applicationAdmissionRefusal(instanceIntent: boolean): ZLinkFrameworkException | undefined;
+    /**
+     * Spot messaging §7: once Close commits Closing, membership work can no longer
+     * enter this incarnation while Instance intent messages still queue behind Close.
+     */
+    setLifecycleAdmissionClosed(closed: boolean): void;
     /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
     isActiveTurn(turn: ZLinkSpotSerialTurn, turnId: number): boolean;
     setExecutionBarrier(barrier: ZLinkExecutionBarrier): void;
     /** Runs `operation` in serial order, one turn at a time. */
-    execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions, replay?: (failure?: unknown) => Promise<T>): Promise<T>;
     /**
      * Always enqueues `operation` as its own serial turn, even when called
      * from within the currently active turn. Detached completion callbacks use
@@ -36,13 +54,18 @@ export declare class ZLinkSpotSerialTurnExecutor {
      */
     postOneWay(operation: () => Promise<unknown> | unknown, onError: (error: unknown) => void, workOptions?: ZLinkSerialWorkOptions, admission?: {
         readonly signal?: AbortSignal;
-    }): Promise<void>;
+    }, replay?: (failure?: unknown) => Promise<unknown>): Promise<void>;
     /**
      * Enqueues the framework-owned turn that completes a boundary while normal
      * application admission remains sealed. Callers must release the matching
      * barrier seal after this turn finishes.
      */
     postBarrierTurn<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T>;
+    /** Admits membership work and holds the lifecycle FIFO until its result settles. */
+    executeLifecycleOperation<T>(operation: () => Promise<T> | T): Promise<T>;
+    /** Runs owner control work that establishes or completes its own admission seal. */
+    executeControlLifecycleOperation<T>(operation: () => Promise<T> | T, context?: ZLinkSerialLifecycleContext): Promise<T>;
+    visitPendingApplication(visitor: (record: ZLinkSerialWorkRecord<unknown>) => void): void;
     private enqueueApplicationTurn;
     private enqueueFrameworkTurn;
     private enqueueContinuationTurn;