@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -6,6 +6,7 @@ exports.encodeChannelEnvelopeParts = encodeChannelEnvelopeParts;
 exports.encodeChannelEnvelopePartsAtDeadline = encodeChannelEnvelopePartsAtDeadline;
 exports.encodeChannelPublishEnvelopeParts = encodeChannelPublishEnvelopeParts;
 exports.encodeChannelReplyParts = encodeChannelReplyParts;
+exports.channelErrorKindFromCode = channelErrorKindFromCode;
 exports.channelErrorCodeName = channelErrorCodeName;
 exports.encodeChannelErrorReplyParts = encodeChannelErrorReplyParts;
 exports.decodeChannelReply = decodeChannelReply;
@@ -13,6 +14,8 @@ exports.decodeChannelEnvelope = decodeChannelEnvelope;
 exports.decodeChannelPayload = decodeChannelPayload;
 exports.closeMessages = closeMessages;
 exports.decodeChannelHeader = decodeChannelHeader;
+exports.isValidChannelCorrelationId = isValidChannelCorrelationId;
+const runtime_message_1 = require("../backend/runtime-message");
 const node_crypto_1 = require("node:crypto");
 const node_buffer_1 = require("node:buffer");
 const contracts_1 = require("../../contracts");
@@ -34,8 +37,27 @@ exports.ZLINK_CHANNEL_FORMAT_MARKER = 0xf2;
 const EMPTY_OUTBOUND_METADATA = new Map();
 exports.JSON_CONTENT_TYPE = 'application/json';
 exports.BINARY_CONTENT_TYPE = 'application/octet-stream';
+const preparedChannelHeaders = new WeakMap();
+const CHANNEL_CORRELATION_FIELD = ',"correlationId":';
+const CHANNEL_DEADLINE_FIELD = ',"deadline":';
+const CHANNEL_CORRELATION_TEXT_LENGTH = 32;
+const PREPARED_CHANNEL_CORRELATION = '0'.repeat(CHANNEL_CORRELATION_TEXT_LENGTH);
+const PREPARED_CHANNEL_DEADLINE = '2000-01-01T00:00:00.000Z';
+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}$/;
+// 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
+// §3) without drawing random bytes for every request — the shape Java
+// ZLinkServiceOperationIds uses.
+const CHANNEL_CORRELATION_PREFIX = (0, node_crypto_1.randomBytes)(CHANNEL_CORRELATION_TEXT_LENGTH / 4).toString('hex');
+let channelCorrelationCounter = 0;
 function newChannelCorrelationId() {
-    return (0, node_crypto_1.randomUUID)().replaceAll('-', '');
+    channelCorrelationCounter += 1;
+    return (CHANNEL_CORRELATION_PREFIX +
+        channelCorrelationCounter.toString(16).padStart(CHANNEL_CORRELATION_TEXT_LENGTH / 2, '0'));
 }
 function encodeChannelEnvelopeParts(kind, channelName, packetName, payload, timeoutMs, topic, codecs, correlationId, createFlow = true, metadata = EMPTY_OUTBOUND_METADATA) {
     return encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, payload, timeoutMs === undefined ? undefined : Date.now() + timeoutMs, topic, codecs, correlationId, createFlow, metadata);
@@ -56,7 +78,7 @@ function encodeChannelEnvelopePartsAtDeadline(kind, channelName, packetName, pay
     const flow = createFlow ? (0, flow_context_1.currentOrCreateFlow)('Application') : undefined;
     const envelopeCorrelationId = correlationIdForOutboundKind(kind, correlationId);
     return [
-        encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin),
+        encodeChannelHeader(kind, channelName, messageName, encoded.contentType, envelopeCorrelationId, deadlineUnixMs === undefined ? null : new Date(deadlineUnixMs).toISOString(), topic ?? null, null, null, undefined, applicationMetadataRecord(metadata), flow?.flowId, flow?.flowOrigin, codecs),
         encoded.message
     ];
 }
@@ -72,7 +94,7 @@ function encodeChannelPublishEnvelopeParts(channelName, topic, packetName, paylo
 function encodeChannelReplyParts(request, payload, codecs) {
     const encoded = encodePayload(payload ?? Buffer.alloc(0), (0, channel_framework_packets_1.codecsForFrameworkPacket)(request.messageName, codecs), request.messageName, 'reply');
     return [
-        encodeChannelHeader(2 /* ZLinkChannelMessageKind.Response */, request.channelName, request.messageName, encoded.contentType, request.correlationId, null, null, undefined, undefined, undefined, EMPTY_APPLICATION_METADATA, request.flowId, request.flowOrigin),
+        encodeChannelHeader(2 /* 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
     ];
 }
@@ -105,6 +127,9 @@ const ERROR_KIND_WIRE_NAMES = [
     'internal_failure' // 11
 ];
 const ERROR_KIND_BY_WIRE_NAME = new Map(ERROR_KIND_WIRE_NAMES.map((name, kind) => [name, kind]));
+function channelErrorKindFromCode(code) {
+    return ERROR_KIND_BY_WIRE_NAME.get(code);
+}
 function channelErrorCodeName(kind) {
     return ERROR_KIND_WIRE_NAMES[kind] ?? 'internal_failure';
 }
@@ -137,10 +162,10 @@ function decodeChannelReply(parts, codecs) {
         return undefined;
     }
     if (header.contentType === exports.BINARY_CONTENT_TYPE) {
-        return Buffer.from(parts[1].data());
+        return runtime_message_1.ZLinkBufferMessage.retainPayload(parts[1]);
     }
     if (serializer !== undefined) {
-        return serializer.deserialize(contracts_1.ZLinkEncodedPayload.from(parts[1].data()), Object);
+        return serializer.deserialize((0, payload_codec_1.encodedPayloadFromOwned)(parts[1].data()), Object);
     }
     return parseWireJson(parts[1].data().toString(), (0, Attributes_1.readZLinkPacketJsonContract)(header.messageName)?.reply);
 }
@@ -155,7 +180,7 @@ function decodeChannelError(header) {
         //  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;
+        const publicKind = channelErrorKindFromCode(code) ?? contracts_1.ZLinkFrameworkErrorKind.InternalFailure;
         failure = new contracts_1.ZLinkFrameworkException(publicKind, message);
     }
     //  Cross-language contract (.NET ZLinkErrorOriginWire.RemoteReplyOrigin /
@@ -197,7 +222,7 @@ function decodeChannelPayload(envelope, codecs) {
         }
         const serializer = codecs?.serializers.get(envelope.header.contentType);
         if (serializer !== undefined) {
-            return serializer.deserialize(contracts_1.ZLinkEncodedPayload.from(envelope.payload), Object);
+            return serializer.deserialize((0, payload_codec_1.encodedPayloadFromOwned)(envelope.payload), Object);
         }
         if (envelope.header.contentType === exports.BINARY_CONTENT_TYPE) {
             // The receive loop owns the Message for the duration of dispatch, so
@@ -270,7 +295,34 @@ function isMessage(value) {
 function encodeJsonBytes(value, schema) {
     return Buffer.from((0, framework_json_v1_1.stringifyFrameworkJsonV1)(value, schema));
 }
-function encodeChannelHeader(kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin) {
+function encodeChannelHeader(kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin, codecs) {
+    if (codecs !== undefined &&
+        metadata === EMPTY_APPLICATION_METADATA &&
+        (flowId === undefined
+            ? flowOrigin === undefined
+            : flowOrigin !== undefined && CHANNEL_FLOW_TEXT.test(flowId)) &&
+        topic === null &&
+        source === undefined &&
+        ((kind === 3 /* ZLinkChannelMessageKind.Command */ &&
+            correlationId === null &&
+            deadline === null &&
+            errorCode === null &&
+            errorMessage === null) ||
+            (kind === 1 /* ZLinkChannelMessageKind.Request */ &&
+                correlationId !== null &&
+                CHANNEL_CORRELATION_TEXT.test(correlationId) &&
+                deadline !== null &&
+                deadline.length === PREPARED_CHANNEL_DEADLINE.length &&
+                errorCode === null &&
+                errorMessage === null) ||
+            (kind === 2 /* ZLinkChannelMessageKind.Response */ &&
+                correlationId !== null &&
+                CHANNEL_CORRELATION_TEXT.test(correlationId) &&
+                deadline === null &&
+                errorCode === undefined &&
+                errorMessage === undefined))) {
+        return preparedChannelHeader(codecs, kind, channelName, messageName, contentType, correlationId, deadline, errorCode, errorMessage, flowId, flowOrigin);
+    }
     // The wire has a fixed field order. Measure escaped UTF-8 first, then write
     // each field once into the only header Buffer: no header object, whole JSON
     // string, or post-encode byte copy exists on the outbound path.
@@ -281,6 +333,49 @@ function encodeChannelHeader(kind, channelName, messageName, contentType, correl
     writeChannelHeader(writer, kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin);
     return result;
 }
+function preparedChannelHeader(codecs, kind, channelName, messageName, contentType, correlationId, deadline, errorCode, errorMessage, flowId, flowOrigin) {
+    let channels = preparedChannelHeaders.get(codecs.serializers);
+    if (channels === undefined)
+        preparedChannelHeaders.set(codecs.serializers, (channels = new Map()));
+    let packets = channels.get(channelName);
+    if (packets === undefined)
+        channels.set(channelName, (packets = new Map()));
+    let contentTypes = packets.get(messageName);
+    if (contentTypes === undefined)
+        packets.set(messageName, (contentTypes = new Map()));
+    let kinds = contentTypes.get(contentType);
+    if (kinds === undefined)
+        contentTypes.set(contentType, (kinds = new Map()));
+    let deadlines = kinds.get(kind);
+    if (deadlines === undefined)
+        kinds.set(kind, (deadlines = new Map()));
+    const hasDeadline = deadline !== null;
+    let flows = deadlines.get(hasDeadline);
+    if (flows === undefined)
+        deadlines.set(hasDeadline, (flows = new Map()));
+    let prepared = flows.get(flowOrigin);
+    if (prepared === undefined) {
+        const bytes = encodeChannelHeader(kind, channelName, messageName, contentType, correlationId === null ? null : PREPARED_CHANNEL_CORRELATION, hasDeadline ? PREPARED_CHANNEL_DEADLINE : null, null, errorCode, errorMessage, undefined, EMPTY_APPLICATION_METADATA, flowOrigin === undefined ? undefined : PREPARED_CHANNEL_FLOW, flowOrigin);
+        prepared = {
+            bytes,
+            correlationOffset: bytes.indexOf(CHANNEL_CORRELATION_FIELD) + CHANNEL_CORRELATION_FIELD.length + 1,
+            deadlineOffset: bytes.indexOf(CHANNEL_DEADLINE_FIELD) + CHANNEL_DEADLINE_FIELD.length + 1,
+            flowOffset: bytes.indexOf(CHANNEL_FLOW_FIELD) + CHANNEL_FLOW_FIELD.length + 1
+        };
+        flows.set(flowOrigin, prepared);
+    }
+    if (correlationId === null && flowId === undefined)
+        return prepared.bytes;
+    const bytes = Buffer.allocUnsafe(prepared.bytes.byteLength);
+    prepared.bytes.copy(bytes);
+    if (correlationId !== null)
+        bytes.write(correlationId, prepared.correlationOffset, CHANNEL_CORRELATION_TEXT_LENGTH, 'ascii');
+    if (deadline !== null)
+        bytes.write(deadline, prepared.deadlineOffset, PREPARED_CHANNEL_DEADLINE.length, 'ascii');
+    if (flowId !== undefined)
+        bytes.write(flowId, prepared.flowOffset, PREPARED_CHANNEL_FLOW.length, 'ascii');
+    return bytes;
+}
 function writeChannelHeader(writer, kind, channelName, messageName, contentType, correlationId, deadline, topic, errorCode, errorMessage, source, metadata, flowId, flowOrigin) {
     writer.append('{"formatMarker":');
     writer.append(String(exports.ZLINK_CHANNEL_FORMAT_MARKER));
@@ -292,9 +387,9 @@ function writeChannelHeader(writer, kind, channelName, messageName, contentType,
     writer.string(messageName);
     writer.append(',"contentType":');
     writer.string(contentType);
-    writer.append(',"correlationId":');
+    writer.append(CHANNEL_CORRELATION_FIELD);
     writer.nullableString(correlationId);
-    writer.append(',"deadline":');
+    writer.append(CHANNEL_DEADLINE_FIELD);
     writer.nullableString(deadline);
     writer.append(',"topic":');
     writer.nullableString(topic);
@@ -438,10 +533,16 @@ function parseWireJson(payload, schema) {
     }, schema);
 }
 function parseChannelHeaderBytes(payload) {
+    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;
     if (!(0, node_buffer_1.isUtf8)(payload)) {
         throw new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, 'Channel envelope header must contain valid UTF-8.');
     }
-    return tryParseCanonicalChannelHeader(payload) ?? (0, framework_json_v1_1.parseFrameworkJsonV1)(payload.toString());
+    return canonical ?? (0, framework_json_v1_1.parseFrameworkJsonV1)(payload.toString());
 }
 /**
  * Accept the byte layout emitted by writeChannelHeader without materializing
@@ -449,8 +550,7 @@ function parseChannelHeaderBytes(payload) {
  * framework-json-v1 parser, which remains the sole authority for JSON
  * failures and unknown properties. Header metadata accepts every valid string key.
  */
-function tryParseCanonicalChannelHeader(payload) {
-    const reader = new CanonicalChannelHeaderReader(payload);
+function tryParseCanonicalChannelHeader(reader) {
     if (!reader.consume('{"formatMarker":242,"kind":'))
         return undefined;
     const kind = reader.readSingleDigit();
@@ -484,25 +584,32 @@ function tryParseCanonicalChannelHeader(payload) {
         deadline: deadline === NULL_JSON_STRING ? null : deadline,
         topic: topic === NULL_JSON_STRING ? null : topic
     };
-    if (!reader.readOptionalNullableString('errorCode', header))
+    if (!reader.readOptionalNullableString(CANONICAL_ERROR_CODE, 'errorCode', header))
         return undefined;
-    if (!reader.readOptionalNullableString('errorMessage', header))
+    if (!reader.readOptionalNullableString(CANONICAL_ERROR_MESSAGE, 'errorMessage', header))
         return undefined;
-    if (!reader.readOptionalNullableString('source', header))
+    if (!reader.readOptionalNullableString(CANONICAL_SOURCE, 'source', header))
         return undefined;
+    // Empty metadata validates to the shared empty record.
     if (!reader.consume(',"metadata":{}'))
         return undefined;
-    header.metadata = {};
-    if (!reader.readOptionalString('flowId', header))
+    if (!reader.readOptionalString(CANONICAL_FLOW_ID, 'flowId', header))
         return undefined;
-    if (!reader.readOptionalSingleDigit('flowOrigin', header))
+    if (!reader.readOptionalSingleDigit(CANONICAL_FLOW_ORIGIN, 'flowOrigin', header))
         return undefined;
     return reader.consume('}') && reader.atEnd() ? header : undefined;
 }
+const CANONICAL_ERROR_CODE = ',"errorCode":';
+const CANONICAL_ERROR_MESSAGE = ',"errorMessage":';
+const CANONICAL_SOURCE = ',"source":';
+const CANONICAL_FLOW_ID = ',"flowId":';
+const CANONICAL_FLOW_ORIGIN = ',"flowOrigin":';
 const NULL_JSON_STRING = Symbol('null JSON string');
 class CanonicalChannelHeaderReader {
     bytes;
     index = 0;
+    /** A string held a byte outside ASCII, so the caller must still check UTF-8. */
+    sawNonAscii = false;
     constructor(bytes) {
         this.bytes = bytes;
     }
@@ -533,15 +640,22 @@ class CanonicalChannelHeaderReader {
             return undefined;
         const start = this.index;
         this.index += 1;
+        let hasEscape = false;
         while (this.index < this.bytes.length) {
             const value = this.bytes[this.index++];
             if (value === 0x22) {
-                return JSON.parse(this.bytes.toString('utf8', start, this.index));
+                // Without escapes the JSON string is its own bytes; decode them once.
+                return hasEscape
+                    ? JSON.parse(this.bytes.toString('utf8', start, this.index))
+                    : this.bytes.toString(this.sawNonAscii ? 'utf8' : 'latin1', start + 1, this.index - 1);
             }
             if (value < 0x20)
                 return undefined;
+            if (value >= 0x80)
+                this.sawNonAscii = true;
             if (value !== 0x5c)
                 continue;
+            hasEscape = true;
             if (this.index === this.bytes.length)
                 return undefined;
             const escaped = this.bytes[this.index++];
@@ -572,8 +686,8 @@ class CanonicalChannelHeaderReader {
             return NULL_JSON_STRING;
         return this.readString();
     }
-    readOptionalNullableString(name, target) {
-        if (!this.consume(`,\"${name}\":`))
+    readOptionalNullableString(token, name, target) {
+        if (!this.consume(token))
             return true;
         const value = this.readNullableString();
         if (value === undefined)
@@ -581,8 +695,8 @@ class CanonicalChannelHeaderReader {
         target[name] = value === NULL_JSON_STRING ? null : value;
         return true;
     }
-    readOptionalString(name, target) {
-        if (!this.consume(`,\"${name}\":`))
+    readOptionalString(token, name, target) {
+        if (!this.consume(token))
             return true;
         const value = this.readString();
         if (value === undefined)
@@ -590,8 +704,8 @@ class CanonicalChannelHeaderReader {
         target[name] = value;
         return true;
     }
-    readOptionalSingleDigit(name, target) {
-        if (!this.consume(`,\"${name}\":`))
+    readOptionalSingleDigit(token, name, target) {
+        if (!this.consume(token))
             return true;
         const value = this.readSingleDigit();
         if (value === undefined)
@@ -681,9 +795,13 @@ function validateCorrelationForKind(kind, correlationId) {
         throw new configuration_1.ZLinkConfigurationException(`Channel ${channelKindName(kind)} must not contain correlationId.`);
     }
 }
+const MAXIMUM_CORRELATION_ID_BYTES = 64;
+function isValidChannelCorrelationId(value) {
+    const byteLength = Buffer.byteLength(value, 'utf8');
+    return (byteLength >= 1 && byteLength <= MAXIMUM_CORRELATION_ID_BYTES && /^[\x00-\x7f]*$/.test(value));
+}
 function validateCorrelationValue(correlationId) {
-    const byteLength = Buffer.byteLength(correlationId, 'utf8');
-    if (byteLength < 1 || byteLength > 64 || !/^[\x00-\x7f]*$/.test(correlationId)) {
+    if (!isValidChannelCorrelationId(correlationId)) {
         throw new configuration_1.ZLinkConfigurationException('Channel envelope correlationId must be a non-empty ASCII value of at most 64 bytes.');
     }
 }

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

@@ -13,7 +13,7 @@ export declare class ZLinkChannelOutboundOperations {
     send(channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private sendScoped;
     private traceSend;
-    request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, onAdmitted?: () => void): Promise<TReply>;
     private requestScoped;
     tryPublish(channelName: string, topic: string, packetName: string | undefined, event: unknown, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
     private tryPublishScoped;
@@ -22,7 +22,7 @@ export declare class ZLinkChannelOutboundOperations {
     routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private routeSubmitScoped;
     private traceRouteSend;
-    routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, onAdmitted?: () => void): Promise<TReply>;
     private routeRequestScoped;
     private measureRequest;
 }

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

@@ -68,10 +68,10 @@ class ZLinkChannelOutboundOperations {
             correlationId: undefined
         });
     }
-    request(channelName, packetName, request, timeoutMs, signal, metadata) {
-        return keepChannelRequestAlive((0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.requestScoped(channelName, packetName, request, timeoutMs, signal, metadata)));
+    request(channelName, packetName, request, timeoutMs, signal, metadata, onAdmitted) {
+        return keepChannelRequestAlive((0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.requestScoped(channelName, packetName, request, timeoutMs, signal, metadata, onAdmitted)));
     }
-    async requestScoped(channelName, packetName, request, timeoutMs, signal, metadata) {
+    async requestScoped(channelName, packetName, request, timeoutMs, signal, metadata, onAdmitted) {
         const deadlineMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
         const deadlineUnixMs = timeoutMs === undefined ? undefined : Date.now() + timeoutMs;
         let correlationId;
@@ -117,7 +117,7 @@ class ZLinkChannelOutboundOperations {
                 let replyParts = [];
                 try {
                     try {
-                        replyParts = await (0, abort_1.awaitWithAbort)(dealer.request(parts, (0, request_deadline_1.remainingRequestTimeout)(`Channel request '${channelName}'`, deadlineMs)), signal);
+                        replyParts = await (0, abort_1.awaitWithAbort)(dealer.request(parts, (0, request_deadline_1.remainingRequestTimeout)(`Channel request '${channelName}'`, deadlineMs), onAdmitted), signal);
                     }
                     catch (error) {
                         if (signal?.aborted === true)
@@ -205,10 +205,10 @@ class ZLinkChannelOutboundOperations {
             targetRid: targetNodeRid
         });
     }
-    routeRequest(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata) {
-        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.routeRequestScoped(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata));
+    routeRequest(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata, onAdmitted) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.dispatchServices.flowCreationEnabled(), () => this.routeRequestScoped(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata, onAdmitted));
     }
-    async routeRequestScoped(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata) {
+    async routeRequestScoped(routerChannelId, targetNodeRid, packetName, request, timeoutMs, signal, metadata, onAdmitted) {
         let correlationId;
         let router;
         let terminalRecorded = false;
@@ -245,7 +245,7 @@ class ZLinkChannelOutboundOperations {
                 targetRid: targetNodeRid
             });
             const reply = await this.measureRequest(routerChannelId, async () => {
-                const replyParts = await (0, abort_1.awaitWithAbort)(router.request(targetNodeRid, parts, timeoutMs), signal);
+                const replyParts = await (0, abort_1.awaitWithAbort)(router.request(targetNodeRid, parts, timeoutMs, onAdmitted), signal);
                 try {
                     return (0, channel_envelope_1.decodeChannelReply)(replyParts, this.codecs);
                 }

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

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkFrameworkRegistration } from '../configuration';
 import type { ZLinkBackendSpotRouteBridge, ZLinkChannelBackendAdapter } from '../backend/contracts';
@@ -49,7 +50,7 @@ export declare class ZLinkChannelRuntimeLifecycle {
         lifecycleGeneration: bigint;
         descriptorRevision: bigint;
         advertisedEndpoint: string;
-        state: "error" | "preparing" | "serving" | "retiring" | "stopped";
+        state: "error" | "preparing" | "serving" | "stopped" | "retiring";
     }[] | undefined;
     configureLocationAutoConnect(runtime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides, events?: ZLinkLocationEventSink): void;
     private beginLocationAutoConnectCore;
@@ -60,8 +61,8 @@ export declare class ZLinkChannelRuntimeLifecycle {
     bindRouteMeshRouters(): void;
     start(taskRunner?: ZLinkRuntimeTaskRunner): Promise<void>[];
     prepareMeshDispatch(taskRunner?: ZLinkRuntimeTaskRunner): void;
-    dispatchMeshChannel(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
-    dispatchMeshRoute(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
+    dispatchMeshChannel(meshName: string, record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
+    dispatchMeshRoute(meshName: string, record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
     dispatchLocalMeshRoute(meshName: string, sourceNodeRid: RoutingId, parts: readonly Message[], signal?: AbortSignal): Promise<void>;
     canDispatchLocalMeshRoute(meshName: string): boolean;
     dispose(signal?: AbortSignal): Promise<void>;

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

@@ -10,9 +10,7 @@ const channel_receive_loops_1 = require("./channel-receive-loops");
 const client_server_location_runtime_1 = require("./client-server-location-runtime");
 const fanout_location_runtime_1 = require("./fanout-location-runtime");
 const RuntimeEndpointConnections_1 = require("../../contracts/Configuration/RuntimeEndpointConnections");
-const node_async_hooks_1 = require("node:async_hooks");
 const state_lane_1 = require("../execution/state-lane");
-const detachedStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:channel-runtime-lifecycle');
 class ZLinkChannelRuntimeLifecycle {
     options;
     lane = new state_lane_1.ZLinkStateLane();
@@ -74,12 +72,12 @@ class ZLinkChannelRuntimeLifecycle {
             return;
         let fanoutLocation;
         try {
-            await startOutsideStateLane(() => start.clientServerLocation?.start(signal) ?? Promise.resolve());
+            await (0, state_lane_1.startOutsideStateLane)(() => start.clientServerLocation?.start(signal) ?? Promise.resolve());
             fanoutLocation = await this.lane.run(() => this.beginFanoutLocationAutoConnectCore(start));
-            await startOutsideStateLane(() => fanoutLocation?.start(signal) ?? Promise.resolve());
+            await (0, state_lane_1.startOutsideStateLane)(() => fanoutLocation?.start(signal) ?? Promise.resolve());
         }
         catch (error) {
-            await startOutsideStateLane(() => Promise.all([
+            await (0, state_lane_1.startOutsideStateLane)(() => Promise.all([
                 start.clientServerLocation?.stop(signal).catch(() => undefined),
                 fanoutLocation?.stop(signal).catch(() => undefined)
             ]));
@@ -89,9 +87,9 @@ class ZLinkChannelRuntimeLifecycle {
     }
     async reclaimLocationOwnerRows(signal) {
         const clientServerLocation = await this.lane.run(() => this.clientServerLocation);
-        await startOutsideStateLane(() => clientServerLocation?.reclaimOwnerRows(signal) ?? Promise.resolve());
+        await (0, state_lane_1.startOutsideStateLane)(() => clientServerLocation?.reclaimOwnerRows(signal) ?? Promise.resolve());
         const fanoutLocation = await this.lane.run(() => this.fanoutLocation);
-        await startOutsideStateLane(() => fanoutLocation?.reclaimOwnerRows(signal) ?? Promise.resolve());
+        await (0, state_lane_1.startOutsideStateLane)(() => fanoutLocation?.reclaimOwnerRows(signal) ?? Promise.resolve());
     }
     bindRouteMeshRouters() {
         for (const routeChannel of this.options.registration.routeChannelOptions.values()) {
@@ -178,7 +176,7 @@ class ZLinkChannelRuntimeLifecycle {
             }
         }
     }
-    dispatchMeshChannel(meshName, record, signal) {
+    dispatchMeshChannel(meshName, record, signal, admit) {
         const channelName = record.channelName;
         if (channelName === null) {
             throw new configuration_1.ZLinkConfigurationException('MeshNode channel record is missing channelName.');
@@ -187,14 +185,14 @@ class ZLinkChannelRuntimeLifecycle {
         if (dispatcher === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' channel '${channelName}' has no registered handlers.`);
         }
-        return dispatcher.dispatchMesh(record, signal);
+        return dispatcher.dispatchMesh(record, signal, admit);
     }
-    dispatchMeshRoute(meshName, record, signal) {
+    dispatchMeshRoute(meshName, record, signal, admit) {
         const dispatcher = this.meshRouteDispatchers.get(meshName);
         if (dispatcher === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' has no registered node-direct handlers.`);
         }
-        return dispatcher.dispatchMesh(record, signal);
+        return dispatcher.dispatchMesh(record, signal, admit);
     }
     dispatchLocalMeshRoute(meshName, sourceNodeRid, parts, signal) {
         const dispatcher = this.meshRouteDispatchers.get(meshName);
@@ -211,20 +209,20 @@ class ZLinkChannelRuntimeLifecycle {
     }
     async disposeCore(signal) {
         const work = await this.lane.run(() => this.beginDisposeCore());
-        const transportStopped = await startOutsideStateLane(() => Promise.allSettled([
+        const transportStopped = await (0, state_lane_1.startOutsideStateLane)(() => Promise.allSettled([
             ...work.channelLoops.map((loop) => loop.stop()),
             ...work.subscriberLoops.map((loop) => loop.stop()),
             ...work.routeLoops.map((loop) => loop.stop()),
             ...work.manualTransitions
         ]));
-        const applicationStopped = await startOutsideStateLane(() => Promise.allSettled(work.applicationDispatchQueues.map((queue) => queue.close())));
+        const applicationStopped = await (0, state_lane_1.startOutsideStateLane)(() => Promise.allSettled(work.applicationDispatchQueues.map((queue) => queue.close())));
         const descriptorStopped = work.clientServerLocation === undefined
             ? []
-            : await startOutsideStateLane(() => Promise.allSettled([work.clientServerLocation?.stop(signal)]));
+            : await (0, state_lane_1.startOutsideStateLane)(() => Promise.allSettled([work.clientServerLocation?.stop(signal)]));
         const fanoutDescriptorStopped = work.fanoutLocation === undefined
             ? []
-            : await startOutsideStateLane(() => Promise.allSettled([work.fanoutLocation?.stop(signal)]));
-        const cleanup = await startOutsideStateLane(() => Promise.allSettled([
+            : await (0, state_lane_1.startOutsideStateLane)(() => Promise.allSettled([work.fanoutLocation?.stop(signal)]));
+        const cleanup = await (0, state_lane_1.startOutsideStateLane)(() => Promise.allSettled([
             ...work.spotRouteBridges.map((bridge) => bridge.dispose()),
             this.options.sockets.dispose()
         ]));
@@ -421,7 +419,7 @@ class ZLinkChannelRuntimeLifecycle {
     }
     enqueueManualFanoutTransition(state, transition) {
         state.transition = state.transition
-            .then(() => startOutsideStateLane(transition), () => startOutsideStateLane(transition))
+            .then(() => (0, state_lane_1.startOutsideStateLane)(transition), () => (0, state_lane_1.startOutsideStateLane)(transition))
             .catch((error) => state.taskRunner.errorSink.reportRuntimeTaskException(`subscriber:${state.channelName}:manual:${state.index}:lifecycle`, error));
     }
     openManualFanoutSubscriber(state) {
@@ -489,13 +487,13 @@ class ZLinkChannelRuntimeLifecycle {
             return;
         const errors = [];
         try {
-            await startOutsideStateLane(() => active.loop.stop());
+            await (0, state_lane_1.startOutsideStateLane)(() => active.loop.stop());
         }
         catch (error) {
             errors.push(error);
         }
         try {
-            await startOutsideStateLane(() => this.options.sockets.closeFanoutSubscriberConnection(state.connectionId));
+            await (0, state_lane_1.startOutsideStateLane)(() => this.options.sockets.closeFanoutSubscriberConnection(state.connectionId));
         }
         catch (error) {
             errors.push(error);
@@ -524,7 +522,7 @@ class ZLinkChannelRuntimeLifecycle {
         state.stopping = undefined;
     }
     drainManualFanoutSubscriberCore(state) {
-        state.transition = state.transition.then(() => startOutsideStateLane(() => this.closeManualFanoutSubscriber(state)), () => startOutsideStateLane(() => this.closeManualFanoutSubscriber(state)));
+        state.transition = state.transition.then(() => (0, state_lane_1.startOutsideStateLane)(() => this.closeManualFanoutSubscriber(state)), () => (0, state_lane_1.startOutsideStateLane)(() => this.closeManualFanoutSubscriber(state)));
         return state.transition;
     }
     startFanoutSubscriberLoop(channelName, connectionId, subscriber) {
@@ -546,7 +544,7 @@ class ZLinkChannelRuntimeLifecycle {
         this.subscriberReceiveLoops.push(loop);
         void taskRunner.run(`subscriber:${channelName}:automatic:${connectionId}`, (signal) => loop.run(signal));
         return async () => {
-            await startOutsideStateLane(() => loop.stop());
+            await (0, state_lane_1.startOutsideStateLane)(() => loop.stop());
             await this.lane.run(() => this.removeSubscriberReceiveLoopCore(loop));
         };
     }
@@ -651,6 +649,3 @@ function hasFanoutLocationTopology(registration) {
     }
     return false;
 }
-function startOutsideStateLane(work) {
-    return detachedStateLaneResource.runInAsyncScope(work);
-}

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

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { RoutingId } from '../../contracts';
@@ -40,22 +41,22 @@ export declare class ZLinkChannelRuntimeManager {
     openMonitoringSource(sourceName: string, adapter: ZLinkMonitoringBackendAdapter): ZLinkBackendSocketMonitor;
     start(taskRunner?: ZLinkRuntimeTaskRunner): Promise<void>[];
     prepareMeshDispatch(taskRunner?: ZLinkRuntimeTaskRunner): void;
-    dispatchMeshChannel(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
-    dispatchMeshRoute(meshName: string, record: ReceiveRecord, signal?: AbortSignal): Promise<void>;
+    dispatchMeshChannel(meshName: string, record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
+    dispatchMeshRoute(meshName: string, record: ReceiveRecord, signal?: AbortSignal, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
     dispatchLocalMeshRoute(meshName: string, sourceNodeRid: RoutingId, parts: readonly Message[], signal?: AbortSignal): Promise<void>;
     canDispatchLocalMeshRoute(meshName: string): boolean;
     send(channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
-    request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, onAdmitted?: () => void): Promise<TReply>;
     tryPublish(channelName: string, topic: string, packetName: string | undefined, event: unknown, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
     publish(channelName: string, topic: string, packetName: string | undefined, event: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
-    routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    routeRequest<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, onAdmitted?: () => void): Promise<TReply>;
     routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<void>;
-    routeRequestToSpot<TReply>(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
-    routeRequestFromSpotToSpot<TReply>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply>;
+    routeRequestToSpot<TReply>(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, onAdmitted?: () => void): Promise<TReply>;
+    routeRequestFromSpotToSpot<TReply>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, onAdmitted?: () => void): Promise<TReply>;
     routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<void>;
-    routeRequestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
-    routeRequestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+    routeRequestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal, onAdmitted?: () => void): Promise<readonly Message[]>;
+    routeRequestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal, onAdmitted?: () => void): Promise<readonly Message[]>;
     canRouteChannel(routerChannelId: string): boolean;
     canRoutePacketChannel(routerChannelId: string): boolean;
     dispose(signal?: AbortSignal): Promise<void>;