@zlink-systems/framework 0.31.0 → 0.32.1

package/dist/runtime/streams/index.d.ts

@@ -8,7 +8,7 @@ import { type ZLinkFrameworkRegistration } from '../configuration';
 import type { ZLinkListenerRecords } from '../foundation/listener-records';
 import { ApplicationJobQueue } from '../host/application-job-queue';
 import type { ZLinkSubmitResult } from '../messaging/submission-result';
-import { type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+import { ZLinkActorSessionBindingRegistry, type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
 import { type ZLinkBoundActorRelaySenderOptions } from './bound-actor-relay-sender';
 import { type ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
 import { type ZLinkBoundSessionTransport } from './bound-session-service';
@@ -100,7 +100,7 @@ export declare class ZLinkStreamSessionNodeRuntime extends ZLinkStreamSessionNod
     constructor(options: ZLinkStreamSessionNodeRuntimeOptions);
 }
 export declare class ZLinkStreamBindingRuntime {
-    private readonly routes;
+    readonly routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>;
     private readonly frameMessages;
     private readonly compressionCodec;
     private readonly boundSessions;
@@ -149,5 +149,5 @@ export declare class ZLinkStreamBindingRuntime {
     createBinaryMessage(payload: Uint8Array): Message;
     decompressPayload(payload: Message): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(context: DefaultZLinkSessionContext, requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
 }

package/dist/runtime/streams/index.js

@@ -348,8 +348,28 @@ class ZLinkStreamBindingRuntime {
     createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId) {
         return this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId);
     }
-    createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload) {
-        return this.frameMessages.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+    async submitReply(context, requestHeader, kind, metadata, compressed, payload) {
+        const frame = this.frameMessages.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+        try {
+            return await this.routes.submitReply(context, requestHeader, async (header) => {
+                if (header === requestHeader)
+                    return await context.stream.submitRaw(frame);
+                const encoded = (0, protocol_1.decodeStreamFrame)((0, protocol_1.messageToBytes)(frame));
+                const normalized = this.createBinaryMessage((0, protocol_1.encodeStreamFrame)({
+                    ...(0, protocol_1.decodeStreamHeader)(encoded.header),
+                    actorSlot: header.actorSlot
+                }, encoded.payload));
+                try {
+                    return await context.stream.submitRaw(normalized);
+                }
+                finally {
+                    normalized.close();
+                }
+            });
+        }
+        finally {
+            frame.close();
+        }
     }
 }
 exports.ZLinkStreamBindingRuntime = ZLinkStreamBindingRuntime;

package/dist/runtime/streams/managed-stream.js

@@ -297,7 +297,8 @@ class ZLinkManagedStream {
         try {
             if (completion.terminalResult !== 0 &&
                 !acceptedTerminalResults.has(completion.terminalResult)) {
-                throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`);
+                throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, completion.failureMessage ??
+                    `${operationName} failed with result ${completion.terminalResult} (errno ${completion.failureErrno}).`);
             }
         }
         finally {

package/dist/runtime/streams/session-calls.d.ts

@@ -12,7 +12,7 @@ export interface ZLinkSessionCallContext {
     };
     readonly dispatchHeader: ZLinkStreamFrameHeader | undefined;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     claimReply(requestHeader: ZLinkStreamFrameHeader): void;
     /**
      * Spec 26 §2.2: the STREAM surface records session-connected sends and the

package/dist/runtime/streams/session-calls.js

@@ -93,15 +93,9 @@ class DefaultZLinkSessionReplyCall {
             throw new Error('Reply is only available while handling a request packet.');
         }
         this.context.claimReply(requestHeader);
-        const message = this.context.createJsonReplyFrameMessage(requestHeader, protocol_1.ZLinkStreamMessageKind.Response, new Map(), this.compressionEnabled, this.message);
-        try {
-            const result = await this.context.stream.submitRaw(message);
-            (0, submission_result_1.requireOneWayCompletion)(result, 'STREAM session reply');
-            this.context.traceFrameWritten?.(protocol_1.ZLinkStreamMessageKind.Response, requestHeader.name, requestHeader.correlationId);
-        }
-        finally {
-            message.close();
-        }
+        const result = await this.context.submitReply(requestHeader, protocol_1.ZLinkStreamMessageKind.Response, new Map(), this.compressionEnabled, this.message);
+        (0, submission_result_1.requireOneWayCompletion)(result, 'STREAM session reply');
+        this.context.traceFrameWritten?.(protocol_1.ZLinkStreamMessageKind.Response, requestHeader.name, requestHeader.correlationId);
     }
 }
 exports.DefaultZLinkSessionReplyCall = DefaultZLinkSessionReplyCall;

package/dist/runtime/streams/session-context.d.ts

@@ -17,7 +17,7 @@ interface ZLinkSessionContextRuntime {
     createTextMessage(payload: string): Message;
     createBinaryMessage(payload: Uint8Array): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(context: DefaultZLinkSessionContext, requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     decompressPayload(payload: Message): Message;
     bind(context: DefaultZLinkSessionContext, actor: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
@@ -64,7 +64,7 @@ export declare class DefaultZLinkSessionContext implements ZLinkSessionContext {
     createTextMessage(payload: string): Message;
     createBinaryMessage(payload: Uint8Array): Message;
     createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
-    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+    submitReply(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Promise<ZLinkSubmitResult>;
     enterDispatch(header: ZLinkStreamFrameHeader): void;
     exitDispatch(): void;
     get dispatchHeader(): ZLinkStreamFrameHeader | undefined;

package/dist/runtime/streams/session-context.js

@@ -105,8 +105,8 @@ class DefaultZLinkSessionContext {
     createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId) {
         return this.runtime.createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId);
     }
-    createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload) {
-        return this.runtime.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+    submitReply(requestHeader, kind, metadata, compressed, payload) {
+        return this.runtime.submitReply(this, requestHeader, kind, metadata, compressed, payload);
     }
     enterDispatch(header) {
         if (this.closingForActorReplacement) {

package/dist/runtime/streams/stream-session-runtime.d.ts

@@ -93,6 +93,7 @@ export declare class ZLinkStreamSessionRuntime {
     private markConnected;
     private dispatchPacket;
     private handleControl;
+    private logIgnoredControl;
     private scheduleLivenessCheck;
     private runLivenessCheck;
     private closeForLiveness;

package/dist/runtime/streams/stream-session-runtime.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = void 0;
+const submission_result_1 = require("../messaging/submission-result");
+const api_logs_1 = require("@opentelemetry/api-logs");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const Registration_1 = require("../../contracts/Configuration/Registration");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const abort_1 = require("../abort");
@@ -8,6 +11,7 @@ const admission_1 = require("../admission");
 const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const channels_1 = require("../channels");
 const diagnostics_1 = require("../diagnostics");
+const message_flow_record_1 = require("../diagnostics/message-flow-record");
 const flow_context_1 = require("../diagnostics/flow-context");
 const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
 const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
@@ -20,7 +24,6 @@ const session_context_1 = require("./session-context");
 const session_serial_executor_1 = require("./session-serial-executor");
 const stream_message_utils_1 = require("./stream-message-utils");
 const RegistrationNormalizers_1 = require("../../contracts/Configuration/RegistrationNormalizers");
-const ZLINK_SEND_DONT_WAIT = 1;
 const ZLINK_RECV_DONT_WAIT = 1;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
@@ -28,6 +31,7 @@ const ZLINK_STREAM_MONITOR_IDLE_MIN_DELAY_MS = 1;
 const ZLINK_STREAM_MONITOR_IDLE_MAX_DELAY_MS = 20;
 const ZLINK_STREAM_MONITOR_IDLE_MAX_STEPS = 7;
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const STREAM_RUNTIME_LOGGER = api_logs_1.logs.getLogger(message_flow_record_1.TELEMETRY_INSTRUMENTATION_NAME);
 const systemLivenessClock = {
     now: () => performance.now(),
     setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
@@ -384,19 +388,45 @@ class ZLinkStreamSessionRuntime {
         }
     }
     async handleControl(header, payload) {
-        if ((0, protocol_1.messageToBytes)(payload).length !== 0) {
-            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', 'Control heartbeat payload must be empty.');
+        const payloadBytes = (0, protocol_1.messageToBytes)(payload);
+        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
+            if (payloadBytes.length !== 0) {
+                this.logIgnoredControl(header.name, payloadBytes.length);
+            }
+            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PONG);
             return;
         }
         if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG) {
+            if (payloadBytes.length !== 0) {
+                this.logIgnoredControl(header.name, payloadBytes.length);
+            }
             return;
         }
-        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
-            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PONG);
+        if (header.name === stream_wire_1.ZlinkStreamControlPacket.ActorBound ||
+            header.name === stream_wire_1.ZlinkStreamControlPacket.ActorUnbound) {
+            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', `Unexpected stream actor control frame: ${header.name}`);
+            return;
+        }
+        if (header.name.startsWith('$zlink.')) {
+            this.logIgnoredControl(header.name, payloadBytes.length);
             return;
         }
         await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', `Unknown stream control frame: ${header.name}`);
     }
+    logIgnoredControl(name, payloadLength) {
+        STREAM_RUNTIME_LOGGER.emit({
+            eventName: 'zlink.stream.control_ignored',
+            timestamp: new Date(),
+            severityNumber: api_logs_1.SeverityNumber.DEBUG,
+            severityText: 'DEBUG',
+            body: `Ignored STREAM control name=${name} payloadBytes=${payloadLength} peerSessionRid=${this.stream.sessionId}`,
+            attributes: {
+                control_name: name,
+                payload_bytes: payloadLength,
+                peer_session_rid: this.stream.sessionId
+            }
+        });
+    }
     scheduleLivenessCheck() {
         if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
             return;
@@ -461,19 +491,14 @@ class ZLinkStreamSessionRuntime {
             // record (spec 26 §2.2) and confuse the peer's reply matching.
             return;
         }
-        const message = this.context.createJsonReplyFrameMessage(header, protocol_1.ZLinkStreamMessageKind.Error, new Map(), false, (0, bound_session_response_target_1.boundSessionErrorPayload)(error));
         try {
-            if (!this.context.stream.writeRaw(message, ZLINK_SEND_DONT_WAIT)) {
-                throw new Error('Client stream error reply send failed.');
-            }
+            const result = await this.context.submitReply(header, protocol_1.ZLinkStreamMessageKind.Error, new Map(), false, (0, bound_session_response_target_1.boundSessionErrorPayload)(error));
+            (0, submission_result_1.requireOneWayCompletion)(result, 'Client stream error reply');
             this.traceFrameWritten(protocol_1.ZLinkStreamMessageKind.Error, header.name, header.correlationId);
         }
         catch (replyError) {
             this.options.onError?.(replyError);
         }
-        finally {
-            message.close();
-        }
     }
     /**
      * Spec 26 §2.1/§2.2: a successful session write is the surface's terminal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.31.0",
+  "version": "0.32.1",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   "dependencies": {
     "@opentelemetry/api": "^1.9.1",
     "@opentelemetry/api-logs": "^0.221.0",
-    "@zlink-systems/stream-wire": "0.31.0",
-    "@zlink-systems/zlink": "1.21.0"
+    "@zlink-systems/stream-wire": "0.32.1",
+    "@zlink-systems/zlink": "1.23.0"
   }
 }

package/src/contracts/Actors/ZLinkActor.ts

@@ -1,8 +1,14 @@
 import type { ZLinkActorContext } from './ZLinkActorContext';
 import type { ZLinkActorJoinCompletion } from './ZLinkActorFactory';
+import type { ZLinkSessionBindingIdentity } from './ZLinkSessionBindingIdentity';
 
 export interface ZLinkActor {
   readonly context: ZLinkActorContext;
   configure?(): void;
   onJoinCompleted?(completion: ZLinkActorJoinCompletion): Promise<void>;
+  onDuplicateBind?(
+    current: ZLinkSessionBindingIdentity,
+    incoming: ZLinkSessionBindingIdentity,
+    signal: AbortSignal
+  ): Promise<string | undefined>;
 }

package/src/contracts/Actors/ZLinkSessionBindingIdentity.ts

@@ -0,0 +1,7 @@
+import type { RoutingId } from '../Common';
+
+export interface ZLinkSessionBindingIdentity {
+  readonly sessionOwnerNodeRid: RoutingId;
+  readonly sessionOwnerNodeGeneration: bigint;
+  readonly bindingGeneration: bigint;
+}

package/src/contracts/Actors/index.ts

@@ -1,4 +1,5 @@
 export * from './ZLinkActor';
+export * from './ZLinkSessionBindingIdentity';
 export * from './ZLinkActorContext';
 export * from './ZLinkActorClient';
 export * from './ZLinkActorFactory';

package/src/contracts/Common/payload-slab.ts

@@ -0,0 +1,29 @@
+const SLAB_BYTES = 64 * 1024;
+const MAX_POOLED_BYTES = 16 * 1024;
+const ALIGNMENT = 8;
+
+let slab: Buffer | undefined;
+let offset = 0;
+
+/** Allocates independent bytes; previously returned regions are never reused. */
+export function allocatePayloadBytes(length: number): Buffer {
+  if (length > MAX_POOLED_BYTES || length < 0 || !Number.isInteger(length)) {
+    return Buffer.allocUnsafe(length);
+  }
+  if (slab === undefined || offset + length > SLAB_BYTES) {
+    slab = Buffer.allocUnsafe(SLAB_BYTES);
+    offset = 0;
+  }
+  const bytes = slab.subarray(offset, offset + length);
+  offset += Math.ceil(length / ALIGNMENT) * ALIGNMENT;
+  // Transient runtime frames only; local queues and application boundaries
+  // copy before they retain or expose these bytes.
+  return bytes;
+}
+
+/** Copies bytes into an exact, standalone backing store with no Buffer pool. */
+export function copyPayloadBytes(bytes: Uint8Array): Buffer {
+  const copy = Buffer.allocUnsafeSlow(bytes.byteLength);
+  copy.set(bytes);
+  return copy;
+}

package/src/contracts/Handlers/Contexts.ts

@@ -7,6 +7,7 @@ export interface ZLinkMessageContext {
   readonly contentType?: string;
   readonly metadata: ZLinkMessageMetadata;
   readonly correlationId?: string;
+  readonly receivedAt: Date;
 }
 
 export interface ZLinkPublishMessageContext extends ZLinkMessageContext {

package/src/internal.ts

@@ -3,6 +3,19 @@ export * from './index';
 export { requireValidSendTimeoutMs } from './contracts/Configuration/SendTimeoutValidation';
 export * from './runtime/diagnostics';
 export * from './runtime/host';
+export { ZLinkActorPlacementCoordinator } from './runtime/host/actor-placement-coordinator';
+export { ZLinkActorTransferRuntime } from './runtime/host/actor-transfer-runtime';
+export {
+  ApplicationJobQueue,
+  ApplicationJobQueuePermit,
+  nodeEffectiveProcessorCount,
+  resolveApplicationJobQueueConfiguration
+} from './runtime/host/application-job-queue';
+export { ZLinkLocationRuntimeOwner } from './runtime/host/location-runtime-owner';
+export {
+  relocationFailedFailureCode,
+  ZLinkHostServiceRelocationRuntime
+} from './runtime/host/service-relocation-host-runtime';
 export * from './runtime/admission';
 export * from './runtime/activation-admission';
 export * from './runtime/streams';
@@ -21,9 +34,13 @@ export {
 } from './contracts/Locations/Values';
 export { ZLinkLocationWriteIntent, ZLinkLocationWriteStatus } from './contracts/Locations/Writes';
 export * from './runtime/channels';
+export { ZLinkChannelRuntimeLifecycle } from './runtime/channels/channel-runtime-lifecycle';
+export { ZLinkChannelSocketRegistry } from './runtime/channels/channel-socket-registry';
+export { ZLinkChannelDispatchPipeline } from './runtime/channels/channel-dispatch-pipeline';
 export * from './runtime/backend';
 export * from './runtime/codecs';
 export * from './runtime/execution';
+export { ZLinkSerialExecutionQueue } from './runtime/execution/serial-execution-queue';
 export * from './runtime/handlers';
 export * from './runtime/messaging';
 export * from './runtime/foundation';

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

@@ -52,7 +52,11 @@ import {
   internalFrameworkErrorKindFromWireFailureCode,
   ZLinkFrameworkInternalErrorKind
 } from '../framework-errors-internal';
-import type { ZLinkResolvedActorRoute, ZLinkStoreLocationResolvers } from '../locations';
+import type {
+  ZLinkActorRouteInvalidationFence,
+  ZLinkResolvedActorRoute,
+  ZLinkStoreLocationResolvers
+} from '../locations';
 import { resolveFrameworkPacketName } from '../messaging/packet-name';
 import { decodeFrameworkPayloadMessage, encodeFrameworkPayload } from '../messaging/payload-codec';
 import {
@@ -161,7 +165,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
   ): Promise<ZLinkSubmitResult> {
     const route = await this.resolveActorRoute(actorId);
     const { meshName, actorRef: actor } = route;
-    this.throwIfKnownStale(meshName, actor);
+    this.throwIfKnownStale(route);
     const parts = this.createPacketParts(
       ZLinkStreamMessageKind.Send,
       undefined,
@@ -169,8 +173,10 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       message,
       metadata
     );
+    let routeFence: ZLinkActorRouteInvalidationFence | undefined;
     try {
       const messageFollow = createActorMessageFollowContext(route, parts, false);
+      routeFence = actorRouteInvalidationFence(route);
       const routedActor = attachActorMessageFollowContext(actor, messageFollow);
       const submissionCopies =
         (await this.options.transportDeliveryGate?.()?.waitBeforeSubmit(actorId, 'oneWay')) ?? 1;
@@ -218,12 +224,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
       }
       return await this.submitActorSend(meshName, toBackendActorRef(actor), parts, route);
     } catch (error) {
-      if (isStaleActorError(error)) {
-        this.invalidateActorRoute(actorId);
-        this.options.staleActorRefReporter?.(meshName, actor.actorId);
-        throw actorLocationStale(actor.actorId, error);
-      }
-      throw error;
+      throw this.mapActorFailure(actorId, error, routeFence, meshName);
     } finally {
       closeMessages(parts);
     }
@@ -243,6 +244,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     const sourceSpotId = currentZLinkActorExecution()?.spotId ?? currentZLinkSpotSerialSourceId();
     const effectiveTimeoutMs = timeoutMs ?? this.options.defaultRequestTimeoutMs;
     let meshName: string | undefined;
+    let routeFence: ZLinkActorRouteInvalidationFence | undefined;
     return this.requests.prepare<TReply>(
       effectiveTimeoutMs,
       signal,
@@ -265,8 +267,10 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
           }
           const { actorRef: actor } = route;
           meshName = route.meshName;
-          if (this.options.staleActorRefPredicate?.(meshName, actor) === true)
+          if (this.options.staleActorRefPredicate?.(meshName, actor) === true) {
+            routeFence = actorRouteInvalidationFence(route);
             throw actorLocationStale(actor.actorId, undefined);
+          }
           const operationId = createMessageFollowId();
           const correlationId = createMessageFollowId();
           const requestSequence = BigInt(`0x${operationId.slice(16)}`);
@@ -287,6 +291,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
               correlationId,
               operationId
             );
+            routeFence = actorRouteInvalidationFence(route);
             const routedActor = attachActorMessageFollowContext(actor, messageFollow);
             const delivery = this.options
               .transportDeliveryGate?.()
@@ -342,14 +347,7 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
         })().catch((error) => receiver.operationFailed(requestOperation.id, error, undefined));
       },
       (value) => value as TReply,
-      (error) => {
-        if (isStaleActorError(error)) {
-          this.invalidateActorRoute(actorId);
-          if (meshName !== undefined) this.options.staleActorRefReporter?.(meshName, actorId);
-          return actorLocationStale(actorId, error);
-        }
-        return error;
-      }
+      (error) => this.mapActorFailure(actorId, error, routeFence, meshName)
     );
   }
 
@@ -387,15 +385,29 @@ export class DefaultZLinkActorClient implements ZLinkActorClient {
     return resolution.route;
   }
 
-  private invalidateActorRoute(actorId: string): void {
-    this.options.locationResolver()?.invalidateActorRoute(actorId);
+  private mapActorFailure(
+    actorId: string,
+    error: unknown,
+    routeFence: ZLinkActorRouteInvalidationFence | undefined,
+    meshName: string | undefined
+  ): unknown {
+    if (!isStaleActorError(error)) return error;
+    const resolver = this.options.locationResolver();
+    if (routeFence !== undefined && resolver !== undefined)
+      resolver.invalidateActorRouteIfMatches(routeFence);
+    if (meshName !== undefined) this.options.staleActorRefReporter?.(meshName, actorId);
+    return actorLocationStale(actorId, error);
   }
 
-  private throwIfKnownStale(meshName: string, actor: ActorRef): void {
+  private throwIfKnownStale(route: ZLinkResolvedActorRoute): void {
+    const { meshName, actorRef: actor } = route;
     if (this.options.staleActorRefPredicate?.(meshName, actor) !== true) return;
-    this.invalidateActorRoute(actor.actorId);
-    this.options.staleActorRefReporter?.(meshName, actor.actorId);
-    throw actorLocationStale(actor.actorId, undefined);
+    throw this.mapActorFailure(
+      actor.actorId,
+      actorLocationStale(actor.actorId, undefined),
+      actorRouteInvalidationFence(route),
+      meshName
+    );
   }
 
   private createPacketParts(
@@ -609,6 +621,19 @@ function nativeActorRouteFence(route: ZLinkResolvedActorRoute, actor: ZLinkBacke
   };
 }
 
+function actorRouteInvalidationFence(
+  route: ZLinkResolvedActorRoute
+): ZLinkActorRouteInvalidationFence {
+  return {
+    actorId: route.actorRef.actorId,
+    objectGeneration: route.actorRef.objectGeneration,
+    targetNodeRid: route.actorRef.nodeRid,
+    targetNodeGeneration: route.ownerNodeGeneration,
+    authorityOwnerGeneration: route.authorityOwnerGeneration,
+    ownerLeaseGeneration: route.ownerLeaseGeneration
+  };
+}
+
 function remoteActorRouteTarget(route: ZLinkResolvedActorRoute) {
   if (route.enclosingSpotRoute !== undefined) {
     return route.enclosingSpotRoute;

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

@@ -97,7 +97,7 @@ export class DefaultZLinkActorContext implements ZLinkActorContext {
   }
 
   get objectGeneration(): bigint {
-    return this.state.nativeActorRef?.generation ?? 1n;
+    return this.state.currentActorRef().generation;
   }
 
   get spotId(): SpotId | undefined {

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

@@ -211,7 +211,7 @@ export class ZLinkActorCreationCoordinator {
         await this.options.locationLifecycle?.setActorRef(
           actorType,
           actorId,
-          { actorId, objectGeneration: 1n, meshName, nodeRid },
+          toFrameworkActorRef(state.currentActorRef(), meshName),
           0n
         );
       }

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

@@ -14,7 +14,7 @@ import {
 import type { ApplicationJobPermitPort } from '../application-jobs/contracts';
 
 export class ZLinkActorSerialExecutor {
-  private readonly scheduler: ZLinkSerialExecutionQueue;
+  readonly scheduler: ZLinkSerialExecutionQueue;
 
   constructor(
     private readonly actorId: string,

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

@@ -9,6 +9,7 @@ import {
 
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
+import { ZLinkConfigurationException } from '../configuration';
 import { isStructuralGuardEnabled } from '../execution/state-lane';
 import {
   ZLinkFrameworkInternalErrorKind,
@@ -172,9 +173,11 @@ export class ZLinkActorRuntimeState {
   private spotIdValue: RoutingId | undefined;
   private spotGenerationValue: bigint | undefined;
   private spotMembershipEpochValue = 0n;
+  // Preserve the exact incarnation until teardown finalization, even after native removal.
   private nativeActorRefValue: ZLinkBackendActorRef | undefined;
+  private nativeActorDestroyed = false;
   private entryNodeRidValue: RoutingId | undefined;
-  private boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
+  boundSessionValue: ZLinkRemoteBoundSessionTarget | undefined;
   private remoteActorPacketTargetValue: ZLinkRemoteActorPacketTarget | undefined;
   private createRequestPayloadValue: Buffer | undefined;
   private ownsLocationValue = false;
@@ -228,6 +231,15 @@ export class ZLinkActorRuntimeState {
     return this.nativeActorRefValue;
   }
 
+  currentActorRef(): ZLinkBackendActorRef {
+    if (this.nativeActorRefValue === undefined) {
+      throw new ZLinkConfigurationException(
+        `Actor '${this.actorId}' lifecycle identity is not initialized.`
+      );
+    }
+    return this.nativeActorRefValue;
+  }
+
   get boundSessionBindingGeneration(): bigint {
     return this.boundSessionValue?.bindingGeneration ?? 0n;
   }
@@ -355,24 +367,26 @@ export class ZLinkActorRuntimeState {
       );
     }
 
-    const task = Promise.resolve().then(() => destroy(actorRef));
+    const task = Promise.resolve()
+      .then(() => destroy(this.nativeActorDestroyed ? undefined : actorRef))
+      .catch((error: unknown) => {
+        // A caller may start another attempt only after this attempt has failed.
+        if (this.destroyTask === task) {
+          this.destroyTask = undefined;
+          this.movingValue = false;
+        }
+        throw error;
+      });
     this.destroyTask = task;
     return task;
   }
 
   markNativeActorDestroyed(actorRef: ZLinkBackendActorRef): void {
     if (this.nativeActorRefValue === actorRef) {
-      this.nativeActorRefValue = undefined;
+      this.nativeActorDestroyed = true;
     }
   }
 
-  clearFailedDestroy(task: Promise<void>): void {
-    if (this.destroyTask === task) {
-      this.destroyTask = undefined;
-    }
-    this.movingValue = false;
-  }
-
   ensureContext(createContext: () => ZLinkActorContext): ZLinkActorContext {
     this.context ??= createContext();
     return this.context;
@@ -425,6 +439,7 @@ export class ZLinkActorRuntimeState {
       this.createRequestPayloadValue = undefined;
       this.configured = false;
       this.nativeActorRefValue = undefined;
+      this.nativeActorDestroyed = false;
       this.entryNodeRidValue = undefined;
       return true;
     }
@@ -474,6 +489,7 @@ export class ZLinkActorRuntimeState {
 
   setNativeActorRef(actorRef: ZLinkBackendActorRef): void {
     this.nativeActorRefValue = actorRef;
+    this.nativeActorDestroyed = false;
     this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
   }
 
@@ -556,6 +572,7 @@ export class ZLinkActorRuntimeState {
     this.spotGenerationValue = undefined;
     this.spotMembershipEpochValue = 0n;
     this.nativeActorRefValue = undefined;
+    this.nativeActorDestroyed = false;
     this.entryNodeRidValue = undefined;
     this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;
@@ -578,6 +595,7 @@ export class ZLinkActorRuntimeState {
     this.spotValue = undefined;
     this.spotIdValue = undefined;
     this.nativeActorRefValue = undefined;
+    this.nativeActorDestroyed = false;
     // The arriving relocation installs the binding it carries.
     this.boundSessionValue = undefined;
     this.remoteActorPacketTargetValue = undefined;