@zlink-systems/framework 0.10.0

package/dist/runtime/streams/protocol.js

@@ -0,0 +1,244 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLINK_STREAM_HEARTBEAT_PONG = exports.ZLINK_STREAM_HEARTBEAT_PING = exports.ZLinkStreamCloseReasonCode = exports.ZLinkStreamHeaderFlags = exports.ZLinkStreamMessageKind = exports.ZLinkStreamCodec = exports.utf8Encode = exports.utf8Decode = void 0;
+exports.streamCodecContentType = streamCodecContentType;
+exports.streamCodecForContentType = streamCodecForContentType;
+exports.resolvePacketName = resolvePacketName;
+exports.ensureSingleSubmit = ensureSingleSubmit;
+exports.encodeStreamFrame = encodeStreamFrame;
+exports.encodeStreamControlFrame = encodeStreamControlFrame;
+exports.encodeSessionClosingFrame = encodeSessionClosingFrame;
+exports.decodeStreamFrame = decodeStreamFrame;
+exports.tryDecodeStreamFrame = tryDecodeStreamFrame;
+exports.encodeStreamHeader = encodeStreamHeader;
+exports.decodeStreamHeader = decodeStreamHeader;
+exports.actorRequestDeadlineMetadata = actorRequestDeadlineMetadata;
+exports.decodeActorRequestDeadlineUnixMs = decodeActorRequestDeadlineUnixMs;
+exports.createStreamReplyHeader = createStreamReplyHeader;
+exports.messageToBytes = messageToBytes;
+exports.lz4Pickle = lz4Pickle;
+exports.lz4Unpickle = lz4Unpickle;
+const packet_name_1 = require("../messaging/packet-name");
+const stream_wire_1 = require("@zlink-systems/stream-wire");
+const submission_result_1 = require("../messaging/submission-result");
+var stream_wire_2 = require("@zlink-systems/stream-wire");
+Object.defineProperty(exports, "utf8Decode", { enumerable: true, get: function () { return stream_wire_2.utf8Decode; } });
+Object.defineProperty(exports, "utf8Encode", { enumerable: true, get: function () { return stream_wire_2.utf8Encode; } });
+const defaultMaxDecompressedPayloadSize = 64 * 1024;
+const actorRequestDeadlineMetadataKey = '$zlink.actor-request-deadline-unix-ms';
+//  Shared empty metadata for the dominant no-metadata frame; ReadonlyMap
+//  keeps every consumer from mutating it.
+const EMPTY_STREAM_METADATA = new Map();
+var ZLinkStreamCodec;
+(function (ZLinkStreamCodec) {
+    ZLinkStreamCodec[ZLinkStreamCodec["Raw"] = 0] = "Raw";
+    ZLinkStreamCodec[ZLinkStreamCodec["Json"] = 1] = "Json";
+    ZLinkStreamCodec[ZLinkStreamCodec["MessagePack"] = 2] = "MessagePack";
+    ZLinkStreamCodec[ZLinkStreamCodec["Protobuf"] = 3] = "Protobuf";
+})(ZLinkStreamCodec || (exports.ZLinkStreamCodec = ZLinkStreamCodec = {}));
+function streamCodecContentType(codec) {
+    switch (codec) {
+        case ZLinkStreamCodec.Json: return 'application/json';
+        case ZLinkStreamCodec.MessagePack: return 'application/x-msgpack';
+        case ZLinkStreamCodec.Protobuf: return 'application/x-protobuf';
+        case ZLinkStreamCodec.Raw: return 'application/octet-stream';
+    }
+    throw new TypeError(`Unsupported STREAM codec '${codec}'.`);
+}
+function streamCodecForContentType(contentType) {
+    switch (contentType) {
+        case 'application/json': return ZLinkStreamCodec.Json;
+        case 'application/x-msgpack': return ZLinkStreamCodec.MessagePack;
+        case 'application/x-protobuf': return ZLinkStreamCodec.Protobuf;
+        case 'application/octet-stream': return ZLinkStreamCodec.Raw;
+    }
+    throw new TypeError(`Unsupported STREAM content type '${contentType}'.`);
+}
+var ZLinkStreamMessageKind;
+(function (ZLinkStreamMessageKind) {
+    ZLinkStreamMessageKind[ZLinkStreamMessageKind["Send"] = 1] = "Send";
+    ZLinkStreamMessageKind[ZLinkStreamMessageKind["Request"] = 2] = "Request";
+    ZLinkStreamMessageKind[ZLinkStreamMessageKind["Response"] = 3] = "Response";
+    ZLinkStreamMessageKind[ZLinkStreamMessageKind["Error"] = 4] = "Error";
+    ZLinkStreamMessageKind[ZLinkStreamMessageKind["Control"] = 5] = "Control";
+})(ZLinkStreamMessageKind || (exports.ZLinkStreamMessageKind = ZLinkStreamMessageKind = {}));
+var ZLinkStreamHeaderFlags;
+(function (ZLinkStreamHeaderFlags) {
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["None"] = 0] = "None";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasRequestSeq"] = 1] = "HasRequestSeq";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasMetadata"] = 2] = "HasMetadata";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["PayloadCompressed"] = 4] = "PayloadCompressed";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasCorrelationId"] = 8] = "HasCorrelationId";
+    ZLinkStreamHeaderFlags[ZLinkStreamHeaderFlags["HasFlowId"] = 16] = "HasFlowId";
+})(ZLinkStreamHeaderFlags || (exports.ZLinkStreamHeaderFlags = ZLinkStreamHeaderFlags = {}));
+var ZLinkStreamCloseReasonCode;
+(function (ZLinkStreamCloseReasonCode) {
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["ClientClose"] = 1] = "ClientClose";
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["IdleTimeout"] = 2] = "IdleTimeout";
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["HeartbeatTimeout"] = 3] = "HeartbeatTimeout";
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["ServerDrain"] = 4] = "ServerDrain";
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["ProtocolError"] = 5] = "ProtocolError";
+    ZLinkStreamCloseReasonCode[ZLinkStreamCloseReasonCode["TransportError"] = 6] = "TransportError";
+})(ZLinkStreamCloseReasonCode || (exports.ZLinkStreamCloseReasonCode = ZLinkStreamCloseReasonCode = {}));
+exports.ZLINK_STREAM_HEARTBEAT_PING = '$zlink.heartbeat.ping';
+exports.ZLINK_STREAM_HEARTBEAT_PONG = '$zlink.heartbeat.pong';
+function resolvePacketName(message, explicitPacketName) {
+    const packetName = (0, packet_name_1.resolveFrameworkPacketName)(message, explicitPacketName, 'Stream');
+    if (packetName.trim().length === 0) {
+        throw new Error('Stream packet name must not be empty.');
+    }
+    return packetName;
+}
+function ensureSingleSubmit(executed) {
+    if (executed) {
+        (0, submission_result_1.throwAlreadySubmitted)('Stream send call');
+    }
+}
+function encodeStreamFrame(header, payload) {
+    return (0, stream_wire_1.encodeStreamWireFrame)(encodeStreamHeader(header), payload);
+}
+function encodeStreamControlFrame(name) {
+    return encodeStreamFrame({
+        kind: ZLinkStreamMessageKind.Control,
+        codec: ZLinkStreamCodec.Raw,
+        flags: ZLinkStreamHeaderFlags.None,
+        name,
+        metadata: EMPTY_STREAM_METADATA
+    }, new Uint8Array());
+}
+function encodeSessionClosingFrame(diagnostic = '', reason = ZLinkStreamCloseReasonCode.ServerDrain) {
+    const diagnosticBytes = (0, stream_wire_1.utf8Encode)(diagnostic);
+    if (diagnosticBytes.length > 512)
+        throw new Error('Session-closing diagnostic is too large.');
+    const payload = new Uint8Array(4 + diagnosticBytes.length);
+    payload[0] = 1;
+    payload[1] = reason;
+    payload[2] = diagnosticBytes.length >>> 8;
+    payload[3] = diagnosticBytes.length & 0xff;
+    payload.set(diagnosticBytes, 4);
+    return encodeStreamFrame({
+        kind: ZLinkStreamMessageKind.Control,
+        codec: ZLinkStreamCodec.Raw,
+        flags: ZLinkStreamHeaderFlags.None,
+        name: 'session-closing',
+        metadata: new Map()
+    }, payload);
+}
+function decodeStreamFrame(frame) {
+    return (0, stream_wire_1.decodeStreamWireFrame)(frame);
+}
+function tryDecodeStreamFrame(frame) {
+    return (0, stream_wire_1.tryDecodeStreamWireFrame)(frame);
+}
+function encodeStreamHeader(header) {
+    const hasRequestSeq = header.requestSeq !== undefined;
+    const hasMetadata = header.metadata.size > 0;
+    const hasCorrelation = header.correlationId !== undefined && header.correlationId.length > 0;
+    const hasFlow = header.flowId !== undefined || header.flowOrigin !== undefined;
+    if (header.kind === ZLinkStreamMessageKind.Control && (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+        throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
+    }
+    //  Explicit construction: this runs for every outbound frame, so avoid a
+    //  per-message spread of the whole header.
+    return (0, stream_wire_1.encodeStreamWireHeader)({
+        kind: header.kind,
+        codec: header.codec,
+        flags: header.flags,
+        requestSeq: header.requestSeq,
+        name: header.name,
+        metadata: header.metadata,
+        correlationId: header.correlationId,
+        flowId: header.flowId,
+        flowOrigin: encodeFlowOrigin(header.flowOrigin)
+    });
+}
+function decodeStreamHeader(header, flowEnabled = true) {
+    const decoded = (0, stream_wire_1.decodeStreamWireHeader)(header, undefined, flowEnabled);
+    const kind = decoded.kind;
+    const flags = decoded.flags;
+    const hasRequestSeq = (flags & ZLinkStreamHeaderFlags.HasRequestSeq) !== 0;
+    const hasMetadata = (flags & ZLinkStreamHeaderFlags.HasMetadata) !== 0;
+    const hasCorrelation = (flags & ZLinkStreamHeaderFlags.HasCorrelationId) !== 0;
+    const hasFlow = (flags & ZLinkStreamHeaderFlags.HasFlowId) !== 0;
+    if (kind === ZLinkStreamMessageKind.Control && (hasCorrelation || hasRequestSeq || hasMetadata || hasFlow)) {
+        throw new Error('Control packet must not contain a request sequence, metadata, correlation id, or flow id.');
+    }
+    const metadata = publicStreamMetadata(decoded.metadata);
+    return {
+        kind,
+        codec: decoded.codec,
+        flags: (metadata.size === 0
+            ? flags & ~ZLinkStreamHeaderFlags.HasMetadata
+            : flags) & (flowEnabled ? ~0 : ~ZLinkStreamHeaderFlags.HasFlowId),
+        requestSeq: decoded.requestSeq,
+        name: decoded.name,
+        metadata,
+        correlationId: decoded.correlationId,
+        flowId: decoded.flowId,
+        flowOrigin: decodeFlowOrigin(decoded.flowOrigin)
+    };
+}
+function actorRequestDeadlineMetadata(deadlineUnixMs) {
+    return deadlineUnixMs === undefined
+        ? EMPTY_STREAM_METADATA
+        : new Map([[actorRequestDeadlineMetadataKey, String(deadlineUnixMs)]]);
+}
+function decodeActorRequestDeadlineUnixMs(header) {
+    const value = (0, stream_wire_1.decodeStreamWireHeader)(header).metadata.get(actorRequestDeadlineMetadataKey);
+    if (value === undefined)
+        return undefined;
+    const deadline = Number(value);
+    return Number.isSafeInteger(deadline) && deadline > 0 ? deadline : undefined;
+}
+function publicStreamMetadata(metadata) {
+    if (!metadata.has(actorRequestDeadlineMetadataKey))
+        return metadata;
+    const visible = new Map(metadata);
+    visible.delete(actorRequestDeadlineMetadataKey);
+    return visible;
+}
+function createStreamReplyHeader(requestHeader, kind, codec, flags, metadata, includeFlow = true) {
+    if (requestHeader.requestSeq === undefined) {
+        throw new Error('Stream reply requires a request sequence.');
+    }
+    return {
+        kind,
+        codec,
+        flags,
+        requestSeq: requestHeader.requestSeq,
+        name: '',
+        metadata,
+        // correlation_id survives every diagnostics level; the flow pair is
+        // observation-only and is not copied into the reply when tracing is Off
+        // (spec 27 §4, §7).
+        correlationId: requestHeader.correlationId,
+        ...(includeFlow
+            ? { flowId: requestHeader.flowId, flowOrigin: requestHeader.flowOrigin }
+            : {})
+    };
+}
+function encodeFlowOrigin(origin) {
+    return origin === undefined ? undefined : { Inbound: 1, Timer: 2, Application: 3, Lifecycle: 4 }[origin];
+}
+function decodeFlowOrigin(origin) {
+    return origin === undefined ? undefined : { 1: 'Inbound', 2: 'Timer', 3: 'Application', 4: 'Lifecycle' }[origin];
+}
+function messageToBytes(message) {
+    const value = message;
+    if (value.data !== undefined) {
+        return value.data();
+    }
+    if (value.bytes !== undefined) {
+        return value.bytes;
+    }
+    if (value.toBytes !== undefined) {
+        return value.toBytes();
+    }
+    throw new Error('Stream payload cannot be copied for relay.');
+}
+function lz4Pickle(payload) {
+    return (0, stream_wire_1.lz4PickleUncompressed)(payload);
+}
+function lz4Unpickle(payload, maxDecompressedSize = defaultMaxDecompressedPayloadSize) {
+    return (0, stream_wire_1.lz4UnpicklePayload)(payload, maxDecompressedSize);
+}

package/dist/runtime/streams/session-actor-coordinator.d.ts

@@ -0,0 +1,56 @@
+import { ActorRef, ZLinkActor } from '../../contracts';
+import type { ZLinkRuntimeMetrics } from '../diagnostics';
+import { ZLinkActorSessionBindingRegistry, type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
+import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+export interface ZLinkSessionActorCoordinatorOptions {
+    readonly actorBindTimeoutMs?: number;
+    readonly actorRefResolver?: (actor: ZLinkActor) => ActorRef;
+    readonly actorAuthorityFenceResolver?: (actorId: string, signal?: AbortSignal) => Promise<ZLinkActorSessionAuthorityFence | undefined>;
+    readonly nativeActorNodeProvider?: () => {
+        status(): {
+            readonly routingId: unknown;
+        };
+    } | undefined;
+    readonly nativeActorMeshNameProvider?: () => string | undefined;
+    readonly confirmRemoteActorSessionBinding?: (actor: ActorRef, sessionRid: ActorRef['nodeRid'], signal?: AbortSignal, options?: {
+        readonly waitForAcknowledgement?: boolean;
+    }) => Promise<void>;
+    readonly errorSink?: () => {
+        reportRuntimeTaskException(taskName: string, error: unknown): void;
+    } | undefined;
+    readonly metrics?: ZLinkRuntimeMetrics;
+}
+export declare class ZLinkSessionActorCoordinator {
+    private readonly routes;
+    private readonly sessionActorRuntime;
+    private readonly options;
+    private readonly lifecycle;
+    constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, sessionActorRuntime: ConstructorParameters<typeof DefaultZLinkSessionActor>[0], options?: ZLinkSessionActorCoordinatorOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
+    bind(context: DefaultZLinkSessionContext, actorOrRef: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
+    private replaceBinding;
+    private replaceBindingCore;
+    private resolveAuthorityFence;
+    bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
+    rebindActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    refreshActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: {
+        readonly confirmRemoteSessionBinding?: boolean | 'send';
+        readonly releaseSeal?: {
+            readonly sealId: string;
+        };
+    }): Promise<void>;
+    retireRemoteBinding(actorRef: ActorRef, sessionRid: ActorRef['nodeRid'], bindingGeneration: bigint, signal?: AbortSignal): Promise<boolean>;
+    authorityFence(actorId: string): Promise<{
+        readonly authorityOwnerGeneration: bigint;
+        readonly ownerLeaseGeneration: bigint;
+    } | undefined>;
+    sessionRouteFence(actorId: string): Promise<{
+        readonly actor: ActorRef;
+        readonly sessionRid: ActorRef['nodeRid'];
+        readonly bindingGeneration: bigint;
+    } | undefined>;
+    private resolveActorRef;
+    private bindNativeActor;
+    private actorBindingRoutingId;
+}

package/dist/runtime/streams/session-actor-coordinator.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkSessionActorCoordinator = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const abort_1 = require("../abort");
+const routing_id_1 = require("../routing-id");
+const actor_session_lifecycle_coordinator_1 = require("./actor-session-lifecycle-coordinator");
+const managed_stream_1 = require("./managed-stream");
+const session_context_1 = require("./session-context");
+class ZLinkSessionActorCoordinator {
+    routes;
+    sessionActorRuntime;
+    options;
+    lifecycle;
+    constructor(routes, sessionActorRuntime, options = {}, lifecycle = new actor_session_lifecycle_coordinator_1.ZLinkActorSessionLifecycleCoordinator()) {
+        this.routes = routes;
+        this.sessionActorRuntime = sessionActorRuntime;
+        this.options = options;
+        this.lifecycle = lifecycle;
+    }
+    async bind(context, actorOrRef, signal) {
+        const actorRef = isActorRefLike(actorOrRef)
+            ? normalizeActorRef(actorOrRef, this.options.nativeActorMeshNameProvider?.())
+            : this.resolveActorRef(actorOrRef);
+        return await this.lifecycle.run(actorRef.actorId, async () => this.replaceBinding(context, actorRef, signal));
+    }
+    async replaceBinding(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
+        return await this.replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding, releaseSeal);
+    }
+    async replaceBindingCore(context, actorRef, signal, confirmRemoteSessionBinding = true, releaseSeal) {
+        (0, abort_1.throwIfAborted)(signal);
+        if (actorRef.actorId.trim().length === 0) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, 'Actor id must not be empty.');
+        }
+        if (context.routingId === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, 'Actor session binding requires a stream routing id.');
+        }
+        const previous = await this.routes.route(actorRef.actorId);
+        const sameIncarnation = previous !== undefined
+            && previous.context === context
+            && previous.actor.ref.actorId === actorRef.actorId
+            && BigInt(previous.actor.ref.objectGeneration) === BigInt(actorRef.objectGeneration);
+        const samePhysicalBinding = sameIncarnation && sameActorRef(previous.actor.ref, actorRef);
+        const reuseActor = sameIncarnation ? previous.actor : undefined;
+        if (reuseActor !== undefined) {
+            // A repeated bind from the same physical session is idempotent. A route
+            // refresh for the same actor incarnation still submits the native bind,
+            // then keeps this session's actor handle and lifecycle token stable.
+            if (samePhysicalBinding) {
+                return reuseActor;
+            }
+        }
+        const authorityFence = await this.resolveAuthorityFence(actorRef, signal);
+        await this.bindNativeActor(context, actorRef, authorityFence, signal);
+        const bindingToken = reuseActor?.bindingToken ?? createBindingToken();
+        const boundActorRef = withBindingGeneration(actorRef, context.stream instanceof managed_stream_1.ZLinkManagedStream
+            ? context.stream.actorBindingGeneration(actorRef.actorId)
+            : undefined, previous?.actor.ref);
+        const sessionActor = reuseActor
+            ?? new session_context_1.DefaultZLinkSessionActor(this.sessionActorRuntime, boundActorRef, bindingToken);
+        const sessionIdentity = String(this.actorBindingRoutingId(context));
+        sessionActor.updateRef(boundActorRef);
+        if (previous === undefined) {
+            if (releaseSeal !== undefined) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorRef.actorId}' route switch has no Session binding to release.`, true);
+            }
+            await this.routes.bind(context, sessionActor, bindingToken, authorityFence, sessionIdentity);
+        }
+        else if (releaseSeal !== undefined) {
+            await this.routes.replaceAndReleaseSeal(previous, context, sessionActor, bindingToken, releaseSeal.sealId, authorityFence, sessionIdentity);
+        }
+        else {
+            await this.routes.replace(previous, context, sessionActor, bindingToken, authorityFence, sessionIdentity);
+        }
+        if (confirmRemoteSessionBinding !== false && this.options.confirmRemoteActorSessionBinding !== undefined) {
+            const waitForAcknowledgement = previous === undefined
+                && confirmRemoteSessionBinding !== 'send';
+            const confirmation = this.options.confirmRemoteActorSessionBinding(boundActorRef, this.actorBindingRoutingId(context), undefined, { waitForAcknowledgement });
+            const reportFailure = (error) => {
+                // A fire-and-forget route update retains the already-current binding;
+                // its failure is bounded diagnostics rather than a rollback. The
+                // relay retries independently and reports the typed failure through
+                // the runtime error sink instead of silently discarding it.
+                this.options.errorSink?.()?.reportRuntimeTaskException('remote session binding confirmation', error);
+            };
+            if (waitForAcknowledgement) {
+                try {
+                    await confirmation;
+                }
+                catch (error) {
+                    // The first bind has no previously accepted route. Its public
+                    // terminal must fail when the Actor owner rejects or times out the
+                    // admission, so remove only this provisional local route and retain
+                    // the relay's typed failure for the caller.
+                    try {
+                        if (context.stream instanceof managed_stream_1.ZLinkManagedStream) {
+                            await context.stream.unbindActor(actorRef.actorId, this.options.actorBindTimeoutMs ?? 2000);
+                        }
+                    }
+                    catch (cleanupError) {
+                        // Native cleanup cannot replace the owner rejection observed by
+                        // the public bind. It is separately observable for diagnosis.
+                        reportFailure(cleanupError);
+                    }
+                    finally {
+                        await this.routes.unbind(actorRef.actorId, context, bindingToken);
+                    }
+                    throw error;
+                }
+            }
+            else {
+                // Replacement does not wait for a remote acknowledgement, but its
+                // one-way bind must reach transport submission before application
+                // relay can use the new Session route. Otherwise the first packet on
+                // a reconnected Session can overtake the binding command.
+                try {
+                    await confirmation;
+                }
+                catch (error) {
+                    reportFailure(error);
+                }
+            }
+        }
+        return sessionActor;
+    }
+    async resolveAuthorityFence(actorRef, signal) {
+        const internal = actorRef;
+        if (internal.ownershipGeneration !== undefined
+            && internal.ownerLeaseGeneration !== undefined) {
+            const resolved = internal.ownerNodeGeneration === undefined
+                ? await this.options.actorAuthorityFenceResolver?.(actorRef.actorId, signal)
+                : undefined;
+            return {
+                authorityOwnerGeneration: internal.ownershipGeneration,
+                ownerLeaseGeneration: internal.ownerLeaseGeneration,
+                ...((internal.ownerNodeGeneration ?? resolved?.ownerNodeGeneration) === undefined
+                    ? {}
+                    : { ownerNodeGeneration: internal.ownerNodeGeneration ?? resolved.ownerNodeGeneration }),
+                ...(resolved?.ownerId === undefined ? {} : { ownerId: resolved.ownerId }),
+                ...(resolved?.authorityStoreVersion === undefined
+                    ? {}
+                    : { authorityStoreVersion: resolved.authorityStoreVersion }),
+                ...(resolved?.actorType === undefined ? {} : { actorType: resolved.actorType })
+            };
+        }
+        return await this.options.actorAuthorityFenceResolver?.(actorRef.actorId, signal);
+    }
+    async bindOrGet(context, actorRef, signal) {
+        const normalizedActorRef = normalizeActorRef(actorRef, this.options.nativeActorMeshNameProvider?.());
+        return await this.lifecycle.run(normalizedActorRef.actorId, async () => {
+            (0, abort_1.throwIfAborted)(signal);
+            const existing = await this.routes.find(normalizedActorRef.actorId);
+            if (existing !== undefined && sameActorRef(existing.ref, normalizedActorRef)) {
+                if (context.findBoundActor(normalizedActorRef.actorId) === existing) {
+                    return existing;
+                }
+                return await this.replaceBinding(context, normalizedActorRef, signal);
+            }
+            if (existing !== undefined) {
+                try {
+                    return await this.replaceBinding(context, normalizedActorRef, signal);
+                }
+                catch (error) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' bound session ref is stale and could not be rebound.`, true, error);
+                }
+            }
+            return await this.replaceBinding(context, normalizedActorRef, signal);
+        });
+    }
+    async rebindActor(actorRef, signal) {
+        const normalizedActorRef = normalizeActorRef(actorRef, this.options.nativeActorMeshNameProvider?.());
+        await this.lifecycle.run(normalizedActorRef.actorId, async () => {
+            (0, abort_1.throwIfAborted)(signal);
+            const route = await this.routes.route(normalizedActorRef.actorId);
+            if (route === undefined || sameActorRef(route.actor.ref, normalizedActorRef))
+                return;
+            requireSameIncarnation(route.actor.ref, normalizedActorRef);
+            await this.replaceBinding(route.context, normalizedActorRef, signal);
+        });
+    }
+    async refreshActor(actorRef, signal) {
+        const normalizedActorRef = normalizeActorRef(actorRef, this.options.nativeActorMeshNameProvider?.());
+        await this.lifecycle.run(normalizedActorRef.actorId, async () => {
+            (0, abort_1.throwIfAborted)(signal);
+            const route = await this.routes.route(normalizedActorRef.actorId);
+            if (route === undefined)
+                return;
+            requireSameIncarnation(route.actor.ref, normalizedActorRef);
+            await this.replaceBinding(route.context, normalizedActorRef, signal);
+        });
+    }
+    async commitActorRoute(actorRef, signal, options = {}) {
+        const normalizedActorRef = normalizeActorRef(actorRef, this.options.nativeActorMeshNameProvider?.());
+        await this.lifecycle.run(normalizedActorRef.actorId, async () => {
+            (0, abort_1.throwIfAborted)(signal);
+            const route = await this.routes.route(normalizedActorRef.actorId);
+            if (route === undefined)
+                return;
+            requireSameIncarnation(route.actor.ref, normalizedActorRef);
+            if ((0, routing_id_1.routingIdsEqual)(route.actor.ref.nodeRid, normalizedActorRef.nodeRid)) {
+                const authorityFence = await this.resolveAuthorityFence(normalizedActorRef, signal);
+                if (options.releaseSeal !== undefined
+                    && !await this.routes.validateSeal(normalizedActorRef.actorId, options.releaseSeal.sealId)) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch did not match its relocation seal.`, true);
+                }
+                route.actor.updateRef(normalizedActorRef);
+                if (authorityFence !== undefined) {
+                    await this.routes.updateAuthorityFence(normalizedActorRef.actorId, authorityFence);
+                }
+                if (options.releaseSeal !== undefined
+                    && !await this.routes.abortSeal(normalizedActorRef.actorId, options.releaseSeal.sealId)) {
+                    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${normalizedActorRef.actorId}' route switch lost its relocation seal.`, true);
+                }
+                return;
+            }
+            await this.replaceBinding(route.context, normalizedActorRef, signal, options.confirmRemoteSessionBinding, options.releaseSeal);
+        });
+    }
+    async retireRemoteBinding(actorRef, sessionRid, bindingGeneration, signal) {
+        return await this.lifecycle.run(actorRef.actorId, async () => {
+            (0, abort_1.throwIfAborted)(signal);
+            const route = await this.routes.route(actorRef.actorId);
+            if (route === undefined
+                || !sameActorRef(route.actor.ref, actorRef)
+                || !(0, routing_id_1.routingIdsEqual)(route.sessionIdentity, sessionRid)
+                || bindingGenerationOf(route.actor.ref) !== bindingGeneration) {
+                return false;
+            }
+            // A late legacy tombstone may remove only the still-current exact route.
+            // A replacement route has a different token or ActorRef, so this path
+            // cannot roll it back or wait on the retired session owner.
+            await this.routes.unbind(actorRef.actorId, route.context, route.bindingToken);
+            return true;
+        });
+    }
+    async authorityFence(actorId) {
+        return (await this.routes.route(actorId))?.authorityFence;
+    }
+    async sessionRouteFence(actorId) {
+        const route = await this.routes.route(actorId);
+        const sessionRid = route?.sessionIdentity;
+        const actor = route?.actor.ref;
+        if (route === undefined
+            || sessionRid === undefined
+            || actor?.bindingGeneration === undefined) {
+            return undefined;
+        }
+        return {
+            actor,
+            sessionRid,
+            bindingGeneration: actor.bindingGeneration
+        };
+    }
+    resolveActorRef(actor) {
+        if (this.options.actorRefResolver !== undefined) {
+            return this.options.actorRefResolver(actor);
+        }
+        const state = actor.context;
+        if (state.actorRef !== undefined) {
+            return state.actorRef;
+        }
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actor.context.actorId}' does not have a concrete actor ref.`);
+    }
+    async bindNativeActor(context, actorRef, authorityFence, signal) {
+        if (!(context.stream instanceof managed_stream_1.ZLinkManagedStream)) {
+            return;
+        }
+        try {
+            await context.stream.bindActor(actorRef, this.options.actorBindTimeoutMs ?? 2000, signal, context.actorBindingReplacedHandler, authorityFence);
+        }
+        catch (error) {
+            if (error instanceof contracts_1.ZLinkFrameworkException) {
+                throw error;
+            }
+            throw new Error(`Actor '${actorRef.actorId}' native session bind failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+    }
+    actorBindingRoutingId(context) {
+        return context.stream instanceof managed_stream_1.ZLinkManagedStream
+            ? context.stream.actorBindingRoutingId
+            : context.routingId;
+    }
+}
+exports.ZLinkSessionActorCoordinator = ZLinkSessionActorCoordinator;
+function withBindingGeneration(actorRef, nativeBindingGeneration, previousRef) {
+    const input = actorRef;
+    const previous = previousRef;
+    const bindingGeneration = nativeBindingGeneration
+        ?? input.bindingGeneration
+        ?? previous?.bindingGeneration;
+    if (bindingGeneration === undefined) {
+        return actorRef;
+    }
+    const result = { ...actorRef, bindingGeneration };
+    preserveNormalizedActorRefField(result, actorRef, 'objectGeneration');
+    preserveNormalizedActorRefField(result, actorRef, 'meshName');
+    preserveInternalActorRefField(result, actorRef, 'ownershipGeneration');
+    preserveInternalActorRefField(result, actorRef, 'ownerLeaseGeneration');
+    return result;
+}
+function bindingGenerationOf(actorRef) {
+    return actorRef.bindingGeneration;
+}
+function preserveNormalizedActorRefField(target, source, field) {
+    if (Object.prototype.propertyIsEnumerable.call(source, field)) {
+        return;
+    }
+    Object.defineProperty(target, field, {
+        configurable: false,
+        enumerable: false,
+        value: source[field]
+    });
+}
+function preserveInternalActorRefField(target, source, field) {
+    const value = source[field];
+    if (value === undefined)
+        return;
+    Object.defineProperty(target, field, {
+        configurable: false,
+        enumerable: false,
+        value
+    });
+}
+function isActorRefLike(value) {
+    return (typeof value === 'object'
+        && 'nodeRid' in value
+        && 'actorId' in value
+        && ('objectGeneration' in value || 'generation' in value));
+}
+function normalizeActorRef(value, defaultMeshName) {
+    const objectGeneration = value.objectGeneration ?? value.generation;
+    if (objectGeneration === undefined) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${value.actorId}' does not have an object generation.`);
+    }
+    if (value.objectGeneration !== undefined && value.meshName !== undefined) {
+        return value;
+    }
+    const normalized = { ...value };
+    if (value.objectGeneration === undefined) {
+        Object.defineProperty(normalized, 'objectGeneration', {
+            configurable: false,
+            enumerable: false,
+            value: BigInt(objectGeneration)
+        });
+    }
+    if (value.meshName === undefined) {
+        Object.defineProperty(normalized, 'meshName', {
+            configurable: false,
+            enumerable: false,
+            value: defaultMeshName ?? ''
+        });
+    }
+    return normalized;
+}
+function createBindingToken() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function sameActorRef(left, right) {
+    return (0, routing_id_1.routingIdsEqual)(left.nodeRid, right.nodeRid)
+        && left.actorId === right.actorId
+        && BigInt(left.objectGeneration) === BigInt(right.objectGeneration);
+}
+function requireSameIncarnation(current, updated) {
+    if (current.actorId === updated.actorId
+        && BigInt(current.objectGeneration) === BigInt(updated.objectGeneration)) {
+        return;
+    }
+    throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorLocationStale, `Actor '${updated.actorId}' route update cannot replace object generation `
+        + `${String(current.objectGeneration)} with ${String(updated.objectGeneration)}.`, true);
+}