@urun-sh/core 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## 0.5.0
+
+- **BREAKING: `end()` PARKS, and `cancel()` is the admission-ticket verb** (owner ruling D3,
+  2026-09-06; Review A §5.1 "two end verbs", §3.3 residue).
+  - `Session.end()` / `sessionDirectory().end(id)` both go through the one implementation
+    `endSession()` → `POST /api/sessions/{id}/end` → `urun_park_session(client_ended)`.
+    It resolves `{ status: 'paused', sessionId, reason }`. `'paused'` can never throw; a
+    TERMINAL word on that route is now the loud error (`invalid_end_response`), because a
+    terminal write on the session plane is what the model forbids.
+  - `Session.cancel()` (new) → `POST /api/session-requests/{id}/cancel`. Request plane only,
+    never addressed by session id. Every outcome the control plane can answer maps to
+    `{ status: 'canceled' }`; an unrecognized word stays loud.
+  - `SessionEndResult` is now `{ status: 'paused'; sessionId; reason } | { status: 'canceled';
+    requestId; platformStatus? }` — the `'ended'` member is gone.
+  - `SessionEndError.requestId` is optional and `sessionId` is new.
+  - `allocateSession`'s `onRequest` handle carries `sessionId` as soon as the create envelope
+    names one, so a hang-up racing allocation parks the session instead of cancelling the
+    ticket of a session that already exists.
+  - `SessionGatewayStatus` gains `'paused'`.
+  - The end request is `keepalive`, like the teardown beacon: an `end()` can race the tab
+    close that triggered it. It sends NO body: the verb names the cause server-side, and
+    session-api reads a wire `reason` only to tolerate it — so `end()` now speaks the same
+    wire shape as the pagehide beacon hitting that same route.
+  - **The one routing rule holds on the paths that are not the two verbs** (review findings):
+    a page teardown that cancelled a still-queued TICKET finishes on the SESSION plane if
+    promotion won the race (otherwise the promoted session holds a GPU seat with no client),
+    and the give-up cancel parks instead of cancelling when allocation threw AFTER the control
+    plane allocated (an unusable `session_api_base` / `ws_url` — the ticket-cancel route
+    refuses those with 409 `request_has_session`).
+  - A REFUSED `cancel()` is not a cancel: the release claim and the re-attach bookmark are
+    only taken on success, so a later `pagehide` still beacons the ticket cancel instead of
+    being suppressed by a release that never happened.
+
+## 0.4.3
+
+- **FIX: no server status word can reach a user as a benign lie — on EITHER path.**
+  Wave 0 (0.4.0) made the SFU WebSocket path honest: `STATUS_TO_PHASE` maps every
+  server word explicitly, an unmapped one goes LOUD (`console.error` via the
+  diagnostic mirror + an `unknown-server-status` diagnostic + phase `unknown`
+  carrying the literal word), and `reason` rides every phase. **It landed on the
+  WebSocket path only.** A brand-new user's cold start spends ALL of its time on
+  the HTTP admission path, and that path was documented as *"tolerant by
+  design"*: `admissionUpdateFrom` collapsed every 202 status word except
+  `queued` into `'pending'`, dropped `reason` entirely, and `reportAdmission`
+  rendered `provisioning`.
+
+  The consequence was that **`waiting_for_capacity` could not reach any client
+  at all**. The control plane answers a starved pull pool with
+  `202 {status:"waiting_for_capacity", reason:"no runtime worker is registered
+  for this pool — waiting for GPU capacity"}`; the phase exists in this SDK and
+  renders "Waiting for GPU capacity", but it was reachable ONLY from `_onStatus`
+  — i.e. only over a WebSocket that does not exist until allocation has already
+  succeeded, by which time capacity is no longer the question. A user whose org
+  has zero registered GPU workers watched "Provisioning…" for up to 600 s and
+  then got `never-live` "the backend is busy or wedged". The whole server-side
+  capacity observer was dead end-to-end.
+
+  Both entry points now share ONE `mapServerStatus(status)` and ONE loud-unknown
+  branch. `AdmissionUpdate.status` **widens from `'queued' | 'pending'` to
+  `string`** and carries the server's `reason`, plus `decisionReason` /
+  `refusalSource` / `refusalMessage` so a `provisioning_refused` 202 delivers
+  the PROVIDER's own message ("0/12 nodes are available: 12 Insufficient
+  nvidia.com/gpu…") instead of silence. The additive `runtime_state` detail may
+  still refine the two GENERIC waiting words (`queued`/`pending`) but may no
+  longer overrule a specific verdict — a starved answer carries
+  `runtime_state:'starting'` too, and letting `starting` win is exactly how the
+  capacity truth was lost.
+
+- **FIX: every pause cause the server can write now has human copy, and a
+  conformance guard fails the build when the two lists diverge.**
+  `describePauseReason` knew 3 of the server's causes; the other 16 fell through
+  to the verbatim arm, so the canonical first-run failure printed as
+  *"Paused — connect_deadline. Resume any time."* — and the only thing relating
+  the two vocabularies was a COMMENT claiming the list was "grepped from the
+  server sources". The vocabulary is now VENDORED at
+  `src/server-pause-reasons.json`, GENERATED by
+  `scripts/refresh-pause-reason-fixture.mjs` from the SFU `PauseReason` union,
+  the `sessions.pause_reason` VOCABULARY clause (urun-infra migration
+  `20270906000000`) and the SFU `RuntimeNotDeliveringReason` union, each with
+  its path and blob sha. `src/pause-reason-vocabulary.test.ts` fails when any
+  vendored cause still hits the default arm. Every line keeps the invariant:
+  never "ended", never "start a new session", always resumable.
+
+- **FIX: the default copy path shows an actionable hint, not developer text.**
+  `describeSessionPhase`'s `error` arm rendered ``Session failed — ${reason}``,
+  which for a create failure is the raw gateway string — an end user read
+  `[urun] session allocation failed at https://session-api.usw2.prod.cloud.urun.sh:
+  queue_full: … (HTTP 429)`. It now delegates to `describeSessionFailure`, so
+  message + hint are one code path. The `create-failed` hint gains arms for
+  **429** (names the load shed and surfaces the server's `Retry-After`) and
+  **5xx** (names the outage, says the retry is automatic) — both previously told
+  the user to "check the app/function name and auth", which is wrong about whose
+  fault it is. A lapsed queued REQUEST (`queue_ttl_expired` /
+  `stale_poll_expired`) no longer repeats the server's *"create a new session"* —
+  the request lapsed, the named object did not.
+
+- **FIX: the server's load-shed pacing is no longer advisory.** A 429 sets a
+  jittered `Retry-After: 2-6`; the SDK read it only on the 202
+  legacy-immediate branch and DROPPED it on the throw path, so the outer sweep
+  re-dialled an overloaded control plane on its own full-jitter schedule.
+  `SessionAllocationError.retryAfterSeconds` now carries it, the sweep waits the
+  MAX of that and its own jitter (bounded by `BACKOFF_MAX_MS`), and
+  `SessionPhaseError.retryAfterSeconds` surfaces it to the copy.
+
+  The pacing floor is the **sweep-wide maximum**, not the last url's: every
+  gateway failure overwrites `lastError`, so a paced 429 from the primary
+  followed by an unpaced retryable failure from a regional fallback used to
+  erase the primary's request entirely and re-dial it on client jitter. The
+  same floor now applies to `resolveViewerConnect`, whose refusal ALSO carries
+  the server's `Retry-After` (it paced itself against a field that was never
+  populated). `samePhase` compares `retryAfterSeconds`, so a refusal that only
+  changed how long the backend is asking for re-stamps the phase instead of
+  leaving the UI quoting the previous number.
+
+- **FIX: an HTTP 408 is a timeout, not a full admission queue.** The
+  `create-failed` hint folded 408 into the 429 arm and told the user "its
+  admission queue is full" — a confident FALSE cause for a status that only
+  establishes that a request timed out (`backoff.ts` treats it as a generic
+  retryable status; the durable-poll path throws `poll_http_408`). 408 now has
+  its own timeout copy, and still names the server's `Retry-After` when it sent
+  one.
+
+- **FIX: the display sanitizer no longer has holes.** It knew exactly TWO
+  gateway wrappers, so token hydration (`session allocation at <url> never got
+  an access token`), the redirect envelope / self-redirect (`session create at
+  <url> …`), the poll give-up and the region-forward loop all still showed an
+  internal hostname in end-user copy — and a reason that is NOTHING BUT a
+  wrapper (the bare allocation timeout) stripped to empty and hit the
+  `|| reason` fallback, printing the raw string the strip existed to clean.
+  Every wrapper is listed, and a residual redaction is the backstop: no gateway
+  URL survives into display copy by any route.
+
+- `whenLive`'s patience clocks (45 s / 600 s) are deliberately UNCHANGED here —
+  they are a separate item.
+
 ## 0.4.2
 
 - **Lockstep release** — version bump to match the `@urun-sh/openai` omp launcher cohort
@@ -7,7 +142,6 @@
 
 ## 0.4.1
 
-
 - **FIX: a re-dial no longer leaves the playout element bound to a DEAD track**
   (urun-infra#2132; the prod qwen-voice "assistant audio drops mid-session and
   never self-heals, reload fixes it" signature). `recvTransport.consume()` /