@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,26 @@
+import { type ActorTransferControlPayload } from '../foundation/service-runtime-contracts';
+import type { ZLinkActorLocationStore } from '../locations/internal-store-contracts';
+import type { ZLinkActorTransferStore } from '../../contracts/Locations/ActorTransfer';
+export type ZLinkActorTransferAuthorityStore = ZLinkActorTransferStore & ZLinkActorLocationStore;
+export interface ZLinkActorTransferAuthorityRuntimeOptions {
+    readonly store: () => ZLinkActorTransferAuthorityStore | undefined;
+    readonly recoveryOwnerId: () => string | undefined;
+    readonly recoveryLeaseTtlMs: number;
+    readonly now?: () => Date;
+}
+/**
+ * Projects Core transfer-control records into the durable location authority.
+ * Core owns sealed tokens; this runtime persists only public transfer identity
+ * and fences, then resumes terminal transitions after a recovery lease takeover.
+ */
+export declare class ZLinkActorTransferAuthorityRuntime {
+    private readonly options;
+    private readonly now;
+    constructor(options: ZLinkActorTransferAuthorityRuntimeOptions);
+    handle(meshName: string, control: ActorTransferControlPayload, signal?: AbortSignal): Promise<void>;
+    private prepare;
+    private transition;
+    private requireStore;
+    private requireOwnerId;
+}
+export declare function transferIdString(high: bigint, low: bigint): string;

package/dist/runtime/host/actor-transfer-authority-runtime.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorTransferAuthorityRuntime = void 0;
+exports.transferIdString = transferIdString;
+const service_runtime_contracts_1 = require("../foundation/service-runtime-contracts");
+const actors_1 = require("../actors");
+/**
+ * Projects Core transfer-control records into the durable location authority.
+ * Core owns sealed tokens; this runtime persists only public transfer identity
+ * and fences, then resumes terminal transitions after a recovery lease takeover.
+ */
+class ZLinkActorTransferAuthorityRuntime {
+    options;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+    }
+    async handle(meshName, control, signal) {
+        if (control.actor === null || control.failureErrno !== 0 || control.resultCode !== 0) {
+            return;
+        }
+        const store = this.requireStore();
+        const ownerId = this.requireOwnerId();
+        const actorId = control.actor.actorId;
+        const transferId = transferIdString(control.transferId.high, control.transferId.low);
+        if (control.role === service_runtime_contracts_1.ActorTransferRole.Target
+            && (control.phase === service_runtime_contracts_1.ActorTransferPhase.Preparing || control.phase === service_runtime_contracts_1.ActorTransferPhase.Fenced)) {
+            await this.prepare(store, ownerId, meshName, actorId, transferId, control.actor, control.membershipEpoch, signal);
+            return;
+        }
+        if (control.phase === service_runtime_contracts_1.ActorTransferPhase.Committed) {
+            await this.transition(store, ownerId, meshName, actorId, transferId, 'committed', signal);
+            return;
+        }
+        if (control.phase === service_runtime_contracts_1.ActorTransferPhase.Activated) {
+            await this.transition(store, ownerId, meshName, actorId, transferId, 'activated', signal);
+            return;
+        }
+        if (control.phase === service_runtime_contracts_1.ActorTransferPhase.Aborted) {
+            await this.transition(store, ownerId, meshName, actorId, transferId, 'aborted', signal);
+        }
+    }
+    async prepare(store, ownerId, meshName, actorId, transferId, nativeTarget, membershipEpoch, signal) {
+        const location = await store.resolveActor({ meshName, actorId }, signal);
+        if (location === undefined) {
+            throw new Error(`Actor transfer '${transferId}' has no source location row.`);
+        }
+        const target = (0, actors_1.toFrameworkActorRef)(nativeTarget, meshName);
+        validateTarget(location, target, membershipEpoch, transferId);
+        const result = await store.prepareActorTransfer({
+            meshName,
+            actorId,
+            transferId,
+            source: location.actorRef,
+            target,
+            expectedActorGeneration: location.actorRef.objectGeneration,
+            expectedMembershipEpoch: location.membershipEpoch,
+            participants: new Set([
+                location.actorRef.nodeRid,
+                target.nodeRid
+            ]),
+            recoveryOwnerId: ownerId,
+            recoveryLeaseTtlMs: this.options.recoveryLeaseTtlMs
+        }, signal);
+        if (result.status !== 'stored') {
+            throw new Error(`Actor transfer '${transferId}' prepare was rejected with status '${result.status}'.`);
+        }
+    }
+    async transition(store, ownerId, meshName, actorId, transferId, targetState, signal) {
+        let record = await store.resolveActorTransfer(meshName, actorId, signal);
+        if (record === undefined || record.transferId !== transferId) {
+            throw new Error(`Actor transfer '${transferId}' has no durable prepared record.`);
+        }
+        if (isAtOrBeyond(record, targetState)) {
+            return;
+        }
+        if (record.recoveryOwnerId !== ownerId) {
+            if (record.recoveryLeaseExpiresAt.getTime() > this.now().getTime()) {
+                return;
+            }
+            const takeover = await store.takeOverActorTransfer(meshName, actorId, transferId, ownerId, this.options.recoveryLeaseTtlMs, signal);
+            if (takeover.status !== 'stored' || takeover.record === undefined) {
+                throw new Error(`Actor transfer '${transferId}' recovery takeover failed with status '${takeover.status}'.`);
+            }
+            record = takeover.record;
+        }
+        if (targetState === 'activated' && record.state === 'prepared') {
+            record = requireStored(await store.commitActorTransfer(meshName, actorId, transferId, ownerId, signal), transferId, 'commit');
+        }
+        const result = targetState === 'committed'
+            ? await store.commitActorTransfer(meshName, actorId, transferId, ownerId, signal)
+            : targetState === 'activated'
+                ? await store.activateActorTransfer(meshName, actorId, transferId, ownerId, signal)
+                : await store.abortActorTransfer(meshName, actorId, transferId, ownerId, signal);
+        requireStored(result, transferId, targetState);
+    }
+    requireStore() {
+        const store = this.options.store();
+        if (store === undefined) {
+            throw new Error('Actor transfer control requires durable Actor transfer authority.');
+        }
+        return store;
+    }
+    requireOwnerId() {
+        const ownerId = this.options.recoveryOwnerId();
+        if (ownerId === undefined || ownerId.length === 0) {
+            throw new Error('Actor transfer control requires an active location owner.');
+        }
+        return ownerId;
+    }
+}
+exports.ZLinkActorTransferAuthorityRuntime = ZLinkActorTransferAuthorityRuntime;
+function validateTarget(location, target, membershipEpoch, transferId) {
+    if (target.actorId !== location.actorId
+        || target.objectGeneration !== location.actorRef.objectGeneration
+        || membershipEpoch !== location.membershipEpoch) {
+        throw new Error(`Actor transfer '${transferId}' does not match the source Actor generation and membership epoch.`);
+    }
+}
+function requireStored(result, transferId, operation) {
+    if (result.status !== 'stored' || result.record === undefined) {
+        throw new Error(`Actor transfer '${transferId}' ${operation} failed with status '${result.status}'.`);
+    }
+    return result.record;
+}
+function isAtOrBeyond(record, target) {
+    if (record.state === target)
+        return true;
+    return target === 'committed' && (record.state === 'committed' || record.state === 'activated');
+}
+function transferIdString(high, low) {
+    const hex = `${unsignedHex64(high)}${unsignedHex64(low)}`;
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function unsignedHex64(value) {
+    return BigInt.asUintN(64, value).toString(16).padStart(16, '0');
+}

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

@@ -0,0 +1,149 @@
+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 { 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 { ZLinkActorRuntimeState } from '../actors/actor-runtime-state';
+import type { ZLinkLocationLifecycle } from '../locations';
+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>;
+}
+type ZLinkCommittedActorAuthority = Pick<ZLinkAuthoritySnapshot, 'objectGeneration' | 'authorityOwnerGeneration' | 'ownerId' | 'ownerLeaseGeneration' | 'allocation'>;
+/** Converts only committed actor authority evidence into a Message Follow fence. */
+export declare function committedActorOwnerFence(actorId: string, targetActorRef: ActorRef, authority: ZLinkCommittedActorAuthority): ZLinkActorMessageFollowOwnerFence;
+export interface ZLinkActorTransferRuntimeActorManager {
+    getState(actorId: string): ZLinkActorRuntimeState | undefined;
+    getOrCreateActor(actorId: string, actorType: string, signal?: AbortSignal): Promise<ZLinkActor>;
+    getOrCreateWithNativeRef(actorId: string, actorType: string, actorRef: ZLinkBackendActorRef, actorCreateRequest?: unknown, signal?: AbortSignal): Promise<ZLinkActor>;
+    materializeTransferredActor(actorId: string, actorType: string, adapterKey: string | undefined, transferState: ZLinkMessage, signal?: AbortSignal): Promise<{
+        readonly actor: ZLinkActor;
+        readonly actorRef: ActorRef;
+    }>;
+    prepareRelocationActor(actorId: string, actorType: string, objectGeneration: bigint, authorityOwnerGeneration: bigint, spotId: RoutingId, spotGeneration: bigint, membershipEpoch: bigint, signal?: AbortSignal, transfer?: {
+        readonly adapterKey: string;
+        readonly state: ZLinkMessage;
+    }): Promise<ZLinkActor>;
+    publishRelocationActor(actorId: string): void;
+    rollbackTransferredActor(actor: ZLinkActor, signal?: AbortSignal): Promise<void>;
+    completeCoreRelocationSource(actorId: string): Promise<void>;
+}
+export interface ZLinkActorTransferRuntimeOptions {
+    readonly routeTransport: ZLinkActorRoutedJoinTransport;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly spotManager: () => DefaultZLinkSpotManager | undefined;
+    readonly actorManager: () => ZLinkActorTransferRuntimeActorManager | undefined;
+    readonly primaryMeshNode: () => ZLinkBackendMeshNode;
+    readonly notifyEntrySpotActorLeft: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+    readonly restoreEntrySpotActorJoined: (actor: ZLinkActor, signal?: AbortSignal) => Promise<void>;
+    readonly locationLifecycle: () => ZLinkLocationLifecycle | undefined;
+    /** Resolves the authoritative Ready route for a target User/Instance Spot. */
+    readonly spotRouteResolver?: () => ZLinkSpotRouteResolver | undefined;
+    readonly actorHandoff: ZLinkActorHandoffCoordinator;
+    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. */
+    readonly sessionRelocationWire?: () => ZLinkSessionRelocationWirePort | undefined;
+    readonly clearRemoteActorPacketTarget: (actorId: string) => void;
+    /** Acquires that permit before the Actor FIFO claims the runnable child. */
+    readonly prepareApplicationJob?: ZLinkActorHandoffReplayPreparation;
+    readonly reportPostCommitError?: (error: unknown) => void;
+    readonly onSourceDepartureCompleted?: (actorId: string) => void;
+    readonly shutdownSignal?: () => AbortSignal | undefined;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+}
+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;
+    private prepareSourceActorLeave;
+    private restoreSourceActor;
+    private beginSourceActorMove;
+    private cancelSourceActorMove;
+    private admitCanceledSourcePrefix;
+    private admitDeferredSourcePrefix;
+    private observeHandoffReplay;
+    private sourceHandoffPrefixQueue;
+    prepareSource(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, lifecycleAuthority?: 'framework' | 'core', deferredOperationId?: string, relocation?: ServiceWireOperationId): Promise<{
+        handoffBacklog: readonly ZLinkActorHandoffPacket[];
+        sourceLeaveCompletion: Promise<void> | undefined;
+        sourceLeaveSubmitted: Promise<void> | undefined;
+        onSourceLeaveSubmitted: (notify: () => Promise<void>) => void;
+        observeTargetAuthority: (target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, observeSignal?: AbortSignal) => Promise<void>;
+        commit: (target: Parameters<ZLinkActorHandoffCoordinator["complete"]>[1], targetActorRef: ActorRef, results: Parameters<ZLinkActorHandoffCoordinator["complete"]>[3], releaseLocation?: boolean) => void;
+        rollback: () => Promise<void>;
+        adapterKey?: string;
+        state: ZLinkMessage;
+    }>;
+    prepareMaintenanceSession(actor: ZLinkActor, state: ZLinkActorRuntimeState, signal?: AbortSignal, manageMembership?: boolean, relocation?: ServiceWireOperationId): Promise<{
+        readonly target?: ZLinkRemoteBoundSessionTarget;
+        readonly handoffBacklog: readonly import('../actors').ZLinkActorHandoffPacket[];
+        takeRelocationRelay(): readonly import('../actors').ZLinkActorHandoffPacket[];
+        setReplayResults(results: readonly import('../actors').ZLinkActorHandoffResult[]): void;
+        commit(target: ZLinkSpotRouteTarget, targetActorRef: ActorRef, targetOwnerFence: ZLinkActorMessageFollowOwnerFence): Promise<void>;
+        rollback(): Promise<void>;
+    }>;
+    notifyCoreSourceLeave(actor: ZLinkActor, callback: () => Promise<void>): Promise<void>;
+    completeRelocationSourceLeave(actor: ZLinkActor, sourceSpotId: RoutingId | undefined, signal?: AbortSignal): Promise<void>;
+    relayMaintenanceTerminal(actorId: string, packet: ZLinkActorHandoffPacket, result: ZLinkActorHandoffResult, sourceNodeRid: RoutingId, targetAuthorityOwnerGeneration?: bigint): ZLinkActorHandoffTerminalAck;
+    relayCanonicalMaintenanceTerminal(operationId: string, replyRouteId: string, result: ZLinkActorHandoffResult, sourceNodeRid: RoutingId, targetAuthorityOwnerGeneration?: bigint): ZLinkActorHandoffTerminalAcceptance;
+    private sealBoundSessionRoute;
+    private abortBoundSessionRouteSeal;
+    private observeBoundSessionSealAbort;
+    private beginCoreSourceLeave;
+    private scheduleSourceDeparture;
+    private finishSourceDeparture;
+    getOrCreateRoutedActor(actorId: string, actorType: string, actorRef?: ActorRef, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, actorCreateRequest?: Message, signal?: AbortSignal): Promise<{
+        readonly actor: ZLinkActor;
+        readonly actorRef: ZLinkBackendActorRef;
+    }>;
+    materializeRoutedActor(actorId: string, actorType: string, adapterKey: string | undefined, transferState: Message, actorEntryNodeRid: RoutingId | undefined, remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget, signal?: AbortSignal): Promise<{
+        readonly actor: ZLinkActor;
+        readonly actorRef: ZLinkBackendActorRef;
+    }>;
+    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?: {
+        readonly spotGeneration: bigint;
+        readonly membershipEpoch: bigint;
+    }): Promise<void>;
+    private installNativeActorPacketTarget;
+    claimNativeActorLocation(actor: ZLinkActor, spotId: RoutingId, spotMeshName: string): Promise<ZLinkNativeActorJoinSnapshot>;
+    publishRoutedActorOwnership(actor: ZLinkActor): 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;
+    private publishBoundSessionOwnership;
+}
+export {};