@abide/abide 0.53.0 → 0.55.0

package/src/lib/server/rpc/types/RpcHelper.ts

@@ -74,30 +74,33 @@ type RpcSchemas = {
 
 /*
 Options every rpc overload accepts: the `schemas` namespace, the `clients` surface
-flags (browser/mcp/cli), the same-origin
-CSRF exemption (`crossOrigin`), the pre-parse body-byte ceiling
-(`maxBodySize`), and the per-surface handler `timeout` (ms). Read helpers add the
-endpoint `cache`/`stream` policy (ADR-0020); mutating helpers add neither — a write has
-no replayable value to retain or stream. The kind-scoping is what makes `POST(fn, { cache })`
-a compile error rather than a silent no-op. The single canonical source both `defineRpc`
-and `RpcRegistryEntry` project from.
+flags (browser/mcp/cli), the same-origin CSRF exemption (`crossOrigin`), the pre-parse
+body-byte ceiling (`maxBodySize`), the per-surface handler `timeout` (ms), and the
+endpoint `cache` policy (ADR-0020). `cache` is shared by both kinds: a mutating rpc
+whose method is a transport choice (a POST that carries a large `code` payload in its
+body yet is a pure function of its args) still coalesces/memoises like a read — the
+runtime already routes `fn.cache` through `readThrough` regardless of method. What stays
+read-only is `stream` (`RpcReadOpts`) — a write has no replayable value to stream.
+Generic over `Args` so `cache.tags`'s `(args) => string[]` form is typed against the
+rpc's own argument shape. The single canonical source both `defineRpc` and
+`RpcRegistryEntry` project from.
 */
-type RpcSharedOpts = {
+type RpcSharedOpts<Args> = {
     schemas?: RpcSchemas
     clients?: Partial<ClientFlags>
     crossOrigin?: boolean
     maxBodySize?: number
     timeout?: number
+    cache?: CachePolicy<Args>
 }
 
 /*
-Read-helper (GET/HEAD) options: the shared base plus the endpoint `cache` policy
-(`ttl`/`tags`/`throttle`/`debounce`/`shared`) and `stream` policy (`n`, replay depth).
-Generic over `Args` so `cache.tags`'s `(args) => string[]` form is typed against the
-rpc's own argument shape.
+Read-helper (GET/HEAD) options: the shared base (including `cache`) plus the endpoint
+`stream` policy (`n`, replay depth) — the one option kind-scoped to replayable reads,
+since a write has no replayable stream. Generic over `Args`, threaded into the shared
+base so `cache.tags`'s `(args) => string[]` form is typed against the rpc's own args.
 */
-type RpcReadOpts<Args> = RpcSharedOpts & {
-    cache?: CachePolicy<Args>
+type RpcReadOpts<Args> = RpcSharedOpts<Args> & {
     stream?: StreamPolicy
 }
 
@@ -147,11 +150,15 @@ export type RpcHelper = {
 }
 
 /*
-The mutating helpers (POST/PUT/PATCH/DELETE). The base opts is the shared `RpcSharedOpts`
-(no `cache`/`stream`) — coalesce-only is the method default and a write has no replayable
-value to retain or stream — which is what makes `cache`/`stream` a compile error here while
-they stay legal on the read helpers (`RpcReadOpts`) — the kind-scoping. Overloads mirror the read helpers by argument source
-(multipart-upload, schema'd, schemaless-with-opts, bare).
+The mutating helpers (POST/PUT/PATCH/DELETE). The base opts is the shared `RpcSharedOpts`,
+which carries `cache` — a mutating rpc still accepts a cache policy (a POST that is a pure
+function of its args, using the body only to carry a large payload, coalesces/memoises like
+a read; the runtime honours `fn.cache` regardless of method). Note the method default for a
+write stays coalesce-only: a no-ttl write is dropped on settle (the mutation idiom), so
+retention across the in-flight window needs an explicit `cache.ttl` (or `shared`). Only
+`stream` stays read-only (`RpcReadOpts`) — a write has no replayable stream — so `POST(fn,
+{ stream })` remains a compile error while `POST(fn, { cache })` is legal. Overloads mirror
+the read helpers by argument source (multipart-upload, schema'd, schemaless-with-opts, bare).
 */
 export type MutatingRpcHelper = {
     <
@@ -163,16 +170,16 @@ export type MutatingRpcHelper = {
             args: StandardSchemaV1.InferOutput<InputSchema> &
                 StandardSchemaV1.InferOutput<FilesSchema>,
         ) => R | Promise<R>,
-        opts: RpcSharedOpts & {
+        opts: RpcSharedOpts<StandardSchemaV1.InferInput<InputSchema>> & {
             schemas: { input: InputSchema; files: FilesSchema; output?: StandardSchemaV1 }
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
     <R extends Response, InputSchema extends StandardSchemaV1 = StandardSchemaV1>(
         fn: (args: StandardSchemaV1.InferOutput<InputSchema>) => R | Promise<R>,
-        opts: RpcSharedOpts & {
+        opts: RpcSharedOpts<StandardSchemaV1.InferInput<InputSchema>> & {
             schemas: { input: InputSchema; output?: StandardSchemaV1 }
         },
     ): RemoteFunction<StandardSchemaV1.InferInput<InputSchema>, SuccessBody<R>, InferredErrors<R>>
-    <F extends RpcFn>(fn: F, opts: RpcSharedOpts): RpcOf<F>
+    <F extends RpcFn>(fn: F, opts: RpcSharedOpts<RpcArgs<F>>): RpcOf<F>
     <F extends RpcFn>(fn: F): RpcOf<F>
 }

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

@@ -1,7 +1,8 @@
 /*
 The tiny inline script the abide-ui SSR stream ships in <head>. For each streamed
 `<abide-resolve data-id>` frame it reads the leading `<script type=application/json>`,
-stores its raw ref-json text into `window.__abideResume` (the resume manifest hydration
+stores its raw ref-json text into `window.__abideSeeds.resume` (the resume partition of the
+one seed manifest, ADR-0048 — the store hydration
 reads, decoding each entry at read time) and swaps the resolved markup into the matching
 `<!--abide:await:ID-->…<!--/abide:await:ID-->` boundary — so the pending shell paints
 instantly and each value lands as it arrives, before the client bundle even loads. It
@@ -12,7 +13,7 @@ inlines cheaply ahead of the document body.
 export const SSR_SWAP_SCRIPT =
     "function __abideSwap(){var f=document.querySelector('abide-resolve');while(f){" +
     "var id=f.getAttribute('data-id'),p=f.firstChild,w=document.createTreeWalker(document.body,NodeFilter.SHOW_COMMENT),o=null,c;" +
-    "if(p&&p.nodeName==='SCRIPT'){(window.__abideResume=window.__abideResume||{})[id]=p.textContent||'';p.remove();}" +
+    "if(p&&p.nodeName==='SCRIPT'){var s=window.__abideSeeds=window.__abideSeeds||{};(s.resume=s.resume||{})[id]=p.textContent||'';p.remove();}" +
     "while((c=w.nextNode())){if(c.data==='abide:await:'+id){o=c;break;}}" +
     "if(o){var n=o.nextSibling;while(n&&!(n.nodeType===8&&n.data==='/abide:await:'+id)){var x=n.nextSibling;n.remove();n=x;}" +
     "while(f.firstChild){o.parentNode.insertBefore(f.firstChild,n);}}f.remove();f=document.querySelector('abide-resolve');}}"

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

@@ -0,0 +1,53 @@
+import { AMEND_TOPIC_PREFIX } from '../../shared/AMEND_TOPIC_PREFIX.ts'
+import { encodeRefJson } from '../../shared/encodeRefJson.ts'
+import { keyForRemoteCall } from '../../shared/keyForRemoteCall.ts'
+import { REMOTE_FUNCTION } from '../../shared/REMOTE_FUNCTION.ts'
+import type { CacheSelector } from '../../shared/types/CacheSelector.ts'
+import type { RawRemoteFunction } from '../../shared/types/RawRemoteFunction.ts'
+import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
+import { getActiveServer } from './getActiveServer.ts'
+
+/*
+The server half of the isomorphic amend value form (ADR-0043): serialize the keyed
+value to a standard socket `msg` frame and publish it on the per-call reserved topic
+`__abide/amend/<key>`, so every browser with a live reader of that exact call (and thus
+already authorized for it) sets the pushed value locally with no refetch. Installed as
+the amendBroadcastSlot resolver by serverEntry ONLY — never imported from a shared or ui
+module — so this server socket code stays out of the client reachability graph; the
+resolver-slot indirection is the guarantee, not the ADR-0022 DCE guard (which polices the
+app's own src/server edge, not abide's internal lib/server modules). Do not import this
+from a client-reachable module.
+
+Only the value form broadcasts: an updater is a closure with no wire form, so it throws
+here (the mistake surfaces at the mutation site). The value must target an exact call — a
+remote function with its args, or a no-input rpc's single key — since a value has to land
+on one entry; a producer/closure or `{ tags }` selector has no single cross-client key and
+throws. The rpc's own key derivation (keyForRemoteCall) names the topic, so it agrees with
+the client cache key by construction. Subscriber-gated: skip the encode + native publish
+when no client is reading that key (the topic evaporates — it holds no tail).
+*/
+export function broadcastAmend<Args, Return>(
+    selector: CacheSelector<Args, Return>,
+    args: Args | undefined,
+    isValue: boolean,
+    payload: Return | ((current: Return) => Return),
+): void {
+    if (!isValue) {
+        throw new Error(
+            '[abide] amend() with an updater is client-local (a closure has no wire form) — pass a value to broadcast from the server.',
+        )
+    }
+    if (typeof selector !== 'function' || !(REMOTE_FUNCTION in selector)) {
+        throw new Error(
+            '[abide] amend(value) can only broadcast for a remote function — a producer/closure or { tags } selector has no cross-client key.',
+        )
+    }
+    const remote = selector as RawRemoteFunction<Args>
+    const topic = `${AMEND_TOPIC_PREFIX}${keyForRemoteCall(remote.method, remote.url, args)}`
+    const server = getActiveServer()
+    if (server === undefined || server.subscriberCount(`socket:${topic}`) === 0) {
+        return
+    }
+    const frame: SocketServerFrame = { type: 'msg', socket: topic, message: payload }
+    server.publish(`socket:${topic}`, encodeRefJson(frame))
+}

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

@@ -1,12 +1,13 @@
 import { appNameSlot } from '../../shared/appNameSlot.ts'
 import { SSR_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
 import { docSnapshotsSlot } from '../../shared/docSnapshotsSlot.ts'
-import { encodeRefJson } from '../../shared/encodeRefJson.ts'
+import { encodeSeedValue } from '../../shared/encodeSeedValue.ts'
 import { formatTraceparent } from '../../shared/formatTraceparent.ts'
 import { hasSeedableRequest } from '../../shared/hasSeedableRequest.ts'
 import { layoutChainForRoute } from '../../shared/layoutChainForRoute.ts'
 import { resolvedCellsSlot } from '../../shared/resolvedCellsSlot.ts'
 import { safeJsonForScript } from '../../shared/safeJsonForScript.ts'
+import { socketTailsSlot } from '../../shared/socketTailsSlot.ts'
 import type { CacheEntry } from '../../shared/types/CacheEntry.ts'
 import type { CacheSnapshotEntry } from '../../shared/types/CacheSnapshotEntry.ts'
 import type { SsrPayload } from '../../shared/types/SsrPayload.ts'
@@ -115,12 +116,13 @@ export function createUiPageRenderer({
         }
         const cells: Record<string, string> = {}
         for (const { key, value } of entries) {
-            try {
-                cells[key] = encodeRefJson(value)
-            } catch {
-                console.warn(
-                    `[abide] async cell "${key}" resolved to an unserializable value — it will re-run on the client instead of hydrating warm.`,
-                )
+            const encoded = encodeSeedValue(
+                value,
+                `async cell "${key}" resolved value`,
+                'it will re-run on the client instead of hydrating warm',
+            )
+            if (encoded !== undefined) {
+                cells[key] = encoded
             }
         }
         return Object.keys(cells).length > 0 ? cells : undefined
@@ -151,16 +153,43 @@ export function createUiPageRenderer({
             ) {
                 continue
             }
-            try {
-                docs[id] = encodeRefJson(snapshot)
-            } catch {
-                /* Unserializable synchronous state (a function/class instance) — the client re-inits
-                   it cold rather than blanking the payload. */
+            const encoded = encodeSeedValue(
+                snapshot,
+                `scope "${id}" state snapshot`,
+                'the client re-inits its state cold',
+            )
+            if (encoded !== undefined) {
+                docs[id] = encoded
             }
         }
         return Object.keys(docs).length > 0 ? docs : undefined
     }
 
+    /* The `sockets` partition of __SSR__: each socket whose retained frame this render read via
+       `peek(socket)` (drained from the request-scoped `socketTailsSlot` populated by
+       `defineSocket.peek`), keyed by socket NAME, ref-json-encoded. Last write per name wins — a
+       socket peeked twice ships its latest read. An unserializable frame is dropped (a warn): that
+       socket falls back to a cold client peek (undefined) rather than blanking the payload. Undefined
+       when no socket was peeked during the render (the common page). */
+    function socketTailSnapshots(): Record<string, string> | undefined {
+        const entries = socketTailsSlot.get()?.entries ?? []
+        if (entries.length === 0) {
+            return undefined
+        }
+        const sockets: Record<string, string> = {}
+        for (const { name, value } of entries) {
+            const encoded = encodeSeedValue(
+                value,
+                `socket "${name}" retained frame`,
+                'its client peek() reads undefined at hydration instead of the server value',
+            )
+            if (encoded !== undefined) {
+                sockets[name] = encoded
+            }
+        }
+        return Object.keys(sockets).length > 0 ? sockets : undefined
+    }
+
     /* Build the __SSR__ <script> the client (startClient) reads on boot. The inline
        (settled) cache partition is computed once by the caller and threaded in, so the
        streaming branch can also drain the pending partition over the same render. */
@@ -177,6 +206,7 @@ export function createUiPageRenderer({
             cache: inline,
             cells: resolvedCellCells(),
             docs: docSeedSnapshots(),
+            sockets: socketTailSnapshots(),
             base: base || undefined,
             trace: formatTraceparent(store.trace),
             app: appNameSlot.name,
@@ -392,10 +422,12 @@ export function createUiPageRenderer({
                            streamed and the client cold-runs it. An unserializable value emits nothing.
                            Read from `store` directly since the stream body runs outside the request ALS. */
                         for (const { key, value } of store.streamedCells.entries) {
-                            let encoded: string
-                            try {
-                                encoded = encodeRefJson(value)
-                            } catch {
+                            const encoded = encodeSeedValue(
+                                value,
+                                `streaming cell "${key}" settled value`,
+                                'the client cold-runs its seed instead of adopting the streamed value',
+                            )
+                            if (encoded === undefined) {
                                 continue
                             }
                             controller.enqueue(
@@ -410,10 +442,12 @@ export function createUiPageRenderer({
                             if (seededCellKeys.has(key)) {
                                 continue
                             }
-                            let encoded: string
-                            try {
-                                encoded = encodeRefJson(value)
-                            } catch {
+                            const encoded = encodeSeedValue(
+                                value,
+                                `streamed child's async cell "${key}" resolved value`,
+                                'it will re-run on the client instead of hydrating warm',
+                            )
+                            if (encoded === undefined) {
                                 continue
                             }
                             controller.enqueue(

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

@@ -34,6 +34,7 @@ export function runWithRequestScope(
         pendingAsyncCells: { promises: [] },
         resolvedCells: { entries: [] },
         streamedCells: { entries: [] },
+        socketTails: { entries: [] },
         docSnapshots: { entries: [] },
         trace: createTraceContext(req.headers.get('traceparent')),
         start: Bun.nanoseconds(),

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

@@ -2,6 +2,7 @@ import type { CacheStore } from '../../../shared/types/CacheStore.ts'
 import type { DocSnapshots } from '../../../shared/types/DocSnapshots.ts'
 import type { PendingAsyncCells } from '../../../shared/types/PendingAsyncCells.ts'
 import type { ResolvedCells } from '../../../shared/types/ResolvedCells.ts'
+import type { SocketTails } from '../../../shared/types/SocketTails.ts'
 import type { StreamedCells } from '../../../shared/types/StreamedCells.ts'
 import type { TraceContext } from '../../../shared/types/TraceContext.ts'
 import type { Scope } from '../../../ui/types/Scope.ts'
@@ -42,6 +43,14 @@ export type RequestStore = {
     */
     streamedCells: StreamedCells
     /*
+    Retained socket frames read via `peek(socket)` during this request's SSR pass, keyed by socket
+    name. `defineSocket`'s server `peek()` pushes each read; the page renderer stamps them into
+    `__SSR__.sockets` (ref-json) so the client seeds `peek(socket)` to the SAME retained value the
+    server rendered instead of `undefined` on the not-yet-connected client. Sibling of `resolvedCells`
+    — a server value carried forward, read at render-return, not awaited.
+    */
+    socketTails: SocketTails
+    /*
     Reactive-document snapshots captured during this request's SSR pass, keyed by render-path id.
     `createScope` registers a lazy `take` for each rendered scope; the page renderer stamps the
     non-empty ones into `__SSR__.docs` (ref-json) so the client seeds a plain `state(initial)` to

package/src/lib/server/sockets/amendFamilyEntry.ts

@@ -0,0 +1,39 @@
+import { browserClientFlags } from '../../shared/browserClientFlags.ts'
+import type { Socket } from '../../shared/types/Socket.ts'
+import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
+
+/* An empty async iterable — the amend channel replays nothing (live-only, no tail). */
+const emptyIterable = {
+    [Symbol.asyncIterator]: () => ({
+        next: async () => ({ done: true as const, value: undefined }),
+    }),
+}
+
+/*
+The single synthetic registry entry the dispatcher resolves every `__abide/amend/<key>`
+topic to (ADR-0043). The amend value channel is a per-call reserved topic family: the
+per-key Bun topic is the sub frame's own socket name, so one shared entry serves the whole
+family — there is no per-key socket object or module to load. It is subscribe-only
+(clientPublish false, so a browser can't forge a push), holds no tail (snapshotTail empty —
+a missed frame heals via the reader's reconnect refresh), and is browser-only, so the REST
+face 404s. The stub Socket methods are never reached: the ws sub path subscribes the raw
+Bun topic and replays via snapshotTail, and the REST face is gated off by the clients flags.
+*/
+const socket = {
+    name: '__abide/amend',
+    clients: browserClientFlags,
+    publish: () => undefined,
+    tail: () => emptyIterable,
+    peek: () => undefined,
+    refresh: () => undefined,
+    watch: () => () => undefined,
+    [Symbol.asyncIterator]: emptyIterable[Symbol.asyncIterator],
+} as unknown as Socket<unknown>
+
+export const amendFamilyEntry: SocketRegistryEntry = {
+    socket,
+    allowClientPublish: false,
+    schema: undefined,
+    clients: browserClientFlags,
+    snapshotTail: () => [],
+}

package/src/lib/server/sockets/createSocketDispatcher.ts

@@ -1,4 +1,5 @@
 import type { ServerWebSocket } from 'bun'
+import { AMEND_TOPIC_PREFIX } from '../../shared/AMEND_TOPIC_PREFIX.ts'
 import { abideLog } from '../../shared/abideLog.ts'
 import { decodeWireBody } from '../../shared/decodeWireBody.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
@@ -10,6 +11,7 @@ import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
 import { error } from '../error.ts'
 import { json } from '../json.ts'
 import { sse } from '../sse.ts'
+import { amendFamilyEntry } from './amendFamilyEntry.ts'
 import { lookupSocket } from './lookupSocket.ts'
 import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
 import type { SocketRoutes } from './types/SocketRoutes.ts'
@@ -87,6 +89,13 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         | { entry: SocketRegistryEntry }
         | { failure: 'unregistered' | 'load-failed' | 'no-export'; message: string }
     > {
+        /* The amend value channel (ADR-0043) is a per-call reserved topic family: one synthetic,
+           subscribe-only entry serves every `__abide/amend/<key>` topic — the per-key Bun topic is
+           the sub frame's own name, and there is no module to load or tail to replay. Checked
+           before the generic reserved lookup, which would miss (no per-key registry entry). */
+        if (name.startsWith(AMEND_TOPIC_PREFIX)) {
+            return { entry: amendFamilyEntry }
+        }
         /* A reserved `__abide/` topic has no user module to load — it is minted at boot into
            the registry (ADR-0041), so skip the loader and read it straight from there. */
         if (name.startsWith(RESERVED_SOCKET_PREFIX)) {

package/src/lib/server/sockets/defineSocket.ts

@@ -2,6 +2,7 @@ import { attachSocketSelectorMethods } from '../../shared/attachSocketSelectorMe
 import { createPushIterator } from '../../shared/createPushIterator.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { resolveClientFlags } from '../../shared/resolveClientFlags.ts'
+import { socketTailsSlot } from '../../shared/socketTailsSlot.ts'
 import { socketTapSlot } from '../../shared/socketTapSlot.ts'
 import type { Socket } from '../../shared/types/Socket.ts'
 import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
@@ -185,7 +186,16 @@ export function defineSocket<T>(name: string, opts: SocketOptions = {}): Socket<
         /* The latest retained frame (after ttl pruning), or undefined when none is held. */
         peek: () => {
             pruneExpired(Date.now())
-            return buffer.length > 0 ? (buffer[buffer.length - 1] as BufferEntry).value : undefined
+            const value =
+                buffer.length > 0 ? (buffer[buffer.length - 1] as BufferEntry).value : undefined
+            /* Record the retained frame this SSR render read so the page renderer can ship it in
+               `__SSR__.sockets` — the client seeds `peek()` to the same value instead of undefined,
+               keeping hydration congruent. `get()` is undefined off-request (ws/boot), so this is a
+               no-op outside an SSR render; a `tail: 0` socket holds no frame and records nothing. */
+            if (value !== undefined) {
+                socketTailsSlot.get()?.entries.push({ name, value })
+            }
+            return value
         },
         /* No-op on the server: it is the source of truth, so there is nothing to re-pull. */
         refresh: () => undefined,

package/src/lib/shared/AMEND_TOPIC_PREFIX.ts

@@ -0,0 +1,9 @@
+/*
+Reserved topic-family prefix for the per-call amend value channel (ADR-0043). A
+server-side `amend(args, value)` broadcasts on `${AMEND_TOPIC_PREFIX}${cacheKey}`, and
+a client with a live reader of that exact call subscribes to the same topic — so a
+pushed value only ever reaches a browser already reading (and therefore authorized
+for) that key. Under the reserved `__abide/` namespace so user code can't shadow it,
+and per-call (not per-rpc) so the subscription set doubles as the authorized-reader set.
+*/
+export const AMEND_TOPIC_PREFIX = '__abide/amend/'

package/src/lib/shared/SEEDS.ts

@@ -0,0 +1,33 @@
+/*
+The ONE hydration seed manifest (ADR-0048): every passive server→client warm-seed
+partition — await resumes, async-cell values, doc snapshots, socket frames — rides a single
+`globalThis.__abideSeeds` global, kind-partitioned. Each partition is a Record of ref-json
+STRINGS decoded lazily at its read site, so the inline pre-bundle scripts (the SSR swap
+script, the resume seed script) can write entries without the codec. The per-kind module
+names (`RESUME`, `CELL_SEED`, `DOC_SEED`, `SOCKET_SEED`) are views onto these partitions,
+so consumers keep their domain name while the wire carries one global.
+
+Each partition initializes with its own `??=` — NOT one whole-object create — because the
+vanilla scripts and the bundle race in either order and a script that ran first may have
+created the root with only its own partition; whoever arrives later must fill the gaps and
+adopt the same references. The live streamed-cell machinery (`STREAMED_CELLS`) and the head
+collector buffer (`__abideResumeCache`) deliberately stay separate: they are apply-timing
+phases (ADR-0040), not passive manifests.
+*/
+type SeedPartitions = {
+    resume: Record<string, string>
+    cells: Record<string, string>
+    docs: Record<string, string>
+    sockets: Record<string, string>
+}
+
+const globalScope = globalThis as { __abideSeeds?: Partial<SeedPartitions> }
+globalScope.__abideSeeds ??= {}
+const root = globalScope.__abideSeeds
+root.resume ??= {}
+root.cells ??= {}
+root.docs ??= {}
+root.sockets ??= {}
+
+// @documentation plumbing
+export const SEEDS: SeedPartitions = root as SeedPartitions

package/src/lib/shared/SOCKET_SEED.ts

@@ -0,0 +1,12 @@
+import { SEEDS } from './SEEDS.ts'
+
+/* The socket warm-seed manifest: a socket's retained latest frame as read via `peek(socket)` during
+   SSR, keyed by the socket's name, as a ref-json-encoded STRING (decoded at the read site in
+   `socketProxy`). `startClient` drains `__SSR__.sockets` into here before mount; a hydrating
+   `socketProxy` reads its key to seed the socket's `lastFrame` WARM, so `peek(socket)` returns the
+   SAME retained value the server rendered instead of `undefined` on the not-yet-connected client —
+   killing the SSR/hydration divergence that would otherwise discard the server markup and cold-render.
+
+   The `sockets` partition of the one `__abideSeeds` manifest (ADR-0048, see SEEDS). */
+// @documentation plumbing
+export const SOCKET_SEED: Record<string, string> = SEEDS.sockets

package/src/lib/shared/amend.ts

@@ -0,0 +1,48 @@
+import { amendBroadcastSlot } from './amendBroadcastSlot.ts'
+import type { CacheOptions } from './types/CacheOptions.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { RemoteFunction } from './types/RemoteFunction.ts'
+
+/*
+Mutate the retained value of the matching cached read(s) in place — reactive
+(readers re-render), no network. The optimistic-update / real-time primitive:
+amend a cached list from a socket frame (`on(chat, m => getList.amend(l => [...l,
+m]))`) or apply an optimistic edit before a write lands. The last argument is
+either a concrete `Return` value (set it) or an updater `(current) => Return`
+(transform the current decoded value). The value form is what a server-side
+`amend(args, value)` broadcasts (ADR-0043 phase 2); the updater form is a closure
+and stays local.
+
+  amend(getFoo, args, value | updater)   → that exact call
+  amend(getFoo, value | updater)         → every args-variant of that rpc
+  amend({ tags }, value | updater)       → every entry sharing a tag
+
+Instance sugar `getFoo.amend(args?, value | updater)` ≡ `amend(getFoo, args, …)`;
+for a no-input rpc the args collapse away (`getFoo.amend(value)` — ADR-0043). The
+value/updater is always the last argument; a not-yet-read key has nothing to amend.
+*/
+// @documentation cache
+export function amend<Args, Return>(
+    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
+    args: Args | undefined,
+    value: Return | ((current: Return) => Return),
+): void
+export function amend<Args, Return>(
+    fn: RemoteFunction<Args, Return> | ((args?: Args) => Promise<Return>),
+    value: Return | ((current: Return) => Return),
+): void
+export function amend<Return>(
+    selector: Pick<CacheOptions, 'tags'>,
+    value: Return | ((current: Return) => Return),
+): void
+export function amend(selector: unknown, argsOrPayload: unknown, maybePayload?: unknown): void {
+    /* Payload (value or updater) is always last: 3 args → (selector, args, payload); 2 args →
+       (selector, payload). A function payload is an updater (a local closure); anything else is
+       a replacement value — a Return that is itself a function must be wrapped by the caller
+       (ADR-0043). Both forms route through the side-swap slot: on the client it applies locally,
+       on the server the value form broadcasts and the updater form throws. */
+    const payload = maybePayload !== undefined ? maybePayload : argsOrPayload
+    const args = maybePayload !== undefined ? argsOrPayload : undefined
+    const isValue = typeof payload !== 'function'
+    amendBroadcastSlot.get()?.(selector as CacheSelector<unknown, unknown>, args, isValue, payload)
+}

package/src/lib/shared/amendBroadcastSlot.ts

@@ -0,0 +1,19 @@
+import { applyAmendLocally } from './applyAmendLocally.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { AmendApply } from './types/AmendApply.ts'
+
+/*
+The one side-swap seam for the isomorphic value form of amend (ADR-0043), mirroring
+cacheStalenessSlot. amend() routes both forms through this — the value form so the side
+decides apply-vs-broadcast, and the updater form only so the server resolver can reject
+it loudly:
+
+  - client entry (startClient): installs applyAmendLocally — set this tab's retained value.
+  - server entry (serverEntry): installs broadcastAmend — publish the keyed value to every
+    authorized reader over the reserved __abide/amend/<key> topic, and throw on an updater
+    (a closure can't broadcast).
+
+With no resolver registered the fallback is applyAmendLocally too, so isolated unit tests
+keep local behaviour without booting a runtime.
+*/
+export const amendBroadcastSlot = createResolverSlot<AmendApply>(() => applyAmendLocally)

package/src/lib/shared/applyAmendLocally.ts

@@ -0,0 +1,20 @@
+import { cache } from './cache.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+
+/*
+Applies an amend to THIS side's cache store(s) — the local half of the isomorphic
+amend value form (ADR-0043). A concrete value folds to an updater that ignores the
+current value; an updater is used as-is. Both the amendBroadcastSlot fallback and the
+client entry's resolver point here so the local-apply path can't diverge between an
+unbooted unit test and a booted client tab. The server entry installs a broadcaster
+instead (the side-swap seam), so this never runs on the server's throwaway request store.
+*/
+export function applyAmendLocally<Args, Return>(
+    selector: CacheSelector<Args, Return>,
+    args: Args | undefined,
+    isValue: boolean,
+    payload: Return | ((current: Return) => Return),
+): void {
+    const updater = isValue ? () => payload as Return : (payload as (current: Return) => Return)
+    cache.amend(selector, args, updater, isValue)
+}

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> {