@zlink-systems/framework 0.10.0

package/dist/runtime/spots/spot-timer.js

@@ -0,0 +1,419 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkManagedTimer = exports.ZLinkSpotTimerRegistry = void 0;
+exports.createTimerDiagnostics = createTimerDiagnostics;
+exports.addEntrySpotTimerRegistrations = addEntrySpotTimerRegistrations;
+exports.addSpotTimerRegistrations = addSpotTimerRegistrations;
+const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
+const contracts_1 = require("../../contracts");
+const TimerRegistrationValidator_1 = require("../../contracts/Configuration/TimerRegistrationValidator");
+const abort_1 = require("../abort");
+const handler_instance_scope_1 = require("../handlers/handler-instance-scope");
+const flow_context_1 = require("../diagnostics/flow-context");
+const state_lane_1 = require("../execution/state-lane");
+const node_async_hooks_1 = require("node:async_hooks");
+const detachedTimerStateLaneResource = new node_async_hooks_1.AsyncResource('zlink:spot-timer');
+const systemTimerClock = {
+    now: () => performance.now(),
+    utcNow: () => Date.now(),
+    setTimeout: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimeout: handle => clearTimeout(handle)
+};
+class ZLinkSpotTimerRegistry {
+    flowCreationEnabled;
+    executionSerialForTimer;
+    executionAllowed;
+    executeTimer;
+    isTimerExecuting;
+    clock;
+    lane = new state_lane_1.ZLinkStateLane();
+    timers = new Map();
+    generations = new Map();
+    executionBarrier;
+    constructor(_metrics, flowCreationEnabled = () => true, executionSerialForTimer, executionAllowed = () => true, executeTimer, isTimerExecuting, clock) {
+        this.flowCreationEnabled = flowCreationEnabled;
+        this.executionSerialForTimer = executionSerialForTimer;
+        this.executionAllowed = executionAllowed;
+        this.executeTimer = executeTimer;
+        this.isTimerExecuting = isTimerExecuting;
+        this.clock = clock;
+    }
+    setExecutionBarrier(barrier) {
+        if (this.executionBarrier !== undefined && this.executionBarrier !== barrier) {
+            throw new Error('ZLink timer registry already belongs to another execution barrier.');
+        }
+        this.executionBarrier = barrier;
+    }
+    get hasActiveTimers() {
+        return this.timers.size > 0;
+    }
+    async add(name, periodMs, options, handlerType, serial, spot, providerResolver, signal, reportFailure) {
+        (0, TimerRegistrationValidator_1.validateTimerRegistration)(name, periodMs, options);
+        (0, abort_1.throwIfAborted)(signal);
+        const handler = await (0, handler_instance_scope_1.resolveLifecycleHandler)(spot, handlerType, providerResolver);
+        const prepared = await this.lane.run(() => this.prepareAddCore(name));
+        if (prepared.previous !== undefined)
+            await prepared.previous.timer.cancel(signal);
+        const executionSerial = this.executeTimer === undefined
+            ? this.executionSerialForTimer?.(name, serial) ?? serial
+            : undefined;
+        if (this.executionBarrier !== undefined)
+            executionSerial?.setExecutionBarrier(this.executionBarrier);
+        const timer = startOutsideStateLane(() => new ZLinkManagedTimer(name, periodMs, normalizeTimerOptions(options), async (tick) => {
+            const timerFlow = (0, flow_context_1.createInboundFlow)(undefined, 'Timer', this.flowCreationEnabled());
+            const operation = () => {
+                const current = this.timers.get(name);
+                if (current === undefined || current.generation !== prepared.generation || current.timer !== timer) {
+                    return undefined;
+                }
+                if (!this.executionAllowed())
+                    return undefined;
+                return (0, flow_context_1.runWithFlow)(timerFlow, () => handler.handle(spot, tick));
+            };
+            if (this.executeTimer !== undefined) {
+                await this.executeTimer(name, operation);
+            }
+            else {
+                await executionSerial.execute(operation);
+            }
+        }, reportFailure, () => this.executeTimer === undefined
+            ? !executionSerial.isExecuting
+            : this.isTimerExecuting?.(name) !== true, this.clock));
+        const registered = await this.lane.run(() => this.completeAddCore(name, prepared.generation, handlerType.name, timer));
+        if (!registered)
+            await timer.cancel(signal);
+        return new ZLinkRegisteredTimer(this, name, prepared.generation, timer);
+    }
+    async dispose() {
+        const timers = await this.lane.run(() => {
+            const active = [...this.timers.values()].map((entry) => entry.timer);
+            this.timers.clear();
+            return active;
+        });
+        for (const timer of timers) {
+            await timer.dispose();
+        }
+    }
+    async captureRelocation() {
+        const timers = await this.lane.run(() => [...this.timers.entries()].sort(([left], [right]) => left.localeCompare(right)));
+        const states = [];
+        for (const [name, entry] of timers) {
+            const state = await entry.timer.captureRelocation(entry.handlerType);
+            if (state.name !== name)
+                throw new Error('Timer relocation identity changed during capture.');
+            states.push(state);
+        }
+        return states;
+    }
+    restoreRelocation(states) {
+        const byName = new Map(states.map(state => [state.name, state]));
+        if (byName.size !== states.length || byName.size !== this.timers.size) {
+            throw new Error('Timer relocation inventory does not match registered handlers.');
+        }
+        for (const [name, entry] of this.timers) {
+            const state = byName.get(name);
+            if (state === undefined) {
+                throw new Error(`Timer '${name}' is missing from relocation state.`);
+            }
+            entry.timer.restoreRelocation(state, entry.handlerType);
+        }
+    }
+    abortRelocation(states) {
+        this.restoreRelocation(states);
+    }
+    async commitRelocation() {
+        await this.dispose();
+    }
+    async cancel(name, generation, timer, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        await this.lane.run(() => this.cancelCore(name, generation, timer));
+        await timer.cancel(signal);
+    }
+    prepareAddCore(name) {
+        const previous = this.timers.get(name);
+        this.timers.delete(name);
+        const generation = (this.generations.get(name) ?? 0n) + 1n;
+        this.generations.set(name, generation);
+        return { previous, generation };
+    }
+    completeAddCore(name, generation, handlerType, timer) {
+        if (this.generations.get(name) !== generation)
+            return false;
+        this.timers.set(name, { generation, handlerType, timer });
+        return true;
+    }
+    cancelCore(name, generation, timer) {
+        const current = this.timers.get(name);
+        if (current?.generation === generation && current.timer === timer) {
+            this.timers.delete(name);
+        }
+    }
+}
+exports.ZLinkSpotTimerRegistry = ZLinkSpotTimerRegistry;
+class ZLinkRegisteredTimer {
+    registry;
+    name;
+    generation;
+    timer;
+    constructor(registry, name, generation, timer) {
+        this.registry = registry;
+        this.name = name;
+        this.generation = generation;
+        this.timer = timer;
+    }
+    get isDisposed() {
+        return this.timer.isDisposed;
+    }
+    cancel(signal) {
+        return this.registry.cancel(this.name, this.generation, this.timer, signal);
+    }
+    dispose() {
+        return this.cancel();
+    }
+}
+class ZLinkManagedTimer {
+    name;
+    periodMs;
+    options;
+    onTick;
+    onFailure;
+    shouldWaitForRunningOnCancel;
+    clock;
+    lane = new state_lane_1.ZLinkStateLane();
+    disposed = false;
+    pausedForRelocation = false;
+    startedAtMs;
+    startedAtUnixMs;
+    deliveryIndex = 0n;
+    lastScheduledIndex = 0n;
+    timeout;
+    running = Promise.resolve();
+    constructor(name, periodMs, options, onTick, onFailure, shouldWaitForRunningOnCancel = () => true, clock = systemTimerClock) {
+        this.name = name;
+        this.periodMs = periodMs;
+        this.options = options;
+        this.onTick = onTick;
+        this.onFailure = onFailure;
+        this.shouldWaitForRunningOnCancel = shouldWaitForRunningOnCancel;
+        this.clock = clock;
+        this.startedAtMs = clock.now();
+        this.startedAtUnixMs = clock.utcNow();
+        this.scheduleNext();
+    }
+    get isDisposed() {
+        return this.disposed;
+    }
+    async cancel(_signal) {
+        const prepared = await this.lane.run(() => this.cancelCore());
+        await prepared.running;
+    }
+    dispose() {
+        return this.cancel();
+    }
+    async captureRelocation(handlerType = '') {
+        const prepared = await this.lane.run(() => this.prepareCaptureCore());
+        await prepared.running;
+        return await this.lane.run(() => ({
+            name: this.name,
+            handlerType,
+            periodMs: this.periodMs,
+            overrunPolicy: this.options.overrunPolicy,
+            maxCatchUpTicks: this.options.maxCatchUpTicks,
+            stopOnUnhandledException: this.options.stopOnUnhandledException,
+            startedAtUnixMs: this.startedAtUnixMs,
+            deliveryIndex: this.deliveryIndex,
+            lastScheduledIndex: this.lastScheduledIndex,
+            nextDueAtUnixMs: this.startedAtUnixMs + Number(this.lastScheduledIndex + 1n) * this.periodMs,
+            pendingTicks: []
+        }));
+    }
+    restoreRelocation(state, handlerType = '') {
+        if (this.disposed)
+            throw new Error(`Timer '${this.name}' is disposed.`);
+        if (state.name !== this.name
+            || state.handlerType !== handlerType
+            || state.periodMs !== this.periodMs
+            || state.overrunPolicy !== this.options.overrunPolicy
+            || state.maxCatchUpTicks !== this.options.maxCatchUpTicks
+            || state.stopOnUnhandledException !== this.options.stopOnUnhandledException
+            || !Number.isSafeInteger(state.startedAtUnixMs)
+            || state.deliveryIndex < 0n
+            || state.lastScheduledIndex < 0n
+            || !Number.isSafeInteger(state.nextDueAtUnixMs)
+            || state.nextDueAtUnixMs !== state.startedAtUnixMs
+                + Number(state.lastScheduledIndex + 1n) * state.periodMs
+            || state.pendingTicks.length !== 0) {
+            throw new Error(`Timer '${this.name}' relocation contract does not match its registration.`);
+        }
+        if (this.timeout !== undefined)
+            this.clock.clearTimeout(this.timeout);
+        this.timeout = undefined;
+        this.startedAtUnixMs = state.startedAtUnixMs;
+        this.startedAtMs = this.clock.now() - Math.max(0, this.clock.utcNow() - state.startedAtUnixMs);
+        this.deliveryIndex = state.deliveryIndex;
+        this.lastScheduledIndex = state.lastScheduledIndex;
+        this.pausedForRelocation = false;
+        this.scheduleNext();
+    }
+    scheduleNext() {
+        if (this.disposed || this.pausedForRelocation) {
+            return;
+        }
+        const delayMs = this.options.overrunPolicy === contracts_1.ZLinkTimerOverrunPolicy.DelayNextTick
+            ? this.periodMs
+            : Math.max(0, Number(this.lastScheduledIndex + 1n) * this.periodMs - this.elapsedMs());
+        this.timeout = this.clock.setTimeout(() => {
+            this.timeout = undefined;
+            this.running = startOutsideStateLane(() => this.fire()).catch(() => undefined);
+        }, delayMs);
+    }
+    async fire() {
+        const prepared = await this.lane.run(() => this.prepareFireCore());
+        if (prepared === undefined)
+            return;
+        let shouldContinue = true;
+        try {
+            await this.onTick(prepared.tick);
+        }
+        catch (cause) {
+            shouldContinue = !this.options.stopOnUnhandledException;
+            await this.onFailure?.(prepared.tick, cause, shouldContinue
+                ? internal_event_contracts_1.ZLinkSpotEventKind.TimerHandlerFailed
+                : internal_event_contracts_1.ZLinkSpotEventKind.TimerStoppedAfterUnhandledException);
+        }
+        await this.lane.run(() => this.completeFireCore(prepared.scheduledIndex, shouldContinue));
+    }
+    cancelCore() {
+        if (this.disposed)
+            return { running: Promise.resolve() };
+        this.disposed = true;
+        if (this.timeout !== undefined) {
+            this.clock.clearTimeout(this.timeout);
+            this.timeout = undefined;
+        }
+        return { running: this.shouldWaitForRunningOnCancel() ? this.running : Promise.resolve() };
+    }
+    prepareCaptureCore() {
+        if (this.disposed)
+            throw new Error(`Timer '${this.name}' is disposed.`);
+        this.pausedForRelocation = true;
+        if (this.timeout !== undefined) {
+            this.clock.clearTimeout(this.timeout);
+            this.timeout = undefined;
+        }
+        return { running: this.shouldWaitForRunningOnCancel() ? this.running : Promise.resolve() };
+    }
+    prepareFireCore() {
+        if (this.disposed)
+            return undefined;
+        const scheduledIndex = this.selectScheduledIndex();
+        const skippedTicks = scheduledIndex - this.lastScheduledIndex - 1n;
+        const startedElapsedMs = this.elapsedMs();
+        const scheduledElapsedMs = Number(scheduledIndex) * this.periodMs;
+        this.deliveryIndex += 1n;
+        return {
+            scheduledIndex,
+            tick: {
+                name: this.name,
+                deliveryIndex: this.deliveryIndex,
+                scheduledIndex,
+                periodMs: this.periodMs,
+                scheduledAt: new Date(this.startedAtUnixMs + scheduledElapsedMs),
+                startedAt: new Date(this.clock.utcNow()),
+                scheduledElapsedMs,
+                startedElapsedMs,
+                delayMs: startedElapsedMs - scheduledElapsedMs,
+                skippedTicks
+            }
+        };
+    }
+    completeFireCore(scheduledIndex, shouldContinue) {
+        this.lastScheduledIndex = scheduledIndex;
+        if (!shouldContinue) {
+            this.disposed = true;
+            return;
+        }
+        this.scheduleNext();
+    }
+    selectScheduledIndex() {
+        const nextScheduledIndex = this.lastScheduledIndex + 1n;
+        if (this.options.overrunPolicy === contracts_1.ZLinkTimerOverrunPolicy.DelayNextTick) {
+            return nextScheduledIndex;
+        }
+        // The due tick is the latest nominal tick the monotonic clock has reached, but never
+        // one that was already delivered: the platform timer truncates the delay to whole
+        // milliseconds and may start the callback a fraction before the nominal due time.
+        const elapsedIndex = BigInt(Math.floor(this.elapsedMs() / this.periodMs));
+        const dueScheduledIndex = elapsedIndex > nextScheduledIndex ? elapsedIndex : nextScheduledIndex;
+        if (this.options.overrunPolicy === contracts_1.ZLinkTimerOverrunPolicy.SkipLateTicks) {
+            return dueScheduledIndex;
+        }
+        const availableTicks = dueScheduledIndex - this.lastScheduledIndex;
+        const maxCatchUpTicks = BigInt(this.options.maxCatchUpTicks);
+        if (availableTicks > maxCatchUpTicks) {
+            return dueScheduledIndex - maxCatchUpTicks + 1n;
+        }
+        return nextScheduledIndex;
+    }
+    elapsedMs() {
+        return this.clock.now() - this.startedAtMs;
+    }
+}
+exports.ZLinkManagedTimer = ZLinkManagedTimer;
+function startOutsideStateLane(work) {
+    return detachedTimerStateLaneResource.runInAsyncScope(work);
+}
+function createTimerDiagnostics(sourceName, spotId, isEntrySpot, timerName, handlerType, publisher) {
+    if (publisher === undefined) {
+        return undefined;
+    }
+    return async (tick, cause, event = internal_event_contracts_1.ZLinkSpotEventKind.TimerHandlerFailed) => {
+        try {
+            await publisher.publish({
+                sourceName,
+                timestamp: new Date(),
+                event,
+                timerDiagnostic: {
+                    spotId,
+                    isEntrySpot,
+                    timerName,
+                    handlerType: handlerType.name,
+                    deliveryIndex: tick.deliveryIndex,
+                    scheduledIndex: tick.scheduledIndex,
+                    exceptionType: exceptionType(cause),
+                    exceptionMessage: exceptionMessage(cause)
+                }
+            });
+        }
+        catch {
+        }
+    };
+}
+async function addEntrySpotTimerRegistrations(timers, entrySpotType, entrySpot, serial, registrations, options) {
+    for (const handler of registrations.timerHandlers ?? []) {
+        if (handler.entrySpotType === entrySpotType) {
+            await timers.add(handler.name, handler.periodMs, handler.options, handler.handlerType, serial, entrySpot, options.providerResolver, undefined, createTimerDiagnostics(options.spotNodeName, options.spotId, true, handler.name, handler.handlerType, options.runtimeEventPublisher));
+        }
+    }
+}
+async function addSpotTimerRegistrations(timers, spotType, spotId, spot, serial, registrations, options) {
+    for (const handler of registrations.timerHandlers ?? []) {
+        if (handler.spotType === spotType
+            || spotType.prototype instanceof handler.spotType) {
+            await timers.add(handler.name, handler.periodMs, handler.options, handler.handlerType, serial, spot, options.providerResolver, options.signal, createTimerDiagnostics(String(spotId), spotId, false, handler.name, handler.handlerType, options.runtimeEventPublisher));
+        }
+    }
+}
+function normalizeTimerOptions(options) {
+    return {
+        overrunPolicy: options?.overrunPolicy ?? contracts_1.ZLinkTimerOverrunPolicy.SkipLateTicks,
+        maxCatchUpTicks: options?.maxCatchUpTicks ?? 1,
+        stopOnUnhandledException: options?.stopOnUnhandledException ?? false
+    };
+}
+function exceptionType(cause) {
+    return cause instanceof Error ? cause.name : typeof cause;
+}
+function exceptionMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/runtime/streams/actor-session-binding-registry.d.ts

@@ -0,0 +1,193 @@
+import type { ServiceSessionBindingAdmissionClaim, ServiceSessionBindingAdmissionResult } from '../foundation/service-session-binding-ingress-port';
+export interface ZLinkActorSessionBindingActor {
+    readonly actorId: string;
+}
+export interface ZLinkActorSessionBindingContext<TActor extends ZLinkActorSessionBindingActor> {
+    readonly routingId?: unknown;
+    bindLocal(actor: TActor, bindingToken: string): void;
+    unbindLocal(actorId: string, bindingToken: string): void;
+}
+export interface ZLinkActorSessionRoute<TContext extends ZLinkActorSessionBindingContext<TActor>, TActor extends ZLinkActorSessionBindingActor> {
+    readonly context: TContext;
+    readonly actor: TActor;
+    readonly bindingToken: string;
+    readonly sessionIdentity?: string;
+    readonly activeFrames: ZLinkActorSessionActiveFrames;
+    sealId?: string;
+    authorityFence?: ZLinkActorSessionAuthorityFence;
+}
+export interface ZLinkActorSessionRelocationClaim {
+    readonly actorId: string;
+    readonly actorGeneration: bigint;
+    readonly bindingGeneration: bigint;
+    readonly sessionIdentity?: string;
+    readonly actorNodeRid?: string;
+    readonly actorNodeGeneration?: bigint;
+    readonly sealId: string;
+}
+export interface ZLinkActorSessionRetainedOutbound {
+    deliver(): Promise<boolean>;
+    fail(error: unknown): void;
+}
+export interface ZLinkActorSessionAcceptedProducerProof {
+    readonly actorId: string;
+    readonly objectGeneration: bigint;
+    readonly actorNodeRid: string;
+    readonly actorNodeGeneration: bigint;
+    readonly sessionIdentity: string;
+    readonly bindingGeneration: bigint;
+}
+export interface ZLinkActorSessionRelocationSnapshot extends ZLinkActorSessionRelocationClaim {
+    readonly phase: 'sealed' | 'applying' | 'applied' | 'terminal';
+    readonly applyFingerprint?: string;
+}
+interface ZLinkActorSessionFrameAdmission {
+    complete(): Promise<void>;
+    completeCore(): void;
+}
+interface ZLinkActorSessionRequestFrameAdmission {
+    complete(): Promise<void>;
+    /**
+     * Claims the one allowed submission attempt. A request captured by a seal
+     * before this call waits for that exact seal to publish or abort its route;
+     * a request captured after this call only observes its original terminal.
+     */
+    beginSubmission(signal?: AbortSignal): Promise<void> | undefined;
+}
+interface ZLinkActorSessionActiveFrames {
+    count: number;
+    readonly requests: Set<{
+        captureBySeal(): void;
+    }>;
+}
+export interface ZLinkActorSessionAuthorityFence {
+    readonly authorityOwnerGeneration: bigint;
+    readonly ownerLeaseGeneration: bigint;
+    readonly ownerId?: string;
+    readonly ownerNodeGeneration?: bigint;
+    readonly authorityStoreVersion?: string;
+    readonly actorType?: string;
+}
+export declare class ZLinkActorSessionBindingRegistry<TContext extends ZLinkActorSessionBindingContext<TActor>, TActor extends ZLinkActorSessionBindingActor> {
+    private readonly terminalRelocationCapacity;
+    private readonly outboundCapacity;
+    private readonly sealWaitTimeoutMs;
+    private readonly lane;
+    private readonly routes;
+    private readonly sealWaiters;
+    private readonly activeFrameWaiters;
+    private readonly relocations;
+    private readonly terminalRelocations;
+    constructor(terminalRelocationCapacity?: number, outboundCapacity?: number, sealWaitTimeoutMs?: number);
+    bind(context: TContext, actor: TActor, bindingToken: string, authorityFence?: ZLinkActorSessionAuthorityFence, sessionIdentity?: string): Promise<void>;
+    private bindCore;
+    replace(previous: ZLinkActorSessionRoute<TContext, TActor>, context: TContext, actor: TActor, bindingToken: string, authorityFence?: ZLinkActorSessionAuthorityFence, sessionIdentity?: string): Promise<void>;
+    private replaceCore;
+    replaceAndReleaseSeal(previous: ZLinkActorSessionRoute<TContext, TActor>, context: TContext, actor: TActor, bindingToken: string, sealId: string, authorityFence?: ZLinkActorSessionAuthorityFence, sessionIdentity?: string): Promise<void>;
+    private replaceAndReleaseSealCore;
+    find(actorId: string): Promise<TActor | undefined>;
+    private findCore;
+    route(actorId: string): Promise<ZLinkActorSessionRoute<TContext, TActor> | undefined>;
+    private routeCore;
+    capturePendingReplyClaim(actorId: string, actor: ZLinkActorSessionBindingActor, bindingToken: string): Promise<{
+        readonly context: TContext;
+    } | undefined>;
+    private capturePendingReplyClaimCore;
+    unbind(actorId: string, context: TContext, bindingToken: string): Promise<void>;
+    private unbindCore;
+    unbindActor(actorId: string): Promise<void>;
+    private unbindActorCore;
+    cleanup(context: TContext): Promise<void>;
+    private cleanupCore;
+    requireRoute(actorId: string): Promise<ZLinkActorSessionRoute<TContext, TActor>>;
+    private requireRouteCore;
+    requireCurrentToken(actorId: string, bindingToken: string): Promise<void>;
+    private requireCurrentTokenCore;
+    accept(actorId: string, bindingToken: string): Promise<void>;
+    private acceptCore;
+    /**
+     * 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.
+     */
+    acceptWhenReady(actorId: string, bindingToken: string, signal?: AbortSignal): Promise<void>;
+    private acceptWhenReadyCore;
+    beginAcceptedFrameWhenReady(actorId: string, bindingToken: string, signal?: AbortSignal): Promise<ZLinkActorSessionFrameAdmission>;
+    private beginAcceptedFrameCore;
+    beginAcceptedRequestFrameWhenReady(actorId: string, bindingToken: string, signal?: AbortSignal): Promise<ZLinkActorSessionRequestFrameAdmission>;
+    private beginAcceptedRequestFrameCore;
+    runAcceptedFrameWhenReady<TResult>(actorId: string, bindingToken: string, operation: () => Promise<TResult>, signal?: AbortSignal): Promise<TResult>;
+    seal(actorId: string, sealId: string, expected: ZLinkActorSessionRouteFence): Promise<void>;
+    private sealCore;
+    sealAndWait(actorId: string, sealId: string, expected: ZLinkActorSessionRouteFence, signal?: AbortSignal): Promise<void>;
+    sealRelocation(claim: ZLinkActorSessionRelocationClaim, expected: ZLinkActorSessionRouteFence, signal?: AbortSignal): Promise<void>;
+    private prepareRelocationSeal;
+    relocationSnapshot(actorId: string, sealId: string): Promise<ZLinkActorSessionRelocationSnapshot | undefined>;
+    private relocationSnapshotCore;
+    retainRelocationOutbound(actorId: string, operation: ZLinkActorSessionRetainedOutbound, sealId?: string): Promise<ServiceSessionBindingAdmissionResult>;
+    private retainRelocationOutboundCorePublic;
+    admitRelocationOutbound(claim: ServiceSessionBindingAdmissionClaim, operation: ZLinkActorSessionRetainedOutbound): Promise<ServiceSessionBindingAdmissionResult>;
+    private admitRelocationOutboundCore;
+    private retainRelocationOutboundCore;
+    discardRelocationOutbound(actorId: string, sealId: string, error: unknown): Promise<void>;
+    private discardRelocationOutboundCore;
+    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, action: 'commit' | 'abort', commitOwnerTransition: () => Promise<void>, acceptedProducerProof?: ZLinkActorSessionAcceptedProducerProof): Promise<void>;
+    private prepareRelocationApply;
+    private completeRelocationApply;
+    private failRelocationApply;
+    private currentProducerProof;
+    observeRelocationTerminal(actorId: string, sealId: string, applyFingerprint: string): Promise<void>;
+    private observeRelocationTerminalCore;
+    /**
+     * 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`).
+     */
+    clearRelocation(actorId: string, error: unknown): Promise<void>;
+    private clearRelocationCore;
+    /**
+     * 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).
+     */
+    private clearRouteRelocation;
+    abortSeal(actorId: string, sealId: string): Promise<boolean>;
+    private abortSealCore;
+    updateAuthorityFence(actorId: string, authorityFence: ZLinkActorSessionAuthorityFence): Promise<void>;
+    private updateAuthorityFenceCore;
+    validateSeal(actorId: string, sealId: string): Promise<boolean>;
+    private validateSealCore;
+    /** True while a relocation seal currently holds this actor's ingress. */
+    isSealed(actorId: string): Promise<boolean>;
+    private isSealedCore;
+    private waitForSealRelease;
+    private waitForSealReleaseCore;
+    private waitForActiveFrames;
+    private waitForActiveFramesCore;
+    private resolveActiveFrameWaiters;
+    private rejectActiveFrameWaiters;
+    private startOutboundDrain;
+    private reserveOutbound;
+    private settleOutbound;
+    private failOutbound;
+    private outboundAdmissionError;
+    private matchesCurrentProducerNode;
+    private rememberTerminalRelocation;
+    private deleteEmptyRelocationQueue;
+    private resolveSealWaiters;
+    private rejectSealWaiters;
+}
+export interface ZLinkActorSessionRouteFence {
+    readonly objectGeneration: bigint;
+    readonly bindingGeneration: bigint;
+}
+export {};