@zlink-systems/framework 0.30.0 → 0.30.1

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -1,3 +1,4 @@
+import { requestDurableService } from '../../foundation/durable-service-request';
 import {
   decodeStreamWireFrame,
   decodeStreamWireHeader,
@@ -19,7 +20,11 @@ import {
 import { randomBytes } from 'node:crypto';
 import type { ZLinkMeshCompletionHandler } from '../mesh-completion-table';
 import { setImmediate as yieldToIO } from 'node:timers/promises';
-import { type RoutingId, ZLinkFrameworkException } from '../../../contracts';
+import {
+  type RoutingId,
+  ZLinkFrameworkException,
+  ZLinkFrameworkErrorKind
+} from '../../../contracts';
 
 import type { Message as FrameworkMessage } from '../../../contracts/Common/Message';
 import { ZLinkConfigurationException } from '../../../contracts/Configuration/ConfigurationException';
@@ -172,7 +177,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     }
   >();
   private completionHandler?: ZLinkMeshCompletionHandler;
-  private readonly routingId: string;
+  readonly routingId: string;
   private readonly lifecycleGeneration: bigint;
   private bindEndpoint?: string;
   private advertiseHost?: string;
@@ -342,7 +347,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     parts: MessageLike | readonly MessageLike[],
     deadlineUnixMs: bigint,
     sourceSpotId?: string,
-    metadata?: ReadonlyMap<string, string>
+    metadata?: ReadonlyMap<string, string>,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.InstanceSpotRequest,
@@ -351,7 +357,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         encodeMultipartApplicationFrame(parts),
         deadlineUnixMs,
         sourceSpotId,
-        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata)
+        metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
+        onAdmitted
       )
     );
   }
@@ -411,15 +418,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
           }
         }
       },
-      onPeerDisconnected: (nodeRoutingId, endpoint) => {
-        for (const [intentId, peer] of this.peerIntents) {
-          if (
-            peer.endpoint === endpoint &&
-            (peer.nodeRoutingId === undefined || peer.nodeRoutingId === nodeRoutingId)
-          ) {
-            this.peerIntents.delete(intentId);
-          }
-        }
+      onPeerDisconnected: (_nodeRoutingId, endpoint) => {
         for (const handler of this.peerDisconnectedHandlers) handler(endpoint);
       }
     });
@@ -630,20 +629,38 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     return this.requireRuntime().isObjectClientNodeDirectTarget(String(targetRid));
   }
 
+  observePeerRoute(targetRid: unknown) {
+    return this.requireRuntime().observePeerRoute(String(targetRid));
+  }
+
+  hasPeerRouteOrConnectionIntent(targetRid: unknown, endpoint: string): boolean {
+    const rid = String(targetRid);
+    if (this.requireRuntime().hasSelectedPeerRoute(rid)) return true;
+    for (const intent of this.peerIntents.values()) {
+      if (
+        intent.nodeRoutingId === rid ||
+        (intent.nodeRoutingId === undefined && intent.endpoint === endpoint)
+      )
+        return true;
+    }
+    return false;
+  }
+
   isPeerRouteReady(targetRid: unknown, lifecycleGeneration?: bigint): boolean {
     return this.requireRuntime().isPeerRouteReady(String(targetRid), lifecycleGeneration);
   }
 
-  async sendToNode(
+  sendToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[]
-  ): Promise<SubmitResultValue> {
-    return (await this.requireRuntime().sendToNode(
+  ): SubmitResultValue | Promise<SubmitResultValue> {
+    const submitted = this.requireRuntime().sendToNode(
       String(targetRid),
       encodeMultipartApplicationFrame(parts)
-    ))
-      ? SubmitResult.Ok
-      : SubmitResult.NotConnected;
+    );
+    return submitted instanceof Promise
+      ? submitted.then(nodeSendResult)
+      : nodeSendResult(submitted);
   }
 
   async sendInfrastructureControl(
@@ -673,24 +690,33 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   async requestInfrastructureControlFrames(
     targetRid: unknown,
     frames: readonly Uint8Array[],
-    options?: { readonly timeoutMs?: number }
+    options?: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onSubmitted?: (signal: AbortSignal) => Promise<void>;
+    }
   ): Promise<readonly Uint8Array[]> {
-    return await this.requireRuntime().requestService(
+    return requestDurableService(
+      this.requireRuntime(),
       String(targetRid),
-      frames.map((frame) => Buffer.from(frame)),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      frames,
+      performance.now() + (options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS),
+      'relocation control',
+      options?.signal,
+      options?.onSubmitted
     );
   }
 
   requestToNode(
     targetRid: unknown,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     const pending = this.requireRuntime().requestToNode(
       String(targetRid),
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted
     );
     return this.observeCompletion(pending.id, OperationKind.NodeRequest, pending.promise);
   }
@@ -705,12 +731,13 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     const pending = this.requireRuntime().requestToChannel(
       channelName,
       encodeMultipartApplicationFrame(parts),
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted
     );
     return this.observeCompletion(pending.id, OperationKind.ChannelRequest, pending.promise);
   }
@@ -1173,7 +1200,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     sourceSpotId?: string,
     metadata?: ReadonlyMap<string, string>,
-    instanceIntent = false
+    instanceIntent = false,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.InstanceSpotRequest,
@@ -1183,7 +1211,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         timeoutMs,
         sourceSpotId,
         metadata === undefined ? undefined : encodeServiceMetadataFrame(metadata),
-        instanceIntent
+        instanceIntent,
+        onAdmitted
       )
     );
   }
@@ -1328,7 +1357,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   requestToActor(
     actor: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorRequest,
@@ -1337,7 +1366,10 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         this.peerGeneration(String(actor.nodeRid)),
         actor.generation,
         encodeMultipart(parts),
-        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+        options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        undefined,
+        undefined,
+        options?.onAdmitted
       )
     );
   }
@@ -1360,7 +1392,7 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     source: ZLinkBackendActorRef,
     target: ZLinkBackendActorRef,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly timeoutMs?: number }
+    options?: { readonly timeoutMs?: number; readonly onAdmitted?: () => void }
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.ActorRequest,
@@ -1370,7 +1402,9 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         target.generation,
         encodeMultipart(parts),
         options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
-        source
+        source,
+        undefined,
+        options?.onAdmitted
       )
     );
   }
@@ -1443,7 +1477,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
     source: ServiceSpotState,
     target: ServiceDirectSpotRouteFence,
     parts: MessageLike | readonly MessageLike[],
-    timeoutMs: number
+    timeoutMs: number,
+    onAdmitted?: () => void
   ): MeshOperationId {
     return this.observeStateful(
       OperationKind.SpotRequest,
@@ -1451,7 +1486,8 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
         source.ref.spotId,
         target,
         encodeMultipart(parts),
-        timeoutMs
+        timeoutMs,
+        onAdmitted
       )
     );
   }
@@ -1475,6 +1511,11 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   }
 
   setSpotSubscription(state: ServiceSpotState, channelName: string, topicFilter: string): void {
+    if (!this.channels.has(channelName))
+      throw new ZLinkFrameworkException(
+        ZLinkFrameworkErrorKind.InvalidOperation,
+        `Spot does not participate in subscription channel '${channelName}'.`
+      );
     this.requireStateful().setSubscription(state, channelName, topicFilter);
   }
 
@@ -1719,7 +1760,11 @@ class RawServiceSpot implements ServiceSpot {
   requestToChannel(
     channelName: string,
     parts: MessageLike | readonly MessageLike[],
-    options?: { readonly flags?: number; readonly timeoutMs?: number }
+    options?: {
+      readonly flags?: number;
+      readonly timeoutMs?: number;
+      readonly onAdmitted?: () => void;
+    }
   ): MeshOperationId {
     this.requireOpen();
     return this.backend.requestToChannel(channelName, parts, options);
@@ -1755,6 +1800,7 @@ class RawServiceSpot implements ServiceSpot {
     parts: MessageLike | readonly MessageLike[],
     options?: {
       readonly timeoutMs?: number;
+      readonly onAdmitted?: () => void;
       readonly routeFence?: ServiceDirectSpotRouteFence;
       readonly entrySpot?: boolean;
     }
@@ -1773,7 +1819,8 @@ class RawServiceSpot implements ServiceSpot {
       this.state,
       routeFence,
       parts,
-      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS
+      options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+      options?.onAdmitted
     );
   }
 
@@ -1823,6 +1870,10 @@ class RawServiceSpot implements ServiceSpot {
   }
 }
 
+function nodeSendResult(submitted: boolean): SubmitResultValue {
+  return submitted ? SubmitResult.Ok : SubmitResult.NotConnected;
+}
+
 function requireDirectSpotRouteFence(
   route: ServiceDirectSpotRouteFence | undefined,
   targetNodeRid: string,
@@ -1970,7 +2021,10 @@ class RawStreamSessionService implements StreamSessionService {
     const target = this.sessionTargets.get(sessionRid);
     if (target === undefined) return false;
     const operation = this.stream.send(target as unknown as BindingRoutingId);
-    const parts = decodeMultipartBuffers(decodeApplicationPayloadView(payload).payload);
+    const parts = decodeMultipartParts(
+      decodeApplicationPayloadView(payload).payload,
+      borrowMultipartPart
+    );
     if (parts.length === 0) return false;
     const actorSlot = await serviceSessionBindingIngressPortIfRegistered(this)?.actorSlot(
       actorId,
@@ -2584,45 +2638,54 @@ function decodeApplicationEnvelope(frame: Uint8Array) {
 }
 
 function decodeMultipart(payload: Uint8Array): FrameworkMessage[] {
-  const buffers = decodeMultipartBuffers(payload);
-  const parts = new Array<FrameworkMessage>(buffers.length);
-  let materialized = 0;
-  try {
-    for (; materialized < buffers.length; materialized += 1) {
-      parts[materialized] = ZLinkBufferMessage.fromOwned(buffers[materialized]!);
-    }
-    return parts;
-  } catch (error) {
-    for (let index = 0; index < materialized; index += 1) parts[index]!.close();
-    throw error;
-  }
+  return decodeMultipartParts(payload, ZLinkBufferMessage.fromOwned, closeMultipartMessage);
 }
 
-function decodeMultipartBuffers(payload: Uint8Array): Buffer[] {
+function closeMultipartMessage(part: FrameworkMessage): void {
+  part.close();
+}
+
+function borrowMultipartPart(part: Buffer): Buffer {
+  return part;
+}
+
+function decodeMultipartParts<T>(
+  payload: Uint8Array,
+  materialize: (part: Buffer) => T,
+  release?: (part: T) => void
+): T[] {
   const bytes = Buffer.from(payload.buffer, payload.byteOffset, payload.byteLength);
   if (bytes.length < 4) throw new ServiceWireProtocolError('Truncated multipart payload.');
   const count = bytes.readUInt32BE(0);
   if (count === 0 || count > Math.floor((bytes.length - 4) / 4)) {
     throw new ServiceWireProtocolError('Invalid multipart part count.');
   }
-  const result = new Array<Buffer>(count);
+  const result = new Array<T>(count);
   let offset = 4;
-  for (let index = 0; index < count; index++) {
-    if (bytes.length - offset < 4) {
-      throw new ServiceWireProtocolError('Truncated multipart part length.');
+  let index = 0;
+  try {
+    for (; index < count; index++) {
+      if (bytes.length - offset < 4) {
+        throw new ServiceWireProtocolError('Truncated multipart part length.');
+      }
+      const length = bytes.readUInt32BE(offset);
+      offset += 4;
+      if (bytes.length - offset < length) {
+        throw new ServiceWireProtocolError('Truncated multipart part.');
+      }
+      result[index] = materialize(bytes.subarray(offset, offset + length));
+      offset += length;
     }
-    const length = bytes.readUInt32BE(offset);
-    offset += 4;
-    if (bytes.length - offset < length) {
-      throw new ServiceWireProtocolError('Truncated multipart part.');
+    if (offset !== bytes.length) {
+      throw new ServiceWireProtocolError('Multipart payload has trailing bytes.');
     }
-    result[index] = bytes.subarray(offset, offset + length);
-    offset += length;
-  }
-  if (offset !== bytes.length) {
-    throw new ServiceWireProtocolError('Multipart payload has trailing bytes.');
+    return result;
+  } catch (error) {
+    if (release !== undefined) {
+      for (let retained = 0; retained < index; retained++) release(result[retained]!);
+    }
+    throw error;
   }
-  return result;
 }
 
 function messageBytesView(value: MessageLike): Uint8Array {

package/src/runtime/backend/node/node-socket-backend-adapter.ts

@@ -208,22 +208,34 @@ export function wrapSocket<T extends { close(): void }>(
     },
     request(...args: unknown[]): unknown {
       if (hasRoutedPeer) {
-        const [routingId, payload, timeoutMs] = args as [unknown, unknown, number | undefined];
+        const [routingId, payload, timeoutMs, onAdmitted] = args as [
+          unknown,
+          unknown,
+          number | undefined,
+          (() => void) | undefined
+        ];
         return submitBindingRequest(
           (
             nativeInstance as T & { request(routingId: unknown): ZLinkBindingRequestOperation }
           ).request(toNativeRoutingId(routingId)),
           payload,
-          timeoutMs
+          timeoutMs,
+          undefined,
+          onAdmitted
         );
       }
       if (hasRequest) {
-        const [payload, timeoutMs] = args as [unknown, number | undefined];
+        const [payload, timeoutMs, onAdmitted] = args as [
+          unknown,
+          number | undefined,
+          (() => void) | undefined
+        ];
         return submitBindingRequest(
           (nativeInstance as T & { request(): ZLinkBindingRequestOperation }).request(),
           payload,
           timeoutMs,
-          adapter.receiveAdmission?.recordReceived
+          adapter.receiveAdmission?.recordReceived,
+          onAdmitted
         );
       }
       throw new TypeError('Backend request requires a DEALER or ROUTER socket.');
@@ -302,7 +314,8 @@ export function wrapSocket<T extends { close(): void }>(
       targetRid: unknown,
       targetSpot: unknown,
       payload: unknown,
-      timeoutMs?: number
+      timeoutMs?: number,
+      onAdmitted?: () => void
     ): Promise<readonly unknown[]> {
       return submitBindingRequest(
         (
@@ -311,7 +324,9 @@ export function wrapSocket<T extends { close(): void }>(
           }
         ).requestToSpot(toNativeRoutingId(targetRid), toNativeRoutingId(targetSpot)),
         payload,
-        timeoutMs
+        timeoutMs,
+        undefined,
+        onAdmitted
       );
     },
     disconnectPeer(routingId: unknown): void {

package/src/runtime/backend/raw-binding-port.ts

@@ -67,7 +67,8 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
     targetRid: string,
     parts: readonly Uint8Array[],
     timeoutMs: number,
-    recordReceived?: () => void
+    recordReceived?: () => void,
+    onAdmitted?: () => void
   ): Promise<readonly Buffer[]>;
   receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
   /** The selected route of every RID. The socket's one route observer calls it. */
@@ -77,7 +78,11 @@ export interface ZLinkRawRouterPort extends ZLinkRawSocketPort {
 export interface ZLinkRawDealerPort extends ZLinkRawSocketPort {
   setRoutingId(routingId: string): void;
   send(parts: readonly Uint8Array[]): Promise<void>;
-  request(parts: readonly Uint8Array[], timeoutMs: number): Promise<readonly Buffer[]>;
+  request(
+    parts: readonly Uint8Array[],
+    timeoutMs: number,
+    onAdmitted?: () => void
+  ): Promise<readonly Buffer[]>;
   receive(dontWait?: boolean): ZLinkRawReceivedRecord | undefined;
 }
 

package/src/runtime/backend/runtime-message.ts

@@ -17,6 +17,12 @@ export class ZLinkBufferMessage implements Message {
     return new ZLinkBufferMessage(bytes);
   }
 
+  static retainPayload(message: Message): Buffer {
+    // Binding data() Buffers retain their storage after the message handle closes.
+    // Preserve that ownership at runtime boundaries without copying the payload.
+    return message.data();
+  }
+
   data(): Buffer {
     return this.bytes;
   }

package/src/runtime/backend/runtime-values.ts

@@ -39,6 +39,7 @@ export type SubmitResult = (typeof SubmitResult)[keyof typeof SubmitResult];
 export type ZLinkBackendSendFlags = number;
 export type ZLinkBackendRecvFlags = number;
 export const ZLINK_BACKEND_SEND_NONE: ZLinkBackendSendFlags = 0;
+export const ZLINK_BACKEND_SEND_DONT_WAIT: ZLinkBackendSendFlags = 1;
 export const ZLINK_BACKEND_RECV_DONT_WAIT: ZLinkBackendRecvFlags = 1;
 
 export class ZLinkBackendResultError extends Error {