@abide/abide 0.47.0 → 0.48.0

package/AGENTS.md

@@ -92,12 +92,17 @@ validate as args, `File` parts validate against `filesSchema`.
 
 **Consuming an rpc** — the bare call `fn(args, opts?)` IS the smart read:
 cached, coalesced, reactive, stale-while-revalidate for replayable (GET/HEAD)
-reads; the second arg takes `{ ttl, tags, throttle, debounce, global, n }`
-(retention and the refetch clock — not transport). `global: true` stores the
-entry in the process-level store instead of the request-scoped default
-(server), so later requests reuse the value — for memoising an external
-endpoint, never per-user data; on the client it is a no-op (one tab store).
-During SSR the same call resolves
+reads; the second arg takes `{ ttl, tags, throttle, debounce, shared, n }`
+(retention and the refetch clock — not transport). `ttl` defaults to `0` on
+the server (coalesce-only — the request is the atomic unit, nothing is
+retained past it) and `Infinity` on the client (retain until invalidate/
+refresh). `shared: true` selects the process-level store instead of the
+request-scoped default (server) — it does not by itself retain, pair it with
+an explicit `ttl` (e.g. `{ shared: true, ttl: Infinity }`) to memoise across
+requests, for an external endpoint, never per-user data; on the client it is
+a no-op (one tab store). A read with no request in flight (e.g. a background
+job) also resolves against the process-level store. During SSR the same call
+resolves
 in-process and its value is baked into the HTML so hydration starts warm —
 there is no `cache()` wrapper; the bare call carries the caching. Around it:
 `fn.raw(args, init?)` returns the raw `Response` (per-call transport options —

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # abide
 
+## 0.48.0
+
+### Minor Changes
+
+- 182cdf5: server reads coalesce-only by default, SWR retain client-only ([`98a3e84`](https://github.com/briancray/abide/commit/98a3e84b1e6bdb50b8950a4197ec4a255c560d2a))
+- 182cdf5: warn on a request-scoped ttl>0 read (add shared or drop ttl) ([`b55425c`](https://github.com/briancray/abide/commit/b55425c986fb4c7cebcb1e8c29d1c616466d7d63))
+
+### Patch Changes
+
+- 182cdf5: rename global option/exports/comments to shared ([`1256934`](https://github.com/briancray/abide/commit/125693481ba23152a44375bbe200d575b66fdf9a))
+- 182cdf5: evict outside-request coalesce-only entries; correct shared help copy ([`1b73e21`](https://github.com/briancray/abide/commit/1b73e21c33c8ee985f7109fdedcbe302322ce7d1))
+- 182cdf5: route outside-a-request server reads to the shared store ([`456cfa6`](https://github.com/briancray/abide/commit/456cfa662405714df99545e02ed6e3b851da84df))
+- 182cdf5: Breaking: the `global` cache option is renamed `shared`, and it no longer implies retention. `{ global: true }` (memoise across requests forever) becomes `{ shared: true, ttl: Infinity }` — `shared` now only selects the process store, while `ttl` alone controls retention (default `0` on the server = coalesce-only, `Infinity` on the client). Reads made with no request in flight resolve to the shared store instead of an orphan fallback. ([`d94f0f9`](https://github.com/briancray/abide/commit/d94f0f9cb15a5822b2d5824db7e32da27368fe04))
+
 ## 0.47.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.47.0",
+    "version": "0.48.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",

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

@@ -1,4 +1,4 @@
-import { globalCacheStore } from '../../shared/globalCacheStore.ts'
+import { sharedCacheStore } from '../../shared/sharedCacheStore.ts'
 import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
 import type { InspectorCacheEntry } from './types/InspectorCacheEntry.ts'
 import type { InspectorCacheSnapshot } from './types/InspectorCacheSnapshot.ts'
@@ -48,14 +48,14 @@ function projectEntry(entry: CacheEntry, now: number): InspectorCacheEntry {
 }
 
 /*
-Snapshots the process-level cache store (the persistent one `cache(fn, { global:
-true })` writes to) for the inspector. Read at call time, so it reflects the
-store as it stands; request-scoped stores are deliberately excluded — they're
-ephemeral and already visible as per-request cache tallies.
+Snapshots the process-level cache store (the persistent one `cache(fn, { shared:
+true, ttl: Infinity })` writes to) for the inspector. Read at call time, so it
+reflects the store as it stands; request-scoped stores are deliberately
+excluded — they're ephemeral and already visible as per-request cache tallies.
 */
 export function buildCacheSnapshot(): InspectorCacheSnapshot {
     const now = Date.now()
-    const entries = Array.from(globalCacheStore().entries.values(), (entry) =>
+    const entries = Array.from(sharedCacheStore().entries.values(), (entry) =>
         projectEntry(entry, now),
     )
     return { entries }

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

@@ -1,5 +1,5 @@
 /*
-One global cache entry projected for the inspector — the serializable facts the
+One shared cache entry projected for the inspector — the serializable facts the
 Cache tab renders. The stored promise/Request/timer aren't included; what an
 operator wants is the entry's identity, lifecycle state, retention, and a peek
 at the held value.

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

@@ -1,10 +1,10 @@
 import type { InspectorCacheEntry } from './InspectorCacheEntry.ts'
 
 /*
-The inspector's view of the cache: the process-level (`global: true`) store's
-current entries. That's the persistent store — request-scoped caches live and
-die with their request, so they surface as per-request tallies in the feed and
-traces rather than here.
+The inspector's view of the cache: the process-level (`shared: true, ttl:
+Infinity`) store's current entries. That's the persistent store —
+request-scoped caches live and die with their request, so they surface as
+per-request tallies in the feed and traces rather than here.
 */
 export type InspectorCacheSnapshot = {
     entries: InspectorCacheEntry[]

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

@@ -17,7 +17,7 @@ export type InspectorContext = {
     app: { name: string; version: string }
     /* Eager-loads the registries, then projects the current RPC + socket catalog. */
     loadSurface: () => Promise<InspectorSurface>
-    /* Snapshots the persistent (global) cache store — current entries with their
+    /* Snapshots the persistent (shared) cache store — current entries with their
        lifecycle state, retention, tags, and a value preview. */
     cacheSnapshot: () => InspectorCacheSnapshot
     /* Snapshots the requests whose handler is executing right now — the live

package/src/lib/shared/cache.ts

@@ -3,7 +3,6 @@ import { activeCacheStore } from './activeCacheStore.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'
@@ -16,6 +15,7 @@ import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
 import { SocketDisconnectedError } from './SocketDisconnectedError.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
+import { sharedCacheStore } from './sharedCacheStore.ts'
 import { openStreamProbe } from './subscribableProbes.ts'
 import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
@@ -36,7 +36,7 @@ const cacheLog = abideLog.channel('abide:cache')
 
 /*
 Tallies one read and narrates it on the diagnostics channel. The sink is the
-request/tab store even when the data store is the process-level global one —
+request/tab store even when the data store is the process-level shared one —
 attribution follows the asker, so a request's closing record reflects every
 read it made. A settled retained entry (including the warm SSR sync path) is
 a hit; an unsettled entry is a coalesced join of an in-flight call; no entry
@@ -62,8 +62,10 @@ Reads a call through a cache store. `cache(fn, args?, options?)` checks the stor
 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.
+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).
 
 Coalescing is always on: identical in-flight calls share one flight, so
 `cache(createPost, args, { ttl: 0 })` is the mutation idiom — double-submit
@@ -87,7 +89,7 @@ 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.global` puts the entry in the process-level store instead of the
+`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
@@ -172,9 +174,9 @@ 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.
+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.
 */
 function readThrough<Args, Return>(
     fn: AnyRemote<Args, Return> | Producer<Args, Return>,
@@ -200,30 +202,45 @@ function readThrough<Args, Return>(
     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
+    /* 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'
     /*
-    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).
+    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.
     */
-    const effectiveOptions =
-        smart && isRemote && !replayable && options?.ttl === undefined
-            ? { ...options, ttl: 0 }
-            : options
+    const serverTtlZero =
+        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
     if (!isRemote) {
         warnAnonymousProducer(fn as Producer<Args, Return>)
     }
-    const store = effectiveOptions?.global ? globalCacheStore() : activeCacheStore()
+    const store = effectiveOptions?.shared ? sharedCacheStore() : 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)
+    if (
+        !effectiveOptions?.shared &&
+        effectiveOptions?.ttl !== undefined &&
+        effectiveOptions.ttl > 0 &&
+        store !== sharedCacheStore()
+    ) {
+        warnEphemeralTtl(key)
+    }
     store.subscribe(key)
     const existing = store.entries.get(key)
-    recordRead(effectiveOptions?.global ? activeCacheStore() : store, key, existing)
+    recordRead(effectiveOptions?.shared ? activeCacheStore() : store, key, existing)
     if (existing) {
         tagEntry(existing, effectiveOptions?.tags)
         attachPolicy(existing, effectiveOptions, () => remote(args as Args), retain)
@@ -390,6 +407,20 @@ function warnAnonymousProducer(producer: (args?: never) => unknown): void {
     )
 }
 
+/* Warn once per key when a ttl>0 read lands in an ephemeral (request-scoped)
+   store — the ttl expires with the request. `shared` (the process store) or a
+   client tab store are the retention homes; a request-scoped ttl is dead config. */
+const warnedEphemeralTtl = new Set<string>()
+function warnEphemeralTtl(key: string): void {
+    if (warnedEphemeralTtl.has(key)) {
+        return
+    }
+    warnedEphemeralTtl.add(key)
+    abideLog.warn(
+        `cache(): a request-scoped ttl expires with the request — add \`shared\` to cache "${key}" across requests, or drop the ttl.`,
+    )
+}
+
 /*
 Producer path: key on the producer's reference + args, share the
 in-flight/retained promise on hit, and store the value promise as-is on miss — no
@@ -404,7 +435,7 @@ function invokeProducer<Args, Return>(
     const key = producerKey(producer, args)
     store.subscribe(key)
     const existing = store.entries.get(key)
-    recordRead(options?.global ? activeCacheStore() : store, key, existing)
+    recordRead(options?.shared ? activeCacheStore() : store, key, existing)
     if (existing) {
         tagEntry(existing, options?.tags)
         attachPolicy(existing, options, () => producer(args), false)
@@ -502,11 +533,18 @@ function registerEntry(
     own method filter; writes never ship). The keep never applies on the
     client (the tab store outlives any unit — a kept write would block every
     future re-submit, so entries evict the moment they settle), to producer
-    entries (no request), or to the process-level `global` store (not
-    request-scoped — keeping it would leak forever).
+    entries (no request), or when the resolved store is the process-level
+    `shared` store — including a non-shared read made outside an inbound
+    request, where the resolver falls back to `sharedCacheStore()` (Decision
+    1): that store is never request-scoped, so keeping it would leak forever.
+    The `store !== sharedCacheStore()` check is what tells a genuinely
+    request-scoped store apart from that fallback.
     */
     const keepZeroTtlForRequest =
-        request !== undefined && !options?.global && typeof window === 'undefined'
+        request !== undefined &&
+        !options?.shared &&
+        typeof window === 'undefined' &&
+        store !== sharedCacheStore()
     function deleteIfCurrent() {
         evictIfCurrent(store, entry)
     }
@@ -890,10 +928,10 @@ function peek<Args, Return>(
     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)
+        const shared = sharedCacheStore()
+        shared.subscribe(key)
+        shared.trackLifecycle(key)
+        entry = shared.entries.get(key)
     }
     if (entry === undefined || entry.settled !== true || entry.value === undefined) {
         return undefined

package/src/lib/shared/cacheStores.ts

@@ -1,10 +1,10 @@
 import { activeCacheStore } from './activeCacheStore.ts'
-import { globalCacheStore } from './globalCacheStore.ts'
+import { sharedCacheStore } from './sharedCacheStore.ts'
 import type { CacheStore } from './types/CacheStore.ts'
 
 /* Active + process-level stores, deduped (one tab store on the client). */
 export function cacheStores(): CacheStore[] {
     const active = activeCacheStore()
-    const global = globalCacheStore()
-    return active === global ? [active] : [active, global]
+    const shared = sharedCacheStore()
+    return active === shared ? [active] : [active, shared]
 }

package/src/lib/shared/refresh.ts

@@ -4,9 +4,9 @@ import type { CacheSelector } from './types/CacheSelector.ts'
 /*
 Refetch every cached read matching the selector, keeping the stale value visible
 until the fresh one swaps in (refreshing() true meanwhile) — the smart-call
-refetch. Because the smart read retains its value (SWR unconditional), a refresh
-always refetches-and-swaps; it never drops to a pending blank. Follows the shared
-selector grammar:
+refetch. Because the smart read retains its value on the client (SWR
+unconditional there), a refresh always refetches-and-swaps; it never drops to a
+pending blank. Follows the shared selector grammar:
 
   refresh(getFoo, args)   → that exact call
   refresh(getFoo)         → every args-variant of that rpc

package/src/lib/shared/sharedCacheStore.ts

@@ -0,0 +1,14 @@
+import { activeCacheStore } from './activeCacheStore.ts'
+import { sharedCacheStoreSlot } from './sharedCacheStoreSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Resolves the process-level ("shared") CacheStore that `cache(fn, { shared: true })`
+entries live in. The server entry registers a module-singleton resolver so the
+store survives across requests; the client points it at the active tab store.
+When no resolver is registered it falls back to the active store, so `shared`
+degrades to request/tab-scoped rather than throwing.
+*/
+export function sharedCacheStore(): CacheStore {
+    return sharedCacheStoreSlot.resolver?.() ?? activeCacheStore()
+}

package/src/lib/shared/sharedCacheStoreSlot.ts

@@ -0,0 +1,10 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+The process-level ("shared") CacheStore slot that `cache(fn, { shared: true })`
+entries live in. The server entry registers a module-singleton store outliving
+every request; the client points it at the active tab store. When no resolver
+is registered, sharedCacheStore() falls back to the active store.
+*/
+export const sharedCacheStoreSlot = createResolverSlot<CacheStore>()

package/src/lib/shared/types/CacheOptions.ts

@@ -2,21 +2,25 @@
 Options for cache(). The key is always auto-derived (method+url+args for a remote
 function, producer-reference+args for a plain producer): hoist a producer to a
 stable reference to share its entry across calls. `ttl` is the
-milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
-dedupe only (entry dropped once the promise settles — the mutation idiom:
-in-flight coalescing and pending() visibility, nothing retained), any other
-number = TTL.
+milliseconds-past-resolve that the entry stays live: 0 = dedupe only (entry
+dropped once the promise settles — the mutation idiom: in-flight coalescing and
+pending() visibility, nothing retained), any other number = TTL. Omitted = 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 — the request is
+the atomic unit, nothing is retained past it; pair with `shared` + an explicit
+`ttl` to memoise across requests).
 `tags` is an array of free-form labels grouping unrelated calls so one
 `cache.invalidate({ tags })` drops every entry sharing any of them — list
 multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
 a uuid) shared by a set of calls gives them their own private invalidation group.
 
-`global` opts the entry into the process-level store instead of the default
-request-scoped one (server) — so a value computed in one request is reused by
-later requests, e.g. memoising an external endpoint the server calls. Omit it
-for per-request data: the default keeps a per-user response from leaking across
-requests. Write only `global: true`; there is no `false` form. On the client
-there is a single tab store, so the flag is a no-op there.
+`shared` opts the entry into the process-level store instead of the default
+request-scoped one (server) — a store that outlives every request. It selects
+the store only; it does NOT retain (pair it with `ttl` to memoise across
+requests). The shared store is keyed by method+url+args, never by user, so do
+not put per-user data in it — it would be served to other users. Omit `shared`
+for per-request data. Write only `shared: true`; there is no `false` form. On
+the client there is a single tab store, so the flag is a no-op there.
 
 `swr` is stale-while-revalidate: it changes what a `cache.invalidate` hit does
 to this key. Without it, an invalidate drops the entry and the next read shows
@@ -44,7 +48,7 @@ with the same wrap-time guard as the `swr` window: set one, not both.
 export type CacheOptions = {
     ttl?: number
     tags?: string[]
-    global?: boolean
+    shared?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
     throttle?: number
     debounce?: number

package/src/lib/shared/types/CacheStats.ts

@@ -2,7 +2,7 @@
 Per-store cache read tallies, frozen into the request's closing log record at
 settle. hit = a read served from a settled retained entry (including the warm
 SSR sync path); coalesced = a read that joined an in-flight call; miss = a
-read that invoked its producer/remote. Reads against the process-level global
+read that invoked its producer/remote. Reads against the process-level shared
 store count into the requesting scope's store, so a request's record reflects
 everything that request asked the cache for.
 */

package/src/lib/shared/types/SmartReadOptions.ts

@@ -5,19 +5,23 @@ these govern retention and the refetch clock — NOT transport. Per-call transpo
 options (signal/keepalive/priority/cache/headers) live on `.raw(args, init)`.
 
 Fetch reads:
-- `ttl` — retention/staleness in ms: undefined = retain forever (no auto-refetch),
-  N ms = the retained value goes stale after N ms and the next access triggers a
-  background revalidation (stale stays visible, `refreshing()` true). The display
-  value is never dropped; ttl drives staleness, not eviction.
+- `ttl` — retention/staleness in ms. Default: 0 on the server (coalesce-only —
+  the request is the atomic unit, nothing is retained past it), Infinity on the
+  client (retain until invalidate/refresh — the tab is the atomic unit). On the
+  client, N ms marks a staleness deadline: the retained value goes stale after N
+  ms and the next access triggers a background revalidation (stale stays visible,
+  `refreshing()` true); the display value is never dropped. On the server, N ms
+  is a plain expiry and only takes effect in the shared store (pair with `shared`).
 - `tags` — free-form invalidation-group labels (see the selector grammar).
 - `throttle` / `debounce` — rate-limit the background refetch clock (set one, not
   both). Leading-edge-then-coalesce, or fire-after-quiet respectively.
-- `global` — store the entry in the process-level store instead of the default
-  request-scoped one (server), so a value computed in one request is reused by
-  later requests — the memoise-an-external-endpoint case. Omit it for per-user
-  data: the default keeps a per-user response from leaking across requests.
-  Write only `global: true`; there is no `false` form. On the client there is a
-  single tab store, so the flag is a no-op there.
+- `shared` — opts the entry into the process-level store instead of the default
+  request-scoped one (server) — a store that outlives every request. It selects
+  the store only; it does NOT retain (pair it with `ttl` to memoise across
+  requests). The shared store is keyed by method+url+args, never by user, so do
+  not put per-user data in it — it would be served to other users. Omit `shared`
+  for per-request data. Write only `shared: true`; there is no `false` form. On
+  the client there is a single tab store, so the flag is a no-op there.
 
 Streaming reads (jsonl/sse):
 - `n` — how many retained frames to replay before going live.
@@ -27,6 +31,6 @@ export type SmartReadOptions = {
     tags?: string[]
     throttle?: number
     debounce?: number
-    global?: boolean
+    shared?: boolean
     n?: number
 }

package/src/lib/test/createTestApp.ts

@@ -37,10 +37,10 @@ import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
-import { globalCacheStoreSlot } from '../shared/globalCacheStoreSlot.ts'
 import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
+import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { Socket } from '../shared/types/Socket.ts'
 import { createTestSocketChannel } from './createTestSocketChannel.ts'
@@ -98,15 +98,15 @@ leaking the request-scope/cache/page resolvers into the next test file.
 export async function createTestApp(): Promise<TestApp> {
     const previous = {
         cacheResolver: cacheStoreSlot.resolver,
-        globalResolver: globalCacheStoreSlot.resolver,
+        sharedResolver: sharedCacheStoreSlot.resolver,
         pageResolver: pageSlot.resolver,
         baseResolver: baseSlot.resolver,
         activeServer: serverSlot.active,
     }
 
-    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache
-    const globalStore = createCacheStore()
-    globalCacheStoreSlot.resolver = () => globalStore
+    const sharedStore = createCacheStore()
+    sharedCacheStoreSlot.resolver = () => sharedStore
+    cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedStore
     pageSlot.resolver = resolvePageSnapshot
 
     /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
@@ -185,7 +185,7 @@ export async function createTestApp(): Promise<TestApp> {
         channel?.close()
         server.stop(true)
         cacheStoreSlot.resolver = previous.cacheResolver
-        globalCacheStoreSlot.resolver = previous.globalResolver
+        sharedCacheStoreSlot.resolver = previous.sharedResolver
         pageSlot.resolver = previous.pageResolver
         baseSlot.resolver = previous.baseResolver
         serverSlot.active = previous.activeServer

package/src/lib/ui/startClient.ts

@@ -1,7 +1,7 @@
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
-import { globalCacheStoreSlot } from '../shared/globalCacheStoreSlot.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
+import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
 import type { SsrPayload } from '../shared/types/SsrPayload.ts'
 import type { StreamedResolution } from '../shared/types/StreamedResolution.ts'
 import { probeNavigation } from './probeNavigation.ts'
@@ -68,8 +68,8 @@ export function startClient(
 
     const store = createCacheStore()
     cacheStoreSlot.resolver = () => store
-    /* One tab store: cache(fn, { global: true }) shares it, so global is a no-op here. */
-    globalCacheStoreSlot.resolver = () => store
+    /* One tab store: cache(fn, { shared: true }) shares it, so shared is a no-op here. */
+    sharedCacheStoreSlot.resolver = () => store
     /* Seed both SSR cache partitions through the one streamed-resolution sink: `ssr.cache`
        (inline — reads settled at render-return, in __SSR__) and `__abideResumeCache` (pending
        {#await} reads whose `__abideResolve(...)` chunks the stream pushed during parse, before

package/src/serverEntry.ts

@@ -31,10 +31,10 @@ import { requestContext } from './lib/server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from './lib/server/runtime/resolvePageSnapshot.ts'
 import { cacheStoreSlot } from './lib/shared/cacheStoreSlot.ts'
 import { createCacheStore } from './lib/shared/createCacheStore.ts'
-import { globalCacheStoreSlot } from './lib/shared/globalCacheStoreSlot.ts'
 import { loadEnvFromDataDir } from './lib/shared/loadEnvFromDataDir.ts'
 import { pageSlot } from './lib/shared/pageSlot.ts'
 import { runningAsStandaloneBinary } from './lib/shared/runningAsStandaloneBinary.ts'
+import { sharedCacheStoreSlot } from './lib/shared/sharedCacheStoreSlot.ts'
 
 /*
 Resolve config into process.env before anything reads it (createServer reads
@@ -65,16 +65,18 @@ await import('./_virtual/config.ts')
 // In a bundle, tie this server's life to the launcher's (no-op standalone).
 exitWithParent()
 
-cacheStoreSlot.resolver = () => requestContext.getStore()?.cache
-
-pageSlot.resolver = resolvePageSnapshot
-
 /*
-Process-level store for cache(fn, { global: true }) — one per server process,
-outlives every request so memoised external calls are shared across them.
+Process-level ("shared") store for cache(fn, { shared: true }) — one per server
+process, outlives every request so memoised external calls are shared across them.
+It is also the store a read with no request in flight resolves to, so boot/cron/
+socket-handler reads coalesce into a real store instead of an orphan fallback.
 */
-const globalCacheStore = createCacheStore()
-globalCacheStoreSlot.resolver = () => globalCacheStore
+const sharedCacheStore = createCacheStore()
+sharedCacheStoreSlot.resolver = () => sharedCacheStore
+
+cacheStoreSlot.resolver = () => requestContext.getStore()?.cache ?? sharedCacheStore
+
+pageSlot.resolver = resolvePageSnapshot
 
 await createServer({
     pages,

package/src/lib/shared/globalCacheStore.ts

@@ -1,15 +0,0 @@
-import { activeCacheStore } from './activeCacheStore.ts'
-import { globalCacheStoreSlot } from './globalCacheStoreSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
-
-/*
-Resolves the process-level CacheStore that `cache(fn, { global: true })` entries
-live in. The server entry registers a module-singleton resolver so the store
-survives across requests; the client points it at the active tab store. When no
-resolver is registered (isolated tests, or a client that never set one) it falls
-back to the active store, so `global` degrades to request/tab-scoped rather than
-throwing.
-*/
-export function globalCacheStore(): CacheStore {
-    return globalCacheStoreSlot.resolver?.() ?? activeCacheStore()
-}

package/src/lib/shared/globalCacheStoreSlot.ts

@@ -1,12 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
-
-/*
-Slot for the process-level cache store used by cache() entries opting into
-`global: true`. The server entry registers a module-singleton store outliving
-any one request; the client entry points it at its single tab store so
-`global` is a no-op there. No fallback creator — unset means no global store
-is registered, in which case globalCacheStore() falls back to the active
-(request/tab) store. Test helpers snapshot/poke `.resolver` directly.
-*/
-export const globalCacheStoreSlot = createResolverSlot<CacheStore>()