@zlink-systems/framework 0.21.0 → 0.23.0

package/src/runtime/streams/actor-session-binding-runtime-owner.ts

@@ -13,6 +13,7 @@ import type {
 } from './actor-session-binding-registry';
 
 export interface ZLinkActorSessionBindingRuntimeOwner {
+  actorSlot(actorId: string, sessionRid: string): Promise<number | undefined>;
   sealRelocation(
     claim: ZLinkActorSessionRelocationClaim,
     expected: ZLinkActorSessionRouteFence,
@@ -46,10 +47,13 @@ export interface ZLinkActorSessionBindingRuntimeOwner {
     applyFingerprint: string
   ): Promise<void>;
   clearRelocation(actorId: string, error: unknown): Promise<void>;
-  committedRoute(actorId: string): Promise<{
-    readonly actor: ActorRef;
-    readonly authorityFence?: ZLinkActorSessionAuthorityFence;
-  } | undefined>;
+  committedRoute(actorId: string): Promise<
+    | {
+        readonly actor: ActorRef;
+        readonly authorityFence?: ZLinkActorSessionAuthorityFence;
+      }
+    | undefined
+  >;
 }
 
 const owners = new WeakMap<object, ZLinkActorSessionBindingRuntimeOwner>();

package/src/runtime/streams/actor-session-lifecycle-coordinator.ts

@@ -4,7 +4,9 @@ export class ZLinkActorSessionLifecycleCoordinator {
   async run<T>(actorId: string, operation: () => Promise<T>): Promise<T> {
     const previous = this.tails.get(actorId) ?? Promise.resolve();
     let release!: () => void;
-    const current = new Promise<void>((resolve) => { release = resolve; });
+    const current = new Promise<void>((resolve) => {
+      release = resolve;
+    });
     const tail = previous.catch(() => undefined).then(() => current);
     this.tails.set(actorId, tail);
     await previous.catch(() => undefined);

package/src/runtime/streams/bound-actor-relay-sender.ts

@@ -1,12 +1,5 @@
-import type {
-  ZLinkMessage,
-  ZLinkMessageSerializer,
-  ZLinkSessionActor
-} from '../../contracts';
-import {
-  ZLinkSubmitStatus,
-  type ZLinkSubmitResult
-} from '../messaging/submission-result';
+import type { ZLinkMessage, ZLinkMessageSerializer, ZLinkSessionActor } from '../../contracts';
+import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
 import {
@@ -18,28 +11,32 @@ import {
 import { throwIfAborted } from '../abort';
 import { captureZLinkExecutionTurn } from '../execution';
 import {
-  ZLinkActorSessionBindingRegistry
+  ZLinkActorSessionBindingRegistry,
+  ZLinkActorSessionBindingTermination
 } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { ZLinkManagedStream } from './managed-stream';
-import {
-  DefaultZLinkSessionActor,
-  DefaultZLinkSessionContext
-} from './session-context';
-import {
-  ZLinkStreamFrameMessageFactory
-} from './stream-frame-factory';
+import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
 
 export interface ZLinkBoundActorRelaySenderOptions {
   readonly actorBindTimeoutMs?: number;
   readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
-  readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal) => Promise<boolean>;
+  readonly relay?: (
+    actor: ZLinkSessionActor,
+    header: ZLinkStreamFrameHeader,
+    payload: Message,
+    signal?: AbortSignal
+  ) => Promise<boolean>;
   readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
 }
 
 export class ZLinkBoundActorRelaySender {
   constructor(
-    private readonly routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>,
+    private readonly routes: ZLinkActorSessionBindingRegistry<
+      DefaultZLinkSessionContext,
+      DefaultZLinkSessionActor
+    >,
     private readonly frameMessages: ZLinkStreamFrameMessageFactory,
     private readonly options: ZLinkBoundActorRelaySenderOptions = {},
     private readonly lifecycle = new ZLinkActorSessionLifecycleCoordinator()
@@ -51,13 +48,11 @@ export class ZLinkBoundActorRelaySender {
     signal?: AbortSignal,
     dispatchHeader?: ZLinkStreamFrameHeader
   ): Promise<ZLinkSubmitResult> {
-    const header = dispatchHeader === undefined
-      ? await this.currentHeader(actor)
-      : await this.requireDispatchHeader(actor, dispatchHeader);
-    if (
-      header.kind === ZLinkStreamMessageKind.Request
-      && header.requestSeq !== undefined
-    ) {
+    const header =
+      dispatchHeader === undefined
+        ? await this.currentHeader(actor)
+        : await this.requireDispatchHeader(actor, dispatchHeader);
+    if (header.kind === ZLinkStreamMessageKind.Request && header.requestSeq !== undefined) {
       const operation = async (): Promise<ZLinkSubmitResult> => {
         const admission = await this.routes.beginAcceptedRequestFrameWhenReady(
           actor.actorId,
@@ -70,13 +65,16 @@ export class ZLinkBoundActorRelaySender {
           await admission.complete();
         }
       };
-      if (await this.routes.isSealed(actor.actorId) && captureZLinkExecutionTurn() !== undefined) {
+      if (
+        (await this.routes.isSealed(actor.actorId)) &&
+        captureZLinkExecutionTurn() !== undefined
+      ) {
         void operation().catch(() => undefined);
         return { status: ZLinkSubmitStatus.Submitted };
       }
       return await operation();
     }
-    if (await this.routes.isSealed(actor.actorId) && captureZLinkExecutionTurn() !== undefined) {
+    if ((await this.routes.isSealed(actor.actorId)) && captureZLinkExecutionTurn() !== undefined) {
       //  Spec 32:62 — a Send completes once the source outbound queue
       //  accepts it; spec 05 — infrastructure send progress must not depend
       //  on the application turn. When the CALLER IS an application turn
@@ -89,12 +87,14 @@ export class ZLinkBoundActorRelaySender {
       //  Non-turn callers (stream ingress relays) keep the waiting
       //  semantics so a held frame across a failed rebind still
       //  terminalizes to the caller.
-      void this.routes.runAcceptedFrameWhenReady(
-        actor.actorId,
-        actor.bindingToken,
-        () => this.relayAcceptedFrame(actor, payload, signal),
-        signal
-      ).catch(() => undefined);
+      void this.routes
+        .runAcceptedFrameWhenReady(
+          actor.actorId,
+          actor.bindingToken,
+          () => this.relayAcceptedFrame(actor, payload, signal),
+          signal
+        )
+        .catch(() => undefined);
       return { status: ZLinkSubmitStatus.Submitted };
     }
     return this.routes.runAcceptedFrameWhenReady(
@@ -112,7 +112,7 @@ export class ZLinkBoundActorRelaySender {
     header?: ZLinkStreamFrameHeader,
     requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined }
   ): Promise<ZLinkSubmitResult> {
-    const activeHeader = header ?? await this.currentHeader(actor);
+    const activeHeader = header ?? (await this.currentHeader(actor));
     const started = await this.lifecycle.run(actor.actorId, async () => {
       const completion = this.relayInsideLifecycle(
         actor,
@@ -122,8 +122,8 @@ export class ZLinkBoundActorRelaySender {
         requestAdmission
       );
       if (
-        activeHeader.kind === ZLinkStreamMessageKind.Request
-        && activeHeader.requestSeq !== undefined
+        activeHeader.kind === ZLinkStreamMessageKind.Request &&
+        activeHeader.requestSeq !== undefined
       ) {
         // A routed REQUEST only needs this lane while its ordered submission
         // is started. Its admission acknowledgement can depend on relocation
@@ -167,7 +167,7 @@ export class ZLinkBoundActorRelaySender {
     currentHeader?: ZLinkStreamFrameHeader,
     requestAdmission?: { beginSubmission(signal?: AbortSignal): Promise<void> | undefined }
   ): Promise<ZLinkSubmitResult> {
-    const header = currentHeader ?? await this.currentHeader(actor);
+    const header = currentHeader ?? (await this.currentHeader(actor));
     const held = requestAdmission?.beginSubmission(signal);
     if (held !== undefined) await held;
     throwIfAborted(signal);
@@ -184,7 +184,9 @@ export class ZLinkBoundActorRelaySender {
         return { status: ZLinkSubmitStatus.TargetNotFound };
       }
       const headerMessage = this.frameMessages.createBinaryMessage(encodeStreamHeader(header));
-      const framePayloadMessage = this.frameMessages.createBinaryMessage(messageToBytes(payloadMessage));
+      const framePayloadMessage = this.frameMessages.createBinaryMessage(
+        messageToBytes(payloadMessage)
+      );
       try {
         return await route.context.stream.submitBoundActor(
           actor.actorId,
@@ -216,9 +218,9 @@ export class ZLinkBoundActorRelaySender {
       return route;
     });
     if (
-      unbindNative
-      && detached.bindingToken === actor.bindingToken
-      && detached.context.stream instanceof ZLinkManagedStream
+      unbindNative &&
+      detached.bindingToken === actor.bindingToken &&
+      detached.context.stream instanceof ZLinkManagedStream
     ) {
       await detached.context.stream.unbindActor(
         actor.actorId,
@@ -237,17 +239,22 @@ export class ZLinkBoundActorRelaySender {
         const detached = await this.lifecycle.run(actor.actorId, async () => {
           const route = await this.routes.route(actor.actorId);
           if (
-            route === undefined
-            || route.context !== context
-            || route.actor !== actor
-            || route.bindingToken !== actor.bindingToken
+            route === undefined ||
+            route.context !== context ||
+            route.actor !== actor ||
+            route.bindingToken !== actor.bindingToken
           ) {
             return false;
           }
           // The transport is already closed, so remove its exact route before
           // invoking application lifecycle code. A reconnect can then install
           // a successor while this best-effort notification is in flight.
-          await this.routes.unbind(actor.actorId, context, actor.bindingToken);
+          await this.routes.unbind(
+            actor.actorId,
+            context,
+            actor.bindingToken,
+            ZLinkActorSessionBindingTermination.PhysicalDisconnect
+          );
           return true;
         });
         if (!detached) return;
@@ -259,9 +266,12 @@ export class ZLinkBoundActorRelaySender {
             new Promise<never>((_, reject) => {
               controller.signal.addEventListener(
                 'abort',
-                () => reject(new Error(
-                  `Actor '${actor.actorId}' disconnect notification exceeded ${timeoutMs} ms.`
-                )),
+                () =>
+                  reject(
+                    new Error(
+                      `Actor '${actor.actorId}' disconnect notification exceeded ${timeoutMs} ms.`
+                    )
+                  ),
                 { once: true }
               );
             })

package/src/runtime/streams/bound-session-response-target.ts

@@ -1,8 +1,8 @@
 import type { Message } from '../../contracts/Common/Message';
-import {
-  ZLinkSubmitStatus,
-  type ZLinkSubmitResult
-} from '../messaging/submission-result';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
+import { channelErrorCodeName } from '../channels/channel-envelope';
+import { ZLinkRouteDisconnectedError } from '../channels/route-disconnected-error';
+import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import { ZLinkStreamMessageKind } from './protocol';
 import type { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
 
@@ -40,7 +40,14 @@ export class DefaultZLinkBoundSessionResponseTarget implements ZLinkBoundSession
     message: unknown,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean> {
-    return this.send(ZLinkStreamMessageKind.Response, packetName, requestSeq, message, metadata, 'response');
+    return this.send(
+      ZLinkStreamMessageKind.Response,
+      packetName,
+      requestSeq,
+      message,
+      metadata,
+      'response'
+    );
   }
 
   sendError(
@@ -49,7 +56,14 @@ export class DefaultZLinkBoundSessionResponseTarget implements ZLinkBoundSession
     error: unknown,
     metadata: ReadonlyMap<string, string>
   ): Promise<boolean> {
-    return this.send(ZLinkStreamMessageKind.Error, packetName, requestSeq, boundSessionErrorPayload(error), metadata, 'error response');
+    return this.send(
+      ZLinkStreamMessageKind.Error,
+      packetName,
+      requestSeq,
+      boundSessionErrorPayload(error),
+      metadata,
+      'error response'
+    );
   }
 
   private async send(
@@ -60,7 +74,14 @@ export class DefaultZLinkBoundSessionResponseTarget implements ZLinkBoundSession
     metadata: ReadonlyMap<string, string>,
     operationName: string
   ): Promise<boolean> {
-    const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, false, requestSeq, payload);
+    const frame = this.frameMessages.createJsonFrameMessage(
+      kind,
+      packetName,
+      metadata,
+      false,
+      requestSeq,
+      payload
+    );
     try {
       const result = await this.context.stream.submitRaw(frame);
       if (result.status !== ZLinkSubmitStatus.Submitted) {
@@ -73,9 +94,18 @@ export class DefaultZLinkBoundSessionResponseTarget implements ZLinkBoundSession
   }
 }
 
-export function boundSessionErrorPayload(error: unknown): { readonly code: string; readonly message: string } {
+export function boundSessionErrorPayload(error: unknown): {
+  readonly code: string;
+  readonly message: string;
+} {
   return {
-    code: error instanceof Error ? error.constructor.name : 'RemoteError',
+    code: channelErrorCodeName(
+      error instanceof ZLinkFrameworkException
+        ? error.kind
+        : error instanceof ZLinkRouteDisconnectedError
+          ? ZLinkFrameworkErrorKind.Unavailable
+          : ZLinkFrameworkErrorKind.InternalFailure
+    ),
     message: errorMessage(error)
   };
 }

package/src/runtime/streams/bound-session-service.ts

@@ -1,10 +1,10 @@
-import { ZLinkFrameworkInternalErrorKind, createInternalFrameworkException  } from '../framework-errors-internal';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import { ZLinkBufferMessage as ZLinkBindingMessage } from '../backend/runtime-message';
 import type { ActorRef } from '../../contracts';
-import {
-  ZLinkSubmitStatus,
-  type ZLinkSubmitResult
-} from '../messaging/submission-result';
+import { ZLinkSubmitStatus, type ZLinkSubmitResult } from '../messaging/submission-result';
 import type { Message } from '../../contracts/Common/Message';
 import { throwIfAborted } from '../abort';
 import type {
@@ -23,26 +23,24 @@ import {
   ZLinkActorSessionBindingRegistry,
   type ZLinkActorSessionRoute
 } from './actor-session-binding-registry';
-import type {
-  DefaultZLinkSessionActor,
-  DefaultZLinkSessionContext
-} from './session-context';
-import {
-  boundSessionErrorPayload
-} from './bound-session-response-target';
-import {
-  ZLinkStreamFrameMessageFactory
-} from './stream-frame-factory';
-import {
-  ZLinkManagedStream
-} from './managed-stream';
+import type { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import { boundSessionErrorPayload } from './bound-session-response-target';
+import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+import { ZLinkManagedStream } from './managed-stream';
 
 const ZLINK_SEND_DONT_WAIT = 1;
 
-type ZLinkStreamActorSessionRoute = ZLinkActorSessionRoute<DefaultZLinkSessionContext, DefaultZLinkSessionActor>;
+type ZLinkStreamActorSessionRoute = ZLinkActorSessionRoute<
+  DefaultZLinkSessionContext,
+  DefaultZLinkSessionActor
+>;
 
 export interface ZLinkBoundSessionTransport {
-  send(actorId: string, message: unknown, options: ZLinkBoundSessionSendOptions): Promise<ZLinkSubmitResult>;
+  send(
+    actorId: string,
+    message: unknown,
+    options: ZLinkBoundSessionSendOptions
+  ): Promise<ZLinkSubmitResult>;
   disconnect(actorId: string, options: ZLinkBoundSessionDisconnectOptions): Promise<void>;
 }
 
@@ -66,7 +64,10 @@ export interface ZLinkBoundSessionServiceOptions {
 
 export class ZLinkBoundSessionService {
   constructor(
-    private readonly routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>,
+    private readonly routes: ZLinkActorSessionBindingRegistry<
+      DefaultZLinkSessionContext,
+      DefaultZLinkSessionActor
+    >,
     private readonly frameMessages: ZLinkStreamFrameMessageFactory,
     private readonly options: ZLinkBoundSessionServiceOptions
   ) {}
@@ -86,7 +87,9 @@ export class ZLinkBoundSessionService {
       metadata,
       false,
       undefined,
-      message
+      message,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       const result = await this.requireTransport().send(actorId, frame, {
@@ -119,7 +122,9 @@ export class ZLinkBoundSessionService {
       metadata,
       false,
       undefined,
-      message
+      message,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       throwIfAborted(signal);
@@ -300,10 +305,7 @@ export class ZLinkBoundSessionService {
     }
   }
 
-  async relayRemoteBoundSessionBind(
-    stream: ZLinkManagedStream,
-    actorRef: ActorRef
-  ): Promise<void> {
+  async relayRemoteBoundSessionBind(stream: ZLinkManagedStream, actorRef: ActorRef): Promise<void> {
     const encodedBindHeader = encodeStreamHeader({
       kind: ZLinkStreamMessageKind.Send,
       codec: ZLinkStreamCodec.Raw,
@@ -312,14 +314,16 @@ export class ZLinkBoundSessionService {
       metadata: new Map()
     });
     //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
-    const header = ZLinkBindingMessage.fromOwned(Buffer.from(
-      encodedBindHeader.buffer,
-      encodedBindHeader.byteOffset,
-      encodedBindHeader.byteLength
-    ));
+    const header = ZLinkBindingMessage.fromOwned(
+      Buffer.from(
+        encodedBindHeader.buffer,
+        encodedBindHeader.byteOffset,
+        encodedBindHeader.byteLength
+      )
+    );
     const body = ZLinkBindingMessage.fromOwned(Buffer.alloc(0));
     try {
-      if (!await stream.sendBoundActor(actorRef.actorId, [header, body], 0)) {
+      if (!(await stream.sendBoundActor(actorRef.actorId, [header, body], 0))) {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,
           `Actor '${actorRef.actorId}' remote bound session bind relay failed.`
@@ -348,7 +352,9 @@ export class ZLinkBoundSessionService {
       metadata,
       compressPayload,
       requestSeq,
-      payload
+      payload,
+      undefined,
+      this.actorSlot(route)
     );
     try {
       if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
@@ -448,6 +454,10 @@ export class ZLinkBoundSessionService {
     }
     return this.options.transport;
   }
+
+  private actorSlot(route: ZLinkStreamActorSessionRoute): number | undefined {
+    return route.actorSlot;
+  }
 }
 
 function requireBoundSessionGeneration(actorRef: ActorRef): bigint {
@@ -480,15 +490,15 @@ function boundSessionSendFence(
     readonly ownerLeaseGeneration?: bigint;
     readonly ownerNodeGeneration?: bigint;
   };
-  const ownerNodeGeneration = internal.ownerNodeGeneration
-    ?? node.actorNodeGeneration?.(backendActor);
+  const ownerNodeGeneration =
+    internal.ownerNodeGeneration ?? node.actorNodeGeneration?.(backendActor);
   if (
-    internal.ownershipGeneration === undefined
-    || internal.ownershipGeneration <= 0n
-    || internal.ownerLeaseGeneration === undefined
-    || internal.ownerLeaseGeneration <= 0n
-    || ownerNodeGeneration === undefined
-    || ownerNodeGeneration <= 0n
+    internal.ownershipGeneration === undefined ||
+    internal.ownershipGeneration <= 0n ||
+    internal.ownerLeaseGeneration === undefined ||
+    internal.ownerLeaseGeneration <= 0n ||
+    ownerNodeGeneration === undefined ||
+    ownerNodeGeneration <= 0n
   ) {
     return undefined;
   }