@abide/abide 0.42.0 → 0.43.0

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

@@ -1,6 +1,6 @@
 import { abideLog } from '../../shared/abideLog.ts'
 import type { Pages } from '../../ui/types/Pages.ts'
-import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { rpcRegistry } from '../rpc/rpcRegistry.ts'
 import { socketRegistry } from '../sockets/socketRegistry.ts'
 import { ensureRegistriesLoaded } from './registryManifests.ts'
 
@@ -15,7 +15,7 @@ const redden = (text: string): string =>
     hasColor ? `${Bun.color('red', 'ansi-256')}${text}\x1b[39m` : text
 
 /*
-A declared inputSchema is what makes mcp/cli safe to advertise (see defineVerb /
+A declared inputSchema is what makes mcp/cli safe to advertise (see defineRpc /
 defineSocket), so a missing schema gets a red `·` to flag the declaration whose
 machine surfaces are gated behind it.
 */
@@ -127,12 +127,12 @@ export async function logExposedSurfaces(routing: { pages: Pages }): Promise<voi
     */
     const methodWidth = Math.max(
         'http'.length,
-        ...Array.from(verbRegistry.values(), (entry) => entry.remote.method.length),
+        ...Array.from(rpcRegistry.values(), (entry) => entry.remote.method.length),
     )
     const withMethod = (method: string, identifier: string): string =>
         method.padEnd(methodWidth + COLUMN_GAP) + identifier
 
-    const rpcRows = Array.from(verbRegistry.values(), (entry) => [
+    const rpcRows = Array.from(rpcRegistry.values(), (entry) => [
         withMethod(entry.remote.method, entry.remote.url),
         schemaCell(Boolean(entry.inputSchema)),
         flag(entry.clients.browser),

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

@@ -7,7 +7,7 @@ Process-wide slot for the rpc + sockets + prompts manifests. createServer
 assigns once at boot (right after the route table is built); the MCP
 server, the OpenAPI emitter, and prompt enumeration read it on first
 request so they can lazy-import every module and walk the
-verb/socket/prompt registries.
+rpc/socket/prompt registries.
 
 The slot pattern (mirrors getActiveServer) lets the framework-generated
 McpServer bind to the manifests at module scope while the loaders stay
@@ -29,7 +29,7 @@ export function setRegistryManifests(value: RegistryManifests): void {
 
 /*
 On first call, eagerly imports every rpc + socket + prompt module so
-defineVerb / defineSocket / definePrompt fire and populate the
+defineRpc / defineSocket / definePrompt fire and populate the
 registries. Idempotent — repeat calls reuse the same in-flight promise,
 so concurrent first requests (e.g. /openapi.json + an MCP tools/list)
 trigger exactly one load instead of racing to fire the full import set

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

@@ -9,7 +9,7 @@ export type InspectorCacheEntry = {
     key: string
     /* Lifecycle: 'settled' | 'in-flight' | 'refreshing'. */
     status: string
-    /* True when the entry stores a wire Response (a remote verb), false for a plain producer value. */
+    /* True when the entry stores a wire Response (a remote rpc), false for a plain producer value. */
     remote: boolean
     /* Retention ttl in ms; undefined = forever, 0 = dedupe-only. */
     ttl: number | undefined

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

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

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

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

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

@@ -3,7 +3,7 @@ import type { TraceContext } from '../../../shared/types/TraceContext.ts'
 
 /*
 Per-request state propagated through AsyncLocalStorage. Every field is
-populated once at the server's fetch boundary; helpers and verb-defined
+populated once at the server's fetch boundary; helpers and rpc-defined
 remote functions read from it without threading arguments through user code.
 The inbound request's AbortSignal is reached via `req.signal` rather than a
 separate field.

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

@@ -1,5 +1,5 @@
 import { abideLog } from '../../shared/abideLog.ts'
-import { verbRegistry } from '../rpc/verbRegistry.ts'
+import { rpcRegistry } from '../rpc/rpcRegistry.ts'
 import { socketRegistry } from '../sockets/socketRegistry.ts'
 import { ensureRegistriesLoaded } from './registryManifests.ts'
 
@@ -19,7 +19,7 @@ export async function warnUnguardedMcp(): Promise<void> {
         return
     }
     const isMcpExposed = (entry: { clients: { mcp: boolean } }): boolean => entry.clients.mcp
-    const exposed = [...verbRegistry.values(), ...socketRegistry.values()].filter(
+    const exposed = [...rpcRegistry.values(), ...socketRegistry.values()].filter(
         isMcpExposed,
     ).length
     if (exposed === 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,