@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -1,3 +1,4 @@
+import { FLOW_ORIGIN_VALUES } from '../diagnostics/flow-context';
 export const ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE = 'zlink.bound_session.fence';
 
 /**
@@ -69,17 +70,10 @@ export function encodeRemoteBoundSessionSendPayload(input: {
   };
 }
 
-const WIRE_FLOW_ORIGIN: Record<import('../../contracts').ZLinkFlowOrigin, string> = {
-  Inbound: 'inbound',
-  Timer: 'timer',
-  Application: 'application',
-  Lifecycle: 'lifecycle'
-};
-
 function encodeWireFlowOrigin(
   origin: import('../../contracts').ZLinkFlowOrigin | undefined
 ): string | undefined {
-  return origin === undefined ? undefined : WIRE_FLOW_ORIGIN[origin];
+  return origin === undefined ? undefined : FLOW_ORIGIN_VALUES[origin];
 }
 
 export function encodeRemoteBoundSessionResponsePayload(input: {

package/src/runtime/actors/deferred-join-completion.ts

@@ -1,17 +1,20 @@
-import type { ActorRef, ZLinkActorJoinOperationId } from '../../contracts';
+import type { ActorRef, ZLinkActorJoinOperationId, ZLinkFrameworkErrorKind } from '../../contracts';
 
 /**
- * The Accepted completion of a deferred cross-node Join. Spot Actor membership
- * sections 4-5: the public OperationId, the optional reply and the delivery
+ * The Accepted or Failed result of a deferred cross-node Join. Spot Actor
+ * membership sections 4-5: the public OperationId, optional reply and delivery
  * state live only while the current source and target processes run. The
- * completion is never written to a Store and never replayed after a restart.
+ * completion is never written to a Store or replayed after a restart.
  */
-export interface ZLinkDeferredJoinCompletion {
+export type ZLinkDeferredJoinCompletion = {
   readonly operationId: ZLinkActorJoinOperationId;
   readonly actor: ActorRef;
   readonly rawReply: Buffer;
   readonly replyContentType?: string;
-}
+} & (
+  | { readonly status: 'accepted' }
+  | { readonly status: 'failed'; readonly kind: ZLinkFrameworkErrorKind }
+);
 
 export function createDeferredJoinCompletion(
   actorId: string,
@@ -32,6 +35,7 @@ export function createDeferredJoinCompletion(
     throw new TypeError('Deferred Join reply content type must be non-empty.');
   }
   return {
+    status: 'accepted',
     operationId,
     actor,
     rawReply: Buffer.from(rawReply),

package/src/runtime/actors/index.ts

@@ -1,41 +1,52 @@
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  wireReplyFailureException
-} from '../framework-errors-internal';
-import type {
-  ActorRef,
-  RoutingId,
-  SpotRef,
-  ZLinkActor,
-  ZLinkActorCreateCall,
-  ZLinkActorCreateResult,
-  ZLinkActorGetOrCreateCall,
-  ZLinkActorManager
+  type ActorRef,
+  type RoutingId,
+  type SpotRef,
+  type ZLinkActor,
+  type ZLinkActorCreateCall,
+  type ZLinkActorCreateResult,
+  type ZLinkActorGetOrCreateCall,
+  type ZLinkActorManager,
+  ZLinkEncodedPayload,
+  ZLinkFrameworkException,
+  ZLinkMessage
 } from '../../contracts';
-import { ZLinkEncodedPayload, ZLinkFrameworkException } from '../../contracts';
-import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import { ZLinkMessage } from '../../contracts';
-import { ZLinkConfigurationException } from '../configuration';
+import { DEFAULT_REQUEST_TIMEOUT_MS } from '../../contracts/Configuration/Registration';
 import { throwIfAborted } from '../abort';
 import type { ZLinkBackendActorRef, ZLinkBackendSpotNode } from '../backend/contracts';
 import { closeMeshCompletion } from '../backend/mesh-completion-table';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
+import { ZLinkConfigurationException } from '../configuration';
+import { METRIC_NAMES } from '../diagnostics/runtime-metrics';
 import {
   captureZLinkSpotSerialTurn,
   requireZLinkYieldTurn,
   type ZLinkSpotSerialTurn
 } from '../execution';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException,
+  wireReplyFailureException
+} from '../framework-errors-internal';
 import { disposeLifecycleHandlers } from '../handlers/handler-instance-scope';
+import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
+import { ZLinkActorCreationCoordinator, type ZLinkActorCreateRequest } from './actor-creation';
+import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
+import {
+  ZLinkActorRuntimeState,
+  toFrameworkActorRef,
+  type ZLinkActorCreationAttemptResult
+} from './actor-runtime-state';
+import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-rollback';
+const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
+const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 
 export {
   DefaultZLinkActorClient,
   forwardEncodedActorPacket,
   type ZLinkActorClientOptions
 } from './actor-client';
-
-import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
 export { DefaultZLinkActorContext, ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME } from './actor-context';
-import { ZLinkActorCreationCoordinator, type ZLinkActorCreateRequest } from './actor-creation';
 export { ZLinkActorSerialExecutor } from './actor-mailbox';
 export {
   DEFAULT_MESSAGE_FOLLOW_DURATION_MS,
@@ -60,8 +71,6 @@ export {
 } from './actor-message-follow-context';
 export {
   ZLinkActorRuntimeState,
-  mergeRemoteBoundSessionTarget,
-  preferredRemoteBoundSessionTarget,
   toFrameworkActorRef,
   toFrameworkRoutingId,
   type ZLinkActorCreationOperation,
@@ -82,11 +91,6 @@ export {
   publishInitialActorAuthority,
   type ZLinkActorAuthorityIdentity
 } from './actor-authority-publication';
-import {
-  ZLinkActorRuntimeState,
-  toFrameworkActorRef,
-  type ZLinkActorCreationAttemptResult
-} from './actor-runtime-state';
 export {
   ZLinkActorPacketKind,
   ZLinkSpotActorDispatcher,
@@ -104,8 +108,6 @@ export type {
   ZLinkActorJoinCoordinator,
   ZLinkActorManagerOptions
 } from './actor-runtime-contracts';
-import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
-import { ZLinkTransferredActorRollbackCoordinator } from './transferred-actor-rollback';
 export {
   ZLinkActorTransferRegistry,
   type ZLinkActorTransferPayloadState
@@ -143,11 +145,18 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
   private readonly creation: ZLinkActorCreationCoordinator;
   private readonly transferredActorRollback: ZLinkTransferredActorRollbackCoordinator;
 
-  constructor(private readonly options: ZLinkActorManagerOptions) {
+  constructor(
+    private readonly options: ZLinkActorManagerOptions,
+    private readonly detachedTaskRunner: import('../spots/spot-actor-join-dispatch').ZLinkDetachedTaskRunner
+  ) {
+    if ((detachedTaskRunner as unknown) === undefined) {
+      throw new Error('Actor manager requires a detached task runner.');
+    }
     this.creation = new ZLinkActorCreationCoordinator(options);
     this.transferredActorRollback = new ZLinkTransferredActorRollbackCoordinator(
       this.states,
-      options
+      options,
+      (actorId, state) => this.finalizeDestroyedActor(actorId, state)
     );
   }
 
@@ -204,7 +213,6 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         `Actor '${actor.actorId}' is relocating.`
       );
     }
-    const actorInstance = state.actor;
     const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
     const completions = this.options.nativeActorCompletionTableProvider?.();
     const entryNodeRid = state.entryNodeRid ?? current.nodeRid;
@@ -233,14 +241,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       if (state.actorType !== undefined && state.ownsLocation) {
         await this.options.locationLifecycle?.releaseActor(state.actorType, actor.actorId, current);
       }
-      this.options.actorDestroyedCleanup?.(actor.actorId);
-      await disposeLifecycleHandlers(actorInstance);
-      state.clearAfterDestroy();
-      if (this.states.get(actor.actorId) === state) {
-        this.states.delete(actor.actorId);
-        this.actorMeshNames.delete(actor.actorId);
-      }
-      this.options.metrics?.change('zlink.actor.count', -1);
+      await this.finalizeDestroyedActor(actor.actorId, state);
     });
     try {
       await destroyTask;
@@ -262,7 +263,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const state = this.getOrCreateState(actorId);
     this.rememberActorMeshFromType(actorId, actorType);
     if (state.actor !== undefined) {
-      await disposeLifecycleHandlers(state.actor);
+      await disposeLifecycleHandlers(state.actor, this.detachedTaskRunner);
     }
     state.prepareForRemoteReentry();
     const operation = state.getOrStartCreation(actorType, false, () =>
@@ -407,7 +408,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     actorType: string,
     objectGeneration: bigint,
     authorityOwnerGeneration: bigint,
-    spotId: RoutingId,
+    spotId: RoutingId | undefined,
     spotGeneration: bigint,
     membershipEpoch: bigint,
     signal?: AbortSignal,
@@ -433,7 +434,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         actorType,
         objectGeneration,
         authorityOwnerGeneration,
-        String(spotId),
+        spotId === undefined ? undefined : String(spotId),
         spotGeneration,
         membershipEpoch
       );
@@ -456,18 +457,13 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         await registry.restore(transfer.adapterKey, actor, transfer.state, signal);
       }
       state.setLocationGeneration(authorityOwnerGeneration);
-      state.setJoinedSpot(spotId, undefined, membershipEpoch);
+      if (spotId !== undefined) state.setJoinedSpot(spotId, undefined, membershipEpoch);
       return actor;
     } catch (error) {
       if (nativeRef !== undefined) node.discardRelocatedActor?.(nativeRef);
       this.relocationStaged.delete(actorId);
       const failedState = this.states.get(actorId);
-      if (failedState?.actor !== undefined) {
-        await disposeLifecycleHandlers(failedState.actor);
-      }
-      failedState?.clearAfterDestroy();
-      this.states.delete(actorId);
-      this.actorMeshNames.delete(actorId);
+      await this.finalizeActorState(actorId, failedState);
       throw error;
     }
   }
@@ -497,29 +493,61 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const state = this.states.get(actorId);
     const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
     const nativeActorRef = exactNativeActorRef ?? state?.nativeActorRef;
-    if (nativeActorRef !== undefined) {
-      node?.discardRelocatedActor?.(nativeActorRef);
+    const failures: unknown[] = [];
+    try {
+      if (nativeActorRef !== undefined) {
+        node?.discardRelocatedActor?.(nativeActorRef);
+      }
+    } catch (error) {
+      failures.push(error);
     }
-    if (state?.actor !== undefined) {
-      await disposeLifecycleHandlers(state.actor);
+    try {
+      await this.completeCoreRelocationSource(actorId);
+    } catch (error) {
+      failures.push(error);
+    }
+    if (failures.length > 0) {
+      throw failures.length === 1
+        ? failures[0]
+        : new AggregateError(failures, 'Actor relocation cleanup failed.');
     }
-    state?.clearAfterDestroy();
-    this.states.delete(actorId);
-    this.actorMeshNames.delete(actorId);
-    this.relocationStaged.delete(actorId);
   }
 
   async completeCoreRelocationSource(actorId: string): Promise<void> {
     const state = this.states.get(actorId);
-    if (state?.actor !== undefined) {
-      await disposeLifecycleHandlers(state.actor);
+    await this.finalizeActorState(actorId, state);
+  }
+
+  private async finalizeActorState(
+    actorId: string,
+    state: ZLinkActorRuntimeState | undefined
+  ): Promise<void> {
+    if (state === undefined || this.states.get(actorId) !== state) 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);
+      }
     }
-    state?.clearAfterDestroy();
-    this.states.delete(actorId);
-    this.actorMeshNames.delete(actorId);
-    this.relocationStaged.delete(actorId);
   }
 
+  private async finalizeDestroyedActor(
+    actorId: string,
+    state: ZLinkActorRuntimeState
+  ): Promise<void> {
+    if (this.states.get(actorId) !== state) return;
+    try {
+      this.options.actorDestroyedCleanup?.(actorId);
+    } finally {
+      await this.finalizeActorState(actorId, state);
+      this.options.metrics?.change(METRIC_NAMES.ActorCount, -1);
+    }
+  }
   async getOrCreateActor(
     actorId: string,
     actorType: string,
@@ -569,7 +597,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       createRequest,
       signal,
       false,
-      30_000,
+      DEFAULT_REQUEST_TIMEOUT_MS,
       nativeActorRef
     );
   }
@@ -634,14 +662,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
           destroyedActorRef
         );
       }
-      this.options.actorDestroyedCleanup?.(actor.context.actorId);
-      await disposeLifecycleHandlers(actor);
-      state.clearAfterDestroy();
-      if (this.states.get(actor.context.actorId) === state) {
-        this.states.delete(actor.context.actorId);
-        this.actorMeshNames.delete(actor.context.actorId);
-      }
-      this.options.metrics?.change('zlink.actor.count', -1);
+      await this.finalizeDestroyedActor(actor.context.actorId, state);
     });
 
     try {
@@ -659,7 +680,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     request: unknown,
     signal?: AbortSignal,
     claimLocation = true,
-    timeoutMs = 30_000,
+    timeoutMs: number = DEFAULT_REQUEST_TIMEOUT_MS,
     nativeActorRef?: ZLinkBackendActorRef
   ): Promise<ZLinkActorLocalCreateResult> {
     const deadline = performance.now() + timeoutMs;
@@ -766,7 +787,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     if (this.states.get(actorId) === state) {
       this.states.delete(actorId);
       this.actorMeshNames.delete(actorId);
-      this.options.metrics?.change('zlink.actor.count', -1);
+      this.options.metrics?.change(METRIC_NAMES.ActorCount, -1);
     }
   }
 
@@ -797,7 +818,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       state.rememberMeshName(remembered);
     }
     this.states.set(actorId, state);
-    this.options.metrics?.change('zlink.actor.count', 1);
+    this.options.metrics?.change(METRIC_NAMES.ActorCount, 1);
     return state;
   }
 
@@ -810,7 +831,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       actorId: state.actorId,
       objectGeneration: 1n,
       meshName: state.meshName ?? '',
-      nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? 'local'
+      nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
     };
   }
 }
@@ -830,7 +851,7 @@ class ZLinkActorCreateCallRuntime implements ZLinkActorCreateCall {
   private meshNameValue: string | undefined;
   private requestValue: unknown;
   private requestConfigured = false;
-  private timeoutMsValue = 30_000;
+  private timeoutMsValue: number = DEFAULT_REQUEST_TIMEOUT_MS;
   private timeoutConfigured = false;
   private submitted = false;
   private readonly turn: ZLinkSpotSerialTurn | undefined = captureZLinkSpotSerialTurn();
@@ -955,7 +976,7 @@ async function waitForCreationRetry(signal?: AbortSignal): Promise<void> {
       if (error === undefined) resolve();
       else reject(error);
     };
-    const timer = setTimeout(() => finish(), 5);
+    const timer = setTimeout(() => finish(), ACTOR_CREATION_RETRY_INTERVAL_MS);
     const onAbort = () => {
       finish(signal?.reason ?? new Error('Actor creation was aborted.'));
     };

package/src/runtime/actors/spot-actor-dispatch.ts

@@ -1,28 +1,31 @@
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
-import type {
-  Type,
-  ZLinkActor,
-  ZLinkActorHandlerRegistry,
-  ZLinkSpot,
-  ZLinkSpotActorJoinResult,
-  ZLinkMessageContext,
-  ZLinkSpotActorRequestHandler,
-  ZLinkSpotActorSendHandler
+  type Type,
+  type ZLinkActor,
+  type ZLinkActorHandlerRegistry,
+  type ZLinkMessageContext,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  type ZLinkSpotActorJoinResult,
+  type ZLinkSpotActorRequestHandler,
+  type ZLinkSpotActorSendHandler,
+  ZLinkFrameworkException,
+  ZLinkMessageMetadataEmpty
 } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
-import { ZLinkFrameworkException, ZLinkMessageMetadataEmpty } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkConfigurationException } from '../configuration';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import { readZLinkDecoratorMetadata } from '../../contracts/Handlers/Attributes';
+import { ZLinkConfigurationException } from '../configuration';
+import type { ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
+import { runWithLifecycleHandler } from '../handlers/handler-instance-scope';
 import { wrapFrameworkPayloadMessage } from '../messaging/payload-codec';
-import type { ZLinkMessageSerializer } from '../../contracts';
-import { actorJoinIdentity } from './actor-lifecycle-snapshot';
 import { runActorHandlerWithDeferredJoins } from './actor-join-deferred-scope';
-import { runWithLifecycleHandler } from '../handlers/handler-instance-scope';
-import type { ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
+import { actorJoinIdentity } from './actor-lifecycle-snapshot';
 
 export enum ZLinkActorPacketKind {
   Send = 'send',
@@ -34,6 +37,7 @@ export interface ZLinkActorPacketDescriptor {
   readonly packetName: string;
   readonly actorType: Type<ZLinkActor>;
   readonly handlerType: Type;
+  readonly methodName?: string;
 }
 
 export class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRegistry {
@@ -56,7 +60,8 @@ export class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRe
           : ZLinkActorPacketKind.Request,
       packetName: resolvedPacketName,
       actorType: Object as unknown as Type<ZLinkActor>,
-      handlerType
+      handlerType,
+      methodName: metadata.methodName
     });
   }
 
@@ -67,7 +72,16 @@ export class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRe
         `Actor packet '${descriptor.packetName}' for '${descriptor.actorType.name}' is already registered.`
       );
     }
-    this.packets.set(key, descriptor);
+    const metadata = readZLinkDecoratorMetadata(descriptor.handlerType).find(
+      (entry) =>
+        entry.kind ===
+          (descriptor.kind === ZLinkActorPacketKind.Send ? 'spotActorSend' : 'spotActorRequest') &&
+        entry.packetName === descriptor.packetName
+    );
+    this.packets.set(key, {
+      ...descriptor,
+      methodName: descriptor.methodName ?? metadata?.methodName
+    });
     return this;
   }
 
@@ -144,9 +158,10 @@ export class ZLinkSpotActorDispatcher {
       await this.invokeHandler<ZLinkSpotActorSendHandler<ZLinkSpot, ZLinkActor, TMessage>, void>(
         actor,
         descriptor,
-        (handler) =>
+        (handler, method) =>
           runActorHandlerWithDeferredJoins(() =>
-            handler.handle(
+            method.call(
+              handler,
               this.options.spot,
               actor,
               this.createContext(packetName, context),
@@ -232,10 +247,11 @@ export class ZLinkSpotActorDispatcher {
       return await this.invokeHandler<
         ZLinkSpotActorRequestHandler<ZLinkSpot, ZLinkActor, TRequest, TReply>,
         TResult
-      >(actor, descriptor, (handler) =>
+      >(actor, descriptor, (handler, method) =>
         runActorHandlerWithDeferredJoins(
           () =>
-            handler.handle(
+            method.call(
+              handler,
               this.options.spot,
               actor,
               this.createContext(packetName, context),
@@ -274,7 +290,7 @@ export class ZLinkSpotActorDispatcher {
   evaluateActorJoin(
     actor: ZLinkActor,
     request: Message,
-    contentType = 'application/json'
+    contentType: string = ZlinkStreamContentType.Json
   ): Promise<ZLinkSpotActorJoinResult> {
     return this.execute(async () => {
       const payload = wrapFrameworkPayloadMessage(
@@ -337,14 +353,29 @@ export class ZLinkSpotActorDispatcher {
 
   private async invokeHandler<THandler, TResult>(
     actor: ZLinkActor,
-    descriptor: Pick<ZLinkActorPacketDescriptor, 'handlerType'>,
-    callback: (handler: THandler) => Promise<TResult>
+    descriptor: Pick<ZLinkActorPacketDescriptor, 'handlerType' | 'methodName'>,
+    callback: (
+      handler: THandler,
+      method: THandler extends { handle: infer TMethod } ? TMethod : never
+    ) => Promise<TResult>
   ): Promise<TResult> {
     return await runWithLifecycleHandler(
       actor,
       descriptor.handlerType,
       this.options.providerResolver,
-      (resolved) => callback(resolved as THandler)
+      (resolved) => {
+        const methodName = descriptor.methodName ?? 'handle';
+        const method = (resolved as Record<string, unknown>)[methodName];
+        if (typeof method !== 'function') {
+          throw new ZLinkConfigurationException(
+            `Actor handler '${descriptor.handlerType.name}.${methodName}' is not callable.`
+          );
+        }
+        return callback(
+          resolved as THandler,
+          method as THandler extends { handle: infer TMethod } ? TMethod : never
+        );
+      }
     );
   }
 

package/src/runtime/actors/transferred-actor-rollback.ts

@@ -4,24 +4,18 @@ import { closeMeshCompletion } from '../backend';
 import { RequestResult } from '../backend/runtime-values';
 import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
-import { ZLinkActorRetryDelay } from './actor-retry-delay';
+import { createActorMembership } from './actor-lifecycle-snapshot';
 
 type ZLinkTransferredActorRollbackOptions = Pick<
   ZLinkActorManagerOptions,
-  | 'actorDestroyedCleanup'
-  | 'nativeActorNode'
-  | 'nativeActorNodeProvider'
-  | 'nativeActorCompletionTableProvider'
-  | 'shutdownSignal'
-  | 'metrics'
+  'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider'
 >;
 
 export class ZLinkTransferredActorRollbackCoordinator {
-  private readonly tasks = new Map<string, Promise<void>>();
-
   constructor(
     private readonly states: Map<string, ZLinkActorRuntimeState>,
-    private readonly options: ZLinkTransferredActorRollbackOptions
+    private readonly options: ZLinkTransferredActorRollbackOptions,
+    private readonly finalize: (actorId: string, state: ZLinkActorRuntimeState) => Promise<void>
   ) {}
 
   async rollback(actor: ZLinkActor, signal?: AbortSignal): Promise<void> {
@@ -37,54 +31,10 @@ export class ZLinkTransferredActorRollbackCoordinator {
 
     const actorRef = state.nativeActorRef;
     const node = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
-    try {
-      if (node !== undefined && actorRef !== undefined) {
-        await this.destroyNativeActor(node, actorRef, signal);
-      }
-    } catch (error) {
-      this.schedule(actor, state, node, actorRef);
-      throw error;
-    }
-    this.complete(actor, state);
-  }
-
-  private schedule(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    node: ZLinkBackendMeshNode | undefined,
-    actorRef: ZLinkBackendActorRef | undefined
-  ): void {
-    if (this.tasks.has(actor.context.actorId)) {
-      return;
-    }
-    const task = this.retry(actor, state, node, actorRef).finally(() =>
-      this.tasks.delete(actor.context.actorId)
-    );
-    this.tasks.set(actor.context.actorId, task);
-  }
-
-  private async retry(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    node: ZLinkBackendMeshNode | undefined,
-    actorRef: ZLinkBackendActorRef | undefined
-  ): Promise<void> {
-    const retryDelay = new ZLinkActorRetryDelay();
-    while (
-      this.states.get(actor.context.actorId) === state &&
-      this.options.shutdownSignal?.aborted !== true
-    ) {
-      if (!(await retryDelay.wait(this.options.shutdownSignal))) return;
-      try {
-        if (node !== undefined && actorRef !== undefined) {
-          await this.destroyNativeActor(node, actorRef);
-        }
-        this.complete(actor, state);
-        return;
-      } catch {
-        // The tombstone prevents dispatch while the next retry is pending.
-      }
+    if (node !== undefined && actorRef !== undefined) {
+      await this.destroyNativeActor(node, actorRef, signal);
     }
+    await this.complete(actor, state);
   }
 
   private async destroyNativeActor(
@@ -116,13 +66,12 @@ export class ZLinkTransferredActorRollbackCoordinator {
     }
   }
 
-  private complete(actor: ZLinkActor, state: ZLinkActorRuntimeState): void {
+  private async complete(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void> {
     if (this.states.get(actor.context.actorId) !== state) {
       return;
     }
-    this.options.actorDestroyedCleanup?.(actor.context.actorId);
-    state.clearAfterDestroy();
-    this.states.delete(actor.context.actorId);
-    this.options.metrics?.change('zlink.actor.count', -1);
+    await state.getOrStartDestroy(createActorMembership(actor).actor.nodeRid, () =>
+      this.finalize(actor.context.actorId, state)
+    );
   }
 }