@zlink-systems/framework 0.26.0 → 0.27.0

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

@@ -1,45 +1,51 @@
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
-import type {
-  RoutingId,
-  SpotId,
-  ZLinkActor,
-  ZLinkActorContext,
-  ZLinkActorJoinCompletion,
-  ZLinkActorJoinEntrySpotCall,
-  ZLinkActorJoinSpotCall,
-  ZLinkBoundSession,
-  ZLinkBoundSessionSendCall
+  type RoutingId,
+  type SpotId,
+  type ZLinkActor,
+  type ZLinkActorContext,
+  type ZLinkActorJoinCompletion,
+  type ZLinkActorJoinEntrySpotCall,
+  type ZLinkActorJoinSpotCall,
+  type ZLinkBoundSession,
+  type ZLinkBoundSessionSendCall,
+  ZLinkEncodedPayload,
+  ZLinkFrameworkException,
+  ZLinkMessage,
+  type ZLinkMessageSerializer
 } from '../../contracts';
-import { ZLinkEncodedPayload, ZLinkFrameworkException, ZLinkMessage } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
-import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import { type ZLinkMessageSerializer } from '../../contracts';
-import { ZLinkConfigurationException } from '../configuration';
 import {
-  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome,
   ZLinkRuntimeDispatchErrorAction as ZLinkDispatchErrorAction,
   ZLinkRuntimeDispatchErrorReason as ZLinkDispatchErrorReason,
   ZLinkDispatchErrorSurface,
-  ZLinkDispatchMessageKind
+  ZLinkDispatchMessageKind,
+  ZLinkRuntimeMessageFlowOutcome as ZLinkMessageFlowOutcome
 } from '../../contracts/Dispatch/ZLinkDispatchOptions';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
+import { ZLinkConfigurationException } from '../configuration';
+import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
+import { captureZLinkSpotSerialTurn } from '../execution';
+import { createRandomOperationIdentity } from '../foundation/operation-identity';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
-import { ZLinkActorRuntimeState, toFrameworkActorRef } from './actor-runtime-state';
-import type {
-  ZLinkActorBoundSessionFactory,
-  ZLinkActorJoinCoordinator
-} from './actor-runtime-contracts';
-import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
+import { deferActorJoin } from './actor-join-deferred-scope';
 import {
   ZLINK_ACTOR_LIFECYCLE_SNAPSHOT,
   type ZLinkActorLifecycleSnapshotSource
 } from './actor-lifecycle-snapshot';
-import { createRandomOperationIdentity } from '../foundation/operation-identity';
-import { deferActorJoin } from './actor-join-deferred-scope';
-import { captureZLinkSpotSerialTurn } from '../execution';
-import { dispatchErrorDetails } from '../diagnostics/dispatch-error-details';
+import type {
+  ZLinkActorBoundSessionFactory,
+  ZLinkActorJoinCoordinator,
+  ZLinkActorManagerOptions
+} from './actor-runtime-contracts';
+import { ZLinkActorRuntimeState, toFrameworkActorRef } from './actor-runtime-state';
+const DEFAULT_ACTOR_JOIN_TIMEOUT_MS = 5_000;
+
+const MAX_ACTOR_JOIN_TIMEOUT_MS = 2_147_483_647;
 
 export const ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = Symbol('zlink.actor.join-entry-spot-runtime');
 
@@ -166,7 +172,7 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
 }
 
 class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
-  private timeoutMs = 5_000;
+  private timeoutMs: number = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
   private deferred = false;
   private readonly turn = captureZLinkSpotSerialTurn();
 
@@ -305,7 +311,7 @@ class DefaultZLinkActorJoinSpotCall implements ZLinkActorJoinSpotCall {
 }
 
 class DefaultZLinkActorJoinEntrySpotCall implements ZLinkActorJoinEntrySpotCall {
-  private timeoutMs = 5_000;
+  private timeoutMs: number = DEFAULT_ACTOR_JOIN_TIMEOUT_MS;
   private deferred = false;
   private readonly turn = captureZLinkSpotSerialTurn();
 
@@ -480,9 +486,9 @@ function encodeJoinRequest(
 
 function validateJoinTimeout(timeoutMs: number): number {
   const rounded = Math.ceil(timeoutMs);
-  if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > 2_147_483_647) {
+  if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > MAX_ACTOR_JOIN_TIMEOUT_MS) {
     throw new ZLinkConfigurationException(
-      'Actor join timeout must be a finite value from 1 through 2147483647 milliseconds.'
+      `Actor join timeout must be a finite value from 1 through ${MAX_ACTOR_JOIN_TIMEOUT_MS} milliseconds.`
     );
   }
   return rounded;

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

@@ -1,45 +1,47 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  internalFrameworkErrorKind
-} from '../framework-errors-internal';
-import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
-import type { ActorRef, RoutingId } from '../../contracts';
-import { ZLinkFrameworkException } from '../../contracts';
+import { type ActorRef, type RoutingId, ZLinkFrameworkException } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import { zlinkDefaultLocationOptions } from '../../contracts/Locations/Options';
+import { releaseApplicationJobPermitForDurableHandoff } from '../application-jobs/application-job-queue-scope';
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
 import {
   MessageFollowSuppressionRegistry,
   type MessageFollowSuppressionFence
 } from '../foundation/message-follow-suppression-registry';
-import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
+import {
+  createInternalFrameworkException,
+  internalFrameworkErrorKind,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
 import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
-import { releaseApplicationJobPermitForDurableHandoff } from '../application-jobs/application-job-queue-scope';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
 import { decodeActorRequestDeadlineUnixMs, decodeStreamHeader } from '../streams/protocol';
-import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
-import { requestRoutedJsonReply } from './actor-routed-json-request';
-import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
-import {
-  encodeMessageFollowRemoteActorPacketRelayPayload,
-  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
-} from './actor-packet-relay-wire';
 import {
   actorMessageFollowContext,
   actorMessageFollowPayloadChecksum,
-  attachActorMessageFollowContext,
   advanceActorMessageFollowContext,
+  attachActorMessageFollowContext,
   createMessageFollowId,
   messageFollowOwnerFenceKey,
   messageFollowOwnerFencesEqual,
   messageFollowOwnerNodeRid,
   ownerFence,
   verifyActorMessageFollowPayload,
+  ZLINK_MESSAGE_FOLLOW_MAX_HOPS,
   type ZLinkActorMessageFollowContext,
   type ZLinkActorMessageFollowOwnerFence
 } from './actor-message-follow-context';
+import {
+  encodeMessageFollowRemoteActorPacketRelayPayload,
+  ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
+} from './actor-packet-relay-wire';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+import { requestRoutedJsonReply } from './actor-routed-json-request';
+import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
 
-export const DEFAULT_MESSAGE_FOLLOW_DURATION_MS = 30_000;
-const MAX_MESSAGE_FOLLOW_HOPS = 8;
+export const DEFAULT_MESSAGE_FOLLOW_DURATION_MS =
+  zlinkDefaultLocationOptions.messageFollowDurationMs;
 const RELOCATION_REPLY_RETENTION_MS = 24 * 60 * 60 * 1_000;
 
 export interface ZLinkActorHandoffPacket {
@@ -1445,7 +1447,7 @@ export class ZLinkActorHandoffCoordinator {
       return duplicate.result;
     }
     const bytes = packetBytes(packet);
-    if (context.hopCount >= MAX_MESSAGE_FOLLOW_HOPS) {
+    if (context.hopCount >= ZLINK_MESSAGE_FOLLOW_MAX_HOPS) {
       this.options.onMarker?.('message_follow_rejected', actorId);
       return Promise.reject(actorLocationStale(actorId));
     }

package/src/runtime/actors/actor-lifecycle-snapshot.ts

@@ -1,5 +1,6 @@
 import type { ActorRef, ZLinkActor, ZLinkActorMembership } from '../../contracts';
 import { ZLinkConfigurationException } from '../configuration';
+import { diagnosticTextOrAbsent } from '../diagnostics/diagnostic-text';
 
 export const ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = Symbol('zlink.actor.lifecycle-snapshot');
 
@@ -63,7 +64,7 @@ function lifecycleSource(actor: ZLinkActor): ZLinkActorLifecycleSnapshotSource {
       : undefined;
   // A caller can hand in a value that carries no Framework context at all, so the
   // failure path reports the configuration error instead of dereferencing it.
-  const actorId = context?.actorId ?? '<unknown>';
+  const actorId = diagnosticTextOrAbsent(context?.actorId);
   const snapshot = context?.[ZLINK_ACTOR_LIFECYCLE_SNAPSHOT];
   const source = snapshot === undefined ? undefined : snapshot.call(context);
   if (source === undefined) {

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

@@ -1,51 +1,73 @@
-import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException,
-  wireReplyFailureException
-} from '../framework-errors-internal';
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import { randomUUID } from 'node:crypto';
-import { isBackendNotConnectedError } from '../backend/runtime-values';
-import type {
-  RoutingId,
-  ZLinkActor,
-  ZLinkActorJoinOperationId,
-  ZLinkMessageSerializer
+import {
+  type RoutingId,
+  type ZLinkActor,
+  type ZLinkActorJoinOperationId,
+  type ZLinkMessageSerializer,
+  type ZLinkSpot,
+  type ZLinkSpotActorJoinResult,
+  ZLinkSpotKind
 } from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
-import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
+
 import type { Message } from '../../contracts/Common/Message';
+import { createAbortError, throwIfAborted } from '../abort';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
 import {
   closeMeshCompletion,
   type ZLinkMeshCompletion,
   type ZLinkMeshCompletionTable
 } from '../backend/mesh-completion-table';
-import { createAbortError, throwIfAborted } from '../abort';
+import { isBackendNotConnectedError } from '../backend/runtime-values';
+import { operationIdentityKey } from '../foundation/operation-identity';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException,
+  wireReplyFailureException
+} from '../framework-errors-internal';
+import type { ZLinkLocationLifecycle } from '../locations';
+import { frameworkPayloadContentType } from '../messaging/payload-codec';
+import { routingIdsEqual, toBackendRoutingId } from '../routing-id';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+import { ZLINK_REMOTE_ACTOR_JOIN_PACKET } from './actor-remote-wire';
+import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
 import {
   ZLinkActorRuntimeState,
   toFrameworkActorRef,
   toFrameworkRoutingId
 } from './actor-runtime-state';
 import type { ZLinkPostCommitActorBinder } from './post-commit-actor-binder';
-import type { ZLinkPostCommitActorLocation } from './post-commit-actor-location';
-import { toBackendRoutingId as toBackendRoutingId } from '../routing-id';
-import { routingIdsEqual } from '../routing-id';
-import { operationIdentityKey } from '../foundation/operation-identity';
-import { frameworkPayloadContentType } from '../messaging/payload-codec';
-import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+const LOCAL_JOIN_RESOLUTION_TIMEOUT_MS = 5_000;
+const LOCAL_JOIN_POLL_INTERVAL_MS = 10;
 
 const ZLINK_FRAMEWORK_ACTOR_JOIN_PACKET_NAME = 'ZLinkFrameworkActorJoinRequest';
 
 export interface ZLinkLocalNativeActorJoinOptions {
-  readonly postCommitLocation?: ZLinkPostCommitActorLocation;
+  readonly locationLifecycle?: ZLinkLocationLifecycle;
+  readonly localSpotJoin?: (
+    spotId: RoutingId,
+    actor: ZLinkActor,
+    request: Message,
+    commit: (spot: ZLinkSpot) => Promise<void>,
+    signal?: AbortSignal,
+    leaveSource?: () => Promise<void>,
+    contentType?: string
+  ) => Promise<ZLinkSpotActorJoinResult>;
+  readonly localEntryJoin?: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+  readonly localSourceLeave?: (
+    actor: ZLinkActor,
+    spotId: RoutingId | undefined,
+    signal?: AbortSignal
+  ) => Promise<void>;
+  readonly reportSourceLeaveError: (error: unknown) => void;
   readonly postCommitBinder?: ZLinkPostCommitActorBinder;
   readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
   readonly actorJoinRelocation?: ZLinkActorJoinRelocation;
   readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
 }
 
-/** Owns core-native actor joins and their local runtime state transition. */
+/** Selects local membership commits or remote Actor relocation. */
 export class ZLinkLocalNativeActorJoin {
   constructor(private readonly options: ZLinkLocalNativeActorJoinOptions) {}
 
@@ -62,9 +84,7 @@ export class ZLinkLocalNativeActorJoin {
     completionOperationId?: ZLinkActorJoinOperationId
   ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
     if (signal?.aborted === true) throw createAbortError();
-    const completions = this.requireCompletions();
     const target = requireUserSpotRoute(spotRouteTarget, spotId);
-    const actorMeshName = runtimeActorMeshName(actor, state, target.routerChannelId);
     const remote = !routingIdsEqual(
       toFrameworkRoutingId(node.status().routingId),
       target.targetNodeRid
@@ -83,88 +103,16 @@ export class ZLinkLocalNativeActorJoin {
         false
       );
     }
-    const completion = await this.waitForJoinCompletion(
-      () =>
-        node.joinActorSpot(
-          actorRef,
-          toBackendRoutingId(target.targetNodeRid),
-          toBackendRoutingId(target.spotId),
-          target.targetSpotGeneration,
-          actorJoinApplicationPayload(request),
-          timeoutMs
-        ),
-      completions,
-      timeoutMs,
+    return await this.joinLocal(
+      node,
+      actor,
+      state,
+      actorRef,
+      target,
+      target.spotId,
+      request,
       signal
     );
-    const control = completion.kindData;
-    if (control?.kind !== 'actorJoinCompletion' || control.actor === null) {
-      closeMeshCompletion(completion);
-      const message = `Actor join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`;
-      //  Classify the (terminal, fine) pair instead of collapsing every non-OK
-      //  or malformed join completion to NotFound (spec 32-framework-error-model:
-      //  83-118). An OK terminal that carries no join control is a protocol
-      //  violation, not a missing route.
-      throw completion.terminalResult !== 0 || completion.failureErrno !== 0
-        ? wireReplyFailureException(completion.terminalResult, completion.failureErrno, message)
-        : createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.RequestProtocolError,
-            message
-          );
-    }
-    if (control.joinResult !== 0) {
-      try {
-        return {
-          accepted: false,
-          actor: toFrameworkActorRef(control.actor as never, actorMeshName),
-          reply: completion.parts[0]
-        };
-      } finally {
-        disposeParts(completion.parts.slice(1));
-      }
-    }
-    if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-      closeMeshCompletion(completion);
-      throw wireReplyFailureException(
-        completion.terminalResult,
-        completion.failureErrno,
-        `Actor join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`
-      );
-    }
-
-    state.setNativeActorRef(control.actor as never);
-    state.setJoinedSpot(
-      toFrameworkRoutingId(control.location.spotId ?? target.spotId),
-      undefined,
-      control.location.membershipEpoch,
-      control.location.spotGeneration
-    );
-    // The Session owner relays from the verified Ready authority snapshot;
-    // membership coordinates alone cannot recreate a User/Instance fence.
-    state.setRemoteActorPacketTarget(target.spotKind === ZLinkSpotKind.Entry ? undefined : target);
-    if (state.actorType !== undefined) {
-      this.options.postCommitLocation?.joinedEventually(
-        state.actorType,
-        actor.context.actorId,
-        spotRouteTarget?.routerChannelId ?? '',
-        toFrameworkRoutingId(control.location.spotId ?? target.spotId),
-        control.location.spotGeneration,
-        control.location.membershipEpoch,
-        node.status().lifecycleGeneration
-      );
-    }
-    await this.options.postCommitBinder?.bind(
-      toFrameworkActorRef(control.actor as never, actorMeshName)
-    );
-    try {
-      return {
-        accepted: true,
-        actor: toFrameworkActorRef(control.actor as never, actorMeshName),
-        reply: completion.parts[0]
-      };
-    } finally {
-      disposeParts(completion.parts.slice(1));
-    }
   }
 
   async joinEntrySpot(
@@ -180,8 +128,6 @@ export class ZLinkLocalNativeActorJoin {
     completionOperationId?: ZLinkActorJoinOperationId
   ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
     if (signal?.aborted === true) throw createAbortError();
-    const completions = this.requireCompletions();
-    const actorMeshName = runtimeActorMeshName(actor, state, '');
     const targetNodeRid = spotRouteTarget?.targetNodeRid ?? nodeRid;
     const remote =
       spotRouteTarget !== undefined &&
@@ -204,77 +150,127 @@ export class ZLinkLocalNativeActorJoin {
         true
       );
     }
-    const completion = await this.waitForJoinCompletion(
-      () =>
-        node.joinActorEntrySpot(
-          actorRef,
-          toBackendRoutingId(targetNodeRid),
-          actorJoinApplicationPayload(request),
-          timeoutMs
-        ),
-      completions,
-      timeoutMs,
+    const target = {
+      routerChannelId: spotRouteTarget?.routerChannelId ?? runtimeActorMeshName(actor, state, ''),
+      targetNodeRid,
+      spotId: toFrameworkRoutingId(node.entrySpot().routingId),
+      spotKind: ZLinkSpotKind.Entry,
+      targetSpotGeneration: node.entrySpot().status().lifecycleGeneration
+    };
+    return await this.joinLocal(
+      node,
+      actor,
+      state,
+      actorRef,
+      target,
+      spotRouteTarget?.spotId ?? target.spotId,
+      request,
       signal
     );
-    const control = completion.kindData;
-    if (control?.kind !== 'actorJoinCompletion' || control.actor === null) {
-      closeMeshCompletion(completion);
-      const message = `Actor entry SPOT join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`;
-      //  Classify the (terminal, fine) pair instead of collapsing to NotFound
-      //  (spec 32-framework-error-model:83-118); an OK terminal with no join
-      //  control is a protocol violation.
-      throw completion.terminalResult !== 0 || completion.failureErrno !== 0
-        ? wireReplyFailureException(completion.terminalResult, completion.failureErrno, message)
-        : createInternalFrameworkException(
-            ZLinkFrameworkInternalErrorKind.RequestProtocolError,
-            message
-          );
-    }
-    if (control.joinResult !== 0) {
-      try {
-        return {
-          accepted: false,
-          actor: toFrameworkActorRef(control.actor as never, actorMeshName),
-          reply: completion.parts[0]
-        };
-      } finally {
-        disposeParts(completion.parts.slice(1));
-      }
+  }
+
+  private async joinLocal(
+    node: ZLinkBackendMeshNode,
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    actorRef: ZLinkBackendActorRef,
+    target: ZLinkSpotRouteTarget,
+    storeSpotId: RoutingId,
+    request: Message,
+    signal: AbortSignal | undefined
+  ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
+    const location = node.actorLookup(actor.context.actorId);
+    const meshName = runtimeActorMeshName(actor, state, target.routerChannelId);
+    if (routingIdsEqual(toFrameworkRoutingId(location.spotId), target.spotId)) {
+      return { accepted: true, actor: toFrameworkActorRef(actorRef, meshName) };
     }
-    if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-      closeMeshCompletion(completion);
-      throw wireReplyFailureException(
-        completion.terminalResult,
-        completion.failureErrno,
-        `Actor entry SPOT join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`
+    if (state.actorType === undefined)
+      throw new Error('Local Actor Join requires a registered Actor type.');
+    const actorType = state.actorType;
+    const previousSpotId = state.spotId;
+    const spotGeneration = target.targetSpotGeneration;
+    if (
+      spotGeneration === undefined ||
+      spotGeneration <= 0n ||
+      node.restoreActorAuthority === undefined
+    ) {
+      throw new Error(
+        'Local Actor Join requires a valid target generation and stateful membership runtime.'
       );
     }
-
-    state.setNativeActorRef(control.actor as never);
-    state.clearJoinedSpot();
-    state.setRemoteActorPacketTarget(undefined);
-    if (state.actorType !== undefined) {
-      this.options.postCommitLocation?.leftEventually(
-        state.actorType,
+    const membershipEpoch = location.membershipEpoch + 1n;
+    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
+        );
+      }
+      const committedActor = node.restoreActorAuthority!(
         actor.context.actorId,
-        toFrameworkRoutingId(control.location.spotId ?? spotRouteTarget?.spotId ?? nodeRid),
-        control.location.spotGeneration,
-        control.location.membershipEpoch,
-        node.status().lifecycleGeneration
+        actorType,
+        actorRef.generation,
+        state.locationGeneration ?? actorRef.generation,
+        target.spotKind === ZLinkSpotKind.Entry ? undefined : String(target.spotId),
+        spotGeneration,
+        membershipEpoch
+      );
+      state.setNativeActorRef(committedActor);
+      if (target.spotKind === ZLinkSpotKind.Entry) state.clearJoinedSpot();
+      else state.setJoinedSpot(target.spotId, spot, membershipEpoch, spotGeneration);
+      state.setRemoteActorPacketTarget(
+        target.spotKind === ZLinkSpotKind.Entry ? undefined : target
+      );
+    };
+    const leaveSource = async (): Promise<void> => {
+      void this.options.localSourceLeave?.(actor, previousSpotId, signal).catch((error) => {
+        this.options.reportSourceLeaveError(error);
+      });
+    };
+    let response: ZLinkSpotActorJoinResult;
+    if (target.spotKind === ZLinkSpotKind.Entry) {
+      if (this.options.localEntryJoin === undefined)
+        throw new Error('Local Entry Actor Join runtime is not configured.');
+      await commit();
+      try {
+        await this.options.localEntryJoin(actor, signal);
+      } finally {
+        await leaveSource();
+      }
+      response = { accepted: true };
+    } else {
+      if (this.options.localSpotJoin === undefined)
+        throw new Error('Local Spot Actor Join runtime is not configured.');
+      response = await this.options.localSpotJoin(
+        target.spotId,
+        actor,
+        request,
+        commit,
+        signal,
+        leaveSource,
+        frameworkPayloadContentType(request)
       );
     }
-    await this.options.postCommitBinder?.bind(
-      toFrameworkActorRef(control.actor as never, actorMeshName)
-    );
-    try {
-      return {
-        accepted: true,
-        actor: toFrameworkActorRef(control.actor as never, actorMeshName),
-        reply: completion.parts[0]
-      };
-    } finally {
-      disposeParts(completion.parts.slice(1));
-    }
+    return {
+      accepted: response.accepted,
+      actor: toFrameworkActorRef(state.nativeActorRef ?? actorRef, meshName),
+      reply: response.reply as Message | undefined
+    };
   }
 
   private async waitForJoinCompletion(
@@ -463,7 +459,7 @@ export class ZLinkLocalNativeActorJoin {
                 ...(completionOperationId === undefined
                   ? {}
                   : {
-                      replyContentType: control.replyContentType ?? 'application/octet-stream'
+                      replyContentType: control.replyContentType ?? ZlinkStreamContentType.Raw
                     }),
                 reply:
                   completionOperationId === undefined
@@ -569,7 +565,7 @@ function legacyRemoteActorJoinPayload(
   // authority fence.
   const payload = Buffer.from(
     JSON.stringify({
-      packetName: '__zlink.actor.join_spot.request',
+      packetName: ZLINK_REMOTE_ACTOR_JOIN_PACKET,
       phase: 'admission',
       transferId,
       spotId: String(target.spotId),
@@ -585,7 +581,7 @@ function legacyRemoteActorJoinPayload(
   );
   return {
     packetName: ZLINK_FRAMEWORK_ACTOR_JOIN_PACKET_NAME,
-    contentType: 'application/json',
+    contentType: ZlinkStreamContentType.Json,
     payload,
     // Older in-process MeshNode adapters consume the fallback as a Message.
     // Keep that structural view without changing the typed service payload.
@@ -624,7 +620,9 @@ async function submitJoinWhenConnected<T>(
   timeoutMs: number | undefined,
   signal: AbortSignal | undefined
 ): Promise<T> {
-  const deadline = performance.now() + Math.min(timeoutMs ?? 5_000, 5_000);
+  const deadline =
+    performance.now() +
+    Math.min(timeoutMs ?? LOCAL_JOIN_RESOLUTION_TIMEOUT_MS, LOCAL_JOIN_RESOLUTION_TIMEOUT_MS);
   for (;;) {
     throwIfAborted(signal);
     try {
@@ -633,7 +631,7 @@ async function submitJoinWhenConnected<T>(
       if (!isBackendNotConnectedError(error) || performance.now() >= deadline) {
         throw error;
       }
-      await new Promise<void>((resolve) => setTimeout(resolve, 10));
+      await new Promise<void>((resolve) => setTimeout(resolve, LOCAL_JOIN_POLL_INTERVAL_MS));
     }
   }
 }