@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,8 +1,11 @@
-import { ZLinkFrameworkException } from '../../contracts';
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
+import { identityRequestReply, type ZLinkRequestResult } from '../messaging/request-result';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import { ZLinkSpotKind } from '../../contracts/Spots';
-import { throwIfAborted } from '../abort';
+import { isAbortError, throwIfAborted } from '../abort';
 import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
 import {
   closeMeshCompletion,
@@ -57,6 +60,7 @@ import type {
 import {
   ZLinkChannelMessageKind,
   decodeChannelReply,
+  closeMessages,
   encodeChannelEnvelopeParts,
   newChannelCorrelationId,
   type ZLinkChannelEnvelopeCodecRegistry
@@ -78,8 +82,9 @@ export interface ZLinkChannelClientTransport {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply>;
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply>;
   tryPublish?(
     channelName: string,
     topic: string,
@@ -136,8 +141,9 @@ export interface ZLinkRouteClientTransport {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply>;
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply>;
   submitToChannel(
     meshName: string,
     channelName: string,
@@ -153,8 +159,9 @@ export interface ZLinkRouteClientTransport {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply>;
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply>;
   sendToSpot?(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -169,11 +176,12 @@ export interface ZLinkRouteClientTransport {
     options: {
       readonly packetName?: string;
       readonly timeoutMs?: number;
+      readonly requestOperation?: PendingOperation<unknown>;
       readonly signal?: AbortSignal;
       readonly onAdmitted?: () => void;
       readonly metadata?: ReadonlyMap<string, string>;
     }
-  ): Promise<TReply>;
+  ): ZLinkRequestResult<TReply>;
 }
 
 interface ZLinkChannelTransportRuntime {
@@ -190,8 +198,9 @@ interface ZLinkChannelTransportRuntime {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply>;
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply>;
   tryPublish(
     channelName: string,
     topic: string,
@@ -224,7 +233,8 @@ interface ZLinkChannelTransportRuntime {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
   ): Promise<TReply>;
   routeSendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
@@ -246,7 +256,9 @@ interface ZLinkChannelTransportRuntime {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply>;
   routeRequestFromSpotToSpot<TReply>(
     sourceSpot: ZLinkBackendSpot,
@@ -255,7 +267,9 @@ interface ZLinkChannelTransportRuntime {
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply>;
   routeRequestRawFromSpotToSpot(
     sourceSpot: ZLinkBackendSpot,
@@ -263,14 +277,16 @@ interface ZLinkChannelTransportRuntime {
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
   ): Promise<readonly Message[]>;
   routeRequestRawToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
   ): Promise<readonly Message[]>;
 }
 
@@ -301,7 +317,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     ) => ZLinkSubmitResult,
     private readonly metrics?: ZLinkRuntimeMetrics,
     private readonly flowCreationEnabled: () => boolean = () => true,
-    private readonly outboundFlow: () => ZLinkMessageFlowTracer | undefined = () => undefined
+    private readonly outboundFlow: () => ZLinkMessageFlowTracer | undefined = () => undefined,
+    private readonly requests = new RequestRuntime()
   ) {}
 
   canRouteChannel(routerChannelId: string): boolean {
@@ -420,8 +437,9 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply> {
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply> {
     if (!this.flowCreationEnabled())
       return this.requestScoped<TReply>(
         meshName,
@@ -431,7 +449,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         timeoutMs,
         signal,
         metadata,
-        onAdmitted
+        onAdmitted,
+        requestOperation
       );
     return runWithOutboundFlow(true, () =>
       this.requestScoped<TReply>(
@@ -442,103 +461,138 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         timeoutMs,
         signal,
         metadata,
-        onAdmitted
+        onAdmitted,
+        requestOperation
       )
     );
   }
 
-  private async requestScoped<TReply>(
+  private requestScoped<TReply>(
     meshName: string,
     targetNodeRid: string,
     packetName: string | undefined,
     request: unknown,
     timeoutMs: number | undefined,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply> {
+    signal: AbortSignal | undefined,
+    metadata: ReadonlyMap<string, string> | undefined,
+    onAdmitted: (() => void) | undefined,
+    existing?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply> {
     const node = this.meshNode(meshName);
     if (node === undefined) {
-      return this.requireManager().routeRequest(
-        meshName,
-        targetNodeRid,
-        packetName,
-        request,
-        timeoutMs,
+      return this.requests.prepare<TReply>(
+        timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
         signal,
-        metadata,
-        onAdmitted
+        (operation) => {
+          this.requireManager().routeRequest<TReply>(
+            meshName,
+            targetNodeRid,
+            packetName,
+            request,
+            timeoutMs,
+            signal,
+            metadata,
+            onAdmitted,
+            operation
+          );
+        },
+        (value) => value as TReply,
+        identityRequestReply,
+        existing
       );
     }
     const correlationId = newChannelCorrelationId();
-    try {
-      throwIfAborted(signal);
-      if (node.isObjectClientNodeDirectTarget?.(toBackendRoutingId(targetNodeRid)) === true) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-          `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`
+    const result = this.requests.prepare<TReply>(
+      timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      signal,
+      (requestOperation, receiver) => {
+        requestOperation.mapCaller(
+          (value) => {
+            this.traceNodeRequest(
+              ZLinkMessageFlowOutcome.ReplyReceived,
+              'succeeded',
+              meshName,
+              targetNodeRid,
+              packetName,
+              correlationId
+            );
+            return value;
+          },
+          (error) => {
+            if (!isRemoteChannelErrorReply(error))
+              this.traceNodeRequest(
+                ZLinkMessageFlowOutcome.ReplyReceived,
+                requestTerminalResult(error, signal),
+                meshName,
+                targetNodeRid,
+                packetName,
+                correlationId,
+                error
+              );
+            throw error;
+          }
         );
-      }
-      const parts = this.encodeMessage(
-        ZLinkChannelMessageKind.Request,
-        meshName,
-        packetName,
-        request,
-        timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-        metadata,
-        correlationId
-      );
-      const requestOptions = { flags: 1, onAdmitted, timeoutMs: requestTimeoutBudget(timeoutMs) };
-      let completion: ZLinkMeshCompletion;
-      try {
-        completion = await this.completionTable(meshName).submit(() => {
-          const operationId = node.requestToNode(
-            toBackendRoutingId(targetNodeRid),
-            parts,
-            requestOptions
+        throwIfAborted(signal);
+        if (node.isObjectClientNodeDirectTarget?.(toBackendRoutingId(targetNodeRid)) === true) {
+          throw createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
+            `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`
           );
-          this.traceNodeRequest(
-            ZLinkMessageFlowOutcome.Sent,
-            undefined,
+        }
+        let parts: readonly MessageLike[] | undefined;
+        try {
+          parts = this.encodeMessage(
+            ZLinkChannelMessageKind.Request,
             meshName,
-            targetNodeRid,
             packetName,
+            request,
+            timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            metadata,
             correlationId
           );
-          return operationId;
-        }, signal);
-      } catch (error) {
-        throw mapMeshSubmissionError(
-          error,
-          `MeshNode '${meshName}' request to node '${targetNodeRid}'`
-        );
-      }
-      const reply = this.decodeMeshReply<TReply>(meshName, completion);
-      this.traceNodeRequest(
-        ZLinkMessageFlowOutcome.ReplyReceived,
-        'succeeded',
-        meshName,
-        targetNodeRid,
-        packetName,
-        correlationId
-      );
-      return reply;
-    } catch (error) {
-      if (!isRemoteChannelErrorReply(error)) {
-        this.traceNodeRequest(
-          ZLinkMessageFlowOutcome.ReplyReceived,
-          requestTerminalResult(error, signal),
-          meshName,
-          targetNodeRid,
-          packetName,
-          correlationId,
-          error
-        );
-      }
-      throw error;
-    }
+        } catch (error) {
+          requestOperation.fail(error);
+          return;
+        }
+        try {
+          this.completionTable(meshName).submit(
+            (completion) => {
+              const operationId = node.requestToNode(
+                toBackendRoutingId(targetNodeRid),
+                parts!,
+                {
+                  requestOperation,
+                  flags: 1,
+                  onAdmitted,
+                  timeoutMs: requestTimeoutBudget(timeoutMs)
+                },
+                completion
+              );
+              this.traceNodeRequest(
+                ZLinkMessageFlowOutcome.Sent,
+                undefined,
+                meshName,
+                targetNodeRid,
+                packetName,
+                correlationId
+              );
+              return operationId;
+            },
+            signal,
+            requestOperation,
+            receiver
+          );
+        } finally {
+          parts = undefined;
+        }
+      },
+      (raw) => this.decodeMeshReply<TReply>(meshName, raw as ZLinkMeshCompletion),
+      (error) =>
+        mapMeshSubmissionError(error, `MeshNode '${meshName}' request to '${targetNodeRid}'`),
+      existing
+    );
+    return result;
   }
-
   private traceNodeRequest(
     outcome: ZLinkMessageFlowOutcome,
     result: ZLinkRuntimeMessageFlowResult | undefined,
@@ -612,8 +666,9 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     timeoutMs: number | undefined,
     signal?: AbortSignal,
     metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply> {
+    onAdmitted?: () => void,
+    requestOperation?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply> {
     if (!this.flowCreationEnabled())
       return this.requestToChannelScoped<TReply>(
         meshName,
@@ -623,7 +678,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         timeoutMs,
         signal,
         metadata,
-        onAdmitted
+        onAdmitted,
+        requestOperation
       );
     return runWithOutboundFlow(true, () =>
       this.requestToChannelScoped<TReply>(
@@ -634,61 +690,90 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
         timeoutMs,
         signal,
         metadata,
-        onAdmitted
+        onAdmitted,
+        requestOperation
       )
     );
   }
 
-  private async requestToChannelScoped<TReply>(
+  private requestToChannelScoped<TReply>(
     meshName: string,
     channelName: string,
     packetName: string | undefined,
     request: unknown,
     timeoutMs: number | undefined,
-    signal?: AbortSignal,
-    metadata?: ReadonlyMap<string, string>,
-    onAdmitted?: () => void
-  ): Promise<TReply> {
-    throwIfAborted(signal);
-    const node = this.requireMeshNode(meshName);
-    const parts = this.encodeMessage(
-      ZLinkChannelMessageKind.Request,
-      channelName,
-      packetName,
-      request,
+    signal: AbortSignal | undefined,
+    metadata: ReadonlyMap<string, string> | undefined,
+    onAdmitted: (() => void) | undefined,
+    existing?: PendingOperation<unknown>
+  ): ZLinkRequestResult<TReply> {
+    let metric: ReturnType<ZLinkRuntimeMetrics['startRequest']> | undefined;
+    const result = this.requests.prepare<TReply>(
       timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-      metadata
-    );
-    const metric = this.metrics?.startRequest(meshName, 'channel');
-    try {
-      const requestOptions = { flags: 1, timeoutMs: requestTimeoutBudget(timeoutMs), onAdmitted };
-      let completion: ZLinkMeshCompletion;
-      try {
-        completion = await this.completionTable(meshName).submit(
-          () => node.requestToChannel(channelName, parts, requestOptions),
-          signal
+      signal,
+      (requestOperation, receiver) => {
+        requestOperation.mapCaller(
+          (value) => {
+            metric?.complete('completed');
+            return value;
+          },
+          (error) => {
+            metric?.complete(requestMetricOutcome(error, signal));
+            if (
+              error instanceof ZLinkFrameworkException &&
+              internalFrameworkErrorKind(error) ===
+                ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+            )
+              this.metrics?.recordChannelSelectionFailure(meshName, channelName, 'no_ready_target');
+            throw error;
+          }
         );
-      } catch (error) {
-        throw mapMeshSubmissionError(
-          error,
-          `MeshNode '${meshName}' request to channel '${channelName}'`
-        );
-      }
-      const reply = this.decodeMeshReply<TReply>(meshName, completion);
-      metric?.complete('completed');
-      return reply;
-    } catch (error) {
-      metric?.complete(requestMetricOutcome(error, signal));
-      if (
-        error instanceof ZLinkFrameworkException &&
-        internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
-      ) {
-        this.metrics?.recordChannelSelectionFailure(meshName, channelName, 'no_ready_target');
-      }
-      throw error;
-    }
+        throwIfAborted(signal);
+        const node = this.requireMeshNode(meshName);
+        let parts: readonly MessageLike[] | undefined;
+        try {
+          parts = this.encodeMessage(
+            ZLinkChannelMessageKind.Request,
+            channelName,
+            packetName,
+            request,
+            timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+            metadata
+          );
+        } catch (error) {
+          requestOperation.fail(error);
+          return;
+        }
+        metric = this.metrics?.startRequest(meshName, 'channel');
+        try {
+          this.completionTable(meshName).submit(
+            (completion) =>
+              node.requestToChannel(
+                channelName,
+                parts!,
+                {
+                  requestOperation,
+                  flags: 1,
+                  timeoutMs: requestTimeoutBudget(timeoutMs),
+                  onAdmitted
+                },
+                completion
+              ),
+            signal,
+            requestOperation,
+            receiver
+          );
+        } finally {
+          parts = undefined;
+        }
+      },
+      (raw) => this.decodeMeshReply<TReply>(meshName, raw as ZLinkMeshCompletion),
+      (error) =>
+        mapMeshSubmissionError(error, `MeshNode '${meshName}' channel '${channelName}' request`),
+      existing
+    );
+    return result;
   }
-
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -782,104 +867,143 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: ZLinkSpotRoutedRequestOptions
-  ): Promise<TReply> {
+    options: ZLinkSpotRoutedRequestOptions,
+    destination?: OperationObserver<unknown, unknown>
+  ): ZLinkRequestResult<TReply> {
     return runWithOutboundFlow(this.flowCreationEnabled(), () =>
-      this.requestToSpotScoped<TReply>(spotRouteTarget, request, options)
+      this.requestToSpotScoped<TReply>(spotRouteTarget, request, options, destination)
     );
   }
 
-  private async requestToSpotScoped<TReply = unknown>(
+  private requestToSpotScoped<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
-    options: ZLinkSpotRoutedRequestOptions
-  ): Promise<TReply> {
+    options: ZLinkSpotRoutedRequestOptions,
+    destination?: OperationObserver<unknown, unknown>
+  ): ZLinkRequestResult<TReply> {
     const meshName = spotRouteTarget.routerChannelId;
     const node = this.meshNode(meshName);
     if (node === undefined) {
-      if (spotRouteTarget.spotKind === ZLinkSpotKind.Instance) {
+      if (spotRouteTarget.spotKind === ZLinkSpotKind.Instance)
         throw new ZLinkConfigurationException(
           'Instance Spot routes require the MeshNode command 39 transport.'
         );
-      }
-      return this.requireManager().routeRequestToSpot<TReply>(
-        spotRouteTarget,
-        options.packetName,
-        request,
-        options.timeoutMs,
+      return this.requests.prepare<TReply>(
+        options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
         options.signal,
-        options.metadata,
-        options.onAdmitted
-      );
-    }
-    throwIfAborted(options.signal);
-    let completionPromise: Promise<ZLinkMeshCompletion>;
-    try {
-      const encoded = this.encodeMessage(
-        ZLinkChannelMessageKind.Request,
-        meshName,
-        options.packetName,
-        request,
-        options.timeoutMs,
-        options.metadata
-      );
-      completionPromise = this.completionTable(meshName).submit(
-        () =>
-          spotRouteTarget.spotKind === ZLinkSpotKind.Instance
-            ? node.requestInstanceSpot(
-                instanceSpotRouteFence(spotRouteTarget),
-                encoded,
-                options.timeoutMs,
-                undefined,
-                options.metadata,
-                options.instanceSpot,
-                options.onAdmitted
-              )
-            : node
-                .entrySpot()
-                .requestToSpot(
-                  toBackendRoutingId(spotRouteTarget.targetNodeRid),
-                  toBackendRoutingId(spotRouteTarget.spotId),
-                  spotRouteTarget.targetSpotGeneration ?? 0n,
-                  encoded,
-                  {
-                    flags: 1,
-                    onAdmitted: options.onAdmitted,
-                    timeoutMs: options.timeoutMs,
-                    routeFence: directSpotRouteFence(spotRouteTarget),
-                    entrySpot: spotRouteTarget.spotKind === ZLinkSpotKind.Entry
-                  }
-                ),
-        options.signal
-      );
-    } catch (error) {
-      throw mapMeshSubmissionError(
-        error,
-        `MeshNode '${meshName}' request to Spot '${spotRouteTarget.spotId}'`
+        (operation, receiver) => {
+          this.requireManager().routeRequestToSpot<TReply>(
+            spotRouteTarget,
+            options.packetName,
+            request,
+            options.timeoutMs,
+            options.signal,
+            options.metadata,
+            options.onAdmitted,
+            operation,
+            receiver
+          );
+        },
+        (value) => value as TReply,
+        identityRequestReply,
+        options.requestOperation,
+        destination
       );
     }
-    return this.waitForMeshReply<TReply>(meshName, completionPromise);
+    return this.requests.prepare<TReply>(
+      options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options.signal,
+      (requestOperation, receiver) => {
+        try {
+          throwIfAborted(options.signal);
+          const encoded = this.encodeMessage(
+            ZLinkChannelMessageKind.Request,
+            meshName,
+            options.packetName,
+            request,
+            options.timeoutMs,
+            options.metadata
+          );
+          this.completionTable(meshName).submit(
+            (completion) =>
+              spotRouteTarget.spotKind === ZLinkSpotKind.Instance
+                ? node.requestInstanceSpot(
+                    instanceSpotRouteFence(spotRouteTarget),
+                    encoded,
+                    options.timeoutMs,
+                    undefined,
+                    options.metadata,
+                    options.instanceSpot,
+                    options.onAdmitted,
+                    requestOperation,
+                    completion
+                  )
+                : node.entrySpot().requestToSpot(
+                    toBackendRoutingId(spotRouteTarget.targetNodeRid),
+                    toBackendRoutingId(spotRouteTarget.spotId),
+                    spotRouteTarget.targetSpotGeneration ?? 0n,
+                    encoded,
+                    {
+                      flags: 1,
+                      onAdmitted: options.onAdmitted,
+                      timeoutMs: options.timeoutMs,
+                      requestOperation,
+                      routeFence: directSpotRouteFence(spotRouteTarget),
+                      entrySpot: spotRouteTarget.spotKind === ZLinkSpotKind.Entry
+                    },
+                    completion
+                  ),
+            options.signal,
+            requestOperation,
+            receiver
+          );
+        } catch (error) {
+          receiver.operationFailed(requestOperation.id, error, undefined);
+        }
+      },
+      (raw) => this.decodeMeshReply<TReply>(meshName, raw as ZLinkMeshCompletion),
+      (error) =>
+        mapMeshSubmissionError(
+          error,
+          `MeshNode '${meshName}' request to Spot '${spotRouteTarget.spotId}'`
+        ),
+      options.requestOperation,
+      destination
+    );
   }
-
-  async requestFromSpotToSpot<TReply = unknown>(
+  requestFromSpotToSpot<TReply = unknown>(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: unknown,
     options: {
       readonly packetName?: string;
       readonly timeoutMs?: number;
+      readonly requestOperation?: PendingOperation<unknown>;
       readonly signal?: AbortSignal;
       readonly onAdmitted?: () => void;
-    }
-  ): Promise<TReply> {
-    return this.requireManager().routeRequestFromSpotToSpot<TReply>(
-      sourceSpot,
-      spotRouteTarget,
-      options.packetName,
-      request,
-      options.timeoutMs,
+    },
+    destination?: OperationObserver<unknown, unknown>
+  ): ZLinkRequestResult<TReply> {
+    return this.requests.prepare<TReply>(
+      options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
       options.signal,
-      options.onAdmitted
+      (operation, receiver) => {
+        this.requireManager().routeRequestFromSpotToSpot<TReply>(
+          sourceSpot,
+          spotRouteTarget,
+          options.packetName,
+          request,
+          options.timeoutMs,
+          options.signal,
+          options.onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => value as TReply,
+      identityRequestReply,
+      options.requestOperation,
+      destination
     );
   }
 
@@ -889,6 +1013,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     request: Message,
     options: {
       readonly timeoutMs?: number;
+      readonly requestOperation?: PendingOperation<unknown>;
       readonly signal?: AbortSignal;
       readonly onAdmitted?: () => void;
     }
@@ -899,7 +1024,8 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
       request,
       options.timeoutMs,
       options.signal,
-      options.onAdmitted
+      options.onAdmitted,
+      options.requestOperation
     );
   }
 
@@ -908,6 +1034,7 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     request: Message,
     options: {
       readonly timeoutMs?: number;
+      readonly requestOperation?: PendingOperation<unknown>;
       readonly signal?: AbortSignal;
       readonly onAdmitted?: () => void;
     }
@@ -922,74 +1049,75 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     request: Message,
     options: {
       readonly timeoutMs?: number;
+      readonly requestOperation?: PendingOperation<unknown>;
       readonly signal?: AbortSignal;
       readonly onAdmitted?: () => void;
     }
   ): Promise<readonly Message[]> {
     const meshName = spotRouteTarget.routerChannelId;
     const node = this.meshNode(meshName);
-    if (node !== undefined) {
-      throwIfAborted(options.signal);
-      const payload = JSON.parse(request.getString('utf8')) as Record<string, unknown>;
-      const packetName = typeof payload.packetName === 'string' ? payload.packetName : undefined;
-      const parts = this.encodeMessage(
-        ZLinkChannelMessageKind.Request,
-        meshName,
-        packetName,
-        payload,
-        options.timeoutMs
+    if (node === undefined)
+      return this.requireManager().routeRequestRawToSpot(
+        spotRouteTarget,
+        request,
+        options.timeoutMs,
+        options.signal,
+        options.onAdmitted,
+        options.requestOperation
       );
-      let completionPromise: Promise<ZLinkMeshCompletion>;
-      try {
-        completionPromise = this.completionTable(meshName).submit(
-          () =>
-            node
-              .entrySpot()
-              .requestToSpot(
-                toBackendRoutingId(spotRouteTarget.targetNodeRid),
-                toBackendRoutingId(spotRouteTarget.spotId),
-                spotRouteTarget.targetSpotGeneration ?? 0n,
-                parts,
-                {
-                  flags: 1,
-                  onAdmitted: options.onAdmitted,
-                  timeoutMs: options.timeoutMs,
-                  routeFence: directSpotRouteFence(spotRouteTarget),
-                  entrySpot: spotRouteTarget.spotKind === ZLinkSpotKind.Entry
-                }
-              ),
-          options.signal
+    const operation = this.requests.begin(
+      options.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options.signal,
+      options.requestOperation
+    );
+    return this.requests.run<readonly Message[]>(
+      operation,
+      (receiver) => {
+        throwIfAborted(options.signal);
+        const payload = JSON.parse(request.getString('utf8')) as Record<string, unknown>;
+        const packetName = typeof payload.packetName === 'string' ? payload.packetName : undefined;
+        const parts = this.encodeMessage(
+          ZLinkChannelMessageKind.Request,
+          meshName,
+          packetName,
+          payload,
+          options.timeoutMs
         );
-      } catch (error) {
-        throw mapMeshSubmissionError(
+        this.completionTable(meshName).submit(
+          (completion) =>
+            node.entrySpot().requestToSpot(
+              toBackendRoutingId(spotRouteTarget.targetNodeRid),
+              toBackendRoutingId(spotRouteTarget.spotId),
+              spotRouteTarget.targetSpotGeneration ?? 0n,
+              parts,
+              {
+                flags: 1,
+                onAdmitted: options.onAdmitted,
+                timeoutMs: options.timeoutMs,
+                requestOperation: operation,
+                routeFence: directSpotRouteFence(spotRouteTarget),
+                entrySpot: spotRouteTarget.spotKind === ZLinkSpotKind.Entry
+              },
+              completion
+            ),
+          options.signal,
+          operation,
+          receiver
+        );
+      },
+      (raw) => {
+        const reply = this.decodeMeshReply<unknown>(meshName, raw as ZLinkMeshCompletion);
+        const parts = [ZLinkBufferMessage.fromOwned(Buffer.from(JSON.stringify(reply)))];
+        if (!operation.isPending()) closeMessages(parts);
+        return parts;
+      },
+      (error) =>
+        mapMeshSubmissionError(
           error,
           `MeshNode '${meshName}' raw request to Spot '${spotRouteTarget.spotId}'`
-        );
-      }
-      const completion = await completionPromise;
-      if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-        try {
-          throw meshRequestFailure(meshName, completion.terminalResult, completion.failureErrno);
-        } finally {
-          closeMeshCompletion(completion);
-        }
-      }
-      try {
-        const reply = decodeChannelReply<unknown>(completion.parts, this.codecs);
-        return [ZLinkBufferMessage.fromOwned(Buffer.from(JSON.stringify(reply)))];
-      } finally {
-        closeMeshCompletion(completion);
-      }
-    }
-    return this.requireManager().routeRequestRawToSpot(
-      spotRouteTarget,
-      request,
-      options.timeoutMs,
-      options.signal,
-      options.onAdmitted
+        )
     );
   }
-
   private requireManager(): ZLinkChannelTransportRuntime {
     const manager = this.manager();
     if (manager === undefined) {
@@ -999,7 +1127,9 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
   }
 
   private meshNode(meshName: string): ZLinkBackendMeshNode | undefined {
-    return this.meshRuntime?.()?.meshNode?.(meshName);
+    const runtime = this.meshRuntime?.();
+    if (runtime === undefined) this.requireManager();
+    return runtime?.meshNode?.(meshName);
   }
 
   private isKnownBackendPeer(node: ZLinkBackendMeshNode, targetNodeRid: string): boolean {
@@ -1067,14 +1197,6 @@ export class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
     );
   }
 
-  private async waitForMeshReply<TReply>(
-    meshName: string,
-    completionPromise: Promise<ZLinkMeshCompletion>
-  ): Promise<TReply> {
-    const completion = await completionPromise;
-    return this.decodeMeshReply<TReply>(meshName, completion);
-  }
-
   private decodeMeshReply<TReply>(meshName: string, completion: ZLinkMeshCompletion): TReply {
     try {
       if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
@@ -1160,7 +1282,7 @@ function mapMeshSubmitResult(result: number): ZLinkSubmitResult {
   return classifySubmitResult(result, 'Mesh submission');
 }
 
-function mapMeshSubmissionError(error: unknown, operation: string): Error {
+function mapMeshSubmissionError(error: unknown, operation: string): unknown {
   if (error instanceof ZLinkFrameworkException) {
     return error;
   }
@@ -1196,12 +1318,17 @@ function mapMeshSubmissionError(error: unknown, operation: string): Error {
       error
     );
   }
-  return createInternalFrameworkException(
-    ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-    `${operation} failed before native submission completed: ${
-      error instanceof Error ? error.message : String(error)
-    }`,
-    true,
+  if (
+    isAbortError(error) ||
+    error instanceof ZLinkConfigurationException ||
+    error instanceof TypeError ||
+    error instanceof RangeError
+  ) {
+    return error;
+  }
+  return new ZLinkFrameworkException(
+    ZLinkFrameworkErrorKind.InternalFailure,
+    `${operation} failed.`,
     error
   );
 }