@zlink-systems/framework 0.10.0

package/dist/runtime/streams/actor-session-binding-registry.js

@@ -0,0 +1,1127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorSessionBindingRegistry = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const abort_1 = require("../abort");
+const node_async_hooks_1 = require("node:async_hooks");
+const state_lane_1 = require("../execution/state-lane");
+const routing_id_1 = require("../routing-id");
+const detachedStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:actor-session-binding-registry');
+class ZLinkActorSessionBindingRegistry {
+    terminalRelocationCapacity;
+    outboundCapacity;
+    sealWaitTimeoutMs;
+    lane = new state_lane_1.ZLinkStateLane();
+    routes = new Map();
+    sealWaiters = new Map();
+    activeFrameWaiters = new Map();
+    relocations = new Map();
+    terminalRelocations = new Map();
+    constructor(terminalRelocationCapacity = 4096, outboundCapacity = 4096, 
+    //  Spec 06 — SessionRelocationSealTimeout bounds how long a session
+    //  relocation seal may hold ingress (default 3,000 ms, finite only).
+    //  Every wait on the seal (accept paths) and on active-frame drain
+    //  (the sealing side) must observe that bound; an unbounded wait here
+    //  turns a lost control or a lifecycle interlock into a silent stall
+    //  (spec 48:205 — transport/deadline limits apply during relocation).
+    sealWaitTimeoutMs = 3_000) {
+        this.terminalRelocationCapacity = terminalRelocationCapacity;
+        this.outboundCapacity = outboundCapacity;
+        this.sealWaitTimeoutMs = sealWaitTimeoutMs;
+        if (!Number.isSafeInteger(terminalRelocationCapacity) || terminalRelocationCapacity <= 0) {
+            throw new RangeError('Session relocation terminal capacity must be a positive safe integer.');
+        }
+        if (!Number.isSafeInteger(outboundCapacity) || outboundCapacity <= 0) {
+            throw new RangeError('Session relocation outbound capacity must be a positive safe integer.');
+        }
+        if (!Number.isSafeInteger(sealWaitTimeoutMs) || sealWaitTimeoutMs <= 0) {
+            throw new RangeError('Session relocation seal timeout must be a positive safe integer.');
+        }
+    }
+    async bind(context, actor, bindingToken, authorityFence, sessionIdentity) {
+        await this.lane.run(() => this.bindCore(context, actor, bindingToken, authorityFence, sessionIdentity));
+    }
+    bindCore(context, actor, bindingToken, authorityFence, sessionIdentity) {
+        this.routes.set(actor.actorId, {
+            context,
+            actor,
+            bindingToken,
+            sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
+            activeFrames: { count: 0, requests: new Set() },
+            authorityFence
+        });
+        context.bindLocal(actor, bindingToken);
+    }
+    async replace(previous, context, actor, bindingToken, authorityFence, sessionIdentity) {
+        await this.lane.run(() => this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity));
+    }
+    replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity) {
+        const current = this.routes.get(actor.actorId);
+        if (current !== previous) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actor.actorId}' session binding changed before route replacement.`, true);
+        }
+        context.bindLocal(actor, bindingToken);
+        const sameLocalBinding = previous.context === context
+            && previous.bindingToken === bindingToken;
+        if (!sameLocalBinding) {
+            try {
+                previous.context.unbindLocal(actor.actorId, previous.bindingToken);
+            }
+            catch (error) {
+                context.unbindLocal(actor.actorId, bindingToken);
+                previous.context.bindLocal(previous.actor, previous.bindingToken);
+                throw error;
+            }
+        }
+        this.routes.set(actor.actorId, {
+            context,
+            actor,
+            bindingToken,
+            sessionIdentity: sessionIdentity ?? sessionIdentityFromContext(context),
+            activeFrames: previous.activeFrames,
+            sealId: previous.sealId,
+            authorityFence: authorityFence ?? previous.authorityFence
+        });
+    }
+    async replaceAndReleaseSeal(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity) {
+        await this.lane.run(() => this.replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity));
+    }
+    replaceAndReleaseSealCore(previous, context, actor, bindingToken, sealId, authorityFence, sessionIdentity) {
+        if (previous.sealId !== sealId) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actor.actorId}' route switch did not match its relocation seal.`, true);
+        }
+        // JavaScript cannot interleave another ingress turn between these two
+        // synchronous mutations. The replacement preserves the seal, then the
+        // exact release publishes the route to held ingress as one owner turn.
+        this.replaceCore(previous, context, actor, bindingToken, authorityFence, sessionIdentity);
+        if (!this.abortSealCore(actor.actorId, sealId)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actor.actorId}' route switch lost its relocation seal.`, true);
+        }
+    }
+    async find(actorId) {
+        return await this.lane.run(() => this.findCore(actorId));
+    }
+    findCore(actorId) {
+        return this.routes.get(actorId)?.actor;
+    }
+    async route(actorId) {
+        return await this.lane.run(() => this.routeCore(actorId));
+    }
+    routeCore(actorId) {
+        return this.routes.get(actorId);
+    }
+    async capturePendingReplyClaim(actorId, actor, bindingToken) {
+        return await this.lane.run(() => this.capturePendingReplyClaimCore(actorId, actor, bindingToken));
+    }
+    capturePendingReplyClaimCore(actorId, actor, bindingToken) {
+        const route = this.routes.get(actorId);
+        if (route === undefined || route.actor !== actor || route.bindingToken !== bindingToken) {
+            return undefined;
+        }
+        return Object.freeze({ context: route.context });
+    }
+    async unbind(actorId, context, bindingToken) {
+        await this.lane.run(() => this.unbindCore(actorId, context, bindingToken));
+    }
+    unbindCore(actorId, context, bindingToken) {
+        const route = this.routes.get(actorId);
+        if (route === undefined || route.context !== context || route.bindingToken !== bindingToken) {
+            return;
+        }
+        this.routes.delete(actorId);
+        context.unbindLocal(actorId, bindingToken);
+        this.rejectSealWaiters(actorId, new Error(`Actor '${actorId}' session binding was removed while ingress was held.`));
+        this.rejectActiveFrameWaiters(actorId, new Error(`Actor '${actorId}' session binding was removed while accepted frames were active.`));
+        this.clearRouteRelocation(actorId, route, new Error(`Actor '${actorId}' session binding was removed.`));
+    }
+    async unbindActor(actorId) {
+        await this.lane.run(() => this.unbindActorCore(actorId));
+    }
+    unbindActorCore(actorId) {
+        const route = this.routes.get(actorId);
+        if (route === undefined) {
+            return;
+        }
+        this.unbindCore(actorId, route.context, route.bindingToken);
+    }
+    async cleanup(context) {
+        await this.lane.run(() => this.cleanupCore(context));
+    }
+    cleanupCore(context) {
+        for (const route of [...this.routes.values()]) {
+            if (route.context === context) {
+                this.unbindCore(route.actor.actorId, context, route.bindingToken);
+            }
+        }
+    }
+    async requireRoute(actorId) {
+        return await this.lane.run(() => this.requireRouteCore(actorId));
+    }
+    requireRouteCore(actorId) {
+        const route = this.routes.get(actorId);
+        if (route !== undefined) {
+            return route;
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `No current session binding exists for actor '${actorId}'.`, true);
+    }
+    async requireCurrentToken(actorId, bindingToken) {
+        await this.lane.run(() => this.requireCurrentTokenCore(actorId, bindingToken));
+    }
+    requireCurrentTokenCore(actorId, bindingToken) {
+        const route = this.requireRouteCore(actorId);
+        if (route.bindingToken === bindingToken) {
+            return;
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorId}' session binding is stale.`, true);
+    }
+    async accept(actorId, bindingToken) {
+        await this.lane.run(() => this.acceptCore(actorId, bindingToken));
+    }
+    acceptCore(actorId, bindingToken) {
+        const route = this.requireRouteCore(actorId);
+        if (route.bindingToken !== bindingToken) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorId}' session binding is stale.`, true);
+        }
+        if (route.sealId !== undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' session ingress is sealed for relocation.`, true);
+        }
+    }
+    /**
+     * Holds Session ingress accepted after a relocation seal until the target
+     * route is published and the seal is released. The caller keeps the
+     * request payload and reply context open while this wait is in progress.
+     */
+    async acceptWhenReady(actorId, bindingToken, signal) {
+        for (;;) {
+            (0, abort_1.throwIfAborted)(signal);
+            const accepted = await this.lane.run(() => this.acceptWhenReadyCore(actorId, bindingToken));
+            if (accepted)
+                return;
+            await this.waitForSealRelease(actorId, bindingToken, signal);
+        }
+    }
+    acceptWhenReadyCore(actorId, bindingToken) {
+        const route = this.requireRouteCore(actorId);
+        this.requireCurrentTokenCore(actorId, bindingToken);
+        if (route.sealId === undefined) {
+            try {
+                this.acceptCore(actorId, bindingToken);
+                return true;
+            }
+            catch (error) {
+                // A new seal can race the check above. Re-enter the wait only for
+                // that relocation fence; unrelated binding failures stay visible.
+                if (this.routes.get(actorId)?.sealId === undefined)
+                    throw error;
+            }
+        }
+        return false;
+    }
+    async beginAcceptedFrameWhenReady(actorId, bindingToken, signal) {
+        for (;;) {
+            (0, abort_1.throwIfAborted)(signal);
+            const admission = await this.lane.run(() => this.beginAcceptedFrameCore(actorId, bindingToken));
+            if (admission !== undefined)
+                return admission;
+            await this.waitForSealRelease(actorId, bindingToken, signal);
+        }
+    }
+    beginAcceptedFrameCore(actorId, bindingToken) {
+        const route = this.requireRouteCore(actorId);
+        this.requireCurrentTokenCore(actorId, bindingToken);
+        if (route.sealId !== undefined)
+            return undefined;
+        route.activeFrames.count++;
+        let completed = false;
+        const completeCore = () => {
+            if (completed)
+                return;
+            completed = true;
+            route.activeFrames.count--;
+            if (route.activeFrames.count === 0
+                && this.routes.get(actorId)?.activeFrames === route.activeFrames) {
+                this.resolveActiveFrameWaiters(actorId);
+            }
+        };
+        return {
+            complete: async () => {
+                await this.lane.run(completeCore);
+            },
+            completeCore
+        };
+    }
+    async beginAcceptedRequestFrameWhenReady(actorId, bindingToken, signal) {
+        const frame = await this.beginAcceptedFrameWhenReady(actorId, bindingToken, signal);
+        return await this.lane.run(() => this.beginAcceptedRequestFrameCore(actorId, bindingToken, frame));
+    }
+    beginAcceptedRequestFrameCore(actorId, bindingToken, frame) {
+        const activeFrames = this.requireRouteCore(actorId).activeFrames;
+        let submissionStarted = false;
+        let capturedBySeal = false;
+        let finished = false;
+        const request = {
+            captureBySeal: () => {
+                if (finished || capturedBySeal)
+                    return;
+                capturedBySeal = true;
+                // Spec 20:389-396,408-412 — command 42 captures the Session-side
+                // frame, while the request correlation and its detached terminal
+                // remain alive. This removes the 42 -> request terminal -> 44 -> 42
+                // cycle without turning the capture into another submission.
+                frame.completeCore();
+            }
+        };
+        activeFrames.requests.add(request);
+        return {
+            beginSubmission: async (submissionSignal) => {
+                const captured = await this.lane.run(() => {
+                    if (submissionStarted)
+                        return false;
+                    // Claim before the asynchronous seal wait. A second continuation
+                    // must not observe an unclaimed request while the first is waiting
+                    // for command 44 to publish the route.
+                    submissionStarted = true;
+                    return capturedBySeal;
+                });
+                if (!captured)
+                    return;
+                await this.acceptWhenReady(actorId, bindingToken, submissionSignal);
+            },
+            complete: async () => {
+                await this.lane.run(() => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    activeFrames.requests.delete(request);
+                    frame.completeCore();
+                });
+            }
+        };
+    }
+    async runAcceptedFrameWhenReady(actorId, bindingToken, operation, signal) {
+        const admission = await this.beginAcceptedFrameWhenReady(actorId, bindingToken, signal);
+        try {
+            return await operation();
+        }
+        finally {
+            await admission.complete();
+        }
+    }
+    async seal(actorId, sealId, expected) {
+        await this.lane.run(() => this.sealCore(actorId, sealId, expected));
+    }
+    sealCore(actorId, sealId, expected) {
+        const route = this.requireRouteCore(actorId);
+        if (route.sealId !== undefined) {
+            if (route.sealId === sealId && routeMatchesFence(route, expected)) {
+                return;
+            }
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' session ingress is sealed by another relocation.`, true);
+        }
+        if (!routeMatchesFence(route, expected)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorId}' session route seal was fenced by its binding identity.`, true);
+        }
+        route.sealId = sealId;
+        // A pre-seal REQUEST is captured as part of installing command 42. Its
+        // Session frame no longer gates the seal; its single submission attempt
+        // and terminal continue under the request admission state above.
+        for (const request of route.activeFrames.requests) {
+            request.captureBySeal();
+        }
+    }
+    async sealAndWait(actorId, sealId, expected, signal) {
+        await this.lane.run(() => this.sealCore(actorId, sealId, expected));
+        await this.waitForActiveFrames(actorId, signal);
+    }
+    async sealRelocation(claim, expected, signal) {
+        for (;;) {
+            (0, abort_1.throwIfAborted)(signal);
+            const step = await this.lane.run(() => this.prepareRelocationSeal(claim, expected, signal));
+            if (step.kind === 'existing') {
+                await waitForSessionRelocation(step.wait, signal);
+                return;
+            }
+            if (step.kind === 'predecessor') {
+                await waitForSessionRelocation(step.wait, signal);
+                continue;
+            }
+            await step.wait;
+            return;
+        }
+    }
+    prepareRelocationSeal(claim, expected, signal) {
+        const queue = this.relocations.get(claim.actorId);
+        const existing = queue?.seals.get(claim.sealId);
+        if (existing !== undefined) {
+            assertRelocationClaim(existing, claim);
+            return { kind: 'existing', wait: existing.ready };
+        }
+        const predecessor = queue?.activeSealId === undefined
+            ? undefined
+            : queue.seals.get(queue.activeSealId);
+        if (predecessor !== undefined && predecessor.phase !== 'terminal') {
+            if (predecessor.sessionIdentity === undefined || claim.sessionIdentity === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${claim.actorId}' session ingress is sealed by another relocation.`, true);
+            }
+            assertSuccessorSessionIdentity(predecessor, claim);
+            return { kind: 'predecessor', wait: predecessor.terminal };
+        }
+        this.sealCore(claim.actorId, claim.sealId, expected);
+        let resolveTerminal;
+        const terminal = new Promise((resolve) => { resolveTerminal = resolve; });
+        const ready = this.waitForActiveFramesCore(claim.actorId, signal);
+        const actorQueue = queue ?? {
+            actorId: claim.actorId,
+            seals: new Map(),
+            outbound: [],
+            nextArrivalOrder: 1n,
+            outboundCount: 0
+        };
+        const state = {
+            ...claim,
+            phase: 'sealed',
+            ready,
+            terminal,
+            resolveTerminal
+        };
+        actorQueue.seals.set(claim.sealId, state);
+        actorQueue.activeSealId = claim.sealId;
+        this.relocations.set(claim.actorId, actorQueue);
+        return { kind: 'new', wait: ready };
+    }
+    async relocationSnapshot(actorId, sealId) {
+        return await this.lane.run(() => this.relocationSnapshotCore(actorId, sealId));
+    }
+    relocationSnapshotCore(actorId, sealId) {
+        return this.relocations.get(actorId)?.seals.get(sealId);
+    }
+    async retainRelocationOutbound(actorId, operation, sealId) {
+        return await this.lane.run(() => this.retainRelocationOutboundCorePublic(actorId, operation, sealId));
+    }
+    retainRelocationOutboundCorePublic(actorId, operation, sealId) {
+        if (sealId !== undefined) {
+            const queue = this.relocations.get(actorId);
+            const state = queue?.seals.get(sealId);
+            if (queue === undefined
+                || state === undefined
+                || (queue.activeSealId !== sealId
+                    && !(queue.activeSealId === undefined && state.phase === 'terminal'))) {
+                failRetainedOutbound(operation, new Error(`Actor '${actorId}' Session outbound did not match its exact relocation seal.`));
+                return 'rejected';
+            }
+        }
+        return this.retainRelocationOutboundCore(actorId, operation, 'legacy');
+    }
+    async admitRelocationOutbound(claim, operation) {
+        return await this.lane.run(() => this.admitRelocationOutboundCore(claim, operation));
+    }
+    admitRelocationOutboundCore(claim, operation) {
+        const queue = this.relocations.get(claim.actorId);
+        const state = queue?.activeSealId === undefined
+            ? undefined
+            : queue.seals.get(queue.activeSealId);
+        const error = this.outboundAdmissionError(claim);
+        if (error !== undefined) {
+            failRetainedOutbound(operation, error);
+            return 'rejected';
+        }
+        if (queue === undefined || state === undefined) {
+            if (!this.matchesCurrentProducerNode(claim)) {
+                failRetainedOutbound(operation, new Error(`Actor '${claim.actorId}' Session outbound admission was fenced by its current binding.`));
+                return 'rejected';
+            }
+            if (queue === undefined)
+                return 'passThrough';
+            return this.retainRelocationOutboundCore(claim.actorId, operation, 'source', claim);
+        }
+        if (state.phase === 'sealed' || state.phase === 'applying') {
+            const matchesSource = matchesRelocationSourceProof(state, claim);
+            const matchesCurrent = this.matchesCurrentProducerNode(claim);
+            const authorization = matchesSource || matchesCurrent
+                ? 'source'
+                : 'pendingTarget';
+            return this.retainRelocationOutboundCore(claim.actorId, operation, authorization, claim);
+        }
+        const acceptedProof = state.acceptedProducerProof;
+        if (acceptedProof === undefined
+            || !matchesAcceptedProducerProof(acceptedProof, claim)) {
+            failRetainedOutbound(operation, new Error(`Actor '${claim.actorId}' Session outbound admission did not match its accepted producer proof.`));
+            return 'rejected';
+        }
+        return this.retainRelocationOutboundCore(claim.actorId, operation, 'source', claim);
+    }
+    retainRelocationOutboundCore(actorId, operation, authorization, claim) {
+        const queue = this.relocations.get(actorId);
+        const state = queue?.activeSealId === undefined
+            ? undefined
+            : queue.seals.get(queue.activeSealId);
+        if (queue === undefined)
+            return 'passThrough';
+        if (state === undefined || state.phase === 'applied' || state.phase === 'terminal') {
+            if (queue.drainPromise === undefined && queue.outbound.length === 0)
+                return 'passThrough';
+            if (!this.reserveOutbound(queue, operation))
+                return 'rejected';
+            queue.outbound.push({
+                operation,
+                authorization,
+                arrivalOrder: queue.nextArrivalOrder++,
+                ...(claim === undefined ? {} : { claim }),
+                released: true,
+                settled: false
+            });
+            this.startOutboundDrain(queue);
+            return 'retained';
+        }
+        if (!this.reserveOutbound(queue, operation))
+            return 'rejected';
+        queue.outbound.push({
+            sealId: state.sealId,
+            operation,
+            authorization,
+            arrivalOrder: queue.nextArrivalOrder++,
+            ...(claim === undefined ? {} : { claim }),
+            released: false,
+            settled: false
+        });
+        return 'retained';
+    }
+    async discardRelocationOutbound(actorId, sealId, error) {
+        await this.lane.run(() => this.discardRelocationOutboundCore(actorId, sealId, error));
+    }
+    discardRelocationOutboundCore(actorId, sealId, error) {
+        const queue = this.relocations.get(actorId);
+        if (queue === undefined)
+            return;
+        for (let index = queue.outbound.length - 1; index >= 0; index--) {
+            const entry = queue.outbound[index];
+            if (entry.sealId !== sealId)
+                continue;
+            queue.outbound.splice(index, 1);
+            this.failOutbound(queue, entry, error);
+        }
+        this.deleteEmptyRelocationQueue(queue);
+    }
+    async applyRelocation(actorId, sealId, applyFingerprint, action, commitOwnerTransition, acceptedProducerProof) {
+        const prepared = await this.lane.run(() => this.prepareRelocationApply(actorId, sealId, applyFingerprint, action, acceptedProducerProof));
+        if (prepared.applyPromise !== undefined) {
+            await prepared.applyPromise;
+            return;
+        }
+        startOutsideStateLane(() => {
+            void (async () => {
+                try {
+                    await commitOwnerTransition();
+                    await this.lane.run(() => this.completeRelocationApply(prepared));
+                    prepared.resolve();
+                }
+                catch (error) {
+                    await this.lane.run(() => this.failRelocationApply(prepared));
+                    prepared.reject(error);
+                }
+            })();
+        });
+        await prepared.promise;
+    }
+    prepareRelocationApply(actorId, sealId, applyFingerprint, action, acceptedProducerProof) {
+        const queue = this.relocations.get(actorId);
+        const state = queue?.seals.get(sealId);
+        if (queue === undefined || state === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' route apply did not match its exact Session seal.`, true);
+        }
+        if (state.phase !== 'sealed') {
+            if (state.applyFingerprint !== applyFingerprint || state.applyPromise === undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' Session seal received a conflicting route apply.`, true);
+            }
+            return { queue, state, applyPromise: state.applyPromise };
+        }
+        if (action === 'commit'
+            && acceptedProducerProof !== undefined
+            && !validAcceptedTargetProof(state, acceptedProducerProof)) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' command 44 target producer proof did not match its Session seal.`, true);
+        }
+        if (action === 'abort' && acceptedProducerProof !== undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' abort route supplied a target producer proof.`, true);
+        }
+        state.phase = 'applying';
+        state.applyFingerprint = applyFingerprint;
+        let resolve;
+        let reject;
+        const promise = new Promise((complete, fail) => {
+            resolve = complete;
+            reject = fail;
+        });
+        state.applyPromise = promise;
+        return {
+            queue,
+            state,
+            action,
+            acceptedProducerProof,
+            promise,
+            resolve,
+            reject,
+            actorId,
+            sealId
+        };
+    }
+    completeRelocationApply(prepared) {
+        const { queue, state, action, acceptedProducerProof, actorId, sealId } = prepared;
+        const proof = action === 'commit'
+            ? acceptedProducerProof ?? this.currentProducerProof(actorId)
+            : relocationSourceProof(state);
+        state.acceptedProducerProof = proof;
+        for (let index = queue.outbound.length - 1; index >= 0; index--) {
+            const entry = queue.outbound[index];
+            if (entry.sealId !== sealId)
+                continue;
+            if (entry.authorization !== 'pendingTarget') {
+                entry.released = true;
+                continue;
+            }
+            if (action === 'commit'
+                && proof !== undefined
+                && entry.claim !== undefined
+                && matchesAcceptedProducerProof(proof, entry.claim)) {
+                entry.released = true;
+                continue;
+            }
+            queue.outbound.splice(index, 1);
+            this.failOutbound(queue, entry, new Error(`Actor '${actorId}' pending Session producer did not match command 44 proof.`));
+        }
+        this.startOutboundDrain(queue);
+        state.phase = 'applied';
+    }
+    failRelocationApply(prepared) {
+        prepared.state.phase = 'sealed';
+        prepared.state.applyFingerprint = undefined;
+        prepared.state.applyPromise = undefined;
+        prepared.state.acceptedProducerProof = undefined;
+    }
+    currentProducerProof(actorId) {
+        const route = this.routes.get(actorId);
+        const actorRef = (route?.actor).ref;
+        const sessionIdentity = route?.sessionIdentity;
+        if (route === undefined
+            || actorRef === undefined
+            || sessionIdentity === undefined
+            || actorRef.ownerNodeGeneration === undefined)
+            return undefined;
+        return {
+            actorId,
+            objectGeneration: BigInt(actorRef.objectGeneration
+                ?? actorRef.generation
+                ?? -1),
+            actorNodeRid: String(actorRef.nodeRid ?? ''),
+            actorNodeGeneration: BigInt(actorRef.ownerNodeGeneration),
+            sessionIdentity: String(sessionIdentity),
+            bindingGeneration: BigInt(actorRef.bindingGeneration ?? -1)
+        };
+    }
+    async observeRelocationTerminal(actorId, sealId, applyFingerprint) {
+        await this.lane.run(() => this.observeRelocationTerminalCore(actorId, sealId, applyFingerprint));
+    }
+    observeRelocationTerminalCore(actorId, sealId, applyFingerprint) {
+        const queue = this.relocations.get(actorId);
+        const state = queue?.seals.get(sealId);
+        if (queue === undefined
+            || state === undefined
+            || state.applyFingerprint !== applyFingerprint
+            || (state.phase !== 'applied' && state.phase !== 'terminal')) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${actorId}' Session relocation terminal did not match its exact route apply.`, true);
+        }
+        if (state.phase === 'terminal') {
+            this.rememberTerminalRelocation(state);
+            return;
+        }
+        state.phase = 'terminal';
+        if (queue.activeSealId === sealId)
+            queue.activeSealId = undefined;
+        state.resolveTerminal();
+        this.rememberTerminalRelocation(state);
+    }
+    /**
+     * Actor-wide relocation teardown: every seal (active and terminal-retained)
+     * and every held outbound entry for `actorId` is discarded unconditionally.
+     * Reserved for paths where the Actor itself is gone or being torn down
+     * (destroy, ownership clear, relocation-seal expiry/failure) — never for a
+     * single physical route's disconnect, which must not disturb a relocation
+     * seal it does not own (see `clearRouteRelocation`).
+     */
+    async clearRelocation(actorId, error) {
+        await this.lane.run(() => this.clearRelocationCore(actorId, error));
+    }
+    clearRelocationCore(actorId, error) {
+        const queue = this.relocations.get(actorId);
+        if (queue === undefined)
+            return;
+        this.relocations.delete(actorId);
+        for (const entry of queue.outbound.splice(0))
+            this.failOutbound(queue, entry, error);
+        for (const state of queue.seals.values()) {
+            this.terminalRelocations.delete(state);
+            if (state.phase !== 'terminal')
+                state.resolveTerminal();
+        }
+    }
+    /**
+     * Spec 48 §137: a relocation seal's lifecycle is independent of any single
+     * physical route's binding. Unbinding one physical route (a disconnect)
+     * must retire only the still-open (nonterminal) relocation seal that this
+     * exact route's Session owns, and the outbound held against that seal — it
+     * must never reach into a seal that has already reached 'terminal' (its
+     * bounded retention exists precisely so a late same-seal relay can still
+     * pass on a successor route) nor into a different Session's active seal
+     * (a concurrent successor that already re-sealed before this stale route
+     * noticed the disconnect).
+     */
+    clearRouteRelocation(actorId, route, error) {
+        const queue = this.relocations.get(actorId);
+        if (queue === undefined)
+            return;
+        const activeSealId = queue.activeSealId;
+        const activeState = activeSealId === undefined ? undefined : queue.seals.get(activeSealId);
+        const ownsActiveSeal = activeState !== undefined
+            && activeState.phase !== 'terminal'
+            && activeState.sessionIdentity === route.sessionIdentity;
+        if (!ownsActiveSeal) {
+            // Nothing this exact route still holds open — leave terminal
+            // retention and any other Session's active seal untouched.
+            this.deleteEmptyRelocationQueue(queue);
+            return;
+        }
+        for (let index = queue.outbound.length - 1; index >= 0; index--) {
+            const entry = queue.outbound[index];
+            if (entry.sealId !== activeSealId)
+                continue;
+            queue.outbound.splice(index, 1);
+            this.failOutbound(queue, entry, error);
+        }
+        queue.activeSealId = undefined;
+        queue.seals.delete(activeSealId);
+        this.terminalRelocations.delete(activeState);
+        activeState.resolveTerminal();
+        this.deleteEmptyRelocationQueue(queue);
+    }
+    async abortSeal(actorId, sealId) {
+        return await this.lane.run(() => this.abortSealCore(actorId, sealId));
+    }
+    abortSealCore(actorId, sealId) {
+        const route = this.routes.get(actorId);
+        if (route === undefined || route.sealId !== sealId)
+            return false;
+        route.sealId = undefined;
+        this.resolveSealWaiters(actorId, sealId);
+        return true;
+    }
+    async updateAuthorityFence(actorId, authorityFence) {
+        await this.lane.run(() => this.updateAuthorityFenceCore(actorId, authorityFence));
+    }
+    updateAuthorityFenceCore(actorId, authorityFence) {
+        const route = this.requireRouteCore(actorId);
+        route.authorityFence = authorityFence;
+    }
+    async validateSeal(actorId, sealId) {
+        return await this.lane.run(() => this.validateSealCore(actorId, sealId));
+    }
+    validateSealCore(actorId, sealId) {
+        const route = this.routes.get(actorId);
+        return route !== undefined
+            && route.sealId === sealId;
+    }
+    /** True while a relocation seal currently holds this actor's ingress. */
+    async isSealed(actorId) {
+        return await this.lane.run(() => this.isSealedCore(actorId));
+    }
+    isSealedCore(actorId) {
+        return this.routes.get(actorId)?.sealId !== undefined;
+    }
+    async waitForSealRelease(actorId, bindingToken, signal) {
+        const prepared = await this.lane.run(() => ({
+            wait: this.waitForSealReleaseCore(actorId, bindingToken, signal)
+        }));
+        await prepared.wait;
+    }
+    waitForSealReleaseCore(actorId, bindingToken, signal) {
+        const route = this.requireRouteCore(actorId);
+        this.requireCurrentTokenCore(actorId, bindingToken);
+        if (route.sealId === undefined)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const waiters = this.sealWaiters.get(actorId) ?? new Set();
+            let settled = false;
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+            };
+            const resolveWaiter = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve();
+            };
+            const rejectWaiter = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const waiter = { bindingToken, resolve: resolveWaiter, reject: rejectWaiter };
+            waiters.add(waiter);
+            this.sealWaiters.set(actorId, waiters);
+            const removeWaiter = () => {
+                waiters.delete(waiter);
+                if (waiters.size === 0)
+                    this.sealWaiters.delete(actorId);
+            };
+            timer = startOutsideStateLane(() => setTimeout(() => {
+                this.lane.tryPost(() => {
+                    removeWaiter();
+                    rejectWaiter((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor '${actorId}' session seal was not released within the relocation seal timeout.`, true));
+                });
+            }, this.sealWaitTimeoutMs));
+            timer.unref();
+            const onAbort = () => {
+                this.lane.tryPost(() => {
+                    removeWaiter();
+                    rejectWaiter(signal?.reason ?? (0, abort_1.createAbortError)());
+                });
+            };
+            if (signal === undefined)
+                return;
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            startOutsideStateLane(() => signal.addEventListener('abort', onAbort, { once: true }));
+        });
+    }
+    async waitForActiveFrames(actorId, signal) {
+        const prepared = await this.lane.run(() => ({
+            wait: this.waitForActiveFramesCore(actorId, signal)
+        }));
+        await prepared.wait;
+    }
+    waitForActiveFramesCore(actorId, signal) {
+        const route = this.requireRouteCore(actorId);
+        if (route.activeFrames.count === 0)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const waiters = this.activeFrameWaiters.get(actorId) ?? new Set();
+            let settled = false;
+            let timer;
+            const cleanup = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal?.removeEventListener('abort', onAbort);
+            };
+            const waiter = {
+                resolve: () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    resolve();
+                },
+                reject: (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    reject(error);
+                }
+            };
+            const onAbort = () => {
+                this.lane.tryPost(() => {
+                    waiters.delete(waiter);
+                    if (waiters.size === 0)
+                        this.activeFrameWaiters.delete(actorId);
+                    waiter.reject(signal?.reason ?? (0, abort_1.createAbortError)());
+                });
+            };
+            waiters.add(waiter);
+            this.activeFrameWaiters.set(actorId, waiters);
+            //  Spec 48:205 — transport/deadline limits keep applying during
+            //  relocation: the sealing side must not wait forever for active
+            //  frames that themselves may be waiting on this relocation.
+            timer = startOutsideStateLane(() => setTimeout(() => {
+                this.lane.tryPost(() => {
+                    waiters.delete(waiter);
+                    if (waiters.size === 0)
+                        this.activeFrameWaiters.delete(actorId);
+                    waiter.reject((0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.DeadlineExceeded, `Actor '${actorId}' session seal timed out waiting for active frames.`, true));
+                });
+            }, this.sealWaitTimeoutMs));
+            timer.unref();
+            if (signal === undefined)
+                return;
+            if (signal.aborted)
+                onAbort();
+            else
+                startOutsideStateLane(() => signal.addEventListener('abort', onAbort, { once: true }));
+        });
+    }
+    resolveActiveFrameWaiters(actorId) {
+        const waiters = this.activeFrameWaiters.get(actorId);
+        if (waiters === undefined)
+            return;
+        this.activeFrameWaiters.delete(actorId);
+        for (const waiter of waiters)
+            waiter.resolve();
+    }
+    rejectActiveFrameWaiters(actorId, error) {
+        const waiters = this.activeFrameWaiters.get(actorId);
+        if (waiters === undefined)
+            return;
+        this.activeFrameWaiters.delete(actorId);
+        for (const waiter of waiters)
+            waiter.reject(error);
+    }
+    startOutboundDrain(queue) {
+        if (queue.drainPromise !== undefined)
+            return;
+        const drain = startOutsideStateLane(async () => {
+            for (;;) {
+                const entry = await this.lane.run(() => {
+                    const current = queue.outbound.at(0);
+                    if (current === undefined || !current.released)
+                        return undefined;
+                    if (current.settled) {
+                        queue.outbound.shift();
+                        return null;
+                    }
+                    return current;
+                });
+                if (entry === undefined)
+                    return;
+                if (entry === null)
+                    continue;
+                try {
+                    const delivered = await entry.operation.deliver();
+                    await this.lane.run(() => {
+                        if (delivered)
+                            this.settleOutbound(queue, entry);
+                        else
+                            this.failOutbound(queue, entry, new Error(`Actor '${queue.actorId}' retained Session outbound delivery was rejected.`));
+                        if (queue.outbound[0] === entry)
+                            queue.outbound.shift();
+                    });
+                }
+                catch (error) {
+                    await this.lane.run(() => {
+                        this.failOutbound(queue, entry, error);
+                        if (queue.outbound[0] === entry)
+                            queue.outbound.shift();
+                    });
+                }
+            }
+        });
+        startOutsideStateLane(() => {
+            void drain.finally(async () => await this.lane.run(() => {
+                if (queue.drainPromise === drain)
+                    queue.drainPromise = undefined;
+                if (queue.outbound[0]?.released === true)
+                    this.startOutboundDrain(queue);
+                else
+                    this.deleteEmptyRelocationQueue(queue);
+            }));
+        });
+        queue.drainPromise = drain;
+    }
+    reserveOutbound(queue, operation) {
+        if (queue.outboundCount < this.outboundCapacity) {
+            queue.outboundCount++;
+            return true;
+        }
+        failRetainedOutbound(operation, new Error(`Actor '${queue.actorId}' Session relocation outbound capacity was exhausted.`));
+        return false;
+    }
+    settleOutbound(queue, entry) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        queue.outboundCount--;
+    }
+    failOutbound(queue, entry, error) {
+        if (entry.settled)
+            return;
+        this.settleOutbound(queue, entry);
+        failRetainedOutbound(entry.operation, error);
+    }
+    outboundAdmissionError(claim) {
+        if (claim.actorId.length === 0
+            || claim.objectGeneration <= 0n
+            || claim.actorNodeRid.length === 0
+            || claim.actorNodeGeneration <= 0n
+            || claim.producerNodeRid.length === 0
+            || claim.producerNodeGeneration <= 0n
+            || claim.bindingGeneration <= 0n
+            || claim.sessionIdentity.length === 0
+            || !(0, routing_id_1.routingIdsEqual)(claim.producerNodeRid, claim.actorNodeRid)
+            || claim.producerNodeGeneration !== claim.actorNodeGeneration) {
+            return new Error(`Actor '${claim.actorId}' Session outbound admission claim is invalid.`);
+        }
+        const route = this.routes.get(claim.actorId);
+        const ref = route?.actor;
+        const actorRef = ref?.ref;
+        const routeSessionIdentity = route?.sessionIdentity;
+        if (route === undefined
+            || actorRef === undefined
+            || String(actorRef.actorId ?? claim.actorId) !== claim.actorId
+            || BigInt(actorRef.objectGeneration
+                ?? actorRef.generation
+                ?? -1) !== claim.objectGeneration
+            || BigInt(actorRef.bindingGeneration ?? -1) !== claim.bindingGeneration
+            || String(routeSessionIdentity ?? '') !== claim.sessionIdentity) {
+            return new Error(`Actor '${claim.actorId}' Session outbound admission was fenced by its current binding.`);
+        }
+        return undefined;
+    }
+    matchesCurrentProducerNode(claim) {
+        const route = this.routes.get(claim.actorId);
+        const actorRef = (route?.actor).ref;
+        return route !== undefined
+            && actorRef !== undefined
+            && (0, routing_id_1.routingIdsEqual)(String(actorRef.nodeRid ?? ''), claim.actorNodeRid);
+    }
+    rememberTerminalRelocation(state) {
+        this.terminalRelocations.delete(state);
+        this.terminalRelocations.set(state, true);
+        while (this.terminalRelocations.size > this.terminalRelocationCapacity) {
+            const oldest = this.terminalRelocations.keys().next().value;
+            if (oldest === undefined)
+                return;
+            this.terminalRelocations.delete(oldest);
+            const queue = this.relocations.get(oldest.actorId);
+            if (queue?.seals.get(oldest.sealId) === oldest) {
+                queue.seals.delete(oldest.sealId);
+                this.deleteEmptyRelocationQueue(queue);
+            }
+        }
+    }
+    deleteEmptyRelocationQueue(queue) {
+        if (queue.activeSealId === undefined
+            && queue.seals.size === 0
+            && queue.outbound.length === 0
+            && queue.drainPromise === undefined
+            && this.relocations.get(queue.actorId) === queue) {
+            this.relocations.delete(queue.actorId);
+        }
+    }
+    resolveSealWaiters(actorId, _sealId) {
+        const waiters = this.sealWaiters.get(actorId);
+        if (waiters === undefined)
+            return;
+        this.sealWaiters.delete(actorId);
+        for (const waiter of waiters)
+            waiter.resolve();
+    }
+    rejectSealWaiters(actorId, error) {
+        const waiters = this.sealWaiters.get(actorId);
+        if (waiters === undefined)
+            return;
+        this.sealWaiters.delete(actorId);
+        for (const waiter of waiters)
+            waiter.reject(error);
+    }
+}
+exports.ZLinkActorSessionBindingRegistry = ZLinkActorSessionBindingRegistry;
+function assertRelocationClaim(state, claim) {
+    if (state.actorGeneration !== claim.actorGeneration
+        || state.bindingGeneration !== claim.bindingGeneration
+        || state.sessionIdentity !== claim.sessionIdentity
+        || state.actorNodeRid !== claim.actorNodeRid
+        || state.actorNodeGeneration !== claim.actorNodeGeneration) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${claim.actorId}' repeated Session seal changed its exact identity.`, true);
+    }
+}
+function startOutsideStateLane(work) {
+    return detachedStateLaneResource.runInAsyncScope(work);
+}
+function matchesRelocationSourceProof(state, claim) {
+    return state.actorId === claim.actorId
+        && state.actorGeneration === claim.objectGeneration
+        && state.bindingGeneration === claim.bindingGeneration
+        && state.sessionIdentity === claim.sessionIdentity
+        && state.actorNodeRid !== undefined
+        && (0, routing_id_1.routingIdsEqual)(state.actorNodeRid, claim.actorNodeRid)
+        && state.actorNodeGeneration === claim.actorNodeGeneration;
+}
+function matchesAcceptedProducerProof(proof, claim) {
+    return proof.actorId === claim.actorId
+        && proof.objectGeneration === claim.objectGeneration
+        && (0, routing_id_1.routingIdsEqual)(proof.actorNodeRid, claim.actorNodeRid)
+        && proof.actorNodeGeneration === claim.actorNodeGeneration
+        && proof.sessionIdentity === claim.sessionIdentity
+        && proof.bindingGeneration === claim.bindingGeneration;
+}
+function validAcceptedTargetProof(state, proof) {
+    return proof.actorId === state.actorId
+        && proof.objectGeneration === state.actorGeneration
+        && proof.actorNodeRid.length > 0
+        && proof.actorNodeGeneration > 0n
+        && proof.sessionIdentity === state.sessionIdentity
+        && proof.bindingGeneration === state.bindingGeneration;
+}
+function relocationSourceProof(state) {
+    if (state.sessionIdentity === undefined
+        || state.actorNodeRid === undefined
+        || state.actorNodeGeneration === undefined)
+        return undefined;
+    return {
+        actorId: state.actorId,
+        objectGeneration: state.actorGeneration,
+        actorNodeRid: state.actorNodeRid,
+        actorNodeGeneration: state.actorNodeGeneration,
+        sessionIdentity: state.sessionIdentity,
+        bindingGeneration: state.bindingGeneration
+    };
+}
+function failRetainedOutbound(operation, error) {
+    try {
+        operation.fail(error);
+    }
+    catch {
+        // The aggregate has already removed the entry. A failure observer cannot
+        // retain or settle the same delivery a second time.
+    }
+}
+function assertSuccessorSessionIdentity(predecessor, successor) {
+    if (predecessor.actorGeneration !== successor.actorGeneration
+        || predecessor.bindingGeneration !== successor.bindingGeneration
+        || predecessor.sessionIdentity !== successor.sessionIdentity) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${successor.actorId}' successor Session seal changed its exact Session identity.`, true);
+    }
+}
+function routeMatchesFence(route, expected) {
+    const ref = route.actor.ref;
+    return ref !== undefined
+        && BigInt(ref.objectGeneration ?? ref.generation ?? -1n) === expected.objectGeneration
+        && ref.bindingGeneration === expected.bindingGeneration;
+}
+function sessionIdentityFromContext(context) {
+    return context.routingId === undefined ? undefined : String(context.routingId);
+}
+function waitForSessionRelocation(operation, signal) {
+    if (signal === undefined)
+        return operation;
+    if (signal.aborted)
+        return Promise.reject(signal.reason ?? (0, abort_1.createAbortError)());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            signal.removeEventListener('abort', onAbort);
+            reject(signal.reason ?? (0, abort_1.createAbortError)());
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        operation.then(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, error => {
+            signal.removeEventListener('abort', onAbort);
+            reject(error);
+        });
+    });
+}