@abide/abide 0.49.0 → 0.50.0

package/src/lib/shared/reviveWireOutput.ts

@@ -0,0 +1,36 @@
+import { reviveWireField } from './reviveWireField.ts'
+import type { OutputWirePlan } from './types/OutputWirePlan.ts'
+
+/*
+The type-directed wire DECODE step for a rpc success response (ADR-0029 output path) — the
+response-side sibling of parseArgs' input revival. The server encoded a handler's structured
+return into honest JSON (`wireJsonReplacer`): a `Set` → array, a `Map` → `[K,V]` entries, a
+`bigint` → digit string, a `Date` → ISO string. A wire array is ambiguous (a real `T[]` vs an
+encoded `Set<T>`), so the abide client revives from the DECLARED kind the warm server program baked
+onto the stub (`OutputWirePlan`), applied to a DECODED response body here. Only the fields named in
+the plan are touched; a genuine array / scalar the plan omits is left as-is.
+
+Mutates the decoded body in place — the value is call-private (a fresh JSON.parse result or a
+freshly cloned warm value), never shared. Fail-open at every branch: no plan, a non-object body, or
+an unrevivable field value keeps the honest-JSON form so a type/runtime mismatch degrades visibly
+rather than throwing. Top-level fields only; a structured value nested deeper is not descended into
+(deferred, ADR-0029).
+*/
+export function reviveWireOutput(value: unknown, plan: OutputWirePlan | undefined): unknown {
+    if (plan === undefined) {
+        return value
+    }
+    /* Only a plain object carries the named fields; a top-level array/scalar/null has none. */
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return value
+    }
+    const record = value as Record<string, unknown>
+    for (const key in plan) {
+        const fieldPlan = plan[key]
+        if (fieldPlan === undefined || !(key in record)) {
+            continue
+        }
+        record[key] = reviveWireField(record[key], fieldPlan)
+    }
+    return value
+}

package/src/lib/shared/rpcServerForRoot.ts

@@ -0,0 +1,25 @@
+import { createRpcServerProgram, type RpcServerProgram } from './createRpcServerProgram.ts'
+
+/*
+Warm per-root accessor for the rpc server program (ADR-0025 D1), mirroring the UI shadow's
+`interpolationClassifierForRoot`: the first rpc transform in a root builds the `ts.Program`,
+every later transform (streaming/method query) reuses it. Fails open in two layers — a
+program that can't build stores `undefined` so the root is not retried and every query falls
+back to the char-scan (each query method also catches per-query throws). The cache lives
+in the resolver plugin's `setup` closure, so it persists across a whole build and is dropped
+between plugin instances.
+*/
+export function rpcServerForRoot(
+    cache: Map<string, RpcServerProgram | undefined>,
+    cwd: string,
+    rpcDir: string,
+): RpcServerProgram | undefined {
+    if (!cache.has(cwd)) {
+        try {
+            cache.set(cwd, createRpcServerProgram(cwd, rpcDir))
+        } catch {
+            cache.set(cwd, undefined)
+        }
+    }
+    return cache.get(cwd)
+}

package/src/lib/shared/scanPages.ts

@@ -0,0 +1,25 @@
+import { existsSync } from 'node:fs'
+import { Glob } from 'bun'
+import { fileName } from './fileName.ts'
+import type { PagesScan } from './types/PagesScan.ts'
+
+/*
+Walks src/ui/pages once and classifies each `.abide` leaf by filename: a
+`page.abide` is a route (its URL is the folder path), a `layout.abide` is a
+layout that wraps every page at or below its folder (keyed by the same folder
+URL). Any other `.abide` file (a shared component) is ignored here — free to
+live anywhere and be imported relatively. Shared by the resolver plugin's
+pages/layouts manifests and generateDeclarations' routes.d.ts so the two never
+diverge on what counts as a route.
+*/
+export async function scanPages(pagesDir: string): Promise<PagesScan> {
+    if (!existsSync(pagesDir)) {
+        return { pageFiles: [], layoutFiles: [] }
+    }
+    const allFiles = await Array.fromAsync(new Glob('**/*.abide').scan({ cwd: pagesDir }))
+    const leafIs = (name: string) => (file: string) => fileName(file) === name
+    return {
+        pageFiles: allFiles.filter(leafIs('page.abide')),
+        layoutFiles: allFiles.filter(leafIs('layout.abide')),
+    }
+}

package/src/lib/shared/snapshotShippable.ts

@@ -1,14 +1,15 @@
-import { hasReplayableRequest } from './hasReplayableRequest.ts'
+import { hasSeedableRequest } from './hasSeedableRequest.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 
 /*
 The one store-filter predicate selecting which cache entries are candidates for a
-warm snapshot: settled AND carrying a replayable (GET-only) wire request, so it
-can ship without re-firing a write or losing a body. Every selection site
-(serializeCacheSnapshot, the renderer's render-return and streaming-drain filters)
-calls this instead of re-spelling the guard, so they cannot drift.
+warm snapshot: settled AND carrying a seedable wire request (any method), so an
+inline call hydrates warm on the client instead of re-firing after render. Every
+selection site (serializeCacheSnapshot, the renderer's render-return and
+streaming-drain filters) calls this instead of re-spelling the guard, so they
+cannot drift.
 
-Composed from `hasReplayableRequest` — the request half snapshotEntryFromCache
+Composed from `hasSeedableRequest` — the request half snapshotEntryFromCache
 also gates on. snapshotEntryFromCache itself uses ONLY the request half (not
 `settled`): the streaming-drain path hands it still-pending entries and awaits
 them, so it can't require `settled` up front.
@@ -18,5 +19,5 @@ awaiting its body. The async response-level half (non-streaming + warmable kind)
 lives in snapshotEntryFromCache, reading the resolved Response.
 */
 export function snapshotShippable(entry: CacheEntry): boolean {
-    return entry.settled === true && hasReplayableRequest(entry)
+    return entry.settled === true && hasSeedableRequest(entry)
 }

package/src/lib/shared/streamedCellsSlot.ts

@@ -0,0 +1,14 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { StreamedCells } from './types/StreamedCells.ts'
+
+/*
+The active streamed-cells slot — mirrors `resolvedCellsSlot`/`pendingAsyncCellsSlot`. The server
+entry installs an ALS-backed resolver (a fresh list per request, so concurrent SSR renders never
+mix their streamed values); with no resolver a single fallback list is created lazily so isolated
+tests work without booting the runtime. `createAsyncCell` pushes a `{ key, promise }` when a
+STREAMING cell constructs server-side; the page renderer drains it during the stream, awaiting each
+promise and streaming an `__abideResolve({ cellKey, value })` chunk (ADR-0035).
+*/
+export const streamedCellsSlot = createResolverSlot<StreamedCells>(() => ({
+    entries: [],
+}))

package/src/lib/shared/subscribableFromResponse.ts

@@ -1,19 +1,19 @@
 import { streamResponse } from './streamResponse.ts'
-import type { Subscribable } from './types/Subscribable.ts'
+import type { NamedAsyncIterable } from './types/NamedAsyncIterable.ts'
 
 /*
-Builds the Subscribable returned by `fn.stream(args)`. The carried
+Builds the NamedAsyncIterable returned by `fn.stream(args)`. The carried
 `name` is the cache-style key for (method, url, args) so tail()
 dedupes multiple readers of identical args into one underlying
 fetch. The fetch is deferred until the first iterator pull so
-constructing the Subscribable (which happens on every $derived
+constructing the NamedAsyncIterable (which happens on every $derived
 re-evaluation) doesn't open a connection — tail()'s registry
 short-circuits the second instance before it iterates.
 */
 export function subscribableFromResponse<T>(
     name: string,
     fetchResponse: () => Promise<Response>,
-): Subscribable<T> {
+): NamedAsyncIterable<T> {
     return {
         name,
         [Symbol.asyncIterator]() {

package/src/lib/shared/subscribableProbes.ts

@@ -29,7 +29,7 @@ re-derive by scanning.
 const lifecycle = createLifecycleChannel()
 
 /*
-Installs the prober the shared probes call for a Subscribable (probeRegistries →
+Installs the prober the shared probes call for a NamedAsyncIterable (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

package/src/lib/shared/tailProbeSlot.ts

@@ -1,6 +1,6 @@
 /*
 Internal slot the browser tail() registry registers its prober into, so the
-shared probes (pending / refreshing) can answer for Subscribables without
+shared probes (pending / refreshing) can answer for NamedAsyncIterables without
 shared/ importing browser/. The prober taps the registry's lifecycle channel
 (reactive inside $derived / $effect) and reports one stream by source name —
 spanning its latest-wins and window entries — or, with no name, whether any

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

@@ -0,0 +1,20 @@
+import type { ASYNC_CELL } from '../ASYNC_CELL.ts'
+
+/*
+A read-only async cell — what `computed(await …)` / `computed(getStream())` produce.
+It *tracks* an async source (a promise it unwrapped, or a NamedAsyncIterable whose
+frames it follows) rather than holding a value. Unlike sync `Computed<T>` it has NO
+`.value`; it is read through the probe family, always method-form — `peek()` (the
+retained value or latest frame, or `undefined`), `pending()` (no value yet),
+`refreshing()` (a value held while a fresher source is in flight), `error()` (the
+last rejection), `refresh()` (re-invoke the source). The standalone probes route
+here too: `peek(cell)` ≡ `cell.peek()`. Branded so those probes recognise it.
+*/
+export interface AsyncComputed<T> {
+    readonly [ASYNC_CELL]: true
+    peek(): T | undefined
+    pending(): boolean
+    refreshing(): boolean
+    error(): unknown
+    refresh(): void
+}

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

@@ -0,0 +1,13 @@
+import type { AsyncComputed } from './AsyncComputed.ts'
+
+/*
+A writable async cell — what `linked(await …)` / `linked(getStream())` produce. Same
+probe surface as `AsyncComputed<T>` plus `set(value)`, following the normal `linked`
+write rule: a local write latches until the next *reseed* (a dependency change that
+produces a new source). An arriving frame or a settling promise updates the value only
+while unwritten, so a high-frequency stream never clobbers an in-progress edit; a
+reseed clears the write and snaps the cell back to the live source.
+*/
+export interface AsyncState<T> extends AsyncComputed<T> {
+    set(value: T): void
+}

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

@@ -37,20 +37,20 @@ into `__SSR__`; ones still pending were consumed via `{#await}` (render emitted
 the pending branch without blocking) and stream a resolve chunk instead.
 
 `refreshing` flips true while this entry is reloading data it already held —
-either an `swr` refetch (stale value still visible) or the default
+either a keep-stale refetch (stale value still visible) or the default
 drop-then-reload (the prior entry was invalidated and dropped, this is its
 replacement read). It backs refreshing(), distinguishing a reload from a
 first-ever load; cleared when the read settles.
 
-`invalidation` holds the entry's `swr` policy: the refetch thunk (the call
+`invalidation` holds the entry's refetch policy: the refetch thunk (the call
 captured with its args) plus its optional throttle/debounce window and runtime
 timer state, so invalidate() keeps the stale value and revalidates this key —
 rate-limited by the window — instead of dropping the entry. Set at registration
-when the creating read declared `swr`, or attached by a later read declaring it
-on an entry that lacks it (hydrated snapshot entries always start without one) —
-first wins. An armed `timer` is cleared if the entry is evicted, so a dead key
-never refetches. Wrap-time validation guarantees `swr` never coexists with
-ttl: 0 and never sits on a non-replayable remote method.
+for a smart retained read (SWR unconditional for a replayable read — ADR-0020) or
+a producer declaring a throttle/debounce window, or attached by a later read on an
+entry that lacks it (hydrated snapshot entries always start without one) — first
+wins. An armed `timer` is cleared if the entry is evicted, so a dead key never
+refetches.
 */
 export type CacheEntry = {
     key: string

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

@@ -1,14 +1,17 @@
 /*
-Options for cache(). The key is always auto-derived (method+url+args for a remote
-function, producer-reference+args for a plain producer): hoist a producer to a
-stable reference to share its entry across calls. `ttl` is the
-milliseconds-past-resolve that the entry stays live: 0 = dedupe only (entry
-dropped once the promise settles — the mutation idiom: in-flight coalescing and
-pending() visibility, nothing retained), any other number = TTL. Omitted = forever
-for a producer and for a remote call on the client; a remote call on the SERVER
-with neither `ttl` nor `swr` stated defaults to 0 (coalesce-only — the request is
-the atomic unit, nothing is retained past it; pair with `shared` + an explicit
-`ttl` to memoise across requests).
+Options for the explicit `cache(producer, args, options?)` call over a plain
+producer, and the value-shape of an endpoint's `cache` policy (CachePolicy adds
+only the arg-derived `tags` function form on top). A remote rpc has no options
+argument any more — its policy lives on the definition (ADR-0020); this type is
+the producer's only policy home. The key is always auto-derived
+(producer-reference+args): hoist a producer to a stable reference to share its
+entry across calls.
+
+`ttl` is the milliseconds-past-resolve the entry stays live: 0 = dedupe only
+(entry dropped once the promise settles — in-flight coalescing and pending()
+visibility, nothing retained), any other number = TTL. Omitted = forever for a
+producer.
+
 `tags` is an array of free-form labels grouping unrelated calls so one
 `cache.invalidate({ tags })` drops every entry sharing any of them — list
 multiple when a call belongs to multiple invalidation groups. A unique tag (e.g.
@@ -17,39 +20,22 @@ a uuid) shared by a set of calls gives them their own private invalidation group
 `shared` opts the entry into the process-level store instead of the default
 request-scoped one (server) — a store that outlives every request. It selects
 the store only; it does NOT retain (pair it with `ttl` to memoise across
-requests). The shared store is keyed by method+url+args, never by user, so do
-not put per-user data in it — it would be served to other users. Omit `shared`
-for per-request data. Write only `shared: true`; there is no `false` form. On
-the client there is a single tab store, so the flag is a no-op there.
-
-`swr` is stale-while-revalidate: it changes what a `cache.invalidate` hit does
-to this key. Without it, an invalidate drops the entry and the next read shows
-`pending()`. With it, the entry is kept and refetched in the background — the
-existing (stale) value stays visible and `refreshing()` reports the in-flight
-reload — so the reader never blanks. It governs only the refetch-after-invalidate;
-the first fetch and arg-change fetches stay immediate regardless.
-
-`swr: true` refetches immediately on every invalidate. An optional window
-coalesces a burst (e.g. a socket spraying `cache.invalidate`) into far fewer
-calls: `swr: { throttle: N }` refetches on the leading edge then at most once
-per N ms while invalidations keep arriving; `swr: { debounce: N }` refetches
-only after N ms of quiet. `swr` declares the call safe to re-run unprompted:
-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.
+requests). The shared store is keyed by producer-reference+args, never by user,
+so do not put per-user data in it — it would be served to other users. Omit
+`shared` for per-request data. Write only `shared: true`; there is no `false`
+form. On the client there is a single tab store, so the flag is a no-op there.
 
-`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.
+`throttle`/`debounce` arm the keep-stale-and-revalidate refetch clock for a
+producer: with one set, a `cache.invalidate` hit keeps the stale value visible
+and coalesces a background refetch (leading-edge-then-coalesce, or
+fire-after-quiet respectively) instead of dropping the entry. Set one, not both.
+SWR is otherwise unconditional for replayable remote reads; there is no `swr`
+toggle.
 */
 export type CacheOptions = {
     ttl?: number
     tags?: string[]
     shared?: boolean
-    swr?: boolean | { throttle?: number; debounce?: number }
     throttle?: number
     debounce?: number
 }

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

@@ -0,0 +1,25 @@
+/*
+Endpoint cache policy, declared once on the rpc definition (ADR-0020). Same value
+shape as the producer-side `CacheOptions` (`ttl` / `tags` / `throttle` / `debounce`
+/ `shared`, no `swr` — SWR is unconditional for replayable reads), except `tags`
+also accepts an arg-derived function so the group can vary by call. That makes the
+type generic over the rpc's `Args`: `(args) => ['rates:' + args.base]` is typed
+against the endpoint's own argument shape.
+
+- `ttl` — retention/staleness in ms. Default Infinity: the entry is retained for its
+  store's lifetime — the request on the server (a non-shared read dies with the request,
+  regardless of ttl), the tab on the client (until invalidate/refresh). An explicit ttl
+  is a hard expiry on the server, a staleness deadline (SWR) on the client.
+- `tags` — static invalidation-group labels, or a function of the call's args.
+- `throttle` / `debounce` — the background refetch clock (set one, not both).
+- `shared` — opt the entry into the process-level store (never per-user data — the store
+  is keyed by method+url+args, not by user). With the default Infinity ttl this memoises
+  across requests; an explicit ttl bounds it. A client no-op (one tab store).
+*/
+export type CachePolicy<Args> = {
+    ttl?: number
+    tags?: string[] | ((args: Args) => string[])
+    throttle?: number
+    debounce?: number
+    shared?: boolean
+}

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

@@ -1,15 +1,16 @@
-import type { ReplayableMethod } from './ReplayableMethod.ts'
+import type { HttpMethod } from './HttpMethod.ts'
 
 /*
 Wire format for a single cached response shipped from SSR to client hydration.
-Only replayable entries (see REPLAYABLE_METHODS) with a textual Content-Type
-are emitted — writes must not re-fire from a snapshot, and binary bodies don't
-survive a JSON round-trip.
+Any entry called inline during render (any method) with a textual Content-Type is
+emitted, so the client hydrates warm instead of re-firing the call after render;
+binary bodies don't survive a JSON round-trip. The seeded value is read warm once
+— it is never auto-replayed (that stays GET-only, see REPLAYABLE_METHODS).
 */
 export type CacheSnapshotEntry = {
     key: string
     url: string
-    method: ReplayableMethod
+    method: HttpMethod
     status: number
     statusText: string
     headers: Array<[string, string]>

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

@@ -0,0 +1,8 @@
+/*
+Status-keyed map of a handler's typed-error data schemas (ADR-0030), baked at build time from the
+handler's `error.typed(name, status, schema?)` return branches. Each key is an HTTP status, each
+value the error's `data` type projected to JSON Schema (multiple errors sharing a status combine
+under `anyOf`; a nullary error with no data contributes a bare `{}`). Feeds the OpenAPI
+`responses[status]` surface — the error-branch sibling of the success `outputJsonSchema`.
+*/
+export type ErrorJsonSchemas = Record<number, Record<string, unknown>>

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

@@ -1 +1,3 @@
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD'
+import type { HTTP_METHODS } from '../HTTP_METHODS.ts'
+
+export type HttpMethod = (typeof HTTP_METHODS)[number]

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

@@ -0,0 +1,17 @@
+import type { WireKind } from './WireKind.ts'
+
+/*
+The build-time wire codec plan for a rpc's input args, keyed by field name (ADR-0028 for the
+scalar `number`/`boolean` kinds, generalized by ADR-0029 to the structured `date`/`bigint`/`set`/
+`map` kinds). A GET/form request delivers every field as a string, and a non-abide JSON client
+sends a `Date` as an ISO string / a `Set` as an array, so parseArgs uses this plan to revive each
+declared field into the typed value the input schema expects — before validation, on the exact
+fields the author declared. String and other-typed fields are never listed, so a value that merely
+looks numeric (an id, a zip code, `'1.0'`) stays a string. The plan is derived by the warm server
+program from the real type graph and stamped into the server `defineRpc` call; a field is absent
+when its type is anything but a recognized WireKind (or an array / optional thereof), so the codec
+is precise and fail-open — no plan ⇒ today's string-through behavior. The abide client's own
+POST/PUT/PATCH body already round-trips these kinds via ref-json; the plan covers the query-string
+and non-abide-client paths where ref-json isn't in play.
+*/
+export type InputCoercion = Record<string, WireKind>

package/src/lib/shared/types/{Subscribable.ts → NamedAsyncIterable.ts}

@@ -20,7 +20,7 @@ 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> {
+export interface NamedAsyncIterable<T> extends AsyncIterable<T> {
     readonly name: string
     tail?(count: number, hooks?: TailHooks): AsyncIterable<T>
 }

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

@@ -0,0 +1,17 @@
+import type { WireKind } from './WireKind.ts'
+
+/*
+The build-time wire codec plan for a rpc's success RESPONSE body, keyed by top-level field name
+(ADR-0029 output path — the response-side sibling of `InputCoercion`). The server serializes a
+handler's structured return through a value-directed replacer (`wireJsonReplacer`), so a `Set`
+crosses as a JSON array, a `Map` as an `[K,V]` entries array, and a `bigint` as a digit string —
+honest JSON a non-abide client still reads. But a wire array is ambiguous (a real `T[]` vs an
+encoded `Set<T>`), so an abide client needs the DECLARED kind to revive: this plan carries only the
+structured kinds (`date`/`bigint`/`set`/`map`) the client proxy revives from a decoded response body.
+It is resolved by the warm server program from the handler's success-body type and baked onto the
+CLIENT `remoteProxy` stub (next to the live `schemas`, ADR-0022 D2). A field absent from the plan (a
+genuine array, a scalar, a `number`/`boolean` JSON already carries) is left untouched. Fail-open —
+no plan / an unrevivable value keeps the honest-JSON form, never a throw. Top-level fields only in
+this increment; a structured value nested inside another value is not descended into.
+*/
+export type OutputWirePlan = Record<string, WireKind>

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

@@ -0,0 +1,7 @@
+/* The classification scanPages returns for src/ui/pages: route leaves
+   (page.abide) and layout leaves (layout.abide), each an array of paths
+   relative to the pages dir. */
+export type PagesScan = {
+    pageFiles: string[]
+    layoutFiles: string[]
+}

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

@@ -0,0 +1,10 @@
+/*
+The per-request list of in-flight async-cell promises registered during an SSR
+render. `createAsyncCell` pushes each settling promise here (server-side only);
+`settleAsyncCells` drains and awaits them between a component's cell declarations
+and its template, so the resolved values bake into the first-pass HTML (ADR-0019
+Tier-2) instead of the template peeking `undefined`.
+*/
+export type PendingAsyncCells = {
+    promises: Promise<unknown>[]
+}

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

@@ -1,5 +1,7 @@
+import type { CachePolicy } from './CachePolicy.ts'
 import type { HttpMethod } from './HttpMethod.ts'
 import type { RemoteCallable } from './RemoteCallable.ts'
+import type { StreamPolicy } from './StreamPolicy.ts'
 
 /*
 Bare-response remote function — same call shape as RemoteFunction but
@@ -11,4 +13,8 @@ implement custom error handling can opt out of the decode.
 export type RawRemoteFunction<Args> = RemoteCallable<Args, Response> & {
     readonly method: HttpMethod
     readonly url: string
+    /* Endpoint cache/stream policy (ADR-0020), stamped on this variant too so readThrough can
+       read it whether the caller passed `fn` or `fn.raw`. Same value as the decoded sibling's. */
+    readonly cache?: CachePolicy<Args>
+    readonly stream?: StreamPolicy
 }

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

@@ -1,5 +1,5 @@
+import type { NamedAsyncIterable } from './NamedAsyncIterable.ts'
 import type { RpcOptions } from './RpcOptions.ts'
-import type { Subscribable } from './Subscribable.ts'
 
 /*
 Call signature shared by RemoteFunction and RawRemoteFunction. The base
@@ -10,24 +10,25 @@ optional-arg signature lets call sites write `fn()` instead of
 stays callable while `Args` is still generic (cache() invokes producers
 before `Args` resolves). FormData is the multipart upload escape hatch —
 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:
+call (RemoteFunction) takes no second argument at all (`Opts = never` — all
+cache/stream policy lives on the rpc definition per ADR-0020), 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
+the bare call return a `NamedAsyncIterable<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.
+error (a NamedAsyncIterable is not awaitable), which replaces the old runtime guard.
 */
 /* `[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>`. */
+   would mistype as a NamedAsyncIterable. A real streaming rpc's `Resolved` is `AsyncIterable<Frame>`. */
 type CallResult<Resolved> = [Resolved] extends [never]
     ? Promise<Resolved>
     : Resolved extends AsyncIterable<infer Frame>
-      ? Subscribable<Frame>
+      ? NamedAsyncIterable<Frame>
       : Promise<Resolved>
 
 export type RemoteCallable<Args, Resolved, Opts = RpcOptions> = ((

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

@@ -1,12 +1,12 @@
+import type { CachePolicy } from './CachePolicy.ts'
 import type { ClientFlags } from './ClientFlags.ts'
 import type { ErrorSpec } from './ErrorSpec.ts'
 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 { SmartReadOptions } from './SmartReadOptions.ts'
+import type { StreamPolicy } from './StreamPolicy.ts'
 
 /*
 Remote function reference produced by GET/POST/... inside an `$rpc/**`
@@ -21,7 +21,7 @@ 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`). A streaming handler (jsonl()/sse()) makes the bare call return a
-`Subscribable<Frame>` directly (the iterable IS the value) — consume it with
+`NamedAsyncIterable<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
@@ -44,23 +44,29 @@ export type RemoteFunction<
     Args,
     Return,
     Errors extends ErrorSpec = Record<never, never>,
-    Durable extends boolean = false,
-> = RemoteCallable<Args, Return, SmartReadOptions> & {
+> = RemoteCallable<Args, Return, never> & {
     readonly method: HttpMethod
     readonly url: string
     readonly clients: ClientFlags
     readonly crossOrigin?: boolean
+    /* Endpoint cache/stream policy declared on the rpc definition (ADR-0020), stamped
+       here so the smart read (readThrough) reads it as the bottom policy layer. Ships to
+       the client too — it governs client cache behaviour and is behaviour, not secrets
+       (`shared` is a client no-op). Absent on a plainly-defined rpc (method defaults only). */
+    readonly cache?: CachePolicy<Args>
+    readonly stream?: StreamPolicy
     readonly raw: RawRemoteFunction<Args>
     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. */
+       `'validation'`): 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>
     /* 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
+       the globals. The bare call `fn(args)` IS the cached read (was `fn.cache`) — all cache
+       policy lives on the definition, so there is no second options argument, 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
@@ -93,9 +99,4 @@ export type RemoteFunction<
         : {
               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> })
+          })

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

@@ -0,0 +1,11 @@
+/*
+The per-request list of async-cell values that RESOLVED during an SSR render, each keyed by the
+cell's serialization-stable render-path id (`${scope.id}:${index}`). `createAsyncCell` pushes an
+entry when its seed settles server-side; the page renderer stamps them into `__SSR__.cells`
+(ref-json-encoded) so the client hydrates the cell WARM — reading the value instead of re-running
+the seed (no refetch, no pending flash). The sibling of `PendingAsyncCells` (the barrier's
+in-flight list); this one holds settled VALUES, read at render-return rather than awaited.
+*/
+export type ResolvedCells = {
+    entries: { key: string; value: unknown }[]
+}

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

@@ -0,0 +1,15 @@
+/*
+The build-time success-body descriptor for an rpc, derived from the handler's return type by the
+warm server program (ADR-0030). Mirrors `RpcHelper`'s `SuccessBody<R>` projection: the handler's
+`Awaited<ReturnType>` union has its `TypedError` branches dropped, and each success
+`TypedResponse<Body>` contributes its `Body`. `type` is that body rendered as a TS type string
+(the union of the surviving branches). For a streaming endpoint (`jsonl()`/`sse()` →
+`TypedResponse<AsyncIterable<Frame>>`) `streaming` is true and `type` is the per-FRAME type — the
+AsyncIterable element — so a consumer describes one streamed item rather than the iterable itself.
+The query fails open to undefined (no handler/body resolvable), matching every other server-program
+query.
+*/
+export type ReturnBody = {
+    type: string
+    streaming: boolean
+}