@zlink-systems/framework 0.10.0

package/dist/runtime/actors/actor-context.js

@@ -0,0 +1,433 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkActorContext = exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = 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 configuration_1 = require("../configuration");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const payload_codec_1 = require("../messaging/payload-codec");
+const actor_runtime_state_1 = require("./actor-runtime-state");
+const actor_lifecycle_snapshot_1 = require("./actor-lifecycle-snapshot");
+const operation_identity_1 = require("../foundation/operation-identity");
+const actor_join_deferred_scope_1 = require("./actor-join-deferred-scope");
+const execution_1 = require("../execution");
+exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME = Symbol('zlink.actor.join-entry-spot-runtime');
+class DefaultZLinkActorContext {
+    state;
+    joinCoordinator;
+    messageSerializers;
+    meshNameProvider;
+    boundSession;
+    resolvedMeshName;
+    constructor(state, joinCoordinator, boundSessionFactory, messageSerializers, meshNameProvider) {
+        this.state = state;
+        this.joinCoordinator = joinCoordinator;
+        this.messageSerializers = messageSerializers;
+        this.meshNameProvider = meshNameProvider;
+        this.boundSession = boundSessionFactory?.(state.actorId) ?? new UnboundZLinkSession();
+    }
+    get meshName() {
+        // The membership resolves once per actor. A getter that re-entered the
+        // application provider on every read would make an observable side effect
+        // out of reading identity.
+        if (this.resolvedMeshName !== undefined) {
+            return this.resolvedMeshName;
+        }
+        const remembered = this.state.meshName;
+        if (remembered !== undefined) {
+            this.resolvedMeshName = remembered;
+            return remembered;
+        }
+        const actorType = this.state.actorType;
+        const meshName = actorType === undefined ? undefined : this.meshNameProvider?.(actorType);
+        if (meshName === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${this.state.actorId}' does not belong to a registered RouteMesh.`);
+        }
+        this.resolvedMeshName = meshName;
+        return meshName;
+    }
+    get actorId() {
+        return this.state.actorId;
+    }
+    get objectGeneration() {
+        return this.state.nativeActorRef?.generation ?? 1n;
+    }
+    get spotId() {
+        return this.state.spotId;
+    }
+    [actor_lifecycle_snapshot_1.ZLINK_ACTOR_LIFECYCLE_SNAPSHOT]() {
+        const nativeActorRef = this.state.nativeActorRef;
+        const actorType = this.state.actorType;
+        if (nativeActorRef === undefined || actorType === undefined) {
+            throw new configuration_1.ZLinkConfigurationException(`Actor '${this.state.actorId}' lifecycle identity is not initialized.`);
+        }
+        return {
+            actorRef: (0, actor_runtime_state_1.toFrameworkActorRef)(nativeActorRef, this.meshName),
+            actorType,
+            membershipEpoch: this.state.spotMembershipEpoch
+        };
+    }
+    joinSpot(spotId, request) {
+        return new DefaultZLinkActorJoinSpotCall(this.state, this.requireActor(), this.requireJoinCoordinator(), spotId, request, this.messageSerializers);
+    }
+    joinEntrySpot(request) {
+        return new DefaultZLinkActorJoinEntrySpotCall(this.state, this.requireActor(), this.requireJoinCoordinator(), request, this.messageSerializers);
+    }
+    async [exports.ZLINK_ACTOR_JOIN_ENTRY_SPOT_RUNTIME](nodeRid, request, signal) {
+        const requestMessage = encodeJoinRequest(request, this.messageSerializers);
+        try {
+            return (await this.requireJoinCoordinator().joinEntrySpot(this.requireActor(), this.state, nodeRid, requestMessage, undefined, signal)).accepted;
+        }
+        finally {
+            requestMessage.close();
+        }
+    }
+    requireActor() {
+        if (this.state.actor === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Actor context is not bound to an actor.');
+        }
+        return this.state.actor;
+    }
+    requireJoinCoordinator() {
+        if (this.joinCoordinator === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Actor join runtime is not started.');
+        }
+        return this.joinCoordinator;
+    }
+}
+exports.DefaultZLinkActorContext = DefaultZLinkActorContext;
+class DefaultZLinkActorJoinSpotCall {
+    state;
+    actor;
+    coordinator;
+    spotId;
+    request;
+    messageSerializers;
+    timeoutMs = 5_000;
+    deferred = false;
+    turn = (0, execution_1.captureZLinkSpotSerialTurn)();
+    constructor(state, actor, coordinator, spotId, request, messageSerializers) {
+        this.state = state;
+        this.actor = actor;
+        this.coordinator = coordinator;
+        this.spotId = spotId;
+        this.request = request;
+        this.messageSerializers = messageSerializers;
+    }
+    timeout(timeoutMs) {
+        this.timeoutMs = validateJoinTimeout(timeoutMs);
+        return this;
+    }
+    defer() {
+        if (this.deferred) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.AlreadySubmitted, 'Actor join call was already deferred.');
+        }
+        this.deferred = true;
+        const deadline = createDeferredJoinDeadline(this.timeoutMs);
+        const sourceNodeRid = this.state.nativeActorRef?.nodeRid;
+        const requestMessage = encodeJoinRequest(this.request, this.messageSerializers);
+        try {
+            claimDeferredJoin(this.state);
+        }
+        catch (error) {
+            deadline.close();
+            requestMessage.close();
+            throw error;
+        }
+        const operationId = createJoinOperationId();
+        let discarded = false;
+        let prepared = false;
+        let pendingJoin;
+        const discard = async () => {
+            if (discarded)
+                return;
+            discarded = true;
+            this.state.endDeferredJoin();
+            try {
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+            }
+            finally {
+                deadline.close();
+                requestMessage.close();
+            }
+        };
+        try {
+            (0, actor_join_deferred_scope_1.deferActorJoin)({
+                requestBytes: requestMessage.data().byteLength,
+                prepare: async () => {
+                    if (prepared)
+                        return;
+                    prepared = true;
+                    this.state.endDeferredJoin();
+                    try {
+                        // The provisional ingress fence is installed only after the
+                        // handler terminal. Target admission starts before reply encoding,
+                        // while completion and finalization remain in execute().
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        pendingJoin = this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        if (this.turn === undefined) {
+                            await pendingJoin.catch(() => undefined);
+                        }
+                    }
+                    catch (error) {
+                        pendingJoin = Promise.reject(error);
+                        void pendingJoin.catch(() => undefined);
+                    }
+                },
+                discard,
+                execute: async () => {
+                    let result;
+                    try {
+                        const pending = pendingJoin ?? this.coordinator.joinSpot(this.actor, this.state, this.spotId, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        result = this.turn === undefined
+                            ? await pending
+                            : await this.turn.yieldFrameworkPromise(pending);
+                    }
+                    catch (error) {
+                        this.state.endDeferredJoin();
+                        await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .catch(() => undefined);
+                        await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
+                        return;
+                    }
+                    finally {
+                        deadline.close();
+                        requestMessage.close();
+                    }
+                    if (!result.accepted
+                        || sourceNodeRid === undefined
+                        || result.actor === undefined
+                        || String(sourceNodeRid) === String(result.actor.nodeRid)) {
+                        await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
+                    }
+                    else {
+                        result.reply?.close();
+                    }
+                    const finalization = result.finalizeDeferredJoin?.();
+                    if (finalization !== undefined) {
+                        // Releasing a rejected provisional handoff can enqueue source
+                        // backlog behind this same Spot turn. Yield the lifecycle boundary
+                        // so replay can run without overtaking the completion callback.
+                        await (this.turn === undefined
+                            ? finalization
+                            : this.turn.yieldFrameworkPromise(finalization));
+                    }
+                }
+            });
+        }
+        catch (error) {
+            void discard().catch(() => undefined);
+            throw error;
+        }
+    }
+}
+class DefaultZLinkActorJoinEntrySpotCall {
+    state;
+    actor;
+    coordinator;
+    request;
+    messageSerializers;
+    timeoutMs = 5_000;
+    deferred = false;
+    turn = (0, execution_1.captureZLinkSpotSerialTurn)();
+    constructor(state, actor, coordinator, request, messageSerializers) {
+        this.state = state;
+        this.actor = actor;
+        this.coordinator = coordinator;
+        this.request = request;
+        this.messageSerializers = messageSerializers;
+    }
+    timeout(timeoutMs) {
+        this.timeoutMs = validateJoinTimeout(timeoutMs);
+        return this;
+    }
+    defer() {
+        if (this.deferred) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.AlreadySubmitted, 'Actor join call was already deferred.');
+        }
+        this.deferred = true;
+        const deadline = createDeferredJoinDeadline(this.timeoutMs);
+        const sourceNodeRid = this.state.nativeActorRef?.nodeRid;
+        const requestMessage = encodeJoinRequest(this.request, this.messageSerializers);
+        try {
+            claimDeferredJoin(this.state);
+        }
+        catch (error) {
+            deadline.close();
+            requestMessage.close();
+            throw error;
+        }
+        const operationId = createJoinOperationId();
+        let discarded = false;
+        let prepared = false;
+        let pendingJoin;
+        const discard = async () => {
+            if (discarded)
+                return;
+            discarded = true;
+            this.state.endDeferredJoin();
+            try {
+                await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId);
+            }
+            finally {
+                deadline.close();
+                requestMessage.close();
+            }
+        };
+        try {
+            (0, actor_join_deferred_scope_1.deferActorJoin)({
+                requestBytes: requestMessage.data().byteLength,
+                prepare: async () => {
+                    if (prepared)
+                        return;
+                    prepared = true;
+                    this.state.endDeferredJoin();
+                    try {
+                        this.coordinator.beginDeferredJoin?.(this.actor, this.state, operationId);
+                        pendingJoin = this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        if (this.turn === undefined) {
+                            await pendingJoin.catch(() => undefined);
+                        }
+                    }
+                    catch (error) {
+                        pendingJoin = Promise.reject(error);
+                        void pendingJoin.catch(() => undefined);
+                    }
+                },
+                discard,
+                execute: async () => {
+                    let result;
+                    try {
+                        const pending = pendingJoin ?? this.coordinator.joinEntrySpot(this.actor, this.state, undefined, requestMessage, remainingJoinTimeout(deadline.atMs), deadline.signal, operationId);
+                        result = this.turn === undefined
+                            ? await pending
+                            : await this.turn.yieldFrameworkPromise(pending);
+                    }
+                    catch (error) {
+                        this.state.endDeferredJoin();
+                        await this.coordinator.abortDeferredJoin?.(this.actor, this.state, operationId)
+                            .catch(() => undefined);
+                        await notifyJoinFailure(this.actor, operationId, error, this.coordinator);
+                        return;
+                    }
+                    finally {
+                        deadline.close();
+                        requestMessage.close();
+                    }
+                    if (!result.accepted
+                        || sourceNodeRid === undefined
+                        || result.actor === undefined
+                        || String(sourceNodeRid) === String(result.actor.nodeRid)) {
+                        await notifyJoinCompletion(this.actor, operationId, result, this.messageSerializers);
+                    }
+                    else {
+                        result.reply?.close();
+                    }
+                    const finalization = result.finalizeDeferredJoin?.();
+                    if (finalization !== undefined) {
+                        await (this.turn === undefined
+                            ? finalization
+                            : this.turn.yieldFrameworkPromise(finalization));
+                    }
+                }
+            });
+        }
+        catch (error) {
+            void discard().catch(() => undefined);
+            throw error;
+        }
+    }
+}
+class UnboundZLinkSession {
+    send() {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, 'Actor session is not bound.', true);
+    }
+    async disconnect() {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, 'Actor session is not bound.', true);
+    }
+}
+function encodeJoinRequest(request, serializers) {
+    return request === undefined
+        ? runtime_message_1.ZLinkBufferMessage.from(Buffer.alloc(0))
+        : (0, payload_codec_1.encodeFrameworkPayloadMessage)(request, serializers);
+}
+function validateJoinTimeout(timeoutMs) {
+    const rounded = Math.ceil(timeoutMs);
+    if (!Number.isFinite(timeoutMs) || rounded < 1 || rounded > 2_147_483_647) {
+        throw new configuration_1.ZLinkConfigurationException('Actor join timeout must be a finite value from 1 through 2147483647 milliseconds.');
+    }
+    return rounded;
+}
+function claimDeferredJoin(state) {
+    if (!state.tryBeginDeferredJoin()) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving, `Actor '${state.actorId}' already has a pending membership transition.`, true);
+    }
+}
+function remainingJoinTimeout(deadline) {
+    const remaining = deadline - performance.now();
+    if (remaining <= 0) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, 'Deferred Actor join deadline elapsed before activation.', true);
+    }
+    return Math.ceil(remaining);
+}
+function createDeferredJoinDeadline(timeoutMs) {
+    const controller = new AbortController();
+    const atMs = performance.now() + timeoutMs;
+    const timer = setTimeout(() => controller.abort((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, 'Deferred Actor join exceeded its absolute deadline.', true)), timeoutMs);
+    return {
+        atMs,
+        signal: controller.signal,
+        close: () => clearTimeout(timer)
+    };
+}
+function createJoinOperationId() {
+    return (0, operation_identity_1.createRandomOperationIdentity)();
+}
+async function notifyJoinCompletion(actor, operationId, result, _messageSerializers) {
+    // The completion preserves the encoded reply without exposing serializer selection.
+    const reply = result.reply === undefined
+        ? undefined
+        : contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(result.reply.data()));
+    result.reply?.close();
+    // `reply`는 계약상 선택 항목이라 없을 때는 key 자체를 만들지 않는다.
+    const replyField = reply === undefined ? {} : { reply };
+    const completion = result.accepted
+        ? {
+            status: 'accepted',
+            operationId,
+            actor: result.actor,
+            ...replyField
+        }
+        : {
+            status: 'rejected',
+            operationId,
+            ...replyField
+        };
+    await actor.onJoinCompleted?.(completion);
+}
+async function notifyJoinFailure(actor, operationId, error, coordinator) {
+    console.error(`actor join failure actor=${actor.context.actorId}`, error);
+    const frameworkError = error instanceof contracts_1.ZLinkFrameworkException
+        ? error
+        : (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestFailed, 'Deferred actor join failed.', false, error);
+    //  The completion carries only an error kind, so trace the cause on the
+    //  message flow under the same flow id as the Join that produced it.
+    const tracePoint = coordinator?.messageFlow?.()?.begin(ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error);
+    tracePoint?.trace({
+        outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Error,
+        surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.SpotActor,
+        messageKind: ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.ActorRequest,
+        packetName: 'JoinSpot',
+        actorId: actor.context.actorId,
+        errorReason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+        errorAction: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError,
+        errorType: String(frameworkError.kind),
+        errorMessage: String(error)
+    });
+    await actor.onJoinCompleted?.({
+        status: 'failed',
+        operationId,
+        kind: frameworkError.kind
+    });
+}

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

@@ -0,0 +1,19 @@
+import type { ZLinkActor } from '../../contracts';
+import { ZLinkMessage } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import { ZLinkActorRuntimeState, type ZLinkActorCreationAttemptResult } from './actor-runtime-state';
+import type { ZLinkActorManagerOptions } from './actor-runtime-contracts';
+export interface ZLinkActorCreateRequest {
+    readonly nativeRequest: Message | undefined;
+    readonly callbackRequest: ZLinkMessage;
+}
+export declare class ZLinkActorCreationCoordinator {
+    private readonly options;
+    constructor(options: ZLinkActorManagerOptions);
+    createActor(actorId: string, actorType: string, state: ZLinkActorRuntimeState, createRequest: ZLinkActorCreateRequest, claimLocation: boolean, signal?: AbortSignal): Promise<ZLinkActorCreationAttemptResult>;
+    materializeTransferredActor(actorId: string, actorType: string, state: ZLinkActorRuntimeState, restore: ((actor: ZLinkActor) => Promise<void>) | undefined): Promise<ZLinkActorCreationAttemptResult>;
+    private createActorAfterClaim;
+    private discardStagingActor;
+    private resolveLocationNodeRid;
+    private createFactory;
+}

package/dist/runtime/actors/actor-creation.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorCreationCoordinator = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const configuration_1 = require("../configuration");
+const actor_context_1 = require("./actor-context");
+const actor_runtime_state_1 = require("./actor-runtime-state");
+class ZLinkActorCreationCoordinator {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async createActor(actorId, actorType, state, createRequest, claimLocation, signal) {
+        const lifecycle = this.options.locationLifecycle;
+        if (lifecycle !== undefined && claimLocation) {
+            const nodeRid = this.resolveLocationNodeRid();
+            const activation = await lifecycle.executeActorClaimThenActivate(actorType, actorId, nodeRid, async () => {
+                // A target takeover is the commit point of an in-flight remote move.
+                // Keep the source runtime state until the commit reply installs the
+                // remote ActorRef used to finish the caller's current request.
+                if (state.isMoving || state.remoteActorPacketTarget !== undefined) {
+                    return;
+                }
+                this.options.actorDestroyedCleanup?.(actorId);
+                state.clearAfterDestroy();
+            }, () => this.createActorAfterClaim(actorId, actorType, state, createRequest, true, signal));
+            if (activation.activated !== undefined) {
+                if (activation.activated.status === 'rejected') {
+                    await lifecycle.releaseActor(actorType, actorId);
+                    return activation.activated;
+                }
+                if (activation.generation !== undefined) {
+                    state.setLocationGeneration(activation.generation);
+                }
+                if (activation.ownerLeaseGeneration !== undefined) {
+                    state.setOwnerLeaseGeneration(activation.ownerLeaseGeneration);
+                }
+                state.markLocationOwned();
+                return activation.activated;
+            }
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, activation.existingLocation === undefined
+                ? `Actor '${actorId}' location claim was rejected and no live location row was found.`
+                : `Actor '${actorId}' is already active on node '${activation.existingLocation.ownerNodeRid}' (location claim conflict).`);
+        }
+        return await this.createActorAfterClaim(actorId, actorType, state, createRequest, claimLocation, signal);
+    }
+    async materializeTransferredActor(actorId, actorType, state, restore) {
+        void actorId;
+        const context = state.ensureContext(() => new actor_context_1.DefaultZLinkActorContext(state, this.options.joinCoordinator, this.options.boundSessionFactory, this.options.messageSerializers, this.options.actorMeshNameProvider));
+        const actor = await (await this.createFactory(actorType)).create(context);
+        attachTransferredActorContext(actor, context);
+        await restore?.(actor);
+        state.bindActor(actor, context);
+        const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+        if (nativeActorNode !== undefined) {
+            state.ensureNativeActorRef(nativeActorNode);
+        }
+        return { status: 'created', actor };
+    }
+    async createActorAfterClaim(actorId, actorType, state, createRequest, updateLocation, signal) {
+        const factory = await this.createFactory(actorType);
+        const context = state.ensureContext(() => new actor_context_1.DefaultZLinkActorContext(state, this.options.joinCoordinator, this.options.boundSessionFactory, this.options.messageSerializers, this.options.actorMeshNameProvider));
+        const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+        try {
+            const actor = await factory.create(context, signal);
+            if (actor.context !== context || actor.context.actorId !== context.actorId) {
+                throw new configuration_1.ZLinkConfigurationException(`Actor factory '${actorType}' must return an Actor bound to the exact supplied context.`);
+            }
+            const meshName = state.meshName ?? '';
+            if (meshName.length === 0 && state.nativeActorRef === undefined) {
+                throw new configuration_1.ZLinkConfigurationException(`Actor '${actorId}' has no RouteMesh identity.`);
+            }
+            let nodeRid;
+            if (nativeActorNode !== undefined) {
+                const actorRef = state.ensureNativeActorRef(nativeActorNode, createRequest.nativeRequest);
+                nodeRid = (0, actor_runtime_state_1.toFrameworkRoutingId)(actorRef.nodeRid);
+            }
+            else {
+                nodeRid = this.options.actorCreatedNodeRidProvider?.();
+            }
+            const response = nodeRid === undefined
+                ? { accepted: true }
+                : await this.options.actorCreatedNotifier?.(nodeRid, actor, createRequest.callbackRequest, signal) ?? { accepted: true };
+            if (!response.accepted) {
+                await this.discardStagingActor(state, nativeActorNode);
+                return { status: 'rejected', reply: response.reply };
+            }
+            state.bindActor(actor, context);
+            if (nativeActorNode !== undefined) {
+                const actorRef = state.nativeActorRef;
+                if (updateLocation) {
+                    await this.options.locationLifecycle?.setActorRef(actorType, actorId, (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, meshName), nativeActorNode.status().lifecycleGeneration);
+                    await this.options.publishActorAuthority?.(actorType, (0, actor_runtime_state_1.toFrameworkActorRef)(actorRef, meshName), nativeActorNode.status().lifecycleGeneration, signal);
+                }
+            }
+            else if (nodeRid !== undefined && updateLocation) {
+                await this.options.locationLifecycle?.setActorRef(actorType, actorId, { actorId, objectGeneration: 1n, meshName, nodeRid }, 0n);
+            }
+            return { status: 'created', actor, reply: response.reply };
+        }
+        catch (error) {
+            await this.discardStagingActor(state, nativeActorNode);
+            throw error;
+        }
+    }
+    async discardStagingActor(state, nativeActorNode) {
+        const actorRef = state.nativeActorRef;
+        if (nativeActorNode !== undefined && actorRef !== undefined) {
+            await nativeActorNode.destroyActor(actorRef, 0);
+            state.markNativeActorDestroyed(actorRef);
+        }
+    }
+    resolveLocationNodeRid() {
+        const nativeActorNode = this.options.nativeActorNode ?? this.options.nativeActorNodeProvider?.();
+        const nodeRid = nativeActorNode === undefined
+            ? this.options.actorCreatedNodeRidProvider?.()
+            : (0, actor_runtime_state_1.toFrameworkRoutingId)(nativeActorNode.status().routingId);
+        if (nodeRid === undefined) {
+            throw new configuration_1.ZLinkConfigurationException('Location actor claim requires a node routing id.');
+        }
+        return nodeRid;
+    }
+    async createFactory(actorType) {
+        const factoryOrType = this.options.actorFactories.get(actorType);
+        if (factoryOrType === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor factory '${actorType}' is not registered.`);
+        }
+        if (typeof factoryOrType === 'function') {
+            const type = factoryOrType;
+            return await createProviderInstance(type, this.options.providerResolver);
+        }
+        return factoryOrType;
+    }
+}
+exports.ZLinkActorCreationCoordinator = ZLinkActorCreationCoordinator;
+function attachTransferredActorContext(actor, context) {
+    const current = actor.context;
+    if (current === context) {
+        return;
+    }
+    Object.defineProperty(actor, 'context', {
+        configurable: false,
+        enumerable: true,
+        writable: false,
+        value: context
+    });
+}
+async function createProviderInstance(type, resolver) {
+    const existing = resolver?.get?.(type);
+    if (existing !== undefined) {
+        return existing;
+    }
+    const created = await resolver?.create?.(type);
+    if (created !== undefined) {
+        return created;
+    }
+    return new type();
+}

package/dist/runtime/actors/actor-execution-context.d.ts

@@ -0,0 +1,6 @@
+/** Runs one Actor handler while retaining its Actor FIFO claim across Yield. */
+export declare function runZLinkActorExecution<T>(actorId: string, spotId: unknown, operation: () => Promise<T> | T): Promise<T>;
+export declare function currentZLinkActorExecution(): Readonly<{
+    actorId: string;
+    spotId?: unknown;
+}> | undefined;

package/dist/runtime/actors/actor-execution-context.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runZLinkActorExecution = runZLinkActorExecution;
+exports.currentZLinkActorExecution = currentZLinkActorExecution;
+const node_async_hooks_1 = require("node:async_hooks");
+const actorExecutionStorage = new node_async_hooks_1.AsyncLocalStorage();
+/** Runs one Actor handler while retaining its Actor FIFO claim across Yield. */
+async function runZLinkActorExecution(actorId, spotId, operation) {
+    const context = { actorId, spotId, active: true };
+    return await actorExecutionStorage.run(context, async () => {
+        try {
+            return await operation();
+        }
+        finally {
+            // Detached async work can inherit AsyncLocalStorage after the handler
+            // terminal. The shared object prevents that stale work from claiming it
+            // still owns the Actor FIFO.
+            context.active = false;
+        }
+    });
+}
+function currentZLinkActorExecution() {
+    const context = actorExecutionStorage.getStore();
+    return context?.active === true
+        ? { actorId: context.actorId, spotId: context.spotId }
+        : undefined;
+}