@zlink-systems/framework 0.30.1 → 0.30.2

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

@@ -9,6 +9,7 @@ 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 { type ZLinkBoundActorRelaySenderOptions } from './bound-actor-relay-sender';
 import { type ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
 import { type ZLinkBoundSessionTransport } from './bound-session-service';
 import { ZLinkManagedStream } from './managed-stream';
@@ -45,7 +46,7 @@ export interface ZLinkStreamBindingRuntimeOptions {
         reportRuntimeTaskException(taskName: string, error: unknown): void;
     } | undefined;
     readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message) => Promise<boolean>;
-    readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
+    readonly notifyDisconnected?: ZLinkBoundActorRelaySenderOptions['notifyDisconnected'];
     readonly flowCreationEnabled?: () => boolean;
     readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
 }
@@ -139,7 +140,7 @@ export declare class ZLinkStreamBindingRuntime {
     sendNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;
     sendNativeBoundSessionResponse(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, message: unknown, metadata: ReadonlyMap<string, string>, compressPayload: boolean, signal?: AbortSignal): Promise<void>;
     sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
-    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, timeoutMs: number, signal?: AbortSignal): Promise<void>;
     disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
     closeSessionBinding(actorId: string, expected: ZLinkSessionBindingIdentity, signal?: AbortSignal): Promise<void>;
     relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;

package/dist/runtime/streams/index.js

@@ -220,12 +220,14 @@ class ZLinkStreamBindingRuntime {
         this.sessionActors = new session_actor_coordinator_1.ZLinkSessionActorCoordinator(this.routes, this, runtimeOptions, actorSessionLifecycle);
         this.boundActorRelay = new bound_actor_relay_sender_1.ZLinkBoundActorRelaySender(this.routes, this.frameMessages, runtimeOptions, actorSessionLifecycle);
         (0, actor_session_binding_runtime_owner_1.registerActorSessionBindingRuntimeOwner)(this, {
+            prepareSessionRelocationSeal: (...args) => this.routes.prepareSessionRelocationSeal(...args),
+            acceptSessionRelocationRoute: (value, apply) => this.routes.acceptSessionRelocationRoute(value, apply),
+            clearSessionRelocationResults: () => this.routes.clearSessionRelocationResults(),
             actorSlot: async (actorId, sessionRid) => (await this.routes.routeForSessionBinding(actorId, sessionRid))?.actorSlot,
-            sealRelocation: (claim, expected, signal) => this.routes.sealRelocation(claim, expected, signal),
             relocationSnapshot: (actorId, sealId) => this.routes.relocationSnapshot(actorId, sealId),
             applyRelocation: (...args) => this.routes.applyRelocation(...args),
             observeRelocationTerminal: (...args) => this.routes.observeRelocationTerminal(...args),
-            clearRelocation: (actorId, error) => this.routes.clearRelocation(actorId, error),
+            clearRelocation: (...args) => this.routes.clearRelocation(...args),
             committedRoute: async (actorId) => {
                 const route = await this.routes.route(actorId);
                 return route === undefined
@@ -319,8 +321,8 @@ class ZLinkStreamBindingRuntime {
     async sendNativeBoundSessionError(node, actorRef, packetName, requestSeq, error, metadata, signal) {
         await this.boundSessions.sendNativeBoundSessionError(node, actorRef, packetName, requestSeq, error, metadata, signal);
     }
-    async disconnectNativeBoundSession(node, actorRef, signal) {
-        await this.boundSessions.disconnectNativeBoundSession(node, actorRef, signal);
+    async disconnectNativeBoundSession(node, actorRef, timeoutMs, signal) {
+        await this.boundSessions.disconnectNativeBoundSession(node, actorRef, timeoutMs, signal);
     }
     async disconnectBoundSession(actorId, signal) {
         await this.boundSessions.disconnectBoundSession(actorId, signal);

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkManagedStream = void 0;
 exports.streamSessionIdFromRoutingId = streamSessionIdFromRoutingId;
+const routing_id_1 = require("../routing-id");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const submission_result_1 = require("../messaging/submission-result");
 const abort_1 = require("../abort");
@@ -140,7 +141,7 @@ class ZLinkManagedStream {
                 ? undefined
                 : (_actorId, retiredSession, replacedActor) => {
                     onBindingReplaced(replacedActor, retiredSession);
-                }, toStreamSessionActorAuthorityFence(authorityFence)), signal), `Actor '${actor.actorId}' native session bind`);
+                }, toStreamSessionActorAuthorityFence(authorityFence), () => this.close()), signal), `Actor '${actor.actorId}' native session bind`);
             const binding = route.service
                 .bindings(this.backendRoutingId())
                 .find((candidate) => candidate.actor.actorId === nativeActor.actorId &&
@@ -180,7 +181,7 @@ class ZLinkManagedStream {
                 resolved === undefined ||
                 resolved.actorId !== actor.actorId ||
                 resolved.generation !== actor.objectGeneration ||
-                String(resolved.nodeRid) !== String(actor.nodeRid)) {
+                !(0, routing_id_1.routingIdsEqual)(resolved.nodeRid, actor.nodeRid)) {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.actorId}' native route fence does not match its ActorRef ` +
                     `(expected ${String(actor.nodeRid)}/${actor.objectGeneration}, ` +
                     `resolved ${(0, diagnostic_text_1.diagnosticTextOrAbsent)(resolved === undefined

package/dist/runtime/streams/native-fallback-bound-session.js

@@ -1,14 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkNativeFallbackBoundSession = void 0;
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const contracts_1 = require("../../contracts");
 const submission_result_1 = require("../messaging/submission-result");
 const actors_1 = require("../actors");
 const actor_packet_relay_wire_1 = require("../actors/actor-packet-relay-wire");
 const bound_session_wire_1 = require("../actors/bound-session-wire");
-const actor_routed_json_request_1 = require("../actors/actor-routed-json-request");
-const protocol_1 = require("./protocol");
 const packet_name_1 = require("../messaging/packet-name");
 const flow_context_1 = require("../diagnostics/flow-context");
 class ZLinkNativeFallbackBoundSession {
@@ -20,40 +19,12 @@ class ZLinkNativeFallbackBoundSession {
         return new ZLinkNativeFallbackBoundSessionSendCall(this.options, message);
     }
     async disconnect(signal) {
-        const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-        if (remoteTarget !== undefined) {
-            const spotKind = 'spotKind' in remoteTarget
-                ? remoteTarget.spotKind
-                : undefined;
-            const payload = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
-                actorId: this.options.actorId,
-                routerChannelId: remoteTarget.routerChannelId,
-                header: (0, protocol_1.encodeStreamHeader)(disconnectedFrameHeader()),
-                payload: Buffer.alloc(0)
-            });
-            const target = {
-                routerChannelId: remoteTarget.routerChannelId,
-                targetNodeRid: remoteTarget.targetNodeRid,
-                spotId: remoteTarget.spotId,
-                spotKind: spotKind ?? contracts_1.ZLinkSpotKind.Entry
-            };
-            if (await (0, actor_routed_json_request_1.tryRequestRoutedJson)(this.options.routedTransport, target, payload, {
-                timeoutMs: this.options.requestTimeoutMs,
-                signal
-            })) {
-                return;
-            }
-            await this.options.routedTransport.sendToSpot(target, payload, {
-                packetName: actors_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET
-            });
-            return;
-        }
         const actorRef = this.options.actorRefProvider();
         const node = this.options.nativeActorNodeProvider();
         if (actorRef !== undefined &&
             node !== undefined &&
             currentBindingGeneration(actorRef) !== undefined) {
-            await this.options.runtime.disconnectNativeBoundSession(node, actorRef, signal);
+            await this.options.runtime.disconnectNativeBoundSession(node, actorRef, this.options.requestTimeoutMs ?? Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, signal);
             return;
         }
         await this.options.runtime.disconnectBoundSession(this.options.actorId, signal);
@@ -96,30 +67,11 @@ class ZLinkNativeFallbackBoundSessionSendCall {
     async executeScoped(packetName) {
         const localActor = this.options.localActorProvider?.() === true;
         const remoteTarget = this.options.remoteBoundSessionTargetProvider();
-        let nativeAttempted = false;
-        if (localActor) {
-            const result = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
-            if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-                this.traceSubmitted(result, packetName);
-                return result;
-            }
-            // A local Actor with a concrete native owner has a direct binding path.
-            // Use that path before a routed transfer target. The transfer target is
-            // retained for actors whose current owner is remote or whose native
-            // binding is no longer available.
-            const actorRef = this.options.actorRefProvider();
-            const node = this.options.nativeActorNodeProvider();
-            const bindingGeneration = currentBindingGeneration(actorRef);
-            if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
-                nativeAttempted = true;
-                const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata);
-                if (result.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-                    this.traceSubmitted(result, packetName);
-                    return result;
-                }
-                if (remoteTarget === undefined) {
-                    return result;
-                }
+        if (localActor || remoteTarget === undefined) {
+            const localResult = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
+            if (localResult.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
+                this.traceSubmitted(localResult, packetName);
+                return localResult;
             }
         }
         if (remoteTarget !== undefined) {
@@ -152,18 +104,10 @@ class ZLinkNativeFallbackBoundSessionSendCall {
             this.traceSubmitted(result, packetName);
             return result;
         }
-        const localResult = await this.options.runtime.submitLocalBoundSession(this.options.actorId, this.message, packetName, this.selectedMetadata);
-        if (localResult.status !== submission_result_1.ZLinkSubmitStatus.TargetNotFound) {
-            this.traceSubmitted(localResult, packetName);
-            return localResult;
-        }
         const actorRef = this.options.actorRefProvider();
         const node = this.options.nativeActorNodeProvider();
         const bindingGeneration = currentBindingGeneration(actorRef);
-        if (!nativeAttempted &&
-            actorRef !== undefined &&
-            node !== undefined &&
-            bindingGeneration !== undefined) {
+        if (actorRef !== undefined && node !== undefined && bindingGeneration !== undefined) {
             const result = await this.options.runtime.sendNativeBoundSession(node, actorRef, this.message, packetName, this.selectedMetadata);
             this.traceSubmitted(result, packetName);
             return result;
@@ -189,12 +133,3 @@ function currentBindingGeneration(actorRef) {
 function positiveBindingGeneration(generation) {
     return generation !== undefined && generation > 0n ? generation : undefined;
 }
-function disconnectedFrameHeader() {
-    return {
-        kind: protocol_1.ZLinkStreamMessageKind.Send,
-        codec: protocol_1.ZLinkStreamCodec.Raw,
-        flags: protocol_1.ZLinkStreamHeaderFlags.None,
-        name: actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET,
-        metadata: new Map()
-    };
-}

package/dist/runtime/streams/session-actor-coordinator.d.ts

@@ -3,7 +3,7 @@ import type { ZLinkRuntimeMetrics } from '../diagnostics';
 import { ZLinkActorSessionBindingRegistry, type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
 import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
 import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
-import type { ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
+import type { ZLinkActorRouteCommitOptions, ZLinkSessionBindingConfirmationOptions } from './stream-binding-runtime-ports';
 export interface ZLinkSessionActorCoordinatorOptions {
     readonly actorBindTimeoutMs?: number;
     readonly actorRefResolver?: (actor: ZLinkActor) => ActorRef;
@@ -28,17 +28,11 @@ export declare class ZLinkSessionActorCoordinator {
     constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, sessionActorRuntime: ConstructorParameters<typeof DefaultZLinkSessionActor>[0], options?: ZLinkSessionActorCoordinatorOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
     bind(context: DefaultZLinkSessionContext, actorOrRef: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     private replaceBinding;
-    private replaceBindingCore;
     private resolveAuthorityFence;
     bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
     rebindActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
     refreshActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
-    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: {
-        readonly confirmRemoteSessionBinding?: boolean | 'send';
-        readonly releaseSeal?: {
-            readonly sealId: string;
-        };
-    }): Promise<void>;
+    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: ZLinkActorRouteCommitOptions): Promise<void>;
     retireRemoteBinding(actorRef: ActorRef, sessionRid: ActorRef['nodeRid'], bindingGeneration: bigint, signal?: AbortSignal): Promise<boolean>;
     authorityFence(actorId: string): Promise<{
         readonly authorityOwnerGeneration: bigint;

package/dist/runtime/streams/session-actor-coordinator.js

@@ -26,10 +26,7 @@ class ZLinkSessionActorCoordinator {
             : this.resolveActorRef(actorOrRef);
         return await this.lifecycle.run(actorRef.actorId, async () => this.replaceBinding(context, actorRef, signal));
     }
-    async replaceBinding(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
-        return await this.replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding, releaseSeal);
-    }
-    async replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
+    async replaceBinding(context, actorRef, signal) {
         (0, abort_1.throwIfAborted)(signal);
         if (actorRef.actorId.trim().length === 0) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, 'Actor id must not be empty.');
@@ -60,22 +57,15 @@ class ZLinkSessionActorCoordinator {
             : undefined, previous?.actor.ref);
         const sessionActor = reuseActor ??
             new session_context_1.DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
-        const sessionIdentity = String(this.actorBindingRoutingId(context));
+        const sessionIdentity = this.actorBindingRoutingId(context);
         if (previous === undefined) {
-            if (releaseSeal !== undefined) {
-                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorRef.actorId}' route switch has no Session binding to release.`, true);
-            }
             await this.routes.bind(context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
-        else if (releaseSeal !== undefined) {
-            await this.routes.replaceAndReleaseSeal(previous, context, sessionActor, bindingToken, releaseSeal.sealId, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
-        }
         else {
             await this.routes.replace(previous, context, sessionActor, bindingToken, authorityFence, sessionIdentity, () => sessionActor.updateRef(boundActorRef));
         }
-        if (confirmRemoteSessionBinding !== false &&
-            this.options.confirmRemoteActorSessionBinding !== undefined) {
-            const waitForAcknowledgement = previous === undefined && confirmRemoteSessionBinding !== 'send';
+        if (this.options.confirmRemoteActorSessionBinding !== undefined) {
+            const waitForAcknowledgement = previous === undefined;
             const confirmation = this.options.confirmRemoteActorSessionBinding(boundActorRef, this.actorBindingRoutingId(context), undefined, {
                 waitForAcknowledgement,
                 binding: context.stream instanceof managed_stream_1.ZLinkManagedStream
@@ -204,25 +194,18 @@ class ZLinkSessionActorCoordinator {
             if (route === undefined)
                 return;
             requireSameIncarnation(route.actor.ref, normalizedActorRef);
-            if ((0, routing_id_1.routingIdsEqual)(route.actor.ref.nodeRid, normalizedActorRef.nodeRid)) {
-                const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
-                if (options.releaseSeal !== undefined &&
-                    !(await this.routes.validateSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))) {
-                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch did not match its relocation seal.`, true);
-                }
-                // A location refresh never changes the route's Session binding
-                // generation; the native bind owns it.
-                route.actor.updateRef(withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined));
-                if (authorityFence !== undefined) {
-                    await this.routes.updateAuthorityFence(normalizedActorRef.actorId, authorityFence);
-                }
-                if (options.releaseSeal !== undefined &&
-                    !(await this.routes.abortSeal(normalizedActorRef.actorId, options.releaseSeal.sealId))) {
-                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch lost its relocation seal.`, true);
-                }
-                return;
+            const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
+            // Relocation changes only the Actor route of this physical binding.
+            // Publish the ref and authority together in the binding registry's turn;
+            // a native bind would issue a different binding generation.
+            const boundActorRef = withBindingGeneration(normalizedActorRef, bindingGenerationOf(route.actor.ref), undefined);
+            const commitActor = () => route.actor.updateRef(boundActorRef);
+            if (options.releaseSeal !== undefined) {
+                await this.routes.replaceAndReleaseSeal(route, route.context, route.actor, route.bindingToken, options.releaseSeal.sealId, authorityFence, route.sessionIdentity, commitActor);
+            }
+            else {
+                await this.routes.replace(route, route.context, route.actor, route.bindingToken, authorityFence, route.sessionIdentity, commitActor);
             }
-            await this.replaceBinding(route.context, normalizedActorRef, signal, options.confirmRemoteSessionBinding, options.releaseSeal);
         });
     }
     async retireRemoteBinding(actorRef, sessionRid, bindingGeneration, signal) {

package/dist/runtime/streams/stream-binding-runtime-ports.d.ts

@@ -26,15 +26,8 @@ export interface ZLinkStreamActorLifecyclePort {
 }
 export interface ZLinkActorRouteCommitOptions {
     /**
-     * Relocation already carries the binding identity to the target actor. The
-     * follow-up confirmation can use a one-way route submission because a
-     * request/ACK would create a nested route request while the Session
-     * ownership command is being dispatched.
-     */
-    readonly confirmRemoteSessionBinding?: boolean | 'send';
-    /**
-     * Command 44 keeps ingress sealed while the native route is prepared, then
-     * publishes the new route and releases this exact seal in one owner turn.
+     * Command 44 publishes the Actor route of the existing binding and releases
+     * this exact seal in one owner turn.
      */
     readonly releaseSeal?: {
         readonly sealId: string;
@@ -68,7 +61,7 @@ export interface ZLinkRemoteBoundSessionPort extends ZLinkStreamActorLifecyclePo
     sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
 }
 export interface ZLinkNativeFallbackBoundSessionPort {
-    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, timeoutMs: number, signal?: AbortSignal): Promise<void>;
     disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
     sendLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>): Promise<boolean>;
     submitLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;

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

@@ -66,7 +66,7 @@ class ZLinkStreamSessionRuntime {
             this.traceFrameWritten(kind, packetName, correlationId);
         });
         const sessionOrPromise = options.sessionFactory(this.context);
-        this.sessionReady = isPromiseLike(sessionOrPromise)
+        this.sessionReady = (0, abort_1.isPromiseLike)(sessionOrPromise)
             ? sessionOrPromise.then((session) => this.completeSessionCreation(session), (error) => {
                 this.context.completeConfiguration();
                 throw error;
@@ -1139,9 +1139,6 @@ function streamMonitorHasEndpoint(event) {
     const endpoint = event;
     return endpoint.localAddr !== undefined || endpoint.remoteAddr !== undefined;
 }
-function isPromiseLike(value) {
-    return typeof value.then === 'function';
-}
 function normalizeStreamCloseReason(reason) {
     switch (reason) {
         case 'client_close':

package/dist/runtime/workers/index.js

@@ -409,7 +409,7 @@ class DefaultZLinkWorkerCall {
     yield(signal) {
         const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
         const pending = this.begin(signal);
-        return turn.yieldPromise(pending);
+        return turn.yieldFrameworkPromise(pending);
     }
     begin(signal) {
         if (this.terminatorSelected) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zlink-systems/framework",
-  "version": "0.30.1",
+  "version": "0.30.2",
   "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.30.1",
-    "@zlink-systems/zlink": "1.19.0"
+    "@zlink-systems/stream-wire": "0.30.2",
+    "@zlink-systems/zlink": "1.20.0"
   }
 }

package/src/contracts/Common/ZLinkEncodedPayload.ts

@@ -1,18 +1,38 @@
-import { borrowEncodedPayload, storeEncodedPayload } from './encoded-payload-storage';
+import {
+  adoptEncodedPayload,
+  borrowEncodedPayload,
+  storeEncodedPayload
+} from './encoded-payload-storage';
 
 export class ZLinkEncodedPayload {
-  private constructor(bytes: Uint8Array) {
-    storeEncodedPayload(this, bytes);
+  private constructor(bytes: Uint8Array, owned: boolean) {
+    if (owned) {
+      adoptEncodedPayload(this, bytes);
+    } else {
+      storeEncodedPayload(this, bytes);
+    }
   }
 
+  /** Copies the supplied bytes. */
   static from(bytes: Uint8Array): ZLinkEncodedPayload {
-    return new ZLinkEncodedPayload(bytes);
+    return new ZLinkEncodedPayload(bytes, false);
+  }
+
+  /** Retains the supplied bytes without copying. Do not modify them afterward; mutation changes the payload. */
+  static fromOwned(bytes: Uint8Array): ZLinkEncodedPayload {
+    return new ZLinkEncodedPayload(bytes, true);
   }
 
+  /** Returns a copy of the stored bytes. */
   data(): Uint8Array {
     return new Uint8Array(this.stored());
   }
 
+  /** Returns the stored bytes without copying. Do not modify this view or its backing buffer. */
+  view(): Readonly<Uint8Array> {
+    return this.stored();
+  }
+
   toBytes(): Uint8Array {
     return this.data();
   }

package/src/contracts/Common/encoded-payload-storage.ts

@@ -6,9 +6,12 @@ export function storeEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
   return stored;
 }
 
-export function adoptEncodedPayload(owner: object, bytes: Buffer): Buffer {
-  encodedPayloadStorage.set(owner, bytes);
-  return bytes;
+export function adoptEncodedPayload(owner: object, bytes: Uint8Array): Buffer {
+  const stored = Buffer.isBuffer(bytes)
+    ? bytes
+    : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  encodedPayloadStorage.set(owner, stored);
+  return stored;
 }
 
 export function borrowEncodedPayload(owner: object): Buffer | undefined {

package/src/contracts/Configuration/Builders.ts

@@ -141,7 +141,10 @@ export interface ZLinkMeshObjectRoleBuilder {
 export interface ZLinkMeshObjectClientBuilder {}
 
 export interface ZLinkMeshObjectServerBuilder {
-  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(entrySpotType: Type<TEntrySpot>): this;
+  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(
+    entrySpotType: Type<TEntrySpot>,
+    actorType: string
+  ): this;
   addSpotFactory<TSpot extends ZLinkSpot>(
     spotType: string,
     implementation: Type<TSpot>,

package/src/contracts/Configuration/RegistrationBuilderPolicy.ts

@@ -68,13 +68,18 @@ export function validateSessionReplacementCallbackTimeout(timeoutMs: number): nu
 }
 
 export function registerEntrySpot(
-  options: { entrySpotType?: Type<ZLinkEntrySpot> },
-  entrySpotType: Type<ZLinkEntrySpot>
+  options: { entrySpotType?: Type<ZLinkEntrySpot>; entrySpotActorType?: string },
+  entrySpotType: Type<ZLinkEntrySpot>,
+  actorType: string
 ): void {
   if (options.entrySpotType !== undefined) {
     throw new ZLinkConfigurationException('Duplicate Entry Spot registration on SpotNode.');
   }
+  if (typeof actorType !== 'string' || actorType.length === 0) {
+    throw new ZLinkConfigurationException('Entry Spot Actor type must be a non-empty string.');
+  }
   options.entrySpotType = entrySpotType;
+  options.entrySpotActorType = actorType;
 }
 
 export function registerSpotFactory(

package/src/contracts/Configuration/RegistrationBuilders.ts

@@ -1234,8 +1234,11 @@ class DefaultMeshObjectServerBuilder implements ZLinkMeshObjectServerBuilder {
     private readonly node: MutableSpotNodeOptions
   ) {}
 
-  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(entrySpotType: Type<TEntrySpot>): this {
-    registerEntrySpot(this.node, entrySpotType);
+  addEntrySpot<TEntrySpot extends ZLinkEntrySpot>(
+    entrySpotType: Type<TEntrySpot>,
+    actorType: string
+  ): this {
+    registerEntrySpot(this.node, entrySpotType, actorType);
     return this;
   }
 
@@ -1646,6 +1649,7 @@ interface MutableSpotNodeOptions {
   router?: MutableSpotRouterCapabilityOptions;
   pubSub?: MutableSpotPubSubCapabilityOptions;
   entrySpotType?: Type<ZLinkEntrySpot>;
+  entrySpotActorType?: string;
   spotFactories?: Type<ZLinkSpot>[];
   spotFactoryRegistrations?: Record<
     string,

package/src/contracts/Configuration/RegistrationTypes.ts

@@ -268,6 +268,7 @@ export interface ZLinkSpotNodeOptions {
   readonly router?: ZLinkSpotRouterCapabilityOptions;
   readonly pubSub?: ZLinkSpotPubSubCapabilityOptions;
   readonly entrySpotType?: Type<ZLinkEntrySpot>;
+  readonly entrySpotActorType?: string;
   readonly spotFactories?: readonly Type<ZLinkSpot>[];
   readonly spotFactoryRegistrations?: Readonly<
     Record<

package/src/contracts/Dispatch/ZLinkDispatchOptions.ts

@@ -85,7 +85,7 @@ export interface ZLinkRuntimeMessageFlowEvent {
   readonly commandId?: number;
   readonly messageSize?: number;
   readonly durationSeconds?: number;
-  readonly errorReason?: ZLinkDispatchErrorReason;
+  readonly errorReason?: ZLinkDispatchErrorReason | 'activation_timeout' | 'activation_rejected';
   readonly errorAction?: ZLinkDispatchErrorAction;
   readonly errorType?: string;
   readonly errorMessage?: string;
@@ -195,6 +195,7 @@ export type ZLinkDispatchErrorReason =
   | 'unexpected_reply'
   | 'backpressure'
   | 'target_closed'
+  | 'location_unavailable'
   | 'stale_target'
   | 'shutdown';
 

package/src/contracts/Locations/Rows.ts

@@ -25,6 +25,8 @@ export interface ZLinkObjectCapability {
   readonly policy: ZLinkObjectMaintenancePolicyKind;
   readonly hasSnapshotAdapter: boolean;
   readonly limit: number;
+  /** True only for an Actor capability whose node registered an Entry Spot type accepting it. */
+  readonly entryAccepted: boolean;
 }
 
 export interface ZLinkPopulationCapacity {

package/src/contracts/Spots/Contracts.ts

@@ -16,12 +16,20 @@ export interface ZLinkActorHandlerRegistry {
 }
 
 export interface ZLinkSpotHandlerRegistry extends ZLinkActorHandlerRegistry {
+  /** Declares a timer handler constructor for relocation without registering an endpoint. */
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkSpot>>(
+    handlerType: Type<THandler>
+  ): this;
   addPacket<THandler>(handlerType: Type<THandler>): this;
   addSubscribe<THandler>(handlerType: Type<THandler>, channelName: string, topic: string): this;
 }
 
 export interface ZLinkInstanceSpotHandlerRegistry {
   addPacket<THandler>(handlerType: Type<THandler>): this;
+  /** Declares a timer handler constructor for relocation without registering an endpoint. */
+  addTimerHandler<THandler extends ZLinkSpotTimerHandler<ZLinkInstanceSpot>>(
+    handlerType: Type<THandler>
+  ): this;
 }
 
 export interface ZLinkWorkerCall<T> {

package/src/contracts/Spots/ZLinkSpot.ts

@@ -61,8 +61,8 @@ export interface ZLinkSpot<
 > extends ZLinkUserSpotActorLifecycle<TActor> {
   readonly context: ZLinkSpotContext<TActor>;
   configure?(): void;
-  onCreate?(request: ZLinkMessage): Promise<ZLinkSpotCreateResponse>;
-  onInitialize?(): Promise<void>;
+  onCreate?(request: ZLinkMessage, signal?: AbortSignal): Promise<ZLinkSpotCreateResponse>;
+  onInitialize?(signal?: AbortSignal): Promise<void>;
   onClosing?(context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal): Promise<void>;
   onRelocationReadyCompleted?(completion: ZLinkSpotRelocationReadyCompletion): Promise<void>;
 }
@@ -70,7 +70,7 @@ export interface ZLinkSpot<
 export interface ZLinkInstanceSpot {
   readonly context: ZLinkInstanceSpotContext;
   configure?(): void;
-  onInitialize?(): Promise<void>;
+  onInitialize?(signal?: AbortSignal): Promise<void>;
   onClosing?(context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal): Promise<void>;
 }
 

package/src/runtime/abort.ts

@@ -38,6 +38,18 @@ export function throwIfAborted(signal: AbortSignal | undefined): void {
   }
 }
 
+/**
+ * Whether a handler or dispatch result is a thenable the caller must wait
+ * for. Synchronous results, including null and undefined, are not.
+ */
+export function isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T> {
+  return (
+    value !== null &&
+    (typeof value === 'object' || typeof value === 'function') &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
 export function macrotaskBoundary(): Promise<void> {
   return new Promise((resolve) => setImmediate(resolve));
 }

package/src/runtime/actors/actor-authority-publication.ts

@@ -1,3 +1,4 @@
+import { routingIdsEqual } from '../routing-id';
 import { createHash } from 'node:crypto';
 import type { ActorRef } from '../../contracts';
 import { ZLinkSpotKind } from '../../contracts';
@@ -278,7 +279,7 @@ function requireActorAuthority(
     snapshot.allocation.objectKind !== 'actor' ||
     snapshot.allocation.stableType !== expected.actorType ||
     snapshot.allocation.descriptor.meshName !== expected.meshName ||
-    String(snapshot.allocation.descriptor.rid) !== String(expected.actor.nodeRid) ||
+    !routingIdsEqual(snapshot.allocation.descriptor.rid, expected.actor.nodeRid) ||
     snapshot.allocation.descriptorLifecycleGeneration !== expected.ownerNodeGeneration ||
     snapshot.ownerId !== expected.owner.ownerId ||
     snapshot.ownerLeaseGeneration !== expected.owner.leaseGeneration ||
@@ -286,7 +287,7 @@ function requireActorAuthority(
     actual.actorType !== expected.actorType ||
     actual.actor.actorId !== expected.actor.actorId ||
     actual.actor.objectGeneration !== expected.actor.objectGeneration ||
-    String(actual.actor.nodeRid) !== String(expected.actor.nodeRid)
+    !routingIdsEqual(actual.actor.nodeRid, expected.actor.nodeRid)
   ) {
     throw new Error(
       `Actor '${expected.actor.actorId}' authority fence does not match its ActorRef.`