@zlink-systems/framework 0.26.0 → 0.28.0

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

@@ -24,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;

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;
@@ -25,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;
@@ -34,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 {
@@ -47,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;
@@ -82,39 +78,42 @@ 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)));
+        return new DefaultZLinkSendCall(() => this.requireMesh(meshName), async (packetName, metadata) => normalizeSubmitResult(await this.requireTransport().submit(meshName, targetNodeRid, packetName, message, metadata)));
     }
     requestToNode(meshName, targetNodeRid, request) {
         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) => {
+            const route = this.requireChannelRoute(channelName);
+            if (route.kind === 'route-mesh') {
+                return normalizeSubmitResult(await this.requireTransport().submitToChannel(route.meshName, channelName, packetName, message, metadata));
+            }
+            return normalizeSubmitResult(await this.requireChannelTransport().send(channelName, packetName, message, 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) {
         return new DefaultZLinkSendCall(() => {
             this.requireSpotTransport();
-        }, async (_packetName, metadata, signal) => {
+        }, async (_packetName, metadata) => {
             await (0, spot_outbound_1.sendToSpotHandle)(this.requireSpotTransport(), spot, message, {
-                signal,
                 metadata,
                 spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
             });
@@ -129,13 +128,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) &&
@@ -143,21 +142,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) {
@@ -165,6 +173,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) {
@@ -220,12 +235,11 @@ class DefaultZLinkSendCall {
         }
         return this;
     }
-    async submit(signal) {
+    async submit() {
         ensureNotExecuted(this.executed);
         this.validate();
         this.executed = true;
-        (0, abort_1.throwIfAborted)(signal);
-        const result = await this.submitter(undefined, new Map(this.selectedMetadata), signal);
+        const result = await this.submitter(undefined, new Map(this.selectedMetadata));
         (0, submission_result_1.requireOneWayCompletion)(result, 'One-way send');
     }
 }
@@ -321,6 +335,6 @@ class DefaultZLinkFanoutPublishCall {
         this.executed = true;
         (0, abort_1.throwIfAborted)(signal);
         const result = await this.submitter(signal);
-        (0, submission_result_1.requireOneWayCompletion)(result, 'Classic fanout publish');
+        (0, submission_result_1.requireClassicFanoutCompletion)(result, 'Classic fanout publish');
     }
 }

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.d.ts

@@ -43,7 +43,7 @@ export declare function encodeChannelEnvelopeParts(kind: ZLinkChannelMessageKind
  * entry point for operations that must not extend their original deadline
  * while the message is being serialized.
  */
-export declare function encodeChannelEnvelopePartsAtDeadline(kind: ZLinkChannelMessageKind, channelName: string, packetName: string | undefined, payload: unknown, deadlineUnixMs: number, topic?: string, codecs?: ZLinkChannelEnvelopeCodecRegistry, correlationId?: string, createFlow?: boolean, metadata?: ReadonlyMap<string, string>): readonly MessageLike[];
+export declare function encodeChannelEnvelopePartsAtDeadline(kind: ZLinkChannelMessageKind, channelName: string, packetName: string | undefined, payload: unknown, deadlineUnixMs: number | undefined, topic?: string, codecs?: ZLinkChannelEnvelopeCodecRegistry, correlationId?: string, createFlow?: boolean, metadata?: ReadonlyMap<string, string>): readonly MessageLike[];
 export declare function encodeChannelPublishEnvelopeParts(channelName: string, topic: string, packetName: string | undefined, payload: unknown, codecs?: ZLinkChannelEnvelopeCodecRegistry, createFlow?: boolean, metadata?: ReadonlyMap<string, string>): readonly MessageLike[];
 export declare function encodeChannelReplyParts(request: ZLinkChannelEnvelopeHeader, payload: unknown, codecs?: ZLinkChannelEnvelopeCodecRegistry): readonly MessageLike[];
 /**

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;
@@ -36,14 +38,7 @@ function newChannelCorrelationId() {
     return (0, node_crypto_1.randomUUID)().replaceAll('-', '');
 }
 function encodeChannelEnvelopeParts(kind, channelName, packetName, payload, timeoutMs, topic, codecs, correlationId, createFlow = true, metadata = EMPTY_OUTBOUND_METADATA) {
-    const messageName = (0, packet_name_1.resolveFrameworkPacketName)(payload, packetName, 'Channel');
-    const encoded = encodePayload(payload, (0, channel_framework_packets_1.codecsForFrameworkPacket)(messageName, codecs), messageName, 'payload');
-    const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
-    const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
-    return [
-        encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, timeoutMs === undefined ? null : new Date(Date.now() + timeoutMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin),
-        encoded.message
-    ];
+    return encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, payload, timeoutMs === undefined ? undefined : Date.now() + timeoutMs, topic, codecs, correlationId, createFlow, metadata);
 }
 /**
  * Encodes an outbound channel envelope with a deadline that was established
@@ -52,7 +47,8 @@ function encodeChannelEnvelopeParts(kind, channelName, packetName, payload, time
  * while the message is being serialized.
  */
 function encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, payload, deadlineUnixMs, topic, codecs, correlationId, createFlow = true, metadata = EMPTY_OUTBOUND_METADATA) {
-    if (!Number.isSafeInteger(deadlineUnixMs) || deadlineUnixMs <= 0) {
+    if (deadlineUnixMs !== undefined &&
+        (!Number.isSafeInteger(deadlineUnixMs) || deadlineUnixMs <= 0)) {
         throw new RangeError('deadlineUnixMs must be a positive safe integer.');
     }
     const messageName = (0, packet_name_1.resolveFrameworkPacketName)(payload, packetName, 'Channel');
@@ -60,7 +56,7 @@ function encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, pay
     const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
     const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
     return [
-        encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, new Date(deadlineUnixMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin),
+        encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin),
         encoded.message
     ];
 }
@@ -314,7 +310,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 +336,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 +438,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 +703,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';
@@ -9,7 +10,7 @@ export declare class ZLinkChannelOutboundOperations {
     private readonly pendingRequests;
     constructor(sockets: ZLinkChannelSocketRegistry, codecs: ZLinkChannelEnvelopeCodecRegistry, dispatchServices: ZLinkChannelDispatchServices);
     pendingRequestCount(channelName: string): number;
-    send(channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    send(channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private sendScoped;
     private traceSend;
     request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
@@ -18,7 +19,7 @@ export declare class ZLinkChannelOutboundOperations {
     private tryPublishScoped;
     publish(channelName: string, topic: string, packetName: string | undefined, event: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private publishScoped;
-    routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private routeSubmitScoped;
     private traceRouteSend;
     routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
@@ -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;