@christianirack/brainllm-runtime 0.8.1 → 0.8.4

package/brain-analytics.js

@@ -70,13 +70,17 @@ export function start(config = {}, env = globalThis) {
         )
 
   // ── identity: anonymous first-party visitor (localStorage) and a session that ends after 30 idle minutes
+  // A session belongs to one visitor (the server refuses it from another), so without storage the visitor id lives in
+  // memory for the page, and a stored session whose visitor is gone or different starts over.
   let session = null
+  let visitor = null
   const ids = () => {
     const t = Date.now()
     let vid = get(VISITOR)
-    if (typeof vid !== 'string') put(VISITOR, (vid = uuid()))
+    if (typeof vid === 'string') visitor = vid
+    else put(VISITOR, (vid = visitor = visitor || uuid()))
     if (!session) session = get(SESSION)
-    if (!session || typeof session.id !== 'string' || t - session.last > IDLE_MS) session = { id: uuid(), last: t, pv: 0, ctx: 0 }
+    if (!session || typeof session.id !== 'string' || session.vid !== vid || t - session.last > IDLE_MS) session = { id: uuid(), vid, last: t, pv: 0, ctx: 0 }
     session.last = t
     put(SESSION, session)
     return vid

package/brain-form.js

@@ -35,7 +35,10 @@ const go = u => {
 // submitted does not ask (#299): the user chose to save, and a submit() that navigates once the server accepted the
 // data (`navigate('/products/' + p.id)`) leaves before submit() returns and marks the values saved.
 const DIRTY = (globalThis.__brainDirty ||= new Set())
-if (globalThis.addEventListener && !globalThis.__brainDirtyHook) {
+// registered with the first edit, not at load: a `beforeunload` listener can keep a page out of the back/forward cache,
+// and most pages that load this file are never edited
+const guardUnload = () => {
+  if (!globalThis.addEventListener || globalThis.__brainDirtyHook) return
   globalThis.__brainDirtyHook = 1
   globalThis.addEventListener('beforeunload', e => {
     for (const f of DIRTY) if (f.dirty && !f.busy) return void (e.preventDefault(), (e.returnValue = ''))
@@ -109,7 +112,7 @@ function remoteCheck(o, x, checking) {
 }
 function createForm(schema, o, readRule, validateRule, remote) {
   const id = 'f' + ++seq, owner = I.owner() // aria effects are created later (in handlers) but live with the component
-  const busy = sig(false), error = sig(''), shown = sig(0) // shown: bumped when touched set changes
+  const busy = sig(false), error = sig(''), status = sig(0), shown = sig(0) // shown: bumped when touched set changes
   const checking = sig(0), saved = sig('') // async checks running · JSON of the last saved values
   const F = [] // flat fields: { path, r, s (value sig), e (error sig), el, touched }
   const byPath = {}
@@ -227,6 +230,9 @@ function createForm(schema, o, readRule, validateRule, remote) {
     get error() {
       return error.v
     },
+    get status() {
+      return status.v
+    },
     get dirty() {
       return now() !== saved.v
     },
@@ -274,6 +280,7 @@ function createForm(schema, o, readRule, validateRule, remote) {
           if (!first && x.e.v) first = x
         }
         error.v = ''
+        status.v = 0
         shown.v++
       })
       if (o.validate && !first) {
@@ -302,6 +309,7 @@ function createForm(schema, o, readRule, validateRule, remote) {
         }
         return r
       } catch (x) {
+        status.v = x?.status || 0
         if (x?.errors) mark(x.errors)
         // a server failure reads the same as without JS: 4xx and the author's own errors keep their message; 5xx and a
         // TypeError (the network dropped, or a bug) get the generic one; the runtime's own English sentence (`plain`) gives
@@ -315,6 +323,9 @@ function createForm(schema, o, readRule, validateRule, remote) {
     },
   }
   DIRTY.add(f)
+  // outside the fx: the listener outlives the form on purpose, one per page, and is not this effect's to clean up
+  const watch = () => fx(() => void (f.dirty && queueMicrotask(guardUnload)))
+  owner ? I.root(watch, owner) : watch()
   if (owner) I.root(() => fx(() => () => DIRTY.delete(f)), owner)
   return f
 }

package/brain-inspect.js

@@ -264,6 +264,9 @@ const fin = G.FinalizationRegistry ? new FinalizationRegistry(w => (w.dead = 1))
 // Where a pending request went, without origin or query: evidence for a fix, never a value.
 const pendingUrls = () => [...inflight.values()].slice(0, 3).map(r => `${r.m} ${r.url.replace(/^[a-z]+:\/\/[^/]+/i, '').split(/[?#]/)[0]}`)
 const SETTLE_MS = 60000
+// While a suite holds the verdict, an instance only ages from its release: a promise or a script load that begins after
+// the unmount is invisible to the network watch and keeps the instance alive for a bounded time.
+let held_verdict = false
 function watch(d) {
   if (!fin) return
   // its first DOM node: an app that keeps a detached node (a module array, a cache) is the leak to catch. The browser
@@ -279,11 +282,13 @@ function checkLeaks() {
   for (let j = watched.length - 1; j >= 0; j--) {
     const w = watched[j]
     if (w.dead) watched.splice(j, 1)
+    else if (held_verdict) w.at = gcs
     // A request from before the unmount may be what holds it: judge after it settles (bounded, for a long poll).
     else if (w.net.some(id => inflight.has(id)) && now() - w.since < SETTLE_MS) w.at = gcs
     else if (gcs - w.at >= 2) {
       watched.splice(j, 1)
-      const waited = w.urls.length ? `${w.urls.length > 2 ? 'several requests' : w.urls.join(', ')} ${w.urls.length > 1 ? 'were' : 'was'} in flight when it unmounted; ` : ''
+      const finished = !w.net.some(id => inflight.has(id))
+      const waited = w.urls.length ? `${w.urls.length > 2 ? 'several requests' : w.urls.join(', ')} ${w.urls.length > 1 ? 'were' : 'was'} in flight when it unmounted${finished ? ' and finished, so look past it' : ''}; ` : ''
       leak({ code: 'B0601', h: w.h, name: w.name, file: w.file, msg: `unmounted ${w.name} instance still alive after 2 GC cycles`, fix: w.fx.length ? 'add cleanup to the listed fx: they retain the instance' : `${waited}look for what still references its nodes or signals: an in-flight promise (a pending server call, \`.then\` or \`await\`) or timer that writes to the component, global listeners, caches, module closures`, fx: w.fx })
     }
   }
@@ -708,7 +713,7 @@ export function inspect(o) {
     G.document.addEventListener.call(G.document, 'keydown', e => e.altKey && e.shiftKey && e.code === 'KeyB' && toggle())
   return api
 }
-const api = { tick, drain, comps, onLoaf, onEvents, leaks: () => leaks.slice(), timers: () => [...timers.values()], toggle: () => toggle(), inflight: () => [...inflight.values()].map(r => `${r.m} ${r.url}`), abortInflight: () => { for (const r of inflight.values()) if (r.stop) r.stop() } }
+const api = { tick, drain, comps, onLoaf, onEvents, leaks: () => leaks.slice(), timers: () => [...timers.values()], toggle: () => toggle(), inflight: () => [...inflight.values()].map(r => `${r.m} ${r.url}`), abortInflight: () => { for (const r of inflight.values()) if (r.stop) r.stop() }, holdVerdict: on => (held_verdict = !!on), alive: () => watched.filter(w => !w.dead).length }
 
 // ---------- mini panel (Alt+Shift+B): heap, leaks and link to the full debugger (§9.1) ----------
 let panel = null

package/brain-lazy.js

@@ -75,6 +75,8 @@ export function lazy(el, imp, mode, props = {}) {
     stop = () => {
       for (const t of ACT) el.removeEventListener(t, f, t === 'click')
     }
+  } else if (G.document && document.visibilityState === 'hidden') {
+    go() // a hidden tab runs no observer: without this the content is missing until the tab is shown
   } else if (G.IntersectionObserver) {
     const io = new IntersectionObserver(es => es.some(e => e.isIntersecting) && go(), { rootMargin: '200px' })
     io.observe(el)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christianirack/brainllm-runtime",
-  "version": "0.8.1",
+  "version": "0.8.4",
   "description": "The BRAINLLM runtime for the Rust-built web compiler for LLMs: dependency-free ES modules (signals, DOM, router, data, forms, channels). The brain binary embeds this same version.",
   "type": "module",
   "exports": {

package/server/server.mjs

@@ -81,6 +81,7 @@ export class HttpError extends Error {
     Object.assign(this, extra)
   }
 }
+const bridgeBusy = message => new HttpError(503, message, { code: 'BRIDGE_BUSY', retryAfter: 1, fix: 'The server is at its limit of concurrent backend requests; retry after the Retry-After delay' })
 // Plain deliberate 4xx signals are portable from server-only application modules; exception messages stay private.
 function intendedStatus(error) {
   if (!error || typeof error !== 'object') return null
@@ -179,6 +180,21 @@ export function acceptedEncodings(header = '', order = ['br', 'zstd', 'gzip']) {
 // already has an encoding, a `no-transform` cache policy or a status without content is sent as is.
 const COMPRESSIBLE = /^(?:text\/|image\/svg\+xml|application\/(?:json|javascript|xml|[\w.-]+\+(?:json|xml)))/i
 const DYNAMIC = ['zstd', 'br', 'gzip']
+// Each Vary token once: a relayed backend header and the additions here must not repeat one (tokens are case-insensitive).
+const varyOnce = v => {
+  const seen = new Set()
+  return String(v).split(',').map(t => t.trim()).filter(t => t && !seen.has(t.toLowerCase()) && seen.add(t.toLowerCase())).join(', ')
+}
+// Parameters that do not make a different page: the list of `<meta seo query>` (brain-check seo.rs, B0503).
+const TRACKING = /^(?:utm_.*|gclid|fbclid|msclkid)$/
+const cacheSearch = url => {
+  const kept = new URLSearchParams([...url.searchParams].filter(([key]) => !TRACKING.test(key)))
+  kept.sort()
+  return kept.size ? '?' + kept : ''
+}
+// Messages this file writes itself, safe to log as the cause; anything else in an error message may hold private data.
+const OWN_CAUSES = new Set(['Backend request unavailable', 'Backend request timed out', 'Backend response exceeds its byte budget', 'Backend request capacity is unavailable', 'Backend stream capacity is unavailable', 'Native file request failed', 'Native file response is invalid', 'Native authentication is temporarily unavailable', 'Native resource response must be JSON', 'Native resource response is invalid', 'Native resource request failed', 'Invalid final response status', 'Invalid configured redirect location', 'timeout'])
+const CODE_SHAPE = /^[A-Z][A-Z0-9_]{0,63}$/
 const varyEncoding = v => (/accept-encoding/i.test(v || '') ? v : [v, 'Accept-Encoding'].filter(Boolean).join(', '))
 function bodyEncoding(req, status, headers) {
   if (status < 200 || status === 204 || status === 206 || status === 304 || headers['content-encoding'] || !COMPRESSIBLE.test(headers['content-type'] || '') || /no-transform/i.test(headers['cache-control'] || '')) return null
@@ -250,7 +266,7 @@ function bucketClient(target, key, bucket) {
     async remove(id) { await send('DELETE', idPath(id), undefined, 10000); return null },
   })
 }
-export function nativeAuthBridge(raw, refused, serviceKey, report) {
+export function nativeAuthBridge(raw, refused, serviceKey, report, ownSession) {
   // How to fix the configuration is for the operator: a visitor of a production app reads a generic message.
   const configuration = (status, detail, rid, shown = 'This service is not available right now') => {
     if (process.env.NODE_ENV !== 'production') return new HttpError(status, detail)
@@ -412,7 +428,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
   const nativeCookies = values => (values || []).filter(value => /^(?:__Host-brain(?:-access|-refresh|-google)?)=/.test(value) && value.length <= 8192).slice(0,8)
   // /_brain/files: both directions stream with backpressure. The bucket enforces its own maxBytes and access checks.
   function fileStream(req, res, url, rid) {
-    if (stopped || streams >= 32) throw new HttpError(503, 'Backend stream capacity is unavailable')
+    if (stopped || streams >= 32) throw bridgeBusy('Backend stream capacity is unavailable')
     if (!['GET','HEAD','POST','DELETE'].includes(req.method)) throw new HttpError(405, 'Method not allowed')
     const ceiling = 2 * 1024 * 1024 * 1024 + 1024 * 1024
     if (Number(req.headers['content-length'] || 0) > ceiling) throw new HttpError(413, 'Request body is too large')
@@ -430,7 +446,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
       }
       const closed = () => finish()
       const count = chunk => { sent += chunk.length; if (sent > ceiling) finish(new HttpError(413, 'Request body is too large')) }
-      const unavailable = () => new HttpError(503, 'Backend request unavailable')
+      const unavailable = transport => new HttpError(503, 'Backend request unavailable', { transport })
       try {
         outgoing = httpRequest(new URL(url.pathname + url.search, target), { agent:streamAgent, method:req.method, headers:requestHeaders(req, rid, FILE_HEADERS) }, backend => {
           const safe = { 'cache-control':'no-store' }
@@ -440,9 +456,11 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
           }
           const cookies = nativeCookies(backend.headers['set-cookie'])
           if (cookies.length) safe['set-cookie'] = cookies
+          if (safe.vary) safe.vary = varyOnce(safe.vary)
+          if (backend.statusCode >= 500) res.$brainCause = 'answered by the native backend'
           res.writeHead(backend.statusCode || 502, safe)
-          backend.once('error', () => finish(unavailable()))
-          backend.once('aborted', () => finish(unavailable()))
+          backend.once('error', e => finish(unavailable(e.code)))
+          backend.once('aborted', () => finish(unavailable('BACKEND_ABORTED')))
           backend.once('end', () => { res.end(() => finish()) })
           backend.pipe(res)
         })
@@ -451,7 +469,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
         outgoing.setTimeout(60000, () => finish(new HttpError(504, 'Backend request timed out')))
         // The backend's own upload deadline is 300 s; nothing else needs a total limit after the headers.
         if (req.method === 'POST') deadline = setTimeout(() => finish(new HttpError(504, 'Backend request timed out')), 310000)
-        outgoing.once('error', () => finish(unavailable()))
+        outgoing.once('error', e => finish(unavailable(e.code)))
         res.once('close', closed)
         req.on('data', count)
         req.pipe(outgoing)
@@ -459,14 +477,14 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
     })
   }
   function proxy(req, res, url, rid, reply, responseLimit = 20 * 1024 * 1024, declared) {
-    if (stopped || active >= 8) throw new HttpError(503, 'Backend request capacity is unavailable')
+    if (stopped || active >= 8) throw bridgeBusy('Backend request capacity is unavailable')
     if (!['GET','HEAD','POST','PUT','PATCH','DELETE','OPTIONS'].includes(req.method)) throw new HttpError(405, 'Method not allowed')
     const post = req.method === 'POST'
     const limit = url.pathname === '/_brain/uploads' && post ? 5 * 1024 * 1024 + 65536 : declared || post && /^\/api\/[^/]+\/batch$/.test(url.pathname) ? 1024 * 1024 : 65536
     if (Number(req.headers['content-length'] || 0) > limit) throw new HttpError(413, 'Request body is too large')
     active++
     return new Promise((resolve, reject) => {
-      let outgoing, timer, done = false, bytes = 0, requestBytes = 0, failure
+      let outgoing, timer, done = false, bytes = 0, requestBytes = 0, failure, transport
       const chunks = []
       const headers = requestHeaders(req, rid, declared?.headers)
       const finish = (error, backend) => {
@@ -474,7 +492,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
         done = true; clearTimeout(timer); active--; proxyBytes -= bytes; owned.delete(outgoing)
         req.removeListener('aborted',cancel); req.removeListener('data',data); req.removeListener('end',end)
         res.removeListener('close',cancel)
-        if (error) { if (!res.destroyed) reject(failure || new HttpError(503,'Backend request unavailable')); else resolve(); return }
+        if (error) { if (!res.destroyed) reject(failure || new HttpError(503,'Backend request unavailable',{transport})); else resolve(); return }
         const safe = { 'cache-control':'no-store' }
         for (const key of RESPONSE_HEADERS) {
           const value = backend.headers[key]
@@ -486,6 +504,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
         }
         const cookies = nativeCookies(backend.headers['set-cookie'])
         if (cookies.length) safe['set-cookie'] = cookies
+        if (backend.statusCode >= 500 && !res.$capture) res.$brainCause = 'answered by the native backend'
         try { reply(res,backend.statusCode || 502,req.method === 'HEAD' ? '' : Buffer.concat(chunks,bytes),safe); resolve() } catch (e) { reject(e) }
       }
       const cancel = () => { outgoing?.destroy(); finish(true) }
@@ -502,11 +521,11 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
             if (bytes > responseLimit || proxyBytes > 64 * 1024 * 1024) { failure = new HttpError(502,'Backend response exceeds its byte budget'); outgoing.destroy(); finish(true); return }
             chunks.push(chunk)
           })
-          backend.once('end',()=>finish(false,backend)); backend.once('error',()=>finish(true)); backend.once('aborted',()=>finish(true))
+          backend.once('end',()=>finish(false,backend)); backend.once('error',e=>{transport=e.code;finish(true)}); backend.once('aborted',()=>{transport='BACKEND_ABORTED';finish(true)})
         })
         owned.add(outgoing)
         timer = setTimeout(()=>{failure = new HttpError(504,'Backend request timed out');outgoing.destroy();finish(true)},declared || url.pathname === '/_brain/uploads' || url.pathname.startsWith('/_brain/uploads/') ? 35000 : 10000)
-        outgoing.once('error',()=>finish(true)); req.once('aborted',cancel); res.once('close',cancel)
+        outgoing.once('error',e=>{transport=e.code;finish(true)}); req.once('aborted',cancel); res.once('close',cancel)
         req.on('data',data); req.once('end',end)
         if (req.readableEnded) end()
       } catch { outgoing?.destroy(); finish(true) }
@@ -531,7 +550,7 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
       req.method = method
       req.$brainForwardedFor = forwardedFor(incoming)
       // A service call acts as the key's owner, never as the visitor: it sends no session.
-      req.headers = { ...(serviceKey ? { authorization: 'Bearer ' + serviceKey } : { cookie: cookies(incoming, false) }), accept: 'application/json', 'content-type':'application/json', 'content-length':String(bytes.length) }
+      req.headers = { ...(serviceKey ? { authorization: 'Bearer ' + serviceKey } : ownSession ? {} : { cookie: cookies(incoming, false) }), accept: 'application/json', 'content-type':'application/json', 'content-length':String(bytes.length) }
       if (method !== 'GET') {
         req.headers.origin = bridgeOrigin(incoming, rid, 'Native writes require a same-origin server request')
       }
@@ -558,6 +577,15 @@ export function nativeAuthBridge(raw, refused, serviceKey, report) {
           if (!String(headers['content-type'] || '').startsWith('application/json')) throw new HttpError(502, 'Native resource response must be JSON')
           try { value = JSON.parse(data.toString('utf8')) } catch { throw new HttpError(502, 'Native resource response is invalid') }
         }, 2 * 1024 * 1024)
+      } catch (e) {
+        // A read that failed: `load` may catch it and render anyway, so the page answer says what happened (ssr below).
+        if (method === 'GET' && !(e?.status >= 400 && e.status < 500)) {
+          const seen = incoming.$brainFailedReads || (incoming.$brainFailedReads = { reads: 0, backendCode: undefined, transport: undefined })
+          seen.reads++
+          seen.backendCode ??= e?.code
+          seen.transport ??= e?.transport
+        }
+        throw e
       } finally { req.destroy() }
       if (response.destroyed || response.writableEnded) throw new HttpError(409, 'The server request has ended')
       return value
@@ -796,18 +824,22 @@ export function createServer(o = {}) {
   // ctx.env: what the supervisor passed, read-only; the service key stays with ctx.backend.service
   const { BRAIN_SERVICE_API_KEY: serviceKey, BRAIN_JOBS_API_KEY: _jobs, BRAIN_JOBS_SYSTEM_KEY: _jobsSystem, BRAIN_ROUTES_API_KEY: _routes, BRAIN_ROUTES_SYSTEM_KEY: _routesSystem, ...visibleEnv } = o.env || ENV
   const env = Object.freeze(visibleEnv)
-  const native = nativeAuthBridge(o.backendURL ?? env.BRAIN_BACKEND_URL, (...why) => originRefused(...why), serviceKey, (...entry) => log(...entry))
-  // Using the native backend does not have to mean it owns the visitor's session: `app` keeps the signed cookie.
   const backendSession = o.backendSession ?? env.BRAIN_BACKEND_SESSION
   if (backendSession && backendSession !== 'app') throw Error("BRAIN_BACKEND_SESSION must be app, or unset for the backend's own session")
+  const native = nativeAuthBridge(o.backendURL ?? env.BRAIN_BACKEND_URL, (...why) => originRefused(...why), serviceKey, (...entry) => log(...entry), backendSession === 'app')
+  // Using the native backend does not have to mean it owns the visitor's session: `app` keeps the signed cookie.
   const nativeSession = native && backendSession !== 'app'
   if (o.nativeSockets !== undefined && typeof o.nativeSockets !== 'boolean') throw Error('nativeSockets must be an explicit boolean')
   const SITEMAP_BYTES = +(o.sitemapBytes ?? 50 * 1024 * 1024) // protocol: 50 MB uncompressed per sitemap file
   const secret = o.secret ?? env.BRAIN_SECRET ?? ''
   const COMPRESS = o.compress !== false && env.BRAIN_COMPRESS !== 'off' // a proxy that already compresses can opt out
   const sink = o.log || ((level, msg, extra) => console[level === 'error' ? 'error' : 'log'](json({ t: new Date().toISOString(), level, msg, ...extra })))
+  // Requests in flight by rid: a 5xx whose cause reached no log line gets one when the response closes (dispatch below).
+  const liveRequests = new Map()
+  let statusPageWindow = 0, statusPageLogs = 0
   const log = (level, msg, extra = {}) => {
     const safe = { ...extra }
+    if (level !== 'info' && extra.rid) { const live = liveRequests.get(extra.rid); if (live) live.logged = true }
     // Error messages may contain credentials or request data. Retain only bounded V8 source frames.
     if (typeof safe.stack === 'string') {
       const kind = /^(TypeError|ReferenceError|RangeError|SyntaxError|AggregateError|Error):/.exec(safe.stack)?.[1] || 'Error'
@@ -843,6 +875,9 @@ export function createServer(o = {}) {
   // log fields for a thrown value: its stack (sanitized by log) plus, for B09xx budget failures, the typed fields only
   const trace = e => {
     const out = { stack: String((e && e.stack) || e) }
+    if (e instanceof HttpError && OWN_CAUSES.has(e.message)) out.cause = e.message
+    if (e && CODE_SHAPE.test(e.transport || '')) out.transport = e.transport
+    if (e && typeof e.code === 'string' && CODE_SHAPE.test(e.code)) out.backendCode = e.code
     if (e && e.kind === 'budget' && /^B09\d\d$/.test(e.code) && typeof e.budget === 'string' && /^[a-zA-Z]{1,16}$/.test(e.budget)) {
       const str = (v, n) => typeof v === 'string' ? v.slice(0, n) : null, pos = v => Number.isSafeInteger(v) && v > 0 ? v : null
       out.budgetFailure = { code: e.code, budget: e.budget, limit: Number.isFinite(e.limit) ? e.limit : null, file: str(e.file, 256), component: str(e.component, 80), line: pos(e.line), column: pos(e.column), fix: str(e.fix, 200) || 'Bound the work or move it to an owned worker.' }
@@ -936,7 +971,7 @@ export function createServer(o = {}) {
       res.req.$nativeLogout.then(() => send(res, status, body, headers, configuredExternal), () => send(res, 503, '', {}, false))
       return
     }
-    if (native && res.req.$nativeLogoutError) { status = 503; body = ''; headers = {}; res.req.$nativeLogoutError = false }
+    if (native && res.req.$nativeLogoutError) { status = 503; body = ''; headers = {}; res.req.$nativeLogoutError = false; res.$brainCause = 'native sign-out failed' }
     if (native && res.req.$nativeLogoutHeaders) {
       const relay = res.req.$nativeLogoutHeaders, own = headers['set-cookie']
       headers = { ...headers, ...relay, 'set-cookie': [...(own ? Array.isArray(own) ? own : [own] : []), ...relay['set-cookie']] }
@@ -974,6 +1009,7 @@ export function createServer(o = {}) {
         delete headers['content-length']
       }
     }
+    if (headers.vary) headers = { ...headers, vary: varyOnce(headers.vary) }
     res.writeHead(status, { ...SECURITY, ...(server.draining ? { connection: 'close' } : {}), ...headers })
     res.end(res.req.method === 'HEAD' || status === 204 || status === 205 || status === 304 ? undefined : body)
   }
@@ -995,8 +1031,8 @@ export function createServer(o = {}) {
   const notFound = (req, res) => failPage(res, 404, res.getHeader('x-request-id'))
   // `gone()` from load (§33): 410 tells crawlers the URL was removed for good; views/410.brain, else the 404 page
   const missing = (req, res, x) => (x && x.gone === true ? failPage(res, 410, res.getHeader('x-request-id')) : notFound(req, res))
-  const failPage = (res, status, rid) => {
-    if (!wantsHtml(res.req)) return send(res, status, json({ schemaVersion: 1, status, rid, error: STATUS_CODES[status] || 'Request failed' }), { 'content-type': MIME['.json'] })
+  const failPage = (res, status, rid, detail) => {
+    if (!wantsHtml(res.req)) return send(res, status, json({ schemaVersion: 1, status, rid, error: detail || STATUS_CODES[status] || 'Request failed' }), { 'content-type': MIME['.json'] })
     const custom = (status === 404 && mf.notFound) || (mf.errors && mf.errors[status]) || (status === 410 && !file('410.html') ? mf.notFound : `${status}.html`)
     const path = typeof custom === 'string' && file(custom)
     return html(res, status, path ? readFileSync(path, 'utf8') : defaultError(status, rid, BASE))
@@ -1049,16 +1085,20 @@ export function createServer(o = {}) {
   const SSRC = new Map(), SSRC_MAX = 500, SSRC_BYTES = 32 * 1024 * 1024, SSRC_ENTRY = 1024 * 1024
   let ssrBytes = 0
   async function cached(req, res, route, params, url, rid) {
-    const n = +route.cache, ms = n * 1000, key = (route.locale || '') + url.pathname + url.search
-    const fill = () =>
-      new Promise(ok => {
+    const n = +route.cache, ms = n * 1000, key = (route.locale || '') + url.pathname + cacheSearch(url)
+    const fill = () => {
+      let failed = false
+      return new Promise(ok => {
         const cap = { req, $capture: (out, h, st) => {
           const headers = Object.fromEntries(Object.entries(h).map(([k, v]) => [k.toLowerCase(), v]))
           const privateResponse = headers['set-cookie'] || headers['vary'] || /private|no-store|no-cache/i.test(headers['cache-control'] || '')
+          if (st >= 500) failed = true
           ok(st === 200 ? { out, h, cacheable: !privateResponse, etag: 'W/"' + tag(out) + '"', t: Date.now(), bytes: Buffer.byteLength(out) } : null)
-        }, writeHead() {}, end: () => ok(null), setHeader() {}, getHeader() {} }
+        }, writeHead(st) { if (st >= 500) failed = true }, end: () => ok(null), setHeader() {}, getHeader: name => (name === 'x-request-id' ? rid : undefined), once() {}, removeListener() {} }
         ssr(req, cap, route, params, url, rid, null, 200, null, true).catch(() => ok(null))
       }).then(c => {
+        // A failed revalidation keeps the copy until 2N, which is what `stale-if-error` promises downstream.
+        if ((!c || !c.cacheable) && (failed || req.$brainFailedReads) && SSRC.has(key)) return c
         if (!c || !c.cacheable) {
           ssrBytes -= SSRC.get(key)?.bytes || 0
           SSRC.delete(key)
@@ -1076,7 +1116,8 @@ export function createServer(o = {}) {
         }
         return c
       })
-    const serve = c => html(res, 200, c.out, { ...c.h, 'cache-control': c.cacheable ? `public, s-maxage=${n}, stale-while-revalidate=${n}` : 'no-store' }, c.etag)
+    }
+    const serve = c => html(res, 200, c.out, { ...c.h, 'cache-control': c.cacheable ? `public, s-maxage=${n}, stale-while-revalidate=${n}, stale-if-error=${n}` : 'no-store' }, c.etag)
     let c = SSRC.get(key)
     const age = c ? Date.now() - c.t : Infinity
     if (c && age < 2 * ms) {
@@ -1129,8 +1170,17 @@ export function createServer(o = {}) {
     const loadOutcome = e => {
       if (e && e.redirect) return send(res, e.status || 303, '', { location: withBase(linkTo(route, redirect(e.redirect, e.status ?? 303).redirect)), ...ctx.session.headers() })
       if ((e instanceof HttpError && e.status === 404) || (e && e.notFound === true)) return missing(req, res, e) // `notFound()` 404 / `gone()` 410
+      // the backend or another service said "not now": a temporary 503 tells crawlers to come back, a 500 tells them it broke
+      // a status the page chose itself (`new HttpError(429)`) stays as it is, with the same hint to come back
+      if (e && (e.status === 429 || e.status === 503) && !(e instanceof HttpError) && !res.headersSent) {
+        log('warn', 'load temporarily unavailable', { rid, path: url.pathname, status: 503, ...trace(e) })
+        res.setHeader('retry-after', String(Math.min(Math.ceil(e.retryAfter) || 5, 3600)))
+        res.setHeader('cache-control', 'no-store')
+        return errorPage(req, res, route, params, url, rid, 503)
+      }
       const status = intendedStatus(e) || 500
       log('error', 'load failed', { rid, path: url.pathname, status, ...trace(e) })
+      if ((status === 429 || status === 503) && !res.headersSent) res.setHeader('retry-after', String(Math.min(Math.ceil(e.retryAfter) || 5, 3600)))
       return status === 500 ? errorPage(req, res, route, params, url, rid) : failPage(res, status, rid)
     }
     if (route.stream && route.server && !fixed && !forms && status === 200 && !res.$capture) return streamed(req, res, route, params, url, rid, ctx, keep(extra || {}), loadOutcome)
@@ -1144,6 +1194,10 @@ export function createServer(o = {}) {
       return loadOutcome(e)
     }
     if (props && (props.redirect || props.notFound === true)) return loadOutcome(props) // `return redirect()` / `return notFound()`
+    if (req.$brainFailedReads && !fixed) {
+      softFailure(req, rid, url, status)
+      extra = { ...extra, 'cache-control': 'no-store' } // what it rendered instead is not worth keeping
+    }
     let body, seo, failed
     try {
       const at = { path: url.pathname, params: params || {}, query: Object.fromEntries(url.searchParams) } // route() (§41.5)
@@ -1172,6 +1226,11 @@ export function createServer(o = {}) {
   // (head, CSS, layout shell) is sent, the view when load() ends. The status and headers are out by then, so a late
   // redirect becomes location.replace and a late failure an inline notice with the request id (both logged); load()
   // cannot change the session on a streamed route.
+  // `load` caught a failed backend read and rendered: the status it asked for stands, the log says what is behind it.
+  const softFailure = (req, rid, url, status) => {
+    const { reads, backendCode, transport } = req.$brainFailedReads
+    log('warn', 'page rendered after a failed backend read', { rid, path: url.pathname, status, reads, backendCode, transport, fix: 'load caught the failure and returned other props; let it throw for a 503, or show that the data is missing' })
+  }
   async function streamed(req, res, route, params, url, rid, ctx, extra, outcome) {
     const [top, bottom = ''] = readFileSync(file(route.page), 'utf8').split('<!--brain:ssr-->')
     const sm = await load(route.server)
@@ -1241,6 +1300,7 @@ export function createServer(o = {}) {
       log('error', 'load failed (streamed)', { rid, path: url.pathname, status: 200, ...trace(e) }) // headers already out
       return fail()
     }
+    if (req.$brainFailedReads) softFailure(req, rid, url, 200)
     try {
       const { body, failed } = await (queue = queue.then(() => render(route, props, null, at), () => render(route, props, null, at)))
       for (const f of failed || []) log('error', 'component failed during SSR', { rid, path: url.pathname, comp: f.comp, where: f.w, ...trace(f.e) })
@@ -1272,9 +1332,9 @@ export function createServer(o = {}) {
     return failPage(res, 403, rid)
   }
   // a failing load or guard → the folder's _error.brain (route `error`, props { message, rid }), else the generic page
-  function errorPage(req, res, route, params, url, rid) {
-    if (wantsHtml(req) && route.error) return ssr(req, res, route.error, params, url, rid, null, 500, { message: 'Something went wrong.', rid })
-    return failPage(res, 500, rid)
+  function errorPage(req, res, route, params, url, rid, status = 500) {
+    if (wantsHtml(req) && route.error) return ssr(req, res, route.error, params, url, rid, null, status, { message: 'Something went wrong.', rid })
+    return failPage(res, status, rid)
   }
   async function render(route, props, forms, at = null) {
     const { install } = await load('_server/dom.js')
@@ -1518,9 +1578,19 @@ export function createServer(o = {}) {
     if (path === null) return false
     const md = file(mdPath(path))
     if (!md) return false
-    send(res, 200, req.method === 'HEAD' ? '' : readFileSync(md), { 'content-type': MIME['.md'], 'cache-control': 'public, max-age=3600', vary: 'accept' })
+    send(res, 200, req.method === 'HEAD' ? '' : readFileSync(md), { 'content-type': MIME['.md'], 'cache-control': 'public, max-age=3600', vary: 'accept', ...twinCanonical(path) })
     return true
   }
+  // A Markdown copy repeats its page: the header names the canonical the page itself declares. A page without one (no
+  // site configured) or with a per-request pattern gets no header, so this never invents a URL.
+  function twinCanonical(path) {
+    const stem = path.replace(/\.md$/, '').replace(/\/+$/, '')
+    const page = file(stem ? stem + '.html' : 'index.html') || file(stem + '/index.html')
+    if (!page) return {}
+    const tag = /<link\b[^>]*\brel=["']canonical["'][^>]*>/i.exec(readFileSync(page, 'utf8'))?.[0]
+    const href = tag && /\bhref="(https?:\/\/[^"<>\s]+)"/.exec(tag)?.[1].replaceAll('&amp;', '&')
+    return href && URL.canParse(href) && !/\/[:*]/.test(new URL(href).pathname) ? { link: `<${href}>; rel="canonical"` } : {}
+  }
   function serveStatic(req, res, url) {
     const p = publicStaticPath(url.pathname)
     if (p === null) return false
@@ -1538,6 +1608,7 @@ export function createServer(o = {}) {
         return html(res, 200, page, md ? { vary: 'accept', 'x-brain-static': '1' } : { 'x-brain-static': '1' }, '"' + (mf.build || tag(page)) + '"'), true
       }
       const headers = {
+        ...(ext === '.md' ? twinCanonical(p) : {}),
         'content-type': type,
         // the worker script must be revalidated on every check, or a CDN could keep an old worker for an hour (§35.7)
         'cache-control': p.startsWith('/_b/') ? 'public, max-age=31536000, immutable' : p === '/sw.js' ? 'no-cache' : 'public, max-age=3600',
@@ -1568,7 +1639,43 @@ export function createServer(o = {}) {
     if (req.method !== 'GET' && req.method !== 'HEAD') return notFound(req, res)
     if (!native) return send(res, 200, json({ ok: true }), headers)
     try { await native.proxy(req, res, new URL(url.pathname, url), rid, send) }
-    catch { if (!res.headersSent) send(res, 503, json({ ok: false }), headers) }
+    catch (e) {
+      if (!res.headersSent) {
+        log('warn', 'health probe could not reach the native backend', { rid, path: url.pathname, status: 503, ...trace(e) })
+        send(res, 503, json({ ok: false }), headers)
+      }
+    }
+  }
+
+  const urlVariant = req => {
+    if (req.method !== 'GET' && req.method !== 'HEAD') return null
+    const q = req.url.indexOf('?'), raw = q < 0 ? req.url : req.url.slice(0, q)
+    if (!raw.includes('//') && !raw.endsWith('/index.html')) return null
+    let path = raw.replace(/\/{2,}/g, '/')
+    const app = '/' + (path.startsWith(BASE) ? path.slice(BASE.length) : path.slice(1))
+    if (/^\/(?:api|_brain|_r|s)(?:\/|$)/.test(app) && !raw.startsWith('//')) return null
+    if (path.endsWith('/index.html')) path = path.slice(0, -'index.html'.length)
+    if (path !== BASE && path !== '/' && (path.endsWith('/') && SLASH !== 'always')) path = path.replace(/\/+$/, '')
+    const location = path + (q < 0 ? '' : req.url.slice(q))
+    try { safeLocation(location) } catch { return null }
+    return location
+  }
+  // `<meta seo query="page">`: `page` is a number from 1 and page 1 is the URL without it. A view decides past its last
+  // page with notFound(). → null (nothing to do) · 404 · the URL to redirect to.
+  const pagedRoutes = new Map()
+  const pageParameter = (route, url) => {
+    if (!url.searchParams.has('page') || !route.page) return null
+    if (!pagedRoutes.has(route.page)) {
+      const keys = /<meta name="brain-query" content="([^"]*)">/.exec(readFileSync(file(route.page), 'utf8'))?.[1]
+      pagedRoutes.set(route.page, !!keys && keys.split(/[\s,]+/).includes('page'))
+    }
+    if (!pagedRoutes.get(route.page)) return null
+    const values = url.searchParams.getAll('page')
+    if (values.length > 1 || !/^[1-9]\d{0,8}$/.test(values[0])) return 404
+    if (values[0] !== '1') return null
+    const rest = new URLSearchParams(url.search)
+    rest.delete('page')
+    return url.pathname + (rest.size ? '?' + rest : '')
   }
 
   // ---------- dispatch ----------
@@ -1585,13 +1692,23 @@ export function createServer(o = {}) {
     }
     const rid = req.headers['x-request-id'] && /^[\w-]{1,64}$/.test(req.headers['x-request-id']) ? req.headers['x-request-id'] : randomUUID()
     res.setHeader('x-request-id', rid)
+    const live = { logged: false }
+    liveRequests.set(rid, live)
+    res.once('close', () => {
+      if (liveRequests.get(rid) === live) liveRequests.delete(rid)
+      // The net under every path: a 5xx that was answered always leaves a line with its request id.
+      if (res.statusCode >= 500 && !live.logged && !res.$brainMuted) log(res.$brainCause === STATUS_PAGE ? 'info' : 'error', 'server error answered', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], status: res.statusCode, cause: res.$brainCause || 'no cause recorded on this path', ...(res.$brainCause === STATUS_PAGE ? {} : { fix: 'Search this rid in the native backend log; its failed requests carry the same id' }) })
+    })
     const t0 = performance.now()
     res.on('finish', () => {
       const ms = performance.now() - t0
       if (ms > 1000) log('warn', 'slow request', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], status: res.statusCode, ms: Math.round(ms) })
     })
     try {
-      // `//` makes new URL throw and `//host/x` would be read as another host
+      // One URL per page: `//route`, `/a//b` and `/route/index.html` answer one 301 on this origin. The path is rewritten
+      // as text, before URL parsing: `//host/x` would be read as another host. Backend paths are left to the backend.
+      const variant = urlVariant(req)
+      if (variant) return send(res, 301, '', { location: variant, 'cache-control': 'public, max-age=3600' })
       if (req.url.startsWith('//')) return notFound(req, res)
       const full = new URL(req.url, 'http://' + (req.headers.host || 'localhost'))
       // /_health stays at the root: the supervisor calls it there whatever the base
@@ -1620,13 +1737,23 @@ export function createServer(o = {}) {
       // a status page opened directly answers its own status: `/403` is never a 200 that a crawler or a probe can trust
       const reserved = post ? 0 : reservedStatus(url.pathname)
       if (reserved === 403) return forbidden(req, res, url, rid, '')
-      if (reserved) return failPage(res, reserved, rid)
+      if (reserved) {
+        // Anyone can open it, so the note about it is bounded and is not an error.
+        const minute = Math.floor(Date.now() / 60000)
+        if (statusPageWindow !== minute) { statusPageWindow = minute; statusPageLogs = 0 }
+        res.$brainCause = STATUS_PAGE
+        res.$brainMuted = statusPageLogs++ >= 16
+        return failPage(res, reserved, rid)
+      }
       for (const route of routes) {
         const m = route.rx.exec(url.pathname)
         if (!m) continue
         // a form page without load is prerendered: GET serves that file (build ETag); only its POST needs the server
         if (!post && route.forms && serveStatic(req, res, url)) return
         if (!post && serveTwin(req, res, url)) return
+        const paged = post ? null : pageParameter(route, url)
+        if (paged === 404) return notFound(req, res)
+        if (paged) return send(res, 301, '', { location: withBase(paged), 'cache-control': 'public, max-age=3600' })
         return await (post ? formPost : ssr)(req, res, route, m.groups ? { ...m.groups } : {}, url, rid)
       }
       if (post) return send(res, 405, 'Method not allowed', { allow: 'GET, HEAD' })
@@ -1637,9 +1764,19 @@ export function createServer(o = {}) {
       if (isProbe(url.pathname)) return await answerProbe(req, res, url, rid)
       notFound(req, res)
     } catch (e) {
-      log('error', 'unhandled', { rid, path: req.url, ...trace(e) })
-      if (!res.headersSent) failPage(res, intendedStatus(e) || 500, rid)
-      else res.end()
+      const busy = e instanceof HttpError && e.code === 'BRIDGE_BUSY'
+      if (busy) log('warn', 'backend bridge busy', { rid, path: req.$brainPath || String(req.url || '').split('?')[0], fix: e.fix })
+      else log('error', 'unhandled', { rid, path: req.url, ...trace(e) })
+      try {
+        if (busy && !res.headersSent) { res.setHeader('retry-after', String(e.retryAfter)); failPage(res, 503, rid, { code: e.code, message: 'Service Unavailable', fix: e.fix }) }
+        else if (!res.headersSent) failPage(res, intendedStatus(e) || 500, rid)
+        else res.end()
+      } catch (again) {
+        // the error page itself failed: still an answer, never an unhandled rejection that takes the process down
+        log('error', 'error page failed', { rid, path: req.url, ...trace(again) })
+        if (!res.headersSent) res.writeHead(500, SECURITY)
+        res.end()
+      }
     }
   })
   if (native) server.once('close', () => native.close())
@@ -1651,6 +1788,7 @@ export function createServer(o = {}) {
 }
 
 // ---------- session (signed cookie; shared with the dev server) ----------
+const STATUS_PAGE = 'status page opened directly'
 const COOKIE = '__Host-session', SECRET_COOKIE = '__Host-session-secret', SECRET_MAX = 3500, DEFAULT_SESSION_SECONDS = 7 * 24 * 3600
 // Keys that still verify and decrypt during a rotation; new cookies always use the current key.
 const previousKeys = () => (process.env.BRAIN_SECRET_PREVIOUS || '').split(',').map(k => k.trim()).filter(Boolean)
@@ -2193,6 +2331,8 @@ function real(p) {
 }
 if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.url))) {
   process.env.NODE_ENV = 'production'
+  // A closed log pipe is the operator's matter: requests do not depend on it.
+  for (const stream of [process.stdout, process.stderr]) stream.on('error', error => { if (error.code !== 'EPIPE') throw error })
   const s = createServer({ dist: fileURLToPath(new URL('.', import.meta.url)) })
   const fd = ENV.BRAIN_LISTEN_FD
   const where = fd ? { fd: Number(fd) } : { port: +(ENV.PORT || 3000), host: ENV.HOST || '127.0.0.1' }