@zlink-systems/framework 0.30.0 → 0.30.1

package/src/runtime/spots/spot-entry-activation.ts

@@ -106,7 +106,7 @@ export class ZLinkEntrySpotActivation {
   private readonly spotSerialExecutor: ZLinkSpotSerialExecutor;
   private readonly timers: ZLinkSpotTimerRegistry;
   private readonly actorHandlers = new ZLinkSpotActorHandlerRegistryRuntime();
-  private readonly handlers = new DefaultZLinkSpotHandlerRegistry(this.actorHandlers);
+  private readonly handlers: DefaultZLinkSpotHandlerRegistry;
   private readonly outbound: DefaultZLinkSpotOutbound;
   private readonly workerRuntime: ZLinkWorkerRuntime;
   private readonly lifecycleMetrics: ZLinkSpotLifecycleMetrics;
@@ -125,6 +125,10 @@ export class ZLinkEntrySpotActivation {
         'Entry Spot activation requires a detached task runner.'
       );
     }
+    this.handlers = new DefaultZLinkSpotHandlerRegistry(
+      this.actorHandlers,
+      options.providerResolver
+    );
     this.serial = new ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
     this.spotSerialExecutor = new ZLinkSpotSerialExecutor(
       this.serial,
@@ -328,7 +332,10 @@ export class ZLinkEntrySpotActivation {
     await cleanup(() => this.timers.dispose());
     await cleanup(() => this.spotSerialExecutor.close());
     await cleanup(() => 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/src/runtime/spots/spot-handler-registry.ts

@@ -16,7 +16,12 @@ import type {
   ZLinkSpotPacketHandlerRegistration,
   ZLinkSpotSubscriptionHandlerRegistration
 } from '../../contracts/Configuration/RegistrationTypes';
-import { ZLinkConfigurationException } from '../configuration';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { prepareHandlerInstance } from '../handlers/handler-instance-scope';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import { ZLinkActorPacketKind, ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
 import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
 
@@ -34,7 +39,10 @@ export class DefaultZLinkSpotHandlerRegistry<
 > implements ZLinkSpotHandlerRegistry {
   private readonly entries: ZLinkSpotHandlerRegistration[] = [];
 
-  constructor(private readonly actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime) {}
+  constructor(
+    private readonly actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime,
+    private readonly providerResolver?: ZLinkProviderResolver
+  ) {}
 
   addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this {
     const metadata = readZLinkDecoratorMetadata(handlerType).find(
@@ -42,7 +50,8 @@ export class DefaultZLinkSpotHandlerRegistry<
     );
     const resolvedPacketName = packetName ?? metadata?.packetName;
     if (metadata === undefined || resolvedPacketName === undefined) {
-      throw new ZLinkConfigurationException(
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
         `Actor packet handler '${handlerType.name}' must declare a packet name.`
       );
     }
@@ -62,7 +71,8 @@ export class DefaultZLinkSpotHandlerRegistry<
       (entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest'
     );
     if (metadata?.packetName === undefined) {
-      throw new ZLinkConfigurationException(
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
         `Actor packet handler '${handlerType.name}' must declare a packet name.`
       );
     }
@@ -78,10 +88,21 @@ export class DefaultZLinkSpotHandlerRegistry<
     const declared = readZLinkDecoratorMetadata(handlerType).find(
       (entry) => entry.kind === 'packet'
     )?.packetName;
+    prepareHandlerInstance(this.providerResolver, handlerType);
+    const resolvedPacketName = packetName ?? declared ?? handlerType.name;
+    if (
+      this.entries.some(
+        (entry) => entry.kind === 'packet' && entry.packetName === resolvedPacketName
+      )
+    )
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        `SPOT packet '${resolvedPacketName}' is already registered.`
+      );
     this.entries.push({
       kind: 'packet',
       handlerType,
-      packetName: packetName ?? declared ?? handlerType.name
+      packetName: resolvedPacketName
     });
     return this;
   }
@@ -96,6 +117,7 @@ export class DefaultZLinkSpotHandlerRegistry<
     actorType: Type<TActor>,
     packetName: string
   ): this {
+    prepareHandlerInstance(this.providerResolver, handlerType);
     this.entries.push({
       kind: kind === ZLinkActorPacketKind.Send ? 'actorSend' : 'actorRequest',
       handlerType,
@@ -139,10 +161,16 @@ export class DefaultZLinkSpotHandlerRegistry<
 
   addSubscribe(handlerType: Type, channelName: string, topic: string): this {
     if (channelName.trim().length === 0) {
-      throw new ZLinkConfigurationException('SPOT subscribe channel name must not be empty.');
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'SPOT subscribe channel name must not be empty.'
+      );
     }
     if (topic.trim().length === 0) {
-      throw new ZLinkConfigurationException('SPOT subscribe topic must not be empty.');
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        'SPOT subscribe topic must not be empty.'
+      );
     }
     if (
       this.entries.some(
@@ -153,8 +181,12 @@ export class DefaultZLinkSpotHandlerRegistry<
           entry.topic === topic
       )
     ) {
-      return this;
+      throw createInternalFrameworkException(
+        ZLinkFrameworkInternalErrorKind.InvalidOperation,
+        `SPOT subscription '${channelName}/${topic}' is already registered.`
+      );
     }
+    prepareHandlerInstance(this.providerResolver, handlerType);
     this.entries.push({ kind: 'subscribe', handlerType, channelName, topic });
     return this;
   }
@@ -164,6 +196,7 @@ export class DefaultZLinkSpotHandlerRegistry<
   }
 
   addSpotHandler(handlerType: Type): this {
+    prepareHandlerInstance(this.providerResolver, handlerType);
     this.entries.push({ kind: 'spotHandler', handlerType });
     return this;
   }

package/src/runtime/spots/spot-node-autoconnect.ts

@@ -164,15 +164,19 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
   }
 
   async connect(target: ZLinkAutoConnectTarget): Promise<boolean> {
-    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: ZLinkAutoConnectTarget): void {
-    if (this.manualConnections) return;
+    if (!this.connectionIntents.has(connectionKey(target))) return;
     this.disconnectPeer(target);
   }
 

package/src/runtime/spots/spot-outbound.ts

@@ -1,3 +1,4 @@
+import { createZLinkRequest } from '../messaging/request-result';
 import {
   type RoutingId,
   type ZLinkChannelClient,
@@ -174,6 +175,7 @@ export class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
 }
 
 export interface ZLinkSpotAddressCallOptions {
+  readonly onAdmitted?: () => void;
   readonly metadata?: ReadonlyMap<string, string>;
   readonly instanceSpot: boolean;
   readonly instanceSpotType?: string;
@@ -232,6 +234,7 @@ export interface ZLinkSpotRoutedSendOptions {
 }
 
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+  readonly onAdmitted?: () => void;
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal;
 }
@@ -308,14 +311,13 @@ function createAddressedSpotRequestCall(
   sourceSpotProvider?: () => ZLinkBackendSpot | undefined
 ): ZLinkSpotRequestCall {
   const options = newAddressCallOptions();
-  const begin = <TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal) => {
-    markSubmitted(options);
-    rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) => {
     return startRequestOnSerial<TReply>(serial, () => ({
       pending: transport.requestToSpotAddress<TReply>(spotId, request, {
         ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
         timeoutMs: options.timeoutMs,
-        signal
+        signal,
+        onAdmitted
       })
     }));
   };
@@ -356,12 +358,18 @@ function createAddressedSpotRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>('async', signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      markSubmitted(options);
+      rejectSameSpotAsyncRequest(serial, spotId, 'async');
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
-      const pending = begin<TReply>('yield', signal);
+      markSubmitted(options);
+      rejectSameSpotAsyncRequest(serial, spotId, 'yield');
+      const pending = begin<TReply>(signal);
       return turn.yieldPromise(pending);
     }
   };
@@ -475,8 +483,12 @@ function wrapRequestCall(
   serial: ZLinkSpotSerialTurnExecutor,
   inner: ZLinkChannelRequestCall
 ): ZLinkChannelRequestCall {
-  const begin = <TReply>(signal?: AbortSignal) =>
-    startRequestOnSerial(serial, () => ({ pending: inner.submit<TReply>(signal) }));
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) =>
+    startRequestOnSerial(serial, () => {
+      const pending = inner.submit<TReply>(signal);
+      if (onAdmitted !== undefined) void pending.admitted.then(onAdmitted, () => undefined);
+      return { pending };
+    });
   return {
     metadata(key: string | ZLinkMessageMetadata, value?: string) {
       if (typeof key === 'string') inner.metadata(key, value!);
@@ -488,8 +500,10 @@ function wrapRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>(signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
@@ -571,15 +585,15 @@ function wrapRoutedSpotRequestCall(
 ): ZLinkRequestCall & Pick<ZLinkChannelRequestCall, 'yield'> {
   let selectedTimeoutMs: number | undefined;
   const metadata = new Map<string, string>();
-  const begin = <TReply>(waitPolicy: 'async' | 'yield', signal?: AbortSignal) => {
+  const begin = <TReply>(signal?: AbortSignal, onAdmitted?: () => void) => {
     // 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<TReply>(serial, () => ({
       pending: requestToSpotHandle<TReply>(transport, spot, request, {
         timeoutMs: selectedTimeoutMs,
         signal,
+        onAdmitted,
         metadata,
         spotRouterChannelIdForMesh,
         sourceSpot: sourceSpotProvider?.()
@@ -602,12 +616,16 @@ function wrapRoutedSpotRequestCall(
       return this;
     },
     submit<TReply>(signal?: AbortSignal) {
-      const pending = begin<TReply>('async', signal);
-      return serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending);
+      rejectSameSpotAsyncRequest(serial, spot.spotId, 'async');
+      return createZLinkRequest(
+        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
+      );
     },
     yield<TReply>(signal?: AbortSignal) {
       const turn = requireZLinkYieldTurn();
-      const pending = begin<TReply>('yield', signal);
+      rejectSameSpotAsyncRequest(serial, spot.spotId, 'yield');
+      const pending = begin<TReply>(signal);
       return turn.yieldPromise(pending);
     }
   };
@@ -628,6 +646,7 @@ function rejectSameSpotAsyncRequest(
 }
 
 export interface ZLinkSpotHandleCallOptions {
+  readonly onAdmitted?: () => void;
   readonly metadata?: ReadonlyMap<string, string>;
   readonly timeoutMs?: number;
   readonly signal?: AbortSignal;
@@ -672,6 +691,7 @@ export async function requestToSpotHandle<TReply = unknown>(
       packetName,
       timeoutMs: options.timeoutMs,
       signal: options.signal,
+      onAdmitted: options.onAdmitted,
       metadata: options.metadata
     };
     if (options.sourceSpot !== undefined && transport.requestFromSpotToSpot !== undefined) {

package/src/runtime/spots/spot-routed-spot-packet-dispatch.ts

@@ -50,6 +50,7 @@ interface ZLinkRoutedSpotPacketDispatchOptions {
 
 interface ZLinkRoutedSpotPacketContext {
   readonly channelName: string;
+  readonly onAdmitted?: () => void;
   readonly contentType?: string;
   readonly workOptions?: ZLinkSerialWorkOptions;
   readonly admissionTimeoutMs?: number;
@@ -265,7 +266,7 @@ export class ZLinkRoutedSpotPacketDispatch {
         }
         await activation.serial.execute(
           runHandler,
-          context.workOptions,
+          { ...context.workOptions, onAdmitted: context.onAdmitted },
           instanceIntent ? runHandler : undefined
         );
       }

package/src/runtime/spots/spot-runtime-ports.ts

@@ -22,6 +22,7 @@ import type {
 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(

package/src/runtime/spots/spot-subscription-dispatch.ts

@@ -68,9 +68,6 @@ export 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/src/runtime/spots/spot-timer.ts

@@ -19,7 +19,10 @@ import { ZLinkTimerOverrunPolicy } from '../../contracts';
 import { validateTimerRegistration } from '../../contracts/Configuration/TimerRegistrationValidator';
 import { throwIfAborted } from '../abort';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import { resolveLifecycleHandler } from '../handlers/handler-instance-scope';
+import {
+  prepareHandlerInstance,
+  resolveLifecycleHandler
+} from '../handlers/handler-instance-scope';
 import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
 import type { ZLinkExecutionBarrier } from '../execution';
 import { ZLinkStateLane } from '../execution/state-lane';
@@ -135,6 +138,7 @@ export class ZLinkSpotTimerRegistry {
   ): Promise<ZLinkTimer> {
     validateTimerRegistration(name, periodMs, options);
     throwIfAborted(signal);
+    prepareHandlerInstance(providerResolver, handlerType);
     const handler = await resolveLifecycleHandler(spot, handlerType, providerResolver);
     const prepared = await this.lane.run(() => this.prepareAddCore(name));
     if (prepared.previous !== undefined) await prepared.previous.timer.cancel(signal);

package/src/runtime/streams/stream-session-runtime.ts

@@ -95,29 +95,6 @@ const systemLivenessClock: ZLinkStreamLivenessClock = {
   clearTimer: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>)
 };
 
-class ZLinkStreamReceiveWake {
-  private pending?: Promise<void>;
-  private resolvePending?: () => void;
-  private readonly finish = (): void => {
-    const resolve = this.resolvePending;
-    this.pending = undefined;
-    this.resolvePending = undefined;
-    resolve?.();
-  };
-
-  wait(): Promise<void> {
-    if (this.pending !== undefined) return this.pending;
-    this.pending = new Promise<void>((resolve) => {
-      this.resolvePending = resolve;
-    });
-    return this.pending;
-  }
-
-  wake(): void {
-    this.finish();
-  }
-}
-
 export interface ZLinkStreamSessionContextFactory {
   createSessionContext(
     stream: ZLinkManagedStream,
@@ -928,7 +905,7 @@ export class ZLinkStreamSessionNodeRuntime {
   private readonly receiveAbortController = new AbortController();
   private receiveLoop: Promise<void> | undefined;
   private monitorLoop: Promise<void> | undefined;
-  private readonly receiveWake = new ZLinkStreamReceiveWake();
+  private receiveWake: AbortController | undefined;
   private receiveWorkSinceYield = 0;
   constructor(
     private readonly options: ZLinkStreamSessionNodeRuntimeOptions & ZLinkStreamLivenessOptions
@@ -1455,14 +1432,20 @@ export class ZLinkStreamSessionNodeRuntime {
   }
 
   private async waitReceiveLoopWake(signal: AbortSignal): Promise<void> {
-    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;
+    }
   }
 
   private wakeReceiveLoop(): void {
-    this.receiveWake.wake();
+    this.receiveWake?.abort();
   }
 
   private getOrCreateSession(routingId: unknown): ZLinkStreamSessionRuntime | undefined {