@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/actors/actor-local-native-join.d.ts

@@ -1,26 +1,31 @@
-import type { RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkMessageSerializer } from '../../contracts';
-import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
+import { type RoutingId, type ZLinkActor, type ZLinkActorJoinOperationId, type ZLinkMessageSerializer, type ZLinkSpot, type ZLinkSpotActorJoinResult } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend/contracts';
 import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import type { ZLinkLocationLifecycle } from '../locations';
 import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
+import type { ZLinkActorJoinRuntimeResult } from './actor-runtime-contracts';
 import { ZLinkActorRuntimeState } from './actor-runtime-state';
 import type { ZLinkPostCommitActorBinder } from './post-commit-actor-binder';
-import type { ZLinkPostCommitActorLocation } from './post-commit-actor-location';
-import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
 export interface ZLinkLocalNativeActorJoinOptions {
-    readonly postCommitLocation?: ZLinkPostCommitActorLocation;
+    readonly locationLifecycle?: ZLinkLocationLifecycle;
+    readonly localSpotJoin?: (spotId: RoutingId, actor: ZLinkActor, request: Message, commit: (spot: ZLinkSpot) => Promise<void>, signal?: AbortSignal, leaveSource?: () => Promise<void>, contentType?: string) => Promise<ZLinkSpotActorJoinResult>;
+    readonly localEntryJoin?: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+    readonly localSourceLeave?: (actor: ZLinkActor, spotId: RoutingId | undefined, signal?: AbortSignal) => Promise<void>;
+    readonly reportSourceLeaveError: (error: unknown) => void;
     readonly postCommitBinder?: ZLinkPostCommitActorBinder;
     readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
     readonly actorJoinRelocation?: ZLinkActorJoinRelocation;
     readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
 }
-/** Owns core-native actor joins and their local runtime state transition. */
+/** Selects local membership commits or remote Actor relocation. */
 export declare class ZLinkLocalNativeActorJoin {
     private readonly options;
     constructor(options: ZLinkLocalNativeActorJoinOptions);
     joinSpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, spotId: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(node: ZLinkBackendMeshNode, actor: ZLinkActor, state: ZLinkActorRuntimeState, actorRef: ZLinkBackendActorRef, nodeRid: RoutingId, spotRouteTarget: ZLinkSpotRouteTarget | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
+    private joinLocal;
     private waitForJoinCompletion;
     private relocateRemoteActorJoin;
     private requireCompletions;

package/dist/runtime/actors/actor-local-native-join.js

@@ -1,19 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkLocalNativeActorJoin = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const node_crypto_1 = require("node:crypto");
-const runtime_values_1 = require("../backend/runtime-values");
 const contracts_1 = require("../../contracts");
-const mesh_completion_table_1 = require("../backend/mesh-completion-table");
 const abort_1 = require("../abort");
-const actor_runtime_state_1 = require("./actor-runtime-state");
-const routing_id_1 = require("../routing-id");
-const routing_id_2 = require("../routing-id");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const runtime_values_1 = require("../backend/runtime-values");
 const operation_identity_1 = require("../foundation/operation-identity");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const payload_codec_1 = require("../messaging/payload-codec");
+const routing_id_1 = require("../routing-id");
+const actor_remote_wire_1 = require("./actor-remote-wire");
+const actor_runtime_state_1 = require("./actor-runtime-state");
+const LOCAL_JOIN_RESOLUTION_TIMEOUT_MS = 5_000;
+const LOCAL_JOIN_POLL_INTERVAL_MS = 10;
 const ZLINK_FRAMEWORK_ACTOR_JOIN_PACKET_NAME = 'ZLinkFrameworkActorJoinRequest';
-/** Owns core-native actor joins and their local runtime state transition. */
+/** Selects local membership commits or remote Actor relocation. */
 class ZLinkLocalNativeActorJoin {
     options;
     constructor(options) {
@@ -22,119 +25,93 @@ class ZLinkLocalNativeActorJoin {
     async joinSpot(node, actor, state, actorRef, spotId, spotRouteTarget, request, timeoutMs, signal, completionOperationId) {
         if (signal?.aborted === true)
             throw (0, abort_1.createAbortError)();
-        const completions = this.requireCompletions();
         const target = requireUserSpotRoute(spotRouteTarget, spotId);
-        const actorMeshName = runtimeActorMeshName(actor, state, target.routerChannelId);
-        const remote = !(0, routing_id_2.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(node.status().routingId), target.targetNodeRid);
+        const remote = !(0, routing_id_1.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(node.status().routingId), target.targetNodeRid);
         if (remote) {
             return await this.relocateRemoteActorJoin(node, actor, state, actorRef, target, request, timeoutMs, signal, completionOperationId, false);
         }
-        const completion = await this.waitForJoinCompletion(() => node.joinActorSpot(actorRef, (0, routing_id_1.toBackendRoutingId)(target.targetNodeRid), (0, routing_id_1.toBackendRoutingId)(target.spotId), target.targetSpotGeneration, actorJoinApplicationPayload(request), timeoutMs), completions, timeoutMs, signal);
-        const control = completion.kindData;
-        if (control?.kind !== 'actorJoinCompletion' || control.actor === null) {
-            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
-            const message = `Actor join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`;
-            //  Classify the (terminal, fine) pair instead of collapsing every non-OK
-            //  or malformed join completion to NotFound (spec 32-framework-error-model:
-            //  83-118). An OK terminal that carries no join control is a protocol
-            //  violation, not a missing route.
-            throw completion.terminalResult !== 0 || completion.failureErrno !== 0
-                ? (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, message)
-                : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, message);
-        }
-        if (control.joinResult !== 0) {
-            try {
-                return {
-                    accepted: false,
-                    actor: (0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName),
-                    reply: completion.parts[0]
-                };
-            }
-            finally {
-                disposeParts(completion.parts.slice(1));
-            }
-        }
-        if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
-            throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `Actor join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`);
-        }
-        state.setNativeActorRef(control.actor);
-        state.setJoinedSpot((0, actor_runtime_state_1.toFrameworkRoutingId)(control.location.spotId ?? target.spotId), undefined, control.location.membershipEpoch, control.location.spotGeneration);
-        // The Session owner relays from the verified Ready authority snapshot;
-        // membership coordinates alone cannot recreate a User/Instance fence.
-        state.setRemoteActorPacketTarget(target.spotKind === contracts_1.ZLinkSpotKind.Entry ? undefined : target);
-        if (state.actorType !== undefined) {
-            this.options.postCommitLocation?.joinedEventually(state.actorType, actor.context.actorId, spotRouteTarget?.routerChannelId ?? '', (0, actor_runtime_state_1.toFrameworkRoutingId)(control.location.spotId ?? target.spotId), control.location.spotGeneration, control.location.membershipEpoch, node.status().lifecycleGeneration);
-        }
-        await this.options.postCommitBinder?.bind((0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName));
-        try {
-            return {
-                accepted: true,
-                actor: (0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName),
-                reply: completion.parts[0]
-            };
-        }
-        finally {
-            disposeParts(completion.parts.slice(1));
-        }
+        return await this.joinLocal(node, actor, state, actorRef, target, target.spotId, request, signal);
     }
     async joinEntrySpot(node, actor, state, actorRef, nodeRid, spotRouteTarget, request, timeoutMs, signal, completionOperationId) {
         if (signal?.aborted === true)
             throw (0, abort_1.createAbortError)();
-        const completions = this.requireCompletions();
-        const actorMeshName = runtimeActorMeshName(actor, state, '');
         const targetNodeRid = spotRouteTarget?.targetNodeRid ?? nodeRid;
         const remote = spotRouteTarget !== undefined &&
-            (!(0, routing_id_2.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(node.status().routingId), spotRouteTarget.targetNodeRid) ||
-                !(0, routing_id_2.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(actorRef.nodeRid), spotRouteTarget.targetNodeRid));
+            (!(0, routing_id_1.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(node.status().routingId), spotRouteTarget.targetNodeRid) ||
+                !(0, routing_id_1.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(actorRef.nodeRid), spotRouteTarget.targetNodeRid));
         if (remote) {
             return await this.relocateRemoteActorJoin(node, actor, state, actorRef, spotRouteTarget, request, timeoutMs, signal, completionOperationId, true);
         }
-        const completion = await this.waitForJoinCompletion(() => node.joinActorEntrySpot(actorRef, (0, routing_id_1.toBackendRoutingId)(targetNodeRid), actorJoinApplicationPayload(request), timeoutMs), completions, timeoutMs, signal);
-        const control = completion.kindData;
-        if (control?.kind !== 'actorJoinCompletion' || control.actor === null) {
-            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
-            const message = `Actor entry SPOT join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`;
-            //  Classify the (terminal, fine) pair instead of collapsing to NotFound
-            //  (spec 32-framework-error-model:83-118); an OK terminal with no join
-            //  control is a protocol violation.
-            throw completion.terminalResult !== 0 || completion.failureErrno !== 0
-                ? (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, message)
-                : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, message);
+        const target = {
+            routerChannelId: spotRouteTarget?.routerChannelId ?? runtimeActorMeshName(actor, state, ''),
+            targetNodeRid,
+            spotId: (0, actor_runtime_state_1.toFrameworkRoutingId)(node.entrySpot().routingId),
+            spotKind: contracts_1.ZLinkSpotKind.Entry,
+            targetSpotGeneration: node.entrySpot().status().lifecycleGeneration
+        };
+        return await this.joinLocal(node, actor, state, actorRef, target, spotRouteTarget?.spotId ?? target.spotId, request, signal);
+    }
+    async joinLocal(node, actor, state, actorRef, target, storeSpotId, request, signal) {
+        const location = node.actorLookup(actor.context.actorId);
+        const meshName = runtimeActorMeshName(actor, state, target.routerChannelId);
+        if ((0, routing_id_1.routingIdsEqual)((0, actor_runtime_state_1.toFrameworkRoutingId)(location.spotId), target.spotId)) {
+            return { accepted: true, actor: (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, meshName) };
         }
-        if (control.joinResult !== 0) {
+        if (state.actorType === undefined)
+            throw new Error('Local Actor Join requires a registered Actor type.');
+        const actorType = state.actorType;
+        const previousSpotId = state.spotId;
+        const spotGeneration = target.targetSpotGeneration;
+        if (spotGeneration === undefined ||
+            spotGeneration <= 0n ||
+            node.restoreActorAuthority === undefined) {
+            throw new Error('Local Actor Join requires a valid target generation and stateful membership runtime.');
+        }
+        const membershipEpoch = location.membershipEpoch + 1n;
+        const commit = async (spot) => {
+            (0, abort_1.throwIfAborted)(signal);
+            if (target.spotKind === contracts_1.ZLinkSpotKind.Entry) {
+                await this.options.locationLifecycle?.notifyActorLeftSpot(actorType, actor.context.actorId, storeSpotId, spotGeneration, membershipEpoch, node.status().lifecycleGeneration);
+            }
+            else {
+                await this.options.locationLifecycle?.notifyActorJoinedSpot(actorType, actor.context.actorId, meshName, storeSpotId, spotGeneration, membershipEpoch, node.status().lifecycleGeneration);
+            }
+            const committedActor = node.restoreActorAuthority(actor.context.actorId, actorType, actorRef.generation, state.locationGeneration ?? actorRef.generation, target.spotKind === contracts_1.ZLinkSpotKind.Entry ? undefined : String(target.spotId), spotGeneration, membershipEpoch);
+            state.setNativeActorRef(committedActor);
+            if (target.spotKind === contracts_1.ZLinkSpotKind.Entry)
+                state.clearJoinedSpot();
+            else
+                state.setJoinedSpot(target.spotId, spot, membershipEpoch, spotGeneration);
+            state.setRemoteActorPacketTarget(target.spotKind === contracts_1.ZLinkSpotKind.Entry ? undefined : target);
+        };
+        const leaveSource = async () => {
+            void this.options.localSourceLeave?.(actor, previousSpotId, signal).catch((error) => {
+                this.options.reportSourceLeaveError(error);
+            });
+        };
+        let response;
+        if (target.spotKind === contracts_1.ZLinkSpotKind.Entry) {
+            if (this.options.localEntryJoin === undefined)
+                throw new Error('Local Entry Actor Join runtime is not configured.');
+            await commit();
             try {
-                return {
-                    accepted: false,
-                    actor: (0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName),
-                    reply: completion.parts[0]
-                };
+                await this.options.localEntryJoin(actor, signal);
             }
             finally {
-                disposeParts(completion.parts.slice(1));
+                await leaveSource();
             }
+            response = { accepted: true };
         }
-        if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
-            (0, mesh_completion_table_1.closeMeshCompletion)(completion);
-            throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `Actor entry SPOT join failed for '${actor.context.actorId}' with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`);
-        }
-        state.setNativeActorRef(control.actor);
-        state.clearJoinedSpot();
-        state.setRemoteActorPacketTarget(undefined);
-        if (state.actorType !== undefined) {
-            this.options.postCommitLocation?.leftEventually(state.actorType, actor.context.actorId, (0, actor_runtime_state_1.toFrameworkRoutingId)(control.location.spotId ?? spotRouteTarget?.spotId ?? nodeRid), control.location.spotGeneration, control.location.membershipEpoch, node.status().lifecycleGeneration);
-        }
-        await this.options.postCommitBinder?.bind((0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName));
-        try {
-            return {
-                accepted: true,
-                actor: (0, actor_runtime_state_1.toFrameworkActorRef)(control.actor, actorMeshName),
-                reply: completion.parts[0]
-            };
-        }
-        finally {
-            disposeParts(completion.parts.slice(1));
+        else {
+            if (this.options.localSpotJoin === undefined)
+                throw new Error('Local Spot Actor Join runtime is not configured.');
+            response = await this.options.localSpotJoin(target.spotId, actor, request, commit, signal, leaveSource, (0, payload_codec_1.frameworkPayloadContentType)(request));
         }
+        return {
+            accepted: response.accepted,
+            actor: (0, actor_runtime_state_1.toFrameworkActorRef)(state.nativeActorRef ?? actorRef, meshName),
+            reply: response.reply
+        };
     }
     async waitForJoinCompletion(submit, completions, timeoutMs, signal) {
         // The operation ID identifies one Core request. Once it is submitted, a
@@ -193,7 +170,7 @@ class ZLinkLocalNativeActorJoin {
             //  (spec 32-framework-error-model:83-118); an OK terminal with no join
             //  control is a protocol violation.
             throw admission.terminalResult !== 0 || admission.failureErrno !== 0
-                ? remoteActorJoinFailureException(node, target, admission.terminalResult, admission.failureErrno, message)
+                ? (0, framework_errors_internal_1.wireReplyFailureException)(admission.terminalResult, admission.failureErrno, message)
                 : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, message);
         }
         if (control.joinResult !== 0) {
@@ -210,7 +187,7 @@ class ZLinkLocalNativeActorJoin {
         }
         if (admission.terminalResult !== 0 || admission.failureErrno !== 0) {
             (0, mesh_completion_table_1.closeMeshCompletion)(admission);
-            throw remoteActorJoinFailureException(node, target, admission.terminalResult, admission.failureErrno, `Actor admission failed for '${actor.context.actorId}' with result '${admission.terminalResult}' and errno '${admission.failureErrno}'.`);
+            throw (0, framework_errors_internal_1.wireReplyFailureException)(admission.terminalResult, admission.failureErrno, `Actor admission failed for '${actor.context.actorId}' with result '${admission.terminalResult}' and errno '${admission.failureErrno}'.`);
         }
         disposeParts(admission.parts.slice(1));
         if (control.canonicalHandoffId !== undefined) {
@@ -253,7 +230,7 @@ class ZLinkLocalNativeActorJoin {
                             ...(completionOperationId === undefined
                                 ? {}
                                 : {
-                                    replyContentType: control.replyContentType ?? 'application/octet-stream'
+                                    replyContentType: control.replyContentType ?? stream_wire_1.ZlinkStreamContentType.Raw
                                 }),
                             reply: completionOperationId === undefined
                                 ? Buffer.alloc(0)
@@ -328,7 +305,7 @@ function legacyRemoteActorJoinPayload(actor, state, actorRef, target, request, t
     // canonical admission; it never substitutes target-Spot values as an Actor
     // authority fence.
     const payload = Buffer.from(JSON.stringify({
-        packetName: '__zlink.actor.join_spot.request',
+        packetName: actor_remote_wire_1.ZLINK_REMOTE_ACTOR_JOIN_PACKET,
         phase: 'admission',
         transferId,
         spotId: String(target.spotId),
@@ -343,7 +320,7 @@ function legacyRemoteActorJoinPayload(actor, state, actorRef, target, request, t
     }));
     return {
         packetName: ZLINK_FRAMEWORK_ACTOR_JOIN_PACKET_NAME,
-        contentType: 'application/json',
+        contentType: stream_wire_1.ZlinkStreamContentType.Json,
         payload,
         // Older in-process MeshNode adapters consume the fallback as a Message.
         // Keep that structural view without changing the typed service payload.
@@ -359,29 +336,14 @@ function canonicalHandoffRelocationId(handoffId) {
     return (`${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}` +
         `-${hex.slice(16, 20)}-${hex.slice(20)}`);
 }
-function remoteActorJoinFailureException(node, target, terminalResult, failureErrno, message) {
-    const failure = (0, framework_errors_internal_1.wireReplyFailureException)(terminalResult, failureErrno, message);
-    const targetGeneration = target.targetNodeGeneration;
-    if (failure.kind === contracts_1.ZLinkFrameworkErrorKind.DeadlineExceeded &&
-        targetGeneration !== undefined &&
-        targetGeneration !== 0n &&
-        !node
-            .peers()
-            .some((peer) => peer.state === 3 &&
-            peer.routingId !== null &&
-            (0, routing_id_2.routingIdsEqual)(peer.routingId, target.targetNodeRid) &&
-            peer.lifecycleGeneration === targetGeneration)) {
-        return (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, 'wire Actor join target RouteMesh peer became unavailable');
-    }
-    return failure;
-}
 function runtimeActorMeshName(actor, state, fallback) {
     const context = actor.context;
     const stateMeshName = state?.meshName;
     return context?.meshName ?? stateMeshName ?? fallback;
 }
 async function submitJoinWhenConnected(submit, timeoutMs, signal) {
-    const deadline = performance.now() + Math.min(timeoutMs ?? 5_000, 5_000);
+    const deadline = performance.now() +
+        Math.min(timeoutMs ?? LOCAL_JOIN_RESOLUTION_TIMEOUT_MS, LOCAL_JOIN_RESOLUTION_TIMEOUT_MS);
     for (;;) {
         (0, abort_1.throwIfAborted)(signal);
         try {
@@ -391,7 +353,7 @@ async function submitJoinWhenConnected(submit, timeoutMs, signal) {
             if (!(0, runtime_values_1.isBackendNotConnectedError)(error) || performance.now() >= deadline) {
                 throw error;
             }
-            await new Promise((resolve) => setTimeout(resolve, 10));
+            await new Promise((resolve) => setTimeout(resolve, LOCAL_JOIN_POLL_INTERVAL_MS));
         }
     }
 }

package/dist/runtime/actors/actor-native-lookup.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.lookupNativeActorRef = lookupNativeActorRef;
+const zlink_1 = require("@zlink-systems/zlink");
 function lookupNativeActorRef(node, actorId) {
     try {
         const location = node.actorLookup(actorId);
@@ -15,16 +16,9 @@ function lookupNativeActorRef(node, actorId) {
         };
     }
     catch (error) {
-        if (nativeErrno(error) === 2) {
+        if (error instanceof zlink_1.ConfigError && error.result === zlink_1.ConfigResult.NotFound) {
             return undefined;
         }
         throw error;
     }
 }
-function nativeErrno(error) {
-    if (typeof error !== 'object' || error === null || !('nativeErrno' in error)) {
-        return undefined;
-    }
-    const value = error.nativeErrno;
-    return typeof value === 'number' ? value : undefined;
-}

package/dist/runtime/actors/actor-packet-relay-wire.d.ts

@@ -1,7 +1,6 @@
-import type { ActorRef, RoutingId } from '../../contracts';
-import { ZLinkSpotKind } from '../../contracts';
-import type { ZLinkRemoteActorPacketTarget } from './actor-runtime-state';
+import { type ActorRef, type RoutingId, ZLinkSpotKind } from '../../contracts';
 import { type ZLinkActorMessageFollowContext } from './actor-message-follow-context';
+import type { ZLinkRemoteActorPacketTarget } from './actor-runtime-state';
 export declare const ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = "__zlink.actor.packet.relay";
 export declare const ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = "zlink.framework.actor.session_disconnected";
 export declare const ZLINK_REMOTE_ACTOR_SESSION_BIND_PACKET = "framework.internal.actor-session-bind";
@@ -21,6 +20,7 @@ export declare function encodeRemoteActorPacketRelayPayload(input: {
     readonly header: Uint8Array;
     readonly payload: Uint8Array;
     readonly bindingActorRef?: ActorRef;
+    readonly bindingGeneration?: bigint;
     /** The actor reference used to preserve relocation context at the target Spot. */
     readonly actorRef?: ActorRef;
     readonly returnResponse?: boolean;

package/dist/runtime/actors/actor-packet-relay-wire.js

@@ -9,6 +9,7 @@ exports.encodeRemoteActorPacketTarget = encodeRemoteActorPacketTarget;
 exports.decodeRemoteActorPacketTarget = decodeRemoteActorPacketTarget;
 exports.decodeRemoteActorPacketRelayPayload = decodeRemoteActorPacketRelayPayload;
 const contracts_1 = require("../../contracts");
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const routing_id_1 = require("../routing-id");
 const actor_message_follow_context_1 = require("./actor-message-follow-context");
 exports.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = '__zlink.actor.packet.relay';
@@ -47,7 +48,8 @@ function encodeRemoteActorPacketRelayPayload(input) {
             ? undefined
             : (0, routing_id_1.routingIdWireHex)(input.bindingActorRef.nodeRid),
         bindingActorGeneration: input.bindingActorRef?.objectGeneration.toString(),
-        bindingGeneration: input.bindingActorRef?.bindingGeneration?.toString(),
+        bindingGeneration: input.bindingGeneration?.toString() ??
+            input.bindingActorRef?.bindingGeneration?.toString(),
         returnResponse: input.returnResponse,
         messageFollowContext: input.messageFollowContext,
         header: Buffer.from(input.header).toString('base64'),
@@ -100,8 +102,8 @@ function decodeRemoteActorPacketTarget(value) {
 }
 function requireSpotId(value) {
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 255) {
-        throw new Error('Actor packet target SpotId must contain 1..255 UTF-8 bytes.');
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES) {
+        throw new Error(`Actor packet target SpotId must contain 1..${CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
     }
     return value;
 }

package/dist/runtime/actors/actor-remote-joiner.d.ts

@@ -7,7 +7,7 @@ import type { ZLinkActorJoinCoordinator, ZLinkActorJoinRuntimeResult } from './a
 import type { ZLinkActorSourceTransfer } from './actor-source-transfer';
 import { ZLinkActorRuntimeState } from './actor-runtime-state';
 import type { ZLinkActorJoinRelocation } from './actor-join-relocation';
-export interface ZLinkActorNativeJoinCoordinatorOptions {
+export interface ZLinkActorNativeJoinCoordinatorOptions extends Pick<import('./actor-local-native-join').ZLinkLocalNativeActorJoinOptions, 'localSpotJoin' | 'localEntryJoin' | 'localSourceLeave' | 'reportSourceLeaveError'> {
     readonly messageFlow?: () => import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
     readonly node: ZLinkBackendMeshNode | (() => ZLinkBackendMeshNode);
     readonly completionTableProvider: () => ZLinkMeshCompletionTable | undefined;
@@ -28,8 +28,8 @@ export declare class ZLinkActorNativeJoinCoordinator implements ZLinkActorJoinCo
     private readonly localJoin;
     messageFlow(): import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
     constructor(options: ZLinkActorNativeJoinCoordinatorOptions);
-    beginDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): void;
-    abortDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): Promise<void>;
+    beginDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
+    abortDeferredJoin(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
     joinSpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, spotId: RoutingId, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, nodeRid: RoutingId | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     private withDeferredJoinFinalizer;

package/dist/runtime/actors/actor-remote-joiner.js

@@ -4,10 +4,8 @@ exports.ZLinkActorNativeJoinCoordinator = void 0;
 const abort_1 = require("../abort");
 const actor_runtime_state_1 = require("./actor-runtime-state");
 const actor_native_lookup_1 = require("./actor-native-lookup");
-const post_commit_actor_location_1 = require("./post-commit-actor-location");
 const actor_local_native_join_1 = require("./actor-local-native-join");
 const post_commit_actor_binder_1 = require("./post-commit-actor-binder");
-const operation_identity_1 = require("../foundation/operation-identity");
 /** Selects local native join or remote two-phase transfer for each destination. */
 class ZLinkActorNativeJoinCoordinator {
     options;
@@ -17,15 +15,12 @@ class ZLinkActorNativeJoinCoordinator {
     }
     constructor(options) {
         this.options = options;
-        const postCommitLocation = options.locationLifecycle === undefined
-            ? undefined
-            : new post_commit_actor_location_1.ZLinkPostCommitActorLocation({
-                lifecycle: options.locationLifecycle,
-                reportError: options.postCommitErrorReporter,
-                signal: options.shutdownSignal
-            });
         this.localJoin = new actor_local_native_join_1.ZLinkLocalNativeActorJoin({
-            postCommitLocation,
+            locationLifecycle: options.locationLifecycle,
+            localSpotJoin: options.localSpotJoin,
+            localEntryJoin: options.localEntryJoin,
+            localSourceLeave: options.localSourceLeave,
+            reportSourceLeaveError: options.reportSourceLeaveError,
             postCommitBinder: options.remoteActorBinder === undefined
                 ? undefined
                 : new post_commit_actor_binder_1.ZLinkPostCommitActorBinder({
@@ -38,11 +33,11 @@ class ZLinkActorNativeJoinCoordinator {
             messageSerializers: options.messageSerializers
         });
     }
-    beginDeferredJoin(actor, state, operationId) {
-        this.options.sourceTransfer?.beginDeferredActorHandoff?.(actor, state, (0, operation_identity_1.operationIdentityKey)(operationId));
+    beginDeferredJoin(actor, state) {
+        this.options.sourceTransfer?.beginDeferredActorHandoff?.(actor, state);
     }
-    async abortDeferredJoin(actor, state, operationId) {
-        await this.options.sourceTransfer?.cancelDeferredActorHandoff?.(actor, state, (0, operation_identity_1.operationIdentityKey)(operationId));
+    async abortDeferredJoin(actor, state) {
+        await this.options.sourceTransfer?.cancelDeferredActorHandoff?.(actor, state);
     }
     async joinSpot(actor, state, spotId, request, timeoutMs, signal, completionOperationId) {
         (0, abort_1.throwIfAborted)(signal);
@@ -85,15 +80,14 @@ class ZLinkActorNativeJoinCoordinator {
     withDeferredJoinFinalizer(actor, state, target, result, operationId) {
         if (operationId === undefined || this.options.sourceTransfer === undefined)
             return result;
-        const key = (0, operation_identity_1.operationIdentityKey)(operationId);
         return {
             ...result,
             finalizeDeferredJoin: async () => {
                 if (result.accepted && result.actor !== undefined && target !== undefined) {
-                    await this.options.sourceTransfer.completeDeferredActorHandoff?.(actor, target, result.actor, key);
+                    await this.options.sourceTransfer.completeDeferredActorHandoff?.(actor, target, result.actor);
                 }
                 else {
-                    await this.options.sourceTransfer.cancelDeferredActorHandoff?.(actor, state, key);
+                    await this.options.sourceTransfer.cancelDeferredActorHandoff?.(actor, state);
                 }
             }
         };

package/dist/runtime/actors/actor-remote-wire.js

@@ -4,6 +4,8 @@ exports.REMOTE_ACTOR_JOIN_ABORT = exports.REMOTE_ACTOR_JOIN_COMMIT = exports.REM
 exports.decodeRemoteActorSourceLeaveTerminal = decodeRemoteActorSourceLeaveTerminal;
 exports.decodeRemoteActorJoinPayload = decodeRemoteActorJoinPayload;
 exports.decodeWireRoutingId = decodeWireRoutingId;
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const routing_id_1 = require("../routing-id");
 exports.ZLINK_REMOTE_ACTOR_JOIN_PACKET = '__zlink.actor.join_spot.request';
 exports.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL = '__zlink.actor.source_leave.terminal';
@@ -56,7 +58,7 @@ function decodeRemoteActorJoinPayload(payload) {
         boundSessionTargetNodeRid: optionalRoutingId(payload, 'boundSessionTargetNodeRid', 'boundSessionTargetNodeRidHex'),
         boundSessionSpotId: optionalSpotId(payload, 'boundSessionSpotId'),
         request: payload.request,
-        requestContentType: optionalString(payload, 'requestContentType') ?? 'application/json'
+        requestContentType: optionalString(payload, 'requestContentType') ?? stream_wire_1.ZlinkStreamContentType.Json
     };
 }
 function decodeWireRoutingId(text, hex) {
@@ -76,8 +78,8 @@ function optionalSpotId(value, key) {
 }
 function requireSpotId(value) {
     const bytes = Buffer.byteLength(value, 'utf8');
-    if (bytes < 1 || bytes > 255) {
-        throw new Error('Remote actor SpotId must contain 1..255 UTF-8 bytes.');
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES) {
+        throw new Error(`Remote actor SpotId must contain 1..${CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
     }
     return value;
 }

package/dist/runtime/actors/actor-request-deadline.d.ts

@@ -0,0 +1,3 @@
+export declare function remainingActorRequestTimeout(actorId: string, deadlineMs: number | undefined): number | undefined;
+/** Only actual Store, delivery-gate, and handoff waits acquire a deadline handle. */
+export declare function waitActorReply<T>(reply: Promise<T>, actorId: string, deadlineMs: number | undefined, signal?: AbortSignal): Promise<T>;

package/dist/runtime/actors/actor-request-deadline.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remainingActorRequestTimeout = remainingActorRequestTimeout;
+exports.waitActorReply = waitActorReply;
+const abort_1 = require("../abort");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+function remainingActorRequestTimeout(actorId, deadlineMs) {
+    if (deadlineMs === undefined)
+        return undefined;
+    const remaining = deadlineMs - performance.now();
+    if (remaining <= 0) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' exceeded its deadline.`);
+    }
+    return Math.max(1, Math.ceil(remaining));
+}
+/** Only actual Store, delivery-gate, and handoff waits acquire a deadline handle. */
+async function waitActorReply(reply, actorId, deadlineMs, signal) {
+    if (deadlineMs === undefined)
+        return await (0, abort_1.awaitWithAbort)(reply, signal);
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        const remaining = remainingActorRequestTimeout(actorId, deadlineMs);
+        timer = setTimeout(() => reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor request '${actorId}' exceeded its deadline.`)), remaining);
+    });
+    try {
+        return await (0, abort_1.awaitWithAbort)(Promise.race([reply, timeout]), signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/runtime/actors/actor-retry-delay.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkActorRetryDelay = void 0;
 const INITIAL_RETRY_DELAY_MS = 25;
 const MAX_RETRY_DELAY_MS = 1_000;
+const RETRY_BACKOFF_MULTIPLIER = 2;
 class ZLinkActorRetryDelay {
     delayMs = INITIAL_RETRY_DELAY_MS;
     reset() {
@@ -11,7 +12,7 @@ class ZLinkActorRetryDelay {
     async wait(signal) {
         const completed = await delayUnlessAborted(this.delayMs, signal);
         if (completed) {
-            this.delayMs = Math.min(this.delayMs * 2, MAX_RETRY_DELAY_MS);
+            this.delayMs = Math.min(this.delayMs * RETRY_BACKOFF_MULTIPLIER, MAX_RETRY_DELAY_MS);
         }
         return completed;
     }

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

@@ -6,6 +6,7 @@ import type { ZLinkLocationLifecycle } from '../locations';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
 import type { ZLinkActorTransferRegistry } from './actor-transfer-registry';
 import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkActivationAdmission } from '../activation-admission';
 export interface ZLinkActorJoinRuntimeResult<TReply> {
     readonly accepted: boolean;
     readonly actor?: import('../../contracts').ActorRef;
@@ -34,6 +35,7 @@ export interface ZLinkActorManagerOptions {
     readonly shutdownSignal?: AbortSignal;
     readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
     readonly admission?: ZLinkRuntimeAdmissionGate;
+    readonly activationAdmission?: ZLinkActivationAdmission;
     readonly placementCreate?: (actorId: string, actorType: string, createOnly: boolean, options: {
         readonly meshName?: string;
         readonly request?: unknown;
@@ -56,8 +58,8 @@ export interface ZLinkActorJoinCoordinator {
      * lookup. This is an internal ordering fence; it is not part of the public
      * actor context contract.
      */
-    beginDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): void;
-    abortDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: import('../../contracts').ZLinkActorJoinOperationId): Promise<void>;
+    beginDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
+    abortDeferredJoin?(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
     joinSpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, spotId: RoutingId, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
     joinEntrySpot(actor: ZLinkActor, state: ZLinkActorRuntimeState, nodeRid: RoutingId | undefined, request: Message, timeoutMs: number | undefined, signal: AbortSignal | undefined, completionOperationId?: import('../../contracts').ZLinkActorJoinOperationId): Promise<ZLinkActorJoinRuntimeResult<Message>>;
 }