@zlink-systems/framework 0.26.0 → 0.27.0

package/dist/runtime/foundation/operation-registry.js

@@ -20,25 +20,19 @@ class OperationCancelledError extends Error {
 }
 exports.OperationCancelledError = OperationCancelledError;
 const systemClock = {
-    setTimeout(callback, delayMs) {
-        // A request promise is live work.  Raw RouteMesh polling deliberately
-        // uses unref'ed timers, so this deadline is the handle that keeps a
-        // submit() caller alive until a reply, cancellation, or deadline settles.
-        return setTimeout(callback, delayMs);
-    },
-    clearTimeout(handle) {
-        clearTimeout(handle);
-    }
+    now: () => performance.now()
 };
 /** Owns request completion so reply, timeout, cancellation, and shutdown race safely. */
 class OperationRegistry {
     clock;
+    onPendingChanged;
     entries = new Map();
     nextId = 1n;
-    generation = 1n;
+    deadlineCursor;
     closed = false;
-    constructor(clock = systemClock) {
+    constructor(clock = systemClock, onPendingChanged) {
         this.clock = clock;
+        this.onPendingChanged = onPendingChanged;
     }
     register(timeoutMs, timeoutOwner = 'registry') {
         if (this.closed)
@@ -47,20 +41,20 @@ class OperationRegistry {
             throw new RangeError('timeoutMs must be a non-negative finite number.');
         }
         const id = this.nextId++;
-        const generation = this.generation;
         let resolve;
         let reject;
         const promise = new Promise((onResolve, onReject) => {
             resolve = onResolve;
             reject = onReject;
         });
-        const entry = { generation, resolve, reject };
+        const entry = {
+            deadlineMs: timeoutOwner === 'registry' ? this.clock.now() + timeoutMs : undefined,
+            resolve,
+            reject
+        };
         this.entries.set(id, entry);
-        // Durable senders classify exhaustion from admission history. Keep their
-        // identity and cancellation here without racing that decision with a timer.
-        if (timeoutOwner === 'registry') {
-            entry.timer = this.clock.setTimeout(() => this.rejectIfCurrent(id, generation, new OperationTimeoutError(id)), timeoutMs);
-        }
+        if (this.entries.size === 1)
+            this.onPendingChanged?.();
         return { id, promise };
     }
     complete(id, value) {
@@ -71,9 +65,6 @@ class OperationRegistry {
         return true;
     }
     fail(id, reason) {
-        return this.failCore(id, reason);
-    }
-    failCore(id, reason) {
         const entry = this.take(id);
         if (entry === undefined)
             return false;
@@ -81,7 +72,7 @@ class OperationRegistry {
         return true;
     }
     cancel(id, message) {
-        return this.failCore(id, new OperationCancelledError(id, message));
+        return this.fail(id, new OperationCancelledError(id, message));
     }
     isPending(id) {
         return this.entries.has(id);
@@ -90,39 +81,38 @@ class OperationRegistry {
         if (this.closed)
             return;
         this.closed = true;
-        this.generation++;
-        const pending = [...this.entries.entries()];
-        this.entries.clear();
-        for (const [, entry] of pending)
-            this.clearTimer(entry);
-        for (const [id, entry] of pending) {
-            entry.reject(new OperationCancelledError(id, reason));
-        }
+        for (const id of this.entries.keys())
+            this.cancel(id, reason);
+        this.deadlineCursor = undefined;
     }
     get size() {
         return this.entries.size;
     }
-    rejectIfCurrent(id, generation, reason) {
-        const entry = this.entries.get(id);
-        if (entry === undefined || entry.generation !== generation)
-            return;
-        this.entries.delete(id);
-        this.clearTimer(entry);
-        entry.reject(reason);
+    expire(nowMs, turnDeadlineMs) {
+        let expired = 0;
+        while (this.clock.now() < turnDeadlineMs) {
+            this.deadlineCursor ??= this.entries.entries();
+            const current = this.deadlineCursor.next();
+            if (current.done === true) {
+                this.deadlineCursor = undefined;
+                break;
+            }
+            const [id, entry] = current.value;
+            if (entry.deadlineMs !== undefined && entry.deadlineMs <= nowMs) {
+                if (this.fail(id, new OperationTimeoutError(id)))
+                    expired++;
+            }
+        }
+        return expired;
     }
     take(id) {
         const entry = this.entries.get(id);
         if (entry === undefined)
             return undefined;
         this.entries.delete(id);
-        this.clearTimer(entry);
+        if (this.entries.size === 0)
+            this.onPendingChanged?.();
         return entry;
     }
-    clearTimer(entry) {
-        if (entry.timer === undefined)
-            return;
-        this.clock.clearTimeout(entry.timer);
-        entry.timer = undefined;
-    }
 }
 exports.OperationRegistry = OperationRegistry;

package/dist/runtime/foundation/raw-service-mesh-runtime.d.ts

@@ -1,7 +1,7 @@
+import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
+import type { ApplicationJobQueuePort } from '../application-jobs/contracts';
 import type { ZLinkRawBindingPort } from '../backend/raw-binding-port';
 import { SubmitResult } from '../backend/runtime-values';
-import type { ApplicationJobQueuePort } from '../application-jobs/contracts';
-import { ApplicationIngressRecordOwner } from '../application-jobs/application-ingress-record-owner';
 import { type PendingOperation } from './operation-registry';
 import { ServiceLivenessRegistry, type ServiceLivenessTick } from './service-liveness-registry';
 import { ServiceMailbox, type ServiceMailboxRecord } from './service-mailbox';
@@ -29,6 +29,7 @@ export interface RawServiceIngressRecord {
 }
 export type RawServiceIngressHandler = (record: RawServiceIngressRecord) => RawServicePumpResult | undefined | Promise<RawServicePumpResult | undefined>;
 export interface RawServiceMeshRuntimeOptions {
+    readonly onPendingOperationsChanged?: () => void;
     readonly descriptor: ServiceNodeDescriptor;
     readonly resolveAdvertisedEndpoint?: (boundEndpoint: string) => string;
     readonly probeIntervalMs?: number;
@@ -47,6 +48,7 @@ export interface RawServiceMeshRuntimeOptions {
         readonly command?: number;
     }) => void;
 }
+export declare const RAW_MESH_RECEIVE_TIME_BUDGET_MS = 2;
 /**
  * RouteMesh M6A runtime built only on the public raw binding package.
  * It owns protocol, admission, mailbox, request and liveness state.
@@ -105,7 +107,6 @@ export declare class RawServiceMeshRuntime {
     requestToNode(targetNodeRoutingId: string, payload: ServiceApplicationPayloadInput, timeoutMs: number): PendingOperation<RawServiceRequestResult>;
     requestToChannel(channelName: string, payload: ServiceApplicationPayloadInput, timeoutMs: number): PendingOperation<RawServiceRequestResult>;
     private selectChannelTarget;
-    private isLocalOrReadyPeer;
     setServiceIngress(handler: RawServiceIngressHandler): void;
     reserveLocalIngress(signal?: AbortSignal): Promise<ApplicationIngressRecordOwner>;
     sendService(targetNodeRoutingId: string, parts: readonly Uint8Array[]): Promise<boolean>;
@@ -113,13 +114,15 @@ export declare class RawServiceMeshRuntime {
     replyService(record: Pick<RawServiceIngressRecord, 'sourceRoutingId' | 'sourceRoute' | 'requestSequence' | 'reply'>, parts: readonly Uint8Array[]): void;
     reply(request: ServiceMailboxRecord, payload: ServiceApplicationPayloadInput, terminalResult?: number, failureCode?: number): void;
     pumpOne(nowMs?: number, observe?: RawServicePumpObserver): Promise<RawServicePumpResult>;
-    setReadableHandler(handler: () => void): void;
+    setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void;
     /** Returns whether a receive budget ended before no-data; idle ticks only maintain peers. */
-    pumpBatch(receiveReady?: boolean): Promise<boolean>;
+    pumpBatch(receiveReady?: boolean, routeReady?: boolean): Promise<boolean>;
     private receiveOne;
     private reportProtocolError;
     private replyGenericProtocolError;
     private processReceived;
+    expireOperations(nowMs: number, turnDeadlineMs: number): number;
+    get pendingOperationCount(): number;
     tickLiveness(nowMs?: number): Promise<ServiceLivenessTick>;
     /**
      * The socket's one route observer (Core ROUTER §10.1). It replaces the

package/dist/runtime/foundation/raw-service-mesh-runtime.js

@@ -1,21 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RawServiceMeshRuntime = void 0;
-const runtime_values_1 = require("../backend/runtime-values");
+exports.RawServiceMeshRuntime = exports.RAW_MESH_RECEIVE_TIME_BUDGET_MS = void 0;
+const node_os_1 = require("node:os");
 const application_ingress_record_owner_1 = require("../application-jobs/application-ingress-record-owner");
+const runtime_values_1 = require("../backend/runtime-values");
+const service_wire_codec_generated_1 = require("../protocol/service_wire_codec.generated");
 const operation_registry_1 = require("./operation-registry");
 const service_liveness_registry_1 = require("./service-liveness-registry");
 const service_mailbox_1 = require("./service-mailbox");
 const service_topology_registry_1 = require("./service-topology-registry");
-const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
 const service_wire_codec_1 = require("./service-wire-codec");
 const service_wire_constants_generated_1 = require("./service-wire-constants.generated");
+const service_wire_m6a_codec_1 = require("./service-wire-m6a-codec");
+const nativeErrnoValues = node_os_1.constants.errno;
 // Framework error code 13 (RequestTargetNotFound) is encoded as 14 on a
 // RequestResult.NotFound reply. Boundary transport results keep failureCode 0.
-const REQUEST_TARGET_NOT_FOUND_FAILURE_CODE = 14;
+const RAW_MESH_RECEIVE_RECORD_BUDGET = 64;
+const RAW_MESH_RECEIVE_BYTE_BUDGET = 4 * 1024 * 1024;
+exports.RAW_MESH_RECEIVE_TIME_BUDGET_MS = 2;
+const REQUEST_TARGET_NOT_FOUND_FAILURE_CODE = service_wire_constants_generated_1.ServiceWireFrameworkErrorCode.requestTargetNotFound;
 const livenessCodec = (0, service_wire_codec_1.createServiceWireCodec)({
-    magic: [0x5a, 0x4d],
-    major: 1,
+    magic: service_wire_constants_generated_1.SERVICE_WIRE_MAGIC,
+    major: service_wire_constants_generated_1.SERVICE_WIRE_MAJOR,
     commands: service_wire_m6a_codec_1.M6aServiceWireCommand
 });
 /**
@@ -26,7 +32,7 @@ class RawServiceMeshRuntime {
     topology;
     mailbox;
     liveness;
-    operations = new operation_registry_1.OperationRegistry();
+    operations;
     expectedPeers = new Map();
     endpointOnlyPeers = new Set();
     peerConnectionIntentRemoved = new Set();
@@ -51,6 +57,7 @@ class RawServiceMeshRuntime {
     serviceIngress;
     closed = false;
     constructor(options) {
+        this.operations = new operation_registry_1.OperationRegistry(undefined, options.onPendingOperationsChanged);
         this.descriptor = options.descriptor;
         this.topology = new service_topology_registry_1.ServiceTopologyRegistry(options.descriptor);
         this.mailbox = new service_mailbox_1.ServiceMailbox(options.onMailboxReady);
@@ -102,32 +109,32 @@ class RawServiceMeshRuntime {
     }
     connectPeer(endpoint, expected) {
         this.requireStarted().connectToRoutingId(expected.nodeRoutingId, endpoint);
-        this.expectedPeers.set(expected.nodeRoutingId, {
+        this.expectedPeers.set(expected.nodeRoutingId, Object.assign(this.expectedPeers.get(expected.nodeRoutingId) ?? {}, {
             meshName: expected.meshName,
             nodeRoutingId: expected.nodeRoutingId,
             endpoint,
             securityIdentity: expected.securityIdentity,
             lifecycleGeneration: expected.lifecycleGeneration
-        });
+        }));
     }
     connectPeerByRoutingId(endpoint, nodeRoutingId, securityIdentity, lifecycleGeneration) {
         this.requireStarted().connectToRoutingId(nodeRoutingId, endpoint);
-        this.expectedPeers.set(nodeRoutingId, {
+        this.expectedPeers.set(nodeRoutingId, Object.assign(this.expectedPeers.get(nodeRoutingId) ?? {}, {
             meshName: this.topology.localDescriptor().meshName,
             nodeRoutingId,
             endpoint,
             securityIdentity,
             lifecycleGeneration
-        });
+        }));
     }
     expectPeerByRoutingId(endpoint, nodeRoutingId, securityIdentity, lifecycleGeneration) {
-        this.expectedPeers.set(nodeRoutingId, {
+        this.expectedPeers.set(nodeRoutingId, Object.assign(this.expectedPeers.get(nodeRoutingId) ?? {}, {
             meshName: this.topology.localDescriptor().meshName,
             nodeRoutingId,
             endpoint,
             securityIdentity,
             lifecycleGeneration
-        });
+        }));
     }
     connectPeerEndpoint(endpoint) {
         this.requireStarted().connect(endpoint);
@@ -215,11 +222,21 @@ class RawServiceMeshRuntime {
             listener(nodeRoutingId);
     }
     async announcePeer(nodeRoutingId) {
-        if (!this.expectedPeers.has(nodeRoutingId) || this.peerAdmissionSealed?.() === true)
+        const expected = this.expectedPeers.get(nodeRoutingId);
+        const generation = this.selectedRoutes.get(nodeRoutingId);
+        if (expected === undefined ||
+            generation === undefined ||
+            expected.helloSubmittedGeneration === generation ||
+            this.peerAdmissionSealed?.() === true)
             return false;
-        return this.send(nodeRoutingId, [
+        const accepted = await this.send(nodeRoutingId, [
             (0, service_wire_m6a_codec_1.encodeRouteMeshAdmission)(service_wire_m6a_codec_1.M6aServiceWireCommand.hello, this.topology.localDescriptor())
         ]);
+        if (accepted &&
+            this.expectedPeers.get(nodeRoutingId) === expected &&
+            this.selectedRoutes.get(nodeRoutingId) === generation)
+            expected.helloSubmittedGeneration = generation;
+        return accepted;
     }
     isPeerRouteReady(nodeRoutingId, lifecycleGeneration) {
         // Admission is bound to the observed selected route: the route observer
@@ -233,11 +250,6 @@ class RawServiceMeshRuntime {
     async announceExpectedPeers() {
         let accepted = 0;
         for (const nodeRoutingId of this.expectedPeers.keys()) {
-            // Admission is a one-time fence for the current selected route.
-            // Re-sending Hello after the peer is admitted would re-run admission on
-            // every poll and reset the liveness record before application traffic
-            // can use the route. A peer whose selected route ended is removed by the
-            // route observer and remains eligible for the next admission attempt.
             if (this.topology.peer(nodeRoutingId) !== undefined)
                 continue;
             if (await this.announcePeer(nodeRoutingId))
@@ -271,7 +283,6 @@ class RawServiceMeshRuntime {
         for (const peer of this.topology.peers()) {
             await this.send(peer.descriptor.nodeRoutingId, [update]);
         }
-        await this.announceExpectedPeers();
     }
     replaceDiscoveredNotRequired(descriptors) {
         this.topology.replaceDiscoveredNotRequired(descriptors);
@@ -291,25 +302,6 @@ class RawServiceMeshRuntime {
             return selection.submitResult;
         const selected = selection.peer;
         const applicationFrame = this.applicationFrame(payload);
-        if (selected.descriptor.nodeRoutingId === this.descriptor.nodeRoutingId) {
-            const applicationJobOwner = await this.reserveLocalIngress();
-            try {
-                const applicationJob = await applicationJobOwner.acquire('application');
-                const accepted = this.mailbox.tryEnqueue({
-                    owner: `channel:${channelName}`,
-                    domain: 'application',
-                    parts: [(0, service_wire_m6a_codec_1.encodeChannelSendHeader)(channelName), applicationFrame],
-                    sourceRoutingId: this.descriptor.nodeRoutingId,
-                    applicationJob
-                });
-                if (!accepted)
-                    applicationJob.close();
-                return accepted ? runtime_values_1.SubmitResult.Ok : runtime_values_1.SubmitResult.NotAdmitted;
-            }
-            finally {
-                applicationJobOwner.close();
-            }
-        }
         return (await this.send(selected.descriptor.nodeRoutingId, [
             (0, service_wire_m6a_codec_1.encodeChannelSendHeader)(channelName),
             applicationFrame
@@ -330,7 +322,7 @@ class RawServiceMeshRuntime {
         return this.requestToTarget(selection.peer.descriptor.nodeRoutingId, payload, timeoutMs, channelName);
     }
     selectChannelTarget(channelName) {
-        const selected = this.topology.selectChannel(channelName, (peer) => this.isLocalOrReadyPeer(peer.descriptor.nodeRoutingId));
+        const selected = this.topology.selectChannel(channelName, (peer) => this.isPeerRouteReady(peer.descriptor.nodeRoutingId));
         if (selected !== undefined)
             return { kind: 'selected', peer: selected };
         return this.topology.hasKnownChannelTarget(channelName)
@@ -348,9 +340,6 @@ class RawServiceMeshRuntime {
                 }
             };
     }
-    isLocalOrReadyPeer(nodeRoutingId) {
-        return nodeRoutingId === this.descriptor.nodeRoutingId || this.isPeerRouteReady(nodeRoutingId);
-    }
     setServiceIngress(handler) {
         if (this.serviceIngress !== undefined && this.serviceIngress !== handler) {
             throw new Error('Raw service ingress is already registered.');
@@ -399,15 +388,16 @@ class RawServiceMeshRuntime {
         this.requireStarted().setReadableHandler(handler);
     }
     /** Returns whether a receive budget ended before no-data; idle ticks only maintain peers. */
-    async pumpBatch(receiveReady = true) {
-        await this.observeSelectedRoutes();
+    async pumpBatch(receiveReady = true, routeReady = false) {
+        if (routeReady)
+            await this.observeSelectedRoutes();
         const startedAtMs = performance.now();
         let messages = 0;
         let bytes = 0;
         const observe = (_source, byteCount) => {
             bytes += byteCount;
         };
-        while (receiveReady && messages < 64 && !this.closed) {
+        while (receiveReady && messages < RAW_MESH_RECEIVE_RECORD_BUDGET && !this.closed) {
             const result = await this.receiveOne(performance.now(), observe);
             if (result === 'noData') {
                 receiveReady = false;
@@ -416,7 +406,8 @@ class RawServiceMeshRuntime {
             messages += 1;
             // Core owns the per-peer fair-queue cursor. The Framework limit bounds
             // the entire round, so changing peers does not renew its byte/count budget.
-            if (bytes >= 4 * 1024 * 1024 || performance.now() - startedAtMs >= 2)
+            if (bytes >= RAW_MESH_RECEIVE_BYTE_BUDGET ||
+                performance.now() - startedAtMs >= exports.RAW_MESH_RECEIVE_TIME_BUDGET_MS)
                 break;
         }
         if (!this.closed) {
@@ -527,7 +518,9 @@ class RawServiceMeshRuntime {
                 if (expected !== undefined &&
                     (expected.meshName !== descriptor.meshName ||
                         expected.nodeRoutingId !== descriptor.nodeRoutingId)) {
-                    await this.send(received.sourceRid, [(0, service_wire_m6a_codec_1.encodeReject)(3)]);
+                    await this.send(received.sourceRid, [
+                        (0, service_wire_m6a_codec_1.encodeReject)((0, service_wire_codec_generated_1.enumWireRejectReason)('identityMismatch'))
+                    ]);
                     return 'infrastructure';
                 }
                 const result = this.admitPeer(descriptor, routeConnectionId(received.routeGeneration), nowMs, expected);
@@ -558,23 +551,7 @@ class RawServiceMeshRuntime {
             if (header.command === service_wire_m6a_codec_1.M6aServiceWireCommand.reject) {
                 if (received.parts.length !== 1)
                     return 'protocolError';
-                const reason = (0, service_wire_m6a_codec_1.decodeReject)(received.parts[0]);
-                // Keep an already admitted peer: a reject of an earlier Hello on the
-                // same selected route does not end the admission that succeeded.
-                if (reason === 4 && this.topology.peer(received.sourceRid) === undefined) {
-                    const expected = this.expectedPeers.get(received.sourceRid);
-                    const local = this.topology.localDescriptor();
-                    this.topology.markNotRequired({
-                        ...local,
-                        nodeRoutingId: received.sourceRid,
-                        lifecycleGeneration: 1n,
-                        descriptorRevision: 1n,
-                        advertisedEndpoint: expected?.endpoint ?? local.advertisedEndpoint,
-                        channels: [],
-                        objectRole: 'client'
-                    });
-                    this.retireNotRequiredExpectedPeer(received.sourceRid);
-                }
+                (0, service_wire_m6a_codec_1.decodeReject)(received.parts[0]);
                 return 'infrastructure';
             }
             const peer = this.topology.peer(received.sourceRid);
@@ -700,6 +677,12 @@ class RawServiceMeshRuntime {
             throw error;
         }
     }
+    expireOperations(nowMs, turnDeadlineMs) {
+        return this.operations.expire(nowMs, turnDeadlineMs);
+    }
+    get pendingOperationCount() {
+        return this.operations.size;
+    }
     async tickLiveness(nowMs = performance.now()) {
         const result = this.liveness.tick(nowMs);
         this.requireStarted();
@@ -739,6 +722,9 @@ class RawServiceMeshRuntime {
             if (observed.get(nodeRoutingId) === generation)
                 continue;
             changes++;
+            const expected = this.expectedPeers.get(nodeRoutingId);
+            if (expected !== undefined)
+                delete expected.helloSubmittedGeneration;
             const peer = this.topology.peer(nodeRoutingId);
             if (peer !== undefined && peer.connectionId === routeConnectionId(generation)) {
                 this.removePeer(peer);
@@ -761,7 +747,6 @@ class RawServiceMeshRuntime {
     close() {
         if (this.closed)
             return;
-        this.closed = true;
         this.applicationJobStop.abort(new Error('Raw service runtime application job admission stopped.'));
         this.mailbox.close();
         this.operations.close('Raw service runtime closed.');
@@ -771,10 +756,11 @@ class RawServiceMeshRuntime {
             this.applicationJobQueue.unregisterReceiveFlowTarget?.(router);
         }
         const host = this.host;
-        this.router = undefined;
-        this.host = undefined;
         if (host !== undefined)
             host.close();
+        this.router = undefined;
+        this.host = undefined;
+        this.closed = true;
     }
     requestToTarget(targetNodeRoutingId, payload, timeoutMs, channelName) {
         const correlation = this.nextCorrelation++;
@@ -796,13 +782,12 @@ class RawServiceMeshRuntime {
                 for (;;) {
                     const alternate = this.topology.selectChannel(channelName, (peer) => {
                         const candidate = peer.descriptor.nodeRoutingId;
-                        return !excludedTargets.has(candidate) && this.isLocalOrReadyPeer(candidate);
+                        return !excludedTargets.has(candidate) && this.isPeerRouteReady(candidate);
                     });
                     if (alternate === undefined)
                         break;
                     selectedTargetNodeRoutingId = alternate.descriptor.nodeRoutingId;
-                    if (selectedTargetNodeRoutingId === this.descriptor.nodeRoutingId ||
-                        this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
+                    if (this.isPeerRouteReady(selectedTargetNodeRoutingId)) {
                         break;
                     }
                     excludedTargets.add(selectedTargetNodeRoutingId);
@@ -824,9 +809,7 @@ class RawServiceMeshRuntime {
                         return;
                     }
                     const accepted = this.mailbox.tryEnqueue({
-                        owner: channelName === undefined
-                            ? `node:${this.descriptor.nodeRoutingId}`
-                            : `channel:${channelName}`,
+                        owner: `node:${this.descriptor.nodeRoutingId}`,
                         domain: 'application',
                         parts,
                         sourceRoutingId: this.descriptor.nodeRoutingId,
@@ -1019,7 +1002,7 @@ function isAlreadyDisconnectedError(error) {
     if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
         return false;
     }
-    return error.nativeErrno === 2;
+    return error.nativeErrno === nativeErrnoValues.ENOENT;
 }
 /**
  * An admission belongs to one Core selected route. Its connection identity is
@@ -1081,14 +1064,10 @@ function immutableDescriptorMismatch(current, descriptor) {
 function admissionReason(result) {
     switch (result) {
         case 'meshMismatch':
-            return 2;
+            return (0, service_wire_codec_generated_1.enumWireRejectReason)('topologyMismatch');
         case 'staleDescriptor':
-            return 7;
+            return (0, service_wire_codec_generated_1.enumWireRejectReason)('descriptorRevisionStale');
         case 'invalidDescriptor':
-            return 11;
-        case 'notRequired':
-            return 4;
-        case 'admitted':
-            return 1;
+            return (0, service_wire_codec_generated_1.enumWireRejectReason)('invalidDescriptor');
     }
 }

package/dist/runtime/foundation/runtime-state-projections.d.ts

@@ -1,4 +1,6 @@
-import { ZLinkFrameworkRuntimeState } from '../../contracts';
+import { ZLinkFrameworkRuntimeState, ZLinkTopologyState } from '../../contracts';
+export declare function runtimeObservationIsTerminal(state: ZLinkFrameworkRuntimeState): boolean;
+export declare function topologyObservationIsTerminal(state: ZLinkTopologyState): boolean;
 export type MaintenanceAdmissionState = 'preparing' | 'serving' | 'retiring' | 'draining' | 'stopped' | 'error';
 export type DiscoveryAvailability = 'preparing' | 'serving' | 'retiring' | 'stopped' | 'error' | 'disconnected';
 /** Derives public readiness from the public runtime state authority. */

package/dist/runtime/foundation/runtime-state-projections.js

@@ -1,11 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeObservationIsTerminal = runtimeObservationIsTerminal;
+exports.topologyObservationIsTerminal = topologyObservationIsTerminal;
 exports.runtimeStateIsReady = runtimeStateIsReady;
 exports.runtimeAcceptsWork = runtimeAcceptsWork;
 exports.maintenanceAdmissionState = maintenanceAdmissionState;
 exports.discoveryAvailabilityForRuntimeState = discoveryAvailabilityForRuntimeState;
 exports.topologyRuntimeIsReady = topologyRuntimeIsReady;
 const contracts_1 = require("../../contracts");
+function runtimeObservationIsTerminal(state) {
+    return state === contracts_1.ZLinkFrameworkRuntimeState.Stopped;
+}
+function topologyObservationIsTerminal(state) {
+    return state === contracts_1.ZLinkTopologyState.Stopped || state === contracts_1.ZLinkTopologyState.Failed;
+}
 /** Derives public readiness from the public runtime state authority. */
 function runtimeStateIsReady(state) {
     return state === contracts_1.ZLinkFrameworkRuntimeState.Serving;

package/dist/runtime/foundation/service-authority-payload-codec.js

@@ -8,7 +8,15 @@ exports.decodeServiceClosingSpotAuthority = decodeServiceClosingSpotAuthority;
 exports.decodeServiceInstanceAuthorityPayload = decodeServiceInstanceAuthorityPayload;
 exports.rewriteServiceAuthorityOwner = rewriteServiceAuthorityOwner;
 exports.rewriteServiceAuthorityRoute = rewriteServiceAuthorityRoute;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
+const contracts_1 = require("../../contracts");
+const actor_join_recovery_codec_1 = require("./actor-join-recovery-codec");
 const service_relocation_runtime_1 = require("./service-relocation-runtime");
+const service_wire_binary_primitives_1 = require("./service-wire-binary-primitives");
+const SPOT_AUTHORITY_OBJECT_KIND = 2;
+const USER_SPOT_WIRE_KIND = (0, contracts_1.zlinkSpotKindToWire)(contracts_1.ZLinkSpotKind.User);
+const INSTANCE_SPOT_WIRE_KIND = (0, contracts_1.zlinkSpotKindToWire)(contracts_1.ZLinkSpotKind.Instance);
+const AUTHORITY_TEXT16_MAX_BYTES = 0xffff;
 const AUTHORITY_MAGIC = Buffer.from([0x5a, 0x4c, 0x41, 0x55]);
 const AUTHORITY_FORMAT_VERSION = 1;
 const AUTHORITY_FLAGS = 0;
@@ -171,7 +179,7 @@ function decodeSpotAuthority(payload) {
         const operationKind = body.u8();
         const objectKind = body.u8();
         const object = body.takeReader(body.u16());
-        if (objectKind !== 2)
+        if (objectKind !== SPOT_AUTHORITY_OBJECT_KIND)
             return undefined;
         const spotKind = object.u8();
         const spot = object.takeReader(object.u16());
@@ -181,13 +189,13 @@ function decodeSpotAuthority(payload) {
         let state;
         let stableType;
         let spotId;
-        if (spotKind === 2) {
+        if (spotKind === USER_SPOT_WIRE_KIND) {
             kind = 'user_spot';
             spotId = spot.rid();
             stableType = spot.text8();
             state = spot.u8();
         }
-        else if (spotKind === 3) {
+        else if (spotKind === INSTANCE_SPOT_WIRE_KIND) {
             kind = 'instance_spot';
             state = spot.u8();
             const instance = spot.takeReader(spot.u16());
@@ -279,21 +287,23 @@ function rid(value, name) {
 }
 function text16(value, name) {
     const bytes = Buffer.from(value);
-    if (bytes.byteLength < 1 || bytes.byteLength > 0xffff || bytes.includes(0)) {
-        throw new RangeError(`${name} must contain 1..65535 UTF-8 bytes without NUL.`);
+    if (bytes.byteLength < 1 || bytes.byteLength > AUTHORITY_TEXT16_MAX_BYTES || bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..${AUTHORITY_TEXT16_MAX_BYTES} UTF-8 bytes without NUL.`);
     }
     return concat(u16(bytes.byteLength), bytes);
 }
 function sha256(value) {
-    if (value.byteLength !== 32) {
-        throw new RangeError('activationRecovery.sha256 must contain exactly 32 bytes.');
+    if (value.byteLength !== actor_join_recovery_codec_1.SHA256_DIGEST_BYTES) {
+        throw new RangeError(`activationRecovery.sha256 must contain exactly ${actor_join_recovery_codec_1.SHA256_DIGEST_BYTES} bytes.`);
     }
-    return concat(Buffer.of(32), value);
+    return concat(Buffer.of(actor_join_recovery_codec_1.SHA256_DIGEST_BYTES), value);
 }
 function sized8(value, name) {
     const bytes = Buffer.from(value);
-    if (bytes.byteLength < 1 || bytes.byteLength > 255 || bytes.includes(0)) {
-        throw new RangeError(`${name} must contain 1..255 UTF-8 bytes without NUL.`);
+    if (bytes.byteLength < 1 ||
+        bytes.byteLength > service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES ||
+        bytes.includes(0)) {
+        throw new RangeError(`${name} must contain 1..${service_wire_binary_primitives_1.SERVICE_WIRE_TEXT8_MAX_BYTES} UTF-8 bytes without NUL.`);
     }
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
@@ -314,7 +324,7 @@ function boundedU32(value, name) {
     return u32(value);
 }
 function u64(value, name) {
-    if (value <= 0n || value > 0xffffffffffffffffn) {
+    if (value <= 0n || value > stream_wire_1.UINT64_MAX) {
         throw new RangeError(`${name} must be a non-zero u64.`);
     }
     const result = Buffer.alloc(8);
@@ -322,7 +332,7 @@ function u64(value, name) {
     return result;
 }
 function ordinalU64(value, name) {
-    if (value < 0n || value > 0xffffffffffffffffn) {
+    if (value < 0n || value > stream_wire_1.UINT64_MAX) {
         throw new RangeError(`${name} must be a u64.`);
     }
     const result = Buffer.alloc(8);

package/dist/runtime/foundation/service-discovery-registry.d.ts

@@ -23,6 +23,9 @@ export interface SelectedClientServer {
 }
 /** Dedicated discovery state; fanout publishers never reuse RouteMesh peer rows. */
 export declare class ServiceDiscoveryRegistry {
+    private readonly clientServerChanged;
+    onClientServerChanged(listener: (error?: Error) => void): () => void;
+    dispose(error: Error): void;
     private readonly clientServers;
     private readonly fanoutPublishers;
     private readonly clientServerSelections;
@@ -32,6 +35,7 @@ export declare class ServiceDiscoveryRegistry {
     selectClientServer(channelName: string): ClientServerDescriptor | undefined;
     selectClientServerConnection(channelName: string): SelectedClientServer | undefined;
     private selectClientServerConnectionCore;
+    hasReadyClientServer(channelName: string): boolean;
     clientServerDescriptors(channelName: string): readonly ClientServerDescriptor[];
     admitFanoutPublisher(descriptor: FanoutPublisherDescriptor, connectionId: string): boolean;
     removeFanoutPublisher(channelName: string, publisherRoutingId: string, connectionId: string): boolean;