@zlink-systems/framework 0.26.0 → 0.28.0

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;
@@ -186,7 +191,7 @@ export interface ZLinkSpotAddressTransport {
   sendToSpotAddress(
     spotId: RoutingId,
     message: unknown,
-    options: ZLinkSpotAddressCallOptions
+    options: Omit<ZLinkSpotAddressCallOptions, 'timeoutMs' | 'signal'>
   ): Promise<ZLinkSubmitResult>;
   requestToSpotAddress<TReply = unknown>(
     spotId: RoutingId,
@@ -221,15 +226,14 @@ export interface ZLinkSpotRoutedTransport {
 }
 
 export interface ZLinkSpotRoutedSendOptions {
+  readonly instanceSpot?: boolean;
   readonly packetName?: string;
-  /** Internal end-to-end budget remaining for route admission. */
-  readonly timeoutMs?: number;
-  readonly signal?: AbortSignal;
   readonly metadata?: ReadonlyMap<string, string>;
 }
 
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
   readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
 }
 
 interface MutableAddressCallOptions {
@@ -260,22 +264,30 @@ 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> {
+    async submit(): Promise<void> {
       markSubmitted(options);
       const pending = startRequestOnSerial(serial, () => ({
         pending: transport.sendToSpotAddress(
           spotId,
           message,
-          freezeAddressCallOptions(options, signal, sourceSpotProvider?.())
+          freezeAddressCallOptions(options, sourceSpotProvider?.())
         )
       }));
       const result = await (serial.isCurrentTurn ? pending : deliverOnSerial(serial, pending));
@@ -300,11 +312,11 @@ function createAddressedSpotRequestCall(
     markSubmitted(options);
     rejectSameSpotAsyncRequest(serial, spotId, waitPolicy);
     return startRequestOnSerial<TReply>(serial, () => ({
-      pending: transport.requestToSpotAddress<TReply>(
-        spotId,
-        request,
-        freezeAddressCallOptions(options, signal, sourceSpotProvider?.())
-      )
+      pending: transport.requestToSpotAddress<TReply>(spotId, request, {
+        ...freezeAddressCallOptions(options, sourceSpotProvider?.()),
+        timeoutMs: options.timeoutMs,
+        signal
+      })
     }));
   };
   return {
@@ -316,13 +328,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) {
@@ -400,7 +420,6 @@ function markSubmitted(options: MutableAddressCallOptions): void {
 
 function freezeAddressCallOptions(
   options: MutableAddressCallOptions,
-  signal: AbortSignal | undefined,
   sourceSpot: ZLinkBackendSpot | undefined
 ): ZLinkSpotAddressCallOptions {
   return {
@@ -408,8 +427,6 @@ function freezeAddressCallOptions(
     instanceSpot: options.instanceSpot,
     instanceSpotType: options.instanceSpotType,
     initialMeshName: options.initialMeshName,
-    timeoutMs: options.timeoutMs,
-    signal,
     sourceSpot
   };
 }
@@ -431,8 +448,8 @@ function wrapSendCall(serial: ZLinkSpotSerialTurnExecutor, inner: ZLinkSendCall)
       else inner.metadata(key);
       return this;
     },
-    async submit(signal?: AbortSignal) {
-      const result = await runInternalTransportStart(serial, () => inner.submit(signal));
+    async submit() {
+      const result = await runInternalTransportStart(serial, () => inner.submit());
       return result;
     }
   };
@@ -526,11 +543,10 @@ function wrapRoutedSpotSendCall(
       }
       return this;
     },
-    async submit(signal?: AbortSignal): Promise<void> {
+    async submit(): Promise<void> {
       const pending = startRequestOnSerial(serial, () => ({
         pending: sendToSpotHandle(transport, spot, message, {
           metadata,
-          signal,
           spotRouterChannelIdForMesh,
           sourceSpot: sourceSpotProvider?.()
         })
@@ -623,7 +639,7 @@ export async function sendToSpotHandle(
   transport: ZLinkSpotRoutedTransport,
   spot: SpotHandle,
   message: unknown,
-  options: ZLinkSpotHandleCallOptions = {}
+  options: Omit<ZLinkSpotHandleCallOptions, 'timeoutMs' | 'signal'> = {}
 ): Promise<ZLinkSubmitResult> {
   const packetName = resolveFrameworkPacketName(message, undefined, 'SPOT');
   const sendResolved = async (resolved: ResolvedSpotHandle): Promise<ZLinkSubmitResult> => {
@@ -631,20 +647,16 @@ export async function sendToSpotHandle(
     if (options.sourceSpot !== undefined && transport.sendFromSpotToSpot !== undefined) {
       return transport.sendFromSpotToSpot(options.sourceSpot, target, message, {
         packetName,
-        timeoutMs: options.timeoutMs,
-        signal: options.signal,
         metadata: options.metadata
       });
     }
     return transport.sendToSpot(target, message, {
       packetName,
-      timeoutMs: options.timeoutMs,
-      signal: options.signal,
       metadata: options.metadata
     });
   };
 
-  return sendResolved(await requireSpotRef(spot, options.signal));
+  return sendResolved(await requireSpotRef(spot));
 }
 
 export async function requestToSpotHandle<TReply = unknown>(

package/src/runtime/spots/spot-remote-codec.ts

@@ -1,3 +1,5 @@
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import type { ZLinkBackendActorRef } from '../backend/contracts';
 import { decodeActorMessageFollowContext, type ZLinkRemoteBoundSessionTarget } from '../actors';
 import type { RoutingId, ZLinkActor } from '../../contracts';
@@ -146,7 +148,7 @@ export function decodeRemoteActorJoinPayload(
     requestContentType:
       typeof payload.requestContentType === 'string'
         ? payload.requestContentType
-        : 'application/json'
+        : ZlinkStreamContentType.Json
   };
 }
 
@@ -302,8 +304,10 @@ function decodeBoundSessionServiceWireRelocation(
 
 function requireSpotId(value: string): string {
   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 > ZLINK_MAX_SPOT_ID_BYTES) {
+    throw new Error(
+      `Remote bound session SpotId must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`
+    );
   }
   return value;
 }

package/src/runtime/spots/spot-route-packet-dispatch.ts

@@ -1,21 +1,31 @@
-import type {
-  Type,
-  ZLinkMessageSerializer,
-  ZLinkSpot,
-  ZLinkSpotPacketHandler,
-  ZLinkSpotRequestHandler
+import {
+  type Type,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  type ZLinkSpotPacketHandler,
+  type ZLinkSpotRequestHandler,
+  ZLinkFrameworkException,
+  zlinkMessageMetadata
 } from '../../contracts';
+
+import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkFrameworkException, zlinkMessageMetadata } from '../../contracts';
 import {
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
   ZLinkDispatchMessageKind
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import {
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET,
+  ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET
+} from '../actors';
+import type { ZLinkApplicationWorkClaim } from '../admission';
+import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
-import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import {
   decodeChannelEnvelope,
@@ -27,25 +37,18 @@ import {
   ZLinkChannelMessageKind,
   type ZLinkChannelEnvelopeCodecRegistry
 } from '../channels/channel-envelope';
+import { SPOT_DIRECT_ENVELOPE } from '../channels/spot-direct-envelope';
+import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
+import { zlinkMetadataByteLength, zlinkSerialWorkOptions } from '../execution/serial-work-size';
 import {
-  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET,
-  ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET
-} from '../actors';
+  internalFrameworkErrorKind,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
 import { resolveLifecycleHandler } from '../handlers/handler-instance-scope';
 import type { ZLinkSpotHandlerRegistration } from './spot-handler-registry';
-import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkApplicationWorkClaim } from '../admission';
-import { zlinkMetadataByteLength, zlinkSerialWorkOptions } from '../execution/serial-work-size';
 import { REMOTE_ACTOR_JOIN_PACKET } from './spot-remote-codec';
 import { appendRouteReplyParts, hasReplyToken, submitRouteReply } from './spot-route-replies';
-import { createInboundFlow, runWithFlow } from '../diagnostics/flow-context';
-import {
-  ZLinkFrameworkInternalErrorKind,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
-import { releaseApplicationJobPermitBeforeHandler } from '../application-jobs/application-job-queue-scope';
+import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 
 interface ZLinkSpotRoutePacketDispatchOptions {
   readonly packetHandlers: ReadonlyMap<string, readonly ZLinkSpotHandlerRegistration[]>;
@@ -58,8 +61,6 @@ interface ZLinkSpotRoutePacketDispatchOptions {
   readonly claimApplicationWork?: () => ZLinkApplicationWorkClaim;
 }
 
-const SPOT_DIRECT_ENVELOPE = 'zlink.framework.spot-direct.v1';
-
 /** D5: reply metadata attached only to framework-self-generated errors. */
 const FRAMEWORK_ORIGIN_REPLY_METADATA: Readonly<Record<string, string>> = Object.freeze({
   [ZLINK_FRAMEWORK_ORIGIN_METADATA_KEY]: ZLINK_FRAMEWORK_ORIGIN_METADATA_VALUE

package/src/runtime/spots/spot-route-replies.ts

@@ -1,6 +1,7 @@
+import { constants as osConstants } from 'node:os';
 import type {
-  ZLinkBackendMessageLike as MessageLike,
-  ZLinkBackendReceived as BackendReceived
+  ZLinkBackendReceived as BackendReceived,
+  ZLinkBackendMessageLike as MessageLike
 } from '../backend/runtime-values';
 import {
   decodeChannelEnvelope,
@@ -8,8 +9,9 @@ import {
   encodeChannelReplyParts
 } from '../channels/channel-envelope';
 import { ZLinkConfigurationException } from '../configuration';
-import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
 import type { ZLinkDecodedRemoteActorJoinRequest } from './spot-remote-codec';
+import { encodeSpotRouteBridgeReply } from './spot-route-reply-wire';
+const nativeErrnoValues = osConstants.errno;
 
 export interface ZLinkRouteReplySubmitOperation {
   message(message: MessageLike): ZLinkRouteReplySubmitOperation;
@@ -120,6 +122,6 @@ function isNativeBadAddress(error: unknown): boolean {
   return (
     typeof error === 'object' &&
     error !== null &&
-    Number((error as { nativeErrno?: unknown }).nativeErrno) === 14
+    Number((error as { nativeErrno?: unknown }).nativeErrno) === nativeErrnoValues.EFAULT
   );
 }

package/src/runtime/spots/spot-routed-actor-admission.ts

@@ -5,6 +5,8 @@ import type {
   ZLinkSpotActorJoinResult
 } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
 import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
 import {
@@ -23,16 +25,12 @@ import {
   hasRemoteActorJoinIdentity,
   isRemoteActorJoinPayload,
   type ZLinkDecodedRemoteActorJoinRequest,
-  type ZLinkRoutedActorTransferProvider,
-  type ZLinkRemoteActorJoinWirePayload
+  type ZLinkRemoteActorJoinWirePayload,
+  type ZLinkRoutedActorTransferProvider
 } from './spot-remote-codec';
 import { submitRoutedActorJoinError, submitRoutedActorJoinReply } from './spot-route-replies';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from '../actors/actor-handoff';
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
+const DEFAULT_PENDING_ADMISSION_TIMEOUT_MS = 30_000;
 
 interface ZLinkRoutedActorAdmissionTarget {
   onActorJoin?(actorId: string, request: ZLinkMessage): Promise<ZLinkSpotActorJoinResult>;
@@ -40,13 +38,13 @@ interface ZLinkRoutedActorAdmissionTarget {
 
 interface ZLinkSpotRoutedActorAdmissionOptions {
   readonly serial: ZLinkSpotSerialTurnExecutor;
-  readonly isSpotClosing?: () => boolean;
   readonly getTarget: () => ZLinkRoutedActorAdmissionTarget;
   readonly defaultAccept: boolean;
   readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
   readonly commitTransferredActor?: (
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ) => Promise<readonly ZLinkActorHandoffResult[]>;
   readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
   readonly pendingAdmissionTimeoutMs?: number;
@@ -78,21 +76,6 @@ export class ZLinkSpotRoutedActorAdmission {
     if (decoded === undefined) {
       return false;
     }
-    if (this.options.isSpotClosing?.() === true) {
-      try {
-        submitRoutedActorJoinError(
-          received,
-          decoded,
-          createInternalFrameworkException(
-            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;
@@ -240,7 +223,11 @@ export class ZLinkSpotRoutedActorAdmission {
         decoded.remoteBoundSessionTarget
       );
       const handoffResults =
-        (await this.options.commitTransferredActor?.(actor, decoded.handoffBacklog)) ?? [];
+        (await this.options.commitTransferredActor?.(
+          actor,
+          decoded.handoffBacklog,
+          decoded.remoteBoundSessionTarget
+        )) ?? [];
       const commitReply = {
         accepted: true,
         actorNodeRid: String(actorRef.nodeRid),
@@ -298,7 +285,7 @@ export class ZLinkSpotRoutedActorAdmission {
     if (pending.deadline !== undefined) clearTimeout(pending.deadline);
     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();
   }
 

package/src/runtime/spots/spot-routed-frame-dispatch.ts

@@ -34,14 +34,14 @@ interface ZLinkRoutedFrameAdmissionTarget {
 interface ZLinkSpotRoutedFrameDispatchOptions {
   readonly nativeSpotId: string;
   readonly serial: ZLinkSpotSerialTurnExecutor;
-  readonly isSpotClosing?: () => boolean;
   readonly resolveActor: (actorId: string) => ZLinkActor | undefined;
   readonly getTarget: () => ZLinkRoutedFrameAdmissionTarget & ZLinkSpot;
   readonly defaultAccept: boolean;
   readonly routedActorTransferProvider?: ZLinkRoutedActorTransferProvider;
   readonly commitTransferredActor?: (
     actor: ZLinkActor,
-    backlog: readonly ZLinkActorHandoffPacket[]
+    backlog: readonly ZLinkActorHandoffPacket[],
+    sealedSession: ZLinkRemoteBoundSessionTarget | undefined
   ) => Promise<readonly ZLinkActorHandoffResult[]>;
   readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
   readonly routedBoundSessionReceiver?: (
@@ -119,7 +119,6 @@ export class ZLinkSpotRoutedFrameDispatch {
     });
     this.routedActorAdmission = new ZLinkSpotRoutedActorAdmission({
       serial: options.serial,
-      isSpotClosing: options.isSpotClosing,
       getTarget: options.getTarget,
       defaultAccept: options.defaultAccept,
       routedActorTransferProvider: options.routedActorTransferProvider,