@abide/abide 0.41.1 → 0.43.0

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

@@ -68,9 +68,10 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
 
     /*
     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 and stays cached as failed by ensureLoaded). Each face maps
-    the failure kind to its own rendering: sub emits err+end frames, pub
+    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(
@@ -200,10 +201,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         send(ws, { type: 'end', sub: frame.sub })
     }
 
-    async function handlePub(
-        ws: ServerWebSocket<unknown>,
-        frame: Extract<SocketClientFrame, { type: 'pub' }>,
-    ): Promise<void> {
+    async function handlePub(frame: Extract<SocketClientFrame, { type: 'pub' }>): Promise<void> {
         const resolution = await resolveEntry(frame.socket)
         if ('failure' in resolution) {
             return
@@ -233,11 +231,6 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         } catch (publishError) {
             abideLog.error(publishError)
         }
-        /*
-        ws parameter retained for future per-ws auth context (cookies on
-        upgrade) the canPublish hook would consult.
-        */
-        void ws
     }
 
     /*
@@ -252,7 +245,8 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
            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.
+    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))
@@ -266,6 +260,13 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
                 : 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
@@ -338,7 +339,7 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
                 return
             }
             if (frame.type === 'pub') {
-                void handlePub(ws, frame)
+                void handlePub(frame)
                 return
             }
         },

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

@@ -1,4 +1,4 @@
-import type { HttpVerb } from '../../../shared/types/HttpVerb.ts'
+import type { HttpMethod } from '../../../shared/types/HttpMethod.ts'
 
 /*
 One operation a socket exposes to the non-browser surfaces. A socket
@@ -18,5 +18,5 @@ export type SocketOperation = {
     // HTTP face of the operation: `/__abide/sockets/<name>`.
     restUrl: string
     // GET for tail, POST for publish.
-    method: HttpVerb
+    method: HttpMethod
 }

package/src/lib/shared/HttpError.ts

@@ -9,12 +9,26 @@ export class HttpError extends Error {
     readonly status: number
     readonly statusText: string
     readonly response: Response
+    /* Set when the handler returned a typed error (`error(errors.x(...))`) or a
+       validation 422: `kind` is the declared error name (or 'validation'), `data` the
+       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). */
+    readonly kind?: string
+    readonly data?: unknown
 
-    constructor(response: Response) {
+    constructor(response: Response, kind?: string, data?: unknown) {
         super(`HTTP ${response.status} ${response.statusText || 'error'}`)
         this.name = 'HttpError'
         this.status = response.status
         this.statusText = response.statusText
         this.response = response
+        this.kind = kind
+        this.data = data
     }
 }

package/src/lib/shared/UNREACHABLE_STATUSES.ts

@@ -0,0 +1,13 @@
+/*
+HTTP statuses that mean "the server didn't process this request" — the gateway /
+availability family. A response with one of these is treated like a transport failure
+by a durable RPC: the call still throws (the error framework is unchanged), and the
+request is parked for replay on recovery. Everything else (4xx, 500, …) means the
+server received and handled it — that flows to the error framework, never the outbox.
+
+  502 Bad Gateway · 503 Service Unavailable · 504 Gateway Timeout (abide's own client
+  timeout surfaces here too) · 520–527, 530 — Cloudflare/CDN origin-unreachable.
+*/
+export const UNREACHABLE_STATUSES: ReadonlySet<number> = new Set([
+    502, 503, 504, 520, 521, 522, 523, 524, 525, 526, 527, 530,
+])

package/src/lib/shared/buildRpcRequest.ts

@@ -2,11 +2,11 @@ import { carriesBodyArgs } from './carriesBodyArgs.ts'
 import { encodeRefJson } from './encodeRefJson.ts'
 import { queryStringFromArgs } from './queryStringFromArgs.ts'
 import { REF_JSON_HEADER } from './REF_JSON_HEADER.ts'
-import type { HttpVerb } from './types/HttpVerb.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
 
 /*
-Builds the Request a verb helper uses to invoke its handler. Same shape on
-both sides (server defineVerb + client remoteProxy) so the cache key
+Builds the Request a rpc helper uses to invoke its handler. Same shape on
+both sides (server defineRpc + client remoteProxy) so the cache key
 derivation and SSR snapshot round-trip identically. $rpc URLs are flat
 (no `:name` segments): GET/DELETE/HEAD serialise args onto the query
 string; POST/PUT/PATCH send them as application/json.
@@ -24,7 +24,7 @@ export function buildRpcRequest({
     baseUrl,
     headers,
 }: {
-    method: HttpVerb
+    method: HttpMethod
     url: string
     args: unknown
     baseUrl: string
@@ -64,7 +64,7 @@ export function buildRpcRequest({
     })
 }
 
-function appendQuery(method: HttpVerb, url: string, args: unknown): string {
+function appendQuery(method: HttpMethod, url: string, args: unknown): string {
     if (args === undefined) {
         return url
     }

package/src/lib/shared/cache.ts

@@ -180,8 +180,8 @@ export function cache<Args, Return>(
         }
         /*
         Warm path: a value pre-decoded onto the entry — by the SSR cache
-        snapshot the client seeds its store from, or by a cache.on().patch
-        broadcast — is served without a network round-trip. It resolves on a
+        snapshot the client seeds its store from — is served without a network
+        round-trip. It resolves on a
         microtask (a settled Promise), not synchronously, so every cache() read
         is uniformly `Promise<Return>` and `.then`/`.catch`/`.finally` chain
         cleanly. Raw callers take the Response path; after an invalidate the
@@ -337,7 +337,7 @@ function invokeRemote<Args>(
     const request = getRemoteMeta(promise)
     if (!request) {
         throw new Error(
-            '[abide] cache() received a function whose call did not record metadata — was it produced by a verb helper?',
+            '[abide] cache() received a function whose call did not record metadata — was it produced by a rpc helper?',
         )
     }
     registerEntry(store, key, promise, options, request, () => rawFn(args as Args))
@@ -512,24 +512,30 @@ function invalidate<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args
     const matches = selectorMatcher(arg, args, prefix)
     invalidateTripwire(selectorLabel(arg, args, prefix))
     for (const store of cacheStores()) {
+        const matched: string[] = []
         const affected: string[] = []
         /* Deleting the current entry mid-iteration is spec-safe on a Map; no snapshot needed. */
         for (const entry of store.entries.values()) {
             if (!matches(entry)) {
                 continue
             }
+            matched.push(entry.key)
             if (entry.invalidation) {
                 scheduleInvalidationRefetch(store, entry)
             } else {
                 store.entries.delete(entry.key)
-                /* Mark so the next read of this key reports as a reload via refreshing(). */
-                store.pendingRefresh.add(entry.key)
+                /* Flag the next read a reload (refreshing()) — but only if a reader is
+                   holding the value now; with none on screen the next read is a first
+                   load, and an ungated add would linger forever on the tab store. */
+                if (store.hasReader(entry.key)) {
+                    store.pendingRefresh.add(entry.key)
+                }
                 affected.push(entry.key)
             }
-            store.markLifecycle(entry.key)
         }
-        emit(store, affected)
-        store.markLifecycle()
+        /* Every match changed state (probes re-derive); only the dropped subset
+           changed its visible value (readers re-read) — swr matches stay put. */
+        notify(store, matched, affected)
     }
 }
 
@@ -555,94 +561,6 @@ function selectorLabel<Args, Return>(
 
 cache.invalidate = invalidate
 
-type EntryWrite = { store: CacheStore; entry: CacheEntry; prior: unknown; next: unknown }
-
-/*
-Core value-fold shared by the authoritative (cache.on context.patch) and
-optimistic (cache.patch) write paths. Folds `updater` into every decoded remote
-entry matching the selector, writing the result to entry.value so the warm-sync
-read path serves it and emitting the keys so readers re-run (ADR-0007). Only
-entry.value is written; entry.promise is left untouched so raw readers of the
-same key keep reading the wire Response. Producer entries (no request) are
-skipped — patching is a decoded-value operation. The current value is entry.value
-when warm (hydrated or already patched), else the entry's settled Response decoded
-— hence async; the first fold of a live-fetched entry hops a decode, subsequent
-ones are synchronous. Returns the keys touched (the cache.on context registers
-them for reconnect resync) and a `restore` that reverts each write iff it still
-stands — the optimistic path runs it on a rejected call, the authoritative path
-discards it (a broadcast is truth, never undone).
-*/
-async function foldEntries<Args, Return>(
-    arg: CacheSelector<Args, Return>,
-    updater: (current: Return) => Return,
-    args: Args | undefined,
-    prefix: string | undefined,
-): Promise<{ touched: string[]; restore: () => void }> {
-    const matches = selectorMatcher(arg, args, prefix ?? selectorPrefix(arg, args))
-    const touched: string[] = []
-    const writes: EntryWrite[] = []
-    for (const store of cacheStores()) {
-        const affected: string[] = []
-        for (const entry of store.entries.values()) {
-            if (!matches(entry) || entry.request === undefined) {
-                continue
-            }
-            const prior = entry.value
-            const current = (prior ??
-                (await decodeResponse(
-                    await shareable(entry.promise as Promise<Response>),
-                ))) as Return
-            const next = structuredClone(updater(current))
-            entry.value = next
-            entry.settled = true
-            entry.refreshing = false
-            store.markLifecycle(entry.key)
-            affected.push(entry.key)
-            writes.push({ store, entry, prior, next })
-        }
-        emit(store, affected)
-        store.markLifecycle()
-        touched.push(...affected)
-    }
-    return { touched, restore: () => revertWrites(writes) }
-}
-
-/*
-Reverts each optimistic write iff entry.value still holds it — a refetch or a
-later write that already replaced it is the newer truth and is left intact — then
-notifies readers of the reverted keys per store.
-*/
-function revertWrites(writes: EntryWrite[]): void {
-    const reverted = new Map<CacheStore, string[]>()
-    for (const { store, entry, prior, next } of writes) {
-        if (store.entries.get(entry.key) !== entry || entry.value !== next) {
-            continue
-        }
-        entry.value = prior
-        store.markLifecycle(entry.key)
-        reverted.set(store, [...(reverted.get(store) ?? []), entry.key])
-    }
-    for (const [store, keys] of reverted) {
-        emit(store, keys)
-        store.markLifecycle()
-    }
-}
-
-/*
-The authoritative-broadcast fold: a cache.on frame is the truth, so foldEntries'
-write stands (no rollback) and only the touched keys are returned for coverage.
-*/
-async function patchEntries<Args, Return>(
-    arg: CacheSelector<Args, Return>,
-    updater: (current: Return) => Return,
-    args?: Args,
-    /* The caller (on().patch) resolves the prefix for its coverage label; reuse it so selectorPrefix runs once per fold. */
-    prefix?: string,
-): Promise<string[]> {
-    const { touched } = await foldEntries(arg, updater, args, prefix)
-    return touched
-}
-
 /*
 Event-driven cache maintenance: subscribes to a Subscribable (socket or rpc
 stream) and runs `handler` once per frame — the declarative home for "this
@@ -685,21 +603,6 @@ function on<T>(
             coverage.set(selectorLabel(arg, args), () => invalidate(arg, args))
             invalidate(arg, args)
         },
-        /*
-        Register the selector (not the delta) for reconnect: a discarded delta
-        can't be replayed, so a transport gap resyncs the patched keys by full
-        invalidate — reusing the same coverage machinery as invalidate above.
-        */
-        patch<Args, Return>(
-            arg: CacheSelector<Args, Return>,
-            updater: (current: Return) => Return,
-            args?: Args,
-        ): Promise<string[]> {
-            /* Resolve the prefix once; the coverage label and patchEntries both consume it. */
-            const prefix = selectorPrefix(arg, args)
-            coverage.set(selectorLabel(arg, args, prefix), () => invalidate(arg, args))
-            return patchEntries(arg, updater, args, prefix)
-        },
         signal: controller.signal,
     }
     /* `let`: the reconnect path swaps in a fresh iterator; dispose closes the current one. */
@@ -741,56 +644,6 @@ function on<T>(
 
 cache.on = on
 
-/*
-Optimistic write: applies `updater` as a prediction now — the reactive read
-shows it immediately — runs `call`, then reconciles. On resolve the server is
-the truth: the prediction is dropped and the selector invalidated, so the value
-refetches authoritatively, coalesced per the read's own swr window
-(cache(fn, { swr: { throttle } }) bounds an optimistic-write storm with no
-extra knob here; without swr it is a plain drop-and-refetch). On reject the
-prediction rolls back. The returned promise is transparent over `call` —
-resolves to `call`'s value (the mutation result, e.g. a created id), rejects
-with its error, settling only after the cache reflects the reconciled state: an
-explicit await reads truth, an ignored call is fire-and-forget (a pre-attached
-catch keeps an un-awaited rejection from surfacing as unhandled, while the await
-still receives it). `call` is required — a global authoritative write with no
-reconciling op would let a caller author cache values, breaking the
-producer-is-the-source invariant (ADR-0001); that path stays cache.on's
-context.patch. Single-flight per key: rollback restores by snapshot, so keep one
-mutation per key in flight (disable the trigger while pending) — concurrent
-same-key optimism wants a layered entry value, deferred (ADR-0009). The reactive
-read holds the value; the return carries the mutation result — separate by
-design (ADR-0009).
-*/
-function patch<Args, Return, Result>(
-    arg: CacheSelector<Args, Return>,
-    updater: (current: Return) => Return,
-    call: Promise<Result>,
-    args?: Args,
-): Promise<Result> {
-    const prefix = selectorPrefix(arg, args)
-    const folded = foldEntries(arg, updater, args, prefix)
-    const settled = (async () => {
-        try {
-            const result = await call
-            /* Wait for the prediction to land before reconciling to server truth. */
-            await folded
-            invalidate(arg, args)
-            return result
-        } catch (error) {
-            const { restore } = await folded
-            restore()
-            throw error
-        }
-    })()
-    /* Ignore-safe: an un-awaited rejection must not report unhandled; an explicit
-       await still receives it (this no-op handler and the await both fire). */
-    settled.catch(() => undefined)
-    return settled
-}
-
-cache.patch = patch
-
 /*
 Schedules a coalesced refetch per the entry's swr policy. No window (swr: true):
 fire immediately (throttle defaults to 0, so the leading-edge branch always
@@ -852,8 +705,9 @@ function fireRefetch(store: CacheStore, entry: CacheEntry): void {
     }
     entry.refreshing = true
     policy.lastFiredAt = Date.now()
-    /* Ping lifecycle so refreshing() re-derives when revalidation begins; the settle handlers ping again when it ends. */
-    store.markLifecycle(entry.key)
+    /* Mark, don't emit: refreshing() re-derives when revalidation begins, but the
+       stale value is still on screen — the settle handlers emit once it lands. */
+    notify(store, [entry.key], [])
     const inflight = policy.refetch()
     inflight.then(
         (result) => {
@@ -876,8 +730,8 @@ function fireRefetch(store: CacheStore, entry: CacheEntry): void {
             if (entry.ttl !== undefined && entry.ttl !== 0) {
                 armTtlExpiry(store, entry, entry.ttl)
             }
-            store.markLifecycle(entry.key)
-            emit(store, [entry.key])
+            /* Fresh value landed — mark and emit so readers re-read. */
+            notify(store, [entry.key], [entry.key])
         },
         (error) => {
             entry.refreshing = false
@@ -925,11 +779,16 @@ so a live read replaces it and surfaces the proper error once.
 function settleRefetchFailure(store: CacheStore, entry: CacheEntry, status?: number): void {
     if (status === 404) {
         evictIfCurrent(store, entry)
-        store.pendingRefresh.add(entry.key)
-        emit(store, [entry.key])
+        /* Same reader-gating as invalidate: only flag a reload if one is on screen. */
+        if (store.hasReader(entry.key)) {
+            store.pendingRefresh.add(entry.key)
+        }
+        /* Value gone — mark and emit so the next read replaces it. */
+        notify(store, [entry.key], [entry.key])
         return
     }
-    store.markLifecycle(entry.key)
+    /* Mark, don't emit: stale value kept, only the refreshing flag cleared. */
+    notify(store, [entry.key], [])
 }
 
 /* Folds new tags into an entry's existing set without duplicating them. */
@@ -970,6 +829,29 @@ function attachPolicy(
     entry.invalidation = { refetch, throttle: policy.throttle, debounce: policy.debounce }
 }
 
+/*
+The single notification seam, holding the cache's freshness invariant in one
+place instead of by hand at every mutation site. Two reader audiences, two
+channels: every key in `marked` had its state change, so the lifecycle channels
+fire and the pending()/refreshing() probes re-derive; only the keys in `emitted`
+had their VISIBLE value change, so the 'invalidate' event fires and the reading
+scope re-reads. The two sets diverge by design — a refetch start marks but does
+not emit (the stale value is still on screen), an invalidate-drop does both, an
+swr invalidate marks the whole match set while emitting only the dropped subset.
+The trailing store-wide mark fires even when nothing matched, so a bare probe
+still re-derives (to the same value); marks coalesce per microtask, so a key in
+both lists is not double work.
+*/
+function notify(store: CacheStore, marked: string[], emitted: string[]): void {
+    marked.forEach((key) => {
+        store.markLifecycle(key)
+    })
+    if (emitted.length > 0) {
+        emit(store, emitted)
+    }
+    store.markLifecycle()
+}
+
 function emit(store: CacheStore, keys: string[]): void {
     if (keys.length === 0) {
         return

package/src/lib/shared/carriesBodyArgs.ts

@@ -1,13 +1,13 @@
-import type { HttpVerb } from './types/HttpVerb.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
 
 /*
-Whether a verb carries its args in the request body (POST/PUT/PATCH) vs
+Whether a rpc carries its args in the request body (POST/PUT/PATCH) vs
 on the query string (GET/DELETE/HEAD). Single source for the split so the
 synthesized Request (buildRpcRequest), the handler-side parse (parseArgs),
 the cache key (keyForRemoteCall), and the OpenAPI doc can't disagree.
 */
-const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
+const BODY_METHODS = new Set<HttpMethod>(['POST', 'PUT', 'PATCH'])
 
-export function carriesBodyArgs(method: HttpVerb): boolean {
+export function carriesBodyArgs(method: HttpMethod): boolean {
     return BODY_METHODS.has(method)
 }

package/src/lib/shared/createCacheStore.ts

@@ -44,6 +44,13 @@ export function createCacheStore(): CacheStore {
                 events.removeEventListener('invalidate', onInvalidate)
                 if (subscribers.get(key) === registered) {
                     subscribers.delete(key)
+                    /* The reload marker is only ever consumed by the NEXT read of this
+                       key (registerEntry). With the last reactive reader gone there is
+                       no scope left to show refreshing() for it, and a future remount
+                       reads with nothing on screen — a first-ever load, not a reload.
+                       Drop the marker so the tab-scoped store can't accrete one per
+                       invalidated-but-never-reread key over a session. */
+                    pendingRefresh.delete(key)
                 }
             }
         })
@@ -96,6 +103,11 @@ export function createCacheStore(): CacheStore {
         entries,
         events,
         subscribe,
+        /* True while a reactive scope is reading this key — i.e. someone is holding
+           its value on screen. invalidate() gates its reload marker on this: a key
+           with no live reader has nothing to reload into, so the next read is a
+           first-ever load, not a refresh. */
+        hasReader: (key: string) => subscribers.has(key),
         trackLifecycle,
         markLifecycle,
         pendingRefresh,

package/src/lib/shared/createRemoteFunction.ts

@@ -5,7 +5,7 @@ import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { recordRemoteMeta } from './recordRemoteMeta.ts'
 import { subscribableFromResponse } from './subscribableFromResponse.ts'
 import type { ClientFlags } from './types/ClientFlags.ts'
-import type { HttpVerb } from './types/HttpVerb.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
 import type { RpcOptions } from './types/RpcOptions.ts'
@@ -13,7 +13,7 @@ import type { Subscribable } from './types/Subscribable.ts'
 
 /*
 Assembles the public RemoteFunction shape used identically by the
-server-side defineVerb (in-process handler invocation) and the
+server-side defineRpc (in-process handler invocation) and the
 client-side remoteProxy (network fetch). Centralising the wiring here
 keeps the call/raw/stream/fetch semantics — including WeakMap meta
 recording, Content-Type decode, and Subscribable derivation — in one
@@ -24,7 +24,7 @@ place so the two halves can't drift.
   base; client uses window.location. The result is memoised inside the
   per-call `getRequest` thunk so the Request is built at most once per
   call regardless of how many readers pull on it.
-- `invoke(args, getRequest)` actually runs the call: server defineVerb
+- `invoke(args, getRequest)` actually runs the call: server defineRpc
   runs the handler and ignores `getRequest`; client remoteProxy calls
   `fetch(getRequest())`. The thunk lets the server skip the Request
   allocation entirely on the SSR hot path — the only consumer that ever
@@ -35,10 +35,10 @@ place so the two halves can't drift.
   forwards the request through invoke().
 */
 export function createRemoteFunction<Args, Return>(opts: {
-    method: HttpVerb
+    method: HttpMethod
     url: string
     clients: ClientFlags
-    /* Server-side only: exempts a mutating verb from the router's same-origin CSRF gate. */
+    /* Server-side only: exempts a mutating rpc from the router's same-origin CSRF gate. */
     crossOrigin?: boolean
     buildRequest: (args: Args | undefined, opts?: RpcOptions) => Request
     invoke: (
@@ -75,7 +75,7 @@ export function createRemoteFunction<Args, Return>(opts: {
     }
 
     /*
-    A body verb may receive a FormData in place of typed Args (the upload
+    A body rpc may receive a FormData in place of typed Args (the upload
     escape hatch). It flows through dispatch only into buildRpcRequest /
     keyForRemoteCall, both of which take it as-is, so the cast to Args is a
     contained type lie — buildRpcRequest's `instanceof FormData` branch handles
@@ -103,6 +103,11 @@ export function createRemoteFunction<Args, Return>(opts: {
             raw(args as Args),
         )
     }
+    /* Uniform runtime guard for every rpc — the per-rpc data typing lives entirely in the
+       RpcErrorGuard<Errors> signature RemoteFunction projects onto it (Errors flows from the
+       rpc helper's declared type, not from here). */
+    callable.isError = (error: unknown, kind: string): boolean =>
+        error instanceof HttpError && error.kind === kind
     Object.defineProperty(callable, REMOTE_FUNCTION, { value: true })
     callable.fetch = parseArgsForFetch
         ? async (request: Request): Promise<Response> => {

package/src/lib/shared/decodeResponse.ts

@@ -1,6 +1,6 @@
 import { contentBodyKind } from './contentBodyKind.ts'
 import { contentTypeOf } from './contentTypeOf.ts'
-import { HttpError } from './HttpError.ts'
+import { httpErrorFor } from './httpErrorFor.ts'
 
 /*
 Decodes a Response into the natural body value based on Content-Type:
@@ -27,7 +27,7 @@ returns the underlying Response untouched.
 */
 export async function decodeResponse(response: Response): Promise<unknown> {
     if (!response.ok) {
-        throw new HttpError(response)
+        throw await httpErrorFor(response)
     }
     if (response.status === 204) {
         return undefined

package/src/lib/shared/detectRpcMethod.ts

@@ -0,0 +1,17 @@
+import type { HttpMethod } from './types/HttpMethod.ts'
+
+/*
+Reads the HTTP method of an $rpc module from its source. Every file under
+src/server/rpc/ follows the convention `export const <name> = GET(fn)` (the
+rpc helper picks the method, possibly with an explicit generic
+`GET<{…}>(fn)`), so the helper name at the export is the method. Returns
+undefined when no rpc export matches — the caller skips the file rather
+than guessing. Used by the rpc.d.ts codegen to type url() against
+query-carrying rpcs; matching the same convention the bundler rewrites
+keeps the two from drifting.
+*/
+const RPC_EXPORT = /export\s+const\s+\w+\s*=\s*(GET|POST|PUT|PATCH|DELETE|HEAD)\s*[<(]/
+
+export function detectRpcMethod(source: string): HttpMethod | undefined {
+    return (source.match(RPC_EXPORT)?.[1] as HttpMethod | undefined) ?? undefined
+}

package/src/lib/shared/emitLogRecord.ts

@@ -77,7 +77,7 @@ function formatClock(ts: number): string {
 
 /*
 Builds the record from the emission's own fields plus the ambient request
-scope (trace, elapsed, verb+path), then renders it through the active
+scope (trace, elapsed, method+path), then renders it through the active
 formatter. The scope is read at emission time so a record emitted from a
 stream-flush callback re-entered into the scope still carries its context.
 Internal seam shared by the public logger and the framework's closing-record
@@ -132,14 +132,14 @@ function consoleFor(level: LogRecord['level']): (...args: unknown[]) => void {
 
 /*
 The unified tsv line (the default format): tab-separated
-`<clock>	<trace8>	<verb path>	[channel] <message>	+0.00ms`. The
+`<clock>	<trace8>	<rpc path>	[channel] <message>	+0.00ms`. The
 wall-clock leads every line (each record carries `ts`); inside a request scope
 the trace column follows and the elapsed-at-emission timing trails; a closing
 record emitted outside one (asset hits sidestep the scope) pads a blank trace
 column and trails its serve duration instead, so request lines stay aligned
 whatever produced them. Every record speaks on a channel
 (the app name, 'abide', or a diagnostic channel), shown as a dim `[name]`
-tag opening the message field. The verb+path pair is one field — it's the
+tag opening the message field. The method+path pair is one field — it's the
 line's anchor unit — and the tag folds into the message field so field
 positions stay stable for cut/awk consumers.
 */

package/src/lib/shared/escapeRegex.ts

@@ -0,0 +1,9 @@
+/*
+Escapes the regex metacharacters in `value` so it can be embedded literally
+inside a `new RegExp(...)` pattern. Shared by the $rpc/$sockets import stripper,
+the resolver plugin's virtual-namespace matcher, and the SSR snippet-call
+rewriter so the same escaping is applied one way everywhere.
+*/
+export function escapeRegex(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}

package/src/lib/shared/extraForwardHeaders.ts

@@ -1,7 +1,7 @@
 /*
 App-configured inbound header names to forward onto in-process rpc Requests,
 on top of the built-in FORWARDED_HEADERS. Set once at boot from
-app.forwardHeaders so the SSR in-process path (defineVerb) and the MCP
+app.forwardHeaders so the SSR in-process path (defineRpc) and the MCP
 dispatcher honour the same list without re-reading app config per call. A
 module-level slot rather than threaded config because both call sites are deep
 in the request path and the value is fixed for the process lifetime.

package/src/lib/shared/fileName.ts

@@ -0,0 +1,9 @@
+/*
+The bare leaf filename of a path — directory stripped, extension kept —
+e.g. `users/list.ts` → `list.ts`. The extension-stripping `fileStem` builds on
+this; call sites that match a full filename (`layout.abide`, `page.abide`) use
+it directly so the leaf-grab is written one way.
+*/
+export function fileName(path: string): string {
+    return path.split('/').pop() ?? ''
+}