gnomonlearn
Docs/RFC-0033/Design Q&A

RFC-0033 · 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: What authentication scheme applies when auth is omitted?

Status: Open

Source: RFC-0033 §6.3; invariants 6 and 8 Issue: Omitting auth defaults to required: true, but no default schemes list is defined. A caller must authenticate, yet the runtime has no accepted scheme. The grammar also permits required: true with schemes [none]. Recommendation: Require at least one concrete scheme whenever authentication is required, define an explicit default only if it is safe across bindings, and reject required: true with none.

Q: Is a draft api externally reachable?

Status: Open

Source: RFC-0033 §§3, 6.1, 7–8 Issue: An api is defined as the external public surface, and only listed operations are externally reachable. The example calls draft api BenefitsAdminAPI “not exposed to external callers” even though it has an exposes block. The runtime and publish treatment of draft APIs is unspecified. Recommendation: Define whether draft APIs are excluded from published bindings, restricted to a named audience, or reachable with draft status. Align the example and generated routing rules with that choice.

Q: Can errors.common name imported qualified types?

Status: Open

Source: RFC-0033 §5 grammar, §6.4, §7 example Issue: The grammar accepts only IDENT entries, while the example uses gnomon.errors.NotFound and other qualified names. The compiler needs an unambiguous import-resolution rule for common error types. Recommendation: Use a qualified type-reference grammar shared with other Gnomon declarations and validate each reference before stub generation.

Q: Is query-parameter API-key authentication permitted for a public API?

Status: Open

Source: RFC-0033 §6.3; RFC-0034 bindings Issue: The api-key scheme permits ?apiKey=<key> alongside a header. URLs are commonly copied into logs and traces, and the RFC does not define how a server binding controls or disables this form. Recommendation: Make the header form canonical and disallow query-parameter credentials unless a separate explicit compatibility policy specifies redaction and transport constraints.