@abide/abide 0.57.1 → 0.100.0

package/src/shared/routePattern.ts

@@ -0,0 +1,146 @@
+// A ROUTE LITERAL, PARSED. One grammar for two things that would otherwise drift: the directory a
+// page is filed under (`ui/pages/invoices/[id]/page.abide`) and the literal an author writes
+// (`'/invoices/[id]'`). The bracket spelling is the file system's, so the address is read off the
+// tree rather than declared beside it and the two cannot disagree.
+//
+// 30.3, 30.4, 30.5 — the three segment kinds are the three the registry's `ParamsOf<P>` names:
+// required takes a value, optional may be left out and omits its segment with it, and rest takes
+// an array as well as a scalar.
+//
+// A LEAF: no imports, because the compiler, the client router and a server router all read it and
+// a constant crossing a seam lives where nothing pulls a graph in behind it.
+
+type SegmentKind = 'static' | 'required' | 'optional' | 'rest'
+
+/** One `/`-separated piece of a route literal, classified by kind. */
+export type Segment = {
+    kind: SegmentKind
+    /** The literal text for a static segment, the param name for the other three. */
+    name: string
+}
+
+/**
+ * A route literal split into its segments, each classified by kind.
+ *
+ * `[...rest]`, `[[optional]]`, `[required]`, or a literal. Ordered longest-first: `[[a]]` is a
+ * `[a]` with another bracket round it, so testing the short form first matches both.
+ */
+export function parseRoutePattern(pattern: string): Segment[] {
+    const out: Segment[] = []
+    for (const raw of pattern.split('/')) {
+        if (raw === '') continue
+        if (raw.startsWith('[[') && raw.endsWith(']]'))
+            out.push({ kind: 'optional', name: raw.slice(2, -2) })
+        else if (raw.startsWith('[...') && raw.endsWith(']'))
+            out.push({ kind: 'rest', name: raw.slice(4, -1) })
+        else if (raw.startsWith('[') && raw.endsWith(']'))
+            out.push({ kind: 'required', name: raw.slice(1, -1) })
+        else out.push({ kind: 'static', name: raw })
+    }
+    return out
+}
+
+const ROUTES = 'ui/pages/'
+
+/** Whether a source is a page, a layout, an error page or a component. */
+export type FileKind = 'page' | 'layout' | 'error' | 'component'
+
+/**
+ * Whether the `.abide` at `path` is a page, a layout, an error page or a component.
+ *
+ * AN ADDRESS RATHER THAN A NAME. Both halves are load-bearing: the file name is the address and
+ * the directory is what says the address is a ROUTE rather than a component filed anywhere. One
+ * test for every name (35.1 reads `layout.abide` the same way), so the directory half cannot be
+ * got right for one and wrong for another — and one test for every reader: the build's routes,
+ * the checker's `Routes` and the `route.params` a page is typed by.
+ *
+ * 23.3 — under `ui/pages/` and nowhere else: a `page.abide` filed in some other `pages/`
+ * directory is a component, as it is to the `Routes` the checker declares. `path` may be relative
+ * to the app or the project, or absolute.
+ */
+export function fileKind(path: string): FileKind {
+    if (routesAt(path) === -1) return 'component'
+    // The WHOLE basename: `homepage.abide` ends with `page.abide` and is a component.
+    const name = path.slice(path.lastIndexOf('/') + 1)
+    if (name === 'page.abide') return 'page'
+    if (name === 'layout.abide') return 'layout'
+    return name === 'error.abide' ? 'error' : 'component'
+}
+
+/**
+ * The route literal a page file is filed under, read off its path below `ui/pages/`.
+ *
+ * `page.abide` is an address rather than a name (CLAUDE.md), so the directories above it ARE the
+ * route and the file itself contributes nothing.
+ *
+ * 23.3 — BELOW THE FIRST `ui/pages/`, which is the routes directory, and not below the last `pages/`:
+ * a section an app files as `ui/pages/pages/` is the address `/pages`, and cutting at the last one
+ * served `ui/pages/pages/add-a-page` at `/add-a-page` and gave `/` two pages.
+ */
+export function routeOf(pagePath: string): string {
+    const at = routesAt(pagePath)
+    const tail = at === -1 ? pagePath : pagePath.slice(at + ROUTES.length)
+    const parts: string[] = []
+    for (const part of tail.split('/'))
+        if (part !== '' && !part.endsWith('.abide')) parts.push(part)
+    return `/${parts.join('/')}`
+}
+
+/** Where the first `ui/pages/` in `path` begins, as whole directories, or -1. */
+function routesAt(path: string): number {
+    if (path.startsWith(ROUTES)) return 0
+    const at = path.indexOf(`/${ROUTES}`)
+    return at === -1 ? -1 : at + 1
+}
+
+/**
+ * A `sort` comparator over two parsed patterns: negative where `a` is the more specific.
+ *
+ * 30.9 — HOW SPECIFIC A PATTERN IS, so `/invoices/new` is tried before `/invoices/[id]` however the
+ * build happened to walk the tree. Negative where `a` is the more specific, which is `sort`'s own
+ * order and so the one this is read in.
+ *
+ * SEGMENT BY SEGMENT, LEFT TO RIGHT, rather than by a score summed over the whole pattern. A sum
+ * cannot carry an ORDERING over kinds: the first thing it loses is position, so `/[id]/edit` and
+ * `/new/[tab]` come out equal and `/new/edit` resolves by whichever the build walked first — the
+ * thing this function exists to stop. Weighting length on top of that then loses the kinds
+ * themselves, and `/x` ranked BELOW `/[[a]]/[[b]]` for the path `/x`: a static segment beaten by
+ * two optionals, which is 30.9 exactly inverted. Both were live on the scalar this replaced.
+ *
+ * THE SHORTER PATTERN WINS A TIE, and only an exhausted prefix can produce one: every segment the
+ * two share is the same kind, so what is left is the extra segments of the longer, which can only
+ * be optional or rest or the two would not match one path. `/a` admits one address and
+ * `/a/[[b]]` admits two, so the shorter is the narrower claim.
+ */
+export function compareRoutes(a: Segment[], b: Segment[]): number {
+    const shared = a.length < b.length ? a.length : b.length
+    for (let at = 0; at < shared; at += 1) {
+        const kind =
+            specificity(b[at] as Segment) - specificity(a[at] as Segment)
+        if (kind !== 0) return kind
+    }
+    return a.length - b.length
+}
+
+function specificity(segment: Segment): number {
+    if (segment.kind === 'static') return 3
+    if (segment.kind === 'required') return 2
+    return segment.kind === 'optional' ? 1 : 0
+}
+
+/**
+ * A route table compiled for matching: each row with its pattern parsed, most specific first.
+ *
+ * 30.9 — MOST SPECIFIC FIRST, for whichever seam is asking. The ranking POLICY is what decides
+ * which page an address resolves to, so it is here with `compareRoutes` rather than written out
+ * beside each table: the server's boot and the client router's start compile through one call.
+ */
+export function rankRoutes<T extends { pattern: string }>(
+    rows: T[],
+): (T & { segments: Segment[] })[] {
+    const ranked: (T & { segments: Segment[] })[] = []
+    for (const row of rows)
+        ranked.push({ ...row, segments: parseRoutePattern(row.pattern) })
+    ranked.sort((a, b) => compareRoutes(a.segments, b.segments))
+    return ranked
+}

package/src/shared/rpc.ts

@@ -0,0 +1,496 @@
+// `GET` and the four mutations: a handler given an address (16.2). The IN-PROCESS arm is what a
+// server-side caller, a page rendering on the server and a test all reach; the WIRE arm is what a
+// browser gets in its place (16.28, `#ui/wire.ts`) — and it is `declare` over a body that fetches,
+// which is why this module is in the seam both reach rather than in the server's.
+//
+// A HANDLER IS A `reactive` OR BECOMES ONE (16.1), so an `Rpc` is not a second kind of value: the
+// call hands back the handler's own `Reactive` (16.3), and every probe, trigger and failure on it is
+// the reactive core's — the `Rpc`'s own `busy`, `ready`, `refresh` and `invalidate` are the
+// handler's, passed through. What this file adds is the normalising — a plain function or a value becomes the
+// `reactive` it would have been (16.6) — and the method.
+//
+// A HANDLER DECLARING `middleware` IS REACHED THROUGH ITS RUNGS (16.11), in process as over the wire:
+// the call hands back a value whose body runs the onion once per args, per request, over the
+// handler's own.
+
+import { type Failed, isFailedNamed } from './Failed.ts'
+import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
+import { compose, type Middleware } from './Middleware.ts'
+import { principalRotated } from './principalRotated.ts'
+import { RPC_SERVER } from './RPC_SERVER.ts'
+import {
+    contractOf,
+    type Gated,
+    gateOf,
+    keyOf,
+    normalised,
+} from './reactive/argsContract.ts'
+import { callLoad } from './reactive/callLoad.ts'
+import {
+    type AdoptedFailures,
+    type AdoptedProduced,
+    type ChunkOf,
+    chunksOfStream,
+    handlerValue,
+    isKeyed,
+    type Kept,
+    type Keyed,
+    type OptionalParameter,
+    type Reactive,
+    type Refusals,
+    reactive,
+    type Shaping,
+    STREAMING,
+    type Streams,
+    streamingOrSettled,
+} from './reactive/index.ts'
+import { MUTATION } from './reactive/MUTATION.ts'
+import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
+import { isForwarder } from './reactive/scoped.ts'
+import { checkArgs } from './refuse.ts'
+import { rpcRequest } from './rpcRequest.ts'
+import type { Schema } from './Schema.ts'
+
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+
+/** What a call is handed beside its args (16.48). */
+export type CallOptions = { signal?: AbortSignal }
+
+/**
+ * A declared handler: callable for its `Reactive`, with the handler's own members and its mount.
+ *
+ * 16.3 — the call hands back the handler's own `Reactive`; the members below are the handler's,
+ * passed through.
+ *
+ * 16.8 — AND ITS FAILURES CARRY THE TRANSPORT'S `HttpError`, which no handler declares and every
+ * call can be answered with: a body over `maxBodySize` (413), a closed `crossOrigin` (403), a
+ * `timeout` (504), and any failure status whose body was not a `Failed`, rebuilt by `answered`.
+ */
+export type Rpc<Value, Args, Failures = never, Produced = Value> = ((
+    ...args: undefined extends Args
+        ? [args?: Args, options?: CallOptions]
+        : [args: Args, options?: CallOptions]
+) => Reactive<
+    Value,
+    Value,
+    Failures | Failed<'HttpError', undefined>,
+    Produced
+>) & {
+    method: Method
+    description: string | undefined
+    /**
+     * The handler's own probe, narrowed by a pattern where the handler is keyed.
+     *
+     * 13.4, 13.12 — the handler's own face. An `Rpc` is a `Selection` by having it (13.1).
+     */
+    busy(pattern?: Partial<Args>): boolean
+    ready(pattern?: Partial<Args>): boolean
+    refresh(pattern?: Partial<Args>): void
+    invalidate(pattern?: Partial<Args>): void
+    isError<Name extends string>(
+        error: unknown,
+        name: Name,
+    ): error is Extract<
+        Failures | Failed<'HttpError', undefined>,
+        { name: Name }
+    >
+    /**
+     * The call's address, resolved against the mount.
+     *
+     * 16.9, 16.10 — a mutation's takes no args.
+     */
+    url(...args: undefined extends Args ? [args?: Args] : [args: Args]): string
+    /** The same call, handed back as the `Response` (16.42). */
+    raw(args?: Args, init?: RequestInit): Promise<Response>
+    /** Where the handler is mounted, stamped by whoever mounted it — `undefined` until then. */
+    address: string | undefined
+    keyed: boolean
+    timeout: number | undefined
+    crossOrigin: boolean | string[]
+    maxBodySize: number | undefined
+    clients: Clients
+    /**
+     * Whether the handler declared rungs.
+     *
+     * 18.8 — rungs a value pushed over the mux would not pass.
+     */
+    guarded: boolean
+}
+
+/** Which generated surfaces carry a handler (20.1). */
+export type Clients = {
+    ui?: boolean
+    mcp?: boolean
+    cli?: boolean
+    openapi?: boolean
+}
+
+export type RpcContext<Args = unknown> = { request: Request; args: () => Args }
+
+/**
+ * The context key holding the args as sent.
+ *
+ * 11.26 — THE ARGS AS SENT, carried on the context under a key no rung spells, so the reach at the
+ * onion's centre keys the value by them rather than by what the gate made of them.
+ */
+const SENT: unique symbol = Symbol('abide.sent')
+
+export type RpcOptions<Args = unknown> = {
+    description?: string
+    middleware?: Middleware<RpcContext<Args>, unknown>[]
+    timeout?: number
+    clients?: Clients
+    crossOrigin?: boolean | string[]
+    maxBodySize?: number
+}
+
+/**
+ * A handler `declare` builds the value of: a plain function or a value, which no `Reactive` or
+ * `Keyed` is.
+ *
+ * Told by a member both carry and neither of those does. Without it a value handed in with a
+ * value's option — `GET(reactive(f), { ttl })` — fell through its own arm to a plain one, and the
+ * option was dropped by a value that had already been built.
+ */
+export type Plain = { invalidate?: never }
+
+// The value arm's handler: anything but a function, which is a body, or a `Reactive` or `Keyed`,
+// which has decided its own options. Unguarded, the arm won overload resolution's subtype pass over
+// every function arm, whose `& Plain` only passes assignability. The guard is the whole parameter
+// because `& Plain` kept `GET(0)` the literal `0`, and a bound of `Plain` refuses every primitive.
+type Held<Accepted> = Accepted extends
+    | ((...given: never[]) => unknown)
+    | { invalidate: unknown }
+    ? never
+    : Accepted | PromiseLike<Accepted>
+
+/**
+ * The signature `GET` and the four mutations share: a handler in, its `Rpc` out.
+ *
+ * ONE CALL SIGNATURE PER HANDLER ARM, shared by all five names. The two `reactive` arms come first:
+ * a `Reactive` is itself a `() => Stored`, so the plain-function arm would otherwise swallow it
+ * and type the `Rpc` as holding the value's own getter. The plain arms are `reactive`'s own
+ * overloads, in its order and for its reason, and take its options beside the address's (16.6) —
+ * which is why a value handed in takes the address's alone: it has decided its own.
+ */
+type Declare = {
+    <Stored, Args, Accepted, Failures, Produced>(
+        handler: Keyed<Stored, Args, Accepted, Failures, Produced>,
+        options?: RpcOptions<Args>,
+    ): Rpc<Stored, Args, Failures, Produced>
+    <Stored, Accepted, Failures, Produced>(
+        handler: Reactive<Stored, Accepted, Failures, Produced>,
+        options?: RpcOptions<undefined>,
+    ): Rpc<Stored, undefined, Failures, Produced>
+    // 11.2 — a stream whose parameter is optional is keyed, for `reactive`'s reason.
+    <
+        Body extends (args?: never) => unknown,
+        Shaped = ChunkOf<Body>[],
+        Gate = Schema<ChunkOf<Body>[]>,
+        ArgsGate = Schema<Parameters<Body>[0]>,
+    >(
+        handler: Body & OptionalParameter<Body> & Streams<Body> & Plain,
+        options?: Shaping<
+            ChunkOf<Body>[],
+            Shaped,
+            Parameters<Body>[0],
+            Gate,
+            ArgsGate
+        > &
+            RpcOptions<Parameters<Body>[0]>,
+    ): Rpc<
+        Kept<Shaped>,
+        Parameters<Body>[0],
+        Refusals<Shaped, Gate, ChunkOf<Body>[], ArgsGate, Parameters<Body>[0]>,
+        ChunkOf<Body>
+    >
+    <Chunk, Shaped = Chunk[], Gate = Schema<Chunk[]>>(
+        handler: (() =>
+            | AsyncGenerator<Chunk>
+            | Promise<AsyncGenerator<Chunk>>) &
+            Plain,
+        options?: Shaping<Chunk[], Shaped, never, Gate> & RpcOptions<undefined>,
+    ): Rpc<Kept<Shaped>, undefined, Refusals<Shaped, Gate, Chunk[]>, Chunk>
+    <
+        Chunk,
+        Args,
+        Shaped = Chunk[],
+        Gate = Schema<Chunk[]>,
+        ArgsGate = Schema<Args>,
+    >(
+        handler: ((
+            args: Args,
+        ) => AsyncGenerator<Chunk> | Promise<AsyncGenerator<Chunk>>) &
+            Plain,
+        options?: Shaping<Chunk[], Shaped, Args, Gate, ArgsGate> &
+            RpcOptions<Args>,
+    ): Rpc<
+        Kept<Shaped>,
+        Args,
+        Refusals<Shaped, Gate, Chunk[], ArgsGate, Args>,
+        Chunk
+    >
+    // 11.2 — an optional parameter is keyed, and ahead of the arm below for `reactive`'s reason.
+    <
+        Body extends (args?: never) => unknown,
+        Shaped = Awaited<ReturnType<Body>>,
+        Gate = Schema<Awaited<ReturnType<Body>>>,
+        ArgsGate = Schema<Parameters<Body>[0]>,
+    >(
+        handler: Body & OptionalParameter<Body> & Plain,
+        options?: Shaping<
+            Awaited<ReturnType<Body>>,
+            Shaped,
+            Parameters<Body>[0],
+            Gate,
+            ArgsGate
+        > &
+            RpcOptions<Parameters<Body>[0]>,
+    ): Rpc<
+        Kept<Shaped>,
+        Parameters<Body>[0],
+        | AdoptedFailures<ReturnType<Body>>
+        | Refusals<
+              Shaped,
+              Gate,
+              Awaited<ReturnType<Body>>,
+              ArgsGate,
+              Parameters<Body>[0]
+          >,
+        AdoptedProduced<ReturnType<Body>, Kept<Shaped>>
+    >
+    <Computed, Shaped = Awaited<Computed>, Gate = Schema<Awaited<Computed>>>(
+        handler: (() => Computed) & Plain,
+        options?: Shaping<Awaited<Computed>, Shaped, never, Gate> &
+            RpcOptions<undefined>,
+    ): Rpc<
+        Kept<Shaped>,
+        undefined,
+        AdoptedFailures<Computed> | Refusals<Shaped, Gate, Awaited<Computed>>,
+        AdoptedProduced<Computed, Kept<Shaped>>
+    >
+    <
+        Computed,
+        Args,
+        Shaped = Awaited<Computed>,
+        Gate = Schema<Awaited<Computed>>,
+        ArgsGate = Schema<Args>,
+    >(
+        handler: ((args: Args) => Computed) & Plain,
+        options?: Shaping<Awaited<Computed>, Shaped, Args, Gate, ArgsGate> &
+            RpcOptions<Args>,
+    ): Rpc<
+        Kept<Shaped>,
+        Args,
+        | AdoptedFailures<Computed>
+        | Refusals<Shaped, Gate, Awaited<Computed>, ArgsGate, Args>,
+        AdoptedProduced<Computed, Kept<Shaped>>
+    >
+    // 16.1 — a value, `reactive`'s value overload given an address. Last, so a function is a body.
+    <Accepted, Shaped = Accepted, Gate = Schema<Accepted>>(
+        handler: Held<Accepted>,
+        options?: Shaping<Accepted, Shaped, never, Gate> &
+            RpcOptions<undefined>,
+    ): Rpc<Kept<Shaped>, undefined, Refusals<Shaped, Gate, Accepted>>
+}
+
+/** Builds the handler declarer for one method — what `GET`, `POST` and the rest are. */
+export function declare(method: Method): Declare {
+    return ((handler: unknown, options?: RpcOptions): unknown => {
+        // 16.6, and 16.7's `ttl` of 0 on a mutation: each call is a write, so nothing a previous
+        // call produced is served to the next one. 13.16 — and marked, so a sweep never sends it again.
+        const cacheOptions =
+            method === 'GET' ? undefined : { ttl: 0, [MUTATION]: true as const }
+        // 16.6 — A PLAIN FUNCTION'S VALUE IS BUILT WITH THE WHOLE OPTIONS OBJECT: `reactive` reads
+        // the keys that are its own and passes over the address's, so nothing splits them. 16.7's
+        // `ttl` is a default the handler's own overrides.
+        const value = handlerValue(
+            handler,
+            cacheOptions === undefined
+                ? options
+                : { ...cacheOptions, ...options },
+        )
+        const keyed = isKeyed(value)
+        // 19.7 — the handler's `args` gate and its parameter defaults, on the `Rpc` too, for the
+        // wire to coerce and key by. 11.27, 11.29 — THE DEFAULTS ARE APPLIED AT THE CALL rather than
+        // left to the value's own reach: a value behind rungs is keyed ahead of the handler's, and
+        // the seed buffer files the call by the args it was handed.
+        const contract = contractOf(keyed ? value : undefined)
+        const reach = (args?: unknown): unknown =>
+            keyed ? (value as (args: unknown) => unknown)(args) : value
+        // 16.11, 16.12 — THE RUNGS, IN REGISTRATION ORDER, around the reach. Built once, at the
+        // declaration (16.14); a value keyed by args, so a second call with the same args in one
+        // request joins the first (1.8) and a server files one per request (11.32).
+        const rungs = options?.middleware ?? []
+        // A rung that handed `next` a context of its own making chose those args.
+        const argsOf = (ctx: RpcContext): unknown =>
+            SENT in ctx ? (ctx as { [SENT]: unknown })[SENT] : ctx.args()
+        const contextOf = (args: unknown): RpcContext =>
+            ({
+                request: RPC_SERVER.request(),
+                args: argsOnce(gateOf(contract), args),
+                [SENT]: args,
+            }) as RpcContext
+        // 16.32 BEHIND RUNGS — A STREAM'S CHUNKS ARE FORWARDED, not collected. The centre of the
+        // onion is an async function, and a `Reactive` is thenable (1.4), so handing a streaming value
+        // out through it would wait out the whole run and answer the accumulation once it closed. So
+        // the centre waits only until the value settles or turns out to stream (9.6), and hands a
+        // stream on as its chunks — a generator, which is not thenable. The value the call reaches
+        // resolves to it and is a stream of its own from then (9.6), so a second call joining it
+        // (1.8) reads the same accumulation. A refusal a rung answers with is the value's refusal.
+        const onion =
+            rungs.length === 0
+                ? null
+                : compose(rungs, async (ctx: RpcContext) => {
+                      const reached = reach(argsOf(ctx))
+                      const started = performance.now()
+                      try {
+                          const settled = await streamingOrSettled(reached)
+                          return settled === STREAMING
+                              ? chunksOfStream(reached)
+                              : settled
+                      } finally {
+                          RPC_SERVER.handled?.(rpc, performance.now() - started)
+                      }
+                  })
+        const wrapped =
+            onion === null
+                ? null
+                : reactive(
+                      (args: unknown) => onion(contextOf(args)),
+                      cacheOptions,
+                  )
+        const reachThrough =
+            wrapped === null ? reach : (wrapped as (args: unknown) => unknown)
+        // 16.3 — the handler's own `Reactive`. A `Keyed` reaches its entry, which is 1.7's start
+        // and 1.8's join; an unkeyed value has one entry and the call is the reach of it.
+        //
+        // 41.13 — AND REPORTED, where the call is made in a page's render: the browser's own call for
+        // this handler and these args is then answered from what this one reached, rather than by
+        // running the handler again. In a browser nothing fills the slot, so the report is one load
+        // of a `null`.
+        const call = (given?: unknown, options?: CallOptions): unknown => {
+            const args = normalised(contract, given)
+            const reached = callLoad(
+                reachThrough,
+                args,
+                options?.signal,
+                rpc.timeout ?? RPC_SERVER.timeout(),
+            )
+            RPC_SERVER.reached?.(rpc, args, reached)
+            return reached
+        }
+        // THE HANDLER'S OWN MEMBERS, handed the pattern. A `Keyed` narrows by it and a `Reactive`'s
+        // take no argument, so one spelling serves both arms and neither is a second mechanism.
+        const face = value as Record<
+            (typeof SELECTION_MEMBERS)[number],
+            (pattern?: unknown) => unknown
+        >
+        const rpc = Object.assign(call, contract, {
+            method,
+            description: options?.description,
+            address: undefined as string | undefined,
+            // 20.9 — which arm the handler took, which is what MCP lists it by.
+            keyed,
+            timeout: options?.timeout,
+            crossOrigin: options?.crossOrigin ?? false,
+            maxBodySize: options?.maxBodySize,
+            clients: options?.clients ?? {},
+            guarded: rungs.length > 0,
+            isError: isFailedNamed,
+            url(args?: Record<string, unknown>): string {
+                return rpcRequest(method, addressOf(rpc), args).url
+            },
+            raw(
+                args?: Record<string, unknown>,
+                init?: RequestInit,
+            ): Promise<Response> {
+                const asked = rpcRequest(method, addressOf(rpc), args)
+                // `Headers`, not a spread — the caller's may be a `Headers` itself, which spreads empty.
+                const headers = new Headers(asked.init.headers)
+                for (const [name, value] of new Headers(init?.headers))
+                    headers.set(name, value)
+                const given: RequestInit = { ...asked.init, ...init, headers }
+                // IN PROCESS ON A SERVER, through the app the process holds; OVER THE WIRE elsewhere.
+                if (RPC_SERVER.raw !== null)
+                    return RPC_SERVER.raw(
+                        new Request(
+                            new URL(asked.url, 'http://app.internal'),
+                            given,
+                        ),
+                    )
+                // 26.24 — a sign-in made raw is still a sign-in.
+                return fetch(asked.url, given).then((answer) => {
+                    principalRotated(answer)
+                    return answer
+                })
+            },
+        }) satisfies Gated<unknown>
+        const members = rpc as unknown as Record<string, unknown>
+        // 7.10, 7.18 — A TRIGGER ON A SERVER REACHES EVERY BROWSER HOLDING WHAT IT NAMES, through the
+        // mux (18.3). `null` in a browser, where the trigger is the copy's own.
+        for (const name of SELECTION_MEMBERS)
+            members[name] =
+                name === 'invalidate' || name === 'refresh'
+                    ? (pattern?: unknown): unknown => {
+                          const done = face[name](pattern)
+                          RPC_SERVER.broadcast?.(rpc, name, pattern)
+                          return done
+                      }
+                    : (pattern?: unknown): unknown => face[name](pattern)
+        // 21.8, 18.5 — a `GET` over a `global` value, the value it is serving for some args: a cache
+        // may hold it for as long as it lives, and the mux may feed it. A request-local one is a
+        // forwarder to a value built per request (11.32).
+        //
+        // READ OFF THE VALUE rather than off the call: behind a rung the call settles to what the
+        // value produced, and holds no way back to it. A keyed value is looked up without a reach,
+        // so asking starts nothing (11.55).
+        if (method === 'GET' && !isForwarder(value))
+            GLOBAL_GETS.set(rpc, (args: unknown): unknown =>
+                keyed
+                    ? (value as { entries: Map<string, unknown> }).entries.get(
+                          keyOf(contract, args),
+                      )
+                    : value,
+            )
+        return rpc
+    }) as Declare
+}
+
+export const GET: Declare = declare('GET')
+export const POST: Declare = declare('POST')
+export const PUT: Declare = declare('PUT')
+export const PATCH: Declare = declare('PATCH')
+export const DELETE: Declare = declare('DELETE')
+
+/** The handler's mount address, or a throw naming where one comes from. */
+function addressOf(rpc: { address: string | undefined }): string {
+    if (rpc.address === undefined)
+        throw new Error(
+            'abide: this handler has no address yet. A handler is given one where it is mounted, under src/server/rpc (16.2).',
+        )
+    return rpc.address
+}
+
+/**
+ * A rung's `ctx.args()`: the args validated on the first ask, and that answer kept after it.
+ *
+ * 16.17, 16.18, 16.19 — validated against the `args` the value declared on the first ask, and the
+ * answer kept for every rung after it. A refusal is thrown, so it leaves the whole onion (16.21)
+ * and is answered at its own status.
+ */
+function argsOnce(
+    gate: Schema<unknown> | undefined,
+    args: unknown,
+): () => unknown {
+    let asked = false
+    let answer: unknown
+    return () => {
+        if (asked) return answer
+        // Validated BEFORE it is marked asked, so a rung that caught the refusal and asks again is
+        // refused again rather than handed nothing.
+        answer = gate === undefined ? args : checkArgs(gate, args)
+        asked = true
+        return answer
+    }
+}