@abide/abide 0.48.0 → 0.50.0

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

@@ -1,21 +1,21 @@
 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 type { CacheResolution } 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
+behind it. Yields exactly one CacheResolution 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.
+settles. (Never the cell arm of StreamedResolution — that is emitted separately.)
 */
 export async function* streamCacheResolutions(
     store: CacheStore,
     pending: CacheEntry[],
-): AsyncIterable<StreamedResolution> {
+): AsyncIterable<CacheResolution> {
     /*
     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
@@ -29,9 +29,16 @@ export async function* streamCacheResolutions(
             snapshotEntryFromCache(store, entry).then((snapshot) => ({ key: entry.key, snapshot })),
         )
     }
+    /*
+    Drain in settle order. A pending BARE read (ADR-0024 auto-streaming) is bounded by its OWN
+    endpoint `timeout` — which 504s the in-process handler during SSR, settling the entry into an
+    error that snapshots as a `{ key, miss }` (the client refetches on hydrate). So there is no
+    separate SSR-stream deadline (ADR-0024 option a): a read with a declared timeout self-settles;
+    a read that declares none is unbounded — the author bounds it with a `timeout`.
+    */
     while (inflight.size > 0) {
-        const { key, snapshot } = await Promise.race(inflight.values())
-        inflight.delete(key)
-        yield snapshot ?? { key, miss: true }
+        const settled = await Promise.race(inflight.values())
+        inflight.delete(settled.key)
+        yield settled.snapshot ?? { key: settled.key, miss: true }
     }
 }

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

@@ -1,3 +1,4 @@
+import { abideLog } from '../../shared/abideLog.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
 
 /*
@@ -27,6 +28,11 @@ export function streamFromIterator<T>(
     const textEncoder = new TextEncoder()
     const iterator = iterable[Symbol.asyncIterator]()
     let keepalive: ReturnType<typeof setInterval> | undefined
+    /* Set once the stream closes or is cancelled. A `pull` parked on `iterator.next()`
+       resolves AFTER a client-disconnect `cancel()` has already closed the controller;
+       without this guard it would touch the dead controller and throw "Controller is
+       already closed" — noise on every mid-frame disconnect. */
+    let closed = false
 
     function stopKeepalive(): void {
         if (keepalive !== undefined) {
@@ -65,20 +71,42 @@ export function streamFromIterator<T>(
         async pull(controller) {
             try {
                 const next = await iterator.next()
+                /* Cancelled during the awaited next() — the controller is already closed,
+                   so any close/enqueue here would throw. Nothing left to do. */
+                if (closed) {
+                    return
+                }
                 if (next.done) {
+                    closed = true
                     stopKeepalive()
                     controller.close()
                     return
                 }
                 controller.enqueue(textEncoder.encode(encoder.encodeFrame(next.value)))
             } catch (error) {
+                /* A throw during cancellation unwinding (the generator's `finally` rejecting
+                   as `.return()` runs) is not a real stream error — the controller is gone. */
+                if (closed) {
+                    return
+                }
+                /* Log the FULL error server-side (host/credentials/stack an operator needs) — the
+                   unary rpc path does the same, and the jsonl/sse docs promise it. Only the
+                   sanitized message crosses the wire in the sentinel error frame. */
+                abideLog.error(error)
                 const message = messageFromError(error)
-                controller.enqueue(textEncoder.encode(encoder.encodeError(message)))
+                closed = true
                 stopKeepalive()
-                controller.close()
+                try {
+                    controller.enqueue(textEncoder.encode(encoder.encodeError(message)))
+                    controller.close()
+                } catch {
+                    /* Consumer vanished between the throw and the sentinel frame — the error
+                       frame never lands, but the connection is already closing regardless. */
+                }
             }
         },
         cancel(reason) {
+            closed = true
             stopKeepalive()
             /*
             Route cancel into the generator's normal exit, but swallow a

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

@@ -0,0 +1,23 @@
+import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
+import { STATUS_TEXT } from './STATUS_TEXT.ts'
+
+/*
+The framework's plain-text status response — a `text/plain`, `no-store` body at
+`status`, shared by the 404/405 dispatch branches, the asset servers' miss, and
+the failed-upgrade reply so those literals can't drift. `body` defaults to the
+status reason phrase (STATUS_TEXT, e.g. 'Not Found'), falling back to `HTTP
+<status>` for an unlisted code. `extraHeaders` overlays the defaults per-key —
+the 405 passes `Allow` this way. A fresh Response per call: a body is
+single-use, so it can't be hoisted to a shared const.
+*/
+export function textResponse(
+    status: number,
+    body?: string,
+    extraHeaders?: Record<string, string>,
+): Response {
+    return new Response(body ?? STATUS_TEXT[status] ?? `HTTP ${status}`, {
+        status,
+        headers: { 'Content-Type': TEXT_PLAIN, 'Cache-Control': NO_STORE, ...extraHeaders },
+    })
+}

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

@@ -1,18 +1,14 @@
 /*
 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.
+  - `structure` fingerprints every source signal a reload must react to — each
+    `.abide`'s client build hash (no CSS), the component-id set, non-`.abide`
+    source, public assets, and the shell (with the stylesheet href normalised out).
+    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.
 */
 export type DevReloadStamp = {
     structure: string
     cssHref: string | undefined
-    components: Record<string, string>
 }

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

@@ -19,6 +19,6 @@ export type InspectorCacheEntry = {
     tags: string[]
     /* A short JSON preview of the decoded warm value, when the entry holds one. */
     value: string | undefined
-    /* An armed swr policy (`swr`, optionally + throttle/debounce + ms), if declared. */
+    /* An armed refetch policy (`refetch`, optionally + throttle/debounce + ms), if declared. */
     policy: string | undefined
 }

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

@@ -1,4 +1,7 @@
 import type { CacheStore } from '../../../shared/types/CacheStore.ts'
+import type { PendingAsyncCells } from '../../../shared/types/PendingAsyncCells.ts'
+import type { ResolvedCells } from '../../../shared/types/ResolvedCells.ts'
+import type { StreamedCells } from '../../../shared/types/StreamedCells.ts'
 import type { TraceContext } from '../../../shared/types/TraceContext.ts'
 import type { Scope } from '../../../ui/types/Scope.ts'
 
@@ -14,6 +17,30 @@ export type RequestStore = {
     req: Request
     cache: CacheStore
     /*
+    In-flight async-cell promises registered during this request's SSR pass. The
+    Tier-2 barrier (`settleAsyncCells`) drains and awaits them between a
+    component's cell declarations and its template so resolved values bake into
+    the HTML. Per-request (like `cache`) so concurrent renders never share a drain.
+    */
+    pendingAsyncCells: PendingAsyncCells
+    /*
+    Async-cell values that RESOLVED during this request's SSR pass, keyed by render-path id.
+    `createAsyncCell.settleValue` pushes each; the page renderer stamps them into `__SSR__.cells`
+    (ref-json) so the client hydrates the cell warm. Sibling of `pendingAsyncCells` (the barrier's
+    in-flight list) — this one holds settled VALUES, read at render-return, not awaited.
+    */
+    resolvedCells: ResolvedCells
+    /*
+    STREAMING async-cell settled VALUES recorded during this request's SSR pass, keyed by render-path
+    id (ADR-0035). A streaming cell ships pending in the shell; the page renderer drains this after the
+    shell and streams an `__abideResolve({ cellKey, value })` chunk for each so the client adopts the
+    resolved value post-hydration. These are already-settled values (pushed by `createAsyncCell`),
+    never awaited here — a cell that stays pending through the request is simply not recorded and the
+    client cold-runs it (awaiting one would hang the response). Per-request so concurrent renders never
+    mix. Sibling of `resolvedCells` (the blocking partition baked into the head snapshot).
+    */
+    streamedCells: StreamedCells
+    /*
     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.

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

@@ -1,4 +1,5 @@
 import { abideLog } from '../../shared/abideLog.ts'
+import { MCP_PATH } from '../../shared/MCP_PATH.ts'
 import { rpcRegistry } from '../rpc/rpcRegistry.ts'
 import { socketRegistry } from '../sockets/socketRegistry.ts'
 import { ensureRegistriesLoaded } from './registryManifests.ts'
@@ -18,15 +19,24 @@ export async function warnUnguardedMcp(): Promise<void> {
     } catch {
         return
     }
-    const isMcpExposed = (entry: { clients: { mcp: boolean } }): boolean => entry.clients.mcp
-    const exposed = [...rpcRegistry.values(), ...socketRegistry.values()].filter(
-        isMcpExposed,
-    ).length
+    /* Rpc entries carry the resolved clients on `entry.remote` (ADR-0020); socket entries
+       keep their own `entry.clients`. Count each from its own home. */
+    let exposed = 0
+    for (const entry of rpcRegistry.values()) {
+        if (entry.remote.clients.mcp) {
+            exposed += 1
+        }
+    }
+    for (const entry of socketRegistry.values()) {
+        if (entry.clients.mcp) {
+            exposed += 1
+        }
+    }
     if (exposed === 0) {
         return
     }
     abideLog.warn(
-        `MCP endpoint /__abide/mcp exposes ${exposed} declaration${exposed === 1 ? '' : 's'} ` +
+        `MCP endpoint ${MCP_PATH} 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/sockets/createSocketDispatcher.ts

@@ -1,6 +1,6 @@
 import type { ServerWebSocket } from 'bun'
 import { abideLog } from '../../shared/abideLog.ts'
-import { decodeRefJson } from '../../shared/decodeRefJson.ts'
+import { decodeWireBody } from '../../shared/decodeWireBody.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
@@ -245,7 +245,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         the process down.
         */
         try {
-            entry.socket.broadcast(frame.message)
+            entry.socket.publish(frame.message)
         } catch (publishError) {
             abideLog.error(publishError)
         }
@@ -309,7 +309,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             }
             try {
                 // publish() validates against the socket schema and throws on a bad payload.
-                entry.socket.broadcast(message)
+                entry.socket.publish(message)
             } catch (publishError) {
                 return error(422, messageFromError(publishError))
             }
@@ -338,14 +338,12 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             const text = typeof data === 'string' ? data : textDecoder.decode(data)
             let frame: SocketClientFrame
             try {
-                /* ref-json from abide's own client; a non-abide client sends a plain-JSON
-                   frame, which decodeRefJson rejects (a frame is always an object, never the
-                   `[rootValue, slots]` envelope) — fall back to JSON.parse so raw WS clients work. */
-                try {
-                    frame = decodeRefJson(text) as SocketClientFrame
-                } catch {
-                    frame = JSON.parse(text) as SocketClientFrame
-                }
+                /* No header rides a ws frame, so decodeWireBody sniffs: ref-json from abide's
+                   own client, else a non-abide client's plain-JSON frame (which decodeRefJson
+                   rejects — a frame is always an object, never the `[rootValue, slots]`
+                   envelope — so it falls back to JSON.parse). A frame malformed under both
+                   codecs throws here and is dropped. */
+                frame = decodeWireBody(text, undefined) as SocketClientFrame
             } catch {
                 return
             }

package/src/lib/server/sockets/defineSocket.ts

@@ -24,8 +24,8 @@ is the live stream — no replay. `chat.tail(count)` opens a subscription
 seeded with the last `count` retained frames (no-arg = the whole
 retained tail, clamped to the declared `tail` size). When `ttl` is set,
 retained frames older than `ttl` ms are evicted lazily on every
-read/append — no timer runs in the background. `chat.broadcast(m)` is isomorphic —
-called server-side it both notifies in-process iterators and broadcasts
+read/append — no timer runs in the background. `chat.publish(m)` is isomorphic —
+called server-side it both notifies in-process iterators and fans out
 to remote subscribers; called client-side (via socketProxy) it sends a
 `pub` frame the dispatcher validates and forwards.
 */
@@ -178,8 +178,9 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
     const self = {
         name,
         clients,
-        /* `broadcast` is the public fan-out; `publish` remains the internal function name. */
-        broadcast: publish,
+        /* `publish` is the public fan-out (mirroring Bun's `server.publish()`); the internal
+           function shares the name. */
+        publish,
         tail: (count?: number, hooks?: TailHooks) => iterate(count ?? 'all', hooks),
         /* The latest retained frame (after ttl pruning), or undefined when none is held. */
         peek: () => {

package/src/lib/server/sse.ts

@@ -24,6 +24,7 @@ EventSource surfaces this via its `error` listener and `tail()`
 maps it to the entry's `error` field.
 */
 import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
+import { encodeWireBody } from '../shared/encodeWireBody.ts'
 import { sseErrorFrame } from '../shared/sseErrorFrame.ts'
 import type { TypedResponse } from './rpc/types/TypedResponse.ts'
 import { streamFromIterator } from './runtime/streamFromIterator.ts'
@@ -37,7 +38,10 @@ export function sse<Frame>(
     init?: ResponseInit,
 ): TypedResponse<AsyncIterable<Frame>> {
     const body = streamFromIterator(iterable, {
-        encodeFrame: (value) => `data: ${JSON.stringify(value)}\n\n`,
+        /* Honest-JSON encode (same encoder as `json()`) so a frame carrying a Set/Map/bigint
+           crosses losslessly instead of the silent `{}` / bigint-throw plain JSON.stringify gave
+           — parseSse's JSON.parse reads it unchanged since the wire stays honest JSON. */
+        encodeFrame: (value) => `data: ${encodeWireBody(value)}\n\n`,
         encodeError: (message) => sseErrorFrame.encode(message),
         keepaliveMs: KEEPALIVE_INTERVAL_MS,
         keepalivePayload: ': keepalive\n\n',

package/src/lib/shared/ASYNC_CELL.ts

@@ -0,0 +1,5 @@
+/* Brand on an async cell's facet (`AsyncComputed`/`AsyncState`). The probe family
+   (`peek`/`pending`/`refreshing`/`refresh`) tests for it to route a cell to its own
+   methods, the way `Symbol.asyncIterator` routes a stream. A well-known symbol (not a
+   string key) so it never collides with a resolved value's own properties. */
+export const ASYNC_CELL: unique symbol = Symbol.for('abide.asyncCell')

package/src/lib/shared/DEV_REBUILD_PATH.ts

@@ -0,0 +1,6 @@
+/*
+Dev-only manual-rebuild trigger: POSTing here signals the orchestrator to rebuild +
+restart. Mounted only under `abide dev`. Shared so the router mount and the launcher's
+"POST … to apply" hint name the one path.
+*/
+export const DEV_REBUILD_PATH = '/__abide/reload'

package/src/lib/shared/HTTP_METHODS.ts

@@ -0,0 +1,6 @@
+/*
+The canonical RPC/HTTP verbs abide understands. One source of truth so the `HttpMethod`
+type, the loader's rpc-export detection, and the compiler's helper set can't drift on which
+export names are rpc entrypoints.
+*/
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const

package/src/lib/shared/HttpError.ts

@@ -14,11 +14,7 @@ export class HttpError extends Error {
        payload it carried — parsed off the `{ $abideError, data }` body by decodeResponse.
        `data` is typed `unknown` (a throw can't carry the rpc's per-kind type to the
        catch); narrow it yourself — for `kind: 'validation'` the shape is the exported
-       `ValidationErrorData` (`{ issues, fields }`). Both undefined for a plain `error(status, text)`.
-       The framework also reserves `kind: 'queued'` for a durable (`outbox: true`) call
-       parked because the server was unreachable — `data` then holds the parked OutboxEntry,
-       so `(error.data as OutboxEntry).settled` awaits the eventual delivered result or
-       server refusal (the entry's own `error` carries the underlying cause). */
+       `ValidationErrorData` (`{ issues, fields }`). Both undefined for a plain `error(status, text)`. */
     readonly kind?: string
     readonly data?: unknown
 

package/src/lib/shared/MCP_PATH.ts

@@ -0,0 +1,6 @@
+/*
+The MCP endpoint: inbound JSON-RPC over HTTP delegated to the app's `McpServer.handle`,
+mounted only when an `mcp` is configured. Framework-internal (`/__abide/*`). Shared so the
+router mount and the boot-time disclosure warning name the one path.
+*/
+export const MCP_PATH = '/__abide/mcp'

package/src/lib/shared/PROXIED_SERVER_SUBDIRS.ts

@@ -0,0 +1,15 @@
+/*
+Single source of truth for the proxied/server-only split. These are the only
+subdirectories under src/server/ whose modules the client bundle replaces with
+proxy stubs instead of shipping their real source: src/server/rpc (each
+HTTP-method handler → remoteProxy) and src/server/sockets (each socket
+declaration → socketProxy). Every OTHER module under src/server/ is server-only
+and must never reach the browser bundle.
+
+Expressed as bare `src/server/`-relative segments so each caller joins them
+against its own base — the resolver plugin against the absolute serverDir, the
+dev orchestrator's changeAffectsClient against the `server/` string prefix —
+rather than re-spelling the set. Adding a proxied directory is one edit here and
+both side-classifiers move in lockstep.
+*/
+export const PROXIED_SERVER_SUBDIRS = ['rpc', 'sockets'] as const

package/src/lib/shared/REF_JSON_TAGS.ts

@@ -26,6 +26,18 @@ export const REF_JSON_TAGS = {
     BIGINT: '~g',
     // ['~u'] — undefined (and functions/symbols, folded to it).
     UNDEFINED: '~u',
-    // ['~n', token] — the numbers JSON flattens to null: 'NaN' | 'Infinity' | '-Infinity' | '-0'.
+    // ['~n', token] — the numbers JSON flattens to null; the token is one of REF_JSON_NUMBER_TOKENS.
     NUMBER: '~n',
 } as const
+
+/*
+The tokens carried by a `['~n', token]` tag — the numbers JSON can't represent. Shared by
+`encodeRefJson`'s `numberToken` (produces them) and `decodeRefJson`'s `decodeNumberToken`
+(parses them) so the wire form can't drift between the two ends.
+*/
+export const REF_JSON_NUMBER_TOKENS = {
+    NAN: 'NaN',
+    INFINITY: 'Infinity',
+    NEG_INFINITY: '-Infinity',
+    NEG_ZERO: '-0',
+} as const

package/src/lib/shared/RPC_SHIM_GLOBALS.ts

@@ -0,0 +1,9 @@
+/*
+The reserved global alias names the `$rpc`/`$socket` module rewrites target: the bundler's
+banner binds each (`import { defineRpc as __abideDefineRpc__ }`, see abideResolverPlugin) and
+the codegen emit (`prepareRpcModule` / `prepareSocketModule`) calls it. Shared so the emitted
+call and the banner binding can't drift into an unbound-name ReferenceError at load.
+*/
+export const DEFINE_RPC_GLOBAL = '__abideDefineRpc__'
+export const REMOTE_PROXY_GLOBAL = '__abideRemoteProxy__'
+export const DEFINE_SOCKET_GLOBAL = '__abideDefineSocket__'

package/src/lib/shared/activeCacheStore.ts

@@ -7,5 +7,6 @@ lazily-created fallback when none is registered (so isolated tests work). The
 fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activeCacheStore(): CacheStore {
+    // biome-ignore lint/style/noNonNullAssertion: the slot's lazy fallback creator always returns a store
     return cacheStoreSlot.get()!
 }

package/src/lib/shared/activePage.ts

@@ -7,5 +7,6 @@ single lazily-created empty snapshot when none is registered (so isolated tests
 work). The fallback creator guarantees a value, hence the non-null assertion.
 */
 export function activePage(): PageSnapshot {
+    // biome-ignore lint/style/noNonNullAssertion: the slot's lazy fallback creator always returns a snapshot
     return pageSlot.get()!
 }

package/src/lib/shared/buildArtifact.ts

@@ -0,0 +1,20 @@
+import type { BuildConfig, BuildOutput } from 'bun'
+import { exitOnBuildFailure } from './exitOnBuildFailure.ts'
+
+/*
+Runs one Bun.build and fails the process on any diagnostic, returning the
+successful output — the build-or-die pairing every one-shot build site shares
+(compile, buildCli's discovery + cli, bundleApp, buildDisconnected). Keeps the
+`Bun.build` + `exitOnBuildFailure` step atomic so a new build site can't ship
+without the failure check. The incremental client build (build.ts) does NOT use
+this: it must clean its staging dir and return `false` rather than exit, so it
+keeps its own epilogue.
+*/
+export async function buildArtifact(config: BuildConfig): Promise<BuildOutput> {
+    /* metafile: true so the abideResolverPlugin's onEnd reachability guard (ADR-0022 D3) can read
+       the post-DCE graph on a client build (buildDisconnected). Harmless extra output on the
+       server builds that also route through here. A caller can still override it explicitly. */
+    const result = await Bun.build({ metafile: true, ...config })
+    exitOnBuildFailure(result)
+    return result
+}

package/src/lib/shared/buildRpcRequest.ts

@@ -68,8 +68,12 @@ function appendQuery(method: HttpMethod, url: string, args: unknown): string {
     if (args === undefined) {
         return url
     }
-    if (typeof args !== 'object' || args === null || Array.isArray(args)) {
-        const got = Array.isArray(args) ? 'array' : typeof args
+    const isFormData = typeof FormData !== 'undefined' && args instanceof FormData
+    if (typeof args !== 'object' || args === null || Array.isArray(args) || isFormData) {
+        /* FormData has no own enumerable keys, so `queryStringFromArgs` would silently drop
+           every field; a query-carrying method (GET/DELETE/HEAD) can't take a body anyway.
+           Fail loudly like any other non-plain-object arg. */
+        const got = Array.isArray(args) ? 'array' : isFormData ? 'FormData' : typeof args
         throw new Error(`[abide] ${method} ${url} args must be a plain object — got ${got}`)
     }
     const suffix = queryStringFromArgs(args as Record<string, unknown>, false)

package/src/lib/shared/buildSocketOverChannel.ts

@@ -63,9 +63,10 @@ export function buildSocketOverChannel<T>(
     const socket = {
         name,
         clients: browserClientFlags,
-        /* `broadcast` sends a server-validated `pub` frame (the dispatcher gates it on the
-           topic's `clientPublish`); `publish` is the internal channel-send function name. */
-        broadcast: publish,
+        /* `publish` sends a server-validated `pub` frame (the dispatcher gates it on the
+           topic's `clientPublish`), mirroring Bun's `server.publish()`; the internal
+           channel-send function shares the name. */
+        publish,
         tail: (count?: number, hooks?: TailHooks) => iterate(count, hooks),
         /* The latest frame this client has seen, synchronously. */
         peek: () => lastFrame,

package/src/lib/shared/bundleGraphFromMetafile.ts

@@ -0,0 +1,68 @@
+import { resolve } from 'node:path'
+import type { BuildMetafile } from 'bun'
+
+/* One surviving module in the post-DCE bundle graph: its absolute path and input source byte
+   size. `bytes` is the metafile's `inputs[key].bytes` — the source weight the budget diagnostic
+   measures (a tree-shaken module is absent from the metafile entirely, so every module here
+   SURVIVED into the bundle). */
+type BundleGraphModule = {
+    path: string
+    bytes: number
+}
+
+/*
+The post-DCE module graph reconstructed from a client build's `Bun.build` metafile — the reusable
+analysis seam ADR-0031 D2 factors out. `metafile.inputs` is the DCE-accurate graph (a
+textually-imported but tree-shaken module is ABSENT), so a single walk yields both the surviving
+modules and their child→importer edges; consumers then judge the graph without re-walking it.
+Two ride it today: the side-crossing reachability guard (a surviving server-only module is a
+violation) and the bundle-budget diagnostic (a surviving input over a size budget is a warning).
+The metafile carries module presence + input byte size, NOT export-level liveness — so a consumer
+can judge "this module survived / is this big", not "this export is unused" (ADR-0031 D2 spike).
+*/
+export type BundleGraph = {
+    /* Every module present in the post-DCE graph, keyed by absolute path. */
+    modules: BundleGraphModule[]
+    /* The import chain from a graph root down to `target`, in root→target order (absolute paths),
+       reconstructed from the graph's own first-wins child→importer edges — one witness, cycle-safe.
+       Returns `[target]` when nothing imports it (a graph root). */
+    importerChain(target: string): string[]
+}
+
+/*
+Walks a client build's metafile once into a `BundleGraph`. `inputs` keys are relative to
+`process.cwd()` while edge `path`s are absolute, so each module path is resolved against `cwd` to
+match on absolute paths throughout. First edge wins for the importer map — enough to render one
+witness chain, and cheap.
+*/
+export function bundleGraphFromMetafile(metafile: BuildMetafile, cwd: string): BundleGraph {
+    const modules: BundleGraphModule[] = []
+    /* child(absolute) → its importer(absolute); first edge wins — one witness chain. */
+    const importerOf = new Map<string, string>()
+    for (const [key, input] of Object.entries(metafile.inputs)) {
+        const modulePath = resolve(cwd, key)
+        modules.push({ path: modulePath, bytes: input.bytes })
+        for (const edge of input.imports) {
+            if (!importerOf.has(edge.path)) {
+                importerOf.set(edge.path, modulePath)
+            }
+        }
+    }
+    return {
+        modules,
+        importerChain(target) {
+            const chain = [target]
+            const seen = new Set([target])
+            let cursor = target
+            while (importerOf.has(cursor)) {
+                cursor = importerOf.get(cursor) as string
+                if (seen.has(cursor)) {
+                    break
+                }
+                seen.add(cursor)
+                chain.push(cursor)
+            }
+            return chain.reverse()
+        },
+    }
+}