@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,329 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkSpotPublisherClient = exports.DefaultZLinkRouteClient = exports.DefaultZLinkFanoutClient = exports.DefaultZLinkChannelClient = void 0;
+const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const submission_result_1 = require("../messaging/submission-result");
+const abort_1 = require("../abort");
+const execution_1 = require("../execution");
+const spot_outbound_1 = require("../spots/spot-outbound");
+const packet_name_1 = require("../messaging/packet-name");
+class DefaultZLinkChannelClient {
+    registration;
+    transport;
+    constructor(registration, transport) {
+        this.registration = registration;
+        this.transport = transport;
+    }
+    sendToChannel(channelName, message) {
+        return new DefaultZLinkSendCall(() => this.requireChannel(channelName), async (packetName, metadata, signal) => normalizeSubmitResult(await this.requireTransport().send(channelName, packetName, message, signal, metadata)));
+    }
+    requestToChannel(channelName, request) {
+        return new DefaultZLinkRequestCall(() => this.requireChannel(channelName), (packetName, timeoutMs, metadata, signal) => this.requireTransport().request(channelName, packetName, request, timeoutMs, signal, metadata), this.defaultRequestTimeout(channelName));
+    }
+    defaultRequestTimeout(channelName) {
+        return this.registration.channels.get(channelName)?.requestTimeoutMs
+            ?? this.registration.requestTimeoutMs
+            ?? 30_000;
+    }
+    requireChannel(channelName) {
+        const channel = this.registration.channels.get(channelName);
+        if (channel === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `Channel client '${channelName}' is not registered.`);
+        }
+        if (channel.client === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, `Channel client role '${channelName}' is not configured.`);
+        }
+    }
+    requireTransport() {
+        const transport = typeof this.transport === 'function'
+            ? this.transport()
+            : this.transport;
+        if (transport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Channel runtime is not started.');
+        }
+        return transport;
+    }
+}
+exports.DefaultZLinkChannelClient = DefaultZLinkChannelClient;
+class DefaultZLinkFanoutClient {
+    registration;
+    transport;
+    constructor(registration, transport) {
+        this.registration = registration;
+        this.transport = transport;
+    }
+    publish(channelName, topicOrEvent, explicitEvent) {
+        const hasExplicitTopic = arguments.length === 3;
+        const event = hasExplicitTopic ? explicitEvent : topicOrEvent;
+        const topic = hasExplicitTopic
+            ? topicOrEvent
+            : (0, packet_name_1.resolveFrameworkPacketName)(event, undefined, 'Fanout');
+        const packetName = (0, packet_name_1.resolveFrameworkPacketName)(event, undefined, 'Fanout');
+        return new DefaultZLinkFanoutPublishCall(() => this.requirePublisherChannel(channelName), async (signal) => ({
+            status: (await this.requireTransport().publish(channelName, topic, packetName, event, signal)).status
+        }));
+    }
+    getListenerStatus(channelName) {
+        this.requirePublisherChannel(channelName);
+        const status = this.requireTransport().getFanoutListenerStatus?.(channelName);
+        if (status === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Fanout publisher '${channelName}' has not reported a bound listener.`);
+        }
+        return status;
+    }
+    requirePublisherChannel(channelName) {
+        if (!this.registration.fanoutPublishers.has(channelName)) {
+            throw new configuration_1.ZLinkConfigurationException(`Channel '${channelName}' does not have a publisher capability.`);
+        }
+    }
+    requireTransport() {
+        const transport = typeof this.transport === 'function'
+            ? this.transport()
+            : this.transport;
+        if (transport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Channel runtime is not started.');
+        }
+        return transport;
+    }
+}
+exports.DefaultZLinkFanoutClient = DefaultZLinkFanoutClient;
+class DefaultZLinkRouteClient {
+    registration;
+    transport;
+    spotRouterChannelIdForMesh;
+    constructor(registration, transport, spotRouterChannelIdForMesh = (meshName) => meshName) {
+        this.registration = registration;
+        this.transport = transport;
+        this.spotRouterChannelIdForMesh = spotRouterChannelIdForMesh;
+    }
+    sendToNode(meshName, targetNodeRid, message) {
+        return new DefaultZLinkSendCall(() => this.requireMesh(meshName), async (packetName, metadata, signal) => normalizeSubmitResult(await this.requireTransport().submit(meshName, targetNodeRid, packetName, message, signal, metadata)));
+    }
+    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));
+    }
+    sendToChannel(channelName, message) {
+        return new DefaultZLinkSendCall(() => { this.resolveMeshChannel(channelName); }, async (packetName, metadata, signal) => {
+            const meshName = this.resolveMeshChannel(channelName);
+            return normalizeSubmitResult(await this.requireTransport().submitToChannel(meshName, channelName, packetName, message, signal, metadata));
+        });
+    }
+    requestToChannel(channelName, request) {
+        return new DefaultZLinkRequestCall(() => { this.resolveMeshChannel(channelName); }, (packetName, timeoutMs, metadata, signal) => {
+            const meshName = this.resolveMeshChannel(channelName);
+            return this.requireTransport().requestToChannel(meshName, channelName, packetName, request, timeoutMs, signal, metadata);
+        }, this.defaultRequestTimeoutForChannel(channelName));
+    }
+    sendToSpot(spot, message) {
+        return new DefaultZLinkSendCall(() => { this.requireSpotTransport(); }, async (_packetName, metadata, signal) => {
+            await (0, spot_outbound_1.sendToSpotHandle)(this.requireSpotTransport(), spot, message, {
+                signal,
+                metadata,
+                spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
+            });
+            return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+        });
+    }
+    requestToSpot(spot, request) {
+        return new DefaultZLinkRequestCall(() => { this.requireSpotTransport(); }, (_packetName, timeoutMs, metadata, signal) => (0, spot_outbound_1.requestToSpotHandle)(this.requireSpotTransport(), spot, request, {
+            timeoutMs,
+            signal,
+            metadata,
+            spotRouterChannelIdForMesh: this.spotRouterChannelIdForMesh
+        }), this.registration.requestTimeoutMs ?? 30_000);
+    }
+    defaultRequestTimeout(meshName) {
+        return this.registration.spotNodes.get(meshName)?.requestTimeoutMs
+            ?? this.registration.routeChannelOptions.get(meshName)?.requestTimeoutMs
+            ?? this.registration.requestTimeoutMs
+            ?? 30_000;
+    }
+    requireMesh(meshName) {
+        if (!this.registration.spotNodes.has(meshName) && !this.registration.routeChannels.has(meshName)) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh '${meshName}' is not registered.`);
+        }
+    }
+    resolveMeshChannel(channelName) {
+        const matches = [...this.registration.spotNodes.entries()]
+            .filter(([, mesh]) => Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName))
+            .map(([meshName]) => meshName);
+        if (matches.length === 0) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `RouteMesh channel '${channelName}' is not registered.`);
+        }
+        if (matches.length !== 1) {
+            throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' must be unique across the Framework host.`);
+        }
+        return matches[0];
+    }
+    defaultRequestTimeoutForChannel(channelName) {
+        const match = [...this.registration.spotNodes.entries()]
+            .find(([, mesh]) => Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName));
+        return match?.[1].requestTimeoutMs
+            ?? this.registration.requestTimeoutMs
+            ?? 30_000;
+    }
+    requireTransport() {
+        if (this.transport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Route channel runtime is not started.');
+        }
+        return this.transport;
+    }
+    requireSpotTransport() {
+        const transport = this.requireTransport();
+        if (transport.sendToSpot === undefined || transport.requestToSpot === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Route channel runtime does not support SpotHandle messaging.');
+        }
+        return transport;
+    }
+}
+exports.DefaultZLinkRouteClient = DefaultZLinkRouteClient;
+class DefaultZLinkSpotPublisherClient {
+    registration;
+    transport;
+    constructor(registration, transport) {
+        this.registration = registration;
+        this.transport = transport;
+    }
+    publish(meshName, channelName, topic, event) {
+        return new DefaultZLinkPublishCall(() => this.requireMeshChannel(meshName, channelName), (packetName, metadata, signal) => this.requireTransport().publish(meshName, channelName, topic, packetName, event, signal, metadata));
+    }
+    requireMeshChannel(meshName, channelName) {
+        const mesh = this.registration.spotNodes.get(meshName);
+        if (mesh === undefined || !Object.prototype.hasOwnProperty.call(mesh.meshChannels ?? {}, channelName)) {
+            throw new configuration_1.ZLinkConfigurationException(`Channel '${channelName}' is not registered in RouteMesh '${meshName}'.`);
+        }
+    }
+    requireTransport() {
+        if (this.transport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('SPOT publisher runtime is not started.');
+        }
+        return this.transport;
+    }
+}
+exports.DefaultZLinkSpotPublisherClient = DefaultZLinkSpotPublisherClient;
+class DefaultZLinkSendCall {
+    validate;
+    submitter;
+    selectedMetadata = new Map();
+    executed = false;
+    constructor(validate, submitter) {
+        this.validate = validate;
+        this.submitter = submitter;
+    }
+    metadata(keyOrMetadata, value) {
+        ensureNotExecuted(this.executed);
+        if (typeof keyOrMetadata === 'string') {
+            this.selectedMetadata.set(keyOrMetadata, value);
+        }
+        else {
+            for (const [key, selectedValue] of keyOrMetadata.values) {
+                this.selectedMetadata.set(key, selectedValue);
+            }
+        }
+        return this;
+    }
+    async submit(signal) {
+        ensureNotExecuted(this.executed);
+        this.validate();
+        this.executed = true;
+        (0, abort_1.throwIfAborted)(signal);
+        const result = await this.submitter(undefined, new Map(this.selectedMetadata), signal);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'One-way send');
+    }
+}
+function ensureNotExecuted(executed) {
+    if (executed) {
+        (0, submission_result_1.throwAlreadySubmitted)('ZLink call');
+    }
+}
+function normalizeSubmitResult(result) {
+    return result ?? { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+}
+class DefaultZLinkRequestCall {
+    validate;
+    submitter;
+    defaultRequestTimeoutMs;
+    timeoutMs;
+    selectedMetadata = new Map();
+    turn = (0, execution_1.captureZLinkSpotSerialTurn)();
+    constructor(validate, submitter, defaultRequestTimeoutMs) {
+        this.validate = validate;
+        this.submitter = submitter;
+        this.defaultRequestTimeoutMs = defaultRequestTimeoutMs;
+    }
+    metadata(keyOrMetadata, value) {
+        if (typeof keyOrMetadata === 'string') {
+            this.selectedMetadata.set(keyOrMetadata, value);
+        }
+        else {
+            for (const [key, selectedValue] of keyOrMetadata.values) {
+                this.selectedMetadata.set(key, selectedValue);
+            }
+        }
+        return this;
+    }
+    timeout(timeoutMs) {
+        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);
+    }
+    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);
+    }
+}
+class DefaultZLinkPublishCall {
+    validate;
+    submitter;
+    selectedMetadata = new Map();
+    executed = false;
+    constructor(validate, submitter) {
+        this.validate = validate;
+        this.submitter = submitter;
+    }
+    metadata(keyOrMetadata, value) {
+        ensureNotExecuted(this.executed);
+        if (typeof keyOrMetadata === 'string') {
+            this.selectedMetadata.set(keyOrMetadata, value);
+        }
+        else {
+            for (const [key, selectedValue] of keyOrMetadata.values) {
+                this.selectedMetadata.set(key, selectedValue);
+            }
+        }
+        return this;
+    }
+    async submit(signal) {
+        ensureNotExecuted(this.executed);
+        this.validate();
+        this.executed = true;
+        (0, abort_1.throwIfAborted)(signal);
+        const result = await this.submitter(undefined, new Map(this.selectedMetadata), signal);
+        (0, submission_result_1.requirePublishCompletion)(result, 'Logical Multicast publish');
+    }
+}
+class DefaultZLinkFanoutPublishCall {
+    validate;
+    submitter;
+    executed = false;
+    constructor(validate, submitter) {
+        this.validate = validate;
+        this.submitter = submitter;
+    }
+    async submit(signal) {
+        ensureNotExecuted(this.executed);
+        this.validate();
+        this.executed = true;
+        (0, abort_1.throwIfAborted)(signal);
+        const result = await this.submitter(signal);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'Classic fanout publish');
+    }
+}

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

@@ -0,0 +1,76 @@
+import type { ZLinkMessageContext, ZLinkHandlerFilter, ZLinkUnhandledDispatchOptions, ZLinkFlowOrigin } from '../../contracts';
+import { ZLinkFrameworkException } from '../../contracts';
+import { ZLinkDispatchMessageKind, ZLinkDispatchErrorSurface } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { type ZLinkChannelEnvelope, type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+import type { ZLinkMalformedChannelHeaderInfo } from './channel-envelope-inspection';
+import type { ZLinkDispatchErrorReporter } from './dispatch-error-reporter';
+export interface ZLinkChannelDispatchPipelineOptions {
+    readonly dispatchErrors: ZLinkDispatchErrorReporter;
+    readonly surface: ZLinkDispatchErrorSurface;
+    readonly channelName: string;
+    readonly filters?: readonly ZLinkHandlerFilter[];
+    readonly unhandled?: ZLinkUnhandledDispatchOptions;
+}
+export interface ZLinkChannelDispatchFields {
+    readonly messageKind: ZLinkDispatchMessageKind;
+    readonly packetName: string;
+    readonly correlationId?: string;
+    readonly topic?: string;
+    readonly sourceRid?: string;
+    readonly flowId?: string;
+    readonly flowOrigin?: ZLinkFlowOrigin;
+}
+interface ZLinkChannelDispatchHandler<TContext extends ZLinkMessageContext, TResult> {
+    handle(payload: unknown, context: TContext): Promise<TResult> | TResult;
+}
+interface ZLinkOneWayDispatch<TContext extends ZLinkMessageContext> {
+    readonly fields: ZLinkChannelDispatchFields;
+    readonly envelope: ZLinkChannelEnvelope;
+    readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
+    readonly handler?: ZLinkChannelDispatchHandler<TContext, void>;
+    readonly context: TContext;
+    readonly signal?: AbortSignal;
+}
+interface ZLinkRequestDispatch<TContext extends ZLinkMessageContext> {
+    readonly fields: ZLinkChannelDispatchFields;
+    readonly envelope: ZLinkChannelEnvelope;
+    readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
+    readonly handler?: ZLinkChannelDispatchHandler<TContext, unknown>;
+    readonly context: TContext;
+    readonly signal?: AbortSignal;
+    readonly missingHandlerMessage: string;
+    readonly writeReply: (reply: unknown) => Promise<void>;
+    readonly writeError: (error: unknown) => 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>;
+    dropMissingReplyPath(fields: ZLinkChannelDispatchFields): void;
+    /**
+     * Terminal handling for an envelope that failed structural decoding.
+     * Requests receive a protocol error reply plus a
+     * `zlink.dispatch_error(invalid_frame/reply_error)` record; one-way frames
+     * are dropped with `invalid_frame/drop`. Identifiers are used only when
+     * they could be read from the invalid frame (spec 27 §7 — never fabricated).
+     */
+    dispatchMalformed(input: {
+        readonly info: ZLinkMalformedChannelHeaderInfo;
+        readonly error: unknown;
+        /** The transport exposed a reply path (e.g. a request sequence). */
+        readonly transportRequest: boolean;
+        readonly sourceRid?: string;
+        readonly writeProtocolError?: (error: ZLinkFrameworkException) => Promise<void>;
+    }): Promise<void>;
+    private invoke;
+    private createFilterContext;
+    private dispatchKind;
+    private report;
+    private trace;
+    private failureReason;
+    private applyOneWayUnhandled;
+}
+export {};

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

@@ -0,0 +1,237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkChannelDispatchPipeline = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const handlers_1 = require("../handlers");
+const channel_envelope_1 = require("./channel-envelope");
+const flow_context_1 = require("../diagnostics/flow-context");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+class ZLinkChannelDispatchPipeline {
+    options;
+    filters;
+    unhandled;
+    constructor(options) {
+        this.options = options;
+        this.filters = options.filters ?? [];
+        this.unhandled = options.unhandled ?? DEFAULT_UNHANDLED_DISPATCH;
+    }
+    async dispatchOneWay(dispatch) {
+        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;
+        }
+        try {
+            const flow = (0, flow_context_1.createInboundFlow)(dispatch.fields.flowId, dispatch.fields.flowOrigin, this.options.dispatchErrors.flow.flowCreationEnabled());
+            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);
+            }
+        }
+        catch (error) {
+            this.report(dispatch.fields, this.failureReason(error), ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop, error);
+        }
+    }
+    async dispatchRequest(dispatch) {
+        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;
+        }
+        let reply;
+        try {
+            const flow = (0, flow_context_1.createInboundFlow)(dispatch.fields.flowId, dispatch.fields.flowOrigin, this.options.dispatchErrors.flow.flowCreationEnabled());
+            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;
+        }
+        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);
+            return;
+        }
+        try {
+            await dispatch.writeReply(reply);
+            this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied, dispatch.fields);
+        }
+        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);
+        }
+    }
+    dropMissingReplyPath(fields) {
+        this.report(fields, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.ReplyPathMissing, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
+    }
+    /**
+     * Terminal handling for an envelope that failed structural decoding.
+     * Requests receive a protocol error reply plus a
+     * `zlink.dispatch_error(invalid_frame/reply_error)` record; one-way frames
+     * are dropped with `invalid_frame/drop`. Identifiers are used only when
+     * they could be read from the invalid frame (spec 27 §7 — never fabricated).
+     */
+    async dispatchMalformed(input) {
+        const { info } = input;
+        const isRequest = info.kind === 1 /* ZLinkChannelMessageKind.Request */
+            || (info.kind === undefined && 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.`);
+            try {
+                await input.writeProtocolError(protocolError);
+                replied = true;
+            }
+            catch {
+                // The reply path failed; the record below downgrades to a drop.
+            }
+        }
+        this.options.dispatchErrors.report({
+            surface: this.options.surface,
+            messageKind: isRequest ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.InvalidFrame,
+            action: replied ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+            packetName: info.messageName,
+            channelName: this.options.channelName,
+            sourceRid: input.sourceRid,
+            correlationId: info.correlationId,
+            flowId: info.flowId,
+            flowOrigin: info.flowOrigin,
+            error: input.error
+        });
+    }
+    async 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) };
+        }
+        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
+            // allowed the handler turn to proceed.
+            const payload = (0, channel_envelope_1.decodeChannelPayload)(envelope, codecs);
+            this.trace(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched, fields);
+            value = await handler.handle(payload, context);
+        }, signal);
+        return { handlerInvoked, value };
+    }
+    createFilterContext(context, fields) {
+        const dispatchKind = this.dispatchKind(context, fields);
+        return {
+            meshName: dispatchKind === contracts_1.ZLinkHandlerDispatchKind.ClassicFanout
+                ? undefined
+                : context.meshName,
+            channelName: context.channelName,
+            packetName: context.packetName,
+            contentType: context.contentType,
+            metadata: context.metadata,
+            correlationId: context.correlationId,
+            dispatchKind
+        };
+    }
+    dispatchKind(context, fields) {
+        if (fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish) {
+            return contracts_1.ZLinkHandlerDispatchKind.ClassicFanout;
+        }
+        const nodeDirect = this.options.surface === ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.RouteMeshChannel
+            && context.channelName === undefined;
+        if (fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request) {
+            return nodeDirect
+                ? contracts_1.ZLinkHandlerDispatchKind.NodeDirectRequest
+                : contracts_1.ZLinkHandlerDispatchKind.ChannelRequest;
+        }
+        return nodeDirect
+            ? contracts_1.ZLinkHandlerDispatchKind.NodeDirectSend
+            : contracts_1.ZLinkHandlerDispatchKind.ChannelSend;
+    }
+    report(fields, reason, action, error) {
+        const classicFanout = fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish;
+        this.options.dispatchErrors.report({
+            surface: classicFanout
+                ? ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.ClassicFanout
+                : this.options.surface,
+            messageKind: classicFanout
+                ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send
+                : fields.messageKind,
+            reason,
+            action,
+            packetName: fields.packetName,
+            channelName: this.options.channelName,
+            topic: fields.topic,
+            sourceRid: fields.sourceRid,
+            correlationId: fields.correlationId,
+            flowId: fields.flowId,
+            flowOrigin: fields.flowOrigin,
+            error
+        });
+    }
+    trace(outcome, fields) {
+        if (fields.messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Publish)
+            return;
+        const flow = this.options.dispatchErrors.flow;
+        const tracePoint = flow.begin(outcome, undefined, fields.flowId);
+        if (tracePoint === undefined)
+            return;
+        tracePoint.trace({
+            outcome,
+            surface: this.options.surface,
+            messageKind: fields.messageKind,
+            packetName: fields.packetName,
+            channelName: this.options.channelName,
+            topic: fields.topic,
+            sourceRid: fields.sourceRid,
+            correlationId: fields.correlationId,
+            flowId: fields.flowId,
+            flowOrigin: fields.flowOrigin
+        });
+    }
+    failureReason(error) {
+        return error instanceof contracts_1.ZLinkFrameworkException
+            && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PayloadDecodeFailed
+            ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.PayloadDecodeFailed
+            : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+    }
+    applyOneWayUnhandled(action, fields) {
+        if (action === contracts_1.ZLinkUnhandledDispatchAction.Throw) {
+            throw new Error(`No ${fields.messageKind} handler is registered for '${this.options.channelName}:${fields.packetName}'.`);
+        }
+    }
+}
+exports.ZLinkChannelDispatchPipeline = ZLinkChannelDispatchPipeline;
+const DEFAULT_UNHANDLED_DISPATCH = {
+    request: contracts_1.ZLinkUnhandledDispatchAction.ReplyError,
+    send: contracts_1.ZLinkUnhandledDispatchAction.LogAndDrop,
+    publish: contracts_1.ZLinkUnhandledDispatchAction.LogAndDrop
+};