@ultimat3/http 19.0.0 → 19.1.0

package/README.md

@@ -257,6 +257,30 @@ const handle = createServer({
 Static paths are registered in Bun's native `routes` table; param/wildcard paths fall
 through to `fetch`. Method resolution stays ours so a 405 still carries problem+json.
 
+### No WebSocket upgrade on the `web` role, and no hand-written `api/` route
+
+`As of 2026-09-05`, and stated because an app went looking for both. The `web` role's
+`Bun.serve` is built with no `websocket` handler (`server.ts`: "the `web` role does not use one"),
+so nothing under `/api` can `server.upgrade()` a request; and `/api/*` is a **projection** —
+`apiRoutes()` in `@ultimat3/cli` mounts every `action` and `query` the registries hold, and
+`x g route --surface api` does not exist (`readSurface` refuses `api` by name). A raw socket is
+not an action, so it has no home on this role.
+
+The framework's one WebSocket is the `sync` role's (`@ultimat3/realtime/server`, `PORT + 1`),
+authenticated by `SyncAuthenticator` and reached from the browser through `LiveClient`. A
+bidirectional stream — a PTY, a log tail — is written as **two halves that already exist**:
+
+| Direction | Primitive | Why |
+|---|---|---|
+| server → browser | a `channel` topic on the sync socket (`ChannelHub`, `topic(...)`, `client.subscribe(topic, …)`) | ordered frames, reconnect and backpressure are the sync node's, not a second socket's |
+| browser → server | an `action` — one call per keystroke batch | it gets a policy, a schema, rate limiting, audit and the typed client for free; a socket message gets none |
+
+A `web`-role upgrade hook was refused rather than half-built: the pipeline returns a `Response` at
+every stage (middleware, finalize, security headers), and an upgraded request must return
+`undefined` from `fetch` — a second exit from the pipeline with none of its guarantees. If the two
+halves above cannot carry a case, the fallback is a long-poll `action` (`GET`-shaped, returning
+`{ frames, cursor }` and re-called on return), which is what the app that asked shipped.
+
 ## Inbound webhooks
 
 `verifyWebhookSignature(request, { secret })` is the receiving half of the framework's webhook

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/http",
-  "version": "19.0.0",
+  "version": "19.1.0",
   "description": "Owned request lifecycle over Bun.serve: router, ordered pipeline, problem+json errors",
   "license": "MIT",
   "type": "module",
@@ -31,9 +31,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.0.0",
-    "@ultimat3/i18n": "19.0.0",
-    "@ultimat3/schema": "19.0.0",
-    "@ultimat3/time": "19.0.0"
+    "@ultimat3/core": "19.1.0",
+    "@ultimat3/i18n": "19.1.0",
+    "@ultimat3/schema": "19.1.0",
+    "@ultimat3/time": "19.1.0"
   }
 }

package/src/error-map.ts

@@ -141,6 +141,12 @@ export const ERROR_STATUS = {
   X_INVARIANT_VIOLATED: 422,
   X_TENANCY_UNSCOPED: 500,
   X_DB_DRIFT: 500,
+  // Both are the server's verdict on a statement the app wrote, which is the app's fault and not
+  // the caller's: a request cannot repair a missing migration or a wrong column list.
+  X_DB_SCHEMA_STALE: 500,
+  X_DB_STATEMENT_FAILED: 500,
+  // Logged at boot, never thrown into a request; the row exists so the table stays closed.
+  X_MCP_APP_UNMOUNTED: 500,
   // The three tenancy refusals, all 403, and all deliberately NOT the 404 `X_STORAGE_ORG_MISMATCH`
   // takes: that one answers 404 because a 403 on a KEY the caller supplied confirms the key exists.
   // These three name no resource and read no row — the comparison is the actor against an argument