@christianirack/brainllm-runtime 0.4.0 → 0.5.0

package/brain-ch.js

@@ -60,10 +60,10 @@ const safe = (k, v) => (k === '__proto__' || k === 'constructor' || k === 'proto
 // global instance) and inside `provide(K, store(…))` (one instance per subtree, §41.2). sync: 'tab' (BroadcastChannel) | 'storage'
 // (localStorage + storage event) | 'ws' (WebSocket at `url`, see ws() below). `id` is set by the codegen (channel
 // path); if missing, it is derived from init.
-export function store(init, o = {}, id) {
-  const name = id || o.name || 'store:' + Object.keys(init).join(',')
+// Shared signal/descriptor construction. Compiler-selected plain stores retain the
+// same reset, serialization and inspector contracts without reaching transport code.
+function storeState(init, name, changed) {
   const S = {}, s = {}
-  let last = '' // JSON of the last state sent or received: cuts the echo between tabs
   for (const k of Object.keys(init)) {
     S[k] = sig(init[k], name + '.' + k) // named: dev tools (brain_why, HMR) see `cart.total`
     Object.defineProperty(s, k, {
@@ -80,7 +80,8 @@ export function store(init, o = {}, id) {
   const apply = d => {
     const n = snap()
     for (const k in d) if (k in S) n[k] = d[k]
-    last = JSON.stringify(n) // before the batch: the sync fx runs when it closes and must see the echo
+    const encoded = JSON.stringify(n) // Preserve serialization errors and toJSON effects, even without sync.
+    if (changed) changed(encoded) // Before the batch: a sync effect must see the new echo marker.
     batch(() => {
       for (const k in n) S[k].v = n[k]
     })
@@ -90,6 +91,19 @@ export function store(init, o = {}, id) {
     $snap: { value: snap },
     $reset: { value: () => apply({ ...init }) }, // back to the initial state (persisted and synced like any write)
   })
+  return { S, s, snap, apply }
+}
+// Compiler-only: public store() still accepts all options and retains its full fallback.
+export function plainStore(init, id) {
+  const name = id || 'store:' + Object.keys(init).join(',')
+  const state = storeState(init, name, null)
+  JSON.stringify(state.snap()) // The public plain path performs this validation too.
+  return state.s
+}
+export function store(init, o = {}, id) {
+  const name = id || o.name || 'store:' + Object.keys(init).join(',')
+  let last = '' // JSON of the last state sent or received: cuts the echo between tabs
+  const { S, s, snap, apply } = storeState(init, name, value => { last = value })
   const K = 'brain:' + name
   if (o.persist) {
     // Persistence (INTERNALS §35.4), versioned by the shape of init. Small states live in localStorage and are restored

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/package.json

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

package/server/native-sockets.mjs

@@ -0,0 +1,156 @@
+// Fixed loopback Upgrade transport. Rust owns WebSocket frames, authentication and per-delivery policy.
+import {request} from 'node:http'
+import {createHash, randomUUID} from 'node:crypto'
+
+const PROTOCOL = 'brain.v1'
+const LIMITS = Object.freeze({connections:32, headers:16384, credentials:16384, head:4096, upstreamHead:8192, queued:262144, bytes:64*1024*1024, handshake:5000, write:2000, idle:70000, lifetime:15*60*1000, close:1000})
+const SINGLE = new Set(['host','origin','authorization','cookie','upgrade','sec-websocket-key','sec-websocket-version','sec-websocket-protocol'])
+const installed = new WeakSet()
+const connectionUpgrade = value => typeof value === 'string' && value.toLowerCase().split(/\s*,\s*/).includes('upgrade')
+const unique = (headers, names) => {
+  const seen = new Set()
+  for (let i=0;i<headers.length;i+=2) {
+    const name = headers[i].toLowerCase()
+    if (names.has(name) && seen.has(name)) return false
+    seen.add(name)
+  }
+  return true
+}
+
+export function installNativeSockets(server, {target, base='/', cookie, log}) {
+  if (installed.has(server)) throw Error('The native socket bridge is already installed')
+  if (typeof target !== 'string' || target.length>2048) throw Error('Native sockets require a fixed loopback HTTP backend')
+  let origin
+  try { origin = new URL(target) } catch { throw Error('Native sockets require a fixed loopback HTTP backend') }
+  if (origin.protocol !== 'http:' || !['127.0.0.1','localhost','[::1]'].includes(origin.hostname) || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) throw Error('Native sockets require a fixed loopback HTTP backend')
+  if (origin.hostname === 'localhost') origin.hostname = '127.0.0.1'
+  if (typeof base !== 'string' || base.length>2048 || !base.startsWith('/') || !base.endsWith('/') || /[\\?#\s]/.test(base) || base.includes('//') || new URL(base,'http://brain.invalid').pathname !== base) throw Error('Native sockets require a canonical application base path')
+  if (typeof cookie !== 'function' || typeof log !== 'function') throw Error('Native socket bridge callbacks are required')
+  const path = (base === '/' ? '' : base.slice(0,-1)) + '/_brain/socket'
+  const owned = new Set()
+  let stopped = false, window = 0, reports = 0
+  // Fixed fields only: never log target URLs, credentials, frames, request headers or exception messages.
+  const report = (code,rid) => {
+    const current = Math.floor(Date.now()/60000)
+    if (window !== current) { window=current; reports=0 }
+    if (reports++ >= 16) return
+    try { log('warn','native socket unavailable',{code,rid,fix:'Check native socket activation, the trusted Origin, authentication and backend availability; reconnect after correcting the cause'}) } catch {}
+  }
+  const reject = (socket,status,rid,code) => {
+    report(code,rid)
+    if (socket.destroyed) return
+    socket.setTimeout(LIMITS.close,()=>socket.destroy())
+    socket.end(`HTTP/1.1 ${status} Socket unavailable\r\nConnection: close\r\nCache-Control: no-store\r\nX-Request-Id: ${rid}\r\nContent-Length: 0\r\n\r\n`,()=>socket.destroy())
+  }
+  const upgrade = (incoming,browser,head) => {
+    const ownedPath=typeof incoming.url === 'string' && incoming.url.split(/[?#]/,1)[0] === path
+    // Other trusted listeners own their endpoints. If this is the only listener, reject unknown upgrades promptly
+    // instead of retaining a raw socket with no owner. Queries on our exact endpoint always remain ours to reject.
+    if (!ownedPath && server.listenerCount('upgrade')>1) return
+    if (browser.destroyed) return
+    const rid = randomUUID()
+    // A socket error can precede admission, including while a rejected response is flushing.
+    browser.on('error',()=>{})
+    if (stopped || server.draining) return reject(browser,503,rid,'NATIVE_SOCKET_DRAINING')
+    if (incoming.method !== 'GET') return reject(browser,405,rid,'NATIVE_SOCKET_METHOD')
+    if (incoming.url !== path) return reject(browser,400,rid,'NATIVE_SOCKET_PATH')
+    const headerBytes = incoming.rawHeaders.reduce((bytes,value)=>bytes+Buffer.byteLength(value)+2,0)
+    if (headerBytes>LIMITS.headers || !unique(incoming.rawHeaders,SINGLE)) return reject(browser,431,rid,'NATIVE_SOCKET_HEADERS')
+    if (head.length>LIMITS.head || incoming.headers['content-length'] && incoming.headers['content-length'] !== '0' || incoming.headers['transfer-encoding']) return reject(browser,400,rid,'NATIVE_SOCKET_BODY')
+    let site
+    try { site=new URL(incoming.headers.origin) } catch { return reject(browser,403,rid,'NATIVE_SOCKET_ORIGIN') }
+    if (!['http:','https:'].includes(site.protocol) || site.origin !== incoming.headers.origin || site.origin.length>2048) return reject(browser,403,rid,'NATIVE_SOCKET_ORIGIN')
+    const key = incoming.headers['sec-websocket-key']
+    if (incoming.headers.upgrade?.toLowerCase() !== 'websocket' || !connectionUpgrade(incoming.headers.connection) || incoming.headers['sec-websocket-version'] !== '13' || incoming.headers['sec-websocket-protocol'] !== PROTOCOL || typeof key !== 'string' || !/^[A-Za-z0-9+/]{22}==$/.test(key) || Buffer.from(key,'base64').toString('base64') !== key) return reject(browser,400,rid,'NATIVE_SOCKET_HANDSHAKE')
+    let credentials
+    try { credentials=cookie(incoming) } catch { return reject(browser,400,rid,'NATIVE_SOCKET_CREDENTIALS') }
+    const authorization = incoming.headers.authorization
+    if (typeof credentials !== 'string' || authorization !== undefined && typeof authorization !== 'string' || Buffer.byteLength(credentials)+Buffer.byteLength(authorization || '')>LIMITS.credentials) return reject(browser,431,rid,'NATIVE_SOCKET_CREDENTIALS')
+    if (owned.size>=LIMITS.connections) return reject(browser,503,rid,'NATIVE_SOCKET_CAPACITY')
+    browser.pause()
+    let outgoing, upstream, handshake, lifetime, closing, bytes=0, done=false, upgraded=false
+    const writes=new Set()
+    const finish = (code,status) => {
+      if (done) return
+      done=true
+      clearTimeout(handshake); clearTimeout(lifetime); clearTimeout(closing); owned.delete(finish)
+      for (const timer of writes) clearTimeout(timer)
+      writes.clear()
+      browser.setTimeout(0)
+      if (upstream) { upstream.setTimeout(0); browser.unpipe(upstream); upstream.unpipe(browser); upstream.destroy() }
+      outgoing?.destroy()
+      if (status && !upgraded) reject(browser,status,rid,code)
+      else { if (code) report(code,rid); browser.destroy() }
+    }
+    const relay = (source,destination) => {
+      let blocked
+      destination.on('drain',()=>{if(blocked){clearTimeout(blocked);writes.delete(blocked);blocked=undefined}})
+      source.on('data',chunk=>{
+        bytes+=chunk.length
+        if (bytes>LIMITS.bytes || destination.writableLength+chunk.length>LIMITS.queued) finish('NATIVE_SOCKET_WRITE_BUDGET')
+      })
+      source.once('end',()=>{
+        if (done) return
+        closing ??= setTimeout(()=>finish('NATIVE_SOCKET_HALF_CLOSE'),LIMITS.close)
+        closing.unref?.()
+        destination.once('finish',()=>finish())
+      })
+      // Native pipe honors write(false)/drain. highWaterMark alone is a threshold, so the explicit queued cap above
+      // also stops a future/custom stream chunk that exceeds the admitted write budget.
+      source.pipe(destination)
+      // Observe after pipe's synchronous write so an unresponsive destination cannot retain its bounded queue
+      // until the much longer idle/lifetime limits. There is at most one stalled-write timer per direction.
+      source.on('data',()=>{
+        if (!done && destination.writableNeedDrain && !blocked) {
+          blocked=setTimeout(()=>finish('NATIVE_SOCKET_WRITE_TIMEOUT'),LIMITS.write)
+          blocked.unref?.();writes.add(blocked)
+        }
+      })
+    }
+    owned.add(finish)
+    browser.once('error',()=>finish('NATIVE_SOCKET_CLIENT_ERROR'))
+    browser.once('close',()=>finish())
+    browser.setTimeout(LIMITS.idle,()=>finish('NATIVE_SOCKET_IDLE'))
+    handshake=setTimeout(()=>finish('NATIVE_SOCKET_HANDSHAKE_TIMEOUT',504),LIMITS.handshake)
+    handshake.unref?.()
+    try {
+      outgoing=request(new URL('/_brain/socket',origin),{
+        method:'GET',agent:false,maxHeaderSize:8192,
+        headers:{host:origin.host,origin:site.origin,connection:'Upgrade',upgrade:'websocket','sec-websocket-version':'13','sec-websocket-key':key,'sec-websocket-protocol':PROTOCOL,'x-request-id':rid,...(credentials ? {cookie:credentials} : {}),...(authorization !== undefined ? {authorization} : {})},
+      })
+      outgoing.once('error',()=>finish('NATIVE_SOCKET_UPSTREAM_UNAVAILABLE',502))
+      outgoing.once('response',response=>{
+        response.destroy()
+        finish('NATIVE_SOCKET_UPSTREAM_REJECTED',[400,401,403,404,429,503].includes(response.statusCode) ? response.statusCode : 502)
+      })
+      outgoing.once('upgrade',(response,socket,buffered)=>{
+        if (done) { socket.destroy(); return }
+        upstream=socket
+        socket.on('error',()=>finish('NATIVE_SOCKET_UPSTREAM_ERROR'))
+        socket.once('close',()=>finish())
+        const expected=createHash('sha1').update(key+'258EAFA5-E914-47DA-95CA-C5AB0DC85B11').digest('base64')
+        if (response.statusCode !== 101 || !unique(response.rawHeaders,new Set(['upgrade','sec-websocket-accept','sec-websocket-protocol'])) || response.headers.upgrade?.toLowerCase() !== 'websocket' || !connectionUpgrade(response.headers.connection) || response.headers['sec-websocket-accept'] !== expected || response.headers['sec-websocket-protocol'] !== PROTOCOL || response.headers['sec-websocket-extensions'] || buffered.length>LIMITS.upstreamHead) return finish('NATIVE_SOCKET_BAD_UPSTREAM_HANDSHAKE',502)
+        clearTimeout(handshake)
+        lifetime=setTimeout(()=>finish('NATIVE_SOCKET_LIFETIME'),LIMITS.lifetime)
+        lifetime.unref?.()
+        socket.setTimeout(LIMITS.idle,()=>finish('NATIVE_SOCKET_IDLE'))
+        upgraded=true
+        browser.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${expected}\r\nSec-WebSocket-Protocol: ${PROTOCOL}\r\nCache-Control: no-store\r\nX-Request-Id: ${rid}\r\n\r\n`)
+        bytes=buffered.length+head.length
+        if (buffered.length) browser.write(buffered)
+        if (head.length) socket.write(head)
+        relay(browser,socket); relay(socket,browser); browser.resume()
+      })
+      outgoing.end()
+    } catch { finish('NATIVE_SOCKET_UPSTREAM_UNAVAILABLE',502) }
+  }
+  const closeOwned = () => { for (const finish of [...owned]) finish() }
+  const stop = () => { if (stopped) return; stopped=true; closeOwned() }
+  installed.add(server)
+  server.on('upgrade',upgrade)
+  server.once('close',()=>{stop();server.removeListener('upgrade',upgrade)})
+  const originalClose=server.close, originalAll=server.closeAllConnections
+  server.close=function(...args){stop();return originalClose.apply(this,args)}
+  if (originalAll) server.closeAllConnections=function(...args){closeOwned();return originalAll.apply(this,args)}
+  return stop
+}

package/server/server.mjs

@@ -19,6 +19,7 @@
 // `<!--brain:props-->` inside <script type="application/json" id="brain-props">.
 import { createServer as http, STATUS_CODES, request as httpRequest, Agent as HttpAgent } from 'node:http'
 import net from 'node:net'
+import { installNativeSockets } from './native-sockets.mjs'
 import { Readable } from 'node:stream'
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto'
 import { existsSync, readFileSync, realpathSync, statSync, lstatSync } from 'node:fs'
@@ -389,6 +390,7 @@ export function nativeAuthBridge(raw) {
         headers: () => req.$nativeLoginHeaders || {},
       }
     },
+    _socketCookie: req => cookies(req, false),
     close() { stopped = true; for (const request of owned) request.destroy(); agent.destroy() },
   }
 }
@@ -397,6 +399,7 @@ export function createServer(o = {}) {
   const dist = resolve(o.dist || process.cwd())
   const env = Object.freeze({ ...(o.env || ENV) }) // ctx.env: what the supervisor passed, read-only
   const native = nativeAuthBridge(o.backendURL ?? env.BRAIN_BACKEND_URL)
+  if (o.nativeSockets !== undefined && typeof o.nativeSockets !== 'boolean') throw Error('nativeSockets must be an explicit boolean')
   const TIMEOUT = +(o.timeout ?? env.BRAIN_TIMEOUT_MS ?? 10000)
   const LIMIT = +(o.rateLimit ?? env.BRAIN_RPC_LIMIT ?? 60) // per IP + function, per minute
   const MAX_BODY = 64 * 1024
@@ -419,6 +422,10 @@ export function createServer(o = {}) {
     sink(level, msg, safe)
   }
   const mf = readManifest(dist)
+  const hasManifestSockets = Object.hasOwn(mf,'nativeSockets')
+  if (hasManifestSockets && typeof mf.nativeSockets !== 'boolean') throw Error('Manifest nativeSockets must be an explicit boolean')
+  const nativeSockets = o.nativeSockets === undefined ? hasManifestSockets && mf.nativeSockets : o.nativeSockets
+  if (nativeSockets && !native) throw Error('Native sockets require a configured native backend')
   // the build's single route table (#187): already in match order, each with its RegExp source (named groups = params)
   const routes = mf.routes.map(r => ({ ...r, rx: r.rx ? new RegExp(r.rx) : exact(r.path) }))
   // the real path: Node imports file URLs through realpath, and the /_b/ hook must name the same modules (a symlinked
@@ -1049,6 +1056,7 @@ export function createServer(o = {}) {
     }
   })
   if (native) server.once('close', () => native.close())
+  if (native && nativeSockets) server.$brainSocketStop = installNativeSockets(server,{target:o.backendURL ?? env.BRAIN_BACKEND_URL,base:BASE,cookie:native._socketCookie,log})
   server.headersTimeout = 15000
   server.requestTimeout = 30000
   return server
@@ -1426,6 +1434,7 @@ if (process.argv[1] && real(process.argv[1]) === real(fileURLToPath(import.meta.
   const drain = () => {
     if (s.draining) return
     s.draining = true
+    s.$brainSocketStop?.()
     const ms = +(ENV.BRAIN_DRAIN_MS || 10000)
     const force = setTimeout(() => {
       s.closeAllConnections()