@abide/abide 0.46.0 → 0.47.0

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

@@ -1,9 +1,10 @@
-import type { BunRequest, Server } from 'bun'
+import type { Server } from 'bun'
 import { createMcpResourceServer } from '../../mcp/createMcpResourceServer.ts'
-import { setMcpResourceServer } from '../../mcp/mcpResourceServerSlot.ts'
+import { mcpResourceServerSlot } from '../../mcp/mcpResourceServerSlot.ts'
 import type { McpServer } from '../../mcp/types/McpServer.ts'
 import { abideLog } from '../../shared/abideLog.ts'
 import { basePathFromAppUrl } from '../../shared/basePathFromAppUrl.ts'
+import { baseSlot } from '../../shared/baseSlot.ts'
 import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
 import { CLI_PATH } from '../../shared/CLI_PATH.ts'
 import { DEV_HOT_PREFIX } from '../../shared/DEV_HOT_PREFIX.ts'
@@ -15,15 +16,15 @@ import { IDENTITY_PATH } from '../../shared/IDENTITY_PATH.ts'
 import { INSPECTOR_PATH } from '../../shared/INSPECTOR_PATH.ts'
 import { isDebugNegated } from '../../shared/isDebugNegated.ts'
 import { logClosingRecord } from '../../shared/logClosingRecord.ts'
+import { matchRoute } from '../../shared/matchRoute.ts'
+import { normalizePathname } from '../../shared/normalizePathname.ts'
 import { OFFLINE_HEADER } from '../../shared/OFFLINE_HEADER.ts'
 import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
-import { responseBodyKind } from '../../shared/responseBodyKind.ts'
+import { parseRouteSegments } from '../../shared/parseRouteSegments.ts'
+import { requestScopeSlot } from '../../shared/requestScopeSlot.ts'
 import { SOCKETS_PATH } from '../../shared/SOCKETS_PATH.ts'
 import { setAppName } from '../../shared/setAppName.ts'
-import { setBaseResolver } from '../../shared/setBaseResolver.ts'
-import { setRequestScopeResolver } from '../../shared/setRequestScopeResolver.ts'
 import { TEXT_PLAIN } from '../../shared/TEXT_PLAIN.ts'
-import { toBunRoutePattern } from '../../shared/toBunRoutePattern.ts'
 import type { Layouts } from '../../ui/types/Layouts.ts'
 import type { Pages } from '../../ui/types/Pages.ts'
 import type { AppModule } from '../AppModule.ts'
@@ -49,6 +50,7 @@ import { devClientFingerprint } from './devClientFingerprint.ts'
 import { devHotModuleResponse } from './devHotModuleResponse.ts'
 import { devReloadResponse } from './devReloadResponse.ts'
 import { disableIdleTimeoutForStream } from './disableIdleTimeoutForStream.ts'
+import { finalizeResponse } from './finalizeResponse.ts'
 import { gzipResponse } from './gzipResponse.ts'
 import { installAmbientScopeStore } from './installAmbientScopeStore.ts'
 import { internalErrorResponse } from './internalErrorResponse.ts'
@@ -166,7 +168,7 @@ export async function createServer({
     `await`s they suspend on (see installAmbientScopeStore / CURRENT_SCOPE).
     */
     installAmbientScopeStore()
-    setRequestScopeResolver(() => {
+    requestScopeSlot.resolver = () => {
         const store = requestContext.getStore()
         if (!store) {
             return undefined
@@ -179,7 +181,7 @@ export async function createServer({
             /* The calling client's reported connectivity — drives server-side online(). Absent header = online. */
             online: !store.req.headers.has(OFFLINE_HEADER),
         }
-    })
+    }
     /*
     health() during an SSR render marks its request through this slot; the
     renderer stamps the health payload into __SSR__ only for marked requests,
@@ -206,10 +208,10 @@ export async function createServer({
     the server-side resolver so url() prefixes SSR-generated links, and rewrite
     the shell's framework `/_app` entry + css refs to carry the base — relative
     code-split chunks inherit it from the entry's own URL. '' (root mount) is a
-    no-op on both. See setBaseResolver / startClient for the client half.
+    no-op on both. See seedBootState / startClient for the client half.
     */
     const base = basePathFromAppUrl(process.env.APP_URL)
-    setBaseResolver(() => base)
+    baseSlot.resolver = () => base
     // Rebase the shell's rooted `/_app/` entry refs onto the mount base, matching
     // either quote style so a custom app.html using single quotes still rewrites.
     const activeShell = base
@@ -237,7 +239,7 @@ export async function createServer({
         buildPreloadManifest({ distDir, assets }),
     ])
     setRegistryManifests({ rpc, sockets, prompts })
-    setMcpResourceServer(createMcpResourceServer({ resourcesDir, mcpResources }))
+    mcpResourceServerSlot.server = createMcpResourceServer({ resourcesDir, mcpResources })
     const cliName = cliProgramName ?? 'app'
     /* The app's public identity, shared by the identity probe and the OpenAPI spec. */
     const appName = appInfo?.name ?? cliName
@@ -309,54 +311,40 @@ export async function createServer({
     /*
     Route dispatch — rpc-vs-page-vs-404 resolution and method matching — lives
     behind createRouteDispatcher; renderPage is injected so those decisions stay
-    testable without SSR. buildRoutes() below binds the returned handler per URL.
+    testable without SSR. The fetch handler resolves a request URL to a handler
+    through the shared matchRoute — the same matcher the client router runs —
+    so params decode and route precedence agree across the sides by
+    construction (no Bun routes table with its own pattern semantics).
     */
     const buildRouteHandler = createRouteDispatcher({ pages, rpc, renderPage })
 
     /*
-    Page URLs (folder paths, e.g. `/media/[id]`) get translated to Bun's
-    pattern syntax (`/media/:id`) at registration. Bun's `*` wildcard
-    matches but does not capture into req.params, so for `[...rest]`
-    routes the catch-all value is reconstructed from the request URL by
-    slicing the pathname segments after the catch-all's pattern index.
-    The reconstructed value is set under the original name (e.g. `rest`)
-    so the page component's $props destructure stays consistent with the
-    file path. Page URLs and rpc URLs (always `/rpc/...`, flat) are
-    disjoint by construction, so a plain object needs no deduplication.
+    Handlers pre-bound per registered URL. rpc URLs are flat literals (always
+    `/rpc/...`), so they dispatch by direct lookup; page URLs carry `[name]` /
+    `[[name]]` / `[...rest]` segments and resolve through matchRoute. Page and
+    rpc URLs are disjoint by construction, so a request lands in exactly one.
     */
-    const routes: Record<string, (req: BunRequest) => Promise<Response>> = {}
-    for (const routeUrl of Object.keys(pages)) {
-        const handler = buildRouteHandler(routeUrl)
-        const { pattern, catchAllName } = toBunRoutePattern(routeUrl)
-        const catchAllIndex = catchAllName
-            ? routeUrl.split('/').findIndex((segment) => segment.startsWith('[...'))
-            : -1
-        /* Only catch-all routes copy req.params (to write the reconstructed
-           segment); plain routes pass it through — it's never mutated downstream. */
-        routes[pattern] =
-            catchAllName && catchAllIndex !== -1
-                ? (req) => {
-                      const pathParams = {
-                          ...((req.params as Record<string, string> | undefined) ?? {}),
-                      }
-                      const url = new URL(req.url)
-                      pathParams[catchAllName] = url.pathname
-                          .split('/')
-                          .slice(catchAllIndex)
-                          .join('/')
-                      return dispatchRequest(req, pathParams, handler, url)
-                  }
-                : (req) =>
-                      dispatchRequest(
-                          req,
-                          (req.params as Record<string, string> | undefined) ?? {},
-                          handler,
-                      )
-    }
+    const rpcHandlers = new Map<string, ReturnType<typeof buildRouteHandler>>()
     for (const routeUrl of Object.keys(rpc)) {
-        const handler = buildRouteHandler(routeUrl)
-        routes[routeUrl] = (req) => dispatchRequest(req, {}, handler)
+        rpcHandlers.set(routeUrl, buildRouteHandler(routeUrl))
+    }
+    const pageHandlers = new Map<string, ReturnType<typeof buildRouteHandler>>()
+    for (const routeUrl of Object.keys(pages)) {
+        /* A `[...rest]` consumes every remaining segment, so segments after it
+           can never constrain matching — the route would silently serve paths
+           it shouldn't. Fail at boot instead. */
+        const segments = parseRouteSegments(routeUrl)
+        const catchAllIndex = segments.findIndex(
+            (segment) => segment.kind === 'param' && segment.catchAll,
+        )
+        if (catchAllIndex !== -1 && catchAllIndex !== segments.length - 1) {
+            throw new Error(
+                `[abide] invalid page route ${routeUrl}: a [...name] catch-all must be the last segment`,
+            )
+        }
+        pageHandlers.set(routeUrl, buildRouteHandler(routeUrl))
     }
+    const pageRouteUrls = Object.keys(pages)
 
     function dispatchRequest(
         req: Request,
@@ -366,26 +354,15 @@ export async function createServer({
             pathParams: Record<string, string>,
             store: RequestStore,
         ) => Promise<Response>,
-        /* Pre-parsed by the fetch fallback; routes-table callers omit it. */
-        url?: URL,
+        url: URL,
     ): Promise<Response> {
         return runWithRequestScope(req, { app, logRequests, url }, async (store) => {
             const response = app?.handle
                 ? await app.handle(req, (next) => handler(next, pathParams, store))
                 : await handler(req, pathParams, store)
-            /* Classify the body once (S2) and thread it into both downstream
-               steps — gzip + the closing-record stream monitor — instead of
-               each re-deriving from the Content-Type. */
-            const kind = responseBodyKind(response)
-            store.responseStreaming = kind === 'streaming'
-            // Streaming bodies (sse/jsonl, socket tail) opt out of the idle timeout.
-            if (kind === 'streaming') {
-                server.timeout(req, 0)
-            }
-            /* Gzip compressible dynamic bodies (SSR HTML, rpc/json, 404) when the
-               client accepts it; streaming frame protocols and static assets are
-               passed through untouched (see gzipResponse). */
-            return gzipResponse(req, response, kind)
+            /* Wire handling — classify once, mark the stream monitor, exempt
+               streams from the idle timeout, gzip — lives in finalizeResponse. */
+            return finalizeResponse(req, response, store, () => server.timeout(req, 0))
         })
     }
 
@@ -431,8 +408,6 @@ export async function createServer({
                 },
             },
 
-            routes,
-
             async fetch(req, bunServer) {
                 const url = new URL(req.url)
                 /*
@@ -521,7 +496,7 @@ export async function createServer({
                         })
                     }
                     return devHotModuleResponse(
-                        decodeURIComponent(url.pathname.slice(DEV_HOT_PREFIX.length)),
+                        decodePathSegment(url.pathname.slice(DEV_HOT_PREFIX.length)),
                     )
                 }
                 /*
@@ -568,7 +543,7 @@ export async function createServer({
                     if (publishForbidden) {
                         return publishForbidden
                     }
-                    const name = decodeURIComponent(url.pathname.slice(SOCKETS_REST_PREFIX.length))
+                    const name = decodePathSegment(url.pathname.slice(SOCKETS_REST_PREFIX.length))
                     return dispatchRequest(
                         req,
                         {},
@@ -596,6 +571,49 @@ export async function createServer({
                         url,
                     )
                 }
+                /*
+                App routes — rpc by flat lookup, pages through the shared
+                matcher (the client router runs the same one). Matched AFTER
+                the `/__abide/*` plumbing above (a reserved namespace no app
+                route occupies) and BEFORE the root-level framework surfaces
+                (/openapi.json, /_app/, public/ files), so a page route
+                shadows a same-path public file — the precedence the Bun
+                routes table used to impose implicitly, now pinned here.
+                */
+                const rpcHandler = rpcHandlers.get(url.pathname)
+                if (rpcHandler) {
+                    return dispatchRequest(req, {}, rpcHandler, url)
+                }
+                /*
+                Pages match only in canonical slash form; a non-canonical
+                request (`/admin/`, `//admin`) that would match is 308'd to the
+                canonical URL instead of served. Serving it directly would hand
+                app.handle — the auth seam — a pathname the matcher silently
+                normalized away, so an exact-match guard on `/admin` never sees
+                the request it's guarding (the old Bun routes table 404'd these
+                forms; the redirect keeps the guard sound AND the URL friendly).
+                rpc URLs stay exact-match strict, as they always were.
+                */
+                const canonicalPathname = normalizePathname(url.pathname)
+                if (canonicalPathname !== url.pathname) {
+                    if (matchRoute(pageRouteUrls, canonicalPathname)) {
+                        return new Response(null, {
+                            status: 308,
+                            headers: {
+                                Location: `${canonicalPathname}${url.search}`,
+                                'Cache-Control': NO_STORE,
+                            },
+                        })
+                    }
+                } else {
+                    const matchedPage = matchRoute(pageRouteUrls, url.pathname)
+                    if (matchedPage) {
+                        const pageHandler = pageHandlers.get(matchedPage.route)
+                        if (pageHandler) {
+                            return dispatchRequest(req, matchedPage.params, pageHandler, url)
+                        }
+                    }
+                }
                 if (url.pathname === OPENAPI_PATH) {
                     return dispatchRequest(
                         req,
@@ -734,3 +752,15 @@ export async function createServer({
     }
     return server
 }
+
+/* Lenient percent-decode for the internal-route names above (dev hot-module
+   paths, socket names) — the same leniency matchRoute applies to page params.
+   A malformed escape (`/%`) keeps the raw text so the downstream lookup misses
+   naturally instead of a URIError escaping the fetch handler as a 500. */
+function decodePathSegment(segment: string): string {
+    try {
+        return decodeURIComponent(segment)
+    } catch {
+        return segment
+    }
+}

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

@@ -5,6 +5,7 @@ import { layoutChainForRoute } from '../../shared/layoutChainForRoute.ts'
 import { safeJsonForScript } from '../../shared/safeJsonForScript.ts'
 import { snapshotShippable } from '../../shared/snapshotShippable.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
+import type { SsrPayload } from '../../shared/types/SsrPayload.ts'
 import type { StreamedResolution } from '../../shared/types/StreamedResolution.ts'
 import { renderChain } from '../../ui/renderChain.ts'
 import { renderToStream } from '../../ui/renderToStream.ts'
@@ -115,7 +116,7 @@ export function createUiPageRenderer({
             app: appNameSlot.name,
             health,
             clientTimeout,
-        })
+        } satisfies SsrPayload)
         return `<script>window.__SSR__ = ${payload};</script>`
     }
 
@@ -142,7 +143,22 @@ export function createUiPageRenderer({
        build-time injector). A no-op when there are none or the shell carries no </head>. */
     function injectRoutePreloads(html: string, routeUrl: string): string {
         const links = routePreloadLinks(routeUrl)
-        return links === '' ? html : html.replace(HEAD_CLOSE_TAG, `${links}</head>`)
+        return links === '' ? html : html.replace(HEAD_CLOSE_TAG, () => `${links}</head>`)
+    }
+
+    /* The layout chain for a route is a pure function of routeUrl and the fixed `layouts`
+       map, so memoise it per route (like `preloadLinkCache`) instead of re-scanning and
+       re-sorting every layout key on every request. */
+    const layoutKeys = Object.keys(layouts)
+    const chainKeyCache = new Map<string, string[]>()
+    function chainKeysForRoute(routeUrl: string): string[] {
+        const cached = chainKeyCache.get(routeUrl)
+        if (cached !== undefined) {
+            return cached
+        }
+        const chain = layoutChainForRoute(routeUrl, layoutKeys)
+        chainKeyCache.set(routeUrl, chain)
+        return chain
     }
 
     async function renderPage(
@@ -166,7 +182,7 @@ export function createUiPageRenderer({
         }
         /* Outermost layout → … → page: load every applicable layout chunk plus the
            page, then render the chain as one document (shared block-id pass). */
-        const chainKeys = layoutChainForRoute(routeUrl, Object.keys(layouts))
+        const chainKeys = chainKeysForRoute(routeUrl)
         const views = await Promise.all([
             ...chainKeys.map((key) => layouts[key]?.().then((module) => module.default)),
             loadPage().then((module) => module.default),
@@ -193,9 +209,12 @@ export function createUiPageRenderer({
                 ),
                 routeUrl,
             )
+            /* Function replacer: the state script carries user cache data, and a string
+               replacement would interpret `$&`/`$'`-style patterns inside it. */
+            const state = await stateTag(routeUrl, params, store, inline)
             const withState = html.replace(
                 '</body>',
-                `${resumeSeedScript(ssr.resume)}${await stateTag(routeUrl, params, store, inline)}</body>`,
+                () => `${resumeSeedScript(ssr.resume)}${state}</body>`,
             )
             return new Response(withState, {
                 headers: {

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

@@ -1,5 +1,6 @@
 import { relative } from 'node:path'
 import { fileName } from '../../shared/fileName.ts'
+import { isLayoutFile } from '../../shared/isLayoutFile.ts'
 import { analyzeComponent } from '../../ui/compile/analyzeComponent.ts'
 import { compileComponent } from '../../ui/compile/compileComponent.ts'
 import { nearestProjectRoot } from '../../ui/compile/nearestProjectRoot.ts'
@@ -20,8 +21,7 @@ const GENERATED = /(^|\/)\.abide\//
 // page.abide / layout.abide are router-mounted, not `mountChild`-tracked, so they
 // can't hot-swap — they fold into `structure` (a reload) instead.
 function isPageOrLayout(moduleId: string): boolean {
-    const file = fileName(moduleId)
-    return file === 'page.abide' || file === 'layout.abide'
+    return fileName(moduleId) === 'page.abide' || isLayoutFile(moduleId)
 }
 
 /*
@@ -81,7 +81,7 @@ export async function devClientFingerprint({
             let bodyHash: string
             let hot = false
             try {
-                const isLayout = moduleId.endsWith('layout.abide')
+                const isLayout = isLayoutFile(moduleId)
                 bodyHash = Bun.hash(compileComponent(source, isLayout, moduleId)).toString(36)
                 hot = analyzeComponent(source).imports === '' && !isPageOrLayout(moduleId)
             } catch {

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

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path'
 import { NO_STORE } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { isLayoutFile } from '../../shared/isLayoutFile.ts'
 import { compileModule } from '../../ui/compile/compileModule.ts'
 
 // Reused across requests — strips the embedded author TypeScript to browser JS.
@@ -27,7 +28,7 @@ export async function devHotModuleResponse(moduleId: string): Promise<Response>
         return new Response('not found', { status: 404 })
     }
     const { code } = compileModule(source, {
-        isLayout: moduleId.endsWith('layout.abide'),
+        isLayout: isLayoutFile(moduleId),
         moduleId,
         hot: true,
     })

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

@@ -0,0 +1,32 @@
+import { responseBodyKind } from '../../shared/responseBodyKind.ts'
+import { gzipResponse } from './gzipResponse.ts'
+import type { RequestStore } from './types/RequestStore.ts'
+
+/*
+The wire-handling step every dynamic route's response crosses after its
+handler (and app.handle) returns. The body is classified once
+(responseBodyKind) and that one decision is threaded into every consumer, in
+order: the closing-record stream monitor (store.responseStreaming), the idle
+timeout — a streaming body (SSE / JSONL, socket tail) is opted out so a quiet
+stream isn't reaped mid-flight — and gzip, which compresses compressible
+dynamic bodies (SSR HTML, rpc/json, 404) when the client accepts it and
+passes streaming frame protocols and opaque bodies through untouched.
+`exemptIdleTimeout` is the server capability (server.timeout(req, 0))
+injected by createServer, so the sequencing is testable without a live
+socket. Framework plumbing endpoints answered before the request scope
+(inspector / dev-reload SSE) don't cross this seam — they opt out via
+disableIdleTimeoutForStream directly.
+*/
+export function finalizeResponse(
+    req: Request,
+    response: Response,
+    store: RequestStore,
+    exemptIdleTimeout: () => void,
+): Response {
+    const kind = responseBodyKind(response)
+    store.responseStreaming = kind === 'streaming'
+    if (kind === 'streaming') {
+        exemptIdleTimeout()
+    }
+    return gzipResponse(req, response, kind)
+}

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

@@ -1,3 +1,4 @@
+import { contentBodyKind } from '../../shared/contentBodyKind.ts'
 import { contentTypeOf } from '../../shared/contentTypeOf.ts'
 import { hasReplayableRequest } from '../../shared/hasReplayableRequest.ts'
 import { isStreamingResponse } from '../../shared/isStreamingResponse.ts'
@@ -51,8 +52,13 @@ export async function snapshotEntryFromCache(
     if (isStreamingResponse(response)) {
         return undefined
     }
-    const contentType = contentTypeOf(response.headers)
-    if (!isTextual(contentType)) {
+    /* Ship only a body the client's WARM read can consume — `json`/`text` per the single
+       `contentBodyKind` classification the live decoder uses. Gating on the same table (not a
+       private textual list) keeps warm read ≡ live read (ADR-0011): the private list shipped
+       `application/xml`, which `contentBodyKind` buckets as `binary` and the warm read defers
+       on, so that snapshot could never be consumed warm — a silent divergence. */
+    const kind = contentBodyKind(contentTypeOf(response.headers))
+    if (kind !== 'json' && kind !== 'text') {
         return undefined
     }
     /* Read a CLONE, not the original: a reader that captured this same `entry.promise`
@@ -74,8 +80,6 @@ export async function snapshotEntryFromCache(
         statusText: response.statusText,
         headers: Array.from(response.headers.entries()),
         body,
-        /* Deferred by the SSR resume path → seed the shipped body lazily (no hydration decode). */
-        lazy: entry.deferred === true ? true : undefined,
     }
 }
 
@@ -86,16 +90,3 @@ async function readSettled(promise: Promise<Response>): Promise<Response | undef
         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/socket.ts

@@ -1,5 +1,5 @@
+import type { Socket } from '../shared/types/Socket.ts'
 import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
-import type { Socket } from './sockets/types/Socket.ts'
 import type { SocketOptions } from './sockets/types/SocketOptions.ts'
 
 /*

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

@@ -4,14 +4,14 @@ import { decodeRefJson } from '../../shared/decodeRefJson.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { messageFromError } from '../../shared/messageFromError.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 { lookupSocket } from './lookupSocket.ts'
-import type { SocketClientFrame } from './types/SocketClientFrame.ts'
 import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
-import type { SocketServerFrame } from './types/SocketServerFrame.ts'
 
 // Reused across every inbound binary frame rather than allocated per message.
 const textDecoder = new TextDecoder()
@@ -36,6 +36,12 @@ 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
 }
 
 /*
@@ -150,8 +156,19 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             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
@@ -194,6 +211,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         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}`)
@@ -227,7 +245,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         the process down.
         */
         try {
-            entry.socket.publish(frame.message)
+            entry.socket.broadcast(frame.message)
         } catch (publishError) {
             abideLog.error(publishError)
         }
@@ -291,7 +309,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
             }
             try {
                 // publish() validates against the socket schema and throws on a bad payload.
-                entry.socket.publish(message)
+                entry.socket.broadcast(message)
             } catch (publishError) {
                 return error(422, messageFromError(publishError))
             }
@@ -304,7 +322,12 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         rest,
 
         open(ws) {
-            connections.set(ws, { subToSocket: new Map(), socketSubs: new Map() })
+            connections.set(ws, {
+                subToSocket: new Map(),
+                socketSubs: new Map(),
+                subEpochs: new Map(),
+                epoch: 0,
+            })
         },
 
         message(ws, data) {

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

@@ -1,13 +1,14 @@
+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 { 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 { Socket } from './types/Socket.ts'
 import type { SocketOptions } from './types/SocketOptions.ts'
-import type { SocketServerFrame } from './types/SocketServerFrame.ts'
 
 /*
 Server-side construction of a Socket. The bundler rewrites every
@@ -23,14 +24,18 @@ 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 —
+read/append — no timer runs in the background. `chat.broadcast(m)` is isomorphic —
 called server-side it both notifies in-process iterators and broadcasts
 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> {
-    const retention = opts.tail ?? 0
+    /* 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
     /*
@@ -150,8 +155,10 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
                     }
                 })
                 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(replay, buffer.length)
+                    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++) {
@@ -168,13 +175,25 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
         }
     }
 
-    const self: Socket<T> = {
+    const self = {
         name,
         clients,
-        publish,
+        /* `broadcast` is the public fan-out; `publish` remains the internal function name. */
+        broadcast: 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())
+            return buffer.length > 0 ? (buffer[buffer.length - 1] as BufferEntry).value : undefined
+        },
+        /* 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,

package/src/lib/server/sockets/types/SocketRegistryEntry.ts

@@ -1,6 +1,6 @@
 import type { ClientFlags } from '../../../shared/types/ClientFlags.ts'
+import type { Socket } from '../../../shared/types/Socket.ts'
 import type { StandardSchemaV1 } from '../../../shared/types/StandardSchemaV1.ts'
-import type { Socket } from './Socket.ts'
 
 /*
 Per-socket registry record. The Socket itself stays uniform between