@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,545 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorRuntimeState = void 0;
+exports.mergeRemoteBoundSessionTarget = mergeRemoteBoundSessionTarget;
+exports.preferredRemoteBoundSessionTarget = preferredRemoteBoundSessionTarget;
+exports.toFrameworkRoutingId = toFrameworkRoutingId;
+exports.toFrameworkActorRef = toFrameworkActorRef;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const routing_id_1 = require("../routing-id");
+const actor_native_lookup_1 = require("./actor-native-lookup");
+/**
+ * Applies a lightweight Session binding refresh without discarding the
+ * relocation fence that was staged for the same route. Core emits the bind
+ * refresh with routing coordinates only; the relocation owner retains the
+ * service-wire relocation identity until command 44 releases the owner seal.
+ */
+function mergeRemoteBoundSessionTarget(target, fallback) {
+    if (fallback === undefined
+        || fallback.routerChannelId !== target.routerChannelId
+        || !(0, routing_id_1.routingIdsEqual)(fallback.targetNodeRid, target.targetNodeRid)
+        || (!(0, routing_id_1.routingIdsEqual)(fallback.spotId, target.spotId)
+            && !samePhysicalRemoteSession(fallback, target))
+        || isSuccessorSessionBinding(fallback, target)) {
+        return target;
+    }
+    const merged = {
+        ...fallback,
+        ...target,
+        sessionNodeRid: target.sessionNodeRid ?? fallback.sessionNodeRid,
+        sessionRid: target.sessionRid ?? fallback.sessionRid,
+        sessionOwnerNodeGeneration: target.sessionOwnerNodeGeneration ?? fallback.sessionOwnerNodeGeneration,
+        sessionOwnerId: target.sessionOwnerId ?? fallback.sessionOwnerId,
+        sessionOwnerLeaseGeneration: target.sessionOwnerLeaseGeneration ?? fallback.sessionOwnerLeaseGeneration,
+        bindingGeneration: target.bindingGeneration ?? fallback.bindingGeneration,
+        previousAuthorityOwnerGeneration: target.previousAuthorityOwnerGeneration ?? fallback.previousAuthorityOwnerGeneration,
+        previousOwnerLeaseGeneration: target.previousOwnerLeaseGeneration ?? fallback.previousOwnerLeaseGeneration,
+        relocationSealId: target.relocationSealId ?? fallback.relocationSealId,
+        serviceWireRelocation: target.serviceWireRelocation ?? fallback.serviceWireRelocation
+    };
+    return merged;
+}
+/**
+ * Spec 48 §125: reconnection creates a new Session; the previous Session's
+ * binding — and its staged relocation fence — is never inherited by a
+ * successor. A Core bind refresh only omits routing coordinates it did not
+ * recompute, so an explicit Session identity on both sides that disagrees
+ * marks the refresh as belonging to a different Session binding, not a
+ * same-Session coordinate/generation-only refresh (a bindingGeneration bump
+ * with the same sessionNodeRid/sessionRid is a legitimate same-Session
+ * refresh and must keep the fence — see the transfer-target generation test
+ * below).
+ *
+ * NOTE: this identity check is a no-op on the path exercised by
+ * `remoteBoundSessionTargetForSource` (mesh-router-resolver.ts), which never
+ * populates sessionNodeRid/sessionRid on the refresh it emits. Confirmed via
+ * TTT reproduction (2026-08-22, run-dir preserved) that a rejected successor
+ * bound-session send still occurs through that path after this change; see
+ * session report for the STOP writeup.
+ */
+function isSuccessorSessionBinding(fallback, target) {
+    return (fallback.sessionNodeRid !== undefined
+        && target.sessionNodeRid !== undefined
+        && !(0, routing_id_1.routingIdsEqual)(fallback.sessionNodeRid, target.sessionNodeRid)) || (fallback.sessionRid !== undefined
+        && target.sessionRid !== undefined
+        && !(0, routing_id_1.routingIdsEqual)(fallback.sessionRid, target.sessionRid)) || (fallback.sessionOwnerNodeGeneration !== undefined
+        && target.sessionOwnerNodeGeneration !== undefined
+        && fallback.sessionOwnerNodeGeneration !== target.sessionOwnerNodeGeneration) || (fallback.sessionOwnerId !== undefined
+        && target.sessionOwnerId !== undefined
+        && fallback.sessionOwnerId !== target.sessionOwnerId) || (fallback.sessionOwnerLeaseGeneration !== undefined
+        && target.sessionOwnerLeaseGeneration !== undefined
+        && fallback.sessionOwnerLeaseGeneration !== target.sessionOwnerLeaseGeneration);
+}
+function samePhysicalRemoteSession(left, right) {
+    return left.sessionNodeRid !== undefined
+        && right.sessionNodeRid !== undefined
+        && left.sessionRid !== undefined
+        && right.sessionRid !== undefined
+        && (0, routing_id_1.routingIdsEqual)(left.sessionNodeRid, right.sessionNodeRid)
+        && (0, routing_id_1.routingIdsEqual)(left.sessionRid, right.sessionRid);
+}
+function sameRemoteSessionOwnerLifecycle(left, right) {
+    return left.sessionNodeRid !== undefined
+        && right.sessionNodeRid !== undefined
+        && left.sessionOwnerNodeGeneration !== undefined
+        && right.sessionOwnerNodeGeneration !== undefined
+        && left.sessionOwnerId !== undefined
+        && right.sessionOwnerId !== undefined
+        && left.sessionOwnerLeaseGeneration !== undefined
+        && right.sessionOwnerLeaseGeneration !== undefined
+        && (0, routing_id_1.routingIdsEqual)(left.sessionNodeRid, right.sessionNodeRid)
+        && left.sessionOwnerNodeGeneration === right.sessionOwnerNodeGeneration
+        && left.sessionOwnerId === right.sessionOwnerId
+        && left.sessionOwnerLeaseGeneration === right.sessionOwnerLeaseGeneration;
+}
+function sameRemoteSessionOwner(left, right) {
+    return left.sessionRid !== undefined
+        && right.sessionRid !== undefined
+        && (0, routing_id_1.routingIdsEqual)(left.sessionRid, right.sessionRid)
+        && sameRemoteSessionOwnerLifecycle(left, right);
+}
+function sameRemoteSessionBinding(left, right) {
+    return sameRemoteSessionOwner(left, right)
+        && left.bindingGeneration !== undefined
+        && right.bindingGeneration !== undefined
+        && left.bindingGeneration === right.bindingGeneration;
+}
+/**
+ * Selects the route that still carries the relocation fence when a Core
+ * binding refresh and a formal transfer target temporarily coexist.
+ */
+function preferredRemoteBoundSessionTarget(remote, transfer) {
+    if (remote === undefined)
+        return transfer;
+    if (hasRelocationFence(remote) || transfer === undefined)
+        return remote;
+    return transfer;
+}
+function hasRelocationFence(target) {
+    return target.relocationSealId !== undefined
+        || target.serviceWireRelocation !== undefined;
+}
+class ZLinkActorRuntimeState {
+    actorId;
+    creationTask;
+    configured = false;
+    context;
+    actorTypeValue;
+    meshNameValue;
+    actorValue;
+    spotValue;
+    spotIdValue;
+    spotGenerationValue;
+    spotMembershipEpochValue = 0n;
+    nativeActorRefValue;
+    boundSessionBindingGenerationValue = 0n;
+    entryNodeRidValue;
+    remoteBoundSessionTargetValue;
+    boundSessionTransferTargetValue;
+    remoteActorPacketTargetValue;
+    createRequestPayloadValue;
+    ownsLocationValue = false;
+    locationGenerationValue;
+    ownerLeaseGenerationValue;
+    movingValue = false;
+    deferredJoinPendingValue = false;
+    destroyTask;
+    constructor(actorId) {
+        this.actorId = actorId;
+    }
+    get actorType() {
+        return this.actorTypeValue;
+    }
+    // The manager resolves RouteMesh membership once when it registers the
+    // actor, so identity reads never re-enter the application provider.
+    get meshName() {
+        return this.meshNameValue;
+    }
+    rememberMeshName(meshName) {
+        this.meshNameValue = meshName;
+    }
+    get actor() {
+        return this.actorValue;
+    }
+    get spot() {
+        return this.spotValue;
+    }
+    get spotId() {
+        return this.spotIdValue;
+    }
+    get spotMembershipEpoch() {
+        return this.spotMembershipEpochValue;
+    }
+    get spotGeneration() {
+        return this.spotGenerationValue;
+    }
+    get nativeActorRef() {
+        return this.nativeActorRefValue;
+    }
+    get boundSessionBindingGeneration() {
+        return this.boundSessionBindingGenerationValue;
+    }
+    get entryNodeRid() {
+        return this.entryNodeRidValue;
+    }
+    get remoteBoundSessionTarget() {
+        return this.remoteBoundSessionTargetValue;
+    }
+    get boundSessionTransferTarget() {
+        return this.boundSessionTransferTargetValue;
+    }
+    get remoteActorPacketTarget() {
+        return this.remoteActorPacketTargetValue;
+    }
+    get createRequestPayload() {
+        return this.createRequestPayloadValue;
+    }
+    get isJoined() {
+        return this.spotIdValue !== undefined;
+    }
+    get ownsLocation() {
+        return this.ownsLocationValue;
+    }
+    get locationGeneration() {
+        return this.locationGenerationValue;
+    }
+    get ownerLeaseGeneration() {
+        return this.ownerLeaseGenerationValue;
+    }
+    get isMoving() {
+        return this.movingValue;
+    }
+    tryBeginDeferredJoin() {
+        if (this.movingValue || this.deferredJoinPendingValue) {
+            return false;
+        }
+        this.deferredJoinPendingValue = true;
+        return true;
+    }
+    endDeferredJoin() {
+        this.deferredJoinPendingValue = false;
+    }
+    get hasActorOrCreation() {
+        return this.actorValue !== undefined || this.creationTask !== undefined;
+    }
+    beginMove() {
+        if (this.deferredJoinPendingValue) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorMoving, `Actor '${this.actorId}' has a pending membership transition.`, true);
+        }
+        if (this.movingValue) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${this.actorId}' is already moving.`);
+        }
+        this.movingValue = true;
+    }
+    endMove() {
+        this.movingValue = false;
+    }
+    markLocationOwned() {
+        this.ownsLocationValue = true;
+    }
+    markLocationReleased() {
+        this.ownsLocationValue = false;
+    }
+    setLocationGeneration(generation) {
+        this.locationGenerationValue = generation;
+    }
+    setOwnerLeaseGeneration(generation) {
+        this.ownerLeaseGenerationValue = generation;
+    }
+    getOrStartDestroy(entryNodeRid, destroy) {
+        if (this.destroyTask !== undefined) {
+            return this.destroyTask;
+        }
+        const actorRef = this.nativeActorRefValue;
+        if (actorRef !== undefined && !(0, routing_id_1.routingIdsEqual)(toFrameworkRoutingId(actorRef.nodeRid), entryNodeRid)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${this.actorId}' is not owned by this Entry Spot.`);
+        }
+        const task = Promise.resolve().then(() => destroy(actorRef));
+        this.destroyTask = task;
+        return task;
+    }
+    markNativeActorDestroyed(actorRef) {
+        if (this.nativeActorRefValue === actorRef) {
+            this.nativeActorRefValue = undefined;
+        }
+    }
+    clearFailedDestroy(task) {
+        if (this.destroyTask === task) {
+            this.destroyTask = undefined;
+        }
+        this.movingValue = false;
+    }
+    ensureContext(createContext) {
+        this.context ??= createContext();
+        return this.context;
+    }
+    getOrStartCreation(actorType, failIfExists, createActor) {
+        if (this.actorTypeValue !== undefined && this.actorTypeValue !== actorType) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorTypeMismatch, `Actor '${this.actorId}' already uses actor type '${this.actorTypeValue}', not '${actorType}'.`);
+        }
+        if (this.actorValue !== undefined) {
+            if (failIfExists) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorAlreadyExists, `Actor '${this.actorId}' already exists.`);
+            }
+            return {
+                task: Promise.resolve({ status: 'created', actor: this.actorValue }),
+                created: false
+            };
+        }
+        if (this.creationTask !== undefined) {
+            if (failIfExists) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorAlreadyExists, `Actor '${this.actorId}' is already being created.`);
+            }
+            return { task: this.creationTask, created: false };
+        }
+        this.actorTypeValue = actorType;
+        this.creationTask = createActor();
+        return { task: this.creationTask, created: true };
+    }
+    clearFailedCreation(task) {
+        if (this.creationTask === task && this.actorValue === undefined) {
+            this.creationTask = undefined;
+            this.actorTypeValue = undefined;
+            this.createRequestPayloadValue = undefined;
+            this.configured = false;
+            this.nativeActorRefValue = undefined;
+            this.entryNodeRidValue = undefined;
+            return true;
+        }
+        return false;
+    }
+    bindActor(actor, context) {
+        if (actor.context.actorId !== this.actorId) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor state id '${this.actorId}' does not match actor id '${actor.context.actorId}'.`);
+        }
+        if (actor.context !== context) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorCreateFailed, `Actor '${this.actorId}' must expose the context provided by its factory.`);
+        }
+        this.actorValue = actor;
+        this.creationTask = undefined;
+        if (!this.configured) {
+            actor.configure?.();
+            this.configured = true;
+        }
+    }
+    ensureNativeActorRef(node, request) {
+        if (this.nativeActorRefValue === undefined) {
+            const existing = (0, actor_native_lookup_1.lookupNativeActorRef)(node, this.actorId);
+            const native = existing ?? node.createActor(this.actorId, request === undefined ? undefined : Buffer.from(request.data()));
+            this.nativeActorRefValue = {
+                nodeRid: native.nodeRid,
+                actorId: native.actorId,
+                generation: native.generation
+            };
+        }
+        this.entryNodeRidValue ??= toFrameworkRoutingId(this.nativeActorRefValue.nodeRid);
+        return this.nativeActorRefValue;
+    }
+    setNativeActorRef(actorRef) {
+        this.nativeActorRefValue = actorRef;
+        this.entryNodeRidValue ??= toFrameworkRoutingId(actorRef.nodeRid);
+    }
+    setBoundSessionBindingGeneration(generation) {
+        if (generation > this.boundSessionBindingGenerationValue) {
+            this.boundSessionBindingGenerationValue = generation;
+            if (this.remoteBoundSessionTargetValue !== undefined) {
+                this.remoteBoundSessionTargetValue = {
+                    ...this.remoteBoundSessionTargetValue,
+                    bindingGeneration: generation
+                };
+            }
+            if (this.boundSessionTransferTargetValue !== undefined) {
+                this.boundSessionTransferTargetValue = {
+                    ...this.boundSessionTransferTargetValue,
+                    bindingGeneration: generation
+                };
+            }
+        }
+    }
+    /** @internal Installs one authority-confirmed binding inside its Actor owner turn. */
+    installBoundSessionBinding(target) {
+        if (target.sessionNodeRid === undefined
+            || target.sessionRid === undefined
+            || target.sessionOwnerNodeGeneration === undefined
+            || target.sessionOwnerId === undefined
+            || target.sessionOwnerLeaseGeneration === undefined
+            || target.bindingGeneration === undefined) {
+            throw new TypeError('An installed bound Session target requires its complete binding identity.');
+        }
+        const current = preferredRemoteBoundSessionTarget(this.remoteBoundSessionTargetValue, this.boundSessionTransferTargetValue);
+        if (current !== undefined && sameRemoteSessionOwnerLifecycle(current, target)) {
+            // A duplicate command for the exact physical Session is idempotent. A
+            // different Session in the same owner lifecycle must advance that
+            // lifecycle's generation; a late equal/lower generation is stale.
+            if (sameRemoteSessionOwner(current, target))
+                return true;
+            if (current.bindingGeneration !== undefined
+                && current.bindingGeneration >= target.bindingGeneration)
+                return false;
+        }
+        const installed = mergeRemoteBoundSessionTarget(target, current);
+        // Binding generations are scoped to a Session-owner lifecycle. A restarted
+        // owner can legitimately reset its counter below the predecessor value.
+        this.boundSessionBindingGenerationValue = target.bindingGeneration;
+        this.remoteBoundSessionTargetValue = undefined;
+        this.boundSessionTransferTargetValue = {
+            ...installed,
+            bindingGeneration: target.bindingGeneration
+        };
+        return true;
+    }
+    /** @internal Removes only the exact authority-confirmed Session incarnation. */
+    retireBoundSessionBinding(target) {
+        if (target.sessionNodeRid === undefined
+            || target.sessionRid === undefined
+            || target.sessionOwnerNodeGeneration === undefined
+            || target.sessionOwnerId === undefined
+            || target.sessionOwnerLeaseGeneration === undefined
+            || target.bindingGeneration === undefined) {
+            throw new TypeError('A retired bound Session target requires its complete binding identity.');
+        }
+        let retired = false;
+        if (this.remoteBoundSessionTargetValue !== undefined
+            && sameRemoteSessionBinding(this.remoteBoundSessionTargetValue, target)) {
+            this.remoteBoundSessionTargetValue = undefined;
+            retired = true;
+        }
+        if (this.boundSessionTransferTargetValue !== undefined
+            && sameRemoteSessionBinding(this.boundSessionTransferTargetValue, target)) {
+            this.boundSessionTransferTargetValue = undefined;
+            retired = true;
+        }
+        if (retired) {
+            this.boundSessionBindingGenerationValue = preferredRemoteBoundSessionTarget(this.remoteBoundSessionTargetValue, this.boundSessionTransferTargetValue)?.bindingGeneration ?? 0n;
+        }
+        return retired;
+    }
+    setEntryNodeRid(entryNodeRid) {
+        this.entryNodeRidValue = entryNodeRid;
+    }
+    setRemoteBoundSessionTarget(target) {
+        const current = preferredRemoteBoundSessionTarget(this.remoteBoundSessionTargetValue, this.boundSessionTransferTargetValue);
+        const merged = target === undefined
+            ? undefined
+            : mergeRemoteBoundSessionTarget(target, current);
+        const bindingGeneration = maxBindingGeneration(merged?.bindingGeneration, this.remoteBoundSessionTargetValue?.bindingGeneration, this.boundSessionBindingGenerationValue);
+        this.remoteBoundSessionTargetValue = merged === undefined
+            ? undefined
+            : bindingGeneration === undefined
+                ? merged
+                : { ...merged, bindingGeneration };
+    }
+    setBoundSessionTransferTarget(target) {
+        const merged = target === undefined
+            ? undefined
+            : mergeRemoteBoundSessionTarget(target, this.boundSessionTransferTargetValue);
+        const bindingGeneration = maxBindingGeneration(merged?.bindingGeneration, this.boundSessionTransferTargetValue?.bindingGeneration, this.boundSessionBindingGenerationValue);
+        this.boundSessionTransferTargetValue = merged === undefined
+            ? undefined
+            : bindingGeneration === undefined
+                ? merged
+                : { ...merged, bindingGeneration };
+    }
+    setRemoteActorPacketTarget(target) {
+        this.remoteActorPacketTargetValue = target;
+    }
+    setCreateRequestPayload(payload) {
+        this.createRequestPayloadValue = Buffer.from(payload);
+    }
+    setJoinedSpot(spotId, spot, membershipEpoch = 0n, spotGeneration) {
+        this.spotIdValue = spotId;
+        this.spotValue = spot;
+        if (spotGeneration !== undefined && spotGeneration > 0n) {
+            this.spotGenerationValue = spotGeneration;
+        }
+        this.spotMembershipEpochValue = membershipEpoch;
+    }
+    clearJoinedSpot() {
+        this.spotIdValue = undefined;
+        this.spotValue = undefined;
+        this.spotGenerationValue = undefined;
+        this.spotMembershipEpochValue = 0n;
+    }
+    clearAfterDestroy() {
+        this.creationTask = undefined;
+        this.configured = false;
+        this.context = undefined;
+        this.actorTypeValue = undefined;
+        this.actorValue = undefined;
+        this.spotValue = undefined;
+        this.spotIdValue = undefined;
+        this.spotGenerationValue = undefined;
+        this.spotMembershipEpochValue = 0n;
+        this.nativeActorRefValue = undefined;
+        this.boundSessionBindingGenerationValue = 0n;
+        this.entryNodeRidValue = undefined;
+        this.remoteBoundSessionTargetValue = undefined;
+        this.boundSessionTransferTargetValue = undefined;
+        this.remoteActorPacketTargetValue = undefined;
+        this.createRequestPayloadValue = undefined;
+        this.ownsLocationValue = false;
+        this.locationGenerationValue = undefined;
+        this.ownerLeaseGenerationValue = undefined;
+        this.movingValue = false;
+        this.deferredJoinPendingValue = false;
+        this.destroyTask = undefined;
+    }
+    prepareForRemoteReentry() {
+        if (this.remoteActorPacketTargetValue === undefined)
+            return;
+        const relocationTransferTarget = this.boundSessionTransferTargetValue !== undefined
+            && hasRelocationFence(this.boundSessionTransferTargetValue)
+            ? this.boundSessionTransferTargetValue
+            : undefined;
+        this.creationTask = undefined;
+        this.configured = false;
+        this.context = undefined;
+        this.actorTypeValue = undefined;
+        this.actorValue = undefined;
+        this.spotValue = undefined;
+        this.spotIdValue = undefined;
+        this.nativeActorRefValue = undefined;
+        this.boundSessionBindingGenerationValue = relocationTransferTarget?.bindingGeneration ?? 0n;
+        this.remoteBoundSessionTargetValue = undefined;
+        this.boundSessionTransferTargetValue = relocationTransferTarget;
+        this.remoteActorPacketTargetValue = undefined;
+        this.createRequestPayloadValue = undefined;
+        this.ownsLocationValue = false;
+        this.locationGenerationValue = undefined;
+        this.ownerLeaseGenerationValue = undefined;
+        this.movingValue = false;
+        this.deferredJoinPendingValue = false;
+        this.destroyTask = undefined;
+    }
+}
+exports.ZLinkActorRuntimeState = ZLinkActorRuntimeState;
+function maxBindingGeneration(...values) {
+    let maximum;
+    for (const value of values) {
+        if (value === undefined || value <= 0n)
+            continue;
+        if (maximum === undefined || value > maximum)
+            maximum = value;
+    }
+    return maximum;
+}
+function toFrameworkRoutingId(routingId) {
+    // Runtime routing identities are opaque binary values. Preserve binding
+    // RoutingId instances so a later native call cannot reinterpret their
+    // hexadecimal display string as different literal bytes.
+    return routingId;
+}
+function toFrameworkActorRef(actor, meshName) {
+    const actorRef = {
+        actorId: actor.actorId,
+        objectGeneration: actor.generation,
+        meshName,
+        nodeRid: toFrameworkRoutingId(actor.nodeRid)
+    };
+    Object.defineProperty(actorRef, 'generation', {
+        configurable: false,
+        enumerable: false,
+        value: actor.generation
+    });
+    return actorRef;
+}

package/dist/runtime/actors/actor-source-transfer.d.ts

@@ -0,0 +1,27 @@
+import type { ActorRef, ZLinkActor, ZLinkMessage } from '../../contracts';
+import type { ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
+import type { ZLinkActorRuntimeState } from './actor-runtime-state';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult } from './actor-handoff';
+import type { ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
+export interface ZLinkPreparedActorSource {
+    readonly adapterKey?: string;
+    readonly state: ZLinkMessage;
+    readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
+    readonly sourceLeaveCompletion?: Promise<void>;
+    readonly sourceLeaveSubmitted?: Promise<void>;
+    onSourceLeaveSubmitted(notify: () => Promise<void>): void;
+    observeTargetAuthority(target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    commit(target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, results: readonly ZLinkActorHandoffResult[], releaseLocation?: boolean): void;
+    rollback(): Promise<void>;
+}
+export interface ZLinkActorSourceTransfer {
+    /** Starts the ingress handoff before target route lookup. */
+    beginDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): void;
+    /** Changes a provisional ingress fence into a relocation handoff. */
+    promoteDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): void;
+    /** Finishes a same-node deferred Join handoff after completion callback. */
+    completeDeferredActorHandoff?(actor: ZLinkActor, target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, operationId: string): Promise<void>;
+    /** Releases an early handoff when Join cannot commit. */
+    cancelDeferredActorHandoff?(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): Promise<void>;
+    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredOperationId?: string, relocation?: ServiceWireOperationId): Promise<ZLinkPreparedActorSource>;
+}

package/dist/runtime/actors/actor-source-transfer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/runtime/actors/actor-transfer-registry.d.ts

@@ -0,0 +1,18 @@
+import type { ZLinkActor, ZLinkMessageSerializer } from '../../contracts';
+import type { ZLinkSpotNodeOptions } from '../../contracts/Configuration/RegistrationTypes';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import { ZLinkMessage } from '../../contracts';
+export interface ZLinkActorTransferPayloadState {
+    readonly adapterKey?: string;
+    readonly state: ZLinkMessage;
+}
+export declare class ZLinkActorTransferRegistry {
+    private readonly providerResolver?;
+    private readonly messageSerializers?;
+    private readonly byKey;
+    constructor(spotNodes: ReadonlyMap<string, ZLinkSpotNodeOptions>, providerResolver?: ZLinkProviderResolver | undefined, messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer> | undefined);
+    transferOut(actor: ZLinkActor, actorType: string | undefined, signal?: AbortSignal): Promise<ZLinkActorTransferPayloadState>;
+    policy(actorType: string | undefined): 'recreate' | 'snapshot';
+    restore(adapterKey: string, actor: ZLinkActor, state: ZLinkMessage, signal?: AbortSignal): Promise<void>;
+    private createAdapter;
+}

package/dist/runtime/actors/actor-transfer-registry.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorTransferRegistry = void 0;
+const contracts_1 = require("../../contracts");
+const abort_1 = require("../abort");
+class ZLinkActorTransferRegistry {
+    providerResolver;
+    messageSerializers;
+    byKey = new Map();
+    constructor(spotNodes, providerResolver, messageSerializers) {
+        this.providerResolver = providerResolver;
+        this.messageSerializers = messageSerializers;
+        for (const node of spotNodes.values()) {
+            for (const [stableType, registration] of Object.entries(node.actorFactoryRegistrations ?? {})) {
+                if (registration.relocation.kind !== 'snapshot')
+                    continue;
+                const adapterType = registration.relocation.adapterType;
+                const current = this.byKey.get(stableType);
+                if (current !== undefined && current !== adapterType) {
+                    throw new Error(`Actor relocation adapter for stable type '${stableType}' is registered more than once.`);
+                }
+                this.byKey.set(stableType, adapterType);
+            }
+        }
+    }
+    async transferOut(actor, actorType, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const adapterType = actorType === undefined
+            ? undefined
+            : this.byKey.get(actorType);
+        if (adapterType === undefined) {
+            return { state: emptyTransferState(this.messageSerializers) };
+        }
+        const adapter = await this.createAdapter(adapterType);
+        const state = await adapter.capture(actor, signal ?? new AbortController().signal);
+        if (!(state instanceof Uint8Array)) {
+            throw new Error(`Actor relocation adapter '${adapterType.name}' returned invalid state bytes.`);
+        }
+        return {
+            adapterKey: actorType,
+            state: contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(state))
+        };
+    }
+    policy(actorType) {
+        return actorType !== undefined && this.byKey.has(actorType) ? 'snapshot' : 'recreate';
+    }
+    async restore(adapterKey, actor, state, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const adapterType = this.byKey.get(adapterKey);
+        if (adapterType === undefined) {
+            throw new Error(`Actor relocation adapter for stable type '${adapterKey}' is not registered on the target node.`);
+        }
+        const adapter = await this.createAdapter(adapterType);
+        await adapter.restore(actor, state.toEncodedPayload().toBytes(), signal ?? new AbortController().signal);
+    }
+    async createAdapter(adapterType) {
+        const existing = this.providerResolver?.get?.(adapterType);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const created = await this.providerResolver?.create?.(adapterType);
+        if (created !== undefined) {
+            return created;
+        }
+        return new adapterType();
+    }
+}
+exports.ZLinkActorTransferRegistry = ZLinkActorTransferRegistry;
+function emptyTransferState(_serializers) {
+    return contracts_1.ZLinkMessage.fromEncoded(contracts_1.ZLinkEncodedPayload.from(Buffer.alloc(0)));
+}

package/dist/runtime/actors/actor-transport-delivery-gate.d.ts

@@ -0,0 +1,6 @@
+import type { ZLinkActorMessageFollowContext } from './actor-message-follow-context';
+export declare const ZLINK_INTERNAL_ACTOR_TRANSPORT_DELIVERY_GATE: unique symbol;
+export interface ZLinkInternalActorTransportDeliveryGate {
+    waitBeforeSubmit(actorId: string, kind: 'oneWay' | 'request', signal?: AbortSignal): Promise<number | void>;
+    recordMessageFollowRelay?(actorId: string, context: ZLinkActorMessageFollowContext): void;
+}

package/dist/runtime/actors/actor-transport-delivery-gate.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_INTERNAL_ACTOR_TRANSPORT_DELIVERY_GATE = void 0;
+exports.ZLINK_INTERNAL_ACTOR_TRANSPORT_DELIVERY_GATE = Symbol.for('zlink.internal.actor.transport-delivery-gate');