@zlink-systems/framework 0.10.0

package/dist/runtime/channels/source-spot-router.d.ts

@@ -0,0 +1,10 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+export declare class ZLinkSourceSpotRouter {
+    private readonly defaultRequestTimeoutMs;
+    constructor(defaultRequestTimeoutMs: number | undefined);
+    request<TReply>(sourceSpot: ZLinkBackendSpot, target: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply>;
+    send(sourceSpot: ZLinkBackendSpot, target: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    requestRaw(sourceSpot: ZLinkBackendSpot, target: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+}

package/dist/runtime/channels/source-spot-router.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSourceSpotRouter = void 0;
+const abort_1 = require("../abort");
+const channel_envelope_1 = require("./channel-envelope");
+const spot_direct_envelope_1 = require("./spot-direct-envelope");
+class ZLinkSourceSpotRouter {
+    defaultRequestTimeoutMs;
+    constructor(defaultRequestTimeoutMs) {
+        this.defaultRequestTimeoutMs = defaultRequestTimeoutMs;
+    }
+    async request(sourceSpot, target, packetName, request, timeoutMs, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const parts = [(0, spot_direct_envelope_1.encodeSpotDirectEnvelope)(1 /* ZLinkChannelMessageKind.Request */, target.routerChannelId, packetName, request)];
+        const operation = sourceSpot.requestToSpot(target.targetNodeRid, target.spotId, parts, timeoutMs ?? this.defaultRequestTimeoutMs);
+        const replyParts = await (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        });
+        try {
+            return (0, spot_direct_envelope_1.decodeSpotDirectReply)(replyParts);
+        }
+        finally {
+            (0, channel_envelope_1.closeMessages)(replyParts);
+            (0, channel_envelope_1.closeMessages)(parts);
+        }
+    }
+    async send(sourceSpot, target, packetName, message, signal, metadata, timeoutMs) {
+        (0, abort_1.throwIfAborted)(signal);
+        const parts = [(0, spot_direct_envelope_1.encodeSpotDirectEnvelope)(3 /* ZLinkChannelMessageKind.Command */, target.routerChannelId, packetName, message, metadata)];
+        try {
+            void timeoutMs;
+            await (0, abort_1.awaitWithAbort)(sourceSpot.sendToSpot(target.targetNodeRid, target.spotId, parts), signal);
+        }
+        finally {
+            (0, channel_envelope_1.closeMessages)(parts);
+        }
+    }
+    async requestRaw(sourceSpot, target, request, timeoutMs, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const operation = sourceSpot.requestToSpot(target.targetNodeRid, target.spotId, request, timeoutMs ?? this.defaultRequestTimeoutMs);
+        return await (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        });
+    }
+}
+exports.ZLinkSourceSpotRouter = ZLinkSourceSpotRouter;

package/dist/runtime/channels/spot-direct-envelope.d.ts

@@ -0,0 +1,5 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
+import { ZLinkChannelMessageKind } from './channel-envelope';
+export declare function encodeSpotDirectEnvelope(kind: ZLinkChannelMessageKind.Request | ZLinkChannelMessageKind.Command, channelName: string, packetName: string | undefined, payload: unknown, metadata?: ReadonlyMap<string, string>): MessageLike;
+export declare function decodeSpotDirectReply<TReply>(parts: readonly Message[]): TReply;

package/dist/runtime/channels/spot-direct-envelope.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeSpotDirectEnvelope = encodeSpotDirectEnvelope;
+exports.decodeSpotDirectReply = decodeSpotDirectReply;
+const configuration_1 = require("../configuration");
+const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
+function encodeSpotDirectEnvelope(kind, channelName, packetName, payload, metadata) {
+    return Buffer.from(JSON.stringify({
+        marker: SPOT_DIRECT_ENVELOPE,
+        kind,
+        channelName,
+        packetName,
+        payload,
+        metadata: Object.fromEntries(metadata ?? [])
+    }));
+}
+function decodeSpotDirectReply(parts) {
+    if (parts.length < 1) {
+        throw new configuration_1.ZLinkConfigurationException('Spot direct reply is missing.');
+    }
+    const reply = JSON.parse(parts[0].data().toString());
+    if (reply.marker !== SPOT_DIRECT_ENVELOPE) {
+        throw new configuration_1.ZLinkConfigurationException('Spot direct reply marker is invalid.');
+    }
+    if (reply.ok !== true) {
+        throw new configuration_1.ZLinkConfigurationException(typeof reply.error === 'string' ? reply.error : 'Spot direct request failed.');
+    }
+    return reply.response;
+}

package/dist/runtime/channels/spot-node-route-transport.d.ts

@@ -0,0 +1,13 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+import { ZLinkSpotRouteTargetResolver } from './spot-route-target-resolver';
+export declare class ZLinkSpotNodeRouteTransport {
+    private readonly registration;
+    private readonly targets;
+    constructor(registration: ZLinkFrameworkRegistration, targets: ZLinkSpotRouteTargetResolver);
+    send(target: ZLinkSpotRouteTarget, parts: readonly Message[], signal?: AbortSignal): Promise<boolean>;
+    request<TReply>(target: ZLinkSpotRouteTarget, parts: readonly Message[], codecs: ZLinkChannelEnvelopeCodecRegistry | undefined, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply> | undefined;
+    requestRaw(target: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]> | undefined;
+}

package/dist/runtime/channels/spot-node-route-transport.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotNodeRouteTransport = void 0;
+const abort_1 = require("../abort");
+const channel_envelope_1 = require("./channel-envelope");
+class ZLinkSpotNodeRouteTransport {
+    registration;
+    targets;
+    constructor(registration, targets) {
+        this.registration = registration;
+        this.targets = targets;
+    }
+    async send(target, parts, signal) {
+        const router = this.targets.spotNodeRouter(target.routerChannelId);
+        if (router === undefined) {
+            return false;
+        }
+        try {
+            (0, abort_1.throwIfAborted)(signal);
+            await (0, abort_1.awaitWithAbort)(router.sendToSpot(target.targetNodeRid, target.spotId, parts), signal);
+            return true;
+        }
+        finally {
+            (0, channel_envelope_1.closeMessages)(parts);
+        }
+    }
+    request(target, parts, codecs, timeoutMs, signal) {
+        const router = this.targets.spotNodeRouter(target.routerChannelId);
+        if (router === undefined) {
+            return undefined;
+        }
+        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+        (0, abort_1.throwIfAborted)(signal);
+        const operation = router.requestToSpot(target.targetNodeRid, target.spotId, parts, effectiveTimeoutMs);
+        return (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        }).then((replyParts) => {
+            try {
+                return (0, channel_envelope_1.decodeChannelReply)(replyParts, codecs);
+            }
+            finally {
+                (0, channel_envelope_1.closeMessages)(replyParts);
+                (0, channel_envelope_1.closeMessages)(parts);
+            }
+        });
+    }
+    requestRaw(target, request, timeoutMs, signal) {
+        const router = this.targets.spotNodeRouter(target.routerChannelId);
+        if (router === undefined) {
+            return undefined;
+        }
+        const effectiveTimeoutMs = timeoutMs ?? this.registration.requestTimeoutMs ?? 30_000;
+        (0, abort_1.throwIfAborted)(signal);
+        const operation = router.requestToSpot(target.targetNodeRid, target.spotId, request, effectiveTimeoutMs);
+        return (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        });
+    }
+}
+exports.ZLinkSpotNodeRouteTransport = ZLinkSpotNodeRouteTransport;

package/dist/runtime/channels/spot-route-bridge-transport.d.ts

@@ -0,0 +1,14 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendSpotRouteBridge } from '../backend/contracts';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+export declare class ZLinkSpotRouteBridgeTransport {
+    private readonly bridges;
+    private readonly defaultRequestTimeoutMs;
+    constructor(bridges: ReadonlyMap<string, ZLinkBackendSpotRouteBridge>, defaultRequestTimeoutMs: number | undefined);
+    has(routerChannelId: string): boolean;
+    send(target: ZLinkSpotRouteTarget, parts: readonly Message[], signal?: AbortSignal): Promise<void>;
+    request<TReply>(target: ZLinkSpotRouteTarget, parts: readonly Message[], codecs: ZLinkChannelEnvelopeCodecRegistry | undefined, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply>;
+    requestRaw(target: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+    private requireBridge;
+}

package/dist/runtime/channels/spot-route-bridge-transport.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRouteBridgeTransport = void 0;
+const configuration_1 = require("../configuration");
+const channel_envelope_1 = require("./channel-envelope");
+const channel_multipart_1 = require("./channel-multipart");
+const abort_1 = require("../abort");
+class ZLinkSpotRouteBridgeTransport {
+    bridges;
+    defaultRequestTimeoutMs;
+    constructor(bridges, defaultRequestTimeoutMs) {
+        this.bridges = bridges;
+        this.defaultRequestTimeoutMs = defaultRequestTimeoutMs;
+    }
+    has(routerChannelId) {
+        return this.bridges.has(routerChannelId);
+    }
+    async send(target, parts, signal) {
+        const bridge = this.requireBridge(target.routerChannelId);
+        try {
+            await (0, abort_1.awaitWithAbort)((0, channel_multipart_1.appendParts)(bridge.send(target.routerChannelId, target.targetNodeRid, target.spotId), parts).submit(), signal);
+        }
+        finally {
+            (0, channel_envelope_1.closeMessages)(parts);
+        }
+    }
+    async request(target, parts, codecs, timeoutMs, signal) {
+        const bridge = this.requireBridge(target.routerChannelId);
+        const operation = (0, channel_multipart_1.appendParts)(bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId), parts).timeout(timeoutMs ?? 0).submit();
+        const replyParts = await (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        });
+        try {
+            return (0, channel_envelope_1.decodeChannelReply)(replyParts, codecs);
+        }
+        finally {
+            (0, channel_envelope_1.closeMessages)(replyParts);
+            (0, channel_envelope_1.closeMessages)(parts);
+        }
+    }
+    requestRaw(target, request, timeoutMs, signal) {
+        const bridge = this.requireBridge(target.routerChannelId);
+        const operation = bridge.request(target.routerChannelId, target.targetNodeRid, target.spotId)
+            .message(request)
+            .timeout(timeoutMs ?? this.defaultRequestTimeoutMs ?? 0)
+            .submit();
+        return (0, abort_1.awaitWithAbort)(operation, signal, () => {
+            void operation.then(channel_envelope_1.closeMessages, () => undefined);
+        });
+    }
+    requireBridge(routerChannelId) {
+        const bridge = this.bridges.get(routerChannelId);
+        if (bridge === undefined)
+            throw new configuration_1.ZLinkConfigurationException(`Route channel '${routerChannelId}' has no SPOT route bridge.`);
+        return bridge;
+    }
+}
+exports.ZLinkSpotRouteBridgeTransport = ZLinkSpotRouteBridgeTransport;

package/dist/runtime/channels/spot-route-dispatch-strategy.d.ts

@@ -0,0 +1,50 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { RoutingId } from '../../contracts';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendSpotRouteBridge } from '../backend/contracts';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import { type ZLinkChannelEnvelopeCodecRegistry } from './channel-envelope';
+import type { ZLinkChannelSocketRegistry } from './channel-socket-registry';
+export interface ZLinkLocalSpotRouteDispatcher {
+    send(spotId: RoutingId, packetName: string | undefined, message: unknown, context: {
+        readonly channelName: string;
+        readonly admissionTimeoutMs?: number;
+        readonly signal?: AbortSignal;
+        readonly metadata?: ReadonlyMap<string, string>;
+    }): Promise<void>;
+    request<TReply>(spotId: RoutingId, packetName: string | undefined, request: unknown, context: {
+        readonly channelName: string;
+        readonly signal?: AbortSignal;
+        readonly metadata?: ReadonlyMap<string, string>;
+    }): Promise<TReply>;
+}
+export interface ZLinkSpotRouteDispatchStrategyOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    readonly sockets: ZLinkChannelSocketRegistry;
+    readonly codecs: ZLinkChannelEnvelopeCodecRegistry;
+    readonly spotRouteBridges: ReadonlyMap<string, ZLinkBackendSpotRouteBridge>;
+    readonly localSpotRouteDispatcher?: ZLinkLocalSpotRouteDispatcher;
+    readonly flowCreationEnabled?: () => boolean;
+}
+export declare class ZLinkSpotRouteDispatchStrategy {
+    private readonly options;
+    private readonly sourceSpotRouter;
+    private readonly targets;
+    private readonly spotNodeTransport;
+    private readonly routerSocketTransport;
+    private readonly localTransport;
+    private readonly bridgeTransport;
+    constructor(options: ZLinkSpotRouteDispatchStrategyOptions);
+    setSpotNodes(spotNodes: ReadonlyMap<string, ZLinkBackendSpotNode>): void;
+    spotRouteNode(routerChannelId: string): ZLinkBackendSpotNode | undefined;
+    canRouteChannel(routerChannelId: string): boolean;
+    canRoutePacketChannel(routerChannelId: string): boolean;
+    routeSendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    private routeSendToSpotScoped;
+    routeRequestToSpot<TReply>(spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<TReply>;
+    private routeRequestToSpotScoped;
+    routeRequestFromSpotToSpot<TReply>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, request: unknown, timeoutMs: number | undefined, signal?: AbortSignal): Promise<TReply>;
+    routeSendFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, packetName: string | undefined, message: unknown, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>, timeoutMs?: number): Promise<void>;
+    routeRequestRawFromSpotToSpot(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+    routeRequestRawToSpot(spotRouteTarget: ZLinkSpotRouteTarget, request: Message, timeoutMs: number | undefined, signal?: AbortSignal): Promise<readonly Message[]>;
+}

package/dist/runtime/channels/spot-route-dispatch-strategy.js

@@ -0,0 +1,128 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRouteDispatchStrategy = void 0;
+const channel_envelope_1 = require("./channel-envelope");
+const channel_framework_packets_1 = require("./channel-framework-packets");
+const abort_1 = require("../abort");
+const source_spot_router_1 = require("./source-spot-router");
+const spot_route_target_resolver_1 = require("./spot-route-target-resolver");
+const spot_node_route_transport_1 = require("./spot-node-route-transport");
+const router_socket_spot_route_transport_1 = require("./router-socket-spot-route-transport");
+const local_spot_route_transport_1 = require("./local-spot-route-transport");
+const spot_route_bridge_transport_1 = require("./spot-route-bridge-transport");
+const flow_context_1 = require("../diagnostics/flow-context");
+const ZLINK_SEND_DONT_WAIT = 1;
+class ZLinkSpotRouteDispatchStrategy {
+    options;
+    sourceSpotRouter;
+    targets;
+    spotNodeTransport;
+    routerSocketTransport;
+    localTransport;
+    bridgeTransport;
+    constructor(options) {
+        this.options = options;
+        this.sourceSpotRouter = new source_spot_router_1.ZLinkSourceSpotRouter(options.registration.requestTimeoutMs);
+        this.targets = new spot_route_target_resolver_1.ZLinkSpotRouteTargetResolver(options.registration);
+        this.spotNodeTransport = new spot_node_route_transport_1.ZLinkSpotNodeRouteTransport(options.registration, this.targets);
+        this.routerSocketTransport = new router_socket_spot_route_transport_1.ZLinkRouterSocketSpotRouteTransport(options.sockets);
+        this.localTransport = new local_spot_route_transport_1.ZLinkLocalSpotRouteTransport(options.localSpotRouteDispatcher, options.registration.requestTimeoutMs);
+        this.bridgeTransport = new spot_route_bridge_transport_1.ZLinkSpotRouteBridgeTransport(options.spotRouteBridges, options.registration.requestTimeoutMs);
+    }
+    setSpotNodes(spotNodes) {
+        this.targets.setSpotNodes(spotNodes);
+    }
+    spotRouteNode(routerChannelId) {
+        return this.targets.routeNode(routerChannelId);
+    }
+    canRouteChannel(routerChannelId) {
+        return this.targets.canRouteChannel(routerChannelId);
+    }
+    canRoutePacketChannel(routerChannelId) {
+        return this.targets.canRoutePacketChannel(routerChannelId);
+    }
+    routeSendToSpot(spotRouteTarget, packetName, message, signal, metadata, timeoutMs) {
+        // 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.options.flowCreationEnabled?.() ?? true, () => this.routeSendToSpotScoped(spotRouteTarget, packetName, message, signal, metadata, timeoutMs));
+    }
+    async routeSendToSpotScoped(spotRouteTarget, packetName, message, signal, metadata, timeoutMs) {
+        (0, abort_1.throwIfAborted)(signal);
+        const localSpotRouteNode = this.targets.localRouteNode(spotRouteTarget);
+        if (localSpotRouteNode !== undefined) {
+            await this.localTransport.send(spotRouteTarget.routerChannelId, spotRouteTarget.spotId, packetName, message, signal, metadata, timeoutMs);
+            return;
+        }
+        const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(3 /* ZLinkChannelMessageKind.Command */, spotRouteTarget.routerChannelId, packetName, message, undefined, undefined, (0, channel_framework_packets_1.codecsForFrameworkPacket)(packetName, this.options.codecs), undefined, this.options.flowCreationEnabled?.() ?? true, metadata);
+        if (this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId)
+            && await this.spotNodeTransport.send(spotRouteTarget, parts, signal)) {
+            return;
+        }
+        if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
+            await this.bridgeTransport.send(spotRouteTarget, parts, signal);
+            return;
+        }
+        if (this.targets.hasBoundRouteRouter(spotRouteTarget.routerChannelId)) {
+            await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT, signal);
+            return;
+        }
+        if (await this.spotNodeTransport.send(spotRouteTarget, parts, signal)) {
+            return;
+        }
+        await this.routerSocketTransport.send(spotRouteTarget, parts, ZLINK_SEND_DONT_WAIT, signal);
+    }
+    routeRequestToSpot(spotRouteTarget, packetName, request, timeoutMs, signal, metadata) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.options.flowCreationEnabled?.() ?? true, () => this.routeRequestToSpotScoped(spotRouteTarget, packetName, request, timeoutMs, signal, metadata));
+    }
+    async routeRequestToSpotScoped(spotRouteTarget, packetName, request, timeoutMs, signal, metadata) {
+        (0, abort_1.throwIfAborted)(signal);
+        const localSpotRouteNode = this.targets.localRouteNode(spotRouteTarget);
+        if (localSpotRouteNode !== undefined) {
+            return this.localTransport.request(spotRouteTarget.routerChannelId, spotRouteTarget.spotId, packetName, request, timeoutMs, signal);
+        }
+        const codecs = (0, channel_framework_packets_1.codecsForFrameworkPacket)(packetName, this.options.codecs);
+        const parts = (0, channel_envelope_1.encodeChannelEnvelopeParts)(1 /* ZLinkChannelMessageKind.Request */, spotRouteTarget.routerChannelId, packetName, request, timeoutMs, undefined, codecs, undefined, this.options.flowCreationEnabled?.() ?? true, metadata);
+        if (this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId)) {
+            const namedSpotNodeRequest = this.spotNodeTransport.request(spotRouteTarget, parts, codecs, timeoutMs, signal);
+            if (namedSpotNodeRequest !== undefined)
+                return namedSpotNodeRequest;
+        }
+        if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
+            return this.bridgeTransport.request(spotRouteTarget, parts, codecs, timeoutMs, signal);
+        }
+        if (this.targets.hasBoundRouteRouter(spotRouteTarget.routerChannelId)) {
+            return this.routerSocketTransport.request(spotRouteTarget, parts, codecs, ZLINK_SEND_DONT_WAIT, timeoutMs, signal);
+        }
+        const spotNodeRequest = this.spotNodeTransport.request(spotRouteTarget, parts, codecs, timeoutMs, signal);
+        if (spotNodeRequest !== undefined) {
+            return spotNodeRequest;
+        }
+        return this.routerSocketTransport.request(spotRouteTarget, parts, codecs, 0, timeoutMs, signal);
+    }
+    routeRequestFromSpotToSpot(sourceSpot, spotRouteTarget, packetName, request, timeoutMs, signal) {
+        return this.sourceSpotRouter.request(sourceSpot, spotRouteTarget, packetName, request, timeoutMs, signal);
+    }
+    async routeSendFromSpotToSpot(sourceSpot, spotRouteTarget, packetName, message, signal, metadata, timeoutMs) {
+        await this.sourceSpotRouter.send(sourceSpot, spotRouteTarget, packetName, message, signal, metadata, timeoutMs);
+    }
+    routeRequestRawFromSpotToSpot(sourceSpot, spotRouteTarget, request, timeoutMs, signal) {
+        return this.sourceSpotRouter.requestRaw(sourceSpot, spotRouteTarget, request, timeoutMs, signal);
+    }
+    async routeRequestRawToSpot(spotRouteTarget, request, timeoutMs, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (this.targets.hasNamedSpotNode(spotRouteTarget.routerChannelId)) {
+            const namedSpotNodeRequest = this.spotNodeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+            if (namedSpotNodeRequest !== undefined)
+                return namedSpotNodeRequest;
+        }
+        if (this.bridgeTransport.has(spotRouteTarget.routerChannelId)) {
+            return this.bridgeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+        }
+        const spotNodeRequest = this.spotNodeTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+        if (spotNodeRequest !== undefined) {
+            return spotNodeRequest;
+        }
+        return this.routerSocketTransport.requestRaw(spotRouteTarget, request, timeoutMs, signal);
+    }
+}
+exports.ZLinkSpotRouteDispatchStrategy = ZLinkSpotRouteDispatchStrategy;

package/dist/runtime/channels/spot-route-target-resolver.d.ts

@@ -0,0 +1,16 @@
+import type { ZLinkBackendSpot, ZLinkBackendSpotNode } from '../backend/contracts';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+export declare class ZLinkSpotRouteTargetResolver {
+    private readonly registration;
+    private spotNodes?;
+    constructor(registration: ZLinkFrameworkRegistration);
+    setSpotNodes(spotNodes: ReadonlyMap<string, ZLinkBackendSpotNode>): void;
+    routeNode(routerChannelId: string): ZLinkBackendSpotNode | undefined;
+    localRouteNode(target: ZLinkSpotRouteTarget): ZLinkBackendSpotNode | undefined;
+    spotNodeRouter(routerChannelId: string): ZLinkBackendSpot | undefined;
+    canRouteChannel(routerChannelId: string): boolean;
+    canRoutePacketChannel(routerChannelId: string): boolean;
+    hasBoundRouteRouter(routerChannelId: string): boolean;
+    hasNamedSpotNode(routerChannelId: string): boolean;
+}

package/dist/runtime/channels/spot-route-target-resolver.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSpotRouteTargetResolver = void 0;
+class ZLinkSpotRouteTargetResolver {
+    registration;
+    spotNodes;
+    constructor(registration) {
+        this.registration = registration;
+    }
+    setSpotNodes(spotNodes) {
+        this.spotNodes = spotNodes;
+    }
+    routeNode(routerChannelId) {
+        const named = this.registration.spotNodes.get(routerChannelId);
+        if (named?.router !== undefined) {
+            return this.spotNodes?.get(routerChannelId);
+        }
+        const channelOwners = [...this.registration.spotNodes.entries()]
+            .filter(([, node]) => Object.prototype.hasOwnProperty.call(node.meshChannels ?? {}, routerChannelId));
+        if (channelOwners.length === 1) {
+            return this.spotNodes?.get(channelOwners[0][0]);
+        }
+        const routeChannel = this.registration.routeChannelOptions.get(routerChannelId);
+        if (routeChannel === undefined) {
+            return undefined;
+        }
+        if (routeChannel.routingId !== undefined) {
+            for (const [spotNodeName, spotNode] of this.registration.spotNodes.entries()) {
+                if (spotNode.router?.routingId === routeChannel.routingId) {
+                    return this.spotNodes?.get(spotNodeName);
+                }
+            }
+        }
+        const routerNodeNames = [...this.registration.spotNodes.entries()]
+            .filter(([, spotNode]) => spotNode.router !== undefined)
+            .map(([spotNodeName]) => spotNodeName);
+        return routerNodeNames.length === 1 ? this.spotNodes?.get(routerNodeNames[0]) : undefined;
+    }
+    localRouteNode(target) {
+        const routeNode = this.routeNode(target.routerChannelId) ?? this.spotNodes?.get(target.routerChannelId);
+        return routeNode !== undefined && routingIdsMatchSpotRoute(routeNode.routingId, target.targetNodeRid)
+            ? routeNode
+            : undefined;
+    }
+    spotNodeRouter(routerChannelId) {
+        if (this.registration.spotNodes.get(routerChannelId)?.router !== undefined) {
+            return this.spotNodes?.get(routerChannelId)?.entrySpot();
+        }
+        const routeBridgeNode = this.routeNode(routerChannelId);
+        return (routeBridgeNode ?? this.spotNodes?.get(routerChannelId))?.entrySpot();
+    }
+    canRouteChannel(routerChannelId) {
+        return this.registration.routeChannels.has(routerChannelId)
+            || this.spotNodeRouter(routerChannelId) !== undefined;
+    }
+    canRoutePacketChannel(routerChannelId) {
+        if (this.spotNodes?.has(routerChannelId) ?? false) {
+            return false;
+        }
+        return this.registration.routeChannels.has(routerChannelId);
+    }
+    hasBoundRouteRouter(routerChannelId) {
+        return this.registration.routeChannelOptions.get(routerChannelId)?.bind !== undefined;
+    }
+    hasNamedSpotNode(routerChannelId) {
+        return this.registration.spotNodes.has(routerChannelId);
+    }
+}
+exports.ZLinkSpotRouteTargetResolver = ZLinkSpotRouteTargetResolver;
+function routingIdsMatchSpotRoute(left, right) {
+    if (left === undefined || right === undefined) {
+        return false;
+    }
+    const rightCandidates = spotRouteRoutingIdCandidates(right);
+    return [...spotRouteRoutingIdCandidates(left)].some(candidate => rightCandidates.has(candidate));
+}
+function spotRouteRoutingIdCandidates(routingId) {
+    const candidates = new Set();
+    const toHex = routingId.toHex;
+    if (typeof toHex === 'function') {
+        candidates.add(toHex.call(routingId).toLowerCase());
+    }
+    const text = String(routingId);
+    candidates.add(text.toLowerCase());
+    try {
+        candidates.add(Buffer.from(text, 'utf8').toString('hex'));
+    }
+    catch {
+        // This legacy route path also receives routing ids already encoded as hex strings.
+    }
+    return candidates;
+}

package/dist/runtime/codecs/index.d.ts

@@ -0,0 +1,14 @@
+import type { ZLinkCodecExtension, ZLinkCodecRegistrar, ZLinkCodecRegistryBuilder, ZLinkMessageTypeSelector, ZLinkMessageSerializer } from '../../contracts';
+export declare class DefaultZLinkCodecRegistryBuilder implements ZLinkCodecRegistryBuilder, ZLinkCodecRegistrar {
+    private readonly serializers;
+    private readonly serializerSelections;
+    private readonly streamCodecs;
+    private readonly codecs;
+    get registeredCodecs(): readonly string[];
+    get registeredSerializers(): ReadonlyMap<string, ZLinkMessageSerializer>;
+    get registeredStreamCodecs(): ReadonlyMap<string, unknown>;
+    use(extension: ZLinkCodecExtension): this;
+    addSerializer(contentType: string, serializer: ZLinkMessageSerializer): this;
+    addSerializer(contentType: string, serializer: ZLinkMessageSerializer, canSerialize: ZLinkMessageTypeSelector): this;
+    addStreamCodec(contentType: string, codec: unknown): this;
+}

package/dist/runtime/codecs/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkCodecRegistryBuilder = void 0;
+const CodecContentType_1 = require("../../contracts/Configuration/CodecContentType");
+const CodecSerializerSelection_1 = require("../../contracts/Configuration/CodecSerializerSelection");
+class DefaultZLinkCodecRegistryBuilder {
+    serializers = new Map();
+    serializerSelections = new Map();
+    streamCodecs = new Map();
+    codecs = new Set();
+    get registeredCodecs() {
+        return [...this.codecs];
+    }
+    get registeredSerializers() {
+        return (0, CodecSerializerSelection_1.rememberCodecSerializerSelections)(this.serializers, this.serializerSelections);
+    }
+    get registeredStreamCodecs() {
+        return this.streamCodecs;
+    }
+    use(extension) {
+        extension.register(this);
+        return this;
+    }
+    addSerializer(contentType, serializer, canSerialize) {
+        const normalized = (0, CodecContentType_1.normalizeCodecContentType)(contentType);
+        this.serializers.delete(normalized);
+        this.serializerSelections.delete(normalized);
+        this.serializers.set(normalized, serializer);
+        this.serializerSelections.set(normalized, {
+            selector: canSerialize ?? CodecSerializerSelection_1.matchEveryDeclaredMessageType,
+            fallback: canSerialize === undefined
+        });
+        this.codecs.add(normalized);
+        return this;
+    }
+    addStreamCodec(contentType, codec) {
+        const normalized = (0, CodecContentType_1.normalizeCodecContentType)(contentType);
+        this.streamCodecs.delete(normalized);
+        this.streamCodecs.set(normalized, codec);
+        this.codecs.add(normalized);
+        return this;
+    }
+}
+exports.DefaultZLinkCodecRegistryBuilder = DefaultZLinkCodecRegistryBuilder;

package/dist/runtime/configuration/index.d.ts

@@ -0,0 +1 @@
+export * from '../../contracts/Configuration/Registration';

package/dist/runtime/configuration/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../../contracts/Configuration/Registration"), exports);

package/dist/runtime/diagnostics/dispatch-error-port.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime-owned port for reporting exceptions raised after dispatch admission.
+ * Keeping the port in diagnostics prevents the channel reporter from becoming
+ * a dependency of the message-flow tracer.
+ */
+export interface ZLinkDispatchErrorSink {
+    reportRuntimeTaskException(taskName: string, error: unknown): void;
+}

package/dist/runtime/diagnostics/dispatch-error-port.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });