@weft-js/start 0.1.0 → 0.1.2

package/src/hub/feed.ts

@@ -0,0 +1,168 @@
+import { createFeed, functionHost, type Feed, type Probe, type Source } from '../changes'
+import { StartError } from '../data'
+import { defaultStore } from '../exec'
+import type { Channel, Conn, HubOptions, Limits, LiveState } from './types'
+
+const proc = globalThis as unknown as {
+  process?: { env: Record<string, string | undefined>; exit(code: number): void }
+}
+const unref = <T>(t: T) => ((t as { unref?(): void } | null | undefined)?.unref?.(), t)
+interface FeedState {
+  options: HubOptions
+  limits: Limits
+  conns: Map<string, Conn>
+  pokes: () => Channel
+  source: Source | undefined
+  live: LiveState
+  refused: StartError | undefined
+  feed: Feed | undefined
+  probed: Promise<unknown>
+  waking: Promise<unknown> | undefined
+  resting: ReturnType<typeof setTimeout> | undefined
+  beats: ReturnType<typeof setInterval> | undefined
+  beat: number
+}
+function report(state: FeedState, code: string, severity: string, message: string) {
+  state.options.onDiagnostic?.({ code, severity, message })
+}
+function wire(state: FeedState) {
+  return { m: state.live.mode, ...(state.live.down && { d: 1 }) }
+}
+function status(state: FeedState, down: string | undefined) {
+  if (state.live.down === down) return
+  state.live = { ...state.live, down }
+  if (down) report(state, 'R016', 'warning', `live: ${down}`)
+  for (const c of state.conns.values()) c.sink.write('L', JSON.stringify(wire(state)))
+}
+
+/** Probes rather than assumes (`what works here`), says what it found once, and refuses to serve what was required. */
+async function settle(state: FeedState, src: Source) {
+  const { options } = state
+  const host = functionHost()
+  const how: Probe = src.external
+    ? { mode: 'feed', via: 'listener' }
+    : host
+      ? {
+          mode: 'off',
+          via: 'none',
+          why: `${host} ends a process with its request, so nothing can hold a database connection`,
+          fix: "run `weft db listen` on an always-on host and set `listener: 'external'`, or deploy to a server preset",
+        }
+      : await src.probe().catch((e) => ({
+          mode: 'off' as const,
+          via: 'none',
+          why: e instanceof Error ? e.message : String(e),
+          fix: 'check the database',
+        }))
+  state.live = {
+    mode: src.external ? 'external' : how.mode,
+    via: how.via,
+    why: how.why,
+    fix: how.fix,
+  }
+  const line = `live: ${state.live.mode} (${state.live.via})${how.why ? `: ${how.why}` : ''}`
+  if (how.mode === 'feed') console.info(`weft ${line}`)
+  else {
+    console.warn(`weft ${line}${how.fix ? `\n  fix: ${how.fix}` : ''}`)
+    report(state, 'R016', 'warning', `${line}. \`.live()\` shows \`degraded\``)
+  }
+  if (how.mode === 'feed' || !options.required?.length) return how
+  state.refused = new StartError(
+    'R015',
+    `${options.required.map((n) => `\`${n}\``).join(', ')} require${options.required.length > 1 ? '' : 's'} a live feed, and this server has ${how.mode === 'poll' ? 'only polling' : 'none'}${how.why ? `: ${how.why}` : ''}`,
+    how.fix ?? 'see `weft doctor`',
+    { status: 503 },
+  )
+  console.error(`weft ${state.refused.message}`)
+  if (!options.dev) proc.process?.exit(1)
+  return how
+}
+
+/** The feed runs while someone can use it: a server with no clients holds no listener and runs no watcher. */
+function want(state: FeedState) {
+  const { source, limits, pokes } = state
+  clearTimeout(state.resting)
+  state.resting = undefined
+  if (!source) return
+  if (source.external) {
+    if (state.beats) return
+    state.beat = Date.now()
+    void pokes()
+    state.beats = unref(
+      setInterval(() => {
+        if (Date.now() - state.beat > limits.window / 2)
+          status(state, 'the external listener has gone quiet')
+      }, limits.heartbeat / 2),
+    )
+    return
+  }
+  return (state.waking ??= state.probed
+    .then((how) => state.feed!.start(how as Probe))
+    .catch((e) => status(state, e instanceof Error ? e.message : String(e)))
+    .finally(() => {
+      state.waking = undefined
+    }))
+}
+
+function rest(state: FeedState) {
+  const { source, conns, feed, limits } = state
+  if (!source || conns.size || state.resting || !feed?.running) return
+  state.resting = unref(
+    setTimeout(() => {
+      state.resting = undefined
+      if (!conns.size) void feed.stop()
+    }, limits.window),
+  )
+}
+
+export function createFeedState(
+  options: HubOptions,
+  limits: Limits,
+  conns: Map<string, Conn>,
+  pokes: () => Channel,
+) {
+  const source = options.changes
+  const state: FeedState = {
+    options,
+    limits,
+    conns,
+    pokes,
+    source,
+    live: source
+      ? { mode: 'off', via: 'none', why: 'not probed yet' }
+      : { mode: 'app', via: 'mutations' },
+    refused: undefined,
+    feed: undefined,
+    probed: Promise.resolve(),
+    waking: undefined,
+    resting: undefined,
+    beats: undefined,
+    beat: 0,
+  }
+  state.feed =
+    source &&
+    createFeed(source, {
+      emit: (p) => pokes().got(JSON.stringify(p)),
+      bump: (tags) => void (options.store ?? defaultStore).bump(tags),
+      status: (down) => status(state, down),
+    })
+  state.probed = source && !proc.process?.env.WEFT_BUILD ? settle(state, source) : Promise.resolve()
+  state.probed.catch(() => {})
+  return {
+    want: () => want(state),
+    rest: () => rest(state),
+    wire: () => wire(state),
+    heartbeat: () => {
+      state.beat = Date.now()
+      status(state, undefined)
+    },
+    live: () => state.live,
+    refused: () => state.refused,
+    probed: state.probed,
+    feed: state.feed,
+    clear: () => {
+      clearTimeout(state.resting)
+      clearInterval(state.beats)
+    },
+  }
+}

package/src/hub/presence.ts

@@ -0,0 +1,64 @@
+import type { Poke } from '../changes'
+import type { Channel, Conn, Ev } from './types'
+
+interface Dependencies {
+  channels: Map<string, Channel>
+  channel: (name: string) => Channel
+  conns: Map<string, Conn>
+  watchers: Set<(tags: string[]) => void>
+  cursorOf: (n: number) => string
+  seq: () => number
+  poke: (c: Conn, tags: string[], at: number) => void
+  replay: (ch: Channel, after: string) => Ev[] | undefined
+  heartbeat: () => void
+}
+
+/** Listens from the first realtime use on, not from boot: `weft build` loads this with no bus to reach. */
+function pokes(deps: Dependencies): Channel {
+  const { channels, channel, conns, cursorOf, seq, poke, watchers, heartbeat } = deps
+  const had = channels.get('weft:poke')
+  if (had) return had
+  const ch = channel('weft:poke')
+  ch.listeners.add((ev) => {
+    if (!ev) {
+      for (const c of conns.values()) c.sink.write('R', JSON.stringify({ c: cursorOf(seq()) }))
+      return
+    }
+    const m = JSON.parse(ev.raw) as Poke & { o?: string; b?: 1 }
+    if (m.b) {
+      // an external listener's heartbeat
+      return heartbeat()
+    }
+    for (const c of conns.values()) if (c.k !== m.o) poke(c, picked(c, m), ev.seq)
+    for (const w of watchers) w(m.t)
+  })
+  return ch
+}
+
+/** What this connection subscribed to. `k`: a mutation's poke already reaches a subscription with one of these tags. */
+function picked(c: Conn, { t, p, k }: Poke) {
+  if (!p && !k) return t.filter((x) => c.tags.has(x))
+  const out = new Set<string>()
+  for (const s of c.subs.values()) {
+    if (k && s.tags.some((x) => k.includes(x))) continue
+    for (const x of s.tags) if (t.includes(x) || p?.some((pre) => x.startsWith(pre))) out.add(x)
+  }
+  return [...out]
+}
+
+function replayPokes(deps: Dependencies, c: Conn, after: string) {
+  const { replay, poke, cursorOf, seq } = deps
+  const list = replay(pokes(deps), after)
+  if (!list) return c.sink.write('R', JSON.stringify({ c: cursorOf(seq()) }))
+  for (const ev of list) {
+    const m = JSON.parse(ev.raw) as Poke & { o?: string }
+    if (m.o !== c.k) poke(c, picked(c, m), ev.seq)
+  }
+}
+
+export function createPresence(deps: Dependencies) {
+  return {
+    pokes: () => pokes(deps),
+    replayPokes: (c: Conn, after: string) => replayPokes(deps, c, after),
+  }
+}

package/src/hub/route.ts

@@ -0,0 +1,158 @@
+import { StartError } from '../data'
+import { sessionOf } from '../mux-session'
+import type { Scope } from '../exec'
+import type { Body, Conn, Hub, Sink } from '../hub'
+
+// ---- the HTTP route -------------------------------------------------------------------------------------------------
+
+const enc = new TextEncoder()
+/** Whether a request body has the shape of `Body`. */
+export const validBody = (input: unknown): input is Body => {
+  const b = input as Partial<Record<keyof Body, unknown>> | null | undefined
+  return (
+    !!b &&
+    typeof b === 'object' &&
+    !Array.isArray(b) &&
+    (b.k === undefined || typeof b.k === 'string') &&
+    (b.c === undefined || typeof b.c === 'string') &&
+    (b.d === undefined ||
+      (Array.isArray(b.d) && b.d.every((n: unknown) => typeof n === 'number'))) &&
+    (b.s === undefined ||
+      (Array.isArray(b.s) &&
+        b.s.every(
+          (e: unknown) =>
+            Array.isArray(e) &&
+            typeof e[0] === 'number' &&
+            (e[1] === 'q' || e[1] === 's') &&
+            typeof e[2] === 'string',
+        )))
+  )
+}
+
+/** `/_weft/rt` (research 30 §4): opens a connection, or changes one. Same proof as a mutation, plus `origins`. */
+export async function handleRoute(
+  request: Request,
+  scope: Scope,
+  origins: string[],
+  hub: () => Hub,
+): Promise<Response> {
+  const refuse = (code: string, message: string, status: number) => {
+    scope.options.onDiagnostic?.({ code, severity: 'error', message })
+    return Response.json(
+      { e: { code, message } },
+      { status, headers: { 'cache-control': 'no-store' } },
+    )
+  }
+  if (request.method !== 'POST') return refuse('Q010', 'Q010: `/_weft/rt` needs POST', 405)
+  const url = new URL(request.url)
+  const origin = request.headers.get('origin')
+  const site = request.headers.get('sec-fetch-site')
+  const allowed = origin && origins.includes(origin)
+  if (
+    !allowed &&
+    ((origin && origin !== url.origin) || (site && site !== 'same-origin' && site !== 'none'))
+  )
+    return refuse(
+      'R010',
+      `R010: origin \`${origin ?? site}\` may not open a realtime connection: list it in \`realtime({ origins })\``,
+      403,
+    )
+  if (
+    request.headers.get('x-weft') !== '1' ||
+    !request.headers.get('content-type')?.startsWith('application/json')
+  )
+    return refuse(
+      'Q010',
+      'Q010: `/_weft/rt` without the CSRF proof (POST + JSON + `x-weft: 1`)',
+      403,
+    )
+  const h = hub()
+  const raw = await request.text()
+  if (raw.length > h.limits.body)
+    return refuse(
+      'R008',
+      `R008: a realtime request of ${raw.length} bytes; the limit is ${h.limits.body}`,
+      413,
+    )
+  let body: Body
+  try {
+    body = JSON.parse(raw)
+  } catch {
+    return refuse('Q002', "Q002: `/_weft/rt` got a body that isn't JSON", 400)
+  }
+  // A tab that didn't dial the shared socket asks who it is now (link.ts).
+  if ((body as { w?: 1 })?.w === 1)
+    return Response.json(
+      { u: await sessionOf(await scope.ctx()) },
+      { headers: { 'cache-control': 'no-store' } },
+    )
+  if (!validBody(body))
+    return refuse('Q002', 'Q002: `/_weft/rt` got a body of the wrong shape', 400)
+  if (body.k) {
+    const c = h.find(body.k)
+    const user = c && ((await scope.ctx()) as { user?: { id?: string } }).user?.id
+    if (!c || c.user !== user)
+      return refuse('Q009', 'Q009: no such realtime connection (reconnect with the whole set)', 404)
+    await h.change(c, request, scope.options, body)
+    return new Response(null, { status: 204 })
+  }
+  return openStream(request, scope, body, h, refuse)
+}
+
+async function openStream(
+  request: Request,
+  scope: Scope,
+  body: Body,
+  h: Hub,
+  refuse: (code: string, message: string, status: number) => Response,
+): Promise<Response> {
+  let conn: Conn | undefined
+  let queued = 0
+  let controller!: ReadableStreamDefaultController<Uint8Array>
+  const push = (text: string) => {
+    const bytes = enc.encode(text)
+    queued += bytes.length
+    controller.enqueue(bytes)
+  }
+  const sink: Sink = {
+    write: (event, data) => push(`event: ${event}\ndata: ${data}\n\n`),
+    ping: () => push(': ping\n\n'),
+    backlog: () => queued,
+    close: () => {
+      try {
+        controller.close()
+      } catch {}
+    },
+  }
+  const out = new ReadableStream<Uint8Array>(
+    {
+      start: (c) => void (controller = c),
+      // The reader took what was queued: the strategy's hwm of 0 means every pull is an empty queue.
+      pull() {
+        queued = 0
+        if (conn) h.drain(conn)
+      },
+      cancel() {
+        if (conn) h.close(conn)
+        else closed = true
+      },
+    },
+    { highWaterMark: 0 },
+  )
+  let closed = false
+  try {
+    conn = await h.connect(request, scope, body, sink)
+  } catch (e) {
+    if (e instanceof StartError) return refuse(e.code, e.message, (e.extra.status as number) ?? 500)
+    throw e
+  }
+  if (closed) h.close(conn)
+  return new Response(out, {
+    headers: {
+      'content-type': 'text/event-stream',
+      'cache-control': 'no-store',
+      'x-accel-buffering': 'no',
+      connection: 'keep-alive',
+    },
+  })
+}

package/src/hub/subscriptions.ts

@@ -0,0 +1,212 @@
+import { enter, fns, StartError, type Context, type Fn } from '../data'
+import {
+  createScope,
+  guard,
+  liveQueries,
+  missedFeed,
+  tagsOf,
+  validate,
+  type ScopeOptions,
+} from '../exec'
+import type { Source } from '../changes'
+import type { Body, Conn, Limits, Sub, SubEntry } from './types'
+import { RESET, Tracked } from './tracked'
+
+interface Dependencies {
+  limits: Limits
+  source: Source | undefined
+  deliver: (c: Conn, s: Sub, raw: string) => boolean
+}
+
+/** A subscription refused before it existed. */
+const refuse = (c: Conn, n: number, e: StartError) =>
+  c.sink.write('e', JSON.stringify([n, { code: e.code, message: e.message }]))
+
+function fail(c: Conn, s: Sub, e: unknown) {
+  remove(c, s)
+  if (e instanceof StartError)
+    return c.sink.write(
+      'e',
+      JSON.stringify([
+        s.n,
+        {
+          code: e.code,
+          message: e.message,
+          ...(e.extra.issues ? { issues: e.extra.issues } : {}),
+        },
+      ]),
+    )
+  s.options.onDiagnostic?.({
+    code: 'E_RT',
+    severity: 'error',
+    message: `${s.fn.$id}: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`,
+  })
+  c.sink.write(
+    'e',
+    JSON.stringify([
+      s.n,
+      { message: s.options.dev && e instanceof Error ? e.message : 'Subscription failed.' },
+    ]),
+  )
+}
+
+function remove(c: Conn, s: Sub) {
+  s.ac.abort()
+  c.subs.delete(s.n)
+  c.held.delete(s)
+  for (const x of s.q) c.bytes -= x.size
+  for (const t of s.tags) {
+    const left = c.tags.get(t)! - 1
+    left ? c.tags.set(t, left) : c.tags.delete(t)
+  }
+}
+
+async function add(
+  deps: Dependencies,
+  c: Conn,
+  entry: SubEntry,
+  request: Request,
+  scoped: ScopeOptions,
+) {
+  const { limits, source } = deps
+  const [n, kind, id, input, cursor, buffer] = entry
+  const fn = fns.get(id)
+  if (c.subs.size >= limits.subscriptions)
+    return refuse(
+      c,
+      n,
+      new StartError(
+        'R009',
+        `this connection already has ${limits.subscriptions} subscriptions`,
+        'read fewer keys, or raise `limits.subscriptions`',
+      ),
+    )
+  if (!fn || fn.kind !== (kind === 'q' ? 'query' : 'stream'))
+    return refuse(
+      c,
+      n,
+      new StartError(
+        'Q009',
+        `no ${kind === 'q' ? 'query' : 'stream'} \`${id}\` (the page is older than the server): reload`,
+      ),
+    )
+  if (c.subs.has(n)) return
+  const s: Sub = {
+    n,
+    kind,
+    fn,
+    input,
+    tags: [],
+    buffer: buffer ?? 0,
+    q: [],
+    ac: new AbortController(),
+    request,
+    options: scoped,
+  }
+  c.subs.set(n, s) // before any await: a `d` that follows finds it
+  try {
+    const valid = await validate(fn, input)
+    if (s.ac.signal.aborted) return
+    if (kind === 's') return void stream(deps, c, s, valid, cursor)
+    guard(fn, fn.def.auth ? await createScope(request, scoped).ctx() : ({} as Context))
+    if (s.ac.signal.aborted) return
+    s.tags = await tagsOf(fn, valid, createScope(request, scoped))
+    for (const t of s.tags) c.tags.set(t, (c.tags.get(t) ?? 0) + 1)
+    if (scoped.dev) {
+      liveQueries.set(fn.$id, s.tags)
+      if (source) missedFeed(fn, s.tags, source.tables, scoped.onDiagnostic)
+      if (!s.tags.length)
+        scoped.onDiagnostic?.({
+          code: 'W053',
+          severity: 'error',
+          message: `\`${fn.$id}\` is read with \`.live()\` but declares no \`tags\`: no mutation can ever poke it. Add \`tags\` to the query`,
+        })
+    }
+    c.sink.write('a', JSON.stringify([n, s.tags]))
+  } catch (e) {
+    fail(c, s, e)
+  }
+}
+
+/** One stream's `run`: resumed with its cursor, restarted without one on a reset. */
+async function stream(deps: Dependencies, c: Conn, s: Sub, input: unknown, cursor?: string) {
+  const { limits, deliver } = deps
+  const { signal } = s.ac
+  for (;;) {
+    try {
+      const scope = createScope(s.request, s.options)
+      const frame = s.options.dev
+        ? Object.create(scope, { touched: { value: { read: new Set(), write: new Set() } } })
+        : scope
+      await enter(frame, async () => {
+        const ctx = await scope.ctx()
+        guard(s.fn, ctx)
+        const replaced = s.options.handlers?.get(s.fn.$id) as
+          | ((
+              input: unknown,
+              ctx: Context,
+              o: { signal: AbortSignal; lastEventId: unknown },
+            ) => unknown)
+          | undefined
+        const out = replaced
+          ? replaced(input, ctx, { signal, lastEventId: cursor })
+          : s.fn.def.run!({ input, ctx, signal, lastEventId: cursor })
+        for await (const y of out as AsyncIterable<unknown>) {
+          if (signal.aborted) return
+          const [id, msg] = y instanceof Tracked ? [y.id, y.value] : [null, y]
+          if (s.options.dev) await checked(s.fn, msg)
+          const raw = JSON.stringify([s.n, id, msg])
+          if (raw.length > limits.message)
+            throw new StartError(
+              'R008',
+              `\`${s.fn.$id}\` yielded ${raw.length} bytes; a message may be ${limits.message}`,
+              'send less, or an id the client fetches',
+            )
+          if (id !== null) cursor = id
+          if (!deliver(c, s, raw)) throw RESET
+        }
+      })
+      if (signal.aborted) return
+      remove(c, s)
+      c.sink.write('f', JSON.stringify([s.n]))
+      return
+    } catch (e) {
+      if (signal.aborted) return
+      if (e !== RESET) return fail(c, s, e)
+      cursor = undefined
+      c.sink.write('r', JSON.stringify([s.n]))
+    }
+  }
+}
+
+async function change(
+  deps: Dependencies,
+  c: Conn,
+  request: Request,
+  opts: ScopeOptions,
+  body: Body,
+) {
+  for (const n of body.d ?? []) {
+    const s = c.subs.get(n)
+    if (s) remove(c, s)
+  }
+  await Promise.all((body.s ?? []).map((e) => add(deps, c, e, request, opts)))
+}
+
+async function checked(fn: Fn, msg: unknown) {
+  const r = await fn.def.message?.['~standard'].validate(msg)
+  if (r?.issues)
+    throw new StartError(
+      'C002',
+      `\`${fn.$id}\` yielded a message its \`message\` schema rejects: ${r.issues.map((i) => `${i.path?.map((p) => (typeof p === 'object' ? p.key : p)).join('.') ?? ''}: ${i.message}`).join('; ')}`,
+      'fix `run`, or the schema',
+      { status: 500 },
+    )
+}
+
+export function createSubscriptions(deps: Dependencies) {
+  return {
+    fail,
+    change: change.bind(null, deps),
+  }
+}

package/src/hub/topic.ts

@@ -0,0 +1,98 @@
+import { currentScope, StartError, type StandardSchemaV1 } from '../data'
+import type { Ev, Hub } from '../hub'
+import { RESET, tracked, type Tracked } from './tracked'
+
+// ---- topics ---------------------------------------------------------------------------------------------------------
+
+/** What `topic()` returns: publish on the server, follow with `.live`. */
+export interface Topic<K, M> {
+  /** Fan a message out to every subscriber, on every instance. */
+  publish(key: K, message: M): Promise<void>
+  /**
+   * The messages of `keys`. Listens from this call, so a read that follows can't miss one (R006's gap): call it before
+   * reading a backlog. With `after`, replays what the ring still has; outside the window the stream resets.
+   */
+  subscribe(
+    keys: K | K[],
+    options?: { signal?: AbortSignal | undefined; after?: string | undefined },
+  ): AsyncGenerator<Tracked<M>, void, void>
+  readonly name: string
+  readonly message?: StandardSchemaV1<unknown, M>
+}
+
+type Out<S> = S extends StandardSchemaV1<unknown, infer O> ? O : never
+
+/** A typed server channel: mutations, jobs and webhooks publish, streams read. */
+export function makeTopic<
+  K extends StandardSchemaV1<unknown, string | number>,
+  M extends StandardSchemaV1,
+>(name: string, def: { key?: K; message: M }, hub: () => Hub): Topic<Out<K>, Out<M>> {
+  const path = (key: unknown) => `weft:t:${name}:${String(key)}`
+  return {
+    name,
+    message: def.message as StandardSchemaV1<unknown, Out<M>>,
+    async publish(key, message) {
+      const raw = JSON.stringify(message)
+      const h = hub()
+      if (raw.length > h.limits.message)
+        throw new StartError(
+          'R008',
+          `a \`${name}\` message is ${raw.length} bytes; a message may be ${h.limits.message}`,
+          'publish less, or an id subscribers fetch',
+        )
+      await h.bus.publish(path(key), raw)
+    },
+    subscribe(keys, { signal, after } = {}) {
+      const h = hub()
+      if (currentScope()?.touched?.read.size)
+        currentScope()!.options.onDiagnostic?.({
+          code: 'R006',
+          severity: 'warning',
+          message: `a stream read ${[...currentScope()!.touched!.read].join(', ')} before \`${name}.subscribe()\`: anything published in between is lost. Call \`subscribe\` first, or pass \`after\``,
+        })
+      const chans = (Array.isArray(keys) ? keys : [keys]).map((k) => h.channel(path(k)))
+      const q: Ev[] = []
+      let wake: (() => void) | undefined
+      let lost = false
+      const on = (ev: Ev | null) => {
+        if (ev) q.push(ev)
+        else lost = true
+        if (q.length > h.limits.ring) lost = true
+        wake?.()
+      }
+      for (const ch of chans) ch.listeners.add(on) // before anything is read: that's the rule
+      const stop = () => {
+        for (const ch of chans) h.unlisten(ch, on)
+      }
+      const abort = () => wake?.()
+      signal?.addEventListener('abort', abort)
+      return (async function* () {
+        try {
+          await Promise.all(chans.map((c) => c.ready))
+          if (after) {
+            const seen = new Set(q.map((e) => e.seq))
+            for (const ch of chans) {
+              const back = h.replay(ch, after)
+              if (!back) throw RESET
+              for (const ev of back) if (!seen.has(ev.seq)) q.push(ev)
+            }
+            q.sort((a, b) => a.seq - b.seq)
+          }
+          for (;;) {
+            if (signal?.aborted) return
+            if (lost) throw RESET
+            const ev = q.shift()
+            if (ev) yield tracked(h.cursorOf(ev.seq), JSON.parse(ev.raw))
+            else
+              await new Promise<void>((ok) => {
+                wake = ok
+              })
+          }
+        } finally {
+          signal?.removeEventListener('abort', abort)
+          stop()
+        }
+      })()
+    },
+  }
+}