@zlink-systems/framework 0.25.0 → 0.27.0

package/dist/runtime/host/actor-transfer-runtime.d.ts

@@ -1,17 +1,16 @@
-import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId, ZLinkMessage, ZLinkMessageSerializer, ZLinkRelocationStore, ZLinkSpot } from '../../contracts';
-import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
-import type { ZLinkAuthorityStore, ZLinkObjectCreationStore, ZLinkOwnerLeaseStore } from '../locations/internal-store-contracts';
+import { type ActorRef, type RoutingId, type ZLinkActor, type ZLinkActorJoinOperationId, type ZLinkMessageSerializer, type ZLinkSpot, ZLinkMessage } from '../../contracts';
 import type { Message } from '../../contracts/Common/Message';
-import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
-import { type ZLinkActorHandoffCoordinator, type ZLinkActorHandoffReplayPreparation, type ZLinkActorRoutedJoinTransport, type ZLinkActorTransferRegistry, type ZLinkDeferredJoinAcceptedRoot, type ZLinkDeferredJoinRootIdentity, type ZLinkRemoteBoundSessionTarget } from '../actors';
+import { type ZLinkActorHandoffCoordinator, type ZLinkActorHandoffReplayPreparation, type ZLinkActorRoutedJoinTransport, type ZLinkActorTransferRegistry, type ZLinkDeferredJoinCompletion, type ZLinkRemoteBoundSessionTarget } from '../actors';
+import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult, ZLinkActorHandoffTerminalAcceptance, ZLinkActorHandoffTerminalAck } from '../actors/actor-handoff';
+import { type ZLinkActorMessageFollowOwnerFence } from '../actors/actor-message-follow-context';
 import type { ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
+import type { ZLinkBackendActorRef, ZLinkBackendMeshNode } from '../backend';
+import { type ServiceSessionRelocationRoute, type ServiceSessionRelocationSeal, type ServiceSessionRelocationSealed, type ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
 import type { ZLinkLocationLifecycle } from '../locations';
+import type { ZLinkAuthoritySnapshot, ZLinkLocationOwnerToken } from '../locations/internal-location-contracts';
+import type { ZLinkAuthorityStore, ZLinkObjectCreationStore, ZLinkOwnerLeaseStore } from '../locations/internal-store-contracts';
 import type { DefaultZLinkSpotManager } from '../spots';
 import type { ZLinkSpotRouteResolver, ZLinkSpotRouteTarget } from '../spots/spot-routing-internal';
-import type { ZLinkActorHandoffPacket, ZLinkActorHandoffResult, ZLinkActorHandoffTerminalAcceptance, ZLinkActorHandoffTerminalAck } from '../actors/actor-handoff';
-import type { ZLinkNativeActorJoinSnapshot } from '../spots/spot-runtime-ports';
-import { type ZLinkActorMessageFollowOwnerFence } from '../actors/actor-message-follow-context';
-import type { ServiceSessionRelocationRoute, ServiceSessionRelocationSeal, ServiceSessionRelocationSealed, ServiceWireOperationId } from '../foundation/service-stateful-wire-codec';
 interface ZLinkSessionRelocationWirePort {
     requestSessionRelocationSeal(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationSeal, signal?: AbortSignal): Promise<ServiceSessionRelocationSealed>;
     sendSessionRelocationRoute(meshName: string, targetNodeRid: RoutingId, request: ServiceSessionRelocationRoute, signal?: AbortSignal): Promise<void>;
@@ -27,7 +26,7 @@ export interface ZLinkActorTransferRuntimeActorManager {
         readonly actor: ZLinkActor;
         readonly actorRef: ActorRef;
     }>;
-    prepareRelocationActor(actorId: string, actorType: string, objectGeneration: bigint, authorityOwnerGeneration: bigint, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, signal?: AbortSignal, transfer?: {
+    prepareRelocationActor(actorId: string, actorType: string, objectGeneration: bigint, authorityOwnerGeneration: bigint, spotId: RoutingId | undefined, spotGeneration: bigint, membershipEpoch: bigint, signal?: AbortSignal, transfer?: {
         readonly adapterKey: string;
         readonly state: ZLinkMessage;
     }): Promise<ZLinkActor>;
@@ -50,7 +49,6 @@ export interface ZLinkActorTransferRuntimeOptions {
     readonly actorTransferRegistry: ZLinkActorTransferRegistry;
     readonly authorityStore: () => (ZLinkAuthorityStore & ZLinkObjectCreationStore & ZLinkOwnerLeaseStore) | undefined;
     readonly currentOwner: () => ZLinkLocationOwnerToken | undefined;
-    readonly relocationStore: () => ZLinkRelocationStore | undefined;
     /** Live admitted peers of a mesh; used to stop retries against a gone session owner. */
     readonly liveDescriptors?: (meshName: string, signal?: AbortSignal) => Promise<readonly import('../../contracts').ZLinkMeshNodeDescriptor[]>;
     /** Service-wire command 42/43/44 bridge, installed after the host runtime is assembled. */
@@ -65,22 +63,22 @@ export interface ZLinkActorTransferRuntimeOptions {
 }
 export declare class ZLinkActorTransferRuntime {
     private readonly options;
-    private readonly sourceDepartureTasks;
     private readonly coreSourceLeaves;
     private readonly activeDeferredJoinTerminals;
     private readonly deferredJoinTerminals;
     constructor(options: ZLinkActorTransferRuntimeOptions);
-    beginDeferredActorHandoff(actor: ZLinkActor, state: ZLinkActorRuntimeState, operationId: string): void;
-    promoteDeferredActorHandoff(actor: ZLinkActor, _state: ZLinkActorRuntimeState, operationId: string): void;
-    completeDeferredActorHandoff(actor: ZLinkActor, target: ZLinkSpotRouteTarget, _targetActorRef: ActorRef, operationId: string): Promise<void>;
-    cancelDeferredActorHandoff(actor: ZLinkActor, _state: ZLinkActorRuntimeState, operationId: string): Promise<void>;
-    prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string, signal?: AbortSignal, canonicalInventoryDigest?: string): Promise<ZLinkDeferredJoinAcceptedRoot>;
-    isDeferredJoinAcceptedRootPublication(reference: string, checksumCrc32c: number, expected: ZLinkDeferredJoinRootIdentity, signal?: AbortSignal): Promise<boolean>;
-    discardDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, signal?: AbortSignal): Promise<void>;
-    markDeferredJoinAcceptedCommitted(root: ZLinkDeferredJoinAcceptedRoot, actorRef: ActorRef, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
-    commitAndDeliverDeferredJoinAccepted(root: ZLinkDeferredJoinAcceptedRoot, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<ZLinkDeferredJoinAcceptedRoot>;
-    private commitAndDeliverDeferredJoinAcceptedCore;
-    private requireDeferredJoinJournal;
+    beginDeferredActorHandoff(actor: ZLinkActor, state: ZLinkActorRuntimeState): void;
+    promoteDeferredActorHandoff(actor: ZLinkActor, _state: ZLinkActorRuntimeState): void;
+    completeDeferredActorHandoff(actor: ZLinkActor, target: ZLinkSpotRouteTarget, _targetActorRef: ActorRef): Promise<void>;
+    cancelDeferredActorHandoff(actor: ZLinkActor, state: ZLinkActorRuntimeState): Promise<void>;
+    prepareDeferredJoinAccepted(actorId: string, operationId: ZLinkActorJoinOperationId, actorRef: ActorRef, rawReply: Uint8Array, replyContentType?: string): ZLinkDeferredJoinCompletion;
+    /**
+     * Runs the completion callback once in the target Actor mailbox.
+     * A repeated delivery of the same OperationId in this process observes the
+     * first terminal (completion idempotency only).
+     */
+    deliverDeferredJoinCompletion(completion: ZLinkDeferredJoinCompletion, actor: ZLinkActor, actorRef: ActorRef, submitMailbox: <T>(operation: () => Promise<T>) => Promise<T>, signal?: AbortSignal): Promise<void>;
+    private deliverDeferredJoinCompletionCore;
     private prepareSourceActorLeave;
     private restoreSourceActor;
     private beginSourceActorMove;
@@ -89,7 +87,7 @@ export declare class ZLinkActorTransferRuntime {
     private admitDeferredSourcePrefix;
     private observeHandoffReplay;
     private sourceHandoffPrefixQueue;
-    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredOperationId?: string, relocation?: ServiceWireOperationId): Promise<{
+    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredJoin?: boolean, relocation?: ServiceWireOperationId): Promise<{
         handoffBacklog: readonly ZLinkActorHandoffPacket[];
         sourceLeaveCompletion: Promise<void> | undefined;
         sourceLeaveSubmitted: Promise<void> | undefined;
@@ -107,6 +105,7 @@ export declare class ZLinkActorTransferRuntime {
         setReplayResults(results: readonly import('../actors').ZLinkActorHandoffResult[]): void;
         commit(target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, targetOwnerFence: ZLinkActorMessageFollowOwnerFence): Promise<void>;
         rollback(): Promise<void>;
+        discard(reason: unknown): void;
     }>;
     notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
     completeRelocationSourceLeave(actor: ZLinkActor, sourceSpotId: RoutingId | undefined, signal?: AbortSignal): Promise<void>;
@@ -128,7 +127,6 @@ export declare class ZLinkActorTransferRuntime {
     }>;
     commitRoutedActorAuthority(actor: ZLinkActor, sourceActorRef: ActorRef, transferId: string, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, deadlineUnixMs: number, signal?: AbortSignal): Promise<ZLinkAuthoritySnapshot>;
     private readActorAuthorityForRelocation;
-    rememberRoutedActorTransferTarget(actorId: string, target: ZLinkRemoteBoundSessionTarget | undefined): void;
     commitRoutedActor(actor: ZLinkActor, spotId: RoutingId, spot: ZLinkSpot): void;
     bindRoutedActorRef(actor: ZLinkActor, actorRef: ActorRef): void;
     claimRoutedActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string, joinedLocation?: {
@@ -136,11 +134,13 @@ export declare class ZLinkActorTransferRuntime {
         readonly membershipEpoch: bigint;
     }): Promise<void>;
     private installNativeActorPacketTarget;
-    claimNativeActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string): Promise<ZLinkNativeActorJoinSnapshot>;
-    publishRoutedActorOwnership(actor: ZLinkActor): Promise<void>;
+    /**
+     * Publishes the committed route of the Session seal that the relocation
+     * operation carried to this target (command 44, Session–Actor binding §8.2).
+     */
+    publishRoutedActorOwnership(actor: ZLinkActor, sealedSession: ZLinkRemoteBoundSessionTarget | undefined): Promise<void>;
     openRoutedActorSession(_actor: ZLinkActor): Promise<void>;
     clearRoutedActor(actor: ZLinkActor): void;
-    rollbackNativeActorJoin(actor: ZLinkActor, snapshot: ZLinkNativeActorJoinSnapshot): Promise<void>;
     rollbackRoutedActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
     actorEntryNodeRid(actor: ZLinkActor): RoutingId | undefined;
     private requireActorManager;