@abide/abide 0.46.0 → 0.47.0

package/src/lib/shared/selectorPrefix.ts

@@ -1,5 +1,5 @@
-import { CACHE_WRAPPED } from './CACHE_WRAPPED.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
 import { producerKey } from './producerKey.ts'
 import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
 import type { CacheSelector } from './types/CacheSelector.ts'
@@ -13,9 +13,7 @@ one call instead — derived through the same encoders the read path uses
 (keyForRemoteCall / producerKey format), so selector and entry can't
 disagree. Undefined when no prefix exists — bare and tag selectors (they
 scan, not prefix-match) and producers never cached (no id was minted;
-minting one here would leak identities for probe-only reads). The
-cache()-wrapper throw lives here so both consumers — the matcher and the
-probes' channel tap — reject it before subscribing to anything.
+minting one here would leak identities for probe-only reads).
 */
 export function selectorPrefix<Args, Return>(
     arg: CacheSelector<Args, Return> | undefined,
@@ -24,15 +22,10 @@ export function selectorPrefix<Args, Return>(
     if (typeof arg !== 'function') {
         return undefined
     }
-    if (CACHE_WRAPPED in arg) {
-        throw new Error(
-            '[abide] a cache() wrapper is not a selector — pass the function it wraps, e.g. pending(getPost), not pending(cache(getPost))',
-        )
-    }
     const remote = REMOTE_FUNCTION in arg ? (arg as RawRemoteFunction<Args>) : undefined
     if (remote) {
         return args === undefined
-            ? `${remote.method} ${remote.url}`
+            ? keyPrefixForRemote(remote.method, remote.url)
             : keyForRemoteCall(remote.method, remote.url, args)
     }
     return producerKey.existing(arg, args)

package/src/lib/shared/setOwnProperty.ts

@@ -0,0 +1,19 @@
+/*
+Assignment can't create an own `__proto__` key — it invokes the
+Object.prototype accessor instead, silently dropping the key or (on decode of
+attacker-controlled wire data) swapping the object's prototype. defineProperty
+always writes an own enumerable data property, so `__proto__` round-trips as a
+plain key. Plain assignment stays on the fast path for every other key.
+*/
+export function setOwnProperty(target: Record<string, unknown>, key: string, value: unknown): void {
+    if (key === '__proto__') {
+        Object.defineProperty(target, key, {
+            value,
+            writable: true,
+            enumerable: true,
+            configurable: true,
+        })
+        return
+    }
+    target[key] = value
+}

package/src/lib/shared/snippet.ts

@@ -1,6 +1,6 @@
 const SNIPPET = Symbol.for('abide.snippet')
 
-/* A `<template name args>` snippet, called like a function: it carries a payload a
+/* A `{#snippet name(args)}` snippet, called like a function: it carries a payload a
    `{expr}` interpolation mounts in place — a DOM builder `(host) => void` on the
    client, the pre-rendered HTML string on the server. The brand is a registered
    Symbol so it survives across module/bundle copies (same idiom as `html\`\``). */

package/src/lib/shared/subscribableProbes.ts

@@ -0,0 +1,111 @@
+import { createLifecycleChannel } from './createLifecycleChannel.ts'
+import { tailProbeSlot } from './tailProbeSlot.ts'
+
+type StreamStatus = 'pending' | 'open' | 'done' | 'error'
+
+/* One registered consumption of a named subscribable — the stream-side analog of a
+   cache-store entry. Populated by the consume path (cache.on / watch(socket)), read
+   by the pending()/refreshing()/done()/error() probes. No window/value here: the
+   value flows through the consumer (watch handler / for-await), the registry only
+   holds probe state. */
+type StreamEntry = {
+    source: string
+    status: StreamStatus
+    refreshing: boolean
+    error: Error | undefined
+    /* Reconnect only counts as refreshing once a value has been seen (probe contract:
+       value held, fresher source in flight — never a first-ever open). */
+    everFramed: boolean
+}
+
+const registry = new Set<StreamEntry>()
+
+/*
+Registry-wide lifecycle channel for the subscribable probes — the stream-side
+counterpart of the cache store's. Probes match entries by source name (or all)
+without creating them, so they tap one "membership or state changed" signal and
+re-derive by scanning.
+*/
+const lifecycle = createLifecycleChannel()
+
+/*
+Installs the prober the shared probes call for a Subscribable (probeRegistries →
+tailProbeSlot). Register-on-consume: an entry exists only while something is
+consuming the stream, exactly as a cache entry exists only while a call is
+retained. A name with no entry reads as "no value yet" (pending) without opening
+anything — probes report, never act. This install replaces tail()'s: the registrar
+moved from the (removed) tail() reader to the consume path.
+*/
+tailProbeSlot.probe = (name) => {
+    lifecycle.track()
+    const entries = [...registry].filter((entry) => name === undefined || entry.source === name)
+    return {
+        pending:
+            (name !== undefined && entries.length === 0) ||
+            entries.some((entry) => entry.status === 'pending'),
+        refreshing: entries.some((entry) => entry.refreshing),
+        /* Terminal only when there is at least one entry and all of them have closed. */
+        done: entries.length > 0 && entries.every((entry) => entry.status === 'done'),
+        error: entries.find((entry) => entry.error !== undefined)?.error,
+    }
+}
+
+export type StreamProbe = {
+    frame(): void
+    reconnecting(): void
+    done(): void
+    errored(error: Error): void
+    close(): void
+}
+
+/*
+Opens a probe entry for a consumed named subscribable and returns the handle the
+consume loop drives: `frame()` on each delivered value (pending → open), plus the
+terminal/lifecycle transitions. `close()` evicts on teardown. Reactivity is the
+registry lifecycle channel, marked on every transition.
+*/
+export function openStreamProbe(source: string): StreamProbe {
+    const entry: StreamEntry = {
+        source,
+        status: 'pending',
+        refreshing: false,
+        error: undefined,
+        everFramed: false,
+    }
+    registry.add(entry)
+    lifecycle.mark()
+    return {
+        frame() {
+            /* Only ping on a real transition (pending→open, or refreshing clearing) so a
+               chatty stream doesn't re-derive every bare probe reader on each value. */
+            const transitioned = entry.status !== 'open' || entry.refreshing
+            entry.status = 'open'
+            entry.refreshing = false
+            entry.everFramed = true
+            if (transitioned) {
+                lifecycle.mark()
+            }
+        },
+        reconnecting() {
+            entry.refreshing = entry.everFramed
+            lifecycle.mark()
+        },
+        done() {
+            if (entry.status !== 'error') {
+                entry.status = 'done'
+            }
+            entry.refreshing = false
+            lifecycle.mark()
+        },
+        errored(error: Error) {
+            entry.error = error
+            entry.status = 'error'
+            entry.refreshing = false
+            lifecycle.mark()
+        },
+        close() {
+            registry.delete(entry)
+            lifecycle.mark()
+        },
+    }
+}

package/src/lib/shared/tailProbeSlot.ts

@@ -10,7 +10,14 @@ itself gives on the server: a named stream has no value yet (pending true),
 and nothing is reconnecting (refreshing false).
 */
 export const tailProbeSlot: {
-    probe: ((name?: string) => { pending: boolean; refreshing: boolean }) | undefined
+    probe:
+        | ((name?: string) => {
+              pending: boolean
+              refreshing: boolean
+              done: boolean
+              error: Error | undefined
+          })
+        | undefined
 } = {
     probe: undefined,
 }

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

@@ -59,26 +59,20 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
-    /*
-    Lazy warm materializer (Tier 2 deferred seed): a memoized thunk that decodes the
-    shipped body into the warm value on first call, so a deferred snapshot pays no decode
-    at hydration — only when a read actually needs the value. `value` stays undefined until
-    then; the read gate treats an entry with `warm` set as warm without invoking it. Eager
-    snapshots set `value` and leave this undefined.
-    */
-    warm?: () => unknown
     tags?: Set<string>
     settled?: boolean
     hydrated?: boolean
-    /*
-    Marks that the SSR resume path deferred this entry's `{#await cache()}` value — shipped a
-    `{ defer, key }` marker instead of inlining it. The post-stream snapshot drain reads it to
-    ship the body as a LAZY seed (decoded on first read, not at hydration). Set server-side
-    only, on the request-scoped entry, during the stream.
-    */
-    deferred?: boolean
     refreshing?: boolean
     invalidation?: InvalidationState
+    /*
+    Set by the smart bare call (a replayable read routed through cache.read): the
+    display value is retained unconditionally and `ttl` marks a staleness deadline
+    (the next read past it revalidates in the background, stale stays visible) rather
+    than driving the hard eviction an explicit cache() ttl triggers. Distinguishes the
+    smart-read lifecycle from the explicit cache()/invalidate old surface, which keeps
+    its drop-on-ttl / drop-on-invalidate behaviour.
+    */
+    retain?: boolean
 }
 
 /* Per-key invalidate coalescing: the throttle/debounce policy plus the timer/in-flight state. */

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

@@ -34,10 +34,18 @@ cache() throws at wrap time on throttle+debounce set at once, on ttl: 0 (nothing
 retained, nothing to revalidate), and on a non-replayable remote method
 (replaying a write is a state change disguised as a refresh). Producers are
 uncheckable — set `swr` only on a producer that is a pure read.
+
+`throttle`/`debounce` are root rate-limit windows for the refetch clock. For the
+smart bare call — where SWR is unconditional for replayable reads, so there is no
+`swr` toggle to hang a window off — they cap how often a background revalidation
+fires (leading-edge-then-coalesce, or fire-after-quiet respectively). They pair
+with the same wrap-time guard as the `swr` window: set one, not both.
 */
 export type CacheOptions = {
     ttl?: number
     tags?: string[]
     global?: boolean
     swr?: boolean | { throttle?: number; debounce?: number }
+    throttle?: number
+    debounce?: number
 }

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

@@ -14,9 +14,4 @@ export type CacheSnapshotEntry = {
     statusText: string
     headers: Array<[string, string]>
     body: string
-    /* Deferred seed (Tier 2): the client stores the body but does NOT decode it at boot —
-       the warm value is materialized lazily on the first read, off the hydration path. Set
-       by the server for a deferred `{#await cache()}` whose value ships via a `{defer,key}`
-       resume marker instead of inline, so hydration touches neither copy's decode. */
-    lazy?: boolean
 }

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

@@ -1,4 +1,5 @@
 import type { RpcOptions } from './RpcOptions.ts'
+import type { Subscribable } from './Subscribable.ts'
 
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
@@ -8,14 +9,31 @@ optional-arg signature lets call sites write `fn()` instead of
 `fn(undefined)`. Intersection rather than a bare conditional so the type
 stays callable while `Args` is still generic (cache() invokes producers
 before `Args` resolves). FormData is the multipart upload escape hatch —
-see RemoteFunction. The optional trailing `opts` carries per-call transport
-options (signal/keepalive/priority/cache/headers); the server ignores them,
-so the callable stays isomorphic.
+see RemoteFunction. The trailing `Opts` differs by variant: the smart bare
+call (RemoteFunction) carries cache/stream options (SmartReadOptions), while
+`.raw` (RawRemoteFunction) carries per-call transport options (RpcOptions:
+signal/keepalive/priority/cache/headers). The server ignores either, so the
+callable stays isomorphic.
+
+A streaming `Resolved` (an `AsyncIterable<Frame>`, branded by jsonl()/sse()) makes
+the bare call return a `Subscribable<Frame>` synchronously — the iterable IS the
+value, consumed by `for await` or `state(fn(args))`, no `.stream()`. Every other
+`Resolved` stays `Promise<Resolved>`. `await`-ing a streaming call is a compile
+error (a Subscribable is not awaitable), which replaces the old runtime guard.
 */
-export type RemoteCallable<Args, Resolved> = ((
+/* `[Resolved] extends [never]` first: a handler that only ever returns error() resolves to
+   `never`, and `never extends AsyncIterable` is vacuously true — without this guard its call
+   would mistype as a Subscribable. A real streaming rpc's `Resolved` is `AsyncIterable<Frame>`. */
+type CallResult<Resolved> = [Resolved] extends [never]
+    ? Promise<Resolved>
+    : Resolved extends AsyncIterable<infer Frame>
+      ? Subscribable<Frame>
+      : Promise<Resolved>
+
+export type RemoteCallable<Args, Resolved, Opts = RpcOptions> = ((
     args: Args | FormData,
-    opts?: RpcOptions,
-) => Promise<Resolved>) &
+    opts?: Opts,
+) => CallResult<Resolved>) &
     (undefined extends Args
-        ? (args?: Args | FormData, opts?: RpcOptions) => Promise<Resolved>
+        ? (args?: Args | FormData, opts?: Opts) => CallResult<Resolved>
         : unknown)

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

@@ -4,8 +4,9 @@ import type { HttpMethod } from './HttpMethod.ts'
 import type { Outbox } from './Outbox.ts'
 import type { RawRemoteFunction } from './RawRemoteFunction.ts'
 import type { RemoteCallable } from './RemoteCallable.ts'
+import type { RpcError } from './RpcError.ts'
 import type { RpcErrorGuard } from './RpcErrorGuard.ts'
-import type { Subscribable } from './Subscribable.ts'
+import type { SmartReadOptions } from './SmartReadOptions.ts'
 
 /*
 Remote function reference produced by GET/POST/... inside an `$rpc/**`
@@ -19,12 +20,12 @@ RemoteFunction whose call resolves to the underlying Response — same
 method, same url, same args, no decode. Pass `fn.raw` to cache() to
 memoise raw Responses against the same cache key as `fn` (both share one
 stored entry — the decode just happens on the way out for callers of
-`fn`). `.stream(args)` returns an iterable view of the Response body:
-SSE / JSONL handlers yield each frame; non-streaming handlers yield the
-decoded body once then complete. The result is a Subscribable, so it
-can be passed to tail() and shared across reactive consumers.
-For sustained broadcast / pub-sub use the `abide/server/socket` primitive —
-HTTP rpc isn't the place for long-lived multi-publisher subscriptions.
+`fn`). A streaming handler (jsonl()/sse()) makes the bare call return a
+`Subscribable<Frame>` directly (the iterable IS the value) — consume it with
+`for await (… of fn(args))` or `state(fn(args))`; there is no `.stream()`, and
+`await`-ing a streaming call is a compile error. For sustained broadcast /
+pub-sub use the `abide/server/socket` primitive — HTTP rpc isn't the place for
+long-lived multi-publisher subscriptions.
 `.fetch(req)` is the framework's request-dispatch entry point — used by
 the router to invoke the handler from an incoming HTTP request, not
 for user code.
@@ -44,23 +45,57 @@ export type RemoteFunction<
     Return,
     Errors extends ErrorSpec = Record<never, never>,
     Durable extends boolean = false,
-> = RemoteCallable<Args, Return> & {
+> = RemoteCallable<Args, Return, SmartReadOptions> & {
     readonly method: HttpMethod
     readonly url: string
     readonly clients: ClientFlags
     readonly crossOrigin?: boolean
     readonly raw: RawRemoteFunction<Args>
-    stream(args?: Args | FormData): Subscribable<Return>
     fetch(request: Request): Promise<Response>
     /* Type-guard a caught error against this rpc's declared `errors` (plus the framework
        `'validation'` / `'queued'`): narrows `.kind` and, for a known kind, `.data` — the
        per-rpc replacement for a global guard, since the error name → data type mapping
        lives in the rpc's own spec. */
     readonly isError: RpcErrorGuard<Errors>
-} /* `outbox` presence follows the `outbox: true` opt: the mutating helper threads `Durable`
+    /* Pre-bound selector sugar: `fn.pending(args?)` ≡ `pending(fn, args?)`, and likewise for
+       refreshing / refresh / peek — the rpc is the leading selector, bound in. The argument is
+       this rpc's typed `Args` (the by-args refinement); tags / cross-cutting selection stay on
+       the globals. The bare call `fn(args, opts)` IS the cached read (was `fn.cache`), and
+       `refresh(args?)` refetches keeping the stale value visible (was `invalidate`, which
+       dropped). `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 memoized value) via the intersection below. */
+    pending(args?: Args): boolean
+    refreshing(args?: Args): boolean
+    refresh(args?: Args): void
+    peek(args?: Args): ([Return] extends [AsyncIterable<infer Frame>] ? Frame : Return) | undefined
+    /* This rpc's last error, typed off `Errors` (a discriminated union already narrowed on
+       `.kind`/`.data`). `args` scopes to one call; omitted aggregates the most-recent across
+       this rpc. Truthiness is the "isError" check. Instance-only — no bare global (it would
+       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>
+        : {
+              patch(args: Args | undefined, updater: (current: Return) => Return): void
+              patch(updater: (current: Return) => Return): void
+          }) /* `outbox` presence follows the `outbox: true` opt: the mutating helper threads `Durable`
      into the return type so a DURABLE rpc's `.outbox` is the required queue face (no optional
      chain). A non-durable rpc keeps it optional — assignable to a durable one everywhere a
      bare `RemoteFunction<Args, Return>` slot (cache selectors, registries) is expected, since
-     required→optional widens cleanly and no call site had to learn the `Durable` bit. */ & (Durable extends true
-        ? { readonly outbox: Outbox<Args> }
-        : { readonly outbox?: Outbox<Args> })
+     required→optional widens cleanly and no call site had to learn the `Durable` bit. */ &
+    (Durable extends true ? { readonly outbox: Outbox<Args> } : { readonly outbox?: Outbox<Args> })

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

@@ -1,10 +1,13 @@
 /*
-The mutable cell a runtime entry registers its resolver into, plus the single
-lazy/value fallback used when no resolver is registered. createServer and
-startClient install side-specific resolvers; isolated tests poke `.resolver` /
-`.fallback` directly, so both fields stay public and mutable.
+One resolved runtime value's whole seam: the mutable cell a runtime entry
+registers its resolver into, the single lazy/value fallback used when no
+resolver is registered, and the read. createServer and startClient install
+side-specific resolvers by assigning `.resolver`; isolated tests poke
+`.resolver` / `.fallback` directly, so both fields stay public and mutable.
 */
 export type ResolverSlot<T> = {
     resolver: (() => T | undefined) | undefined
     fallback: T | undefined
+    // The resolved value: the registered resolver's, else the (lazy) fallback.
+    get(): T | undefined
 }

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

@@ -0,0 +1,26 @@
+import type { HttpError } from '../HttpError.ts'
+import type { ErrorSpec } from './ErrorSpec.ts'
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+
+/* Payload a declared error name carries: its data schema's inferred input, or `unknown`
+   for a nullary error (no data schema) — mirrors RpcErrorGuard's DeclaredErrorData. */
+type DeclaredData<
+    Errors extends ErrorSpec,
+    Name extends keyof Errors,
+> = Errors[Name]['data'] extends StandardSchemaV1
+    ? StandardSchemaV1.InferInput<Errors[Name]['data']>
+    : unknown
+
+/*
+The typed error value `fn.error()` returns: the discriminated union of this rpc's declared
+errors (name → data), each an HttpError narrowed on `.kind` / `.data`. The read-side mirror
+of RpcErrorGuard's narrowing, as a value rather than a guard — so `getUser.error()?.name`
+is already narrowed with no guard call. `never` (collapses to `undefined`-only at the call
+site) for an rpc that declares no errors.
+*/
+export type RpcError<Errors extends ErrorSpec> = {
+    [Name in keyof Errors & string]: HttpError & {
+        kind: Name
+        data: DeclaredData<Errors, Name>
+    }
+}[keyof Errors & string]

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

@@ -0,0 +1,32 @@
+/*
+Second-argument options for the smart bare rpc call (`getFoo(args, opts)`). The
+call is cached/coalesced/reactive with SWR always on for replayable reads, so
+these govern retention and the refetch clock — NOT transport. Per-call transport
+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.
+- `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.
+
+Streaming reads (jsonl/sse):
+- `n` — how many retained frames to replay before going live.
+*/
+export type SmartReadOptions = {
+    ttl?: number
+    tags?: string[]
+    throttle?: number
+    debounce?: number
+    global?: boolean
+    n?: number
+}

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

@@ -0,0 +1,54 @@
+import type { CacheOnContext } from './CacheOnContext.ts'
+import type { ClientFlags } from './ClientFlags.ts'
+import type { TailHooks } from './TailHooks.ts'
+
+/*
+Bidirectional named broadcast primitive. Declared once with `socket<T>()`
+inside a file under `src/server/sockets/`; the same import resolves to a server-side
+fan-out and a client-side ws proxy by build target. Iterating the socket
+is the live stream — no replay. `.tail(count)` opens a subscription seeded
+with the last `count` frames of the retained tail (declared via
+`{ tail: n }`; no-arg = the whole retained tail) before going live — the
+optional Subscribable retention capability a reactive `watch(socket, …)`
+seeds from. `broadcast` is isomorphic: server code broadcasts in-process
+and fans out to remote subscribers; client code sends a `pub` frame the
+dispatcher validates against the topic's `clientPublish` flag. `clients`
+exposes which adapter surfaces (browser / mcp / cli) advertise this
+socket.
+*/
+export interface Socket<T> extends AsyncIterable<T> {
+    readonly name: string
+    readonly clients: ClientFlags
+    /* Send a frame to every subscriber (server always; client only when `clientPublish` is
+       set). Isomorphic: server code fans out in-process + to remote subscribers; client code
+       sends a validated `pub` frame. */
+    broadcast(message: T): void
+    tail(count?: number, hooks?: TailHooks): AsyncIterable<T>
+    /* The latest retained frame, synchronously — `T | undefined` when none. The value
+       member of the probe family for a stream; `peek(socket)` routes here. */
+    peek(): T | undefined
+    /* Reactive probe sugar mirroring the rpc instance — the socket is the pre-bound stream
+       selector: `socket.pending()` ≡ `pending(socket)` (no frame yet), `socket.refreshing()` ≡
+       `refreshing(socket)` (a held frame revalidating, e.g. across a reconnect gap),
+       `socket.done()` ≡ `done(socket)` (the stream closed). Client-reactive; on the server (and
+       the raw test builder) they read the same fallbacks the globals give with no tail prober
+       registered (pending true until a frame, refreshing/done false). */
+    pending(): boolean
+    refreshing(): boolean
+    done(): boolean
+    /* The stream's terminal error, or undefined. Instance-only — like the rpc's `.error`, since a
+       bare `error` global would shadow the server `error()` thrower. Reactive off the tail prober's
+       error field; undefined on the server. */
+    error(): Error | undefined
+    /* Drop local frames and re-pull the server's retained tail — the socket analog of
+       getFoo.refresh(), for a ttl-expired frame or a reconnect resync. Server-side it is a
+       no-op (the server IS the source). */
+    refresh(): void
+    /* Client-only reaction sugar: `socket.watch(handler)` ≡ `watch(socket, handler)` — the
+       handler runs per delivered frame with reconnect-replay and returns a scope-tied disposer.
+       Reaction is a client concern (`watch` is a ui primitive that never rides into a server
+       bundle), so server-side — and in the raw test builder — this is an inert no-op like
+       `.refresh`; the SSR effect-strip leaves member calls intact, so an author `socket.watch(…)`
+       reaching the server is a safe no-op. The real method is attached client-side by socketProxy. */
+    watch(handler: (frame: T, context: CacheOnContext) => void | Promise<void>): () => void
+}

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

@@ -0,0 +1,27 @@
+/*
+The subset of the `__SSR__` payload the client seeds into ambient slots at boot: the
+mount base, the default log channel (app name), the warm health payload, and the
+env-configured RPC client timeout. Every field here is stamped by the server's SSR
+state tag and MUST be seeded client-side by `seedBootState`, whose seed map is keyed
+EXHAUSTIVELY off this type — so a field added here fails to compile until both sides
+wire it. That compile error is the guard closing the silent stamped-but-unseeded gap
+(the bug that left `ABIDE_CLIENT_TIMEOUT` inoperative in the browser while every test
+still passed).
+*/
+export type SsrBootState = {
+    /* The mount base (`base || undefined`); seeds the base resolver so call keys and
+       navigation resolve rooted paths. Seeded first — the cache seed that follows keys
+       through it. */
+    base?: string
+    /* The app name — the default log channel; falls back to `'app'` when absent. */
+    app?: string
+    /* The health payload, so `health()`'s first client probe is warm rather than cold. */
+    health?: Record<string, unknown>
+    /* The env-configured RPC client timeout (`ABIDE_CLIENT_TIMEOUT`), shipped per request;
+       absent → unbounded client fetches. */
+    clientTimeout?: number
+    /* The SSR request's W3C traceparent; seeds the browser request scope so trace(), log
+       prefixes, and RPC traceparent headers continue the document's trace. Absent → a
+       fresh sampled trace is minted at boot. */
+    trace?: string
+}

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

@@ -0,0 +1,21 @@
+import type { CacheSnapshotEntry } from './CacheSnapshotEntry.ts'
+import type { SsrBootState } from './SsrBootState.ts'
+
+/*
+The `window.__SSR__` payload: the single contract between the server's SSR state tag
+(`createUiPageRenderer.stateTag`) and the client entry (`startClient`). Both sides
+import THIS type — the server stamps its object with `satisfies SsrPayload` (an unknown
+or mis-typed field is a compile error) and the client reads through it — so the
+write-set and read-set can't drift apart on a matching-string-key handshake.
+
+Three partitions:
+  - `SsrBootState` fields seed ambient slots via the exhaustive `seedBootState` map;
+  - `cache` is the inline warm-seed partition, drained through `seedResolved`;
+  - `route`/`params` are stamped for inspectability and are NOT read by the client
+    (the router re-resolves the route from the URL).
+*/
+export type SsrPayload = SsrBootState & {
+    route: string
+    params: Record<string, string>
+    cache?: CacheSnapshotEntry[]
+}

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

@@ -1,24 +1,24 @@
 import type { TailHooks } from './TailHooks.ts'
 
 /*
-The thing `tail()` reads from: an AsyncIterable carrying a stable `name`
-used as the subscription registry key. Both `Socket<T>` (the declared
-broadcast primitive) and the result of `fn.stream(args)` (per-call HTTP
-stream consumer) satisfy this shape, so tail() can share one iterator
-across multiple readers regardless of source.
+A named async stream: an AsyncIterable carrying a stable `name` used as the
+subscription registry key. Both `Socket<T>` (the declared broadcast
+primitive) and a streaming rpc's bare call (a `jsonl`/`sse` handler makes
+the call return the stream itself) satisfy this shape, so the consume path
+(`watch` → `cache.on`) and the stream probes (`pending`/`refreshing`/
+`done`/`error`) handle either source through one contract.
 
 The name on a Socket comes from the file path under `src/server/sockets/`.
-The name on an fn.stream(args) result is `keyForRemoteCall(method, url,
-args)` — the same key cache() uses — so two readers of the same remote-call
-args dedupe to one underlying fetch.
+The name on a streaming rpc call is `keyForRemoteCall(method, url, args)` —
+the same key the smart call's cache store uses — so two readers of the same
+remote-call args dedupe to one underlying fetch.
 
 `tail` is the optional retention capability: a source that keeps a tail of
 recent frames hands back an iterable seeded with at most the last `count`
-before going live. Sockets implement it verbatim; one-shot rpc streams omit
-it. The tail() consumer uses it to bound replay to what the reader will
-keep — it never requires it. Implementers must signal `hooks.replayed`
-in-band once the seed portion is delivered (even when empty) so window
-readers can commit atomically; see TailHooks.
+before going live. Sockets implement it verbatim (it also backs the socket's
+HTTP/SSE read face); one-shot rpc streams omit it. Implementers must signal
+`hooks.replayed` in-band once the seed portion is delivered (even when
+empty) so a seeded reader can commit its window atomically; see TailHooks.
 */
 export interface Subscribable<T> extends AsyncIterable<T> {
     readonly name: string

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

@@ -1,5 +1,6 @@
 /*
-Hooks a tail() reader passes to a Subscribable's retention capability.
+Hooks a `tail(count, hooks)` caller passes to a Subscribable's retention
+capability.
 `replayed` must be signalled in-band exactly once per iteration — after the
 last replayed frame, before any live frame, and even when nothing was
 replayed — so a window reader can commit its seed atomically instead of