@zlink-systems/framework 0.30.0 → 0.30.1

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

@@ -36,7 +36,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, objectKind === 'user_spot'
             ? {
                 actorSendHandlers: this.options.spotActorSendHandlers,
@@ -154,7 +154,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = serialOwner?.serial ?? new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(true, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         const instanceHandlers = new spot_handler_registry_1.DefaultZLinkInstanceSpotHandlerRegistry(handlers);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, {
             packetHandlers: this.options.spotPacketHandlers
@@ -268,7 +268,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, spotType, {
             actorSendHandlers: this.options.spotActorSendHandlers,
             actorRequestHandlers: this.options.spotActorRequestHandlers,
@@ -571,7 +571,9 @@ class ZLinkSpotActivationLifecycle {
             catch (error) {
                 // An OnClosing failure is diagnostic and cleanup continues. It is
                 // returned so host shutdown can classify its teardown outcome.
-                this.options.closeErrorSink?.reportRuntimeTaskException(`spot ${String(activation.spotId)} onClosing`, error);
+                if (reason !== contracts_1.ZLinkSpotCloseReason.HostShutdown) {
+                    this.options.closeErrorSink?.reportRuntimeTaskException(`spot ${String(activation.spotId)} onClosing`, error);
+                }
                 closingFailure = error;
             }
         }
@@ -598,7 +600,12 @@ class ZLinkSpotActivationLifecycle {
             });
         }
         if (!state.nativeDisposed) {
-            await cleanup(() => activation.nativeSpot?.dispose(), () => {
+            await cleanup(async () => {
+                if (reason === contracts_1.ZLinkSpotCloseReason.HostShutdown) {
+                    await this.options.releaseActorMembers?.(locationMeshName, activation.spotId);
+                }
+                await activation.nativeSpot?.dispose();
+            }, () => {
                 state.nativeDisposed = true;
             });
         }
@@ -617,9 +624,11 @@ class ZLinkSpotActivationLifecycle {
                 state.locationReleased = true;
             });
         }
-        if (errors.length === 1)
-            throw errors[0];
-        if (errors.length > 1) {
+        if (errors.length > 0) {
+            if (closingFailure !== undefined)
+                errors.unshift(closingFailure);
+            if (errors.length === 1)
+                throw errors[0];
             throw new AggregateError(errors, `Spot '${activation.spotId}' cleanup failed.`);
         }
         return closingFailure;

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

@@ -27,7 +27,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 +43,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
@@ -182,7 +183,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');
         }

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

@@ -1,5 +1,6 @@
 import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotHandlerRegistry } 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';
@@ -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;

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,17 +70,18 @@ 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;
     }
@@ -80,6 +89,7 @@ class DefaultZLinkSpotHandlerRegistry {
         return this.addSubscribe(handlerType, channelName, topic);
     }
     addSpotHandler(handlerType) {
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({ kind: 'spotHandler', handlerType });
         return this;
     }

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

@@ -105,16 +105,17 @@ class ZLinkSpotNodeAutoConnectExecutor {
         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));
     }
     disconnect(target) {
-        if (this.manualConnections)
+        if (!this.connectionIntents.has(connectionKey(target)))
             return;
         this.disconnectPeer(target);
     }

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

@@ -35,6 +35,7 @@ export declare class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
     private requireAddressTransport;
 }
 export interface ZLinkSpotAddressCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly instanceSpot: boolean;
     readonly instanceSpotType?: string;
@@ -63,10 +64,12 @@ export interface ZLinkSpotRoutedSendOptions {
     readonly metadata?: ReadonlyMap<string, string>;
 }
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+    readonly onAdmitted?: () => void;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
 export interface ZLinkSpotHandleCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;

package/dist/runtime/spots/spot-outbound.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkSpotOutbound = void 0;
 exports.sendToSpotHandle = sendToSpotHandle;
 exports.requestToSpotHandle = requestToSpotHandle;
+const request_result_1 = require("../messaging/request-result");
 const contracts_1 = require("../../contracts");
 const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const configuration_1 = require("../configuration");
@@ -115,14 +116,13 @@ function createAddressedSpotSendCall(serial, transport, spotId, message, sourceS
 }
 function createAddressedSpotRequestCall(serial, transport, spotId, request, sourceSpotProvider) {
     const options = newAddressCallOptions();
-    const begin = (waitPolicy, signal) => {
-        markSubmitted(options);
-        rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
+    const begin = (signal, onAdmitted) => {
         return startRequestOnSerial(serial, () => ({
             pending: transport.requestToSpotAddress(spotId, request, {
                 ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
                 timeoutMs: options.timeoutMs,
-                signal
+                signal,
+                onAdmitted
             })
         }));
     };
@@ -153,12 +153,15 @@ function createAddressedSpotRequestCall(serial, transport, spotId, request, sour
             return this;
         },
         submit(signal) {
-            const pending = begin('async', signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            markSubmitted(options);
+            rejectSameSpotAsyncRequest(serial, spotId, 'async');
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
-            const pending = begin('yield', signal);
+            markSubmitted(options);
+            rejectSameSpotAsyncRequest(serial, spotId, 'yield');
+            const pending = begin(signal);
             return turn.yieldPromise(pending);
         }
     };
@@ -250,7 +253,12 @@ function wrapPublishCall(serial, inner) {
     };
 }
 function wrapRequestCall(serial, inner) {
-    const begin = (signal) => startRequestOnSerial(serial, () => ({ pending: inner.submit(signal) }));
+    const begin = (signal, onAdmitted) => startRequestOnSerial(serial, () => {
+        const pending = inner.submit(signal);
+        if (onAdmitted !== undefined)
+            void pending.admitted.then(onAdmitted, () => undefined);
+        return { pending };
+    });
     return {
         metadata(key, value) {
             if (typeof key === 'string')
@@ -264,8 +272,7 @@ function wrapRequestCall(serial, inner) {
             return this;
         },
         submit(signal) {
-            const pending = begin(signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
@@ -320,15 +327,15 @@ function wrapRoutedSpotSendCall(serial, transport, spot, message, spotRouterChan
 function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterChannelIdForMesh, sourceSpotProvider) {
     let selectedTimeoutMs;
     const metadata = new Map();
-    const begin = (waitPolicy, signal) => {
+    const begin = (signal, onAdmitted) => {
         // A request to the current Spot would wait behind the handler that owns
         // the same Spot claim. Reject it before resolving a route or submitting
         // transport work; one-way self-send remains a valid FIFO admission.
-        rejectSameSpotAsyncRequest(serial, spot.spotId, waitPolicy);
         return startRequestOnSerial(serial, () => ({
             pending: requestToSpotHandle(transport, spot, request, {
                 timeoutMs: selectedTimeoutMs,
                 signal,
+                onAdmitted,
                 metadata,
                 spotRouterChannelIdForMesh,
                 sourceSpot: sourceSpotProvider?.()
@@ -352,12 +359,13 @@ function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterC
             return this;
         },
         submit(signal) {
-            const pending = begin('async', signal);
-            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+            rejectSameSpotAsyncRequest(serial, spot.spotId, 'async');
+            return (0, request_result_1.createZLinkRequest)((onAdmitted) => begin(signal, onAdmitted), (pending) => (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending)));
         },
         yield(signal) {
             const turn = (0, execution_1.requireZLinkYieldTurn)();
-            const pending = begin('yield', signal);
+            rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
+            const pending = begin(signal);
             return turn.yieldPromise(pending);
         }
     };
@@ -395,6 +403,7 @@ async function requestToSpotHandle(transport, spot, request, options = {}) {
             packetName,
             timeoutMs: options.timeoutMs,
             signal: options.signal,
+            onAdmitted: options.onAdmitted,
             metadata: options.metadata
         };
         if (options.sourceSpot !== undefined && transport.requestFromSpotToSpot !== undefined) {

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

@@ -23,6 +23,7 @@ interface ZLinkRoutedSpotPacketDispatchOptions {
 }
 interface ZLinkRoutedSpotPacketContext {
     readonly channelName: string;
+    readonly onAdmitted?: () => void;
     readonly contentType?: string;
     readonly workOptions?: ZLinkSerialWorkOptions;
     readonly admissionTimeoutMs?: number;

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

@@ -151,7 +151,7 @@ class ZLinkRoutedSpotPacketDispatch {
                 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, instanceIntent ? runHandler : undefined);
+                await activation.serial.execute(runHandler, { ...context.workOptions, onAdmitted: context.onAdmitted }, instanceIntent ? runHandler : undefined);
             }
         }
         catch (error) {

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

@@ -8,6 +8,7 @@ import type { ZLinkActorResponseOptions } from './spot-actor-packet-dispatch';
 import type { ZLinkRemoteActorJoinActor, ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
 import type { ZLinkBackendSpotNode } from '../backend/contracts';
 export interface ZLinkEntryActorRuntime {
+    releaseMembers?(meshName: string): Promise<void>;
     resolveActor(actorId: string): ZLinkActor | undefined;
     commitActorTransaction(actor: ZLinkActor, onJoined: () => Promise<void>): Promise<void>;
     destroyActor(node: ZLinkBackendSpotNode, entryNodeRid: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;

package/dist/runtime/spots/spot-subscription-dispatch.js

@@ -31,9 +31,6 @@ class ZLinkSpotSubscriptionDispatch {
             }
             const key = subscriptionKey(registration.channelName, registration.topic);
             const existing = this.handlers.get(key) ?? [];
-            if (existing.some((entry) => entry.handlerType === registration.handlerType)) {
-                continue;
-            }
             existing.push(registration);
             this.handlers.set(key, existing);
             this.options.nativeSpot.setSubscription(registration.channelName, registration.topic);

package/dist/runtime/spots/spot-timer.js

@@ -50,6 +50,7 @@ class ZLinkSpotTimerRegistry {
     async add(name, periodMs, options, handlerType, serial, spot, providerResolver, signal, reportFailure) {
         (0, TimerRegistrationValidator_1.validateTimerRegistration)(name, periodMs, options);
         (0, abort_1.throwIfAborted)(signal);
+        (0, handler_instance_scope_1.prepareHandlerInstance)(providerResolver, handlerType);
         const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(spot, handlerType, providerResolver);
         const prepared = await this.lane.run(() => this.prepareAddCore(name));
         if (prepared.previous !== undefined)

package/dist/runtime/streams/stream-session-runtime.d.ts

@@ -134,7 +134,7 @@ export declare class ZLinkStreamSessionNodeRuntime {
     private readonly receiveAbortController;
     private receiveLoop;
     private monitorLoop;
-    private readonly receiveWake;
+    private receiveWake;
     private receiveWorkSinceYield;
     constructor(options: ZLinkStreamSessionNodeRuntimeOptions & ZLinkStreamLivenessOptions);
     start(): void;

package/dist/runtime/streams/stream-session-runtime.js

@@ -33,27 +33,6 @@ const systemLivenessClock = {
     setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
     clearTimer: (timer) => clearTimeout(timer)
 };
-class ZLinkStreamReceiveWake {
-    pending;
-    resolvePending;
-    finish = () => {
-        const resolve = this.resolvePending;
-        this.pending = undefined;
-        this.resolvePending = undefined;
-        resolve?.();
-    };
-    wait() {
-        if (this.pending !== undefined)
-            return this.pending;
-        this.pending = new Promise((resolve) => {
-            this.resolvePending = resolve;
-        });
-        return this.pending;
-    }
-    wake() {
-        this.finish();
-    }
-}
 class ZLinkStreamSessionRuntime {
     options;
     removeSession;
@@ -650,7 +629,7 @@ class ZLinkStreamSessionNodeRuntime {
     receiveAbortController = new AbortController();
     receiveLoop;
     monitorLoop;
-    receiveWake = new ZLinkStreamReceiveWake();
+    receiveWake;
     receiveWorkSinceYield = 0;
     constructor(options) {
         this.options = options;
@@ -1113,13 +1092,20 @@ class ZLinkStreamSessionNodeRuntime {
         });
     }
     async waitReceiveLoopWake(signal) {
-        await Promise.race([
-            this.options.readablePoller.waitForReadable(signal),
-            this.receiveWake.wait()
-        ]);
+        const wake = new AbortController();
+        this.receiveWake = wake;
+        try {
+            // Readiness, internal wake and shutdown share one cancellable wait;
+            // no losing Promise retains reactions across receive cycles.
+            await this.options.readablePoller.waitForReadable(AbortSignal.any([signal, wake.signal]));
+        }
+        finally {
+            wake.abort();
+            this.receiveWake = undefined;
+        }
     }
     wakeReceiveLoop() {
-        this.receiveWake.wake();
+        this.receiveWake?.abort();
     }
     getOrCreateSession(routingId) {
         const sessionId = (0, managed_stream_1.streamSessionIdFromRoutingId)(routingId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.30.0",
+  "version": "0.30.1",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.30.0",
+    "@zlink-systems/stream-wire": "0.30.1",
     "@zlink-systems/zlink": "1.19.0"
   }
 }

package/src/contracts/Actors/ZLinkActorClient.ts

@@ -1,4 +1,5 @@
 import type { ActorId } from '../Common';
+import type { ZLinkRequest } from '../Handlers/Attributes';
 
 export interface ZLinkActorClient {
   sendToActor(actorId: ActorId, message: unknown): ZLinkActorSendCall;
@@ -13,6 +14,6 @@ export interface ZLinkActorSendCall {
 export interface ZLinkActorRequestCall {
   metadata(key: string, value: string): this;
   timeout(timeoutMs: number): this;
-  submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply>;
   yield<TReply>(signal?: AbortSignal): Promise<TReply>;
 }

package/src/contracts/Channels/Calls.ts

@@ -1,4 +1,5 @@
 import type { ZLinkMessageMetadata } from '../Common';
+import type { ZLinkRequest } from '../Handlers/Attributes';
 
 export interface ZLinkSendCall {
   metadata(key: string, value: string): this;
@@ -10,7 +11,7 @@ export interface ZLinkRequestCall {
   metadata(key: string, value: string): this;
   metadata(metadata: ZLinkMessageMetadata): this;
   timeout(timeoutMs: number): this;
-  submit<TReply>(signal?: AbortSignal): Promise<TReply>;
+  submit<TReply>(signal?: AbortSignal): ZLinkRequest<TReply>;
 }
 
 export interface ZLinkChannelRequestCall extends ZLinkRequestCall {

package/src/contracts/Common/ZLinkMessageMetadata.ts

@@ -11,7 +11,7 @@ export interface ZLinkMessageMetadataPolicy {
 class ImmutableZLinkMessageMetadata implements ZLinkMessageMetadata {
   readonly values: ReadonlyMap<string, string>;
 
-  constructor(values: ReadonlyMap<string, string> | Readonly<Record<string, string>> = new Map()) {
+  constructor(values: Iterable<readonly [string, string]> = []) {
     this.values = Object.freeze(new ImmutableMetadataMap(values));
   }
 
@@ -23,12 +23,8 @@ class ImmutableZLinkMessageMetadata implements ZLinkMessageMetadata {
 class ImmutableMetadataMap implements ReadonlyMap<string, string> {
   readonly #values: Map<string, string>;
 
-  constructor(values: ReadonlyMap<string, string> | Readonly<Record<string, string>>) {
-    this.#values = new Map(
-      typeof (values as ReadonlyMap<string, string>)[Symbol.iterator] === 'function'
-        ? (values as ReadonlyMap<string, string>)
-        : Object.entries(values)
-    );
+  constructor(values: Iterable<readonly [string, string]>) {
+    this.#values = new Map(values);
   }
 
   get size(): number {
@@ -74,5 +70,14 @@ export const ZLinkMessageMetadataEmpty: ZLinkMessageMetadata = Object.freeze(
 export function zlinkMessageMetadata(
   values: ReadonlyMap<string, string> | Readonly<Record<string, string>>
 ): ZLinkMessageMetadata {
-  return Object.freeze(new ImmutableZLinkMessageMetadata(values));
+  const entries =
+    typeof (values as ReadonlyMap<string, string>)[Symbol.iterator] === 'function'
+      ? (values as ReadonlyMap<string, string>)
+      : Object.entries(values);
+  const size = Array.isArray(entries)
+    ? entries.length
+    : (entries as ReadonlyMap<string, string>).size;
+  return size === 0
+    ? ZLinkMessageMetadataEmpty
+    : Object.freeze(new ImmutableZLinkMessageMetadata(entries));
 }

package/src/contracts/Handlers/Attributes.ts

@@ -4,23 +4,25 @@ import {
   type ZLinkPacketJsonContract
 } from './JsonContract';
 
-export const ZLINK_DECORATOR_METADATA = Symbol.for('@zlink-systems/framework:decorator');
-
-export interface ZLinkDecoratorMetadata {
-  readonly kind: string;
-  readonly packetName?: string;
-  readonly groupName?: string;
-  readonly methodName?: string;
-  readonly meshName?: string;
-  readonly channelName?: string;
-  readonly topic?: string;
-  readonly jsonContract?: ZLinkPacketJsonContract;
-}
+import {
+  ZLINK_DECORATOR_METADATA,
+  readZLinkDecoratorMetadata,
+  type ZLinkDecoratorMetadata
+} from '@zlink-systems/stream-wire/internal/json';
+export {
+  ZLINK_DECORATOR_METADATA,
+  readZLinkDecoratorMetadata
+} from '@zlink-systems/stream-wire/internal/json';
+export type { ZLinkDecoratorMetadata } from '@zlink-systems/stream-wire/internal/json';
 
 export function ZLinkHandlerGroup(groupName: string): ClassDecorator {
   return classDecorator({ kind: 'handlerGroup', groupName });
 }
 
+export interface ZLinkRequest<TReply> extends Promise<TReply> {
+  readonly admitted: Promise<void>;
+}
+
 export function ZLinkRequest(packetName?: string): MethodDecorator {
   return methodDecorator({ kind: 'request', packetName });
 }
@@ -106,12 +108,3 @@ function appendMetadata(target: object, metadata: ZLinkDecoratorMetadata): void
     writable: false
   });
 }
-
-export function readZLinkDecoratorMetadata(target: object): readonly ZLinkDecoratorMetadata[] {
-  if (!Object.prototype.hasOwnProperty.call(target, ZLINK_DECORATOR_METADATA)) {
-    return [];
-  }
-  return (target as Record<symbol, unknown>)[
-    ZLINK_DECORATOR_METADATA
-  ] as readonly ZLinkDecoratorMetadata[];
-}