@zlink-systems/stream-connector 0.16.0 → 0.18.0

package/dist/browser/Contracts/Calls/ZlinkStreamCalls.d.ts

@@ -28,8 +28,14 @@ export interface ZlinkStreamExpectNoneCall<TPayload = ZlinkStreamEncodedPayload>
     within(windowMs: number): ZlinkStreamExpectNoneCall<TPayload>;
     run(signal?: AbortSignal): Promise<void>;
 }
+/**
+ * Spec stream-connector 32 §10.1: the predicates and the returned values are
+ * messages, not payloads. A payload-only predicate cannot read the packet name
+ * or the metadata, so `TPayload` is the type of the payload the message carries
+ * and never the value handed to `expect(...)`.
+ */
 export interface ZlinkStreamSequenceCall<TPayload = ZlinkStreamEncodedPayload> {
-    expect(predicate: (payload: TPayload) => boolean): ZlinkStreamSequenceCall<TPayload>;
+    expect(predicate: (message: ZlinkStreamMessage<TPayload>) => boolean): ZlinkStreamSequenceCall<TPayload>;
     timeout(timeoutMs: number): ZlinkStreamSequenceCall<TPayload>;
-    run(signal?: AbortSignal): Promise<readonly TPayload[]>;
+    run(signal?: AbortSignal): Promise<readonly ZlinkStreamMessage<TPayload>[]>;
 }

package/dist/browser/Contracts/IZlinkStreamConnector.d.ts

@@ -22,6 +22,21 @@ export interface ZlinkStreamConnector {
      * with {@link import('./ZlinkStreamEnums').ZlinkStreamErrorCode.ConfigurationError}.
      */
     setDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel): void;
+    /**
+     * Asynchronous counterpart of {@link setDiagnosticsLevel} (spec
+     * stream-connector 32 §13). Both surfaces change the same value, and this
+     * one never replaces the synchronous surface: the synchronous call does not
+     * wait for a completion, so a caller whose idiom is an awaited completion
+     * uses this one instead. Rejects unknown values the same way.
+     */
+    setDiagnosticsLevelAsync(level: ZlinkStreamDiagnosticsLevel): Promise<void>;
+    /**
+     * Number of packets received under `name` on the current connection (spec
+     * stream-connector 32 §10). Counts arrivals, so consuming a message through
+     * a handler or a wait surface never lowers it, and the dispatch mode does
+     * not change it. Restarts at 0 every time a connection is established.
+     */
+    receivedCount(name: string): number;
     onErrorReceived(handler: (error: ZlinkStreamError, signal?: AbortSignal) => Promise<void> | void): Disposable;
     onDisconnected(handler: (signal?: AbortSignal) => Promise<void> | void): Disposable;
     onConnectionStateChanged(handler: (change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal) => Promise<void> | void): Disposable;
@@ -31,7 +46,13 @@ export interface ZlinkStreamConnector {
     send(payload: unknown, messageType?: Function): ZlinkStreamSendCall;
     request(payload: unknown, messageType?: Function): ZlinkStreamRequestCall;
     on<TPayload = ZlinkStreamEncodedPayload>(name: string, handler: (message: ZlinkStreamMessage<TPayload>, signal?: AbortSignal) => Promise<void> | void, messageType?: Function): Disposable;
-    waitFor<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamWaitCall<TPayload>;
-    expectNone<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamExpectNoneCall<TPayload>;
-    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamSequenceCall<TPayload>;
+    /**
+     * Wait surfaces (spec stream-connector 32 §10.1). Each takes the packet name
+     * the caller states explicitly, or the payload constructor the options'
+     * `nameResolver` turns into that name — TypeScript types are erased at
+     * runtime, so the type-driven path takes a constructor value.
+     */
+    waitFor<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamWaitCall<TPayload>;
+    expectNone<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamExpectNoneCall<TPayload>;
+    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamSequenceCall<TPayload>;
 }

package/dist/browser/Contracts/ZlinkStreamConnectorOptions.d.ts

@@ -16,7 +16,6 @@ export interface ZlinkStreamConnectorOptions {
     readonly compression?: ZlinkStreamCompression;
     readonly compressionCodec?: ZlinkStreamCompressionCodec;
     readonly nameResolver?: ZlinkStreamPacketNameResolver;
-    readonly meterProvider?: ZlinkStreamMeterProvider;
     /**
      * Initial diagnostics level (spec 26 §4); defaults to
      * {@link ZlinkStreamDiagnosticsLevel.Errors}, which preserves the current
@@ -27,20 +26,6 @@ export interface ZlinkStreamConnectorOptions {
      */
     readonly diagnosticsLevel?: ZlinkStreamDiagnosticsLevel;
 }
-export interface ZlinkStreamMeterProvider {
-    getMeter(name: string): {
-        createCounter(name: string, options?: {
-            readonly unit?: string;
-        }): {
-            add(value: number, attributes?: Readonly<Record<string, string | number | boolean>>): void;
-        };
-        createHistogram(name: string, options?: {
-            readonly unit?: string;
-        }): {
-            record(value: number, attributes?: Readonly<Record<string, string | number | boolean>>): void;
-        };
-    };
-}
 export interface ZlinkStreamHeartbeatOptions {
     readonly enabled?: boolean;
     readonly intervalMs?: number;
@@ -51,7 +36,11 @@ export interface ZlinkStreamReconnectOptions {
     readonly initialDelayMs?: number;
     readonly maxDelayMs?: number;
     readonly backoffFactor?: number;
-    readonly maxAttempts?: number;
+    /**
+     * `null` means unlimited (spec stream-connector 32 §6: the option has to be
+     * able to say "keep trying"); any other value must be a positive number.
+     */
+    readonly maxAttempts?: number | null;
 }
 export interface ZlinkStreamPacketNameResolver {
     resolve(payloadType: Function): string;
@@ -88,6 +77,5 @@ export interface RequiredZlinkStreamConnectorOptions {
     readonly nameResolver: ZlinkStreamPacketNameResolver;
     readonly transportFactory: ZlinkStreamTransportFactory;
     readonly codec?: ZlinkStreamPayloadCodec;
-    readonly meterProvider?: ZlinkStreamMeterProvider;
     readonly diagnosticsLevel: ZlinkStreamDiagnosticsLevel;
 }

package/dist/browser/Runtime/Calls/ZlinkStreamObservationBuilders.d.ts

@@ -21,9 +21,9 @@ export declare class ZlinkStreamSequenceBuilder<TPayload> implements ZlinkStream
     private timeoutMs;
     private executed;
     constructor(connector: ZlinkStreamMessageWaiter, name: string);
-    expect(predicate: (payload: TPayload) => boolean): this;
+    expect(predicate: (message: ZlinkStreamMessage<TPayload>) => boolean): this;
     timeout(timeoutMs: number): this;
-    run(signal?: AbortSignal): Promise<readonly TPayload[]>;
+    run(signal?: AbortSignal): Promise<readonly ZlinkStreamMessage<TPayload>[]>;
     private ensureConfigurable;
     private markExecuted;
 }

package/dist/browser/Runtime/ZlinkStreamConnector.d.ts

@@ -16,6 +16,14 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
     get closeReason(): import("..").ZlinkStreamCloseReason | undefined;
     get state(): ZlinkStreamConnectionState;
     get pendingDispatchCount(): number;
+    /**
+     * Spec stream-connector 32 §10: how many packets carrying `name` arrived on
+     * the current connection. Arrivals are what is counted, so a message a
+     * handler dispatched or a wait surface consumed still counts, and `Manual`
+     * and `Immediate` report the same number. Establishing a connection resets
+     * the count to 0, a reconnect included.
+     */
+    receivedCount(name: string): number;
     /**
      * Current diagnostics level (spec 26 §4.1, spec stream-connector 32 §13).
      * Reflects the level set by the most recent {@link setDiagnosticsLevel}
@@ -29,10 +37,16 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
      * state update: it applies to processing points that read the level after
      * this call returns and is never applied retroactively to frames already
      * built. Rejects unknown values with {@link ZlinkStreamErrorCode.ConfigurationError}.
-     * Do not call this synchronous bridge from a framework execution context such
-     * as a handler or callback; use setDiagnosticsLevelAsync there.
+     * Spec stream-connector 32 §13: this surface changes the value without
+     * waiting for anything; it is not a blocking call over the asynchronous pair,
+     * which a receive callback would otherwise make wait for its own completion.
      */
     setDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel): void;
+    /**
+     * Asynchronous counterpart of {@link setDiagnosticsLevel} (spec
+     * stream-connector 32 §13). It changes the same value; awaiting it is how a
+     * caller observes the change, and it never replaces the synchronous surface.
+     */
     setDiagnosticsLevelAsync(level: ZlinkStreamDiagnosticsLevel): Promise<void>;
     onErrorReceived(handler: (error: ZlinkStreamError, signal?: AbortSignal) => Promise<void> | void): Disposable;
     onDisconnected(handler: (signal?: AbortSignal) => Promise<void> | void): Disposable;
@@ -43,9 +57,16 @@ export declare class DefaultZlinkStreamConnector implements ZlinkStreamConnector
     send(payload: unknown, messageType?: Function): ZlinkStreamSendCall;
     request(payload: unknown, messageType?: Function): ZlinkStreamRequestCall;
     on<TPayload = ZlinkStreamEncodedPayload>(name: string, handler: (message: ZlinkStreamMessage<TPayload>, signal?: AbortSignal) => Promise<void> | void, messageType?: Function): Disposable;
-    waitFor<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamWaitCall<TPayload>;
-    expectNone<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamExpectNoneCall<TPayload>;
-    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamSequenceCall<TPayload>;
+    waitFor<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamWaitCall<TPayload>;
+    expectNone<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamExpectNoneCall<TPayload>;
+    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(nameOrType: string | Function): ZlinkStreamSequenceCall<TPayload>;
+    /**
+     * Spec stream-connector 32 §10.1: each wait surface offers both ways of
+     * naming a packet. A string is the name the caller states; a constructor
+     * goes through the options' `nameResolver`, which is the same resolver
+     * `send` and `request` use, so both paths land on one name for one type.
+     */
+    private observedName;
     waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
     private encodePayload;
     private decodePayload;

package/dist/browser/Runtime/ZlinkStreamConnectorLifecycle.d.ts

@@ -6,7 +6,6 @@ import type { ZlinkStreamFrameSender } from './ZlinkStreamFrameSender';
 import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
 import type { ZlinkStreamReceiveDispatcher } from './ZlinkStreamReceiveDispatcher';
 import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
-import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
 export declare class ZlinkStreamConnectorLifecycle {
     private readonly options;
     private readonly pendingRequests;
@@ -14,7 +13,6 @@ export declare class ZlinkStreamConnectorLifecycle {
     private readonly receiveDispatcher;
     private readonly receivedMessages;
     private readonly events;
-    private readonly metrics;
     private receiveLoopAbort;
     private receiveLoopSleeping;
     private receiveLoopWake;
@@ -23,6 +21,7 @@ export declare class ZlinkStreamConnectorLifecycle {
     private connectionGeneration;
     private currentState;
     private heartbeatTimer;
+    private heartbeatTickRunning;
     private lastInboundAt;
     private closeTask;
     private connectTask;
@@ -31,7 +30,7 @@ export declare class ZlinkStreamConnectorLifecycle {
     private disconnectedPublished;
     private closeReasonValue?;
     private lateConnectCleanupError;
-    constructor(options: RequiredZlinkStreamConnectorOptions, pendingRequests: ZlinkStreamPendingRequests, frameSender: ZlinkStreamFrameSender, receiveDispatcher: ZlinkStreamReceiveDispatcher, receivedMessages: ZlinkStreamReceivedMessages, events: ZlinkStreamConnectorEvents, metrics: ZlinkStreamRuntimeMetrics);
+    constructor(options: RequiredZlinkStreamConnectorOptions, pendingRequests: ZlinkStreamPendingRequests, frameSender: ZlinkStreamFrameSender, receiveDispatcher: ZlinkStreamReceiveDispatcher, receivedMessages: ZlinkStreamReceivedMessages, events: ZlinkStreamConnectorEvents);
     get isConnected(): boolean;
     get state(): ZlinkStreamConnectionState;
     get closeReason(): ZlinkStreamCloseReason | undefined;
@@ -65,8 +64,46 @@ export declare class ZlinkStreamConnectorLifecycle {
     private runHeartbeatTick;
     private disconnectForTransportFailure;
     private isCurrentConnection;
-    private disconnectOnce;
+    /** Transport teardown only — no application callback runs from here. */
+    private tearDownConnection;
+    /**
+     * Runs once the teardown promise has settled, so a handler reached from here
+     * may call `connect` without waiting for a task its own caller still holds.
+     * The reconnect is queued before the notification is awaited for the same
+     * reason: spec stream-connector 32 §6 has reconnect on by default, and a
+     * handler that is slow — or whose promise never settles at all — must not
+     * cost the connector the attempt. The state is already `Disconnected` and the
+     * state handlers are already invoked by the time the queued microtask runs,
+     * because `setState` records the state and hands the change to the handlers
+     * before it awaits any of them.
+     */
+    private announceDisconnect;
     private shouldReconnect;
+    private claimDisconnectedPublish;
     private publishDisconnectedOnce;
+    /**
+     * Spec stream-connector 32 §7: the connector runs the registered handler, it
+     * does not wait for it to finish. `close` returns once its own work is done —
+     * the drain, the transport close, the pending requests — having run the
+     * disconnect handler but without looking at whether that handler has ended.
+     *
+     * Starting the publish without awaiting it still runs every handler right
+     * here: an `async` function body runs synchronously up to its first `await`,
+     * and `publishDisconnected` reaches each handler before that point. So the
+     * handler has run by the time `close` returns, which is what the spec asks
+     * for, while a handler that calls `close` no longer waits for the very
+     * `closeTask` it is running inside. Java and C++ hand the handler to a queue
+     * and return the same way.
+     *
+     * `claimDisconnectedPublish` is taken by the same call and before any await,
+     * so deferring the completion never turns the one notification into two.
+     *
+     * Nothing awaits the promise, so a rejection would reach the process as an
+     * unhandled rejection and kill it. Handler failures are already contained
+     * where they were before this call stopped waiting — the `Promise.allSettled`
+     * in `publishDisconnected` — and this `catch` covers what is left rather than
+     * reporting the same failure a second time on the error surface.
+     */
+    private publishDisconnectedWithoutWaiting;
     private setState;
 }

package/dist/browser/Runtime/ZlinkStreamConnectorOptions.d.ts

@@ -1,3 +1,17 @@
-import { RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel } from '../Contracts';
+import { RequiredZlinkStreamConnectorOptions, ZlinkStreamConnectorOptions, ZlinkStreamDiagnosticsLevel, ZlinkStreamPacketNameResolver } from '../Contracts';
 export declare function normalizeOptions(options: ZlinkStreamConnectorOptions, defaultTransportFactory: RequiredZlinkStreamConnectorOptions['transportFactory']): RequiredZlinkStreamConnectorOptions;
+/**
+ * Spec stream-connector 32 §5 and the TypeScript projection §4: a payload type
+ * carries its packet name in a static `packetName` member, and that name wins
+ * over the type's own name.
+ *
+ * The `name` fallback is a convenience for a type that declares nothing, and it
+ * is NOT trustworthy in a browser build: a minifier renames the constructor, so
+ * the same type produces a different packet name after a build setting changes
+ * and the server stops finding the handler — exactly the "name that changes
+ * with the build environment" §5 forbids. A payload type that crosses the wire
+ * declares `static readonly packetName`; leaving it out is only safe while the
+ * bundle keeps class names.
+ */
+export declare const defaultPacketNameResolver: ZlinkStreamPacketNameResolver;
 export declare function validateDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel | undefined): void;

package/dist/browser/Runtime/ZlinkStreamFrameSender.d.ts

@@ -1,13 +1,11 @@
 import type { ZlinkStreamConnection, ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMetadata, ZlinkStreamMessageKind } from '../Contracts';
 import type { ZlinkStreamFrameProtocol } from './Protocol/ZlinkStreamFrameProtocol';
 import type { ZlinkFlowContext } from './ZlinkFlowContext';
-import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
 export declare class ZlinkStreamFrameSender {
     private readonly protocol;
     private readonly flowContext;
-    private readonly metrics;
     private readonly pendingWrites;
-    constructor(protocol: ZlinkStreamFrameProtocol, flowContext: ZlinkFlowContext, metrics: ZlinkStreamRuntimeMetrics);
+    constructor(protocol: ZlinkStreamFrameProtocol, flowContext: ZlinkFlowContext);
     send(connection: ZlinkStreamConnection, kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, correlationId?: string, explicitFlow?: ZlinkStreamFlow): Promise<void>;
     sendControl(connection: ZlinkStreamConnection, name: string, signal?: AbortSignal): Promise<void>;
     drain(signal?: AbortSignal): Promise<void>;

package/dist/browser/Runtime/ZlinkStreamReceiveDispatcher.d.ts

@@ -6,7 +6,6 @@ import type { ZlinkStreamPendingRequests } from './ZlinkStreamPendingRequests';
 import type { ZlinkStreamReceivedMessages } from './ZlinkStreamReceivedMessages';
 import type { ZlinkFlowContext } from './ZlinkFlowContext';
 import type { ZlinkStreamCloseReason } from '../Contracts';
-import type { ZlinkStreamRuntimeMetrics } from './ZlinkStreamRuntimeMetrics';
 export interface ZlinkStreamReceiveResult {
     readonly available: boolean;
     readonly inbound: boolean;
@@ -18,10 +17,22 @@ export declare class ZlinkStreamReceiveDispatcher {
     private readonly frameSender;
     private readonly events;
     private readonly flowContext;
-    private readonly metrics;
     private readonly serverClosing?;
-    constructor(protocol: ZlinkStreamFrameProtocol, pendingRequests: ZlinkStreamPendingRequests, receivedMessages: ZlinkStreamReceivedMessages, frameSender: ZlinkStreamFrameSender, events: ZlinkStreamConnectorEvents, flowContext: ZlinkFlowContext, metrics: ZlinkStreamRuntimeMetrics, serverClosing?: ((reason: ZlinkStreamCloseReason) => Promise<void>) | undefined);
-    readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean): Promise<ZlinkStreamReceiveResult>;
+    constructor(protocol: ZlinkStreamFrameProtocol, pendingRequests: ZlinkStreamPendingRequests, receivedMessages: ZlinkStreamReceivedMessages, frameSender: ZlinkStreamFrameSender, events: ZlinkStreamConnectorEvents, flowContext: ZlinkFlowContext, serverClosing?: ((reason: ZlinkStreamCloseReason) => Promise<void>) | undefined);
+    /**
+     * @param isCurrent Tells whether the connection this batch was read from is
+     *   still the connector's connection. It is asked again at the head of every
+     *   frame, not only after the read: `dispatch` awaits application code —
+     *   registered handlers in `Immediate`, the error handler on a failed frame —
+     *   and a disconnect and reconnect can complete inside that await. Without
+     *   the recheck the rest of a dead connection's batch lands on the new
+     *   connection's state, and the §10 arrival counts, which start at 0 when a
+     *   connection is established, take the stale frames on top.
+     * @param connectionForSend Resolves the connection a reply belongs on at the
+     *   moment it is written. The captured `connection` is the one the batch was
+     *   read from, which a reconnect may already have replaced.
+     */
+    readAndDispatch(connection: ZlinkStreamConnection | undefined, signal?: AbortSignal, isCurrent?: () => boolean, connectionForSend?: () => ZlinkStreamConnection): Promise<ZlinkStreamReceiveResult>;
     private dispatch;
     private dispatchControl;
 }

package/dist/browser/Runtime/ZlinkStreamReceivedMessages.d.ts

@@ -16,6 +16,8 @@ export declare class ZlinkStreamReceivedMessages {
     private queueHead;
     private queuedCount;
     private drainTask;
+    private draining;
+    private readonly receivedCounts;
     /**
      * @param deliverOnArrival `Immediate` runs registered handlers on the receive
      *   path; `Manual` leaves them queued until {@link pump} runs them on the
@@ -31,12 +33,50 @@ export declare class ZlinkStreamReceivedMessages {
      * `Manual` needs no dispatch pump to complete a wait. The queue is scanned in
      * a microtask so a message that arrived before the wait started is still
      * observed, and so the caller has its subscription in hand by then.
+     *
+     * @param onConnectionEnded Called, instead of {@link observer}, when
+     *   {@link resetForNewConnection} abandons this registration because the
+     *   connection it was watching ended before a message matched (spec
+     *   stream-connector 32 §10.1: "연결이 끝나 대기를 이어갈 수 없으면
+     *   `Disconnected`다").
      */
-    observe(name: string, observer: EncodedMessageObserver): Disposable;
+    observe(name: string, observer: EncodedMessageObserver, onConnectionEnded: () => void): Disposable;
+    /** Spec stream-connector 32 §10: arrivals under `name` on this connection. */
+    receivedCount(name: string): number;
+    /**
+     * Rebaselines the queue for a connection that was just established. Spec
+     * stream-connector 32 §10 (line ~649): the reference point is the moment a
+     * connection is established, so counts restart at 0 and whatever the
+     * previous connection left unconsumed goes with it — keeping the queue
+     * while only the counts reset would let counts and queue describe two
+     * different connections, and let `waitFor` hand back a packet from before
+     * the drop as if the new connection had delivered it.
+     *
+     * `ZlinkStreamMessage`/`ZlinkStreamEncodedPayload` are plain data (name,
+     * metadata, a `Uint8Array` payload) with no dispose/close of their own —
+     * unlike Java's queued frames, which `closeMessage` releases — so dropping
+     * the queue's references is the whole of the release here.
+     *
+     * @param replacesAnEarlierConnection False for the very first connection:
+     *   there is no earlier queue or wait to abandon yet. True for a reconnect,
+     *   which also fails every wait surface still registered from the
+     *   connection that just ended with `Disconnected` (Java
+     *   `ZLinkStreamDispatchQueue.resetForNewConnection` parity) — that
+     *   registration was watching a queue this call just discarded, so letting
+     *   it keep watching would silently rebind it to the new connection.
+     */
+    resetForNewConnection(replacesAnEarlierConnection: boolean): void;
     enqueue(message: ZlinkStreamMessage<ZlinkStreamEncodedPayload>, signal?: AbortSignal): void;
     /**
      * Runs the registered handlers the receive path left queued. `Manual` calls
      * this from `dispatch`; `Immediate` has already drained on arrival.
+     *
+     * A handler that calls `dispatch` arrives back here from inside the drain it
+     * was started by. `scheduleDrain` would find `drainTask` already set and
+     * return, and the await below would then be the drain waiting on itself —
+     * a deadlock with neither timeout nor error. The drain loop already takes
+     * every message a handler exists for, so there is nothing a second drain
+     * would deliver and returning is the whole of the correct behaviour.
      */
     pump(): Promise<void>;
     private offerQueued;

package/dist/browser/index.d.ts

@@ -1,8 +1,13 @@
 export * from './Contracts';
-export { DefaultZlinkStreamConnector, } from './Runtime/ZlinkStreamConnector';
 export { zlinkStreamAssert } from './Runtime/ZlinkStreamAssertions';
-import { DefaultZlinkStreamConnector } from './Runtime/ZlinkStreamConnector';
-import type { ZlinkStreamConnectorOptions } from './Contracts';
+import type { ZlinkStreamConnector, ZlinkStreamConnectorOptions } from './Contracts';
+/**
+ * The only way to build a connector (TypeScript spec §4). The concrete class
+ * stays inside the package — the other four connectors hide their
+ * implementation type as well, and a consumer that named it here would depend
+ * on a shape no spec fixes. `create` validates every option before it returns
+ * and throws `ZlinkStreamException` when one is rejected (common spec §6.3).
+ */
 export declare const zlinkStreamConnectorFactory: {
-    create(options: ZlinkStreamConnectorOptions): DefaultZlinkStreamConnector;
+    create(options: ZlinkStreamConnectorOptions): ZlinkStreamConnector;
 };