@zlink-systems/framework 0.29.1 → 0.30.1

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

@@ -36,7 +36,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, objectKind === 'user_spot'
             ? {
                 actorSendHandlers: this.options.spotActorSendHandlers,
@@ -154,7 +154,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = serialOwner?.serial ?? new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(true, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         const instanceHandlers = new spot_handler_registry_1.DefaultZLinkInstanceSpotHandlerRegistry(handlers);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, implementation, {
             packetHandlers: this.options.spotPacketHandlers
@@ -268,7 +268,7 @@ class ZLinkSpotActivationLifecycle {
         const serial = new spot_serial_turn_executor_1.ZLinkSpotSerialTurnExecutor(executionMode === contracts_1.ZLinkUserSpotExecutionMode.SpotWide, spotId);
         const serialExecutor = new spot_serial_executor_1.ZLinkSpotSerialExecutor(serial, executionMode, spotId);
         const actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers);
+        const handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(actorHandlers, this.options.providerResolver);
         (0, spot_handler_registry_1.applySpotHandlerRegistrations)(handlers, spotType, {
             actorSendHandlers: this.options.spotActorSendHandlers,
             actorRequestHandlers: this.options.spotActorRequestHandlers,
@@ -477,12 +477,12 @@ class ZLinkSpotActivationLifecycle {
     async cleanupFailedIncarnation(activation) {
         await this.cleanupActivation(activation, activation.meshName, false, undefined, contracts_1.ZLinkSpotCloseReason.ExplicitClose, undefined, true);
     }
-    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
-        return await this.actorAdmission.dispatchActorPacket(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
+    async dispatchActorPacket(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        return await this.actorAdmission.dispatchActorPacket(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin);
     }
     /** @internal Dispatches a held Actor record after its handoff owner releases it. */
-    dispatchActorPacketDirect(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
-        return this.actorAdmission.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
+    dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef) {
+        return this.actorAdmission.dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef);
     }
     /** @internal Atomically restores one durable Actor packet prefix. */
     admitActorPacketPrefix(activation, actorId, records) {
@@ -571,7 +571,9 @@ class ZLinkSpotActivationLifecycle {
             catch (error) {
                 // An OnClosing failure is diagnostic and cleanup continues. It is
                 // returned so host shutdown can classify its teardown outcome.
-                this.options.closeErrorSink?.reportRuntimeTaskException(`spot ${String(activation.spotId)} onClosing`, error);
+                if (reason !== contracts_1.ZLinkSpotCloseReason.HostShutdown) {
+                    this.options.closeErrorSink?.reportRuntimeTaskException(`spot ${String(activation.spotId)} onClosing`, error);
+                }
                 closingFailure = error;
             }
         }
@@ -598,7 +600,12 @@ class ZLinkSpotActivationLifecycle {
             });
         }
         if (!state.nativeDisposed) {
-            await cleanup(() => activation.nativeSpot?.dispose(), () => {
+            await cleanup(async () => {
+                if (reason === contracts_1.ZLinkSpotCloseReason.HostShutdown) {
+                    await this.options.releaseActorMembers?.(locationMeshName, activation.spotId);
+                }
+                await activation.nativeSpot?.dispose();
+            }, () => {
                 state.nativeDisposed = true;
             });
         }
@@ -617,9 +624,11 @@ class ZLinkSpotActivationLifecycle {
                 state.locationReleased = true;
             });
         }
-        if (errors.length === 1)
-            throw errors[0];
-        if (errors.length > 1) {
+        if (errors.length > 0) {
+            if (closingFailure !== undefined)
+                errors.unshift(closingFailure);
+            if (errors.length === 1)
+                throw errors[0];
             throw new AggregateError(errors, `Spot '${activation.spotId}' cleanup failed.`);
         }
         return closingFailure;

package/dist/runtime/spots/spot-actor-admission-coordinator.d.ts

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkMessageFollowOrigin } from '../foundation/service-runtime-contracts';
@@ -10,7 +11,7 @@ type AdmissionOptions = Pick<ZLinkSpotActivationLifecycleOptions, 'actorHandoffR
 export declare class ZLinkSpotActorAdmissionCoordinator {
     private readonly options;
     constructor(options: AdmissionOptions);
-    dispatchActorPacket(activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    dispatchActorPacket(origin: ApplicationJobOrigin, activation: ZLinkSpotActivation, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     attachNativeActorJoinDispatch(activation: ZLinkSpotActivation, nativeSpot: ZLinkBackendSpot | undefined): ZLinkSpotActorJoinDispatch | undefined;
     private dispatchActorPacketInActorTurn;
     private commitTransferredActorTransaction;

package/dist/runtime/spots/spot-actor-admission-coordinator.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorAdmissionCoordinator = void 0;
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
 const actor_handoff_1 = require("../actors/actor-handoff");
 const routing_id_1 = require("../routing-id");
 const spot_actor_join_dispatch_1 = require("./spot-actor-join-dispatch");
@@ -10,11 +11,11 @@ class ZLinkSpotActorAdmissionCoordinator {
     constructor(options) {
         this.options = options;
     }
-    async dispatchActorPacket(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
-        const handoff = this.options.actorHandoffRuntime?.capture(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.dispatchActorPacketDirect(activation, actorId, replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef));
+    async dispatchActorPacket(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+        const handoff = this.options.actorHandoffRuntime?.capture(origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.dispatchActorPacketDirect(origin, activation, actorId, replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef));
         if (handoff !== undefined)
             return await handoff;
-        return await this.dispatchActorPacketDirect(activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+        return await this.dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
     }
     attachNativeActorJoinDispatch(activation, nativeSpot) {
         if (nativeSpot === undefined)
@@ -39,7 +40,7 @@ class ZLinkSpotActorAdmissionCoordinator {
                 commitTransferredActor: (actor, backlog, sealedSession) => this.commitTransferredActorTransaction(activation, actor, backlog, sealedSession)
             },
             packets: {
-                handle: (delivery) => this.dispatchActorPacket(activation, delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef),
+                handle: (delivery) => this.dispatchActorPacket('remote', activation, delivery.actorId, delivery.parts, delivery.returnResponse, delivery.remoteBoundSessionTarget, delivery.fallbackActorRef),
                 bindRemoteSession: (actor, sourceNodeRid, sourceSessionRid) => {
                     const node = this.options.nativeSpotNodeProvider?.(activation.meshName);
                     if (node === undefined || (0, routing_id_1.routingIdsEqual)(sourceNodeRid, node.routingId))
@@ -63,8 +64,8 @@ class ZLinkSpotActorAdmissionCoordinator {
         return nativeDispatch;
     }
     /** @internal Dispatches a coordinator-owned replay without recapturing it. */
-    dispatchActorPacketDirect(activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
-        return activation.executeActor(actorId, (actorSerial) => this.dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal));
+    dispatchActorPacketDirect(origin, activation, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+        return activation.executeActor(actorId, (actorSerial) => this.dispatchActorPacketInActorTurn(origin, activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal));
     }
     /**
      * Atomically restores one durable packet prefix at the Actor FIFO tail.
@@ -75,7 +76,7 @@ class ZLinkSpotActorAdmissionCoordinator {
      */
     admitActorPacketPrefix(activation, actorId, records) {
         const terminals = activation.admitActorDurablePrefix(actorId, records.map((record) => ({
-            operation: (executeChild) => record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => executeChild((actorSerial) => this.dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef))),
+            operation: (executeChild) => record.drain((parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => executeChild((actorSerial) => this.dispatchActorPacketInActorTurn((0, application_job_queue_scope_1.currentApplicationJobOrigin)(), activation, actorSerial, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef))),
             preparation: record.preparation,
             workOptions: { payloadBytes: record.payloadBytes }
         })));
@@ -89,7 +90,7 @@ class ZLinkSpotActorAdmissionCoordinator {
         });
         return { terminal };
     }
-    dispatchActorPacketInActorTurn(activation, actorSerial, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+    dispatchActorPacketInActorTurn(origin, activation, actorSerial, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
         return new spot_actor_packet_dispatch_1.ZLinkSpotActorPacketDispatch({
             spot: activation.spot,
             spotId: () => String(activation.spotId),
@@ -107,7 +108,7 @@ class ZLinkSpotActorAdmissionCoordinator {
             messageSerializers: this.options.messageSerializers,
             dispatchErrors: this.options.dispatchErrors,
             routeToActorJoinPrewarm: this.options.routeToActorJoinPrewarm
-        }).dispatch(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+        }).dispatch(origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
     }
     async commitTransferredActorTransaction(activation, actor, backlog, sealedSession) {
         const transfer = this.options.actorTransferRuntime;
@@ -140,7 +141,7 @@ class ZLinkSpotActorAdmissionCoordinator {
         }
     }
     async replayActorBacklog(activation, actor, backlog) {
-        return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.dispatchActorPacketDirect(activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef), (index) => this.options.runtimeEventPublisher?.publish({
+        return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.dispatchActorPacketDirect('remote', activation, actor.context.actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef), (index) => this.options.runtimeEventPublisher?.publish({
             sourceName: 'zlink.framework.actor-handoff',
             timestamp: new Date(),
             marker: 'backlog_enqueued',

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import type { ActorRef, RoutingId, ZLinkActor, ZLinkMessageSerializer, ZLinkSpot } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkRemoteBoundSessionTarget } from '../actors';
@@ -17,6 +18,7 @@ export interface ZLinkActorRequestTerminal {
 }
 /** One admitted Actor packet and the routing context that must move with it. */
 export interface ZLinkActorPacketDelivery {
+    readonly origin: ApplicationJobOrigin;
     readonly actorId: string;
     readonly parts: readonly Message[];
     readonly returnResponse: boolean;
@@ -35,6 +37,7 @@ export interface ZLinkActorPacketDelivery {
  * unchanged.
  */
 export type ZLinkRouteToActorJoinPrewarm = (actorId: string, objectGeneration: bigint, arrival: {
+    readonly origin: ApplicationJobOrigin;
     readonly header: Buffer;
     readonly payload: Buffer;
     readonly returnResponse: boolean;
@@ -69,7 +72,7 @@ interface ZLinkSpotActorPacketDispatchOptions {
 export declare class ZLinkSpotActorPacketDispatch {
     private readonly options;
     constructor(options: ZLinkSpotActorPacketDispatchOptions);
-    dispatch(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: ZLinkActorRequestTerminal): Promise<unknown>;
+    dispatch(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: ZLinkActorRequestTerminal): Promise<unknown>;
     dispatchDelivery(delivery: ZLinkActorPacketDelivery): Promise<unknown>;
     private handleMissingActor;
     /**

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

@@ -17,8 +17,9 @@ class ZLinkSpotActorPacketDispatch {
     constructor(options) {
         this.options = options;
     }
-    dispatch(actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+    dispatch(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
         return this.dispatchDelivery({
+            origin,
             actorId,
             parts,
             returnResponse,
@@ -71,7 +72,7 @@ class ZLinkSpotActorPacketDispatch {
             }
             const actor = this.options.resolveActor(actorId);
             if (actor === undefined) {
-                return this.handleMissingActor(actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
+                return this.handleMissingActor(delivery.origin, actorId, parts, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal);
             }
             if (header.name === actors_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET) {
                 await this.options.onDisconnectActor(actor);
@@ -81,7 +82,7 @@ class ZLinkSpotActorPacketDispatch {
             return this.dispatchActorPacket(actor, actorId, decodePayload, header, messageKind, action, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, requestDeadlineUnixMs, (0, serial_work_size_1.zlinkSerialWorkOptions)(parts[1].data().byteLength, (0, serial_work_size_1.zlinkMetadataByteLength)(header.metadata)));
         });
     }
-    async handleMissingActor(actorId, parts, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal) {
+    async handleMissingActor(origin, actorId, parts, header, messageKind, action, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal) {
         if (this.options.routeToActorJoinPrewarm !== undefined &&
             fallbackActorRef !== undefined &&
             parts.length >= 2 &&
@@ -90,7 +91,7 @@ class ZLinkSpotActorPacketDispatch {
             //  forever with no reply route. Fall through to the existing
             //  missing-actor handling for that shape instead.
             (messageKind !== ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest || requestTerminal !== undefined)) {
-            const parked = this.parkForActorJoinPrewarm(actorId, parts, messageKind, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal);
+            const parked = this.parkForActorJoinPrewarm(origin, actorId, parts, messageKind, returnResponse, fallbackBoundSessionTarget, fallbackActorRef, requestTerminal);
             if (parked !== undefined)
                 return parked;
         }
@@ -126,7 +127,7 @@ class ZLinkSpotActorPacketDispatch {
      * arrival survives independently of the original {@link Message}
      * lifetime.
      */
-    parkForActorJoinPrewarm(actorId, parts, messageKind, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
+    parkForActorJoinPrewarm(origin, actorId, parts, messageKind, returnResponse, remoteBoundSessionTarget, fallbackActorRef, requestTerminal) {
         const isRequest = messageKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest;
         let resolve = () => undefined;
         let reject = () => undefined;
@@ -154,6 +155,7 @@ class ZLinkSpotActorPacketDispatch {
                 }
             }, { prepare: requestTerminal.prepare });
         const route = this.options.routeToActorJoinPrewarm(actorId, fallbackActorRef.objectGeneration, {
+            origin,
             header: Buffer.from(parts[0].data()),
             payload: Buffer.from(parts[1].data()),
             returnResponse,

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

@@ -83,6 +83,7 @@ class ZLinkSpotActorPacketDrain {
             }
             else {
                 await this.options.actorPacketHandler({
+                    origin: 'remote',
                     actorId,
                     parts,
                     returnResponse: false,
@@ -131,6 +132,7 @@ class ZLinkSpotActorPacketDrain {
     async dispatchNoBindActorRequest(info, actorId, parts, actorRef) {
         try {
             const response = await this.options.actorPacketHandler?.({
+                origin: 'remote',
                 actorId,
                 parts,
                 returnResponse: true,

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

@@ -69,6 +69,7 @@ class ZLinkSpotActorPacketRelayDispatch {
                 actorPacketRelay.messageFollowContext !== undefined &&
                 remoteBoundSessionTarget !== undefined;
             const response = await this.options.actorPacketHandler({
+                origin: 'remote',
                 actorId: actorPacketRelay.actorId,
                 parts: [header, payload],
                 returnResponse: !followedBoundSessionReply,

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

@@ -27,7 +27,7 @@ class ZLinkEntrySpotActivation {
     spotSerialExecutor;
     timers;
     actorHandlers = new actors_1.ZLinkSpotActorHandlerRegistryRuntime();
-    handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(this.actorHandlers);
+    handlers;
     outbound;
     workerRuntime;
     lifecycleMetrics;
@@ -43,6 +43,7 @@ class ZLinkEntrySpotActivation {
         if (options.detachedTaskRunner === undefined) {
             throw new configuration_1.ZLinkConfigurationException('Entry Spot activation requires a detached task runner.');
         }
+        this.handlers = new spot_handler_registry_1.DefaultZLinkSpotHandlerRegistry(this.actorHandlers, options.providerResolver);
         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
@@ -182,7 +183,10 @@ class ZLinkEntrySpotActivation {
         await cleanup(() => this.timers.dispose());
         await cleanup(() => this.spotSerialExecutor.close());
         await cleanup(() => (0, handler_instance_scope_1.disposeLifecycleHandlers)(this.entrySpot, this.options.detachedTaskRunner));
-        await cleanup(() => this.options.nativeSpot.dispose());
+        await cleanup(async () => {
+            await this.options.entryActorRuntime?.releaseMembers?.(this.options.spotNodeName);
+            await this.options.nativeSpot.dispose();
+        });
         if (this.initialized) {
             this.lifecycleMetrics.closed('entry');
         }
@@ -287,7 +291,8 @@ class ZLinkEntrySpotActivation {
     }
     async dispatchActorPacket(delivery) {
         const { actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, messageFollowOrigin } = delivery;
-        const handoff = this.options.actorHandoffRuntime?.capture(actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox({
+        const handoff = this.options.actorHandoffRuntime?.capture(delivery.origin, actorId, parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef, undefined, messageFollowOrigin, (replayedParts, replayReturnResponse, replayRemoteBoundSessionTarget, replayFallbackActorRef) => this.spotSerialExecutor.executeActor(actorId, () => this.dispatchActorPacketInsideMailbox({
+            origin: delivery.origin,
             actorId,
             parts: replayedParts,
             returnResponse: replayReturnResponse,
@@ -300,6 +305,7 @@ class ZLinkEntrySpotActivation {
     }
     async replayActorBacklog(actor, backlog) {
         return await (0, actor_handoff_1.replayActorHandoffBacklog)(backlog, (parts, returnResponse, remoteBoundSessionTarget, fallbackActorRef) => this.spotSerialExecutor.executeActor(actor.context.actorId, () => this.dispatchActorPacketInsideMailbox({
+            origin: 'remote',
             actorId: actor.context.actorId,
             parts,
             returnResponse,

package/dist/runtime/spots/spot-handler-registry.d.ts

@@ -1,5 +1,6 @@
 import type { Type, ZLinkActor, ZLinkEntrySpot, ZLinkInstanceSpotHandlerRegistry, ZLinkSpot, ZLinkSpotHandlerRegistry } from '../../contracts';
 import type { ZLinkEntrySpotActorRequestHandlerRegistration, ZLinkEntrySpotActorSendHandlerRegistration, ZLinkEntrySpotPacketHandlerRegistration, ZLinkEntrySpotSubscriptionHandlerRegistration, ZLinkSpotActorRequestHandlerRegistration, ZLinkSpotActorSendHandlerRegistration, ZLinkSpotPacketHandlerRegistration, ZLinkSpotSubscriptionHandlerRegistration } from '../../contracts/Configuration/RegistrationTypes';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import { ZLinkActorPacketKind, ZLinkSpotActorHandlerRegistryRuntime } from '../actors';
 export interface ZLinkSpotHandlerRegistration {
     readonly kind: 'packet' | 'subscribe' | 'actorSend' | 'actorRequest' | 'spotHandler';
@@ -11,8 +12,9 @@ export interface ZLinkSpotHandlerRegistration {
 }
 export declare class DefaultZLinkSpotHandlerRegistry<TActor extends ZLinkActor = ZLinkActor> implements ZLinkSpotHandlerRegistry {
     private readonly actorHandlers?;
+    private readonly providerResolver?;
     private readonly entries;
-    constructor(actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime | undefined);
+    constructor(actorHandlers?: ZLinkSpotActorHandlerRegistryRuntime | undefined, providerResolver?: ZLinkProviderResolver | undefined);
     addHandler<THandler>(handlerType: Type<THandler>, packetName?: string): this;
     addActorPacket<THandler, TRegisteredActor extends ZLinkActor>(handlerType: Type<THandler>, actorType: Type<TRegisteredActor>): this;
     addPacket(handlerType: Type, packetName?: string): this;

package/dist/runtime/spots/spot-handler-registry.js

@@ -3,36 +3,43 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultZLinkInstanceSpotHandlerRegistry = exports.DefaultZLinkSpotHandlerRegistry = void 0;
 exports.applyEntrySpotHandlerRegistrations = applyEntrySpotHandlerRegistrations;
 exports.applySpotHandlerRegistrations = applySpotHandlerRegistrations;
-const configuration_1 = require("../configuration");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const actors_1 = require("../actors");
 const Attributes_1 = require("../../contracts/Handlers/Attributes");
 class DefaultZLinkSpotHandlerRegistry {
     actorHandlers;
+    providerResolver;
     entries = [];
-    constructor(actorHandlers) {
+    constructor(actorHandlers, providerResolver) {
         this.actorHandlers = actorHandlers;
+        this.providerResolver = providerResolver;
     }
     addHandler(handlerType, packetName) {
         const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
         const resolvedPacketName = packetName ?? metadata?.packetName;
         if (metadata === undefined || resolvedPacketName === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor packet handler '${handlerType.name}' must declare a packet name.`);
         }
         return this.addActorPacketRegistration(metadata.kind === 'spotActorSend' ? actors_1.ZLinkActorPacketKind.Send : actors_1.ZLinkActorPacketKind.Request, handlerType, Object, resolvedPacketName);
     }
     addActorPacket(handlerType, actorType) {
         const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'spotActorSend' || entry.kind === 'spotActorRequest');
         if (metadata?.packetName === undefined) {
-            throw new configuration_1.ZLinkConfigurationException(`Actor packet handler '${handlerType.name}' must declare a packet name.`);
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor packet handler '${handlerType.name}' must declare a packet name.`);
         }
         return this.addActorPacketRegistration(metadata.kind === 'spotActorSend' ? actors_1.ZLinkActorPacketKind.Send : actors_1.ZLinkActorPacketKind.Request, handlerType, actorType, metadata.packetName);
     }
     addPacket(handlerType, packetName) {
         const declared = (0, Attributes_1.readZLinkDecoratorMetadata)(handlerType).find((entry) => entry.kind === 'packet')?.packetName;
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
+        const resolvedPacketName = packetName ?? declared ?? handlerType.name;
+        if (this.entries.some((entry) => entry.kind === 'packet' && entry.packetName === resolvedPacketName))
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `SPOT packet '${resolvedPacketName}' is already registered.`);
         this.entries.push({
             kind: 'packet',
             handlerType,
-            packetName: packetName ?? declared ?? handlerType.name
+            packetName: resolvedPacketName
         });
         return this;
     }
@@ -40,6 +47,7 @@ class DefaultZLinkSpotHandlerRegistry {
         return this.addPacket(handlerType, packetName);
     }
     addActorPacketRegistration(kind, handlerType, actorType, packetName) {
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({
             kind: kind === actors_1.ZLinkActorPacketKind.Send ? 'actorSend' : 'actorRequest',
             handlerType,
@@ -62,17 +70,18 @@ class DefaultZLinkSpotHandlerRegistry {
     }
     addSubscribe(handlerType, channelName, topic) {
         if (channelName.trim().length === 0) {
-            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe channel name must not be empty.');
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'SPOT subscribe channel name must not be empty.');
         }
         if (topic.trim().length === 0) {
-            throw new configuration_1.ZLinkConfigurationException('SPOT subscribe topic must not be empty.');
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, 'SPOT subscribe topic must not be empty.');
         }
         if (this.entries.some((entry) => entry.kind === 'subscribe' &&
             entry.handlerType === handlerType &&
             entry.channelName === channelName &&
             entry.topic === topic)) {
-            return this;
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `SPOT subscription '${channelName}/${topic}' is already registered.`);
         }
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({ kind: 'subscribe', handlerType, channelName, topic });
         return this;
     }
@@ -80,6 +89,7 @@ class DefaultZLinkSpotHandlerRegistry {
         return this.addSubscribe(handlerType, channelName, topic);
     }
     addSpotHandler(handlerType) {
+        (0, handler_instance_scope_1.prepareHandlerInstance)(this.providerResolver, handlerType);
         this.entries.push({ kind: 'spotHandler', handlerType });
         return this;
     }

package/dist/runtime/spots/spot-node-autoconnect.js

@@ -105,16 +105,17 @@ class ZLinkSpotNodeAutoConnectExecutor {
         this.node.onPeerDisconnected?.(handler);
     }
     async connect(target) {
-        if (this.manualConnections)
-            return false;
         const key = connectionKey(target);
+        if (!this.connectionIntents.has(key) &&
+            this.node.hasPeerRouteOrConnectionIntent?.(target.nodeRid, target.endpoint) === true)
+            return false;
         const intent = await this.lane.run(() => this.prepareConnectCore(key));
         if (intent === undefined)
             return true;
         return await runDetachedSpotNodeAutoConnect(() => this.connectPeer(target, key, intent));
     }
     disconnect(target) {
-        if (this.manualConnections)
+        if (!this.connectionIntents.has(connectionKey(target)))
             return;
         this.disconnectPeer(target);
     }

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

@@ -1,3 +1,4 @@
+import type { ApplicationJobOrigin } from '../application-jobs/contracts';
 import { type ActorRef, type RoutingId, type ZLinkActor, type ZLinkChannelClient, type ZLinkFanoutClient, type ZLinkMeshNodeDescriptor, type ZLinkMessage, type ZLinkMessageSerializer, type ZLinkSpotPublisherClient, ZLinkFrameworkRuntimeState } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
 import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
@@ -116,7 +117,7 @@ export declare class ZLinkSpotNodeRuntimeManager {
     private ensureEntryActivation;
     private initializeEntrySpot;
     private primaryEntryActivation;
-    dispatchEntryActorPacket(actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
+    dispatchEntryActorPacket(origin: ApplicationJobOrigin, actorId: string, parts: readonly Message[], returnResponse?: boolean, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, fallbackActorRef?: ActorRef, requestTerminal?: (response: unknown) => Promise<void> | void, messageFollowOrigin?: ZLinkMessageFollowOrigin): Promise<unknown>;
     dispatchEntryActorJoin(meshName: string, actor: ZLinkActor, handoffBacklog?: readonly ZLinkActorHandoffPacket[]): Promise<void>;
     executeEntryActor<T>(meshName: string, actorId: string, operation: () => Promise<T>): Promise<T>;
     publish(meshName: string, channelName: string, topic: string, packetName: string | undefined, event: Message, signal?: AbortSignal, metadata?: ReadonlyMap<string, string>): Promise<ZLinkSubmitResult>;

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

@@ -17,7 +17,6 @@ const channel_clients_1 = require("../channels/channel-clients");
 const channel_envelope_1 = require("../channels/channel-envelope");
 const configuration_1 = require("../configuration");
 const flow_context_1 = require("../diagnostics/flow-context");
-const execution_1 = require("../execution");
 const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
 const framework_errors_internal_1 = require("../framework-errors-internal");
 const application_job_queue_1 = require("../host/application-job-queue");
@@ -146,6 +145,7 @@ class ZLinkSpotNodeRuntimeManager {
                 routingId,
                 receiveTimeoutMs: spotNode.router?.receiveTimeoutMs,
                 applicationJobQueue: this.applicationJobQueue,
+                infrastructureTaskRunner: this.options.detachedTaskRunner,
                 applicationJobReceiveFlowFailureSink: this.options.applicationJobReceiveFlowFailureSink,
                 peerAdmissionSealed: () => this.options.peerAdmissionSealed?.(spotNodeName) ?? false
             });
@@ -177,6 +177,7 @@ class ZLinkSpotNodeRuntimeManager {
             let pump;
             const completions = new mesh_completion_table_1.ZLinkMeshCompletionTable();
             try {
+                node.setCompletionHandler((terminal, materialize) => completions.complete(terminal, materialize));
                 node.setBind(bind);
                 if (spotNode.router?.advertiseHost !== undefined) {
                     node.setAdvertiseHost(spotNode.router.advertiseHost);
@@ -604,15 +605,6 @@ class ZLinkSpotNodeRuntimeManager {
         this.meshCompletions.clear();
     }
     async dispatchMeshRecord(meshName, owner, record) {
-        if (record.kind === service_runtime_contracts_1.ReceiveKind.Completion) {
-            (0, execution_1.requireZLinkInfrastructureExecutionArea)();
-            const completions = this.meshCompletions.get(meshName);
-            if (completions === undefined) {
-                throw new configuration_1.ZLinkConfigurationException(`MeshNode '${meshName}' received a completion before its completion table was registered.`);
-            }
-            completions.complete(record);
-            return;
-        }
         const node = this.meshNodes.get(meshName);
         const targetsEntrySpot = owner.spotId === null ||
             (node !== undefined &&
@@ -745,7 +737,7 @@ class ZLinkSpotNodeRuntimeManager {
     primaryEntryActivation() {
         return this.entryActivations.values().next().value;
     }
-    async dispatchEntryActorPacket(actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
+    async dispatchEntryActorPacket(origin, actorId, parts, returnResponse = false, remoteBoundSessionTarget, fallbackActorRef, requestTerminal, messageFollowOrigin) {
         let activation = this.primaryEntryActivation();
         if (activation === undefined) {
             const candidates = this.options.primaryMeshName === undefined
@@ -774,6 +766,7 @@ class ZLinkSpotNodeRuntimeManager {
             throw new configuration_1.ZLinkConfigurationException('Entry Spot actor packet dispatch requires an Entry Spot.');
         }
         return await activation.dispatchActorPacket({
+            origin,
             actorId,
             parts,
             returnResponse,

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

@@ -35,6 +35,7 @@ export declare class DefaultZLinkSpotOutbound implements ZLinkSpotOutbound {
     private requireAddressTransport;
 }
 export interface ZLinkSpotAddressCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly instanceSpot: boolean;
     readonly instanceSpotType?: string;
@@ -63,10 +64,12 @@ export interface ZLinkSpotRoutedSendOptions {
     readonly metadata?: ReadonlyMap<string, string>;
 }
 export interface ZLinkSpotRoutedRequestOptions extends ZLinkSpotRoutedSendOptions {
+    readonly onAdmitted?: () => void;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;
 }
 export interface ZLinkSpotHandleCallOptions {
+    readonly onAdmitted?: () => void;
     readonly metadata?: ReadonlyMap<string, string>;
     readonly timeoutMs?: number;
     readonly signal?: AbortSignal;