@zlink-systems/framework 0.25.0 → 0.27.0

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

@@ -27,36 +27,23 @@ export interface ZLinkPreparedActorSource {
 
 export interface ZLinkActorSourceTransfer {
   /** Starts the ingress handoff before target route lookup. */
-  beginDeferredActorHandoff?(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    operationId: string
-  ): void;
+  beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
   /** Changes a provisional ingress fence into a relocation handoff. */
-  promoteDeferredActorHandoff?(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    operationId: string
-  ): void;
+  promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
   /** Finishes a same-node deferred Join handoff after completion callback. */
   completeDeferredActorHandoff?(
     actor: ZLinkActor,
     target: ZLinkSpotRouteTarget,
-    targetActorRef: ActorRef,
-    operationId: string
+    targetActorRef: ActorRef
   ): Promise<void>;
   /** Releases an early handoff when Join cannot commit. */
-  cancelDeferredActorHandoff?(
-    actor: ZLinkActor,
-    state: ZLinkActorRuntimeState,
-    operationId: string
-  ): Promise<void>;
+  cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
   prepareSource(
     actor: ZLinkActor,
     state: ZLinkActorRuntimeState,
     signal?: AbortSignal,
     lifecycleAuthority?: 'framework' | 'core',
-    deferredOperationId?: string,
+    deferredJoin?: boolean,
     relocation?: ServiceWireOperationId
   ): Promise<ZLinkPreparedActorSource>;
 }

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

@@ -0,0 +1,44 @@
+import type { ActorRef, ZLinkActorJoinOperationId, ZLinkFrameworkErrorKind } from '../../contracts';
+
+/**
+ * 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 or replayed after a restart.
+ */
+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,
+  operationId: ZLinkActorJoinOperationId,
+  actor: ActorRef,
+  rawReply: Uint8Array,
+  replyContentType?: string
+): ZLinkDeferredJoinCompletion {
+  if (
+    actorId.length === 0 ||
+    actor.actorId !== actorId ||
+    actor.objectGeneration <= 0n ||
+    (operationId.high === 0n && operationId.low === 0n)
+  ) {
+    throw new Error('Deferred Join completion identity is invalid.');
+  }
+  if (replyContentType !== undefined && replyContentType.length === 0) {
+    throw new TypeError('Deferred Join reply content type must be non-empty.');
+  }
+  return {
+    status: 'accepted',
+    operationId,
+    actor,
+    rawReply: Buffer.from(rawReply),
+    ...(replyContentType === undefined ? {} : { replyContentType })
+  };
+}

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,
@@ -69,12 +78,9 @@ export {
   type ZLinkRemoteBoundSessionTarget
 } from './actor-runtime-state';
 export {
-  isDeferredJoinAcceptedRootPublication,
-  ZLinkDeferredJoinAcceptedJournal,
-  type ZLinkDeferredJoinAcceptedRoot,
-  type ZLinkDeferredJoinRootIdentity,
-  type ZLinkDeferredJoinDeliveryCursor
-} from './deferred-join-accepted-journal';
+  createDeferredJoinCompletion,
+  type ZLinkDeferredJoinCompletion
+} from './deferred-join-completion';
 export {
   decodeActorAuthorityIdentity,
   decodeRelocatingActorAuthorityIdentity,
@@ -85,11 +91,6 @@ export {
   publishInitialActorAuthority,
   type ZLinkActorAuthorityIdentity
 } from './actor-authority-publication';
-import {
-  ZLinkActorRuntimeState,
-  toFrameworkActorRef,
-  type ZLinkActorCreationAttemptResult
-} from './actor-runtime-state';
 export {
   ZLinkActorPacketKind,
   ZLinkSpotActorDispatcher,
@@ -107,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
@@ -146,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)
     );
   }
 
@@ -207,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;
@@ -236,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;
@@ -265,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, () =>
@@ -410,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,
@@ -436,7 +434,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         actorType,
         objectGeneration,
         authorityOwnerGeneration,
-        String(spotId),
+        spotId === undefined ? undefined : String(spotId),
         spotGeneration,
         membershipEpoch
       );
@@ -459,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;
     }
   }
@@ -500,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,
@@ -572,7 +597,7 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       createRequest,
       signal,
       false,
-      30_000,
+      DEFAULT_REQUEST_TIMEOUT_MS,
       nativeActorRef
     );
   }
@@ -637,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 {
@@ -662,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;
@@ -687,9 +705,25 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       if (request !== undefined && createRequest.nativeRequest !== undefined) {
         state.setCreateRequestPayload(createRequest.nativeRequest.data());
       }
-      const operation = state.getOrStartCreation(actorType, failIfExists, () =>
-        this.creation.createActor(actorId, actorType, state, createRequest, claimLocation, signal)
-      );
+      const operation = state.getOrStartCreation(actorType, failIfExists, async () => {
+        const meshName = state.meshName ?? this.options.actorMeshNameProvider?.(actorType);
+        const release =
+          meshName === undefined
+            ? undefined
+            : await this.options.activationAdmission?.acquire(meshName, signal);
+        try {
+          return await this.creation.createActor(
+            actorId,
+            actorType,
+            state,
+            createRequest,
+            claimLocation,
+            signal
+          );
+        } finally {
+          release?.();
+        }
+      });
       if (operation.created) {
         void operation.task.then(
           (result) => {
@@ -753,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);
     }
   }
 
@@ -784,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;
   }
 
@@ -797,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
     };
   }
 }
@@ -817,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();
@@ -942,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
+        );
+      }
     );
   }