@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -1,25 +1,47 @@
-import { AsyncResource } from 'node:async_hooks';
 import {
   ZLinkFrameworkErrorKind,
   ZLinkFrameworkException
 } from '../../contracts/Errors/ZLinkFrameworkException';
 import { zlinkDefaultLocationOptions } from '../../contracts/Locations/Options';
 import { createAbortError, throwIfAborted } from '../abort';
-import { ZLinkStateLane } from '../execution/state-lane';
+import { startOutsideStateLane, ZLinkStateLane } from '../execution/state-lane';
+import type { RoutingId } from '../../contracts';
+import { routingIdsEqual } from '../routing-id';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException
 } from '../framework-errors-internal';
+import {
+  encodeSessionRelocationSeal,
+  encodeSessionRelocationRoute,
+  type ServiceSessionRelocationRoute,
+  serviceSessionRelocationIdentityKey,
+  type ServiceSessionRelocationSeal,
+  type ServiceSessionRelocationSealed
+} from '../foundation/service-stateful-wire-codec';
+import { ServiceWireProtocolError } from '../foundation/service-wire-m6a-codec';
+import { ZLinkRemoteBoundSessionFenceError } from '../actors/bound-session-wire';
+
+export interface ZLinkPreparedSessionRelocationSeal {
+  readonly response: ServiceSessionRelocationSealed;
+  readonly ready: Promise<void>;
+}
+
+interface SessionRelocationResult extends ZLinkPreparedSessionRelocationSeal {
+  readonly key: string;
+  readonly fingerprint: string;
+  readonly seal?: ZLinkActorSessionRelocationState;
+}
+
 export const DEFAULT_TERMINAL_RELOCATION_CAPACITY = 4096;
 
-const detachedStateLaneResource = new AsyncResource('zlink:actor-session-binding-registry');
 export interface ZLinkActorSessionBindingActor {
   readonly actorId: string;
   readonly ref: { readonly actorId: string; readonly bindingGeneration?: bigint };
 }
 
 export interface ZLinkActorSessionBindingContext<TActor extends ZLinkActorSessionBindingActor> {
-  readonly routingId?: unknown;
+  readonly routingId?: RoutingId;
   readonly actorSlotControls?: {
     enqueueBound(actorSlot: number, actorId: string): Promise<void>;
     enqueueUnbound(actorSlot: number): Promise<void>;
@@ -36,9 +58,10 @@ export interface ZLinkActorSessionRoute<
   readonly actor: TActor;
   readonly bindingToken: string;
   readonly actorSlot?: number;
-  readonly sessionIdentity?: string;
+  readonly sessionIdentity?: RoutingId;
   readonly activeFrames: ZLinkActorSessionActiveFrames;
   sealId?: string;
+  sessionRelocationResult?: SessionRelocationResult;
   authorityFence?: ZLinkActorSessionAuthorityFence;
 }
 
@@ -46,8 +69,8 @@ export interface ZLinkActorSessionRelocationClaim {
   readonly actorId: string;
   readonly actorGeneration: bigint;
   readonly bindingGeneration: bigint;
-  readonly sessionIdentity?: string;
-  readonly actorNodeRid?: string;
+  readonly sessionIdentity?: RoutingId;
+  readonly actorNodeRid?: RoutingId;
   readonly actorNodeGeneration?: bigint;
   readonly sealId: string;
 }
@@ -88,8 +111,8 @@ interface ZLinkActorSessionRelocationState {
   readonly actorId: string;
   readonly actorGeneration: bigint;
   readonly bindingGeneration: bigint;
-  readonly sessionIdentity?: string;
-  readonly actorNodeRid?: string;
+  readonly sessionIdentity?: RoutingId;
+  readonly actorNodeRid?: RoutingId;
   readonly actorNodeGeneration?: bigint;
   readonly sealId: string;
   phase: 'sealed' | 'applying' | 'applied' | 'terminal';
@@ -143,6 +166,13 @@ export class ZLinkActorSessionBindingRegistry<
   >();
   private readonly activeFrameWaiters = new Map<string, Set<ZLinkActorSessionActiveFrameWaiter>>();
   private readonly relocations = new Map<string, ZLinkActorSessionRelocationQueue>();
+  private readonly absentSessionRelocationResults = new Map<
+    string,
+    {
+      readonly result: SessionRelocationResult;
+      readonly expiry: ReturnType<typeof setTimeout>;
+    }
+  >();
   private readonly terminalRelocations = new Map<ZLinkActorSessionRelocationState, true>();
 
   constructor(
@@ -170,7 +200,7 @@ export class ZLinkActorSessionBindingRegistry<
     actor: TActor,
     bindingToken: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string,
+    sessionIdentity?: RoutingId,
     commitActor?: () => void
   ): Promise<void> {
     await this.lane.run(() =>
@@ -192,7 +222,7 @@ export class ZLinkActorSessionBindingRegistry<
     actor: TActor,
     bindingToken: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string,
+    sessionIdentity?: RoutingId,
     commitActor?: () => void
   ): void {
     const current = this.routes.get(actor.actorId);
@@ -204,29 +234,29 @@ export class ZLinkActorSessionBindingRegistry<
       );
     }
 
+    const currentSessionIdentity = sessionIdentity ?? sessionIdentityFromContext(context);
     const sameBinding =
       previous !== undefined &&
-      previous.context === context &&
-      previous.bindingToken === bindingToken;
+      previous.bindingToken === bindingToken &&
+      (previous.context === context ||
+        (previous.sessionIdentity !== undefined &&
+          currentSessionIdentity !== undefined &&
+          routingIdsEqual(previous.sessionIdentity, currentSessionIdentity)));
     const actorSlot = sameBinding ? previous.actorSlot : this.issueActorSlot(context);
     commitActor?.();
     context.bindLocal(actor, bindingToken, actorSlot);
 
     try {
       if (previous !== undefined && !sameBinding) {
-        this.routes.delete(actor.actorId);
-        previous.context.unbindLocal(actor.actorId, previous.bindingToken);
-        if (previous.actorSlot !== undefined) {
-          let unbound: Promise<void> | undefined;
-          try {
-            unbound = previous.context.actorSlotControls?.enqueueUnbound(previous.actorSlot);
-          } catch (error) {
-            unbound = Promise.reject(error);
-          }
-          void unbound?.catch((error) =>
-            this.errorSink?.()?.reportRuntimeTaskException('retired session actor unbound', error)
-          );
-        }
+        const unbound = this.unbindCore(
+          actor.actorId,
+          previous.context,
+          previous.bindingToken,
+          ZLinkActorSessionBindingTermination.BindingEnd
+        );
+        void unbound?.catch((error) =>
+          this.errorSink?.()?.reportRuntimeTaskException('retired session actor unbound', error)
+        );
       }
 
       if (!sameBinding && actorSlot !== undefined) {
@@ -254,15 +284,19 @@ export class ZLinkActorSessionBindingRegistry<
       throw error;
     }
 
+    const bindingState = sameBinding ? previous : undefined;
     this.routes.set(actor.actorId, {
       context,
       actor,
       bindingToken,
       actorSlot,
-      sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
+      sessionIdentity: currentSessionIdentity,
+      // Accepted frames retain their completion fence across route replacement;
+      // the successor's seal must still drain them (Session binding §8.1).
       activeFrames: previous?.activeFrames ?? { count: 0, requests: new Set() },
-      sealId: previous?.sealId,
-      authorityFence: authorityFence ?? previous?.authorityFence
+      sealId: bindingState?.sealId,
+      sessionRelocationResult: bindingState?.sessionRelocationResult,
+      authorityFence: authorityFence ?? bindingState?.authorityFence
     });
   }
 
@@ -285,7 +319,7 @@ export class ZLinkActorSessionBindingRegistry<
     actor: TActor,
     bindingToken: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string,
+    sessionIdentity?: RoutingId,
     commitActor?: () => void
   ): Promise<void> {
     await this.lane.run(() =>
@@ -308,7 +342,7 @@ export class ZLinkActorSessionBindingRegistry<
     bindingToken: string,
     sealId: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string,
+    sessionIdentity?: RoutingId,
     commitActor?: () => void
   ): Promise<void> {
     await this.lane.run(() =>
@@ -332,7 +366,7 @@ export class ZLinkActorSessionBindingRegistry<
     bindingToken: string,
     sealId: string,
     authorityFence?: ZLinkActorSessionAuthorityFence,
-    sessionIdentity?: string,
+    sessionIdentity?: RoutingId,
     commitActor?: () => void
   ): void {
     if (previous.sealId !== sealId) {
@@ -378,13 +412,13 @@ export class ZLinkActorSessionBindingRegistry<
   /** Selects the route only when it is the exact Session binding (§8.1 validation values). */
   async routeForSessionBinding(
     actorId: string,
-    sessionRid: string,
+    sessionRid: RoutingId,
     bindingGeneration?: bigint
   ): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined> {
     return await this.lane.run(() => {
       const route = this.routeCore(actorId);
       const generation = route?.actor.ref.bindingGeneration;
-      return route?.sessionIdentity === sessionRid &&
+      return routingIdsEqual(route?.sessionIdentity, sessionRid) &&
         (bindingGeneration === undefined || generation === bindingGeneration)
         ? route
         : undefined;
@@ -455,7 +489,11 @@ export class ZLinkActorSessionBindingRegistry<
       termination === ZLinkActorSessionBindingTermination.BindingEnd &&
       route.actorSlot !== undefined
     ) {
-      return context.actorSlotControls?.enqueueUnbound(route.actorSlot);
+      try {
+        return context.actorSlotControls?.enqueueUnbound(route.actorSlot);
+      } catch (error) {
+        return Promise.reject(error);
+      }
     }
     return undefined;
   }
@@ -778,6 +816,145 @@ export class ZLinkActorSessionBindingRegistry<
     await this.waitForActiveFrames(actorId, signal);
   }
 
+  async prepareSessionRelocationSeal(
+    value: ServiceSessionRelocationSeal,
+    signal?: AbortSignal
+  ): Promise<ZLinkPreparedSessionRelocationSeal | undefined> {
+    for (;;) {
+      const step = await this.lane.run(() => this.prepareSessionRelocationSealCore(value, signal));
+      if (step === undefined || !('predecessor' in step)) return step;
+      await waitForSessionRelocation(step.predecessor, signal);
+    }
+  }
+
+  private prepareSessionRelocationSealCore(
+    value: ServiceSessionRelocationSeal,
+    signal?: AbortSignal
+  ): ZLinkPreparedSessionRelocationSeal | { readonly predecessor: Promise<void> } | undefined {
+    const actorId = value.actor.actor.actorId;
+    const key = serviceSessionRelocationIdentityKey(value);
+    const fingerprint = encodeSessionRelocationSeal(value).toString('base64');
+    const route = this.routes.get(actorId);
+    const bindingResult = route?.sessionRelocationResult;
+    const recorded =
+      this.absentSessionRelocationResults.get(key)?.result ??
+      (bindingResult?.key === key ? bindingResult : undefined);
+    if (recorded !== undefined) {
+      if (recorded.fingerprint !== fingerprint) {
+        throw new ServiceWireProtocolError(
+          `Session relocation '${key}' repeated command 42 with different bytes.`
+        );
+      }
+      if (recorded.seal?.phase === 'terminal') {
+        console.warn(`late_session_relocation_seal session=${value.session.sessionRid}`);
+        return undefined;
+      }
+      return recorded;
+    }
+    throwIfAborted(signal);
+    const response: ServiceSessionRelocationSealed = {
+      relocation: value.relocation,
+      coordinator: value.coordinator,
+      actor: value.actor,
+      session: value.session,
+      sealResult: route === undefined ? 'bindingAbsent' : 'sealed'
+    };
+    if (route === undefined) {
+      const result: SessionRelocationResult = {
+        key,
+        fingerprint,
+        response,
+        ready: Promise.resolve()
+      };
+      const expiry = startOutsideStateLane(() =>
+        setTimeout(() => {
+          void (async () => {
+            await this.lane.run(() => this.absentSessionRelocationResults.delete(key));
+          })().catch((error) =>
+            this.errorSink?.()?.reportRuntimeTaskException(
+              'session relocation result expiry',
+              error
+            )
+          );
+        }, this.sealWaitTimeoutMs)
+      );
+      expiry.unref();
+      this.absentSessionRelocationResults.set(key, { result, expiry });
+      return result;
+    }
+    const expected = {
+      objectGeneration: value.actor.actor.generation,
+      bindingGeneration: value.session.bindingGeneration
+    };
+    if (
+      !routingIdsEqual(route.sessionIdentity, value.session.sessionRid) ||
+      !routeMatchesFence(route, expected) ||
+      (route.authorityFence !== undefined &&
+        value.actor.ownerLeaseGeneration < route.authorityFence.ownerLeaseGeneration) ||
+      (route.sealId !== undefined && route.sealId !== key)
+    ) {
+      throw new ZLinkRemoteBoundSessionFenceError(
+        `Actor '${actorId}' command 42 was fenced by its exact Session route.`
+      );
+    }
+    const step = this.prepareRelocationSeal(
+      {
+        actorId,
+        actorGeneration: value.actor.actor.generation,
+        bindingGeneration: value.session.bindingGeneration,
+        sessionIdentity: value.session.sessionRid,
+        actorNodeRid: value.actor.actor.nodeRid,
+        actorNodeGeneration: value.actor.targetNodeGeneration,
+        sealId: key
+      },
+      expected,
+      signal
+    );
+    if (step.kind === 'predecessor') return { predecessor: step.wait };
+    const result: SessionRelocationResult = {
+      key,
+      fingerprint,
+      response,
+      ready: step.wait,
+      seal: this.relocations.get(actorId)!.seals.get(key)!
+    };
+    route.sessionRelocationResult = result;
+    return result;
+  }
+
+  async acceptSessionRelocationRoute(
+    value: ServiceSessionRelocationRoute,
+    apply: () => Promise<void>
+  ): Promise<boolean> {
+    const key = serviceSessionRelocationIdentityKey(value);
+    const fingerprint = encodeSessionRelocationRoute(value).toString('base64');
+    const prepared = await this.lane.run(() => {
+      if (this.absentSessionRelocationResults.has(key)) return undefined;
+      const result = this.routes.get(value.actor.actorId)?.sessionRelocationResult;
+      if (result?.key !== key || result.seal === undefined) return undefined;
+      const seal = result.seal;
+      if (seal.applyFingerprint !== undefined && seal.applyFingerprint !== fingerprint) {
+        throw new ServiceWireProtocolError(
+          `Session relocation '${key}' repeated command 44 with different bytes.`
+        );
+      }
+      if (seal.phase === 'terminal') return undefined;
+      return this.prepareRelocationApply(value.actor.actorId, key, fingerprint);
+    });
+    if (prepared === undefined) return false;
+    await this.runRelocationApply(prepared, apply);
+    await this.observeRelocationTerminal(value.actor.actorId, key, fingerprint);
+    return true;
+  }
+
+  async clearSessionRelocationResults(): Promise<void> {
+    await this.lane.run(() => {
+      for (const { expiry } of this.absentSessionRelocationResults.values()) clearTimeout(expiry);
+      this.absentSessionRelocationResults.clear();
+      for (const route of this.routes.values()) route.sessionRelocationResult = undefined;
+    });
+  }
+
   async sealRelocation(
     claim: ZLinkActorSessionRelocationClaim,
     expected: ZLinkActorSessionRouteFence,
@@ -869,6 +1046,15 @@ export class ZLinkActorSessionBindingRegistry<
     const prepared = await this.lane.run(() =>
       this.prepareRelocationApply(actorId, sealId, applyFingerprint)
     );
+    await this.runRelocationApply(prepared, commitOwnerTransition);
+  }
+
+  private async runRelocationApply(
+    prepared: ReturnType<
+      ZLinkActorSessionBindingRegistry<TContext, TActor>['prepareRelocationApply']
+    >,
+    commitOwnerTransition: () => Promise<void>
+  ): Promise<void> {
     if (prepared.applyPromise !== undefined) {
       await prepared.applyPromise;
       return;
@@ -997,11 +1183,14 @@ export class ZLinkActorSessionBindingRegistry<
    * single physical route's disconnect, which must not disturb a relocation
    * seal it does not own (see `clearRouteRelocation`).
    */
-  async clearRelocation(actorId: string, error: unknown): Promise<void> {
-    await this.lane.run(() => this.clearRelocationCore(actorId, error));
+  async clearRelocation(actorId: string, error: unknown, sealId?: string): Promise<void> {
+    await this.lane.run(() => this.clearRelocationCore(actorId, error, sealId));
   }
 
-  private clearRelocationCore(actorId: string, error: unknown): void {
+  private clearRelocationCore(actorId: string, error: unknown, sealId?: string): void {
+    const result = this.routes.get(actorId)?.sessionRelocationResult;
+    if (sealId !== undefined && (result?.key !== sealId || result.seal?.phase === 'terminal'))
+      return;
     const queue = this.relocations.get(actorId);
     if (queue === undefined) return;
     this.rejectSealWaiters(
@@ -1018,7 +1207,8 @@ export class ZLinkActorSessionBindingRegistry<
     this.relocations.delete(actorId);
     for (const state of queue.seals.values()) {
       this.terminalRelocations.delete(state);
-      if (state.phase !== 'terminal') state.resolveTerminal();
+      state.phase = 'terminal';
+      state.resolveTerminal();
     }
   }
 
@@ -1044,7 +1234,7 @@ export class ZLinkActorSessionBindingRegistry<
     const ownsActiveSeal =
       activeState !== undefined &&
       activeState.phase !== 'terminal' &&
-      activeState.sessionIdentity === route.sessionIdentity;
+      routingIdsEqual(activeState.sessionIdentity, route.sessionIdentity);
     if (!ownsActiveSeal) {
       // Nothing this exact route still holds open — leave terminal
       // retention and any other Session's active seal untouched.
@@ -1054,6 +1244,7 @@ export class ZLinkActorSessionBindingRegistry<
     queue.activeSealId = undefined;
     queue.seals.delete(activeSealId!);
     this.terminalRelocations.delete(activeState);
+    activeState.phase = 'terminal';
     activeState.resolveTerminal();
     this.deleteEmptyRelocationQueue(queue);
   }
@@ -1070,21 +1261,6 @@ export class ZLinkActorSessionBindingRegistry<
     return true;
   }
 
-  async updateAuthorityFence(
-    actorId: string,
-    authorityFence: ZLinkActorSessionAuthorityFence
-  ): Promise<void> {
-    await this.lane.run(() => this.updateAuthorityFenceCore(actorId, authorityFence));
-  }
-
-  private updateAuthorityFenceCore(
-    actorId: string,
-    authorityFence: ZLinkActorSessionAuthorityFence
-  ): void {
-    const route = this.requireRouteCore(actorId);
-    route.authorityFence = authorityFence;
-  }
-
   async validateSeal(actorId: string, sealId: string): Promise<boolean> {
     return await this.lane.run(() => this.validateSealCore(actorId, sealId));
   }
@@ -1356,8 +1532,8 @@ function assertRelocationClaim(
   if (
     state.actorGeneration !== claim.actorGeneration ||
     state.bindingGeneration !== claim.bindingGeneration ||
-    state.sessionIdentity !== claim.sessionIdentity ||
-    state.actorNodeRid !== claim.actorNodeRid ||
+    !routingIdsEqual(state.sessionIdentity, claim.sessionIdentity) ||
+    !routingIdsEqual(state.actorNodeRid, claim.actorNodeRid) ||
     state.actorNodeGeneration !== claim.actorNodeGeneration
   ) {
     throw createInternalFrameworkException(
@@ -1368,10 +1544,6 @@ function assertRelocationClaim(
   }
 }
 
-function startOutsideStateLane<T>(work: () => T): T {
-  return detachedStateLaneResource.runInAsyncScope(work);
-}
-
 function assertSuccessorSessionIdentity(
   predecessor: ZLinkActorSessionRelocationState,
   successor: ZLinkActorSessionRelocationClaim
@@ -1379,7 +1551,7 @@ function assertSuccessorSessionIdentity(
   if (
     predecessor.actorGeneration !== successor.actorGeneration ||
     predecessor.bindingGeneration !== successor.bindingGeneration ||
-    predecessor.sessionIdentity !== successor.sessionIdentity
+    !routingIdsEqual(predecessor.sessionIdentity, successor.sessionIdentity)
   ) {
     throw createInternalFrameworkException(
       ZLinkFrameworkInternalErrorKind.ActorLocationStale,
@@ -1415,8 +1587,8 @@ function routeMatchesFence<
 function sessionIdentityFromContext<
   TActor extends ZLinkActorSessionBindingActor,
   TContext extends ZLinkActorSessionBindingContext<TActor>
->(context: TContext): string | undefined {
-  return context.routingId === undefined ? undefined : String(context.routingId);
+>(context: TContext): RoutingId | undefined {
+  return context.routingId;
 }
 
 function waitForSessionRelocation(operation: Promise<void>, signal?: AbortSignal): Promise<void> {

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

@@ -1,18 +1,26 @@
+import type { RoutingId } from '../../contracts';
+import type {
+  ServiceSessionRelocationSeal,
+  ServiceSessionRelocationRoute
+} from '../foundation/service-stateful-wire-codec';
 import type { ActorRef } from '../../contracts';
 import type {
   ZLinkActorSessionAuthorityFence,
-  ZLinkActorSessionRelocationClaim,
   ZLinkActorSessionRelocationSnapshot,
-  ZLinkActorSessionRouteFence
+  ZLinkPreparedSessionRelocationSeal
 } from './actor-session-binding-registry';
 
 export interface ZLinkActorSessionBindingRuntimeOwner {
-  actorSlot(actorId: string, sessionRid: string): Promise<number | undefined>;
-  sealRelocation(
-    claim: ZLinkActorSessionRelocationClaim,
-    expected: ZLinkActorSessionRouteFence,
+  prepareSessionRelocationSeal(
+    value: ServiceSessionRelocationSeal,
     signal?: AbortSignal
-  ): Promise<void>;
+  ): Promise<ZLinkPreparedSessionRelocationSeal | undefined>;
+  acceptSessionRelocationRoute(
+    value: ServiceSessionRelocationRoute,
+    apply: () => Promise<void>
+  ): Promise<boolean>;
+  clearSessionRelocationResults(): Promise<void>;
+  actorSlot(actorId: string, sessionRid: RoutingId): Promise<number | undefined>;
   relocationSnapshot(
     actorId: string,
     sealId: string
@@ -28,7 +36,7 @@ export interface ZLinkActorSessionBindingRuntimeOwner {
     sealId: string,
     applyFingerprint: string
   ): Promise<void>;
-  clearRelocation(actorId: string, error: unknown): Promise<void>;
+  clearRelocation(actorId: string, error: unknown, sealId?: string): Promise<void>;
   committedRoute(actorId: string): Promise<
     | {
         readonly actor: ActorRef;

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

@@ -23,6 +23,7 @@ import {
 } from './protocol';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
 import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+import type { ServiceStreamSessionBinding } from '../foundation/service-runtime-contracts';
 export const DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS = 2000;
 
 export interface ZLinkBoundActorRelaySenderOptions {
@@ -34,7 +35,11 @@ export interface ZLinkBoundActorRelaySenderOptions {
     header: ZLinkStreamFrameHeader,
     payload: Message
   ) => Promise<boolean>;
-  readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
+  readonly notifyDisconnected?: (
+    actor: ZLinkSessionActor,
+    signal?: AbortSignal,
+    binding?: ServiceStreamSessionBinding
+  ) => Promise<void>;
 }
 
 export class ZLinkBoundActorRelaySender {
@@ -246,21 +251,25 @@ export class ZLinkBoundActorRelaySender {
     const detached = await this.lifecycle.run(actor.actorId, async () => {
       await this.routes.requireCurrentToken(actor.actorId, actor.bindingToken);
       const route = await this.routes.requireRoute(actor.actorId);
+      const binding =
+        route.context.stream instanceof ZLinkManagedStream
+          ? route.context.stream.actorBinding(actor.actorId)
+          : undefined;
       await this.routes.unbind(actor.actorId, route.context, actor.bindingToken);
-      return route;
+      return { route, binding };
     });
     if (
       unbindNative &&
-      detached.bindingToken === actor.bindingToken &&
-      detached.context.stream instanceof ZLinkManagedStream
+      detached.route.bindingToken === actor.bindingToken &&
+      detached.route.context.stream instanceof ZLinkManagedStream
     ) {
-      await detached.context.stream.unbindActor(
+      await detached.route.context.stream.unbindActor(
         actor.actorId,
         this.options.actorBindTimeoutMs ?? DEFAULT_RELAY_ACTOR_BIND_TIMEOUT_MS,
         signal
       );
     }
-    await this.options.notifyDisconnected?.(actor, signal);
+    await this.options.notifyDisconnected?.(actor, signal, detached.binding);
   }
 
   async notifyPhysicalDisconnect(context: DefaultZLinkSessionContext): Promise<void> {
@@ -281,20 +290,25 @@ export class ZLinkBoundActorRelaySender {
           // 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.
+          const binding =
+            context.stream instanceof ZLinkManagedStream
+              ? context.stream.actorBinding(actor.actorId)
+              : undefined;
           await this.routes.unbind(
             actor.actorId,
             context,
             actor.bindingToken,
             ZLinkActorSessionBindingTermination.PhysicalDisconnect
           );
-          return true;
+          return { binding };
         });
-        if (!detached) return;
+        if (detached === false) return;
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeoutMs);
         try {
           await Promise.race([
-            this.options.notifyDisconnected?.(actor, controller.signal) ?? Promise.resolve(),
+            this.options.notifyDisconnected?.(actor, controller.signal, detached.binding) ??
+              Promise.resolve(),
             new Promise<never>((_, reject) => {
               controller.signal.addEventListener(
                 'abort',

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

@@ -279,13 +279,14 @@ export class ZLinkBoundSessionService {
   async disconnectNativeBoundSession(
     node: ZLinkBackendActorSessionNode,
     actorRef: ActorRef,
+    timeoutMs: number,
     signal?: AbortSignal
   ): Promise<void> {
     throwIfAborted(signal);
     await node.closeActorBoundSession(
-      actorRef as unknown as ZLinkBackendActorRef,
+      toBoundSessionSendActorRef(actorRef),
       requireBoundSessionGeneration(actorRef),
-      0,
+      timeoutMs,
       signal
     );
   }
@@ -293,14 +294,10 @@ export class ZLinkBoundSessionService {
   async disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void> {
     throwIfAborted(signal);
     const route = await this.routes.requireRoute(actorId);
-    try {
-      await this.requireTransport().disconnect(actorId, {
-        bindingToken: route.bindingToken,
-        signal
-      });
-    } finally {
-      await this.routes.unbind(actorId, route.context, route.bindingToken);
-    }
+    await this.requireTransport().disconnect(actorId, {
+      bindingToken: route.bindingToken,
+      signal
+    });
   }
 
   /**