@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/actors/index.js

@@ -1,23 +1,28 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DefaultZLinkActorManager = exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = exports.createActorMembership = exports.createActorJoinRequest = exports.actorJoinIdentity = exports.ZLinkRemoteBoundSessionFenceError = exports.isRemoteBoundSessionFenceError = exports.encodeRemoteBoundSessionNack = exports.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE = exports.ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET = exports.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = exports.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = exports.decodeRemoteActorSourceLeaveTerminal = exports.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL = exports.ZLINK_REMOTE_ACTOR_JOIN_PACKET = exports.ZLinkActorTransferRegistry = exports.ZLinkActorNativeJoinCoordinator = exports.ZLinkSpotActorHandlerRegistryRuntime = exports.ZLinkSpotActorDispatcher = exports.ZLinkActorPacketKind = exports.publishInitialActorAuthority = exports.rewriteActorAuthorityOwner = exports.rewriteActorAuthorityRoute = exports.isActorAuthorityPayload = exports.encodeActorAuthorityIdentity = exports.decodeRelocatingActorAuthorityIdentity = exports.decodeActorAuthorityIdentity = exports.ZLinkDeferredJoinAcceptedJournal = exports.isDeferredJoinAcceptedRootPublication = exports.toFrameworkRoutingId = exports.toFrameworkActorRef = exports.preferredRemoteBoundSessionTarget = exports.mergeRemoteBoundSessionTarget = exports.ZLinkActorRuntimeState = exports.decodeActorMessageFollowContext = exports.attachActorMessageFollowContext = exports.actorMessageFollowContext = exports.decodeHandoffPacket = exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = exports.ZLinkActorSerialExecutor = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = exports.DefaultZLinkActorContext = exports.forwardEncodedActorPacket = exports.DefaultZLinkActorClient = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
+exports.DefaultZLinkActorManager = exports.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT = exports.createActorMembership = exports.createActorJoinRequest = exports.actorJoinIdentity = exports.ZLinkRemoteBoundSessionFenceError = exports.isRemoteBoundSessionFenceError = exports.encodeRemoteBoundSessionNack = exports.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET = exports.ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE = exports.ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET = exports.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET = exports.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET = exports.decodeRemoteActorSourceLeaveTerminal = exports.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL = exports.ZLINK_REMOTE_ACTOR_JOIN_PACKET = exports.ZLinkActorTransferRegistry = exports.ZLinkActorNativeJoinCoordinator = exports.ZLinkSpotActorHandlerRegistryRuntime = exports.ZLinkSpotActorDispatcher = exports.ZLinkActorPacketKind = exports.publishInitialActorAuthority = exports.rewriteActorAuthorityOwner = exports.rewriteActorAuthorityRoute = exports.isActorAuthorityPayload = exports.encodeActorAuthorityIdentity = exports.decodeRelocatingActorAuthorityIdentity = exports.decodeActorAuthorityIdentity = exports.createDeferredJoinCompletion = exports.toFrameworkRoutingId = exports.toFrameworkActorRef = exports.ZLinkActorRuntimeState = exports.decodeActorMessageFollowContext = exports.attachActorMessageFollowContext = exports.actorMessageFollowContext = exports.decodeHandoffPacket = exports.ZLinkActorHandoffCoordinator = exports.DEFAULT_MESSAGE_FOLLOW_DURATION_MS = exports.ZLinkActorSerialExecutor = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = exports.DefaultZLinkActorContext = exports.forwardEncodedActorPacket = exports.DefaultZLinkActorClient = void 0;
 const contracts_1 = require("../../contracts");
-const runtime_message_1 = require("../backend/runtime-message");
-const contracts_2 = require("../../contracts");
-const configuration_1 = require("../configuration");
+const Registration_1 = require("../../contracts/Configuration/Registration");
 const abort_1 = require("../abort");
 const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const runtime_message_1 = require("../backend/runtime-message");
+const configuration_1 = require("../configuration");
+const runtime_metrics_1 = require("../diagnostics/runtime-metrics");
 const execution_1 = require("../execution");
+const framework_errors_internal_1 = require("../framework-errors-internal");
 const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const payload_codec_1 = require("../messaging/payload-codec");
+const actor_creation_1 = require("./actor-creation");
+const actor_runtime_state_1 = require("./actor-runtime-state");
+const transferred_actor_rollback_1 = require("./transferred-actor-rollback");
+const ACTOR_CREATION_RETRY_INTERVAL_MS = 5;
+const LOCAL_DIAGNOSTIC_NODE_RID = 'local';
 var actor_client_1 = require("./actor-client");
 Object.defineProperty(exports, "DefaultZLinkActorClient", { enumerable: true, get: function () { return actor_client_1.DefaultZLinkActorClient; } });
 Object.defineProperty(exports, "forwardEncodedActorPacket", { enumerable: true, get: function () { return actor_client_1.forwardEncodedActorPacket; } });
-const payload_codec_1 = require("../messaging/payload-codec");
 var actor_context_1 = require("./actor-context");
 Object.defineProperty(exports, "DefaultZLinkActorContext", { enumerable: true, get: function () { return actor_context_1.DefaultZLinkActorContext; } });
 Object.defineProperty(exports, "ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME", { enumerable: true, get: function () { return actor_context_1.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME; } });
-const actor_creation_1 = require("./actor-creation");
 var actor_mailbox_1 = require("./actor-mailbox");
 Object.defineProperty(exports, "ZLinkActorSerialExecutor", { enumerable: true, get: function () { return actor_mailbox_1.ZLinkActorSerialExecutor; } });
 var actor_handoff_1 = require("./actor-handoff");
@@ -28,15 +33,12 @@ var actor_message_follow_context_1 = require("./actor-message-follow-context");
 Object.defineProperty(exports, "actorMessageFollowContext", { enumerable: true, get: function () { return actor_message_follow_context_1.actorMessageFollowContext; } });
 Object.defineProperty(exports, "attachActorMessageFollowContext", { enumerable: true, get: function () { return actor_message_follow_context_1.attachActorMessageFollowContext; } });
 Object.defineProperty(exports, "decodeActorMessageFollowContext", { enumerable: true, get: function () { return actor_message_follow_context_1.decodeActorMessageFollowContext; } });
-var actor_runtime_state_1 = require("./actor-runtime-state");
-Object.defineProperty(exports, "ZLinkActorRuntimeState", { enumerable: true, get: function () { return actor_runtime_state_1.ZLinkActorRuntimeState; } });
-Object.defineProperty(exports, "mergeRemoteBoundSessionTarget", { enumerable: true, get: function () { return actor_runtime_state_1.mergeRemoteBoundSessionTarget; } });
-Object.defineProperty(exports, "preferredRemoteBoundSessionTarget", { enumerable: true, get: function () { return actor_runtime_state_1.preferredRemoteBoundSessionTarget; } });
-Object.defineProperty(exports, "toFrameworkActorRef", { enumerable: true, get: function () { return actor_runtime_state_1.toFrameworkActorRef; } });
-Object.defineProperty(exports, "toFrameworkRoutingId", { enumerable: true, get: function () { return actor_runtime_state_1.toFrameworkRoutingId; } });
-var deferred_join_accepted_journal_1 = require("./deferred-join-accepted-journal");
-Object.defineProperty(exports, "isDeferredJoinAcceptedRootPublication", { enumerable: true, get: function () { return deferred_join_accepted_journal_1.isDeferredJoinAcceptedRootPublication; } });
-Object.defineProperty(exports, "ZLinkDeferredJoinAcceptedJournal", { enumerable: true, get: function () { return deferred_join_accepted_journal_1.ZLinkDeferredJoinAcceptedJournal; } });
+var actor_runtime_state_2 = require("./actor-runtime-state");
+Object.defineProperty(exports, "ZLinkActorRuntimeState", { enumerable: true, get: function () { return actor_runtime_state_2.ZLinkActorRuntimeState; } });
+Object.defineProperty(exports, "toFrameworkActorRef", { enumerable: true, get: function () { return actor_runtime_state_2.toFrameworkActorRef; } });
+Object.defineProperty(exports, "toFrameworkRoutingId", { enumerable: true, get: function () { return actor_runtime_state_2.toFrameworkRoutingId; } });
+var deferred_join_completion_1 = require("./deferred-join-completion");
+Object.defineProperty(exports, "createDeferredJoinCompletion", { enumerable: true, get: function () { return deferred_join_completion_1.createDeferredJoinCompletion; } });
 var actor_authority_publication_1 = require("./actor-authority-publication");
 Object.defineProperty(exports, "decodeActorAuthorityIdentity", { enumerable: true, get: function () { return actor_authority_publication_1.decodeActorAuthorityIdentity; } });
 Object.defineProperty(exports, "decodeRelocatingActorAuthorityIdentity", { enumerable: true, get: function () { return actor_authority_publication_1.decodeRelocatingActorAuthorityIdentity; } });
@@ -45,14 +47,12 @@ Object.defineProperty(exports, "isActorAuthorityPayload", { enumerable: true, ge
 Object.defineProperty(exports, "rewriteActorAuthorityRoute", { enumerable: true, get: function () { return actor_authority_publication_1.rewriteActorAuthorityRoute; } });
 Object.defineProperty(exports, "rewriteActorAuthorityOwner", { enumerable: true, get: function () { return actor_authority_publication_1.rewriteActorAuthorityOwner; } });
 Object.defineProperty(exports, "publishInitialActorAuthority", { enumerable: true, get: function () { return actor_authority_publication_1.publishInitialActorAuthority; } });
-const actor_runtime_state_2 = require("./actor-runtime-state");
 var spot_actor_dispatch_1 = require("./spot-actor-dispatch");
 Object.defineProperty(exports, "ZLinkActorPacketKind", { enumerable: true, get: function () { return spot_actor_dispatch_1.ZLinkActorPacketKind; } });
 Object.defineProperty(exports, "ZLinkSpotActorDispatcher", { enumerable: true, get: function () { return spot_actor_dispatch_1.ZLinkSpotActorDispatcher; } });
 Object.defineProperty(exports, "ZLinkSpotActorHandlerRegistryRuntime", { enumerable: true, get: function () { return spot_actor_dispatch_1.ZLinkSpotActorHandlerRegistryRuntime; } });
 var actor_remote_joiner_1 = require("./actor-remote-joiner");
 Object.defineProperty(exports, "ZLinkActorNativeJoinCoordinator", { enumerable: true, get: function () { return actor_remote_joiner_1.ZLinkActorNativeJoinCoordinator; } });
-const transferred_actor_rollback_1 = require("./transferred-actor-rollback");
 var actor_transfer_registry_1 = require("./actor-transfer-registry");
 Object.defineProperty(exports, "ZLinkActorTransferRegistry", { enumerable: true, get: function () { return actor_transfer_registry_1.ZLinkActorTransferRegistry; } });
 var actor_remote_wire_1 = require("./actor-remote-wire");
@@ -77,15 +77,20 @@ Object.defineProperty(exports, "createActorMembership", { enumerable: true, get:
 Object.defineProperty(exports, "ZLINK_ACTOR_LIFECYCLE_SNAPSHOT", { enumerable: true, get: function () { return actor_lifecycle_snapshot_1.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT; } });
 class DefaultZLinkActorManager {
     options;
+    detachedTaskRunner;
     states = new Map();
     actorMeshNames = new Map();
     relocationStaged = new Set();
     creation;
     transferredActorRollback;
-    constructor(options) {
+    constructor(options, detachedTaskRunner) {
         this.options = options;
+        this.detachedTaskRunner = detachedTaskRunner;
+        if (detachedTaskRunner === undefined) {
+            throw new Error('Actor manager requires a detached task runner.');
+        }
         this.creation = new actor_creation_1.ZLinkActorCreationCoordinator(options);
-        this.transferredActorRollback = new transferred_actor_rollback_1.ZLinkTransferredActorRollbackCoordinator(this.states, options);
+        this.transferredActorRollback = new transferred_actor_rollback_1.ZLinkTransferredActorRollbackCoordinator(this.states, options, (actorId, state) => this.finalizeDestroyedActor(actorId, state));
     }
     create(actorId, actorType) {
         return new ZLinkActorCreateCallRuntime((options, signal) => this.submitCreate(actorId, actorType, true, options, signal));
@@ -129,7 +134,6 @@ class DefaultZLinkActorManager {
         if (state.isMoving) {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving, `Actor '${actor.actorId}' is relocating.`);
         }
-        const actorInstance = state.actor;
         const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
         const completions = this.options.nativeActorCompletionTableProvider?.();
         const entryNodeRid = state.entryNodeRid ?? current.nodeRid;
@@ -156,14 +160,7 @@ class DefaultZLinkActorManager {
             if (state.actorType !== undefined && state.ownsLocation) {
                 await this.options.locationLifecycle?.releaseActor(state.actorType, actor.actorId, current);
             }
-            this.options.actorDestroyedCleanup?.(actor.actorId);
-            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(actorInstance);
-            state.clearAfterDestroy();
-            if (this.states.get(actor.actorId) === state) {
-                this.states.delete(actor.actorId);
-                this.actorMeshNames.delete(actor.actorId);
-            }
-            this.options.metrics?.change('zlink.actor.count', -1);
+            await this.finalizeDestroyedActor(actor.actorId, state);
         });
         try {
             await destroyTask;
@@ -179,7 +176,7 @@ class DefaultZLinkActorManager {
         const state = this.getOrCreateState(actorId);
         this.rememberActorMeshFromType(actorId, actorType);
         if (state.actor !== undefined) {
-            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor);
+            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor, this.detachedTaskRunner);
         }
         state.prepareForRemoteReentry();
         const operation = state.getOrStartCreation(actorType, false, () => this.creation.materializeTransferredActor(actorId, actorType, state, adapterKey === undefined
@@ -285,7 +282,7 @@ class DefaultZLinkActorManager {
         this.relocationStaged.add(actorId);
         let nativeRef;
         try {
-            nativeRef = restore.call(node, actorId, actorType, objectGeneration, authorityOwnerGeneration, String(spotId), spotGeneration, membershipEpoch);
+            nativeRef = restore.call(node, actorId, actorType, objectGeneration, authorityOwnerGeneration, spotId === undefined ? undefined : String(spotId), spotGeneration, membershipEpoch);
             this.rememberActorMeshFromType(actorId, actorType);
             const state = this.getOrCreateState(actorId);
             state.setNativeActorRef(nativeRef);
@@ -303,7 +300,8 @@ class DefaultZLinkActorManager {
                 await registry.restore(transfer.adapterKey, actor, transfer.state, signal);
             }
             state.setLocationGeneration(authorityOwnerGeneration);
-            state.setJoinedSpot(spotId, undefined, membershipEpoch);
+            if (spotId !== undefined)
+                state.setJoinedSpot(spotId, undefined, membershipEpoch);
             return actor;
         }
         catch (error) {
@@ -311,12 +309,7 @@ class DefaultZLinkActorManager {
                 node.discardRelocatedActor?.(nativeRef);
             this.relocationStaged.delete(actorId);
             const failedState = this.states.get(actorId);
-            if (failedState?.actor !== undefined) {
-                await (0, handler_instance_scope_1.disposeLifecycleHandlers)(failedState.actor);
-            }
-            failedState?.clearAfterDestroy();
-            this.states.delete(actorId);
-            this.actorMeshNames.delete(actorId);
+            await this.finalizeActorState(actorId, failedState);
             throw error;
         }
     }
@@ -336,26 +329,57 @@ class DefaultZLinkActorManager {
         const state = this.states.get(actorId);
         const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
         const nativeActorRef = exactNativeActorRef ?? state?.nativeActorRef;
-        if (nativeActorRef !== undefined) {
-            node?.discardRelocatedActor?.(nativeActorRef);
+        const failures = [];
+        try {
+            if (nativeActorRef !== undefined) {
+                node?.discardRelocatedActor?.(nativeActorRef);
+            }
         }
-        if (state?.actor !== undefined) {
-            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor);
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await this.completeCoreRelocationSource(actorId);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        if (failures.length > 0) {
+            throw failures.length === 1
+                ? failures[0]
+                : new AggregateError(failures, 'Actor relocation cleanup failed.');
         }
-        state?.clearAfterDestroy();
-        this.states.delete(actorId);
-        this.actorMeshNames.delete(actorId);
-        this.relocationStaged.delete(actorId);
     }
     async completeCoreRelocationSource(actorId) {
         const state = this.states.get(actorId);
-        if (state?.actor !== undefined) {
-            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor);
+        await this.finalizeActorState(actorId, state);
+    }
+    async finalizeActorState(actorId, state) {
+        if (state === undefined || this.states.get(actorId) !== state)
+            return;
+        try {
+            if (state.actor !== undefined)
+                await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor, this.detachedTaskRunner);
+        }
+        finally {
+            state.clearAfterDestroy();
+            if (this.states.get(actorId) === state) {
+                this.states.delete(actorId);
+                this.actorMeshNames.delete(actorId);
+                this.relocationStaged.delete(actorId);
+            }
+        }
+    }
+    async finalizeDestroyedActor(actorId, state) {
+        if (this.states.get(actorId) !== state)
+            return;
+        try {
+            this.options.actorDestroyedCleanup?.(actorId);
+        }
+        finally {
+            await this.finalizeActorState(actorId, state);
+            this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.ActorCount, -1);
         }
-        state?.clearAfterDestroy();
-        this.states.delete(actorId);
-        this.actorMeshNames.delete(actorId);
-        this.relocationStaged.delete(actorId);
     }
     async getOrCreateActor(actorId, actorType, signal) {
         this.rememberActorMeshFromType(actorId, actorType);
@@ -375,7 +399,7 @@ class DefaultZLinkActorManager {
     }
     async createReservedActorResult(actorId, actorType, createRequest, signal, nativeActorRef) {
         this.rememberActorMeshFromType(actorId, actorType);
-        return await this.createOrGet(actorId, actorType, false, createRequest, signal, false, 30_000, nativeActorRef);
+        return await this.createOrGet(actorId, actorType, false, createRequest, signal, false, Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef);
     }
     adoptCreatedAuthority(actorId, authorityOwnerGeneration, ownerLeaseGeneration) {
         const state = this.states.get(actorId);
@@ -406,7 +430,7 @@ class DefaultZLinkActorManager {
             throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.context.actorId}' must leave its current SPOT before destroy.`);
         }
         const destroyTask = state.getOrStartDestroy(entryNodeRid, async (actorRef) => {
-            const destroyedActorRef = actorRef === undefined ? undefined : (0, actor_runtime_state_2.toFrameworkActorRef)(actorRef, state.meshName ?? '');
+            const destroyedActorRef = actorRef === undefined ? undefined : (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, state.meshName ?? '');
             if (actorRef !== undefined) {
                 await node.destroyActor(actorRef, 0, destroySignal);
                 state.markNativeActorDestroyed(actorRef);
@@ -414,14 +438,7 @@ class DefaultZLinkActorManager {
             if (state.actorType !== undefined && state.ownsLocation) {
                 await this.options.locationLifecycle?.releaseActor(state.actorType, actor.context.actorId, destroyedActorRef);
             }
-            this.options.actorDestroyedCleanup?.(actor.context.actorId);
-            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(actor);
-            state.clearAfterDestroy();
-            if (this.states.get(actor.context.actorId) === state) {
-                this.states.delete(actor.context.actorId);
-                this.actorMeshNames.delete(actor.context.actorId);
-            }
-            this.options.metrics?.change('zlink.actor.count', -1);
+            await this.finalizeDestroyedActor(actor.context.actorId, state);
         });
         try {
             await destroyTask;
@@ -431,7 +448,7 @@ class DefaultZLinkActorManager {
             throw error;
         }
     }
-    async createOrGet(actorId, actorType, failIfExists, request, signal, claimLocation = true, timeoutMs = 30_000, nativeActorRef) {
+    async createOrGet(actorId, actorType, failIfExists, request, signal, claimLocation = true, timeoutMs = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS, nativeActorRef) {
         const deadline = performance.now() + timeoutMs;
         const requestedMeshName = this.actorMeshNames.get(actorId);
         for (;;) {
@@ -451,7 +468,18 @@ class DefaultZLinkActorManager {
             if (request !== undefined && createRequest.nativeRequest !== undefined) {
                 state.setCreateRequestPayload(createRequest.nativeRequest.data());
             }
-            const operation = state.getOrStartCreation(actorType, failIfExists, () => this.creation.createActor(actorId, actorType, state, createRequest, claimLocation, signal));
+            const operation = state.getOrStartCreation(actorType, failIfExists, async () => {
+                const meshName = state.meshName ?? this.options.actorMeshNameProvider?.(actorType);
+                const release = meshName === undefined
+                    ? undefined
+                    : await this.options.activationAdmission?.acquire(meshName, signal);
+                try {
+                    return await this.creation.createActor(actorId, actorType, state, createRequest, claimLocation, signal);
+                }
+                finally {
+                    release?.();
+                }
+            });
             if (operation.created) {
                 void operation.task.then((result) => {
                     if (result.status !== 'created') {
@@ -499,7 +527,7 @@ class DefaultZLinkActorManager {
         if (this.states.get(actorId) === state) {
             this.states.delete(actorId);
             this.actorMeshNames.delete(actorId);
-            this.options.metrics?.change('zlink.actor.count', -1);
+            this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.ActorCount, -1);
         }
     }
     createRequestMessage(request) {
@@ -507,13 +535,13 @@ class DefaultZLinkActorManager {
             const empty = runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0));
             return {
                 nativeRequest: empty,
-                callbackRequest: contracts_2.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(empty.data()))
+                callbackRequest: contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(empty.data()))
             };
         }
         const nativeRequest = (0, payload_codec_1.encodeFrameworkPayloadMessage)(request, this.options.messageSerializers);
         return {
             nativeRequest,
-            callbackRequest: contracts_2.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(nativeRequest.data()))
+            callbackRequest: contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(nativeRequest.data()))
         };
     }
     getOrCreateState(actorId) {
@@ -521,25 +549,25 @@ class DefaultZLinkActorManager {
         if (existing !== undefined) {
             return existing;
         }
-        const state = new actor_runtime_state_2.ZLinkActorRuntimeState(actorId);
+        const state = new actor_runtime_state_1.ZLinkActorRuntimeState(actorId);
         const remembered = this.actorMeshNames.get(actorId);
         if (remembered !== undefined) {
             state.rememberMeshName(remembered);
         }
         this.states.set(actorId, state);
-        this.options.metrics?.change('zlink.actor.count', 1);
+        this.options.metrics?.change(runtime_metrics_1.METRIC_NAMES.ActorCount, 1);
         return state;
     }
     actorRefForState(state) {
         const nativeActorRef = state.nativeActorRef;
         if (nativeActorRef !== undefined) {
-            return (0, actor_runtime_state_2.toFrameworkActorRef)(nativeActorRef, state.meshName ?? '');
+            return (0, actor_runtime_state_1.toFrameworkActorRef)(nativeActorRef, state.meshName ?? '');
         }
         return {
             actorId: state.actorId,
             objectGeneration: 1n,
             meshName: state.meshName ?? '',
-            nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? 'local'
+            nodeRid: this.options.actorCreatedNodeRidProvider?.() ?? LOCAL_DIAGNOSTIC_NODE_RID
         };
     }
 }
@@ -549,7 +577,7 @@ class ZLinkActorCreateCallRuntime {
     meshNameValue;
     requestValue;
     requestConfigured = false;
-    timeoutMsValue = 30_000;
+    timeoutMsValue = Registration_1.DEFAULT_REQUEST_TIMEOUT_MS;
     timeoutConfigured = false;
     submitted = false;
     turn = (0, execution_1.captureZLinkSpotSerialTurn)();
@@ -633,7 +661,7 @@ async function waitForCreationRetry(signal) {
             else
                 reject(error);
         };
-        const timer = setTimeout(() => finish(), 5);
+        const timer = setTimeout(() => finish(), ACTOR_CREATION_RETRY_INTERVAL_MS);
         const onAbort = () => {
             finish(signal?.reason ?? new Error('Actor creation was aborted.'));
         };

package/dist/runtime/actors/spot-actor-dispatch.d.ts

@@ -1,7 +1,6 @@
-import type { Type, ZLinkActor, ZLinkActorHandlerRegistry, ZLinkSpot, ZLinkSpotActorJoinResult, ZLinkMessageContext } from '../../contracts';
-import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { type Type, type ZLinkActor, type ZLinkActorHandlerRegistry, type ZLinkMessageContext, type ZLinkMessageSerializer, type ZLinkSpot, type ZLinkSpotActorJoinResult } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkMessageSerializer } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
 import type { ZLinkSerialWorkOptions } from '../execution/serial-execution-queue';
 export declare enum ZLinkActorPacketKind {
     Send = "send",
@@ -12,6 +11,7 @@ export interface ZLinkActorPacketDescriptor {
     readonly packetName: string;
     readonly actorType: Type<ZLinkActor>;
     readonly handlerType: Type;
+    readonly methodName?: string;
 }
 export declare class ZLinkSpotActorHandlerRegistryRuntime implements ZLinkActorHandlerRegistry {
     private readonly packets;

package/dist/runtime/actors/spot-actor-dispatch.js

@@ -1,14 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkSpotActorDispatcher = exports.ZLinkSpotActorHandlerRegistryRuntime = exports.ZLinkActorPacketKind = void 0;
-const framework_errors_internal_1 = require("../framework-errors-internal");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
 const contracts_1 = require("../../contracts");
-const configuration_1 = require("../configuration");
 const Attributes_1 = require("../../contracts/Handlers/Attributes");
+const configuration_1 = require("../configuration");
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
 const payload_codec_1 = require("../messaging/payload-codec");
-const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
 const actor_join_deferred_scope_1 = require("./actor-join-deferred-scope");
-const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
 var ZLinkActorPacketKind;
 (function (ZLinkActorPacketKind) {
     ZLinkActorPacketKind["Send"] = "send";
@@ -28,7 +29,8 @@ class ZLinkSpotActorHandlerRegistryRuntime {
                 : ZLinkActorPacketKind.Request,
             packetName: resolvedPacketName,
             actorType: Object,
-            handlerType
+            handlerType,
+            methodName: metadata.methodName
         });
     }
     addPacket(descriptor) {
@@ -36,7 +38,13 @@ class ZLinkSpotActorHandlerRegistryRuntime {
         if (this.packets.has(key)) {
             throw new configuration_1.ZLinkConfigurationException(`Actor packet '${descriptor.packetName}' for '${descriptor.actorType.name}' is already registered.`);
         }
-        this.packets.set(key, descriptor);
+        const metadata = (0, Attributes_1.readZLinkDecoratorMetadata)(descriptor.handlerType).find((entry) => entry.kind ===
+            (descriptor.kind === ZLinkActorPacketKind.Send ? 'spotActorSend' : 'spotActorRequest') &&
+            entry.packetName === descriptor.packetName);
+        this.packets.set(key, {
+            ...descriptor,
+            methodName: descriptor.methodName ?? metadata?.methodName
+        });
         return this;
     }
     resolvePacket(kind, actor, packetName) {
@@ -73,7 +81,7 @@ class ZLinkSpotActorDispatcher {
             const descriptor = this.requirePacket(ZLinkActorPacketKind.Send, actor, packetName);
             const message = decode();
             this.options.onHandlerStart?.();
-            await this.invokeHandler(actor, descriptor, (handler) => (0, actor_join_deferred_scope_1.runActorHandlerWithDeferredJoins)(() => handler.handle(this.options.spot, actor, this.createContext(packetName, context), message)));
+            await this.invokeHandler(actor, descriptor, (handler, method) => (0, actor_join_deferred_scope_1.runActorHandlerWithDeferredJoins)(() => method.call(handler, this.options.spot, actor, this.createContext(packetName, context), message)));
         });
     }
     dispatchRequest(actor, packetName, request, context = {}) {
@@ -90,7 +98,7 @@ class ZLinkSpotActorDispatcher {
             const descriptor = this.requirePacket(ZLinkActorPacketKind.Request, actor, packetName);
             const request = decode();
             this.options.onHandlerStart?.();
-            return await this.invokeHandler(actor, descriptor, (handler) => (0, actor_join_deferred_scope_1.runActorHandlerWithDeferredJoins)(() => handler.handle(this.options.spot, actor, this.createContext(packetName, context), request), (reply) => afterReply(reply, {
+            return await this.invokeHandler(actor, descriptor, (handler, method) => (0, actor_join_deferred_scope_1.runActorHandlerWithDeferredJoins)(() => method.call(handler, this.options.spot, actor, this.createContext(packetName, context), request), (reply) => afterReply(reply, {
                 metadata: new Map(),
                 compressPayload: false
             }), beforeReply === undefined
@@ -109,7 +117,7 @@ class ZLinkSpotActorDispatcher {
             return result;
         });
     }
-    evaluateActorJoin(actor, request, contentType = 'application/json') {
+    evaluateActorJoin(actor, request, contentType = stream_wire_1.ZlinkStreamContentType.Json) {
         return this.execute(async () => {
             const payload = (0, payload_codec_1.wrapFrameworkPayloadMessage)(request, this.options.messageSerializers, contentType);
             const onActorJoin = this.options.spot.onActorJoin;
@@ -151,7 +159,14 @@ class ZLinkSpotActorDispatcher {
         throw actorDispatchHandlerNotFound(`Actor handler '${descriptor.handlerType.name}' expects actor '${descriptor.actorType.name}'.`);
     }
     async invokeHandler(actor, descriptor, callback) {
-        return await (0, handler_instance_scope_1.runWithLifecycleHandler)(actor, descriptor.handlerType, this.options.providerResolver, (resolved) => callback(resolved));
+        return await (0, handler_instance_scope_1.runWithLifecycleHandler)(actor, descriptor.handlerType, this.options.providerResolver, (resolved) => {
+            const methodName = descriptor.methodName ?? 'handle';
+            const method = resolved[methodName];
+            if (typeof method !== 'function') {
+                throw new configuration_1.ZLinkConfigurationException(`Actor handler '${descriptor.handlerType.name}.${methodName}' is not callable.`);
+            }
+            return callback(resolved, method);
+        });
     }
     execute(operation) {
         const pending = this.options.serial?.execute(operation, this.options.serialWorkOptions) ??

package/dist/runtime/actors/transferred-actor-rollback.d.ts

@@ -1,15 +1,13 @@
 import type { ZLinkActor } from '../../contracts';
 import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
 import type { ZLinkActorRuntimeState } from './actor-runtime-state';
-type ZLinkTransferredActorRollbackOptions = Pick<ZLinkActorManagerOptions, 'actorDestroyedCleanup' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'shutdownSignal' | 'metrics'>;
+type ZLinkTransferredActorRollbackOptions = Pick<ZLinkActorManagerOptions, 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider'>;
 export declare class ZLinkTransferredActorRollbackCoordinator {
     private readonly states;
     private readonly options;
-    private readonly tasks;
-    constructor(states: Map<string, ZLinkActorRuntimeState>, options: ZLinkTransferredActorRollbackOptions);
+    private readonly finalize;
+    constructor(states: Map<string, ZLinkActorRuntimeState>, options: ZLinkTransferredActorRollbackOptions, finalize: (actorId: string, state: ZLinkActorRuntimeState) => Promise<void>);
     rollback(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
-    private schedule;
-    private retry;
     private destroyNativeActor;
     private complete;
 }

package/dist/runtime/actors/transferred-actor-rollback.js

@@ -3,14 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkTransferredActorRollbackCoordinator = void 0;
 const backend_1 = require("../backend");
 const runtime_values_1 = require("../backend/runtime-values");
-const actor_retry_delay_1 = require("./actor-retry-delay");
+const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
 class ZLinkTransferredActorRollbackCoordinator {
     states;
     options;
-    tasks = new Map();
-    constructor(states, options) {
+    finalize;
+    constructor(states, options, finalize) {
         this.states = states;
         this.options = options;
+        this.finalize = finalize;
     }
     async rollback(actor, signal) {
         const state = this.states.get(actor.context.actorId);
@@ -23,41 +24,10 @@ class ZLinkTransferredActorRollbackCoordinator {
         }
         const actorRef = state.nativeActorRef;
         const node = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
-        try {
-            if (node !== undefined && actorRef !== undefined) {
-                await this.destroyNativeActor(node, actorRef, signal);
-            }
-        }
-        catch (error) {
-            this.schedule(actor, state, node, actorRef);
-            throw error;
-        }
-        this.complete(actor, state);
-    }
-    schedule(actor, state, node, actorRef) {
-        if (this.tasks.has(actor.context.actorId)) {
-            return;
-        }
-        const task = this.retry(actor, state, node, actorRef).finally(() => this.tasks.delete(actor.context.actorId));
-        this.tasks.set(actor.context.actorId, task);
-    }
-    async retry(actor, state, node, actorRef) {
-        const retryDelay = new actor_retry_delay_1.ZLinkActorRetryDelay();
-        while (this.states.get(actor.context.actorId) === state &&
-            this.options.shutdownSignal?.aborted !== true) {
-            if (!(await retryDelay.wait(this.options.shutdownSignal)))
-                return;
-            try {
-                if (node !== undefined && actorRef !== undefined) {
-                    await this.destroyNativeActor(node, actorRef);
-                }
-                this.complete(actor, state);
-                return;
-            }
-            catch {
-                // The tombstone prevents dispatch while the next retry is pending.
-            }
+        if (node !== undefined && actorRef !== undefined) {
+            await this.destroyNativeActor(node, actorRef, signal);
         }
+        await this.complete(actor, state);
     }
     async destroyNativeActor(node, actorRef, signal) {
         const completions = this.options.nativeActorCompletionTableProvider?.();
@@ -78,14 +48,11 @@ class ZLinkTransferredActorRollbackCoordinator {
             (0, backend_1.closeMeshCompletion)(completion);
         }
     }
-    complete(actor, state) {
+    async complete(actor, state) {
         if (this.states.get(actor.context.actorId) !== state) {
             return;
         }
-        this.options.actorDestroyedCleanup?.(actor.context.actorId);
-        state.clearAfterDestroy();
-        this.states.delete(actor.context.actorId);
-        this.options.metrics?.change('zlink.actor.count', -1);
+        await state.getOrStartDestroy((0, actor_lifecycle_snapshot_1.createActorMembership)(actor).actor.nodeRid, () => this.finalize(actor.context.actorId, state));
     }
 }
 exports.ZLinkTransferredActorRollbackCoordinator = ZLinkTransferredActorRollbackCoordinator;

package/dist/runtime/admission.d.ts

@@ -1,7 +1,13 @@
 import { ZLinkFrameworkInternalErrorKind } from './framework-errors-internal';
+/** 소비한 배열 prefix가 정리 조건에 도달했는지 판정합니다. */
+export declare function shouldCompactBackingArray(head: number, length: number): boolean;
 export declare class ZLinkRuntimeAdmissionGate {
-    private readonly ownerAdmissionOpen;
+    readonly ownerAdmissionOpen: () => boolean;
     private readonly meshes;
+    /**
+     * Location runtime §5: the host's single new-work decision (local admission deadline and host
+     * execution combination). A host without a Location Store has no such block.
+     */
     constructor(ownerAdmissionOpen?: () => boolean);
     get acceptsNewWork(): boolean;
     register(meshName: string): void;

package/dist/runtime/admission.js

@@ -1,10 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkRuntimeAdmissionGate = void 0;
+exports.shouldCompactBackingArray = shouldCompactBackingArray;
 const framework_errors_internal_1 = require("./framework-errors-internal");
+const BACKING_ARRAY_COMPACTION_MIN_HEAD = 1024;
+/** 소비한 배열 prefix가 정리 조건에 도달했는지 판정합니다. */
+function shouldCompactBackingArray(head, length) {
+    return head >= BACKING_ARRAY_COMPACTION_MIN_HEAD && head * 2 >= length;
+}
 class ZLinkRuntimeAdmissionGate {
     ownerAdmissionOpen;
     meshes = new Map();
+    /**
+     * Location runtime §5: the host's single new-work decision (local admission deadline and host
+     * execution combination). A host without a Location Store has no such block.
+     */
     constructor(ownerAdmissionOpen = () => true) {
         this.ownerAdmissionOpen = ownerAdmissionOpen;
     }
@@ -161,7 +171,7 @@ function compactWaiters(state) {
         state.waiters.length = 0;
         state.waiterHead = 0;
     }
-    else if (state.waiterHead >= 1024 && state.waiterHead * 2 >= state.waiters.length) {
+    else if (shouldCompactBackingArray(state.waiterHead, state.waiters.length)) {
         state.waiters.splice(0, state.waiterHead);
         state.waiterHead = 0;
     }

package/dist/runtime/application-jobs/application-job-queue-scope.d.ts

@@ -9,7 +9,7 @@ export declare function releaseApplicationJobPermitBeforeHandler(): void;
 /** True while dispatch already owns the host-wide application job permit. */
 export declare function hasApplicationJobPermit(): boolean;
 /** Re-enters the captured permit scope when a serial executor runs later. */
-export declare function bindApplicationJobPermit<TResult>(callback: () => Promise<TResult> | TResult): () => Promise<TResult> | TResult;
+export declare function bindApplicationJobPermit<TResult, TArgument>(callback: (argument?: TArgument) => Promise<TResult> | TResult): (argument?: TArgument) => Promise<TResult> | TResult;
 /**
  * Transfers the current permit to a detached internal handler turn. The
  * detached owner must release it at handler entry or at a pre-start terminal.

package/dist/runtime/application-jobs/application-job-queue-scope.js

@@ -41,7 +41,7 @@ function bindApplicationJobPermit(callback) {
     const scope = applicationJobPermitScope.getStore();
     if (scope === undefined)
         return callback;
-    return () => applicationJobPermitScope.run(scope, callback);
+    return (argument) => applicationJobPermitScope.run(scope, callback, argument);
 }
 /**
  * Transfers the current permit to a detached internal handler turn. The