@zlink-systems/framework 0.10.0

package/dist/runtime/host/spot-address-transport.d.ts

@@ -0,0 +1,47 @@
+import { type RoutingId } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { ZLinkBackendMeshNode } from '../backend/contracts';
+import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import { type ZLinkChannelEnvelopeCodecRegistry } from '../channels/channel-envelope';
+import type { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkSpotAddressCallOptions, ZLinkSpotAddressTransport, ZLinkSpotRoutedTransport } from '../spots/spot-outbound';
+import type { ZLinkSpotRouteResolver } from '../spots/spot-routing-internal';
+export interface ZLinkHostSpotAddressTransportOptions {
+    readonly resolver: () => ZLinkSpotRouteResolver | undefined;
+    readonly routed: ZLinkSpotRoutedTransport;
+    readonly meshNames: () => readonly string[];
+    readonly isMeshConfigured?: (meshName: string) => boolean;
+    readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly completions: (meshName: string) => ZLinkMeshCompletionTable | undefined;
+    readonly codecs?: ZLinkChannelEnvelopeCodecRegistry;
+    readonly defaultRequestTimeoutMs: number;
+    /** Internal one-way deadline policy; public calls do not expose this option. */
+    readonly defaultSendTimeoutMs?: number;
+    /** Resolves the send timeout for a configured Spot Mesh. */
+    readonly sendTimeoutMsForMesh?: (meshName: string) => number;
+    /** Resolves the send timeout for a resolved Spot route channel. */
+    readonly sendTimeoutMsForRouteChannel?: (routeChannelId: string) => number;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+}
+export declare function hasObjectClientCapability(role: 'none' | 'client' | 'server' | undefined): boolean;
+/** Owns global Spot authority lookup and Missing Instance placement. */
+export declare class ZLinkHostSpotAddressTransport implements ZLinkSpotAddressTransport {
+    private readonly options;
+    constructor(options: ZLinkHostSpotAddressTransportOptions);
+    sendToSpotAddress(spotId: RoutingId, message: unknown, call: ZLinkSpotAddressCallOptions): Promise<ZLinkSubmitResult>;
+    private sendToSpotAddressScoped;
+    requestToSpotAddress<TReply = unknown>(spotId: RoutingId, request: unknown, call: ZLinkSpotAddressCallOptions): Promise<TReply>;
+    private requestToSpotAddressScoped;
+    private requestToExistingSpot;
+    private requestToMissingInstance;
+    private reportInstanceRequestError;
+    private traceInstanceAddress;
+    private resolveExisting;
+    private recoverStaleInstanceRoute;
+    private selectMissingTarget;
+    private sendTimeoutMsForMesh;
+    private sendTimeoutMsForRouteChannel;
+    private validateExisting;
+    private encode;
+    private encodeAtDeadline;
+}

package/dist/runtime/host/spot-address-transport.js

@@ -0,0 +1,601 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkHostSpotAddressTransport = void 0;
+exports.hasObjectClientCapability = hasObjectClientCapability;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_values_1 = require("../backend/runtime-values");
+const contracts_1 = require("../../contracts");
+const submission_result_1 = require("../messaging/submission-result");
+const contracts_2 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const abort_1 = require("../abort");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const diagnostics_1 = require("../diagnostics");
+const flow_context_1 = require("../diagnostics/flow-context");
+const packet_name_1 = require("../messaging/packet-name");
+function hasObjectClientCapability(role) {
+    return role === 'client' || role === 'server';
+}
+// Only a synchronous target-admission rejection is safe to retry. A
+// completion with the same public error kind may already represent an
+// admitted application operation, so it must not enter the retry loop.
+const PRE_ADMISSION_MISSING_INSTANCE_ERRORS = new WeakSet();
+/** Owns global Spot authority lookup and Missing Instance placement. */
+class ZLinkHostSpotAddressTransport {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    sendToSpotAddress(spotId, message, call) {
+        // Call-scoped flow (spec 27 §4): the envelope encoders and the
+        // traceInstanceAddress points share one ambient flow that does not
+        // outlive this call.
+        return (0, flow_context_1.runWithOutboundFlow)(this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, () => this.sendToSpotAddressScoped(spotId, message, call));
+    }
+    async sendToSpotAddressScoped(spotId, message, call) {
+        const timeoutMs = initialSendTimeoutMs(this.options, call);
+        const deadline = createSpotAddressDeadline(timeoutMs, call.signal);
+        try {
+            const existing = await this.resolveExisting(spotId, deadline.signal);
+            deadline.requireRemaining();
+            if (existing !== undefined) {
+                this.validateExisting(existing, call);
+                deadline.setOwnerTimeout(this.sendTimeoutMsForRouteChannel(existing.routerChannelId));
+                try {
+                    const result = await (0, abort_1.awaitWithAbort)(this.options.routed.sendToSpot(existing, message, {
+                        timeoutMs: deadline.requireRemaining(),
+                        signal: deadline.signal,
+                        metadata: call.metadata
+                    }), deadline.signal);
+                    if (result.status === submission_result_1.ZLinkSubmitStatus.Submitted) {
+                        this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, existing.routerChannelId, existing.stableType, existing.targetNodeRid);
+                    }
+                    else {
+                        this.traceInstanceAddress(submitResultFlowOutcome(result.status), ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, existing.routerChannelId, existing.stableType, existing.targetNodeRid, submitResultReason(result.status));
+                    }
+                    if (result.status === submission_result_1.ZLinkSubmitStatus.TargetNotFound
+                        || result.status === submission_result_1.ZLinkSubmitStatus.RouteNotConnected) {
+                        this.options.resolver()?.invalidate?.(spotId);
+                    }
+                    return result;
+                }
+                catch (error) {
+                    if (isSpotRouteRefreshError(error)) {
+                        this.options.resolver()?.invalidate?.(spotId);
+                    }
+                    const reason = addressedInstanceErrorReason(error);
+                    this.traceInstanceAddress(reason === ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure
+                        ? ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured
+                        : ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, existing.routerChannelId, existing.stableType, existing.targetNodeRid, reason);
+                    throw error;
+                }
+            }
+            if (!call.instanceSpot) {
+                return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+            }
+            const selected = this.selectMissingTarget(spotId, call);
+            if (selected.kind === 'unsupported') {
+                this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, call.initialMeshName, call.instanceSpotType, undefined, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget);
+                return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+            }
+            if (selected.kind === 'capacity') {
+                const error = missingInstancePlacementCapacity(spotId, call.instanceSpotType);
+                this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, call.initialMeshName, call.instanceSpotType, undefined, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure);
+                throw error;
+            }
+            if (selected.kind === 'unavailable') {
+                this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, call.initialMeshName, call.instanceSpotType, undefined, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget);
+                return { status: submission_result_1.ZLinkSubmitStatus.RouteNotConnected };
+            }
+            deadline.setOwnerTimeout(this.sendTimeoutMsForMesh(selected.meshName));
+            const encoded = this.encode(3 /* ZLinkChannelMessageKind.Command */, selected.meshName, message);
+            const sourceSpotId = call.sourceSpot === undefined
+                ? undefined
+                : String(call.sourceSpot.routingId);
+            const mapped = mapSubmitResult(await (0, abort_1.awaitWithAbort)(selected.node.sendToMissingInstanceSpot(selected.target, encoded, BigInt(deadline.deadlineUnixMs), sourceSpotId, call.metadata), deadline.signal));
+            this.traceInstanceAddress(submitResultFlowOutcome(mapped.status), ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send, spotId, message, selected.meshName, selected.target.stableType, selected.target.targetNodeRid, mapped.status === submission_result_1.ZLinkSubmitStatus.Submitted ? undefined : submitResultReason(mapped.status));
+            return mapped;
+        }
+        catch (error) {
+            if (deadline.expired()) {
+                return { status: submission_result_1.ZLinkSubmitStatus.TimedOut };
+            }
+            throw error;
+        }
+        finally {
+            deadline.close();
+        }
+    }
+    requestToSpotAddress(spotId, request, call) {
+        return (0, flow_context_1.runWithOutboundFlow)(this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true, () => this.requestToSpotAddressScoped(spotId, request, call));
+    }
+    async requestToSpotAddressScoped(spotId, request, call) {
+        const timeoutMs = call.timeoutMs ?? this.options.defaultRequestTimeoutMs;
+        const deadline = createSpotAddressDeadline(timeoutMs, call.signal);
+        try {
+            for (;;) {
+                const existing = await this.resolveExisting(spotId, deadline.signal);
+                deadline.requireRemaining();
+                if (existing !== undefined) {
+                    this.validateExisting(existing, call);
+                    try {
+                        return await this.requestToExistingSpot(spotId, request, call, existing, deadline);
+                    }
+                    catch (error) {
+                        if (isSpotRouteRefreshError(error)) {
+                            this.options.resolver()?.invalidate?.(spotId);
+                        }
+                        const recovery = await this.recoverStaleInstanceRoute(spotId, call, deadline, error, existing);
+                        if (recovery.kind === 'route') {
+                            // Retry only after the resolver exposes a different route. The
+                            // stale target cannot have admitted the application operation.
+                            continue;
+                        }
+                        if (recovery.kind !== 'cold') {
+                            this.reportInstanceRequestError(spotId, request, error, existing.routerChannelId, existing.targetNodeRid, existing.stableType, addressedInstanceErrorReason(error));
+                            throw error;
+                        }
+                        // The logical authority is no longer Ready, so the Instance
+                        // intent path below may submit the original operation once.
+                    }
+                }
+                try {
+                    return await this.requestToMissingInstance(spotId, request, call, deadline);
+                }
+                catch (error) {
+                    if (!isMissingInstanceRetryError(error))
+                        throw error;
+                    // A placement node can finish cleanup before its stale native result
+                    // reaches this process. Refresh authority and select again under the
+                    // same end-to-end deadline; the old envelope was not admitted.
+                    this.options.resolver()?.invalidate?.(spotId);
+                    await waitForSpotRouteRefresh(Math.min(10, deadline.requireRemaining()), deadline.signal);
+                }
+            }
+        }
+        catch (error) {
+            if (deadline.expired()
+                && !(error instanceof contracts_1.ZLinkFrameworkException
+                    && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound)) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Spot request for '${String(spotId)}' exceeded its end-to-end deadline.`, true, error);
+            }
+            throw error;
+        }
+        finally {
+            deadline.close();
+        }
+    }
+    async requestToExistingSpot(spotId, request, call, existing, deadline) {
+        this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, existing.routerChannelId, existing.stableType, existing.targetNodeRid);
+        const reply = await (0, abort_1.awaitWithAbort)(this.options.routed.requestToSpot(existing, request, {
+            timeoutMs: deadline.requireRemaining(),
+            signal: deadline.signal,
+            metadata: call.metadata
+        }), deadline.signal);
+        this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, existing.routerChannelId, existing.stableType, existing.targetNodeRid);
+        return reply;
+    }
+    async requestToMissingInstance(spotId, request, call, deadline) {
+        if (!call.instanceSpot) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `Spot '${String(spotId)}' has no Ready authority.`);
+        }
+        const selected = this.selectMissingTarget(spotId, call);
+        if (selected.kind === 'capacity') {
+            throw missingInstancePlacementCapacity(spotId, call.instanceSpotType);
+        }
+        if (selected.kind === 'unsupported') {
+            const error = (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound, `No eligible Instance Spot target serves '${String(spotId)}'.`);
+            this.reportInstanceRequestError(spotId, request, error, call.initialMeshName, undefined, call.instanceSpotType, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget);
+            throw error;
+        }
+        if (selected.kind === 'unavailable') {
+            const error = missingInstancePlacementUnavailable(spotId, call.instanceSpotType);
+            this.reportInstanceRequestError(spotId, request, error, call.initialMeshName, undefined, call.instanceSpotType, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget);
+            throw error;
+        }
+        const deadlineUnixMs = BigInt(deadline.deadlineUnixMs);
+        const encoded = this.encodeAtDeadline(1 /* ZLinkChannelMessageKind.Request */, selected.meshName, request, deadline.deadlineUnixMs);
+        deadline.requireRemaining();
+        const table = this.options.completions(selected.meshName);
+        if (table === undefined)
+            throw new Error(`MeshNode '${selected.meshName}' completion table is not started.`);
+        let completionPromise;
+        try {
+            completionPromise = table.submit(() => selected.node.requestToMissingInstanceSpot(selected.target, encoded, deadlineUnixMs, call.sourceSpot === undefined ? undefined : String(call.sourceSpot.routingId), call.metadata), deadline.signal);
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ZLinkFrameworkException
+                && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound) {
+                PRE_ADMISSION_MISSING_INSTANCE_ERRORS.add(error);
+            }
+            throw error;
+        }
+        this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, selected.meshName, selected.target.stableType, selected.target.targetNodeRid);
+        const completion = await (0, abort_1.awaitWithAbort)(completionPromise, deadline.signal);
+        try {
+            if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+                const error = missingInstanceRequestFailure(completion.terminalResult, completion.failureErrno);
+                this.reportInstanceRequestError(spotId, request, error, selected.meshName, selected.target.targetNodeRid, selected.target.stableType, addressedInstanceErrorReason(error));
+                throw error;
+            }
+            const reply = (0, channel_envelope_1.decodeChannelReply)(completion.parts, this.options.codecs);
+            this.traceInstanceAddress(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.ReplyReceived, ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request, spotId, request, selected.meshName, selected.target.stableType, selected.target.targetNodeRid);
+            return reply;
+        }
+        finally {
+            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+        }
+    }
+    reportInstanceRequestError(spotId, request, error, meshName, targetRid, instanceSpotType, reason) {
+        this.options.dispatchErrors?.report({
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot,
+            messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request,
+            packetName: (0, packet_name_1.resolveFrameworkPacketName)(request, undefined, 'Channel'),
+            meshName,
+            targetRid,
+            spotId: String(spotId),
+            instanceSpotType,
+            reason,
+            action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.FailCaller,
+            error
+        });
+    }
+    traceInstanceAddress(outcome, messageKind, spotId, message, meshName, instanceSpotType, targetRid, errorReason) {
+        const flow = (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, outcome);
+        if (flow === undefined)
+            return;
+        flow.trace({
+            outcome,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.InstanceSpot,
+            messageKind,
+            packetName: (0, packet_name_1.resolveFrameworkPacketName)(message, undefined, 'Channel'),
+            meshName,
+            targetRid,
+            spotId: String(spotId),
+            instanceSpotType,
+            errorReason
+        });
+    }
+    async resolveExisting(spotId, signal) {
+        const resolver = this.options.resolver();
+        if (resolver === undefined) {
+            throw new Error('Global Spot address resolution requires a Location Store.');
+        }
+        try {
+            return await (0, abort_1.awaitWithAbort)(resolver.resolve(spotId, signal), signal);
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ZLinkFrameworkException
+                && (0, framework_errors_internal_1.internalFrameworkErrorKind)(error) === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound) {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    async recoverStaleInstanceRoute(spotId, call, deadline, error, staleRoute) {
+        if (!call.instanceSpot
+            || !(error instanceof contracts_1.ZLinkFrameworkException)
+            || !isInstanceRouteStaleError(error)) {
+            return { kind: 'fail' };
+        }
+        for (;;) {
+            deadline.requireRemaining();
+            const current = await this.resolveExisting(spotId, deadline.signal);
+            if (current === undefined)
+                return { kind: 'cold' };
+            if (!sameSpotRouteSnapshot(current, staleRoute)) {
+                return { kind: 'route', route: current };
+            }
+            await waitForSpotRouteRefresh(Math.min(10, deadline.requireRemaining()), deadline.signal);
+        }
+    }
+    selectMissingTarget(spotId, call) {
+        const configuredMeshes = this.options.meshNames();
+        if (call.initialMeshName !== undefined
+            && this.options.isMeshConfigured?.(call.initialMeshName) === false) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.MeshNotFound, `RouteMesh '${call.initialMeshName}' is not configured.`);
+        }
+        if (call.initialMeshName !== undefined && !configuredMeshes.includes(call.initialMeshName)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ObjectClientNotConfigured, `RouteMesh '${call.initialMeshName}' has no object-client role.`);
+        }
+        if (call.initialMeshName === undefined && configuredMeshes.length === 0) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ObjectClientNotConfigured, 'No object-client RouteMesh is configured.');
+        }
+        if (call.initialMeshName === undefined && configuredMeshes.length > 1) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.MeshSelectionRequired, 'Multiple object-client RouteMeshes are configured; call inMesh(...).');
+        }
+        const meshNames = call.initialMeshName === undefined
+            ? configuredMeshes
+            : [call.initialMeshName];
+        const distinctTypes = [...new Set(meshNames.flatMap(meshName => this.options.meshNode(meshName)?.instanceSpotPlacementTypes?.() ?? []))];
+        const canInspectPlacementTypes = meshNames.some(meshName => typeof this.options.meshNode(meshName)?.instanceSpotPlacementTypes === 'function');
+        const stableType = call.instanceSpotType
+            ?? (distinctTypes.length === 1 ? distinctTypes[0] : undefined);
+        if (stableType === undefined) {
+            if (distinctTypes.length === 0)
+                return { kind: 'unsupported' };
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, 'Instance Spot type is required when multiple types are registered.');
+        }
+        if (canInspectPlacementTypes && !distinctTypes.includes(stableType)) {
+            return { kind: 'unsupported' };
+        }
+        let unavailable = false;
+        let capacity = false;
+        let unsupported = false;
+        for (const meshName of meshNames) {
+            const node = this.options.meshNode(meshName);
+            const placement = node?.selectObjectPlacement(stableType);
+            if (node === undefined || placement === undefined) {
+                unavailable = true;
+                continue;
+            }
+            if (placement.kind === 'selected') {
+                return {
+                    kind: 'selected',
+                    meshName,
+                    node,
+                    target: {
+                        ...placement.target,
+                        targetSpotId: String(spotId),
+                        stableType
+                    }
+                };
+            }
+            if (placement.kind === 'unavailable')
+                unavailable = true;
+            if (placement.kind === 'capacity')
+                capacity = true;
+            if (placement.kind === 'unsupported')
+                unsupported = true;
+        }
+        if (unavailable)
+            return { kind: 'unavailable' };
+        if (capacity)
+            return { kind: 'capacity' };
+        if (unsupported)
+            return { kind: 'unsupported' };
+        return { kind: 'unavailable' };
+    }
+    sendTimeoutMsForMesh(meshName) {
+        return this.options.sendTimeoutMsForMesh?.(meshName)
+            ?? this.options.defaultSendTimeoutMs
+            ?? this.options.defaultRequestTimeoutMs;
+    }
+    sendTimeoutMsForRouteChannel(routeChannelId) {
+        return this.options.sendTimeoutMsForRouteChannel?.(routeChannelId)
+            ?? this.options.defaultSendTimeoutMs
+            ?? this.options.defaultRequestTimeoutMs;
+    }
+    validateExisting(target, call) {
+        if (!call.instanceSpot)
+            return;
+        if (target.spotKind !== contracts_2.ZLinkSpotKind.Instance
+            || (call.instanceSpotType !== undefined
+                && target.stableType !== call.instanceSpotType)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotTypeMismatch, `Spot '${String(target.spotId)}' is not the requested Instance Spot type.`);
+        }
+    }
+    encode(kind, meshName, payload, timeoutMs) {
+        return (0, channel_envelope_1.encodeChannelEnvelopeParts)(kind, meshName, undefined, payload, timeoutMs, undefined, this.options.codecs, undefined, true, new Map());
+    }
+    encodeAtDeadline(kind, meshName, payload, deadlineUnixMs) {
+        return (0, channel_envelope_1.encodeChannelEnvelopePartsAtDeadline)(kind, meshName, undefined, payload, deadlineUnixMs, undefined, this.options.codecs, undefined, true, new Map());
+    }
+}
+exports.ZLinkHostSpotAddressTransport = ZLinkHostSpotAddressTransport;
+function isInstanceRouteStaleError(error) {
+    if (!(error instanceof contracts_1.ZLinkFrameworkException))
+        return false;
+    const kind = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
+    // RequestTargetNotFound from an existing route is a pre-admission route
+    // lookup failure. A stale owner result is terminal for this application
+    // operation: the routed request may already have crossed the transport
+    // boundary, so refreshing the route and resubmitting it could execute the
+    // same operation twice. Instance cold activation is selected only when the
+    // authority resolver itself reports that the Ready route is absent.
+    if (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound)
+        return true;
+    return false;
+}
+function isMissingInstanceRetryError(error) {
+    return error instanceof contracts_1.ZLinkFrameworkException
+        && PRE_ADMISSION_MISSING_INSTANCE_ERRORS.has(error);
+}
+function missingInstanceRequestFailure(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.Backpressured
+                        //  Spec 32-framework-error-model:104-108 — the bounded admission
+                        //  terminal is target placement capacity: CapacityExceeded.
+                        ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted
+                        : result === runtime_values_1.RequestResult.NotConnected
+                            ? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected
+                            : wireKind ?? framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed;
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(kind, `Instance Spot request failed with result ${result} and errno ${nativeErrno}.`);
+}
+function mapSubmitResult(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, `Instance Spot submission failed with result ${result}.`);
+    }
+}
+function missingInstancePlacementCapacity(spotId, stableType) {
+    const type = stableType === undefined ? '' : ` of type '${stableType}'`;
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `No eligible Instance Spot placement target${type} is available for '${String(spotId)}'.`, true);
+}
+function missingInstancePlacementUnavailable(spotId, stableType) {
+    const type = stableType === undefined ? '' : ` of type '${stableType}'`;
+    return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `No connected Instance Spot placement target${type} is available for '${String(spotId)}'.`, true);
+}
+function isSpotRouteRefreshError(error) {
+    if (!(error instanceof contracts_1.ZLinkFrameworkException))
+        return false;
+    const kind = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
+    return kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale
+        || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected;
+}
+function sameSpotRouteSnapshot(left, right) {
+    return String(left.targetNodeRid) === String(right.targetNodeRid)
+        && String(left.spotId) === String(right.spotId)
+        && left.routerChannelId === right.routerChannelId
+        && left.spotKind === right.spotKind
+        && left.stableType === right.stableType
+        && left.targetSpotGeneration === right.targetSpotGeneration
+        && left.targetNodeGeneration === right.targetNodeGeneration
+        && left.authorityOwnerGeneration === right.authorityOwnerGeneration
+        && left.targetOwnerId === right.targetOwnerId
+        && left.ownerLeaseGeneration === right.ownerLeaseGeneration
+        && left.authorityStoreVersion === right.authorityStoreVersion;
+}
+function waitForSpotRouteRefresh(delayMs, signal) {
+    return new Promise((resolve, reject) => {
+        const finish = () => {
+            signal.removeEventListener('abort', abort);
+            resolve();
+        };
+        const abort = () => {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(finish, delayMs);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted)
+            abort();
+    });
+}
+function submitResultReason(status) {
+    switch (status) {
+        case submission_result_1.ZLinkSubmitStatus.Backpressured:
+        case submission_result_1.ZLinkSubmitStatus.TimedOut:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure;
+        case submission_result_1.ZLinkSubmitStatus.Shutdown:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Shutdown;
+        case submission_result_1.ZLinkSubmitStatus.TargetNotFound:
+        case submission_result_1.ZLinkSubmitStatus.RouteNotConnected:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget;
+        case submission_result_1.ZLinkSubmitStatus.Submitted:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+    }
+}
+function submitResultFlowOutcome(status) {
+    switch (status) {
+        case submission_result_1.ZLinkSubmitStatus.Submitted:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent;
+        case submission_result_1.ZLinkSubmitStatus.Backpressured:
+        case submission_result_1.ZLinkSubmitStatus.TimedOut:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Backpressured;
+        case submission_result_1.ZLinkSubmitStatus.Shutdown:
+        case submission_result_1.ZLinkSubmitStatus.TargetNotFound:
+        case submission_result_1.ZLinkSubmitStatus.RouteNotConnected:
+            return ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped;
+    }
+}
+function addressedInstanceErrorReason(error) {
+    if (error instanceof contracts_1.ZLinkFrameworkException) {
+        const kind = (0, framework_errors_internal_1.internalFrameworkErrorKind)(error);
+        if (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotRouteNotFound
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotGenerationStale
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.SpotMoving
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestTargetNotFound
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected) {
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.StaleTarget;
+        }
+        if (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RuntimeShutdown) {
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Shutdown;
+        }
+        if (kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerQueueFull
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.WorkerTimedOut
+            || kind === framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded) {
+            return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Backpressure;
+        }
+    }
+    return ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException;
+}
+function initialSendTimeoutMs(options, call) {
+    return call.initialMeshName === undefined
+        ? options.defaultSendTimeoutMs ?? options.defaultRequestTimeoutMs
+        : options.sendTimeoutMsForMesh?.(call.initialMeshName)
+            ?? options.defaultSendTimeoutMs
+            ?? options.defaultRequestTimeoutMs;
+}
+function createSpotAddressDeadline(timeoutMs, parent) {
+    const startedAtMs = performance.now();
+    const startedAtUnixMs = Date.now();
+    let deadlineMs = startedAtMs + Math.max(0, timeoutMs);
+    const controller = new AbortController();
+    let expired = false;
+    let timeout;
+    const expire = () => {
+        expired = true;
+        controller.abort();
+    };
+    const arm = () => {
+        if (timeout !== undefined)
+            clearTimeout(timeout);
+        const remainingMs = deadlineMs - performance.now();
+        if (remainingMs <= 0) {
+            expire();
+            return;
+        }
+        timeout = setTimeout(expire, remainingMs);
+    };
+    arm();
+    const abort = () => controller.abort(parent?.reason);
+    if (parent?.aborted === true)
+        abort();
+    else
+        parent?.addEventListener('abort', abort, { once: true });
+    return {
+        get deadlineUnixMs() {
+            return Math.round(startedAtUnixMs + (deadlineMs - startedAtMs));
+        },
+        signal: controller.signal,
+        setOwnerTimeout(ownerTimeoutMs) {
+            deadlineMs = startedAtMs + Math.max(0, ownerTimeoutMs);
+            arm();
+        },
+        requireRemaining() {
+            const remainingMs = deadlineMs - performance.now();
+            if (remainingMs <= 0) {
+                expired = true;
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, 'Spot address operation exceeded its end-to-end deadline.', true);
+            }
+            return Math.max(1, Math.ceil(remainingMs));
+        },
+        expired: () => expired,
+        close() {
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            parent?.removeEventListener('abort', abort);
+        }
+    };
+}