@mcpwarp/ws-mixer 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,357 @@
+# Changelog
+
+All notable changes to `@mcpwarp/ws-mixer` (the JS/TypeScript client SDK) are documented here.
+
+## 0.6.0 - 2026-09-26
+
+- A stream write that fails outside stream termination now reports that error to its write callback,
+  so a promisified/awaited write rejects. Previously, with no `'error'` listener attached, the
+  callback was called with no error — the write reported success even though its bytes were never
+  sent.
+  - On a stream whose peer CLOSE already arrived, a write whose socket send fails before the
+    connection's teardown reaches the stream is held, the same way as 0.4.0's held writes: the
+    buffered data, `'end'` and `'close'` are still delivered, and the callback is settled once the
+    read side has emitted `'end'` (or the stream is destroyed first) — with the error of whatever
+    tore the stream down first (connection teardown, or the app's own `destroy()`/`reset()`),
+    otherwise the send's own error. This no longer depends on teardown reaching the stream, so it
+    also holds after the app's own `closeWrite()`. If `'end'` had already fired, the callback gets
+    the send's error immediately.
+    With an `'error'` listener attached, 0.5.0 instead failed the callback immediately, which
+    errored the read side and blocked `'end'`; that is fixed too.
+  - Otherwise the callback gets the error immediately. This includes a write rejected after the
+    app's own `closeWrite()`: for a stream with no `'error'` listener it now also marks the stream
+    errored (`stream.errored` carries the error), same as before with a listener. If nothing is
+    listening, the SDK's internal no-op `'error'` listener is attached first, so the failure never
+    crashes the process.
+- CI: a new `pair-go-js` conformance job runs the go->js pair matrix (`--mode pair`) against
+  ws-mixer-go at `goserver.pin`, with a `go->js: 10` floor in `conformance/COUNTS.json` (all 10 pair
+  scenarios pass at spec v0.4.0 / ws-mixer-go v0.6.0). `spec.pin` is v0.4.1 in this release, whose
+  runner enforces COUNTS on `--sdk`/`--mode`-filtered runs, so the floor is live.
+- Docs: nearly all comments (84 of 88 references) now cite the split spec docs (`WIRE.md` section
+  2.x, `CLIENT-SDK.md` rows, and this repo's `docs/DESIGN.md`) instead of the old monorepo
+  `OVERVIEW.md` section numbers. The remaining four point at material that no longer exists in any
+  spec doc and are left as-is (`conn.ts`, `control.test.ts` ×2, `reconnect.test.ts`).
+  Comment-only; no behaviour change.
+
+## 0.5.0 - 2026-09-25
+
+- **Breaking:** `MixerClient.close()`'s options no longer take a `code` — `close({message})` always
+  closes the connection with `APPLICATION_CLOSE` (`0x0e`/WS close `4014`), never a caller-chosen
+  code. WIRE.md section 2.8 makes `APPLICATION_CLOSE` the only code an application may close a
+  *connection* with, so a caller-supplied code could previously close a healthy connection with a
+  protocol-fault code and produce an `errorCode`/`errorName` pair outside that table (D-2026-09-25-01).
+  Which path runs is chosen by whether `message` is present, not by any `code`: `close({message})`
+  is the application close, and `close()`/`close({})`/`message: undefined` is the default graceful
+  drain-then-close. Passing a `code` key at all (e.g. a plain-JS caller still on
+  `close({code: 14})`, with or without `message`) now throws a `TypeError` synchronously, before
+  any close is attempted, instead of silently taking either path. The `[0, 999]` `RangeError`
+  validation is gone along with `code`.
+- Conformance adapter: the `close` command's `code` now accepts only `0`/absent (graceful close) or
+  `14` (application close via the new `close({message})`) — any other value replies with a
+  command-error, `"close: only 0 or 14"`.
+
+## 0.4.0 - 2026-09-25
+
+- New `TokenUnavailableError` (exported from the package root): a token provider that throws or
+  rejects with an instance of it (directly, or wrapped via `cause`) now gets treated like a failed
+  dial instead of the fatal-by-default verdict every other provider throw/reject still gets — a
+  non-fatal `{phase: "dial", fatal: false}` report, normal full-jitter backoff (it counts as a
+  failed attempt: `reconnect.maxAttempts` applies, the stability rule is unaffected), and the
+  provider's error surfaced verbatim as `cause`, same as before. Detection is `instanceof
+  TokenUnavailableError` only, deliberately not duck-typed on any property or method, so an
+  unrelated library's error can never accidentally turn a genuinely fatal provider failure into an
+  endless retry loop. On the one-time pre-`welcome` refresh-retry's own provider call, a marked
+  failure leaves the retry budget spent and takes this same non-fatal path rather than going fatal
+  or granting a second refresh. On the very first connect, a marked failure no longer rejects
+  `start()`/`connect()` — same as a first-dial network error.
+- A pre-`welcome` token rejection -- an HTTP 401 on the upgrade, or a handshake-phase
+  `UNAUTHORIZED` (`4011`, with or without a preceding `error{}`) -- now gets the same one-time
+  refresh-retry treatment in *either* place, as ONE shared budget: when `token` is a provider
+  function, the SDK calls it again and retries the dial immediately (no backoff); a second
+  rejection, in either shape (`401` then `4011`, or `4011` then `401`), is fatal. A retry dial that
+  instead fails for an unrelated, non-auth reason (a network error, an HTTP 5xx, a transport death
+  before `welcome`) is *not* treated as a second rejection -- it takes the ordinary recoverable path
+  (non-fatal report, normal backoff) -- but the budget stays spent regardless, so a genuine
+  rejection on some later cycle, before the client ever goes stable, is still fatal with no further
+  refresh. Previously only the dial's own HTTP 401 got this retry -- a handshake-phase `4011` was
+  always immediately fatal, even with a token provider present. A **static string** `token` is
+  unaffected: still fatal on the very first rejection of any of the three forms, since there is
+  nothing to refresh (this was already true for HTTP 401 with a static token; it now also
+  explicitly applies to the two handshake-phase forms, which previously had no retry concept at all
+  to skip). Also fixed: this refresh-retry is now unconditional on `reconnect.maxAttempts`/
+  reconnect being disabled (it applies to the very first connect too -- one immediate redial that
+  completes the initial connection is not itself "a reconnect"), matching `ws-mixer-go`'s
+  `dialAndHandshake`; it likewise does not itself increment the attempt counter.
+- The refresh-retry budget above is a client-level flag (not local to one `connectOnce()` call), and
+  re-arms only once the connection reaches stability (see `stableAfter` below), never merely on the
+  next redial -- otherwise a server that welcomes and then closes shortly after could make the
+  client hit the token endpoint on every single reconnect cycle forever.
+- New `reconnect.stableAfter` option (default `10000`ms, next to `base`/`cap`/`connectTimeout`/
+  `maxAttempts`; must be a finite number `>= 0`, or the constructor throws a `RangeError`
+  synchronously, same as `close()`'s `code` validation -- `0` is legal and reproduces the pre-0.4
+  "reset on `welcome`" behaviour): how long a connection must stay up past `welcome` before it's
+  considered stable (WIRE.md/OVERVIEW.md section 2.9's `stable`). Fixed: the backoff attempt
+  counter, and every once-only retry budget re-armed alongside it (4013 KEEPALIVE_TIMEOUT's one-shot
+  immediate retry; the pre-`welcome` token refresh-retry above), now reset only once a connection
+  reaches stability -- **not** on `welcome` itself, as before. Fixed alongside it: 4013's one-shot
+  budget no longer un-spends itself on the very next 4013 (a leftover pre-`stableAfter` line reset
+  the flag back to "unused" immediately after falling back to normal backoff, so four 4013s in a row
+  with no intervening stable connection cycled immediate/backoff/immediate/backoff... forever instead
+  of only the first ever being immediate). A server that welcomes and then immediately closes no
+  longer resets backoff every cycle (which turned it into a redial-roughly-once-a-second loop
+  instead of actually backing off): `4009`/`4014`'s own "start backoff at the cap" treatment is
+  unaffected (still an explicit "refused on purpose, back off hard" rule, not a workaround for the
+  counter's reset timing). Stability is tracked per connection: a `drain` hand-over's retired
+  connection ending, however long after its replacement's own `welcome`, never resets or clears the
+  replacement's own stability timer. `reconnect.maxAttempts`'s doc is updated to match: it now
+  counts consecutive reconnect attempts *without* a stable connection in between.
+- Fixed: `giveUp` (the `reconnect.maxAttempts`-exhaustion path) now mirrors `goFatal` -- it clears
+  the stability timer and detaches-then-fails every live/in-flight conn (`conn`, `dialingConn`,
+  `retiringConn`, which a drain hand-over can leave all pointing at the very same live connection)
+  before reporting. Previously, exhaustion during (for example) a drain hand-over's parallel dial
+  failing could leave the still-live predecessor connection running -- socket, ping/watchdog timers,
+  and the now-orphaned stability timer all still ticking 10s past a client that already reports
+  itself `closed`.
+- Fixed: a transport failure between the 101 upgrade and `welcome` no longer fabricates a
+  semantically-meaningless ws-mixer close code (`wsCode: 4002`, "as if" this side had itself closed
+  with `INTERNAL_ERROR`) depending on whether `ws`'s `'error'` or `'close'` event happened to be
+  delivered first. `'close'` is now the sole reporter for this window (measured against real `ws`
+  8.21: a TCP reset/half-close/peer close frame delivers a bare `'close'` with no `'error'` at all;
+  a protocol-level failure `ws` itself detects delivers `'error'` immediately followed by `'close'`
+  a macrotask or more later -- `'close'` never races `'error'`, it always follows it, if it comes at
+  all); `'error'` only records its message for `'close'`'s report to fall back on when the close
+  itself carries no reason. The report now always carries the close code `ws` actually delivers
+  (`1006` for a genuine abnormal closure, or whatever real close code it sent), never a fabricated
+  one. If `'error'` fires and `'close'` never follows at all, nothing here waits on it: the existing
+  hello/welcome timeout (`wsCode` `4001`) is unaffected and is what eventually reports it, as before
+  -- deliberately the only fallback for that case. The connected phase was checked for the same
+  class of bug and does not have it: an `'error'` there never produces a report by itself (see the
+  `message` bullet below for the one real behaviour change to the connected phase's report shape).
+- Fixed: a second `drain` on the same connection (before its first parallel reconnect resolves) no
+  longer starts a second, redundant parallel dial -- mirrors `ws-mixer-go`, which already ignores a
+  repeat drain the same way.
+- `conformance/adapter/adapter.mjs`: `disconnected.error_name` now prefers the SDK's own
+  `DisconnectReason.errorName` (which already derives the wire name from a bare 4xxx close code, not
+  only from an explicit `error{}`) over re-deriving it from `errorCode` through the adapter's own
+  smaller name table.
+- A disconnect whose close frame carried no reason (from the peer, or a `ws`-level abnormal closure)
+  now reports `message: "socket closed with code N"` instead of an empty string, in both the
+  connected and handshake phases. Previously that fallback text only ever reached the internal
+  `WsMixerError` used to reject in-flight sends and fail the handshake promise; the *emitted*
+  `'close'` event (and so `DisconnectPayload.message`) carried the bare, possibly-empty close
+  reason directly. A non-empty `message` is strictly more useful (and matches `ws-mixer-go`, which
+  reports `"peer closed with code N"` for the same case) -- consumers that want "nothing, if the
+  peer sent nothing" specifically should keep preferring `closeReason` over `message`, as the
+  `closeReason` field's own doc already recommends.
+- Confirmed (no behavior change): `MixerClient.close()`/`close({code,message})` already stop
+  reconnecting in every state, and clear the stability timer alongside the existing backoff timer.
+  Precisely what's reported: one non-fatal disconnect when a connection had actually been
+  established for this cycle; nothing at all when none had (dialing, mid-handshake, or backing off)
+  -- exactly like plain `close()` in those same windows, since there is no connection to send
+  `error{}`/a WS close over in the first place.
+- **Behavior change** (D-2026-09-20-09, cross-SDK alignment with `ws-mixer-go`): `errorCode`/
+  `errorName` are no longer synthesised for anything that isn't a ws-mixer wire close code. An HTTP
+  `401`/`403` upgrade rejection previously carried `errorCode: UNAUTHORIZED` -- it no longer does;
+  `httpStatus` alone still identifies it (`404`/`429`/`5xx` were never affected, they never carried
+  one). Conversely, a **connected**-phase bare close (no preceding `error{}`) in ws-mixer's private-use
+  range `4001`-`4999` now derives both `errorCode`/`errorName` from the wire code the same way the
+  dial/handshake phases already did -- previously only `errorName` was derived there, `errorCode`
+  stayed `undefined`. The derivation itself is unchanged: `errorCode = wsCode - 4000`, `errorName`
+  from the WIRE.md §2.8 table (unknown -> `INTERNAL_ERROR`), restricted to `4001`-`4999` (not `4000`,
+  which is never legitimately on the wire -- `NO_ERROR` closes as `1000`). Also fixed as part of the
+  same alignment: the `'fatal'` event's `WsMixerError.code` now follows this same rule instead of its
+  own, separately-stale `info.errorCode` read -- for an HTTP `401`/`403` it is now `INTERNAL_ERROR`
+  (no ws-mixer code exists for an upgrade rejection) where it used to be `UNAUTHORIZED`, and for a
+  bare `4010`/`4011` close it is now the derived `UNSUPPORTED`/`UNAUTHORIZED` (previously
+  `INTERNAL_ERROR`, mismatching the disconnect reason's own `errorCode` for that same close).
+  Consumers that need to distinguish *why* a fatal happened should branch on the disconnect reason's
+  `httpStatus`/`wsCode`/`errorCode`, not on the fatal error's `code` alone.
+- **Fixed (blocker):** a stream `OPEN`, `app`, or `drain` event already queued for delivery when the
+  connection ended could be silently dropped instead of delivered, whenever an async
+  `onStream`/`onApp`/`onDrain` handler was still in flight at that exact moment (`error{}` is always
+  the *last* message on the wire, so anything queued ahead of it genuinely arrived before the
+  connection ended and is owed delivery — CLIENT-SDK.md's "Handler delivery" row). The delivery loop
+  now finishes flushing whatever was already queued even after the connection has torn down, instead
+  of exiting as soon as `this.closed` flips true out from under an in-flight `await`. **Behaviour
+  change:** `onStream`/`onApp`/`onDrain` (and the `'stream'`/`'app'`/`'drain'` events) may now fire
+  shortly after `MixerClient.close()`/`MixerConn.close()`'s own promise has already resolved, for an
+  event that arrived before that close. A `drain` delivered this way never starts a reconnect for a
+  connection that is no longer the live one: on an already closing/closed client the existing
+  `!this.closing && this.state !== "closed"` guard already covered it, but a `drain` queued behind a
+  blocked handler on a conn that then dies for an *unrelated* reason (its own 'close' handler already
+  ran synchronously and replaced/cleared `this.conn`, and already scheduled the real reconnect) needed
+  a further `this.conn === conn` guard -- without it, the flushed `drain` would still see
+  `!this.closing && this.state !== "closed" && !this.drainReconnectScheduled` all true and spawn a
+  second, parallel reconnect against the already-dead conn, latching `drainReconnectScheduled` and
+  wrongly suppressing the next legitimate close-driven reconnect. Nothing can be newly enqueued once
+  the connection is closed (defensive backstop, in addition to the architectural invariant that the
+  read path always stops before teardown), so the flush is always bounded and terminates.
+- **Fixed:** an open stream whose connection died abnormally (a `1006` tunnel death, or any
+  connection-level failure) with no `'error'` listener attached used to end *cleanly* — `'end'`
+  then `'close'`, with `stream.errored` never set — indistinguishable from the peer's own response
+  legitimately finishing (CLIENT-SDK.md's "Stream teardown on disconnect" row; WIRE.md section 2.9
+  requires the opposite: `io.ErrUnexpectedEOF`-equivalent, unless that stream's own `CLOSE` had
+  already arrived). **Behaviour change**, and it now depends on whether the peer's own `CLOSE` for
+  *that stream* had already arrived when the connection died, per WIRE.md's "`CLOSE` preserves
+  buffered data; `RESET` discards it" rule:
+  - `CLOSE` already arrived: the response DID complete, independent of the connection dying. Node's
+    `push(null)` doesn't discard what's still buffered — it marks EOF, and Node delivers the buffered
+    bytes to the consumer and only then emits `'end'`. `stream.errored` stays `null` and no `'error'`
+    event fires. Only the **write** side fails: a write already pending, or started afterward, fails
+    promptly (its callback receives the connection's error) instead of hanging or silently
+    succeeding.
+  - Otherwise (a peer `RESET`, or the connection ending any other way, with this stream's `CLOSE`
+    never having arrived): the stream always ends with an error, never a false clean end —
+    `stream.errored` carries it, `'close'` fires, and (for a consumer that *did* attach `'error'`)
+    that listener receives it, but `'end'` is never emitted for this case; a read or write already
+    pending, or started afterward, fails promptly. A pending write's callback now also receives the
+    real error instead of being reported as having succeeded, in both cases above. A `RESET` always
+    discards buffered data and errors, even if this stream's `CLOSE` had *also* already arrived
+    (`RESET` always wins). A stream already fully, cleanly closed before the connection died (both
+    directions' `CLOSE` already exchanged) is unaffected — it already ended cleanly and is no longer
+    tracked by the connection at all. `MixerClient`'s class doc comment and README already described
+    the intended behaviour; the code now actually matches it, with no remaining gap against
+    CLIENT-SDK.md's "data already buffered ... still delivered first" rule.
+- **Fixed:** a stream whose peer `CLOSE` had already arrived when the connection died -- the
+  cleanly-ending case in the bullet above -- never actually emitted `'close'` (never got
+  destroyed): `push(null)` delivered the buffered data and `'end'` fired, but nothing then called
+  `destroy()`. It now does: buffered data delivered, `'end'`, then `destroy()`/`'close'`, same as
+  a stream that ends any other way.
+- **Fixed:** in that same state, a write already pending (or started afterward) had its error
+  routed through Node's ordinary Writable error path, which also marks the readable side
+  `errored` and permanently blocks `'end'` -- a consumer draining `data`/`end` on the stream could
+  hang forever waiting behind a write it never awaited. Affected write callbacks are now held and
+  only settled with the terminal error once the read side has finished delivering buffered data
+  and emitted `'end'`, or the stream is destroyed some other way (app `destroy()`, `reset()`). An
+  app that awaits a write's callback without ever reading this stream will wait until it does one
+  or the other.
+- **Fixed:** a fatal close (`UNSUPPORTED`/`UNAUTHORIZED`) on the retiring connection during a
+  `drain` hand-over's parallel dial didn't cancel that in-flight dial: the client emitted
+  `'fatal'` and then flipped back to `"connected"` once the dial's own `welcome` landed, and with
+  `UNAUTHORIZED` it could also redial again via the pre-`welcome` token-refresh-retry loop. The
+  dial is now cancelled (`NO_ERROR`/"client closing") as part of going fatal, and the client stays
+  closed.
+- `conformance/adapter/adapter.mjs` now reports the SDK's real `SDK_VERSION` in `ready`/`hello`
+  instead of a stale hardcoded `"0.1.0"`.
+
+## 0.3.1 - 2026-09-20
+
+- `DisconnectReason` gains `closeReason`: the reason field of the close frame *received from the
+  peer*, verbatim -- never this side's own outgoing reason. Absent when this side initiated the
+  close (a peer's echo carries no information), when no close frame was observed at all (an
+  abnormal closure), or when the SDK closed on a peer's `error{}` without reading whatever close
+  frame follows it. `message` is unchanged and still carries the human-readable text in every case.
+- Fixed: a **handshake-phase** close now classifies (and, for `4010`/`4011`, goes fatal) from the
+  ws-mixer wire code the same way a connected-phase one already did, covering two previously-wrong
+  cases. (1) A bare close carrying a ws-mixer wire code before `welcome` previously reported
+  `errorName: "INTERNAL_ERROR"` and `fatal: false` -- silently retrying forever against a server
+  that will never accept the retry. (2) The normative pre-`welcome` auth-rejection shape
+  (`error{code:11 UNAUTHORIZED}` + close `4011`, before `welcome` -- OVERVIEW.md section 3.4's
+  Authenticate hook, `spec/fixtures/sequences/auth_failure.json`) was previously treated as a
+  *local* protocol violation: the client replied with its own `error{PROTOCOL_ERROR}` (forbidden by
+  WIRE.md section 2.7 -- a peer that receives `error` must never reply), closed with its own `4001`
+  instead of `4011`, discarded the server's real reason, and retried forever. A revoked token is now
+  what it should always have been: one fatal, non-retried disconnect. The client's own hello/welcome
+  timeout now also reports its locally-generated `wsCode: 4001` (previously omitted).
+- New public API: `MixerClient.close({ code, message })` (CLIENT-SDK.md's "Application close" row)
+  performs `error{code, message}` + WS close `4000+code` (message truncated to 123 UTF-8 bytes on a
+  character boundary) + close the socket, instead of the default graceful drain -- e.g. to close
+  with the new `APPLICATION_CLOSE` code below. `code` must be an integer in `[0, 999]`, or `close()`
+  throws a `RangeError` synchronously. `close()` with no arguments is unchanged. Fixed: `code`/
+  `message` now also apply when `close()` is called while a `drain`-triggered replacement dial or an
+  in-flight (pre-`welcome`) handshake is still outstanding -- both previously always sent
+  `error{NO_ERROR, "client closing"}` regardless of what was passed.
+- New named error code: `APPLICATION_CLOSE` (`0x0e`, WS close `4014`). Connection-level only, never
+  emitted by ws-mixer itself -- reserved for the application above to close a connection for its
+  own reason (see `close({ code, message })` above). A **connected-phase** `4014` gets `4009`'s own
+  "start at the cap" backoff treatment (WIRE.md section 2.9), not plain full-jitter backoff: it is
+  by nature sent *after* `welcome` already reset the attempt counter, so plain backoff would redial
+  roughly once a second forever instead of climbing. A handshake-phase `4014` is unaffected (its
+  attempt counter still climbs normally).
+- Fixed: closing with an error code whose `4000 + code` isn't a legal WS close code (any
+  `code > 999`, reachable off the wire whenever a peer sends `error{code >= 0x1000_0000}`) now sends
+  WS close `4002` (`INTERNAL_ERROR`'s close code) on the wire instead of throwing inside `ws` and
+  falling back to `terminate()` -- a bare abnormal closure (`1006`) that told the peer nothing at
+  all. `errorCode` and the reported `wsCode` stay the real, semantic `4000+code` either way; only
+  the bytes actually put on the wire are clamped (spec `WIRE.md` section 2.8 / decision
+  `D-2026-09-20-03`).
+- Fixed: `SDK_VERSION` -- sent on the wire in `hello.agent.sdk_version` and the dial's `User-Agent`
+  header -- was hard-coded to `"0.2.0"`, two releases stale. Now kept in sync with `package.json`'s
+  version by hand, enforced by `test/version.test.ts` so a future release bump that forgets it fails
+  CI instead of silently drifting again.
+- `conformance/adapter/adapter.mjs`: `disconnected` now always includes `phase`, and includes
+  `close_reason` when the SDK reports one; `close` now forwards a non-zero numeric `code`/`message`
+  to the new application-close API (`code: 0`/absent stays the existing graceful drain-then-close,
+  so `graceful_close.json`'s WIRE.md section 2.10 step 14 drain sequence keeps being exercised); the
+  RESET code-name table gained `14: "APPLICATION_CLOSE"`; `connect`'s `reconnect.baseMs`/
+  `reconnect.capMs` (when positive) now override the SDK's default backoff `base`/`cap`, so a
+  scenario needing a fast connected-phase `4014` at-cap reconnect isn't stuck behind the SDK's 60s
+  default cap.
+
+## 0.3.0 - 2026-09-04
+
+Repo split from the `mcpwarp/ws-mixer` monorepo into its own repo,
+`mcpwarp/ws-mixer-js`, per MIGRATION.md section 4.1.
+
+- Licensed Apache-2.0 (previously `UNLICENSED` in the monorepo).
+- The package now publishes to the public npm registry (`registry.npmjs.org`) instead of a
+  private registry.
+- Spec fixtures are no longer vendored from the monorepo's `spec/` directory;
+  they are now fetched from `ws-mixer-spec` at the tag pinned in `spec.pin`
+  (`npm run fetch-spec`, into the gitignored `.spec/`).
+
+## 0.2.0
+
+Per OVERVIEW.md section 4.0 ("Client SDK requirements") and the decision log entry dated
+2026-08-27.
+
+- `token` may now be a provider callback (`() => string | Promise<string>`), not just a static
+  string. It is called fresh on every dial -- initial connect and every reconnect -- never cached.
+- HTTP `401` on the upgrade now gets exactly one immediate refresh-retry when `token` is a
+  provider: the SDK calls it again and redials right away, no backoff, though the retry still
+  counts toward `reconnect.maxAttempts`. A second `401` is fatal. A static string `token` is
+  unchanged: fatal on the first `401`.
+- A token provider that throws or rejects is fatal; the error is surfaced verbatim via the new
+  `DisconnectReason.cause` field.
+- The disconnect reason reported to `onDisconnect` and the `'close'` event is now a `DisconnectReason`:
+  adds `phase` (`"dial"` | `"handshake"` | `"connected"`), `errorName`, `httpStatus`, and `cause`
+  alongside the existing `wsCode`/`errorCode`/`fatal`/`message`. Every disconnect -- not just fatal
+  or maxAttempts-exhaustion ones -- is now reported, including a recoverable dial failure and a
+  non-fatal handshake failure, which previously went unreported.
+- Fixed: a disconnect that also exhausted `reconnect.maxAttempts` (or hit the dial-side 401
+  refresh-retry ceiling) previously fired `onDisconnect` **twice** -- once for the failure, once
+  for giving up. It's now exactly one report per disconnect, `fatal: true` with the exhaustion
+  message, carrying the underlying failure's `wsCode`/`errorCode`/`httpStatus`/`cause`.
+- Fixed: the dial's per-attempt failure context (phase, HTTP status, provider `cause`) is now
+  threaded through each dial attempt instead of stored on shared mutable client fields, so a
+  concurrent old-connection close can no longer clobber a new dial's own disconnect report.
+- Fixed: an `unexpected-response` during the dial (HTTP 401/403/404/429) now drains and destroys
+  the response, destroys the request, and terminates the socket -- `ws` skips its own cleanup once
+  a listener is attached, and this SDK's listener wasn't doing that cleanup itself.
+- A `drain` while `reconnect.maxAttempts` is `0` no longer starts a parallel reconnect the client
+  is configured never to complete, and no longer treats the `drain` itself as an immediate fatal
+  event either: per OVERVIEW.md section 2.9, the connection is left alone, in-flight streams finish
+  normally, and only once the server's own deadline closes the socket with `4012` is that reported
+  -- once -- as the terminal `fatal: true` disconnect (`message: "drained; reconnect disabled"`).
+- Fixed: a superseded (drained) connection's own teardown, once its replacement's `welcome` lands,
+  no longer fires a spurious `onDisconnect`/`'close'` -- the client is still connected throughout,
+  via the replacement. Its in-flight streams now get a stream-scoped `StreamError(CANCEL,
+  "connection drained")` instead of the connection-level error, via `MixerConn.fail()`'s new
+  optional per-stream error override.
+- `MixerStream.reset()` now actually sets `resetCode`, as its docs already promised. Added
+  internal `abort()`, used for SDK-detected stream violations (mirrors a peer-sent RESET): unlike
+  the app-facing `reset()`, `abort()` also emits `'reset'`, since in both cases the stream's owner
+  didn't choose the teardown.
+- Per OVERVIEW.md section 2.9's Drain and the 2026-08-27 decision log: an `OPEN` received above a
+  drain's `last_stream_id` is now connection-fatal `PROTOCOL_ERROR` (WS close `4001`), not a
+  stream-scoped `REFUSED_STREAM` -- the server already promised not to send one, so this is it
+  breaking that promise, not a benign race. `stats().drainRefusedOpens` is renamed
+  `stats().drainViolations` to match.
+- New public exports: `TokenProvider`, `DisconnectReason`, `DisconnectPhase`, `DisconnectPayload`.
+
+## 0.1.0
+
+Initial release: `connect()`, `MixerClient`'s reconnect/backoff state machine (OVERVIEW.md section
+2.9 -- full-jitter backoff, `drain`/`4012` handling, `4013`/`4009` special-cased retries, fatal-close
+handling), `MixerConn` (handshake, keepalive, flow control, the control-priority + round-robin
+write scheduler), `MixerStream` (`stream.Duplex`), and the frame/control wire codecs.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Anatoly Tarnavsky
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.