eraspace 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eraspace",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "eraspace: build, deploy and manage eraspace capsules",
   "type": "module",
   "keywords": [
@@ -8,7 +8,7 @@
     "cli",
     "realtime",
     "preact",
-    "beam"
+    "v8"
   ],
   "license": "MIT",
   "bin": {
@@ -24,10 +24,8 @@
     "@preact/signals": "2.11.3",
     "@tailwindcss/node": "4.3.3",
     "@tailwindcss/oxide": "4.3.3",
-    "@types/phoenix": "1.6.7",
     "esbuild": "0.28.2",
     "oxc-parser": "0.154.0",
-    "phoenix": "1.8.15",
     "preact": "11.0.1",
     "preact-iso": "2.12.2",
     "tailwindcss": "4.3.3",

package/sdk/src/client/client.ts

@@ -1,11 +1,13 @@
 import { computed, type ReadonlySignal } from "@preact/signals";
-import { useEffect, useMemo, useRef } from "preact/hooks";
+import { useEffect, useMemo, useRef, useState } from "preact/hooks";
 import { createStorageClient } from "./storage.ts";
-import type { ClientOptions } from "./config.ts";
+import { useUpload, type UseUploadOptions } from "./files.ts";
+import { readConfig, type ClientOptions } from "./config.ts";
 import { subKey, stableStringify } from "./sub-key.ts";
 import type { Subscription } from "./subscription.ts";
 import type { RoomConn } from "./room.ts";
 import type { EraspaceClient, Room } from "./types.ts";
+import { EraspaceError } from "./errors.ts";
 import { ClientImpl } from "./connection.ts";
 import { Pager } from "./pagination.ts";
 
@@ -21,8 +23,10 @@ type Fn = (...args: any[]) => any;
  */
 export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C> {
   let impl: ClientImpl | undefined;
-  // Lazy so a module-level createClient() costs nothing until first use.
+  // Lazy so a module-level createClient() costs nothing until first use, except in a browser page that reloads on
+  // deploy (the platform shell's default), where the client connects at once to hear deploys.
   const get = () => (impl ??= new ClientImpl(options));
+  if (typeof location !== "undefined" && (options.reloadOnDeploy ?? readConfig().app)) get().watchDeploys();
 
   function useSubscription(name: string, args: unknown[]): Subscription {
     const c = get();
@@ -39,7 +43,8 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
     return useMemo(() => computed(() => {
       const err = sub.error.value;
       const value: unknown = sub.value.value;
-      if (err && value === undefined) throw err;
+      // Retried failures keep showing the last value; a gone app cannot recover.
+      if (err && (value === undefined || err.name === "AppGone")) throw err;
       return value;
     }), [sub]);
   }
@@ -61,7 +66,7 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
   }
 
   function useAction(name: string) {
-    return useMemo(() => (...args: unknown[]) => get().call(name, args), [name]);
+    return useMemo(() => (...args: unknown[]) => get().call(name, args, "action"), [name]);
   }
 
   function usePaginatedQuery(name: string, args: unknown[], opts?: { initialNumItems?: number }) {
@@ -85,8 +90,17 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
 
   function useRoomConn(room: string, meta: Record<string, unknown> | undefined): RoomConn {
     const c = get();
-    const r = useMemo(() => c.acquireRoom(room), [room]);
-    useEffect(() => () => c.releaseRoom(r), [r]);
+    const [generation, renew] = useState(0);
+    // Acquiring during render holds nothing: only a committed effect retains the room.
+    const r = useMemo(() => c.acquireRoom(room), [room, generation]);
+    useEffect(() => {
+      if (!c.retainRoom(r)) {
+        // Dropped between render and commit.
+        renew((n) => n + 1);
+        return;
+      }
+      return () => c.releaseRoom(r);
+    }, [r]);
     const metaKey = meta === undefined ? undefined : stableStringify(meta);
     useEffect(() => {
       if (meta !== undefined) r.setMeta(meta);
@@ -104,8 +118,9 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
       presence: r.members.value,
       self: r.self.value,
       state: r.state.value,
+      error: r.error.value,
       broadcast: (event: string, payload?: unknown) => {
-        r.channel.push("broadcast", { event, payload: payload ?? null });
+        void r.channel.push("broadcast", { event, payload: payload ?? null }).catch(error => { r.error.value = EraspaceError.from(error); });
       },
       on: (event: string, cb: (payload: any, from: string | undefined) => void) => {
         let set = r.listeners.get(event);
@@ -114,14 +129,15 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
         return () => set!.delete(cb);
       },
       setState: (key: string, value: unknown) => {
-        r.state.value = { ...r.state.peek(), [key]: value };
-        r.channel.push("state:set", { key, value: value ?? null });
+        r.setState(key, value);
       },
     };
   }
 
+  const storage = createStorageClient(() => get().base);
   const client = {
-    storage: createStorageClient(() => get().base),
+    storage,
+    useUpload: (opts?: UseUploadOptions) => useUpload(storage, opts),
     useQuery,
     useQuerySignal,
     useQuerySelector,
@@ -131,8 +147,9 @@ export function createClient<C>(options: ClientOptions = {}): EraspaceClient<C>
     usePresence,
     useRoom,
     query: (name: string, ...args: unknown[]) => get().call(name, args),
-    mutation: (name: string, ...args: unknown[]) => get().call(name, args),
-    action: (name: string, ...args: unknown[]) => get().call(name, args),
+    mutation: (name: string, ...args: unknown[]) => get().mutate(name, args),
+    retryMutation: (name: string, args: unknown[], requestKey: string) => get().retryMutation(name, args, requestKey),
+    action: (name: string, ...args: unknown[]) => get().call(name, args, "action"),
     subscribe: (name: string, args: unknown[], onValue: Fn, onError?: Fn) => get().subscribe(name, args, onValue, onError),
     get app() {
       return get().app;

package/sdk/src/client/config.ts

@@ -1,9 +1,23 @@
+import type { SocketOptions, WebSocketConstructor } from "./transport.ts";
+
+/** A query result the shell embedded, as a `sub` reply would carry it. */
+export interface InitialResult {
+  fn: string;
+  args: unknown[];
+  value: unknown;
+  commitSeq: number;
+  revision: number;
+  entry: string;
+}
+
 /** `window.__ERASPACE__`, injected by the platform's HTML shell (SPEC §6). */
 export interface EraspaceConfig {
   app: string;
   base: string;
   version: number;
   socket: string;
+  /** Current results of the queries the app's pages usually open first. */
+  initial?: InitialResult[];
 }
 
 export interface ClientOptions {
@@ -12,7 +26,11 @@ export interface ClientOptions {
   socket?: string;
   base?: string;
   version?: number;
-  /** Reload the page when the app is redeployed (after re-subscribing). Default `false`. */
+  /**
+   * Reload the page when the app is redeployed, so a deploy reaches open tabs without a manual refresh. Default
+   * `true` for the shell's own app on pages served by the platform shell (`window.__ERASPACE__` is set), otherwise
+   * `false`. When enabled in a browser, the client connects at creation rather than on first use.
+   */
   reloadOnDeploy?: boolean;
   /** Push timeout in ms. Default 15000. */
   timeout?: number;
@@ -21,9 +39,9 @@ export interface ClientOptions {
   /** Delay before refreshing a subscription still waiting for a mutation commit. Default 2000 ms. */
   optimisticTimeoutMs?: number;
   /** WebSocket constructor (tests, non-browser runtimes). */
-  transport?: unknown;
-  /** Extra Phoenix socket options. */
-  socketOptions?: Record<string, unknown>;
+  transport?: WebSocketConstructor;
+  /** Reconnect and rejoin delay overrides. */
+  socketOptions?: Pick<SocketOptions, "reconnectAfterMs" | "rejoinAfterMs">;
 }
 
 declare global {

package/sdk/src/client/connection.ts

@@ -1,11 +1,13 @@
-import { Socket, type Channel } from "phoenix";
+import { Socket, type Channel } from "./transport.ts";
 import { signal, effect, batch, type Signal } from "@preact/signals";
 import { applyPatch } from "./result-diff.ts";
-import { EraspaceError } from "./errors.ts";
-import { readConfig, type ClientOptions } from "./config.ts";
-import { subKey } from "./sub-key.ts";
-import { Subscription, type FullResult, type DataMessage } from "./subscription.ts";
+import { EraspaceError, OutcomeUnknownError } from "./errors.ts";
+import { readConfig, type ClientOptions, type InitialResult } from "./config.ts";
+import { requestKey } from "./request-key.ts";
+import { canonicalArgs, subKey } from "./sub-key.ts";
+import { Subscription, type FullResult, type UnchangedResult, type DataMessage } from "./subscription.ts";
 import { RoomConn } from "./room.ts";
+import { retryDelay } from "./retry.ts";
 import type { Status } from "./types.ts";
 
 type Fn = (...args: any[]) => any;
@@ -16,17 +18,25 @@ export class ClientImpl {
   readonly self = signal("");
   readonly status = signal<Status>("connecting");
   readonly version: Signal<number>;
+  readonly reloadOnDeploy: boolean;
   private opts: ClientOptions;
   private socketUrl: string;
   private socket: Socket | undefined;
   private channel: Channel | undefined;
   private joinedOnce = false;
+  /** Counts app channel joins. Server subscription ids live only as long as the join that created them. */
+  private joins = 0;
+  /** Server time minus local time, from the latest join reply. */
+  private clockOffset = 0;
+  private gone: EraspaceError | undefined;
   private nextSub = 1;
   private nextMutation = 1;
   private subs = new Map<string, Subscription>();
   private subsById = new Map<string, Subscription>();
   private rooms = new Map<string, RoomConn>();
   private deployedCbs = new Set<(v: number) => void>();
+  /** Results the shell embedded, by subscription key, each used by the first subscription to it. */
+  private initial = new Map<string, InitialResult>();
 
   constructor(opts: ClientOptions) {
     const cfg = readConfig();
@@ -35,23 +45,31 @@ export class ClientImpl {
     if (!this.app) throw new Error("eraspace: createClient() needs an app (window.__ERASPACE__ is missing)");
     this.base = opts.base ?? cfg.base ?? `/${this.app}/`;
     this.socketUrl = opts.socket ?? cfg.socket ?? "/socket";
-    this.version = signal(opts.version ?? cfg.version ?? 0);
+    // The shell's version and reload default describe the page's own app, not another app it talks to.
+    const ownApp = !opts.app || opts.app === cfg.app;
+    this.version = signal(opts.version ?? (ownApp ? cfg.version : undefined) ?? 0);
+    this.reloadOnDeploy = opts.reloadOnDeploy ?? (ownApp && Boolean(cfg.app));
+    if (ownApp && Array.isArray(cfg.initial)) {
+      for (const r of cfg.initial) if (typeof r?.fn === "string" && Array.isArray(r.args)) this.initial.set(subKey(r.fn, r.args), r);
+    }
+  }
+
+  /** Join the app topic now when deploys reload the page, so a page that has not queried yet still hears them. */
+  watchDeploys(): void {
+    if (this.reloadOnDeploy && !this.gone) this.ensureChannel();
   }
 
   // -- connection -----------------------------------------------------------------------------------------------
 
   private ensureSocket(): Socket {
     if (this.socket) return this.socket;
-    const socketOpts: Record<string, unknown> = {
-      params: () => ({ app: this.app }),
-      timeout: this.opts.timeout ?? 15000,
+    const socket = new Socket(this.socketUrl, {
+      timeout: this.opts.timeout,
       ...this.opts.socketOptions,
-    };
-    if (this.opts.transport) socketOpts.transport = this.opts.transport;
-    const socket = new Socket(this.socketUrl, socketOpts as any);
+      transport: this.opts.transport,
+    });
     socket.onOpen(() => { this.status.value = "open"; });
     socket.onClose(() => { this.status.value = "closed"; });
-    socket.onError(() => { this.status.value = "closed"; });
     socket.connect();
     this.socket = socket;
     return socket;
@@ -60,41 +78,105 @@ export class ClientImpl {
   private ensureChannel(): Channel {
     if (this.channel) return this.channel;
     const socket = this.ensureSocket();
-    const channel = socket.channel(`app:${this.app}`, { patches: true, watermarks: true });
+    const channel = socket.channel(`app:${this.app}`, {});
     channel.on("data", (m: DataMessage) => this.onData(m));
     channel.on("error", (m: { id?: string; name?: string; message?: string }) => {
       const sub = m.id !== undefined ? this.subsById.get(String(m.id)) : undefined;
-      if (sub) sub.error.value = EraspaceError.from(m);
+      if (sub) {
+        sub.error.value = EraspaceError.from(m);
+        this.retrySub(sub);
+      }
     });
+    channel.on("gone", () => this.onGone());
+    // Transport loss changes status; reconnect rejoins and resubscribes while cached values stay valid.
+    // A join the server rejects is reported to every subscription.
+    const failed = (payload: unknown, rejected: boolean) => {
+      if (this.gone) return;
+      if (payload instanceof EraspaceError && payload.name === "AppGone") { this.onGone(); return; }
+      this.status.value = "closed";
+      if (rejected) for (const sub of this.subs.values()) sub.error.value = EraspaceError.from(payload, "App channel join failed");
+    };
+    channel.onError((reason, rejected) => failed(reason, rejected));
+    channel.onClose(() => failed(undefined, false));
     channel.on("deployed", (m: { version?: number }) => this.onDeployed(m?.version));
-    channel.join().receive("ok", (resp: { self?: string } | undefined) => {
+    channel.onJoin((resp) => {
+      this.joins++;
+      if (this.gone) return;
+      this.status.value = "open";
       if (resp && typeof resp.self === "string") this.self.value = resp.self;
+      if (resp && typeof resp.now === "number") this.clockOffset = resp.now - Date.now();
+      if (resp && typeof resp.version === "number") this.onJoinVersion(resp.version);
       // The channel process is new after a reconnect, so every live subscription is sent again.
       if (this.joinedOnce) this.resubscribeAll();
       this.joinedOnce = true;
     });
+    channel.join();
     this.channel = channel;
     return channel;
   }
 
-  private push<T>(event: string, payload: object): Promise<T> {
+  private push<T>(event: string, payload: object | (() => object | null)): Promise<T> {
+    if (this.gone) return Promise.reject(this.gone);
     const channel = this.ensureChannel();
-    return new Promise<T>((resolve, reject) => {
-      channel
-        .push(event, payload, this.opts.timeout ?? 15000)
-        .receive("ok", (resp: T) => resolve(resp))
-        .receive("error", (resp: unknown) => reject(EraspaceError.from(resp)))
-        .receive("timeout", () => reject(new EraspaceError("TimeoutError", `${event} timed out`)));
-    });
+    return channel.push<T>(event, payload, this.opts.timeout ?? 15000);
+  }
+
+  async call(fn: string, args: unknown[], kind: "query" | "action" = "query"): Promise<unknown> {
+    const key = this.requestKey();
+    try {
+      // Sorted object keys let equal query arguments share the server's cached result.
+      const resp = await this.push<{ value?: unknown }>("call", { fn, args: kind === "query" ? canonicalArgs(args) : args, kind, key });
+      return resp?.value;
+    } catch (error) {
+      if (kind === "action" && error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError"].includes(error.name)) {
+        throw new OutcomeUnknownError(key, "The action may have performed effects; it cannot be replayed safely");
+      }
+      throw error;
+    }
   }
 
-  async call(fn: string, args: unknown[]): Promise<any> {
-    const resp = await this.push<{ value?: unknown }>("call", { fn, args });
-    return resp?.value;
+  /** Request keys carry server time, so a skewed client clock cannot place them outside the retry window. */
+  private requestKey(): string {
+    return requestKey(Date.now() + this.clockOffset);
+  }
+
+  private async mutationRequest(fn: string, args: unknown[], key = this.requestKey(), retry = false): Promise<{ value: unknown; commitSeq?: number }> {
+    let rekeyed = false;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        return await this.push("call", { fn, args, kind: "mutation", key, retry });
+      } catch (error) {
+        // The server refused the key before running anything. The join reply has corrected the clock by now.
+        if (error instanceof EraspaceError && error.name === "RequestKeyError" && !retry && !rekeyed) {
+          rekeyed = true;
+          attempt--;
+          key = this.requestKey();
+          continue;
+        }
+        const uncertain = error instanceof EraspaceError && ["TimeoutError", "OutcomeUnknownError", "RetryExpiredError"].includes(error.name);
+        // A rejected recovery attempt cannot resolve the original request's unknown outcome.
+        if (!uncertain && !retry) throw error;
+        if (uncertain && attempt === 0 && error.name !== "RetryExpiredError") {
+          retry = true;
+          continue;
+        }
+        const message = error instanceof Error ? error.message : "Recovery failed";
+        throw new OutcomeUnknownError(key, `${message}. Recover this mutation only with the same request key.`);
+      }
+    }
+  }
+
+  async retryMutation(fn: string, args: unknown[], key: string): Promise<unknown> {
+    return (await this.mutationRequest(fn, args, key, true)).value;
   }
 
   close(): void {
-    for (const r of this.rooms.values()) r.channel.leave();
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.timer);
+      clearTimeout(sub.retryTimer);
+      sub.request++;
+    }
+    for (const r of this.rooms.values()) r.close();
     this.rooms.clear();
     this.channel?.leave();
     this.socket?.disconnect();
@@ -102,38 +184,92 @@ export class ClientImpl {
     this.socket = undefined;
     this.subs.clear();
     this.subsById.clear();
+    this.joinedOnce = false;
     this.status.value = "closed";
   }
 
+  private onGone(): void {
+    this.gone = new EraspaceError("AppGone", "This app is no longer serving");
+    for (const sub of this.subs.values()) {
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
+      sub.error.value = this.gone;
+    }
+    for (const r of this.rooms.values()) r.close();
+    this.channel?.leave();
+    this.socket?.disconnect();
+    this.status.value = "closed";
+  }
+
+  private retrySub(sub: Subscription): void {
+    if (this.gone || sub.retryTimer || this.subs.get(sub.key) !== sub) return;
+    sub.retryTimer = setTimeout(() => {
+      sub.retryTimer = undefined;
+      if (this.subs.get(sub.key) === sub) this.sendSub(sub);
+    }, retryDelay(++sub.retries));
+  }
+
   // -- subscriptions --------------------------------------------------------------------------------------------
 
   private sendSub(sub: Subscription): void {
+    if (this.gone) { sub.error.value = this.gone; return; }
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
     const oldId = sub.id;
     const request = ++sub.request;
+    // The server replies without the value when its cache entry still holds the revision we have.
+    const known = sub.hasServer && sub.entry !== undefined && sub.revision !== undefined ? { entry: sub.entry, revision: sub.revision } : undefined;
     if (request > 1) {
       this.subsById.delete(oldId);
       sub.id = String(this.nextSub++);
       this.subsById.set(sub.id, sub);
       sub.revision = undefined;
-      this.push("unsub", { id: oldId }).catch(() => {});
+      this.unsubscribe(sub, oldId);
     }
-    this.push<FullResult>("sub", { id: sub.id, fn: sub.fn, args: sub.args,
-      minCommitSeq: Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0)),
+    const id = sub.id;
+    this.push<FullResult | UnchangedResult>("sub", () => {
+      // A newer request or a drop replaced this one before it was sent: withdraw it.
+      if (sub.request !== request) return null;
+      sub.sent = { id, join: this.joins };
+      const minCommitSeq = Math.max(0, ...sub.layers.map(layer => layer.commitSeq ?? 0));
+      return known ? { id, fn: sub.fn, args: sub.args, minCommitSeq, known } : { id, fn: sub.fn, args: sub.args, minCommitSeq };
     }).then(
       (resp) => {
         if (this.subsById.get(sub.id) !== sub || sub.request !== request) return;
-        this.setServer(sub, resp.value, resp.commitSeq, resp.revision);
+        if ("unchanged" in resp && resp.unchanged === true) {
+          // Only a known revision is answered this way, and the value cannot have changed since it was sent.
+          if (known && sub.hasServer) this.setServer(sub, sub.server, resp.commitSeq, resp.revision);
+          else this.sendSub(sub);
+          return;
+        }
+        const full = resp as FullResult;
+        sub.entry = full.entry;
+        this.setServer(sub, full.value, full.commitSeq, full.revision);
       },
       (err: EraspaceError) => {
-        if (this.subsById.get(sub.id) === sub && sub.request === request) sub.error.value = err;
+        if (this.subsById.get(sub.id) === sub && sub.request === request) {
+          sub.error.value = err;
+          this.retrySub(sub);
+        }
       },
     );
   }
 
+  /** Tells the server to drop `id`, unless the server cannot have it: never sent, or sent before a reconnect. */
+  private unsubscribe(sub: Subscription, id: string): void {
+    if (sub.sent?.id !== id || sub.sent.join !== this.joins) return;
+    sub.sent = undefined;
+    this.push("unsub", { id }).catch(() => {});
+  }
+
   // Messages for one subscription id arrive in order, so only commit watermarks are compared. Revisions
   // belong to a server cache entry and may restart lower when an identity-dependent query splits.
   private setServer(sub: Subscription, value: unknown, commitSeq: number, revision: number): void {
     if (commitSeq < sub.commitSeq) return;
+    clearTimeout(sub.retryTimer);
+    sub.retryTimer = undefined;
+    sub.retries = 0;
     batch(() => {
       sub.server = value;
       sub.hasServer = true;
@@ -146,6 +282,7 @@ export class ClientImpl {
   }
 
   private onData(message: DataMessage): void {
+    if (this.gone) return;
     const sub = this.subsById.get(String(message.id));
     if (!sub || message.commitSeq < sub.commitSeq) return;
     if ("patch" in message) {
@@ -159,6 +296,8 @@ export class ClientImpl {
         this.sendSub(sub);
       }
     } else {
+      // Recovered subscriptions arrive as full pushes that name their new cache entry.
+      if (typeof message.entry === "string") sub.entry = message.entry;
       this.setServer(sub, message.value, message.commitSeq, message.revision);
     }
   }
@@ -167,11 +306,18 @@ export class ClientImpl {
     for (const sub of this.subs.values()) this.sendSub(sub);
   }
 
+  // Subscriptions survive a deploy: the server re-runs them with the new code and pushes changed values.
   private onDeployed(version: number | undefined): void {
     if (typeof version === "number") this.version.value = version;
-    this.resubscribeAll();
     for (const cb of [...this.deployedCbs]) cb(this.version.value);
-    if (this.opts.reloadOnDeploy && typeof location !== "undefined") location.reload();
+    if (this.reloadOnDeploy && typeof location !== "undefined") location.reload();
+  }
+
+  // A deploy announced while the socket was down, or before the first join, shows up as a newer join version.
+  // Without a known page version there is nothing to compare, so the first one seen becomes the baseline.
+  private onJoinVersion(version: number): void {
+    if (this.version.value === 0) this.version.value = version;
+    else if (version > this.version.value) this.onDeployed(version);
   }
 
   onDeployedCb(cb: (v: number) => void): () => void {
@@ -187,6 +333,14 @@ export class ClientImpl {
       sub = new Subscription(String(this.nextSub++), fn, args, key);
       this.subs.set(key, sub);
       this.subsById.set(sub.id, sub);
+      // A result embedded in the page shows at once; the server confirms it with `unchanged` when the first
+      // `sub` sends it as `known`, or replies with the current value.
+      const seed = this.initial.get(key);
+      if (seed) {
+        this.initial.delete(key);
+        sub.entry = seed.entry;
+        this.setServer(sub, seed.value, seed.commitSeq, seed.revision);
+      }
       this.sendSub(sub);
     }
     if (sub.refs === 0) this.scheduleDrop(sub, 1000);
@@ -221,9 +375,12 @@ export class ClientImpl {
     sub.timer = setTimeout(() => {
       sub.timer = undefined;
       if (sub.refs > 0 || this.subs.get(sub.key) !== sub) return;
+      clearTimeout(sub.retryTimer);
+      sub.retryTimer = undefined;
+      sub.request++;
       this.subs.delete(sub.key);
       this.subsById.delete(sub.id);
-      this.push("unsub", { id: sub.id }).catch(() => {});
+      this.unsubscribe(sub, sub.id);
     }, ms);
   }
 
@@ -245,7 +402,7 @@ export class ClientImpl {
   // -- mutations ------------------------------------------------------------------------------------------------
 
   async mutate(fn: string, args: unknown[], optimistic?: Fn): Promise<any> {
-    if (!optimistic) return this.call(fn, args);
+    if (!optimistic) return (await this.mutationRequest(fn, args)).value;
     const mid = this.nextMutation++;
     const touched = new Set<Subscription>();
     const store = {
@@ -256,7 +413,7 @@ export class ClientImpl {
     };
     try {
       batch(() => optimistic(store, ...args));
-      const { value, commitSeq } = await this.push<{ value: unknown; commitSeq?: number }>("call", { fn, args });
+      const { value, commitSeq } = await this.mutationRequest(fn, args);
       const timeout = this.opts.optimisticTimeoutMs ?? 2000;
       for (const sub of touched) {
         // Only mutations report a commit. Without one, no watermark can cover the layer.
@@ -269,9 +426,13 @@ export class ClientImpl {
           l.commitSeq = commitSeq;
         }
         if (sub.commitSeq >= commitSeq) this.dropLayers(sub, mid);
-        else setTimeout(() => {
-          if (sub.layers.some((l) => l.mid === mid) && this.subs.get(sub.key) === sub) this.sendSub(sub);
-        }, timeout);
+        else {
+          // The server sends unchanged values' newer watermarks only on request.
+          this.watch(sub, commitSeq);
+          setTimeout(() => {
+            if (sub.layers.some((l) => l.mid === mid) && this.subs.get(sub.key) === sub) this.sendSub(sub);
+          }, timeout);
+        }
       }
       return value;
     } catch (e) {
@@ -280,6 +441,13 @@ export class ClientImpl {
     }
   }
 
+  /** Asks for a watermark covering `commitSeq` on the subscription's current server id. */
+  private watch(sub: Subscription, commitSeq: number): void {
+    const id = sub.id;
+    if (sub.sent?.id !== id || sub.sent.join !== this.joins) return;
+    this.push("watch", { id, commitSeq }).catch(() => {});
+  }
+
   private addLayer(mid: number, name: string, args: unknown[], apply: Fn, touched: Set<Subscription>): void {
     const sub = this.subs.get(subKey(name, args));
     if (!sub) return;
@@ -296,6 +464,10 @@ export class ClientImpl {
 
   // -- rooms ----------------------------------------------------------------------------------------------------
 
+  /**
+   * Get or create the room for `room`. Like a subscription, it is only held once retained: a render that never
+   * commits leaves an unretained room, which is dropped after a grace period.
+   */
   acquireRoom(room: string): RoomConn {
     const topic = `room:${this.app}:${room}`;
     let r = this.rooms.get(topic);
@@ -303,20 +475,31 @@ export class ClientImpl {
       r = new RoomConn(this.ensureSocket(), topic, this.self);
       this.rooms.set(topic, r);
     }
-    if (r.timer) clearTimeout(r.timer);
+    if (r.refs === 0) this.scheduleRoomDrop(r, 1000);
+    return r;
+  }
+
+  /** False when the room was dropped after it was acquired; acquire it again. */
+  retainRoom(r: RoomConn): boolean {
+    if (this.rooms.get(r.topic) !== r) return false;
+    clearTimeout(r.timer);
     r.timer = undefined;
     r.refs++;
-    return r;
+    return true;
   }
 
   releaseRoom(r: RoomConn): void {
     r.refs = Math.max(0, r.refs - 1);
-    if (r.refs > 0) return;
-    if (r.timer) clearTimeout(r.timer);
+    if (r.refs === 0) this.scheduleRoomDrop(r, this.opts.unsubscribeDelayMs ?? 50);
+  }
+
+  private scheduleRoomDrop(r: RoomConn, ms: number): void {
+    clearTimeout(r.timer);
     r.timer = setTimeout(() => {
+      r.timer = undefined;
       if (r.refs > 0 || this.rooms.get(r.topic) !== r) return;
       this.rooms.delete(r.topic);
-      r.channel.leave();
-    }, this.opts.unsubscribeDelayMs ?? 50);
+      r.close();
+    }, ms);
   }
 }

package/sdk/src/client/errors.ts

@@ -1,6 +1,6 @@
 /**
  * An error raised by a server handler (or the transport). `name` is the server error name, for example `Error`,
- * `TypeError`, or `TimeoutError` for a call that got no reply in time.
+ * `TypeError`, or `OutcomeUnknownError` when a mutation or action could have applied.
  */
 export class EraspaceError extends Error {
   readonly data?: unknown;
@@ -26,3 +26,12 @@ export class EraspaceError extends Error {
 export function isEraspaceError(e: unknown): e is EraspaceError {
   return e instanceof EraspaceError;
 }
+
+/** The mutation may have committed. Recover with `client.retryMutation(name, args, error.requestKey)`. */
+export class OutcomeUnknownError extends EraspaceError {
+  readonly requestKey: string;
+  constructor(requestKey: string, message = "The request's outcome is unknown") {
+    super("OutcomeUnknownError", message);
+    this.requestKey = requestKey;
+  }
+}