@zlink-systems/stream-connector 0.17.0 → 0.18.1

package/dist/browser/index.mjs

@@ -659,6 +659,53 @@ function utf8Decode2(value) {
   return new TextDecoder().decode(value);
 }
 
+// packages/stream-connector/src/Runtime/ZlinkStreamAssertions.ts
+var zlinkStreamAssert = {
+  ensure(condition, message) {
+    if (typeof message !== "string" || message.trim().length === 0) {
+      throw connectorError("validationFailed" /* ValidationFailed */, "zlinkStreamAssert.ensure requires a non-empty diagnostic message.");
+    }
+    if (!condition) {
+      throw connectorError("validationFailed" /* ValidationFailed */, message);
+    }
+  },
+  async expectFailure(action, errorKind) {
+    let failure;
+    try {
+      await action();
+    } catch (error) {
+      failure = error;
+    }
+    if (failure === void 0) {
+      throw connectorError("validationFailed" /* ValidationFailed */, "Expected action to fail.");
+    }
+    const streamError = unwrapStreamError(failure);
+    if (errorKind !== void 0 && streamError.code !== errorKind) {
+      throw connectorError(
+        "validationFailed" /* ValidationFailed */,
+        `Expected failure kind '${errorKind}', got '${streamError.code}'.`,
+        failure
+      );
+    }
+    return streamError;
+  },
+  async expectTimeout(action) {
+    let failure;
+    try {
+      await action();
+    } catch (error) {
+      failure = error;
+    }
+    if (failure === void 0) {
+      throw connectorError("validationFailed" /* ValidationFailed */, "Expected action to time out.");
+    }
+    const code = unwrapStreamError(failure).code;
+    if (code !== "requestTimeout" /* RequestTimeout */ && code !== "connectTimeout" /* ConnectTimeout */) {
+      throw failure;
+    }
+  }
+};
+
 // packages/stream-connector/src/Runtime/Protocol/ZlinkStreamPacketNameValidator.ts
 function validateName(name, allowReserved = false) {
   if (name.length === 0) {
@@ -814,14 +861,17 @@ var ZlinkStreamWaitBuilder = class {
     this.timeoutMs = timeoutMs;
     return this;
   }
-  submit(signal) {
+  async submit(signal) {
     this.markExecuted();
-    return this.connector.waitForMessage(
-      this.name,
-      this.timeoutMs ?? this.connector.options.waitTimeoutMs,
-      this.predicate,
-      signal
-    );
+    const timeoutMs = this.timeoutMs ?? this.connector.options.waitTimeoutMs;
+    const message = await this.connector.waitForMessage(this.name, timeoutMs, this.predicate, signal);
+    if (message === void 0) {
+      throw connectorError(
+        "validationFailed" /* ValidationFailed */,
+        `No '${this.name}' message arrived within ${timeoutMs}ms.`
+      );
+    }
+    return message;
   }
   ensureConfigurable() {
     if (this.executed) {
@@ -853,13 +903,9 @@ var ZlinkStreamExpectNoneBuilder = class {
     if (this.windowMs === void 0) {
       throw connectorError("validationFailed" /* ValidationFailed */, "expectNone requires within(windowMs).");
     }
-    try {
-      await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
-    } catch (error) {
-      if (unwrapStreamError(error).code === "requestTimeout" /* RequestTimeout */) {
-        return;
-      }
-      throw error;
+    const message = await this.connector.waitForMessage(this.name, this.windowMs, () => true, signal);
+    if (message === void 0) {
+      return;
     }
     throw connectorError(
       "validationFailed" /* ValidationFailed */,
@@ -895,6 +941,9 @@ var ZlinkStreamSequenceBuilder = class {
     this.timeoutMs = timeoutMs;
     return this;
   }
+  // Spec stream-connector 32 §10.1: the predicate reads the whole message, and
+  // the call answers with the messages themselves, so a caller can assert on the
+  // packet name and the metadata and not only on the payload.
   async run(signal) {
     this.markExecuted();
     if (this.predicates.length === 0) {
@@ -902,13 +951,13 @@ var ZlinkStreamSequenceBuilder = class {
     }
     const timeoutMs = this.timeoutMs ?? this.connector.options.waitTimeoutMs;
     const deadline = Date.now() + timeoutMs;
-    const payloads = [];
+    const messages = [];
     for (const predicate of this.predicates) {
       const message = await this.connector.waitForMessage(
         this.name,
         Math.max(0, deadline - Date.now()),
         (candidate) => {
-          if (!predicate(candidate.payload)) {
+          if (!predicate(candidate)) {
             throw connectorError(
               "validationFailed" /* ValidationFailed */,
               `Message '${this.name}' arrived out of the expected sequence.`
@@ -918,9 +967,15 @@ var ZlinkStreamSequenceBuilder = class {
         },
         signal
       );
-      payloads.push(message.payload);
+      if (message === void 0) {
+        throw connectorError(
+          "validationFailed" /* ValidationFailed */,
+          `The '${this.name}' sequence did not complete within ${timeoutMs}ms.`
+        );
+      }
+      messages.push(message);
     }
-    return payloads;
+    return messages;
   }
   ensureConfigurable() {
     if (this.executed) {
@@ -1021,7 +1076,7 @@ function splitZlinkStreamFrames(chunk) {
 }
 function validatePayload(payloadLength, maxPayloadSize) {
   if (payloadLength > maxPayloadSize) {
-    throw connectorError("frameTooLarge" /* FrameTooLarge */, "Payload exceeds MaxSendPayloadSize.");
+    throw connectorError("validationFailed" /* ValidationFailed */, "Payload exceeds MaxSendPayloadSize.");
   }
 }
 
@@ -1303,22 +1358,30 @@ function normalizeOptions(options, defaultTransportFactory) {
       initialDelayMs: options.reconnect?.initialDelayMs ?? 250,
       maxDelayMs: options.reconnect?.maxDelayMs ?? 5e3,
       backoffFactor: options.reconnect?.backoffFactor ?? 2,
-      maxAttempts: options.reconnect?.maxAttempts ?? 3
+      maxAttempts: options.reconnect?.maxAttempts === void 0 ? 3 : options.reconnect.maxAttempts
     },
     maxSendPayloadSize: options.maxSendPayloadSize ?? 64 * 1024,
     maxReceivePayloadSize: options.maxReceivePayloadSize ?? 64 * 1024,
     dispatchMode: options.dispatchMode ?? "manual" /* Manual */,
     compression: options.compression ?? "lz4" /* Lz4 */,
     compressionCodec: resolveCompressionCodec2(options),
-    nameResolver: options.nameResolver ?? { resolve: (type) => type.name },
+    nameResolver: options.nameResolver ?? defaultPacketNameResolver,
     transportFactory: options.transportFactory ?? defaultTransportFactory,
     codec: options.codec,
-    meterProvider: options.meterProvider,
     // Spec 26 §4: the default diagnostics level is Errors, which preserves
     // the connector's established wire behavior.
     diagnosticsLevel: options.diagnosticsLevel ?? "errors" /* Errors */
   };
 }
+var defaultPacketNameResolver = {
+  resolve(payloadType) {
+    const declared = payloadType.packetName;
+    if (typeof declared === "string" && declared.length > 0) {
+      return declared;
+    }
+    return payloadType.name;
+  }
+};
 function resolveCompressionCodec2(options) {
   const compression = options.compression ?? "lz4" /* Lz4 */;
   if (compression === "none" /* None */) {
@@ -1362,7 +1425,8 @@ function validateReconnect(options) {
   if ((options?.backoffFactor ?? 2) < 1) {
     throw connectorError("validationFailed" /* ValidationFailed */, "Reconnect BackoffFactor must be at least 1.0.");
   }
-  if ((options?.maxAttempts ?? 3) <= 0) {
+  const maxAttempts = options?.maxAttempts === void 0 ? 3 : options.maxAttempts;
+  if (maxAttempts !== null && !(Number.isFinite(maxAttempts) && maxAttempts > 0)) {
     throw connectorError("validationFailed" /* ValidationFailed */, "Reconnect MaxAttempts must be null or positive.");
   }
 }
@@ -1486,6 +1550,16 @@ var ZlinkStreamReceivedMessages = class {
   queueHead = 0;
   queuedCount = 0;
   drainTask;
+  // True for as long as `drain` is on the stack, handler awaits included. It
+  // marks the execution context a registered handler runs in, so a `dispatch`
+  // made from inside a handler is recognised as re-entry rather than a fresh
+  // pump. It is not a lock: a single event loop admits no second thread, and
+  // nothing ever waits for this flag to fall.
+  draining = false;
+  // Spec stream-connector 32 §10: arrivals per packet name on the current
+  // connection. It is raised where a packet arrives, never where one is taken,
+  // so consuming does not lower it and the dispatch mode does not change it.
+  receivedCounts = /* @__PURE__ */ new Map();
   on(name, handler) {
     validateName(name);
     let set = this.handlers.get(name);
@@ -1511,30 +1585,86 @@ var ZlinkStreamReceivedMessages = class {
    * `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 connectionEnded} abandons this registration because the
+   *   connection it was watching ended before a message matched (spec
+   *   stream-connector 32 §10.1.1: "연결이 끝나 대기를 이어갈 수 없으면
+   *   `Disconnected`다", released when that connection ends).
    */
-  observe(name, observer) {
+  observe(name, observer, onConnectionEnded) {
     validateName(name);
     let set = this.observers.get(name);
     if (set === void 0) {
       set = /* @__PURE__ */ new Set();
       this.observers.set(name, set);
     }
-    set.add(observer);
+    const registration = { consume: observer, onConnectionEnded };
+    set.add(registration);
     queueMicrotask(() => {
-      if (this.observers.get(name)?.has(observer) === true) {
-        this.offerQueued(name, observer);
+      if (this.observers.get(name)?.has(registration) === true) {
+        this.offerQueued(name, registration);
       }
     });
     return subscription(() => {
-      set.delete(observer);
+      set.delete(registration);
       if (set.size === 0 && this.observers.get(name) === set) {
         this.observers.delete(name);
       }
     });
   }
+  /** Spec stream-connector 32 §10: arrivals under `name` on this connection. */
+  receivedCount(name) {
+    return this.receivedCounts.get(name) ?? 0;
+  }
+  /**
+   * 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.
+   *
+   * Wait surfaces are not touched here. The ones of the previous connection
+   * were released by {@link connectionEnded} when that connection ended, and
+   * one registered since then is waiting for this connection.
+   */
+  resetForNewConnection() {
+    this.receivedCounts.clear();
+    this.queue.length = 0;
+    this.queueHead = 0;
+    this.queuedCount = 0;
+  }
+  /**
+   * Releases every registered wait surface because the connection it was
+   * watching has ended — a transport loss, a server close, or `close()`.
+   * Spec stream-connector 32 §10.1.1: "푸는 시점은 연결이 끝난 때이지 다음
+   * 연결이 성립한 때가 아니다". The release belongs to the ending, so a wait
+   * does not hang until its own timeout when no next connection comes
+   * (reconnect off, attempts spent) and does not silently rebind to the next
+   * one when it does. The queue and the counts stay: they are rebaselined by
+   * the next {@link resetForNewConnection}, not by the ending (§10).
+   */
+  connectionEnded() {
+    if (this.observers.size === 0) {
+      return;
+    }
+    const abandoned = [...this.observers.values()].flatMap((set) => [...set]);
+    this.observers.clear();
+    for (const registration of abandoned) {
+      registration.onConnectionEnded();
+    }
+  }
   enqueue(message, signal) {
-    for (const observer of [...this.observers.get(message.name) ?? []]) {
-      if (observer(message)) {
+    this.receivedCounts.set(message.name, (this.receivedCounts.get(message.name) ?? 0) + 1);
+    for (const registration of [...this.observers.get(message.name) ?? []]) {
+      if (registration.consume(message)) {
         return;
       }
     }
@@ -1547,18 +1677,28 @@ var ZlinkStreamReceivedMessages = class {
   /**
    * 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.
    */
   async pump() {
+    if (this.draining) {
+      return;
+    }
     this.scheduleDrain();
     await this.drainTask;
   }
-  offerQueued(name, observer) {
+  offerQueued(name, registration) {
     for (let index = this.queueHead; index < this.queue.length; index += 1) {
       const queued = this.queue[index];
       if (queued === void 0 || queued.message.name !== name) {
         continue;
       }
-      if (!observer(queued.message)) {
+      if (!registration.consume(queued.message)) {
         continue;
       }
       this.removeAt(index);
@@ -1577,23 +1717,28 @@ var ZlinkStreamReceivedMessages = class {
     });
   }
   async drain() {
-    for (let index = this.findDeliverableIndex(); index >= 0; index = this.findDeliverableIndex()) {
-      const queued = this.queue[index];
-      if (queued === void 0) continue;
-      this.removeAt(index);
-      const { message, signal } = queued;
-      const handlers = [...this.handlers.get(message.name)];
-      for (const handler of handlers) {
-        try {
-          await handler(message, signal);
-        } catch (cause) {
-          await this.events.publishError({
-            code: "userCallbackFailed" /* UserCallbackFailed */,
-            message: "Typed message handler failed.",
-            cause
-          }, signal);
+    this.draining = true;
+    try {
+      for (let index = this.findDeliverableIndex(); index >= 0; index = this.findDeliverableIndex()) {
+        const queued = this.queue[index];
+        if (queued === void 0) continue;
+        this.removeAt(index);
+        const { message, signal } = queued;
+        const handlers = [...this.handlers.get(message.name)];
+        for (const handler of handlers) {
+          try {
+            await handler(message, signal);
+          } catch (cause) {
+            await this.events.publishError({
+              code: "userCallbackFailed" /* UserCallbackFailed */,
+              message: "Typed message handler failed.",
+              cause
+            }, signal);
+          }
         }
       }
+    } finally {
+      this.draining = false;
     }
   }
   removeAt(index) {
@@ -1637,10 +1782,9 @@ var ZlinkStreamReceivedMessages = class {
 
 // packages/stream-connector/src/Runtime/ZlinkStreamFrameSender.ts
 var ZlinkStreamFrameSender = class {
-  constructor(protocol, flowContext, metrics) {
+  constructor(protocol, flowContext) {
     this.protocol = protocol;
     this.flowContext = flowContext;
-    this.metrics = metrics;
   }
   pendingWrites = /* @__PURE__ */ new Set();
   async send(connection, kind, name, payload, metadata, compress, requestSeq, signal, correlationId, explicitFlow) {
@@ -1666,7 +1810,6 @@ var ZlinkStreamFrameSender = class {
     this.pendingWrites.add(write);
     try {
       await write;
-      this.metrics.outbound(frame.byteLength);
     } finally {
       this.pendingWrites.delete(write);
     }
@@ -1695,17 +1838,29 @@ function decodeSessionClosing(payload) {
 
 // packages/stream-connector/src/Runtime/ZlinkStreamReceiveDispatcher.ts
 var ZlinkStreamReceiveDispatcher = class {
-  constructor(protocol, pendingRequests, receivedMessages, frameSender, events, flowContext, metrics, serverClosing) {
+  constructor(protocol, pendingRequests, receivedMessages, frameSender, events, flowContext, serverClosing) {
     this.protocol = protocol;
     this.pendingRequests = pendingRequests;
     this.receivedMessages = receivedMessages;
     this.frameSender = frameSender;
     this.events = events;
     this.flowContext = flowContext;
-    this.metrics = metrics;
     this.serverClosing = serverClosing;
   }
-  async readAndDispatch(connection, signal, isCurrent) {
+  /**
+   * @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.
+   */
+  async readAndDispatch(connection, signal, isCurrent, connectionForSend) {
     if (connection?.read === void 0) {
       return { available: false, inbound: false };
     }
@@ -1716,7 +1871,6 @@ var ZlinkStreamReceiveDispatcher = class {
     if (frameBytes === void 0) {
       return { available: false, inbound: false };
     }
-    this.metrics.inbound(frameBytes.byteLength);
     const flowEnabled = this.protocol.flowEnabled();
     let frames;
     try {
@@ -1729,8 +1883,11 @@ var ZlinkStreamReceiveDispatcher = class {
       return { available: true, inbound: false };
     }
     for (const frame of frames) {
+      if (isCurrent !== void 0 && !isCurrent()) {
+        break;
+      }
       try {
-        await this.dispatch(connection, frame.header, frame.payload, signal, flowEnabled);
+        await this.dispatch(connection, frame.header, frame.payload, signal, flowEnabled, connectionForSend);
       } catch (cause) {
         if (frame.header.kind === 5 /* Control */ && frame.header.name === ZLINK_STREAM_HEARTBEAT_PING) {
           throw cause;
@@ -1743,7 +1900,7 @@ var ZlinkStreamReceiveDispatcher = class {
     }
     return { available: true, inbound: true };
   }
-  async dispatch(connection, header, payload, signal, flowEnabled) {
+  async dispatch(connection, header, payload, signal, flowEnabled, connectionForSend) {
     if (header.kind === 3 /* Response */ && header.requestSeq !== void 0) {
       try {
         if (!this.pendingRequests.resolve(header.requestSeq, {
@@ -1796,7 +1953,7 @@ var ZlinkStreamReceiveDispatcher = class {
       return;
     }
     if (header.kind === 5 /* Control */) {
-      await this.dispatchControl(connection, header, payload, signal);
+      await this.dispatchControl(connection, header, payload, signal, connectionForSend);
       return;
     }
     if (header.kind === 1 /* Send */) {
@@ -1810,7 +1967,7 @@ var ZlinkStreamReceiveDispatcher = class {
       }, signal);
     }
   }
-  async dispatchControl(connection, header, payload, signal) {
+  async dispatchControl(connection, header, payload, signal, connectionForSend) {
     if (header.name === ZLINK_SESSION_CLOSING) {
       const closing = decodeSessionClosing(payload);
       await this.serverClosing?.(closing.closeReason);
@@ -1821,7 +1978,11 @@ var ZlinkStreamReceiveDispatcher = class {
     }
     if (header.name === ZLINK_STREAM_HEARTBEAT_PING) {
       try {
-        await this.frameSender.sendControl(connection, ZLINK_STREAM_HEARTBEAT_PONG, signal);
+        await this.frameSender.sendControl(
+          connectionForSend?.() ?? connection,
+          ZLINK_STREAM_HEARTBEAT_PONG,
+          signal
+        );
       } catch (cause) {
         throw connectorError(
           "sendFailed" /* SendFailed */,
@@ -1854,15 +2015,17 @@ function decodeRemoteError(protocol, header, payload) {
 }
 
 // packages/stream-connector/src/Runtime/ZlinkStreamConnectorLifecycle.ts
+function randomizedDelay(baseDelayMs) {
+  return Math.round(baseDelayMs * (0.5 + Math.random() * 0.5));
+}
 var ZlinkStreamConnectorLifecycle = class {
-  constructor(options, pendingRequests, frameSender, receiveDispatcher, receivedMessages, events, metrics) {
+  constructor(options, pendingRequests, frameSender, receiveDispatcher, receivedMessages, events) {
     this.options = options;
     this.pendingRequests = pendingRequests;
     this.frameSender = frameSender;
     this.receiveDispatcher = receiveDispatcher;
     this.receivedMessages = receivedMessages;
     this.events = events;
-    this.metrics = metrics;
   }
   receiveLoopAbort;
   receiveLoopSleeping = false;
@@ -1872,6 +2035,7 @@ var ZlinkStreamConnectorLifecycle = class {
   connectionGeneration = 0;
   currentState = "created" /* Created */;
   heartbeatTimer;
+  heartbeatTickRunning = false;
   lastInboundAt = 0;
   closeTask;
   connectTask;
@@ -1922,6 +2086,7 @@ var ZlinkStreamConnectorLifecycle = class {
       this.currentConnection = connection;
       this.connectionGeneration += 1;
       this.disconnectedPublished = false;
+      this.receivedMessages.resetForNewConnection();
       this.lastInboundAt = Date.now();
       await this.setState("connected" /* Connected */, void 0, signal);
       this.startHeartbeat();
@@ -1933,7 +2098,9 @@ var ZlinkStreamConnectorLifecycle = class {
         throw new ZlinkStreamException(error2);
       }
       const error = toStreamError(cause, "connectTimeout" /* ConnectTimeout */, "Connect failed.");
+      this.closeReasonValue ??= "TransportError";
       await this.setState("disconnected" /* Disconnected */, error, signal);
+      await this.publishDisconnectedOnce(signal);
       throw new ZlinkStreamException(error);
     }
   }
@@ -1979,8 +2146,9 @@ var ZlinkStreamConnectorLifecycle = class {
       errors.push(error);
     }
     this.pendingRequests.failAll({ code: "disconnected" /* Disconnected */, message: "Connector closed." });
+    this.receivedMessages.connectionEnded();
     await this.setState("closed" /* Closed */, void 0, signal);
-    await this.publishDisconnectedOnce(signal);
+    this.publishDisconnectedWithoutWaiting(signal);
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) throw new AggregateError(errors, "Stream connector close failed.");
   }
@@ -2011,7 +2179,8 @@ var ZlinkStreamConnectorLifecycle = class {
     const result = await this.receiveDispatcher.readAndDispatch(
       connection,
       signal,
-      () => this.isCurrentConnection(connection, generation)
+      () => this.isCurrentConnection(connection, generation),
+      () => this.connectionForSend()
     );
     if (result.inbound && this.isCurrentConnection(connection, generation)) {
       this.lastInboundAt = Date.now();
@@ -2023,25 +2192,18 @@ var ZlinkStreamConnectorLifecycle = class {
     let delayMs = this.options.reconnect.initialDelayMs;
     let lastError;
     const maxAttempts = this.options.reconnect.enabled ? this.options.reconnect.maxAttempts : 1;
-    while (attempt < maxAttempts) {
+    const unlimited = maxAttempts === null;
+    while (unlimited || attempt < maxAttempts) {
       attempt += 1;
-      if (attempt > 1) {
-        this.metrics.reconnect();
-      }
-      const handshakeStartedAt = performance.now();
       try {
-        const connection = await this.options.transportFactory.connect(this.options, signal);
-        this.metrics.handshakeCompleted(handshakeStartedAt);
-        return connection;
+        return await this.options.transportFactory.connect(this.options, signal);
       } catch (cause) {
-        this.metrics.handshakeCompleted(handshakeStartedAt);
-        this.metrics.handshakeFailed(cause);
         lastError = toStreamError(cause, "connectTimeout" /* ConnectTimeout */, "Connect failed.");
-        if (!this.options.reconnect.enabled || attempt >= maxAttempts) {
+        if (!this.options.reconnect.enabled || !unlimited && attempt >= maxAttempts) {
           break;
         }
         await this.setState("reconnecting" /* Reconnecting */, lastError, signal);
-        await delay(delayMs, signal);
+        await delay(randomizedDelay(delayMs), signal);
         delayMs = Math.min(
           this.options.reconnect.maxDelayMs,
           Math.ceil(delayMs * this.options.reconnect.backoffFactor)
@@ -2057,15 +2219,25 @@ var ZlinkStreamConnectorLifecycle = class {
     if (!this.options.heartbeat.enabled) {
       return;
     }
-    this.heartbeatTimer = setInterval(() => {
-      void this.runHeartbeatTick();
+    const timer = setInterval(() => {
+      if (this.heartbeatTickRunning) {
+        return;
+      }
+      this.heartbeatTickRunning = true;
+      void this.runHeartbeatTick().finally(() => {
+        if (this.heartbeatTimer === timer) {
+          this.heartbeatTickRunning = false;
+        }
+      });
     }, this.options.heartbeat.intervalMs);
+    this.heartbeatTimer = timer;
   }
   stopHeartbeat() {
     if (this.heartbeatTimer !== void 0) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = void 0;
     }
+    this.heartbeatTickRunning = false;
   }
   // Spec stream-connector 32 §7: the receive loop runs in both dispatch modes.
   // `Manual` only changes what the loop does with a frame — it queues the
@@ -2180,41 +2352,96 @@ var ZlinkStreamConnectorLifecycle = class {
     if (this.disconnectTask !== void 0) {
       return await this.disconnectTask;
     }
-    this.disconnectTask = this.disconnectOnce(error).finally(() => {
+    this.disconnectTask = this.tearDownConnection(error).finally(() => {
       this.disconnectTask = void 0;
     });
-    return await this.disconnectTask;
+    await this.disconnectTask;
+    await this.announceDisconnect(error);
   }
   isCurrentConnection(connection, generation) {
     return !this.closeRequested && this.currentConnection === connection && this.connectionGeneration === generation;
   }
-  async disconnectOnce(error) {
+  /** Transport teardown only — no application callback runs from here. */
+  async tearDownConnection(error) {
     this.stopHeartbeat();
     this.stopReceiveLoop();
     const connection = this.currentConnection;
     this.currentConnection = void 0;
     this.pendingRequests.failAll(error);
+    this.receivedMessages.connectionEnded();
     try {
       await connection?.close();
     } catch {
     }
+  }
+  /**
+   * 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.
+   */
+  async announceDisconnect(error) {
     if (this.closeRequested) return;
-    await this.setState("disconnected" /* Disconnected */, error);
-    await this.publishDisconnectedOnce();
+    const announce = this.claimDisconnectedPublish();
+    const notified = (async () => {
+      await this.setState("disconnected" /* Disconnected */, error);
+      if (announce) {
+        await this.events.publishDisconnected();
+      }
+    })();
     if (this.shouldReconnect()) {
       queueMicrotask(() => {
         void this.connect().catch(() => void 0);
       });
     }
+    await notified;
   }
   shouldReconnect() {
     return this.options.reconnect.enabled && !this.closeRequested;
   }
-  async publishDisconnectedOnce(signal) {
-    if (this.disconnectedPublished) return;
+  // Synchronous test-and-set, taken before any await, so the single disconnect
+  // notification the spec promises is claimed by exactly one caller even when
+  // the publishing itself is deferred.
+  claimDisconnectedPublish() {
+    if (this.disconnectedPublished) return false;
     this.disconnectedPublished = true;
+    return true;
+  }
+  async publishDisconnectedOnce(signal) {
+    if (!this.claimDisconnectedPublish()) return;
     await this.events.publishDisconnected(signal);
   }
+  /**
+   * 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.
+   */
+  publishDisconnectedWithoutWaiting(signal) {
+    void this.publishDisconnectedOnce(signal).catch(() => void 0);
+  }
   async setState(current, error, signal) {
     const previous = this.currentState;
     this.currentState = current;
@@ -2396,9 +2623,6 @@ var BrowserWebSocketConnection = class {
         this.readWaiter = void 0;
         resolve();
       };
-      if (this.hasQueuedMessage() || this.closed) {
-        this.wakeReader();
-      }
     });
   }
   wakeReader() {
@@ -2478,50 +2702,6 @@ function toUint8Array(data) {
   throw connectorError("frameDecodeFailed" /* FrameDecodeFailed */, "WebSocket text messages are not supported.");
 }
 
-// packages/stream-connector/src/Runtime/ZlinkStreamRuntimeMetrics.ts
-var ZlinkStreamRuntimeMetrics = class {
-  constructor(options) {
-    this.options = options;
-    const meter = options.meterProvider?.getMeter("zlink.framework");
-    this.reconnects = meter?.createCounter("zlink.stream.reconnects", { unit: "{event}" });
-    this.handshakeDuration = meter?.createHistogram("zlink.stream.handshake.duration", { unit: "s" });
-    this.handshakeFailures = meter?.createCounter("zlink.stream.handshake.failures", { unit: "{failure}" });
-    this.inboundBytes = meter?.createCounter("zlink.stream.inbound.bytes", { unit: "By" });
-    this.outboundBytes = meter?.createCounter("zlink.stream.outbound.bytes", { unit: "By" });
-  }
-  reconnects;
-  handshakeDuration;
-  handshakeFailures;
-  inboundBytes;
-  outboundBytes;
-  reconnect() {
-    this.safe(() => this.reconnects?.add(1, { transport: this.transportLabel() }));
-  }
-  handshakeCompleted(startedAt) {
-    const seconds = (performance.now() - startedAt) / 1e3;
-    this.safe(() => this.handshakeDuration?.record(seconds, { transport: this.transportLabel() }));
-  }
-  handshakeFailed(error) {
-    const reason = error instanceof Error && (error.name === "AbortError" || error.name === "TimeoutError") ? "canceled" : "transport_error";
-    this.safe(() => this.handshakeFailures?.add(1, { transport: this.transportLabel(), reason }));
-  }
-  inbound(byteCount) {
-    this.safe(() => this.inboundBytes?.add(byteCount, { transport: this.transportLabel() }));
-  }
-  outbound(byteCount) {
-    this.safe(() => this.outboundBytes?.add(byteCount, { transport: this.transportLabel() }));
-  }
-  transportLabel() {
-    return this.options.endpoint.startsWith("wss:") ? "wss" : "ws";
-  }
-  safe(record) {
-    try {
-      record();
-    } catch {
-    }
-  }
-};
-
 // packages/stream-connector/src/Runtime/ZlinkStreamConnector.ts
 var DefaultZlinkStreamConnector = class {
   static heartbeatPingName = ZLINK_STREAM_HEARTBEAT_PING;
@@ -2544,9 +2724,8 @@ var DefaultZlinkStreamConnector = class {
       configurable: true,
       get: () => this.diagnosticsLevelCell.level
     });
-    const metrics = new ZlinkStreamRuntimeMetrics(this.options);
     const protocol = new ZlinkStreamFrameProtocol(this.options);
-    this.frameSender = new ZlinkStreamFrameSender(protocol, flowContext, metrics);
+    this.frameSender = new ZlinkStreamFrameSender(protocol, flowContext);
     this.receivedMessages = new ZlinkStreamReceivedMessages(
       this.events,
       this.options.dispatchMode === "immediate" /* Immediate */
@@ -2558,7 +2737,6 @@ var DefaultZlinkStreamConnector = class {
       this.frameSender,
       this.events,
       flowContext,
-      metrics,
       (reason) => this.lifecycle.serverClosing(reason)
     );
     this.lifecycle = new ZlinkStreamConnectorLifecycle(
@@ -2567,8 +2745,7 @@ var DefaultZlinkStreamConnector = class {
       this.frameSender,
       this.receiveDispatcher,
       this.receivedMessages,
-      this.events,
-      metrics
+      this.events
     );
   }
   get isConnected() {
@@ -2583,6 +2760,17 @@ var DefaultZlinkStreamConnector = class {
   get pendingDispatchCount() {
     return this.pendingRequests.count;
   }
+  /**
+   * 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) {
+    validateName(name);
+    return this.receivedMessages.receivedCount(name);
+  }
   /**
    * Current diagnostics level (spec 26 §4.1, spec stream-connector 32 §13).
    * Reflects the level set by the most recent {@link setDiagnosticsLevel}
@@ -2598,14 +2786,20 @@ var DefaultZlinkStreamConnector = class {
    * 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) {
-    void this.setDiagnosticsLevelAsync(level);
+    this.diagnosticsLevelCell.set(level);
   }
+  /**
+   * 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) {
-    this.diagnosticsLevelCell.set(level);
+    this.setDiagnosticsLevel(level);
     return Promise.resolve();
   }
   onErrorReceived(handler) {
@@ -2644,18 +2838,41 @@ var DefaultZlinkStreamConnector = class {
     }, signal);
     return this.receivedMessages.on(name, encodedHandler);
   }
-  waitFor(name) {
-    validateName(name);
-    return new ZlinkStreamWaitBuilder(this, name);
+  waitFor(nameOrType) {
+    return new ZlinkStreamWaitBuilder(this, this.observedName(nameOrType));
   }
-  expectNone(name) {
-    validateName(name);
-    return new ZlinkStreamExpectNoneBuilder(this, name);
+  expectNone(nameOrType) {
+    return new ZlinkStreamExpectNoneBuilder(this, this.observedName(nameOrType));
+  }
+  waitForSequence(nameOrType) {
+    return new ZlinkStreamSequenceBuilder(this, this.observedName(nameOrType));
   }
-  waitForSequence(name) {
+  /**
+   * 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.
+   */
+  observedName(nameOrType) {
+    const name = typeof nameOrType === "function" ? this.options.nameResolver.resolve(nameOrType) : nameOrType;
+    if (typeof name !== "string") {
+      throw connectorError("validationFailed" /* ValidationFailed */, "Packet name must be a string or a payload constructor.");
+    }
     validateName(name);
-    return new ZlinkStreamSequenceBuilder(this, name);
+    return name;
   }
+  /**
+   * Consumes the first message under `name` that `predicate` accepts, or
+   * resolves `undefined` when `timeoutMs` elapses first.
+   *
+   * A timeout is not a failure here. Each wait surface decides what its own
+   * timeout means — `waitFor` fails on it while `expectNone` succeeds — and
+   * reports that decision as `ValidationFailed` (spec stream-connector 32
+   * §10.1.1; .NET `ZlinkStreamReceivedMessages.WaitForAsync` parity). Losing
+   * the connection the wait observes is the one ending decided here, because
+   * the wait has no place left to observe: that is `Disconnected` for every
+   * surface (§10.1.1).
+   */
   waitForMessage(name, timeoutMs, predicate, signal) {
     validateName(name);
     if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
@@ -2683,9 +2900,7 @@ var DefaultZlinkStreamConnector = class {
           resolve(message);
         }
       };
-      timer = setTimeout(() => {
-        finish(connectorError("requestTimeout" /* RequestTimeout */, "Wait for stream message timed out."));
-      }, timeoutMs);
+      timer = setTimeout(() => finish(), timeoutMs);
       signal?.addEventListener("abort", onAbort, { once: true });
       disposable = this.receivedMessages.observe(name, (message) => {
         if (done) {
@@ -2707,7 +2922,10 @@ var DefaultZlinkStreamConnector = class {
           finish(cause);
         }
         return true;
-      });
+      }, () => finish(connectorError(
+        "disconnected" /* Disconnected */,
+        `The connection this wait for '${name}' observed has ended.`
+      )));
     });
   }
   encodePayload(payload, messageType) {
@@ -2786,50 +3004,6 @@ function isEncodedPayload(value) {
   return typeof candidate.codec === "number" && candidate.payload instanceof Uint8Array;
 }
 
-// packages/stream-connector/src/Runtime/ZlinkStreamAssertions.ts
-var zlinkStreamAssert = {
-  ensure(condition, message) {
-    if (!condition) {
-      throw connectorError("validationFailed" /* ValidationFailed */, message);
-    }
-  },
-  async expectFailure(action, errorKind) {
-    let failure;
-    try {
-      await action();
-    } catch (error) {
-      failure = error;
-    }
-    if (failure === void 0) {
-      throw connectorError("validationFailed" /* ValidationFailed */, "Expected action to fail.");
-    }
-    const streamError = unwrapStreamError(failure);
-    if (errorKind !== void 0 && streamError.code !== errorKind) {
-      throw connectorError(
-        "validationFailed" /* ValidationFailed */,
-        `Expected failure kind '${errorKind}', got '${streamError.code}'.`,
-        failure
-      );
-    }
-    return streamError;
-  },
-  async expectTimeout(action) {
-    let failure;
-    try {
-      await action();
-    } catch (error) {
-      failure = error;
-    }
-    if (failure === void 0) {
-      throw connectorError("validationFailed" /* ValidationFailed */, "Expected action to time out.");
-    }
-    const code = unwrapStreamError(failure).code;
-    if (code !== "requestTimeout" /* RequestTimeout */ && code !== "connectTimeout" /* ConnectTimeout */) {
-      throw failure;
-    }
-  }
-};
-
 // packages/stream-connector/src/index.ts
 var zlinkStreamConnectorFactory = {
   create(options) {
@@ -2837,7 +3011,6 @@ var zlinkStreamConnectorFactory = {
   }
 };
 export {
-  DefaultZlinkStreamConnector,
   ZlinkStreamCodec,
   ZlinkStreamCompression,
   ZlinkStreamConnectionState,