@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,546 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE = exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY = exports.BINARY_CONTENT_TYPE = exports.JSON_CONTENT_TYPE = exports.ZLINK_CHANNEL_FORMAT_MARKER = void 0;
+exports.newChannelCorrelationId = newChannelCorrelationId;
+exports.encodeChannelEnvelopeParts = encodeChannelEnvelopeParts;
+exports.encodeChannelEnvelopePartsAtDeadline = encodeChannelEnvelopePartsAtDeadline;
+exports.encodeChannelPublishEnvelopeParts = encodeChannelPublishEnvelopeParts;
+exports.encodeChannelReplyParts = encodeChannelReplyParts;
+exports.channelErrorCodeName = channelErrorCodeName;
+exports.encodeChannelErrorReplyParts = encodeChannelErrorReplyParts;
+exports.decodeChannelReply = decodeChannelReply;
+exports.decodeChannelEnvelope = decodeChannelEnvelope;
+exports.decodeChannelPayload = decodeChannelPayload;
+exports.closeMessages = closeMessages;
+exports.decodeChannelHeader = decodeChannelHeader;
+const node_crypto_1 = require("node:crypto");
+const contracts_1 = require("../../contracts");
+const encoded_payload_storage_1 = require("../../contracts/Common/encoded-payload-storage");
+const ZLinkMessage_1 = require("../../contracts/Common/ZLinkMessage");
+const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const packet_name_1 = require("../messaging/packet-name");
+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 channel_framework_packets_1 = require("./channel-framework-packets");
+const Attributes_1 = require("../../contracts/Handlers/Attributes");
+exports.ZLINK_CHANNEL_FORMAT_MARKER = 0xf2;
+//  Shared default for the dominant no-metadata message; avoids a Map
+//  allocation per outbound envelope.
+const EMPTY_OUTBOUND_METADATA = new Map();
+exports.JSON_CONTENT_TYPE = 'application/json';
+exports.BINARY_CONTENT_TYPE = 'application/octet-stream';
+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);
+    const header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind,
+        channelName,
+        messageName,
+        contentType: encoded.contentType,
+        correlationId: envelopeCorrelationId,
+        deadline: timeoutMs === undefined ? null : new Date(Date.now() + timeoutMs).toISOString(),
+        topic: topic ?? null,
+        errorCode: null,
+        errorMessage: null,
+        metadata: applicationMetadataRecord(metadata),
+        flowId: flow?.flowId,
+        flowOrigin: flow?.flowOrigin
+    };
+    return [encodeChannelHeader(header), encoded.message];
+}
+/**
+ * Encodes an outbound channel envelope with a deadline that was established
+ * before synchronous payload encoding began. This is an internal runtime
+ * entry point for operations that must not extend their original deadline
+ * 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) {
+        throw new RangeError('deadlineUnixMs must be a positive safe integer.');
+    }
+    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);
+    const header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind,
+        channelName,
+        messageName,
+        contentType: encoded.contentType,
+        correlationId: envelopeCorrelationId,
+        deadline: new Date(deadlineUnixMs).toISOString(),
+        topic: topic ?? null,
+        errorCode: null,
+        errorMessage: null,
+        metadata: applicationMetadataRecord(metadata),
+        flowId: flow?.flowId,
+        flowOrigin: flow?.flowOrigin
+    };
+    return [encodeChannelHeader(header), encoded.message];
+}
+function encodeChannelPublishEnvelopeParts(channelName, topic, packetName, payload, codecs, 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 header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind: 4 /* ZLinkChannelMessageKind.Publish */,
+        channelName,
+        messageName,
+        contentType: encoded.contentType,
+        correlationId: null,
+        deadline: null,
+        topic,
+        errorCode: null,
+        errorMessage: null,
+        metadata: applicationMetadataRecord(metadata),
+        flowId: flow?.flowId,
+        flowOrigin: flow?.flowOrigin
+    };
+    return [encodeChannelHeader(header), encoded.message];
+}
+function encodeChannelReplyParts(request, payload, codecs) {
+    const encoded = encodePayload(payload ?? Buffer.alloc(0), (0, channel_framework_packets_1.codecsForFrameworkPacket)(request.messageName, codecs), request.messageName, 'reply');
+    const header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind: 2 /* ZLinkChannelMessageKind.Response */,
+        channelName: request.channelName,
+        messageName: request.messageName,
+        contentType: encoded.contentType,
+        correlationId: request.correlationId,
+        deadline: null,
+        topic: null,
+        metadata: {},
+        flowId: request.flowId,
+        flowOrigin: request.flowOrigin
+    };
+    return [encodeChannelHeader(header), encoded.message];
+}
+/**
+ * Reply metadata marker for errors the framework generated itself (never for
+ * application handler failures). Lets a requester distinguish a
+ * framework-origin NOT_FOUND (e.g. stale route / missing handler) from an
+ * application error that happens to use the same kind.
+ */
+exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY = 'zlink.origin';
+exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE = 'framework';
+/**
+ * Cross-language errorCode wire names, indexed by ZLinkFrameworkErrorKind.
+ * Canonical table: C++ channel_reply_writer.cpp error_code_name(). Every
+ * language encodes the snake_case name on the wire; numeric codes are a
+ * process-local representation and never cross the wire.
+ */
+const ERROR_KIND_WIRE_NAMES = [
+    'not_found', // 0
+    'already_exists', // 1
+    'type_mismatch', // 2
+    'not_configured', // 3
+    'rejected', // 4
+    'unavailable', // 5
+    'capacity_exceeded', // 6
+    'deadline_exceeded', // 7
+    'shutting_down', // 8
+    'protocol_error', // 9
+    'invalid_operation', // 10
+    'data_lost', // 11
+    'internal_failure' // 12
+];
+const ERROR_KIND_BY_WIRE_NAME = new Map(ERROR_KIND_WIRE_NAMES.map((name, kind) => [name, kind]));
+function channelErrorCodeName(kind) {
+    return ERROR_KIND_WIRE_NAMES[kind] ?? 'internal_failure';
+}
+function encodeChannelErrorReplyParts(request, error, metadata = {}) {
+    const errorCode = channelErrorCodeName(error instanceof contracts_1.ZLinkFrameworkException
+        ? error.kind
+        : contracts_1.ZLinkFrameworkErrorKind.InternalFailure);
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const header = {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind: 5 /* ZLinkChannelMessageKind.Error */,
+        channelName: request.channelName,
+        messageName: request.messageName,
+        contentType: exports.JSON_CONTENT_TYPE,
+        correlationId: request.correlationId,
+        deadline: null,
+        topic: null,
+        errorCode,
+        errorMessage,
+        metadata,
+        flowId: request.flowId,
+        flowOrigin: request.flowOrigin
+    };
+    return [encodeChannelHeader(header), encodeJsonBytes(null)];
+}
+function decodeChannelReply(parts, codecs) {
+    const header = decodeChannelHeader(parts);
+    if (header.kind === 5 /* ZLinkChannelMessageKind.Error */) {
+        throw decodeChannelError(header);
+    }
+    if (header.kind !== 2 /* ZLinkChannelMessageKind.Response */) {
+        throw new configuration_1.ZLinkConfigurationException(`Channel reply kind '${header.kind}' is not a response.`);
+    }
+    if (!(0, CodecContentType_1.isCanonicalCodecContentType)(header.contentType)) {
+        throw unsupportedChannelContentType(header.contentType);
+    }
+    const serializer = codecs?.serializers.get(header.contentType);
+    if (serializer === undefined
+        && header.contentType !== exports.BINARY_CONTENT_TYPE
+        && header.contentType !== exports.JSON_CONTENT_TYPE) {
+        throw unsupportedChannelContentType(header.contentType);
+    }
+    if (parts.length < 2 || parts[1].data().length === 0) {
+        return undefined;
+    }
+    if (header.contentType === exports.BINARY_CONTENT_TYPE) {
+        return Buffer.from(parts[1].data());
+    }
+    if (serializer !== undefined) {
+        return serializer.deserialize(contracts_1.ZLinkEncodedPayload.from(parts[1].data()), Object);
+    }
+    return parseWireJson(parts[1].data().toString(), (0, Attributes_1.readZLinkPacketJsonContract)(header.messageName)?.reply);
+}
+function decodeChannelError(header) {
+    const code = header.errorCode;
+    let failure;
+    if (code === undefined || code === null || code.trim().length === 0) {
+        failure = new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'Channel Error reply does not contain a non-empty errorCode.');
+    }
+    else {
+        const message = header.errorMessage ?? 'ZLink channel request failed.';
+        //  Cross-language contract: errorCode carries the snake_case wire name.
+        //  An unknown name degrades to InternalFailure, matching the C++
+        //  request_failure_mapper fallback for unrecognized codes.
+        const publicKind = ERROR_KIND_BY_WIRE_NAME.get(code)
+            ?? contracts_1.ZLinkFrameworkErrorKind.InternalFailure;
+        failure = new contracts_1.ZLinkFrameworkException(publicKind, message);
+    }
+    //  Cross-language contract (.NET ZLinkErrorOriginWire.RemoteReplyOrigin /
+    //  ZLinkEnvelopeErrorMapper): every error DECODED FROM A REMOTE REPLY is
+    //  classified, never left unmarked. The zlink.origin=framework marker
+    //  means the framework itself produced the error (stale route, sealed
+    //  admission, dispatch rejection); its absence means a remote application
+    //  handler produced it. Local/transport failures that never round-trip a
+    //  reply (this function's only caller, decodeChannelReply, is only
+    //  reached for bytes that DID come back over the wire) are unaffected and
+    //  stay unclassified (`origin: undefined`, i.e. "unspecified") because
+    //  they never call this function at all.
+    failure.origin = header.metadata[exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY]
+        === exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE
+        ? exports.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE
+        : 'application';
+    return failure;
+}
+function decodeChannelEnvelope(parts, decodedHeader, flowEnabled = true) {
+    let header = decodedHeader ?? decodeChannelHeader(parts, flowEnabled);
+    if (!flowEnabled && (header.flowId !== undefined || header.flowOrigin !== undefined)) {
+        // Spec 27 §4: with tracing Off the processing point neither reads the
+        // inbound flow fields into context nor copies them into the reply or any
+        // forwarded message. Dropping them here keeps every downstream consumer
+        // (dispatch fields, reply encoders, traces) naturally flow-free.
+        header = { ...header, flowId: undefined, flowOrigin: undefined };
+    }
+    if (parts.length < 2) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope body part is missing.');
+    }
+    // The owning receive loop keeps the Message open until dispatch completes.
+    // Borrow its Buffer so envelope admission does not copy the whole payload.
+    return { header, packetName: header.messageName, payload: parts[1].data() };
+}
+function decodeChannelPayload(envelope, codecs) {
+    try {
+        if (!(0, CodecContentType_1.isCanonicalCodecContentType)(envelope.header.contentType)) {
+            throw unsupportedChannelContentType(envelope.header.contentType);
+        }
+        const serializer = codecs?.serializers.get(envelope.header.contentType);
+        if (serializer !== undefined) {
+            return serializer.deserialize(contracts_1.ZLinkEncodedPayload.from(envelope.payload), Object);
+        }
+        if (envelope.header.contentType === exports.BINARY_CONTENT_TYPE) {
+            // The receive loop owns the Message for the duration of dispatch, so
+            // the envelope's borrowed payload remains valid until this returns.
+            return envelope.payload;
+        }
+        if (envelope.header.contentType === exports.JSON_CONTENT_TYPE) {
+            return parseWireJson(envelope.payload.toString(), schemaForInboundChannelEnvelope(envelope.header));
+        }
+        throw unsupportedChannelContentType(envelope.header.contentType);
+    }
+    catch (error) {
+        if (error instanceof contracts_1.ZLinkFrameworkException) {
+            throw error;
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed, `PayloadDecodeFailed: failed to decode channel payload for '${envelope.header.channelName}:${envelope.header.messageName}'.`, error);
+    }
+}
+function unsupportedChannelContentType(contentType) {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed, `ProtocolError: unsupported channel content type '${contentType}'.`);
+}
+function closeMessages(parts) {
+    for (const part of parts) {
+        if (typeof part.close === 'function') {
+            part.close();
+        }
+    }
+}
+function encodePayload(value, codecs, packetName, contractPart) {
+    if ((0, ZLinkMessage_1.isZLinkMessage)(value) && value.isEncoded()) {
+        const payload = value.toEncodedPayload();
+        return {
+            contentType: exports.BINARY_CONTENT_TYPE,
+            message: (0, encoded_payload_storage_1.borrowEncodedPayload)(payload) ?? payload.data()
+        };
+    }
+    const declaredType = (0, ZLinkMessage_1.isZLinkMessage)(value)
+        ? (0, ZLinkMessage_1.readZLinkMessageDeclaredType)(value)
+        : undefined;
+    if ((0, ZLinkMessage_1.isZLinkMessage)(value))
+        value = value.decode();
+    const selected = (0, payload_codec_1.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: (0, encoded_payload_storage_1.borrowEncodedPayload)(payload) ?? payload.data()
+        };
+    }
+    return {
+        contentType: contentTypeOf(value),
+        message: toMessageLike(value, (0, Attributes_1.readZLinkPacketJsonContract)(packetName)?.[contractPart])
+    };
+}
+function toMessageLike(value, schema) {
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array || isMessage(value)) {
+        return value;
+    }
+    return encodeJsonBytes(value, schema);
+}
+function contentTypeOf(value) {
+    return Buffer.isBuffer(value) || value instanceof Uint8Array || isMessage(value)
+        ? exports.BINARY_CONTENT_TYPE
+        : exports.JSON_CONTENT_TYPE;
+}
+function isMessage(value) {
+    return typeof value === 'object' && value !== null && typeof value.data === 'function';
+}
+function encodeJsonBytes(value, schema) {
+    return Buffer.from((0, framework_json_v1_1.stringifyFrameworkJsonV1)(value, schema));
+}
+function encodeChannelHeader(header) {
+    //  Explicit construction: this runs for every outbound envelope, so avoid a
+    //  per-message spread of the whole header.
+    return encodeJsonBytes({
+        formatMarker: header.formatMarker,
+        kind: header.kind,
+        channelName: header.channelName,
+        messageName: header.messageName,
+        contentType: header.contentType,
+        correlationId: header.correlationId,
+        deadline: header.deadline,
+        topic: header.topic,
+        errorCode: header.errorCode,
+        errorMessage: header.errorMessage,
+        source: header.source,
+        metadata: header.metadata,
+        flowId: header.flowId,
+        flowOrigin: header.flowOrigin === undefined ? undefined : encodeFlowOrigin(header.flowOrigin)
+    });
+}
+function encodeFlowOrigin(origin) {
+    switch (origin) {
+        case 'Inbound': return 1;
+        case 'Timer': return 2;
+        case 'Application': return 3;
+        case 'Lifecycle': return 4;
+    }
+}
+function decodeChannelHeader(parts, flowEnabled = true) {
+    if (parts.length === 0) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope header part is missing.');
+    }
+    return validateChannelHeader(parseWireJson(parts[0].data().toString()), flowEnabled);
+}
+function parseWireJson(payload, schema) {
+    return (0, framework_json_v1_1.parseFrameworkJsonV1)(payload, {
+        rejectPropertyName: isPrototypeKey
+    }, schema);
+}
+function schemaForInboundChannelEnvelope(header) {
+    const contract = (0, Attributes_1.readZLinkPacketJsonContract)(header.messageName);
+    return header.kind === 2 /* ZLinkChannelMessageKind.Response */ ? contract?.reply : contract?.payload;
+}
+function validateChannelHeader(value, flowEnabled = true) {
+    if (!isRecord(value)) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope header must be a JSON object.');
+    }
+    const header = value;
+    if (header.formatMarker !== exports.ZLINK_CHANNEL_FORMAT_MARKER) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope format marker is invalid.');
+    }
+    const kind = requireChannelMessageKind(header.kind);
+    const contentType = requireString(header.contentType, 'contentType');
+    if (contentType.trim().length === 0) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope contentType must not be empty.');
+    }
+    // Spec 27 §4: flow fields are observation-only. With tracing Off the
+    // processing point neither reads nor validates them; correlation_id below
+    // stays mandatory at every level.
+    const flowId = flowEnabled ? optionalFlowId(header.flowId) : undefined;
+    const flowOrigin = flowEnabled ? optionalFlowOrigin(header.flowOrigin) : undefined;
+    if ((flowId === undefined) !== (flowOrigin === undefined)) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope flowId and flowOrigin must both be present or absent.');
+    }
+    const correlationId = requireNullableString(header.correlationId, 'correlationId');
+    validateCorrelationForKind(kind, correlationId);
+    return {
+        formatMarker: exports.ZLINK_CHANNEL_FORMAT_MARKER,
+        kind,
+        channelName: requireString(header.channelName, 'channelName'),
+        messageName: requireString(header.messageName, 'messageName'),
+        contentType,
+        correlationId,
+        deadline: requireNullableString(header.deadline, 'deadline'),
+        topic: requireNullableString(header.topic, 'topic'),
+        errorCode: header.errorCode === undefined ? null : requireNullableString(header.errorCode, 'errorCode'),
+        errorMessage: header.errorMessage === undefined ? null : requireNullableString(header.errorMessage, 'errorMessage'),
+        source: header.source === undefined ? undefined : requireNullableString(header.source, 'source'),
+        metadata: requireApplicationMetadata(header.metadata),
+        flowId,
+        flowOrigin
+    };
+}
+function correlationIdForOutboundKind(kind, correlationId) {
+    if (kind === 1 /* ZLinkChannelMessageKind.Request */) {
+        const selected = correlationId ?? newChannelCorrelationId();
+        validateCorrelationValue(selected);
+        return selected;
+    }
+    if (kind === 3 /* ZLinkChannelMessageKind.Command */ || kind === 4 /* ZLinkChannelMessageKind.Publish */) {
+        if (correlationId !== undefined && correlationId !== null) {
+            throw new configuration_1.ZLinkConfigurationException(`Channel ${kind === 4 /* ZLinkChannelMessageKind.Publish */ ? 'publish' : 'send'} must not contain correlationId.`);
+        }
+        return null;
+    }
+    const selected = correlationId ?? null;
+    validateCorrelationForKind(kind, selected);
+    return selected;
+}
+function validateCorrelationForKind(kind, correlationId) {
+    if (kind === 1 /* ZLinkChannelMessageKind.Request */
+        || kind === 2 /* ZLinkChannelMessageKind.Response */
+        || kind === 5 /* ZLinkChannelMessageKind.Error */) {
+        if (correlationId === null) {
+            throw new configuration_1.ZLinkConfigurationException(`Channel ${channelKindName(kind)} requires correlationId.`);
+        }
+        validateCorrelationValue(correlationId);
+        return;
+    }
+    if (correlationId !== null) {
+        throw new configuration_1.ZLinkConfigurationException(`Channel ${channelKindName(kind)} must not contain correlationId.`);
+    }
+}
+function validateCorrelationValue(correlationId) {
+    const byteLength = Buffer.byteLength(correlationId, 'utf8');
+    if (byteLength < 1 || byteLength > 64 || !/^[\x00-\x7f]*$/.test(correlationId)) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope correlationId must be a non-empty ASCII value of at most 64 bytes.');
+    }
+}
+function channelKindName(kind) {
+    switch (kind) {
+        case 1 /* ZLinkChannelMessageKind.Request */: return 'request';
+        case 2 /* ZLinkChannelMessageKind.Response */: return 'response';
+        case 3 /* ZLinkChannelMessageKind.Command */: return 'send';
+        case 4 /* ZLinkChannelMessageKind.Publish */: return 'publish';
+        case 5 /* ZLinkChannelMessageKind.Error */: return 'error';
+    }
+}
+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.');
+        }
+        record[key] = value;
+    }
+    if (Buffer.byteLength(JSON.stringify(record), 'utf8') > 1024) {
+        throw new configuration_1.ZLinkConfigurationException('Channel application metadata exceeds the 1024-byte limit.');
+    }
+    return Object.freeze(record);
+}
+function requireApplicationMetadata(value) {
+    if (value === undefined) {
+        return Object.freeze({});
+    }
+    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);
+}
+function optionalFlowId(value) {
+    return value === undefined || value === null ? undefined : requireFlowId(value);
+}
+function optionalFlowOrigin(value) {
+    return value === undefined || value === null ? undefined : requireFlowOrigin(value);
+}
+function requireFlowId(value) {
+    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)) {
+        throw new configuration_1.ZLinkConfigurationException('Channel envelope flowId must be a lowercase UUIDv7.');
+    }
+    return flowId;
+}
+function requireFlowOrigin(value) {
+    switch (value) {
+        case 1: return 'Inbound';
+        case 2: return 'Timer';
+        case 3: return 'Application';
+        case 4: return 'Lifecycle';
+    }
+    throw new configuration_1.ZLinkConfigurationException('Channel envelope flowOrigin is invalid.');
+}
+function requireChannelMessageKind(value) {
+    if (value === 1 /* ZLinkChannelMessageKind.Request */ ||
+        value === 2 /* ZLinkChannelMessageKind.Response */ ||
+        value === 3 /* ZLinkChannelMessageKind.Command */ ||
+        value === 4 /* ZLinkChannelMessageKind.Publish */ ||
+        value === 5 /* ZLinkChannelMessageKind.Error */) {
+        return value;
+    }
+    throw new configuration_1.ZLinkConfigurationException('Channel envelope kind is not supported.');
+}
+function requireString(value, fieldName) {
+    if (typeof value !== 'string') {
+        throw new configuration_1.ZLinkConfigurationException(`Channel envelope ${fieldName} must be a string.`);
+    }
+    return value;
+}
+function requireNullableString(value, fieldName) {
+    if (value === null || typeof value === 'string') {
+        return value;
+    }
+    throw new configuration_1.ZLinkConfigurationException(`Channel envelope ${fieldName} must be a string or null.`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isPrototypeKey(key) {
+    return key === '__proto__' || key === 'constructor' || key === 'prototype';
+}

package/dist/runtime/channels/channel-framework-packets.d.ts

@@ -0,0 +1,2 @@
+import type { ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+export declare function codecsForFrameworkPacket(packetName: string | undefined, codecs: ZLinkChannelEnvelopeCodecRegistry | undefined): ZLinkChannelEnvelopeCodecRegistry | undefined;

package/dist/runtime/channels/channel-framework-packets.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codecsForFrameworkPacket = codecsForFrameworkPacket;
+function codecsForFrameworkPacket(packetName, codecs) {
+    return packetName?.startsWith('__zlink.') === true ? undefined : codecs;
+}

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

@@ -0,0 +1,16 @@
+import type { Message } from '../../contracts/Common/Message';
+import { type ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
+export interface ZLinkMultipartOperation<TNext> {
+    message(message: MessageLike): TNext;
+}
+export interface ZLinkMultipartSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartSubmitOperation> {
+    submit(): unknown;
+}
+export interface ZLinkMultipartAsyncSubmitOperation extends ZLinkMultipartOperation<ZLinkMultipartAsyncSubmitOperation> {
+    submit(): Promise<void>;
+}
+export type ZLinkMultipartReplyOperation = ZLinkMultipartSubmitOperation;
+export declare function appendParts<TNext extends ZLinkMultipartOperation<TNext>>(operation: ZLinkMultipartOperation<TNext>, parts: readonly MessageLike[]): TNext;
+export declare function submitRequestOperation(operation: {
+    submit(): Promise<readonly Message[]>;
+}, label: string): Promise<readonly Message[]>;

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

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendParts = appendParts;
+exports.submitRequestOperation = submitRequestOperation;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_values_1 = require("../backend/runtime-values");
+const configuration_1 = require("../configuration");
+const contracts_1 = require("../../contracts");
+function appendParts(operation, parts) {
+    if (parts.length === 0) {
+        throw new configuration_1.ZLinkConfigurationException('Channel multipart envelope must contain at least one part.');
+    }
+    let current = operation.message(parts[0]);
+    for (let index = 1; index < parts.length; index++) {
+        current = current.message(parts[index]);
+    }
+    return current;
+}
+async function submitRequestOperation(operation, label) {
+    try {
+        return await operation.submit();
+    }
+    catch (error) {
+        //  Spec 32-framework-error-model:81-92 — classify the backend request
+        //  terminal rather than collapsing every failure to Unavailable.
+        if ((0, runtime_values_1.isZLinkBackendResultError)(error) && error.operation === 'request') {
+            throw new contracts_1.ZLinkFrameworkException((0, framework_errors_internal_1.requestResultToPublicErrorKind)(error.result), `${label} failed with result ${error.result}.`, error);
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${label} failed before a reply was received.`, true, error);
+    }
+}

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

@@ -0,0 +1,33 @@
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+import { ZLinkChannelDispatchServices } from './channel-dispatch-services';
+import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+export declare class ZLinkChannelOutboundOperations {
+    private readonly sockets;
+    private readonly codecs;
+    private readonly dispatchServices;
+    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>;
+    private sendScoped;
+    private traceSend;
+    request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    private requestScoped;
+    tryPublish(channelName: string, topic: string, packetName: string | undefined, event: unknown, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
+    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>;
+    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>;
+    private routeRequestScoped;
+    private measureRequest;
+}
+/**
+ * A ClientServer DEALER's request progress poller is intentionally unref'ed.
+ * The public request promise is live work, however, so it needs its own
+ * ref'ed handle until reply, cancellation, timeout, or failure settles it.
+ */
+export declare function keepChannelRequestAlive<T>(request: Promise<T>): Promise<T>;