@abide/abide 0.45.0 → 0.47.0

package/src/lib/shared/cache.ts

@@ -1,21 +1,22 @@
 import { abideLog } from './abideLog.ts'
 import { activeCacheStore } from './activeCacheStore.ts'
-import { CACHE_WRAPPED } from './CACHE_WRAPPED.ts'
 import { cacheStores } from './cacheStores.ts'
 import { decodeResponse } from './decodeResponse.ts'
 import { getRemoteMeta } from './getRemoteMeta.ts'
 import { globalCacheStore } from './globalCacheStore.ts'
 import { HttpError } from './HttpError.ts'
+import { hydratingSlot } from './hydratingSlot.ts'
 import { invalidateEvent } from './invalidateEvent.ts'
 import { invalidateTripwire } from './invalidateTripwire.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { producerKey } from './producerKey.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import { REPLAYABLE_METHODS } from './REPLAYABLE_METHODS.ts'
-import { recordCacheKey } from './recordCacheKey.ts'
+import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
+import { openStreamProbe } from './subscribableProbes.ts'
 import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheOnContext } from './types/CacheOnContext.ts'
@@ -57,16 +58,15 @@ function recordRead(sink: CacheStore, key: string, existing: CacheEntry | undefi
 }
 
 /*
-Curries a call against a cache store. `cache(fn, options?)` returns an invoker;
-calling that invoker with args checks the store for a prior entry and returns a
-shared promise on hit, or invokes `fn` once and stores its promise on miss.
-Splitting configuration (the outer call) from invocation (the inner call) keeps
-options anchored in a fixed position so they can't collide with arg shapes. TTL
-= undefined → forever; ttl = 0 → dedupe only; ttl > 0 → entry expires `ttl` ms
-after the promise resolves.
+Reads a call through a cache store. `cache(fn, args?, options?)` checks the store
+for a prior entry and returns a shared promise on hit, or invokes `fn` once and
+stores its promise on miss — a direct read-through call, not a curried invoker.
+Args lead (the common refinement); options trail in a fixed final position so
+they can't collide with arg shapes. TTL = undefined → forever; ttl = 0 → dedupe
+only; ttl > 0 → entry expires `ttl` ms after the promise resolves.
 
 Coalescing is always on: identical in-flight calls share one flight, so
-`cache(createPost, { ttl: 0 })` is the mutation idiom — double-submit
+`cache(createPost, args, { ttl: 0 })` is the mutation idiom — double-submit
 coalescing and pending() visibility with nothing retained beyond the store's
 atomic unit (the whole request on the server: one render, one effect; the
 in-flight window in the tab). Caching is the retention `ttl` adds on top.
@@ -74,9 +74,10 @@ in-flight window in the tab). Caching is the retention `ttl` adds on top.
 `fn` is either a remote function (a GET/POST/... helper) or a plain producer
 returning a Promise:
 
-  cache(getPost)({ id })       // → Promise<Post>      (decoded body)
-  cache(getPost.raw)({ id })   // → Promise<Response>  (raw escape hatch)
-  cache(fetchRates)()          // → Promise<Rates>     (plain producer)
+  cache(getPost, { id })          // → Promise<Post>      (decoded body)
+  cache(getPost.raw, { id })      // → Promise<Response>  (raw escape hatch)
+  cache(fetchRates)               // → Promise<Rates>     (plain producer, no args)
+  cache(createPost, body, { ttl: 0 })  // options trail; no-arg-with-options: cache(fn, undefined, opts)
 
 Remote calls key on fn.method + fn.url + args and store the underlying Response
 (the decoded view is derived on the way out for the non-raw variant; both share
@@ -92,18 +93,18 @@ requests — the memoise-an-external-endpoint case. Default (omitted) is
 request-scoped on the server, which keeps per-user data from leaking across
 requests; on the client there is one tab store either way, so it is a no-op.
 
-Reactivity is implicit: the invoker calls `store.subscribe(key)`, which
-registers the surrounding scope().computed() / scope().effect() scope. Invalidating the key
-then re-runs that scope, which calls cache() again and gets a fresh entry.
-Outside a tracking scope subscribe() is a no-op, so cache() works the same
-in server code and plain client code.
+Reactivity is implicit: the read calls `store.subscribe(key)`, which registers
+the surrounding state.computed() / effect() scope. Invalidating the key then
+re-runs that scope, which calls cache() again and gets a fresh entry. Outside a
+tracking scope subscribe() is a no-op, so cache() works the same in server code
+and plain client code.
 
 SSR: how you consume the call decides inline vs streaming (during SSR only the
 pending branch of a `<template await>` renders):
 
-  const post = await cache(getPost)({ id })   // blocks render → baked into
+  const post = await cache(getPost, { id })   // blocks render → baked into
                                               // the initial SSR HTML
-  <template await={cache(getPost)({ id })}>   // renders pending → shell flushes
+  <template await={cache(getPost, { id })}>   // renders pending → shell flushes
                                               // now, value streams in on the
                                               // same response when it resolves
 
@@ -119,32 +120,68 @@ await-everything mode is per component instance, so a child's await blocks only
 the child.
 */
 // @documentation cache
+/**
+ * @deprecated Streaming rpcs (jsonl/sse) aren't cacheable — a stream has no single
+ * value to retain. Consume it with `state(fn(args))` (reactive) or `for await (… of
+ * fn(args))` (imperative). This overload is selected first for a streaming rpc so the
+ * mistake is a red squiggle at the keyboard; the `decodeResponse` guard also throws.
+ */
+export function cache<Args>(
+    fn: RemoteFunction<Args, AsyncIterable<unknown>>,
+    ...rest: never[]
+): never
 export function cache<Args, Return>(
     fn: RemoteFunction<Args, Return>,
+    args?: Args,
     options?: CacheOptions,
-): (args?: Args) => Promise<Return>
+): Promise<Return>
 export function cache<Args>(
     fn: RawRemoteFunction<Args>,
+    args?: Args,
     options?: CacheOptions,
-): (args?: Args) => Promise<Response>
+): Promise<Response>
 export function cache<Args, Return>(
     fn: Producer<Args, Return>,
+    args?: Args,
     options?: CacheOptions,
-): (args?: Args) => Promise<Return>
+): Promise<Return>
 export function cache<Args, Return>(
     fn: AnyRemote<Args, Return> | Producer<Args, Return>,
+    args?: Args,
     options?: CacheOptions,
-): (args?: Args) => Promise<Return | Response> {
-    /*
-    Re-wrapping loses the remote's identity (no url/method on the wrapper), so
-    the inner remote would silently become an anonymous producer — no shared
-    key, no SSR snapshot, no write-method guards. Throw where the mistake is.
-    */
-    if (CACHE_WRAPPED in fn) {
-        throw new Error(
-            '[abide] cache(): fn is already a cache() wrapper — wrap the original function once',
-        )
-    }
+): Promise<Return | Response> {
+    return readThrough(fn, args, options, false)
+}
+
+/*
+The smart bare rpc call routes here (createRemoteFunction.callable → cache.read):
+identical to cache() except a replayable read gets unconditional SWR retention —
+its value is kept for display regardless of ttl, and ttl marks a staleness
+deadline (the next read past it revalidates in the background) instead of driving
+eviction. Always a decoded RemoteFunction read (the callable carries .raw), so it
+returns Promise<Return>.
+*/
+function smartRead<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    args?: Args,
+    options?: CacheOptions,
+): Promise<Return> {
+    return readThrough(fn, args, options, true) as Promise<Return>
+}
+cache.read = smartRead
+
+/*
+The shared read-through core. `smart` marks the smart bare call, which enables
+unconditional SWR retention for replayable reads (see smartRead / entry.retain);
+the public cache() passes false, keeping its explicit drop-on-ttl /
+drop-on-invalidate old surface.
+*/
+function readThrough<Args, Return>(
+    fn: AnyRemote<Args, Return> | Producer<Args, Return>,
+    args: Args | undefined,
+    options: CacheOptions | undefined,
+    smart: boolean,
+): Promise<Return | Response> {
     /*
     A remote function carries the REMOTE_FUNCTION brand (set by
     createRemoteFunction on both variants); a plain producer never does — exact,
@@ -160,26 +197,52 @@ export function cache<Args, Return>(
         : isRaw
           ? (fn as RawRemoteFunction<Args>)
           : (fn as RemoteFunction<Args, Return>).raw
-    validatePolicy(options, isRemote ? (rawFn as RawRemoteFunction<Args>).method : undefined)
+    const method = isRemote ? (rawFn as RawRemoteFunction<Args>).method : undefined
+    const replayable = method !== undefined && REPLAYABLE_METHODS.has(method.toUpperCase())
+    validatePolicy(options, method, smart)
+    /* Unconditional SWR retention for a smart replayable read (unless opted out). */
+    const retain = smart && replayable && options?.swr !== false
+    /*
+    A smart write is coalesce-only, not retained (design: same as cache(fn, body,
+    { ttl: 0 })) — a second identical submit must re-fire, never replay the first
+    result. Default a smart write's ttl to 0 when the caller left it open. Reads and
+    explicit cache() keep the caller's ttl (undefined = forever).
+    */
+    const effectiveOptions =
+        smart && isRemote && !replayable && options?.ttl === undefined
+            ? { ...options, ttl: 0 }
+            : options
     if (!isRemote) {
         warnAnonymousProducer(fn as Producer<Args, Return>)
     }
-    const read = (args?: Args): Promise<Return | Response> => {
-        const store = options?.global ? globalCacheStore() : activeCacheStore()
-        if (!isRemote) {
-            return invokeProducer(store, fn as Producer<Args, Return>, args, options)
-        }
-        const remote = rawFn as RawRemoteFunction<Args>
-        const key = keyForRemoteCall(remote.method, remote.url, args)
-        store.subscribe(key)
-        const existing = store.entries.get(key)
-        recordRead(options?.global ? activeCacheStore() : store, key, existing)
-        if (existing) {
-            tagEntry(existing, options?.tags)
-            attachPolicy(existing, options, () => remote(args as Args))
-            adoptTtl(store, existing, options)
+    const store = effectiveOptions?.global ? globalCacheStore() : activeCacheStore()
+    if (!isRemote) {
+        return invokeProducer(store, fn as Producer<Args, Return>, args, effectiveOptions)
+    }
+    const remote = rawFn as RawRemoteFunction<Args>
+    const key = keyForRemoteCall(remote.method, remote.url, args)
+    store.subscribe(key)
+    const existing = store.entries.get(key)
+    recordRead(effectiveOptions?.global ? activeCacheStore() : store, key, existing)
+    if (existing) {
+        tagEntry(existing, effectiveOptions?.tags)
+        attachPolicy(existing, effectiveOptions, () => remote(args as Args), retain)
+        adoptTtl(store, existing, effectiveOptions, retain)
+        /* Access-triggered staleness: reading a retained entry past its ttl deadline
+           kicks a background revalidation now (stale value stays visible below,
+           refreshing() true). Guarded on `!refreshing` so a read while one is already
+           in flight doesn't queue a redundant refetch. This is the whole staleness
+           mechanism — no timer polls an untouched entry. */
+        if (
+            existing.retain === true &&
+            existing.refreshing !== true &&
+            existing.expiresAt !== undefined &&
+            existing.expiresAt <= Date.now()
+        ) {
+            scheduleInvalidationRefetch(store, existing)
         }
-        /*
+    }
+    /*
         Warm path: a value pre-decoded onto the entry — by the SSR cache
         snapshot the client seeds its store from — is served without a network
         round-trip. It resolves on a
@@ -199,43 +262,22 @@ export function cache<Args, Return>(
         reader of the key, so one mutating it would corrupt the others. A live
         fetch hands each reader a fresh object; cloning keeps warm reads the same.
         */
-        if (
-            !isRaw &&
-            existing !== undefined &&
-            (existing.value !== undefined || existing.warm !== undefined)
-        ) {
-            /* A deferred seed carries a lazy materializer instead of a decoded value: decode
-               it here, on the first read that needs it (off the hydration path), and cache the
-               result onto the entry so later reads skip the decode. Drop the materializer once
-               used — its closure pins the raw body string, so keeping it alongside the decoded
-               value would double memory for exactly the large payloads deferral targets. */
-            const warmValue = existing.value !== undefined ? existing.value : existing.warm?.()
-            existing.value = warmValue
-            existing.warm = undefined
-            const warmed = Promise.resolve(cloneWarmValue(warmValue)) as Promise<Return>
-            recordCacheKey(warmed, key)
-            return warmed
-        }
-        const responsePromise = invokeRemote(
-            store,
-            key,
-            existing,
-            rawFn as RawRemoteFunction<Args>,
-            args,
-            options,
-        )
-        if (isRaw) {
-            return responsePromise
-        }
-        /* Tag the decoded value promise with its key so the SSR resume path can recognise a
-           cache-backed await value and defer a large one to a `{ defer, key }` marker. */
-        const decoded = responsePromise.then(decodeResponse) as Promise<Return>
-        recordCacheKey(decoded, key)
-        return decoded
+    if (!isRaw && existing !== undefined && existing.value !== undefined) {
+        return Promise.resolve(cloneWarmValue(existing.value)) as Promise<Return>
+    }
+    const responsePromise = invokeRemote(
+        store,
+        key,
+        existing,
+        rawFn as RawRemoteFunction<Args>,
+        args,
+        effectiveOptions,
+        retain,
+    )
+    if (isRaw) {
+        return responsePromise
     }
-    /* Non-enumerable brand; selectorMatcher and the re-wrap guard read it. */
-    Object.defineProperty(read, CACHE_WRAPPED, { value: fn })
-    return read
+    return responsePromise.then(decodeResponse) as Promise<Return>
 }
 
 /*
@@ -259,20 +301,34 @@ function cloneWarmValue(value: unknown): unknown {
 }
 
 /*
-Normalises the `swr` option to its window, or undefined when off. `true` (or
-`{}`) is stale-while-revalidate with no window — refetch immediately on every
-invalidate; an object carries the throttle/debounce window. `false`/omitted is
-off. Collapsing the boolean here lets every downstream site treat "is SWR on"
-as a single defined/undefined check.
+Normalises the refetch window, or undefined when off. Precedence: an explicit
+`swr` object carries its own throttle/debounce; `swr: true` (or `defaultOn`) uses
+the root `throttle`/`debounce` window if present, else `{}` (fire immediately).
+`swr: false` is an explicit opt-out and wins over `defaultOn`. `defaultOn` is the
+smart bare call's unconditional SWR for replayable reads — it turns the window on
+without an `swr` toggle. Collapsing all of this here lets every downstream site
+treat "is SWR on" as a single defined/undefined check.
 */
 function swrWindow(
     options: CacheOptions | undefined,
+    defaultOn: boolean,
 ): { throttle?: number; debounce?: number } | undefined {
     const swr = options?.swr
-    if (swr === undefined || swr === false) {
+    if (swr === false) {
         return undefined
     }
-    return swr === true ? {} : swr
+    const root =
+        options?.throttle !== undefined || options?.debounce !== undefined
+            ? { throttle: options?.throttle, debounce: options?.debounce }
+            : undefined
+    /* Explicit window object (swr: { throttle | debounce }). */
+    if (swr !== undefined && swr !== true) {
+        return swr
+    }
+    if (swr === true || defaultOn) {
+        return root ?? {}
+    }
+    return undefined
 }
 
 /*
@@ -284,20 +340,29 @@ refresh. Producers are opaque (no method to check); the same contract is on
 the caller there. ttl: 0 retains nothing, so there is nothing to revalidate;
 and the two coalescing windows are exclusive by construction.
 */
-function validatePolicy(options: CacheOptions | undefined, method: string | undefined): void {
-    const policy = swrWindow(options)
+function validatePolicy(
+    options: CacheOptions | undefined,
+    method: string | undefined,
+    smart: boolean,
+): void {
+    const replayable = method !== undefined && REPLAYABLE_METHODS.has(method.toUpperCase())
+    const policy = swrWindow(options, smart && replayable)
     if (!policy) {
         return
     }
     if (policy.throttle !== undefined && policy.debounce !== undefined) {
-        throw new Error('[abide] cache(): set swr.throttle or swr.debounce, not both')
+        throw new Error('[abide] cache(): set throttle or debounce, not both')
     }
-    if (options?.ttl === 0) {
+    /* An EXPLICIT swr with ttl: 0 is the old error — nothing retained to revalidate.
+       The smart read's implicit SWR retains unconditionally, so ttl: 0 is fine there. */
+    const explicitSwr =
+        options?.swr === true || (typeof options?.swr === 'object' && options?.swr !== null)
+    if (explicitSwr && options?.ttl === 0) {
         throw new Error(
             '[abide] cache(): swr requires retention — ttl: 0 keeps nothing to revalidate',
         )
     }
-    if (method !== undefined && !REPLAYABLE_METHODS.has(method.toUpperCase())) {
+    if (method !== undefined && !replayable) {
         throw new Error(
             `[abide] cache(): swr re-runs the call unprompted — ${method.toUpperCase()} is a write and must not be replayed`,
         )
@@ -342,7 +407,7 @@ function invokeProducer<Args, Return>(
     recordRead(options?.global ? activeCacheStore() : store, key, existing)
     if (existing) {
         tagEntry(existing, options?.tags)
-        attachPolicy(existing, options, () => producer(args))
+        attachPolicy(existing, options, () => producer(args), false)
         const shared = existing.promise as Promise<Return>
         /* A coalesced join waits on the in-flight producer — time the block so the
            waterfall shows it; a settled hit returns immediately, so no span. */
@@ -358,7 +423,7 @@ function invokeProducer<Args, Return>(
     const promise = cacheLog.trace<Return>(`cache ${key}`, () =>
         withCacheManaged(() => producer(args)),
     )
-    registerEntry(store, key, promise, options, undefined, () => producer(args))
+    registerEntry(store, key, promise, options, undefined, () => producer(args), false)
     return promise
 }
 
@@ -369,6 +434,7 @@ function invokeRemote<Args>(
     rawFn: RawRemoteFunction<Args>,
     args: Args | undefined,
     options: CacheOptions | undefined,
+    retain: boolean,
 ): Promise<Response> {
     if (existing) {
         return shareable(existing.promise as Promise<Response>)
@@ -382,7 +448,7 @@ function invokeRemote<Args>(
             '[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))
+    registerEntry(store, key, promise, options, request, () => rawFn(args as Args), retain)
     return shareable(promise)
 }
 
@@ -398,10 +464,12 @@ function registerEntry(
     options: CacheOptions | undefined,
     request: Request | undefined,
     refetch: () => Promise<unknown>,
+    retain: boolean,
 ): CacheEntry {
     const ttl = options?.ttl
-    /* Capture the refetch thunk + window only when swr was asked for. */
-    const policy = swrWindow(options)
+    /* Capture the refetch thunk + window when swr was asked for OR this is a smart
+       retained read (SWR unconditional). */
+    const policy = swrWindow(options, retain)
     const invalidation = policy
         ? { refetch, throttle: policy.throttle, debounce: policy.debounce }
         : undefined
@@ -420,6 +488,7 @@ function registerEntry(
         tags: options?.tags === undefined ? undefined : toTagSet(options.tags),
         refreshing,
         invalidation,
+        retain: retain || undefined,
     }
     store.entries.set(key, entry)
     store.markLifecycle(key)
@@ -463,6 +532,29 @@ function registerEntry(
             deleteIfCurrent()
             return
         }
+        /*
+        A post-invalidate reload registers with refreshing=true; an invalidation
+        firing while it was in flight parked its refetch on policy.pending
+        (fireRefetch bails when refreshing). This settle path — not fireRefetch —
+        cleared the flag, so drain the parked refetch here or it's lost and the
+        entry keeps data that predates the invalidation.
+        */
+        if (entry.invalidation?.pending) {
+            reschedulePendingRefetch(store, entry, entry.invalidation)
+        }
+        /*
+        Smart retained read: the display value is kept unconditionally — never
+        hard-evicted on settle. ttl marks a staleness deadline (the next read past
+        it revalidates in the background, stale stays visible, refreshing() true)
+        instead of eviction; ttl 0/undefined retain with no staleness clock.
+        */
+        if (entry.retain) {
+            materializeRetained(store, entry, result)
+            if (ttl !== undefined && ttl > 0) {
+                stampStaleDeadline(entry, ttl)
+            }
+            return
+        }
         if (ttl === 0) {
             if (!keepZeroTtlForRequest) {
                 deleteIfCurrent()
@@ -492,11 +584,71 @@ function evictIfCurrent(store: CacheStore, entry: CacheEntry): void {
 /* Arms the ttl > 0 expiry sweep; `expiresAt` re-checks at fire time so a refreshed deadline survives. */
 function armTtlExpiry(store: CacheStore, entry: CacheEntry, ttl: number): void {
     entry.expiresAt = Date.now() + ttl
+    scheduleTtlSweep(store, entry)
+}
+
+/* setTimeout clamps a delay beyond 2^31-1 ms (~24.8 days) to ~1ms, which would
+   fire the sweep instantly, find the deadline unexpired, and never re-arm —
+   the entry would live forever. Chain capped hops until the deadline is in
+   reach; each hop bails once a newer entry owns the key. */
+const MAX_TIMEOUT_DELAY = 2147483647
+
+function scheduleTtlSweep(store: CacheStore, entry: CacheEntry): void {
+    if (store.entries.get(entry.key) !== entry) {
+        return
+    }
+    const remaining = (entry.expiresAt ?? 0) - Date.now()
+    if (remaining > MAX_TIMEOUT_DELAY) {
+        setTimeout(() => scheduleTtlSweep(store, entry), MAX_TIMEOUT_DELAY).unref?.()
+        return
+    }
     setTimeout(() => {
         if ((entry.expiresAt ?? 0) <= Date.now()) {
             evictIfCurrent(store, entry)
         }
-    }, ttl).unref?.()
+    }, remaining).unref?.()
+}
+
+/*
+Stamps the smart-read staleness deadline. Revalidation is access-triggered, NOT
+timer-driven: once `expiresAt` has passed, the NEXT read of the entry (see the
+staleness branch in readThrough) schedules a background revalidation — the stale
+value stays visible, refreshing() flips true, and fireRefetch re-stamps a fresh
+deadline on success. No `setTimeout`, so an entry no reader touches never refetches
+on its own — no background polling accretes across a session.
+*/
+function stampStaleDeadline(entry: CacheEntry, ttl: number): void {
+    entry.expiresAt = Date.now() + ttl
+}
+
+/*
+Decodes a retained read's Response onto entry.value so peek() can read the current
+value synchronously, and reads take the warm (cloned) path. Client-only: on the
+server the SSR snapshot serializer owns value materialization (from the response
+body it inlines), so leaving entry.value untouched there keeps the snapshot path
+unchanged. Async decode (a microtask); markLifecycle re-runs a peek() scope once
+the value lands. A non-Response (a producer retain — not currently reachable) is
+stored as-is.
+*/
+function materializeRetained(store: CacheStore, entry: CacheEntry, result: unknown): void {
+    if (typeof window === 'undefined') {
+        return
+    }
+    if (result instanceof Response) {
+        decodeResponse(result.clone()).then(
+            (value) => {
+                /* Only if this entry still owns the key and hasn't been re-mutated meanwhile. */
+                if (store.entries.get(entry.key) === entry) {
+                    entry.value = value
+                    store.markLifecycle(entry.key)
+                }
+            },
+            () => undefined,
+        )
+        return
+    }
+    entry.value = result
+    store.markLifecycle(entry.key)
 }
 
 /*
@@ -511,11 +663,27 @@ the already-painted DOM stays put) and the next read fetches live. The first
 reader consumes the flag, so its declaration wins; live entries never carry
 the flag and keep the ttl they registered with.
 */
-function adoptTtl(store: CacheStore, entry: CacheEntry, options: CacheOptions | undefined): void {
+function adoptTtl(
+    store: CacheStore,
+    entry: CacheEntry,
+    options: CacheOptions | undefined,
+    retain: boolean,
+): void {
     if (entry.hydrated !== true) {
         return
     }
     entry.hydrated = false
+    /* A smart read adopting a hydrated entry retains it and stamps the staleness
+       deadline, mirroring registerEntry's retain branch — never the hard-evict path. */
+    if (retain) {
+        entry.retain = true
+        const ttl = options?.ttl
+        entry.ttl = ttl
+        if (ttl !== undefined && ttl > 0) {
+            stampStaleDeadline(entry, ttl)
+        }
+        return
+    }
     const ttl = options?.ttl
     if (ttl === undefined) {
         return
@@ -553,6 +721,11 @@ function invalidate<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args
     const prefix = selectorPrefix(arg, args)
     const matches = selectorMatcher(arg, args, prefix)
     invalidateTripwire(selectorLabel(arg, args, prefix))
+    /* Reset any recorded rpc errors for this selector too (independent of cache entries — a
+       bare call that errored never became one). Only fn selectors resolve a prefix. */
+    if (prefix !== undefined) {
+        rpcErrorRegistry.clearMatching(prefix)
+    }
     for (const store of cacheStores()) {
         const matched: string[] = []
         const affected: string[] = []
@@ -603,6 +776,169 @@ function selectorLabel<Args, Return>(
 
 cache.invalidate = invalidate
 
+/*
+The smart-call refetch: refetches every entry matching the selector, keeping the
+stale value visible (refreshing() true) until the fresh value swaps in — never
+blanks. This is the old invalidate reborn as *refetch*: because SWR retains the
+value, there is no "invalidate that drops to pending" for the smart call. Follows
+invalidate's exact selector grammar (fn / fn+args / { tags } / bare = all).
+
+A smart-read match already carries an invalidation policy, so it routes straight
+through scheduleInvalidationRefetch (throttle/debounce-honouring). A policy-less
+remote match (an explicit cache() entry, or a hydrated one) gets a refetch armed
+on the fly by replaying its stored Request. A policy-less producer match has no
+way to re-run, so it drops (the next read reloads) — the invalidate fallback.
+*/
+function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args): void {
+    const prefix = selectorPrefix(arg, args)
+    const matches = selectorMatcher(arg, args, prefix)
+    invalidateTripwire(selectorLabel(arg, args, prefix))
+    if (prefix !== undefined) {
+        rpcErrorRegistry.clearMatching(prefix)
+    }
+    for (const store of cacheStores()) {
+        const matched: string[] = []
+        const affected: string[] = []
+        for (const entry of store.entries.values()) {
+            if (!matches(entry)) {
+                continue
+            }
+            matched.push(entry.key)
+            /* Arm a refetch on the fly for a policy-less remote entry by replaying its
+               stored Request — so a refresh always refetches-and-swaps, never blanks. */
+            if (entry.invalidation === undefined && entry.request !== undefined) {
+                const request = entry.request
+                entry.invalidation = { refetch: () => fetch(request.clone()) }
+            }
+            if (entry.invalidation !== undefined) {
+                scheduleInvalidationRefetch(store, entry)
+            } else {
+                /* No policy, no request (a producer never cached with swr): drop so the
+                   next read reloads, flagged a reload if a reader is holding it. */
+                store.entries.delete(entry.key)
+                if (store.hasReader(entry.key)) {
+                    store.pendingRefresh.add(entry.key)
+                }
+                affected.push(entry.key)
+            }
+        }
+        /* Mark the whole match set (probes re-derive); emit only the dropped subset — the
+           refetched entries emit when their fresh value lands (fireRefetch). */
+        notify(store, matched, affected)
+    }
+}
+
+cache.refresh = refresh
+
+/*
+Local value mutation: replaces the retained value of every entry matching the
+selector via `updater(current)`, re-renders readers, and fires NO network — the
+optimistic-update / real-time primitive (feed a socket frame straight into a
+cached list). The next value is stored onto `entry.value`, which the read path
+serves warm (cloned per read), so it persists across reads until a refresh /
+invalidate replaces the entry. `current` comes from `entry.value` when already
+materialized, else decoded from the settled/in-flight promise (async — readers
+re-render when the patch lands). Follows the selector grammar, but only fn / args
+/ tags select a value to mutate; a not-yet-read key has nothing to patch.
+*/
+function patch<Args, Return>(
+    arg: CacheSelector<Args, Return>,
+    args: Args | undefined,
+    updater: (current: Return) => Return,
+): void {
+    const prefix = selectorPrefix(arg, args)
+    const matches = selectorMatcher(arg, args, prefix)
+    for (const store of cacheStores()) {
+        for (const entry of store.entries.values()) {
+            if (matches(entry)) {
+                applyPatch(store, entry, updater as (current: unknown) => unknown)
+            }
+        }
+    }
+}
+
+cache.patch = patch
+
+/*
+Synchronous, non-triggering value probe: returns the currently-retained value for
+a call, or undefined when nothing is retained (no entry, or not yet settled). Never
+invokes — reading it opens no fetch. Reactive: it subscribes the key AND taps the
+key's lifecycle channel (the exact key is a one-entry prefix, same as
+pending(fn, args)) so a state.computed / on / template scope re-runs both when the
+value changes (invalidate, patch) and when a retained value lands —
+materializeRetained's async decode signals only markLifecycle, no invalidate event,
+so without the lifecycle tap a scope that read undefined would never see the value
+arrive. Outside a tracking scope it is a one-shot snapshot. Returns a clone (like
+the warm read path) so a caller mutating it can't corrupt the retained value.
+`peek(sub)` for a subscribable is wired on the socket side.
+*/
+function peek<Args, Return>(
+    fn: RemoteFunction<Args, Return> | RawRemoteFunction<Args> | Producer<Args, Return>,
+    args?: Args,
+): Return | undefined {
+    const isRemote = REMOTE_FUNCTION in fn
+    const rawFn = !isRemote
+        ? undefined
+        : 'raw' in fn
+          ? (fn as RemoteFunction<Args, Return>).raw
+          : (fn as RawRemoteFunction<Args>)
+    const key = isRemote
+        ? keyForRemoteCall(rawFn!.method, rawFn!.url, args)
+        : producerKey(fn as Producer<Args, Return>, args)
+    const active = activeCacheStore()
+    active.subscribe(key)
+    active.trackLifecycle(key)
+    let entry = active.entries.get(key)
+    if (entry === undefined) {
+        const global = globalCacheStore()
+        global.subscribe(key)
+        global.trackLifecycle(key)
+        entry = global.entries.get(key)
+    }
+    if (entry === undefined || entry.settled !== true || entry.value === undefined) {
+        return undefined
+    }
+    /* SSR congruence: the server materializes no cache value, so server-side peek is
+       uniformly undefined and the SSR render shows the fallback. Returning a snapshot-
+       seeded warm value here — mid-hydration — would diverge from that server text and
+       corrupt the claimed text node. Withhold it until the pass ends; the trackLifecycle
+       tap above lets wakeHydrationPeeks re-run this scope on the congruent value. */
+    if (hydratingSlot.active) {
+        return undefined
+    }
+    return cloneWarmValue(entry.value) as Return
+}
+
+cache.peek = peek
+
+/*
+Applies one entry's patch: materialize the current decoded value (warm value if
+present, else decode the promise — a Response for a remote entry, cloned so the
+readers' own clones still succeed), run the updater, store it warm, and emit so
+readers re-read. Fire-and-forget on the async branch: patch() stays sync-return.
+*/
+function applyPatch(
+    store: CacheStore,
+    entry: CacheEntry,
+    updater: (current: unknown) => unknown,
+): void {
+    function apply(current: unknown): void {
+        entry.value = updater(current)
+        notify(store, [entry.key], [entry.key])
+    }
+    if (entry.value !== undefined) {
+        apply(entry.value)
+        return
+    }
+    const currentValue =
+        entry.request !== undefined
+            ? (entry.promise as Promise<Response>).then((response) =>
+                  decodeResponse(response.clone()),
+              )
+            : (entry.promise as Promise<unknown>)
+    currentValue.then(apply, () => undefined)
+}
+
 /*
 Event-driven cache maintenance: subscribes to a Subscribable (socket or rpc
 stream) and runs `handler` once per frame — the declarative home for "this
@@ -647,6 +983,11 @@ function on<T>(
         },
         signal: controller.signal,
     }
+    /* Register-on-consume: consuming a named subscribable populates the probe registry so
+       pending()/refreshing()/error()/done()(source) work — the stream-side analog of a call
+       populating the cache store. Driven by this one loop, so watch(socket) / for-await all
+       register through here. An unnamed source (rare) skips probe tracking. */
+    const probe = source.name ? openStreamProbe(source.name) : undefined
     /* `let`: the reconnect path swaps in a fresh iterator; dispose closes the current one. */
     let iterator = source[Symbol.asyncIterator]()
     ;(async () => {
@@ -659,18 +1000,25 @@ function on<T>(
                     return
                 }
                 if (error instanceof SocketDisconnectedError) {
+                    probe?.reconnecting()
                     coverage.forEach((replay) => {
                         replay()
                     })
                     iterator = source[Symbol.asyncIterator]()
                     continue
                 }
+                probe?.errored(error instanceof Error ? error : new Error(String(error)))
                 abideLog.error(error)
                 return
             }
-            if (controller.signal.aborted || next.done === true) {
+            if (controller.signal.aborted) {
                 return
             }
+            if (next.done === true) {
+                probe?.done()
+                return
+            }
+            probe?.frame()
             try {
                 await handler(next.value, context)
             } catch (error) {
@@ -680,6 +1028,7 @@ function on<T>(
     })()
     return () => {
         controller.abort()
+        probe?.close()
         iterator.return?.(undefined)?.catch(() => undefined)
     }
 }
@@ -766,11 +1115,23 @@ function fireRefetch(store: CacheStore, entry: CacheEntry): void {
             entry.promise = inflight
             entry.value = undefined
             entry.settled = true
+            /* Re-materialize the retained value from the fresh Response so peek() stays
+               current after a background revalidation. */
+            if (entry.retain) {
+                materializeRetained(store, entry, result)
+            }
             /* Restart the freshness clock from the revalidation — without this the
-               entry keeps its original expiresAt and is evicted at the old deadline
-               despite holding fresh data. Mirrors registerEntry's settle path. */
+               entry keeps its original expiresAt and would read as stale (or be evicted
+               at the old deadline) despite holding fresh data. Mirrors registerEntry's
+               settle path: a retained smart read re-stamps the staleness deadline (the
+               next read past it revalidates), an explicit-swr entry re-arms the eviction
+               clock. */
             if (entry.ttl !== undefined && entry.ttl !== 0) {
-                armTtlExpiry(store, entry, entry.ttl)
+                if (entry.retain) {
+                    stampStaleDeadline(entry, entry.ttl)
+                } else {
+                    armTtlExpiry(store, entry, entry.ttl)
+                }
             }
             /* Fresh value landed — mark and emit so readers re-read. */
             notify(store, [entry.key], [entry.key])
@@ -863,8 +1224,14 @@ function attachPolicy(
     entry: CacheEntry,
     options: CacheOptions | undefined,
     refetch: () => Promise<unknown>,
+    defaultOn: boolean,
 ): void {
-    const policy = swrWindow(options)
+    /* A smart read hitting a bare existing entry (e.g. one an explicit cache()
+       created first) adopts unconditional retention too. */
+    if (defaultOn) {
+        entry.retain = true
+    }
+    const policy = swrWindow(options, defaultOn)
     if (entry.invalidation || !policy) {
         return
     }