@abide/abide 0.53.0 → 0.54.0

package/AGENTS.md

@@ -100,11 +100,11 @@ For tests, add `preload = ["@abide/abide/preload"]` under `[test]` in
 - **Consume forms** — the **bare call `fn(args)` is the smart read** (cached,
   coalesced, reactive; in-process during SSR and baked into the HTML for warm
   hydration — there is no `cache()` wrapper). Around it: `fn.raw(args, opts?)`
-  (raw `Response`), `fn.refresh` / `fn.invalidate` / `fn.patch` / `fn.peek` /
+  (raw `Response`), `fn.refresh` / `fn.invalidate` / `fn.amend` / `fn.peek` /
   `fn.pending` / `fn.refreshing` / `fn.error` / `fn.watch` / `fn.isError`. A
   streaming handler (`jsonl`/`sse`) makes the bare call return a
   `NamedAsyncIterable<Frame>` (the iterable IS the value; `await`-ing it is a
-  compile error; `patch` is dropped).
+  compile error; `amend` is dropped).
 - **Socket** (`src/server/sockets/<name>.ts`) — `export const x =
   socket<T>(opts?)`. `opts`: `tail` (retention depth; defaults to keeping the last
   frame), `ttl` (per-frame eviction ms), `clientPublish` (accept `pub` frames from
@@ -291,9 +291,13 @@ from the server.
 - `abide/shared/invalidate` — `invalidate(selector?, args?)`: the drop verb — drop
   matching cached reads so the next read reloads lazily. Selector grammar:
   `(fn, args)` / `(fn)` / `({ tags })` / `()`.
-- `abide/shared/patch` — `patch(fn, args?, updater)` / `patch({ tags }, updater)`:
-  mutate the retained value of matching reads in place, reactive, no network (the
-  optimistic-update / socket-frame primitive).
+- `abide/shared/amend` — `amend(fn, args?, value | updater)` / `amend({ tags }, …)`:
+  set the retained value of matching reads in place (a concrete `Return`) or transform
+  it (`updater`), reactive, no network — the optimistic-update / socket-frame primitive.
+  Isomorphic like `invalidate`/`refresh` (ADR-0043): the value form applies locally on
+  the client but from the server broadcasts the keyed value to every client reading that
+  exact call (a push-refresh — zero refetches); the updater form is client-local (a
+  closure can't broadcast). For a no-input rpc the args collapse (`fn.amend(value)`).
 - `abide/shared/refresh` — `refresh(selector?, args?)`: refetch matching reads now,
   keeping the stale value visible (`refreshing()` true) until the fresh one swaps in.
 

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # abide
 
+## 0.54.0
+
+### Minor Changes
+
+- 7cd75d7: `amend` is now isomorphic like `invalidate`/`refresh` (ADR-0043): called on the client it mutates the local cache, but called on the **server** with a concrete value it broadcasts that value to every client reading the call — a push-refresh with zero refetches.
+
+    `amend` gains a value form alongside the updater form. The last argument may be a concrete `Return` (set it) or an updater `(current) => Return` (transform it); for a no-input rpc the args collapse (`getFoo.amend(value)`), matching how `fn()` vs `fn(args)` already read. From the server, only the value form broadcasts — an updater is a closure with no wire form and throws, and the value must target a keyed remote call (a producer/`{ tags }` selector throws). Delivery is confined to clients already reading that exact call (over a per-call reserved `__abide/amend/<key>` topic), so a pushed value reaches only readers already authorized for that key; a dropped frame heals on the next reconnect refresh. The updater form and client-side `amend` are unchanged.
+
+- 42354ba: A bare `state.computed(getFoo())` over an rpc now unwraps to the resolved value, so `{foo?.field}` renders and reactively updates — the pattern the docs and examples already teach.
+
+    Previously a no-`await` `state.computed(getFoo())` was classified as an opaque `Computed<Promise>` (ADR-0023 routing), so a template read like `{foo?.messages}` read `.messages` off a Promise and always showed `undefined`, with no cache reactivity reaching it. Now `getFoo()` and `await getFoo()` inside `state.computed(...)` differ only by SSR tier and are both unwrapped value cells (ADR-0045):
+
+    - `state.computed(getFoo())` — **streaming**: SSR ships the pending branch, the client resolves after hydration.
+    - `state.computed(await getFoo())` — **blocking**: SSR waits and bakes the value into the HTML (warm hydrate, never pending).
+
+    **Breaking behavior change:** `foo` is now a reactive value cell in both forms, never a `Promise`. Code that treated the bare binding as a thenable — `state.computed(getFoo()).then(…)` or `await foo` — no longer gets the fetch promise (it gets the unwrapped value, or `undefined` while pending). For an imperative one-off, call `await getFoo()` directly (cached/coalesced); to render with an await block use `{#await getFoo()}` inline; for a genuinely opaque `Computed<Promise>` binding use an explicit thunk, `state.computed(() => getFoo())`. `{#await foo}` on a bare computed still works (it reads the async-cell subject reactively).
+
+- 7bc2bfb: Rename the cache-mutation verb `patch` → `amend`. The word "patch" collided with the HTTP `PATCH` method (`abide/server/PATCH`) and the internal DOM-tree `Patch` type; `amend` names the same intent — mutate the retained value of matching cached reads in place, reactive, no network — without the overload.
+
+    **Breaking:**
+
+    - **`abide/shared/patch` is now `abide/shared/amend`.** The standalone `patch(fn, args?, updater)` / `patch({ tags }, updater)` is now `amend(...)` with identical signatures.
+    - **The rpc selector method `fn.patch(...)` is now `fn.amend(...)`.** `fn.amend(args?, updater)` ≡ `amend(fn, args, updater)`. Still fetch-only (omitted for a streaming rpc).
+
+    Mechanical rename — no behavior change. Update imports (`abide/shared/patch` → `abide/shared/amend`) and call sites (`.patch(` → `.amend(`). The HTTP `PATCH` method export is unaffected.
+
+- 88959d7: `watch(source, handler)` now runs the handler untracked — the named source(s) are the sole triggers (ADR-0044).
+
+    Previously the two cell forms (`watch(cell, h)` / `watch([a, b], h)`) wrapped the handler in an effect that captured _every_ reactive read in the handler body, so `watch(foo, () => { id = bar.id })` silently re-ran on `bar.id` as well as `foo`. The handler is now a sink: reactive reads inside it no longer become extra triggers. This makes the cell forms match the socket and rpc forms, whose handlers already ran outside the tracking window. Only the bare `watch(() => …)` binding form still auto-tracks everything it reads. If you relied on a handler-body read re-triggering the watch, name it as a source instead (`watch([foo, bar], …)`) or use the auto-track form (`watch(() => { id = bar.id })`).
+
+### Patch Changes
+
+- dc4ddfc: normalize pre-existing format drift ([`757f142`](https://github.com/briancray/abide/commit/757f1420b4e37064da1b5048d2f5d3b1a556b6fe))
+- 11965e9: Fix the JS semantics of reactive-state mutation expressions so `{ }` code behaves like plain TypeScript.
+
+    - **Logical assignments now short-circuit.** `count ??= 5` / `x ||= v` / `x &&= v` on reactive state (`state` slot or `linked` cell) now write **only when the guard passes** — `count ??= 5` no longer fires a redundant patch (and reseed) when `count` is already non-nullish. Previously every logical assignment lowered to an unconditional write.
+    - **Postfix `x++` / `x--` now evaluates to the previous value** (and prefix `++x` to the new value), matching JS. Previously postfix returned the stepped value.
+    - As a consequence, reactive writes now evaluate to the written value, so chained assignment (`a = b = count`) through a state slot works too.
+
+    Internally, `Cell.set` and `Doc.replace` now return the written value, and the two lowering sites share `lowerCompoundAssignment` / `lowerUpdateExpression` helpers so they can't drift.
+
+- 9773885: Warn when the type program for a project can't be built, instead of silently disabling async detection.
+
+    The type-directed async lowering (deciding whether `{getFoo()}` is a promise/stream and streaming it) depends on a warm shadow program built once per project root. If that program failed to build (e.g. a broken `tsconfig`), the failure was swallowed and **every** async interpolation in the project silently degraded to plain text — a bare `{getFoo()}` shipping as the literal `[object Promise]` with no signal. It now emits a one-time `console.warn` per root naming the cause, so a build with async detection disabled is visible. Behavior is otherwise unchanged (the build still never breaks on a program-build failure).
+
+- 0d9316e: `watch(cell.foo, handler)` is now a compile error instead of a silent no-op.
+
+    abide has no per-property cells — a member access on a cell is read once as a plain value, so `watch(s.foo, handler)` subscribed to nothing and the handler silently never fired. It was only flagged by a `console.warn` (easily lost in build output). It now fails compilation with a message pointing at the corrective forms: wrap it in a thunk (`watch(() => …(s.foo))`) or watch the whole cell (`watch(s, v => …)`). A member of a cell is never itself a cell, so this can never reject a valid `watch`.
+
+- 66e5d3b: Fix a hydration desync (and the dead page it could cascade into) when a render reads a `tail`-retaining socket's `peek(socket)`. At SSR the server holds the socket's retained frame so `peek` returns it; a not-yet-connected client's `peek` returned `undefined`, so any markup derived from it (e.g. `state.computed(() => peek(refreshStatus))`) disagreed with the server HTML and tripped a hydration mismatch — which discards the server markup and cold-renders.
+
+    Sockets now warm-seed their retained frame across SSR→client like async cells do: the server records each frame read via `peek(socket)` during the render, ships it in `__SSR__.sockets` keyed by socket name, and the client seeds the socket's latest frame before mount so `peek(socket)` returns the same value the server rendered. (Contrast `cache.peek`, which withholds on the client because the server materializes no cache value — sockets carry a real server value forward, so they seed instead.)
+
+    Also hardens the hydration-desync recovery: the discard→cold-rebuild path now re-primes the async-cell and doc-state warm-seed manifests the failed hydration pass consumed, so the cold rebuild re-adopts the SSR-resolved values instead of refetching. A cold refetch left blocking `await` cells pending, and a top-level blocking read sits in no suspense region, so its `SuspenseSignal` escaped the rebuild and killed the mount ("page threw while mounting"). The rebuild now reads settled — a live page with real data, no loading flash.
+
+    No public API change.
+
 ## 0.53.0
 
 ### Minor Changes

package/README.md

@@ -53,7 +53,7 @@ One declaration branches to every surface:
 
 A **typed handler input** is what flips those surfaces on: the input type is projected to JSON Schema at build, so a plainly-typed handler auto-exposes to the CLI and — for read-only methods (`GET`/`HEAD`) — MCP with no hand-written `schemas.input` (a declared `schemas.input` adds runtime validation on top). A mutating method (`POST`/`PUT`/`PATCH`/`DELETE`) never auto-exposes to MCP; opt it in with `clients: { mcp: true }`.
 
-Consume it by importing the export. The **bare call `getMessages(args)` is the smart read** — cached, coalesced, reactive, isomorphic (in-process on the server, `fetch` in the browser). Around it sit `getMessages.raw(args, opts?)` for the raw `Response`, the mutators/probes `.refresh()` / `.invalidate()` / `.patch(...)` / `.peek()` / `.pending()` / `.refreshing()` / `.error()`, and — when the handler streams (`jsonl`/`sse`) — a bare call that returns an `AsyncIterable`.
+Consume it by importing the export. The **bare call `getMessages(args)` is the smart read** — cached, coalesced, reactive, isomorphic (in-process on the server, `fetch` in the browser). Around it sit `getMessages.raw(args, opts?)` for the raw `Response`, the mutators/probes `.refresh()` / `.invalidate()` / `.amend(...)` / `.peek()` / `.pending()` / `.refreshing()` / `.error()`, and — when the handler streams (`jsonl`/`sse`) — a bare call that returns an `AsyncIterable`.
 
 > Query, path, and form args auto-coerce from the endpoint's typed shape at build, so a numeric/boolean/date field arrives already typed — no `z.coerce` (a value that won't parse stays a string, so the schema raises an honest 422). The per-RPC `timeout` (504 on every surface) is distinct from the client transport ceiling `ABIDE_CLIENT_TIMEOUT`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.53.0",
+    "version": "0.54.0",
     "type": "module",
     "sideEffects": false,
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
@@ -60,7 +60,7 @@
         "./ui/watch": "./src/lib/ui/watch.ts",
         "./shared/pending": "./src/lib/shared/pending.ts",
         "./shared/invalidate": "./src/lib/shared/invalidate.ts",
-        "./shared/patch": "./src/lib/shared/patch.ts",
+        "./shared/amend": "./src/lib/shared/amend.ts",
         "./shared/peek": "./src/lib/shared/peek.ts",
         "./shared/refresh": "./src/lib/shared/refresh.ts",
         "./shared/refreshing": "./src/lib/shared/refreshing.ts",

package/src/checkAbide.ts

@@ -78,7 +78,7 @@ function collectByProject(cwd: string): { diagnostics: AbideDiagnostic[]; checke
         )
         /* The shadow program already holds the project's real `.ts` files (loaded so the
            components' imports/types resolve), but `collectAbideDiagnostics` only reports the
-           `.abide` shadows. Report the `.ts` files too, so a mistyped `navigate`/`url`/`patch`
+           `.abide` shadows. Report the `.ts` files too, so a mistyped `navigate`/`url`/`amend`
            call — or any type error — in an rpc handler, `app.ts`, or a `$shared` helper fails
            `abide check` instead of only surfacing under a separately-run `tsc`. */
         return [...collectAbideDiagnostics(shadow), ...collectTsDiagnostics(shadow.program)]

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

@@ -7,6 +7,7 @@ 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'
@@ -161,6 +162,30 @@ export function createUiPageRenderer({
         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) {
+            try {
+                sockets[name] = encodeRefJson(value)
+            } catch {
+                console.warn(
+                    `[abide] socket "${name}" retained frame is unserializable — its client peek() will read undefined at hydration instead of the server value.`,
+                )
+            }
+        }
+        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 +202,7 @@ export function createUiPageRenderer({
             cache: inline,
             cells: resolvedCellCells(),
             docs: docSeedSnapshots(),
+            sockets: socketTailSnapshots(),
             base: base || undefined,
             trace: formatTraceparent(store.trace),
             app: appNameSlot.name,

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

@@ -0,0 +1,13 @@
+/* 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.
+   Backed by `globalThis.__abideSockets` so an inline pre-bundle script and the framework share one
+   store — whoever runs first creates it, the other adopts the same reference (mirrors CELL_SEED). */
+const globalScope = globalThis as { __abideSockets?: Record<string, string> }
+globalScope.__abideSockets ??= {}
+
+// @documentation plumbing
+export const SOCKET_SEED: Record<string, string> = globalScope.__abideSockets

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