@abide/abide 0.52.0 → 0.54.0

package/src/lib/shared/attachRpcSelectorMethods.ts

@@ -1,7 +1,7 @@
+import { amend } from './amend.ts'
 import { invalidate } from './invalidate.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
-import { patch } from './patch.ts'
 import { peek } from './peek.ts'
 import { pending } from './pending.ts'
 import { refresh } from './refresh.ts'
@@ -12,13 +12,13 @@ import type { RemoteFunction } from './types/RemoteFunction.ts'
 /*
 Attaches the pre-bound selector sugar onto an assembled RemoteFunction:
 `fn.pending(args?)` ≡ `pending(fn, args?)`, likewise refreshing / refresh / invalidate / peek,
-`fn.patch(args?, updater)` ≡ `patch(fn, args, updater)`, and `fn.error(args?)` — the typed
+`fn.amend(args?, value | updater)` ≡ `amend(fn, args, …)`, and `fn.error(args?)` — the typed
 last error from the rpc error registry (most-recent across the rpc when args omitted, that
 exact call when given). The cached read is the bare call `fn(args, opts)` itself; refetch is
 `fn.refresh(args?)`. The methods only reference the globals at call time, so the shared import
 edge carries no module-init dependency (safe against any cache ↔ createRemoteFunction cycle).
 Attached in createRemoteFunction so the server (defineRpc) and client (remoteProxy) shapes are
-identical. `patch` is attached uniformly; the type omits it for a streaming rpc (harmless at
+identical. `amend` is attached uniformly; the type omits it for a streaming rpc (harmless at
 runtime — a stream has no cache entry).
 */
 export function attachRpcSelectorMethods<Args, Return>(fn: RemoteFunction<Args, Return>): void {
@@ -28,8 +28,8 @@ export function attachRpcSelectorMethods<Args, Return>(fn: RemoteFunction<Args,
         refresh: (args?: Args) => refresh(fn, args),
         invalidate: (args?: Args) => invalidate(fn, args),
         peek: (args?: Args) => peek(fn, args),
-        patch: (argsOrUpdater?: unknown, updater?: unknown) =>
-            (patch as (fn: unknown, a?: unknown, b?: unknown) => void)(fn, argsOrUpdater, updater),
+        amend: (argsOrUpdater?: unknown, updater?: unknown) =>
+            (amend as (fn: unknown, a?: unknown, b?: unknown) => void)(fn, argsOrUpdater, updater),
         /* Reaction sugar is client-only (`watch` is a ui primitive that must not ride into a
            server bundle), so the shared attach binds an inert no-op — the server (defineRpc)
            shape carries `.watch` too, and an author `fn.watch(…)` surviving the SSR effect-strip

package/src/lib/shared/buildSocketOverChannel.ts

@@ -22,15 +22,22 @@ Bare iteration is the live stream (replay 0); `.tail(n)` seeds from the
 retained tail (no-arg = the whole tail). Each iterator mints its own sub id for
 lifecycle routing (end/err), and `hooks.replayed` fires in-band after the
 replay batch so a window reader commits its seed strictly before any live frame.
+
+`initialFrame` warm-seeds `lastFrame` at construction (socketProxy passes the
+server's retained frame from `__SSR__.sockets`) so `peek()` returns the SSR value
+at hydration instead of undefined — congruent with the server HTML until the ws
+delivers its own replay of the same frame.
 */
 export function buildSocketOverChannel<T>(
     name: string,
     resolveChannel: () => SocketChannel,
+    initialFrame?: T,
 ): Socket<T> {
     /* The latest frame seen across every iterator of this socket — what peek() returns and
        what refresh() re-seeds from the server tail. A plain slot (not reactive): peek(socket)
-       is a synchronous snapshot; live reactivity is the for-await / watch(socket) path. */
-    let lastFrame: T | undefined
+       is a synchronous snapshot; live reactivity is the for-await / watch(socket) path. Seeded
+       from the SSR-retained frame so a not-yet-connected client's peek matches the server. */
+    let lastFrame: T | undefined = initialFrame
     function iterate(replay: number | undefined, hooks?: TailHooks): AsyncIterable<T> {
         return {
             [Symbol.asyncIterator](): AsyncIterator<T, void, undefined> {

package/src/lib/shared/cache.ts

@@ -920,26 +920,27 @@ 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 matches = selectorMatcher(arg, args, prefix)
     for (const store of cacheStores()) {
         for (const entry of store.entries.values()) {
             if (matches(entry)) {
-                applyPatch(store, entry, updater as (current: unknown) => unknown)
+                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 +948,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 +1004,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 +1036,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

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/peek.ts

@@ -8,7 +8,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)`.

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
+}

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

@@ -71,7 +71,7 @@ export type RemoteFunction<
        reloads lazily, while `refresh(args?)` REFETCHES now keeping the stale value visible — both
        apply locally on the client and broadcast to every connected client from the server.
        `peek(args?)` reads the retained value synchronously (a streaming rpc peeks its latest
-       frame). `patch` is fetch-only, so it is omitted for a streaming rpc (a stream isn't a
+       frame). `amend` is fetch-only, so it is omitted for a streaming rpc (a stream isn't a
        memoized value) via the intersection below. */
     pending(args?: Args): boolean
     refreshing(args?: Args): boolean
@@ -84,22 +84,33 @@ export type RemoteFunction<
        shadow the server `error()` thrower). Reads the rpc error registry captured at the call
        boundary; the cache is untouched. */
     error(args?: Args): RpcError<Errors> | undefined
-    /* Client-only reaction sugar: `fn.watch(handler)` / `fn.watch(args, handler)` ≡
-       `watch(fn, …)` — runs the smart read reactively and pipes each resolved value to the
-       handler, returning a scope-tied disposer. Reaction is a client concern (`watch` is a ui
-       primitive), so this is an inert no-op server-side; an author `fn.watch(…)` surviving the
-       SSR effect-strip (which leaves member calls intact) is a safe no-op there. The real method
-       is attached client-side by remoteProxy. */
-    watch(handler: (value: Return) => void): () => void
-    watch(args: Args, handler: (value: Return) => void): () => void
-} /* `patch` is fetch-only: a streaming rpc has no single memoized value to mutate, so the
-     method is present only when `Return` is not an AsyncIterable. Two signatures: with args
-     (`patch(args, updater)`) and without (`patch(updater)` — every args-variant). Tuple-wrapped
-     so the conditional doesn't distribute over a `never` Return (an error-only rpc). */ & ([
-        Return,
-    ] extends [AsyncIterable<unknown>]
-        ? Record<never, never>
+} /* Client-only reaction sugar: `fn.watch(handler)` / `fn.watch(args, handler)` ≡ `watch(fn, …)`
+     — runs the smart read reactively and pipes each resolved value to the handler, returning a
+     scope-tied disposer. Inert no-op server-side (reaction is a ui concern; the real method is
+     attached client-side by remoteProxy). The keyed overload collapses away for a no-input rpc
+     (`undefined extends Args`) — there is no key to scope to (ADR-0043 §5, type-only). */ & (undefined extends Args
+        ? {
+              watch(handler: (value: Return) => void): () => void
+          }
         : {
-              patch(args: Args | undefined, updater: (current: Return) => Return): void
-              patch(updater: (current: Return) => Return): void
-          })
+              watch(handler: (value: Return) => void): () => void
+              watch(args: Args, handler: (value: Return) => void): () => void
+          }) /* `amend` is fetch-only: a streaming rpc has no single memoized value to mutate, so the
+     method is present only when `Return` is not an AsyncIterable. The last argument is a
+     replacement `Return` value (broadcastable — ADR-0043) or an updater `(current) => Return`
+     (a local closure). For a keyed rpc the value/updater takes the args key first; the bare
+     `amend(updater)` covers every args-variant (local-only). For a no-input rpc the key
+     collapses away (`amend(value)` / `amend(updater)`). Tuple-wrapped so the conditional
+     doesn't distribute over a `never` Return (an error-only rpc). */ &
+    ([Return] extends [AsyncIterable<unknown>]
+        ? Record<never, never>
+        : undefined extends Args
+          ? {
+                amend(value: Return): void
+                amend(updater: (current: Return) => Return): void
+            }
+          : {
+                amend(args: Args, value: Return): void
+                amend(args: Args, updater: (current: Return) => Return): void
+                amend(updater: (current: Return) => Return): void
+            })

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

@@ -0,0 +1,13 @@
+/*
+The per-request list of retained socket frames read via `peek(socket)` during an SSR render, each
+keyed by the socket's name. `defineSocket`'s server `peek()` pushes an entry when a retained frame is
+read server-side; the page renderer stamps them into `__SSR__.sockets` (ref-json-encoded, last write
+per name winning) so the client seeds the socket's latest frame WARM — a not-yet-connected client's
+`peek(socket)` then returns the same retained value the SSR render committed to instead of `undefined`,
+which would otherwise diverge from the server HTML and trip a hydration desync. Sibling of
+`ResolvedCells` — sockets carry a server value forward like cells, not withhold on the client like
+cache (whose server peek is uniformly undefined).
+*/
+export type SocketTails = {
+    entries: { name: string; value: unknown }[]
+}

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

@@ -27,4 +27,10 @@ export type SsrPayload = SsrBootState & {
        write to each slot adopts the server value, so a plain `state(uuid())`/`state(Date.now())`
        keeps the SSR value instead of recomputing a divergent one. */
     docs?: Record<string, string>
+    /* Retained socket frames read via `peek(socket)` during SSR, keyed by socket name → ref-json
+       string. `startClient` seeds these into `SOCKET_SEED`; a hydrating `socketProxy` adopts the frame
+       as its `lastFrame` so `peek(socket)` returns the SAME retained value the server rendered instead
+       of `undefined` on the not-yet-connected client — otherwise the two disagree and hydration
+       discards the server markup. */
+    sockets?: Record<string, string>
 }

package/src/lib/test/createTestApp.ts

@@ -47,6 +47,7 @@ import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
 import { resolvedCellsSlot } from '../shared/resolvedCellsSlot.ts'
 import { SOCKETS_PATH } from '../shared/SOCKETS_PATH.ts'
 import { sharedCacheStoreSlot } from '../shared/sharedCacheStoreSlot.ts'
+import { socketTailsSlot } from '../shared/socketTailsSlot.ts'
 import { streamedCellsSlot } from '../shared/streamedCellsSlot.ts'
 import type { RemoteFunction } from '../shared/types/RemoteFunction.ts'
 import type { Socket } from '../shared/types/Socket.ts'
@@ -111,6 +112,7 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsResolver: pendingAsyncCellsSlot.resolver,
         resolvedCellsResolver: resolvedCellsSlot.resolver,
         streamedCellsResolver: streamedCellsSlot.resolver,
+        socketTailsResolver: socketTailsSlot.resolver,
         docSnapshotsResolver: docSnapshotsSlot.resolver,
         activeServer: serverSlot.active,
         pageRender: pageRenderSlot.render,
@@ -129,6 +131,9 @@ export async function createTestApp(): Promise<TestApp> {
     const sharedStreamedCells = { entries: [] }
     streamedCellsSlot.resolver = () =>
         requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+    /* No shared fallback — mirrors serverEntry: `defineSocket.peek` records off-request too, so a
+       fallback would leak. Off-request this resolves undefined and the record is skipped. */
+    socketTailsSlot.resolver = () => requestContext.getStore()?.socketTails
     const sharedDocSnapshots = { entries: [] }
     docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
     pageSlot.resolver = resolvePageSnapshot
@@ -218,6 +223,7 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsSlot.resolver = previous.pendingAsyncCellsResolver
         resolvedCellsSlot.resolver = previous.resolvedCellsResolver
         streamedCellsSlot.resolver = previous.streamedCellsResolver
+        socketTailsSlot.resolver = previous.socketTailsResolver
         docSnapshotsSlot.resolver = previous.docSnapshotsResolver
         serverSlot.active = previous.activeServer
         pageRenderSlot.render = previous.pageRender

package/src/lib/ui/amendReaderHook.ts

@@ -0,0 +1,125 @@
+import { AMEND_TOPIC_PREFIX } from '../shared/AMEND_TOPIC_PREFIX.ts'
+import { abideLog } from '../shared/abideLog.ts'
+import { cache } from '../shared/cache.ts'
+import { SocketDisconnectedError } from '../shared/SocketDisconnectedError.ts'
+import type { CacheReaderHook } from '../shared/types/CacheReaderHook.ts'
+import type { Socket } from '../shared/types/Socket.ts'
+import { socketProxy } from './socketProxy.ts'
+
+/* A cache key is a broadcastable amend target only when it carries cross-client wire
+   identity — a remote call key (`METHOD /url…`, per keyForRemoteCall). Producer keys
+   (per-process reference ids) and anything else can't be pushed across clients, so we
+   never open a subscription for them. */
+const REMOTE_KEY = /^(?:GET|POST|PUT|PATCH|DELETE|HEAD) \//
+
+/*
+The client-only reactive-reader lifecycle hook (ADR-0043) installed into
+cacheReaderSocketSlot by startClient. When a remote key gains its first live reader it
+opens a subscription to that call's reserved amend topic and folds each pushed value
+into the cache; when the key loses its last reader it closes the subscription — so the
+set of subscribed topics stays congruent with the set of keys this tab is reading (and
+therefore already authorized for). Refcounted per key so co-readers (or the active/shared
+store both reporting a reader) share one subscription.
+
+The channel is live-only (no tail): a value pushed while this tab was disconnected is
+missed, so on a transport loss the hook re-opens a fresh live iterator AND refreshes the
+key — the ADR-0043 convergence rule, reconciling against authoritative server state
+rather than leaving a silently-stale value. `openSocket` is injectable so a test can drive
+frames over its own channel without a live ws.
+*/
+export function createAmendReaderHook(
+    openSocket: (name: string) => Socket<unknown> = socketProxy,
+): { hook: CacheReaderHook; dispose: () => void } {
+    const open = new Map<string, { readers: number; dispose: () => void }>()
+
+    function subscribe(key: string): () => void {
+        const socket = openSocket(AMEND_TOPIC_PREFIX + key)
+        const controller = new AbortController()
+        /* Opening the shared ws channel must never propagate into the cache read that engaged
+           this key — a read can't fail because an optional real-time subscription couldn't open
+           (e.g. no ws transport). Log and give up on this key's push channel; SWR still holds. */
+        let iterator: AsyncIterator<unknown>
+        try {
+            iterator = socket[Symbol.asyncIterator]()
+        } catch (error) {
+            abideLog.error(error)
+            return () => undefined
+        }
+        ;(async () => {
+            while (!controller.signal.aborted) {
+                let next: IteratorResult<unknown>
+                try {
+                    next = await iterator.next()
+                } catch (error) {
+                    if (controller.signal.aborted) {
+                        return
+                    }
+                    /* Transport loss: reconcile the possibly-missed value against server truth,
+                       then re-open a fresh LIVE subscription (no replay) and keep going. */
+                    if (error instanceof SocketDisconnectedError) {
+                        cache.refreshMatching((entry) => entry.key === key, key, undefined)
+                        try {
+                            iterator = socket[Symbol.asyncIterator]()
+                        } catch (reopenError) {
+                            abideLog.error(reopenError)
+                            return
+                        }
+                        continue
+                    }
+                    abideLog.error(error)
+                    return
+                }
+                if (controller.signal.aborted || next.done === true) {
+                    return
+                }
+                /* One malformed frame must not tear down the live pipe. Frames come only from the
+                   trusted server (clientPublish is false), so this is defense in depth. */
+                try {
+                    cache.amendByKey(key, next.value)
+                } catch (error) {
+                    abideLog.error(error)
+                }
+            }
+        })()
+        return () => {
+            controller.abort()
+            iterator.return?.(undefined)?.catch(() => undefined)
+        }
+    }
+
+    const hook: CacheReaderHook = {
+        engage(key) {
+            if (!REMOTE_KEY.test(key)) {
+                return
+            }
+            const existing = open.get(key)
+            if (existing) {
+                existing.readers += 1
+                return
+            }
+            open.set(key, { readers: 1, dispose: subscribe(key) })
+        },
+        disengage(key) {
+            const existing = open.get(key)
+            if (existing === undefined) {
+                return
+            }
+            existing.readers -= 1
+            if (existing.readers <= 0) {
+                existing.dispose()
+                open.delete(key)
+            }
+        },
+    }
+
+    /* Tear down every open subscription — for the startClient disposer, in case reads are
+       still mounted when the whole client is torn down (e.g. a test harness). */
+    function dispose(): void {
+        for (const entry of open.values()) {
+            entry.dispose()
+        }
+        open.clear()
+    }
+
+    return { hook, dispose }
+}

package/src/lib/ui/compile/UI_RUNTIME_IMPORTS.ts

@@ -56,6 +56,7 @@ export const UI_RUNTIME_IMPORTS: { name: string; specifier: string; alias?: stri
     { name: 'spreadAttrs', specifier: 'ui/dom/spreadAttrs', alias: '$$spreadAttrs' },
     { name: 'readCall', specifier: 'ui/dom/readCall', alias: '$$readCall' },
     { name: 'readCell', specifier: 'ui/dom/readCell', alias: '$$readCell' },
+    { name: 'readCellBlocking', specifier: 'ui/dom/readCellBlocking', alias: '$$readCellBlocking' },
     { name: 'writeCell', specifier: 'ui/dom/writeCell', alias: '$$writeCell' },
     { name: 'cellPending', specifier: 'ui/dom/cellPending', alias: '$$cellPending' },
     { name: 'withPath', specifier: 'ui/runtime/withPath', alias: '$$withPath' },

package/src/lib/ui/compile/analyzeComponent.ts

@@ -120,6 +120,7 @@ export function analyzeComponent(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingCellNames,
         droppedReactiveImports,
     } = lowerScript(
         fullScriptBody,
@@ -142,6 +143,7 @@ export function analyzeComponent(
         derivedNames,
         computedNames,
         cellReadNames,
+        blockingCellNames: allBlockingCellNames,
         nodes,
         styles,
         /* Hydration adopts every block in place — including `await`, which resumes

package/src/lib/ui/compile/cachedShadowProgram.ts

@@ -0,0 +1,38 @@
+import { createShadowProgram, type ShadowProgram } from './createShadowProgram.ts'
+
+/*
+Get-or-build the warm shadow program for a project root, cached once per root and shared by
+the interpolation and seed classifiers (whichever is requested first for a root warms it; the
+other reuses it). The shadow program is what makes type-directed async detection possible —
+resolving whether `{getFoo()}` is a promise/stream and lifting it to a streaming/blocking cell.
+
+On a build FAILURE the program is cached as `undefined` and the classifiers degrade to today's
+plain-value / syntactic behavior — the build never breaks. But the failure is WARNED once per
+root: a silent `undefined` disables type-directed async detection for EVERY component in the
+root, so a broken tsconfig would otherwise ship a bare `{getFoo()}` as the literal
+`[object Promise]` text with no signal at all. The warn fires once (guarded by `cache.has`), so
+the two classifiers sharing a cache never double-report.
+
+`build` is injectable so the warn-once path is testable without a broken project on disk;
+callers pass nothing and get `createShadowProgram`.
+*/
+export function cachedShadowProgram(
+    cache: Map<string, ShadowProgram | undefined>,
+    root: string,
+    build: (root: string) => ShadowProgram = createShadowProgram,
+): ShadowProgram | undefined {
+    if (!cache.has(root)) {
+        try {
+            cache.set(root, build(root))
+        } catch (error) {
+            cache.set(root, undefined)
+            const detail = error instanceof Error ? error.message : String(error)
+            console.warn(
+                `[abide] couldn't build the type program for ${root}: ${detail}\n` +
+                    '  type-directed async detection is disabled for this project — a bare promise/stream\n' +
+                    '  read like {getFoo()} renders as text instead of streaming. Check the tsconfig.',
+            )
+        }
+    }
+    return cache.get(root)
+}

package/src/lib/ui/compile/compileComponent.ts

@@ -29,7 +29,15 @@ export function compileComponent(
        a direct caller (tests) omits it and the front-end runs here — threading `classify` and
        `seedClassify` so type-directed interpolation + cell lowering happen on this path too. */
     const resolved = analyzed ?? analyzeComponent(source, scopeSeed, classify, seedClassify)
-    const { script, stateNames, derivedNames, computedNames, cellReadNames, nodes } = resolved
+    const {
+        script,
+        stateNames,
+        derivedNames,
+        computedNames,
+        cellReadNames,
+        blockingCellNames,
+        nodes,
+    } = resolved
     const build = generateBuild(
         nodes,
         'host',
@@ -38,6 +46,7 @@ export function compileComponent(
         computedNames,
         isLayout,
         cellReadNames,
+        blockingCellNames,
     )
     /* The scoped CSS is bundled into the entry stylesheet (see `abideUiPlugin`), not
        injected at runtime; the build only needs the `data-a-…` scope attributes on

package/src/lib/ui/compile/compileSSR.ts

@@ -66,6 +66,18 @@ export function compileSSR(
         flightDecls,
         hasStagedChildren,
     } = generateSSR(nodes, stateNames, derivedNames, computedNames, isLayout, cellReadNames)
+    /* ADR-0042 D7 (barrier completeness): every async cell — and so every BLOCKING (`await`) cell —
+       is declared in the lowered script (`lowered`), which the body below emits BEFORE the
+       `$$settleAsyncCells` barrier; the template back-end (`ssr`) constructs no cells. A blocking
+       cell built AFTER its barrier would ship an unresolved value the client then SUSPENDS against,
+       desyncing hydration. The invariant holds by construction today (cells are a script-block
+       construct); assert it as a tripwire so a future template lowering that emits a cell
+       construction fails the build LOUDLY here instead of as a runtime hydration desync. */
+    if (/\$\$scope\(\)\.(trackedComputed|computed|linked)\(/.test(ssr)) {
+        throw new Error(
+            '[abide] a reactive cell is constructed in template output, after the async-cell barrier (ADR-0042 D7) — cells must be declared in the component script so they settle before the SSR flush.',
+        )
+    }
     /* ADR-0039: a component with hoistable children declares `$childSlots` (the body walk reserves an
        output slot per child) and, after the walk, awaits `$$finalizeStreamedChildren` — which fills
        each slot inline (settled child, byte-identical to the old inline await) or with a streaming