gnomonlearn
Docs/RFC-0027/Design Q&A

RFC-0027 · 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.

← Read the authored RFC

Q: How are GraphQL variable definitions generated in the operation document?

Status: Open

Source: RFC-0027 §§2, 4.3–4.4 Issue: The wire document is assembled as <operationType> <operationName> { <selection> }, but the examples reference $owner, $name, and other variables without the required operation variable definitions. Mapping Gnomon Text to GraphQL String also cannot infer schema-specific ID, enum, custom input-object, or non-null types. Recommendation: Require explicit GraphQL variable type declarations for hand-authored operations, or validate against an imported schema and generate a complete document with $name: Type! definitions. The compiler should reject unresolved variables and type mismatches.

Q: What part of a GraphQL data object binds to returns:?

Status: Open

Source: RFC-0027 §§2.2, 5.1 Issue: The example declares returns: Repository, while a successful response has data.repository as the repository and data itself is a wrapper object. The RFC says to deserialize all of data against returns without defining root-field extraction or alias handling. Recommendation: Require a declared result path or make returns describe the whole data shape. Validate it against the selection set at compile time when schema information is available.

Q: Can a partial GraphQL result satisfy a required return field?

Status: Open

Source: RFC-0027 §5.3; RFC-0024 §3 Issue: A partial result fills fields missing due to errors with zero values and treats the operation as successful, even if those fields are required or have no valid neutral value. The caller receives a value that may violate returns and can inspect only implementation-defined diagnostics. Recommendation: Make partial results an explicit result variant with structured errors, or fail when a required field is absent. Define wildcard selector behavior without manufacturing invalid values.

Q: Is a GraphQL subscription an RFC-0020 event-log subscription?

Status: Open

Source: RFC-0027 §3.3; RFC-0020 §§3–8 Issue: The RFC assigns RFC-0020’s subscription lifecycle to an arbitrary GraphQL stream, but RFC-0020’s guarantees depend on Gnomon event IDs, event-log replay, query filtering, and read-scope checks. The GraphQL transport and resume behavior are implementation-defined. Recommendation: Define a transport stream contract with cancellation, errors, and flow control; share lifecycle methods only where semantics match, and require a separate bridge before claiming RFC-0020 delivery guarantees.