@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,126 @@
+import { type ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
+import type { ZLinkBackendMeshNode, ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkFanoutListenerStatus } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+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 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>;
+    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>;
+    getFanoutListenerStatus?(channelName: string): ZLinkFanoutListenerStatus;
+}
+export type ZLinkChannelClientTransportSource = ZLinkChannelClientTransport | (() => ZLinkChannelClientTransport | undefined);
+export interface ZLinkSpotPublisherClientTransport {
+    tryPublish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: unknown, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
+    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>;
+    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>;
+    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: {
+        readonly packetName?: string;
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+        readonly metadata?: ReadonlyMap<string, string>;
+    }): Promise<TReply>;
+}
+interface ZLinkChannelTransportRuntime {
+    send(channelName: string, packetName: string | undefined, message: unknown, signal?: AbortSignal, 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>;
+    getFanoutListenerStatus(channelName: string): ZLinkFanoutListenerStatus;
+    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>;
+    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>;
+    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[]>;
+    routeRequestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+}
+export declare class ZLinkRuntimeRouteTransport implements ZLinkRouteClientTransport {
+    private readonly manager;
+    private readonly routeChannelPredicate;
+    private readonly meshRuntime;
+    private readonly codecs?;
+    private readonly manualNodeTarget?;
+    private readonly localNodeSubmit?;
+    private readonly metrics?;
+    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);
+    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>;
+    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 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>;
+    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>;
+    private requestToSpotScoped;
+    requestFromSpotToSpot<TReply = unknown>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: {
+        readonly packetName?: string;
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<TReply>;
+    requestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, options: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<readonly Message[]>;
+    requestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, options: {
+        readonly timeoutMs?: number;
+        readonly signal?: AbortSignal;
+    }): Promise<readonly Message[]>;
+    private requestRawToSpotScoped;
+    private requireManager;
+    private meshNode;
+    private isSelfNode;
+    private isKnownBackendPeer;
+    private submitLocalNode;
+    private requireMeshNode;
+    private completionTable;
+    private encodeMessage;
+    private waitForMeshReply;
+    private decodeMeshReply;
+}
+export {};

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

@@ -0,0 +1,448 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRuntimeRouteTransport = void 0;
+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 Spots_1 = require("../../contracts/Spots");
+const abort_1 = require("../abort");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+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;
+    meshRuntime;
+    codecs;
+    manualNodeTarget;
+    localNodeSubmit;
+    metrics;
+    constructor(manager, routeChannelPredicate = undefined, meshRuntime = undefined, codecs, manualNodeTarget, localNodeSubmit, metrics) {
+        this.manager = manager;
+        this.routeChannelPredicate = routeChannelPredicate;
+        this.meshRuntime = meshRuntime;
+        this.codecs = codecs;
+        this.manualNodeTarget = manualNodeTarget;
+        this.localNodeSubmit = localNodeSubmit;
+        this.metrics = metrics;
+    }
+    canRouteChannel(routerChannelId) {
+        const manager = this.manager();
+        if (manager !== undefined) {
+            return manager.canRouteChannel(routerChannelId);
+        }
+        return this.routeChannelPredicate?.(routerChannelId) ?? false;
+    }
+    canRoutePacketChannel(routerChannelId) {
+        return this.manager()?.canRoutePacketChannel(routerChannelId)
+            ?? this.routeChannelPredicate?.(routerChannelId)
+            ?? false;
+    }
+    async submit(meshName, targetNodeRid, packetName, message, signal, 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)(true, () => this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, false));
+    }
+    async submitInfrastructure(meshName, targetNodeRid, packetName, message, signal, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, true));
+    }
+    async submitNode(meshName, targetNodeRid, packetName, message, signal, metadata, allowObjectClientTarget) {
+        const node = this.meshNode(meshName);
+        if (node === undefined) {
+            return this.requireManager().routeSubmit(meshName, targetNodeRid, packetName, message, signal, metadata);
+        }
+        (0, abort_1.throwIfAborted)(signal);
+        if (!allowObjectClientTarget
+            && node.isObjectClientNodeDirectTarget?.((0, routing_id_1.toBackendRoutingId)(targetNodeRid)) === true) {
+            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+        }
+        const parts = this.encodeMessage(3 /* ZLinkChannelMessageKind.Command */, meshName, packetName, message, undefined, metadata);
+        const operation = `MeshNode '${meshName}' send to node '${targetNodeRid}'`;
+        if (this.isSelfNode(node, targetNodeRid)) {
+            return this.submitLocalNode(meshName, String(node.status().routingId), parts);
+        }
+        if (!this.isKnownBackendPeer(node, targetNodeRid)
+            && this.manualNodeTarget?.(meshName, targetNodeRid) === false) {
+            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+        }
+        try {
+            return mapMeshSubmitResult(await node.sendToNode((0, routing_id_1.toBackendRoutingId)(targetNodeRid), parts, { flags: 1 }));
+        }
+        catch (error) {
+            throw mapMeshSubmissionError(error, operation);
+        }
+    }
+    request(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.requestScoped(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata));
+    }
+    async requestScoped(meshName, targetNodeRid, packetName, request, timeoutMs, signal, metadata) {
+        const node = this.meshNode(meshName);
+        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 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)(true, () => this.submitToChannelScoped(meshName, channelName, packetName, message, signal, metadata));
+    }
+    async submitToChannelScoped(meshName, channelName, packetName, message, signal, metadata) {
+        (0, abort_1.throwIfAborted)(signal);
+        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}'`;
+        try {
+            const result = mapMeshSubmitResult(await node.sendToChannel(channelName, parts, { flags: 1 }));
+            if (result.status === submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+                this.metrics?.recordChannelSelectionFailure(meshName, channelName, 'no_ready_target');
+            }
+            return result;
+        }
+        catch (error) {
+            throw mapMeshSubmissionError(error, operation);
+        }
+    }
+    requestToChannel(meshName, channelName, packetName, request, timeoutMs, signal, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.requestToChannelScoped(meshName, channelName, packetName, request, timeoutMs, signal, metadata));
+    }
+    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 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 }));
+            const reply = this.decodeMeshReply(meshName, completion);
+            metric?.complete('completed');
+            return reply;
+        }
+        catch (error) {
+            metric?.complete(requestMetricOutcome(error));
+            if (requestMetricOutcome(error) === 'target_not_found') {
+                this.metrics?.recordChannelSelectionFailure(meshName, channelName, 'no_ready_target');
+            }
+            throw error;
+        }
+    }
+    async submitRequestOperation(meshName, timeoutMs, signal, operation, attempt) {
+        const effectiveTimeoutMs = Math.max(1, timeoutMs ?? 30_000);
+        const deadlineMs = performance.now() + effectiveTimeoutMs;
+        const remainingTimeoutMs = deadlineMs - performance.now();
+        if (remainingTimeoutMs <= 0) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `${operation} timed out before submission.`);
+        }
+        try {
+            return await this.completionTable(meshName).submit(() => attempt(Math.max(1, Math.ceil(remainingTimeoutMs))), signal);
+        }
+        catch (error) {
+            throw mapMeshSubmissionError(error, operation);
+        }
+    }
+    sendToSpot(spotRouteTarget, message, options) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.sendToSpotScoped(spotRouteTarget, message, options));
+    }
+    async sendToSpotScoped(spotRouteTarget, message, options) {
+        const node = this.meshNode(spotRouteTarget.routerChannelId);
+        if (node === undefined) {
+            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);
+            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.entrySpot().sendToSpot((0, routing_id_1.toBackendRoutingId)(spotRouteTarget.targetNodeRid), (0, routing_id_1.toBackendRoutingId)(spotRouteTarget.spotId), spotRouteTarget.targetSpotGeneration ?? 0n, encoded, {
+                flags: 1,
+                routeFence: directSpotRouteFence(spotRouteTarget),
+                entrySpot: spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Entry
+            }));
+        }
+        catch (error) {
+            throw mapMeshSubmissionError(error, operation);
+        }
+    }
+    async sendFromSpotToSpot(sourceSpot, spotRouteTarget, message, options) {
+        await this.requireManager().routeSendFromSpotToSpot(sourceSpot, spotRouteTarget, options.packetName, message, options.signal, options.metadata, options.timeoutMs);
+        return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+    }
+    requestToSpot(spotRouteTarget, request, options) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.requestToSpotScoped(spotRouteTarget, request, options));
+    }
+    async requestToSpotScoped(spotRouteTarget, request, options) {
+        const meshName = spotRouteTarget.routerChannelId;
+        const node = this.meshNode(meshName);
+        if (node === undefined) {
+            if (spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Instance) {
+                throw new configuration_1.ZLinkConfigurationException('Instance Spot routes require the MeshNode command 39 transport.');
+            }
+            return this.requireManager().routeRequestToSpot(spotRouteTarget, options.packetName, request, options.timeoutMs, options.signal, options.metadata);
+        }
+        (0, abort_1.throwIfAborted)(options.signal);
+        let completionPromise;
+        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.entrySpot().requestToSpot((0, routing_id_1.toBackendRoutingId)(spotRouteTarget.targetNodeRid), (0, routing_id_1.toBackendRoutingId)(spotRouteTarget.spotId), spotRouteTarget.targetSpotGeneration ?? 0n, encoded, {
+                    flags: 1,
+                    timeoutMs: options.timeoutMs,
+                    routeFence: directSpotRouteFence(spotRouteTarget),
+                    entrySpot: spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Entry
+                }), options.signal);
+        }
+        catch (error) {
+            throw mapMeshSubmissionError(error, `MeshNode '${meshName}' request to Spot '${spotRouteTarget.spotId}'`);
+        }
+        return this.waitForMeshReply(meshName, completionPromise);
+    }
+    async requestFromSpotToSpot(sourceSpot, spotRouteTarget, request, options) {
+        return this.requireManager().routeRequestFromSpotToSpot(sourceSpot, spotRouteTarget, options.packetName, request, options.timeoutMs, options.signal);
+    }
+    async requestRawFromSpotToSpot(sourceSpot, spotRouteTarget, request, options) {
+        return this.requireManager().routeRequestRawFromSpotToSpot(sourceSpot, spotRouteTarget, request, options.timeoutMs, options.signal);
+    }
+    requestRawToSpot(spotRouteTarget, request, options) {
+        return (0, flow_context_1.runWithOutboundFlow)(true, () => this.requestRawToSpotScoped(spotRouteTarget, request, options));
+    }
+    async requestRawToSpotScoped(spotRouteTarget, request, options) {
+        const meshName = spotRouteTarget.routerChannelId;
+        const node = this.meshNode(meshName);
+        if (node !== undefined) {
+            (0, abort_1.throwIfAborted)(options.signal);
+            const payload = JSON.parse(request.getString('utf8'));
+            const packetName = typeof payload.packetName === 'string'
+                ? payload.packetName
+                : undefined;
+            const parts = this.encodeMessage(1 /* ZLinkChannelMessageKind.Request */, meshName, packetName, payload, options.timeoutMs);
+            let completionPromise;
+            try {
+                completionPromise = this.completionTable(meshName).submit(() => node.entrySpot().requestToSpot((0, routing_id_1.toBackendRoutingId)(spotRouteTarget.targetNodeRid), (0, routing_id_1.toBackendRoutingId)(spotRouteTarget.spotId), spotRouteTarget.targetSpotGeneration ?? 0n, parts, {
+                    flags: 1,
+                    timeoutMs: options.timeoutMs,
+                    routeFence: directSpotRouteFence(spotRouteTarget),
+                    entrySpot: spotRouteTarget.spotKind === Spots_1.ZLinkSpotKind.Entry
+                }), options.signal);
+            }
+            catch (error) {
+                throw mapMeshSubmissionError(error, `MeshNode '${meshName}' raw request to Spot '${spotRouteTarget.spotId}'`);
+            }
+            const completion = await completionPromise;
+            if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+                try {
+                    throw meshRequestFailure(meshName, completion.terminalResult, completion.failureErrno);
+                }
+                finally {
+                    (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+                }
+            }
+            try {
+                const reply = (0, channel_envelope_1.decodeChannelReply)(completion.parts, this.codecs);
+                return [runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(JSON.stringify(reply)))];
+            }
+            finally {
+                (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+            }
+        }
+        return this.requireManager().routeRequestRawToSpot(spotRouteTarget, request, options.timeoutMs, options.signal);
+    }
+    requireManager() {
+        const manager = this.manager();
+        if (manager === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Route channel runtime is not started.');
+        }
+        return manager;
+    }
+    meshNode(meshName) {
+        const runtime = this.meshRuntime?.();
+        return runtime?.meshNode?.(meshName);
+    }
+    isSelfNode(node, targetNodeRid) {
+        return (0, routing_id_1.routingIdsEqual)(node.status().routingId, targetNodeRid);
+    }
+    isKnownBackendPeer(node, targetNodeRid) {
+        return node.peers().some((peer) => peer.routingId !== null && (0, routing_id_1.routingIdsEqual)(peer.routingId, targetNodeRid));
+    }
+    submitLocalNode(meshName, sourceNodeRid, parts) {
+        if (this.localNodeSubmit === undefined) {
+            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+        }
+        return this.localNodeSubmit(meshName, sourceNodeRid, parts);
+    }
+    requireMeshNode(meshName) {
+        const node = this.meshNode(meshName);
+        if (node === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' runtime is not started.`);
+        }
+        return node;
+    }
+    completionTable(meshName) {
+        const table = this.meshRuntime?.()?.meshCompletionTable(meshName);
+        if (table === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' completion runtime is not started.`);
+        }
+        return table;
+    }
+    encodeMessage(kind, channelName, packetName, message, timeoutMs, metadata) {
+        return (0, channel_envelope_1.encodeChannelEnvelopeParts)(kind, channelName, packetName, message, timeoutMs, undefined, this.codecs, undefined, true, metadata);
+    }
+    async waitForMeshReply(meshName, completionPromise) {
+        const completion = await completionPromise;
+        return this.decodeMeshReply(meshName, completion);
+    }
+    decodeMeshReply(meshName, completion) {
+        try {
+            if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+                throw meshRequestFailure(meshName, completion.terminalResult, completion.failureErrno);
+            }
+            return (0, channel_envelope_1.decodeChannelReply)(completion.parts, this.codecs);
+        }
+        finally {
+            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+        }
+    }
+}
+exports.ZLinkRuntimeRouteTransport = ZLinkRuntimeRouteTransport;
+function directSpotRouteFence(target) {
+    // Entry Spots are addressed by their owning MeshNode. They have no
+    // Location Store authority row, so only User and Instance Spots carry the
+    // exact Ready authority fence required by direct Spot submission.
+    if (target.spotKind === Spots_1.ZLinkSpotKind.Entry) {
+        return undefined;
+    }
+    if (target.targetSpotGeneration === undefined
+        || target.targetNodeGeneration === undefined
+        || target.authorityOwnerGeneration === undefined
+        || 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.`);
+    }
+    return {
+        spot: {
+            spotId: String(target.spotId),
+            generation: target.targetSpotGeneration
+        },
+        targetNodeRid: String(target.targetNodeRid),
+        targetNodeGeneration: target.targetNodeGeneration,
+        authorityOwnerGeneration: target.authorityOwnerGeneration,
+        ownerLeaseGeneration: target.ownerLeaseGeneration,
+        storeVersion: target.authorityStoreVersion
+    };
+}
+function instanceSpotRouteFence(target) {
+    if (target.targetSpotGeneration === undefined
+        || target.targetNodeGeneration === undefined
+        || target.authorityOwnerGeneration === undefined
+        || target.targetOwnerId === undefined
+        || target.ownerLeaseGeneration === undefined
+        || target.authorityStoreVersion === undefined) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound, `Instance Spot '${String(target.spotId)}' has no complete Ready authority fence.`);
+    }
+    return {
+        targetNodeRid: String(target.targetNodeRid),
+        targetNodeGeneration: target.targetNodeGeneration,
+        targetSpotId: String(target.spotId),
+        objectGeneration: target.targetSpotGeneration,
+        ownerId: target.targetOwnerId,
+        authorityOwnerGeneration: target.authorityOwnerGeneration,
+        leaseGeneration: target.ownerLeaseGeneration,
+        storeVersion: target.authorityStoreVersion
+    };
+}
+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}.`);
+    }
+}
+function mapMeshSubmissionError(error, operation) {
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
+        return error;
+    }
+    // A remote authority route can advance its durable StoreVersion while the
+    // object generation remains unchanged. The stateful runtime reports that
+    // exact-fence mismatch as a raw ServiceStaleGenerationError before native
+    // submission. Preserve the retryable route meaning so the address
+    // transport can invalidate the Location Store cache and resolve again.
+    if (error instanceof service_stateful_registry_1.ServiceStaleGenerationError) {
+        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);
+    }
+    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);
+}
+function meshRequestFailure(meshName, result, nativeErrno) {
+    const canonical = (0, framework_errors_internal_1.isCanonicalWireReplyTerminal)(result, nativeErrno);
+    const wireKind = canonical
+        ? (0, framework_errors_internal_1.internalFrameworkErrorKindFromWireReply)(result, nativeErrno)
+        : undefined;
+    const kind = !canonical
+        ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError
+        : result === runtime_values_1.RequestResult.NotFound
+            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+            : result === runtime_values_1.RequestResult.TimedOut
+                ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded
+                : result === runtime_values_1.RequestResult.Terminated
+                    ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown
+                    : result === runtime_values_1.RequestResult.Conflict || result === runtime_values_1.RequestResult.InternalError
+                        ? wireKind ?? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError
+                        : result === runtime_values_1.RequestResult.NotConnected || result === runtime_values_1.RequestResult.Backpressured
+                            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected
+                            : wireKind ?? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
+    const error = (0, framework_errors_internal_1.createInternalFrameworkException)(kind, `MeshNode '${meshName}' request failed with result ${result} and errno ${nativeErrno}.`, result === runtime_values_1.RequestResult.NotConnected || result === runtime_values_1.RequestResult.Backpressured);
+    // An operation id was returned before this completion was observed. The
+    // application envelope therefore crossed the native submission boundary,
+    // including terminal NotFound replies; callers must not resubmit it through
+    // a cold route.
+    Object.defineProperty(error, 'physicalSubmission', {
+        value: true,
+        enumerable: false
+    });
+    return error;
+}
+function requestMetricOutcome(error) {
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
+        if ((0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound)
+            return 'target_not_found';
+        if ((0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded)
+            return 'timed_out';
+        if ((0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown)
+            return 'shutdown';
+    }
+    return 'failed';
+}

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

@@ -0,0 +1,41 @@
+import { type ZLinkClientServerServerDescriptor } from '../../contracts/Locations';
+import { type ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkLocationRuntime, ZLinkLocationRuntimeStores } from '../locations';
+import { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+/**
+ * Owns the dedicated ClientServer discovery domain. It never converts these
+ * descriptors into RouteMesh peer rows.
+ */
+export declare class ZLinkClientServerLocationRuntime {
+    private readonly registration;
+    private readonly sockets;
+    private readonly locationRuntime;
+    private readonly stores;
+    private readonly lane;
+    private readonly options;
+    private readonly store;
+    private readonly localDescriptors;
+    private readonly connections;
+    private controller?;
+    private timer?;
+    constructor(registration: ZLinkFrameworkRegistration, sockets: ZLinkChannelSocketRegistry, locationRuntime: ZLinkLocationRuntime, stores: ZLinkLocationRuntimeStores, options: ZLinkLocationOptionOverrides);
+    start(signal?: AbortSignal): Promise<void>;
+    tick(signal?: AbortSignal): Promise<void>;
+    private tickCore;
+    stop(signal?: AbortSignal): Promise<void>;
+    activeTargets(channelName: string): readonly ZLinkClientServerServerDescriptor[];
+    reclaimOwnerRows(signal?: AbortSignal): Promise<void>;
+    private publishServers;
+    private reconcileClients;
+    private listLiveServers;
+    private disconnectClients;
+    private openConnection;
+    private handleTransportReady;
+    private removeSupersededConnections;
+    private handleConnectionTerminated;
+    private closeConnection;
+    private drainAndRemoveServers;
+    private requireOwnerToken;
+    private schedule;
+}