@zlink-systems/framework 0.10.0

package/dist/runtime/actors/index.js

@@ -0,0 +1,639 @@
+"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");
+const contracts_1 = require("../../contracts");
+const runtime_message_1 = require("../backend/runtime-message");
+const contracts_2 = require("../../contracts");
+const configuration_1 = require("../configuration");
+const abort_1 = require("../abort");
+const mesh_completion_table_1 = require("../backend/mesh-completion-table");
+const execution_1 = require("../execution");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+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");
+Object.defineProperty(exports, "DEFAULT_MESSAGE_FOLLOW_DURATION_MS", { enumerable: true, get: function () { return actor_handoff_1.DEFAULT_MESSAGE_FOLLOW_DURATION_MS; } });
+Object.defineProperty(exports, "ZLinkActorHandoffCoordinator", { enumerable: true, get: function () { return actor_handoff_1.ZLinkActorHandoffCoordinator; } });
+Object.defineProperty(exports, "decodeHandoffPacket", { enumerable: true, get: function () { return actor_handoff_1.decodeHandoffPacket; } });
+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_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; } });
+Object.defineProperty(exports, "encodeActorAuthorityIdentity", { enumerable: true, get: function () { return actor_authority_publication_1.encodeActorAuthorityIdentity; } });
+Object.defineProperty(exports, "isActorAuthorityPayload", { enumerable: true, get: function () { return actor_authority_publication_1.isActorAuthorityPayload; } });
+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");
+Object.defineProperty(exports, "ZLINK_REMOTE_ACTOR_JOIN_PACKET", { enumerable: true, get: function () { return actor_remote_wire_1.ZLINK_REMOTE_ACTOR_JOIN_PACKET; } });
+Object.defineProperty(exports, "ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL", { enumerable: true, get: function () { return actor_remote_wire_1.ZLINK_REMOTE_ACTOR_SOURCE_LEAVE_TERMINAL; } });
+Object.defineProperty(exports, "decodeRemoteActorSourceLeaveTerminal", { enumerable: true, get: function () { return actor_remote_wire_1.decodeRemoteActorSourceLeaveTerminal; } });
+var actor_packet_relay_wire_1 = require("./actor-packet-relay-wire");
+Object.defineProperty(exports, "ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET", { enumerable: true, get: function () { return actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_PACKET_RELAY_PACKET; } });
+Object.defineProperty(exports, "ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET", { enumerable: true, get: function () { return actor_packet_relay_wire_1.ZLINK_REMOTE_ACTOR_SESSION_DISCONNECTED_PACKET; } });
+var bound_session_wire_1 = require("./bound-session-wire");
+Object.defineProperty(exports, "ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET", { enumerable: true, get: function () { return bound_session_wire_1.ZLINK_REMOTE_BOUND_SESSION_ERROR_PACKET; } });
+Object.defineProperty(exports, "ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE", { enumerable: true, get: function () { return bound_session_wire_1.ZLINK_REMOTE_BOUND_SESSION_FENCE_NACK_CODE; } });
+Object.defineProperty(exports, "ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET", { enumerable: true, get: function () { return bound_session_wire_1.ZLINK_REMOTE_BOUND_SESSION_RESPONSE_PACKET; } });
+Object.defineProperty(exports, "ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET", { enumerable: true, get: function () { return bound_session_wire_1.ZLINK_REMOTE_BOUND_SESSION_SEND_PACKET; } });
+Object.defineProperty(exports, "encodeRemoteBoundSessionNack", { enumerable: true, get: function () { return bound_session_wire_1.encodeRemoteBoundSessionNack; } });
+Object.defineProperty(exports, "isRemoteBoundSessionFenceError", { enumerable: true, get: function () { return bound_session_wire_1.isRemoteBoundSessionFenceError; } });
+Object.defineProperty(exports, "ZLinkRemoteBoundSessionFenceError", { enumerable: true, get: function () { return bound_session_wire_1.ZLinkRemoteBoundSessionFenceError; } });
+var actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
+Object.defineProperty(exports, "actorJoinIdentity", { enumerable: true, get: function () { return actor_lifecycle_snapshot_1.actorJoinIdentity; } });
+Object.defineProperty(exports, "createActorJoinRequest", { enumerable: true, get: function () { return actor_lifecycle_snapshot_1.createActorJoinRequest; } });
+Object.defineProperty(exports, "createActorMembership", { enumerable: true, get: function () { return actor_lifecycle_snapshot_1.createActorMembership; } });
+Object.defineProperty(exports, "ZLINK_ACTOR_LIFECYCLE_SNAPSHOT", { enumerable: true, get: function () { return actor_lifecycle_snapshot_1.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT; } });
+class DefaultZLinkActorManager {
+    options;
+    states = new Map();
+    actorMeshNames = new Map();
+    relocationStaged = new Set();
+    creation;
+    transferredActorRollback;
+    constructor(options) {
+        this.options = options;
+        this.creation = new actor_creation_1.ZLinkActorCreationCoordinator(options);
+        this.transferredActorRollback = new transferred_actor_rollback_1.ZLinkTransferredActorRollbackCoordinator(this.states, options);
+    }
+    create(actorId, actorType) {
+        return new ZLinkActorCreateCallRuntime((options, signal) => this.submitCreate(actorId, actorType, true, options, signal));
+    }
+    async find(actorId, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (this.relocationStaged.has(actorId))
+            return undefined;
+        const state = this.states.get(actorId);
+        if (state?.actor !== undefined) {
+            return this.actorRefForState(state);
+        }
+        return await this.options.actorRefResolver?.resolveActorRef(actorId, signal);
+    }
+    getOrCreate(actorId, actorType) {
+        return new ZLinkActorGetOrCreateCallRuntime((options, signal) => this.submitCreate(actorId, actorType, false, options, signal));
+    }
+    async findSpot(actorId, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const state = this.states.get(actorId);
+        if (state?.actor === undefined || state.spotId === undefined)
+            return undefined;
+        const spotId = state.spotId;
+        const actorRef = this.actorRefForState(state);
+        return {
+            spotId: spotId,
+            objectGeneration: state.locationGeneration ?? 0n,
+            meshName: this.actorMeshNames.get(actorId) ?? '',
+            nodeRid: actorRef.nodeRid
+        };
+    }
+    async destroy(actor, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const state = this.states.get(actor.actorId);
+        if (state?.actor === undefined)
+            return false;
+        const current = this.actorRefForState(state);
+        if (current.objectGeneration !== actor.objectGeneration) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorGenerationStale, `Actor '${actor.actorId}' generation is stale.`);
+        }
+        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;
+        if (node === undefined || completions === undefined)
+            return false;
+        const destroyTask = state.getOrStartDestroy(entryNodeRid, async (nativeRef) => {
+            if (nativeRef !== undefined) {
+                const completion = await completions.submit(() => node.destroyActor(nativeRef, 0), signal);
+                try {
+                    if (completion.terminalResult !== 0 || completion.failureErrno !== 0) {
+                        //  Classify the (terminal, fine) pair via the shared translator
+                        //  (spec 32-framework-error-model:83-118, 99-108) instead of
+                        //  collapsing every destroy failure to NotFound; genuine
+                        //  route-not-found fine codes still yield NotFound through the
+                        //  shared table.
+                        throw (0, framework_errors_internal_1.wireReplyFailureException)(completion.terminalResult, completion.failureErrno, `Actor '${actor.actorId}' destroy failed with result '${completion.terminalResult}' and errno '${completion.failureErrno}'.`);
+                    }
+                }
+                finally {
+                    (0, mesh_completion_table_1.closeMeshCompletion)(completion);
+                }
+                state.markNativeActorDestroyed(nativeRef);
+            }
+            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);
+        });
+        try {
+            await destroyTask;
+        }
+        catch (error) {
+            state.clearFailedDestroy(destroyTask);
+            throw error;
+        }
+        return true;
+    }
+    async materializeTransferredActor(actorId, actorType, adapterKey, transferState, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const state = this.getOrCreateState(actorId);
+        this.rememberActorMeshFromType(actorId, actorType);
+        if (state.actor !== undefined) {
+            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor);
+        }
+        state.prepareForRemoteReentry();
+        const operation = state.getOrStartCreation(actorType, false, () => this.creation.materializeTransferredActor(actorId, actorType, state, adapterKey === undefined
+            ? undefined
+            : (actor) => {
+                const registry = this.options.actorTransferRegistry;
+                if (registry === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException('Actor transfer registry is not configured.');
+                }
+                return registry.restore(adapterKey, actor, transferState, signal);
+            }));
+        try {
+            const result = await operation.task;
+            if (result.status !== 'created') {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateRejected, `Transferred Actor '${actorId}' materialization was rejected.`);
+            }
+            const actor = result.actor;
+            return { actor, actorRef: this.actorRefForState(state) };
+        }
+        catch (error) {
+            state.clearFailedCreation(operation.task);
+            throw error;
+        }
+    }
+    async rollbackTransferredActor(actor, signal) {
+        await this.transferredActorRollback.rollback(actor, signal);
+    }
+    async submitCreate(actorId, actorType, failIfExists, options, signal) {
+        const meshName = options.meshName ?? this.options.actorMeshNameProvider?.(actorType);
+        if (meshName === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ObjectClientNotConfigured, `Actor type '${actorType}' has no configured object-role RouteMesh.`);
+        }
+        requireActorMeshName(meshName);
+        this.ensureActorTypeBelongsToMesh(meshName, actorType);
+        if (this.options.placementCreate !== undefined) {
+            return await this.options.placementCreate(actorId, actorType, failIfExists, options, signal);
+        }
+        const localState = this.states.get(actorId);
+        if (localState?.actorType !== undefined && localState.actorType !== actorType) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorTypeMismatch, `Actor '${actorId}' is registered as type '${localState.actorType}', not '${actorType}'.`);
+        }
+        const existing = await this.find(actorId, signal);
+        if (existing !== undefined) {
+            if (failIfExists) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorAlreadyExists, `Actor '${actorId}' already exists.`);
+            }
+            return { status: 'existing', actor: existing };
+        }
+        this.rememberActorMesh(actorId, meshName);
+        const result = await this.createOrGet(actorId, actorType, failIfExists, options.request, signal, true, options.timeoutMs);
+        if (result.status === 'rejected') {
+            return result.reply === undefined
+                ? { status: 'rejected' }
+                : { status: 'rejected', reply: result.reply };
+        }
+        return result.reply === undefined
+            ? { status: result.status, actor: result.actorRef }
+            : { status: result.status, actor: result.actorRef, reply: result.reply };
+    }
+    ensureActorTypeBelongsToMesh(meshName, actorType) {
+        const registeredMesh = this.options.actorMeshNameProvider?.(actorType);
+        if (registeredMesh !== undefined && registeredMesh !== meshName) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor type '${actorType}' belongs to RouteMesh '${registeredMesh}', not '${meshName}'.`);
+        }
+    }
+    rememberActorMesh(actorId, meshName) {
+        const existing = this.actorMeshNames.get(actorId);
+        if (existing !== undefined && existing !== meshName) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' belongs to RouteMesh '${existing}', not '${meshName}'.`);
+        }
+        this.actorMeshNames.set(actorId, meshName);
+        this.states.get(actorId)?.rememberMeshName(meshName);
+    }
+    rememberActorMeshFromType(actorId, actorType) {
+        const meshName = this.options.actorMeshNameProvider?.(actorType);
+        if (meshName !== undefined) {
+            this.rememberActorMesh(actorId, meshName);
+        }
+    }
+    async findActor(actorId, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (this.relocationStaged.has(actorId))
+            return undefined;
+        return this.states.get(actorId)?.actor;
+    }
+    requireRelocationActorFactory(actorType) {
+        if (!this.options.actorFactories.has(actorType)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor factory '${actorType}' is not registered.`);
+        }
+    }
+    async prepareRelocationActor(actorId, actorType, objectGeneration, authorityOwnerGeneration, spotId, spotGeneration, membershipEpoch, signal, transfer) {
+        if (this.states.has(actorId) || this.relocationStaged.has(actorId)) {
+            throw new Error(`Actor '${actorId}' already exists on the relocation target.`);
+        }
+        const node = this.options.nativeActorNodeProvider?.() ?? this.options.nativeActorNode;
+        const restore = node?.restoreActorAuthority;
+        if (node === undefined || restore === undefined) {
+            throw new Error('Actor relocation requires native authority restore support.');
+        }
+        this.relocationStaged.add(actorId);
+        let nativeRef;
+        try {
+            nativeRef = restore.call(node, actorId, actorType, objectGeneration, authorityOwnerGeneration, String(spotId), spotGeneration, membershipEpoch);
+            this.rememberActorMeshFromType(actorId, actorType);
+            const state = this.getOrCreateState(actorId);
+            state.setNativeActorRef(nativeRef);
+            const operation = state.getOrStartCreation(actorType, false, () => this.creation.materializeTransferredActor(actorId, actorType, state, undefined));
+            const result = await operation.task;
+            if (result.status !== 'created') {
+                throw new Error(`Actor '${actorId}' relocation materialization was rejected.`);
+            }
+            const actor = result.actor;
+            if (transfer !== undefined) {
+                const registry = this.options.actorTransferRegistry;
+                if (registry === undefined) {
+                    throw new configuration_1.ZLinkConfigurationException('Actor transfer registry is not configured.');
+                }
+                await registry.restore(transfer.adapterKey, actor, transfer.state, signal);
+            }
+            state.setLocationGeneration(authorityOwnerGeneration);
+            state.setJoinedSpot(spotId, undefined, membershipEpoch);
+            return actor;
+        }
+        catch (error) {
+            if (nativeRef !== undefined)
+                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);
+            throw error;
+        }
+    }
+    publishRelocationActor(actorId) {
+        if (!this.states.has(actorId)) {
+            throw new Error(`Actor '${actorId}' relocation staging is missing.`);
+        }
+        this.relocationStaged.delete(actorId);
+    }
+    async abortRelocationActor(actorId) {
+        await this.removeRelocationActor(actorId);
+    }
+    async completeRelocationSource(actorId, sourceActorRef) {
+        await this.removeRelocationActor(actorId, sourceActorRef);
+    }
+    async removeRelocationActor(actorId, exactNativeActorRef) {
+        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);
+        }
+        if (state?.actor !== undefined) {
+            await (0, handler_instance_scope_1.disposeLifecycleHandlers)(state.actor);
+        }
+        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);
+        }
+        state?.clearAfterDestroy();
+        this.states.delete(actorId);
+        this.actorMeshNames.delete(actorId);
+        this.relocationStaged.delete(actorId);
+    }
+    async getOrCreateActor(actorId, actorType, signal) {
+        this.rememberActorMeshFromType(actorId, actorType);
+        const result = await this.createOrGet(actorId, actorType, false, undefined, signal);
+        return requireCreatedActor(result, actorId);
+    }
+    async getOrCreateWithNativeRef(actorId, actorType, actorRef, createRequest, signal) {
+        this.rememberActorMeshFromType(actorId, actorType);
+        const state = this.getOrCreateState(actorId);
+        state.setNativeActorRef(actorRef);
+        const result = await this.createOrGet(actorId, actorType, false, createRequest, signal, false);
+        return requireCreatedActor(result, actorId);
+    }
+    async getOrCreateActorResult(actorId, actorType, createRequest, signal) {
+        this.rememberActorMeshFromType(actorId, actorType);
+        return await this.createOrGet(actorId, actorType, false, createRequest, signal);
+    }
+    async createReservedActorResult(actorId, actorType, createRequest, signal, nativeActorRef) {
+        this.rememberActorMeshFromType(actorId, actorType);
+        return await this.createOrGet(actorId, actorType, false, createRequest, signal, false, 30_000, nativeActorRef);
+    }
+    adoptCreatedAuthority(actorId, authorityOwnerGeneration, ownerLeaseGeneration) {
+        const state = this.states.get(actorId);
+        if (state === undefined) {
+            throw new Error(`Actor '${actorId}' is not materialized.`);
+        }
+        state.setLocationGeneration(authorityOwnerGeneration);
+        state.setOwnerLeaseGeneration(ownerLeaseGeneration);
+        state.markLocationOwned();
+    }
+    getState(actorId) {
+        return this.states.get(actorId);
+    }
+    snapshotStates() {
+        return [...this.states.values()];
+    }
+    activeActorCount(meshName) {
+        return [...this.states.values()].filter((state) => state.meshName === meshName && state.actor !== undefined).length;
+    }
+    async destroyActor(node, entryNodeRid, actor, signal) {
+        const destroySignal = signal;
+        (0, abort_1.throwIfAborted)(destroySignal);
+        const state = this.states.get(actor.context.actorId);
+        if (state === undefined || state.actor === undefined || state.actor !== actor) {
+            return;
+        }
+        if (state.isJoined) {
+            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 ?? '');
+            if (actorRef !== undefined) {
+                await node.destroyActor(actorRef, 0, destroySignal);
+                state.markNativeActorDestroyed(actorRef);
+            }
+            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);
+        });
+        try {
+            await destroyTask;
+        }
+        catch (error) {
+            state.clearFailedDestroy(destroyTask);
+            throw error;
+        }
+    }
+    async createOrGet(actorId, actorType, failIfExists, request, signal, claimLocation = true, timeoutMs = 30_000, nativeActorRef) {
+        const deadline = performance.now() + timeoutMs;
+        const requestedMeshName = this.actorMeshNames.get(actorId);
+        for (;;) {
+            (0, abort_1.throwIfAborted)(signal);
+            if (requestedMeshName !== undefined && !this.actorMeshNames.has(actorId)) {
+                this.actorMeshNames.set(actorId, requestedMeshName);
+            }
+            const existingState = this.states.get(actorId);
+            if (existingState?.hasActorOrCreation !== true) {
+                this.options.admission?.requireActorCreate(actorId, this.options.actorMeshNameProvider?.(actorType));
+            }
+            const state = existingState ?? this.getOrCreateState(actorId);
+            if (nativeActorRef !== undefined) {
+                state.setNativeActorRef(nativeActorRef);
+            }
+            const createRequest = this.createRequestMessage(request);
+            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));
+            if (operation.created) {
+                void operation.task.then((result) => {
+                    if (result.status === 'rejected') {
+                        this.discardFailedState(actorId, state, operation.task);
+                    }
+                }, () => this.discardFailedState(actorId, state, operation.task));
+            }
+            try {
+                const result = await operation.task;
+                if (result.status === 'created') {
+                    const actorRef = this.actorRefForState(state);
+                    return {
+                        status: operation.created ? 'created' : 'existing',
+                        actor: result.actor,
+                        actorRef,
+                        reply: operation.created ? result.reply : undefined
+                    };
+                }
+                if (operation.created) {
+                    return { status: 'rejected', reply: result.reply };
+                }
+            }
+            catch (error) {
+                if (operation.created) {
+                    if (error instanceof contracts_1.ZLinkFrameworkException) {
+                        throw error;
+                    }
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${actorId}' creation failed: ${error instanceof Error ? error.message : String(error)}`, false, error);
+                }
+            }
+            finally {
+                createRequest.nativeRequest?.close();
+            }
+            if (performance.now() >= deadline) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor '${actorId}' creation did not reach a terminal state before its deadline.`, true);
+            }
+            await waitForCreationRetry(signal);
+        }
+    }
+    discardFailedState(actorId, state, task) {
+        if (!state.clearFailedCreation(task))
+            return;
+        if (this.states.get(actorId) === state) {
+            this.states.delete(actorId);
+            this.actorMeshNames.delete(actorId);
+            this.options.metrics?.change('zlink.actor.count', -1);
+        }
+    }
+    createRequestMessage(request) {
+        if (request === undefined) {
+            const empty = runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0));
+            return {
+                nativeRequest: empty,
+                callbackRequest: contracts_2.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()))
+        };
+    }
+    getOrCreateState(actorId) {
+        const existing = this.states.get(actorId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const state = new actor_runtime_state_2.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);
+        return state;
+    }
+    actorRefForState(state) {
+        const nativeActorRef = state.nativeActorRef;
+        if (nativeActorRef !== undefined) {
+            return (0, actor_runtime_state_2.toFrameworkActorRef)(nativeActorRef, state.meshName ?? '');
+        }
+        return {
+            actorId: state.actorId,
+            objectGeneration: 1n,
+            meshName: state.meshName ?? '',
+            nodeRid: this.options.actorCreatedNodeRidProvider?.()
+                ?? 'local'
+        };
+    }
+}
+exports.DefaultZLinkActorManager = DefaultZLinkActorManager;
+class ZLinkActorCreateCallRuntime {
+    execute;
+    meshNameValue;
+    requestValue;
+    requestConfigured = false;
+    timeoutMsValue = 30_000;
+    timeoutConfigured = false;
+    submitted = false;
+    turn = (0, execution_1.captureZLinkSpotSerialTurn)();
+    constructor(execute) {
+        this.execute = execute;
+    }
+    inMesh(meshName) {
+        this.requireMutable();
+        if (this.meshNameValue !== undefined)
+            this.throwDuplicateOption('inMesh');
+        requireActorMeshName(meshName);
+        this.meshNameValue = meshName;
+        return this;
+    }
+    request(request) {
+        this.requireMutable();
+        if (this.requestConfigured)
+            this.throwDuplicateOption('request');
+        this.requestConfigured = true;
+        this.requestValue = request;
+        return this;
+    }
+    timeout(timeoutMs) {
+        this.requireMutable();
+        if (this.timeoutConfigured)
+            this.throwDuplicateOption('timeout');
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidConfiguration, 'Actor create timeout must be a positive finite number.');
+        }
+        this.timeoutConfigured = true;
+        this.timeoutMsValue = timeoutMs;
+        return this;
+    }
+    submit(signal) {
+        return this.executeOnce(signal);
+    }
+    yield(signal) {
+        const turn = (0, execution_1.requireZLinkYieldTurn)(this.turn);
+        const pending = this.executeOnce(signal);
+        return turn.yieldPromise(pending);
+    }
+    executeOnce(signal) {
+        this.requireMutable();
+        this.submitted = true;
+        return this.execute({
+            ...(this.meshNameValue === undefined ? {} : { meshName: this.meshNameValue }),
+            ...(this.requestConfigured ? { request: this.requestValue } : {}),
+            timeoutMs: this.timeoutMsValue
+        }, signal);
+    }
+    requireMutable() {
+        if (!this.submitted)
+            return;
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.AlreadySubmitted, 'Actor create call was already submitted.');
+    }
+    throwDuplicateOption(option) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.InvalidOperation, `Actor create option '${option}' was already configured.`);
+    }
+}
+class ZLinkActorGetOrCreateCallRuntime extends ZLinkActorCreateCallRuntime {
+}
+function requireCreatedActor(result, actorId) {
+    if (result.status !== 'rejected')
+        return result.actor;
+    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateRejected, `Actor '${actorId}' create request was rejected.`);
+}
+async function waitForCreationRetry(signal) {
+    (0, abort_1.throwIfAborted)(signal);
+    await new Promise((resolve, reject) => {
+        const finish = (error) => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            if (error === undefined)
+                resolve();
+            else
+                reject(error);
+        };
+        const timer = setTimeout(() => finish(), 5);
+        const onAbort = () => {
+            finish(signal?.reason ?? new Error('Actor creation was aborted.'));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function requireActorMeshName(meshName) {
+    if (meshName.length === 0 || meshName !== meshName.trim()) {
+        throw new configuration_1.ZLinkConfigurationException('Actor RouteMesh name must not be empty or padded.');
+    }
+}

package/dist/runtime/actors/post-commit-actor-binder.d.ts

@@ -0,0 +1,18 @@
+import type { ActorRef } from '../../contracts';
+export interface ZLinkPostCommitActorBinderOptions {
+    readonly bind: (actorRef: ActorRef, force: boolean) => Promise<void>;
+    readonly reportError?: (error: unknown) => void;
+    readonly signal?: AbortSignal | (() => AbortSignal | undefined);
+}
+export declare class ZLinkPostCommitActorBinder {
+    private readonly options;
+    private readonly lane;
+    private readonly desiredRefs;
+    private readonly tasks;
+    constructor(options: ZLinkPostCommitActorBinderOptions);
+    bindEventually(actorRef: ActorRef): void;
+    bind(actorRef: ActorRef): Promise<void>;
+    private run;
+    private signal;
+    private completeBindCore;
+}