@christianirack/brainllm-runtime 0.5.0 → 0.6.0

package/brain-guard.js

@@ -24,22 +24,22 @@ const TEXT = 'This section could not load.'
 const BUDGET = { nodes: 200000, rows: 100000, runs: 1000, ms: 200 }
 const STOPPED = 'This part stopped to protect the page.'
 const OWN = new WeakMap() // root owner → instance
-const now = () => (G.performance ? performance.now() : Date.now())
+const now = () => performance.now()
 // work per flush: the time between two effect runs belongs to the earlier one (the hook fires as a run starts); the
 // last run of a flush is settled by a microtask queued at the flush's first run
 let LX = null, LT = 0, inFlush = false
 const touched = new Set()
 // elements under a root, and the most element children any one of them has (the rows of a list)
 const count = (e, c) => {
-  if (e.nodeType !== 1) return
+  if (e.nodeType != 1) return
   c.nodes++
   let k = 0
-  for (const n of e.childNodes) if (n.nodeType === 1) k++, count(n, c)
+  for (const n of e.childNodes) if (n.nodeType == 1) k++, count(n, c)
   if (k > c.rows) c.rows = k
 }
 // elements under a root: native when the DOM has it (the shim walks)
 const elems = r => {
-  if (r.nodeType !== 1) return 0
+  if (r.nodeType != 1) return 0
   if (r.getElementsByTagName) return 1 + r.getElementsByTagName('*').length
   const c = { nodes: 0, rows: 0 }
   count(r, c)
@@ -219,7 +219,7 @@ export function guard(C, fb, budget) {
           report(pending[0], pending[1])
           pending = null
         }
-        for (const n of nodes) if (n.nodeType === 1) (n.$g = handler), (n.$c = reqs)
+        for (const n of nodes) if (n.nodeType == 1) (n.$g = handler), (n.$c = reqs)
       }, own)
     function again() {
       const p = end.parentNode
@@ -232,7 +232,7 @@ export function guard(C, fb, budget) {
     if (own)
       I.root(() => fx(() => () => {
         if (dispose) dispose()
-        for (const n of nodes) if (n.nodeType === 1) (n.$g = null), (n.$c = null) // see brain-dev: no node → instance links
+        for (const n of nodes) if (n.nodeType == 1) (n.$g = null), (n.$c = null) // see brain-dev: no node → instance links
         I.rm(nodes)
       }), own)
     return [...nodes, end]

package/brain-live.js

@@ -4,6 +4,8 @@ import { sig, fx, untrack, _rt } from './brain.js'
 const G = globalThis, I = _rt()
 const MAX_OWNERS = 128, MAX_ROOMS = 32, FRAME = 4096, BUFFER = 32768
 const COALESCE = 100, READY_MS = 8000, REFRESH_MS = 10000, RETRY_MS = 60000
+// A joined room proves health only once the connection stays up this long; shorter sessions keep spending the budget.
+const STABLE_MS = 30000
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key)
 const RESERVED = new Set(['constructor', 'prototype', '__proto__', 'id', 'owner', 'created_at', 'updated_at', 'search'])
@@ -66,7 +68,7 @@ function createBroker() {
   const members = new Set(), joined = new Map(), waiting = [], events = new Map()
   let socket = null, epoch = 0, scope = null, terminal = '', ready = false
   let reconcileQueued = false, retryTimer, readyTimer, heartbeat, pongTimer, flushTimer
-  let attempts = 0, retryStart = 0, lastConnect = 0
+  let attempts = 0, retryStart = 0, lastConnect = 0, healthySince = 0
 
   const update = () => {
     for (const member of members) {
@@ -89,7 +91,7 @@ function createBroker() {
     }
   }
   const stop = () => {
-    epoch++; ready = false
+    epoch++; ready = false; healthySince = 0
     clearTimeout(retryTimer); retryTimer = null
     clearTimeout(readyTimer); clearInterval(heartbeat); clearTimeout(pongTimer)
     readyTimer = heartbeat = pongTimer = null
@@ -160,6 +162,7 @@ function createBroker() {
     }
   }
   const retry = () => {
+    if (healthySince && Date.now() - healthySince >= STABLE_MS) { attempts = 0; retryStart = 0 }
     stop()
     if (++attempts > 5 || (retryStart && Date.now() - retryStart >= RETRY_MS)) { terminal = 'exhausted'; update(); return }
     if (!retryStart) retryStart = Date.now()
@@ -227,7 +230,7 @@ function createBroker() {
         const key = waiting.shift()
         if (!key) { reject('protocol-error'); return }
         joined.set(key, value.type === 'resync' ? 'ready' : 'forbidden')
-        if (value.type === 'resync') { attempts = 0; retryStart = 0 }
+        if (value.type === 'resync' && !healthySince) healthySince = Date.now()
         update()
         if (value.type === 'resync') invalidate(value, key)
       } else {

package/brain-mcp.js

@@ -7,8 +7,10 @@
 // anything destructive should still ask for confirmation in the UI.
 // Optional 5th argument (WebMCP draft 2026-10-27): { title, readOnly, consequential, untrusted } → `title` and
 // `annotations: { readOnlyHint, consequentialHint, untrustedContentHint }` on the registration; only the keys given.
+// `<meta tools>` (#106) compiles to registerTools([{ name, description, inputSchema, execute }]): the schema is built by
+// the compiler from the tool's parameter list, the rest (detection, lifetime, validation, answers) is the same as tool().
 import { fx } from './brain.js'
-import { rule, check } from './brain-schema.js'
+import { rule, check, msg } from './brain-schema.js'
 
 const G = globalThis
 export const context = () => (G.document && G.document.modelContext) || (G.navigator && G.navigator.modelContext) || null
@@ -36,9 +38,8 @@ const text = v => ({ content: [{ type: 'text', text: typeof v === 'string' ? v :
 
 const HINTS = [['readOnly', 'readOnlyHint'], ['consequential', 'consequentialHint'], ['untrusted', 'untrustedContentHint']]
 
-// The registration dictionary: name, description, inputSchema, then title/annotations only when given.
-export function definition(name, description, params, opts) {
-  const def = { name, description, inputSchema: schema(params) }
+// title/annotations onto a registration dictionary, only the keys given.
+function extras(def, opts) {
   if (!opts) return def
   if (typeof opts.title === 'string' && opts.title) def.title = opts.title
   let annotations = null
@@ -50,24 +51,92 @@ export function definition(name, description, params, opts) {
   return def
 }
 
-export function tool(name, description, params, run, opts) {
+// The registration dictionary: name, description, inputSchema, then title/annotations only when given.
+export function definition(name, description, params, opts) {
+  return extras({ name, description, inputSchema: schema(params) }, opts)
+}
+
+// The browser's model context, or null where tools must not be registered (no WebMCP, server render, prerender).
+const live = () => {
   const mc = context()
-  if (!mc || !mc.registerTool || G.__brainSSR || G.__brainRoute) return
-  const rules = Object.fromEntries(Object.entries(params || {}).map(([k, s]) => [k, rule(s)]))
+  return mc && mc.registerTool && !G.__brainSSR && !G.__brainRoute ? mc : null
+}
+
+// `execute` for a registration: invalid arguments answer with the field's message and never run the function; its
+// result (or error) is the tool's text answer.
+const answer = (invalid, run) => async (args = {}) => {
+  const m = invalid(args || {})
+  if (m) return text(m)
+  try {
+    return text(await run(args || {}))
+  } catch (e) {
+    return text(`Error: ${(e && e.message) || e}`)
+  }
+}
+
+// Registers the dictionaries for the lifetime of the calling component (one effect, cleaned up on dispose). A
+// registration the browser refuses (a name another mounted instance already holds) is skipped: the page keeps working
+// and unmounting this instance leaves the other one's tool in place.
+function own(mc, make) {
   fx(() => {
-    const def = definition(name, description, params, opts)
-    def.execute = async (args = {}) => {
-      for (const k in rules) {
-        const m = check(rules[k], args[k])
-        if (m) return text(`${k}: ${m}`)
-      }
+    const defs = make(), offs = []
+    for (let i = 0; i < defs.length; i++) {
+      const name = defs[i].name
+      let reg
       try {
-        return text(await run(args))
-      } catch (e) {
-        return text(`Error: ${(e && e.message) || e}`)
+        reg = mc.registerTool(defs[i])
+      } catch {
+        continue
       }
+      offs.push(() => (reg && reg.unregister ? reg.unregister() : mc.unregisterTool && mc.unregisterTool(name)))
+    }
+    return () => {
+      for (let i = 0; i < offs.length; i++) offs[i]()
     }
-    const reg = mc.registerTool(def)
-    return () => (reg && reg.unregister ? reg.unregister() : mc.unregisterTool && mc.unregisterTool(name))
   })
 }
+
+export function tool(name, description, params, run, opts) {
+  const mc = live()
+  if (!mc) return
+  const rules = Object.fromEntries(Object.entries(params || {}).map(([k, s]) => [k, rule(s)]))
+  const invalid = args => {
+    for (const k in rules) {
+      const m = check(rules[k], args[k])
+      if (m) return `${k}: ${m}`
+    }
+    return ''
+  }
+  own(mc, () => [extras({ name, description, inputSchema: schema(params), execute: answer(invalid, run) }, opts)])
+}
+
+// A compiled parameter's JSON Schema → the message for a bad value ('' when it fits). Required means present: `false`
+// and `0` are values; a missing or empty one is not.
+const FORMAT = { email: 'email', uri: 'url', date: 'date' }, KIND = { number: 'num', boolean: 'bool' }
+function argError(p, v, req) {
+  if (v == null || v === '') return req ? msg('form.required', 'Required') : ''
+  if (p.type === 'array') return Array.isArray(v) ? '' : msg('form.list', 'Must be a list')
+  if (p.type === 'object') return typeof v === 'object' && !Array.isArray(v) ? '' : 'Must be an object'
+  const t = p.type === 'string' ? FORMAT[p.format] || 'str' : KIND[p.type]
+  return t ? check(rule(t), v) : ''
+}
+
+// `<meta tools>`: [{ name, description, inputSchema, execute, title?, readOnly?, consequential?, untrusted? }], emitted
+// by the compiler with `execute` bound to the component's same-named function.
+export function registerTools(list) {
+  const mc = live()
+  if (!mc) return
+  own(mc, () =>
+    list.map(t => {
+      const s = t.inputSchema || {}, props = s.properties || {}, req = s.required || []
+      const invalid = args => {
+        for (const k in props) {
+          const m = argError(props[k], args[k], req.includes(k))
+          if (m) return `${k}: ${m}`
+        }
+        return ''
+      }
+      return extras({ name: t.name, description: t.description, inputSchema: s, execute: answer(invalid, t.execute) }, t)
+    }),
+  )
+}

package/brain-outbound.js

@@ -0,0 +1,244 @@
+// Outbound HTTP for server logic: bounded attempts, deadlines, safe retries and redacted failures.
+// Built on node:http(s) with a resolver guard: every address a name resolves to is checked at connect time, so a
+// public name that resolves (or rebinds) to a private address is refused. No client library is bundled.
+const RETRY_STATUS = new Set([408, 425, 429, 500, 502, 503, 504])
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'])
+const MAX_TIMEOUT = 60000, MAX_RETRIES = 5, MAX_BYTES = 16777216, MAX_WAIT = 30000
+
+export class HttpCallError extends Error {
+  constructor(code, message, detail = {}) {
+    super(message)
+    this.name = 'HttpCallError'
+    this.code = code
+    this.status = detail.status ?? null
+    this.attempts = detail.attempts ?? 0
+    this.url = detail.url ?? ''
+  }
+}
+
+function ipv4(host) {
+  const parts = host.split('.')
+  if (parts.length !== 4 || !parts.every(p => /^\d{1,3}$/.test(p) && +p < 256)) return null
+  return parts.map(Number)
+}
+// 0/8, 10/8, 127/8, 169.254/16 (cloud metadata), 172.16/12, 192.0.0/24, 192.168/16, 100.64/10 (CGNAT),
+// 198.18/15 (benchmark), 224/4 multicast and 240/4 reserved
+function privateV4([a, b, c]) {
+  return a === 0 || a === 10 || a === 127 || (a === 169 && b === 254) || (a === 172 && b >= 16 && b < 32) || (a === 192 && b === 168) || (a === 192 && b === 0 && c === 0) || (a === 100 && b >= 64 && b < 128) || (a === 198 && (b === 18 || b === 19)) || a >= 224
+}
+function ipv6(host) {
+  let text = host
+  const tail = text.match(/:(\d+\.\d+\.\d+\.\d+)$/)
+  if (tail) {
+    const v4 = ipv4(tail[1])
+    if (!v4) return null
+    text = `${text.slice(0, -tail[1].length)}${((v4[0] << 8) | v4[1]).toString(16)}:${((v4[2] << 8) | v4[3]).toString(16)}`
+  }
+  const halves = text.split('::')
+  if (halves.length > 2) return null
+  const head = halves[0] ? halves[0].split(':') : [], rest = halves.length === 2 && halves[1] ? halves[1].split(':') : []
+  const fill = 8 - head.length - rest.length
+  if (halves.length === 1 ? fill !== 0 : fill < 1) return null
+  const words = [...head, ...Array(halves.length === 2 ? fill : 0).fill('0'), ...rest]
+  return words.every(w => /^[0-9a-f]{1,4}$/.test(w)) ? words.map(w => parseInt(w, 16)) : null
+}
+// Loopback, unspecified, IPv4-mapped/compatible, NAT64 and 6to4 (checked against the embedded IPv4), unique local,
+// link-local, site-local, multicast, Teredo and documentation ranges
+function privateV6(w) {
+  const quad = (hi, lo) => [hi >> 8, hi & 255, lo >> 8, lo & 255]
+  if (w.slice(0, 5).every(x => x === 0) && (w[5] === 0 || w[5] === 0xffff)) return privateV4(quad(w[6], w[7]))
+  if (w[0] === 0x64 && w[1] === 0xff9b) return privateV4(quad(w[6], w[7]))
+  if (w[0] === 0x2002) return privateV4(quad(w[1], w[2]))
+  const top = w[0]
+  return (top & 0xfe00) === 0xfc00 || (top & 0xffc0) === 0xfe80 || (top & 0xffc0) === 0xfec0 || (top & 0xff00) === 0xff00 || (top === 0x2001 && (w[1] === 0 || w[1] === 0xdb8))
+}
+// True for an IP literal (v4 or v6, brackets allowed) in a non-public range; false for names and public addresses
+function privateAddress(address) {
+  const host = String(address).toLowerCase().replace(/^\[|\]$/g, '').replace(/%.*$/, '')
+  const v4 = ipv4(host)
+  if (v4) return privateV4(v4)
+  const v6 = host.includes(':') ? ipv6(host) : null
+  return v6 ? privateV6(v6) : host.includes(':')
+}
+function privateHost(hostname) {
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '')
+  if (host === 'localhost' || /\.(localhost|internal|local|home\.arpa)$/.test(host)) return true
+  return privateAddress(host)
+}
+function redact(url) {
+  return `${url.origin}${url.pathname}`
+}
+function bounded(value, name, min, max, fallback) {
+  if (value === undefined) return fallback
+  if (!Number.isInteger(value) || value < min || value > max) throw RangeError(`httpCall: ${name} must be an integer in ${min}..${max}`)
+  return value
+}
+function retryAfter(header) {
+  if (header == null) return null
+  const secs = Number(header)
+  const ms = Number.isFinite(secs) ? secs * 1000 : Date.parse(header) - Date.now()
+  return Number.isFinite(ms) ? Math.min(Math.max(ms, 0), MAX_WAIT) : null
+}
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+const PRIVATE = 'BRAIN_PRIVATE_ADDRESS'
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308])
+const CREDENTIAL_HEADERS = ['authorization', 'cookie', 'proxy-authorization']
+let net
+const nodeNet = () => (net ??= Promise.all([import('node:http'), import('node:https'), import('node:dns')]).then(([http, https, dns]) => ({ http, https, dns })))
+
+// Private targets are allowed by `allowPrivate: true`, by naming the host in `allowPrivate: [...]`, or in development
+// only by BRAIN_OUTBOUND_ALLOW_PRIVATE=1 (ignored when NODE_ENV is production)
+function allowsPrivate(option, hostname) {
+  if (option === true) return true
+  const host = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (Array.isArray(option) && option.some(h => String(h).toLowerCase() === host)) return true
+  const env = globalThis.process?.env ?? {}
+  return env.BRAIN_OUTBOUND_ALLOW_PRIVATE === '1' && env.NODE_ENV !== 'production'
+}
+function checkTarget(url, option) {
+  const safe = redact(url)
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new HttpCallError('UNSAFE_URL', `httpCall: ${safe} must be http(s) without credentials`, { url: safe })
+  const allow = allowsPrivate(option, url.hostname)
+  if (!allow && privateHost(url.hostname)) throw new HttpCallError('UNSAFE_URL', `httpCall: ${safe} targets a private or loopback address; pass allowPrivate for internal services`, { url: safe })
+  return allow
+}
+function guardedLookup(resolver, allow) {
+  return (hostname, options, callback) => {
+    resolver(hostname, { ...options, all: true }, (error, found) => {
+      if (error) return callback(error)
+      const list = (Array.isArray(found) ? found : [{ address: found, family: String(found).includes(':') ? 6 : 4 }]).filter(a => a && a.address)
+      if (!list.length) return callback(Object.assign(new Error(`${hostname} has no address`), { code: 'ENOTFOUND' }))
+      if (!allow && list.some(a => privateAddress(a.address))) return callback(Object.assign(new Error(`${hostname} resolves to a private address`), { code: PRIVATE }))
+      return options.all ? callback(null, list) : callback(null, list[0].address, list[0].family)
+    })
+  }
+}
+function payload(body, headers) {
+  if (body == null) return undefined
+  if (typeof body === 'string' || body instanceof Uint8Array) return body
+  if (body instanceof ArrayBuffer) return new Uint8Array(body)
+  if (ArrayBuffer.isView(body)) return new Uint8Array(body.buffer, body.byteOffset, body.byteLength)
+  if (body instanceof URLSearchParams) {
+    if (!headers.has('content-type')) headers.set('content-type', 'application/x-www-form-urlencoded;charset=UTF-8')
+    return body.toString()
+  }
+  throw TypeError('httpCall: body must be a string, bytes or URLSearchParams')
+}
+// One request on a fresh connection (no pooling, so a socket opened for an allowed private host is never reused)
+async function exchange(url, { method, headers, body, signal, lookup, allow }) {
+  const { http, https, dns } = await nodeNet()
+  return new Promise((resolve, reject) => {
+    const request = (url.protocol === 'https:' ? https : http).request(url, { method, headers: Object.fromEntries(headers), signal, agent: false, lookup: guardedLookup(lookup ?? dns.lookup, allow) })
+    request.on('response', resolve)
+    request.on('error', reject)
+    request.end(body)
+  })
+}
+function plainHeaders(raw) {
+  return Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, Array.isArray(v) ? v.join(', ') : v]))
+}
+
+async function readBody(response, maxBytes, url, attempts) {
+  const chunks = []
+  let size = 0
+  for await (const value of response) {
+    size += value.byteLength
+    if (size > maxBytes) {
+      response.destroy()
+      throw new HttpCallError('TOO_LARGE', `httpCall: response from ${url} exceeds ${maxBytes} bytes`, { status: response.statusCode, attempts, url })
+    }
+    chunks.push(value)
+  }
+  const out = new Uint8Array(size)
+  let at = 0
+  for (const c of chunks) { out.set(c, at); at += c.byteLength }
+  return out
+}
+
+/**
+ * httpCall(url, {method, headers, json, body, timeout, retries, idempotencyKey, maxBytes, backoff, allowPrivate, redirects, lookup, signal})
+ * → {status, ok, headers, text, json, attempts, url}. Network failures, deadlines, oversized bodies and final
+ * retryable statuses (5xx, 408, 425, 429) throw HttpCallError; other statuses are returned.
+ */
+export async function httpCall(target, options = {}) {
+  const method = String(options.method ?? 'GET').toUpperCase()
+  const timeout = bounded(options.timeout, 'timeout', 1, MAX_TIMEOUT, 10000)
+  const retries = bounded(options.retries, 'retries', 0, MAX_RETRIES, 2)
+  const maxBytes = bounded(options.maxBytes, 'maxBytes', 1, MAX_BYTES, 1048576)
+  const backoff = bounded(options.backoff, 'backoff', 1, 10000, 250)
+  const redirects = bounded(options.redirects, 'redirects', 0, 10, 0)
+  if (options.lookup !== undefined && typeof options.lookup !== 'function') throw TypeError('httpCall: lookup must be a dns.lookup-compatible function')
+  let url
+  try { url = new URL(target) } catch { throw new HttpCallError('UNSAFE_URL', 'httpCall: an absolute http(s) URL is required') }
+  const safe = redact(url)
+  const allowFirst = checkTarget(url, options.allowPrivate)
+
+  const headers = new Headers(options.headers ?? {})
+  let body = options.body
+  if (options.json !== undefined) {
+    body = JSON.stringify(options.json)
+    if (!headers.has('content-type')) headers.set('content-type', 'application/json')
+    if (!headers.has('accept')) headers.set('accept', 'application/json')
+  }
+  body = payload(body, headers)
+  if (options.idempotencyKey) headers.set('idempotency-key', options.idempotencyKey === true ? globalThis.crypto.randomUUID() : String(options.idempotencyKey))
+  const replayable = SAFE_METHODS.has(method) || headers.has('idempotency-key')
+  const allowed = replayable ? retries : 0
+
+  // One attempt: the request plus up to `redirects` hops, each target checked again before it is contacted
+  async function attemptOnce(signal) {
+    let hop = { url, method, headers: new Headers(headers), body, allow: allowFirst }
+    for (let hops = 0; ; hops++) {
+      const response = await exchange(hop.url, { ...hop, signal, lookup: options.lookup })
+      const location = response.headers.location
+      if (!redirects || !REDIRECT_STATUS.has(response.statusCode) || !location) return { response, url: hop.url }
+      response.resume()
+      if (hops >= redirects) throw new HttpCallError('REDIRECT', `httpCall: ${safe} redirected more than ${redirects} times`, { status: response.statusCode, url: safe })
+      let next
+      try { next = new URL(location, hop.url) } catch { throw new HttpCallError('REDIRECT', `httpCall: ${redact(hop.url)} sent an invalid redirect`, { status: response.statusCode, url: safe }) }
+      if (hop.url.protocol === 'https:' && next.protocol === 'http:') throw new HttpCallError('UNSAFE_URL', `httpCall: ${redact(hop.url)} redirected from https to http`, { url: redact(next) })
+      const allow = checkTarget(next, options.allowPrivate)
+      const nextHeaders = new Headers(hop.headers)
+      let nextMethod = hop.method, nextBody = hop.body
+      if (response.statusCode === 303 || ((response.statusCode === 301 || response.statusCode === 302) && hop.method === 'POST')) {
+        nextMethod = hop.method === 'HEAD' ? 'HEAD' : 'GET'
+        nextBody = undefined
+        for (const h of ['content-type', 'content-length']) nextHeaders.delete(h)
+      }
+      if (next.origin !== hop.url.origin) for (const h of CREDENTIAL_HEADERS) nextHeaders.delete(h)
+      hop = { url: next, method: nextMethod, headers: nextHeaders, body: nextBody, allow }
+    }
+  }
+
+  for (let attempt = 1; ; attempt++) {
+    const signal = AbortSignal.any([AbortSignal.timeout(timeout), options.signal].filter(Boolean))
+    let result = null, wait = null
+    try {
+      result = await attemptOnce(signal)
+      const status = result.response.statusCode
+      if (RETRY_STATUS.has(status)) {
+        result.response.resume()
+        if (attempt > allowed) throw new HttpCallError('HTTP_STATUS', `httpCall: ${safe} answered ${status}`, { status, attempts: attempt, url: safe })
+        wait = retryAfter(result.response.headers['retry-after'])
+        result = null
+      } else {
+        const bytes = await readBody(result.response, maxBytes, safe, attempt)
+        const text = new TextDecoder().decode(bytes)
+        const headersOut = plainHeaders(result.response.headers)
+        let json = null
+        if ((headersOut['content-type'] ?? '').includes('json') && text) {
+          try { json = JSON.parse(text) } catch { json = null }
+        }
+        return { status, ok: status >= 200 && status < 300, headers: headersOut, text, json, attempts: attempt, url: redact(result.url) }
+      }
+    } catch (error) {
+      if (error instanceof HttpCallError) throw error.attempts ? error : Object.assign(error, { attempts: attempt })
+      if (error?.code === PRIVATE || error?.cause?.code === PRIVATE) throw new HttpCallError('UNSAFE_URL', `httpCall: ${safe} resolves to a private or loopback address; pass allowPrivate for internal services`, { attempts: attempt, url: safe })
+      if (options.signal?.aborted) throw new HttpCallError('ABORTED', `httpCall: request to ${safe} was cancelled`, { attempts: attempt, url: safe })
+      const timedOut = error?.name === 'TimeoutError' || error?.name === 'AbortError'
+      if (attempt > allowed) throw new HttpCallError(timedOut ? 'TIMEOUT' : 'NETWORK', `httpCall: ${safe} ${timedOut ? `did not answer within ${timeout} ms` : 'is unreachable'}`, { attempts: attempt, url: safe })
+    }
+    await sleep(wait ?? Math.random() * Math.min(5000, backoff * 2 ** (attempt - 1)))
+  }
+}

package/brain-router.js

@@ -206,25 +206,21 @@ export function router(o = {}) {
       if (!cur.$d && [...cur.querySelectorAll('script[type=module]')].some(sc => /\$d\s*=/.test(sc.textContent))) hold(cur)
       for (const a of next.attributes || []) cur.setAttribute(a.name, a.value)
       if (doc.title) document.title = doc.title
-      for (const s of ['meta[name=description]', 'link[rel=canonical]']) {
-        const a = document.head && document.head.querySelector(s), b = doc.querySelector(s)
-        if (a && b) a.replaceWith(document.adoptNode ? document.adoptNode(b) : b)
-      }
-      // SEO (§32): og:*, twitter:*, robots and JSON-LD follow the page; the region's own tags stay where they are
+      // SEO (§32, S04): the route owns description, og:*, twitter:*, robots, JSON-LD, canonical, hreflang and Markdown
+      // alternates, prev/next and its route params (brain-params, read by route()): the current page's go, the next
+      // page's come (none when it has none). Site links (icons, stylesheets, the RSS feed) and the region's own tags stay.
       const tags = (r, skip) =>
-        [...((r && r.querySelectorAll && r.querySelectorAll('meta,script')) || [])].filter(e => {
+        [...((r && r.querySelectorAll && r.querySelectorAll('meta,script,link')) || [])].filter(e => {
           for (let p = e.parentNode; p; p = p.parentNode) if (p === skip) return false
-          const k = e.getAttribute('property') || e.getAttribute('name') || ''
-          return e.tagName === 'SCRIPT' ? e.getAttribute('type') === 'application/ld+json' : /^(og:|twitter:|robots$)/.test(k)
+          const a = n => e.getAttribute(n) || '', t = e.tagName
+          return t == 'SCRIPT' ? a('type') == 'application/ld+json'
+            : t == 'LINK' ? /^(canonical|prev|next)$/.test(a('rel')) || (a('rel') == 'alternate' && (a('hreflang') || a('type') == 'text/markdown'))
+            : /^(og:|twitter:|robots$|description$|brain-params$)/.test(a('property') || a('name'))
         })
       if (document.head) {
         for (const e of tags(document.head)) e.remove()
         for (const e of tags(doc.head || doc, next)) document.head.appendChild(document.adoptNode ? document.adoptNode(e) : e)
       }
-      // the next page's route params (or none): route() reads them
-      const pa = document.head && document.head.querySelector('meta[name=brain-params]'), pb = doc.querySelector('meta[name=brain-params]')
-      if (pa) pa.remove()
-      if (pb && document.head) document.head.appendChild(document.adoptNode ? document.adoptNode(pb) : pb)
       routed()
       current()
       const oldPlan = document.getElementById('brain-next'), newPlan = doc.querySelector('#brain-next')

package/brain-update.js

@@ -0,0 +1,37 @@
+// BRAINLLM app updates with user control (brain.json `"cache": { "update": "prompt" }`, INTERNALS §35.8).
+// `updateReady()` is a signal read: true once a new build's service worker is installed and waiting while this page is
+// controlled by the previous one. `applyUpdate()` tells that worker to take over (`brain:skip-waiting`) and reloads
+// the page once it controls it. Without a service worker both are inert: false / a resolved promise.
+import { sig } from './brain.js'
+
+const G = globalThis
+let READY = null, reg = null
+function start() {
+  READY = sig(false)
+  const sw = G.navigator?.serviceWorker
+  if (!sw?.getRegistration) return
+  const seen = r => {
+    if (!r || reg === r) return
+    reg = r
+    const mark = () => (READY.v = !!(r.waiting && sw.controller))
+    mark()
+    r.addEventListener?.('updatefound', () => {
+      const n = r.installing
+      n?.addEventListener?.('statechange', () => n.state === 'installed' && mark())
+    })
+  }
+  sw.getRegistration().then(seen, () => {})
+}
+export function updateReady() {
+  if (!READY) start()
+  return READY.v
+}
+// reloads once, when the new worker controls the page; resolves false when there is nothing to apply
+export function applyUpdate() {
+  const sw = G.navigator?.serviceWorker
+  if (!reg?.waiting || !sw) return Promise.resolve(false)
+  return new Promise(ok => {
+    sw.addEventListener('controllerchange', () => (ok(true), G.location?.reload()), { once: true })
+    reg.waiting.postMessage('brain:skip-waiting')
+  })
+}

package/brain-url.js

@@ -15,11 +15,13 @@ function decode(raw, base) {
   else if (Array.isArray(base)) { try { v = JSON.parse(raw) } catch { return base }; if (!Array.isArray(v) || (base.length && v.some(x => typeof x !== typeof base[0]))) return base }
   return encode(v) == null ? base : v
 }
+// `values`: an allowed set; a query value outside it reads as the first allowed value
+const allow = (v, b) => !Array.isArray(b?.values) || !b.values.length || b.values.includes(v) ? v : b.values[0]
 function restore() {
   if (!G.location) return
   const url = new URL(G.location.href)
   for (const [key, b] of bindings) if (b.path === url.pathname) {
-    const value = decode(url.searchParams.get(key), b.base)
+    const value = allow(decode(url.searchParams.get(key), b.base), b)
     b.last = encode(value)
     b.cell.v = value
   }
@@ -37,7 +39,7 @@ G.__brainURLOnly = (from, to) => {
 G.__brainURLRestore = restore
 
 export function urlState(initial, options) {
-  const cell = sig(initial)
+  const cell = sig(allow(initial, options))
   if (!options?.disabled) urlBind(cell, options?.key, options)
   return cell
 }
@@ -78,7 +80,7 @@ export function urlBind(cell, key, options = {}) {
   if (G.__brainRoute || G.__brainSSR) {
     if (typeof key === 'string' && key.length <= 200 && !privateKey.test(key) && encode(untrack(() => cell.v)) != null) {
       const raw = G.__brainRoute?.query?.[key]
-      cell.v = decode(typeof raw === 'string' ? raw : null, untrack(() => cell.v))
+      cell.v = allow(decode(typeof raw === 'string' ? raw : null, untrack(() => cell.v)), options)
     }
     return cell
   }
@@ -97,8 +99,8 @@ export function urlBind(cell, key, options = {}) {
   if (bindings.size >= 128 || known.size >= 512) { report('URL state key capacity exceeded; reduce public state or reuse stable keys'); return cell }
   const base = untrack(() => cell.v), url = new URL(G.location.href)
   if (url.search.length > 8192) { report('URL state exceeds 8 KiB; shorten public selections'); return cell }
-  cell.v = decode(url.searchParams.get(key), base)
-  const b = { cell, base, path: url.pathname, last: encode(cell.v) }
+  cell.v = allow(decode(url.searchParams.get(key), base), options)
+  const b = { cell, base, path: url.pathname, last: encode(cell.v), values: options.values }
   bindings.set(key, b); known.add(key)
   if (!listening) { G.addEventListener('popstate', restore); listening = true }
   fx(() => {

package/brain.js

@@ -131,6 +131,9 @@ class N {
   }
 }
 
+// Owners first (guard-first, as Solid and Svelte): an {#if} re-evaluates its condition, and disposes its block, before
+// an effect inside the block runs, even when the inner effect was queued first.
+const up = n => (n.p && up(n.p), n.u())
 function flush() {
   P = 0
   B++
@@ -147,7 +150,7 @@ function flush() {
           continue
         }
       }
-      n.u()
+      up(n)
     }
   } finally {
     Q = []
@@ -209,7 +212,7 @@ export const _err = h => ((E = h), _rt())
 const mk = p => p.appendChild(document.createComment(''))
 // Yield to the browser: scheduler.yield (Chrome 129+), else a MessageChannel task (no 4 ms setTimeout clamp)
 const later = f => {
-  if (globalThis.scheduler && scheduler.yield) return scheduler.yield().then(f)
+  if (globalThis.scheduler?.yield) return scheduler.yield().then(f)
   const c = new MessageChannel()
   c.port1.onmessage = () => (c.port1.close(), f())
   c.port2.postMessage(0)
@@ -219,7 +222,7 @@ const rm = a => {
   for (const n of a) n.$out ? n.$out().then(() => n.remove()) : n.remove()
 }
 function nodes(v, a = []) {
-  if (v == null || v === true || v === false) return a
+  if (v == null || v === !!v) return a // null, undefined, true, false
   if (Array.isArray(v)) for (const x of v) nodes(x, a)
   else if (typeof v == 'function') nodes(v(), a)
   else if (v.nodeType == 11) a.push(...v.childNodes)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@christianirack/brainllm-runtime",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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": {