@zlink-systems/framework 0.26.0 → 0.27.0

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;
 }

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

@@ -11,12 +11,14 @@ import type {
 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 type { ZLinkActorJoinRelocation } from './actor-join-relocation';
 
-export interface ZLinkActorNativeJoinCoordinatorOptions {
+export interface ZLinkActorNativeJoinCoordinatorOptions extends Pick<
+  import('./actor-local-native-join').ZLinkLocalNativeActorJoinOptions,
+  'localSpotJoin' | 'localEntryJoin' | 'localSourceLeave' | 'reportSourceLeaveError'
+> {
   readonly messageFlow?: () =>
     import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
   readonly node: ZLinkBackendMeshNode | (() => ZLinkBackendMeshNode);
@@ -46,16 +48,12 @@ export class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCoordinato
   }
 
   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,
+      locationLifecycle: options.locationLifecycle,
+      localSpotJoin: options.localSpotJoin,
+      localEntryJoin: options.localEntryJoin,
+      localSourceLeave: options.localSourceLeave,
+      reportSourceLeaveError: options.reportSourceLeaveError,
       postCommitBinder:
         options.remoteActorBinder === undefined
           ? undefined

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

@@ -1,3 +1,5 @@
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
+import { ZlinkStreamContentType } from '@zlink-systems/stream-wire';
 import type { RoutingId, SpotId } from '../../contracts';
 import { decodeRoutingId } from '../routing-id';
 
@@ -133,7 +135,7 @@ export function decodeRemoteActorJoinPayload(payload: unknown): {
     ),
     boundSessionSpotId: optionalSpotId(payload, 'boundSessionSpotId'),
     request: (payload as { request: string }).request,
-    requestContentType: optionalString(payload, 'requestContentType') ?? 'application/json'
+    requestContentType: optionalString(payload, 'requestContentType') ?? ZlinkStreamContentType.Json
   };
 }
 
@@ -158,8 +160,8 @@ function optionalSpotId(value: object, key: string): SpotId | undefined {
 
 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.');
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES) {
+    throw new Error(`Remote actor SpotId must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
   }
   return value;
 }

package/src/runtime/actors/actor-request-deadline.ts

@@ -0,0 +1,49 @@
+import { awaitWithAbort } from '../abort';
+import {
+  createInternalFrameworkException,
+  ZLinkFrameworkInternalErrorKind
+} from '../framework-errors-internal';
+
+export function remainingActorRequestTimeout(
+  actorId: string,
+  deadlineMs: number | undefined
+): number | undefined {
+  if (deadlineMs === undefined) return undefined;
+  const remaining = deadlineMs - performance.now();
+  if (remaining <= 0) {
+    throw createInternalFrameworkException(
+      ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+      `Actor request '${actorId}' exceeded its deadline.`
+    );
+  }
+  return Math.max(1, Math.ceil(remaining));
+}
+
+/** Only actual Store, delivery-gate, and handoff waits acquire a deadline handle. */
+export async function waitActorReply<T>(
+  reply: Promise<T>,
+  actorId: string,
+  deadlineMs: number | undefined,
+  signal?: AbortSignal
+): Promise<T> {
+  if (deadlineMs === undefined) return await awaitWithAbort(reply, signal);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    const remaining = remainingActorRequestTimeout(actorId, deadlineMs);
+    timer = setTimeout(
+      () =>
+        reject(
+          createInternalFrameworkException(
+            ZLinkFrameworkInternalErrorKind.DeadlineExceeded,
+            `Actor request '${actorId}' exceeded its deadline.`
+          )
+        ),
+      remaining
+    );
+  });
+  try {
+    return await awaitWithAbort(Promise.race([reply, timeout]), signal);
+  } finally {
+    clearTimeout(timer);
+  }
+}

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

@@ -1,5 +1,6 @@
 const INITIAL_RETRY_DELAY_MS = 25;
 const MAX_RETRY_DELAY_MS = 1_000;
+const RETRY_BACKOFF_MULTIPLIER = 2;
 
 export class ZLinkActorRetryDelay {
   private delayMs = INITIAL_RETRY_DELAY_MS;
@@ -11,7 +12,7 @@ export class ZLinkActorRetryDelay {
   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);
+      this.delayMs = Math.min(this.delayMs * RETRY_BACKOFF_MULTIPLIER, MAX_RETRY_DELAY_MS);
     }
     return completed;
   }

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

@@ -1,17 +1,19 @@
 import {
-  ZLinkFrameworkInternalErrorKind,
-  createInternalFrameworkException
-} from '../framework-errors-internal';
-import type {
-  ActorRef,
-  RoutingId,
-  ZLinkActor,
-  ZLinkActorContext,
-  ZLinkSpot
+  type ActorRef,
+  type RoutingId,
+  type ZLinkActor,
+  type ZLinkActorContext,
+  type ZLinkSpot,
+  ZLinkSpotKind
 } from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
+
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
+import { isStructuralGuardEnabled } from '../execution/state-lane';
+import {
+  ZLinkFrameworkInternalErrorKind,
+  createInternalFrameworkException
+} from '../framework-errors-internal';
 import { routingIdsEqual } from '../routing-id';
 import { lookupNativeActorRef } from './actor-native-lookup';
 
@@ -52,85 +54,24 @@ export interface ZLinkRemoteBoundSessionTarget {
 }
 
 /**
- * Applies a lightweight Session binding refresh without discarding the
- * relocation fence that was staged for the same route. Core emits the bind
- * refresh with routing coordinates only; the relocation owner retains the
- * service-wire relocation identity until command 44 releases the owner seal.
+ * Session–Actor binding §5·§6: the Actor owner keeps one current binding. The
+ * stored value is the binding identity and the route to its Session owner; a
+ * relocation fence belongs to the relocation operation that created it.
  */
-export function mergeRemoteBoundSessionTarget(
-  target: ZLinkRemoteBoundSessionTarget,
-  fallback: ZLinkRemoteBoundSessionTarget | undefined
+function boundSessionIdentity(
+  target: ZLinkRemoteBoundSessionTarget
 ): ZLinkRemoteBoundSessionTarget {
-  if (
-    fallback === undefined ||
-    fallback.routerChannelId !== target.routerChannelId ||
-    !routingIdsEqual(fallback.targetNodeRid, target.targetNodeRid) ||
-    (!routingIdsEqual(fallback.spotId, target.spotId) &&
-      !samePhysicalRemoteSession(fallback, target)) ||
-    isSuccessorSessionBinding(fallback, target)
-  ) {
-    return target;
-  }
-  const merged = {
-    ...fallback,
-    ...target,
-    sessionNodeRid: target.sessionNodeRid ?? fallback.sessionNodeRid,
-    sessionRid: target.sessionRid ?? fallback.sessionRid,
-    sessionOwnerNodeGeneration:
-      target.sessionOwnerNodeGeneration ?? fallback.sessionOwnerNodeGeneration,
-    sessionOwnerId: target.sessionOwnerId ?? fallback.sessionOwnerId,
-    sessionOwnerLeaseGeneration:
-      target.sessionOwnerLeaseGeneration ?? fallback.sessionOwnerLeaseGeneration,
-    bindingGeneration: target.bindingGeneration ?? fallback.bindingGeneration,
-    previousAuthorityOwnerGeneration:
-      target.previousAuthorityOwnerGeneration ?? fallback.previousAuthorityOwnerGeneration,
-    previousOwnerLeaseGeneration:
-      target.previousOwnerLeaseGeneration ?? fallback.previousOwnerLeaseGeneration,
-    relocationSealId: target.relocationSealId ?? fallback.relocationSealId,
-    serviceWireRelocation: target.serviceWireRelocation ?? fallback.serviceWireRelocation
+  return {
+    routerChannelId: target.routerChannelId,
+    targetNodeRid: target.targetNodeRid,
+    spotId: target.spotId,
+    sessionNodeRid: target.sessionNodeRid,
+    sessionRid: target.sessionRid,
+    sessionOwnerNodeGeneration: target.sessionOwnerNodeGeneration,
+    sessionOwnerId: target.sessionOwnerId,
+    sessionOwnerLeaseGeneration: target.sessionOwnerLeaseGeneration,
+    bindingGeneration: target.bindingGeneration
   };
-  return merged;
-}
-
-/**
- * Spec 48 §125: reconnection creates a new Session; the previous Session's
- * binding — and its staged relocation fence — is never inherited by a
- * successor. A Core bind refresh only omits routing coordinates it did not
- * recompute, so an explicit Session identity on both sides that disagrees
- * marks the refresh as belonging to a different Session binding, not a
- * same-Session coordinate/generation-only refresh (a bindingGeneration bump
- * with the same sessionNodeRid/sessionRid is a legitimate same-Session
- * refresh and must keep the fence — see the transfer-target generation test
- * below).
- *
- * NOTE: this identity check is a no-op on the path exercised by
- * `remoteBoundSessionTargetForSource` (mesh-router-resolver.ts), which never
- * populates sessionNodeRid/sessionRid on the refresh it emits. Confirmed via
- * TTT reproduction (2026-08-22, run-dir preserved) that a rejected successor
- * bound-session send still occurs through that path after this change; see
- * session report for the STOP writeup.
- */
-function isSuccessorSessionBinding(
-  fallback: ZLinkRemoteBoundSessionTarget,
-  target: ZLinkRemoteBoundSessionTarget
-): boolean {
-  return (
-    (fallback.sessionNodeRid !== undefined &&
-      target.sessionNodeRid !== undefined &&
-      !routingIdsEqual(fallback.sessionNodeRid, target.sessionNodeRid)) ||
-    (fallback.sessionRid !== undefined &&
-      target.sessionRid !== undefined &&
-      !routingIdsEqual(fallback.sessionRid, target.sessionRid)) ||
-    (fallback.sessionOwnerNodeGeneration !== undefined &&
-      target.sessionOwnerNodeGeneration !== undefined &&
-      fallback.sessionOwnerNodeGeneration !== target.sessionOwnerNodeGeneration) ||
-    (fallback.sessionOwnerId !== undefined &&
-      target.sessionOwnerId !== undefined &&
-      fallback.sessionOwnerId !== target.sessionOwnerId) ||
-    (fallback.sessionOwnerLeaseGeneration !== undefined &&
-      target.sessionOwnerLeaseGeneration !== undefined &&
-      fallback.sessionOwnerLeaseGeneration !== target.sessionOwnerLeaseGeneration)
-  );
 }
 
 type ZLinkRemoteSessionOwnerIdentity = Pick<
@@ -144,20 +85,6 @@ type ZLinkRemoteSessionOwnerIdentity = Pick<
 
 type ZLinkRemoteSessionOwnerLifecycle = Omit<ZLinkRemoteSessionOwnerIdentity, 'sessionRid'>;
 
-function samePhysicalRemoteSession(
-  left: ZLinkRemoteBoundSessionTarget,
-  right: Pick<ZLinkRemoteBoundSessionTarget, 'sessionNodeRid' | 'sessionRid'>
-): boolean {
-  return (
-    left.sessionNodeRid !== undefined &&
-    right.sessionNodeRid !== undefined &&
-    left.sessionRid !== undefined &&
-    right.sessionRid !== undefined &&
-    routingIdsEqual(left.sessionNodeRid, right.sessionNodeRid) &&
-    routingIdsEqual(left.sessionRid, right.sessionRid)
-  );
-}
-
 function sameRemoteSessionOwnerLifecycle(
   left: ZLinkRemoteBoundSessionTarget,
   right: ZLinkRemoteSessionOwnerLifecycle
@@ -207,23 +134,6 @@ function sameRemoteSessionBinding(
   );
 }
 
-/**
- * Selects the route that still carries the relocation fence when a Core
- * binding refresh and a formal transfer target temporarily coexist.
- */
-export function preferredRemoteBoundSessionTarget(
-  remote: ZLinkRemoteBoundSessionTarget | undefined,
-  transfer: ZLinkRemoteBoundSessionTarget | undefined
-): ZLinkRemoteBoundSessionTarget | undefined {
-  if (remote === undefined) return transfer;
-  if (hasRelocationFence(remote) || transfer === undefined) return remote;
-  return transfer;
-}
-
-function hasRelocationFence(target: ZLinkRemoteBoundSessionTarget): boolean {
-  return target.relocationSealId !== undefined || target.serviceWireRelocation !== undefined;
-}
-
 export interface ZLinkRemoteActorPacketTarget {
   readonly routerChannelId: string;
   readonly targetNodeRid: RoutingId;
@@ -269,10 +179,8 @@ export class ZLinkActorRuntimeState {
   private spotGenerationValue: bigint | undefined;
   private spotMembershipEpochValue = 0n;
   private nativeActorRefValue: ZLinkBackendActorRef | undefined;
-  private boundSessionBindingGenerationValue = 0n;
   private entryNodeRidValue: RoutingId | undefined;
-  private remoteBoundSessionTargetValue: ZLinkRemoteBoundSessionTarget | undefined;
-  private boundSessionTransferTargetValue: ZLinkRemoteBoundSessionTarget | undefined;
+  private boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
   private remoteActorPacketTargetValue: ZLinkRemoteActorPacketTarget | undefined;
   private createRequestPayloadValue: Buffer | undefined;
   private ownsLocationValue = false;
@@ -282,7 +190,11 @@ export class ZLinkActorRuntimeState {
   private deferredJoinPendingValue = false;
   private destroyTask: Promise<void> | undefined;
 
-  constructor(readonly actorId: string) {}
+  constructor(readonly actorId: string) {
+    if (isStructuralGuardEnabled()) {
+      guardBoundSessionTargetWrites(this);
+    }
+  }
 
   get actorType(): string | undefined {
     return this.actorTypeValue;
@@ -323,19 +235,31 @@ export class ZLinkActorRuntimeState {
   }
 
   get boundSessionBindingGeneration(): bigint {
-    return this.boundSessionBindingGenerationValue;
+    return this.boundSessionValue?.bindingGeneration ?? 0n;
   }
 
   get entryNodeRid(): RoutingId | undefined {
     return this.entryNodeRidValue;
   }
 
-  get remoteBoundSessionTarget(): ZLinkRemoteBoundSessionTarget | undefined {
-    return this.remoteBoundSessionTargetValue;
+  /** The one current Session binding of this Actor (Session–Actor binding §6). */
+  get boundSession(): ZLinkRemoteBoundSessionTarget | undefined {
+    return this.boundSessionValue;
   }
 
-  get boundSessionTransferTarget(): ZLinkRemoteBoundSessionTarget | undefined {
-    return this.boundSessionTransferTargetValue;
+  /**
+   * The current binding when its Session owner is another node. A same-node
+   * binding is served by the local Session registry, so remote routing sees
+   * no target for it.
+   */
+  get remoteBoundSessionTarget(): ZLinkRemoteBoundSessionTarget | undefined {
+    const binding = this.boundSessionValue;
+    const actorNodeRid = this.nativeActorRefValue?.nodeRid;
+    return binding?.sessionNodeRid !== undefined &&
+      actorNodeRid !== undefined &&
+      routingIdsEqual(binding.sessionNodeRid, toFrameworkRoutingId(actorNodeRid))
+      ? undefined
+      : binding;
   }
 
   get remoteActorPacketTarget(): ZLinkRemoteActorPacketTarget | undefined {
@@ -559,24 +483,6 @@ export class ZLinkActorRuntimeState {
     this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
   }
 
-  setBoundSessionBindingGeneration(generation: bigint): void {
-    if (generation > this.boundSessionBindingGenerationValue) {
-      this.boundSessionBindingGenerationValue = generation;
-      if (this.remoteBoundSessionTargetValue !== undefined) {
-        this.remoteBoundSessionTargetValue = {
-          ...this.remoteBoundSessionTargetValue,
-          bindingGeneration: generation
-        };
-      }
-      if (this.boundSessionTransferTargetValue !== undefined) {
-        this.boundSessionTransferTargetValue = {
-          ...this.boundSessionTransferTargetValue,
-          bindingGeneration: generation
-        };
-      }
-    }
-  }
-
   /** @internal Installs one authority-confirmed binding inside its Actor owner turn. */
   installBoundSessionBinding(target: ZLinkRemoteBoundSessionTarget): boolean {
     if (
@@ -587,34 +493,22 @@ export class ZLinkActorRuntimeState {
       target.sessionOwnerLeaseGeneration === undefined ||
       target.bindingGeneration === undefined
     ) {
-      throw new TypeError(
-        'An installed bound Session target requires its complete binding identity.'
-      );
+      throw new TypeError('An installed bound Session target requires its binding identity.');
     }
-    const current = preferredRemoteBoundSessionTarget(
-      this.remoteBoundSessionTargetValue,
-      this.boundSessionTransferTargetValue
-    );
+    const current = this.boundSessionValue;
     if (current !== undefined && sameRemoteSessionOwnerLifecycle(current, target)) {
-      // A duplicate command for the exact physical Session is idempotent. A
-      // different Session in the same owner lifecycle must advance that
-      // lifecycle's generation; a late equal/lower generation is stale.
-      if (sameRemoteSessionOwner(current, target)) return true;
-      if (
-        current.bindingGeneration !== undefined &&
-        current.bindingGeneration >= target.bindingGeneration
-      )
-        return false;
+      // A duplicate or late older command for the exact physical Session
+      // leaves the current binding; a newer generation of the same Session
+      // replaces it. A different Session in the same owner lifecycle must
+      // advance that lifecycle's generation; a late equal/lower one is stale.
+      const advances =
+        current.bindingGeneration === undefined ||
+        target.bindingGeneration > current.bindingGeneration;
+      if (!advances) return sameRemoteSessionOwner(current, target);
     }
-    const installed = mergeRemoteBoundSessionTarget(target, current);
     // Binding generations are scoped to a Session-owner lifecycle. A restarted
     // owner can legitimately reset its counter below the predecessor value.
-    this.boundSessionBindingGenerationValue = target.bindingGeneration;
-    this.remoteBoundSessionTargetValue = undefined;
-    this.boundSessionTransferTargetValue = {
-      ...installed,
-      bindingGeneration: target.bindingGeneration
-    };
+    this.boundSessionValue = boundSessionIdentity(target);
     return true;
   }
 
@@ -628,75 +522,18 @@ export class ZLinkActorRuntimeState {
       target.sessionOwnerLeaseGeneration === undefined ||
       target.bindingGeneration === undefined
     ) {
-      throw new TypeError('A retired bound Session target requires its complete binding identity.');
+      throw new TypeError('A retired bound Session target requires its binding identity.');
     }
-    let retired = false;
-    if (
-      this.remoteBoundSessionTargetValue !== undefined &&
-      sameRemoteSessionBinding(this.remoteBoundSessionTargetValue, target)
-    ) {
-      this.remoteBoundSessionTargetValue = undefined;
-      retired = true;
-    }
-    if (
-      this.boundSessionTransferTargetValue !== undefined &&
-      sameRemoteSessionBinding(this.boundSessionTransferTargetValue, target)
-    ) {
-      this.boundSessionTransferTargetValue = undefined;
-      retired = true;
-    }
-    if (retired) {
-      this.boundSessionBindingGenerationValue =
-        preferredRemoteBoundSessionTarget(
-          this.remoteBoundSessionTargetValue,
-          this.boundSessionTransferTargetValue
-        )?.bindingGeneration ?? 0n;
-    }
-    return retired;
+    const current = this.boundSessionValue;
+    if (current === undefined || !sameRemoteSessionBinding(current, target)) return false;
+    this.boundSessionValue = undefined;
+    return true;
   }
 
   setEntryNodeRid(entryNodeRid: RoutingId): void {
     this.entryNodeRidValue = entryNodeRid;
   }
 
-  setRemoteBoundSessionTarget(target: ZLinkRemoteBoundSessionTarget | undefined): void {
-    const current = preferredRemoteBoundSessionTarget(
-      this.remoteBoundSessionTargetValue,
-      this.boundSessionTransferTargetValue
-    );
-    const merged =
-      target === undefined ? undefined : mergeRemoteBoundSessionTarget(target, current);
-    const bindingGeneration = maxBindingGeneration(
-      merged?.bindingGeneration,
-      this.remoteBoundSessionTargetValue?.bindingGeneration,
-      this.boundSessionBindingGenerationValue
-    );
-    this.remoteBoundSessionTargetValue =
-      merged === undefined
-        ? undefined
-        : bindingGeneration === undefined
-          ? merged
-          : { ...merged, bindingGeneration };
-  }
-
-  setBoundSessionTransferTarget(target: ZLinkRemoteBoundSessionTarget | undefined): void {
-    const merged =
-      target === undefined
-        ? undefined
-        : mergeRemoteBoundSessionTarget(target, this.boundSessionTransferTargetValue);
-    const bindingGeneration = maxBindingGeneration(
-      merged?.bindingGeneration,
-      this.boundSessionTransferTargetValue?.bindingGeneration,
-      this.boundSessionBindingGenerationValue
-    );
-    this.boundSessionTransferTargetValue =
-      merged === undefined
-        ? undefined
-        : bindingGeneration === undefined
-          ? merged
-          : { ...merged, bindingGeneration };
-  }
-
   setRemoteActorPacketTarget(target: ZLinkRemoteActorPacketTarget | undefined): void {
     this.remoteActorPacketTargetValue = target;
   }
@@ -737,10 +574,8 @@ export class ZLinkActorRuntimeState {
     this.spotGenerationValue = undefined;
     this.spotMembershipEpochValue = 0n;
     this.nativeActorRefValue = undefined;
-    this.boundSessionBindingGenerationValue = 0n;
     this.entryNodeRidValue = undefined;
-    this.remoteBoundSessionTargetValue = undefined;
-    this.boundSessionTransferTargetValue = undefined;
+    this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;
     this.createRequestPayloadValue = undefined;
     this.ownsLocationValue = false;
@@ -753,11 +588,6 @@ export class ZLinkActorRuntimeState {
 
   prepareForRemoteReentry(): void {
     if (this.remoteActorPacketTargetValue === undefined) return;
-    const relocationTransferTarget =
-      this.boundSessionTransferTargetValue !== undefined &&
-      hasRelocationFence(this.boundSessionTransferTargetValue)
-        ? this.boundSessionTransferTargetValue
-        : undefined;
     this.creationTask = undefined;
     this.configured = false;
     this.context = undefined;
@@ -766,9 +596,8 @@ export class ZLinkActorRuntimeState {
     this.spotValue = undefined;
     this.spotIdValue = undefined;
     this.nativeActorRefValue = undefined;
-    this.boundSessionBindingGenerationValue = relocationTransferTarget?.bindingGeneration ?? 0n;
-    this.remoteBoundSessionTargetValue = undefined;
-    this.boundSessionTransferTargetValue = relocationTransferTarget;
+    // The arriving relocation installs the binding it carries.
+    this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;
     this.createRequestPayloadValue = undefined;
     this.ownsLocationValue = false;
@@ -780,13 +609,22 @@ export class ZLinkActorRuntimeState {
   }
 }
 
-function maxBindingGeneration(...values: (bigint | undefined)[]): bigint | undefined {
-  let maximum: bigint | undefined;
-  for (const value of values) {
-    if (value === undefined || value <= 0n) continue;
-    if (maximum === undefined || value > maximum) maximum = value;
-  }
-  return maximum;
+function guardBoundSessionTargetWrites(actor: ZLinkActorRuntimeState): void {
+  let current: ZLinkRemoteBoundSessionTarget | undefined;
+  Object.defineProperty(actor, 'boundSessionValue', {
+    configurable: true,
+    enumerable: true,
+    get: () => current,
+    set: (target: ZLinkRemoteBoundSessionTarget | undefined) => {
+      if (
+        target !== undefined &&
+        new Error().stack?.includes('installBoundSessionBinding') !== true
+      ) {
+        throw new Error('Bound Session target must be installed by installBoundSessionBinding.');
+      }
+      current = target;
+    }
+  });
 }
 
 export function toFrameworkRoutingId(routingId: unknown): RoutingId {