lecodes-sdk 2.5.1 → 2.8.0

package/src/server/computedHost.ts

@@ -0,0 +1,413 @@
+/**
+ * The host side of `computed` (./computed.ts): what a worker does for the computed subscriptions the
+ * hub (./channelHub.ts) hands it. Built by `createComputedHost` (./runtime.ts), which gives it the run
+ * of one computed in a subscriber's request scope; everything else is here:
+ *
+ *   const computed = createComputedHost(server, { watch, auth, onError })
+ *   await computed.start(id, args, ctx, sub)    // the first run: the envelope's `result` is the value
+ *   computed.end(sub)                           // the hub says it is over (null = every one)
+ *   computed.presenceChanged(id, key)           // the hub says who is subscribed to (id, key) changed
+ *
+ * The gate. The bundle's db client hands every operation to `globalThis.__lecodesDbGate` before it
+ * sends it (./db/defineDb.ts). Inside a computed's run (an AsyncLocalStorage scope around the function
+ * alone — what the host does before and after is not the computed's) a write is refused
+ * (`ComputedWriteError`, a 500 with its message) and each read is recorded: watched (./db/watch.ts)
+ * before it goes out, so a commit between the two is either in its answer or signalled. A one-shot call
+ * of a computed (an endpoint call) runs under the same gate with nothing recorded.
+ *
+ * Shared runs. A run whose code did not read the request — `request.*`, `db.auth`: whatever asks the
+ * request provider, which tells this file (`requestRead`, the one flag of the run's scope) — depends on
+ * the arguments and the data alone, so its value is every subscriber's with those arguments: the
+ * subscriptions of one key (export, arguments, and the `filesBase` a stored file's url is made of) hear
+ * ONE run — one watch set, one presence-dependency set, one last value — each through its own publish
+ * (the hub's per-subscription dedupe holds). A run that read the request is its subscriber's alone, as
+ * every run was before. Decided at the end of each run, so a key moves between the two as its data
+ * does: a shared run that read the request is dropped and each of its subscriptions runs its own (from
+ * its watches: nothing is lost or watched twice); an own run that read nothing joins its key's run — or
+ * becomes it. The first run of a subscription is always its own: it is the subscription's answer (its
+ * arguments checked, its session resolved or minted, a refusal its own); the sharing starts after it.
+ *
+ * The watches. One per distinct read (model, action, query) in the worker, shared by every run that made
+ * it, dropped with the last one. After each run its watch set is the reads of that run: what the previous
+ * run read and this one did not is let go.
+ *
+ * The runs. A "changed" for a watch runs the runs that hold it again — once for any number of signals
+ * that come during a run — and a new value is published through the host's channel publisher
+ * (`setChannelPublisher`) as an envelope to (computed id, subscription) for each subscription of the run:
+ * `{ ok, result }`, or the failure. A value equal to the last one that subscription had (JSON) is not
+ * published; a subscription that joined a run under way hears that run's next one. A subscription stands
+ * whatever its runs answer: only `end` lets it go — the hub decides that a failed FIRST run is a refusal.
+ *
+ * Presence. `watchers(...args)` / `members(group)` (./computed.ts, ./channel.ts) ask the host through the
+ * seam `setPresenceProvider` installs: the hub's table, over the host's IPC. Inside a run the read is
+ * recorded the way a db read is — before it is asked, so a join between the two runs it again — as a
+ * dependency on (export id, key); the hub says when the sessions of a key changed (`presenceChanged`: a
+ * join at once, a leave after its grace) and the runs that read it go again, through the same coalesced
+ * loop. A subscriber is present in its own value: the hub lists it once its first run is answered, and a
+ * read inside a run counts in, besides the hub's answer, every subscription of that key this worker has
+ * answered (the hub may not have heard of it yet) and, in a subscription's own first run, its subscriber.
+ * So `roomView.watchers(code)` inside `roomView(code)` never says "you are away", and a shared run's value
+ * lists every one of its subscribers.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks"
+import { presenceKey, type PresenceAsk } from "./channel"
+import type { RequestContext } from "./context"
+import type { MarciOp } from "./db/marci/query"
+import { isReadOp, type WatchOp, type WatchSource } from "./db/watch"
+import type { InvokeResult } from "./runtime"
+
+type Ctx = Omit<RequestContext, "id">
+
+/** A write inside a computed: the rule broken, said as such (a 500 with this message, and the server log). */
+export class ComputedWriteError extends Error {
+  constructor(id: string, op: Pick<MarciOp, "model" | "action">) {
+    super(`computed ${id}: ${op.model}.${op.action} is a write — a computed only reads (it runs again whenever its data changes); write in an endpoint`)
+    this.name = "ComputedWriteError"
+  }
+}
+
+type Scope = {
+  id: string
+  record: ((op: WatchOp) => Promise<void>) | null
+  /** a presence read of this run: (export id, key) is one of its inputs from now on */
+  heard: ((id: string, key: string) => void) | null
+  /** who a presence read of (export id, key) counts in besides the hub's answer: this worker's subscriptions of it */
+  present: ((id: string, key: string) => number[]) | null
+  /** the run's code read the request: its value is its subscriber's own */
+  read: (() => void) | null
+}
+const scope = new AsyncLocalStorage<Scope>()
+
+const gate = async (ops: MarciOp[]): Promise<void> => {
+  const s = scope.getStore()
+  if (!s) return
+  for (const op of ops) if (!isReadOp(op)) throw new ComputedWriteError(s.id, op)
+  if (s.record) for (const op of ops) await s.record({ model: op.model, action: op.action, query: op.query ?? {} })
+}
+
+/** Install the gate the bundle's db client calls (idempotent; every host factory of ./runtime.ts does it). */
+export const installDbGate = () => {
+  (globalThis as { __lecodesDbGate?: typeof gate }).__lecodesDbGate = gate
+}
+
+/** The request provider's hook (./runtime.ts): the code of the computed run in scope read the request —
+ *  `request.*`, `db.auth`, whatever reads the context the provider gives. Outside a run, nothing. */
+export const requestRead = () => { scope.getStore()?.read?.() }
+
+/** Run `fn` as computed `id` called once: a write inside is refused, nothing is recorded. */
+export const readOnly = <T>(id: string, fn: () => T): T => scope.run({ id, record: null, heard: null, present: null, read: null }, fn)
+
+/**
+ * Host hook (runner / local backend / test): where `watchers` and `members` get their answer — the hub's
+ * table (./channelHub.ts `presence`), over the host's IPC. The seam the bundle reads records the read in
+ * the computed run it is in, and counts in the subscriptions of that key this worker has answered.
+ */
+export const setPresenceProvider = (ask: PresenceAsk | null) => {
+  const seam = globalThis as { __lecodesPresence?: PresenceAsk }
+  if (!ask) { delete seam.__lecodesPresence; return }
+  seam.__lecodesPresence = async (id, key) => {
+    const s = scope.getStore()
+    s?.heard?.(id, key)
+    const here = await ask(id, key)
+    const more = (s?.present?.(id, key) ?? []).filter((n) => !here.includes(n))
+    return more.length ? [...here, ...more] : here
+  }
+}
+
+/** One run of a computed in a subscriber's request scope (./runtime.ts): `around` wraps the function alone;
+ *  `me` is the subscriber's `request.session` as it stands, minting nothing. */
+export type ComputedRun = (id: string, args: unknown[], ctx: Ctx, around: <T>(fn: () => T, me: () => number | undefined) => T) => Promise<InvokeResult>
+type Publisher = (ch: string, group: number, envelope: InvokeResult) => void
+
+export type ComputedHost = {
+  /** Subscription `sub` (the hub's number) of computed `id`: the first run, its envelope. From now on
+   *  the host keeps it fresh, until `end`. */
+  start(id: string, args: unknown[], ctx: Ctx, sub: number): Promise<InvokeResult>
+  /** The subscription is over (`null` = every one): its watches go. An unknown one is ignored. */
+  end(sub: number | null): void
+  /** The sessions subscribed to (`id`, `key`) changed (the hub says so): the runs that read them go again. */
+  presenceChanged(id: string, key: string): void
+  /** Every subscription ended and the source closed (the worker is going away). */
+  close(): void
+}
+
+type Watch = { key: string, id: number | null, ready: Promise<void>, runs: Set<Run> }
+/** What runs: one subscription's own, or — when it read nothing of the request — the one of every
+ *  subscription of its key (`shared`). */
+type Run = {
+  id: string, args: unknown[]
+  /** the key it is the run of (`shareKey`); null = one subscription's own */
+  shared: string | null
+  members: Set<Sub>
+  /** the watch set of the last finished run */
+  watched: Map<string, Watch>
+  /** the presence keys the last finished run read */
+  heard: Set<string>
+  /** the last finished run's envelope, as text */
+  last: string | undefined
+  /** how many runs began: a member that came during one hears the next */
+  runs: number
+  running: boolean
+  dirty: boolean
+  ended: boolean
+}
+type Sub = {
+  sub: number, id: string, args: unknown[], ctx: Ctx
+  /** what its first run said its subscriber is (`request.session`): who it is present as */
+  session: number | undefined
+  /** the last envelope it was sent (or answered), as text: a value's JSON, a failure's status and message */
+  last: string | undefined
+  /** the run it hears, from the run after number `since` */
+  run: Run
+  since: number
+}
+
+const opKey = (op: WatchOp) => JSON.stringify([op.model, op.action, op.query])
+const heardKey = (id: string, key: string) => JSON.stringify([id, key])
+/** What makes two subscriptions' runs one, when neither read the request: the export, the arguments — and
+ *  the base a stored file's url is made of (the request's, as the socket reached the backend). */
+const shareKey = (s: Sub) => JSON.stringify([s.id, s.args, s.ctx.filesBase ?? null])
+let opaque = 0
+const textOf = (r: InvokeResult) => {
+  if (!r.ok) return `!${r.status} ${r.message}`
+  // a value JSON cannot say (a BigInt, a cycle) equals nothing: it goes on, and fails where it is sent
+  try { return JSON.stringify(r.result === undefined ? null : r.result) } catch { return `?${opaque++}` }
+}
+/** What travels to the hub: the envelope without what only a call's response carries. */
+const bare = (r: InvokeResult): InvokeResult => r.ok ? { ok: true, result: r.result === undefined ? null : r.result } : { ok: false, status: r.status, message: r.message }
+
+export const computedSubscriptions = (opts: { run: ComputedRun, watch: WatchSource | null, publish?: Publisher }): ComputedHost => {
+  const { run, watch: source } = opts
+  const publish: Publisher = opts.publish ?? ((ch, group, envelope) => {
+    const p = (globalThis as { __lecodesPublish?: (ch: string, group: number, data: unknown) => void }).__lecodesPublish
+    if (!p) throw new Error("computed: no host publisher installed")
+    p(ch, group, envelope)
+  })
+  const subs = new Map<number, Sub>()
+  /** the shared runs, by their key */
+  const groups = new Map<string, Run>()
+  const watches = new Map<string, Watch>()
+  const byId = new Map<number, Watch>()
+  /** presence key → the runs that read it */
+  const listeners = new Map<string, Set<Run>>()
+  /** presence key (export id, its arguments) → the subscriptions of it this worker has answered */
+  const present = new Map<string, Set<Sub>>()
+
+  const listen = (key: string, r: Run) => {
+    let set = listeners.get(key)
+    if (!set) listeners.set(key, set = new Set())
+    set.add(r)
+  }
+  const unlisten = (key: string, r: Run) => {
+    const set = listeners.get(key)
+    if (set?.delete(r) && set.size === 0) listeners.delete(key)
+  }
+  const presentAt = (s: Sub) => heardKey(s.id, presenceKey(s.args))
+  const presentIn = (id: string, key: string, me: number | undefined): number[] => {
+    const out = new Set<number>()
+    for (const s of present.get(heardKey(id, key)) ?? []) if (s.session !== undefined) out.add(s.session)
+    if (me !== undefined) out.add(me)
+    return [...out]
+  }
+
+  const release = (w: Watch, r: Run) => {
+    if (!w.runs.delete(r) || w.runs.size) return
+    if (watches.get(w.key) === w) watches.delete(w.key)
+    const drop = () => { byId.delete(w.id!); source?.unwatch(w.id!) }
+    // the engine's answer may still be on its way: it goes once it came
+    if (w.id !== null) drop()
+    else void w.ready.then(drop, () => {})
+  }
+
+  /** A read of run `r` in the run whose watch set is `used`: watched before it is sent. */
+  const record = (r: Run, used: Map<string, Watch>) => async (op: WatchOp) => {
+    const key = opKey(op)
+    let w = used.get(key) ?? watches.get(key)
+    if (!w) {
+      if (!source) throw new Error(`computed ${r.id}: this host watches no database, so a computed that reads one cannot be kept fresh`)
+      const fresh: Watch = { key, id: null, ready: null as unknown as Promise<void>, runs: new Set() }
+      fresh.ready = source.watch(op).then(
+        (id) => { fresh.id = id; byId.set(id, fresh) },
+        (e) => { if (watches.get(key) === fresh) watches.delete(key); throw e },
+      )
+      watches.set(key, fresh)
+      w = fresh
+    }
+    // in the set from now on: a change while the run goes on runs it again
+    w.runs.add(r)
+    used.set(key, w)
+    await w.ready
+  }
+
+  const personal = (s: Sub): Run => {
+    const r: Run = { id: s.id, args: s.args, shared: null, members: new Set([s]), watched: new Map(), heard: new Set(), last: s.last, runs: 0, running: false, dirty: false, ended: false }
+    s.run = r
+    s.since = 0
+    return r
+  }
+
+  /** A run is over for good: its watches and its presence keys go (a run still going lets go of its own reads when it is back). */
+  const drop = (r: Run) => {
+    r.ended = true
+    if (r.shared !== null && groups.get(r.shared) === r) groups.delete(r.shared)
+    for (const w of r.watched.values()) release(w, r)
+    r.watched = new Map()
+    for (const k of r.heard) unlisten(k, r)
+    r.heard = new Set()
+  }
+
+  const runOnce = async (r: Run): Promise<{ result: InvokeResult, personal: boolean, n: number }> => {
+    // whose request scope it runs in: a shared one's code reads nothing of it
+    const by = r.members.values().next().value as Sub
+    const n = ++r.runs
+    const used = new Map<string, Watch>()
+    const heard = new Set<string>()
+    let read = false
+    const own = presenceKey(r.args)
+    const result = await run(r.id, r.args, by.ctx, (fn, me) => scope.run({
+      id: r.id,
+      record: record(r, used),
+      // in the set from now on, as a read: a join while the run goes on runs it again
+      heard: (id, key) => { const k = heardKey(id, key); heard.add(k); listen(k, r) },
+      // a subscription is present in its own value — before the hub has heard its answer, and as whoever
+      // its own run makes it (a session minted meanwhile)
+      present: (id, key) => presentIn(id, key, r.shared === null && id === r.id && key === own ? me() : undefined),
+      read: () => { read = true },
+    }, fn))
+    // a token minted by this run (a device's first contact): the next runs are that device's
+    if (result.session) by.ctx = { ...by.ctx, sessionToken: result.session, headers: { ...by.ctx.headers, authorization: `Bearer ${result.session}` } }
+    for (const [key, w] of r.watched) if (!used.has(key)) release(w, r)
+    r.watched = used
+    for (const k of r.heard) if (!heard.has(k)) unlisten(k, r)
+    r.heard = heard
+    if (r.ended) {
+      for (const w of used.values()) release(w, r)
+      for (const k of heard) unlisten(k, r)
+    }
+    return { result, personal: read, n }
+  }
+
+  /** Run `r` read nothing of the request: it is its key's run from now on — or the key has one, which takes its subscription. */
+  const share = (r: Run) => {
+    const [s] = r.members
+    const key = shareKey(s)
+    const g = groups.get(key)
+    if (!g) { r.shared = key; groups.set(key, r); return }
+    g.members.add(s)
+    s.run = g
+    s.since = g.runs
+    drop(r)
+    // its value may be newer or older than the key's, or the key's run under way began before it came: one more run says
+    if (r.dirty || g.running || s.last !== g.last) schedule(g)
+  }
+
+  /** The shared run `g` read the request: each of its subscriptions runs its own from now on, starting from its
+   *  watches and presence keys (a change before the first of them is not lost, nothing is watched twice). */
+  const split = (g: Run) => {
+    const members = [...g.members]
+    g.members.clear()
+    for (const s of members) {
+      const p = personal(s)
+      for (const [k, w] of g.watched) { w.runs.add(p); p.watched.set(k, w) }
+      for (const k of g.heard) { listen(k, p); p.heard.add(k) }
+      schedule(p)
+    }
+    drop(g)
+  }
+
+  const loop = async (r: Run) => {
+    try {
+      while (r.dirty && !r.ended) {
+        r.dirty = false
+        const { result, personal: mine, n } = await runOnce(r)
+        if (r.ended) return
+        // the value is one subscriber's: its run says nothing to the others
+        if (r.shared !== null && mine) { split(r); return }
+        const text = textOf(result)
+        r.last = text
+        for (const s of r.members) {
+          if (s.since >= n || s.last === text) continue
+          s.last = text
+          publish(s.id, s.sub, bare(result))
+        }
+        if (r.shared === null && !mine) share(r)
+      }
+    } finally {
+      r.running = false
+    }
+  }
+
+  const schedule = (r: Run) => {
+    if (r.ended) return
+    r.dirty = true
+    if (r.running) return
+    r.running = true
+    void loop(r)
+  }
+
+  const end = (sub: number) => {
+    const s = subs.get(sub)
+    if (!s) return
+    subs.delete(sub)
+    const at = presentAt(s)
+    const set = present.get(at)
+    if (set?.delete(s) && set.size === 0) present.delete(at)
+    const r = s.run
+    r.members.delete(s)
+    if (r.members.size === 0) drop(r)
+  }
+
+  source?.onChanged((ids) => {
+    const hit = new Set<Run>()
+    for (const id of ids) for (const r of byId.get(id)?.runs ?? []) hit.add(r)
+    for (const r of hit) schedule(r)
+  })
+
+  return {
+    async start(id, args, ctx, sub) {
+      end(sub)
+      const s = { sub, id, args, ctx, session: undefined, last: undefined, since: 0 } as Sub
+      const r = personal(s)
+      r.running = true
+      subs.set(sub, s)
+      let out: Awaited<ReturnType<typeof runOnce>>
+      try {
+        out = await runOnce(r)
+      } catch (e) {
+        r.running = false
+        throw e
+      }
+      const { result, personal: mine } = out
+      s.last = r.last = textOf(result)
+      if (result.ok && subs.get(sub) === s) {
+        s.session = result.subscriber
+        const at = presentAt(s)
+        let set = present.get(at)
+        if (!set) present.set(at, set = new Set())
+        set.add(s)
+      }
+      // what comes after the first run goes once its answer is on its way (a timer, not a microtask — the
+      // host posts the answer first, the hub hears the two in order): a run that read nothing of the request
+      // joins its key's, and a change during it runs it again
+      setTimeout(() => {
+        r.running = false
+        if (r.ended) return
+        if (result.ok && !mine) share(r)
+        if (!r.ended && r.dirty) { r.dirty = false; schedule(r) }
+      }, 0)
+      return result
+    },
+    end(sub) {
+      if (sub === null) for (const key of [...subs.keys()]) end(key)
+      else end(sub)
+    },
+    presenceChanged(id, key) {
+      for (const r of [...listeners.get(heardKey(id, key)) ?? []]) schedule(r)
+    },
+    close() {
+      for (const key of [...subs.keys()]) end(key)
+      source?.close()
+    },
+  }
+}

package/src/server/context.ts

@@ -4,6 +4,10 @@
  * server bundle carries its own copy of this module (chisel bundles the SDK in), so the host can't
  * hand it a value by import. `request` reads through that seam; outside a request (module load,
  * timers after the response) every member is undefined.
+ *
+ * `session` is decided in ONE place, the host runtime (./runtime.ts `defineSession`), for endpoints
+ * and channel hooks alike: every host (the runner, `lecodes dev`, a test) gets it by running calls
+ * through `createInvoker` / `createSubscribeGuard`.
  */
 
 export type RequestContext = {
@@ -15,13 +19,18 @@ export type RequestContext = {
   sessionToken?: string
   /** Set by the auth runtime after resolving the token — read via `db.auth`, not here. */
   auth?: unknown
+  /** The device of the request — `request.session`. Defined by the host runtime (./runtime.ts), read lazily:
+   *  a host never sets it. */
+  readonly session?: number
   /** The files a multipart call carried, as the receiving process left them (./files/host.ts `Upload`). */
   uploads?: unknown[]
   /** What `/files/<id>/<name>` is appended to in a stored file's url: the backend's own base, as this request reached it. */
   filesBase?: string
 }
 
-type Provider = () => RequestContext | undefined
+/** `quiet`: the host's own read, not the code's (a stored file's url is made of the request's `filesBase`).
+ *  Every other read is the code's: inside a computed it makes the run its subscriber's alone (./computedHost.ts). */
+type Provider = (quiet?: boolean) => RequestContext | undefined
 const seam = globalThis as unknown as { __lecodesRequest?: Provider }
 
 /** Host hook (runner / test harness): install the current-request provider. */
@@ -30,11 +39,14 @@ export const setRequestProvider = (provider: Provider | null) => {
   else delete seam.__lecodesRequest
 }
 /** @internal */
-export const currentRequest = (): RequestContext | undefined => seam.__lecodesRequest?.()
+export const currentRequest = (quiet?: boolean): RequestContext | undefined => seam.__lecodesRequest?.(quiet)
 
 /** The current request (server global). Undefined members outside a request. */
 export const request = {
   get id(): string | undefined { return currentRequest()?.id },
   get headers(): Record<string, string> { return currentRequest()?.headers ?? {} },
   get ip(): string | undefined { return currentRequest()?.ip },
+  /** The calling device: a number that stays the same for as long as the app keeps its storage, without
+   *  sign-in; with `withAuth` it is `db.auth.sessionId`. Not a secret — the token behind it is. */
+  get session(): number | undefined { return currentRequest()?.session },
 }

package/src/server/db/defineDb.ts

@@ -13,7 +13,7 @@ import { createAuthApi } from "../auth/api"
 import { AUTH_IDENTITY_MODEL, AUTH_SESSION_MODEL, identityFields, sessionFields } from "../auth/models"
 import { createFileLayer } from "../files/db"
 import { FILE_MODEL, fileFields, fileOwnerKey, type FileField } from "../files/models"
-import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta } from "./marci/query"
+import { createQueryLayer, type FieldDesc, type MarciOp, type MarciTransport, type ModelsMeta, type WatchRegistration } from "./marci/query"
 import type { AuthBinding, Db, Fields, Model, Schema, ValidateRefs } from "./types"
 
 export const model = <F extends Fields>(fields: F): Model<F> => ({ fields, __model: true })
@@ -22,7 +22,7 @@ export const model = <F extends Fields>(fields: F): Model<F> => ({ fields, __mod
 
 // A GLOBAL seam (not a module variable): the compiled server bundle carries its own copy of this
 // module, so the host's `setDbTransport` and the bundle's `defineDb` only meet through globalThis.
-const seam = globalThis as unknown as { __lecodesDbTransport?: MarciTransport, __lecodesDbs?: Db<any>[] }
+const seam = globalThis as unknown as { __lecodesDbTransport?: MarciTransport, __lecodesDbs?: Db<any>[], __lecodesDbGate?: (ops: MarciOp[]) => Promise<void> }
 /** Host hook: the runner/dev-server installs the project's transport before loading user code. */
 export const setDbTransport = (transport: MarciTransport | null) => {
   if (transport) seam.__lecodesDbTransport = transport
@@ -60,6 +60,17 @@ type ModelMeta = {
 
 const isRel = (d: FieldDef) => d.kind === "one" || d.kind === "many" || d.kind === "list"
 
+/** A default the engine would refuse at `$sync` (the server's start) is refused here, where the model is
+ *  written: a date's is `"now"` or whole milliseconds since 1970; a json's is a JSON value. */
+const checkDefault = (model: string, key: string, d: FieldDef) => {
+  if (!d.hasDefault) return
+  const v = d.default
+  if (d.scalar === "date" && v !== "now" && !(typeof v === "number" && Number.isInteger(v)))
+    throw new Error(`defineDb: ${model}.${key}: a date's default is "now" or a number of milliseconds since 1970, not ${JSON.stringify(v)}`)
+  if (d.kind === "json" && (v == null || JSON.stringify(v) === undefined))
+    throw new Error(`defineDb: ${model}.${key}: a json default must be a JSON value (an object, a list, a string, a number, a boolean) — for "no value" make the field .optional()`)
+}
+
 const buildMeta = (models: Record<string, Model>): Record<string, ModelMeta> => {
   const metas: Record<string, ModelMeta> = {}
   for (const [name, m] of Object.entries(models)) {
@@ -69,6 +80,7 @@ const buildMeta = (models: Record<string, Model>): Record<string, ModelMeta> =>
       const def = (f as Field<any, any>).def
       if (def.kind === "struct" && Object.values(def.fields!).some(inner => (inner as Field<any, any>).def.kind === "file"))
         throw new Error(`defineDb: ${name}.${key} — a file belongs to a model's row: put the t.file() field on ${name} itself, not inside a struct`)
+      checkDefault(name, key, def)
       fields[key] = { ...def }
     }
     if (fields.id && !fields.id.isId) fields.id.isId = true
@@ -111,6 +123,7 @@ const ON_DELETE = { cascade: "Cascade", setNull: "SetNull", restrict: "Restrict"
 
 const literal = (v: unknown, d: FieldDef): string => {
   if (d.scalar === "date" && v === "now") return "now()"
+  if (d.kind === "json") return JSON.stringify(v)           // `Json @default(<JSON literal>)`, compact
   if (Array.isArray(v)) return `[${v.map(x => literal(x, { ...d, array: false })).join(", ")}]`
   if (typeof v === "string") return d.kind === "enum" ? v : JSON.stringify(v)
   return String(v)
@@ -236,21 +249,33 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
     if (!t) throw new Error("db: no transport — the host must call setDbTransport() before user code runs")
     return t
   }
+  // The host looks at what goes out before it does (a GLOBAL seam, as the transport's): inside a
+  // `computed` a write is refused and every read is recorded (../computedHost.ts). No host, no look.
+  const send = async (op: MarciOp): Promise<any> => {
+    const gate = seam.__lecodesDbGate
+    if (gate) await gate([op])
+    return transport().exec(op)
+  }
+  const sendBatch = async (ops: MarciOp[]): Promise<any[]> => {
+    const gate = seam.__lecodesDbGate
+    if (gate) await gate(ops)
+    return transport().batch(ops)
+  }
   // A db with file fields runs every operation through the file layer: a write of a file field is the
   // row's operation and the ones on File after it, in one transaction.
   let files: ReturnType<typeof createFileLayer> | null = null
   const exec = async (op: MarciOp): Promise<any> => {
-    if (!files) return transport().exec(op)
+    if (!files) return send(op)
     const plan = await files.plan(op, 0)
-    if (!plan.after.length) return files.result(plan.op, await transport().exec(plan.op))
-    return (await transport().batch([plan.op, ...plan.after]))[0]
+    if (!plan.after.length) return files.result(plan.op, await send(plan.op))
+    return (await sendBatch([plan.op, ...plan.after]))[0]
   }
   const batch = async (ops: MarciOp[]): Promise<any[]> => {
-    if (!files) return transport().batch(ops)
+    if (!files) return sendBatch(ops)
     // the project's operations keep their places (its `ref`s count them); what follows them goes after
     const plans: Awaited<ReturnType<typeof files.plan>>[] = []
     for (let index = 0; index < ops.length; index++) plans.push(await files.plan(ops[index], index))
-    const results = await transport().batch([...plans.map(p => p.op), ...plans.flatMap(p => p.after)])
+    const results = await sendBatch([...plans.map(p => p.op), ...plans.flatMap(p => p.after)])
     return plans.map((p, index) => files!.result(p.op, results[index]))
   }
   const seal = () => {
@@ -292,6 +317,21 @@ export const defineDb = <const S extends Schema>(declared: S & ValidateRefs<S>,
       prepareInsert: (name, data) => metas[name].uuidId && data?.id == null ? { ...data, id: crypto.randomUUID() } : data,
       // an upsert that creates the row needs the id a uuid model leaves to the client; the key wins when it is the id
       prepareUpsert: (name, onInsert) => metas[name].uuidId ? { id: crypto.randomUUID(), ...(onInsert ?? {}) } : onInsert,
+      // `op.watch`: the transport's watches, of the op as the database sees it (a file field is its relation);
+      // the reads again go through `exec`, as any read
+      watch: (op, listener) => {
+        const t = transport()
+        if (!t.watch) throw new Error("db: this host's database cannot watch — op.watch needs a transport with watch()")
+        if (!files) return t.watch(op, listener)
+        let reg: WatchRegistration | null = null
+        let closed = false
+        const ready = files.plan(op, 0).then((plan) => {
+          if (closed) return
+          reg = t.watch!(plan.op, listener)
+          return reg.ready
+        })
+        return { ready, close() { closed = true; reg?.close() } }
+      },
     })
     const collections: Record<string, unknown> = {}
     for (const name of Object.keys(own)) collections[name] = collection(name)

package/src/server/db/fields.ts

@@ -71,7 +71,8 @@ export interface Field<T, M extends FieldMeta = FieldMeta> {
   unique(group?: string): Field<T, M>
   /** `@index` — used by `$where`, `$order`, aggregations. */
   index(): Field<T, M>
-  /** `@default(...)`; `"now"` on `t.date()` → `now()`. Makes the field optional on insert. */
+  /** `@default(...)`; `"now"` on `t.date()` → `now()`, a number is milliseconds since 1970; a json's is
+   *  any JSON value (`t.json<number[]>().default([])`). Makes the field optional on insert. */
   default(value: DefaultOf<T, M>): Field<T, SetMeta<M, "hasDefault", true>>
   /** Primitive list (`String[]`). */
   array(): Field<T, SetMeta<M, "array", true>>

package/src/server/db/httpTransport.ts

@@ -6,10 +6,14 @@
  *
  * `baseUrl` = `http://host:port/<db>`; an optional bearer token (marcidb-server `MARCI_TOKEN`) is sent
  * on every request. Pass `fetch` explicitly when the global one might be monkey-patched by untrusted
- * code running in the same realm (the runner captures it before evaluating a project bundle).
+ * code running in the same realm (the runner captures it before evaluating a project bundle) — and
+ * `WebSocket` likewise for `op.watch`, which rides the database's watch socket (./httpWatch.ts, opened
+ * with the first watch and in a context of its own, not the request's that asked for it).
  */
 
-import type { MarciOp, MarciTransport } from "./marci/query"
+import { marciHttpWatchSource, type WatchSocketCtor } from "./httpWatch"
+import type { MarciOp, MarciTransport, WatchListener } from "./marci/query"
+import { outsideRequests, type WatchSource } from "./watch"
 
 /** A failed marcidb request: `status` is the HTTP status (0 = network failure), `kind` the server's class of the
  *  failure — a constraint (`unique`, `foreign_key`, `restrict`, `duplicate_id`), `not_found`, `bad_request`,
@@ -39,6 +43,8 @@ const failure = (status: number, text: string): MarciHttpError => {
 export type MarciHttpOptions = {
   token?: string | null
   fetch?: typeof fetch
+  /** The watch socket's constructor (`op.watch`); default the global one. */
+  WebSocket?: WatchSocketCtor
 }
 
 /** `update/:id` and `delete/:id` take the key in the path: a bare value, or `k=v&k2=v2` for composite keys
@@ -85,7 +91,36 @@ export const marciRequest = async (
 export const marciHttpTransport = (baseUrl: string, options: MarciHttpOptions = {}): MarciTransport => {
   const url = baseUrl.replace(/\/+$/, "")
   const call = (path: string, body?: unknown, method?: string) => marciRequest(`${url}/${path}`, { body, method, token: options.token, fetch: options.fetch })
+  // `op.watch`: the signals of the database's watch socket, made with the first watch
+  let source: WatchSource | null = null
+  const listeners = new Map<number, WatchListener>()
+  const watches = () => {
+    if (source) return source
+    source = marciHttpWatchSource(url, { token: options.token, WebSocket: options.WebSocket })
+    source.onChanged((ids) => { for (const id of ids) listeners.get(id)?.changed() })
+    return source
+  }
   return {
+    watch(op, listener) {
+      const src = watches()
+      let id: number | null = null
+      let closed = false
+      const ready = outsideRequests(() => src.watch({ model: op.model, action: op.action, query: op.query ?? {} })).then((n) => {
+        if (closed) { src.unwatch(n); return }
+        id = n
+        listeners.set(n, listener)
+      })
+      return {
+        ready,
+        close() {
+          if (closed) return
+          closed = true
+          if (id === null) return
+          listeners.delete(id)
+          src.unwatch(id)
+        },
+      }
+    },
     exec(op: MarciOp) {
       switch (op.action) {
         case "findMany":   return call(`${op.model}/findMany`, op.query ?? {})