@abide/abide 0.57.1 → 0.100.0

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

@@ -1,397 +0,0 @@
-import type { ServerWebSocket } from 'bun'
-import { AMEND_TOPIC_PREFIX } from '../../shared/AMEND_TOPIC_PREFIX.ts'
-import { abideLog } from '../../shared/abideLog.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'
-import { RESERVED_SOCKET_PREFIX } from '../../shared/RESERVED_SOCKET_PREFIX.ts'
-import type { SocketClientFrame } from '../../shared/types/SocketClientFrame.ts'
-import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
-import { error } from '../error.ts'
-import { json } from '../json.ts'
-import { sse } from '../sse.ts'
-import { amendFamilyEntry } from './amendFamilyEntry.ts'
-import { lookupSocket } from './lookupSocket.ts'
-import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
-import type { SocketRoutes } from './types/SocketRoutes.ts'
-
-// Reused across every inbound binary frame rather than allocated per message.
-const textDecoder = new TextDecoder()
-
-/* Socket REST-face spans (CLI/MCP tail + publish), opt-in via DEBUG=abide:sockets. */
-const socketsLog = abideLog.channel('abide:sockets')
-
-type SocketDispatcher = {
-    open(ws: ServerWebSocket<unknown>): void
-    message(ws: ServerWebSocket<unknown>, data: string | Buffer): void
-    close(ws: ServerWebSocket<unknown>): void
-    rest(req: Request, name: string): Promise<Response>
-}
-
-/*
-Per-connection state: which sockets this ws is currently subscribed to
-(at the Bun-topic level), and which `sub` ids map to which socket. One
-ws can hold multiple subs against the same socket (e.g. one seeded
-from the retained tail, one live-only); the Bun-topic subscription is reference-counted
-so we only `ws.unsubscribe` when the last local sub drops.
-*/
-type ConnectionState = {
-    subToSocket: Map<string, string>
-    socketSubs: Map<string, Set<string>>
-    /* Latest claim token per `sub` id. handleSub awaits the module load before
-       registering, so an unsub (delete) or a newer sub (higher token) landing
-       during that await must win — the resumed handler re-checks its token and
-       bails instead of registering a zombie subscription. */
-    subEpochs: Map<string, number>
-    epoch: number
-}
-
-/*
-Bridges the framework's socket registry to a single ws per client. All
-sockets multiplex over `/__abide/sockets`. Steady-state fan-out rides
-Bun's native `server.publish('socket:<name>', frame)` so the dispatcher
-is only on the path for sub/unsub bookkeeping and client-initiated pub
-validation; the published `msg` frames go from publisher to subscribers
-without touching JS per frame.
-
-`sub` opens a subscription: the requested slice of the retained tail
-is replayed directly to this ws, then the ws is added to the Bun
-topic. `unsub` drops the local sub and unsubscribes the ws from
-the Bun topic if no other local subs remain. `pub` validates the
-socket's `allowClientPublish` policy and calls `socket.publish` —
-which fans out to in-process iterators and republishes through Bun
-to other connected clients.
-
-Module-level lookups are cached per socket name: loading a socket
-module triggers its `defineSocket` call, which inserts into the
-registry. After that the dispatcher just reads the registry.
-*/
-export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher {
-    const connections = new WeakMap<ServerWebSocket<unknown>, ConnectionState>()
-
-    const ensureLoaded = memoizeByKey((name): Promise<void> | undefined => {
-        const loader = sockets[name]
-        return loader ? loader().then(() => undefined) : undefined
-    })
-
-    /*
-    Loads a socket module on first use and reads its registry entry — the
-    one statement of the load/lookup failure semantics. A throwing module is
-    logged here; memoizeByKey evicts the rejected load so the next frame
-    retries (a transient import failure doesn't poison the name). Each face
-    maps the failure kind to its own rendering: sub emits err+end frames, pub
-    drops silently, rest answers with HTTP errors.
-    */
-    async function resolveEntry(
-        name: string,
-    ): Promise<
-        | { entry: SocketRegistryEntry }
-        | { failure: 'unregistered' | 'load-failed' | 'no-export'; message: string }
-    > {
-        /* The amend value channel (ADR-0043) is a per-call reserved topic family: one synthetic,
-           subscribe-only entry serves every `__abide/amend/<key>` topic — the per-key Bun topic is
-           the sub frame's own name, and there is no module to load or tail to replay. Checked
-           before the generic reserved lookup, which would miss (no per-key registry entry). */
-        if (name.startsWith(AMEND_TOPIC_PREFIX)) {
-            return { entry: amendFamilyEntry }
-        }
-        /* A reserved `__abide/` topic has no user module to load — it is minted at boot into
-           the registry (ADR-0041), so skip the loader and read it straight from there. */
-        if (name.startsWith(RESERVED_SOCKET_PREFIX)) {
-            const reserved = lookupSocket(name)
-            return reserved
-                ? { entry: reserved }
-                : { failure: 'unregistered', message: `[abide] no socket registered at ${name}` }
-        }
-        const loader = ensureLoaded(name)
-        if (!loader) {
-            return { failure: 'unregistered', message: `[abide] no socket registered at ${name}` }
-        }
-        try {
-            await loader
-        } catch (loadError) {
-            abideLog.error(loadError)
-            return {
-                failure: 'load-failed',
-                message: messageFromError(loadError),
-            }
-        }
-        const entry = lookupSocket(name)
-        if (!entry) {
-            return {
-                failure: 'no-export',
-                message: `[abide] socket module at ${name} did not register a Socket export`,
-            }
-        }
-        return { entry }
-    }
-
-    function send(ws: ServerWebSocket<unknown>, frame: SocketServerFrame): void {
-        if (ws.readyState !== WebSocket.OPEN) {
-            return
-        }
-        ws.send(encodeRefJson(frame))
-    }
-
-    function addSub(state: ConnectionState, name: string, sub: string): boolean {
-        state.subToSocket.set(sub, name)
-        let subs = state.socketSubs.get(name)
-        if (!subs) {
-            subs = new Set()
-            state.socketSubs.set(name, subs)
-        }
-        const wasEmpty = subs.size === 0
-        subs.add(sub)
-        return wasEmpty
-    }
-
-    function removeSub(state: ConnectionState, sub: string): string | undefined {
-        const name = state.subToSocket.get(sub)
-        if (!name) {
-            return undefined
-        }
-        state.subToSocket.delete(sub)
-        const subs = state.socketSubs.get(name)
-        if (!subs) {
-            return undefined
-        }
-        subs.delete(sub)
-        if (subs.size === 0) {
-            state.socketSubs.delete(name)
-            return name
-        }
-        return undefined
-    }
-
-    async function handleSub(
-        ws: ServerWebSocket<unknown>,
-        state: ConnectionState,
-        frame: Extract<SocketClientFrame, { type: 'sub' }>,
-    ): Promise<void> {
-        // Reject this sub: emit the error then the terminal end frame for its id.
-        function fail(message: string): void {
-            send(ws, { type: 'err', sub: frame.sub, message })
-            send(ws, { type: 'end', sub: frame.sub })
-        }
-        /* Claim the sub id synchronously — the await below yields to other
-           frames on this connection. */
-        const token = ++state.epoch
-        state.subEpochs.set(frame.sub, token)
-        const resolution = await resolveEntry(frame.socket)
-        if (state.subEpochs.get(frame.sub) !== token) {
-            /* An unsub (already answered with `end`) or a newer sub for this id
-               won the race while the module loaded — registering now would leak
-               a subscription the client can never cancel. */
-            return
-        }
-        if ('failure' in resolution) {
-            state.subEpochs.delete(frame.sub)
-            return fail(resolution.message)
-        }
-        const { entry } = resolution
-        /* A client reusing a live `sub` id rebinds it: drop the prior binding first (and
-           unsubscribe its topic if that was the last local sub) so the old socket's Set
-           doesn't retain the id forever, leaking the topic subscription. */
-        const rebound = removeSub(state, frame.sub)
-        if (rebound) {
-            ws.unsubscribe(`socket:${rebound}`)
-        }
-        const isFirstLocalSub = addSub(state, frame.socket, frame.sub)
-        if (isFirstLocalSub) {
-            ws.subscribe(`socket:${frame.socket}`)
-        }
-        /*
-        Replay rides one per-sub `replay` frame (sent even when empty), not
-        socket-keyed msg frames: the batch demarcates replay from live for
-        the reader, and the per-sub address keeps this sub's replay out of
-        sibling subs on the same socket. Live messages flow through the Bun
-        topic the ws just joined; a frame published between the join and
-        this snapshot can appear in both, so user payloads should carry an
-        id/timestamp when ordering matters.
-
-        `replay === undefined` means the whole retained tail (`.tail()`
-        no-arg); a number is clamped to the buffer length so the client
-        can ask for "as many as available, up to N" — `0` (bare
-        `for await`) replays nothing.
-        */
-        /*
-        A non-finite `replay` (NaN/Infinity from a buggy client) would make
-        snapshotTail's slice(NaN) leak the whole retained buffer — coerce it
-        to undefined, matching the REST `?tail=` guard below.
-        */
-        const replay = Number.isFinite(frame.replay) ? frame.replay : undefined
-        send(ws, { type: 'replay', sub: frame.sub, messages: entry.snapshotTail(replay) })
-    }
-
-    function handleUnsub(
-        ws: ServerWebSocket<unknown>,
-        state: ConnectionState,
-        frame: Extract<SocketClientFrame, { type: 'unsub' }>,
-    ): void {
-        state.subEpochs.delete(frame.sub)
-        const emptied = removeSub(state, frame.sub)
-        if (emptied) {
-            ws.unsubscribe(`socket:${emptied}`)
-        }
-        send(ws, { type: 'end', sub: frame.sub })
-    }
-
-    async function handlePub(frame: Extract<SocketClientFrame, { type: 'pub' }>): Promise<void> {
-        const resolution = await resolveEntry(frame.socket)
-        if ('failure' in resolution) {
-            return
-        }
-        const { entry } = resolution
-        if (!entry.allowClientPublish) {
-            /*
-            Silent drop: the publish is rejected because the topic
-            wasn't declared `{ clientPublish: true }`. Surfacing this as
-            an error per-publish would tempt apps to attempt-then-handle
-            instead of routing through an HTTP route for auth. Log it
-            once per process at debug level (out of scope here) if
-            visibility is needed.
-            */
-            return
-        }
-        /*
-        publish() runs the topic's optional Standard Schema synchronously
-        and throws on failure (see validateSync in defineSocket.ts). The
-        dispatcher invokes us via `void handlePub(...)`, so an unhandled
-        throw would surface as an unhandled promise rejection on every
-        malformed client frame. Catch + log so a buggy client can't take
-        the process down.
-        */
-        try {
-            entry.socket.publish(frame.message)
-        } catch (publishError) {
-            abideLog.error(publishError)
-        }
-    }
-
-    /*
-    HTTP face of the sockets hub at `/__abide/sockets/<name>`, for the CLI
-    and MCP (which can't speak the ws multiplex protocol):
-
-      GET  text/event-stream → live SSE stream; `?tail=N` seeds with the
-           last N retained frames before tailing live (default 0 = live only).
-      GET  otherwise         → JSON array of the retained tail
-           (`?tail=N` caps it; default all).
-      POST                   → publish the JSON body, gated by the socket's
-           clientPublish policy and validated against its schema.
-
-    Loads the socket module on first hit (same cache the ws path uses) so
-    its defineSocket call populates the registry. A socket exposed to neither
-    mcp nor cli answers 404 here — its `clients` flags gate this surface.
-    */
-    async function rest(req: Request, name: string): Promise<Response> {
-        return socketsLog.trace(`socket-rest ${name}`, () => restImpl(req, name))
-    }
-
-    async function restImpl(req: Request, name: string): Promise<Response> {
-        const resolution = await resolveEntry(name)
-        if ('failure' in resolution) {
-            return resolution.failure === 'load-failed'
-                ? error(500, 'socket failed to load')
-                : error(404)
-        }
-        const { entry } = resolution
-        /* The REST face is the CLI/MCP transport (the browser uses the ws multiplex). A
-           socket advertised to neither non-browser surface has no REST consumer, so its
-           `clients` flags are access control here: 404 as if unmounted, not 403, so a
-           browser-only socket's existence doesn't leak over this surface. */
-        if (!entry.clients.mcp && !entry.clients.cli) {
-            return error(404)
-        }
-        const tailParam = new URL(req.url).searchParams.get('tail')
-        const parsedTail = tailParam !== null ? Number(tailParam) : undefined
-        // A non-numeric ?tail= yields NaN; treat it as absent rather than letting
-        // snapshotTail(NaN)/slice(NaN) leak the whole retained buffer.
-        const count =
-            parsedTail !== undefined && Number.isFinite(parsedTail) ? parsedTail : undefined
-        if (req.method === 'GET' || req.method === 'HEAD') {
-            if ((req.headers.get('accept') ?? '').includes('text/event-stream')) {
-                return sse(entry.socket.tail(count ?? 0))
-            }
-            return json(entry.snapshotTail(count))
-        }
-        if (req.method === 'POST') {
-            if (!entry.allowClientPublish) {
-                return error(403, 'publishing not allowed')
-            }
-            let message: unknown
-            try {
-                message = await req.json()
-            } catch {
-                return error(400, 'body must be JSON')
-            }
-            try {
-                // publish() validates against the socket schema and throws on a bad payload.
-                entry.socket.publish(message)
-            } catch (publishError) {
-                return error(422, messageFromError(publishError))
-            }
-            return json({ ok: true })
-        }
-        return error(405, undefined, { headers: { Allow: 'GET, POST' } })
-    }
-
-    return {
-        rest,
-
-        open(ws) {
-            connections.set(ws, {
-                subToSocket: new Map(),
-                socketSubs: new Map(),
-                subEpochs: new Map(),
-                epoch: 0,
-            })
-        },
-
-        message(ws, data) {
-            const state = connections.get(ws)
-            if (!state) {
-                return
-            }
-            const text = typeof data === 'string' ? data : textDecoder.decode(data)
-            let frame: SocketClientFrame
-            try {
-                /* 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
-            }
-            // both codecs yield a value for `null`/`42`/`true` too; ignore anything that isn't a frame object.
-            if (typeof frame !== 'object' || frame === null) {
-                return
-            }
-            if (frame.type === 'sub') {
-                void handleSub(ws, state, frame)
-                return
-            }
-            if (frame.type === 'unsub') {
-                handleUnsub(ws, state, frame)
-                return
-            }
-            if (frame.type === 'pub') {
-                void handlePub(frame)
-                return
-            }
-        },
-
-        close(ws) {
-            const state = connections.get(ws)
-            if (!state) {
-                return
-            }
-            connections.delete(ws)
-            for (const name of state.socketSubs.keys()) {
-                ws.unsubscribe(`socket:${name}`)
-            }
-        },
-    }
-}

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

@@ -1,225 +0,0 @@
-import { attachSocketSelectorMethods } from '../../shared/attachSocketSelectorMethods.ts'
-import { createPushIterator } from '../../shared/createPushIterator.ts'
-import { encodeRefJson } from '../../shared/encodeRefJson.ts'
-import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
-import { socketTailsSlot } from '../../shared/socketTailsSlot.ts'
-import { socketTapSlot } from '../../shared/socketTapSlot.ts'
-import type { Socket } from '../../shared/types/Socket.ts'
-import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
-import type { TailHooks } from '../../shared/types/TailHooks.ts'
-import { getActiveServer } from '../runtime/getActiveServer.ts'
-import { registerSocket } from './registerSocket.ts'
-import type { SocketOptions } from './types/SocketOptions.ts'
-
-/*
-Server-side construction of a Socket. The bundler rewrites every
-`export const NAME = socket(opts)` inside `src/server/sockets/<file>.ts` into
-`__abideDefineSocket__("<name>", opts)` so the file path becomes the
-socket's identity. Each subscriber gets its own queue + notifier, the
-optional retained tail is shared, and outbound fan-out rides Bun's
-native `server.publish` so connected ws clients are notified by the
-runtime in C rather than per-client iteration in JS.
-
-The Socket itself is the AsyncIterable: `for await (const m of chat)`
-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.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.
-*/
-// @documentation plumbing
-export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<T> {
-    /* Retention defaults to 1: the socket keeps its last frame so a late joiner, a
-       reconnect, and `.peek()` all have the current value to seed from. Bare iteration
-       still replays nothing (iterate(0) below) — a real-time `watch(socket, …)` reaction
-       must see only live frames, never re-process the retained one. `tail: 0` opts out. */
-    const retention = opts.tail ?? 1
-    const ttl = opts.ttl
-    const schema = opts.schema
-    /*
-    A schema makes the socket's payload safe to advertise to non-browser
-    surfaces, so it flips mcp/cli on by default — exposing the `tail` read
-    tool (and `publish` when clientPublish is set). Explicit `clients` wins.
-    */
-    const hasSchema = schema !== undefined
-    const clients = resolveClientFlags(opts.clients, { mcp: hasSchema, cli: hasSchema })
-    type BufferEntry = { value: T; expiresAt: number | undefined }
-    const buffer: BufferEntry[] = []
-    const subscribers = new Set<(message: T) => void>()
-    const topic = `socket:${name}`
-
-    /*
-    Retained frames are stored with an expiry timestamp. When `ttl` is set,
-    every read/append starts by dropping leading entries whose expiry has
-    passed — entries are appended in order so the expired prefix is
-    contiguous. No timer/setInterval is needed: expiry is lazy.
-    */
-    function pruneExpired(now: number): void {
-        if (ttl === undefined) {
-            return
-        }
-        let drop = 0
-        for (const entry of buffer) {
-            if (entry.expiresAt !== undefined && entry.expiresAt <= now) {
-                drop++
-            } else {
-                break
-            }
-        }
-        if (drop > 0) {
-            buffer.splice(0, drop)
-        }
-    }
-
-    /*
-    Active server is set once per process during createServer's boot,
-    immediately after Bun.serve resolves, and never reassigned. Resolve
-    it lazily on the first publish then keep the reference so subsequent
-    publishes skip the per-call getter.
-    */
-    let cachedServer: ReturnType<typeof getActiveServer>
-    /*
-    When a schema is attached, publish() validates synchronously and
-    throws on bad payloads. Standard Schema's validate() is generally
-    async — but for the synchronous server-side publish path we treat
-    a Promise return as a programming error (publish must be sync to
-    preserve in-process notify ordering). Schemas that need async
-    refinement should pre-validate at the call site instead.
-    */
-    function validateSync(message: T): T {
-        if (!schema) {
-            return message
-        }
-        const result = schema['~standard'].validate(message)
-        if (result instanceof Promise) {
-            throw new Error(
-                `[abide] socket "${name}" schema returned a Promise — sockets require sync validation`,
-            )
-        }
-        if (result.issues) {
-            throw new Error(
-                `[abide] socket "${name}" publish payload failed validation: ${JSON.stringify(result.issues)}`,
-            )
-        }
-        return result.value as T
-    }
-    function publish(message: T): void {
-        const validated = validateSync(message)
-        if (retention > 0) {
-            const now = Date.now()
-            pruneExpired(now)
-            buffer.push({ value: validated, expiresAt: ttl === undefined ? undefined : now + ttl })
-            if (buffer.length > retention) {
-                buffer.shift()
-            }
-        }
-        for (const notify of subscribers) {
-            notify(validated)
-        }
-        // Observe the fanned-out frame (inspector); no-op when unobserved.
-        socketTapSlot.tap?.({ socket: name, message: validated })
-        if (cachedServer === undefined) {
-            cachedServer = getActiveServer()
-        }
-        const server = cachedServer
-        /* Remote fan-out is the only consumer of the encoded frame: in-process iterators
-           already received the live object via notify() above. Skip the full message-graph
-           walk (encodeRefJson) + native publish when zero ws clients are subscribed to the
-           topic — subscriberCount is a cheap C-side check, encodeRefJson is not. */
-        if (server && server.subscriberCount(topic) > 0) {
-            /* Typed against the shared wire contract so a `SocketServerFrame` change can't
-               silently drift from this construction site (the dispatcher's `send` is already
-               typed; this was the last `msg` frame built through an unchecked JSON.stringify). */
-            const frame: SocketServerFrame = { type: 'msg', socket: name, message: validated }
-            // ref-json (matching the dispatcher + client) so a message graph with cycles/shared refs fans out intact.
-            server.publish(topic, encodeRefJson(frame))
-        }
-    }
-
-    /*
-    replay === 'all' replays the whole retained tail (`.tail()` no-arg);
-    a number replays the last min(count, buffer.length) items — `0` is
-    live-only, the bare `for await` behavior. `hooks.replayed` is queued
-    in-band after the replayed frames so a window reader commits its seed
-    atomically, strictly before any live frame.
-    */
-    function iterate(replay: number | 'all', hooks?: TailHooks): AsyncIterable<T> {
-        return {
-            [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {
-                let subscriber: ((message: T) => void) | undefined
-                const iter = createPushIterator<T>(() => {
-                    if (subscriber) {
-                        subscribers.delete(subscriber)
-                    }
-                })
-                pruneExpired(Date.now())
-                /* Floor: a fractional count (`?tail=1.5` over REST) must not
-                   produce a fractional buffer index. */
-                const replayCount =
-                    replay === 'all' ? buffer.length : Math.min(Math.floor(replay), buffer.length)
-                if (replayCount > 0) {
-                    const start = buffer.length - replayCount
-                    for (let index = start; index < buffer.length; index++) {
-                        iter.push((buffer[index] as BufferEntry).value)
-                    }
-                }
-                if (hooks?.replayed) {
-                    iter.control(hooks.replayed)
-                }
-                subscriber = (message: T) => iter.push(message)
-                subscribers.add(subscriber)
-                return iter
-            },
-        }
-    }
-
-    const self = {
-        name,
-        clients,
-        /* `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: () => {
-            pruneExpired(Date.now())
-            const value =
-                buffer.length > 0 ? (buffer[buffer.length - 1] as BufferEntry).value : undefined
-            /* Record the retained frame this SSR render read so the page renderer can ship it in
-               `__SSR__.sockets` — the client seeds `peek()` to the same value instead of undefined,
-               keeping hydration congruent. `get()` is undefined off-request (ws/boot), so this is a
-               no-op outside an SSR render; a `tail: 0` socket holds no frame and records nothing. */
-            if (value !== undefined) {
-                socketTailsSlot.get()?.entries.push({ name, value })
-            }
-            return value
-        },
-        /* No-op on the server: it is the source of truth, so there is nothing to re-pull. */
-        refresh: () => undefined,
-        /* Inert on the server: reaction is a client-only concern, and an author `socket.watch(…)`
-           that survives the SSR effect-strip must be a safe no-op here. Returns a disposer. */
-        watch: () => () => {},
-        [Symbol.asyncIterator]: () => iterate(0)[Symbol.asyncIterator](),
-    }
-    attachSocketSelectorMethods(self)
-    registerSocket({
-        socket: self as Socket<unknown>,
-        allowClientPublish: opts.clientPublish ?? false,
-        schema,
-        clients,
-        snapshotTail: (count?: number) => {
-            pruneExpired(Date.now())
-            /* A non-finite count (NaN/Infinity) would make slice() leak the whole
-               buffer — treat it as absent (full tail), the same as count === undefined. */
-            const start =
-                count === undefined || !Number.isFinite(count)
-                    ? 0
-                    : Math.max(0, buffer.length - count)
-            return buffer.slice(start).map((entry) => entry.value)
-        },
-    })
-    return self
-}

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

@@ -1,6 +0,0 @@
-import { socketRegistry } from './socketRegistry.ts'
-import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
-
-export function lookupSocket(name: string): SocketRegistryEntry | undefined {
-    return socketRegistry.get(name)
-}

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

@@ -1,18 +0,0 @@
-import { RESERVED_SOCKET_PREFIX } from '../../shared/RESERVED_SOCKET_PREFIX.ts'
-import { socketRegistry } from './socketRegistry.ts'
-import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
-
-export function registerSocket(entry: SocketRegistryEntry): void {
-    /* A reserved (__abide/) topic is framework-internal and server-publish-only. Enforce
-       that invariant at the one chokepoint every socket flows through: a reserved name can
-       never register with client publish enabled, so no later trusted-but-mistaken
-       defineSocket call can turn an internal topic into one a browser could forge frames on
-       (ADR-0041). The framework mints its reserved topics clientPublish:false, so this never
-       fires on the legitimate path; the boot scan separately rejects reserved user files. */
-    if (entry.socket.name.startsWith(RESERVED_SOCKET_PREFIX) && entry.allowClientPublish) {
-        throw new Error(
-            `[abide] socket "${entry.socket.name}" is reserved — the "${RESERVED_SOCKET_PREFIX}" namespace is framework-internal and cannot enable clientPublish.`,
-        )
-    }
-    socketRegistry.set(entry.socket.name, entry)
-}

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

@@ -1,36 +0,0 @@
-import { commandNameForUrl } from '../../shared/commandNameForUrl.ts'
-import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.ts'
-import type { SocketOperation } from './types/SocketOperation.ts'
-import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
-
-/*
-Projects a socket registry entry into the operations it exposes to the
-CLI and MCP. Single source for the naming convention (`<base>-tail` /
-`<base>-publish`), the existence rule (tail always; publish only when the
-socket allows client publishing), and each operation's HTTP face — so the
-CLI manifest builder, the MCP tool list, and the MCP tool dispatcher can't
-disagree about which operations a socket has or what they're called.
-*/
-export function socketOperations(entry: SocketRegistryEntry): SocketOperation[] {
-    const base = commandNameForUrl(entry.socket.name)
-    const restUrl = `${SOCKETS_PATH}/${entry.socket.name}`
-    const operations: SocketOperation[] = [
-        {
-            kind: 'tail',
-            name: `${base}-tail`,
-            socketName: entry.socket.name,
-            restUrl,
-            method: 'GET',
-        },
-    ]
-    if (entry.allowClientPublish) {
-        operations.push({
-            kind: 'publish',
-            name: `${base}-publish`,
-            socketName: entry.socket.name,
-            restUrl,
-            method: 'POST',
-        })
-    }
-    return operations
-}