@zlink-systems/framework 0.31.0 → 0.32.1

package/src/runtime/actors/index.ts

@@ -40,7 +40,6 @@ import {
 } from './actor-runtime-state';
 import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-rollback';
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
-const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 
 export { DefaultZLinkActorClient, type ZLinkActorClientOptions } from './actor-client';
 export { DefaultZLinkActorContext, ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME } from './actor-context';
@@ -167,7 +166,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     throwIfAborted(signal);
     if (this.relocationStaged.has(actorId)) return undefined;
     const state = this.states.get(actorId);
-    if (state?.actor !== undefined) {
+    if (state?.actor !== undefined && state.nativeActorRef !== undefined) {
       return this.actorRefForState(state);
     }
     return await this.options.actorRefResolver?.resolveActorRef(actorId, signal);
@@ -182,7 +181,12 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   async findSpot(actorId: string, signal?: AbortSignal): Promise<SpotRef | undefined> {
     throwIfAborted(signal);
     const state = this.states.get(actorId);
-    if (state?.actor === undefined || state.spotId === undefined) return undefined;
+    if (
+      state?.actor === undefined ||
+      state.spotId === undefined ||
+      state.nativeActorRef === undefined
+    )
+      return undefined;
     const spotId = state.spotId;
     const actorRef = this.actorRefForState(state);
     return {
@@ -249,12 +253,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         await this.finalizeDestroyedActor(actor.actorId, state);
       })
     );
-    try {
-      await this.awaitActorDestroy(state, destroyTask);
-    } catch (error) {
-      state.clearFailedDestroy(destroyTask);
-      throw error;
-    }
+    await this.awaitActorDestroy(state, destroyTask);
     return true;
   }
 
@@ -362,9 +361,10 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     if (result.status === 'failed') {
       throw actorApplicationFailure(actorId, result.error);
     }
+    const actorRef = result.actorRef ?? this.actorRefForState(this.states.get(actorId)!);
     return result.reply === undefined
-      ? { status: result.status, actor: result.actorRef }
-      : { status: result.status, actor: result.actorRef, reply: result.reply };
+      ? { status: result.status, actor: actorRef }
+      : { status: result.status, actor: actorRef, reply: result.reply };
   }
 
   private ensureActorTypeBelongsToMesh(meshName: string, actorType: string): void {
@@ -638,7 +638,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     actorType: string,
     createRequest?: unknown,
     signal?: AbortSignal
-  ): Promise<ZLinkActorLocalCreateResult> {
+  ): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>> {
     this.rememberActorMeshFromType(actorId, actorType);
     return await this.createOrGet(actorId, actorType, false, createRequest, signal);
   }
@@ -651,7 +651,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     nativeActorRef?: ZLinkBackendActorRef
   ): Promise<ZLinkActorLocalCreateResult> {
     this.rememberActorMeshFromType(actorId, actorType);
-    return await this.createOrGet(
+    const result = await this.createOrGet(
       actorId,
       actorType,
       false,
@@ -661,6 +661,11 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       DEFAULT_REQUEST_TIMEOUT_MS,
       nativeActorRef
     );
+    if (result.status === 'failed' || result.status === 'rejected') return result;
+    return {
+      ...result,
+      actorRef: this.actorRefForState(this.states.get(actorId)!)
+    };
   }
 
   adoptCreatedAuthority(
@@ -712,7 +717,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) =>
       this.terminateActor(state, async () => {
         const destroyedActorRef =
-          actorRef === undefined ? undefined : toFrameworkActorRef(actorRef, state.meshName ?? '');
+          state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
         if (actorRef !== undefined) {
           await node.destroyActor(actorRef, 0, destroySignal);
           state.markNativeActorDestroyed(actorRef);
@@ -728,12 +733,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       })
     );
 
-    try {
-      await this.awaitActorDestroy(state, destroyTask);
-    } catch (error) {
-      state.clearFailedDestroy(destroyTask);
-      throw error;
-    }
+    await this.awaitActorDestroy(state, destroyTask);
   }
 
   private async createOrGet(
@@ -745,7 +745,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     claimLocation = true,
     timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     nativeActorRef?: ZLinkBackendActorRef
-  ): Promise<ZLinkActorLocalCreateResult> {
+  ): Promise<ZLinkActorLocalCreateResult<ActorRef | undefined>> {
     const deadline = performance.now() + timeoutMs;
     const requestedMeshName = this.actorMeshNames.get(actorId);
     for (;;) {
@@ -801,7 +801,8 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       try {
         const result = await operation.task;
         if (result.status === 'created') {
-          const actorRef = this.actorRefForState(state);
+          const actorRef =
+            state.nativeActorRef === undefined ? undefined : this.actorRefForState(state);
           return {
             status: operation.created ? 'created' : 'existing',
             actor: result.actor,
@@ -886,16 +887,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   }
 
   private actorRefForState(state: ZLinkActorRuntimeState): ActorRef {
-    const nativeActorRef = state.nativeActorRef;
-    if (nativeActorRef !== undefined) {
-      return toFrameworkActorRef(nativeActorRef, state.meshName ?? '');
-    }
-    return {
-      actorId: state.actorId,
-      objectGeneration: 1n,
-      meshName: state.meshName ?? '',
-      nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
-    };
+    return toFrameworkActorRef(state.currentActorRef(), state.meshName ?? '');
   }
 }
 
@@ -994,11 +986,11 @@ class ZLinkActorGetOrCreateCallRuntime
   extends ZLinkActorCreateCallRuntime
   implements ZLinkActorGetOrCreateCall {}
 
-export type ZLinkActorLocalCreateResult =
+export type ZLinkActorLocalCreateResult<TActorRef extends ActorRef | undefined = ActorRef> =
   | {
       readonly status: 'existing' | 'created';
       readonly actor: ZLinkActor;
-      readonly actorRef: ActorRef;
+      readonly actorRef: TActorRef;
       readonly reply?: unknown;
     }
   | {
@@ -1010,7 +1002,10 @@ export type ZLinkActorLocalCreateResult =
       readonly error: unknown;
     };
 
-function requireCreatedActor(result: ZLinkActorLocalCreateResult, actorId: string): ZLinkActor {
+function requireCreatedActor(
+  result: ZLinkActorLocalCreateResult<ActorRef | undefined>,
+  actorId: string
+): ZLinkActor {
   if (result.status === 'existing' || result.status === 'created') return result.actor;
   if (result.status === 'failed') {
     throw actorApplicationFailure(actorId, result.error);

package/src/runtime/actors/spot-actor-dispatch.ts

@@ -362,7 +362,7 @@ export class ZLinkSpotActorDispatcher {
     );
   }
 
-  private invokeHandler<THandler, TResult>(
+  invokeHandler<THandler, TResult>(
     actor: ZLinkActor,
     descriptor: Pick<ZLinkActorPacketDescriptor, 'handlerType' | 'methodName'>,
     callback: (
@@ -398,7 +398,7 @@ export class ZLinkSpotActorDispatcher {
     return pending;
   }
 
-  private createContext(
+  createContext(
     packetName: string,
     context: Partial<ZLinkMessageContext> | undefined
   ): ZLinkMessageContext {
@@ -408,7 +408,8 @@ export class ZLinkSpotActorDispatcher {
       packetName,
       contentType: context?.contentType,
       metadata: context?.metadata ?? ZLinkMessageMetadataEmpty,
-      correlationId: context?.correlationId
+      correlationId: context?.correlationId,
+      receivedAt: context?.receivedAt ?? new Date()
     };
   }
 }

package/src/runtime/application-jobs/application-ingress-record-owner.ts

@@ -105,6 +105,10 @@ export class ApplicationJobRecordLease implements ApplicationJobPermitPort {
     private permit: ApplicationJobPermitPort | undefined
   ) {}
 
+  reacquire(signal: AbortSignal): Promise<ApplicationJobPermitPort> {
+    return this.shared.acquirePermit(signal);
+  }
+
   get origin(): ApplicationJobOrigin {
     return this.shared.origin;
   }

package/src/runtime/backend/contracts/index.ts

@@ -865,6 +865,8 @@ export interface ZLinkMeshBackendAdapter {
     options: {
       readonly meshName: string;
       readonly routingId?: RoutingId;
+      readonly sendHighWaterMark?: number;
+      readonly receiveHighWaterMark?: number;
       readonly receiveTimeoutMs?: number;
       readonly trustProfile?: string;
       readonly applicationJobQueue: import('../../application-jobs/contracts').ApplicationJobQueuePort;

package/src/runtime/backend/mesh-completion-table.ts

@@ -22,6 +22,7 @@ export interface ZLinkMeshCompletionDiagnostic {
 export interface ZLinkMeshCompletion {
   readonly terminalResult: number;
   readonly failureErrno: number;
+  readonly failureMessage?: string;
   readonly operationKind: number;
   readonly kindData: ReceiveKindData | null;
   readonly parts: Message[];
@@ -330,6 +331,7 @@ function retainCompletion(record: ReceiveRecord): ZLinkMeshCompletion {
   return {
     terminalResult: record.terminalResult,
     failureErrno: record.failureErrno,
+    ...(record.failureMessage === undefined ? {} : { failureMessage: record.failureMessage }),
     operationKind: record.operationKind,
     kindData: record.kindData,
     parts

package/src/runtime/backend/node/node-mesh-backend-adapter.ts

@@ -26,7 +26,11 @@ export class ZLinkNodeMeshBackendAdapter implements ZLinkMeshBackendAdapter {
     return new ZLinkNodeRawMeshBackend(
       options.meshName,
       options.routingId,
-      new ZLinkNodeRawBindingPort(bindingContext, options.receiveTimeoutMs),
+      new ZLinkNodeRawBindingPort(bindingContext, {
+        sendHighWaterMark: options.sendHighWaterMark,
+        receiveHighWaterMark: options.receiveHighWaterMark,
+        receiveTimeoutMs: options.receiveTimeoutMs
+      }),
       options.applicationJobQueue,
       options.applicationJobReceiveFlowFailureSink,
       options.peerAdmissionSealed,

package/src/runtime/backend/node/node-raw-binding-port.ts

@@ -42,6 +42,13 @@ import type {
   ZLinkRawRouterRoute,
   ZLinkRawSocketPort
 } from '../raw-binding-port';
+
+interface ZLinkNodeRawRouterSocketOptions {
+  readonly sendHighWaterMark?: number;
+  readonly receiveHighWaterMark?: number;
+  readonly receiveTimeoutMs?: number;
+}
+
 export type {
   ZLinkRawBindingPort,
   ZLinkRawDealerPort,
@@ -57,14 +64,14 @@ export type {
 export class ZLinkNodeRawBindingPort implements ZLinkRawBindingPort {
   constructor(
     private readonly sharedContext?: Context,
-    private readonly routerReceiveTimeoutMs?: number
+    private readonly routerSocketOptions?: ZLinkNodeRawRouterSocketOptions
   ) {}
 
   createHost(): ZLinkRawHostPort {
     return new NodeRawHostPort(
       this.sharedContext ?? createContext(),
       this.sharedContext === undefined,
-      this.routerReceiveTimeoutMs
+      this.routerSocketOptions
     );
   }
 }
@@ -76,13 +83,13 @@ class NodeRawHostPort implements ZLinkRawHostPort {
   constructor(
     private readonly context: Context,
     private readonly ownsContext: boolean,
-    private readonly routerReceiveTimeoutMs?: number
+    private readonly routerSocketOptions?: ZLinkNodeRawRouterSocketOptions
   ) {}
 
   createRouter(): ZLinkRawRouterPort {
     this.requireOpen();
     return this.own(
-      new NodeRawRouterPort(createRouterSocket(this.context), this.routerReceiveTimeoutMs)
+      new NodeRawRouterPort(createRouterSocket(this.context), this.routerSocketOptions)
     );
   }
 
@@ -281,13 +288,19 @@ class NodeRawRouterPort extends NodeRawSocketPort<RouterSocket> implements ZLink
     disconnectSocketPeer(this.socket, this.preparedRoutingId(routingId));
   }
 
-  constructor(socket: RouterSocket, receiveTimeoutMs?: number) {
+  constructor(socket: RouterSocket, options?: ZLinkNodeRawRouterSocketOptions) {
     super(socket, true);
     socket.options.handover = true;
     socket.options.mandatory = true;
     socket.options.probe = true;
-    if (receiveTimeoutMs !== undefined) {
-      socket.options.recvTimeout = receiveTimeoutMs;
+    if (options?.sendHighWaterMark !== undefined) {
+      socket.options.sendHwm = BigInt(options.sendHighWaterMark);
+    }
+    if (options?.receiveHighWaterMark !== undefined) {
+      socket.options.recvHwm = BigInt(options.receiveHighWaterMark);
+    }
+    if (options?.receiveTimeoutMs !== undefined) {
+      socket.options.recvTimeout = options.receiveTimeoutMs;
     }
   }
 

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -190,7 +190,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   private readonly lifecycleGeneration: bigint;
   private bindEndpoint?: string;
   private advertiseHost?: string;
-  private runtime?: RawServiceMeshRuntime;
+  runtime?: RawServiceMeshRuntime;
   private stateful?: ServiceStatefulRuntime;
   private readyHandler?: (domains: number) => number;
   private maintenanceTimer?: NodeJS.Timeout;
@@ -629,6 +629,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
       peer.securityIdentity,
       peer.lifecycleGeneration
     );
+    this.scheduleMaintenance();
   }
 
   removePeerConnection(intentId: bigint): void {
@@ -1690,7 +1691,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     this.requireStateful().clearSubscriptions(state.ref.spotId);
   }
 
-  private createDescriptor(): ServiceNodeDescriptor {
+  createDescriptor(): ServiceNodeDescriptor {
     const channels: ServiceChannelDescriptor[] = [...this.channels]
       .map(([name, weight]) => ({ name, weight }))
       .sort((left, right) => left.name.localeCompare(right.name));
@@ -2559,6 +2560,9 @@ function completionRecord(
     kindData: 'kindData' in result ? (result.kindData ?? null) : null,
     terminalResult: result.terminalResult,
     failureErrno: result.failureCode,
+    ...('failureMessage' in result && result.failureMessage !== undefined
+      ? { failureMessage: result.failureMessage }
+      : {}),
     parts:
       payload === undefined
         ? []
@@ -2808,9 +2812,9 @@ function decodeStatefulRecord(
       });
       return accepted ? SubmitResult.Ok : SubmitResult.InvalidState;
     },
-    replyFailure(terminalResult, failureCode) {
+    replyFailure(terminalResult, failureCode, tail) {
       if (stateful.reply === undefined) return SubmitResult.InvalidState;
-      return stateful.reply(terminalResult, failureCode)
+      return stateful.reply(terminalResult, failureCode, undefined, tail)
         ? SubmitResult.Ok
         : SubmitResult.InvalidState;
     }
@@ -2818,16 +2822,20 @@ function decodeStatefulRecord(
 }
 
 function receiveIngressLifecycle(record: ServiceMailboxRecord): {
+  readonly receivedAt?: Date;
   readonly applicationJobPermit?: import('../../application-jobs/contracts').ApplicationJobPermitPort;
   readonly releaseRetainedIngress?: () => void;
 } {
   const applicationJob = record.applicationJob;
-  return applicationJob === undefined
-    ? {}
-    : {
-        applicationJobPermit: applicationJob,
-        releaseRetainedIngress: () => applicationJob.close()
-      };
+  return {
+    ...(record.receivedAt === undefined ? {} : { receivedAt: record.receivedAt }),
+    ...(applicationJob === undefined
+      ? {}
+      : {
+          applicationJobPermit: applicationJob,
+          releaseRetainedIngress: () => applicationJob.close()
+        })
+  };
 }
 
 function prepareStatefulMailboxDispatch(

package/src/runtime/channels/channel-dispatch-pipeline.ts

@@ -84,10 +84,10 @@ export interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
 }
 
 export class ZLinkChannelDispatchPipeline {
-  private readonly filters: readonly ZLinkHandlerFilter[];
+  readonly filters: readonly ZLinkHandlerFilter[];
   private readonly unhandled: ZLinkUnhandledDispatchOptions;
 
-  constructor(private readonly options: ZLinkChannelDispatchPipelineOptions) {
+  constructor(readonly options: ZLinkChannelDispatchPipelineOptions) {
     this.filters = options.filters ?? [];
     this.unhandled = options.unhandled ?? DEFAULT_UNHANDLED_DISPATCH;
   }
@@ -203,7 +203,7 @@ export class ZLinkChannelDispatchPipeline {
     }
   }
 
-  private invokeInFlow<TContext extends ZLinkMessageContext, TResult>(
+  invokeInFlow<TContext extends ZLinkMessageContext, TResult>(
     dispatch: ZLinkOneWayDispatch<TContext> | ZLinkRequestDispatch<TContext>,
     handler: ZLinkChannelDispatchHandler<TContext, TResult>
   ): unknown {
@@ -330,7 +330,7 @@ export class ZLinkChannelDispatchPipeline {
     });
   }
 
-  private invoke<TContext extends ZLinkMessageContext, TResult>(
+  invoke<TContext extends ZLinkMessageContext, TResult>(
     dispatch: ZLinkOneWayDispatch<TContext> | ZLinkRequestDispatch<TContext>,
     handler: ZLinkChannelDispatchHandler<TContext, TResult>
   ):
@@ -409,6 +409,7 @@ export class ZLinkChannelDispatchPipeline {
       contentType: context.contentType,
       metadata: context.metadata,
       correlationId: context.correlationId,
+      receivedAt: context.receivedAt,
       dispatchKind
     };
   }
@@ -456,7 +457,7 @@ export class ZLinkChannelDispatchPipeline {
     });
   }
 
-  private trace(outcome: ZLinkMessageFlowOutcome, fields: ZLinkChannelDispatchFields): void {
+  trace(outcome: ZLinkMessageFlowOutcome, fields: ZLinkChannelDispatchFields): void {
     if (fields.messageKind === ZLinkDispatchMessageKind.Publish) return;
     const flow = this.options.dispatchErrors.flow;
     const tracePoint = flow.begin(outcome, undefined, fields.flowId);

package/src/runtime/channels/channel-dispatchers.ts

@@ -50,6 +50,7 @@ import {
 export interface ZLinkChannelRequestDispatcherOptions {
   readonly meshName?: string;
   readonly channelName: string;
+  readonly receivedAtClock?: () => Date;
   /**
    * Mesh channels use the routed message context so a handler can associate
    * a report with the node that sent it.
@@ -124,7 +125,8 @@ export class ZLinkChannelRequestDispatcher {
       reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
     },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt: Date = this.options.receivedAtClock?.() ?? new Date()
   ): Promise<boolean | void> {
     if (received.spotId !== null && received.spotId !== undefined) {
       if (received.send === undefined) {
@@ -185,7 +187,8 @@ export class ZLinkChannelRequestDispatcher {
         contentType: envelope.header.contentType,
         packetName,
         metadata: zlinkMessageMetadata(envelope.header.metadata),
-        correlationId
+        correlationId,
+        receivedAt
       };
       await this.pipeline.dispatchOneWay({
         fields,
@@ -221,7 +224,8 @@ export class ZLinkChannelRequestDispatcher {
       contentType: envelope.header.contentType,
       packetName,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId
+      correlationId,
+      receivedAt
     };
     await this.pipeline.dispatchRequest({
       fields: requestFields,
@@ -301,7 +305,7 @@ export class ZLinkChannelRequestDispatcher {
           codecs: this.options.codecs,
           handler: handler?.handler,
           messageType: handler?.messageType,
-          context: this.createMeshContext(envelope, record.sourceNodeRid),
+          context: this.createMeshContext(envelope, record.sourceNodeRid, record.receivedAt),
           signal
         },
         admit
@@ -323,7 +327,7 @@ export class ZLinkChannelRequestDispatcher {
         envelope,
         this.options.codecs,
         this.options.handlers.get(packetName),
-        this.createMeshContext(envelope, record.sourceNodeRid),
+        this.createMeshContext(envelope, record.sourceNodeRid, record.receivedAt),
         signal,
         record,
         'channel',
@@ -346,7 +350,8 @@ export class ZLinkChannelRequestDispatcher {
 
   private createMeshContext(
     envelope: ReturnType<typeof decodeChannelEnvelope>,
-    sourceNodeRid: unknown
+    sourceNodeRid: unknown,
+    receivedAt?: Date
   ): ZLinkMessageContext {
     const base = {
       meshName: this.options.meshName,
@@ -354,7 +359,8 @@ export class ZLinkChannelRequestDispatcher {
       contentType: envelope.header.contentType,
       packetName: envelope.packetName!,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: envelope.header.correlationId ?? undefined
+      correlationId: envelope.header.correlationId ?? undefined,
+      receivedAt: receivedAt ?? this.options.receivedAtClock?.() ?? new Date()
     };
     if (this.options.routeMesh !== true) {
       return base;
@@ -424,6 +430,7 @@ function requireMeshReplyAccepted(result: number): void {
 export interface ZLinkChannelPublishDispatcherOptions {
   readonly meshName?: string;
   readonly channelName: string;
+  readonly receivedAtClock?: () => Date;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
   readonly dispatchErrors: ZLinkDispatchErrorReporter;
   readonly handlers: ReadonlyMap<
@@ -455,7 +462,8 @@ export class ZLinkChannelPublishDispatcher {
   async dispatch(
     topicMessage: { readonly topic: string; readonly parts: readonly Message[] },
     signal?: AbortSignal,
-    decodedHeader?: ZLinkChannelEnvelopeHeader
+    decodedHeader?: ZLinkChannelEnvelopeHeader,
+    receivedAt: Date = this.options.receivedAtClock?.() ?? new Date()
   ): Promise<void> {
     if (topicMessage.parts.length === 0 || topicMessage.parts[0].data().length === 0) {
       return;
@@ -507,7 +515,8 @@ export class ZLinkChannelPublishDispatcher {
       topic: publishTopic,
       source: publishSource,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: publishCorr
+      correlationId: publishCorr,
+      receivedAt
     };
     await this.pipeline.dispatchOneWay({
       fields,
@@ -523,6 +532,7 @@ export class ZLinkChannelPublishDispatcher {
 
 export interface ZLinkRoutePacketDispatcherOptions {
   readonly routerChannelId: string;
+  readonly receivedAtClock?: () => Date;
   readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
   readonly dispatchErrors: ZLinkDispatchErrorReporter;
   readonly handlers: readonly ZLinkRouteHandlerRegistration[];
@@ -557,11 +567,13 @@ export class ZLinkRoutePacketDispatcher {
     Pick<ZLinkRequestDispatch<ZLinkRouteMessageContext>, 'handler' | 'messageType'>
   >();
   private readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
+  private readonly receivedAtClock: () => Date;
   private readonly pipeline: ZLinkChannelDispatchPipeline;
 
   constructor(options: ZLinkRoutePacketDispatcherOptions) {
     this.routerChannelId = options.routerChannelId;
     this.codecs = options.codecs;
+    this.receivedAtClock = options.receivedAtClock ?? (() => new Date());
     this.dispatchErrors = options.dispatchErrors;
     this.pipeline = new ZLinkChannelDispatchPipeline({
       dispatchErrors: options.dispatchErrors,
@@ -635,7 +647,8 @@ export class ZLinkRoutePacketDispatcher {
     },
     signal?: AbortSignal,
     decodedHeader?: ZLinkChannelEnvelopeHeader,
-    infrastructureChecked = false
+    infrastructureChecked = false,
+    receivedAt: Date = this.receivedAtClock()
   ): Promise<boolean | void> {
     const channelHeader =
       decodedHeader ?? tryDecodeChannelHeader(received.parts, this.flowEnabled());
@@ -699,7 +712,7 @@ export class ZLinkRoutePacketDispatcher {
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
         handler: handler?.handler,
         messageType: handler?.messageType,
-        context: this.createRouteContext(envelope, received.routingId),
+        context: this.createRouteContext(envelope, received.routingId, receivedAt),
         signal
       });
       return;
@@ -738,7 +751,7 @@ export class ZLinkRoutePacketDispatcher {
       codecs,
       handler: handler?.handler,
       messageType: handler?.messageType,
-      context: this.createRouteContext(envelope, received.routingId),
+      context: this.createRouteContext(envelope, received.routingId, receivedAt),
       signal,
       missingHandlerMessage: `No routed request handler is registered for '${this.routerChannelId}:${packetName}'.`,
       writeReply: (reply) =>
@@ -801,7 +814,8 @@ export class ZLinkRoutePacketDispatcher {
         sourceNodeRid,
         record.sourceNodeRid,
         signal,
-        admit
+        admit,
+        record.receivedAt ?? this.receivedAtClock()
       );
     }
     if (envelope.header.kind !== ZLinkChannelMessageKind.Request) {
@@ -821,7 +835,7 @@ export class ZLinkRoutePacketDispatcher {
         envelope,
         codecsForFrameworkPacket(packetName, this.codecs),
         this.requestHandlers.get(packetName),
-        this.createRouteContext(envelope, record.sourceNodeRid),
+        this.createRouteContext(envelope, record.sourceNodeRid, record.receivedAt),
         signal,
         record,
         'routed',
@@ -836,6 +850,7 @@ export class ZLinkRoutePacketDispatcher {
     sourceNodeRid: RoutingId,
     signal?: AbortSignal
   ): Promise<void> {
+    const receivedAt = this.receivedAtClock();
     if (parts.length === 0 || parts[0].data().length === 0) return;
     let envelope: ReturnType<typeof decodeChannelEnvelope>;
     try {
@@ -864,7 +879,9 @@ export class ZLinkRoutePacketDispatcher {
       packetName,
       String(sourceNodeRid),
       sourceNodeRid,
-      signal
+      signal,
+      undefined,
+      receivedAt
     );
   }
 
@@ -874,7 +891,8 @@ export class ZLinkRoutePacketDispatcher {
     sourceRid: string,
     sourceNodeRid: unknown,
     signal?: AbortSignal,
-    admit?: ZLinkMeshDispatchAdmission
+    admit?: ZLinkMeshDispatchAdmission,
+    receivedAt: Date = this.receivedAtClock()
   ): void | Promise<void> {
     const handler = this.sendHandlers.get(packetName);
     return this.pipeline.dispatchOneWay(
@@ -891,7 +909,7 @@ export class ZLinkRoutePacketDispatcher {
         codecs: codecsForFrameworkPacket(packetName, this.codecs),
         handler: handler?.handler,
         messageType: handler?.messageType,
-        context: this.createRouteContext(envelope, sourceNodeRid),
+        context: this.createRouteContext(envelope, sourceNodeRid, receivedAt),
         signal
       },
       admit
@@ -907,7 +925,8 @@ export class ZLinkRoutePacketDispatcher {
 
   private createRouteContext(
     envelope: ReturnType<typeof decodeChannelEnvelope>,
-    sourceRid: unknown
+    sourceRid: unknown,
+    receivedAt: Date = this.receivedAtClock()
   ): ZLinkRouteMessageContext {
     const sourceNodeRid = String(sourceRid ?? '');
     return {
@@ -916,7 +935,8 @@ export class ZLinkRoutePacketDispatcher {
       contentType: envelope.header.contentType,
       sourceNodeRid,
       metadata: zlinkMessageMetadata(envelope.header.metadata),
-      correlationId: envelope.header.correlationId ?? undefined
+      correlationId: envelope.header.correlationId ?? undefined,
+      receivedAt
     };
   }
 }