@urun-sh/core 0.2.60 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 0.3.0
+
+- **BREAKING (types): `SessionPhaseName` widens 9 → 11 members** — adds
+  `'waiting_for_capacity'` and `'unknown'`. An exhaustive `switch` over
+  `phase.name` with a `never` default, or a `Record<SessionPhaseName, …>` label
+  map, stops compiling until the two new members are handled. The terminal
+  server words RELEASED/REAPED/EXPIRED/SUPERSEDED still map onto the *existing*
+  `'ended'`/`'expired'` names — no new terminal strings. (Breaking change rides
+  the 0.x minor per semver.)
+- **Server status honesty (#351).** `STATUS_TO_PHASE` maps the full server
+  vocabulary; an unrecognized status is no longer silently rendered as
+  `'provisioning'` — it becomes a loud `'unknown'` phase + `console.error` +
+  `unknown-server-status` diagnostic carrying the literal word. The lookup is
+  own-property-only, so `Object.prototype` words (`"constructor"`, `"toString"`,
+  `"__proto__"`) are treated as unknown rather than resolving inherited members.
+  `SessionPhase.reason` now propagates on non-terminal AND terminal paths, and
+  the session-refresh stash is cleared on every server-declared terminal frame
+  (fixes the eternal "Provisioning…" re-attach, urun-infra#1856). New exports:
+  `isServerTerminalPhase`, `SIGNALING_PROTOCOL_VERSION` (`'v1'`, sent on the
+  `start` frame).
+- **WT audio lane (#353).** Opus-over-QUIC-datagram downlink: datagram header
+  byte 11 is the lane discriminant (0 = video, byte-for-byte the historical
+  layout; 1 = audio) → `AudioFrameAssembler` → WebCodecs `AudioDecoder` →
+  scheduled WebAudio playout → bridge `MediaStreamTrack`, with a 40ms standing
+  buffer. A decode-error budget kills only the audio lane (reverts to WebRTC;
+  video keeps flowing). Negotiated per leg, so a pre-audio client never receives
+  a lane-1 datagram. The assembler bounds its in-flight set
+  (`WT_AUDIO_MAX_PENDING_FRAMES`) under sustained loss, rejects a non-finite
+  `jitterBufferTargetMs`, and closes the `AudioContext` if decoder setup throws.
+
+- **BREAKING (exported type `SignalCarrier`).** Implementers of the exported
+  `SignalCarrier` interface must update two members:
+  `sendSignal` now returns `boolean` (was `void`), and a new REQUIRED
+  `emitDiagnostic(diagnostic: SessionDiagnostic): void` reports through the
+  session's diagnostic channel. `TransportSession` — the only implementation
+  in this repo, and the one every SDK consumer actually passes — already
+  satisfies both; this affects only a host that hand-rolled its own carrier.
+
+  Deliberately NOT widened to `boolean | void` for source compatibility: a
+  legacy `void` implementation that FAILED to send returns `undefined`, and
+  treating `undefined` as success is precisely the silent-drop this release
+  exists to remove — it would preserve the phantom-timeout bug for exactly the
+  carriers that still have it. A compile error that names the seam is the
+  correct outcome (`CLAUDE.md`: one canonical path, fail hard, never a silent
+  alternate path). Pre-1.0, so a minor bump carries it.
+
+- **FIX: a signaling request that never left the process no longer fails as a
+  phantom timeout.** `SignalCarrier.sendSignal` returned `void` and was
+  documented as "dropped while disconnected", so a `transport.offer` issued
+  across a signaling blip vanished silently and `request()` then sat out its
+  full 10s deadline before rejecting with `signaling request timed out:
+  transport.offer` — a message that blames a timeout for a condition known
+  locally and instantly, and points the reader at a server that never received
+  a byte. `sendSignal`/`_send` now report whether the message went out on an
+  OPEN socket, `request()` rejects IMMEDIATELY with `signaling request not
+  sent: <method> — the signaling socket is not open` (tearing down its deadline
+  timer so nothing fires behind the rejection), and `notify()` — fire-and-forget
+  by contract, so nothing to reject — warns instead of pretending delivery. The
+  genuine no-reply case still uses the deadline lane, unchanged. The
+  undelivered-notify report rides the session's diagnostic channel
+  (`diagnosticSink` when configured, the `'diagnostic'` event always,
+  `kind: 'signaling-notify-undelivered'`) rather than a bare `console.warn`
+  that would bypass a host sink.
+
 ## 0.2.57
 
 - **FIX: `jitterBufferTarget` range guard (0–4000ms).** The W3C
@@ -95,6 +159,28 @@
   past the `<= 0` check and throw on assignment to the WebIDL double, aborting
   the consume before `resumeConsumer`.
 
+- **`SessionGatewayResponse.region_apex` is renamed `session_api_base`** (type
+  surface change: a consumer reading the raw allocated payload off
+  `AllocatedSession.response` must rename the field). The control plane owns
+  this name — urun-infra #1497 emits `session_api_base`, and its value is
+  already a full origin the SDK accepts unchanged. The field stays OPTIONAL:
+  #1497 is not merged, so nothing emits it yet and an ABSENT field remains the
+  normal path, keeping the create-final origin as the bootstrap pin.
+- **A present-but-unusable `session_api_base` now THROWS** where the previous
+  `region_apex` handling silently kept the bootstrap origin. On a managed
+  `urun.sh` https gateway a malformed / non-https / path-bearing / off-trust
+  value raises a gateway contract error, because silently keeping the bootstrap
+  origin sent the session's polls, release beacons and auth to a region that
+  does not own it and surfaced as a confident-looking 401/404 elsewhere.
+  Non-managed bases (kind's in-cluster `http://` service base, localhost,
+  self-hosted) ignore the field for that stated reason and never throw.
+- **An HTTP 3xx / `opaqueredirect` from session create OR poll is now a loud
+  terminal error** instead of a swallowed `HTTP 0`. The cross-region contract is
+  the JSON envelope (`200 {status:'redirect', location}`); an HTTP redirect is a
+  contract violation. The poll request also moves to `redirect: 'manual'`, so a
+  consumer that relied on the browser transparently following a poll redirect
+  will now see the error instead.
+
 - **`SessionDiagnostic.level` gains `'debug'`** (union widened: an exhaustive
   `switch`/`Record` over the level needs a new arm). `debug` diagnostics mirror
   to `console.debug` — hidden at the browser console's default verbosity —
@@ -148,6 +234,25 @@
   fails the build on ANY wall-clock media-gap branch that drives
   `_renegotiate()`/`_attemptReconnect()` (inbound counter or decode counter),
   while allowing the bounded first-byte-anchored join probe.
+- **A dispose racing an in-flight WebTransport negotiation aborts quietly and leaks
+  nothing.** zimage.urun.sh prod (2026-07-30): React lifecycle churn (the FE's bounded
+  terminal-frame auto-mint remounts its session engine; the unmount cleanup calls
+  `session.disconnect()` synchronously inside the React commit) disposed the dial-
+  negotiation handle while the QUIC probe was in flight. `WebTransportSession.stop()`
+  rejects the pending `firstMedia` with "webtransport session stopped", and the sidecar's
+  connect catch dressed that DELIBERATE teardown in the loud error-shaped
+  `transport negotiation unavailable, staying on webrtc` line — three identical times per
+  page load. A dispose is not a fallback (no session survives to fall back): the abort now
+  logs at debug and schedules nothing. The loud warn stays byte-for-byte for genuine
+  negotiation failures on a live handle (the WT-QUIC-first LOUD-fallback mandate is
+  unchanged). Additionally, a dispose racing `connect()`/`retryWebTransport()` used to
+  leak the just-established WT session (armed failover and all) past the handle's
+  lifecycle — the late arrival is now stopped.
+- **The `selected ICE candidate pair` diagnostic emits once per ACTUAL route.** It was
+  latched once-per-session-handle: repeated identical lines still spammed the console
+  across session churn, while a genuine route migration (an ICE restart landing on a
+  different pair, e.g. UDP → TCP relay) stayed silent forever after the first emit. The
+  diagnostic now dedupes on the pair itself — first route, then only on change.
 
 ## 0.2.44