@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -1,3 +1,4 @@
+import { ZLINK_DEFAULT_PUBLIC_WEIGHT } from '../../contracts/Configuration/RegistrationBuilderPolicy';
 import type { ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
 import type { ZLinkPeerLocationFilter } from '../../contracts/Locations/Keys';
 import type { ZLinkPeerLocationResolver } from '../../contracts/Locations/Resolvers';
@@ -10,6 +11,7 @@ import type { ZLinkBackendMeshNode } from '../backend/contracts';
 import { AsyncResource } from 'node:async_hooks';
 import { ZLinkStateLane } from '../execution/state-lane';
 import { toBackendRoutingId as toBackendRoutingId } from '../routing-id';
+import { MeshPeerRuntimeState } from '../foundation/service-runtime-contracts';
 import {
   ZLinkLocationRuntime,
   ZLinkOwnerLeaseTracker,
@@ -113,7 +115,7 @@ function meshDescriptorPeerResolver(runtime: ZLinkLocationRuntime): ZLinkPeerLoc
           nodeRid: descriptor.rid,
           role: ZLinkLocationRole.Router,
           endpoint: descriptor.endpoint,
-          weight: 100,
+          weight: ZLINK_DEFAULT_PUBLIC_WEIGHT,
           draining: descriptor.state !== ZLinkFrameworkRuntimeState.Serving,
           value: descriptor.descriptorRevision,
           ownerId: descriptor.ownerId,
@@ -205,7 +207,7 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
           peer.endpoint === target.endpoint &&
           (target.nodeRid === undefined || String(peer.routingId) === String(target.nodeRid)) &&
           peer.lifecycleGeneration === target.lifecycleGeneration &&
-          peer.state === 3
+          peer.state === MeshPeerRuntimeState.Serving
       );
   }
 
@@ -241,7 +243,9 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
   }
 
   private prepareConnectCore(key: string): ZLinkSpotNodeConnectionIntent | undefined {
-    if (this.connectionIntents.has(key)) return undefined;
+    const current = this.connectionIntents.get(key);
+    if (current !== undefined)
+      return current.connectionIntentId === undefined ? current : undefined;
     const intent: ZLinkSpotNodeConnectionIntent = {};
     this.connectionIntents.set(key, intent);
     return intent;
@@ -252,29 +256,19 @@ class ZLinkSpotNodeAutoConnectExecutor implements IZLinkAutoConnectExecutor {
     key: string,
     intent: ZLinkSpotNodeConnectionIntent
   ): Promise<boolean> {
-    try {
-      const connectionIntentId = await this.node.connectPeer({
-        endpoint: target.endpoint,
-        expectedRid: target.nodeRid === undefined ? undefined : toBackendRoutingId(target.nodeRid),
-        expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
-        expectedLifecycleGeneration: target.lifecycleGeneration
-      });
-      const accepted = await this.lane.run(() => {
-        if (this.connectionIntents.get(key) !== intent) return false;
-        intent.connectionIntentId = connectionIntentId;
-        return true;
-      });
-      if (!accepted) this.node.removePeerConnection(connectionIntentId);
-      return accepted;
-    } catch {
-      // A discovered endpoint can become unavailable between the store read and
-      // the socket connect. Leave the target inactive so the next reconciliation
-      // can retry without terminating the host's background runtime.
-      await this.lane.run(() => {
-        if (this.connectionIntents.get(key) === intent) this.connectionIntents.delete(key);
-      });
-      return false;
-    }
+    const connectionIntentId = await this.node.connectPeer({
+      endpoint: target.endpoint,
+      expectedRid: target.nodeRid === undefined ? undefined : toBackendRoutingId(target.nodeRid),
+      expectedSecurityIdentity: toAdmissionSecurityIdentity(target.metadata?.securityIdentity),
+      expectedLifecycleGeneration: target.lifecycleGeneration
+    });
+    const accepted = await this.lane.run(() => {
+      if (this.connectionIntents.get(key) !== intent) return false;
+      intent.connectionIntentId = connectionIntentId;
+      return true;
+    });
+    if (!accepted) this.node.removePeerConnection(connectionIntentId);
+    return accepted;
   }
 
   private disconnectPeer(target: ZLinkAutoConnectTarget): void {

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

@@ -1,61 +1,53 @@
-import type { ZLinkListenerRecords } from '../foundation/listener-records';
-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,
@@ -63,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,
@@ -70,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 {
@@ -81,20 +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 { ZLinkActivationConcurrency } from '../activation-admission';
-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;
 
@@ -103,6 +117,7 @@ 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;
@@ -123,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;
@@ -147,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
@@ -164,6 +179,9 @@ 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());
@@ -207,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,
@@ -323,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}`)
@@ -491,14 +511,18 @@ export class ZLinkSpotNodeRuntimeManager {
         },
         activationConcurrency: this.options.activationConcurrency?.(meshName) ?? {
           active: 0,
-          limit: registration.activationConcurrencyLimit ?? 128
+          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,
@@ -613,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 {
@@ -686,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(
@@ -717,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 {
@@ -791,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);
@@ -818,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(
@@ -979,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,
@@ -1083,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,
@@ -1092,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) {
@@ -1159,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);
@@ -1208,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 {
@@ -1252,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;
 }
@@ -1345,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,35 +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
 } from '../framework-errors-internal';
-import { ZLinkSpotKind } from '../../contracts';
-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, type SpotHandle, type ResolvedSpotHandle } from './spot-handle';
 
 export interface DefaultZLinkSpotOutboundOptions {
   readonly serial: ZLinkSpotSerialTurnExecutor;
@@ -221,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;
@@ -260,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> {
@@ -316,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) {