@zlink-systems/framework 0.10.0

package/dist/runtime/streams/stream-session-runtime.js

@@ -0,0 +1,1144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkStreamSessionNodeRuntime = exports.ZLinkStreamSessionRuntime = void 0;
+const framework_errors_internal_1 = require("../framework-errors-internal");
+const contracts_1 = require("../../contracts");
+const internal_event_contracts_1 = require("../diagnostics/internal-event-contracts");
+const ZLinkDispatchOptions_1 = require("../../contracts/Dispatch/ZLinkDispatchOptions");
+const abort_1 = require("../abort");
+const channels_1 = require("../channels");
+const diagnostics_1 = require("../diagnostics");
+const payload_codec_1 = require("../messaging/payload-codec");
+const protocol_1 = require("./protocol");
+const flow_context_1 = require("../diagnostics/flow-context");
+const managed_stream_1 = require("./managed-stream");
+const session_context_1 = require("./session-context");
+const session_serial_executor_1 = require("./session-serial-executor");
+const stream_message_utils_1 = require("./stream-message-utils");
+const application_job_queue_scope_1 = require("../application-jobs/application-job-queue-scope");
+const application_job_queue_scope_2 = require("../application-jobs/application-job-queue-scope");
+const ZLINK_SEND_DONT_WAIT = 1;
+const ZLINK_RECV_DONT_WAIT = 1;
+const ZLINK_STREAM_HEARTBEAT_INTERVAL_MS = 1_000;
+const ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS = 5_000;
+const ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS = 30_000;
+const ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT = 64;
+const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS = 30_000;
+const ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS = 100;
+const systemLivenessClock = {
+    now: () => performance.now(),
+    setTimer: (callback, delayMs) => setTimeout(callback, delayMs),
+    clearTimer: (timer) => clearTimeout(timer)
+};
+class ZLinkStreamIdleWaiter {
+    delayMs;
+    pending;
+    resolvePending;
+    timer;
+    finish = () => {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        const resolve = this.resolvePending;
+        this.pending = undefined;
+        this.resolvePending = undefined;
+        resolve?.();
+    };
+    constructor(delayMs) {
+        this.delayMs = delayMs;
+    }
+    wait() {
+        if (this.pending !== undefined)
+            return this.pending;
+        this.pending = new Promise((resolve) => {
+            this.resolvePending = resolve;
+        });
+        this.timer = setTimeout(this.finish, this.delayMs);
+        return this.pending;
+    }
+    wake() {
+        this.finish();
+    }
+}
+class ZLinkStreamSessionRuntime {
+    options;
+    removeSession;
+    stream;
+    context;
+    sessionReady;
+    serial = new session_serial_executor_1.ZLinkSessionSerialExecutor();
+    connected = false;
+    disconnected = false;
+    disconnectQueued = false;
+    disposed = false;
+    closeReason = 'client_close';
+    metricsClosed = false;
+    livenessClock;
+    lastApplicationActivityAt = 0;
+    awaitingPongSince;
+    livenessTimer;
+    constructor(options, routingId, removeSession = () => { }) {
+        this.options = options;
+        this.removeSession = removeSession;
+        this.livenessClock = options.livenessClock ?? systemLivenessClock;
+        this.stream = new managed_stream_1.ZLinkManagedStream(options.socket, routingId, options.messageSerializers, options.nativeSessionService, options.meshCompletions, undefined, options.nativeSessionRouteForMesh);
+        this.context = options.bindingRuntime.createSessionContext(this.stream, (signal) => this.close(signal), options.providerResolver);
+        this.context.setActorBindingReplacementHandler((actor, retiredSession) => {
+            this.enqueueActorBindingReplaced(actor, retiredSession);
+        });
+        this.context.setFrameWrittenObserver((kind, packetName, correlationId) => {
+            this.traceFrameWritten(kind, packetName, correlationId);
+        });
+        const sessionOrPromise = options.sessionFactory(this.context);
+        this.sessionReady = isPromiseLike(sessionOrPromise)
+            ? sessionOrPromise.then((session) => this.completeSessionCreation(session), (error) => {
+                this.context.completeConfiguration();
+                throw error;
+            })
+            : Promise.resolve(this.completeSessionCreation(sessionOrPromise));
+    }
+    get session() {
+        return this.sessionReady;
+    }
+    get isDisconnected() {
+        return this.disconnected || this.disconnectQueued;
+    }
+    requireProvidedContext(session) {
+        if (session.context !== this.context) {
+            throw (0, framework_errors_internal_1.createInternalFrameworkException)(framework_errors_internal_1.ZLinkFrameworkInternalErrorKind.RouteNotConnected, 'Session must expose the context provided by the stream runtime.');
+        }
+        return session;
+    }
+    completeSessionCreation(session) {
+        this.context.completeConfiguration();
+        return this.requireProvidedContext(session);
+    }
+    requireSession() {
+        return this.sessionReady;
+    }
+    enqueueConnected(localAddr, remoteAddr) {
+        this.serial.executeInfrastructure(async () => this.markConnected(localAddr, remoteAddr));
+    }
+    enqueuePacket(payload, decodedHeader, terminalOwner, applicationJobPermit) {
+        let terminalReleased = false;
+        const releaseTerminal = () => {
+            if (terminalReleased)
+                return;
+            terminalReleased = true;
+            terminalOwner?.close();
+        };
+        if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Control) {
+            if ((0, protocol_1.messageToBytes)(payload).length === 0
+                && (decodedHeader.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG
+                    || decodedHeader.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING)) {
+                void this.handleControl(decodedHeader, payload).catch(error => {
+                    this.options.onError?.(error);
+                }).finally(() => {
+                    applicationJobPermit?.releaseAfterInternalProcessing();
+                    payload.close();
+                    releaseTerminal();
+                });
+                return;
+            }
+            this.enqueueControl(async () => {
+                try {
+                    const dispatch = () => this.dispatchPacket(payload, decodedHeader);
+                    if (applicationJobPermit === undefined)
+                        await dispatch();
+                    else
+                        await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, dispatch);
+                }
+                finally {
+                    releaseTerminal();
+                }
+            }, () => {
+                applicationJobPermit?.releaseAfterInternalProcessing();
+                payload.close();
+                releaseTerminal();
+            }, () => this.traceShutdownDrop(decodedHeader));
+            return;
+        }
+        if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Response
+            || decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Error) {
+            this.enqueueInfrastructure(async () => {
+                try {
+                    await this.dispatchPacket(payload, decodedHeader);
+                }
+                finally {
+                    releaseTerminal();
+                }
+            }, () => {
+                applicationJobPermit?.releaseAfterInternalProcessing();
+                payload.close();
+                releaseTerminal();
+            }, () => this.traceShutdownDrop(decodedHeader));
+            return;
+        }
+        this.enqueueApplication(async () => {
+            try {
+                const dispatch = () => this.dispatchPacket(payload, decodedHeader);
+                if (applicationJobPermit === undefined)
+                    await dispatch();
+                else
+                    await (0, application_job_queue_scope_1.runWithApplicationJobPermit)(applicationJobPermit, dispatch);
+            }
+            finally {
+                releaseTerminal();
+            }
+        }, (error) => {
+            applicationJobPermit?.releaseAfterInternalProcessing();
+            payload.close();
+            releaseTerminal();
+            if (error !== undefined) {
+                void this.replyDispatchError(decodedHeader, error).catch((replyError) => {
+                    this.options.onError?.(replyError);
+                });
+            }
+        }, () => this.traceShutdownDrop(decodedHeader));
+    }
+    enqueueDisconnected(error) {
+        this.queueDisconnect(error);
+    }
+    /**
+     * Starts the callback on the session lane and observes its terminal result
+     * without retaining that lane while application code awaits unrelated work.
+     */
+    enqueueActorBindingReplaced(actor, retiredSession) {
+        this.serial.executeControl(async () => {
+            if (this.disposed || this.disconnected)
+                return;
+            if (!this.context.beginActorBindingReplacement(actor, retiredSession))
+                return;
+            const session = await this.requireSession();
+            let callbackDeadlineTimer;
+            let callbackTerminal = false;
+            let forcedClose = false;
+            const scheduleClose = () => {
+                if (forcedClose)
+                    return;
+                this.livenessClock.setTimer(() => {
+                    if (this.disposed
+                        || this.disconnected
+                        || !this.context.isExactRetiredActorBinding(actor, retiredSession)) {
+                        return;
+                    }
+                    void this.close().catch(error => this.options.onError?.(error));
+                }, ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CLOSE_DELAY_MS);
+            };
+            const completeCallback = () => {
+                if (callbackTerminal)
+                    return;
+                callbackTerminal = true;
+                if (callbackDeadlineTimer !== undefined) {
+                    this.livenessClock.clearTimer(callbackDeadlineTimer);
+                    callbackDeadlineTimer = undefined;
+                }
+                scheduleClose();
+            };
+            const reportCallbackFailure = (error) => {
+                try {
+                    this.options.onError?.(error);
+                }
+                catch {
+                    // Diagnostics must not prevent the lifecycle terminal transition.
+                }
+                completeCallback();
+            };
+            callbackDeadlineTimer = this.livenessClock.setTimer(() => {
+                if (this.disposed
+                    || this.disconnected
+                    || !this.context.isExactRetiredActorBinding(actor, retiredSession)) {
+                    return;
+                }
+                forcedClose = true;
+                void this.close().catch(error => this.options.onError?.(error));
+            }, this.options.replacementCallbackTimeoutMs
+                ?? ZLINK_STREAM_ACTOR_BINDING_REPLACEMENT_CALLBACK_TIMEOUT_MS);
+            const callback = session.onActorBindingReplaced;
+            if (callback === undefined) {
+                completeCallback();
+                return;
+            }
+            try {
+                // Start the callback on this lifecycle turn, but do not retain the
+                // serial lane while application code awaits an unrelated operation.
+                const result = callback.call(session, this.context, actor.actorId);
+                void Promise.resolve(result).then(() => completeCallback(), reportCallbackFailure);
+            }
+            catch (error) {
+                reportCallbackFailure(error);
+            }
+        });
+    }
+    async close(signal) {
+        (0, abort_1.throwIfAborted)(signal);
+        this.stream.markTransportClosed();
+        await this.stream.close(signal);
+        if (this.disconnected || this.disconnectQueued) {
+            return;
+        }
+        this.queueDisconnect(undefined);
+    }
+    async dispose() {
+        if (this.disposed) {
+            return;
+        }
+        this.disposed = true;
+        this.stopLivenessChecks();
+        await this.serial.dispose();
+        this.stream.markTransportClosed();
+        if (!this.disconnected) {
+            this.disconnected = true;
+            const session = await this.requireSession();
+            await session.onDisconnected?.(this.context);
+        }
+        await this.cleanup();
+    }
+    async drainClose() {
+        this.closeReason = 'server_drain';
+        await this.serial.executeFinal(async () => {
+            if (this.disposed)
+                return;
+            this.stream.markTransportClosed();
+            this.stopLivenessChecks();
+            await this.stream.closeForDrain();
+            if (!this.disconnected) {
+                this.disconnected = true;
+                await this.complete(undefined, true);
+            }
+        });
+    }
+    async markConnected(localAddr, remoteAddr) {
+        this.stream.updateAddresses(localAddr, remoteAddr);
+        if (this.connected) {
+            return;
+        }
+        this.connected = true;
+        this.lastApplicationActivityAt = this.livenessClock.now();
+        this.scheduleLivenessCheck();
+        this.options.metrics?.change('zlink.stream.connections.active', 1, { transport: 'tcp' });
+        this.options.metrics?.count('zlink.stream.connections.opened', 1, { transport: 'tcp' });
+        const session = await this.requireSession();
+        await session.onConnected?.(this.context);
+    }
+    async dispatchPacket(payload, decodedHeader) {
+        let dispatchPayload = payload;
+        let enteredDispatch = false;
+        try {
+            if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Control) {
+                await this.handleControl(decodedHeader, payload);
+                return;
+            }
+            this.lastApplicationActivityAt = this.livenessClock.now();
+            dispatchPayload = this.context.payloadForHeader(decodedHeader, payload);
+            if (this.context.tryCompleteResponse(decodedHeader, dispatchPayload)) {
+                return;
+            }
+            this.context.enterDispatch(decodedHeader);
+            enteredDispatch = true;
+            const session = await this.requireSession();
+            const streamKind = decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Request
+                ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request
+                : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send;
+            const streamCorr = decodedHeader.correlationId;
+            const inboundHeader = decodedHeader;
+            await (0, flow_context_1.runWithFlow)((0, flow_context_1.createInboundFlow)(inboundHeader.flowId, inboundHeader.flowOrigin, this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true), async () => {
+                (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received)?.trace({
+                    outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Received,
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+                    messageKind: streamKind,
+                    packetName: inboundHeader.name,
+                    correlationId: streamCorr,
+                    sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+                });
+                (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted)?.trace({
+                    outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Admitted,
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+                    messageKind: streamKind,
+                    packetName: inboundHeader.name,
+                    correlationId: streamCorr,
+                    sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+                });
+                (0, application_job_queue_scope_2.releaseApplicationJobPermitBeforeHandler)();
+                (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched)?.trace({
+                    outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dispatched,
+                    surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+                    messageKind: streamKind,
+                    packetName: inboundHeader.name,
+                    correlationId: streamCorr,
+                    sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+                });
+                await session.onDispatch?.((0, session_context_1.createSessionDispatchContext)(inboundHeader), (0, payload_codec_1.wrapFrameworkPayloadMessage)(dispatchPayload, this.options.messageSerializers, (0, protocol_1.streamCodecContentType)(inboundHeader.codec), inboundHeader.name));
+                if (streamKind === ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send) {
+                    (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed)?.trace({
+                        outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Completed,
+                        surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+                        messageKind: streamKind,
+                        packetName: inboundHeader.name,
+                        correlationId: streamCorr,
+                        sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+                    });
+                }
+            });
+        }
+        catch (error) {
+            this.options.dispatchErrors?.report({
+                surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+                messageKind: decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Request
+                    ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request
+                    : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+                reason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.HandlerException,
+                action: decodedHeader.requestSeq === undefined
+                    ? ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.Drop
+                    : ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorAction.ReplyError,
+                packetName: decodedHeader.name,
+                sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId),
+                correlationId: decodedHeader.correlationId,
+                flowId: decodedHeader.flowId,
+                flowOrigin: decodedHeader.flowOrigin,
+                error
+            });
+            this.options.onError?.(error);
+            await this.replyDispatchError(decodedHeader, error);
+            if (error instanceof channels_1.ZLinkRouteDisconnectedError && decodedHeader.requestSeq === undefined) {
+                await this.context.close();
+            }
+        }
+        finally {
+            if (enteredDispatch) {
+                this.context.exitDispatch();
+            }
+            if (dispatchPayload !== payload) {
+                dispatchPayload.close();
+            }
+            payload.close();
+        }
+    }
+    async handleControl(header, payload) {
+        if ((0, protocol_1.messageToBytes)(payload).length !== 0) {
+            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', 'Control heartbeat payload must be empty.');
+            return;
+        }
+        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PONG) {
+            this.awaitingPongSince = undefined;
+            return;
+        }
+        if (header.name === protocol_1.ZLINK_STREAM_HEARTBEAT_PING) {
+            await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PONG);
+            return;
+        }
+        await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.ProtocolError, 'protocol_error', `Unknown stream control frame: ${header.name}`);
+    }
+    scheduleLivenessCheck() {
+        if (this.disposed || this.disconnected || this.livenessTimer !== undefined) {
+            return;
+        }
+        this.livenessTimer = this.livenessClock.setTimer(() => {
+            this.livenessTimer = undefined;
+            this.serial.executeInfrastructure(async () => this.runLivenessCheck(), {}, error => this.options.onError?.(error));
+        }, ZLINK_STREAM_HEARTBEAT_INTERVAL_MS);
+    }
+    async runLivenessCheck() {
+        if (this.disposed || this.disconnected || !this.connected) {
+            return;
+        }
+        const now = this.livenessClock.now();
+        if (now - this.lastApplicationActivityAt >= ZLINK_STREAM_APPLICATION_IDLE_TIMEOUT_MS) {
+            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.IdleTimeout, 'idle_timeout', 'Application idle timeout.');
+            return;
+        }
+        if (this.awaitingPongSince !== undefined
+            && now - this.awaitingPongSince >= ZLINK_STREAM_HEARTBEAT_TIMEOUT_MS) {
+            await this.closeForLiveness(protocol_1.ZLinkStreamCloseReasonCode.HeartbeatTimeout, 'heartbeat_timeout', 'Heartbeat timeout.');
+            return;
+        }
+        await this.stream.writeControl(protocol_1.ZLINK_STREAM_HEARTBEAT_PING);
+        this.awaitingPongSince ??= now;
+        this.scheduleLivenessCheck();
+    }
+    async closeForLiveness(reason, closeReason, diagnostic) {
+        if (this.disconnected) {
+            return;
+        }
+        this.stream.markTransportClosed();
+        this.disconnected = true;
+        this.closeReason = closeReason;
+        this.stopLivenessChecks();
+        await this.stream.closeForReason(reason, diagnostic);
+        await this.complete(undefined, true);
+    }
+    stopLivenessChecks() {
+        if (this.livenessTimer !== undefined) {
+            this.livenessClock.clearTimer(this.livenessTimer);
+            this.livenessTimer = undefined;
+        }
+    }
+    async replyDispatchError(header, error) {
+        if (header.requestSeq === undefined) {
+            return;
+        }
+        if (this.context.dispatchHeader === header && this.context.replyClaimed) {
+            // The handler already submitted the request's terminal reply; a second
+            // error frame for the same requestSeq would duplicate the terminal
+            // record (spec 26 §2.2) and confuse the peer's reply matching.
+            return;
+        }
+        const message = this.context.createJsonReplyFrameMessage(header, protocol_1.ZLinkStreamMessageKind.Error, new Map(), false, {
+            code: error instanceof contracts_1.ZLinkFrameworkException
+                ? contracts_1.ZLinkFrameworkErrorKind[error.kind]
+                : error instanceof Error
+                    ? error.constructor.name
+                    : 'RemoteError',
+            message: error instanceof Error ? error.message : String(error)
+        });
+        try {
+            if (!this.context.stream.writeRaw(message, ZLINK_SEND_DONT_WAIT)) {
+                throw new Error('Client stream error reply send failed.');
+            }
+            this.traceFrameWritten(protocol_1.ZLinkStreamMessageKind.Error, header.name, header.correlationId);
+        }
+        catch (replyError) {
+            this.options.onError?.(replyError);
+        }
+        finally {
+            message.close();
+        }
+    }
+    /**
+     * Spec 26 §2.1/§2.2: a successful session write is the surface's terminal
+     * boundary — `replied` for a request's response or error reply, `sent` for a
+     * session-connected send. Exactly one record per write, matching the other
+     * languages' write-path trace.
+     */
+    traceFrameWritten(kind, packetName, correlationId) {
+        const reply = kind === protocol_1.ZLinkStreamMessageKind.Response
+            || kind === protocol_1.ZLinkStreamMessageKind.Error;
+        const outcome = reply ? ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Replied : ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Sent;
+        (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, outcome)?.trace({
+            outcome,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+            messageKind: kind === protocol_1.ZLinkStreamMessageKind.Response
+                ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Response
+                : kind === protocol_1.ZLinkStreamMessageKind.Error
+                    ? ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Error
+                    : ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send,
+            packetName: packetName.length === 0 ? undefined : packetName,
+            correlationId,
+            sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId)
+        });
+    }
+    async complete(error, notifyDisconnected) {
+        try {
+            if (error !== undefined && this.closeReason !== 'server_drain') {
+                this.closeReason = 'transport_error';
+            }
+            if (error !== undefined) {
+                const session = await this.requireSession();
+                await session.onError?.(this.context, {
+                    error: 'transportError',
+                    message: error instanceof Error ? error.message : String(error)
+                });
+            }
+            if (notifyDisconnected) {
+                const session = await this.requireSession();
+                await session.onDisconnected?.(this.context);
+            }
+        }
+        finally {
+            await this.cleanup();
+        }
+    }
+    queueDisconnect(error) {
+        if (this.disconnected || this.disconnectQueued)
+            return;
+        this.disconnectQueued = true;
+        this.stopLivenessChecks();
+        void this.serial.executeFinal(async () => {
+            this.disconnectQueued = false;
+            if (this.disconnected)
+                return;
+            this.stream.markTransportClosed();
+            this.disconnected = true;
+            await this.complete(error, true);
+        }).catch(() => {
+            this.disconnectQueued = false;
+        });
+    }
+    async cleanup() {
+        if (this.connected && !this.metricsClosed) {
+            this.metricsClosed = true;
+            this.options.metrics?.change('zlink.stream.connections.active', -1, { transport: 'tcp' });
+            this.options.metrics?.count('zlink.stream.connections.closed', 1, {
+                transport: 'tcp',
+                close_reason: normalizeStreamCloseReason(this.closeReason)
+            });
+        }
+        await this.context.cleanupBindings();
+        this.removeSession(this.stream.sessionId, this);
+    }
+    enqueueControl(work, onRejected, onShutdownRejected) {
+        if (!this.serial.executeControl(work, {}, onRejected)) {
+            // The serial lane only refuses new work after dispose() closed it.
+            onShutdownRejected?.();
+            onRejected?.();
+        }
+    }
+    enqueueInfrastructure(work, onRejected, onShutdownRejected) {
+        if (!this.serial.executeInfrastructure(work, {}, onRejected)) {
+            // The serial lane only refuses new work after dispose() closed it.
+            onShutdownRejected?.();
+            onRejected?.();
+        }
+    }
+    enqueueApplication(work, onRejected, onShutdownRejected) {
+        let claim;
+        try {
+            claim = this.options.claimApplicationWork?.();
+        }
+        catch (error) {
+            onRejected?.(error);
+            return;
+        }
+        if (!this.serial.executeApplication(async () => {
+            try {
+                await work();
+            }
+            finally {
+                claim?.close();
+            }
+        }, {}, () => {
+            claim?.close();
+            onRejected?.();
+        })) {
+            claim?.close();
+            // The serial lane only refuses new work after dispose() closed it.
+            onShutdownRejected?.();
+            onRejected?.();
+        }
+    }
+    /**
+     * Spec 26 §2.1/§3.1: a frame discarded because the session serial lane is
+     * closed for shutdown is recorded as `phase=dropped` with the closed
+     * reason `shutdown`. Drops are recorded from the Errors level up and are
+     * never sampled out.
+     */
+    traceShutdownDrop(header) {
+        const flowEnabled = this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true;
+        (0, diagnostics_1.flowIfEnabled)(this.options.dispatchErrors?.flow, ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped, undefined, flowEnabled ? header.flowId : undefined)?.trace({
+            outcome: ZLinkDispatchOptions_1.ZLinkRuntimeMessageFlowOutcome.Dropped,
+            surface: ZLinkDispatchOptions_1.ZLinkDispatchErrorSurface.StreamSession,
+            messageKind: streamShutdownDropMessageKind(header.kind),
+            packetName: header.name === '' ? undefined : header.name,
+            correlationId: header.correlationId,
+            sourceRid: this.context.routingId === undefined ? undefined : String(this.context.routingId),
+            flowId: flowEnabled ? header.flowId : undefined,
+            flowOrigin: flowEnabled ? header.flowOrigin : undefined,
+            errorReason: ZLinkDispatchOptions_1.ZLinkRuntimeDispatchErrorReason.Shutdown
+        });
+    }
+}
+exports.ZLinkStreamSessionRuntime = ZLinkStreamSessionRuntime;
+function streamShutdownDropMessageKind(kind) {
+    switch (kind) {
+        case protocol_1.ZLinkStreamMessageKind.Request: return ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Request;
+        case protocol_1.ZLinkStreamMessageKind.Response: return ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Response;
+        case protocol_1.ZLinkStreamMessageKind.Error: return ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Error;
+        case protocol_1.ZLinkStreamMessageKind.Control: return ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Control;
+        default: return ZLinkDispatchOptions_1.ZLinkDispatchMessageKind.Send;
+    }
+}
+class ZLinkStreamSessionNodeRuntime {
+    options;
+    sessions = new Map();
+    availablePackets = [];
+    pendingConnectionMetadata = [];
+    pendingConnectionMetadataHead = 0;
+    pendingConnectionMetadataCount = 0;
+    unaddressedMonitorSessions = [];
+    unaddressedMonitorSessionHead = 0;
+    unaddressedMonitorSessionCount = 0;
+    disconnectedEndpoints = new Set();
+    pendingEndpointlessDisconnect;
+    activityVersion = 0;
+    stopped = false;
+    receiveAbortController = new AbortController();
+    receiveLoop;
+    receiveIdleWaiter = new ZLinkStreamIdleWaiter(5);
+    receiveWorkSinceYield = 0;
+    constructor(options) {
+        this.options = options;
+    }
+    start() {
+        if (this.stopped || this.receiveLoop !== undefined) {
+            return;
+        }
+        this.options.monitor?.onEvent(event => this.onMonitorEvent(event));
+        const running = this.runReceiveLoop(this.receiveAbortController.signal)
+            .catch((error) => {
+            if (!this.stopped) {
+                this.options.onError?.(error);
+            }
+        });
+        this.receiveLoop = running;
+    }
+    markConnected(routingId, localAddr, remoteAddr) {
+        const session = this.getOrCreateSession(routingId);
+        session?.enqueueConnected(localAddr, remoteAddr);
+    }
+    markDisconnected(routingId, error) {
+        const sessionId = (0, managed_stream_1.streamSessionIdFromRoutingId)(routingId);
+        this.sessions.get(sessionId)?.enqueueDisconnected(error);
+    }
+    findSession(routingId) {
+        return this.sessions.get((0, managed_stream_1.streamSessionIdFromRoutingId)(routingId));
+    }
+    async dispose() {
+        this.stopped = true;
+        this.receiveAbortController.abort();
+        this.wakeReceiveLoop();
+        try {
+            await this.receiveLoop;
+            const sessions = [...this.sessions.values()];
+            this.sessions.clear();
+            for (const packet of this.availablePackets.splice(0))
+                packet.close();
+            this.unaddressedMonitorSessions.length = 0;
+            this.unaddressedMonitorSessionHead = 0;
+            this.unaddressedMonitorSessionCount = 0;
+            this.pendingConnectionMetadata.length = 0;
+            this.pendingConnectionMetadataHead = 0;
+            this.pendingConnectionMetadataCount = 0;
+            for (const session of sessions) {
+                await session.dispose();
+            }
+        }
+        finally {
+            this.options.readablePoller.dispose();
+        }
+    }
+    async drainCloseSessions() {
+        await Promise.allSettled([...this.sessions.values()].map((session) => session.drainClose()));
+    }
+    async runReceiveLoop(signal) {
+        while (!this.isReceiveStopped(signal)) {
+            this.drainMonitorEvents();
+            let permit;
+            let packet;
+            let packetTransferred = false;
+            try {
+                permit = await this.options.applicationJobQueue.acquire(signal);
+                if (this.isReceiveStopped(signal)) {
+                    permit.releaseAfterInternalProcessing();
+                    break;
+                }
+                if (!this.options.readablePoller.wait(0)) {
+                    permit.releaseAfterInternalProcessing();
+                    await this.waitReceiveLoopIdle();
+                    continue;
+                }
+                packet = this.takePacket();
+                if (!this.options.socket.recvPacket(packet, ZLINK_RECV_DONT_WAIT)) {
+                    permit.releaseAfterInternalProcessing();
+                    this.recyclePacket(packet);
+                    await this.waitReceiveLoopIdle();
+                    continue;
+                }
+                packetTransferred = true;
+                this.acceptPacket(packet, permit);
+                packet = undefined;
+                permit = undefined;
+            }
+            catch (error) {
+                if (!packetTransferred)
+                    permit?.releaseAfterInternalProcessing();
+                if (packet !== undefined && !packetTransferred)
+                    this.recyclePacket(packet);
+                if (!this.isReceiveStopped(signal) && !packetTransferred) {
+                    this.options.onError?.(error);
+                    this.receiveWorkSinceYield = 0;
+                    await this.waitReceiveLoopIdle();
+                }
+                else if (!this.isReceiveStopped(signal)) {
+                    this.receiveWorkSinceYield = 0;
+                    await this.waitReceiveLoopIdle();
+                }
+                continue;
+            }
+            this.receiveWorkSinceYield += 1;
+            if (this.receiveWorkSinceYield >= ZLINK_STREAM_RECEIVE_FRAME_BATCH_LIMIT
+                && !this.isReceiveStopped(signal)) {
+                this.receiveWorkSinceYield = 0;
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+    }
+    acceptPacket(packet, permit) {
+        const routingId = packet.routingId;
+        const header = packet.header;
+        const body = packet.body;
+        let releasePermitOnFailure = true;
+        let packetTransferred = false;
+        let payload;
+        let session;
+        try {
+            if (routingId === null || header === null || body === null) {
+                throw new Error('STREAM packet did not provide routing id, header, and body.');
+            }
+            this.activityVersion += 1;
+            session = this.getOrCreateSession(routingId);
+            if (session === undefined)
+                return;
+            this.applyPendingConnectionMetadata(session);
+            const decodedHeader = (0, protocol_1.decodeStreamHeader)(header.data(), this.options.dispatchErrors?.flow.flowCreationEnabled() ?? true);
+            payload = (0, stream_message_utils_1.ownedMessage)(body.data());
+            const terminalCompletion = decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Response
+                || decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Error;
+            const applicationPermit = terminalCompletion ? undefined : permit;
+            if (terminalCompletion) {
+                permit.releaseAfterInternalProcessing();
+                releasePermitOnFailure = false;
+            }
+            else {
+                if (decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Send
+                    || decodedHeader.kind === protocol_1.ZLinkStreamMessageKind.Request) {
+                    permit.markApplicationQueued();
+                }
+            }
+            const owner = {
+                close: () => this.recyclePacket(packet)
+            };
+            session.enqueuePacket(payload, decodedHeader, owner, applicationPermit);
+            releasePermitOnFailure = false;
+            payload = undefined;
+            packetTransferred = true;
+        }
+        catch (error) {
+            const failure = error instanceof Error ? error : new Error(String(error));
+            if (routingId !== null && session !== undefined) {
+                this.handleMalformedPacket(routingId, session, failure);
+            }
+            else {
+                this.options.onError?.(failure);
+                if (routingId !== null) {
+                    try {
+                        this.options.socket.disconnectPeer(routingId);
+                    }
+                    catch (disconnectError) {
+                        this.options.onError?.(disconnectError);
+                    }
+                }
+            }
+            throw failure;
+        }
+        finally {
+            if (!packetTransferred) {
+                if (releasePermitOnFailure)
+                    permit.releaseAfterInternalProcessing();
+                payload?.close();
+                this.recyclePacket(packet);
+            }
+        }
+    }
+    takePacket() {
+        return this.availablePackets.pop() ?? this.options.createPacket();
+    }
+    recyclePacket(packet) {
+        packet.close();
+        if (!this.stopped)
+            this.availablePackets.push(packet);
+    }
+    drainMonitorEvents() {
+        this.options.monitor?.drain();
+    }
+    handleMalformedPacket(routingId, session, error) {
+        this.options.onError?.(error);
+        try {
+            this.options.socket.disconnectPeer(routingId);
+        }
+        catch (disconnectError) {
+            this.options.onError?.(disconnectError);
+        }
+        session.enqueueDisconnected(error);
+    }
+    isReceiveStopped(signal) {
+        return this.stopped || signal.aborted;
+    }
+    onMonitorEvent(event) {
+        if (this.stopped) {
+            return;
+        }
+        switch (event.nativeEvent) {
+            case internal_event_contracts_1.ZLinkSocketNativeEventType.ConnectionReady:
+                this.activityVersion += 1;
+                {
+                    const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
+                    if (this.disconnectedEndpoints.delete(endpointKey)) {
+                        return;
+                    }
+                }
+                if (event.routingId === undefined) {
+                    const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
+                    const unaddressed = this.firstUnaddressedSession();
+                    if (unaddressed !== undefined) {
+                        this.disconnectedEndpoints.delete(endpointKey);
+                        unaddressed.enqueueConnected(event.localAddr, event.remoteAddr);
+                        this.enqueueUnaddressedMonitorSession(unaddressed.stream.sessionId);
+                        return;
+                    }
+                    if (this.hasPendingConnectionMetadata(endpointKey)) {
+                        return;
+                    }
+                    this.pendingConnectionMetadata.push({
+                        localAddr: event.localAddr,
+                        remoteAddr: event.remoteAddr
+                    });
+                    this.pendingConnectionMetadataCount += 1;
+                    return;
+                }
+                this.getOrCreateSession(event.routingId)?.enqueueConnected(event.localAddr, event.remoteAddr);
+                return;
+            case internal_event_contracts_1.ZLinkSocketNativeEventType.Disconnected:
+                {
+                    const endpointKey = streamMonitorEndpointKey(event.localAddr, event.remoteAddr);
+                    this.disconnectedEndpoints.add(endpointKey);
+                    this.removePendingConnectionMetadata(endpointKey);
+                    const session = this.resolveMonitorSession(event);
+                    const error = new Error(`Stream disconnected: ${event.nativeEvent}/${event.value}`);
+                    if (session !== undefined) {
+                        session.enqueueDisconnected(error);
+                        return;
+                    }
+                    if (event.routingId === undefined
+                        && !streamMonitorHasEndpoint(event)) {
+                        this.enqueueEndpointlessDisconnect(error);
+                    }
+                }
+                return;
+            default:
+                return;
+        }
+    }
+    applyPendingConnectionMetadata(session) {
+        if (session.stream.localAddr !== undefined
+            || session.stream.remoteAddr !== undefined
+            || this.pendingConnectionMetadataCount === 0) {
+            return;
+        }
+        const metadata = this.takePendingConnectionMetadata();
+        if (metadata === undefined)
+            return;
+        this.removePendingConnectionMetadata(streamMonitorEndpointKey(metadata.localAddr, metadata.remoteAddr));
+        session.enqueueConnected(metadata.localAddr, metadata.remoteAddr);
+        this.enqueueUnaddressedMonitorSession(session.stream.sessionId);
+    }
+    hasPendingConnectionMetadata(endpointKey) {
+        for (let index = this.pendingConnectionMetadataHead; index < this.pendingConnectionMetadata.length; index += 1) {
+            const metadata = this.pendingConnectionMetadata[index];
+            if (metadata !== undefined
+                && streamMonitorEndpointKey(metadata.localAddr, metadata.remoteAddr) === endpointKey) {
+                return true;
+            }
+        }
+        return false;
+    }
+    takePendingConnectionMetadata() {
+        while (this.pendingConnectionMetadataHead < this.pendingConnectionMetadata.length
+            && this.pendingConnectionMetadata[this.pendingConnectionMetadataHead] === undefined) {
+            this.pendingConnectionMetadataHead += 1;
+        }
+        const metadata = this.pendingConnectionMetadata[this.pendingConnectionMetadataHead];
+        if (metadata === undefined)
+            return undefined;
+        this.pendingConnectionMetadata[this.pendingConnectionMetadataHead] = undefined;
+        this.pendingConnectionMetadataHead += 1;
+        this.pendingConnectionMetadataCount -= 1;
+        this.compactPendingConnectionMetadata();
+        return metadata;
+    }
+    compactPendingConnectionMetadata() {
+        if (this.pendingConnectionMetadataCount === 0) {
+            this.pendingConnectionMetadata.length = 0;
+            this.pendingConnectionMetadataHead = 0;
+        }
+        else if (this.pendingConnectionMetadataHead >= 1024
+            && this.pendingConnectionMetadataHead * 2 >= this.pendingConnectionMetadata.length) {
+            this.pendingConnectionMetadata.splice(0, this.pendingConnectionMetadataHead);
+            this.pendingConnectionMetadataHead = 0;
+        }
+    }
+    enqueueUnaddressedMonitorSession(sessionId) {
+        this.unaddressedMonitorSessions.push(sessionId);
+        this.unaddressedMonitorSessionCount += 1;
+    }
+    takeUnaddressedMonitorSession() {
+        while (this.unaddressedMonitorSessionHead < this.unaddressedMonitorSessions.length
+            && this.unaddressedMonitorSessions[this.unaddressedMonitorSessionHead] === undefined) {
+            this.unaddressedMonitorSessionHead += 1;
+        }
+        const sessionId = this.unaddressedMonitorSessions[this.unaddressedMonitorSessionHead];
+        if (sessionId === undefined)
+            return undefined;
+        this.unaddressedMonitorSessions[this.unaddressedMonitorSessionHead] = undefined;
+        this.unaddressedMonitorSessionHead += 1;
+        this.unaddressedMonitorSessionCount -= 1;
+        if (this.unaddressedMonitorSessionCount === 0) {
+            this.unaddressedMonitorSessions.length = 0;
+            this.unaddressedMonitorSessionHead = 0;
+        }
+        else if (this.unaddressedMonitorSessionHead >= 1024
+            && this.unaddressedMonitorSessionHead * 2 >= this.unaddressedMonitorSessions.length) {
+            this.unaddressedMonitorSessions.splice(0, this.unaddressedMonitorSessionHead);
+            this.unaddressedMonitorSessionHead = 0;
+        }
+        return sessionId;
+    }
+    firstUnaddressedSession() {
+        for (const session of this.sessions.values()) {
+            if (!session.isDisconnected
+                && session.stream.localAddr === undefined
+                && session.stream.remoteAddr === undefined) {
+                return session;
+            }
+        }
+        return undefined;
+    }
+    getActiveSession(sessionId) {
+        const session = this.sessions.get(sessionId);
+        if (session === undefined || session.isDisconnected) {
+            return undefined;
+        }
+        return session;
+    }
+    removePendingConnectionMetadata(endpointKey) {
+        for (let index = this.pendingConnectionMetadataHead; index < this.pendingConnectionMetadata.length; index += 1) {
+            const metadata = this.pendingConnectionMetadata[index];
+            if (metadata === undefined)
+                continue;
+            if (streamMonitorEndpointKey(metadata.localAddr, metadata.remoteAddr) === endpointKey) {
+                this.pendingConnectionMetadata[index] = undefined;
+                this.pendingConnectionMetadataCount -= 1;
+            }
+        }
+        this.compactPendingConnectionMetadata();
+    }
+    resolveMonitorSession(event) {
+        if (event.routingId !== undefined) {
+            const session = this.getActiveSession((0, managed_stream_1.streamSessionIdFromRoutingId)(event.routingId));
+            if (session !== undefined) {
+                return session;
+            }
+        }
+        if (streamMonitorHasEndpoint(event)) {
+            let match;
+            let matchCount = 0;
+            for (const session of this.sessions.values()) {
+                if (session.isDisconnected
+                    || session.stream.localAddr !== event.localAddr
+                    || session.stream.remoteAddr !== event.remoteAddr) {
+                    continue;
+                }
+                match = session;
+                matchCount += 1;
+                if (matchCount > 1)
+                    return undefined;
+            }
+            return matchCount === 1 ? match : undefined;
+        }
+        return undefined;
+    }
+    enqueueEndpointlessDisconnect(error) {
+        const sessionId = this.takeUnaddressedMonitorSession();
+        if (sessionId !== undefined) {
+            this.getActiveSession(sessionId)?.enqueueDisconnected(error);
+            return;
+        }
+        let session;
+        let activeCount = 0;
+        for (const candidate of this.sessions.values()) {
+            if (candidate.isDisconnected)
+                continue;
+            session = candidate;
+            activeCount += 1;
+            if (activeCount > 1)
+                return;
+        }
+        if (activeCount !== 1 || session === undefined) {
+            return;
+        }
+        if (this.pendingEndpointlessDisconnect !== undefined) {
+            this.pendingEndpointlessDisconnect.cancelled = true;
+        }
+        const pending = {
+            session,
+            cancelled: false,
+            error,
+            activityVersion: this.activityVersion
+        };
+        this.pendingEndpointlessDisconnect = pending;
+        // A pending endpointless disconnect must yield to a recv that is already
+        // queued. Wake the recv loop instead of waiting for its idle backoff.
+        this.wakeReceiveLoop();
+        setImmediate(() => {
+            if (pending.cancelled
+                || this.stopped
+                || this.pendingEndpointlessDisconnect !== pending
+                || this.activityVersion !== pending.activityVersion
+                || this.sessions.get(pending.session.stream.sessionId) !== pending.session) {
+                return;
+            }
+            this.pendingEndpointlessDisconnect = undefined;
+            pending.session.enqueueDisconnected(pending.error);
+        });
+    }
+    waitReceiveLoopIdle() {
+        return this.receiveIdleWaiter.wait();
+    }
+    wakeReceiveLoop() {
+        this.receiveIdleWaiter.wake();
+    }
+    getOrCreateSession(routingId) {
+        const sessionId = (0, managed_stream_1.streamSessionIdFromRoutingId)(routingId);
+        const existing = this.getActiveSession(sessionId);
+        if (existing !== undefined) {
+            return existing;
+        }
+        if (this.options.acceptNewSession?.() === false) {
+            const rejected = new managed_stream_1.ZLinkManagedStream(this.options.socket, routingId, this.options.messageSerializers, this.options.nativeSessionService, this.options.meshCompletions, undefined, this.options.nativeSessionRouteForMesh);
+            void rejected.closeForDrain().catch((error) => this.options.onError?.(error));
+            return undefined;
+        }
+        const created = new ZLinkStreamSessionRuntime(this.options, routingId, (sessionId, session) => {
+            if (this.sessions.get(sessionId) === session) {
+                this.sessions.delete(sessionId);
+            }
+        });
+        this.sessions.set(sessionId, created);
+        return created;
+    }
+}
+exports.ZLinkStreamSessionNodeRuntime = ZLinkStreamSessionNodeRuntime;
+function streamMonitorEndpointKey(localAddr, remoteAddr) {
+    return `${localAddr ?? ''}\n${remoteAddr ?? ''}`;
+}
+function streamMonitorHasEndpoint(event) {
+    const endpoint = event;
+    return endpoint.localAddr !== undefined || endpoint.remoteAddr !== undefined;
+}
+function isPromiseLike(value) {
+    return typeof value.then === 'function';
+}
+function normalizeStreamCloseReason(reason) {
+    switch (reason) {
+        case 'client_close':
+        case 'idle_timeout':
+        case 'heartbeat_timeout':
+        case 'protocol_error':
+            return reason;
+        case 'server_shutdown':
+        case 'server_drain':
+            return 'server_shutdown';
+        default:
+            return 'transport_error';
+    }
+}