@zlink-systems/framework 0.25.0 → 0.27.0

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 { ZLinkFrameworkErrorKind, 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(
@@ -391,13 +387,7 @@ export class ZLinkLocalNativeActorJoin {
       //  (spec 32-framework-error-model:83-118); an OK terminal with no join
       //  control is a protocol violation.
       throw admission.terminalResult !== 0 || admission.failureErrno !== 0
-        ? remoteActorJoinFailureException(
-            node,
-            target,
-            admission.terminalResult,
-            admission.failureErrno,
-            message
-          )
+        ? wireReplyFailureException(admission.terminalResult, admission.failureErrno, message)
         : createInternalFrameworkException(
             ZLinkFrameworkInternalErrorKind.RequestProtocolError,
             message
@@ -419,9 +409,7 @@ export class ZLinkLocalNativeActorJoin {
     }
     if (admission.terminalResult !== 0 || admission.failureErrno !== 0) {
       closeMeshCompletion(admission);
-      throw remoteActorJoinFailureException(
-        node,
-        target,
+      throw wireReplyFailureException(
         admission.terminalResult,
         admission.failureErrno,
         `Actor admission failed for '${actor.context.actorId}' with result '${admission.terminalResult}' and errno '${admission.failureErrno}'.`
@@ -471,7 +459,7 @@ export class ZLinkLocalNativeActorJoin {
                 ...(completionOperationId === undefined
                   ? {}
                   : {
-                      replyContentType: control.replyContentType ?? 'application/octet-stream'
+                      replyContentType: control.replyContentType ?? ZlinkStreamContentType.Raw
                     }),
                 reply:
                   completionOperationId === undefined
@@ -577,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),
@@ -593,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.
@@ -613,37 +601,6 @@ function canonicalHandoffRelocationId(handoffId: string): string {
   );
 }
 
-function remoteActorJoinFailureException(
-  node: ZLinkBackendMeshNode,
-  target: ZLinkSpotRouteTarget,
-  terminalResult: number,
-  failureErrno: number,
-  message: string
-) {
-  const failure = wireReplyFailureException(terminalResult, failureErrno, message);
-  const targetGeneration = target.targetNodeGeneration;
-  if (
-    failure.kind === ZLinkFrameworkErrorKind.DeadlineExceeded &&
-    targetGeneration !== undefined &&
-    targetGeneration !== 0n &&
-    !node
-      .peers()
-      .some(
-        (peer) =>
-          peer.state === 3 &&
-          peer.routingId !== null &&
-          routingIdsEqual(peer.routingId, target.targetNodeRid) &&
-          peer.lifecycleGeneration === targetGeneration
-      )
-  ) {
-    return createInternalFrameworkException(
-      ZLinkFrameworkInternalErrorKind.RouteNotConnected,
-      'wire Actor join target RouteMesh peer became unavailable'
-    );
-  }
-  return failure;
-}
-
 function runtimeActorMeshName(
   actor: ZLinkActor,
   state: ZLinkActorRuntimeState,
@@ -663,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 {
@@ -672,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));
     }
   }
 }

package/src/runtime/actors/actor-native-lookup.ts

@@ -1,3 +1,4 @@
+import { ConfigError, ConfigResult } from '@zlink-systems/zlink';
 import type {
   ZLinkBackendActorRef,
   ZLinkBackendMeshNode,
@@ -22,17 +23,9 @@ export function lookupNativeActorRef(
       generation: actor.generation
     };
   } catch (error) {
-    if (nativeErrno(error) === 2) {
+    if (error instanceof ConfigError && error.result === ConfigResult.NotFound) {
       return undefined;
     }
     throw error;
   }
 }
-
-function nativeErrno(error: unknown): number | undefined {
-  if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
-    return undefined;
-  }
-  const value = error.nativeErrno;
-  return typeof value === 'number' ? value : undefined;
-}

package/src/runtime/actors/actor-packet-relay-wire.ts

@@ -1,11 +1,12 @@
-import type { ActorRef, RoutingId } from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
+import { type ActorRef, type RoutingId, ZLinkSpotKind } from '../../contracts';
+
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
 import { decodeRoutingId, routingIdWireHex } from '../routing-id';
-import type { ZLinkRemoteActorPacketTarget } from './actor-runtime-state';
 import {
   decodeActorMessageFollowContext,
   type ZLinkActorMessageFollowContext
 } from './actor-message-follow-context';
+import type { ZLinkRemoteActorPacketTarget } from './actor-runtime-state';
 
 export const ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = '__zlink.actor.packet.relay';
 export const ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET =
@@ -48,6 +49,7 @@ export function encodeRemoteActorPacketRelayPayload(input: {
   readonly header: Uint8Array;
   readonly payload: Uint8Array;
   readonly bindingActorRef?: ActorRef;
+  readonly bindingGeneration?: bigint;
   /** The actor reference used to preserve relocation context at the target Spot. */
   readonly actorRef?: ActorRef;
   readonly returnResponse?: boolean;
@@ -70,13 +72,15 @@ export function encodeRemoteActorPacketRelayPayload(input: {
         ? undefined
         : routingIdWireHex(input.bindingActorRef.nodeRid),
     bindingActorGeneration: input.bindingActorRef?.objectGeneration.toString(),
-    bindingGeneration: (
-      input.bindingActorRef as
-        | (ActorRef & {
-            readonly bindingGeneration?: bigint;
-          })
-        | undefined
-    )?.bindingGeneration?.toString(),
+    bindingGeneration:
+      input.bindingGeneration?.toString() ??
+      (
+        input.bindingActorRef as
+          | (ActorRef & {
+              readonly bindingGeneration?: bigint;
+            })
+          | undefined
+      )?.bindingGeneration?.toString(),
     returnResponse: input.returnResponse,
     messageFollowContext: input.messageFollowContext,
     header: Buffer.from(input.header).toString('base64'),
@@ -169,8 +173,10 @@ export function decodeRemoteActorPacketTarget(
 
 function requireSpotId(value: string): string {
   const bytes = Buffer.byteLength(value, 'utf8');
-  if (bytes < 1 || bytes > 255) {
-    throw new Error('Actor packet target SpotId must contain 1..255 UTF-8 bytes.');
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES) {
+    throw new Error(
+      `Actor packet target SpotId must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`
+    );
   }
   return value;
 }