@abide/abide 0.48.0 → 0.50.0

package/src/lib/shared/createRpcServerProgram.ts

@@ -0,0 +1,820 @@
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { HTTP_METHODS } from './HTTP_METHODS.ts'
+import { jsonSchemaForType } from './jsonSchemaForType.ts'
+import { loadProjectTsConfig } from './loadProjectTsConfig.ts'
+import type { ErrorJsonSchemas } from './types/ErrorJsonSchemas.ts'
+import type { HttpMethod } from './types/HttpMethod.ts'
+import type { InputCoercion } from './types/InputCoercion.ts'
+import type { OutputWirePlan } from './types/OutputWirePlan.ts'
+import type { ReturnBody } from './types/ReturnBody.ts'
+import type { WireKind } from './types/WireKind.ts'
+
+const RPC_HELPERS = new Set<string>(HTTP_METHODS)
+const NUMBER_FLAGS = ts.TypeFlags.Number | ts.TypeFlags.NumberLiteral
+const BOOLEAN_FLAGS = ts.TypeFlags.Boolean | ts.TypeFlags.BooleanLiteral
+const BIGINT_FLAGS = ts.TypeFlags.BigInt | ts.TypeFlags.BigIntLiteral
+const NULLISH_FLAGS = ts.TypeFlags.Undefined | ts.TypeFlags.Null | ts.TypeFlags.Void
+// Only `undefined`/`void` make a property OPTIONAL (a `T | null` is a required-but-nullable field).
+const OPTIONALITY_FLAGS = ts.TypeFlags.Undefined | ts.TypeFlags.Void
+
+export type RpcServerProgram = {
+    /*
+    Whether the rpc module at `modulePath` has a STREAMING handler, decided through the
+    type graph: the handler's return type resolves to a `TypedResponse<AsyncIterable<…>>`
+    (the branded shape only `jsonl()`/`sse()` produce). Returns true/false when the export
+    call site and a call signature are found — INCLUDING when the stream is produced through
+    a wrapper function, the case the char-scan `detectStreaming` misses. undefined when the
+    module or its export call can't be resolved, so the caller fails open to the scan.
+    */
+    streamingForModule(modulePath: string): boolean | undefined
+    /*
+    The rpc's HTTP method, read from the export binding's helper SYMBOL (aliases and
+    re-exports followed through the checker) rather than the callee's source text. So an
+    `import { GET as read }` / a re-exported helper resolves to `GET`, where the `RPC_EXPORT`
+    regex — keyed on the literal helper name — misses it. undefined when the export call or
+    its helper symbol can't be resolved, so the caller fails open to `detectRpcMethod`.
+    */
+    methodForModule(modulePath: string): HttpMethod | undefined
+    /*
+    The input-args wire codec plan (ADR-0028 scalars, ADR-0029 structured): the endpoint's wire
+    `Args` type read off the exported RemoteFunction's call signature, projected to the
+    number/boolean/date/bigint/set/map fields parseArgs revives a plain-JSON wire value into. Reads
+    `InferInput` (the wire shape the schema validates), so a self-coercing schema whose input is
+    loose is correctly left uncoerced. undefined when the export call or its Args type can't be
+    resolved, or no field is a recognized WireKind — the caller then stamps no plan, so a GET field
+    stays a string exactly as today.
+    */
+    inputCoercionForModule(modulePath: string): InputCoercion | undefined
+    /*
+    The output-args wire codec plan (ADR-0029 output path): the endpoint's success RESPONSE body type
+    (resolved the same way `returnBodyForModule`/`walkSuccessBodies` read it — unwrap `Promise`, drop
+    the `TypedError` branches) projected to the structured `date`/`bigint`/`set`/`map` fields the
+    client proxy revives from a decoded response. The response-side sibling of
+    `inputCoercionForModule`: it is baked onto the CLIENT `remoteProxy` stub (not the server
+    `defineRpc`), so an abide client revives a `Set`/`Map`/`bigint`/`Date` the server encoded to
+    honest JSON. Only the structured kinds are listed — `number`/`boolean` already ride as their JSON
+    type. undefined when the export call or its success body can't be resolved, or no field is a
+    structured WireKind, so the client bakes no plan and a response array stays an array.
+    */
+    outputWirePlanForModule(modulePath: string): OutputWirePlan | undefined
+    /*
+    The endpoint's success-BODY type (ADR-0030), read from the handler's return type the same way
+    streaming detection reads it: unwrap `Promise`, drop the `TypedError` branches, take each
+    success `TypedResponse<Body>` body. `type` is that body rendered as a TS type string; a
+    streaming endpoint reports `streaming: true` and the per-FRAME type (the `AsyncIterable`
+    element) so a surface describes one streamed item. This is the output-side sibling of
+    `inputCoercionForModule` — the handler's return is the single source for the generated surfaces
+    (`.d.ts`/OpenAPI 200/MCP outputSchema) instead of a hand-written `schemas.output`. undefined
+    when the export call or its handler body type can't be resolved, so a consumer falls open to an
+    author-declared `schemas.output`.
+    */
+    returnBodyForModule(modulePath: string): ReturnBody | undefined
+    /*
+    The endpoint's success-body projected to JSON Schema (ADR-0030 D2), for the OpenAPI 200 / MCP
+    outputSchema / inspector surface when the author declared no `schemas.output` validator. Resolves
+    the same success-body `ts.Type`(s) `returnBodyForModule` reads — unwrap `Promise`, drop the
+    `TypedError` branches, frame-unwrap a streaming body — then projects each through
+    `jsonSchemaForType`, combining multiple success branches under `anyOf`. undefined when no body
+    resolves or the projection is bare permissive `{}`, so a surface omits the schema exactly as today
+    when no `schemas.output` is declared. The build stamps the resolved schema into the server
+    `defineRpc` call (like the ADR-0028 `coerce` plan) so the runtime registry can carry it.
+    */
+    returnBodySchemaForModule(modulePath: string): Record<string, unknown> | undefined
+    /*
+    The endpoint's typed-error branches surfaced as a status-keyed JSON-Schema map (ADR-0030) — the
+    error-branch sibling of `returnBodySchemaForModule`. Walks the SAME return union but KEEPS the
+    `TypedError` branches success projection drops: for each, reads the `error.typed(name, status,
+    schema?)` brand's numeric `status` and projects the error's `data` type (its schema's
+    `~standard.types.input`) through `jsonSchemaForType`. Errors sharing a status combine under
+    `anyOf`; a nullary error (no data) contributes a bare `{}` so the status still surfaces. undefined
+    when no handler signature resolves or the handler declares no typed errors, so a consumer omits
+    the error responses exactly as today. The build stamps the resolved map into the server
+    `defineRpc` call (like `outputJsonSchema`) so the runtime registry can carry it to OpenAPI.
+    */
+    errorSchemasForModule(modulePath: string): ErrorJsonSchemas | undefined
+    /*
+    The endpoint's INPUT args projected to JSON Schema (ADR-0030 input side — the input-surface
+    sibling of `returnBodySchemaForModule`), for the OpenAPI parameters/request body / MCP
+    inputSchema / inspector input surface when the author declared no `schemas.input` VALIDATOR.
+    Resolves the SAME wire `Args` bag `inputCoercionForModule` reads — the exported RemoteFunction's
+    first call-signature parameter, with the multipart `FormData` member dropped — then projects each
+    property through `jsonSchemaForType` into an object schema. File-typed properties are EXCLUDED
+    exactly as `filesSchema` keeps File parts out of the `inputSchema` projection (a File has no
+    honest JSON-Schema form). This is a SHAPE description only: it is never wired into runtime
+    validation, so it can never produce a 422 — an author who wants that still declares
+    `schemas.input`, which also OVERRIDES this projection on every surface. undefined when no call
+    signature / Args bag resolves or every property is excluded, so the surface behaves as today. The
+    build stamps the resolved schema into the server `defineRpc` call so the runtime registry carries
+    it.
+    */
+    inputSchemaForModule(modulePath: string): Record<string, unknown> | undefined
+}
+
+/*
+Warms one `ts.Program` over every `.ts` under `rpcDir`, reused across every rpc transform
+in the root (ADR-0025 D1 — the server-side mirror of the UI shadow program). The handler's
+transitive imports resolve on demand through the default compiler host, so the type queries
+see the real `jsonl()`/`sse()` return shape, the aliased helper's origin symbol, and an
+imported const's literal type. Type queries only — never emits, never reports diagnostics; a
+module that fails to type-check still yields its answers. Building is the expensive step (a
+few hundred ms once per root), so the resolver plugin caches it per-root and builds it lazily
+on the first rpc transform.
+*/
+export function createRpcServerProgram(cwd: string, rpcDir: string): RpcServerProgram {
+    const rpcFiles = [...new Bun.Glob('**/*.ts').scanSync({ cwd: rpcDir, onlyFiles: true })].map(
+        (relative) => resolve(rpcDir, relative),
+    )
+    const { options } = loadProjectTsConfig(cwd)
+    const program = ts.createProgram({ rootNames: rpcFiles, options })
+    const checker = program.getTypeChecker()
+    /* Every query fails open to its char-scan/regex counterpart: an unresolved module or any
+       checker throw yields undefined so a type-resolution hiccup never breaks a build (ADR-0025
+       D3). */
+    const query = <T>(
+        modulePath: string,
+        read: (call: ResolvedRpcCall) => T | undefined,
+    ): T | undefined => {
+        try {
+            const sourceFile = program.getSourceFile(modulePath)
+            if (sourceFile === undefined) {
+                return undefined
+            }
+            const call = resolveRpcCall(checker, sourceFile)
+            if (call === undefined) {
+                return undefined
+            }
+            return read(call)
+        } catch {
+            return undefined
+        }
+    }
+    return {
+        streamingForModule(modulePath) {
+            return query(modulePath, (call) => handlerReturnsStream(checker, call.node))
+        },
+        methodForModule(modulePath) {
+            return query(modulePath, (call) => call.method)
+        },
+        inputCoercionForModule(modulePath) {
+            return query(modulePath, (call) => inputCoercionPlan(checker, call.node))
+        },
+        outputWirePlanForModule(modulePath) {
+            return query(modulePath, (call) => outputWirePlan(checker, call.node))
+        },
+        returnBodyForModule(modulePath) {
+            return query(modulePath, (call) => handlerReturnBody(checker, call.node))
+        },
+        returnBodySchemaForModule(modulePath) {
+            return query(modulePath, (call) => returnBodyJsonSchema(checker, call.node))
+        },
+        errorSchemasForModule(modulePath) {
+            return query(modulePath, (call) => errorBranchSchemas(checker, call.node))
+        },
+        inputSchemaForModule(modulePath) {
+            return query(modulePath, (call) => inputArgsJsonSchema(checker, call.node))
+        },
+    }
+}
+
+type ResolvedRpcCall = {
+    /* The exported `<METHOD>(handler, opts?)` CallExpression. */
+    node: ts.CallExpression
+    /* The method the callee's helper symbol resolves to (alias/re-export followed). */
+    method: HttpMethod
+}
+
+/*
+The module's exported rpc call — the initializer of `export const <name> = <helper>(…)` whose
+callee resolves (through the checker, following import aliases and re-exports) to one of the
+rpc helper symbols. Scoped to top-level exported const initializers, so a nested `jsonl(` in a
+handler body can't match and an aliased helper (`import { GET as read }`) still resolves. undefined
+when no such export exists — the caller falls back to the char-scan.
+*/
+function resolveRpcCall(
+    checker: ts.TypeChecker,
+    sourceFile: ts.SourceFile,
+): ResolvedRpcCall | undefined {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue
+        }
+        const isExported = statement.modifiers?.some(
+            (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+        )
+        if (!isExported) {
+            continue
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            const initializer = declaration.initializer
+            if (initializer === undefined || !ts.isCallExpression(initializer)) {
+                continue
+            }
+            const method = methodOfCallee(checker, initializer.expression)
+            if (method !== undefined) {
+                return { node: initializer, method }
+            }
+        }
+    }
+    return undefined
+}
+
+/*
+The HTTP method a call's callee names — the origin helper symbol's name, following import
+aliases and re-exports through the checker (so `read` from `import { GET as read }` yields
+`GET`). Falls back to the callee's own identifier text when the symbol doesn't resolve, so a
+bare `GET(` still reads as `GET` even if type resolution hiccups. undefined when neither is an
+rpc helper.
+*/
+function methodOfCallee(checker: ts.TypeChecker, callee: ts.Expression): HttpMethod | undefined {
+    if (!ts.isIdentifier(callee)) {
+        return undefined
+    }
+    let symbol = checker.getSymbolAtLocation(callee)
+    if (symbol !== undefined && symbol.flags & ts.SymbolFlags.Alias) {
+        symbol = checker.getAliasedSymbol(symbol)
+    }
+    const resolvedName = symbol?.getName()
+    if (resolvedName !== undefined && RPC_HELPERS.has(resolvedName)) {
+        return resolvedName as HttpMethod
+    }
+    if (RPC_HELPERS.has(callee.text)) {
+        return callee.text as HttpMethod
+    }
+    return undefined
+}
+
+/*
+The rpc export's handler return type, tested for the streaming brand. undefined when no handler
+call signature is found — the caller falls back to the char-scan. A resolvable handler that
+returns a plain value yields `false` (definitively not streaming), so a warm program does not
+needlessly defer to the scan for ordinary handlers.
+*/
+function handlerReturnsStream(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): boolean | undefined {
+    const handler = call.arguments[0]
+    if (handler === undefined) {
+        return undefined
+    }
+    const signature = checker.getTypeAtLocation(handler).getCallSignatures()[0]
+    if (signature === undefined) {
+        return undefined
+    }
+    const returnType = unwrapPromise(checker, checker.getReturnTypeOfSignature(signature))
+    return returnTypeIsStreaming(checker, returnType)
+}
+
+/* An async handler returns `Promise<TypedResponse<…>>`; unwrap one Promise layer so the
+   brand check sees the response type. */
+function unwrapPromise(checker: ts.TypeChecker, type: ts.Type): ts.Type {
+    if (type.getSymbol()?.name === 'Promise') {
+        const inner = checker.getTypeArguments(type as ts.TypeReference)[0]
+        if (inner !== undefined) {
+            return inner
+        }
+    }
+    return type
+}
+
+/* True when the type is (or, across a union of return branches, contains) a
+   `TypedResponse<AsyncIterable<…>>` — a `__body` phantom property whose type is async-iterable.
+   `jsonl()`/`sse()` are the only constructors of that shape, so this is congruent by
+   construction with the RemoteCallable streaming conditional. */
+function returnTypeIsStreaming(checker: ts.TypeChecker, type: ts.Type): boolean {
+    if (type.isUnion()) {
+        return type.types.some((member) => returnTypeIsStreaming(checker, member))
+    }
+    const bodyProperty = type.getProperty('__body')
+    if (bodyProperty === undefined) {
+        return false
+    }
+    const declaration = bodyProperty.valueDeclaration ?? bodyProperty.declarations?.[0]
+    if (declaration === undefined) {
+        return false
+    }
+    return typeIsAsyncIterable(
+        checker,
+        checker.getTypeOfSymbolAtLocation(bodyProperty, declaration),
+    )
+}
+
+/* Async-iterable iff the type exposes a `[Symbol.asyncIterator]` member — the computed
+   well-known symbol surfaces as an `__@asyncIterator@<n>` property name. Recurses through a
+   union so `AsyncIterable<A> | AsyncIterable<B>` still counts. */
+function typeIsAsyncIterable(checker: ts.TypeChecker, type: ts.Type): boolean {
+    if (type.isUnion()) {
+        return type.types.some((member) => typeIsAsyncIterable(checker, member))
+    }
+    for (const property of checker.getPropertiesOfType(type)) {
+        if (property.getName().includes('asyncIterator')) {
+            return true
+        }
+    }
+    return false
+}
+
+/*
+The rpc export's success-body descriptor (ADR-0030), projected from the handler's return type the
+same way `handlerReturnsStream` reads it — unwrap one `Promise` layer, then walk the return union.
+This mirrors `RpcHelper`'s `SuccessBody<R>`: a `TypedError` branch (its `__abideError` brand) is an
+error response and is dropped; every success `TypedResponse<Body>` (its `__body` phantom) yields its
+body. A branch is a streaming body when the body is async-iterable, in which case its per-FRAME type
+(the `AsyncIterable` element) is taken and the descriptor marked streaming. undefined when no handler
+call signature or no success body resolves — the caller falls open to an author-declared schema.
+*/
+function handlerReturnBody(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): ReturnBody | undefined {
+    const rendered: string[] = []
+    let streaming = false
+    const resolved = walkSuccessBodies(checker, call, (part, isStreaming) => {
+        if (isStreaming) {
+            streaming = true
+        }
+        // An untagged Response (no `__body` phantom) has an `unknown` success body — SuccessBody's fallback.
+        pushUnique(rendered, part === undefined ? 'unknown' : checker.typeToString(part))
+    })
+    if (!resolved || rendered.length === 0) {
+        return undefined
+    }
+    return { type: rendered.join(' | '), streaming }
+}
+
+/*
+The rpc export's success body projected to JSON Schema (ADR-0030 D2) — the output-surface sibling of
+`handlerReturnBody`, walking the identical success-body constituents but projecting each through
+`jsonSchemaForType` instead of rendering a TS string. Multiple success branches combine under `anyOf`;
+an untagged/unprojectable body contributes the permissive `{}`. undefined when no handler signature
+resolves or the combined schema is bare permissive `{}` — the caller falls open to an author-declared
+`schemas.output`.
+*/
+function returnBodyJsonSchema(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): Record<string, unknown> | undefined {
+    const schemas: Record<string, unknown>[] = []
+    const resolved = walkSuccessBodies(checker, call, (part) => {
+        const projected = part === undefined ? undefined : jsonSchemaForType(checker, part)
+        pushUniqueSchema(schemas, projected ?? {})
+    })
+    if (!resolved || schemas.length === 0) {
+        return undefined
+    }
+    const [onlySchema] = schemas
+    const combined =
+        schemas.length === 1 && onlySchema !== undefined ? onlySchema : { anyOf: schemas }
+    return Object.keys(combined).length === 0 ? undefined : combined
+}
+
+/*
+Walks a handler's success-body constituents, shared by `handlerReturnBody` (renders each to a TS
+string) and `returnBodyJsonSchema` (projects each to JSON Schema) so the two surfaces stay congruent.
+Unwraps one `Promise`, then over the return union drops the `TypedError` branches (their `__abideError`
+brand) and, for each success `TypedResponse<Body>` (its `__body` phantom), visits every meaningful body
+part — frame-unwrapped and flagged streaming when async-iterable. `visit` receives undefined for an
+untagged Response (its body is `unknown`). Returns false when no handler call signature resolves, so
+callers fail open.
+*/
+function walkSuccessBodies(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+    visit: (part: ts.Type | undefined, streaming: boolean) => void,
+): boolean {
+    const members = returnUnionMembers(checker, call)
+    if (members === undefined) {
+        return false
+    }
+    for (const member of members) {
+        if (member.getProperty('__abideError') !== undefined) {
+            continue
+        }
+        const bodyProperty = member.getProperty('__body')
+        if (bodyProperty === undefined) {
+            visit(undefined, false)
+            continue
+        }
+        const declaration = bodyProperty.valueDeclaration ?? bodyProperty.declarations?.[0]
+        if (declaration === undefined) {
+            visit(undefined, false)
+            continue
+        }
+        // The `__body?` phantom is optional, so reading its type adds a spurious `| undefined`;
+        // drop the nullish members (indistinguishable from an authored optional body — the surface
+        // describes the present value's shape either way).
+        const bodyType = checker.getTypeOfSymbolAtLocation(bodyProperty, declaration)
+        for (const part of meaningfulMembers(bodyType)) {
+            if (typeIsAsyncIterable(checker, part)) {
+                visit(asyncIterableElement(checker, part) ?? part, true)
+            } else {
+                visit(part, false)
+            }
+        }
+    }
+    return true
+}
+
+/* The handler's return-type union members — the shared front of both the success walk
+   (`walkSuccessBodies`) and the error walk (`errorBranchSchemas`): resolve the handler call
+   signature, unwrap one `Promise` layer, then split the union (a lone return is a one-member list).
+   undefined when no handler call signature resolves, so both callers fail open. */
+function returnUnionMembers(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): ts.Type[] | undefined {
+    const handler = call.arguments[0]
+    if (handler === undefined) {
+        return undefined
+    }
+    const signature = checker.getTypeAtLocation(handler).getCallSignatures()[0]
+    if (signature === undefined) {
+        return undefined
+    }
+    const returnType = unwrapPromise(checker, checker.getReturnTypeOfSignature(signature))
+    return returnType.isUnion() ? returnType.types : [returnType]
+}
+
+/*
+The handler's typed-error branches projected to a status-keyed JSON-Schema map (ADR-0030) — the
+error-branch sibling of `returnBodyJsonSchema`, walking the SAME return union but keeping the
+`TypedError` members the success walk drops. For each `__abideError`-branded branch it reads the
+brand's numeric `entry.status` (a literal, captured by `error.typed`'s `Status` type param) and
+projects the error's `data` type (its schema's `~standard.types.input`) through `jsonSchemaForType`.
+Branches sharing a status combine their distinct data schemas under `anyOf`; a nullary error (no
+`data`) contributes a bare `{}` so the status still surfaces. undefined when no handler signature
+resolves or no typed-error branch is present, so the caller stamps nothing and the surface omits the
+error responses exactly as today.
+*/
+function errorBranchSchemas(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): ErrorJsonSchemas | undefined {
+    const members = returnUnionMembers(checker, call)
+    if (members === undefined) {
+        return undefined
+    }
+    // Status → its collected distinct data schemas (empty when only nullary errors share the status).
+    const byStatus = new Map<number, Record<string, unknown>[]>()
+    for (const member of members) {
+        const brand = member.getProperty('__abideError')
+        if (brand === undefined) {
+            continue
+        }
+        const entry = memberType(checker, checker.getTypeOfSymbol(brand), 'entry')
+        if (entry === undefined) {
+            continue
+        }
+        const status = numberLiteral(memberType(checker, entry, 'status'))
+        if (status === undefined) {
+            continue
+        }
+        let schemas = byStatus.get(status)
+        if (schemas === undefined) {
+            schemas = []
+            byStatus.set(status, schemas)
+        }
+        const dataSchema = errorDataSchema(checker, memberType(checker, entry, 'data'))
+        if (dataSchema !== undefined) {
+            pushUniqueSchema(schemas, dataSchema)
+        }
+    }
+    if (byStatus.size === 0) {
+        return undefined
+    }
+    const result: ErrorJsonSchemas = {}
+    for (const [status, schemas] of byStatus) {
+        const [onlySchema] = schemas
+        result[status] =
+            schemas.length === 0
+                ? {}
+                : schemas.length === 1 && onlySchema !== undefined
+                  ? onlySchema
+                  : { anyOf: schemas }
+    }
+    return result
+}
+
+/* An error branch's `data` type projected to JSON Schema — navigates the schema brand's phantom
+   `~standard.types.input` (the data payload the `error.typed` constructor receives) and projects it
+   via `jsonSchemaForType`. undefined for a nullary error (its `entry.data` is `undefined`, so the
+   `~standard` chain doesn't resolve) or an unprojectable/permissive data type, so the status
+   surfaces without a content schema. */
+function errorDataSchema(
+    checker: ts.TypeChecker,
+    dataType: ts.Type | undefined,
+): Record<string, unknown> | undefined {
+    if (dataType === undefined) {
+        return undefined
+    }
+    const standard = memberType(checker, dataType, '~standard')
+    if (standard === undefined) {
+        return undefined
+    }
+    // `types` is `{ input; output } | undefined` (the spec's optional phantom) — take the non-nullish member.
+    const types = memberType(checker, standard, 'types')
+    if (types === undefined) {
+        return undefined
+    }
+    const input = memberType(checker, nonNullishType(types), 'input')
+    if (input === undefined) {
+        return undefined
+    }
+    return jsonSchemaForType(checker, input)
+}
+
+/* A named property's type, read location-free off a resolved type. undefined when the type has no
+   such property — the phantom-navigation guard for the error brand's nested `entry`/`status`/`data`
+   / `~standard`/`types`/`input` chain. */
+function memberType(checker: ts.TypeChecker, type: ts.Type, name: string): ts.Type | undefined {
+    const symbol = type.getProperty(name)
+    return symbol === undefined ? undefined : checker.getTypeOfSymbol(symbol)
+}
+
+/* A type's numeric-literal value (e.g. `404`), or undefined when it isn't a single number literal
+   (a widened `number`, a union, or undefined) — so a computed error status the type can't pin down
+   is skipped rather than guessed. */
+function numberLiteral(type: ts.Type | undefined): number | undefined {
+    if (type === undefined || (type.flags & ts.TypeFlags.NumberLiteral) === 0) {
+        return undefined
+    }
+    return (type as ts.NumberLiteralType).value
+}
+
+/* Drops the nullish members of a `T | undefined` union, returning the lone survivor; else the type
+   unchanged (a non-union or a genuine multi-member union stays as-is). Used to strip the spec's
+   optional `types?` phantom down to its concrete `Types` object. */
+function nonNullishType(type: ts.Type): ts.Type {
+    if (!type.isUnion()) {
+        return type
+    }
+    const kept = type.types.filter((member) => (member.flags & NULLISH_FLAGS) === 0)
+    const [onlyKept] = kept
+    return kept.length === 1 && onlyKept !== undefined ? onlyKept : type
+}
+
+/* The non-nullish constituents of a body type — a single-element list for a non-union, else the
+   union's members with `undefined`/`null`/`void` dropped (the `__body?` phantom's optionality). All
+   members nullish (an unusual `undefined`-only body) keeps them so something still renders. */
+function meaningfulMembers(type: ts.Type): ts.Type[] {
+    if (!type.isUnion()) {
+        return [type]
+    }
+    const kept = type.types.filter((member) => (member.flags & NULLISH_FLAGS) === 0)
+    return kept.length > 0 ? kept : type.types
+}
+
+/* The element type of an `AsyncIterable<Frame>` (or the AsyncIterableIterator/AsyncGenerator a
+   generator produces) — the per-frame type `jsonl()`/`sse()` streams. undefined when the type isn't
+   one of those references, so the caller renders the whole body instead. */
+function asyncIterableElement(checker: ts.TypeChecker, type: ts.Type): ts.Type | undefined {
+    const name = type.getSymbol()?.name
+    if (name === 'AsyncIterable' || name === 'AsyncIterableIterator' || name === 'AsyncGenerator') {
+        return checker.getTypeArguments(type as ts.TypeReference)[0]
+    }
+    return undefined
+}
+
+/* Appends `value` only when not already present, so a union of identical success branches renders
+   once (the rendered list stays a small monomorphic string array). */
+function pushUnique(list: string[], value: string): void {
+    if (!list.includes(value)) {
+        list.push(value)
+    }
+}
+
+/* Appends a projected schema only when structurally new, so identical success branches contribute one
+   `anyOf` member. Dedup by serialization — the schema objects are small plain data, and this build
+   path runs once per rpc. */
+function pushUniqueSchema(list: Record<string, unknown>[], schema: Record<string, unknown>): void {
+    const serialized = JSON.stringify(schema)
+    if (!list.some((existing) => JSON.stringify(existing) === serialized)) {
+        list.push(schema)
+    }
+}
+
+/*
+The wire codec plan for an rpc export's input args (ADR-0028 scalars, ADR-0029 structured). The
+export's type is its RemoteFunction; its call signature's first parameter is the wire `Args` type
+(`InferInput` of the input schema, or the handler's annotated param when schemaless). Each
+number/boolean/date/bigint/set/map field of that Args object becomes a plan entry; every other
+field is omitted. undefined when the RemoteFunction has no call signature, the Args aren't a
+single object type, or no field is a recognized WireKind — the caller then ships no plan (today's
+string-through behavior).
+*/
+function inputCoercionPlan(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): InputCoercion | undefined {
+    const signature = checker.getTypeAtLocation(call).getCallSignatures()[0]
+    if (signature === undefined) {
+        return undefined
+    }
+    const parameter = signature.getParameters()[0]
+    if (parameter === undefined) {
+        return undefined
+    }
+    const argsType = argsBagType(checker.getTypeOfSymbolAtLocation(parameter, call))
+    if (argsType === undefined) {
+        return undefined
+    }
+    const plan: InputCoercion = {}
+    for (const property of argsType.getProperties()) {
+        const kind = wireKind(checker, checker.getTypeOfSymbolAtLocation(property, call))
+        if (kind !== undefined) {
+            plan[property.getName()] = kind
+        }
+    }
+    /* An empty plan (no codec-eligible field) ships nothing, so no opts are injected. */
+    return Object.keys(plan).length === 0 ? undefined : plan
+}
+
+/*
+The wire codec plan for an rpc export's success RESPONSE body (ADR-0029 output path) — the
+response-side sibling of `inputCoercionPlan`. Walks the handler's success-body constituents the same
+way the ADR-0030 surfaces do (`walkSuccessBodies` — unwrap `Promise`, drop the `TypedError` branches)
+and, for each OBJECT body, reads each property's `WireKind` and keeps only the STRUCTURED kinds
+(`date`/`bigint`/`set`/`map`) the client revives — `number`/`boolean` already ride as their JSON type.
+A streaming body is skipped (its frame encoding is deferred). undefined when no handler signature
+resolves or no structured field is present, so the client bakes no plan.
+*/
+function outputWirePlan(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): OutputWirePlan | undefined {
+    const plan: OutputWirePlan = {}
+    const resolved = walkSuccessBodies(checker, call, (part, streaming) => {
+        /* Frame-level encoding for jsonl()/sse() is deferred (ADR-0029), and an untagged Response
+           body is `unknown` — neither yields a top-level field plan. */
+        if (streaming || part === undefined) {
+            return
+        }
+        for (const property of part.getProperties()) {
+            const kind = wireKind(checker, checker.getTypeOfSymbol(property))
+            if (kind === 'date' || kind === 'bigint' || kind === 'set' || kind === 'map') {
+                plan[property.getName()] = kind
+            }
+        }
+    })
+    if (!resolved || Object.keys(plan).length === 0) {
+        return undefined
+    }
+    return plan
+}
+
+/*
+The rpc export's INPUT args projected to JSON Schema (ADR-0030 input side) — the input-surface
+sibling of `returnBodyJsonSchema`. Resolves the SAME wire `Args` bag `inputCoercionPlan` reads (the
+exported RemoteFunction's first call-signature parameter, `FormData` dropped by `argsBagType`), then
+builds an object schema, projecting each property through `jsonSchemaForType`. A File-typed property
+is EXCLUDED exactly as `filesSchema` keeps File parts out of the `inputSchema` projection — a File has
+no honest JSON-Schema form, so the multipart body advertises binaries generically instead. A property
+is required unless it is `?` optional or its type bears `undefined`. This is purely a SHAPE
+description: the surfaces consume it for docs, never for runtime validation, so it can't cause a 422.
+undefined when no call signature / single-object Args bag resolves or every property is excluded, so
+the caller stamps nothing and the surface falls open to an author-declared `schemas.input`.
+*/
+function inputArgsJsonSchema(
+    checker: ts.TypeChecker,
+    call: ts.CallExpression,
+): Record<string, unknown> | undefined {
+    const signature = checker.getTypeAtLocation(call).getCallSignatures()[0]
+    if (signature === undefined) {
+        return undefined
+    }
+    const parameter = signature.getParameters()[0]
+    if (parameter === undefined) {
+        return undefined
+    }
+    const argsType = argsBagType(checker.getTypeOfSymbolAtLocation(parameter, call))
+    if (argsType === undefined) {
+        return undefined
+    }
+    const properties: Record<string, unknown> = {}
+    const required: string[] = []
+    for (const property of argsType.getProperties()) {
+        const propertyType = checker.getTypeOfSymbolAtLocation(property, call)
+        if (isFileType(propertyType)) {
+            continue
+        }
+        // jsonSchemaForType collapses a bare permissive projection to undefined; restore `{}` so an
+        // unprojectable property still appears as an "any JSON" field of the object.
+        properties[property.getName()] = jsonSchemaForType(checker, propertyType) ?? {}
+        const optional =
+            (property.flags & ts.SymbolFlags.Optional) !== 0 || bearsOptionality(propertyType)
+        if (!optional) {
+            required.push(property.getName())
+        }
+    }
+    if (Object.keys(properties).length === 0) {
+        return undefined
+    }
+    const schema: Record<string, unknown> = { type: 'object', properties }
+    if (required.length > 0) {
+        schema.required = required
+    }
+    return schema
+}
+
+/* True when a type is (or, across a union, contains) `File`/`Blob` — the multipart binary members
+   excluded from the input-schema projection, mirroring how `filesSchema` stays out of `inputSchema`. */
+function isFileType(type: ts.Type): boolean {
+    if (type.isUnion()) {
+        return type.types.some((member) => isFileType(member))
+    }
+    const name = type.getSymbol()?.name
+    return name === 'File' || name === 'Blob'
+}
+
+/* True when a property's type bears `undefined`/`void` — an implicit optional even without the `?`
+   modifier (mirrors jsonSchemaForType's own `bearsUndefined` so the two projections agree). */
+function bearsOptionality(type: ts.Type): boolean {
+    if (type.isUnion()) {
+        return type.types.some((member) => (member.flags & OPTIONALITY_FLAGS) !== 0)
+    }
+    return (type.flags & OPTIONALITY_FLAGS) !== 0
+}
+
+/*
+The object `Args` constituent of a RemoteCallable parameter. Every rpc call signature types its
+first parameter `Args | FormData` (the multipart upload escape hatch), so the FormData and any
+nullish members are dropped and the lone remaining type returned. undefined when the arg is not
+a single object type — a no-input rpc (`Args = undefined`) or a FormData-only body — so no plan
+is produced.
+*/
+function argsBagType(parameterType: ts.Type): ts.Type | undefined {
+    if (!parameterType.isUnion()) {
+        return parameterType
+    }
+    const kept = parameterType.types.filter(
+        (member) => member.getSymbol()?.name !== 'FormData' && (member.flags & NULLISH_FLAGS) === 0,
+    )
+    return kept.length === 1 ? kept[0] : undefined
+}
+
+/*
+A field's wire codec kind, or undefined when it isn't codec-eligible. Unwraps `T | undefined` (an
+optional field) and a `T[]` (a repeated query key / JSON array whose ELEMENTS revive per item) to
+the target type, then classifies: a pure `number`/`boolean`/`bigint` by its type flag, a `Date`/
+`Set`/`Map` by its symbol identity through the checker. Anything else — a string, a `number |
+string` union, a plain object — → undefined, so it stays its JSON form and the schema decides. The
+symbol checks are top-level only: a `Set` NESTED in another value is not descended into (ADR-0029
+defers recursive descent).
+*/
+function wireKind(checker: ts.TypeChecker, type: ts.Type): WireKind | undefined {
+    const bare = unwrapOptional(type)
+    const target = arrayElement(checker, bare) ?? bare
+    if (isKind(target, NUMBER_FLAGS)) {
+        return 'number'
+    }
+    if (isKind(target, BOOLEAN_FLAGS)) {
+        return 'boolean'
+    }
+    if (isKind(target, BIGINT_FLAGS)) {
+        return 'bigint'
+    }
+    const symbolName = target.getSymbol()?.name
+    if (symbolName === 'Date') {
+        return 'date'
+    }
+    if (symbolName === 'Set' || symbolName === 'ReadonlySet') {
+        return 'set'
+    }
+    if (symbolName === 'Map' || symbolName === 'ReadonlyMap') {
+        return 'map'
+    }
+    return undefined
+}
+
+/* Drops the nullish members of a `T | undefined` optional; returns the lone survivor, else the
+   type unchanged (a genuine multi-member union stays as-is for isKind to reject). */
+function unwrapOptional(type: ts.Type): ts.Type {
+    if (!type.isUnion()) {
+        return type
+    }
+    const kept = type.types.filter((member) => (member.flags & NULLISH_FLAGS) === 0)
+    const [onlyKept] = kept
+    return kept.length === 1 && onlyKept !== undefined ? onlyKept : type
+}
+
+/* The element type of a `T[]`/`readonly T[]`, so a repeated query key (`?tag=1&tag=2`) coerces
+   per element; undefined for a non-array (tuples included — their element type is heterogeneous). */
+function arrayElement(checker: ts.TypeChecker, type: ts.Type): ts.Type | undefined {
+    const name = type.getSymbol()?.name
+    if (name === 'Array' || name === 'ReadonlyArray') {
+        return checker.getTypeArguments(type as ts.TypeReference)[0]
+    }
+    return undefined
+}
+
+/* True when every meaningful (non-nullish) member of the type matches `mask` — so `number`,
+   `number | undefined`, and a `1 | 2` literal union all read as number; a `number | string`
+   union does not. A bare `boolean` is a `true | false` union, handled by the recursion. */
+function isKind(type: ts.Type, mask: ts.TypeFlags): boolean {
+    if (type.isUnion()) {
+        const meaningful = type.types.filter((member) => (member.flags & NULLISH_FLAGS) === 0)
+        return meaningful.length > 0 && meaningful.every((member) => isKind(member, mask))
+    }
+    return (type.flags & mask) !== 0
+}