@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/backend/raw-binding-port.d.ts

@@ -2,6 +2,11 @@ export interface ZLinkRawReceivedRecord {
     readonly sourceRid: string;
     readonly sourceRoute: Uint8Array;
     readonly requestSeq?: bigint;
+    /**
+     * Core selected-route generation of the ROUTER route that delivered this
+     * record (Core ROUTER §10.1); 0n for a non-ROUTER receive. Equality only.
+     */
+    readonly routeGeneration: bigint;
     readonly reply?: (parts: readonly Uint8Array[]) => void;
     readonly parts: readonly Buffer[];
     /** Releases the ordinary Framework-owned receive record exactly once. */
@@ -19,7 +24,7 @@ export interface ZLinkRawMonitorRecord {
     readonly flags?: number;
 }
 export interface ZLinkRawSocketPort {
-    setReadableHandler(handler: () => void): void;
+    setReadableHandler(handler: (receiveReady: boolean, routeReady: boolean) => void): void;
     bind(endpoint: string): void;
     unbind(endpoint: string): void;
     connect(endpoint: string): void;
@@ -33,6 +38,11 @@ export interface ZLinkRawMonitorPort {
     statusReady(): boolean;
     close(): void;
 }
+/** One row of the ROUTER selected-route snapshot (Core ROUTER §10.1). */
+export interface ZLinkRawRouterRoute {
+    readonly routingId: string;
+    readonly routeGeneration: bigint;
+}
 export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     disconnectRid?(routingId: string): void;
     localEndpoint(): string;
@@ -41,6 +51,8 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     send(targetRid: string, parts: readonly Uint8Array[]): Promise<void>;
     request(targetRid: string, parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]>;
     receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
+    /** The selected route of every RID. The socket's one route observer calls it. */
+    routesSnapshot(): readonly ZLinkRawRouterRoute[];
 }
 export interface ZLinkRawDealerPort extends ZLinkRawSocketPort {
     setRoutingId(routingId: string): void;

package/dist/runtime/backend/runtime-values.d.ts

@@ -41,7 +41,10 @@ export declare class ZLinkBackendResultError extends Error {
     readonly operation: 'request' | 'submit';
     readonly result: number;
     readonly nativeErrno?: number | undefined;
-    constructor(operation: 'request' | 'submit', result: number, nativeErrno?: number | undefined, options?: ErrorOptions);
+    constructor(operation: 'request' | 'submit', result: number, nativeErrno?: number | undefined, options?: ErrorOptions & {
+        readonly phase?: 'submit' | 'completion';
+    });
+    readonly phase: 'submit' | 'completion';
 }
 export declare function isZLinkBackendResultError(error: unknown): error is ZLinkBackendResultError;
 export declare function isBackendNotConnectedError(error: unknown): boolean;

package/dist/runtime/backend/runtime-values.js

@@ -48,7 +48,9 @@ class ZLinkBackendResultError extends Error {
         this.result = result;
         this.nativeErrno = nativeErrno;
         this.name = 'ZLinkBackendResultError';
+        this.phase = options?.phase ?? 'completion';
     }
+    phase;
 }
 exports.ZLinkBackendResultError = ZLinkBackendResultError;
 function isZLinkBackendResultError(error) {

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

@@ -2,15 +2,24 @@ import type { ZLinkChannelClient, ZLinkChannelRequestCall, ZLinkFanoutClient, ZL
 import type { SpotHandle } from '../spots/spot-handle';
 import { type ZLinkFrameworkRegistration } from '../configuration';
 import type { ZLinkChannelClientTransportSource, ZLinkRouteClientTransport, ZLinkSpotPublisherClientTransport } from './channel-transports';
+type RouteMeshChannelMatch = {
+    readonly meshName: string;
+    readonly mesh: NonNullable<ReturnType<ZLinkFrameworkRegistration['spotNodes']['get']>>;
+};
+type ChannelRouteResolution = {
+    readonly kind: 'client-server';
+    readonly channel: NonNullable<ReturnType<ZLinkFrameworkRegistration['channels']['get']>>;
+} | {
+    readonly kind: 'route-mesh';
+    readonly matches: readonly RouteMeshChannelMatch[];
+};
+export declare function resolveChannelRoute(registration: ZLinkFrameworkRegistration, channelName: string): ChannelRouteResolution | undefined;
+export declare function requireUniqueRouteMeshChannel(matches: readonly RouteMeshChannelMatch[], duplicateMessage: string): RouteMeshChannelMatch;
 export declare class DefaultZLinkChannelClient implements ZLinkChannelClient {
-    private readonly registration;
-    private readonly transport?;
-    constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkChannelClientTransportSource | undefined);
+    private readonly routeClient;
+    constructor(registration: ZLinkFrameworkRegistration, channelTransport?: ZLinkChannelClientTransportSource, routeTransport?: ZLinkRouteClientTransport, spotRouterChannelIdForMesh?: (meshName: string) => string);
     sendToChannel(channelName: string, message: unknown): ZLinkSendCall;
     requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall;
-    private defaultRequestTimeout;
-    private requireChannel;
-    private requireTransport;
 }
 export declare class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
     private readonly registration;
@@ -18,7 +27,6 @@ export declare class DefaultZLinkFanoutClient implements ZLinkFanoutClient {
     constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkChannelClientTransportSource | undefined);
     publish(channelName: string, event: unknown): ZLinkFanoutPublishCall;
     publish(channelName: string, topic: string, event: unknown): ZLinkFanoutPublishCall;
-    getListenerStatus(channelName: string): import('../../contracts').ZLinkFanoutListenerStatus;
     private requirePublisherChannel;
     private requireTransport;
 }
@@ -26,7 +34,8 @@ export declare class DefaultZLinkRouteClient implements ZLinkRouteClient {
     private readonly registration;
     private readonly transport?;
     private readonly spotRouterChannelIdForMesh;
-    constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkRouteClientTransport | undefined, spotRouterChannelIdForMesh?: (meshName: string) => string);
+    private readonly channelTransport?;
+    constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkRouteClientTransport | undefined, spotRouterChannelIdForMesh?: (meshName: string) => string, channelTransport?: ZLinkChannelClientTransportSource | undefined);
     sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall;
     requestToNode(meshName: string, targetNodeRid: string, request: unknown): ZLinkRequestCall;
     sendToChannel(channelName: string, message: unknown): ZLinkSendCall;
@@ -35,9 +44,10 @@ export declare class DefaultZLinkRouteClient implements ZLinkRouteClient {
     requestToSpot(spot: SpotHandle, request: unknown): ZLinkRequestCall;
     private defaultRequestTimeout;
     private requireMesh;
-    private resolveMeshChannel;
+    private requireChannelRoute;
     private defaultRequestTimeoutForChannel;
     private requireTransport;
+    private requireChannelTransport;
     private requireSpotTransport;
 }
 export declare class DefaultZLinkSpotPublisherClient implements ZLinkSpotPublisherClient {
@@ -48,3 +58,4 @@ export declare class DefaultZLinkSpotPublisherClient implements ZLinkSpotPublish
     private requireMeshChannel;
     private requireTransport;
 }
+export {};

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

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkSpotPublisherClient = exports.DefaultZLinkRouteClient = exports.DefaultZLinkFanoutClient = exports.DefaultZLinkChannelClient = void 0;
+exports.resolveChannelRoute = resolveChannelRoute;
+exports.requireUniqueRouteMeshChannel = requireUniqueRouteMeshChannel;
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const configuration_1 = require("../configuration");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const submission_result_1 = require("../messaging/submission-result");
@@ -9,39 +12,32 @@ const execution_1 = require("../execution");
 const fanout_service_wire_1 = require("./fanout-service-wire");
 const spot_outbound_1 = require("../spots/spot-outbound");
 const packet_name_1 = require("../messaging/packet-name");
+function resolveChannelRoute(registration, channelName) {
+    const clientServerChannel = registration.channels.get(channelName);
+    if (clientServerChannel !== undefined) {
+        return { kind: 'client-server', channel: clientServerChannel };
+    }
+    const matches = [...registration.spotNodes.entries()]
+        .filter(([, mesh]) => Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName))
+        .map(([meshName, mesh]) => ({ meshName, mesh }));
+    return matches.length === 0 ? undefined : { kind: 'route-mesh', matches };
+}
+function requireUniqueRouteMeshChannel(matches, duplicateMessage) {
+    if (matches.length !== 1) {
+        throw new configuration_1.ZLinkConfigurationException(duplicateMessage);
+    }
+    return matches[0];
+}
 class DefaultZLinkChannelClient {
-    registration;
-    transport;
-    constructor(registration, transport) {
-        this.registration = registration;
-        this.transport = transport;
+    routeClient;
+    constructor(registration, channelTransport, routeTransport, spotRouterChannelIdForMesh = (meshName) => meshName) {
+        this.routeClient = new DefaultZLinkRouteClient(registration, routeTransport, spotRouterChannelIdForMesh, channelTransport);
     }
     sendToChannel(channelName, message) {
-        return new DefaultZLinkSendCall(() => this.requireChannel(channelName), async (packetName, metadata, signal) => normalizeSubmitResult(await this.requireTransport().send(channelName, packetName, message, signal, metadata)));
+        return this.routeClient.sendToChannel(channelName, message);
     }
     requestToChannel(channelName, request) {
-        return new DefaultZLinkRequestCall(() => this.requireChannel(channelName), (packetName, timeoutMs, metadata, signal) => this.requireTransport().request(channelName, packetName, request, timeoutMs, signal, metadata), this.defaultRequestTimeout(channelName));
-    }
-    defaultRequestTimeout(channelName) {
-        return (this.registration.channels.get(channelName)?.requestTimeoutMs ??
-            this.registration.requestTimeoutMs ??
-            30_000);
-    }
-    requireChannel(channelName) {
-        const channel = this.registration.channels.get(channelName);
-        if (channel === undefined) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `Channel client '${channelName}' is not registered.`);
-        }
-        if (channel.client === undefined) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `Channel client role '${channelName}' is not configured.`);
-        }
-    }
-    requireTransport() {
-        const transport = typeof this.transport === 'function' ? this.transport() : this.transport;
-        if (transport === undefined) {
-            throw new configuration_1.ZLinkConfigurationException('Channel runtime is not started.');
-        }
-        return transport;
+        return this.routeClient.requestToChannel(channelName, request);
     }
 }
 exports.DefaultZLinkChannelClient = DefaultZLinkChannelClient;
@@ -64,14 +60,6 @@ class DefaultZLinkFanoutClient {
             status: (await this.requireTransport().publish(channelName, topic, packetName, event, signal)).status
         }));
     }
-    getListenerStatus(channelName) {
-        this.requirePublisherChannel(channelName);
-        const status = this.requireTransport().getFanoutListenerStatus?.(channelName);
-        if (status === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Fanout publisher '${channelName}' has not reported a bound listener.`);
-        }
-        return status;
-    }
     requirePublisherChannel(channelName) {
         if (!this.registration.fanoutPublishers.has(channelName)) {
             throw new configuration_1.ZLinkConfigurationException(`Channel '${channelName}' does not have a publisher capability.`);
@@ -90,10 +78,12 @@ class DefaultZLinkRouteClient {
     registration;
     transport;
     spotRouterChannelIdForMesh;
-    constructor(registration, transport, spotRouterChannelIdForMesh = (meshName) => meshName) {
+    channelTransport;
+    constructor(registration, transport, spotRouterChannelIdForMesh = (meshName) => meshName, channelTransport) {
         this.registration = registration;
         this.transport = transport;
         this.spotRouterChannelIdForMesh = spotRouterChannelIdForMesh;
+        this.channelTransport = channelTransport;
     }
     sendToNode(meshName, targetNodeRid, message) {
         return new DefaultZLinkSendCall(() => this.requireMesh(meshName), async (packetName, metadata, signal) => normalizeSubmitResult(await this.requireTransport().submit(meshName, targetNodeRid, packetName, message, signal, metadata)));
@@ -102,19 +92,21 @@ class DefaultZLinkRouteClient {
         return new DefaultZLinkRequestCall(() => this.requireMesh(meshName), (packetName, timeoutMs, metadata, signal) => this.requireTransport().request(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata), this.defaultRequestTimeout(meshName));
     }
     sendToChannel(channelName, message) {
-        return new DefaultZLinkSendCall(() => {
-            this.resolveMeshChannel(channelName);
-        }, async (packetName, metadata, signal) => {
-            const meshName = this.resolveMeshChannel(channelName);
-            return normalizeSubmitResult(await this.requireTransport().submitToChannel(meshName, channelName, packetName, message, signal, metadata));
+        return new DefaultZLinkSendCall(() => this.requireChannelRoute(channelName), async (packetName, metadata, signal) => {
+            const route = this.requireChannelRoute(channelName);
+            if (route.kind === 'route-mesh') {
+                return normalizeSubmitResult(await this.requireTransport().submitToChannel(route.meshName, channelName, packetName, message, signal, metadata));
+            }
+            return normalizeSubmitResult(await this.requireChannelTransport().send(channelName, packetName, message, signal, metadata));
         });
     }
     requestToChannel(channelName, request) {
-        return new DefaultZLinkRequestCall(() => {
-            this.resolveMeshChannel(channelName);
-        }, (packetName, timeoutMs, metadata, signal) => {
-            const meshName = this.resolveMeshChannel(channelName);
-            return this.requireTransport().requestToChannel(meshName, channelName, packetName, request, timeoutMs, signal, metadata);
+        return new DefaultZLinkRequestCall(() => this.requireChannelRoute(channelName), (packetName, timeoutMs, metadata, signal) => {
+            const route = this.requireChannelRoute(channelName);
+            if (route.kind === 'route-mesh') {
+                return this.requireTransport().requestToChannel(route.meshName, channelName, packetName, request, timeoutMs, signal, metadata);
+            }
+            return this.requireChannelTransport().request(channelName, packetName, request, timeoutMs, signal, metadata);
         }, this.defaultRequestTimeoutForChannel(channelName));
     }
     sendToSpot(spot, message) {
@@ -137,13 +129,13 @@ class DefaultZLinkRouteClient {
             signal,
             metadata,
             spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
-        }), this.registration.requestTimeoutMs ?? 30_000);
+        }), this.registration.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS);
     }
     defaultRequestTimeout(meshName) {
         return (this.registration.spotNodes.get(meshName)?.requestTimeoutMs ??
             this.registration.routeChannelOptions.get(meshName)?.requestTimeoutMs ??
             this.registration.requestTimeoutMs ??
-            30_000);
+            Registration_1.DEFAULT_REQUEST_TIMEOUT_MS);
     }
     requireMesh(meshName) {
         if (!this.registration.spotNodes.has(meshName) &&
@@ -151,21 +143,30 @@ class DefaultZLinkRouteClient {
             throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' is not registered.`);
         }
     }
-    resolveMeshChannel(channelName) {
-        const matches = [...this.registration.spotNodes.entries()]
-            .filter(([, mesh]) => Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName))
-            .map(([meshName]) => meshName);
-        if (matches.length === 0) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `RouteMesh channel '${channelName}' is not registered.`);
+    requireChannelRoute(channelName) {
+        const resolution = resolveChannelRoute(this.registration, channelName);
+        if (resolution === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `ChannelName '${channelName}' is not registered.`);
         }
-        if (matches.length !== 1) {
-            throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' must be unique across the Framework host.`);
+        if (resolution.kind === 'client-server') {
+            if (resolution.channel.client === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `Channel client role '${channelName}' is not configured.`);
+            }
+            return resolution;
         }
-        return matches[0];
+        return {
+            kind: 'route-mesh',
+            ...requireUniqueRouteMeshChannel(resolution.matches, `RouteMesh channel '${channelName}' must be unique across the Framework host.`)
+        };
     }
     defaultRequestTimeoutForChannel(channelName) {
-        const match = [...this.registration.spotNodes.entries()].find(([, mesh]) => Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName));
-        return match?.[1].requestTimeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+        const route = resolveChannelRoute(this.registration, channelName);
+        const timeoutMs = route?.kind === 'client-server'
+            ? route.channel.requestTimeoutMs
+            : route?.kind === 'route-mesh'
+                ? route.matches[0]?.mesh.requestTimeoutMs
+                : undefined;
+        return timeoutMs ?? this.registration.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS;
     }
     requireTransport() {
         if (this.transport === undefined) {
@@ -173,6 +174,13 @@ class DefaultZLinkRouteClient {
         }
         return this.transport;
     }
+    requireChannelTransport() {
+        const transport = typeof this.channelTransport === 'function' ? this.channelTransport() : this.channelTransport;
+        if (transport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Channel runtime is not started.');
+        }
+        return transport;
+    }
     requireSpotTransport() {
         const transport = this.requireTransport();
         if (transport.sendToSpot === undefined || transport.requestToSpot === undefined) {

package/dist/runtime/channels/channel-envelope-inspection.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.tryDecodeChannelHeader = tryDecodeChannelHeader;
 exports.inspectMalformedChannelHeader = inspectMalformedChannelHeader;
 exports.malformedProtocolErrorRequestHeader = malformedProtocolErrorRequestHeader;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const channel_envelope_1 = require("./channel-envelope");
 function tryDecodeChannelHeader(parts, flowEnabled = true) {
     if (parts.length < 2 || parts[0].data().length === 0) {
@@ -55,7 +56,7 @@ function malformedProtocolErrorRequestHeader(channelName, info) {
         kind: 1 /* ZLinkChannelMessageKind.Request */,
         channelName,
         messageName: info.messageName ?? '',
-        contentType: 'application/json',
+        contentType: stream_wire_1.ZlinkStreamContentType.Json,
         correlationId: info.correlationId ?? null,
         deadline: null,
         topic: null,

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

@@ -14,6 +14,7 @@ exports.decodeChannelPayload = decodeChannelPayload;
 exports.closeMessages = closeMessages;
 exports.decodeChannelHeader = decodeChannelHeader;
 const node_crypto_1 = require("node:crypto");
+const node_buffer_1 = require("node:buffer");
 const contracts_1 = require("../../contracts");
 const encoded_payload_storage_1 = require("../../contracts/Common/encoded-payload-storage");
 const ZLinkMessage_1 = require("../../contracts/Common/ZLinkMessage");
@@ -24,6 +25,7 @@ const payload_codec_1 = require("../messaging/payload-codec");
 const CodecContentType_1 = require("../../contracts/Configuration/CodecContentType");
 const framework_json_v1_1 = require("../messaging/framework-json-v1");
 const flow_context_1 = require("../diagnostics/flow-context");
+const service_wire_constants_generated_1 = require("../foundation/service-wire-constants.generated");
 const channel_framework_packets_1 = require("./channel-framework-packets");
 const Attributes_1 = require("../../contracts/Handlers/Attributes");
 exports.ZLINK_CHANNEL_FORMAT_MARKER = 0xf2;
@@ -314,7 +316,20 @@ function writeChannelHeader(writer, kind, channelName, messageName, contentType,
         writer.append(',"source":');
         writer.nullableString(source);
     }
-    writer.append(',"metadata":{');
+    writer.append(',"metadata":');
+    writeApplicationMetadata(writer, metadata);
+    if (flowId !== undefined) {
+        writer.append(',"flowId":');
+        writer.string(flowId);
+    }
+    if (flowOrigin !== undefined) {
+        writer.append(',"flowOrigin":');
+        writer.append(String(encodeFlowOrigin(flowOrigin)));
+    }
+    writer.append('}');
+}
+function writeApplicationMetadata(writer, metadata) {
+    writer.append('{');
     let first = true;
     for (const name in metadata) {
         if (!Object.prototype.hasOwnProperty.call(metadata, name))
@@ -327,15 +342,6 @@ function writeChannelHeader(writer, kind, channelName, messageName, contentType,
         writer.string(metadata[name]);
     }
     writer.append('}');
-    if (flowId !== undefined) {
-        writer.append(',"flowId":');
-        writer.string(flowId);
-    }
-    if (flowOrigin !== undefined) {
-        writer.append(',"flowOrigin":');
-        writer.append(String(encodeFlowOrigin(flowOrigin)));
-    }
-    writer.append('}');
 }
 class ChannelHeaderWriter {
     output;
@@ -438,13 +444,16 @@ function parseWireJson(payload, schema) {
     }, schema);
 }
 function parseChannelHeaderBytes(payload) {
-    return tryParseCanonicalChannelHeader(payload) ?? parseWireJson(payload.toString());
+    if (!(0, node_buffer_1.isUtf8)(payload)) {
+        throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'Channel envelope header must contain valid UTF-8.');
+    }
+    return tryParseCanonicalChannelHeader(payload) ?? (0, framework_json_v1_1.parseFrameworkJsonV1)(payload.toString());
 }
 /**
  * Accept the byte layout emitted by writeChannelHeader without materializing
  * the enclosing JSON text. Any variation falls through to the established
  * framework-json-v1 parser, which remains the sole authority for JSON
- * failures, unknown properties, and prototype-key rejection.
+ * failures and unknown properties. Header metadata accepts every valid string key.
  */
 function tryParseCanonicalChannelHeader(payload) {
     const reader = new CanonicalChannelHeaderReader(payload);
@@ -700,34 +709,43 @@ function channelKindName(kind) {
 }
 const EMPTY_APPLICATION_METADATA = Object.freeze({});
 function applicationMetadataRecord(metadata) {
-    //  The common case carries no metadata; skip the record + JSON.stringify
-    //  byte-limit walk entirely.
     if (metadata.size === 0)
         return EMPTY_APPLICATION_METADATA;
-    const record = {};
-    for (const [key, value] of metadata) {
-        if (key.length === 0 || key.includes('\0') || value.includes('\0')) {
-            throw new configuration_1.ZLinkConfigurationException('Channel application metadata keys must be non-empty and keys and values must not contain NUL.');
-        }
+    const record = Object.create(null);
+    for (const [key, value] of metadata)
         record[key] = value;
+    return validateApplicationMetadata(record);
+}
+const INVALID_METADATA_UNICODE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u;
+function validateApplicationMetadata(metadata) {
+    const keys = Object.keys(metadata);
+    if (keys.length === 0)
+        return EMPTY_APPLICATION_METADATA;
+    for (const key of keys) {
+        const value = requireString(metadata[key], `metadata.${key}`);
+        if (key.length === 0 ||
+            key.includes('\0') ||
+            value.includes('\0') ||
+            INVALID_METADATA_UNICODE.test(key) ||
+            INVALID_METADATA_UNICODE.test(value)) {
+            throw new configuration_1.ZLinkConfigurationException('Channel application metadata keys must be non-empty and keys and values must be valid Unicode without NUL.');
+        }
     }
-    if (Buffer.byteLength(JSON.stringify(record), 'utf8') > 1024) {
-        throw new configuration_1.ZLinkConfigurationException('Channel application metadata exceeds the 1024-byte limit.');
+    const record = metadata;
+    const writer = new ChannelHeaderWriter();
+    writeApplicationMetadata(writer, record);
+    if (writer.byteLength > service_wire_constants_generated_1.SERVICE_WIRE_METADATA_BYTES) {
+        throw new configuration_1.ZLinkConfigurationException(`Channel application metadata exceeds the ${service_wire_constants_generated_1.SERVICE_WIRE_METADATA_BYTES}-byte limit.`);
     }
     return Object.freeze(record);
 }
 function requireApplicationMetadata(value) {
-    if (value === undefined) {
-        return Object.freeze({});
-    }
+    if (value === undefined)
+        return EMPTY_APPLICATION_METADATA;
     if (!isRecord(value)) {
         throw new configuration_1.ZLinkConfigurationException('Channel application metadata must be a JSON object.');
     }
-    const metadata = new Map();
-    for (const [key, selectedValue] of Object.entries(value)) {
-        metadata.set(key, requireString(selectedValue, `metadata.${key}`));
-    }
-    return applicationMetadataRecord(metadata);
+    return validateApplicationMetadata(value);
 }
 function optionalFlowId(value) {
     return value === undefined || value === null ? undefined : requireFlowId(value);

package/dist/runtime/channels/channel-outbound-operations.d.ts

@@ -1,4 +1,5 @@
 import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import { type ZLinkRuntimeMessageFlowResult } from '../../contracts/Dispatch/ZLinkDispatchOptions';
 import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
 import { ZLinkChannelDispatchServices } from './channel-dispatch-services';
 import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
@@ -31,3 +32,5 @@ export declare class ZLinkChannelOutboundOperations {
  * ref'ed handle until reply, cancellation, timeout, or failure settles it.
  */
 export declare function keepChannelRequestAlive<T>(request: Promise<T>): Promise<T>;
+export declare function requestTerminalResult(error: unknown, signal: AbortSignal | undefined): ZLinkRuntimeMessageFlowResult;
+export declare function isRemoteChannelErrorReply(error: unknown): boolean;

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

@@ -2,6 +2,8 @@
 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 runtime_values_1 = require("../backend/runtime-values");
 const submission_result_1 = require("../messaging/submission-result");
@@ -39,11 +41,7 @@ class ZLinkChannelOutboundOperations {
         (0, abort_1.throwIfAborted)(signal);
         const dealer = await this.sockets.awaitClientDealerForOutbound(channelName, signal);
         if (dealer === undefined) {
-            return {
-                status: this.sockets.hasKnownClientServerTargets(channelName)
-                    ? submission_result_1.ZLinkSubmitStatus.RouteNotConnected
-                    : submission_result_1.ZLinkSubmitStatus.TargetNotFound
-            };
+            return { status: submission_result_1.ZLinkSubmitStatus.TimedOut };
         }
         const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(3 /* ZLinkChannelMessageKind.Command */, channelName, packetName, message, undefined, undefined, this.codecs, undefined, this.dispatchServices.flowCreationEnabled(), metadata);
         try {
@@ -83,7 +81,6 @@ 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;
         let correlationId;
         let selectedServerRid;
         let terminalRecorded = false;
@@ -104,20 +101,14 @@ 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)(this.sockets.hasKnownClientServerTargets(channelName)
-                    ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected
-                    : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, this.sockets.hasKnownClientServerTargets(channelName)
-                    ? `Channel '${channelName}' has known ClientServer targets but no ready server.`
-                    : `Channel '${channelName}' has no ready ClientServer server.`);
+            const dealer = await this.sockets.awaitClientDealerForOutbound(channelName, signal);
+            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.encodeChannelEnvelopeParts)(1 /* ZLinkChannelMessageKind.Request */, channelName, packetName, request, timeoutMs, 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,
@@ -131,7 +122,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, timeoutMs), signal);
                     }
                     catch (error) {
                         if (signal?.aborted === true)
@@ -142,7 +133,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);
                 }

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>;