@abide/abide 0.28.0

package/src/lib/server/runtime/serializeCacheSnapshot.ts

@@ -0,0 +1,45 @@
+import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshot } from '../../shared/types/CacheSnapshot.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
+
+/*
+Partitions the request-scoped cache for SSR. Entries settled by the time
+`render()` returns were consumed via `await` (render blocked on them) and ship
+inline in the document's `__SSR__` blob. Entries still pending were consumed
+via `{#await}` — render emitted their pending branch without blocking — so they
+go to `pending` for the response streamer to drain and resolve over the wire.
+
+Unlike the old buffer-everything path, this never awaits the pending promises:
+that's the whole point of streaming. Settled entries are read concurrently (the
+awaits are immediate since they're already resolved, but their body reads run in
+parallel); pending entries are handed back as-is for the streamer to await one
+chunk at a time.
+*/
+export async function serializeCacheSnapshot(store: CacheStore): Promise<CacheSnapshot> {
+    const settled: CacheEntry[] = []
+    const pending: CacheEntry[] = []
+    for (const entry of store.entries.values()) {
+        /* Producer entries carry no wire request — nothing to rehydrate against, skip. */
+        if (!entry.request) {
+            continue
+        }
+        if (!isReplayableMethod(entry.request.method.toUpperCase())) {
+            continue
+        }
+        if (entry.settled) {
+            settled.push(entry)
+        } else {
+            pending.push(entry)
+        }
+    }
+    const snapshots = await Promise.all(
+        settled.map((entry) => snapshotEntryFromCache(store, entry)),
+    )
+    const inline = snapshots.filter(
+        (snapshot): snapshot is CacheSnapshotEntry => snapshot !== undefined,
+    )
+    return { inline, pending }
+}

package/src/lib/server/runtime/serverSlot.ts

@@ -0,0 +1,13 @@
+import type { Server } from 'bun'
+
+/*
+Internal holder for the active Bun.serve instance. setActiveServer is
+called once from createServer after Bun.serve resolves; the public
+`server()` function and any internal callers read through this slot
+and throw when accessed before init completes. `Server<unknown>` matches
+Bun's generic — ws.data is opaque to user code since the only ws path
+is the framework-managed sockets dispatcher.
+*/
+export const serverSlot: { active: Server<unknown> | undefined } = {
+    active: undefined,
+}

package/src/lib/server/runtime/setActiveServer.ts

@@ -0,0 +1,6 @@
+import type { Server } from 'bun'
+import { serverSlot } from './serverSlot.ts'
+
+export function setActiveServer(server: Server<unknown>): void {
+    serverSlot.active = server
+}

package/src/lib/server/runtime/snapshotEntryFromCache.ts

@@ -0,0 +1,83 @@
+import { isReplayableMethod } from '../../shared/isReplayableMethod.ts'
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+
+/*
+Awaits one cache entry and turns it into a wire-safe snapshot, or undefined
+when it can't ship. Shared by the inline snapshot path (settled entries,
+resolves immediately) and the streaming drain (pending {#await} entries,
+resolves whenever the underlying fetch lands). Only replayable methods (see
+REPLAYABLE_METHODS) with a textual Content-Type survive — writes must not
+re-fire from a snapshot, body-carrying methods can't be replayed without the
+original request body, and binary bodies don't round-trip through JSON.
+
+Reads the body once and replaces the entry's promise with a string-bodied
+Response so later `shareable()` clones operate on a buffered body instead of
+teeing the original stream. Returns undefined on a rejected fetch (the client
+falls back to a live re-fetch on cache miss) or when the entry was evicted /
+replaced between resolution and read (a concurrent invalidate) so the snapshot
+never ships a key that no longer matches the live store.
+*/
+export async function snapshotEntryFromCache(
+    store: CacheStore,
+    entry: CacheEntry,
+): Promise<CacheSnapshotEntry | undefined> {
+    /* Producer entries have no wire request to replay — they never snapshot. */
+    if (!entry.request) {
+        return undefined
+    }
+    const method = entry.request.method.toUpperCase()
+    if (!isReplayableMethod(method)) {
+        return undefined
+    }
+    const response = await readSettled(entry.promise as Promise<Response>)
+    if (!response) {
+        return undefined
+    }
+    if (store.entries.get(entry.key) !== entry) {
+        return undefined
+    }
+    const contentType = (response.headers.get('content-type') ?? '').toLowerCase()
+    if (!isTextual(contentType)) {
+        return undefined
+    }
+    const body = await response.text()
+    entry.promise = Promise.resolve(
+        new Response(body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: response.headers,
+        }),
+    )
+    return {
+        key: entry.key,
+        url: entry.request.url,
+        method,
+        status: response.status,
+        statusText: response.statusText,
+        headers: Array.from(response.headers.entries()),
+        body,
+    }
+}
+
+async function readSettled(promise: Promise<Response>): Promise<Response | undefined> {
+    try {
+        return await promise
+    } catch {
+        return undefined
+    }
+}
+
+function isTextual(contentType: string): boolean {
+    if (contentType.startsWith('text/')) {
+        return true
+    }
+    if (contentType.includes('json')) {
+        return true
+    }
+    if (contentType.includes('xml')) {
+        return true
+    }
+    return false
+}

package/src/lib/server/runtime/streamCacheResolutions.ts

@@ -0,0 +1,37 @@
+import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { CacheStore } from '../../shared/types/CacheStore.ts'
+import type { StreamedResolution } from '../../shared/types/StreamedResolution.ts'
+import { snapshotEntryFromCache } from './snapshotEntryFromCache.ts'
+
+/*
+Drains the pending ({#await}) cache entries in resolution order — whichever
+fetch lands next is yielded next, so a slow entry never blocks a fast one
+behind it. Yields exactly one StreamedResolution per entry: the snapshot when
+serialization succeeds, or a `{ key, miss }` marker when the body can't ship so
+the client placeholder re-fetches instead of hanging on a deferred that never
+settles.
+*/
+export async function* streamCacheResolutions(
+    store: CacheStore,
+    pending: CacheEntry[],
+): AsyncIterable<StreamedResolution> {
+    /*
+    Tag each pending serialization with its key so the loop can drop exactly
+    the one that just settled. Deleting inside the `.then` instead would race
+    the loop — already-resolved promises empty the map before the first
+    Promise.race runs — so removal happens here, after the await.
+    */
+    const inflight = new Map<string, Promise<{ key: string; snapshot?: CacheSnapshotEntry }>>()
+    for (const entry of pending) {
+        inflight.set(
+            entry.key,
+            snapshotEntryFromCache(store, entry).then((snapshot) => ({ key: entry.key, snapshot })),
+        )
+    }
+    while (inflight.size > 0) {
+        const { key, snapshot } = await Promise.race(inflight.values())
+        inflight.delete(key)
+        yield snapshot ?? { key, miss: true }
+    }
+}

package/src/lib/server/runtime/streamFromIterator.ts

@@ -0,0 +1,86 @@
+/*
+Shared body builder for the streaming respond helpers (`jsonl`, `sse`).
+Both flow the same shape — pull from an AsyncIterator, encode each frame
+to bytes, emit a sentinel `error` frame on a generator throw, and route
+ReadableStream's `cancel` into `iter.return()` so the handler's
+`for await` exits via its normal control path. Only the per-frame
+encoding and the optional keepalive payload differ between the two.
+
+Keepalive is opt-in: SSE uses `: keepalive\n\n` every 15s so proxies
+don't drop an idle connection; jsonl has no spec-defined comment, so it
+omits keepalive entirely.
+*/
+
+export type StreamEncoder<T> = {
+    encodeFrame: (value: T) => string
+    encodeError: (message: string) => string
+    keepaliveMs?: number
+    keepalivePayload?: string
+}
+
+export function streamFromIterator<T>(
+    iterable: AsyncIterable<T>,
+    encoder: StreamEncoder<T>,
+): ReadableStream<Uint8Array> {
+    const textEncoder = new TextEncoder()
+    const iterator = iterable[Symbol.asyncIterator]()
+    let keepalive: ReturnType<typeof setInterval> | undefined
+
+    function stopKeepalive(): void {
+        if (keepalive !== undefined) {
+            clearInterval(keepalive)
+            keepalive = undefined
+        }
+    }
+
+    return new ReadableStream<Uint8Array>({
+        start(controller) {
+            if (encoder.keepaliveMs !== undefined && encoder.keepalivePayload !== undefined) {
+                const payload = textEncoder.encode(encoder.keepalivePayload)
+                keepalive = setInterval(() => {
+                    /*
+                    Every close/cancel path clears this interval synchronously,
+                    so a tick can't normally hit a closed controller — but
+                    enqueue throws on a closed/errored stream, and an uncaught
+                    throw in a timer crashes the process. Guard + self-stop.
+                    */
+                    try {
+                        controller.enqueue(payload)
+                    } catch {
+                        stopKeepalive()
+                    }
+                }, encoder.keepaliveMs)
+            }
+        },
+        async pull(controller) {
+            try {
+                const next = await iterator.next()
+                if (next.done) {
+                    stopKeepalive()
+                    controller.close()
+                    return
+                }
+                controller.enqueue(textEncoder.encode(encoder.encodeFrame(next.value)))
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error)
+                controller.enqueue(textEncoder.encode(encoder.encodeError(message)))
+                stopKeepalive()
+                controller.close()
+            }
+        },
+        cancel(reason) {
+            stopKeepalive()
+            /*
+            Route cancel into the generator's normal exit, but swallow a
+            rejection from its cleanup: a `finally` that throws on `.return()`
+            would otherwise surface as an unhandled rejection (process-fatal
+            under Bun's default) on a client disconnect — a path every
+            sse/jsonl/resolve stream hits routinely.
+            */
+            return iterator.return?.(reason)?.then(
+                () => undefined,
+                () => undefined,
+            )
+        },
+    })
+}

package/src/lib/server/runtime/types/Assets.ts

@@ -0,0 +1,6 @@
+/*
+Embedded asset bytes keyed by request path (compile-time gzip embed). Pinned
+to a plain-ArrayBuffer backing so values feed `new Response(...)` directly —
+BodyInit rejects views over a possibly-shared buffer.
+*/
+export type Assets = Record<string, Uint8Array<ArrayBuffer>>

package/src/lib/server/runtime/types/DevReloadStamp.ts

@@ -0,0 +1,18 @@
+/*
+The dev live-reload stamp the worker announces on the channel, split so the
+browser keeps its page across edits that don't need a reload:
+  - `structure` fingerprints everything EXCEPT the entry stylesheet and the
+    hot-swappable component bodies — non-component source, public assets, the
+    shell, the component-id set, and non-hot component bodies (pages, layouts,
+    import-bearing components). Any change here reloads.
+  - `cssHref` is the entry stylesheet's current content-hashed URL; a change
+    here alone swaps the `<link>` in place. Undefined when no stylesheet is built.
+  - `components` maps each hot-swappable (leaf child) component's module id to a
+    hash of its client build (style-independent). A change here alone fetches the
+    component's hot module and replaces its live instances — no reload.
+*/
+export type DevReloadStamp = {
+    structure: string
+    cssHref: string | undefined
+    components: Record<string, string>
+}

package/src/lib/server/runtime/types/InspectorCacheEntry.ts

@@ -0,0 +1,24 @@
+/*
+One global cache entry projected for the inspector — the serializable facts the
+Cache tab renders. The stored promise/Request/timer aren't included; what an
+operator wants is the entry's identity, lifecycle state, retention, and a peek
+at the held value.
+*/
+export type InspectorCacheEntry = {
+    /* The cache key (remote: method+url+args; producer: reference+args). */
+    key: string
+    /* Lifecycle: 'settled' | 'in-flight' | 'refreshing'. */
+    status: string
+    /* True when the entry stores a wire Response (a remote verb), false for a plain producer value. */
+    remote: boolean
+    /* Retention ttl in ms; undefined = forever, 0 = dedupe-only. */
+    ttl: number | undefined
+    /* Ms until expiry from snapshot time; undefined = no expiry armed. */
+    expiresInMs: number | undefined
+    /* The call's scope tags (cache.invalidate({ scope }) targets). */
+    scope: string[]
+    /* A short JSON preview of the decoded warm value, when the entry holds one. */
+    value: string | undefined
+    /* An armed invalidate policy (throttle/debounce + ms), if declared. */
+    policy: string | undefined
+}

package/src/lib/server/runtime/types/InspectorCacheSnapshot.ts

@@ -0,0 +1,11 @@
+import type { InspectorCacheEntry } from './InspectorCacheEntry.ts'
+
+/*
+The inspector's view of the cache: the process-level (`global: true`) store's
+current entries. That's the persistent store — request-scoped caches live and
+die with their request, so they surface as per-request tallies in the feed and
+traces rather than here.
+*/
+export type InspectorCacheSnapshot = {
+    entries: InspectorCacheEntry[]
+}

package/src/lib/server/runtime/types/InspectorContext.ts

@@ -0,0 +1,30 @@
+import type { LogRecord } from '../../../shared/types/LogRecord.ts'
+import type { InspectorCacheSnapshot } from './InspectorCacheSnapshot.ts'
+import type { InspectorSurface } from './InspectorSurface.ts'
+
+/*
+The capabilities core injects into `@abide/inspector` when
+ABIDE_ENABLE_INSPECTOR=true. The package consumes this and imports no abide
+internals — so the inspector stays a pure consumer and core grows no public
+surface for it (mirrors how AppModule / AgentEngine are the documented seams).
+Everything here is already produced by the runtime: the registries behind
+loadSurface(), the log chokepoint behind onRecord().
+*/
+// @readme plumbing
+export type InspectorContext = {
+    /* App identity for the UI header — the same name/version the health probe reports. */
+    app: { name: string; version: string }
+    /* Eager-loads the registries, then projects the current RPC + socket catalog. */
+    loadSurface: () => Promise<InspectorSurface>
+    /* Snapshots the persistent (global) cache store — current entries with their
+       lifecycle state, retention, scope tags, and a value preview. */
+    cacheSnapshot: () => InspectorCacheSnapshot
+    /*
+    Subscribes to the unified event stream: every emitted log record (the log's
+    structured form, trace context and all) plus published socket frames shaped
+    as `socket`-channel records — one feed, so the inspector treats sockets,
+    cache diagnostics, and request logs uniformly. Returns an unsubscribe; the
+    underlying taps are process-wide, owned by the inspector for its lifetime.
+    */
+    onRecord: (listener: (record: LogRecord) => void) => () => void
+}

package/src/lib/server/runtime/types/InspectorSocket.ts

@@ -0,0 +1,17 @@
+/*
+One declared socket projected for the inspector: its name plus the operations
+it exposes (tail always; publish only when it allows client publishing),
+mirroring the CLI/MCP projection from socketOperations so the inspector can't
+disagree with them about a socket's faces.
+*/
+export type InspectorSocket = {
+    /* The socket's file-path name (may contain `/` for nested files). */
+    name: string
+    /* The operations exposed, named as the CLI/MCP advertise them. */
+    operations: Array<{
+        kind: string
+        name: string
+        method: string
+        restUrl: string
+    }>
+}

package/src/lib/server/runtime/types/InspectorSurface.ts

@@ -0,0 +1,13 @@
+import type { InspectorSocket } from './InspectorSocket.ts'
+import type { InspectorVerb } from './InspectorVerb.ts'
+
+/*
+The app's machine surface projected for the inspector — the static catalog the
+UI renders. Built by reading the verb and socket registries after they're
+eager-loaded, so a freshly-booted server lists its whole surface, not just the
+verbs hit so far. Pages stay out: they're the human surface, already navigable.
+*/
+export type InspectorSurface = {
+    verbs: InspectorVerb[]
+    sockets: InspectorSocket[]
+}

package/src/lib/server/runtime/types/InspectorVerb.ts

@@ -0,0 +1,27 @@
+/*
+One RPC verb projected for the inspector: the registry entry reduced to the
+serializable facts the UI renders — where it mounts, its method, which
+non-browser surfaces advertise it, and its argument/result shapes as JSON
+Schema. Schemas project through jsonSchemaForSchema (same as MCP/OpenAPI), so
+a verb whose library can't render a schema still lists with an opaque shape.
+*/
+export type InspectorVerb = {
+    /* Registry key — the rpc URL the verb mounts at (e.g. /rpc/users/create). */
+    url: string
+    /* HTTP method bound to the verb. */
+    method: string
+    /* Which surfaces advertise it (browser/mcp/cli), from the verb's ClientFlags. */
+    clients: Record<string, boolean>
+    /* Argument-bag shape as JSON Schema; undefined when the verb declares none. */
+    inputSchema: Record<string, unknown> | undefined
+    /* Success-body shape as JSON Schema; undefined when the verb declares none. */
+    outputSchema: Record<string, unknown> | undefined
+    /* True when the verb declares a filesSchema — it accepts multipart File parts. */
+    files: boolean
+    /* Per-verb handler deadline in ms; undefined = no deadline. */
+    timeout: number | undefined
+    /* Per-verb received-body cap in bytes; undefined = Bun's server-wide ceiling. */
+    maxBodySize: number | undefined
+    /* True when the verb opts out of the same-origin CSRF gate. */
+    crossOrigin: boolean | undefined
+}

package/src/lib/server/runtime/types/RequestStore.ts

@@ -0,0 +1,55 @@
+import type { CacheStore } from '../../../shared/types/CacheStore.ts'
+import type { TraceContext } from '../../../shared/types/TraceContext.ts'
+
+/*
+Per-request state propagated through AsyncLocalStorage. Every field is
+populated once at the server's fetch boundary; helpers and verb-defined
+remote functions read from it without threading arguments through user code.
+The inbound request's AbortSignal is reached via `req.signal` rather than a
+separate field.
+*/
+export type RequestStore = {
+    url: URL
+    req: Request
+    cache: CacheStore
+    /*
+    W3C trace position: inbound `traceparent` continued (prefer-incoming) or a
+    fresh sampled trace minted at the boundary. Read by trace()/log via the
+    request-scope resolver and stamped into __SSR__ for the browser half.
+    */
+    trace: TraceContext
+    /* Bun.nanoseconds() at scope entry — anchors log `+elapsed`, Server-Timing, and the closing record's total. */
+    start: number
+    /*
+    The matched page route and its decoded params, set just before the page
+    renders so the `page` proxy resolves them inside layout-scoped components
+    during SSR. Undefined on rpc/socket requests and until a page match lands.
+    */
+    route?: string
+    params?: Record<string, string>
+    /*
+    store.url with the mount base re-applied — the browser-space URL the `page`
+    proxy publishes, memoized by pageUrlFromStore on first read. `url` itself
+    stays app-space for routing and error-prefix matching.
+    */
+    pageUrl?: URL
+    /*
+    Set by a server-side health() read (via healthReadSlot) during this
+    request's SSR pass. The renderer stamps the health payload into __SSR__
+    only when set, so the client seed stays reader-driven like the poll.
+    */
+    healthRead?: boolean
+    /*
+    The request's cookie jar, materialized lazily by the first cookies() call
+    and flushed to Set-Cookie headers when the scope returns. Undefined while a
+    request never touches cookies, so the common path parses and emits nothing.
+    */
+    cookies?: Bun.CookieMap
+    /*
+    File parts split off a multipart/form-data body by parseArgs, grouped by
+    field name, for files() to read. Files never enter the handler's args so the
+    input schema keeps validating a plain object; undefined when the request
+    carried no file parts.
+    */
+    files?: Record<string, File[]>
+}

package/src/lib/server/runtime/warnUnguardedMcp.ts

@@ -0,0 +1,32 @@
+import { abideLog } from '../../shared/abideLog.ts'
+import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { socketRegistry } from '../sockets/socketRegistry.ts'
+import { ensureRegistriesLoaded } from './registryManifests.ts'
+
+/*
+Boot-time disclosure for an unguarded MCP endpoint: when /__abide/mcp is
+mounted with at least one MCP-exposed declaration and no app.handle
+middleware to authenticate requests, say so. Printed unconditionally — the
+surface map is DEBUG-gated diagnostics, but an unauthenticated machine
+surface should never boot silently. The caller skips this entirely when
+app.handle exists, so only the authless path pays the eager registry load.
+Best-effort like the surface map: enumeration failures are swallowed.
+*/
+export async function warnUnguardedMcp(): Promise<void> {
+    try {
+        await ensureRegistriesLoaded()
+    } catch {
+        return
+    }
+    const exposed =
+        Array.from(verbRegistry.values()).filter((entry) => entry.clients.mcp).length +
+        Array.from(socketRegistry.values()).filter((entry) => entry.clients.mcp).length
+    if (exposed === 0) {
+        return
+    }
+    abideLog.warn(
+        `MCP endpoint /__abide/mcp exposes ${exposed} declaration${exposed === 1 ? '' : 's'} ` +
+            'with no auth guard — add an app.handle middleware in src/app.ts to ' +
+            'authenticate machine clients, or set clients.mcp: false per declaration',
+    )
+}

package/src/lib/server/runtime/withResponseDefaults.ts

@@ -0,0 +1,24 @@
+/*
+Merges a caller's `ResponseInit` over a respond helper's default headers.
+The helper's defaults seed the header set; the caller's headers overlay them
+per-key (so an explicit `cache-control` wins over the helper's `no-store`),
+and the rest of `init` (status, statusText) passes straight through. Shared
+by `json` / `jsonl` / `sse` / `error` / `redirect` so every helper accepts a
+final `ResponseInit` with identical override semantics.
+
+A helper that owns the status itself (`error`, `redirect`) passes it as the
+final `status` argument; it is applied last so it always wins over any
+`init.status`, keeping that precedence inside the helper rather than relying
+on each call site spreading in the right order.
+*/
+export function withResponseDefaults(
+    init: ResponseInit | undefined,
+    defaultHeaders: Record<string, string>,
+    status?: number,
+): ResponseInit {
+    const headers = new Headers(defaultHeaders)
+    new Headers(init?.headers).forEach((value, key) => {
+        headers.set(key, value)
+    })
+    return { ...init, headers, ...(status !== undefined && { status }) }
+}

package/src/lib/server/server.ts

@@ -0,0 +1,33 @@
+import type { Server } from 'bun'
+import { getActiveServer } from './runtime/getActiveServer.ts'
+import { inProcessServer } from './runtime/inProcessServer.ts'
+import { requestContext } from './runtime/requestContext.ts'
+
+/*
+Returns the active Bun.serve instance. Mirrors `request()`'s function-call
+shape so call sites appear in stack traces (a Proxy trap intermediates and
+obscures them).
+
+When no Bun.serve has booted, resolution forks on the request scope:
+- Inside a scope it is in-process dispatch (CLI / MCP / test client), which
+  never boots a server — return the no-op inProcessServer so handler idioms
+  (server().timeout/publish/requestIP …) run unchanged instead of throwing.
+  createServer sets the slot at boot before any request, so an empty slot
+  while a scope is live can only be in-process.
+- Outside any scope it is a genuine before-init misuse (module top-level /
+  app.ts init); keep throwing — silent undefined would mask it and strand
+  later property reads with cryptic errors.
+*/
+// @readme request-scope
+export function server(): Server<unknown> {
+    const active = getActiveServer()
+    if (active) {
+        return active
+    }
+    if (requestContext.getStore()) {
+        return inProcessServer
+    }
+    throw new Error(
+        '[abide] server() called before init — make sure your call happens inside or after app.ts init() resolves',
+    )
+}

package/src/lib/server/socket.ts

@@ -0,0 +1,32 @@
+import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
+import type { Socket } from './sockets/types/Socket.ts'
+import type { SocketOptions } from './sockets/types/SocketOptions.ts'
+
+/*
+Declares a Socket inside a file under `src/server/sockets/`. Each file contains
+exactly one export, named after the file (e.g. `chat.ts` →
+`export const chat = socket<ChatMessage>(...)`). The bundler reads the
+// @readme sockets
+export name from the filename and the socket name from the file path
+under `src/server/sockets/`, then rewrites this call to bind the name into the
+runtime implementation (defineSocket on the server, socketProxy on the
+client). Opts (tail, clientPublish, schema, clients) live on the
+server side only; the client target discards them.
+
+When `schema` is set, `T` infers from `InferOutput<Schema>` and publish
+payloads validate against it on the server. `clients` controls which
+adapter surfaces (browser / mcp / cli) advertise the socket — defaults
+to browser-only when schemaless, all surfaces when a schema is present.
+
+This function exists only for the type signature; calling it directly
+means the bundler plugin didn't process the file, which throws.
+*/
+export function socket<Schema extends StandardSchemaV1>(
+    opts: SocketOptions<Schema> & { schema: Schema },
+): Socket<StandardSchemaV1.InferOutput<Schema>>
+export function socket<T = unknown>(opts?: SocketOptions): Socket<T>
+export function socket<T = unknown>(_opts?: SocketOptions): Socket<T> {
+    throw new Error(
+        '[abide] `socket(...)` was called outside an $sockets module — the socket helper is only valid as the value of `export const <filename> = ...` inside a file under src/server/sockets/',
+    )
+}