@weft-js/start 0.1.0 → 0.1.2

package/src/derive.mjs

@@ -2,23 +2,85 @@
 // title gets its `h1`, one that sets no description gets its first real paragraph, cleaned and cut at a sentence. Pure
 // functions on a string, server-side only: `weft check` runs the same `descriptionProblem` on what a route wrote.
 
-const SKIP = new Set(['script', 'style', 'template', 'noscript', 'svg', 'math', 'nav', 'aside', 'footer', 'pre', 'figure', 'table', 'ul', 'ol', 'dl', 'details', 'button', 'select', 'textarea', 'form', 'dialog', 'iframe', 'canvas', 'object'])
-const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'source', 'track', 'wbr'])
-const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', ldquo: '“', rdquo: '”', middot: '·', copy: '©', reg: '®', trade: '™', times: '×', rarr: '→', larr: '←' }
+const SKIP = new Set([
+  'script',
+  'style',
+  'template',
+  'noscript',
+  'svg',
+  'math',
+  'nav',
+  'aside',
+  'footer',
+  'pre',
+  'figure',
+  'table',
+  'ul',
+  'ol',
+  'dl',
+  'details',
+  'button',
+  'select',
+  'textarea',
+  'form',
+  'dialog',
+  'iframe',
+  'canvas',
+  'object',
+])
+const VOID = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'source',
+  'track',
+  'wbr',
+])
+const ENTITIES = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  mdash: '—',
+  ndash: '–',
+  hellip: '…',
+  rsquo: '’',
+  lsquo: '‘',
+  ldquo: '“',
+  rdquo: '”',
+  middot: '·',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+  times: '×',
+  rarr: '→',
+  larr: '←',
+}
 
 /** `&amp;`, `&#39;`, `&#x27;` → their characters. An unknown name stays as written. */
-export const decode = text => text.replace(/&(#\d+|#x[\da-f]+|[a-z]+);/gi, (all, e) => {
-  if (e[0] !== '#') return ENTITIES[e] ?? all
-  const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))
-  return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : ''
-})
+export const decode = (text) =>
+  text.replace(/&(#\d+|#x[\da-f]+|[a-z]+);/gi, (all, e) => {
+    if (e[0] !== '#') return ENTITIES[e] ?? all
+    const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))
+    return n > 0 && n <= 0x10ffff ? String.fromCodePoint(n) : ''
+  })
 
 /** One line of plain text: whitespace collapsed, no list marker in front, no space before punctuation. */
-export const cleanText = text => text
-  .replace(/\s+/g, ' ')
-  .replace(/\s+([.,;:!?)])(?=\s|$)/g, '$1')
-  .trim()
-  .replace(/^(?:[-*•‣–—]\s+|\d{1,3}[.)]\s+)+/, '')
+export const cleanText = (text) =>
+  text
+    .replace(/\s+/g, ' ')
+    .replace(/\s+([.,;:!?)])(?=\s|$)/g, '$1')
+    .trim()
+    .replace(/^(?:[-*•‣–—]\s+|\d{1,3}[.)]\s+)+/, '')
 
 /** Not the end of a sentence, though it ends in a full stop. */
 const ABBREVIATION = /(?:^|[\s(])(?:e\.g|i\.e|etc|vs|cf|approx|no|fig|[A-Z])\.$/
@@ -43,17 +105,23 @@ export function truncate(text, max = 155) {
 /** `undefined`, or why this text isn't a description a person would read: markup, code, a list item or a fragment. */
 export function descriptionProblem(text) {
   const s = text.trim()
-  if (/^(?:[-*•+]\s|\d{1,3}[.)]\s|#{1,6}\s|>\s)/.test(s)) return 'it starts with a markdown list marker or heading'
-  if (/<\/?[a-z][^>]*>?|\/>|=>|\w\(\)|[{}]|`|\]\(|\bx = </i.test(s)) return 'it holds code or markup'
-  if ((s.match(/[<>=;$[\]{}()|\\]/g)?.length ?? 0) / Math.max(s.length, 1) > 0.05) return 'it is mostly symbols, which reads as code'
-  if (/\s[.,;:!?)](?=\s|$)/.test(s)) return 'it has a space before punctuation, the mark of inline code that was stripped out'
+  if (/^(?:[-*•+]\s|\d{1,3}[.)]\s|#{1,6}\s|>\s)/.test(s))
+    return 'it starts with a markdown list marker or heading'
+  if (/<\/?[a-z][^>]*>?|\/>|=>|\w\(\)|[{}]|`|\]\(|\bx = </i.test(s))
+    return 'it holds code or markup'
+  if ((s.match(/[<>=;$[\]{}()|\\]/g)?.length ?? 0) / Math.max(s.length, 1) > 0.05)
+    return 'it is mostly symbols, which reads as code'
+  if (/\s[.,;:!?)](?=\s|$)/.test(s))
+    return 'it has a space before punctuation, the mark of inline code that was stripped out'
   if (s.length && !/[.!?…"'”’)]$/.test(s) && s.length > 100) return 'it stops mid-sentence'
-  if (/^[a-z]/.test(s) && !/^[a-z][\w.-]*[A-Z@/:]|^[a-z]+:/.test(s)) return 'it starts in lower case, like a fragment of a longer sentence'
+  if (/^[a-z]/.test(s) && !/^[a-z][\w.-]*[A-Z@/:]|^[a-z]+:/.test(s))
+    return 'it starts in lower case, like a fragment of a longer sentence'
   return undefined
 }
 
 /** A paragraph worth quoting: prose of some length, with no code in it. */
-const prose = text => text.length >= 40 && text.includes(' ') && !descriptionProblem(truncate(text))
+const prose = (text) =>
+  text.length >= 40 && text.includes(' ') && !descriptionProblem(truncate(text))
 
 function tokens(html) {
   const out = []
@@ -67,7 +135,7 @@ function tokens(html) {
   return out
 }
 
-const hidden = attrs => /\s(?:hidden|aria-hidden=(?:"true"|'true'|true))(?:[\s/]|$)/.test(attrs)
+const hidden = (attrs) => /\s(?:hidden|aria-hidden=(?:"true"|'true'|true))(?:[\s/]|$)/.test(attrs)
 
 /**
  * The page's own words: `{ title, description }`, either missing when the page doesn't have one. Reads `<main>` when
@@ -78,22 +146,40 @@ export function pageText(html) {
   const open = /<main\b/i.exec(html)
   const end = html.toLowerCase().lastIndexOf('</main>')
   const region = open ? html.slice(open.index, end > open.index ? end : undefined) : html
-  let title, heading, description, skip, grab, buffer = ''
-  const done = t => {
+  let title,
+    heading,
+    description,
+    skip,
+    grab,
+    buffer = ''
+  const done = (t) => {
     const text = cleanText(decode(buffer))
     grab = undefined
-    if (t === 'p') { if (prose(text)) description ??= truncate(text) }
-    else if (t !== 'h1') heading ??= text || undefined
-    else if (text && !title) { title = text; description = undefined } // the description is what follows the title
+    if (t === 'p') {
+      if (prose(text)) description ??= truncate(text)
+    } else if (t !== 'h1') heading ??= text || undefined
+    else if (text && !title) {
+      title = text
+      description = undefined
+    } // the description is what follows the title
   }
   for (const t of tokens(region)) {
     if (skip) {
-      if (t.tag === skip.tag && !VOID.has(t.tag) && !/\/\s*$/.test(t.attrs ?? '')) skip.depth += t.close ? -1 : 1
+      if (t.tag === skip.tag && !VOID.has(t.tag) && !/\/\s*$/.test(t.attrs ?? ''))
+        skip.depth += t.close ? -1 : 1
       if (!skip.depth) skip = undefined
       continue
     }
-    if (t.text !== undefined) { if (grab) buffer += t.text; continue }
-    if (!t.close && (SKIP.has(t.tag) || hidden(t.attrs)) && !VOID.has(t.tag) && !/\/\s*$/.test(t.attrs)) {
+    if (t.text !== undefined) {
+      if (grab) buffer += t.text
+      continue
+    }
+    if (
+      !t.close &&
+      (SKIP.has(t.tag) || hidden(t.attrs)) &&
+      !VOID.has(t.tag) &&
+      !/\/\s*$/.test(t.attrs)
+    ) {
       skip = { tag: t.tag, depth: 1 }
       continue
     }
@@ -102,7 +188,10 @@ export function pageText(html) {
       else if (t.tag === 'br') buffer += ' '
       continue
     }
-    if (!t.close && /^(?:h1|h2|h3|p)$/.test(t.tag)) { grab = t.tag; buffer = '' }
+    if (!t.close && /^(?:h1|h2|h3|p)$/.test(t.tag)) {
+      grab = t.tag
+      buffer = ''
+    }
     if (title && description) break
   }
   return { title: title ?? heading, description }
@@ -114,25 +203,33 @@ export function pageText(html) {
  */
 export function deployUrl(site, env = {}) {
   if (site?.url) return site.url
-  const https = host => host && `https://${host}`
-  return env.WEFT_SITE_URL
-    || https(env.VERCEL_PROJECT_PRODUCTION_URL) || https(env.VERCEL_URL)
-    || env.URL // Netlify
-    || env.CF_PAGES_URL || env.RENDER_EXTERNAL_URL
-    || https(env.RAILWAY_PUBLIC_DOMAIN)
-    || (env.FLY_APP_NAME && `https://${env.FLY_APP_NAME}.fly.dev`)
-    || undefined
+  const https = (host) => host && `https://${host}`
+  return (
+    env.WEFT_SITE_URL ||
+    https(env.VERCEL_PROJECT_PRODUCTION_URL) ||
+    https(env.VERCEL_URL) ||
+    env.URL || // Netlify
+    env.CF_PAGES_URL ||
+    env.RENDER_EXTERNAL_URL ||
+    https(env.RAILWAY_PUBLIC_DOMAIN) ||
+    (env.FLY_APP_NAME && `https://${env.FLY_APP_NAME}.fly.dev`) ||
+    undefined
+  )
 }
 
 /** The built-in card's title size: bigger type for a shorter title. */
-export const cardTitleSize = title => (title.length <= 24 ? 92 : title.length <= 44 ? 76 : title.length <= 70 ? 62 : 52)
+export const cardTitleSize = (title) =>
+  title.length <= 24 ? 92 : title.length <= 44 ? 76 : title.length <= 70 ? 62 : 52
 
 /** `paths` in pages that each fit in a response header, with room for the link to the next page. */
 export function pathPages(paths, max = 6000) {
   const pages = [[]]
   let size = 0
   for (const p of paths) {
-    if (size + p.length + 1 > max) { pages.push([]); size = 0 }
+    if (size + p.length + 1 > max) {
+      pages.push([])
+      size = 0
+    }
     pages.at(-1).push(p)
     size += p.length + 1
   }

package/src/dev-runtime.mjs

@@ -5,7 +5,7 @@
 
 const alternate = Boolean(process.versions.bun || process.versions.deno)
 
-export const devRunner = sockets => (alternate && sockets ? 'self' : undefined)
+export const devRunner = (sockets) => (alternate && sockets ? 'self' : undefined)
 
 const GUARD = /if \("Deno" in globalThis \|\| "Bun" in globalThis\) throw new Error\([^)]*\);?/
 
@@ -23,19 +23,23 @@ export const devSockets = () => ({
   },
   transform: {
     filter: { id: /crossws/, code: 'incompatible environment' },
-    handler: code => code.replace(GUARD, ''),
+    handler: (code) => code.replace(GUARD, ''),
   },
 })
 
 // Nitro can name an environment to the runner before Vite has made it. Across a process that takes long enough, but
 // `self` answers at once: the first request goes to nothing and the environment hangs for good. So each one is held
 // until it exists, and `init` names it again. (The worker keeps these on globalThis, and `self` is this process.)
-const HELD = { hasEvaluated: () => false, reload: async () => {}, fetch: () => Promise.resolve(new Response('starting', { status: 503 })) }
+const HELD = {
+  hasEvaluated: () => false,
+  reload: async () => {},
+  fetch: () => Promise.resolve(new Response('starting', { status: 503 })),
+}
 
 function hold(name) {
   const environments = (globalThis.__nitro_vite_envs__ ??= {})
   environments[name] = HELD
-  return environment => {
+  return (environment) => {
     environments[name] = undefined
     return environment
   }

package/src/exec/errors.ts

@@ -0,0 +1,57 @@
+import { FnError, StartError, type Context, type Fn } from '../data'
+import { unavailable } from '../db/core'
+
+/** `auth: 'user'`: A003 when `ctx` has no `user` at all, A002 when no one is signed in. */
+export function guard(fn: Fn, ctx: Context) {
+  if (fn.def.auth !== 'user') return
+  if (!('user' in ctx))
+    throw new StartError(
+      'A003',
+      `\`${fn.$id}\` has \`auth: 'user'\`, but \`ctx\` has no \`user\``,
+      'spread `session(auth, request)` into what `src/context.server.ts` returns',
+      { status: 500 },
+    )
+  if (!(ctx as { user?: unknown }).user)
+    throw new StartError(
+      'A002',
+      `\`${fn.$id}\` needs a signed-in user`,
+      'sign in first, or guard the route with `redirect()` in its `load`',
+      { status: 401 },
+    )
+}
+
+const DOWN =
+  /^(ECONNREFUSED|ECONNRESET|ENOTFOUND|EHOSTUNREACH|ETIMEDOUT|CONNECT_TIMEOUT|CONNECTION_(CLOSED|ENDED|DESTROYED)|PROTOCOL_CONNECTION_LOST|P100[12])$/
+
+interface Failure {
+  cause?: Failure | null
+  answer?: { message?: string; code?: string; status: number }
+  code?: string | number
+  message?: string
+}
+
+/** A dropped connection is Q016; a missing table is a migration that wasn't generated or applied (Q014): the driver's error, with the fix. */
+export function dbError(e: unknown): unknown {
+  const failure = e as Failure | null | undefined
+  const cause = failure?.cause ?? failure
+  if (failure?.answer) return new FnError(failure.answer, failure.answer.status)
+  if (cause instanceof StartError) return cause // Drizzle wraps what a driver throws, the gate's Q016 included
+  if (!(e instanceof StartError) && DOWN.test(String(cause?.code ?? failure?.code ?? '')))
+    return unavailable(e)
+  const m = cause?.message ?? ''
+  if (
+    e instanceof StartError ||
+    !(
+      /no such (table|column)|has no column named/.test(m) ||
+      cause?.code === '42P01' ||
+      cause?.code === '42703'
+    )
+  )
+    return e
+  return new StartError(
+    'Q014',
+    `the database doesn't match the schema: ${m}`,
+    'run `weft db generate`, then reload (new migrations apply on the next request)',
+    { status: 500 },
+  )
+}

package/src/exec/landing.ts

@@ -0,0 +1,66 @@
+import { FnError, isRedirect, StartError } from '../data'
+import type { Scope, ScopeEntry } from './scope'
+
+/** How long a landed read waits for the others in flight, in ms: long enough for a pool's worth of replies. */
+const GATHER = 4
+
+interface Landing {
+  flying: number
+  held: (() => void)[]
+  timer?: ReturnType<typeof setTimeout> | undefined
+}
+const landings = new WeakMap<object, Landing>()
+
+/**
+ * A read as a render sees it. Each landing costs a pass over the whole page, so reads land together: all of them once
+ * none is in flight, or `GATHER` after the first, so a slow query never holds a fast one for longer than that.
+ */
+export function landed(scope: Scope, e: ScopeEntry): Promise<unknown> {
+  if (e.read) return e.read
+  let l = landings.get(scope.entries)
+  if (!l) landings.set(scope.entries, (l = { flying: 0, held: [] }))
+  const at = l
+  at.flying++
+  const release = () => {
+    clearTimeout(at.timer)
+    at.timer = undefined
+    for (const go of at.held.splice(0)) go()
+  }
+  e.read = new Promise((ok, no) => {
+    const land = () => {
+      at.held.push(() => (e.e !== undefined ? no(shown(e.e, scope)) : ok(e.v)))
+      if (!--at.flying) release()
+      else at.timer ??= setTimeout(release, GATHER)
+    }
+    e.p.then(land, land)
+  })
+  e.read.catch(() => {}) // a failure surfaces where the value is read
+  return e.read
+}
+
+const FAILED = 'Server function failed.'
+
+/** A failure as the page may show it. In production a fault's text stays in the diagnostics: a driver's error names tables. */
+export function shown(e: unknown, scope: Scope): unknown {
+  const { dev, onDiagnostic } = scope.options
+  const fault = !(
+    e instanceof FnError ||
+    isRedirect(e) ||
+    (e instanceof StartError && Number(e.extra.status ?? 500) < 500)
+  )
+  const { message, code } = (e ?? {}) as { message?: string; code?: string }
+  if (dev || !fault) {
+    if (message !== undefined) scope.said.add(message)
+    return e
+  }
+  onDiagnostic?.({
+    code: code ?? 'E_FN',
+    severity: 'error',
+    message: `a render read a failed query: ${e instanceof Error ? (e.stack ?? e.message) : String(e)}`,
+  })
+  return new Error(FAILED)
+}
+
+/** The message for a value that's going in a page: its own when `shown` passed it, else the plain one. */
+export const said = (message: string, scope: Scope) =>
+  scope.options.dev || scope.said.has(message) ? message : FAILED

package/src/exec/scope.ts

@@ -0,0 +1,174 @@
+import type { MediaAsset } from '@weft-js/core/media'
+import type { ServerExtension } from '../extension'
+import { StartError, type Context } from '../data'
+import { dbError } from './errors'
+
+export interface ScopeEntry {
+  id: string
+  input: unknown
+  p: Promise<ScopeEntry>
+  /** A render's read of it (`landed`). */
+  read?: Promise<unknown>
+  done?: boolean
+  v?: unknown
+  e?: unknown
+  tags: string[]
+}
+
+export interface Scope {
+  request: Request
+  entries: Map<string, ScopeEntry>
+  /** Tags a mutation or `invalidate()` dropped during this request. */
+  invalidated: Set<string>
+  /** Response headers the functions set (cookies), merged into the response. */
+  headers: Headers
+  /** The page's first byte went out: a redirect can't change the status any more (Q007). */
+  started?: boolean
+  /** The tags of the queries a route level's `load` read (a frame per loader; research 27 §4). */
+  tags?: Set<string>
+  /** Dev: the tables this function's statements read and wrote (a frame per `run`; research 28 §2). */
+  touched?: Touched
+  /** A no-JS form POST that failed: `<Form>` renders it into the page (research 29 §5). */
+  form?: FormFailure
+  /** Failure messages meant for the visitor, the only ones a production page may carry (`shown`). */
+  said: Set<string>
+  /** The render read a live query or a stream: the page carries the realtime cursor (research 30 §1). */
+  live?: boolean
+  ctx(): Promise<Context>
+  options: ScopeOptions
+}
+
+export interface Touched {
+  read: Set<string>
+  write: Set<string>
+}
+
+export interface FormFailure {
+  id: string
+  key?: string
+  values: Record<string, unknown>
+  errors: Record<string, string>
+  message?: string | undefined
+  status: number
+}
+
+/** The `media.server@1` provider (`@weft-js/plugin-media/server`, research 29 §6). */
+export interface MediaServer {
+  ingest(bytes: Uint8Array, options: { name?: string }): Promise<MediaAsset>
+  serve(want: { hash: string; width: number; format: string; accept: string }): Promise<{
+    bytes: Uint8Array
+    type: string
+    width: number
+    format: string
+    negotiated: boolean
+    temporary?: boolean
+  } | null>
+}
+
+export interface ScopeOptions {
+  /** The app's context (`src/context.server.ts`). */
+  context?: ((args: { request: Request }) => object | Promise<object>) | undefined
+  store?: Store | undefined
+  /** Tests (@weft-js/core/test `net.handle`): a replacement `run` by function id. */
+  handlers?: Map<string, (input: unknown, ctx: Context) => unknown>
+  onDiagnostic?: ((d: { code: string; severity: string; message: string }) => void) | undefined
+  dev?: boolean | undefined
+  media?: (() => Promise<MediaServer> | undefined) | undefined
+  /** What plugins add through `server.extension` (extension.ts). */
+  extensions?: ServerExtension[] | undefined
+}
+
+export function createScope(request: Request, options: ScopeOptions = {}): Scope {
+  const headers = new Headers()
+  let ctx: Promise<Context> | undefined
+  return {
+    request,
+    entries: new Map(),
+    invalidated: new Set(),
+    headers,
+    options,
+    said: new Set(),
+    // oxlint-disable typescript/no-unnecessary-type-assertion -- needed where a plugin such as pay adds required fields to Context
+    ctx: () =>
+      (ctx ??= Promise.resolve()
+        .then(() => options.context?.({ request }) ?? {})
+        .then(
+          (app) =>
+            extended(
+              {
+                ...app,
+                request,
+                response: { headers },
+                media: mediaApi(options),
+              } /* oxlint-enable typescript/no-unnecessary-type-assertion */ as Context,
+              options,
+            ),
+          (e) => {
+            throw dbError(e)
+          },
+        )),
+  }
+}
+
+/** Each extension's part of `ctx`, once the app's is there: an extension reads `ctx.user` to say what it adds. */
+function extended(ctx: Context, options: ScopeOptions): Context {
+  for (const e of options.extensions ?? []) Object.assign(ctx, e.context?.(ctx))
+  return ctx
+}
+
+/** `ctx.media`. A refusal is the user's answer, with its own status; `<Form>` shows it. */
+const mediaApi = (options: ScopeOptions): Context['media'] => ({
+  async ingest(file, { name } = {}) {
+    const server = await options.media?.()
+    if (!server)
+      throw new StartError(
+        'M017',
+        '`ctx.media` needs a `media.server` provider',
+        'add `media()` from `@weft-js/plugin-media` to `plugins` in weft.config.ts',
+        { status: 500 },
+      )
+    const bytes = file instanceof Uint8Array ? file : new Uint8Array(await file.arrayBuffer())
+    try {
+      return await server.ingest(bytes, { name: name ?? (file as File).name })
+    } catch (e) {
+      const { code, message } = e as Error & { code?: string }
+      throw code ? new StartError(code, message, undefined, { status: 422 }) : e
+    }
+  },
+})
+
+/** A child scope for one loader: the same entries, its own `tags` collector. */
+export const frame = (scope: Scope): Scope =>
+  Object.create(scope, { tags: { value: new Set<string>() } })
+
+// ---- the shared tagged cache --------------------------------------------------------------------------------------
+
+/** Where `cache: { life }` values live. Memory by default; Nitro storage (fs, KV, Redis) plugs in here. */
+export interface Store {
+  get(key: string): Stored | undefined | Promise<Stored | undefined>
+  set(key: string, value: Stored): void | Promise<void>
+  /** The current version of each tag (0 for one never bumped). */
+  versions(tags: string[]): number[] | Promise<number[]>
+  bump(tags: string[]): void | Promise<void>
+}
+export interface Stored {
+  v: unknown
+  tags: string[]
+  versions: number[]
+  expires: number
+}
+
+export function memoryStore(): Store {
+  const values = new Map<string, Stored>()
+  const tags = new Map<string, number>()
+  return {
+    get: (k) => values.get(k),
+    set: (k, v) => void values.set(k, v),
+    versions: (t) => t.map((x) => tags.get(x) ?? 0),
+    bump: (t) => {
+      for (const x of t) tags.set(x, (tags.get(x) ?? 0) + 1)
+    },
+  }
+}
+
+export const defaultStore = memoryStore()

package/src/exec/touch.ts

@@ -0,0 +1,80 @@
+import type { Fn } from '../data'
+import type { Scope, ScopeOptions, Touched } from './scope'
+
+export const tracker = (scope: Scope): Touched | undefined =>
+  scope.options.dev ? { read: new Set(), write: new Set() } : undefined
+
+/** R105 (dev, once per function): a cached Rust query with tags that named no table, so Q011 has nothing to check it by. */
+export function untouched(fn: Fn, read: Set<string>, tags: readonly string[], scope: Scope) {
+  if (!fn.def.impl || !fn.def.cache || read.size || !tags.length || warned.has(`${fn.$id}:R105`))
+    return
+  warned.add(`${fn.$id}:R105`)
+  scope.options.onDiagnostic?.({
+    code: 'R105',
+    severity: 'warning',
+    message: `\`${fn.$id}\` is cached under ${tags.map((t) => `\`${t}\``).join(', ')} and reported no table: nothing can tell whether those tags cover what it reads. Call \`ctx.touch("table")\` in the Rust, or drop \`tags\` if it reads none`,
+  })
+}
+
+/** Q011 (dev, once per function and table): a table the function touched that no tag names (PLAN §4). */
+export function missedTags(
+  fn: Fn,
+  verb: 'read' | 'write',
+  tables: Set<string>,
+  tags: readonly string[],
+  scope: Scope,
+) {
+  for (const t of tables) {
+    const key = `${fn.$id}:${t}`
+    if (warned.has(key) || tags.some((x) => x === t || x.startsWith(`${t}:`))) continue
+    warned.add(key)
+    const list = fn.kind === 'query' ? '`tags`' : '`invalidates`'
+    scope.options.onDiagnostic?.({
+      code: 'Q011',
+      severity: 'warning',
+      message: `\`${fn.$id}\` ${verb === 'read' ? 'reads' : 'writes'} table \`${t}\`, but its ${list} don't name it: ${fn.kind === 'query' ? "a mutation of that table won't refresh it" : 'queries of that table stay stale'}. Add \`'${t}'\` to ${list}`,
+    })
+  }
+}
+const warned = new Set<string>()
+
+/** Dev: the tables each query last read, and the tags of the queries read with `.live()` (the hub fills it). */
+export const reads = new Map<string, Set<string>>()
+export const liveQueries = new Map<string, string[]>()
+
+/** R003 (dev, once per pair): this mutation wrote what a live query reads, and pokes none of its tags. */
+export function missedPokes(fn: Fn, write: Set<string>, tags: string[], scope: Scope) {
+  for (const [id, own] of liveQueries) {
+    const table = [...(reads.get(id) ?? [])].find((t) => write.has(t))
+    const key = `${fn.$id}>${id}`
+    if (!table || warned.has(key) || own.some((t) => tags.includes(t))) continue
+    warned.add(key)
+    scope.options.onDiagnostic?.({
+      code: 'R003',
+      severity: 'warning',
+      message: `\`${fn.$id}\` writes table \`${table}\`, which live query \`${id}\` reads, but their tags don't intersect (${JSON.stringify(tags)} and ${JSON.stringify(own)}): open pages won't update. Add one of the query's tags to \`invalidates\``,
+    })
+  }
+}
+
+/** R012 (dev, once per query and table): a live query whose tags won't hear what `changes` reports, or a table it doesn't report. */
+export function missedFeed(
+  fn: Fn,
+  tags: string[],
+  tables: string[],
+  report: ScopeOptions['onDiagnostic'],
+) {
+  for (const t of reads.get(fn.$id) ?? []) {
+    const key = `${fn.$id}~${t}`
+    const named = tags.some((x) => x === t || x.startsWith(`${t}:`))
+    if (warned.has(key) || (named && tables.includes(t))) continue
+    warned.add(key)
+    report?.({
+      code: 'R012',
+      severity: 'warning',
+      message: tables.includes(t)
+        ? `live query \`${fn.$id}\` reads table \`${t}\`, but no tag names it: writes from outside the app won't refresh it. Add \`'${t}'\` to its \`tags\``
+        : `live query \`${fn.$id}\` reads table \`${t}\`, which \`changes\` doesn't list: only mutations refresh it, not writes from outside the app. Add the table to \`dbChanges\``,
+    })
+  }
+}