@abide/abide 0.51.0 → 0.52.0

package/src/lib/cli/renderCliCompletions.ts

@@ -0,0 +1,56 @@
+/*
+The shell-completion script for a standalone CLI binary. Emits a thin
+wrapper that shells back into the binary's `/completions --query` on every
+tab — so the candidate list always reflects the manifest baked into the
+running binary (rebuild the binary and completion updates, no re-source).
+Returns undefined for an unrecognised shell so the caller can error. The
+`\0` sentinel below is the program name, substituted once here rather than
+threaded through every heredoc line.
+*/
+export function renderCliCompletions(
+    programName: string,
+    shell: string | undefined,
+): string | undefined {
+    const script = SCRIPTS[shell ?? '']
+    if (!script) {
+        return undefined
+    }
+    return script.replaceAll('\0', programName)
+}
+
+/*
+One wrapper per shell. Each forwards the tokens typed so far — the cursor
+index and the command word (`words[1]`) — to `\0 /completions --query`,
+then lets the shell filter the newline-separated candidates by the current
+prefix. `2>/dev/null` keeps a connection error off the completion output.
+The index is normalised to bash's 0-based `COMP_CWORD` convention (program =
+0, first positional = 1) that `completeCli` expects: zsh's `$CURRENT` is
+1-based (`words[1]` is the program), so it forwards `CURRENT - 1`.
+*/
+const SCRIPTS: Record<string, string> = {
+    bash: `_\0_complete() {
+  local cur cmd candidates
+  cur="\${COMP_WORDS[COMP_CWORD]}"
+  cmd="\${COMP_WORDS[1]}"
+  candidates="$(\0 /completions --query "\${COMP_CWORD}" "\${cmd}" 2>/dev/null)"
+  COMPREPLY=( $(compgen -W "\${candidates}" -- "\${cur}") )
+}
+complete -F _\0_complete \0
+`,
+    zsh: `#compdef \0
+_\0() {
+  local cmd="\${words[2]}"
+  local -a candidates
+  candidates=("\${(@f)$(\0 /completions --query "\$((CURRENT - 1))" "\${cmd}" 2>/dev/null)}")
+  compadd -- "\${candidates[@]}"
+}
+compdef _\0 \0
+`,
+    fish: `function __\0_complete
+  set -l words (commandline -opc)
+  set -l cword (count $words)
+  \0 /completions --query (math $cword) $words[2] 2>/dev/null
+end
+complete -c \0 -f -a '(__\0_complete)'
+`,
+}

package/src/lib/cli/runCli.ts

@@ -1,12 +1,14 @@
 import { clearLastConnection } from '../shared/clearLastConnection.ts'
 import { loadEnvFromDataDir } from '../shared/loadEnvFromDataDir.ts'
 import { messageFromError } from '../shared/messageFromError.ts'
+import { completeCli } from './completeCli.ts'
 import { connectToServer } from './connectToServer.ts'
 import { dispatchCommand } from './dispatchCommand.ts'
 import { loadEnvFromBinaryDir } from './loadEnvFromBinaryDir.ts'
 import { printCommandHelp } from './printCommandHelp.ts'
 import { printTopLevelHelp } from './printTopLevelHelp.ts'
 import { printTrimmed } from './printTrimmed.ts'
+import { renderCliCompletions } from './renderCliCompletions.ts'
 import { resolveCliTarget } from './resolveCliTarget.ts'
 import { runSession } from './runSession.ts'
 import { startLocalInstance } from './startLocalInstance.ts'
@@ -51,6 +53,7 @@ a bare word runs a command:
   /connect <url>                  → connect to a remote server, open a session
   /start                          → boot a local instance, open a session
   /disconnect                     → forget the saved connection, exit
+  /completions <shell>            → print a bash/zsh/fish completion script (local, no connection)
   <cmd> [--flags]                 → one-shot RPC against the resumed target
 
 The connection rpcs are `/`-prefixed only — no bare aliases — so a bare word is
@@ -93,6 +96,30 @@ export async function runCli({
         return 0
     }
 
+    // Shell completion: `--query` answers a live tab (candidates from the baked
+    // manifest, no server needed), otherwise emit the wrapper script for a shell.
+    if (first === '/completions') {
+        if (argv[1] === '--query') {
+            const cword = Number(argv[2] ?? '1')
+            const command = argv[3]
+            for (const candidate of completeCli(
+                manifest,
+                Number.isNaN(cword) ? 1 : cword,
+                command,
+            )) {
+                console.log(candidate)
+            }
+            return 0
+        }
+        const script = renderCliCompletions(programName, argv[1])
+        if (!script) {
+            console.error(`${programName}: /completions requires a shell — bash, zsh, or fish`)
+            return 1
+        }
+        process.stdout.write(script)
+        return 0
+    }
+
     // No command: interactive session on a TTY, help otherwise (scripts/pipes).
     if (!first) {
         if (!process.stdin.isTTY) {

package/src/lib/server/render.ts

@@ -0,0 +1,70 @@
+import { basePath } from '../shared/basePath.ts'
+import { forwardHeaders } from '../shared/forwardHeaders.ts'
+import type { PageRoutes, PathParams } from '../shared/url.ts'
+import { url } from '../shared/url.ts'
+import { getActiveServer } from './runtime/getActiveServer.ts'
+import { pageRenderSlot } from './runtime/pageRenderSlot.ts'
+import { requestContext } from './runtime/requestContext.ts'
+
+/* Query args carried onto the rendered URL — the same shape url() appends. */
+type Query = Record<string, string | number | boolean | undefined>
+
+/*
+Renders a page route to its HTML string, server-side, from anywhere in a request
+scope — the same pipeline (app.html shell, layout chain, params, inline rpc
+reads) an HTTP GET of that URL would run, so the page stays directly linkable and
+its emailed form is one call away. Argument shape mirrors url()/navigate: a route
+literal with `[name]` segments takes its params first (`render('/emails/[id]',
+{ id })`), then optional query; a paramless route takes optional query directly.
+
+The page renders in a fresh nested request scope (like an in-process rpc call), so
+its own `cache()`/rpc reads resolve exactly as under a live request; app.handle
+middleware and gzip are not applied. A page whose content is baked inline —
+top-level `await` or a blocking `{#await expr then value}` — returns complete,
+self-contained HTML. A page with streaming `{#await}` blocks returns the shell
+plus trailing `<abide-resolve>` fragments a browser reassembles client-side, so
+for a no-JS surface (email) use blocking awaits.
+*/
+// @documentation render
+export function render<P extends keyof PageRoutes | (string & {})>(
+    path: P,
+    ...args: keyof PathParams<P> extends never
+        ? [query?: Query]
+        : [params: PathParams<P>, query?: Query]
+): Promise<string>
+export async function render(path: string, first?: Query, second?: Query): Promise<string> {
+    const dispatch = pageRenderSlot.render
+    if (!dispatch) {
+        throw new Error(
+            '[abide] render() called before init — make sure your call happens inside or after app.ts init() resolves',
+        )
+    }
+    /* url() discriminates params-vs-query off the path's own segments at runtime;
+       cast past its typed overload since `path` is a plain string here. */
+    const resolved = (url as (path: string, first?: Query, second?: Query) => string)(
+        path,
+        first,
+        second,
+    )
+    /* url() prefixes the mount base for browser-facing links; strip it back off so
+       the pathname matches the base-less page route keys the resolver matches on. */
+    const base = basePath()
+    const routePath =
+        base && resolved.startsWith(base) ? resolved.slice(base.length) || '/' : resolved
+    /* Origin only shapes absolute-URL generation inside the page; the live server's
+       own origin when booted, a stable localhost otherwise. */
+    const origin = getActiveServer()?.url.origin ?? 'http://localhost'
+    const requestUrl = new URL(routePath, origin)
+    /* Called inside a request scope, inherit the caller's auth/identity context —
+       the same allowlisted cookies/authorization/trace/forwarded headers defineRpc
+       threads onto an in-process rpc, cached per scope. Outside a scope (a cron/CLI
+       render) the page renders with no forwarded headers. */
+    const store = requestContext.getStore()
+    let headers: Headers | undefined
+    if (store) {
+        store.forwardedHeaders ??= forwardHeaders(store.req.headers)
+        headers = store.forwardedHeaders
+    }
+    const response = await dispatch(new Request(requestUrl, { headers }), requestUrl)
+    return response.text()
+}

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

@@ -0,0 +1,33 @@
+import { CACHE_STALENESS_SOCKET } from '../../shared/CACHE_STALENESS_SOCKET.ts'
+import { serializeSelector } from '../../shared/serializeSelector.ts'
+import type { CacheSelector } from '../../shared/types/CacheSelector.ts'
+import { lookupSocket } from '../sockets/lookupSocket.ts'
+
+/*
+The server half of the isomorphic staleness verbs (ADR-0041): serialize the selector
+to the cross-client envelope and publish it on the reserved __abide/cache socket so
+every connected browser applies the same drop/refetch locally. Installed as the
+cacheStalenessSlot resolver by serverEntry ONLY — never imported from a shared or ui
+module. That single discipline is what keeps this server socket code (and lookupSocket)
+out of the client bundle: the ADR-0022 DCE guard polices the app's own src/server edge,
+NOT abide's internal lib/server modules, so it would NOT catch a leak from here — the
+resolver-slot indirection is the actual guarantee. Do not import this from a
+client-reachable module.
+
+serializeSelector throws for a producer/closure or bare match-all selector (not
+cross-client serializable) — the throw surfaces at the mutation site as the
+programming error it is. Publishing is subscriber-gated by defineSocket.publish
+(it skips the encode + native fan-out when no ws client is subscribed), and the
+reserved socket keeps no tail, so a frame published to nobody simply evaporates.
+*/
+export function broadcastCacheStaleness<Args, Return>(
+    op: 'invalidate' | 'refresh',
+    selector: CacheSelector<Args, Return>,
+    args?: Args,
+): void {
+    const frame = serializeSelector(op, selector, args)
+    /* Resolved lazily from the registry — the socket is minted at server boot, before any
+       request-scoped mutation can call a staleness verb. Absent only in a degenerate boot. */
+    const entry = lookupSocket(CACHE_STALENESS_SOCKET)
+    entry?.socket.publish(frame)
+}

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

@@ -5,12 +5,14 @@ import type { McpServer } from '../../mcp/types/McpServer.ts'
 import { abideLog } from '../../shared/abideLog.ts'
 import { basePathFromAppUrl } from '../../shared/basePathFromAppUrl.ts'
 import { baseSlot } from '../../shared/baseSlot.ts'
+import { CACHE_STALENESS_SOCKET } from '../../shared/CACHE_STALENESS_SOCKET.ts'
 import { extraForwardHeaders } from '../../shared/extraForwardHeaders.ts'
 import { healthReadSlot } from '../../shared/healthReadSlot.ts'
 import { isDebugNegated } from '../../shared/isDebugNegated.ts'
 import { logClosingRecord } from '../../shared/logClosingRecord.ts'
 import { OFFLINE_HEADER } from '../../shared/OFFLINE_HEADER.ts'
 import { parseBoundedEnvInt } from '../../shared/parseBoundedEnvInt.ts'
+import { RESERVED_SOCKET_PREFIX } from '../../shared/RESERVED_SOCKET_PREFIX.ts'
 import { requestScopeSlot } from '../../shared/requestScopeSlot.ts'
 import { setAppName } from '../../shared/setAppName.ts'
 import type { Layouts } from '../../ui/types/Layouts.ts'
@@ -19,6 +21,7 @@ import type { AppModule } from '../AppModule.ts'
 import type { PromptRoutes } from '../prompts/types/PromptRoutes.ts'
 import type { RemoteRoutes } from '../rpc/types/RemoteRoutes.ts'
 import { createSocketDispatcher } from '../sockets/createSocketDispatcher.ts'
+import { defineSocket } from '../sockets/defineSocket.ts'
 import type { SocketRoutes } from '../sockets/types/SocketRoutes.ts'
 import { buildHealthPayload } from './buildHealthPayload.ts'
 import { buildOpenApiSpec } from './buildOpenApiSpec.ts'
@@ -39,6 +42,7 @@ import { internalErrorResponse } from './internalErrorResponse.ts'
 import { listenOnOpenPort } from './listenOnOpenPort.ts'
 import { logExposedSurfaces } from './logExposedSurfaces.ts'
 import { maybeMountInspector } from './maybeMountInspector.ts'
+import { pageRenderSlot } from './pageRenderSlot.ts'
 import { parseIdleTimeout } from './parseIdleTimeout.ts'
 import { parsePort } from './parsePort.ts'
 import { ensureRegistriesLoaded, setRegistryManifests } from './registryManifests.ts'
@@ -348,6 +352,30 @@ export async function createServer({
         })
     }
 
+    /*
+    Publish the in-process page-render seam for the public `render()`. It resolves
+    a synthetic GET request the same way the fetch handler resolves live app routes
+    (matchRoute → page handler / 308 redirect), then runs the matched handler
+    directly under runWithRequestScope — the page analogue of dispatchRpcInProcess,
+    so it skips app.handle middleware and wire finalization (gzip) exactly as the
+    in-process rpc seam does. A URL that resolves to no page renders the framework
+    404, matching the fetch fallback.
+    */
+    pageRenderSlot.render = (request, url) => {
+        const resolution = resolveAppRoute(request, url)
+        if (resolution.kind === 'redirect') {
+            return Promise.resolve(resolution.response)
+        }
+        if (resolution.kind === 'handler') {
+            return runWithRequestScope(request, { app, logRequests: false, url }, (store) =>
+                resolution.handler(request, resolution.params, store),
+            )
+        }
+        return runWithRequestScope(request, { app, logRequests: false, url }, async (store) => {
+            return (await renderError(404, 'Not Found', store)) ?? textResponse(404)
+        })
+    }
+
     /*
     Abide's only native WebSocket surface is the sockets hub: every Socket
     declared under src/server/sockets/ multiplexes onto one framework-owned
@@ -356,6 +384,21 @@ export async function createServer({
     lifecycle. Steady-state fan-out rides Bun's native server.publish so
     a busy socket doesn't iterate JS per subscriber per message.
     */
+    /* Reserve the `__abide/` socket namespace: a user socket file whose name lands there
+       would shadow a framework-minted internal topic (the cache-staleness pipe below), so
+       fail the boot loudly rather than let it silently override. */
+    for (const name of Object.keys(sockets)) {
+        if (name.startsWith(RESERVED_SOCKET_PREFIX)) {
+            throw new Error(
+                `[abide] socket name "${name}" is reserved — the "${RESERVED_SOCKET_PREFIX}" namespace is framework-internal. Rename the file under src/server/sockets.`,
+            )
+        }
+    }
+    /* Mint the reserved cache-staleness topic (ADR-0041): server-publish-only, no retention
+       tail (a pure live pipe). defineSocket registers it in socketRegistry, where the
+       broadcaster and the dispatcher's reserved-name path both resolve it. */
+    defineSocket(CACHE_STALENESS_SOCKET, { tail: 0, clientPublish: false })
+
     const socketDispatcher = createSocketDispatcher(sockets)
 
     /*

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

@@ -1,5 +1,6 @@
 import { appNameSlot } from '../../shared/appNameSlot.ts'
 import { SSR_CACHE_CONTROL } from '../../shared/CACHE_CONTROL_VALUES.ts'
+import { docSnapshotsSlot } from '../../shared/docSnapshotsSlot.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { formatTraceparent } from '../../shared/formatTraceparent.ts'
 import { hasSeedableRequest } from '../../shared/hasSeedableRequest.ts'
@@ -125,6 +126,41 @@ export function createUiPageRenderer({
         return Object.keys(cells).length > 0 ? cells : undefined
     }
 
+    /* The `docs` partition of __SSR__: each rendered scope's reactive-document snapshot (drained from
+       the request-scoped `docSnapshotsSlot` populated by `createScope`), keyed by its render-path id,
+       ref-json-encoded. A scope that used no state snapshots to `{}` and is dropped; an unserializable
+       doc value is dropped with the cell falling back to a client re-init. Undefined when no scope
+       carried seedable synchronous state (the common cell-only or static page). */
+    function docSeedSnapshots(): Record<string, string> | undefined {
+        const entries = docSnapshotsSlot.get()?.entries ?? []
+        if (entries.length === 0) {
+            return undefined
+        }
+        const docs: Record<string, string> = {}
+        for (const { id, take } of entries) {
+            let snapshot: unknown
+            try {
+                snapshot = take()
+            } catch {
+                continue
+            }
+            if (
+                snapshot === null ||
+                typeof snapshot !== 'object' ||
+                Object.keys(snapshot).length === 0
+            ) {
+                continue
+            }
+            try {
+                docs[id] = encodeRefJson(snapshot)
+            } catch {
+                /* Unserializable synchronous state (a function/class instance) — the client re-inits
+                   it cold rather than blanking the payload. */
+            }
+        }
+        return Object.keys(docs).length > 0 ? docs : 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. */
@@ -140,6 +176,7 @@ export function createUiPageRenderer({
             params,
             cache: inline,
             cells: resolvedCellCells(),
+            docs: docSeedSnapshots(),
             base: base || undefined,
             trace: formatTraceparent(store.trace),
             app: appNameSlot.name,

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

@@ -0,0 +1,15 @@
+/*
+Internal holder for the in-process page-render dispatch. createServer sets this
+once at boot, closing over the app's route resolver + render pipeline, so the
+public `render()` can turn a route URL into the same Response the HTTP fetch
+handler would — a page render, without a socket hop. Empty until boot: `render()`
+throws on access before the slot is set (mirroring serverSlot / server()). The
+closure runs the matched page handler directly under runWithRequestScope — like
+dispatchRpcInProcess for rpcs — so it skips app.handle middleware and wire
+finalization (gzip); it is the page analogue of the in-process rpc seam.
+*/
+export const pageRenderSlot: {
+    render: ((request: Request, url: URL) => Promise<Response>) | undefined
+} = {
+    render: undefined,
+}

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

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

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

@@ -1,4 +1,5 @@
 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 { StreamedCells } from '../../../shared/types/StreamedCells.ts'
@@ -41,6 +42,14 @@ export type RequestStore = {
     */
     streamedCells: StreamedCells
     /*
+    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
+    the server value rather than re-running a divergent init. Sibling of `resolvedCells` — this holds
+    synchronous document state, taken at render-return rather than at settle.
+    */
+    docSnapshots: DocSnapshots
+    /*
     W3C trace position: inbound `traceparent` continued (prefer-incoming) or a
     fresh sampled trace minted at the boundary. Read by trace()/log via the
     request-scope resolver and stamped into __SSR__ for the browser half.

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

@@ -4,6 +4,7 @@ import { decodeWireBody } from '../../shared/decodeWireBody.ts'
 import { encodeRefJson } from '../../shared/encodeRefJson.ts'
 import { memoizeByKey } from '../../shared/memoizeByKey.ts'
 import { messageFromError } from '../../shared/messageFromError.ts'
+import { RESERVED_SOCKET_PREFIX } from '../../shared/RESERVED_SOCKET_PREFIX.ts'
 import type { SocketClientFrame } from '../../shared/types/SocketClientFrame.ts'
 import type { SocketServerFrame } from '../../shared/types/SocketServerFrame.ts'
 import { error } from '../error.ts'
@@ -86,6 +87,14 @@ export function createSocketDispatcher(sockets: SocketRoutes): SocketDispatcher
         | { entry: SocketRegistryEntry }
         | { failure: 'unregistered' | 'load-failed' | 'no-export'; message: string }
     > {
+        /* 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)) {
+            const reserved = lookupSocket(name)
+            return reserved
+                ? { entry: reserved }
+                : { failure: 'unregistered', message: `[abide] no socket registered at ${name}` }
+        }
         const loader = ensureLoaded(name)
         if (!loader) {
             return { failure: 'unregistered', message: `[abide] no socket registered at ${name}` }

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

@@ -1,6 +1,18 @@
+import { RESERVED_SOCKET_PREFIX } from '../../shared/RESERVED_SOCKET_PREFIX.ts'
 import { socketRegistry } from './socketRegistry.ts'
 import type { SocketRegistryEntry } from './types/SocketRegistryEntry.ts'
 
 export function registerSocket(entry: SocketRegistryEntry): void {
+    /* A reserved (__abide/) topic is framework-internal and server-publish-only. Enforce
+       that invariant at the one chokepoint every socket flows through: a reserved name can
+       never register with client publish enabled, so no later trusted-but-mistaken
+       defineSocket call can turn an internal topic into one a browser could forge frames on
+       (ADR-0041). The framework mints its reserved topics clientPublish:false, so this never
+       fires on the legitimate path; the boot scan separately rejects reserved user files. */
+    if (entry.socket.name.startsWith(RESERVED_SOCKET_PREFIX) && entry.allowClientPublish) {
+        throw new Error(
+            `[abide] socket "${entry.socket.name}" is reserved — the "${RESERVED_SOCKET_PREFIX}" namespace is framework-internal and cannot enable clientPublish.`,
+        )
+    }
     socketRegistry.set(entry.socket.name, entry)
 }

package/src/lib/shared/CACHE_STALENESS_SOCKET.ts

@@ -0,0 +1,8 @@
+/*
+The reserved internal socket the server broadcasts cache-staleness frames on
+(ADR-0041): server-publish-only (`clientPublish: false`) and a pure live pipe
+(`tail: 0`, no retention) — delivery is live-only, never replayed, so an offline
+client falls back to SWR staleness. Named in the reserved `__abide/` namespace so
+user code can't shadow it.
+*/
+export const CACHE_STALENESS_SOCKET = '__abide/cache'

package/src/lib/shared/RESERVED_SOCKET_PREFIX.ts

@@ -0,0 +1,8 @@
+/*
+The reserved socket-name namespace (ADR-0041). Framework-minted internal topics
+live under `__abide/` (e.g. the cache-staleness pipe); user socket files under
+`src/server/sockets` may not declare a name in this namespace — createServer rejects
+the boot, and the dispatcher resolves these names straight from the registry
+(bypassing the user-module loader) so an internal topic can never be shadowed.
+*/
+export const RESERVED_SOCKET_PREFIX = '__abide/'

package/src/lib/shared/applyCacheStalenessLocally.ts

@@ -0,0 +1,18 @@
+import { cache } from './cache.ts'
+import type { CacheSelector } from './types/CacheSelector.ts'
+
+/*
+Applies a staleness verb to THIS side's cache store(s) — the local half of the
+isomorphic invalidate/refresh (ADR-0041). Both the cacheStalenessSlot fallback and
+the client entry's resolver point at this one function so the local-apply path can't
+diverge between "unbooted unit test" and "booted client tab". The server entry
+replaces the resolver with a broadcaster instead (the side-swap seam), so this never
+runs on the server's throwaway request store.
+*/
+export function applyCacheStalenessLocally<Args, Return>(
+    op: 'invalidate' | 'refresh',
+    selector: CacheSelector<Args, Return>,
+    args?: Args,
+): void {
+    cache[op](selector, args)
+}

package/src/lib/shared/attachRpcSelectorMethods.ts

@@ -1,3 +1,4 @@
+import { invalidate } from './invalidate.ts'
 import { keyForRemoteCall } from './keyForRemoteCall.ts'
 import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
 import { patch } from './patch.ts'
@@ -10,7 +11,7 @@ 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 / peek,
+`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
 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
@@ -25,6 +26,7 @@ export function attachRpcSelectorMethods<Args, Return>(fn: RemoteFunction<Args,
         pending: (args?: Args) => pending(fn, args),
         refreshing: (args?: Args) => refreshing(fn, 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),

package/src/lib/shared/cache.ts

@@ -758,8 +758,22 @@ cache; the lifecycle ping still fires but recomputes pending() to the same value
 function invalidate<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args): void {
     /* Resolve the fn-selector prefix once; the matcher and the label both consume it. */
     const prefix = selectorPrefix(arg, args)
-    const matches = selectorMatcher(arg, args, prefix)
-    invalidateTripwire(selectorLabel(arg, args, prefix))
+    invalidateMatching(selectorMatcher(arg, args, prefix), selectorLabel(arg, args, prefix), prefix)
+}
+
+/*
+The store-loop body of invalidate(), driven by a raw entry predicate rather than a
+selector — the single apply-by-matcher seam so a local invalidate() and a
+wire-driven one (a server broadcast decoded via matcherFromEnvelope) run the EXACT
+same drop loop and can't diverge (ADR-0041). `label` feeds the cycle tripwire;
+`prefix` (undefined for a tag selector) resets recorded rpc errors for the selector.
+*/
+function invalidateMatching(
+    matches: (entry: CacheEntry) => boolean,
+    label: string,
+    prefix: string | undefined,
+): void {
+    invalidateTripwire(label)
     /* Reset any recorded rpc errors for this selector too (independent of cache entries — a
        bare call that errored never became one). Only fn selectors resolve a prefix. */
     if (prefix !== undefined) {
@@ -814,6 +828,7 @@ function selectorLabel<Args, Return>(
 }
 
 cache.invalidate = invalidate
+cache.invalidateMatching = invalidateMatching
 
 /*
 The smart-call refetch: refetches every entry matching the selector, keeping the
@@ -836,8 +851,20 @@ way to re-run, so it drops (the next read reloads) — the invalidate fallback.
 */
 function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args): void {
     const prefix = selectorPrefix(arg, args)
-    const matches = selectorMatcher(arg, args, prefix)
-    invalidateTripwire(selectorLabel(arg, args, prefix))
+    refreshMatching(selectorMatcher(arg, args, prefix), selectorLabel(arg, args, prefix), prefix)
+}
+
+/*
+The store-loop body of refresh(), driven by a raw entry predicate — the refetch
+analogue of invalidateMatching, so a local refresh() and a wire-driven one share
+one refetch loop (ADR-0041).
+*/
+function refreshMatching(
+    matches: (entry: CacheEntry) => boolean,
+    label: string,
+    prefix: string | undefined,
+): void {
+    invalidateTripwire(label)
     if (prefix !== undefined) {
         rpcErrorRegistry.clearMatching(prefix)
     }
@@ -883,6 +910,7 @@ function refresh<Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args):
 }
 
 cache.refresh = refresh
+cache.refreshMatching = refreshMatching
 
 /*
 Local value mutation: replaces the retained value of every entry matching the

package/src/lib/shared/cacheStalenessSlot.ts

@@ -0,0 +1,21 @@
+import { applyCacheStalenessLocally } from './applyCacheStalenessLocally.ts'
+import { createResolverSlot } from './createResolverSlot.ts'
+import type { CacheStalenessApply } from './types/CacheStalenessApply.ts'
+
+/*
+The one side-swap seam for the isomorphic staleness verbs (ADR-0041), mirroring
+cacheStoreSlot exactly. `invalidate()` and `refresh()` route through this after their
+async-cell short-circuit, so their sources stay byte-identical on both sides — the
+resolver decides the side:
+
+  - client entry (startClient): installs applyCacheStalenessLocally — drop/refetch
+    this tab's cache.
+  - server entry (serverEntry): installs a broadcaster — serialize the selector and
+    publish it to every connected client over the reserved __abide/cache socket.
+
+With no resolver registered the fallback is applyCacheStalenessLocally too, so
+isolated unit tests keep today's local behaviour without booting a runtime.
+*/
+export const cacheStalenessSlot = createResolverSlot<CacheStalenessApply>(
+    () => applyCacheStalenessLocally,
+)