@zlink-systems/framework 0.26.0 → 0.28.0

package/dist/runtime/channels/channel-outbound-operations.js

@@ -2,7 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkChannelOutboundOperations = void 0;
 exports.keepChannelRequestAlive = keepChannelRequestAlive;
+exports.requestTerminalResult = requestTerminalResult;
+exports.isRemoteChannelErrorReply = isRemoteChannelErrorReply;
 const framework_errors_internal_1 = require("../framework-errors-internal");
+const request_deadline_1 = require("../messaging/request-deadline");
 const runtime_values_1 = require("../backend/runtime-values");
 const submission_result_1 = require("../messaging/submission-result");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
@@ -30,16 +33,15 @@ class ZLinkChannelOutboundOperations {
     pendingRequestCount(channelName) {
         return this.pendingRequests.get(channelName) ?? 0;
     }
-    send(channelName, packetName, message, signal, metadata = EMPTY_OUTBOUND_METADATA) {
+    send(channelName, packetName, message, metadata = EMPTY_OUTBOUND_METADATA) {
         // Call-scoped flow (spec 27 §4): the envelope encoder and the trace
         // points below share one ambient flow that does not outlive this call.
-        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.sendScoped(channelName, packetName, message, signal, metadata));
+        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.sendScoped(channelName, packetName, message, metadata));
     }
-    async sendScoped(channelName, packetName, message, signal, metadata = EMPTY_OUTBOUND_METADATA) {
-        (0, abort_1.throwIfAborted)(signal);
-        const dealer = await this.sockets.awaitClientDealerForOutbound(channelName, signal);
+    async sendScoped(channelName, packetName, message, metadata = EMPTY_OUTBOUND_METADATA) {
+        const dealer = await this.sockets.awaitClientDealerForOutbound(channelName);
         if (dealer === undefined) {
-            return { status: submission_result_1.ZLinkSubmitStatus.RouteNotConnected };
+            return { status: submission_result_1.ZLinkSubmitStatus.Shutdown };
         }
         const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(3 /* ZLinkChannelMessageKind.Command */, channelName, packetName, message, undefined, undefined, this.codecs, undefined, this.dispatchServices.flowCreationEnabled(), metadata);
         try {
@@ -47,17 +49,8 @@ class ZLinkChannelOutboundOperations {
         }
         catch (error) {
             (0, channel_envelope_1.closeMessages)(parts);
-            if (isSubmitDeadline(error)) {
-                this.dispatchServices.beginOutbound(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured)?.trace({
-                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Channel,
-                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
-                    channelName,
-                    channelRouteKind: 'client_server',
-                    packetName,
-                    correlationId: undefined,
-                    result: 'backpressured'
-                });
-                return { status: submission_result_1.ZLinkSubmitStatus.TimedOut };
+            if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'submit') {
+                return (0, submission_result_1.classifySubmitResult)(error.result, 'One-way send', error.phase);
             }
             throw error;
         }
@@ -79,7 +72,8 @@ class ZLinkChannelOutboundOperations {
         return keepChannelRequestAlive((0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.requestScoped(channelName, packetName, request, timeoutMs, signal, metadata)));
     }
     async requestScoped(channelName, packetName, request, timeoutMs, signal, metadata) {
-        const deadlineAtMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
+        const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
+        const deadlineUnixMs = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
         let correlationId;
         let selectedServerRid;
         let terminalRecorded = false;
@@ -100,16 +94,16 @@ class ZLinkChannelOutboundOperations {
         };
         try {
             (0, abort_1.throwIfAborted)(signal);
-            const dealer = await this.sockets.awaitClientDealerForOutbound(channelName, signal, deadlineAtMs);
-            // Binding timeouts are whole milliseconds; rounding down keeps the call's deadline.
-            const remainingMs = deadlineAtMs === undefined ? undefined : Math.floor(deadlineAtMs - performance.now());
-            if (dealer === undefined || (remainingMs !== undefined && remainingMs <= 0)) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Channel '${channelName}' has no ready ClientServer server.`);
+            const readyWait = new AbortController();
+            const readySignal = signal === undefined ? readyWait.signal : AbortSignal.any([signal, readyWait.signal]);
+            const dealer = await (0, request_deadline_1.waitRequestReply)(this.sockets.awaitClientDealerForOutbound(channelName, readySignal), `Channel request '${channelName}'`, deadlineMs, signal, () => readyWait.abort());
+            if (dealer === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Channel '${channelName}' has no ready ClientServer server before its admission deadline.`);
             }
             const serverRid = this.sockets.selectedClientServerRid(channelName, dealer);
             selectedServerRid = serverRid;
             correlationId = (0, channel_envelope_1.newChannelCorrelationId)();
-            const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(1 /* ZLinkChannelMessageKind.Request */, channelName, packetName, request, remainingMs, undefined, this.codecs, correlationId, this.dispatchServices.flowCreationEnabled(), metadata);
+            const parts = (0, channel_envelope_1.encodeChannelEnvelopePartsAtDeadline)(1 /* ZLinkChannelMessageKind.Request */, channelName, packetName, request, deadlineUnixMs, undefined, this.codecs, correlationId, this.dispatchServices.flowCreationEnabled(), metadata);
             this.dispatchServices.beginOutbound(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent)?.trace({
                 surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Channel,
                 messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
@@ -123,7 +117,7 @@ class ZLinkChannelOutboundOperations {
                 let replyParts = [];
                 try {
                     try {
-                        replyParts = await (0, abort_1.awaitWithAbort)(dealer.request(parts, remainingMs), signal);
+                        replyParts = await (0, abort_1.awaitWithAbort)(dealer.request(parts, (0, request_deadline_1.remainingRequestTimeout)(`Channel request '${channelName}'`, deadlineMs)), signal);
                     }
                     catch (error) {
                         if (signal?.aborted === true)
@@ -134,7 +128,7 @@ class ZLinkChannelOutboundOperations {
                         if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'request') {
                             throw new contracts_1.ZLinkFrameworkException((0, framework_errors_internal_1.requestResultToPublicErrorKind)(error.result), `Channel '${channelName}' request failed with result ${error.result}.`, error);
                         }
-                        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Channel '${channelName}' request failed before a reply was received.`, true, error);
+                        throw error;
                     }
                     return (0, channel_envelope_1.decodeChannelReply)(replyParts, this.codecs);
                 }
@@ -183,29 +177,18 @@ class ZLinkChannelOutboundOperations {
         publisher.publish(topic, parts);
         return publishResult(submission_result_1.ZLinkSubmitStatus.Submitted);
     }
-    routeSubmit(routerChannelId, targetNodeRid, packetName, message, signal, metadata = EMPTY_OUTBOUND_METADATA) {
-        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.routeSubmitScoped(routerChannelId, targetNodeRid, packetName, message, signal, metadata));
+    routeSubmit(routerChannelId, targetNodeRid, packetName, message, metadata = EMPTY_OUTBOUND_METADATA) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.routeSubmitScoped(routerChannelId, targetNodeRid, packetName, message, metadata));
     }
-    async routeSubmitScoped(routerChannelId, targetNodeRid, packetName, message, signal, metadata = EMPTY_OUTBOUND_METADATA) {
-        (0, abort_1.throwIfAborted)(signal);
+    async routeSubmitScoped(routerChannelId, targetNodeRid, packetName, message, metadata = EMPTY_OUTBOUND_METADATA) {
         const router = this.sockets.routeRouter(routerChannelId);
         const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(3 /* ZLinkChannelMessageKind.Command */, routerChannelId, packetName, message, undefined, undefined, (0, channel_framework_packets_1.codecsForFrameworkPacket)(packetName, this.codecs), undefined, this.dispatchServices.flowCreationEnabled(), metadata);
         try {
             await router.send(targetNodeRid, parts);
         }
         catch (error) {
-            if (isSubmitDeadline(error)) {
-                this.dispatchServices.beginOutbound(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured)?.trace({
-                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel,
-                    messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
-                    channelName: routerChannelId,
-                    channelRouteKind: 'route_mesh',
-                    packetName,
-                    correlationId: undefined,
-                    targetRid: targetNodeRid,
-                    result: 'backpressured'
-                });
-                return { status: submission_result_1.ZLinkSubmitStatus.TimedOut };
+            if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'submit') {
+                return (0, submission_result_1.classifySubmitResult)(error.result, 'One-way send', error.phase);
             }
             throw error;
         }

package/dist/runtime/channels/channel-receive-loops.d.ts

@@ -5,6 +5,8 @@ import type { ZLinkMultipartAsyncSubmitOperation } from './channel-multipart';
 import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 import { type ZLinkReceiveTaskErrorReporter } from './channel-receive-task-tracker';
 import { ApplicationJobQueue } from '../host/application-job-queue';
+import { ZLinkSerialExecutionQueue } from '../execution/serial-execution-queue';
+export declare function createChannelApplicationDispatchQueue(): ZLinkSerialExecutionQueue;
 interface ZLinkMultipartOperation<TNext> {
     message(message: MessageLike): TNext;
 }
@@ -84,6 +86,7 @@ export declare class ZLinkChannelReceiveLoop {
     private readonly poller;
     private readonly applicationJobQueue;
     private readonly roundRobin?;
+    private readonly applicationDispatchQueue;
     private stoppedFlag;
     private isStopped;
     private running?;
@@ -93,7 +96,7 @@ export declare class ZLinkChannelReceiveLoop {
     private readonly capacityStop;
     constructor(channelName: string, router: ZLinkBackendRouterSocket & {
         reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
-    }, dispatcher: ZLinkChannelRequestDispatchLoop, spotRouteBridge: ZLinkBackendSpotRouteBridge | undefined, infrastructureHandler: ZLinkChannelInfrastructureHandler | undefined, poller: ZLinkBackendReadablePoller, applicationJobQueue: ApplicationJobQueue, reportError?: ZLinkReceiveTaskErrorReporter, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined);
+    }, dispatcher: ZLinkChannelRequestDispatchLoop, spotRouteBridge: ZLinkBackendSpotRouteBridge | undefined, infrastructureHandler: ZLinkChannelInfrastructureHandler | undefined, poller: ZLinkBackendReadablePoller, applicationJobQueue: ApplicationJobQueue, reportError?: ZLinkReceiveTaskErrorReporter, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined, applicationDispatchQueue?: ZLinkSerialExecutionQueue);
     run(signal?: AbortSignal): Promise<void>;
     private runLoop;
     stop(): Promise<void>;
@@ -108,6 +111,7 @@ export declare class ZLinkSubscriberReceiveLoop {
     private readonly applicationJobQueue;
     private readonly infrastructureHandler?;
     private readonly roundRobin?;
+    private readonly applicationDispatchQueue;
     private stoppedFlag;
     private isStopped;
     private running?;
@@ -115,7 +119,7 @@ export declare class ZLinkSubscriberReceiveLoop {
     private readonly receiveOwner;
     private readonly rawReceiveReservations;
     private readonly capacityStop;
-    constructor(adapter: ZLinkChannelBackendAdapter, subscriber: ZLinkBackendSubscriberSocket, dispatcher: ZLinkChannelPublishDispatchLoop, applicationJobQueue: ApplicationJobQueue, infrastructureHandler?: ((topicMessage: ReturnType<ZLinkChannelBackendAdapter["createTopicMessage"]>) => boolean | ZLinkSubscriberInfrastructureResult) | undefined, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined, reportError?: ZLinkReceiveTaskErrorReporter);
+    constructor(adapter: ZLinkChannelBackendAdapter, subscriber: ZLinkBackendSubscriberSocket, dispatcher: ZLinkChannelPublishDispatchLoop, applicationJobQueue: ApplicationJobQueue, infrastructureHandler?: ((topicMessage: ReturnType<ZLinkChannelBackendAdapter["createTopicMessage"]>) => boolean | ZLinkSubscriberInfrastructureResult) | undefined, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined, reportError?: ZLinkReceiveTaskErrorReporter, applicationDispatchQueue?: ZLinkSerialExecutionQueue);
     private readonly poller;
     run(signal?: AbortSignal): Promise<void>;
     private runLoop;
@@ -130,6 +134,7 @@ export declare class ZLinkRouteReceiveLoop {
     private readonly poller;
     private readonly applicationJobQueue;
     private readonly roundRobin?;
+    private readonly applicationDispatchQueue;
     private stoppedFlag;
     private isStopped;
     private running?;
@@ -139,7 +144,7 @@ export declare class ZLinkRouteReceiveLoop {
     private readonly capacityStop;
     constructor(router: ZLinkBackendRouterSocket & {
         reply(routingId: unknown, replyToken: unknown): ZLinkMultipartReplyOperation;
-    }, dispatcher: ZLinkRoutePacketDispatchLoop, poller: ZLinkBackendReadablePoller, applicationJobQueue: ApplicationJobQueue, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined, reportError?: ZLinkReceiveTaskErrorReporter);
+    }, dispatcher: ZLinkRoutePacketDispatchLoop, poller: ZLinkBackendReadablePoller, applicationJobQueue: ApplicationJobQueue, roundRobin?: ZLinkReceiveRoundRobinCoordinator | undefined, reportError?: ZLinkReceiveTaskErrorReporter, applicationDispatchQueue?: ZLinkSerialExecutionQueue);
     run(signal?: AbortSignal): Promise<void>;
     private runLoop;
     stop(): Promise<void>;

package/dist/runtime/channels/channel-receive-loops.js

@@ -1,10 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkRouteReceiveLoop = exports.ZLinkSubscriberReceiveLoop = exports.ZLinkChannelReceiveLoop = exports.ZLINK_CHANNEL_RAW_RECEIVE_RESERVATION_LIMIT = exports.ZLinkReceiveRoundRobinCoordinator = void 0;
+exports.createChannelApplicationDispatchQueue = createChannelApplicationDispatchQueue;
 const channel_envelope_1 = require("./channel-envelope");
 const channel_envelope_inspection_1 = require("./channel-envelope-inspection");
 const channel_receive_task_tracker_1 = require("./channel-receive-task-tracker");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const serial_execution_queue_1 = require("../execution/serial-execution-queue");
+function createChannelApplicationDispatchQueue() {
+    return new serial_execution_queue_1.ZLinkSerialExecutionQueue(async (record) => {
+        try {
+            record.resolve(await record.operation());
+        }
+        catch (error) {
+            record.reject(error);
+        }
+        finally {
+            record.release();
+        }
+    });
+}
 //  The loop awaits between reads and the signal can abort in that gap. Reading
 //  through a function keeps the later check honest; an inline read stays
 //  narrowed by the loop condition and the comparison is rejected as dead.
@@ -102,6 +117,7 @@ class ZLinkChannelReceiveLoop {
     poller;
     applicationJobQueue;
     roundRobin;
+    applicationDispatchQueue;
     //  The loop awaits between the two reads and stop() can land in that gap.
     //  Reading through a method keeps the second check honest; a field read stays
     //  narrowed to false across the await and is treated as dead code.
@@ -114,7 +130,7 @@ class ZLinkChannelReceiveLoop {
     receiveOwner;
     rawReceiveReservations;
     capacityStop = new AbortController();
-    constructor(channelName, router, dispatcher, spotRouteBridge, infrastructureHandler, poller, applicationJobQueue, reportError, roundRobin) {
+    constructor(channelName, router, dispatcher, spotRouteBridge, infrastructureHandler, poller, applicationJobQueue, reportError, roundRobin, applicationDispatchQueue = createChannelApplicationDispatchQueue()) {
         this.channelName = channelName;
         this.router = router;
         this.dispatcher = dispatcher;
@@ -123,6 +139,7 @@ class ZLinkChannelReceiveLoop {
         this.poller = poller;
         this.applicationJobQueue = applicationJobQueue;
         this.roundRobin = roundRobin;
+        this.applicationDispatchQueue = applicationDispatchQueue;
         this.inFlight = new channel_receive_task_tracker_1.ZLinkReceiveTaskTracker(reportError);
         this.receiveOwner = roundRobin?.register() ?? Symbol('channel-receive-owner');
         this.rawReceiveReservations = new ZLinkRawReceiveReservationPool(exports.ZLINK_CHANNEL_RAW_RECEIVE_RESERVATION_LIMIT);
@@ -218,7 +235,7 @@ class ZLinkChannelReceiveLoop {
                 break;
             }
             applicationJobPermit.markApplicationQueued();
-            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.dispatchAndClose(received, signal, classification.decodedHeader, true));
+            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.applicationDispatchQueue.submitPreAdmitted((0, application_job_queue_scope_1.bindApplicationJobPermit)(() => this.dispatchAndClose(received, signal, classification.decodedHeader, true))));
             releaseRawReceive();
             this.inFlight.track(task);
             if (batch.record(receivedBytes)) {
@@ -292,6 +309,7 @@ class ZLinkSubscriberReceiveLoop {
     applicationJobQueue;
     infrastructureHandler;
     roundRobin;
+    applicationDispatchQueue;
     //  The loop awaits between the two reads and stop() can land in that gap.
     //  Reading through a method keeps the second check honest; a field read stays
     //  narrowed to false across the await and is treated as dead code.
@@ -304,13 +322,14 @@ class ZLinkSubscriberReceiveLoop {
     receiveOwner;
     rawReceiveReservations;
     capacityStop = new AbortController();
-    constructor(adapter, subscriber, dispatcher, applicationJobQueue, infrastructureHandler, roundRobin, reportError) {
+    constructor(adapter, subscriber, dispatcher, applicationJobQueue, infrastructureHandler, roundRobin, reportError, applicationDispatchQueue = createChannelApplicationDispatchQueue()) {
         this.adapter = adapter;
         this.subscriber = subscriber;
         this.dispatcher = dispatcher;
         this.applicationJobQueue = applicationJobQueue;
         this.infrastructureHandler = infrastructureHandler;
         this.roundRobin = roundRobin;
+        this.applicationDispatchQueue = applicationDispatchQueue;
         this.inFlight = new channel_receive_task_tracker_1.ZLinkReceiveTaskTracker(reportError);
         this.poller = adapter.createReadablePoller(subscriber);
         this.receiveOwner = roundRobin?.register() ?? Symbol('subscriber-receive-owner');
@@ -406,7 +425,7 @@ class ZLinkSubscriberReceiveLoop {
                 break;
             }
             applicationJobPermit.markApplicationQueued();
-            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.dispatchAndClose(topicMessage, signal, classification.decodedHeader, true));
+            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.applicationDispatchQueue.submitPreAdmitted((0, application_job_queue_scope_1.bindApplicationJobPermit)(() => this.dispatchAndClose(topicMessage, signal, classification.decodedHeader, true))));
             releaseRawReceive();
             this.inFlight.track(task);
             if (batch.record(receivedBytes)) {
@@ -469,6 +488,7 @@ class ZLinkRouteReceiveLoop {
     poller;
     applicationJobQueue;
     roundRobin;
+    applicationDispatchQueue;
     //  The loop awaits between the two reads and stop() can land in that gap.
     //  Reading through a method keeps the second check honest; a field read stays
     //  narrowed to false across the await and is treated as dead code.
@@ -481,12 +501,13 @@ class ZLinkRouteReceiveLoop {
     receiveOwner;
     rawReceiveReservations;
     capacityStop = new AbortController();
-    constructor(router, dispatcher, poller, applicationJobQueue, roundRobin, reportError) {
+    constructor(router, dispatcher, poller, applicationJobQueue, roundRobin, reportError, applicationDispatchQueue = createChannelApplicationDispatchQueue()) {
         this.router = router;
         this.dispatcher = dispatcher;
         this.poller = poller;
         this.applicationJobQueue = applicationJobQueue;
         this.roundRobin = roundRobin;
+        this.applicationDispatchQueue = applicationDispatchQueue;
         this.inFlight = new channel_receive_task_tracker_1.ZLinkReceiveTaskTracker(reportError);
         this.receiveOwner = roundRobin?.register() ?? Symbol('route-receive-owner');
         this.rawReceiveReservations = new ZLinkRawReceiveReservationPool(exports.ZLINK_CHANNEL_RAW_RECEIVE_RESERVATION_LIMIT);
@@ -596,7 +617,7 @@ class ZLinkRouteReceiveLoop {
                 break;
             }
             applicationJobPermit.markApplicationQueued();
-            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.dispatchAndClose(received, signal, true));
+            const task = (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, () => this.applicationDispatchQueue.submitPreAdmitted((0, application_job_queue_scope_1.bindApplicationJobPermit)(() => this.dispatchAndClose(received, signal, true))));
             releaseRawReceive();
             this.inFlight.track(task);
             if (batch.record(receivedBytes)) {

package/dist/runtime/channels/channel-runtime-lifecycle.d.ts

@@ -33,15 +33,24 @@ export declare class ZLinkChannelRuntimeLifecycle {
     private readonly manualFanoutSubscribers;
     private readonly manualFanoutSubscriberOwners;
     private readonly routeReceiveLoops;
+    private readonly applicationDispatchQueues;
     private readonly meshChannelDispatchers;
     private readonly meshRouteDispatchers;
     private nextManualFanoutIndex;
-    private disposed;
+    private readonly disposal;
     private locationAutoConnect?;
     private clientServerLocation?;
     private fanoutLocation?;
     private taskRunner?;
     constructor(options: ZLinkChannelRuntimeLifecycleOptions);
+    fanoutTopologyTargets(channelName: string): {
+        channelName: string;
+        publisherRoutingId: string;
+        lifecycleGeneration: bigint;
+        descriptorRevision: bigint;
+        advertisedEndpoint: string;
+        state: "error" | "preparing" | "serving" | "retiring" | "stopped";
+    }[] | undefined;
     configureLocationAutoConnect(runtime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, events?: ZLinkLocationEventSink): void;
     private beginLocationAutoConnectCore;
     private beginFanoutLocationAutoConnectCore;
@@ -56,7 +65,9 @@ export declare class ZLinkChannelRuntimeLifecycle {
     dispatchLocalMeshRoute(meshName: string, sourceNodeRid: RoutingId, parts: readonly Message[], signal?: AbortSignal): Promise<void>;
     canDispatchLocalMeshRoute(meshName: string): boolean;
     dispose(signal?: AbortSignal): Promise<void>;
+    private disposeCore;
     private beginDisposeCore;
+    private applicationDispatchQueue;
     private openOutboundSockets;
     private startChannelReceivers;
     private startSubscriberReceivers;

package/dist/runtime/channels/channel-runtime-lifecycle.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkChannelRuntimeLifecycle = void 0;
+const disposal_1 = require("../disposal");
 const configuration_1 = require("../configuration");
 const contracts_1 = require("../backend/contracts");
 const channel_autoconnect_1 = require("./channel-autoconnect");
@@ -21,10 +22,11 @@ class ZLinkChannelRuntimeLifecycle {
     manualFanoutSubscribers = new Map();
     manualFanoutSubscriberOwners = new Set();
     routeReceiveLoops = [];
+    applicationDispatchQueues = new Map();
     meshChannelDispatchers = new Map();
     meshRouteDispatchers = new Map();
     nextManualFanoutIndex = 0;
-    disposed = false;
+    disposal = new disposal_1.RuntimeDisposal();
     locationAutoConnect;
     clientServerLocation;
     fanoutLocation;
@@ -32,6 +34,9 @@ class ZLinkChannelRuntimeLifecycle {
     constructor(options) {
         this.options = options;
     }
+    fanoutTopologyTargets(channelName) {
+        return this.fanoutLocation?.topologyTargets(channelName);
+    }
     configureLocationAutoConnect(runtime, stores, options, events) {
         this.locationAutoConnect = (0, channel_autoconnect_1.createChannelLocationAutoConnectContext)(runtime, stores, options, events);
     }
@@ -201,7 +206,10 @@ class ZLinkChannelRuntimeLifecycle {
     canDispatchLocalMeshRoute(meshName) {
         return this.meshRouteDispatchers.has(meshName);
     }
-    async dispose(signal) {
+    dispose(signal) {
+        return this.disposal.run(() => this.disposeCore(signal));
+    }
+    async disposeCore(signal) {
         const work = await this.lane.run(() => this.beginDisposeCore());
         const transportStopped = await startOutsideStateLane(() => Promise.allSettled([
             ...work.channelLoops.map((loop) => loop.stop()),
@@ -209,6 +217,7 @@ class ZLinkChannelRuntimeLifecycle {
             ...work.routeLoops.map((loop) => loop.stop()),
             ...work.manualTransitions
         ]));
+        const applicationStopped = await startOutsideStateLane(() => Promise.allSettled(work.applicationDispatchQueues.map((queue) => queue.close())));
         const descriptorStopped = work.clientServerLocation === undefined
             ? []
             : await startOutsideStateLane(() => Promise.allSettled([work.clientServerLocation?.stop(signal)]));
@@ -221,6 +230,7 @@ class ZLinkChannelRuntimeLifecycle {
         ]));
         const errors = [
             ...transportStopped,
+            ...applicationStopped,
             ...descriptorStopped,
             ...fanoutDescriptorStopped,
             ...cleanup
@@ -231,46 +241,58 @@ class ZLinkChannelRuntimeLifecycle {
             throw errors[0];
         if (errors.length > 1)
             throw new AggregateError(errors, 'Channel runtime cleanup failed.');
+        await this.lane.run(() => {
+            this.manualFanoutSubscriberOwners.clear();
+            this.manualFanoutSubscribers.clear();
+            this.channelReceiveLoops.length = 0;
+            this.subscriberReceiveLoops.length = 0;
+            this.routeReceiveLoops.length = 0;
+            this.applicationDispatchQueues.clear();
+            this.clientServerLocation = undefined;
+            this.fanoutLocation = undefined;
+            this.taskRunner = undefined;
+            this.meshChannelDispatchers.clear();
+            this.meshRouteDispatchers.clear();
+            this.options.spotRouteBridges.clear();
+        });
     }
     beginDisposeCore() {
         const channelLoops = [...this.channelReceiveLoops];
         const manualStates = [...this.manualFanoutSubscribers.values()];
-        this.disposed = true;
         for (const state of manualStates)
             state.desired = false;
         for (const owner of this.manualFanoutSubscriberOwners) {
             (0, RuntimeEndpointConnections_1.detachEndpointConnections)(owner);
         }
-        this.manualFanoutSubscriberOwners.clear();
-        this.manualFanoutSubscribers.clear();
         const manualLoops = new Set(manualStates
             .map((state) => state.active?.loop ?? state.stopping?.loop)
             .filter((loop) => loop !== undefined));
         const subscriberLoops = [...this.subscriberReceiveLoops].filter((loop) => !manualLoops.has(loop));
         const manualTransitions = manualStates.map((state) => this.drainManualFanoutSubscriberCore(state));
         const routeLoops = [...this.routeReceiveLoops];
+        const applicationDispatchQueues = [...this.applicationDispatchQueues.values()];
         const clientServerLocation = this.clientServerLocation;
         const fanoutLocation = this.fanoutLocation;
         const spotRouteBridges = [...this.options.spotRouteBridges.values()];
-        this.channelReceiveLoops.length = 0;
-        this.subscriberReceiveLoops.length = 0;
-        this.routeReceiveLoops.length = 0;
-        this.clientServerLocation = undefined;
-        this.fanoutLocation = undefined;
-        this.taskRunner = undefined;
-        this.meshChannelDispatchers.clear();
-        this.meshRouteDispatchers.clear();
-        this.options.spotRouteBridges.clear();
         return {
             channelLoops,
             subscriberLoops,
             manualTransitions,
             routeLoops,
+            applicationDispatchQueues,
             clientServerLocation,
             fanoutLocation,
             spotRouteBridges
         };
     }
+    applicationDispatchQueue(channelName) {
+        let queue = this.applicationDispatchQueues.get(channelName);
+        if (queue === undefined) {
+            queue = (0, channel_receive_loops_1.createChannelApplicationDispatchQueue)();
+            this.applicationDispatchQueues.set(channelName, queue);
+        }
+        return queue;
+    }
     openOutboundSockets() {
         // The process-local Server is an independent peer source. Location Store
         // discovery may later alias the same admitted identity, but startup and
@@ -310,7 +332,7 @@ class ZLinkChannelRuntimeLifecycle {
                 unhandled: this.options.registration.dispatch?.unhandled
             });
             const spotRouteBridge = this.createSpotRouteBridgeForRouter(channelName, router);
-            const loop = new channel_receive_loops_1.ZLinkChannelReceiveLoop(channelName, router, dispatcher, spotRouteBridge, (received, socket) => this.options.sockets.tryHandleClientServerControl(channelName, received, socket), this.options.adapter.createReadablePoller(router), this.options.applicationJobQueue, (error) => taskRunner.errorSink.reportRuntimeTaskException(`channel:${channelName}:dispatch`, error), this.receiveRoundRobin);
+            const loop = new channel_receive_loops_1.ZLinkChannelReceiveLoop(channelName, router, dispatcher, spotRouteBridge, (received, socket) => this.options.sockets.tryHandleClientServerControl(channelName, received, socket), this.options.adapter.createReadablePoller(router), this.options.applicationJobQueue, (error) => taskRunner.errorSink.reportRuntimeTaskException(`channel:${channelName}:dispatch`, error), this.receiveRoundRobin, this.applicationDispatchQueue(channelName));
             this.channelReceiveLoops.push(loop);
             tasks.push(taskRunner.run(`channel:${channelName}`, (signal) => loop.run(signal)));
         }
@@ -369,7 +391,7 @@ class ZLinkChannelRuntimeLifecycle {
         return state;
     }
     requestManualFanoutConnect(channelName, endpoint, taskRunner, dispatcher) {
-        if (this.disposed)
+        if (this.disposal.started)
             return;
         const state = this.getOrCreateManualFanoutSubscriber(channelName, endpoint, this.nextManualFanoutIndex++, taskRunner, dispatcher);
         state.desired = true;
@@ -403,7 +425,7 @@ class ZLinkChannelRuntimeLifecycle {
     }
     openManualFanoutSubscriber(state) {
         const { channelName, endpoint, connectionId, taskRunner, dispatcher } = state;
-        if (this.disposed || !state.desired || this.taskRunner !== taskRunner) {
+        if (this.disposal.started || !state.desired || this.taskRunner !== taskRunner) {
             return Promise.resolve();
         }
         const token = Symbol(`manual-fanout:${channelName}:${endpoint}`);
@@ -414,20 +436,20 @@ class ZLinkChannelRuntimeLifecycle {
             const subscriber = this.options.sockets.openFanoutSubscriberConnection(channelName, connectionId, endpoint, {
                 onReady() { },
                 onTerminated: () => {
-                    if (this.disposed ||
+                    if (this.disposal.started ||
                         (state.active?.token !== token && state.openingToken !== token) ||
                         reconnecting)
                         return;
                     reconnecting = true;
                     setImmediate(() => {
-                        if (this.disposed ||
+                        if (this.disposal.started ||
                             (state.active?.token !== token && state.openingToken !== token)) {
                             reconnecting = false;
                             return;
                         }
                         this.enqueueManualFanoutTransition(state, async () => {
                             reconnecting = false;
-                            if (this.disposed || state.active?.token !== token)
+                            if (this.disposal.started || state.active?.token !== token)
                                 return;
                             try {
                                 await this.closeManualFanoutSubscriber(state, token);
@@ -442,7 +464,7 @@ class ZLinkChannelRuntimeLifecycle {
                     });
                 }
             });
-            loop = new channel_receive_loops_1.ZLinkSubscriberReceiveLoop(this.options.adapter, subscriber, dispatcher, this.options.applicationJobQueue, (message) => this.options.sockets.handleFanoutInboundResult(connectionId, message, subscriber), this.receiveRoundRobin, (error) => taskRunner.errorSink.reportRuntimeTaskException(`subscriber:${state.channelName}:manual:${state.index}:dispatch`, error));
+            loop = new channel_receive_loops_1.ZLinkSubscriberReceiveLoop(this.options.adapter, subscriber, dispatcher, this.options.applicationJobQueue, (message) => this.options.sockets.handleFanoutInboundResult(connectionId, message, subscriber), this.receiveRoundRobin, (error) => taskRunner.errorSink.reportRuntimeTaskException(`subscriber:${state.channelName}:manual:${state.index}:dispatch`, error), this.applicationDispatchQueue(channelName));
             state.openingToken = undefined;
             state.active = { token, loop };
             this.subscriberReceiveLoops.push(loop);
@@ -471,9 +493,6 @@ class ZLinkChannelRuntimeLifecycle {
         catch (error) {
             errors.push(error);
         }
-        finally {
-            await this.lane.run(() => this.finishCloseManualFanoutSubscriberCore(state, active));
-        }
         try {
             await startOutsideStateLane(() => this.options.sockets.closeFanoutSubscriberConnection(state.connectionId));
         }
@@ -485,12 +504,13 @@ class ZLinkChannelRuntimeLifecycle {
         if (errors.length > 1) {
             throw new AggregateError(errors, `Fanout subscriber '${state.connectionId}' cleanup failed.`);
         }
+        await this.lane.run(() => this.finishCloseManualFanoutSubscriberCore(state, active));
     }
     shouldReconnectManualFanoutSubscriber(state) {
-        return !this.disposed && state.desired;
+        return !this.disposal.started && state.desired;
     }
     beginCloseManualFanoutSubscriberCore(state, expectedToken) {
-        const active = state.active;
+        const active = state.active ?? state.stopping;
         if (active === undefined || (expectedToken !== undefined && active.token !== expectedToken)) {
             return undefined;
         }
@@ -521,7 +541,7 @@ class ZLinkChannelRuntimeLifecycle {
             unhandled: this.options.registration.dispatch?.unhandled,
             metrics: this.options.dispatchServices.metrics()
         });
-        const loop = new channel_receive_loops_1.ZLinkSubscriberReceiveLoop(this.options.adapter, subscriber, dispatcher, this.options.applicationJobQueue, (message) => this.options.sockets.handleFanoutInboundResult(connectionId, message, subscriber), undefined, (error) => taskRunner.errorSink.reportRuntimeTaskException(`subscriber:${channelName}:automatic:${connectionId}:dispatch`, error));
+        const loop = new channel_receive_loops_1.ZLinkSubscriberReceiveLoop(this.options.adapter, subscriber, dispatcher, this.options.applicationJobQueue, (message) => this.options.sockets.handleFanoutInboundResult(connectionId, message, subscriber), undefined, (error) => taskRunner.errorSink.reportRuntimeTaskException(`subscriber:${channelName}:automatic:${connectionId}:dispatch`, error), this.applicationDispatchQueue(channelName));
         this.subscriberReceiveLoops.push(loop);
         void taskRunner.run(`subscriber:${channelName}:automatic:${connectionId}`, (signal) => loop.run(signal));
         return async () => {
@@ -567,7 +587,7 @@ class ZLinkChannelRuntimeLifecycle {
                 unhandled: this.options.registration.dispatch?.unhandled,
                 spotRouteBridge
             });
-            const loop = new channel_receive_loops_1.ZLinkRouteReceiveLoop(router, dispatcher, this.options.adapter.createReadablePoller(router), this.options.applicationJobQueue, this.receiveRoundRobin, (error) => taskRunner.errorSink.reportRuntimeTaskException(`route:${routeChannel.routerChannelId}:dispatch`, error));
+            const loop = new channel_receive_loops_1.ZLinkRouteReceiveLoop(router, dispatcher, this.options.adapter.createReadablePoller(router), this.options.applicationJobQueue, this.receiveRoundRobin, (error) => taskRunner.errorSink.reportRuntimeTaskException(`route:${routeChannel.routerChannelId}:dispatch`, error), this.applicationDispatchQueue(routeChannel.routerChannelId));
             this.routeReceiveLoops.push(loop);
             tasks.push(taskRunner.run(`route:${routeChannel.routerChannelId}`, (signal) => loop.run(signal)));
         }

package/dist/runtime/channels/channel-runtime-manager.d.ts

@@ -44,16 +44,16 @@ export declare class ZLinkChannelRuntimeManager {
     dispatchMeshRoute(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
     dispatchLocalMeshRoute(meshName: string, sourceNodeRid: RoutingId, parts: readonly Message[], signal?: AbortSignal): Promise<void>;
     canDispatchLocalMeshRoute(meshName: string): boolean;
-    send(channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    send(channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
     tryPublish(channelName: string, topic: string, packetName: string | undefined, event: unknown, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
     publish(channelName: string, topic: string, packetName: string | undefined, event: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
-    routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
-    routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<void>;
     routeRequestToSpot<TReply>(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
     routeRequestFromSpotToSpot<TReply>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply>;
-    routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<void>;
     routeRequestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
     routeRequestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
     canRouteChannel(routerChannelId: string): boolean;