@abide/abide 0.48.0 → 0.50.0

package/src/lib/shared/cache.ts

@@ -4,13 +4,14 @@ import { cacheStores } from './cacheStores.ts'
 import { decodeResponse } from './decodeResponse.ts'
 import { getRemoteMeta } from './getRemoteMeta.ts'
 import { HttpError } from './HttpError.ts'
-import { hydratingSlot } from './hydratingSlot.ts'
+import { hydrationWindow } from './hydrationWindow.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 { reviveWireOutput } from './reviveWireOutput.ts'
 import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
@@ -21,11 +22,13 @@ import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheOnContext } from './types/CacheOnContext.ts'
 import type { CacheOptions } from './types/CacheOptions.ts'
+import type { CachePolicy } from './types/CachePolicy.ts'
 import type { CacheSelector } from './types/CacheSelector.ts'
 import type { CacheStore } from './types/CacheStore.ts'
+import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
+import type { OutputWirePlan } from './types/OutputWirePlan.ts'
 import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
-import type { Subscribable } from './types/Subscribable.ts'
 import { withCacheManaged } from './withCacheManaged.ts'
 
 type AnyRemote<Args, Return> = RemoteFunction<Args, Return> | RawRemoteFunction<Args>
@@ -58,28 +61,34 @@ function recordRead(sink: CacheStore, key: string, existing: CacheEntry | undefi
 }
 
 /*
-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 = 0 → dedupe only; ttl > 0 → entry
-expires `ttl` ms after the promise resolves. Omitted ttl → forever for a
-producer and for a remote call on the client; a remote call on the server with
-neither ttl nor swr stated defaults to 0 (coalesce-only, see CacheOptions).
+Reads a call through a cache store. `cache(fn, 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 — a direct read-through call, not a curried invoker. Args
+lead (the common refinement).
 
-Coalescing is always on: identical in-flight calls share one flight, so
-`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
+A REMOTE rpc carries no call-site options (ADR-0020): its cache policy lives on
+the endpoint definition (`GET(fn, { cache: {...} })`) and readThrough reads it as
+the bottom layer. A plain PRODUCER has no endpoint, so it keeps a trailing
+`options?: CacheOptions` (ttl/tags/throttle/debounce/shared) — its only policy
+home. ttl = 0 → dedupe only; ttl > 0 → entry expires `ttl` ms after the promise
+resolves. Omitted ttl → retained for the store's lifetime: a producer or a remote
+READ is kept as long as its store lives (the request on the server, the tab on the
+client), while a remote WRITE coalesces only (ttl 0 — the mutation idiom). A remote
+read made outside any request scope falls back to the process store and coalesces
+only too, so a scopeless read can't leak forever. See CachePolicy.
+
+Coalescing is always on: identical in-flight calls share one flight — 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.
 
 `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, { id })          // → Promise<Post>      (decoded body; policy on the endpoint)
   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)
+  cache(computeReport, input, { ttl: 60_000 })  // producer options trail
 
 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
@@ -89,11 +98,12 @@ new reference every call and never does; a warning fires once per such call
 site), and the promise is stored and handed back as-is (no Response, no decode,
 no SSR snapshot).
 
-`options.shared` puts the entry in the process-level store instead of the
-request-scoped one, so a value computed in one request is reused by later
-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.
+`options.shared` (producer) / `cache.shared` (endpoint) puts the entry in the
+process-level store instead of the request-scoped one, so a value computed in one
+request is reused by later 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 read calls `store.subscribe(key)`, which registers
 the surrounding state.computed() / effect() scope. Invalidating the key then
@@ -132,16 +142,8 @@ 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,
-): Promise<Return>
-export function cache<Args>(
-    fn: RawRemoteFunction<Args>,
-    args?: Args,
-    options?: CacheOptions,
-): Promise<Response>
+export function cache<Args, Return>(fn: RemoteFunction<Args, Return>, args?: Args): Promise<Return>
+export function cache<Args>(fn: RawRemoteFunction<Args>, args?: Args): Promise<Response>
 export function cache<Args, Return>(
     fn: Producer<Args, Return>,
     args?: Args,
@@ -152,7 +154,19 @@ export function cache<Args, Return>(
     args?: Args,
     options?: CacheOptions,
 ): Promise<Return | Response> {
-    return readThrough(fn, args, options, false)
+    const result = readThrough(fn, args, options, false)
+    /* Revive the decoded body's structured fields (Set/Map/Date/bigint) so `cache(fn, args)`
+       matches the bare `fn(args)` read (createRemoteFunction.callable revives there) — without
+       this the two read APIs disagree for a typed field, and both violate the declared Return.
+       A producer / a raw `Response` carry no plan and pass through untouched; the decoded value is
+       call-private (fresh decode or cloned warm value), so revive mutates it in place. */
+    const plan = (fn as { outputWirePlan?: OutputWirePlan }).outputWirePlan
+    if (plan === undefined) {
+        return result
+    }
+    return result.then((value) =>
+        value instanceof Response ? value : (reviveWireOutput(value, plan) as Return),
+    )
 }
 
 /*
@@ -160,15 +174,12 @@ The smart bare rpc call routes here (createRemoteFunction.callable → cache.rea
 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>.
+eviction. No call-site options (ADR-0020): all policy is read off the endpoint
+(fn.cache). 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>
+function smartRead<Args, Return>(fn: RemoteFunction<Args, Return>, args?: Args): Promise<Return> {
+    return readThrough(fn, args, undefined, true) as Promise<Return>
 }
 cache.read = smartRead
 
@@ -177,6 +188,8 @@ The shared read-through core. `smart` marks the smart bare call, which enables
 unconditional SWR retention for a replayable read — but only on the client (see
 smartRead / entry.retain and the `retain` computation below); the public cache()
 passes false, keeping its explicit drop-on-ttl / drop-on-invalidate old surface.
+A remote's policy is read off the endpoint (fn.cache — ADR-0020); a producer's
+policy is its explicit cache() `options`.
 */
 function readThrough<Args, Return>(
     fn: AnyRemote<Args, Return> | Producer<Args, Return>,
@@ -201,30 +214,42 @@ function readThrough<Args, Return>(
           : (fn as RemoteFunction<Args, Return>).raw
     const method = isRemote ? (rawFn as RawRemoteFunction<Args>).method : undefined
     const replayable = method !== undefined && REPLAYABLE_METHODS.has(method.toUpperCase())
-    validatePolicy(options, method, smart)
+    /* Remote policy is endpoint-declared — the bottom (and only) layer; a producer has no
+       endpoint, so its explicit cache() options stand in. */
+    const policy = isRemote ? resolveEndpointCache(fn as AnyRemote<Args, Return>, args) : options
     /* SWR retention is a client concern (the tab store lives; revalidation is
        visible). On the server there is no live UI to hold stale, so a smart read
-       never retains — it coalesces only. */
-    const retain = smart && replayable && options?.swr !== false && typeof window !== 'undefined'
+       never retains — it coalesces only. Unconditional for a replayable read now
+       (no swr toggle to opt out of). */
+    const retain = smart && replayable && typeof window !== 'undefined'
+    /*
+    ttl defaults to Infinity — an entry is retained for as long as its STORE lives, and
+    the store's lifetime (not ttl) is what ends a read: the request-scoped store on the
+    server (so a non-shared read dies with the request regardless of ttl), the tab store
+    on the client (until invalidate/refresh). `shared` selects the process store, where
+    the default Infinity memoises across requests and an explicit ttl bounds it — so
+    `shared` alone is "memoise", not a store-selector that retains nothing.
+    */
+    const store = policy?.shared ? sharedCacheStore() : activeCacheStore()
     /*
-    ttl defaults to 0 (coalesce-only) on the server for any remote read/write, and
-    on the client for a smart write — in both cases only when the caller stated
-    neither ttl nor swr. The server default makes retention opt-in (via an explicit
-    ttl, paired with `shared` to survive the request). An explicit swr opts out so
-    it does not trip validatePolicy's "swr + ttl:0" throw; server-side swr is a
-    client-only concept with no added server guarantee.
+    Two cases force coalesce-only (ttl 0) when the caller stated no ttl — nothing retained
+    beyond the in-flight window:
+    - a write (non-replayable remote): dropped on settle so a re-submit of the same body
+      isn't blocked by a retained entry (the mutation idiom);
+    - a read that resolved to the process store WITHOUT `shared` — a server read outside any
+      request scope, where activeCacheStore() falls back to the shared store. Nothing bounds
+      its lifetime there, so retaining it would leak forever.
+    Both apply on either side and however the call is made.
     */
-    const serverTtlZero =
+    const coalesceOnly =
         isRemote &&
-        typeof window === 'undefined' &&
-        options?.ttl === undefined &&
-        options?.swr === undefined
-    const smartWriteTtlZero = smart && isRemote && !replayable && options?.ttl === undefined
-    const effectiveOptions = serverTtlZero || smartWriteTtlZero ? { ...options, ttl: 0 } : options
+        policy?.ttl === undefined &&
+        (!replayable ||
+            (!policy?.shared && typeof window === 'undefined' && store === sharedCacheStore()))
+    const effectiveOptions = coalesceOnly ? { ...policy, ttl: 0 } : policy
     if (!isRemote) {
         warnAnonymousProducer(fn as Producer<Args, Return>)
     }
-    const store = effectiveOptions?.shared ? sharedCacheStore() : activeCacheStore()
     if (!isRemote) {
         return invokeProducer(store, fn as Producer<Args, Return>, args, effectiveOptions)
     }
@@ -318,72 +343,48 @@ function cloneWarmValue(value: unknown): unknown {
 }
 
 /*
-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.
+Resolves an rpc endpoint's declared cache policy (ADR-0020) into a plain
+CacheOptions for the read-through machinery, evaluating the `tags` function form
+against this call's args. Both remote variants (decoded + raw) carry `.cache`, so
+either can be passed. Undefined when the endpoint declared no policy (method
+defaults still apply below).
 */
-function swrWindow(
-    options: CacheOptions | undefined,
-    defaultOn: boolean,
-): { throttle?: number; debounce?: number } | undefined {
-    const swr = options?.swr
-    if (swr === false) {
+function resolveEndpointCache<Args, Return>(
+    fn: AnyRemote<Args, Return>,
+    args: Args | undefined,
+): CacheOptions | undefined {
+    const policy = (fn as { cache?: CachePolicy<Args> }).cache
+    if (policy === undefined) {
         return undefined
     }
-    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
+    const tags = typeof policy.tags === 'function' ? policy.tags(args as Args) : policy.tags
+    return {
+        ttl: policy.ttl,
+        tags,
+        shared: policy.shared,
+        throttle: policy.throttle,
+        debounce: policy.debounce,
     }
-    if (swr === true || defaultOn) {
-        return root ?? {}
-    }
-    return undefined
 }
 
 /*
-Guards impossible option combinations at wrap time, where the call site is on
-the stack. `swr` declares "this call is safe to re-run unprompted", so a
-non-replayable remote method (a write) must never carry it — replaying a write
-through the invalidation grammar would be a state change disguised as a
-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.
+The keep-stale-and-revalidate refetch window, or undefined when the entry should
+hard-drop on invalidate instead. Present when the smart bare call retains a
+replayable read (`defaultOn`, SWR unconditional — the window is just the endpoint's
+throttle/debounce, or `{}` = fire immediately) OR when a policy explicitly declares
+a throttle/debounce window (producer options / endpoint cache). Collapsing this here
+lets every downstream site treat "is a refetch window armed" as a single
+defined/undefined check.
 */
-function validatePolicy(
+function refetchWindow(
     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 throttle or debounce, not both')
-    }
-    /* 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) {
-        throw new Error(
-            `[abide] cache(): swr re-runs the call unprompted — ${method.toUpperCase()} is a write and must not be replayed`,
-        )
+    defaultOn: boolean,
+): { throttle?: number; debounce?: number } | undefined {
+    const hasWindow = options?.throttle !== undefined || options?.debounce !== undefined
+    if (defaultOn || hasWindow) {
+        return { throttle: options?.throttle, debounce: options?.debounce }
     }
+    return undefined
 }
 
 /*
@@ -498,9 +499,9 @@ function registerEntry(
     retain: boolean,
 ): CacheEntry {
     const ttl = options?.ttl
-    /* Capture the refetch thunk + window when swr was asked for OR this is a smart
-       retained read (SWR unconditional). */
-    const policy = swrWindow(options, retain)
+    /* Capture the refetch thunk + window when a smart retained read (SWR unconditional)
+       or an explicit throttle/debounce window is present. */
+    const policy = refetchWindow(options, retain)
     const invalidation = policy
         ? { refetch, throttle: policy.throttle, debounce: policy.debounce }
         : undefined
@@ -748,7 +749,7 @@ Invalidates every entry matching the selector (see selectorMatcher) across both
 the request/tab store and the process-level store, and notifies readers.
 `args` narrows a fn selector to exactly that call's entry — derived through
 the same encoders the read path uses, so other args variants stay warm. An entry
-with an swr policy is kept and its refetch coalesced (stale served
+with a refetch policy is kept and its refetch coalesced (stale served
 until it resolves); every other match is dropped so the next read refetches —
 its key recorded in pendingRefresh so that read reports as a reload (refreshing())
 rather than a first-ever load. An empty or unmatched selector is a no-op on the
@@ -821,6 +822,12 @@ 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).
 
+Only a match with a live reader refetches: refresh keeps the stale value visible
+until the fresh one swaps in, and with no reader on screen there is nothing to
+swap into — so a match whose reactive scope has torn down ("no longer has
+listeners") drops instead of firing a wasted network refetch, and the next read
+reloads it fresh.
+
 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
@@ -842,6 +849,16 @@ function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args):
                 continue
             }
             matched.push(entry.key)
+            /* No live reader is holding this key — its reactive scope has torn down (or
+               it was never read reactively and already dropped). A refresh has no
+               on-screen value to keep-stale-and-swap, so firing the network now is
+               wasted work that may be stale again before anything shows it. Drop the
+               entry so the next read reloads fresh instead — the same lazy path a
+               reader-less invalidate() takes. */
+            if (!store.hasReader(entry.key)) {
+                store.entries.delete(entry.key)
+                continue
+            }
             /* 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) {
@@ -851,12 +868,11 @@ function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args):
             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. */
+                /* No policy, no request (a producer never cached with a refetch window): drop so the
+                   next read reloads. A reader is holding it (checked above), so flag the
+                   next read a reload (refreshing()). */
                 store.entries.delete(entry.key)
-                if (store.hasReader(entry.key)) {
-                    store.pendingRefresh.add(entry.key)
-                }
+                store.pendingRefresh.add(entry.key)
                 affected.push(entry.key)
             }
         }
@@ -921,7 +937,8 @@ function peek<Args, Return>(
           ? (fn as RemoteFunction<Args, Return>).raw
           : (fn as RawRemoteFunction<Args>)
     const key = isRemote
-        ? keyForRemoteCall(rawFn!.method, rawFn!.url, args)
+        ? // biome-ignore lint/style/noNonNullAssertion: rawFn is undefined only when !isRemote, so this branch has it
+          keyForRemoteCall(rawFn!.method, rawFn!.url, args)
         : producerKey(fn as Producer<Args, Return>, args)
     const active = activeCacheStore()
     active.subscribe(key)
@@ -940,11 +957,19 @@ function peek<Args, Return>(
        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) {
+       tap above lets hydrationWindow.wake re-run this scope on the congruent value. */
+    if (hydrationWindow.active) {
         return undefined
     }
-    return cloneWarmValue(entry.value) as Return
+    /* Revive structured fields after cloning: the clone is the honest-JSON wire form, and revive
+       turns a wire array into its declared Set/Map and an ISO string into a Date — so peek matches
+       fn(args) / cache(fn, args). A raw or producer read carries no plan → the clone passes through
+       untouched (revive is a no-op on an undefined plan). */
+    const plan =
+        isRemote && 'raw' in fn
+            ? (fn as { outputWirePlan?: OutputWirePlan }).outputWirePlan
+            : undefined
+    return reviveWireOutput(cloneWarmValue(entry.value), plan) as Return
 }
 
 cache.peek = peek
@@ -978,7 +1003,7 @@ function applyPatch(
 }
 
 /*
-Event-driven cache maintenance: subscribes to a Subscribable (socket or rpc
+Event-driven cache maintenance: subscribes to a NamedAsyncIterable (socket or rpc
 stream) and runs `handler` once per frame — the declarative home for "this
 socket event stales that cached data", replacing the hand-rolled $effect +
 tail() + edge-detection pattern. Bare iteration means live frames only
@@ -1005,7 +1030,7 @@ already seeded the cache. Dispose aborts `signal`, stops delivery, and
 closes the subscription.
 */
 function on<T>(
-    source: Subscribable<T>,
+    source: NamedAsyncIterable<T>,
     handler: (frame: T, context: CacheOnContext) => void | Promise<void>,
 ): () => void {
     if (typeof window === 'undefined') {
@@ -1074,7 +1099,7 @@ function on<T>(
 cache.on = on
 
 /*
-Schedules a coalesced refetch per the entry's swr policy. No window (swr: true):
+Schedules a coalesced refetch per the entry's refetch policy. No window:
 fire immediately (throttle defaults to 0, so the leading-edge branch always
 takes). debounce: (re)arm a timer that fires after N ms of quiet. throttle: fire
 on the leading edge when a full window has elapsed since the last fire, else arm
@@ -1162,7 +1187,7 @@ function fireRefetch(store: CacheStore, entry: CacheEntry): void {
                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
+               next read past it revalidates), a windowed producer entry re-arms the eviction
                clock. */
             if (entry.ttl !== undefined && entry.ttl !== 0) {
                 if (entry.retain) {
@@ -1269,7 +1294,7 @@ function attachPolicy(
     if (defaultOn) {
         entry.retain = true
     }
-    const policy = swrWindow(options, defaultOn)
+    const policy = refetchWindow(options, defaultOn)
     if (entry.invalidation || !policy) {
         return
     }
@@ -1284,7 +1309,7 @@ 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.
+a keep-stale (refetch-policy) 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.

package/src/lib/shared/canonicalJson.ts

@@ -8,7 +8,8 @@ POST/PUT/PATCH bodies; the output is a key, not a request body, so it is free to
 encode types JSON.stringify would silently flatten (Map/Set → {}), coerce
 (Date → its ISO string, via toJSON before any replacer sees it) or drop
 (undefined). Covers the value types commonly passed as rpc args: primitives,
-arrays, plain objects, Date, Map, Set, and bigint. Functions and symbols can't
+arrays, plain objects, Date, Map, Set, bigint, and FormData/File/Blob (the
+multipart upload path). Functions and symbols can't
 key anything meaningful but are tagged rather than dropped so a stray one can't
 silently collapse two distinct argument sets onto the same key.
 */
@@ -55,6 +56,28 @@ export function canonicalJson(value: unknown): string {
         const members = Array.from(value, canonicalJson).sort()
         return `Set{${members.join(',')}}`
     }
+    /* FormData is the documented multipart escape hatch for body rpcs. Its fields are
+       NOT own enumerable keys, so the generic object branch below would return `{}` for
+       every distinct upload — collapsing them onto one cache key and coalescing unrelated
+       uploads onto each other. Encode its entries (sorted, so field order doesn't change
+       the key) with File/Blob distinguished by identity attributes below. */
+    if (typeof FormData !== 'undefined' && value instanceof FormData) {
+        const entries: string[] = []
+        value.forEach((entryValue, entryKey) => {
+            entries.push(`${JSON.stringify(entryKey)}=>${canonicalJson(entryValue)}`)
+        })
+        entries.sort()
+        return `FormData{${entries.join(',')}}`
+    }
+    /* File extends Blob — check it first so a named upload keys on its name too. Contents
+       can't be read synchronously, so identity attributes are the best available key;
+       distinct files (name/size/type/mtime) get distinct keys, which is the fix. */
+    if (typeof File !== 'undefined' && value instanceof File) {
+        return `File(${JSON.stringify(value.name)},${value.size},${JSON.stringify(value.type)},${value.lastModified})`
+    }
+    if (typeof Blob !== 'undefined' && value instanceof Blob) {
+        return `Blob(${value.size},${JSON.stringify(value.type)})`
+    }
     const record = value as Record<string, unknown>
     const entries = Object.keys(record)
         .sort()

package/src/lib/shared/changeAffectsClient.ts

@@ -1,3 +1,5 @@
+import { PROXIED_SERVER_SUBDIRS } from './PROXIED_SERVER_SUBDIRS.ts'
+
 /*
 Classifies a watcher change (a path relative to the project's `src/`, with
 either OS separator) by whether it can alter the client bundle. The dev
@@ -9,8 +11,8 @@ Server/MCP-only — client unaffected, skip the client rebuild:
                         path (rpc url) and the `<METHOD>(...)` wrapper, not the
                         handler body; the rpc manifest is server-only. A body
                         edit produces an identical stub. (Risk: changing the
-                        method, the export name, or `outbox: true` does change
-                        the stub — those need a manual full rebuild.)
+                        method or the export name does change the stub — those
+                        need a manual full rebuild.)
 - `server/sockets/**` — name-only `socketProxy` stubs derived from the file
                         path; socket opts are server-side. Body edits don't
                         change the stub.
@@ -26,10 +28,13 @@ full rebuild rather than risking a stale client.
 */
 export function changeAffectsClient(relativePath: string): boolean {
     const path = relativePath.split('\\').join('/')
-    const serverOnly =
-        path.startsWith('server/rpc/') ||
-        path.startsWith('server/sockets/') ||
-        path.startsWith('mcp/') ||
-        path === 'server/config.ts'
+    /* The proxied server dirs (rpc/sockets) ship path-derived stubs, so a body edit can't change the
+       client bundle. Read from the shared PROXIED_SERVER_SUBDIRS authority so this stays in lockstep
+       with the resolver's side-classifier. mcp/** and server/config.ts are additional server-only
+       skips specific to this classifier (not proxied — never imported by the client at all). */
+    const proxiedServerOnly = PROXIED_SERVER_SUBDIRS.some((subdir) =>
+        path.startsWith(`server/${subdir}/`),
+    )
+    const serverOnly = proxiedServerOnly || path.startsWith('mcp/') || path === 'server/config.ts'
     return !serverOnly
 }

package/src/lib/shared/createCacheStore.ts

@@ -1,3 +1,4 @@
+import { REACTIVE_CONTEXT } from '../ui/runtime/REACTIVE_CONTEXT.ts'
 import { createLifecycleChannel } from './createLifecycleChannel.ts'
 import { createSubscriber } from './createSubscriber.ts'
 import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
@@ -28,6 +29,16 @@ export function createCacheStore(): CacheStore {
     const pendingRefresh = new Set<string>()
 
     function subscribe(key: string): void {
+        /* An untracked read (an event handler, a setup-time `await getFoo()`, any
+           server render) subscribes to nothing: `track` inside createSubscriber no-ops,
+           node.subsHead stays empty, and the resource never opens. Skip the bookkeeping
+           too — otherwise a bare read would pin an entry in `subscribers` for the tab's
+           lifetime, growing the map and leaving hasReader() over-reporting a reader that
+           isn't there. Honouring the tracking seam here makes hasReader() mean exactly
+           "a live tracking reader exists". */
+        if (REACTIVE_CONTEXT.observer === undefined) {
+            return
+        }
         const existing = subscribers.get(key)
         if (existing) {
             existing()
@@ -63,9 +74,12 @@ export function createCacheStore(): CacheStore {
     /*
     Per-prefix channels arm fn-selector probes (pending(fn) / refreshing(fn))
     without waking them on unrelated cache events. Keyed by selector prefix
-    (method+url / producer reference id — see selectorPrefix), so the
-    population is bounded by probe call sites in code, not by data; a channel
-    whose last reader tore down is an inert closure, not a leak.
+    (method+url / producer reference id — see selectorPrefix). Probes carry the
+    FULL call key when args are given (pending(fn, args) / peek(fn, args)), so a
+    long session that probes many distinct ids would otherwise accrete one map
+    entry per id on the tab-scoped store forever and make markLifecycle's forEach
+    O(distinct-keys-ever-probed). Each channel evicts its own entry once its last
+    reader tears down (identity-guarded against a concurrent re-track).
     */
     const prefixLifecycles = new Map<string, ReturnType<typeof createLifecycleChannel>>()
 
@@ -76,7 +90,15 @@ export function createCacheStore(): CacheStore {
         }
         let channel = prefixLifecycles.get(keyPrefix)
         if (channel === undefined) {
-            channel = createLifecycleChannel()
+            const created = createLifecycleChannel(() => {
+                /* Drop the entry only if it's still THIS channel — a concurrent re-track may have
+                   replaced it, and createSubscriber's own reader-count guard means onIdle fires
+                   only when genuinely reader-less. */
+                if (prefixLifecycles.get(keyPrefix) === created) {
+                    prefixLifecycles.delete(keyPrefix)
+                }
+            })
+            channel = created
             prefixLifecycles.set(keyPrefix, channel)
         }
         channel.track()
@@ -103,10 +125,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. */
+        /* True iff a live tracking scope is reading this key — i.e. someone is holding
+           its value on screen right now. An untracked read never registers (subscribe
+           gates on the tracking seam), so a bare handler/setup read does not make this
+           true. invalidate()/refresh() gate 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,