@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -1,3 +1,4 @@
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { RoutingId } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -27,11 +28,6 @@ export declare class ZLinkChannelRuntimeManager {
     fanoutTopology(channelName: string): {
         descriptors: readonly import("../foundation").FanoutPublisherDescriptor[];
     };
-    getFanoutListenerStatus(channelName: string): {
-        channelName: string;
-        endpoint: string;
-        observedAt: Date;
-    };
     observeClientServerTopology(channelName: string, changed: () => void): () => void;
     observeFanoutTopology(channelName: string, changed: () => void): () => void;
     configureLocationAutoConnect(runtime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, events?: ZLinkLocationEventSink): void;
@@ -65,6 +61,7 @@ export declare class ZLinkChannelRuntimeManager {
     dispose(signal?: AbortSignal): Promise<void>;
 }
 export interface ZLinkChannelRuntimeManagerOptions {
+    readonly listenerRecords?: ZLinkListenerRecords;
     readonly internalRouteSendHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeSendHandler>;
     readonly internalRouteRequestHandlers?: ReadonlyMap<string, ZLinkRouteRuntimeRequestHandler>;
     readonly monitoringAdapter?: ZLinkMonitoringBackendAdapter;

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

@@ -18,7 +18,7 @@ class ZLinkChannelRuntimeManager {
         this.registration = registration;
         const applicationJobQueue = options.applicationJobQueue ??
             new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)());
-        this.sockets = new channel_socket_registry_1.ZLinkChannelSocketRegistry(registration, adapter, context, options.monitoringAdapter, options.oneWayFailureSink, applicationJobQueue);
+        this.sockets = new channel_socket_registry_1.ZLinkChannelSocketRegistry(registration, adapter, context, options.monitoringAdapter, options.oneWayFailureSink, applicationJobQueue, options.listenerRecords);
         const codecs = {
             serializers: registration.messageSerializers
         };
@@ -63,22 +63,14 @@ class ZLinkChannelRuntimeManager {
         };
     }
     fanoutTopology(channelName) {
-        return { descriptors: this.sockets.fanoutActiveTargets(channelName) };
-    }
-    getFanoutListenerStatus(channelName) {
-        const endpoint = this.sockets.fanoutPublisherEndpoint(channelName);
-        if (endpoint === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Fanout publisher '${channelName}' has not reported a bound listener.`);
-        }
         return {
-            channelName,
-            endpoint,
-            observedAt: new Date()
+            descriptors: this.lifecycle.fanoutTopologyTargets(channelName) ??
+                this.sockets.fanoutActiveTargets(channelName)
         };
     }
     observeClientServerTopology(channelName, changed) {
         const monitor = this.sockets.clientServerMonitoringSource(channelName);
-        monitor.onEvent(changed);
+        monitor.onChange(changed);
         return () => {
             void monitor.dispose();
         };

package/dist/runtime/channels/channel-socket-options.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkChannelRuntimeOptions = void 0;
+const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const configuration_1 = require("../configuration");
 const SendTimeoutValidation_1 = require("../../contracts/Configuration/SendTimeoutValidation");
 class ZLinkLiveSocketConfig {
@@ -112,8 +113,8 @@ function requireChannelName(channelName) {
     }
 }
 function validatePublicWeight(value) {
-    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
-        throw new configuration_1.ZLinkConfigurationException('Weight must be an integer in 0..10000.');
+    if (!(0, RegistrationBuilderPolicy_1.isValidPublicWeight)(value)) {
+        throw new configuration_1.ZLinkConfigurationException(`Weight must be an integer in 0..${RegistrationBuilderPolicy_1.ZLINK_MAX_PUBLIC_WEIGHT}.`);
     }
 }
 function validateHighWaterMark(value, label) {

package/dist/runtime/channels/channel-socket-registry.d.ts

@@ -1,10 +1,11 @@
 import { type ZLinkClientServerServerDescriptor, type ZLinkFanoutPublisherDescriptor } from '../../contracts';
-import { type ZLinkFrameworkRegistration } from '../configuration';
-import type { ZLinkBackendContext, ZLinkBackendDealerSocket, ZLinkBackendPublisherSocket, ZLinkBackendRouterSocket, ZLinkBackendSocketMonitor, ZLinkBackendSubscriberSocket, ZLinkChannelBackendAdapter, ZLinkMonitoringBackendAdapter } from '../backend/contracts';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendContext, ZLinkBackendDealerSocket, ZLinkBackendPublisherSocket, ZLinkBackendRouterSocket, ZLinkBackendSocketMonitor, ZLinkBackendSubscriberSocket, ZLinkChannelBackendAdapter, ZLinkMonitoringBackendAdapter } from '../backend/contracts';
+import { type ZLinkFrameworkRegistration } from '../configuration';
+import { ZLinkListenerRecords } from '../foundation/listener-records';
 import { ServiceDiscoveryRegistry } from '../foundation/service-discovery-registry';
-import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 import type { ApplicationJobQueue } from '../host/application-job-queue';
+import type { ZLinkChannelEnvelopeHeader } from './channel-envelope';
 export interface ZLinkClientServerServerSocketIdentity {
     readonly serverRid: string;
     readonly lifecycleGeneration: bigint;
@@ -40,7 +41,8 @@ export declare class ZLinkChannelSocketRegistry {
     private readonly routeMeshPublicWeights;
     private readonly clientServerAdmittedClients;
     private readonly clientServerServerPeers;
-    private readonly ownedMonitors;
+    private readonly disposal;
+    private readonly ownedResources;
     private readonly fanoutConnections;
     private readonly fanoutPublisherNextBeacon;
     private clientServerLivenessTimer?;
@@ -48,11 +50,15 @@ export declare class ZLinkChannelSocketRegistry {
     private readonly clientServerMonitorHandlers;
     private readonly fanoutMonitorHandlers;
     private readonly fanoutTopologyHandlers;
-    constructor(registration: ZLinkFrameworkRegistration, adapter: ZLinkChannelBackendAdapter, context: ZLinkBackendContext, monitoringAdapter?: ZLinkMonitoringBackendAdapter | undefined, oneWayFailureSink?: ((error: unknown) => void) | undefined, applicationJobQueue?: ApplicationJobQueue | undefined);
+    private readonly listenerRecords;
+    constructor(registration: ZLinkFrameworkRegistration, adapter: ZLinkChannelBackendAdapter, context: ZLinkBackendContext, monitoringAdapter?: ZLinkMonitoringBackendAdapter | undefined, oneWayFailureSink?: ((error: unknown) => void) | undefined, applicationJobQueue?: ApplicationJobQueue | undefined, listenerRecords?: ZLinkListenerRecords);
     dispose(): Promise<void>;
+    private disposeCore;
     clientDealer(channelName: string): ZLinkBackendDealerSocket;
     channelRouter(channelName: string): ZLinkBackendRouterSocket;
     clientServerServerIdentity(channelName: string): ZLinkClientServerServerSocketIdentity;
+    fanoutPublisherEndpoint(channelName: string): string | undefined;
+    private recordListener;
     clientServerServerSocket(channelName: string): ZLinkBackendRouterSocket;
     clientServerServerWeight(channelName: string): number;
     setClientServerServerWeight(channelName: string, weight: number): void;
@@ -64,37 +70,19 @@ export declare class ZLinkChannelSocketRegistry {
     selectClientServerDealer(channelName: string): ZLinkBackendDealerSocket | undefined;
     clientDealerForOutbound(channelName: string): ZLinkBackendDealerSocket | undefined;
     selectedClientServerRid(channelName: string, dealer: ZLinkBackendDealerSocket): string | undefined;
-    /**
-     * Resolves a ClientServer send target, waiting when the ready candidate set is still empty, as
-     * `framework/doc/framework/common/spec/server/02-channel-transport/02-channel-messaging.ko.md` §3.2 requires: the call waits
-     * at call time for a bounded period and then fails with no-target. The bound is the shorter of
-     * the call's remaining deadline and five seconds, mirroring the .NET reference
-     * `ZLinkClientServerClientRuntime.WaitForReadyAsync`. The wait lives here because this registry
-     * owns ClientServer connections, admission and weighted selection. Sends have no per-call
-     * timeout, so they use the Channel's request timeout.
-     *
-     * The wait only observes admission that is already in flight: it never opens or reconnects a
-     * connection, so it cannot trigger the admission it waits for, and Framework startup keeps not
-     * waiting for local ClientServer admission. It applies whenever nothing is selectable, including
-     * candidate sets excluded by weight 0 or drain, because `selectClientServerDealer` filters the
-     * same way the reference `SelectReady()` does.
-     *
-     * Every attempt yields to the event loop between polls. ClientServer admission completes on the
-     * monitor drains that the backend poll timer pumps, so a synchronous wait would starve the
-     * admission it is waiting for and burn the whole bound before failing anyway. That is this
-     * execution model's form of the hazard the JVM mirror avoids by not holding the admission
-     * monitor across its sleep.
-     */
-    awaitClientDealerForOutbound(channelName: string, signal?: AbortSignal, deadlineAtMs?: number): Promise<ZLinkBackendDealerSocket | undefined>;
+    /** Observes discovery changes until the client DEALER admission deadline. */
+    awaitClientDealerForOutbound(channelName: string, signal?: AbortSignal): Promise<ZLinkBackendDealerSocket | undefined>;
     startManualClientServerConnections(): void;
     startLocalClientServerConnections(): void;
-    clientServerMonitoringSource(channelName: string): ZLinkBackendSocketMonitor;
+    clientServerMonitoringSource(channelName: string): ZLinkBackendSocketMonitor & {
+        onChange(handler: () => void): void;
+    };
     clientServerActiveTargets(channelName: string): readonly Pick<ClientServerDiscoveryDescriptor, 'serverRoutingId' | 'weight' | 'state'>[];
-    hasKnownClientServerTargets(channelName: string): boolean;
     fanoutActiveTargets(channelName: string): readonly import("../foundation/service-discovery-registry").FanoutPublisherDescriptor[];
     admitFanoutPublisher(descriptor: ZLinkFanoutPublisherDescriptor, connectionId: string): boolean;
     removeFanoutPublisher(descriptor: ZLinkFanoutPublisherDescriptor, connectionId: string): boolean;
     setClientServerServerDescriptor(descriptor: ZLinkClientServerServerDescriptor | undefined, channelName: string): void;
+    private notifyClientServerTopology;
     tryHandleClientServerControl(channelName: string, received: {
         readonly parts: readonly Message[];
         readonly replyToken: unknown | null;
@@ -124,13 +112,24 @@ export declare class ZLinkChannelSocketRegistry {
         onChange(handler: () => void): void;
         dispose(): Promise<void>;
     };
-    private notifyFanoutTopology;
+    notifyFanoutTopology(channelName: string): void;
     private tickFanoutLiveness;
     private openManualClientServerConnection;
     private openConfiguredClientServerConnection;
     private admitConfiguredClientServerConnection;
     private drainClientServerControl;
-    private requestClientServerEndpointTermination;
+    /**
+     * Ends the current logical admission of this connection: later replies of
+     * the fenced attempt no longer apply and its ready target is withdrawn.
+     */
+    private endClientServerAdmission;
+    /**
+     * A peer deadline or an invalid pushed control ends only the current logical
+     * admission. The connect intent stays with Core, which owns the endpoint
+     * reconnect (transport liveness §6); the service handshake starts again on
+     * the existing admission path.
+     */
+    private restartClientServerAdmission;
     private applyClientServerDescriptorUpdate;
     private ensureClientServerLivenessTimer;
     private drainSocketMonitors;
@@ -143,7 +142,6 @@ export declare class ZLinkChannelSocketRegistry {
     private pushClientServerDescriptorUpdate;
     private allocateClientServerProbeId;
     publisher(channelName: string): ZLinkBackendPublisherSocket;
-    fanoutPublisherEndpoint(channelName: string): string | undefined;
     routeRouter(routerChannelId: string): ZLinkBackendRouterSocket;
     routeMeshSocket(routerChannelId: string): ZLinkBackendRouterSocket;
     routeMeshWeight(routerChannelId: string): number;