@abide/abide 0.53.0 → 0.55.0

package/src/lib/shared/cache.ts

@@ -176,10 +176,16 @@ 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. 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>.
+it returns Promise<Return>. `key` is the caller's already-derived cache key (the
+callable keys its rpc-error registry with it) — threaded through so readThrough
+reuses it instead of re-deriving the identical string; omitted, readThrough derives.
 */
-function smartRead<Args, Return>(fn: RemoteFunction<Args, Return>, args?: Args): Promise<Return> {
-    return readThrough(fn, args, undefined, true) as Promise<Return>
+function smartRead<Args, Return>(
+    fn: RemoteFunction<Args, Return>,
+    args?: Args,
+    key?: string,
+): Promise<Return> {
+    return readThrough(fn, args, undefined, true, key) as Promise<Return>
 }
 cache.read = smartRead
 
@@ -196,6 +202,7 @@ function readThrough<Args, Return>(
     args: Args | undefined,
     options: CacheOptions | undefined,
     smart: boolean,
+    precomputedKey?: string,
 ): Promise<Return | Response> {
     /*
     A remote function carries the REMOTE_FUNCTION brand (set by
@@ -239,13 +246,17 @@ function readThrough<Args, Return>(
     - 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.
+    Both apply on either side and however the call is made. An explicit `shared` defeats both:
+    it is a deliberate "memoise this across requests" opt-in (a POST that is a pure function
+    of its args, using the body only to carry a large payload — highlightCode), so it retains
+    in the process store with the default Infinity ttl rather than dropping on settle. An
+    explicit `ttl` already defeats them via the `ttl === undefined` guard above.
     */
     const coalesceOnly =
         isRemote &&
         policy?.ttl === undefined &&
-        (!replayable ||
-            (!policy?.shared && typeof window === 'undefined' && store === sharedCacheStore()))
+        !policy?.shared &&
+        (!replayable || (typeof window === 'undefined' && store === sharedCacheStore()))
     const effectiveOptions = coalesceOnly ? { ...policy, ttl: 0 } : policy
     if (!isRemote) {
         warnAnonymousProducer(fn as Producer<Args, Return>)
@@ -254,7 +265,12 @@ function readThrough<Args, Return>(
         return invokeProducer(store, fn as Producer<Args, Return>, args, effectiveOptions)
     }
     const remote = rawFn as RawRemoteFunction<Args>
-    const key = keyForRemoteCall(remote.method, remote.url, args)
+    /* Reuse the caller's derived key when it threaded one (the smart bare call already
+       computes it for its rpc-error registry, and remote is that callable's .raw — same
+       method/url, so the string is identical). Otherwise derive it — the public cache()
+       and the raw path pass none. Saves a query-encode / canonical-json stringify per read,
+       warm hits included. */
+    const key = precomputedKey ?? keyForRemoteCall(remote.method, remote.url, args)
     if (
         !effectiveOptions?.shared &&
         effectiveOptions?.ttl !== undefined &&
@@ -756,22 +772,100 @@ rather than a first-ever load. An empty or unmatched selector is a no-op on the
 cache; the lifecycle ping still fires but recomputes pending() to the same value.
 */
 function invalidate<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args): void {
-    /* Resolve the fn-selector prefix once; the matcher and the label both consume it. */
+    /* Resolve the fn-selector prefix once; the matcher, the label, and the exact-key
+       fast path all consume it. */
     const prefix = selectorPrefix(arg, args)
-    invalidateMatching(selectorMatcher(arg, args, prefix), selectorLabel(arg, args, prefix), prefix)
+    invalidateMatching(
+        selectorMatcher(arg, args, prefix),
+        selectorLabel(arg, args, prefix),
+        prefix,
+        exactSelectorKey(arg, args, prefix),
+    )
+}
+
+/*
+The single entry key a `fn + args` selector targets: args narrows the match to one
+call, so the resolved prefix IS the exact key — the apply loops can `Map.get` it
+directly instead of scanning every store. undefined for an all / bare-fn-prefix /
+tag selector (which may match many entries) so those still scan, and for a producer
+never cached (prefix undefined) whose scan matches nothing anyway.
+*/
+function exactSelectorKey<Args, Return>(
+    arg: CacheSelector<Args, Return> | undefined,
+    args: Args | undefined,
+    prefix: string | undefined,
+): string | undefined {
+    return typeof arg === 'function' && args !== undefined ? prefix : undefined
+}
+
+/*
+The ONE per-store selection dispatch every selector-driven verb runs through: an exact
+key (a fn + args selector, from exactSelectorKey) picks its single candidate via a
+direct Map.get instead of scanning; any other selector scans the store against
+`matches`. Shared so the fast path and the scan can't diverge across
+invalidate / refresh / amend (ADR-0041).
+*/
+function applyToMatching(
+    store: CacheStore,
+    exactKey: string | undefined,
+    matches: (entry: CacheEntry) => boolean,
+    apply: (entry: CacheEntry) => void,
+): void {
+    if (exactKey !== undefined) {
+        const entry = store.entries.get(exactKey)
+        if (entry !== undefined) {
+            apply(entry)
+        }
+        return
+    }
+    /* Deleting the current entry mid-iteration is spec-safe on a Map; no snapshot needed. */
+    for (const entry of store.entries.values()) {
+        if (matches(entry)) {
+            apply(entry)
+        }
+    }
+}
+
+/*
+The per-entry drop/refetch decision of invalidate() — the single seam so the full
+scan and the exact-key fast path can't diverge (ADR-0041). A refetch-policy entry is
+kept and its refetch coalesced; every other match is dropped so the next read reloads.
+*/
+function invalidateEntry(
+    store: CacheStore,
+    entry: CacheEntry,
+    matched: string[],
+    affected: string[],
+): void {
+    matched.push(entry.key)
+    if (entry.invalidation) {
+        scheduleInvalidationRefetch(store, entry)
+    } else {
+        store.entries.delete(entry.key)
+        /* Flag the next read a reload (refreshing()) — but only if a reader is
+           holding the value now; with none on screen the next read is a first
+           load, and an ungated add would linger forever on the tab store. */
+        if (store.hasReader(entry.key)) {
+            store.pendingRefresh.add(entry.key)
+        }
+        affected.push(entry.key)
+    }
 }
 
 /*
 The store-loop body of invalidate(), driven by a raw entry predicate rather than a
-selector — the single apply-by-matcher seam so a local invalidate() and a
-wire-driven one (a server broadcast decoded via matcherFromEnvelope) run the EXACT
-same drop loop and can't diverge (ADR-0041). `label` feeds the cycle tripwire;
-`prefix` (undefined for a tag selector) resets recorded rpc errors for the selector.
+selector — a local invalidate() and a wire-driven one (a server broadcast decoded via
+matcherFromEnvelope) share the per-entry `invalidateEntry` seam and can't diverge
+(ADR-0041). `label` feeds the cycle tripwire; `prefix` (undefined for a tag selector)
+resets recorded rpc errors for the selector. `exactKey` (a fn + args selector's one
+key, from exactSelectorKey) picks that entry directly instead of scanning; the
+wire-driven path passes none and scans as before.
 */
 function invalidateMatching(
     matches: (entry: CacheEntry) => boolean,
     label: string,
     prefix: string | undefined,
+    exactKey?: string,
 ): void {
     invalidateTripwire(label)
     /* Reset any recorded rpc errors for this selector too (independent of cache entries — a
@@ -782,25 +876,9 @@ function invalidateMatching(
     for (const store of cacheStores()) {
         const matched: string[] = []
         const affected: string[] = []
-        /* Deleting the current entry mid-iteration is spec-safe on a Map; no snapshot needed. */
-        for (const entry of store.entries.values()) {
-            if (!matches(entry)) {
-                continue
-            }
-            matched.push(entry.key)
-            if (entry.invalidation) {
-                scheduleInvalidationRefetch(store, entry)
-            } else {
-                store.entries.delete(entry.key)
-                /* Flag the next read a reload (refreshing()) — but only if a reader is
-                   holding the value now; with none on screen the next read is a first
-                   load, and an ungated add would linger forever on the tab store. */
-                if (store.hasReader(entry.key)) {
-                    store.pendingRefresh.add(entry.key)
-                }
-                affected.push(entry.key)
-            }
-        }
+        applyToMatching(store, exactKey, matches, (entry) =>
+            invalidateEntry(store, entry, matched, affected),
+        )
         /* Every match changed state (probes re-derive); only the dropped subset
            changed its visible value (readers re-read) — swr matches stay put. */
         notify(store, matched, affected)
@@ -851,18 +929,65 @@ 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)
-    refreshMatching(selectorMatcher(arg, args, prefix), selectorLabel(arg, args, prefix), prefix)
+    refreshMatching(
+        selectorMatcher(arg, args, prefix),
+        selectorLabel(arg, args, prefix),
+        prefix,
+        exactSelectorKey(arg, args, prefix),
+    )
+}
+
+/*
+The per-entry refetch/drop decision of refresh() — the single seam shared by the full
+scan and the exact-key fast path (ADR-0041). Only a match with a live reader refetches;
+a reader-less match drops so the next read reloads.
+*/
+function refreshEntry(
+    store: CacheStore,
+    entry: CacheEntry,
+    matched: string[],
+    affected: string[],
+): void {
+    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)
+        return
+    }
+    /* 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 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)
+        store.pendingRefresh.add(entry.key)
+        affected.push(entry.key)
+    }
 }
 
 /*
 The store-loop body of refresh(), driven by a raw entry predicate — the refetch
-analogue of invalidateMatching, so a local refresh() and a wire-driven one share
-one refetch loop (ADR-0041).
+analogue of invalidateMatching, so a local refresh() and a wire-driven one share the
+per-entry `refreshEntry` seam (ADR-0041). `exactKey` (a fn + args selector's one key)
+picks that entry directly instead of scanning; the wire-driven path passes none.
 */
 function refreshMatching(
     matches: (entry: CacheEntry) => boolean,
     label: string,
     prefix: string | undefined,
+    exactKey?: string,
 ): void {
     invalidateTripwire(label)
     if (prefix !== undefined) {
@@ -871,38 +996,9 @@ function refreshMatching(
     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)
-            /* 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) {
-                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 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)
-                store.pendingRefresh.add(entry.key)
-                affected.push(entry.key)
-            }
-        }
+        applyToMatching(store, exactKey, matches, (entry) =>
+            refreshEntry(store, entry, matched, affected),
+        )
         /* 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)
@@ -920,26 +1016,28 @@ 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.
+re-render when the amend lands). Follows the selector grammar, but only fn / args
+/ tags select a value to mutate; a not-yet-read key has nothing to amend.
 */
-function patch<Args, Return>(
+function amend<Args, Return>(
     arg: CacheSelector<Args, Return>,
     args: Args | undefined,
     updater: (current: Return) => Return,
+    isValue: boolean,
 ): void {
     const prefix = selectorPrefix(arg, args)
+    const exactKey = exactSelectorKey(arg, args, prefix)
     const matches = selectorMatcher(arg, args, prefix)
+    /* The exact-key arm is the optimistic-update / socket-frame path, potentially once
+       per frame — a direct Map.get through the shared dispatch, no scan. */
     for (const store of cacheStores()) {
-        for (const entry of store.entries.values()) {
-            if (matches(entry)) {
-                applyPatch(store, entry, updater as (current: unknown) => unknown)
-            }
-        }
+        applyToMatching(store, exactKey, matches, (entry) =>
+            applyAmend(store, entry, updater as (current: unknown) => unknown, isValue),
+        )
     }
 }
 
-cache.patch = patch
+cache.amend = amend
 
 /*
 Synchronous, non-triggering value probe: returns the currently-retained value for
@@ -947,7 +1045,7 @@ a call, or undefined when nothing is retained (no entry, or not yet settled). Ne
 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 —
+value changes (invalidate, amend) 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
@@ -1003,21 +1101,26 @@ function peek<Args, Return>(
 cache.peek = peek
 
 /*
-Applies one entry's patch: materialize the current decoded value (warm value if
+Applies one entry's amend: 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.
+readers re-read. Fire-and-forget on the async branch: amend() stays sync-return.
 */
-function applyPatch(
+function applyAmend(
     store: CacheStore,
     entry: CacheEntry,
     updater: (current: unknown) => unknown,
+    isValue: boolean,
 ): void {
     function apply(current: unknown): void {
         entry.value = updater(current)
         notify(store, [entry.key], [entry.key])
     }
-    if (entry.value !== undefined) {
+    /* A value-form amend is current-independent (its updater ignores the argument), so set it
+       directly and synchronously like the wire path (amendByKey) — never defer to the in-flight
+       promise. Deferring would drop the value if that fetch rejects (the reject handler below
+       swallows it), diverging local value-amend from the broadcast receive path. */
+    if (isValue || entry.value !== undefined) {
         apply(entry.value)
         return
     }
@@ -1030,6 +1133,25 @@ function applyPatch(
     currentValue.then(apply, () => undefined)
 }
 
+/*
+Wire-driven value apply (ADR-0043): set the retained value of the entry at an exact
+cache key and re-render its readers — the receive half of a server amend broadcast. A
+direct set, not the applyAmend materialize-current dance: the frame carries the
+authoritative value now, and the receiving subscriber is by construction reading this
+key. A key with no local entry is a no-op (nothing to amend).
+*/
+function amendByKey(key: string, value: unknown): void {
+    for (const store of cacheStores()) {
+        const entry = store.entries.get(key)
+        if (entry !== undefined) {
+            entry.value = value
+            notify(store, [entry.key], [entry.key])
+        }
+    }
+}
+
+cache.amendByKey = amendByKey
+
 /*
 Event-driven cache maintenance: subscribes to a NamedAsyncIterable (socket or rpc
 stream) and runs `handler` once per frame — the declarative home for "this
@@ -1353,8 +1475,5 @@ function notify(store: CacheStore, marked: string[], emitted: string[]): void {
 }
 
 function emit(store: CacheStore, keys: string[]): void {
-    if (keys.length === 0) {
-        return
-    }
     store.events.dispatchEvent(invalidateEvent(keys))
 }

package/src/lib/shared/cacheReaderSocketSlot.ts

@@ -0,0 +1,11 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheReaderHook } from './types/CacheReaderHook.ts'
+
+/*
+Client-only seam for the reactive-reader lifecycle (ADR-0043). No fallback: unresolved,
+get() is undefined and the store's engage/disengage calls are inert — so the server's
+request store and isolated unit tests do nothing. The client entry (startClient) installs
+a hook that opens a per-key amend value subscription on a key's first reader and closes it
+on its last, keeping the subscription set congruent with what this tab is reading.
+*/
+export const cacheReaderSocketSlot = createResolverSlot<CacheReaderHook>()

package/src/lib/shared/createCacheStore.ts

@@ -1,4 +1,5 @@
 import { REACTIVE_CONTEXT } from '../ui/runtime/REACTIVE_CONTEXT.ts'
+import { cacheReaderSocketSlot } from './cacheReaderSocketSlot.ts'
 import { createLifecycleChannel } from './createLifecycleChannel.ts'
 import { createSubscriber } from './createSubscriber.ts'
 import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
@@ -62,10 +63,17 @@ export function createCacheStore(): CacheStore {
                        Drop the marker so the tab-scoped store can't accrete one per
                        invalidated-but-never-reread key over a session. */
                     pendingRefresh.delete(key)
+                    /* Last reader gone: close any per-key amend subscription opened on engage
+                       (ADR-0043). Inert unless the client entry installed the hook. */
+                    cacheReaderSocketSlot.get()?.disengage(key)
                 }
             }
         })
         subscribers.set(key, registered)
+        /* First reader for this key: open a per-key amend value subscription (ADR-0043), so a
+           server amend(args, value) push lands on a key this tab is actually reading. Inert on
+           the server / in unit tests (slot unresolved). Paired with disengage in the cleanup. */
+        cacheReaderSocketSlot.get()?.engage(key)
         registered()
     }
 

package/src/lib/shared/createRemoteFunction.ts

@@ -142,7 +142,10 @@ export function createRemoteFunction<Args, Return>(opts: {
            `raw`. There is no call-site options argument any more — all cache policy is read
            from the endpoint (`callable.cache`); per-call transport options live on `.raw`. */
         const key = keyForRemoteCall(method, url, args)
-        return cache.read(callable as RemoteFunction<Args, Return>, args as Args).then(
+        /* Thread the derived key into the smart read so readThrough reuses it rather than
+           re-deriving the identical string (callable.raw carries the same method/url); the
+           key already tags the rpc-error registry entries in the handlers below. */
+        return cache.read(callable as RemoteFunction<Args, Return>, args as Args, key).then(
             /* Capture the rejection into the rpc error registry (design Part 4) keyed by call
                identity, and clear it on success — the reactive `fn.error()` probe reads it. */
             (value) => {

package/src/lib/shared/encodeSeedValue.ts

@@ -0,0 +1,24 @@
+import { encodeRefJson } from './encodeRefJson.ts'
+
+/*
+The ONE degradation site for every server→client hydration seed (ADR-0048): ref-json-encode
+a value bound for a warm-seed channel (await resume, cell value, doc snapshot, socket frame,
+streamed-cell chunk), or drop JUST that entry with a warn naming what was dropped and what
+the client does instead. encodeRefJson is total for ordinary graphs (cycles become
+back-references, functions fold to undefined), so a throw is pathological — but it must
+never blank the surrounding payload/stream. Funnelling every channel through here keeps the
+serialize-or-degrade policy, the warn shape, and the per-kind consequence in one place
+instead of seven independently-worded (or silent) drop sites.
+*/
+export function encodeSeedValue(
+    value: unknown,
+    label: string,
+    consequence: string,
+): string | undefined {
+    try {
+        return encodeRefJson(value)
+    } catch (cause) {
+        console.warn(`[abide] ${label} is not serializable — ${consequence}.`, cause)
+        return undefined
+    }
+}

package/src/lib/shared/jsonSchemaForType.ts

@@ -85,7 +85,7 @@ function project(
     // A `Set`/`Map` rides the wire as a JSON array (ADR-0029 output encode), so the projected schema
     // MUST agree with those bytes — a `Set<T>` is `T[]`, a `Map<K,V>` is `[K,V][]` entries.
     if (symbolName === 'Set' || symbolName === 'ReadonlySet') {
-        return projectSet(checker, type, seen)
+        return projectArray(checker, type, seen)
     }
     if (symbolName === 'Map' || symbolName === 'ReadonlyMap') {
         return projectMap(checker, type, seen)
@@ -131,7 +131,8 @@ function projectUnion(
     return { anyOf }
 }
 
-/* `T[]`/`readonly T[]` → `{ type: 'array', items: project(T) }`. */
+/* `T[]`/`readonly T[]` → `{ type: 'array', items: project(T) }`. Also serves `Set<T>`, which
+   rides the wire as `[...set]` (ADR-0029) — the same `T[]` shape. */
 function projectArray(
     checker: ts.TypeChecker,
     type: ts.Type,
@@ -144,20 +145,6 @@ function projectArray(
     return { type: 'array', items }
 }
 
-/* `Set<T>`/`readonly Set<T>` → `{ type: 'array', items: project(T) }` — congruent with the
-   `wireJsonReplacer` encode (`[...set]`). */
-function projectSet(
-    checker: ts.TypeChecker,
-    type: ts.Type,
-    seen: Set<ts.Type>,
-): Record<string, unknown> {
-    const element = checker.getTypeArguments(type as ts.TypeReference)[0]
-    seen.add(type)
-    const items = element === undefined ? {} : project(checker, element, seen)
-    seen.delete(type)
-    return { type: 'array', items }
-}
-
 /* `Map<K,V>`/`readonly Map<K,V>` → an array of `[K,V]` entry tuples — congruent with the
    `wireJsonReplacer` encode (`[...map]`). Each entry is a fixed 2-tuple, so the item schema is
    positional `prefixItems` with `items: false` to forbid extras (matching projectTuple). */

package/src/lib/shared/peek.ts

@@ -1,5 +1,6 @@
 import { cache } from './cache.ts'
 import { isAsyncCell } from './isAsyncCell.ts'
+import { isAsyncIterable } from './isAsyncIterable.ts'
 import type { AsyncComputed } from './types/AsyncComputed.ts'
 import type { RemoteFunction } from './types/RemoteFunction.ts'
 import type { Socket } from './types/Socket.ts'
@@ -8,7 +9,7 @@ import type { Socket } from './types/Socket.ts'
 The value member of the probe family: the currently-retained value, synchronously,
 without triggering anything — `T | undefined` (undefined when nothing is retained
 yet). For a cached read it is the retained cache value (reactive in a tracking
-scope — re-runs when a refresh lands or a patch mutates it; a one-shot snapshot
+scope — re-runs when a refresh lands or an amend mutates it; a one-shot snapshot
 otherwise). For a subscribable (socket / stream) it is the latest frame, read off
 the source's own `.peek()`. Instance sugar `getFoo.peek(args?)` ≡ `peek(getFoo,
 args?)`, `socket.peek()` ≡ `peek(socket)`.
@@ -38,12 +39,8 @@ export function peek(source: unknown, args?: unknown): unknown {
     /* A subscribable (socket/stream) carries its own latest-frame probe; an rpc does not
        have Symbol.asyncIterator, so this cleanly splits the two even though both expose a
        `.peek` method. */
-    if (
-        source !== null &&
-        typeof source === 'object' &&
-        typeof (source as { [Symbol.asyncIterator]?: unknown })[Symbol.asyncIterator] === 'function'
-    ) {
-        return (source as { peek: () => unknown }).peek()
+    if (isAsyncIterable(source)) {
+        return (source as unknown as { peek: () => unknown }).peek()
     }
     return cache.peek(source as RemoteFunction<unknown, unknown>, args as never)
 }

package/src/lib/shared/socketTailsSlot.ts

@@ -0,0 +1,13 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { SocketTails } from './types/SocketTails.ts'
+
+/*
+The active socket-tail slot — mirrors `resolvedCellsSlot`, but deliberately WITHOUT a lazily-created
+shared fallback. `defineSocket`'s server `peek()` records into it on every retained-frame read, and a
+socket peeked outside a request (a ws message handler, boot, cron) has no request store — a shared
+fallback would then accumulate entries no page render ever drains, a slow leak. With no fallback,
+`get()` returns undefined off-request and the record is skipped. During an SSR render the server
+entry's resolver returns the request store's list, which `createUiPageRenderer` drains into
+`__SSR__.sockets`.
+*/
+export const socketTailsSlot = createResolverSlot<SocketTails>()

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

@@ -0,0 +1,15 @@
+import type { CacheSelector } from './CacheSelector.ts'
+
+/*
+The side-swappable applier stored in amendBroadcastSlot (ADR-0043). Given a selector,
+its args, whether the payload is a concrete value (vs. an updater closure), and the
+payload itself, either apply it to this side's store (client / fallback) or broadcast
+the keyed value to every authorized reader (server). Only the value form is
+broadcastable; the server resolver throws on an updater (a closure has no wire form).
+*/
+export type AmendApply = <Args, Return>(
+    selector: CacheSelector<Args, Return>,
+    args: Args | undefined,
+    isValue: boolean,
+    payload: Return | ((current: Return) => Return),
+) => void

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

@@ -0,0 +1,11 @@
+/*
+The client-installed reactive-reader lifecycle hook stored in cacheReaderSocketSlot
+(ADR-0043). The cache store calls engage(key) when a key gains its first live reader
+and disengage(key) when it loses its last, so the client can open/close a per-key
+amend value subscription whose lifetime tracks "a reader is holding this key on
+screen". Inert (slot unresolved) on the server and in isolated unit tests.
+*/
+export interface CacheReaderHook {
+    engage(key: string): void
+    disengage(key: string): void
+}