@zlink-systems/framework 0.30.1 → 0.30.2

package/dist/contracts/Common/ZLinkEncodedPayload.d.ts

@@ -1,7 +1,13 @@
 export declare class ZLinkEncodedPayload {
     private constructor();
+    /** Copies the supplied bytes. */
     static from(bytes: Uint8Array): ZLinkEncodedPayload;
+    /** Retains the supplied bytes without copying. Do not modify them afterward; mutation changes the payload. */
+    static fromOwned(bytes: Uint8Array): ZLinkEncodedPayload;
+    /** Returns a copy of the stored bytes. */
     data(): Uint8Array;
+    /** Returns the stored bytes without copying. Do not modify this view or its backing buffer. */
+    view(): Readonly<Uint8Array>;
     toBytes(): Uint8Array;
     copy(): ZLinkEncodedPayload;
     size(): number;

package/dist/contracts/Common/ZLinkEncodedPayload.js

@@ -3,15 +3,30 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkEncodedPayload = void 0;
 const encoded_payload_storage_1 = require("./encoded-payload-storage");
 class ZLinkEncodedPayload {
-    constructor(bytes) {
-        (0, encoded_payload_storage_1.storeEncodedPayload)(this, bytes);
+    constructor(bytes, owned) {
+        if (owned) {
+            (0, encoded_payload_storage_1.adoptEncodedPayload)(this, bytes);
+        }
+        else {
+            (0, encoded_payload_storage_1.storeEncodedPayload)(this, bytes);
+        }
     }
+    /** Copies the supplied bytes. */
     static from(bytes) {
-        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) {
+        return new ZLinkEncodedPayload(bytes, true);
+    }
+    /** Returns a copy of the stored bytes. */
     data() {
         return new Uint8Array(this.stored());
     }
+    /** Returns the stored bytes without copying. Do not modify this view or its backing buffer. */
+    view() {
+        return this.stored();
+    }
     toBytes() {
         return this.data();
     }

package/dist/contracts/Common/encoded-payload-storage.d.ts

@@ -1,3 +1,3 @@
 export declare function storeEncodedPayload(owner: object, bytes: Uint8Array): Buffer;
-export declare function adoptEncodedPayload(owner: object, bytes: Buffer): Buffer;
+export declare function adoptEncodedPayload(owner: object, bytes: Uint8Array): Buffer;
 export declare function borrowEncodedPayload(owner: object): Buffer | undefined;

package/dist/contracts/Common/encoded-payload-storage.js

@@ -10,8 +10,11 @@ function storeEncodedPayload(owner, bytes) {
     return stored;
 }
 function adoptEncodedPayload(owner, bytes) {
-    encodedPayloadStorage.set(owner, bytes);
-    return bytes;
+    const stored = Buffer.isBuffer(bytes)
+        ? bytes
+        : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    encodedPayloadStorage.set(owner, stored);
+    return stored;
 }
 function borrowEncodedPayload(owner) {
     return encodedPayloadStorage.get(owner);

package/dist/contracts/Configuration/Builders.d.ts

@@ -112,7 +112,7 @@ 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>, configure: (builder: ZLinkUserSpotFactoryBuilder<TSpot>) => void): this;
     addInstanceSpotFactory<TSpot extends ZLinkInstanceSpot>(instanceSpotType: string, implementation: Type<TSpot>, configure: (builder: ZLinkInstanceSpotFactoryBuilder<TSpot>) => void): this;
     addActorFactory<TActor extends ZLinkActor>(actorType: string, implementation: Type<ZLinkActorFactory<TActor>>, configure: (builder: ZLinkActorFactoryBuilder<TActor>) => void): this;

package/dist/contracts/Configuration/RegistrationBuilderPolicy.d.ts

@@ -16,7 +16,8 @@ export declare function validateActorTransferTimeout(timeoutMs: number): number;
 export declare function validateSessionReplacementCallbackTimeout(timeoutMs: number): number;
 export declare function registerEntrySpot(options: {
     entrySpotType?: Type<ZLinkEntrySpot>;
-}, entrySpotType: Type<ZLinkEntrySpot>): void;
+    entrySpotActorType?: string;
+}, entrySpotType: Type<ZLinkEntrySpot>, actorType: string): void;
 export declare function registerSpotFactory(options: {
     spotFactories?: Type<ZLinkSpot>[];
 }, spotType: Type<ZLinkSpot>): void;

package/dist/contracts/Configuration/RegistrationBuilderPolicy.js

@@ -62,11 +62,15 @@ function validateSessionReplacementCallbackTimeout(timeoutMs) {
     }
     return timeoutMs;
 }
-function registerEntrySpot(options, entrySpotType) {
+function registerEntrySpot(options, entrySpotType, actorType) {
     if (options.entrySpotType !== undefined) {
         throw new ConfigurationException_1.ZLinkConfigurationException('Duplicate Entry Spot registration on SpotNode.');
     }
+    if (typeof actorType !== 'string' || actorType.length === 0) {
+        throw new ConfigurationException_1.ZLinkConfigurationException('Entry Spot Actor type must be a non-empty string.');
+    }
     options.entrySpotType = entrySpotType;
+    options.entrySpotActorType = actorType;
 }
 function registerSpotFactory(options, spotType) {
     options.spotFactories ??= [];

package/dist/contracts/Configuration/RegistrationBuilders.js

@@ -942,8 +942,8 @@ class DefaultMeshObjectServerBuilder {
         this.meshName = meshName;
         this.node = node;
     }
-    addEntrySpot(entrySpotType) {
-        (0, RegistrationBuilderPolicy_1.registerEntrySpot)(this.node, entrySpotType);
+    addEntrySpot(entrySpotType, actorType) {
+        (0, RegistrationBuilderPolicy_1.registerEntrySpot)(this.node, entrySpotType, actorType);
         return this;
     }
     addSpotFactory(spotType, implementation, configure) {

package/dist/contracts/Configuration/RegistrationTypes.d.ts

@@ -233,6 +233,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<string, ZLinkObjectFactoryRegistration<ZLinkSpot, ZLinkSpot, ZLinkUserSpotFactoryConfiguration>>>;
     readonly instanceSpotFactories?: Readonly<Record<string, Type<ZLinkInstanceSpot>>>;

package/dist/contracts/Dispatch/ZLinkDispatchOptions.d.ts

@@ -76,7 +76,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;
@@ -162,7 +162,7 @@ export declare enum ZLinkDispatchMessageKind {
     ActorRequest = "actorRequest",
     ActorSend = "actorSend"
 }
-export type ZLinkDispatchErrorReason = 'no_handler' | 'decode_error' | 'handler_exception' | 'invalid_frame' | 'reply_path_missing' | 'unexpected_reply' | 'backpressure' | 'target_closed' | 'stale_target' | 'shutdown';
+export type ZLinkDispatchErrorReason = 'no_handler' | 'decode_error' | 'handler_exception' | 'invalid_frame' | 'reply_path_missing' | 'unexpected_reply' | 'backpressure' | 'target_closed' | 'location_unavailable' | 'stale_target' | 'shutdown';
 export type ZLinkDispatchErrorAction = 'reply_error' | 'fail_caller' | 'drop';
 export declare enum ZLinkRuntimeDispatchErrorReason {
     HandlerMissing = "no_handler",

package/dist/contracts/Locations/Rows.d.ts

@@ -22,6 +22,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 {
     readonly active: number;

package/dist/contracts/Spots/Contracts.d.ts

@@ -9,11 +9,15 @@ export interface ZLinkActorHandlerRegistry {
     addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this;
 }
 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> {
     timeoutMs(durationMs: number): ZLinkWorkerCall<T>;

package/dist/contracts/Spots/ZLinkSpot.d.ts

@@ -42,15 +42,15 @@ export interface ZLinkUserSpotActorLifecycle<TActor extends ZLinkActor = ZLinkAc
 export interface ZLinkSpot<TActor extends ZLinkActor = ZLinkActor> 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>;
 }
 export interface ZLinkInstanceSpot {
     readonly context: ZLinkInstanceSpotContext;
     configure?(): void;
-    onInitialize?(): Promise<void>;
+    onInitialize?(signal?: AbortSignal): Promise<void>;
     onClosing?(context: ZLinkSpotClosingContext, cleanupSignal: AbortSignal): Promise<void>;
 }
 export interface ZLinkEntrySpot<TActor extends ZLinkActor = ZLinkActor> extends ZLinkSpotActorMembershipLifecycle<TActor> {

package/dist/runtime/abort.d.ts

@@ -10,5 +10,10 @@ export declare function isAbortError(error: unknown): boolean;
 export declare function createDeadlineExceededError(message?: string): ZLinkDeadlineExceededError;
 export declare function isDeadlineExceededError(error: unknown): boolean;
 export declare 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 declare function isPromiseLike<T>(value: T | PromiseLike<T>): value is PromiseLike<T>;
 export declare function macrotaskBoundary(): Promise<void>;
 export declare function awaitWithAbort<T>(operation: Promise<T>, signal: AbortSignal | undefined, abortOperation?: () => void): Promise<T>;

package/dist/runtime/abort.js

@@ -6,6 +6,7 @@ exports.isAbortError = isAbortError;
 exports.createDeadlineExceededError = createDeadlineExceededError;
 exports.isDeadlineExceededError = isDeadlineExceededError;
 exports.throwIfAborted = throwIfAborted;
+exports.isPromiseLike = isPromiseLike;
 exports.macrotaskBoundary = macrotaskBoundary;
 exports.awaitWithAbort = awaitWithAbort;
 /** The typed cancellation error produced by Framework admission helpers. */
@@ -41,6 +42,15 @@ function throwIfAborted(signal) {
         throw createAbortError();
     }
 }
+/**
+ * Whether a handler or dispatch result is a thenable the caller must wait
+ * for. Synchronous results, including null and undefined, are not.
+ */
+function isPromiseLike(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
 function macrotaskBoundary() {
     return new Promise((resolve) => setImmediate(resolve));
 }

package/dist/runtime/actors/actor-authority-publication.js

@@ -7,6 +7,7 @@ exports.decodeRelocatingActorAuthorityIdentity = decodeRelocatingActorAuthorityI
 exports.rewriteActorAuthorityRoute = rewriteActorAuthorityRoute;
 exports.rewriteActorAuthorityOwner = rewriteActorAuthorityOwner;
 exports.isActorAuthorityPayload = isActorAuthorityPayload;
+const routing_id_1 = require("../routing-id");
 const node_crypto_1 = require("node:crypto");
 const creation_operation_id_1 = require("../locations/creation-operation-id");
 const actor_authority_payload_codec_1 = require("./actor-authority-payload-codec");
@@ -197,7 +198,7 @@ function requireActorAuthority(snapshot, expected) {
         snapshot.allocation.objectKind !== 'actor' ||
         snapshot.allocation.stableType !== expected.actorType ||
         snapshot.allocation.descriptor.meshName !== expected.meshName ||
-        String(snapshot.allocation.descriptor.rid) !== String(expected.actor.nodeRid) ||
+        !(0, routing_id_1.routingIdsEqual)(snapshot.allocation.descriptor.rid, expected.actor.nodeRid) ||
         snapshot.allocation.descriptorLifecycleGeneration !== expected.ownerNodeGeneration ||
         snapshot.ownerId !== expected.owner.ownerId ||
         snapshot.ownerLeaseGeneration !== expected.owner.leaseGeneration ||
@@ -205,7 +206,7 @@ function requireActorAuthority(snapshot, expected) {
         actual.actorType !== expected.actorType ||
         actual.actor.actorId !== expected.actor.actorId ||
         actual.actor.objectGeneration !== expected.actor.objectGeneration ||
-        String(actual.actor.nodeRid) !== String(expected.actor.nodeRid)) {
+        !(0, routing_id_1.routingIdsEqual)(actual.actor.nodeRid, expected.actor.nodeRid)) {
         throw new Error(`Actor '${expected.actor.actorId}' authority fence does not match its ActorRef.`);
     }
 }

package/dist/runtime/actors/actor-client.d.ts

@@ -33,4 +33,3 @@ export declare class DefaultZLinkActorClient implements ZLinkActorClient {
     private submitActorRequest;
     private requireNode;
 }
-export declare function forwardEncodedActorPacket(node: ZLinkBackendMeshNode, completions: ZLinkMeshCompletionTable, actor: ActorRef, header: Buffer, payload: Buffer, returnResponse: boolean, timeoutMs: number | undefined, serializers?: ReadonlyMap<string, ZLinkMessageSerializer>): Promise<unknown>;

package/dist/runtime/actors/actor-client.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkActorClient = void 0;
-exports.forwardEncodedActorPacket = forwardEncodedActorPacket;
+const node_buffer_1 = require("node:buffer");
+const channel_envelope_1 = require("../channels/channel-envelope");
+const routing_id_1 = require("../routing-id");
 const stream_wire_1 = require("@zlink-systems/stream-wire");
 const request_result_1 = require("../messaging/request-result");
 const contracts_1 = require("../../contracts");
@@ -57,7 +59,7 @@ class DefaultZLinkActorClient {
             }
             const node = this.requireNode(meshName);
             if (this.options.routeTransport !== undefined &&
-                String(node.status().routingId) !== String(actor.nodeRid)) {
+                !(0, routing_id_1.routingIdsEqual)(node.status().routingId, actor.nodeRid)) {
                 await this.options.routeTransport.sendToSpot(remoteActorRouteTarget(route), (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
                     actorId,
                     header: parts[0].data(),
@@ -69,7 +71,7 @@ class DefaultZLinkActorClient {
                 }), { packetName: actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET });
                 return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
             }
-            return await this.submitActorSend(meshName, toBackendActorRef(actor), parts);
+            return await this.submitActorSend(meshName, toBackendActorRef(actor), parts, route);
         }
         catch (error) {
             if (isStaleActorError(error)) {
@@ -191,11 +193,12 @@ class DefaultZLinkActorClient {
             throw error;
         }
     }
-    async submitActorSend(meshName, actor, parts) {
+    async submitActorSend(meshName, actor, parts, route) {
         const node = this.requireNode(meshName);
         try {
             return (0, submission_result_1.classifySubmitResult)(await node.sendToActor(actor, toMessageLikeParts(parts), {
-                flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE
+                flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
+                routeFence: nativeActorRouteFence(route, actor)
             }), 'Actor send');
         }
         catch (error) {
@@ -208,8 +211,7 @@ class DefaultZLinkActorClient {
     async submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext, onAdmitted) {
         const node = this.requireNode(meshName);
         if (this.options.routeTransport !== undefined &&
-            String(node.status().routingId) !== String(actor.nodeRid) &&
-            route !== undefined) {
+            !(0, routing_id_1.routingIdsEqual)(node.status().routingId, actor.nodeRid)) {
             const relay = (0, actor_packet_relay_wire_1.encodeRemoteActorPacketRelayPayload)({
                 actorId: actor.actorId,
                 header: parts[0].data(),
@@ -243,6 +245,7 @@ class DefaultZLinkActorClient {
         }
         const completion = await completions.submit(() => node.requestToActor(actor, toMessageLikeParts(parts), {
             flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
+            routeFence: nativeActorRouteFence(route, actor),
             timeoutMs,
             onAdmitted
         }), signal);
@@ -261,6 +264,14 @@ class DefaultZLinkActorClient {
     }
 }
 exports.DefaultZLinkActorClient = DefaultZLinkActorClient;
+function nativeActorRouteFence(route, actor) {
+    return {
+        actor,
+        targetNodeGeneration: route.ownerNodeGeneration,
+        authorityOwnerGeneration: route.authorityOwnerGeneration,
+        ownerLeaseGeneration: route.ownerLeaseGeneration
+    };
+}
 function remoteActorRouteTarget(route) {
     if (route.enclosingSpotRoute !== undefined) {
         return route.enclosingSpotRoute;
@@ -304,27 +315,6 @@ function requireActorId(actorId) {
         throw new configuration_1.ZLinkConfigurationException(`Actor ID must contain 1..${CoreTypes_1.ZLINK_MAX_ACTOR_ID_BYTES} UTF-8 bytes.`);
     }
 }
-async function forwardEncodedActorPacket(node, completions, actor, header, payload, returnResponse, timeoutMs, serializers) {
-    const target = toBackendActorRef(actor);
-    const parts = [header, payload];
-    const packetName = (0, protocol_1.decodeStreamHeader)(header).name;
-    if (!returnResponse) {
-        if ((await node.sendToActor(target, parts, { flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE })) !==
-            runtime_values_1.SubmitResult.Ok) {
-            throw routeNotConnected('Actor handoff send submit was not accepted.');
-        }
-        return undefined;
-    }
-    const completion = await completions.submit(() => node.requestToActor(target, parts, {
-        flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
-        timeoutMs
-    }));
-    if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
-        (0, backend_1.closeMeshCompletion)(completion);
-        throw mapRequestResult(completion.terminalResult, completion.failureErrno, 'Actor handoff request');
-    }
-    return decodeActorReply(completion.parts, serializers, packetName);
-}
 function toBackendActorRef(actor) {
     return {
         nodeRid: actor.nodeRid,
@@ -414,7 +404,7 @@ class DefaultZLinkActorRequestCall {
         this.rejectSelfActorRequest();
         const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
         const pending = this.execute('yield', signal);
-        return turn.yieldPromise(pending);
+        return turn.yieldFrameworkPromise(pending);
     }
     execute(waitPolicy, signal, onAdmitted) {
         ensureSingleSubmit(this.executed);
@@ -442,18 +432,14 @@ function decodeActorReply(reply, serializers, packetName) {
                 const header = (0, protocol_1.decodeStreamHeader)(frame.header);
                 const payload = runtime_message_1.ZLinkBufferMessage.from(frame.payload);
                 try {
-                    return decodeActorReplyPayload(header.kind, payload, serializers, packetName);
+                    return decodeActorReplyPayload(header.kind, header.codec, payload, serializers, packetName);
                 }
                 finally {
                     payload.close();
                 }
             }
         }
-        if (reply.length >= 2) {
-            const header = (0, protocol_1.decodeStreamHeader)(reply[0].data());
-            return decodeActorReplyPayload(header.kind, reply[1], serializers, packetName);
-        }
-        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Actor request reply is empty.');
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Actor request reply must contain one valid STREAM frame.');
     }
     finally {
         closeMessages(reply);
@@ -463,17 +449,24 @@ function closeMessages(parts) {
     for (const part of parts)
         part.close();
 }
-function decodeActorReplyPayload(kind, payload, serializers, packetName) {
+function decodeActorReplyPayload(kind, codec, payload, serializers, packetName) {
     if (kind === protocol_1.ZLinkStreamMessageKind.Error) {
-        const error = (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers);
-        const wireKind = error.kind;
-        const publicKind = typeof wireKind === 'number' &&
-            Number.isInteger(wireKind) &&
-            wireKind >= contracts_1.ZLinkFrameworkErrorKind.NotFound &&
-            wireKind <= contracts_1.ZLinkFrameworkErrorKind.InternalFailure
-            ? wireKind
-            : contracts_1.ZLinkFrameworkErrorKind.InternalFailure;
-        throw new contracts_1.ZLinkFrameworkException(publicKind, error.message ?? 'Actor request failed.');
+        if (codec !== protocol_1.ZLinkStreamCodec.Json || !(0, node_buffer_1.isUtf8)(payload.data())) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Actor Error reply requires UTF-8 JSON.');
+        }
+        const error = (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload);
+        if (typeof error !== 'object' ||
+            error === null ||
+            typeof error.code !== 'string' ||
+            typeof error.message !== 'string') {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Actor Error reply requires code and message strings.');
+        }
+        const wire = error;
+        const kind = (0, channel_envelope_1.channelErrorKindFromCode)(wire.code);
+        if (kind === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, `Actor Error reply uses an unknown error code '${wire.code}'.`);
+        }
+        throw new contracts_1.ZLinkFrameworkException(kind, wire.message);
     }
     return (0, payload_codec_1.decodeFrameworkPayloadMessage)(payload, serializers, undefined, stream_wire_1.ZlinkStreamContentType.Json, packetName, 'reply');
 }

package/dist/runtime/actors/actor-context.d.ts

@@ -13,6 +13,8 @@ export declare class DefaultZLinkActorContext implements ZLinkActorContext {
     constructor(state: ZLinkActorRuntimeState, joinCoordinator: ZLinkActorJoinCoordinator | undefined, boundSessionFactory: ZLinkActorBoundSessionFactory | undefined, messageSerializers: ReadonlyMap<string, ZLinkMessageSerializer> | undefined, meshNameProvider: ZLinkActorManagerOptions['actorMeshNameProvider']);
     get meshName(): string;
     get actorId(): string;
+    /** Actor-turn view of the single current Session binding (§7). */
+    get currentSessionBinding(): import("./actor-runtime-state").ZLinkRemoteBoundSessionTarget | undefined;
     get objectGeneration(): bigint;
     get spotId(): SpotId | undefined;
     [ZLINK_ACTOR_LIFECYCLE_SNAPSHOT](): ZLinkActorLifecycleSnapshotSource;

package/dist/runtime/actors/actor-context.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkActorContext = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = void 0;
+const routing_id_1 = require("../routing-id");
 const contracts_1 = require("../../contracts");
 const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const runtime_message_1 = require("../backend/runtime-message");
@@ -53,6 +54,10 @@ class DefaultZLinkActorContext {
     get actorId() {
         return this.state.actorId;
     }
+    /** Actor-turn view of the single current Session binding (§7). */
+    get currentSessionBinding() {
+        return this.state.boundSession;
+    }
     get objectGeneration() {
         return this.state.nativeActorRef?.generation ?? 1n;
     }
@@ -200,10 +205,25 @@ class DefaultZLinkActorJoinSpotCall {
                         deadline.close();
                         requestMessage.close();
                     }
+                    if (result.sourceCleanup !== undefined) {
+                        // Infrastructure cleanup has its own terminal, outside the public Failed conversion.
+                        try {
+                            const cleanup = result.sourceCleanup();
+                            await (this.turn === undefined ? cleanup : this.turn.yieldFrameworkPromise(cleanup));
+                        }
+                        catch (error) {
+                            traceJoinError(this.actor, error, this.coordinator, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
+                            throw error;
+                        }
+                        finally {
+                            this.state.endDeferredJoin();
+                        }
+                        return;
+                    }
                     if (!result.accepted ||
                         sourceNodeRid === undefined ||
                         result.actor === undefined ||
-                        String(sourceNodeRid) === String(result.actor.nodeRid)) {
+                        (0, routing_id_1.routingIdsEqual)(sourceNodeRid, result.actor.nodeRid)) {
                         await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
                     }
                     else {
@@ -322,10 +342,25 @@ class DefaultZLinkActorJoinEntrySpotCall {
                         deadline.close();
                         requestMessage.close();
                     }
+                    if (result.sourceCleanup !== undefined) {
+                        // Infrastructure cleanup has its own terminal, outside the public Failed conversion.
+                        try {
+                            const cleanup = result.sourceCleanup();
+                            await (this.turn === undefined ? cleanup : this.turn.yieldFrameworkPromise(cleanup));
+                        }
+                        catch (error) {
+                            traceJoinError(this.actor, error, this.coordinator, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop);
+                            throw error;
+                        }
+                        finally {
+                            this.state.endDeferredJoin();
+                        }
+                        return;
+                    }
                     if (!result.accepted ||
                         sourceNodeRid === undefined ||
                         result.actor === undefined ||
-                        String(sourceNodeRid) === String(result.actor.nodeRid)) {
+                        (0, routing_id_1.routingIdsEqual)(sourceNodeRid, result.actor.nodeRid)) {
                         await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
                     }
                     else {
@@ -430,10 +465,17 @@ async function notifyJoinCompletion(actor, operationId, result, _messageSerializ
     await actor.onJoinCompleted?.(completion);
 }
 async function notifyJoinFailure(actor, operationId, error, coordinator) {
-    console.error(`actor join failure actor=${actor.context.actorId}`, error);
     const frameworkError = error instanceof contracts_1.ZLinkFrameworkException
         ? error
         : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Deferred actor join failed.', false, error);
+    traceJoinError(actor, error, coordinator, ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError);
+    await actor.onJoinCompleted?.({
+        status: 'failed',
+        operationId,
+        kind: frameworkError.kind
+    });
+}
+function traceJoinError(actor, error, coordinator, errorAction) {
     //  The completion carries only an error kind, so trace the cause on the
     //  message flow under the same flow id as the Join that produced it.
     const tracePoint = coordinator?.messageFlow?.()?.begin(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error);
@@ -445,13 +487,8 @@ async function notifyJoinFailure(actor, operationId, error, coordinator) {
         packetName: 'JoinSpot',
         actorId: actor.context.actorId,
         errorReason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
-        errorAction: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError,
+        errorAction,
         errorType: errorDetails?.errorType,
         errorMessage: errorDetails?.errorMessage
     });
-    await actor.onJoinCompleted?.({
-        status: 'failed',
-        operationId,
-        kind: frameworkError.kind
-    });
 }

package/dist/runtime/actors/actor-handoff.d.ts

@@ -8,6 +8,7 @@ import { type ZLinkActorMessageFollowContext, type ZLinkActorMessageFollowOwnerF
 import type { ZLinkActorRoutedJoinTransport } from './actor-routed-join-transport';
 import type { ZLinkRemoteBoundSessionTarget } from './actor-runtime-state';
 export declare const DEFAULT_MESSAGE_FOLLOW_DURATION_MS: number;
+export declare const RELOCATED_REQUEST_OWNED_BY_REQUESTER: unique symbol;
 export interface ZLinkActorHandoffPacket {
     readonly index: number;
     readonly header: string;
@@ -36,6 +37,7 @@ export interface ZLinkActorHandoffRequestSource {
     readonly ownerId: string;
     readonly ownerLeaseGeneration: string;
     readonly nodeRid: string;
+    readonly nodeRidHex?: string;
     readonly nodeGeneration: string;
     readonly replyRouteId: string;
 }
@@ -63,6 +65,7 @@ export interface ZLinkActorHandoffPrefixAdmission {
     readonly terminal: Promise<void>;
 }
 export interface ZLinkActorHandoffPrefixRecord {
+    readonly onWithdrawable?: (withdraw: () => boolean) => void;
     readonly drain: (dispatch: ZLinkActorHandoffDispatch) => Promise<void>;
     readonly preparation?: {
         prepare(signal: AbortSignal): Promise<void>;
@@ -118,13 +121,15 @@ export declare class ZLinkActorHandoffCoordinator {
     begin(actorId: string, oldGeneration: bigint): void;
     beginProvisional(actorId: string, oldGeneration: bigint): void;
     private startHandoff;
+    /** True while a hold owns this Actor's ingress, before its release to the Actor FIFO. */
     isActive(actorId: string): boolean;
     isProvisional(actorId: string): boolean;
-    promoteProvisional(actorId: string): void;
     sealConnectionBoundIngress(actorId: string): void;
     activeSourceOwner(actorId: string): ZLinkActorMessageFollowOwnerFence | undefined;
     releaseDeferred(actorId: string, dispatch?: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
     releaseCanceled(actorId: string, dispatch: ZLinkActorHandoffDispatch, admission?: ZLinkActorHandoffReplayAdmission): Promise<void>;
+    /** Installs a restored target's payload in the same owner used by local handoffs. */
+    admitTransferredPrefix(actorId: string, objectGeneration: bigint, packets: readonly ZLinkActorHandoffPacket[], queue: ZLinkActorHandoffPrefixQueue, preparation: ZLinkActorHandoffReplayPreparation | undefined, start: Promise<void>, onResult: (packet: ZLinkActorHandoffPacket, result: ZLinkActorHandoffResult) => void): ZLinkActorHandoffPrefixAdmission;
     private admitHandoffPrefix;
     private admitPendingPrefix;
     private createPrefixRecord;
@@ -144,7 +149,6 @@ export declare class ZLinkActorHandoffCoordinator {
     cancel(actorId: string): void;
     capture(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch, onAdmitted?: () => void): Promise<unknown> | undefined;
     snapshot(actorId: string): readonly ZLinkActorHandoffPacket[];
-    snapshotCoreBacklog(actorId: string): readonly ZLinkActorHandoffPacket[];
     /**
      * Freezes the post-capture ingress segment immediately before the caller
      * appends the one-way cutover on the same relocation lane. Records returned
@@ -152,7 +156,7 @@ export declare class ZLinkActorHandoffCoordinator {
      * from the later Message Follow tail.
      */
     takeRelocationRelay(actorId: string): readonly ZLinkActorHandoffPacket[];
-    complete(actorId: string, target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, results: readonly ZLinkActorHandoffResult[], targetOwnerFence: ZLinkActorMessageFollowOwnerFence): void;
+    complete(actorId: string, target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, results: readonly ZLinkActorHandoffResult[], targetOwnerFence: ZLinkActorMessageFollowOwnerFence | null): void;
     messageFollowCount(actorId?: string): number;
     pendingCount(actorId: string): number;
     isKnownStale(actor: ActorRef): boolean;