@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/actors/actor-join-relocation.ts

@@ -30,8 +30,11 @@ export interface ZLinkActorJoinRelocation {
     };
     /** Target's advertised relocation state chunk cap from the accepted admission reply. */
     readonly advertisedReceiveChunkLimitBytes?: number;
+    readonly deadlineAtMs?: number;
     readonly signal?: AbortSignal;
   }): Promise<{
+    /** Source-only terminal after relay readiness transferred public completion. */
+    readonly sourceCleanup?: () => Promise<void>;
     readonly actorRef: ZLinkBackendActorRef;
     readonly membershipEpoch: bigint;
     readonly spotGeneration: bigint;

package/src/runtime/actors/actor-local-native-join.ts

@@ -199,33 +199,24 @@ export class ZLinkLocalNativeActorJoin {
       );
     }
     const membershipEpoch = location.membershipEpoch + 1n;
+    const currentActor = toFrameworkActorRef(actorRef, meshName);
+    const authorityOwnerGeneration = state.locationGeneration ?? actorRef.generation;
     const commit = async (spot?: ZLinkSpot): Promise<void> => {
       throwIfAborted(signal);
-      if (target.spotKind === ZLinkSpotKind.Entry) {
-        await this.options.locationLifecycle?.notifyActorLeftSpot(
-          actorType,
-          actor.context.actorId,
-          storeSpotId,
-          spotGeneration,
-          membershipEpoch,
-          node.status().lifecycleGeneration
-        );
-      } else {
-        await this.options.locationLifecycle?.notifyActorJoinedSpot(
-          actorType,
-          actor.context.actorId,
-          meshName,
-          storeSpotId,
-          spotGeneration,
-          membershipEpoch,
-          node.status().lifecycleGeneration
-        );
-      }
+      await this.options.locationLifecycle?.commitActorMembership(
+        actorType,
+        currentActor,
+        authorityOwnerGeneration,
+        storeSpotId,
+        spotGeneration,
+        target.spotKind === ZLinkSpotKind.Entry ? ZLinkSpotKind.Entry : ZLinkSpotKind.User,
+        node.status().lifecycleGeneration
+      );
       const committedActor = node.restoreActorAuthority!(
         actor.context.actorId,
         actorType,
         actorRef.generation,
-        state.locationGeneration ?? actorRef.generation,
+        authorityOwnerGeneration,
         target.spotKind === ZLinkSpotKind.Entry ? undefined : String(target.spotId),
         spotGeneration,
         membershipEpoch
@@ -297,6 +288,7 @@ export class ZLinkLocalNativeActorJoin {
     completionOperationId: ZLinkActorJoinOperationId | undefined,
     entrySpot: boolean
   ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
+    const deadlineAtMs = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
     const actorType = state.actorType;
     if (actorType === undefined) {
       throw createInternalFrameworkException(
@@ -443,6 +435,7 @@ export class ZLinkLocalNativeActorJoin {
         target,
         relocationId,
         completionOperationId,
+        deadlineAtMs,
         ...(control.canonicalHandoffId === undefined || canonicalAdmission === undefined
           ? {}
           : {
@@ -456,11 +449,9 @@ export class ZLinkLocalNativeActorJoin {
                 },
                 requestContentType: canonicalAdmission.request.contentType,
                 request: Buffer.from(canonicalAdmission.request.payload),
-                ...(completionOperationId === undefined
+                ...(completionOperationId === undefined || control.replyContentType === undefined
                   ? {}
-                  : {
-                      replyContentType: control.replyContentType ?? ZlinkStreamContentType.Raw
-                    }),
+                  : { replyContentType: control.replyContentType }),
                 reply:
                   completionOperationId === undefined
                     ? Buffer.alloc(0)
@@ -469,7 +460,7 @@ export class ZLinkLocalNativeActorJoin {
                 expectedOwnerLeaseGeneration: actorAuthorityFence!.ownerLeaseGeneration,
                 targetNodeGeneration: target.targetNodeGeneration!,
                 targetSpotGeneration: control.location.spotGeneration,
-                targetAuthorityOwnerGeneration: actorAuthorityFence!.authorityOwnerGeneration + 1n,
+                targetAuthorityOwnerGeneration: actorAuthorityFence!.authorityOwnerGeneration,
                 targetSpotAuthorityOwnerGeneration: target.authorityOwnerGeneration ?? 1n
               }
             }),
@@ -480,6 +471,10 @@ export class ZLinkLocalNativeActorJoin {
       admission.parts[0]?.close();
       throw error;
     }
+    if (relocated.sourceCleanup !== undefined) {
+      admission.parts[0]?.close();
+      return { accepted: false, sourceCleanup: relocated.sourceCleanup };
+    }
     state.setNativeActorRef(relocated.actorRef);
     if (entrySpot) {
       state.clearJoinedSpot();

package/src/runtime/actors/actor-mailbox.ts

@@ -8,8 +8,10 @@ import {
 import { runZLinkActorExecution } from './actor-execution-context';
 import {
   bindApplicationJobPermit,
-  hasApplicationJobPermit
+  currentApplicationJobPermit,
+  runWithApplicationJobPermit
 } from '../application-jobs/application-job-queue-scope';
+import type { ApplicationJobPermitPort } from '../application-jobs/contracts';
 
 export class ZLinkActorSerialExecutor {
   private readonly scheduler: ZLinkSerialExecutionQueue;
@@ -28,10 +30,46 @@ export class ZLinkActorSerialExecutor {
   }
 
   execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {
+    const initial = currentApplicationJobPermit();
+    if (
+      initial !== undefined &&
+      workOptions?.lane !== 'lifecycle' &&
+      this.scheduler.hasPendingDurableApplication
+    ) {
+      let prepared: ApplicationJobPermitPort | undefined;
+      const cancel = (): void => {
+        prepared?.releaseAfterInternalProcessing();
+        prepared = undefined;
+      };
+      const terminal = this.scheduler.admitDurablePrefix(
+        () =>
+          runWithApplicationJobPermit(prepared!, () =>
+            runZLinkActorExecution(this.actorId, this.sourceSpotId, operation)
+          ),
+        workOptions,
+        undefined,
+        {
+          prepare: async (signal) => {
+            if (initial.reacquire === undefined) {
+              throw new Error('Durable Actor ingress requires its host permit source.');
+            }
+            prepared = await initial.reacquire(signal);
+            if (signal.aborted) {
+              cancel();
+              throw signal.reason;
+            }
+            prepared.markApplicationQueued();
+          },
+          cancel
+        }
+      );
+      initial.releaseAfterInternalProcessing();
+      return terminal;
+    }
     const boundOperation = bindApplicationJobPermit(() =>
       runZLinkActorExecution(this.actorId, this.sourceSpotId, operation)
     );
-    return hasApplicationJobPermit()
+    return initial !== undefined
       ? this.scheduler.submitPreAdmitted(boundOperation, workOptions)
       : this.scheduler.submit(boundOperation, workOptions);
   }

package/src/runtime/actors/actor-remote-joiner.ts

@@ -164,7 +164,12 @@ export class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCoordinato
     result: ZLinkActorJoinRuntimeResult<Message>,
     operationId: import('../../contracts').ZLinkActorJoinOperationId | undefined
   ): ZLinkActorJoinRuntimeResult<Message> {
-    if (operationId === undefined || this.options.sourceTransfer === undefined) return result;
+    if (
+      result.sourceCleanup !== undefined ||
+      operationId === undefined ||
+      this.options.sourceTransfer === undefined
+    )
+      return result;
     return {
       ...result,
       finalizeDeferredJoin: async () => {

package/src/runtime/actors/actor-remote-wire.ts

@@ -21,9 +21,26 @@ export interface ZLinkRemoteActorSourceLeaveTerminal {
   readonly succeeded: boolean;
 }
 
+const JSON_OBJECT_START = '{'.charCodeAt(0);
+const JSON_SPACE = ' '.charCodeAt(0);
+const JSON_TAB = '\t'.charCodeAt(0);
+const JSON_LINE_FEED = '\n'.charCodeAt(0);
+const JSON_CARRIAGE_RETURN = '\r'.charCodeAt(0);
+
 export function decodeRemoteActorSourceLeaveTerminal(
   payload: Buffer
 ): ZLinkRemoteActorSourceLeaveTerminal | undefined {
+  // A SourceLeave terminal is a JSON object. Binary channel frames and JSON
+  // primitives cannot be terminals, so do not materialize or parse them.
+  let offset = 0;
+  while (
+    payload[offset] === JSON_SPACE ||
+    payload[offset] === JSON_TAB ||
+    payload[offset] === JSON_LINE_FEED ||
+    payload[offset] === JSON_CARRIAGE_RETURN
+  )
+    offset++;
+  if (payload[offset] !== JSON_OBJECT_START) return undefined;
   let decoded: unknown;
   try {
     decoded = JSON.parse(payload.toString());

package/src/runtime/actors/actor-reply.ts

@@ -0,0 +1,42 @@
+import { encodeFrameworkPayload } from '../messaging/payload-codec';
+import {
+  decodeStreamHeader,
+  encodeStreamFrame,
+  streamCodecForContentType,
+  ZLinkStreamHeaderFlags,
+  ZLinkStreamMessageKind
+} from '../streams/protocol';
+
+/** Ordinary dispatch and relocation use the same typed Actor reply envelope. */
+export function encodeActorReply(
+  requestHeaderBytes: Uint8Array,
+  kind: ZLinkStreamMessageKind.Response | ZLinkStreamMessageKind.Error,
+  payload: unknown,
+  serializers: Parameters<typeof encodeFrameworkPayload>[1],
+  flowEnabled: boolean
+): readonly Buffer[] {
+  const requestHeader = decodeStreamHeader(requestHeaderBytes, flowEnabled);
+  const encoded =
+    kind === ZLinkStreamMessageKind.Response
+      ? encodeFrameworkPayload(payload, serializers, requestHeader.name, 'reply')
+      : encodeFrameworkPayload(payload);
+  try {
+    const frame = encodeStreamFrame(
+      {
+        kind,
+        codec: streamCodecForContentType(encoded.contentType),
+        flags: ZLinkStreamHeaderFlags.None,
+        requestSeq: requestHeader.requestSeq,
+        name: '',
+        metadata: new Map(),
+        correlationId: requestHeader.correlationId,
+        flowId: requestHeader.flowId,
+        flowOrigin: requestHeader.flowOrigin
+      },
+      encoded.message.data()
+    );
+    return [Buffer.from(frame.buffer, frame.byteOffset, frame.byteLength)];
+  } finally {
+    encoded.message.close();
+  }
+}

package/src/runtime/actors/actor-routed-join-transport.ts

@@ -19,13 +19,13 @@ export interface ZLinkActorRoutedJoinTransport {
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   submitInfrastructure?(
     routerChannelId: string,
     targetNodeRid: string,
     packetName: string | undefined,
     message: unknown
-  ): Promise<ZLinkSubmitResult>;
+  ): ZLinkSubmitResult | Promise<ZLinkSubmitResult>;
   sendToSpot(
     spotRouteTarget: ZLinkSpotRouteTarget,
     message: unknown,
@@ -34,7 +34,11 @@ export interface ZLinkActorRoutedJoinTransport {
   requestRawToSpot?(
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
   requestToSpot<TReply = unknown>(
     spotRouteTarget: ZLinkSpotRouteTarget,
@@ -43,6 +47,7 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestFromSpotToSpot?<TReply = unknown>(
@@ -53,12 +58,17 @@ export interface ZLinkActorRoutedJoinTransport {
       readonly packetName?: string;
       readonly timeoutMs?: number;
       readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
     }
   ): Promise<TReply>;
   requestRawFromSpotToSpot?(
     sourceSpot: ZLinkBackendSpot,
     spotRouteTarget: ZLinkSpotRouteTarget,
     request: Message,
-    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+    options: {
+      readonly timeoutMs?: number;
+      readonly signal?: AbortSignal;
+      readonly onAdmitted?: () => void;
+    }
   ): Promise<readonly Message[]>;
 }

package/src/runtime/actors/actor-routed-json-request.ts

@@ -7,7 +7,11 @@ export async function tryRequestRoutedJson(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  }
 ): Promise<boolean> {
   const request = transport.requestRawToSpot;
   if (request === undefined) return false;
@@ -24,7 +28,11 @@ export async function requestRoutedJsonReply<T>(
   transport: ZLinkActorRoutedJoinTransport,
   target: ZLinkSpotRouteTarget,
   payload: unknown,
-  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal },
+  options: {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onAdmitted?: () => void;
+  },
   unavailableMessage: string,
   decode: (replyParts: readonly Message[]) => T
 ): Promise<T> {

package/src/runtime/actors/actor-runtime-contracts.ts

@@ -19,6 +19,8 @@ import type { ZLinkRuntimeAdmissionGate } from '../admission';
 import type { ZLinkActivationAdmission } from '../activation-admission';
 
 export interface ZLinkActorJoinRuntimeResult<TReply> {
+  /** Relay-ready transferred completion; this continuation only releases source work. */
+  readonly sourceCleanup?: () => Promise<void>;
   readonly accepted: boolean;
   readonly actor?: import('../../contracts').ActorRef;
   readonly reply?: TReply;

package/src/runtime/actors/actor-runtime-state.ts

@@ -94,14 +94,8 @@ function sameRemoteSessionOwnerLifecycle(
     right.sessionNodeRid !== undefined &&
     left.sessionOwnerNodeGeneration !== undefined &&
     right.sessionOwnerNodeGeneration !== undefined &&
-    left.sessionOwnerId !== undefined &&
-    right.sessionOwnerId !== undefined &&
-    left.sessionOwnerLeaseGeneration !== undefined &&
-    right.sessionOwnerLeaseGeneration !== undefined &&
     routingIdsEqual(left.sessionNodeRid, right.sessionNodeRid) &&
-    left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration &&
-    left.sessionOwnerId === right.sessionOwnerId &&
-    left.sessionOwnerLeaseGeneration === right.sessionOwnerLeaseGeneration
+    left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration
   );
 }
 
@@ -495,19 +489,7 @@ export class ZLinkActorRuntimeState {
     ) {
       throw new TypeError('An installed bound Session target requires its binding identity.');
     }
-    const current = this.boundSessionValue;
-    if (current !== undefined && sameRemoteSessionOwnerLifecycle(current, target)) {
-      // A duplicate or late older command for the exact physical Session
-      // leaves the current binding; a newer generation of the same Session
-      // replaces it. A different Session in the same owner lifecycle must
-      // advance that lifecycle's generation; a late equal/lower one is stale.
-      const advances =
-        current.bindingGeneration === undefined ||
-        target.bindingGeneration > current.bindingGeneration;
-      if (!advances) return sameRemoteSessionOwner(current, target);
-    }
-    // Binding generations are scoped to a Session-owner lifecycle. A restarted
-    // owner can legitimately reset its counter below the predecessor value.
+    // The service registry accepted this identity in the Actor owner turn.
     this.boundSessionValue = boundSessionIdentity(target);
     return true;
   }

package/src/runtime/actors/actor-source-transfer.ts

@@ -1,35 +1,10 @@
-import type { ActorRef, ZLinkActor, ZLinkMessage } from '../../contracts';
+import type { ActorRef, ZLinkActor } from '../../contracts';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from './actor-handoff';
-import type { ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
-
-export interface ZLinkPreparedActorSource {
-  readonly adapterKey?: string;
-  readonly state: ZLinkMessage;
-  readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
-  readonly sourceLeaveCompletion?: Promise<void>;
-  readonly sourceLeaveSubmitted?: Promise<void>;
-  onSourceLeaveSubmitted(notify: () => Promise<void>): void;
-  observeTargetAuthority(
-    target: ZLinkSpotRouteTarget,
-    targetActorRef: ActorRef,
-    signal?: AbortSignal
-  ): Promise<void>;
-  commit(
-    target: ZLinkSpotRouteTarget,
-    targetActorRef: ActorRef,
-    results: readonly ZLinkActorHandoffResult[],
-    releaseLocation?: boolean
-  ): void;
-  rollback(): Promise<void>;
-}
 
 export interface ZLinkActorSourceTransfer {
   /** Starts the ingress handoff before target route lookup. */
   beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
-  /** Changes a provisional ingress fence into a relocation handoff. */
-  promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
   /** Finishes a same-node deferred Join handoff after completion callback. */
   completeDeferredActorHandoff?(
     actor: ZLinkActor,
@@ -38,12 +13,4 @@ export interface ZLinkActorSourceTransfer {
   ): Promise<void>;
   /** Releases an early handoff when Join cannot commit. */
   cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
-  prepareSource(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    signal?: AbortSignal,
-    lifecycleAuthority?: 'framework' | 'core',
-    deferredJoin?: boolean,
-    relocation?: ServiceWireOperationId
-  ): Promise<ZLinkPreparedActorSource>;
 }

package/src/runtime/actors/index.ts

@@ -42,11 +42,7 @@ import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-ro
 const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
 const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 
-export {
-  DefaultZLinkActorClient,
-  forwardEncodedActorPacket,
-  type ZLinkActorClientOptions
-} from './actor-client';
+export { DefaultZLinkActorClient, type ZLinkActorClientOptions } from './actor-client';
 export { DefaultZLinkActorContext, ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME } from './actor-context';
 export { ZLinkActorSerialExecutor } from './actor-mailbox';
 export {
@@ -191,7 +187,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const actorRef = this.actorRefForState(state);
     return {
       spotId: spotId,
-      objectGeneration: state.locationGeneration ?? 0n,
+      objectGeneration: state.spotGeneration ?? 0n,
       meshName: this.actorMeshNames.get(actorId) ?? '',
       nodeRid: actorRef.nodeRid
     };
@@ -400,6 +396,11 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
 
   async findActor(actorId: string, signal?: AbortSignal): Promise<ZLinkActor | undefined> {
     throwIfAborted(signal);
+    return this.resolveLocalActor(actorId);
+  }
+
+  /** @internal Uses the relocation owner's publication boundary for local dispatch. */
+  resolveLocalActor(actorId: string): ZLinkActor | undefined {
     if (this.relocationStaged.has(actorId)) return undefined;
     return this.states.get(actorId)?.actor;
   }
@@ -467,13 +468,14 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         await registry.restore(transfer.adapterKey, actor, transfer.state, signal);
       }
       state.setLocationGeneration(authorityOwnerGeneration);
-      if (spotId !== undefined) state.setJoinedSpot(spotId, undefined, membershipEpoch);
+      if (spotId !== undefined)
+        state.setJoinedSpot(spotId, undefined, membershipEpoch, spotGeneration);
       return actor;
     } catch (error) {
       if (nativeRef !== undefined) node.discardRelocatedActor?.(nativeRef);
       this.relocationStaged.delete(actorId);
       const failedState = this.states.get(actorId);
-      await this.finalizeActorState(actorId, failedState);
+      await this.finalizeActorState(failedState);
       throw error;
     }
   }
@@ -486,33 +488,50 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   }
 
   async abortRelocationActor(actorId: string): Promise<void> {
-    await this.removeRelocationActor(actorId);
+    await this.releaseLocalActor(actorId);
   }
 
   async completeRelocationSource(
     actorId: string,
     sourceActorRef?: ZLinkBackendActorRef
   ): Promise<void> {
-    await this.removeRelocationActor(actorId, sourceActorRef);
+    await this.releaseLocalActor(actorId, sourceActorRef);
+  }
+
+  /** Commit removes current ownership; a Join profile may still own its leave callback. */
+  detachRelocationSource(state: ZLinkActorRuntimeState): void {
+    if (this.detachActorStateRegistration(state)) {
+      this.discardNativeRelocationSource(state.nativeActorRef);
+    }
   }
 
-  private async removeRelocationActor(
+  async releaseSpotActorMembers(meshName: string, spotId?: RoutingId): Promise<void> {
+    const results = await Promise.allSettled(
+      [...this.states.values()]
+        .filter((state) => state.meshName === meshName && state.spotId === spotId)
+        .map((state) => this.releaseLocalActor(state.actorId))
+    );
+    const errors = results
+      .filter((result): result is PromiseRejectedResult => result.status === 'rejected')
+      .map((result) => result.reason);
+    if (errors.length === 1) throw errors[0];
+    if (errors.length > 1) throw new AggregateError(errors, 'Actor member cleanup failed.');
+  }
+
+  private async releaseLocalActor(
     actorId: string,
     exactNativeActorRef?: ZLinkBackendActorRef
   ): Promise<void> {
     const state = this.states.get(actorId);
-    const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
-    const nativeActorRef = exactNativeActorRef ?? state?.nativeActorRef;
+    if (state === undefined) return;
     const failures: unknown[] = [];
     try {
-      if (nativeActorRef !== undefined) {
-        node?.discardRelocatedActor?.(nativeActorRef);
-      }
+      this.discardNativeRelocationSource(exactNativeActorRef ?? state.nativeActorRef);
     } catch (error) {
       failures.push(error);
     }
     try {
-      await this.completeCoreRelocationSource(actorId);
+      await this.completeCoreRelocationSource(actorId, state);
     } catch (error) {
       failures.push(error);
     }
@@ -523,29 +542,38 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     }
   }
 
-  async completeCoreRelocationSource(actorId: string): Promise<void> {
-    const state = this.states.get(actorId);
-    await this.finalizeActorState(actorId, state);
-  }
-
-  private async finalizeActorState(
+  async completeCoreRelocationSource(
     actorId: string,
-    state: ZLinkActorRuntimeState | undefined
+    state = this.states.get(actorId)
   ): Promise<void> {
-    if (state === undefined || this.states.get(actorId) !== state) return;
+    await this.finalizeActorState(state);
+  }
+
+  private discardNativeRelocationSource(nativeActorRef: ZLinkBackendActorRef | undefined): void {
+    if (nativeActorRef === undefined) return;
+    const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
+    node?.discardRelocatedActor?.(nativeActorRef);
+  }
+
+  private async finalizeActorState(state: ZLinkActorRuntimeState | undefined): Promise<void> {
+    if (state === undefined) return;
     try {
       if (state.actor !== undefined)
         await disposeLifecycleHandlers(state.actor, this.detachedTaskRunner);
     } finally {
       state.clearAfterDestroy();
-      if (this.states.get(actorId) === state) {
-        this.states.delete(actorId);
-        this.actorMeshNames.delete(actorId);
-        this.relocationStaged.delete(actorId);
-      }
+      this.detachActorStateRegistration(state);
     }
   }
 
+  private detachActorStateRegistration(state: ZLinkActorRuntimeState): boolean {
+    if (this.states.get(state.actorId) !== state) return false;
+    this.states.delete(state.actorId);
+    this.actorMeshNames.delete(state.actorId);
+    this.relocationStaged.delete(state.actorId);
+    return true;
+  }
+
   private async finalizeDestroyedActor(
     actorId: string,
     state: ZLinkActorRuntimeState
@@ -554,7 +582,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     try {
       this.options.actorDestroyedCleanup?.(actorId);
     } finally {
-      await this.finalizeActorState(actorId, state);
+      await this.finalizeActorState(state);
       this.options.metrics?.change(METRIC_NAMES.ActorCount, -1);
     }
   }
@@ -930,7 +958,7 @@ class ZLinkActorCreateCallRuntime implements ZLinkActorCreateCall {
   yield(signal?: AbortSignal): Promise<ZLinkActorCreateResult> {
     const turn = requireZLinkYieldTurn(this.turn);
     const pending = this.executeOnce(signal);
-    return turn.yieldPromise(pending);
+    return turn.yieldFrameworkPromise(pending);
   }
 
   private executeOnce(signal?: AbortSignal): Promise<ZLinkActorCreateResult> {

package/src/runtime/actors/session-disconnected-wire.ts

@@ -0,0 +1,66 @@
+import type { RoutingId } from '../../contracts';
+import { ZLINK_MAX_ROUTING_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { ZLinkFrameworkErrorKind, ZLinkFrameworkException } from '../../contracts';
+import { decodeRoutingId, encodeRoutingIdStorageHex } from '../routing-id';
+
+const RID_LENGTH_BYTES = 1;
+const GENERATION_BYTES = 8;
+const GENERATIONS_BYTES = GENERATION_BYTES * 2;
+
+export interface SessionDisconnectedIdentity {
+  readonly sessionOwnerNodeRid: RoutingId;
+  readonly sessionOwnerNodeGeneration: bigint;
+  readonly bindingGeneration: bigint;
+}
+
+export function encodeSessionDisconnected(
+  sessionOwnerNodeRid: RoutingId | undefined,
+  sessionOwnerNodeGeneration: bigint | undefined,
+  bindingGeneration: bigint | undefined
+): Buffer {
+  if (
+    sessionOwnerNodeRid === undefined ||
+    sessionOwnerNodeGeneration === undefined ||
+    sessionOwnerNodeGeneration === 0n ||
+    bindingGeneration === undefined ||
+    bindingGeneration === 0n
+  ) {
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.ProtocolError,
+      'Session disconnect requires an exact binding identity.'
+    );
+  }
+  const rid = Buffer.from(encodeRoutingIdStorageHex(sessionOwnerNodeRid), 'hex');
+  if (rid.length === 0 || rid.length > ZLINK_MAX_ROUTING_ID_BYTES) {
+    throw new ZLinkFrameworkException(
+      ZLinkFrameworkErrorKind.ProtocolError,
+      'Invalid Session owner Node RID length.'
+    );
+  }
+  const payload = Buffer.allocUnsafe(RID_LENGTH_BYTES + rid.length + GENERATIONS_BYTES);
+  payload[0] = rid.length;
+  rid.copy(payload, RID_LENGTH_BYTES);
+  payload.writeBigUInt64BE(sessionOwnerNodeGeneration, RID_LENGTH_BYTES + rid.length);
+  payload.writeBigUInt64BE(bindingGeneration, RID_LENGTH_BYTES + rid.length + GENERATION_BYTES);
+  return payload;
+}
+
+export function decodeSessionDisconnected(
+  bytes: Uint8Array
+): SessionDisconnectedIdentity | undefined {
+  const payload = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (payload.length < RID_LENGTH_BYTES + 1 + GENERATIONS_BYTES) return undefined;
+  const ridLength = payload[0];
+  if (ridLength === 0 || payload.length !== RID_LENGTH_BYTES + ridLength + GENERATIONS_BYTES)
+    return undefined;
+  const offset = RID_LENGTH_BYTES + ridLength;
+  const sessionOwnerNodeGeneration = payload.readBigUInt64BE(offset);
+  const bindingGeneration = payload.readBigUInt64BE(offset + GENERATION_BYTES);
+  if (sessionOwnerNodeGeneration === 0n || bindingGeneration === 0n) return undefined;
+  const hex = payload.subarray(RID_LENGTH_BYTES, offset).toString('hex');
+  return {
+    sessionOwnerNodeRid: decodeRoutingId(hex, hex),
+    sessionOwnerNodeGeneration,
+    bindingGeneration
+  };
+}