@zlink-systems/framework 0.30.0 → 0.30.2

package/src/runtime/host/actor-packet-relay.ts

@@ -12,6 +12,7 @@ import type {
 } from '../../contracts';
 import { ZLinkFrameworkException, ZLinkSpotKind } from '../../contracts';
 import { ZLinkConfigurationException } from '../../contracts/Configuration/ConfigurationException';
+import { throwIfAborted } from '../abort';
 import type { Message } from '../../contracts/Common/Message';
 import {
   ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET,
@@ -38,6 +39,7 @@ import {
 } from '../actors/actor-message-follow-context';
 import { streamMetadataMap } from '../actors/bound-session-wire';
 import { decodeRoutingId, normalizeRoutingId, routingIdsEqual } from '../routing-id';
+import { encodeSessionDisconnected } from '../actors/session-disconnected-wire';
 import { ZLinkSubmitStatus } from '../messaging/submission-result';
 import type { DefaultZLinkSpotManager, ZLinkSpotNodeRuntimeManager } from '../spots';
 import type { ZLinkDetachedTaskRunner } from '../spots/spot-actor-join-dispatch';
@@ -109,37 +111,22 @@ export class ZLinkActorPacketRelay {
 
   async notifyBoundActorDisconnected(
     actor: ZLinkSessionActor,
-    signal?: AbortSignal
+    signal?: AbortSignal,
+    binding?: ServiceStreamSessionBinding
   ): Promise<void> {
-    const state = this.options.actorManager()?.getState(actor.actorId);
-    const currentRemoteBoundSessionTarget =
-      state?.spotId === undefined ? undefined : state.remoteBoundSessionTarget;
-    const currentRemoteActorPacketTarget =
-      state?.spotId === undefined ? undefined : state.remoteActorPacketTarget;
-    const remoteTarget =
-      currentRemoteBoundSessionTarget ??
-      currentRemoteActorPacketTarget ??
-      (state?.spotId === undefined ? undefined : this.targets.cachedTargetForActor(actor));
-    if (remoteTarget !== undefined) {
-      await this.notifyRemoteActorDisconnected(actor.actorId, remoteTarget, signal, actor.ref);
-      return;
-    }
+    // The Session binding owns this route, including after relocation and detach (§5, §7).
     const actorRefTarget = this.targets.targetForActorRef(actor.ref);
     if (actorRefTarget !== undefined) {
-      await this.notifyRemoteActorDisconnected(actor.actorId, actorRefTarget, signal, actor.ref);
-      return;
-    }
-    if (state?.spotId !== undefined && state.actor !== undefined) {
-      const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(
-        state.spotId,
-        state.actor,
-        signal
+      await this.notifyRemoteActorDisconnected(
+        actor.actorId,
+        actorRefTarget,
+        signal,
+        actor.ref,
+        binding
       );
-      if (handled) {
-        return;
-      }
+      return;
     }
-    await this.notifyActorDisconnectedById(actor.actorId, signal);
+    await this.notifyLocalActorDisconnectedById(actor.actorId, signal, binding, actor.ref);
   }
 
   clearRemoteActorPacketTarget(actorId: string): void {
@@ -154,44 +141,41 @@ export class ZLinkActorPacketRelay {
     return this.targets.targetForState(actorId);
   }
 
-  async notifyActorDisconnectedById(actorId: string, signal?: AbortSignal): Promise<void> {
-    const state = this.options.actorManager()?.getState(actorId);
-    const remoteTarget =
-      state === undefined
-        ? undefined
-        : (state.remoteBoundSessionTarget ?? state.remoteActorPacketTarget);
-    if (remoteTarget !== undefined) {
-      await this.notifyRemoteActorDisconnected(actorId, remoteTarget, signal);
-      return;
-    }
-    await this.notifyLocalActorDisconnectedById(actorId, signal);
-  }
-
-  async notifyLocalActorDisconnectedById(actorId: string, signal?: AbortSignal): Promise<void> {
+  async notifyLocalActorDisconnectedById(
+    actorId: string,
+    signal?: AbortSignal,
+    binding?: ServiceStreamSessionBinding,
+    bindingActorRef?: ActorRef
+  ): Promise<void> {
+    throwIfAborted(signal);
     const state = this.options.actorManager()?.getState(actorId);
-    if (state?.spotId !== undefined && state.actor !== undefined) {
-      const handled = await this.requireSpotManager().notifyJoinedSpotActorDisconnected(
-        state.spotId,
-        state.actor,
-        signal
-      );
-      if (handled) {
-        return;
-      }
-    }
-    const localActor = state?.actor;
-    if (localActor === undefined) {
-      throw new Error(`Actor '${actorId}' does not have a local actor instance.`);
-    }
-    const meshName = state?.meshName;
-    if (meshName === undefined) {
-      throw new Error(`Actor '${actorId}' does not have a RouteMesh identity.`);
+    const frame = this.disconnectedFrame(actorId, binding);
+    const header = RuntimeMessage.fromOwned(Buffer.from(frame.header));
+    const body = RuntimeMessage.fromOwned(frame.payload);
+    try {
+      if (state?.spotId === undefined)
+        await this.requireSpotNodeRuntime().dispatchEntryActorPacket(
+          'local',
+          actorId,
+          [header, body],
+          false,
+          undefined,
+          bindingActorRef
+        );
+      else
+        await this.requireSpotManager().dispatchRoutedActorPacket(
+          'local',
+          state.spotId,
+          actorId,
+          [header, body],
+          false,
+          undefined,
+          bindingActorRef
+        );
+    } finally {
+      header.close();
+      body.close();
     }
-    await this.requireSpotNodeRuntime().notifyEntrySpotActorDisconnected(
-      meshName,
-      localActor,
-      signal
-    );
   }
 
   async receiveRemoteActorPacketRelay(
@@ -285,21 +269,17 @@ export class ZLinkActorPacketRelay {
         }
         return { ok: true, response: { acknowledged: true } };
       }
-      if (frameHeader.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
-        this.requireCurrentRemoteBinding(relay, _routeContext);
-        await this.notifyLocalActorDisconnectedById(relay.actorId);
-        return {
-          ok: true,
-          actorPacketTarget: encodeRemoteActorPacketTarget(
-            this.actorPacketTargetForState(relay.actorId)
-          )
-        };
-      }
-      if (remoteBoundSessionTarget !== undefined) {
+      if (
+        remoteBoundSessionTarget !== undefined &&
+        frameHeader.name !== ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET
+      ) {
         this.requireCurrentRemoteBinding(relay, _routeContext);
       }
       const state = this.options.actorManager()?.getState(relay.actorId);
-      if (frameHeader.kind === ZLinkStreamMessageKind.Send) {
+      if (
+        frameHeader.kind === ZLinkStreamMessageKind.Send ||
+        frameHeader.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET
+      ) {
         const dispatch =
           state?.spotId === undefined
             ? this.requireSpotNodeRuntime().dispatchEntryActorPacket(
@@ -319,6 +299,15 @@ export class ZLinkActorPacketRelay {
                 remoteBoundSessionTarget,
                 fallbackActorRef
               );
+        if (frameHeader.name === ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
+          await dispatch;
+          return {
+            ok: true,
+            actorPacketTarget: encodeRemoteActorPacketTarget(
+              this.actorPacketTargetForState(relay.actorId)
+            )
+          };
+        }
         // Spec 05 §1.3: a one-way Session Actor relay completes at relay
         // queue admission, not after the remote application turn. In
         // particular, a handler may register a deferred Join whose relocation
@@ -761,23 +750,21 @@ export class ZLinkActorPacketRelay {
     actorId: string,
     remoteTarget: ZLinkRemoteBoundSessionTarget | ZLinkRemoteActorPacketTarget,
     signal?: AbortSignal,
-    bindingActorRef?: ActorRef
+    bindingActorRef?: ActorRef,
+    binding?: ServiceStreamSessionBinding
   ): Promise<void> {
     const spotKind: ZLinkSpotKind | undefined =
       'spotKind' in remoteTarget ? (remoteTarget.spotKind as ZLinkSpotKind | undefined) : undefined;
-    const header: ZLinkStreamFrameHeader = {
-      kind: ZLinkStreamMessageKind.Send,
-      codec: ZLinkStreamCodec.Raw,
-      flags: ZLinkStreamHeaderFlags.None,
-      name: ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
-      metadata: new Map()
-    };
+    const frame = this.disconnectedFrame(
+      actorId,
+      binding,
+      'sessionNodeRid' in remoteTarget ? remoteTarget : undefined
+    );
     const payload = encodeRemoteActorPacketRelayPayload({
       actorId,
       routerChannelId: remoteTarget.routerChannelId,
       bindingActorRef,
-      header: encodeStreamHeader(header),
-      payload: Buffer.alloc(0)
+      ...frame
     });
     if ((spotKind ?? ZLinkSpotKind.Entry) === ZLinkSpotKind.Entry) {
       await this.options.routeTransport.request(
@@ -806,20 +793,37 @@ export class ZLinkActorPacketRelay {
     );
   }
 
+  private disconnectedFrame(
+    actorId: string,
+    binding?: ServiceStreamSessionBinding,
+    target?: ZLinkRemoteBoundSessionTarget
+  ) {
+    const current =
+      binding === undefined
+        ? (this.options.actorManager()?.getState(actorId)?.boundSession ?? target)
+        : undefined;
+    const header: ZLinkStreamFrameHeader = {
+      kind: ZLinkStreamMessageKind.Send,
+      codec: ZLinkStreamCodec.Raw,
+      flags: ZLinkStreamHeaderFlags.None,
+      name: ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
+      metadata: new Map()
+    };
+    return {
+      header: encodeStreamHeader(header),
+      payload: encodeSessionDisconnected(
+        binding?.sessionOwnerNodeRid ?? current?.sessionNodeRid,
+        binding?.sessionOwnerNodeGeneration ?? current?.sessionOwnerNodeGeneration,
+        binding?.bindingGeneration ?? current?.bindingGeneration
+      )
+    };
+  }
+
   private requireCurrentRemoteBinding(
     relay: ReturnType<typeof decodeRemoteActorPacketRelayPayload>,
     routeContext: ZLinkRouteMessageContext
   ): void {
-    const state = this.options.actorManager()?.getState(relay.actorId);
-    const current = state?.boundSession;
-    if (
-      current === undefined ||
-      current.sessionNodeRid === undefined ||
-      !routingIdsEqual(current.sessionNodeRid, routeContext.sourceNodeRid) ||
-      current.bindingGeneration === undefined ||
-      relay.bindingGeneration === undefined ||
-      current.bindingGeneration !== BigInt(relay.bindingGeneration)
-    ) {
+    if (!this.matchesCurrentRemoteBinding(relay, routeContext)) {
       throw createInternalFrameworkException(
         ZLinkFrameworkInternalErrorKind.ActorSessionNotBound,
         `Actor '${relay.actorId}' bound session identity is stale.`,
@@ -828,6 +832,21 @@ export class ZLinkActorPacketRelay {
     }
   }
 
+  private matchesCurrentRemoteBinding(
+    relay: ReturnType<typeof decodeRemoteActorPacketRelayPayload>,
+    routeContext: ZLinkRouteMessageContext
+  ): boolean {
+    const current = this.options.actorManager()?.getState(relay.actorId)?.boundSession;
+    return (
+      current !== undefined &&
+      current.sessionNodeRid !== undefined &&
+      routingIdsEqual(current.sessionNodeRid, routeContext.sourceNodeRid) &&
+      current.bindingGeneration !== undefined &&
+      relay.bindingGeneration !== undefined &&
+      current.bindingGeneration === BigInt(relay.bindingGeneration)
+    );
+  }
+
   private async requestRemoteTarget<TReply>(
     target: ZLinkRemoteActorPacketTarget,
     request: Record<string, unknown>,

package/src/runtime/host/actor-placement-coordinator.ts

@@ -1,6 +1,8 @@
+import { encodeRoutingIdStorageHex, routingIdsEqual } from '../routing-id';
 import {
   ZLinkFrameworkInternalErrorKind,
   createInternalFrameworkException,
+  internalFrameworkErrorKindFromWireReply,
   wireReplyFailureException
 } from '../framework-errors-internal';
 import { createHash } from 'node:crypto';
@@ -9,6 +11,7 @@ import type { ActorRef, RoutingId, ZLinkActorCreateResult } from '../../contract
 import { ZLinkSpotKind } from '../../contracts';
 import type {
   ZLinkAuthoritySnapshot,
+  ZLinkAuthorityReadResult,
   ZLinkCreationOperationIdentity,
   ZLinkLocationOwnerToken,
   ZLinkObjectReserveResult,
@@ -102,6 +105,15 @@ export class ZLinkActorPlacementCoordinator {
       for (;;) {
         const target = await this.options.target(meshName, stableType, deadline.signal, excluded);
         if (target === undefined) {
+          // Entry eligibility limits new creation, not lookup of a Ready Actor (Actor model §6.3, §6.5).
+          if (!createOnly) {
+            const current = await this.options.store.readAuthority(
+              encodeAuthorityKey('actor', actorId),
+              deadline.signal
+            );
+            const existing = existingActor(current, actorId, stableType);
+            if (existing !== undefined) return { status: 'existing', actor: existing };
+          }
           throw createInternalFrameworkException(
             ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted,
             `No eligible Actor placement target is ready for '${stableType}'.`,
@@ -158,7 +170,7 @@ export class ZLinkActorPlacementCoordinator {
           );
         }
         if (reserved.kind === 'placementCapacityExhausted') {
-          excluded.add(String(target.nodeRid));
+          excluded.add(encodeRoutingIdStorageHex(target.nodeRid));
           continue;
         }
         if (reserved.kind === 'alreadyExists' || reserved.kind === 'conflict') {
@@ -203,6 +215,15 @@ export class ZLinkActorPlacementCoordinator {
           }
         }
         if (remote === undefined) throw transportFailure;
+        if (
+          internalFrameworkErrorKindFromWireReply(remote.terminalResult, remote.failureCode) ===
+          ZLinkFrameworkInternalErrorKind.RouteNotConnected
+        ) {
+          //  The target refused before the callback and cancelled its reservation
+          //  (Actor model §6.3); exclude this host run like a Reserve failure.
+          excluded.add(encodeRoutingIdStorageHex(target.nodeRid));
+          continue;
+        }
         if (remote.terminalResult !== RequestResult.Ok || remote.failureCode !== 0) {
           //  Classify the (terminal, fine failure code) pair via the shared
           //  ownership-aware translator instead of collapsing every non-OK
@@ -443,16 +464,18 @@ function creationTarget(snapshot: ZLinkAuthoritySnapshot) {
 }
 
 function existingActor(
-  reserved: ZLinkObjectReserveResult,
+  current: ZLinkObjectReserveResult | ZLinkAuthorityReadResult,
   actorId: string,
   stableType: string
 ): ActorRef | undefined {
   const snapshot =
-    reserved.kind === 'alreadyExists'
-      ? reserved.current
-      : reserved.kind === 'conflict' && reserved.current.kind === 'snapshot'
-        ? reserved.current
-        : undefined;
+    current.kind === 'snapshot'
+      ? current
+      : current.kind === 'alreadyExists'
+        ? current.current
+        : current.kind === 'conflict' && current.current.kind === 'snapshot'
+          ? current.current
+          : undefined;
   if (
     snapshot === undefined ||
     snapshot.allocation.state !== 'active' ||
@@ -542,7 +565,7 @@ function requireExactReservation(
     current.allocation.stableType !== record.stableType ||
     current.objectGeneration !== record.reservation.objectGeneration ||
     current.authorityOwnerGeneration !== record.reservation.authorityOwnerGeneration ||
-    String(current.allocation.descriptor.rid) !== record.reservation.targetNodeRid ||
+    !routingIdsEqual(current.allocation.descriptor.rid, record.reservation.targetNodeRid) ||
     current.allocation.descriptorLifecycleGeneration !== record.reservation.targetNodeGeneration ||
     current.ownerId !== record.reservation.targetOwnerId ||
     current.ownerLeaseGeneration !== record.reservation.targetOwnerLeaseGeneration ||

package/src/runtime/host/actor-runtime-options-factory.ts

@@ -276,7 +276,15 @@ export class ZLinkActorRuntimeOptionsFactory {
       staleActorRefPredicate: (meshName, actor) =>
         this.actorBelongsToMesh(meshName, actor.actorId) &&
         this.options.actorHandoff.isKnownStale(actor),
-      handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs) =>
+      handoffCapture: (
+        meshName,
+        actorId,
+        parts,
+        returnResponse,
+        actor,
+        deadlineUnixMs,
+        onAdmitted
+      ) =>
         this.actorBelongsToMesh(meshName, actorId) &&
         !this.options.actorHandoff.isProvisional(actorId)
           ? this.options.actorHandoff.capture(
@@ -286,7 +294,10 @@ export class ZLinkActorRuntimeOptionsFactory {
               returnResponse,
               undefined,
               actor,
-              deadlineUnixMs
+              deadlineUnixMs,
+              undefined,
+              undefined,
+              onAdmitted
             )
           : undefined,
       sendErrorReporter: this.options.reportPostCommitError