RFC-0029 · Reference catalog
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Generated reference catalog. This page renders structured Lean data for RFC-0029: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0029.This page is generated from the
lean/Gnomon/Spec/module for RFC-0029. Edit that source and regenerate this catalog.
Title: tRPC Schema Adapter
Status: draft
Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024, RFC-0025
Extended by: RFC-0034
Proof citations in source: 15 / 15. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
M29900 | Warning | tRPC procedure has an unanalyzable input validator; input typed as JSON |
M29901 | Error | tRPC router type not found at the specified import path |
M29902 | Warning | tRPC procedure output type cannot be mapped to an gnomon type; return typed as JSON |
M29903 | Error | tsconfig.json not found; TypeScript type resolution failed |
M29904 | Error | tRPC server is running a pre-v10 wire protocol; v10+ is required |
Dependency neighborhood
graph LR
nRFC_0029["RFC-0029"]
nRFC_0001["RFC-0001"]
nRFC_0029 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0029 --> nRFC_0006
nRFC_0008["RFC-0008"]
nRFC_0029 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0029 --> nRFC_0024
nRFC_0025["RFC-0025"]
nRFC_0029 --> nRFC_0025
nRFC_0034["RFC-0034"]
nRFC_0034 --> nRFC_0029
Invariants
- Each tRPC procedure (query, mutation, subscription) MUST become exactly one gnomon operation. (enforced by: build-time)
- If batch support is implemented, batch tRPC requests MUST be limited to 10 procedures per request; larger batches MUST be split automatically by the implementation. (enforced by: runtime)
- Implementations MUST support the tRPC v10+ wire protocol; pre-v10 servers MUST be rejected at runtime with M29904. (enforced by: runtime)
- Nested router trees MUST be flattened into operation names by concatenating segment names in camelCase, with duplicates rejected via M29901. (enforced by: build-time)
- The TypeScript program created by the adapter MUST be configured with noEmit:true to avoid writing output files. (enforced by: build-time)
- The adapter MUST NOT import or execute any tRPC router code; it operates exclusively on TypeScript type information from ts.createProgram. (enforced by: build-time)
- The adapter MUST compute a SHA-256 specHash over the canonical extracted type graph, store it in gnomon.lock, and skip re-extraction when the hash matches. (enforced by: build-time)
- The adapter MUST locate tsconfig.json by searching upward from the declaring .gnm file; absence MUST emit M29903 and halt. (enforced by: build-time)
- The adapter MUST resolve AppRouter (or a #-fragment named export, or fall back to the first AnyRouter-assignable export); failure MUST emit M29901. (enforced by: build-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Adapter Function Signature
- MUST — If no fragment is given and AppRouter is not found, the adapter MUST fall back to the first exported type assignable to AnyRouter.
- MUST — If no router type is found by any strategy, the adapter MUST emit M29901. (proof citation:
rfc0029_b31_grounded; verification pending) - MUST — The adapter MUST look for an exported type named AppRouter in the resolved module.
- MAY — The specifier MAY include an explicit export name using a # fragment.
Build-Time Extraction
- MUST — On matching specHash the adapter MUST skip re-extraction and use the cached operation set. (proof citation:
rfc0029_b14_grounded; verification pending) - MUST_NOT — The adapter MUST NOT import or execute any tRPC router code; it operates exclusively on TypeScript type information.
- MUST — The adapter MUST compute specHash as SHA-256 of a canonical JSON of the extracted type graph and store it in gnomon.lock.
- MUST — The adapter MUST locate tsconfig.json by searching upward; if not found it MUST emit M29903 and halt. (proof citation:
rfc0029_b9_grounded; verification pending) - MUST — The adapter MUST traverse the AppRouter type graph depth-first using only type information (no JS evaluation).
- MUST — The ts.Program MUST be created with noEmit: true to avoid writing output files.
Error Code Mapping
- MAY — Authors MAY override default error class mappings on the parent client declaration.
- MUST — The adapter MUST map TRPCError codes to gnomon error classes and inject them into each generated operation’s errors {} block. (proof citation:
rfc0029_b37_grounded; verification pending)
Input Validator Introspection
- MUST — Arktype schemas MUST be detected via infer/inferIn brands and the inferred type MUST be mapped via §5.
- MUST — If the input schema cannot be resolved, the adapter MUST emit M29900 and MUST type the input as JSON; the operation MUST still be generated. (proof citation:
rfc0029_b25_grounded; verification pending) - MUST — Raw TypeScript input types MUST be extracted via the TS compiler API and mapped via §5.
- MUST — The adapter MUST attempt to extract the input schema statically for each supported validator case. (proof citation:
rfc0029_b27_grounded; verification pending) - MUST — Valibot schemas MUST be detected via the _types brand and mapped following the same structure as Zod.
- MUST — Zod schemas detected via _def and ZodType brand MUST be resolved to an gnomon input schema by recursive descent.
Nested Router Support
- MUST — Naming conflicts MUST be detected and MUST emit M29901 as a duplicate name. (proof citation:
rfc0029_b19_grounded; verification pending) - MUST — The adapter MUST flatten nested router trees into operation names by concatenating segment names in camelCase.
Output Type Mapping
- MUST — If the output type cannot be mapped, the adapter MUST emit M29902 and MUST use JSON as the return type. (proof citation:
rfc0029_b21_grounded; verification pending) - MUST — The procedure output type MUST be extracted from the inferred return type after stripping Promise<>. (proof citation:
rfc0029_b44_grounded; verification pending) - MUST — Union types MUST map to gnomon variant; simple optional unions (T|undefined or T|null) MUST map to optional fields. (proof citation:
rfc0029_b6_grounded; verification pending)
Procedure Type Mapping
- MUST — Each tRPC procedure MUST become one gnomon operation. (proof citation:
rfc0029_b29_grounded; verification pending) - MUST — The adapter MUST set OperationDefinition.mode to ‘unary’ for query/mutation and ‘streaming’ for subscription procedures. (proof citation:
rfc0029_b11_grounded; verification pending)
Wire Protocol Mapping
- MUST — Implementations MUST construct the procedure URL by joining baseUrl with the router path and procedure name.
- MUST — Implementations MUST support the tRPC v10+ wire protocol.
- SHOULD — Implementations SHOULD support tRPC batch requests with the documented batching envelope and a 10-procedure limit per batch.
- MUST — Mutation input MUST be sent as JSON body using the tRPC v10 envelope { “json”: } with Content-Type application/json.
- MUST — Query input MUST be JSON-encoded as the input URL search parameter, omitted if undefined. (proof citation:
rfc0029_b39_grounded; verification pending) - MUST — Query procedures MUST map to GET, mutations to POST, and subscriptions to GET (initial handshake).
- MUST — Runtime MUST extract error.json.code and map it via §7; missing/unrecognized codes MUST be treated as INTERNAL_SERVER_ERROR/transient.
- MUST — Runtime MUST extract result.data.json from success responses and map it to the declared returns type. (proof citation:
rfc0029_b46_grounded; verification pending) - MUST_NOT — tRPC v9 and earlier MUST NOT be used; pre-v10 servers MUST trigger M29904. (proof citation:
rfc0029_b16_grounded; verification pending)
Linked References
| Direction | Target |
|---|---|
| Depends on | RFC-0001 |
| Depends on | RFC-0006 |
| Depends on | RFC-0008 |
| Depends on | RFC-0024 |
| Depends on | RFC-0025 |
| Extended by | RFC-0034 |