@zlink-systems/framework 0.26.0 → 0.27.0

package/dist/runtime/spots/spot-node-runtime-manager.d.ts

@@ -1,28 +1,27 @@
-import type { ZLinkListenerRecords } from '../foundation/listener-records';
-import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
-import type { ActorRef, RoutingId, ZLinkActor, ZLinkChannelClient, ZLinkFanoutClient, ZLinkMessage, ZLinkMeshNodeDescriptor, ZLinkMessageSerializer, ZLinkSpotPublisherClient } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
-import { ZLinkFrameworkRuntimeState } from '../../contracts';
-import { type ZLinkSubmitResult } from '../messaging/submission-result';
-import { type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import { type ActorRef, type RoutingId, type ZLinkActor, type ZLinkChannelClient, type ZLinkFanoutClient, type ZLinkMeshNodeDescriptor, type ZLinkMessage, type ZLinkMessageSerializer, type ZLinkSpotPublisherClient, ZLinkFrameworkRuntimeState } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import { type ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ZLinkActivationConcurrency } from '../activation-admission';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import type { ZLinkBackendAdapterFactory, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
 import { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
 import type { ZLinkDispatchErrorReporter } from '../channels';
+import { type ZLinkFrameworkRegistration } from '../configuration';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
+import { type ZLinkMessageFollowOrigin, type ReadyRecord, type ReceiveRecord } from '../foundation/service-runtime-contracts';
+import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
+import { ApplicationJobQueue } from '../host/application-job-queue';
 import { ZLinkLocationRuntime, type ZLinkLocationEventSink, type ZLinkLocationRuntimeStores } from '../locations';
-import type { ZLinkRemoteBoundSessionTarget } from '../actors';
-import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
 import type { ZLinkSpotRoutedTransport } from './spot-outbound';
 import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
-import type { ZLinkEntryActorRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotActorHandoffRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
-import type { ZLinkActivationConcurrency } from '../activation-admission';
-import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
-import { ApplicationJobQueue } from '../host/application-job-queue';
+import type { ZLinkEntryActorRuntime, ZLinkSpotActorHandoffRuntime, ZLinkSpotActorTransferRuntime, ZLinkSpotBoundSessionRuntime } from './spot-runtime-ports';
 export interface ZLinkSpotNodeRuntimeManagerOptions {
+    readonly errorSink: import('../diagnostics/dispatch-error-port').ZLinkDispatchErrorSink;
     readonly listenerRecords?: ZLinkListenerRecords;
     readonly registration: ZLinkFrameworkRegistration;
     readonly primaryMeshName?: string;
@@ -43,7 +42,7 @@ export interface ZLinkSpotNodeRuntimeManagerOptions {
     readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
     readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
     readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+    readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
     readonly applicationJobQueue?: ApplicationJobQueue;
     readonly applicationJobReceiveFlowFailureSink?: (error: unknown) => void;
     readonly peerAdmissionSealed?: (meshName: string) => boolean;
@@ -60,7 +59,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     private readonly entryActivations;
     private readonly entryActivationStarts;
     private readonly publishers;
-    private disposed;
+    private readonly disposal;
     private readonly autoConnectLoops;
     private readonly publishedMeshNodeDescriptors;
     private readonly descriptorRevisionByMesh;
@@ -110,6 +109,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     notifyEntrySpotActorDisconnected(meshName: string, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     serverChannels(meshName: string): [string, import("../configuration").ZLinkMeshChannelOptions][];
     dispose(signal?: AbortSignal, deadline?: Date): Promise<void>;
+    private disposeCore;
     private dispatchMeshRecord;
     dispatchEntrySpotRecord(meshName: string, owner: ReadyRecord, record: ReceiveRecord): Promise<boolean>;
     private ensureEntryActivation;
@@ -117,6 +117,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     private primaryEntryActivation;
     dispatchEntryActorPacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     dispatchEntryActorJoin(meshName: string, actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[]): Promise<void>;
+    executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T>;
     publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;
     private executePublish;
     tryPublish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, metadata?: ReadonlyMap<string, string>): ZLinkSubmitResult;

package/dist/runtime/spots/spot-node-runtime-manager.js

@@ -2,26 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotNodeRuntimeManager = void 0;
 exports.createFrameworkEntrySpotId = createFrameworkEntrySpotId;
-const framework_errors_internal_1 = require("../framework-errors-internal");
+const disposal_1 = require("../disposal");
 const node_crypto_1 = require("node:crypto");
-const Locations_1 = require("../../contracts/Locations");
 const contracts_1 = require("../../contracts");
-const submission_result_1 = require("../messaging/submission-result");
+const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
+const RegistrationBuilderPolicy_1 = require("../../contracts/Configuration/RegistrationBuilderPolicy");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const Locations_1 = require("../../contracts/Locations");
+const abort_1 = require("../abort");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const mesh_dispatch_pump_1 = require("../backend/mesh-dispatch-pump");
 const runtime_values_1 = require("../backend/runtime-values");
-const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const channel_clients_1 = require("../channels/channel-clients");
+const channel_envelope_1 = require("../channels/channel-envelope");
 const configuration_1 = require("../configuration");
-const mesh_dispatch_pump_1 = require("../backend/mesh-dispatch-pump");
-const execution_1 = require("../execution");
 const flow_context_1 = require("../diagnostics/flow-context");
-const mesh_completion_table_1 = require("../backend/mesh-completion-table");
-const channel_envelope_1 = require("../channels/channel-envelope");
+const execution_1 = require("../execution");
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const application_job_queue_1 = require("../host/application-job-queue");
 const locations_1 = require("../locations");
+const submission_result_1 = require("../messaging/submission-result");
+const routing_id_1 = require("../routing-id");
 const spot_entry_activation_1 = require("./spot-entry-activation");
 const spot_node_autoconnect_1 = require("./spot-node-autoconnect");
-const routing_id_1 = require("../routing-id");
-const abort_1 = require("../abort");
-const application_job_queue_1 = require("../host/application-job-queue");
+const DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS = 1000;
 const ZLINK_SEND_DONT_WAIT = 1;
 //  Shared default for the dominant no-metadata call; avoids a Map allocation
 //  per outbound operation.
@@ -34,7 +39,7 @@ class ZLinkSpotNodeRuntimeManager {
     entryActivations = new Map();
     entryActivationStarts = new Map();
     publishers = new Map();
-    disposed = false;
+    disposal = new disposal_1.RuntimeDisposal();
     autoConnectLoops = [];
     publishedMeshNodeDescriptors = new Map();
     // Keep the revision source separate from the cached Store row. A new owner
@@ -51,6 +56,9 @@ class ZLinkSpotNodeRuntimeManager {
     applicationJobQueue;
     constructor(options) {
         this.options = options;
+        if (options.detachedTaskRunner === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Spot node runtime requires a detached task runner.');
+        }
         this.applicationJobQueue =
             options.applicationJobQueue ??
                 new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)());
@@ -82,7 +90,8 @@ class ZLinkSpotNodeRuntimeManager {
                     peerResolver: location.resolver,
                     executor: capability.executor,
                     events: location.events,
-                    options: location.options
+                    options: location.options,
+                    errorSink: this.options.errorSink
                 });
                 const loop = new locations_1.ZLinkAutoConnectLoop({
                     reconciler,
@@ -185,9 +194,9 @@ class ZLinkSpotNodeRuntimeManager {
                         : Object.keys(spotNode.actorFactories ?? {}).length) > 0;
                 node.configureObjectPlacement({
                     role: spotNode.objectRole ?? (hasLegacyObjectFactories ? 'server' : 'none'),
-                    placementWeight: spotNode.placementWeight ?? 100,
+                    placementWeight: spotNode.placementWeight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT,
                     activeCapacityLimit: aggregatePlacementCapacity(spotNode.actorLimit ?? 0, spotNode.spotLimit ?? 0),
-                    pendingCapacityLimit: spotNode.activationConcurrencyLimit ?? 128,
+                    pendingCapacityLimit: spotNode.activationConcurrencyLimit ?? InternalDefaults_1.DEFAULT_ACTIVATION_CONCURRENCY_LIMIT,
                     objectCapabilities: [
                         ...stableTypes.map((type) => `object-type:${type}`),
                         ...instanceSpotTypes.map((type) => `instance-spot-type:${type}`)
@@ -336,13 +345,13 @@ class ZLinkSpotNodeRuntimeManager {
                 },
                 activationConcurrency: this.options.activationConcurrency?.(meshName) ?? {
                     active: 0,
-                    limit: registration.activationConcurrencyLimit ?? 128
+                    limit: registration.activationConcurrencyLimit ?? InternalDefaults_1.DEFAULT_ACTIVATION_CONCURRENCY_LIMIT
                 },
                 channelWeights: Object.fromEntries(this.serverChannels(meshName).map(([channelName, channel]) => [
                     channelName,
                     state === contracts_1.ZLinkFrameworkRuntimeState.Draining
                         ? 0
-                        : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? 100)
+                        : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT)
                 ])),
                 applicationVersion: this.options.registration.applicationVersion,
                 maintenanceWave: this.options.registration.maintenanceWave,
@@ -433,7 +442,9 @@ class ZLinkSpotNodeRuntimeManager {
         if (registration === undefined) {
             throw new configuration_1.ZLinkConfigurationException(`Mesh '${meshName}' is not registered.`);
         }
-        return this.runtimePlacementWeights.get(meshName) ?? registration.placementWeight ?? 100;
+        return (this.runtimePlacementWeights.get(meshName) ??
+            registration.placementWeight ??
+            RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT);
     }
     channelWeight(channelName) {
         const match = this.resolveChannel(channelName);
@@ -486,17 +497,15 @@ class ZLinkSpotNodeRuntimeManager {
         return this.runtimeChannelWeights.get(meshName)?.get(channelName) ?? configuredWeight;
     }
     resolveChannel(channelName) {
-        const matches = [...this.options.registration.spotNodes].flatMap(([meshName, registration]) => {
-            const channel = registration.meshChannels?.[channelName];
-            return channel === undefined ? [] : [{ meshName, configuredWeight: channel.weight ?? 100 }];
-        });
-        if (matches.length === 0) {
+        const route = (0, channel_clients_1.resolveChannelRoute)(this.options.registration, channelName);
+        if (route?.kind !== 'route-mesh') {
             throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' is not registered.`);
         }
-        if (matches.length > 1) {
-            throw new configuration_1.ZLinkConfigurationException(`RouteMesh channel '${channelName}' is registered in more than one Mesh.`);
-        }
-        return matches[0];
+        const match = (0, channel_clients_1.requireUniqueRouteMeshChannel)(route.matches, `RouteMesh channel '${channelName}' is registered in more than one Mesh.`);
+        return {
+            meshName: match.meshName,
+            configuredWeight: match.mesh.meshChannels?.[channelName]?.weight ?? RegistrationBuilderPolicy_1.ZLINK_DEFAULT_PUBLIC_WEIGHT
+        };
     }
     scheduleRuntimeWeightPublication(meshName, applyWeight) {
         const publish = this.runtimeWeightPublication
@@ -508,12 +517,7 @@ class ZLinkSpotNodeRuntimeManager {
             await this.publishMeshNodeState(state, undefined, meshName);
         });
         this.runtimeWeightPublication = publish;
-        if (this.options.detachedTaskRunner !== undefined) {
-            this.options.detachedTaskRunner.runDetached(`RouteMesh '${meshName}' runtime weight publication`, async () => await publish);
-        }
-        else {
-            void publish.catch(() => undefined);
-        }
+        this.options.detachedTaskRunner.runDetached(`RouteMesh '${meshName}' runtime weight publication`, async () => await publish);
     }
     get primaryMeshCompletions() {
         const meshName = this.options.primaryMeshName ?? this.meshNodes.keys().next().value;
@@ -553,18 +557,16 @@ class ZLinkSpotNodeRuntimeManager {
     serverChannels(meshName) {
         return Object.entries(this.options.registration.spotNodes.get(meshName)?.meshChannels ?? {}).filter(([, channel]) => channel.server === true);
     }
-    async dispose(signal, deadline) {
-        this.disposed = true;
+    dispose(signal, deadline) {
+        return this.disposal.run(() => this.disposeCore(signal, deadline));
+    }
+    async disposeCore(signal, deadline) {
         const autoConnectLoops = [...this.autoConnectLoops];
         const entryActivations = [...this.entryActivations.values()];
         const meshPumps = [...this.meshPumps.values()];
         const meshNodes = [...this.meshNodes.values()];
         const meshCompletions = [...this.meshCompletions.values()];
-        this.entryActivations.clear();
-        this.autoConnectLoops.length = 0;
-        this.meshPumps.clear();
         const publishers = [...this.publishers.values()];
-        this.publishers.clear();
         const errors = [];
         const settle = async (operations) => {
             const results = await Promise.allSettled(operations);
@@ -577,19 +579,23 @@ class ZLinkSpotNodeRuntimeManager {
         await settle(entryActivations.reverse().map((activation) => activation.dispose(deadline)));
         await settle(meshPumps.reverse().map((pump) => pump.dispose()));
         await settle(meshNodes.reverse().map(async (node) => {
-            node.shutdown(1000);
+            node.shutdown(DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS);
             node.close();
         }));
         for (const completions of meshCompletions) {
             completions.dispose();
         }
-        this.meshNodes.clear();
-        this.meshCompletions.clear();
         await settle(autoConnectLoops.map((loop) => loop.finishTransportShutdown(signal)));
         if (errors.length === 1)
             throw errors[0];
         if (errors.length > 1)
             throw new AggregateError(errors, 'SPOT node runtime cleanup failed.');
+        this.entryActivations.clear();
+        this.autoConnectLoops.length = 0;
+        this.meshPumps.clear();
+        this.publishers.clear();
+        this.meshNodes.clear();
+        this.meshCompletions.clear();
     }
     async dispatchMeshRecord(meshName, owner, record) {
         if (record.kind === service_runtime_contracts_1.ReceiveKind.Completion) {
@@ -699,7 +705,6 @@ class ZLinkSpotNodeRuntimeManager {
             spotPublisherClient: this.options.spotPublisherClient,
             routedTransport: this.options.routedTransport,
             spotRouterChannelIdForMesh: this.options.spotRouterChannelIdForMesh,
-            channelMeshNameForChannel: (channelName) => resolveChannelMeshName(this.options.registration, channelName),
             timerHandlers: spotNode.entrySpotTimerHandlers,
             packetHandlers: spotNode.entrySpotPacketHandlers,
             subscriptionHandlers: spotNode.entrySpotSubscriptionHandlers,
@@ -780,8 +785,15 @@ class ZLinkSpotNodeRuntimeManager {
         }
         await activation.commitServiceActorJoin(actor, handoffBacklog);
     }
+    executeEntryActor(meshName, actorId, operation) {
+        const activation = this.entryActivations.get(meshName);
+        if (activation === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Entry Spot Actor '${actorId}' has no activation for MeshNode '${meshName}'.`);
+        }
+        return activation.executeActor(actorId, operation);
+    }
     publish(meshName, channelName, topic, packetName, event, signal, metadata = EMPTY_SPOT_METADATA) {
-        if (this.disposed) {
+        if (this.disposal.started) {
             return Promise.reject(runtimeShutdownError());
         }
         if (signal?.aborted === true) {
@@ -803,7 +815,7 @@ class ZLinkSpotNodeRuntimeManager {
         return this.publishWithFlags(meshName, channelName, topic, packetName, event, ZLINK_SEND_DONT_WAIT, metadata);
     }
     publishWithFlags(meshName, channelName, topic, packetName, event, flags, metadata) {
-        if (this.disposed) {
+        if (this.disposal.started) {
             throw runtimeShutdownError();
         }
         const publisher = this.publishers.get(meshName);
@@ -834,31 +846,14 @@ function createFrameworkEntrySpotId(prefix) {
     }
     return `${prefix}-entry-${(0, node_crypto_1.randomUUID)()}`;
 }
-function resolveChannelMeshName(registration, channelName) {
-    const matches = [...registration.spotNodes.entries()]
-        .filter(([, node]) => Object.prototype.hasOwnProperty.call(node.meshChannels ?? {}, channelName))
-        .map(([meshName]) => meshName);
-    return matches.length === 1 ? matches[0] : undefined;
-}
 function mapPublishSubmitStatus(result) {
-    switch (result) {
-        case runtime_values_1.SubmitResult.Ok:
-            return submission_result_1.ZLinkSubmitStatus.Submitted;
-        case runtime_values_1.SubmitResult.Backpressured:
-        case runtime_values_1.SubmitResult.NotAdmitted:
-            return submission_result_1.ZLinkSubmitStatus.Backpressured;
-        case runtime_values_1.SubmitResult.NotFound:
-            // A publish with no matching subscriber is a successful zero-recipient
-            // operation, not an operation-specific not-found failure.
-            return submission_result_1.ZLinkSubmitStatus.Submitted;
-        case runtime_values_1.SubmitResult.NotConnected:
-            return submission_result_1.ZLinkSubmitStatus.RouteNotConnected;
-        case runtime_values_1.SubmitResult.Terminated:
-        case runtime_values_1.SubmitResult.InvalidHandle:
-            return submission_result_1.ZLinkSubmitStatus.Shutdown;
-        default:
-            throw new configuration_1.ZLinkConfigurationException(`Logical Multicast failed with submit result '${result}'.`);
-    }
+    // Source publication preserves its local admission status before commit.
+    if (result === runtime_values_1.SubmitResult.NotAdmitted || result === runtime_values_1.SubmitResult.Backpressured)
+        return submission_result_1.ZLinkSubmitStatus.Backpressured;
+    // A publish with no matching subscriber succeeds with zero recipients.
+    if (result === runtime_values_1.SubmitResult.NotFound)
+        return submission_result_1.ZLinkSubmitStatus.Submitted;
+    return (0, submission_result_1.classifySubmitResult)(result, 'Logical Multicast').status;
 }
 function requireEntrySpotReply(result) {
     if (result !== runtime_values_1.SubmitResult.Ok) {
@@ -866,8 +861,8 @@ function requireEntrySpotReply(result) {
     }
 }
 function requirePublicRuntimeWeight(value, label) {
-    if (!Number.isInteger(value) || value < 0 || value > 10_000) {
-        throw new configuration_1.ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+    if (!(0, RegistrationBuilderPolicy_1.isValidPublicWeight)(value)) {
+        throw new configuration_1.ZLinkConfigurationException(`${label} must be an integer in 0..${RegistrationBuilderPolicy_1.ZLINK_MAX_PUBLIC_WEIGHT}.`);
     }
     return value;
 }
@@ -927,7 +922,7 @@ function objectCapability(objectKind, stableType, factory) {
     };
 }
 function aggregatePlacementCapacity(actorLimit, spotLimit) {
-    const unlimited = 0x7fff_ffff;
+    const unlimited = RegistrationBuilderPolicy_1.ZLINK_MAX_CAPACITY;
     const actors = actorLimit === 0 ? unlimited : actorLimit;
     const spots = spotLimit === 0 ? unlimited : spotLimit;
     return Math.min(unlimited, actors + spots);

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

@@ -1,9 +1,9 @@
-import type { RoutingId, ZLinkChannelClient, ZLinkChannelRequestCall, ZLinkPublishCall, ZLinkSendCall, ZLinkSpotOutbound, ZLinkSpotRequestCall, ZLinkSpotSendCall, ZLinkSpotPublisherClient } from '../../contracts';
-import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import { type RoutingId, type ZLinkChannelClient, type ZLinkChannelRequestCall, type ZLinkPublishCall, type ZLinkSendCall, type ZLinkSpotOutbound, type ZLinkSpotPublisherClient, type ZLinkSpotRequestCall, type ZLinkSpotSendCall } from '../../contracts';
 import type { ZLinkBackendSpot } from '../backend/contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import { type SpotHandle } from './spot-handle';
 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;
@@ -58,6 +58,7 @@ export interface ZLinkSpotRoutedTransport {
     requestFromSpotToSpot?<TReply = unknown>(sourceSpot: ZLinkBackendSpot, spotRouteTarget: ZLinkSpotRouteTarget, request: unknown, options: ZLinkSpotRoutedRequestOptions): Promise<TReply>;
 }
 export interface ZLinkSpotRoutedSendOptions {
+    readonly instanceSpot?: boolean;
     readonly packetName?: string;
     /** Internal end-to-end budget remaining for route admission. */
     readonly timeoutMs?: number;

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

@@ -3,14 +3,15 @@ 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 submission_result_1 = require("../messaging/submission-result");
-const routing_id_1 = require("../routing-id");
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const configuration_1 = require("../configuration");
-const workers_1 = require("../workers");
 const execution_1 = require("../execution");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const packet_name_1 = require("../messaging/packet-name");
+const submission_result_1 = require("../messaging/submission-result");
+const routing_id_1 = require("../routing-id");
+const workers_1 = require("../workers");
 const spot_handle_1 = require("./spot-handle");
 class DefaultZLinkSpotOutbound {
     serial;
@@ -93,13 +94,13 @@ function createAddressedSpotSendCall(serial, transport, spotId, message, sourceS
             selectOnce(options, 'instanceSpot');
             options.instanceSpot = true;
             if (instanceSpotType !== undefined) {
-                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', CoreTypes_1.ZLINK_MAX_STABLE_TYPE_BYTES);
             }
             return this;
         },
         inMesh(meshName) {
             selectOnce(options, 'inMesh');
-            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', CoreTypes_1.ZLINK_MAX_MESH_NAME_BYTES);
             return this;
         },
         async submit(signal) {
@@ -130,13 +131,13 @@ function createAddressedSpotRequestCall(serial, transport, spotId, request, sour
             selectOnce(options, 'instanceSpot');
             options.instanceSpot = true;
             if (instanceSpotType !== undefined) {
-                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+                options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', CoreTypes_1.ZLINK_MAX_STABLE_TYPE_BYTES);
             }
             return this;
         },
         inMesh(meshName) {
             selectOnce(options, 'inMesh');
-            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+            options.initialMeshName = requireAddressValue(meshName, 'Mesh name', CoreTypes_1.ZLINK_MAX_MESH_NAME_BYTES);
             return this;
         },
         timeout(timeoutMs) {

package/dist/runtime/spots/spot-remote-codec.js

@@ -7,6 +7,8 @@ exports.decodeRemoteActorJoinPayload = decodeRemoteActorJoinPayload;
 exports.decodeHandoffBacklog = decodeHandoffBacklog;
 exports.decodeRemoteActorRef = decodeRemoteActorRef;
 exports.decodeRemoteBoundSessionTarget = decodeRemoteBoundSessionTarget;
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const actors_1 = require("../actors");
 const runtime_message_1 = require("../backend/runtime-message");
 const routing_id_1 = require("../routing-id");
@@ -58,7 +60,7 @@ function decodeRemoteActorJoinPayload(payload, request, received, raw, envelope)
         request,
         requestContentType: typeof payload.requestContentType === 'string'
             ? payload.requestContentType
-            : 'application/json'
+            : stream_wire_1.ZlinkStreamContentType.Json
     };
 }
 function decodeHandoffBacklog(value) {
@@ -179,8 +181,8 @@ function decodeBoundSessionServiceWireRelocation(value) {
 }
 function requireSpotId(value) {
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 255) {
-        throw new Error('Remote bound session SpotId must contain 1..255 UTF-8 bytes.');
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES) {
+        throw new Error(`Remote bound session SpotId must contain 1..${CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
     }
     return value;
 }

package/dist/runtime/spots/spot-route-packet-dispatch.d.ts

@@ -1,10 +1,10 @@
-import type { ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
+import { type ZLinkMessageSerializer, type ZLinkSpot } from '../../contracts';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkApplicationWorkClaim } from '../admission';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkApplicationWorkClaim } from '../admission';
 interface ZLinkSpotRoutePacketDispatchOptions {
     readonly packetHandlers: ReadonlyMap<string, readonly ZLinkSpotHandlerRegistration[]>;
     readonly nativeSpotId: string;

package/dist/runtime/spots/spot-route-packet-dispatch.js

@@ -3,17 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotRoutePacketDispatch = void 0;
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const actors_1 = require("../actors");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const runtime_message_1 = require("../backend/runtime-message");
 const channel_envelope_1 = require("../channels/channel-envelope");
-const actors_1 = require("../actors");
-const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const spot_direct_envelope_1 = require("../channels/spot-direct-envelope");
+const flow_context_1 = require("../diagnostics/flow-context");
 const serial_work_size_1 = require("../execution/serial-work-size");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
 const spot_remote_codec_1 = require("./spot-remote-codec");
 const spot_route_replies_1 = require("./spot-route-replies");
-const flow_context_1 = require("../diagnostics/flow-context");
-const framework_errors_internal_1 = require("../framework-errors-internal");
-const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
 /** D5: reply metadata attached only to framework-self-generated errors. */
 const FRAMEWORK_ORIGIN_REPLY_METADATA = Object.freeze({
     [channel_envelope_1.ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY]: channel_envelope_1.ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE
@@ -206,7 +206,7 @@ function decodeSpotDirectEnvelope(parts) {
     }
     try {
         const decoded = JSON.parse(parts[0].data().toString());
-        if (decoded.marker !== SPOT_DIRECT_ENVELOPE ||
+        if (decoded.marker !== spot_direct_envelope_1.SPOT_DIRECT_ENVELOPE ||
             (decoded.kind !== 1 /* ZLinkChannelMessageKind.Request */ &&
                 decoded.kind !== 3 /* ZLinkChannelMessageKind.Command */) ||
             typeof decoded.channelName !== 'string') {
@@ -232,7 +232,7 @@ function decodeSpotDirectEnvelope(parts) {
 }
 function encodeSpotDirectReply(ok, response, error) {
     return runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(JSON.stringify({
-        marker: SPOT_DIRECT_ENVELOPE,
+        marker: spot_direct_envelope_1.SPOT_DIRECT_ENVELOPE,
         ok,
         response,
         error

package/dist/runtime/spots/spot-route-replies.d.ts

@@ -1,7 +1,7 @@
-import type { ZLinkBackendMessageLike as MessageLike, ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
+import type { ZLinkBackendReceived as BackendReceived, ZLinkBackendMessageLike as MessageLike } from '../backend/runtime-values';
 import { decodeChannelEnvelope } from '../channels/channel-envelope';
-import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 import type { ZLinkDecodedRemoteActorJoinRequest } from './spot-remote-codec';
+import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 export interface ZLinkRouteReplySubmitOperation {
     message(message: MessageLike): ZLinkRouteReplySubmitOperation;
     submit(): void;

package/dist/runtime/spots/spot-route-replies.js

@@ -7,9 +7,11 @@ exports.submitRoutedActorJoinReply = submitRoutedActorJoinReply;
 exports.submitRoutedActorJoinError = submitRoutedActorJoinError;
 exports.appendRouteReplyParts = appendRouteReplyParts;
 exports.hasReplyToken = hasReplyToken;
+const node_os_1 = require("node:os");
 const channel_envelope_1 = require("../channels/channel-envelope");
 const configuration_1 = require("../configuration");
 const spot_route_reply_wire_1 = require("./spot-route-reply-wire");
+const nativeErrnoValues = node_os_1.constants.errno;
 function submitRouteReply(operation) {
     try {
         operation.submit();
@@ -70,5 +72,5 @@ function requireRoutedActorJoinEnvelope(decoded) {
 function isNativeBadAddress(error) {
     return (typeof error === 'object' &&
         error !== null &&
-        Number(error.nativeErrno) === 14);
+        Number(error.nativeErrno) === nativeErrnoValues.EFAULT);
 }

package/dist/runtime/spots/spot-routed-actor-admission.d.ts

@@ -1,18 +1,18 @@
 import type { ZLinkActor, ZLinkMessage, ZLinkMessageSerializer, ZLinkSpotActorJoinResult } from '../../contracts';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import { type ZLinkRoutedActorTransferProvider } from './spot-remote-codec';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
 interface ZLinkRoutedActorAdmissionTarget {
     onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
 }
 interface ZLinkSpotRoutedActorAdmissionOptions {
     readonly serial: ZLinkSpotSerialTurnExecutor;
-    readonly isSpotClosing?: () => boolean;
     readonly getTarget: () => ZLinkRoutedActorAdmissionTarget;
     readonly defaultAccept: boolean;
     readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
-    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[]) => Promise<readonly ZLinkActorHandoffResult[]>;
+    readonly commitTransferredActor?: (actor: ZLinkActor, backlog: readonly ZLinkActorHandoffPacket[], sealedSession: ZLinkRemoteBoundSessionTarget | undefined) => Promise<readonly ZLinkActorHandoffResult[]>;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
     readonly pendingAdmissionTimeoutMs?: number;
     /** Spec 27 §4: with tracing Off, inbound flow fields are neither validated nor carried forward. */

package/dist/runtime/spots/spot-routed-actor-admission.js

@@ -7,7 +7,7 @@ const payload_codec_1 = require("../messaging/payload-codec");
 const routing_id_1 = require("../routing-id");
 const spot_remote_codec_1 = require("./spot-remote-codec");
 const spot_route_replies_1 = require("./spot-route-replies");
-const framework_errors_internal_1 = require("../framework-errors-internal");
+const DEFAULT_PENDING_ADMISSION_TIMEOUT_MS = 30_000;
 class ZLinkSpotRoutedActorAdmission {
     options;
     pending = new Map();
@@ -22,15 +22,6 @@ class ZLinkSpotRoutedActorAdmission {
         if (decoded === undefined) {
             return false;
         }
-        if (this.options.isSpotClosing?.() === true) {
-            try {
-                (0, spot_route_replies_1.submitRoutedActorJoinError)(received, decoded, (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestRejected, `Actor '${decoded.actorId}' target Spot is closing.`));
-            }
-            finally {
-                this.closeDecoded(decoded);
-            }
-            return true;
-        }
         if (decoded.phase === 'admission') {
             await this.admitTransfer(decoded, received);
             return true;
@@ -149,7 +140,7 @@ class ZLinkSpotRoutedActorAdmission {
                 throw new Error('Remote actor transfer commit cannot materialize the target actor.');
             }
             const { actor, actorRef } = await this.options.routedActorTransferProvider(decoded.actorId, decoded.actorType, decoded.transferAdapterKey, decoded.transferState, decoded.actorEntryNodeRid, decoded.remoteBoundSessionTarget);
-            const handoffResults = (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog)) ?? [];
+            const handoffResults = (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog, decoded.remoteBoundSessionTarget)) ?? [];
             const commitReply = {
                 accepted: true,
                 actorNodeRid: String(actorRef.nodeRid),
@@ -193,7 +184,7 @@ class ZLinkSpotRoutedActorAdmission {
         pending.deadline = setTimeout(() => {
             if (this.pending.get(transferId) === pending)
                 this.pending.delete(transferId);
-        }, this.options.pendingAdmissionTimeoutMs ?? 30_000);
+        }, this.options.pendingAdmissionTimeoutMs ?? DEFAULT_PENDING_ADMISSION_TIMEOUT_MS);
         pending.deadline.unref();
     }
     closeDecoded(decoded) {