@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,6 +1,10 @@
 "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 actor_context_1 = require("../actors/actor-context");
+const session_disconnected_wire_1 = require("../actors/session-disconnected-wire");
+const routing_id_1 = require("../routing-id");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
@@ -12,6 +16,7 @@ const protocol_1 = require("../streams/protocol");
 const payload_codec_1 = require("../messaging/payload-codec");
 const serial_work_size_1 = require("../execution/serial-work-size");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const emptyDisconnectedReply = contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.fromOwned(Buffer.alloc(0)));
 class ZLinkSpotActorPacketDispatch {
     options;
     constructor(options) {
@@ -62,9 +67,12 @@ class ZLinkSpotActorPacketDispatch {
                 ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError
                 : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop;
             this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, actorId, header, messageKind);
-            if (this.options.actorLeft?.(actorId) === true &&
-                header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
-                return undefined;
+            const disconnected = header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET;
+            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) {
@@ -74,9 +82,23 @@ class ZLinkSpotActorPacketDispatch {
             if (actor === undefined) {
                 return this.handleMissingActor(delivery.origin, actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
             }
-            if (header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+            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;
+                }
+                const current = actor.context instanceof actor_context_1.DefaultZLinkActorContext
+                    ? actor.context.currentSessionBinding
+                    : undefined;
+                if (current !== undefined &&
+                    (!(0, routing_id_1.routingIdsEqual)(current.sessionNodeRid, identity.sessionOwnerNodeRid) ||
+                        current.sessionOwnerNodeGeneration !== identity.sessionOwnerNodeGeneration ||
+                        current.bindingGeneration !== identity.bindingGeneration))
+                    return disconnectedReply;
                 await this.options.onDisconnectActor(actor);
-                return undefined;
+                return 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)));
@@ -108,7 +130,9 @@ class ZLinkSpotActorPacketDispatch {
         if (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest) {
             return undefined;
         }
-        const missingActorError = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound, `SPOT actor is not registered locally: ${actorId}`);
+        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) {
@@ -290,7 +314,7 @@ class ZLinkSpotActorPacketDispatch {
             throw error;
         }
     }
-    reportInvalidFrame(actorId, messageKind, error) {
+    reportInvalidFrame(actorId, messageKind, error, severity) {
         this.options.dispatchErrors?.report({
             surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
             messageKind,
@@ -298,7 +322,8 @@ class ZLinkSpotActorPacketDispatch {
             action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
             spotId: this.options.spotId(),
             actorId,
-            error
+            error,
+            severity
         });
     }
     trace(outcome, actorId, header, messageKind) {

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

@@ -1,13 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorPacketDrain = void 0;
-const contracts_1 = require("../../contracts");
 const runtime_message_1 = require("../backend/runtime-message");
 const runtime_values_1 = require("../backend/runtime-values");
 const spot_remote_codec_1 = require("./spot-remote-codec");
 const spot_native_flags_1 = require("./spot-native-flags");
 const protocol_1 = require("../streams/protocol");
-const payload_codec_1 = require("../messaging/payload-codec");
+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;
 class ZLinkSpotActorPacketDrain {
     options;
@@ -143,33 +143,13 @@ class ZLinkSpotActorPacketDrain {
         }
         catch (error) {
             this.options.replyActorNoBind?.(info, [
-                this.encodeActorReplyFrame(parts[0], protocol_1.ZLinkStreamMessageKind.Error, frameworkErrorPayload(error))
+                this.encodeActorReplyFrame(parts[0], protocol_1.ZLinkStreamMessageKind.Error, (0, bound_session_response_target_1.boundSessionErrorPayload)(error))
             ], runtime_values_1.RequestResult.Ok);
         }
     }
     encodeActorReplyFrame(requestHeaderPart, kind, payload) {
-        const requestHeader = (0, protocol_1.decodeStreamHeader)((0, protocol_1.messageToBytes)(requestHeaderPart), this.flowEnabled());
-        const encoded = (0, payload_codec_1.encodeFrameworkPayload)(payload, this.options.messageSerializers, kind === protocol_1.ZLinkStreamMessageKind.Response ? requestHeader.name : undefined, 'payload');
-        try {
-            //  encodeStreamFrame returns a fresh, unaliased array; view it without re-copying.
-            const frame = (0, protocol_1.encodeStreamFrame)({
-                kind,
-                codec: (0, protocol_1.streamCodecForContentType)(encoded.contentType),
-                flags: protocol_1.ZLinkStreamHeaderFlags.None,
-                requestSeq: requestHeader.requestSeq,
-                name: '',
-                metadata: new Map(),
-                correlationId: requestHeader.correlationId,
-                // Spec 27 §7: preserve the request flow pair on the reply while
-                // tracing is on; the gated decode above already strips it at Off.
-                flowId: requestHeader.flowId,
-                flowOrigin: requestHeader.flowOrigin
-            }, encoded.message.data());
-            return runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength));
-        }
-        finally {
-            encoded.message.close();
-        }
+        const [frame] = (0, actor_reply_1.encodeActorReply)((0, protocol_1.messageToBytes)(requestHeaderPart), kind, payload, this.options.messageSerializers, this.flowEnabled());
+        return runtime_message_1.ZLinkBufferMessage.fromOwned(frame);
     }
     consumeRemoteBoundSessionBind(actor, sourceNodeRid, sourceSessionRid, parts) {
         if (parts.length < 1) {
@@ -231,11 +211,3 @@ function closeMessages(messages) {
     for (const message of messages)
         message.close();
 }
-function frameworkErrorPayload(error) {
-    return {
-        message: error instanceof Error ? error.message : String(error),
-        kind: error instanceof contracts_1.ZLinkFrameworkException
-            ? error.kind
-            : contracts_1.ZLinkFrameworkErrorKind.InternalFailure
-    };
-}

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

@@ -100,6 +100,8 @@ export declare class ZLinkEntrySpotActivation {
     notifyLeaveActor(actor: ZLinkActor, signal?: AbortSignal, _actorRef?: ActorRef, _membershipEpoch?: bigint): Promise<void>;
     notifyDisconnectActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     dispatchActorPacket(delivery: ZLinkActorPacketDelivery): Promise<unknown>;
+    /** Restores source packets through the Entry Actor's existing executor. */
+    admitActorPacketPrefix(actorId: string, records: readonly import('../actors/actor-handoff').ZLinkActorHandoffPrefixRecord[]): import('../actors/actor-handoff').ZLinkActorHandoffPrefixAdmission;
     private replayActorBacklog;
     private dispatchActorPacketInsideMailbox;
     private replyActorNoBind;

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 application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const contracts_1 = require("../../contracts");
 const abort_1 = require("../abort");
 const routing_id_1 = require("../routing-id");
@@ -27,7 +28,7 @@ class ZLinkEntrySpotActivation {
     spotSerialExecutor;
     timers;
     actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-    handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(this.actorHandlers);
+    handlers;
     outbound;
     workerRuntime;
     lifecycleMetrics;
@@ -43,6 +44,7 @@ class ZLinkEntrySpotActivation {
         if (options.detachedTaskRunner === undefined) {
             throw new configuration_1.ZLinkConfigurationException('Entry Spot activation requires a detached task runner.');
         }
+        this.handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(this.actorHandlers, options.providerResolver);
         this.serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
         this.spotSerialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(this.serial, contracts_1.ZLinkUserSpotExecutionMode.PerActor, options.nativeSpot.routingId);
         // Entry Spot lifecycle, timers and detached continuations use this serial
@@ -139,7 +141,7 @@ class ZLinkEntrySpotActivation {
             : this.packetDispatch.sendEncoded(this.spotId, packetName, decodePayload, context);
     }
     async create() {
-        const entrySpot = await (0, spot_provider_1.createProviderInstance)(this.options.entrySpotType, this.options.providerResolver, this.context);
+        const entrySpot = await (0, spot_provider_1.createFreshProviderInstance)(this.options.entrySpotType, this.options.providerResolver, this.context);
         this.entrySpot = entrySpot;
         Object.defineProperty(this.entrySpot, 'context', {
             configurable: true,
@@ -182,7 +184,10 @@ class ZLinkEntrySpotActivation {
         await cleanup(() => this.timers.dispose());
         await cleanup(() => this.spotSerialExecutor.close());
         await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(this.entrySpot, this.options.detachedTaskRunner));
-        await cleanup(() => this.options.nativeSpot.dispose());
+        await cleanup(async () => {
+            await this.options.entryActorRuntime?.releaseMembers?.(this.options.spotNodeName);
+            await this.options.nativeSpot.dispose();
+        });
         if (this.initialized) {
             this.lifecycleMetrics.closed('entry');
         }
@@ -287,18 +292,22 @@ class ZLinkEntrySpotActivation {
     }
     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, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox({
-            origin: delivery.origin,
-            actorId,
-            parts: replayedParts,
-            returnResponse: replayReturnResponse,
-            remoteBoundSessionTarget: replayRemoteBoundSessionTarget,
-            fallbackActorRef: replayFallbackActorRef
-        })));
+        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));
     }
+    /** Restores source packets through the Entry Actor's existing executor. */
+    admitActorPacketPrefix(actorId, records) {
+        return this.spotSerialExecutor.admitActorPacketPrefix(actorId, records, (_serial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.dispatchActorPacketInsideMailbox({
+            origin: (0, application_job_queue_scope_1.currentApplicationJobOrigin)(),
+            actorId,
+            parts,
+            returnResponse,
+            remoteBoundSessionTarget,
+            fallbackActorRef
+        }));
+    }
     async replayActorBacklog(actor, backlog) {
         return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.spotSerialExecutor.executeActor(actor.context.actorId, () => this.dispatchActorPacketInsideMailbox({
             origin: 'remote',

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

@@ -1,8 +1,9 @@
-import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotHandlerRegistry } from '../../contracts';
+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';
 import { ZLinkActorPacketKind, ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
 export interface ZLinkSpotHandlerRegistration {
-    readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'spotHandler';
+    readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'timer';
     readonly handlerType: Type;
     readonly packetName?: string;
     readonly channelName?: string;
@@ -11,8 +12,9 @@ export interface ZLinkSpotHandlerRegistration {
 }
 export declare class DefaultZLinkSpotHandlerRegistry<TActor extends ZLinkActor = ZLinkActor> implements ZLinkSpotHandlerRegistry {
     private readonly actorHandlers?;
+    private readonly providerResolver?;
     private readonly entries;
-    constructor(actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime | undefined);
+    constructor(actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime | undefined, providerResolver?: ZLinkProviderResolver | undefined);
     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;
@@ -22,7 +24,7 @@ export declare class DefaultZLinkSpotHandlerRegistry<TActor extends ZLinkActor =
     actorRequest(packetName: string, handlerType: Type, actorType?: Type<TActor>): this;
     addSubscribe(handlerType: Type, channelName: string, topic: string): this;
     subscribe(channelName: string, topic: string, handlerType: Type): this;
-    addSpotHandler(handlerType: Type): this;
+    addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkSpot>>(handlerType: Type<THandler>): this;
     snapshot(): readonly ZLinkSpotHandlerRegistration[];
 }
 /**
@@ -33,6 +35,7 @@ export declare class DefaultZLinkInstanceSpotHandlerRegistry implements ZLinkIns
     private readonly registrations;
     constructor(registrations: DefaultZLinkSpotHandlerRegistry);
     addPacket<THandler>(handlerType: Type<THandler>): this;
+    addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkInstanceSpot>>(handlerType: Type<THandler>): this;
     snapshot(): readonly ZLinkSpotHandlerRegistration[];
 }
 interface ZLinkEntrySpotHandlerRegistrationSet {

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

@@ -3,36 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkInstanceSpotHandlerRegistry = exports.DefaultZLinkSpotHandlerRegistry = void 0;
 exports.applyEntrySpotHandlerRegistrations = applyEntrySpotHandlerRegistrations;
 exports.applySpotHandlerRegistrations = applySpotHandlerRegistrations;
-const configuration_1 = require("../configuration");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const actors_1 = require("../actors");
 const Attributes_1 = require("../../contracts/Handlers/Attributes");
 class DefaultZLinkSpotHandlerRegistry {
     actorHandlers;
+    providerResolver;
     entries = [];
-    constructor(actorHandlers) {
+    constructor(actorHandlers, providerResolver) {
         this.actorHandlers = actorHandlers;
+        this.providerResolver = providerResolver;
     }
     addHandler(handlerType, packetName) {
         const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
         const resolvedPacketName = packetName ?? metadata?.packetName;
         if (metadata === undefined || resolvedPacketName === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor packet handler '${handlerType.name}' must declare a packet name.`);
         }
         return this.addActorPacketRegistration(metadata.kind === 'spotActorSend' ? actors_1.ZLinkActorPacketKind.Send : actors_1.ZLinkActorPacketKind.Request, handlerType, Object, resolvedPacketName);
     }
     addActorPacket(handlerType, actorType) {
         const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
         if (metadata?.packetName === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor packet handler '${handlerType.name}' must declare a packet name.`);
         }
         return this.addActorPacketRegistration(metadata.kind === 'spotActorSend' ? actors_1.ZLinkActorPacketKind.Send : actors_1.ZLinkActorPacketKind.Request, handlerType, actorType, metadata.packetName);
     }
     addPacket(handlerType, packetName) {
         const declared = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'packet')?.packetName;
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
+        const resolvedPacketName = packetName ?? declared ?? handlerType.name;
+        if (this.entries.some((entry) => entry.kind === 'packet' && entry.packetName === resolvedPacketName))
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `SPOT packet '${resolvedPacketName}' is already registered.`);
         this.entries.push({
             kind: 'packet',
             handlerType,
-            packetName: packetName ?? declared ?? handlerType.name
+            packetName: resolvedPacketName
         });
         return this;
     }
@@ -40,6 +47,7 @@ class DefaultZLinkSpotHandlerRegistry {
         return this.addPacket(handlerType, packetName);
     }
     addActorPacketRegistration(kind, handlerType, actorType, packetName) {
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({
             kind: kind === actors_1.ZLinkActorPacketKind.Send ? 'actorSend' : 'actorRequest',
             handlerType,
@@ -62,25 +70,27 @@ class DefaultZLinkSpotHandlerRegistry {
     }
     addSubscribe(handlerType, channelName, topic) {
         if (channelName.trim().length === 0) {
-            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe channel name must not be empty.');
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'SPOT subscribe channel name must not be empty.');
         }
         if (topic.trim().length === 0) {
-            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe topic must not be empty.');
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'SPOT subscribe topic must not be empty.');
         }
         if (this.entries.some((entry) => entry.kind === 'subscribe' &&
             entry.handlerType === handlerType &&
             entry.channelName === channelName &&
             entry.topic === topic)) {
-            return this;
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `SPOT subscription '${channelName}/${topic}' is already registered.`);
         }
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({ kind: 'subscribe', handlerType, channelName, topic });
         return this;
     }
     subscribe(channelName, topic, handlerType) {
         return this.addSubscribe(handlerType, channelName, topic);
     }
-    addSpotHandler(handlerType) {
-        this.entries.push({ kind: 'spotHandler', handlerType });
+    addTimerHandler(handlerType) {
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
+        this.entries.push({ kind: 'timer', handlerType });
         return this;
     }
     snapshot() {
@@ -101,6 +111,10 @@ class DefaultZLinkInstanceSpotHandlerRegistry {
         this.registrations.addPacket(handlerType);
         return this;
     }
+    addTimerHandler(handlerType) {
+        this.registrations.addTimerHandler(handlerType);
+        return this;
+    }
     snapshot() {
         return this.registrations.snapshot();
     }

package/dist/runtime/spots/spot-manager-internal-contracts.d.ts

@@ -4,7 +4,7 @@ export interface ZLinkLocalSpotCreateResult {
     readonly state: ZLinkSpotCreateState;
     readonly reply?: unknown;
     readonly publication?: {
-        publish(): void;
-        abort(): void;
+        publish(): void | Promise<void>;
+        abort(): void | Promise<void>;
     };
 }

package/dist/runtime/spots/spot-manager-public.js

@@ -123,7 +123,7 @@ class ZLinkPublicSpotManager {
             yield: (signal) => {
                 const yieldTurn = (0, execution_1.requireZLinkYieldTurn)(turn);
                 const pending = this.submit(spotId, stableType, generatedIdentity, state, signal);
-                return yieldTurn.yieldPromise(pending);
+                return yieldTurn.yieldFrameworkPromise(pending);
             }
         };
         return call;
@@ -166,7 +166,7 @@ class ZLinkPublicSpotManager {
                 };
             }
             catch (error) {
-                this.options.local.abortUserSpotPublication(target.meshName, spotId);
+                await this.options.local.abortUserSpotPublication(target.meshName, spotId);
                 throw error;
             }
         }, async (cleanupSignal) => {

package/dist/runtime/spots/spot-node-autoconnect.d.ts

@@ -4,13 +4,14 @@ import type { ZLinkDomainLocationStore as ZLinkLocationStore } from '../location
 import type { ZLinkPeerLocation } from '../../contracts/Locations/Rows';
 import type { ZLinkSpotNodeOptions } from '../configuration';
 import type { ZLinkBackendMeshNode } from '../backend/contracts';
-import { ZLinkLocationRuntime, ZLinkOwnerLeaseTracker, type IZLinkAutoConnectExecutor, type ZLinkAutoConnectLocal, type ZLinkLocationEventSink, type ZLinkLocationRuntimeStores } from '../locations';
+import { ZLinkLocationRuntime, ZLinkOwnerLeaseTracker, ZLinkRequestSourceResolver, type IZLinkAutoConnectExecutor, type ZLinkAutoConnectLocal, type ZLinkLocationEventSink, type ZLinkLocationRuntimeStores } from '../locations';
 export interface ZLinkSpotNodeLocationAutoConnectContext {
     readonly runtime: ZLinkLocationRuntime;
     readonly stores: ZLinkLocationRuntimeStores;
     readonly options: ZLinkLocationOptionOverrides;
     readonly leaseTracker: ZLinkOwnerLeaseTracker;
     readonly resolver: ZLinkPeerLocationResolver;
+    readonly requestSources: ZLinkRequestSourceResolver;
     readonly events?: ZLinkLocationEventSink;
     readonly changeStampStore?: Pick<ZLinkLocationStore, 'getMeshNodeChangeStamp'>;
 }

package/dist/runtime/spots/spot-node-autoconnect.js

@@ -2,12 +2,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSpotNodeLocationAutoConnectContext = createSpotNodeLocationAutoConnectContext;
 exports.spotNodeAutoConnectCapability = spotNodeAutoConnectCapability;
+const routing_id_1 = require("../routing-id");
 const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const Values_1 = require("../../contracts/Locations/Values");
 const contracts_1 = require("../../contracts");
-const node_async_hooks_1 = require("node:async_hooks");
 const state_lane_1 = require("../execution/state-lane");
-const routing_id_1 = require("../routing-id");
+const routing_id_2 = require("../routing-id");
 const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
 const locations_1 = require("../locations");
 function createSpotNodeLocationAutoConnectContext(runtime, stores, options, events) {
@@ -15,12 +15,17 @@ function createSpotNodeLocationAutoConnectContext(runtime, stores, options, even
         store: stores.ownerLeaseStore,
         options
     });
+    const requestSources = new locations_1.ZLinkRequestSourceResolver({
+        listLiveMeshNodes: (meshName, signal) => runtime.listLiveMeshNodes(meshName, signal),
+        remainingOwnerTokenLeaseMs: (owner, signal) => runtime.remainingOwnerTokenLeaseMs(owner, signal)
+    });
     return {
         runtime,
         stores,
         options,
         leaseTracker,
-        resolver: meshDescriptorPeerResolver(runtime),
+        resolver: meshDescriptorPeerResolver(runtime, requestSources),
+        requestSources,
         events,
         // The opaque provider has no cross-process change notification primitive.
         // A process-local inherited stamp would hide descriptors written by peers,
@@ -46,13 +51,12 @@ function spotNodeAutoConnectCapability(spotNodeName, spotNode, node) {
         objectRole: spotNode.objectRole ?? 'none',
         hasRouteMeshServerChannel: Object.values(spotNode.meshChannels ?? {}).some((channel) => channel.server === true)
     };
-    const manualConnections = hasManualRouterConnections(spotNode);
     return {
         local,
-        executor: new ZLinkSpotNodeAutoConnectExecutor(node, manualConnections)
+        executor: new ZLinkSpotNodeAutoConnectExecutor(node)
     };
 }
-function meshDescriptorPeerResolver(runtime) {
+function meshDescriptorPeerResolver(runtime, requestSources) {
     return {
         async listLivePeers(filter, signal) {
             if (filter.meshName === undefined ||
@@ -62,6 +66,8 @@ function meshDescriptorPeerResolver(runtime) {
                 return [];
             }
             const descriptors = await runtime.listLiveMeshNodes(filter.meshName, signal);
+            // The auto-connect poll owns the live descriptors; request acceptance reads them.
+            await requestSources.observeLiveDescriptors(filter.meshName, descriptors, signal);
             return descriptors
                 .map((descriptor) => ({
                 autoConnectType: Values_1.ZLinkLocationAutoConnectType.RouteMesh,
@@ -82,59 +88,36 @@ function meshDescriptorPeerResolver(runtime) {
                     securityIdentity: descriptor.securityIdentity
                 }
             }))
-                .filter((peer) => (filter.nodeRid === undefined || String(peer.nodeRid) === String(filter.nodeRid)) &&
+                .filter((peer) => (filter.nodeRid === undefined || (0, routing_id_1.routingIdsEqual)(peer.nodeRid, filter.nodeRid)) &&
                 (filter.endpoint === undefined || peer.endpoint === filter.endpoint));
         }
     };
 }
-function hasManualRouterConnections(spotNode) {
-    return ((spotNode.router?.manualConnections?.length ?? 0) > 0 ||
-        (spotNode.router?.manualPeerConnections?.length ?? 0) > 0);
-}
-const detachedSpotNodeAutoConnectResource = new node_async_hooks_1.AsyncResource('zlink:spot-node-autoconnect');
 class ZLinkSpotNodeAutoConnectExecutor {
     node;
-    manualConnections;
     lane = new state_lane_1.ZLinkStateLane();
     connectionIntents = new Map();
-    constructor(node, manualConnections) {
+    constructor(node) {
         this.node = node;
-        this.manualConnections = manualConnections;
     }
     onDisconnected(handler) {
         this.node.onPeerDisconnected?.(handler);
     }
     async connect(target) {
-        if (this.manualConnections)
-            return false;
         const key = connectionKey(target);
+        if (!this.connectionIntents.has(key) &&
+            this.node.hasPeerRouteOrConnectionIntent?.(target.nodeRid, target.endpoint) === true)
+            return false;
         const intent = await this.lane.run(() => this.prepareConnectCore(key));
         if (intent === undefined)
             return true;
-        return await runDetachedSpotNodeAutoConnect(() => this.connectPeer(target, key, intent));
+        return await (0, state_lane_1.startOutsideStateLane)(() => this.connectPeer(target, key, intent));
     }
     disconnect(target) {
-        if (this.manualConnections)
+        if (!this.connectionIntents.has(connectionKey(target)))
             return;
         this.disconnectPeer(target);
     }
-    disconnectStalePeers(targets) {
-        if (this.manualConnections)
-            return;
-        const current = new Map(targets
-            .filter((target) => target.nodeRid !== undefined)
-            .map((target) => [String(target.nodeRid), target]));
-        const peers = this.node.peers();
-        for (const peer of peers) {
-            if (peer.routingId === null)
-                continue;
-            const target = current.get(String(peer.routingId));
-            if (target !== undefined && peer.endpoint === target.endpoint) {
-                continue;
-            }
-            this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
-        }
-    }
     isDisconnected(target) {
         // A connect intent still owns transport state even when its peer has not
         // reached the admitted table yet. Shutdown must remove that intent before
@@ -145,7 +128,7 @@ class ZLinkSpotNodeAutoConnectExecutor {
             .peers()
             .some((peer) => peer.routingId !== null &&
             peer.endpoint === target.endpoint &&
-            (target.nodeRid === undefined || String(peer.routingId) === String(target.nodeRid)) &&
+            (target.nodeRid === undefined || (0, routing_id_1.routingIdsEqual)(peer.routingId, target.nodeRid)) &&
             peer.lifecycleGeneration === target.lifecycleGeneration &&
             peer.state === service_runtime_contracts_1.MeshPeerRuntimeState.Serving);
     }
@@ -182,7 +165,7 @@ class ZLinkSpotNodeAutoConnectExecutor {
     async connectPeer(target, key, intent) {
         const connectionIntentId = await this.node.connectPeer({
             endpoint: target.endpoint,
-            expectedRid: target.nodeRid === undefined ? undefined : (0, routing_id_1.toBackendRoutingId)(target.nodeRid),
+            expectedRid: target.nodeRid === undefined ? undefined : (0, routing_id_2.toBackendRoutingId)(target.nodeRid),
             expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
             expectedLifecycleGeneration: target.lifecycleGeneration
         });
@@ -212,16 +195,13 @@ class ZLinkSpotNodeAutoConnectExecutor {
             if (peer.endpoint !== target.endpoint) {
                 continue;
             }
-            if (target.nodeRid !== undefined && String(peer.routingId) !== String(target.nodeRid)) {
+            if (target.nodeRid !== undefined && !(0, routing_id_1.routingIdsEqual)(peer.routingId, target.nodeRid)) {
                 continue;
             }
             this.node.disconnectPeer(peer.routingId, peer.lifecycleGeneration);
         }
     }
 }
-function runDetachedSpotNodeAutoConnect(work) {
-    return detachedSpotNodeAutoConnectResource.runInAsyncScope(work);
-}
 function connectionKey(target) {
     return `${target.nodeRid ?? ''}\0${target.lifecycleGeneration}\0${target.endpoint}`;
 }