@abide/abide 0.51.0 → 0.52.0

package/src/lib/shared/createRpcServerProgram.ts

@@ -109,6 +109,20 @@ export type RpcServerProgram = {
     it.
     */
     inputSchemaForModule(modulePath: string): Record<string, unknown> | undefined
+    /*
+    The top-level statements the CLIENT rpc module must retain — reachability rooted at the endpoint
+    `opts` argument, resolved through the binder/checker rather than by scanning source text. On the
+    client an rpc is only a `remoteProxy` fetch, so the handler and every declaration/import only it
+    reaches is dead; but `opts` (schemas/cache/stream) is a LIVE expression that may reference
+    imported values and module-level consts (e.g. a `const inputSchema = z.object(...)` under
+    `schemas.input`), so those — and what THEY reach — must survive. Returns each kept statement's
+    source text in source order (imports + declarations transitively reachable from `opts`),
+    EXCLUDING the exported rpc statement itself (it becomes the `remoteProxy` line) and, naturally,
+    the rpc-helper import (`opts` never names it). An endpoint with no `opts` returns `[]` — a bare
+    `remoteProxy` needs nothing. undefined when the module or its rpc call can't be resolved, so the
+    caller falls open to the keep-the-file char-scan rewrite (ADR-0022 D2 legacy path).
+    */
+    clientKeepForModule(modulePath: string): string[] | undefined
 }
 
 /*
@@ -174,7 +188,180 @@ export function createRpcServerProgram(cwd: string, rpcDir: string): RpcServerPr
         inputSchemaForModule(modulePath) {
             return query(modulePath, (call) => inputArgsJsonSchema(checker, call.node))
         },
+        clientKeepForModule(modulePath) {
+            /* Needs the SourceFile alongside the call (statement walk), so it resolves both itself
+               rather than going through `query` (which yields only the call). Same fail-open
+               contract: an unresolved module / any checker throw yields undefined. */
+            try {
+                const sourceFile = program.getSourceFile(modulePath)
+                if (sourceFile === undefined) {
+                    return undefined
+                }
+                const call = resolveRpcCall(checker, sourceFile)
+                if (call === undefined) {
+                    return undefined
+                }
+                return clientKeepStatements(checker, sourceFile, call.node)
+            } catch {
+                return undefined
+            }
+        },
+    }
+}
+
+/*
+The top-level statements the client rpc module retains, rooted at the endpoint `opts` argument
+(ADR-0022 addendum). Builds a reachability graph over the module's top-level bindings — each binding
+symbol → its declaring statement, plus which top-level symbols each statement references — then
+marks every statement reachable from `opts` and returns the marked ones' source text in source
+order. The exported rpc statement is excluded (it becomes the `remoteProxy` line); everything the
+handler alone reaches is simply never marked, so it drops out.
+*/
+function clientKeepStatements(
+    checker: ts.TypeChecker,
+    sourceFile: ts.SourceFile,
+    call: ts.CallExpression,
+): string[] {
+    const opts = call.arguments[1]
+    // No opts → the client module needs nothing but the bare remoteProxy call.
+    if (opts === undefined) {
+        return []
+    }
+    // The exported rpc statement becomes the remoteProxy line, so it is never a retained statement.
+    const exportStatement = enclosingTopLevelStatement(call, sourceFile)
+    // Every top-level binding symbol → the statement that declares it (the export statement's own
+    // bindings excluded so a self-reference can't re-admit it).
+    const declaringStatement = new Map<ts.Symbol, ts.Statement>()
+    for (const statement of sourceFile.statements) {
+        if (statement === exportStatement) {
+            continue
+        }
+        for (const symbol of topLevelBindingSymbols(checker, statement)) {
+            declaringStatement.set(symbol, statement)
+        }
+    }
+    // Mark from opts outward: a statement is kept once any of its bindings is referenced by opts or
+    // by an already-kept statement (transitive closure via the work queue).
+    const kept = new Set<ts.Statement>()
+    const queue: ts.Node[] = [opts]
+    while (queue.length > 0) {
+        const node = queue.pop() as ts.Node
+        for (const symbol of referencedTopLevelSymbols(checker, node, declaringStatement)) {
+            const statement = declaringStatement.get(symbol)
+            if (statement !== undefined && !kept.has(statement)) {
+                kept.add(statement)
+                queue.push(statement)
+            }
+        }
+    }
+    const texts: string[] = []
+    for (const statement of sourceFile.statements) {
+        if (kept.has(statement)) {
+            texts.push(statement.getText(sourceFile))
+        }
+    }
+    return texts
+}
+
+/* The top-level statement enclosing `node` — walk parents until the one whose parent is the source
+   file. */
+function enclosingTopLevelStatement(node: ts.Node, sourceFile: ts.SourceFile): ts.Statement {
+    let current: ts.Node = node
+    while (current.parent !== undefined && current.parent !== sourceFile) {
+        current = current.parent
+    }
+    return current as ts.Statement
+}
+
+/*
+The binding symbols a top-level statement introduces — an import's clause names (default /
+namespace / each named element), a variable statement's declaration names (destructuring patterns
+walked to their leaves), and a function/class declaration's name. A statement that binds nothing
+(a bare side-effect `import './x'`, an expression statement) contributes no symbol and so is never
+reachable from opts — exactly the server-only setup the client drops.
+*/
+function topLevelBindingSymbols(checker: ts.TypeChecker, statement: ts.Statement): ts.Symbol[] {
+    const names: ts.Node[] = []
+    if (ts.isImportDeclaration(statement)) {
+        const clause = statement.importClause
+        if (clause?.name !== undefined) {
+            names.push(clause.name)
+        }
+        const bindings = clause?.namedBindings
+        if (bindings !== undefined) {
+            if (ts.isNamespaceImport(bindings)) {
+                names.push(bindings.name)
+            } else {
+                for (const element of bindings.elements) {
+                    names.push(element.name)
+                }
+            }
+        }
+    } else if (ts.isVariableStatement(statement)) {
+        for (const declaration of statement.declarationList.declarations) {
+            collectBindingNames(declaration.name, names)
+        }
+    } else if (
+        (ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
+        statement.name !== undefined
+    ) {
+        names.push(statement.name)
+    }
+    const symbols: ts.Symbol[] = []
+    for (const name of names) {
+        const symbol = checker.getSymbolAtLocation(name)
+        if (symbol !== undefined) {
+            symbols.push(symbol)
+        }
+    }
+    return symbols
+}
+
+/* The leaf identifiers of a binding name — a plain identifier is itself; a destructuring pattern
+   (`{ a, b: { c } }`, `[x, ...rest]`) descends to each bound identifier. */
+function collectBindingNames(name: ts.BindingName, out: ts.Node[]): void {
+    if (ts.isIdentifier(name)) {
+        out.push(name)
+        return
+    }
+    for (const element of name.elements) {
+        if (ts.isBindingElement(element)) {
+            collectBindingNames(element.name, out)
+        }
+    }
+}
+
+/*
+The top-level binding symbols referenced within `node` — every identifier in the subtree whose
+resolved symbol is a known top-level binding. An import alias resolves to the same local symbol at
+its use site and its declaration, so uses match declarations; a property name (`obj.map`) resolves
+to a property symbol, not a top-level one, so it can't false-match. Over-inclusion is safe (it only
+keeps more), so a bare identifier scan needs no scope analysis.
+*/
+function referencedTopLevelSymbols(
+    checker: ts.TypeChecker,
+    node: ts.Node,
+    declaringStatement: Map<ts.Symbol, ts.Statement>,
+): ts.Symbol[] {
+    const found: ts.Symbol[] = []
+    const consider = (symbol: ts.Symbol | undefined): void => {
+        if (symbol !== undefined && declaringStatement.has(symbol)) {
+            found.push(symbol)
+        }
+    }
+    const visit = (current: ts.Node): void => {
+        // A shorthand `{ schemas }` resolves to the object PROPERTY symbol at its location, not the
+        // referenced binding — so read the value symbol explicitly, else the used import is missed
+        // (the one unsafe direction: a dropped-but-needed statement).
+        if (ts.isShorthandPropertyAssignment(current)) {
+            consider(checker.getShorthandAssignmentValueSymbol(current))
+        } else if (ts.isIdentifier(current)) {
+            consider(checker.getSymbolAtLocation(current))
+        }
+        ts.forEachChild(current, visit)
     }
+    visit(node)
+    return found
 }
 
 type ResolvedRpcCall = {

package/src/lib/shared/docSnapshotsSlot.ts

@@ -0,0 +1,13 @@
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { DocSnapshots } from './types/DocSnapshots.ts'
+
+/*
+The active doc-snapshot slot — mirrors `resolvedCellsSlot`. The server entry installs an ALS-backed
+resolver (a fresh list per request, so concurrent SSR renders never mix their doc seeds); with no
+resolver registered a single fallback list is created lazily so isolated tests work without booting
+the runtime. `createScope` pushes a `{ id, take }` for each rendered scope server-side; the page
+renderer reads it at render-return to stamp `__SSR__.docs`.
+*/
+export const docSnapshotsSlot = createResolverSlot<DocSnapshots>(() => ({
+    entries: [],
+}))

package/src/lib/shared/invalidate.ts

@@ -0,0 +1,39 @@
+import { cacheStalenessSlot } from './cacheStalenessSlot.ts'
+import { isAsyncCell } from './isAsyncCell.ts'
+import type { AsyncComputed } from './types/AsyncComputed.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+
+/*
+Drop every cached read matching the selector so the next read reloads it lazily —
+the drop verb, distinct from refresh (which refetches now, keeping the stale value
+visible). A mounted RETAINED reader revalidates stale-in-place under invalidate too
+(its retain+invalidation policy keeps the value and refetches); a background /
+non-retained entry (an explicit `cache()`, a producer, a reader-less entry) is
+dropped and refetches only when re-read. Follows the shared selector grammar:
+
+  invalidate(getFoo, args)   → that exact call
+  invalidate(getFoo)         → every args-variant of that rpc
+  invalidate({ tags })       → every entry sharing a tag
+  invalidate()               → every entry
+
+Instance sugar `getFoo.invalidate(args?)` ≡ `invalidate(getFoo, args?)`.
+
+Isomorphic (ADR-0041): applied LOCALLY on the client, and on the SERVER it
+broadcasts to every connected client (each applies the local drop). The side-swap
+rides the cacheStalenessSlot resolver — this source is byte-identical on both
+sides. `invalidate(asyncCell)` aliases `cell.refresh()` (a cell has no droppable
+entry; its staleness is re-running its seed), matching `refresh(cell)`.
+*/
+// @documentation cache
+export function invalidate<Args, Return>(
+    arg?: CacheSelector<Args, Return> | AsyncComputed<unknown>,
+    args?: Args,
+): void {
+    /* An async cell re-invokes its own seed (`invalidate(cell)` ≡ `cell.refresh()`). */
+    if (isAsyncCell(arg)) {
+        arg.refresh()
+        return
+    }
+    /* Side-swap: the client entry applies locally; the server entry broadcasts. */
+    cacheStalenessSlot.get()?.('invalidate', arg as CacheSelector<Args, Return>, args)
+}

package/src/lib/shared/matcherFromEnvelope.ts

@@ -0,0 +1,31 @@
+import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
+import { setsIntersect } from './setsIntersect.ts'
+import { toTagSet } from './toTagSet.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheStalenessFrame } from './types/CacheStalenessFrame.ts'
+
+/*
+Rebuilds the entry predicate from a decoded staleness envelope (ADR-0041) — the
+decode half of serializeSelector, driving the SAME store loop a local apply does
+(cache.invalidateMatching / cache.refreshMatching). The three modes are
+selectorMatcher's three real branches with the `args !== undefined` discriminant
+replaced by the explicit `mode`, reusing keyMatchesPrefix/toTagSet so a decoded
+predicate can't disagree with what a local selector would have matched:
+
+  key    → exactly that call's entry (args already the canonical string the read
+           path keyed with, so it re-matches by equality — no ref-json codec crosses)
+  prefix → every args-variant of that fn (method+url prefix)
+  tags   → any entry sharing one of the requested tags
+*/
+export function matcherFromEnvelope(frame: CacheStalenessFrame): (entry: CacheEntry) => boolean {
+    if (frame.mode === 'key') {
+        const key = frame.match
+        return (entry) => entry.key === key
+    }
+    if (frame.mode === 'prefix') {
+        const prefix = frame.match
+        return (entry) => keyMatchesPrefix(entry.key, prefix)
+    }
+    const requestedTags = toTagSet(frame.tags)
+    return (entry) => entry.tags !== undefined && setsIntersect(requestedTags, entry.tags)
+}

package/src/lib/shared/prepareRpcModule.ts

@@ -118,7 +118,6 @@ export function prepareRpcModule(
         remoteProxy reads only streaming/cache/stream off the opts and ignores the rest.
         */
         rewriteForClient(url: string): string {
-            const callHead = `${stripped.slice(0, site.callStart)}${REMOTE_PROXY_GLOBAL}(${JSON.stringify(method)}, ${JSON.stringify(url)}`
             const opts = argParts[1]
             /* Build-injected CLIENT opts: `streaming` (build-derived from the elided handler body)
                and the `outputWirePlan` (the handler's structured success fields → the client revives
@@ -142,8 +141,28 @@ export function prepareRpcModule(
                         ? `, { ${injectedText} }`
                         : `, { ${injectedText}, ...(${opts}) }`
             }
-            /* Keep everything from the call's closing paren onward (same slicing discipline as
-               rewriteForServer) so any trailing content after the call survives. */
+            const remoteCall = `${REMOTE_PROXY_GLOBAL}(${JSON.stringify(method)}, ${JSON.stringify(url)}${argsText})`
+            /*
+            Minimal emit (ADR-0022 addendum): the warm program resolved which top-level statements
+            the live `opts` actually reaches, so emit ONLY those plus the `remoteProxy` export. The
+            handler and every declaration/import only it used are never emitted — nothing server-side
+            is loaded, tree-shaken, or flagged, matching "the client is only ever a fetch". An empty
+            plan (no opts, or opts references nothing top-level) emits the bare call alone.
+            */
+            const clientKeep = stamps.clientKeep
+            if (clientKeep !== undefined) {
+                const exportLine = `export const ${site.exportName} = ${remoteCall}`
+                return clientKeep.length > 0
+                    ? `${clientKeep.join('\n')}\n${exportLine}\n`
+                    : `${exportLine}\n`
+            }
+            /*
+            Fallback (no warm program): keep the real module, swap the METHOD( call for the
+            remoteProxy( call, and elide the handler argument — leaning on the bundler's DCE to drop
+            the dead server imports. `stripped.slice(0, site.callStart)` keeps the imports + the
+            `export const <name> = ` head; `stripped.slice(site.parenEnd)` keeps any trailing content.
+            */
+            const callHead = `${stripped.slice(0, site.callStart)}${REMOTE_PROXY_GLOBAL}(${JSON.stringify(method)}, ${JSON.stringify(url)}`
             return `${callHead}${argsText}${stripped.slice(site.parenEnd)}`
         },
     }

package/src/lib/shared/refresh.ts

@@ -1,4 +1,4 @@
-import { cache } from './cache.ts'
+import { cacheStalenessSlot } from './cacheStalenessSlot.ts'
 import { isAsyncCell } from './isAsyncCell.ts'
 import type { AsyncComputed } from './types/AsyncComputed.ts'
 import type { CacheSelector } from './types/CacheSelector.ts'
@@ -17,6 +17,12 @@ pending blank. Follows the shared selector grammar:
 
 Instance sugar `getFoo.refresh(args?)` ≡ `refresh(getFoo, args?)`. Reports, never
 retains a spinner — pair with `refreshing()` to surface the in-flight reload.
+
+Isomorphic (ADR-0041): applied LOCALLY on the client, and on the SERVER it now
+broadcasts to every connected client (each refetches eagerly) instead of mutating a
+throwaway request store that reached no browser. The side-swap rides the
+cacheStalenessSlot resolver — this source is byte-identical on both sides. The
+paired drop verb is `invalidate`.
 */
 // @documentation cache
 export function refresh<Args, Return>(
@@ -28,5 +34,6 @@ export function refresh<Args, Return>(
         arg.refresh()
         return
     }
-    cache.refresh(arg as CacheSelector<Args, Return>, args)
+    /* Side-swap: the client entry applies locally; the server entry broadcasts. */
+    cacheStalenessSlot.get()?.('refresh', arg as CacheSelector<Args, Return>, args)
 }

package/src/lib/shared/selectorMatcher.ts

@@ -1,5 +1,6 @@
 import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
+import { setsIntersect } from './setsIntersect.ts'
 import { toTagSet } from './toTagSet.ts'
 import type { CacheEntry } from './types/CacheEntry.ts'
 import type { CacheSelector } from './types/CacheSelector.ts'
@@ -50,19 +51,5 @@ export function selectorMatcher<Args, Return>(
         return () => false
     }
     const requestedTags = toTagSet(arg.tags)
-    return (entry) => entry.tags !== undefined && intersects(entry.tags, requestedTags)
-}
-
-/*
-True when an entry's tags and the requested tags overlap on any tag. A plain
-for-of over the Set rather than .values().some() — Iterator Helpers are too new
-for this module's browser baseline (see producerKey).
-*/
-function intersects(entryTags: Set<string>, requestedTags: Set<string>): boolean {
-    for (const tag of requestedTags) {
-        if (entryTags.has(tag)) {
-            return true
-        }
-    }
-    return false
+    return (entry) => entry.tags !== undefined && setsIntersect(requestedTags, entry.tags)
 }

package/src/lib/shared/serializeSelector.ts

@@ -0,0 +1,69 @@
+import { keyForRemoteCall } from './keyForRemoteCall.ts'
+import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
+import { REMOTE_FUNCTION } from './REMOTE_FUNCTION.ts'
+import { toTagSet } from './toTagSet.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+import type { CacheStalenessFrame } from './types/CacheStalenessFrame.ts'
+import type { RawRemoteFunction } from './types/RawRemoteFunction.ts'
+
+/*
+Encodes a CacheSelector into the cross-client staleness envelope (ADR-0041) — the
+single authoring site for the on-wire selector, reusing the same encoders the read
+path keys with (keyForRemoteCall / keyPrefixForRemote) so it can never drift from
+selectorMatcher. The three real branches map 1:1 onto the envelope's `mode`:
+
+  fn + args → { mode: 'key',    match: keyForRemoteCall(method, url, args) }
+  fn        → { mode: 'prefix', match: keyPrefixForRemote(method, url) }
+  { tags }  → { mode: 'tags',   tags }
+
+A producer/closure selector mints a per-process ref id (selectorPrefix) that no
+other client shares, and a bare/undefined match-all would nuke every client's whole
+cache — both are NOT cross-client serializable, so they THROW here rather than
+broadcast. The caller (the server broadcaster) surfaces the throw as a programming
+error at the mutation site.
+*/
+export function serializeSelector<Args, Return>(
+    op: CacheStalenessFrame['op'],
+    arg?: CacheSelector<Args, Return>,
+    args?: Args,
+): CacheStalenessFrame {
+    if (arg === undefined) {
+        throw new Error(
+            `[abide] ${op}(): a bare match-all selector cannot broadcast across clients — it would drop every client's whole cache. Pass a remote function or { tags }.`,
+        )
+    }
+    if (typeof arg === 'function') {
+        /* Only a remote function carries wire identity (method+url, stable across clients);
+           a plain producer's key is a per-process ref id that no other client shares. */
+        if (!(REMOTE_FUNCTION in arg)) {
+            throw new Error(
+                `[abide] ${op}(): a producer/closure selector is not cross-client serializable (its key is a per-process reference id). Broadcast a remote function or { tags }.`,
+            )
+        }
+        const remote = arg as RawRemoteFunction<Args>
+        if (args === undefined) {
+            return {
+                op,
+                mode: 'prefix',
+                match: keyPrefixForRemote(remote.method, remote.url),
+                tags: [],
+            }
+        }
+        return {
+            op,
+            mode: 'key',
+            match: keyForRemoteCall(remote.method, remote.url, args),
+            tags: [],
+        }
+    }
+    /* Reject an empty tag set too, not just an absent `tags`: an empty-array selector
+       matches nothing locally, so broadcasting it would fan a match-nothing frame out to
+       every peer (a wasted store scan). Compute the set once and reuse it. */
+    const tags = arg.tags === undefined ? undefined : toTagSet(arg.tags)
+    if (tags === undefined || tags.size === 0) {
+        throw new Error(
+            `[abide] ${op}(): a { tags } selector must list at least one tag to broadcast.`,
+        )
+    }
+    return { op, mode: 'tags', match: '', tags: [...tags] }
+}

package/src/lib/shared/setsIntersect.ts

@@ -0,0 +1,15 @@
+/*
+True when two sets share at least one member — a plain for-of over the first set
+rather than `.values().some()` (Iterator Helpers are too new for this module's
+browser baseline; see producerKey). Pass the smaller set first. Shared by
+selectorMatcher (local selectors) and matcherFromEnvelope (wire-decoded frames) so
+the two tag predicates can't drift.
+*/
+export function setsIntersect<T>(a: Set<T>, b: Set<T>): boolean {
+    for (const value of a) {
+        if (b.has(value)) {
+            return true
+        }
+    }
+    return false
+}

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

@@ -0,0 +1,13 @@
+import type { CacheSelector } from './CacheSelector.ts'
+
+/*
+The side-swappable staleness applier stored in cacheStalenessSlot (ADR-0041): given
+a verb and a (non-async-cell) selector, either apply it locally (client / fallback)
+or broadcast it (server). The async-cell short-circuit is handled in invalidate() /
+refresh() before the slot, so this only ever sees a real CacheSelector.
+*/
+export type CacheStalenessApply = <Args, Return>(
+    op: 'invalidate' | 'refresh',
+    selector: CacheSelector<Args, Return>,
+    args?: Args,
+) => void

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

@@ -0,0 +1,24 @@
+/*
+The on-wire envelope for a cross-client staleness signal (ADR-0041). A single
+monomorphic shape — every field always present so the JIT keeps it a stable
+hidden class — carried as the `message` of a standard socket frame on the
+reserved `__abide/cache` topic.
+
+  op    — which local verb each subscriber runs: drop (`invalidate`) or refetch
+          (`refresh`).
+  mode  — how `match`/`tags` select entries, mapping 1:1 onto selectorMatcher's
+          three real branches: an exact call key, a fn key prefix, or a tag set.
+  match — the exact cache key (`mode: 'key'`), the key prefix (`mode: 'prefix'`),
+          or `''` (`mode: 'tags'`, unused).
+  tags  — the requested tag list (`mode: 'tags'`), or `[]` otherwise.
+
+Producer/closure selectors and the bare match-all form are NOT expressible here
+— they are rejected at encode time (serializeSelector), so this envelope only
+ever carries a cross-client-stable selector.
+*/
+export interface CacheStalenessFrame {
+    op: 'invalidate' | 'refresh'
+    mode: 'key' | 'prefix' | 'tags'
+    match: string
+    tags: string[]
+}

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

@@ -0,0 +1,12 @@
+/*
+The per-request list of reactive-document snapshots captured during an SSR render, each keyed by
+its scope's serialization-stable render-path id. A rendered scope registers a lazy `take` at
+creation; the page renderer calls it at render-return (after the synchronous `state` inits have
+run), encodes the non-empty result (ref-json) into `__SSR__.docs`, and the client seeds it so a
+plain `state(initial)` — a uuid, a timestamp — hydrates to the SERVER's value instead of
+recomputing a divergent one. Sibling of `ResolvedCells` (async-cell values); this holds the
+synchronous document state, taken lazily rather than at settle.
+*/
+export type DocSnapshots = {
+    entries: { id: string; take: () => unknown }[]
+}

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

@@ -63,17 +63,20 @@ export type RemoteFunction<
        the rpc's own spec. */
     readonly isError: RpcErrorGuard<Errors>
     /* Pre-bound selector sugar: `fn.pending(args?)` ≡ `pending(fn, args?)`, and likewise for
-       refreshing / refresh / peek — the rpc is the leading selector, bound in. The argument is
-       this rpc's typed `Args` (the by-args refinement); tags / cross-cutting selection stay on
-       the globals. The bare call `fn(args)` IS the cached read (was `fn.cache`) — all cache
-       policy lives on the definition, so there is no second options argument, and
-       `refresh(args?)` refetches keeping the stale value visible (was `invalidate`, which
-       dropped). `peek(args?)` reads the retained value synchronously (a streaming rpc peeks its
-       latest frame). `patch` is fetch-only, so it is omitted for a streaming rpc (a stream isn't
-       a memoized value) via the intersection below. */
+       refreshing / refresh / invalidate / peek — the rpc is the leading selector, bound in. The
+       argument is this rpc's typed `Args` (the by-args refinement); tags / cross-cutting selection
+       stay on the globals. The bare call `fn(args)` IS the cached read (was `fn.cache`) — all cache
+       policy lives on the definition, so there is no second options argument. The two staleness
+       verbs are distinct again (ADR-0041): `invalidate(args?)` DROPS the entry so the next read
+       reloads lazily, while `refresh(args?)` REFETCHES now keeping the stale value visible — both
+       apply locally on the client and broadcast to every connected client from the server.
+       `peek(args?)` reads the retained value synchronously (a streaming rpc peeks its latest
+       frame). `patch` is fetch-only, so it is omitted for a streaming rpc (a stream isn't a
+       memoized value) via the intersection below. */
     pending(args?: Args): boolean
     refreshing(args?: Args): boolean
     refresh(args?: Args): void
+    invalidate(args?: Args): void
     peek(args?: Args): ([Return] extends [AsyncIterable<infer Frame>] ? Frame : Return) | undefined
     /* This rpc's last error, typed off `Errors` (a discriminated union already narrowed on
        `.kind`/`.data`). `args` scopes to one call; omitted aggregates the most-recent across

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

@@ -12,6 +12,14 @@ unresolvable node), and the rewrite falls open to its char-scan / today's behavi
 before. `streaming` overrides the char-scan streaming verdict; the rest are stamped as server opts
 (`coercion`→`coerce`, `inputSchema`→`inputJsonSchema`, `outputSchema`→`outputJsonSchema`,
 `errorSchemas`→`errorJsonSchemas`) or the client opt (`outputWirePlan`).
+
+`clientKeep` is the reachability plan for the CLIENT rewrite: the source text of the top-level
+statements the emitted client module must retain (imports + declarations transitively reachable from
+the endpoint `opts`), computed through the binder/checker. Present → `rewriteForClient` emits a
+MINIMAL module (`remoteProxy(opts)` plus only those statements), so the handler and every
+declaration/import only it reaches is never emitted — nothing server-side is loaded, tree-shaken, or
+flagged (superseding ADR-0022 D2/D3's "keep the file, trust DCE"). Absent (no warm program /
+unresolvable rpc call) falls open to the keep-the-file char-scan rewrite.
 */
 export type RpcBuildStamps = {
     streaming?: boolean
@@ -20,4 +28,5 @@ export type RpcBuildStamps = {
     outputSchema?: Record<string, unknown>
     errorSchemas?: ErrorJsonSchemas
     outputWirePlan?: OutputWirePlan
+    clientKeep?: string[]
 }

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

@@ -22,4 +22,9 @@ export type SsrPayload = SsrBootState & {
     /* Async-cell values that resolved during SSR, keyed by render-path id → ref-json string.
        `startClient` seeds these into `CELL_SEED`; a hydrating cell reads its key to warm-hydrate. */
     cells?: Record<string, string>
+    /* Reactive-document snapshots that carried synchronous `state` during SSR, keyed by render-path
+       id → ref-json string. `startClient` seeds these into `DOC_SEED`; a hydrating scope's first
+       write to each slot adopts the server value, so a plain `state(uuid())`/`state(Date.now())`
+       keeps the SSR value instead of recomputing a divergent one. */
+    docs?: Record<string, string>
 }

package/src/lib/test/createTestApp.ts

@@ -26,7 +26,9 @@ import { shell } from '../../_virtual/shell.ts'
 // @ts-expect-error virtual module resolved by abideResolverPlugin
 import { sockets } from '../../_virtual/sockets.ts'
 import { rpcRegistry } from '../server/rpc/rpcRegistry.ts'
+import { broadcastCacheStaleness } from '../server/runtime/cacheStalenessBroadcaster.ts'
 import { createServer } from '../server/runtime/createServer.ts'
+import { pageRenderSlot } from '../server/runtime/pageRenderSlot.ts'
 import { ensureRegistriesLoaded } from '../server/runtime/registryManifests.ts'
 import { requestContext } from '../server/runtime/requestContext.ts'
 import { resolvePageSnapshot } from '../server/runtime/resolvePageSnapshot.ts'
@@ -34,9 +36,11 @@ import { serverSlot } from '../server/runtime/serverSlot.ts'
 import { baseSlot } from '../shared/baseSlot.ts'
 import { buildRpcProxy } from '../shared/buildRpcProxy.ts'
 import { buildRpcRequest } from '../shared/buildRpcRequest.ts'
+import { cacheStalenessSlot } from '../shared/cacheStalenessSlot.ts'
 import { cacheStoreSlot } from '../shared/cacheStoreSlot.ts'
 import { commandNameForUrl } from '../shared/commandNameForUrl.ts'
 import { createCacheStore } from '../shared/createCacheStore.ts'
+import { docSnapshotsSlot } from '../shared/docSnapshotsSlot.ts'
 import { HEALTH_PATH } from '../shared/HEALTH_PATH.ts'
 import { pageSlot } from '../shared/pageSlot.ts'
 import { pendingAsyncCellsSlot } from '../shared/pendingAsyncCellsSlot.ts'
@@ -107,7 +111,10 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsResolver: pendingAsyncCellsSlot.resolver,
         resolvedCellsResolver: resolvedCellsSlot.resolver,
         streamedCellsResolver: streamedCellsSlot.resolver,
+        docSnapshotsResolver: docSnapshotsSlot.resolver,
         activeServer: serverSlot.active,
+        pageRender: pageRenderSlot.render,
+        stalenessResolver: cacheStalenessSlot.resolver,
     }
 
     const sharedStore = createCacheStore()
@@ -122,7 +129,12 @@ export async function createTestApp(): Promise<TestApp> {
     const sharedStreamedCells = { entries: [] }
     streamedCellsSlot.resolver = () =>
         requestContext.getStore()?.streamedCells ?? sharedStreamedCells
+    const sharedDocSnapshots = { entries: [] }
+    docSnapshotsSlot.resolver = () => requestContext.getStore()?.docSnapshots ?? sharedDocSnapshots
     pageSlot.resolver = resolvePageSnapshot
+    /* Server-side invalidate()/refresh() broadcast over the reserved socket (ADR-0041),
+       exactly as serverEntry installs it. */
+    cacheStalenessSlot.resolver = () => broadcastCacheStaleness
 
     /* Eager env validation, exactly as serverEntry: a top-level env(schema) in
        src/server/config.ts fails the boot loudly here rather than lazily. No-op
@@ -206,7 +218,10 @@ export async function createTestApp(): Promise<TestApp> {
         pendingAsyncCellsSlot.resolver = previous.pendingAsyncCellsResolver
         resolvedCellsSlot.resolver = previous.resolvedCellsResolver
         streamedCellsSlot.resolver = previous.streamedCellsResolver
+        docSnapshotsSlot.resolver = previous.docSnapshotsResolver
         serverSlot.active = previous.activeServer
+        pageRenderSlot.render = previous.pageRender
+        cacheStalenessSlot.resolver = previous.stalenessResolver
     }
 
     return {