@zlink-systems/framework 0.10.0

package/dist/runtime/streams/index.d.ts

@@ -0,0 +1,152 @@
+import type { ActorRef, ZLinkActor, ZLinkBoundSession, ZLinkSessionActor, ZLinkMessageSerializer, ZLinkStreamCompressionOptions } from '../../contracts';
+import type { ZLinkProviderResolver } from '../../contracts/Common/ZLinkProviderResolver';
+import type { ZLinkSubmitResult } from '../messaging/submission-result';
+import { ZLinkMessage } from '../../contracts';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkFrameworkRegistration } from '../configuration';
+import { ZLinkDispatchErrorReporter } from '../channels';
+import type { ZLinkBackendAdapterFactory, ZLinkBackendActorSessionNode, ZLinkBackendContext, ZLinkBackendMeshNode } from '../backend/contracts';
+import type { ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import { ZLinkStreamCodec, type ZLinkStreamFrameHeader, ZLinkStreamMessageKind, type ZLinkStreamReplyMessageKind } from './protocol';
+import { type ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+import { ApplicationJobQueue } from '../host/application-job-queue';
+import { DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+import { type ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
+import { type ZLinkBoundSessionTransport } from './bound-session-service';
+import { ZLinkManagedStream } from './managed-stream';
+import { ZLinkStreamSessionNodeRuntime as ZLinkStreamSessionNodeRuntimeCore, ZLinkStreamSessionRuntime as ZLinkStreamSessionRuntimeCore, type ZLinkStreamSessionNodeRuntimeOptions as ZLinkStreamSessionNodeRuntimeCoreOptions, type ZLinkStreamSessionRuntimeOptions as ZLinkStreamSessionRuntimeCoreOptions } from './stream-session-runtime';
+import type { ZLinkActorRouteCommitOptions } from './stream-binding-runtime-ports';
+export { ZLinkPendingSessionRequest } from './session-requests';
+export { ZLinkActorSessionLifecycleCoordinator } from './actor-session-lifecycle-coordinator';
+export { ZLinkActorSessionBindingRegistry } from './actor-session-binding-registry';
+export { zlinkStreamLz4CompressionCodec } from './stream-frame-factory';
+export { ZLinkManagedStream } from './managed-stream';
+export { DefaultZLinkBoundSession, DefaultZLinkBoundSessionFactory, DefaultZLinkSessionActor, DefaultZLinkSessionContext } from './session-context';
+export type { ZLinkBoundSessionResponseTarget } from './bound-session-response-target';
+export type { ZLinkBoundSessionDisconnectOptions, ZLinkBoundSessionSendOptions, ZLinkBoundSessionTransport } from './bound-session-service';
+export interface ZLinkStreamBindingRuntimeOptions {
+    readonly transport?: ZLinkBoundSessionTransport;
+    readonly messageFactory?: ZLinkStreamMessageFactory;
+    readonly streamPayloadCodec?: ZLinkStreamPayloadCodec;
+    readonly streamCompression?: ZLinkStreamCompressionOptions;
+    readonly messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer>;
+    readonly actorBindTimeoutMs?: number;
+    readonly sessionRelocationSealTimeoutMs?: number;
+    readonly nativeActorMeshNameProvider?: () => string | undefined;
+    readonly actorRefResolver?: (actor: ZLinkActor) => ActorRef;
+    readonly actorAuthorityFenceResolver?: (actorId: string, signal?: AbortSignal) => Promise<ZLinkActorSessionAuthorityFence | undefined>;
+    readonly nativeActorNodeProvider?: () => {
+        status(): {
+            readonly routingId: unknown;
+        };
+    } | 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 relay?: (actor: ZLinkSessionActor, header: ZLinkStreamFrameHeader, payload: Message, signal?: AbortSignal) => Promise<boolean>;
+    readonly notifyDisconnected?: (actor: ZLinkSessionActor, signal?: AbortSignal) => Promise<void>;
+    readonly flowCreationEnabled?: () => boolean;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+}
+export interface ZLinkStreamPayloadCodec {
+    encode(payload: unknown): {
+        readonly codec: ZLinkStreamCodec;
+        readonly payload: Uint8Array;
+    };
+}
+export interface ZLinkStreamMessageFactory {
+    createTextMessage(payload: string): Message;
+    createBinaryMessage?(payload: Uint8Array): Message;
+}
+export interface ZLinkStreamSessionRuntimeOptions extends Omit<ZLinkStreamSessionRuntimeCoreOptions, 'bindingRuntime'> {
+    readonly bindingRuntime?: ZLinkStreamBindingRuntime;
+}
+export interface ZLinkStreamSessionNodeRuntimeOptions extends Omit<ZLinkStreamSessionNodeRuntimeCoreOptions, 'bindingRuntime'> {
+    readonly bindingRuntime?: ZLinkStreamBindingRuntime;
+}
+export interface ZLinkStreamRuntimeManagerOptions {
+    readonly registration: ZLinkFrameworkRegistration;
+    readonly backendAdapterFactory: ZLinkBackendAdapterFactory;
+    readonly context: ZLinkBackendContext;
+    readonly bindingRuntime: ZLinkStreamBindingRuntime;
+    readonly providerResolver?: ZLinkProviderResolver;
+    readonly dispatchErrors?: ZLinkDispatchErrorReporter;
+    readonly metrics?: import('../diagnostics').ZLinkRuntimeMetrics;
+    readonly acceptNewSession?: (meshName?: string) => boolean;
+    readonly primaryMeshName?: string;
+    readonly nativeMeshNode?: ZLinkBackendMeshNode;
+    readonly meshCompletions?: ZLinkMeshCompletionTable;
+    readonly nativeMeshNodeForName?: (meshName: string) => ZLinkBackendMeshNode | undefined;
+    readonly meshCompletionsForName?: (meshName: string) => ZLinkMeshCompletionTable | undefined;
+    readonly applicationJobQueue?: ApplicationJobQueue;
+}
+export declare class ZLinkStreamRuntimeManager {
+    private readonly options;
+    private readonly nodes;
+    private readonly applicationJobQueue;
+    constructor(options: ZLinkStreamRuntimeManagerOptions);
+    start(): void;
+    dispose(): Promise<void>;
+    notifyServerDrain(meshName: string): Promise<void>;
+    notifyUnscopedServerDrain(): Promise<void>;
+}
+export declare class ZLinkStreamSessionRuntime extends ZLinkStreamSessionRuntimeCore {
+    constructor(options: ZLinkStreamSessionRuntimeOptions, routingId: unknown, removeSession?: (sessionId: string, session: ZLinkStreamSessionRuntime) => void);
+}
+export declare class ZLinkStreamSessionNodeRuntime extends ZLinkStreamSessionNodeRuntimeCore {
+    constructor(options: ZLinkStreamSessionNodeRuntimeOptions);
+}
+export declare class ZLinkStreamBindingRuntime {
+    private readonly routes;
+    private readonly frameMessages;
+    private readonly compressionCodec;
+    private readonly boundSessions;
+    private readonly sessionActors;
+    private readonly boundActorRelay;
+    constructor(options?: ZLinkStreamBindingRuntimeOptions);
+    createSessionContext(stream: ZLinkManagedStream, close?: (signal?: AbortSignal) => Promise<void>, providerResolver?: ZLinkProviderResolver): DefaultZLinkSessionContext;
+    createBoundSession(actorId: string): ZLinkBoundSession;
+    bind(context: DefaultZLinkSessionContext, actorOrRef: ZLinkActor | ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
+    bindOrGet(context: DefaultZLinkSessionContext, actorRef: ActorRef, signal?: AbortSignal): Promise<DefaultZLinkSessionActor>;
+    find(actorId: string): Promise<DefaultZLinkSessionActor | undefined>;
+    hasBoundSession(actorId: string): Promise<boolean>;
+    captureBoundSessionResponseTarget(actor: ZLinkSessionActor): Promise<ZLinkBoundSessionResponseTarget | undefined>;
+    rebindActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    refreshActor(actorRef: ActorRef, signal?: AbortSignal): Promise<void>;
+    commitActorRoute(actorRef: ActorRef, signal?: AbortSignal, options?: ZLinkActorRouteCommitOptions): 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>;
+    abortActorRouteSeal(actorId: string, sealId: string): Promise<boolean>;
+    validateActorRouteSeal(actorId: string, sealId: string): Promise<boolean>;
+    unbind(actorId: string, context: DefaultZLinkSessionContext, bindingToken: string): Promise<void>;
+    unbindActor(actorId: string): Promise<void>;
+    cleanup(context: DefaultZLinkSessionContext): Promise<void>;
+    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>;
+    relay(actor: DefaultZLinkSessionActor, payload: ZLinkMessage, signal?: AbortSignal, dispatchHeader?: ZLinkStreamFrameHeader): Promise<ZLinkSubmitResult>;
+    notifyDisconnected(actor: DefaultZLinkSessionActor, signal?: AbortSignal): Promise<void>;
+    createTextMessage(payload: string): Message;
+    createBinaryMessage(payload: Uint8Array): Message;
+    decompressPayload(payload: Message): Message;
+    createJsonFrameMessage(kind: ZLinkStreamMessageKind, packetName: string, metadata: ReadonlyMap<string, string>, compressed: boolean, requestSeq: bigint | undefined, payload: unknown, correlationId?: string): Message;
+    createJsonReplyFrameMessage(requestHeader: ZLinkStreamFrameHeader, kind: ZLinkStreamReplyMessageKind, metadata: ReadonlyMap<string, string>, compressed: boolean, payload: unknown): Message;
+}

package/dist/runtime/streams/index.js

@@ -0,0 +1,338 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkStreamBindingRuntime = exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = exports.ZLinkStreamRuntimeManager = exports.DefaultZLinkSessionContext = exports.DefaultZLinkSessionActor = exports.DefaultZLinkBoundSessionFactory = exports.DefaultZLinkBoundSession = exports.ZLinkManagedStream = exports.zlinkStreamLz4CompressionCodec = exports.ZLinkActorSessionBindingRegistry = exports.ZLinkActorSessionLifecycleCoordinator = exports.ZLinkPendingSessionRequest = void 0;
+const service_session_binding_ingress_port_1 = require("../foundation/service-session-binding-ingress-port");
+const protocol_1 = require("./protocol");
+const actor_session_binding_registry_1 = require("./actor-session-binding-registry");
+const actor_session_binding_runtime_owner_1 = require("./actor-session-binding-runtime-owner");
+const actor_session_lifecycle_coordinator_1 = require("./actor-session-lifecycle-coordinator");
+const stream_frame_factory_1 = require("./stream-frame-factory");
+const application_job_queue_1 = require("../host/application-job-queue");
+const stream_message_utils_1 = require("./stream-message-utils");
+const session_context_1 = require("./session-context");
+const bound_session_response_target_1 = require("./bound-session-response-target");
+const bound_session_service_1 = require("./bound-session-service");
+const session_actor_coordinator_1 = require("./session-actor-coordinator");
+const bound_actor_relay_sender_1 = require("./bound-actor-relay-sender");
+const session_provider_1 = require("./session-provider");
+const InternalDefaults_1 = require("../../contracts/Configuration/InternalDefaults");
+const stream_session_runtime_1 = require("./stream-session-runtime");
+var session_requests_1 = require("./session-requests");
+Object.defineProperty(exports, "ZLinkPendingSessionRequest", { enumerable: true, get: function () { return session_requests_1.ZLinkPendingSessionRequest; } });
+var actor_session_lifecycle_coordinator_2 = require("./actor-session-lifecycle-coordinator");
+Object.defineProperty(exports, "ZLinkActorSessionLifecycleCoordinator", { enumerable: true, get: function () { return actor_session_lifecycle_coordinator_2.ZLinkActorSessionLifecycleCoordinator; } });
+var actor_session_binding_registry_2 = require("./actor-session-binding-registry");
+Object.defineProperty(exports, "ZLinkActorSessionBindingRegistry", { enumerable: true, get: function () { return actor_session_binding_registry_2.ZLinkActorSessionBindingRegistry; } });
+var stream_frame_factory_2 = require("./stream-frame-factory");
+Object.defineProperty(exports, "zlinkStreamLz4CompressionCodec", { enumerable: true, get: function () { return stream_frame_factory_2.zlinkStreamLz4CompressionCodec; } });
+var managed_stream_1 = require("./managed-stream");
+Object.defineProperty(exports, "ZLinkManagedStream", { enumerable: true, get: function () { return managed_stream_1.ZLinkManagedStream; } });
+var session_context_2 = require("./session-context");
+Object.defineProperty(exports, "DefaultZLinkBoundSession", { enumerable: true, get: function () { return session_context_2.DefaultZLinkBoundSession; } });
+Object.defineProperty(exports, "DefaultZLinkBoundSessionFactory", { enumerable: true, get: function () { return session_context_2.DefaultZLinkBoundSessionFactory; } });
+Object.defineProperty(exports, "DefaultZLinkSessionActor", { enumerable: true, get: function () { return session_context_2.DefaultZLinkSessionActor; } });
+Object.defineProperty(exports, "DefaultZLinkSessionContext", { enumerable: true, get: function () { return session_context_2.DefaultZLinkSessionContext; } });
+const DEFAULT_ACTOR_BIND_TIMEOUT_MS = 30_000;
+class ZLinkStreamRuntimeManager {
+    options;
+    nodes = new Map();
+    applicationJobQueue;
+    constructor(options) {
+        this.options = options;
+        this.applicationJobQueue = options.applicationJobQueue
+            ?? new application_job_queue_1.ApplicationJobQueue((0, application_job_queue_1.resolveApplicationJobQueueConfiguration)());
+    }
+    start() {
+        if (this.options.registration.streamNodes.size === 0) {
+            return;
+        }
+        const streamAdapter = this.options.backendAdapterFactory.createStreamAdapter();
+        const monitoringAdapter = this.options.backendAdapterFactory.createMonitoringAdapter();
+        for (const [nodeName, streamNode] of this.options.registration.streamNodes.entries()) {
+            const actorDispatchEnabled = streamNode.actorDispatchEnabled === true;
+            const applicationMeshName = actorDispatchEnabled ? this.options.primaryMeshName : undefined;
+            const nativeMeshNode = actorDispatchEnabled ? this.options.nativeMeshNode : undefined;
+            const meshCompletions = actorDispatchEnabled ? this.options.meshCompletions : undefined;
+            const socket = streamAdapter.createStreamSocket(this.options.context);
+            // Core uses -1 as the explicit unlimited value. The Framework value 0
+            // means that it adds no separate STREAM cap, so preserve that meaning
+            // when applying the socket option.
+            const maxMessageSize = streamNode.maxMessageSize ?? InternalDefaults_1.DEFAULT_STREAM_NODE_MAX_MESSAGE_SIZE;
+            socket.maxMessageSize = maxMessageSize === 0 ? -1 : maxMessageSize;
+            const tlsServer = streamNode.tlsServer;
+            if (tlsServer !== undefined) {
+                socket.setTlsServer(tlsServer.certificatePath, tlsServer.keyPath, tlsServer.requireClientCertificate ?? false);
+            }
+            socket.bind(streamNode.bind);
+            const readablePoller = streamAdapter.createReadablePoller(socket);
+            const nativeSessionRoutes = new Map();
+            if (actorDispatchEnabled) {
+                for (const [meshName, mesh] of this.options.registration.spotNodes) {
+                    const isPrimaryMesh = meshName === applicationMeshName;
+                    if (!isPrimaryMesh
+                        && mesh.objectRole !== 'client'
+                        && mesh.objectRole !== 'server')
+                        continue;
+                    const meshNode = this.options.nativeMeshNodeForName?.(meshName)
+                        ?? (isPrimaryMesh ? nativeMeshNode : undefined);
+                    const completions = this.options.meshCompletionsForName?.(meshName)
+                        ?? (isPrimaryMesh ? meshCompletions : undefined);
+                    const createService = meshNode?.createStreamSessionService;
+                    if (typeof createService !== 'function' || completions === undefined)
+                        continue;
+                    const service = createService.call(meshNode, socket.nativeInstance);
+                    const bindingOwner = (0, actor_session_binding_runtime_owner_1.actorSessionBindingRuntimeOwner)(this.options.bindingRuntime);
+                    (0, service_session_binding_ingress_port_1.registerServiceSessionBindingIngressPort)(service, {
+                        retainOutbound: (claim, delivery) => bindingOwner.admitRelocationOutbound(claim, delivery),
+                        clearOutbound: (actorId, error) => bindingOwner.clearRelocation(actorId, error)
+                    });
+                    nativeSessionRoutes.set(meshName, {
+                        service,
+                        completions
+                    });
+                }
+            }
+            const nativeSessionService = applicationMeshName === undefined
+                ? undefined
+                : nativeSessionRoutes.get(applicationMeshName)?.service;
+            const monitor = monitoringAdapter.openSocketMonitor(socket);
+            const sessionType = streamNode.session;
+            const sessionHandlerTypes = streamNode[Symbol.for('@zlink-systems/framework:session-handler-types')] ?? [];
+            const runtime = new stream_session_runtime_1.ZLinkStreamSessionNodeRuntime({
+                nodeName,
+                socket,
+                createPacket: () => streamAdapter.createStreamPacket(),
+                readablePoller,
+                applicationJobQueue: this.applicationJobQueue,
+                nativeSessionService,
+                meshCompletions,
+                nativeSessionRouteForMesh: meshName => nativeSessionRoutes.get(meshName),
+                monitor,
+                bindingRuntime: this.options.bindingRuntime,
+                acceptNewSession: () => this.options.acceptNewSession?.(applicationMeshName) !== false,
+                dispatchErrors: this.options.dispatchErrors,
+                metrics: this.options.metrics,
+                providerResolver: this.options.providerResolver,
+                messageSerializers: this.options.registration.messageSerializers,
+                replacementCallbackTimeoutMs: this.options.registration.sessionReplacementCallbackTimeoutMs,
+                sessionFactory: (context) => (0, session_provider_1.createStreamSessionInstance)(sessionType, this.options.providerResolver, context, sessionHandlerTypes)
+            });
+            runtime.start();
+            this.nodes.set(nodeName, {
+                meshName: applicationMeshName,
+                runtime,
+                socket,
+                monitor,
+                nativeSessionService,
+                nativeSessionServices: [...nativeSessionRoutes.values()].map(route => route.service)
+            });
+        }
+    }
+    async dispose() {
+        const nodes = [...this.nodes.values()];
+        this.nodes.clear();
+        for (const node of nodes.reverse()) {
+            await node.runtime.dispose();
+            const nativeServices = node.nativeSessionServices
+                ?? (node.nativeSessionService === undefined ? [] : [node.nativeSessionService]);
+            for (const service of nativeServices) {
+                service.shutdown(1000);
+                service.close();
+            }
+            await node.monitor.dispose();
+            await node.socket.dispose();
+        }
+    }
+    async notifyServerDrain(meshName) {
+        await Promise.all([...this.nodes.values()]
+            .filter((node) => node.meshName === meshName)
+            .map((node) => node.runtime.drainCloseSessions()));
+    }
+    async notifyUnscopedServerDrain() {
+        await Promise.all([...this.nodes.values()]
+            .filter((node) => node.meshName === undefined)
+            .map((node) => node.runtime.drainCloseSessions()));
+    }
+}
+exports.ZLinkStreamRuntimeManager = ZLinkStreamRuntimeManager;
+class ZLinkStreamSessionRuntime extends stream_session_runtime_1.ZLinkStreamSessionRuntime {
+    constructor(options, routingId, removeSession) {
+        // Spec 27 §4: a default-constructed binding runtime must still honor the
+        // process diagnostics level, so wire its Off gate to the runtime's
+        // dispatch-error flow tracer.
+        const bindingRuntime = options.bindingRuntime ?? new ZLinkStreamBindingRuntime({
+            flowCreationEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+        });
+        super({
+            ...options,
+            bindingRuntime
+        }, routingId, removeSession === undefined
+            ? undefined
+            : (sessionId, session) => removeSession(sessionId, session));
+    }
+}
+exports.ZLinkStreamSessionRuntime = ZLinkStreamSessionRuntime;
+class ZLinkStreamSessionNodeRuntime extends stream_session_runtime_1.ZLinkStreamSessionNodeRuntime {
+    constructor(options) {
+        // Spec 27 §4: keep the default binding runtime's flow creation behind the
+        // process diagnostics Off gate (see ZLinkStreamSessionRuntime above).
+        const bindingRuntime = options.bindingRuntime ?? new ZLinkStreamBindingRuntime({
+            flowCreationEnabled: () => options.dispatchErrors?.flow.flowCreationEnabled() ?? true
+        });
+        super({
+            ...options,
+            bindingRuntime
+        });
+    }
+}
+exports.ZLinkStreamSessionNodeRuntime = ZLinkStreamSessionNodeRuntime;
+class ZLinkStreamBindingRuntime {
+    routes;
+    frameMessages;
+    compressionCodec;
+    boundSessions;
+    sessionActors;
+    boundActorRelay;
+    constructor(options = {}) {
+        const runtimeOptions = {
+            ...options,
+            actorBindTimeoutMs: options.actorBindTimeoutMs ?? DEFAULT_ACTOR_BIND_TIMEOUT_MS
+        };
+        this.routes = new actor_session_binding_registry_1.ZLinkActorSessionBindingRegistry(4096, 4096, runtimeOptions.sessionRelocationSealTimeoutMs ?? 3_000);
+        this.compressionCodec = (0, stream_frame_factory_1.resolveStreamCompressionCodec)(runtimeOptions.streamCompression);
+        this.frameMessages = new stream_frame_factory_1.ZLinkStreamFrameMessageFactory(runtimeOptions);
+        this.boundSessions = new bound_session_service_1.ZLinkBoundSessionService(this.routes, this.frameMessages, runtimeOptions);
+        const actorSessionLifecycle = new actor_session_lifecycle_coordinator_1.ZLinkActorSessionLifecycleCoordinator();
+        this.sessionActors = new session_actor_coordinator_1.ZLinkSessionActorCoordinator(this.routes, this, runtimeOptions, actorSessionLifecycle);
+        this.boundActorRelay = new bound_actor_relay_sender_1.ZLinkBoundActorRelaySender(this.routes, this.frameMessages, runtimeOptions, actorSessionLifecycle);
+        (0, actor_session_binding_runtime_owner_1.registerActorSessionBindingRuntimeOwner)(this, {
+            sealRelocation: (claim, expected, signal) => this.routes.sealRelocation(claim, expected, signal),
+            relocationSnapshot: (actorId, sealId) => this.routes.relocationSnapshot(actorId, sealId),
+            retainRelocationOutbound: (actorId, operation, sealId) => this.routes.retainRelocationOutbound(actorId, operation, sealId),
+            admitRelocationOutbound: (claim, operation) => this.routes.admitRelocationOutbound(claim, operation),
+            discardRelocationOutbound: (actorId, sealId, error) => this.routes.discardRelocationOutbound(actorId, sealId, error),
+            applyRelocation: (...args) => this.routes.applyRelocation(...args),
+            observeRelocationTerminal: (...args) => this.routes.observeRelocationTerminal(...args),
+            clearRelocation: (actorId, error) => this.routes.clearRelocation(actorId, error),
+            committedRoute: async (actorId) => {
+                const route = await this.routes.route(actorId);
+                return route === undefined
+                    ? undefined
+                    : { actor: route.actor.ref, authorityFence: route.authorityFence };
+            }
+        });
+    }
+    createSessionContext(stream, close, providerResolver) {
+        return new session_context_1.DefaultZLinkSessionContext(this, stream, close ?? ((signal) => stream.close(signal)), providerResolver);
+    }
+    createBoundSession(actorId) {
+        return new session_context_1.DefaultZLinkBoundSession(this, actorId);
+    }
+    async bind(context, actorOrRef, signal) {
+        return await this.sessionActors.bind(context, actorOrRef, signal);
+    }
+    async bindOrGet(context, actorRef, signal) {
+        return await this.sessionActors.bindOrGet(context, actorRef, signal);
+    }
+    async find(actorId) {
+        return await this.routes.find(actorId);
+    }
+    async hasBoundSession(actorId) {
+        return (await this.routes.find(actorId)) !== undefined;
+    }
+    async captureBoundSessionResponseTarget(actor) {
+        const bindingToken = actor.bindingToken;
+        if (typeof bindingToken !== 'string') {
+            return undefined;
+        }
+        const claim = await this.routes.capturePendingReplyClaim(actor.actorId, actor, bindingToken);
+        if (claim === undefined)
+            return undefined;
+        return new bound_session_response_target_1.DefaultZLinkBoundSessionResponseTarget(this.frameMessages, claim.context, actor.actorId);
+    }
+    async rebindActor(actorRef, signal) {
+        await this.sessionActors.rebindActor(actorRef, signal);
+    }
+    async refreshActor(actorRef, signal) {
+        await this.sessionActors.refreshActor(actorRef, signal);
+    }
+    async commitActorRoute(actorRef, signal, options) {
+        await this.sessionActors.commitActorRoute(actorRef, signal, options);
+    }
+    async retireRemoteBinding(actorRef, sessionRid, bindingGeneration, signal) {
+        return await this.sessionActors.retireRemoteBinding(actorRef, sessionRid, bindingGeneration, signal);
+    }
+    async authorityFence(actorId) {
+        return await this.sessionActors.authorityFence(actorId);
+    }
+    async sessionRouteFence(actorId) {
+        return await this.sessionActors.sessionRouteFence(actorId);
+    }
+    async abortActorRouteSeal(actorId, sealId) {
+        return await this.routes.abortSeal(actorId, sealId);
+    }
+    async validateActorRouteSeal(actorId, sealId) {
+        return await this.routes.validateSeal(actorId, sealId);
+    }
+    async unbind(actorId, context, bindingToken) {
+        await this.routes.unbind(actorId, context, bindingToken);
+    }
+    async unbindActor(actorId) {
+        await this.routes.unbindActor(actorId);
+    }
+    async cleanup(context) {
+        await this.boundActorRelay.notifyPhysicalDisconnect(context);
+    }
+    async sendBoundSession(actorId, message, packetName, metadata, signal) {
+        return await this.boundSessions.sendBoundSession(actorId, message, packetName, metadata, signal);
+    }
+    async submitLocalBoundSession(actorId, message, packetName, metadata, signal) {
+        return await this.boundSessions.submitLocalBoundSession(actorId, message, packetName, metadata, signal);
+    }
+    async sendLocalBoundSession(actorId, message, packetName, metadata) {
+        return await this.boundSessions.sendLocalBoundSession(actorId, message, packetName, metadata);
+    }
+    async sendLocalBoundSessionResponse(actorId, packetName, requestSeq, message, metadata, compressPayload) {
+        return await this.boundSessions.sendLocalBoundSessionResponse(actorId, packetName, requestSeq, message, metadata, compressPayload);
+    }
+    async sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata) {
+        return await this.boundSessions.sendLocalBoundSessionError(actorId, packetName, requestSeq, error, metadata);
+    }
+    async sendNativeBoundSession(node, actorRef, message, packetName, metadata, signal) {
+        return await this.boundSessions.sendNativeBoundSession(node, actorRef, message, packetName, metadata, signal);
+    }
+    async sendNativeBoundSessionResponse(node, actorRef, packetName, requestSeq, message, metadata, compressPayload, signal) {
+        await this.boundSessions.sendNativeBoundSessionResponse(node, actorRef, packetName, requestSeq, message, metadata, compressPayload, signal);
+    }
+    async sendNativeBoundSessionError(node, actorRef, packetName, requestSeq, error, metadata, signal) {
+        await this.boundSessions.sendNativeBoundSessionError(node, actorRef, packetName, requestSeq, error, metadata, signal);
+    }
+    async disconnectNativeBoundSession(node, actorRef, signal) {
+        await this.boundSessions.disconnectNativeBoundSession(node, actorRef, signal);
+    }
+    async disconnectBoundSession(actorId, signal) {
+        await this.boundSessions.disconnectBoundSession(actorId, signal);
+    }
+    async relay(actor, payload, signal, dispatchHeader) {
+        return await this.boundActorRelay.relay(actor, payload, signal, dispatchHeader);
+    }
+    async notifyDisconnected(actor, signal) {
+        await this.boundActorRelay.notifyDisconnected(actor, signal);
+    }
+    createTextMessage(payload) {
+        return this.frameMessages.createTextMessage(payload);
+    }
+    createBinaryMessage(payload) {
+        return this.frameMessages.createBinaryMessage(payload);
+    }
+    decompressPayload(payload) {
+        return (0, stream_message_utils_1.simpleMessage)((0, stream_frame_factory_1.decompressStreamPayload)((0, protocol_1.messageToBytes)(payload), this.compressionCodec));
+    }
+    createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId) {
+        return this.frameMessages.createJsonFrameMessage(kind, packetName, metadata, compressed, requestSeq, payload, correlationId);
+    }
+    createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload) {
+        return this.frameMessages.createJsonReplyFrameMessage(requestHeader, kind, metadata, compressed, payload);
+    }
+}
+exports.ZLinkStreamBindingRuntime = ZLinkStreamBindingRuntime;

package/dist/runtime/streams/managed-stream.d.ts

@@ -0,0 +1,53 @@
+import type { ActorRef, RoutingId, ZLinkMessage, ZLinkMessageSerializer, ZLinkStream } from '../../contracts';
+import { type ZLinkSubmitResult } from '../messaging/submission-result';
+import type { Message } from '../../contracts/Common/Message';
+import type { ZLinkBackendSendFlags, ZLinkBackendStreamSocket } from '../backend/contracts';
+import type { StreamSessionService } from '../foundation/service-runtime-contracts';
+import type { ServiceRetiredBoundSessionRouteFence } from '../foundation/service-stateful-wire-codec';
+import type { ServiceActorRef } from '../foundation/service-stateful-registry';
+import { type ZLinkMeshCompletionTable } from '../backend/mesh-completion-table';
+import { ZLinkStreamCloseReasonCode } from './protocol';
+import type { ZLinkActorSessionAuthorityFence } from './actor-session-binding-registry';
+export interface ZLinkNativeSessionRoute {
+    readonly service: StreamSessionService;
+    readonly completions: ZLinkMeshCompletionTable;
+}
+export declare class ZLinkManagedStream implements ZLinkStream {
+    private readonly socket;
+    private readonly backendSessionRoutingId;
+    private readonly messageSerializers?;
+    private readonly nativeSessionService?;
+    private readonly meshCompletions?;
+    private readonly publicSessionId;
+    private readonly nativeSessionRouteForMesh?;
+    private currentLocalAddr;
+    private currentRemoteAddr;
+    private transportClosed;
+    private readonly nativeActorBindings;
+    constructor(socket: ZLinkBackendStreamSocket, backendSessionRoutingId: unknown, messageSerializers?: ReadonlyMap<string, ZLinkMessageSerializer> | undefined, nativeSessionService?: StreamSessionService | undefined, meshCompletions?: ZLinkMeshCompletionTable | undefined, publicSessionId?: string, nativeSessionRouteForMesh?: ((meshName: string) => ZLinkNativeSessionRoute | undefined) | undefined);
+    get sessionId(): string;
+    get routingId(): RoutingId;
+    get actorBindingRoutingId(): RoutingId;
+    actorBindingGeneration(actorId: string): bigint | undefined;
+    private isTransportClosed;
+    get localAddr(): string | undefined;
+    get remoteAddr(): string | undefined;
+    write(payload: ZLinkMessage, flags?: ZLinkBackendSendFlags): boolean;
+    writeRaw(payload: Message, flags?: ZLinkBackendSendFlags): boolean;
+    submitRaw(payload: Message, signal?: AbortSignal, timeoutMs?: number): Promise<ZLinkSubmitResult>;
+    submitBoundActor(actorId: string, parts: readonly Message[], signal?: AbortSignal): Promise<ZLinkSubmitResult>;
+    close(signal?: AbortSignal): Promise<void>;
+    closeForDrain(signal?: AbortSignal): Promise<void>;
+    writeControl(name: string): Promise<void>;
+    closeForReason(reason: ZLinkStreamCloseReasonCode, diagnostic: string, signal?: AbortSignal): Promise<void>;
+    bindActor(actor: ActorRef, timeoutMs: number, signal?: AbortSignal, onBindingReplaced?: (actor: ServiceActorRef, retiredSession: ServiceRetiredBoundSessionRouteFence) => void, authorityFence?: ZLinkActorSessionAuthorityFence): Promise<void>;
+    private ensureNativeActorRoute;
+    unbindActor(actorId: string, timeoutMs: number, signal?: AbortSignal): Promise<void>;
+    sendBoundActor(actorId: string, parts: readonly Message[], flags?: ZLinkBackendSendFlags): Promise<boolean>;
+    updateAddresses(localAddr: string | undefined, remoteAddr: string | undefined): void;
+    private hasNativeBinding;
+    private backendRoutingId;
+    private requireSuccessfulCompletion;
+    private nativeRoute;
+}
+export declare function streamSessionIdFromRoutingId(routingId: unknown): string;