@zlink-systems/framework 0.30.0 → 0.30.2

package/dist/runtime/backend/node/node-socket-backend-adapter.d.ts

@@ -4,7 +4,7 @@ export declare function wrapSocket<T extends {
     close(): void;
 }>(nativeInstance: T, pollCompletion?: boolean): T & ZLinkBackendObject;
 export declare function nodeEventLoopPollerOf(socket: object): ZLinkNodeEventLoopPoller;
-export declare function disconnectStreamPeer(socket: {
+export declare function disconnectSocketPeer(socket: {
     disconnectRid(routingId: unknown): void;
 }, routingId: unknown): void;
 export declare function isEndpointCloseIgnorableError(error: unknown): boolean;

package/dist/runtime/backend/node/node-socket-backend-adapter.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.wrapSocket = wrapSocket;
 exports.nodeEventLoopPollerOf = nodeEventLoopPollerOf;
-exports.disconnectStreamPeer = disconnectStreamPeer;
+exports.disconnectSocketPeer = disconnectSocketPeer;
 exports.isEndpointCloseIgnorableError = isEndpointCloseIgnorableError;
 const RegistrationBuilderPolicy_1 = require("../../../contracts/Configuration/RegistrationBuilderPolicy");
 const node_backend_adapter_support_1 = require("./node-backend-adapter-support");
@@ -144,12 +144,12 @@ function wrapSocket(nativeInstance, pollCompletion) {
         },
         request(...args) {
             if (hasRoutedPeer) {
-                const [routingId, payload, timeoutMs] = args;
-                return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.request((0, node_backend_adapter_support_1.toNativeRoutingId)(routingId)), payload, timeoutMs);
+                const [routingId, payload, timeoutMs, onAdmitted] = args;
+                return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.request((0, node_backend_adapter_support_1.toNativeRoutingId)(routingId)), payload, timeoutMs, undefined, onAdmitted);
             }
             if (hasRequest) {
-                const [payload, timeoutMs] = args;
-                return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.request(), payload, timeoutMs, adapter.receiveAdmission?.recordReceived);
+                const [payload, timeoutMs, onAdmitted] = args;
+                return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.request(), payload, timeoutMs, adapter.receiveAdmission?.recordReceived, onAdmitted);
             }
             throw new TypeError('Backend request requires a DEALER or ROUTER socket.');
         },
@@ -201,11 +201,11 @@ function wrapSocket(nativeInstance, pollCompletion) {
             const operation = nativeInstance.sendToSpot((0, node_backend_adapter_support_1.toNativeRoutingId)(targetRid), (0, node_backend_adapter_support_1.toNativeRoutingId)(targetSpot));
             await (0, node_backend_adapter_support_1.submitBindingAsyncSend)(operation, payload);
         },
-        requestToSpot(targetRid, targetSpot, payload, timeoutMs) {
-            return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.requestToSpot((0, node_backend_adapter_support_1.toNativeRoutingId)(targetRid), (0, node_backend_adapter_support_1.toNativeRoutingId)(targetSpot)), payload, timeoutMs);
+        requestToSpot(targetRid, targetSpot, payload, timeoutMs, onAdmitted) {
+            return (0, node_backend_adapter_support_1.submitBindingRequest)(nativeInstance.requestToSpot((0, node_backend_adapter_support_1.toNativeRoutingId)(targetRid), (0, node_backend_adapter_support_1.toNativeRoutingId)(targetSpot)), payload, timeoutMs, undefined, onAdmitted);
         },
         disconnectPeer(routingId) {
-            disconnectStreamPeer(nativeInstance, routingId);
+            disconnectSocketPeer(nativeInstance, (0, node_backend_adapter_support_1.toNativeRoutingId)(routingId));
         },
         async bindActor(_sessionRid, _actor, _timeoutMs, _signal) {
             throw new Error('Session Actor dispatch requires enableActorDispatch() and a Framework MeshNode service route.');
@@ -228,13 +228,13 @@ function nodeEventLoopPollerOf(socket) {
     }
     return poller;
 }
-function disconnectStreamPeer(socket, routingId) {
+function disconnectSocketPeer(socket, routingId) {
     try {
-        socket.disconnectRid((0, node_backend_adapter_support_1.toNativeRoutingId)(routingId));
+        socket.disconnectRid(routingId);
     }
     catch (error) {
         // An absent RID has already completed the physical close. The existing
-        // session lifecycle still owns local cleanup and unbind.
+        // logical lifecycle still owns local cleanup and unbind.
         if (!(0, node_backend_adapter_support_1.isBindingNotFound)(error))
             throw error;
     }

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

@@ -56,7 +56,7 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     setRoutingId(routingId: string): void;
     connectToRoutingId(routingId: string, endpoint: string): void;
     send(targetRid: string, parts: readonly Uint8Array[]): Promise<void>;
-    request(targetRid: string, parts: readonly Uint8Array[], timeoutMs: number, recordReceived?: () => void): Promise<readonly Buffer[]>;
+    request(targetRid: string, parts: readonly Uint8Array[], timeoutMs: number, recordReceived?: () => void, onAdmitted?: () => void): Promise<readonly Buffer[]>;
     receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
     /** The selected route of every RID. The socket's one route observer calls it. */
     routesSnapshot(): readonly ZLinkRawRouterRoute[];
@@ -64,7 +64,7 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
 export interface ZLinkRawDealerPort extends ZLinkRawSocketPort {
     setRoutingId(routingId: string): void;
     send(parts: readonly Uint8Array[]): Promise<void>;
-    request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]>;
+    request(parts: readonly Uint8Array[], timeoutMs: number, onAdmitted?: () => void): Promise<readonly Buffer[]>;
     receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
 }
 export interface ZLinkRawHostPort {

package/dist/runtime/backend/runtime-message.d.ts

@@ -4,6 +4,7 @@ export declare class ZLinkBufferMessage implements Message {
     private constructor();
     static from(value: Message | Buffer | Uint8Array | string): ZLinkBufferMessage;
     static fromOwned(bytes: Buffer): ZLinkBufferMessage;
+    static retainPayload(message: Message): Buffer;
     data(): Buffer;
     toBytes(): Uint8Array;
     copy(): Message;

package/dist/runtime/backend/runtime-message.js

@@ -16,6 +16,11 @@ class ZLinkBufferMessage {
     static fromOwned(bytes) {
         return new ZLinkBufferMessage(bytes);
     }
+    static retainPayload(message) {
+        // Binding data() Buffers retain their storage after the message handle closes.
+        // Preserve that ownership at runtime boundaries without copying the payload.
+        return message.data();
+    }
     data() {
         return this.bytes;
     }

package/dist/runtime/backend/runtime-values.d.ts

@@ -36,6 +36,7 @@ export type SubmitResult = (typeof SubmitResult)[keyof typeof SubmitResult];
 export type ZLinkBackendSendFlags = number;
 export type ZLinkBackendRecvFlags = number;
 export declare const ZLINK_BACKEND_SEND_NONE: ZLinkBackendSendFlags;
+export declare const ZLINK_BACKEND_SEND_DONT_WAIT: ZLinkBackendSendFlags;
 export declare const ZLINK_BACKEND_RECV_DONT_WAIT: ZLinkBackendRecvFlags;
 export declare class ZLinkBackendResultError extends Error {
     readonly operation: 'request' | 'submit';

package/dist/runtime/backend/runtime-values.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkBackendResultError = exports.ZLINK_BACKEND_RECV_DONT_WAIT = exports.ZLINK_BACKEND_SEND_NONE = exports.SubmitResult = exports.RequestResult = void 0;
+exports.ZLinkBackendResultError = exports.ZLINK_BACKEND_RECV_DONT_WAIT = exports.ZLINK_BACKEND_SEND_DONT_WAIT = exports.ZLINK_BACKEND_SEND_NONE = exports.SubmitResult = exports.RequestResult = void 0;
 exports.isZLinkBackendResultError = isZLinkBackendResultError;
 exports.isBackendNotConnectedError = isBackendNotConnectedError;
 exports.isBackendRequestTimeoutError = isBackendRequestTimeoutError;
@@ -37,6 +37,7 @@ exports.SubmitResult = Object.freeze({
     NotAdmitted: 13
 });
 exports.ZLINK_BACKEND_SEND_NONE = 0;
+exports.ZLINK_BACKEND_SEND_DONT_WAIT = 1;
 exports.ZLINK_BACKEND_RECV_DONT_WAIT = 1;
 class ZLinkBackendResultError extends Error {
     operation;

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

@@ -35,6 +35,8 @@ export declare class DefaultZLinkRouteClient implements ZLinkRouteClient {
     private readonly transport?;
     private readonly spotRouterChannelIdForMesh;
     private readonly channelTransport?;
+    private readonly nodeSends;
+    private readonly nodeRequests;
     constructor(registration: ZLinkFrameworkRegistration, transport?: ZLinkRouteClientTransport | undefined, spotRouterChannelIdForMesh?: (meshName: string) => string, channelTransport?: ZLinkChannelClientTransportSource | undefined);
     sendToNode(meshName: string, targetNodeRid: string, message: unknown): ZLinkSendCall;
     requestToNode(meshName: string, targetNodeRid: string, request: unknown): ZLinkRequestCall;

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

@@ -4,6 +4,7 @@ exports.DefaultZLinkSpotPublisherClient = exports.DefaultZLinkRouteClient = expo
 exports.resolveChannelRoute = resolveChannelRoute;
 exports.requireUniqueRouteMeshChannel = requireUniqueRouteMeshChannel;
 const Registration_1 = require("../../contracts/Configuration/Registration");
+const request_result_1 = require("../messaging/request-result");
 const configuration_1 = require("../configuration");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const submission_result_1 = require("../messaging/submission-result");
@@ -79,6 +80,8 @@ class DefaultZLinkRouteClient {
     transport;
     spotRouterChannelIdForMesh;
     channelTransport;
+    nodeSends = new Map();
+    nodeRequests = new Map();
     constructor(registration, transport, spotRouterChannelIdForMesh = (meshName) => meshName, channelTransport) {
         this.registration = registration;
         this.transport = transport;
@@ -86,10 +89,34 @@ class DefaultZLinkRouteClient {
         this.channelTransport = channelTransport;
     }
     sendToNode(meshName, targetNodeRid, message) {
-        return new DefaultZLinkSendCall(() => this.requireMesh(meshName), async (packetName, metadata) => normalizeSubmitResult(await this.requireTransport().submit(meshName, targetNodeRid, packetName, message, metadata)));
+        let targets = this.nodeSends.get(meshName);
+        if (targets === undefined)
+            this.nodeSends.set(meshName, (targets = new Map()));
+        let prepared = targets.get(targetNodeRid);
+        if (prepared === undefined) {
+            prepared = {
+                validate: () => {
+                    this.requireMesh(meshName);
+                },
+                submit: (packetName, metadata, payload) => normalizeSubmitResult(this.requireTransport().submit(meshName, targetNodeRid, packetName, payload, metadata))
+            };
+            targets.set(targetNodeRid, prepared);
+        }
+        return new DefaultZLinkSendCall(prepared.validate, prepared.submit, message);
     }
     requestToNode(meshName, targetNodeRid, request) {
-        return new DefaultZLinkRequestCall(() => this.requireMesh(meshName), (packetName, timeoutMs, metadata, signal) => this.requireTransport().request(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata), this.defaultRequestTimeout(meshName));
+        let targets = this.nodeRequests.get(meshName);
+        if (targets === undefined)
+            this.nodeRequests.set(meshName, (targets = new Map()));
+        let prepared = targets.get(targetNodeRid);
+        if (prepared === undefined) {
+            prepared = {
+                validate: () => this.requireMesh(meshName),
+                submit: (packetName, timeoutMs, metadata, signal, onAdmitted, message) => this.requireTransport().request(meshName, targetNodeRid, packetName, message, timeoutMs, signal, metadata, onAdmitted)
+            };
+            targets.set(targetNodeRid, prepared);
+        }
+        return new DefaultZLinkRequestCall(prepared.validate, prepared.submit, this.defaultRequestTimeout(meshName), request);
     }
     sendToChannel(channelName, message) {
         return new DefaultZLinkSendCall(() => this.requireChannelRoute(channelName), async (packetName, metadata) => {
@@ -101,12 +128,12 @@ class DefaultZLinkRouteClient {
         });
     }
     requestToChannel(channelName, request) {
-        return new DefaultZLinkRequestCall(() => this.requireChannelRoute(channelName), (packetName, timeoutMs, metadata, signal) => {
+        return new DefaultZLinkRequestCall(() => this.requireChannelRoute(channelName), (packetName, timeoutMs, metadata, signal, onAdmitted) => {
             const route = this.requireChannelRoute(channelName);
             if (route.kind === 'route-mesh') {
-                return this.requireTransport().requestToChannel(route.meshName, channelName, packetName, request, timeoutMs, signal, metadata);
+                return this.requireTransport().requestToChannel(route.meshName, channelName, packetName, request, timeoutMs, signal, metadata, onAdmitted);
             }
-            return this.requireChannelTransport().request(channelName, packetName, request, timeoutMs, signal, metadata);
+            return this.requireChannelTransport().request(channelName, packetName, request, timeoutMs, signal, metadata, onAdmitted);
         }, this.defaultRequestTimeoutForChannel(channelName));
     }
     sendToSpot(spot, message) {
@@ -123,10 +150,11 @@ class DefaultZLinkRouteClient {
     requestToSpot(spot, request) {
         return new DefaultZLinkRequestCall(() => {
             this.requireSpotTransport();
-        }, (_packetName, timeoutMs, metadata, signal) => (0, spot_outbound_1.requestToSpotHandle)(this.requireSpotTransport(), spot, request, {
+        }, (_packetName, timeoutMs, metadata, signal, onAdmitted) => (0, spot_outbound_1.requestToSpotHandle)(this.requireSpotTransport(), spot, request, {
             timeoutMs,
             signal,
             metadata,
+            onAdmitted,
             spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
         }), this.registration.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS);
     }
@@ -217,14 +245,17 @@ exports.DefaultZLinkSpotPublisherClient = DefaultZLinkSpotPublisherClient;
 class DefaultZLinkSendCall {
     validate;
     submitter;
-    selectedMetadata = new Map();
+    message;
+    selectedMetadata;
     executed = false;
-    constructor(validate, submitter) {
+    constructor(validate, submitter, message) {
         this.validate = validate;
         this.submitter = submitter;
+        this.message = message;
     }
     metadata(keyOrMetadata, value) {
         ensureNotExecuted(this.executed);
+        this.selectedMetadata ??= new Map();
         if (typeof keyOrMetadata === 'string') {
             this.selectedMetadata.set(keyOrMetadata, value);
         }
@@ -235,12 +266,20 @@ class DefaultZLinkSendCall {
         }
         return this;
     }
-    async submit() {
-        ensureNotExecuted(this.executed);
-        this.validate();
-        this.executed = true;
-        const result = await this.submitter(undefined, new Map(this.selectedMetadata));
-        (0, submission_result_1.requireOneWayCompletion)(result, 'One-way send');
+    submit() {
+        try {
+            ensureNotExecuted(this.executed);
+            this.validate();
+            this.executed = true;
+            const result = this.submitter(undefined, this.selectedMetadata ?? EMPTY_CALL_METADATA, this.message);
+            if (result instanceof Promise)
+                return result.then(completeOneWaySend);
+            completeOneWaySend(result);
+            return completedOneWaySend;
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
     }
 }
 function ensureNotExecuted(executed) {
@@ -248,22 +287,33 @@ function ensureNotExecuted(executed) {
         (0, submission_result_1.throwAlreadySubmitted)('ZLink call');
     }
 }
+const EMPTY_CALL_METADATA = new Map();
+const completedOneWaySend = Promise.resolve();
+function completeOneWaySend(result) {
+    (0, submission_result_1.requireOneWayCompletion)(result, 'One-way send');
+}
 function normalizeSubmitResult(result) {
-    return result ?? { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+    return result instanceof Promise
+        ? result.then((value) => value ?? submission_result_1.submittedResult)
+        : (result ?? submission_result_1.submittedResult);
 }
 class DefaultZLinkRequestCall {
     validate;
     submitter;
     defaultRequestTimeoutMs;
+    message;
     timeoutMs;
-    selectedMetadata = new Map();
+    selectedMetadata;
     turn = (0, execution_1.captureZLinkSpotSerialTurn)();
-    constructor(validate, submitter, defaultRequestTimeoutMs) {
+    /** `message` is the request payload a prepared submitter receives per call. */
+    constructor(validate, submitter, defaultRequestTimeoutMs, message) {
         this.validate = validate;
         this.submitter = submitter;
         this.defaultRequestTimeoutMs = defaultRequestTimeoutMs;
+        this.message = message;
     }
     metadata(keyOrMetadata, value) {
+        this.selectedMetadata ??= new Map();
         if (typeof keyOrMetadata === 'string') {
             this.selectedMetadata.set(keyOrMetadata, value);
         }
@@ -278,17 +328,19 @@ class DefaultZLinkRequestCall {
         this.timeoutMs = timeoutMs;
         return this;
     }
-    async submit(signal) {
-        (0, abort_1.throwIfAborted)(signal);
-        this.validate();
-        return this.submitter(undefined, this.timeoutMs ?? this.defaultRequestTimeoutMs, new Map(this.selectedMetadata), signal);
+    submit(signal) {
+        return (0, request_result_1.createZLinkRequest)((onAdmitted) => {
+            (0, abort_1.throwIfAborted)(signal);
+            this.validate();
+            return this.submitter(undefined, this.timeoutMs ?? this.defaultRequestTimeoutMs, this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata), signal, onAdmitted, this.message);
+        });
     }
     async yield(signal) {
         const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
         (0, abort_1.throwIfAborted)(signal);
         this.validate();
-        const pending = this.submitter(undefined, this.timeoutMs ?? this.defaultRequestTimeoutMs, new Map(this.selectedMetadata), signal);
-        return turn.yieldPromise(pending);
+        const pending = this.submitter(undefined, this.timeoutMs ?? this.defaultRequestTimeoutMs, this.selectedMetadata === undefined ? EMPTY_CALL_METADATA : new Map(this.selectedMetadata), signal, undefined, this.message);
+        return turn.yieldFrameworkPromise(pending);
     }
 }
 class DefaultZLinkPublishCall {

package/dist/runtime/channels/channel-dispatch-pipeline.d.ts

@@ -1,3 +1,4 @@
+import type { ZLinkMeshDispatchAdmission } from '../admission';
 import type { ZLinkMessageContext, ZLinkHandlerFilter, ZLinkUnhandledDispatchOptions, ZLinkFlowOrigin } from '../../contracts';
 import { ZLinkFrameworkException } from '../../contracts';
 import { ZLinkDispatchMessageKind, ZLinkDispatchErrorSurface } from '../../contracts/Dispatch/ZLinkDispatchOptions';
@@ -31,7 +32,7 @@ interface ZLinkOneWayDispatch<TContext extends ZLinkMessageContext> {
     readonly context: TContext;
     readonly signal?: AbortSignal;
 }
-interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
+export interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
     readonly fields: ZLinkChannelDispatchFields;
     readonly envelope: ZLinkChannelEnvelope;
     readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
@@ -39,16 +40,34 @@ interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
     readonly context: TContext;
     readonly signal?: AbortSignal;
     readonly missingHandlerMessage: string;
-    readonly writeReply: (reply: unknown) => Promise<void>;
-    readonly writeError: (error: unknown) => Promise<void>;
+    readonly writeReply: (reply: unknown) => void | Promise<void>;
+    readonly writeError: (error: unknown) => void | Promise<void>;
 }
 export declare class ZLinkChannelDispatchPipeline {
     private readonly options;
     private readonly filters;
     private readonly unhandled;
     constructor(options: ZLinkChannelDispatchPipelineOptions);
-    dispatchOneWay<TContext extends ZLinkMessageContext>(dispatch: ZLinkOneWayDispatch<TContext>): Promise<void>;
-    dispatchRequest<TContext extends ZLinkMessageContext>(dispatch: ZLinkRequestDispatch<TContext>): Promise<void>;
+    /**
+     * Runs the handler in the caller's execution turn. A synchronous handler
+     * completes here; an asynchronous handler adds exactly one continuation
+     * for its terminal trace or error record.
+     */
+    dispatchOneWay<TContext extends ZLinkMessageContext>(dispatch: ZLinkOneWayDispatch<TContext>, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
+    private dispatchMissingOneWay;
+    private completeOneWay;
+    private failOneWay;
+    /**
+     * Runs the handler in the caller's execution turn and writes its reply in
+     * the same turn when the handler completes synchronously. An asynchronous
+     * handler adds exactly one continuation that writes the reply.
+     */
+    dispatchRequest<TContext extends ZLinkMessageContext>(dispatch: ZLinkRequestDispatch<TContext>, admit?: ZLinkMeshDispatchAdmission): void | Promise<void>;
+    private dispatchMissingRequest;
+    private invokeInFlow;
+    private completeRequest;
+    private replyPathMissing;
+    private failRequest;
     dropMissingReplyPath(fields: ZLinkChannelDispatchFields): void;
     /**
      * Terminal handling for an envelope that failed structural decoding.
@@ -66,6 +85,7 @@ export declare class ZLinkChannelDispatchPipeline {
         readonly writeProtocolError?: (error: ZLinkFrameworkException) => Promise<void>;
     }): Promise<void>;
     private invoke;
+    private invokeFiltered;
     private createFilterContext;
     private dispatchKind;
     private report;

package/dist/runtime/channels/channel-dispatch-pipeline.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkChannelDispatchPipeline = void 0;
 const framework_errors_internal_1 = require("../framework-errors-internal");
+const abort_1 = require("../abort");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const handlers_1 = require("../handlers");
@@ -17,75 +18,126 @@ class ZLinkChannelDispatchPipeline {
         this.filters = options.filters ?? [];
         this.unhandled = options.unhandled ?? DEFAULT_UNHANDLED_DISPATCH;
     }
-    async dispatchOneWay(dispatch) {
+    /**
+     * Runs the handler in the caller's execution turn. A synchronous handler
+     * completes here; an asynchronous handler adds exactly one continuation
+     * for its terminal trace or error record.
+     */
+    dispatchOneWay(dispatch, admit) {
+        if (admit !== undefined) {
+            const pipeline = this;
+            const record = dispatch;
+            return admit(() => pipeline.dispatchOneWay(record), (error) => pipeline.failOneWay(record.fields, error));
+        }
         this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, dispatch.fields);
         this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, dispatch.fields);
-        if (dispatch.handler === undefined) {
-            const action = dispatch.fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish
-                ? this.unhandled.publish
-                : this.unhandled.send;
-            this.report(dispatch.fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
-            this.applyOneWayUnhandled(action, dispatch.fields);
-            return;
-        }
+        if (dispatch.handler === undefined)
+            return this.dispatchMissingOneWay(dispatch.fields);
+        let invocation;
         try {
-            const flow = (0, flow_context_1.createInboundFlow)(dispatch.fields.flowId, dispatch.fields.flowOrigin, this.options.dispatchErrors.flow.flowCreationEnabled(), undefined);
-            const invocation = await (0, flow_context_1.runWithFlow)(flow, () => this.invoke(dispatch.envelope, dispatch.codecs, dispatch.handler, dispatch.context, dispatch.fields, dispatch.signal));
-            if (invocation.handlerInvoked) {
-                this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, dispatch.fields);
-            }
+            invocation = this.invokeInFlow(dispatch, dispatch.handler);
         }
         catch (error) {
-            this.report(dispatch.fields, this.failureReason(error), ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, error);
+            this.failOneWay(dispatch.fields, error);
+            return;
+        }
+        if (!(0, abort_1.isPromiseLike)(invocation)) {
+            this.completeOneWay(dispatch.fields, invocation);
+            return;
         }
+        return Promise.resolve(invocation).then((value) => this.completeOneWay(dispatch.fields, value), (error) => this.failOneWay(dispatch.fields, error));
     }
-    async dispatchRequest(dispatch) {
+    async dispatchMissingOneWay(fields) {
+        const action = fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish
+            ? this.unhandled.publish
+            : this.unhandled.send;
+        this.report(fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
+        this.applyOneWayUnhandled(action, fields);
+    }
+    completeOneWay(fields, invocation) {
+        if (invocation !== HANDLER_FILTER_REJECTED) {
+            this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed, fields);
+        }
+    }
+    failOneWay(fields, error) {
+        this.report(fields, this.failureReason(error), ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, error);
+    }
+    /**
+     * Runs the handler in the caller's execution turn and writes its reply in
+     * the same turn when the handler completes synchronously. An asynchronous
+     * handler adds exactly one continuation that writes the reply.
+     */
+    dispatchRequest(dispatch, admit) {
+        if (admit !== undefined) {
+            const pipeline = this;
+            const record = dispatch;
+            return admit(() => pipeline.dispatchRequest(record), (error) => pipeline.failRequest(record, error));
+        }
         this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received, dispatch.fields);
         this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted, dispatch.fields);
-        if (dispatch.handler === undefined) {
-            const missing = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.HandlerNotFound, dispatch.missingHandlerMessage);
-            if (this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.ReplyError) {
-                await dispatch.writeError(missing);
-            }
-            this.report(dispatch.fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing, this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.ReplyError
-                ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError
-                : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
-            if (this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.Throw) {
-                throw missing;
-            }
-            return;
+        if (dispatch.handler === undefined)
+            return this.dispatchMissingRequest(dispatch);
+        let invocation;
+        try {
+            invocation = this.invokeInFlow(dispatch, dispatch.handler);
         }
-        let reply;
+        catch (error) {
+            return this.failRequest(dispatch, error);
+        }
+        if (!(0, abort_1.isPromiseLike)(invocation))
+            return this.completeRequest(dispatch, invocation);
+        return Promise.resolve(invocation).then((value) => this.completeRequest(dispatch, value), (error) => this.failRequest(dispatch, error));
+    }
+    async dispatchMissingRequest(dispatch) {
+        const missing = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.HandlerNotFound, dispatch.missingHandlerMessage);
+        if (this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.ReplyError) {
+            await dispatch.writeError(missing);
+        }
+        this.report(dispatch.fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerMissing, this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.ReplyError
+            ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError
+            : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
+        if (this.unhandled.request === contracts_1.ZLinkUnhandledDispatchAction.Throw) {
+            throw missing;
+        }
+    }
+    invokeInFlow(dispatch, handler) {
+        const flow = (0, flow_context_1.createInboundFlow)(dispatch.fields.flowId, dispatch.fields.flowOrigin, this.options.dispatchErrors.flow.flowCreationEnabled(), undefined);
+        return flow === undefined
+            ? this.invoke(dispatch.envelope, dispatch.codecs, handler, dispatch.context, dispatch.fields, dispatch.signal)
+            : (0, flow_context_1.runWithFlow)(flow, () => this.invoke(dispatch.envelope, dispatch.codecs, handler, dispatch.context, dispatch.fields, dispatch.signal));
+    }
+    completeRequest(dispatch, invocation) {
+        if (invocation === HANDLER_FILTER_REJECTED) {
+            return this.failRequest(dispatch, (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `A handler filter rejected '${this.options.channelName}:${dispatch.fields.packetName}'.`));
+        }
+        let written;
         try {
-            const flow = (0, flow_context_1.createInboundFlow)(dispatch.fields.flowId, dispatch.fields.flowOrigin, this.options.dispatchErrors.flow.flowCreationEnabled(), undefined);
-            const invocation = await (0, flow_context_1.runWithFlow)(flow, () => this.invoke(dispatch.envelope, dispatch.codecs, dispatch.handler, dispatch.context, dispatch.fields, dispatch.signal));
-            if (!invocation.handlerInvoked) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `A handler filter rejected '${this.options.channelName}:${dispatch.fields.packetName}'.`);
-            }
-            reply = invocation.value;
+            written = dispatch.writeReply(invocation);
         }
         catch (error) {
-            try {
-                await dispatch.writeError(error);
-            }
-            catch (replyError) {
-                // Spec 26 §3.1: a failed reply write means the reply delivery path is
-                // gone; `unexpected_reply` names a surplus/late reply instead.
-                this.report(dispatch.fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.ReplyPathMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, replyError);
-                return;
-            }
-            this.report(dispatch.fields, this.failureReason(error), ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError, error);
+            this.replyPathMissing(dispatch.fields, error);
             return;
         }
-        try {
-            await dispatch.writeReply(reply);
+        if (written === undefined) {
             this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, dispatch.fields);
+            return;
         }
-        catch (error) {
-            // Spec 26 §3.1: a failed reply write means the reply delivery path is
-            // gone; `unexpected_reply` names a surplus/late reply instead.
-            this.report(dispatch.fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.ReplyPathMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, error);
+        return written.then(() => this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, dispatch.fields), (error) => this.replyPathMissing(dispatch.fields, error));
+    }
+    replyPathMissing(fields, error) {
+        // Spec 26 §3.1: a failed reply write means the reply delivery path is
+        // gone; `unexpected_reply` names a surplus/late reply instead.
+        this.report(fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.ReplyPathMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, error);
+    }
+    async failRequest(dispatch, error) {
+        try {
+            await dispatch.writeError(error);
         }
+        catch (replyError) {
+            this.replyPathMissing(dispatch.fields, replyError);
+            return;
+        }
+        this.report(dispatch.fields, this.failureReason(error), ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError, error);
     }
     dropMissingReplyPath(fields) {
         this.report(fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.ReplyPathMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
@@ -99,8 +151,7 @@ class ZLinkChannelDispatchPipeline {
      */
     async dispatchMalformed(input) {
         const { info } = input;
-        const isRequest = info.kind === 1 /* ZLinkChannelMessageKind.Request */ ||
-            (info.kind === undefined && input.transportRequest);
+        const isRequest = input.transportRequest;
         let replied = false;
         if (isRequest && input.writeProtocolError !== undefined && info.correlationId !== undefined) {
             const protocolError = new contracts_1.ZLinkFrameworkException(contracts_1.ZLinkFrameworkErrorKind.ProtocolError, `Channel '${this.options.channelName}' received a malformed envelope.`);
@@ -126,15 +177,18 @@ class ZLinkChannelDispatchPipeline {
             error: input.error
         });
     }
-    async invoke(envelope, codecs, handler, context, fields, signal) {
+    invoke(envelope, codecs, handler, context, fields, signal) {
         (0, application_job_queue_scope_1.releaseApplicationJobPermitBeforeHandler)();
         if (this.filters.length === 0) {
             //  Fast path for the dominant unfiltered dispatch: skip the filter
             //  context object and chain machinery entirely.
             const payload = (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
             this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, fields);
-            return { handlerInvoked: true, value: await handler.handle(payload, context) };
+            return handler.handle(payload, context);
         }
+        return this.invokeFiltered(envelope, codecs, handler, context, fields, signal);
+    }
+    async invokeFiltered(envelope, codecs, handler, context, fields, signal) {
         let value;
         const handlerInvoked = await (0, handlers_1.invokeZLinkHandlerFilters)(this.filters, this.createFilterContext(context, fields), async () => {
             // Filters are the channel admission gate. Decode only after they have
@@ -143,7 +197,7 @@ class ZLinkChannelDispatchPipeline {
             this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, fields);
             value = await handler.handle(payload, context);
         }, signal);
-        return { handlerInvoked, value };
+        return handlerInvoked ? value : HANDLER_FILTER_REJECTED;
     }
     createFilterContext(context, fields) {
         const dispatchKind = this.dispatchKind(context, fields);
@@ -222,6 +276,7 @@ class ZLinkChannelDispatchPipeline {
     }
 }
 exports.ZLinkChannelDispatchPipeline = ZLinkChannelDispatchPipeline;
+const HANDLER_FILTER_REJECTED = Symbol('handler-filter-rejected');
 const DEFAULT_UNHANDLED_DISPATCH = {
     request: contracts_1.ZLinkUnhandledDispatchAction.ReplyError,
     send: contracts_1.ZLinkUnhandledDispatchAction.LogAndDrop,

package/dist/runtime/channels/channel-dispatch-services.d.ts

@@ -43,6 +43,7 @@ export declare class ZLinkChannelDispatchServices {
     channelSendHandler(handlerType: Type): ZLinkChannelSendHandler;
     routeRequestHandler(handlerType: Type): ZLinkRouteRuntimeRequestHandler;
     routeSendHandler(handlerType: Type): ZLinkRouteRuntimeSendHandler;
+    private invokeScopeFreeHandler;
     private invokeHandlerFilters;
     private withHandlerScope;
     beginOutbound(outcome: ZLinkMessageFlowOutcome, result?: ZLinkRuntimeMessageFlowResult): ZLinkChannelOutboundTracePoint | undefined;