RFC-0031 · Design Q&A
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.
Q: How does an introspected object-returning field become an executable operation?
Status: Open
Source: RFC-0031 §§7–8; RFC-0027 §§2, 4
Issue: Each root field becomes an operation, but the GraphQL binding requires a selection: set. Object, interface, and union returns need nested field selections; the adapter does not define which fields to select, how deep to recurse, or how callers specify a selection. Generated operations can therefore lack valid GraphQL documents.
Recommendation: Require an authored selection template or generate a documented bounded selection with explicit caller override, and verify that the generated returns shape matches it.
Q: Does the introspection hash include every fact that changes generated operations?
Status: Open
Source: RFC-0031 §§3, 7, 9–10
Issue: The hash keeps only data.__schema.types, excluding queryType, mutationType, and subscriptionType root names. A schema can change which existing type is a root while keeping the types array unchanged, changing generated operations without changing the lock hash.
Recommendation: Hash a canonical complete schema representation including root names, directives and any other adapter-consumed fields, then test root changes and list nesting.
Q: Should missing build credentials trigger an unauthenticated introspection request?
Status: Open
Source: RFC-0031 §4; §11 M31100
Issue: When a declared auth: scheme has no matching build credential, the adapter sends the request without auth and may report a generic network/HTTP failure. It cannot distinguish missing local configuration from an endpoint outage, and the policy may expose an endpoint to unintended unauthenticated requests.
Recommendation: Fail before dispatch with a dedicated missing-build-credential diagnostic unless auth: none was explicitly chosen.
Q: How does the adapter build offline from its lockfile entry?
Status: Open
Source: RFC-0031 §§9–10; RFC-0024 §6.3 Issue: The lockfile sample stores a schema hash and operation count, but no introspection response, SDL snapshot, or generated operation/type data. It promises cached operation reuse without network access even though those values cannot be reconstructed from the entry. Recommendation: Pin the full verified adapter result or schema snapshot in the canonical lockfile or a content-addressed artifact, with explicit offline and refresh behavior.