@zlink-systems/framework 0.10.0

package/dist/runtime/host/actor-placement-coordinator.d.ts

@@ -0,0 +1,32 @@
+import type { ActorRef, RoutingId, ZLinkActorCreateResult } from '../../contracts';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore } from '../locations/internal-store-contracts';
+import type { ServiceActorCreateRecord } from '../foundation/service-stateful-wire-codec';
+import type { ServiceUserSpotOperationResult } from '../foundation/service-stateful-runtime';
+export interface ZLinkActorPlacementTarget {
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly nodeGeneration: bigint;
+    readonly entrySpotId: string;
+    readonly owner: ZLinkLocationOwnerToken;
+    readonly isLocal: boolean;
+}
+export interface ZLinkActorPlacementCoordinatorOptions {
+    readonly store: ZLinkObjectCreationStore & ZLinkAuthorityStore;
+    readonly target: (meshName: string | undefined, stableType: string, signal?: AbortSignal, excludedNodeRids?: ReadonlySet<string>) => Promise<ZLinkActorPlacementTarget | undefined>;
+    readonly remoteCreate: (meshName: string, targetNodeRid: string, request: Omit<ServiceActorCreateRecord, 'kind' | 'correlation' | 'operation'>, timeoutMs: number) => Promise<ServiceUserSpotOperationResult>;
+    readonly decodeRemoteReply?: (payload: Uint8Array) => unknown;
+}
+export declare class ZLinkActorPlacementCoordinator {
+    private readonly options;
+    constructor(options: ZLinkActorPlacementCoordinatorOptions);
+    create(actorId: string, stableType: string, createOnly: boolean, meshName: string | undefined, requestPayload: Uint8Array, timeoutMs: number, signal?: AbortSignal): Promise<ZLinkActorCreateResult>;
+    handleRemoteCreate(record: ServiceActorCreateRecord, materialize: (requestPayload: Uint8Array, authority: ZLinkAuthoritySnapshot, signal: AbortSignal) => Promise<{
+        readonly result: 'created' | 'rejected';
+        readonly actor?: ActorRef;
+        readonly reply?: Uint8Array;
+        readonly onPublished?: () => void;
+        readonly entrySpotId?: string;
+        readonly entrySpotGeneration?: bigint;
+    }>, signal: AbortSignal): Promise<ServiceUserSpotOperationResult>;
+}

package/dist/runtime/host/actor-placement-coordinator.js

@@ -0,0 +1,386 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorPlacementCoordinator = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const node_crypto_1 = require("node:crypto");
+const runtime_values_1 = require("../backend/runtime-values");
+const contracts_1 = require("../../contracts");
+const authority_key_codec_1 = require("../locations/authority-key-codec");
+const actor_authority_publication_1 = require("../actors/actor-authority-publication");
+const user_spot_creation_coordinator_1 = require("./user-spot-creation-coordinator");
+class ZLinkActorPlacementCoordinator {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async create(actorId, stableType, createOnly, meshName, requestPayload, timeoutMs, signal) {
+        const deadline = createDeadline(timeoutMs, signal);
+        const deadlineMs = performance.now() + timeoutMs;
+        const deadlineUnixMs = Date.now() + timeoutMs;
+        const contentReference = (0, user_spot_creation_coordinator_1.encodeLocationCreationContent)(requestPayload);
+        const requestSha256 = (0, node_crypto_1.createHash)('sha256').update(requestPayload).digest();
+        const excluded = new Set();
+        try {
+            for (;;) {
+                const target = await this.options.target(meshName, stableType, deadline.signal, excluded);
+                if (target === undefined) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.PlacementCapacityExhausted, `No eligible Actor placement target is ready for '${stableType}'.`, true);
+                }
+                const creatingPayload = (0, actor_authority_publication_1.encodeActorAuthorityIdentity)({
+                    actorType: stableType,
+                    actor: {
+                        actorId,
+                        objectGeneration: 1n,
+                        meshName: target.meshName,
+                        nodeRid: target.nodeRid
+                    },
+                    meshName: target.meshName,
+                    ownerNodeGeneration: target.nodeGeneration,
+                    owner: target.owner,
+                    state: 'creating',
+                    spotId: target.entrySpotId,
+                    spotGeneration: target.nodeGeneration,
+                    spotKind: contracts_1.ZLinkSpotKind.Entry
+                });
+                const reserved = await this.options.store.reserve({
+                    key: { kind: 'actor', globalId: actorId },
+                    intent: {
+                        stableType,
+                        requestContentReference: contentReference,
+                        requestSha256,
+                        requestEncodedSize: BigInt(requestPayload.byteLength)
+                    },
+                    target: reservationTarget(target),
+                    creatingPayload,
+                    capacity: { actors: 1, spots: 0 }
+                }, deadline.signal);
+                const existing = existingActor(reserved, actorId, stableType);
+                if (existing !== undefined) {
+                    if (createOnly) {
+                        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorAlreadyExists, `Actor '${actorId}' already exists.`);
+                    }
+                    return { status: 'existing', actor: existing };
+                }
+                if (reserved.kind === 'typeMismatch') {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorTypeMismatch, `Actor '${actorId}' is registered with another stable type.`);
+                }
+                if (reserved.kind === 'placementCapacityExhausted') {
+                    excluded.add(String(target.nodeRid));
+                    continue;
+                }
+                if (reserved.kind === 'alreadyExists' || reserved.kind === 'conflict') {
+                    await waitForAuthorityChange(deadline.signal);
+                    continue;
+                }
+                if (reserved.kind !== 'reserved') {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${actorId}' reservation failed with '${reserved.kind}'.`, true);
+                }
+                const remote = await this.options.remoteCreate(target.meshName, String(target.nodeRid), actorCreateRecord(actorId, stableType, reserved.creating, target, deadlineUnixMs), Math.max(1, Math.ceil(deadlineMs - performance.now())));
+                if (remote.terminalResult !== runtime_values_1.RequestResult.Ok
+                    || remote.failureCode !== 0) {
+                    //  Classify the (terminal, fine failure code) pair via the shared
+                    //  ownership-aware translator instead of collapsing every non-OK
+                    //  remote create to InternalFailure (spec 32-framework-error-model:
+                    //  83-118, 99-108). Backpressured(113) still surfaces as target
+                    //  placement capacity -> CapacityExceeded through the shared path.
+                    throw (0, framework_errors_internal_1.wireReplyFailureException)(remote.terminalResult, remote.failureCode, `Remote Actor '${actorId}' creation failed with result ${remote.terminalResult}, `
+                        + `failure code ${remote.failureCode}, and tail ${remote.tail?.kind ?? 'none'}.`);
+                }
+                if (remote.tail?.kind !== 'actorCreate') {
+                    //  An OK terminal whose reply lacks the actorCreate tail is a
+                    //  protocol violation, not a create failure.
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, `Remote Actor '${actorId}' create reply carried tail `
+                        + `${remote.tail?.kind ?? 'none'} on an OK terminal.`);
+                }
+                if (remote.tail.createResult === 'rejected') {
+                    return {
+                        status: 'rejected',
+                        ...(remote.payload === undefined
+                            ? {}
+                            : {
+                                reply: this.options.decodeRemoteReply?.(remote.payload.payload)
+                                    ?? Buffer.from(remote.payload.payload)
+                            })
+                    };
+                }
+                const actor = remote.tail.actor;
+                if (actor === undefined) {
+                    //  A created/existing terminal without an ActorRef is a malformed
+                    //  reply (spec 32-framework-error-model:91-92).
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RequestProtocolError, 'Remote Actor create terminal omitted ActorRef.');
+                }
+                const ref = withActorAuthorityFence({
+                    actorId: actor.actorId,
+                    objectGeneration: actor.generation,
+                    meshName: target.meshName,
+                    nodeRid: actor.nodeRid
+                }, reserved.creating);
+                return {
+                    status: remote.tail.createResult,
+                    actor: ref,
+                    ...(remote.payload === undefined
+                        ? {}
+                        : {
+                            reply: this.options.decodeRemoteReply?.(remote.payload.payload)
+                                ?? Buffer.from(remote.payload.payload)
+                        })
+                };
+            }
+        }
+        finally {
+            deadline.close();
+        }
+    }
+    async handleRemoteCreate(record, materialize, signal) {
+        const key = { kind: 'actor', globalId: record.actorId };
+        const current = await this.options.store.readAuthority((0, authority_key_codec_1.encodeAuthorityKey)('actor', record.actorId), signal);
+        requireExactReservation(current, record);
+        if (current.kind !== 'snapshot') {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${record.actorId}' reservation is missing.`);
+        }
+        if (current.allocation.state === 'active') {
+            const identity = (0, actor_authority_publication_1.decodeActorAuthorityIdentity)(current.payload, current.objectGeneration);
+            if (identity === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${record.actorId}' Ready authority is invalid.`);
+            }
+            return actorResult('existing', identity.actor);
+        }
+        const pending = current.pendingCreation;
+        const requestPayload = (0, user_spot_creation_coordinator_1.decodeLocationCreationContent)(pending.requestContentReference, pending.requestSha256, pending.requestEncodedSize);
+        let local;
+        let completion;
+        try {
+            local = await materialize(requestPayload, current, signal);
+            const terminal = encodeActorTerminal(record.correlation, local.result, local.actor);
+            completion = await this.options.store.completeCreation({
+                key,
+                reservationId: record.reservation.reservationId,
+                expectedStoreVersion: current.storeVersion.value,
+                target: creationTarget(current),
+                completion: local.result === 'created'
+                    ? {
+                        kind: 'created',
+                        readyPayload: (0, actor_authority_publication_1.encodeActorAuthorityIdentity)({
+                            actorType: record.stableType,
+                            actor: local.actor,
+                            meshName: current.allocation.descriptor.meshName,
+                            ownerNodeGeneration: current.allocation.descriptorLifecycleGeneration,
+                            owner: {
+                                ownerId: current.ownerId,
+                                leaseGeneration: current.ownerLeaseGeneration
+                            },
+                            spotId: local.entrySpotId,
+                            spotGeneration: local.entrySpotGeneration,
+                            spotKind: contracts_1.ZLinkSpotKind.Entry
+                        }),
+                        terminal: terminalPublication(record, terminal)
+                    }
+                    : {
+                        kind: 'rejected',
+                        terminal: terminalPublication(record, terminal)
+                    }
+            }, signal);
+        }
+        catch (error) {
+            const cleanup = createDeadline(1_000);
+            try {
+                await this.options.store.abort({
+                    key,
+                    reservationId: record.reservation.reservationId,
+                    expectedStoreVersion: current.storeVersion.value,
+                    target: creationTarget(current)
+                }, cleanup.signal);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], `Actor '${record.actorId}' creation and reservation rollback both failed.`);
+            }
+            finally {
+                cleanup.close();
+            }
+            throw error;
+        }
+        if (local.result === 'created'
+            ? completion.kind !== 'created' && completion.kind !== 'alreadyCompleted'
+            : completion.kind !== 'rejected' && completion.kind !== 'alreadyCompleted') {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${record.actorId}' creation completion lost its reservation.`);
+        }
+        if (local.result === 'created')
+            local.onPublished?.();
+        return actorResult(local.result, local.actor, local.reply);
+    }
+}
+exports.ZLinkActorPlacementCoordinator = ZLinkActorPlacementCoordinator;
+function creationTarget(snapshot) {
+    return {
+        meshName: snapshot.allocation.descriptor.meshName,
+        nodeRid: snapshot.allocation.descriptor.rid,
+        nodeLifecycleGeneration: snapshot.allocation.descriptorLifecycleGeneration,
+        owner: {
+            ownerId: snapshot.ownerId,
+            leaseGeneration: snapshot.ownerLeaseGeneration
+        }
+    };
+}
+function existingActor(reserved, actorId, stableType) {
+    const snapshot = reserved.kind === 'alreadyExists'
+        ? reserved.current
+        : reserved.kind === 'conflict' && reserved.current.kind === 'snapshot'
+            ? reserved.current
+            : undefined;
+    if (snapshot === undefined
+        || snapshot.allocation.state !== 'active'
+        || snapshot.allocation.objectKind !== 'actor'
+        || snapshot.allocation.stableType !== stableType) {
+        return undefined;
+    }
+    const identity = (0, actor_authority_publication_1.decodeActorAuthorityIdentity)(snapshot.payload, snapshot.objectGeneration);
+    return identity?.actor.actorId === actorId
+        ? withActorAuthorityFence(identity.actor, snapshot)
+        : undefined;
+}
+function withActorAuthorityFence(actor, authority) {
+    Object.defineProperties(actor, {
+        ownershipGeneration: {
+            configurable: false,
+            enumerable: false,
+            value: authority.authorityOwnerGeneration
+        },
+        ownerLeaseGeneration: {
+            configurable: false,
+            enumerable: false,
+            value: authority.ownerLeaseGeneration
+        }
+    });
+    return actor;
+}
+function actorCreateRecord(actorId, stableType, snapshot, target, deadlineUnixMs) {
+    const pending = snapshot.pendingCreation;
+    if (pending === undefined)
+        throw new Error('Actor reservation omitted Pending creation.');
+    return {
+        sourceNodeRid: '',
+        sourceNodeGeneration: 1n,
+        actorId,
+        stableType,
+        reservation: reservationFence(snapshot, target, pending.reservationId),
+        deadlineUnixMs: BigInt(deadlineUnixMs)
+    };
+}
+function reservationFence(snapshot, target, reservationId) {
+    return {
+        reservationId,
+        expectedStoreVersion: snapshot.storeVersion.value,
+        objectGeneration: snapshot.objectGeneration,
+        authorityOwnerGeneration: snapshot.authorityOwnerGeneration,
+        targetNodeRid: String(target.nodeRid),
+        targetNodeGeneration: target.nodeGeneration,
+        targetOwnerId: target.owner.ownerId,
+        targetOwnerLeaseGeneration: target.owner.leaseGeneration,
+        pendingCapacityDelta: 1
+    };
+}
+function reservationTarget(target) {
+    return {
+        meshName: target.meshName,
+        nodeRid: target.nodeRid,
+        nodeLifecycleGeneration: target.nodeGeneration,
+        owner: target.owner
+    };
+}
+function requireExactReservation(current, record) {
+    const pending = current.kind === 'snapshot' ? current.pendingCreation : undefined;
+    if (current.kind !== 'snapshot'
+        || current.allocation.objectKind !== 'actor'
+        || current.allocation.stableType !== record.stableType
+        || current.objectGeneration !== record.reservation.objectGeneration
+        || current.authorityOwnerGeneration !== record.reservation.authorityOwnerGeneration
+        || String(current.allocation.descriptor.rid) !== record.reservation.targetNodeRid
+        || current.allocation.descriptorLifecycleGeneration !== record.reservation.targetNodeGeneration
+        || current.ownerId !== record.reservation.targetOwnerId
+        || current.ownerLeaseGeneration !== record.reservation.targetOwnerLeaseGeneration
+        || (current.allocation.state === 'reserved'
+            && (current.storeVersion.value !== record.reservation.expectedStoreVersion
+                || pending?.reservationId !== record.reservation.reservationId))) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${record.actorId}' reservation fence is stale.`, true);
+    }
+}
+function actorResult(createResult, actor, reply) {
+    return {
+        terminalResult: runtime_values_1.RequestResult.Ok,
+        failureCode: 0,
+        tail: {
+            kind: 'actorCreate',
+            createResult,
+            ...(actor === undefined
+                ? {}
+                : {
+                    actor: {
+                        actorId: actor.actorId,
+                        generation: actor.objectGeneration,
+                        nodeRid: String(actor.nodeRid)
+                    }
+                })
+        },
+        ...(reply === undefined
+            ? {}
+            : {
+                payload: {
+                    packetName: 'ZLinkFrameworkActorCreateReply',
+                    contentType: 'application/octet-stream',
+                    payload: Buffer.from(reply)
+                }
+            })
+    };
+}
+function encodeActorTerminal(correlation, result, actor) {
+    return Buffer.from(JSON.stringify({
+        correlation: correlation.toString(),
+        result,
+        actor: actor === undefined
+            ? undefined
+            : {
+                actorId: actor.actorId,
+                generation: actor.objectGeneration.toString(),
+                meshName: actor.meshName,
+                nodeRid: String(actor.nodeRid)
+            }
+    }));
+}
+function terminalPublication(record, terminalEnvelope) {
+    return {
+        operation: {
+            sourceNodeRid: record.sourceNodeRid,
+            sourceNodeGeneration: record.sourceNodeGeneration,
+            operationId: record.operation
+        },
+        terminalEnvelope,
+        terminalEnvelopeSha256: (0, node_crypto_1.createHash)('sha256').update(terminalEnvelope).digest(),
+        operationDeadline: new Date(Number(record.deadlineUnixMs))
+    };
+}
+function createDeadline(timeoutMs, parent) {
+    const controller = new AbortController();
+    const abort = () => controller.abort(parent?.reason);
+    parent?.addEventListener('abort', abort, { once: true });
+    const timer = setTimeout(() => controller.abort(new Error('Actor creation deadline exceeded.')), Math.max(1, timeoutMs));
+    return {
+        signal: controller.signal,
+        close: () => {
+            clearTimeout(timer);
+            parent?.removeEventListener('abort', abort);
+        }
+    };
+}
+async function waitForAuthorityChange(signal) {
+    signal.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(finish, 10);
+        const abort = () => finish(signal.reason ?? new Error('Actor creation was aborted.'));
+        function finish(error) {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            error === undefined ? resolve() : reject(error);
+        }
+        signal.addEventListener('abort', abort, { once: true });
+    });
+}

package/dist/runtime/host/actor-runtime-options-factory.d.ts

@@ -0,0 +1,65 @@
+import type { ActorRef, RoutingId, ZLinkActor, ZLinkMessage } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { type ZLinkBackendMeshNode, type ZLinkMeshCompletionTable } from '../backend';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import type { DefaultZLinkActorManager } from '../actors';
+import type { DefaultZLinkSpotManager } from '../spots';
+import type { ZLinkSpotRouteResolver } from '../spots/spot-routing-internal';
+import { DefaultZLinkActorClient, type ZLinkActorTransferRegistry, type ZLinkActorManagerOptions } from '../actors';
+import type { ZLinkActorHandoffCoordinator } from '../actors';
+import { type ZLinkActorRoutedJoinTransport } from '../actors';
+import type { ZLinkLocationLifecycle, ZLinkStoreLocationResolvers } from '../locations';
+import type { ZLinkNativeFallbackBoundSessionPort, ZLinkStreamActorLifecyclePort } from '../streams/stream-binding-runtime-ports';
+import type { ZLinkActorTransferRuntime } from './actor-transfer-runtime';
+import type { ZLinkRuntimeAdmissionGate } from '../admission';
+import type { ZLinkRemoteActorPacketTarget } from '../actors';
+import type { ZLinkActorJoinRelocation } from '../actors/actor-join-relocation';
+export interface ZLinkActorRuntimeOptionsFactoryOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    /** Message flow tracer, so a failed deferred Join records its cause on the flow. */
+    readonly messageFlow?: () => import('../diagnostics/message-flow').ZLinkMessageFlowTracer | undefined;
+    readonly routeTransport: ZLinkActorRoutedJoinTransport;
+    readonly streamBindingRuntime: ZLinkStreamActorLifecyclePort & ZLinkNativeFallbackBoundSessionPort;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly spotManager: () => DefaultZLinkSpotManager | undefined;
+    readonly actorManager: () => DefaultZLinkActorManager | undefined;
+    readonly primaryMeshNode: () => ZLinkBackendMeshNode;
+    readonly primaryMeshNodeOrUndefined: () => ZLinkBackendMeshNode | undefined;
+    readonly primaryMeshCompletions: () => ZLinkMeshCompletionTable | undefined;
+    readonly meshNode: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly meshCompletions: (meshName: string) => ZLinkMeshCompletionTable | undefined;
+    readonly notifyEntrySpotActorCreated: (nodeRid: RoutingId, actor: ZLinkActor, createRequest: ZLinkMessage, signal?: AbortSignal) => Promise<import('../../contracts').ZLinkActorCreateResponse | undefined>;
+    readonly locationLifecycle: () => ZLinkLocationLifecycle | undefined;
+    readonly primaryMeshName: () => string | undefined;
+    readonly actorMeshName: (actorType: string) => string | undefined;
+    readonly createLocationSpotRouteResolver: () => ZLinkSpotRouteResolver | undefined;
+    readonly createActorLocationResolver: () => ZLinkStoreLocationResolvers | undefined;
+    readonly forgetDestroyedActorRef: (actorId: string) => void;
+    readonly rememberDestroyedActorRef: (actorId: string, actorRef: ActorRef) => void;
+    /**
+     * Drops a cached direct route when the local Actor incarnation changes.
+     * Authority deletion and recreation are separate store mutations, so a
+     * positive route cache must not bridge the two incarnations.
+     */
+    readonly invalidateActorRoute: (actorId: string) => void;
+    readonly publishActorAuthority: NonNullable<ZLinkActorManagerOptions['publishActorAuthority']>;
+    readonly reportPostCommitError: (error: unknown) => void;
+    readonly reportBoundSessionSendError: (error: unknown) => void;
+    readonly actorHandoff: ZLinkActorHandoffCoordinator;
+    readonly actorTransferRuntime: ZLinkActorTransferRuntime;
+    readonly actorJoinRelocation: ZLinkActorJoinRelocation;
+    readonly actorTransferRegistry: ZLinkActorTransferRegistry;
+    readonly shutdownSignal: () => AbortSignal | undefined;
+    readonly metrics: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly traceBoundSessionSend?: (actorId: string, packetName: string) => void;
+    readonly flowCreationEnabled?: () => boolean;
+    readonly admission: ZLinkRuntimeAdmissionGate;
+    readonly actorPacketTargetForState: (actorId: string) => ZLinkRemoteActorPacketTarget | undefined;
+}
+export declare class ZLinkActorRuntimeOptionsFactory {
+    private readonly options;
+    constructor(options: ZLinkActorRuntimeOptionsFactoryOptions);
+    createActorManagerOptions(): Pick<ZLinkActorManagerOptions, 'joinCoordinator' | 'actorMeshNameProvider' | 'actorLeaveSpot' | 'messageSerializers' | 'nativeActorNode' | 'nativeActorNodeProvider' | 'nativeActorCompletionTableProvider' | 'actorCreatedNodeRidProvider' | 'actorRefResolver' | 'actorCreatedNotifier' | 'actorDestroyedCleanup' | 'publishActorAuthority' | 'locationLifecycle' | 'boundSessionFactory' | 'actorTransferRegistry' | 'shutdownSignal' | 'metrics' | 'admission'>;
+    createActorClientOptions(): ConstructorParameters<typeof DefaultZLinkActorClient>[0];
+    private actorBelongsToMesh;
+}

package/dist/runtime/host/actor-runtime-options-factory.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorRuntimeOptionsFactory = void 0;
+const backend_1 = require("../backend");
+const actors_1 = require("../actors");
+const actor_transport_delivery_gate_1 = require("../actors/actor-transport-delivery-gate");
+const native_fallback_bound_session_1 = require("../streams/native-fallback-bound-session");
+class ZLinkActorRuntimeOptionsFactory {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    createActorManagerOptions() {
+        const actorTransferRegistry = this.options.actorTransferRegistry;
+        return {
+            actorMeshNameProvider: this.options.actorMeshName,
+            actorLeaveSpot: (meshName, spotId, actor, signal) => {
+                const spotManager = this.options.spotManager();
+                if (spotManager === undefined) {
+                    throw new Error('Actor Spot lifecycle runtime is not started.');
+                }
+                return spotManager.leaveActorInMesh(meshName, spotId, actor, signal);
+            },
+            joinCoordinator: new actors_1.ZLinkActorNativeJoinCoordinator({
+                messageFlow: () => this.options.messageFlow?.(),
+                node: this.options.primaryMeshNode,
+                completionTableProvider: this.options.primaryMeshCompletions,
+                spotRouteResolver: this.options.createLocationSpotRouteResolver(),
+                locationLifecycle: this.options.locationLifecycle(),
+                postCommitErrorReporter: this.options.reportPostCommitError,
+                sourceTransfer: this.options.actorTransferRuntime,
+                actorJoinRelocation: this.options.actorJoinRelocation,
+                entrySpotIdProvider: meshName => {
+                    const resolvedMeshName = meshName ?? this.options.primaryMeshName();
+                    return resolvedMeshName === undefined
+                        ? undefined
+                        : this.options.spotManager()?.entrySpotIdForMesh(resolvedMeshName);
+                },
+                remoteActorBinder: (actorRef, signal) => this.options.streamBindingRuntime.commitActorRoute(actorRef, signal),
+                messageSerializers: this.options.registration.messageSerializers,
+                actorTransferTimeoutMs: this.options.registration.actorTransferTimeoutMs,
+                shutdownSignal: this.options.shutdownSignal()
+            }),
+            messageSerializers: this.options.registration.messageSerializers,
+            actorTransferRegistry,
+            shutdownSignal: this.options.shutdownSignal(),
+            metrics: this.options.metrics,
+            admission: this.options.admission,
+            nativeActorNodeProvider: this.options.primaryMeshNodeOrUndefined,
+            nativeActorCompletionTableProvider: this.options.primaryMeshCompletions,
+            locationLifecycle: this.options.locationLifecycle(),
+            boundSessionFactory: (actorId) => new native_fallback_bound_session_1.ZLinkNativeFallbackBoundSession({
+                runtime: this.options.streamBindingRuntime,
+                routedTransport: this.options.routeTransport,
+                actorRefProvider: () => {
+                    const state = this.options.actorManager()?.getState(actorId);
+                    const actorRef = state?.nativeActorRef;
+                    const meshName = state?.meshName
+                        ?? (state?.actorType === undefined
+                            ? undefined
+                            : this.options.actorMeshName(state.actorType));
+                    const objectGeneration = actorRef?.generation
+                        ?? actorRef
+                            ?.objectGeneration;
+                    return actorRef === undefined || objectGeneration === undefined
+                        ? undefined
+                        : {
+                            actorId: actorRef.actorId,
+                            objectGeneration,
+                            meshName: meshName ?? this.options.primaryMeshName() ?? '',
+                            nodeRid: actorRef.nodeRid,
+                            ownershipGeneration: state?.locationGeneration,
+                            ownerLeaseGeneration: state?.ownerLeaseGeneration,
+                            bindingGeneration: state?.boundSessionBindingGeneration
+                        };
+                },
+                nativeActorNodeProvider: () => {
+                    const state = this.options.actorManager()?.getState(actorId);
+                    const meshName = state?.meshName
+                        ?? (state?.actorType === undefined
+                            ? undefined
+                            : this.options.actorMeshName(state.actorType));
+                    const node = meshName === undefined
+                        ? this.options.primaryMeshNodeOrUndefined()
+                        : this.options.meshNode(meshName);
+                    const completions = meshName === undefined
+                        ? this.options.primaryMeshCompletions()
+                        : this.options.meshCompletions(meshName);
+                    return node === undefined
+                        ? undefined
+                        : (0, backend_1.meshActorSessionNodeAdapter)(node, completions);
+                },
+                localActorProvider: () => this.options.actorManager()?.getState(actorId)?.actor !== undefined,
+                remoteBoundSessionTargetProvider: () => {
+                    const state = this.options.actorManager()?.getState(actorId);
+                    return (0, actors_1.preferredRemoteBoundSessionTarget)(state?.remoteBoundSessionTarget, state?.boundSessionTransferTarget);
+                },
+                remoteActorPacketTargetProvider: () => this.options.actorPacketTargetForState(actorId),
+                requestTimeoutMs: this.options.registration.requestTimeoutMs,
+                actorId,
+                onSend: this.options.traceBoundSessionSend,
+                reportError: this.options.reportBoundSessionSendError,
+                flowCreationEnabled: this.options.flowCreationEnabled
+            }),
+            actorCreatedNodeRidProvider: () => {
+                const node = this.options.primaryMeshNodeOrUndefined();
+                return node === undefined ? undefined : String(node.status().routingId);
+            },
+            actorRefResolver: {
+                resolveActorRef: async (actorId, signal) => await this.options.createActorLocationResolver()?.resolveActorRef(actorId, signal)
+            },
+            actorCreatedNotifier: (nodeRid, actor, createRequest, signal) => {
+                this.options.forgetDestroyedActorRef(actor.context.actorId);
+                return this.options.notifyEntrySpotActorCreated(nodeRid, actor, createRequest, signal);
+            },
+            actorDestroyedCleanup: (actorId) => {
+                this.options.invalidateActorRoute(actorId);
+                const actorRef = this.options.actorManager()?.getState(actorId)?.nativeActorRef;
+                if (actorRef !== undefined) {
+                    this.options.rememberDestroyedActorRef(actorId, actorRef);
+                }
+                this.options.streamBindingRuntime.unbindActor(actorId);
+            },
+            publishActorAuthority: this.options.publishActorAuthority
+        };
+    }
+    createActorClientOptions() {
+        const locationResolver = this.options.createActorLocationResolver();
+        return {
+            nodeProvider: this.options.meshNode,
+            completionTableProvider: this.options.meshCompletions,
+            locationResolver: () => locationResolver,
+            routeTransport: this.options.routeTransport,
+            transportDeliveryGate: () => this.options.providerResolver?.get?.(actor_transport_delivery_gate_1.ZLINK_INTERNAL_ACTOR_TRANSPORT_DELIVERY_GATE),
+            messageSerializers: this.options.registration.messageSerializers,
+            defaultRequestTimeoutMs: this.options.registration.requestTimeoutMs,
+            staleActorRefReporter: (_meshName, actorId) => this.options.actorHandoff.recordStaleFailure(actorId),
+            staleActorRefPredicate: (meshName, actor) => this.actorBelongsToMesh(meshName, actor.actorId)
+                && this.options.actorHandoff.isKnownStale(actor),
+            handoffCapture: (meshName, actorId, parts, returnResponse, actor, deadlineUnixMs) => this.actorBelongsToMesh(meshName, actorId)
+                && !this.options.actorHandoff.isProvisional(actorId)
+                ? this.options.actorHandoff.capture(actorId, parts, returnResponse, undefined, actor, deadlineUnixMs)
+                : undefined,
+            sendErrorReporter: this.options.reportPostCommitError
+        };
+    }
+    actorBelongsToMesh(meshName, actorId) {
+        const actorType = this.options.actorManager()?.getState(actorId)?.actorType;
+        if (actorType !== undefined) {
+            return this.options.actorMeshName(actorType) === meshName;
+        }
+        const actorMeshes = [...this.options.registration.spotNodes.entries()]
+            .filter(([, node]) => node.actorFactories instanceof Map
+            ? node.actorFactories.size > 0
+            : Object.keys(node.actorFactories ?? {}).length > 0)
+            .map(([name]) => name);
+        return actorMeshes.length === 1 && actorMeshes[0] === meshName;
+    }
+}
+exports.ZLinkActorRuntimeOptionsFactory = ZLinkActorRuntimeOptionsFactory;