@zlink-systems/framework 0.30.3 → 0.32.0

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

@@ -1,16 +1,20 @@
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkBufferMessage } from '../backend/runtime-message';
 import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import { randomBytes } from 'node:crypto';
 import { isUtf8 } from 'node:buffer';
 import {
+  type Type,
   ZLinkFrameworkErrorKind,
   ZLinkFrameworkException,
   type ZLinkMessageSerializer,
   type ZLinkFlowOrigin
 } from '../../contracts';
 import { borrowEncodedPayload } from '../../contracts/Common/encoded-payload-storage';
-import { isZLinkMessage, readZLinkMessageDeclaredType } from '../../contracts/Common/ZLinkMessage';
+import {
+  isZLinkMessage,
+  materializeZLinkMessageValue,
+  readZLinkMessageDeclaredType
+} from '../../contracts/Common/ZLinkMessage';
 import { ZLinkConfigurationException } from '../configuration';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -98,7 +102,7 @@ const CHANNEL_CORRELATION_TEXT = /^[0-9a-f]{32}$/;
 const CHANNEL_FLOW_FIELD = ',"flowId":';
 // A flow id is a lowercase UUIDv7 (spec 27 §3): fixed 36 JSON-safe ASCII bytes.
 const PREPARED_CHANNEL_FLOW = '00000000-0000-7000-8000-000000000000';
-const CHANNEL_FLOW_TEXT = /^[0-9a-f-]{36}$/;
+const CHANNEL_FLOW_TEXT = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
 
 // A per-process random 64-bit prefix followed by a per-process counter, both
 // as lowercase hex: unique among the runtime's pending requests (spec 06-obs/04
@@ -109,9 +113,11 @@ let channelCorrelationCounter = 0;
 
 export function newChannelCorrelationId(): string {
   channelCorrelationCounter += 1;
+  const suffix = channelCorrelationCounter.toString(16);
   return (
     CHANNEL_CORRELATION_PREFIX +
-    channelCorrelationCounter.toString(16).padStart(CHANNEL_CORRELATION_TEXT_LENGTH / 2, '0')
+    PREPARED_CHANNEL_CORRELATION.slice(suffix.length, CHANNEL_CORRELATION_TEXT_LENGTH / 2) +
+    suffix
   );
 }
 
@@ -166,33 +172,21 @@ export function encodeChannelEnvelopePartsAtDeadline(
     throw new RangeError('deadlineUnixMs must be a positive safe integer.');
   }
   const messageName = resolveFrameworkPacketName(payload, packetName, 'Channel');
-  const encoded = encodePayload(
+  return encodePayload(
     payload,
     codecsForFrameworkPacket(messageName, codecs),
     messageName,
-    'payload'
+    'payload',
+    kind,
+    channelName,
+    correlationId,
+    deadlineUnixMs,
+    topic,
+    createFlow,
+    metadata,
+    undefined,
+    codecs
   );
-  const flow = createFlow ? currentOrCreateFlow('Application') : undefined;
-  const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
-  return [
-    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,
-      codecs
-    ),
-    encoded.message
-  ];
 }
 
 export function encodeChannelPublishEnvelopeParts(
@@ -205,31 +199,19 @@ export function encodeChannelPublishEnvelopeParts(
   metadata: ReadonlyMap<string, string> = EMPTY_OUTBOUND_METADATA
 ): readonly MessageLike[] {
   const messageName = resolveFrameworkPacketName(payload, packetName, 'Channel');
-  const encoded = encodePayload(
+  return encodePayload(
     payload,
     codecsForFrameworkPacket(messageName, codecs),
     messageName,
-    'payload'
+    'payload',
+    ZLinkChannelMessageKind.Publish,
+    channelName,
+    undefined,
+    undefined,
+    topic,
+    createFlow,
+    metadata
   );
-  const flow = createFlow ? currentOrCreateFlow('Application') : undefined;
-  return [
-    encodeChannelHeader(
-      ZLinkChannelMessageKind.Publish,
-      channelName,
-      messageName,
-      encoded.contentType,
-      null,
-      null,
-      topic,
-      null,
-      null,
-      undefined,
-      applicationMetadataRecord(metadata),
-      flow?.flowId,
-      flow?.flowOrigin
-    ),
-    encoded.message
-  ];
 }
 
 export function encodeChannelReplyParts(
@@ -237,31 +219,21 @@ export function encodeChannelReplyParts(
   payload: unknown,
   codecs?: ZLinkChannelEnvelopeCodecRegistry
 ): readonly MessageLike[] {
-  const encoded = encodePayload(
+  return encodePayload(
     payload ?? Buffer.alloc(0),
     codecsForFrameworkPacket(request.messageName, codecs),
     request.messageName,
-    'reply'
+    'reply',
+    ZLinkChannelMessageKind.Response,
+    request.channelName,
+    request.correlationId ?? undefined,
+    undefined,
+    undefined,
+    false,
+    EMPTY_OUTBOUND_METADATA,
+    request,
+    codecs
   );
-  return [
-    encodeChannelHeader(
-      ZLinkChannelMessageKind.Response,
-      request.channelName,
-      request.messageName,
-      encoded.contentType,
-      request.correlationId,
-      null,
-      null,
-      undefined,
-      undefined,
-      undefined,
-      EMPTY_APPLICATION_METADATA,
-      request.flowId,
-      request.flowOrigin,
-      codecs
-    ),
-    encoded.message
-  ];
 }
 
 /**
@@ -342,7 +314,7 @@ export function encodeChannelErrorReplyParts(
       request.flowId,
       request.flowOrigin
     ),
-    encodeJsonBytes(null)
+    encodeJsonText(null)
   ];
 }
 
@@ -368,20 +340,18 @@ export function decodeChannelReply<TReply>(
   ) {
     throw unsupportedChannelContentType(header.contentType);
   }
-  if (parts.length < 2 || parts[1].data().length === 0) {
+  const body = parts.length < 2 ? undefined : parts[1].data();
+  if (body === undefined || body.length === 0) {
     return undefined as TReply;
   }
   if (header.contentType === BINARY_CONTENT_TYPE) {
-    return ZLinkBufferMessage.retainPayload(parts[1]) as TReply;
+    return body as TReply;
   }
   if (serializer !== undefined) {
-    return serializer.deserialize<TReply>(
-      encodedPayloadFromOwned(parts[1].data()),
-      Object as never
-    );
+    return serializer.deserialize<TReply>(encodedPayloadFromOwned(body), Object as never);
   }
   return parseWireJson(
-    parts[1].data().toString(),
+    body.toString(),
     readZLinkPacketJsonContract(header.messageName)?.reply
   ) as TReply;
 }
@@ -442,7 +412,8 @@ export function decodeChannelEnvelope(
 
 export function decodeChannelPayload(
   envelope: ZLinkChannelEnvelope,
-  codecs?: ZLinkChannelEnvelopeCodecRegistry
+  codecs?: ZLinkChannelEnvelopeCodecRegistry,
+  messageType?: Type
 ): unknown {
   try {
     if (!isCanonicalCodecContentType(envelope.header.contentType)) {
@@ -450,7 +421,10 @@ export function decodeChannelPayload(
     }
     const serializer = codecs?.serializers.get(envelope.header.contentType);
     if (serializer !== undefined) {
-      return serializer.deserialize(encodedPayloadFromOwned(envelope.payload), Object as never);
+      return serializer.deserialize(
+        encodedPayloadFromOwned(envelope.payload),
+        (messageType ?? Object) as never
+      );
     }
     if (envelope.header.contentType === BINARY_CONTENT_TYPE) {
       // The receive loop owns the Message for the duration of dispatch, so
@@ -458,9 +432,12 @@ export function decodeChannelPayload(
       return envelope.payload;
     }
     if (envelope.header.contentType === JSON_CONTENT_TYPE) {
-      return parseWireJson(
-        envelope.payload.toString(),
-        schemaForInboundChannelEnvelope(envelope.header)
+      return materializeZLinkMessageValue(
+        parseWireJson(
+          envelope.payload.toString(),
+          schemaForInboundChannelEnvelope(envelope.header)
+        ),
+        messageType
       );
     }
     throw unsupportedChannelContentType(envelope.header.contentType);
@@ -495,42 +472,71 @@ function encodePayload(
   value: unknown,
   codecs: ZLinkChannelEnvelopeCodecRegistry | undefined,
   packetName: string,
-  contractPart: 'payload' | 'reply'
-): {
-  readonly contentType: string;
-  readonly message: MessageLike;
-} {
+  contractPart: 'payload' | 'reply',
+  kind: ZLinkChannelMessageKind,
+  channelName: string,
+  correlationId: string | undefined,
+  deadlineUnixMs: number | undefined,
+  topic: string | undefined,
+  createFlow: boolean,
+  metadata: ReadonlyMap<string, string>,
+  request?: ZLinkChannelEnvelopeHeader,
+  headerCodecs?: ZLinkChannelEnvelopeCodecRegistry
+): readonly MessageLike[] {
+  let declaredType;
+  let contentType: string;
+  let message: MessageLike;
   if (isZLinkMessage(value) && value.isEncoded()) {
     const payload = value.toEncodedPayload();
-    return {
-      contentType: BINARY_CONTENT_TYPE,
-      message: borrowEncodedPayload(payload) ?? payload.data()
-    };
-  }
-  const declaredType = isZLinkMessage(value) ? readZLinkMessageDeclaredType(value) : undefined;
-  if (isZLinkMessage(value)) value = value.decode();
-  const selected = selectSerializerWithContentType(value, codecs, declaredType);
-  if (
-    selected !== undefined &&
-    !(Buffer.isBuffer(value) || value instanceof Uint8Array || isMessage(value))
-  ) {
-    const payload = selected.serializer.serialize(value);
-    return {
-      contentType: selected.contentType,
-      message: borrowEncodedPayload(payload) ?? payload.data()
-    };
+    contentType = BINARY_CONTENT_TYPE;
+    message = borrowEncodedPayload(payload) ?? payload.data();
+  } else {
+    if (isZLinkMessage(value)) {
+      declaredType = readZLinkMessageDeclaredType(value);
+      value = value.decode();
+    }
+    const selected = selectSerializerWithContentType(value, codecs, declaredType);
+    if (
+      selected !== undefined &&
+      !(Buffer.isBuffer(value) || value instanceof Uint8Array || isMessage(value))
+    ) {
+      const payload = selected.serializer.serialize(value);
+      contentType = selected.contentType;
+      message = borrowEncodedPayload(payload) ?? payload.data();
+    } else {
+      contentType = contentTypeOf(value);
+      message = toMessageLike(value, readZLinkPacketJsonContract(packetName)?.[contractPart]);
+    }
   }
-  return {
-    contentType: contentTypeOf(value),
-    message: toMessageLike(value, readZLinkPacketJsonContract(packetName)?.[contractPart])
-  };
+  const flow = request ?? (createFlow ? currentOrCreateFlow('Application') : undefined);
+  return [
+    encodeChannelHeader(
+      kind,
+      channelName,
+      packetName,
+      contentType,
+      request === undefined
+        ? correlationIdForOutboundKind(kind, correlationId)
+        : request.correlationId,
+      deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(),
+      topic ?? null,
+      contractPart === 'reply' ? undefined : null,
+      contractPart === 'reply' ? undefined : null,
+      undefined,
+      applicationMetadataRecord(metadata),
+      flow?.flowId,
+      flow?.flowOrigin,
+      headerCodecs
+    ),
+    message
+  ];
 }
 
 function toMessageLike(value: unknown, schema?: ZLinkJsonSchema): MessageLike {
   if (Buffer.isBuffer(value) || value instanceof Uint8Array || isMessage(value)) {
     return value;
   }
-  return encodeJsonBytes(value, schema);
+  return encodeJsonText(value, schema);
 }
 
 function contentTypeOf(value: unknown): string {
@@ -547,8 +553,8 @@ function isMessage(value: unknown): value is Message {
   );
 }
 
-function encodeJsonBytes(value: unknown, schema?: ZLinkJsonSchema): Buffer {
-  return Buffer.from(stringifyFrameworkJsonV1(value, schema));
+function encodeJsonText(value: unknown, schema?: ZLinkJsonSchema): string {
+  return stringifyFrameworkJsonV1(value, schema);
 }
 
 function encodeChannelHeader(
@@ -887,44 +893,77 @@ export function decodeChannelHeader(
   if (parts.length === 0) {
     throw new ZLinkConfigurationException('Channel envelope header part is missing.');
   }
-  return validateChannelHeader(parseChannelHeaderBytes(parts[0].data()), flowEnabled);
+  return validateChannelHeader(parseChannelHeaderBytes(parts[0].data(), flowEnabled), flowEnabled);
 }
 
+const CHANNEL_JSON_PARSE_OPTIONS = Object.freeze({ rejectPropertyName: isPrototypeKey });
+
 function parseWireJson(payload: string, schema?: ZLinkJsonSchema): unknown {
-  return parseFrameworkJsonV1(
-    payload,
-    {
-      rejectPropertyName: isPrototypeKey
-    },
-    schema
-  );
+  return parseFrameworkJsonV1(payload, CHANNEL_JSON_PARSE_OPTIONS, schema);
 }
 
-function parseChannelHeaderBytes(payload: Buffer): unknown {
-  const reader = new CanonicalChannelHeaderReader(payload);
-  const canonical = tryParseCanonicalChannelHeader(reader);
-  // An all-ASCII canonical header is valid UTF-8 by construction; any other
-  // header is checked before it is decoded.
-  if (canonical !== undefined && !reader.sawNonAscii) return canonical;
+const CHANNEL_HEADER_FIELD_NAMES = [
+  '',
+  'formatMarker',
+  'kind',
+  'channelName',
+  'messageName',
+  'contentType',
+  'correlationId',
+  'deadline',
+  'topic',
+  'errorCode',
+  'errorMessage',
+  'source',
+  'flowId',
+  'flowOrigin',
+  'metadata'
+] as const;
+const CHANNEL_HEADER_FIELD_COUNT = CHANNEL_HEADER_FIELD_NAMES.length - 1;
+const CHANNEL_HEADER_INVALID_VALUE = Symbol('invalid channel header value');
+const CANONICAL_CHANNEL_HEADER_PREFIX = '{"formatMarker":242,"kind":';
+
+function parseChannelHeaderBytes(payload: Buffer, flowEnabled: boolean): unknown {
+  if (startsWithJson(payload, CANONICAL_CHANNEL_HEADER_PREFIX)) {
+    const reader = new CanonicalChannelHeaderReader(
+      payload,
+      CANONICAL_CHANNEL_HEADER_PREFIX.length
+    );
+    const canonical = tryParseCanonicalChannelHeader(reader, flowEnabled);
+    // Canonical ASCII headers need no UTF-8 pass; all other paths are checked
+    // before byte slices are decoded.
+    if (canonical !== undefined && !reader.sawNonAscii) return canonical;
+    if (canonical !== undefined) {
+      if (!isUtf8(payload)) {
+        throw new ZLinkFrameworkException(
+          ZLinkFrameworkErrorKind.ProtocolError,
+          'Channel envelope header must contain valid UTF-8.'
+        );
+      }
+      return canonical;
+    }
+  }
   if (!isUtf8(payload)) {
     throw new ZLinkFrameworkException(
       ZLinkFrameworkErrorKind.ProtocolError,
       'Channel envelope header must contain valid UTF-8.'
     );
   }
-  return canonical ?? parseFrameworkJsonV1(payload.toString());
+  return new ChannelHeaderJsonReader(payload, flowEnabled).parse();
+}
+
+function startsWithJson(bytes: Buffer, value: string): boolean {
+  if (bytes.length < value.length) return false;
+  for (let index = 0; index < value.length; index += 1) {
+    if (bytes[index] !== value.charCodeAt(index)) return false;
+  }
+  return true;
 }
 
-/**
- * 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 and unknown properties. Header metadata accepts every valid string key.
- */
 function tryParseCanonicalChannelHeader(
-  reader: CanonicalChannelHeaderReader
+  reader: CanonicalChannelHeaderReader,
+  flowEnabled: boolean
 ): Record<string, unknown> | undefined {
-  if (!reader.consume('{"formatMarker":242,"kind":')) return undefined;
   const kind = reader.readSingleDigit();
   if (kind === undefined || !reader.consume(',"channelName":')) return undefined;
   const channelName = reader.readString();
@@ -948,16 +987,25 @@ function tryParseCanonicalChannelHeader(
     contentType,
     correlationId: correlationId === NULL_JSON_STRING ? null : correlationId,
     deadline: deadline === NULL_JSON_STRING ? null : deadline,
-    topic: topic === NULL_JSON_STRING ? null : topic
+    topic: topic === NULL_JSON_STRING ? null : topic,
+    errorCode: null,
+    errorMessage: null,
+    source: undefined,
+    metadata: undefined,
+    flowId: undefined,
+    flowOrigin: undefined
   };
   if (!reader.readOptionalNullableString(CANONICAL_ERROR_CODE, 'errorCode', header))
     return undefined;
   if (!reader.readOptionalNullableString(CANONICAL_ERROR_MESSAGE, 'errorMessage', header))
     return undefined;
   if (!reader.readOptionalNullableString(CANONICAL_SOURCE, 'source', header)) return undefined;
+  const metadata = reader.readMetadata();
+  if (metadata === undefined) return undefined;
   // Empty metadata validates to the shared empty record.
-  if (!reader.consume(',"metadata":{}')) return undefined;
-  if (!reader.readOptionalString(CANONICAL_FLOW_ID, 'flowId', header)) return undefined;
+  if (metadata !== NULL_JSON_STRING) header.metadata = metadata;
+  if (!reader.readOptionalString(CANONICAL_FLOW_ID, 'flowId', header, flowEnabled))
+    return undefined;
   if (!reader.readOptionalSingleDigit(CANONICAL_FLOW_ORIGIN, 'flowOrigin', header))
     return undefined;
   return reader.consume('}') && reader.atEnd() ? header : undefined;
@@ -976,7 +1024,12 @@ class CanonicalChannelHeaderReader {
   /** A string held a byte outside ASCII, so the caller must still check UTF-8. */
   sawNonAscii = false;
 
-  constructor(private readonly bytes: Buffer) {}
+  constructor(
+    private readonly bytes: Buffer,
+    initialIndex = 0
+  ) {
+    this.index = initialIndex;
+  }
 
   atEnd(): boolean {
     return this.index === this.bytes.length;
@@ -1045,6 +1098,37 @@ class CanonicalChannelHeaderReader {
     return this.readString();
   }
 
+  readMetadata(): Record<string, unknown> | symbol | undefined {
+    if (!this.consume(',"metadata":{')) return undefined;
+    if (this.consume('}')) return NULL_JSON_STRING;
+    const metadata: Record<string, unknown> = {};
+    for (;;) {
+      const key = this.readString();
+      if (key === undefined) return undefined;
+      if (Object.prototype.hasOwnProperty.call(metadata, key)) {
+        throw new ZLinkFrameworkException(
+          ZLinkFrameworkErrorKind.ProtocolError,
+          'duplicate envelope metadata key'
+        );
+      }
+      if (!this.consume(':')) return undefined;
+      const value = this.readString();
+      if (value === undefined) return undefined;
+      if (key === '__proto__') {
+        Object.defineProperty(metadata, key, {
+          configurable: true,
+          enumerable: true,
+          value,
+          writable: true
+        });
+      } else {
+        metadata[key] = value;
+      }
+      if (this.consume('}')) return metadata;
+      if (!this.consume(',')) return undefined;
+    }
+  }
+
   readOptionalNullableString(
     token: string,
     name: string,
@@ -1057,14 +1141,53 @@ class CanonicalChannelHeaderReader {
     return true;
   }
 
-  readOptionalString(token: string, name: string, target: Record<string, unknown>): boolean {
+  readOptionalString(
+    token: string,
+    name: string,
+    target: Record<string, unknown>,
+    decode = true
+  ): boolean {
     if (!this.consume(token)) return true;
+    if (!decode) return this.skipString();
     const value = this.readString();
     if (value === undefined) return false;
     target[name] = value;
     return true;
   }
 
+  private skipString(): boolean {
+    if (this.bytes[this.index] !== 0x22) return false;
+    this.index += 1;
+    while (this.index < this.bytes.length) {
+      const value = this.bytes[this.index++]!;
+      if (value === 0x22) return true;
+      if (value < 0x20) return false;
+      if (value >= 0x80) this.sawNonAscii = true;
+      if (value !== 0x5c) continue;
+      if (this.index === this.bytes.length) return false;
+      const escaped = this.bytes[this.index++]!;
+      if (escaped === 0x75) {
+        for (let count = 0; count < 4; count += 1) {
+          if (this.index === this.bytes.length || !isHexDigit(this.bytes[this.index]!))
+            return false;
+          this.index += 1;
+        }
+      } else if (
+        escaped !== 0x22 &&
+        escaped !== 0x5c &&
+        escaped !== 0x2f &&
+        escaped !== 0x62 &&
+        escaped !== 0x66 &&
+        escaped !== 0x6e &&
+        escaped !== 0x72 &&
+        escaped !== 0x74
+      ) {
+        return false;
+      }
+    }
+    return false;
+  }
+
   readOptionalSingleDigit(token: string, name: string, target: Record<string, unknown>): boolean {
     if (!this.consume(token)) return true;
     const value = this.readSingleDigit();
@@ -1082,6 +1205,418 @@ function isHexDigit(value: number): boolean {
   );
 }
 
+/** Reads a noncanonical channel header directly from its UTF-8 bytes. */
+class ChannelHeaderJsonReader {
+  private index = 0;
+  private propertyName = '';
+  private stringStart = 0;
+  private stringEnd = 0;
+  private stringHasEscapes = false;
+
+  constructor(
+    private readonly bytes: Buffer,
+    private readonly flowEnabled: boolean
+  ) {}
+
+  parse(): unknown {
+    if (
+      this.bytes.length >= 3 &&
+      this.bytes[0] === 0xef &&
+      this.bytes[1] === 0xbb &&
+      this.bytes[2] === 0xbf
+    ) {
+      throw new SyntaxError('framework-json-v1 does not allow a UTF-8 BOM.');
+    }
+    this.skipWhitespace();
+    if (this.bytes[this.index] !== 0x7b) {
+      this.skipValue();
+      this.skipWhitespace();
+      if (this.index !== this.bytes.length) this.fail('trailing data');
+      return CHANNEL_HEADER_INVALID_VALUE;
+    }
+
+    const header: Record<string, unknown> = {};
+    let seenFields = 0;
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consumeByte(0x7d)) return this.finish(header);
+
+    for (;;) {
+      const field = this.readPropertyName(true);
+      const propertyName = this.propertyName;
+      this.skipWhitespace();
+      this.expectByte(0x3a, "':' after object property");
+      this.skipWhitespace();
+
+      if (field !== 0) {
+        const bit = 1 << field;
+        if ((seenFields & bit) !== 0) {
+          throw new ZLinkFrameworkException(
+            ZLinkFrameworkErrorKind.ProtocolError,
+            'duplicate envelope header field'
+          );
+        }
+        seenFields |= bit;
+        const name = CHANNEL_HEADER_FIELD_NAMES[field]!;
+        if (!this.flowEnabled && (field === 12 || field === 13)) {
+          this.skipValue();
+          header[name] = undefined;
+        } else if (field === 14) {
+          header[name] = this.readMetadata();
+        } else {
+          header[name] = this.readValue(field === 1 || field === 2 || field === 13);
+        }
+      } else {
+        const value = this.readValue();
+        if (propertyName === '__proto__') {
+          Object.defineProperty(header, propertyName, {
+            configurable: true,
+            enumerable: true,
+            value,
+            writable: true
+          });
+        } else {
+          header[propertyName] = value;
+        }
+      }
+
+      this.skipWhitespace();
+      if (this.consumeByte(0x7d)) break;
+      this.expectByte(0x2c, "',' or '}' after object property");
+      this.skipWhitespace();
+    }
+    return this.finish(header);
+  }
+
+  private finish(header: Record<string, unknown>): Record<string, unknown> {
+    this.skipWhitespace();
+    if (this.index !== this.bytes.length) this.fail('trailing data');
+    return header;
+  }
+
+  private readMetadata(): unknown {
+    if (this.bytes[this.index] !== 0x7b) return this.readValue();
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consumeByte(0x7d)) return undefined;
+    const metadata: Record<string, unknown> = {};
+
+    for (;;) {
+      const key = this.readString();
+      if (Object.prototype.hasOwnProperty.call(metadata, key)) {
+        throw new ZLinkFrameworkException(
+          ZLinkFrameworkErrorKind.ProtocolError,
+          'duplicate envelope metadata key'
+        );
+      }
+      this.skipWhitespace();
+      this.expectByte(0x3a, "':' after object property");
+      this.skipWhitespace();
+      const value = this.readValue();
+      if (key === '__proto__') {
+        Object.defineProperty(metadata, key, {
+          configurable: true,
+          enumerable: true,
+          value,
+          writable: true
+        });
+      } else {
+        metadata[key] = value;
+      }
+      this.skipWhitespace();
+      if (this.consumeByte(0x7d)) return metadata;
+      this.expectByte(0x2c, "',' or '}' after object property");
+      this.skipWhitespace();
+    }
+  }
+
+  private readPropertyName(materializeUnknown = false): number {
+    this.scanString();
+    let field = 0;
+    let decoded: string | undefined;
+    if (this.stringHasEscapes) {
+      decoded = this.decodeString();
+      for (let candidate = 1; candidate <= CHANNEL_HEADER_FIELD_COUNT; candidate += 1) {
+        if (CHANNEL_HEADER_FIELD_NAMES[candidate] === decoded) {
+          field = candidate;
+          break;
+        }
+      }
+    } else {
+      for (let candidate = 1; candidate <= CHANNEL_HEADER_FIELD_COUNT; candidate += 1) {
+        if (
+          this.matchesAscii(
+            this.stringStart + 1,
+            this.stringEnd - 1,
+            CHANNEL_HEADER_FIELD_NAMES[candidate]!
+          )
+        ) {
+          field = candidate;
+          break;
+        }
+      }
+    }
+    this.propertyName =
+      field !== 0
+        ? CHANNEL_HEADER_FIELD_NAMES[field]!
+        : (decoded ??
+          (materializeUnknown
+            ? this.bytes.toString('utf8', this.stringStart + 1, this.stringEnd - 1)
+            : ''));
+    return field;
+  }
+
+  private readValue(integerOnly = false): unknown {
+    const value = this.bytes[this.index];
+    if (value === 0x22) return this.readString();
+    if (value === 0x7b) return this.readObject();
+    if (value === 0x5b) return this.readArray();
+    if (value === 0x74) {
+      this.readLiteral('true');
+      return true;
+    }
+    if (value === 0x66) {
+      this.readLiteral('false');
+      return false;
+    }
+    if (value === 0x6e) {
+      this.readLiteral('null');
+      return null;
+    }
+    return this.readNumber(integerOnly);
+  }
+
+  private readObject(): Record<string, unknown> {
+    this.index += 1;
+    this.skipWhitespace();
+    const object: Record<string, unknown> = {};
+    if (this.consumeByte(0x7d)) return object;
+    for (;;) {
+      const key = this.readString();
+      this.skipWhitespace();
+      this.expectByte(0x3a, "':' after object property");
+      this.skipWhitespace();
+      const value = this.readValue();
+      if (key === '__proto__') {
+        Object.defineProperty(object, key, {
+          configurable: true,
+          enumerable: true,
+          value,
+          writable: true
+        });
+      } else {
+        object[key] = value;
+      }
+      this.skipWhitespace();
+      if (this.consumeByte(0x7d)) return object;
+      this.expectByte(0x2c, "',' or '}' after object property");
+      this.skipWhitespace();
+    }
+  }
+
+  private readArray(): unknown[] {
+    this.index += 1;
+    this.skipWhitespace();
+    const array: unknown[] = [];
+    if (this.consumeByte(0x5d)) return array;
+    for (;;) {
+      array.push(this.readValue());
+      this.skipWhitespace();
+      if (this.consumeByte(0x5d)) return array;
+      this.expectByte(0x2c, "',' or ']' after array item");
+      this.skipWhitespace();
+    }
+  }
+
+  private skipValue(): void {
+    const value = this.bytes[this.index];
+    if (value === 0x22) {
+      this.scanString();
+      return;
+    }
+    if (value === 0x7b) return this.skipObject();
+    if (value === 0x5b) return this.skipArray();
+    if (value === 0x74) return this.readLiteral('true');
+    if (value === 0x66) return this.readLiteral('false');
+    if (value === 0x6e) return this.readLiteral('null');
+    this.readNumber();
+  }
+
+  private skipObject(): void {
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consumeByte(0x7d)) return;
+    for (;;) {
+      this.readPropertyName();
+      this.skipWhitespace();
+      this.expectByte(0x3a, "':' after object property");
+      this.skipWhitespace();
+      this.skipValue();
+      this.skipWhitespace();
+      if (this.consumeByte(0x7d)) return;
+      this.expectByte(0x2c, "',' or '}' after object property");
+      this.skipWhitespace();
+    }
+  }
+
+  private skipArray(): void {
+    this.index += 1;
+    this.skipWhitespace();
+    if (this.consumeByte(0x5d)) return;
+    for (;;) {
+      this.skipValue();
+      this.skipWhitespace();
+      if (this.consumeByte(0x5d)) return;
+      this.expectByte(0x2c, "',' or ']' after array item");
+      this.skipWhitespace();
+    }
+  }
+
+  private readString(): string {
+    this.scanString();
+    return this.decodeString();
+  }
+
+  private scanString(): void {
+    if (this.bytes[this.index] !== 0x22) this.fail('string');
+    this.stringStart = this.index++;
+    this.stringHasEscapes = false;
+    while (this.index < this.bytes.length) {
+      const value = this.bytes[this.index++]!;
+      if (value === 0x22) {
+        this.stringEnd = this.index;
+        return;
+      }
+      if (value < 0x20) this.fail('valid string character');
+      if (value !== 0x5c) continue;
+      this.stringHasEscapes = true;
+      if (this.index === this.bytes.length) this.fail('valid string escape');
+      const escaped = this.bytes[this.index++]!;
+      if (escaped === 0x75) {
+        for (let count = 0; count < 4; count += 1) {
+          if (this.index === this.bytes.length || !isHexDigit(this.bytes[this.index]!))
+            this.fail('four hexadecimal digits after \\u');
+          this.index += 1;
+        }
+      } else if (
+        escaped !== 0x22 &&
+        escaped !== 0x5c &&
+        escaped !== 0x2f &&
+        escaped !== 0x62 &&
+        escaped !== 0x66 &&
+        escaped !== 0x6e &&
+        escaped !== 0x72 &&
+        escaped !== 0x74
+      ) {
+        this.fail('valid string escape');
+      }
+    }
+    this.fail('terminated string');
+  }
+
+  private decodeString(): string {
+    return this.stringHasEscapes
+      ? (JSON.parse(this.bytes.toString('utf8', this.stringStart, this.stringEnd)) as string)
+      : this.bytes.toString('utf8', this.stringStart + 1, this.stringEnd - 1);
+  }
+
+  private readNumber(integerOnly = false): number {
+    const start = this.index;
+    let hasFractionOrExponent = false;
+    if (this.bytes[this.index] === 0x2d) this.index += 1;
+    if (this.bytes[this.index] === 0x30) {
+      this.index += 1;
+    } else if (this.isDigitOneToNine(this.bytes[this.index])) {
+      while (this.isDigit(this.bytes[this.index])) this.index += 1;
+    } else {
+      this.fail('JSON value');
+    }
+    if (this.bytes[this.index] === 0x2e) {
+      hasFractionOrExponent = true;
+      this.index += 1;
+      if (!this.isDigit(this.bytes[this.index])) this.fail('digit after decimal point');
+      while (this.isDigit(this.bytes[this.index])) this.index += 1;
+    }
+    if (this.bytes[this.index] === 0x65 || this.bytes[this.index] === 0x45) {
+      hasFractionOrExponent = true;
+      this.index += 1;
+      if (this.bytes[this.index] === 0x2b || this.bytes[this.index] === 0x2d) this.index += 1;
+      if (!this.isDigit(this.bytes[this.index])) this.fail('digit in exponent');
+      while (this.isDigit(this.bytes[this.index])) this.index += 1;
+    }
+    if (integerOnly && hasFractionOrExponent) {
+      throw new ZLinkFrameworkException(
+        ZLinkFrameworkErrorKind.ProtocolError,
+        'Channel envelope integer fields must use an integer literal.'
+      );
+    }
+    if (integerOnly) {
+      const negative = this.bytes[start] === 0x2d;
+      const digitsStart = start + (negative ? 1 : 0);
+      if (this.index - digitsStart <= 3) {
+        let integer = 0;
+        for (let offset = digitsStart; offset < this.index; offset += 1) {
+          integer = integer * 10 + this.bytes[offset]! - 0x30;
+        }
+        return negative ? -integer : integer;
+      }
+    }
+    const number = Number(this.bytes.toString('ascii', start, this.index));
+    if (!Number.isFinite(number)) {
+      throw new TypeError('framework-json-v1 only accepts finite JSON numbers.');
+    }
+    return number;
+  }
+
+  private readLiteral(value: 'true' | 'false' | 'null'): void {
+    for (let offset = 0; offset < value.length; offset += 1) {
+      if (this.bytes[this.index + offset] !== value.charCodeAt(offset)) this.fail(value);
+    }
+    this.index += value.length;
+  }
+
+  private matchesAscii(start: number, end: number, value: string): boolean {
+    if (end - start !== value.length) return false;
+    for (let offset = 0; offset < value.length; offset += 1) {
+      if (this.bytes[start + offset] !== value.charCodeAt(offset)) return false;
+    }
+    return true;
+  }
+
+  private isDigit(value: number | undefined): boolean {
+    return value !== undefined && value >= 0x30 && value <= 0x39;
+  }
+
+  private isDigitOneToNine(value: number | undefined): boolean {
+    return value !== undefined && value >= 0x31 && value <= 0x39;
+  }
+
+  private skipWhitespace(): void {
+    while (
+      this.bytes[this.index] === 0x20 ||
+      this.bytes[this.index] === 0x09 ||
+      this.bytes[this.index] === 0x0a ||
+      this.bytes[this.index] === 0x0d
+    ) {
+      this.index += 1;
+    }
+  }
+
+  private consumeByte(value: number): boolean {
+    if (this.bytes[this.index] !== value) return false;
+    this.index += 1;
+    return true;
+  }
+
+  private expectByte(value: number, expected: string): void {
+    if (!this.consumeByte(value)) this.fail(expected);
+  }
+
+  private fail(expected: string): never {
+    throw new SyntaxError(`framework-json-v1 expected ${expected} at offset ${this.index}.`);
+  }
+}
+
 function schemaForInboundChannelEnvelope(
   header: ZLinkChannelEnvelopeHeader
 ): ZLinkJsonSchema | undefined {
@@ -1183,10 +1718,11 @@ function validateCorrelationForKind(
 const MAXIMUM_CORRELATION_ID_BYTES = 64;
 
 export function isValidChannelCorrelationId(value: string): boolean {
-  const byteLength = Buffer.byteLength(value, 'utf8');
-  return (
-    byteLength >= 1 && byteLength <= MAXIMUM_CORRELATION_ID_BYTES && /^[\x00-\x7f]*$/.test(value)
-  );
+  if (value.length < 1 || value.length > MAXIMUM_CORRELATION_ID_BYTES) return false;
+  for (let index = 0; index < value.length; index++) {
+    if (value.charCodeAt(index) > 0x7f) return false;
+  }
+  return true;
 }
 
 function validateCorrelationValue(correlationId: string): void {
@@ -1274,7 +1810,7 @@ function optionalFlowOrigin(value: unknown): ZLinkFlowOrigin | undefined {
 
 function requireFlowId(value: unknown): string {
   const flowId = requireString(value, 'flowId');
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(flowId)) {
+  if (!CHANNEL_FLOW_TEXT.test(flowId)) {
     throw new ZLinkConfigurationException('Channel envelope flowId must be a lowercase UUIDv7.');
   }
   return flowId;