@zlink-systems/framework 0.30.3 → 0.32.0

package/src/runtime/channels/dispatch-error-reporter.ts

@@ -7,15 +7,13 @@ import {
   type ZLinkDispatchFailure
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import {
-  type ZLinkRuntimeMetrics,
   DEFAULT_ZLINK_DIAGNOSTICS,
   ZLinkMessageFlowTracer,
   type ZLinkDiagnosticsContext
-} from '../diagnostics';
+} from '../diagnostics/message-flow';
 
 import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
-import type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
-import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
+import { METRIC_NAMES, type ZLinkRuntimeMetrics } from '../diagnostics/runtime-metrics';
 
 export type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
 
@@ -29,14 +27,11 @@ export class ZLinkDispatchErrorReporter {
   /**
    * Success-path tracer companion: every surface already receives a reporter, so
    * exposing the flow tracer here wires all dispatch sites without threading a new
-   * parameter. Shares the same diagnostics context (live mode) and error sink.
+   * parameter. Shares the diagnostics context and host submission lease.
    */
   readonly flow: ZLinkMessageFlowTracer;
 
   constructor(
-    _observerType: undefined,
-    _providerResolver: unknown,
-    errorSink: ZLinkDispatchErrorSink,
     ctx?: ZLinkDiagnosticsContext,
     readonly metrics?: ZLinkRuntimeMetrics
   ) {
@@ -45,7 +40,7 @@ export class ZLinkDispatchErrorReporter {
       liveMode: { mode: 'errors' },
       sourceMeshGeneration: 0n
     };
-    this.flow = new ZLinkMessageFlowTracer(flowCtx, errorSink);
+    this.flow = new ZLinkMessageFlowTracer(flowCtx);
   }
 
   report(event: ZLinkRuntimeDispatchFailure): void {

package/src/runtime/channels/local-spot-route-transport.ts

@@ -1,3 +1,5 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
 import type { RoutingId } from '../../contracts';
 import { ZLinkConfigurationException } from '../configuration';
 import type { ZLinkLocalSpotRouteDispatcher } from './spot-route-dispatch-strategy';
@@ -5,7 +7,8 @@ import type { ZLinkLocalSpotRouteDispatcher } from './spot-route-dispatch-strate
 export class ZLinkLocalSpotRouteTransport {
   constructor(
     private readonly dispatcher: ZLinkLocalSpotRouteDispatcher | undefined,
-    private readonly defaultRequestTimeoutMs: number | undefined
+    private readonly defaultRequestTimeoutMs: number | undefined,
+    private readonly requests = new RequestRuntime()
   ) {}
 
   async send(
@@ -33,40 +36,35 @@ export class ZLinkLocalSpotRouteTransport {
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply> {
     if (this.dispatcher === undefined) {
       throw new ZLinkConfigurationException(
         `Route channel '${routerChannelId}' could not dispatch local SPOT request.`
       );
     }
-    const pending = this.dispatcher.request<TReply>(spotId, packetName, request, {
-      channelName: routerChannelId,
-      onAdmitted,
-      signal
-    });
     const effectiveTimeoutMs = timeoutMs ?? this.defaultRequestTimeoutMs;
-    if (effectiveTimeoutMs === undefined) return pending;
-    return new Promise<TReply>((resolve, reject) => {
-      const timeout = setTimeout(
-        () =>
-          reject(
-            new ZLinkConfigurationException(
-              `Route channel '${routerChannelId}' local SPOT request timed out.`
-            )
-          ),
-        effectiveTimeoutMs
-      );
-      pending.then(
-        (value) => {
-          clearTimeout(timeout);
-          resolve(value);
-        },
-        (error) => {
-          clearTimeout(timeout);
-          reject(error);
-        }
-      );
-    });
+    const dispatcher = this.dispatcher;
+    const operation = this.requests.begin(effectiveTimeoutMs, signal, existing);
+    return this.requests.run<TReply>(
+      operation,
+      (receiver) => {
+        const work = dispatcher.request<TReply>(spotId, packetName, request, {
+          channelName: routerChannelId,
+          onAdmitted,
+          signal,
+          requestOperation: operation
+        });
+        void work.then(
+          (value) => receiver.operationCompleted(operation.id, value, undefined),
+          (error) => receiver.operationFailed(operation.id, error, undefined)
+        );
+      },
+      (value) => value as TReply,
+      (error) => error,
+      destination
+    );
   }
 }

package/src/runtime/channels/router-socket-spot-route-transport.ts

@@ -1,7 +1,8 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendSendFlags } from '../backend/contracts';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import { awaitWithAbort } from '../abort';
 import {
   closeMessages,
   decodeChannelReply,
@@ -10,7 +11,10 @@ import {
 import type { ZLinkChannelSocketRegistry } from './channel-socket-registry';
 
 export class ZLinkRouterSocketSpotRouteTransport {
-  constructor(private readonly sockets: ZLinkChannelSocketRegistry) {}
+  constructor(
+    private readonly sockets: ZLinkChannelSocketRegistry,
+    private readonly requests = new RequestRuntime()
+  ) {}
 
   async send(
     target: ZLinkSpotRouteTarget,
@@ -25,52 +29,79 @@ export class ZLinkRouterSocketSpotRouteTransport {
     }
   }
 
-  async request<TReply>(
+  request<TReply>(
     target: ZLinkSpotRouteTarget,
     parts: readonly Message[],
     codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
     flags: ZLinkBackendSendFlags,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply> {
-    const router = this.sockets.routeRouter(target.routerChannelId);
-    void flags;
-    const operation = router.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      parts,
-      timeoutMs,
-      onAdmitted
-    );
-    const replyParts = await awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
     try {
-      return decodeChannelReply<TReply>(replyParts, codecs);
-    } finally {
-      closeMessages(replyParts);
-      closeMessages(parts);
+      const operation = this.requests.begin(timeoutMs, signal, existing);
+      return this.requests.run<TReply>(
+        operation,
+        (receiver) => {
+          const router = this.sockets.routeRouter(target.routerChannelId);
+          void flags;
+          router.requestToSpot(
+            target.targetNodeRid,
+            target.spotId,
+            parts,
+            timeoutMs,
+            onAdmitted,
+            operation,
+            receiver
+          );
+        },
+        (value) => {
+          const replyParts = value as readonly Message[];
+          try {
+            return decodeChannelReply<TReply>(replyParts, codecs);
+          } finally {
+            closeMessages(replyParts);
+            closeMessages(parts);
+          }
+        },
+        (error) => error,
+        destination
+      );
+    } catch (error) {
+      return Promise.reject(error);
     }
   }
-
   async requestRaw(
     target: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<readonly Message[]> {
-    const router = this.sockets.routeRouter(target.routerChannelId);
-    const operation = router.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      [request],
-      timeoutMs,
-      onAdmitted
+    const operation = this.requests.begin(timeoutMs, signal, existing);
+    return this.requests.run<readonly Message[]>(
+      operation,
+      (receiver) => {
+        const router = this.sockets.routeRouter(target.routerChannelId);
+        router.requestToSpot(
+          target.targetNodeRid,
+          target.spotId,
+          [request],
+          timeoutMs,
+          onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        if (!operation.isPending()) closeMessages(replyParts);
+        return replyParts;
+      },
+      (error) => error
     );
-    return await awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
   }
 }

package/src/runtime/channels/source-spot-router.ts

@@ -1,49 +1,70 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendSpot } from '../backend/contracts';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import { awaitWithAbort, throwIfAborted } from '../abort';
+import { throwIfAborted } from '../abort';
 import { closeMessages, ZLinkChannelMessageKind } from './channel-envelope';
 import { decodeSpotDirectReply, encodeSpotDirectEnvelope } from './spot-direct-envelope';
 
 export class ZLinkSourceSpotRouter {
-  constructor(private readonly defaultRequestTimeoutMs: number | undefined) {}
+  constructor(
+    private readonly defaultRequestTimeoutMs: number | undefined,
+    private readonly requests = new RequestRuntime()
+  ) {}
 
-  async request<TReply>(
+  request<TReply>(
     sourceSpot: ZLinkBackendSpot,
     target: ZLinkSpotRouteTarget,
     packetName: string | undefined,
     request: unknown,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply> {
-    throwIfAborted(signal);
-    const parts = [
-      encodeSpotDirectEnvelope(
-        ZLinkChannelMessageKind.Request,
-        target.routerChannelId,
-        packetName,
-        request
-      )
-    ] as readonly Message[];
-    const operation = sourceSpot.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      parts,
+    let parts: readonly Message[];
+    const operation = this.requests.begin(
       timeoutMs ?? this.defaultRequestTimeoutMs,
-      onAdmitted
+      signal,
+      existing
+    );
+    return this.requests.run<TReply>(
+      operation,
+      (receiver) => {
+        throwIfAborted(signal);
+        parts = [
+          encodeSpotDirectEnvelope(
+            ZLinkChannelMessageKind.Request,
+            target.routerChannelId,
+            packetName,
+            request
+          )
+        ] as readonly Message[];
+        sourceSpot.requestToSpot(
+          target.targetNodeRid,
+          target.spotId,
+          parts,
+          timeoutMs ?? this.defaultRequestTimeoutMs,
+          onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        try {
+          return decodeSpotDirectReply<TReply>(replyParts);
+        } finally {
+          closeMessages(replyParts);
+          closeMessages(parts);
+        }
+      },
+      (error) => error,
+      destination
     );
-    const replyParts = await awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
-    try {
-      return decodeSpotDirectReply<TReply>(replyParts);
-    } finally {
-      closeMessages(replyParts);
-      closeMessages(parts);
-    }
   }
-
   async send(
     sourceSpot: ZLinkBackendSpot,
     target: ZLinkSpotRouteTarget,
@@ -73,18 +94,34 @@ export class ZLinkSourceSpotRouter {
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<readonly Message[]> {
-    throwIfAborted(signal);
-    const operation = sourceSpot.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      request,
+    const operation = this.requests.begin(
       timeoutMs ?? this.defaultRequestTimeoutMs,
-      onAdmitted
+      signal,
+      existing
+    );
+    return this.requests.run<readonly Message[]>(
+      operation,
+      (receiver) => {
+        throwIfAborted(signal);
+        sourceSpot.requestToSpot(
+          target.targetNodeRid,
+          target.spotId,
+          request,
+          timeoutMs ?? this.defaultRequestTimeoutMs,
+          onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        if (!operation.isPending()) closeMessages(replyParts);
+        return replyParts;
+      },
+      (error) => error
     );
-    return await awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
   }
 }

package/src/runtime/channels/spot-node-route-transport.ts

@@ -1,7 +1,8 @@
-import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkFrameworkRegistration } from '../configuration';
-import { awaitWithAbort, throwIfAborted } from '../abort';
+import { throwIfAborted } from '../abort';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import {
   closeMessages,
@@ -13,7 +14,8 @@ import { ZLinkSpotRouteTargetResolver } from './spot-route-target-resolver';
 export class ZLinkSpotNodeRouteTransport {
   constructor(
     private readonly registration: ZLinkFrameworkRegistration,
-    private readonly targets: ZLinkSpotRouteTargetResolver
+    private readonly targets: ZLinkSpotRouteTargetResolver,
+    private readonly requests = new RequestRuntime()
   ) {}
 
   async send(target: ZLinkSpotRouteTarget, parts: readonly Message[]): Promise<boolean> {
@@ -35,57 +37,85 @@ export class ZLinkSpotNodeRouteTransport {
     codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply> | undefined {
     const router = this.targets.spotNodeRouter(target.routerChannelId);
     if (router === undefined) {
       return undefined;
     }
-    const effectiveTimeoutMs =
-      timeoutMs ?? this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    throwIfAborted(signal);
-    const operation = router.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      parts,
-      effectiveTimeoutMs,
-      onAdmitted
+
+    const operation = this.requests.begin(
+      timeoutMs ?? this.registration.requestTimeoutMs,
+      signal,
+      existing
+    );
+    return this.requests.run<TReply>(
+      operation,
+      (receiver) => {
+        throwIfAborted(signal);
+        router.requestToSpot(
+          target.targetNodeRid,
+          target.spotId,
+          parts,
+          timeoutMs ?? this.registration.requestTimeoutMs,
+          onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        try {
+          return decodeChannelReply<TReply>(replyParts, codecs);
+        } finally {
+          closeMessages(replyParts);
+          closeMessages(parts);
+        }
+      },
+      (error) => error,
+      destination
     );
-    return awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    }).then((replyParts) => {
-      try {
-        return decodeChannelReply<TReply>(replyParts, codecs);
-      } finally {
-        closeMessages(replyParts);
-        closeMessages(parts);
-      }
-    });
   }
-
   requestRaw(
     target: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<readonly Message[]> | undefined {
     const router = this.targets.spotNodeRouter(target.routerChannelId);
     if (router === undefined) {
       return undefined;
     }
-    const effectiveTimeoutMs =
-      timeoutMs ?? this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
-    throwIfAborted(signal);
-    const operation = router.requestToSpot(
-      target.targetNodeRid,
-      target.spotId,
-      request,
-      effectiveTimeoutMs,
-      onAdmitted
+
+    const operation = this.requests.begin(
+      timeoutMs ?? this.registration.requestTimeoutMs,
+      signal,
+      existing
+    );
+    return this.requests.run<readonly Message[]>(
+      operation,
+      (receiver) => {
+        throwIfAborted(signal);
+        router.requestToSpot(
+          target.targetNodeRid,
+          target.spotId,
+          request,
+          timeoutMs ?? this.registration.requestTimeoutMs,
+          onAdmitted,
+          operation,
+          receiver
+        );
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        if (!operation.isPending()) closeMessages(replyParts);
+        return replyParts;
+      },
+      (error) => error
     );
-    return awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
   }
 }

package/src/runtime/channels/spot-route-bridge-transport.ts

@@ -1,3 +1,5 @@
+import { RequestRuntime } from '../foundation/request-runtime';
+import type { PendingOperation, OperationObserver } from '../foundation/operation-registry';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendSpotRouteBridge } from '../backend/contracts';
 import { ZLinkConfigurationException } from '../configuration';
@@ -8,12 +10,12 @@ import {
   type ZLinkChannelEnvelopeCodecRegistry
 } from './channel-envelope';
 import { appendParts } from './channel-multipart';
-import { awaitWithAbort } from '../abort';
 
 export class ZLinkSpotRouteBridgeTransport {
   constructor(
     private readonly bridges: ReadonlyMap<string, ZLinkBackendSpotRouteBridge>,
-    private readonly defaultRequestTimeoutMs: number | undefined
+    private readonly defaultRequestTimeoutMs: number | undefined,
+    private readonly requests = new RequestRuntime()
   ) {}
 
   has(routerChannelId: string): boolean {
@@ -32,50 +34,80 @@ export class ZLinkSpotRouteBridgeTransport {
     }
   }
 
-  async request<TReply>(
+  request<TReply>(
     target: ZLinkSpotRouteTarget,
     parts: readonly Message[],
     codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>,
+    destination?: OperationObserver<unknown, unknown>
   ): Promise<TReply> {
-    const bridge = this.requireBridge(target.routerChannelId);
-    const operation = appendParts(
-      bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId),
-      parts
-    )
-      .timeout(timeoutMs ?? 0)
-      .submit(onAdmitted);
-    const replyParts = await awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
     try {
-      return decodeChannelReply<TReply>(replyParts, codecs);
-    } finally {
-      closeMessages(replyParts);
-      closeMessages(parts);
+      const operation = this.requests.begin(
+        timeoutMs ?? this.defaultRequestTimeoutMs,
+        signal,
+        existing
+      );
+      return this.requests.run<TReply>(
+        operation,
+        (receiver) => {
+          const bridge = this.requireBridge(target.routerChannelId);
+          appendParts(
+            bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId),
+            parts
+          )
+            .timeout(timeoutMs ?? this.defaultRequestTimeoutMs ?? 0)
+            .submit(onAdmitted, operation, receiver);
+        },
+        (value) => {
+          const replyParts = value as readonly Message[];
+          try {
+            return decodeChannelReply<TReply>(replyParts, codecs);
+          } finally {
+            closeMessages(replyParts);
+            closeMessages(parts);
+          }
+        },
+        (error) => error,
+        destination
+      );
+    } catch (error) {
+      return Promise.reject(error);
     }
   }
-
   requestRaw(
     target: ZLinkSpotRouteTarget,
     request: Message,
     timeoutMs: number | undefined,
     signal?: AbortSignal,
-    onAdmitted?: () => void
+    onAdmitted?: () => void,
+    existing?: PendingOperation<unknown>
   ): Promise<readonly Message[]> {
-    const bridge = this.requireBridge(target.routerChannelId);
-    const operation = bridge
-      .request(target.routerChannelId, target.targetNodeRid, target.spotId)
-      .message(request)
-      .timeout(timeoutMs ?? this.defaultRequestTimeoutMs ?? 0)
-      .submit(onAdmitted);
-    return awaitWithAbort(operation, signal, () => {
-      void operation.then(closeMessages, () => undefined);
-    });
+    const operation = this.requests.begin(
+      timeoutMs ?? this.defaultRequestTimeoutMs,
+      signal,
+      existing
+    );
+    return this.requests.run<readonly Message[]>(
+      operation,
+      (receiver) => {
+        const bridge = this.requireBridge(target.routerChannelId);
+        appendParts(bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId), [
+          request
+        ])
+          .timeout(timeoutMs ?? this.defaultRequestTimeoutMs ?? 0)
+          .submit(onAdmitted, operation, receiver);
+      },
+      (value) => {
+        const replyParts = value as readonly Message[];
+        if (!operation.isPending()) closeMessages(replyParts);
+        return replyParts;
+      },
+      (error) => error
+    );
   }
-
   private requireBridge(routerChannelId: string): ZLinkBackendSpotRouteBridge {
     const bridge = this.bridges.get(routerChannelId);
     if (bridge === undefined)