@zlink-systems/framework 0.30.0 → 0.30.2

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

@@ -11,7 +11,7 @@ export interface ZLinkActorClientOptions {
     readonly defaultRequestTimeoutMs?: number;
     readonly staleActorRefReporter?: (meshName: string, actorId: string) => void;
     readonly staleActorRefPredicate?: (meshName: string, actor: ActorRef) => boolean;
-    readonly handoffCapture?: (meshName: string, actorId: string, parts: readonly Message[], returnResponse: boolean, actor: ActorRef, deadlineUnixMs?: number) => Promise<unknown> | undefined;
+    readonly handoffCapture?: (meshName: string, actorId: string, parts: readonly Message[], returnResponse: boolean, actor: ActorRef, deadlineUnixMs?: number, onAdmitted?: () => void) => Promise<unknown> | undefined;
     readonly sendErrorReporter?: (error: unknown) => void;
     readonly routeTransport?: ZLinkActorRoutedJoinTransport;
     readonly transportDeliveryGate?: () => {
@@ -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,8 +1,11 @@
 "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");
 const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const abort_1 = require("../abort");
@@ -32,7 +35,7 @@ class DefaultZLinkActorClient {
     }
     requestToActor(actorId, request) {
         requireActorId(actorId);
-        return new DefaultZLinkActorRequestCall((packetName, timeoutMs, metadata, signal) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'async'), (packetName, timeoutMs, metadata, signal) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'yield'), actorId, request, this.options.defaultRequestTimeoutMs);
+        return new DefaultZLinkActorRequestCall((packetName, timeoutMs, metadata, signal, onAdmitted) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'async', onAdmitted), (packetName, timeoutMs, metadata, signal) => this.request(actorId, packetName, request, timeoutMs, metadata, signal, 'yield'), actorId, request, this.options.defaultRequestTimeoutMs);
     }
     async send(actorId, explicitPacketName, message, metadata) {
         const route = await this.resolveActorRoute(actorId);
@@ -56,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(),
@@ -68,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)) {
@@ -82,7 +85,7 @@ class DefaultZLinkActorClient {
             closeMessages(parts);
         }
     }
-    async request(actorId, explicitPacketName, request, timeoutMs, metadata, signal, waitPolicy = 'async') {
+    async request(actorId, explicitPacketName, request, timeoutMs, metadata, signal, waitPolicy = 'async', onAdmitted) {
         (0, abort_1.throwIfAborted)(signal);
         const sourceSpotId = (0, actor_execution_context_1.currentZLinkActorExecution)()?.spotId ?? (0, execution_1.currentZLinkSpotSerialSourceId)();
         const effectiveTimeoutMs = timeoutMs ?? this.options.defaultRequestTimeoutMs;
@@ -109,18 +112,18 @@ class DefaultZLinkActorClient {
             const submissionCopies = delivery === undefined
                 ? 1
                 : ((await (0, actor_request_deadline_1.waitActorReply)(delivery, actorId, deadlineMs, signal)) ?? 1);
-            const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs);
+            const handoff = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted);
             if (handoff !== undefined) {
                 const submissions = [handoff];
                 for (let copy = 1; copy < submissionCopies; copy++) {
-                    const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs);
+                    const duplicate = this.options.handoffCapture?.(meshName, actor.actorId, parts, true, routedActor, deadlineUnixMs, onAdmitted);
                     if (duplicate !== undefined)
                         submissions.push(duplicate);
                 }
                 const replies = await (0, actor_request_deadline_1.waitActorReply)(Promise.all(submissions), actorId, deadlineMs, signal);
                 return replies[0];
             }
-            return await this.submitActorRequest(meshName, toBackendActorRef(actor), parts, (0, actor_request_deadline_1.remainingActorRequestTimeout)(actorId, deadlineMs), signal, route, messageFollow);
+            return await this.submitActorRequest(meshName, toBackendActorRef(actor), parts, (0, actor_request_deadline_1.remainingActorRequestTimeout)(actorId, deadlineMs), signal, route, messageFollow, onAdmitted);
         }
         catch (error) {
             if (isStaleActorError(error)) {
@@ -190,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) {
@@ -204,11 +208,10 @@ class DefaultZLinkActorClient {
             throw mapSubmitError(error, 'Actor send');
         }
     }
-    async submitActorRequest(meshName, actor, parts, timeoutMs, signal, route, messageFollowContext) {
+    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(),
@@ -228,7 +231,7 @@ class DefaultZLinkActorClient {
                 returnResponse: true,
                 messageFollowContext
             });
-            const reply = await (0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routeTransport, remoteActorRouteTarget(route), relay, { timeoutMs, signal }, `Remote Actor request is not available for '${actor.actorId}'.`, (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}'));
+            const reply = await (0, actor_routed_json_request_1.requestRoutedJsonReply)(this.options.routeTransport, remoteActorRouteTarget(route), relay, { timeoutMs, signal, onAdmitted }, `Remote Actor request is not available for '${actor.actorId}'.`, (replyParts) => JSON.parse(replyParts[0]?.getString('utf8') ?? '{}'));
             if (reply.ok !== true) {
                 throw (0, framework_errors_internal_1.createInternalFrameworkException)(remoteRelayErrorKind(reply.errorKind), typeof reply.error === 'string'
                     ? reply.error
@@ -242,7 +245,9 @@ class DefaultZLinkActorClient {
         }
         const completion = await completions.submit(() => node.requestToActor(actor, toMessageLikeParts(parts), {
             flags: runtime_values_1.ZLINK_BACKEND_SEND_NONE,
-            timeoutMs
+            routeFence: nativeActorRouteFence(route, actor),
+            timeoutMs,
+            onAdmitted
         }), signal);
         if (completion.terminalResult !== runtime_values_1.RequestResult.Ok) {
             (0, backend_1.closeMeshCompletion)(completion);
@@ -259,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;
@@ -302,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,
@@ -405,21 +397,21 @@ class DefaultZLinkActorRequestCall {
         return this;
     }
     submit(signal) {
-        return this.execute('async', signal);
+        this.rejectSelfActorRequest();
+        return (0, request_result_1.createZLinkRequest)((onAdmitted) => this.execute('async', signal, onAdmitted));
     }
     yield(signal) {
         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) {
+    execute(waitPolicy, signal, onAdmitted) {
         ensureSingleSubmit(this.executed);
-        this.rejectSelfActorRequest();
         this.executed = true;
         (0, abort_1.throwIfAborted)(signal);
         const submitter = waitPolicy === 'async' ? this.asyncSubmitter : this.yieldSubmitter;
-        return submitter(this.packet ?? (0, packet_name_1.resolveFrameworkPacketName)(this.request, undefined, 'Actor'), this.timeoutMs ?? this.defaultRequestTimeoutMs, this.selectedMetadata, signal);
+        return submitter(this.packet ?? (0, packet_name_1.resolveFrameworkPacketName)(this.request, undefined, 'Actor'), this.timeoutMs ?? this.defaultRequestTimeoutMs, this.selectedMetadata, signal, onAdmitted);
     }
     rejectSelfActorRequest() {
         const current = (0, actor_execution_context_1.currentZLinkActorExecution)();
@@ -440,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);
@@ -461,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;
@@ -142,9 +147,8 @@ export declare class ZLinkActorHandoffCoordinator {
      */
     failPending(actorId: string, reason: unknown): void;
     cancel(actorId: string): void;
-    capture(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, deadlineUnixMs?: number, messageFollowOrigin?: ZLinkMessageFollowOrigin, provisionalReplay?: ZLinkActorHandoffDispatch): Promise<unknown> | undefined;
+    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;