@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/spots/spot-actor-admission-coordinator.ts

@@ -59,22 +59,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       remoteBoundSessionTarget,
       fallbackActorRef,
       undefined,
-      messageFollowOrigin,
-      (
-        replayedParts,
-        replayReturnResponse,
-        replayRemoteBoundSessionTarget,
-        replayFallbackActorRef
-      ) =>
-        this.dispatchActorPacketDirect(
-          origin,
-          activation,
-          actorId,
-          replayedParts,
-          replayReturnResponse,
-          replayRemoteBoundSessionTarget,
-          replayFallbackActorRef
-        )
+      messageFollowOrigin
     );
     if (handoff !== undefined) return await handoff;
     return await this.dispatchActorPacketDirect(
@@ -102,10 +87,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       ),
       serial: activation.serial,
       actors: {
-        resolveActor: (actorId) =>
-          activation.hasDepartedActor(actorId)
-            ? undefined
-            : (activation.resolveJoinedActor(actorId) ?? this.options.actorResolver?.(actorId)),
+        resolveActor: (actorId) => this.resolveActor(activation, actorId),
         getTarget: () => activation.spot,
         defaultAccept: false,
         transfer:
@@ -192,38 +174,21 @@ export class ZLinkSpotActorAdmissionCoordinator {
     actorId: string,
     records: readonly ZLinkActorHandoffPrefixRecord[]
   ): ZLinkActorHandoffPrefixAdmission {
-    const terminals = activation.admitActorDurablePrefix(
+    return activation.admitActorPacketPrefix(
       actorId,
-      records.map((record) => ({
-        operation: (executeChild) =>
-          record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
-            executeChild((actorSerial) =>
-              this.dispatchActorPacketInActorTurn(
-                currentApplicationJobOrigin(),
-                activation,
-                actorSerial,
-                actorId,
-                parts,
-                returnResponse,
-                remoteBoundSessionTarget,
-                fallbackActorRef
-              )
-            )
-          ),
-        preparation: record.preparation,
-        workOptions: { payloadBytes: record.payloadBytes }
-      }))
+      records,
+      (actorSerial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
+        this.dispatchActorPacketInActorTurn(
+          currentApplicationJobOrigin(),
+          activation,
+          actorSerial,
+          actorId,
+          parts,
+          returnResponse,
+          remoteBoundSessionTarget,
+          fallbackActorRef
+        )
     );
-    const terminal = Promise.allSettled(terminals).then((outcomes) => {
-      const errors = outcomes.flatMap((outcome) =>
-        outcome.status === 'rejected' ? [outcome.reason] : []
-      );
-      if (errors.length === 1) throw errors[0];
-      if (errors.length > 1) {
-        throw new AggregateError(errors, `Actor '${actorId}' durable prefix replay failed.`);
-      }
-    });
-    return { terminal };
   }
 
   private dispatchActorPacketInActorTurn(
@@ -242,11 +207,7 @@ export class ZLinkSpotActorAdmissionCoordinator {
       spotId: () => String(activation.spotId),
       registry: activation.actorHandlers,
       serial: actorSerial,
-      resolveActor: (targetActorId) =>
-        activation.hasDepartedActor(targetActorId)
-          ? undefined
-          : (activation.resolveJoinedActor(targetActorId) ??
-            this.options.actorResolver?.(targetActorId)),
+      resolveActor: (targetActorId) => this.resolveActor(activation, targetActorId),
       actorLeft: (targetActorId) => activation.hasDepartedActor(targetActorId),
       onDisconnectActor: (actor) =>
         activation.serial.execute(() => activation.spot.onDisconnectActor?.(actor)),
@@ -271,6 +232,15 @@ export class ZLinkSpotActorAdmissionCoordinator {
     );
   }
 
+  private resolveActor(activation: ZLinkSpotActivation, actorId: string): ZLinkActor | undefined {
+    if (activation.hasDepartedActor(actorId)) return undefined;
+    // The manager owns relocation visibility. Membership alone cannot publish
+    // a staged Actor; resolver absence supports standalone Spot runtimes.
+    return this.options.actorResolver === undefined
+      ? activation.resolveJoinedActor(actorId)
+      : this.options.actorResolver(actorId);
+  }
+
   private async commitTransferredActorTransaction(
     activation: ZLinkSpotActivation,
     actor: ZLinkActor,

package/src/runtime/spots/spot-actor-membership.ts

@@ -219,21 +219,6 @@ export class ZLinkSpotActorMembership {
     );
   }
 
-  async restoreActorAfterFailedTransfer(
-    spotId: RoutingId,
-    actor: ZLinkActor,
-    signal?: AbortSignal
-  ): Promise<void> {
-    throwIfAborted(signal);
-    const activation = this.requireActivation(spotId);
-    await this.runLifecycleOperation(activation, () =>
-      activation.serial.execute(async () => {
-        activation.cancelActorTransfer(actor.context.actorId);
-        await activation.spot.onJoinedActor(actor);
-      })
-    );
-  }
-
   async beginActorTransfer(spotId: RoutingId, actorId: string): Promise<void> {
     const activation = this.requireActivation(spotId);
     await this.runLifecycleOperation(activation, () =>

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

@@ -1,3 +1,7 @@
+import { actorMessageFollowContext } from '../actors/actor-message-follow-context';
+import { DefaultZLinkActorContext } from '../actors/actor-context';
+import { decodeSessionDisconnected } from '../actors/session-disconnected-wire';
+import { routingIdsEqual } from '../routing-id';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -12,7 +16,13 @@ import type {
   ZLinkSpot
 } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkFrameworkException, zlinkMessageMetadata } from '../../contracts';
+import {
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind,
+  ZLinkMessage,
+  ZLinkEncodedPayload,
+  zlinkMessageMetadata
+} from '../../contracts';
 import {
   ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
@@ -45,6 +55,10 @@ import { zlinkMetadataByteLength, zlinkSerialWorkOptions } from '../execution/se
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
 import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
 
+const emptyDisconnectedReply = ZLinkMessage.fromEncoded(
+  ZLinkEncodedPayload.fromOwned(Buffer.alloc(0))
+);
+
 export interface ZLinkActorResponseOptions {
   readonly metadata: ReadonlyMap<string, string>;
   readonly compressPayload: boolean;
@@ -204,11 +218,13 @@ export class ZLinkSpotActorPacketDispatch {
             ? ZLinkDispatchErrorAction.ReplyError
             : ZLinkDispatchErrorAction.Drop;
         this.trace(ZLinkMessageFlowOutcome.Received, actorId, header, messageKind);
-        if (
-          this.options.actorLeft?.(actorId) === true &&
-          header.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET
-        ) {
-          return undefined;
+        const disconnected = header.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET;
+        const disconnectedReply =
+          disconnected && header.kind === ZLinkStreamMessageKind.Request
+            ? emptyDisconnectedReply
+            : undefined;
+        if (this.options.actorLeft?.(actorId) === true && disconnected) {
+          return disconnectedReply;
         }
         const routed = await this.options.routeBeforeLocal?.(delivery);
         if (routed?.handled === true) {
@@ -229,9 +245,34 @@ export class ZLinkSpotActorPacketDispatch {
             requestTerminal
           );
         }
-        if (header.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+        if (disconnected) {
+          const identity = decodeSessionDisconnected(messageToBytes(parts[1]));
+          if (identity === undefined) {
+            if (this.options.dispatchErrors?.captureEnabled() === true)
+              this.reportInvalidFrame(
+                actorId,
+                messageKind,
+                new ZLinkFrameworkException(
+                  ZLinkFrameworkErrorKind.ProtocolError,
+                  'ProtocolError: malformed Session disconnect identity.'
+                ),
+                'warning'
+              );
+            return disconnectedReply;
+          }
+          const current =
+            actor.context instanceof DefaultZLinkActorContext
+              ? actor.context.currentSessionBinding
+              : undefined;
+          if (
+            current !== undefined &&
+            (!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(
@@ -303,7 +344,9 @@ export class ZLinkSpotActorPacketDispatch {
       return undefined;
     }
     const missingActorError = createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound,
+      actorMessageFollowContext(fallbackActorRef) === undefined
+        ? ZLinkFrameworkInternalErrorKind.ActorDispatchHandlerNotFound
+        : ZLinkFrameworkInternalErrorKind.ActorLocationStale,
       `SPOT actor is not registered locally: ${actorId}`
     );
     if (
@@ -603,7 +646,8 @@ export class ZLinkSpotActorPacketDispatch {
   private reportInvalidFrame(
     actorId: string,
     messageKind: ZLinkDispatchMessageKind,
-    error?: unknown
+    error?: unknown,
+    severity?: 'warning'
   ): void {
     this.options.dispatchErrors?.report({
       surface: ZLinkDispatchErrorSurface.SpotActor,
@@ -612,7 +656,8 @@ export class ZLinkSpotActorPacketDispatch {
       action: ZLinkDispatchErrorAction.Drop,
       spotId: this.options.spotId(),
       actorId,
-      error
+      error,
+      severity
     });
   }
 

package/src/runtime/spots/spot-actor-packet-drain.ts

@@ -1,5 +1,4 @@
 import type { ActorRef, RoutingId, ZLinkMessageSerializer } from '../../contracts';
-import { ZLinkFrameworkException, ZLinkFrameworkErrorKind } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import { RequestResult } from '../backend/runtime-values';
@@ -7,15 +6,9 @@ import type { ZLinkBackendActorRef, ZLinkBackendActorRecvInfo } from '../backend
 import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
 import { REMOTE_BOUND_SESSION_BIND_PACKET } from './spot-remote-codec';
 import { ZLINK_RECV_DONT_WAIT } from './spot-native-flags';
-import {
-  decodeStreamHeader,
-  encodeStreamFrame,
-  messageToBytes,
-  streamCodecForContentType,
-  ZLinkStreamHeaderFlags,
-  ZLinkStreamMessageKind
-} from '../streams/protocol';
-import { encodeFrameworkPayload } from '../messaging/payload-codec';
+import { decodeStreamHeader, messageToBytes, ZLinkStreamMessageKind } from '../streams/protocol';
+import { encodeActorReply } from '../actors/actor-reply';
+import { boundSessionErrorPayload } from '../streams/bound-session-response-target';
 
 export interface ZLinkActorDispatchPart {
   readonly info: {
@@ -218,7 +211,7 @@ export class ZLinkSpotActorPacketDrain {
           this.encodeActorReplyFrame(
             parts[0],
             ZLinkStreamMessageKind.Error,
-            frameworkErrorPayload(error)
+            boundSessionErrorPayload(error)
           )
         ],
         RequestResult.Ok
@@ -231,37 +224,14 @@ export class ZLinkSpotActorPacketDrain {
     kind: ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error,
     payload: unknown
   ): Message {
-    const requestHeader = decodeStreamHeader(messageToBytes(requestHeaderPart), this.flowEnabled());
-    const encoded = encodeFrameworkPayload(
+    const [frame] = encodeActorReply(
+      messageToBytes(requestHeaderPart),
+      kind,
       payload,
       this.options.messageSerializers,
-      kind === ZLinkStreamMessageKind.Response ? requestHeader.name : undefined,
-      'payload'
+      this.flowEnabled()
     );
-    try {
-      //  encodeStreamFrame returns a fresh, unaliased array; view it without re-copying.
-      const frame = encodeStreamFrame(
-        {
-          kind,
-          codec: streamCodecForContentType(encoded.contentType),
-          flags: 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 RuntimeMessage.fromOwned(
-        Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength)
-      ) as Message;
-    } finally {
-      encoded.message.close();
-    }
+    return RuntimeMessage.fromOwned(frame) as Message;
   }
 
   private consumeRemoteBoundSessionBind(
@@ -329,16 +299,3 @@ function isStreamHeaderMessage(message: Message, flowEnabled: boolean): boolean
 function closeMessages(messages: readonly Message[]): void {
   for (const message of messages) message.close();
 }
-
-function frameworkErrorPayload(error: unknown): {
-  readonly message: string;
-  readonly kind: ZLinkFrameworkErrorKind;
-} {
-  return {
-    message: error instanceof Error ? error.message : String(error),
-    kind:
-      error instanceof ZLinkFrameworkException
-        ? error.kind
-        : ZLinkFrameworkErrorKind.InternalFailure
-  };
-}

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

@@ -1,3 +1,4 @@
+import { currentApplicationJobOrigin } from '../application-jobs/application-job-queue-scope';
 import type {
   ActorRef,
   RoutingId,
@@ -50,7 +51,7 @@ import {
   DefaultZLinkSpotHandlerRegistry
 } from './spot-handler-registry';
 import { DefaultZLinkSpotOutbound, type ZLinkSpotRoutedTransport } from './spot-outbound';
-import { createProviderInstance } from './spot-provider';
+import { createFreshProviderInstance } from './spot-provider';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 import { ZLinkSpotSerialExecutor } from './spot-serial-executor';
 import { invokeSpotClosing } from './spot-closing';
@@ -106,7 +107,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 +126,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,
@@ -265,7 +270,7 @@ export class ZLinkEntrySpotActivation {
   }
 
   async create(): Promise<void> {
-    const entrySpot = await createProviderInstance(
+    const entrySpot = await createFreshProviderInstance(
       this.options.entrySpotType,
       this.options.providerResolver,
       this.context
@@ -328,7 +333,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');
     }
@@ -472,23 +480,7 @@ export class ZLinkEntrySpotActivation {
       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
-          })
-        )
+      messageFollowOrigin
     );
     if (handoff !== undefined) return await handoff;
     return this.spotSerialExecutor.executeActor(actorId, () =>
@@ -496,6 +488,26 @@ export class ZLinkEntrySpotActivation {
     );
   }
 
+  /** 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 {
+    return this.spotSerialExecutor.admitActorPacketPrefix(
+      actorId,
+      records,
+      (_serial, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) =>
+        this.dispatchActorPacketInsideMailbox({
+          origin: currentApplicationJobOrigin(),
+          actorId,
+          parts,
+          returnResponse,
+          remoteBoundSessionTarget,
+          fallbackActorRef
+        })
+    );
+  }
+
   private async replayActorBacklog(
     actor: ZLinkActor,
     backlog: readonly ZLinkActorHandoffPacket[]

package/src/runtime/spots/spot-handler-registry.ts

@@ -2,9 +2,11 @@ import type {
   Type,
   ZLinkActor,
   ZLinkEntrySpot,
+  ZLinkInstanceSpot,
   ZLinkInstanceSpotHandlerRegistry,
   ZLinkSpot,
-  ZLinkSpotHandlerRegistry
+  ZLinkSpotHandlerRegistry,
+  ZLinkSpotTimerHandler
 } from '../../contracts';
 import type {
   ZLinkEntrySpotActorRequestHandlerRegistration,
@@ -16,12 +18,17 @@ 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';
 
 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;
@@ -34,7 +41,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 +52,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 +73,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 +90,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 +119,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 +163,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 +183,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;
   }
@@ -163,8 +197,11 @@ export class DefaultZLinkSpotHandlerRegistry<
     return this.addSubscribe(handlerType, channelName, topic);
   }
 
-  addSpotHandler(handlerType: Type): this {
-    this.entries.push({ kind: 'spotHandler', handlerType });
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkSpot>>(
+    handlerType: Type<THandler>
+  ): this {
+    prepareHandlerInstance(this.providerResolver, handlerType);
+    this.entries.push({ kind: 'timer', handlerType });
     return this;
   }
 
@@ -185,6 +222,13 @@ export class DefaultZLinkInstanceSpotHandlerRegistry implements ZLinkInstanceSpo
     return this;
   }
 
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkInstanceSpot>>(
+    handlerType: Type<THandler>
+  ): this {
+    this.registrations.addTimerHandler(handlerType as never);
+    return this;
+  }
+
   snapshot(): readonly ZLinkSpotHandlerRegistration[] {
     return this.registrations.snapshot();
   }

package/src/runtime/spots/spot-manager-internal-contracts.ts

@@ -5,7 +5,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/src/runtime/spots/spot-manager-public.ts

@@ -196,7 +196,7 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
       yield: (signal) => {
         const yieldTurn = requireZLinkYieldTurn(turn);
         const pending = this.submit(spotId, stableType, generatedIdentity, state, signal);
-        return yieldTurn.yieldPromise(pending);
+        return yieldTurn.yieldFrameworkPromise(pending);
       }
     };
     return call;
@@ -264,7 +264,7 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
             }
           };
         } catch (error) {
-          this.options.local.abortUserSpotPublication(target.meshName, spotId);
+          await this.options.local.abortUserSpotPublication(target.meshName, spotId);
           throw error;
         }
       },