lecodes-sdk 2.5.1 → 2.8.0

package/src/server/db/httpWatch.ts

@@ -0,0 +1,180 @@
+/**
+ * `WatchSource` (./watch.ts) over marcidb-server's watch socket — the source the runner gives every
+ * project worker beside its HTTP transport (./httpTransport.ts). One WebSocket per database,
+ * `GET <baseUrl>/$watch`, the bearer token as on every other route; JSON text frames:
+ *
+ *   → { "watch": 7, "op": { "model": "Room", "action": "findMany", "query": {…} } }
+ *   ← { "ok": 7 }   |   { "err": 7, "message": "…" }
+ *   → { "unwatch": 7 }
+ *   ← { "changed": [7, 9] }       one frame per commit, an id at most once in it
+ *
+ * The ids are ours. The socket opens with the first watch and closes a few seconds after the last
+ * `unwatch`. When it drops while watches are live it reconnects with back-off, sends every watch again
+ * and, once the engine has answered them all, says every one changed: what was committed meanwhile was
+ * not signalled. A socket that never opened (an engine without `$watch`, a refused token) fails the
+ * watches waiting for it with the reason.
+ *
+ * Host-side code (Bun): the WebSocket is the platform's — Bun's takes `headers`. Pass `WebSocket`
+ * explicitly when the global one might be patched by code in the same realm (the runner captures it
+ * before it evaluates a bundle, as it does `fetch`).
+ */
+
+import type { WatchOp, WatchSource } from "./watch"
+
+type Socket = {
+  readyState: number
+  send(data: string): void
+  close(): void
+  onopen: ((ev: unknown) => void) | null
+  onmessage: ((ev: { data: unknown }) => void) | null
+  onclose: ((ev: unknown) => void) | null
+  onerror: ((ev: unknown) => void) | null
+}
+export type WatchSocketCtor = new (url: string, options?: { headers?: Record<string, string> }) => Socket
+
+export type MarciWatchOptions = {
+  token?: string | null
+  WebSocket?: WatchSocketCtor
+  /** How long the socket outlives its last watch (ms). */
+  lingerMs?: number
+  /** How long a watch waits for the engine's answer before it fails (ms). */
+  answerMs?: number
+}
+
+const BACKOFF_MS = [250, 1000, 2000, 5000, 10000]
+
+export const marciHttpWatchSource = (baseUrl: string, options: MarciWatchOptions = {}): WatchSource => {
+  const url = baseUrl.replace(/\/+$/, "").replace(/^http/, "ws") + "/$watch"
+  const Ctor = options.WebSocket ?? (globalThis.WebSocket as unknown as WatchSocketCtor)
+  const lingerMs = options.lingerMs ?? 3000
+  const answerMs = options.answerMs ?? 10_000
+
+  /** every live watch, answered or not: what a reconnect sends again */
+  const ops = new Map<number, WatchOp>()
+  /** the watches the engine has answered `ok` */
+  const held = new Set<number>()
+  /** the watches waiting for their first answer */
+  const waiting = new Map<number, { resolve: (id: number) => void, reject: (e: Error) => void, timer: ReturnType<typeof setTimeout> }>()
+  /** after a reconnect: the held watches sent again and not answered yet — "changed" goes out when it empties */
+  let resync: Set<number> | null = null
+  let resynced: number[] = []
+  let listener: ((ids: number[]) => void) | null = null
+  let ws: Socket | null = null
+  let open = false
+  let attempts = 0
+  let retry: ReturnType<typeof setTimeout> | null = null
+  let linger: ReturnType<typeof setTimeout> | null = null
+  let closed = false
+  let next = 1
+
+  const send = (frame: unknown) => { if (open) ws!.send(JSON.stringify(frame)) }
+  const fail = (id: number, message: string) => {
+    const w = waiting.get(id)
+    ops.delete(id)
+    if (!w) return
+    waiting.delete(id)
+    clearTimeout(w.timer)
+    w.reject(new Error(message))
+  }
+  const answered = (id: number) => {
+    if (!resync?.delete(id) || resync.size) return
+    resync = null
+    const ids = resynced.filter(i => held.has(i))
+    resynced = []
+    if (ids.length) listener?.(ids)
+  }
+
+  const connect = () => {
+    if (ws || retry !== null || closed) return
+    const socket = new Ctor(url, { headers: options.token ? { authorization: `Bearer ${options.token}` } : {} })
+    ws = socket
+    let opened = false
+    socket.onopen = () => {
+      if (ws !== socket) return
+      const again = attempts > 0
+      opened = true
+      open = true
+      attempts = 0
+      if (again && held.size) { resync = new Set(held); resynced = [...held] }
+      for (const [id, op] of ops) socket.send(JSON.stringify({ watch: id, op }))
+    }
+    socket.onmessage = (ev) => {
+      let msg: { ok?: number, err?: number, message?: string, changed?: number[] }
+      try { msg = JSON.parse(String(ev.data)) } catch { return }
+      if (typeof msg.ok === "number") {
+        const id = msg.ok
+        const w = waiting.get(id)
+        if (w) { waiting.delete(id); clearTimeout(w.timer); if (ops.has(id)) { held.add(id); w.resolve(id) } }
+        answered(id)
+      } else if (typeof msg.err === "number") {
+        const id = msg.err
+        // a watch the engine takes no more (a migration made its query invalid): its subscriber reads
+        // again and hears the read's own error
+        if (held.delete(id)) { ops.delete(id); answered(id); listener?.([id]); return }
+        fail(id, `marcidb refused the watch: ${msg.message ?? "unknown error"}`)
+      } else if (Array.isArray(msg.changed)) {
+        const ids = msg.changed.filter(id => held.has(id))
+        if (ids.length) listener?.(ids)
+      }
+    }
+    const down = () => {
+      if (ws !== socket) return
+      ws = null
+      open = false
+      resync = null
+      // never opened: nothing will answer the watches waiting for it
+      if (!opened) for (const id of [...waiting.keys()]) fail(id, `marcidb: no watch socket at ${url} (an engine without $watch, or the token refused)`)
+      if (closed || ops.size === 0) { attempts = 0; return }
+      const delay = BACKOFF_MS[Math.min(attempts++, BACKOFF_MS.length - 1)]
+      retry = setTimeout(() => { retry = null; connect() }, delay)
+    }
+    socket.onclose = down
+    socket.onerror = down
+  }
+
+  const idle = () => {
+    if (ops.size || linger !== null) return
+    linger = setTimeout(() => {
+      linger = null
+      if (ops.size || !ws) return
+      const socket = ws
+      ws = null
+      open = false
+      socket.close()
+    }, lingerMs)
+  }
+
+  return {
+    watch(op) {
+      if (closed) return Promise.reject(new Error("db watch: the source is closed"))
+      const id = next++
+      if (linger !== null) { clearTimeout(linger); linger = null }
+      return new Promise<number>((resolve, reject) => {
+        const timer = setTimeout(() => fail(id, `marcidb did not answer the watch within ${answerMs} ms`), answerMs)
+        waiting.set(id, { resolve, reject, timer })
+        ops.set(id, op)
+        if (open) send({ watch: id, op })
+        else connect()
+      })
+    },
+    unwatch(id) {
+      if (!ops.delete(id)) return
+      held.delete(id)
+      send({ unwatch: id })
+      idle()
+    },
+    onChanged(cb) { listener = cb },
+    close() {
+      closed = true
+      if (retry !== null) { clearTimeout(retry); retry = null }
+      if (linger !== null) { clearTimeout(linger); linger = null }
+      for (const id of [...waiting.keys()]) fail(id, "db watch: the source is closed")
+      ops.clear()
+      held.clear()
+      const socket = ws
+      ws = null
+      open = false
+      socket?.close()
+    },
+  }
+}

package/src/server/db/marci/query.ts

@@ -3,7 +3,7 @@
 
 // The generic query layer of the marcidb client: the query-language types every generated client is built
 // on (where / update operators, `GetResult`, `Op`, the query builder `Query<T>`) and the builder runtime
-// (`createQueryLayer`). Everything here is schema-agnostic — the codegen (crates/marcidb-ts) emits the
+// (`createQueryLayer`, `op.watch` included). Everything here is schema-agnostic — the codegen (crates/marcidb-ts) emits the
 // per-model type bags and MODELS metadata this file is parametrised by.
 //
 // Keep it dependency-free: besides shipping in `marcidb-client/runtime`, this file is vendored verbatim
@@ -181,6 +181,37 @@ export type Settles<T> = PromiseLike<T> & {
 }
 export type Op<T> = Settles<T> & { readonly [__op]: T }
 
+/** A running watch — see `ReadOp.watch`. */
+export interface Watch {
+  /** Stops it: no callback after this returns. Idempotent. */
+  close(): void
+}
+export type WatchOptions = {
+  /** Gets what a read of the watch failed with (an op the database refuses — after a migration, say),
+   *  and what the callback threw. Without it, they are logged. */
+  error?: (error: unknown) => void
+}
+/** A read (`select`, `first`, `count`, `aggregate`): an op that can also be watched. */
+export type ReadOp<T> = Op<T> & {
+  /**
+   * Calls `callback` with the result at once, then again each time a commit changed it. The database signals
+   * every commit that may have changed it; the client reads again and calls back only when the result
+   * differs (as JSON) from the one it delivered last. Signals that arrive during a read make one more read.
+   * A dropped connection is reopened and read again by the client — nothing to handle outside.
+   */
+  watch(callback: (result: T) => void, options?: WatchOptions): Watch
+}
+/** What a transport tells a watch it holds (internal: `op.watch` is built on it). */
+export type WatchListener = {
+  /** A commit may have changed the result — or the transport recovered a lost connection. */
+  changed(): void
+  /** The database refused the op when the transport registered it again. */
+  failed(error: unknown): void
+}
+/** A watch registered with a transport: `ready` settles once the database has it (it rejects with the
+ *  refusal), `close` drops it. */
+export type WatchRegistration = { ready: Promise<void>, close(): void }
+
 // A transport-neutral operation descriptor and the pluggable transport that runs it. The HTTP transport
 // is selected by passing a URL string; marcidb-embedded provides an in-process FFI transport.
 export type MarciOp = { model: string, action: string, query?: any, data?: any, id?: any, key?: any, onInsert?: any, journal?: JournalArgs }
@@ -189,6 +220,14 @@ export type JournalArgs = { name: string, on?: readonly JournalOp[], after?: num
 export type MarciTransport = {
   exec(op: MarciOp): Promise<any>
   batch(ops: MarciOp[]): Promise<any[]>
+  /** The binary read fast path, if the transport has one. `schemaHash` is the fingerprint of the schema the
+   *  calling client was generated from; the transport answers with the binary result buffer only for a
+   *  database on the same schema. `{ json }` is an already-parsed JSON answer (HTTP, when the server declined
+   *  binary); `null` means "no binary answer" and the client falls back to `exec`. */
+  queryBinary?(op: MarciOp, schemaHash: string): Promise<Uint8Array | { json: any } | null>
+  /** Watches, if the transport has them: registers the read `op` and tells `listener` whenever a commit may
+   *  have changed its result. Only signals — the re-read and the comparison are the query layer's. */
+  watch?(op: MarciOp, listener: WatchListener): WatchRegistration
 }
 
 // ───────────────────────────── query builder ─────────────────────────────
@@ -237,6 +276,8 @@ export type IdArg<I> = I | BareId<I>
  */
 export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles<Rows<T, Sel>[]> {
   readonly [__op]: Rows<T, Sel>[]
+  /** The rows now, then each time a commit changed them — see `ReadOp.watch`. */
+  watch(callback: (rows: Rows<T, Sel>[]) => void, options?: WatchOptions): Watch
   readonly [__sub]: T["name"]
   readonly [__sel]: Effective<T, Sel>
   /** Filter (marcidb `$where`). Repeated calls are ANDed. */
@@ -257,13 +298,13 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles
    */
   select<S extends T["query"] = T["scalars"]>(shape?: S): Query<T, S>
   /** The first matching row or `null`. */
-  first(): Op<Rows<T, Sel> | null>
+  first(): ReadOp<Rows<T, Sel> | null>
   /** Row count; inside a select it becomes `{ count }` for the relation. */
-  count(): Op<number> & Sub<T["name"], { $count: true }>
+  count(): ReadOp<number> & Sub<T["name"], { $count: true }>
   /** @deprecated pass the filter through the chain: `db.user.where(w).count()` (removed in the next minor). */
-  count(query: { $where?: T["where"] }): Op<number> & Sub<T["name"], { $count: true }>
+  count(query: { $where?: T["where"] }): ReadOp<number> & Sub<T["name"], { $count: true }>
   // `NoInfer`: as a select value the contextual type is `Sub<Name, any>`, which would otherwise win the inference of `A`
-  aggregate<A extends T["aggregate"]>(query: A): Op<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>
+  aggregate<A extends T["aggregate"]>(query: A): ReadOp<AggregateResult<T["model"], A>> & Sub<T["name"], NoInfer<A>>
 
   insert(data: T["insert"]): Op<T["id"]>
   /** The new row by `select`'s shape — its defaults, dates and files as stored: one call, nothing to read back. */
@@ -289,9 +330,9 @@ export interface Query<T extends ModelTypes, Sel = T["scalars"]> extends Settles
 
   // ── object form (deprecated): one query object (select shape + $where/$order/$limit/$skip/$cursor)
   /** @deprecated use `.select(query)` — it takes the same object, merged with the chain (removed in the next minor). */
-  findMany<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q>[]>
+  findMany<Q extends T["query"] = {}>(query?: Q): ReadOp<Rows<T, Q>[]>
   /** @deprecated use `.select(query).first()` (removed in the next minor). */
-  findFirst<Q extends T["query"] = {}>(query?: Q): Op<Rows<T, Q> | null>
+  findFirst<Q extends T["query"] = {}>(query?: Q): ReadOp<Rows<T, Q> | null>
 }
 
 // ───────────────────────────── journals ─────────────────────────────
@@ -340,8 +381,12 @@ export type QueryLayerOptions = {
   /** Hook for the `onInsert` part of an `upsert` — the fields used only when the row is created (the lecodes SDK
    *  puts a uuid id here). Receives what the caller gave (or undefined), returns what is sent. */
   prepareUpsert?(model: string, onInsert: any): any;
+  /** The transport's watches (`MarciTransport.watch`); without it `op.watch` throws. */
+  watch?(op: MarciOp, listener: WatchListener): WatchRegistration;
 };
 
+const READ_ACTIONS = ["findMany", "findFirst", "count", "aggregate"];
+
 const AGGREGATE_KEYS = ["$count", "$sum", "$avg", "$min", "$max"];
 const and = (a: any, b: any): any => (a ? (b ? { $and: [a, b] } : a) : b);
 
@@ -355,6 +400,64 @@ type QueryState = { shape?: Record<string, any>; where?: any; order?: any; limit
 export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor: MarciOp) => any; collection: (model: string) => any } {
   const { models, run } = options;
 
+  // `op.watch(callback, { error })` — one code for every transport: the transport only says "may have
+  // changed"; reading again, comparing with what was delivered and coalescing happen here.
+  const watch = (descriptor: MarciOp, callback: (result: any) => void, o?: WatchOptions): Watch => {
+    if (!READ_ACTIONS.includes(descriptor.action)) {
+      throw new Error(`marcidb: ${descriptor.model}.${descriptor.action} is a write — only reads can be watched`);
+    }
+    if (!options.watch) throw new Error("marcidb: this transport cannot watch");
+    let closed = false;
+    let reading = false;
+    let again = false;
+    let last: string | undefined; // the last result delivered, as JSON
+    const fail = (e: unknown) => {
+      if (closed) return;
+      if (o?.error) o.error(e);
+      else console.error(`marcidb: a watch of ${descriptor.model}.${descriptor.action} failed:`, e);
+    };
+    const read = async (): Promise<void> => {
+      if (closed) return;
+      if (reading) {
+        again = true; // one more read after this one, however many signals came meanwhile
+        return;
+      }
+      reading = true;
+      try {
+        do {
+          again = false;
+          let result: any;
+          try {
+            result = await run(descriptor);
+          } catch (e) {
+            fail(e);
+            continue;
+          }
+          const json = JSON.stringify(result);
+          if (closed || json === last) continue;
+          last = json;
+          try {
+            callback(result);
+          } catch (e) {
+            fail(e);
+          }
+        } while (again && !closed);
+      } finally {
+        reading = false;
+      }
+    };
+    // Registered first, read second: a commit between the two is signalled, not lost.
+    const registration = options.watch(descriptor, { changed: () => void read(), failed: fail });
+    registration.ready.then(read, fail);
+    return {
+      close() {
+        if (closed) return;
+        closed = true;
+        registration.close();
+      },
+    };
+  };
+
   // Lazily-executed operation: `await` runs it through the transport as a single op,
   // while `$transaction` takes only the `__op` descriptor and sends them as one batch.
   const op = (descriptor: MarciOp): any => ({
@@ -362,6 +465,7 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
     then: (onFulfilled?: any, onRejected?: any) => run(descriptor).then(onFulfilled, onRejected),
     catch: (onRejected?: any) => run(descriptor).catch(onRejected),
     finally: (onFinally?: any) => run(descriptor).finally(onFinally),
+    watch: (callback: (result: any) => void, o?: WatchOptions) => watch(descriptor, callback, o),
   });
 
   // A field key is anything that isn't a `$`-clause. A shape without field keys selects id + every scalar
@@ -460,6 +564,7 @@ export function createQueryLayer(options: QueryLayerOptions): { op: (descriptor:
         then: (onFulfilled?: any, onRejected?: any) => run(findMany()).then(onFulfilled, onRejected),
         catch: (onRejected?: any) => run(findMany()).catch(onRejected),
         finally: (onFinally?: any) => run(findMany()).finally(onFinally),
+        watch: (callback: (rows: any) => void, o?: WatchOptions) => watch(findMany(), callback, o),
 
         where: (where: any) => make({ ...st, where: and(st.where, where) }),
         order: (field: any, direction?: "asc" | "desc") => {

package/src/server/db/watch.ts

@@ -0,0 +1,160 @@
+/**
+ * The database's half of `computed` (../computed.ts): a WATCH is a read the engine keeps an eye on.
+ * After a commit that may have changed its result the engine says so — and nothing more: it carries no
+ * rows, whoever watches reads again (marci-db's `watch`, docs/plans/multiplayer-plan.md D1). A false
+ * "changed" costs one read, a missed one a stale screen, so the engine over-approximates.
+ *
+ *   const source = marciHttpWatchSource(dbUrl, { token })        // ./httpWatch.ts
+ *   source.onChanged((ids) => …)                                 // these results may differ now
+ *   const id = await source.watch({ model: "Room", action: "findMany", query })   // the engine holds it
+ *   source.unwatch(id)
+ *
+ * `watch` resolves once the engine holds the watch: a commit after that is signalled. So the host
+ * watches a read BEFORE it sends it (../computedHost.ts) — a write that lands between the two is either
+ * in the read's answer or signalled, never lost. Watches are ephemeral: a source whose connection drops
+ * registers them all again and then says every one changed.
+ *
+ * Host-side only (it is never bundled). Three sources stand behind the interface: the HTTP one
+ * (./httpWatch.ts, the runner's: marcidb-server's `GET /<db>/$watch` socket), the embedded one
+ * (marcidb-embedded's handle, `lecodes dev` / `lecodes test`, below), and a fake for tests that fires
+ * when it is told to.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { MarciOp, WatchListener, WatchRegistration } from "./marci/query"
+
+/** A read as the engine watches it: the op the db client sends, minus what a read does not have. */
+export type WatchOp = { model: string, action: string, query: unknown }
+
+/** The ops a watch takes — and the only ones a computed may send. */
+export const READ_ACTIONS: ReadonlySet<string> = new Set(["findMany", "findFirst", "count", "aggregate"])
+export const isReadOp = (op: Pick<MarciOp, "action">): boolean => READ_ACTIONS.has(op.action)
+
+export interface WatchSource {
+  /** Watch the result of `op`; resolves with the watch's id once the engine holds it. Rejects when the
+   *  engine refuses the query (it would refuse the read too) or cannot be reached. */
+  watch(op: WatchOp): Promise<number>
+  /** Stop watching (an id it does not hold is ignored). */
+  unwatch(id: number): void
+  /** Where "these watches' results may have changed" goes: one listener, set once. */
+  onChanged(listener: (ids: number[]) => void): void
+  /** Drop every watch and the connection (the worker is going away). */
+  close(): void
+}
+
+// ───────────────────────────── a fake, for tests ─────────────────────────────
+
+export type FakeWatchSource = WatchSource & {
+  /** The live watches: id → op. */
+  readonly watches: ReadonlyMap<number, WatchOp>
+  /** Every `watch` and `unwatch`, in order: `+1 Room.findMany`, `-1`. */
+  readonly log: string[]
+  /** Say these watches changed — every live one when none is named. Synchronous. */
+  fire(...ids: number[]): void
+  /** Say every watch of `model` changed: what a commit that wrote the model does, coarsely. */
+  fireModel(model: string): void
+  /** Refuse a query the way the engine would (`watch` rejects with the message); null = take it. */
+  refuse: ((op: WatchOp) => string | null) | null
+}
+
+export const createFakeWatchSource = (): FakeWatchSource => {
+  const watches = new Map<number, WatchOp>()
+  let listener: ((ids: number[]) => void) | null = null
+  let next = 1
+  const fake: FakeWatchSource = {
+    watches,
+    log: [],
+    refuse: null,
+    watch: async (op) => {
+      const refused = fake.refuse?.(op)
+      if (refused) throw new Error(refused)
+      const id = next++
+      watches.set(id, op)
+      fake.log.push(`+${id} ${op.model}.${op.action}`)
+      return id
+    },
+    unwatch: (id) => {
+      if (!watches.delete(id)) return
+      fake.log.push(`-${id}`)
+    },
+    onChanged: (cb) => { listener = cb },
+    close: () => { watches.clear() },
+    fire: (...ids) => {
+      const hit = (ids.length ? ids : [...watches.keys()]).filter(id => watches.has(id))
+      if (hit.length) listener?.(hit)
+    },
+    fireModel: (model) => {
+      const hit = [...watches].filter(([, op]) => op.model === model).map(([id]) => id)
+      if (hit.length) listener?.(hit)
+    },
+  }
+  return fake
+}
+
+// ───────────────────────────── marcidb-embedded ─────────────────────────────
+
+/** What the embedded source needs of a marcidb-embedded handle (`openDatabase(dir)`): its `watch`, which the
+ *  package has from the engine's ABI 4 (marcidb-embedded 0.18). */
+export type EmbeddedWatchHandle = { watch?(op: MarciOp, listener: WatchListener): WatchRegistration }
+
+/**
+ * Run `fn` in a clean async context — the one this module was loaded in — instead of the caller's. For the
+ * timers and sockets a watch makes: marcidb-embedded's poll timer is made by the handle's first watch and
+ * every watch's callback runs in the context it was made in (the app's own `op.watch` too), which must not be
+ * a computed's run or a request. Where the platform has no snapshot (an old Node), the caller's.
+ */
+export const outsideRequests: <R>(fn: () => R) => R =
+  (AsyncLocalStorage as unknown as { snapshot?: () => <R>(fn: () => R) => R }).snapshot?.() ?? ((fn) => fn())
+
+/**
+ * marcidb-embedded's watches (`lecodes dev`, `lecodes test`): the handle's `watch(op, listener)`. The engine
+ * keeps the ids a commit touched; the package polls them every 50 ms while a watch is open and calls each
+ * one's listener — the ids of one poll reach `onChanged` together. `ready` is settled at once (the engine
+ * takes or refuses the query on the spot). `db` is read at each watch: the host opens the database after it
+ * made the source. A package from before the engine had watches (no `watch` on the handle) refuses every
+ * watch with the reason, so a computed that reads the database is refused when subscribed to (its call works).
+ */
+export const embeddedWatchSource = (db: () => EmbeddedWatchHandle | null): WatchSource => {
+  const held = new Map<number, WatchRegistration>()
+  let listener: ((ids: number[]) => void) | null = null
+  let batch: number[] | null = null
+  let next = 1
+  const changed = (id: number) => {
+    if (!held.has(id)) return
+    if (!batch) {
+      batch = []
+      queueMicrotask(() => { const ids = batch!; batch = null; if (ids.length) listener?.(ids.filter((i) => held.has(i))) })
+    }
+    if (!batch.includes(id)) batch.push(id)
+  }
+  return {
+    async watch(op) {
+      const handle = db()
+      if (!handle) throw new Error("db watch: the database is not open")
+      if (typeof handle.watch !== "function") throw new Error("db watch: this marcidb-embedded has no watch (it came with marcidb-embedded 0.18) — update it, so a computed that reads the database can be subscribed to under `lecodes dev` / `lecodes test`; call it once meanwhile")
+      const id = next++
+      // a watch the engine took no more is read again: the read says why (as the HTTP source does)
+      const reg = outsideRequests(() => handle.watch!({ model: op.model, action: op.action, query: op.query }, { changed: () => changed(id), failed: () => changed(id) }))
+      held.set(id, reg)
+      try {
+        await reg.ready
+      } catch (e) {
+        held.delete(id)
+        reg.close()
+        throw e
+      }
+      return id
+    },
+    unwatch(id) {
+      const reg = held.get(id)
+      if (!reg) return
+      held.delete(id)
+      reg.close()
+    },
+    onChanged(cb) { listener = cb },
+    close() {
+      for (const reg of held.values()) reg.close()
+      held.clear()
+    },
+  }
+}

package/src/server/files/host.ts

@@ -400,7 +400,8 @@ export const createFilesHost = (cfg: FilesHostConfig): FilesHost => {
   }
   const seam: FilesSeam = {
     uploaded: (value) => typeof value === "object" && value !== null ? uploaded.get(value) : undefined,
-    url: (id, name) => `${currentRequest()?.filesBase ?? ""}/files/${id}/${encodeURIComponent(name)}`,
+    // the host's read, not the code's: a computed that returns a file is still every subscriber's (the base is in its key)
+    url: (id, name) => `${currentRequest(true)?.filesBase ?? ""}/files/${id}/${encodeURIComponent(name)}`,
     image,
     dirty: false,
   }

package/src/server/host.ts

@@ -6,20 +6,32 @@
  */
 
 export {
-  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, setChannelPublisher, setRequestProvider, runSeed, SeedError,
+  loadServerModules, createInvoker, createFileWriter, createSubscribeGuard, createComputedHost, setChannelPublisher, setPresenceProvider, setRequestProvider, runSeed, SeedError,
 } from "./runtime"
-export type { LoadedServer, InvokeResult, InvokerOptions, ServerRegistration, SeedOutcome } from "./runtime"
+export type { LoadedServer, InvokeResult, InvokerOptions, ComputedHostOptions, ServerRegistration, SeedOutcome } from "./runtime"
+export { ComputedWriteError } from "./computedHost"
+export type { ComputedHost } from "./computedHost"
+export { createFakeWatchSource, embeddedWatchSource, isReadOp, outsideRequests, READ_ACTIONS } from "./db/watch"
+export type { EmbeddedWatchHandle, FakeWatchSource, WatchOp, WatchSource } from "./db/watch"
+export { marciHttpWatchSource } from "./db/httpWatch"
+export type { MarciWatchOptions, WatchSocketCtor } from "./db/httpWatch"
 export type { RequestContext } from "./context"
 export { setEnv, EnvError, ENV_NAME, PUBLIC_ENV_PREFIX, isPublicEnvName } from "./env"
 export { TRUSTED_CA_FILE, trustedCaEnv } from "./trustedCa"
+export { setServerClock, serverClockOffset } from "./clock"
+export { firstCallGate } from "../runtime/firstCall"
+export type { FirstCallGate } from "../runtime/firstCall"
 export type { Env } from "./env"
-export { createChannelHub } from "./channelHub"
+export { createChannelHub, PRESENCE_GRACE_MS } from "./channelHub"
+export { callerKey, createRateLimiter, RATE_LIMITS, TOO_MANY_CALLS } from "./rateLimit"
+export type { RateLimit, RateLimiter } from "./rateLimit"
+export type { PresenceAsk } from "./channel"
 export type { ChannelHub, ChannelHubOptions, HubConnection, HubFanout } from "./channelHub"
 export type { ChannelGroup, ClientFrame, ServerFrame } from "../runtime/wire"
 export { setDbTransport } from "./db/defineDb"
 export { marciHttpTransport, marciRequest, encodeMarciId, MarciHttpError } from "./db/httpTransport"
 export type { MarciHttpOptions } from "./db/httpTransport"
-export type { MarciOp, MarciTransport } from "./db/marci/query"
+export type { MarciOp, MarciTransport, WatchListener, WatchRegistration } from "./db/marci/query"
 export type { ServerManifest, ServerExport } from "../compile/serverSplit"
 export { validateArgs, ValidationError } from "./validate"
 export type { ParamSchema, Schema as ParamSchemaNode } from "./validate"
@@ -57,6 +69,8 @@ export type ServerDescription = {
    *  A `t.file()` field itself is described as `kind: "file"`. */
   models: Record<string, { fields: Record<string, FieldDescription>, auth?: true, files?: true }>
   endpoints: { id: string, params: unknown[] | null }[]
+  /** The computeds (`computed()` exports), by id. Each is in `endpoints` too: its one-shot call. */
+  computeds: string[]
   channels: string[]
   /** The push channels (`pushChannel()` exports), by id. */
   pushChannels: string[]
@@ -109,6 +123,7 @@ export const describeServer = (server: LoadedServer): ServerDescription => {
     marci: db?.$schema ?? "",
     models,
     endpoints: [...server.endpoints.keys()].map(id => ({ id, params: params[id] ?? null })),
+    computeds: [...server.computeds.keys()],
     channels: [...server.channels.keys()],
     pushChannels: [...server.pushChannels.keys()],
     auth: { model: db?.$auth?.model ?? null },

package/src/server/inject.ts

@@ -3,16 +3,20 @@
  * chisel injects these into the server bundle exactly like ./inject.ts does for the client bundle;
  * nothing here may reach the client bundle. Keep this the ONLY file that exports server globals.
  *
- * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, pushChannel, request, env. Sign-in is
- * not a global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`.
+ * Globals: t, model, defineDb, ref (schema + queries), ApiError, channel, computed, pushChannel, request, ordered, env.
+ * Sign-in is not a global: it is `db.auth` of a db made with `defineDb({...}).withAuth({ model })`. `computed` and
+ * `ref` are names of the app's globals too — another value each side, one declaration of both in the project's
+ * types (build-types.ts).
  */
 
 export { t, model, defineDb, ref } from "./db"
 export { ApiError } from "./errors"
 export { env, type Env } from "./env"
 export { channel } from "./channel"
+export { computed } from "./computed"
 export { pushChannel, type PushChannel, type PushMessage, type PushNotification, type PushTarget } from "./pushChannel"
 export { request } from "./context"
+export { ordered } from "./ordered"
 export type { StoredFile, StoredImage } from "./files/models"
 /** The value an SVG source is to the client (`assetIcon(…)` compiles to `SvgSource(…)`): a shared module of
  *  the design that names an icon per row loads on the server too. The server draws nothing with it. */

package/src/server/ordered.ts

@@ -0,0 +1,41 @@
+/**
+ * `ordered(key, fn)` — calls with one key run one after another (server global). A worker runs its
+ * calls concurrently and every `await` lets another one in, so a read-check-write under a key (a
+ * room's code) needs the key's other calls to wait: a chain of promises per key, in this worker. A
+ * key is dropped when its chain drains; different keys run in parallel; nothing else is kept (the
+ * state stays in the database). Honest because one worker serves a project at a time — the runner
+ * lets the new worker of a deploy take calls only once the old one's are done (tools/runner/src/project.ts).
+ *
+ * Two rules: keep the body short (the key's other callers wait; a call has 30 s), and no `ordered` of a
+ * key from inside its own body (it would wait for itself) — that rejects. The keys a body holds follow
+ * its async chain in an AsyncLocalStorage: a body's sibling (another call of the same request) is not
+ * taken for re-entry, nor is a timer that fires after the body ended. The class comes over a global seam
+ * the host runtime installs (./runtime.ts): the bundle carries its own copy of this module and imports
+ * nothing. Without the seam the queue still works; only re-entry is not caught.
+ */
+
+export type OrderedKey = string | number
+type Hold = { key: OrderedKey, done: boolean }
+type Scope = { getStore(): readonly Hold[] | undefined, run<R>(held: readonly Hold[], fn: () => R): R }
+
+const seam = globalThis as unknown as { __lecodesAsyncLocalStorage?: new () => Scope }
+const chains = new Map<OrderedKey, Promise<void>>()
+let scope: Scope | undefined
+
+/** Run `fn` once every earlier call of `key` has finished; its result (or failure) is the call's. */
+export const ordered = <T>(key: OrderedKey, fn: () => T | Promise<T>): Promise<T> => {
+  scope ??= seam.__lecodesAsyncLocalStorage && new seam.__lecodesAsyncLocalStorage()
+  const held = scope?.getStore() ?? []
+  if (held.some(h => h.key === key && !h.done)) {
+    return Promise.reject(new Error(`ordered(${JSON.stringify(key)}) inside its own body would wait for itself — call that code directly`))
+  }
+  const hold: Hold = { key, done: false }
+  const run = (chains.get(key) ?? Promise.resolve()).then(() => scope ? scope.run([...held, hold], fn) : fn())
+  const tail = run.then(() => { hold.done = true }, () => { hold.done = true })
+  chains.set(key, tail)
+  void tail.then(() => { if (chains.get(key) === tail) chains.delete(key) })
+  return run
+}
+
+/** @internal the keys with a chain right now (a test's look at the queue). */
+export const _orderedKeys = (): OrderedKey[] => [...chains.keys()]