@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-outbound.d.ts

@@ -0,0 +1,78 @@
+import type { RoutingId, ZLinkChannelClient, ZLinkChannelRequestCall, ZLinkPublishCall, ZLinkSendCall, ZLinkSpotOutbound, ZLinkSpotRequestCall, ZLinkSpotSendCall, ZLinkSpotPublisherClient } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkSpotRouteTarget } from './spot-routing-internal';
+import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
+import { type SpotHandle } from './spot-handle';
+export interface DefaultZLinkSpotOutboundOptions {
+    readonly serial: ZLinkSpotSerialTurnExecutor;
+    readonly channelClient?: ZLinkChannelClient;
+    readonly spotPublisherClient?: ZLinkSpotPublisherClient;
+    readonly routedTransport?: ZLinkSpotRoutedTransport;
+    readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
+    readonly sourceSpotProvider?: () => ZLinkBackendSpot | undefined;
+    readonly meshName?: string;
+    readonly addressTransport?: ZLinkSpotAddressTransport;
+}
+export declare class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
+    private readonly serial;
+    private readonly channelClient;
+    private readonly spotPublisherClient;
+    private readonly routedTransport;
+    private readonly spotRouterChannelIdForMesh;
+    private readonly sourceSpotProvider;
+    private readonly meshName;
+    private readonly addressTransport;
+    constructor(options: DefaultZLinkSpotOutboundOptions);
+    sendToSpot(spotId: RoutingId, message: unknown): ZLinkSpotSendCall;
+    requestToSpot(spotId: RoutingId, request: unknown): ZLinkSpotRequestCall;
+    publish(channelName: string, topic: string, event: unknown): ZLinkPublishCall;
+    sendToChannel(channelName: string, message: unknown): ZLinkSendCall;
+    requestToChannel(channelName: string, request: unknown): ZLinkChannelRequestCall;
+    private requireChannelClient;
+    private requireMeshName;
+    private requireRoutedTransport;
+    private requireAddressTransport;
+}
+export interface ZLinkSpotAddressCallOptions {
+    readonly metadata?: ReadonlyMap<string, string>;
+    readonly instanceSpot: boolean;
+    readonly instanceSpotType?: string;
+    readonly initialMeshName?: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly sourceSpot?: ZLinkBackendSpot;
+}
+/**
+ * Resolves current authority and owns Missing Instance placement and
+ * activation. Public callers never handle an owner or generation fence.
+ */
+export interface ZLinkSpotAddressTransport {
+    sendToSpotAddress(spotId: RoutingId, message: unknown, options: ZLinkSpotAddressCallOptions): Promise<ZLinkSubmitResult>;
+    requestToSpotAddress<TReply = unknown>(spotId: RoutingId, request: unknown, options: ZLinkSpotAddressCallOptions): Promise<TReply>;
+}
+export interface ZLinkSpotRoutedTransport {
+    sendToSpot(spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: ZLinkSpotRoutedSendOptions): Promise<ZLinkSubmitResult>;
+    sendFromSpotToSpot?(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, message: unknown, options: ZLinkSpotRoutedSendOptions): Promise<ZLinkSubmitResult>;
+    requestToSpot<TReply = unknown>(spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: ZLinkSpotRoutedRequestOptions): Promise<TReply>;
+    requestFromSpotToSpot?<TReply = unknown>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: ZLinkSpotRoutedRequestOptions): Promise<TReply>;
+}
+export interface ZLinkSpotRoutedSendOptions {
+    readonly packetName?: string;
+    /** Internal end-to-end budget remaining for route admission. */
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly metadata?: ReadonlyMap<string, string>;
+}
+export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+    readonly timeoutMs?: number;
+}
+export interface ZLinkSpotHandleCallOptions {
+    readonly metadata?: ReadonlyMap<string, string>;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
+    readonly sourceSpot?: ZLinkBackendSpot;
+}
+export declare function sendToSpotHandle(transport: ZLinkSpotRoutedTransport, spot: SpotHandle, message: unknown, options?: ZLinkSpotHandleCallOptions): Promise<ZLinkSubmitResult>;
+export declare function requestToSpotHandle<TReply = unknown>(transport: ZLinkSpotRoutedTransport, spot: SpotHandle, request: unknown, options?: ZLinkSpotHandleCallOptions): Promise<TReply>;

package/dist/runtime/spots/spot-outbound.js

@@ -0,0 +1,460 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkSpotOutbound = void 0;
+exports.sendToSpotHandle = sendToSpotHandle;
+exports.requestToSpotHandle = requestToSpotHandle;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const Errors_1 = require("../../contracts/Errors");
+const submission_result_1 = require("../messaging/submission-result");
+const routing_id_1 = require("../routing-id");
+const configuration_1 = require("../configuration");
+const workers_1 = require("../workers");
+const execution_1 = require("../execution");
+const packet_name_1 = require("../messaging/packet-name");
+const spot_handle_1 = require("./spot-handle");
+class DefaultZLinkSpotOutbound {
+    serial;
+    channelClient;
+    spotPublisherClient;
+    routedTransport;
+    spotRouterChannelIdForMesh;
+    sourceSpotProvider;
+    meshName;
+    addressTransport;
+    constructor(options) {
+        this.serial = options.serial;
+        this.channelClient = options.channelClient;
+        this.spotPublisherClient = options.spotPublisherClient;
+        this.routedTransport = options.routedTransport;
+        this.spotRouterChannelIdForMesh = options.spotRouterChannelIdForMesh
+            ?? ((meshName) => meshName);
+        this.sourceSpotProvider = options.sourceSpotProvider;
+        this.meshName = options.meshName;
+        this.addressTransport = options.addressTransport;
+    }
+    sendToSpot(spot, message) {
+        if (typeof spot !== 'object') {
+            return createAddressedSpotSendCall(this.serial, this.requireAddressTransport(), spot, message, this.sourceSpotProvider);
+        }
+        return wrapRoutedSpotSendCall(this.serial, this.requireRoutedTransport(), spot, message, this.spotRouterChannelIdForMesh, this.sourceSpotProvider);
+    }
+    requestToSpot(spot, request) {
+        if (typeof spot !== 'object') {
+            return createAddressedSpotRequestCall(this.serial, this.requireAddressTransport(), spot, request, this.sourceSpotProvider);
+        }
+        return wrapRoutedSpotRequestCall(this.serial, this.requireRoutedTransport(), spot, request, this.spotRouterChannelIdForMesh, this.sourceSpotProvider);
+    }
+    publish(channelName, topic, event) {
+        if (this.spotPublisherClient !== undefined) {
+            return wrapPublishCall(this.serial, this.spotPublisherClient.publish(this.requireMeshName(), channelName, topic, event));
+        }
+        throw new configuration_1.ZLinkConfigurationException('Spot outbound publish requires a configured Spot publisher client.');
+    }
+    sendToChannel(channelName, message) {
+        return wrapSendCall(this.serial, this.requireChannelClient().sendToChannel(channelName, message));
+    }
+    requestToChannel(channelName, request) {
+        return wrapRequestCall(this.serial, this.requireChannelClient().requestToChannel(channelName, request));
+    }
+    requireChannelClient() {
+        if (this.channelClient === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Spot channel outbound runtime is not started.');
+        }
+        return this.channelClient;
+    }
+    requireMeshName() {
+        if (this.meshName === undefined || this.meshName.length === 0) {
+            throw new configuration_1.ZLinkConfigurationException('Spot channel outbound requires a MeshName context.');
+        }
+        return this.meshName;
+    }
+    requireRoutedTransport() {
+        if (this.routedTransport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Spot routed outbound runtime is not started.');
+        }
+        return this.routedTransport;
+    }
+    requireAddressTransport() {
+        if (this.addressTransport === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Spot address outbound runtime is not started.');
+        }
+        return this.addressTransport;
+    }
+}
+exports.DefaultZLinkSpotOutbound = DefaultZLinkSpotOutbound;
+function createAddressedSpotSendCall(serial, transport, spotId, message, sourceSpotProvider) {
+    const options = newAddressCallOptions();
+    return {
+        metadata(key, value) {
+            addMetadata(options, key, value);
+            return this;
+        },
+        instanceSpot(instanceSpotType) {
+            selectOnce(options, 'instanceSpot');
+            options.instanceSpot = true;
+            if (instanceSpotType !== undefined) {
+                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+            }
+            return this;
+        },
+        inMesh(meshName) {
+            selectOnce(options, 'inMesh');
+            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+            return this;
+        },
+        async submit(signal) {
+            markSubmitted(options);
+            const pending = startRequestOnSerial(serial, () => ({
+                pending: transport.sendToSpotAddress(spotId, message, freezeAddressCallOptions(options, signal, sourceSpotProvider?.()))
+            }));
+            const result = await (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending));
+            (0, submission_result_1.requireOneWayCompletion)(result, 'Spot send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound);
+        }
+    };
+}
+function createAddressedSpotRequestCall(serial, transport, spotId, request, sourceSpotProvider) {
+    const options = newAddressCallOptions();
+    const begin = (waitPolicy, signal) => {
+        markSubmitted(options);
+        rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
+        return startRequestOnSerial(serial, () => ({
+            pending: transport.requestToSpotAddress(spotId, request, freezeAddressCallOptions(options, signal, sourceSpotProvider?.()))
+        }));
+    };
+    return {
+        metadata(key, value) {
+            addMetadata(options, key, value);
+            return this;
+        },
+        instanceSpot(instanceSpotType) {
+            selectOnce(options, 'instanceSpot');
+            options.instanceSpot = true;
+            if (instanceSpotType !== undefined) {
+                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+            }
+            return this;
+        },
+        inMesh(meshName) {
+            selectOnce(options, 'inMesh');
+            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+            return this;
+        },
+        timeout(timeoutMs) {
+            selectOnce(options, 'timeout');
+            if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0) {
+                throw new configuration_1.ZLinkConfigurationException('Spot request timeout must be a positive safe integer.');
+            }
+            options.timeoutMs = timeoutMs;
+            return this;
+        },
+        submit(signal) {
+            const pending = begin('async', signal);
+            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+        },
+        yield(signal) {
+            const turn = (0, execution_1.requireZLinkYieldTurn)();
+            const pending = begin('yield', signal);
+            return turn.yieldPromise(pending);
+        }
+    };
+}
+function newAddressCallOptions() {
+    return {
+        metadata: new Map(),
+        metadataPresent: false,
+        instanceSpot: false,
+        submitted: false,
+        selected: new Set()
+    };
+}
+function selectOnce(options, name) {
+    if (options.submitted) {
+        (0, submission_result_1.throwAlreadySubmitted)('Spot call');
+    }
+    if (options.selected.has(name)) {
+        throw new configuration_1.ZLinkConfigurationException(`Spot call option '${name}' was already selected.`);
+    }
+    options.selected.add(name);
+}
+function addMetadata(options, key, value) {
+    if (options.submitted) {
+        (0, submission_result_1.throwAlreadySubmitted)('Spot call');
+    }
+    options.metadataPresent = true;
+    if (typeof key === 'string') {
+        options.metadata.set(key, value);
+        return;
+    }
+    for (const [metadataKey, metadataValue] of key.values) {
+        options.metadata.set(metadataKey, metadataValue);
+    }
+}
+function markSubmitted(options) {
+    if (options.submitted) {
+        (0, submission_result_1.throwAlreadySubmitted)('Spot call');
+    }
+    if (!options.instanceSpot && (options.instanceSpotType !== undefined
+        || options.initialMeshName !== undefined)) {
+        throw new configuration_1.ZLinkConfigurationException('Mesh selection requires an Instance Spot intent.');
+    }
+    options.submitted = true;
+}
+function freezeAddressCallOptions(options, signal, sourceSpot) {
+    return {
+        ...(options.metadataPresent ? { metadata: new Map(options.metadata) } : {}),
+        instanceSpot: options.instanceSpot,
+        instanceSpotType: options.instanceSpotType,
+        initialMeshName: options.initialMeshName,
+        timeoutMs: options.timeoutMs,
+        signal,
+        sourceSpot
+    };
+}
+function requireAddressValue(value, label, maxBytes) {
+    const byteLength = Buffer.byteLength(value, 'utf8');
+    if (byteLength < 1 || byteLength > maxBytes || value.includes('\0')) {
+        throw new configuration_1.ZLinkConfigurationException(`${label} must contain 1..${maxBytes} UTF-8 bytes and no NUL.`);
+    }
+    return value;
+}
+function wrapSendCall(serial, inner) {
+    return {
+        metadata(key, value) {
+            if (typeof key === 'string')
+                inner.metadata(key, value);
+            else
+                inner.metadata(key);
+            return this;
+        },
+        async submit(signal) {
+            const result = await runInternalTransportStart(serial, () => inner.submit(signal));
+            return result;
+        }
+    };
+}
+function wrapPublishCall(serial, inner) {
+    return {
+        metadata(key, value) {
+            if (typeof key === 'string')
+                inner.metadata(key, value);
+            else
+                inner.metadata(key);
+            return this;
+        },
+        submit(signal) {
+            return runInternalTransportStart(serial, () => inner.submit(signal));
+        }
+    };
+}
+function wrapRequestCall(serial, inner) {
+    const begin = (signal) => startRequestOnSerial(serial, () => ({ pending: inner.submit(signal) }));
+    return {
+        metadata(key, value) {
+            if (typeof key === 'string')
+                inner.metadata(key, value);
+            else
+                inner.metadata(key);
+            return this;
+        },
+        timeout(timeoutMs) {
+            inner.timeout(timeoutMs);
+            return this;
+        },
+        submit(signal) {
+            const pending = begin(signal);
+            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+        },
+        yield(signal) {
+            const turn = (0, execution_1.requireZLinkYieldTurn)();
+            const pending = begin(signal);
+            return turn.yieldPromise(pending);
+        }
+    };
+}
+/**
+ * Starts an outbound request in Spot serial order without gating the serial
+ * line on the request round trip. When already running inside the Spot line
+ * (a handler turn), the request starts immediately as part of that turn;
+ * otherwise the start is enqueued as its own serial turn.
+ */
+function startRequestOnSerial(serial, begin) {
+    return runInternalTransportStart(serial, begin)
+        .then((startedRequest) => startedRequest.pending);
+}
+/**
+ * Synthesizes only the transport start in the current turn. This is not a
+ * nested public operation: public same-owner waits are rejected or use Yield.
+ */
+function runInternalTransportStart(serial, begin) {
+    return serial.isCurrentTurn
+        ? Promise.resolve().then(begin)
+        : serial.post(begin);
+}
+function wrapRoutedSpotSendCall(serial, transport, spot, message, spotRouterChannelIdForMesh, sourceSpotProvider) {
+    const metadata = new Map();
+    return {
+        metadata(key, value) {
+            if (typeof key === 'string') {
+                metadata.set(key, value);
+            }
+            else {
+                for (const [selectedKey, selectedValue] of key.values) {
+                    metadata.set(selectedKey, selectedValue);
+                }
+            }
+            return this;
+        },
+        async submit(signal) {
+            const pending = startRequestOnSerial(serial, () => ({
+                pending: sendToSpotHandle(transport, spot, message, {
+                    metadata,
+                    signal,
+                    spotRouterChannelIdForMesh,
+                    sourceSpot: sourceSpotProvider?.()
+                })
+            }));
+            const result = await (serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending));
+            (0, submission_result_1.requireOneWayCompletion)(result, 'Spot send', framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound);
+        }
+    };
+}
+function wrapRoutedSpotRequestCall(serial, transport, spot, request, spotRouterChannelIdForMesh, sourceSpotProvider) {
+    let selectedTimeoutMs;
+    const metadata = new Map();
+    const begin = (waitPolicy, signal) => {
+        // A request to the current Spot would wait behind the handler that owns
+        // the same Spot claim. Reject it before resolving a route or submitting
+        // transport work; one-way self-send remains a valid FIFO admission.
+        rejectSameSpotAsyncRequest(serial, spot.spotId, waitPolicy);
+        return startRequestOnSerial(serial, () => ({
+            pending: requestToSpotHandle(transport, spot, request, {
+                timeoutMs: selectedTimeoutMs,
+                signal,
+                metadata,
+                spotRouterChannelIdForMesh,
+                sourceSpot: sourceSpotProvider?.()
+            })
+        }));
+    };
+    return {
+        metadata(key, value) {
+            if (typeof key === 'string') {
+                metadata.set(key, value);
+            }
+            else {
+                for (const [metadataKey, metadataValue] of key.values) {
+                    metadata.set(metadataKey, metadataValue);
+                }
+            }
+            return this;
+        },
+        timeout(timeoutMs) {
+            selectedTimeoutMs = timeoutMs;
+            return this;
+        },
+        submit(signal) {
+            const pending = begin('async', signal);
+            return serial.isCurrentTurn ? pending : (0, workers_1.deliverOnSerial)(serial, pending);
+        },
+        yield(signal) {
+            const turn = (0, execution_1.requireZLinkYieldTurn)();
+            const pending = begin('yield', signal);
+            return turn.yieldPromise(pending);
+        }
+    };
+}
+function rejectSameSpotAsyncRequest(serial, targetSpotId, waitPolicy) {
+    if (waitPolicy === 'yield' || !serial.isCurrentTurn)
+        return;
+    const sourceSpotId = serial.sourceSpotId;
+    if (sourceSpotId === undefined || String(sourceSpotId) !== String(targetSpotId))
+        return;
+    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `A Spot request cannot await the current Spot '${String(sourceSpotId)}' while holding its execution claim.`);
+}
+async function sendToSpotHandle(transport, spot, message, options = {}) {
+    const packetName = (0, packet_name_1.resolveFrameworkPacketName)(message, undefined, 'SPOT');
+    const sendResolved = async (resolved) => {
+        const target = spotRefToSpotRouteTarget(resolved, options.spotRouterChannelIdForMesh);
+        if (options.sourceSpot !== undefined && transport.sendFromSpotToSpot !== undefined) {
+            return transport.sendFromSpotToSpot(options.sourceSpot, target, message, {
+                packetName,
+                timeoutMs: options.timeoutMs,
+                signal: options.signal,
+                metadata: options.metadata
+            });
+        }
+        return transport.sendToSpot(target, message, {
+            packetName,
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            metadata: options.metadata
+        });
+    };
+    return sendResolved(await requireSpotRef(spot, options.signal));
+}
+async function requestToSpotHandle(transport, spot, request, options = {}) {
+    const packetName = (0, packet_name_1.resolveFrameworkPacketName)(request, undefined, 'SPOT');
+    const requestResolved = async (resolved) => {
+        const target = spotRefToSpotRouteTarget(resolved, options.spotRouterChannelIdForMesh);
+        const transportOptions = {
+            packetName,
+            timeoutMs: options.timeoutMs,
+            signal: options.signal,
+            metadata: options.metadata
+        };
+        if (options.sourceSpot !== undefined && transport.requestFromSpotToSpot !== undefined) {
+            return transport.requestFromSpotToSpot(options.sourceSpot, target, request, transportOptions);
+        }
+        return transport.requestToSpot(target, request, transportOptions);
+    };
+    const resolved = await requireSpotRef(spot, options.signal);
+    try {
+        return await requestResolved(resolved);
+    }
+    catch (error) {
+        if (!shouldRefreshAfterRouteDisconnect(resolved, error)) {
+            throw error;
+        }
+        let refreshed;
+        try {
+            refreshed = await (0, spot_handle_1.refreshSpotHandle)(spot, options.signal);
+        }
+        catch {
+            throw error;
+        }
+        if (isShutdownTargetState(refreshed?.targetNodeState)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown, `Spot '${String(spot.spotId)}' target host is shutting down.`, false, error);
+        }
+        throw error;
+    }
+}
+async function requireSpotRef(handle, signal) {
+    const resolved = await (0, spot_handle_1.resolveSpotHandle)(handle, signal);
+    if (resolved === undefined) {
+        throw new configuration_1.ZLinkConfigurationException(`Spot '${handle.spotId}' has no live location.`);
+    }
+    return resolved;
+}
+function spotRefToSpotRouteTarget(spot, spotRouterChannelIdForMesh = (meshName) => meshName) {
+    return {
+        routerChannelId: spotRouterChannelIdForMesh(spot.meshName),
+        targetNodeRid: normalizeSpotRefRoutingId(spot.nodeRid),
+        spotId: normalizeSpotRefRoutingId(spot.spotId),
+        spotKind: spot.spotKind ?? contracts_1.ZLinkSpotKind.User,
+        targetSpotGeneration: spot.spotGeneration,
+        targetNodeState: spot.targetNodeState
+    };
+}
+function shouldRefreshAfterRouteDisconnect(target, error) {
+    return target.targetNodeState === contracts_1.ZLinkFrameworkRuntimeState.Serving
+        && error instanceof Errors_1.ZLinkFrameworkException
+        && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected;
+}
+function isShutdownTargetState(state) {
+    return state === contracts_1.ZLinkFrameworkRuntimeState.Draining
+        || state === contracts_1.ZLinkFrameworkRuntimeState.Stopped;
+}
+function normalizeSpotRefRoutingId(routingId) {
+    return (0, routing_id_1.normalizeOpaqueRoutingId)(routingId);
+}

package/dist/runtime/spots/spot-provider.d.ts

@@ -0,0 +1,4 @@
+import type { Type } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+export declare function createProviderInstance<T>(type: Type<T>, resolver: ZLinkProviderResolver | undefined, fallbackArg?: unknown): Promise<T>;
+export declare function createFreshProviderInstance<T>(type: Type<T>, resolver: ZLinkProviderResolver | undefined, fallbackArg?: unknown): Promise<T>;

package/dist/runtime/spots/spot-provider.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProviderInstance = createProviderInstance;
+exports.createFreshProviderInstance = createFreshProviderInstance;
+async function createProviderInstance(type, resolver, fallbackArg) {
+    const existing = resolver?.get?.(type);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = await resolver?.create?.(type);
+    if (created !== undefined) {
+        return created;
+    }
+    if (fallbackArg !== undefined) {
+        return new type(fallbackArg);
+    }
+    return new type();
+}
+async function createFreshProviderInstance(type, resolver, fallbackArg) {
+    const created = await resolver?.create?.(type);
+    if (created !== undefined) {
+        return created;
+    }
+    if (fallbackArg !== undefined) {
+        return new type(fallbackArg);
+    }
+    return new type();
+}

package/dist/runtime/spots/spot-publisher-transport.d.ts

@@ -0,0 +1,14 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkSpotPublisherClientTransport } from '../channels';
+import type { ZLinkSubmitResult } from '../messaging/submission-result';
+interface ZLinkRuntimeSpotPublisherManager {
+    tryPublish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
+    publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+}
+export declare class ZLinkRuntimeSpotPublisherTransport implements ZLinkSpotPublisherClientTransport {
+    private readonly manager;
+    constructor(manager: () => ZLinkRuntimeSpotPublisherManager | undefined);
+    tryPublish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;
+    publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
+}
+export {};

package/dist/runtime/spots/spot-publisher-transport.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkRuntimeSpotPublisherTransport = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+class ZLinkRuntimeSpotPublisherTransport {
+    manager;
+    constructor(manager) {
+        this.manager = manager;
+    }
+    tryPublish(meshName, channelName, topic, packetName, event, metadata) {
+        const manager = this.manager();
+        if (manager === undefined) {
+            throw publisherRuntimeShutdown();
+        }
+        return manager.tryPublish(meshName, channelName, topic, packetName, event, metadata);
+    }
+    publish(meshName, channelName, topic, packetName, event, signal, metadata) {
+        const manager = this.manager();
+        if (manager === undefined) {
+            throw publisherRuntimeShutdown();
+        }
+        return manager.publish(meshName, channelName, topic, packetName, event, signal, metadata);
+    }
+}
+exports.ZLinkRuntimeSpotPublisherTransport = ZLinkRuntimeSpotPublisherTransport;
+function publisherRuntimeShutdown() {
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown, 'SPOT publisher runtime is not available because the runtime is not started or is shutting down.');
+}

package/dist/runtime/spots/spot-remote-codec.d.ts

@@ -0,0 +1,50 @@
+import type { ZLinkBackendActorRef } from '../backend/contracts';
+import { type ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { RoutingId, ZLinkActor } from '../../contracts';
+import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import { decodeChannelEnvelope } from '../channels/channel-envelope';
+import { REMOTE_ACTOR_JOIN_PACKET, type ZLinkRemoteActorJoinWirePayload } from '../actors/actor-remote-wire';
+export { REMOTE_ACTOR_JOIN_PACKET };
+export declare const REMOTE_BOUND_SESSION_BIND_PACKET = "zlink.framework.actor.bound_session.bind";
+export interface ZLinkRemoteActorJoinActor {
+    readonly actor: ZLinkActor;
+    readonly actorRef: ZLinkBackendActorRef;
+}
+export type ZLinkRoutedActorTransferProvider = (actorId: string, actorType: string, adapterKey: string | undefined, transferState: Message, actorEntryNodeRid: RoutingId | undefined, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, signal?: AbortSignal) => Promise<ZLinkRemoteActorJoinActor>;
+export interface ZLinkDecodedRemoteActorJoinRequest {
+    readonly envelope?: ReturnType<typeof decodeChannelEnvelope>;
+    readonly raw: boolean;
+    readonly actorId: string;
+    readonly actorType: string;
+    readonly actorRef?: ZLinkBackendActorRef;
+    readonly expectedMembershipEpoch: bigint;
+    readonly actorEntryNodeRid?: RoutingId;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly actorCreateRequest?: Message;
+    readonly request: Message;
+    readonly requestContentType: string;
+    readonly phase?: 'admission' | 'commit';
+    readonly transferId?: string;
+    readonly transferAdapterKey?: string;
+    readonly transferState?: Message;
+    readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
+}
+export type { ZLinkRemoteActorJoinWirePayload };
+export declare function hasRemoteActorJoinIdentity(value: unknown): value is ZLinkRemoteActorJoinWirePayload & {
+    readonly actorId: string;
+    readonly actorType: string;
+};
+export declare function isRemoteActorJoinPayload(value: unknown): value is ZLinkRemoteActorJoinWirePayload & {
+    readonly actorId: string;
+    readonly actorType: string;
+    readonly request: string;
+};
+export declare function decodeRemoteActorJoinPayload(payload: ZLinkRemoteActorJoinWirePayload & {
+    readonly actorId: string;
+    readonly actorType: string;
+}, request: Message, received: BackendReceived, raw: boolean, envelope?: ReturnType<typeof decodeChannelEnvelope>): ZLinkDecodedRemoteActorJoinRequest;
+export declare function decodeHandoffBacklog(value: unknown): readonly ZLinkActorHandoffPacket[];
+export declare function decodeRemoteActorRef(nodeRid: unknown, nodeRidHex: unknown, actorId: string, generation: unknown): ZLinkBackendActorRef | undefined;
+export declare function decodeRemoteBoundSessionTarget(routerChannelId: unknown, targetNodeRid: unknown, targetNodeRidHex: unknown, spotId: unknown, sessionNodeRid: unknown, sessionNodeRidHex: unknown, sessionRid: unknown, sessionRidHex: unknown, bindingGeneration: unknown, previousAuthorityOwnerGeneration?: unknown, previousOwnerLeaseGeneration?: unknown, relocationSealId?: unknown, serviceWireRelocation?: unknown): ZLinkRemoteBoundSessionTarget | undefined;