@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/streams/index.ts

@@ -48,7 +48,10 @@ import {
   registerActorSessionBindingRuntimeOwner
 } from './actor-session-binding-runtime-owner';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
-import { ZLinkBoundActorRelaySender } from './bound-actor-relay-sender';
+import {
+  ZLinkBoundActorRelaySender,
+  type ZLinkBoundActorRelaySenderOptions
+} from './bound-actor-relay-sender';
 import {
   DefaultZLinkBoundSessionResponseTarget,
   type ZLinkBoundSessionResponseTarget
@@ -140,7 +143,7 @@ export interface ZLinkStreamBindingRuntimeOptions {
     header: ZLinkStreamFrameHeader,
     payload: Message
   ) => Promise<boolean>;
-  readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
+  readonly notifyDisconnected?: ZLinkBoundActorRelaySenderOptions['notifyDisconnected'];
   readonly flowCreationEnabled?: () => boolean;
   readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
 }
@@ -459,14 +462,16 @@ export class ZLinkStreamBindingRuntime {
       actorSessionLifecycle
     );
     registerActorSessionBindingRuntimeOwner(this, {
+      prepareSessionRelocationSeal: (...args) => this.routes.prepareSessionRelocationSeal(...args),
+      acceptSessionRelocationRoute: (value, apply) =>
+        this.routes.acceptSessionRelocationRoute(value, apply),
+      clearSessionRelocationResults: () => this.routes.clearSessionRelocationResults(),
       actorSlot: async (actorId, sessionRid) =>
         (await this.routes.routeForSessionBinding(actorId, sessionRid))?.actorSlot,
-      sealRelocation: (claim, expected, signal) =>
-        this.routes.sealRelocation(claim, expected, signal),
       relocationSnapshot: (actorId, sealId) => this.routes.relocationSnapshot(actorId, sealId),
       applyRelocation: (...args) => this.routes.applyRelocation(...args),
       observeRelocationTerminal: (...args) => this.routes.observeRelocationTerminal(...args),
-      clearRelocation: (actorId, error) => this.routes.clearRelocation(actorId, error),
+      clearRelocation: (...args) => this.routes.clearRelocation(...args),
       committedRoute: async (actorId) => {
         const route = await this.routes.route(actorId);
         return route === undefined
@@ -739,9 +744,10 @@ export class ZLinkStreamBindingRuntime {
   async disconnectNativeBoundSession(
     node: ZLinkBackendActorSessionNode,
     actorRef: ActorRef,
+    timeoutMs: number,
     signal?: AbortSignal
   ): Promise<void> {
-    await this.boundSessions.disconnectNativeBoundSession(node, actorRef, signal);
+    await this.boundSessions.disconnectNativeBoundSession(node, actorRef, timeoutMs, signal);
   }
 
   async disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void> {

package/src/runtime/streams/managed-stream.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
@@ -225,7 +226,8 @@ export class ZLinkManagedStream implements ZLinkStream {
                 : (_actorId, retiredSession, replacedActor) => {
                     onBindingReplaced(replacedActor, retiredSession);
                   },
-              toStreamSessionActorAuthorityFence(authorityFence)
+              toStreamSessionActorAuthorityFence(authorityFence),
+              () => this.close()
             ),
           signal
         ),
@@ -307,7 +309,7 @@ export class ZLinkManagedStream implements ZLinkStream {
         resolved === undefined ||
         resolved.actorId !== actor.actorId ||
         resolved.generation !== actor.objectGeneration ||
-        String(resolved.nodeRid) !== String(actor.nodeRid)
+        !routingIdsEqual(resolved.nodeRid, actor.nodeRid)
       ) {
         throw createInternalFrameworkException(
           ZLinkFrameworkInternalErrorKind.ActorRouteNotFound,

package/src/runtime/streams/native-fallback-bound-session.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import {
   createInternalFrameworkException,
   ZLinkFrameworkInternalErrorKind
@@ -11,26 +12,13 @@ import {
   type ZLinkSubmitResult
 } from '../messaging/submission-result';
 import {
-  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
-  ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
   ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET,
   type ZLinkActorRoutedJoinTransport,
   type ZLinkRemoteActorPacketTarget,
   type ZLinkRemoteBoundSessionTarget
 } from '../actors';
-import {
-  encodeRemoteActorPacketRelayPayload,
-  encodeRemoteActorPacketTarget
-} from '../actors/actor-packet-relay-wire';
+import { encodeRemoteActorPacketTarget } from '../actors/actor-packet-relay-wire';
 import { encodeRemoteBoundSessionSendPayload } from '../actors/bound-session-wire';
-import { tryRequestRoutedJson } from '../actors/actor-routed-json-request';
-import {
-  ZLinkStreamCodec,
-  ZLinkStreamHeaderFlags,
-  ZLinkStreamMessageKind,
-  encodeStreamHeader,
-  type ZLinkStreamFrameHeader
-} from './protocol';
 import type { ZLinkNativeFallbackBoundSessionPort } from './stream-binding-runtime-ports';
 import type { ZLinkBackendActorSessionNode } from '../backend';
 import { resolveFrameworkPacketName } from '../messaging/packet-name';
@@ -59,37 +47,6 @@ export class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
   }
 
   async disconnect(signal?: AbortSignal): Promise<void> {
-    const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-    if (remoteTarget !== undefined) {
-      const spotKind: ZLinkSpotKind | undefined =
-        'spotKind' in remoteTarget
-          ? (remoteTarget.spotKind as ZLinkSpotKind | undefined)
-          : undefined;
-      const payload = encodeRemoteActorPacketRelayPayload({
-        actorId: this.options.actorId,
-        routerChannelId: remoteTarget.routerChannelId,
-        header: encodeStreamHeader(disconnectedFrameHeader()),
-        payload: Buffer.alloc(0)
-      });
-      const target = {
-        routerChannelId: remoteTarget.routerChannelId,
-        targetNodeRid: remoteTarget.targetNodeRid,
-        spotId: remoteTarget.spotId,
-        spotKind: spotKind ?? ZLinkSpotKind.Entry
-      };
-      if (
-        await tryRequestRoutedJson(this.options.routedTransport, target, payload, {
-          timeoutMs: this.options.requestTimeoutMs,
-          signal
-        })
-      ) {
-        return;
-      }
-      await this.options.routedTransport.sendToSpot(target, payload, {
-        packetName: ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
-      });
-      return;
-    }
     const actorRef = this.options.actorRefProvider();
     const node = this.options.nativeActorNodeProvider();
     if (
@@ -97,7 +54,12 @@ export class ZLinkNativeFallbackBoundSession implements ZLinkBoundSession {
       node !== undefined &&
       currentBindingGeneration(actorRef) !== undefined
     ) {
-      await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
+      await this.options.runtime.disconnectNativeBoundSession(
+        node,
+        actorRef,
+        this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+        signal
+      );
       return;
     }
     await this.options.runtime.disconnectBoundSession(this.options.actorId, signal);
@@ -154,42 +116,16 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
   private async executeScoped(packetName: string): Promise<ZLinkSubmitResult> {
     const localActor = this.options.localActorProvider?.() === true;
     const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-    let nativeAttempted = false;
-    if (localActor) {
-      const result = await this.options.runtime.submitLocalBoundSession(
+    if (localActor || remoteTarget === undefined) {
+      const localResult = await this.options.runtime.submitLocalBoundSession(
         this.options.actorId,
         this.message,
         packetName,
         this.selectedMetadata
       );
-      if (result.status !== ZLinkSubmitStatus.TargetNotFound) {
-        this.traceSubmitted(result, packetName);
-        return result;
-      }
-
-      // A local Actor with a concrete native owner has a direct binding path.
-      // Use that path before a routed transfer target. The transfer target is
-      // retained for actors whose current owner is remote or whose native
-      // binding is no longer available.
-      const actorRef = this.options.actorRefProvider();
-      const node = this.options.nativeActorNodeProvider();
-      const bindingGeneration = currentBindingGeneration(actorRef);
-      if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
-        nativeAttempted = true;
-        const result = await this.options.runtime.sendNativeBoundSession(
-          node,
-          actorRef,
-          this.message,
-          packetName,
-          this.selectedMetadata
-        );
-        if (result.status !== ZLinkSubmitStatus.TargetNotFound) {
-          this.traceSubmitted(result, packetName);
-          return result;
-        }
-        if (remoteTarget === undefined) {
-          return result;
-        }
+      if (localResult.status !== ZLinkSubmitStatus.TargetNotFound) {
+        this.traceSubmitted(localResult, packetName);
+        return localResult;
       }
     }
     if (remoteTarget !== undefined) {
@@ -238,25 +174,10 @@ class ZLinkNativeFallbackBoundSessionSendCall implements ZLinkBoundSessionSendCa
       this.traceSubmitted(result, packetName);
       return result;
     }
-    const localResult = await this.options.runtime.submitLocalBoundSession(
-      this.options.actorId,
-      this.message,
-      packetName,
-      this.selectedMetadata
-    );
-    if (localResult.status !== ZLinkSubmitStatus.TargetNotFound) {
-      this.traceSubmitted(localResult, packetName);
-      return localResult;
-    }
     const actorRef = this.options.actorRefProvider();
     const node = this.options.nativeActorNodeProvider();
     const bindingGeneration = currentBindingGeneration(actorRef);
-    if (
-      !nativeAttempted &&
-      actorRef !== undefined &&
-      node !== undefined &&
-      bindingGeneration !== undefined
-    ) {
+    if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
       const result = await this.options.runtime.sendNativeBoundSession(
         node,
         actorRef,
@@ -300,13 +221,3 @@ function currentBindingGeneration(actorRef: ActorRef | undefined): bigint | unde
 function positiveBindingGeneration(generation: bigint | undefined): bigint | undefined {
   return generation !== undefined && generation > 0n ? generation : undefined;
 }
-
-function disconnectedFrameHeader(): ZLinkStreamFrameHeader {
-  return {
-    kind: ZLinkStreamMessageKind.Send,
-    codec: ZLinkStreamCodec.Raw,
-    flags: ZLinkStreamHeaderFlags.None,
-    name: ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
-    metadata: new Map()
-  };
-}

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

@@ -14,7 +14,10 @@ import {
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { ZLinkManagedStream } from './managed-stream';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
-import type { ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
+import type {
+  ZLinkActorRouteCommitOptions,
+  ZLinkSessionBindingConfirmationOptions
+} from './stream-binding-runtime-ports';
 
 export interface ZLinkSessionActorCoordinatorOptions {
   readonly actorBindTimeoutMs?: number;
@@ -70,25 +73,7 @@ export class ZLinkSessionActorCoordinator {
   private async replaceBinding(
     context: DefaultZLinkSessionContext,
     actorRef: ActorRef,
-    signal?: AbortSignal,
-    confirmRemoteSessionBinding: boolean | 'send' = true,
-    releaseSeal?: { readonly sealId: string }
-  ): Promise<DefaultZLinkSessionActor> {
-    return await this.replaceBindingCore(
-      context,
-      actorRef,
-      signal,
-      confirmRemoteSessionBinding,
-      releaseSeal
-    );
-  }
-
-  private async replaceBindingCore(
-    context: DefaultZLinkSessionContext,
-    actorRef: ActorRef,
-    signal?: AbortSignal,
-    confirmRemoteSessionBinding: boolean | 'send' = true,
-    releaseSeal?: { readonly sealId: string }
+    signal?: AbortSignal
   ): Promise<DefaultZLinkSessionActor> {
     throwIfAborted(signal);
     if (actorRef.actorId.trim().length === 0) {
@@ -134,15 +119,8 @@ export class ZLinkSessionActorCoordinator {
     const sessionActor =
       reuseActor ??
       new DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
-    const sessionIdentity = String(this.actorBindingRoutingId(context));
+    const sessionIdentity = this.actorBindingRoutingId(context);
     if (previous === undefined) {
-      if (releaseSeal !== undefined) {
-        throw createInternalFrameworkException(
-          ZLinkFrameworkInternalErrorKind.ActorSessionNotBound,
-          `Actor '${actorRef.actorId}' route switch has no Session binding to release.`,
-          true
-        );
-      }
       await this.routes.bind(
         context,
         sessionActor,
@@ -151,17 +129,6 @@ export class ZLinkSessionActorCoordinator {
         sessionIdentity,
         () => sessionActor.updateRef(boundActorRef)
       );
-    } else if (releaseSeal !== undefined) {
-      await this.routes.replaceAndReleaseSeal(
-        previous,
-        context,
-        sessionActor,
-        bindingToken,
-        releaseSeal.sealId,
-        authorityFence,
-        sessionIdentity,
-        () => sessionActor.updateRef(boundActorRef)
-      );
     } else {
       await this.routes.replace(
         previous,
@@ -173,12 +140,8 @@ export class ZLinkSessionActorCoordinator {
         () => sessionActor.updateRef(boundActorRef)
       );
     }
-    if (
-      confirmRemoteSessionBinding !== false &&
-      this.options.confirmRemoteActorSessionBinding !== undefined
-    ) {
-      const waitForAcknowledgement =
-        previous === undefined && confirmRemoteSessionBinding !== 'send';
+    if (this.options.confirmRemoteActorSessionBinding !== undefined) {
+      const waitForAcknowledgement = previous === undefined;
       const confirmation = this.options.confirmRemoteActorSessionBinding(
         boundActorRef,
         this.actorBindingRoutingId(context),
@@ -334,12 +297,7 @@ export class ZLinkSessionActorCoordinator {
   async commitActorRoute(
     actorRef: ActorRef,
     signal?: AbortSignal,
-    options: {
-      readonly confirmRemoteSessionBinding?: boolean | 'send';
-      readonly releaseSeal?: {
-        readonly sealId: string;
-      };
-    } = {}
+    options: ZLinkActorRouteCommitOptions = {}
   ): Promise<void> {
     const normalizedActorRef = normalizeActorRef(
       actorRef as ActorRef & { readonly generation?: bigint | number },
@@ -350,45 +308,38 @@ export class ZLinkSessionActorCoordinator {
       const route = await this.routes.route(normalizedActorRef.actorId);
       if (route === undefined) return;
       requireSameIncarnation(route.actor.ref, normalizedActorRef);
-      if (routingIdsEqual(route.actor.ref.nodeRid, normalizedActorRef.nodeRid)) {
-        const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
-        if (
-          options.releaseSeal !== undefined &&
-          !(await this.routes.validateSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))
-        ) {
-          throw createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.ActorLocationStale,
-            `Actor '${normalizedActorRef.actorId}' route switch did not match its relocation seal.`,
-            true
-          );
-        }
-        // A location refresh never changes the route's Session binding
-        // generation; the native bind owns it.
-        route.actor.updateRef(
-          withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined)
-        );
-        if (authorityFence !== undefined) {
-          await this.routes.updateAuthorityFence(normalizedActorRef.actorId, authorityFence);
-        }
-        if (
-          options.releaseSeal !== undefined &&
-          !(await this.routes.abortSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))
-        ) {
-          throw createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.ActorLocationStale,
-            `Actor '${normalizedActorRef.actorId}' route switch lost its relocation seal.`,
-            true
-          );
-        }
-        return;
-      }
-      await this.replaceBinding(
-        route.context,
+      const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
+      // Relocation changes only the Actor route of this physical binding.
+      // Publish the ref and authority together in the binding registry's turn;
+      // a native bind would issue a different binding generation.
+      const boundActorRef = withBindingGeneration(
         normalizedActorRef,
-        signal,
-        options.confirmRemoteSessionBinding,
-        options.releaseSeal
+        bindingGenerationOf(route.actor.ref),
+        undefined
       );
+      const commitActor = () => route.actor.updateRef(boundActorRef);
+      if (options.releaseSeal !== undefined) {
+        await this.routes.replaceAndReleaseSeal(
+          route,
+          route.context,
+          route.actor,
+          route.bindingToken,
+          options.releaseSeal.sealId,
+          authorityFence,
+          route.sessionIdentity,
+          commitActor
+        );
+      } else {
+        await this.routes.replace(
+          route,
+          route.context,
+          route.actor,
+          route.bindingToken,
+          authorityFence,
+          route.sessionIdentity,
+          commitActor
+        );
+      }
     });
   }
 

package/src/runtime/streams/stream-binding-runtime-ports.ts

@@ -39,15 +39,8 @@ export interface ZLinkStreamActorLifecyclePort {
 
 export interface ZLinkActorRouteCommitOptions {
   /**
-   * Relocation already carries the binding identity to the target actor. The
-   * follow-up confirmation can use a one-way route submission because a
-   * request/ACK would create a nested route request while the Session
-   * ownership command is being dispatched.
-   */
-  readonly confirmRemoteSessionBinding?: boolean | 'send';
-  /**
-   * Command 44 keeps ingress sealed while the native route is prepared, then
-   * publishes the new route and releases this exact seal in one owner turn.
+   * Command 44 publishes the Actor route of the existing binding and releases
+   * this exact seal in one owner turn.
    */
   readonly releaseSeal?: {
     readonly sealId: string;
@@ -143,6 +136,7 @@ export interface ZLinkNativeFallbackBoundSessionPort {
   disconnectNativeBoundSession(
     node: ZLinkBackendActorSessionNode,
     actorRef: ActorRef,
+    timeoutMs: number,
     signal?: AbortSignal
   ): Promise<void>;
   disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;

package/src/runtime/streams/stream-session-runtime.ts

@@ -9,7 +9,7 @@ import {
   ZLinkDispatchMessageKind,
   ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
-import { throwIfAborted } from '../abort';
+import { isPromiseLike, throwIfAborted } from '../abort';
 import { type ZLinkApplicationWorkClaim, shouldCompactBackingArray } from '../admission';
 
 import {
@@ -95,29 +95,6 @@ const systemLivenessClock: ZLinkStreamLivenessClock = {
   clearTimer: (timer) => clearTimeout(timer as ReturnType<typeof setTimeout>)
 };
 
-class ZLinkStreamReceiveWake {
-  private pending?: Promise<void>;
-  private resolvePending?: () => void;
-  private readonly finish = (): void => {
-    const resolve = this.resolvePending;
-    this.pending = undefined;
-    this.resolvePending = undefined;
-    resolve?.();
-  };
-
-  wait(): Promise<void> {
-    if (this.pending !== undefined) return this.pending;
-    this.pending = new Promise<void>((resolve) => {
-      this.resolvePending = resolve;
-    });
-    return this.pending;
-  }
-
-  wake(): void {
-    this.finish();
-  }
-}
-
 export interface ZLinkStreamSessionContextFactory {
   createSessionContext(
     stream: ZLinkManagedStream,
@@ -928,7 +905,7 @@ export class ZLinkStreamSessionNodeRuntime {
   private readonly receiveAbortController = new AbortController();
   private receiveLoop: Promise<void> | undefined;
   private monitorLoop: Promise<void> | undefined;
-  private readonly receiveWake = new ZLinkStreamReceiveWake();
+  private receiveWake: AbortController | undefined;
   private receiveWorkSinceYield = 0;
   constructor(
     private readonly options: ZLinkStreamSessionNodeRuntimeOptions & ZLinkStreamLivenessOptions
@@ -1455,14 +1432,20 @@ export class ZLinkStreamSessionNodeRuntime {
   }
 
   private async waitReceiveLoopWake(signal: AbortSignal): Promise<void> {
-    await Promise.race([
-      this.options.readablePoller.waitForReadable(signal),
-      this.receiveWake.wait()
-    ]);
+    const wake = new AbortController();
+    this.receiveWake = wake;
+    try {
+      // Readiness, internal wake and shutdown share one cancellable wait;
+      // no losing Promise retains reactions across receive cycles.
+      await this.options.readablePoller.waitForReadable(AbortSignal.any([signal, wake.signal]));
+    } finally {
+      wake.abort();
+      this.receiveWake = undefined;
+    }
   }
 
   private wakeReceiveLoop(): void {
-    this.receiveWake.wake();
+    this.receiveWake?.abort();
   }
 
   private getOrCreateSession(routingId: unknown): ZLinkStreamSessionRuntime | undefined {
@@ -1511,10 +1494,6 @@ function streamMonitorHasEndpoint(event: ZLinkBackendSocketMonitorEvent): boolea
   return endpoint.localAddr !== undefined || endpoint.remoteAddr !== undefined;
 }
 
-function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
-  return typeof (value as { then?: unknown }).then === 'function';
-}
-
 function normalizeStreamCloseReason(reason: string): string {
   switch (reason) {
     case 'client_close':

package/src/runtime/workers/index.ts

@@ -503,7 +503,7 @@ export class DefaultZLinkWorkerCall<T> implements ZLinkWorkerCall<T> {
   yield(signal?: AbortSignal): Promise<T> {
     const turn = requireZLinkYieldTurn(this.turn);
     const pending = this.begin(signal);
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 
   private begin(signal?: AbortSignal): Promise<T> {