@christianirack/brainllm-runtime 0.3.1 → 0.5.0

package/brain-form.js

@@ -15,7 +15,7 @@
 // Unsaved changes (§41.5): `f.dirty` is true while values differ from the last saved ones (init, reset() or a successful
 // submit); leaving the page (client navigation or closing the tab) then asks first. No API.
 import { sig, fx, batch, untrack, _rt } from './brain.js'
-import { rule, check, msg } from './brain-schema.js'
+import { rule, check, checkText, checkScalar, msg } from './brain-schema.js'
 
 export { rule, check } // server.mjs validates posted forms with the same rules (§38)
 
@@ -41,9 +41,18 @@ if (globalThis.addEventListener && !globalThis.__brainDirtyHook) {
     for (const f of DIRTY) if (f.dirty && !f.busy) return void (e.preventDefault(), (e.returnValue = ''))
   })
 }
-const empty = v => v == null || v === '' || (Array.isArray(v) && !v.length)
+const empty = v => v == null || typeof v === 'string' && v.trim() === '' || Array.isArray(v) && !v.length
 const init0 = r => (r.list ? [] : r.t === 'bool' ? false : '')
-const out = (r, v) => (r.list ? v || [] : r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v)
+const out = (r, v) => {
+  if (r.list) {
+    if (!Array.isArray(v)) return []
+    if (r.t !== 'num') return v
+    const numbers = new Array(v.length)
+    for (let i = 0; i < v.length; i++) numbers[i] = Number(v[i])
+    return numbers
+  }
+  return r.t === 'num' ? (empty(v) ? null : Number(v)) : r.t === 'bool' ? !!v : v
+}
 
 // state left by the server: globalThis.__brainForms while it renders, or the page's #brain-forms JSON
 let SEEN
@@ -62,6 +71,46 @@ function posted(id) {
 }
 
 export function form(schema, o = {}) {
+  if (rule(schema).t !== 'obj') throw Error('form: schema must be a nested field object')
+  return createForm(schema, o, rule, check, remoteCheck)
+}
+// Compiler-only flat literal schema bytecode. Dynamic/public form() keeps the full parser.
+export function formStatic(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, remoteCheck)
+}
+export function formScalars(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, remoteCheck)
+}
+// Compiler-only options proven not to configure or dynamically install async checks.
+export function formStaticSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email'], checkText, null)
+}
+export function formScalarsSync(schema, o = {}) {
+  return compiledForm(schema, o, ['str', 'email', 'bool', 'num'], checkScalar, null)
+}
+function compiledForm(schema, o, types, validate, remote) {
+  if (remote === null && ('check' in o || 'validate' in o)) throw Error('form: invalid compiled synchronous options')
+  if (!schema || Object.getPrototypeOf(schema) !== Object.prototype || Object.keys(schema).length > 4096) throw Error('form: invalid compiled schema')
+  return createForm(schema, o, (value, key) => {
+    if (['__proto__', 'prototype', 'constructor'].includes(key) || !Array.isArray(value) || value.length !== 2 || !types.includes(value[0]) || typeof value[1] !== 'boolean') throw Error('form: invalid compiled schema')
+    return { t: value[0], req: value[1], list: false, min: null, max: null }
+  }, validate, remote)
+}
+// Only public/dynamic or check-configured forms retain this optional capability.
+function remoteCheck(o, x, checking) {
+  const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
+  if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
+  checking.v++
+  return Promise.resolve()
+    .then(() => c(v))
+    .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || msg('form.check_failed', 'Could not check this value.')))
+    .then(m => {
+      if (untrack(() => x.s.v) === v) x.e.v = m
+      return untrack(() => x.e.v)
+    })
+    .finally(() => checking.v--)
+}
+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 checking = sig(0), saved = sig('') // async checks running · JSON of the last saved values
@@ -72,7 +121,7 @@ export function form(schema, o = {}) {
   function build(sch, base, init) {
     const v = {}, err = {}
     for (const k of Object.keys(sch)) {
-      const r = rule(sch[k]), path = base ? base + '.' + k : k
+      const r = readRule(sch[k], k), path = base ? base + '.' + k : k
       if (r.t === 'obj') {
         const sub = build(r.s, path, (init && init[k]) || {})
         Object.defineProperty(v, k, { enumerable: true, value: sub.v })
@@ -115,23 +164,9 @@ export function form(schema, o = {}) {
   const touch = x => {
     validate(x)
     if (!x.touched) (x.touched = true), shown.v++
-    remote(x)
-  }
-  // async check of one field (only when its own rule passes); resolves to its message
-  const remote = x => {
-    const c = o.check && o.check[x.path], v = untrack(() => x.s.v)
-    if (!c || untrack(() => x.e.v)) return Promise.resolve(untrack(() => x.e.v))
-    checking.v++
-    return Promise.resolve()
-      .then(() => c(v))
-      .then(m => m || '', e => (e && e.kind === 'aborted' ? '' : (e && e.message) || msg('form.check_failed', 'Could not check this value.')))
-      .then(m => {
-        if (untrack(() => x.s.v) === v) x.e.v = m // a stale answer (the value changed meanwhile) is ignored
-        return untrack(() => x.e.v)
-      })
-      .finally(() => checking.v--)
+    if (remote) remote(o, x, checking)
   }
-  const validate = x => (x.e.v = untrack(() => check(x.r, x.s.v)))
+  const validate = x => (x.e.v = untrack(() => validateRule(x.r, x.s.v)))
   const fid = p => `${id}-${p.replace(/\./g, '-')}-err`
 
   // A form posted without JS (§38) comes back from the server with its values and messages: start from them, already
@@ -196,7 +231,7 @@ export function form(schema, o = {}) {
       return checking.v > 0
     },
     get ok() {
-      for (const x of F) if (check(x.r, x.s.v)) return false
+      for (const x of F) if (validateRule(x.r, x.s.v)) return false
       return true
     },
     id: path => fid(path),
@@ -244,8 +279,8 @@ export function form(schema, o = {}) {
       busy.v = true
       if (fm) fm.setAttribute('aria-busy', 'true') // assistive tech hears the form is working
       try {
-        if (o.check) {
-          await Promise.all(F.map(remote))
+        if (remote && o.check) {
+          await Promise.all(F.map(x => remote(o, x, checking)))
           first = F.find(x => untrack(() => x.e.v))
           if (first) return void (shown.v++, first.el && first.el.focus && first.el.focus())
         }

package/brain-hash.js

@@ -0,0 +1,17 @@
+// Web Crypto owns cryptography in browsers and Node. No hashing implementation is bundled.
+export async function hashText(value, algorithm = 'SHA-256') {
+  if (!['SHA-256', 'SHA-384', 'SHA-512'].includes(algorithm)) throw RangeError('hashText: SHA-256, SHA-384 or SHA-512 required')
+  if (typeof value !== 'string') throw TypeError('hashText: text input required')
+  if (value.length > 8388608) throw RangeError('hashText: input exceeds 8 MiB')
+  const bytes = new TextEncoder().encode(value)
+  if (bytes.byteLength > 8388608) throw RangeError('hashText: UTF-8 input exceeds 8 MiB')
+  if (!globalThis.crypto?.subtle) throw Error('hashText: Web Crypto requires a secure browser context or Node 22+')
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest(algorithm, bytes))
+  let hex = ''
+  for (let i = 0; i < digest.length; i++) hex += digest[i].toString(16).padStart(2, '0')
+  return hex
+}
+export async function shortHash(value, length = 32) {
+  if (!Number.isInteger(length) || length < 8 || length > 64) throw RangeError('shortHash: length must be 8..64 hex characters')
+  return (await hashText(value)).slice(0, length)
+}

package/brain-inspect.js

@@ -16,8 +16,8 @@ const now = () => Date.now()
 const pnow = () => (G.performance ? performance.now() : now())
 const syncHeap = () => (G.performance && performance.memory ? performance.memory.usedJSHeapSize : G.process && process.memoryUsage ? process.memoryUsage().heapUsed : null)
 
-let out = [], seq = 0, opts = {}, started = false
-const push = r => out.push(r)
+let out = [], seq = 0, opts = {}, started = false, dropped = 0
+const push = r => { if (out.length >= 2000) { out.shift(); dropped++ } out.push(r) }
 
 // ---------- instance identity and current owner ----------
 const ids = new WeakMap()
@@ -612,6 +612,8 @@ export function tick() {
 export function drain() {
   if (!out.length) return null
   const m = { t: 'm', v: 2, seq: seq++, at: now(), d: out }
+  if (dropped) m.dropped = dropped
+  dropped = 0
   out = []
   if (opts.send) opts.send(JSON.stringify(m))
   return m
@@ -629,7 +631,7 @@ export function inspect(o) {
       else i = instOf(x)
       if (!i) return null
       const chain = []
-      for (let j = i; j; j = instOf(j.p)) chain.push(nameOf(j))
+      for (let j = i; j && chain.length < 33; j = instOf(j.p)) chain.push(nameOf(j))
       return { id: idOf(i), h: i.h, name: nameOf(i), file: (i.C && (i.C.f || (i.C.C && i.C.C.f))) || null, chain }
     },
     sigName,
@@ -643,7 +645,7 @@ export function inspect(o) {
     if (done) done.add(key)
     push({ k: 'chan', kind, name, role, id: i ? idOf(i) : null, h: i ? i.h : null, comp: i ? nameOf(i) : null })
   })
-  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, crumbs: r.crumbs, n: r.n, at: r.last }))
+  sub.add(r => push({ k: 'err', fp: r.fp, code: r.code, msg: r.msg, where: r.where, comp: r.comp, line: r.line, src: r.src || null, stack: r.brainStack || r.stack, brainStack: r.brainStack || null, location: r.location, generatedLocation: r.generatedLocation, frames: r.frames, causes: r.causes, truncated: r.truncated, mapping: r.mapping, crumbs: r.crumbs, n: r.n, at: r.last }))
   patchTimers()
   patchGlobalListeners()
   patchHandlers()

package/brain-interop.js

@@ -0,0 +1,50 @@
+// Explicit foreign-DOM ownership. The adapter, SDK and any React runtime belong to the app.
+import { _rt, fx, untrack } from './brain.js'
+
+const I = _rt()
+
+// Call during component setup. Resolve the bound element only after insertion.
+// mount must synchronously return a cleanup function or { update?, destroy }.
+export function interop(element, adapter, props = {}, options = {}) {
+  const owner = I.owner()
+  if (!owner) throw Error('interop: call during component setup')
+  let alive = true, instance = null, pending = props, ready = false
+  const report = (error, phase) => {
+    if (typeof options.onError === 'function') options.onError(error, phase)
+    else I.oops(error, owner, 'interop:' + phase)
+  }
+  const destroy = () => {
+    if (!alive) return
+    alive = false
+    const old = instance
+    instance = null
+    if (old) try { old.destroy() } catch (error) { report(error, 'destroy') }
+  }
+  const controller = {
+    update(next) {
+      if (!alive) throw Error('interop: boundary has been destroyed')
+      pending = next
+      if (!ready) return
+      if (!instance || typeof instance.update !== 'function') throw Error('interop: adapter does not support updates')
+      try { untrack(() => instance.update(next)) } catch (error) { report(error, 'update') }
+    },
+    destroy,
+  }
+  // No SDK execution during SSR or prerender. Disposal still invalidates this controller.
+  fx(() => destroy)
+  if (globalThis.__brainSSR || globalThis.__brainRoute) return controller
+  queueMicrotask(() => {
+    if (!alive) return
+    try {
+      const el = typeof element === 'function' ? untrack(element) : element
+      if (!el || el.nodeType !== 1) throw Error('interop: expected a bound DOM element')
+      if (!adapter || typeof adapter.mount !== 'function') throw Error('interop: adapter.mount is required')
+      const result = untrack(() => adapter.mount(el, pending))
+      if (typeof result === 'function') instance = { destroy: result }
+      else if (result && typeof result.destroy === 'function' && typeof result.then !== 'function') instance = result
+      else throw Error('interop: mount must return cleanup or { update, destroy }; asynchronous mounts are unsupported')
+      ready = true
+    } catch (error) { report(error, 'mount') }
+  })
+  return controller
+}

package/brain-live.js

@@ -0,0 +1,364 @@
+// Native, same-origin invalidation metadata. HTTP resource reads remain authoritative.
+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
+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'])
+let broker
+const fault = fix => Object.assign(Error('B0918: ' + fix), { code: 'B0918', fix })
+const fail = fix => { throw fault(fix) }
+const exact = (value, keys) => value && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).every(key => keys.includes(key))
+const resourceName = name => typeof name === 'string' && /^[a-z][a-z0-9_]{0,47}$/.test(name) && !RESERVED.has(name)
+
+function roomsOf(value) {
+  if (!Array.isArray(value) || value.length > MAX_ROOMS) fail('Use at most 32 native resource rooms')
+  const rooms = new Map()
+  for (const room of value) {
+    let command, key
+    const id = room && typeof room === 'object' && own(room, 'id') ? room.id : undefined
+    if (exact(room, ['room']) && own(room, 'room') && room.room === 'user:self') {
+      command = { room: 'user:self' }; key = 'user:self'
+    } else if (exact(room, ['resource', 'id']) && own(room, 'resource') && resourceName(room.resource) && (id === undefined || (typeof id === 'string' && UUID.test(id)))) {
+      command = id === undefined ? { resource: room.resource } : { resource: room.resource, id: id.toLowerCase() }
+      key = command.resource + ':' + (command.id || '')
+    } else fail('Use a declared resource, an optional UUID, or the user:self room')
+    rooms.set(key, Object.freeze(command))
+  }
+  return rooms
+}
+
+function endpoint() {
+  const location = G.location
+  if (!location || !/^https?:$/.test(location.protocol)) fail('Serve live resources from an HTTP(S) application origin')
+  const meta = G.document && document.querySelector('meta[name=brain-base]')
+  const base = meta && meta.getAttribute('content') || ''
+  if (typeof base !== 'string' || base.length > 512 || (base && (!base.startsWith('/') || base.startsWith('//') || /[\\?#\x00-\x20\x7f]/.test(base)))) fail('Use a normalized same-origin application base path')
+  const origin = new URL(location.origin)
+  if (origin.origin !== location.origin || origin.username || origin.password) fail('Use a canonical application origin')
+  const normalized = base.replace(/\/$/, '')
+  const url = new URL(normalized + '/_brain/socket', origin)
+  if (url.origin !== origin.origin || url.pathname !== normalized + '/_brain/socket') fail('Use a normalized same-origin application base path')
+  url.protocol = origin.protocol === 'https:' ? 'wss:' : 'ws:'
+  return url.href
+}
+
+function metadata(text) {
+  if (typeof text !== 'string' || text.length > FRAME || /[^\x09\x0a\x0d\x20-\x7e]/.test(text)) return null
+  let value
+  try {
+    value = JSON.parse(text, (key, item) => {
+      if (key === '__proto__' || key === 'constructor' || key === 'prototype') throw Error('Unsafe metadata')
+      return item
+    })
+  } catch { return null }
+  if (exact(value, ['type', 'protocol', 'durable', 'resyncRequired']) && value.type === 'ready' && value.protocol === 1 && value.durable === false && value.resyncRequired === true) return Object.freeze(value)
+  if (exact(value, ['type', 'reason']) && value.type === 'resync' && value.reason === 'joined') return Object.freeze(value)
+  if (exact(value, ['type']) && value.type === 'pong') return Object.freeze(value)
+  if (exact(value, ['type', 'code']) && value.type === 'error' && value.code === 'ROOM_FORBIDDEN') return Object.freeze(value)
+  if (exact(value, ['type', 'resource', 'id', 'operation', 'eventId']) && value.type === 'invalidate' && resourceName(value.resource) && typeof value.id === 'string' && UUID.test(value.id) && typeof value.eventId === 'string' && UUID.test(value.eventId) && ['create', 'update', 'delete'].includes(value.operation)) return Object.freeze(value)
+  return null
+}
+
+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
+
+  const update = () => {
+    for (const member of members) {
+      const active = [...member.rooms.keys()].some(key => joined.get(key) === 'ready')
+      const forbidden = member.rooms.size > 0 && [...member.rooms.keys()].every(key => joined.get(key) === 'forbidden')
+      member.up.v = !!(socket && ready && member.scope && member.scope === scope && active)
+      member.state.v = !member.scope || !member.rooms.size ? 'idle' : terminal || (member.refreshState || (forbidden ? 'forbidden' : member.up.v ? 'open' : retryTimer ? 'retrying' : 'connecting'))
+    }
+  }
+  const clearMember = member => {
+    member.generation++
+    member.dirty = false
+    member.pending = member.resync = null
+    member.refreshState = member.flight ? 'refresh-pending' : ''
+    if (member.flight) {
+      const flight = member.flight
+      clearTimeout(flight.deadline); clearTimeout(flight.tick)
+      flight.deadline = flight.tick = null
+      if (flight.resolveTick) { flight.resolveTick(); flight.resolveTick = null }
+    }
+  }
+  const stop = () => {
+    epoch++; ready = false
+    clearTimeout(retryTimer); retryTimer = null
+    clearTimeout(readyTimer); clearInterval(heartbeat); clearTimeout(pongTimer)
+    readyTimer = heartbeat = pongTimer = null
+    clearTimeout(flushTimer); flushTimer = null
+    joined.clear(); waiting.length = 0; events.clear(); currentRooms.clear()
+    const previous = socket; socket = null
+    if (previous) {
+      previous.onopen = previous.onmessage = previous.onclose = previous.onerror = null
+      try { previous.close(1000, 'Live resource lifecycle ended') } catch {}
+    }
+    for (const member of members) { clearMember(member); member.up.v = false }
+  }
+  const reject = state => { stop(); terminal = state; update() }
+  const send = value => {
+    if (!socket || socket.readyState !== 1 || socket.bufferedAmount > BUFFER) return false
+    const text = JSON.stringify(value)
+    if (text.length > FRAME) return false
+    try { socket.send(text); return true } catch { return false }
+  }
+  const refresh = member => {
+    if (!members.has(member) || !member.up.v || !member.dirty || member.flight) return
+    member.dirty = false; member.refreshState = ''; update()
+    const pending = member.pending, resync = member.resync
+    member.pending = member.resync = null
+    const flight = { generation: member.generation, epoch, deadline: null, tick: null, resolveTick: null }
+    member.flight = flight
+    flight.deadline = setTimeout(timeoutFlight.bind(null, member.cell, flight), REFRESH_MS)
+    try {
+      if (resync && own(member.options, 'onResync') && member.options.onResync) observeMetadata(member.options.onResync, resync)
+      if (pending && own(member.options, 'onInvalidate') && member.options.onInvalidate) observeMetadata(member.options.onInvalidate, pending)
+      untrack(() => member.node.refetch())
+      // Equivalent post-effect tick, with an owned cancellation handle. The
+      // standard tick() intentionally exposes no handle for owner cancellation.
+      const next = new Promise(resolve => {
+        flight.resolveTick = resolve
+        flight.tick = setTimeout(resolve, 0)
+      })
+      next.then(readResource.bind(null, member.cell, flight)).then(
+        settleFlight.bind(null, member.cell, flight, false),
+        settleFlight.bind(null, member.cell, flight, true),
+      )
+    } catch {
+      I.oops(fault('Keep live metadata observers synchronous and handle resource failures in the view'), member.owner, 'B0918')
+      dispose(member.cell)
+    }
+  }
+  const valid = (member, flight) => members.has(member) && member.generation === flight.generation && epoch === flight.epoch
+  function complete(member, flight, failed) {
+    if (member.flight !== flight) return
+    clearTimeout(flight.deadline); clearTimeout(flight.tick)
+    flight.deadline = flight.tick = flight.resolveTick = null
+    member.flight = null; member.refreshState = ''
+    if (valid(member, flight) && failed) member.refreshState = 'refresh-error'
+    if (members.has(member) && member.dirty) schedule()
+    if (members.has(member)) update()
+  }
+  function schedule() {
+    if (!flushTimer) flushTimer = setTimeout(() => {
+      flushTimer = null
+      for (const member of members) refresh(member)
+    }, COALESCE)
+  }
+  const invalidate = (value, roomKey) => {
+    for (const member of members) {
+      if (!member.scope || member.scope !== scope) continue
+      const interested = roomKey ? member.rooms.has(roomKey) : [...member.rooms].some(([key, room]) => joined.get(key) === 'ready' && (room.room === 'user:self' || (room.resource === value.resource && (!room.id || room.id === value.id))))
+      if (interested) { member.dirty = true; if (value.type === 'resync') member.resync = value; else member.pending = value; schedule() }
+    }
+  }
+  const retry = () => {
+    stop()
+    if (++attempts > 5 || (retryStart && Date.now() - retryStart >= RETRY_MS)) { terminal = 'exhausted'; update(); return }
+    if (!retryStart) retryStart = Date.now()
+    const delay = Math.floor(Math.min(8000, 250 * 2 ** (attempts - 1)) * (0.75 + Math.random() * 0.25))
+    retryTimer = setTimeout(() => { retryTimer = null; reconcile() }, delay)
+    update()
+  }
+  const desired = () => {
+    const rooms = new Map(), scopes = new Set()
+    for (const member of members) if (member.scope && member.rooms.size) {
+      scopes.add(member.scope)
+      for (const [key, value] of member.rooms) rooms.set(key, value)
+    }
+    return { rooms, scopes }
+  }
+  const syncRooms = rooms => {
+    const changed = [...rooms.keys()].some(key => !joined.has(key)) || [...joined.keys()].some(key => !rooms.has(key))
+    if (waiting.length && changed) { retry(); return }
+    for (const [key] of joined) if (!rooms.has(key)) {
+      const room = currentRooms.get(key)
+      if (!room || !send({ type: 'leave', ...room })) { retry(); return }
+      joined.delete(key)
+    }
+    currentRooms = rooms
+    for (const [key, room] of rooms) if (!joined.has(key)) {
+      if (waiting.length >= MAX_ROOMS || !send({ type: 'join', ...room })) { retry(); return }
+      joined.set(key, 'pending'); waiting.push(key)
+    }
+    update()
+  }
+  let currentRooms = new Map()
+  const connect = () => {
+    const captured = ++epoch
+    lastConnect = Date.now()
+    let address
+    try { address = endpoint() } catch { reject('invalid-config'); return }
+    try { socket = new G.WebSocket(address, 'brain.v1') } catch { retry(); return }
+    readyTimer = setTimeout(() => { if (epoch === captured) retry() }, READY_MS)
+    socket.onopen = () => {
+      if (epoch !== captured) return
+      if (socket.protocol !== 'brain.v1') reject('protocol-error')
+    }
+    socket.onerror = () => { /* close or the ready deadline owns retries; arbitrary browser errors are not retained. */ }
+    socket.onclose = event => {
+      if (epoch !== captured) return
+      if (event.code === 1008) reject(event.reason === 'Authentication expired' ? 'auth-required' : 'policy-closed')
+      else retry()
+    }
+    socket.onmessage = event => {
+      if (epoch !== captured) return
+      const value = metadata(event.data)
+      if (!value) { reject('protocol-error'); return }
+      if (value.type === 'ready') {
+        if (ready) { reject('protocol-error'); return }
+        clearTimeout(readyTimer); readyTimer = null; ready = true
+        syncRooms(desired().rooms)
+        heartbeat = setInterval(() => {
+          if (!send({ type: 'ping' })) { retry(); return }
+          clearTimeout(pongTimer)
+          pongTimer = setTimeout(() => { if (epoch === captured) retry() }, 12000)
+        }, 25000)
+      } else if (!ready) reject('protocol-error')
+      else if (value.type === 'pong') { clearTimeout(pongTimer); pongTimer = null }
+      else if (value.type === 'resync' || value.type === 'error') {
+        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 }
+        update()
+        if (value.type === 'resync') invalidate(value, key)
+      } else {
+        const now = Date.now()
+        for (const [id, time] of events) if (now - time > 60000) events.delete(id)
+        if (events.has(value.eventId)) return
+        events.set(value.eventId, now)
+        while (events.size > 128) events.delete(events.keys().next().value)
+        invalidate(value)
+      }
+    }
+    update()
+  }
+  function reconcile() {
+    reconcileQueued = false
+    const { rooms, scopes } = desired()
+    if (!rooms.size) { stop(); scope = null; terminal = ''; attempts = 0; retryStart = 0; update(); return }
+    if (scopes.size !== 1) { reject('scope-conflict'); return }
+    const next = scopes.values().next().value
+    if (next !== scope || terminal === 'scope-conflict') { stop(); scope = next; terminal = ''; attempts = 0; retryStart = 0 }
+    if (rooms.size > MAX_ROOMS) { reject('room-limit'); return }
+    if (terminal || retryTimer) { update(); return }
+    if (socket && ready) syncRooms(rooms)
+    else if (!socket) {
+      const elapsed = Date.now() - lastConnect
+      const delay = elapsed < 0 ? 0 : Math.max(0, 250 - elapsed)
+      if (delay) retryTimer = setTimeout(() => { retryTimer = null; reconcile() }, delay)
+      else connect()
+    }
+    update()
+  }
+  const queue = () => { if (!reconcileQueued) { reconcileQueued = true; queueMicrotask(reconcile) } }
+  return {
+    valid, complete,
+    stats() { return { owners: members.size, rooms: joined.size, pendingJoins: waiting.length, dedupe: events.size, connection: socket ? 1 : 0, timers: [retryTimer, readyTimer, heartbeat, pongTimer, flushTimer].filter(Boolean).length + [...members].filter(member => member.flight && member.flight.deadline).length, refreshes: [...members].filter(member => member.flight).length, dirty: [...members].filter(member => member.dirty).length } },
+    add(member) {
+      if (!members.has(member) && members.size >= MAX_OWNERS) fail('Close unused live resource owners before adding another')
+      members.add(member)
+      if (scope && member.scope && member.scope !== scope) stop()
+      queue()
+    },
+    remove(member) {
+      members.delete(member); clearMember(member); member.up.v = false
+      if (!members.size) { stop(); scope = null; terminal = ''; attempts = 0; retryStart = 0 }
+      else queue()
+    },
+    reconnect(member) {
+      if (!members.has(member)) return
+      stop(); terminal = ''; attempts = 0; retryStart = 0; queue()
+    },
+  }
+}
+
+function observeMetadata(callback, value) {
+  const result = untrack(() => callback(value))
+  if (result && typeof result.then === 'function') {
+    // Observe rejection without retaining an owner or the user-provided error.
+    Promise.resolve(result).catch(() => {})
+    fail('Use synchronous metadata observers; resource owns asynchronous fetching')
+  }
+}
+
+// Promise reactions retain only a nullable cell and scalar flight metadata. An
+// externally retained, never-settling Promise cannot keep a disposed resource alive.
+function readResource(cell, flight) {
+  flight.tick = flight.resolveTick = null
+  const member = cell.record
+  if (member && broker.valid(member, flight)) return member.node.v
+}
+function settleFlight(cell, flight, failed) {
+  const member = cell.record
+  if (member) broker.complete(member, flight, failed)
+}
+function timeoutFlight(cell, flight) {
+  const member = cell.record
+  if (member && broker.valid(member, flight)) {
+    // Never release a pending fetch slot merely because its deadline elapsed.
+    member.refreshState = 'refresh-timeout'
+    member.state.v = 'refresh-timeout'
+  }
+}
+function detach(cell) {
+  const member = cell.record
+  if (member && broker) broker.remove(member)
+}
+function dispose(cell) {
+  const member = cell.record
+  if (!member) return
+  cell.record = null
+  if (member.stopWatch) member.stopWatch()
+  if (broker) broker.remove(member)
+  member.node = member.options = member.owner = member.stopWatch = null
+  member.scope = null; member.rooms.clear(); member.flight = null
+  member.state.v = 'closed'
+}
+function observe(cell) {
+  const member = cell.record
+  if (!member) return
+  const scope = member.options.scope()
+  if (scope !== null && (typeof scope !== 'string' || !scope.length || scope.length > 160 || /[\x00-\x20\x7f]/.test(scope))) fail('Use null or a bounded public user/revision string as scope; never credentials')
+  member.scope = scope
+  member.rooms = roomsOf(typeof member.options.rooms === 'function' ? member.options.rooms() : member.options.rooms)
+  broker = broker || createBroker()
+  broker.add(member)
+  return detach.bind(null, cell)
+}
+function ownerCleanup(cell) { return dispose.bind(null, cell) }
+function reconnect(cell) { if (cell.record && broker) broker.reconnect(cell.record) }
+
+// Internal, metadata-only capacity evidence; never scope identifiers, rooms or values.
+export function _liveStats() {
+  return broker ? broker.stats() : { owners: 0, rooms: 0, pendingJoins: 0, dedupe: 0, connection: 0, timers: 0, refreshes: 0, dirty: 0 }
+}
+
+export function liveResource(node, options = {}) {
+  if (!node || typeof node !== 'object' || typeof node.refetch !== 'function' || !('v' in node) || !exact(options, ['rooms', 'scope', 'onInvalidate', 'onResync']) || !own(options, 'rooms') || !own(options, 'scope') || typeof options.scope !== 'function') fail('Use liveResource(rows, {rooms, scope: () => publicUserRevision}) with a resource handle')
+  if (own(options, 'onInvalidate') && options.onInvalidate !== undefined && typeof options.onInvalidate !== 'function') fail('Use a metadata callback for onInvalidate')
+  if (own(options, 'onResync') && options.onResync !== undefined && typeof options.onResync !== 'function') fail('Use a metadata callback for onResync')
+  const state = sig('idle'), up = sig(false), cell = { record: null }
+  const out = {
+    get connected() { return up.v },
+    get state() { return state.v },
+    close() { dispose(cell); up.v = false; state.v = 'closed' },
+    reconnect: reconnect.bind(null, cell),
+  }
+  if (G.__brainSSR || G.__brainRoute) return out
+  if (typeof G.WebSocket !== 'function') { state.v = 'unsupported'; return out }
+  const owner = I.owner()
+  if (!owner) fail('Create liveResource inside a component so unmount closes its subscription')
+  cell.record = { cell, node, options, state, up, owner, scope: null, rooms: new Map(), generation: 0, flight: null, dirty: false, pending: null, resync: null, refreshState: '', stopWatch: null }
+  fx(ownerCleanup.bind(null, cell))
+  cell.record.stopWatch = fx(observe.bind(null, cell))
+  return out
+}

package/brain-overlay.js

@@ -24,10 +24,21 @@ export function forLLM(d) {
     })
   if (d.fix) out.push(`fix: ${d.fix}`)
   if (d.brainStack) out.push('stack:', ...[].concat(d.brainStack))
+  if (d.location || d.frames || d.causes || d.rid) out.push('structured trace (development only):', JSON.stringify(traceOf(d)))
+  if (d.mapping?.status && d.mapping.status !== 'mapped') out.push('Location mapping is incomplete; do not treat generated coordinates as original source coordinates.')
+  out.push('Agent next steps: inspect the exact source revision, apply a focused change, run brain check --json, then reproduce the failing action. Record evidence with brain history and refresh brain quality.')
   if (d.file) out.push('brain check --json:', JSON.stringify((byFile.get(d.file) || [d]).map(({ snippet, ...x }) => x)))
   return out.join('\n')
 }
 
+function traceOf(d) {
+  return { schemaVersion: 1, requestId: d.rid || d.requestId || null, component: d.comp || null,
+    location: d.location || null, generatedLocation: d.generatedLocation || null,
+    mapping: d.mapping || null, truncated: d.truncated || null,
+    frames: Array.isArray(d.frames) ? d.frames.slice(0, 24) : [],
+    causes: Array.isArray(d.causes) ? d.causes.slice(0, 6) : [] }
+}
+
 function item(d, i) {
   const loc = d.file ? `${d.file}:${d.line || ''}${d.col ? ':' + d.col : ''}` : d.src || ''
   const snip = d.snippet && d.snippet.text
@@ -35,6 +46,7 @@ function item(d, i) {
     : ''
   return `<li class="${d.level === 'warning' || d.level === 'info' ? d.level : 'error'}"><p class="t"><b>${esc(d.code || 'Error')}</b> <span>${esc(loc)}</span></p>` +
     `<p>${esc(d.msg)}</p>${snip}${d.fix ? `<p class="fix">fix: ${esc(d.fix)}</p>` : ''}` +
+    `${d.location || d.frames || d.causes ? `<details><summary>Development trace and mapping</summary><pre>${esc(JSON.stringify(traceOf(d), null, 2))}</pre></details>` : ''}` +
     `<button type="button" data-copy="${i}">Copy for the LLM</button></li>`
 }