@abide/abide 0.42.0 → 0.43.1

package/src/lib/shared/outboxProbeSlot.ts

@@ -0,0 +1,20 @@
+/*
+Internal slot the browser outbox registry registers its prober into, so the
+shared pending() probe can count parked durable-rpc writes without shared/
+importing browser/. Mirrors tailProbeSlot. The prober reads the doc-backed
+queue entries (reactive inside $derived / $effect) and reports whether any
+undelivered entry matches the selector: a durable rpc selector (carries a
+`url`) narrows to its own queue, the bare form spans every registered queue,
+optional args narrow to one parked call by structural compare. Outbox state is
+pending-only — a parked write has no value, so it never contributes to
+refreshing(); probeRegistries reads this slot only on its `field === 'pending'`
+branch, which is why the slot mirrors tailProbeSlot but reports a bare boolean
+rather than a { pending, refreshing } pair. When no prober is registered (server
+render, or no durable rpc was ever used) pending() sees no parked writes,
+exactly as on the server where there are no client queues.
+*/
+export const outboxProbeSlot: {
+    probe: ((selector: unknown, args: unknown) => boolean) | undefined
+} = {
+    probe: undefined,
+}

package/src/lib/shared/pending.ts

@@ -15,9 +15,12 @@ tail registry (streams). Pending means "no value yet":
   pending(subscribable)  → that stream awaiting its first frame
                            (tail.status === 'pending'; true when nothing
                            is reading yet — there is no value either way)
+  pending(durableRpc)    → that durable rpc's parked writes (a parked write
+                           has no value yet); the bare form counts them too
 Probes report, never act: reading one opens no fetch and no stream. SSR
 loading state is driven by {#await}, not this. Scan semantics (tap order,
-selector grammar, registry spans) live in probeRegistries.
+selector grammar, registry spans, the parked-write term) live in
+probeRegistries.
 */
 // @documentation probes
 export function pending<Args, Return>(

package/src/lib/shared/prepareRpcModule.ts

@@ -1,24 +1,34 @@
 import { findExportCallSite } from './findExportCallSite.ts'
 import { importNamesToStrip } from './importNamesToStrip.ts'
+import { isReadOnlyMethod } from './isReadOnlyMethod.ts'
+import { skipNonCode } from './skipNonCode.ts'
 import { stripImport } from './stripImport.ts'
-import type { HttpVerb } from './types/HttpVerb.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
 
-const VERB_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
-const VERB_SET = new Set<string>(VERB_NAMES)
+const RPC_NAMES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
+const RPC_SET = new Set<string>(RPC_NAMES)
 
 const SINGLE_EXPORT_ERROR =
-    '[abide] $rpc module contains more than one `<VERB>(...)` export — each file must declare exactly one remote function'
+    '[abide] $rpc module contains more than one `<METHOD>(...)` export — each file must declare exactly one remote function'
 
 export type PreparedRpcModule = {
-    verb: HttpVerb
+    method: HttpMethod
+    /* `outbox: true` in the opts — the client proxy is emitted durable. */
+    durable: boolean
     exportName: string
     rewriteForServer: (url: string) => string
 }
 
+/* The `outbox` opts key plus its value's leading token (up to the next comma / whitespace /
+   closing brace). `outbox` is a BUILD-TIME flag: the client bundle is rewritten durable or
+   not from this scan, before any handler runs — so the value must be a literal the scan can
+   read, not a computed expression. */
+const OUTBOX_OPT = /\boutbox\s*:\s*([^,\s}]+)/
+
 /*
-Scans an `$rpc/**` module once and returns its declared verb + export
+Scans an `$rpc/**` module once and returns its declared method + export
 name plus a closure that, given the route URL, emits the server-side
-rewrite (`__abideDefineVerb__("VERB", "<url>", … )` spliced into the
+rewrite (`__abideDefineRpc__("METHOD", "<url>", … )` spliced into the
 original source). The single scan replaces the prior separate
 extract + rewrite passes, so the resolver plugin only walks each source
 character-by-character once.
@@ -26,34 +36,106 @@ character-by-character once.
 A regex pass would be tidier but it can't tell a `GET` mention inside a
 docstring or template literal from the real call, and it can't follow
 nested generics like `GET<Map<K, V>>(`.
+
+The two build-time `outbox` invariants live here, not at runtime, because the
+client bundle's durability is decided here — making this the single source of
+truth (the server-side defineRpc guard stays as a cheap backstop):
+  - `outbox` must be a literal `true`/`false`; a computed value can't be read at
+    bundle time, so it's rejected loudly instead of silently shipping a
+    non-durable client proxy.
+  - `outbox: true` is mutating-only — a read RPC (GET/HEAD) has nothing to
+    durably deliver.
 */
 export function prepareRpcModule(
     source: string,
     importName: string,
 ): PreparedRpcModule | undefined {
     /*
-    The "no barrels" surface places each verb at its own path
+    The "no barrels" surface places each method at its own path
     (`abide/server/GET`, `abide/server/POST`, …) — strip every one so
-    the user's verb import doesn't linger and side-effect-load the
+    the user's method import doesn't linger and side-effect-load the
     stub module into the server bundle. The user may import under the
     project's chosen name or the canonical package name, so strip both.
     */
     const stripped = importNamesToStrip(importName).reduce(
         (current, name) =>
-            VERB_NAMES.reduce((acc, verb) => stripImport(acc, `${name}/server/${verb}`), current),
+            RPC_NAMES.reduce(
+                (acc, method) => stripImport(acc, `${name}/server/${method}`),
+                current,
+            ),
         source,
     )
-    const site = findExportCallSite(stripped, (ident) => VERB_SET.has(ident), SINGLE_EXPORT_ERROR)
+    const site = findExportCallSite(stripped, (ident) => RPC_SET.has(ident), SINGLE_EXPORT_ERROR)
     if (!site) {
         return undefined
     }
-    const verb = site.ident as HttpVerb
+    const method = site.ident as HttpMethod
+    const durable = detectDurable(stripped, site.parenStart, site.parenEnd, method)
     return {
-        verb,
+        method,
+        durable,
         exportName: site.exportName,
         rewriteForServer(url: string): string {
-            const binding = `__abideDefineVerb__(${JSON.stringify(verb)}, ${JSON.stringify(url)}, `
+            const binding = `__abideDefineRpc__(${JSON.stringify(method)}, ${JSON.stringify(url)}, `
             return stripped.slice(0, site.callStart) + binding + stripped.slice(site.parenStart + 1)
         },
     }
 }
+
+/* Reads the `outbox` flag off the call's opts object (the trailing argument), enforcing the
+   two build-time invariants. Scoping to the opts object keeps the scan off the handler body,
+   so a handler that mentions `outbox:` doesn't misfire. */
+function detectDurable(
+    source: string,
+    parenStart: number,
+    parenEnd: number,
+    method: HttpMethod,
+): boolean {
+    const opts = lastArgText(source, parenStart, parenEnd)
+    const match = opts === undefined ? null : OUTBOX_OPT.exec(opts)
+    if (match === null) {
+        return false
+    }
+    const value = match[1]
+    if (value !== 'true' && value !== 'false') {
+        throw new Error(
+            `[abide] \`outbox\` must be a literal \`true\` or \`false\` (got \`${value}\`) — it's a build-time flag the client bundle reads, so it can't be a computed expression`,
+        )
+    }
+    const durable = value === 'true'
+    if (durable && isReadOnlyMethod(method)) {
+        throw new Error(
+            `[abide] outbox: true is only valid on mutating RPCs (POST/PUT/PATCH/DELETE), not ${method}`,
+        )
+    }
+    return durable
+}
+
+/*
+The text of the call's final argument — the opts object for a `METHOD(handler, opts)` call.
+Walks the arg list depth-aware, skipping strings / templates / comments / regex (skipNonCode)
+so their commas and braces don't miscount, and returns the slice after the last top-level
+comma. undefined when the call has a single argument (a bare handler, no opts).
+*/
+function lastArgText(source: string, parenStart: number, parenEnd: number): string | undefined {
+    let depth = 0
+    let lastComma = -1
+    let i = parenStart + 1
+    while (i < parenEnd) {
+        const skipped = skipNonCode(source, i)
+        if (skipped !== undefined) {
+            i = skipped
+            continue
+        }
+        const c = source[i]
+        if (c === '(' || c === '{' || c === '[') {
+            depth++
+        } else if (c === ')' || c === '}' || c === ']') {
+            depth--
+        } else if (c === ',' && depth === 0) {
+            lastComma = i
+        }
+        i++
+    }
+    return lastComma === -1 ? undefined : source.slice(lastComma + 1, parenEnd)
+}

package/src/lib/shared/probeRegistries.ts

@@ -1,5 +1,6 @@
 import { cacheStores } from './cacheStores.ts'
 import { isSubscribable } from './isSubscribable.ts'
+import { outboxProbeSlot } from './outboxProbeSlot.ts'
 import { selectorMatcher } from './selectorMatcher.ts'
 import { selectorPrefix } from './selectorPrefix.ts'
 import { tailProbeSlot } from './tailProbeSlot.ts'
@@ -22,9 +23,20 @@ cache() marks that channel, the re-derive resolves the prefix, and the scope
 re-tracks narrowed. `matchesEntry` is the probe's cache-side question;
 `field` selects the stream-side answer; `unprobed` is the answer for a
 stream no prober can see (server, or tail never imported) — matching what
-tail() itself reports there. The bare form (no selector) spans both
-registries; fn/tag selectors are cache identities only. Outside a tracking
-scope the taps are no-ops and the current value returns.
+tail() itself reports there. The bare form (no selector) spans every
+registry; fn/tag selectors are cache identities only (plus the parked-write
+queue a durable rpc selector narrows to). Outside a tracking scope the taps
+are no-ops and the current value returns.
+
+A parked durable (`outbox`) write has no value yet, so it counts as pending —
+but never refreshing (it's holding nothing to supersede), hence the term is
+guarded to `field === 'pending'`. The outbox prober (registered into
+outboxProbeSlot by browser/, empty on the server) reads its doc-backed queue,
+which is the term's own reactive tap. It sits last under `||`: when a matching
+cache call or stream already answers true the queue isn't read, but that's
+monotonic-safe — the parked write can't flip a true result, and the moment the
+cache/stream term falls back to false its lifecycle tap re-derives and the
+queue is read then.
 */
 export function probeRegistries<Args, Return>(
     arg: CacheSelector<Args, Return> | Subscribable<unknown> | undefined,
@@ -46,7 +58,8 @@ export function probeRegistries<Args, Return>(
     const matches = selectorMatcher(arg, args, prefix)
     return (
         stores.some((store) => anyEntryMatches(store, matchesEntry, matches)) ||
-        streams?.[field] === true
+        streams?.[field] === true ||
+        (field === 'pending' && (outboxProbeSlot.probe?.(arg, args) ?? false))
     )
 }
 

package/src/lib/shared/queryStringFromArgs.ts

@@ -1,5 +1,5 @@
 /*
-Canonical query-string encoding for a query-carrying verb's args bag. The
+Canonical query-string encoding for a query-carrying rpc's args bag. The
 single definition both the synthesized Request (buildRpcRequest) and its
 cache key (keyForRemoteCall) build their query from, so the request URL and
 the key encode every value identically and can't drift. `undefined` values

package/src/lib/shared/remoteMetaStore.ts

@@ -1,10 +1,10 @@
 /*
-WeakMap that records how to obtain the synthesized Request for a verb
+WeakMap that records how to obtain the synthesized Request for a rpc
 call. The cache layer reads it to populate an entry's stored request
 without rebuilding from scratch.
 
 Stored as a thunk rather than the Request itself so SSR pages that fire
-dozens of in-process verb calls without ever reaching cache() don't pay
+dozens of in-process rpc calls without ever reaching cache() don't pay
 the URL + Headers + Request allocation per call. The thunk memoises its
 own first call inside createRemoteFunction, so cache() and any future
 meta reader see the same Request instance.

package/src/lib/shared/resolveClientFlags.ts

@@ -4,7 +4,7 @@ import type { ClientFlags } from './types/ClientFlags.ts'
 Fills in the missing keys of a user-supplied `clients` option. Browser
 always defaults to true (the historical surface). The mcp/cli auto-on
 defaults are decided by the caller and passed in, since the safe default
-differs per declaration: a read-only verb may auto-expose to MCP while a
+differs per declaration: a read-only rpc may auto-expose to MCP while a
 mutating one must not, and sockets gate differently again. Explicit
 values in `flags` always win over the computed defaults.
 */

package/src/lib/shared/skipNonCode.ts

@@ -0,0 +1,230 @@
+import { isAsciiWhitespace } from './isAsciiWhitespace.ts'
+import { isIdentPart } from './isIdentPart.ts'
+
+/*
+The shared "skip a non-code construct" primitive for the source scanners
+(findExportCallSite, prepareRpcModule's arg walker, …). When `i` sits on the
+start of a string, template literal, line/block comment, or regex literal, it
+returns the index immediately after that construct; undefined when `source[i]`
+begins ordinary code — including a `/` that's division rather than a regex.
+
+Centralising the string / template / regex / comment rules here is what lets
+every scanner walk source depth-aware without re-deriving them and getting the
+regex-vs-division or `${…}` edge cases subtly wrong (the bug that made a naive
+arg walker miscount a `{ ratio: a / b }` or a regex literal in the opts).
+*/
+export function skipNonCode(source: string, i: number): number | undefined {
+    const c = source[i]
+    if (c === '"' || c === "'") {
+        return skipString(source, i + 1, c)
+    }
+    if (c === '`') {
+        return skipTemplate(source, i + 1)
+    }
+    if (c === '/') {
+        return skipSlashConstruct(source, i)
+    }
+    return undefined
+}
+
+function skipString(source: string, start: number, quote: string): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === quote) {
+            return i + 1
+        }
+        if (c === '\n') {
+            return i
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplate(source: string, start: number): number {
+    let i = start
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '`') {
+            return i + 1
+        }
+        if (c === '$' && source[i + 1] === '{') {
+            i = skipTemplateExpression(source, i + 2)
+            continue
+        }
+        i++
+    }
+    return source.length
+}
+
+function skipTemplateExpression(source: string, start: number): number {
+    let depth = 1
+    let i = start
+    while (i < source.length && depth > 0) {
+        const c = source[i]
+        if (c === '{') {
+            depth++
+            i++
+            continue
+        }
+        if (c === '}') {
+            depth--
+            i++
+            continue
+        }
+        const skipped = skipNonCode(source, i)
+        if (skipped !== undefined) {
+            i = skipped
+            continue
+        }
+        i++
+    }
+    return i
+}
+
+/*
+When `i` sits on a `/` introducing a line comment, block comment, or regex
+literal, returns the index immediately after the construct; undefined when the
+`/` is division (or `i` isn't a `/`). One statement of the skip rules shared by
+every scanner loop so they can't drift.
+*/
+function skipSlashConstruct(source: string, i: number): number | undefined {
+    if (source[i] !== '/') {
+        return undefined
+    }
+    const next = source[i + 1]
+    if (next === '/') {
+        const newline = source.indexOf('\n', i + 2)
+        return newline === -1 ? source.length : newline + 1
+    }
+    if (next === '*') {
+        const end = source.indexOf('*/', i + 2)
+        return end === -1 ? source.length : end + 2
+    }
+    if (isRegexContext(source, i)) {
+        return skipRegex(source, i + 1)
+    }
+    return undefined
+}
+
+/*
+A `/` starts a regex literal when the prior expression context expects an
+expression rather than a value — after an open delimiter, operator, or
+expression-prefix keyword (return, typeof, instanceof, in, of, delete, void,
+await, yield, new, throw, case, do). Otherwise `/` is division. Without this
+disambiguation a regex like `/^\//` reads as `/` (division), then `^`, `\`,
+`/`, `/` — and the final `//` pair fakes a line comment that swallows the rest
+of the line, eating any `)` that closes the enclosing call.
+*/
+const REGEX_PREFIX_KEYWORDS = new Set([
+    'return',
+    'typeof',
+    'instanceof',
+    'in',
+    'of',
+    'delete',
+    'void',
+    'await',
+    'yield',
+    'new',
+    'throw',
+    'case',
+    'do',
+])
+
+const REGEX_PUNCTUATION = new Set([
+    '(',
+    '[',
+    '{',
+    ',',
+    ';',
+    ':',
+    '?',
+    '!',
+    '&',
+    '|',
+    '^',
+    '~',
+    '+',
+    '-',
+    '*',
+    '%',
+    '<',
+    '>',
+    '=',
+    '/',
+])
+
+function isRegexContext(source: string, slashIndex: number): boolean {
+    let i = slashIndex - 1
+    while (i >= 0 && isAsciiWhitespace(source[i])) {
+        i--
+    }
+    if (i < 0) {
+        return true
+    }
+    const prev = source[i] as string
+    if (REGEX_PUNCTUATION.has(prev)) {
+        return true
+    }
+    if (isIdentPart(prev)) {
+        let start = i
+        while (start > 0 && isIdentPart(source[start - 1])) {
+            start--
+        }
+        return REGEX_PREFIX_KEYWORDS.has(source.slice(start, i + 1))
+    }
+    return false
+}
+
+/*
+Walks past a regex literal body, respecting character classes (`[...]` where
+`/` is literal) and backslash escapes, then consumes trailing flag identifiers.
+Returns the index immediately after the regex. An unterminated regex (newline
+before the closing `/`) returns the newline position so the outer scanner can
+resume normally on the next line.
+*/
+function skipRegex(source: string, start: number): number {
+    let i = start
+    let inClass = false
+    while (i < source.length) {
+        const c = source[i]
+        if (c === '\\') {
+            i += 2
+            continue
+        }
+        if (c === '\n') {
+            return i
+        }
+        if (inClass) {
+            if (c === ']') {
+                inClass = false
+            }
+            i++
+            continue
+        }
+        if (c === '[') {
+            inClass = true
+            i++
+            continue
+        }
+        if (c === '/') {
+            let j = i + 1
+            while (j < source.length && isIdentPart(source[j])) {
+                j++
+            }
+            return j
+        }
+        i++
+    }
+    return source.length
+}

package/src/lib/shared/streamResponse.ts

@@ -1,6 +1,6 @@
 import { contentTypeOf } from './contentTypeOf.ts'
 import { decodeResponse } from './decodeResponse.ts'
-import { HttpError } from './HttpError.ts'
+import { httpErrorFor } from './httpErrorFor.ts'
 import { jsonlErrorFrame } from './jsonlErrorFrame.ts'
 import { STREAMING_CONTENT_TYPES } from './STREAMING_CONTENT_TYPES.ts'
 import { sseErrorFrame } from './sseErrorFrame.ts'
@@ -24,11 +24,12 @@ identically. Three shapes are handled:
   handler, not just the streaming ones.
 
 Non-2xx responses surface as a thrown HttpError on the first pull,
-mirroring the plain `fn(args)` decode path.
+mirroring the plain `fn(args)` decode path — typed-error body included
+(`.kind` / `.data`), parsed by httpErrorFor when the generator is pulled.
 */
 export function streamResponse<T>(response: Response): AsyncIterable<T> {
     if (!response.ok) {
-        return errorIterable<T>(new HttpError(response))
+        return errorIterable<T>(response)
     }
     const contentType = contentTypeOf(response.headers)
     if (contentType.startsWith('text/event-stream')) {
@@ -40,10 +41,12 @@ export function streamResponse<T>(response: Response): AsyncIterable<T> {
     return oneShot<T>(response)
 }
 
-/* Surfaces a non-2xx response (or any pre-stream failure) as a thrown error on the first pull. */
+/* Surfaces a non-2xx response as a thrown HttpError on the first pull — awaiting the
+   typed-error body parse here (not in the sync streamResponse body) is what lets the
+   stream path carry `.kind` / `.data` like the plain decode path. */
 // biome-ignore lint/correctness/useYield: throws on first pull; the generator shape is intentional so callers iterate it uniformly
-async function* errorIterable<T>(error: Error): AsyncGenerator<T> {
-    throw error
+async function* errorIterable<T>(response: Response): AsyncGenerator<T> {
+    throw await httpErrorFor(response)
 }
 
 /*

package/src/lib/shared/stripImport.ts

@@ -3,9 +3,9 @@ import { escapeRegex } from './escapeRegex.ts'
 /*
 Strips the user's `import { … } from '<moduleName>'` declaration from a
 module source. Used by the $rpc / $sockets rewriters to remove the
-verb / `socket` import after its call site has been replaced by the
-runtime-injected binding (defineVerb / defineSocket). Without this
-strip the dead import would still side-effect-load the verb/socket
+rpc / `socket` import after its call site has been replaced by the
+runtime-injected binding (defineRpc / defineSocket). Without this
+strip the dead import would still side-effect-load the rpc/socket
 helper module into the server bundle for every $rpc / $sockets file.
 
 The braced body is `[^}]*` rather than `[\s\S]*?` so the lazy match

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

@@ -16,10 +16,8 @@ settles).
 `value` is the decoded warm value served synchronously by the read path
 (cloned per read). It is set at hydration — the SSR snapshot body is
 pre-decoded so the first client render reads it without a microtask hop and
-byte-matches the SSR DOM — and also by cache.on's `context.patch`, which folds
-an authoritative frame delta straight onto it without a refetch (ADR-0007).
-Live fetches leave it undefined and take the async decode path until a patch
-populates it.
+byte-matches the SSR DOM. Live fetches leave it undefined and take the async
+decode path.
 
 `hydrated` marks an entry built from the SSR snapshot, which ships no wrap
 options — the first read consumes the flag and adopts its call site's `ttl`

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

@@ -6,20 +6,10 @@ inside a binding. `invalidate` is the binding-scoped copy of cache.invalidate
 (same selector grammar, same effect): calls through it are recorded in the
 binding's coverage set by function identity, so attribution survives awaits
 and the coverage replays after a reconnect gap; the global cache.invalidate
-still works inside a handler but is not covered. `patch` folds an
-authoritative delta carried by the frame into the matching cached entries
-without a refetch (ADR-0007) — `updater` maps the current decoded value to the
-next; it resolves to the touched keys and is covered for reconnect resync the
-same way (the gap re-invalidates, since a delta can't be replayed). Await it to
-keep deltas ordered under sequential delivery. `signal` aborts when the binding
+still works inside a handler but is not covered. `signal` aborts when the binding
 is disposed, so an async handler mid-flight can bail or cancel its own fetches.
 */
 export type CacheOnContext = {
     invalidate: <Args, Return>(arg?: CacheSelector<Args, Return>, args?: Args) => void
-    patch: <Args, Return>(
-        arg: CacheSelector<Args, Return>,
-        updater: (current: Return) => Return,
-        args?: Args,
-    ) => Promise<string[]>
     signal: AbortSignal
 }

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

@@ -22,16 +22,22 @@ export type CacheStore = {
     entries: Map<string, CacheEntry>
     events: EventTarget
     subscribe: (key: string) => void
+    /* True while a reactive scope is reading `key` (a value held on screen).
+       invalidate() gates its reload marker on this — see pendingRefresh. */
+    hasReader: (key: string) => boolean
     trackLifecycle: (keyPrefix?: string) => void
     markLifecycle: (key?: string) => void
     /*
-    Keys dropped by a (policy-less) invalidate, awaiting their next read. The
-    drop erases the entry, so the next cache() call is a cold miss with no memory
-    it followed an invalidate; this set carries that signal across the gap so the
-    replacement entry is flagged a reload (refreshing() true) rather than a
-    first-ever load. Consumed when that entry is created; a key invalidated but
-    never re-read just lingers (bounded by distinct such keys; the server's
-    request-scoped store discards it with the response).
+    Keys dropped by a (policy-less) invalidate while a reader was holding the
+    value, awaiting their next read. The drop erases the entry, so the next
+    cache() call is a cold miss with no memory it followed an invalidate; this set
+    carries that signal across the gap so the replacement entry is flagged a reload
+    (refreshing() true) rather than a first-ever load. Consumed when that entry is
+    created. Bounded on the long-lived tab store from both ends: a marker is only
+    added when `hasReader(key)` (no on-screen value → the next read is a first
+    load, not a reload, so no marker), and a marker whose reader tears down before
+    re-reading is pruned by the subscriber's cleanup. The server's request-scoped
+    store discards the whole set with the response.
     */
     pendingRefresh: Set<string>
     /* Read tallies for the closing log record + Server-Timing; see CacheStats. */

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

@@ -1,5 +1,5 @@
 /*
-Which client surfaces a verb or socket is exposed to. Browser is the
+Which client surfaces a rpc or socket is exposed to. Browser is the
 historical default; MCP and CLI flip on automatically when the
 declaration carries a Standard Schema (the schema is what makes the
 non-browser surfaces safe to advertise). Explicit values always win.

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

@@ -0,0 +1,17 @@
+import type { ErrorDescriptor } from './ErrorDescriptor.ts'
+import type { ErrorSpec } from './ErrorSpec.ts'
+import type { StandardSchemaV1 } from './StandardSchemaV1.ts'
+
+/*
+The constructors handed to the handler via its second arg (`(args, { errors })`),
+derived from the rpc's `ErrorSpec`. An entry with a `data` schema makes its
+constructor require that schema's inferred input; an entry without one is nullary.
+Each returns a typed `ErrorDescriptor` to pass to `error()`.
+*/
+export type ErrorConstructors<Spec extends ErrorSpec> = {
+    [Name in keyof Spec & string]: Spec[Name]['data'] extends StandardSchemaV1
+        ? (
+              data: StandardSchemaV1.InferInput<Spec[Name]['data']>,
+          ) => ErrorDescriptor<Name, StandardSchemaV1.InferInput<Spec[Name]['data']>>
+        : () => ErrorDescriptor<Name, undefined>
+}

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

@@ -0,0 +1,10 @@
+/*
+What a rpc error constructor returns: a plain descriptor (NOT a Response), so it
+flows through the single `error()` funnel — `return error(errors.invalidCoupon({…}))`.
+`error()` reads `status` off it and serializes `{ $abideError: name, data }` as the body.
+*/
+export type ErrorDescriptor<Name extends string = string, Data = unknown> = {
+    readonly $abideError: Name
+    readonly status: number
+    readonly data: Data
+}