@ultimat3/realtime 23.0.0 → 25.0.0

package/src/page-outbox.ts

@@ -1,13 +1,10 @@
 /**
- * The page's ONE outbox: writes a page could not send are queued in `OfflineQueue`, persisted in
- * the page's durable store under the current principal, and replayed IN ORDER over HTTP — each to
- * `actionPath(name)` through core's `clientTransport`, each with its own idempotency key, so a
- * replay after a lost response is answered from the action's idempotency store and never applied
- * twice. Replayed on open, on `online`, and on the service worker's `OUTBOX_DRAIN_MESSAGE`.
- * A principal change wipes the previous principal's queue: its writes are never sent as the next.
+ * The page's ONE outbox: writes a page could not send, persisted under the current principal and
+ * replayed IN ORDER over HTTP, each under its own idempotency key. AT LEAST once — an entry leaves
+ * the disk when its ack is written. A principal change abandons the pass and wipes the queue.
  */
 
-import type { ClientScope } from '@ultimat3/core/page';
+import type { ClientScope, UltimateError } from '@ultimat3/core/page';
 import {
   actionPath,
   classifyThrown,
@@ -15,12 +12,14 @@ import {
   OUTBOX_DRAIN_MESSAGE,
   onRescope,
   pageClient,
+  renderThrowable,
 } from '@ultimat3/core/page';
 import type { LocalStore } from './local-store-idb';
 import { pageLocalStore, scopeKey } from './local-store-idb';
 import type { DrainReport, QueuedMutation, QueueState, QueueStore } from './offline-queue';
-import { MemoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
+import { memoryQueueStore, OfflineQueue, toQueueError } from './offline-queue';
 import { OUTBOX_KEY, type OutboxEntry, type OutboxHandle, type OutboxHost } from './outbox-slot';
+import { LocalStoreUnavailableError, OfflineQueueAbandonedError } from './page-errors';
 import { peekPageRealtime } from './page-store';
 import { carriedBy } from './record-store';
 
@@ -63,70 +62,142 @@ export interface OutboxOptions {
    * the write queued and the post it liked missing, and showed the old count.
    */
   readonly beforeEnqueue?: (() => Promise<void>) | undefined;
+  /** Where a disk that refused the queue is said, by code. Default `console.warn`. */
+  readonly warn?: ((error: UltimateError) => void) | undefined;
 }
 
 const EMPTY: DrainReport = { sent: 0, collapsed: 0, remaining: 0, stoppedAt: null };
 
-export function createOutbox(options: OutboxOptions): PageOutbox {
+/** One principal's open queue, and the scope the drain lock is named after. */
+interface Held {
+  readonly queue: OfflineQueue;
+  readonly scope: string | undefined;
+}
+
+export function localOutbox(options: OutboxOptions): PageOutbox {
   const principal =
     options.principal ?? ((): ClientScope['principal'] => pageClient().scope.principal);
   const send = options.send ?? sendOverHttp;
   const overlays =
     options.overlays ?? ((): OutboxOverlays | undefined => peekPageRealtime()?.store);
-  let queue: OfflineQueue | undefined;
-  /** The scope the open queue belongs to — what the drain lock is named after. */
-  let scope: string | undefined;
+  /**
+   * The open queue AND the scope it belongs to, as one value: a pass captures both when it starts,
+   * so nothing it does later can be read off a principal that arrived since.
+   */
+  let held: Held | undefined;
+  /**
+   * Bumped by every principal change, SYNCHRONOUSLY. Anything here that resolves a queue after an
+   * await compares it first: the answer to "whose queue" must be the one from before the await.
+   */
+  let epoch = 0;
+  const warn = options.warn ?? ((error: UltimateError): void => console.warn(error));
+  const unavailable = (what: string, error: unknown): void =>
+    warn(new LocalStoreUnavailableError({ reason: `${what}: ${renderThrowable(error)}` }));
 
+  /** Never rejects: a queue the disk would not open is a memory queue, said once by code. */
   const open = async (): Promise<void> => {
-    scope = scopeKey(principal());
-    queue = await OfflineQueue.open(queueStore(await options.local, scope));
-  };
-  let ready = open();
-  let running: Promise<DrainReport> | undefined;
-  /** A trigger landed while a pass ran: one more pass follows it, never one per trigger. */
-  let again = false;
-
-  const deliver = async (mutation: QueuedMutation): Promise<void> => {
-    const current = queue;
-    const carried = new Set<string>();
+    const at = epoch;
+    const scope = scopeKey(principal());
+    let queue: OfflineQueue;
     try {
-      await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+      queue = await OfflineQueue.open(queueStore(await options.local, scope));
     } catch (error) {
-      const kind = classifyThrown(error);
-      // The network, or a server asking to be asked again: stays queued, and the pass stops so
-      // nothing behind it overtakes it.
-      if (kind === 'retryable' || kind === 'retry-after') throw error;
-      // Anything else is the server's decision about this write — kept for the UI, never resent.
-      await current?.fail(mutation.key, toQueueError(error));
-      overlays()?.drop(mutation.key);
+      unavailable('the outbox could not be opened', error);
+      queue = await OfflineQueue.open(memoryQueueStore());
+    }
+    // The principal left while the disk was being read: this queue is the one that left with it,
+    // and the handler that saw the change has already chained the next open.
+    if (at !== epoch) {
+      queue.abandon();
       return;
     }
-    await current?.ack(mutation.key);
-    const store = overlays();
-    try {
-      // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
-      // the server's row for it arrives.
-      store?.settle(mutation.key, carried);
-    } catch {
-      // A custom merge that answered no row: the server's truth stands.
-      store?.drop(mutation.key);
+    held?.queue.abandon();
+    held = { queue, scope };
+  };
+  let ready = open();
+  /** The current principal's queue: `ready` is re-made by a rescope, so it is re-read until still. */
+  const current = async (): Promise<Held | undefined> => {
+    for (;;) {
+      const opening = ready;
+      await opening;
+      if (opening === ready) return held;
     }
   };
+  let running: Promise<DrainReport> | undefined;
+  /** A trigger landed while a pass ran: one more pass follows it, never one per trigger. */
+  let again = false;
+
+  const deliver =
+    (queue: OfflineQueue) =>
+    async (mutation: QueuedMutation): Promise<void> => {
+      const carried = new Set<string>();
+      try {
+        await send({ key: mutation.key, name: mutation.name, input: mutation.input }, carried);
+      } catch (error) {
+        const kind = classifyThrown(error);
+        // The network, or a server asking to be asked again: stays queued, and the pass stops so
+        // nothing behind it overtakes it. So does a queue whose principal left mid-send.
+        if (kind === 'retryable' || kind === 'retry-after' || queue.abandoned) throw error;
+        // Anything else is the server's decision about this write — kept for the UI, never resent.
+        await queue.fail(mutation.key, toQueueError(error));
+        overlays()?.drop(mutation.key);
+        return;
+      }
+      // The principal changed while this was on the wire: its store and its twins are already
+      // gone, and what is on the page now is somebody else's.
+      if (queue.abandoned) return;
+      await queue.ack(mutation.key);
+      const store = overlays();
+      try {
+        // Exactly as a live write settles: a row the answer did not carry keeps its overlay until
+        // the server's row for it arrives.
+        store?.settle(mutation.key, carried);
+      } catch {
+        // A custom merge that answered no row: the server's truth stands.
+        store?.drop(mutation.key);
+      }
+    };
 
   onRescope((_next, prev) => {
     const gone = scopeKey(prev.principal);
+    // SYNCHRONOUSLY, before anything is awaited: a pass parked inside `send` resumes into the next
+    // principal's session, and the wipe below reaches the disk but never the pass. Abandoned, it
+    // sends nothing more and writes nothing back.
+    held?.queue.abandon();
+    held = undefined;
+    epoch += 1;
+    // The single-flight slot is the principal's too: left set, the next principal's trigger JOINED
+    // the abandoned pass — handed its report, another principal's key in it — and its own queue
+    // was not drained until some later trigger. `settled` only clears a slot that is still its own.
+    running = undefined;
+    again = false;
     ready = ready.then(async () => {
-      if (gone !== undefined) await (await options.local).wipe(gone);
+      try {
+        if (gone !== undefined) await (await options.local).wipe(gone);
+      } catch (error) {
+        // Still on disk, under the scope that left: unreachable from this principal, and the next
+        // boot's `wipeOthers` takes it. Said, never thrown — a rejection here used to poison the
+        // chain, so every later enqueue, replay and rescope on this tab failed with it.
+        unavailable("the previous principal's outbox could not be wiped", error);
+      }
       await open();
     });
   });
 
   const self: PageOutbox = {
     enqueue: async (entry) => {
+      // WHOSE queue is decided now, before anything is awaited: resolved after the flush below,
+      // a write issued under one principal and parked there was queued — and sent — as the next.
+      // A queue still opening is waited for, and belongs to this call only if nobody left since.
+      const at = epoch;
+      const mine = held ?? (await current());
+      if (mine === undefined || at !== epoch) {
+        throw new OfflineQueueAbandonedError({ name: entry.name });
+      }
       // A disk that refused the rows must not also cost the write: the intent still goes on disk.
       await options.beforeEnqueue?.().catch(() => undefined);
-      await ready;
-      await queue?.enqueue(entry);
+      // Abandoned meanwhile, it refuses by the same code.
+      await mine.queue.enqueue(entry);
     },
     replay: () => {
       // Single flight: a trigger that lands while a replay is running JOINS it. Open, `online`,
@@ -140,20 +211,19 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
         return running;
       }
       const pass = (async (): Promise<DrainReport> => {
-        await ready;
-        if (queue === undefined) return EMPTY;
+        const now = await current();
+        if (now === undefined) return EMPTY;
         // Checked when the pass STARTS, whoever asked (the socket's reconnect asks too): an
         // attempt the browser already knows cannot leave is a failed request on the wire and
         // nothing more. `online` asks again.
-        if (knownOffline()) return { ...EMPTY, remaining: queue.pending().length };
-        const draining = queue;
+        if (knownOffline()) return { ...EMPTY, remaining: now.queue.pending().length };
         // One tab drains a principal's outbox at a time, and it drains what EVERY tab queued: the
         // queue is re-read under the lock, so a write another tab made since this one opened is
         // sent too, and an `inflight` entry — which only a pass holding this lock could have put
         // on the wire, and it is over — goes back to `pending`.
-        return await exclusive(`ultimate-outbox:${scope ?? 'memory'}`, async () => {
-          await draining.reload();
-          return await draining.drain(deliver);
+        return await exclusive(`ultimate-outbox:${now.scope ?? 'memory'}`, async () => {
+          await now.queue.reload();
+          return await now.queue.drain(deliver(now.queue));
         });
       })();
       const settled = (report?: DrainReport): void => {
@@ -172,9 +242,10 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
       return pass;
     },
     get size(): number {
-      return queue?.pending().length ?? 0;
+      return held?.queue.pending().length ?? 0;
     },
-    pending: () => (queue?.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
+    pending: () =>
+      (held?.queue.pending() ?? []).map(({ key, name, input }) => ({ key, name, input })),
     get ready(): Promise<void> {
       return ready;
     },
@@ -184,7 +255,7 @@ export function createOutbox(options: OutboxOptions): PageOutbox {
 
 /** Persisted under the principal; an UNSCOPED page queues in memory only, and loses it on reload. */
 function queueStore(local: LocalStore, scope: string | undefined): QueueStore {
-  if (scope === undefined) return new MemoryQueueStore();
+  if (scope === undefined) return memoryQueueStore();
   return {
     load: async (): Promise<QueueState> =>
       (await local.queue(scope)) ?? { mutations: [], nextSeq: 1 },
@@ -255,7 +326,7 @@ export function pageOutbox(options: Pick<OutboxOptions, 'beforeEnqueue'> = {}):
   const existing = host[OUTBOX_KEY];
   // Only this function writes the slot, so what it holds is always a `PageOutbox`.
   if (existing !== undefined) return existing as PageOutbox;
-  const outbox = createOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
+  const outbox = localOutbox({ local: pageLocalStore(), beforeEnqueue: options.beforeEnqueue });
   Object.defineProperty(host, OUTBOX_KEY, { value: outbox, configurable: true });
   if (Reflect.has(globalThis, 'document')) {
     listenForDrain(outbox);

package/src/page-runtime-wait.ts

@@ -0,0 +1,72 @@
+// What a realtime island waits on before its first hook runs: the page runtime, installed ONCE per
+// page. A document the server rendered for a principal carries it in the page boot (a deferred
+// classic script); every other document — a static export, an anonymous page, an app with no sync
+// node — gets it from the runtime chunk the island loads itself. Never both, never twice.
+
+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.
+   */
+  readonly boot: string;
+  /** Imports the runtime chunk — only on a page whose boot is absent, or never ran. */
+  readonly load: () => Promise<unknown>;
+}
+
+type Listenable = {
+  addEventListener(type: string, listener: () => void, options?: { once?: boolean }): void;
+};
+
+const installed = (): boolean => {
+  const page = peekPageRealtime();
+  return page?.store !== undefined && page.services !== undefined;
+};
+
+/**
+ * Resolves once the page runtime is installed. An island can be imported while the parser still
+ * waits on the deferred boot (the idle callback fires first), so a boot that may still run is
+ * waited for — its `load`, its `error`, or DOMContentLoaded, which fires after every deferred
+ * script — and a page it never installed the runtime on loads the chunk. Never on a FUTURE event
+ * once the deferred scripts are done: a boot that failed before the island asked fires none again.
+ */
+export async function awaitPageRuntime(options: AwaitPageRuntimeOptions): Promise<void> {
+  if (installed()) return;
+  const boot = bootElement(options.boot);
+  if (boot !== undefined) await firstOf(boot);
+  if (!installed()) await options.load();
+}
+
+/** The page boot's `<script>` while it may still run; `undefined` once it cannot, or with none. */
+function bootElement(prefix: string): Listenable | undefined {
+  const doc: unknown = Reflect.get(globalThis, 'document');
+  if (typeof doc !== 'object' || doc === null) return undefined;
+  // Every deferred script has run: a boot that installed nothing failed, and is not coming.
+  if (!deferredScriptsPending()) return undefined;
+  const query: unknown = Reflect.get(doc, 'querySelector');
+  // A partial document (a component test's stand-in) has no query surface: no tag, no boot.
+  if (typeof query !== 'function') return undefined;
+  const found: unknown = Reflect.apply(query, doc, [`script[src^="${prefix}"]`]);
+  return isListenable(found) ? found : undefined;
+}
+
+function isListenable(value: unknown): value is Listenable {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof Reflect.get(value, 'addEventListener') === 'function'
+  );
+}
+
+/** The boot ran, failed, or every deferred script is done — whichever comes first. */
+function firstOf(boot: Listenable): Promise<void> {
+  return new Promise<void>((resolve) => {
+    const done = (): void => resolve();
+    boot.addEventListener('load', done, { once: true });
+    boot.addEventListener('error', done, { once: true });
+    const doc: unknown = Reflect.get(globalThis, 'document');
+    if (isListenable(doc)) doc.addEventListener('DOMContentLoaded', done, { once: true });
+    if (typeof addEventListener === 'function') addEventListener('load', done, { once: true });
+  });
+}

package/src/page-runtime.ts

@@ -0,0 +1,32 @@
+// The page runtime: the ONE record store, the socket stack, the query client and core's transport
+// behind every hook, installed once per page onto the page object (`page-store.ts`). Never in an
+// island: the page boot carries it where the server renders one, and the CLI builds it as the
+// runtime chunk an island loads where it does not (`packages/cli/src/island-realtime.ts`).
+
+import { clientTransport, onRescope, pageClient } from '@ultimat3/core/page';
+import { queryClientMethodFor } from '@ultimat3/query/client';
+import { pageSocket } from './page-socket';
+import { type InstalledPage, pageRealtime } from './page-store';
+import { RecordStore } from './record-store';
+
+/**
+ * Get-or-install, idempotent: the boot and the runtime chunk may both run on one page (a boot that
+ * arrived after its island gave up on it), and whichever runs second adopts what the first built.
+ * Installs the store as core's `RecordSink`, so every HTTP answer's records land in it.
+ */
+export function installPageRuntime(): InstalledPage {
+  const page = pageRealtime();
+  const store = page.store;
+  if (store !== undefined && page.services !== undefined) return page as InstalledPage;
+  const created = store ?? new RecordStore();
+  page.store = created;
+  page.services = {
+    socket: pageSocket,
+    read: (name) => queryClientMethodFor(name, { baseUrl: '' }),
+    send: clientTransport,
+  };
+  pageClient().store = created;
+  // A new principal sees nothing of the previous one: every record goes, in memory, at once.
+  onRescope(() => created.clear());
+  return page as InstalledPage;
+}

package/src/page-socket.ts

@@ -1,6 +1,6 @@
-// The page's ONE socket: built on the first live or channel hook, by whichever island bundle asks
-// first, and shared by every other one through the page state. A form-only island never imports
-// this module, so it ships none of the connection lifecycle.
+// The page's ONE socket: built on the first live or channel hook, and shared by every island
+// through the page state. Part of the page runtime (`page-runtime.ts`), so no island bundle carries
+// the connection lifecycle: a hook reaches it as `services.socket`, off the page object.
 
 import { onRescope, pageClient } from '@ultimat3/core/page';
 import { queryClientMethodFor } from '@ultimat3/query/client';
@@ -8,7 +8,7 @@ import { LiveClient } from './client';
 import { DEFAULT_HEARTBEAT_MS } from './client-heartbeat';
 import { peekOutbox } from './outbox-slot';
 import { SyncUnconfiguredError } from './page-errors';
-import { pageRealtime } from './page-store';
+import { installedPage } from './page-store';
 import {
   openHost,
   type RehostingHost,
@@ -20,7 +20,7 @@ import { pageSyncTarget, syncWorkerFromMeta } from './sync-meta';
 
 /** Get-or-create, and connect on creation. `hook` names the caller in the refusal. */
 export function pageSocket(hook: string): LiveClient {
-  const page = pageRealtime();
+  const page = installedPage(hook);
   // Its one writer is below, so the stored value is always this class — from SOME bundle's copy,
   // which is why it is read structurally and never checked with `instanceof`.
   if (page.socket !== undefined) return page.socket as LiveClient;
@@ -110,17 +110,8 @@ export function resetPageSocket(
   hosts = options.openHost ?? openHost;
 }
 
-/**
- * Whether this page holds a socket — `false` on a server render and before any live hook ran.
- * The guard a component with a static fallback asks (an offline banner, an update prompt).
- */
-export function hasPageSocket(): boolean {
-  const host = globalThis as { [key: symbol]: unknown };
-  const page = host[Symbol.for('ultimate.realtime')];
-  return (
-    typeof page === 'object' && page !== null && (page as { socket?: unknown }).socket !== undefined
-  );
-}
+/** Where `hasPageSocket` lives, re-exported for the callers that reach it from here. */
+export { hasPageSocket } from './page-store';
 
 function hostFor(scope: string | null, buildId: string): SocketHost {
   const workerUrl =

package/src/page-store.ts

@@ -1,9 +1,14 @@
-// The page's realtime state: ONE record store and ONE sync target per tab, whichever island bundle
-// asks first. On `globalThis` under a `Symbol.for` key, because every island is its own bundle and
-// a module-scope singleton here is one store PER ISLAND — the bug this file exists to end.
+// The page's realtime state as every island READS it: one object per tab on `globalThis` under a
+// `Symbol.for` key, because every island is its own bundle and a module-scope singleton here is
+// one store PER ISLAND. Thin by design — the store, the socket and the transport behind it are the
+// page runtime's (`page-runtime.ts`), shipped once per page and never inside an island (#505).
 
-import { CLIENT_SCOPE_META, onRescope, pageClient } from '@ultimat3/core/page';
-import { RecordStore } from './record-store';
+import type { clientTransport } from '@ultimat3/core/page';
+import { CLIENT_SCOPE_META } from '@ultimat3/core/page';
+import type { queryClientMethodFor } from '@ultimat3/query/client';
+import type { LiveClient } from './client';
+import { RealtimeUninstalledError } from './page-errors';
+import type { RecordStore } from './record-store';
 
 /** Where the page's one socket dials. Resolved on the server and handed to the island bootstrap. */
 export interface SyncTarget {
@@ -15,7 +20,12 @@ export interface SyncTarget {
 
 /** Page-wide and shared by every bundle. Structural on purpose: no `instanceof` across copies. */
 export interface PageRealtime {
-  readonly store: RecordStore;
+  /**
+   * The page's ONE record store — `undefined` until the page runtime is installed (the page boot,
+   * or the runtime chunk an island loads where no boot is rendered). A hook reads it through
+   * `installedPage`, which refuses by code rather than answering a store nobody shares.
+   */
+  store: RecordStore | undefined;
   sync: SyncTarget | undefined;
   /** The socket client, once a live hook opened it. Typed by `page-socket.ts`, its one writer. */
   socket: unknown;
@@ -27,8 +37,30 @@ export interface PageRealtime {
    * the first frame can race it. Resolved at once on a page that carries no boot script.
    */
   readonly booted: Promise<void>;
+  /** What a hook calls instead of bundling it — installed with the store, by the page runtime. */
+  services: PageServices | undefined;
+}
+
+/**
+ * The runtime's half of every hook: the work whose code would otherwise ship in each island. An
+ * island calls these off the page object, so the socket stack, the query client and core's
+ * transport are in the page runtime once, however many islands the page renders.
+ */
+export interface PageServices {
+  /** The page's one socket, opened on the first ask. `hook` names the caller in a refusal. */
+  socket(hook: string): LiveClient;
+  /** A non-live query read over HTTP — `@ultimat3/query`'s client, through core's transport. */
+  read(name: string): ReturnType<typeof queryClientMethodFor>;
+  /** Core's one transport, for a write's POST. */
+  send: typeof clientTransport;
 }
 
+/** The page once its runtime is installed: what every hook works against. */
+export type InstalledPage = PageRealtime & {
+  readonly store: RecordStore;
+  readonly services: PageServices;
+};
+
 /** Every optimistic write on the page, counted per mutator name, and who renders the counts. */
 export interface PageWrites {
   readonly pending: Map<string, number>;
@@ -86,9 +118,32 @@ export function bootedPromise(): Promise<void> {
   return waiting;
 }
 
+/**
+ * Whether a deferred `<script>` of this document may still run. Not past `loading`, yes; past
+ * `complete`, no. In between (`interactive`) the deferred scripts run, then DOMContentLoaded fires —
+ * and `readyState` stays `interactive` until every image has loaded, so the navigation timing's
+ * `domContentLoadedEventStart` is what says they have all run (a boot that 404'd among them). A
+ * document with no such reading is assumed still running them: a caller then waits on DOMContentLoaded.
+ */
+export function deferredScriptsPending(): boolean {
+  if (typeof document === 'undefined') return false;
+  const state: unknown = document.readyState;
+  if (state === 'complete') return false;
+  if (state !== 'interactive') return true;
+  const timing: unknown =
+    typeof performance === 'undefined' || typeof performance.getEntriesByType !== 'function'
+      ? undefined
+      : performance.getEntriesByType('navigation')[0];
+  const started: unknown =
+    typeof timing === 'object' && timing !== null
+      ? Reflect.get(timing, 'domContentLoadedEventStart')
+      : undefined;
+  return !(typeof started === 'number' && started > 0);
+}
+
 function bootComing(): boolean {
   if (typeof document === 'undefined' || typeof addEventListener !== 'function') return false;
-  if (document.readyState === 'complete') return false;
+  if (!deferredScriptsPending()) return false;
   // A partial `document` (a component test's stand-in) has no query surface: no tag, no boot.
   if (typeof document.querySelector !== 'function') return false;
   return document.querySelector(`meta[name="${CLIENT_SCOPE_META}"]`) !== null;
@@ -96,25 +151,25 @@ function bootComing(): boolean {
 
 type Host = { [KEY]?: PageRealtime };
 
-/** Get-or-create. Installs the store as core's `RecordSink`, so HTTP answers adopt into it. */
+/**
+ * Get-or-create the page object — never its runtime: an island that asks before the runtime is
+ * installed (`installRealtime` seating a sync target) gets the object the runtime then fills.
+ */
 export function pageRealtime(): PageRealtime {
   const host = globalThis as Host;
   const existing = host[KEY];
   if (existing !== undefined) return existing;
-  const store = new RecordStore();
   const created: PageRealtime = {
-    store,
+    store: undefined,
     sync: undefined,
     socket: undefined,
     writes: { pending: new Map(), failed: 0, listeners: new Set() },
     get booted(): Promise<void> {
       return bootedPromise();
     },
+    services: undefined,
   };
   Object.defineProperty(host, KEY, { value: created, configurable: true });
-  pageClient().store = store;
-  // A new principal sees nothing of the previous one: every record goes, in memory, at once.
-  onRescope(() => store.clear());
   return created;
 }
 
@@ -123,6 +178,18 @@ export function peekPageRealtime(): PageRealtime | undefined {
   return (globalThis as Host)[KEY];
 }
 
+/**
+ * The page with its runtime installed, or `X_REALTIME_UNINSTALLED` naming `hook`. An island `x
+ * build` wrapped never sees the refusal — its bootstrap awaits the runtime before any hook runs.
+ */
+export function installedPage(hook: string): InstalledPage {
+  const page = pageRealtime();
+  if (page.store === undefined || page.services === undefined) {
+    throw new RealtimeUninstalledError({ hook });
+  }
+  return page as InstalledPage;
+}
+
 /**
  * Whether this page holds a socket — `false` on a server render and before any live hook ran.
  * The guard a component with a static fallback asks (an offline banner, an update prompt). Here,
@@ -132,7 +199,7 @@ export function hasPageSocket(): boolean {
   return peekPageRealtime()?.socket !== undefined;
 }
 
-/** The page's record store. */
-export function pageStore(): RecordStore {
-  return pageRealtime().store;
+/** The page's record store, from its installed runtime. */
+export function pageStore(hook = 'pageStore'): RecordStore {
+  return installedPage(hook).store;
 }