@ultimat3/realtime 25.2.0 → 26.1.0

package/CLAUDE.md

@@ -284,7 +284,7 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 
 ## The page boot
 
-- **The disk boot is ONE page script (`boot.ts`, `./boot`)**, served at `/_x/page-boot/<hash>.js`
+- **The disk boot is ONE page script (`boot.ts`)**, at `/_x/assets/page-boot/<hash>.js`
   on a document with the scope tag and a realtime island; it installs the runtime, wipes every other
   principal's stored scope (read at the wipe), then restores. `booted` reads its promise off
   `Symbol.for('ultimate.page-boot')`. No boot: islands load its chunk.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "25.2.0",
+  "version": "26.1.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "25.2.0",
-    "@ultimat3/entity": "25.2.0",
-    "@ultimat3/policy": "25.2.0",
-    "@ultimat3/query": "25.2.0",
+    "@ultimat3/core": "26.1.0",
+    "@ultimat3/entity": "26.1.0",
+    "@ultimat3/policy": "26.1.0",
+    "@ultimat3/query": "26.1.0",
     "nats": "2.29.3"
   }
 }

package/src/errors.ts

@@ -282,7 +282,7 @@ export class LiveRowUnidentifiedError extends RealtimeError {
             cause: `live query "${args.query}" returned a row whose id is a ${args.idType}, not text or a safe integer — a live row is addressed by a text id, so project the key as text (a uuid or text column) or drop live: true from the query`,
             // A name the shell would not read verbatim does not travel: the list names it instead.
             fix: isFixShellSafe(args.query)
-              ? `x queries describe ${renderFixShellArg(args.query, 'name')} --json`
+              ? `x queries show ${renderFixShellArg(args.query, 'name')} --json`
               : 'x queries list --json',
           },
     );

package/src/page-errors.ts

@@ -72,7 +72,7 @@ export class RecordRejectedError extends RealtimeError {
     super({
       code: 'X_RECORD_REJECTED',
       cause: `a ${args.type === '' ? 'record' : `"${args.type}" record`} was rejected by the page's record store: ${args.reason}`,
-      fix: `x entities describe ${renderFixShellArg(args.type, '<entity>')} --json   # the primary key every row of it must carry; return whole rows from the handler that built this one`,
+      fix: `x entities show ${renderFixShellArg(args.type, '<entity>')} --json   # the primary key every row of it must carry; return whole rows from the handler that built this one`,
     });
   }
 }

package/src/page-runtime-wait.ts

@@ -7,8 +7,8 @@ import { deferredScriptsPending, peekPageRealtime } from './page-store';
 
 export interface AwaitPageRuntimeOptions {
   /**
-   * The path every page boot is served under (`/_x/page-boot/`). A `<script>` whose `src` starts
-   * with it is the boot this document carries, and the runtime is coming with it.
+   * The path every page boot is served under (`/_x/assets/page-boot/`). A `<script>` whose `src`
+   * starts with it is the boot this document carries, and the runtime is coming with it.
    */
   readonly boot: string;
   /** Imports the runtime chunk — only on a page whose boot is absent, or never ran. */

package/src/sync-upgrade.ts

@@ -115,11 +115,28 @@ export interface UpgradeDeps {
 /**
  * `undefined` means the upgrade took and Bun owns the connection now. Async because `authenticate`
  * is: the credential is decided *before* `server.upgrade`, so a refused one never costs a websocket.
+ *
+ * Every answer that is NOT a socket is `no-store`, whatever it is: a response with no
+ * `cache-control` is one a CDN applies its own default TTL to, and this role sits behind an
+ * operator's routing rule that can send it what it does not serve — a page asset misrouted here
+ * came back `404 not found`, and the edge kept that miss for four hours after the fix.
  */
 export async function handleUpgrade(
   deps: UpgradeDeps,
   request: Request,
   server: UpgradeTarget,
+): Promise<Response | undefined> {
+  const response = await answerUpgrade(deps, request, server);
+  if (response !== undefined && !response.headers.has('cache-control')) {
+    response.headers.set('cache-control', 'no-store');
+  }
+  return response;
+}
+
+async function answerUpgrade(
+  deps: UpgradeDeps,
+  request: Request,
+  server: UpgradeTarget,
 ): Promise<Response | undefined> {
   const url = new URL(request.url);
   // Health is the process's, readiness is this node's: a draining node stays healthy while it hands

package/src/sync-worker.ts

@@ -1,6 +1,6 @@
 // The SharedWorker entry (plan 101, slice 11): every tab of this origin and principal connects a
 // port, and the one engine behind them holds the one socket. `x build` bundles this file as a
-// classic script at `/_x/sync-worker/<hash>.js`. No other code lives here.
+// classic script at `/_x/assets/sync-worker/<hash>.js`. No other code lives here.
 
 import { browserSocket, dialUrl } from './browser-socket';
 import { messagePort, SocketEngine } from './socket-engine';