@zlink-systems/framework 0.10.0

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

@@ -0,0 +1,20 @@
+import type { ActorRef } from '../../contracts';
+import type { ServiceSessionBindingAdmissionClaim, ServiceSessionBindingAdmissionResult } from '../foundation/service-session-binding-ingress-port';
+import type { ZLinkActorSessionAuthorityFence, ZLinkActorSessionAcceptedProducerProof, ZLinkActorSessionRelocationClaim, ZLinkActorSessionRelocationSnapshot, ZLinkActorSessionRetainedOutbound, ZLinkActorSessionRouteFence } from './actor-session-binding-registry';
+export interface ZLinkActorSessionBindingRuntimeOwner {
+    sealRelocation(claim: ZLinkActorSessionRelocationClaim, expected: ZLinkActorSessionRouteFence, signal?: AbortSignal): Promise<void>;
+    relocationSnapshot(actorId: string, sealId: string): Promise<ZLinkActorSessionRelocationSnapshot | undefined>;
+    retainRelocationOutbound(actorId: string, operation: ZLinkActorSessionRetainedOutbound, sealId?: string): Promise<ServiceSessionBindingAdmissionResult>;
+    admitRelocationOutbound(claim: ServiceSessionBindingAdmissionClaim, operation: ZLinkActorSessionRetainedOutbound): Promise<ServiceSessionBindingAdmissionResult>;
+    discardRelocationOutbound(actorId: string, sealId: string, error: unknown): Promise<void>;
+    applyRelocation(actorId: string, sealId: string, applyFingerprint: string, action: 'commit' | 'abort', commitOwnerTransition: () => Promise<void>, acceptedProducerProof?: ZLinkActorSessionAcceptedProducerProof): Promise<void>;
+    observeRelocationTerminal(actorId: string, sealId: string, applyFingerprint: string): Promise<void>;
+    clearRelocation(actorId: string, error: unknown): Promise<void>;
+    committedRoute(actorId: string): Promise<{
+        readonly actor: ActorRef;
+        readonly authorityFence?: ZLinkActorSessionAuthorityFence;
+    } | undefined>;
+}
+export declare function registerActorSessionBindingRuntimeOwner(runtime: object, owner: ZLinkActorSessionBindingRuntimeOwner): void;
+export declare function actorSessionBindingRuntimeOwner(runtime: object): ZLinkActorSessionBindingRuntimeOwner;
+export declare function actorSessionBindingRuntimeOwnerIfRegistered(runtime: object): ZLinkActorSessionBindingRuntimeOwner | undefined;

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

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerActorSessionBindingRuntimeOwner = registerActorSessionBindingRuntimeOwner;
+exports.actorSessionBindingRuntimeOwner = actorSessionBindingRuntimeOwner;
+exports.actorSessionBindingRuntimeOwnerIfRegistered = actorSessionBindingRuntimeOwnerIfRegistered;
+const owners = new WeakMap();
+function registerActorSessionBindingRuntimeOwner(runtime, owner) {
+    owners.set(runtime, owner);
+}
+function actorSessionBindingRuntimeOwner(runtime) {
+    const owner = owners.get(runtime);
+    if (owner === undefined) {
+        throw new Error('Stream binding runtime does not have a Session binding aggregate owner.');
+    }
+    return owner;
+}
+function actorSessionBindingRuntimeOwnerIfRegistered(runtime) {
+    return owners.get(runtime);
+}

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

@@ -0,0 +1,4 @@
+export declare class ZLinkActorSessionLifecycleCoordinator {
+    private readonly tails;
+    run<T>(actorId: string, operation: () => Promise<T>): Promise<T>;
+}

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

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkActorSessionLifecycleCoordinator = void 0;
+class ZLinkActorSessionLifecycleCoordinator {
+    tails = new Map();
+    async run(actorId, operation) {
+        const previous = this.tails.get(actorId) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => { release = resolve; });
+        const tail = previous.catch(() => undefined).then(() => current);
+        this.tails.set(actorId, tail);
+        await previous.catch(() => undefined);
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.tails.get(actorId) === tail) {
+                this.tails.delete(actorId);
+            }
+        }
+    }
+}
+exports.ZLinkActorSessionLifecycleCoordinator = ZLinkActorSessionLifecycleCoordinator;

package/dist/runtime/streams/bound-actor-relay-sender.d.ts

@@ -0,0 +1,29 @@
+import type { ZLinkMessage, ZLinkMessageSerializer, ZLinkSessionActor } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { Message } from '../../contracts/Common/Message';
+import { type ZLinkStreamFrameHeader } from './protocol';
+import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
+import { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
+import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+export interface ZLinkBoundActorRelaySenderOptions {
+    readonly actorBindTimeoutMs?: number;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal) => Promise<boolean>;
+    readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
+}
+export declare class ZLinkBoundActorRelaySender {
+    private readonly routes;
+    private readonly frameMessages;
+    private readonly options;
+    private readonly lifecycle;
+    constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, frameMessages: ZLinkStreamFrameMessageFactory, options?: ZLinkBoundActorRelaySenderOptions, lifecycle?: ZLinkActorSessionLifecycleCoordinator);
+    relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, signal?: AbortSignal, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
+    private relayAcceptedFrame;
+    private currentHeader;
+    private requireDispatchHeader;
+    private relayInsideLifecycle;
+    notifyDisconnected(actor: DefaultZLinkSessionActor, signal?: AbortSignal): Promise<void>;
+    private notifyDisconnectedCore;
+    notifyPhysicalDisconnect(context: DefaultZLinkSessionContext): Promise<void>;
+}

package/dist/runtime/streams/bound-actor-relay-sender.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkBoundActorRelaySender = void 0;
+const submission_result_1 = require("../messaging/submission-result");
+const payload_codec_1 = require("../messaging/payload-codec");
+const protocol_1 = require("./protocol");
+const abort_1 = require("../abort");
+const execution_1 = require("../execution");
+const actor_session_lifecycle_coordinator_1 = require("./actor-session-lifecycle-coordinator");
+const managed_stream_1 = require("./managed-stream");
+class ZLinkBoundActorRelaySender {
+    routes;
+    frameMessages;
+    options;
+    lifecycle;
+    constructor(routes, frameMessages, options = {}, lifecycle = new actor_session_lifecycle_coordinator_1.ZLinkActorSessionLifecycleCoordinator()) {
+        this.routes = routes;
+        this.frameMessages = frameMessages;
+        this.options = options;
+        this.lifecycle = lifecycle;
+    }
+    async relay(actor, payload, signal, dispatchHeader) {
+        const header = dispatchHeader === undefined
+            ? await this.currentHeader(actor)
+            : await this.requireDispatchHeader(actor, dispatchHeader);
+        if (header.kind === protocol_1.ZLinkStreamMessageKind.Request
+            && header.requestSeq !== undefined) {
+            const operation = async () => {
+                const admission = await this.routes.beginAcceptedRequestFrameWhenReady(actor.actorId, actor.bindingToken, signal);
+                try {
+                    return await this.relayAcceptedFrame(actor, payload, signal, header, admission);
+                }
+                finally {
+                    await admission.complete();
+                }
+            };
+            if (await this.routes.isSealed(actor.actorId) && (0, execution_1.captureZLinkExecutionTurn)() !== undefined) {
+                void operation().catch(() => undefined);
+                return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+            }
+            return await operation();
+        }
+        if (await this.routes.isSealed(actor.actorId) && (0, execution_1.captureZLinkExecutionTurn)() !== undefined) {
+            //  Spec 32:62 — a Send completes once the source outbound queue
+            //  accepts it; spec 05 — infrastructure send progress must not depend
+            //  on the application turn. When the CALLER IS an application turn
+            //  (a lifecycle callback pushing to a bound actor), awaiting the seal
+            //  release here deadlocks: the relocation seal waits for that very
+            //  callback to finish (onJoinedActor -> push -> seal ->
+            //  onJoinedActor). Accept the frame now and deliver it after the
+            //  seal releases, in per-actor order through the lifecycle lane; the
+            //  bounded seal wait converts a stuck seal into a typed failure.
+            //  Non-turn callers (stream ingress relays) keep the waiting
+            //  semantics so a held frame across a failed rebind still
+            //  terminalizes to the caller.
+            void this.routes.runAcceptedFrameWhenReady(actor.actorId, actor.bindingToken, () => this.relayAcceptedFrame(actor, payload, signal), signal).catch(() => undefined);
+            return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+        }
+        return this.routes.runAcceptedFrameWhenReady(actor.actorId, actor.bindingToken, () => this.relayAcceptedFrame(actor, payload, signal), signal);
+    }
+    async relayAcceptedFrame(actor, payload, signal, header, requestAdmission) {
+        const activeHeader = header ?? await this.currentHeader(actor);
+        const started = await this.lifecycle.run(actor.actorId, async () => {
+            const completion = this.relayInsideLifecycle(actor, payload, signal, activeHeader, requestAdmission);
+            if (activeHeader.kind === protocol_1.ZLinkStreamMessageKind.Request
+                && activeHeader.requestSeq !== undefined) {
+                // A routed REQUEST only needs this lane while its ordered submission
+                // is started. Its admission acknowledgement can depend on relocation
+                // route publication, and command 44 uses the same lane. Keeping the
+                // lane until that acknowledgement arrives creates:
+                // REQUEST -> lane -> command 44 -> seal -> active REQUEST.
+                // The request admission remains observable outside the lane, so
+                // command 42 can capture its Session frame while the one original
+                // submission continues to its detached terminal.
+                return { kind: 'completion', completion };
+            }
+            return { kind: 'result', result: await completion };
+        });
+        return started.kind === 'result' ? started.result : await started.completion;
+    }
+    async currentHeader(actor) {
+        await this.routes.requireCurrentToken(actor.actorId, actor.bindingToken);
+        const header = (await this.routes.requireRoute(actor.actorId)).context.dispatchHeader;
+        if (header === undefined) {
+            throw new Error('Session actor relay requires an active stream dispatch.');
+        }
+        return header;
+    }
+    async requireDispatchHeader(actor, header) {
+        await this.routes.requireCurrentToken(actor.actorId, actor.bindingToken);
+        if ((await this.routes.requireRoute(actor.actorId)).context.dispatchHeader !== header) {
+            throw new Error('Session actor relay dispatch is not active for this bound actor.');
+        }
+        return header;
+    }
+    async relayInsideLifecycle(actor, payload, signal, currentHeader, requestAdmission) {
+        const header = currentHeader ?? await this.currentHeader(actor);
+        const held = requestAdmission?.beginSubmission(signal);
+        if (held !== undefined)
+            await held;
+        (0, abort_1.throwIfAborted)(signal);
+        const payloadMessage = (0, payload_codec_1.encodeFrameworkPayloadMessage)(payload, this.options.messageSerializers);
+        try {
+            if (this.options.relay !== undefined) {
+                const handled = await this.options.relay(actor, header, payloadMessage, signal);
+                if (handled) {
+                    return { status: submission_result_1.ZLinkSubmitStatus.Submitted };
+                }
+            }
+            const route = await this.routes.requireRoute(actor.actorId);
+            if (!(route.context.stream instanceof managed_stream_1.ZLinkManagedStream)) {
+                return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+            }
+            const headerMessage = this.frameMessages.createBinaryMessage((0, protocol_1.encodeStreamHeader)(header));
+            const framePayloadMessage = this.frameMessages.createBinaryMessage((0, protocol_1.messageToBytes)(payloadMessage));
+            try {
+                return await route.context.stream.submitBoundActor(actor.actorId, [headerMessage, framePayloadMessage], signal);
+            }
+            finally {
+                headerMessage.close();
+                framePayloadMessage.close();
+            }
+        }
+        finally {
+            payloadMessage.close();
+        }
+    }
+    async notifyDisconnected(actor, signal) {
+        await this.notifyDisconnectedCore(actor, true, signal);
+    }
+    async notifyDisconnectedCore(actor, unbindNative, signal) {
+        const detached = await this.lifecycle.run(actor.actorId, async () => {
+            await this.routes.requireCurrentToken(actor.actorId, actor.bindingToken);
+            const route = await this.routes.requireRoute(actor.actorId);
+            await this.routes.unbind(actor.actorId, route.context, actor.bindingToken);
+            return route;
+        });
+        if (unbindNative
+            && detached.bindingToken === actor.bindingToken
+            && detached.context.stream instanceof managed_stream_1.ZLinkManagedStream) {
+            await detached.context.stream.unbindActor(actor.actorId, this.options.actorBindTimeoutMs ?? 2000, signal);
+        }
+        await this.options.notifyDisconnected?.(actor, signal);
+    }
+    async notifyPhysicalDisconnect(context) {
+        const snapshot = [...context.boundActors];
+        const timeoutMs = this.options.actorBindTimeoutMs ?? 2000;
+        await Promise.allSettled(snapshot.map(async (actor) => {
+            const detached = await this.lifecycle.run(actor.actorId, async () => {
+                const route = await this.routes.route(actor.actorId);
+                if (route === undefined
+                    || route.context !== context
+                    || route.actor !== actor
+                    || route.bindingToken !== actor.bindingToken) {
+                    return false;
+                }
+                // The transport is already closed, so remove its exact route before
+                // invoking application lifecycle code. A reconnect can then install
+                // a successor while this best-effort notification is in flight.
+                await this.routes.unbind(actor.actorId, context, actor.bindingToken);
+                return true;
+            });
+            if (!detached)
+                return;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeoutMs);
+            try {
+                await Promise.race([
+                    this.options.notifyDisconnected?.(actor, controller.signal) ?? Promise.resolve(),
+                    new Promise((_, reject) => {
+                        controller.signal.addEventListener('abort', () => reject(new Error(`Actor '${actor.actorId}' disconnect notification exceeded ${timeoutMs} ms.`)), { once: true });
+                    })
+                ]);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }));
+    }
+}
+exports.ZLinkBoundActorRelaySender = ZLinkBoundActorRelaySender;

package/dist/runtime/streams/bound-session-response-target.d.ts

@@ -0,0 +1,25 @@
+import type { Message } from '../../contracts/Common/Message';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+export interface ZLinkBoundSessionResponseTarget {
+    sendResponse(packetName: string, requestSeq: bigint, message: unknown, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+    sendError(packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+}
+export interface ZLinkBoundSessionResponseContext {
+    readonly stream: {
+        submitRaw(payload: Message): Promise<ZLinkSubmitResult>;
+    };
+}
+export declare class DefaultZLinkBoundSessionResponseTarget implements ZLinkBoundSessionResponseTarget {
+    private readonly frameMessages;
+    private readonly context;
+    private readonly actorId;
+    constructor(frameMessages: ZLinkStreamFrameMessageFactory, context: ZLinkBoundSessionResponseContext, actorId: string);
+    sendResponse(packetName: string, requestSeq: bigint, message: unknown, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+    sendError(packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+    private send;
+}
+export declare function boundSessionErrorPayload(error: unknown): {
+    readonly code: string;
+    readonly message: string;
+};

package/dist/runtime/streams/bound-session-response-target.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DefaultZLinkBoundSessionResponseTarget = void 0;
+exports.boundSessionErrorPayload = boundSessionErrorPayload;
+const submission_result_1 = require("../messaging/submission-result");
+const protocol_1 = require("./protocol");
+class DefaultZLinkBoundSessionResponseTarget {
+    frameMessages;
+    context;
+    actorId;
+    constructor(frameMessages, context, actorId) {
+        this.frameMessages = frameMessages;
+        this.context = context;
+        this.actorId = actorId;
+    }
+    sendResponse(packetName, requestSeq, message, metadata) {
+        return this.send(protocol_1.ZLinkStreamMessageKind.Response, packetName, requestSeq, message, metadata, 'response');
+    }
+    sendError(packetName, requestSeq, error, metadata) {
+        return this.send(protocol_1.ZLinkStreamMessageKind.Error, packetName, requestSeq, boundSessionErrorPayload(error), metadata, 'error response');
+    }
+    async send(kind, packetName, requestSeq, payload, metadata, operationName) {
+        const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, false, requestSeq, payload);
+        try {
+            const result = await this.context.stream.submitRaw(frame);
+            if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+                throw new Error(`Actor '${this.actorId}' local bound session ${operationName} failed.`);
+            }
+            return true;
+        }
+        finally {
+            frame.close();
+        }
+    }
+}
+exports.DefaultZLinkBoundSessionResponseTarget = DefaultZLinkBoundSessionResponseTarget;
+function boundSessionErrorPayload(error) {
+    return {
+        code: error instanceof Error ? error.constructor.name : 'RemoteError',
+        message: errorMessage(error)
+    };
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'object' && error !== null) {
+        const message = error.message;
+        if (typeof message === 'string')
+            return message;
+        if (message !== undefined)
+            return errorMessage(message);
+    }
+    return String(error);
+}

package/dist/runtime/streams/bound-session-service.d.ts

@@ -0,0 +1,48 @@
+import type { ActorRef } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { ZLinkBackendActorSessionNode } from '../backend/contracts';
+import { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
+import type { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import { ZLinkStreamFrameMessageFactory } from './stream-frame-factory';
+import { ZLinkManagedStream } from './managed-stream';
+export interface ZLinkBoundSessionTransport {
+    send(actorId: string, message: unknown, options: ZLinkBoundSessionSendOptions): Promise<ZLinkSubmitResult>;
+    disconnect(actorId: string, options: ZLinkBoundSessionDisconnectOptions): Promise<void>;
+}
+export interface ZLinkBoundSessionSendOptions {
+    readonly bindingToken: string;
+    readonly packetName?: string;
+    readonly metadata: ReadonlyMap<string, string>;
+    readonly signal?: AbortSignal;
+}
+export interface ZLinkBoundSessionDisconnectOptions {
+    readonly bindingToken: string;
+    readonly signal?: AbortSignal;
+}
+export interface ZLinkBoundSessionServiceOptions {
+    readonly transport?: ZLinkBoundSessionTransport;
+    readonly actorBindTimeoutMs?: number;
+    readonly nativeActorMeshNameProvider?: () => string | undefined;
+}
+export declare class ZLinkBoundSessionService {
+    private readonly routes;
+    private readonly frameMessages;
+    private readonly options;
+    constructor(routes: ZLinkActorSessionBindingRegistry<DefaultZLinkSessionContext, DefaultZLinkSessionActor>, frameMessages: ZLinkStreamFrameMessageFactory, options: ZLinkBoundSessionServiceOptions);
+    sendBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;
+    submitLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;
+    sendLocalBoundSession(actorId: string, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+    sendLocalBoundSessionResponse(actorId: string, packetName: string, requestSeq: bigint, message: unknown, metadata: ReadonlyMap<string, string>, compressPayload: boolean): Promise<boolean>;
+    sendLocalBoundSessionError(actorId: string, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>): Promise<boolean>;
+    sendNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, message: unknown, packetName: string | undefined, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<ZLinkSubmitResult>;
+    sendNativeBoundSessionResponse(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, message: unknown, metadata: ReadonlyMap<string, string>, compressPayload: boolean, signal?: AbortSignal): Promise<void>;
+    sendNativeBoundSessionError(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, packetName: string, requestSeq: bigint, error: unknown, metadata: ReadonlyMap<string, string>, signal?: AbortSignal): Promise<void>;
+    disconnectNativeBoundSession(node: ZLinkBackendActorSessionNode, actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    disconnectBoundSession(actorId: string, signal?: AbortSignal): Promise<void>;
+    relayRemoteBoundSessionBind(stream: ZLinkManagedStream, actorRef: ActorRef): Promise<void>;
+    private writeLocalBoundSessionFrame;
+    private sendNativeBoundSessionPayload;
+    private submitNativeBoundSessionPayload;
+    private submitNativeBoundSessionFrame;
+    private requireTransport;
+}

package/dist/runtime/streams/bound-session-service.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkBoundSessionService = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const runtime_message_1 = require("../backend/runtime-message");
+const submission_result_1 = require("../messaging/submission-result");
+const abort_1 = require("../abort");
+const protocol_1 = require("./protocol");
+const bound_session_response_target_1 = require("./bound-session-response-target");
+const ZLINK_SEND_DONT_WAIT = 1;
+class ZLinkBoundSessionService {
+    routes;
+    frameMessages;
+    options;
+    constructor(routes, frameMessages, options) {
+        this.routes = routes;
+        this.frameMessages = frameMessages;
+        this.options = options;
+    }
+    async sendBoundSession(actorId, message, packetName, metadata, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const route = await this.routes.requireRoute(actorId);
+        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message);
+        try {
+            const result = await this.requireTransport().send(actorId, frame, {
+                bindingToken: route.bindingToken,
+                packetName,
+                metadata,
+                signal
+            });
+            await this.routes.requireCurrentToken(actorId, route.bindingToken);
+            return result;
+        }
+        finally {
+            frame.close();
+        }
+    }
+    async submitLocalBoundSession(actorId, message, packetName, metadata, signal) {
+        const route = await this.routes.route(actorId);
+        if (route === undefined) {
+            return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+        }
+        const frame = this.frameMessages.createJsonFrameMessage(protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message);
+        try {
+            (0, abort_1.throwIfAborted)(signal);
+            if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
+                return { status: submission_result_1.ZLinkSubmitStatus.TargetNotFound };
+            }
+            return await route.context.stream.submitRaw(frame, signal);
+        }
+        finally {
+            frame.close();
+        }
+    }
+    async sendLocalBoundSession(actorId, message, packetName, metadata) {
+        const route = await this.routes.route(actorId);
+        if (route === undefined) {
+            return false;
+        }
+        return await this.writeLocalBoundSessionFrame(actorId, route, protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message, 'send');
+    }
+    async sendLocalBoundSessionResponse(actorId, packetName, requestSeq, message, metadata, compressPayload) {
+        const route = await this.routes.route(actorId);
+        if (route === undefined) {
+            return false;
+        }
+        return await this.writeLocalBoundSessionFrame(actorId, route, protocol_1.ZLinkStreamMessageKind.Response, packetName, metadata, compressPayload, requestSeq, message, 'response');
+    }
+    async sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata) {
+        const route = await this.routes.route(actorId);
+        if (route === undefined) {
+            return false;
+        }
+        return await this.writeLocalBoundSessionFrame(actorId, route, protocol_1.ZLinkStreamMessageKind.Error, packetName, metadata, false, requestSeq, (0, bound_session_response_target_1.boundSessionErrorPayload)(error), 'error response');
+    }
+    async sendNativeBoundSession(node, actorRef, message, packetName, metadata, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        return await this.submitNativeBoundSessionPayload(node, actorRef, protocol_1.ZLinkStreamMessageKind.Send, (0, protocol_1.resolvePacketName)(message, packetName), metadata, false, undefined, message, signal);
+    }
+    async sendNativeBoundSessionResponse(node, actorRef, packetName, requestSeq, message, metadata, compressPayload, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        await this.sendNativeBoundSessionPayload(node, actorRef, protocol_1.ZLinkStreamMessageKind.Response, packetName, metadata, compressPayload, requestSeq, message, signal);
+    }
+    async sendNativeBoundSessionError(node, actorRef, packetName, requestSeq, error, metadata, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        await this.sendNativeBoundSessionPayload(node, actorRef, protocol_1.ZLinkStreamMessageKind.Error, packetName, metadata, false, requestSeq, (0, bound_session_response_target_1.boundSessionErrorPayload)(error), signal);
+    }
+    async disconnectNativeBoundSession(node, actorRef, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        await node.closeActorBoundSession(actorRef, requireBoundSessionGeneration(actorRef), 0, signal);
+    }
+    async disconnectBoundSession(actorId, signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        const route = await this.routes.requireRoute(actorId);
+        try {
+            await this.requireTransport().disconnect(actorId, {
+                bindingToken: route.bindingToken,
+                signal
+            });
+        }
+        finally {
+            await this.routes.unbind(actorId, route.context, route.bindingToken);
+        }
+    }
+    async relayRemoteBoundSessionBind(stream, actorRef) {
+        const encodedBindHeader = (0, protocol_1.encodeStreamHeader)({
+            kind: protocol_1.ZLinkStreamMessageKind.Send,
+            codec: protocol_1.ZLinkStreamCodec.Raw,
+            flags: protocol_1.ZLinkStreamHeaderFlags.None,
+            name: 'zlink.framework.actor.bound_session.bind',
+            metadata: new Map()
+        });
+        //  encodeStreamHeader returns a fresh, unaliased array; view it without re-copying.
+        const header = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.from(encodedBindHeader.buffer, encodedBindHeader.byteOffset, encodedBindHeader.byteLength));
+        const body = runtime_message_1.ZLinkBufferMessage.fromOwned(Buffer.alloc(0));
+        try {
+            if (!await stream.sendBoundActor(actorRef.actorId, [header, body], 0)) {
+                throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorRouteNotFound, `Actor '${actorRef.actorId}' remote bound session bind relay failed.`);
+            }
+        }
+        finally {
+            header.close();
+            body.close();
+        }
+    }
+    async writeLocalBoundSessionFrame(actorId, route, kind, packetName, metadata, compressPayload, requestSeq, payload, operationName) {
+        const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressPayload, requestSeq, payload);
+        try {
+            if ((await this.routes.route(actorId))?.bindingToken !== route.bindingToken) {
+                return false;
+            }
+            const result = await route.context.stream.submitRaw(frame);
+            if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+                throw new Error(`Actor '${actorId}' local bound session ${operationName} failed.`);
+            }
+            return true;
+        }
+        finally {
+            frame.close();
+        }
+    }
+    async sendNativeBoundSessionPayload(node, actorRef, kind, packetName, metadata, compressPayload, requestSeq, payload, signal) {
+        const result = await this.submitNativeBoundSessionPayload(node, actorRef, kind, packetName, metadata, compressPayload, requestSeq, payload, signal);
+        if (result.status !== submission_result_1.ZLinkSubmitStatus.Submitted) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, `Actor '${actorRef.actorId}' bound session route rejected '${result.status}'.`, result.status === submission_result_1.ZLinkSubmitStatus.RouteNotConnected);
+        }
+    }
+    async submitNativeBoundSessionPayload(node, actorRef, kind, packetName, metadata, compressPayload, requestSeq, payload, signal) {
+        const frame = this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressPayload, requestSeq, payload);
+        try {
+            return await this.submitNativeBoundSessionFrame(node, actorRef, frame, signal);
+        }
+        finally {
+            frame.close();
+        }
+    }
+    async submitNativeBoundSessionFrame(node, actorRef, frame, signal) {
+        const backendActorRef = toBoundSessionSendActorRef(actorRef);
+        (0, abort_1.throwIfAborted)(signal);
+        return await node.sendActorBoundSession(backendActorRef, requireBoundSessionGeneration(actorRef), [frame], ZLINK_SEND_DONT_WAIT, boundSessionSendFence(node, backendActorRef, actorRef));
+    }
+    requireTransport() {
+        if (this.options.transport === undefined) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, 'Bound session transport is not started.', true);
+        }
+        return this.options.transport;
+    }
+}
+exports.ZLinkBoundSessionService = ZLinkBoundSessionService;
+function requireBoundSessionGeneration(actorRef) {
+    const generation = actorRef.bindingGeneration;
+    if (generation === undefined || generation <= 0n) {
+        throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.ActorSessionNotBound, `Actor '${actorRef.actorId}' has no current bound-session generation.`, true);
+    }
+    return generation;
+}
+function toBoundSessionSendActorRef(actor) {
+    return {
+        nodeRid: actor.nodeRid,
+        actorId: actor.actorId,
+        generation: actor.objectGeneration
+    };
+}
+function boundSessionSendFence(node, backendActor, actor) {
+    const internal = actor;
+    const ownerNodeGeneration = internal.ownerNodeGeneration
+        ?? node.actorNodeGeneration?.(backendActor);
+    if (internal.ownershipGeneration === undefined
+        || internal.ownershipGeneration <= 0n
+        || internal.ownerLeaseGeneration === undefined
+        || internal.ownerLeaseGeneration <= 0n
+        || ownerNodeGeneration === undefined
+        || ownerNodeGeneration <= 0n) {
+        return undefined;
+    }
+    return Object.freeze({
+        targetNodeGeneration: ownerNodeGeneration,
+        authorityOwnerGeneration: internal.ownershipGeneration,
+        ownerLeaseGeneration: internal.ownerLeaseGeneration
+    });
+}