@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/spots/spot-node-runtime-manager.ts

@@ -1,60 +1,53 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
+import { RuntimeDisposal } from '../disposal';
 import { randomUUID } from 'node:crypto';
-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 { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from '../../contracts/Locations';
 import {
-  ZLinkFrameworkRuntimeState,
+  type ActorRef,
+  type RoutingId,
+  type ZLinkActor,
+  type ZLinkChannelClient,
+  type ZLinkFanoutClient,
+  type ZLinkMeshNodeDescriptor,
+  type ZLinkMessage,
+  type ZLinkMessageSerializer,
+  type ZLinkSpotPublisherClient,
   ZLinkFrameworkException,
+  ZLinkFrameworkRuntimeState,
   ZLinkObjectRole
 } from '../../contracts';
-import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
+
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { DEFAULT_ACTIVATION_CONCURRENCY_LIMIT } from '../../contracts/Configuration/InternalDefaults';
+import {
+  ZLINK_DEFAULT_PUBLIC_WEIGHT,
+  ZLINK_MAX_CAPACITY,
+  ZLINK_MAX_PUBLIC_WEIGHT,
+  isValidPublicWeight
+} from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import {
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import { SubmitResult, isZLinkBackendResultError } from '../backend/runtime-values';
-import {
-  ReceiveKind,
-  type ReadyRecord,
-  type ReceiveRecord
-} from '../foundation/service-runtime-contracts';
-import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
-import {
-  ZLinkConfigurationException,
-  type ZLinkFrameworkRegistration,
-  type ZLinkSpotNodeOptions
-} from '../configuration';
+import { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from '../../contracts/Locations';
+import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ZLinkLocationOwnerToken } from '../../contracts/Locations/Writes';
+import { createAbortError } from '../abort';
+import type { ZLinkActivationConcurrency } from '../activation-admission';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
 import type {
   ZLinkBackendAdapterFactory,
   ZLinkBackendContext,
   ZLinkBackendMeshNode,
   ZLinkBackendSpotNode
 } from '../backend/contracts';
-import type { ZLinkLocationOwnerToken } from '../../contracts/Locations/Writes';
-import { ZLinkMeshDispatchPump } from '../backend/mesh-dispatch-pump';
-import { requireZLinkInfrastructureExecutionArea } from '../execution';
-import { runWithOutboundFlow } from '../diagnostics/flow-context';
 import { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import { ZLinkMeshDispatchPump } from '../backend/mesh-dispatch-pump';
+import { SubmitResult, isZLinkBackendResultError } from '../backend/runtime-values';
 import type { ZLinkDispatchErrorReporter } from '../channels';
+import { requireUniqueRouteMeshChannel, resolveChannelRoute } from '../channels/channel-clients';
 import {
   decodeChannelEnvelope,
   decodeChannelPayload,
@@ -62,6 +55,31 @@ import {
   encodeChannelPublishEnvelopeParts,
   encodeChannelReplyParts
 } from '../channels/channel-envelope';
+import {
+  ZLinkConfigurationException,
+  type ZLinkFrameworkRegistration,
+  type ZLinkSpotNodeOptions
+} from '../configuration';
+import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
+import { runWithOutboundFlow } from '../diagnostics/flow-context';
+import { requireZLinkInfrastructureExecutionArea } from '../execution';
+import type { ZLinkListenerRecords } from '../foundation/listener-records';
+import {
+  type ZLinkMessageFollowOrigin,
+  ReceiveKind,
+  type ReadyRecord,
+  type ReceiveRecord
+} from '../foundation/service-runtime-contracts';
+
+import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import {
+  ApplicationJobQueue,
+  resolveApplicationJobQueueConfiguration
+} from '../host/application-job-queue';
 import {
   ZLinkAutoConnectLoop,
   ZLinkAutoConnectReconciler,
@@ -69,8 +87,12 @@ import {
   type ZLinkLocationEventSink,
   type ZLinkLocationRuntimeStores
 } from '../locations';
-import type { ZLinkRemoteBoundSessionTarget } from '../actors';
-import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+import {
+  classifySubmitResult,
+  ZLinkSubmitStatus,
+  type ZLinkSubmitResult
+} from '../messaging/submission-result';
+import { routingIdsEqual, toBackendRoutingId } from '../routing-id';
 import type { ZLinkDetachedTaskRunner } from './spot-actor-join-dispatch';
 import { ZLinkEntrySpotActivation } from './spot-entry-activation';
 import {
@@ -80,19 +102,13 @@ import {
 } from './spot-node-autoconnect';
 import type { ZLinkSpotRoutedTransport } from './spot-outbound';
 import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
-import { routingIdsEqual, toBackendRoutingId } from '../routing-id';
 import type {
   ZLinkEntryActorRuntime,
-  ZLinkSpotActorTransferRuntime,
   ZLinkSpotActorHandoffRuntime,
+  ZLinkSpotActorTransferRuntime,
   ZLinkSpotBoundSessionRuntime
 } from './spot-runtime-ports';
-import { createAbortError } from '../abort';
-import type { ServiceMessageFollowRecord } from '../foundation/service-stateful-wire-codec';
-import {
-  ApplicationJobQueue,
-  resolveApplicationJobQueueConfiguration
-} from '../host/application-job-queue';
+const DEFAULT_SPOT_NODE_SHUTDOWN_TIMEOUT_MS = 1000;
 
 const ZLINK_SEND_DONT_WAIT = 1;
 
@@ -101,6 +117,8 @@ const ZLINK_SEND_DONT_WAIT = 1;
 const EMPTY_SPOT_METADATA: ReadonlyMap<string, string> = new Map();
 
 export interface ZLinkSpotNodeRuntimeManagerOptions {
+  readonly errorSink: import('../diagnostics/dispatch-error-port').ZLinkDispatchErrorSink;
+  readonly listenerRecords?: ZLinkListenerRecords;
   readonly registration: ZLinkFrameworkRegistration;
   readonly primaryMeshName?: string;
   readonly backendAdapterFactory: ZLinkBackendAdapterFactory;
@@ -120,7 +138,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;
@@ -130,10 +148,8 @@ export interface ZLinkSpotNodeRuntimeManagerOptions {
     record: ReceiveRecord
   ) => void | Promise<void>;
   readonly messageFollowReceiver?: (record: ServiceMessageFollowRecord) => void;
-  readonly instanceActivationConcurrencyProvider?: (meshName: string) => {
-    readonly active: number;
-    readonly limit: number;
-  };
+  /** MeshNode §5.1 activation admission record; the descriptor projects it for placement. */
+  readonly activationConcurrency?: (meshName: string) => ZLinkActivationConcurrency;
 }
 
 export class ZLinkSpotNodeRuntimeManager {
@@ -146,7 +162,7 @@ export class ZLinkSpotNodeRuntimeManager {
     string,
     ReturnType<ZLinkBackendMeshNode['createPublisher']>
   >();
-  private disposed = false;
+  private readonly disposal = new RuntimeDisposal();
   private readonly autoConnectLoops: ZLinkAutoConnectLoop[] = [];
   private readonly publishedMeshNodeDescriptors = new Map<string, ZLinkMeshNodeDescriptor>();
   // Keep the revision source separate from the cached Store row. A new owner
@@ -163,15 +179,14 @@ export class ZLinkSpotNodeRuntimeManager {
   private readonly applicationJobQueue: ApplicationJobQueue;
 
   constructor(private readonly options: ZLinkSpotNodeRuntimeManagerOptions) {
+    if ((options.detachedTaskRunner as unknown) === undefined) {
+      throw new ZLinkConfigurationException('Spot node runtime requires a detached task runner.');
+    }
     this.applicationJobQueue =
       options.applicationJobQueue ??
       new ApplicationJobQueue(resolveApplicationJobQueueConfiguration());
   }
 
-  createReceived() {
-    return this.options.backendAdapterFactory.createReceived();
-  }
-
   createTopicMessage() {
     return this.options.backendAdapterFactory.createTopicMessage();
   }
@@ -210,7 +225,8 @@ export class ZLinkSpotNodeRuntimeManager {
           peerResolver: location.resolver,
           executor: capability.executor,
           events: location.events,
-          options: location.options
+          options: location.options,
+          errorSink: this.options.errorSink
         });
         const loop = new ZLinkAutoConnectLoop({
           reconciler,
@@ -326,12 +342,13 @@ export class ZLinkSpotNodeRuntimeManager {
             : Object.keys(spotNode.actorFactories ?? {}).length) > 0;
         node.configureObjectPlacement({
           role: spotNode.objectRole ?? (hasLegacyObjectFactories ? 'server' : 'none'),
-          placementWeight: spotNode.placementWeight ?? 100,
+          placementWeight: spotNode.placementWeight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT,
           activeCapacityLimit: aggregatePlacementCapacity(
             spotNode.actorLimit ?? 0,
             spotNode.spotLimit ?? 0
           ),
-          pendingCapacityLimit: spotNode.activationConcurrencyLimit ?? 128,
+          pendingCapacityLimit:
+            spotNode.activationConcurrencyLimit ?? DEFAULT_ACTIVATION_CONCURRENCY_LIMIT,
           objectCapabilities: [
             ...stableTypes.map((type) => `object-type:${type}`),
             ...instanceSpotTypes.map((type) => `instance-spot-type:${type}`)
@@ -378,6 +395,10 @@ export class ZLinkSpotNodeRuntimeManager {
         this.meshNodes.set(spotNodeName, node);
         this.meshPumps.set(spotNodeName, pump);
         this.meshCompletions.set(spotNodeName, completions);
+        const listenerEndpoint = node.status().localEndpoint;
+        if (listenerEndpoint.length > 0) {
+          this.options.listenerRecords?.record('routeMesh', spotNodeName, listenerEndpoint);
+        }
       } catch (error) {
         this.entryActivations.delete(spotNodeName);
         this.publishers.get(spotNodeName)?.close();
@@ -488,22 +509,20 @@ export class ZLinkSpotNodeRuntimeManager {
               };
             })
         },
-        activationConcurrency: {
-          active:
-            this.options.instanceActivationConcurrencyProvider?.(meshName).active ??
-            current?.activationConcurrency.active ??
-            0,
-          limit:
-            this.options.instanceActivationConcurrencyProvider?.(meshName).limit ??
-            registration.activationConcurrencyLimit ??
-            128
+        activationConcurrency: this.options.activationConcurrency?.(meshName) ?? {
+          active: 0,
+          limit: registration.activationConcurrencyLimit ?? DEFAULT_ACTIVATION_CONCURRENCY_LIMIT
         },
         channelWeights: Object.fromEntries(
           this.serverChannels(meshName).map(([channelName, channel]) => [
             channelName,
             state === ZLinkFrameworkRuntimeState.Draining
               ? 0
-              : this.effectiveChannelWeight(meshName, channelName, channel.weight ?? 100)
+              : this.effectiveChannelWeight(
+                  meshName,
+                  channelName,
+                  channel.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
+                )
           ])
         ),
         applicationVersion: this.options.registration.applicationVersion,
@@ -618,7 +637,11 @@ export class ZLinkSpotNodeRuntimeManager {
     if (registration === undefined) {
       throw new ZLinkConfigurationException(`Mesh '${meshName}' is not registered.`);
     }
-    return this.runtimePlacementWeights.get(meshName) ?? registration.placementWeight ?? 100;
+    return (
+      this.runtimePlacementWeights.get(meshName) ??
+      registration.placementWeight ??
+      ZLINK_DEFAULT_PUBLIC_WEIGHT
+    );
   }
 
   channelWeight(channelName: string): number {
@@ -691,21 +714,21 @@ export class ZLinkSpotNodeRuntimeManager {
     readonly meshName: string;
     readonly configuredWeight: number;
   } {
-    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 = resolveChannelRoute(this.options.registration, channelName);
+    if (route?.kind !== 'route-mesh') {
       throw new ZLinkConfigurationException(
         `RouteMesh channel '${channelName}' is not registered.`
       );
     }
-    if (matches.length > 1) {
-      throw new ZLinkConfigurationException(
-        `RouteMesh channel '${channelName}' is registered in more than one Mesh.`
-      );
-    }
-    return matches[0]!;
+    const match = requireUniqueRouteMeshChannel(
+      route.matches,
+      `RouteMesh channel '${channelName}' is registered in more than one Mesh.`
+    );
+    return {
+      meshName: match.meshName,
+      configuredWeight:
+        match.mesh.meshChannels?.[channelName]?.weight ?? ZLINK_DEFAULT_PUBLIC_WEIGHT
+    };
   }
 
   private scheduleRuntimeWeightPublication(
@@ -722,14 +745,10 @@ export 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(): ZLinkMeshCompletionTable | undefined {
@@ -796,18 +815,17 @@ export class ZLinkSpotNodeRuntimeManager {
     ).filter(([, channel]) => channel.server === true);
   }
 
-  async dispose(signal?: AbortSignal, deadline?: Date): Promise<void> {
-    this.disposed = true;
+  dispose(signal?: AbortSignal, deadline?: Date): Promise<void> {
+    return this.disposal.run(() => this.disposeCore(signal, deadline));
+  }
+
+  private async disposeCore(signal?: AbortSignal, deadline?: Date): Promise<void> {
     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: unknown[] = [];
     const settle = async (operations: readonly Promise<unknown>[]) => {
       const results = await Promise.allSettled(operations);
@@ -823,18 +841,22 @@ export class ZLinkSpotNodeRuntimeManager {
     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();
   }
 
   private async dispatchMeshRecord(
@@ -975,7 +997,6 @@ export class ZLinkSpotNodeRuntimeManager {
       entrySpotType: spotNode.entrySpotType,
       nativeSpot: node.entrySpot() as never,
       nativeNode: node as unknown as ZLinkBackendSpotNode,
-      createReceived: () => this.options.backendAdapterFactory.createReceived(),
       createTopicMessage: () => this.options.backendAdapterFactory.createTopicMessage(),
       nodeRid: String(node.status().routingId),
       spotNodeName,
@@ -985,8 +1006,6 @@ export 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,
@@ -1089,6 +1108,16 @@ export class ZLinkSpotNodeRuntimeManager {
     await activation.commitServiceActorJoin(actor, handoffBacklog);
   }
 
+  executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T> {
+    const activation = this.entryActivations.get(meshName);
+    if (activation === undefined) {
+      throw new ZLinkConfigurationException(
+        `Entry Spot Actor '${actorId}' has no activation for MeshNode '${meshName}'.`
+      );
+    }
+    return activation.executeActor(actorId, operation);
+  }
+
   publish(
     meshName: string,
     channelName: string,
@@ -1098,7 +1127,7 @@ export class ZLinkSpotNodeRuntimeManager {
     signal?: AbortSignal,
     metadata: ReadonlyMap<string, string> = EMPTY_SPOT_METADATA
   ): Promise<ZLinkSubmitResult> {
-    if (this.disposed) {
+    if (this.disposal.started) {
       return Promise.reject(runtimeShutdownError());
     }
     if (signal?.aborted === true) {
@@ -1165,7 +1194,7 @@ export class ZLinkSpotNodeRuntimeManager {
     flags: number,
     metadata: ReadonlyMap<string, string>
   ): ZLinkSubmitResult {
-    if (this.disposed) {
+    if (this.disposal.started) {
       throw runtimeShutdownError();
     }
     const publisher = this.publishers.get(meshName);
@@ -1214,39 +1243,13 @@ export function createFrameworkEntrySpotId(prefix: string): string {
   return `${prefix}-entry-${randomUUID()}`;
 }
 
-function resolveChannelMeshName(
-  registration: ZLinkFrameworkRegistration,
-  channelName: string
-): string | undefined {
-  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: number): ZLinkSubmitStatus {
-  switch (result) {
-    case SubmitResult.Ok:
-      return ZLinkSubmitStatus.Submitted;
-    case SubmitResult.Backpressured:
-    case SubmitResult.NotAdmitted:
-      return ZLinkSubmitStatus.Backpressured;
-    case SubmitResult.NotFound:
-      // A publish with no matching subscriber is a successful zero-recipient
-      // operation, not an operation-specific not-found failure.
-      return ZLinkSubmitStatus.Submitted;
-    case SubmitResult.NotConnected:
-      return ZLinkSubmitStatus.RouteNotConnected;
-    case SubmitResult.Terminated:
-    case SubmitResult.InvalidHandle:
-      return ZLinkSubmitStatus.Shutdown;
-    default:
-      throw new ZLinkConfigurationException(
-        `Logical Multicast failed with submit result '${result}'.`
-      );
-  }
+  // Source publication preserves its local admission status before commit.
+  if (result === SubmitResult.NotAdmitted || result === SubmitResult.Backpressured)
+    return ZLinkSubmitStatus.Backpressured;
+  // A publish with no matching subscriber succeeds with zero recipients.
+  if (result === SubmitResult.NotFound) return ZLinkSubmitStatus.Submitted;
+  return classifySubmitResult(result, 'Logical Multicast').status;
 }
 
 function requireEntrySpotReply(result: number): void {
@@ -1258,8 +1261,10 @@ function requireEntrySpotReply(result: number): void {
 }
 
 function requirePublicRuntimeWeight(value: number, label: string): number {
-  if (!Number.isInteger(value) || value < 0 || value > 10_000) {
-    throw new ZLinkConfigurationException(`${label} must be an integer in 0..10000.`);
+  if (!isValidPublicWeight(value)) {
+    throw new ZLinkConfigurationException(
+      `${label} must be an integer in 0..${ZLINK_MAX_PUBLIC_WEIGHT}.`
+    );
   }
   return value;
 }
@@ -1351,7 +1356,7 @@ function objectCapability(
 }
 
 function aggregatePlacementCapacity(actorLimit: number, spotLimit: number): number {
-  const unlimited = 0x7fff_ffff;
+  const unlimited = ZLINK_MAX_CAPACITY;
   const actors = actorLimit === 0 ? unlimited : actorLimit;
   const spots = spotLimit === 0 ? unlimited : spotLimit;
   return Math.min(unlimited, actors + spots);

package/src/runtime/spots/spot-outbound.ts

@@ -1,42 +1,40 @@
+import {
+  type RoutingId,
+  type ZLinkChannelClient,
+  type ZLinkChannelRequestCall,
+  type ZLinkMessageMetadata,
+  type ZLinkPublishCall,
+  type ZLinkRequestCall,
+  type ZLinkSendCall,
+  type ZLinkSpotOutbound,
+  type ZLinkSpotPublisherClient,
+  type ZLinkSpotRequestCall,
+  type ZLinkSpotSendCall,
+  ZLinkSpotKind
+} from '../../contracts';
+
+import {
+  ZLINK_MAX_MESH_NAME_BYTES,
+  ZLINK_MAX_STABLE_TYPE_BYTES
+} from '../../contracts/Common/CoreTypes';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import { ZLinkConfigurationException } from '../configuration';
+import { requireZLinkYieldTurn } from '../execution';
 import {
   ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
+  createInternalFrameworkException
 } from '../framework-errors-internal';
-import { ZLinkFrameworkRuntimeState, ZLinkSpotKind } from '../../contracts';
-import { ZLinkFrameworkException } from '../../contracts/Errors';
-import type {
-  RoutingId,
-  ZLinkChannelClient,
-  ZLinkChannelRequestCall,
-  ZLinkPublishCall,
-  ZLinkRequestCall,
-  ZLinkSendCall,
-  ZLinkMessageMetadata,
-  ZLinkSpotOutbound,
-  ZLinkSpotRequestCall,
-  ZLinkSpotSendCall,
-  ZLinkSpotPublisherClient
-} from '../../contracts';
+import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import {
   requireOneWayCompletion,
   throwAlreadySubmitted,
   type ZLinkSubmitResult
 } from '../messaging/submission-result';
 import { normalizeOpaqueRoutingId } from '../routing-id';
-import { ZLinkConfigurationException } from '../configuration';
-import type { ZLinkBackendSpot } from '../backend/contracts';
 import { deliverOnSerial } from '../workers';
-import { requireZLinkYieldTurn } from '../execution';
-import { resolveFrameworkPacketName } from '../messaging/packet-name';
+import { resolveSpotHandle, type ResolvedSpotHandle, type SpotHandle } from './spot-handle';
 import type { ZLinkSpotRouteTarget } from './spot-routing-internal';
 import { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import {
-  resolveSpotHandle,
-  refreshSpotHandle,
-  type SpotHandle,
-  type ResolvedSpotHandle
-} from './spot-handle';
 
 export interface DefaultZLinkSpotOutboundOptions {
   readonly serial: ZLinkSpotSerialTurnExecutor;
@@ -228,6 +226,7 @@ export interface ZLinkSpotRoutedTransport {
 }
 
 export interface ZLinkSpotRoutedSendOptions {
+  readonly instanceSpot?: boolean;
   readonly packetName?: string;
   /** Internal end-to-end budget remaining for route admission. */
   readonly timeoutMs?: number;
@@ -267,13 +266,21 @@ function createAddressedSpotSendCall(
       selectOnce(options, 'instanceSpot');
       options.instanceSpot = true;
       if (instanceSpotType !== undefined) {
-        options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+        options.instanceSpotType = requireAddressValue(
+          instanceSpotType,
+          'Instance Spot type',
+          ZLINK_MAX_STABLE_TYPE_BYTES
+        );
       }
       return this;
     },
     inMesh(meshName: string) {
       selectOnce(options, 'inMesh');
-      options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+      options.initialMeshName = requireAddressValue(
+        meshName,
+        'Mesh name',
+        ZLINK_MAX_MESH_NAME_BYTES
+      );
       return this;
     },
     async submit(signal?: AbortSignal): Promise<void> {
@@ -323,13 +330,21 @@ function createAddressedSpotRequestCall(
       selectOnce(options, 'instanceSpot');
       options.instanceSpot = true;
       if (instanceSpotType !== undefined) {
-        options.instanceSpotType = requireAddressValue(instanceSpotType, 'Instance Spot type', 255);
+        options.instanceSpotType = requireAddressValue(
+          instanceSpotType,
+          'Instance Spot type',
+          ZLINK_MAX_STABLE_TYPE_BYTES
+        );
       }
       return this;
     },
     inMesh(meshName: string) {
       selectOnce(options, 'inMesh');
-      options.initialMeshName = requireAddressValue(meshName, 'Mesh name', 255);
+      options.initialMeshName = requireAddressValue(
+        meshName,
+        'Mesh name',
+        ZLINK_MAX_MESH_NAME_BYTES
+      );
       return this;
     },
     timeout(timeoutMs: number) {
@@ -680,29 +695,7 @@ export async function requestToSpotHandle<TReply = unknown>(
     return transport.requestToSpot<TReply>(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: ResolvedSpotHandle | undefined;
-    try {
-      refreshed = await refreshSpotHandle(spot, options.signal);
-    } catch {
-      throw error;
-    }
-    if (isShutdownTargetState(refreshed?.targetNodeState)) {
-      throw createInternalFrameworkException(
-        ZLinkFrameworkInternalErrorKind.RuntimeShutdown,
-        `Spot '${String(spot.spotId)}' target host is shutting down.`,
-        false,
-        error
-      );
-    }
-    throw error;
-  }
+  return requestResolved(await requireSpotRef(spot, options.signal));
 }
 
 async function requireSpotRef(
@@ -730,20 +723,6 @@ function spotRefToSpotRouteTarget(
   };
 }
 
-function shouldRefreshAfterRouteDisconnect(target: ResolvedSpotHandle, error: unknown): boolean {
-  return (
-    target.targetNodeState === ZLinkFrameworkRuntimeState.Serving &&
-    error instanceof ZLinkFrameworkException &&
-    internalFrameworkErrorKind(error) === ZLinkFrameworkInternalErrorKind.RouteNotConnected
-  );
-}
-
-function isShutdownTargetState(state: ResolvedSpotHandle['targetNodeState']): boolean {
-  return (
-    state === ZLinkFrameworkRuntimeState.Draining || state === ZLinkFrameworkRuntimeState.Stopped
-  );
-}
-
 function normalizeSpotRefRoutingId(routingId: RoutingId): RoutingId {
   return normalizeOpaqueRoutingId(routingId);
 }