@zlink-systems/framework 0.28.0 → 0.29.1

package/dist/runtime/streams/stream-message-utils.d.ts

@@ -1,5 +1,4 @@
 import type { Message } from '../../contracts/Common/Message';
-export declare function copyMessage(message: Message): Message;
 export declare function simpleMessage(bytes: Uint8Array): unknown;
 /** Create the structural Message used by the internal receive assembler. */
 export declare function ownedMessage(bytes: Uint8Array): Message;

package/dist/runtime/streams/stream-message-utils.js

@@ -1,30 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.copyMessage = copyMessage;
 exports.simpleMessage = simpleMessage;
 exports.ownedMessage = ownedMessage;
 const framework_json_v1_1 = require("../messaging/framework-json-v1");
 const protocol_1 = require("./protocol");
 const EMPTY_MESSAGE_BYTES = new Uint8Array(0);
-function copyMessage(message) {
-    const value = message;
-    if (value.copy !== undefined) {
-        return value.copy();
-    }
-    if (value.toBytes !== undefined) {
-        return simpleMessage(value.toBytes());
-    }
-    if (value.data !== undefined) {
-        return simpleMessage(value.data());
-    }
-    if (value.bytes !== undefined) {
-        return simpleMessage(value.bytes);
-    }
-    if (value.getString !== undefined) {
-        return simpleMessage((0, protocol_1.utf8Encode)(value.getString()));
-    }
-    throw new Error('Stream response payload cannot be copied.');
-}
 function simpleMessage(bytes) {
     return createSimpleMessage(new Uint8Array(bytes), false);
 }

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

@@ -30,6 +30,9 @@ export interface ZLinkStreamSessionContextFactory {
     createSessionContext(stream: ZLinkManagedStream, close?: (signal?: AbortSignal) => Promise<void>, providerResolver?: ZLinkProviderResolver): DefaultZLinkSessionContext;
 }
 export interface ZLinkStreamSessionRuntimeOptions {
+    readonly heartbeatIntervalMs?: number;
+    readonly heartbeatTimeoutMs?: number;
+    readonly idleTimeoutMs?: number;
     readonly socket: ZLinkBackendStreamSocket;
     readonly nativeSessionService?: StreamSessionService;
     readonly meshCompletions?: ZLinkMeshCompletionTable;
@@ -66,8 +69,10 @@ export declare class ZLinkStreamSessionRuntime {
     private closeReason;
     private metricsClosed;
     private readonly livenessClock;
+    private readonly liveness;
     private lastApplicationActivityAt;
     private lastInboundFrameAt;
+    private lastHeartbeatPingAt;
     private livenessTimer;
     constructor(options: ZLinkStreamSessionRuntimeOptions & ZLinkStreamLivenessOptions, routingId: unknown, removeSession?: (sessionId: string, session: ZLinkStreamSessionRuntime) => void);
     get session(): Promise<ZLinkSession>;
@@ -79,8 +84,7 @@ export declare class ZLinkStreamSessionRuntime {
     enqueuePacket(payload: Message, decodedHeader: ZLinkStreamFrameHeader, terminalOwner?: ZLinkRetainedStreamOwner, applicationJobPermit?: ApplicationJobPermitPort): void;
     enqueueDisconnected(error?: unknown): void;
     /**
-     * Starts the callback on the session lane and observes its terminal result
-     * without retaining that lane while application code awaits unrelated work.
+     * Retains the session turn through the callback's terminal result.
      */
     enqueueActorBindingReplaced(actor: ServiceActorRef, retiredSession: ServiceRetiredBoundSessionRouteFence): void;
     close(signal?: AbortSignal): Promise<void>;
@@ -105,7 +109,6 @@ export declare class ZLinkStreamSessionRuntime {
     private queueDisconnect;
     private cleanup;
     private enqueueControl;
-    private enqueueInfrastructure;
     private enqueueApplication;
     /**
      * Spec 26 §2.1/§3.1: a frame discarded because the session serial lane is

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

@@ -19,19 +19,18 @@ const protocol_1 = require("./protocol");
 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_HEARTBEAT_INTERVAL_MS = 1_000;
-const ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
-const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
 const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
 const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
 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 systemLivenessClock = {
     now: () => performance.now(),
-    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    setTimer: (callback, delayMs) => setTimeout(callback, Math.min(delayMs, MAX_TIMER_DELAY_MS)),
     clearTimer: (timer) => clearTimeout(timer)
 };
 class ZLinkStreamReceiveWake {
@@ -69,12 +68,15 @@ class ZLinkStreamSessionRuntime {
     closeReason = 'client_close';
     metricsClosed = false;
     livenessClock;
+    liveness;
     lastApplicationActivityAt = 0;
     lastInboundFrameAt = 0;
+    lastHeartbeatPingAt = 0;
     livenessTimer;
     constructor(options, routingId, removeSession = () => { }) {
         this.options = options;
         this.removeSession = removeSession;
+        this.liveness = (0, RegistrationNormalizers_1.normalizeStreamLiveness)(options);
         this.livenessClock = options.livenessClock ?? systemLivenessClock;
         this.stream = new managed_stream_1.ZLinkManagedStream(options.socket, routingId, options.messageSerializers, options.nativeSessionService, options.meshCompletions, undefined, options.nativeSessionRouteForMesh);
         this.context = options.bindingRuntime.createSessionContext(this.stream, (signal) => this.close(signal), options.providerResolver);
@@ -112,7 +114,7 @@ class ZLinkStreamSessionRuntime {
         return this.sessionReady;
     }
     enqueueConnected(localAddr, remoteAddr) {
-        this.serial.executeInfrastructure(async () => this.markConnected(localAddr, remoteAddr));
+        this.serial.executeControl(async () => this.markConnected(localAddr, remoteAddr));
     }
     enqueuePacket(payload, decodedHeader, terminalOwner, applicationJobPermit) {
         this.lastInboundFrameAt = Math.max(this.lastInboundFrameAt, this.livenessClock.now());
@@ -124,41 +126,20 @@ class ZLinkStreamSessionRuntime {
             terminalOwner?.close();
         };
         if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Control) {
-            if ((0, protocol_1.messageToBytes)(payload).length === 0 &&
-                (decodedHeader.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG ||
-                    decodedHeader.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING)) {
-                void this.handleControl(decodedHeader, payload)
-                    .catch((error) => {
-                    this.options.onError?.(error);
-                })
-                    .finally(() => {
-                    applicationJobPermit?.releaseAfterInternalProcessing();
-                    payload.close();
-                    releaseTerminal();
-                });
-                return;
-            }
-            this.enqueueControl(async () => {
-                try {
-                    const dispatch = () => this.dispatchPacket(payload, decodedHeader);
-                    if (applicationJobPermit === undefined)
-                        await dispatch();
-                    else
-                        await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, dispatch);
-                }
-                finally {
-                    releaseTerminal();
-                }
-            }, () => {
+            void this.handleControl(decodedHeader, payload)
+                .catch((error) => {
+                this.options.onError?.(error);
+            })
+                .finally(() => {
                 applicationJobPermit?.releaseAfterInternalProcessing();
                 payload.close();
                 releaseTerminal();
-            }, () => this.traceShutdownDrop(decodedHeader));
+            });
             return;
         }
         if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Response ||
             decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Error) {
-            this.enqueueInfrastructure(async () => {
+            this.enqueueControl(async () => {
                 try {
                     await this.dispatchPacket(payload, decodedHeader);
                 }
@@ -198,8 +179,7 @@ class ZLinkStreamSessionRuntime {
         this.queueDisconnect(error);
     }
     /**
-     * Starts the callback on the session lane and observes its terminal result
-     * without retaining that lane while application code awaits unrelated work.
+     * Retains the session turn through the callback's terminal result.
      */
     enqueueActorBindingReplaced(actor, retiredSession) {
         this.serial.executeControl(async () => {
@@ -209,7 +189,6 @@ class ZLinkStreamSessionRuntime {
                 return;
             const session = await this.requireSession();
             let callbackDeadlineTimer;
-            let callbackTerminal = false;
             let forcedClose = false;
             const scheduleClose = () => {
                 if (forcedClose)
@@ -223,25 +202,6 @@ class ZLinkStreamSessionRuntime {
                     void this.close().catch((error) => this.options.onError?.(error));
                 }, ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS);
             };
-            const completeCallback = () => {
-                if (callbackTerminal)
-                    return;
-                callbackTerminal = true;
-                if (callbackDeadlineTimer !== undefined) {
-                    this.livenessClock.clearTimer(callbackDeadlineTimer);
-                    callbackDeadlineTimer = undefined;
-                }
-                scheduleClose();
-            };
-            const reportCallbackFailure = (error) => {
-                try {
-                    this.options.onError?.(error);
-                }
-                catch {
-                    // Diagnostics must not prevent the lifecycle terminal transition.
-                }
-                completeCallback();
-            };
             callbackDeadlineTimer = this.livenessClock.setTimer(() => {
                 if (this.disposed ||
                     this.disconnected ||
@@ -251,19 +211,17 @@ class ZLinkStreamSessionRuntime {
                 forcedClose = true;
                 void this.close().catch((error) => this.options.onError?.(error));
             }, this.options.replacementCallbackTimeoutMs ?? Registration_1.DEFAULT_SESSION_REPLACEMENT_CALLBACK_TIMEOUT_MS);
-            const callback = session.onActorBindingReplaced;
-            if (callback === undefined) {
-                completeCallback();
-                return;
-            }
             try {
-                // Start the callback on this lifecycle turn, but do not retain the
-                // serial lane while application code awaits an unrelated operation.
-                const result = callback.call(session, this.context, actor.actorId);
-                void Promise.resolve(result).then(() => completeCallback(), reportCallbackFailure);
+                await session.onActorBindingReplaced?.(this.context, actor.actorId);
             }
             catch (error) {
-                reportCallbackFailure(error);
+                this.options.onError?.(error);
+            }
+            finally {
+                if (callbackDeadlineTimer !== undefined) {
+                    this.livenessClock.clearTimer(callbackDeadlineTimer);
+                }
+                scheduleClose();
             }
         });
     }
@@ -313,6 +271,7 @@ class ZLinkStreamSessionRuntime {
         this.connected = true;
         const connectedAt = this.livenessClock.now();
         this.lastApplicationActivityAt = connectedAt;
+        this.lastHeartbeatPingAt = connectedAt;
         this.lastInboundFrameAt = Math.max(this.lastInboundFrameAt, connectedAt);
         this.scheduleLivenessCheck();
         this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.StreamConnectionsActive, 1, { transport: 'tcp' });
@@ -324,15 +283,8 @@ class ZLinkStreamSessionRuntime {
         let dispatchPayload = payload;
         let enteredDispatch = false;
         try {
-            if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Control) {
-                await this.handleControl(decodedHeader, payload);
-                return;
-            }
             this.lastApplicationActivityAt = this.livenessClock.now();
             dispatchPayload = this.context.payloadForHeader(decodedHeader, payload);
-            if (this.context.tryCompleteResponse(decodedHeader, dispatchPayload)) {
-                return;
-            }
             const dispatchActor = this.context.actorForSlot(decodedHeader.actorSlot);
             if (decodedHeader.actorSlot !== undefined && dispatchActor === undefined) {
                 const staleFlowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
@@ -466,25 +418,33 @@ class ZLinkStreamSessionRuntime {
         if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
             return;
         }
+        const now = this.livenessClock.now();
+        const due = Math.min(this.lastHeartbeatPingAt + this.liveness.heartbeatIntervalMs, this.lastInboundFrameAt + this.liveness.heartbeatTimeoutMs, this.liveness.idleTimeoutMs > 0
+            ? this.lastApplicationActivityAt + this.liveness.idleTimeoutMs
+            : Infinity);
         this.livenessTimer = this.livenessClock.setTimer(() => {
             this.livenessTimer = undefined;
-            this.serial.executeInfrastructure(async () => this.runLivenessCheck(), {}, (error) => this.options.onError?.(error));
-        }, ZLINK_STREAM_HEARTBEAT_INTERVAL_MS);
+            void this.runLivenessCheck().catch((error) => this.options.onError?.(error));
+        }, Math.max(0, due - now));
     }
     async runLivenessCheck() {
         if (this.disposed || this.disconnected || !this.connected) {
             return;
         }
         const now = this.livenessClock.now();
-        if (now - this.lastApplicationActivityAt >= ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS) {
+        if (this.liveness.idleTimeoutMs > 0 &&
+            now - this.lastApplicationActivityAt >= this.liveness.idleTimeoutMs) {
             await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.IdleTimeout, 'idle_timeout', 'Application idle timeout.');
             return;
         }
-        if (now - this.lastInboundFrameAt >= ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS) {
+        if (now - this.lastInboundFrameAt >= this.liveness.heartbeatTimeoutMs) {
             await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.HeartbeatTimeout, 'heartbeat_timeout', 'Heartbeat timeout.');
             return;
         }
-        await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PING);
+        if (now - this.lastHeartbeatPingAt >= this.liveness.heartbeatIntervalMs) {
+            this.lastHeartbeatPingAt = now;
+            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PING);
+        }
         this.scheduleLivenessCheck();
     }
     async closeForLiveness(reason, closeReason, diagnostic) {
@@ -496,7 +456,9 @@ class ZLinkStreamSessionRuntime {
         this.closeReason = closeReason;
         this.stopLivenessChecks();
         await this.stream.closeForReason(reason, diagnostic);
-        await this.complete(undefined, true);
+        void this.serial
+            .executeFinal(async () => this.complete(undefined, true))
+            .catch((error) => this.options.onError?.(error));
     }
     stopLivenessChecks() {
         if (this.livenessTimer !== undefined) {
@@ -609,13 +571,6 @@ class ZLinkStreamSessionRuntime {
             onRejected?.();
         }
     }
-    enqueueInfrastructure(work, onRejected, onShutdownRejected) {
-        if (!this.serial.executeInfrastructure(work, {}, onRejected)) {
-            // The serial lane only refuses new work after dispose() closed it.
-            onShutdownRejected?.();
-            onRejected?.();
-        }
-    }
     enqueueApplication(work, onRejected, onShutdownRejected) {
         let claim;
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.28.0",
+  "version": "0.29.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.28.0",
-    "@zlink-systems/zlink": "1.15.0"
+    "@zlink-systems/stream-wire": "0.29.1",
+    "@zlink-systems/zlink": "1.17.0"
   }
 }

package/src/contracts/Configuration/Builders.ts

@@ -187,6 +187,8 @@ export interface ZLinkFanoutChannelBuilder {
 }
 
 export interface ZLinkStreamNodeBuilder {
+  setHeartbeat(intervalMs: number, timeoutMs: number): this;
+  setIdleTimeout(timeoutMs: number): this;
   bind(endpointOrPort?: string | number): this;
   setBindHost(bindHost: string): this;
   setAdvertiseHost(advertiseHost: string): this;

package/src/contracts/Configuration/InternalDefaults.ts

@@ -22,3 +22,7 @@ export const ZLINK_RELOCATION_MAX_BLOB_REFERENCE_BYTES = 4096;
 export const AUTHORITY_ENVELOPE_MAX_BYTES = 1024 * 1024;
 export const CREATION_INTENT_MAX_BYTES = 1024 * 1024;
 export const CREATION_TERMINAL_ENVELOPE_MAX_BYTES = 1024 * 1024;
+
+export const DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS = 1_000;
+export const DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 0;

package/src/contracts/Configuration/RegistrationBuilders.ts

@@ -689,6 +689,16 @@ class DefaultClientServerChannelServerBuilder implements ZLinkClientServerChanne
 }
 
 class DefaultStreamNodeBuilder implements ZLinkStreamNodeBuilder {
+  setHeartbeat(intervalMs: number, timeoutMs: number): this {
+    this.streamNode.heartbeatIntervalMs = intervalMs;
+    this.streamNode.heartbeatTimeoutMs = timeoutMs;
+    return this;
+  }
+  setIdleTimeout(timeoutMs: number): this {
+    this.streamNode.idleTimeoutMs = timeoutMs;
+    return this;
+  }
+
   constructor(private readonly streamNode: MutableStreamNodeOptions) {}
 
   bind(endpointOrPort: string | number = 0): this {
@@ -1605,6 +1615,9 @@ interface MutablePublisherCapabilityOptions {
 }
 
 interface MutableStreamNodeOptions {
+  heartbeatIntervalMs?: number;
+  heartbeatTimeoutMs?: number;
+  idleTimeoutMs?: number;
   bind?: string;
   bindHost?: string;
   advertiseHost?: string;

package/src/contracts/Configuration/RegistrationNormalizers.ts

@@ -21,6 +21,9 @@ import { normalizeEndpoint, parseEndpointHostPort } from './EndpointNotation';
 import {
   defaultWorkerMaxThreads,
   DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE,
+  DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS,
+  DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   DEFAULT_WORKER_IDLE_TIMEOUT_MS,
   DEFAULT_WORKER_MIN_THREADS
 } from './InternalDefaults';
@@ -77,6 +80,27 @@ export function toChannelMap(
   );
 }
 
+export function normalizeStreamLiveness(
+  options: ZLinkStreamNodeOptions
+): Required<
+  Pick<ZLinkStreamNodeOptions, 'heartbeatIntervalMs' | 'heartbeatTimeoutMs' | 'idleTimeoutMs'>
+> {
+  const heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_STREAM_HEARTBEAT_INTERVAL_MS;
+  const heartbeatTimeoutMs = options.heartbeatTimeoutMs ?? DEFAULT_STREAM_HEARTBEAT_TIMEOUT_MS;
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+  if (!Number.isFinite(heartbeatIntervalMs) || heartbeatIntervalMs <= 0)
+    throw new ZLinkConfigurationException('STREAM heartbeat interval must be positive.');
+  if (!Number.isFinite(heartbeatTimeoutMs) || heartbeatTimeoutMs <= 0)
+    throw new ZLinkConfigurationException('STREAM heartbeat timeout must be positive.');
+  if (heartbeatTimeoutMs <= heartbeatIntervalMs)
+    throw new ZLinkConfigurationException(
+      'STREAM heartbeat timeout must be greater than interval.'
+    );
+  if (!Number.isFinite(idleTimeoutMs) || idleTimeoutMs < 0)
+    throw new ZLinkConfigurationException('STREAM idle timeout must not be negative.');
+  return { heartbeatIntervalMs, heartbeatTimeoutMs, idleTimeoutMs };
+}
+
 export function toStreamNodeMap(
   streamNodes: ZLinkFrameworkRegistrationOptions['streamNodes'],
   network: ZLinkNetworkOptions
@@ -88,6 +112,7 @@ export function toStreamNodeMap(
         name,
         {
           ...normalized,
+          ...normalizeStreamLiveness(streamNode),
           maxMessageSize: streamNode.maxMessageSize ?? DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE
         }
       ];

package/src/contracts/Configuration/RegistrationTypes.ts

@@ -233,6 +233,9 @@ export interface ZLinkRouteChannelOptions {
 }
 
 export interface ZLinkStreamNodeOptions {
+  readonly heartbeatIntervalMs?: number;
+  readonly heartbeatTimeoutMs?: number;
+  readonly idleTimeoutMs?: number;
   readonly bind?: string;
   readonly bindHost?: string;
   readonly advertiseHost?: string;

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

@@ -17,9 +17,14 @@ export class ZLinkActorSerialExecutor {
   constructor(
     private readonly actorId: string,
     private readonly sourceSpotId: unknown,
-    options?: ZLinkSerialSchedulerOptions
+    options?: ZLinkSerialSchedulerOptions,
+    sharedOwner?: ZLinkSerialExecutionQueue
   ) {
-    this.scheduler = new ZLinkSerialExecutionQueue((record) => this.runRecord(record), options);
+    this.scheduler = new ZLinkSerialExecutionQueue(
+      (record) => this.runRecord(record),
+      options,
+      sharedOwner
+    );
   }
 
   execute<T>(operation: () => Promise<T> | T, workOptions?: ZLinkSerialWorkOptions): Promise<T> {

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

@@ -49,6 +49,10 @@ export interface ZLinkActorManagerOptions {
     signal?: AbortSignal
   ) => Promise<ZLinkActorCreateResponse | undefined>;
   readonly actorDestroyedCleanup?: (actorId: string) => void;
+  readonly terminateActorActivation?: (
+    actor: ZLinkActor,
+    terminal: () => Promise<void>
+  ) => Promise<void>;
   readonly publishActorAuthority?: (
     actorType: string,
     actorRef: ActorRef,

package/src/runtime/actors/index.ts

@@ -29,6 +29,7 @@ import {
   wireReplyFailureException
 } from '../framework-errors-internal';
 import { disposeLifecycleHandlers } from '../handlers/handler-instance-scope';
+import { currentZLinkActorExecution } from './actor-execution-context';
 import { encodeFrameworkPayloadMessage } from '../messaging/payload-codec';
 import { ZLinkActorCreationCoordinator, type ZLinkActorCreateRequest } from './actor-creation';
 import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
@@ -217,34 +218,43 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
     const completions = this.options.nativeActorCompletionTableProvider?.();
     const entryNodeRid = state.entryNodeRid ?? current.nodeRid;
     if (node === undefined || completions === undefined) return false;
-    const destroyTask = state.getOrStartDestroy(entryNodeRid, async (nativeRef) => {
-      if (nativeRef !== undefined) {
-        const completion = await completions.submit(() => node.destroyActor(nativeRef, 0), signal);
-        try {
-          if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-            //  Classify the (terminal, fine) pair via the shared translator
-            //  (spec 32-framework-error-model:83-118, 99-108) instead of
-            //  collapsing every destroy failure to NotFound; genuine
-            //  route-not-found fine codes still yield NotFound through the
-            //  shared table.
-            throw wireReplyFailureException(
-              completion.terminalResult,
-              completion.failureErrno,
-              `Actor '${actor.actorId}' destroy failed with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`
-            );
+    const destroyTask = state.getOrStartDestroy(entryNodeRid, (nativeRef) =>
+      this.terminateActor(state, async () => {
+        if (nativeRef !== undefined) {
+          const completion = await completions.submit(
+            () => node.destroyActor(nativeRef, 0),
+            signal
+          );
+          try {
+            if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+              //  Classify the (terminal, fine) pair via the shared translator
+              //  (spec 32-framework-error-model:83-118, 99-108) instead of
+              //  collapsing every destroy failure to NotFound; genuine
+              //  route-not-found fine codes still yield NotFound through the
+              //  shared table.
+              throw wireReplyFailureException(
+                completion.terminalResult,
+                completion.failureErrno,
+                `Actor '${actor.actorId}' destroy failed with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`
+              );
+            }
+          } finally {
+            closeMeshCompletion(completion);
           }
-        } finally {
-          closeMeshCompletion(completion);
+          state.markNativeActorDestroyed(nativeRef);
         }
-        state.markNativeActorDestroyed(nativeRef);
-      }
-      if (state.actorType !== undefined && state.ownsLocation) {
-        await this.options.locationLifecycle?.releaseActor(state.actorType, actor.actorId, current);
-      }
-      await this.finalizeDestroyedActor(actor.actorId, state);
-    });
+        if (state.actorType !== undefined && state.ownsLocation) {
+          await this.options.locationLifecycle?.releaseActor(
+            state.actorType,
+            actor.actorId,
+            current
+          );
+        }
+        await this.finalizeDestroyedActor(actor.actorId, state);
+      })
+    );
     try {
-      await destroyTask;
+      await this.awaitActorDestroy(state, destroyTask);
     } catch (error) {
       state.clearFailedDestroy(destroyTask);
       throw error;
@@ -548,6 +558,29 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
       this.options.metrics?.change(METRIC_NAMES.ActorCount, -1);
     }
   }
+
+  private terminateActor(
+    state: ZLinkActorRuntimeState,
+    terminal: () => Promise<void>
+  ): Promise<void> {
+    const actor = state.actor;
+    const completion =
+      actor === undefined || this.options.terminateActorActivation === undefined
+        ? terminal()
+        : this.options.terminateActorActivation(actor, terminal);
+    return completion;
+  }
+
+  private awaitActorDestroy(
+    state: ZLinkActorRuntimeState,
+    completion: Promise<void>
+  ): Promise<void> {
+    if (currentZLinkActorExecution()?.actorId === state.actorId) {
+      this.detachedTaskRunner.runDetached('Actor terminal cleanup', () => completion);
+      return Promise.resolve();
+    }
+    return completion;
+  }
   async getOrCreateActor(
     actorId: string,
     actorType: string,
@@ -648,25 +681,27 @@ export class DefaultZLinkActorManager implements ZLinkActorManager {
         `Actor '${actor.context.actorId}' must leave its current SPOT before destroy.`
       );
     }
-    const destroyTask = state.getOrStartDestroy(entryNodeRid, async (actorRef) => {
-      const destroyedActorRef =
-        actorRef === undefined ? undefined : toFrameworkActorRef(actorRef, state.meshName ?? '');
-      if (actorRef !== undefined) {
-        await node.destroyActor(actorRef, 0, destroySignal);
-        state.markNativeActorDestroyed(actorRef);
-      }
-      if (state.actorType !== undefined && state.ownsLocation) {
-        await this.options.locationLifecycle?.releaseActor(
-          state.actorType,
-          actor.context.actorId,
-          destroyedActorRef
-        );
-      }
-      await this.finalizeDestroyedActor(actor.context.actorId, state);
-    });
+    const destroyTask = state.getOrStartDestroy(entryNodeRid, (actorRef) =>
+      this.terminateActor(state, async () => {
+        const destroyedActorRef =
+          actorRef === undefined ? undefined : toFrameworkActorRef(actorRef, state.meshName ?? '');
+        if (actorRef !== undefined) {
+          await node.destroyActor(actorRef, 0, destroySignal);
+          state.markNativeActorDestroyed(actorRef);
+        }
+        if (state.actorType !== undefined && state.ownsLocation) {
+          await this.options.locationLifecycle?.releaseActor(
+            state.actorType,
+            actor.context.actorId,
+            destroyedActorRef
+          );
+        }
+        await this.finalizeDestroyedActor(actor.context.actorId, state);
+      })
+    );
 
     try {
-      await destroyTask;
+      await this.awaitActorDestroy(state, destroyTask);
     } catch (error) {
       state.clearFailedDestroy(destroyTask);
       throw error;

package/src/runtime/backend/node/node-raw-mesh-backend.ts

@@ -297,19 +297,13 @@ export class ZLinkNodeRawMeshBackend implements ZLinkBackendMeshNode {
   selectObjectPlacement(stableType: string): ZLinkBackendObjectPlacement {
     const runtime = this.requireRuntime();
     const localNodeRid = runtime.topology.localDescriptor().nodeRoutingId;
-    const status = runtime.topology.objectPlacementStatus(
+    const { status, descriptor } = runtime.topology.selectObjectPlacementWithStatus(
       stableType,
       (candidate) =>
         candidate.nodeRoutingId === localNodeRid ||
         runtime.isPeerRouteReady(candidate.nodeRoutingId)
     );
     if (status !== 'available') return { kind: status };
-    const descriptor = runtime.topology.selectObjectPlacement(
-      stableType,
-      (candidate) =>
-        candidate.nodeRoutingId === localNodeRid ||
-        runtime.isPeerRouteReady(candidate.nodeRoutingId)
-    );
     return descriptor === undefined
       ? { kind: 'unavailable' }
       : {