@abide/abide 0.58.0 → 0.101.0

package/src/lib/shared/abideLog.ts

@@ -1,38 +0,0 @@
-import { createChannelLog } from './createChannelLog.ts'
-import { emitLogRecord } from './emitLogRecord.ts'
-import type { ChannelLog } from './types/ChannelLog.ts'
-import type { FrameworkLog } from './types/FrameworkLog.ts'
-
-const ABIDE_CHANNEL = 'abide'
-
-/*
-The framework's own voice: the public log shape bound to the always-on
-'abide' channel, so every framework line — boot messages, build output,
-internal warns/errors, the closing record's sibling diagnostics — reads
-`[abide] …` and json consumers filter channel='abide'. The styling voices
-(info/success/detail) ride the same channel and the same negation gate, so
-DEBUG=-abide silences every voice; diagnostic sub-channels (abide:cache,
-abide:rpc, …) stay DEBUG-gated via .channel().
-*/
-const channelVoice = createChannelLog(() => ABIDE_CHANNEL, true)
-
-export const abideLog: FrameworkLog = Object.assign(channelVoice, {
-    channel(name: string): ChannelLog {
-        return createChannelLog(() => name, false)
-    },
-    info(message: string): void {
-        if (channelVoice.enabled()) {
-            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL })
-        }
-    },
-    success(message: string): void {
-        if (channelVoice.enabled()) {
-            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL }, 'success')
-        }
-    },
-    detail(message: string): void {
-        if (channelVoice.enabled()) {
-            emitLogRecord({ level: 'info', msg: message, channel: ABIDE_CHANNEL }, 'detail')
-        }
-    },
-})

package/src/lib/shared/activeCacheStore.ts

@@ -1,12 +0,0 @@
-import { cacheStoreSlot } from './cacheStoreSlot.ts'
-import type { CacheStore } from './types/CacheStore.ts'
-
-/*
-Resolves the active CacheStore: the registered resolver's store, or a single
-lazily-created fallback when none is registered (so isolated tests work). The
-fallback creator guarantees a value, hence the non-null assertion.
-*/
-export function activeCacheStore(): CacheStore {
-    // biome-ignore lint/style/noNonNullAssertion: the slot's lazy fallback creator always returns a store
-    return cacheStoreSlot.get()!
-}

package/src/lib/shared/activePage.ts

@@ -1,12 +0,0 @@
-import { pageSlot } from './pageSlot.ts'
-import type { PageSnapshot } from './types/PageSnapshot.ts'
-
-/*
-Resolves the active page snapshot: the registered resolver's snapshot, or a
-single lazily-created empty snapshot when none is registered (so isolated tests
-work). The fallback creator guarantees a value, hence the non-null assertion.
-*/
-export function activePage(): PageSnapshot {
-    // biome-ignore lint/style/noNonNullAssertion: the slot's lazy fallback creator always returns a snapshot
-    return pageSlot.get()!
-}

package/src/lib/shared/amend.ts

@@ -1,48 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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/appDataDir.ts

@@ -1,34 +0,0 @@
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-
-/*
-Platform-standard per-user data directory for a bundle, keyed by its program
-name. cwd-independent on purpose: the path derives from `programName`, not the
-process working directory — which the OS `open` command sets to `/`, so anything
-relying on cwd (Bun's `.env` autoload, relative paths) finds nothing inside a
-launched `.app`. This is where a bundle keeps what can't be baked at compile time
-— the user's config, DB, and cache. macOS Application Support, Windows %APPDATA%,
-XDG data home elsewhere. Pure: computes the path, never touches the filesystem.
-
-`ABIDE_DATA_DIR` overrides the lot on every platform, used as-is (no programName
-appended) — a cross-platform `XDG_DATA_HOME` that also works on macOS/Windows. Set
-it to point dev at a throwaway dir without touching app code; leave it unset in
-prod for the platform default. A relative value reintroduces cwd-dependence, so a
-launched `.app` (cwd `/`) needs an absolute path. Must come from a layer above the
-data-dir `.env` (shell, CWD `.env`, or binary-dir `.env`) — it can't be read from
-the very file whose location it decides.
-*/
-export function appDataDir(programName: string): string {
-    const override = process.env.ABIDE_DATA_DIR
-    if (override !== undefined && override !== '') {
-        return override
-    }
-    const home = homedir()
-    if (process.platform === 'darwin') {
-        return join(home, 'Library', 'Application Support', programName)
-    }
-    if (process.platform === 'win32') {
-        return join(process.env.APPDATA ?? join(home, 'AppData', 'Roaming'), programName)
-    }
-    return join(process.env.XDG_DATA_HOME ?? join(home, '.local', 'share'), programName)
-}

package/src/lib/shared/appNameSlot.ts

@@ -1,10 +0,0 @@
-/*
-The app's name — the default log channel every unchanneled record carries.
-Set once per process by createServer (package.json name / appInfo) and once
-per page by startClient (the __SSR__ stamp). Undefined until the runtime
-boots; readers fall back to 'app' so isolated tests and pre-boot logging
-still carry a channel.
-*/
-export const appNameSlot: { name: string | undefined } = {
-    name: undefined,
-}

package/src/lib/shared/applyAmendLocally.ts

@@ -1,20 +0,0 @@
-import { cache } from './cache.ts'
-import type { CacheSelector } from './types/CacheSelector.ts'
-
-/*
-Applies an amend to THIS side's cache store(s) — the local half of the isomorphic
-amend value form (ADR-0043). A concrete value folds to an updater that ignores the
-current value; an updater is used as-is. Both the amendBroadcastSlot fallback and the
-client entry's resolver point here so the local-apply path can't diverge between an
-unbooted unit test and a booted client tab. The server entry installs a broadcaster
-instead (the side-swap seam), so this never runs on the server's throwaway request store.
-*/
-export function applyAmendLocally<Args, Return>(
-    selector: CacheSelector<Args, Return>,
-    args: Args | undefined,
-    isValue: boolean,
-    payload: Return | ((current: Return) => Return),
-): void {
-    const updater = isValue ? () => payload as Return : (payload as (current: Return) => Return)
-    cache.amend(selector, args, updater, isValue)
-}

package/src/lib/shared/applyCacheStalenessLocally.ts

@@ -1,18 +0,0 @@
-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/assertExhaustive.ts

@@ -1,14 +0,0 @@
-/*
-Exhaustiveness guard for a discriminated-union dispatch. When every variant is
-handled, the fall-through value narrows to `never`, so passing it here type-checks;
-adding a new variant without a branch makes this a COMPILE error AND, if it slips
-past types, throws at runtime naming the variant — converting a silent mis-dispatch
-(a new template-node kind routed to the wrong branch) into a loud failure. The
-enumeration's completeness becomes the type checker's job instead of inspection's.
-*/
-export function assertExhaustive(value: never, context = 'variant'): never {
-    const kind = (value as { kind?: unknown })?.kind
-    throw new Error(
-        `[abide] non-exhaustive ${context}${kind === undefined ? '' : `: ${String(kind)}`}`,
-    )
-}

package/src/lib/shared/attachRpcSelectorMethods.ts

@@ -1,44 +0,0 @@
-import { amend } from './amend.ts'
-import { invalidate } from './invalidate.ts'
-import { keyForRemoteCall } from './keyForRemoteCall.ts'
-import { keyPrefixForRemote } from './keyPrefixForRemote.ts'
-import { peek } from './peek.ts'
-import { pending } from './pending.ts'
-import { refresh } from './refresh.ts'
-import { refreshing } from './refreshing.ts'
-import { rpcErrorRegistry } from './rpcErrorRegistry.ts'
-import type { RemoteFunction } from './types/RemoteFunction.ts'
-
-/*
-Attaches the pre-bound selector sugar onto an assembled RemoteFunction:
-`fn.pending(args?)` ≡ `pending(fn, args?)`, likewise refreshing / refresh / invalidate / peek,
-`fn.amend(args?, value | updater)` ≡ `amend(fn, args, …)`, and `fn.error(args?)` — the typed
-last error from the rpc error registry (most-recent across the rpc when args omitted, that
-exact call when given). The cached read is the bare call `fn(args, opts)` itself; refetch is
-`fn.refresh(args?)`. The methods only reference the globals at call time, so the shared import
-edge carries no module-init dependency (safe against any cache ↔ createRemoteFunction cycle).
-Attached in createRemoteFunction so the server (defineRpc) and client (remoteProxy) shapes are
-identical. `amend` is attached uniformly; the type omits it for a streaming rpc (harmless at
-runtime — a stream has no cache entry).
-*/
-export function attachRpcSelectorMethods<Args, Return>(fn: RemoteFunction<Args, Return>): void {
-    Object.assign(fn, {
-        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),
-        amend: (argsOrUpdater?: unknown, updater?: unknown) =>
-            (amend as (fn: unknown, a?: unknown, b?: unknown) => void)(fn, argsOrUpdater, updater),
-        /* Reaction sugar is client-only (`watch` is a ui primitive that must not ride into a
-           server bundle), so the shared attach binds an inert no-op — the server (defineRpc)
-           shape carries `.watch` too, and an author `fn.watch(…)` surviving the SSR effect-strip
-           is a safe no-op. The client proxy (remoteProxy) overwrites this with the real
-           `watch(fn, …)`. */
-        watch: () => () => {},
-        error: (args?: Args) =>
-            args === undefined
-                ? rpcErrorRegistry.readAny(keyPrefixForRemote(fn.method, fn.url))
-                : rpcErrorRegistry.read(keyForRemoteCall(fn.method, fn.url, args)),
-    })
-}

package/src/lib/shared/attachSocketSelectorMethods.ts

@@ -1,34 +0,0 @@
-import { done } from './done.ts'
-import { pending } from './pending.ts'
-import { refreshing } from './refreshing.ts'
-import { tailProbeSlot } from './tailProbeSlot.ts'
-import type { Socket } from './types/Socket.ts'
-
-/* The socket surface before the probe sugar is attached — every Socket member except the
-   pre-bound probes this module adds. Both construction sites (defineSocket / buildSocketOverChannel)
-   build this shape, then the assertion below narrows it to a full Socket. */
-type SocketWithoutProbes<T> = Omit<Socket<T>, 'pending' | 'refreshing' | 'done' | 'error'>
-
-/*
-Attaches the pre-bound probe sugar onto an assembled Socket, mirroring
-attachRpcSelectorMethods for the rpc side: `socket.pending()` ≡ `pending(socket)`,
-likewise refreshing / done, and `socket.error()` reads the stream's terminal error (the
-tail prober's `error` field — instance-only, no bare global, same as the rpc's `.error`).
-The socket is the pre-bound stream selector. The methods reference the globals at call
-time, so the shared import edge carries no module-init dependency. Called by both
-buildSocketOverChannel (consumer / test) and defineSocket (server) so the two Socket
-shapes stay identical; on the server the tail prober is unregistered, so the probes read
-the same fallbacks the globals give there (pending true until a frame, refreshing/done
-false, error undefined). An assertion return narrows the base object to a full Socket at
-each call site, so neither construction literal needs a cast.
-*/
-export function attachSocketSelectorMethods<T>(
-    socket: SocketWithoutProbes<T>,
-): asserts socket is Socket<T> {
-    Object.assign(socket, {
-        pending: () => pending(socket),
-        refreshing: () => refreshing(socket),
-        done: () => done(socket),
-        error: () => tailProbeSlot.probe?.(socket.name)?.error,
-    })
-}

package/src/lib/shared/augmentModule.ts

@@ -1,18 +0,0 @@
-/*
-Emits one `declare module '<module>' { interface <iface> { … } }` block, the
-module-augmentation shape every codegen writer (routes, rpc, publicAssets,
-testRpc, testSockets) shares. `entries` is `[key, type]` pairs already in final
-order; each becomes an 8-space-indented `"key": type` member, the indentation
-the consumer src tsconfig include expects. Returns the block body only — the
-writeDts envelope adds banner + footer.
-*/
-export function augmentModule(module: string, iface: string, entries: [string, string][]): string {
-    const members = entries
-        .map(([key, type]) => `        ${JSON.stringify(key)}: ${type}`)
-        .join('\n')
-    return `declare module '${module}' {
-    interface ${iface} {
-${members}
-    }
-}`
-}

package/src/lib/shared/basePath.ts

@@ -1,11 +0,0 @@
-import { baseSlot } from './baseSlot.ts'
-
-/*
-The current mount base path ('' at root). Resolved per side: the server installs
-an APP_URL-derived resolver at boot, the client one reading window.__SSR__.base.
-url() reads this to prefix rooted internal paths. Defaults to '' when no resolver
-or fallback is set.
-*/
-export function basePath(): string {
-    return baseSlot.get() ?? ''
-}

package/src/lib/shared/basePathFromAppUrl.ts

@@ -1,20 +0,0 @@
-/*
-Derives the mount base path from APP_URL. APP_URL carries both the app's
-public origin (for absolute URLs) and, via its pathname, where the app is
-mounted — `https://foo.com/v2` → `/v2`. Returns the pathname with any
-trailing slash stripped; root (`/`), unset, or unparseable collapses to ''
-(root mount, the zero-config default). A bare path value with no origin is
-tolerated so `.env` can carry `APP_URL=/v2`.
-*/
-export function basePathFromAppUrl(appUrl: string | undefined): string {
-    if (!appUrl) {
-        return ''
-    }
-    let pathname: string
-    try {
-        pathname = new URL(appUrl).pathname
-    } catch {
-        pathname = appUrl.startsWith('/') ? appUrl : ''
-    }
-    return pathname.replace(/\/+$/, '')
-}

package/src/lib/shared/baseSlot.ts

@@ -1,9 +0,0 @@
-import { createResolverSlot } from './createResolverSlot.ts'
-
-/*
-The mount-base slot. The server entry installs an APP_URL-derived resolver at
-boot; the client entry one reading window.__SSR__.base. No lazy fallback
-creator — `.fallback` is a plain string set directly by isolated tests, and
-basePath() (the public read) supplies the '' default.
-*/
-export const baseSlot = createResolverSlot<string>()

package/src/lib/shared/binaryDirEnvPath.ts

@@ -1,12 +0,0 @@
-import { dirname } from 'node:path'
-import { bundleLayout } from './bundleLayout.ts'
-
-/*
-The bundle's shipped `.env` (its default config layer), resolved from the
-running binary's directory via bundleLayout — beside the binary in the flat
-layout, under `Contents/Resources` in a macOS `.app`. One statement of the
-location for the boot loader, the config form, and the embedded-port resolver.
-*/
-export function binaryDirEnvPath(): string {
-    return bundleLayout(dirname(process.execPath)).envPath
-}

package/src/lib/shared/bodyValueForKind.ts

@@ -1,34 +0,0 @@
-import type { ContentBodyKind } from './contentBodyKind.ts'
-import { DEFER } from './DEFER.ts'
-
-/*
-The single body-kind → value mapping shared by the live read (decodeResponse) and
-the synchronous warm read (warmValueFromSnapshot), so neither can disagree about
-which kind yields what — the divergence behind the streaming-guard-in-one-but-not-
-the-other bug.
-
-Generic over the extraction (`Value`) so both async and sync callers reuse it:
-the live read passes Promise-returning accessors (response.json()/text()) and
-handles the deferred kinds (streaming → throw, binary → blob); the warm read
-passes sync accessors (JSON.parse(body)/body) and treats every deferred kind as
-no-warm-value, leaving the live async path to throw/blob exactly as a fresh call
-would. The json/text branches — the only kinds that produce a directly-usable
-value on both sides — are decided here, once.
-
-Returns the DEFER sentinel for `streaming` and `binary`: kinds whose handling is
-side-specific (the live read throws on streaming and blobs on binary; the warm
-read has no synchronous equivalent for either), so the caller branches on it.
-*/
-export function bodyValueForKind<Value>(
-    kind: ContentBodyKind,
-    json: () => Value,
-    text: () => Value,
-): Value | typeof DEFER {
-    if (kind === 'json') {
-        return json()
-    }
-    if (kind === 'text') {
-        return text()
-    }
-    return DEFER
-}

package/src/lib/shared/browserClientFlags.ts

@@ -1,10 +0,0 @@
-import type { ClientFlags } from './types/ClientFlags.ts'
-
-/*
-Client surface flags for a browser-emitted RPC/socket stub. The bundler only
-emits the browser proxy when clients.browser is true, so browser is always true
-here; mcp/cli are server-only discovery state with no meaning in the browser
-bundle, defaulted false so the public RemoteFunction/Socket shape matches the
-server side. Single source shared by remoteProxy and socketProxy.
-*/
-export const browserClientFlags: ClientFlags = { browser: true, mcp: false, cli: false }

package/src/lib/shared/buildArtifact.ts

@@ -1,20 +0,0 @@
-import type { BuildConfig, BuildOutput } from 'bun'
-import { exitOnBuildFailure } from './exitOnBuildFailure.ts'
-
-/*
-Runs one Bun.build and fails the process on any diagnostic, returning the
-successful output — the build-or-die pairing every one-shot build site shares
-(compile, buildCli's discovery + cli, bundleApp, buildDisconnected). Keeps the
-`Bun.build` + `exitOnBuildFailure` step atomic so a new build site can't ship
-without the failure check. The incremental client build (build.ts) does NOT use
-this: it must clean its staging dir and return `false` rather than exit, so it
-keeps its own epilogue.
-*/
-export async function buildArtifact(config: BuildConfig): Promise<BuildOutput> {
-    /* metafile: true so the abideResolverPlugin's onEnd reachability guard (ADR-0022 D3) can read
-       the post-DCE graph on a client build (buildDisconnected). Harmless extra output on the
-       server builds that also route through here. A caller can still override it explicitly. */
-    const result = await Bun.build({ metafile: true, ...config })
-    exitOnBuildFailure(result)
-    return result
-}

package/src/lib/shared/buildRpcProxy.ts

@@ -1,39 +0,0 @@
-import { decodeResponse } from './decodeResponse.ts'
-import type { RpcInvoker } from './types/RpcInvoker.ts'
-
-/*
-Builds the name→callable proxy every RPC client surface shares (the CLI client,
-the test harness). The caller supplies `resolveSend`, the one part that differs:
-it maps a command name to the closure that issues that command's wire call, or
-undefined for an unknown name. This module owns the invariant — a plain call
-decodes the body (decodeResponse throws HttpError on non-2xx), `.raw` returns the
-untouched Response — so the two surfaces can't drift from each other or from the
-remote-function path they mirror.
-
-Each name resolves once: the per-name invoker (or its absence) is memoised, since
-the underlying registry/manifest is fixed for a client's lifetime, so repeated
-`client.foo` accesses skip both the resolve and a fresh closure allocation.
-*/
-export function buildRpcProxy<Api extends object>(
-    resolveSend: (name: string) => ((args?: unknown) => Promise<Response>) | undefined,
-): Api {
-    const invokerCache = new Map<string, RpcInvoker | undefined>()
-    return new Proxy({} as Api, {
-        get(_target, prop): RpcInvoker | undefined {
-            if (typeof prop !== 'string') {
-                return undefined
-            }
-            // Caches undefined too, so an unknown name resolves once, not per access.
-            return invokerCache.getOrInsertComputed(prop, () => {
-                const send = resolveSend(prop)
-                if (!send) {
-                    return undefined
-                }
-                const invoker = (async (args?: unknown) =>
-                    decodeResponse(await send(args))) as RpcInvoker
-                invoker.raw = (args?: unknown) => send(args)
-                return invoker
-            })
-        },
-    })
-}

package/src/lib/shared/buildRpcRequest.ts

@@ -1,81 +0,0 @@
-import { carriesBodyArgs } from './carriesBodyArgs.ts'
-import { encodeRefJson } from './encodeRefJson.ts'
-import { queryStringFromArgs } from './queryStringFromArgs.ts'
-import { REF_JSON_HEADER } from './REF_JSON_HEADER.ts'
-import type { HttpMethod } from './types/HttpMethod.ts'
-
-/*
-Builds the Request a rpc helper uses to invoke its handler. Same shape on
-both sides (server defineRpc + client remoteProxy) so the cache key
-derivation and SSR snapshot round-trip identically. $rpc URLs are flat
-(no `:name` segments): GET/DELETE/HEAD serialise args onto the query
-string; POST/PUT/PATCH send them as application/json.
-
-`baseUrl` provides the origin needed by the Request constructor — on the
-server it's the inbound request's URL (so handlers reading `request.url` see
-the caller's host), in the browser it's window.location. `headers` lets the
-server pre-populate the synthetic Request with forwarded session headers;
-the client passes nothing.
-*/
-export function buildRpcRequest({
-    method,
-    url,
-    args,
-    baseUrl,
-    headers,
-}: {
-    method: HttpMethod
-    url: string
-    args: unknown
-    baseUrl: string
-    headers?: Headers
-}): Request {
-    const requestHeaders = headers ?? new Headers()
-    if (!carriesBodyArgs(method)) {
-        const target = appendQuery(method, url, args)
-        return new Request(new URL(target, baseUrl).href, { method, headers: requestHeaders })
-    }
-    if (args === undefined) {
-        return new Request(new URL(url, baseUrl).href, { method, headers: requestHeaders })
-    }
-    /*
-    A FormData body ships as-is: the Request constructor sets its own
-    `multipart/form-data` content-type with a boundary, so the server's
-    parseArgs splits text fields into args and File parts into files().
-    Setting the header by hand would omit the boundary and break parsing.
-    */
-    if (args instanceof FormData) {
-        return new Request(new URL(url, baseUrl).href, {
-            method,
-            headers: requestHeaders,
-            body: args,
-        })
-    }
-    /* ref-json (still valid JSON, so the content-type holds) so an arg graph with
-       cycles or shared back-references reaches the handler instead of throwing here.
-       The REF_JSON_HEADER flags the encoding so parseArgs decodes it with the same
-       codec; a non-abide client omits it and parseArgs reads plain JSON.parse. */
-    requestHeaders.set('content-type', 'application/json')
-    requestHeaders.set(REF_JSON_HEADER, '1')
-    return new Request(new URL(url, baseUrl).href, {
-        method,
-        headers: requestHeaders,
-        body: encodeRefJson(args),
-    })
-}
-
-function appendQuery(method: HttpMethod, url: string, args: unknown): string {
-    if (args === undefined) {
-        return url
-    }
-    const isFormData = typeof FormData !== 'undefined' && args instanceof FormData
-    if (typeof args !== 'object' || args === null || Array.isArray(args) || isFormData) {
-        /* FormData has no own enumerable keys, so `queryStringFromArgs` would silently drop
-           every field; a query-carrying method (GET/DELETE/HEAD) can't take a body anyway.
-           Fail loudly like any other non-plain-object arg. */
-        const got = Array.isArray(args) ? 'array' : isFormData ? 'FormData' : typeof args
-        throw new Error(`[abide] ${method} ${url} args must be a plain object — got ${got}`)
-    }
-    const suffix = queryStringFromArgs(args as Record<string, unknown>, false)
-    return suffix === '' ? url : `${url}?${suffix}`
-}