@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,3 +1,4 @@
+import { dispatchActorPacketInMailbox } from './spot-actor-admission-coordinator';
 import { currentApplicationJobOrigin } from '../application-jobs/application-job-queue-scope';
 import type {
   ActorRef,
@@ -70,9 +71,9 @@ import type {
   ZLinkSpotActorHandoffRuntime,
   ZLinkSpotBoundSessionRuntime
 } from './spot-runtime-ports';
-import { ZLinkSpotLifecycleMetrics } from './spot-lifecycle-metrics';
 
 interface ZLinkEntrySpotActivationOptions {
+  readonly admission?: import('../admission').ZLinkRuntimeAdmissionGate;
   readonly entrySpotType: Type<ZLinkEntrySpot>;
   readonly timerHandlers?: readonly ZLinkEntrySpotTimerHandlerRegistration[];
   readonly packetHandlers?: readonly ZLinkEntrySpotPacketHandlerRegistration[];
@@ -104,13 +105,12 @@ interface ZLinkEntrySpotActivationOptions {
 
 export class ZLinkEntrySpotActivation {
   private readonly serial: ZLinkSpotSerialTurnExecutor;
-  private readonly spotSerialExecutor: ZLinkSpotSerialExecutor;
+  readonly spotSerialExecutor: ZLinkSpotSerialExecutor;
   private readonly timers: ZLinkSpotTimerRegistry;
   private readonly actorHandlers = new ZLinkSpotActorHandlerRegistryRuntime();
   private readonly handlers: DefaultZLinkSpotHandlerRegistry;
   private readonly outbound: DefaultZLinkSpotOutbound;
   private readonly workerRuntime: ZLinkWorkerRuntime;
-  private readonly lifecycleMetrics: ZLinkSpotLifecycleMetrics;
   private readonly packetDispatch: ZLinkRoutedSpotPacketDispatch;
   private readonly actorPacketDispatch: ZLinkSpotActorPacketDispatch;
   private initialized = false;
@@ -150,7 +150,6 @@ export class ZLinkEntrySpotActivation {
       options.metrics,
       () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
     );
-    this.lifecycleMetrics = new ZLinkSpotLifecycleMetrics(options.metrics);
     this.workerRuntime = options.workerRuntime ?? new ZLinkWorkerRuntime();
     this.context = createEntrySpotContext({
       spotId: String(options.nativeSpot.routingId),
@@ -192,17 +191,21 @@ export class ZLinkEntrySpotActivation {
       dispatchErrors: options.dispatchErrors
     });
     this.actorPacketDispatch = new ZLinkSpotActorPacketDispatch({
+      admission: this.options.admission,
       spot: () => this.entrySpot as unknown as ZLinkSpot,
       spotId: () => String(this.options.nativeSpot.routingId),
       registry: this.actorHandlers,
       resolveActor: (targetActorId) => this.options.entryActorRuntime?.resolveActor(targetActorId),
-      routeBeforeLocal: (target) =>
+      routeBeforeLocal: (delivery) =>
         this.options.entryActorRuntime?.routePacket(
-          target.actorId,
-          target.parts,
-          target.returnResponse,
-          target.remoteBoundSessionTarget,
-          target.fallbackActorRef
+          delivery.actorId,
+          delivery.parts,
+          delivery.returnResponse,
+          delivery.remoteBoundSessionTarget,
+          delivery.fallbackActorRef,
+          delivery.origin,
+          delivery.requestTerminal,
+          delivery.messageFollowOrigin
         ),
       onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
       actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(
@@ -260,7 +263,7 @@ export class ZLinkEntrySpotActivation {
 
   dispatchPacketEncoded(
     packetName: string | undefined,
-    decodePayload: () => unknown,
+    decodePayload: (messageType?: Type) => unknown,
     context: { readonly channelName: string; readonly contentType?: string },
     returnResponse: boolean
   ): Promise<unknown> {
@@ -304,7 +307,7 @@ export class ZLinkEntrySpotActivation {
     await this.serial.execute(() => this.entrySpot.onInitialize?.());
     this.attachActorJoinDispatch();
     this.initialized = true;
-    this.lifecycleMetrics.opened('entry');
+    this.options.metrics?.recordSpotCount(this.options.spotNodeName, 'entry', 1);
   }
 
   async dispose(deadline?: Date): Promise<void> {
@@ -338,7 +341,7 @@ export class ZLinkEntrySpotActivation {
       await this.options.nativeSpot.dispose();
     });
     if (this.initialized) {
-      this.lifecycleMetrics.closed('entry');
+      this.options.metrics?.recordSpotCount(this.options.spotNodeName, 'entry', -1);
     }
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) throw new AggregateError(errors, 'Entry Spot cleanup failed.');
@@ -464,27 +467,14 @@ export class ZLinkEntrySpotActivation {
   }
 
   async dispatchActorPacket(delivery: ZLinkActorPacketDelivery): Promise<unknown> {
-    const {
-      actorId,
-      parts,
-      returnResponse,
-      remoteBoundSessionTarget,
-      fallbackActorRef,
-      messageFollowOrigin
-    } = delivery;
-    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)
+    return dispatchActorPacketInMailbox(
+      (operation) => this.spotSerialExecutor.executeActor(delivery.actorId, operation),
+      () =>
+        this.actorPacketDispatch.admitDelivery(
+          undefined,
+          delivery,
+          this.options.actorHandoffRuntime
+        )
     );
   }
 
@@ -539,7 +529,7 @@ export class ZLinkEntrySpotActivation {
   private async dispatchActorPacketInsideMailbox(
     delivery: ZLinkActorPacketDelivery
   ): Promise<unknown> {
-    return this.actorPacketDispatch.dispatchDelivery(delivery);
+    return this.actorPacketDispatch.dispatchDelivery(undefined, delivery);
   }
 
   private replyActorNoBind(

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

@@ -1,3 +1,4 @@
+import type { ZLinkHandlerMessageType } from '../../contracts/Common/HandlerMessageType';
 import type {
   Type,
   ZLinkActor,
@@ -19,6 +20,7 @@ import type {
   ZLinkSpotSubscriptionHandlerRegistration
 } from '../../contracts/Configuration/RegistrationTypes';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { resolveHandlerMessageType } from '../../contracts/Common/HandlerMessageType';
 import { prepareHandlerInstance } from '../handlers/handler-instance-scope';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -30,6 +32,7 @@ import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes'
 export interface ZLinkSpotHandlerRegistration {
   readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'timer';
   readonly handlerType: Type;
+  readonly messageType?: ZLinkHandlerMessageType;
   readonly packetName?: string;
   readonly channelName?: string;
   readonly topic?: string;
@@ -61,7 +64,8 @@ export class DefaultZLinkSpotHandlerRegistry<
       metadata.kind === 'spotActorSend' ? ZLinkActorPacketKind.Send : ZLinkActorPacketKind.Request,
       handlerType,
       Object as unknown as Type<TActor>,
-      resolvedPacketName
+      resolvedPacketName,
+      resolveHandlerMessageType(handlerType)
     );
   }
 
@@ -82,11 +86,24 @@ export class DefaultZLinkSpotHandlerRegistry<
       metadata.kind === 'spotActorSend' ? ZLinkActorPacketKind.Send : ZLinkActorPacketKind.Request,
       handlerType,
       actorType as unknown as Type<TActor>,
-      metadata.packetName
+      metadata.packetName,
+      resolveHandlerMessageType(handlerType)
     );
   }
 
   addPacket(handlerType: Type, packetName?: string): this {
+    return this.addPacketRegistration(
+      handlerType,
+      packetName,
+      resolveHandlerMessageType(handlerType)
+    );
+  }
+
+  addPacketRegistration(
+    handlerType: Type,
+    packetName: string | undefined,
+    messageType: ZLinkHandlerMessageType | undefined
+  ): this {
     const declared = readZLinkDecoratorMetadata(handlerType).find(
       (entry) => entry.kind === 'packet'
     )?.packetName;
@@ -104,6 +121,7 @@ export class DefaultZLinkSpotHandlerRegistry<
     this.entries.push({
       kind: 'packet',
       handlerType,
+      ...(messageType === undefined ? {} : { messageType: messageType }),
       packetName: resolvedPacketName
     });
     return this;
@@ -117,12 +135,14 @@ export class DefaultZLinkSpotHandlerRegistry<
     kind: ZLinkActorPacketKind,
     handlerType: Type,
     actorType: Type<TActor>,
-    packetName: string
+    packetName: string,
+    messageType: ZLinkHandlerMessageType | undefined
   ): this {
     prepareHandlerInstance(this.providerResolver, handlerType);
     this.entries.push({
       kind: kind === ZLinkActorPacketKind.Send ? 'actorSend' : 'actorRequest',
       handlerType,
+      ...(messageType === undefined ? {} : { messageType: messageType }),
       actorType,
       packetName
     });
@@ -130,7 +150,8 @@ export class DefaultZLinkSpotHandlerRegistry<
       kind,
       packetName,
       actorType,
-      handlerType
+      handlerType,
+      messageType: messageType
     });
     return this;
   }
@@ -144,7 +165,8 @@ export class DefaultZLinkSpotHandlerRegistry<
       ZLinkActorPacketKind.Send,
       handlerType,
       actorType,
-      packetName
+      packetName,
+      resolveHandlerMessageType(handlerType)
     );
   }
 
@@ -157,11 +179,26 @@ export class DefaultZLinkSpotHandlerRegistry<
       ZLinkActorPacketKind.Request,
       handlerType,
       actorType,
-      packetName
+      packetName,
+      resolveHandlerMessageType(handlerType)
     );
   }
 
   addSubscribe(handlerType: Type, channelName: string, topic: string): this {
+    return this.addSubscriptionRegistration(
+      handlerType,
+      channelName,
+      topic,
+      resolveHandlerMessageType(handlerType)
+    );
+  }
+
+  addSubscriptionRegistration(
+    handlerType: Type,
+    channelName: string,
+    topic: string,
+    messageType: ZLinkHandlerMessageType | undefined
+  ): this {
     if (channelName.trim().length === 0) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.InvalidOperation,
@@ -189,7 +226,13 @@ export class DefaultZLinkSpotHandlerRegistry<
       );
     }
     prepareHandlerInstance(this.providerResolver, handlerType);
-    this.entries.push({ kind: 'subscribe', handlerType, channelName, topic });
+    this.entries.push({
+      kind: 'subscribe',
+      handlerType,
+      ...(messageType === undefined ? {} : { messageType: messageType }),
+      channelName,
+      topic
+    });
     return this;
   }
 
@@ -259,7 +302,8 @@ export function applyEntrySpotHandlerRegistrations(
         ZLinkActorPacketKind.Send,
         handler.handlerType,
         handler.actorType,
-        handler.packetName
+        handler.packetName,
+        handler.messageType
       );
     }
   }
@@ -269,18 +313,24 @@ export function applyEntrySpotHandlerRegistrations(
         ZLinkActorPacketKind.Request,
         handler.handlerType,
         handler.actorType,
-        handler.packetName
+        handler.packetName,
+        handler.messageType
       );
     }
   }
   for (const handler of registrations.packetHandlers ?? []) {
     if (handler.entrySpotType === entrySpotType) {
-      registry.addPacket(handler.handlerType, handler.packetName);
+      registry.addPacketRegistration(handler.handlerType, handler.packetName, handler.messageType);
     }
   }
   for (const handler of registrations.subscriptionHandlers ?? []) {
     if (handler.entrySpotType === entrySpotType) {
-      registry.addSubscribe(handler.handlerType, handler.channelName, handler.topic);
+      registry.addSubscriptionRegistration(
+        handler.handlerType,
+        handler.channelName,
+        handler.topic,
+        handler.messageType
+      );
     }
   }
 }
@@ -296,7 +346,8 @@ export function applySpotHandlerRegistrations(
         ZLinkActorPacketKind.Send,
         handler.handlerType,
         handler.actorType,
-        handler.packetName
+        handler.packetName,
+        handler.messageType
       );
     }
   }
@@ -306,18 +357,24 @@ export function applySpotHandlerRegistrations(
         ZLinkActorPacketKind.Request,
         handler.handlerType,
         handler.actorType,
-        handler.packetName
+        handler.packetName,
+        handler.messageType
       );
     }
   }
   for (const handler of registrations.packetHandlers ?? []) {
     if (isSpotImplementation(handler.spotType, spotType)) {
-      registry.addPacket(handler.handlerType, handler.packetName);
+      registry.addPacketRegistration(handler.handlerType, handler.packetName, handler.messageType);
     }
   }
   for (const handler of registrations.subscriptionHandlers ?? []) {
     if (isSpotImplementation(handler.spotType, spotType)) {
-      registry.addSubscribe(handler.handlerType, handler.channelName, handler.topic);
+      registry.addSubscriptionRegistration(
+        handler.handlerType,
+        handler.channelName,
+        handler.topic,
+        handler.messageType
+      );
     }
   }
 }

package/src/runtime/spots/spot-manager-public.ts

@@ -96,6 +96,7 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
   }
 
   async close(spot: SpotRef, signal?: AbortSignal): Promise<boolean> {
+    const deadline = new Date(Date.now() + this.options.defaultTimeoutMs);
     const resolved = await this.options.coordinator.resolveCloseTarget(spot, signal);
     if (resolved === undefined) return false;
     const current = resolved.spot;
@@ -107,7 +108,8 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
             local.meshName,
             local.spotId,
             beginAuthority,
-            signal
+            signal,
+            deadline
           ),
         signal
       );
@@ -136,7 +138,7 @@ export class ZLinkPublicSpotManager implements ZLinkSpotManager {
           authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
           expectedStoreVersion: snapshot.storeVersion.value
         },
-        deadlineUnixMs: BigInt(Date.now() + timeoutMs)
+        deadlineUnixMs: BigInt(deadline.getTime())
       },
       timeoutMs
     );

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

@@ -1,3 +1,4 @@
+import type { RequestRuntime } from '../foundation/request-runtime';
 import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { RuntimeDisposal } from '../disposal';
@@ -5,6 +6,7 @@ import { randomUUID } from 'node:crypto';
 import {
   type ActorRef,
   type RoutingId,
+  type Type,
   type ZLinkActor,
   type ZLinkChannelClient,
   type ZLinkFanoutClient,
@@ -118,6 +120,8 @@ const ZLINK_SEND_DONT_WAIT = 1;
 const EMPTY_SPOT_METADATA: ReadonlyMap<string, string> = new Map();
 
 export interface ZLinkSpotNodeRuntimeManagerOptions {
+  readonly requests?: RequestRuntime;
+  readonly admission?: import('../admission').ZLinkRuntimeAdmissionGate;
   readonly errorSink: import('../diagnostics/dispatch-error-port').ZLinkDispatchErrorSink;
   readonly listenerRecords?: ZLinkListenerRecords;
   readonly registration: ZLinkFrameworkRegistration;
@@ -154,10 +158,10 @@ export interface ZLinkSpotNodeRuntimeManagerOptions {
 }
 
 export class ZLinkSpotNodeRuntimeManager {
-  private readonly meshNodes = new Map<string, ZLinkBackendMeshNode>();
+  readonly meshNodes = new Map<string, ZLinkBackendMeshNode>();
   private readonly meshPumps = new Map<string, ZLinkMeshDispatchPump>();
   private readonly meshCompletions = new Map<string, ZLinkMeshCompletionTable>();
-  private readonly entryActivations = new Map<string, ZLinkEntrySpotActivation>();
+  readonly entryActivations = new Map<string, ZLinkEntrySpotActivation>();
   private readonly entryActivationStarts = new Map<string, Promise<void>>();
   private readonly publishers = new Map<
     string,
@@ -175,11 +179,11 @@ export class ZLinkSpotNodeRuntimeManager {
   private readonly runtimeChannelWeights = new Map<string, Map<string, number>>();
   private readonly entrySpotIds = new Map<string, string>();
   private runtimeWeightPublication = Promise.resolve();
-  private statePublication = Promise.resolve();
-  private locationAutoConnect?: ZLinkSpotNodeLocationAutoConnectContext;
+  statePublication = Promise.resolve();
+  locationAutoConnect?: ZLinkSpotNodeLocationAutoConnectContext;
   private readonly applicationJobQueue: ApplicationJobQueue;
 
-  constructor(private readonly options: ZLinkSpotNodeRuntimeManagerOptions) {
+  constructor(readonly options: ZLinkSpotNodeRuntimeManagerOptions) {
     if ((options.detachedTaskRunner as unknown) === undefined) {
       throw new ZLinkConfigurationException('Spot node runtime requires a detached task runner.');
     }
@@ -300,12 +304,15 @@ export class ZLinkSpotNodeRuntimeManager {
       const node = meshAdapter.createMeshNode(this.options.context, {
         meshName: spotNodeName,
         routingId,
+        sendHighWaterMark: spotNode.router?.sendHighWaterMark,
+        receiveHighWaterMark: spotNode.router?.receiveHighWaterMark,
         receiveTimeoutMs: spotNode.router?.receiveTimeoutMs,
         applicationJobQueue: this.applicationJobQueue,
         infrastructureTaskRunner: this.options.detachedTaskRunner,
         applicationJobReceiveFlowFailureSink: this.options.applicationJobReceiveFlowFailureSink,
         peerAdmissionSealed: () => this.options.peerAdmissionSealed?.(spotNodeName) ?? false
       });
+      if (this.options.requests !== undefined) node.setRequestRuntime?.(this.options.requests);
       if (this.options.dispatchErrors !== undefined) {
         node.setDispatchErrorReporter?.(this.options.dispatchErrors, spotNodeName);
       }
@@ -1024,7 +1031,8 @@ export class ZLinkSpotNodeRuntimeManager {
       this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true
     );
     const codecs = { serializers: this.options.registration.messageSerializers };
-    const decodePayload = () => decodeChannelPayload(envelope, codecs);
+    const decodePayload = (messageType?: Type) =>
+      decodeChannelPayload(envelope, codecs, messageType);
     const context = {
       channelName: envelope.header.channelName,
       contentType: envelope.header.contentType
@@ -1083,7 +1091,7 @@ export class ZLinkSpotNodeRuntimeManager {
     }
   }
 
-  private async initializeEntrySpot(
+  async initializeEntrySpot(
     spotNodeName: string,
     node: ZLinkBackendMeshNode,
     spotNode: ZLinkSpotNodeOptions
@@ -1092,6 +1100,7 @@ export class ZLinkSpotNodeRuntimeManager {
       return;
     }
     const activation = new ZLinkEntrySpotActivation({
+      admission: this.options.admission,
       entrySpotType: spotNode.entrySpotType,
       nativeSpot: node.entrySpot() as never,
       nativeNode: node as unknown as ZLinkBackendSpotNode,

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

@@ -1,4 +1,11 @@
-import { createZLinkRequest } from '../messaging/request-result';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
+import {
+  createZLinkRequest,
+  mapZLinkRequestReply,
+  prepareZLinkRequestReply,
+  identityRequestReply,
+  type ZLinkRequestResult
+} from '../messaging/request-result';
 import {
   type RoutingId,
   type ZLinkChannelClient,
@@ -181,6 +188,7 @@ export interface ZLinkSpotAddressCallOptions {
   readonly instanceSpotType?: string;
   readonly initialMeshName?: string;
   readonly timeoutMs?: number;
+  readonly requestOperation?: PendingOperation<unknown>;
   readonly signal?: AbortSignal;
   readonly sourceSpot?: ZLinkBackendSpot;
 }
@@ -217,14 +225,16 @@ export interface ZLinkSpotRoutedTransport {
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: ZLinkSpotRoutedRequestOptions
-  ): Promise<TReply>;
+    options: ZLinkSpotRoutedRequestOptions,
+    destination?: OperationObserver<unknown, unknown>
+  ): ZLinkRequestResult<TReply>;
   requestFromSpotToSpot?<TReply = unknown>(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: ZLinkSpotRoutedRequestOptions
-  ): Promise<TReply>;
+    options: ZLinkSpotRoutedRequestOptions,
+    destination?: OperationObserver<unknown, unknown>
+  ): ZLinkRequestResult<TReply>;
 }
 
 export interface ZLinkSpotRoutedSendOptions {
@@ -234,8 +244,10 @@ export interface ZLinkSpotRoutedSendOptions {
 }
 
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+  readonly deadlineMs?: number;
   readonly onAdmitted?: () => void;
   readonly timeoutMs?: number;
+  readonly requestOperation?: PendingOperation<unknown>;
   readonly signal?: AbortSignal;
 }
 
@@ -361,7 +373,8 @@ function createAddressedSpotRequestCall(
       markSubmitted(options);
       rejectSameSpotAsyncRequest(serial, spotId, 'async');
       return createZLinkRequest(
-        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (onAdmitted) =>
+          prepareZLinkRequestReply(begin<TReply>(signal, onAdmitted), identityRequestReply),
         (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
       );
     },
@@ -501,7 +514,8 @@ function wrapRequestCall(
     },
     submit<TReply>(signal?: AbortSignal) {
       return createZLinkRequest(
-        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (onAdmitted) =>
+          prepareZLinkRequestReply(begin<TReply>(signal, onAdmitted), identityRequestReply),
         (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
       );
     },
@@ -618,7 +632,8 @@ function wrapRoutedSpotRequestCall(
     submit<TReply>(signal?: AbortSignal) {
       rejectSameSpotAsyncRequest(serial, spot.spotId, 'async');
       return createZLinkRequest(
-        (onAdmitted) => begin<TReply>(signal, onAdmitted),
+        (onAdmitted) =>
+          prepareZLinkRequestReply(begin<TReply>(signal, onAdmitted), identityRequestReply),
         (pending) => (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending))
       );
     },
@@ -649,6 +664,7 @@ export interface ZLinkSpotHandleCallOptions {
   readonly onAdmitted?: () => void;
   readonly metadata?: ReadonlyMap<string, string>;
   readonly timeoutMs?: number;
+  readonly requestOperation?: PendingOperation<unknown>;
   readonly signal?: AbortSignal;
   readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
   readonly sourceSpot?: ZLinkBackendSpot;
@@ -685,7 +701,7 @@ export async function requestToSpotHandle<TReply = unknown>(
   options: ZLinkSpotHandleCallOptions = {}
 ): Promise<TReply> {
   const packetName = resolveFrameworkPacketName(request, undefined, 'SPOT');
-  const requestResolved = async (resolved: ResolvedSpotHandle): Promise<TReply> => {
+  const requestResolved = (resolved: ResolvedSpotHandle): ZLinkRequestResult<TReply> => {
     const target = spotRefToSpotRouteTarget(resolved, options.spotRouterChannelIdForMesh);
     const transportOptions = {
       packetName,
@@ -705,7 +721,7 @@ export async function requestToSpotHandle<TReply = unknown>(
     return transport.requestToSpot<TReply>(target, request, transportOptions);
   };
 
-  return requestResolved(await requireSpotRef(spot, options.signal));
+  return mapZLinkRequestReply(requestResolved(await requireSpotRef(spot, options.signal)));
 }
 
 async function requireSpotRef(

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

@@ -46,6 +46,7 @@ import {
 } from '../framework-errors-internal';
 import { resolveLifecycleHandler } from '../handlers/handler-instance-scope';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
+import { resolveMessageTypeForDecode } from '../../contracts/Common/HandlerMessageType';
 import { REMOTE_ACTOR_JOIN_PACKET } from './spot-remote-codec';
 import { appendRouteReplyParts, hasReplyToken, submitRouteReply } from './spot-route-replies';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
@@ -78,9 +79,10 @@ export class ZLinkSpotRoutePacketDispatch {
   constructor(private readonly options: ZLinkSpotRoutePacketDispatchOptions) {}
 
   async dispatch(received: BackendReceived): Promise<boolean> {
+    const receivedAt = new Date();
     const directEnvelope = decodeSpotDirectEnvelope(received.parts);
     if (directEnvelope !== undefined) {
-      await this.dispatchSpotDirectEnvelope(received, directEnvelope);
+      await this.dispatchSpotDirectEnvelope(received, directEnvelope, receivedAt);
       return true;
     }
     let envelope: ReturnType<typeof decodeChannelEnvelope>;
@@ -147,7 +149,8 @@ export class ZLinkSpotRoutePacketDispatch {
       contentType: envelope.header.contentType,
       packetName: envelope.packetName!,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: envelope.header.correlationId ?? undefined
+      correlationId: envelope.header.correlationId ?? undefined,
+      receivedAt
     };
     try {
       let response: unknown;
@@ -167,7 +170,11 @@ export class ZLinkSpotRoutePacketDispatch {
                 // Keep the wire payload raw until this Spot has acquired its
                 // execution authority. A rejected or superseded work item must not
                 // pay the deserialization cost.
-                const payload = decodeChannelPayload(envelope, this.channelCodecs());
+                const payload = decodeChannelPayload(
+                  envelope,
+                  this.channelCodecs(),
+                  resolveMessageTypeForDecode(registrations[0]?.messageType)
+                );
                 for (const registration of registrations) {
                   const handler = await resolveLifecycleHandler(
                     spot,
@@ -240,7 +247,8 @@ export class ZLinkSpotRoutePacketDispatch {
 
   private async dispatchSpotDirectEnvelope(
     received: BackendReceived,
-    envelope: ZLinkSpotDirectEnvelope
+    envelope: ZLinkSpotDirectEnvelope,
+    receivedAt: Date
   ): Promise<void> {
     const replyable =
       envelope.kind === ZLinkChannelMessageKind.Request && hasReplyToken(received.replyToken);
@@ -287,13 +295,15 @@ export class ZLinkSpotRoutePacketDispatch {
               >,
               this.options.providerResolver
             );
-            releaseApplicationJobPermitBeforeHandler();
-            response = await handler.handle(spot, envelope.payload, {
+            const handlerContext = {
               channelName: envelope.channelName,
               packetName: envelope.packetName!,
               metadata: zlinkMessageMetadata(envelope.metadata),
-              correlationId: undefined
-            });
+              correlationId: undefined,
+              receivedAt
+            };
+            releaseApplicationJobPermitBeforeHandler();
+            response = await handler.handle(spot, envelope.payload, handlerContext);
           }
         },
         zlinkSerialWorkOptions(