@zlink-systems/framework 0.10.0

package/dist/runtime/routing-id.d.ts

@@ -0,0 +1,8 @@
+import type { RoutingId } from '../contracts';
+export declare function normalizeRoutingId(value: RoutingId | string): RoutingId;
+export declare function normalizeOpaqueRoutingId(value: unknown): RoutingId;
+export declare function decodeRoutingId(text: string, hex: unknown): RoutingId;
+export declare function routingIdWireHex(routingId: RoutingId): string | undefined;
+export declare function encodeRoutingIdStorageHex(routingId: RoutingId): string;
+export declare function toBackendRoutingId(routingId: unknown): RoutingId;
+export declare function routingIdsEqual(left: RoutingId | undefined, right: RoutingId | undefined): boolean;

package/dist/runtime/routing-id.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRoutingId = normalizeRoutingId;
+exports.normalizeOpaqueRoutingId = normalizeOpaqueRoutingId;
+exports.decodeRoutingId = decodeRoutingId;
+exports.routingIdWireHex = routingIdWireHex;
+exports.encodeRoutingIdStorageHex = encodeRoutingIdStorageHex;
+exports.toBackendRoutingId = toBackendRoutingId;
+exports.routingIdsEqual = routingIdsEqual;
+class ZLinkOpaqueRoutingId {
+    text;
+    hex;
+    constructor(text, hex) {
+        this.text = text;
+        this.hex = hex;
+    }
+    toHex() {
+        return this.hex;
+    }
+    toBytes() {
+        return Buffer.from(this.hex, 'hex');
+    }
+    toString() {
+        return this.text;
+    }
+}
+function normalizeRoutingId(value) {
+    const candidate = value;
+    if (candidate instanceof ZLinkOpaqueRoutingId) {
+        return candidate;
+    }
+    return String(value);
+}
+function normalizeOpaqueRoutingId(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null) {
+        const candidate = value;
+        if (typeof candidate.toHex === 'function') {
+            const hex = candidate.toHex.call(value);
+            if (typeof hex === 'string') {
+                return normalizeRoutingIdHex(hex);
+            }
+        }
+        if (typeof candidate.toString === 'function') {
+            const text = candidate.toString.call(value);
+            if (typeof text === 'string' && text !== '[object Object]')
+                return text;
+        }
+    }
+    throw new TypeError('RoutingId must be a string or expose a string conversion.');
+}
+function decodeRoutingId(text, hex) {
+    if (typeof hex !== 'string') {
+        return normalizeRoutingId(text);
+    }
+    const normalizedHex = normalizeRoutingIdHex(hex);
+    const bytes = Buffer.from(normalizedHex, 'hex');
+    const decoded = bytes.toString('utf8');
+    if (Buffer.from(decoded, 'utf8').toString('hex') === normalizedHex
+        && !/[\u0000-\u001f\u007f-\u009f]/u.test(decoded)) {
+        return normalizeRoutingId(decoded);
+    }
+    return new ZLinkOpaqueRoutingId(text, normalizedHex);
+}
+function routingIdWireHex(routingId) {
+    const value = routingId;
+    return typeof value.toHex === 'function'
+        ? value.toHex.call(routingId).toLowerCase()
+        : undefined;
+}
+function encodeRoutingIdStorageHex(routingId) {
+    const wireHex = routingIdWireHex(routingId);
+    if (wireHex !== undefined) {
+        return wireHex;
+    }
+    if (typeof routingId !== 'string') {
+        throw new TypeError('RoutingId must be a string or expose toHex().');
+    }
+    return Buffer.from(routingId, 'utf8').toString('hex');
+}
+function toBackendRoutingId(routingId) {
+    if (typeof routingId === 'string') {
+        return routingId;
+    }
+    const value = routingId;
+    if (typeof value.toBytes === 'function') {
+        const bytes = value.toBytes.call(routingId);
+        return new ZLinkOpaqueRoutingId(String(routingId), Buffer.from(bytes).toString('hex'));
+    }
+    if (typeof value.toHex === 'function') {
+        return new ZLinkOpaqueRoutingId(String(routingId), normalizeRoutingIdHex(value.toHex.call(routingId)));
+    }
+    throw new TypeError('RoutingId must be a string or expose toBytes() or toHex().');
+}
+function normalizeRoutingIdHex(value) {
+    const hex = value.toLowerCase();
+    if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-f]+$/.test(hex)) {
+        throw new TypeError('RoutingId hex must contain a non-empty, even number of hexadecimal digits.');
+    }
+    return hex;
+}
+function routingIdsEqual(left, right) {
+    if (left === undefined || right === undefined) {
+        return left === right;
+    }
+    if (left === right)
+        return true;
+    if (typeof left === 'string' && typeof right === 'string')
+        return false;
+    return encodeRoutingIdStorageHex(left) === encodeRoutingIdStorageHex(right);
+}

package/dist/runtime/spots/formal-remote-actor-admission-registry.d.ts

@@ -0,0 +1,124 @@
+import type { ActorRef, RoutingId, ZLinkActor, ZLinkActorJoinOperationId } from '../../contracts';
+import type { ZLinkRemoteBoundSessionTarget } from '../actors/actor-runtime-state';
+import type { ZLinkDeferredJoinAcceptedRoot } from '../actors/deferred-join-accepted-journal';
+import type { ZLinkActorRequestTerminal } from './spot-actor-packet-dispatch';
+/**
+ * One production-ingress arrival parked at the target between admission
+ * Accepted and the cutover that makes the Actor resolvable (spec 15 §4.2
+ * relocation temporary queue). Header/payload are kept as raw bytes — not
+ * as the original {@link Message} objects — so parking never depends on
+ * how long the underlying buffer stays valid.
+ */
+export interface ZLinkParkedActorArrival {
+    readonly header: Buffer;
+    readonly payload: Buffer;
+    readonly returnResponse: boolean;
+    readonly remoteBoundSessionTarget?: ZLinkRemoteBoundSessionTarget;
+    readonly fallbackActorRef?: ActorRef;
+    readonly requestTerminal?: ZLinkActorRequestTerminal;
+    readonly resolve: (value: unknown) => void;
+    readonly reject: (reason: unknown) => void;
+}
+export type ZLinkActorJoinIngressRoute = 'parked' | 'not-found';
+export type ZLinkFormalRemoteActorAdmissionState = 'provisional' | 'admitting' | 'admitted' | 'rejected' | 'committed' | 'aborted' | 'failed';
+export interface ZLinkFormalRemoteActorAdmission {
+    readonly actorId: string;
+    readonly actorType: string;
+    readonly actorRef: ActorRef;
+    readonly spotId: RoutingId;
+    readonly targetSpotGeneration: bigint;
+    readonly expectedMembershipEpoch: bigint;
+    readonly requestFingerprint: string;
+    readonly transferId: string;
+    readonly completionOperationId?: ZLinkActorJoinOperationId;
+    readonly sourceSpotId?: RoutingId;
+    readonly sourceActorNodeRid?: RoutingId;
+}
+export type ZLinkProvisionalRemoteActorAdmission = Omit<ZLinkFormalRemoteActorAdmission, 'actorType'>;
+export interface ZLinkFormalRemoteActorAdmissionOutcome {
+    readonly accepted: boolean;
+    readonly actorRef: ActorRef;
+    readonly reply?: Buffer;
+    readonly replyContentType?: string;
+    readonly deferredJoinRoot?: ZLinkDeferredJoinAcceptedRoot;
+}
+export interface ZLinkFormalRemoteActorAdmissionFailure {
+    readonly error: unknown;
+}
+export type ZLinkFormalRemoteActorAdmissionResult = ZLinkFormalRemoteActorAdmissionOutcome | ZLinkFormalRemoteActorAdmissionFailure;
+export interface ZLinkFormalRemoteActorAdmissionRecord {
+    readonly admission: ZLinkFormalRemoteActorAdmission;
+    readonly state: ZLinkFormalRemoteActorAdmissionState;
+    readonly result?: ZLinkFormalRemoteActorAdmissionResult;
+    readonly actor?: ZLinkActor;
+    readonly resultTask: Promise<ZLinkFormalRemoteActorAdmissionResult>;
+}
+interface ZLinkFormalRemoteActorAdmissionEntry extends ZLinkFormalRemoteActorAdmissionRecord {
+    readonly timer: ReturnType<typeof setTimeout>;
+    readonly resolveResult: (result: ZLinkFormalRemoteActorAdmissionResult) => void;
+    admission: ZLinkFormalRemoteActorAdmission;
+    state: ZLinkFormalRemoteActorAdmissionState;
+    result?: ZLinkFormalRemoteActorAdmissionResult;
+    actor?: ZLinkActor;
+    parked: ZLinkParkedActorArrival[];
+    migrated: boolean;
+}
+/** Owns target-side admission, commit tombstones and duplicate request handling. */
+export declare class ZLinkFormalRemoteActorAdmissionRegistry {
+    private readonly admissions;
+    private readonly byObject;
+    get(transferId: string): ZLinkFormalRemoteActorAdmissionEntry | undefined;
+    begin(input: ZLinkFormalRemoteActorAdmission): {
+        readonly record: ZLinkFormalRemoteActorAdmissionEntry;
+        readonly created: boolean;
+    };
+    /**
+     * Installs the exact object/handoff identity synchronously before canonical
+     * Store and factory validation yields. The actor type is deliberately not
+     * invented while that validation is pending; {@link finalizeProvisional}
+     * supplies it once the Store result is available.
+     */
+    beginProvisional(input: ZLinkProvisionalRemoteActorAdmission): {
+        readonly record: ZLinkFormalRemoteActorAdmissionEntry;
+        readonly created: boolean;
+    };
+    /** Completes a synchronous provisional registration after async validation. */
+    finalizeProvisional(transferId: string, input: ZLinkFormalRemoteActorAdmission): ZLinkFormalRemoteActorAdmissionEntry;
+    private create;
+    /**
+     * Production ingress lookup (spec 15 §4.2). Parks the arrival in the
+     * relocation temporary queue if an attempt exists for the object and has
+     * not yet migrated, or reports not-found so the caller falls through to
+     * its existing missing-actor handling — either because no attempt was
+     * ever registered for this object, or because the attempt already
+     * migrated and the Actor should now resolve directly. Synchronous: the
+     * object-key lookup and the park decision are one critical section, so
+     * no arrival can slip between lookup and park.
+     */
+    routeIngress(actorId: string, objectGeneration: bigint, arrival: ZLinkParkedActorArrival): ZLinkActorJoinIngressRoute;
+    /**
+     * Installs the migrated state and atomically (synchronously) drains
+     * every arrival parked since admission, in order, so the caller can
+     * dispatch them for real once the Actor is resolvable (spec 15 §4.2).
+     * The drain snapshot is taken and `migrated` flips inside one
+     * synchronous critical section — an arrival racing this call sees
+     * either the pre-migration parked queue or `migrated === true` and
+     * ordinary ingress, never a window where it is silently lost.
+     */
+    completeMigration(transferId: string): readonly ZLinkParkedActorArrival[];
+    private evict;
+    private failParked;
+    complete(transferId: string, outcome: ZLinkFormalRemoteActorAdmissionOutcome): void;
+    fail(transferId: string, error: unknown): void;
+    markCommitted(transferId: string, actor: ZLinkActor): void;
+    attachDeferredJoinRoot(transferId: string, root: ZLinkDeferredJoinAcceptedRoot): void;
+    abort(transferId: string): void;
+    /**
+     * Releases the admission for {@code transferId} — normal retention
+     * expiry, or explicit cleanup once the transfer is fully resolved. Any
+     * arrival still parked at release time fails exactly once (spec 15
+     * §4.2), mirroring {@link #abort}.
+     */
+    delete(transferId: string): void;
+}
+export {};

package/dist/runtime/spots/formal-remote-actor-admission-registry.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkFormalRemoteActorAdmissionRegistry = void 0;
+const ADMISSION_RETENTION_MS = 30_000;
+/** Identifies the object one admission attempt belongs to. */
+function objectKey(actorId, objectGeneration) {
+    return `${actorId}\u0000${objectGeneration}`;
+}
+/** Owns target-side admission, commit tombstones and duplicate request handling. */
+class ZLinkFormalRemoteActorAdmissionRegistry {
+    admissions = new Map();
+    //  Spec 15 §4.2 "같은 object의 relocation temporary queue는 하나만
+    //  존재한다": at most one admission attempt per (actorId,
+    //  objectGeneration). A newer exact identity for the same object evicts
+    //  the older attempt — newest attempt wins.
+    byObject = new Map();
+    get(transferId) {
+        return this.admissions.get(transferId);
+    }
+    begin(input) {
+        const existing = this.admissions.get(input.transferId);
+        if (existing !== undefined) {
+            if (!sameAdmission(existing.admission, input)) {
+                throw new Error(`Remote actor admission '${input.transferId}' does not match the original request.`);
+            }
+            return { record: existing, created: false };
+        }
+        return this.create(input, 'admitting');
+    }
+    /**
+     * Installs the exact object/handoff identity synchronously before canonical
+     * Store and factory validation yields. The actor type is deliberately not
+     * invented while that validation is pending; {@link finalizeProvisional}
+     * supplies it once the Store result is available.
+     */
+    beginProvisional(input) {
+        const existing = this.admissions.get(input.transferId);
+        if (existing !== undefined) {
+            if (!sameProvisionalAdmission(existing.admission, input)) {
+                throw new Error(`Remote actor admission '${input.transferId}' does not match the original request.`);
+            }
+            return { record: existing, created: false };
+        }
+        return this.create({ ...input, actorType: '' }, 'provisional');
+    }
+    /** Completes a synchronous provisional registration after async validation. */
+    finalizeProvisional(transferId, input) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined) {
+            throw new Error(`Remote actor admission '${transferId}' was evicted during validation.`);
+        }
+        if (!sameProvisionalAdmission(entry.admission, input)) {
+            throw new Error(`Remote actor admission '${transferId}' changed during validation.`);
+        }
+        if (entry.state === 'provisional') {
+            entry.admission = input;
+            entry.state = 'admitting';
+        }
+        else if (!sameAdmission(entry.admission, input)) {
+            throw new Error(`Remote actor admission '${transferId}' resolved a different Actor type.`);
+        }
+        return entry;
+    }
+    create(input, state) {
+        const key = objectKey(input.actorId, input.actorRef.objectGeneration);
+        const displacedTransferId = this.byObject.get(key);
+        if (displacedTransferId !== undefined && displacedTransferId !== input.transferId) {
+            this.evict(displacedTransferId);
+        }
+        let resolveResult;
+        const resultTask = new Promise((resolve) => {
+            resolveResult = resolve;
+        });
+        const timer = setTimeout(() => {
+            this.delete(input.transferId);
+        }, ADMISSION_RETENTION_MS);
+        timer.unref();
+        const entry = {
+            admission: input,
+            state,
+            resultTask,
+            timer,
+            resolveResult,
+            parked: [],
+            migrated: false
+        };
+        this.admissions.set(input.transferId, entry);
+        this.byObject.set(key, input.transferId);
+        return { record: entry, created: true };
+    }
+    /**
+     * Production ingress lookup (spec 15 §4.2). Parks the arrival in the
+     * relocation temporary queue if an attempt exists for the object and has
+     * not yet migrated, or reports not-found so the caller falls through to
+     * its existing missing-actor handling — either because no attempt was
+     * ever registered for this object, or because the attempt already
+     * migrated and the Actor should now resolve directly. Synchronous: the
+     * object-key lookup and the park decision are one critical section, so
+     * no arrival can slip between lookup and park.
+     */
+    routeIngress(actorId, objectGeneration, arrival) {
+        const transferId = this.byObject.get(objectKey(actorId, objectGeneration));
+        if (transferId === undefined)
+            return 'not-found';
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined
+            || entry.migrated
+            || entry.state === 'rejected'
+            || entry.state === 'aborted'
+            || entry.state === 'failed') {
+            return 'not-found';
+        }
+        entry.parked.push(arrival);
+        return 'parked';
+    }
+    /**
+     * Installs the migrated state and atomically (synchronously) drains
+     * every arrival parked since admission, in order, so the caller can
+     * dispatch them for real once the Actor is resolvable (spec 15 §4.2).
+     * The drain snapshot is taken and `migrated` flips inside one
+     * synchronous critical section — an arrival racing this call sees
+     * either the pre-migration parked queue or `migrated === true` and
+     * ordinary ingress, never a window where it is silently lost.
+     */
+    completeMigration(transferId) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined) {
+            throw new Error(`Remote actor admission '${transferId}' was evicted before its relocation temporary queue could migrate.`);
+        }
+        const drained = entry.parked;
+        entry.parked = [];
+        entry.migrated = true;
+        return drained;
+    }
+    evict(transferId) {
+        if (!this.admissions.has(transferId))
+            return;
+        this.abort(transferId);
+        this.delete(transferId);
+    }
+    failParked(entry, reason) {
+        if (entry.parked.length === 0)
+            return;
+        const parked = entry.parked;
+        entry.parked = [];
+        const aborted = reason ?? new Error(`Actor Join relocation temporary queue for '${entry.admission.actorId}' was aborted.`);
+        for (const message of parked) {
+            message.reject(aborted);
+        }
+    }
+    complete(transferId, outcome) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined || entry.state === 'aborted' || entry.state === 'committed')
+            return;
+        entry.state = outcome.accepted ? 'admitted' : 'rejected';
+        entry.result = {
+            accepted: outcome.accepted,
+            actorRef: { ...outcome.actorRef },
+            ...(outcome.reply === undefined ? {} : { reply: Buffer.from(outcome.reply) }),
+            ...(outcome.replyContentType === undefined
+                ? {}
+                : { replyContentType: outcome.replyContentType }),
+            ...(outcome.deferredJoinRoot === undefined
+                ? {}
+                : { deferredJoinRoot: outcome.deferredJoinRoot })
+        };
+        entry.resolveResult(entry.result);
+        if (!outcome.accepted) {
+            //  Spec 15 §4.2: Rejected admission removes the relocation
+            //  temporary queue and fails whatever it was still holding, in the
+            //  same processing step as the reject decision.
+            this.failParked(entry);
+        }
+    }
+    fail(transferId, error) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined || entry.state === 'aborted' || entry.state === 'committed')
+            return;
+        entry.state = 'failed';
+        entry.result = { error };
+        entry.resolveResult(entry.result);
+        this.failParked(entry, error);
+    }
+    markCommitted(transferId, actor) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined)
+            return;
+        if (entry.state !== 'admitted' && entry.state !== 'committed') {
+            throw new Error(`Remote actor admission '${transferId}' is not ready to commit.`);
+        }
+        entry.state = 'committed';
+        entry.actor = actor;
+    }
+    attachDeferredJoinRoot(transferId, root) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined || entry.state !== 'admitted'
+            || entry.result === undefined || 'error' in entry.result || !entry.result.accepted) {
+            throw new Error(`Remote actor admission '${transferId}' cannot attach deferred recovery.`);
+        }
+        entry.result = { ...entry.result, deferredJoinRoot: root };
+    }
+    abort(transferId) {
+        const entry = this.admissions.get(transferId);
+        if (entry === undefined || entry.state === 'committed')
+            return;
+        entry.state = 'aborted';
+        if (entry.result === undefined) {
+            entry.result = {
+                error: new Error(`Remote actor admission '${transferId}' was aborted.`)
+            };
+            entry.resolveResult(entry.result);
+        }
+        //  Spec 15 §4.2: Rejected admission or an explicit target abort
+        //  removes the relocation temporary queue and fails whatever it was
+        //  still holding, exactly once.
+        this.failParked(entry);
+    }
+    /**
+     * Releases the admission for {@code transferId} — normal retention
+     * expiry, or explicit cleanup once the transfer is fully resolved. Any
+     * arrival still parked at release time fails exactly once (spec 15
+     * §4.2), mirroring {@link #abort}.
+     */
+    delete(transferId) {
+        const pending = this.admissions.get(transferId);
+        if (pending === undefined)
+            return;
+        clearTimeout(pending.timer);
+        this.admissions.delete(transferId);
+        this.failParked(pending);
+        const key = objectKey(pending.admission.actorId, pending.admission.actorRef.objectGeneration);
+        if (this.byObject.get(key) === transferId) {
+            this.byObject.delete(key);
+        }
+    }
+}
+exports.ZLinkFormalRemoteActorAdmissionRegistry = ZLinkFormalRemoteActorAdmissionRegistry;
+function sameAdmission(left, right) {
+    return left.actorId === right.actorId
+        && left.actorType === right.actorType
+        && String(left.spotId) === String(right.spotId)
+        && left.targetSpotGeneration === right.targetSpotGeneration
+        && left.expectedMembershipEpoch === right.expectedMembershipEpoch
+        && left.requestFingerprint === right.requestFingerprint
+        && sameOperationId(left.completionOperationId, right.completionOperationId)
+        && String(left.sourceSpotId ?? '') === String(right.sourceSpotId ?? '')
+        && String(left.sourceActorNodeRid ?? '') === String(right.sourceActorNodeRid ?? '')
+        && left.actorRef.actorId === right.actorRef.actorId
+        && String(left.actorRef.nodeRid) === String(right.actorRef.nodeRid)
+        && left.actorRef.objectGeneration === right.actorRef.objectGeneration;
+}
+function sameProvisionalAdmission(left, right) {
+    return left.actorId === right.actorId
+        && String(left.spotId) === String(right.spotId)
+        && left.targetSpotGeneration === right.targetSpotGeneration
+        && left.expectedMembershipEpoch === right.expectedMembershipEpoch
+        && left.requestFingerprint === right.requestFingerprint
+        && sameOperationId(left.completionOperationId, right.completionOperationId)
+        && String(left.sourceSpotId ?? '') === String(right.sourceSpotId ?? '')
+        && String(left.sourceActorNodeRid ?? '') === String(right.sourceActorNodeRid ?? '')
+        && left.actorRef.actorId === right.actorRef.actorId
+        && String(left.actorRef.nodeRid) === String(right.actorRef.nodeRid)
+        && left.actorRef.objectGeneration === right.actorRef.objectGeneration;
+}
+function sameOperationId(left, right) {
+    return left === undefined || right === undefined
+        ? left === right
+        : left.high === right.high && left.low === right.low;
+}

package/dist/runtime/spots/formal-remote-actor-transfer-registry.d.ts

@@ -0,0 +1,33 @@
+import type { RoutingId, ZLinkActor } from '../../contracts';
+import type { ZLinkDeferredJoinAcceptedRoot } from '../actors';
+import type { ZLinkActorHandoffPacket } from '../actors/actor-handoff';
+export interface ZLinkFormalRemoteActorTransfer {
+    readonly actor: ZLinkActor;
+    readonly spotId: RoutingId;
+    readonly transferId: string;
+    readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
+    readonly deferredJoinRoot?: ZLinkDeferredJoinAcceptedRoot;
+    readonly targetLifecycleCompleted: Promise<void>;
+    readonly sourceLeaveSubmitted: Promise<boolean>;
+}
+/** Keeps the source-leave fence attached to one admitted formal transfer. */
+export declare class ZLinkFormalRemoteActorTransferRegistry {
+    private readonly lane;
+    private readonly transfers;
+    private readonly transfersById;
+    has(actorId: string): boolean;
+    get(actorId: string): ZLinkFormalRemoteActorTransfer | undefined;
+    getByTransferId(transferId: string): ZLinkFormalRemoteActorTransfer | undefined;
+    begin(input: {
+        readonly actor: ZLinkActor;
+        readonly spotId: RoutingId;
+        readonly transferId: string;
+        readonly handoffBacklog: readonly ZLinkActorHandoffPacket[];
+        readonly deferredJoinRoot?: ZLinkDeferredJoinAcceptedRoot;
+    }): ZLinkFormalRemoteActorTransfer;
+    delete(actorId: string): void;
+    completeTargetLifecycle(actorId: string, transferId: string): boolean;
+    completeSourceLeaveTerminal(actorId: string, transferId: string, succeeded: boolean): Promise<boolean>;
+    private completeSourceLeaveTerminalStartCore;
+    private completeSourceLeaveTerminalCore;
+}

package/dist/runtime/spots/formal-remote-actor-transfer-registry.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkFormalRemoteActorTransferRegistry = void 0;
+const state_lane_1 = require("../execution/state-lane");
+/** Keeps the source-leave fence attached to one admitted formal transfer. */
+class ZLinkFormalRemoteActorTransferRegistry {
+    lane = new state_lane_1.ZLinkStateLane();
+    transfers = new Map();
+    transfersById = new Map();
+    has(actorId) {
+        return this.transfers.has(actorId);
+    }
+    get(actorId) {
+        return this.transfers.get(actorId)?.transfer;
+    }
+    getByTransferId(transferId) {
+        return this.transfersById.get(transferId);
+    }
+    begin(input) {
+        const existingByActor = this.transfers.get(input.actor.context.actorId)?.transfer;
+        if (existingByActor !== undefined) {
+            if (existingByActor.transferId !== input.transferId) {
+                throw new Error(`Actor '${input.actor.context.actorId}' already has a different formal transfer.`);
+            }
+            return existingByActor;
+        }
+        const existingById = this.transfersById.get(input.transferId);
+        if (existingById !== undefined) {
+            if (existingById.actor.context.actorId !== input.actor.context.actorId) {
+                throw new Error(`Formal actor transfer '${input.transferId}' does not match its Actor.`);
+            }
+            return existingById;
+        }
+        let resolveSourceLeaveTerminal;
+        let resolveTargetLifecycleCompleted;
+        const targetLifecycleCompleted = new Promise((resolve) => {
+            resolveTargetLifecycleCompleted = resolve;
+        });
+        const sourceLeaveSubmitted = new Promise((resolve) => {
+            resolveSourceLeaveTerminal = resolve;
+        });
+        const transfer = {
+            ...input,
+            targetLifecycleCompleted,
+            sourceLeaveSubmitted
+        };
+        this.transfers.set(input.actor.context.actorId, {
+            transfer,
+            resolveTargetLifecycleCompleted,
+            resolveSourceLeaveTerminal
+        });
+        this.transfersById.set(input.transferId, transfer);
+        return transfer;
+    }
+    delete(actorId) {
+        const pending = this.transfers.get(actorId);
+        if (pending !== undefined) {
+            this.transfersById.delete(pending.transfer.transferId);
+            this.transfers.delete(actorId);
+        }
+    }
+    completeTargetLifecycle(actorId, transferId) {
+        const pending = this.transfers.get(actorId);
+        if (pending === undefined || pending.transfer.transferId !== transferId) {
+            return false;
+        }
+        pending.resolveTargetLifecycleCompleted();
+        return true;
+    }
+    async completeSourceLeaveTerminal(actorId, transferId, succeeded) {
+        // The synchronous lookup remains in the caller's JS turn. Only the
+        // target-lifecycle wait crosses turns, so the completion must re-check
+        // the exact entry after that external await.
+        const pending = this.completeSourceLeaveTerminalStartCore(actorId, transferId);
+        if (pending === undefined)
+            return false;
+        await pending.transfer.targetLifecycleCompleted;
+        return await this.lane.run(() => this.completeSourceLeaveTerminalCore(actorId, transferId, pending, succeeded));
+    }
+    completeSourceLeaveTerminalStartCore(actorId, transferId) {
+        const pending = this.transfers.get(actorId);
+        return pending === undefined || pending.transfer.transferId !== transferId
+            ? undefined
+            : pending;
+    }
+    completeSourceLeaveTerminalCore(actorId, transferId, pending, succeeded) {
+        if (pending.transfer.transferId !== transferId
+            || this.transfers.get(actorId) !== pending)
+            return false;
+        pending.resolveSourceLeaveTerminal(succeeded);
+        return true;
+    }
+}
+exports.ZLinkFormalRemoteActorTransferRegistry = ZLinkFormalRemoteActorTransferRegistry;