@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/spots/spot-actor-join-dispatch.js

@@ -4,21 +4,17 @@ exports.ZLinkSpotActorJoinDispatch = void 0;
 const contracts_1 = require("../backend/contracts");
 const spot_actor_lifecycle_drain_1 = require("./spot-actor-lifecycle-drain");
 const spot_actor_packet_drain_1 = require("./spot-actor-packet-drain");
-const spot_native_flags_1 = require("./spot-native-flags");
-const spot_native_actor_join_admission_1 = require("./spot-native-actor-join-admission");
 const spot_routed_frame_dispatch_1 = require("./spot-routed-frame-dispatch");
 const spot_subscription_dispatch_1 = require("./spot-subscription-dispatch");
+const ACTOR_JOIN_POLL_INTERVAL_MS = 5;
 const ZLINK_SPOT_DISPATCH_SUBJECT_SPOT = 1;
 const ZLINK_SPOT_DISPATCH_SUBJECT_CHANNEL_DEALER = 3;
 class ZLinkSpotActorJoinDispatch {
     options;
-    draining = false;
-    redrainRequested = false;
     nativeSpotId;
     subscriptions;
     actorLifecycleDrain;
     actorPacketDrain;
-    nativeActorJoinAdmission;
     routedFrames;
     nativeSpot;
     constructor(options) {
@@ -43,19 +39,7 @@ class ZLinkSpotActorJoinDispatch {
             waitIdle: waitSpotDispatchIdle,
             flowEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
         });
-        this.nativeActorJoinAdmission = new spot_native_actor_join_admission_1.ZLinkSpotNativeActorJoinAdmission({
-            nativeSpot: options.nativeSpot,
-            serial: options.serial,
-            resolveActor: actors.resolveActor,
-            getTarget: actors.getTarget,
-            defaultAccept: actors.defaultAccept,
-            commitAcceptedActor: actors.commitNativeActor,
-            messageSerializers: options.messageSerializers,
-            dispatchErrors: options.dispatchErrors
-        });
         this.routedFrames = new spot_routed_frame_dispatch_1.ZLinkSpotRoutedFrameDispatch({
-            nativeSpot: options.nativeSpot,
-            createReceived: options.createReceived,
             nativeSpotId: this.nativeSpotId,
             serial: options.serial,
             resolveActor: actors.resolveActor,
@@ -66,11 +50,11 @@ class ZLinkSpotActorJoinDispatch {
             actorPacketHandler: options.packets?.handle,
             bindRemoteSession: options.packets?.bindRemoteSession === undefined
                 ? undefined
-                : (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => options.packets.bindRemoteSession({
+                : (actor, sourceNodeRid, sourceSessionRid) => options.packets.bindRemoteSession({
                     actorId: actor.actorId,
                     generation: actor.objectGeneration,
                     nodeRid: actor.nodeRid
-                }, sourceNodeRid, sourceSessionRid, declaredTarget),
+                }, sourceNodeRid, sourceSessionRid),
             routedBoundSessionReceiver: options.boundSessionRuntime?.receiveRoutedBoundSession.bind(options.boundSessionRuntime),
             routedBoundSessionResponseReceiver: options.boundSessionRuntime?.receiveRoutedBoundSessionResponse.bind(options.boundSessionRuntime),
             routedBoundSessionErrorReceiver: options.boundSessionRuntime?.receiveRoutedBoundSessionError.bind(options.boundSessionRuntime),
@@ -78,8 +62,7 @@ class ZLinkSpotActorJoinDispatch {
             messageSerializers: options.messageSerializers,
             providerResolver: options.providerResolver,
             dispatchErrors: options.dispatchErrors,
-            claimApplicationWork: options.claimApplicationWork,
-            waitIdle: waitSpotDispatchIdle
+            claimApplicationWork: options.claimApplicationWork
         });
         this.subscriptions = new spot_subscription_dispatch_1.ZLinkSpotSubscriptionDispatch({
             nativeSpot: options.nativeSpot,
@@ -107,10 +90,6 @@ class ZLinkSpotActorJoinDispatch {
             return;
         }
         this.nativeSpot.setDispatchHandler((info) => {
-            if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.ActorJoinReadable) {
-                this.runDetached('spot actor join drain', () => this.drain());
-                return;
-            }
             if (info.event === contracts_1.ZLinkBackendSpotDispatchEvent.SubscribeReadable) {
                 this.runDetached('spot subscription drain', () => this.subscriptions.drain());
                 return;
@@ -149,37 +128,8 @@ class ZLinkSpotActorJoinDispatch {
         }
         void callback().catch(() => undefined);
     }
-    async drain() {
-        if (this.draining) {
-            this.redrainRequested = true;
-            return;
-        }
-        this.draining = true;
-        try {
-            do {
-                this.redrainRequested = false;
-                await this.drainAvailableActorJoins();
-            } while (this.redrainWasRequested());
-        }
-        finally {
-            this.draining = false;
-        }
-    }
-    redrainWasRequested() {
-        return this.redrainRequested;
-    }
-    async drainAvailableActorJoins() {
-        for (;;) {
-            const request = this.nativeSpot.recvActorJoin(spot_native_flags_1.ZLINK_RECV_DONT_WAIT);
-            if (request === null) {
-                await waitSpotDispatchIdle();
-                return;
-            }
-            await this.nativeActorJoinAdmission.admit(request);
-        }
-    }
 }
 exports.ZLinkSpotActorJoinDispatch = ZLinkSpotActorJoinDispatch;
 function waitSpotDispatchIdle() {
-    return new Promise((resolve) => setTimeout(resolve, 5));
+    return new Promise((resolve) => setTimeout(resolve, ACTOR_JOIN_POLL_INTERVAL_MS));
 }

package/dist/runtime/spots/spot-actor-lifecycle-drain.js

@@ -26,7 +26,7 @@ class ZLinkSpotActorLifecycleDrain {
             }
             if (actorRef === null || actorRef === undefined)
                 continue;
-            await this.options.serial.execute(() => {
+            await this.options.serial.executeLifecycleOperation(() => this.options.serial.execute(() => {
                 const actor = this.options.resolveActor(actorId);
                 if (actor === undefined) {
                     return undefined;
@@ -44,7 +44,7 @@ class ZLinkSpotActorLifecycleDrain {
                     return target.onDisconnectActor?.(actor);
                 }
                 return undefined;
-            });
+            }));
         }
     }
 }

package/dist/runtime/spots/spot-actor-membership.d.ts

@@ -1,10 +1,10 @@
-import type { RoutingId, ZLinkActor, ZLinkMessageSerializer, ZLinkSpot, ZLinkSpotActorJoinResult } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { type RoutingId, type ZLinkActor, type ZLinkMessageSerializer, type ZLinkSpot, type ZLinkSpotActorJoinResult } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import { ZLinkDispatchErrorReporter } from '../channels';
 import type { ZLinkSpotActivation } from './spot-activation-state';
-import type { ZLinkSpotActorTransferRuntime } from './spot-runtime-ports';
 import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
+import type { ZLinkSpotActorTransferRuntime } from './spot-runtime-ports';
 export interface ZLinkSpotActorMembershipOptions {
     readonly resolveActivation: (spotId: RoutingId, meshName?: string) => ZLinkSpotActivation | undefined;
     readonly providerResolver?: ZLinkProviderResolver;
@@ -21,12 +21,13 @@ export interface ZLinkSpotActorMembershipOptions {
     readonly spotRouteResolver?: ZLinkSpotRouteResolver;
     readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
 }
-export type ZLinkActorJoinRollback = () => Promise<void> | void;
 export declare class ZLinkSpotActorMembership {
     private readonly options;
     constructor(options: ZLinkSpotActorMembershipOptions);
-    admitActorJoin(spotId: RoutingId, actor: ZLinkActor, request: Message, commit: (spot: ZLinkSpot) => Promise<ZLinkActorJoinRollback | void> | ZLinkActorJoinRollback | void, signal?: AbortSignal, leaveSource?: () => Promise<void>, contentType?: string): Promise<ZLinkSpotActorJoinResult>;
+    admitActorJoin(spotId: RoutingId, actor: ZLinkActor, request: Message, commit: (spot: ZLinkSpot) => Promise<void> | void, signal?: AbortSignal, leaveSource?: () => Promise<void>, contentType?: string): Promise<ZLinkSpotActorJoinResult>;
+    private admitActorJoinCore;
     leaveActor(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal, meshName?: string): Promise<void>;
+    private leaveActorCore;
     notifyActorLeftAfterTransfer(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     prepareActorLeaveForTransfer(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     commitActorLeaveAfterTransfer(spotId: RoutingId, actorId: string): Promise<void>;
@@ -35,5 +36,6 @@ export declare class ZLinkSpotActorMembership {
     cancelActorTransfer(spotId: RoutingId, actorId: string): Promise<void>;
     notifyJoinedActorDisconnected(spotId: RoutingId, actor: ZLinkActor, signal?: AbortSignal): Promise<boolean>;
     private requireActivation;
+    private runLifecycleOperation;
     private createActorDispatcher;
 }

package/dist/runtime/spots/spot-actor-membership.js

@@ -1,48 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorMembership = void 0;
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const contracts_1 = require("../../contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
 const abort_1 = require("../abort");
+const actors_1 = require("../actors");
 const runtime_message_1 = require("../backend/runtime-message");
 const configuration_1 = require("../configuration");
-const actors_1 = require("../actors");
 const payload_codec_1 = require("../messaging/payload-codec");
-const routing_id_1 = require("../routing-id");
 class ZLinkSpotActorMembership {
     options;
     constructor(options) {
         this.options = options;
     }
-    async admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType = 'application/json') {
+    async admitActorJoin(spotId, actor, request, commit, signal, leaveSource, contentType = stream_wire_1.ZlinkStreamContentType.Json) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId);
+        return await this.runLifecycleOperation(activation, async () => {
+            return await this.admitActorJoinCore(activation, actor, request, commit, signal, leaveSource, contentType);
+        });
+    }
+    async admitActorJoinCore(activation, actor, request, commit, signal, leaveSource, contentType) {
         const dispatcher = this.createActorDispatcher(activation);
-        const transaction = { committed: false };
-        let response;
-        try {
-            response = await dispatcher.evaluateActorJoin(actor, request, contentType);
-            if (response.accepted) {
+        const response = await dispatcher.evaluateActorJoin(actor, request, contentType);
+        if (response.accepted) {
+            await commit(activation.spot);
+            activation.commitActorJoin(actor);
+            try {
+                await dispatcher.notifyJoinActor(actor);
+            }
+            finally {
                 if (leaveSource === undefined) {
-                    await this.options.entrySpotCallbacks?.onLeaveActor(actor, signal);
+                    void this.options.entrySpotCallbacks?.onLeaveActor(actor, signal).catch((error) => {
+                        this.options.dispatchErrors?.report({
+                            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+                            messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorSend,
+                            reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                            action: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop,
+                            actorId: actor.context.actorId,
+                            error
+                        });
+                    });
                 }
                 else {
                     await leaveSource();
                 }
-                await dispatcher.commitActorJoin(actor, async () => {
-                    const rollback = await commit(activation.spot);
-                    if (rollback !== undefined)
-                        transaction.rollbackExternal = rollback;
-                    transaction.rollbackMembership = activation.commitActorJoin(actor);
-                    transaction.committed = true;
-                });
-            }
-        }
-        catch (error) {
-            if (transaction.committed) {
-                transaction.rollbackMembership?.();
-                await transaction.rollbackExternal?.();
             }
-            throw error;
         }
         return {
             accepted: response.accepted,
@@ -54,6 +58,9 @@ class ZLinkSpotActorMembership {
     async leaveActor(spotId, actor, signal, meshName) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId, meshName);
+        await this.runLifecycleOperation(activation, () => this.leaveActorCore(activation, actor, signal, meshName));
+    }
+    async leaveActorCore(activation, actor, signal, meshName) {
         const localEntryNodeRid = (meshName === undefined ? undefined : this.options.nodeRidProvider?.(meshName)) ??
             this.options.entryNodeRidProvider?.() ??
             this.options.entryNodeRid ??
@@ -68,24 +75,6 @@ class ZLinkSpotActorMembership {
         if (entryNodeRid === undefined) {
             throw new configuration_1.ZLinkConfigurationException('Spot actor leave requires an Entry Spot node routing id.');
         }
-        const remoteEntry = localEntryNodeRid !== undefined && !(0, routing_id_1.routingIdsEqual)(entryNodeRid, localEntryNodeRid);
-        if (!remoteEntry) {
-            const leaveSource = async () => {
-                activation.beginActorTransfer(actor.context.actorId);
-                await activation.spot.onLeaveActor(actor);
-                activation.commitActorDeparture(actor.context.actorId);
-                this.options.actorTransferRuntime?.clearRoutedActor(actor);
-            };
-            // A Spot actor handler already owns this activation's serial turn.
-            // Complete its lifecycle transition inside that turn instead of trying
-            // to acquire a second turn for the same owner.
-            if (activation.serial.isCurrentTurn) {
-                await leaveSource();
-            }
-            else {
-                await activation.serial.execute(leaveSource);
-            }
-        }
         const request = runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0));
         try {
             const context = actor.context;
@@ -109,40 +98,36 @@ class ZLinkSpotActorMembership {
     async notifyActorLeftAfterTransfer(spotId, actor, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(async () => {
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(async () => {
             activation.beginActorTransfer(actor.context.actorId);
             await activation.spot.onLeaveActor(actor);
             activation.commitActorDeparture(actor.context.actorId);
-        });
+        }));
     }
     async prepareActorLeaveForTransfer(spotId, actor, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(() => activation.spot.onLeaveActor(actor));
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(() => activation.spot.onLeaveActor(actor)));
     }
     async commitActorLeaveAfterTransfer(spotId, actorId) {
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(() => activation.commitActorDeparture(actorId));
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(() => activation.commitActorDeparture(actorId)));
     }
     async restoreActorAfterFailedTransfer(spotId, actor, signal) {
         (0, abort_1.throwIfAborted)(signal);
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(async () => {
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(async () => {
             activation.cancelActorTransfer(actor.context.actorId);
             await activation.spot.onJoinedActor(actor);
-        });
+        }));
     }
     async beginActorTransfer(spotId, actorId) {
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(() => {
-            activation.beginActorTransfer(actorId);
-        });
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(() => activation.beginActorTransfer(actorId)));
     }
     async cancelActorTransfer(spotId, actorId) {
         const activation = this.requireActivation(spotId);
-        await activation.serial.execute(() => {
-            activation.cancelActorTransfer(actorId);
-        });
+        await this.runLifecycleOperation(activation, () => activation.serial.execute(() => activation.cancelActorTransfer(actorId)));
     }
     async notifyJoinedActorDisconnected(spotId, actor, signal) {
         (0, abort_1.throwIfAborted)(signal);
@@ -164,6 +149,12 @@ class ZLinkSpotActorMembership {
         }
         return activation;
     }
+    async runLifecycleOperation(activation, operation) {
+        const pending = activation.serial.executeLifecycleOperation(operation);
+        return activation.serial.isCurrentTurn
+            ? await activation.serial.currentTurn.yieldFrameworkPromise(pending)
+            : await pending;
+    }
     createActorDispatcher(activation) {
         return new actors_1.ZLinkSpotActorDispatcher({
             registry: activation.actorHandlers,

package/dist/runtime/spots/spot-actor-packet-dispatch.d.ts

@@ -58,7 +58,6 @@ interface ZLinkSpotActorPacketDispatchOptions {
         readonly handled: boolean;
         readonly response?: unknown;
     } | undefined;
-    readonly onRemoteBoundSessionTarget?: (actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined) => void;
     readonly onDisconnectActor: (actor: ZLinkActor) => Promise<void>;
     readonly actorResponseSender?: (actor: ZLinkActor, packetName: string, requestSeq: bigint, response: unknown, replyOptions: ZLinkActorResponseOptions, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, signal?: AbortSignal) => Promise<void> | void;
     readonly actorErrorSender?: (actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, fallbackBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef) => Promise<void> | void;

package/dist/runtime/spots/spot-actor-packet-dispatch.js

@@ -65,14 +65,6 @@ class ZLinkSpotActorPacketDispatch {
                 header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
                 return undefined;
             }
-            if (remoteBoundSessionTarget !== undefined &&
-                (0, actors_1.actorMessageFollowContext)(fallbackActorRef) === undefined) {
-                // A replayed handoff/Message Follow packet keeps its captured Session
-                // route solely for that packet's response. It cannot republish the
-                // predecessor route over a binding already confirmed by a later Actor
-                // owner turn.
-                this.options.onRemoteBoundSessionTarget?.(actorId, remoteBoundSessionTarget);
-            }
             const routed = await this.options.routeBeforeLocal?.(delivery);
             if (routed?.handled === true) {
                 return routed.response;
@@ -82,7 +74,6 @@ class ZLinkSpotActorPacketDispatch {
                 return this.handleMissingActor(actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
             }
             if (header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
-                this.options.onRemoteBoundSessionTarget?.(actorId, undefined);
                 await this.options.onDisconnectActor(actor);
                 return undefined;
             }

package/dist/runtime/spots/spot-actor-packet-relay-dispatch.d.ts

@@ -1,12 +1,12 @@
 import { type ActorRef, type RoutingId } from '../../contracts';
 import type { ZLinkBackendReceived as BackendReceived } from '../backend/runtime-values';
-import type { ZLinkRemoteActorPacketTarget, ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkRemoteActorPacketTarget } from '../actors';
 import type { ZLinkRemoteActorPacketRelay } from './spot-remote-route-codec';
 import type { ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
 interface ZLinkSpotActorPacketRelayDispatchOptions {
     readonly actorPacketHandler?: (delivery: ZLinkActorPacketDelivery) => Promise<unknown>;
     readonly actorPacketTargetProvider?: (actorId: string) => ZLinkRemoteActorPacketTarget | undefined;
-    readonly bindRemoteSession?: (actor: ActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId, declaredTarget?: ZLinkRemoteBoundSessionTarget) => void;
+    readonly bindRemoteSession?: (actor: ActorRef, sourceNodeRid: RoutingId, sourceSessionRid: RoutingId) => void;
     readonly flowEnabled?: () => boolean;
 }
 export declare class ZLinkSpotActorPacketRelayDispatch {

package/dist/runtime/spots/spot-actor-packet-relay-dispatch.js

@@ -44,13 +44,7 @@ class ZLinkSpotActorPacketRelayDispatch {
                 if (!(0, routing_id_1.routingIdsEqual)(sourceNodeRid, declaredSourceNodeRid)) {
                     throw new Error('Remote actor session binding source did not match the declared session node.');
                 }
-                this.options.bindRemoteSession(actorRef, declaredSourceNodeRid, binding.sessionRid, remoteBoundSessionTarget === undefined
-                    ? undefined
-                    : {
-                        ...remoteBoundSessionTarget,
-                        sessionNodeRid: declaredSourceNodeRid,
-                        sessionRid: binding.sessionRid
-                    });
+                this.options.bindRemoteSession(actorRef, declaredSourceNodeRid, binding.sessionRid);
                 if ((0, spot_route_replies_1.hasReplyToken)(received.replyToken)) {
                     (0, spot_route_replies_1.submitSpotRouteBridgeReply)(received, actorPacketRelay.envelope, {
                         ok: true,

package/dist/runtime/spots/spot-context.d.ts

@@ -6,7 +6,7 @@ import { type ZLinkSpotTimerRegistry } from './spot-timer';
 import type { ZLinkSpotSerialTurnExecutor } from './spot-serial-turn-executor';
 interface ZLinkEntrySpotContextOptions {
     readonly spotId: SpotId;
-    readonly objectGeneration: number;
+    readonly objectGeneration: bigint;
     readonly nodeRid: RoutingId;
     readonly handlers: ZLinkSpotHandlerRegistry;
     readonly outbound: ZLinkSpotOutbound;
@@ -22,7 +22,7 @@ interface ZLinkEntrySpotContextOptions {
 interface ZLinkSpotContextOptions {
     readonly meshName: string;
     readonly spotId: SpotId;
-    readonly objectGeneration: number;
+    readonly objectGeneration: bigint;
     readonly handlers: ZLinkSpotHandlerRegistry;
     readonly outbound: ZLinkSpotOutbound;
     readonly timers: ZLinkSpotTimerRegistry;

package/dist/runtime/spots/spot-entry-activation.d.ts

@@ -3,7 +3,7 @@ import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProvider
 import type { ZLinkRuntimeEventPublisher } from '../diagnostics';
 import type { ZLinkEntrySpotActorRequestHandlerRegistration, ZLinkEntrySpotActorSendHandlerRegistration, ZLinkEntrySpotPacketHandlerRegistration, ZLinkEntrySpotSubscriptionHandlerRegistration, ZLinkEntrySpotTimerHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkBackendReceived, ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendTopicMessage } from '../backend/contracts';
+import type { ZLinkBackendSpot, ZLinkBackendSpotNode, ZLinkBackendTopicMessage } from '../backend/contracts';
 import type { ZLinkDispatchErrorReporter } from '../channels';
 import { ZLinkWorkerRuntime } from '../workers';
 import { type ZLinkActorPacketDelivery } from './spot-actor-packet-dispatch';
@@ -21,7 +21,6 @@ interface ZLinkEntrySpotActivationOptions {
     readonly actorRequestHandlers?: readonly ZLinkEntrySpotActorRequestHandlerRegistration[];
     readonly nativeSpot: ZLinkBackendSpot;
     readonly nativeNode: ZLinkBackendSpotNode;
-    readonly createReceived: () => ZLinkBackendReceived;
     readonly createTopicMessage: () => ZLinkBackendTopicMessage;
     readonly nodeRid: RoutingId;
     readonly spotNodeName: string;
@@ -30,7 +29,6 @@ interface ZLinkEntrySpotActivationOptions {
     readonly spotPublisherClient?: ZLinkSpotPublisherClient;
     readonly routedTransport?: ZLinkSpotRoutedTransport;
     readonly spotRouterChannelIdForMesh?: (meshName: string) => string;
-    readonly channelMeshNameForChannel?: (channelName: string) => string | undefined;
     readonly providerResolver?: ZLinkProviderResolver;
     readonly dispatchErrors?: ZLinkDispatchErrorReporter;
     readonly runtimeEventPublisher?: ZLinkRuntimeEventPublisher;
@@ -41,7 +39,7 @@ interface ZLinkEntrySpotActivationOptions {
     readonly actorTransferRuntime?: ZLinkSpotActorTransferRuntime;
     readonly boundSessionRuntime?: ZLinkSpotBoundSessionRuntime;
     readonly actorHandoffRuntime?: ZLinkSpotActorHandoffRuntime;
-    readonly detachedTaskRunner?: ZLinkDetachedTaskRunner;
+    readonly detachedTaskRunner: ZLinkDetachedTaskRunner;
 }
 export declare class ZLinkEntrySpotActivation {
     private readonly options;
@@ -90,6 +88,7 @@ export declare class ZLinkEntrySpotActivation {
      * actor-manager transaction in its admission callback.
      */
     commitServiceActorJoin(actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[], signal?: AbortSignal): Promise<void>;
+    executeActor<T>(actorId: string, operation: () => Promise<T>): Promise<T>;
     /**
      * Entry Spot membership does not have an application admission callback.
      * The shared core round-trip therefore accepts a valid returning Actor and

package/dist/runtime/spots/spot-entry-activation.js

@@ -40,6 +40,9 @@ class ZLinkEntrySpotActivation {
     context;
     constructor(options) {
         this.options = options;
+        if (options.detachedTaskRunner === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Entry Spot activation requires a detached task runner.');
+        }
         this.serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(false, options.nativeSpot.routingId);
         this.spotSerialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(this.serial, contracts_1.ZLinkUserSpotExecutionMode.PerActor, options.nativeSpot.routingId);
         // Entry Spot lifecycle, timers and detached continuations use this serial
@@ -57,7 +60,7 @@ class ZLinkEntrySpotActivation {
         this.workerRuntime = options.workerRuntime ?? new workers_1.ZLinkWorkerRuntime();
         this.context = (0, spot_context_1.createEntrySpotContext)({
             spotId: String(options.nativeSpot.routingId),
-            objectGeneration: toContextGeneration(entrySpotGeneration(options.nativeSpot)),
+            objectGeneration: entrySpotGeneration(options.nativeSpot),
             nodeRid: options.nodeRid,
             handlers: this.handlers,
             outbound: this.outbound,
@@ -97,7 +100,6 @@ class ZLinkEntrySpotActivation {
             registry: this.actorHandlers,
             resolveActor: (targetActorId) => this.options.entryActorRuntime?.resolveActor(targetActorId),
             routeBeforeLocal: (target) => this.options.entryActorRuntime?.routePacket(target.actorId, target.parts, target.returnResponse, target.remoteBoundSessionTarget, target.fallbackActorRef),
-            onRemoteBoundSessionTarget: (targetActorId, target) => this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(targetActorId, target),
             onDisconnectActor: (actor) => this.notifyDisconnectActor(actor),
             actorResponseSender: this.options.boundSessionRuntime?.sendActorResponse.bind(this.options.boundSessionRuntime),
             actorErrorSender: this.options.boundSessionRuntime?.sendActorError.bind(this.options.boundSessionRuntime),
@@ -179,7 +181,7 @@ class ZLinkEntrySpotActivation {
         await cleanup(() => this.actorDispatch?.dispose());
         await cleanup(() => this.timers.dispose());
         await cleanup(() => this.spotSerialExecutor.close());
-        await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(this.entrySpot));
+        await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(this.entrySpot, this.options.detachedTaskRunner));
         await cleanup(() => this.options.nativeSpot.dispose());
         if (this.initialized) {
             this.lifecycleMetrics.closed('entry');
@@ -215,6 +217,9 @@ class ZLinkEntrySpotActivation {
             await this.replayActorBacklog(actor, handoffBacklog);
         }
     }
+    executeActor(actorId, operation) {
+        return this.spotSerialExecutor.executeActor(actorId, operation);
+    }
     /**
      * Entry Spot membership does not have an application admission callback.
      * The shared core round-trip therefore accepts a valid returning Actor and
@@ -223,7 +228,6 @@ class ZLinkEntrySpotActivation {
     attachActorJoinDispatch() {
         const dispatch = new spot_actor_join_dispatch_1.ZLinkSpotActorJoinDispatch({
             nativeSpot: this.options.nativeSpot,
-            createReceived: this.options.createReceived,
             createTopicMessage: this.options.createTopicMessage,
             serial: this.serial,
             actors: {
@@ -236,7 +240,6 @@ class ZLinkEntrySpotActivation {
                         kind: 'enabled',
                         runtime: this.options.actorTransferRuntime
                     },
-                commitNativeActor: (actor) => this.commitEntryActorTransaction(actor),
                 commitTransferredActor: async (actor, backlog) => {
                     await this.commitEntryActorTransaction(actor);
                     return await this.replayActorBacklog(actor, backlog);
@@ -244,19 +247,10 @@ class ZLinkEntrySpotActivation {
             },
             packets: {
                 handle: (delivery) => this.dispatchActorPacket(delivery),
-                bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid, declaredTarget) => {
+                bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
                     if ((0, routing_id_1.routingIdsEqual)(sourceNodeRid, this.options.nativeNode.routingId)) {
                         return;
                     }
-                    const target = declaredTarget ??
-                        this.options.boundSessionRuntime?.resolveRemoteBoundSessionTarget(sourceNodeRid, sourceSessionRid);
-                    if (target !== undefined) {
-                        this.options.boundSessionRuntime?.rememberRemoteBoundSessionTarget(actor.actorId, {
-                            ...target,
-                            sessionNodeRid: sourceNodeRid,
-                            sessionRid: sourceSessionRid
-                        });
-                    }
                     this.options.nativeNode.bindRemoteActorSession(actor, sourceNodeRid, sourceSessionRid);
                 },
                 replyNoBind: (info, parts, result) => this.replyActorNoBind(info, parts, result)
@@ -328,12 +322,6 @@ function notifyEntryActorJoined(entrySpot, actor) {
     const callback = entrySpot.onJoinedActor;
     return callback === undefined ? Promise.resolve() : callback.call(entrySpot, actor);
 }
-function toContextGeneration(generation) {
-    if (generation < 0n || generation > BigInt(Number.MAX_SAFE_INTEGER)) {
-        throw new configuration_1.ZLinkConfigurationException(`Entry Spot object generation '${generation}' cannot be represented by the Node.js public context.`);
-    }
-    return Number(generation);
-}
 function entrySpotGeneration(spot) {
     return (spot.lifecycleGeneration ??
         spot.status?.().lifecycleGeneration ??

package/dist/runtime/spots/spot-lifecycle-metrics.js

@@ -1,16 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotLifecycleMetrics = void 0;
+const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 class ZLinkSpotLifecycleMetrics {
     metrics;
     constructor(metrics) {
         this.metrics = metrics;
     }
     opened(kind) {
-        this.metrics?.change('zlink.spot.count', 1, { kind });
+        this.metrics?.change(runtime_metrics_1.METRIC_NAMES.SpotCount, 1, { kind });
     }
     closed(kind) {
-        this.metrics?.change('zlink.spot.count', -1, { kind });
+        this.metrics?.change(runtime_metrics_1.METRIC_NAMES.SpotCount, -1, { kind });
     }
 }
 exports.ZLinkSpotLifecycleMetrics = ZLinkSpotLifecycleMetrics;

package/dist/runtime/spots/spot-manager-public.d.ts

@@ -1,12 +1,11 @@
-import { type RoutingId, type SpotId, type SpotRef, type ZLinkSpot, type ZLinkSpotCreateCall, type ZLinkSpotGetOrCreateCall, type ZLinkSpotManager } from '../../contracts';
-import type { ZLinkMessageSerializer } from '../../contracts';
+import { type ZLinkMessageSerializer, type RoutingId, type SpotId, type SpotRef, type ZLinkSpot, type ZLinkSpotCreateCall, type ZLinkSpotGetOrCreateCall, type ZLinkSpotManager } from '../../contracts';
 import type { ZLinkObjectFactoryRegistration } from '../../contracts/Configuration/RegistrationTypes';
-import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
-import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
-import type { DefaultZLinkSpotManager } from './index';
-import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
 import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+import type { ServiceUserSpotCloseRecord } from '../foundation/service-stateful-wire-codec';
+import type { ZLinkUserSpotCreationCoordinator } from '../host/user-spot-creation-coordinator';
 import type { ZLinkAuthoritySnapshot } from '../locations/internal-location-contracts';
+import type { DefaultZLinkSpotManager } from './index';
+import type { ZLinkSpotRouteResolver } from './spot-routing-internal';
 export interface ZLinkPublicSpotManagerOptions {
     readonly local: DefaultZLinkSpotManager;
     readonly coordinator: ZLinkUserSpotCreationCoordinator;

package/dist/runtime/spots/spot-manager-public.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkPublicSpotManager = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
 const node_crypto_1 = require("node:crypto");
 const contracts_1 = require("../../contracts");
+const CoreTypes_1 = require("../../contracts/Common/CoreTypes");
 const configuration_1 = require("../configuration");
-const creation_payload_codec_1 = require("../messaging/creation-payload-codec");
 const execution_1 = require("../execution");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const creation_payload_codec_1 = require("../messaging/creation-payload-codec");
 class ZLinkPublicSpotManager {
     options;
     constructor(options) {
@@ -51,7 +52,7 @@ class ZLinkPublicSpotManager {
             return false;
         const current = resolved.spot;
         if (this.options.isLocalNode(current.meshName, current.nodeRid)) {
-            const closed = await this.options.coordinator.close(spot, (local) => this.options.local.close(local.meshName, local.spotId, signal), signal, (local) => this.options.local.hasActiveSpot(local.spotId), (local) => this.options.local.canCloseUserSpot(local.meshName, local.spotId));
+            const closed = await this.options.coordinator.close(spot, (local, beginAuthority) => this.options.local.closeUserWithAuthority(local.meshName, local.spotId, beginAuthority, signal), signal);
             if (closed)
                 this.options.resolver()?.invalidate?.(spot.spotId);
             return closed;
@@ -208,8 +209,8 @@ function selectFactory(factories, stableType, selectedMesh) {
 }
 function requireText(value, label) {
     const bytes = Buffer.byteLength(value);
-    if (bytes < 1 || bytes > 255 || value.includes('\0')) {
-        throw invalidConfiguration(`${label} must contain 1..255 UTF-8 bytes and no NUL.`);
+    if (bytes < 1 || bytes > CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES || value.includes('\0')) {
+        throw invalidConfiguration(`${label} must contain 1..${CoreTypes_1.ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes and no NUL.`);
     }
     return value;
 }