@zlink-systems/framework 0.26.0 → 0.28.0

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

@@ -1,14 +1,16 @@
-import { type ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
-import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
 import { ZLinkFrameworkException } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
+import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import { type ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import { type ZLinkMessageFlowTracer } from '../diagnostics';
 import { type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
-import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import type { ZLinkSpotRoutedSendOptions, ZLinkSpotRoutedRequestOptions } from '../spots/spot-outbound';
 import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
 export interface ZLinkChannelClientTransport {
-    send(channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
+    send(channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
     request<TReply>(channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): 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>): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
@@ -19,14 +21,12 @@ export interface ZLinkSpotPublisherClientTransport {
     publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
 }
 export interface ZLinkRouteClientTransport {
-    submit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
+    submit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
     request<TReply>(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
-    submitToChannel(meshName: string, channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
+    submitToChannel(meshName: string, channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): void | ZLinkSubmitResult | Promise<void | ZLinkSubmitResult>;
     requestToChannel<TReply>(meshName: string, channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
     sendToSpot?(spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: {
         readonly packetName?: string;
-        readonly timeoutMs?: number;
-        readonly signal?: AbortSignal;
         readonly metadata?: ReadonlyMap<string, string>;
     }): Promise<ZLinkSubmitResult>;
     requestToSpot?<TReply = unknown>(spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: {
@@ -37,16 +37,16 @@ export interface ZLinkRouteClientTransport {
     }): Promise<TReply>;
 }
 interface ZLinkChannelTransportRuntime {
-    send(channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    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>;
     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>;
     canRouteChannel(routerChannelId: string): boolean;
     canRoutePacketChannel(routerChannelId: string): boolean;
-    routeSubmit(routerChannelId: string, targetNodeRid: string, packetName: string | undefined, message: 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>;
-    routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
-    routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<void>;
+    routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, 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>;
     routeRequestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
@@ -61,41 +61,31 @@ export declare class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTrans
     private readonly localNodeSubmit?;
     private readonly metrics?;
     private readonly flowCreationEnabled;
+    private readonly outboundFlow;
     constructor(manager: () => ZLinkChannelTransportRuntime | undefined, routeChannelPredicate?: ((routerChannelId: string) => boolean) | undefined, meshRuntime?: (() => {
         readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
         readonly meshCompletionTable: (meshName: string) => ZLinkMeshCompletionTable | undefined;
-    } | undefined) | undefined, codecs?: ZLinkChannelEnvelopeCodecRegistry | undefined, manualNodeTarget?: ((meshName: string, targetNodeRid: string) => boolean | undefined) | undefined, localNodeSubmit?: ((meshName: string, sourceNodeRid: string, parts: readonly MessageLike[]) => ZLinkSubmitResult) | undefined, metrics?: ZLinkRuntimeMetrics | undefined, flowCreationEnabled?: () => boolean);
+    } | undefined) | undefined, codecs?: ZLinkChannelEnvelopeCodecRegistry | undefined, manualNodeTarget?: ((meshName: string, targetNodeRid: string) => boolean | undefined) | undefined, localNodeSubmit?: ((meshName: string, sourceNodeRid: string, parts: readonly MessageLike[]) => ZLinkSubmitResult) | undefined, metrics?: ZLinkRuntimeMetrics | undefined, flowCreationEnabled?: () => boolean, outboundFlow?: () => ZLinkMessageFlowTracer | undefined);
     canRouteChannel(routerChannelId: string): boolean;
     canRoutePacketChannel(routerChannelId: string): boolean;
-    submit(meshName: string, targetNodeRid: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
-    submitInfrastructure(meshName: string, targetNodeRid: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    submit(meshName: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    submitInfrastructure(meshName: string, targetNodeRid: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private submitNode;
     request<TReply>(meshName: string, targetNodeRid: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
     private requestScoped;
-    submitToChannel(meshName: string, channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+    private traceNodeRequest;
+    submitToChannel(meshName: string, channelName: string, packetName: string | undefined, message: unknown, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private submitToChannelScoped;
     requestToChannel<TReply>(meshName: string, channelName: string, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
     private requestToChannelScoped;
     private submitRequestOperation;
-    sendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: {
-        readonly packetName?: string;
-        readonly timeoutMs?: number;
-        readonly signal?: AbortSignal;
-        readonly metadata?: ReadonlyMap<string, string>;
-    }): Promise<ZLinkSubmitResult>;
+    sendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: ZLinkSpotRoutedSendOptions): Promise<ZLinkSubmitResult>;
     private sendToSpotScoped;
     sendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: {
         readonly packetName?: string;
-        readonly timeoutMs?: number;
-        readonly signal?: AbortSignal;
         readonly metadata?: ReadonlyMap<string, string>;
     }): Promise<ZLinkSubmitResult>;
-    requestToSpot<TReply = unknown>(spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: {
-        readonly packetName?: string;
-        readonly timeoutMs?: number;
-        readonly signal?: AbortSignal;
-        readonly metadata?: ReadonlyMap<string, string>;
-    }): Promise<TReply>;
+    requestToSpot<TReply = unknown>(spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: ZLinkSpotRoutedRequestOptions): Promise<TReply>;
     private requestToSpotScoped;
     requestFromSpotToSpot<TReply = unknown>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: {
         readonly packetName?: string;

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

@@ -2,19 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkRuntimeRouteTransport = void 0;
 exports.meshRequestFailure = meshRequestFailure;
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const runtime_message_1 = require("../backend/runtime-message");
-const runtime_values_1 = require("../backend/runtime-values");
 const contracts_1 = require("../../contracts");
-const submission_result_1 = require("../messaging/submission-result");
-const configuration_1 = require("../configuration");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const Spots_1 = require("../../contracts/Spots");
 const abort_1 = require("../abort");
 const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const runtime_message_1 = require("../backend/runtime-message");
+const runtime_values_1 = require("../backend/runtime-values");
+const configuration_1 = require("../configuration");
+const flow_context_1 = require("../diagnostics/flow-context");
+const diagnostics_1 = require("../diagnostics");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const channel_outbound_operations_1 = require("./channel-outbound-operations");
+const service_stateful_registry_1 = require("../foundation/service-stateful-registry");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const submission_result_1 = require("../messaging/submission-result");
 const routing_id_1 = require("../routing-id");
 const channel_envelope_1 = require("./channel-envelope");
-const service_stateful_registry_1 = require("../foundation/service-stateful-registry");
-const flow_context_1 = require("../diagnostics/flow-context");
 class ZLinkRuntimeRouteTransport {
     manager;
     routeChannelPredicate;
@@ -24,7 +28,8 @@ class ZLinkRuntimeRouteTransport {
     localNodeSubmit;
     metrics;
     flowCreationEnabled;
-    constructor(manager, routeChannelPredicate = undefined, meshRuntime = undefined, codecs, manualNodeTarget, localNodeSubmit, metrics, flowCreationEnabled = () => true) {
+    outboundFlow;
+    constructor(manager, routeChannelPredicate = undefined, meshRuntime = undefined, codecs, manualNodeTarget, localNodeSubmit, metrics, flowCreationEnabled = () => true, outboundFlow = () => undefined) {
         this.manager = manager;
         this.routeChannelPredicate = routeChannelPredicate;
         this.meshRuntime = meshRuntime;
@@ -33,6 +38,7 @@ class ZLinkRuntimeRouteTransport {
         this.localNodeSubmit = localNodeSubmit;
         this.metrics = metrics;
         this.flowCreationEnabled = flowCreationEnabled;
+        this.outboundFlow = outboundFlow;
     }
     canRouteChannel(routerChannelId) {
         const manager = this.manager();
@@ -46,20 +52,19 @@ class ZLinkRuntimeRouteTransport {
             this.routeChannelPredicate?.(routerChannelId) ??
             false);
     }
-    async submit(meshName, targetNodeRid, packetName, message, signal, metadata) {
+    async submit(meshName, targetNodeRid, packetName, message, metadata) {
         // Call-scoped flow (spec 27 §4): the envelope flow pair lives only for
         // the duration of this outbound call, never in the caller's context.
-        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, false));
+        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitNode(meshName, targetNodeRid, packetName, message, metadata, false));
     }
-    async submitInfrastructure(meshName, targetNodeRid, packetName, message, signal, metadata) {
-        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, true));
+    async submitInfrastructure(meshName, targetNodeRid, packetName, message, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitNode(meshName, targetNodeRid, packetName, message, metadata, true));
     }
-    async submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, allowObjectClientTarget) {
+    async submitNode(meshName, targetNodeRid, packetName, message, metadata, allowObjectClientTarget) {
         const node = this.meshNode(meshName);
         if (node === undefined) {
-            return this.requireManager().routeSubmit(meshName, targetNodeRid, packetName, message, signal, metadata);
+            return this.requireManager().routeSubmit(meshName, targetNodeRid, packetName, message, metadata);
         }
-        (0, abort_1.throwIfAborted)(signal);
         if (!allowObjectClientTarget &&
             node.isObjectClientNodeDirectTarget?.((0, routing_id_1.toBackendRoutingId)(targetNodeRid)) === true) {
             return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
@@ -88,22 +93,51 @@ class ZLinkRuntimeRouteTransport {
         if (node === undefined) {
             return this.requireManager().routeRequest(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata);
         }
-        (0, abort_1.throwIfAborted)(signal);
-        if (node.isObjectClientNodeDirectTarget?.((0, routing_id_1.toBackendRoutingId)(targetNodeRid)) === true) {
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`);
+        const correlationId = (0, channel_envelope_1.newChannelCorrelationId)();
+        try {
+            (0, abort_1.throwIfAborted)(signal);
+            if (node.isObjectClientNodeDirectTarget?.((0, routing_id_1.toBackendRoutingId)(targetNodeRid)) === true) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `MeshNode '${meshName}' target '${targetNodeRid}' is an Object Client.`);
+            }
+            const parts = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, meshName, packetName, request, timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, metadata, correlationId);
+            const completion = await this.submitRequestOperation(meshName, timeoutMs, signal, `MeshNode '${meshName}' request to node '${targetNodeRid}'`, (remainingTimeoutMs) => {
+                const operationId = node.requestToNode((0, routing_id_1.toBackendRoutingId)(targetNodeRid), parts, {
+                    flags: 1,
+                    timeoutMs: remainingTimeoutMs
+                });
+                this.traceNodeRequest(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent, undefined, meshName, targetNodeRid, packetName, correlationId);
+                return operationId;
+            });
+            const reply = this.decodeMeshReply(meshName, completion);
+            this.traceNodeRequest(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived, 'succeeded', meshName, targetNodeRid, packetName, correlationId);
+            return reply;
+        }
+        catch (error) {
+            if (!(0, channel_outbound_operations_1.isRemoteChannelErrorReply)(error)) {
+                this.traceNodeRequest(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived, (0, channel_outbound_operations_1.requestTerminalResult)(error, signal), meshName, targetNodeRid, packetName, correlationId, error);
+            }
+            throw error;
         }
-        const parts = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, meshName, packetName, request, timeoutMs ?? 30_000, metadata);
-        const completion = await this.submitRequestOperation(meshName, timeoutMs, signal, `MeshNode '${meshName}' request to node '${targetNodeRid}'`, (remainingTimeoutMs) => node.requestToNode((0, routing_id_1.toBackendRoutingId)(targetNodeRid), parts, {
-            flags: 1,
-            timeoutMs: remainingTimeoutMs
-        }));
-        return this.decodeMeshReply(meshName, completion);
-    }
-    submitToChannel(meshName, channelName, packetName, message, signal, metadata) {
-        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitToChannelScoped(meshName, channelName, packetName, message, signal, metadata));
     }
-    async submitToChannelScoped(meshName, channelName, packetName, message, signal, metadata) {
-        (0, abort_1.throwIfAborted)(signal);
+    traceNodeRequest(outcome, result, meshName, targetRid, packetName, correlationId, error) {
+        if (!this.flowCreationEnabled())
+            return;
+        (0, diagnostics_1.flowIfEnabled)(this.outboundFlow(), outcome, result)?.trace({
+            outcome,
+            result,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.Node,
+            messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
+            meshName,
+            targetRid,
+            packetName,
+            correlationId,
+            ...(error instanceof Error ? { errorType: error.name, errorMessage: error.message } : {})
+        });
+    }
+    submitToChannel(meshName, channelName, packetName, message, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.flowCreationEnabled(), () => this.submitToChannelScoped(meshName, channelName, packetName, message, metadata));
+    }
+    async submitToChannelScoped(meshName, channelName, packetName, message, metadata) {
         const node = this.requireMeshNode(meshName);
         const parts = this.encodeMessage(3 /* ZLinkChannelMessageKind.Command */, channelName, packetName, message, undefined, metadata);
         const operation = `MeshNode '${meshName}' send to channel '${channelName}'`;
@@ -124,7 +158,7 @@ class ZLinkRuntimeRouteTransport {
     async requestToChannelScoped(meshName, channelName, packetName, request, timeoutMs, signal, metadata) {
         (0, abort_1.throwIfAborted)(signal);
         const node = this.requireMeshNode(meshName);
-        const parts = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, channelName, packetName, request, timeoutMs ?? 30_000, metadata);
+        const parts = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, channelName, packetName, request, timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, metadata);
         const metric = this.metrics?.startRequest(meshName, 'channel');
         try {
             const completion = await this.submitRequestOperation(meshName, timeoutMs, signal, `MeshNode '${meshName}' request to channel '${channelName}'`, (remainingTimeoutMs) => node.requestToChannel(channelName, parts, { flags: 1, timeoutMs: remainingTimeoutMs }));
@@ -141,7 +175,7 @@ class ZLinkRuntimeRouteTransport {
         }
     }
     async submitRequestOperation(meshName, timeoutMs, signal, operation, attempt) {
-        const effectiveTimeoutMs = Math.max(1, timeoutMs ?? 30_000);
+        const effectiveTimeoutMs = Math.max(1, timeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS);
         const deadlineMs = performance.now() + effectiveTimeoutMs;
         const remainingTimeoutMs = deadlineMs - performance.now();
         if (remainingTimeoutMs <= 0) {
@@ -163,15 +197,14 @@ class ZLinkRuntimeRouteTransport {
             if (spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Instance) {
                 throw new configuration_1.ZLinkConfigurationException('Instance Spot routes require the MeshNode command 39 transport.');
             }
-            await this.requireManager().routeSendToSpot(spotRouteTarget, options.packetName, message, options.signal, options.metadata, options.timeoutMs);
+            await this.requireManager().routeSendToSpot(spotRouteTarget, options.packetName, message, options.metadata);
             return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
         }
-        (0, abort_1.throwIfAborted)(options.signal);
         const operation = `MeshNode '${spotRouteTarget.routerChannelId}' send to Spot '${spotRouteTarget.spotId}'`;
         try {
             const encoded = this.encodeMessage(3 /* ZLinkChannelMessageKind.Command */, spotRouteTarget.routerChannelId, options.packetName, message, undefined, options.metadata);
             if (spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Instance) {
-                return mapMeshSubmitResult(await node.sendToInstanceSpot(instanceSpotRouteFence(spotRouteTarget), encoded, undefined, options.metadata));
+                return mapMeshSubmitResult(await node.sendToInstanceSpot(instanceSpotRouteFence(spotRouteTarget), encoded, undefined, options.metadata, options.instanceSpot));
             }
             return mapMeshSubmitResult(await node
                 .entrySpot()
@@ -186,7 +219,7 @@ class ZLinkRuntimeRouteTransport {
         }
     }
     async sendFromSpotToSpot(sourceSpot, spotRouteTarget, message, options) {
-        await this.requireManager().routeSendFromSpotToSpot(sourceSpot, spotRouteTarget, options.packetName, message, options.signal, options.metadata, options.timeoutMs);
+        await this.requireManager().routeSendFromSpotToSpot(sourceSpot, spotRouteTarget, options.packetName, message, options.metadata);
         return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
     }
     requestToSpot(spotRouteTarget, request, options) {
@@ -206,7 +239,7 @@ class ZLinkRuntimeRouteTransport {
         try {
             const encoded = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, meshName, options.packetName, request, options.timeoutMs, options.metadata);
             completionPromise = this.completionTable(meshName).submit(() => spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Instance
-                ? node.requestInstanceSpot(instanceSpotRouteFence(spotRouteTarget), encoded, options.timeoutMs, undefined, options.metadata)
+                ? node.requestInstanceSpot(instanceSpotRouteFence(spotRouteTarget), encoded, options.timeoutMs, undefined, options.metadata, options.instanceSpot)
                 : node
                     .entrySpot()
                     .requestToSpot((0, routing_id_1.toBackendRoutingId)(spotRouteTarget.targetNodeRid), (0, routing_id_1.toBackendRoutingId)(spotRouteTarget.spotId), spotRouteTarget.targetSpotGeneration ?? 0n, encoded, {
@@ -311,8 +344,8 @@ class ZLinkRuntimeRouteTransport {
         }
         return table;
     }
-    encodeMessage(kind, channelName, packetName, message, timeoutMs, metadata) {
-        return (0, channel_envelope_1.encodeChannelEnvelopeParts)(kind, channelName, packetName, message, timeoutMs, undefined, this.codecs, undefined, this.flowCreationEnabled(), metadata);
+    encodeMessage(kind, channelName, packetName, message, timeoutMs, metadata, correlationId) {
+        return (0, channel_envelope_1.encodeChannelEnvelopeParts)(kind, channelName, packetName, message, timeoutMs, undefined, this.codecs, correlationId, this.flowCreationEnabled(), metadata);
     }
     async waitForMeshReply(meshName, completionPromise) {
         const completion = await completionPromise;
@@ -344,7 +377,7 @@ function directSpotRouteFence(target) {
         target.targetOwnerId === undefined ||
         target.ownerLeaseGeneration === undefined ||
         target.authorityStoreVersion === undefined) {
-        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `Spot '${String(target.spotId)}' has no complete Ready authority fence.`);
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Spot '${String(target.spotId)}' has no complete Ready authority fence.`);
     }
     return {
         spot: {
@@ -379,21 +412,7 @@ function instanceSpotRouteFence(target) {
     };
 }
 function mapMeshSubmitResult(result) {
-    switch (result) {
-        case runtime_values_1.SubmitResult.Ok:
-            return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
-        case runtime_values_1.SubmitResult.Backpressured:
-        case runtime_values_1.SubmitResult.NotAdmitted:
-            return { status: submission_result_1.ZLinkSubmitStatus.Backpressured };
-        case runtime_values_1.SubmitResult.NotFound:
-            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
-        case runtime_values_1.SubmitResult.NotConnected:
-            return { status: submission_result_1.ZLinkSubmitStatus.RouteNotConnected };
-        case runtime_values_1.SubmitResult.Terminated:
-            return { status: submission_result_1.ZLinkSubmitStatus.Shutdown };
-        default:
-            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, `Mesh submission failed with result ${result}.`);
-    }
+    return (0, submission_result_1.classifySubmitResult)(result, 'Mesh submission');
 }
 function mapMeshSubmissionError(error, operation) {
     if (error instanceof contracts_1.ZLinkFrameworkException) {
@@ -408,14 +427,13 @@ function mapMeshSubmissionError(error, operation) {
         return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale, `${operation} received a stale Spot authority fence: ${error.message}`, true, error);
     }
     if ((0, runtime_values_1.isZLinkBackendResultError)(error)) {
-        const notFound = error.result === runtime_values_1.SubmitResult.NotFound || error.result === 102;
-        const retriable = error.result === runtime_values_1.SubmitResult.Backpressured ||
-            error.result === runtime_values_1.SubmitResult.NotConnected ||
-            error.result === 109 ||
-            error.result === 113;
-        return (0, framework_errors_internal_1.createInternalFrameworkException)(notFound
-            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
-            : framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operation} failed with result ${error.result}.`, retriable, error);
+        const terminal = error.operation === 'request'
+            ? error.result
+            : (0, submission_result_1.submitToRequestResult)(error.result, error.phase);
+        if (terminal === runtime_values_1.RequestResult.NotFound) {
+            return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `${operation} failed with result ${error.result}.`, false, error);
+        }
+        return new contracts_1.ZLinkFrameworkException((0, framework_errors_internal_1.requestResultToPublicErrorKind)(terminal), `${operation} failed with result ${error.result}.`, error);
     }
     return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `${operation} failed before native submission completed: ${error instanceof Error ? error.message : String(error)}`, true, error);
 }

package/dist/runtime/channels/client-server-location-runtime.d.ts

@@ -1,6 +1,6 @@
 import { type ZLinkClientServerServerDescriptor } from '../../contracts/Locations';
 import { type ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
-import type { ZLinkFrameworkRegistration } from '../configuration';
+import { type ZLinkFrameworkRegistration } from '../configuration';
 import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
 import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
 /**

package/dist/runtime/channels/client-server-location-runtime.js

@@ -1,14 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkClientServerLocationRuntime = void 0;
+const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const Locations_1 = require("../../contracts/Locations");
 const Options_1 = require("../../contracts/Locations/Options");
-const configuration_1 = require("../configuration");
+const Stores_1 = require("../../contracts/Locations/Stores");
 const runtime_message_1 = require("../backend/runtime-message");
-const client_server_service_wire_1 = require("./client-server-service-wire");
-const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
-const state_lane_1 = require("../execution/state-lane");
 const runtime_values_1 = require("../backend/runtime-values");
+const configuration_1 = require("../configuration");
+const state_lane_1 = require("../execution/state-lane");
+const runtime_state_projections_1 = require("../foundation/runtime-state-projections");
+const client_server_service_wire_1 = require("./client-server-service-wire");
 /**
  * Owns the dedicated ClientServer discovery domain. It never converts these
  * descriptors into RouteMesh peer rows.
@@ -129,7 +131,7 @@ class ZLinkClientServerLocationRuntime {
                 lifecycleGeneration: identity.lifecycleGeneration,
                 descriptorRevision: 1n,
                 endpoint: identity.endpoint,
-                weight: channel.server.weight ?? 100,
+                weight: channel.server.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT,
                 state: Locations_1.ZLinkFrameworkRuntimeState.Serving,
                 securityIdentity: 'default',
                 ownerId: owner.ownerId,
@@ -193,7 +195,7 @@ class ZLinkClientServerLocationRuntime {
         const rows = [];
         let continuationToken;
         do {
-            const page = await this.store.listClientServers(channelName, { pageSize: 1000, continuationToken }, signal);
+            const page = await this.store.listClientServers(channelName, { pageSize: Stores_1.ZLINK_PROVIDER_MAX_PAGE_SIZE, continuationToken }, signal);
             rows.push(...page.items);
             continuationToken = page.continuationToken;
         } while (continuationToken !== undefined);
@@ -405,7 +407,7 @@ function sameDescriptor(left, right) {
         left.ownerId === right.ownerId &&
         left.leaseGeneration === right.leaseGeneration);
 }
-function toDiscoveryDescriptor(descriptor, effectiveMaxMessageBytes = 0x7fff_ffff) {
+function toDiscoveryDescriptor(descriptor, effectiveMaxMessageBytes = client_server_service_wire_1.DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT) {
     return {
         channelName: descriptor.channelName,
         serverRoutingId: String(descriptor.serverRid),
@@ -422,7 +424,7 @@ function requestAdmission(dealer, descriptor, timeoutMs) {
     const message = runtime_message_1.ZLinkBufferMessage.from((0, client_server_service_wire_1.encodeClientServerHello)({
         channelName: descriptor.channelName,
         securityIdentity: descriptor.securityIdentity,
-        normalizedEffectiveMaxMessageBytes: normalizedMessageLimit(dealer.maxMessageSize)
+        normalizedEffectiveMaxMessageBytes: (0, client_server_service_wire_1.normalizeClientServerMessageLimit)(dealer.maxMessageSize)
     }));
     return dealer.request(message, timeoutMs).then((parts) => {
         try {
@@ -464,6 +466,3 @@ function closeMessages(parts) {
     for (const part of parts)
         part.close();
 }
-function normalizedMessageLimit(value) {
-    return Number.isSafeInteger(value) && value > 0 ? Math.min(value, 0xffff_ffff) : 0x7fff_ffff;
-}

package/dist/runtime/channels/client-server-service-wire.d.ts

@@ -1,5 +1,10 @@
-import type { ZLinkClientServerServerDescriptor } from '../../contracts/Locations';
-import { ZLinkFrameworkRuntimeState } from '../../contracts/Locations';
+import { type ZLinkClientServerServerDescriptor, ZLinkFrameworkRuntimeState } from '../../contracts/Locations';
+export declare const DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT = 2147483647;
+export declare function normalizeClientServerMessageLimit(value: number): number;
+export declare enum ClientServerRejectReason {
+    ProtocolVersionUnsupported = 1,
+    AdmissionMismatch = 3
+}
 export interface ZLinkClientServerHello {
     readonly channelName: string;
     readonly securityIdentity: string;

package/dist/runtime/channels/client-server-service-wire.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZLinkClientServerServiceWireError = void 0;
+exports.ZLinkClientServerServiceWireError = exports.ClientServerRejectReason = exports.DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT = void 0;
+exports.normalizeClientServerMessageLimit = normalizeClientServerMessageLimit;
 exports.encodeClientServerHello = encodeClientServerHello;
 exports.encodeClientServerAdmit = encodeClientServerAdmit;
 exports.encodeClientServerUpdate = encodeClientServerUpdate;
@@ -9,12 +10,29 @@ exports.encodeClientServerLivenessProbe = encodeClientServerLivenessProbe;
 exports.encodeClientServerLivenessAck = encodeClientServerLivenessAck;
 exports.isClientServerControlFrame = isClientServerControlFrame;
 exports.decodeClientServerControl = decodeClientServerControl;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
+const EndpointNotation_1 = require("../../contracts/Configuration/EndpointNotation");
+const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const Locations_1 = require("../../contracts/Locations");
 const service_wire_binary_primitives_1 = require("../foundation/service-wire-binary-primitives");
-const EndpointNotation_1 = require("../../contracts/Configuration/EndpointNotation");
-const MAGIC_0 = 0x5a;
-const MAGIC_1 = 0x4d;
-const WIRE_MAJOR = 1;
+const service_wire_constants_generated_1 = require("../foundation/service-wire-constants.generated");
+exports.DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT = 0x7fff_ffff;
+function normalizeClientServerMessageLimit(value) {
+    return Number.isSafeInteger(value) && value > 0
+        ? Math.min(value, stream_wire_1.UINT32_MAX)
+        : exports.DEFAULT_CLIENT_SERVER_MESSAGE_LIMIT;
+}
+const CLIENT_SERVER_PREFIX_BYTES = 5;
+const CLIENT_SERVER_ROLE_BODY_MAX_BYTES = 0xffff;
+const CLIENT_SERVER_TEXT_MAX_BYTES = 4096;
+var ClientServerRejectReason;
+(function (ClientServerRejectReason) {
+    ClientServerRejectReason[ClientServerRejectReason["ProtocolVersionUnsupported"] = 1] = "ProtocolVersionUnsupported";
+    ClientServerRejectReason[ClientServerRejectReason["AdmissionMismatch"] = 3] = "AdmissionMismatch";
+})(ClientServerRejectReason || (exports.ClientServerRejectReason = ClientServerRejectReason = {}));
+const MAGIC_0 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[0];
+const MAGIC_1 = service_wire_constants_generated_1.SERVICE_WIRE_MAGIC[1];
+const WIRE_MAJOR = service_wire_constants_generated_1.SERVICE_WIRE_MAJOR;
 const TOPOLOGY_CLIENT_SERVER = 2;
 const ROLE_CLIENT = 1;
 const ROLE_SERVER = 2;
@@ -26,7 +44,7 @@ const COMMAND_UPDATE = 4;
 const COMMAND_LIVENESS_PROBE = 5;
 const COMMAND_LIVENESS_ACK = 6;
 const MAX_DESCRIPTOR_BYTES = 1024 * 1024;
-const MAX_U32 = 0xffff_ffff;
+const MAX_U32 = stream_wire_1.UINT32_MAX;
 const MAX_GENERATION = 0x7fffffffffffffffn;
 class ZLinkClientServerServiceWireError extends Error {
     constructor(message) {
@@ -58,7 +76,10 @@ function encodeClientServerLivenessAck(probeId) {
     return encodeLiveness(COMMAND_LIVENESS_ACK, probeId);
 }
 function isClientServerControlFrame(frame) {
-    return (frame.byteLength >= 5 && frame[0] === MAGIC_0 && frame[1] === MAGIC_1 && frame[2] === WIRE_MAJOR);
+    return (frame.byteLength >= CLIENT_SERVER_PREFIX_BYTES &&
+        frame[0] === MAGIC_0 &&
+        frame[1] === MAGIC_1 &&
+        frame[2] === WIRE_MAJOR);
 }
 function decodeClientServerControl(frame) {
     if (frame.byteLength > MAX_DESCRIPTOR_BYTES)
@@ -121,7 +142,7 @@ function encodeServerAdmission(command, descriptor, normalizedEffectiveMaxMessag
     return encodeAdmission(command, ROLE_SERVER, roleBody);
 }
 function encodeAdmission(command, role, roleBody) {
-    if (roleBody.byteLength > 0xffff)
+    if (roleBody.byteLength > CLIENT_SERVER_ROLE_BODY_MAX_BYTES)
         fail('ClientServer role body is oversized.');
     const admission = concat(Buffer.of(role), encodeU16(roleBody.byteLength), roleBody);
     const result = concat(prefix(command), Buffer.of(TOPOLOGY_CLIENT_SERVER), encodeU32(admission.byteLength), admission);
@@ -149,7 +170,7 @@ function decodeServerAdmission(reader) {
     const lifecycleGeneration = reader.nonZeroU64('lifecycleGeneration');
     const descriptorRevision = reader.nonZeroU64('descriptorRevision');
     const weight = reader.u32('weight');
-    if (weight > 10_000)
+    if (!(0, RegistrationBuilderPolicy_1.isValidPublicWeight)(weight))
         fail('ClientServer weight is invalid.');
     return {
         channelName,
@@ -196,7 +217,7 @@ function encodeText8(value, field) {
     return concat(Buffer.of(bytes.byteLength), bytes);
 }
 function encodeText16(value, field) {
-    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, 4096, fail);
+    const bytes = (0, service_wire_binary_primitives_1.encodeCanonicalServiceWireText)(value, field, CLIENT_SERVER_TEXT_MAX_BYTES, fail);
     return concat(encodeU16(bytes.byteLength), bytes);
 }
 function runtimeStateToWire(value) {
@@ -295,7 +316,7 @@ class Reader {
     }
     text16(field) {
         const length = this.u16(`${field}.length`);
-        if (length < 1 || length > 4096)
+        if (length < 1 || length > CLIENT_SERVER_TEXT_MAX_BYTES)
             fail(`${field} length is invalid.`);
         return decodeText(this.bytes(length, field), field);
     }

package/dist/runtime/channels/dispatch-error-reporter.d.ts

@@ -1,6 +1,5 @@
 import { type ZLinkDispatchFailure } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import type { ZLinkRuntimeMetrics } from '../diagnostics';
-import { ZLinkMessageFlowTracer, type ZLinkDiagnosticsContext } from '../diagnostics';
+import { type ZLinkRuntimeMetrics, ZLinkMessageFlowTracer, type ZLinkDiagnosticsContext } from '../diagnostics';
 import type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
 export type { ZLinkDispatchErrorSink } from '../diagnostics/dispatch-error-port';
 type ZLinkRuntimeDispatchFailure = ZLinkDispatchFailure & {

package/dist/runtime/channels/dispatch-error-reporter.js

@@ -4,6 +4,7 @@ exports.ZLinkDispatchErrorReporter = void 0;
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const diagnostics_1 = require("../diagnostics");
 const dispatch_error_details_1 = require("../diagnostics/dispatch-error-details");
+const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 class ZLinkDispatchErrorReporter {
     metrics;
     reportedEvents = 0;
@@ -26,7 +27,7 @@ class ZLinkDispatchErrorReporter {
         const normalized = normalizeDispatchFailure(event);
         const dropReason = channelDropReason(normalized);
         if (dropReason !== undefined) {
-            this.metrics?.count('zlink.mesh_node.messages.dropped', 1, {
+            this.metrics?.count(runtime_metrics_1.METRIC_NAMES.MeshNodeMessagesDropped, 1, {
                 surface: normalized.surface,
                 message_kind: normalized.messageKind,
                 reason: dropReason