@zlink-systems/framework 0.25.0 → 0.27.0

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 {
@@ -185,7 +187,12 @@ interface ActiveHandoff {
   readonly sourceEvidence: ReplySourceEvidence;
   readonly sourceOwner: ZLinkActorMessageFollowOwnerFence;
   phase: 'provisional' | 'releasing' | 'relocating';
-  readonly operationId?: string;
+  /**
+   * True for the handoff a deferred Join started. The handoff is keyed by
+   * its Actor; the public Join OperationId is a completion idempotency ID and
+   * never identifies the handoff (Spot Actor membership section 4).
+   */
+  readonly deferredJoin: boolean;
   replay?: ZLinkActorHandoffDispatch;
   connectionBoundSealed: boolean;
   readonly pending: PendingPacket[];
@@ -300,22 +307,17 @@ export class ZLinkActorHandoffCoordinator {
   }
 
   begin(actorId: string, oldGeneration: bigint): void {
-    this.startHandoff(actorId, oldGeneration, { phase: 'relocating' });
+    this.startHandoff(actorId, oldGeneration, 'relocating');
   }
 
-  beginProvisional(actorId: string, operationId: string, oldGeneration: bigint): void {
-    this.startHandoff(actorId, oldGeneration, { phase: 'provisional', operationId });
+  beginProvisional(actorId: string, oldGeneration: bigint): void {
+    this.startHandoff(actorId, oldGeneration, 'provisional');
   }
 
   private startHandoff(
     actorId: string,
     oldGeneration: bigint,
-    transition:
-      | { readonly phase: 'relocating' }
-      | {
-          readonly phase: 'provisional';
-          readonly operationId: string;
-        }
+    phase: 'relocating' | 'provisional'
   ): void {
     if (this.active.has(actorId)) {
       throw new Error(`Actor '${actorId}' already has an active packet handoff.`);
@@ -363,8 +365,8 @@ export class ZLinkActorHandoffCoordinator {
       oldNodeRidHex: sourceEvidence.nodeRidHex,
       sourceEvidence,
       sourceOwner,
-      phase: transition.phase,
-      ...(transition.phase === 'provisional' ? { operationId: transition.operationId } : {}),
+      phase,
+      deferredJoin: phase === 'provisional',
       connectionBoundSealed: false,
       pending: [],
       nextIndex: 0,
@@ -381,14 +383,11 @@ export class ZLinkActorHandoffCoordinator {
     return this.active.get(actorId)?.phase === 'provisional';
   }
 
-  promoteProvisional(actorId: string, operationId: string): void {
+  promoteProvisional(actorId: string): void {
     const handoff = this.active.get(actorId);
-    if (handoff === undefined) {
+    if (handoff?.phase !== 'provisional') {
       throw new Error(`Actor '${actorId}' does not have a provisional packet handoff.`);
     }
-    if (handoff.phase !== 'provisional' || handoff.operationId !== operationId) {
-      throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
-    }
     handoff.phase = 'relocating';
   }
 
@@ -403,14 +402,13 @@ export class ZLinkActorHandoffCoordinator {
 
   async releaseDeferred(
     actorId: string,
-    operationId: string,
     dispatch?: ZLinkActorHandoffDispatch,
     admission?: ZLinkActorHandoffReplayAdmission
   ): Promise<void> {
     const handoff = this.active.get(actorId);
     if (handoff === undefined) return;
-    if (handoff.operationId !== operationId) {
-      throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+    if (!handoff.deferredJoin) {
+      throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
     }
     await this.releaseHandoff(actorId, handoff, dispatch ?? handoff.replay, admission);
   }
@@ -434,15 +432,14 @@ export class ZLinkActorHandoffCoordinator {
    */
   admitDeferredPrefix(
     actorId: string,
-    operationId: string,
     queue: ZLinkActorHandoffPrefixQueue,
     preparation?: ZLinkActorHandoffReplayPreparation,
     start: Promise<void> = Promise.resolve()
   ): ZLinkActorHandoffPrefixAdmission {
     const handoff = this.active.get(actorId);
     if (handoff === undefined) return { terminal: Promise.resolve() };
-    if (handoff.operationId !== operationId) {
-      throw new Error(`Actor '${actorId}' packet handoff belongs to another operation.`);
+    if (!handoff.deferredJoin) {
+      throw new Error(`Actor '${actorId}' packet handoff was not started by a deferred Join.`);
     }
     return this.admitHandoffPrefix(actorId, handoff, queue, preparation, start);
   }
@@ -740,6 +737,19 @@ export class ZLinkActorHandoffCoordinator {
     pending.reject?.(error);
   }
 
+  /**
+   * Expired-owner terminal of a relocation (spec 28 §4.4): every pending
+   * record without a terminal fails once with `reason`. The handoff stays
+   * active, so the source never dispatches the Actor again.
+   */
+  failPending(actorId: string, reason: unknown): void {
+    const handoff = this.active.get(actorId);
+    if (handoff === undefined) return;
+    for (const pending of handoff.pending.splice(0)) this.failReleasedPending(pending, reason);
+    handoff.snapshotIndex = -1;
+    handoff.pendingBytes = 0;
+  }
+
   cancel(actorId: string): void {
     const handoff = this.active.get(actorId);
     if (handoff === undefined) return;
@@ -1437,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) {