@zlink-systems/framework 0.26.0 → 0.28.0

package/src/runtime/backend/node/node-socket-backend-adapter.ts

@@ -1,3 +1,4 @@
+import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../../contracts/Configuration/RegistrationBuilderPolicy';
 import type { Socket } from '@zlink-systems/zlink';
 import type { ZLinkBackendObject } from '../contracts';
 import {
@@ -114,7 +115,7 @@ export function wrapSocket<T extends { close(): void }>(
       );
     },
     get peerWeight(): number {
-      return socket.options?.peerWeight ?? 100;
+      return socket.options?.peerWeight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT;
     },
     set peerWeight(value: number) {
       requireSocketOptions(socket).peerWeight = value;
@@ -193,7 +194,7 @@ export function wrapSocket<T extends { close(): void }>(
       }
       return submitBindingAsyncSend(operation, payload);
     },
-    submit(routingId: unknown, payload: unknown, _timeoutMs?: number): Promise<void> {
+    submit(routingId: unknown, payload: unknown): Promise<void> {
       if (!hasStream) throw new TypeError('Async stream send requires a STREAM socket.');
       return submitBindingAsyncSend(
         (nativeInstance as T & { send(routingId: unknown): ZLinkBindingAsyncSendOperation }).send(
@@ -381,7 +382,7 @@ export function isEndpointCloseIgnorableError(error: unknown): boolean {
     isContextTerminatedError(error) ||
     (error instanceof Error &&
       'code' in error &&
-      ((error as { code: unknown }).code === 604 ||
+      ((error as { code: unknown }).code === zlink.ConnectResult.InternalError ||
         (error as { code: unknown }).code === zlink.ConnectResult.NotFound))
   );
 }

package/src/runtime/backend/raw-binding-port.ts

@@ -26,7 +26,7 @@ export interface ZLinkRawMonitorRecord {
 }
 
 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/src/runtime/backend/runtime-values.ts

@@ -46,11 +46,14 @@ export class ZLinkBackendResultError extends Error {
     readonly operation: 'request' | 'submit',
     readonly result: number,
     readonly nativeErrno?: number,
-    options?: ErrorOptions
+    options?: ErrorOptions & { readonly phase?: 'submit' | 'completion' }
   ) {
     super(`Backend ${operation} failed with result ${result}.`, options);
     this.name = 'ZLinkBackendResultError';
+    this.phase = options?.phase ?? 'completion';
   }
+
+  readonly phase: 'submit' | 'completion';
 }
 
 export function isZLinkBackendResultError(error: unknown): error is ZLinkBackendResultError {

package/src/runtime/channels/channel-clients.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import type {
   ZLinkChannelClient,
   ZLinkChannelRequestCall,
@@ -19,6 +20,7 @@ import {
 import {
   requireOneWayCompletion,
   requirePublishCompletion,
+  requireClassicFanoutCompletion,
   throwAlreadySubmitted,
   ZLinkSubmitStatus,
   type ZLinkSubmitResult
@@ -43,68 +45,76 @@ import {
 } from '../spots/spot-outbound';
 import { resolveFrameworkPacketName } from '../messaging/packet-name';
 
-export class DefaultZLinkChannelClient implements ZLinkChannelClient {
-  constructor(
-    private readonly registration: ZLinkFrameworkRegistration,
-    private readonly transport?: ZLinkChannelClientTransportSource
-  ) {}
+type RouteMeshChannelMatch = {
+  readonly meshName: string;
+  readonly mesh: NonNullable<ReturnType<ZLinkFrameworkRegistration['spotNodes']['get']>>;
+};
 
-  sendToChannel(channelName: string, message: unknown): ZLinkSendCall {
-    return new DefaultZLinkSendCall(
-      () => this.requireChannel(channelName),
-      async (packetName, metadata, signal) =>
-        normalizeSubmitResult(
-          await this.requireTransport().send(channelName, packetName, message, signal, metadata)
-        )
-    );
-  }
+type ChannelRouteResolution =
+  | {
+      readonly kind: 'client-server';
+      readonly channel: NonNullable<ReturnType<ZLinkFrameworkRegistration['channels']['get']>>;
+    }
+  | { readonly kind: 'route-mesh'; readonly matches: readonly RouteMeshChannelMatch[] };
+
+type ResolvedChannelRoute =
+  | Extract<ChannelRouteResolution, { readonly kind: 'client-server' }>
+  | {
+      readonly kind: 'route-mesh';
+      readonly meshName: string;
+      readonly mesh: RouteMeshChannelMatch['mesh'];
+    };
+
+export function resolveChannelRoute(
+  registration: ZLinkFrameworkRegistration,
+  channelName: string
+): ChannelRouteResolution | undefined {
+  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 };
+}
 
-  requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall {
-    return new DefaultZLinkRequestCall(
-      () => this.requireChannel(channelName),
-      (packetName, timeoutMs, metadata, signal) =>
-        this.requireTransport().request(
-          channelName,
-          packetName,
-          request,
-          timeoutMs,
-          signal,
-          metadata
-        ),
-      this.defaultRequestTimeout(channelName)
-    );
+export function requireUniqueRouteMeshChannel(
+  matches: readonly RouteMeshChannelMatch[],
+  duplicateMessage: string
+): RouteMeshChannelMatch {
+  if (matches.length !== 1) {
+    throw new ZLinkConfigurationException(duplicateMessage);
   }
+  return matches[0]!;
+}
 
-  private defaultRequestTimeout(channelName: string): number {
-    return (
-      this.registration.channels.get(channelName)?.requestTimeoutMs ??
-      this.registration.requestTimeoutMs ??
-      30_000
+export class DefaultZLinkChannelClient implements ZLinkChannelClient {
+  private readonly routeClient: DefaultZLinkRouteClient;
+
+  constructor(
+    registration: ZLinkFrameworkRegistration,
+    channelTransport?: ZLinkChannelClientTransportSource,
+    routeTransport?: ZLinkRouteClientTransport,
+    spotRouterChannelIdForMesh: (meshName: string) => string = (meshName) => meshName
+  ) {
+    this.routeClient = new DefaultZLinkRouteClient(
+      registration,
+      routeTransport,
+      spotRouterChannelIdForMesh,
+      channelTransport
     );
   }
 
-  private requireChannel(channelName: string): void {
-    const channel = this.registration.channels.get(channelName);
-    if (channel === undefined) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-        `Channel client '${channelName}' is not registered.`
-      );
-    }
-    if (channel.client === undefined) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.InvalidConfiguration,
-        `Channel client role '${channelName}' is not configured.`
-      );
-    }
+  sendToChannel(channelName: string, message: unknown): ZLinkSendCall {
+    return this.routeClient.sendToChannel(channelName, message);
   }
 
-  private requireTransport(): ZLinkChannelClientTransport {
-    const transport = typeof this.transport === 'function' ? this.transport() : this.transport;
-    if (transport === undefined) {
-      throw new ZLinkConfigurationException('Channel runtime is not started.');
-    }
-    return transport;
+  requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall {
+    return this.routeClient.requestToChannel(channelName, request);
   }
 }
 
@@ -160,20 +170,20 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
     private readonly registration: ZLinkFrameworkRegistration,
     private readonly transport?: ZLinkRouteClientTransport,
     private readonly spotRouterChannelIdForMesh: (meshName: string) => string = (meshName) =>
-      meshName
+      meshName,
+    private readonly channelTransport?: ZLinkChannelClientTransportSource
   ) {}
 
   sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall {
     return new DefaultZLinkSendCall(
       () => this.requireMesh(meshName),
-      async (packetName, metadata, signal) =>
+      async (packetName, metadata) =>
         normalizeSubmitResult(
           await this.requireTransport().submit(
             meshName,
             targetNodeRid,
             packetName,
             message,
-            signal,
             metadata
           )
         )
@@ -199,20 +209,22 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
 
   sendToChannel(channelName: string, message: unknown): ZLinkSendCall {
     return new DefaultZLinkSendCall(
-      () => {
-        this.resolveMeshChannel(channelName);
-      },
-      async (packetName, metadata, signal) => {
-        const meshName = this.resolveMeshChannel(channelName);
+      () => 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.requireTransport().submitToChannel(
-            meshName,
-            channelName,
-            packetName,
-            message,
-            signal,
-            metadata
-          )
+          await this.requireChannelTransport().send(channelName, packetName, message, metadata)
         );
       }
     );
@@ -220,13 +232,21 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
 
   requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall {
     return new DefaultZLinkRequestCall(
-      () => {
-        this.resolveMeshChannel(channelName);
-      },
+      () => this.requireChannelRoute(channelName),
       (packetName, timeoutMs, metadata, signal) => {
-        const meshName = this.resolveMeshChannel(channelName);
-        return this.requireTransport().requestToChannel(
-          meshName,
+        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,
@@ -244,9 +264,8 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
       () => {
         this.requireSpotTransport();
       },
-      async (_packetName, metadata, signal) => {
+      async (_packetName, metadata) => {
         await sendToSpotHandle(this.requireSpotTransport(), spot, message, {
-          signal,
           metadata,
           spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
         });
@@ -267,7 +286,7 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
           metadata,
           spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
         }),
-      this.registration.requestTimeoutMs ?? 30_000
+      this.registration.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
     );
   }
 
@@ -276,7 +295,7 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
       this.registration.spotNodes.get(meshName)?.requestTimeoutMs ??
       this.registration.routeChannelOptions.get(meshName)?.requestTimeoutMs ??
       this.registration.requestTimeoutMs ??
-      30_000
+      DEFAULT_REQUEST_TIMEOUT_MS
     );
   }
 
@@ -289,31 +308,42 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
     }
   }
 
-  private resolveMeshChannel(channelName: string): string {
-    const matches = [...this.registration.spotNodes.entries()]
-      .filter(([, mesh]) =>
-        Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName)
-      )
-      .map(([meshName]) => meshName);
-    if (matches.length === 0) {
+  private requireChannelRoute(channelName: string): ResolvedChannelRoute {
+    const resolution = resolveChannelRoute(this.registration, channelName);
+    if (resolution === undefined) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.RequestTargetNotFound,
-        `RouteMesh channel '${channelName}' is not registered.`
+        `ChannelName '${channelName}' is not registered.`
       );
     }
-    if (matches.length !== 1) {
-      throw new ZLinkConfigurationException(
-        `RouteMesh channel '${channelName}' must be unique across the Framework host.`
-      );
+    if (resolution.kind === 'client-server') {
+      if (resolution.channel.client === undefined) {
+        throw createInternalFrameworkException(
+          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.`
+      )
+    };
   }
 
   private defaultRequestTimeoutForChannel(channelName: string): number {
-    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 ?? DEFAULT_REQUEST_TIMEOUT_MS;
   }
 
   private requireTransport(): ZLinkRouteClientTransport {
@@ -323,6 +353,15 @@ export class DefaultZLinkRouteClient implements ZLinkRouteClient {
     return this.transport;
   }
 
+  private requireChannelTransport(): ZLinkChannelClientTransport {
+    const transport =
+      typeof this.channelTransport === 'function' ? this.channelTransport() : this.channelTransport;
+    if (transport === undefined) {
+      throw new ZLinkConfigurationException('Channel runtime is not started.');
+    }
+    return transport;
+  }
+
   private requireSpotTransport(): ZLinkSpotRoutedTransport {
     const transport = this.requireTransport();
     if (transport.sendToSpot === undefined || transport.requestToSpot === undefined) {
@@ -384,8 +423,7 @@ class DefaultZLinkSendCall implements ZLinkSendCall {
     private readonly validate: () => void,
     private readonly submitter: (
       packetName: string | undefined,
-      metadata: ReadonlyMap<string, string>,
-      signal?: AbortSignal
+      metadata: ReadonlyMap<string, string>
     ) => Promise<ZLinkSubmitResult>
   ) {}
 
@@ -403,12 +441,11 @@ class DefaultZLinkSendCall implements ZLinkSendCall {
     return this;
   }
 
-  async submit(signal?: AbortSignal): Promise<void> {
+  async submit(): Promise<void> {
     ensureNotExecuted(this.executed);
     this.validate();
     this.executed = true;
-    throwIfAborted(signal);
-    const result = await this.submitter(undefined, new Map(this.selectedMetadata), signal);
+    const result = await this.submitter(undefined, new Map(this.selectedMetadata));
     requireOneWayCompletion(result, 'One-way send');
   }
 }
@@ -533,6 +570,6 @@ class DefaultZLinkFanoutPublishCall implements ZLinkFanoutPublishCall {
     this.executed = true;
     throwIfAborted(signal);
     const result = await this.submitter(signal);
-    requireOneWayCompletion(result, 'Classic fanout publish');
+    requireClassicFanoutCompletion(result, 'Classic fanout publish');
   }
 }

package/src/runtime/channels/channel-envelope-inspection.ts

@@ -1,3 +1,4 @@
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkFlowOrigin } from '../../contracts';
 import {
@@ -80,7 +81,7 @@ export function malformedProtocolErrorRequestHeader(
     kind: ZLinkChannelMessageKind.Request,
     channelName,
     messageName: info.messageName ?? '',
-    contentType: 'application/json',
+    contentType: ZlinkStreamContentType.Json,
     correlationId: info.correlationId ?? null,
     deadline: null,
     topic: null,

package/src/runtime/channels/channel-envelope.ts

@@ -1,6 +1,7 @@
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import { randomUUID } from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
 import {
   ZLinkFrameworkErrorKind,
   ZLinkFrameworkException,
@@ -20,6 +21,7 @@ import { selectSerializerWithContentType } from '../messaging/payload-codec';
 import { isCanonicalCodecContentType } from '../../contracts/Configuration/CodecContentType';
 import { parseFrameworkJsonV1, stringifyFrameworkJsonV1 } from '../messaging/framework-json-v1';
 import { currentOrCreateFlow } from '../diagnostics/flow-context';
+import { SERVICE_WIRE_METADATA_BYTES } from '../foundation/service-wire-constants.generated';
 import { codecsForFrameworkPacket } from './channel-framework-packets';
 import { readZLinkPacketJsonContract } from '../../contracts/Handlers/Attributes';
 import type { ZLinkJsonSchema } from '../../contracts/Handlers/JsonContract';
@@ -84,33 +86,18 @@ export function encodeChannelEnvelopeParts(
   createFlow = true,
   metadata: ReadonlyMap<string, string> = EMPTY_OUTBOUND_METADATA
 ): readonly MessageLike[] {
-  const messageName = resolveFrameworkPacketName(payload, packetName, 'Channel');
-  const encoded = encodePayload(
+  return encodeChannelEnvelopePartsAtDeadline(
+    kind,
+    channelName,
+    packetName,
     payload,
-    codecsForFrameworkPacket(messageName, codecs),
-    messageName,
-    'payload'
+    timeoutMs === undefined ? undefined : Date.now() + timeoutMs,
+    topic,
+    codecs,
+    correlationId,
+    createFlow,
+    metadata
   );
-  const flow = createFlow ? 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
-  ];
 }
 
 /**
@@ -124,14 +111,17 @@ export function encodeChannelEnvelopePartsAtDeadline(
   channelName: string,
   packetName: string | undefined,
   payload: unknown,
-  deadlineUnixMs: number,
+  deadlineUnixMs: number | undefined,
   topic?: string,
   codecs?: ZLinkChannelEnvelopeCodecRegistry,
   correlationId?: string,
   createFlow = true,
   metadata: ReadonlyMap<string, string> = EMPTY_OUTBOUND_METADATA
 ): readonly MessageLike[] {
-  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 = resolveFrameworkPacketName(payload, packetName, 'Channel');
@@ -150,7 +140,7 @@ export function encodeChannelEnvelopePartsAtDeadline(
       messageName,
       encoded.contentType,
       envelopeCorrelationId,
-      new Date(deadlineUnixMs).toISOString(),
+      deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(),
       topic ?? null,
       null,
       null,
@@ -614,7 +604,24 @@ function writeChannelHeader(
     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: ChannelHeaderWriter,
+  metadata: Readonly<Record<string, string>>
+): void {
+  writer.append('{');
   let first = true;
   for (const name in metadata) {
     if (!Object.prototype.hasOwnProperty.call(metadata, name)) continue;
@@ -625,15 +632,6 @@ function writeChannelHeader(
     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 {
@@ -744,14 +742,20 @@ function parseWireJson(payload: string, schema?: ZLinkJsonSchema): unknown {
 }
 
 function parseChannelHeaderBytes(payload: Buffer): unknown {
-  return tryParseCanonicalChannelHeader(payload) ?? parseWireJson(payload.toString());
+  if (!isUtf8(payload)) {
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.ProtocolError,
+      'Channel envelope header must contain valid UTF-8.'
+    );
+  }
+  return tryParseCanonicalChannelHeader(payload) ?? 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: Buffer): Record<string, unknown> | undefined {
   const reader = new CanonicalChannelHeaderReader(payload);
@@ -1019,38 +1023,51 @@ const EMPTY_APPLICATION_METADATA: Readonly<Record<string, string>> = Object.free
 function applicationMetadataRecord(
   metadata: ReadonlyMap<string, string>
 ): Readonly<Record<string, string>> {
-  //  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: Record<string, string> = {};
-  for (const [key, value] of metadata) {
-    if (key.length === 0 || key.includes('\0') || value.includes('\0')) {
+  const record: Record<string, string> = Object.create(null) as Record<string, string>;
+  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: Record<string, unknown>
+): Readonly<Record<string, string>> {
+  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 ZLinkConfigurationException(
-        'Channel application metadata keys must be non-empty and keys and values must not contain NUL.'
+        'Channel application metadata keys must be non-empty and keys and values must be valid Unicode without NUL.'
       );
     }
-    record[key] = value;
   }
-  if (Buffer.byteLength(JSON.stringify(record), 'utf8') > 1024) {
+  const record = metadata as Record<string, string>;
+  const writer = new ChannelHeaderWriter();
+  writeApplicationMetadata(writer, record);
+  if (writer.byteLength > SERVICE_WIRE_METADATA_BYTES) {
     throw new ZLinkConfigurationException(
-      'Channel application metadata exceeds the 1024-byte limit.'
+      `Channel application metadata exceeds the ${SERVICE_WIRE_METADATA_BYTES}-byte limit.`
     );
   }
   return Object.freeze(record);
 }
 
 function requireApplicationMetadata(value: unknown): Readonly<Record<string, string>> {
-  if (value === undefined) {
-    return Object.freeze({});
-  }
+  if (value === undefined) return EMPTY_APPLICATION_METADATA;
   if (!isRecord(value)) {
     throw new ZLinkConfigurationException('Channel application metadata must be a JSON object.');
   }
-  const metadata = new Map<string, string>();
-  for (const [key, selectedValue] of Object.entries(value)) {
-    metadata.set(key, requireString(selectedValue, `metadata.${key}`));
-  }
-  return applicationMetadataRecord(metadata);
+  return validateApplicationMetadata(value);
 }
 
 function optionalFlowId(value: unknown): string | undefined {