@zlink-systems/framework 0.26.0 → 0.28.0

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,18 +1,18 @@
 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>;
 }
 interface ZLinkSpotRoutedActorAdmissionOptions {
     readonly serial: ZLinkSpotSerialTurnExecutor;
-    readonly isSpotClosing?: () => boolean;
     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,7 +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 framework_errors_internal_1 = require("../framework-errors-internal");
+const DEFAULT_PENDING_ADMISSION_TIMEOUT_MS = 30_000;
 class ZLinkSpotRoutedActorAdmission {
     options;
     pending = new Map();
@@ -22,15 +22,6 @@ class ZLinkSpotRoutedActorAdmission {
         if (decoded === undefined) {
             return false;
         }
-        if (this.options.isSpotClosing?.() === true) {
-            try {
-                (0, spot_route_replies_1.submitRoutedActorJoinError)(received, decoded, (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `Actor '${decoded.actorId}' target Spot is closing.`));
-            }
-            finally {
-                this.closeDecoded(decoded);
-            }
-            return true;
-        }
         if (decoded.phase === 'admission') {
             await this.admitTransfer(decoded, received);
             return true;
@@ -149,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),
@@ -193,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

@@ -17,12 +17,11 @@ interface ZLinkRoutedFrameAdmissionTarget {
 interface ZLinkSpotRoutedFrameDispatchOptions {
     readonly nativeSpotId: string;
     readonly serial: ZLinkSpotSerialTurnExecutor;
-    readonly isSpotClosing?: () => boolean;
     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>;

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

@@ -40,7 +40,6 @@ class ZLinkSpotRoutedFrameDispatch {
         });
         this.routedActorAdmission = new spot_routed_actor_admission_1.ZLinkSpotRoutedActorAdmission({
             serial: options.serial,
-            isSpotClosing: options.isSpotClosing,
             getTarget: options.getTarget,
             defaultAccept: options.defaultAccept,
             routedActorTransferProvider: options.routedActorTransferProvider,

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

@@ -17,41 +17,27 @@ export interface ZLinkEntryActorRuntime {
 }
 export interface ZLinkSpotActorTransferRuntime {
     prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;
-    deliverDeferredJoinAccepted(completion: ZLinkDeferredJoinCompletion, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<void>;
+    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.js

@@ -71,7 +71,7 @@ class ZLinkSpotSerialExecutor {
      */
     close() {
         const children = this.closeChildren();
-        return Promise.all([children, this.spotSerial.close()]).then(() => undefined);
+        return Promise.all([children, this.spotSerial.whenIdle()]).then(() => undefined);
     }
     /**
      * Closes the Actor and timer queues. The Spot queue stays open for the Spot
@@ -87,7 +87,7 @@ class ZLinkSpotSerialExecutor {
         this.timerSerials.clear();
         this.actorExecutors.clear();
         this.closePromise = Promise.all([
-            ...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,14 +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
@@ -37,15 +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>;
-    /** Holds this Spot's lifecycle FIFO until the full operation result settles. */
+    /** 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;

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

@@ -14,6 +14,7 @@ class ZLinkSpotSerialTurnExecutor {
     executionBarrier;
     resumedOwnerTurn;
     lastActivityAtMs = performance.now();
+    lifecycleAdmissionClosed = false;
     activeTurnId = 0;
     constructor(yieldAllowed = true, sourceSpotId, schedulerOptions) {
         this.yieldAllowed = yieldAllowed;
@@ -35,13 +36,32 @@ class ZLinkSpotSerialTurnExecutor {
     get currentTurn() {
         return (0, execution_1.captureZLinkSpotSerialTurn)(this);
     }
-    /** Stops new turns while allowing turns accepted before close to complete. */
-    close() {
-        return this.scheduler.close();
+    /** Waits for turns admitted through the execution barrier to complete. */
+    whenIdle() {
+        return this.scheduler.whenIdle();
     }
     closeAdmission() {
         this.scheduler.closeAdmission();
     }
+    /**
+     * 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) {
+        if (!this.scheduler.admissionClosed)
+            return undefined;
+        return instanceIntent
+            ? (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving, 'The Spot incarnation released its authority before admitting this Instance intent message.')
+            : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, 'The Spot incarnation is closed.');
+    }
+    /**
+     * 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) {
+        this.lifecycleAdmissionClosed = closed;
+    }
     /** Distinguishes a gate-owning turn from a suspended AsyncLocalStorage tail. */
     isActiveTurn(turn, turnId) {
         return (this.depth > 0 &&
@@ -57,11 +77,11 @@ class ZLinkSpotSerialTurnExecutor {
         this.executionBarrier = barrier;
     }
     /** Runs `operation` in serial order, one turn at a time. */
-    execute(operation, workOptions) {
+    execute(operation, workOptions, replay) {
         if (this.isCurrentTurn) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'A Spot serial turn cannot implicitly execute another turn for the same owner.');
         }
-        return this.enqueueApplicationTurn(operation, workOptions);
+        return this.enqueueApplicationTurn(operation, workOptions, replay);
     }
     /**
      * Always enqueues `operation` as its own serial turn, even when called
@@ -75,11 +95,18 @@ class ZLinkSpotSerialTurnExecutor {
      * Queues a one-way turn in serial order. Handler completion is reported
      * through `onError` and never blocks the sender turn.
      */
-    async postOneWay(operation, onError, workOptions = {}, admission = {}) {
+    async postOneWay(operation, onError, workOptions = {}, admission = {}, replay) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
-            barrierClaim = await this.executionBarrier?.enter();
+            const entry = this.executionBarrier?.enter();
+            barrierClaim = entry instanceof Promise ? await entry : entry;
+            const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+            if (refusal !== undefined)
+                throw refusal;
+            if (barrierClaim !== undefined && replay !== undefined) {
+                Object.assign(barrierClaim, { replay: (0, application_job_queue_scope_1.bindApplicationJobPermit)(replay) });
+            }
             if (admission.signal?.aborted === true) {
                 throw new DOMException('The operation was aborted.', 'AbortError');
             }
@@ -112,15 +139,55 @@ class ZLinkSpotSerialTurnExecutor {
     postBarrierTurn(operation, workOptions) {
         return this.enqueueFrameworkTurn(operation, workOptions);
     }
-    /** Holds this Spot's lifecycle FIFO until the full operation result settles. */
+    /** Admits membership work and holds the lifecycle FIFO until its result settles. */
     executeLifecycleOperation(operation) {
-        return this.scheduler.submitLifecycleOperation(operation);
+        let entry;
+        try {
+            if (this.lifecycleAdmissionClosed) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, 'Spot lifecycle admission is closed by a committed Close.');
+            }
+            entry = this.executionBarrier?.enter();
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        const submit = (claim) => {
+            try {
+                return this.scheduler.submitLifecycleOperation(operation);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            finally {
+                claim?.release();
+            }
+        };
+        return entry instanceof Promise ? entry.then(submit) : submit(entry);
     }
-    async enqueueApplicationTurn(operation, workOptions = {}) {
+    /** Runs owner control work that establishes or completes its own admission seal. */
+    executeControlLifecycleOperation(operation, context) {
+        try {
+            return this.scheduler.submitLifecycleOperation(operation, context);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    visitPendingApplication(visitor) {
+        this.scheduler.visitPendingApplication(visitor);
+    }
+    async enqueueApplicationTurn(operation, workOptions = {}, replay) {
         this.lastActivityAtMs = performance.now();
         let barrierClaim;
         try {
-            barrierClaim = await this.executionBarrier?.enter();
+            const entry = this.executionBarrier?.enter();
+            barrierClaim = entry instanceof Promise ? await entry : entry;
+            const refusal = this.applicationAdmissionRefusal(replay !== undefined);
+            if (refusal !== undefined)
+                throw refusal;
+            if (barrierClaim !== undefined && replay !== undefined) {
+                Object.assign(barrierClaim, { replay: (0, application_job_queue_scope_1.bindApplicationJobPermit)(replay) });
+            }
             return await this.submitQueuedTurn(operation, workOptions, barrierClaim);
         }
         catch (error) {
@@ -152,6 +219,11 @@ class ZLinkSpotSerialTurnExecutor {
             : this.scheduler.submit(boundOperation, options, barrierClaim);
     }
     runQueuedRecord(record) {
+        const context = record.context;
+        if (context?.replay !== undefined && record.operation === context.replay) {
+            context.release();
+            return Promise.resolve(this.executionBarrier?.enter()).then((claim) => this.runTurn(record.operation, (value) => record.resolve(value), (error) => record.reject(error), claim, record.release));
+        }
         return this.runTurn(record.operation, (value) => record.resolve(value), (error) => record.reject(error), record.context, record.release);
     }
     yieldPromise(pending) {

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

@@ -6,10 +6,11 @@ import type { ZLinkEntrySpotTimerHandlerRegistration, ZLinkSpotTimerHandlerRegis
 import { ZLinkTimerOverrunPolicy } from '../../contracts';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 import type { ZLinkExecutionBarrier } from '../execution';
-import type { OperationClock } from '../foundation/operation-registry';
-export interface ZLinkTimerClock extends OperationClock {
+export interface ZLinkTimerClock {
     now(): number;
     utcNow(): number;
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
 }
 type ZLinkTimerOwnerSpot = ZLinkSpot | ZLinkEntrySpot;
 type ZLinkTimerFailureReporter = (tick: ZLinkTimerTick, cause: unknown, event?: ZLinkSpotEventKind.TimerHandlerFailed | ZLinkSpotEventKind.TimerStoppedAfterUnhandledException) => Promise<void> | void;