@abide/abide 0.52.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
@@ -176,13 +176,19 @@ Mustache `{#…}` blocks, not `<template>`. The rendered blocks are
 | `{#try}` / `{:catch}` / `{:finally}` / `{/try}` | Render error boundary. |
 | `{#snippet name(args)}…{/snippet}` | Reusable builder; called `{name(args)}`. |
 
-Async reads have no ceremony: the **bare call in an interpolation**
-(`{getMessages({ limit })}`) is the documented default — a peek that reads
-`undefined` while pending (auto-streaming on SSR), composing with `?? fallback`,
-`?.`, `{#if}`, and attributes; pair it with `.pending(...)` / `.error(...)`
-probes. `{await fn()}` is an inline read that blocks SSR until the value is in the
-HTML. `{#await}` is the opt-in for branch structure and `{:then}` narrowing — not
-the default.
+Async reads have no ceremony, and `await` is the marker that picks the mode
+(ADR-0042). A **bare call in an interpolation** (`{getMessages({ limit })}`)
+*streams*: a peek that reads `undefined` while pending (typed `T | undefined`,
+auto-streaming on SSR), composing with `?? fallback`, `?.`, `{#if}`, and
+attributes; pair it with `.pending(...)` / `.error(...)` probes. `{await fn()}`
+means *resolved*: the server blocks the flush AND the client **suspends** the
+reading region (renders nothing) until it settles, so the value is never pending
+at the read — `{(await fn()).field}` needs no `?.` and never derefs a pending
+`undefined`. A refetch never re-suspends (stale-while-revalidate); warm-seed keeps
+a hydrating read `refreshing()`, so no flash. (Consequently a no-`await` `async`
+thunk — `computed(async () => getFoo())` — is a *streaming* cell, not blocking;
+`await` is the sole blocking marker.) `{#await}` is the opt-in for branch structure
+and `{:then}` narrowing — not the default.
 
 Components are capitalised tags; the content nested in a component renders where
 it calls `{children()}` (`{#if children}{children()}{:else}…{/if}` is the
@@ -285,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.
 
@@ -444,6 +454,9 @@ Compiler-emitted; an author never imports these directly.
   read, with legible authored-scope errors.
 - `abide/ui/dom/readCell` — unified read of a `computed`/`linked`/derive reference
   (async → throwing peek, function → call, sync → `.value`).
+- `abide/ui/dom/readCellBlocking` — the blocking (`await`) variant of `readCell`: on a
+  pending cell it throws a suspense signal so the reading region withholds until the
+  value resolves, rather than reading `undefined` (client template lowering; ADR-0042).
 - `abide/ui/dom/writeCell` — unified write of a `linked` reference from an author
   assignment (async → `.set`, sync → `.value =`).
 - `abide/ui/dom/cellPending` — whether a control-flow subject is a still-loading async

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # 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
+
+- shadow narrows streaming cells to T|undefined + D7 barrier tripwire (ADR-0042 D5.2/D7) ([`034a384`](https://github.com/briancray/abide/commit/034a384bdfb5b482f818de757e10c2e2e88ac52c))
+- suspend interpolations/attributes on a pending blocking read (ADR-0042) ([`88da27c`](https://github.com/briancray/abide/commit/88da27c998666b7cca9149effd5f171f3adca8d1))
+- flip async-thunk blocking marker + emit $$readCellBlocking on the client (ADR-0042 D5/D6) ([`a3468fe`](https://github.com/briancray/abide/commit/a3468feacbb67ac9cd337ffa2e220b10af309324))
+- dormant client-suspense foundation for await-means-resolved (ADR-0042) ([`b5f6104`](https://github.com/briancray/abide/commit/b5f6104c41ea1d57d3347ae007cdb1b316a09784))
+- complete the client suspense withhold surface across all template effects (ADR-0042) ([`c5db314`](https://github.com/briancray/abide/commit/c5db314fa3e0ce18294f609be5fb43e5128970d0))
+- fa7bfed: `await` now means "resolved" for a cell and its dependents, with the client suspending to mirror the server flush barrier (ADR-0042). A blocking `await` read (`{await foo()}`, `const x = state.computed(await …)`, `{#if await …}`) reads as a resolved value on both sides: the server already blocks the flush until it settles, and the client now **withholds the reading region** (interpolation, attribute, `{#if}`/`{#each}`/`{#switch}` block) until the value resolves rather than rendering against a pending `undefined`. So `{sources.length}` on an `await` binding no longer needs `?.` and no longer crashes while pending — the region simply shows nothing until it settles, then reveals. After the first resolution a refetch never re-suspends (stale-while-revalidate); on hydrate the warm-seed keeps the read `refreshing()`, never `pending()`, so there is no flash.
+
+    **Breaking:**
+
+    - **The async modifier alone is no longer a blocking marker — `await` is.** `computed(async () => getFoo())` (an `async` thunk with no top-level `await`) now creates a **streaming** cell (ships pending, resolves on the client) instead of a blocking one. Add `await` — `computed(async () => await getFoo())` — to keep the blocking/inline-SSR behavior. `computed(await …)` and `computed(async () => await …)` are unchanged (blocking).
+    - **A streaming (no-`await`) async `computed`/`linked` now types as `T | undefined`.** Its read is honestly pending-able, so guard it with `?.`/`??` (matching the runtime). A blocking `await` binding stays `T`.
+
+    No new public API — the change is in how `await` lowers and types.
+
+### Patch Changes
+
+- document await-means-resolved (ADR-0042) ([`16ec341`](https://github.com/briancray/abide/commit/16ec341a6ea7da509919b37a1cdcc2f237e04c1c))
+- close await-suspense gaps and simplify the boundary (ADR-0042 review) ([`7f9fcbb`](https://github.com/briancray/abide/commit/7f9fcbbec862eba6da3103a6aca77d505ef6f58d))
+- type {:catch} bindings as unknown, not any (ADR-0042) ([`9a91522`](https://github.com/briancray/abide/commit/9a915229caf92914b5bcd9e5625153831783049d))
+- withhold pending blocking reads in {#await}/{#for await} subjects (ADR-0042) ([`e58b538`](https://github.com/briancray/abide/commit/e58b538f477c2bfcec654fd1a7aab65466cc956c))
+
 ## 0.52.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`.
 
@@ -124,14 +124,16 @@ async function send() {
 <section class="chat" class:empty={limit === 0} style:--rows={shown} {...rootAttrs}>
     <h1>{title}</h1>
 
-    <!-- Async reads have no ceremony: the bare call is the way. It peeks
-         `undefined` while pending, so it composes with `??` and the probes. -->
+    <!-- A bare read STREAMS: it peeks `undefined` while pending, so it composes
+         with `??` and the probes. `await` is the marker for the other mode. -->
     <p class:loading={getMessages.pending({ limit })}>
         {getMessages({ limit })?.length ?? 0} messages
         {#if getMessages.error({ limit })}<span>failed to load</span>{/if}
     </p>
 
-    <!-- `{await}` is an inline read: it blocks SSR until the value is in the HTML. -->
+    <!-- `{await}` means RESOLVED: the server blocks the flush and the client suspends
+         this region until it settles, so the value is never pending at the read (no `?.`)
+         — the region just shows nothing, then reveals. -->
     <small>today: {await countToday()}</small>
 
     <!-- `{#await}` is the explicit opt-in — a distinct pending branch and `{:then}` narrowing. -->
@@ -150,7 +152,7 @@ async function send() {
             <p>raise the limit</p>
         {/if}
     {:catch err}
-        <p>{err.message}</p>
+        <p>{err instanceof Error ? err.message : String(err)}</p>
     {:finally}
         <hr />
     {/await}
@@ -171,7 +173,7 @@ async function send() {
     {#try}
         <p>{risky()}</p>
     {:catch e}
-        <p>widget crashed: {e.message}</p>
+        <p>widget crashed: {e instanceof Error ? e.message : String(e)}</p>
     {:finally}
         <span>rendered</span>
     {/try}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.52.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",
@@ -95,6 +95,7 @@
         "./ui/dom/spreadAttrs": "./src/lib/ui/dom/spreadAttrs.ts",
         "./ui/dom/readCall": "./src/lib/ui/dom/readCall.ts",
         "./ui/dom/readCell": "./src/lib/ui/dom/readCell.ts",
+        "./ui/dom/readCellBlocking": "./src/lib/ui/dom/readCellBlocking.ts",
         "./ui/dom/writeCell": "./src/lib/ui/dom/writeCell.ts",
         "./ui/dom/cellPending": "./src/lib/ui/dom/cellPending.ts",
         "./ui/runtime/withPath": "./src/lib/ui/runtime/withPath.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)
+}