RFC-0031 · 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-0031: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in
RFC-0031.This page is generated from the
lean/Gnomon/Spec/module for RFC-0031. Edit that source and regenerate this catalog.
Title: GraphQL Introspection Adapter
Status: draft
Diagnostic range: M31100-M31199
Depends on: RFC-0001, RFC-0006, RFC-0008, RFC-0024, RFC-0025, RFC-0027
Proof citations in source: 12 / 12. Standalone proof verification is pending.
Definitions
(none defined)
Diagnostics
| Code | Severity | Description |
|---|---|---|
M31100 | Error | GraphQL introspection request failed (network error, non-200 response, or malformed JSON) |
M31101 | Error | GraphQL SDL file not found at declared path |
M31102 | Warning | GraphQL type cannot be mapped to an gnomon type; field falls back to JSON (custom scalars, unresolvable interfaces) |
M31103 | Error | Introspection response is missing required fields, or query root type is absent |
M31104 | Error | SDL parse error; file contains invalid GraphQL syntax |
Dependency neighborhood
graph LR
nRFC_0031["RFC-0031"]
nRFC_0001["RFC-0001"]
nRFC_0031 --> nRFC_0001
nRFC_0006["RFC-0006"]
nRFC_0031 --> nRFC_0006
nRFC_0008["RFC-0008"]
nRFC_0031 --> nRFC_0008
nRFC_0024["RFC-0024"]
nRFC_0031 --> nRFC_0024
nRFC_0025["RFC-0025"]
nRFC_0031 --> nRFC_0025
nRFC_0027["RFC-0027"]
nRFC_0031 --> nRFC_0027
Invariants
- A schema with no Query root type is invalid and causes the adapter to emit M31103. (enforced by: compile-time)
- For graphqlIntrospect the specHash is SHA-256 of the canonicalized data.__schema.types array (typename-stripped, sorted, compact JSON); for graphqlSchema it is SHA-256 of the raw file contents. (enforced by: compile-time)
- Generated operation names are the GraphQL field name preserved as-is, with no transformation by the adapter. (enforced by: compile-time)
- GraphQL built-in types whose names begin with __ are excluded from type registration by the adapter. (enforced by: compile-time)
- The adapter gnomon.lock lockfile MUST be committed to version control and reused when specHash matches the current spec. (enforced by: compile-time)
- The adapter gnomon.lock lockfile MUST be committed to version control and reused when specHash matches the current spec. (enforced by: process)
- The gnomon.lock entry produced by the adapter must be committed to version control so CI builds without network access can compile from cache. (enforced by: compile-time)
- The gnomon.lock entry produced by the adapter must be committed to version control so CI builds without network access can compile from cache. (enforced by: process)
- The introspection response MUST contain name, kind, fields, inputFields, enumValues, possibleTypes, and ofType, otherwise the adapter emits M31103. (enforced by: compile-time)
- The path passed to graphqlSchema MUST have a .graphql or .gql extension; other extensions emit M31101. (enforced by: compile-time)
- The url passed to graphqlIntrospect MUST be an absolute HTTP or HTTPS URL; relative URLs emit M31100. (enforced by: compile-time)
Normative Statements
Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.
Adapter Function Signatures
- MUST — graphqlIntrospect url MUST be an absolute HTTP or HTTPS URL; relative URLs emit M31100. (proof citation:
rfc0031_b1_grounded; verification pending) - MUST — graphqlSchema file MUST have a .graphql or .gql extension; other extensions emit M31101. (proof citation:
rfc0031_b24_grounded; verification pending)
Argument Mapping
- MUST — Argument ordering MUST be preserved from the schema declaration. (proof citation:
rfc0031_b11_grounded; verification pending) - MUST — Required (T!) arguments MUST become required input fields; optional arguments MUST become optional fields preserving any default value in the description. (proof citation:
rfc0031_b29_grounded; verification pending)
Auth for Introspection
- MUST — Adapter MUST resolve introspection credentials from build-environment variables, not the runtime credential store.
Caching and Refresh
- MUST — If the endpoint is unreachable and no lockfile entry exists, the compiler MUST emit M24420; with a lockfile entry it MUST use the cache and emit M24421. (proof citation:
rfc0031_b20_grounded; verification pending) - MUST — The lockfile MUST be committed to version control.
Introspection Query
- MUST — Adapter MUST send the standard introspection query as HTTP POST with Content-Type application/json.
- MUST_NOT — Built-in types (names beginning with __) MUST NOT be registered.
- MUST — If any required introspection field is absent, the adapter MUST emit M31103. (proof citation:
rfc0031_b16_grounded; verification pending)
Lockfile
- MUST — For graphqlIntrospect, specHash MUST be the SHA-256 of the canonical normalized introspection JSON.
- MUST — For graphqlSchema, specHash MUST be the SHA-256 of the raw file contents.
Root Type to Operation Mapping
- MUST — Each root type field MUST become exactly one gnomon operation, with the field name preserved. (proof citation:
rfc0031_b6_grounded; verification pending) - MUST — If the query root type is absent, the adapter MUST emit M31103. (proof citation:
rfc0031_b13_grounded; verification pending)
SDL File Parsing
- MUST — Executable document syntax in SDL files MUST emit M31104. (proof citation:
rfc0031_b4_grounded; verification pending) - MUST — Syntax errors in SDL MUST produce M31104 with line and column from the parser. (proof citation:
rfc0031_b9_grounded; verification pending) - MUST — When no schema declaration is present, adapter MUST default root type names to Query, Mutation, and Subscription.
Type Mapping
- MUST — Custom scalars MUST map to JSON and emit M31102. (proof citation:
rfc0031_b27_grounded; verification pending) - MUST — Every GraphQL type MUST be mapped to an gnomon Value type or TypeDefinition per the table. (proof citation:
rfc0031_b18_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 |
| Depends on | RFC-0027 |