@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,238 @@
+import type {
+  ActorRef,
+  RoutingId,
+  ZLinkActor,
+  ZLinkMessageSerializer
+} from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
+import type { ZLinkLocationLifecycle } from '../locations';
+import { throwIfAborted } from '../abort';
+import type {
+  ZLinkSpotRouteResolver
+} from '../spots/spot-routing-internal';
+import type { ZLinkActorJoinCoordinator, ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
+import type { ZLinkActorSourceTransfer } from './actor-source-transfer';
+import { ZLinkActorRuntimeState, toFrameworkRoutingId } from './actor-runtime-state';
+import { lookupNativeActorRef } from './actor-native-lookup';
+import { ZLinkPostCommitActorLocation } from './post-commit-actor-location';
+import { ZLinkLocalNativeActorJoin } from './actor-local-native-join';
+import { ZLinkPostCommitActorBinder } from './post-commit-actor-binder';
+import { operationIdentityKey } from '../foundation/operation-identity';
+import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+
+export interface ZLinkActorNativeJoinCoordinatorOptions {
+  readonly messageFlow?: () =>
+    import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
+  readonly node: ZLinkBackendMeshNode | (() => ZLinkBackendMeshNode);
+  readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
+  readonly spotRouteResolver?: ZLinkSpotRouteResolver;
+  readonly locationLifecycle?: ZLinkLocationLifecycle;
+  readonly remoteActorBinder?: (actorRef: ActorRef, signal?: AbortSignal, force?: boolean) => Promise<void>;
+  readonly postCommitErrorReporter?: (error: unknown) => void;
+  readonly sourceTransfer?: ZLinkActorSourceTransfer;
+  readonly actorJoinRelocation?: ZLinkActorJoinRelocation;
+  readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+  readonly shutdownSignal?: AbortSignal;
+  readonly actorTransferTimeoutMs?: number;
+  readonly entrySpotIdProvider?: (meshName: string | undefined) => string | undefined;
+}
+
+/** Selects local native join or remote two-phase transfer for each destination. */
+export class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCoordinator {
+  private readonly localJoin: ZLinkLocalNativeActorJoin;
+
+  messageFlow(): import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined {
+    return this.options.messageFlow?.();
+  }
+
+  constructor(private readonly options: ZLinkActorNativeJoinCoordinatorOptions) {
+    const postCommitLocation = options.locationLifecycle === undefined
+      ? undefined
+      : new ZLinkPostCommitActorLocation({
+          lifecycle: options.locationLifecycle,
+          reportError: options.postCommitErrorReporter,
+          signal: options.shutdownSignal
+        });
+    this.localJoin = new ZLinkLocalNativeActorJoin({
+      postCommitLocation,
+      postCommitBinder: options.remoteActorBinder === undefined
+        ? undefined
+        : new ZLinkPostCommitActorBinder({
+            bind: (actorRef, force) => options.remoteActorBinder!(actorRef, undefined, force),
+            reportError: options.postCommitErrorReporter,
+            signal: options.shutdownSignal
+          }),
+      completionTableProvider: options.completionTableProvider,
+      actorJoinRelocation: options.actorJoinRelocation,
+      messageSerializers: options.messageSerializers
+    });
+  }
+
+  beginDeferredJoin(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    operationId: import('../../contracts').ZLinkActorJoinOperationId
+  ): void {
+    this.options.sourceTransfer?.beginDeferredActorHandoff?.(
+      actor,
+      state,
+      operationIdentityKey(operationId)
+    );
+  }
+
+  async abortDeferredJoin(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    operationId: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<void> {
+    await this.options.sourceTransfer?.cancelDeferredActorHandoff?.(
+      actor,
+      state,
+      operationIdentityKey(operationId)
+    );
+  }
+
+  async joinSpot(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    spotId: RoutingId,
+    request: Message,
+    timeoutMs: number | undefined,
+    signal: AbortSignal | undefined,
+    completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
+    throwIfAborted(signal);
+    const node = this.node();
+    const actorRef = state.nativeActorRef ?? lookupNativeActorRef(node, actor.context.actorId) ?? node.createActor(actor.context.actorId);
+    state.setNativeActorRef(actorRef as never);
+    let target: Awaited<ReturnType<ZLinkSpotRouteResolver['resolve']>> | undefined;
+    target = await this.options.spotRouteResolver?.resolve(spotId, signal);
+    installResolvedSpotRoute(node, target);
+    const result = await this.localJoin.joinSpot(
+      node,
+      actor,
+      state,
+      actorRef,
+      spotId,
+      target,
+      request,
+      timeoutMs ?? this.options.actorTransferTimeoutMs,
+      signal,
+      completionOperationId
+    );
+    return this.withDeferredJoinFinalizer(
+      actor,
+      state,
+      target,
+      result,
+      completionOperationId
+    );
+  }
+
+  async joinEntrySpot(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    nodeRid: RoutingId | undefined,
+    request: Message,
+    timeoutMs: number | undefined,
+    signal: AbortSignal | undefined,
+    completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<ZLinkActorJoinRuntimeResult<Message>> {
+    throwIfAborted(signal);
+    const node = this.node();
+    const actorRef = state.nativeActorRef ?? lookupNativeActorRef(node, actor.context.actorId) ?? node.createActor(actor.context.actorId);
+    state.setNativeActorRef(actorRef as never);
+    const meshName = state.meshName ?? actor.context.meshName;
+    const entrySpotId = this.options.entrySpotIdProvider?.(meshName);
+    let resolvedTarget: Awaited<ReturnType<ZLinkSpotRouteResolver['resolve']>> | undefined;
+    resolvedTarget = entrySpotId === undefined
+      ? undefined
+      : await this.options.spotRouteResolver?.resolve(entrySpotId, signal);
+    // The caller may carry the Entry node from the previous membership.
+    // Entry placement can change while the Actor is in a User Spot, so the
+    // current authority route is the source of truth whenever it is available.
+    const selectedNodeRid = resolvedTarget?.targetNodeRid
+      ?? nodeRid
+      ?? state.entryNodeRid
+      ?? toFrameworkRoutingId(node.status().routingId);
+    const target = resolvedTarget;
+    const result = await this.localJoin.joinEntrySpot(
+      node,
+      actor,
+      state,
+      actorRef,
+      selectedNodeRid,
+      target,
+      request,
+      timeoutMs ?? this.options.actorTransferTimeoutMs,
+      signal,
+      completionOperationId
+    );
+    return this.withDeferredJoinFinalizer(
+      actor,
+      state,
+      target,
+      result,
+      completionOperationId
+    );
+  }
+
+  private withDeferredJoinFinalizer(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    target: Awaited<ReturnType<ZLinkSpotRouteResolver['resolve']>> | undefined,
+    result: ZLinkActorJoinRuntimeResult<Message>,
+    operationId: import('../../contracts').ZLinkActorJoinOperationId | undefined
+  ): ZLinkActorJoinRuntimeResult<Message> {
+    if (operationId === undefined || this.options.sourceTransfer === undefined) return result;
+    const key = operationIdentityKey(operationId);
+    return {
+      ...result,
+      finalizeDeferredJoin: async () => {
+        if (result.accepted && result.actor !== undefined && target !== undefined) {
+          await this.options.sourceTransfer!.completeDeferredActorHandoff?.(
+            actor,
+            target,
+            result.actor,
+            key
+          );
+        } else {
+          await this.options.sourceTransfer!.cancelDeferredActorHandoff?.(actor, state, key);
+        }
+      }
+    };
+  }
+
+  private node(): ZLinkBackendMeshNode {
+    return typeof this.options.node === 'function'
+      ? this.options.node()
+      : this.options.node;
+  }
+}
+
+function installResolvedSpotRoute(
+  node: ZLinkBackendMeshNode,
+  target: Awaited<ReturnType<ZLinkSpotRouteResolver['resolve']>> | undefined
+): void {
+  if (
+    target?.targetSpotGeneration === undefined
+    || target.targetNodeGeneration === undefined
+    || target.authorityOwnerGeneration === undefined
+    || target.ownerLeaseGeneration === undefined
+    || target.authorityStoreVersion === undefined
+  ) {
+    return;
+  }
+  node.rememberSpotRoute?.({
+    spot: {
+      spotId: String(target.spotId),
+      generation: target.targetSpotGeneration
+    },
+    targetNodeRid: String(target.targetNodeRid),
+    targetNodeGeneration: target.targetNodeGeneration,
+    authorityOwnerGeneration: target.authorityOwnerGeneration,
+    ownerLeaseGeneration: target.ownerLeaseGeneration,
+    storeVersion: target.authorityStoreVersion
+  });
+}

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

@@ -0,0 +1,169 @@
+import type { RoutingId, SpotId } from '../../contracts';
+import { decodeRoutingId } from '../routing-id';
+
+export const ZLINK_REMOTE_ACTOR_JOIN_PACKET = '__zlink.actor.join_spot.request';
+export const ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL =
+  '__zlink.actor.source_leave.terminal';
+export const REMOTE_ACTOR_JOIN_PACKET = ZLINK_REMOTE_ACTOR_JOIN_PACKET;
+export const REMOTE_ACTOR_JOIN_ADMISSION = 'admission';
+export const REMOTE_ACTOR_JOIN_COMMIT = 'commit';
+export const REMOTE_ACTOR_JOIN_ABORT = 'abort';
+export type ZLinkRemoteActorJoinPhase =
+  | typeof REMOTE_ACTOR_JOIN_ADMISSION
+  | typeof REMOTE_ACTOR_JOIN_COMMIT
+  | typeof REMOTE_ACTOR_JOIN_ABORT;
+
+export interface ZLinkRemoteActorSourceLeaveTerminal {
+  readonly packetName: typeof ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL;
+  readonly transferId: string;
+  readonly actorId: string;
+  readonly succeeded: boolean;
+}
+
+export function decodeRemoteActorSourceLeaveTerminal(
+  payload: Buffer
+): ZLinkRemoteActorSourceLeaveTerminal | undefined {
+  let decoded: unknown;
+  try {
+    decoded = JSON.parse(payload.toString());
+  } catch {
+    return undefined;
+  }
+  if (
+    typeof decoded !== 'object'
+    || decoded === null
+    || (decoded as { packetName?: unknown }).packetName
+      !== ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL
+    || typeof (decoded as { transferId?: unknown }).transferId !== 'string'
+    || typeof (decoded as { actorId?: unknown }).actorId !== 'string'
+    || typeof (decoded as { succeeded?: unknown }).succeeded !== 'boolean'
+  ) {
+    return undefined;
+  }
+  return decoded as ZLinkRemoteActorSourceLeaveTerminal;
+}
+export interface ZLinkRemoteActorJoinWirePayload {
+  readonly packetName?: unknown;
+  readonly spotId?: unknown;
+  readonly actorId?: unknown;
+  readonly actorType?: unknown;
+  readonly actorNodeRid?: unknown;
+  readonly actorNodeRidHex?: unknown;
+  readonly actorGeneration?: unknown;
+  readonly actorNodeGeneration?: unknown;
+  readonly expectedAuthorityOwnerGeneration?: unknown;
+  readonly expectedOwnerLeaseGeneration?: unknown;
+  readonly expectedMembershipEpoch?: unknown;
+  readonly actorEntryNodeRid?: unknown;
+  readonly actorEntryNodeRidHex?: unknown;
+  readonly actorCreateRequest?: unknown;
+  readonly phase?: unknown;
+  readonly transferId?: unknown;
+  readonly transferAdapterKey?: unknown;
+  readonly transferState?: unknown;
+  readonly sourceSpotId?: unknown;
+  readonly routerChannelId?: unknown;
+  readonly boundSessionRouterChannelId?: unknown;
+  readonly boundSessionTargetNodeRid?: unknown;
+  readonly boundSessionTargetNodeRidHex?: unknown;
+  readonly boundSessionSpotId?: unknown;
+  readonly boundSessionNodeRid?: unknown;
+  readonly boundSessionNodeRidHex?: unknown;
+  readonly boundSessionRid?: unknown;
+  readonly boundSessionRidHex?: unknown;
+  readonly boundSessionBindingGeneration?: unknown;
+  readonly boundSessionPreviousAuthorityOwnerGeneration?: unknown;
+  readonly boundSessionPreviousOwnerLeaseGeneration?: unknown;
+  readonly boundSessionRelocationSealId?: unknown;
+  readonly boundSessionServiceWireRelocation?: unknown;
+  readonly request?: unknown;
+  readonly requestContentType?: unknown;
+  readonly handoffBacklog?: unknown;
+  readonly completionOperationHigh?: unknown;
+  readonly completionOperationLow?: unknown;
+}
+
+export function decodeRemoteActorJoinPayload(payload: unknown): {
+  readonly spotId: SpotId;
+  readonly actorId: string;
+  readonly actorType: string;
+  readonly actorNodeRid: RoutingId;
+  readonly actorGeneration: string;
+  readonly actorNodeGeneration?: string;
+  readonly expectedAuthorityOwnerGeneration?: string;
+  readonly expectedOwnerLeaseGeneration?: string;
+  readonly sourceSpotId?: SpotId;
+  readonly routerChannelId?: string;
+  readonly boundSessionRouterChannelId?: string;
+  readonly boundSessionTargetNodeRid?: RoutingId;
+  readonly boundSessionSpotId?: SpotId;
+  readonly request: string;
+  readonly requestContentType: string;
+} {
+  if (
+    typeof payload !== 'object' ||
+    payload === null ||
+    (payload as { packetName?: unknown }).packetName !== ZLINK_REMOTE_ACTOR_JOIN_PACKET ||
+    typeof (payload as { spotId?: unknown }).spotId !== 'string' ||
+    typeof (payload as { actorId?: unknown }).actorId !== 'string' ||
+    typeof (payload as { actorType?: unknown }).actorType !== 'string' ||
+    typeof (payload as { actorNodeRid?: unknown }).actorNodeRid !== 'string' ||
+    typeof (payload as { actorGeneration?: unknown }).actorGeneration !== 'string' ||
+    typeof (payload as { request?: unknown }).request !== 'string'
+  ) {
+    throw new Error('Remote actor join payload is invalid.');
+  }
+  return {
+    spotId: requireSpotId((payload as { spotId: string }).spotId),
+    actorId: (payload as { actorId: string }).actorId,
+    actorType: (payload as { actorType: string }).actorType,
+    actorNodeRid: decodeWireRoutingId(
+      (payload as { actorNodeRid: string }).actorNodeRid,
+      optionalString(payload, 'actorNodeRidHex')
+    ),
+    actorGeneration: (payload as { actorGeneration: string }).actorGeneration,
+    actorNodeGeneration: optionalString(payload, 'actorNodeGeneration'),
+    expectedAuthorityOwnerGeneration:
+      optionalString(payload, 'expectedAuthorityOwnerGeneration'),
+    expectedOwnerLeaseGeneration:
+      optionalString(payload, 'expectedOwnerLeaseGeneration'),
+    sourceSpotId: optionalSpotId(payload, 'sourceSpotId'),
+    routerChannelId: optionalString(payload, 'routerChannelId'),
+    boundSessionRouterChannelId: optionalString(payload, 'boundSessionRouterChannelId'),
+    boundSessionTargetNodeRid: optionalRoutingId(
+      payload,
+      'boundSessionTargetNodeRid',
+      'boundSessionTargetNodeRidHex'
+    ),
+    boundSessionSpotId: optionalSpotId(payload, 'boundSessionSpotId'),
+    request: (payload as { request: string }).request,
+    requestContentType: optionalString(payload, 'requestContentType') ?? 'application/json'
+  };
+}
+
+export function decodeWireRoutingId(text: string, hex: string | undefined): RoutingId {
+  return decodeRoutingId(text, hex);
+}
+
+function optionalString(value: object, key: string): string | undefined {
+  const field = (value as Record<string, unknown>)[key];
+  return typeof field === 'string' ? field : undefined;
+}
+
+function optionalRoutingId(value: object, textKey: string, hexKey: string): RoutingId | undefined {
+  const text = optionalString(value, textKey);
+  return text === undefined ? undefined : decodeWireRoutingId(text, optionalString(value, hexKey));
+}
+
+function optionalSpotId(value: object, key: string): SpotId | undefined {
+  const text = optionalString(value, key);
+  return text === undefined ? undefined : requireSpotId(text);
+}
+
+function requireSpotId(value: string): SpotId {
+  const bytes = Buffer.byteLength(value, 'utf8');
+  if (bytes < 1 || bytes > 255) {
+    throw new Error('Remote actor SpotId must contain 1..255 UTF-8 bytes.');
+  }
+  return value;
+}

package/src/runtime/actors/actor-retry-delay.ts

@@ -0,0 +1,37 @@
+const INITIAL_RETRY_DELAY_MS = 25;
+const MAX_RETRY_DELAY_MS = 1_000;
+
+export class ZLinkActorRetryDelay {
+  private delayMs = INITIAL_RETRY_DELAY_MS;
+
+  reset(): void {
+    this.delayMs = INITIAL_RETRY_DELAY_MS;
+  }
+
+  async wait(signal: AbortSignal | undefined): Promise<boolean> {
+    const completed = await delayUnlessAborted(this.delayMs, signal);
+    if (completed) {
+      this.delayMs = Math.min(this.delayMs * 2, MAX_RETRY_DELAY_MS);
+    }
+    return completed;
+  }
+}
+
+function delayUnlessAborted(delayMs: number, signal: AbortSignal | undefined): Promise<boolean> {
+  if (signal?.aborted === true) return Promise.resolve(false);
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (completed: boolean): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      signal?.removeEventListener('abort', aborted);
+      resolve(completed);
+    };
+    const aborted = (): void => finish(false);
+    const deadline = setTimeout(() => finish(true), delayMs);
+    deadline.unref();
+    signal?.addEventListener('abort', aborted, { once: true });
+    if (signal?.aborted === true) aborted();
+  });
+}

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

@@ -0,0 +1,58 @@
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendSpot } from '../backend/contracts';
+import type { ZLinkSubmitResult } from '../messaging/submission-result';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+
+export interface ZLinkActorRoutedJoinTransport {
+  canRouteChannel?(routerChannelId: string): boolean;
+  canRoutePacketChannel?(routerChannelId: string): boolean;
+  request<TReply>(
+    routerChannelId: string,
+    targetNodeRid: string,
+    packetName: string | undefined,
+    request: unknown,
+    timeoutMs: number | undefined,
+    signal?: AbortSignal
+  ): Promise<TReply>;
+  submit?(
+    routerChannelId: string,
+    targetNodeRid: string,
+    packetName: string | undefined,
+    message: unknown,
+    signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult>;
+  submitInfrastructure?(
+    routerChannelId: string,
+    targetNodeRid: string,
+    packetName: string | undefined,
+    message: unknown,
+    signal?: AbortSignal
+  ): Promise<ZLinkSubmitResult>;
+  sendToSpot(
+    spotRouteTarget: ZLinkSpotRouteTarget,
+    message: unknown,
+    options: { readonly packetName?: string; readonly signal?: AbortSignal }
+  ): Promise<ZLinkSubmitResult>;
+  requestRawToSpot?(
+    spotRouteTarget: ZLinkSpotRouteTarget,
+    request: Message,
+    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  ): Promise<readonly Message[]>;
+  requestToSpot<TReply = unknown>(
+    spotRouteTarget: ZLinkSpotRouteTarget,
+    request: unknown,
+    options: { readonly packetName?: string; readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  ): Promise<TReply>;
+  requestFromSpotToSpot?<TReply = unknown>(
+    sourceSpot: ZLinkBackendSpot,
+    spotRouteTarget: ZLinkSpotRouteTarget,
+    request: unknown,
+    options: { readonly packetName?: string; readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  ): Promise<TReply>;
+  requestRawFromSpotToSpot?(
+    sourceSpot: ZLinkBackendSpot,
+    spotRouteTarget: ZLinkSpotRouteTarget,
+    request: Message,
+    options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+  ): Promise<readonly Message[]>;
+}

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

@@ -0,0 +1,44 @@
+import { ZLinkBufferMessage as RuntimeMessage } from '../backend/runtime-message';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
+
+export async function tryRequestRoutedJson(
+  transport: ZLinkActorRoutedJoinTransport,
+  target: ZLinkSpotRouteTarget,
+  payload: unknown,
+  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal }
+): Promise<boolean> {
+  const request = transport.requestRawToSpot;
+  if (request === undefined) return false;
+  const message = RuntimeMessage.fromOwned(Buffer.from(JSON.stringify(payload)));
+  try {
+    const replyParts = await request.call(transport, target, message, options);
+    for (const part of replyParts) part.close();
+    return true;
+  } finally {
+    message.close();
+  }
+}
+export async function requestRoutedJsonReply<T>(
+  transport: ZLinkActorRoutedJoinTransport,
+  target: ZLinkSpotRouteTarget,
+  payload: unknown,
+  options: { readonly timeoutMs?: number; readonly signal?: AbortSignal },
+  unavailableMessage: string,
+  decode: (replyParts: readonly Message[]) => T
+): Promise<T> {
+  const request = transport.requestRawToSpot;
+  if (request === undefined) throw new Error(unavailableMessage);
+  const message = RuntimeMessage.fromOwned(Buffer.from(JSON.stringify(payload)));
+  try {
+    const replyParts = await request.call(transport, target, message, options);
+    try {
+      return decode(replyParts);
+    } finally {
+      for (const part of replyParts) part.close();
+    }
+  } finally {
+    message.close();
+  }
+}

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

@@ -0,0 +1,126 @@
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type {
+  RoutingId,
+  ActorRef,
+  Type,
+  ZLinkActor,
+  ZLinkActorFactory,
+  ZLinkBoundSession,
+  ZLinkMessage,
+  ZLinkActorCreateResponse,
+  ZLinkMessageSerializer,
+} from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendMeshNode, ZLinkMeshCompletionTable } from '../backend';
+import type { ZLinkLocationLifecycle } from '../locations';
+import type { ZLinkActorRuntimeState } from './actor-runtime-state';
+import type { ZLinkActorTransferRegistry } from './actor-transfer-registry';
+import type { ZLinkRuntimeAdmissionGate } from '../admission';
+
+export interface ZLinkActorJoinRuntimeResult<TReply> {
+  readonly accepted: boolean;
+  readonly actor?: import('../../contracts').ActorRef;
+  readonly reply?: TReply;
+  /** Internal terminal work that must run after the completion callback. */
+  readonly finalizeDeferredJoin?: () => Promise<void>;
+}
+
+export interface ZLinkActorManagerOptions {
+  readonly actorFactories: ReadonlyMap<string, Type | ZLinkActorFactory>;
+  readonly joinCoordinator?: ZLinkActorJoinCoordinator;
+  readonly actorMeshNameProvider?: (actorType: string) => string | undefined;
+  readonly actorLeaveSpot?: (
+    meshName: string,
+    spotId: RoutingId,
+    actor: ZLinkActor,
+    signal?: AbortSignal
+  ) => Promise<void>;
+  readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+  readonly nativeActorNode?: ZLinkBackendMeshNode;
+  readonly nativeActorNodeProvider?: () => ZLinkBackendMeshNode | undefined;
+  readonly nativeActorCompletionTableProvider?: () => ZLinkMeshCompletionTable | undefined;
+  readonly actorCreatedNodeRidProvider?: () => RoutingId | undefined;
+  readonly actorRefResolver?: ZLinkActorRuntimeLocationLookup;
+  readonly actorCreatedNotifier?: (
+    nodeRid: RoutingId,
+    actor: ZLinkActor,
+    createRequest: ZLinkMessage,
+    signal?: AbortSignal
+  ) => Promise<ZLinkActorCreateResponse | undefined>;
+  readonly actorDestroyedCleanup?: (actorId: string) => void;
+  readonly publishActorAuthority?: (
+    actorType: string,
+    actorRef: ActorRef,
+    ownerNodeGeneration: bigint,
+    signal?: AbortSignal
+  ) => Promise<void>;
+  readonly locationLifecycle?: ZLinkLocationLifecycle;
+  readonly boundSessionFactory?: ZLinkActorBoundSessionFactory;
+  readonly providerResolver?: ZLinkProviderResolver;
+  readonly actorTransferRegistry?: ZLinkActorTransferRegistry;
+  readonly shutdownSignal?: AbortSignal;
+  readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+  readonly admission?: ZLinkRuntimeAdmissionGate;
+  readonly placementCreate?: (
+    actorId: string,
+    actorType: string,
+    createOnly: boolean,
+    options: {
+      readonly meshName?: string;
+      readonly request?: unknown;
+      readonly timeoutMs: number;
+    },
+    signal?: AbortSignal
+  ) => Promise<import('../../contracts').ZLinkActorCreateResult>;
+}
+
+export interface ZLinkActorRuntimeLocationLookup {
+  resolveActorRef(
+    actorId: string,
+    signal?: AbortSignal
+  ): Promise<ActorRef | undefined>;
+}
+
+export type ZLinkActorBoundSessionFactory = (actorId: string) => ZLinkBoundSession;
+
+export interface ZLinkActorJoinCoordinator {
+  /**
+   * The message flow tracer, when the host wired one. A deferred Join that ends
+   * in `failed` reports its cause here so the failure carries the same flow
+   * identity as the Join that produced it.
+   */
+  messageFlow?(): import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
+  /**
+   * Starts the internal packet handoff before a Deferred Join performs target
+   * lookup. This is an internal ordering fence; it is not part of the public
+   * actor context contract.
+   */
+  beginDeferredJoin?(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    operationId: import('../../contracts').ZLinkActorJoinOperationId
+  ): void;
+  abortDeferredJoin?(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    operationId: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<void>;
+  joinSpot(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    spotId: RoutingId,
+    request: Message,
+    timeoutMs: number | undefined,
+    signal: AbortSignal | undefined,
+    completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+  joinEntrySpot(
+    actor: ZLinkActor,
+    state: ZLinkActorRuntimeState,
+    nodeRid: RoutingId | undefined,
+    request: Message,
+    timeoutMs: number | undefined,
+    signal: AbortSignal | undefined,
+    completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId
+  ): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+}