RFC-0031 GraphQL adapter proposal
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.
This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.
Evidence
RFC-0031 §10 says introspection runs once per build, but also says a matching gnomon.lock hash prevents re-querying. A remote schema hash cannot be computed without querying the endpoint. RFC-0024 §6.3 has the same sequencing problem. The documented lockfile entry records a hash, source, timestamp, and operation count, but no complete input/output schemas or artifact locator; it cannot by itself support the promised offline compilation.
RFC-0031 §9 hashes only data.__schema.types for live introspection. It excludes queryType, mutationType, and subscriptionType names, though §7 uses those names to choose generated operations. A root change among existing types can therefore change the operation set without changing the hash. The normalization also needs a specified object-key canonicalization and adapter-version component so independent builders calculate the same identity.
The domain projection treats the four build-time auth: choices as Capability nodes, though §4 defines them as credential lookup modes. It treats M31100–M31104 diagnostic codes as NamedDeclaration, though §11 defines codes, not source declarations. These categories need explicit ontology identities. The previously recorded type/Stream ownership mismatch remains in STREAM_CONTRACT_PROPOSAL.md.
Recommended first-release contract
- Treat the checked-in lockfile and a pinned, content-addressed adapter snapshot as the default compile input. The snapshot contains the complete generated type and operation definitions, plus the selected root names. Define this cross-stage snapshot as a protobuf message and record its digest, format version, adapter version, and source in
gnomon.lock. --refresh-specsperforms a live introspection query, validates and canonicalizes the full schema needed for generation (including root names), writes a new snapshot and lock entry atomically, and reports semantic operation/type changes. With no pinned snapshot, a first build may fetch, but it must materialize a snapshot before succeeding.- Offline builds consume the pinned snapshot and verify its digest. A missing or corrupt snapshot is an error. The build must not silently substitute an old operation set after a refresh failure.
- Model introspection auth choices as adapter-scoped values and diagnostic codes as diagnostic identities, not capabilities or declarations.
Acceptance
- A clean offline build from committed lock and snapshot reproduces the same operation/type surface.
- Changing only the selected GraphQL root names changes the schema identity and generated operations.
- A refresh with reordered introspection arrays but identical semantics yields the same digest; changing field types or root names yields a new digest.
- Snapshot corruption, missing schema fields, missing credentials, and unreachable endpoints have distinct tested outcomes.
- RFC-0024 and RFC-0031 narrative, Lean, lockfile schema, source-domain RDF, generated references, and site pin agree. Framework KG consumers and claim queries are compared before RDF IRI changes.
Nothing is deployed, so no persisted-client migration is required for the first release.